From 826062aa173829ce8dd22e86af26af19085b0a72 Mon Sep 17 00:00:00 2001
From: Eric Rakestraw <eric@rakestraw.us>
Date: Sun, 25 Oct 2026 22:09:55 +0000
Subject: [PATCH] Test public historical path enumeration

---
 docs/roadmap/implementation.md  |  9 +++++
 facade_historical_paths_test.go | 62 +++++++++++++++++++++++++++++++++
 facade_internal_test.go         | 17 ---------
 3 files changed, 71 insertions(+), 17 deletions(-)
 create mode 100644 facade_historical_paths_test.go

diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md
index c257946..cd264c1 100644
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -487,6 +487,15 @@ Focused check: `go test ./internal/engine -run 'Dynamic|Projection|Clone|Resolut
 Findings: **F09**, replacement path coverage for **F12**, prerequisites for **F04**.
 Owners: root external-package facade tests and existing source-snapshot tests.
 
+Status: **complete** (F09; replacement path coverage for F12; public snapshot
+ownership review for F04). Prior completed commits: `2736ddf`, `deb9aa5`,
+`ae3408a`, `ea27f17`, `08a8c25`, `877c497`, `8aba43d`, `7bf2f0c`,
+`0f9ecf1`, `119b42c`, `247a12b`, `4fcff5f`, `12d350a`, `08f2a8f`.
+Validation passed: `env GOTOOLCHAIN=local GOPROXY=off GOTELEMETRY=off go test . -run 'Historical|Metadata|Facade|Source|WrappedPaths' -count=1`
+and `git diff --check`. Existing public source-version and import-selection
+snapshot tests cover repeated-query detachment of location/version pointers and
+nested selections; no duplicate ownership matrix was added.
+
 Add compact public tests using only root APIs. Cover effective and removed
 historical paths, sorted unique pointer spelling, zero metadata, escaped keys,
 and a numeric-key/sequence shape change. Feed returned paths into `Lookup` and
diff --git a/facade_historical_paths_test.go b/facade_historical_paths_test.go
new file mode 100644
index 0000000..b149c49
--- /dev/null
+++ b/facade_historical_paths_test.go
@@ -0,0 +1,62 @@
+package configkit_test
+
+import (
+	"reflect"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func TestPublicHistoricalPathsEnumerateContextualShapes(t *testing.T) {
+	loaded, err := configkit.Load[map[string]any](configkit.Bytes("main", []byte(
+		"retired: {child: 1}\nshape: {'0': base}\n'a/b~': {'': 2}\n",
+	)), configkit.Options[map[string]any]{Overrides: []configkit.Override{
+		{Path: configkit.Keys("retired"), Value: nil, Flag: "--retired"},
+		{Path: configkit.Keys("shape"), Value: []any{"replacement"}, Flag: "--shape"},
+	}})
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+
+	metadata := loaded.Metadata()
+	paths := metadata.HistoricalPaths()
+	got := make([]string, len(paths))
+	for index, path := range paths {
+		got[index] = path.String()
+		if len(metadata.History(path)) == 0 {
+			t.Errorf("enumerated path %s has no history", path)
+		}
+	}
+	want := []string{"", "/a~1b~0", "/a~1b~0/", "/retired", "/retired/child", "/shape", "/shape/0"}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("historical paths = %v, want sorted unique pointers %v", got, want)
+	}
+	if _, ok := metadata.Lookup(paths[4]); ok {
+		t.Fatal("removed descendant remains effective")
+	}
+	if _, ok := metadata.Lookup(paths[6]); !ok {
+		t.Fatal("enumerated numeric path did not follow the effective sequence shape")
+	}
+	if len(metadata.History(paths[6])) == 0 {
+		t.Fatal("enumerated numeric path lost history")
+	}
+	if _, ok := metadata.Lookup(configkit.Keys("shape", "0")); ok {
+		t.Fatal("mapping-key path resolved against the effective sequence")
+	}
+	if len((configkit.Metadata{}).HistoricalPaths()) != 0 {
+		t.Fatal("zero metadata contains historical paths")
+	}
+
+	paths[1] = configkit.Keys("mutated")
+	if again := metadata.HistoricalPaths(); !reflect.DeepEqual(pathStrings(again), want) {
+		t.Fatalf("returned path slice mutated retained metadata: %v", pathStrings(again))
+	}
+}
+
+func pathStrings(paths []configkit.Path) []string {
+	result := make([]string, len(paths))
+	for index, path := range paths {
+		result[index] = path.String()
+	}
+	return result
+}
diff --git a/facade_internal_test.go b/facade_internal_test.go
index d60fac9..aaf3a6f 100644
--- a/facade_internal_test.go
+++ b/facade_internal_test.go
@@ -2,7 +2,6 @@ package configkit
 
 import (
 	"errors"
-	"reflect"
 	"strings"
 	"testing"
 
@@ -34,19 +33,3 @@ func TestWrappedSourcesPreserveEngineOwnership(t *testing.T) {
 		t.Fatalf("copied reader source error = %#v", err)
 	}
 }
-
-func TestWrappedPathsRetainEngineSegmentIntent(t *testing.T) {
-	t.Parallel()
-
-	parsed, err := ParsePath("/0")
-	if err != nil {
-		t.Fatal(err)
-	}
-	keyed, indexed := Keys("0"), Path{}.Index(0)
-	if parsed.String() != "/0" || keyed.String() != "/0" || indexed.String() != "/0" {
-		t.Fatalf("path spellings = %q, %q, %q", parsed, keyed, indexed)
-	}
-	if reflect.DeepEqual(parsed.value, keyed.value) || reflect.DeepEqual(parsed.value, indexed.value) || reflect.DeepEqual(keyed.value, indexed.value) {
-		t.Fatal("path wrappers collapsed parsed, mapping-key, and index segments")
-	}
-}