From 1619b06541ac6da630529c1d80c513ae424f8078 Mon Sep 17 00:00:00 2001
From: Ophestra <cat@gensokyo.uk>
Date: Thu, 19 Feb 2026 15:06:10 +0900
Subject: [PATCH] internal/pkg: export layer promotion

This is a useful helper for external tooling.

Signed-off-by: Ophestra <cat@gensokyo.uk>
---
 internal/pkg/exec.go | 41 ++++++++++++++++++++++++++---------------
 1 file changed, 26 insertions(+), 15 deletions(-)

diff --git a/internal/pkg/exec.go b/internal/pkg/exec.go
index 7b1d7f3..92b14ab 100644
--- a/internal/pkg/exec.go
+++ b/internal/pkg/exec.go
@@ -39,22 +39,20 @@ type ExecPath struct {
 	W bool
 }
 
-// layers returns pathnames collected from A deduplicated by checksum.
-func (p *ExecPath) layers(f *FContext) []*check.Absolute {
-	msg := f.GetMessage()
-
-	layers := make([]*check.Absolute, 0, len(p.A))
-	checksums := make(map[unique.Handle[Checksum]]struct{}, len(p.A))
-	for i := range p.A {
-		d := p.A[len(p.A)-1-i]
-		pathname, checksum := f.GetArtifact(d)
+// PromoteLayers returns artifacts with identical-by-content layers promoted to
+// the highest priority instance, as if mounted via [ExecPath].
+func PromoteLayers(
+	artifacts []Artifact,
+	getArtifact func(Artifact) (*check.Absolute, unique.Handle[Checksum]),
+	report func(i int, d Artifact),
+) []*check.Absolute {
+	layers := make([]*check.Absolute, 0, len(artifacts))
+	checksums := make(map[unique.Handle[Checksum]]struct{}, len(artifacts))
+	for i := range artifacts {
+		d := artifacts[len(artifacts)-1-i]
+		pathname, checksum := getArtifact(d)
 		if _, ok := checksums[checksum]; ok {
-			if msg.IsVerbose() {
-				msg.Verbosef(
-					"promoted layer %d as %s",
-					len(p.A)-1-i, reportName(d, f.cache.Ident(d)),
-				)
-			}
+			report(len(artifacts)-1-i, d)
 			continue
 		}
 		checksums[checksum] = struct{}{}
@@ -64,6 +62,19 @@ func (p *ExecPath) layers(f *FContext) []*check.Absolute {
 	return layers
 }
 
+// layers returns pathnames collected from A deduplicated via [PromoteLayers].
+func (p *ExecPath) layers(f *FContext) []*check.Absolute {
+	msg := f.GetMessage()
+	return PromoteLayers(p.A, f.GetArtifact, func(i int, d Artifact) {
+		if msg.IsVerbose() {
+			msg.Verbosef(
+				"promoted layer %d as %s",
+				i, reportName(d, f.cache.Ident(d)),
+			)
+		}
+	})
+}
+
 // Path returns a populated [ExecPath].
 func Path(pathname *check.Absolute, writable bool, a ...Artifact) ExecPath {
 	return ExecPath{pathname, a, writable}