Document the ConfigKit v0.8.0 release

README.md

@@ -20,7 +20,18 @@ secrets-directory bootstrap is available as a separate startup operation. Explic
 CLI override records apply above overlays. Value explanation is available through
 detached structured records and deterministic redacted output. Built-in
 `extends` relationships let a mapping inherit from a named sibling during the
-same load, retaining explicit presence and source/derivation history.
+same load, retaining explicit presence and source/derivation history. The root
+`Diff` API compares frozen effective values from two successful same-type loads;
+the [configuration contract](docs/config.md#effective-configuration-diffs) and
+[consumer guide](docs/consumers/README.md#effective-configuration-diffs) describe
+its safe changed-region records and maintained workflows.
+
+Sources can also be explicitly placed as sequence items, and definitions can
+register selected sequences to append records with distinct string IDs during
+strict composition. Higher-priority sequences still replace lower-priority
+sequences as whole values. See the [sequence contract](docs/config.md#strict-document-composition),
+[maintained prompt example](docs/consumers/README.md#identified-prompt-sequences),
+and [ADR 0014](docs/adr/0014-sequence-placement-and-composition.md).
 
 ```go
 type Config struct {
@@ -58,18 +69,26 @@ children; other values replace lower-priority values. The main document and its
 imports form one strictly composed tier. Explicit underlay groups sit below it
 and above typed defaults; a selected overlay and explicit CLI overrides sit
 above it. The [configuration contract](docs/config.md#strict-document-composition)
-owns the detailed combination rules and input-specific constraints.
+owns the detailed combination rules and input-specific constraints. At
+definition-registered paths only, strict composition can append records with
+distinct explicit IDs; ordinary and unregistered sequences keep their conflict
+or whole-value replacement behavior.
 
 The [architecture goals](docs/policy/architecture.md#success-criteria) explain
 these priorities and how genuine new needs can justify extending the shared
-model. The [deferred scope](docs/roadmap/deferred.md) records deliberate exclusions.
+model. The [future feature list](docs/roadmap/future.md) preserves candidates for
+consideration in future releases.
 
-The [configuration contract](docs/config.md) describes implemented behavior. The
+The [configuration contract](docs/config.md) describes implemented behavior,
-[consumer adoption guide](docs/consumers/README.md) provides maintained simple
+including [input destinations](docs/config.md#input-destinations). The
-native-filesystem, layered, and sibling-inheritance examples alongside the migration shapes.
+[consumer adoption guide](docs/consumers/README.md) provides maintained simple,
-See the [development guide](docs/development.md) for repository orientation and the
+layered, mounted-collection, and identified-prompt examples alongside the
-[release procedure](docs/release.md) for maintainer-only candidate and publication
+migration shapes. Input placement decisions are recorded in
-steps.
+[ADR 0011](docs/adr/0011-input-destinations.md) and sequence placement and
+composition in [ADR 0014](docs/adr/0014-sequence-placement-and-composition.md).
+See the [development guide](docs/development.md) for repository orientation and
+the [release procedure](docs/release.md) for maintainer-only candidate and
+publication steps.
 
 ConfigKit code is licensed under the [LGPL v3.0 or later](COPYRIGHT).
 

conversion.go

@@ -43,10 +43,31 @@ func toEngineLocations(values []Location) []engine.Location {
 	return result
 }
 func fromEngineSourceInfo(value engine.SourceInfo) SourceInfo {
-	return SourceInfo{ID: value.ID, Label: value.Label, Path: value.Path, Layer: Layer(value.Layer), Kind: SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, ImportedFrom: fromEngineLocationPointer(value.ImportedFrom)}
+	return SourceInfo{ID: value.ID, Label: value.Label, Path: value.Path, Destination: fromEnginePath(value.Destination), PlacementMode: PlacementMode(engine.SourceInfoPlacementModeForFacade(value)), DestinationUnresolved: engine.SourceInfoDestinationUnresolvedForFacade(value), Layer: Layer(value.Layer), Kind: SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, ImportedFrom: fromEngineLocationPointer(value.ImportedFrom), VersionCheck: fromEngineSourceVersionCheck(value.VersionCheck)}
 }
 func toEngineSourceInfo(value SourceInfo) engine.SourceInfo {
-	return engine.SourceInfo{ID: value.ID, Label: value.Label, Path: value.Path, Layer: engine.Layer(value.Layer), Kind: engine.SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, ImportedFrom: toEngineLocationPointer(value.ImportedFrom)}
+	result := engine.SourceInfo{ID: value.ID, Label: value.Label, Path: value.Path, Destination: toEnginePath(value.Destination), Layer: engine.Layer(value.Layer), Kind: engine.SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, ImportedFrom: toEngineLocationPointer(value.ImportedFrom), VersionCheck: toEngineSourceVersionCheck(value.VersionCheck)}
+	return engine.SourceInfoWithPlacement(result, uint8(value.PlacementMode), value.DestinationUnresolved)
+}
+func fromEngineSourceVersionCheck(value *engine.SourceVersionCheck) *SourceVersionCheck {
+	if value == nil {
+		return nil
+	}
+	return &SourceVersionCheck{
+		Path:     fromEnginePath(value.Path),
+		Version:  Version{Present: value.Version.Present, Null: value.Version.Null, Text: value.Version.Text},
+		Location: fromEngineLocationPointer(value.Location), Redacted: value.Redacted,
+	}
+}
+func toEngineSourceVersionCheck(value *SourceVersionCheck) *engine.SourceVersionCheck {
+	if value == nil {
+		return nil
+	}
+	return &engine.SourceVersionCheck{
+		Path:     toEnginePath(value.Path),
+		Version:  engine.Version{Present: value.Version.Present, Null: value.Version.Null, Text: value.Version.Text},
+		Location: toEngineLocationPointer(value.Location), Redacted: value.Redacted,
+	}
 }
 func fromEngineOrigin(value engine.Origin) Origin {
 	result := Origin{Layer: Layer(value.Layer), Locations: fromEngineLocations(value.Locations), Operation: ChangeKind(value.Operation)}

development_check_test.go

@@ -66,7 +66,7 @@ func TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure(t *testing.T) {
 						t.Fatal(err)
 					}
 					cmd := exec.Command("/bin/bash", filepath.Join(root, "scripts", scriptName))
-					cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "CONFIGKIT_BASELINE_TOOLCHAIN=test-baseline", "CONFIGKIT_NEWER_TOOLCHAIN=", "CONFIGKIT_TEST_FMT_LOG="+log, "CONFIGKIT_TEST_GO_LOG="+calls)
+					cmd.Env = append(os.Environ(), "PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"), "CONFIGKIT_TEST_FMT_LOG="+log, "CONFIGKIT_TEST_GO_LOG="+calls)
 					// Log only targets selected by the script, not inherited host settings.
 					cmd.Env = append(cmd.Env, "GOOS=", "GOARCH=")
 					if name == "failed-go-check" {
@@ -108,90 +108,3 @@ func TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure(t *testing.T) {
 		})
 	}
 }
-
-func TestCheckScriptsReleaseGates(t *testing.T) {
-	script, err := os.ReadFile("scripts/release-check.sh")
-	if err != nil {
-		t.Fatal(err)
-	}
-	for _, scenario := range []string{"success", "failed-test", "missing-toolchain"} {
-		t.Run(scenario, func(t *testing.T) {
-			root := t.TempDir()
-			bin := t.TempDir()
-			for _, directory := range []string{"scripts", "nested"} {
-				if err := os.Mkdir(filepath.Join(root, directory), 0700); err != nil {
-					t.Fatal(err)
-				}
-			}
-			checker := filepath.Join(root, "scripts", "release-check.sh")
-			if err := os.WriteFile(checker, script, 0700); err != nil {
-				t.Fatal(err)
-			}
-			calls := filepath.Join(bin, "go.calls")
-			goStub := `#!/bin/sh
-printf '%s|%s|%s|%s|%s|%s\n' "$GOTOOLCHAIN" "$GOPROXY" "${CGO_ENABLED-}" "${GOOS-}" "${GOARCH-}" "$*" >> "$CONFIGKIT_TEST_GO_LOG"
-if [ "${CONFIGKIT_TEST_FAIL-}" = toolchain ] && [ "${1-}" = version ]; then exit 37; fi
-if [ "${CONFIGKIT_TEST_FAIL-}" = test ] && [ "${1-}" = test ]; then exit 37; fi
-`
-			if err := os.WriteFile(filepath.Join(bin, "go"), []byte(goStub), 0700); err != nil {
-				t.Fatal(err)
-			}
-			cmd := exec.Command("/bin/bash", checker)
-			cmd.Dir = filepath.Join(root, "nested")
-			cmd.Env = append(os.Environ(),
-				"PATH="+bin+string(os.PathListSeparator)+os.Getenv("PATH"),
-				"CONFIGKIT_BASELINE_TOOLCHAIN=test-baseline",
-				"CONFIGKIT_TEST_GO_LOG="+calls,
-				"GOOS=", "GOARCH=", "CGO_ENABLED=",
-			)
-			switch scenario {
-			case "failed-test":
-				cmd.Env = append(cmd.Env, "CONFIGKIT_TEST_FAIL=test")
-			case "missing-toolchain":
-				cmd.Env = append(cmd.Env, "CONFIGKIT_TEST_FAIL=toolchain")
-			}
-			output, err := cmd.CombinedOutput()
-			if scenario == "success" && err != nil {
-				t.Fatalf("checker: %v\n%s", err, output)
-			}
-			if scenario != "success" && err == nil {
-				t.Fatalf("checker accepted %s", scenario)
-			}
-			data, err := os.ReadFile(calls)
-			if err != nil {
-				t.Fatal(err)
-			}
-			lines := strings.Split(strings.TrimSpace(string(data)), "\n")
-			for _, line := range lines {
-				if !strings.HasPrefix(line, "test-baseline|off|") {
-					t.Fatalf("toolchain or offline setting lost: %q", line)
-				}
-			}
-			if scenario == "missing-toolchain" {
-				if len(lines) != 1 || !strings.HasSuffix(lines[0], "|version") {
-					t.Fatalf("checker ran after unavailable toolchain: %q", lines)
-				}
-				return
-			}
-			if len(lines) < 2 || lines[1] != "test-baseline|off||||test -mod=readonly -vet=off -race -v ./..." {
-				t.Fatalf("release suite command changed: %q", lines)
-			}
-			if scenario == "failed-test" {
-				if len(lines) != 2 {
-					t.Fatalf("checker continued after failure: %q", lines)
-				}
-				return
-			}
-			want := []string{
-				"test-baseline|off||||version",
-				"test-baseline|off||||test -mod=readonly -vet=off -race -v ./...",
-				"test-baseline|off||||vet -mod=readonly ./...",
-				"test-baseline|off|0|linux|amd64|build -mod=readonly ./...",
-				"test-baseline|off|0|linux|arm64|build -mod=readonly ./...",
-			}
-			if strings.Join(lines, "\n") != strings.Join(want, "\n") {
-				t.Fatalf("unexpected release gates:\n%s", data)
-			}
-		})
-	}
-}

diff.go

@@ -0,0 +1,53 @@
+package configkit
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
+
+// Difference describes one canonical changed region between two successful
+// loads. Left is the earlier value and Right is the later value. Each snapshot
+// is detached; Present distinguishes absence from an explicit null, and
+// Redacted reports whether combined sensitivity affected that side. Mappings
+// are compared recursively, while sequences are reported as atomic values.
+// Records are ordered by canonical JSON pointer. HiddenChanged indicates that
+// a value concealed by combined sensitivity changed, without revealing which
+// concealed member changed.
+type Difference struct {
+	Path          Path
+	Left          ValueSnapshot
+	Right         ValueSnapshot
+	HiddenChanged bool
+}
+
+// Diff compares the frozen effective values of two successful loads of the
+// same configuration type. It does not reread sources, environment variables,
+// or rerun defaults or resolvers. Equal values produce no records even when
+// their sources, defaults, or resolution histories differ. Credential contents
+// are not compared: typed secret references compare by reference name only.
+//
+// Both results must be non-nil successful loads with inspection state; nil or
+// zero results return an error and no records. Load errors are returned by
+// Load, so callers must handle those before calling Diff. Snapshots are safe
+// for presentation but are not a complete reloadable configuration.
+func Diff[T any](left, right *Result[T]) ([]Difference, error) {
+	var leftInspection, rightInspection *engine.Inspection
+	if left != nil {
+		leftInspection = left.inspection
+	}
+	if right != nil {
+		rightInspection = right.inspection
+	}
+
+	values, err := engine.Diff(leftInspection, rightInspection)
+	if err != nil {
+		return nil, err
+	}
+	differences := make([]Difference, len(values))
+	for index, value := range values {
+		differences[index] = Difference{
+			Path:          fromEnginePath(value.Path),
+			Left:          fromEngineValueSnapshot(value.Left),
+			Right:         fromEngineValueSnapshot(value.Right),
+			HiddenChanged: value.HiddenChanged,
+		}
+	}
+	return differences, nil
+}

docs/adr/0010-effective-configuration-diff.md

@@ -0,0 +1,99 @@
+# ADR 0010: Compare Frozen Effective Configuration Snapshots
+
+## Status
+
+Accepted and implemented. The
+[configuration contract](../config.md#effective-configuration-diffs) owns current
+behavior. Completed planning and remediation records are preserved in Git
+history at `1c2610c` under `docs/roadmap/`.
+
+## Date
+
+2026-10-09
+
+## Context
+
+Applications need to inspect how two completed configurations differ, including
+the effective impact of an overlay after defaults and application resolution.
+ConfigKit already retains canonical typed inspection snapshots, semantic paths,
+presence information, and sensitivity classification for successful loads.
+
+Extending this inspection model lets applications share configuration comparison
+and safe disclosure while keeping their presentation and domain interpretation.
+The operation should follow ConfigKit's existing equality, ownership, and secret
+boundaries so consumers can reason about loading and inspection consistently.
+
+## Decision
+
+Provide structured effective-value comparison between successful results of the
+same configuration type. Compare their retained canonical inspection snapshots
+through the root-owned public facade. Each comparison uses the completed load
+state and returns detached records with a semantic path and safe left and right
+value snapshots.
+
+Use canonical value equality and the existing structural comparison rules.
+Mappings compare recursively, sequences report atomic changes, and scalar or
+kind replacements report the affected region. Presence distinguishes additions
+and removals from explicit null. Equal effective values produce an empty diff;
+source attribution, explicit-input status, and history remain separately
+inspectable through each result. Canonical pointer ordering makes reporting
+deterministic.
+
+Detect changes before masking values. Apply sensitivity from both loads to both
+returned sides, including historical and dependency-derived classification.
+Preserve public content where the shapes permit corresponding sensitive regions
+to be identified. When a structural replacement prevents safe correspondence,
+mask the complete reported replacement region on both present sides. Absence
+retains its own representation.
+
+Keep masking and hidden-change information distinct. Each record indicates
+whether an actual change is withheld by redaction, allowing applications to
+display a changed-sensitive-value indicator even when safe snapshots render
+identically. Public-only changes alongside unchanged masked content retain that
+distinction.
+
+Typed secret references participate through their configured environment names.
+Resolved credential bytes remain behind the existing explicit secret accessor.
+The comparison uses the same frozen inspection boundary as effective rendering
+and explanation.
+
+ConfigKit owns comparison and paired safe disclosure. Applications own labels,
+layout, and rendering of the returned changed regions. Reusing the existing
+snapshot representation and engine boundary keeps the extension consistent with
+the library's established inspection model.
+
+## Alternatives considered
+
+- **Compare input text or separately rendered YAML.** Supports familiar textual
+  displays, but input text precedes composition and resolution, and independently
+  redacted output can hide changes or apply different disclosure rules. Canonical
+  comparison with paired masking represents the completed configuration.
+- **Leave comparison to applications using returned Go values.** Offers direct
+  access to application types, but duplicates structural and redaction machinery
+  and observes caller mutation. Retained inspection snapshots preserve the
+  completed load's values and established ownership boundary.
+- **Align sequence elements and return context-rich rendering data.** Enables
+  finer-grained displays, but requires additional correspondence and disclosure
+  rules. Atomic sequence records and existing value snapshots satisfy the
+  selected changed-region workflows with a smaller public model.
+- **Compare resolved credentials or retain credential-derived tokens.** Could
+  detect rotation behind an unchanged reference, but expands retained sensitive
+  state and introduces a separate trusted comparison mechanism. Reference-name
+  comparison preserves the existing inspection boundary.
+
+## Consequences
+
+Applications can compare independently loaded configurations using ConfigKit's
+shared equality, presence, and disclosure rules. Existing composition and load
+semantics continue to determine the values being compared. Caller mutation of a
+returned configuration leaves its retained comparison snapshot unchanged.
+
+Paired redaction can conceal public content within a structurally incompatible
+replacement. The changed region and hidden-change indicator still communicate
+its effective impact. Credential rotation behind an unchanged environment name
+produces equal reference values for comparison.
+
+The implementation requires operation-local disclosure preparation and focused
+coverage for presence, shape changes, historical sensitivity, and detached
+results. Applications retain control of presentation; changed-region records
+supply the safe data needed for that responsibility.

docs/adr/0011-input-destinations.md

@@ -0,0 +1,74 @@
+# ADR 0011: Place Configuration Inputs at Mapping Destinations
+
+## Status
+
+Accepted and implemented. Current placement behavior is owned by the
+[configuration contract](../config.md#input-destinations). The accepted
+relative-import extension is recorded in
+[ADR 0012](0012-relative-import-destinations.md). The completed roadmap, consumer
+request, and review records are preserved at `e4270c9` under `docs/roadmap/` in
+Git history; the original input-destination implementation plan remains at
+`315f464:docs/roadmap/implementation.md`.
+
+## Date
+
+2026-10-14
+
+## Context
+
+Consumers assembling collections of independently authored configuration
+fragments need each source to contribute beneath a selected application path.
+Requiring consumers to rewrite source documents or merge completed values would
+separate placement from ConfigKit's existing composition, precedence, source
+identity, and inspection behavior. Placement should remain part of the ordinary
+loading lifecycle and preserve the root-owned public facade.
+
+## Decision
+
+Add an optional `Destination Path` to root-owned `Input` and expose the effective
+destination on existing `SourceInfo` records. The empty path means the existing
+application root. A non-empty destination is a sequence of literal mapping keys;
+explicit sequence-index segments are invalid. Existing reserved structural keys
+remain reserved, while keys that merely contain their spelling remain ordinary
+keys.
+
+Acquire and interpret each source using its original physical identity and
+source-local directives, then place its application body before strict
+composition and the existing final lifecycle. Imported application bodies
+inherit the input destination. Placement applies to main and underlay inputs;
+ordinary root loading, selected overlays, and CLI inputs retain root placement.
+The main-owned version rule continues to check its effective application path
+at its existing lifecycle point.
+
+Placement preserves authored node locations and source identity. Introduced
+mapping structure belongs to the contributing source and uses that document's
+root location as its source-coordinate fallback. A present empty mapping
+materializes its destination; an absent `NoSource` contributes nothing. The
+result continues through the existing strict composition, overlay, inheritance,
+typed loading, diagnostics, provenance, history, sensitivity, and resource
+context mechanisms.
+
+The added exported fields preserve keyed and zero-value struct use. Callers
+using unkeyed composite literals for `Input` or `SourceInfo` must migrate to
+keyed literals. Treat this feature as minor-release work; select the version and
+document the compatibility impact during separately authorized release
+preparation, consistent with the release policy.
+
+## Alternatives considered
+
+- **Rewrite or merge sources in consumers.** This makes each consumer reproduce
+  placement, strict composition, source attribution, and inspection semantics.
+- **Add a separate loading entry point or public wrapper type.** This creates a
+  parallel API for a behavior that belongs to existing per-input loading.
+- **Load each fragment as a complete application before placement.** This runs
+  defaults, decoding, resolution, and validation on incomplete fragments rather
+  than once on the assembled application.
+
+## Consequences
+
+Consumers can assemble contributions at effective mapping paths in one ordinary
+layered load and inspect each source's placement through existing source
+records. Paths, conflicts, and later application operations use the placed
+structure while source coordinates and relative-resource contexts continue to
+identify their original sources. Public field additions require release-note
+guidance for callers using unkeyed literals.

docs/adr/0012-relative-import-destinations.md

@@ -0,0 +1,78 @@
+# ADR 0012: Place Imported Configuration at Relative Destinations
+
+## Status
+
+Accepted and implemented. The
+[configuration contract](../config.md#input-destinations) owns current behavior.
+The completed roadmap and review records are preserved at `e4270c9` under
+`docs/roadmap/` in Git history; the relative-import implementation plan remains
+at `d9f08ff:docs/roadmap/implementation.md`.
+
+## Date
+
+2026-10-14
+
+## Context
+
+ConfigKit can place an input document at a literal mapping path while retaining
+source identity, composition, and inspection in its normal loading lifecycle.
+An importing document can currently bring in other documents, but those
+contributions inherit only the importing input's destination. Consumers that
+assemble a collection therefore cannot declare the layout of imported
+fragments alongside the import itself without rewriting source documents or
+performing another merge outside ConfigKit.
+
+The extension should reuse input placement and the existing import lifecycle.
+Logical application placement must remain independent from physical path
+resolution, source identity, precedence, and resource ownership.
+
+## Decision
+
+Add an optional `destination` field to each YAML import declaration. Its value
+is a sequence of strings representing literal mapping-key segments. Omission
+and an empty sequence add no segments. A non-empty destination appends to the
+effective destination of the immediately importing document; nested imports
+continue from the resulting child destination. Every match of one glob
+declaration receives the same computed destination.
+
+Use the existing input-destination validation and reserved-key rules. Do not
+interpret destination segments as filesystem paths, separators, sequence
+indices, or root-reset instructions. Physical import paths continue to resolve
+from their declaring source under existing containment rules.
+
+Imports remain in their existing strict-composition group. A destination does
+not grant precedence, bypass cycle or repeated-source rules, or change source
+identity. Existing placement, version ownership, source records, diagnostics,
+resource contexts, inheritance, history, and inspection mechanisms continue to
+govern the placed contributions. No public Go entry point or independent
+specification-header behavior is introduced.
+
+This is additive YAML functionality and is minor-release work. Version
+selection, release notes, roadmap retirement, and publication remain separate
+release-preparation work.
+
+## Alternatives Considered
+
+- **Require complete application-root destinations on every import.** This
+  avoids inherited context but repeats collection prefixes in nested source
+  declarations and does not express placement relative to the importing
+  document.
+- **Encode destinations as dotted or slash-delimited strings.** This introduces
+  separator and escaping rules even though existing paths already represent
+  literal mapping keys as segments.
+- **Rewrite or merge imported documents in consumers.** This duplicates source
+  placement, strict composition, attribution, and inspection behavior outside
+  ConfigKit's loading lifecycle.
+- **Add independent specification headers or collection-specific validation.**
+  These are separate design questions and are not required to declare relative
+  placement.
+
+## Consequences
+
+Import declarations can describe the logical placement of their contributions
+while preserving the physical source and existing composition lifecycle.
+Placement is immediate-parent-relative, so nested imports accumulate their
+declared segments and sibling declarations remain independent. The feature is
+implemented behind the existing public loading surface; detailed validation,
+diagnostic, accounting, and inspection requirements are tracked by the
+implementation roadmap.

docs/adr/0013-shared-source-version-checks.md

@@ -0,0 +1,92 @@
+# ADR 0013: Check Source Versions with One Shared Policy
+
+## Status
+
+Accepted and implemented. The
+[configuration contract](../config.md#shared-source-version-checks) owns current
+behavior. The completed roadmap, implementation plan, consumer request, and
+resolved review findings are preserved at `e4270c9` under `docs/roadmap/` in
+Git history; the [development guide](../development.md#baseline-validation)
+provides retrieval examples.
+
+## Date
+
+2026-10-15
+
+## Context
+
+Applications that assemble one configuration from independently authored
+documents need a way to require that each contributing document declares a
+version accepted by the application's existing `Definition.Version` checker.
+Checking only the eventual composed value lets another source hide a rejected
+declaration, while separate consumer-side parsing duplicates ConfigKit's source
+handling and diagnostics.
+
+The extension must preserve one application-owned acceptance policy and the
+existing loading lifecycle. Source declarations are compatibility evidence, not
+independent fragment schemas or values to compare for equality. Existing
+composition, placement, precedence, source identity, diagnostics, and
+sensitivity rules remain authoritative.
+
+## Decision
+
+Provide a load-wide source-version mode for ordinary and layered loading. The
+zero-value mode preserves current behavior. The enabled modes check declarations
+when present or require them, using the existing `Definition.Version` path and
+checker. Interpret the configured path relative to each participating source
+before placement or composition. Different declarations may be accepted by the
+same checker; ConfigKit adds no equality, SemVer, or expected-version rule.
+
+Apply the selected policy to the actual main document, direct underlays,
+imports, and selected overlays. Missing non-main declarations are skipped in
+if-present mode and rejected in required mode. Existing main absence behavior
+remains, with required mode additionally rejecting an absent declaration on an
+actual main document. `NoSource`, unmatched optional inputs, synthetic field
+operations, and empty groups do not become documents that need declarations.
+
+Reuse the existing version vocabulary and validation boundary: absence, null,
+exact strings, and strict decimal integers retain their established meanings;
+unsupported present values fail version-type validation. Warnings remain
+nonfatal, and source declarations do not replace final application decoding or
+domain validation.
+
+After an accepted non-main declaration is checked, consume exactly that node
+before its remaining application content is composed or overlaid. Preserve the
+main declaration and its value semantics. Keep the declaration, source-local
+path, physical location, and checked absence as detached source evidence,
+separate from effective application values and history. Apply established
+sensitivity rules to that evidence, including original mounted paths and
+ancestors; retain existing safe failure disclosure.
+
+In enabled modes, the main declaration remains source-local while its protected
+application path is derived from the main input's destination. This distinction
+does not change default-mode path interpretation or weaken protection of
+remaining payload and synthetic operations.
+
+Public option-field additions and the enabled-mode interpretation for mounted
+main inputs are compatibility considerations for separately authorized minor-
+release preparation. This decision does not select a release version or
+authorize release notes or publication.
+
+## Alternatives Considered
+
+- **Check only the final composed value.** Later sources can hide an earlier
+  rejected declaration, so this does not validate every contributing document.
+- **Let consumers parse and check each source.** This duplicates acquisition,
+  source attribution, safe diagnostics, and lifecycle coordination in every
+  application.
+- **Require declarations to be equal or impose a universal version grammar.**
+  Consumers already own the acceptance policy; ConfigKit need not invent an
+  expected value or a domain-specific compatibility rule.
+- **Keep accepted non-main declarations in application payload.** A selected
+  source-local declaration is metadata for this policy and cannot also remain
+  an ordinary field at the same path without ambiguity.
+
+## Consequences
+
+Consumers can apply one existing version policy across contributing documents
+and select gradual or required adoption per load. Accepted non-main headers no
+longer participate in application composition; their inspectable evidence is
+kept separate and subject to sensitivity classification. Default callers retain
+current behavior. The implementation plan records the concrete API names,
+integration order, and validation evidence.

docs/adr/0014-sequence-placement-and-composition.md

@@ -0,0 +1,77 @@
+# ADR 0014: Place and Compose Sequence Items Explicitly
+
+## Status
+
+Accepted and implemented. The [configuration contract](../config.md#strict-document-composition)
+defines current behavior, and the [consumer guide](../consumers/README.md#identified-prompt-sequences)
+shows the maintained example. The completed roadmap, implementation plan, and
+resolved remediation record are preserved in Git history at `008d2ba` under
+`docs/roadmap/`; see the [development guide](../development.md) for retrieval
+commands.
+
+## Date
+
+2026-10-16
+
+## Context
+
+ConfigKit strictly composes independent documents by recursively combining
+mappings and rejecting other overlapping values. This makes two independently
+authored sequence fragments conflict, even when their records are distinct.
+Precedence assembly has a different purpose: a higher-priority present sequence
+replaces the lower-priority sequence as one value. Those existing rules are
+predictable, but they do not express the separate operation of collecting
+independent records while rejecting duplicate identities.
+
+Likewise, mapping destinations place a source beneath literal mapping keys, but
+there is no explicit way to state that a source mapping represents one item in a
+sequence. Inferring that intent from document shape or fields would make source
+meaning implicit and change existing placement behavior.
+
+## Decision
+
+Keep mapping placement as the zero-value behavior and add an explicit item
+placement choice for a source whose mapping should become one element at a
+non-root sequence destination. Item placement provides structure only; it does
+not infer or synthesize identity values.
+
+Allow a definition to register literal mapping paths and one literal identity
+field for sequences at those paths. Within each strict composition tier, a
+registered sequence accepts mapping records with a present string identity,
+appends distinct records in contribution order, and rejects repeated exact
+identity strings. Identical registrations coalesce; conflicting identity fields
+for the same path are invalid. Registration does not recursively select paths
+inside sequence records.
+
+Keep precedence assembly unchanged. A present higher-priority sequence replaces
+the lower-priority value wholesale, including at a registered path. Registration
+changes strict composition only; it does not turn precedence into append or
+identity-based merging.
+
+This decision preserves ConfigKit's distinction between independent
+same-priority contributions and intentional precedence. Explicit source
+placement and definition-owned composition policy make the two required choices
+visible while keeping the existing zero-value load behavior.
+
+## Alternatives Considered
+
+- **Infer item placement from a source mapping or identity field.** Shape-based
+  inference would make ordinary mapping placement depend on document contents
+  and would leave the intended destination ambiguous.
+- **Append all overlapping sequences during strict composition.** This would
+  change existing conflict semantics at unregistered paths and would not detect
+  duplicate records.
+- **Merge matching records recursively by identity.** This would add a second
+  recursive merge rule with different conflict and precedence behavior from
+  ConfigKit's existing mapping composition and overlay operations.
+- **Use identity to merge sequences across precedence tiers.** This would
+  change established whole-value replacement semantics and conflate strict
+  composition with precedence.
+
+## Consequences
+
+Consumers can explicitly place mappings as sequence items and opt selected
+sequences into duplicate-rejecting strict composition. Unregistered sequences
+retain their current strict-conflict behavior, and higher-priority sequences
+continue to replace lower-priority ones. The implementation plan owns the exact
+API, YAML syntax, diagnostics, and implementation status.

docs/config.md

@@ -67,13 +67,18 @@ ID `source-1`; enabled imports continue in depth-first order as `source-2` onwar
 contributes no source, and continues through defaults, decode, and projection. A
 missing file remains an error; it is never interpreted as no input.
 
-The current `Options` boundary accepts a defaults factory, `VersionRule`, resolver,
+`Options` accepts the application definition, ordinary-source `Destination` and
-semantic validator, explicit path and glob imports, one selected overlay, and
+`PlacementMode`, explicit path and glob imports, one selected overlay, filesystem
-filesystem context. It also accepts explicit CLI override records, static secret
+context, explicit CLI overrides, and shared source-version controls. The definition
-tags, and a dynamic path predicate. `NoSource` rejects imports, active overlays,
+may register strict sequence composition paths through
-and filesystem context as invalid combinations but accepts overrides. Input
+`SequenceCompositions`. Its zero-valued placement mode places the source mapping
-containing a reserved `configkit` mapping key is rejected while imports are
+at the destination; `sequence-item` explicitly wraps the mapping as one item at a
-disabled.
+non-root destination. Unknown modes, invalid destinations, and invalid or
+conflicting sequence registrations fail before source acquisition. Overlay and
+CLI coordinates remain rooted at the application root. `NoSource` rejects
+imports, active overlays, and filesystem context as invalid combinations but
+accepts overrides. Input containing a reserved `configkit` mapping key is rejected
+while imports are disabled.
 
 Every source, options, schema, version, defaults, decode, resolution, or validation
 failure returns a nil result and a `*LoadError`. Successful results contain caller-owned `Config`, detached
@@ -149,9 +154,60 @@ have index zero. Explicit empty groups and `NoSource` consume no source ID.
 Byte, source, node, and glob-entry budgets are shared across the load, while
 the existing per-source and import-depth bounds still apply.
 
+When a source mapping is explicitly placed as an item, its effective destination
+is the sequence container. After assembly assigns an index, nested source
+destinations are projected through that item. Physical source locations and
+resource contexts continue to identify the declaring source.
+
+#### Input destinations
+
+`Input.Destination` places the source's application mapping beneath a path
+relative to the configuration root. Its zero or empty value means root, so
+existing inputs keep their behavior. Main inputs and underlay inputs use the
+same destination model. Destination segments are literal mapping keys: dots,
+slashes, and numeric-looking text are not split or interpreted as sequence
+indexes. Explicit index segments and paths that introduce the reserved
+`configkit` or mapping-valued `extends` structure are invalid input options and
+produce a structured `LoadError` before source acquisition.
+
+Source-root `configkit.imports` directives are processed before placement. An
+import without an explicit destination inherits the effective destination of
+its importing document, including through nested imports. An import may instead
+declare a relative destination as a sequence of literal mapping keys; its keys
+append to the importing document's effective destination. Omission and `[]`
+add no keys. Nested imports continue relative to their immediate importing
+document, each declaration is independent of its siblings, and all matches of
+one glob receive the same resulting destination. This logical placement does
+not change how the physical import path resolves from its declaring file.
+
+A valid destination on `NoSource()` contributes nothing; an actual empty
+mapping materializes its destination containers. Once placed, contributions
+follow the same strict composition within a tier and recursive precedence
+behavior described above. A selected overlay and CLI overrides remain rooted at
+the application root and are not moved beneath the main input's destination.
+
+`SourceInfo.Destination` reports each acquired source's effective mapping or
+sequence-container path, including imports. `PlacementMode` reports how that
+source was placed; mapping is the zero value, and CLI/overlay sources report
+mapping unless item placement was applied. `DestinationUnresolved` is true only
+when an enclosing item index needed to name the source's destination has not yet
+been assigned. In that case `Destination` reports the nearest resolved enclosing
+collection container and omits the unresolved local suffix. A source's own item
+placement still has an exact destination at its sequence container. Completed
+loads project nested source destinations through their owning items. Callback and
+failed-load snapshots preserve the evidence available at that point; a fallback
+snapshot remains unresolved, while a later exact snapshot is false. Returned
+source records and paths are detached. Placement does not change source IDs,
+acquisition identity, physical source locations, or passive resource contexts.
+Introduced ancestor mappings use the contributing document's root location as a
+source fallback; authored content retains its original source coordinates.
+
 The maintained [layered consumer example](consumers/README.md#native-filesystem-and-layered-input)
 shows a main host file, two underlay tiers, embedded defaults, a mapping source,
 and explicit resource access without a second configuration pass.
+The accepted rationale for input placement and its relative-import extension
+is recorded in [ADR 0011](adr/0011-input-destinations.md) and
+[ADR 0012](adr/0012-relative-import-destinations.md).
 
 ### Sibling inheritance
 
@@ -269,6 +325,67 @@ error without reporting one, ConfigKit emits a generic `version.hook_failed`
 diagnostic and suppresses the returned error text. Warnings alone are retained on a
 successful result. Callback panics remain programming failures.
 
+#### Shared source-version checks
+
+`Options.SourceVersionMode` and `LayeredOptions.SourceVersionMode` select how
+one `Definition.Version` policy applies across source documents. The zero value
+`SourceVersionModeDefault` preserves the existing main-only check at its
+effective path and existing protected-path behavior. `SourceVersionModeIfPresent`
+checks each participating document that declares a version and permits absent
+non-main declarations. `SourceVersionModeRequired` rejects a participating
+document without a declaration. Enabled modes require a usable `VersionRule`
+and checker; an unknown mode or unusable rule is an options error before source
+access or callbacks.
+
+In enabled modes, `Definition.Version.Path` is interpreted in each acquired
+document's own coordinates, before placement and composition. The main document,
+direct underlay documents, imported documents (including transitive and glob
+matches), and the selected overlay participate. `NoSource`, absent optional
+imports, empty underlay groups, defaults, resolution output, inheritance, and
+synthetic CLI overrides are not documents to check. An absent declaration in an
+actual main document still reaches the checker in if-present mode; required mode
+rejects it first. With `NoSource`, the existing single absent-main checker
+behavior remains in both enabled modes. If-present omissions in non-main
+documents skip the checker. Explicit null is present and reaches the checker;
+unsupported selected values produce `version.type`. No equality with the main
+declaration or non-null rule is imposed. Acceptance establishes only that the
+declaration is accepted by the consumer's checker; it does not establish that
+each fragment conforms to a complete application schema. Final assembled
+decoding and application validation still run once.
+
+A header that is absent below a structural control follows the same omission
+policy. Actual header/control overlap is rejected, and ordinary structural
+validation and main-version ownership protection continue independently.
+
+Accepted non-main declarations are consumed from their owned payload before
+composition; their authored ancestors remain, even if empty. The main
+declaration remains in the application. Ordinary release metadata should use a
+different path. Enabled main protection uses the main input's effective path:
+its `Destination` prefixed to the source-local `VersionRule.Path`. This protects
+the remaining payload against imports, underlays, inheritance, and CLI
+overrides. Thus a mounted main looks up a local header while ownership checks
+protect its destination-prefixed application path. Main checker diagnostics and
+declaration locations use source-local coordinates; ordinary payload
+diagnostics continue to use effective paths. Default-mode diagnostics are
+unchanged.
+
+`SourceInfo.VersionCheck` is nil when enabled declaration processing did not
+occur. Otherwise it records a source-local `Path`, the observed `Version` state
+(`Present`, `Null`, and, when disclosed, exact `Text`), an actual or nearest
+available `Location`, and whether text was redacted. A non-nil record with
+`Present == false` records observed absence; it does not say the checker ran or
+accepted a declaration. Absent evidence still identifies the full requested
+header path, while its location identifies the nearest available source node.
+During callbacks and in failed-load source records,
+text is conservatively withheld because final classification may not be
+available. Successful final source records reflect completed sensitivity
+classification at the declaration's mounted path and ancestors, including
+historical classification. Redaction empties `Text` while retaining presence
+and null state. Returned copies are detached; evidence does not reopen inputs.
+Consult [ADR 0013](adr/0013-shared-source-version-checks.md) for the accepted
+decision and the [development guide](development.md#baseline-validation) for
+the completed implementation and remediation records in Git history.
+
 ### Layered metadata
 
 `Result.Metadata` describes every final canonical path. Queries retain explicit
@@ -299,6 +416,11 @@ the descendant can therefore retain history after `Lookup` stops reporting it as
 effective. Equal-valued input is still an explicit base definition, while a derived
 value for absent input remains non-explicit.
 
+Appending registered records during strict composition assigns each contribution
+its assembled sequence index in history. A later precedence tier that supplies a
+sequence records replacement at the sequence path; history does not imply
+identity-based merging across tiers.
+
 A mapping assembled from the selected file and imports has one composite base origin
 whose locations retain source traversal order. A mapping also visited by an overlay
 has an overlay-layer composite origin with the lower contributing locations followed
@@ -423,6 +545,46 @@ an explicit `LoadSecretsDir` bootstrap, then use `WriteDiagnostics`,
 ConfigKit does not infer bootstrap outcomes from a secret reference and does not
 bundle these independent reports into a command framework.
 
+## Effective configuration diffs
+
+`configkit.Diff(left, right)` compares two completed successful loads of the same
+configuration type. `left` is the earlier state and `right` is the later state.
+Applications load both sides with the sources and options they choose; to inspect
+an overlay's impact, load the same base once without the overlay and once with it
+selected. The [consumer guide](consumers/README.md#effective-configuration-diffs)
+links to maintained examples. The public API returns safe changed-region records;
+applications own their presentation.
+
+Comparison uses the frozen canonical effective inspection values, not mutable
+`Result.Config`, source text, provenance, or history. It does not reopen sources,
+reread environment variables, or rerun defaults or callbacks. Equal effective
+values produce no records even when sources, explicit-input status, defaults, or
+resolution histories differ; for example, explicit zero and defaulted zero are
+equal. Mappings compare recursively, sequences compare atomically, and scalar,
+kind, or null/container replacements report their affected region. Records use
+the existing comparator's canonical pointer ordering. `Present=false` with empty
+YAML means absence; explicit null is present and renders as `null`.
+
+Before either side is returned, sensitivity from both loads is applied to both
+snapshots, including historical and dependency-derived classification. A
+classification on either side protects the corresponding values on both sides.
+`Redacted` reports masking, while `HiddenChanged` reports an actual concealed
+value or presence change; it is not implied merely by redaction. A structural
+replacement that prevents safe correspondence masks the complete reported
+region, and an absent side remains absent. Record membership establishes that a
+change occurred even when safe snapshots render identically. Literal
+marker-looking input is ordinary input; consumers use the record fields rather
+than interpreting marker text.
+
+Typed secret references contribute their configured environment names to the
+frozen comparison, never resolved credential bytes. Credential rotation behind
+an unchanged reference is therefore not detected. The records contain changed
+regions only, not paired full-document context; independently calling
+`WriteEffective` on each result does not create cross-protected context. Nil or
+uninitialized results return an error with no records. A failed `Load` retains
+its normal nil-result/`LoadError` behavior, which callers handle before invoking
+`Diff`.
+
 ## Typed secret references
 
 Credential-bearing fields use the opaque `Secret` type and store an environment
@@ -606,12 +768,47 @@ Application defaults do not participate in this operation.
 | Mapping | Mapping | Recurse by mapping key |
 | Any other pair of present nodes | Any other pair of present nodes | `compose.conflict` |
 
-Every non-mapping overlap is a conflict, even when values are equal. Nulls and
+Every non-mapping overlap is a conflict, even when values are equal, except for
-sequences are present atomic values, so they also conflict when repeated; sequences
+sequence/sequence contributions at a registered sequence-composition path. Nulls
-are never joined by index. Disjoint entries under shared mappings compose, making
+remain atomic conflicts. Unregistered sequences conflict when repeated and are
+never joined by index. Disjoint entries under shared mappings compose, making
 stable keyed mappings the natural representation for independently contributed
 entries.
 
+`Definition.SequenceCompositions` registers literal mapping paths and one literal
+`IdentityField` for sequences that should compose independently authored records.
+Registration paths follow input-destination key rules: parsed numeric tokens are
+literal mapping keys, explicit index segments and reserved `configkit` or
+mapping-valued `extends` segments are invalid, and the root registration is
+harmless and unused. The identity field is one literal string key; neither the
+field name nor identity strings are normalized.
+At each registered path, every actual sequence contribution in a strict tier is
+validated, including a singleton contribution: each record must be a mapping with
+a present string identity field. Distinct exact identity strings append in source
+and list order; duplicate identities conflict even if the records are otherwise
+equal or disjoint. Empty identity strings are valid. Malformed records produce
+`compose.invalid`; duplicate identities produce `compose.conflict`, with the
+sequence container and source locations identifying a duplicate without exposing
+identity values. Missing paths and non-sequence values do not fail by themselves.
+Identical registrations coalesce; conflicting registrations at one path and
+invalid registration paths produce `options.invalid`. Unused and root registrations
+are allowed and have no effect.
+
+Registration changes strict composition only. Each underlay group and the main
+tier has independent duplicate-identity state. Precedence assembly is unchanged:
+a present higher-priority sequence replaces the lower sequence as one value,
+including at a registered path. Overlays, CLI overrides, defaults, inheritance,
+and application resolution do not run the registered identity check. The accepted
+rationale is recorded in [ADR 0014](adr/0014-sequence-placement-and-composition.md).
+The [maintained prompt catalog](consumers/README.md#identified-prompt-sequences)
+shows item path and glob imports, helper-supplied identity, and main-tier
+replacement of a lower-priority sequence.
+When an enabled source-version mode is selected, declarations are checked in each
+source's own coordinates before placement and composition. Accepted non-main
+headers are consumed before strict composition and cannot supply a registered
+record identity. Final typed decoding and application validation still run on the
+completed configuration.
+
 An empty mapping contributes no child definitions. Two empty mappings compose, and
 an empty mapping neither clears nor conflicts with another mapping's children.
 Shared mapping containers retain all contributing value locations as their composite
@@ -711,9 +908,13 @@ zero.
 Imports are opt-in. With `Options.Imports` enabled, a document may reserve its root
 `configkit` mapping for an `imports` sequence. ConfigKit removes that mapping before
 application decoding. Each sequence item is a mapping with exactly one nonempty
-string `path` or `glob` plus an optional boolean `optional`; all other shapes and
+string `path` or `glob`, an optional boolean `optional`, and an optional
-fields are `import.invalid`. A `configkit` key below the root is invalid. With
+`destination` sequence of strings. Every destination string is one literal
-imports disabled, any occurrence remains `import.disabled`.
+mapping key and follows the input-destination validation rules above; quote
+numeric-looking keys so YAML reads them as strings. Null, scalar destinations,
+and non-string members are `import.invalid`, as are all other unsupported shapes
+and fields. A `configkit` key below the root is invalid. With imports disabled,
+any occurrence remains `import.disabled`.
 
 The directive key is `configkit`, not the `_configkit` spelling used in v0.1.0.
 There is no legacy alias: `_configkit` is ordinary application data, subject to
@@ -742,6 +943,30 @@ walk failures, matched directories, invalid documents, escapes, and repeated tar
 remain errors. Final candidates are bounded by the remaining source limit before
 their contents are accumulated.
 
+Each path or glob declaration may include `placement: mapping` or
+`placement: sequence-item`. Omission means `mapping` for that declaration,
+including every match of a glob; placement is not inherited. Sequence-item
+placement requires a nonempty effective destination and wraps the imported
+mapping as one element of a sequence there. It does not split source sequences
+or infer identity fields. Repeated sequences still conflict unless their path is
+registered through `Definition.SequenceCompositions`; registration does not
+change placement or precedence behavior. Sequence records retain source
+locations through placement and history; indexes describe their assembled
+positions while source coordinates continue to identify the declaring files.
+Header/version policy and final application validation retain their existing
+owners and timing; sequence registration is a strict-composition rule only.
+
+An item import first opens a local mapping scope. Its body and ordinary helper
+imports compose within that record. An omitted helper destination or
+`destination: []` places the helper at the record root; other destinations are
+relative to the immediate importing source. A helper may supply fields such as
+the record's `id`. An explicit nested `sequence-item` import creates a sequence
+inside the record, and its placement is independent of the enclosing item.
+At the record root, an item import must name a nonempty nested destination.
+Physical paths continue to resolve from the file that declares each import.
+An actual empty mapping contributes an empty item, while an optional unmatched
+path or glob contributes nothing.
+
 For host files, the configuration root defaults to the selected file's canonical
 directory. A host file may supply `FilesystemContext.Root` to widen that root but
 may not supply `BaseDir` or a native `FS`. Byte, reader, and mapping inputs with host context

docs/consumers/README.md

@@ -17,7 +17,11 @@ sanitized shapes using only ConfigKit and the Go standard library:
 | Seriatim-like | Independent strict ordered speaker and autocorrect rule files | First-match and ordered replacement algorithms; no central application configuration file |
 | Bundled file | Simple native `fs.FS` source through ordinary `Load` | Selection and lifetime of the application-owned embedded filesystem |
 | Layered catalog | Embedded defaults with an import, a mapping underlay, an independent host main file, explicit false/zero input, and source-relative resource access | Domain validation and opening/interpreting the template resource |
+| Mounted collections | Entry-declared relative destinations, nested metadata/prompt/profile imports, local inheritance, and a version-only higher-tier override | Collection IDs, profile meaning, and opening/interpreting prompt resources |
 | Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
+| Effective configuration diff | Same-type frozen effective comparisons for two selected files or base-versus-overlay impact | Source/options selection and consumer-owned safe presentation |
+| Shared source-version checks | One `Definition.Version` policy for accepted declarations across participating source documents, with optional or required declarations and sanitized evidence | Choosing which declarations the application accepts; final assembled schema and domain validation |
+| Identified prompt sequences | Explicit item path/glob imports, helper-supplied IDs, reusable single-field registration, and main-tier replacement of a lower-priority collection | Prompt meaning and final domain validation |
 
 The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
 executable examples and ordinary tests. It contains no private application data,
@@ -51,6 +55,37 @@ both without redefining their syntax. ConfigKit overlays are configuration overl
 they do not select or replace an application's LLM, model, pipeline, report, or
 execution profile concepts.
 
+## Shared source-version checks
+
+[`LoadVersionedService`](../../examples/consumers/source_version.go) demonstrates
+if-present and required modes with one `Definition.Version` rule across a mounted
+main input and an underlay. The example reads only sanitized
+`SourceInfo.VersionCheck` fields; its executable test is in
+[`layered_test.go`](../../examples/consumers/layered_test.go). The
+[configuration contract](../config.md#shared-source-version-checks) defines
+participation, source-local lookup and diagnostics, non-main header consumption,
+main-path protection, default behavior, and evidence disclosure. Accepted
+declarations do not replace final assembled decoding or application validation.
+
+## Effective configuration diffs
+
+[`CompareFiles`](../../examples/consumers/diff.go) loads two caller-selected files
+with one application definition, handles each load error, calls `configkit.Diff`,
+and presents the safe records through consumer-owned `FormatDifferences`.
+[`CompareRolloutOverlay`](../../examples/consumers/diff.go) loads the same base
+once without an overlay and once with the selected overlay, so omitted lower
+priority values remain present. Its resolver records a derived endpoint URL after
+overlay application, and its nested typed secret reference is classified before
+the resulting records are presented.
+
+The maintained [behavior tests and executable examples](../../examples/consumers/diff_test.go)
+use temporary files and disposable secret values. Presenters should use
+`ValueSnapshot.Present` for absence, record membership for change, and
+`HiddenChanged` for a withheld change indicator. Do not parse the redaction marker
+or add separately rendered full contexts that lack combined sensitivity. The
+[configuration contract](../config.md#effective-configuration-diffs) owns shared
+equality, granularity, and disclosure semantics.
+
 ## Named sibling inheritance
 
 [`LoadPresets`](../../examples/consumers/inheritance.go) loads the maintained
@@ -88,6 +123,65 @@ and may fail independently of the completed configuration load. The
 [configuration contract](../config.md#source-resource-contexts) owns exact
 lifetime and precedence rules.
 
+[`LoadPromptBundle`](../../examples/consumers/layered.go) is the ordinary-root
+counterpart: its entry opts into imports through `Load`, imports metadata at the
+root, and places a prompt beneath `prompts` using YAML. The executable example
+and behavior test are in
+[`layered_test.go`](../../examples/consumers/layered_test.go).
+
+## Input destinations and mounted collections
+
+Main and underlay inputs use the same destination field. An import without a
+`destination` inherits its declaring document's effective destination; an
+explicit sequence of key strings appends a relative suffix. Nested imports
+append to their immediate parent's effective destination, while filesystem
+paths remain relative to the declaring file. Destinations are application
+mapping paths, independent of filesystem context. The configuration contract
+owns the complete behavior and validation rules.
+
+The small [`Example_inputDestination`](../../examples/consumers/destinations_test.go)
+mounts one mapping source beneath literal collection/prompt keys and loads a
+second input without a destination to show that root placement remains the
+default. Consumers pass paths, not filenames or namespace strings for ConfigKit
+to interpret.
+
+[`LoadCollectionBundle`](../../examples/consumers/destinations.go) assembles an
+embedded collection manifest mounted beneath a literal collection path. The
+entry's YAML places nested metadata imports at the collection root and prompt
+and profile peers beneath their own keys. A higher-priority input changes only
+one prompt's ordinary `version` field. The main document alone supplies the
+application schema version. A prompt's local `extends` relationship resolves
+after all tiers, so `custom` inherits the final `brief` content and fields while
+retaining its own profile selection.
+
+The resolver follows each effective `content_file` origin to its declaring
+source context. This also works for `custom`'s inherited resource. The
+application-owned [`ReadCollectionPromptContent`](../../examples/consumers/destinations.go)
+demonstrates the same lookup after loading; ConfigKit does not open or interpret
+the resource. [`destinations_test.go`](../../examples/consumers/destinations_test.go)
+checks source destinations and authored coordinates, presence, inherited values,
+relative resources, and strict peer conflicts. The
+[configuration contract](../config.md#input-destinations) owns shared placement,
+import, source-location, and ownership behavior.
+
+## Identified prompt sequences
+
+[`LoadPromptCatalog`](../../examples/consumers/prompt_catalog.go) uses one
+definition registration for the literal `prompts` path and `id` field. Its main
+file imports one prompt by path and others by glob, placing each source as an
+item. A nested ordinary helper import supplies an item's ID. The main tier
+strictly appends the distinct records in contribution order; its completed
+sequence replaces the lower-priority default collection as one value.
+
+The example's `validatePromptCatalog` remains application-owned. It checks that
+prompt names and message lists satisfy this consumer's requirements after
+ConfigKit has composed, projected, and decoded the configuration. It does not
+add recursive record merging, identity-based overlay, or final uniqueness checks
+after defaults and resolution. See the [strict composition contract](../config.md#strict-document-composition),
+[import syntax](../config.md#explicit-imports), and
+[ADR 0014](../adr/0014-sequence-placement-and-composition.md) for the exact
+boundaries.
+
 Known module catalogs should use canonical object entries with a module identifier
 and typed options. A small union struct is sufficient when the available option
 fields are known; validation selects which fields apply to each module. Runtime-
@@ -167,7 +261,9 @@ focused behavioral owner:
 | Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
 | `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
 | Native filesystem, grouped underlays, programmatic mapping, retained resource context | `Example_nativeFilesystem`, `Example_layeredCatalog`, and their focused consumer tests |
+| Literal input destinations, root-default compatibility, and mounted peer collections | `Example_inputDestination`, `LoadCollectionBundle`, and `destinations_test.go` |
 | Named sibling inheritance, presence, and derivation | `Example_inheritedPresets` and `TestPresetCatalogOneLoadAndDerivation` |
+| Effective configuration diffs and consumer-owned presentation | `ExampleDiff`, `ExampleCompareFiles`, and `ExampleCompareRolloutOverlay` |
 | Results, metadata, diagnostics, effective output, and writer failures | Focused root-package load, provenance, rendering, and explanation tests |
 
 The package-level import-boundary test covers the consumer examples too: supported

docs/development.md

@@ -39,9 +39,11 @@ public behavior.
 | Task | Read |
 | --- | --- |
 | Repository orientation or component responsibility | [Component overview](internal/overview.md) |
+| Input destinations | [Configuration contract](config.md#input-destinations), [ADR 0011](adr/0011-input-destinations.md), and the destination tests below |
+| Shared source-version checks | [Configuration contract](config.md#shared-source-version-checks), [ADR 0013](adr/0013-shared-source-version-checks.md), and the version/source-version tests below |
 | Documentation changes | The owning document |
 | Licensing, dependencies, attribution, or release-document changes | [Project grant](../COPYRIGHT) and [attribution](oss/attribution.md); release changes also follow the release procedure |
-| Architecture decisions or future work | [Deferred scope](roadmap/deferred.md) and relevant ADRs listed below |
+| Architecture decisions or future work | [Future features](roadmap/future.md) and relevant ADRs listed below |
 | Code and test changes | The owning contract and tests from the map below |
 | Examples or copyable assets | The owning implemented contract and [consumer adoption guide](consumers/README.md) |
 | Release preparation | [Release procedure](release.md) |
@@ -49,11 +51,14 @@ public behavior.
 Accepted decisions:
 
 - [Separate composition and overlay](adr/0001-separate-composition-and-overlay.md)
+- [Check source versions with one shared policy](adr/0013-shared-source-version-checks.md)
 - [Own YAML semantics behind a private parser boundary](adr/0002-own-yaml-semantics.md)
 - [Preserve presence and record application resolution](adr/0003-preserve-presence-and-resolution-history.md)
 - [Secret references and explicit bootstrap](adr/0004-secret-references-and-explicit-bootstrap.md)
 - [Explicit overrides and safe explanation](adr/0005-explicit-overrides-and-safe-explanation.md)
 - [Keep the public facade root-owned](adr/0006-public-facade.md)
+- [Compare frozen effective configuration snapshots](adr/0010-effective-configuration-diff.md)
+- [Place inputs at literal application mapping paths](adr/0011-input-destinations.md)
 
 For cross-cutting changes, follow every applicable row. Completed implementation
 and remediation plans are preserved in Git history at `cb5b435`; use current
@@ -64,8 +69,9 @@ git show cb5b435:docs/roadmap/remediation.md
 ```
 
 Release-candidate, publication, and verification work follows the operational
-[release procedure](release.md). Its single publication command validates the
+[release procedure](release.md). Its module-selected ReleaseKit `publish`
-committed candidate and publishes only the intended refs.
+invocation validates the committed candidate and publishes only the intended
+tag; those release checks remain distinct from the everyday development check.
 
 The completed string-and-integer schema-version implementation and remediation
 records are preserved in Git history at `244104f`. The
@@ -93,9 +99,60 @@ preserved in Git history at `73ce6e9` under `docs/roadmap/`. Current overlay
 behavior belongs to the [configuration contract](config.md#selected-overlays),
 and release operations belong to the [release procedure](release.md).
 
-Install Go 1.25.0 or a supported patched/newer Go toolchain. Acquire declared
+The completed ReleaseKit adoption, startup performance request and experiments,
-dependencies explicitly before entering an offline development or validation
+benchmark evidence, performance audit, implementation plan, and remediation
-environment:
+record are preserved in Git history at `8e91a2b` under `docs/roadmap/`. For example:
+
+```sh
+git show 8e91a2b:docs/roadmap/startup-benchmark.md
+```
+
+Remaining optimization candidates belong to
+[future performance experiments](roadmap/future.md#3-performance-experiments).
+
+The completed effective-configuration diff roadmap, implementation plan, and
+resolved review findings are preserved in Git history at `1c2610c` under
+`docs/roadmap/`. The
+[configuration contract](config.md#effective-configuration-diffs) owns current
+comparison and disclosure behavior, and
+[ADR 0010](adr/0010-effective-configuration-diff.md) records the decision.
+
+The completed input-destination, relative-import-destination, and shared
+source-version roadmaps, associated consumer request, implementation plan, and
+resolved review findings are preserved in Git history at `e4270c9` under
+`docs/roadmap/`. For example:
+
+```sh
+git show e4270c9:docs/roadmap/implementation.md
+git show e4270c9:docs/roadmap/remediation.md
+```
+
+Current behavior belongs to the configuration contract's
+[input destinations](config.md#input-destinations),
+[imports](config.md#explicit-imports), and
+[shared source-version checks](config.md#shared-source-version-checks) sections.
+Explicit sequence-item placement and registered strict composition are owned by
+the [strict composition](config.md#strict-document-composition) and
+[imports](config.md#explicit-imports) sections. The
+[maintained prompt catalog](consumers/README.md#identified-prompt-sequences)
+shows the current consumer boundary, and [ADR 0014](adr/0014-sequence-placement-and-composition.md)
+records the decision.
+
+The completed sequence-composition roadmap, implementation plan, and resolved
+remediation record are preserved in Git history at `008d2ba` under
+`docs/roadmap/`. For example:
+
+```sh
+git show 008d2ba:docs/roadmap/sequence-composition.md
+git show 008d2ba:docs/roadmap/implementation.md
+git show 008d2ba:docs/roadmap/remediation.md
+```
+
+Potential enhancements are tracked in [future features](roadmap/future.md).
+
+Install the Go version required by `go.mod` or a compatible newer toolchain.
+Acquire declared dependencies explicitly before entering an offline
+development or validation environment:
 
 ```sh
 go mod download
@@ -125,11 +182,10 @@ Use focused checks while iterating, with validation proportionate to the change
 under the testing policy. Documentation-only work normally needs the local-link
 check below and whitespace review; behavior-bearing examples and commands also
 need execution. Use `go test -race ./...` for ownership or concurrency changes.
-The [publication command](release.md#4-publish-the-committed-candidate) invokes
+The [release procedure](release.md#4-publish-the-committed-candidate) performs
-the release checker once. It performs one minimum-toolchain offline race-suite
+its selected validation through one `publish` invocation. The everyday checker
-run, one full vet pass, and Linux cross-builds using readonly module mode.
+remains a development gate and is not a separate release prerequisite. CI never
-It already covers examples, links, and package boundaries; do not additionally
+gates a release.
-run the everyday checker just to repeat those checks. CI never gates a release.
 
 ## Task-to-test map
 
@@ -140,22 +196,25 @@ code changes. Use the component overview to find the corresponding implementatio
 | Task | Behavioral test owners | Focused command |
 | --- | --- | --- |
 | YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../internal/engine/parse_test.go) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` |
-| File/reader access, imports, globs, containment | [Sources](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [imports](../internal/engine/imports_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
+| File/reader access, imports, globs, containment | [Sources](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [imports](../internal/engine/imports_test.go), [relative destinations](../internal/engine/destination_import_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
 | Native filesystem and mapping sources | [Native acquisition](../internal/engine/native_filesystem_test.go), [filesystem facade](../facade_filesystem_test.go), [mapping facade](../facade_mapping_test.go) | `go test ./internal/engine -run 'NativeFilesystem'` and `go test . -run 'TestFacade'` |
 | Composition, selected overlays, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [selected overlays](../internal/engine/selected_overlay_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` |
 | Sibling inheritance, provenance, history, sensitivity | [Expansion](../internal/engine/inheritance_test.go), [destination scopes](../internal/engine/inheritance_walk_test.go), [origins](../internal/engine/inheritance_origin_test.go), [history](../internal/engine/inheritance_history_test.go), [secrets](../internal/engine/inheritance_secret_test.go), [public loading](../facade_inheritance_test.go) | `go test ./internal/engine -run 'Inheritance\|Inherited'` and `go test . -run '^TestFacadeInheritance\|^TestFacadeInheritedSecrets'` |
 | Layered loading and source equivalence | [Grouped lifecycle](../internal/engine/load_request_test.go), [layered facade](../facade_layered_test.go), [equivalence](../facade_equivalence_test.go) | `go test ./internal/engine -run '^TestGrouped'`, `go test . -run '^TestFacadeLayered'`, and `go test . -run '^TestEquivalentSourceForms'` |
+| Input and relative-import destinations, mounted sources, and source ownership | [Destination engine tests](../internal/engine/destination_test.go), [tier tests](../internal/engine/destination_tiers_test.go), [import traversal and version tests](../internal/engine/destination_import_test.go), [accounting tests](../internal/engine/destination_accounting_test.go), [lifecycle inspection tests](../internal/engine/destination_import_lifecycle_test.go), [public source/error tests](../facade_destination_test.go), [resource contexts](../facade_resource_context_test.go), and [consumer examples](../examples/consumers/destinations_test.go) | `go test ./internal/engine -run 'Destination|Import|Glob|Mounted'`, `go test . -run 'Destination|Import|SourceContext|FacadeMounted'`, and `go test ./examples/consumers` |
+| Shared source-version modes and evidence | [Engine source-version tests](../internal/engine/source_version_test.go), [public facade tests](../facade_source_version_mode_test.go), and [consumer example tests](../examples/consumers/layered_test.go) | `go test ./internal/engine -run 'SourceVersion'`, `go test . -run 'SourceVersion'`, and `go test ./examples/consumers` |
 | Schema, defaults, projection, cloning | [Schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
 | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
 | Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |
 | Passive resource contexts | [Engine contexts](../internal/engine/resource_context_test.go), [public contexts](../facade_resource_context_test.go) | `go test ./internal/engine -run 'Resource'` and `go test . -run 'SourceContext'` |
 | Secrets, bootstrap, redaction, explanation | [References](../internal/engine/secret_reference_test.go), [bootstrap](../internal/engine/secrets_test.go), [rendering](../internal/engine/render_test.go), [explanation](../internal/engine/explain_test.go) | `go test ./internal/engine -run 'Secret\|Bootstrap\|Effective\|Explain\|Explanation\|History\|Sensitivity'` |
-| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native and layered examples](../examples/consumers/layered_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
+| Effective configuration diff | [Engine comparison and masking tests](../internal/engine/diff_test.go), [engine operation tests](../internal/engine/diff_operation_test.go), [root facade tests](../facade_diff_test.go), and [consumer examples](../examples/consumers/diff_test.go) | `go test ./internal/engine -run 'Diff|Explain|History|Secret|Independent'`, `go test . -run 'Diff|FacadeInspection|PublicFacadeBoundary|DependencyImportBoundary'`, `go test ./examples/consumers`, and `go test . -run '^ExampleDiff$'` |
+| Consumer examples and migration fixtures | [Consumer tests](../examples/consumers/consumers_test.go), [native, layered, and ordinary relative-import examples](../examples/consumers/layered_test.go), [mounted collection examples](../examples/consumers/destinations_test.go), [API examples](../example_test.go) | `go test ./examples/consumers` and `go test . -run '^Example'` |
 | Assembly and layered scaling evidence | [Assembly benchmarks](../internal/engine/assembly_bench_test.go), [layered benchmarks](../internal/engine/underlay_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkUnderlay' -benchmem`; repeat with `^BenchmarkCompose` and `^BenchmarkOverlay` |
 | Inheritance scaling evidence | [Expansion benchmarks](../internal/engine/inheritance_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` |
 | Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go), [public boundary](../public_boundary_test.go) | `go test . -run 'TestLocalDocumentationLinks\|TestDependencyImportBoundary\|TestPublicFacadeBoundary'` |
-| Development and release checker behavior | [Shell regression](../release_check_test.go) | `go test . -run 'TestCheckScripts\|TestDevelopmentCheck'` |
+| Development check behavior | [Development checker test](../development_check_test.go) | `go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$'` |
-| Guarded release publication and recovery | [Publication regression](../release_publish_test.go) | `go test . -run '^TestReleasePublication'` |
+| Release profile wiring | [Release profile test](../releasekit_profile_test.go) | `go test . -run '^TestReleaseKitProfile$'` |
 
 ## Fuzz validation
 

docs/internal/overview.md

@@ -8,11 +8,19 @@ private state; public signatures and fields do not expose engine types.
 Implemented component owners:
 
 - `internal/engine` owns host and native-filesystem source acquisition,
-  grouped strict composition, recursive precedence assembly, and destination-local
+  grouped strict composition, recursive precedence assembly, per-input mapping
-  sibling inheritance before typed decoding. It also owns schema
+  and sequence-item placement, definition-registered distinct-ID sequence
+  composition within strict tiers, and immediate-parent-relative import
+  placement within that assembly. Higher-priority sequences replace lower
+  sequences as whole values. The engine also owns destination-local sibling
+  inheritance before typed decoding, plus shared source-version checking with
+  sanitized declaration evidence.
+  It retains each source's effective placement alongside physical source
+  identity and owns schema
   inspection, lifecycle coordination, callback auditing,
   provenance/history, passive source-context retention, secret resolution and
-  bootstrap, and safe inspection rendering. It never imports the root package.
+  bootstrap, safe inspection rendering, and effective-value comparison over
+  frozen inspection snapshots. It never imports the root package.
 - Root `Source`, `Filesystem`, `Input`, `Underlay`, `Path`, `Secret`, records,
   lifecycle callbacks, results, and bootstrap reports are root-defined wrappers
   or records. Callback wrappers pass only live engine context during a callback;
@@ -21,6 +29,9 @@ Implemented component owners:
 - Root conversion files explicitly cross the path, record, callback, secret, and
   error boundaries. There are no public aliases, anonymous engine embeddings, or
   public engine bridge methods.
+- Root `Diff` and `Difference` provide the public comparison boundary and
+  convert detached engine records to root-owned paths and snapshots; consumer
+  examples own presentation of the safe changed regions.
 - `internal/document` owns the parser-independent ordered tree and cloning.
   `internal/yaml` is the sole upstream YAML adapter and parser/dumper boundary.
 - Engine mechanism tests own source, composition, inheritance, decoding,
@@ -37,10 +48,23 @@ these constraints and rejects exported aliases, fields, or signatures involving
 internal types.
 
 The [configuration contract](../config.md) owns implemented YAML and lifecycle
-semantics. The [consumer adoption guide](../consumers/README.md) owns application
+semantics, including [input destinations](../config.md#input-destinations),
-guidance. The [architecture policy](../policy/architecture.md) owns contributor
+[shared source-version checks](../config.md#shared-source-version-checks), and
-boundaries, and [ADR 0006](../adr/0006-public-facade.md) records the facade
+[effective configuration diffs](../config.md#effective-configuration-diffs).
+The [strict composition contract](../config.md#strict-document-composition)
+owns sequence placement, registration, replacement, and history behavior; the
+[consumer guide](../consumers/README.md#identified-prompt-sequences) shows the
+maintained example.
+The [consumer adoption guide](../consumers/README.md) owns application guidance.
+The [architecture policy](../policy/architecture.md) owns contributor
+boundaries; [ADR 0006](../adr/0006-public-facade.md) records the facade decision
+and [ADR 0010](../adr/0010-effective-configuration-diff.md) records the diff
+decision; [ADR 0011](../adr/0011-input-destinations.md) records the placement
 decision. See the [development guide](../development.md) for validation commands
 and [release procedure](../release.md) for source-candidate gates. [ADR
 0009](../adr/0009-sibling-inheritance.md) records why inheritance is a built-in
-post-assembly structural operation.
+post-assembly structural operation. [ADR 0012](../adr/0012-relative-import-destinations.md)
+records the relative-import extension; [ADR 0013](../adr/0013-shared-source-version-checks.md)
+records the source-version decision.
+[ADR 0014](../adr/0014-sequence-placement-and-composition.md) records explicit
+sequence placement and composition.

docs/oss/attribution.md

@@ -2,11 +2,12 @@
 
 ## Standard Repository Policies
 
-Material: `docs/policy/meta.md`, `docs/policy/oss.md`,
+Material: `docs/policy/release.md`, adapted from
+`e833faddf120c789a9b45348edaf75720de16348`; `docs/policy/meta.md`, `docs/policy/oss.md`,
 `docs/policy/documentation.md`, `docs/policy/agents.md`,
-`docs/policy/architecture.md`, `docs/policy/testing.md`, and
+`docs/policy/architecture.md`, `docs/policy/testing.md`; root `AGENTS.md`; and the
-`docs/policy/release.md`; root `AGENTS.md`; and the Policy Reading Guide in
+Policy Reading Guide in `docs/development.md`, adapted from
-`docs/development.md`, adapted for this repository.
+`d84a38ebab26f048cafbe59a2246700c35d29843` for this repository.
 
 Copyright (C) 2026 Eric Rakestraw
 
@@ -14,10 +15,14 @@ SPDX-License-Identifier: CC-BY-SA-4.0
 
 License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
 [COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/COPYRIGHT) |
-[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE).
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/LICENSE) |
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/COPYRIGHT) |
+[LICENSE](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/LICENSE).
 
 [Source](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843).
 
+[Source](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348).
+
 ## go-yaml v4
 
 Selected module: `go.yaml.in/yaml/v4` at `v4.0.0-rc.6`.

docs/policy/architecture.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.3
 
-**Last Updated**: 2026-09-29
+**Last Updated**: 2026-10-16
 
 **Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/architecture.md)
 
@@ -19,8 +19,8 @@ to ADRs for decision rationale.
 ConfigKit is an opinionated Go library for consistent YAML configuration loading
 and resolution across consuming applications. The [component overview](../internal/overview.md)
 owns implementation inventory, the [configuration contract](../config.md) owns
-implemented behavior, and the [deferred scope](../roadmap/deferred.md) preserves
+implemented behavior, and the [future feature list](../roadmap/future.md) preserves
-deferred scope.
+candidates for future consideration.
 
 ## Adopted Constraints And Implemented Structure
 
@@ -99,6 +99,15 @@ types, field meanings, defaults, normalization, semantic validation, and schema
 version policy. Applications also own main-file search conventions, CLI wiring,
 remote acquisition, runtime initialization, and resource checks.
 
+The engine applies each input's mapping destination within the existing source
+assembly, applies immediate-parent-relative YAML destinations to imports, and
+retains each effective placement with source identity and inspection records;
+the root facade owns the public fields and conversions. The
+[configuration contract](../config.md#input-destinations) defines the observable
+placement behavior. [ADR 0011](../adr/0011-input-destinations.md) records input
+placement, and [ADR 0012](../adr/0012-relative-import-destinations.md) records
+the import extension.
+
 Library code must not depend on consuming applications or initialize their
 runtime resources. It must not perform implicit network access, discover
 application-specific paths, or change process-global state during ordinary `Load`.
@@ -154,13 +163,23 @@ framework on this library.
 
 Within a configuration tier, independent contributions use strict composition:
 shared mappings combine recursively, while overlapping non-mapping definitions
-are conflicts, including equal values. Between precedence tiers, intentional
+are conflicts, including equal values, except that sequences at explicitly
-overlay combines mappings recursively, retains omitted lower-priority children,
+registered paths append records with distinct present string identities. Between
+precedence tiers, intentional overlay combines mappings recursively, retains
+omitted lower-priority children,
 and replaces other present values according to the existing overlay rules.
 Tier precedence is explicit; traversal order within a tier establishes stable
 reporting, not permission to override. The distinction and its rationale are
 recorded in [ADR 0001](../adr/0001-separate-composition-and-overlay.md).
 
+Sequence-item placement and sequence registration are explicit source and
+definition controls; registration does not change precedence replacement. The
+[configuration contract](../config.md#strict-document-composition) defines the
+behavior, [ADR 0014](../adr/0014-sequence-placement-and-composition.md) records
+the decision, and the [consumer guide](../consumers/README.md#identified-prompt-sequences)
+shows the implemented subset. This feature does not authorize arbitrary
+configurable merge strategies.
+
 The main document and its imports form a strictly composed tier. Explicit
 underlay groups compose strictly within each group, then combine recursively
 from lowest to highest beneath the main tier. Source acquisition kind does not
@@ -201,6 +220,13 @@ See [ADR 0005](../adr/0005-explicit-overrides-and-safe-explanation.md).
 Detailed syntax and operation tables belong to the
 [current configuration contract](../config.md).
 
+The frozen inspection boundary also supports comparing completed same-type
+results without reopening sources or rerunning the load lifecycle. The
+[configuration contract](../config.md#effective-configuration-diffs) owns
+comparison and disclosure behavior, the [component overview](../internal/overview.md)
+owns implementation responsibility, and [ADR 0010](../adr/0010-effective-configuration-diff.md)
+records the accepted decision.
+
 ## Ownership And Confidentiality
 
 Returned configuration and metadata must not share mutable state across loads.
@@ -227,7 +253,7 @@ for safe messages supplied by their hooks.
 Do not introduce automatic directory discovery, network providers, arbitrary
 merge strategies, additional configuration languages, or application runtime
 management without concrete consumer evidence and an explicit design decision.
-The [deferred scope](../roadmap/deferred.md#explicit-non-goals-and-deferred-scope)
+Record significant decisions to exclude capabilities, and their rationale, in
-owns the deferred-feature inventory. Significant boundary
+ADRs. Significant boundary changes require an ADR and corresponding
-changes require an ADR and corresponding policy/contract updates; implementation
+policy/contract updates; implementation convenience alone is not a reason to
-convenience alone is not a reason to broaden the public API.
+broaden the public API.

docs/policy/documentation.md

@@ -2,7 +2,7 @@
 
 **Base Policy Version:** 1.11
 
-**Last Updated**: 2026-09-28
+**Last Updated**: 2026-10-16
 
 **Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/documentation.md)
 
@@ -38,9 +38,10 @@ roadmap owns implementation status and sequencing until the decision is
 implemented. Current architecture, user, operator, integration, and internal
 documentation are updated when the behavior lands.
 
-`docs/roadmap/deferred.md` owns deliberate exclusions; task-specific plans
+`docs/roadmap/future.md` owns potential enhancements and their open questions;
-own execution order and progress. Completed plans retire during release
+task-specific plans own execution order and progress. Record significant
-preparation.
+architectural exclusions and their rationale in ADRs. Do not maintain a roadmap
+inventory of rejected proposals. Completed plans retire during release preparation.
 
 ### Audience And Detail
 
@@ -91,7 +92,7 @@ secret values.
 | Inventory of implemented internal packages | `docs/internal/overview.md` | Implemented packages and components, responsibilities, and links to focused internal docs. | Normative architecture, contributor reading policy, external contracts. |
 | Behavior and architecture of internal packages | Other files under `docs/internal/` | Implementation flow, collaborators, state transitions, package-local guarantees and failures, and relevant tests. | Global architecture invariants, configuration definitions and defaults, external schemas, operator procedures. |
 | Architectural decision records | `docs/adr/` | Significant decisions, context, alternatives, rationale, consequences, and supersession history. | Current behavior reference, implementation status, task sequencing. |
-| Deferred scope | `docs/roadmap/deferred.md` | Deliberate exclusions and conditions for reconsideration. | Task execution and current behavior. |
+| Potential future features | `docs/roadmap/future.md` | Candidate enhancements and open questions for future consideration. | Rejected proposals, architectural decisions, task execution, and current behavior. |
 | Future implementation plans | Task-specific files under `docs/roadmap/` | Unfinished work, sequencing, acceptance, and progress; completed plans retire during release preparation. | Implemented behavior and ADR rationale. |
 | Release-note history | `docs/releases/` | One checked-in summary per source release under the procedure; the note at its immutable tag is the release record. | Current commands, behavior, contracts, and compatibility definitions. |
 | Complete examples | `examples/` and executable Go examples | Maintained copyable artifacts and Go API examples. | Configuration reference, symbol contracts, and prose explanation. |
@@ -156,8 +157,10 @@ Use sequentially numbered ADR filenames such as
 
 Treat the decision content of an accepted ADR as immutable. When a decision
 changes, create a new ADR and update the earlier ADR's status to superseded.
-Rejected architectural alternatives belong in the ADR; rejected product ideas
+Rejected architectural alternatives and significant architectural exclusions
-belong in the roadmap. Routine choices need no ADR.
+belong in ADRs. Roadmaps preserve plausible future work, not rejected product
+ideas. Routine choices and rejected suggestions need no ADR unless they
+represent a significant architectural decision.
 
 ## Maintenance
 

docs/policy/release.md

@@ -1,10 +1,10 @@
 # Release Policy
 
-**Base Policy Version:** 1.4
+**Base Policy Version:** 1.6
 
-**Last Updated**: 2026-09-28
+**Last Updated**: 2026-10-09
 
-**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/d84a38ebab26f048cafbe59a2246700c35d29843/docs/policy/release.md)
+**Upstream Source:** [Standard Repository Policies](https://gitea.maximumdirect.net/eric/policy/src/commit/e833faddf120c789a9b45348edaf75720de16348/docs/policy/release.md)
 
 ## Purpose
 
@@ -12,6 +12,9 @@ This policy defines a proportionate workflow for validating and publishing an
 intended source revision under a fresh version. Releases should require little
 routine intervention, avoid repeated work, and preserve published contents.
 
+Adopt stronger verification or reproducibility requirements through an explicit
+project-specific decision justified by the intended audience and support needs.
+
 The repository-specific commands belong in `docs/release.md`. Historical release
 summaries belong in `docs/releases/`. The procedure must agree with the adopted
 policy and link to it rather than introduce additional release requirements.
@@ -54,10 +57,11 @@ authoritative primary branch, completes the release. The source commit may be
 pushed before the tag or published together with it through an atomic push.
 The procedure must choose and document the supported approach.
 
-ConfigKit uses sequential explicit pushes: first the captured candidate to
+ConfigKit uses sequential publication: first push the committed candidate to
-authoritative `main`, then the annotated tag. Its
+authoritative `main`, then invoke ReleaseKit once to validate that candidate and
-[release procedure](../release.md) names `origin` and checks that its fetch and
+publish its annotated tag. The [release procedure](../release.md) names
-push destinations resolve to the authoritative URL.
+`origin`; ReleaseKit checks its exact effective push URL before validation and
+tag publication.
 
 Release commands must finish at successful publication. They must not wait for
 or poll CI, require successful CI status, inspect downloadable artifacts, or
@@ -76,8 +80,9 @@ the tagged source. The procedure must identify those deliverables and the
 responsibility of their automation. Published deliverables must be traceable
 to that source and identify the same version.
 
-ConfigKit currently declares no additional deliverables. Its source-tag push
+ConfigKit currently declares no additional deliverables. Confirmed publication
-is the completion point.
+of the intended source tag is the completion point. CI, macOS validation,
+hosted delivery, and consumer retrieval are outside the release gates.
 
 ## Versioning And Compatibility
 
@@ -96,7 +101,8 @@ requires a deliberate update to the policy and procedure where needed.
 For releases at or after `v1.0.0`:
 
 - a major release may make intentional incompatible changes;
-- a minor release may add backward-compatible behavior; and
+- a minor release may add backward-compatible behavior or raise the Go consumer
+  minimum as described below; and
 - a patch release may make backward-compatible fixes.
 
 Before `v1.0.0`, a minor release may change a documented public, operational,
@@ -108,13 +114,53 @@ Additional compatibility promises and deliberate exceptions belong in the
 adopted policy or canonical contract documentation. Release notes explain
 changes; they do not redefine current compatibility contracts.
 
+## Consumer Minimum And Release Toolchain
+
+Distinguish the minimum toolchain supported for consumers from the toolchain
+maintainers use to build and validate a release. Record the consumer minimum in
+the language's standard metadata and explain its support meaning in canonical
+documentation. Define the selected release toolchain and its setup commands in
+`docs/release.md`. Toolchain selection and upgrade cadence are repository-specific
+choices.
+
+For Go repositories, normally declare the initial stable release of the selected
+series as the consumer minimum, such as `go 1.26.0`. Use a higher patch minimum
+when a dependency or an identified correctness fix requires it, and document
+the reason.
+
+For release-policy purposes, successful build and release validation on the
+selected Go patch release are sufficient to presume support across that Go
+series, subject to the declared consumer minimum and concrete evidence of
+incompatibility. Investigate specific compatibility concerns as they arise.
+
+Use the selected release toolchain for candidate validation and release builds,
+including CI jobs performing those tasks. A newer validation patch version alone
+leaves the consumer minimum unchanged.
+
+A minor release may raise the Go consumer minimum, including from one Go series
+to the next, both before and after `v1.0.0`. This is an explicit exception to the
+backward-compatibility requirement for minor releases. Patch releases preserve
+the consumer minimum. Explain an increase's impact and required consumer action
+in the release note. Other incompatible changes remain subject to the versioning
+rules above.
+
+### ConfigKit Toolchain Selection
+
+For minor and major releases, select the newest stable Go series available in
+the development environment. For patch releases, retain the series recorded in
+`go.mod` and its consumer minimum. Use the latest locally available compatible
+patch in the selected series, with `GOTOOLCHAIN=local`, to build the
+module-selected ReleaseKit CLI and validate the candidate. The same Go
+executable builds the tool and runs its validation commands.
+
 ## Release Documentation And Preparation
 
 Every new release must include `docs/releases/<version>.md` in the tagged
 source tree. Use the complete version tag as the filename and begin with a
 title containing the product name and that exact version.
 
-ConfigKit requires the first line `# ConfigKit <version>`.
+ConfigKit requires the first line `# ConfigKit <version>`. ReleaseKit's
+publication guard checks the release-note H1 for the product and version.
 
 Include a short summary and any relevant compatibility impact or upgrade
 instructions. Choose sections suited to the release and keep the note
@@ -146,10 +192,9 @@ checks publication state, and publishes the intended refs. A validation-only
 mode or command may be provided for diagnosis, but must not be a required step
 before publication repeats the same checks.
 
-ConfigKit uses `./scripts/release.sh vMAJOR.MINOR.PATCH`. The separate
+ConfigKit uses the module-selected ReleaseKit CLI's `publish
-`scripts/release-check.sh` remains an optional diagnostic command; the
+vMAJOR.MINOR.PATCH` command. Its `check` command is optional for diagnosis; it
-publication command invokes it once and does not use a persistent candidate
+is not a required preliminary pass to publication.
-record.
 
 Run the complete deterministic, offline default test suite once for the final
 candidate, following the [testing policy](testing.md). For repositories that
@@ -157,13 +202,17 @@ publish builds, verify the required build targets. Select those targets for
 the application's actual support commitments; native testing on each platform
 and access to particular hardware are not default release prerequisites.
 
-ConfigKit's one maintained Go 1.25 baseline runs the full suite with the race
+Prepare dependencies and build the tool before offline validation; the
-detector and test-time vet disabled. This protects library behavior, ownership,
+publication command is the required validation run, with no separate successful
-and concurrent use; the suite already includes examples, consumer fixtures,
+test or CI run required before it.
-documentation links, and package boundaries. One full vet pass adds static
+
-checks beyond the test-time subset. CGO-disabled Linux amd64 and arm64 builds
+The selected profile runs the complete deterministic, offline default suite
-cover supported configurations distinct from native race compilation. macOS
+once with the race detector and test-time vet disabled. The suite already
-and newer-toolchain checks are optional.
+includes examples, consumer fixtures, documentation links, and package
+boundaries. One full vet pass adds static checks beyond the test-time subset.
+CGO-disabled Linux amd64 and arm64 package compilation covers supported
+configurations distinct from native race compilation. macOS and newer-toolchain
+checks are optional.
 
 Additional gates must address a concrete risk that the existing checks do not
 adequately cover. Do not automatically require linting, race testing, module
@@ -172,9 +221,10 @@ expanded platform matrices solely because they are possible. Retain such
 checks when their distinct protection justifies their cost. A one-time migration
 check must not silently become a permanent release requirement.
 
-The selected Go commands use readonly module mode with `GOPROXY=off`; acquire
+ReleaseKit runs its selected Go commands with readonly module mode and
-the baseline toolchain and dependencies before validation. Formatting and
+`GOPROXY=off`; acquire dependencies and build the tool before candidate
-whitespace remain ordinary development checks in `scripts/check.sh`.
+validation. Formatting and whitespace remain ordinary development checks in
+`scripts/check.sh`.
 Review module tidiness when dependencies change, not as a release gate.
 
 Release tests must not require real credentials, mutable application services,
@@ -206,16 +256,19 @@ Automate the checks needed to publish the intended source under a fresh version:
   authoritative remote;
 - the worktree and index are clean on the primary release branch;
 - the source being published is the exact candidate that passed validation,
-  including its matching release note;
+  including its matching release note H1;
 - the remote primary branch can be advanced to that candidate without
   discarding remote history, and is published before the tag; and
 - the tag identifies the validated candidate and only the intended refs are
   published.
 
-ConfigKit also checks that `origin` has exactly the authoritative fetch and
+ReleaseKit checks that `origin`'s effective push URL exactly matches the
-push destination, including configured push URLs. The command checks the
+authoritative URL before candidate validation. This does not assert the
-candidate and unused version again after validation, and checks local state
+configured fetch URL or require the release-note H1 to be the first line; the
-before creating the tag. Ignored local files do not block publication.
+required `# ConfigKit <version>` first-line format remains a content rule. The
+command checks the candidate and unused version again after validation, and
+checks local state before creating the tag. Ignored local files do not block
+publication.
 
 Fetch the authoritative branch and tag state as needed for these checks.
 Do not force branch or tag updates to bypass a failed guard. Publish explicit
@@ -248,10 +301,10 @@ release without replacing its contents or reusing its version.
 ## Repository Release Procedure
 
 Maintain `docs/release.md` as a short, executable maintainer runbook. It must
-identify prerequisites, the primary branch and authoritative remote, version
+identify prerequisites, the selected release toolchain, the primary branch and
-and note preparation, one publication command with local checks and guards,
+authoritative remote, version and note preparation, one publication command with
-source-only deliverables, the successful-tag-push completion point, and
+local checks and guards, source-only deliverables, the successful-tag-push
-partial or unknown-state recovery.
+completion point, and partial or unknown-state recovery.
 
 Use copyable commands where practical. Keep optional diagnostics and consumer
 verification clearly optional. The procedure must not turn preparation work,

docs/release.md

@@ -1,7 +1,7 @@
 # ConfigKit Release Procedure
 
 This is the maintainer runbook for ConfigKit's [release policy](policy/release.md).
-ConfigKit publishes one source-only Go module. The immutable annotated tag and
+ConfigKit publishes a source-only Go module. The immutable annotated tag and
 matching checked-in release note are the deliverables; there is no binary,
 container image, generated package, or separate registry publication.
 
@@ -9,183 +9,221 @@ container image, generated package, or separate registry publication.
 
 - Module: `gitea.maximumdirect.net/eric/ConfigKit`
 - Primary branch: `main`
-- Authoritative remote: `origin`, with fetch and push destination
+- Authoritative remote: `origin`
-  `https://gitea.maximumdirect.net/eric/ConfigKit.git`
+- Authoritative push URL: `https://gitea.maximumdirect.net/eric/ConfigKit.git`
 - Tags: stable Semantic Versions such as `v0.5.0`; no prereleases
-- Minimum Go line: Go 1.25, validated with one maintained patch
+- Minimum Go version: the first stable patch of the selected Go series, or a
+  higher patch when required by a dependency or specific correctness fix, as
+  recorded in `go.mod`; see the
+  [consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain)
 - Release-gated targets: Linux amd64 and arm64
 - Best-effort targets: macOS amd64 and arm64, under the
   [platform support policy](policy/release.md#platform-support)
 
-The checker runs one offline race suite, one full vet pass, and CGO-disabled
+Release validation runs one offline race-enabled Go suite, one full vet pass,
-builds for both Linux targets. It reports skipped filesystem cases. macOS checks
+and CGO-disabled package compilation for both Linux targets. macOS and CI are
-and newer-toolchain tests are optional. CI is never a readiness or completion
+not release gates; do not wait for or poll CI.
-gate; do not wait for or poll it.
 
-## 1. Prepare access and tools
+## 1. Select Go and prepare the tool
 
-Use a clean checkout with Git, Bash 3.2 or newer, a maintained Go 1.25 patch,
+Use a clean checkout with Git, Bash 3.2 or newer, and a native compiler for race
-and a native compiler for race tests. Configure private-host access through the
+tests. Choose the release type before selecting Go. For a minor or major release,
-normal credential manager. Keep credentials and environment dumps outside the
+select the newest stable Go series available in the development environment.
-repository and command transcript.
+For a patch release, retain the series recorded in `go.mod` and leave its consumer
+minimum unchanged. Follow the
+[toolchain selection policy](policy/release.md#configkit-toolchain-selection).
 
-Verify access without displaying credentials:
+Put the selected series' latest locally available compatible patch first on
+`PATH`, ensuring it meets `go.mod`'s minimum. The same `go` executable must build
+ReleaseKit and run its child validation commands. Set local toolchain selection
+and verify it:
 
 ```sh
-git remote get-url origin
+export GOTOOLCHAIN=local
-git ls-remote origin HEAD
+go version
+go env GOVERSION
+command -v go
 ```
 
-The fetch URL and all configured push destinations must resolve to the
+Only when a minor or major release advances the consumer minimum to a newer Go
-authoritative URL above. The publication command checks this again. Acquire the
+series, derive that series' initial stable release from the selected executable:
-selected toolchain and dependencies explicitly before offline validation:
 
 ```sh
-export CONFIGKIT_BASELINE_TOOLCHAIN=go1.25.14
+selected_go=$(GOTOOLCHAIN=local go env GOVERSION)
-GOTOOLCHAIN="$CONFIGKIT_BASELINE_TOOLCHAIN" go version
+selected_series=${selected_go#go}
-GOTOOLCHAIN="$CONFIGKIT_BASELINE_TOOLCHAIN" go mod download
+selected_series=${selected_series%.*}
+release_minimum="$selected_series.0"
+go mod edit -go="$release_minimum"
 ```
 
-A maintained patch may replace the example pin. No per-release latest-version
+If a dependency or identified correctness fix requires a higher patch minimum,
-survey is required. Dependencies must be cached; the checker sets `GOPROXY=off`.
+use that required version instead and document the reason. When the series is
-Publication requires user authorization. Standing authorization for local
+unchanged, leave the minimum unchanged unless a minor or major release
-commits does not authorize a push or release.
+deliberately changes it under the
+[consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).
+For example, validating with Go 1.26.8 leaves `go 1.26.0` unchanged. There is no
+separate requirement to validate with Go 1.26.0.
 
-## 2. Select the version and review compatibility
+Prepare dependencies whether or not the minimum changes:
 
-Choose an unused stable version. Compare the candidate with the previous tag.
+```sh
-Review exported Go signatures and ownership, YAML and scalar semantics,
+go mod download
-precedence, diagnostic codes, minimum Go version, and platform support. A
+```
-signature-preserving change may still affect consumers. Before `v1.0.0`,
-intentional incompatible minor-release changes need a note explaining impact
-and consumer action; patch releases remain compatible within their minor line.
-Review the maintained consumer examples and migration guide.
 
-When dependencies change, review parser behavior and migration impact as part
+Build the tool selected by `go.mod` into temporary storage outside the checkout.
-of that change. Module tidiness belongs to dependency-change review, not the
+Ensure `$TMPDIR` names a system temporary location, not the repository. These
-release checker. Do not repeat a dependency-version survey for every release.
+commands never install another ReleaseKit version:
 
-## 3. Write and commit the release note
+```sh
+releasekit_tmp=$(mktemp -d "${TMPDIR:-/tmp}/configkit-releasekit.XXXXXX")
+releasekit_bin="$releasekit_tmp/releasekit"
+go build -o "$releasekit_bin" gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit
+go list -m gitea.maximumdirect.net/eric/ReleaseKit
+"$releasekit_bin" version
+```
 
-Create `docs/releases/<version>.md` for the selected version. Its first line
+The module-selected executable is ReleaseKit v0.4.1. Use the built executable
-must be `# ConfigKit <version>`. Give a meaningful summary and include
+for publication to preserve its exit status and publication-state diagnostics.
-compatibility impact or upgrade instructions when applicable. Link to current
+`go run` maps a nonzero child exit status to 1. ReleaseKit's child Go commands
-contracts for exact behavior. Review the note and affected canonical documents
+use the `go` found on `PATH` with `GOTOOLCHAIN=local`; keep the selected
-as ordinary preparation, then commit the complete candidate.
+executable first on `PATH` through the publication command.
 
-End every new note with these links, replacing `VERSION` with the complete tag:
+Verify access to the authoritative remote without displaying credentials:
+
+```sh
+git ls-remote https://gitea.maximumdirect.net/eric/ConfigKit.git HEAD refs/heads/main
+```
+
+Publication requires explicit authorization. Local implementation commits do
+not authorize a push or release.
+
+## 2. Prepare and commit the candidate
+
+Choose an unused stable version locally and on the authoritative remote. Compare
+the candidate with the previous tag and review exported Go signatures and
+ownership, YAML and resolution semantics, diagnostic contracts, minimum Go
+version, and platform support. Review maintained consumer examples and the
+migration guidance. Explain any consumer-minimum increase and required consumer
+action under the
+[consumer minimum policy](policy/release.md#consumer-minimum-and-release-toolchain).
+
+Create `docs/releases/<version>.md`. Its first line must be exactly
+`# ConfigKit <version>`, and it must end with the license and attribution footer:
 
 ```markdown
 [COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/VERSION/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/VERSION/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/VERSION/docs/oss/attribution.md)
 ```
 
-Confirm the three target files exist in the candidate and review the version in
+Replace `VERSION` with the full tag and confirm the three target files exist in
-the URLs. The future tag need not resolve remotely yet; this review adds no
+the candidate. Retire completed roadmaps, preserve unfinished and deferred
-network gate. ConfigKit uses checked-in notes without hosted release objects.
+work, and repair affected links. Review the complete candidate for unintended
-If a hosted page is used later, reuse the note and preserve its footer. Do not
+files and credentials, then commit it on `main`. These are ordinary preparation
-rewrite historical notes or add downloadable license assets.
+tasks, not separate approval gates. Any `go.mod` change belongs in this
+candidate.
+
+## 3. Push the candidate to `main`
+
+Push only that committed candidate to the literal authoritative URL. This does
+not follow local tags:
+
+```sh
+git push --no-follow-tags https://gitea.maximumdirect.net/eric/ConfigKit.git HEAD:refs/heads/main
+```
+
+ReleaseKit requires authoritative `main` to equal this candidate before it
+validates. A failure before this push means ReleaseKit publication has not
+started. If the push result is uncertain, inspect authoritative `main` and
+continue only when it is confirmed at the candidate. If validation later fails,
+no release tag is published; correct the issue in a new commit, push the new
+candidate to `main`, and invoke validation again.
 
 ## 4. Publish the committed candidate
 
-Before publication, review compatibility, release-note accuracy, and the file
+With the authorized candidate already on authoritative `main`, invoke the
-list for unintended content or credentials. Retire completed roadmaps as part of
+module-selected native executable exactly once:
-release preparation, preserving unfinished and deferred work and repairing
-links. These are ordinary preparation tasks, not separate human sign-offs.
-
-With the release explicitly authorized, run the one publication command.
-The script resolves the repository root from its own path, so it may be invoked
-from another directory by using its path there. Replace the sample version with
-the selected version:
 
 ```sh
-./scripts/release.sh v0.5.0
+"$releasekit_bin" publish vMAJOR.MINOR.PATCH
 ```
 
-The command requires `main`, a clean index/worktree, an unused version locally
+Replace the placeholder with the selected version. ReleaseKit checks the
-and on the authoritative remote, and a matching note in the captured commit.
+effective push URL against `expected_push_url`, verifies the candidate on
-Ignored local files do not block it. It checks remote ancestry, runs
+`main`, and checks the release-note H1 for the product and version. It then
-[`release-check.sh`](../scripts/release-check.sh) once against that commit,
+runs the selected race-enabled standard suite once with test-time vet disabled,
-rechecks candidate and version state, pushes only that commit to `main`, then
+one full vet pass, and CGO-disabled package compilation for Linux amd64 and
-creates and pushes one annotated tag. The tag message is the checked-in note.
+arm64. It publishes only the annotated tag for that candidate. Confirmed
-It never commits or repairs the checkout.
+publication of the intended tag completes the release. The tag points to the
-
+captured commit and uses the complete checked-in note as its annotation message.
-A successful intended tag push completes publication. The command reports the
+The optional `check`
-version and commit immediately. No CI, module retrieval, remote read-back, or
+command is available for diagnosis but is not a separate required pass:
-hosted release object is required. The checker may be run separately for
-diagnosis, but it is not a prerequisite: a fresh publication invocation
-validates its candidate once.
-
-## 5. Recover from a failed or uncertain push
-
-The command performs one bounded authoritative-state check after a failed push.
-If the main push failed but authoritative main equals the candidate, it proceeds.
-If the tag push failed but its exact tag object reached the remote, it reports
-success. Otherwise it reports branch-only, conflicting, or unknown state and
-retains any local tag.
-
-Inspect exact refs before any retry. Set `release_version` to the attempted
-version and compare main with the candidate from the command's report:
 
 ```sh
-release_version=v0.5.0
+"$releasekit_bin" check vMAJOR.MINOR.PATCH
-authoritative=https://gitea.maximumdirect.net/eric/ConfigKit.git
-if remote_main=$(git ls-remote --refs --exit-code "$authoritative" refs/heads/main); then
-  printf 'remote main: %s\n' "$remote_main"
-else
-  result=$?
-  if [ "$result" -eq 2 ]; then
-    printf 'authoritative main confirmed absent\n' >&2
-  else
-    printf 'remote main state unknown; inspect before retrying\n' >&2
-  fi
-fi
-ref="refs/tags/$release_version"
-if remote_tag=$(git ls-remote --refs --exit-code "$authoritative" "$ref"); then
-  printf 'remote tag: %s\n' "$remote_tag"
-else
-  result=$?
-  if [ "$result" -eq 2 ]; then
-    printf 'remote tag confirmed absent\n'
-  else
-    printf 'remote tag state unknown; do not reuse the version\n' >&2
-  fi
-fi
-if local_tag=$(git rev-parse --verify "refs/tags/$release_version" 2>/dev/null); then
-  printf 'local tag object: %s\n' "$local_tag"
-else
-  printf 'no local tag object\n'
-fi
 ```
 
-A query failure is not proof that the tag is absent. Compare the remote tag
+Status 0 confirms publication, status 1 reports a known publication failure or
-object ID with the local annotated tag object ID; its peeled commit alone is
+conflict, status 2 reports usage, profile, or version errors, and status 3 means
-insufficient to establish identical publication. A conflicting published tag
+the push outcome remains unknown. Preserve both the native exit status and its
-must not be moved or replaced. If remote main advanced but the tag was not
+diagnostics.
-published, report that partial progress. Only after confirming the local tag
+
-was never published or used by another channel may a maintainer remove it:
+The command does not push or repair `main`, wait for CI, or publish binaries or
+a hosted release page. A successful intended-tag publication does not require
+remote read-back or consumer retrieval; those checks remain optional.
+
+## 5. Recover from a failed or uncertain tag push
+
+The executable reports the publication state, phase, version, candidate commit,
+tag-object ID, effective endpoint, and error on standard error. It performs one
+bounded authoritative reconciliation after a failed tag push. Exit status 3
+means the tag outcome remains unknown; do not blindly retry or move a tag.
+
+For an uncertain result, use the exact endpoint, candidate commit, version, and
+tag-object ID from the report. Copy the captured endpoint into the variable
+below using normal shell quoting. Check that Git still resolves it to itself,
+then query the authoritative refs once:
+
+```sh
+authoritative='COPY_CAPTURED_ENDPOINT'
+release_version='vMAJOR.MINOR.PATCH'
+test "$(git ls-remote --get-url -- "$authoritative")" = "$authoritative" &&
+  git ls-remote --refs -- "$authoritative" refs/heads/main "refs/tags/$release_version"
+```
+
+A failed URL-equality check or remote query leaves the outcome unresolved.
+Correct transport configuration before continuing; a rewritten destination
+cannot establish absence at the captured endpoint.
+
+Compare the `main` object ID with the reported candidate commit and the tag
+object ID with the reported tag-object ID. `--refs` returns the annotated tag
+object itself, not merely its peeled commit. If the tag object matches, the
+release is published. If the query fails, the result is conflicting, or the
+endpoint or candidate differs, stop and resolve the state before retrying. If
+the endpoint is reachable, the tag is confirmed absent, and `main` still equals
+the reported candidate, remove a retained local tag only after confirming it
+was not published or used by another channel; then rerun `publish`, which
+revalidates the candidate:
 
 ```sh
 git tag -d "$release_version"
+"$releasekit_bin" publish "$release_version"
 ```
 
-A subsequent invocation revalidates the candidate; a correctly published tag
+A validation failure after the candidate reached `main` leaves an untagged
-needs no rerun. Do not roll back main or automatically delete a tag. Transport
+candidate there. Correct it with a new commit rather than rewriting or rolling
-or authentication failure alone does not require a new version. A defect in
+back `main`. A conflicting published tag must never be moved or reused. A
-published source requires a corrected commit, a new semantically appropriate
+defect in published source requires a corrected commit, a new semantically
-version and note, and the release procedure again.
+appropriate version, and a matching release note.
 
 ## 6. Optional consumer verification
 
-Only when useful or requested, read back the remote tag or retrieve the exact
+When useful or requested, read back the remote tag or retrieve the exact
-version into a new module without a local `replace` directive. These checks
+version into a new module without a local `replace` directive. These checks are
-are optional and non-gating. Do not poll CI or wait for module propagation.
+optional and non-gating. Do not poll CI or wait for module propagation. For
-Private-host credentials must already be configured. For direct-origin
+direct-origin verification, use the exact published version in a temporary
-verification, set the version to the release just published (replace the sample
+consumer module:
-below), then use a temporary consumer module and check the exact module path
-and version reported by `go list -m`:
 
 ```sh
-release_version=v0.5.0
+release_version=vMAJOR.MINOR.PATCH
 consumer_dir=$(mktemp -d)
 (
   cd "$consumer_dir"

docs/releases/v0.6.0.md

@@ -0,0 +1,63 @@
+# ConfigKit v0.6.0
+
+This minor release reduces avoidable configuration-loading and inspection work,
+adopts ReleaseKit for source publication, and raises the consumer Go minimum to
+1.26.0. The public configuration model remains unchanged from v0.5.0.
+
+## Changes
+
+- Reduce temporary path allocations by sizing pointer-formatting buffers,
+  combining final metadata traversal, reusing parsed sensitivity paths, and
+  avoiding path construction when detecting inheritance. Effective and
+  historical metadata indexes retain independently owned paths.
+- Replace repeated resolution-coverage, metadata-update, CLI-overlap, and
+  sensitivity-propagation scans with private indexes and incremental processing.
+  Preserve diagnostic ordering, history, contextual path shapes, and redaction.
+- Make presence-only metadata queries avoid materializing provenance. Prepare
+  resolution replay descriptors and immutable mapping and inheritance-history
+  lookups for inspection, and use ordered membership indexes for provenance
+  collections. Returned records remain detached; explanations still replay
+  complete trees and render on demand.
+- Add a maintained public-API startup construction benchmark. The initial path
+  formatting and metadata traversal experiments reproduced allocation reductions
+  across local and downstream workloads. Later algorithmic improvements were
+  validated behaviorally without a new benchmark campaign. Busy-host timings
+  were inconclusive; no fixed speedup or allocation threshold is promised.
+- Replace ConfigKit-owned release scripts with a small profile and the
+  module-selected ReleaseKit v0.3.0 tool. The
+  [release procedure](../release.md) documents candidate preparation, tag-only
+  publication, and failed-push recovery. Existing release checks and the
+  successful-tag-push completion point remain unchanged; CI is not a gate.
+- Adopt release policy 1.6, distinguishing the consumer Go minimum from the
+  validation toolchain. Retire completed planning and measurement records into
+  Git history while preserving [performance candidates](../roadmap/future.md#3-performance-experiments).
+
+## Compatibility and upgrade
+
+The consumer minimum increases from Go 1.25.0 to **Go 1.26.0**. Install Go 1.26.0
+or newer before upgrading, and update application build and CI environments that
+still use Go 1.25. The `go.mod` directive records the consumer minimum; using a
+newer validation patch does not itself raise that minimum. See the
+[consumer minimum policy](../policy/release.md#consumer-minimum-and-release-toolchain).
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.6.0
+```
+
+No application-code or configuration migration is required from v0.5.0. Public
+Go signatures, strict within-tier composition, recursive tier precedence,
+sibling inheritance, presence/null distinctions, provenance, secret handling,
+and synchronous completion retain their existing contracts. See the
+[configuration contract](../config.md) and
+[consumer guide](../consumers/README.md).
+
+The YAML dependency remains `go.yaml.in/yaml/v4 v4.0.0-rc.6`. ReleaseKit is a
+declared Go tool dependency for maintainer commands, not a library runtime
+import; its requirements participate in ConfigKit's module graph. Linux amd64
+and arm64 remain release-validated targets, and macOS remains best-effort.
+Maintainers should use the current release procedure instead of the retired
+`scripts/release.sh` and `scripts/release-check.sh` commands.
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.6.0/docs/oss/attribution.md)

docs/releases/v0.7.0.md

@@ -0,0 +1,58 @@
+# ConfigKit v0.7.0
+
+This minor release adds structured comparison of completed configurations.
+Applications can inspect changes between two configuration files or the
+effective impact of a selected overlay, with ConfigKit handling comparison and
+safe value disclosure while applications own presentation.
+
+## Changes
+
+- Add `Diff[T](left, right *Result[T]) ([]Difference, error)` through the public
+  facade. It compares frozen effective inspection values from successful loads,
+  including defaults and recorded application resolution, rather than source
+  text or later mutations of `Result.Config`.
+- Return detached changed-region records containing a semantic path, safe left
+  and right `ValueSnapshot` values, and `HiddenChanged`. Mappings compare
+  recursively, sequences report atomic changes, and records follow canonical
+  pointer order. Presence distinguishes additions and removals from explicit
+  null; equal effective values produce no records regardless of provenance or
+  loading history.
+- Protect both snapshots with sensitivity from both loads, including historical
+  and dependency-derived classification. Compatible regions retain public
+  siblings; incompatible structural replacements use complete-region masking
+  where required. `HiddenChanged` identifies actual changes withheld by masking,
+  rather than merely indicating that a snapshot contains redacted content.
+- Preserve visible public scalar changes when only historical sensitive
+  descendants remain, including additions and removals. Historical explanation
+  redaction and masking of incompatible present shapes remain intact.
+- Add maintained file-comparison and base-versus-overlay examples with
+  consumer-owned formatting, plus an executable public API example. See the
+  [consumer guide](../consumers/README.md#effective-configuration-diffs) and
+  [configuration contract](../config.md#effective-configuration-diffs).
+
+## Compatibility and upgrade
+
+No application-code or configuration migration is required from v0.6.0.
+Adopting the new API is optional. Loading, composition, inheritance, provenance,
+existing inspection, and secret-handling contracts remain unchanged.
+
+Load both configurations successfully before calling `Diff`; nil or
+uninitialized results return an error with no records. Comparison does not
+reopen sources, rerun callbacks, or reread environment variables. Typed secret
+references compare by configured reference name, not resolved credential bytes,
+so credential rotation behind an unchanged name is not reported. Returned
+snapshots describe changed regions, not cross-protected full-document context.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.7.0
+```
+
+The consumer minimum remains Go 1.26.0. The YAML dependency remains
+`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
+ReleaseKit v0.3.0. Linux amd64 and arm64 remain release-validated targets;
+macOS remains best-effort. Publication follows the existing
+[release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.0/docs/oss/attribution.md)

docs/releases/v0.7.1.md

@@ -0,0 +1,22 @@
+# ConfigKit v0.7.1
+
+This patch updates the maintainer release tool to ReleaseKit v0.4.1. ConfigKit's
+runtime behavior and public API are unchanged.
+
+## Compatibility and upgrade
+
+No application-code or configuration migration is required from v0.7.0. The
+consumer minimum remains Go 1.26.0, and the YAML dependency is unchanged.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.7.1
+```
+
+ReleaseKit v0.4.1 is a maintainer tool dependency and does not change consumer
+configuration or runtime behavior. Linux amd64 and arm64 remain
+release-validated targets; macOS remains best-effort. Publication follows the
+existing [release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.7.1/docs/oss/attribution.md)

docs/releases/v0.8.0.md

@@ -0,0 +1,70 @@
+# ConfigKit v0.8.0
+
+This minor release adds explicit input placement, relative import destinations,
+shared source-version checking, and opt-in composition of identified sequence
+records. Applications can assemble independently authored configuration fragments
+into one final configuration while retaining source locations, provenance,
+history, and sensitivity information.
+
+## Changes
+
+- Add `Destination` to ordinary load options and layered inputs. A source mapping
+  can contribute beneath literal application keys without being rewritten by the
+  consumer. Imports inherit that destination or append a relative YAML
+  `destination`. Physical import paths and resource contexts remain relative to
+  their declaring sources. See [input destinations](../config.md#input-destinations),
+  [import syntax](../config.md#explicit-imports), and the
+  [mounted collection example](../consumers/README.md#input-destinations-and-mounted-collections).
+- Add `SourceVersionModeIfPresent` and `SourceVersionModeRequired` to apply one
+  application-owned version checker across main, underlay, imported, and selected
+  overlay documents. Enabled modes check source-local declarations and consume
+  accepted non-main headers before composition. Detached, sensitivity-aware
+  evidence is available through `SourceInfo.VersionCheck`. Acceptance remains
+  application policy; ConfigKit does not require declarations to equal the main
+  version. See [shared source-version checks](../config.md#shared-source-version-checks).
+- Add explicit `PlacementModeSequenceItem` placement for ordinary and layered
+  inputs, and `placement: sequence-item` for path and glob imports. A source
+  mapping becomes one item at its destination; ordinary helper imports compose
+  within that item and can supply its identity. See
+  [imports](../config.md#explicit-imports).
+- Add `Definition.SequenceCompositions` registrations for strict composition at
+  selected literal paths using one string identity field. Distinct records append
+  in contribution order, while duplicate identities conflict. Higher-priority
+  sequences still replace lower-priority sequences wholesale. Registration does
+  not add identity-based overlays or final identity validation after defaults and
+  application resolution. See the [composition contract](../config.md#strict-document-composition)
+  and [maintained prompt catalog](../consumers/README.md#identified-prompt-sequences).
+- Extend source inspection with destination and placement evidence, including
+  whether a nested destination is unresolved in an intermediate or failed-load
+  snapshot. Preserve source-specific history, consumed-header sensitivity, and
+  explanations of descendants removed by sequence replacement as records are
+  assembled. Source locations continue to identify authored coordinates.
+
+## Compatibility and upgrade
+
+The new behavior is opt-in: zero-valued destinations retain root placement,
+mapping placement remains the default, unregistered sequences retain strict
+conflict behavior, and the default source-version mode preserves the existing
+main-only version policy. Recursive mapping precedence, whole-sequence
+replacement between tiers, and application-owned final validation remain intact.
+
+Public option, definition, input, and source-information structs gain fields.
+Consumers using unkeyed literals for affected structs must switch to keyed
+literals or update them. `SourceInfo` now contains a `Path` and is no longer
+comparable with `==` or usable directly as a map key; compare the relevant fields
+or select an application-appropriate key instead. Existing keyed literals need
+no changes to retain the previous loading behavior.
+
+Select this version and rebuild:
+
+```sh
+go get gitea.maximumdirect.net/eric/ConfigKit@v0.8.0
+```
+
+The consumer minimum remains Go 1.26.0. The YAML dependency remains
+`go.yaml.in/yaml/v4 v4.0.0-rc.6`, and the maintainer tool dependency remains
+ReleaseKit v0.4.1. Linux amd64 and arm64 remain release-validated targets;
+macOS remains best-effort. Publication follows the existing
+[release procedure](../release.md).
+
+[COPYRIGHT](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/COPYRIGHT) | [LICENSE](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/LICENSE) | [ATTRIBUTION](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.8.0/docs/oss/attribution.md)

docs/roadmap/deferred.md

@@ -1,34 +0,0 @@
-# Deferred Scope
-
-This document owns intentionally excluded features, not a committed delivery plan.
-The [architecture policy](../policy/architecture.md) governs changes to these
-boundaries. Implemented behavior belongs in the [configuration contract](../config.md)
-and consumer adoption in the [consumer guide](../consumers/README.md).
-
-## Explicit non-goals and deferred scope
-
-General environment-variable configuration overlays are not supported. Typed secret
-references and explicit directory bootstrap are the environment convention. Literal
-credential configuration and implicit secret-directory discovery are unsupported.
-
-The following remain deliberately excluded:
-
-- automatic `conf.d` discovery;
-- remote imports, arbitrary providers, and additional configuration formats;
-- custom merge strategies, sequence merging, reset operators, multiple-parent
-  inheritance, and cross-scope references;
-- named overlay inheritance;
-- parser-specific or custom structural-decoding extension APIs;
-- generic dynamic-subtree conversion and module-registry APIs;
-- automatic schema migrations;
-- hot reload, runtime resource replacement, and remote resource validation;
-- a bundled CLI framework or application commands; and
-- configuration diffs and fingerprints.
-
-Applications may build their own validate, effective-value, source, bootstrap, and
-explanation commands around the library. Broadening these boundaries requires
-concrete consumer evidence, compatibility review, and an explicit design change.
-
-Built-in sibling inheritance using `extends` is implemented as described in the
-[configuration contract](../config.md#sibling-inheritance). It is distinct from
-inheritance between selected overlay files, which remains excluded above.

docs/roadmap/future.md

@@ -0,0 +1,171 @@
+# Potential Future Features
+
+This document lists potential enhancements for consideration in future ConfigKit
+releases. Entries are not accepted contracts, implementation plans, or release
+commitments. Adopting a candidate requires an explicit design decision and a
+separate plan. Significant architectural exclusions and their rationale belong
+in ADRs; this document does not maintain a list of rejected proposals.
+
+## 1. Identified record sequences
+
+Status: deferred. PromptKit proposed this capability from its retired proposal 2,
+**Namespaced Collections As Identified Records**. The original proposal is in the
+PromptKit repository at
+`b5866dd:docs/roadmap/configuration-collections-identified-records.md`.
+PromptKit selected mounted mappings instead; this feature is not a dependency
+of that design or a request to restore multiple installed prompt versions.
+
+A narrower [sequence placement and composition feature](../config.md#strict-document-composition)
+is implemented: consumers can place imported mappings as sequence items and
+register a single literal string identity field for duplicate-rejecting strict
+composition. Precedence still replaces sequences as whole values. This entry
+tracks broader identified-record behavior that remains deferred and is not part
+of that implemented contract.
+
+### Motivation and proposed behavior
+
+Allow applications to declare that selected sequences contain records identified
+by explicit fields, while retaining sequence-shaped output for slice decoding
+and effective YAML. This could make composite identities and independently
+authored catalogs more convenient than encoding identity in nested mapping keys.
+Current [composition](../config.md#strict-document-composition) appends distinct
+records only at explicitly registered paths; other sequences remain atomic.
+Selected [overlays](../config.md#selected-overlays) always treat sequences
+atomically.
+
+The proposed broader opt-in registration would extend the current reusable
+application definition from one identity field to a composite identity made of
+an ordered, nonempty set of distinct direct string-field names. For example,
+records at `profiles` could be identified by `(namespace, id)`. Records
+`(provider, brief)`
+and `(application, brief)` would coexist, and a later layer could update the
+provider record's temperature while retaining its backend and model.
+
+The requested semantics, all still subject to design review, are:
+
+- Match exact string tuples, preserving component boundaries and spelling,
+  including empty strings. Every contribution supplies its complete identity;
+  defaults, inheritance, filenames, and normalization do not supply it.
+- Retain distinct identities. Matching records from strict peers recursively
+  compose disjoint body fields and conflict on overlapping non-mapping body
+  values, even equal values. Equal identity fields act as structural keys rather
+  than conflicts and retain their contributing source evidence.
+- Higher layers recursively overlay matching bodies. A changed identity denotes
+  a different record, not a rename. Proposed ordering is first contribution in
+  precedence-assembly order; matching records keep position and new ones append.
+- Reject malformed identities, non-mapping records, non-null non-sequence values
+  at registered paths, and duplicate tuples within one source sequence. Later
+  layers cannot repair malformed structural identity in an acquired contribution.
+- Treat an empty registered sequence as contributing no records; whole-path null
+  retains ordinary conflict/replacement semantics. Unregistered sequences,
+  including nested message lists, retain existing atomic behavior.
+- Support record inheritance within the same registered sequence using an
+  `extends` mapping containing the complete parent tuple. Resolve only final
+  active relationships after precedence, preserve the child's identity, overlay
+  its body on the parent's body, and consume the directive before decoding.
+  Preserve cancellation, missing-parent/cycle errors, and declaring resource
+  contexts. Existing string-based mapping-sibling inheritance stays unchanged.
+
+Integrate ordinary and layered loads, imports, mounted paths, selected overlays,
+and whole-sequence CLI overrides. Keep origins, presence, history, sensitivity,
+and resource contexts attached to the correct record despite different source
+and final indexes. Diagnostics must retain source locations without exposing
+sensitive identity values. Final inspection may use snapshot-specific sequence
+indexes; existing atomic sequence diffs need not become identity-aware.
+
+Successful results would have valid, unique identities, including after defaults
+and application resolution, without a second merge or inheritance pass. Existing
+source-version checks remain independent; consumed headers cannot supply missing
+record identities. No identity-selector path syntax, arbitrary merge callbacks,
+wildcard registration, per-record deletion/rename operator, multiple inheritance,
+or cross-path parent references are requested.
+
+### Questions to resolve before implementation
+
+- **Need and delivery scope:** does an active consumer benefit enough to justify
+  the added semantics over keyed mappings? Are composite identities required?
+  Staging composition before inheritance is possible but would leave part of
+  the request incomplete.
+- **Defaults and callbacks:** do default records merge by identity or retain
+  existing sequence-replacement behavior? How are callback-created duplicates,
+  identity edits, and reordering validated and reflected in provenance?
+- **Null, empty, and order:** what happens when null clears a collection and a
+  later layer reintroduces records? How do absent and explicitly empty sequences
+  interact with defaults and first-contribution order?
+- **Inheritance references:** how do peers compose relationship declarations,
+  and how are complete references enforced without assembling partial tuples
+  accidentally? What happens if identity fields overlap structural controls?
+- **Registration paths:** how do overlapping registrations and paths beneath
+  sequence indexes behave when assembly changes those indexes?
+- **Evidence and lifecycle:** how are record identities mapped between source
+  trees, history, inheritance, callback snapshots, and final indexes without
+  mixing records' provenance or sensitivity? Where do identity checks run relative
+  to header consumption and other structural processing?
+
+Keep the feature deferred until its consumer value and full lifecycle design
+justify reconsidering the sequence-merging exclusion. A correct final sequence
+alone would not establish correct inspection or disclosure behavior.
+
+## 2. Required version declarations for selected sources
+
+Status: deferred. PromptKit requested a way to require version declarations on
+a selected subset of source files while permitting other fragments to omit them.
+
+### Motivation and proposed behavior
+
+PromptKit could require each collection's root file (for example,
+`collection.yml` or `meta.yml`, with naming still undecided) to declare an
+accepted specification version. Other files would use the existing
+[check-when-present behavior](../config.md#shared-source-version-checks).
+This would enforce a rule that otherwise remains a documentation convention.
+
+All declarations would use the same application-owned `Definition.Version`
+path and acceptance policy. The proposal concerns where declarations are
+required; it does not introduce independently versioned collections or subtrees.
+A root declaration would not prove that headerless descendants declare a
+compatible version or replace final configuration validation.
+
+### Questions to resolve before implementation
+
+- **Selection API:** should callers mark explicit inputs, select sources by
+  path or predicate, or annotate imports? An input-level requirement is simpler,
+  but cannot by itself select a root reached only through an import.
+- **Scope:** does a requirement apply only to the selected document or also to
+  its imports? Applying it only to that document best fits PromptKit's request;
+  imported fragments could still declare versions checked by the shared policy.
+- **Mode interaction:** how should selection interact with disabled source
+  checks? Require an enabled mode, or activate checking for selected sources?
+  Selection would strengthen check-when-present behavior and add no requirement
+  beyond the load-wide required mode.
+- **Source handling and evidence:** how should selection work across file,
+  reader, byte, and mapping inputs, glob matches, and repeated imports? Define
+  behavior for absent optional inputs and preserve source-local diagnostics,
+  inspection evidence, and existing sensitivity handling.
+
+## 3. Performance experiments
+
+Status: deferred pending evidence. The completed performance audit identified
+four internal optimization candidates for separate investigation:
+
+- Branch-local explanation replay instead of the current whole-tree replay.
+- Redesigning the private metadata-copy handoff while preserving detached public
+  records.
+- Caching schema descriptors across loads.
+- Indexing complex contributor-trace membership while preserving its equality
+  rules and compact linked traces.
+
+These are experiments, not committed implementation work or promised speedups.
+Reconsider them with evidence that the benefit justifies the ownership,
+retained-memory, or equivalence risks. The completed audit and implementation
+evidence are preserved in Git history at `8e91a2b` under `docs/roadmap/`.
+
+### Questions to resolve before implementation
+
+- Which representative workloads show enough remaining cost to justify each
+  optimization, and what measurements would establish a useful improvement?
+- Can narrower replay and membership indexes preserve explanation results,
+  ordering, provenance, and sensitivity behavior?
+- Can metadata handoff changes preserve detached public records and ownership
+  across loads without introducing aliasing?
+- What cache lifetime and concurrency design would make schema reuse worthwhile
+  without excessive retained memory?

example_test.go

@@ -30,6 +30,32 @@ func ExampleNoSource() {
 	// Output: 4 0 <nil>
 }
 
+func ExampleDiff() {
+	type Config struct {
+		Workers int `yaml:"workers"`
+	}
+	before, err := configkit.Load[Config](configkit.Mapping("before", map[string]any{"workers": 2}))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	after, err := configkit.Load[Config](configkit.Mapping("after", map[string]any{"workers": 4}))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	differences, err := configkit.Diff(before, after)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	for _, difference := range differences {
+		fmt.Printf("%s: %s -> %s\n", difference.Path.String(),
+			strings.TrimSpace(difference.Left.YAML), strings.TrimSpace(difference.Right.YAML))
+	}
+	// Output: /workers: 2 -> 4
+}
+
 func ExampleValidation_Error() {
 	type Config struct {
 		First  string `yaml:"first"`

examples/consumers/destinations.go

@@ -0,0 +1,154 @@
+package consumers
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"path"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+// CollectionBundleConfig is a representative application-owned collection
+// shape. Collection and prompt version labels remain ordinary domain fields.
+type CollectionBundleConfig struct {
+	Version     string                          `yaml:"version"`
+	Collections map[string]CollectionDefinition `yaml:"collections"`
+}
+
+type CollectionDefinition struct {
+	Name        string                       `yaml:"name"`
+	Version     string                       `yaml:"version"`
+	Description string                       `yaml:"description"`
+	Prompts     map[string]CollectionPrompt  `yaml:"prompts"`
+	Profiles    map[string]CollectionProfile `yaml:"profiles"`
+}
+
+type CollectionPrompt struct {
+	Version        string              `yaml:"version"`
+	DefaultProfile string              `yaml:"default_profile"`
+	ContentFile    string              `yaml:"content_file"`
+	ResourceText   string              `yaml:"resource_text"`
+	Messages       []CollectionMessage `yaml:"messages"`
+}
+
+type CollectionMessage struct {
+	Role    string `yaml:"role"`
+	Content string `yaml:"content"`
+}
+
+type CollectionProfile struct {
+	Format      string  `yaml:"format"`
+	Temperature float64 `yaml:"temperature"`
+}
+
+// LoadCollectionBundle demonstrates one layered collection load. Its main
+// document owns the application schema version; the mounted entry declares
+// relative destinations for collection metadata, prompt/profile peers, and
+// their nested imports. The operator version override remains a separate tier.
+func LoadCollectionBundle() (*configkit.Result[CollectionBundleConfig], error) {
+	files, err := fs.Sub(bundledFiles, "testdata/collection-bundle")
+	if err != nil {
+		return nil, err
+	}
+	bundle := configkit.NewFilesystem("collection bundle", files)
+	collectionDestination := configkit.Keys("collections", "weatherreporter")
+	promptDestination := collectionDestination.Key("prompts")
+	return configkit.LoadLayered(
+		configkit.Input{Source: configkit.Bytes("application main", []byte("version: 1\n"))},
+		configkit.LayeredOptions[CollectionBundleConfig]{
+			Definition: configkit.Definition[CollectionBundleConfig]{
+				Version: &configkit.VersionRule{Path: configkit.Keys("version"), Check: func(version configkit.Version, _ *configkit.Validation) error {
+					if !version.Present || version.Text != "1" {
+						return errors.New("unsupported application schema version")
+					}
+					return nil
+				}},
+				Resolve:  resolveCollectionResources,
+				Validate: validateCollectionBundle,
+			},
+			Underlays: []configkit.Underlay{
+				{Inputs: []configkit.Input{{
+					Source: bundle.File("collections/weather/collection.yml"), Imports: true, Destination: collectionDestination,
+				}}},
+				{Inputs: []configkit.Input{{
+					Source: bundle.File("operators/weather-prompt-version.yml"), Destination: promptDestination,
+				}}},
+			},
+		},
+	)
+}
+
+func resolveCollectionResources(configuration *CollectionBundleConfig, resolution *configkit.Resolution) error {
+	for collectionID, collection := range configuration.Collections {
+		for promptID, prompt := range collection.Prompts {
+			if prompt.ContentFile == "" {
+				continue
+			}
+			contentPath := configkit.Keys("collections", collectionID, "prompts", promptID, "content_file")
+			info, found := resolution.InputInfo(contentPath)
+			if !found || len(info.Origin.Locations) != 1 {
+				return fmt.Errorf("prompt resource has no single declaring source")
+			}
+			resourceSource, found := resolution.Source(info.Origin.Locations[0].SourceID)
+			if !found {
+				return fmt.Errorf("prompt resource source is unavailable")
+			}
+			context, found := resolution.SourceContext(resourceSource.ID)
+			if !found {
+				return fmt.Errorf("prompt resource context is unavailable")
+			}
+			data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, prompt.ContentFile))
+			if err != nil {
+				return fmt.Errorf("read prompt resource: %w", err)
+			}
+			prompt.ResourceText = string(data)
+			collection.Prompts[promptID] = prompt
+			resolution.Record(
+				configkit.Keys("collections", collectionID, "prompts", promptID, "resource_text"),
+				configkit.ChangeNormalization, "read source-relative prompt content", contentPath,
+			)
+		}
+		configuration.Collections[collectionID] = collection
+	}
+	return nil
+}
+
+func validateCollectionBundle(configuration *CollectionBundleConfig, validation *configkit.Validation) {
+	for collectionID, collection := range configuration.Collections {
+		for promptID, prompt := range collection.Prompts {
+			if prompt.DefaultProfile == "" {
+				continue
+			}
+			if _, found := collection.Profiles[prompt.DefaultProfile]; !found {
+				validation.Error(configkit.Keys("collections", collectionID, "prompts", promptID, "default_profile"), "must name a profile in this collection")
+			}
+		}
+	}
+}
+
+// ReadCollectionPromptContent follows the effective content field's physical
+// source, including when it was inherited from a peer prompt.
+func ReadCollectionPromptContent(result *configkit.Result[CollectionBundleConfig], collectionID, promptID string) (string, error) {
+	if result == nil {
+		return "", errors.New("collection result is nil")
+	}
+	contentPath := configkit.Keys("collections", collectionID, "prompts", promptID, "content_file")
+	info, found := result.Metadata().Lookup(contentPath)
+	if !found || len(info.Origin.Locations) != 1 {
+		return "", errors.New("prompt resource has no single declaring source")
+	}
+	context, found := result.SourceContext(info.Origin.Locations[0].SourceID)
+	if !found {
+		return "", errors.New("prompt resource context is unavailable")
+	}
+	prompt, found := result.Config.Collections[collectionID].Prompts[promptID]
+	if !found {
+		return "", errors.New("prompt is unavailable")
+	}
+	data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, prompt.ContentFile))
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}

examples/consumers/destinations_test.go

@@ -0,0 +1,137 @@
+package consumers_test
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+)
+
+func Example_inputDestination() {
+	mounted, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.Mapping("weather prompt", map[string]any{
+			"summarize.alerts": map[string]any{"version": "1"},
+		}),
+		Destination: configkit.Keys("collections", "weather.reporter", "prompts"),
+	})
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	root, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.Bytes("standalone", []byte("name: standalone\n")),
+	})
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	_, found := mounted.Config["collections"]
+	fmt.Println(found, root.Config["name"])
+	// Output: true standalone
+}
+
+func TestCollectionBundleAssemblesMountedPeersAndResources(t *testing.T) {
+	result, err := consumers.LoadCollectionBundle()
+	if err != nil {
+		t.Fatalf("LoadCollectionBundle: %v", err)
+	}
+	collection := result.Config.Collections["weatherreporter"]
+	if result.Config.Version != "1" || collection.Name != "Weather Reporter" || collection.Version != "2.4.0" {
+		t.Fatalf("main and collection versions = %q, %#v", result.Config.Version, collection)
+	}
+	brief := collection.Prompts["brief"]
+	custom := collection.Prompts["custom"]
+	if brief.Version != "2" || brief.DefaultProfile != "compact" || brief.ContentFile != "welcome.txt" || len(brief.Messages) != 1 {
+		t.Fatalf("version-only override replaced lower prompt fields: %#v", brief)
+	}
+	if custom.Version != "2" || custom.DefaultProfile != "weather" || custom.ContentFile != brief.ContentFile ||
+		len(custom.Messages) != 1 || custom.ResourceText != "Welcome to the weather collection.\n" {
+		t.Fatalf("inherited prompt = %#v", custom)
+	}
+	weatherProfile := collection.Profiles["weather"]
+	if weatherProfile.Format != "text" || weatherProfile.Temperature != 0.4 {
+		t.Fatalf("inherited profile = %#v", weatherProfile)
+	}
+	resource, err := consumers.ReadCollectionPromptContent(result, "weatherreporter", "custom")
+	if err != nil || resource != custom.ResourceText {
+		t.Fatalf("inherited prompt resource = %q, %v", resource, err)
+	}
+
+	versionInfo, ok := result.Metadata().Lookup(configkit.Keys("version"))
+	if !ok || !versionInfo.Explicit || versionInfo.Origin.Layer != configkit.LayerBase || len(versionInfo.Origin.Locations) != 1 {
+		t.Fatalf("main-owned version metadata = %#v, %v", versionInfo, ok)
+	}
+	collectionVersionPath := configkit.Keys("collections", "weatherreporter", "version")
+	collectionVersion, ok := result.Metadata().Lookup(collectionVersionPath)
+	if !ok || !collectionVersion.Explicit || collectionVersion.Origin.Layer != configkit.LayerUnderlay || len(collectionVersion.Origin.Locations) != 1 {
+		t.Fatalf("ordinary collection version metadata = %#v, %v", collectionVersion, ok)
+	}
+	var metadataSource configkit.SourceInfo
+	var collectionEntrySource configkit.SourceInfo
+	var versionSource configkit.SourceInfo
+	var parentPromptSource configkit.SourceInfo
+	var promptIndexSource configkit.SourceInfo
+	var profileIndexSource configkit.SourceInfo
+	var promptVersionSource configkit.SourceInfo
+	for _, source := range result.Sources() {
+		switch source.Path {
+		case "collections/weather/collection.yml":
+			collectionEntrySource = source
+		case "collections/weather/metadata.yml":
+			metadataSource = source
+		case "collections/weather/version.yml":
+			versionSource = source
+		case "collections/weather/prompts/index.yml":
+			promptIndexSource = source
+		case "collections/weather/prompts/brief.yml":
+			parentPromptSource = source
+		case "collections/weather/profiles/index.yml":
+			profileIndexSource = source
+		case "operators/weather-prompt-version.yml":
+			promptVersionSource = source
+		}
+	}
+	collectionVersionLocation := collectionVersion.Origin.Locations[0]
+	if collectionEntrySource.ID != "source-2" || collectionEntrySource.Destination.String() != "/collections/weatherreporter" ||
+		metadataSource.ID == "" || metadataSource.Destination.String() != "/collections/weatherreporter" ||
+		metadataSource.ImportedFrom == nil || metadataSource.ImportedFrom.SourceID != collectionEntrySource.ID ||
+		versionSource.ID == "" || collectionVersionLocation.SourceID != versionSource.ID || versionSource.Destination.String() != "/collections/weatherreporter" ||
+		versionSource.ImportedFrom == nil || versionSource.ImportedFrom.SourceID != metadataSource.ID || collectionVersionLocation.Line != 1 {
+		t.Fatalf("nested collection version provenance = entry %#v, metadata %#v, version %#v, location %#v", collectionEntrySource, metadataSource, versionSource, collectionVersionLocation)
+	}
+	if promptIndexSource.ID == "" || promptIndexSource.Destination.String() != "/collections/weatherreporter/prompts" ||
+		promptIndexSource.ImportedFrom == nil || promptIndexSource.ImportedFrom.SourceID != collectionEntrySource.ID ||
+		profileIndexSource.ID == "" || profileIndexSource.Destination.String() != "/collections/weatherreporter/profiles" ||
+		profileIndexSource.ImportedFrom == nil || profileIndexSource.ImportedFrom.SourceID != collectionEntrySource.ID {
+		t.Fatalf("nested prompt/profile placement = prompt %#v profile %#v", promptIndexSource, profileIndexSource)
+	}
+	if promptVersionSource.ID == "" || promptVersionSource.Destination.String() != "/collections/weatherreporter/prompts" || promptVersionSource.UnderlayIndex != 2 {
+		t.Fatalf("prompt version source = %#v", promptVersionSource)
+	}
+	contentPath := configkit.Keys("collections", "weatherreporter", "prompts", "custom", "content_file")
+	contentInfo, ok := result.Metadata().Lookup(contentPath)
+	if !ok || !contentInfo.Explicit || len(contentInfo.Origin.Inheritance) != 1 || len(contentInfo.Origin.Locations) != 1 {
+		t.Fatalf("inherited content field metadata = %#v, %v", contentInfo, ok)
+	}
+	contentLocation := contentInfo.Origin.Locations[0]
+	if parentPromptSource.ID == "" || contentLocation.SourceID != parentPromptSource.ID || contentLocation.Line != 4 ||
+		parentPromptSource.Destination.String() != "/collections/weatherreporter/prompts" {
+		t.Fatalf("inherited resource source coordinates = %#v, source %#v", contentLocation, parentPromptSource)
+	}
+}
+
+func TestCollectionPeerPromptConflictsRemainStrict(t *testing.T) {
+	destination := configkit.Keys("collections", "weatherreporter", "prompts")
+	_, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+			{Source: configkit.Bytes("peer-a", []byte("brief: {version: '1'}\n")), Destination: destination},
+			{Source: configkit.Bytes("peer-b", []byte("brief: {version: '1'}\n")), Destination: destination},
+		}}},
+	})
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeComposeConflict {
+		t.Fatalf("duplicate peer prompt error = %v", err)
+	}
+}

examples/consumers/diff.go

@@ -0,0 +1,136 @@
+package consumers
+
+import (
+	"fmt"
+	"strconv"
+	"strings"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+// FileComparisonConfig is a small application-owned shape for comparing
+// caller-selected configuration files.
+type FileComparisonConfig struct {
+	Name    string         `yaml:"name"`
+	Entries map[string]any `yaml:"entries"`
+}
+
+// CompareFiles loads two caller-selected files with the same application
+// definition, then formats only the safe records returned by configkit.Diff.
+func CompareFiles(leftPath, rightPath string) (string, error) {
+	options := configkit.Options[FileComparisonConfig]{
+		Definition: configkit.Definition[FileComparisonConfig]{
+			Defaults: func() FileComparisonConfig {
+				return FileComparisonConfig{Entries: map[string]any{}}
+			},
+		},
+	}
+	left, err := configkit.Load(configkit.File(leftPath), options)
+	if err != nil {
+		return "", fmt.Errorf("load left configuration: %w", err)
+	}
+	right, err := configkit.Load(configkit.File(rightPath), options)
+	if err != nil {
+		return "", fmt.Errorf("load right configuration: %w", err)
+	}
+	differences, err := configkit.Diff(left, right)
+	if err != nil {
+		return "", err
+	}
+	return FormatDifferences(differences), nil
+}
+
+// RolloutConfig models a service endpoint whose URL is derived by the
+// application resolver and whose credential reference is classified.
+type RolloutConfig struct {
+	Service RolloutService `yaml:"service"`
+}
+
+// RolloutService contains endpoint settings and a classified credential.
+type RolloutService struct {
+	Endpoint   RolloutEndpoint   `yaml:"endpoint"`
+	Credential RolloutCredential `yaml:"credential"`
+}
+
+// RolloutEndpoint is the effective destination used by the application.
+type RolloutEndpoint struct {
+	Host string `yaml:"host"`
+	Port int    `yaml:"port"`
+	URL  string `yaml:"url"`
+}
+
+// RolloutCredential holds only a typed secret reference in configuration.
+type RolloutCredential struct {
+	Token configkit.Secret `yaml:"token" configkit:"secret"`
+}
+
+// LoadRollout loads a base file, optionally with one selected configuration
+// overlay. Resolution derives the effective URL after the overlay is applied.
+func LoadRollout(basePath, overlayName string) (*configkit.Result[RolloutConfig], error) {
+	return configkit.Load(configkit.File(basePath), configkit.Options[RolloutConfig]{
+		Overlay: overlayName,
+		Definition: configkit.Definition[RolloutConfig]{
+			Resolve: resolveRollout,
+		},
+	})
+}
+
+// CompareRolloutOverlay compares the effective base configuration with that
+// same file plus one selected overlay. It presents only safe diff records.
+func CompareRolloutOverlay(basePath, overlayName string) (string, error) {
+	base, err := LoadRollout(basePath, "")
+	if err != nil {
+		return "", fmt.Errorf("load base configuration: %w", err)
+	}
+	withOverlay, err := LoadRollout(basePath, overlayName)
+	if err != nil {
+		return "", fmt.Errorf("load overlay configuration: %w", err)
+	}
+	differences, err := configkit.Diff(base, withOverlay)
+	if err != nil {
+		return "", err
+	}
+	return FormatDifferences(differences), nil
+}
+
+func resolveRollout(configuration *RolloutConfig, resolution *configkit.Resolution) error {
+	endpoint := &configuration.Service.Endpoint
+	if endpoint.Host == "" || endpoint.Port <= 0 {
+		return nil
+	}
+	url := fmt.Sprintf("https://%s:%d", endpoint.Host, endpoint.Port)
+	if endpoint.URL != url {
+		endpoint.URL = url
+		resolution.Record(configkit.Keys("service", "endpoint", "url"),
+			configkit.ChangeNormalization, "derived endpoint URL",
+			configkit.Keys("service", "endpoint", "host"),
+			configkit.Keys("service", "endpoint", "port"))
+	}
+	return nil
+}
+
+// FormatDifferences is consumer-owned presentation. It distinguishes absence
+// through Present and reports withheld changes through HiddenChanged without
+// interpreting redaction marker text.
+func FormatDifferences(differences []configkit.Difference) string {
+	if len(differences) == 0 {
+		return "No effective changes.\n"
+	}
+	var output strings.Builder
+	for _, difference := range differences {
+		fmt.Fprintf(&output, "%s: left=%s right=%s", difference.Path.String(),
+			formatSnapshot(difference.Left), formatSnapshot(difference.Right))
+		if difference.HiddenChanged {
+			output.WriteString(" hidden-change")
+		}
+		output.WriteByte('\n')
+	}
+	return output.String()
+}
+
+func formatSnapshot(snapshot configkit.ValueSnapshot) string {
+	if !snapshot.Present {
+		return "<absent>"
+	}
+	return strconv.Quote(snapshot.YAML)
+}

examples/consumers/diff_test.go

@@ -0,0 +1,187 @@
+package consumers_test
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+)
+
+func ExampleCompareFiles() {
+	directory, err := os.MkdirTemp("", "configkit-diff-files-")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(directory)
+	leftPath := filepath.Join(directory, "before.yml")
+	rightPath := filepath.Join(directory, "after.yml")
+	if err := os.WriteFile(leftPath, []byte("name: before\nentries: {}\n"), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := os.WriteFile(rightPath, []byte("name: after\nentries:\n  added: null\n"), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	output, err := consumers.CompareFiles(leftPath, rightPath)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Print(output)
+	// Output:
+	// /entries/added: left=<absent> right="null\n"
+	// /name: left="before\n" right="after\n"
+}
+
+func ExampleCompareRolloutOverlay() {
+	const baseToken = "CONFIGKIT_DIFF_EXAMPLE_BASE_TOKEN"
+	const overlayToken = "CONFIGKIT_DIFF_EXAMPLE_OVERLAY_TOKEN"
+	defer preserveEnvironment(baseToken)()
+	defer preserveEnvironment(overlayToken)()
+	_ = os.Setenv(baseToken, "disposable-example-base-credential")
+	_ = os.Setenv(overlayToken, "disposable-example-overlay-credential")
+
+	directory, err := os.MkdirTemp("", "configkit-diff-overlay-")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	defer os.RemoveAll(directory)
+	basePath := filepath.Join(directory, "config.yml")
+	overlayPath := filepath.Join(directory, "overlays", "canary.yml")
+	if err := os.MkdirAll(filepath.Dir(overlayPath), 0o700); err != nil {
+		fmt.Println(err)
+		return
+	}
+	base := "service:\n  endpoint:\n    host: base.example\n    port: 8443\n  credential:\n    token: " + baseToken + "\n"
+	overlay := "service:\n  endpoint:\n    host: canary.example\n  credential:\n    token: " + overlayToken + "\n"
+	if err := os.WriteFile(basePath, []byte(base), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	if err := os.WriteFile(overlayPath, []byte(overlay), 0o600); err != nil {
+		fmt.Println(err)
+		return
+	}
+	output, err := consumers.CompareRolloutOverlay(basePath, "canary")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Print(output)
+	// Output:
+	// /service/credential/token: left="'[REDACTED]'\n" right="'[REDACTED]'\n" hidden-change
+	// /service/endpoint/host: left="base.example\n" right="canary.example\n"
+	// /service/endpoint/url: left="https://base.example:8443\n" right="https://canary.example:8443\n"
+}
+
+func TestCompareFilesUsesCallerSelectedSourcesAndSafePresence(t *testing.T) {
+	directory := t.TempDir()
+	leftPath := filepath.Join(directory, "before.yml")
+	rightPath := filepath.Join(directory, "after.yml")
+	writeConfiguration(t, leftPath, "name: before\nentries: {}\n")
+	writeConfiguration(t, rightPath, "name: after\nentries:\n  added: null\n")
+
+	output, err := consumers.CompareFiles(leftPath, rightPath)
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := "/entries/added: left=<absent> right=\"null\\n\"\n" +
+		"/name: left=\"before\\n\" right=\"after\\n\"\n"
+	if output != want {
+		t.Fatalf("comparison output = %q, want %q", output, want)
+	}
+	if again, err := consumers.CompareFiles(leftPath, rightPath); err != nil || again != output {
+		t.Fatalf("repeat output = %q, %v", again, err)
+	}
+}
+
+func TestCompareFilesReturnsEachLoadError(t *testing.T) {
+	directory := t.TempDir()
+	leftPath := filepath.Join(directory, "before.yml")
+	rightPath := filepath.Join(directory, "after.yml")
+	writeConfiguration(t, leftPath, "name: before\n")
+	writeConfiguration(t, rightPath, "unknown: invalid\n")
+
+	output, err := consumers.CompareFiles(leftPath, rightPath)
+	if err == nil || output != "" || !strings.Contains(err.Error(), "load right configuration") {
+		t.Fatalf("right load failure = %q, %v", output, err)
+	}
+	if _, err := consumers.CompareFiles(filepath.Join(directory, "missing.yml"), rightPath); err == nil || !strings.Contains(err.Error(), "load left configuration") {
+		t.Fatalf("left load failure = %v", err)
+	}
+}
+
+func TestCompareRolloutOverlayShowsResolvedSafeChangesAndRetainsSiblings(t *testing.T) {
+	t.Setenv("CONFIGKIT_DIFF_BASE_TOKEN", "disposable-base-credential")
+	t.Setenv("CONFIGKIT_DIFF_OVERLAY_TOKEN", "disposable-overlay-credential")
+	directory := t.TempDir()
+	basePath := filepath.Join(directory, "config.yml")
+	overlayPath := filepath.Join(directory, "overlays", "canary.yml")
+	if err := os.MkdirAll(filepath.Dir(overlayPath), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	writeConfiguration(t, basePath, "service:\n  endpoint:\n    host: base.example\n    port: 8443\n  credential:\n    token: CONFIGKIT_DIFF_BASE_TOKEN\n")
+	writeConfiguration(t, overlayPath, "service:\n  endpoint:\n    host: canary.example\n  credential:\n    token: CONFIGKIT_DIFF_OVERLAY_TOKEN\n")
+
+	base, err := consumers.LoadRollout(basePath, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	withOverlay, err := consumers.LoadRollout(basePath, "canary")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if base.Config.Service.Endpoint.Port != 8443 || withOverlay.Config.Service.Endpoint.Port != 8443 {
+		t.Fatalf("lower-priority port was not retained: base=%#v overlay=%#v", base.Config.Service.Endpoint, withOverlay.Config.Service.Endpoint)
+	}
+	urlInfo, found := withOverlay.Metadata().Lookup(configkit.Keys("service", "endpoint", "url"))
+	if !found || urlInfo.Origin.Layer != configkit.LayerResolution || withOverlay.Config.Service.Endpoint.URL != "https://canary.example:8443" {
+		t.Fatalf("resolved endpoint = %#v, metadata=%#v, %v", withOverlay.Config.Service.Endpoint, urlInfo, found)
+	}
+
+	differences, err := configkit.Diff(base, withOverlay)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 3 {
+		t.Fatalf("differences = %#v", differences)
+	}
+	wantPaths := []string{"/service/credential/token", "/service/endpoint/host", "/service/endpoint/url"}
+	for index, difference := range differences {
+		if got := difference.Path.String(); got != wantPaths[index] {
+			t.Errorf("path[%d] = %q, want %q", index, got, wantPaths[index])
+		}
+	}
+	secret := differences[0]
+	if !secret.Left.Redacted || !secret.Right.Redacted || !secret.HiddenChanged || secret.Left.YAML != "'[REDACTED]'\n" || secret.Right.YAML != "'[REDACTED]'\n" {
+		t.Fatalf("classified credential difference = %#v", secret)
+	}
+	if strings.Contains(consumers.FormatDifferences(differences), "disposable-") {
+		t.Fatal("formatted differences exposed credential contents")
+	}
+
+	output, err := consumers.CompareRolloutOverlay(basePath, "canary")
+	if err != nil || output != consumers.FormatDifferences(differences) {
+		t.Fatalf("formatted base/overlay comparison = %q, %v", output, err)
+	}
+}
+
+func TestFormatDifferencesUsesRecordMembershipForNoChange(t *testing.T) {
+	if got := consumers.FormatDifferences(nil); got != "No effective changes.\n" {
+		t.Fatalf("no-change output = %q", got)
+	}
+}
+
+func writeConfiguration(t *testing.T, filename, contents string) {
+	t.Helper()
+	if err := os.WriteFile(filename, []byte(contents), 0o600); err != nil {
+		t.Fatal(err)
+	}
+}

examples/consumers/layered.go

@@ -9,7 +9,7 @@ import (
 	configkit "gitea.maximumdirect.net/eric/ConfigKit"
 )
 
-//go:embed testdata/native-source testdata/layered-bundle
+//go:embed testdata/native-source testdata/layered-bundle testdata/collection-bundle testdata/ordinary-imports testdata/source-version
 var bundledFiles embed.FS
 
 // BundledConfig is a small configuration loaded directly from an embedded file.
@@ -18,6 +18,30 @@ type BundledConfig struct {
 	Enabled bool   `yaml:"enabled"`
 }
 
+type PromptBundleConfig struct {
+	Name        string                  `yaml:"name"`
+	Version     string                  `yaml:"version"`
+	Description string                  `yaml:"description"`
+	Prompts     map[string]BundlePrompt `yaml:"prompts"`
+}
+
+type BundlePrompt struct {
+	Summary string `yaml:"summary"`
+}
+
+// LoadPromptBundle demonstrates ordinary Load with opt-in imports whose
+// destinations are declared relative to the entry document.
+func LoadPromptBundle() (*configkit.Result[PromptBundleConfig], error) {
+	files, err := fs.Sub(bundledFiles, "testdata/ordinary-imports")
+	if err != nil {
+		return nil, err
+	}
+	return configkit.Load[PromptBundleConfig](
+		configkit.NewFilesystem("prompt bundle", files).File("config.yml"),
+		configkit.Options[PromptBundleConfig]{Imports: true},
+	)
+}
+
 // LoadBundled demonstrates a native filesystem source without layered options.
 func LoadBundled() (*configkit.Result[BundledConfig], error) {
 	files, err := fs.Sub(bundledFiles, "testdata/native-source")

examples/consumers/layered_test.go

@@ -20,6 +20,34 @@ func Example_nativeFilesystem() {
 	// Output: embedded false
 }
 
+func Example_rootRelativeImports() {
+	result, err := consumers.LoadPromptBundle()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	source := result.Sources()[2]
+	fmt.Println(result.Config.Name, result.Config.Version, result.Config.Prompts["brief"].Summary, source.Destination.String(), err)
+	// Output: Root import example 1.0 A root-loaded prompt. /prompts <nil>
+}
+
+func TestPromptBundleUsesRelativeImportDestinations(t *testing.T) {
+	result, err := consumers.LoadPromptBundle()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Config.Name != "Root import example" || result.Config.Version != "1.0" || result.Config.Prompts["brief"].Summary != "A root-loaded prompt." {
+		t.Fatalf("root import result = %#v", result.Config)
+	}
+	sources := result.Sources()
+	if len(sources) != 3 || sources[0].Destination.String() != configkit.Keys().String() ||
+		sources[1].Path != "metadata.yml" || sources[1].Destination.String() != configkit.Keys().String() ||
+		sources[2].Path != "prompts/brief.yml" || sources[2].Destination.String() != "/prompts" ||
+		sources[2].ImportedFrom == nil || sources[2].ImportedFrom.SourceID != sources[0].ID {
+		t.Fatalf("root import sources = %#v", sources)
+	}
+}
+
 func Example_layeredCatalog() {
 	result, err := consumers.LoadCatalog(fixture("layered-main", "config.yml"))
 	if err != nil {
@@ -32,6 +60,58 @@ func Example_layeredCatalog() {
 	// Output: production false 0 bundle example Welcome from the bundle. <nil>
 }
 
+func Example_sourceVersionAdoption() {
+	result, err := consumers.LoadVersionedService(configkit.SourceVersionModeIfPresent)
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	checks, redacted := 0, true
+	for _, source := range result.Sources() {
+		if check := source.VersionCheck; check != nil {
+			checks++
+			redacted = redacted && check.Redacted && check.Version.Text == ""
+		}
+	}
+	required, requiredErr := consumers.LoadVersionedService(configkit.SourceVersionModeRequired)
+	fmt.Println(result.Config.Service.Version, result.Config.Service.Metadata.Release,
+		checks, redacted, required != nil && requiredErr == nil)
+	// Output: service-v2 application-2026.10 2 true true
+}
+
+func TestVersionedServiceModesAndMountedProtection(t *testing.T) {
+	for _, mode := range []configkit.SourceVersionMode{
+		configkit.SourceVersionModeIfPresent,
+		configkit.SourceVersionModeRequired,
+	} {
+		result, err := consumers.LoadVersionedService(mode)
+		if err != nil || result == nil || result.Config.Service.Version != "service-v2" ||
+			result.Config.Service.Name != "example service" || result.Config.Service.Endpoint != "https://service.example.invalid" ||
+			result.Config.Service.Metadata.Release != "application-2026.10" {
+			t.Fatalf("versioned service mode %d = %#v, %v", mode, result, err)
+		}
+		sources := result.Sources()
+		if len(sources) != 2 {
+			t.Fatalf("versioned service sources = %#v", sources)
+		}
+		for _, source := range sources {
+			check := source.VersionCheck
+			if check == nil || check.Path.String() != "/version" || !check.Version.Present ||
+				!check.Redacted || check.Version.Text != "" {
+				t.Fatalf("safe source version evidence = %#v", sources)
+			}
+		}
+	}
+	_, err := consumers.LoadVersionedService(configkit.SourceVersionModeIfPresent,
+		configkit.Override{Path: configkit.Keys("service", "version"), Value: "cli-v3", Flag: "--service-version"})
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 ||
+		loadError.Diagnostics()[0].Code != configkit.CodeOverrideVersion ||
+		loadError.Diagnostics()[0].Path.String() != "/service/version" {
+		t.Fatalf("mounted main version override error = %v", err)
+	}
+}
+
 func TestCatalogRetainsPresenceAndSourceContext(t *testing.T) {
 	result, err := consumers.LoadCatalog(fixture("layered-main", "config.yml"))
 	if err != nil {

examples/consumers/prompt_catalog.go

@@ -0,0 +1,53 @@
+package consumers
+
+import (
+	"strings"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+// PromptCatalogConfig is an application-owned prompt collection shape.
+type PromptCatalogConfig struct {
+	Prompts []PromptRecord `yaml:"prompts"`
+}
+
+// PromptRecord keeps its identity and message meaning in the consumer.
+type PromptRecord struct {
+	ID       string   `yaml:"id"`
+	Name     string   `yaml:"name"`
+	Messages []string `yaml:"messages"`
+}
+
+// LoadPromptCatalog composes explicitly registered prompt records in the main
+// tier and replaces the lower-priority default collection as a whole.
+func LoadPromptCatalog(mainPath string) (*configkit.Result[PromptCatalogConfig], error) {
+	return configkit.LoadLayered(configkit.Input{
+		Source:  configkit.File(mainPath),
+		Imports: true,
+	}, configkit.LayeredOptions[PromptCatalogConfig]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Bytes("default prompts", []byte("prompts:\n  - id: default\n    name: Default prompt\n    messages: [Default message]\n")),
+		}}}},
+		Definition: configkit.Definition[PromptCatalogConfig]{
+			SequenceCompositions: []configkit.SequenceComposition{{
+				Path:          configkit.Keys("prompts"),
+				IdentityField: "id",
+			}},
+			Validate: validatePromptCatalog,
+		},
+	})
+}
+
+func validatePromptCatalog(configuration *PromptCatalogConfig, validation *configkit.Validation) {
+	for index, prompt := range configuration.Prompts {
+		if strings.TrimSpace(prompt.Name) == "" {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("name"), "must not be empty")
+		}
+		if len(prompt.Messages) == 0 {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("messages"), "must contain at least one message")
+		}
+	}
+	if len(configuration.Prompts) == 0 {
+		validation.Error(configkit.Keys("prompts"), "must contain at least one prompt")
+	}
+}

examples/consumers/prompt_catalog_test.go

@@ -0,0 +1,82 @@
+package consumers_test
+
+import (
+	"errors"
+	"fmt"
+	"path/filepath"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+)
+
+func Example_identifiedPromptCatalog() {
+	result, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "config.yml"))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	ids := make([]string, 0, len(result.Config.Prompts))
+	for _, prompt := range result.Config.Prompts {
+		ids = append(ids, prompt.ID)
+	}
+	fmt.Println(ids, err)
+	// Output: [main curated weather welcome] <nil>
+}
+
+func TestPromptCatalogImportsRegisteredItemsAndReplacesDefaults(t *testing.T) {
+	result, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "config.yml"))
+	if err != nil {
+		var loadError *configkit.LoadError
+		if errors.As(err, &loadError) {
+			t.Fatalf("load prompt catalog: %v (%#v)", err, loadError.Diagnostics())
+		}
+		t.Fatal(err)
+	}
+	if len(result.Config.Prompts) != 4 {
+		t.Fatalf("prompt records = %#v", result.Config.Prompts)
+	}
+	ids := []string{"main", "curated", "weather", "welcome"}
+	for index, id := range ids {
+		if result.Config.Prompts[index].ID != id {
+			t.Fatalf("prompt %d ID = %q, want %q", index, result.Config.Prompts[index].ID, id)
+		}
+	}
+	for _, prompt := range result.Config.Prompts {
+		if prompt.ID == "default" {
+			t.Fatalf("lower-priority default survived main sequence replacement: %#v", result.Config.Prompts)
+		}
+	}
+
+	var itemImports, helperImports int
+	for _, source := range result.Sources() {
+		switch filepath.Base(source.Path) {
+		case "curated.yml", "generated-weather.yml", "generated-welcome.yml":
+			if source.PlacementMode != configkit.PlacementModeSequenceItem || source.Destination.String() != "/prompts" {
+				t.Fatalf("item source placement = %#v", source)
+			}
+			itemImports++
+		case "curated-id.yml":
+			if source.PlacementMode != configkit.PlacementModeMapping || source.ImportedFrom == nil {
+				t.Fatalf("helper source = %#v", source)
+			}
+			helperImports++
+		}
+	}
+	if itemImports != 3 || helperImports != 1 {
+		t.Fatalf("item imports = %d, helper imports = %d, sources = %#v", itemImports, helperImports, result.Sources())
+	}
+	if result.Config.Prompts[1].ID != "curated" {
+		t.Fatalf("helper did not provide prompt ID: %#v", result.Config.Prompts[1])
+	}
+}
+
+func TestPromptCatalogLeavesDomainValidationWithConsumer(t *testing.T) {
+	_, err := consumers.LoadPromptCatalog(fixture("prompt-catalog", "invalid.yml"))
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 ||
+		loadError.Diagnostics()[0].Code != configkit.CodeValidateError ||
+		loadError.Diagnostics()[0].Path.String() != "/prompts/0/messages" {
+		t.Fatalf("consumer domain validation error = %v", err)
+	}
+}

examples/consumers/source_version.go

@@ -0,0 +1,64 @@
+package consumers
+
+import (
+	"errors"
+	"io/fs"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+// VersionedServiceConfig demonstrates a mounted main input whose source-local
+// schema version is retained at the effective service path.
+type VersionedServiceConfig struct {
+	Service struct {
+		Version  string `yaml:"version"`
+		Name     string `yaml:"name"`
+		Endpoint string `yaml:"endpoint"`
+		Metadata struct {
+			Release string `yaml:"release"`
+		} `yaml:"metadata"`
+	} `yaml:"service"`
+}
+
+// LoadVersionedService checks the main and underlay declarations with one
+// application policy. The local rule path is "version" for each source; the
+// main input's destination places its protected value at /service/version.
+// Optional CLI overrides are passed through to ConfigKit for normal protection.
+func LoadVersionedService(mode configkit.SourceVersionMode, overrides ...configkit.Override) (*configkit.Result[VersionedServiceConfig], error) {
+	files, err := fs.Sub(bundledFiles, "testdata/source-version")
+	if err != nil {
+		return nil, err
+	}
+	main, err := fs.ReadFile(files, "main.yml")
+	if err != nil {
+		return nil, err
+	}
+	underlay, err := fs.ReadFile(files, "underlay.yml")
+	if err != nil {
+		return nil, err
+	}
+	definition := configkit.Definition[VersionedServiceConfig]{
+		Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(version configkit.Version, _ *configkit.Validation) error {
+				if !version.Present || version.Null || version.Text == "" {
+					return errors.New("a nonempty source version is required")
+				}
+				return nil
+			},
+		},
+		Secret: func(path configkit.Path) bool {
+			return path.String() == "/service/version"
+		},
+	}
+	return configkit.LoadLayered(configkit.Input{
+		Source: configkit.Bytes("service main", main), Destination: configkit.Keys("service"),
+	}, configkit.LayeredOptions[VersionedServiceConfig]{
+		Definition:        definition,
+		SourceVersionMode: mode,
+		Overrides:         overrides,
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Bytes("service defaults", underlay), Destination: configkit.Keys("service"),
+		}}}},
+	})
+}

examples/consumers/testdata/collection-bundle/collections/weather/collection.yml

@@ -0,0 +1,9 @@
+configkit:
+  imports:
+    - path: metadata.yml
+      destination: []
+    - path: prompts/index.yml
+      destination: [prompts]
+    - path: profiles/index.yml
+      destination: [profiles]
+name: Weather Reporter

examples/consumers/testdata/collection-bundle/collections/weather/metadata.yml

@@ -0,0 +1,4 @@
+configkit:
+  imports:
+    - path: version.yml
+description: Imported collection metadata.

examples/consumers/testdata/collection-bundle/collections/weather/profiles/compact.yml

@@ -0,0 +1,3 @@
+compact:
+  format: text
+  temperature: 0.2

examples/consumers/testdata/collection-bundle/collections/weather/profiles/index.yml

@@ -0,0 +1,4 @@
+configkit:
+  imports:
+    - path: compact.yml
+    - path: weather.yml

examples/consumers/testdata/collection-bundle/collections/weather/profiles/weather.yml

@@ -0,0 +1,3 @@
+weather:
+  extends: compact
+  temperature: 0.4

examples/consumers/testdata/collection-bundle/collections/weather/prompts/brief.yml

@@ -0,0 +1,7 @@
+brief:
+  version: "1"
+  default_profile: compact
+  content_file: welcome.txt
+  messages:
+    - role: user
+      content: Write a concise weather summary.

examples/consumers/testdata/collection-bundle/collections/weather/prompts/custom.yml

@@ -0,0 +1,3 @@
+custom:
+  extends: brief
+  default_profile: weather

examples/consumers/testdata/collection-bundle/collections/weather/prompts/index.yml

@@ -0,0 +1,4 @@
+configkit:
+  imports:
+    - path: brief.yml
+    - path: custom.yml

examples/consumers/testdata/collection-bundle/collections/weather/prompts/welcome.txt

@@ -0,0 +1 @@
+Welcome to the weather collection.

examples/consumers/testdata/collection-bundle/collections/weather/version.yml

@@ -0,0 +1 @@
+version: "2.4.0"

examples/consumers/testdata/collection-bundle/operators/weather-prompt-version.yml

@@ -0,0 +1,2 @@
+brief:
+  version: "2"

examples/consumers/testdata/ordinary-imports/config.yml

@@ -0,0 +1,6 @@
+configkit:
+  imports:
+    - path: metadata.yml
+    - path: prompts/brief.yml
+      destination: [prompts]
+name: Root import example

examples/consumers/testdata/ordinary-imports/metadata.yml

@@ -0,0 +1,2 @@
+version: "1.0"
+description: Metadata imported into the root document.

examples/consumers/testdata/ordinary-imports/prompts/brief.yml

@@ -0,0 +1,2 @@
+brief:
+  summary: A root-loaded prompt.

examples/consumers/testdata/prompt-catalog/config.yml

@@ -0,0 +1,12 @@
+configkit:
+  imports:
+    - path: prompts/curated.yml
+      destination: [prompts]
+      placement: sequence-item
+    - glob: prompts/generated-*.yml
+      destination: [prompts]
+      placement: sequence-item
+prompts:
+  - id: main
+    name: Main authored prompt
+    messages: [Use the main prompt.]

examples/consumers/testdata/prompt-catalog/invalid.yml

@@ -0,0 +1,4 @@
+prompts:
+  - id: invalid
+    name: Invalid prompt
+    messages: []

examples/consumers/testdata/prompt-catalog/prompts/curated-id.yml

@@ -0,0 +1 @@
+id: curated

examples/consumers/testdata/prompt-catalog/prompts/curated.yml

@@ -0,0 +1,6 @@
+configkit:
+  imports:
+    - path: curated-id.yml
+name: Curated summary
+messages:
+  - Summarize the supplied content.

examples/consumers/testdata/prompt-catalog/prompts/generated-weather.yml

@@ -0,0 +1,4 @@
+id: weather
+name: Weather forecast
+messages:
+  - Describe today's forecast.

examples/consumers/testdata/prompt-catalog/prompts/generated-welcome.yml

@@ -0,0 +1,4 @@
+id: welcome
+name: Welcome
+messages:
+  - Welcome the user.

examples/consumers/testdata/source-version/main.yml

@@ -0,0 +1,4 @@
+version: service-v2
+name: example service
+metadata:
+  release: application-2026.10

examples/consumers/testdata/source-version/underlay.yml

@@ -0,0 +1,2 @@
+version: catalog-v1
+endpoint: https://service.example.invalid

facade_destination_test.go

@@ -0,0 +1,705 @@
+package configkit_test
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func TestFacadeInputDestinationsAcrossSourceKinds(t *testing.T) {
+	directory := t.TempDir()
+	hostPath := filepath.Join(directory, "host.yml")
+	if err := os.WriteFile(hostPath, []byte("value: host\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	native := configkit.NewFilesystem("native", fstest.MapFS{
+		"main.yml": &fstest.MapFile{Data: []byte("value: native\n")},
+	})
+	const literalValuePath = "/collections/weather.reporter/profiles/a~1b/~0/0"
+	destination := configkit.Keys("collections", "weather.reporter", "profiles", "a/b", "~", "0")
+	for _, test := range []struct {
+		name   string
+		source configkit.Source
+		want   string
+		kind   configkit.SourceKind
+	}{
+		{name: "host file", source: configkit.File(hostPath), want: "host", kind: configkit.SourceKindFile},
+		{name: "native filesystem", source: native.File("main.yml"), want: "native", kind: configkit.SourceKindFilesystem},
+		{name: "bytes", source: configkit.Bytes("bytes", []byte("value: bytes\n")), want: "bytes", kind: configkit.SourceKindBytes},
+		{name: "reader", source: configkit.Reader("reader", strings.NewReader("value: reader\n")), want: "reader", kind: configkit.SourceKindReader},
+		{name: "mapping", source: configkit.Mapping("mapping", map[string]any{"value": "mapping"}), want: "mapping", kind: configkit.SourceKindMapping},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: test.source, Destination: destination})
+			if err != nil {
+				t.Fatalf("LoadLayered: %v", err)
+			}
+			if got := facadeDestinationValue(t, result.Config, "collections", "weather.reporter", "profiles", "a/b", "~", "0", "value"); got != test.want {
+				t.Fatalf("placed value = %#v, want %q", got, test.want)
+			}
+			sources := result.Sources()
+			if len(sources) != 1 || sources[0].Kind != test.kind || sources[0].Destination.String() != destination.String() || destination.String() != literalValuePath {
+				t.Fatalf("source placement = %#v, destination = %q", sources, destination.String())
+			}
+		})
+	}
+}
+
+func TestFacadeDestinationRootEmptyMappingNoSourceAndInvalidPaths(t *testing.T) {
+	for _, test := range []struct {
+		name        string
+		destination configkit.Path
+	}{
+		{name: "omitted destination"},
+		{name: "explicit empty destination", destination: configkit.Path{}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Bytes("root", []byte("value: root\n")), Destination: test.destination})
+			if err != nil {
+				t.Fatalf("root load: %v", err)
+			}
+			if result.Config["value"] != "root" || len(result.Sources()) != 1 || result.Sources()[0].Destination.String() != "" {
+				t.Fatalf("root placement = %#v, sources %#v", result.Config, result.Sources())
+			}
+		})
+	}
+
+	emptyPath := configkit.Keys("collections", "empty")
+	empty, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.Mapping("empty", map[string]any{}), Destination: emptyPath,
+	})
+	if err != nil {
+		t.Fatalf("empty mapping load: %v", err)
+	}
+	if value := facadeDestinationMap(t, empty.Config, "collections")["empty"]; value == nil {
+		t.Fatal("empty mapping did not materialize its destination")
+	}
+	if info, ok := empty.Metadata().Lookup(emptyPath); !ok || !info.Explicit {
+		t.Fatalf("empty destination metadata = %#v, %v", info, ok)
+	}
+
+	absentPath := configkit.Keys("collections", "absent")
+	absent, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource(), Destination: absentPath})
+	if err != nil {
+		t.Fatalf("NoSource with a destination: %v", err)
+	}
+	if len(absent.Sources()) != 0 {
+		t.Fatalf("NoSource created source records: %#v", absent.Sources())
+	}
+	if _, ok := absent.Metadata().Lookup(absentPath); ok {
+		t.Fatal("NoSource materialized its destination")
+	}
+
+	reader := &destinationCountingReader{}
+	for _, test := range []struct {
+		name        string
+		source      configkit.Source
+		destination configkit.Path
+		wantReads   int
+	}{
+		{name: "index segment", source: configkit.Reader("unread", reader), destination: configkit.Keys("catalog").Index(0)},
+		{name: "reserved configkit key", source: configkit.NoSource(), destination: configkit.Keys("configkit")},
+		{name: "reserved extends key", source: configkit.NoSource(), destination: configkit.Keys("catalog", "extends")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: test.source, Destination: test.destination})
+			loadError, ok := err.(*configkit.LoadError)
+			if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeOptionsInvalid {
+				t.Fatalf("invalid destination error = %#v", err)
+			}
+			if reader.reads != test.wantReads {
+				t.Fatalf("reader calls = %d, want %d", reader.reads, test.wantReads)
+			}
+		})
+	}
+}
+
+func TestFacadeImportedSourcesRetainInputDestination(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	fragmentPath := filepath.Join(directory, "fragment.yml")
+	if err := os.WriteFile(mainPath, []byte("configkit: {imports: [{path: fragment.yml}]}\nmain: present\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(fragmentPath, []byte("imported: present\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	destination := configkit.Keys("collections", "weatherreporter")
+	result, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.File(mainPath), Imports: true, Destination: destination,
+	})
+	if err != nil {
+		t.Fatalf("mounted import load: %v", err)
+	}
+	collection := facadeDestinationMap(t, result.Config, "collections", "weatherreporter")
+	if collection["main"] != "present" || collection["imported"] != "present" {
+		t.Fatalf("mounted imported values = %#v", collection)
+	}
+	sources := result.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != destination.String() || sources[1].Destination.String() != destination.String() {
+		t.Fatalf("mounted import source destinations = %#v", sources)
+	}
+	if sources[1].ImportedFrom == nil {
+		t.Fatalf("imported source lacks its authored directive: %#v", sources[1])
+	}
+}
+
+func TestFacadeRelativeImportDestinationsForRootAndMountedLoads(t *testing.T) {
+	directory := t.TempDir()
+	write := func(relative, contents string) string {
+		t.Helper()
+		filename := filepath.Join(directory, filepath.FromSlash(relative))
+		if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filename, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return filename
+	}
+
+	mainPath := write("main.yml", `configkit:
+  imports:
+    - path: metadata.yml
+      destination: [metadata]
+    - glob: prompts/*.yml
+      destination: [prompts]
+    - path: entries/main.yml
+      destination: [profiles]
+    - path: sibling.yml
+      destination: [sibling]
+root: main
+`)
+	write("metadata.yml", "name: imported\n")
+	write("prompts/a.yml", "a: {name: alpha}\n")
+	write("prompts/b.yml", "b: {name: beta}\n")
+	write("entries/main.yml", `configkit:
+  imports:
+    - path: nested/details.yml
+      destination: [details]
+name: profile
+`)
+	write("entries/nested/details.yml", "summary: nested\n")
+	write("sibling.yml", "name: separate\n")
+
+	root, err := configkit.Load(
+		configkit.File(mainPath), configkit.Options[map[string]any]{Imports: true},
+	)
+	if err != nil {
+		if loadError, ok := err.(*configkit.LoadError); ok {
+			t.Fatalf("ordinary root Load: %v, diagnostics %#v", err, loadError.Diagnostics())
+		}
+		t.Fatalf("ordinary root Load: %v", err)
+	}
+	mountedDestination := configkit.Keys("collections", "weatherreporter")
+	mounted, err := configkit.LoadLayered[map[string]any](configkit.Input{
+		Source: configkit.File(mainPath), Imports: true, Destination: mountedDestination,
+	})
+	if err != nil {
+		t.Fatalf("mounted layered Load: %v", err)
+	}
+
+	for _, test := range []struct {
+		name   string
+		result *configkit.Result[map[string]any]
+		prefix []string
+	}{
+		{name: "ordinary root", result: root},
+		{name: "mounted entry", result: mounted, prefix: []string{"collections", "weatherreporter"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			at := func(keys ...string) []string {
+				return append(append([]string(nil), test.prefix...), keys...)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("root")...); got != "main" {
+				t.Fatalf("root value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("metadata", "name")...); got != "imported" {
+				t.Fatalf("metadata value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("prompts", "a", "name")...); got != "alpha" {
+				t.Fatalf("first glob value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("prompts", "b", "name")...); got != "beta" {
+				t.Fatalf("second glob value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("profiles", "name")...); got != "profile" {
+				t.Fatalf("entry value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("profiles", "details", "summary")...); got != "nested" {
+				t.Fatalf("nested import value = %#v", got)
+			}
+			if got := facadeDestinationValue(t, test.result.Config, at("sibling", "name")...); got != "separate" {
+				t.Fatalf("subsequent sibling value = %#v", got)
+			}
+
+			wantPaths := []string{
+				"main.yml", "metadata.yml", "a.yml", "b.yml", "main.yml", "details.yml", "sibling.yml",
+			}
+			wantPhysicalPaths := []string{
+				mainPath,
+				filepath.Join(directory, "metadata.yml"),
+				filepath.Join(directory, "prompts", "a.yml"),
+				filepath.Join(directory, "prompts", "b.yml"),
+				filepath.Join(directory, "entries", "main.yml"),
+				filepath.Join(directory, "entries", "nested", "details.yml"),
+				filepath.Join(directory, "sibling.yml"),
+			}
+			wantImportParents := []string{"", "source-1", "source-1", "source-1", "source-1", "source-5", "source-1"}
+			wantDestinations := []configkit.Path{configkit.Keys(test.prefix...)}
+			for _, suffix := range [][]string{{"metadata"}, {"prompts"}, {"prompts"}, {"profiles"}, {"profiles", "details"}, {"sibling"}} {
+				destination := append([]string(nil), test.prefix...)
+				for _, segment := range suffix {
+					destination = append(destination, segment)
+				}
+				wantDestinations = append(wantDestinations, configkit.Keys(destination...))
+			}
+			sources := test.result.Sources()
+			if len(sources) != len(wantPaths) {
+				t.Fatalf("sources = %#v, want %d", sources, len(wantPaths))
+			}
+			for index, source := range sources {
+				if filepath.Base(source.Path) != wantPaths[index] || source.Path != wantPhysicalPaths[index] || source.Destination.String() != wantDestinations[index].String() {
+					t.Errorf("source %d path/destination = (%q, %q), want physical path %q and destination %q", index, source.Path, source.Destination.String(), wantPhysicalPaths[index], wantDestinations[index].String())
+				}
+				if source.ID != fmt.Sprintf("source-%d", index+1) || source.Kind != configkit.SourceKindFile {
+					t.Errorf("source %d identity/kind = (%q, %q)", index, source.ID, source.Kind)
+				}
+				if wantImportParents[index] == "" {
+					if source.ImportedFrom != nil {
+						t.Errorf("entry source unexpectedly has an import location: %#v", source.ImportedFrom)
+					}
+				} else if source.ImportedFrom == nil || source.ImportedFrom.SourceID != wantImportParents[index] || source.ImportedFrom.Line == 0 || source.ImportedFrom.Column == 0 {
+					t.Errorf("source %d import location = %#v, want declaration in %s", index, source.ImportedFrom, wantImportParents[index])
+				}
+			}
+		})
+	}
+}
+
+func TestFacadeSameFragmentMountsAtSeparateCollectionDestinations(t *testing.T) {
+	weatherDestination := configkit.Keys("collections", "weather", "prompts")
+	homeDestination := configkit.Keys("collections", "homewatch", "prompts")
+	result, err := configkit.LoadLayered(
+		configkit.Input{Source: configkit.NoSource()},
+		configkit.LayeredOptions[map[string]any]{Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+			{Source: configkit.Bytes("weather", []byte("summarize.alerts: {title: weather}\n")), Destination: weatherDestination},
+			{Source: configkit.Bytes("homewatch", []byte("summarize.alerts: {title: home}\n")), Destination: homeDestination},
+		}}}},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	for _, test := range []struct {
+		path []string
+		want string
+	}{
+		{path: []string{"collections", "weather", "prompts", "summarize.alerts", "title"}, want: "weather"},
+		{path: []string{"collections", "homewatch", "prompts", "summarize.alerts", "title"}, want: "home"},
+	} {
+		if got := facadeDestinationValue(t, result.Config, test.path...); got != test.want {
+			t.Errorf("value at %v = %#v, want %q", test.path, got, test.want)
+		}
+	}
+	sources := result.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != weatherDestination.String() || sources[1].Destination.String() != homeDestination.String() {
+		t.Fatalf("independent collection source placements = %#v", sources)
+	}
+}
+
+type destinationCountingReader struct{ reads int }
+
+func (reader *destinationCountingReader) Read([]byte) (int, error) {
+	reader.reads++
+	return 0, io.EOF
+}
+
+func TestFacadeMountedMainAndUnderlayInspectionResourcesAndDiff(t *testing.T) {
+	t.Parallel()
+
+	filesystem := configkit.NewFilesystem("resources", fstest.MapFS{
+		"assets/summary.md": &fstest.MapFile{Data: []byte("source-relative summary")},
+	})
+	context := &configkit.FilesystemContext{Root: ".", BaseDir: "assets", FS: &filesystem}
+	destination := configkit.Keys("catalog", "entries")
+	tokenPath := configkit.Keys("catalog", "entries", "item", "token")
+	titlePath := configkit.Keys("catalog", "entries", "item", "title")
+	var callbacks struct{ resolve, validate int }
+	load := func(token string) *configkit.Result[map[string]any] {
+		t.Helper()
+		main := configkit.Input{
+			Source:      configkit.Bytes("main", []byte("item:\n  title: main\n  resource: summary.md\n  token: "+token+"\n")),
+			Destination: destination, Filesystem: context,
+		}
+		underlay := configkit.Input{
+			Source:      configkit.Bytes("underlay", []byte("item:\n  title: lower\n  retained: lower-value\n  token: LOWER-TOKEN-CANARY\n")),
+			Destination: destination,
+		}
+		result, err := configkit.LoadLayered(main, configkit.LayeredOptions[map[string]any]{
+			Underlays: []configkit.Underlay{{Inputs: []configkit.Input{underlay}}},
+			Definition: configkit.Definition[map[string]any]{
+				Resolve: func(configuration *map[string]any, resolution *configkit.Resolution) error {
+					callbacks.resolve++
+					resourcePath := configkit.Keys("catalog", "entries", "item", "resource")
+					input, ok := resolution.InputInfo(resourcePath)
+					if !ok || len(input.Origin.Locations) != 1 {
+						return fmt.Errorf("mounted resource input has no single source origin")
+					}
+					source, ok := resolution.Source(input.Origin.Locations[0].SourceID)
+					if !ok || source.Destination.String() != destination.String() {
+						return fmt.Errorf("resolution source did not retain its destination")
+					}
+					resourceContext, ok := resolution.SourceContext(source.ID)
+					if !ok {
+						return fmt.Errorf("resolution source context is unavailable")
+					}
+					data, err := fs.ReadFile(resourceContext.FS, path.Join(resourceContext.BaseDir, "summary.md"))
+					if err != nil {
+						return fmt.Errorf("read source-relative resource: %w", err)
+					}
+					entry := facadeDestinationMap(t, facadeDestinationMap(t, facadeDestinationMap(t, *configuration, "catalog"), "entries"), "item")
+					entry["resource_text"] = string(data)
+					resolution.Record(configkit.Keys("catalog", "entries", "item", "resource_text"), configkit.ChangeNormalization, "read source-relative summary", resourcePath)
+					return nil
+				},
+				Validate: func(*map[string]any, *configkit.Validation) { callbacks.validate++ },
+				Secret:   func(candidate configkit.Path) bool { return candidate.String() == tokenPath.String() },
+			},
+		})
+		if err != nil {
+			t.Fatalf("mounted load: %v", err)
+		}
+		return result
+	}
+
+	first := load("FIRST-TOKEN-CANARY")
+	second := load("SECOND-TOKEN-CANARY")
+	if callbacks.resolve != 2 || callbacks.validate != 2 {
+		t.Fatalf("lifecycle callbacks = %#v", callbacks)
+	}
+	for _, result := range []*configkit.Result[map[string]any]{first, second} {
+		entry := facadeDestinationMap(t, facadeDestinationMap(t, facadeDestinationMap(t, result.Config, "catalog"), "entries"), "item")
+		if entry["title"] != "main" || entry["retained"] != "lower-value" || entry["resource_text"] != "source-relative summary" {
+			t.Fatalf("mounted main/underlay configuration = %#v", entry)
+		}
+		sources := result.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != destination.String() || sources[1].Destination.String() != destination.String() {
+			t.Fatalf("public source destinations = %#v", sources)
+		}
+		resource, ok := result.SourceContext(sources[0].ID)
+		if !ok || resource.BaseDir != "assets" {
+			t.Fatalf("completed source context = %#v, %v", resource, ok)
+		}
+		data, err := fs.ReadFile(resource.FS, path.Join(resource.BaseDir, "summary.md"))
+		if err != nil || string(data) != "source-relative summary" {
+			t.Fatalf("completed relative resource = %q, %v", data, err)
+		}
+		if info, ok := result.Metadata().Lookup(titlePath); !ok || info.Origin.Layer != configkit.LayerBase {
+			t.Fatalf("mounted title metadata = %#v, %v", info, ok)
+		}
+		if history := result.Metadata().History(titlePath); len(history) < 2 {
+			t.Fatalf("mounted title history = %#v", history)
+		}
+		if explanation, ok := result.Explain(tokenPath); !ok || !explanation.Effective.Redacted {
+			t.Fatalf("mounted secret explanation = %#v, %v", explanation, ok)
+		}
+		var effective, explanation bytes.Buffer
+		if err := result.WriteEffective(&effective); err != nil {
+			t.Fatal(err)
+		}
+		if err := result.WriteExplanation(&explanation, tokenPath); err != nil {
+			t.Fatal(err)
+		}
+		output := effective.String() + explanation.String()
+		for _, canary := range []string{"FIRST-TOKEN-CANARY", "SECOND-TOKEN-CANARY", "LOWER-TOKEN-CANARY"} {
+			if strings.Contains(output, canary) {
+				t.Fatalf("public inspection leaked %q: %s", canary, output)
+			}
+		}
+	}
+
+	// Mutating published records and query copies must not alter the retained result.
+	returnedSources := first.Sources()
+	returnedSources[0].Destination = configkit.Keys("mutated")
+	if got := first.Sources()[0].Destination.String(); got != destination.String() {
+		t.Fatalf("source destination changed after caller mutation: %q", got)
+	}
+	info, ok := first.Metadata().Lookup(titlePath)
+	if !ok {
+		t.Fatal("mounted metadata lookup failed")
+	}
+	info.Origin.Locations[0].SourceID = "mutated"
+	if fresh, ok := first.Metadata().Lookup(titlePath); !ok || fresh.Origin.Locations[0].SourceID == "mutated" {
+		t.Fatalf("metadata copy mutation escaped: %#v, %v", fresh, ok)
+	}
+	history := first.Metadata().History(titlePath)
+	if len(history) == 0 {
+		t.Fatal("mounted history is empty")
+	}
+	history[0].Path = configkit.Keys("mutated")
+	if fresh := first.Metadata().History(titlePath); len(fresh) == 0 || fresh[0].Path.String() != titlePath.String() {
+		t.Fatalf("history copy mutation escaped: %#v", fresh)
+	}
+
+	differences, err := configkit.Diff(first, second)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 1 || differences[0].Path.String() != tokenPath.String() ||
+		!differences[0].Left.Redacted || !differences[0].Right.Redacted ||
+		strings.Contains(differences[0].Left.YAML+differences[0].Right.YAML, "TOKEN-CANARY") {
+		t.Fatalf("public mounted secret diff = %#v", differences)
+	}
+	if callbacks.resolve != 2 || callbacks.validate != 2 {
+		t.Fatalf("inspection reran lifecycle callbacks: %#v", callbacks)
+	}
+}
+
+func TestFacadeFailedLoadExposesDetachedSourceDestination(t *testing.T) {
+	type configuration struct {
+		Tenant struct {
+			Count int `yaml:"count"`
+		} `yaml:"tenant"`
+	}
+	destination := configkit.Keys("tenant")
+	_, err := configkit.LoadLayered[configuration](configkit.Input{
+		Source: configkit.Bytes("invalid", []byte("count: not-an-integer\n")), Destination: destination,
+	})
+	loadError, ok := err.(*configkit.LoadError)
+	if !ok {
+		t.Fatalf("failed load error = %T %v", err, err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 1 || sources[0].Destination.String() != destination.String() {
+		t.Fatalf("failed source destinations = %#v", sources)
+	}
+	sources[0].Destination = configkit.Keys("caller-change")
+	if fresh := loadError.Sources(); len(fresh) != 1 || fresh[0].Destination.String() != destination.String() {
+		t.Fatalf("failed source destination was not detached: %#v", fresh)
+	}
+}
+
+func TestFacadeRelativeImportFailuresRetainSourceRecordsAndCoordinates(t *testing.T) {
+	directory := t.TempDir()
+	write := func(name, contents string) string {
+		t.Helper()
+		filename := filepath.Join(directory, name)
+		if err := os.MkdirAll(filepath.Dir(filename), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filename, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return filename
+	}
+
+	t.Run("imported parse failure retains effective source destination", func(t *testing.T) {
+		mainPath := write("parse/main.yml", "configkit:\n  imports:\n    - path: child.yml\n      destination: [tenant]\n")
+		childPath := write("parse/child.yml", "count: [unterminated\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeYAMLInvalid || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+			t.Fatalf("imported parse diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != childPath {
+			t.Fatalf("imported parse failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("directive failure stays source local", func(t *testing.T) {
+		mainPath := write("directive/main.yml", "configkit:\n  imports:\n    - path: parent.yml\n      destination: [tenant]\n")
+		parentPath := write("directive/parent.yml", "configkit:\n  imports:\n    - path: details.yml\n      destination: [3]\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		wantPath := configkit.Keys("configkit", "imports").Index(0).Key("destination").Index(0)
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeImportInvalid || !reflect.DeepEqual(diagnostics[0].Path, wantPath) || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+			t.Fatalf("import directive diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != parentPath {
+			t.Fatalf("directive failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("composition failure reports effective path and all sources", func(t *testing.T) {
+		mainPath := write("compose/main.yml", "configkit:\n  imports:\n    - path: left.yml\n      destination: [tenant]\n    - path: right.yml\n      destination: [tenant]\n")
+		write("compose/left.yml", "value: same\n")
+		write("compose/right.yml", "value: same\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeComposeConflict || diagnostics[0].Path.String() != "/mount/tenant/value" {
+			t.Fatalf("composition diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 3 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[2].Destination.String() != "/mount/tenant" {
+			t.Fatalf("composition failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("version failure reports effective path and imported source", func(t *testing.T) {
+		mainPath := write("version/main.yml", "configkit:\n  imports:\n    - path: child.yml\n      destination: [tenant]\n")
+		childPath := write("version/child.yml", "version: forbidden\n")
+		_, err := configkit.LoadLayered[map[string]any](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		}, configkit.LayeredOptions[map[string]any]{
+			Definition: configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+				Path:  configkit.Keys("mount", "tenant", "version"),
+				Check: func(configkit.Version, *configkit.Validation) error { return nil },
+			}},
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeImportVersion || diagnostics[0].Path.String() != "/mount/tenant/version" || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+			t.Fatalf("version diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != childPath {
+			t.Fatalf("version failure sources = %#v", sources)
+		}
+	})
+
+	t.Run("typed validation reports effective path and authored location", func(t *testing.T) {
+		type configuration struct {
+			Mount struct {
+				Tenant struct {
+					Count int `yaml:"count"`
+				} `yaml:"tenant"`
+			} `yaml:"mount"`
+		}
+		mainPath := write("typed/main.yml", "configkit:\n  imports:\n    - path: child.yml\n      destination: [tenant]\n")
+		childPath := write("typed/child.yml", "count: invalid\n")
+		_, err := configkit.LoadLayered[configuration](configkit.Input{
+			Source: configkit.File(mainPath), Imports: true, Destination: configkit.Keys("mount"),
+		})
+		var loadError *configkit.LoadError
+		if !errors.As(err, &loadError) {
+			t.Fatalf("load error = %T %v", err, err)
+		}
+		diagnostics := loadError.Diagnostics()
+		if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeDecodeType || diagnostics[0].Path.String() != "/mount/tenant/count" || diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" || diagnostics[0].Primary.Line != 1 {
+			t.Fatalf("typed validation diagnostic = %#v", diagnostics)
+		}
+		sources := loadError.Sources()
+		if len(sources) != 2 || sources[0].Destination.String() != "/mount" || sources[1].Destination.String() != "/mount/tenant" || sources[1].Path != childPath {
+			t.Fatalf("typed validation sources = %#v", sources)
+		}
+	})
+}
+
+func TestFacadeDestinationMappingFailurePaths(t *testing.T) {
+	t.Parallel()
+
+	cycle := map[string]any{}
+	cycle["self"] = cycle
+	for _, fixture := range []struct {
+		name   string
+		values map[string]any
+		path   func(configkit.Path) configkit.Path
+	}{
+		{
+			name:   "unsupported nested sequence value",
+			values: map[string]any{"a/b": []any{map[string]any{"~": func() {}}}},
+			path:   func(base configkit.Path) configkit.Path { return base.Key("a/b").Index(0).Key("~") },
+		},
+		{
+			name:   "cyclic value",
+			values: map[string]any{"item": cycle},
+			path:   func(base configkit.Path) configkit.Path { return base.Key("item").Key("self") },
+		},
+		{
+			name: "constructor failure keeps source coordinates",
+			path: func(configkit.Path) configkit.Path { return configkit.Path{} },
+		},
+	} {
+		t.Run(fixture.name, func(t *testing.T) {
+			for _, role := range []string{"root", "mounted main", "mounted underlay"} {
+				t.Run(role, func(t *testing.T) {
+					var destination configkit.Path
+					if role != "root" {
+						destination = configkit.Keys("catalog", "entries")
+					}
+					wantPath := fixture.path(destination)
+					input := configkit.Input{Source: configkit.Mapping("invalid mapping", fixture.values), Destination: destination}
+					var result *configkit.Result[map[string]any]
+					var err error
+					if role == "mounted underlay" {
+						result, err = configkit.LoadLayered(configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{
+							Underlays: []configkit.Underlay{{Inputs: []configkit.Input{input}}},
+						})
+					} else {
+						result, err = configkit.LoadLayered[map[string]any](input)
+					}
+					var loadError *configkit.LoadError
+					if result != nil || !errors.As(err, &loadError) {
+						t.Fatalf("failed load = %#v, %v", result, err)
+					}
+					diagnostics := loadError.Diagnostics()
+					if len(diagnostics) != 1 {
+						t.Fatalf("diagnostics = %#v", diagnostics)
+					}
+					diagnostic := diagnostics[0]
+					if diagnostic.Code != configkit.CodeSourceInvalid || !reflect.DeepEqual(diagnostic.Path, wantPath) {
+						t.Fatalf("diagnostic = %#v; want source.invalid at %q", diagnostic, wantPath.String())
+					}
+					if diagnostic.Primary == nil || *diagnostic.Primary != (configkit.Location{SourceID: "source-1"}) || len(diagnostic.Related) != 0 {
+						t.Fatalf("mapping source locations = %#v, %#v", diagnostic.Primary, diagnostic.Related)
+					}
+					sources := loadError.Sources()
+					if len(sources) != 1 || sources[0].ID != "source-1" || sources[0].Destination.String() != destination.String() {
+						t.Fatalf("error sources = %#v", sources)
+					}
+				})
+			}
+		})
+	}
+}
+
+func facadeDestinationMap(t *testing.T, value map[string]any, keys ...string) map[string]any {
+	t.Helper()
+	for _, key := range keys {
+		child, ok := value[key].(map[string]any)
+		if !ok {
+			t.Fatalf("%q = %#v, want mapping", key, value[key])
+		}
+		value = child
+	}
+	return value
+}
+
+func facadeDestinationValue(t *testing.T, value map[string]any, keys ...string) any {
+	t.Helper()
+	return facadeDestinationMap(t, value, keys[:len(keys)-1]...)[keys[len(keys)-1]]
+}

facade_diff_test.go

@@ -0,0 +1,327 @@
+package configkit_test
+
+import (
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+type facadeDiffConfig struct {
+	Value   string         `yaml:"value"`
+	Count   int            `yaml:"count"`
+	Items   []string       `yaml:"items"`
+	Dynamic map[string]any `yaml:"dynamic"`
+}
+
+type facadeDiffSecretConfig struct {
+	Secret configkit.Secret `yaml:"secret"`
+}
+
+func TestFacadeDiffKeepsPublicSequenceChangesWithHistoricalDescendants(t *testing.T) {
+	type configuration struct {
+		Items []any `yaml:"items"`
+	}
+	load := func(public string) *configkit.Result[configuration] {
+		t.Helper()
+		result, err := configkit.Load(configkit.Bytes("historical-sequence.yml", []byte("items: [{secret: disposable-canary}, "+public+"]\n")),
+			configkit.Options[configuration]{Definition: configkit.Definition[configuration]{
+				Secret: func(path configkit.Path) bool { return path.String() == "/items/0/secret" },
+				Resolve: func(current *configuration, resolution *configkit.Resolution) error {
+					current.Items[0] = "public scalar"
+					resolution.Record(configkit.Keys("items"), configkit.ChangeNormalization, "normalize first item")
+					return nil
+				},
+			}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return result
+	}
+	left, right := load("1"), load("2")
+	history, ok := left.Explain(configkit.Keys("items").Index(0).Key("secret"))
+	if !ok || history.Effective.Present || len(history.History) == 0 {
+		t.Fatalf("removed historical secret = %#v, known=%v", history, ok)
+	}
+	maskedHistory := false
+	for _, change := range history.History {
+		maskedHistory = maskedHistory || change.Before.Redacted || change.After.Redacted
+	}
+	if !maskedHistory {
+		t.Fatal("historical sensitivity was not retained")
+	}
+	differences, err := configkit.Diff(left, right)
+	if err != nil || len(differences) != 1 || differences[0].Path.String() != "/items" {
+		t.Fatalf("sequence difference = %#v, %v", differences, err)
+	}
+	difference := differences[0]
+	if !difference.Left.Present || !difference.Right.Present || difference.Left.Redacted || difference.Right.Redacted || difference.HiddenChanged {
+		t.Fatalf("public sequence change was concealed: %#v", difference)
+	}
+	if difference.Left.YAML != "- public scalar\n- 1\n" || difference.Right.YAML != "- public scalar\n- 2\n" {
+		t.Fatalf("public sequence snapshots = %#v", difference)
+	}
+}
+
+func TestFacadeDiffKeepsPublicScalarAcrossHistoricalAbsence(t *testing.T) {
+	type configuration struct {
+		Dynamic map[string]any `yaml:"dynamic"`
+	}
+	options := configkit.Options[configuration]{Definition: configkit.Definition[configuration]{
+		Secret: func(path configkit.Path) bool { return path.String() == "/dynamic/entry/token" },
+		Resolve: func(current *configuration, resolution *configkit.Resolution) error {
+			delete(current.Dynamic, "entry")
+			resolution.Record(configkit.Keys("dynamic", "entry"), configkit.ChangeNormalization, "remove entry")
+			return nil
+		},
+	}}
+	absent, err := configkit.Load(configkit.Bytes("removed-entry.yml", []byte("dynamic: {entry: {token: disposable-canary}}\n")), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	options.Definition.Resolve = nil
+	present, err := configkit.Load(configkit.Bytes("public-entry.yml", []byte("dynamic: {entry: public}\n")), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, test := range []struct {
+		name        string
+		left, right *configkit.Result[configuration]
+		leftPresent bool
+	}{
+		{name: "addition", left: absent, right: present},
+		{name: "removal", left: present, right: absent, leftPresent: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			differences, err := configkit.Diff(test.left, test.right)
+			if err != nil || len(differences) != 1 || differences[0].Path.String() != "/dynamic/entry" {
+				t.Fatalf("entry difference = %#v, %v", differences, err)
+			}
+			difference := differences[0]
+			if difference.Left.Present != test.leftPresent || difference.Right.Present == test.leftPresent ||
+				difference.Left.Redacted || difference.Right.Redacted || difference.HiddenChanged {
+				t.Fatalf("public presence change was concealed: %#v", difference)
+			}
+			wantLeft, wantRight := "", "public\n"
+			if test.leftPresent {
+				wantLeft, wantRight = wantRight, wantLeft
+			}
+			if difference.Left.YAML != wantLeft || difference.Right.YAML != wantRight {
+				t.Fatalf("entry snapshots = %#v", difference)
+			}
+		})
+	}
+}
+
+func TestFacadeDiffReturnsDetachedCanonicalRecords(t *testing.T) {
+	left, err := configkit.Load[facadeDiffConfig](configkit.Bytes("left.yml", []byte("value: before\ncount: 0\nitems: [one, two]\ndynamic: {}\n")))
+	if err != nil {
+		t.Fatalf("load left: %v", err)
+	}
+	right, err := configkit.Load[facadeDiffConfig](configkit.Bytes("right.yml", []byte("value: after\ncount: 0\nitems: [one, three]\ndynamic:\n  added: null\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	differences, err := configkit.Diff(left, right)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wantPaths := []string{"/dynamic/added", "/items", "/value"}
+	if len(differences) != len(wantPaths) {
+		t.Fatalf("differences = %#v", differences)
+	}
+	for index, difference := range differences {
+		if got := difference.Path.String(); got != wantPaths[index] {
+			t.Errorf("path[%d] = %q, want %q", index, got, wantPaths[index])
+		}
+	}
+	if differences[0].Left.Present || !differences[0].Right.Present || differences[0].Right.YAML != "null\n" {
+		t.Errorf("null/absence snapshots = %#v / %#v", differences[0].Left, differences[0].Right)
+	}
+	if differences[1].Left.YAML != "- one\n- two\n" || differences[1].Right.YAML != "- one\n- three\n" {
+		t.Errorf("sequence snapshots = %#v / %#v", differences[1].Left, differences[1].Right)
+	}
+
+	left.Config.Value = "caller mutation"
+	left.Config.Items[0] = "caller mutation"
+	right.Config.Dynamic["added"] = "caller mutation"
+	differences[2].Left.YAML = "record mutation"
+	differences[2].Path = configkit.Keys("rewritten")
+
+	again, err := configkit.Diff(left, right)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if again[2].Path.String() != "/value" || again[2].Left.YAML != "before\n" || again[1].Left.YAML != "- one\n- two\n" {
+		t.Fatalf("repeat diff changed = %#v", again)
+	}
+	explanation, ok := left.Explain(configkit.Keys("value"))
+	if !ok || explanation.Effective.YAML != "before\n" {
+		t.Fatalf("frozen explanation = %#v, %v", explanation, ok)
+	}
+}
+
+func TestFacadeDiffRejectsUnavailableResults(t *testing.T) {
+	type config struct {
+		Value string `yaml:"value"`
+	}
+	loaded, err := configkit.Load[config](configkit.Bytes("valid.yml", []byte("value: valid\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	var nilResult *configkit.Result[config]
+	zeroResult := &configkit.Result[config]{Config: config{Value: "must not be inspected"}}
+	for name, left := range map[string]*configkit.Result[config]{"nil": nilResult, "zero": zeroResult} {
+		t.Run(name, func(t *testing.T) {
+			if records, err := configkit.Diff(left, loaded); err == nil || records != nil {
+				t.Fatalf("Diff = %#v, %v; want nil records and error", records, err)
+			}
+		})
+	}
+	if records, err := configkit.Diff(loaded, nilResult); err == nil || records != nil {
+		t.Fatalf("right nil Diff = %#v, %v", records, err)
+	}
+}
+
+func TestFacadeDiffIgnoresSourceAndResolutionHistory(t *testing.T) {
+	type config struct {
+		Count int `yaml:"count"`
+	}
+	defaults := configkit.Options[config]{Definition: configkit.Definition[config]{
+		Defaults: func() config { return config{Count: 7} },
+	}}
+	defaulted, err := configkit.Load[config](configkit.NoSource(), defaults)
+	if err != nil {
+		t.Fatal(err)
+	}
+	explicit, err := configkit.Load[config](configkit.Bytes("explicit.yml", []byte("count: 7\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(defaulted, explicit); err != nil || len(differences) != 0 {
+		t.Fatalf("default/source difference = %#v, %v", differences, err)
+	}
+
+	zeroDefault, err := configkit.Load[config](configkit.NoSource(), configkit.Options[config]{Definition: configkit.Definition[config]{Defaults: func() config { return config{} }}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	explicitZero, err := configkit.Load[config](configkit.Bytes("explicit-zero.yml", []byte("count: 0\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(zeroDefault, explicitZero); err != nil || len(differences) != 0 {
+		t.Fatalf("explicit/defaulted zero difference = %#v, %v", differences, err)
+	}
+
+	resolve := func(value string) configkit.Options[config] {
+		return configkit.Options[config]{Definition: configkit.Definition[config]{Resolve: func(current *config, resolution *configkit.Resolution) error {
+			current.Count = len(value) + 8
+			resolution.Record(configkit.Keys("count"), configkit.ChangeNormalization, "set effective count")
+			return nil
+		}}}
+	}
+	resolvedA, err := configkit.Load[config](configkit.Bytes("a.yml", []byte("{}\n")), resolve("a"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	resolvedB, err := configkit.Load[config](configkit.Bytes("b.yml", []byte("{}\n")), resolve("b"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(resolvedA, resolvedB); err != nil || len(differences) != 0 {
+		t.Fatalf("equal resolved values = %#v, %v", differences, err)
+	}
+}
+
+func TestFacadeDiffUsesFrozenFilesAndRunsCallbacksOnlyDuringLoad(t *testing.T) {
+	type config struct {
+		Value string `yaml:"value"`
+	}
+	calls := 0
+	options := configkit.Options[config]{Definition: configkit.Definition[config]{Defaults: func() config {
+		calls++
+		return config{}
+	}}}
+	dir := t.TempDir()
+	paths := []string{filepath.Join(dir, "left.yml"), filepath.Join(dir, "right.yml")}
+	for index, contents := range []string{"value: left\n", "value: right\n"} {
+		if err := os.WriteFile(paths[index], []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	left, err := configkit.Load[config](configkit.File(paths[0]), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	right, err := configkit.Load[config](configkit.File(paths[1]), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 2 {
+		t.Fatalf("defaults calls after loads = %d", calls)
+	}
+	for _, path := range paths {
+		if err := os.Remove(path); err != nil {
+			t.Fatal(err)
+		}
+	}
+	differences, err := configkit.Diff(left, right)
+	if err != nil || len(differences) != 1 || differences[0].Path.String() != "/value" {
+		t.Fatalf("Diff after removing files = %#v, %v", differences, err)
+	}
+	if calls != 2 {
+		t.Fatalf("defaults reran during Diff: %d calls", calls)
+	}
+}
+
+func TestFacadeDiffCombinesSecretSensitivityAndLoadErrors(t *testing.T) {
+	t.Setenv("FACADE_DIFF_SECRET", "credential-one")
+	secretOptions := configkit.Options[facadeDiffSecretConfig]{Definition: configkit.Definition[facadeDiffSecretConfig]{Secret: func(path configkit.Path) bool {
+		return path.String() == "/secret"
+	}}}
+	left, err := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("left.yml", []byte("secret: FACADE_DIFF_SECRET\n")), secretOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("FACADE_DIFF_SECRET", "credential-two")
+	right, err := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("right.yml", []byte("secret: FACADE_DIFF_SECRET\n")), secretOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if differences, err := configkit.Diff(left, right); err != nil || len(differences) != 0 {
+		t.Fatalf("credential rotation = %#v, %v", differences, err)
+	}
+	t.Setenv("OTHER_FACADE_DIFF_SECRET", "other-credential")
+	otherReference, err := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("other.yml", []byte("secret: OTHER_FACADE_DIFF_SECRET\n")), secretOptions)
+	if err != nil {
+		t.Fatal(err)
+	}
+	differences, err := configkit.Diff(left, otherReference)
+	if err != nil || len(differences) != 1 || !differences[0].HiddenChanged || !differences[0].Left.Redacted || !differences[0].Right.Redacted {
+		t.Fatalf("reference change = %#v, %v", differences, err)
+	}
+	if strings.Contains(differences[0].Left.YAML+differences[0].Right.YAML, "credential") {
+		t.Fatalf("credential leaked: %#v", differences)
+	}
+
+	invalidLeft, leftErr := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("invalid-left.yml", []byte("unknown: true\n")))
+	if invalidLeft != nil || leftErr == nil {
+		t.Fatalf("invalid left load = %#v, %v", invalidLeft, leftErr)
+	}
+	var loadError *configkit.LoadError
+	if !errors.As(leftErr, &loadError) {
+		t.Fatalf("left load error = %T, want *configkit.LoadError", leftErr)
+	}
+	invalidRight, rightErr := configkit.Load[facadeDiffSecretConfig](configkit.Bytes("invalid-right.yml", []byte("unknown: true\n")))
+	if invalidRight != nil || rightErr == nil {
+		t.Fatalf("invalid right load = %#v, %v", invalidRight, rightErr)
+	}
+	if !errors.As(rightErr, &loadError) {
+		t.Fatalf("right load error = %T, want *configkit.LoadError", rightErr)
+	}
+}

facade_resource_context_test.go

@@ -2,10 +2,12 @@ package configkit_test
 
 import (
 	"errors"
+	"fmt"
 	"io/fs"
 	"os"
 	"path"
 	"path/filepath"
+	"reflect"
 	"strings"
 	"testing"
 	"testing/fstest"
@@ -219,3 +221,77 @@ func TestFacadeSyntheticSourceContextsAndContextlessSources(t *testing.T) {
 		t.Fatal("CLI source returned a context")
 	}
 }
+
+func TestFacadeRelativeImportDestinationsPreserveNativeResourceContexts(t *testing.T) {
+	borrowed := &observedResourceFS{files: fstest.MapFS{
+		"bundle/config/main.yml":                   &fstest.MapFile{Data: []byte("configkit:\n  imports:\n    - path: entries/parent.yml\n      destination: [logical]\n")},
+		"bundle/config/entries/parent.yml":         &fstest.MapFile{Data: []byte("configkit:\n  imports:\n    - path: nested/details.yml\n      destination: [details]\nresource: icon.txt\n")},
+		"bundle/config/entries/nested/details.yml": &fstest.MapFile{Data: []byte("resource: detail.txt\n")},
+		"bundle/config/entries/icon.txt":           &fstest.MapFile{Data: []byte("parent-resource")},
+		"bundle/config/entries/nested/detail.txt":  &fstest.MapFile{Data: []byte("nested-resource")},
+	}}
+	namespace := configkit.NewFilesystem("bundle", borrowed)
+	input := configkit.Input{
+		Source: namespace.File("bundle/config/main.yml"), Imports: true,
+		Filesystem: &configkit.FilesystemContext{Root: "bundle", FS: &namespace},
+	}
+	load := func() *configkit.Result[map[string]any] {
+		t.Helper()
+		result, err := configkit.LoadLayered[map[string]any](input)
+		if err != nil {
+			t.Fatalf("load relative native imports: %v", err)
+		}
+		return result
+	}
+	result := load()
+	wantDestinations := []string{configkit.Keys().String(), "/logical", "/logical/details"}
+	wantPaths := []string{"bundle/config/main.yml", "bundle/config/entries/parent.yml", "bundle/config/entries/nested/details.yml"}
+	sources := result.Sources()
+	if len(sources) != len(wantPaths) {
+		t.Fatalf("sources = %#v", sources)
+	}
+	for index, source := range sources {
+		if source.ID != fmt.Sprintf("source-%d", index+1) || source.Kind != configkit.SourceKindFilesystem || source.Path != wantPaths[index] || source.Destination.String() != wantDestinations[index] {
+			t.Errorf("source %d = %#v", index, source)
+		}
+		if index == 0 {
+			if source.ImportedFrom != nil {
+				t.Errorf("entry source has import location %#v", source.ImportedFrom)
+			}
+		} else if source.ImportedFrom == nil || source.ImportedFrom.SourceID != fmt.Sprintf("source-%d", index) || source.ImportedFrom.Line == 0 || source.ImportedFrom.Column == 0 {
+			t.Errorf("source %d import location = %#v", index, source.ImportedFrom)
+		}
+	}
+
+	for _, test := range []struct {
+		field, effectivePath, wantBase, wantResource, wantContents string
+	}{
+		{"parent resource", "/logical/resource", "config/entries", "icon.txt", "parent-resource"},
+		{"nested resource", "/logical/details/resource", "config/entries/nested", "detail.txt", "nested-resource"},
+	} {
+		info, ok := result.Metadata().Lookup(configkit.Keys(strings.Split(strings.Trim(test.effectivePath, "/"), "/")...))
+		if !ok || len(info.Origin.Locations) != 1 {
+			t.Fatalf("%s origin = %#v, %v", test.field, info, ok)
+		}
+		context, ok := result.SourceContext(info.Origin.Locations[0].SourceID)
+		if !ok || context.BaseDir != test.wantBase || context.FS == nil {
+			t.Fatalf("%s context = %#v, %v", test.field, context, ok)
+		}
+		contents, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, test.wantResource))
+		if err != nil || string(contents) != test.wantContents {
+			t.Fatalf("%s opened resource = %q, %v", test.field, contents, err)
+		}
+	}
+
+	sources[1].Destination = configkit.Keys("caller", "mutation")
+	for query := 0; query < 2; query++ {
+		fresh := result.Sources()
+		if fresh[1].Destination.String() != "/logical" {
+			t.Fatalf("query %d source destination = %q", query, fresh[1].Destination.String())
+		}
+	}
+	second := load()
+	if !reflect.DeepEqual(second.Sources(), result.Sources()) {
+		t.Fatalf("independent source records differ: %#v vs %#v", second.Sources(), result.Sources())
+	}
+}

facade_sequence_test.go

@@ -0,0 +1,669 @@
+package configkit_test
+
+import (
+	"bytes"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func TestFacadeNoSourcePreservesAbsenceWithSequencePolicy(t *testing.T) {
+	t.Parallel()
+	for _, defaults := range []bool{false, true} {
+		for _, registered := range []bool{false, true} {
+			definition := configkit.Definition[map[string]any]{}
+			if defaults {
+				definition.Defaults = func() map[string]any { return map[string]any{"fallback": true} }
+			}
+			if registered {
+				definition.SequenceCompositions = []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}
+			}
+			ordinary, err := configkit.Load(configkit.NoSource(), configkit.Options[map[string]any]{Definition: definition})
+			if err != nil {
+				t.Fatal(err)
+			}
+			layered, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{Definition: definition})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !reflect.DeepEqual(ordinary.Config, layered.Config) {
+				t.Fatal("NoSource values differ between entry points")
+			}
+			for _, result := range []*configkit.Result[map[string]any]{ordinary, layered} {
+				if len(result.Sources()) != 0 || result.Metadata().IsExplicit(configkit.Keys()) {
+					t.Fatal("NoSource contributed an explicit root")
+				}
+				info, ok := result.Metadata().Lookup(configkit.Keys())
+				if !ok || info.Origin.Layer != configkit.LayerDefault {
+					t.Fatalf("NoSource root origin = %#v, %t", info, ok)
+				}
+			}
+			empty, err := configkit.Load(configkit.Mapping("empty", map[string]any{}), configkit.Options[map[string]any]{Definition: definition})
+			if err != nil || !empty.Metadata().IsExplicit(configkit.Keys()) {
+				t.Fatal("real empty mapping lost its presence")
+			}
+		}
+	}
+}
+
+func TestFacadeItemHelperHistoryPreservesTraversalOrder(t *testing.T) {
+	t.Parallel()
+	filesystem := configkit.NewFilesystem("history", fstest.MapFS{
+		"main.yml":         {Data: []byte("records: [{id: authored}]\nconfigkit: {imports: [{path: one.yml, destination: [records], placement: sequence-item}, {path: two.yml, destination: [records], placement: sequence-item}]}\n")},
+		"one.yml":          {Data: []byte("id: one\nconfigkit: {imports: [{path: helper-one.yml}, {path: child.yml, destination: [children], placement: sequence-item}]}\n")},
+		"two.yml":          {Data: []byte("id: two\nconfigkit: {imports: [{path: helper-two.yml}]}\n")},
+		"helper-one.yml":   {Data: []byte("text: first helper\n")},
+		"helper-two.yml":   {Data: []byte("text: second helper\n")},
+		"child.yml":        {Data: []byte("id: child\nconfigkit: {imports: [{path: child-helper.yml}]}\n")},
+		"child-helper.yml": {Data: []byte("text: nested helper\n")},
+	})
+	result, err := configkit.Load(filesystem.File("main.yml"), configkit.Options[map[string]any]{
+		Imports: true, Definition: configkit.Definition[map[string]any]{SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sourceOrder := make(map[string]int)
+	sourceFiles := make(map[string]string)
+	for index, source := range result.Sources() {
+		sourceOrder[source.ID] = index
+		sourceFiles[source.ID] = source.Path
+	}
+	for _, test := range []struct {
+		path       configkit.Path
+		file, text string
+	}{
+		{configkit.Keys("records").Index(1).Key("text"), "helper-one.yml", "first helper\n"},
+		{configkit.Keys("records").Index(2).Key("text"), "helper-two.yml", "second helper\n"},
+		{configkit.Keys("records").Index(1).Key("children").Index(0).Key("text"), "child-helper.yml", "nested helper\n"},
+	} {
+		explanation, ok := result.Explain(test.path)
+		if !ok || explanation.Effective.YAML != test.text || len(explanation.History) != 1 {
+			t.Fatalf("helper history at %s = %#v", test.path.String(), explanation)
+		}
+		locations := explanation.History[0].Origin.Locations
+		if len(locations) != 1 || sourceFiles[locations[0].SourceID] != test.file {
+			t.Fatalf("helper origin at %s = %#v", test.path.String(), locations)
+		}
+		info, ok := result.Metadata().Lookup(test.path)
+		if !ok || len(info.Origin.Locations) != 1 || info.Origin.Locations[0].SourceID != locations[0].SourceID {
+			t.Fatal("metadata and explanation disagree")
+		}
+	}
+	explanation, ok := result.Explain(configkit.Keys())
+	if !ok {
+		t.Fatal("root explanation missing")
+	}
+	previous := -1
+	for _, change := range explanation.History {
+		for _, location := range change.Origin.Locations {
+			current := sourceOrder[location.SourceID]
+			if current < previous {
+				t.Fatalf("source %s replayed out of traversal order", location.SourceID)
+			}
+			previous = current
+		}
+	}
+}
+
+func TestFacadeRegisteredReplacementExplainsRemovedDescendants(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name  string
+		upper []any
+		path  configkit.Path
+	}{
+		{"shorter", []any{map[string]any{"id": "main"}}, configkit.Keys("records").Index(1).Key("id")},
+		{"empty", []any{}, configkit.Keys("records").Index(0).Key("id")},
+		{"removed field", []any{map[string]any{"id": "main"}}, configkit.Keys("records").Index(0).Key("text")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Mapping("main", map[string]any{"records": test.upper})}, configkit.LayeredOptions[map[string]any]{
+				Definition: configkit.Definition[map[string]any]{SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}},
+				Underlays:  []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Mapping("lower", map[string]any{"records": []any{map[string]any{"id": "one", "text": "old"}, map[string]any{"id": "two"}}})}}}},
+			})
+			if err != nil {
+				t.Fatal(err)
+			}
+			explanation, ok := result.Explain(test.path)
+			if !ok || explanation.Effective.Present || len(explanation.History) < 2 {
+				t.Fatalf("removal not explained: %#v", explanation)
+			}
+			last := explanation.History[len(explanation.History)-1]
+			if !last.Before.Present || last.After.Present || last.Origin.Layer != configkit.LayerBase || len(last.Origin.Locations) != 1 || last.Origin.Locations[0].SourceID != result.Sources()[0].ID {
+				t.Fatalf("wrong removal transition/origin: %#v", last)
+			}
+		})
+	}
+}
+
+func TestFacadeItemConflictDiagnosticsFollowEnclosingIndexes(t *testing.T) {
+	t.Parallel()
+	filesystem := configkit.NewFilesystem("conflicts", fstest.MapFS{
+		"main.yml":   {Data: []byte("records: [{id: authored}]\nconfigkit: {imports: [{path: good.yml, destination: [records], placement: sequence-item}, {path: bad.yml, destination: [records], placement: sequence-item}]}\n")},
+		"group.yml":  {Data: []byte("records: [{id: authored}]\nconfigkit: {imports: [{path: bad.yml, destination: [records], placement: sequence-item}]}\n")},
+		"nested.yml": {Data: []byte("records: [{id: authored}]\nconfigkit: {imports: [{path: parent.yml, destination: [records], placement: sequence-item}]}\n")},
+		"parent.yml": {Data: []byte("id: parent\nchildren: [{id: authored-child}]\nconfigkit: {imports: [{path: bad.yml, destination: [children], placement: sequence-item}]}\n")},
+		"good.yml":   {Data: []byte("id: good\n")},
+		"bad.yml":    {Data: []byte("id: bad\nconfigkit: {imports: [{path: helper.yml}]}\n")},
+		"helper.yml": {Data: []byte("id: duplicate-field\n")},
+	})
+	definition := configkit.Definition[map[string]any]{SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}}
+	for _, test := range []struct {
+		name, file, path  string
+		grouped, itemMain bool
+	}{
+		{"preceding authored and imported items", "main.yml", "/records/2/id", false, false},
+		{"nested item", "nested.yml", "/records/1/children/1/id", false, false},
+		{"preceding grouped input", "group.yml", "/records/2/id", true, false},
+		{"item main source", "bad.yml", "/records/0/id", false, true},
+		{"grouped item source", "bad.yml", "/records/1/id", true, true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			var err error
+			input := configkit.Input{Source: filesystem.File(test.file), Imports: true}
+			if test.itemMain {
+				input.Destination = configkit.Keys("records")
+				input.PlacementMode = configkit.PlacementModeSequenceItem
+			}
+			if test.grouped {
+				_, err = configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{
+					Definition: definition, Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+						{Source: configkit.Mapping("prior", map[string]any{"records": []any{map[string]any{"id": "prior"}}})},
+						input,
+					}}},
+				})
+			} else {
+				_, err = configkit.Load(input.Source, configkit.Options[map[string]any]{Definition: definition, Imports: true, Destination: input.Destination, PlacementMode: input.PlacementMode})
+			}
+			loadError, ok := err.(*configkit.LoadError)
+			if !ok || len(loadError.Diagnostics()) != 1 {
+				t.Fatalf("expected helper conflict: %v", err)
+			}
+			diagnostic := loadError.Diagnostics()[0]
+			if diagnostic.Code != configkit.CodeComposeConflict || diagnostic.Path.String() != test.path {
+				t.Fatalf("diagnostic = %s %s, want %s", diagnostic.Code, diagnostic.Path.String(), test.path)
+			}
+			files := make(map[string]string)
+			for _, source := range loadError.Sources() {
+				files[source.ID] = source.Path
+			}
+			if diagnostic.Primary == nil || files[diagnostic.Primary.SourceID] != "bad.yml" || len(diagnostic.Related) != 1 || files[diagnostic.Related[0].SourceID] != "helper.yml" {
+				t.Fatal("conflict lost physical source locations")
+			}
+		})
+	}
+}
+
+func TestFacadeSequencePlacementControlsAcrossLoadEntryPoints(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{
+		SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("entries"), IdentityField: "id"}},
+	}
+	ordinary, err := configkit.Load(configkit.Mapping("ordinary", map[string]any{"id": "one"}), configkit.Options[map[string]any]{
+		Definition: definition, Destination: configkit.Keys("entries"), PlacementMode: configkit.PlacementModeSequenceItem,
+	})
+	if err != nil {
+		t.Fatalf("ordinary item load: %v", err)
+	}
+	if got := ordinary.Config["entries"].([]any); len(got) != 1 || got[0].(map[string]any)["id"] != "one" {
+		t.Fatalf("ordinary item placement = %#v", ordinary.Config)
+	}
+	if sources := ordinary.Sources(); len(sources) != 1 || sources[0].PlacementMode != configkit.PlacementModeSequenceItem || sources[0].Destination.String() != "/entries" || sources[0].DestinationUnresolved {
+		t.Fatalf("ordinary item source = %#v", sources)
+	}
+
+	layered, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition,
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+			{Source: configkit.Mapping("first", map[string]any{"id": "first"}), Destination: configkit.Keys("entries"), PlacementMode: configkit.PlacementModeSequenceItem},
+			{Source: configkit.Mapping("second", map[string]any{"id": "second"}), Destination: configkit.Keys("entries"), PlacementMode: configkit.PlacementModeSequenceItem},
+		}}},
+	})
+	if err != nil {
+		t.Fatalf("layered item load: %v", err)
+	}
+	items := layered.Config["entries"].([]any)
+	if len(items) != 2 || items[0].(map[string]any)["id"] != "first" || items[1].(map[string]any)["id"] != "second" {
+		t.Fatalf("layered item placement = %#v", layered.Config)
+	}
+	for _, source := range layered.Sources() {
+		if source.PlacementMode != configkit.PlacementModeSequenceItem || source.Destination.String() != "/entries" || source.DestinationUnresolved {
+			t.Errorf("layered item source = %#v", source)
+		}
+	}
+
+	precedence, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Mapping("main", map[string]any{
+		"entries": []any{map[string]any{"id": "main"}},
+	})}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition,
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Mapping("lower", map[string]any{"id": "lower"}), Destination: configkit.Keys("entries"), PlacementMode: configkit.PlacementModeSequenceItem,
+		}}}},
+	})
+	if err != nil {
+		t.Fatalf("registered sequence precedence load: %v", err)
+	}
+	if got := precedence.Config["entries"].([]any); len(got) != 1 || got[0].(map[string]any)["id"] != "main" {
+		t.Fatalf("higher-priority list did not replace the lower sequence: %#v", precedence.Config)
+	}
+
+	for _, test := range []struct {
+		name string
+		load func(configkit.Source) error
+	}{
+		{name: "ordinary", load: func(source configkit.Source) error {
+			_, loadErr := configkit.Load(source, configkit.Options[map[string]any]{PlacementMode: configkit.PlacementMode(9)})
+			return loadErr
+		}},
+		{name: "layered", load: func(source configkit.Source) error {
+			_, loadErr := configkit.LoadLayered[map[string]any](configkit.Input{Source: source, PlacementMode: configkit.PlacementMode(9)})
+			return loadErr
+		}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			reader := &destinationCountingReader{}
+			err := test.load(configkit.Reader("unread", reader))
+			loadError, ok := err.(*configkit.LoadError)
+			if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeOptionsInvalid || reader.reads != 0 {
+				t.Fatalf("invalid placement result = %v, reads = %d", err, reader.reads)
+			}
+		})
+	}
+}
+
+func TestFacadeItemImportGlobComposesWithAuthoredSequence(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	if err := os.WriteFile(mainPath, []byte(`configkit:
+  imports:
+    - glob: records/*.yml
+      destination: [items]
+      placement: sequence-item
+items:
+  - id: authored
+    name: authored item
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	for name, id := range map[string]string{"b.yml": "imported-b", "a.yml": "imported-a"} {
+		if err := os.MkdirAll(filepath.Join(directory, "records"), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(filepath.Join(directory, "records", name), []byte("id: "+id+"\n"), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+	var callbackSources []configkit.SourceInfo
+	var callbackContexts []configkit.ResourceContext
+	result, err := configkit.Load(configkit.File(mainPath), configkit.Options[map[string]any]{
+		Imports: true,
+		Definition: configkit.Definition[map[string]any]{
+			SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("items"), IdentityField: "id"}},
+			Resolve: func(_ *map[string]any, resolution *configkit.Resolution) error {
+				for _, id := range []string{"source-2", "source-3"} {
+					source, ok := resolution.Source(id)
+					if !ok {
+						t.Errorf("resolver could not query %s", id)
+						continue
+					}
+					context, found := resolution.SourceContext(id)
+					if !found || context.FS == nil || context.BaseDir != "records" {
+						t.Errorf("resolver context for %s = %#v, %v", id, context, found)
+					}
+					callbackSources = append(callbackSources, source)
+					callbackContexts = append(callbackContexts, context)
+				}
+				return nil
+			},
+		},
+	})
+	if err != nil {
+		t.Fatalf("load item glob: %v", err)
+	}
+	items := result.Config["items"].([]any)
+	wantIDs := []string{"authored", "imported-a", "imported-b"}
+	for index, item := range items {
+		if got := item.(map[string]any)["id"]; got != wantIDs[index] {
+			t.Errorf("item %d ID = %#v, want %q", index, got, wantIDs[index])
+		}
+	}
+	if len(callbackSources) != 2 || len(callbackContexts) != 2 {
+		t.Fatalf("callback snapshots = %#v, contexts %#v", callbackSources, callbackContexts)
+	}
+	for index, source := range callbackSources {
+		if source.PlacementMode != configkit.PlacementModeSequenceItem || source.Destination.String() != "/items" || source.DestinationUnresolved {
+			t.Errorf("callback source = %#v", source)
+		}
+		if callbackContexts[index].FS == nil || callbackContexts[index].BaseDir != "records" {
+			t.Errorf("callback context = %#v", callbackContexts[index])
+		}
+	}
+	metadata := result.Metadata()
+	for index := 1; index < len(wantIDs); index++ {
+		path := configkit.Keys("items").Index(index).Key("id")
+		info, ok := metadata.Lookup(path)
+		if !ok || !info.Explicit || len(info.Origin.Locations) != 1 || info.Origin.Locations[0].SourceID != []string{"source-2", "source-3"}[index-1] {
+			t.Errorf("shifted item origin at %s = %#v, %v", path.String(), info, ok)
+		}
+	}
+	if got := result.Sources(); len(got) != 3 || got[1].Destination.String() != "/items" || got[1].DestinationUnresolved {
+		t.Fatalf("final item sources = %#v", got)
+	}
+}
+
+func TestFacadeItemDestinationFallbackEvidenceSurvivesFailures(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	helperPath := filepath.Join(directory, "helper.yml")
+	if err := os.WriteFile(mainPath, []byte("configkit: {imports: [{path: helper.yml, destination: [metadata]}]}\nid: main\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(helperPath, []byte("value: [unterminated\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	_, err := configkit.Load(configkit.File(mainPath), configkit.Options[map[string]any]{
+		Imports: true, Destination: configkit.Keys("items"), PlacementMode: configkit.PlacementModeSequenceItem,
+	})
+	loadError, ok := err.(*configkit.LoadError)
+	if !ok {
+		t.Fatalf("early failure = %v", err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != "/items" || sources[0].DestinationUnresolved ||
+		sources[0].PlacementMode != configkit.PlacementModeSequenceItem ||
+		sources[1].Destination.String() != "/items" || !sources[1].DestinationUnresolved ||
+		sources[1].PlacementMode != configkit.PlacementModeMapping {
+		t.Fatalf("early source snapshots = %#v", sources)
+	}
+
+	if err := os.WriteFile(helperPath, []byte("value: invalid-for-typed-schema\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	type item struct {
+		ID       string `yaml:"id"`
+		Metadata struct {
+			Value int `yaml:"value"`
+		} `yaml:"metadata"`
+	}
+	type configuration struct {
+		Items []item `yaml:"items"`
+	}
+	_, err = configkit.Load(configkit.File(mainPath), configkit.Options[configuration]{
+		Imports: true, Destination: configkit.Keys("items"), PlacementMode: configkit.PlacementModeSequenceItem,
+	})
+	loadError, ok = err.(*configkit.LoadError)
+	if !ok {
+		t.Fatalf("post-placement failure = %v", err)
+	}
+	sources = loadError.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != "/items" || sources[0].DestinationUnresolved ||
+		sources[1].Destination.String() != "/items/0/metadata" || sources[1].DestinationUnresolved {
+		t.Fatalf("post-placement source snapshots = %#v", sources)
+	}
+	firstSnapshot := sources[1]
+	sources[1].Destination = configkit.Keys("mutated")
+	if again := loadError.Sources(); len(again) != 2 || again[1].Destination.String() != firstSnapshot.Destination.String() || again[1].DestinationUnresolved {
+		t.Fatalf("failure source snapshots were aliased: %#v", again)
+	}
+
+	var callback configkit.SourceInfo
+	_, err = configkit.Load(configkit.File(mainPath), configkit.Options[map[string]any]{
+		Imports: true, Destination: configkit.Keys("items"), PlacementMode: configkit.PlacementModeSequenceItem,
+		Definition: configkit.Definition[map[string]any]{Resolve: func(_ *map[string]any, resolution *configkit.Resolution) error {
+			callback, _ = resolution.Source("source-2")
+			return nil
+		}},
+	})
+	if err != nil {
+		t.Fatalf("successful item load: %v", err)
+	}
+	if callback.Destination.String() != "/items/0/metadata" || callback.DestinationUnresolved || callback.PlacementMode != configkit.PlacementModeMapping {
+		t.Fatalf("callback source snapshot = %#v", callback)
+	}
+}
+
+func TestFacadeNestedItemFallbackUsesNearestResolvedContainer(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	childPath := filepath.Join(directory, "child.yml")
+	helperPath := filepath.Join(directory, "helper.yml")
+	if err := os.WriteFile(mainPath, []byte("configkit: {imports: [{path: child.yml, destination: [children], placement: sequence-item}]}\nid: parent\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(childPath, []byte("configkit: {imports: [{path: helper.yml, destination: [metadata]}]}\nid: child\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(helperPath, []byte("value: [unterminated\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	_, err := configkit.Load(configkit.File(mainPath), configkit.Options[map[string]any]{
+		Imports: true, Destination: configkit.Keys("groups"), PlacementMode: configkit.PlacementModeSequenceItem,
+	})
+	loadError, ok := err.(*configkit.LoadError)
+	if !ok {
+		t.Fatalf("nested acquisition failure = %v", err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 3 {
+		t.Fatalf("nested source snapshots = %#v", sources)
+	}
+	if got := sources[0]; got.Destination.String() != "/groups" || got.DestinationUnresolved || got.PlacementMode != configkit.PlacementModeSequenceItem {
+		t.Errorf("outer item snapshot = %#v", got)
+	}
+	if got := sources[1]; got.Destination.String() != "/groups" || !got.DestinationUnresolved || got.PlacementMode != configkit.PlacementModeSequenceItem {
+		t.Errorf("nested item fallback = %#v", got)
+	}
+	if got := sources[2]; got.Destination.String() != "/groups" || !got.DestinationUnresolved || got.PlacementMode != configkit.PlacementModeMapping {
+		t.Errorf("nested helper fallback = %#v", got)
+	}
+}
+
+func TestFacadeSequenceCompositionRegistrationPathIsDetached(t *testing.T) {
+	registrations := []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}
+	definition := configkit.Definition[map[string]any]{
+		SequenceCompositions: registrations,
+		Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(configkit.Version, *configkit.Validation) error {
+				registrations[0].Path = configkit.Keys("other")
+				registrations[0].IdentityField = "changed"
+				return nil
+			},
+		},
+	}
+	_, err := configkit.Load(configkit.Mapping("registration", map[string]any{
+		"version": "1",
+		"records": []any{map[string]any{"id": "same"}, map[string]any{"id": "same"}},
+	}), configkit.Options[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+	})
+	loadError, ok := err.(*configkit.LoadError)
+	if !ok {
+		t.Fatalf("duplicate registered identity = %v", err)
+	}
+	for _, diagnostic := range loadError.Diagnostics() {
+		if diagnostic.Code == configkit.CodeComposeConflict {
+			return
+		}
+	}
+	t.Fatalf("registration mutation changed the in-flight policy: %#v", loadError.Diagnostics())
+}
+
+func TestFacadeSourceInfoPlacementCopiesAndZeroValues(t *testing.T) {
+	zero := configkit.SourceInfo{}
+	if zero.PlacementMode != configkit.PlacementModeMapping || zero.DestinationUnresolved {
+		t.Fatalf("zero source info = %#v", zero)
+	}
+	loaded, err := configkit.Load[map[string]any](configkit.Mapping("mapping", map[string]any{"value": true}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	sources := loaded.Sources()
+	if len(sources) != 1 || sources[0].PlacementMode != configkit.PlacementModeMapping || sources[0].DestinationUnresolved {
+		t.Fatalf("mapping source evidence = %#v", sources)
+	}
+	first := sources[0]
+	first.Destination = configkit.Keys("caller")
+	if again := loaded.Sources(); len(again) != 1 || again[0].Destination.String() != "" || again[0].DestinationUnresolved {
+		t.Fatalf("source evidence changed after caller mutation: %#v", again)
+	}
+}
+
+func TestFacadeSequenceReplacementKeepsTypedAndHistoricalEvidenceAligned(t *testing.T) {
+	type record struct {
+		ID       string  `yaml:"id"`
+		Count    int     `yaml:"count"`
+		Enabled  bool    `yaml:"enabled"`
+		Empty    string  `yaml:"empty"`
+		Nullable *string `yaml:"nullable"`
+		Token    string  `yaml:"token"`
+		Omitted  string  `yaml:"omitted"`
+	}
+	type configuration struct {
+		Entries []record `yaml:"entries"`
+	}
+
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	underlayPath := filepath.Join(directory, "underlay.yml")
+	if err := os.WriteFile(mainPath, []byte(`entries:
+  - id: current
+    count: 0
+    enabled: false
+    empty: ""
+    nullable: null
+    token: CURRENT-SECRET-CANARY
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(underlayPath, []byte(`configkit:
+  imports:
+    - glob: records/*.yml
+      destination: [entries]
+      placement: sequence-item
+`), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	recordsDir := filepath.Join(directory, "records")
+	if err := os.MkdirAll(recordsDir, 0o700); err != nil {
+		t.Fatal(err)
+	}
+	for name, body := range map[string]string{
+		"a.yml": "id: old-a\ntoken: OLD-SECRET-CANARY-A\n",
+		"b.yml": "id: old-b\ntoken: OLD-SECRET-CANARY-B\n",
+	} {
+		if err := os.WriteFile(filepath.Join(recordsDir, name), []byte(body), 0o600); err != nil {
+			t.Fatal(err)
+		}
+	}
+
+	var callbackItems []configkit.SourceInfo
+	var callbackContexts []configkit.ResourceContext
+	result, err := configkit.LoadLayered(configkit.Input{Source: configkit.File(mainPath)}, configkit.LayeredOptions[configuration]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.File(underlayPath), Imports: true}}}},
+		Definition: configkit.Definition[configuration]{
+			SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("entries"), IdentityField: "id"}},
+			Secret: func(path configkit.Path) bool {
+				return path.String() == "/entries/0/token" || path.String() == "/entries/1/token"
+			},
+			Resolve: func(value *configuration, resolution *configkit.Resolution) error {
+				for _, field := range []string{"count", "enabled", "empty", "nullable"} {
+					path := configkit.Keys("entries").Index(0).Key(field)
+					if !resolution.IsExplicit(path) {
+						t.Errorf("resolver did not see explicit %s", path.String())
+					}
+				}
+				if resolution.IsExplicit(configkit.Keys("entries").Index(0).Key("omitted")) {
+					t.Error("resolver treated an omitted field as explicit")
+				}
+				info, found := resolution.InputInfo(configkit.Keys("entries").Index(0).Key("count"))
+				if !found || info.Origin.Layer != configkit.LayerBase {
+					t.Errorf("resolver current-record input info = %#v, %v", info, found)
+				}
+				for _, id := range []string{"source-3", "source-4"} {
+					source, ok := resolution.Source(id)
+					if !ok {
+						t.Errorf("resolver could not query %s", id)
+						continue
+					}
+					context, contextOK := resolution.SourceContext(id)
+					if !contextOK || context.FS == nil || context.BaseDir != "records" {
+						t.Errorf("resolver context for %s = %#v, %v", id, context, contextOK)
+					}
+					callbackItems = append(callbackItems, source)
+					callbackContexts = append(callbackContexts, context)
+				}
+				return nil
+			},
+		},
+	})
+	if err != nil {
+		if loadError, ok := err.(*configkit.LoadError); ok {
+			t.Fatalf("layered item replacement: %#v", loadError.Diagnostics())
+		}
+		t.Fatalf("layered item replacement: %v", err)
+	}
+	if len(result.Config.Entries) != 1 || result.Config.Entries[0].ID != "current" || result.Config.Entries[0].Count != 0 ||
+		result.Config.Entries[0].Enabled || result.Config.Entries[0].Empty != "" || result.Config.Entries[0].Nullable != nil {
+		t.Fatalf("typed replacement result = %#v", result.Config)
+	}
+	if len(callbackItems) != 2 || len(callbackContexts) != 2 {
+		t.Fatalf("callback sources = %#v; contexts = %#v", callbackItems, callbackContexts)
+	}
+	for _, source := range callbackItems {
+		if source.PlacementMode != configkit.PlacementModeSequenceItem || source.Destination.String() != "/entries" || source.DestinationUnresolved {
+			t.Errorf("callback item source = %#v", source)
+		}
+	}
+	metadata := result.Metadata()
+	for _, field := range []string{"count", "enabled", "empty", "nullable"} {
+		path := configkit.Keys("entries").Index(0).Key(field)
+		if info, ok := metadata.Lookup(path); !ok || !info.Explicit || (field == "nullable") != info.Null {
+			t.Errorf("explicit metadata at %s = %#v, %v", path.String(), info, ok)
+		}
+	}
+	if info, ok := metadata.Lookup(configkit.Keys("entries").Index(0).Key("omitted")); ok && info.Explicit {
+		t.Errorf("metadata marked an omitted zero-valued field explicit: %#v", info)
+	}
+	mainID := ""
+	for _, source := range result.Sources() {
+		if source.Path == mainPath {
+			mainID = source.ID
+		}
+	}
+	currentOrigin, ok := metadata.Lookup(configkit.Keys("entries").Index(0).Key("id"))
+	if !ok || len(currentOrigin.Origin.Locations) != 1 || currentOrigin.Origin.Locations[0].SourceID != mainID || mainID == "" {
+		t.Fatalf("replacement origin = %#v, main source %q", currentOrigin, mainID)
+	}
+	oldRecord, ok := result.Explain(configkit.Keys("entries").Index(1).Key("token"))
+	if !ok || oldRecord.Effective.Present {
+		t.Fatalf("removed appended item explanation = %#v, %v", oldRecord, ok)
+	}
+	maskedHistory := false
+	for _, change := range oldRecord.History {
+		maskedHistory = maskedHistory || change.Before.Redacted || change.After.Redacted
+	}
+	if !maskedHistory {
+		t.Fatal("removed appended item lost historical sensitivity")
+	}
+	var effective bytes.Buffer
+	if err := result.WriteEffective(&effective); err != nil {
+		t.Fatal(err)
+	}
+	var explanation bytes.Buffer
+	if err := result.WriteExplanation(&explanation, configkit.Keys("entries").Index(1).Key("token")); err != nil {
+		t.Fatal(err)
+	}
+	for _, output := range []string{effective.String(), explanation.String()} {
+		for _, canary := range []string{"CURRENT-SECRET-CANARY", "OLD-SECRET-CANARY-A", "OLD-SECRET-CANARY-B"} {
+			if strings.Contains(output, canary) {
+				t.Fatalf("sensitive sequence value leaked: %s", output)
+			}
+		}
+	}
+}

facade_source_version_mode_test.go

@@ -0,0 +1,879 @@
+package configkit_test
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func TestFacadeSourceVersionEvidenceFollowsAuthoredSequenceRanges(t *testing.T) {
+	t.Parallel()
+	for _, grouped := range []bool{false, true} {
+		for _, sensitivePath := range []string{"", "/records/1/version", "/records/1"} {
+			t.Run(fmt.Sprintf("grouped=%t/secret=%s", grouped, sensitivePath), func(t *testing.T) {
+				definition := configkit.Definition[map[string]any]{
+					SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}},
+					Version:              &configkit.VersionRule{Path: configkit.Keys("records").Index(0).Key("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil }},
+					Secret:               func(path configkit.Path) bool { return sensitivePath != "" && path.String() == sensitivePath },
+				}
+				first := "records: [{id: first, version: first-version}]\n"
+				child := "records: [{id: child, version: PRIVATE-VERSION-CANARY}]\n"
+				var result *configkit.Result[map[string]any]
+				var err error
+				if grouped {
+					result, err = configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte(first))}, configkit.LayeredOptions[map[string]any]{
+						Definition: definition, SourceVersionMode: configkit.SourceVersionModeRequired,
+						Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+							{Source: configkit.Bytes("first", []byte(first))}, {Source: configkit.Bytes("child", []byte(child))},
+						}}},
+					})
+				} else {
+					filesystem := configkit.NewFilesystem("versions", fstest.MapFS{
+						"main.yml":  {Data: []byte("configkit: {imports: [{path: child.yml}]}\n" + first)},
+						"child.yml": {Data: []byte(child)},
+					})
+					result, err = configkit.Load(filesystem.File("main.yml"), configkit.Options[map[string]any]{
+						Definition: definition, Imports: true, SourceVersionMode: configkit.SourceVersionModeRequired,
+					})
+				}
+				if err != nil {
+					t.Fatal(err)
+				}
+				sources := result.Sources()
+				check := sources[len(sources)-1].VersionCheck
+				if check == nil || check.Path.String() != "/records/0/version" || check.Location == nil || check.Location.SourceID != sources[len(sources)-1].ID {
+					t.Fatalf("source-local evidence changed: %#v", check)
+				}
+				if sensitivePath != "" {
+					if !check.Redacted || check.Version.Text != "" {
+						t.Fatal("shifted version evidence was disclosed")
+					}
+				} else if check.Redacted || check.Version.Text != "PRIVATE-VERSION-CANARY" {
+					t.Fatal("unclassified version evidence was lost")
+				}
+			})
+		}
+	}
+}
+
+func TestFacadeSourceVersionOwnershipAcceptsContextualIndexes(t *testing.T) {
+	t.Parallel()
+	parsed, err := configkit.ParsePath("/records/0/version")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, grouped := range []bool{false, true} {
+		for _, path := range []configkit.Path{configkit.Keys("records").Index(0).Key("version"), parsed} {
+			definition := configkit.Definition[map[string]any]{
+				SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}},
+				Version:              &configkit.VersionRule{Path: path, Check: func(configkit.Version, *configkit.Validation) error { return nil }},
+			}
+			first := "records: [{id: first, version: first}]\n"
+			child := "records: [{id: child, version: child}]\n"
+			var result *configkit.Result[map[string]any]
+			if grouped {
+				result, err = configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte(first))}, configkit.LayeredOptions[map[string]any]{
+					Definition: definition, SourceVersionMode: configkit.SourceVersionModeRequired,
+					Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("lower", []byte(child))}}}},
+				})
+			} else {
+				filesystem := configkit.NewFilesystem("versions", fstest.MapFS{"main.yml": {Data: []byte("configkit: {imports: [{path: child.yml}]}\n" + first)}, "child.yml": {Data: []byte(child)}})
+				result, err = configkit.Load(filesystem.File("main.yml"), configkit.Options[map[string]any]{Definition: definition, SourceVersionMode: configkit.SourceVersionModeRequired, Imports: true})
+			}
+			if err != nil || result == nil {
+				t.Fatalf("grouped=%t path=%#v: %v", grouped, path, err)
+			}
+			want := 2
+			if grouped {
+				want = 1
+			}
+			if len(result.Config["records"].([]any)) != want {
+				t.Fatal("version path changed composition")
+			}
+		}
+	}
+}
+
+func TestFacadeItemMainKeepsDefaultVersionOwnership(t *testing.T) {
+	t.Parallel()
+	for _, layered := range []bool{false, true} {
+		for _, protected := range []bool{true, false} {
+			body, helper := "id: main\n", "version: imported-version\n"
+			if !protected {
+				body += "version: main-version\n"
+				helper = "other: {version: permitted}\n"
+			}
+			filesystem := configkit.NewFilesystem("item-main", fstest.MapFS{
+				"main.yml": {Data: []byte(body + "configkit: {imports: [{path: helper.yml}]}\n")}, "helper.yml": {Data: []byte(helper)},
+			})
+			checks := 0
+			definition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+				Path: configkit.Keys("records").Index(0).Key("version"),
+				Check: func(version configkit.Version, _ *configkit.Validation) error {
+					checks++
+					if version.Text != "main-version" {
+						t.Error("helper supplied main version")
+					}
+					return nil
+				},
+			}}
+			var err error
+			if layered {
+				_, err = configkit.LoadLayered[map[string]any](configkit.Input{Source: filesystem.File("main.yml"), Imports: true, Destination: configkit.Keys("records"), PlacementMode: configkit.PlacementModeSequenceItem}, configkit.LayeredOptions[map[string]any]{Definition: definition})
+			} else {
+				_, err = configkit.Load(filesystem.File("main.yml"), configkit.Options[map[string]any]{Definition: definition, Imports: true, Destination: configkit.Keys("records"), PlacementMode: configkit.PlacementModeSequenceItem})
+			}
+			if protected {
+				loadError, ok := err.(*configkit.LoadError)
+				if !ok || len(loadError.Diagnostics()) != 1 || loadError.Diagnostics()[0].Code != configkit.CodeImportVersion || loadError.Diagnostics()[0].Path.String() != "/records/0/version" || checks != 0 {
+					t.Fatalf("layered=%t ownership error = %v, checks=%d", layered, err, checks)
+				}
+			} else if err != nil || checks != 1 {
+				t.Fatalf("unrelated helper version rejected: %v, checks=%d", err, checks)
+			}
+		}
+	}
+}
+
+type sourceVersionModeReader struct {
+	*strings.Reader
+	reads int
+}
+
+func TestFacadeSourceVersionEvidenceRedactsCollidingShapes(t *testing.T) {
+	t.Parallel()
+	type header struct {
+		Version string `yaml:"version"`
+	}
+	type secretHeader struct {
+		Version string `yaml:"version" configkit:"secret"`
+	}
+	type configuration struct {
+		Meta map[string]header `yaml:"meta"`
+		Data struct {
+			Meta map[string]secretHeader `yaml:"meta"`
+		} `yaml:"data"`
+	}
+	path, err := configkit.ParsePath("/meta/0/version")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, reverse := range []bool{false, true} {
+		groups := []configkit.Underlay{
+			{Inputs: []configkit.Input{{
+				Source:      configkit.Bytes("mapping", []byte("meta: {\"0\": {version: PRIVATE-HEADER-CANARY}}\n")),
+				Destination: configkit.Keys("data"),
+			}}},
+			{Inputs: []configkit.Input{{
+				Source:      configkit.Bytes("sequence", []byte("meta: [{version: another-header}]\n")),
+				Destination: configkit.Keys("data"),
+			}}},
+		}
+		if reverse {
+			groups[0], groups[1] = groups[1], groups[0]
+		}
+		loaded, err := configkit.LoadLayered(configkit.Input{
+			Source: configkit.Bytes("main", []byte("meta: {\"0\": {version: main}}\ndata: {meta: null}\n")),
+		}, configkit.LayeredOptions[configuration]{
+			Definition: configkit.Definition[configuration]{Version: &configkit.VersionRule{
+				Path: path, Check: func(configkit.Version, *configkit.Validation) error { return nil },
+			}},
+			SourceVersionMode: configkit.SourceVersionModeRequired, Underlays: groups,
+		})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if loaded.Config.Meta["0"].Version != "main" || loaded.Config.Data.Meta != nil {
+			t.Fatalf("reverse=%v: final payload changed: %#v", reverse, loaded.Config)
+		}
+		foundMapping := false
+		for _, source := range loaded.Sources() {
+			if source.Label != "mapping" {
+				continue
+			}
+			foundMapping = true
+			if check := source.VersionCheck; check == nil || !check.Version.Present || !check.Redacted || check.Version.Text != "" {
+				t.Errorf("reverse=%v: schema-tagged header was not redacted", reverse)
+			}
+		}
+		if !foundMapping {
+			t.Fatal("missing mapping source record")
+		}
+	}
+}
+
+func TestFacadeSourceVersionModesPreserveImportOptIn(t *testing.T) {
+	t.Parallel()
+	for _, mode := range []configkit.SourceVersionMode{configkit.SourceVersionModeIfPresent, configkit.SourceVersionModeRequired} {
+		for _, underlay := range []bool{false, true} {
+			bad := configkit.Bytes("disabled-imports", []byte("version: accepted\nconfigkit: {imports: [{path: missing.yml}]}\nvalue: visible\n"))
+			definition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+				Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil },
+			}}
+			var err error
+			var resultPresent bool
+			wantSource := "source-1"
+			if underlay {
+				loaded, loadErr := configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte("version: main\n"))}, configkit.LayeredOptions[map[string]any]{
+					Definition: definition, SourceVersionMode: mode,
+					Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: bad}}}},
+				})
+				err, resultPresent, wantSource = loadErr, loaded != nil, "source-2"
+			} else {
+				loaded, loadErr := configkit.Load(bad, configkit.Options[map[string]any]{Definition: definition, SourceVersionMode: mode})
+				err, resultPresent = loadErr, loaded != nil
+			}
+			var failure *configkit.LoadError
+			if resultPresent || !errors.As(err, &failure) {
+				t.Errorf("mode=%v underlay=%v: import opt-in did not fail safely", mode, underlay)
+				continue
+			}
+			diagnostics := failure.Diagnostics()
+			if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeImportDisabled || diagnostics[0].Path.String() != "/configkit" ||
+				diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != wantSource {
+				t.Errorf("mode=%v underlay=%v: diagnostics=%#v", mode, underlay, diagnostics)
+			}
+		}
+	}
+}
+
+func TestFacadeSourceVersionAbsenceKeepsCompleteEvidencePath(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name, main, underlay string
+		path                 configkit.Path
+	}{
+		{"missing member", "meta: {version: main}\n", "{}\n", configkit.Keys("meta", "version")},
+		{"scalar obstruction", "meta: {version: main}\n", "meta: false\n", configkit.Keys("meta", "version")},
+		{"unavailable index", "meta: [null, null, null, {version: main}]\n", "meta: []\n", configkit.Keys("meta").Index(3).Key("version")},
+	} {
+		for _, mode := range []configkit.SourceVersionMode{configkit.SourceVersionModeIfPresent, configkit.SourceVersionModeRequired} {
+			var callbackEvidence *configkit.SourceVersionCheck
+			loaded, err := configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte(test.main))}, configkit.LayeredOptions[map[string]any]{
+				SourceVersionMode: mode,
+				Definition: configkit.Definition[map[string]any]{
+					Version: &configkit.VersionRule{Path: test.path, Check: func(configkit.Version, *configkit.Validation) error { return nil }},
+					Resolve: func(_ *map[string]any, resolution *configkit.Resolution) error {
+						source, found := resolution.Source("source-2")
+						if !found {
+							t.Fatal("missing callback source")
+						}
+						callbackEvidence = source.VersionCheck
+						return nil
+					},
+				},
+				Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+					Source: configkit.Bytes("underlay", []byte(test.underlay)), Destination: configkit.Keys("under"),
+				}}}},
+			})
+			var evidence *configkit.SourceVersionCheck
+			if mode == configkit.SourceVersionModeRequired {
+				var failure *configkit.LoadError
+				if loaded != nil || !errors.As(err, &failure) {
+					t.Fatalf("%s: required omission did not fail", test.name)
+				}
+				diagnostics := failure.Diagnostics()
+				if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeVersionError || diagnostics[0].Path.String() != test.path.String() {
+					t.Fatalf("%s: required diagnostics=%#v", test.name, diagnostics)
+				}
+				evidence = failure.Sources()[1].VersionCheck
+			} else {
+				if err != nil {
+					t.Fatalf("%s: %v", test.name, err)
+				}
+				evidence = loaded.Sources()[1].VersionCheck
+				if callbackEvidence == nil || callbackEvidence.Path.String() != test.path.String() {
+					t.Errorf("%s: callback path is incomplete", test.name)
+				}
+			}
+			if evidence == nil || evidence.Version.Present || evidence.Path.String() != test.path.String() ||
+				evidence.Location == nil || evidence.Location.SourceID != "source-2" || evidence.Location.Line != 1 {
+				t.Errorf("%s mode=%v: absence evidence=%#v", test.name, mode, evidence)
+			}
+		}
+	}
+}
+
+func TestFacadeSourceVersionMissingHeaderDoesNotOverlapControl(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name     string
+		mode     configkit.SourceVersionMode
+		control  string
+		wantCode configkit.Code
+	}{
+		{"optional omission", configkit.SourceVersionModeIfPresent, "base", ""},
+		{"required omission", configkit.SourceVersionModeRequired, "base", configkit.CodeVersionError},
+		{"invalid control", configkit.SourceVersionModeIfPresent, "true", configkit.CodeInheritanceInvalid},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			main := configkit.Bytes("main", []byte("{}\n"))
+			if test.mode == configkit.SourceVersionModeRequired {
+				main = configkit.NoSource()
+			}
+			checks := 0
+			path := configkit.Keys("entries", "child", "extends", "version")
+			loaded, err := configkit.LoadLayered(configkit.Input{Source: main, Destination: configkit.Keys("main")}, configkit.LayeredOptions[map[string]any]{
+				SourceVersionMode: test.mode,
+				Definition: configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+					Path: path, Check: func(version configkit.Version, _ *configkit.Validation) error {
+						checks++
+						if version.Present {
+							t.Error("checker received a nonexistent declaration")
+						}
+						return nil
+					},
+				}},
+				Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+					Source: configkit.Bytes("underlay", []byte("entries:\n  base: {value: good}\n  child: {extends: "+test.control+"}\n")), Destination: configkit.Keys("under"),
+				}}}},
+			})
+			if checks != 1 {
+				t.Errorf("checker ran %d times, want absent main only", checks)
+			}
+			if test.wantCode != "" {
+				var failure *configkit.LoadError
+				if loaded != nil || !errors.As(err, &failure) {
+					t.Fatal("invalid input did not fail safely")
+				}
+				if diagnostics := failure.Diagnostics(); len(diagnostics) != 1 || diagnostics[0].Code != test.wantCode {
+					t.Fatalf("diagnostics=%#v", diagnostics)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			child := loaded.Config["under"].(map[string]any)["entries"].(map[string]any)["child"].(map[string]any)
+			if child["value"] != "good" {
+				t.Fatal("valid sibling inheritance was not applied")
+			}
+			check := loaded.Sources()[1].VersionCheck
+			if check == nil || check.Version.Present || check.Path.String() != path.String() {
+				t.Fatal("optional omission evidence was not retained")
+			}
+		})
+	}
+}
+
+func (reader *sourceVersionModeReader) Read(data []byte) (int, error) {
+	reader.reads++
+	return reader.Reader.Read(data)
+}
+
+func TestFacadeSourceVersionModesAcrossOrdinaryAndLayeredLoads(t *testing.T) {
+	t.Parallel()
+
+	var checked []configkit.Version
+	definition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+		Path: configkit.Keys("meta", "version"),
+		Check: func(version configkit.Version, _ *configkit.Validation) error {
+			checked = append(checked, version)
+			return nil
+		},
+	}}
+	ordinary, err := configkit.Load(configkit.Bytes("ordinary", []byte("meta: {version: ordinary-v}\n")), configkit.Options[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+	})
+	if err != nil || ordinary == nil {
+		t.Fatalf("ordinary enabled load = %#v, %v", ordinary, err)
+	}
+	if got := ordinary.Config["meta"].(map[string]any)["version"]; got != "ordinary-v" {
+		t.Fatalf("main declaration was not retained: %#v", ordinary.Config)
+	}
+
+	directory := t.TempDir()
+	mainPath := filepath.Join(directory, "main.yml")
+	if err := os.WriteFile(mainPath, []byte("meta: {version: main-v}\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	layered, err := configkit.LoadLayered(configkit.Input{Source: configkit.File(mainPath)}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeRequired,
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Mapping("underlay", map[string]any{
+				"meta": map[string]any{"version": "underlay-v"}, "fallback": "present",
+			}),
+			Destination: configkit.Keys("defaults"),
+		}}}},
+	})
+	if err != nil || layered == nil {
+		t.Fatalf("layered enabled load = %#v, %v", layered, err)
+	}
+	defaults, ok := layered.Config["defaults"].(map[string]any)
+	if !ok || defaults["fallback"] != "present" {
+		t.Fatalf("layered underlay payload = %#v", layered.Config["defaults"])
+	}
+	if meta, ok := defaults["meta"].(map[string]any); !ok || len(meta) != 0 {
+		t.Fatalf("accepted underlay declaration was not consumed: %#v", defaults["meta"])
+	}
+	if len(checked) != 3 {
+		t.Fatalf("checker calls across separate mode uses = %#v", checked)
+	}
+	for _, want := range []string{"ordinary-v", "main-v", "underlay-v"} {
+		found := false
+		for _, version := range checked {
+			found = found || version.Present && version.Text == want
+		}
+		if !found {
+			t.Errorf("checked versions %#v do not include %q", checked, want)
+		}
+	}
+}
+
+func TestFacadeSourceVersionModeZeroPreservesDefaultBehavior(t *testing.T) {
+	t.Parallel()
+
+	checks := 0
+	result, err := configkit.Load(configkit.Bytes("default", []byte("version: v1\n")), configkit.Options[map[string]any]{
+		Definition: configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(version configkit.Version, _ *configkit.Validation) error {
+				checks++
+				if version != (configkit.Version{Present: true, Text: "v1"}) {
+					t.Errorf("default version = %#v", version)
+				}
+				return nil
+			},
+		}},
+	})
+	if err != nil || result == nil || result.Config["version"] != "v1" || checks != 1 {
+		t.Fatalf("zero-mode load = %#v, %v; checks = %d", result, err, checks)
+	}
+}
+
+func TestFacadeSourceVersionModeValidationPrecedesSourceReads(t *testing.T) {
+	t.Parallel()
+
+	validDefinition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+		Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil },
+	}}
+	for _, test := range []struct {
+		name    string
+		mode    configkit.SourceVersionMode
+		def     configkit.Definition[map[string]any]
+		layered bool
+	}{
+		{name: "unknown ordinary mode", mode: configkit.SourceVersionMode(255), def: validDefinition},
+		{name: "ordinary mode requires checker", mode: configkit.SourceVersionModeIfPresent},
+		{name: "unknown layered mode", mode: configkit.SourceVersionMode(255), def: validDefinition, layered: true},
+		{name: "layered mode requires checker", mode: configkit.SourceVersionModeRequired, layered: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			reader := &sourceVersionModeReader{Reader: strings.NewReader("version: v1\n")}
+			source := configkit.Reader("version.yml", reader)
+			var err error
+			if test.layered {
+				_, err = configkit.LoadLayered(configkit.Input{Source: source}, configkit.LayeredOptions[map[string]any]{
+					Definition: test.def, SourceVersionMode: test.mode,
+				})
+			} else {
+				_, err = configkit.Load(source, configkit.Options[map[string]any]{
+					Definition: test.def, SourceVersionMode: test.mode,
+				})
+			}
+			var loadError *configkit.LoadError
+			if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 || loadError.Diagnostics()[0].Code != configkit.CodeOptionsInvalid {
+				t.Fatalf("invalid mode error = %#v", err)
+			}
+			if reader.reads != 0 {
+				t.Fatalf("invalid options read source %d times", reader.reads)
+			}
+		})
+	}
+}
+
+func TestFacadeSourceVersionDefinitionCanBeReusedWithDifferentModes(t *testing.T) {
+	t.Parallel()
+
+	checks := 0
+	definition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+		Path: configkit.Keys("version"),
+		Check: func(version configkit.Version, _ *configkit.Validation) error {
+			checks++
+			if version.Present {
+				t.Errorf("missing declaration reached checker as %#v", version)
+			}
+			return nil
+		},
+	}}
+	source := configkit.Bytes("reused", []byte("value: retained\n"))
+	ifPresent, err := configkit.Load(source, configkit.Options[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+	})
+	if err != nil || ifPresent == nil || checks != 1 {
+		t.Fatalf("if-present load = %#v, %v; checks = %d", ifPresent, err, checks)
+	}
+	required, err := configkit.Load(source, configkit.Options[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeRequired,
+	})
+	var loadError *configkit.LoadError
+	if required != nil || !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 || loadError.Diagnostics()[0].Code != configkit.CodeVersionError {
+		t.Fatalf("required load = %#v, %v", required, err)
+	}
+	if checks != 1 {
+		t.Fatalf("required absence reached checker: calls = %d", checks)
+	}
+}
+
+func TestFacadeSourceVersionEvidenceIsSanitizedAndDetached(t *testing.T) {
+	t.Parallel()
+
+	const canary = "PRIVATE-SOURCE-VERSION-CANARY"
+	directory := t.TempDir()
+	path := filepath.Join(directory, "main.yml")
+	if err := os.WriteFile(path, []byte("version: "+canary+"\nvalue: visible\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	var callbackSource configkit.SourceInfo
+	var callbackContext configkit.ResourceContext
+	definition := configkit.Definition[map[string]any]{
+		Version: &configkit.VersionRule{Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil }},
+		Secret:  func(candidate configkit.Path) bool { return candidate.String() == "/service/version" },
+		Resolve: func(_ *map[string]any, resolution *configkit.Resolution) error {
+			var found bool
+			callbackSource, found = resolution.Source("source-1")
+			if !found {
+				t.Fatal("resolution callback could not query the acquired source")
+			}
+			if callbackSource.VersionCheck == nil || !callbackSource.VersionCheck.Redacted || callbackSource.VersionCheck.Version.Text != "" {
+				t.Fatalf("callback source did not conservatively redact evidence: %#v", callbackSource.VersionCheck)
+			}
+			callbackContext, found = resolution.SourceContext("source-1")
+			if !found || callbackContext.FS == nil || callbackContext.BaseDir != "." {
+				t.Fatalf("callback source context = %#v, found=%v", callbackContext, found)
+			}
+			return nil
+		},
+	}
+	loaded, err := configkit.LoadLayered(configkit.Input{Source: configkit.File(path), Destination: configkit.Keys("service")}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+	})
+	if err != nil || loaded == nil {
+		t.Fatalf("LoadLayered = %#v, %v", loaded, err)
+	}
+	if callbackSource.VersionCheck == nil || !callbackSource.VersionCheck.Redacted || callbackSource.VersionCheck.Version.Text != "" {
+		t.Fatalf("callback evidence lost its conservative snapshot: %#v", callbackSource.VersionCheck)
+	}
+	callbackSource.VersionCheck.Path = configkit.Keys("mutated-callback")
+	callbackSource.VersionCheck.Version.Text = canary
+	callbackSource.VersionCheck.Location.Line = 98
+	finalSources := loaded.Sources()
+	if len(finalSources) != 1 || finalSources[0].Path != path || finalSources[0].VersionCheck == nil {
+		t.Fatalf("final sources = %#v", finalSources)
+	}
+	check := finalSources[0].VersionCheck
+	if check.Path.String() != "/version" || check.Version != (configkit.Version{Present: true}) || !check.Redacted ||
+		check.Location == nil || check.Location.SourceID != finalSources[0].ID || check.Location.Line != 1 {
+		t.Fatalf("final classified evidence = %#v", check)
+	}
+	if err := os.Remove(path); err != nil {
+		t.Fatal(err)
+	}
+	if callbackContext.FS == nil || callbackContext.BaseDir != "." {
+		t.Fatalf("resource metadata changed after removing the source: %#v", callbackContext)
+	}
+	check.Path = configkit.Keys("mutated")
+	check.Location.Line = 99
+	check.Redacted = false
+	check.Version.Text = "mutated"
+	repeated := loaded.Sources()
+	if len(repeated) != 1 || repeated[0].VersionCheck.Path.String() != "/version" ||
+		repeated[0].VersionCheck.Location.Line != 1 || !repeated[0].VersionCheck.Redacted ||
+		repeated[0].VersionCheck.Version.Text != "" {
+		t.Fatalf("source evidence was aliased or re-read after source removal: %#v", repeated)
+	}
+
+	publicText := "PUBLIC-SOURCE-VERSION"
+	var publicCallback configkit.SourceInfo
+	public, err := configkit.Load(configkit.Bytes("public", []byte("version: "+publicText+"\n")), configkit.Options[map[string]any]{
+		SourceVersionMode: configkit.SourceVersionModeIfPresent,
+		Definition: configkit.Definition[map[string]any]{
+			Version: definition.Version,
+			Resolve: func(_ *map[string]any, resolution *configkit.Resolution) error {
+				publicCallback, _ = resolution.Source("source-1")
+				return nil
+			},
+		},
+	})
+	if err != nil || public == nil || len(public.Sources()) != 1 || public.Sources()[0].VersionCheck == nil {
+		t.Fatalf("unclassified source evidence = %#v, %v", public, err)
+	}
+	if got := public.Sources()[0].VersionCheck; got.Redacted || got.Version.Text != publicText || !got.Version.Present {
+		t.Fatalf("unclassified evidence = %#v", got)
+	}
+	if publicCallback.VersionCheck == nil || !publicCallback.VersionCheck.Redacted || publicCallback.VersionCheck.Version.Text != "" {
+		t.Fatalf("unclassified callback evidence was not initially conservative: %#v", publicCallback.VersionCheck)
+	}
+}
+
+func TestFacadeSourceVersionEvidenceOnFailedLoadsAndSyntheticSources(t *testing.T) {
+	t.Parallel()
+
+	definition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+		Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil },
+	}}
+	t.Run("early import acquisition failure", func(t *testing.T) {
+		const canary = "EARLY-ACQUISITION-SOURCE-VERSION-CANARY"
+		checked := 0
+		earlyDefinition := configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { checked++; return nil },
+		}}
+		path := filepath.Join(t.TempDir(), "main.yml")
+		contents := "version: " + canary + "\nconfigkit:\n  imports:\n    - path: missing.yml\n"
+		if err := os.WriteFile(path, []byte(contents), 0o600); err != nil {
+			t.Fatal(err)
+		}
+		_, err := configkit.LoadLayered(configkit.Input{Source: configkit.File(path), Imports: true}, configkit.LayeredOptions[map[string]any]{
+			Definition: earlyDefinition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+		})
+		var failure *configkit.LoadError
+		if !errors.As(err, &failure) || len(failure.Sources()) != 1 {
+			t.Fatalf("early acquisition failure sources = %#v, error %v", failure, err)
+		}
+		if checked != 1 {
+			t.Fatalf("main declaration checker calls = %d; error %v", checked, err)
+		}
+		check := failure.Sources()[0].VersionCheck
+		if check == nil || !check.Redacted || !check.Version.Present || check.Version.Text != "" {
+			t.Fatalf("early acquisition evidence was not conservatively redacted: %#v; sources %#v", check, failure.Sources())
+		}
+		if strings.Contains(err.Error(), canary) {
+			t.Fatalf("early acquisition failure disclosed source-version canary: %v", err)
+		}
+	})
+	_, err := configkit.Load(configkit.Bytes("malformed", []byte("version: true\n")), configkit.Options[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+	})
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) {
+		t.Fatalf("malformed version error = %v", err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 1 || sources[0].VersionCheck == nil || !sources[0].VersionCheck.Redacted ||
+		!sources[0].VersionCheck.Version.Present || sources[0].VersionCheck.Version.Text != "" || sources[0].VersionCheck.Path.String() != "/version" {
+		t.Fatalf("failed-load source evidence = %#v", sources)
+	}
+	sources[0].VersionCheck.Path = configkit.Keys("mutated-error")
+	sources[0].VersionCheck.Version.Text = "mutated"
+	sources[0].VersionCheck.Location.Line = 99
+	if again := loadError.Sources()[0].VersionCheck; again.Path.String() != "/version" || again.Version.Text != "" || again.Location.Line == 99 {
+		t.Fatalf("LoadError source evidence was aliased: %#v", again)
+	}
+	for _, test := range []struct {
+		name   string
+		def    configkit.Definition[map[string]any]
+		canary string
+	}{
+		{
+			name:   "resolver failure",
+			canary: "RESOLVER-SOURCE-VERSION-CANARY",
+			def: configkit.Definition[map[string]any]{Version: definition.Version, Resolve: func(*map[string]any, *configkit.Resolution) error {
+				return errors.New("resolver failed")
+			}},
+		},
+		{
+			name:   "validator failure",
+			canary: "VALIDATOR-SOURCE-VERSION-CANARY",
+			def: configkit.Definition[map[string]any]{Version: definition.Version, Validate: func(_ *map[string]any, validation *configkit.Validation) {
+				validation.Error(configkit.Keys("value"), "invalid value")
+			}},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			_, err := configkit.Load(configkit.Bytes("late-failure", []byte("version: "+test.canary+"\nvalue: configured\n")), configkit.Options[map[string]any]{
+				Definition: test.def, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+			})
+			var failure *configkit.LoadError
+			if !errors.As(err, &failure) || len(failure.Sources()) != 1 {
+				t.Fatalf("late failure sources = %#v, error %v", failure, err)
+			}
+			if strings.Contains(err.Error(), test.canary) {
+				t.Fatalf("late failure disclosed source-version canary: %v", err)
+			}
+			check := failure.Sources()[0].VersionCheck
+			if check == nil || !check.Redacted || !check.Version.Present || check.Version.Text != "" {
+				t.Fatalf("late-failure evidence was not conservatively redacted: %#v", check)
+			}
+		})
+	}
+
+	defaultResult, err := configkit.Load(configkit.Bytes("default", []byte("version: 7\n")), configkit.Options[map[string]any]{})
+	if err != nil || defaultResult == nil || len(defaultResult.Sources()) != 1 || defaultResult.Sources()[0].VersionCheck != nil {
+		t.Fatalf("default source version check = %#v, %v", defaultResult, err)
+	}
+
+	withCLI, err := configkit.Load(configkit.Bytes("main", []byte("version: 8\nvalue: old\n")), configkit.Options[map[string]any]{
+		Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+		Overrides: []configkit.Override{{Path: configkit.Keys("value"), Value: "new", Flag: "--value"}},
+	})
+	if err != nil || withCLI == nil {
+		t.Fatalf("enabled load with CLI source = %#v, %v", withCLI, err)
+	}
+	sawCLI := false
+	for _, source := range withCLI.Sources() {
+		if source.Kind == configkit.SourceKindCLI && source.VersionCheck != nil {
+			t.Fatalf("synthetic CLI source acquired declaration evidence: %#v", source)
+		}
+		sawCLI = sawCLI || source.Kind == configkit.SourceKindCLI
+	}
+	if !sawCLI {
+		t.Fatalf("CLI source record missing: %#v", withCLI.Sources())
+	}
+}
+
+func TestFacadeSourceVersionEvidencePreservesAbsenceAndNull(t *testing.T) {
+	t.Parallel()
+
+	var checked []configkit.Version
+	loaded, err := configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte("version: 17\n"))}, configkit.LayeredOptions[map[string]any]{
+		SourceVersionMode: configkit.SourceVersionModeIfPresent,
+		Definition: configkit.Definition[map[string]any]{Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(version configkit.Version, _ *configkit.Validation) error {
+				checked = append(checked, version)
+				return nil
+			},
+		}},
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{
+			{Source: configkit.Bytes("absent", []byte("value: visible\n")), Destination: configkit.Keys("absent")},
+			{Source: configkit.Bytes("null", []byte("version: null\nvalue: visible\n")), Destination: configkit.Keys("nullable")},
+		}}},
+	})
+	if err != nil || loaded == nil {
+		t.Fatalf("LoadLayered = %#v, %v", loaded, err)
+	}
+	if len(checked) != 2 || !checked[0].Present || checked[0].Text != "17" ||
+		!checked[1].Present || !checked[1].Null {
+		t.Fatalf("checker calls = %#v; absent contribution must skip while null is checked", checked)
+	}
+	sources := loaded.Sources()
+	if len(sources) != 3 || sources[1].VersionCheck == nil || sources[2].VersionCheck == nil {
+		t.Fatalf("source version evidence = %#v", sources)
+	}
+	absent := sources[1].VersionCheck
+	if absent.Version.Present || absent.Path.String() != "/version" || absent.Location == nil || absent.Redacted {
+		t.Fatalf("optional omission evidence = %#v", absent)
+	}
+	null := sources[2].VersionCheck
+	if !null.Version.Present || !null.Version.Null || null.Version.Text != "" || null.Path.String() != "/version" {
+		t.Fatalf("null declaration evidence = %#v", null)
+	}
+}
+
+func TestFacadeSourceVersionLifecycleKeepsConsumedHeadersOutOfPayloadHistory(t *testing.T) {
+	type serviceConfig struct {
+		Version    uint64           `yaml:"version"`
+		Count      int              `yaml:"count"`
+		Enabled    bool             `yaml:"enabled"`
+		Nullable   *string          `yaml:"nullable"`
+		Revision   string           `yaml:"revision"`
+		Defaulted  string           `yaml:"defaulted"`
+		Resolved   string           `yaml:"resolved"`
+		Credential configkit.Secret `yaml:"credential"`
+	}
+	type configuration struct {
+		Service serviceConfig `yaml:"service"`
+	}
+	t.Setenv("CONFIGKIT_LIFECYCLE_SECRET", "lifecycle-secret-value")
+	var checked []configkit.Version
+	var validationCalls int
+	definition := configkit.Definition[configuration]{
+		Defaults: func() configuration {
+			return configuration{Service: serviceConfig{Defaulted: "from defaults"}}
+		},
+		Version: &configkit.VersionRule{
+			Path: configkit.Keys("version"),
+			Check: func(version configkit.Version, _ *configkit.Validation) error {
+				checked = append(checked, version)
+				return nil
+			},
+		},
+		Resolve: func(current *configuration, resolution *configkit.Resolution) error {
+			current.Service.Resolved = "resolved once"
+			resolution.Record(configkit.Keys("service", "resolved"), configkit.ChangeNormalization, "derive resolved value")
+			return nil
+		},
+		Validate: func(current *configuration, validation *configkit.Validation) {
+			validationCalls++
+			if current.Service.Version != 9007199254740993 || current.Service.Count != 0 || current.Service.Enabled ||
+				current.Service.Nullable != nil || current.Service.Revision != "ordinary-payload" || current.Service.Defaulted != "from defaults" ||
+				current.Service.Resolved != "resolved once" || current.Service.Credential.Value() != "lifecycle-secret-value" {
+				validation.Error(configkit.Keys("service"), "assembled values did not survive source declaration processing")
+			}
+		},
+	}
+
+	load := func(header string) *configkit.Result[configuration] {
+		t.Helper()
+		result, err := configkit.LoadLayered(configkit.Input{
+			Source: configkit.Bytes("main", []byte("version: 9007199254740993\n")), Destination: configkit.Keys("service"),
+		}, configkit.LayeredOptions[configuration]{
+			Definition: definition, SourceVersionMode: configkit.SourceVersionModeIfPresent,
+			Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+				Source:      configkit.Bytes("underlay", []byte("version: "+header+"\ncount: 0\nenabled: false\nnullable: null\nrevision: ordinary-payload\ncredential: CONFIGKIT_LIFECYCLE_SECRET\n")),
+				Destination: configkit.Keys("service"),
+			}}}},
+		})
+		if err != nil || result == nil {
+			var failure *configkit.LoadError
+			var diagnostics []configkit.Diagnostic
+			if errors.As(err, &failure) {
+				diagnostics = failure.Diagnostics()
+			}
+			t.Fatalf("LoadLayered(%q) = %#v, %v; diagnostics %#v", header, result, err, diagnostics)
+		}
+		return result
+	}
+
+	first := load("underlay-release-a")
+	second := load("underlay-release-b")
+	if len(checked) != 4 || checked[0].Text != "9007199254740993" || checked[1].Text != "underlay-release-a" ||
+		checked[2].Text != "9007199254740993" || checked[3].Text != "underlay-release-b" {
+		t.Fatalf("source declarations checked = %#v", checked)
+	}
+	if validationCalls != 2 || first.Config.Service != second.Config.Service {
+		t.Fatalf("final configs or validation count = %#v, %#v, %d", first.Config, second.Config, validationCalls)
+	}
+	if differences, err := configkit.Diff(first, second); err != nil || len(differences) != 0 {
+		t.Fatalf("different consumed declarations created effective differences: %#v, %v", differences, err)
+	}
+	var firstEffective, secondEffective bytes.Buffer
+	if err := first.WriteEffective(&firstEffective); err != nil {
+		t.Fatal(err)
+	}
+	if err := second.WriteEffective(&secondEffective); err != nil {
+		t.Fatal(err)
+	}
+	if firstEffective.String() != secondEffective.String() || strings.Contains(firstEffective.String(), "underlay-release") {
+		t.Fatalf("consumed declarations affected effective rendering:\n%s\n%s", firstEffective.String(), secondEffective.String())
+	}
+	sourcesA, sourcesB := first.Sources(), second.Sources()
+	if len(sourcesA) != 2 || len(sourcesB) != 2 || sourcesA[1].VersionCheck == nil || sourcesB[1].VersionCheck == nil ||
+		sourcesA[1].VersionCheck.Version.Text != "underlay-release-a" || sourcesB[1].VersionCheck.Version.Text != "underlay-release-b" {
+		t.Fatalf("sanitized evidence did not retain distinct accepted declarations: %#v / %#v", sourcesA, sourcesB)
+	}
+	versionExplanation, found := first.Explain(configkit.Keys("service", "version"))
+	if !found {
+		t.Fatal("retained main version missing from effective explanation")
+	}
+	underlayID := sourcesA[1].ID
+	for _, location := range versionExplanation.Origin.Locations {
+		if location.SourceID == underlayID {
+			t.Fatalf("consumed underlay declaration entered effective origin: %#v", versionExplanation.Origin)
+		}
+	}
+	for _, change := range versionExplanation.History {
+		for _, location := range change.Origin.Locations {
+			if location.SourceID == underlayID {
+				t.Fatalf("consumed underlay declaration entered effective history: %#v", versionExplanation.History)
+			}
+		}
+	}
+}

go.mod

@@ -1,5 +1,13 @@
 module gitea.maximumdirect.net/eric/ConfigKit
 
-go 1.25.0
+go 1.26.0
 
 require go.yaml.in/yaml/v4 v4.0.0-rc.6
+
+require (
+	gitea.maximumdirect.net/eric/ReleaseKit v0.4.1 // indirect
+	github.com/yuin/goldmark/v2 v2.1.6 // indirect
+	golang.org/x/mod v0.40.0 // indirect
+)
+
+tool gitea.maximumdirect.net/eric/ReleaseKit/cmd/releasekit

go.sum

@@ -1,2 +1,8 @@
+gitea.maximumdirect.net/eric/ReleaseKit v0.4.1 h1:Qn+mdebYOzCVCEXgCbuGSO/WHmJtItwaQ8e3XwY3qtI=
+gitea.maximumdirect.net/eric/ReleaseKit v0.4.1/go.mod h1:LVodqNQ3OIKv9NBq+fFeyMByd1lHY25YOmmpah/NaNI=
+github.com/yuin/goldmark/v2 v2.1.6 h1:igy0q9JcqovoFXFx/XjtU8sHVhcUHavPj2sA3EoKJUE=
+github.com/yuin/goldmark/v2 v2.1.6/go.mod h1:G6M4/qOFtfn01/o14BU1UR2Lo5N3S9Qo7xCuz/sHjGQ=
 go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
 go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
+golang.org/x/mod v0.40.0 h1:hUv+3cXcdRHz08UmSiOob7sadHig73uo5bkXxQ/tvUs=
+golang.org/x/mod v0.40.0/go.mod h1:0/weTWkPWGBikyTWAX3dkjVztMmBA5hM0DH6BElSupE=

internal/engine/compose.go

@@ -6,13 +6,29 @@ import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 // precedence layers. Claims remain ordered by source and declaration traversal;
 // origins retain every source that contributes to a composite mapping.
 type composedDocument struct {
-	root         *document.Node
+	root           *document.Node
-	claims       []compositionClaim
+	acquisition    []acquisitionScope
-	origins      map[string]Origin
+	claims         []compositionClaim
-	overlays     []overlayRecord
+	sequenceRanges []sequenceRange
-	applications []historyApplication
+	origins        map[string]Origin
-	inputBytes   int64
+	overlays       []overlayRecord
-	inputNodes   int
+	applications   []historyApplication
+	inputBytes     int64
+	inputNodes     int
+}
+
+type sequenceHistoryMode uint8
+
+const (
+	sequenceHistoryReplace sequenceHistoryMode = iota + 1
+	sequenceHistoryAppend
+)
+
+type sequenceHistoryContribution struct {
+	path   Path
+	mode   sequenceHistoryMode
+	offset int
+	length int
 }
 
 // assemblyAccumulator owns one mutable working document. Acquired trees held by
@@ -29,18 +45,25 @@ func newAssemblyAccumulator(owned *composedDocument) *assemblyAccumulator {
 // cloneComposedDocument detaches mutable composition and provenance state;
 // history application trees are immutable and retain their existing sharing.
 func cloneComposedDocument(base *composedDocument) *composedDocument {
+	if base == nil {
+		return nil
+	}
 	return &composedDocument{
 		root: document.Clone(base.root), claims: cloneCompositionClaims(base.claims),
-		origins: cloneOriginIndex(base.origins), overlays: cloneOverlayRecords(base.overlays),
+		acquisition:    cloneAcquisitionScopes(base.acquisition),
+		sequenceRanges: cloneSequenceRanges(base.sequenceRanges),
+		origins:        cloneOriginIndex(base.origins), overlays: cloneOverlayRecords(base.overlays),
 		applications: cloneHistoryApplications(base.applications),
 		inputBytes:   base.inputBytes, inputNodes: base.inputNodes,
 	}
 }
 
 type compositionClaim struct {
-	path     Path
+	node        *document.Node // borrowed immutable contribution, not the assembly tree
-	kind     document.Kind
+	path        Path
-	location Location
+	kind        document.Kind
+	location    Location
+	sourceIndex int
 }
 
 type compositionClaims struct {
@@ -48,16 +71,32 @@ type compositionClaims struct {
 	byPath  map[string][]compositionClaim
 }
 
+// sequenceRange records where one source's sequence items were assigned in the
+// composed sequence at path. End is exclusive.
+type sequenceRange struct {
+	sourceIndex int
+	path        Path
+	start       int
+	end         int
+}
+
 // composeDocuments recursively joins disjoint mapping entries. Source order
 // controls only output traversal and diagnostics: every non-mapping overlap is
 // rejected before a result is assembled.
 func composeDocuments(inputs ...*document.Node) (*composedDocument, []Diagnostic) {
+	return composeDocumentsWithPolicy(sequencePolicy{}, inputs...)
+}
+
+// composeDocumentsWithPolicy composes one strict tier using the registered
+// sequence rules when policy contains registrations. The ordinary adapter above
+// deliberately preserves the existing unregistered behavior for current callers.
+func composeDocumentsWithPolicy(policy sequencePolicy, inputs ...*document.Node) (*composedDocument, []Diagnostic) {
 	if len(inputs) == 0 {
 		return nil, []Diagnostic{compositionInvalidDiagnostic("strict composition requires at least one document", nil)}
 	}
 
 	collected := compositionClaims{byPath: make(map[string][]compositionClaim)}
-	for _, input := range inputs {
+	for sourceIndex, input := range inputs {
 		if input == nil || input.Kind != document.Mapping {
 			var location *Location
 			if input != nil {
@@ -66,7 +105,7 @@ func composeDocuments(inputs ...*document.Node) (*composedDocument, []Diagnostic
 			}
 			return nil, []Diagnostic{compositionInvalidDiagnostic("strict composition requires mapping document roots", location)}
 		}
-		collected.append(input, Path{})
+		collected.append(input, Path{}, sourceIndex)
 	}
 
 	checked := make(map[string]struct{}, len(collected.byPath))
@@ -77,28 +116,52 @@ func composeDocuments(inputs ...*document.Node) (*composedDocument, []Diagnostic
 		}
 		checked[pointer] = struct{}{}
 		claims := collected.byPath[pointer]
-		if len(claims) < 2 || allMappingClaims(claims) {
+		if len(claims) < 2 || allMappingClaims(claims) || (allSequenceClaims(claims) && policy.registered(claim.path)) {
 			continue
 		}
 		return nil, []Diagnostic{compositionConflictDiagnostic(claim.path, claims)}
 	}
 
+	validated, ranges, diagnostics := validateRegisteredSequences(collected.ordered, policy)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+
 	root := document.Clone(inputs[0])
 	index := new(mappingIndex)
-	for _, input := range inputs[1:] {
+	for sourceIndex, input := range inputs[1:] {
-		mergeDisjointMappings(root, input, index)
+		mergeComposedMappings(root, input, Path{}, index, sourceIndex+1, policy, validated)
 	}
 	applications := make([]historyApplication, 0, len(inputs))
-	for _, input := range inputs {
+	seenSequences := make(map[string]bool)
-		applications = append(applications, historyApplication{layer: LayerBase, value: input})
+	rangesBySource := make([][]sequenceRange, len(inputs))
+	for _, assigned := range ranges {
+		rangesBySource[assigned.sourceIndex] = append(rangesBySource[assigned.sourceIndex], assigned)
 	}
-	origins := compositionOrigins(collected.ordered)
+	for sourceIndex, input := range inputs {
+		application := historyApplication{layer: LayerBase, value: input}
+		for _, assigned := range rangesBySource[sourceIndex] {
+			pointer := assigned.path.String()
+			mode := sequenceHistoryAppend
+			if !seenSequences[pointer] {
+				mode = sequenceHistoryReplace
+			}
+			seenSequences[pointer] = true
+			application.sequences = append(application.sequences, sequenceHistoryContribution{
+				path: assigned.path.clone(), mode: mode, offset: assigned.start, length: assigned.end - assigned.start,
+			})
+		}
+		application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+		applications = append(applications, application)
+	}
+	origins := projectedCompositionOrigins(inputs, ranges)
 	completeCompositionOrigins(root, Path{}, origins)
 	return &composedDocument{
-		root:         root,
+		root:           root,
-		claims:       cloneCompositionClaims(collected.ordered),
+		claims:         cloneCompositionClaims(collected.ordered),
-		origins:      origins,
+		sequenceRanges: cloneSequenceRanges(ranges),
-		applications: applications,
+		origins:        origins,
+		applications:   applications,
 	}, nil
 }
 
@@ -121,11 +184,13 @@ func completeCompositionOrigins(node *document.Node, path Path, origins map[stri
 	}
 }
 
-func (c *compositionClaims) append(node *document.Node, path Path) {
+func (c *compositionClaims) append(node *document.Node, path Path, sourceIndex int) {
 	claim := compositionClaim{
-		path:     path.clone(),
+		node:        node,
-		kind:     node.Kind,
+		path:        path.clone(),
-		location: publicLocation(node.Location),
+		kind:        node.Kind,
+		location:    publicLocation(node.Location),
+		sourceIndex: sourceIndex,
 	}
 	c.ordered = append(c.ordered, claim)
 	pointer := path.String()
@@ -135,10 +200,146 @@ func (c *compositionClaims) append(node *document.Node, path Path) {
 		return
 	}
 	for _, entry := range node.Mapping {
-		c.append(entry.Value, path.Key(entry.Key))
+		c.append(entry.Value, path.Key(entry.Key), sourceIndex)
 	}
 }
 
+func allSequenceClaims(claims []compositionClaim) bool {
+	for _, claim := range claims {
+		if claim.kind != document.Sequence {
+			return false
+		}
+	}
+	return true
+}
+
+type validatedSequence struct {
+	items []*document.Node
+}
+
+func validateRegisteredSequences(claims []compositionClaim, policy sequencePolicy) (map[string]map[int]validatedSequence, []sequenceRange, []Diagnostic) {
+	itemsByPath := make(map[string]map[int]validatedSequence)
+	identitiesByPath := make(map[string]map[string]Location)
+	lengthsByPath := make(map[string]int)
+	var ranges []sequenceRange
+	for _, claim := range claims {
+		if claim.kind != document.Sequence {
+			continue
+		}
+		identityField, registered := policy.identityFields[claim.path.String()]
+		if !registered {
+			continue
+		}
+		node := claim.node
+		pathKey := claim.path.String()
+		identities := identitiesByPath[pathKey]
+		if identities == nil {
+			identities = make(map[string]Location, len(node.Sequence))
+			identitiesByPath[pathKey] = identities
+		}
+		start := lengthsByPath[pathKey]
+		contribution := validatedSequence{items: node.Sequence}
+		for itemIndex, item := range node.Sequence {
+			itemPath := claim.path.Index(start + itemIndex)
+			if item == nil || item.Kind != document.Mapping {
+				location := (*Location)(nil)
+				if item != nil {
+					converted := publicLocation(item.Location)
+					location = &converted
+				}
+				return nil, nil, []Diagnostic{{
+					Code: CodeComposeInvalid, Severity: SeverityError,
+					Path: itemPath, Message: "registered sequence items must be mappings", Primary: location,
+				}}
+			}
+			fieldIndex := documentEntryIndex(item.Mapping, identityField)
+			if fieldIndex < 0 {
+				location := publicLocation(item.Location)
+				return nil, nil, []Diagnostic{{
+					Code: CodeComposeInvalid, Severity: SeverityError,
+					Path: itemPath, Message: "registered sequence item is missing its identity field",
+					Primary: &location,
+				}}
+			}
+			field := item.Mapping[fieldIndex].Value
+			if field == nil || field.Kind != document.String {
+				location := publicLocation(item.Mapping[fieldIndex].ValueLocation)
+				if field != nil {
+					location = publicLocation(field.Location)
+				}
+				return nil, nil, []Diagnostic{{
+					Code: CodeComposeInvalid, Severity: SeverityError,
+					Path: itemPath.Key(identityField), Message: "registered sequence identity must be a string",
+					Primary: &location,
+				}}
+			}
+			if first, duplicate := identities[field.Text]; duplicate {
+				current := publicLocation(field.Location)
+				return nil, nil, []Diagnostic{{
+					Code: CodeComposeConflict, Severity: SeverityError,
+					Path: claim.path.clone(), Message: "registered sequence contains duplicate identities",
+					Primary: &first, Related: []Location{current},
+				}}
+			}
+			identities[field.Text] = publicLocation(field.Location)
+		}
+		if itemsByPath[pathKey] == nil {
+			itemsByPath[pathKey] = make(map[int]validatedSequence)
+		}
+		itemsByPath[pathKey][claim.sourceIndex] = contribution
+		lengthsByPath[pathKey] = start + len(node.Sequence)
+		ranges = append(ranges, sequenceRange{
+			sourceIndex: claim.sourceIndex, path: claim.path.clone(), start: start, end: start + len(node.Sequence),
+		})
+	}
+	return itemsByPath, ranges, nil
+}
+
+func mergeComposedMappings(target, incoming *document.Node, path Path, index *mappingIndex, sourceIndex int, policy sequencePolicy, validated map[string]map[int]validatedSequence) {
+	for _, incomingEntry := range incoming.Mapping {
+		entryPath := path.Key(incomingEntry.Key)
+		position := index.find(target, incomingEntry.Key)
+		if position < 0 {
+			cloned := incomingEntry
+			cloned.Value = document.Clone(incomingEntry.Value)
+			index.append(target, cloned)
+			continue
+		}
+		current := target.Mapping[position].Value
+		if current.Kind == document.Sequence && incomingEntry.Value.Kind == document.Sequence && policy.registered(entryPath) {
+			contribution := validated[entryPath.String()][sourceIndex]
+			if contribution.items != nil {
+				for _, item := range contribution.items {
+					current.Sequence = append(current.Sequence, document.Clone(item))
+				}
+			}
+			continue
+		}
+		mergeDisjointMappingsAtPath(current, incomingEntry.Value, entryPath, index, sourceIndex, policy, validated)
+	}
+}
+
+func mergeDisjointMappingsAtPath(target, incoming *document.Node, path Path, index *mappingIndex, sourceIndex int, policy sequencePolicy, validated map[string]map[int]validatedSequence) {
+	if target.Kind != document.Mapping || incoming.Kind != document.Mapping {
+		return
+	}
+	mergeComposedMappings(target, incoming, path, index, sourceIndex, policy, validated)
+}
+
+func (p sequencePolicy) registered(path Path) bool {
+	_, ok := p.identityFields[path.String()]
+	return ok
+}
+
+func cloneSequenceRanges(ranges []sequenceRange) []sequenceRange {
+	cloned := make([]sequenceRange, len(ranges))
+	for i, assigned := range ranges {
+		cloned[i] = assigned
+		cloned[i].path = assigned.path.clone()
+	}
+	return cloned
+}
+
 func allMappingClaims(claims []compositionClaim) bool {
 	for _, claim := range claims {
 		if claim.kind != document.Mapping {
@@ -172,18 +373,64 @@ func documentEntryIndex(entries []document.Entry, key string) int {
 	return -1
 }
 
-func compositionOrigins(claims []compositionClaim) map[string]Origin {
+func projectedCompositionOrigins(inputs []*document.Node, ranges []sequenceRange) map[string]Origin {
-	origins := make(map[string]Origin, len(claims))
+	origins := make(map[string]Origin)
-	for _, claim := range claims {
+	rangeBySourcePath := make(map[sequenceRangeKey]int, len(ranges))
-		pointer := claim.path.String()
+	for index, assigned := range ranges {
-		origin := origins[pointer]
+		rangeBySourcePath[sequenceRangeKey{sourceIndex: assigned.sourceIndex, path: assigned.path.String()}] = index
-		origin.Layer = LayerBase
+	}
-		origin.Locations = append(origin.Locations, claim.location)
+	for sourceIndex, input := range inputs {
-		origins[pointer] = origin
+		collectProjectedCompositionOrigins(input, Path{}, Path{}, sourceIndex, ranges, rangeBySourcePath, origins)
 	}
 	return origins
 }
 
+type sequenceRangeKey struct {
+	sourceIndex int
+	path        string
+}
+
+type sequenceRangeIndex map[sequenceRangeKey]sequenceRange
+
+func indexSequenceRanges(ranges []sequenceRange) sequenceRangeIndex {
+	if len(ranges) == 0 {
+		return nil
+	}
+	index := make(sequenceRangeIndex, len(ranges))
+	for _, assigned := range ranges {
+		index[sequenceRangeKey{sourceIndex: assigned.sourceIndex, path: assigned.path.String()}] = assigned
+	}
+	return index
+}
+
+// Keep local paths for matching Stage 2 ranges and effective paths for emitted
+// evidence. The paths are transformed segment by segment; pointer strings are
+// only used as map keys after projection is complete.
+func collectProjectedCompositionOrigins(node *document.Node, localPath, effectivePath Path, sourceIndex int, ranges []sequenceRange, rangeBySourcePath map[sequenceRangeKey]int, origins map[string]Origin) {
+	pointer := effectivePath.String()
+	origin := origins[pointer]
+	origin.Layer = LayerBase
+	origin.Locations = append(origin.Locations, publicLocation(node.Location))
+	origins[pointer] = origin
+
+	switch node.Kind {
+	case document.Mapping:
+		for _, entry := range node.Mapping {
+			collectProjectedCompositionOrigins(entry.Value, localPath.Key(entry.Key), effectivePath.Key(entry.Key), sourceIndex, ranges, rangeBySourcePath, origins)
+		}
+	case document.Sequence:
+		start := 0
+		if rangeIndex, ok := rangeBySourcePath[sequenceRangeKey{sourceIndex: sourceIndex, path: localPath.String()}]; ok {
+			start = ranges[rangeIndex].start
+		}
+		for index, child := range node.Sequence {
+			localChild := localPath.Index(index)
+			effectiveChild := effectivePath.Index(start + index)
+			collectProjectedCompositionOrigins(child, localChild, effectiveChild, sourceIndex, ranges, rangeBySourcePath, origins)
+		}
+	}
+}
+
 func applyCompositionOrigins(decoded *decodedConfiguration, origins map[string]Origin) {
 	for pointer, origin := range origins {
 		if _, present := decoded.presence[pointer]; present {

internal/engine/compose_test.go

@@ -1,12 +1,60 @@
 package engine
 
 import (
+	"fmt"
 	"reflect"
+	"strings"
 	"testing"
 
 	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 )
 
+func TestComposeWideRegisteredCollectionsPreservesEvidenceAndReplay(t *testing.T) {
+	policy := sequencePolicy{identityFields: make(map[string]string)}
+	var inputs []*document.Node
+	for source := 0; source < 3; source++ {
+		var text strings.Builder
+		for collection := 0; collection < 128; collection++ {
+			key := fmt.Sprintf("records%d", collection)
+			policy.identityFields[Keys(key).String()] = "id"
+			fmt.Fprintf(&text, "%s: [{id: source%d}]\n", key, source)
+		}
+		inputs = append(inputs, parseCompositionDocument(t, fmt.Sprintf("source-%d", source), text.String()))
+	}
+	composed, diagnostics := composeDocumentsWithPolicy(policy, inputs...)
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	working := &document.Node{Kind: document.Mapping}
+	for _, application := range composed.applications {
+		applyHistoryApplication(&working, application, new(mappingIndex))
+	}
+	if !configurationValuesEqual(working, composed.root) {
+		t.Fatal("wide registered collections replay differs from assembly")
+	}
+	for collection := 0; collection < 128; collection++ {
+		path := Keys(fmt.Sprintf("records%d", collection)).Index(2).Key("id")
+		origin := composed.origins[path.String()]
+		if len(origin.Locations) != 1 || origin.Locations[0].SourceID != "source-2" {
+			t.Fatalf("shifted origin at %s = %#v", path.String(), origin)
+		}
+		local, ok := historyApplicationLocalPath(composed.applications[2], path)
+		if !ok || local.String() != Keys(fmt.Sprintf("records%d", collection)).Index(0).Key("id").String() {
+			t.Fatal("wide local path projection failed")
+		}
+	}
+	clone := cloneComposedDocument(composed)
+	for _, original := range composed.applications[0].sequences {
+		pointer := original.path.String()
+		copy := clone.applications[0].sequencesByPath[pointer]
+		copy.path.segments[0].key = "changed"
+		if composed.applications[0].sequencesByPath[pointer].path.String() != pointer {
+			t.Fatal("history path index aliases cloned state")
+		}
+		break
+	}
+}
+
 func TestComposeDocumentsJoinsDisjointMappingsAndTracksClaims(t *testing.T) {
 	base := parseCompositionDocument(t, "source-1", `services:
   api:
@@ -190,6 +238,268 @@ func TestComposeDocumentsRejectsInvalidBoundaries(t *testing.T) {
 	}
 }
 
+func TestComposeDocumentsAppendsRegisteredSequencesAndReturnsRanges(t *testing.T) {
+	first := parseCompositionDocument(t, "source-1", "records: [{id: '', left: 1}, {id: ' spaced ', right: 1}]\nother: [one]\n")
+	second := parseCompositionDocument(t, "source-2", "records: [{id: ' ', text: second}]\n")
+	firstBefore, secondBefore := document.Clone(first), document.Clone(second)
+	policy := sequencePolicy{identityFields: map[string]string{"/records": "id"}}
+
+	composed, diagnostics := composeDocumentsWithPolicy(policy, first, second)
+	if len(diagnostics) != 0 {
+		t.Fatalf("composeDocumentsWithPolicy() diagnostics = %#v", diagnostics)
+	}
+	records, ok := documentAtPath(composed.root, Keys("records"))
+	if !ok || records.Kind != document.Sequence || len(records.Sequence) != 3 {
+		t.Fatalf("records = %#v, want three appended records", records)
+	}
+	if got := composed.sequenceRanges; !reflect.DeepEqual(got, []sequenceRange{
+		{sourceIndex: 0, path: Keys("records"), start: 0, end: 2},
+		{sourceIndex: 1, path: Keys("records"), start: 2, end: 3},
+	}) {
+		t.Fatalf("sequence ranges = %#v", got)
+	}
+	if !reflect.DeepEqual(first, firstBefore) || !reflect.DeepEqual(second, secondBefore) {
+		t.Fatal("registered composition mutated an input")
+	}
+	composed.root.Mapping[0].Value.Sequence[0].Mapping[1].Value.Text = "changed"
+	if !reflect.DeepEqual(first, firstBefore) || !reflect.DeepEqual(second, secondBefore) {
+		t.Fatal("composed sequence aliases an input")
+	}
+}
+
+func TestComposeDocumentsProjectsSequenceOriginsToAssignedIndexes(t *testing.T) {
+	first := parseCompositionDocument(t, "source-1", `mounted:
+  records:
+    - id: first
+      name: first-name
+escaped/~:
+  "7":
+    - id: escaped-first
+      name: escaped-first-name
+`)
+	second := parseCompositionDocument(t, "source-2", `mounted:
+  records:
+    - id: second
+      name: second-name
+escaped/~:
+  "7":
+    - id: escaped-second
+      name: escaped-second-name
+`)
+	firstBefore, secondBefore := document.Clone(first), document.Clone(second)
+	policy := sequencePolicy{identityFields: map[string]string{
+		Keys("mounted", "records").String(): "id",
+		Keys("escaped/~", "7").String():     "id",
+	}}
+
+	composed, diagnostics := composeDocumentsWithPolicy(policy, first, second)
+	if len(diagnostics) != 0 {
+		t.Fatalf("composeDocumentsWithPolicy() diagnostics = %#v", diagnostics)
+	}
+	for _, test := range []struct {
+		path Path
+		want Location
+	}{
+		{path: Keys("mounted", "records").Index(1).Key("name"), want: Location{SourceID: "source-2", Line: 4, Column: 13}},
+		{path: Keys("escaped/~", "7").Index(1).Key("name"), want: Location{SourceID: "source-2", Line: 8, Column: 13}},
+	} {
+		path, want := test.path, test.want
+		origin, ok := composed.origins[path.String()]
+		if !ok || !reflect.DeepEqual(origin.Locations, []Location{want}) {
+			t.Errorf("origin at %s = %#v, want source-specific location %#v", path, origin, want)
+		}
+	}
+	for _, test := range []struct {
+		path        Path
+		wantSources []string
+	}{
+		{path: Keys("mounted", "records"), wantSources: []string{"source-1", "source-2"}},
+		{path: Keys("escaped/~", "7"), wantSources: []string{"source-1", "source-2"}},
+	} {
+		path, wantSources := test.path, test.wantSources
+		origin := composed.origins[path.String()]
+		gotSources := make([]string, len(origin.Locations))
+		for index, location := range origin.Locations {
+			gotSources[index] = location.SourceID
+		}
+		if !reflect.DeepEqual(gotSources, wantSources) {
+			t.Errorf("container origin at %s = %#v, want contributors %#v", path, gotSources, wantSources)
+		}
+	}
+	if !reflect.DeepEqual(first, firstBefore) || !reflect.DeepEqual(second, secondBefore) {
+		t.Fatal("composition projection mutated an input")
+	}
+
+	copy := cloneComposedDocument(composed)
+	copy.origins[Keys("mounted", "records").Index(1).Key("name").String()].Locations[0].SourceID = "changed"
+	for index := range copy.claims {
+		if copy.claims[index].path.String() == "/mounted/records" {
+			copy.claims[index].path.segments[0].key = "changed"
+			break
+		}
+	}
+	copy.sequenceRanges[0].path.segments[0].key = "changed"
+	if got := composed.origins[Keys("mounted", "records").Index(1).Key("name").String()].Locations[0].SourceID; got != "source-2" {
+		t.Fatalf("copied origin mutation changed source evidence: %q", got)
+	}
+	foundClaim := false
+	for _, claim := range composed.claims {
+		if claim.path.String() == "/mounted/records" {
+			foundClaim = true
+			break
+		}
+	}
+	if !foundClaim {
+		t.Fatal("copied claim mutation changed source path")
+	}
+	if got := composed.sequenceRanges[0].path.String(); got != "/mounted/records" {
+		t.Fatalf("copied range mutation changed assigned path: %q", got)
+	}
+}
+
+func TestComposeDocumentsValidatesRegisteredSequenceSingletons(t *testing.T) {
+	tests := []struct {
+		name     string
+		body     string
+		path     string
+		wantCode Code
+	}{
+		{name: "nonmapping item", body: "records: [plain]\n", path: "/records/0", wantCode: CodeComposeInvalid},
+		{name: "missing identity", body: "records: [{name: plain}]\n", path: "/records/0", wantCode: CodeComposeInvalid},
+		{name: "null identity", body: "records: [{id: null}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
+		{name: "numeric identity", body: "records: [{id: 12}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
+		{name: "boolean identity", body: "records: [{id: false}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, diagnostics := composeDocumentsWithPolicy(
+				sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+				parseCompositionDocument(t, "source-1", test.body),
+			)
+			if len(diagnostics) != 1 || diagnostics[0].Code != test.wantCode || diagnostics[0].Path.String() != test.path {
+				t.Fatalf("diagnostics = %#v, want %s at %s", diagnostics, test.wantCode, test.path)
+			}
+			if diagnostics[0].Primary == nil {
+				t.Fatal("malformed sequence diagnostic has no source location")
+			}
+		})
+	}
+}
+
+func TestComposeDocumentsReportsAssignedPathForMalformedRegisteredSequenceContribution(t *testing.T) {
+	_, diagnostics := composeDocumentsWithPolicy(
+		sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+		parseCompositionDocument(t, "source-1", "records: [{id: first}]\n"),
+		parseCompositionDocument(t, "source-2", "records: [{name: malformed}]\n"),
+	)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeInvalid || diagnostics[0].Path.String() != "/records/1" {
+		t.Fatalf("diagnostics = %#v, want invalid item at /records/1", diagnostics)
+	}
+	if diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
+		t.Fatalf("malformed item location = %#v, want source-2", diagnostics[0].Primary)
+	}
+}
+
+func TestComposeDocumentsRejectsRegisteredDuplicateIdentities(t *testing.T) {
+	tests := []struct {
+		name   string
+		first  string
+		second string
+		within bool
+	}{
+		{name: "within identical bodies", first: "records: [{id: '', value: same}, {id: '', value: same}]\n", within: true},
+		{name: "within disjoint bodies", first: "records: [{id: same, left: 1}, {id: same, right: 2}]\n", within: true},
+		{name: "across identical bodies", first: "records: [{id: same, value: same}]\n", second: "records: [{id: same, value: same}]\n"},
+		{name: "across disjoint bodies", first: "records: [{id: same, left: 1}]\n", second: "records: [{id: same, right: 2}]\n"},
+		{name: "empty identity across lists", first: "records: [{id: ''}]\n", second: "records: [{id: ''}]\n"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			inputs := []*document.Node{parseCompositionDocument(t, "source-1", test.first)}
+			if !test.within {
+				inputs = append(inputs, parseCompositionDocument(t, "source-2", test.second))
+			}
+			_, diagnostics := composeDocumentsWithPolicy(
+				sequencePolicy{identityFields: map[string]string{"/records": "id"}}, inputs...,
+			)
+			if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeConflict || diagnostics[0].Path.String() != "/records" {
+				t.Fatalf("diagnostics = %#v, want duplicate conflict at /records", diagnostics)
+			}
+			if diagnostics[0].Primary == nil || len(diagnostics[0].Related) != 1 {
+				t.Fatalf("duplicate locations = %#v", diagnostics[0])
+			}
+			for _, secret := range []string{"same", "left", "right", "value"} {
+				if strings.Contains(diagnostics[0].Message, secret) {
+					t.Fatalf("diagnostic leaks %q: %q", secret, diagnostics[0].Message)
+				}
+			}
+		})
+	}
+}
+
+func TestComposeDocumentsSkipsMissingAndNonSequenceRegistrations(t *testing.T) {
+	policy := sequencePolicy{identityFields: map[string]string{
+		"/absent": "id", "/not-a-sequence": "id", "/catalog": "id", "/catalog/records": "id",
+	}}
+	composed, diagnostics := composeDocumentsWithPolicy(policy, parseCompositionDocument(t, "source-1", `
+not-a-sequence: null
+catalog:
+  records: [{id: present}]
+`))
+	if len(diagnostics) != 0 {
+		t.Fatalf("composeDocumentsWithPolicy() diagnostics = %#v", diagnostics)
+	}
+	if len(composed.sequenceRanges) != 1 || composed.sequenceRanges[0].path.String() != "/catalog/records" {
+		t.Fatalf("sequence ranges = %#v, want only the reached descendant sequence", composed.sequenceRanges)
+	}
+
+	composed, diagnostics = composeDocumentsWithPolicy(
+		sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+		parseCompositionDocument(t, "source-1", "records: []\n"),
+		parseCompositionDocument(t, "source-2", "records: []\n"),
+	)
+	if len(diagnostics) != 0 || len(composed.root.Mapping[0].Value.Sequence) != 0 {
+		t.Fatalf("empty registered sequences = (%#v, %#v)", composed, diagnostics)
+	}
+	if got := composed.sequenceRanges; !reflect.DeepEqual(got, []sequenceRange{
+		{sourceIndex: 0, path: Keys("records"), start: 0, end: 0},
+		{sourceIndex: 1, path: Keys("records"), start: 0, end: 0},
+	}) {
+		t.Fatalf("empty sequence ranges = %#v", got)
+	}
+}
+
+func TestComposeDocumentsKeepsUnregisteredSequenceConflicts(t *testing.T) {
+	_, diagnostics := composeDocumentsWithPolicy(
+		sequencePolicy{identityFields: map[string]string{"/registered": "id"}},
+		parseCompositionDocument(t, "source-1", "unregistered: [one]\n"),
+		parseCompositionDocument(t, "source-2", "unregistered: [two]\n"),
+	)
+	assertCompositionConflict(t, diagnostics, "/unregistered", []string{"source-1", "source-2"})
+}
+
+func TestComposeDocumentsKeepsNonSequenceRegisteredOverlapsConflicting(t *testing.T) {
+	tests := []struct {
+		name   string
+		first  string
+		second string
+	}{
+		{name: "mapping and sequence", first: "records: {id: one}\n", second: "records: [{id: two}]\n"},
+		{name: "null and sequence", first: "records: null\n", second: "records: [{id: two}]\n"},
+		{name: "scalar and sequence", first: "records: value\n", second: "records: [{id: two}]\n"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, diagnostics := composeDocumentsWithPolicy(
+				sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+				parseCompositionDocument(t, "source-1", test.first),
+				parseCompositionDocument(t, "source-2", test.second),
+			)
+			assertCompositionConflict(t, diagnostics, "/records", []string{"source-1", "source-2"})
+		})
+	}
+}
+
 func parseCompositionDocument(t *testing.T, sourceID, input string) *document.Node {
 	t.Helper()
 	parsed, diagnostics := parseSource(Bytes(sourceID, []byte(input)), sourceID, defaultParseLimits())

internal/engine/destination.go

@@ -0,0 +1,197 @@
+package engine
+
+import (
+	"errors"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+var (
+	errInvalidDestination = errors.New("configkit: destination must contain only non-reserved mapping keys")
+	errDestinationLimit   = errors.New("configkit: destination exceeds document limits")
+)
+
+type placementMode uint8
+
+const (
+	placementModeMapping placementMode = iota
+	placementModeSequenceItem
+)
+
+// PlacementModeFromFacade preserves root-owned numeric values until preflight
+// can reject unsupported modes.
+func PlacementModeFromFacade(value uint8) placementMode { return placementMode(value) }
+
+// PlacementModeForFacade converts private source evidence to the root-owned mode.
+func PlacementModeForFacade(value placementMode) uint8 { return uint8(value) }
+
+// InputWithPlacement copies the root-owned mode into a private engine input.
+func InputWithPlacement(input Input, value uint8) Input {
+	input.placementMode = placementMode(value)
+	return input
+}
+
+// OptionsWithPlacement copies root-owned controls into private engine options.
+func OptionsWithPlacement[T any](options Options[T], destination Path, value uint8) Options[T] {
+	options.destination = destination.clone()
+	options.placementMode = placementMode(value)
+	return options
+}
+
+func normalizeDestination(path Path) (Path, error) {
+	if !path.valid() {
+		return Path{}, errInvalidDestination
+	}
+
+	segments := make([]pathSegment, 0, len(path.segments))
+	for _, segment := range path.segments {
+		if segment.kind != pathSegmentKey && segment.kind != pathSegmentParsed {
+			return Path{}, errInvalidDestination
+		}
+		if segment.key == "configkit" || segment.key == "extends" {
+			return Path{}, errInvalidDestination
+		}
+		segments = append(segments, pathSegment{kind: pathSegmentKey, key: segment.key})
+	}
+	return Path{segments: segments}, nil
+}
+
+// appendDestination combines validated mapping-key paths with owned segments.
+func appendDestination(parent, relative Path) Path {
+	segments := clonePathSegments(parent.segments, len(relative.segments))
+	segments = append(segments, relative.segments...)
+	return Path{segments: segments}
+}
+
+func invalidDestinationDiagnostic(destination Path) Diagnostic {
+	return Diagnostic{
+		Code: CodeOptionsInvalid, Severity: SeverityError,
+		Path:    destination.clone(),
+		Message: "input destination must contain only non-reserved mapping keys",
+	}
+}
+
+// placeDocument checks all per-document bounds before allocating destination
+// wrappers. Aggregate accounting remains the caller's responsibility.
+func placeDocument(body *document.Node, destination Path, sourceRoot document.Location, maxDepth, maxNodes int) (Path, *document.Node, error) {
+	return placeDocumentWithMode(body, destination, placementModeMapping, sourceRoot, maxDepth, maxNodes)
+}
+
+// placeDocumentWithMode places a source mapping beneath its literal destination.
+// Sequence-item placement adds one sequence containing the complete mapping.
+func placeDocumentWithMode(body *document.Node, destination Path, mode placementMode, sourceRoot document.Location, maxDepth, maxNodes int) (Path, *document.Node, error) {
+	normalized, err := normalizeDestination(destination)
+	if err != nil {
+		return Path{}, nil, err
+	}
+	if mode != placementModeMapping && mode != placementModeSequenceItem {
+		return Path{}, nil, errInvalidDestination
+	}
+	if mode == placementModeSequenceItem && len(normalized.segments) == 0 {
+		return Path{}, nil, errInvalidDestination
+	}
+	if body == nil {
+		return normalized, nil, nil
+	}
+	if mode == placementModeSequenceItem && body.Kind != document.Mapping {
+		return normalized, nil, errInvalidDestination
+	}
+	if !destinationWithinLimitsWithMode(body, normalized, mode, maxDepth, maxNodes) {
+		return normalized, nil, errDestinationLimit
+	}
+
+	placed := body
+	if mode == placementModeSequenceItem {
+		placed = &document.Node{
+			Kind: document.Sequence, Location: sourceRoot,
+			Sequence: []*document.Node{placed},
+		}
+	}
+	for index := len(normalized.segments) - 1; index >= 0; index-- {
+		key := normalized.segments[index].key
+		placed = &document.Node{
+			Kind:     document.Mapping,
+			Location: sourceRoot,
+			Mapping: []document.Entry{{
+				Key:           key,
+				KeyLocation:   sourceRoot,
+				ValueLocation: sourceRoot,
+				Value:         placed,
+			}},
+		}
+	}
+	return normalized, placed, nil
+}
+
+// destinationWithinLimits expects a normalized mapping-key destination.
+func destinationWithinLimits(body *document.Node, destination Path, maxDepth, maxNodes int) bool {
+	return destinationWithinLimitsWithMode(body, destination, placementModeMapping, maxDepth, maxNodes)
+}
+
+func destinationWithinLimitsWithMode(body *document.Node, destination Path, mode placementMode, maxDepth, maxNodes int) bool {
+	if body == nil {
+		return true
+	}
+	if maxDepth < 0 || maxNodes < 0 || !destination.valid() || (mode != placementModeMapping && mode != placementModeSequenceItem) {
+		return false
+	}
+	segments := len(destination.segments)
+	sequenceNodes := 0
+	sequenceDepth := 0
+	if mode == placementModeSequenceItem {
+		if segments == 0 {
+			return false
+		}
+		sequenceNodes = 1
+		sequenceDepth = 1
+	}
+	if segments > maxDepth-sequenceDepth || segments > (maxNodes-sequenceNodes)/2 {
+		return false
+	}
+	wrapperNodes := destinationWrapperNodeCount(destination) + sequenceNodes
+	for _, segment := range destination.segments {
+		if segment.kind != pathSegmentKey {
+			return false
+		}
+	}
+	if documentDepth(body) > maxDepth-segments-sequenceDepth {
+		return false
+	}
+	return countInputNodes(body) <= maxNodes-wrapperNodes
+}
+
+func destinationWrapperNodeCountForMode(destination Path, mode placementMode) int {
+	count := destinationWrapperNodeCount(destination)
+	if mode == placementModeSequenceItem {
+		count++
+	}
+	return count
+}
+
+func destinationWrapperNodeCount(destination Path) int {
+	return 2 * len(destination.segments)
+}
+
+func documentDepth(node *document.Node) int {
+	if node == nil {
+		return -1
+	}
+	depth := 0
+	var visit func(*document.Node, int)
+	visit = func(current *document.Node, currentDepth int) {
+		if current == nil {
+			return
+		}
+		if currentDepth > depth {
+			depth = currentDepth
+		}
+		for _, entry := range current.Mapping {
+			visit(entry.Value, currentDepth+1)
+		}
+		for _, child := range current.Sequence {
+			visit(child, currentDepth+1)
+		}
+	}
+	visit(node, 0)
+	return depth
+}

internal/engine/destination_accounting_test.go

@@ -0,0 +1,439 @@
+package engine
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"testing/fstest"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestDestinationPlacementCountsAgainstSharedNodeBudget(t *testing.T) {
+	t.Parallel()
+
+	limits := defaultImportLimits()
+	destination := Keys("collections", "entry")
+	empty := Mapping("empty", map[string]any{})
+	parsed, diagnostics := parseSource(empty, "fixture", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	perInput := countInputNodes(parsed.document) + destinationWrapperNodeCount(destination)
+
+	for _, test := range []struct {
+		name       string
+		delta      int
+		wantError  bool
+		wantCharge int
+	}{
+		{name: "below aggregate bound", delta: -1, wantCharge: perInput},
+		{name: "at aggregate bound", delta: 0, wantCharge: perInput},
+		{name: "above aggregate bound", delta: 1, wantError: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			accounting := &importAccounting{nodes: limits.nodes - perInput + test.delta}
+			composition, _, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{
+				source: empty, destination: destination,
+			}}}, 1, nil, accounting)
+			if test.wantError {
+				if composition != nil || len(diagnostics) != 1 || diagnostics[0].Code != CodeSourceLimitExceeded {
+					t.Fatalf("over-budget placement = %#v, %#v", composition, diagnostics)
+				}
+				return
+			}
+			if composition == nil || len(diagnostics) != 0 || composition.inputNodes != test.wantCharge {
+				t.Fatalf("bounded placement = %#v, %#v", composition, diagnostics)
+			}
+		})
+	}
+}
+
+func TestMultipleMountedInputsSharePlacementCharges(t *testing.T) {
+	t.Parallel()
+
+	limits := defaultImportLimits()
+	inputs := []loadInput{
+		{source: Mapping("one", map[string]any{}), destination: Keys("collection", "one")},
+		{source: Mapping("two", map[string]any{}), destination: Keys("collection", "two")},
+		{source: Mapping("three", map[string]any{}), destination: Keys("collection", "three")},
+	}
+	perInput := countInputNodes(&document.Node{Kind: document.Mapping}) + destinationWrapperNodeCount(Keys("collection", "one"))
+	charge := len(inputs) * perInput
+	accounting := &importAccounting{nodes: limits.nodes - charge}
+	composition, _, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: inputs}, 1, nil, accounting)
+	if len(diagnostics) != 0 || composition == nil || accounting.nodes != limits.nodes || composition.inputNodes != charge {
+		t.Fatalf("shared placement accounting = %#v, %#v, accounting %#v; want charge %d", composition, diagnostics, accounting, charge)
+	}
+}
+
+func TestNestedItemGlobsShareUnderlayNodeBudget(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - glob: children/*.yml
+      destination: [children]
+      placement: sequence-item
+id: parent
+`)
+	fragmentPath := writeImportFile(t, directory, "children/a.yml", "id: child-a\n")
+	parseNodes := func(path string) int {
+		t.Helper()
+		parsed, diagnostics := parseSource(File(path), "fixture", defaultParseLimits())
+		if len(diagnostics) != 0 {
+			t.Fatalf("parse %s: %#v", path, diagnostics)
+		}
+		return countInputNodes(parsed.document)
+	}
+	destination := Keys("groups")
+	childDestination := appendDestination(destination, Keys("children"))
+	otherDestination := Keys("other")
+	wantNodes := parseNodes(mainPath) + parseNodes(fragmentPath) + countInputNodes(&document.Node{Kind: document.Mapping}) +
+		destinationWrapperNodeCountForMode(destination, placementModeSequenceItem) +
+		destinationWrapperNodeCountForMode(childDestination, placementModeSequenceItem) +
+		destinationWrapperNodeCountForMode(otherDestination, placementModeSequenceItem)
+	limits := defaultImportLimits()
+
+	for _, test := range []struct {
+		name      string
+		delta     int
+		wantError bool
+	}{
+		{name: "at aggregate bound"},
+		{name: "one node below aggregate bound", delta: 1, wantError: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			accounting := &importAccounting{nodes: limits.nodes - wantNodes + test.delta}
+			composition, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{
+				source: File(mainPath), imports: true, destination: destination, placementMode: placementModeSequenceItem,
+			}, {
+				source: Mapping("other", map[string]any{"id": "other"}), destination: otherDestination, placementMode: placementModeSequenceItem,
+			}}}, 1, nil, accounting)
+			if test.wantError {
+				if composition != nil || len(diagnostics) == 0 || diagnostics[0].Code != CodeSourceLimitExceeded {
+					t.Fatalf("under-budget nested item glob = %#v, %#v", composition, diagnostics)
+				}
+				return
+			}
+			if composition == nil || len(diagnostics) != 0 || len(sources) != 3 {
+				t.Fatalf("bounded nested item glob = %#v, sources %#v, diagnostics %#v", composition, sources, diagnostics)
+			}
+			if composition.inputNodes != wantNodes || accounting.nodes != limits.nodes+test.delta {
+				t.Fatalf("nested item node charge = %d/%d, want %d/%d", composition.inputNodes, accounting.nodes, wantNodes, limits.nodes+test.delta)
+			}
+		})
+	}
+}
+
+func TestImportedEmptyBodiesChargeEachDestinationWrapper(t *testing.T) {
+	t.Parallel()
+
+	filesystem := NewFilesystem("bundle", fstest.MapFS{
+		"main.yml":     &fstest.MapFile{Data: []byte("configkit: {imports: [{path: fragment.yml}]}\n")},
+		"fragment.yml": &fstest.MapFile{Data: []byte("{}\n")},
+	})
+	mainSource := filesystem.File("main.yml")
+	mainParsed, diagnostics := parseSource(mainSource, "fixture", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	fragmentParsed, diagnostics := parseSource(Bytes("fragment", []byte("{}\n")), "fixture", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	rawNodes := countInputNodes(mainParsed.document) + countInputNodes(fragmentParsed.document)
+	destination := Keys("collection", "empty")
+	placementNodes := 2 * destinationWrapperNodeCount(destination)
+	limits := defaultImportLimits()
+	for _, test := range []struct {
+		name      string
+		delta     int
+		wantError bool
+	}{
+		{name: "below aggregate bound", delta: -1},
+		{name: "at aggregate bound", delta: 0},
+		{name: "above aggregate bound", delta: 1, wantError: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			accounting := &importAccounting{nodes: limits.nodes - rawNodes - placementNodes + test.delta}
+			composition, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{
+				source: mainSource, imports: true, destination: destination,
+			}}}, 1, nil, accounting)
+			if test.wantError {
+				if composition != nil || len(diagnostics) == 0 || diagnostics[0].Code != CodeImportLimitExceeded {
+					t.Fatalf("over-budget imports = %#v, %#v", composition, diagnostics)
+				}
+				return
+			}
+			if len(diagnostics) != 0 || composition == nil || len(sources) != 2 {
+				t.Fatalf("bounded imports = %#v, sources %#v, diagnostics %#v", composition, sources, diagnostics)
+			}
+			if composition.inputNodes != rawNodes+placementNodes || accounting.nodes != limits.nodes+test.delta {
+				t.Fatalf("import node charge = %d, accounting %d; want %d and %d", composition.inputNodes, accounting.nodes, rawNodes+placementNodes, limits.nodes+test.delta)
+			}
+			if node, present := documentAtPath(composition.root, Keys("collection", "empty")); !present || node.Kind != document.Mapping || len(node.Mapping) != 0 {
+				t.Fatalf("placed empty import body = %#v, present %v", node, present)
+			}
+		})
+	}
+}
+
+func TestImportedEmptyBodiesChargeFullRelativeDestinations(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: empty.yml
+      destination: [groups, empty]
+`)
+	fragmentPath := writeImportFile(t, directory, "empty.yml", "{}\n")
+	main := parseImportMain(t, mainPath)
+	fragment, diagnostics := parseSource(File(fragmentPath), "source-2", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("empty fragment diagnostics = %#v", diagnostics)
+	}
+	entryDestination := Keys("collections", "entry")
+	importDestination := appendDestination(entryDestination, Keys("groups", "empty"))
+	wantNodes := countInputNodes(main.document) + countInputNodes(fragment.document) +
+		destinationWrapperNodeCount(entryDestination) + destinationWrapperNodeCount(importDestination)
+	limits := defaultImportLimits()
+
+	for _, test := range []struct {
+		name      string
+		delta     int
+		wantError bool
+	}{
+		{name: "below aggregate bound", delta: -1, wantError: true},
+		{name: "at aggregate bound"},
+		{name: "above aggregate bound", delta: 1},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			currentLimits := limits
+			currentLimits.nodes = wantNodes + test.delta
+			accounting := &importAccounting{}
+			composed, sources, diagnostics := loadImportedDocumentsTracked(
+				File(mainPath), nil, main, entryDestination, nil, currentLimits, accounting, nil, nil,
+			)
+			if test.wantError {
+				if composed != nil || len(diagnostics) != 1 || diagnostics[0].Code != CodeImportLimitExceeded {
+					t.Fatalf("below-bound relative placement = %#v, %#v", composed, diagnostics)
+				}
+				return
+			}
+			if len(diagnostics) != 0 || composed == nil || len(sources) != 2 {
+				t.Fatalf("bounded relative placement = %#v, %#v, %#v", composed, sources, diagnostics)
+			}
+			if composed.inputNodes != wantNodes || accounting.nodes != wantNodes {
+				t.Fatalf("relative placement node charge = %d/%d, want %d", composed.inputNodes, accounting.nodes, wantNodes)
+			}
+			if sources[1].Destination.String() != importDestination.String() {
+				t.Fatalf("empty import destination = %q, want %q", sources[1].Destination.String(), importDestination.String())
+			}
+			if node, present := documentAtPath(composed.root, importDestination); !present || node.Kind != document.Mapping || len(node.Mapping) != 0 {
+				t.Fatalf("empty relative import body = %#v, present %v", node, present)
+			}
+		})
+	}
+}
+
+func TestGlobMatchesChargeTheirSharedRelativeDestination(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - glob: fragments/*.yml
+      destination: [groups, empty]
+`)
+	fragmentPaths := []string{
+		writeImportFile(t, directory, "fragments/a.yml", "{}\n"),
+		writeImportFile(t, directory, "fragments/b.yml", "{}\n"),
+		writeImportFile(t, directory, "fragments/c.yml", "{}\n"),
+	}
+	main := parseImportMain(t, mainPath)
+	fragment, diagnostics := parseSource(File(fragmentPaths[0]), "source-fragment", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("glob fragment diagnostics = %#v", diagnostics)
+	}
+	entryDestination := Keys("collections", "entry")
+	importDestination := appendDestination(entryDestination, Keys("groups", "empty"))
+	wantNodes := countInputNodes(main.document) + len(fragmentPaths)*countInputNodes(fragment.document) +
+		destinationWrapperNodeCount(entryDestination) + len(fragmentPaths)*destinationWrapperNodeCount(importDestination)
+	limits := defaultImportLimits()
+
+	for _, test := range []struct {
+		name      string
+		delta     int
+		wantError bool
+	}{
+		{name: "below aggregate bound", delta: -1, wantError: true},
+		{name: "at aggregate bound"},
+		{name: "above aggregate bound", delta: 1},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			currentLimits := limits
+			currentLimits.nodes = wantNodes + test.delta
+			accounting := &importAccounting{}
+			composed, sources, diagnostics := loadImportedDocumentsTracked(
+				File(mainPath), nil, main, entryDestination, nil, currentLimits, accounting, nil, nil,
+			)
+			if test.wantError {
+				if composed != nil || len(diagnostics) != 1 || diagnostics[0].Code != CodeImportLimitExceeded {
+					t.Fatalf("below-bound glob placement = %#v, %#v", composed, diagnostics)
+				}
+				return
+			}
+			if len(diagnostics) != 0 || composed == nil || len(sources) != len(fragmentPaths)+1 {
+				t.Fatalf("bounded glob placement = %#v, %#v, %#v", composed, sources, diagnostics)
+			}
+			if composed.inputNodes != wantNodes || accounting.nodes != wantNodes {
+				t.Fatalf("glob relative placement node charge = %d/%d, want %d", composed.inputNodes, accounting.nodes, wantNodes)
+			}
+			for index, source := range sources[1:] {
+				if source.Destination.String() != importDestination.String() {
+					t.Errorf("glob source %d destination = %q, want %q", index, source.Destination.String(), importDestination.String())
+				}
+			}
+			if node, present := documentAtPath(composed.root, importDestination); !present || node.Kind != document.Mapping || len(node.Mapping) != 0 {
+				t.Fatalf("empty glob contributions = %#v, present %v", node, present)
+			}
+		})
+	}
+}
+
+func TestRelativeImportDestinationUsesAccumulatedDocumentDepth(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: fragment.yml, destination: [extra]}]}\n")
+	writeImportFile(t, directory, "fragment.yml", "value: nested\n")
+	destination := Path{segments: make([]pathSegment, maxDocumentDepth)}
+	for index := range destination.segments {
+		destination.segments[index] = pathSegment{kind: pathSegmentKey, key: "entry"}
+	}
+	_, err := LoadLayered(
+		Input{Source: File(mainPath), Imports: true, Destination: destination}, testSecretBinding(),
+		LayeredOptions[map[string]any]{},
+	)
+	loadError, ok := err.(*LoadError)
+	if !ok || len(loadError.Diagnostics()) != 1 || loadError.Diagnostics()[0].Code != CodeImportLimitExceeded {
+		t.Fatalf("accumulated depth result = %v", err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 2 || len(sources[0].Destination.segments) != maxDocumentDepth || len(sources[1].Destination.segments) != maxDocumentDepth+1 {
+		t.Fatalf("depth failure source destinations = %#v", sources)
+	}
+}
+
+func TestAbsentOptionalImportsDoNotChargeUnusedDeepDestinations(t *testing.T) {
+	t.Parallel()
+
+	destination := Path{segments: make([]pathSegment, maxDocumentDepth)}
+	for index := range destination.segments {
+		destination.segments[index] = pathSegment{kind: pathSegmentKey, key: "entry"}
+	}
+
+	for _, test := range []struct {
+		name  string
+		body  string
+		setup func(*testing.T, string)
+	}{
+		{
+			name: "optional missing path",
+			body: "configkit: {imports: [{path: missing.yml, optional: true, destination: [unused]}]}\n",
+		},
+		{
+			name: "optional unmatched glob",
+			body: "configkit: {imports: [{glob: empty/*.yml, optional: true, destination: [unused]}]}\n",
+			setup: func(t *testing.T, directory string) {
+				if err := os.Mkdir(filepath.Join(directory, "empty"), 0o755); err != nil {
+					t.Fatal(err)
+				}
+			},
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			directory := t.TempDir()
+			if test.setup != nil {
+				test.setup(t, directory)
+			}
+			mainPath := writeImportFile(t, directory, "main.yml", test.body)
+			main := parseImportMain(t, mainPath)
+			limits := defaultImportLimits()
+			accounting := &importAccounting{}
+			composed, sources, diagnostics := loadImportedDocumentsTracked(
+				File(mainPath), nil, main, destination, nil, limits, accounting, nil, nil,
+			)
+			if len(diagnostics) != 0 || composed == nil || len(sources) != 1 {
+				t.Fatalf("absent optional import = %#v, %#v, %#v", composed, sources, diagnostics)
+			}
+			wantNodes := countInputNodes(main.document) + destinationWrapperNodeCount(destination)
+			if composed.inputNodes != wantNodes || accounting.nodes != wantNodes {
+				t.Fatalf("absent optional node charge = %d/%d, want %d", composed.inputNodes, accounting.nodes, wantNodes)
+			}
+			if node, present := documentAtPath(composed.root, destination); !present || node.Kind != document.Mapping || len(node.Mapping) != 0 {
+				t.Fatalf("empty entry body = %#v, present %v", node, present)
+			}
+		})
+	}
+}
+
+func TestNoSourceAndRootPlacementAddNoWrapperCharges(t *testing.T) {
+	t.Parallel()
+
+	accounting := &importAccounting{}
+	composition, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{
+		{source: NoSource(), destination: Keys("absent")},
+		{source: Mapping("root", map[string]any{})},
+	}}, 1, nil, accounting)
+	if len(diagnostics) != 0 || composition == nil || len(sources) != 1 || accounting.nodes != 1 || composition.inputNodes != 1 {
+		t.Fatalf("root and absent placement = %#v, sources %#v, diagnostics %#v, accounting %#v", composition, sources, diagnostics, accounting)
+	}
+}
+
+func TestSelectedOverlayAndCLIUsePlacementNodeCharges(t *testing.T) {
+	t.Parallel()
+
+	limits := defaultImportLimits()
+	baseNodes := countInputNodes(&document.Node{Kind: document.Mapping}) + destinationWrapperNodeCount(Keys("mounted"))
+
+	t.Run("selected overlay", func(t *testing.T) {
+		t.Parallel()
+		filesystem := NewFilesystem("bundle", fstest.MapFS{
+			"overlays/test.yml": &fstest.MapFile{Data: []byte("{}\n")},
+		})
+		request := loadRequest[map[string]any]{
+			underlays: []loadGroup{{inputs: []loadInput{{source: Mapping("empty", map[string]any{}), destination: Keys("mounted")}}}},
+			overlay:   "test", overlayFilesystem: &FilesystemContext{Root: ".", BaseDir: ".", FS: &filesystem},
+		}
+		accounting := &importAccounting{nodes: limits.nodes - baseNodes}
+		_, diagnostics := assembleLayeredInput(request, assembledInput{}, accounting)
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverlayLimitExceeded {
+			t.Fatalf("overlay diagnostics = %#v", diagnostics)
+		}
+	})
+
+	t.Run("CLI override", func(t *testing.T) {
+		t.Parallel()
+		override := Override{Path: Keys("mounted", "value"), Value: "x", Flag: "--value"}
+		builder := valueBuilder{sourceID: "fixture", active: make(map[valueVisit]bool)}
+		if _, issue := builder.build(override.Value, override.Path, len(override.Path.segments)); issue != nil {
+			t.Fatal(issue)
+		}
+		overrideNodes := builder.nodes + destinationWrapperNodeCount(override.Path)
+		request := loadRequest[map[string]any]{
+			underlays: []loadGroup{{inputs: []loadInput{{source: Mapping("empty", map[string]any{}), destination: Keys("mounted")}}}},
+			overrides: []Override{override},
+		}
+		accounting := &importAccounting{nodes: limits.nodes - baseNodes - overrideNodes + 1}
+		_, diagnostics := assembleLayeredInput(request, assembledInput{}, accounting)
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverrideLimitExceeded {
+			t.Fatalf("override diagnostics = %#v", diagnostics)
+		}
+	})
+}

internal/engine/destination_diagnostic_test.go

@@ -0,0 +1,142 @@
+package engine
+
+import (
+	"path/filepath"
+	"testing"
+	"testing/fstest"
+)
+
+func TestLayeredDestinationDiagnosticsUseEffectivePathsAndAuthoredLocations(t *testing.T) {
+	t.Parallel()
+
+	t.Run("strict conflict retains both source locations", func(t *testing.T) {
+		t.Parallel()
+		loaded, err := LoadLayered(
+			Input{Source: NoSource()},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{Underlays: []Underlay{{Inputs: []Input{
+				{Source: Bytes("left", []byte("section:\n  value: left\n")), Destination: Keys("application")},
+				{Source: Bytes("right", []byte("section:\n  value: right\n")), Destination: Keys("application")},
+			}}}},
+		)
+		if loaded != nil {
+			t.Fatalf("conflicting load returned a result: %#v", loaded)
+		}
+		diagnostic := firstDestinationDiagnostic(t, err)
+		if diagnostic.Code != CodeComposeConflict || diagnostic.Path.String() != "/application/section/value" {
+			t.Fatalf("conflict diagnostic = %#v", diagnostic)
+		}
+		if diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-1" || diagnostic.Primary.Line != 2 {
+			t.Fatalf("primary location = %#v", diagnostic.Primary)
+		}
+		if len(diagnostic.Related) != 1 || diagnostic.Related[0].SourceID != "source-2" || diagnostic.Related[0].Line != 2 {
+			t.Fatalf("related locations = %#v", diagnostic.Related)
+		}
+	})
+
+	t.Run("decode failure keeps effective path and content line", func(t *testing.T) {
+		t.Parallel()
+		type section struct {
+			Count int `yaml:"count"`
+		}
+		type config struct {
+			Application struct {
+				Section section `yaml:"section"`
+			} `yaml:"application"`
+		}
+		loaded, err := LoadLayered(
+			Input{Source: Bytes("main", []byte("section:\n  count: invalid\n")), Destination: Keys("application")},
+			testSecretBinding(),
+			LayeredOptions[config]{},
+		)
+		if loaded != nil {
+			t.Fatalf("invalid load returned a result: %#v", loaded)
+		}
+		diagnostic := firstDestinationDiagnostic(t, err)
+		if diagnostic.Code != CodeDecodeType || diagnostic.Path.String() != "/application/section/count" {
+			t.Fatalf("decode diagnostic = %#v", diagnostic)
+		}
+		if diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-1" || diagnostic.Primary.Line != 2 {
+			t.Fatalf("decode location = %#v", diagnostic.Primary)
+		}
+	})
+
+	t.Run("imported version failure uses effective path and import source", func(t *testing.T) {
+		t.Parallel()
+		directory := t.TempDir()
+		writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: fragment.yml}]}\n")
+		writeImportFile(t, directory, "fragment.yml", "version: forbidden\n")
+		rule := &VersionRule{Path: Keys("application", "version"), Check: func(Version, *Validation) error { return nil }}
+		loaded, err := LoadLayered(
+			Input{Source: NoSource()},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{
+				Definition: Definition[map[string]any]{Version: rule},
+				Underlays: []Underlay{{Inputs: []Input{{
+					Source: File(filepath.Join(directory, "main.yml")), Imports: true, Destination: Keys("application"),
+				}}}},
+			},
+		)
+		if loaded != nil {
+			t.Fatalf("invalid import returned a result: %#v", loaded)
+		}
+		diagnostic := firstDestinationDiagnostic(t, err)
+		if diagnostic.Code != CodeImportVersion || diagnostic.Path.String() != "/application/version" {
+			t.Fatalf("import version diagnostic = %#v", diagnostic)
+		}
+		if diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-2" || diagnostic.Primary.Line != 1 {
+			t.Fatalf("import version location = %#v", diagnostic.Primary)
+		}
+	})
+
+	t.Run("invalid destination has no fictional source location", func(t *testing.T) {
+		t.Parallel()
+		loaded, err := LoadLayered(
+			Input{Source: Bytes("main", []byte("value: present\n")), Destination: Keys("configkit")},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{},
+		)
+		if loaded != nil {
+			t.Fatalf("invalid destination returned a result: %#v", loaded)
+		}
+		diagnostic := firstDestinationDiagnostic(t, err)
+		if diagnostic.Code != CodeOptionsInvalid || diagnostic.Path.String() != "/configkit" || diagnostic.Primary != nil {
+			t.Fatalf("invalid destination diagnostic = %#v", diagnostic)
+		}
+	})
+
+	t.Run("malformed source directive keeps its local path and location", func(t *testing.T) {
+		t.Parallel()
+		filesystem := NewFilesystem("bundle", fstest.MapFS{
+			"main.yml": &fstest.MapFile{Data: []byte("configkit: {imports: [true]}\nvalue: present\n")},
+		})
+		loaded, err := LoadLayered(
+			Input{Source: filesystem.File("main.yml"), Imports: true, Destination: Keys("application")},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{},
+		)
+		if loaded != nil {
+			t.Fatalf("malformed directive returned a result: %#v", loaded)
+		}
+		diagnostic := firstDestinationDiagnostic(t, err)
+		if diagnostic.Code != CodeImportInvalid || diagnostic.Path.String() != "/configkit/imports/0" {
+			t.Fatalf("malformed directive diagnostic = %#v", diagnostic)
+		}
+		if diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-1" || diagnostic.Primary.Line != 1 {
+			t.Fatalf("malformed directive location = %#v", diagnostic.Primary)
+		}
+	})
+}
+
+func firstDestinationDiagnostic(t *testing.T, err error) Diagnostic {
+	t.Helper()
+	loadError, ok := err.(*LoadError)
+	if !ok {
+		t.Fatalf("load error = %#v", err)
+	}
+	diagnostics := loadError.Diagnostics()
+	if len(diagnostics) == 0 {
+		t.Fatal("load error has no diagnostics")
+	}
+	return diagnostics[0]
+}

internal/engine/destination_import_lifecycle_test.go

@@ -0,0 +1,211 @@
+package engine
+
+import (
+	"bytes"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func TestRelativeImportsFeedFinalInheritanceAndInspectionLifecycle(t *testing.T) {
+	t.Parallel()
+
+	type entry struct {
+		Extends string  `yaml:"extends"`
+		Label   string  `yaml:"label"`
+		Token   *Secret `yaml:"token" configkit:"secret"`
+		Dynamic string  `yaml:"dynamic"`
+		Derived string  `yaml:"derived"`
+		Height  int     `yaml:"height"`
+	}
+	type configuration struct {
+		Catalog struct {
+			Entries map[string]entry `yaml:"entries"`
+		} `yaml:"catalog"`
+	}
+
+	load := func(dynamic string) *testResult[configuration] {
+		t.Helper()
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "entry.yml", `configkit:
+  imports:
+    - path: parent.yml
+      destination: [entries]
+    - path: child.yml
+      destination: [entries]
+`)
+		writeImportFile(t, directory, "parent.yml", `parent:
+  label: lower
+  token: PARENT_TOKEN
+  height: 1
+`)
+		writeImportFile(t, directory, "child.yml", fmt.Sprintf(`child:
+  extends: parent
+  label: child
+  dynamic: %s
+  height: 9
+`, dynamic))
+
+		var defaultsCalls, resolveCalls, validateCalls int
+		secretPaths := make(map[string]bool)
+		lookupCalls := make(map[string]int)
+		request := loadRequest[configuration]{
+			main: loadInput{
+				source:      Bytes("main", []byte("parent: {label: final, height: 4}\n")),
+				destination: Keys("catalog", "entries"),
+			},
+			underlays: []loadGroup{{inputs: []loadInput{{
+				source: File(mainPath), imports: true, destination: Keys("catalog"),
+			}}}},
+			definition: Definition[configuration]{
+				Defaults: func() configuration {
+					defaultsCalls++
+					var defaults configuration
+					defaults.Catalog.Entries = map[string]entry{"fallback": {Label: "default"}}
+					return defaults
+				},
+				Resolve: func(config *configuration, resolution *Resolution) error {
+					resolveCalls++
+					child := config.Catalog.Entries["child"]
+					child.Derived = child.Label + ":" + child.Dynamic + ":" + fmt.Sprint(child.Height)
+					config.Catalog.Entries["child"] = child
+					resolution.Record(Keys("catalog", "entries", "child", "derived"), ChangeNormalization, "derive final child summary", Keys("catalog", "entries", "child", "label"), Keys("catalog", "entries", "child", "dynamic"), Keys("catalog", "entries", "child", "height"))
+					return nil
+				},
+				Validate: func(config *configuration, validation *Validation) {
+					validateCalls++
+					parent := config.Catalog.Entries["parent"]
+					child := config.Catalog.Entries["child"]
+					if parent.Label != "final" || parent.Height != 4 || child.Label != "child" || child.Height != 9 || child.Derived != child.Label+":"+child.Dynamic+":9" || child.Token == nil || !child.Token.IsResolved() || child.Token.Value() != "parent-secret-canary" {
+						validation.Error(Keys("catalog", "entries", "child"), "final imported configuration was not available to validation")
+					}
+				},
+				Secret: func(path Path) bool {
+					secretPaths[path.String()] = true
+					return path.String() == "/catalog/entries/child/dynamic"
+				},
+			},
+		}
+		loaded, err := loadGroupedWithSecretLookup(request, testSecretBinding(), func(name string) (string, bool) {
+			lookupCalls[name]++
+			if name == "PARENT_TOKEN" {
+				return "parent-secret-canary", true
+			}
+			return "", false
+		})
+		if err != nil {
+			if loadError, ok := err.(*LoadError); ok {
+				t.Fatalf("relative import lifecycle diagnostics: %#v", loadError.Diagnostics())
+			}
+			t.Fatalf("relative import lifecycle: %v", err)
+		}
+		if defaultsCalls != 1 || resolveCalls != 1 || validateCalls != 1 || lookupCalls["PARENT_TOKEN"] != 1 {
+			t.Fatalf("lifecycle calls defaults=%d resolve=%d validate=%d lookups=%#v", defaultsCalls, resolveCalls, validateCalls, lookupCalls)
+		}
+		if !secretPaths["/catalog/entries/child/dynamic"] {
+			t.Fatalf("secret classifier did not see effective paths: %#v", secretPaths)
+		}
+		return testLoaded(loaded)
+	}
+
+	left := load("LEFT-DYNAMIC-CANARY")
+	child := left.Config.Catalog.Entries["child"]
+	if child.Extends != "" || child.Label != "child" || child.Height != 9 || child.Derived != "child:LEFT-DYNAMIC-CANARY:9" || child.Token == nil || child.Token.Value() != "parent-secret-canary" {
+		t.Fatalf("resolved imported child = %#v", child)
+	}
+	if left.Config.Catalog.Entries["parent"].Label != "final" || left.Config.Catalog.Entries["parent"].Height != 4 || left.Config.Catalog.Entries["fallback"].Label != "default" {
+		t.Fatalf("final parent/default shape = %#v", left.Config.Catalog.Entries)
+	}
+
+	childTokenPath := Keys("catalog", "entries", "child", "token")
+	childToken, found := left.Inspection.Explain(childTokenPath)
+	childTokenInfo, tokenInfoFound := left.Inspection.Metadata().Lookup(childTokenPath)
+	if !found || !tokenInfoFound || !childToken.Effective.Redacted || strings.Contains(childToken.Effective.YAML, "parent-secret-canary") || len(childTokenInfo.Origin.Inheritance) != 1 {
+		t.Fatalf("inherited field explanation = %#v, %v", childToken, found)
+	}
+	var explanation bytes.Buffer
+	if err := left.Inspection.WriteExplanation(&explanation, childTokenPath); err != nil || strings.Contains(explanation.String(), "parent-secret-canary") || strings.Contains(explanation.String(), "LEFT-DYNAMIC-CANARY") {
+		t.Fatalf("safe explanation = %q, %v", explanation.String(), err)
+	}
+	labelHistory := left.Inspection.Metadata().History(Keys("catalog", "entries", "parent", "label"))
+	if len(labelHistory) < 2 {
+		t.Fatalf("parent label history omitted replaced contribution: %#v", labelHistory)
+	}
+	derived, found := left.Inspection.Explain(Keys("catalog", "entries", "child", "derived"))
+	if !found || !derived.Effective.Redacted || strings.Contains(derived.Effective.YAML, "LEFT-DYNAMIC-CANARY") || len(derived.History) == 0 || derived.History[len(derived.History)-1].Origin.Operation != ChangeNormalization {
+		t.Fatalf("recorded derived field explanation = %#v, %v", derived, found)
+	}
+
+	right := load("RIGHT-DYNAMIC-CANARY")
+	differences, err := Diff(left.Inspection, right.Inspection)
+	if err != nil {
+		t.Fatal(err)
+	}
+	seen := make(map[string]bool)
+	for _, difference := range differences {
+		path := difference.Path.String()
+		seen[path] = true
+		if !difference.Left.Redacted || !difference.Right.Redacted || !difference.HiddenChanged || strings.Contains(difference.Left.YAML+difference.Right.YAML, "DYNAMIC-CANARY") || strings.Contains(difference.Left.YAML+difference.Right.YAML, "parent-secret-canary") {
+			t.Errorf("sensitive difference at %s = %#v", path, difference)
+		}
+	}
+	for _, path := range []string{"/catalog/entries/child/dynamic", "/catalog/entries/child/derived"} {
+		if !seen[path] {
+			t.Errorf("missing inherited/derived difference at %s: %#v", path, differences)
+		}
+	}
+}
+
+func TestRelativeImportMatchesWrappedPlacementAndSafeDiff(t *testing.T) {
+	t.Parallel()
+
+	load := func(relativeImport bool, value string) *testResult[map[string]any] {
+		t.Helper()
+		input := Input{Source: NoSource()}
+		options := LayeredOptions[map[string]any]{}
+		if relativeImport {
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: fragment.yml
+      destination: [application]
+`)
+			writeImportFile(t, directory, "fragment.yml", "field: "+value+"\n")
+			options.Underlays = []Underlay{{Inputs: []Input{{Source: File(mainPath), Imports: true}}}}
+		} else {
+			options.Underlays = []Underlay{{Inputs: []Input{{Source: Bytes("wrapped", []byte("application: {field: "+value+"}\n"))}}}}
+		}
+		loaded, err := LoadLayered(input, testSecretBinding(), options)
+		if err != nil {
+			t.Fatalf("LoadLayered: %v", err)
+		}
+		return testLoaded(loaded)
+	}
+
+	relativeBefore := load(true, "before")
+	relativeAfter := load(true, "after")
+	wrappedBefore := load(false, "before")
+	wrappedAfter := load(false, "after")
+	for _, pair := range [][2]*testResult[map[string]any]{{relativeBefore, wrappedBefore}, {relativeAfter, wrappedAfter}} {
+		if !reflect.DeepEqual(pair[0].Config, pair[1].Config) {
+			t.Fatalf("relative and wrapped configurations differ: %#v vs %#v", pair[0].Config, pair[1].Config)
+		}
+		for _, result := range pair {
+			if info, ok := result.Metadata().Lookup(Keys("application", "field")); !ok || !info.Explicit {
+				t.Fatalf("effective field presence = %#v, %v", info, ok)
+			}
+		}
+	}
+	relativeDiff, err := Diff(relativeBefore.Inspection, relativeAfter.Inspection)
+	if err != nil {
+		t.Fatal(err)
+	}
+	wrappedDiff, err := Diff(wrappedBefore.Inspection, wrappedAfter.Inspection)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(relativeDiff, wrappedDiff) {
+		t.Fatalf("relative safe diff = %#v, wrapped safe diff = %#v", relativeDiff, wrappedDiff)
+	}
+}

internal/engine/destination_import_test.go

@@ -0,0 +1,574 @@
+package engine
+
+import (
+	"path/filepath"
+	"testing"
+	"testing/fstest"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type importDestinationConfig struct {
+	Mounted     map[string]string            `yaml:"mounted"`
+	Collections map[string]map[string]string `yaml:"collections"`
+}
+
+func TestLayeredHostImportsInheritInputDestinationTransitively(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: first.yml
+    - path: second.yml
+root: main
+`)
+	firstPath := writeImportFile(t, directory, "first.yml", `configkit:
+  imports:
+    - path: nested/third.yml
+first: one
+`)
+	thirdPath := writeImportFile(t, directory, "nested/third.yml", "nested: three\n")
+	secondPath := writeImportFile(t, directory, "second.yml", "second: two\n")
+
+	loaded, err := LoadLayered(
+		Input{Source: File(mainPath), Imports: true, Destination: Keys("mounted")},
+		testSecretBinding(),
+		LayeredOptions[importDestinationConfig]{},
+	)
+	if err != nil {
+		if loadError, ok := err.(*LoadError); ok {
+			t.Fatalf("LoadLayered diagnostics: %#v", loadError.Diagnostics())
+		}
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	want := map[string]string{"root": "main", "first": "one", "nested": "three", "second": "two"}
+	if len(result.Config.Mounted) != len(want) {
+		t.Fatalf("mounted values = %#v", result.Config.Mounted)
+	}
+	for key, value := range want {
+		if result.Config.Mounted[key] != value {
+			t.Errorf("mounted[%q] = %q, want %q", key, result.Config.Mounted[key], value)
+		}
+	}
+	if _, ok := result.Metadata().Lookup(Keys("mounted", "configkit")); ok {
+		t.Fatal("source-root import directive leaked into application content")
+	}
+	sources := result.Sources()
+	wantPaths := []string{canonicalTestPath(t, mainPath), canonicalTestPath(t, firstPath), canonicalTestPath(t, thirdPath), canonicalTestPath(t, secondPath)}
+	if len(sources) != len(wantPaths) {
+		t.Fatalf("sources = %#v", sources)
+	}
+	for index, source := range sources {
+		if source.Destination.String() != "/mounted" {
+			t.Errorf("source %d destination = %q", index, source.Destination.String())
+		}
+		if source.Path != wantPaths[index] {
+			t.Errorf("source %d path = %q, want %q", index, source.Path, wantPaths[index])
+		}
+		if index > 0 && source.ImportedFrom == nil {
+			t.Errorf("imported source %d has no physical import location", index)
+		}
+	}
+}
+
+func TestImportTraversalUsesPerDeclarationDestinations(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: parent.yml
+    - path: sibling.yml
+    - glob: fragments/*.yml
+`)
+	parentPath := writeImportFile(t, directory, "parent.yml", `configkit:
+  imports:
+    - path: nested/child.yml
+parent: true
+`)
+	childPath := writeImportFile(t, directory, "nested/child.yml", "child: true\n")
+	siblingPath := writeImportFile(t, directory, "sibling.yml", "sibling: true\n")
+	alphaPath := writeImportFile(t, directory, "fragments/a.yml", "alpha: true\n")
+	betaPath := writeImportFile(t, directory, "fragments/b.yml", "beta: true\n")
+
+	main := parseImportMain(t, mainPath)
+	_, declarations, diagnostics := splitImportDirectives(main.document)
+	if len(diagnostics) != 0 {
+		t.Fatalf("main directive diagnostics = %#v", diagnostics)
+	}
+	declarations[0].destination = Keys("parent")
+	declarations[1].destination = Keys("sibling")
+	declarations[2].destination = Keys("collection")
+
+	access, err := openHostAccess(directory)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = access.close() }()
+	state := importTraversal{
+		access: access, accounting: &importAccounting{}, limits: defaultImportLimits(),
+		active: make(map[resourceIdentity]int), visited: make(map[resourceIdentity]importRoute),
+	}
+	if diagnostics := state.walkDeclarations(directory, declarations, 0, Keys("entry")); len(diagnostics) != 0 {
+		t.Fatalf("walk diagnostics = %#v", diagnostics)
+	}
+
+	wantSources := []struct {
+		path        string
+		destination string
+	}{
+		{path: parentPath, destination: "/entry/parent"},
+		{path: childPath, destination: "/entry/parent"},
+		{path: siblingPath, destination: "/entry/sibling"},
+		{path: alphaPath, destination: "/entry/collection"},
+		{path: betaPath, destination: "/entry/collection"},
+	}
+	if len(state.sources) != len(wantSources) {
+		t.Fatalf("import sources = %#v, want %d", state.sources, len(wantSources))
+	}
+	for index, want := range wantSources {
+		got := state.sources[index]
+		if got.Path != canonicalTestPath(t, want.path) || got.Destination.String() != want.destination {
+			t.Errorf("source %d = (%q, %q), want (%q, %q)", index, got.Path, got.Destination.String(), canonicalTestPath(t, want.path), want.destination)
+		}
+	}
+
+	documents := make([]*document.Node, 0, len(state.scope.contributions))
+	for _, contribution := range state.scope.contributions {
+		documents = append(documents, contribution.document)
+	}
+	composed, diagnostics := composeDocuments(documents...)
+	if len(diagnostics) != 0 {
+		t.Fatalf("composition diagnostics = %#v", diagnostics)
+	}
+	for _, path := range []Path{
+		Keys("entry", "parent", "parent"), Keys("entry", "parent", "child"),
+		Keys("entry", "sibling", "sibling"), Keys("entry", "collection", "alpha"),
+		Keys("entry", "collection", "beta"),
+	} {
+		if _, present := documentAtPath(composed.root, path); !present {
+			t.Errorf("no composed value at %q", path.String())
+		}
+	}
+}
+
+func TestEntryDestinationSurvivesImportSetupAndParseFailures(t *testing.T) {
+	t.Parallel()
+
+	t.Run("import context failure", func(t *testing.T) {
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: child.yml}]}\n")
+		input, diagnostics := assembleBaseInputTracked(
+			File(mainPath),
+			Options[map[string]any]{Imports: true, Filesystem: &FilesystemContext{Root: t.TempDir()}},
+			Keys("mounted"), &importAccounting{}, nil, nil,
+		)
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeImportOutsideRoot {
+			t.Fatalf("context diagnostics = %#v", diagnostics)
+		}
+		if len(input.sources) != 1 || input.sources[0].Destination.String() != "/mounted" {
+			t.Fatalf("entry source fallback = %#v", input.sources)
+		}
+	})
+
+	t.Run("imported parse failure", func(t *testing.T) {
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: broken.yml}]}\n")
+		writeImportFile(t, directory, "broken.yml", "broken: [\n")
+		input, diagnostics := assembleBaseInputTracked(
+			File(mainPath), Options[map[string]any]{Imports: true},
+			Keys("mounted"), &importAccounting{}, nil, nil,
+		)
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeYAMLInvalid {
+			t.Fatalf("parse diagnostics = %#v", diagnostics)
+		}
+		if len(input.sources) != 2 {
+			t.Fatalf("parse-failure sources = %#v", input.sources)
+		}
+		for index, source := range input.sources {
+			if source.Destination.String() != "/mounted" {
+				t.Errorf("source %d destination = %q, want /mounted", index, source.Destination.String())
+			}
+		}
+	})
+}
+
+func TestRelativeImportDestinationsKeepStrictCompositionBoundaries(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name     string
+		main     string
+		files    map[string]string
+		want     map[string]any
+		conflict bool
+		wantPath string
+	}{
+		{
+			name:  "disjoint peers at one destination",
+			main:  "configkit:\n  imports:\n    - path: left.yml\n      destination: [application]\n    - path: right.yml\n      destination: [application]\n",
+			files: map[string]string{"left.yml": "left: one\n", "right.yml": "right: two\n"},
+			want:  map[string]any{"/application/left": "one", "/application/right": "two"},
+		},
+		{
+			name:  "different destinations",
+			main:  "configkit:\n  imports:\n    - path: left.yml\n      destination: [left]\n    - path: right.yml\n      destination: [right]\n",
+			files: map[string]string{"left.yml": "value: shared\n", "right.yml": "value: shared\n"},
+			want:  map[string]any{"/left/value": "shared", "/right/value": "shared"},
+		},
+		{
+			name:  "ancestor and descendant overlap",
+			main:  "configkit:\n  imports:\n    - path: parent.yml\n      destination: [application]\n    - path: child.yml\n      destination: [application, branch]\n",
+			files: map[string]string{"parent.yml": "branch: {base: one}\n", "child.yml": "leaf: two\n"},
+			want:  map[string]any{"/application/branch/base": "one", "/application/branch/leaf": "two"},
+		},
+		{
+			name:     "collision with explicitly wrapped content",
+			main:     "configkit: {imports: [{path: fragment.yml, destination: [application]}]}\napplication: {value: root}\n",
+			files:    map[string]string{"fragment.yml": "value: imported\n"},
+			conflict: true,
+			wantPath: "/application/value",
+		},
+		{
+			name:     "equal peer values conflict",
+			main:     "configkit:\n  imports:\n    - path: left.yml\n      destination: [application]\n    - path: right.yml\n      destination: [application]\n",
+			files:    map[string]string{"left.yml": "value: same\n", "right.yml": "value: same\n"},
+			conflict: true,
+			wantPath: "/application/value",
+		},
+		{
+			name:     "unequal peer values conflict",
+			main:     "configkit:\n  imports:\n    - path: left.yml\n      destination: [application]\n    - path: right.yml\n      destination: [application]\n",
+			files:    map[string]string{"left.yml": "value: left\n", "right.yml": "value: right\n"},
+			conflict: true,
+			wantPath: "/application/value",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", test.main)
+			for name, body := range test.files {
+				writeImportFile(t, directory, name, body)
+			}
+			loaded, err := LoadLayered(
+				Input{Source: File(mainPath), Imports: true}, testSecretBinding(),
+				LayeredOptions[map[string]any]{},
+			)
+			if test.conflict {
+				if loaded != nil || groupedErrorCode(t, err) != CodeComposeConflict {
+					t.Fatalf("relative import composition = %#v, %v", loaded, err)
+				}
+				loadError := err.(*LoadError)
+				if diagnostics := loadError.Diagnostics(); diagnostics[0].Path.String() != test.wantPath {
+					t.Fatalf("conflict path = %q, want %q", diagnostics[0].Path.String(), test.wantPath)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("relative import composition: %v", err)
+			}
+			configuration := testLoaded(loaded).Config
+			for path, want := range test.want {
+				parsed, err := ParsePath(path)
+				if err != nil {
+					t.Fatal(err)
+				}
+				keys := make([]string, len(parsed.segments))
+				for index, segment := range parsed.segments {
+					keys[index] = segment.key
+				}
+				if got := layeredMapValue(t, configuration, keys...); got != want {
+					t.Errorf("value at %s = %#v, want %#v", path, got, want)
+				}
+			}
+		})
+	}
+
+	t.Run("upper tier cannot repair a lower import conflict", func(t *testing.T) {
+		directory := t.TempDir()
+		lowerPath := writeImportFile(t, directory, "lower.yml", `configkit:
+  imports:
+    - path: left.yml
+      destination: [application]
+    - path: right.yml
+      destination: [application]
+`)
+		writeImportFile(t, directory, "left.yml", "value: left\n")
+		writeImportFile(t, directory, "right.yml", "value: right\n")
+		loaded, err := LoadLayered(
+			Input{Source: Bytes("upper", []byte("application: {value: upper}\n"))},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{Underlays: []Underlay{{Inputs: []Input{{Source: File(lowerPath), Imports: true}}}}},
+		)
+		if loaded != nil || groupedErrorCode(t, err) != CodeComposeConflict {
+			t.Fatalf("upper tier repaired a lower conflict: %#v, %v", loaded, err)
+		}
+	})
+}
+
+func TestRelativeImportDestinationsUseEffectiveVersionOwnership(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name     string
+		rulePath Path
+		fragment string
+	}{
+		{name: "direct claim", rulePath: Keys("collection", "group", "nested", "version"), fragment: "version: v2\n"},
+		{name: "ancestor claim", rulePath: Keys("collection", "group", "nested", "schema", "version"), fragment: "schema: null\n"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: parent.yml
+      destination: [group]
+`)
+			writeImportFile(t, directory, "parent.yml", `configkit:
+  imports:
+    - path: fragment.yml
+      destination: [nested]
+`)
+			writeImportFile(t, directory, "fragment.yml", test.fragment)
+			_, err := LoadLayered(
+				Input{Source: File(mainPath), Imports: true, Destination: Keys("collection")},
+				testSecretBinding(),
+				LayeredOptions[map[string]any]{Definition: Definition[map[string]any]{Version: &VersionRule{
+					Path: test.rulePath, Check: func(Version, *Validation) error { return nil },
+				}}},
+			)
+			if groupedErrorCode(t, err) != CodeImportVersion {
+				t.Fatalf("effective imported claim error = %v", err)
+			}
+			loadError := err.(*LoadError)
+			diagnostic := loadError.Diagnostics()[0]
+			if diagnostic.Path.String() != test.rulePath.String() || diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-3" {
+				t.Fatalf("effective version diagnostic = %#v", diagnostic)
+			}
+			sources := loadError.Sources()
+			wantDestinations := []string{"/collection", "/collection/group", "/collection/group/nested"}
+			if len(sources) != len(wantDestinations) {
+				t.Fatalf("version failure sources = %#v", sources)
+			}
+			for index, source := range sources {
+				if source.Destination.String() != wantDestinations[index] {
+					t.Errorf("source %d destination = %q, want %q", index, source.Destination.String(), wantDestinations[index])
+				}
+			}
+		})
+	}
+}
+
+func TestRelativeImportDestinationsKeepMainVersionCheckScoped(t *testing.T) {
+	t.Parallel()
+
+	type config struct {
+		Collection struct {
+			SchemaVersion string         `yaml:"schema_version"`
+			Group         map[string]any `yaml:"group"`
+		} `yaml:"collection"`
+	}
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: parent.yml
+      destination: [group]
+schema_version: 6
+`)
+	writeImportFile(t, directory, "parent.yml", `configkit:
+  imports:
+    - path: fragment.yml
+      destination: [nested]
+`)
+	writeImportFile(t, directory, "fragment.yml", "version: 7\n")
+	checks := 0
+	loaded, err := LoadLayered(
+		Input{Source: File(mainPath), Imports: true, Destination: Keys("collection")},
+		testSecretBinding(),
+		LayeredOptions[config]{Definition: Definition[config]{Version: &VersionRule{
+			Path: Keys("collection", "schema_version"),
+			Check: func(version Version, _ *Validation) error {
+				checks++
+				if !version.Present || version.Text != "6" {
+					t.Errorf("main-owned version = %#v", version)
+				}
+				return nil
+			},
+		}}},
+	)
+	if err != nil {
+		t.Fatalf("ordinary nested imported version was rejected: %v", err)
+	}
+	result := testLoaded(loaded)
+	if checks != 1 || result.Config.Collection.SchemaVersion != "6" {
+		t.Fatalf("main version callback/value = %d/%q", checks, result.Config.Collection.SchemaVersion)
+	}
+	nested, ok := result.Config.Collection.Group["nested"].(map[string]any)
+	if !ok {
+		t.Fatalf("nested imported payload = %#v", result.Config.Collection.Group["nested"])
+	}
+	if got, ok := nested["version"].(int64); !ok || got != 7 {
+		t.Fatalf("ordinary nested version = %#v, want integer payload 7", nested["version"])
+	}
+}
+
+func TestLayeredNativeFilesystemImportsInheritInputDestination(t *testing.T) {
+	t.Parallel()
+
+	native := fstest.MapFS{
+		"main.yml":   &fstest.MapFile{Data: []byte("configkit:\n  imports:\n    - path: first.yml\nroot: main\n")},
+		"first.yml":  &fstest.MapFile{Data: []byte("configkit: {imports: [{path: nested.yml}]}\nfirst: imported\n")},
+		"nested.yml": &fstest.MapFile{Data: []byte("nested: imported\n")},
+	}
+	namespace := newNativeNamespace("bundle", native)
+	loaded, err := LoadLayered(
+		Input{Source: filesystemFile(namespace, "main.yml"), Imports: true, Destination: Keys("mounted")},
+		testSecretBinding(),
+		LayeredOptions[importDestinationConfig]{},
+	)
+	if err != nil {
+		if loadError, ok := err.(*LoadError); ok {
+			t.Fatalf("LoadLayered diagnostics: %#v", loadError.Diagnostics())
+		}
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	if result.Config.Mounted["root"] != "main" || result.Config.Mounted["first"] != "imported" || result.Config.Mounted["nested"] != "imported" {
+		t.Fatalf("mounted native filesystem values = %#v", result.Config.Mounted)
+	}
+	sources := result.Sources()
+	if len(sources) != 3 || sources[0].Destination.String() != "/mounted" || sources[1].Destination.String() != "/mounted" || sources[2].Destination.String() != "/mounted" {
+		t.Fatalf("native source destinations = %#v", sources)
+	}
+}
+
+func TestLayeredImportOnlyInputMaterializesDestination(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: optional.yml
+      optional: true
+`)
+	loaded, err := LoadLayered(
+		Input{Source: File(mainPath), Imports: true, Destination: Keys("collections", "empty")},
+		testSecretBinding(),
+		LayeredOptions[importDestinationConfig]{},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	info, ok := result.Metadata().Lookup(Keys("collections", "empty"))
+	if !ok || !info.Explicit {
+		t.Fatalf("import-only body destination = %#v, %v", info, ok)
+	}
+	sources := result.Sources()
+	if len(sources) != 1 || sources[0].Destination.String() != "/collections/empty" {
+		t.Fatalf("sources = %#v", sources)
+	}
+}
+
+func TestLayeredImportedVersionClaimsUseEffectiveDestination(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name        string
+		rulePath    Path
+		destination Path
+		wantCode    Code
+	}{
+		{name: "protected effective path", rulePath: Keys("mounted", "version"), destination: Keys("mounted"), wantCode: CodeImportVersion},
+		{name: "ordinary nested domain version", rulePath: Keys("version"), destination: Keys("collections", "entry")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			directory := t.TempDir()
+			writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: fragment.yml}]}\n")
+			writeImportFile(t, directory, "fragment.yml", "version: v2\n")
+			rule := &VersionRule{Path: test.rulePath, Check: func(Version, *Validation) error { return nil }}
+			loaded, err := LoadLayered(
+				Input{Source: NoSource()},
+				testSecretBinding(),
+				LayeredOptions[importDestinationConfig]{
+					Definition: Definition[importDestinationConfig]{Version: rule},
+					Underlays: []Underlay{{Inputs: []Input{{
+						Source: File(filepath.Join(directory, "main.yml")), Imports: true, Destination: test.destination,
+					}}}},
+				},
+			)
+			if test.wantCode != "" {
+				if err == nil {
+					t.Fatal("protected imported version claim was accepted")
+				}
+				loadError, ok := err.(*LoadError)
+				if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != test.wantCode {
+					t.Fatalf("load error = %#v", err)
+				}
+				if test.name == "protected effective path" {
+					sources := loadError.Sources()
+					if len(sources) != 2 || sources[0].Destination.String() != "/mounted" || sources[1].Destination.String() != "/mounted" {
+						t.Fatalf("error source destinations = %#v", sources)
+					}
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("ordinary nested version was rejected: %v", err)
+			}
+			result := testLoaded(loaded)
+			if got := result.Config.Collections["entry"]["version"]; got != "v2" {
+				t.Fatalf("nested version = %q", got)
+			}
+		})
+	}
+}
+
+func TestLayeredDestinationsDoNotChangeRepeatedSourceIdentity(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	writeImportFile(t, directory, "shared.yml", "value: shared\n")
+	importerPath := writeImportFile(t, directory, "importer.yml", "configkit: {imports: [{path: shared.yml, destination: [nested]}]}\n")
+	_, err := LoadLayered(
+		Input{Source: NoSource()},
+		testSecretBinding(),
+		LayeredOptions[importDestinationConfig]{Underlays: []Underlay{{Inputs: []Input{
+			{Source: File(importerPath), Imports: true, Destination: Keys("imported")},
+			{Source: File(filepath.Join(directory, "shared.yml")), Destination: Keys("direct")},
+		}}}},
+	)
+	if err == nil {
+		t.Fatal("the same physical source was accepted at two destinations in one group")
+	}
+	loadError, ok := err.(*LoadError)
+	if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != CodeImportRepeated {
+		t.Fatalf("load error = %#v", err)
+	}
+	sources := loadError.Sources()
+	if len(sources) != 3 || sources[1].Destination.String() != "/imported/nested" || sources[2].Destination.String() != "/direct" {
+		t.Fatalf("repeated import sources = %#v", sources)
+	}
+
+	t.Run("placement does not break a physical cycle", func(t *testing.T) {
+		t.Parallel()
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: parent.yml, destination: [one]}]}\n")
+		writeImportFile(t, directory, "parent.yml", "configkit: {imports: [{path: main.yml, destination: [two]}]}\n")
+		_, err := LoadLayered(Input{Source: File(mainPath), Imports: true}, testSecretBinding(), LayeredOptions[map[string]any]{})
+		loadError, ok := err.(*LoadError)
+		if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != CodeImportCycle {
+			t.Fatalf("cycle load error = %#v", err)
+		}
+		diagnostic := loadError.Diagnostics()[0]
+		if diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-2" {
+			t.Fatalf("cycle primary location = %#v", diagnostic.Primary)
+		}
+		if sources := loadError.Sources(); len(sources) != 2 || sources[1].Destination.String() != "/one" {
+			t.Fatalf("cycle sources = %#v", sources)
+		}
+	})
+}

internal/engine/destination_integration_test.go

@@ -0,0 +1,500 @@
+package engine
+
+import (
+	"bytes"
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+	"testing/fstest"
+)
+
+func TestLayeredDestinationInheritanceUsesFinalSiblingScopes(t *testing.T) {
+	t.Parallel()
+
+	loaded, err := LoadLayered(
+		Input{Source: Bytes("main", []byte("parent:\n  label: final\n  settings:\n    primary: {height: 4}\ncancelled:\n  extends: null\n  own: retained\n")), Destination: Keys("catalog", "entries")},
+		testSecretBinding(),
+		LayeredOptions[map[string]any]{Underlays: []Underlay{{Inputs: []Input{
+			{Source: Bytes("parent", []byte("parent:\n  label: lower\n  settings:\n    primary: {width: '10'}\n    secondary: {extends: primary}\ncancelled:\n  extends: parent\n  own: retained\n")), Destination: Keys("catalog", "entries")},
+			{Source: Bytes("child", []byte("child:\n  extends: parent\n  settings:\n    primary: {width: '20'}\n    secondary: {extends: primary}\n")), Destination: Keys("catalog", "entries")},
+		}}}},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	entries := layeredMap(t, layeredMap(t, result.Config, "catalog"), "entries")
+	parent := layeredMap(t, entries, "parent")
+	child := layeredMap(t, entries, "child")
+	parentSettings := layeredMap(t, parent, "settings")
+	childSettings := layeredMap(t, child, "settings")
+	if parent["label"] != "final" || child["label"] != "final" {
+		t.Fatalf("higher-tier parent was not inherited after precedence: parent=%#v child=%#v", parent, child)
+	}
+	if layeredMapValue(t, parentSettings, "secondary", "width") != "10" ||
+		fmt.Sprint(layeredMapValue(t, parentSettings, "secondary", "height")) != "4" ||
+		layeredMapValue(t, childSettings, "secondary", "width") != "20" ||
+		fmt.Sprint(layeredMapValue(t, childSettings, "secondary", "height")) != "4" {
+		t.Fatalf("nested sibling scopes were not resolved at their destinations: parent=%#v child=%#v", parentSettings, childSettings)
+	}
+	cancelled := layeredMap(t, entries, "cancelled")
+	if len(cancelled) != 1 || cancelled["own"] != "retained" {
+		t.Fatalf("higher-tier cancellation did not suppress inheritance: %#v", cancelled)
+	}
+	if _, ok := result.Metadata().Lookup(Keys("catalog", "entries", "child", inheritanceKey)); ok {
+		t.Fatal("effective child retained its extends directive")
+	}
+}
+
+func TestLayeredDestinationInheritanceDoesNotSearchOtherCollections(t *testing.T) {
+	t.Parallel()
+
+	_, err := LoadLayered(
+		Input{Source: Bytes("main", []byte("parent: {value: foreign}\n")), Destination: Keys("catalog", "other")},
+		testSecretBinding(),
+		LayeredOptions[map[string]any]{Underlays: []Underlay{{Inputs: []Input{{
+			Source:      Bytes("child", []byte("child: {extends: parent}\n")),
+			Destination: Keys("catalog", "entries"),
+		}}}}},
+	)
+	if got := groupedErrorCode(t, err); got != CodeInheritanceMissing {
+		t.Fatalf("cross-collection parent lookup error = %s, want %s", got, CodeInheritanceMissing)
+	}
+}
+
+func TestLayeredMountedVersionProtectionCoversInheritanceAndUpperTiers(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name     string
+		body     string
+		rulePath Path
+	}{
+		{name: "inherited protected value", body: "parent: {version: v2}\nchild: {extends: parent}\n", rulePath: Keys("catalog", "entries", "child", "version")},
+		{name: "inherited protected ancestor", body: "parent: {schema: null}\nchild: {extends: parent}\n", rulePath: Keys("catalog", "entries", "child", "schema", "version")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			_, err := LoadLayered(
+				Input{Source: NoSource()}, testSecretBinding(),
+				LayeredOptions[map[string]any]{
+					Definition: Definition[map[string]any]{Version: &VersionRule{Path: test.rulePath, Check: func(Version, *Validation) error { return nil }}},
+					Underlays:  []Underlay{{Inputs: []Input{{Source: Bytes("underlay", []byte(test.body)), Destination: Keys("catalog", "entries")}}}},
+				},
+			)
+			if got := groupedErrorCode(t, err); got != CodeInheritanceVersion {
+				t.Fatalf("inheritance version protection code = %s", got)
+			}
+		})
+	}
+	t.Run("inheritance consumes a protected directive", func(t *testing.T) {
+		_, err := LoadLayered(
+			Input{Source: Bytes("main", []byte("parent: {value: inherited}\nchild: {extends: parent}\n")), Destination: Keys("catalog", "entries")},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{Definition: Definition[map[string]any]{Version: &VersionRule{
+				Path: Keys("catalog", "entries", "child", "extends"),
+				Check: func(version Version, _ *Validation) error {
+					if !version.Present || version.Text != "parent" {
+						t.Errorf("mounted protected directive value = %#v", version)
+					}
+					return nil
+				},
+			}}},
+		)
+		if got := groupedErrorCode(t, err); got != CodeInheritanceVersion {
+			t.Fatalf("consumed directive protection code = %s", got)
+		}
+	})
+	t.Run("inherited mapping ancestor without a version claim", func(t *testing.T) {
+		loaded, err := LoadLayered(
+			Input{Source: NoSource()}, testSecretBinding(),
+			LayeredOptions[map[string]any]{
+				Definition: Definition[map[string]any]{Version: &VersionRule{Path: Keys("catalog", "entries", "child", "schema", "version"), Check: func(Version, *Validation) error { return nil }}},
+				Underlays: []Underlay{{Inputs: []Input{{
+					Source: Bytes("underlay", []byte("parent: {schema: {name: ordinary}}\nchild: {extends: parent}\n")), Destination: Keys("catalog", "entries"),
+				}}}},
+			},
+		)
+		if err != nil {
+			t.Fatalf("nonclaiming inherited mapping ancestor was rejected: %v", err)
+		}
+		if got := layeredMapValue(t, testLoaded(loaded).Config, "catalog", "entries", "child", "schema", "name"); got != "ordinary" {
+			t.Fatalf("inherited non-version value = %#v", got)
+		}
+	})
+
+	for _, test := range []struct {
+		name string
+		body string
+	}{
+		{name: "overlay protected value", body: "catalog: {schema: {version: v2}}\n"},
+		{name: "overlay protected ancestor", body: "catalog: {schema: null}\n"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			filesystem := NewFilesystem("overlay", fstest.MapFS{"overlays/test.yml": &fstest.MapFile{Data: []byte(test.body)}})
+			_, err := LoadLayered(
+				Input{Source: Bytes("main", []byte("schema: {version: v1}\n")), Destination: Keys("catalog")},
+				testSecretBinding(),
+				LayeredOptions[map[string]any]{
+					Definition: Definition[map[string]any]{Version: &VersionRule{Path: Keys("catalog", "schema", "version"), Check: func(version Version, _ *Validation) error {
+						if !version.Present || version.Text != "v1" {
+							t.Errorf("mounted main version = %#v", version)
+						}
+						return nil
+					}}},
+					Overlay: "test", OverlayFilesystem: &FilesystemContext{Root: ".", BaseDir: ".", FS: &filesystem},
+				},
+			)
+			if got := groupedErrorCode(t, err); got != CodeOverlayVersion {
+				t.Fatalf("overlay version protection code = %s", got)
+			}
+		})
+	}
+
+	for _, test := range []struct {
+		name  string
+		path  Path
+		value any
+	}{
+		{name: "override protected value", path: Keys("catalog", "schema", "version"), value: "v2"},
+		{name: "override protected ancestor", path: Keys("catalog", "schema"), value: map[string]any{"version": "v2"}},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			_, err := LoadLayered(
+				Input{Source: Bytes("main", []byte("schema: {version: v1}\n")), Destination: Keys("catalog")},
+				testSecretBinding(),
+				LayeredOptions[map[string]any]{
+					Definition: Definition[map[string]any]{Version: &VersionRule{Path: Keys("catalog", "schema", "version"), Check: func(Version, *Validation) error { return nil }}},
+					Overrides:  []Override{{Path: test.path, Value: test.value, Flag: "--config"}},
+				},
+			)
+			if got := groupedErrorCode(t, err); got != CodeOverrideVersion {
+				t.Fatalf("override version protection code = %s", got)
+			}
+		})
+	}
+
+	t.Run("unrelated inheritance under the protected mapping ancestor", func(t *testing.T) {
+		loaded, err := LoadLayered(
+			Input{Source: Bytes("main", []byte("schema: {version: v1}\nentries:\n  parent: {value: inherited}\n  child: {extends: parent}\n")), Destination: Keys("catalog")},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{Definition: Definition[map[string]any]{Version: &VersionRule{Path: Keys("catalog", "schema", "version"), Check: func(Version, *Validation) error { return nil }}}},
+		)
+		if err != nil {
+			t.Fatalf("unrelated mounted inheritance was rejected: %v", err)
+		}
+		child := layeredMapValue(t, testLoaded(loaded).Config, "catalog", "entries", "child", "value")
+		if child != "inherited" {
+			t.Fatalf("unrelated inheritance value = %#v", child)
+		}
+	})
+}
+
+func TestLayeredItemVersionProtectionTracksAssignedPeerIndexes(t *testing.T) {
+	t.Parallel()
+
+	definition := Definition[map[string]any]{
+		Version:               &VersionRule{Path: Keys("schema", "version"), Check: func(Version, *Validation) error { return nil }},
+		sequenceRegistrations: []sequenceRegistration{{path: Keys("catalog", "entries"), identityField: "id"}},
+	}
+	item := func(label string, value map[string]any) Input {
+		return Input{Source: Mapping(label, value), Destination: Keys("catalog", "entries"), placementMode: placementModeSequenceItem}
+	}
+	options := func(inputs ...Input) LayeredOptions[map[string]any] {
+		return LayeredOptions[map[string]any]{Definition: definition, SourceVersionMode: sourceVersionModeIfPresent, Underlays: []Underlay{{Inputs: inputs}}}
+	}
+	main := item("main", map[string]any{"id": "main", "schema": map[string]any{"version": "v1"}})
+
+	t.Run("same assigned main path is protected", func(t *testing.T) {
+		_, err := LoadLayered(main, testSecretBinding(), options(item("underlay", map[string]any{"id": "underlay", "schema": nil})))
+		if got := groupedErrorCode(t, err); got != CodeUnderlayVersion {
+			t.Fatalf("protected item claim code = %s, want %s", got, CodeUnderlayVersion)
+		}
+	})
+
+	t.Run("appended peer does not claim main path", func(t *testing.T) {
+		loaded, err := LoadLayered(main, testSecretBinding(), options(
+			item("first", map[string]any{"id": "first", "schema": map[string]any{"other": "value"}}),
+			item("peer", map[string]any{"id": "peer", "schema": nil}),
+		))
+		if err != nil {
+			t.Fatalf("unrelated appended peer rejected: %v", err)
+		}
+		entries := layeredMapValue(t, testLoaded(loaded).Config, "catalog", "entries").([]any)
+		if len(entries) != 1 || entries[0].(map[string]any)["id"] != "main" {
+			t.Fatalf("main item projection = %#v", entries)
+		}
+	})
+}
+
+type destinationDecodeProbe string
+
+var destinationDecodeProbeValues []string
+
+func (value *destinationDecodeProbe) UnmarshalText(text []byte) error {
+	destinationDecodeProbeValues = append(destinationDecodeProbeValues, string(text))
+	*value = destinationDecodeProbe(text)
+	return nil
+}
+
+func (value destinationDecodeProbe) MarshalText() ([]byte, error) {
+	return []byte(value), nil
+}
+
+type destinationLifecycleConfig struct {
+	Defaulted string `yaml:"defaulted"`
+	Tenant    struct {
+		Tagged     string                 `yaml:"tagged" configkit:"secret"`
+		Dynamic    string                 `yaml:"dynamic"`
+		Credential Secret                 `yaml:"credential"`
+		Derived    string                 `yaml:"derived"`
+		Decoded    destinationDecodeProbe `yaml:"decoded"`
+	} `yaml:"tenant"`
+}
+
+func TestLayeredDestinationLifecycleAndSensitiveInspectionUseFinalShape(t *testing.T) {
+	const (
+		oldTagged   = "SUPERSEDED-TAGGED-CANARY"
+		newTagged   = "CURRENT-TAGGED-CANARY"
+		oldDynamic  = "SUPERSEDED-DYNAMIC-CANARY"
+		newDynamic  = "CURRENT-DYNAMIC-CANARY"
+		credential  = "RESOLVED-CREDENTIAL-CANARY"
+		secretName  = "DESTINATION_SECRET_NAME"
+		decodeValue = "decoded-once"
+	)
+	type calls struct{ defaults, resolve, lookup, validate int }
+	newLoad := func(mounted bool, observed *calls) (*testResult[destinationLifecycleConfig], error) {
+		mainBody := "tagged: " + newTagged + "\ndynamic: " + newDynamic + "\ncredential: " + secretName + "\ndecoded: " + decodeValue + "\n"
+		underlayBody := "tagged: " + oldTagged + "\ndynamic: " + oldDynamic + "\ncredential: OLD_DESTINATION_SECRET_NAME\ndecoded: old\n"
+		if !mounted {
+			mainBody = "tenant:\n" + indentDestinationBody(mainBody)
+			underlayBody = "tenant:\n" + indentDestinationBody(underlayBody)
+		}
+		main := loadInput{source: Bytes("main", []byte(mainBody))}
+		underlay := loadInput{source: Bytes("underlay", []byte(underlayBody))}
+		if mounted {
+			main.destination = Keys("tenant")
+			underlay.destination = Keys("tenant")
+		}
+		definition := Definition[destinationLifecycleConfig]{
+			Defaults: func() destinationLifecycleConfig {
+				observed.defaults++
+				return destinationLifecycleConfig{Defaulted: "from-default"}
+			},
+			Resolve: func(configuration *destinationLifecycleConfig, resolution *Resolution) error {
+				observed.resolve++
+				configuration.Tenant.Derived = configuration.Tenant.Dynamic
+				resolution.Record(Keys("tenant", "derived"), ChangeNormalization, "derive from mounted input", Keys("tenant", "dynamic"))
+				return nil
+			},
+			Validate: func(configuration *destinationLifecycleConfig, _ *Validation) {
+				observed.validate++
+				if configuration.Tenant.Decoded != destinationDecodeProbe(decodeValue) || configuration.Tenant.Dynamic != newDynamic {
+					t.Errorf("validation saw a non-final mounted configuration: %#v", configuration.Tenant)
+				}
+			},
+			Secret: func(path Path) bool { return path.String() == "/tenant/dynamic" },
+		}
+		loaded, err := loadGroupedWithSecretLookup(loadRequest[destinationLifecycleConfig]{
+			main: main, underlays: []loadGroup{{inputs: []loadInput{underlay}}}, definition: definition,
+		}, testSecretBinding(), func(name string) (string, bool) {
+			observed.lookup++
+			if name != secretName {
+				return "", false
+			}
+			return credential, true
+		})
+		return testLoaded(loaded), err
+	}
+
+	var observed calls
+	destinationDecodeProbeValues = nil
+	mounted, err := newLoad(true, &observed)
+	if err != nil {
+		if loadError, ok := err.(*LoadError); ok {
+			t.Fatalf("mounted load: %#v", loadError.Diagnostics())
+		}
+		t.Fatalf("mounted load: %v", err)
+	}
+	if observed != (calls{defaults: 1, resolve: 1, lookup: 1, validate: 1}) {
+		t.Fatalf("mounted lifecycle counts = %#v", observed)
+	}
+	sawFinalDecode := false
+	for _, value := range destinationDecodeProbeValues {
+		if value == decodeValue {
+			sawFinalDecode = true
+		} else if value != "" {
+			t.Fatalf("decoder observed a non-final mounted value %q: %#v", value, destinationDecodeProbeValues)
+		}
+	}
+	if !sawFinalDecode {
+		t.Fatal("final mounted value was not decoded")
+	}
+	if mounted.Config.Defaulted != "from-default" || mounted.Config.Tenant.Tagged != newTagged || mounted.Config.Tenant.Dynamic != newDynamic ||
+		mounted.Config.Tenant.Derived != newDynamic || mounted.Config.Tenant.Decoded != destinationDecodeProbe(decodeValue) ||
+		mounted.Config.Tenant.Credential.Value() != credential {
+		t.Fatalf("mounted final configuration = %#v", mounted.Config)
+	}
+	for _, path := range []Path{Keys("tenant", "tagged"), Keys("tenant", "dynamic"), Keys("tenant", "derived")} {
+		if !mounted.Inspection.secrets[path.String()] {
+			t.Errorf("effective sensitivity missing at %s: %#v", path, mounted.Inspection.secrets)
+		}
+	}
+	for _, path := range []Path{Keys("tenant", "tagged"), Keys("tenant", "dynamic"), Keys("tenant", "derived")} {
+		explanation, ok := mounted.Explain(path)
+		if !ok || !explanation.Effective.Redacted {
+			t.Errorf("effective explanation at %s = %#v, %v", path, explanation, ok)
+			continue
+		}
+		for _, change := range explanation.History {
+			if strings.Contains(change.Before.YAML+change.After.YAML, oldTagged) ||
+				strings.Contains(change.Before.YAML+change.After.YAML, newTagged) ||
+				strings.Contains(change.Before.YAML+change.After.YAML, oldDynamic) ||
+				strings.Contains(change.Before.YAML+change.After.YAML, newDynamic) {
+				t.Errorf("classified history leaked a canary at %s: %#v", path, change)
+			}
+		}
+		var rendered bytes.Buffer
+		if err := mounted.WriteExplanation(&rendered, path); err != nil || strings.Contains(rendered.String(), "CANARY") {
+			t.Errorf("safe explanation at %s = %q, %v", path, rendered.String(), err)
+		}
+	}
+	var effective bytes.Buffer
+	if err := mounted.WriteEffective(&effective); err != nil {
+		t.Fatal(err)
+	}
+	for _, canary := range []string{oldTagged, newTagged, oldDynamic, newDynamic, credential} {
+		if strings.Contains(effective.String(), canary) {
+			t.Fatalf("effective rendering exposed %q: %s", canary, effective.String())
+		}
+	}
+	if serializedConfig := fmt.Sprintf("%#v", mounted.Config); strings.Contains(serializedConfig, credential) {
+		t.Fatalf("configuration formatting exposed the resolved credential: %s", serializedConfig)
+	}
+	for _, path := range []Path{Keys("tenant", "tagged"), Keys("tenant", "dynamic")} {
+		if history := fmt.Sprintf("%#v", mounted.Metadata().History(path)); strings.Contains(history, "CANARY") {
+			t.Fatalf("metadata history at %s exposed a canary: %s", path, history)
+		}
+	}
+
+	var authoredCalls calls
+	destinationDecodeProbeValues = nil
+	authored, err := newLoad(false, &authoredCalls)
+	if err != nil {
+		t.Fatalf("explicitly wrapped load: %v", err)
+	}
+	if authoredCalls != (calls{defaults: 1, resolve: 1, lookup: 1, validate: 1}) {
+		t.Fatalf("authored lifecycle counts = %#v", authoredCalls)
+	}
+	sawFinalDecode = false
+	for _, value := range destinationDecodeProbeValues {
+		if value == decodeValue {
+			sawFinalDecode = true
+		} else if value != "" {
+			t.Fatalf("authored decoder observed a non-final value %q: %#v", value, destinationDecodeProbeValues)
+		}
+	}
+	if !sawFinalDecode {
+		t.Fatal("final authored value was not decoded")
+	}
+	if !reflect.DeepEqual(mounted.Config, authored.Config) {
+		t.Fatalf("mounted config %#v differs from explicitly wrapped config %#v", mounted.Config, authored.Config)
+	}
+	differences, err := Diff(mounted.Inspection, authored.Inspection)
+	if err != nil || len(differences) != 0 {
+		t.Fatalf("mounted versus authored diff = %#v, %v", differences, err)
+	}
+}
+
+func TestLayeredDestinationDiffUsesBilateralSensitivity(t *testing.T) {
+	t.Parallel()
+
+	type config struct {
+		Tenant struct {
+			Dynamic string `yaml:"dynamic"`
+			Derived string `yaml:"derived"`
+		} `yaml:"tenant"`
+	}
+	load := func(value string, classify bool) *testResult[config] {
+		t.Helper()
+		loaded, err := loadGroupedWithSecretLookup(loadRequest[config]{
+			main: loadInput{source: Bytes("input", []byte("dynamic: "+value+"\n")), destination: Keys("tenant")},
+			definition: Definition[config]{
+				Resolve: func(configuration *config, resolution *Resolution) error {
+					configuration.Tenant.Derived = configuration.Tenant.Dynamic
+					resolution.Record(Keys("tenant", "derived"), ChangeNormalization, "derive from dynamic input", Keys("tenant", "dynamic"))
+					return nil
+				},
+				Secret: func(path Path) bool { return classify && path.String() == "/tenant/dynamic" },
+			},
+		}, testSecretBinding(), func(string) (string, bool) { return "", false })
+		if err != nil {
+			t.Fatalf("LoadLayered: %v", err)
+		}
+		return testLoaded(loaded)
+	}
+	left := load("LEFT-DIFF-CANARY", true)
+	right := load("RIGHT-DIFF-CANARY", false)
+	differences, err := Diff(left.Inspection, right.Inspection)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 2 {
+		t.Fatalf("differences = %#v", differences)
+	}
+	seen := make(map[string]bool)
+	for _, difference := range differences {
+		path := difference.Path.String()
+		seen[path] = true
+		if !difference.Left.Redacted || !difference.Right.Redacted || !difference.HiddenChanged ||
+			strings.Contains(difference.Left.YAML+difference.Right.YAML, "DIFF-CANARY") {
+			t.Errorf("bilaterally classified difference at %s = %#v", path, difference)
+		}
+	}
+	for _, path := range []string{"/tenant/dynamic", "/tenant/derived"} {
+		if !seen[path] || !left.Inspection.secrets[path] || right.Inspection.secrets[path] {
+			t.Errorf("classification/difference at %s: seen=%v left=%v right=%v", path, seen[path], left.Inspection.secrets[path], right.Inspection.secrets[path])
+		}
+	}
+}
+
+func TestLayeredDestinationDecodeFailureReturnsNoResultOrLaterCallbacks(t *testing.T) {
+	t.Parallel()
+
+	type config struct {
+		Tenant struct {
+			Count int `yaml:"count"`
+		} `yaml:"tenant"`
+	}
+	calls := struct{ defaults, resolve, lookup, validate int }{}
+	loaded, err := loadGroupedWithSecretLookup(loadRequest[config]{
+		main: loadInput{source: Bytes("invalid", []byte("count: not-an-integer\n")), destination: Keys("tenant")},
+		definition: Definition[config]{
+			Defaults: func() config { calls.defaults++; return config{} },
+			Resolve:  func(*config, *Resolution) error { calls.resolve++; return nil },
+			Validate: func(*config, *Validation) { calls.validate++ },
+		},
+	}, testSecretBinding(), func(string) (string, bool) { calls.lookup++; return "", false })
+	if loaded != nil || err == nil {
+		t.Fatalf("mounted decode failure returned a usable result: %#v, %v", loaded, err)
+	}
+	if calls.defaults != 1 || calls.resolve != 0 || calls.lookup != 0 || calls.validate != 0 {
+		t.Fatalf("callbacks after mounted decode failure = %#v", calls)
+	}
+	if got := groupedErrorCode(t, err); got != CodeDecodeType {
+		t.Fatalf("mounted decode failure code = %s", got)
+	}
+}
+
+func indentDestinationBody(body string) string {
+	var result strings.Builder
+	for _, line := range strings.Split(strings.TrimSuffix(body, "\n"), "\n") {
+		result.WriteString("  ")
+		result.WriteString(line)
+		result.WriteByte('\n')
+	}
+	return result.String()
+}

internal/engine/destination_load_test.go

@@ -0,0 +1,210 @@
+package engine
+
+import (
+	"bytes"
+	"testing"
+)
+
+type destinationLoadConfig struct {
+	Main        map[string]string            `yaml:"main"`
+	Defaults    map[string]string            `yaml:"defaults"`
+	Collections map[string]map[string]string `yaml:"collections"`
+	Value       string                       `yaml:"value"`
+}
+
+type destinationItemConfig struct {
+	Catalog struct {
+		Entries []map[string]string `yaml:"entries"`
+	} `yaml:"catalog"`
+}
+
+func TestLayeredLoadPlacesCompletedMappingAsOneItem(t *testing.T) {
+	t.Parallel()
+
+	loaded, err := LoadLayered[destinationItemConfig](
+		Input{Source: NoSource(), Destination: Keys("catalog", "entries"), placementMode: placementModeSequenceItem},
+		testSecretBinding(),
+		LayeredOptions[destinationItemConfig]{Underlays: []Underlay{{Inputs: []Input{{
+			Source: Mapping("empty-item", map[string]any{}), Destination: Keys("catalog", "entries"),
+			placementMode: placementModeSequenceItem,
+		}}}}},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	if len(result.Config.Catalog.Entries) != 1 || result.Config.Catalog.Entries[0] == nil || len(result.Config.Catalog.Entries[0]) != 0 {
+		t.Fatalf("empty mapping item = %#v", result.Config.Catalog.Entries)
+	}
+	if _, ok := result.Metadata().Lookup(Keys("catalog", "entries", "0")); ok {
+		t.Fatal("sequence index was treated as a literal mapping key during metadata lookup")
+	}
+	sources := result.Sources()
+	if len(sources) != 1 || sources[0].placementMode != placementModeSequenceItem || sources[0].destinationUnresolved {
+		t.Fatalf("source placement evidence = %#v", sources)
+	}
+	if got := sources[0].Destination.String(); got != "/catalog/entries" {
+		t.Fatalf("source destination = %q", got)
+	}
+
+	absent, err := LoadLayered[destinationItemConfig](
+		Input{Source: NoSource(), Destination: Keys("catalog", "entries"), placementMode: placementModeSequenceItem},
+		testSecretBinding(),
+	)
+	if err != nil {
+		t.Fatalf("NoSource item load: %v", err)
+	}
+	if got := len(testLoaded(absent).Config.Catalog.Entries); got != 0 {
+		t.Fatalf("absent item created %d entries", got)
+	}
+}
+
+func TestLayeredItemPlacementPreflightsModeAndDestination(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name string
+		mode placementMode
+		path Path
+	}{
+		{name: "root item", mode: placementModeSequenceItem},
+		{name: "unknown mode", mode: placementMode(255), path: Keys("catalog")},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			reader := bytes.NewBufferString("value: unused\n")
+			_, err := LoadLayered[destinationItemConfig](
+				Input{Source: Reader("reader", reader), Destination: test.path, placementMode: test.mode},
+				testSecretBinding(),
+			)
+			if err == nil || reader.Len() == 0 {
+				t.Fatalf("preflight err %v, unread bytes %d", err, reader.Len())
+			}
+			loadError, ok := err.(*LoadError)
+			if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != CodeOptionsInvalid {
+				t.Fatalf("preflight error = %#v", err)
+			}
+		})
+	}
+}
+
+func TestLoadOptionsPlaceOneMappingItem(t *testing.T) {
+	t.Parallel()
+
+	loaded, err := Load[destinationItemConfig](
+		Mapping("ordinary", map[string]any{}), testSecretBinding(),
+		Options[destinationItemConfig]{destination: Keys("catalog", "entries"), placementMode: placementModeSequenceItem},
+	)
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	result := testLoaded(loaded)
+	if len(result.Config.Catalog.Entries) != 1 || result.Config.Catalog.Entries[0] == nil {
+		t.Fatalf("ordinary item placement = %#v", result.Config.Catalog.Entries)
+	}
+}
+
+func TestLayeredLoadPlacesNonImportMainAndUnderlayInputs(t *testing.T) {
+	t.Parallel()
+
+	destination := Keys("main")
+	main := Input{Source: Bytes("main", []byte("value: primary\n")), Destination: destination}
+	underlay := Input{Source: Bytes("defaults", []byte("value: fallback\n")), Destination: Keys("defaults")}
+	loaded, err := LoadLayered(main, testSecretBinding(), LayeredOptions[destinationLoadConfig]{
+		Underlays: []Underlay{{Inputs: []Input{underlay}}},
+	})
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	if result.Config.Main["value"] != "primary" || result.Config.Defaults["value"] != "fallback" {
+		t.Fatalf("mounted configuration = %#v", result.Config)
+	}
+	sources := result.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != "/main" || sources[1].Destination.String() != "/defaults" {
+		t.Fatalf("source destinations = %#v", sources)
+	}
+
+	destination.segments[0].key = "caller mutation"
+	sources[0].Destination.segments[0].key = "record mutation"
+	if got := result.Sources()[0].Destination.String(); got != "/main" {
+		t.Fatalf("source destination was not independently owned: %q", got)
+	}
+}
+
+func TestLayeredLoadOmittedAndEmptyDestinationsKeepRootPlacement(t *testing.T) {
+	t.Parallel()
+
+	inputs := []Input{
+		{Source: Bytes("omitted", []byte("value: same\n"))},
+		{Source: Bytes("empty", []byte("value: same\n")), Destination: Keys()},
+	}
+	for _, input := range inputs {
+		loaded, err := LoadLayered(input, testSecretBinding(), LayeredOptions[destinationLoadConfig]{})
+		if err != nil {
+			t.Fatalf("LoadLayered: %v", err)
+		}
+		result := testLoaded(loaded)
+		if result.Config.Value != "same" {
+			t.Fatalf("root value = %q", result.Config.Value)
+		}
+		sources := result.Sources()
+		if len(sources) != 1 || sources[0].Destination.String() != "" {
+			t.Fatalf("root source destination = %#v", sources)
+		}
+	}
+}
+
+func TestLayeredLoadDistinguishesEmptyBodyFromNoSource(t *testing.T) {
+	t.Parallel()
+
+	loaded, err := LoadLayered(
+		Input{Source: NoSource(), Destination: Keys("absent")},
+		testSecretBinding(),
+		LayeredOptions[destinationLoadConfig]{Underlays: []Underlay{{Inputs: []Input{{
+			Source: Bytes("empty", []byte("{}\n")), Destination: Keys("collections", "one"),
+		}}}}},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	info, ok := result.Metadata().Lookup(Keys("collections", "one"))
+	if !ok || !info.Explicit || info.Origin.Layer != LayerUnderlay {
+		t.Fatalf("empty mounted mapping = %#v, %v", info, ok)
+	}
+	if _, ok := result.Metadata().Lookup(Keys("absent")); ok {
+		t.Fatal("NoSource materialized its destination")
+	}
+	sources := result.Sources()
+	if len(sources) != 1 || sources[0].Label != "empty" || sources[0].Destination.String() != "/collections/one" {
+		t.Fatalf("sources = %#v", sources)
+	}
+}
+
+func TestLayeredLoadPreflightsDestinationsBeforeReadingSources(t *testing.T) {
+	t.Parallel()
+
+	reader := bytes.NewBufferString("value: unused\n")
+	_, err := LoadLayered(
+		Input{Source: NoSource()},
+		testSecretBinding(),
+		LayeredOptions[destinationLoadConfig]{Underlays: []Underlay{{Inputs: []Input{{
+			Source: Reader("reader", reader), Destination: Keys("configkit"),
+		}}}}},
+	)
+	if err == nil {
+		t.Fatal("reserved destination was accepted")
+	}
+	if reader.Len() == 0 {
+		t.Fatal("source reader was consumed before destination preflight")
+	}
+	loadError, ok := err.(*LoadError)
+	if !ok || len(loadError.Diagnostics()) != 1 {
+		t.Fatalf("error = %#v", err)
+	}
+	diagnostic := loadError.Diagnostics()[0]
+	if diagnostic.Code != CodeOptionsInvalid || diagnostic.Path.String() != "/configkit" || diagnostic.Primary != nil {
+		t.Fatalf("destination diagnostic = %#v", diagnostic)
+	}
+}

internal/engine/destination_provenance_test.go

@@ -0,0 +1,181 @@
+package engine
+
+import (
+	"errors"
+	"io/fs"
+	"path"
+	"reflect"
+	"testing"
+)
+
+func TestLayeredDestinationsRetainOriginsHistoryAndDetachedRecords(t *testing.T) {
+	t.Parallel()
+
+	directory := t.TempDir()
+	sharedPath := writeImportFile(t, directory, "shared.yml", "section:\n  shared: lower\n  branch:\n    child: old\n    kept: retained\n")
+	shared := File(sharedPath)
+	load := func() (*Loaded[map[string]any], error) {
+		return LoadLayered(
+			Input{Source: NoSource()}, testSecretBinding(),
+			LayeredOptions[map[string]any]{Underlays: []Underlay{
+				{Inputs: []Input{
+					{Source: shared, Destination: Keys("catalog")},
+					{Source: Bytes("peer", []byte("section:\n  peer: present\n")), Destination: Keys("catalog")},
+				}},
+				{Inputs: []Input{{Source: shared, Destination: Keys("backup")}}},
+				{Inputs: []Input{{Source: Bytes("replacement", []byte("section:\n  branch: replaced\n")), Destination: Keys("catalog")}}},
+			}},
+		)
+	}
+	loaded, err := load()
+	if err != nil {
+		t.Fatalf("LoadLayered: %v, diagnostics %#v", err, err.(*LoadError).Diagnostics())
+	}
+	result := testLoaded(loaded)
+	metadata := result.Metadata()
+
+	container, ok := metadata.Lookup(Keys("catalog"))
+	if !ok || !container.Explicit || len(container.Origin.Locations) < 3 {
+		t.Fatalf("mounted container origin = %#v, %v", container, ok)
+	}
+	containerSources := make(map[string]bool)
+	for _, location := range container.Origin.Locations {
+		containerSources[location.SourceID] = true
+		if location.Line < 1 {
+			t.Fatalf("introduced container lacks its source-root fallback: %#v", location)
+		}
+	}
+	for _, sourceID := range []string{"source-1", "source-2", "source-4"} {
+		if !containerSources[sourceID] {
+			t.Fatalf("container contributors = %#v, missing %s", container.Origin.Locations, sourceID)
+		}
+	}
+
+	sharedField, ok := metadata.Lookup(Keys("catalog", "section", "shared"))
+	if !ok || len(sharedField.Origin.Locations) != 1 || sharedField.Origin.Locations[0].SourceID != "source-1" || sharedField.Origin.Locations[0].Line != 2 {
+		t.Fatalf("authored leaf origin = %#v, %v", sharedField, ok)
+	}
+	peerField, ok := metadata.Lookup(Keys("catalog", "section", "peer"))
+	if !ok || len(peerField.Origin.Locations) != 1 || peerField.Origin.Locations[0].SourceID != "source-2" {
+		t.Fatalf("peer leaf origin = %#v, %v", peerField, ok)
+	}
+	if _, ok := metadata.Lookup(Keys("catalog", "section", "branch", "child")); ok {
+		t.Fatal("replaced descendant remains effective")
+	}
+	removed := metadata.History(Keys("catalog", "section", "branch", "child"))
+	if len(removed) < 2 || removed[0].Origin.Locations[0].SourceID != "source-1" {
+		t.Fatalf("removed descendant history = %#v", removed)
+	}
+
+	backup, ok := metadata.Lookup(Keys("backup", "section", "shared"))
+	if !ok || len(backup.Origin.Locations) != 1 || backup.Origin.Locations[0].SourceID != "source-3" {
+		t.Fatalf("second-tier leaf origin = %#v, %v", backup, ok)
+	}
+	sources := result.Sources()
+	if len(sources) != 4 || sources[0].Path != sources[2].Path || sources[0].Destination.String() != "/catalog" || sources[2].Destination.String() != "/backup" {
+		t.Fatalf("same source in separate tiers = %#v", sources)
+	}
+	if sources[0].Layer != LayerUnderlay || sources[0].UnderlayIndex != 1 || sources[2].Layer != LayerUnderlay || sources[2].UnderlayIndex != 2 {
+		t.Fatalf("tier source records = %#v", sources)
+	}
+
+	other, err := load()
+	if err != nil {
+		t.Fatalf("independent load: %v", err)
+	}
+	differences, err := Diff(loaded.Inspection, other.Inspection)
+	if err != nil || len(differences) != 0 {
+		t.Fatalf("equivalent inspection diff = %#v, %v", differences, err)
+	}
+
+	sources[0].Destination.segments[0].key = "mutated"
+	sharedField.Origin.Locations[0].SourceID = "mutated"
+	removed[0].Path.segments[0].key = "mutated"
+	if got := result.Sources()[0].Destination.String(); got != "/catalog" {
+		t.Fatalf("source record copy changed after inspection: %q", got)
+	}
+	fresh, ok := result.Metadata().Lookup(Keys("catalog", "section", "shared"))
+	if !ok || fresh.Origin.Locations[0].SourceID != "source-1" {
+		t.Fatalf("effective origin changed after mutating returned records: %#v, %v", fresh, ok)
+	}
+	if got := result.Metadata().History(Keys("catalog", "section", "branch", "child")); len(got) < 2 || got[0].Path.String() != "/catalog/section/branch/child" {
+		t.Fatalf("historical path changed after mutating returned records: %#v", got)
+	}
+	if got := other.Inspection.sources[0].Destination.String(); got != "/catalog" {
+		t.Fatalf("independent load destination changed: %q", got)
+	}
+}
+
+func TestLayeredImportedInheritedValuesRetainResourceContexts(t *testing.T) {
+	t.Parallel()
+
+	type entry struct {
+		Extends  string `yaml:"extends"`
+		Resource string `yaml:"resource"`
+		Count    int    `yaml:"count"`
+	}
+	type config struct {
+		Catalog struct {
+			Entries map[string]entry `yaml:"entries"`
+		} `yaml:"catalog"`
+	}
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "config/main.yml", "child:\n  extends: parent\n")
+	inputPath := writeImportFile(t, directory, "shared/input.yml", "configkit: {imports: [{path: parent.yml}]}\n")
+	writeImportFile(t, directory, "shared/parent.yml", "parent:\n  resource: icon.txt\n  count: 1\n")
+	writeImportFile(t, directory, "shared/icon.txt", "parent-resource")
+	var resolutionContext ResourceContext
+	loaded, err := LoadLayered(
+		Input{Source: File(mainPath), Destination: Keys("catalog", "entries")},
+		testSecretBinding(),
+		LayeredOptions[config]{
+			Underlays: []Underlay{{Inputs: []Input{{
+				Source: File(inputPath), Imports: true, Destination: Keys("catalog", "entries"),
+			}}}},
+			Definition: Definition[config]{Resolve: func(configuration *config, resolution *Resolution) error {
+				info, ok := resolution.InputInfo(Keys("catalog", "entries", "child", "resource"))
+				if !ok || len(info.Origin.Locations) != 1 || len(info.Origin.Inheritance) != 1 {
+					return errors.New("inherited resource lacks its source origin")
+				}
+				var found bool
+				resolutionContext, found = resolution.state.input.sourceContext(info.Origin.Locations[0].SourceID)
+				if !found || resolutionContext.BaseDir != "." || resolutionContext.FS == nil {
+					return errors.New("resolver could not find the declaring resource context")
+				}
+				data, err := fs.ReadFile(resolutionContext.FS, path.Join(resolutionContext.BaseDir, configuration.Catalog.Entries["child"].Resource))
+				if err != nil || string(data) != "parent-resource" {
+					return errors.New("resolver could not read the inherited relative resource")
+				}
+				return nil
+			}},
+		},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v, diagnostics %#v", err, err.(*LoadError).Diagnostics())
+	}
+	result := testLoaded(loaded)
+	child := result.Config.Catalog.Entries["child"]
+	if child.Resource != "icon.txt" || child.Count != 1 || child.Extends != "" {
+		t.Fatalf("inherited child = %#v", child)
+	}
+	field, ok := result.Metadata().Lookup(Keys("catalog", "entries", "child", "resource"))
+	if !ok || len(field.Origin.Locations) != 1 || len(field.Origin.Inheritance) != 1 {
+		t.Fatalf("inherited resource origin = %#v, %v", field, ok)
+	}
+	context, ok := result.Inspection.SourceContext(field.Origin.Locations[0].SourceID)
+	if !ok || context.BaseDir != "." || context.FS == nil || resolutionContext.BaseDir != context.BaseDir {
+		t.Fatalf("completed resource contexts = %#v, %#v, %v", resolutionContext, context, ok)
+	}
+	data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, child.Resource))
+	if err != nil || string(data) != "parent-resource" {
+		t.Fatalf("completed source-relative resource = %q, %v", data, err)
+	}
+	if !reflect.DeepEqual(result.Config.Catalog.Entries["parent"], entry{Resource: "icon.txt", Count: 1}) {
+		t.Fatalf("surviving lower-tier parent = %#v", result.Config.Catalog.Entries["parent"])
+	}
+	for _, source := range result.Sources() {
+		if source.Layer == LayerUnderlay && source.Destination.String() != "/catalog/entries" {
+			t.Errorf("underlay destination = %#v", source)
+		}
+	}
+}

internal/engine/destination_test.go

@@ -0,0 +1,287 @@
+package engine
+
+import (
+	"errors"
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestNormalizeDestinationUsesLiteralMappingKeys(t *testing.T) {
+	t.Parallel()
+
+	parsed, err := ParsePath("/a~1b/0/~0")
+	if err != nil {
+		t.Fatal(err)
+	}
+	normalized, err := normalizeDestination(parsed)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := normalized.String(), "/a~1b/0/~0"; got != want {
+		t.Fatalf("normalized path = %q, want %q", got, want)
+	}
+	for index, want := range []string{"a/b", "0", "~"} {
+		segment := normalized.segments[index]
+		if segment.kind != pathSegmentKey || segment.key != want {
+			t.Fatalf("segment %d = %#v, want key %q", index, segment, want)
+		}
+	}
+
+	original := Keys("owned", "path")
+	owned, err := normalizeDestination(original)
+	if err != nil {
+		t.Fatal(err)
+	}
+	owned.segments[0].key = "changed"
+	if got := original.String(); got != "/owned/path" {
+		t.Fatalf("normalizing shared path storage mutated its input: %q", got)
+	}
+}
+
+func TestMappingPlacementModeMatchesZeroValue(t *testing.T) {
+	t.Parallel()
+
+	body := &document.Node{
+		Kind: document.Mapping,
+		Mapping: []document.Entry{{
+			Key: "name", Value: &document.Node{Kind: document.String, Text: "entry"},
+		}},
+	}
+	destination := Keys("catalog", "entry")
+	path, zero, err := placeDocument(body, destination, body.Location, 5, 32)
+	if err != nil {
+		t.Fatal(err)
+	}
+	explicitPath, explicit, err := placeDocumentWithMode(body, destination, placementModeMapping, body.Location, 5, 32)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if path.String() != explicitPath.String() || !reflect.DeepEqual(zero, explicit) {
+		t.Fatalf("zero placement (%q, %#v) differs from mapping mode (%q, %#v)", path.String(), zero, explicitPath.String(), explicit)
+	}
+}
+
+func TestAppendDestinationCopiesLiteralSegments(t *testing.T) {
+	t.Parallel()
+
+	parent := Keys("collection", "entry")
+	relative := Keys("a/b", "0", "~")
+	combined := appendDestination(parent, relative)
+	if got, want := combined.String(), "/collection/entry/a~1b/0/~0"; got != want {
+		t.Fatalf("combined destination = %q, want %q", got, want)
+	}
+	if len(combined.segments) != 5 {
+		t.Fatalf("combined segments = %#v", combined.segments)
+	}
+	for index, segment := range combined.segments {
+		if segment.kind != pathSegmentKey {
+			t.Errorf("segment %d kind = %v, want mapping key", index, segment.kind)
+		}
+	}
+
+	combined.segments[0].key = "changed parent"
+	combined.segments[2].key = "changed relative"
+	if got := parent.String(); got != "/collection/entry" {
+		t.Fatalf("combined path shares parent segment storage: %q", got)
+	}
+	if got := relative.String(); got != "/a~1b/0/~0" {
+		t.Fatalf("combined path shares relative segment storage: %q", got)
+	}
+}
+
+func TestNormalizeDestinationRejectsIndicesAndReservedKeys(t *testing.T) {
+	t.Parallel()
+
+	for name, path := range map[string]Path{
+		"explicit index":   Keys("items").Index(0),
+		"negative index":   Keys("items").Index(-1),
+		"invalid path":     Path{invalid: true},
+		"configkit":        Keys("configkit"),
+		"extends":          Keys("extends"),
+		"nested configkit": Keys("outer", "configkit"),
+		"nested extends":   Keys("outer", "extends"),
+	} {
+		t.Run(name, func(t *testing.T) {
+			t.Parallel()
+			if _, err := normalizeDestination(path); !errors.Is(err, errInvalidDestination) {
+				t.Fatalf("normalizeDestination(%q) error = %v, want invalid destination", path.String(), err)
+			}
+		})
+	}
+
+	for _, key := range []string{"myextends", "configkit2", "", ".", "..", "../x", "a.b", "a/b", "~"} {
+		t.Run("ordinary key "+key, func(t *testing.T) {
+			t.Parallel()
+			if _, err := normalizeDestination(Keys(key)); err != nil {
+				t.Fatalf("normalizeDestination(%q): %v", key, err)
+			}
+		})
+	}
+}
+
+func TestPlaceDocumentWrapsEmptyMappingAndPreservesSourceCoordinates(t *testing.T) {
+	t.Parallel()
+
+	rootLocation := document.Location{SourceID: "source-a", Line: 1, Column: 1}
+	body := &document.Node{
+		Kind:     document.Mapping,
+		Location: document.Location{SourceID: "source-a", Line: 4, Column: 1},
+	}
+	path, placed, err := placeDocument(body, Keys("a", "b"), rootLocation, 2, 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got, want := path.String(), "/a/b"; got != want {
+		t.Fatalf("normalized destination = %q, want %q", got, want)
+	}
+	if placed == body || len(placed.Mapping) != 1 || placed.Mapping[0].Key != "a" {
+		t.Fatalf("outer destination mapping was not created: %#v", placed)
+	}
+	inner := placed.Mapping[0].Value
+	if inner.Kind != document.Mapping || len(inner.Mapping) != 1 || inner.Mapping[0].Key != "b" {
+		t.Fatalf("inner destination mapping was not created: %#v", inner)
+	}
+	if inner.Mapping[0].Value != body || len(body.Mapping) != 0 {
+		t.Fatal("placement mutated or copied the authored body")
+	}
+	if placed.Location != rootLocation || inner.Location != rootLocation || placed.Mapping[0].KeyLocation != rootLocation || placed.Mapping[0].ValueLocation != rootLocation {
+		t.Fatal("introduced structure did not use the source-root coordinate fallback")
+	}
+	if body.Location != (document.Location{SourceID: "source-a", Line: 4, Column: 1}) {
+		t.Fatalf("authored body location changed: %#v", body.Location)
+	}
+	if got, want := countInputNodes(placed), countInputNodes(body)+4; got != want {
+		t.Fatalf("placed node count = %d, want body count plus four synthetic nodes (%d)", got, want)
+	}
+}
+
+func TestPlaceDocumentPreservesAuthoredEntryCoordinates(t *testing.T) {
+	t.Parallel()
+
+	rootLocation := document.Location{SourceID: "source-b", Line: 1, Column: 1}
+	bodyLocation := document.Location{SourceID: "source-b", Line: 3, Column: 1}
+	keyLocation := document.Location{SourceID: "source-b", Line: 3, Column: 3}
+	valueLocation := document.Location{SourceID: "source-b", Line: 4, Column: 5}
+	value := &document.Node{Kind: document.String, Location: valueLocation, Text: "value"}
+	body := &document.Node{
+		Kind:     document.Mapping,
+		Location: bodyLocation,
+		Mapping: []document.Entry{{
+			Key:           "leaf",
+			KeyLocation:   keyLocation,
+			ValueLocation: valueLocation,
+			Value:         value,
+		}},
+	}
+	_, placed, err := placeDocument(body, Keys("mounted"), rootLocation, 2, 5)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if placed.Mapping[0].KeyLocation != rootLocation || placed.Mapping[0].ValueLocation != rootLocation {
+		t.Fatal("introduced destination entry did not use the source-root fallback")
+	}
+	if placed.Mapping[0].Value != body || body.Location != bodyLocation {
+		t.Fatal("placement changed the authored body node or location")
+	}
+	entry := body.Mapping[0]
+	if entry.KeyLocation != keyLocation || entry.ValueLocation != valueLocation || entry.Value != value || value.Location != valueLocation {
+		t.Fatal("placement changed authored entry or value coordinates")
+	}
+}
+
+func TestPlaceDocumentRootAndBounds(t *testing.T) {
+	t.Parallel()
+
+	body := &document.Node{
+		Kind: document.Mapping,
+		Mapping: []document.Entry{{
+			Key:   "leaf",
+			Value: &document.Node{Kind: document.String, Text: "value"},
+		}},
+	}
+	path, placed, err := placeDocument(body, Path{}, body.Location, 1, 3)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if path.String() != "" || placed != body {
+		t.Fatal("root placement must preserve the existing body")
+	}
+
+	destination := Keys("a", "b")
+	if !destinationWithinLimits(body, destination, 3, 7) {
+		t.Fatal("exact depth and node limits should admit the placed document")
+	}
+	if destinationWithinLimits(body, destination, 2, 7) {
+		t.Fatal("placement exceeding the depth limit was accepted")
+	}
+	if destinationWithinLimits(body, destination, 3, 6) {
+		t.Fatal("placement exceeding the node limit was accepted")
+	}
+	_, placed, err = placeDocument(body, destination, body.Location, 3, 6)
+	if !errors.Is(err, errDestinationLimit) || placed != nil {
+		t.Fatalf("bounded placement returned node %p and error %v", placed, err)
+	}
+	_, absent, err := placeDocument(nil, destination, document.Location{}, 0, 0)
+	if err != nil || absent != nil {
+		t.Fatalf("absent body should not consume placement limits: node %p, error %v", absent, err)
+	}
+}
+
+func TestPlaceDocumentSequenceItemAndMountedBounds(t *testing.T) {
+	t.Parallel()
+
+	root := document.Location{SourceID: "item", Line: 1, Column: 1}
+	body := &document.Node{Kind: document.Mapping, Location: root}
+	destination := Keys("catalog", "entries")
+	placedPath, placed, err := placeDocumentWithMode(body, destination, placementModeSequenceItem, root, 3, 6)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if placedPath.String() != "/catalog/entries" || placed.Kind != document.Mapping {
+		t.Fatalf("placed root = %q %#v", placedPath.String(), placed)
+	}
+	container, ok := documentAtPath(placed, destination)
+	if !ok || container.Kind != document.Sequence || len(container.Sequence) != 1 || container.Sequence[0] != body {
+		t.Fatalf("item destination = %#v, present %v", container, ok)
+	}
+	if got, want := countInputNodes(placed), countInputNodes(body)+destinationWrapperNodeCount(destination)+1; got != want {
+		t.Fatalf("item node count = %d, want %d", got, want)
+	}
+	if container.Location != root || container.Sequence[0].Location != root {
+		t.Fatal("synthetic sequence or authored mapping lost source coordinates")
+	}
+
+	if _, _, err := placeDocumentWithMode(body, Path{}, placementModeSequenceItem, root, 3, 6); !errors.Is(err, errInvalidDestination) {
+		t.Fatalf("root item placement error = %v, want invalid destination", err)
+	}
+	if _, _, err := placeDocumentWithMode(&document.Node{Kind: document.String}, destination, placementModeSequenceItem, root, 3, 6); !errors.Is(err, errInvalidDestination) {
+		t.Fatalf("non-mapping item placement error = %v, want invalid destination", err)
+	}
+	if _, _, err := placeDocumentWithMode(body, destination, placementMode(255), root, 3, 6); !errors.Is(err, errInvalidDestination) {
+		t.Fatalf("unknown placement mode error = %v, want invalid destination", err)
+	}
+
+	for _, test := range []struct {
+		name       string
+		depth      int
+		nodes      int
+		wantAccept bool
+	}{
+		{name: "exact allowance", depth: 3, nodes: 6, wantAccept: true},
+		{name: "one too shallow", depth: 2, nodes: 6},
+		{name: "one node short", depth: 3, nodes: 5},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			_, _, err := placeDocumentWithMode(body, destination, placementModeSequenceItem, root, test.depth, test.nodes)
+			if test.wantAccept && err != nil {
+				t.Fatalf("exact bounds rejected: %v", err)
+			}
+			if !test.wantAccept && !errors.Is(err, errDestinationLimit) {
+				t.Fatalf("over-bound placement error = %v", err)
+			}
+		})
+	}
+}

internal/engine/destination_tiers_test.go

@@ -0,0 +1,347 @@
+package engine
+
+import (
+	"path/filepath"
+	"reflect"
+	"testing"
+	"testing/fstest"
+)
+
+func TestLayeredDestinationStrictCompositionBoundaries(t *testing.T) {
+	t.Parallel()
+
+	tests := []struct {
+		name     string
+		inputs   []Input
+		wantPath []string
+		want     any
+		alsoPath []string
+		alsoWant any
+	}{
+		{
+			name: "disjoint peers at one destination",
+			inputs: []Input{
+				{Source: Bytes("left", []byte("left: one\n")), Destination: Keys("application")},
+				{Source: Bytes("right", []byte("right: two\n")), Destination: Keys("application")},
+			},
+			wantPath: []string{"application", "right"},
+			want:     "two",
+			alsoPath: []string{"application", "left"},
+			alsoWant: "one",
+		},
+		{
+			name: "different destinations",
+			inputs: []Input{
+				{Source: Bytes("left", []byte("value: shared\n")), Destination: Keys("left")},
+				{Source: Bytes("right", []byte("value: shared\n")), Destination: Keys("right")},
+			},
+			wantPath: []string{"right", "value"},
+			want:     "shared",
+		},
+		{
+			name: "ancestor and descendant destinations",
+			inputs: []Input{
+				{Source: Bytes("parent", []byte("branch: {base: one}\n")), Destination: Keys("application")},
+				{Source: Bytes("child", []byte("leaf: two\n")), Destination: Keys("application", "branch")},
+			},
+			wantPath: []string{"application", "branch", "leaf"},
+			want:     "two",
+			alsoPath: []string{"application", "branch", "base"},
+			alsoWant: "one",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			loaded, err := LoadLayered(Input{Source: NoSource()}, testSecretBinding(), LayeredOptions[map[string]any]{
+				Underlays: []Underlay{{Inputs: test.inputs}},
+			})
+			if err != nil {
+				t.Fatalf("LoadLayered: %v", err)
+			}
+			result := testLoaded(loaded)
+			if got := layeredMapValue(t, result.Config, test.wantPath...); got != test.want {
+				t.Fatalf("value at %v = %#v, want %#v", test.wantPath, got, test.want)
+			}
+			if len(test.alsoPath) != 0 {
+				if got := layeredMapValue(t, result.Config, test.alsoPath...); got != test.alsoWant {
+					t.Fatalf("value at %v = %#v, want %#v", test.alsoPath, got, test.alsoWant)
+				}
+			}
+		})
+	}
+
+	for _, test := range []struct {
+		name  string
+		left  string
+		right string
+	}{
+		{name: "equal values conflict", left: "value: same\n", right: "value: same\n"},
+		{name: "unequal values conflict", left: "value: left\n", right: "value: right\n"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			inputs := []Input{
+				{Source: Bytes("left", []byte(test.left)), Destination: Keys("application")},
+				{Source: Bytes("right", []byte(test.right)), Destination: Keys("application")},
+			}
+			loaded, err := LoadLayered(Input{Source: NoSource()}, testSecretBinding(), LayeredOptions[map[string]any]{
+				Underlays: []Underlay{{Inputs: inputs}},
+			})
+			if loaded != nil || groupedErrorCode(t, err) != CodeComposeConflict {
+				t.Fatalf("strict composition result = %#v, %v", loaded, err)
+			}
+		})
+	}
+
+	t.Run("strict conflict is not hidden by an upper override", func(t *testing.T) {
+		inputs := []Input{
+			{Source: Bytes("left", []byte("value: left\n")), Destination: Keys("application")},
+			{Source: Bytes("right", []byte("value: right\n")), Destination: Keys("application")},
+		}
+		loaded, err := LoadLayered(
+			Input{Source: Bytes("main", []byte("value: upper\n")), Destination: Keys("application")},
+			testSecretBinding(),
+			LayeredOptions[map[string]any]{Underlays: []Underlay{{Inputs: inputs}}},
+		)
+		if loaded != nil || groupedErrorCode(t, err) != CodeComposeConflict {
+			t.Fatalf("strict composition result = %#v, %v", loaded, err)
+		}
+	})
+}
+
+func TestLayeredDestinationMatchesExplicitlyWrappedInput(t *testing.T) {
+	t.Parallel()
+
+	load := func(input Input) map[string]any {
+		t.Helper()
+		loaded, err := LoadLayered(Input{Source: NoSource()}, testSecretBinding(), LayeredOptions[map[string]any]{
+			Underlays: []Underlay{{Inputs: []Input{input}}},
+		})
+		if err != nil {
+			t.Fatalf("LoadLayered: %v", err)
+		}
+		return testLoaded(loaded).Config
+	}
+
+	placed := load(Input{Source: Bytes("placed", []byte("field: value\n")), Destination: Keys("application")})
+	authored := load(Input{Source: Bytes("authored", []byte("application: {field: value}\n"))})
+	if !reflect.DeepEqual(placed, authored) {
+		t.Fatalf("placed configuration %#v differs from explicitly wrapped %#v", placed, authored)
+	}
+}
+
+func TestEmptyMountedMappingRetainsLowerChildren(t *testing.T) {
+	t.Parallel()
+
+	destination := Keys("collections", "weather")
+	loaded, err := LoadLayered(
+		Input{Source: Bytes("empty-main", []byte("{}\n")), Destination: destination},
+		testSecretBinding(),
+		LayeredOptions[map[string]any]{Underlays: []Underlay{{Inputs: []Input{{
+			Source: Bytes("lower", []byte("prompt: {title: retained}\n")), Destination: destination,
+		}}}}},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	if got := layeredMapValue(t, testLoaded(loaded).Config, "collections", "weather", "prompt", "title"); got != "retained" {
+		t.Fatalf("lower child beneath empty mounted mapping = %#v, want retained", got)
+	}
+}
+
+func TestLayeredDestinationOverlayRetainsOrdinaryValueSemantics(t *testing.T) {
+	t.Parallel()
+
+	filesystem := NewFilesystem("bundle", fstest.MapFS{
+		"overlays/test.yml": &fstest.MapFile{Data: []byte("settings:\n  metadata:\n    version: overlay\n")},
+	})
+	loaded, err := LoadLayered(
+		Input{Source: Bytes("main", []byte("mapping: {shared: main}\nsequence: [9]\ncleared: null\nenabled: false\nmetadata: {version: main}\n")), Destination: Keys("settings")},
+		testSecretBinding(),
+		LayeredOptions[map[string]any]{
+			Underlays: []Underlay{{Inputs: []Input{{
+				Source:      Bytes("underlay", []byte("mapping: {retained: lower, shared: lower}\nsequence: [1, 2]\ncleared: {old: true}\nenabled: true\ncount: 7\nmetadata: {version: lower, label: retained}\n")),
+				Destination: Keys("settings"),
+			}}}},
+			Overlay:           "test",
+			OverlayFilesystem: &FilesystemContext{Root: ".", BaseDir: ".", FS: &filesystem},
+			Overrides:         []Override{{Path: Keys("settings", "count"), Value: 0, Flag: "--count"}},
+		},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	settings := layeredMap(t, result.Config, "settings")
+	mapping := layeredMap(t, settings, "mapping")
+	if mapping["retained"] != "lower" || mapping["shared"] != "main" {
+		t.Fatalf("recursive mapping overlay = %#v", mapping)
+	}
+	sequence, ok := settings["sequence"].([]any)
+	if !ok || len(sequence) != 1 || sequence[0] != int64(9) {
+		t.Fatalf("sequence overlay = %#v", settings["sequence"])
+	}
+	if value, present := settings["cleared"]; !present || value != nil {
+		t.Fatalf("explicit null = %#v, present %v", value, present)
+	}
+	if value, ok := settings["enabled"].(bool); !ok || value {
+		t.Fatalf("explicit false = %#v", settings["enabled"])
+	}
+	if value, ok := settings["count"].(int64); !ok || value != 0 {
+		t.Fatalf("explicit zero override = %#v", settings["count"])
+	}
+	metadata := layeredMap(t, settings, "metadata")
+	if metadata["version"] != "overlay" || metadata["label"] != "retained" {
+		t.Fatalf("version-only overlay = %#v", metadata)
+	}
+	if _, present := settings["settings"]; present {
+		t.Fatalf("upper tiers were incorrectly nested under the main destination: %#v", result.Config)
+	}
+}
+
+func TestLayeredDestinationChecksVersionOnceOnComposedMain(t *testing.T) {
+	t.Parallel()
+
+	type appConfig struct {
+		Version  int8   `yaml:"version"`
+		Count    int    `yaml:"count"`
+		Main     string `yaml:"main"`
+		Imported string `yaml:"imported"`
+		Lower    string `yaml:"lower"`
+	}
+	type config struct {
+		App appConfig `yaml:"app"`
+	}
+	filesystem := NewFilesystem("bundle", fstest.MapFS{
+		"main.yml":     &fstest.MapFile{Data: []byte("configkit: {imports: [{path: fragment.yml}]}\nversion: 6\ncount: 4\nmain: main\n")},
+		"fragment.yml": &fstest.MapFile{Data: []byte("imported: included\n")},
+	})
+	checks := 0
+	loaded, err := LoadLayered(
+		Input{Source: filesystem.File("main.yml"), Imports: true, Destination: Keys("app")},
+		testSecretBinding(),
+		LayeredOptions[config]{
+			Definition: Definition[config]{Version: &VersionRule{Path: Keys("app", "version"), Check: func(version Version, _ *Validation) error {
+				checks++
+				if !version.Present || version.Text != "6" {
+					t.Errorf("nested main version = %#v", version)
+				}
+				return nil
+			}}},
+			Underlays: []Underlay{{Inputs: []Input{{
+				Source: Bytes("lower", []byte("lower: underlay\n")), Destination: Keys("app"),
+			}}}},
+		},
+	)
+	if err != nil {
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	if checks != 1 {
+		t.Fatalf("version hook calls = %d, want 1", checks)
+	}
+	if result.Config.App.Version != 6 || result.Config.App.Count != 4 || result.Config.App.Main != "main" || result.Config.App.Imported != "included" || result.Config.App.Lower != "underlay" {
+		t.Fatalf("nested app = %#v", result.Config.App)
+	}
+}
+
+func TestLayeredDestinationVersionClaimsUsePlacedApplicationPaths(t *testing.T) {
+	t.Parallel()
+
+	rule := &VersionRule{Path: Keys("app", "schema", "version"), Check: func(Version, *Validation) error { return nil }}
+	for _, test := range []struct {
+		name      string
+		body      string
+		wantCode  Code
+		wantValue any
+	}{
+		{name: "underlay direct claim", body: "schema: {version: v2}\n", wantCode: CodeUnderlayVersion},
+		{name: "underlay ancestor claim", body: "schema: null\n", wantCode: CodeUnderlayVersion},
+		{name: "underlay mapping ancestor without claim", body: "schema: {name: ordinary}\n", wantValue: "ordinary"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			loaded, err := LoadLayered(
+				Input{Source: NoSource()},
+				testSecretBinding(),
+				LayeredOptions[map[string]any]{
+					Definition: Definition[map[string]any]{Version: rule},
+					Underlays: []Underlay{{Inputs: []Input{{
+						Source: Bytes("underlay", []byte(test.body)), Destination: Keys("app"),
+					}}}},
+				},
+			)
+			if test.wantCode != "" {
+				if loaded != nil || groupedErrorCode(t, err) != test.wantCode {
+					t.Fatalf("version claim result = %#v, %v", loaded, err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("nonclaiming mapping ancestor was rejected: %v", err)
+			}
+			result := testLoaded(loaded)
+			if got := layeredMapValue(t, result.Config, "app", "schema", "name"); got != test.wantValue {
+				t.Fatalf("nested ordinary value = %#v", got)
+			}
+		})
+	}
+
+	for _, test := range []struct {
+		name     string
+		body     string
+		wantCode Code
+	}{
+		{name: "imported direct claim", body: "schema: {version: v2}\n", wantCode: CodeImportVersion},
+		{name: "imported ancestor claim", body: "schema: null\n", wantCode: CodeImportVersion},
+		{name: "imported mapping ancestor without claim", body: "schema: {name: ordinary}\n"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			t.Parallel()
+			directory := t.TempDir()
+			writeImportFile(t, directory, "main.yml", "configkit: {imports: [{path: fragment.yml}]}\n")
+			writeImportFile(t, directory, "fragment.yml", test.body)
+			loaded, err := LoadLayered(
+				Input{Source: NoSource()},
+				testSecretBinding(),
+				LayeredOptions[map[string]any]{
+					Definition: Definition[map[string]any]{Version: rule},
+					Underlays: []Underlay{{Inputs: []Input{{
+						Source: File(filepath.Join(directory, "main.yml")), Imports: true, Destination: Keys("app"),
+					}}}},
+				},
+			)
+			if test.wantCode != "" {
+				if loaded != nil || groupedErrorCode(t, err) != test.wantCode {
+					t.Fatalf("version claim result = %#v, %v", loaded, err)
+				}
+				return
+			}
+			if err != nil {
+				t.Fatalf("nonclaiming imported mapping ancestor was rejected: %v", err)
+			}
+			result := testLoaded(loaded)
+			if got := layeredMapValue(t, result.Config, "app", "schema", "name"); got != "ordinary" {
+				t.Fatalf("nested ordinary value = %#v", got)
+			}
+		})
+	}
+}
+
+func layeredMap(t *testing.T, value map[string]any, key string) map[string]any {
+	t.Helper()
+	result, ok := value[key].(map[string]any)
+	if !ok {
+		t.Fatalf("%q = %#v, want mapping", key, value[key])
+	}
+	return result
+}
+
+func layeredMapValue(t *testing.T, value map[string]any, keys ...string) any {
+	t.Helper()
+	for _, key := range keys[:len(keys)-1] {
+		value = layeredMap(t, value, key)
+	}
+	return value[keys[len(keys)-1]]
+}

internal/engine/diagnostic.go

@@ -63,8 +63,9 @@ func WriteDiagnostics(output io.Writer, diagnostics []Diagnostic) error {
 }
 
 type diagnosticAccumulator struct {
-	diagnostics []Diagnostic
+	diagnostics  []Diagnostic
-	sources     []SourceInfo
+	sources      []SourceInfo
+	versionState *sourceVersionState
 }
 
 func (a *diagnosticAccumulator) add(diagnostics ...Diagnostic) {
@@ -74,9 +75,13 @@ func (a *diagnosticAccumulator) add(diagnostics ...Diagnostic) {
 }
 
 func (a *diagnosticAccumulator) loadError() *LoadError {
+	sources := a.sources
+	if a.versionState != nil {
+		sources = sourceInfosWithVersionEvidence(sources, a.versionState.evidence, nil, true)
+	}
 	return &LoadError{
 		diagnostics: canonicalDiagnostics(a.diagnostics),
-		sources:     cloneSourceInfos(a.sources),
+		sources:     cloneSourceInfos(sources),
 	}
 }
 
@@ -85,15 +90,28 @@ func canonicalDiagnostics(diagnostics []Diagnostic) []Diagnostic {
 	for i := range canonical {
 		slices.SortFunc(canonical[i].Related, compareLocation)
 	}
-	slices.SortFunc(canonical, compareDiagnostic)
+	type orderedDiagnostic struct {
+		diagnostic Diagnostic
+		pointer    string
+	}
+	ordered := make([]orderedDiagnostic, len(canonical))
+	for i, diagnostic := range canonical {
+		ordered[i] = orderedDiagnostic{diagnostic: diagnostic, pointer: diagnostic.Path.String()}
+	}
+	slices.SortFunc(ordered, func(left, right orderedDiagnostic) int {
+		return compareDiagnosticWithPaths(left.diagnostic, right.diagnostic, left.pointer, right.pointer)
+	})
+	for i, item := range ordered {
+		canonical[i] = item.diagnostic
+	}
 	return canonical
 }
 
-func compareDiagnostic(left, right Diagnostic) int {
+func compareDiagnosticWithPaths(left, right Diagnostic, leftPath, rightPath string) int {
 	if order := compareOptionalLocation(left.Primary, right.Primary); order != 0 {
 		return order
 	}
-	if order := cmp.Compare(left.Path.String(), right.Path.String()); order != 0 {
+	if order := cmp.Compare(leftPath, rightPath); order != 0 {
 		return order
 	}
 	if order := cmp.Compare(left.Code, right.Code); order != 0 {

internal/engine/diagnostic_test.go

@@ -90,6 +90,26 @@ func TestDiagnosticsAreCanonicalAndDetached(t *testing.T) {
 	}
 }
 
+func TestCanonicalDiagnosticsSortEscapedPaths(t *testing.T) {
+	primary := &Location{SourceID: "source-1", Line: 1, Column: 1}
+	diagnostics := []Diagnostic{
+		{Code: "same", Severity: SeverityError, Path: Keys("a/b"), Message: "same", Primary: primary},
+		{Code: "same", Severity: SeverityError, Path: Keys("a~b"), Message: "same", Primary: primary},
+		{Code: "z", Severity: SeverityError, Path: Keys("same"), Message: "same", Primary: primary},
+		{Code: "a", Severity: SeverityError, Path: Keys("same"), Message: "same", Primary: primary},
+	}
+	canonical := canonicalDiagnostics(diagnostics)
+	want := []string{"/a~0b", "/a~1b", "/same", "/same"}
+	for i, diagnostic := range canonical {
+		if got := diagnostic.Path.String(); got != want[i] {
+			t.Fatalf("diagnostic[%d] path = %q, want %q", i, got, want[i])
+		}
+	}
+	if canonical[2].Code != "a" || canonical[3].Code != "z" {
+		t.Fatalf("same-path code order = %q, %q", canonical[2].Code, canonical[3].Code)
+	}
+}
+
 func TestWriteDiagnosticsEscapesControls(t *testing.T) {
 	t.Parallel()
 

internal/engine/diff.go

@@ -0,0 +1,98 @@
+package engine
+
+import (
+	"bytes"
+	"errors"
+	"io"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+	yamladapter "gitea.maximumdirect.net/eric/ConfigKit/internal/yaml"
+)
+
+var errDiffInspectionUnavailable = errors.New("configkit: diff inspection unavailable")
+var errDiffSnapshotUnavailable = errors.New("configkit: diff snapshot unavailable")
+
+// Difference describes one canonical changed region with safe snapshots.
+type Difference struct {
+	Path          Path
+	Left          ValueSnapshot
+	Right         ValueSnapshot
+	HiddenChanged bool
+}
+
+type diffRegion struct {
+	path  Path
+	left  *document.Node
+	right *document.Node
+}
+
+func prepareDiffRegions(left, right *Inspection) ([]diffRegion, error) {
+	if left == nil || left.final == nil || right == nil || right.final == nil {
+		return nil, errDiffInspectionUnavailable
+	}
+
+	deltas := compareConfigurationValues(left.final, right.final)
+	regions := make([]diffRegion, 0, len(deltas))
+	for _, delta := range deltas {
+		leftNode, leftPresent := documentAtPathWithLookup(left.final, delta.path, left.immutableLookup)
+		if !leftPresent {
+			leftNode = nil
+		}
+		rightNode, rightPresent := documentAtPathWithLookup(right.final, delta.path, right.immutableLookup)
+		if !rightPresent {
+			rightNode = nil
+		}
+		regions = append(regions, diffRegion{path: delta.path, left: leftNode, right: rightNode})
+	}
+	return regions, nil
+}
+
+// Diff compares the final frozen values retained by two successful inspections.
+// Values are serialized only after applying the combined sensitivity of both loads.
+func Diff(left, right *Inspection) ([]Difference, error) {
+	regions, err := prepareDiffRegions(left, right)
+	if err != nil {
+		return nil, err
+	}
+	sensitivity := newDiffSensitivity(left.secrets, right.secrets)
+	differences := make([]Difference, 0, len(regions))
+	for _, region := range regions {
+		paired, supported := preparePairedDiffSnapshot(region.left, region.right, region.path, sensitivity)
+		if !supported {
+			return nil, errDiffSnapshotUnavailable
+		}
+		leftSnapshot, err := serializeDiffSnapshot(paired.left, paired.leftRedacted)
+		if err != nil {
+			return nil, errDiffSnapshotUnavailable
+		}
+		rightSnapshot, err := serializeDiffSnapshot(paired.right, paired.rightRedacted)
+		if err != nil {
+			return nil, errDiffSnapshotUnavailable
+		}
+		differences = append(differences, Difference{
+			Path:          region.path,
+			Left:          leftSnapshot,
+			Right:         rightSnapshot,
+			HiddenChanged: paired.hiddenChanged,
+		})
+	}
+	return differences, nil
+}
+
+func serializeDiffSnapshot(node *document.Node, redacted bool) (ValueSnapshot, error) {
+	if node == nil {
+		return ValueSnapshot{}, nil
+	}
+	var output bytes.Buffer
+	if err := writeDiffDocument(&output, node); err != nil {
+		return ValueSnapshot{}, errDiffSnapshotUnavailable
+	}
+	return ValueSnapshot{Present: true, Redacted: redacted, YAML: output.String()}, nil
+}
+
+func writeDiffDocument(output io.Writer, node *document.Node) error {
+	if err := yamladapter.Write(output, node); err != nil {
+		return errDiffSnapshotUnavailable
+	}
+	return nil
+}

internal/engine/diff_hidden_test.go

@@ -0,0 +1,130 @@
+package engine
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestPreparePairedDiffSnapshotReportsWhollyMaskedChanges(t *testing.T) {
+	left := &document.Node{Kind: document.String, Text: "private-before"}
+	right := &document.Node{Kind: document.String, Text: "private-after"}
+	paired, supported := preparePairedDiffSnapshot(
+		left, right, Keys("credential"), newDiffSensitivity(nil, map[string]bool{"/credential": true}),
+	)
+	if !supported || !paired.hiddenChanged || !paired.leftRedacted || !paired.rightRedacted {
+		t.Fatalf("masked change = %#v, supported=%v", paired, supported)
+	}
+	assertDiffStringNode(t, paired.left, "[REDACTED]")
+	assertDiffStringNode(t, paired.right, "[REDACTED]")
+}
+
+func TestPreparePairedDiffSnapshotDetectsRawChangesBehindIdenticalMarkers(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "token: old-canary\n")
+	right := parseCompositionDocument(t, "right", "token: new-canary\n")
+	paired, supported := preparePairedDiffSnapshot(
+		mappingValue(t, left, "token"), mappingValue(t, right, "token"), Keys("token"),
+		newDiffSensitivity(map[string]bool{"/token": true}, nil),
+	)
+	if !supported || !paired.hiddenChanged || paired.left.Text != paired.right.Text {
+		t.Fatalf("identically rendered masked values lost raw change: %#v, supported=%v", paired, supported)
+	}
+}
+
+func TestPreparePairedDiffSnapshotCombinesPublicAndHiddenChanges(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "public: before\ntoken: old\n")
+	right := parseCompositionDocument(t, "right", "public: after\ntoken: new\n")
+	paired, supported := preparePairedDiffSnapshot(
+		left, right, Path{}, newDiffSensitivity(nil, map[string]bool{"/token": true}),
+	)
+	if !supported || !paired.hiddenChanged {
+		t.Fatalf("mixed public and hidden change = %#v, supported=%v", paired, supported)
+	}
+	assertDiffStringNode(t, mappingValue(t, paired.left, "public"), "before")
+	assertDiffStringNode(t, mappingValue(t, paired.right, "public"), "after")
+	assertDiffStringNode(t, mappingValue(t, paired.left, "token"), "[REDACTED]")
+	assertDiffStringNode(t, mappingValue(t, paired.right, "token"), "[REDACTED]")
+}
+
+func TestPreparePairedDiffSnapshotDoesNotFlagUnchangedMaskedValues(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "public: before\ntoken: unchanged\n")
+	right := parseCompositionDocument(t, "right", "public: after\ntoken: unchanged\n")
+	regions, err := prepareDiffRegions(diffTestInspection(left), diffTestInspection(right))
+	if err != nil || len(regions) != 1 || regions[0].path.String() != "/public" {
+		t.Fatalf("changed regions = %#v, err = %v; want only /public", regions, err)
+	}
+	paired, supported := preparePairedDiffSnapshot(
+		left, right, Path{}, newDiffSensitivity(map[string]bool{"/token": true}, nil),
+	)
+	if !supported || !paired.leftRedacted || !paired.rightRedacted || paired.hiddenChanged {
+		t.Fatalf("unchanged masked values affected hidden-change state: %#v, supported=%v", paired, supported)
+	}
+
+	leftSequence := parseCompositionDocument(t, "left-sequence", "items: [unchanged, before]\n")
+	rightSequence := parseCompositionDocument(t, "right-sequence", "items: [unchanged, after]\n")
+	sequence, supported := preparePairedDiffSnapshot(
+		mappingValue(t, leftSequence, "items"), mappingValue(t, rightSequence, "items"), Keys("items"),
+		newDiffSensitivity(nil, map[string]bool{"/items/0": true}),
+	)
+	if !supported || !sequence.leftRedacted || !sequence.rightRedacted || sequence.hiddenChanged {
+		t.Fatalf("unchanged masked sequence member affected hidden-change state: %#v, supported=%v", sequence, supported)
+	}
+}
+
+func TestPreparePairedDiffSnapshotReportsMaskedAdditionAndRemoval(t *testing.T) {
+	value := &document.Node{Kind: document.String, Text: "private"}
+	tests := []struct {
+		name        string
+		left, right *document.Node
+		leftHidden  bool
+		rightHidden bool
+	}{
+		{name: "addition", right: value, rightHidden: true},
+		{name: "removal", left: value, leftHidden: true},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			paired, supported := preparePairedDiffSnapshot(
+				test.left, test.right, Keys("token"), newDiffSensitivity(nil, map[string]bool{"/token": true}),
+			)
+			if !supported || !paired.hiddenChanged || paired.leftRedacted != test.leftHidden || paired.rightRedacted != test.rightHidden {
+				t.Fatalf("masked presence change = %#v, supported=%v", paired, supported)
+			}
+			if test.left == nil && paired.left != nil || test.right == nil && paired.right != nil {
+				t.Fatalf("absence became a value: %#v", paired)
+			}
+		})
+	}
+}
+
+func TestPreparePairedDiffSnapshotReportsHiddenSequenceLengthChange(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "items: [public]\n")
+	right := parseCompositionDocument(t, "right", "items: [public, private]\n")
+	paired, supported := preparePairedDiffSnapshot(
+		mappingValue(t, left, "items"), mappingValue(t, right, "items"), Keys("items"),
+		newDiffSensitivity(nil, map[string]bool{"/items/1": true}),
+	)
+	if !supported || !paired.hiddenChanged || paired.leftRedacted || !paired.rightRedacted {
+		t.Fatalf("masked sequence length change = %#v, supported=%v", paired, supported)
+	}
+	if len(paired.left.Sequence) != 1 || len(paired.right.Sequence) != 2 {
+		t.Fatalf("safe sequence lengths = %d, %d; want 1, 2", len(paired.left.Sequence), len(paired.right.Sequence))
+	}
+	assertDiffStringNode(t, paired.right.Sequence[1], "[REDACTED]")
+}
+
+func TestPreparePairedDiffSnapshotClassificationAloneDoesNotCreateHiddenChange(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "token: same\n")
+	right := parseCompositionDocument(t, "right", "token: same\n")
+	regions, err := prepareDiffRegions(diffTestInspection(left), diffTestInspection(right))
+	if err != nil || len(regions) != 0 {
+		t.Fatalf("classification-independent changed regions = %#v, err = %v", regions, err)
+	}
+	paired, supported := preparePairedDiffSnapshot(
+		mappingValue(t, left, "token"), mappingValue(t, right, "token"), Keys("token"),
+		newDiffSensitivity(map[string]bool{"/token": true}, nil),
+	)
+	if !supported || !paired.leftRedacted || !paired.rightRedacted || paired.hiddenChanged {
+		t.Fatalf("classification alone reported hidden change: %#v, supported=%v", paired, supported)
+	}
+}

internal/engine/diff_operation_test.go

@@ -0,0 +1,282 @@
+package engine
+
+import (
+	"bytes"
+	"errors"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type diffIntegrationConfig struct {
+	Defaulted  string         `yaml:"defaulted"`
+	Dynamic    map[string]any `yaml:"dynamic"`
+	Credential Secret         `yaml:"credential" configkit:"secret"`
+	Derived    string         `yaml:"derived"`
+}
+
+type diffOptionalSecretConfig struct {
+	Optional *Secret `yaml:"optional" configkit:"secret"`
+}
+
+func TestDiffUsesFinalValuesAndDependencyDerivedSensitivity(t *testing.T) {
+	var resolveCalls int
+	options := Options[diffIntegrationConfig]{Definition: Definition[diffIntegrationConfig]{
+		Defaults: func() diffIntegrationConfig {
+			return diffIntegrationConfig{Defaulted: "from-default", Dynamic: map[string]any{"defaulted": "retained"}}
+		},
+		Resolve: func(configuration *diffIntegrationConfig, resolution *Resolution) error {
+			resolveCalls++
+			configuration.Derived = configuration.Dynamic["visible"].(string)
+			resolution.Record(Keys("derived"), ChangeNormalization, "derive from effective values", Keys("credential"))
+			return nil
+		},
+	}}
+	input := func(value string) Source {
+		return Bytes("effective.yml", []byte("dynamic: {visible: "+value+"}\ncredential: DIFF_ENGINE_SECRET\n"))
+	}
+	t.Setenv("DIFF_ENGINE_SECRET", "credential-left-canary")
+	left, err := testLoad(input("before"), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("DIFF_ENGINE_SECRET", "credential-right-canary")
+	right, err := testLoad(input("after"), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if left.Config.Defaulted != "from-default" || right.Config.Defaulted != "from-default" {
+		t.Fatalf("defaulted values = %q, %q", left.Config.Defaulted, right.Config.Defaulted)
+	}
+	if !left.Inspection.secrets["/credential"] || !left.Inspection.secrets["/derived"] ||
+		!right.Inspection.secrets["/credential"] || !right.Inspection.secrets["/derived"] {
+		t.Fatalf("typed or dependency-derived sensitivity was not retained: left=%#v right=%#v", left.Inspection.secrets, right.Inspection.secrets)
+	}
+	if node, present := documentAtPathWithLookup(left.Inspection.final, Keys("derived"), left.Inspection.immutableLookup); !present || node.Text != "before" {
+		t.Fatalf("left frozen derived value = %#v, present=%v", node, present)
+	}
+
+	differences, err := Diff(left.Inspection, right.Inspection)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(differences) != 2 || differences[0].Path.String() != "/derived" || differences[1].Path.String() != "/dynamic/visible" {
+		t.Fatalf("differences = %#v", differences)
+	}
+	if !differences[0].Left.Redacted || !differences[0].Right.Redacted || !differences[0].HiddenChanged ||
+		differences[0].Left.YAML != "'[REDACTED]'\n" || differences[0].Right.YAML != "'[REDACTED]'\n" {
+		t.Fatalf("dependency-derived difference = %#v", differences[0])
+	}
+	if differences[1].Left.Redacted || differences[1].Right.Redacted || differences[1].HiddenChanged ||
+		differences[1].Left.YAML != "before\n" || differences[1].Right.YAML != "after\n" {
+		t.Fatalf("public dynamic difference = %#v", differences[1])
+	}
+	for _, value := range differences {
+		if strings.Contains(value.Left.YAML+value.Right.YAML, "credential-") {
+			t.Fatal("diff snapshot exposed a resolved credential")
+		}
+	}
+
+	var effective bytes.Buffer
+	if err := left.Inspection.WriteEffective(&effective); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(effective.String(), "credential-left-canary") {
+		t.Fatal("standalone effective rendering exposed a credential after diff")
+	}
+	explanation, ok := left.Inspection.Explain(Keys("derived"))
+	if !ok || !explanation.Effective.Redacted || explanation.Effective.YAML != "'[REDACTED]'\n" {
+		t.Fatalf("explanation changed after diff: %#v, ok=%v", explanation, ok)
+	}
+	if _, ok := left.Inspection.Metadata().Lookup(Keys("dynamic", "visible")); !ok {
+		t.Fatal("metadata lookup failed after diff")
+	}
+	if resolveCalls != 2 {
+		t.Fatalf("resolution callbacks ran during diff: %d calls", resolveCalls)
+	}
+
+	// Returned records can be modified without affecting a later comparison.
+	differences[0].Path.segments[0].key = "changed-by-caller"
+	differences[0].Left.YAML = "changed-by-caller"
+	t.Setenv("DIFF_ENGINE_SECRET", "credential-after-load-canary")
+	repeated, err := Diff(left.Inspection, right.Inspection)
+	if err != nil || len(repeated) != 2 || repeated[0].Path.String() != "/derived" || repeated[0].Left.YAML != "'[REDACTED]'\n" {
+		t.Fatalf("repeated diff = %#v, err = %v", repeated, err)
+	}
+	if resolveCalls != 2 {
+		t.Fatalf("repeated diff reran resolution: %d calls", resolveCalls)
+	}
+
+	independent, err := testLoad(input("before"), options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resolveCalls != 3 {
+		t.Fatalf("independent load did not retain normal resolution behavior: %d calls", resolveCalls)
+	}
+	if _, err := Diff(left.Inspection, independent.Inspection); err != nil {
+		t.Fatalf("independent load comparison = %v", err)
+	}
+}
+
+func TestDiffUsesReferenceNamesAndFrozenSecretState(t *testing.T) {
+	loadReference := func(name string) *testResult[diffOptionalSecretConfig] {
+		t.Helper()
+		result, err := testLoad[diffOptionalSecretConfig](Bytes("secret-reference.yml", []byte("optional: "+name+"\n")))
+		if err != nil {
+			t.Fatal(err)
+		}
+		return result
+	}
+	t.Setenv("DIFF_ROTATING_SECRET", "first-credential-canary")
+	left := loadReference("DIFF_ROTATING_SECRET")
+	t.Setenv("DIFF_ROTATING_SECRET", "second-credential-canary")
+	right := loadReference("DIFF_ROTATING_SECRET")
+	t.Setenv("DIFF_ROTATING_SECRET", "changed-after-load-canary")
+	differences, err := Diff(left.Inspection, right.Inspection)
+	if err != nil || len(differences) != 0 {
+		t.Fatalf("credential rotation behind one reference = %#v, err = %v", differences, err)
+	}
+	if node, present := documentAtPathWithLookup(left.Inspection.final, Keys("optional"), left.Inspection.immutableLookup); !present || node.Text != "DIFF_ROTATING_SECRET" {
+		t.Fatalf("frozen reference = %#v, present=%v", node, present)
+	}
+	if node, present := documentAtPathWithLookup(right.Inspection.final, Keys("optional"), right.Inspection.immutableLookup); !present || node.Text != "DIFF_ROTATING_SECRET" {
+		t.Fatalf("right frozen reference = %#v, present=%v", node, present)
+	}
+
+	t.Setenv("DIFF_OTHER_SECRET", "other-credential-canary")
+	other := loadReference("DIFF_OTHER_SECRET")
+	differences, err = Diff(left.Inspection, other.Inspection)
+	if err != nil || len(differences) != 1 || differences[0].Path.String() != "/optional" {
+		t.Fatalf("reference-name change = %#v, err = %v", differences, err)
+	}
+	if !differences[0].Left.Present || !differences[0].Right.Present || !differences[0].Left.Redacted ||
+		!differences[0].Right.Redacted || !differences[0].HiddenChanged ||
+		differences[0].Left.YAML != "'[REDACTED]'\n" || differences[0].Right.YAML != "'[REDACTED]'\n" {
+		t.Fatalf("classified reference-name diff = %#v", differences[0])
+	}
+
+	absent, err := testLoad[diffOptionalSecretConfig](Bytes("absent-secret.yml", []byte("{}\n")))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if absent.Config.Optional != nil {
+		t.Fatalf("missing optional reference decoded as %#v", absent.Config.Optional)
+	}
+	if node, present := documentAtPathWithLookup(absent.Inspection.final, Keys("optional"), absent.Inspection.immutableLookup); !present || node.Kind != document.Null {
+		t.Fatalf("optional nil projection = %#v, present=%v", node, present)
+	}
+	differences, err = Diff(absent.Inspection, left.Inspection)
+	if err != nil || len(differences) != 1 || differences[0].Path.String() != "/optional" {
+		t.Fatalf("optional absence diff = %#v, err = %v", differences, err)
+	}
+	if !differences[0].Left.Present || !differences[0].Left.Redacted ||
+		!differences[0].Right.Present || !differences[0].Right.Redacted || !differences[0].HiddenChanged {
+		t.Fatalf("optional reference change snapshots = %#v", differences[0])
+	}
+	for _, value := range differences {
+		if strings.Contains(value.Left.YAML+value.Right.YAML, "credential-canary") {
+			t.Fatal("reference diff exposed a resolved credential")
+		}
+	}
+}
+
+func TestDiffProtectsHistoricalSensitiveRemovalAndReplacement(t *testing.T) {
+	type configuration struct {
+		Dynamic map[string]any `yaml:"dynamic"`
+	}
+	secretPath := Keys("dynamic", "token")
+	secretSelector := func(path Path) bool { return path.String() == secretPath.String() }
+	load := func(input string, resolve func(*configuration, *Resolution) error) *testResult[configuration] {
+		t.Helper()
+		result, err := testLoad(Bytes("historical-secret.yml", []byte(input)), Options[configuration]{Definition: Definition[configuration]{
+			Secret:  secretSelector,
+			Resolve: resolve,
+		}})
+		if err != nil {
+			t.Fatal(err)
+		}
+		return result
+	}
+
+	t.Run("removed historical value", func(t *testing.T) {
+		left := load("dynamic: {token: removed-canary}\n", func(configuration *configuration, resolution *Resolution) error {
+			delete(configuration.Dynamic, "token")
+			resolution.Record(secretPath, ChangeNormalization, "remove token")
+			return nil
+		})
+		right := load("dynamic: {token: current-canary}\n", nil)
+		if !left.Inspection.secrets[secretPath.String()] {
+			t.Fatal("removed historical selector was not retained")
+		}
+		if _, present := documentAtPathWithLookup(left.Inspection.final, secretPath, left.Inspection.immutableLookup); present {
+			t.Fatal("removed token remains in the effective left tree")
+		}
+		differences, err := Diff(left.Inspection, right.Inspection)
+		if err != nil || len(differences) != 1 || differences[0].Path.String() != secretPath.String() {
+			t.Fatalf("historical removal diff = %#v, err = %v", differences, err)
+		}
+		if differences[0].Left.Present || !differences[0].Right.Present || !differences[0].Right.Redacted || !differences[0].HiddenChanged {
+			t.Fatalf("historical removal snapshots = %#v", differences[0])
+		}
+		if strings.Contains(differences[0].Left.YAML+differences[0].Right.YAML, "canary") {
+			t.Fatal("historical removal diff exposed a sensitive value")
+		}
+	})
+
+	t.Run("replaced historical value", func(t *testing.T) {
+		left := load("dynamic: {token: original-canary}\n", func(configuration *configuration, resolution *Resolution) error {
+			configuration.Dynamic["token"] = "replacement-canary"
+			resolution.Record(secretPath, ChangeNormalization, "replace token")
+			return nil
+		})
+		right := load("dynamic: {token: other-canary}\n", nil)
+		if !left.Inspection.secrets[secretPath.String()] {
+			t.Fatal("replaced historical selector was not retained")
+		}
+		differences, err := Diff(left.Inspection, right.Inspection)
+		if err != nil || len(differences) != 1 || differences[0].Path.String() != secretPath.String() {
+			t.Fatalf("historical replacement diff = %#v, err = %v", differences, err)
+		}
+		if !differences[0].Left.Present || !differences[0].Right.Present || !differences[0].Left.Redacted ||
+			!differences[0].Right.Redacted || !differences[0].HiddenChanged {
+			t.Fatalf("historical replacement snapshots = %#v", differences[0])
+		}
+		if strings.Contains(differences[0].Left.YAML+differences[0].Right.YAML, "canary") {
+			t.Fatal("historical replacement diff exposed a sensitive value")
+		}
+	})
+}
+
+func TestDiffReturnsSafeErrorsWithoutRecords(t *testing.T) {
+	valid := diffTestInspection(&document.Node{Kind: document.String, Text: "safe"})
+	for _, test := range []struct {
+		name        string
+		left, right *Inspection
+	}{
+		{name: "nil left", right: valid},
+		{name: "nil right", left: valid},
+		{name: "missing final tree", left: &Inspection{}, right: valid},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			differences, err := Diff(test.left, test.right)
+			if differences != nil || err == nil || err != errDiffInspectionUnavailable || strings.Contains(err.Error(), "safe") {
+				t.Fatalf("differences, err = %#v, %v", differences, err)
+			}
+		})
+	}
+}
+
+func TestDiffSerializationErrorDoesNotExposeWriterDetails(t *testing.T) {
+	err := writeDiffDocument(diffErrorWriter{}, &document.Node{Kind: document.String, Text: "safe"})
+	if err != errDiffSnapshotUnavailable || strings.Contains(err.Error(), "CANARY") {
+		t.Fatalf("serialization error = %v", err)
+	}
+}
+
+type diffErrorWriter struct{}
+
+func (diffErrorWriter) Write([]byte) (int, error) {
+	return 0, errors.New("CANARY_WRITER_ERROR")
+}

internal/engine/diff_sensitivity.go

@@ -0,0 +1,48 @@
+package engine
+
+type diffSensitivity struct {
+	prefixes pathPrefixIndex
+	pointers []string
+}
+
+func newDiffSensitivity(left, right map[string]bool) *diffSensitivity {
+	sensitivity := &diffSensitivity{}
+	seen := make(map[string]struct{}, len(left)+len(right))
+	for _, classifications := range []map[string]bool{left, right} {
+		for pointer, classified := range classifications {
+			if !classified {
+				continue
+			}
+			if _, found := seen[pointer]; found {
+				continue
+			}
+			seen[pointer] = struct{}{}
+			id := len(sensitivity.pointers)
+			sensitivity.pointers = append(sensitivity.pointers, pointer)
+			sensitivity.prefixes.insert(pointer, id)
+		}
+	}
+	return sensitivity
+}
+
+func (sensitivity *diffSensitivity) isSensitiveAtOrAbove(pointer string) bool {
+	if sensitivity == nil {
+		return false
+	}
+	found := false
+	sensitivity.prefixes.visitAncestors(pointer, func(int) { found = true })
+	return found
+}
+
+func (sensitivity *diffSensitivity) hasStrictDescendant(pointer string) bool {
+	if sensitivity == nil {
+		return false
+	}
+	found := false
+	sensitivity.prefixes.visitDescendants(pointer, func(id int) {
+		if sensitivity.pointers[id] != pointer {
+			found = true
+		}
+	})
+	return found
+}

internal/engine/diff_sensitivity_test.go

@@ -0,0 +1,90 @@
+package engine
+
+import (
+	"maps"
+	"testing"
+)
+
+func TestDiffSensitivityCombinesClassificationsWithoutMutation(t *testing.T) {
+	left := map[string]bool{
+		"/a":                  true,
+		"/a/b":                true,
+		"/historical/removed": true,
+		"/cross~1key":         true,
+		"/literal~01slash":    true,
+		"/items/01":           true,
+		"/items/+1":           false,
+		"/false-left":         false,
+	}
+	right := map[string]bool{
+		"/a/b":         true,
+		"/right-only":  true,
+		"/false-right": false,
+	}
+	leftBefore, rightBefore := maps.Clone(left), maps.Clone(right)
+	sensitivity := newDiffSensitivity(left, right)
+
+	for _, test := range []struct {
+		pointer string
+		want    bool
+	}{
+		{pointer: "/a", want: true},
+		{pointer: "/a/b", want: true},
+		{pointer: "/a/b/c", want: true},
+		{pointer: "/ab", want: false},
+		{pointer: "/ab/c", want: false},
+		{pointer: "/historical/removed", want: true},
+		{pointer: "/historical/removed/child", want: true},
+		{pointer: "/historical", want: false},
+		{pointer: "/right-only", want: true},
+		{pointer: "/false-left", want: false},
+		{pointer: "/false-right", want: false},
+		{pointer: "/cross~1key", want: true},
+		{pointer: "/cross/key", want: false},
+		{pointer: "/literal~01slash", want: true},
+		{pointer: "/literal~1slash", want: false},
+		{pointer: "/items/01", want: true},
+		{pointer: "/items/1", want: false},
+		{pointer: "/items/+1", want: false},
+	} {
+		if got := sensitivity.isSensitiveAtOrAbove(test.pointer); got != test.want {
+			t.Errorf("isSensitiveAtOrAbove(%q) = %v, want %v", test.pointer, got, test.want)
+		}
+	}
+
+	for _, test := range []struct {
+		pointer string
+		want    bool
+	}{
+		{pointer: "", want: true},
+		{pointer: "/a", want: true},
+		{pointer: "/a/b", want: false},
+		{pointer: "/ab", want: false},
+		{pointer: "/historical", want: true},
+		{pointer: "/right-only", want: false},
+		{pointer: "/cross~1key", want: false},
+	} {
+		if got := sensitivity.hasStrictDescendant(test.pointer); got != test.want {
+			t.Errorf("hasStrictDescendant(%q) = %v, want %v", test.pointer, got, test.want)
+		}
+	}
+
+	if !maps.Equal(left, leftBefore) || !maps.Equal(right, rightBefore) {
+		t.Fatal("classification maps were modified")
+	}
+}
+
+func TestDiffSensitivityDistinguishesRootAndEmptyKey(t *testing.T) {
+	root := newDiffSensitivity(map[string]bool{"": true}, nil)
+	if !root.isSensitiveAtOrAbove("") || !root.isSensitiveAtOrAbove("/empty") ||
+		root.hasStrictDescendant("") {
+		t.Fatal("root classification did not remain distinct from strict descendants")
+	}
+
+	emptyKey := newDiffSensitivity(map[string]bool{"/": true}, nil)
+	if emptyKey.isSensitiveAtOrAbove("") || !emptyKey.isSensitiveAtOrAbove("/") ||
+		emptyKey.isSensitiveAtOrAbove("/other") || !emptyKey.hasStrictDescendant("") ||
+		emptyKey.hasStrictDescendant("/") {
+		t.Fatal("empty-key classification was treated as the root or an unrelated path")
+	}
+}

internal/engine/diff_snapshot.go

@@ -0,0 +1,195 @@
+package engine
+
+import (
+	"sort"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type pairedDiffSnapshot struct {
+	left             *document.Node
+	right            *document.Node
+	leftRedacted     bool
+	rightRedacted    bool
+	requiresFallback bool
+	hiddenChanged    bool
+}
+
+func preparePairedDiffSnapshot(left, right *document.Node, path Path, sensitivity *diffSensitivity) (pairedDiffSnapshot, bool) {
+	paired, supported := preparePairedDiffNodes(left, right, path, sensitivity)
+	if !supported || !paired.requiresFallback {
+		return paired, supported
+	}
+	return pairedDiffSnapshot{
+		left:          redactedDiffNode(left),
+		right:         redactedDiffNode(right),
+		leftRedacted:  left != nil,
+		rightRedacted: right != nil,
+		hiddenChanged: true,
+	}, true
+}
+
+func preparePairedDiffNodes(left, right *document.Node, path Path, sensitivity *diffSensitivity) (pairedDiffSnapshot, bool) {
+	if left == nil && right == nil {
+		return pairedDiffSnapshot{}, true
+	}
+	if sensitivity.isSensitiveAtOrAbove(path.String()) {
+		return pairedDiffSnapshot{
+			left:          redactedDiffNode(left),
+			right:         redactedDiffNode(right),
+			leftRedacted:  left != nil,
+			rightRedacted: right != nil,
+			hiddenChanged: !configurationValuesEqual(left, right),
+		}, true
+	}
+	if left != nil && right != nil && left.Kind != right.Kind {
+		if sensitivity.hasStrictDescendant(path.String()) {
+			return pairedDiffSnapshot{requiresFallback: true}, true
+		}
+		return pairedDiffSnapshot{left: left, right: right}, true
+	}
+
+	kind := document.Null
+	if left != nil {
+		kind = left.Kind
+	} else if right != nil {
+		kind = right.Kind
+	}
+	switch kind {
+	case document.Mapping:
+		return preparePairedDiffMapping(left, right, path, sensitivity)
+	case document.Sequence:
+		return preparePairedDiffSequence(left, right, path, sensitivity)
+	default:
+		return pairedDiffSnapshot{left: left, right: right}, true
+	}
+}
+
+func preparePairedDiffMapping(left, right *document.Node, path Path, sensitivity *diffSensitivity) (pairedDiffSnapshot, bool) {
+	leftEntries := diffMappingEntries(left)
+	rightEntries := diffMappingEntries(right)
+	keys := make([]string, 0, len(leftEntries)+len(rightEntries))
+	seen := make(map[string]struct{}, len(leftEntries)+len(rightEntries))
+	for key := range leftEntries {
+		seen[key] = struct{}{}
+		keys = append(keys, key)
+	}
+	for key := range rightEntries {
+		if _, found := seen[key]; found {
+			continue
+		}
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	var leftCopy, rightCopy *document.Node
+	if left != nil {
+		copy := *left
+		copy.Mapping = make([]document.Entry, 0, len(left.Mapping))
+		leftCopy = &copy
+	}
+	if right != nil {
+		copy := *right
+		copy.Mapping = make([]document.Entry, 0, len(right.Mapping))
+		rightCopy = &copy
+	}
+	redacted := pairedDiffSnapshot{}
+	for _, key := range keys {
+		leftEntry, leftPresent := leftEntries[key]
+		rightEntry, rightPresent := rightEntries[key]
+		var leftChild, rightChild *document.Node
+		if leftPresent {
+			leftChild = leftEntry.Value
+		}
+		if rightPresent {
+			rightChild = rightEntry.Value
+		}
+		child, supported := preparePairedDiffNodes(leftChild, rightChild, path.Key(key), sensitivity)
+		if !supported {
+			return pairedDiffSnapshot{}, false
+		}
+		if child.requiresFallback {
+			return pairedDiffSnapshot{requiresFallback: true}, true
+		}
+		if leftPresent {
+			leftEntry.Value = child.left
+			leftCopy.Mapping = append(leftCopy.Mapping, leftEntry)
+		}
+		if rightPresent {
+			rightEntry.Value = child.right
+			rightCopy.Mapping = append(rightCopy.Mapping, rightEntry)
+		}
+		redacted.leftRedacted = redacted.leftRedacted || child.leftRedacted
+		redacted.rightRedacted = redacted.rightRedacted || child.rightRedacted
+		redacted.hiddenChanged = redacted.hiddenChanged || child.hiddenChanged
+	}
+	redacted.left = leftCopy
+	redacted.right = rightCopy
+	return redacted, true
+}
+
+func preparePairedDiffSequence(left, right *document.Node, path Path, sensitivity *diffSensitivity) (pairedDiffSnapshot, bool) {
+	var leftCopy, rightCopy *document.Node
+	if left != nil {
+		copy := *left
+		copy.Sequence = make([]*document.Node, len(left.Sequence))
+		leftCopy = &copy
+	}
+	if right != nil {
+		copy := *right
+		copy.Sequence = make([]*document.Node, len(right.Sequence))
+		rightCopy = &copy
+	}
+	length := 0
+	if left != nil {
+		length = len(left.Sequence)
+	}
+	if right != nil && len(right.Sequence) > length {
+		length = len(right.Sequence)
+	}
+	result := pairedDiffSnapshot{left: leftCopy, right: rightCopy}
+	for index := 0; index < length; index++ {
+		var leftChild, rightChild *document.Node
+		if left != nil && index < len(left.Sequence) {
+			leftChild = left.Sequence[index]
+		}
+		if right != nil && index < len(right.Sequence) {
+			rightChild = right.Sequence[index]
+		}
+		child, supported := preparePairedDiffNodes(leftChild, rightChild, path.Index(index), sensitivity)
+		if !supported {
+			return pairedDiffSnapshot{}, false
+		}
+		if child.requiresFallback {
+			return pairedDiffSnapshot{requiresFallback: true}, true
+		}
+		if left != nil && index < len(left.Sequence) {
+			leftCopy.Sequence[index] = child.left
+		}
+		if right != nil && index < len(right.Sequence) {
+			rightCopy.Sequence[index] = child.right
+		}
+		result.leftRedacted = result.leftRedacted || child.leftRedacted
+		result.rightRedacted = result.rightRedacted || child.rightRedacted
+		result.hiddenChanged = result.hiddenChanged || child.hiddenChanged
+	}
+	return result, true
+}
+
+func diffMappingEntries(node *document.Node) map[string]document.Entry {
+	entries := make(map[string]document.Entry)
+	if node == nil {
+		return entries
+	}
+	for _, entry := range node.Mapping {
+		entries[entry.Key] = entry
+	}
+	return entries
+}
+
+func redactedDiffNode(node *document.Node) *document.Node {
+	if node == nil {
+		return nil
+	}
+	return &document.Node{Kind: document.String, Text: "[REDACTED]"}
+}

internal/engine/diff_snapshot_test.go

@@ -0,0 +1,351 @@
+package engine
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestPreparePairedDiffSnapshotRedactsAlignedMappingFromEitherSide(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "credential: alpha\npublic: before\n")
+	right := parseCompositionDocument(t, "right", "credential: bravo\npublic: after\n")
+	sensitivity := newDiffSensitivity(map[string]bool{"/credential": true}, nil)
+
+	paired, supported := preparePairedDiffSnapshot(left, right, Path{}, sensitivity)
+	if !supported {
+		t.Fatal("compatible mappings were not supported")
+	}
+	if !paired.leftRedacted || !paired.rightRedacted {
+		t.Fatalf("redacted flags = %v, %v; want true on both sides", paired.leftRedacted, paired.rightRedacted)
+	}
+	assertDiffStringNode(t, mappingValue(t, paired.left, "credential"), "[REDACTED]")
+	assertDiffStringNode(t, mappingValue(t, paired.right, "credential"), "[REDACTED]")
+	assertDiffStringNode(t, mappingValue(t, paired.left, "public"), "before")
+	assertDiffStringNode(t, mappingValue(t, paired.right, "public"), "after")
+	assertDiffStringNode(t, mappingValue(t, left, "credential"), "alpha")
+	assertDiffStringNode(t, mappingValue(t, right, "credential"), "bravo")
+	if paired.left == left || paired.right == right || &paired.left.Mapping[0] == &left.Mapping[0] {
+		t.Fatal("safe mapping containers or entries share mutable storage with retained trees")
+	}
+}
+
+func TestPreparePairedDiffSnapshotPreservesSequencePositionsAndLengths(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "items: [left-public, hidden, old-tail]\n")
+	right := parseCompositionDocument(t, "right", "items: [right-public, hidden, old-tail, extra]\n")
+	sensitivity := newDiffSensitivity(nil, map[string]bool{"/items/1": true})
+
+	paired, supported := preparePairedDiffSnapshot(
+		mappingValue(t, left, "items"), mappingValue(t, right, "items"), Keys("items"), sensitivity,
+	)
+	if !supported {
+		t.Fatal("compatible sequences were not supported")
+	}
+	if !paired.leftRedacted || !paired.rightRedacted {
+		t.Fatalf("redacted flags = %v, %v; want true on both sides", paired.leftRedacted, paired.rightRedacted)
+	}
+	if len(paired.left.Sequence) != 3 || len(paired.right.Sequence) != 4 {
+		t.Fatalf("sequence lengths = %d, %d; want 3, 4", len(paired.left.Sequence), len(paired.right.Sequence))
+	}
+	assertDiffStringNode(t, paired.left.Sequence[0], "left-public")
+	assertDiffStringNode(t, paired.right.Sequence[0], "right-public")
+	assertDiffStringNode(t, paired.left.Sequence[1], "[REDACTED]")
+	assertDiffStringNode(t, paired.right.Sequence[1], "[REDACTED]")
+	assertDiffStringNode(t, paired.right.Sequence[3], "extra")
+	assertDiffStringNode(t, mappingValue(t, left, "items").Sequence[1], "hidden")
+	if &paired.left.Sequence[0] == &mappingValue(t, left, "items").Sequence[0] {
+		t.Fatal("safe sequence shares mutable storage with retained tree")
+	}
+}
+
+func TestPreparePairedDiffSnapshotMasksSensitiveDescendantsOfAbsentSubtrees(t *testing.T) {
+	tests := []struct {
+		name        string
+		left, right string
+		absentSide  string
+	}{
+		{
+			name:       "removed subtree",
+			left:       "removed: {token: old-secret, public: retained}\n",
+			right:      "other: value\n",
+			absentSide: "right",
+		},
+		{
+			name:       "added subtree",
+			left:       "other: value\n",
+			right:      "added: {token: new-secret, public: retained}\n",
+			absentSide: "left",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			left := parseCompositionDocument(t, "left", test.left)
+			right := parseCompositionDocument(t, "right", test.right)
+			paired, supported := preparePairedDiffSnapshot(
+				mappingValueIfPresent(left, "removed", "added"),
+				mappingValueIfPresent(right, "removed", "added"),
+				Keys("subtree"),
+				newDiffSensitivity(map[string]bool{"/subtree/token": true}, nil),
+			)
+			if !supported {
+				t.Fatal("compatible subtree and absence were not supported")
+			}
+			if test.absentSide == "left" {
+				if paired.left != nil || paired.leftRedacted || !paired.rightRedacted {
+					t.Fatalf("paired absence/redaction = %#v", paired)
+				}
+				assertDiffStringNode(t, mappingValue(t, paired.right, "token"), "[REDACTED]")
+				assertDiffStringNode(t, mappingValue(t, paired.right, "public"), "retained")
+			} else {
+				if paired.right != nil || paired.rightRedacted || !paired.leftRedacted {
+					t.Fatalf("paired absence/redaction = %#v", paired)
+				}
+				assertDiffStringNode(t, mappingValue(t, paired.left, "token"), "[REDACTED]")
+				assertDiffStringNode(t, mappingValue(t, paired.left, "public"), "retained")
+			}
+		})
+	}
+}
+
+func TestPreparePairedDiffSnapshotMasksSelectedRootAndContainer(t *testing.T) {
+	tests := []struct {
+		name        string
+		left, right *document.Node
+		path        Path
+		selector    string
+	}{
+		{
+			name:     "root",
+			left:     parseCompositionDocument(t, "left", "token: old\n"),
+			right:    parseCompositionDocument(t, "right", "token: new\n"),
+			path:     Path{},
+			selector: "",
+		},
+		{
+			name:     "container",
+			left:     parseCompositionDocument(t, "left", "group: {public: old}\n"),
+			right:    parseCompositionDocument(t, "right", "group: {public: new}\n"),
+			path:     Keys("group"),
+			selector: "/group",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			paired, supported := preparePairedDiffSnapshot(
+				test.left, test.right, test.path,
+				newDiffSensitivity(map[string]bool{test.selector: true}, nil),
+			)
+			if !supported {
+				t.Fatal("selected nodes were not supported")
+			}
+			if !paired.leftRedacted || !paired.rightRedacted {
+				t.Fatalf("redacted flags = %v, %v; want true on both sides", paired.leftRedacted, paired.rightRedacted)
+			}
+			assertDiffStringNode(t, paired.left, "[REDACTED]")
+			assertDiffStringNode(t, paired.right, "[REDACTED]")
+		})
+	}
+}
+
+func TestPreparePairedDiffSnapshotDoesNotInterpretMarkerLookingInput(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "label: '[REDACTED]'\n")
+	right := parseCompositionDocument(t, "right", "label: '[REDACTED]'\n")
+	paired, supported := preparePairedDiffSnapshot(
+		mappingValue(t, left, "label"), mappingValue(t, right, "label"), Keys("label"),
+		newDiffSensitivity(nil, nil),
+	)
+	if !supported {
+		t.Fatal("ordinary scalar values were not supported")
+	}
+	if paired.leftRedacted || paired.rightRedacted {
+		t.Fatalf("redacted flags = %v, %v; want false", paired.leftRedacted, paired.rightRedacted)
+	}
+	if paired.left != mappingValue(t, left, "label") || paired.right != mappingValue(t, right, "label") {
+		t.Fatal("unselected scalar nodes should remain borrowed immutable nodes")
+	}
+	assertDiffStringNode(t, paired.left, "[REDACTED]")
+	assertDiffStringNode(t, paired.right, "[REDACTED]")
+}
+
+func TestPreparePairedDiffSnapshotMasksSensitiveStructuralReplacements(t *testing.T) {
+	tests := []struct {
+		name        string
+		left, right string
+		path        Path
+		selector    string
+	}{
+		{
+			name:     "mapping to scalar",
+			left:     "changed: {token: old-secret, public: old}\n",
+			right:    "changed: new-scalar\n",
+			path:     Keys("changed"),
+			selector: "/changed/token",
+		},
+		{
+			name:     "mapping to scalar with historical-only descendant",
+			left:     "changed: {public: old}\n",
+			right:    "changed: new-scalar\n",
+			path:     Keys("changed"),
+			selector: "/changed/removed/secret",
+		},
+		{
+			name:     "scalar to mapping",
+			left:     "changed: old-scalar\n",
+			right:    "changed: {token: new-secret, public: new}\n",
+			path:     Keys("changed"),
+			selector: "/changed/token",
+		},
+		{
+			name:     "mapping to sequence with numeric paths",
+			left:     "changed: {'0': {token: old-secret}}\n",
+			right:    "changed: [{token: new-secret}]\n",
+			path:     Keys("changed"),
+			selector: "/changed/0/token",
+		},
+		{
+			name:     "sequence to mapping with numeric paths",
+			left:     "changed: [{token: old-secret}]\n",
+			right:    "changed: {'0': {token: new-secret}}\n",
+			path:     Keys("changed"),
+			selector: "/changed/0/token",
+		},
+		{
+			name:     "null to container",
+			left:     "changed: null\n",
+			right:    "changed: {token: new-secret}\n",
+			path:     Keys("changed"),
+			selector: "/changed/token",
+		},
+		{
+			name:     "container to null",
+			left:     "changed: {token: old-secret}\n",
+			right:    "changed: null\n",
+			path:     Keys("changed"),
+			selector: "/changed/token",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			leftRoot := parseCompositionDocument(t, "left", test.left)
+			rightRoot := parseCompositionDocument(t, "right", test.right)
+			left := mappingValue(t, leftRoot, test.path.segments[0].key)
+			right := mappingValue(t, rightRoot, test.path.segments[0].key)
+			paired, supported := preparePairedDiffSnapshot(
+				left, right, test.path, newDiffSensitivity(nil, map[string]bool{test.selector: true}),
+			)
+			assertWholeRegionFallback(t, paired, supported, left, right)
+		})
+	}
+}
+
+func TestPreparePairedDiffSnapshotMasksOriginalRegionForNestedSequenceMismatch(t *testing.T) {
+	leftRoot := parseCompositionDocument(t, "left", "items: [{branch: {token: old-secret, public: old}}]\n")
+	rightRoot := parseCompositionDocument(t, "right", "items: [{branch: new-scalar}]\n")
+	left := mappingValue(t, leftRoot, "items")
+	right := mappingValue(t, rightRoot, "items")
+	paired, supported := preparePairedDiffSnapshot(
+		left, right, Keys("items"), newDiffSensitivity(nil, map[string]bool{"/items/0/branch/token": true}),
+	)
+	assertWholeRegionFallback(t, paired, supported, left, right)
+}
+
+func TestPreparePairedDiffSnapshotKeepsPublicScalarsWithHistoricalDescendants(t *testing.T) {
+	leftRoot := parseCompositionDocument(t, "left", "changed: before\n")
+	rightRoot := parseCompositionDocument(t, "right", "changed: after\n")
+	left := mappingValue(t, leftRoot, "changed")
+	right := mappingValue(t, rightRoot, "changed")
+	paired, supported := preparePairedDiffSnapshot(
+		left, right, Keys("changed"), newDiffSensitivity(map[string]bool{"/changed/removed/secret": true}, nil),
+	)
+	if !supported || paired.leftRedacted || paired.rightRedacted || paired.hiddenChanged {
+		t.Fatalf("public scalar replacement = %#v, supported=%v", paired, supported)
+	}
+	assertDiffStringNode(t, paired.left, "before")
+	assertDiffStringNode(t, paired.right, "after")
+}
+
+func TestPreparePairedDiffSnapshotKeepsPublicContentAcrossAbsence(t *testing.T) {
+	right := parseCompositionDocument(t, "right", "branch: scalar\n")
+	paired, supported := preparePairedDiffSnapshot(
+		nil, right, Keys("added"), newDiffSensitivity(nil, map[string]bool{"/added/branch/secret": true}),
+	)
+	if !supported || paired.left != nil || paired.leftRedacted || paired.rightRedacted || paired.hiddenChanged {
+		t.Fatalf("public addition presence/redaction = %#v, supported=%v", paired, supported)
+	}
+	assertDiffStringNode(t, mappingValue(t, paired.right, "branch"), "scalar")
+}
+
+func TestPreparePairedDiffSnapshotPreservesPublicReplacementBesideSensitiveSibling(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "child: before\n")
+	right := &document.Node{Kind: document.String, Text: "after"}
+	paired, supported := preparePairedDiffSnapshot(
+		mappingValue(t, left, "child"), right, Keys("public"),
+		newDiffSensitivity(nil, map[string]bool{"/private/token": true}),
+	)
+	if !supported || paired.left != mappingValue(t, left, "child") || paired.right != right || paired.leftRedacted || paired.rightRedacted {
+		t.Fatalf("unrelated classification changed public replacement: %#v, supported=%v", paired, supported)
+	}
+}
+
+func TestPreparePairedDiffSnapshotTargetsRedactionAcrossAbsence(t *testing.T) {
+	left := parseCompositionDocument(t, "left", "items: []\n")
+	right := parseCompositionDocument(t, "right", "items: [{token: new-secret, public: visible}]\n")
+	leftItems := mappingValue(t, left, "items")
+	rightItems := mappingValue(t, right, "items")
+	paired, supported := preparePairedDiffSnapshot(
+		leftItems, rightItems, Keys("items"), newDiffSensitivity(nil, map[string]bool{"/items/0/token": true}),
+	)
+	if !supported || paired.left == nil || paired.right == nil || paired.leftRedacted || !paired.rightRedacted {
+		t.Fatalf("targeted sequence redaction = %#v, supported=%v", paired, supported)
+	}
+	if len(paired.left.Sequence) != 0 || len(paired.right.Sequence) != 1 {
+		t.Fatalf("sequence lengths = %d, %d; want 0, 1", len(paired.left.Sequence), len(paired.right.Sequence))
+	}
+	assertDiffStringNode(t, mappingValue(t, paired.right.Sequence[0], "token"), "[REDACTED]")
+	assertDiffStringNode(t, mappingValue(t, paired.right.Sequence[0], "public"), "visible")
+}
+
+func assertWholeRegionFallback(t *testing.T, paired pairedDiffSnapshot, supported bool, left, right *document.Node) {
+	t.Helper()
+	if !supported {
+		t.Fatal("sensitive incompatible shape was not handled")
+	}
+	if !paired.hiddenChanged {
+		t.Fatal("fallback for a changed reported region did not mark hidden change")
+	}
+	if (left == nil) != (paired.left == nil) || (right == nil) != (paired.right == nil) {
+		t.Fatalf("fallback changed root presence: %#v", paired)
+	}
+	if left != nil {
+		assertDiffStringNode(t, paired.left, "[REDACTED]")
+		if !paired.leftRedacted {
+			t.Fatal("present left region was not marked redacted")
+		}
+	}
+	if right != nil {
+		assertDiffStringNode(t, paired.right, "[REDACTED]")
+		if !paired.rightRedacted {
+			t.Fatal("present right region was not marked redacted")
+		}
+	}
+}
+
+func mappingValueIfPresent(node *document.Node, keys ...string) *document.Node {
+	if node == nil {
+		return nil
+	}
+	for _, key := range keys {
+		for _, entry := range node.Mapping {
+			if entry.Key == key {
+				return entry.Value
+			}
+		}
+	}
+	return nil
+}
+
+func assertDiffStringNode(t *testing.T, node *document.Node, want string) {
+	t.Helper()
+	if node == nil || node.Kind != document.String || node.Text != want {
+		t.Fatalf("node = %#v, want string %q", node, want)
+	}
+}

internal/engine/diff_test.go

@@ -0,0 +1,144 @@
+package engine
+
+import (
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestPrepareDiffRegionsUsesCanonicalConfigurationComparison(t *testing.T) {
+	tests := []struct {
+		name  string
+		left  string
+		right string
+		want  []expectedDiffRegion
+	}{
+		{
+			name:  "mapping order is ignored for equal values",
+			left:  "first: 1\nsecond: true\n",
+			right: "second: true\nfirst: 1\n",
+		},
+		{
+			name:  "addition removal null and empty values",
+			left:  "removed: null\n",
+			right: "added: null\nempty_map: {}\nempty_sequence: []\n",
+			want: []expectedDiffRegion{
+				{path: "/added", rightKind: document.Null, rightPresent: true},
+				{path: "/empty_map", rightKind: document.Mapping, rightPresent: true},
+				{path: "/empty_sequence", rightKind: document.Sequence, rightPresent: true},
+				{path: "/removed", leftKind: document.Null, leftPresent: true},
+			},
+		},
+		{
+			name:  "scalar kinds and atomic sequences",
+			left:  "scalar: 1\nitems: [one, two]\n",
+			right: "scalar: '1'\nitems: [one, changed]\n",
+			want: []expectedDiffRegion{
+				{path: "/items", leftKind: document.Sequence, rightKind: document.Sequence, leftPresent: true, rightPresent: true},
+				{path: "/scalar", leftKind: document.Number, rightKind: document.String, leftPresent: true, rightPresent: true},
+			},
+		},
+		{
+			name:  "escaped empty and numeric mapping keys sort by pointer",
+			left:  `"": old` + "\n'0': old\n'01': old\n'a/b': old\n'a~b': old\n",
+			right: `"": new` + "\n'0': new\n'01': new\n'a/b': new\n'a~b': new\n",
+			want: []expectedDiffRegion{
+				{path: "/", leftKind: document.String, rightKind: document.String, leftPresent: true, rightPresent: true},
+				{path: "/0", leftKind: document.String, rightKind: document.String, leftPresent: true, rightPresent: true},
+				{path: "/01", leftKind: document.String, rightKind: document.String, leftPresent: true, rightPresent: true},
+				{path: "/a~0b", leftKind: document.String, rightKind: document.String, leftPresent: true, rightPresent: true},
+				{path: "/a~1b", leftKind: document.String, rightKind: document.String, leftPresent: true, rightPresent: true},
+			},
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			leftRoot := parseCompositionDocument(t, "left", test.left)
+			rightRoot := parseCompositionDocument(t, "right", test.right)
+			regions, err := prepareDiffRegions(diffTestInspection(leftRoot), diffTestInspection(rightRoot))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(regions) != len(test.want) {
+				t.Fatalf("regions = %#v, want %#v", regions, test.want)
+			}
+			for index, want := range test.want {
+				region := regions[index]
+				if region.path.String() != want.path {
+					t.Fatalf("region[%d].path = %q, want %q", index, region.path.String(), want.path)
+				}
+				assertDiffRegionNode(t, "left", region.left, want.leftPresent, want.leftKind)
+				assertDiffRegionNode(t, "right", region.right, want.rightPresent, want.rightKind)
+			}
+		})
+	}
+}
+
+func TestPrepareDiffRegionsHandlesRootReplacementAndBorrowsNodes(t *testing.T) {
+	leftRoot := &document.Node{Kind: document.String, Text: "before"}
+	rightRoot := &document.Node{Kind: document.Mapping, Mapping: []document.Entry{{
+		Key: "value", Value: &document.Node{Kind: document.Number, Text: "1"},
+	}}}
+	regions, err := prepareDiffRegions(diffTestInspection(leftRoot), diffTestInspection(rightRoot))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(regions) != 1 || regions[0].path.String() != "" || regions[0].left != leftRoot || regions[0].right != rightRoot {
+		t.Fatalf("root region = %#v", regions)
+	}
+
+	leftRoot = parseCompositionDocument(t, "left-child", "value: before\n")
+	rightRoot = parseCompositionDocument(t, "right-child", "value: after\n")
+	regions, err = prepareDiffRegions(diffTestInspection(leftRoot), diffTestInspection(rightRoot))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(regions) != 1 || regions[0].left != mappingValue(t, leftRoot, "value") || regions[0].right != mappingValue(t, rightRoot, "value") {
+		t.Fatalf("child nodes were not borrowed from the frozen trees: %#v", regions)
+	}
+}
+
+func TestPrepareDiffRegionsRejectsUnavailableInspections(t *testing.T) {
+	valid := diffTestInspection(&document.Node{Kind: document.String, Text: "safe"})
+	tests := []struct {
+		name        string
+		left, right *Inspection
+	}{
+		{name: "nil left", left: nil, right: valid},
+		{name: "nil right", left: valid, right: nil},
+		{name: "missing left tree", left: &Inspection{}, right: valid},
+		{name: "missing right tree", left: valid, right: &Inspection{}},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			regions, err := prepareDiffRegions(test.left, test.right)
+			if err == nil || regions != nil {
+				t.Fatalf("regions, err = %#v, %v", regions, err)
+			}
+		})
+	}
+}
+
+type expectedDiffRegion struct {
+	path                      string
+	leftKind, rightKind       document.Kind
+	leftPresent, rightPresent bool
+}
+
+func diffTestInspection(root *document.Node) *Inspection {
+	return &Inspection{final: root, immutableLookup: buildDocumentLookup(root)}
+}
+
+func assertDiffRegionNode(t *testing.T, side string, node *document.Node, wantPresent bool, wantKind document.Kind) {
+	t.Helper()
+	if !wantPresent {
+		if node != nil {
+			t.Fatalf("%s node = %#v, want absence", side, node)
+		}
+		return
+	}
+	if node == nil || node.Kind != wantKind {
+		t.Fatalf("%s node = %#v, want kind %v", side, node, wantKind)
+	}
+}

internal/engine/directives.go

@@ -10,10 +10,14 @@ import (
 const directiveKey = "configkit"
 
 type importDeclaration struct {
-	path     string
+	path              string
-	glob     string
+	glob              string
-	optional bool
+	destination       Path
-	location Location
+	placement         placementMode
+	placementPath     Path
+	placementLocation *Location
+	optional          bool
+	location          Location
 }
 
 func splitImportDirectives(root *document.Node) (*document.Node, []importDeclaration, []Diagnostic) {
@@ -69,7 +73,7 @@ func parseImportDeclaration(node *document.Node, declarationPath Path) (importDe
 	if node.Kind != document.Mapping {
 		return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, declarationPath, "import declaration must be a mapping", node)}
 	}
-	declaration := importDeclaration{location: publicLocation(node.Location)}
+	declaration := importDeclaration{location: publicLocation(node.Location), placementPath: declarationPath.clone()}
 	seenTarget := false
 	for _, entry := range node.Mapping {
 		fieldPath := declarationPath.Key(entry.Key)
@@ -90,6 +94,42 @@ func parseImportDeclaration(node *document.Node, declarationPath Path) (importDe
 				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "optional must be a boolean", entry.Value)}
 			}
 			declaration.optional = entry.Value.Text == "true"
+		case "destination":
+			if entry.Value.Kind != document.Sequence {
+				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "destination must be a sequence of strings", entry.Value)}
+			}
+			relative := Path{segments: make([]pathSegment, 0, len(entry.Value.Sequence))}
+			for index, item := range entry.Value.Sequence {
+				memberPath := fieldPath.Index(index)
+				if item.Kind != document.String {
+					return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, memberPath, "destination members must be strings", item)}
+				}
+				member := Path{segments: []pathSegment{{kind: pathSegmentKey, key: item.Text}}}
+				if _, err := normalizeDestination(member); err != nil {
+					return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, memberPath, "destination members must be non-reserved mapping keys", item)}
+				}
+				relative.segments = append(relative.segments, pathSegment{kind: pathSegmentKey, key: item.Text})
+			}
+			normalized, err := normalizeDestination(relative)
+			if err != nil {
+				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "destination must contain only non-reserved mapping keys", entry.Value)}
+			}
+			declaration.destination = normalized
+		case "placement":
+			declaration.placementPath = fieldPath.clone()
+			placementLocation := publicLocation(entry.Value.Location)
+			declaration.placementLocation = &placementLocation
+			if entry.Value.Kind != document.String {
+				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "placement must be mapping or sequence-item", entry.Value)}
+			}
+			switch entry.Value.Text {
+			case "mapping":
+				declaration.placement = placementModeMapping
+			case "sequence-item":
+				declaration.placement = placementModeSequenceItem
+			default:
+				return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "placement must be mapping or sequence-item", entry.Value)}
+			}
 		default:
 			return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "import declaration field is not recognized", entry.Value)}
 		}
@@ -123,26 +163,54 @@ func nestedDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic
 }
 
 func fragmentVersionClaim(root *document.Node, rule *VersionRule) *document.Node {
+	return fragmentVersionClaimProjected(root, rule, -1, nil)
+}
+
+func fragmentVersionClaimProjected(root *document.Node, rule *VersionRule, sourceIndex int, ranges []sequenceRange) *document.Node {
+	return fragmentVersionClaimWithIndex(root, rule, sourceIndex, indexSequenceRanges(ranges))
+}
+
+func fragmentVersionClaimWithIndex(root *document.Node, rule *VersionRule, sourceIndex int, ranges sequenceRangeIndex) *document.Node {
 	if rule == nil {
 		return nil
 	}
 	current := root
+	currentPath := Path{}
 	if len(rule.Path.segments) == 0 {
 		return current
 	}
 	for _, segment := range rule.Path.segments {
-		if current.Kind != document.Mapping {
+		switch current.Kind {
+		case document.Mapping:
+			if segment.kind == pathSegmentIndex {
+				return current
+			}
+			index := documentEntryIndex(current.Mapping, segment.key)
+			if index < 0 {
+				return nil
+			}
+			current = current.Mapping[index].Value
+			currentPath = currentPath.Key(segment.key)
+		case document.Sequence:
+			index, valid := schemaIndex(segment)
+			if !valid {
+				return current
+			}
+			if assigned, found := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: currentPath.String()}]; found {
+				if index < assigned.start || index >= assigned.end {
+					return nil
+				}
+				index -= assigned.start
+			}
+			if index < 0 || index >= len(current.Sequence) {
+				return nil
+			}
+			current = current.Sequence[index]
+			currentPath = currentPath.Index(index)
+		default:
+			// A scalar or null at an ancestor replaces the protected subtree.
 			return current
 		}
-		if segment.kind == pathSegmentIndex {
-			return nil
-		}
-		key := segment.key
-		index := documentEntryIndex(current.Mapping, key)
-		if index < 0 {
-			return nil
-		}
-		current = current.Mapping[index].Value
 	}
 	return current
 }

internal/engine/document_compare.go

@@ -24,12 +24,23 @@ type documentDelta struct {
 func compareConfigurationValues(before, after *document.Node) []documentDelta {
 	var deltas []documentDelta
 	compareConfigurationValue(before, after, Path{}, &deltas)
-	slices.SortFunc(deltas, func(left, right documentDelta) int {
+	type orderedDelta struct {
-		if order := cmp.Compare(left.path.String(), right.path.String()); order != 0 {
+		delta   documentDelta
+		pointer string
+	}
+	ordered := make([]orderedDelta, len(deltas))
+	for i, delta := range deltas {
+		ordered[i] = orderedDelta{delta: delta, pointer: delta.path.String()}
+	}
+	slices.SortFunc(ordered, func(left, right orderedDelta) int {
+		if order := cmp.Compare(left.pointer, right.pointer); order != 0 {
 			return order
 		}
-		return int(left.kind) - int(right.kind)
+		return int(left.delta.kind) - int(right.delta.kind)
 	})
+	for i, item := range ordered {
+		deltas[i] = item.delta
+	}
 	return deltas
 }
 

internal/engine/document_lookup.go

@@ -0,0 +1,54 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// documentLookup contains read-only mapping positions for a completed document.
+type documentLookup struct {
+	byNode map[*document.Node]map[string]int
+}
+
+func buildDocumentLookup(roots ...*document.Node) *documentLookup {
+	lookup := &documentLookup{byNode: make(map[*document.Node]map[string]int)}
+	visited := make(map[*document.Node]struct{})
+	var visit func(*document.Node)
+	visit = func(node *document.Node) {
+		if node == nil {
+			return
+		}
+		if _, ok := visited[node]; ok {
+			return
+		}
+		visited[node] = struct{}{}
+		switch node.Kind {
+		case document.Mapping:
+			entries := make(map[string]int, len(node.Mapping))
+			for index, entry := range node.Mapping {
+				if _, exists := entries[entry.Key]; !exists {
+					entries[entry.Key] = index
+				}
+				visit(entry.Value)
+			}
+			lookup.byNode[node] = entries
+		case document.Sequence:
+			for _, child := range node.Sequence {
+				visit(child)
+			}
+		}
+	}
+	for _, root := range roots {
+		visit(root)
+	}
+	return lookup
+}
+
+func (lookup *documentLookup) find(node *document.Node, key string) int {
+	if lookup == nil {
+		return -1
+	}
+	if entries := lookup.byNode[node]; entries != nil {
+		if index, ok := entries[key]; ok {
+			return index
+		}
+	}
+	return -1
+}

internal/engine/document_walk.go

@@ -31,6 +31,10 @@ func indexDocument(node *document.Node, path Path, index map[string]*document.No
 }
 
 func documentAtPath(root *document.Node, path Path) (*document.Node, bool) {
+	return documentAtPathWithLookup(root, path, nil)
+}
+
+func documentAtPathWithLookup(root *document.Node, path Path, lookup *documentLookup) (*document.Node, bool) {
 	if root == nil || !path.valid() {
 		return nil, false
 	}
@@ -41,17 +45,21 @@ func documentAtPath(root *document.Node, path Path) (*document.Node, bool) {
 			if segment.kind == pathSegmentIndex {
 				return nil, false
 			}
-			found := false
+			entryIndex := -1
-			for _, entry := range current.Mapping {
+			if lookup != nil {
-				if entry.Key == segment.key {
+				entryIndex = lookup.find(current, segment.key)
-					current = entry.Value
+			} else {
-					found = true
+				for index, entry := range current.Mapping {
-					break
+					if entry.Key == segment.key {
+						entryIndex = index
+						break
+					}
 				}
 			}
-			if !found {
+			if entryIndex < 0 || entryIndex >= len(current.Mapping) {
 				return nil, false
 			}
+			current = current.Mapping[entryIndex].Value
 		case document.Sequence:
 			index, ok := schemaIndex(segment)
 			if !ok || index >= len(current.Sequence) {

internal/engine/explain.go

@@ -40,7 +40,7 @@ func (r *Inspection) Explain(path Path) (Explanation, bool) {
 	if r == nil || r.final == nil || r.baseline == nil || !r.metadata.hasHistoricalPath(path) {
 		return Explanation{}, false
 	}
-	explanation := Explanation{Path: path.clone(), Effective: valueSnapshot(r.final, path, r.secrets)}
+	explanation := Explanation{Path: path.clone(), Effective: valueSnapshotWithLookup(r.final, path, r.secrets, r.immutableLookup)}
 	if info, ok := r.metadata.Lookup(path); ok {
 		explanation.Origin = cloneOrigin(info.Origin)
 	}
@@ -53,7 +53,7 @@ func (r *Inspection) Explain(path Path) (Explanation, bool) {
 	}
 	replayIndex := new(mappingIndex)
 	for _, application := range r.applications {
-		operationPath, relevant := applicationOperationPath(application, path)
+		operationPath, relevant := applicationOperationPath(application, path, r.immutableLookup)
 		var before ValueSnapshot
 		if relevant {
 			before = valueSnapshot(working, path, r.secrets)
@@ -69,7 +69,7 @@ func (r *Inspection) Explain(path Path) (Explanation, bool) {
 		explanation.History = append(explanation.History, ValueChange{
 			Before: before,
 			After:  after,
-			Origin: historyApplicationOrigin(application, operationPath),
+			Origin: historyApplicationOrigin(application, operationPath, r.immutableLookup),
 		})
 	}
 	appendInheritanceExplanation(&explanation, &working, path, r.inheritance, r.secrets)
@@ -78,20 +78,20 @@ func (r *Inspection) Explain(path Path) (Explanation, bool) {
 	// decoding applies them to the final input tree. Show that reconciliation
 	// explicitly, including canonical scalar conversions, before domain changes.
 	replayed, _ := documentAtPath(working, path)
-	decoded, _ := documentAtPath(r.input, path)
+	decoded, _ := documentAtPathWithLookup(r.input, path, r.immutableLookup)
 	if !configurationValuesEqual(replayed, decoded) {
 		origin := cloneOrigin(r.inputOrigins[path.String()])
 		origin.Operation = ChangeDecoding
 		explanation.History = append(explanation.History, ValueChange{
 			Before:  valueSnapshot(working, path, r.secrets),
-			After:   valueSnapshot(r.input, path, r.secrets),
+			After:   valueSnapshotWithLookup(r.input, path, r.secrets, r.immutableLookup),
 			Origin:  origin,
 			Reasons: []string{"applied retained defaults and canonical typed decoding"},
 		})
 	}
 
 	working = document.Clone(r.input)
-	for _, snapshot := range coalescedResolutionSnapshots(r.resolution) {
+	for _, snapshot := range r.resolutionReplay {
 		relevant := pathsIntersect(snapshot.change.Path, path)
 		var before ValueSnapshot
 		if relevant {

internal/engine/explain_test.go

@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 	"reflect"
 	"strings"
+	"sync"
 	"testing"
 
 	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
@@ -520,3 +521,95 @@ func TestExplanationReplaysResolutionAdditionsAndOverlappingIntent(t *testing.T)
 		})
 	}
 }
+
+func TestExplanationReplayDescriptorsRemainDetachedAcrossQueries(t *testing.T) {
+	type config struct {
+		Count int `yaml:"count"`
+	}
+	result, err := testLoad(Bytes("resolution-explanation.yml", []byte("count: 1\n")), Options[config]{
+		Definition: Definition[config]{Resolve: func(value *config, resolution *Resolution) error {
+			value.Count = 2
+			resolution.Record(Keys("count"), ChangeNormalization, "normalized", Keys("count"))
+			return nil
+		}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	first, ok := result.Explain(Keys("count"))
+	if !ok {
+		t.Fatal("missing explanation")
+	}
+	var firstResolution *ValueChange
+	for index := range first.History {
+		if first.History[index].Origin.Layer == LayerResolution {
+			firstResolution = &first.History[index]
+			break
+		}
+	}
+	if firstResolution == nil || len(firstResolution.Reasons) != 1 || len(firstResolution.Dependencies) != 1 {
+		t.Fatalf("resolution history = %#v", first.History)
+	}
+	firstResolution.Reasons[0] = "mutated"
+	firstResolution.Dependencies[0].segments[0].key = "mutated"
+
+	second, ok := result.Explain(Keys("count"))
+	if !ok {
+		t.Fatal("missing repeated explanation")
+	}
+	for _, change := range second.History {
+		if change.Origin.Layer == LayerResolution {
+			if !reflect.DeepEqual(change.Reasons, []string{"normalized"}) || len(change.Dependencies) != 1 || change.Dependencies[0].String() != "/count" {
+				t.Fatalf("repeated explanation observed caller mutation: %#v", change)
+			}
+			return
+		}
+	}
+	t.Fatalf("resolution change missing from repeated explanation: %#v", second.History)
+}
+
+func TestConcurrentReadOnlyInspectionQueries(t *testing.T) {
+	type config struct {
+		Group struct {
+			Value string `yaml:"value"`
+		} `yaml:"group"`
+	}
+	result, err := testLoad(Bytes("concurrent-inspection.yml", []byte("group: {value: input}\n")), Options[config]{
+		Definition: Definition[config]{Resolve: func(value *config, resolution *Resolution) error {
+			value.Group.Value = "resolved"
+			resolution.Record(Keys("group", "value"), ChangeNormalization, "normalized", Keys("group", "value"))
+			return nil
+		}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	paths := []Path{Keys("group"), Keys("group", "value")}
+	var wait sync.WaitGroup
+	errors := make(chan string, 8)
+	for worker := 0; worker < cap(errors); worker++ {
+		wait.Add(1)
+		go func() {
+			defer wait.Done()
+			for iteration := 0; iteration < 8; iteration++ {
+				for _, path := range paths {
+					explanation, found := result.Explain(path)
+					if !found || !explanation.Effective.Present {
+						errors <- "missing effective explanation for " + path.String()
+						return
+					}
+					metadata := result.Metadata()
+					if _, found := metadata.Lookup(path); !found || len(metadata.History(path)) == 0 {
+						errors <- "missing metadata for " + path.String()
+						return
+					}
+				}
+			}
+		}()
+	}
+	wait.Wait()
+	close(errors)
+	for message := range errors {
+		t.Error(message)
+	}
+}

internal/engine/history.go

@@ -45,10 +45,12 @@ func (c *retainedNodeCounter) add(root *document.Node) bool {
 // Replay reconciles with canonical decoding before domain resolution so both
 // contracts agree on the effective result without retaining a tree per field.
 type historyApplication struct {
-	layer  Layer
+	layer           Layer
-	path   Path
+	path            Path
-	value  *document.Node
+	value           *document.Node
-	origin Origin
+	origin          Origin
+	sequences       []sequenceHistoryContribution
+	sequencesByPath map[string]sequenceHistoryContribution
 }
 
 func cloneHistoryApplications(values []historyApplication) []historyApplication {
@@ -59,48 +61,130 @@ func cloneHistoryApplications(values []historyApplication) []historyApplication
 	for index, value := range values {
 		cloned[index] = historyApplication{
 			layer: value.layer, path: value.path.clone(), value: value.value,
-			origin: cloneOrigin(value.origin),
+			origin: cloneOrigin(value.origin), sequences: cloneSequenceHistoryContributions(value.sequences),
 		}
+		cloned[index].sequencesByPath = indexSequenceHistoryContributions(cloned[index].sequences)
 	}
 	return cloned
 }
 
-func applicationOperationPath(application historyApplication, query Path) (Path, bool) {
+// walkHistoryApplication visits a retained source tree with both its local
+// semantic path and its effective projected path. Sequence fragments keep
+// their original tree indexes, while the effective path uses the assigned
+// range recorded by strict composition.
+func walkHistoryApplication(application historyApplication, visit func(local, effective Path, node *document.Node)) {
+	if application.value == nil {
+		return
+	}
+	var walk func(*document.Node, Path, Path)
+	walk = func(node *document.Node, local, effective Path) {
+		if node == nil {
+			return
+		}
+		visit(local, appendDestination(application.path, effective), node)
+		switch node.Kind {
+		case document.Mapping:
+			for _, entry := range node.Mapping {
+				walk(entry.Value, local.Key(entry.Key), effective.Key(entry.Key))
+			}
+		case document.Sequence:
+			contribution, projected := sequenceHistoryAt(application.sequencesByPath, local)
+			for index, child := range node.Sequence {
+				effectiveIndex := index
+				if projected {
+					effectiveIndex += contribution.offset
+				}
+				walk(child, local.Index(index), effective.Index(effectiveIndex))
+			}
+		}
+	}
+	walk(application.value, Path{}, Path{})
+}
+
+// historyApplicationLocalPath translates an effective projected path back to
+// the retained source tree, including indexes shifted by enclosing appends.
+func historyApplicationLocalPath(application historyApplication, effective Path) (Path, bool) {
+	relative, ok := relativeHistoryPath(application.path, effective)
+	if !ok {
+		return Path{}, false
+	}
+	local := Path{}
+	for _, segment := range relative.segments {
+		if contribution, found := sequenceHistoryAt(application.sequencesByPath, local); found {
+			index, valid := schemaIndex(segment)
+			if !valid || segment.kind == pathSegmentKey || index < contribution.offset || index >= contribution.offset+contribution.length {
+				return Path{}, false
+			}
+			local = local.Index(index - contribution.offset)
+			continue
+		}
+		local.segments = append(local.segments, segment)
+	}
+	return local, true
+}
+
+func applicationOperationPath(application historyApplication, query Path, lookup *documentLookup) (Path, bool) {
 	if !application.path.valid() || application.value == nil {
 		return Path{}, false
 	}
-	if application.path.String() != "" {
+	if !pathContains(application.path, query) {
-		if pathsIntersect(application.path, query) {
+		if pathContains(query, application.path) {
 			return application.path.clone(), true
 		}
 		return Path{}, false
 	}
-	if len(query.segments) == 0 {
+	sequencePathMatched := false
-		return Path{}, true
+	for _, contribution := range application.sequences {
+		container := appendDestination(application.path, contribution.path)
+		if !pathContains(container, query) && !pathContains(query, container) {
+			continue
+		}
+		sequencePathMatched = true
+		if pathContains(container, query) && len(query.segments) > len(container.segments) {
+			local, ok := historyApplicationLocalPath(application, query)
+			if contribution.mode == sequenceHistoryReplace {
+				if _, present := documentAtPathWithLookup(application.value, local, lookup); !ok || !present {
+					// A replacement also changes descendants missing from the
+					// incoming list. Attribute their removal to its container.
+					return container, true
+				}
+			}
+			if !ok {
+				continue
+			}
+		}
+		return query.clone(), true
 	}
-	for length := 1; length <= len(query.segments); length++ {
+	if sequencePathMatched {
-		prefix := Path{segments: clonePathSegments(query.segments[:length], 0)}
+		return Path{}, false
-		node, present := documentAtPath(application.value, prefix)
+	}
+	if len(query.segments) == len(application.path.segments) || application.value.Kind != document.Mapping {
+		return application.path.clone(), true
+	}
+	relative, _ := relativeHistoryPath(application.path, query)
+	for length := 1; length <= len(relative.segments); length++ {
+		prefix := Path{segments: clonePathSegments(relative.segments[:length], 0)}
+		node, present := documentAtPathWithLookup(application.value, prefix, lookup)
 		if !present {
 			return Path{}, false
 		}
-		if length == len(query.segments) || node.Kind != document.Mapping {
+		if length == len(relative.segments) || node.Kind != document.Mapping {
-			return prefix, true
+			return appendDestination(application.path, prefix), true
 		}
 	}
 	return Path{}, false
 }
 
-func historyApplicationOrigin(application historyApplication, operationPath Path) Origin {
+func historyApplicationOrigin(application historyApplication, operationPath Path, lookup *documentLookup) Origin {
 	if application.origin.Layer != "" {
 		return cloneOrigin(application.origin)
 	}
 	origin := Origin{Layer: application.layer}
-	relative, ok := relativeHistoryPath(application.path, operationPath)
+	relative, ok := historyApplicationLocalPath(application, operationPath)
 	if !ok {
 		return origin
 	}
-	if node, present := documentAtPath(application.value, relative); present {
+	if node, present := documentAtPathWithLookup(application.value, relative, lookup); present {
 		origin.Locations = []Location{publicLocation(node.Location)}
 	}
 	return origin
@@ -119,13 +203,17 @@ func pathsIntersect(left, right Path) bool {
 
 func applyHistoryApplication(root **document.Node, application historyApplication, index *mappingIndex) {
 	if application.path.String() == "" {
-		mergeHistoryDocument(root, application.value, index)
+		mergeHistoryDocumentAtPath(root, application.value, Path{}, index, application.sequencesByPath)
 		return
 	}
 	mergeHistoryAtPath(root, application.path, application.value, index)
 }
 
 func mergeHistoryDocument(target **document.Node, incoming *document.Node, index *mappingIndex) {
+	mergeHistoryDocumentAtPath(target, incoming, Path{}, index, nil)
+}
+
+func mergeHistoryDocumentAtPath(target **document.Node, incoming *document.Node, path Path, index *mappingIndex, sequences map[string]sequenceHistoryContribution) {
 	if incoming == nil {
 		return
 	}
@@ -141,10 +229,56 @@ func mergeHistoryDocument(target **document.Node, incoming *document.Node, index
 			index.append(*target, cloned)
 			continue
 		}
-		mergeHistoryDocument(&(*target).Mapping[position].Value, entry.Value, index)
+		entryPath := path.Key(entry.Key)
+		if contribution, found := sequenceHistoryAt(sequences, entryPath); found {
+			applySequenceHistory(&(*target).Mapping[position].Value, entry.Value, contribution)
+			continue
+		}
+		mergeHistoryDocumentAtPath(&(*target).Mapping[position].Value, entry.Value, entryPath, index, sequences)
 	}
 }
 
+func sequenceHistoryAt(contributions map[string]sequenceHistoryContribution, path Path) (sequenceHistoryContribution, bool) {
+	contribution, found := contributions[path.String()]
+	return contribution, found
+}
+
+func indexSequenceHistoryContributions(values []sequenceHistoryContribution) map[string]sequenceHistoryContribution {
+	if len(values) == 0 {
+		return nil
+	}
+	index := make(map[string]sequenceHistoryContribution, len(values))
+	for _, value := range values {
+		index[value.path.String()] = value
+	}
+	return index
+}
+
+func applySequenceHistory(target **document.Node, incoming *document.Node, contribution sequenceHistoryContribution) {
+	if incoming == nil || incoming.Kind != document.Sequence {
+		return
+	}
+	if contribution.mode == sequenceHistoryReplace || *target == nil || (*target).Kind != document.Sequence {
+		*target = document.Clone(incoming)
+		return
+	}
+	for _, item := range incoming.Sequence {
+		(*target).Sequence = append((*target).Sequence, document.Clone(item))
+	}
+}
+
+func cloneSequenceHistoryContributions(values []sequenceHistoryContribution) []sequenceHistoryContribution {
+	if values == nil {
+		return nil
+	}
+	cloned := make([]sequenceHistoryContribution, len(values))
+	for index, value := range values {
+		cloned[index] = value
+		cloned[index].path = value.path.clone()
+	}
+	return cloned
+}
+
 func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node, index *mappingIndex) {
 	if root == nil || *root == nil || len(path.segments) == 0 {
 		mergeHistoryDocument(root, incoming, index)
@@ -152,7 +286,19 @@ func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node
 	}
 	current := *root
 	for segmentIndex, segment := range path.segments {
-		if current.Kind != document.Mapping || segment.kind == pathSegmentIndex {
+		if segment.kind == pathSegmentIndex {
+			position, ok := schemaIndex(segment)
+			if current.Kind != document.Sequence || !ok || position >= len(current.Sequence) {
+				return
+			}
+			if segmentIndex == len(path.segments)-1 {
+				mergeHistoryDocument(&current.Sequence[position], incoming, index)
+				return
+			}
+			current = current.Sequence[position]
+			continue
+		}
+		if current.Kind != document.Mapping {
 			return
 		}
 		position := index.find(current, segment.key)
@@ -179,28 +325,50 @@ func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node
 // intent into that event rather than replay a child assignment a second time.
 func coalescedResolutionSnapshots(snapshots []resolutionSnapshot) []resolutionSnapshot {
 	groups := make([]resolutionSnapshot, 0, len(snapshots))
+	reasons := make([]map[string]struct{}, 0, len(snapshots))
+	dependencies := make([]map[string]struct{}, 0, len(snapshots))
+	var coverage pathPrefixIndex
 	for _, snapshot := range snapshots {
-		merged := false
+		pointer := snapshot.change.Path.String()
-		for i := range groups {
+		groupIndex := -1
-			if !pathContains(groups[i].change.Path, snapshot.change.Path) {
+		coverage.visitAncestors(pointer, func(id int) {
-				continue
+			if groupIndex < 0 || id < groupIndex {
+				groupIndex = id
 			}
+		})
+		if groupIndex >= 0 {
+			group := &groups[groupIndex]
 			for _, reason := range snapshot.change.Reasons {
-				groups[i].change.Reasons = appendUniqueString(groups[i].change.Reasons, reason)
+				if _, found := reasons[groupIndex][reason]; !found {
+					reasons[groupIndex][reason] = struct{}{}
+					group.change.Reasons = append(group.change.Reasons, reason)
+				}
 			}
 			for _, dependency := range snapshot.change.Dependencies {
-				groups[i].change.Dependencies = appendUniquePath(groups[i].change.Dependencies, dependency)
+				dependencyPointer := dependency.String()
+				if _, found := dependencies[groupIndex][dependencyPointer]; !found {
+					dependencies[groupIndex][dependencyPointer] = struct{}{}
+					group.change.Dependencies = append(group.change.Dependencies, dependency.clone())
+				}
 			}
 			if snapshot.change.Origin.Operation == ChangeNormalization {
-				groups[i].change.Origin.Operation = ChangeNormalization
+				group.change.Origin.Operation = ChangeNormalization
 			}
-			merged = true
+			continue
-			break
 		}
-		if !merged {
+		snapshot.change = cloneChange(snapshot.change)
-			snapshot.change = cloneChange(snapshot.change)
+		groups = append(groups, snapshot)
-			groups = append(groups, snapshot)
+		reasonSet := make(map[string]struct{}, len(snapshot.change.Reasons))
+		for _, reason := range snapshot.change.Reasons {
+			reasonSet[reason] = struct{}{}
 		}
+		reasons = append(reasons, reasonSet)
+		dependencySet := make(map[string]struct{}, len(snapshot.change.Dependencies))
+		for _, dependency := range snapshot.change.Dependencies {
+			dependencySet[dependency.String()] = struct{}{}
+		}
+		dependencies = append(dependencies, dependencySet)
+		coverage.insert(pointer, len(groups)-1)
 	}
 	return groups
 }

internal/engine/history_sequence_test.go

@@ -0,0 +1,240 @@
+package engine
+
+import (
+	"bytes"
+	"reflect"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestSequenceHistoryReplaysAppendAtAssignedIndexes(t *testing.T) {
+	policy := sequencePolicy{identityFields: map[string]string{"/records": "id", "/other": "id"}}
+	first := parseCompositionDocument(t, "source-1", "records: [{id: a, value: first}]\nother: [{id: x}]\n")
+	second := parseCompositionDocument(t, "source-2", "records: [{id: b, value: second}]\nother: [{id: y}]\n")
+	composed, diagnostics := composeDocumentsWithPolicy(policy, first, second)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose diagnostics = %#v", diagnostics)
+	}
+	for applicationIndex, application := range composed.applications {
+		for path, want := range map[string]int{"/records": 1, "/other": 1} {
+			sequence, present := documentAtPath(application.value, mustParsePath(t, path))
+			if !present || sequence.Kind != document.Sequence || len(sequence.Sequence) != want {
+				t.Errorf("application %d retained %s = %#v, %v; want one source fragment item", applicationIndex, path, sequence, present)
+			}
+		}
+	}
+
+	working := parseCompositionDocument(t, "defaults", "records: [{id: default}]\nother: [{id: default}]\n")
+	index := new(mappingIndex)
+	for _, application := range composed.applications {
+		applyHistoryApplication(&working, application, index)
+	}
+	for path, want := range map[string][]string{
+		"/records": {"a", "b"},
+		"/other":   {"x", "y"},
+	} {
+		sequence, present := documentAtPath(working, mustParsePath(t, path))
+		if !present || sequence.Kind != document.Sequence || len(sequence.Sequence) != len(want) {
+			t.Fatalf("replayed %s = %#v", path, sequence)
+		}
+		for itemIndex, id := range want {
+			field := sequence.Sequence[itemIndex].Mapping[0].Value.Text
+			if field != id {
+				t.Errorf("replayed %s[%d].id = %q, want %q", path, itemIndex, field, id)
+			}
+		}
+	}
+
+	application := composed.applications[1]
+	cloned := cloneHistoryApplications(composed.applications)
+	cloned[1].sequences[0].path.segments[0].key = "mutated"
+	if composed.applications[1].sequences[0].path.String() != "/records" {
+		t.Fatal("cloned sequence history path aliases its source")
+	}
+	addedPath := Keys("records").Index(1).Key("value")
+	if operation, relevant := applicationOperationPath(application, addedPath, nil); !relevant || operation.String() != addedPath.String() {
+		t.Fatalf("appended value operation = %s, %v", operation.String(), relevant)
+	}
+	if _, relevant := applicationOperationPath(application, Keys("records").Index(0).Key("value"), nil); relevant {
+		t.Fatal("later contribution was reported as changing an earlier record")
+	}
+	origin := historyApplicationOrigin(application, addedPath, nil)
+	if len(origin.Locations) != 1 || origin.Locations[0].SourceID != "source-2" {
+		t.Fatalf("appended value origin = %#v", origin)
+	}
+	overlay := historyApplication{
+		layer: LayerOverlay,
+		value: parseCompositionDocument(t, "overlay", "records: []\n"),
+	}
+	applyHistoryApplication(&working, overlay, index)
+	replaced, present := documentAtPath(working, Keys("records"))
+	if !present || replaced.Kind != document.Sequence || len(replaced.Sequence) != 0 {
+		t.Fatalf("ordinary later list replacement = %#v, %v", replaced, present)
+	}
+}
+
+func TestSequenceHistoryPreservesTierReplacementAndEmptyLists(t *testing.T) {
+	policy := sequencePolicy{identityFields: map[string]string{"/records": "id", "/independent": "id"}}
+	first, diagnostics := composeDocumentsWithPolicy(policy,
+		parseCompositionDocument(t, "underlay-1a", "records: [{id: shared}]\nindependent: [{id: x}]\n"),
+		parseCompositionDocument(t, "underlay-1b", "records: [{id: lower}]\n"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("first tier diagnostics = %#v", diagnostics)
+	}
+	for index := range first.applications {
+		first.applications[index].layer = LayerUnderlay
+	}
+	second, diagnostics := composeDocumentsWithPolicy(policy,
+		parseCompositionDocument(t, "underlay-2", "records: [{id: shared}]\nindependent: []\n"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("second tier diagnostics = %#v", diagnostics)
+	}
+	main, diagnostics := composeDocumentsWithPolicy(policy,
+		parseCompositionDocument(t, "main", "records: []\n"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("main diagnostics = %#v", diagnostics)
+	}
+
+	assembly := newAssemblyAccumulator(first)
+	if diagnostics := assembly.applyOverlay(second.root, second.origins, second.applications, LayerUnderlay); len(diagnostics) != 0 {
+		t.Fatalf("second tier handoff diagnostics = %#v", diagnostics)
+	}
+	if diagnostics := assembly.applyOverlay(main.root, main.origins, main.applications, LayerBase); len(diagnostics) != 0 {
+		t.Fatalf("main handoff diagnostics = %#v", diagnostics)
+	}
+	if len(assembly.current.applications) != 4 {
+		t.Fatalf("retained source applications = %d, want 4", len(assembly.current.applications))
+	}
+
+	working := parseCompositionDocument(t, "defaults", "records: [{id: default}]\nindependent: [{id: default}]\n")
+	index := new(mappingIndex)
+	for _, application := range assembly.current.applications {
+		applyHistoryApplication(&working, application, index)
+	}
+	for path, want := range map[string][]string{
+		"/records":     nil,
+		"/independent": nil,
+	} {
+		sequence, present := documentAtPath(working, mustParsePath(t, path))
+		if !present || sequence.Kind != document.Sequence || len(sequence.Sequence) != len(want) {
+			t.Errorf("replayed replacement %s = %#v, want an explicit empty sequence", path, sequence)
+		}
+	}
+
+	// The same identity may appear in separate tiers, while each tier still
+	// retains its individual source applications for explanation replay.
+	if got := []Layer{assembly.current.applications[0].layer, assembly.current.applications[1].layer,
+		assembly.current.applications[2].layer, assembly.current.applications[3].layer}; !reflect.DeepEqual(got, []Layer{LayerUnderlay, LayerUnderlay, LayerUnderlay, LayerBase}) {
+		t.Fatalf("application layers = %#v", got)
+	}
+}
+
+func TestHistoryMergeSupportsSemanticIndexedPrefixes(t *testing.T) {
+	root := parseCompositionDocument(t, "base", "records: [{id: one, helper: {value: old}}]\n")
+	application := historyApplication{
+		path:  Keys("records").Index(0).Key("helper"),
+		value: parseCompositionDocument(t, "helper", "value: new\n"),
+	}
+	applyHistoryApplication(&root, application, new(mappingIndex))
+	value, present := documentAtPath(root, Keys("records").Index(0).Key("helper").Key("value"))
+	if !present || value.Text != "new" {
+		t.Fatalf("indexed helper replay = %#v, %v", value, present)
+	}
+}
+
+func TestProjectedSequenceHistoryAgreesAcrossMetadataAndExplanation(t *testing.T) {
+	policy := sequencePolicy{identityFields: map[string]string{"/records": "id"}}
+	composed, diagnostics := composeDocumentsWithPolicy(policy,
+		parseCompositionDocument(t, "first", "records: [{id: first, token: public}]"),
+		parseCompositionDocument(t, "second", "records: [{id: second, token: private}]"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose diagnostics = %#v", diagnostics)
+	}
+	path := Keys("records").Index(1).Key("token")
+	var metadata Metadata
+	finalizeMetadataPaths(&metadata, composed.root, composed.applications)
+	if !metadata.hasHistoricalPath(path) {
+		t.Fatalf("projected metadata omitted shifted path %s: %#v", path, metadata.historicalPaths)
+	}
+
+	inspection := &Inspection{
+		metadata: metadata, baseline: &document.Node{Kind: document.Mapping},
+		input: composed.root, final: composed.root, applications: composed.applications,
+	}
+	inspection.secrets = classifySecretPaths(nil, func(candidate Path) bool {
+		return reflect.DeepEqual(candidate, path)
+	}, metadata, composed.root, composed.applications)
+	explanation, ok := inspection.Explain(path)
+	if !ok || !explanation.Effective.Redacted {
+		t.Fatalf("shifted explanation = %#v, %v", explanation, ok)
+	}
+	var foundSecondOrigin bool
+	for _, change := range explanation.History {
+		for _, location := range change.Origin.Locations {
+			foundSecondOrigin = foundSecondOrigin || location.SourceID == "second"
+		}
+	}
+	if !foundSecondOrigin {
+		t.Fatalf("shifted history lost second source attribution: %#v", explanation.History)
+	}
+	var rendered bytes.Buffer
+	if err := inspection.WriteExplanation(&rendered, path); err != nil {
+		t.Fatal(err)
+	}
+	if !strings.Contains(rendered.String(), `path: "/records/1/token"`) || strings.Contains(rendered.String(), "private") {
+		t.Fatalf("shifted explanation rendering is incomplete or unsafe: %s", rendered.String())
+	}
+}
+
+func TestReplacedProjectedSensitiveRecordRemainsRedacted(t *testing.T) {
+	policy := sequencePolicy{identityFields: map[string]string{"/records": "id"}}
+	composed, diagnostics := composeDocumentsWithPolicy(policy,
+		parseCompositionDocument(t, "first", "records: [{id: first, token: public}]"),
+		parseCompositionDocument(t, "second", "records: [{id: second, token: PRIVATE-RECORD-CANARY}]"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose diagnostics = %#v", diagnostics)
+	}
+	applications := append([]historyApplication(nil), composed.applications...)
+	applications = append(applications, historyApplication{
+		layer: LayerOverlay,
+		value: parseCompositionDocument(t, "replacement", "records: [{id: replacement, token: visible}]"),
+	})
+	final := applications[len(applications)-1].value
+	path := Keys("records").Index(1).Key("token")
+	var metadata Metadata
+	finalizeMetadataPaths(&metadata, final, applications)
+	inspection := &Inspection{
+		metadata: metadata, baseline: &document.Node{Kind: document.Mapping},
+		input: final, final: final, applications: applications,
+	}
+	inspection.secrets = classifySecretPaths(nil, func(candidate Path) bool {
+		return reflect.DeepEqual(candidate, path)
+	}, metadata, final, applications)
+	explanation, ok := inspection.Explain(path)
+	if !ok || explanation.Effective.Present {
+		t.Fatalf("replaced shifted record explanation = %#v, %v", explanation, ok)
+	}
+	var rendered bytes.Buffer
+	if err := inspection.WriteExplanation(&rendered, path); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(rendered.String(), "PRIVATE-RECORD-CANARY") || !strings.Contains(rendered.String(), "[REDACTED]") {
+		t.Fatalf("replaced sensitive history leaked or was not redacted: %s", rendered.String())
+	}
+}
+
+func mustParsePath(t *testing.T, value string) Path {
+	t.Helper()
+	path, err := ParsePath(value)
+	if err != nil {
+		t.Fatal(err)
+	}
+	return path
+}

internal/engine/imports.go

@@ -45,29 +45,45 @@ type importAccounting struct {
 }
 
 type importTraversal struct {
-	access     *filesystemAccess
+	access       *filesystemAccess
-	accounting *importAccounting
+	accounting   *importAccounting
-	limits     importLimits
+	limits       importLimits
-	rule       *VersionRule
+	rule         *VersionRule
+	versionState *sourceVersionState
 
-	documents []*document.Node
+	scope        acquisitionScope
-	sources   []SourceInfo
+	itemScope    bool
-	active    map[resourceIdentity]int
+	itemPrefix   Path
-	visited   map[resourceIdentity]importRoute
+	itemFallback Path
-	stack     []importRoute
+	sources      []SourceInfo
+	active       map[resourceIdentity]int
+	visited      map[resourceIdentity]importRoute
+	stack        []importRoute
 }
 
 func loadImportedDocuments(source Source, context *FilesystemContext, main parsedSource, rule *VersionRule, limits importLimits) (*composedDocument, []SourceInfo, []Diagnostic) {
-	return loadImportedDocumentsTracked(source, context, main, rule, limits, &importAccounting{}, nil, nil)
+	return loadImportedDocumentsTracked(source, context, main, Path{}, rule, limits, &importAccounting{}, nil, nil)
 }
 
-func loadImportedDocumentsTracked(source Source, context *FilesystemContext, main parsedSource, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken) (*composedDocument, []SourceInfo, []Diagnostic) {
+func loadImportedDocumentsTracked(source Source, context *FilesystemContext, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken) (*composedDocument, []SourceInfo, []Diagnostic) {
+	return loadImportedDocumentsTrackedWithVersion(source, context, main, destination, rule, limits, accounting, visited, hostToken, nil)
+}
+
+func loadImportedDocumentsTrackedWithVersion(source Source, context *FilesystemContext, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken, versionState *sourceVersionState) (*composedDocument, []SourceInfo, []Diagnostic) {
+	var processing *sourceVersionProcessingResult
+	if versionState != nil && versionState.mode != sourceVersionModeDefault {
+		processing = versionState.mainProcessing
+	}
+	return loadImportedDocumentsTrackedWithProcessing(source, context, main, destination, rule, limits, accounting, visited, hostToken, versionState, processing, sequencePolicy{})
+}
+
+func loadImportedDocumentsTrackedWithProcessing(source Source, context *FilesystemContext, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken, versionState *sourceVersionState, processing *sourceVersionProcessingResult, policy sequencePolicy) (*composedDocument, []SourceInfo, []Diagnostic) {
 	if nativeContext(source, context) {
 		access, basePath, mainPath, diagnostic := nativeFilesystemAccess(source, context)
 		if diagnostic != nil {
 			return nil, sourceInfos(main.source), []Diagnostic{*diagnostic}
 		}
-		return loadImportedWithAccessTracked(access, basePath, mainPath, main, rule, limits, accounting, visited)
+		return loadImportedWithAccessTrackedAndProcessingPolicy(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, versionState, processing, policy)
 	}
 	rootPath, basePath, mainPath, diagnostic := importFilesystem(source, context, main)
 	if diagnostic != nil {
@@ -82,14 +98,30 @@ func loadImportedDocumentsTracked(source Source, context *FilesystemContext, mai
 	if hostToken != nil {
 		access.token = hostToken
 	}
-	return loadImportedWithAccessTracked(access, basePath, mainPath, main, rule, limits, accounting, visited)
+	return loadImportedWithAccessTrackedAndProcessingPolicy(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, versionState, processing, policy)
 }
 
 func loadImportedWithAccess(access *filesystemAccess, basePath, mainPath string, main parsedSource, rule *VersionRule, limits importLimits, accounting *importAccounting) (*composedDocument, []SourceInfo, []Diagnostic) {
-	return loadImportedWithAccessTracked(access, basePath, mainPath, main, rule, limits, accounting, nil)
+	return loadImportedWithAccessTracked(access, basePath, mainPath, main, Path{}, rule, limits, accounting, nil)
 }
 
-func loadImportedWithAccessTracked(access *filesystemAccess, basePath, mainPath string, main parsedSource, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute) (*composedDocument, []SourceInfo, []Diagnostic) {
+func loadImportedWithAccessTracked(access *filesystemAccess, basePath, mainPath string, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute) (*composedDocument, []SourceInfo, []Diagnostic) {
+	return loadImportedWithAccessTrackedWithVersion(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, nil)
+}
+
+func loadImportedWithAccessTrackedWithVersion(access *filesystemAccess, basePath, mainPath string, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, versionState *sourceVersionState) (*composedDocument, []SourceInfo, []Diagnostic) {
+	var processing *sourceVersionProcessingResult
+	if versionState != nil && versionState.mode != sourceVersionModeDefault {
+		processing = versionState.mainProcessing
+	}
+	return loadImportedWithAccessTrackedAndProcessing(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, versionState, processing)
+}
+
+func loadImportedWithAccessTrackedAndProcessing(access *filesystemAccess, basePath, mainPath string, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, versionState *sourceVersionState, processing *sourceVersionProcessingResult) (*composedDocument, []SourceInfo, []Diagnostic) {
+	return loadImportedWithAccessTrackedAndProcessingPolicy(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, versionState, processing, sequencePolicy{})
+}
+
+func loadImportedWithAccessTrackedAndProcessingPolicy(access *filesystemAccess, basePath, mainPath string, main parsedSource, destination Path, rule *VersionRule, limits importLimits, accounting *importAccounting, visited map[resourceIdentity]importRoute, versionState *sourceVersionState, processing *sourceVersionProcessingResult, policy sequencePolicy) (*composedDocument, []SourceInfo, []Diagnostic) {
 	if !access.contains(basePath) || (mainPath != "" && !access.contains(mainPath)) {
 		_ = access.close()
 		return nil, sourceInfos(main.source), []Diagnostic{importDiagnostic(CodeImportOutsideRoot, "selected source and import base must stay inside the configuration root", nil)}
@@ -102,6 +134,8 @@ func loadImportedWithAccessTracked(access *filesystemAccess, basePath, mainPath
 		}
 	}
 	mainInfo := cloneSourceInfo(*main.source)
+	mainInfo.Destination = destination.clone()
+	mainIsItem := main.source.placementMode == placementModeSequenceItem
 	if mainPath != "" {
 		mainInfo.Path = mainPath
 	}
@@ -117,10 +151,17 @@ func loadImportedWithAccessTracked(access *filesystemAccess, basePath, mainPath
 	accounting.bytes += main.bytes
 	accounting.nodes += countInputNodes(main.document)
 	state := importTraversal{
-		access: access, accounting: accounting, limits: limits, rule: rule,
+		access: access, accounting: accounting, limits: limits, rule: rule, versionState: versionState,
-		documents: make([]*document.Node, 0, 1),
+		scope:   acquisitionScope{destination: destination.clone()},
-		sources:   []SourceInfo{mainInfo},
+		sources: []SourceInfo{mainInfo},
-		active:    make(map[resourceIdentity]int), visited: visited,
+		active:  make(map[resourceIdentity]int), visited: visited,
+	}
+	if mainIsItem {
+		state.itemScope = true
+		state.itemPrefix = destination.clone()
+		state.itemFallback = destination.clone()
+		state.scope.destination = Path{}
+		state.sources[0] = cloneSourceInfo(mainInfo)
 	}
 	if state.visited == nil {
 		state.visited = make(map[resourceIdentity]importRoute)
@@ -138,21 +179,118 @@ func loadImportedWithAccessTracked(access *filesystemAccess, basePath, mainPath
 	state.active[mainKey] = 0
 	state.visited[mainKey] = mainRoute
 	state.stack = append(state.stack, mainRoute)
-	body, declarations, diagnostics := splitImportDirectives(main.document)
+	var body *document.Node
+	var declarations []importDeclaration
+	var diagnostics []Diagnostic
+	if processing != nil {
+		body = processing.payload
+		declarations = processing.imports
+	} else {
+		body, declarations, diagnostics = splitImportDirectives(main.document)
+	}
 	if len(diagnostics) == 0 {
-		state.documents = append(state.documents, body)
+		if mainIsItem {
-		diagnostics = state.walkDeclarations(basePath, declarations, 0)
+			state.scope.contributions = append(state.scope.contributions, acquiredContribution{
+				source: cloneSourceInfo(mainInfo), payload: body, document: body, processing: processing,
+			})
+			diagnostics = state.walkDeclarations(basePath, declarations, 0, Path{})
+		} else {
+			_, placed, err := placeDocument(body, destination, body.Location, maxDocumentDepth, maxDocumentNodes)
+			placementNodes := destinationWrapperNodeCount(destination)
+			if err != nil {
+				diagnostics = []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, main.source.ID, "configuration exceeds the source depth or node limit after destination placement")}
+			} else if accounting.nodes+placementNodes > limits.nodes {
+				diagnostics = []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", nil)}
+			} else {
+				accounting.nodes += placementNodes
+				state.scope.contributions = append(state.scope.contributions, acquiredContribution{
+					source: cloneSourceInfo(mainInfo), payload: body, document: placed,
+					destination: destination.clone(), processing: processing,
+				})
+				diagnostics = state.walkDeclarations(basePath, declarations, 0, destination)
+			}
+		}
 	}
 
 	closeErr := access.close()
 	if len(diagnostics) != 0 {
+		if mainIsItem {
+			diagnostics = prependCompositionDiagnosticPaths(diagnostics, destination.Index(0))
+		}
 		return nil, cloneSourceInfos(state.sources), diagnostics
 	}
 	if closeErr != nil {
 		return nil, cloneSourceInfos(state.sources), []Diagnostic{importDiagnostic(CodeImportRead, "configuration root could not be closed", nil)}
 	}
-	composed, diagnostics := composeDocuments(state.documents...)
+	if mainIsItem {
+		localScope := state.scope
+		documents := make([]*document.Node, 0, len(localScope.contributions))
+		for _, contribution := range localScope.contributions {
+			documents = append(documents, contribution.document)
+		}
+		completed, failures := composeDocuments(documents...)
+		if len(failures) != 0 {
+			return nil, cloneSourceInfos(state.sources), prependCompositionDiagnosticPaths(failures, destination.Index(0))
+		}
+		if versionState != nil {
+			protectionRule := versionState.localRule
+			if versionState.mode == sourceVersionModeDefault && protectionRule != nil {
+				prefix := destination.Index(0)
+				relative, inside := relativeHistoryPath(prefix, protectionRule.Path)
+				if !inside || !matchesPathShape(Path{segments: protectionRule.Path.segments[:len(prefix.segments)]}, prefix) {
+					protectionRule = nil
+				} else {
+					scoped := *protectionRule
+					scoped.Path = relative
+					protectionRule = &scoped
+				}
+			}
+			if diagnostic := importedVersionClaim(documents, completed, protectionRule, 0); diagnostic != nil {
+				if rule != nil {
+					diagnostic.Path = rule.Path.clone()
+				}
+				return nil, cloneSourceInfos(state.sources), []Diagnostic{*diagnostic}
+			}
+		}
+		completed.acquisition = []acquisitionScope{cloneAcquisitionScope(localScope)}
+		projectNestedEvidence(completed, localScope)
+		_, placed, err := placeDocumentWithMode(completed.root, destination, placementModeSequenceItem, body.Location, maxDocumentDepth, maxDocumentNodes)
+		if err != nil {
+			return nil, cloneSourceInfos(state.sources), []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, main.source.ID, "configuration exceeds the source depth or node limit after destination placement")}
+		}
+		placementNodes := destinationWrapperNodeCountForMode(destination, placementModeSequenceItem)
+		if accounting.nodes+placementNodes > limits.nodes {
+			return nil, cloneSourceInfos(state.sources), []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", nil)}
+		}
+		accounting.nodes += placementNodes
+		composed, failures := composeDocumentsWithPolicy(policy, placed)
+		if composed != nil {
+			synthetic := acquisitionScope{contributions: []acquiredContribution{{
+				source: cloneSourceInfo(mainInfo), payload: completed.root, document: placed,
+				destination: destination.clone(), processing: processing, nested: completed,
+			}}}
+			projectNestedEvidence(composed, synthetic)
+			projectAcquiredDestinations(composed, synthetic, state.sources)
+			composed.acquisition = []acquisitionScope{cloneAcquisitionScope(synthetic)}
+			composed.inputBytes = accounting.bytes
+			composed.inputNodes = accounting.nodes
+		}
+		return composed, cloneSourceInfos(state.sources), failures
+	}
+	documents := make([]*document.Node, 0, len(state.scope.contributions))
+	for _, contribution := range state.scope.contributions {
+		documents = append(documents, contribution.document)
+	}
+	composed, diagnostics := composeDocumentsWithPolicy(policy, documents...)
 	if composed != nil {
+		if diagnostic := importedVersionClaim(documents, composed, rule, 0); diagnostic != nil {
+			return nil, cloneSourceInfos(state.sources), []Diagnostic{*diagnostic}
+		}
+	}
+	if composed != nil {
+		projectNestedEvidence(composed, state.scope)
+		projectAcquiredDestinations(composed, state.scope, state.sources)
+		composed.acquisition = []acquisitionScope{cloneAcquisitionScope(state.scope)}
 		composed.inputBytes = accounting.bytes
 		composed.inputNodes = accounting.nodes
 	}
@@ -175,8 +313,9 @@ func (s *importTraversal) checkInitialLimits() *Diagnostic {
 	return nil
 }
 
-func (s *importTraversal) walkDeclarations(basePath string, declarations []importDeclaration, depth int) []Diagnostic {
+func (s *importTraversal) walkDeclarations(basePath string, declarations []importDeclaration, depth int, parentDestination Path) []Diagnostic {
 	for _, declaration := range declarations {
+		childDestination := appendDestination(parentDestination, declaration.destination)
 		if declaration.glob != "" {
 			matches, diagnostics := s.expandImportGlob(basePath, declaration)
 			if len(diagnostics) != 0 {
@@ -193,21 +332,29 @@ func (s *importTraversal) walkDeclarations(basePath string, declarations []impor
 				matched := declaration
 				matched.path = match
 				matched.glob = ""
-				if diagnostics := s.visitPath(basePath, matched, depth+1); len(diagnostics) != 0 {
+				if diagnostics := s.visitPath(basePath, matched, childDestination, declaration.destination, depth+1); len(diagnostics) != 0 {
 					return diagnostics
 				}
 			}
 			continue
 		}
-		if diagnostics := s.visitPath(basePath, declaration, depth+1); len(diagnostics) != 0 {
+		if diagnostics := s.visitPath(basePath, declaration, childDestination, declaration.destination, depth+1); len(diagnostics) != 0 {
 			return diagnostics
 		}
 	}
 	return nil
 }
 
-func (s *importTraversal) visitPath(basePath string, declaration importDeclaration, depth int) []Diagnostic {
+func (s *importTraversal) visitPath(basePath string, declaration importDeclaration, destination, relativeDestination Path, depth int) []Diagnostic {
 	location := declaration.location
+	if declaration.placement == placementModeSequenceItem && len(destination.segments) == 0 {
+		return []Diagnostic{{
+			Code: CodeImportInvalid, Severity: SeverityError,
+			Path:    declaration.placementPath.clone(),
+			Message: "sequence-item placement requires a nonempty destination",
+			Primary: cloneLocation(declaration.placementLocation),
+		}}
+	}
 	if depth > s.limits.depth {
 		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the active import-depth limit", &location)}
 	}
@@ -260,7 +407,14 @@ func (s *importTraversal) visitPath(basePath string, declaration importDeclarati
 		kind = SourceKindFilesystem
 		label = s.access.label + "/" + canonical
 	}
-	info := SourceInfo{ID: sourceID, Label: label, Path: canonical, Layer: LayerBase, Kind: kind, ImportedFrom: &location}
+	info := SourceInfo{ID: sourceID, Label: label, Path: canonical, Destination: s.sourceDestination(destination), Layer: LayerBase, Kind: kind, ImportedFrom: &location}
+	if declaration.placement == placementModeSequenceItem {
+		info.placementMode = placementModeSequenceItem
+	}
+	// A source's own item placement still has an exact sequence-container
+	// destination. Only an unresolved enclosing item index makes the path a
+	// fallback container for this snapshot.
+	info.destinationUnresolved = s.itemScope
 	if kind == SourceKindFilesystem {
 		info.namespace = s.access.token
 	}
@@ -287,29 +441,339 @@ func (s *importTraversal) visitPath(basePath string, declaration importDeclarati
 	}
 	s.accounting.nodes += nodeCount
 
-	body, declarations, diagnostics := splitImportDirectives(root)
+	var body *document.Node
-	if len(diagnostics) != 0 {
+	var declarations []importDeclaration
+	var diagnostics []Diagnostic
+	var processing *sourceVersionProcessingResult
+	if s.versionState != nil && s.versionState.mode != sourceVersionModeDefault {
+		versionDestination := destination
+		if s.itemScope {
+			versionDestination = appendDestination(s.itemPrefix.Index(0), destination)
+		}
+		processed, failures := s.versionState.process(root, sourceVersionContribution, versionDestination, sourceID, declaration.placement)
+		if len(failures) != 0 {
+			return failures
+		}
+		processing = &processed
+		body, declarations = processed.payload, processed.imports
+	} else {
+		body, declarations, diagnostics = splitImportDirectives(root)
+		if len(diagnostics) != 0 {
+			return diagnostics
+		}
+	}
+	placementDestination := destination
+	mode := placementModeMapping
+	if declaration.placement == placementModeSequenceItem {
+		mode = placementModeSequenceItem
+	}
+	if mode == placementModeSequenceItem {
+		route := importRoute{canonical: canonical, locations: currentRoute.locations}
+		s.active[identity] = len(s.stack)
+		s.visited[identity] = route
+		s.stack = append(s.stack, route)
+		diagnostics := s.visitItemSource(canonical, declaration, destination, relativeDestination, depth, info, body, declarations, processing)
+		delete(s.active, identity)
+		s.stack = s.stack[:len(s.stack)-1]
 		return diagnostics
 	}
-	if versionNode := fragmentVersionClaim(body, s.rule); versionNode != nil {
+	_, placed, err := placeDocument(body, placementDestination, body.Location, maxDocumentDepth, maxDocumentNodes)
-		versionLocation := publicLocation(versionNode.Location)
+	if err != nil {
-		return []Diagnostic{{
+		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the source depth or node limit after destination placement", &location)}
-			Code: CodeImportVersion, Severity: SeverityError, Path: s.rule.Path.clone(),
-			Message: "imported fragments cannot contribute to the schema-version path", Primary: &versionLocation,
-		}}
 	}
-
+	placementNodes := destinationWrapperNodeCount(placementDestination)
+	if s.accounting.nodes+placementNodes > s.limits.nodes {
+		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", &location)}
+	}
+	s.accounting.nodes += placementNodes
 	route := importRoute{canonical: canonical, locations: currentRoute.locations}
-	s.documents = append(s.documents, body)
+	s.scope.contributions = append(s.scope.contributions, acquiredContribution{
+		source: cloneSourceInfo(info), payload: body, document: placed,
+		destination: placementDestination.clone(), relativeDestination: relativeDestination.clone(), processing: processing,
+	})
 	s.active[identity] = len(s.stack)
 	s.visited[identity] = route
 	s.stack = append(s.stack, route)
-	diagnostics = s.walkDeclarations(s.access.dir(canonical), declarations, depth)
+	diagnostics = s.walkDeclarations(s.access.dir(canonical), declarations, depth, destination)
 	delete(s.active, identity)
 	s.stack = s.stack[:len(s.stack)-1]
 	return diagnostics
 }
 
+func (s *importTraversal) sourceDestination(destination Path) Path {
+	if !s.itemScope {
+		return destination.clone()
+	}
+	// Until the enclosing item receives its assigned index, only the collection
+	// container is exact. Keep the local suffix in the acquisition projection.
+	return s.itemFallback.clone()
+}
+
+func (s *importTraversal) visitItemSource(canonical string, declaration importDeclaration, destination, relativeDestination Path, depth int, info SourceInfo, body *document.Node, declarations []importDeclaration, processing *sourceVersionProcessingResult) []Diagnostic {
+	parentScope := s.scope
+	parentItemScope, parentPrefix, parentFallback := s.itemScope, s.itemPrefix, s.itemFallback
+	s.scope = acquisitionScope{}
+	s.itemScope = true
+	if parentItemScope {
+		s.itemPrefix = appendDestination(parentPrefix, destination)
+	} else {
+		s.itemPrefix = destination.clone()
+		s.itemFallback = destination.clone()
+	}
+	s.scope.contributions = append(s.scope.contributions, acquiredContribution{
+		source: cloneSourceInfo(info), payload: body, document: body,
+		processing: processing,
+	})
+	diagnostics := s.walkDeclarations(s.access.dir(canonical), declarations, depth, Path{})
+	itemScope := s.scope
+	s.scope, s.itemScope, s.itemPrefix, s.itemFallback = parentScope, parentItemScope, parentPrefix, parentFallback
+	if len(diagnostics) != 0 {
+		return projectItemDiagnosticPaths(diagnostics, parentScope, destination)
+	}
+	documents := make([]*document.Node, 0, len(itemScope.contributions))
+	for _, contribution := range itemScope.contributions {
+		documents = append(documents, contribution.document)
+	}
+	completed, diagnostics := composeDocuments(documents...)
+	if len(diagnostics) != 0 {
+		return projectItemDiagnosticPaths(diagnostics, parentScope, destination)
+	}
+	itemScope.destination = Path{}
+	completed.acquisition = []acquisitionScope{cloneAcquisitionScope(itemScope)}
+	projectNestedEvidence(completed, itemScope)
+	pl := destination
+	_, placed, err := placeDocumentWithMode(completed.root, pl, placementModeSequenceItem, body.Location, maxDocumentDepth, maxDocumentNodes)
+	if err != nil {
+		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the source depth or node limit after destination placement", &declaration.location)}
+	}
+	placementNodes := destinationWrapperNodeCountForMode(pl, placementModeSequenceItem)
+	if s.accounting.nodes+placementNodes > s.limits.nodes {
+		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", &declaration.location)}
+	}
+	s.accounting.nodes += placementNodes
+	s.scope.contributions = append(s.scope.contributions, acquiredContribution{
+		source: cloneSourceInfo(info), payload: completed.root, document: placed,
+		destination: pl.clone(), relativeDestination: relativeDestination.clone(), processing: processing,
+		nested: completed,
+	})
+	return nil
+}
+
+func importedVersionClaim(documents []*document.Node, composed *composedDocument, rule *VersionRule, mainIndex int) *Diagnostic {
+	if composed == nil || rule == nil {
+		return nil
+	}
+	ranges := indexSequenceRanges(composed.sequenceRanges)
+	for index, contribution := range documents {
+		if index == mainIndex {
+			continue
+		}
+		if node := fragmentVersionClaimWithIndex(contribution, rule, index, ranges); node != nil {
+			location := publicLocation(node.Location)
+			return &Diagnostic{
+				Code: CodeImportVersion, Severity: SeverityError, Path: rule.Path.clone(),
+				Message: "imported fragments cannot contribute to the schema-version path", Primary: &location,
+			}
+		}
+	}
+	return nil
+}
+
+func prependCompositionDiagnosticPaths(diagnostics []Diagnostic, prefix Path) []Diagnostic {
+	cloned := append([]Diagnostic(nil), diagnostics...)
+	for index := range cloned {
+		if !isCompositionDiagnostic(cloned[index]) {
+			continue
+		}
+		cloned[index].Path = appendDestination(prefix, cloned[index].Path)
+		cloned[index].Primary = cloneLocation(cloned[index].Primary)
+		cloned[index].Related = cloneLocations(cloned[index].Related)
+	}
+	return cloned
+}
+
+func isCompositionDiagnostic(diagnostic Diagnostic) bool {
+	return diagnostic.Code == CodeComposeConflict || diagnostic.Code == CodeComposeInvalid
+}
+
+// On a composition failure only the earlier contributions are needed to locate
+// this item. Project one enclosing scope at a time as traversal unwinds; syntax
+// and access diagnostics keep their original source-local coordinates.
+func projectItemDiagnosticPaths(diagnostics []Diagnostic, parent acquisitionScope, destination Path) []Diagnostic {
+	for _, diagnostic := range diagnostics {
+		if isCompositionDiagnostic(diagnostic) {
+			index := priorSequenceLength([]acquisitionScope{parent}, destination)
+			return prependCompositionDiagnosticPaths(diagnostics, destination.Index(index))
+		}
+	}
+	return diagnostics
+}
+
+// This scan is confined to failed loads, not the successful construction path.
+func priorSequenceLength(scopes []acquisitionScope, path Path) int {
+	length := 0
+	for _, scope := range scopes {
+		for _, contribution := range scope.contributions {
+			if node, present := documentAtPath(contribution.document, path); present && node.Kind == document.Sequence {
+				length += len(node.Sequence)
+			}
+		}
+	}
+	return length
+}
+
+func projectPriorInputDiagnosticPaths(diagnostics []Diagnostic, scopes []acquisitionScope) []Diagnostic {
+	cloned := cloneDiagnostics(diagnostics)
+	for index := range cloned {
+		if !isCompositionDiagnostic(cloned[index]) {
+			continue
+		}
+		for position, segment := range cloned[index].Path.segments {
+			if segment.kind != pathSegmentIndex {
+				continue
+			}
+			container := Path{segments: cloned[index].Path.segments[:position]}
+			cloned[index].Path.segments[position].index += priorSequenceLength(scopes, container)
+			// Registration does not address paths through item indexes. A prior
+			// input shifts the outer collection, not its item-local sequences.
+			break
+		}
+	}
+	return cloned
+}
+
+func projectNestedEvidence(composed *composedDocument, scope acquisitionScope) {
+	if composed == nil {
+		return
+	}
+	applications := composed.applications
+	projectedApplications := make([]historyApplication, 0, len(applications))
+	ranges := indexSequenceRanges(composed.sequenceRanges)
+	for sourceIndex, contribution := range scope.contributions {
+		if contribution.nested == nil {
+			projectedApplications = append(projectedApplications, applications[sourceIndex])
+			continue
+		}
+		start := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: contribution.destination.String()}].start
+		prefix := contribution.destination.Index(start)
+		if sourceIndex < len(applications) {
+			outer := applications[sourceIndex]
+			structural := document.Clone(outer.value)
+			if node, found := documentAtPath(structural, contribution.destination); found && node.Kind == document.Sequence && len(node.Sequence) > 0 {
+				// The retained fragment is still a local singleton. Its assigned
+				// outer index belongs to the projection, not this source tree.
+				node.Sequence[0] = &document.Node{Kind: document.Mapping, Location: node.Sequence[0].Location}
+			}
+			outer.value = structural
+			projectedApplications = append(projectedApplications, outer)
+			for _, nested := range contribution.nested.applications {
+				projected := nested
+				projected.path = appendDestination(prefix, nested.path)
+				projected.sequences = cloneSequenceHistoryContributions(nested.sequences)
+				projected.sequencesByPath = indexSequenceHistoryContributions(projected.sequences)
+				projectedApplications = append(projectedApplications, projected)
+			}
+		}
+		projectNestedOrigins(composed.origins, contribution.nested.root, contribution.nested.origins, prefix)
+	}
+	composed.applications = projectedApplications
+}
+
+func projectNestedOrigins(target map[string]Origin, root *document.Node, origins map[string]Origin, prefix Path) {
+	var visit func(*document.Node, Path)
+	visit = func(node *document.Node, path Path) {
+		if node == nil {
+			return
+		}
+		if origin, ok := origins[path.String()]; ok {
+			target[appendDestination(prefix, path).String()] = cloneOrigin(origin)
+		}
+		for _, entry := range node.Mapping {
+			visit(entry.Value, path.Key(entry.Key))
+		}
+		for index, child := range node.Sequence {
+			visit(child, path.Index(index))
+		}
+	}
+	visit(root, Path{})
+}
+
+func projectAcquiredDestinations(composed *composedDocument, scope acquisitionScope, sources []SourceInfo) {
+	byID := make(map[string]int, len(sources))
+	for index := range sources {
+		byID[sources[index].ID] = index
+	}
+	var projectScope func(*composedDocument, acquisitionScope, Path, bool, string)
+	projectScope = func(currentComposition *composedDocument, current acquisitionScope, prefix Path, insideItem bool, parentSourceID string) {
+		ranges := indexSequenceRanges(currentComposition.sequenceRanges)
+		for sourceIndex, contribution := range current.contributions {
+			if contribution.source.ID == parentSourceID {
+				continue
+			}
+			contributionPrefix := prefix
+			contributionInsideItem := insideItem
+			start := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: contribution.destination.String()}].start
+			if contribution.source.placementMode == placementModeSequenceItem {
+				container := appendDestination(contributionPrefix, contribution.destination)
+				contribution.source.Destination = container.clone()
+				contribution.source.destinationUnresolved = false
+				current.contributions[sourceIndex].source = cloneSourceInfo(contribution.source)
+				if position, ok := byID[contribution.source.ID]; ok {
+					sources[position].Destination = container
+					sources[position].destinationUnresolved = false
+				}
+				contributionPrefix = appendDestination(container, Path{}.Index(start))
+				contributionInsideItem = true
+				projectSourceVersionEvidence(contribution.processing, contributionPrefix, nil, sourceIndex)
+			} else if contributionInsideItem {
+				exactDestination := appendDestination(contributionPrefix, contribution.destination)
+				contribution.source.Destination = exactDestination.clone()
+				contribution.source.destinationUnresolved = false
+				current.contributions[sourceIndex].source = cloneSourceInfo(contribution.source)
+				if position, ok := byID[contribution.source.ID]; ok {
+					sources[position].Destination = exactDestination
+					sources[position].destinationUnresolved = false
+				}
+				projectSourceVersionEvidence(contribution.processing, exactDestination, nil, sourceIndex)
+			} else {
+				projectSourceVersionEvidence(contribution.processing, contribution.destination, ranges, sourceIndex)
+			}
+			if contribution.nested != nil && contribution.nested.acquisition != nil {
+				for _, nestedScope := range contribution.nested.acquisition {
+					projectScope(contribution.nested, nestedScope, contributionPrefix, contributionInsideItem, contribution.source.ID)
+				}
+			}
+		}
+	}
+	projectScope(composed, scope, Path{}, false, "")
+}
+
+func projectSourceVersionEvidence(processing *sourceVersionProcessingResult, destination Path, ranges sequenceRangeIndex, sourceIndex int) {
+	if processing != nil && processing.evidence != nil {
+		evidence := processing.evidence
+		evidence.destination = destination.clone()
+		// Rebuild from source-local paths on each handoff: an input can be
+		// composed first on its own and then at a different offset in its tier.
+		evidence.projectedPaths = nil
+		paths := evidence.sensitivityPaths()
+		for index, path := range paths {
+			for position := range path.segments {
+				prefix := Path{segments: path.segments[:position]}
+				assigned, found := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: prefix.String()}]
+				if !found {
+					continue
+				}
+				item, ok := schemaIndex(path.segments[position])
+				if ok && path.segments[position].kind != pathSegmentKey {
+					path.segments[position] = pathSegment{kind: pathSegmentIndex, index: assigned.start + item}
+				}
+			}
+			paths[index] = path
+		}
+		evidence.projectedPaths = paths
+	}
+}
+
 func (s *importTraversal) readImport(name, sourceID string, optional bool) ([]byte, bool, *Diagnostic) {
 	remaining := s.limits.bytes - s.accounting.bytes
 	limit := min(int64(maxSourceBytes), remaining)

internal/engine/imports_test.go

@@ -9,6 +9,8 @@ import (
 	"strconv"
 	"strings"
 	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 )
 
 type importTestConfig struct {
@@ -155,6 +157,8 @@ func TestLoadImportDirectiveValidationAndTemporaryGlobGate(t *testing.T) {
 		{name: "two targets", body: "configkit: {imports: [{path: a.yml, glob: '*.yml'}]}\n", code: CodeImportInvalid},
 		{name: "unknown declaration field", body: "configkit: {imports: [{path: a.yml, extra: true}]}\n", code: CodeImportInvalid},
 		{name: "optional kind", body: "configkit: {imports: [{path: a.yml, optional: 'yes'}]}\n", code: CodeImportInvalid},
+		{name: "placement kind", body: "configkit: {imports: [{path: a.yml, placement: true}]}\n", code: CodeImportInvalid},
+		{name: "placement value", body: "configkit: {imports: [{path: a.yml, placement: item}]}\n", code: CodeImportInvalid},
 		{name: "nested directive", body: "nested: {configkit: {}}\n", code: CodeImportInvalid},
 	}
 	for _, test := range tests {
@@ -166,6 +170,434 @@ func TestLoadImportDirectiveValidationAndTemporaryGlobGate(t *testing.T) {
 	}
 }
 
+func TestLoadItemImportComposesHelpersAndNestedItemsInDeclaringScope(t *testing.T) {
+	t.Parallel()
+	type nested struct {
+		Value string `yaml:"value"`
+	}
+	type record struct {
+		ID       string            `yaml:"id"`
+		Name     string            `yaml:"name"`
+		Label    string            `yaml:"label"`
+		Metadata map[string]string `yaml:"metadata"`
+		Children []nested          `yaml:"children"`
+	}
+	type config struct {
+		Items []record `yaml:"items"`
+	}
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: records/item.yml
+      destination: [items]
+      placement: sequence-item
+`)
+	itemPath := writeImportFile(t, directory, "records/item.yml", `configkit:
+  imports:
+    - path: nested/helper.yml
+    - path: child.yml
+      destination: [children]
+      placement: sequence-item
+name: authored
+`)
+	helperPath := writeImportFile(t, directory, "records/nested/helper.yml", `configkit:
+  imports:
+    - path: more.yml
+      destination: [metadata]
+id: supplied
+label: helper
+`)
+	morePath := writeImportFile(t, directory, "records/nested/more.yml", "flavor: transitive\n")
+	childPath := writeImportFile(t, directory, "records/child.yml", "value: nested\n")
+
+	result, err := testLoad[config](File(mainPath), Options[config]{Imports: true})
+	if err != nil {
+		t.Fatalf("load item import: %v", err)
+	}
+	if len(result.Config.Items) != 1 {
+		t.Fatalf("items = %#v", result.Config.Items)
+	}
+	item := result.Config.Items[0]
+	if item.ID != "supplied" || item.Name != "authored" || item.Label != "helper" || item.Metadata["flavor"] != "transitive" || len(item.Children) != 1 || item.Children[0].Value != "nested" {
+		t.Fatalf("composed item = %#v", item)
+	}
+	if got := result.Sources(); len(got) != 5 || got[1].Path != canonicalTestPath(t, itemPath) || got[2].Path != canonicalTestPath(t, helperPath) || got[3].Path != canonicalTestPath(t, morePath) || got[4].Path != canonicalTestPath(t, childPath) {
+		t.Fatalf("source traversal = %#v", got)
+	}
+	for _, test := range []struct {
+		index int
+		want  string
+	}{
+		{index: 1, want: "/items"},
+		{index: 2, want: "/items/0"},
+		{index: 3, want: "/items/0/metadata"},
+		{index: 4, want: "/items/0/children"},
+	} {
+		if got := result.Sources()[test.index].Destination.String(); got != test.want {
+			t.Errorf("source %d destination = %q, want %q", test.index+1, got, test.want)
+		}
+	}
+	for _, test := range []struct {
+		path     Path
+		sourceID string
+	}{
+		{path: Keys("items").Index(0).Key("id"), sourceID: "source-3"},
+		{path: Keys("items").Index(0).Key("metadata").Key("flavor"), sourceID: "source-4"},
+	} {
+		info, ok := result.Metadata().Lookup(test.path)
+		if !ok || !info.Explicit || len(info.Origin.Locations) != 1 || info.Origin.Locations[0].SourceID != test.sourceID {
+			t.Errorf("origin at %s = %#v, %v, want source %s", test.path.String(), info, ok, test.sourceID)
+		}
+		foundInHistory := false
+		for _, change := range result.Metadata().History(test.path) {
+			for _, location := range change.Origin.Locations {
+				foundInHistory = foundInHistory || location.SourceID == test.sourceID
+			}
+		}
+		if !foundInHistory {
+			t.Errorf("history at %s does not retain source %s", test.path.String(), test.sourceID)
+		}
+	}
+
+	t.Run("duplicate helper identity remains a mapping conflict", func(t *testing.T) {
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: item.yml
+      destination: [items]
+      placement: sequence-item
+`)
+		writeImportFile(t, directory, "item.yml", `configkit:
+  imports:
+    - path: helper.yml
+id: authored
+`)
+		writeImportFile(t, directory, "helper.yml", "id: supplied\n")
+		_, err := testLoad[config](File(mainPath), Options[config]{Imports: true})
+		var loadError *LoadError
+		if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 {
+			t.Fatalf("duplicate identity error = %v", err)
+		}
+		diagnostic := loadError.Diagnostics()[0]
+		if diagnostic.Code != CodeComposeConflict || diagnostic.Path.String() != "/items/0/id" || diagnostic.Primary == nil || len(diagnostic.Related) != 1 {
+			t.Fatalf("duplicate identity diagnostic = %#v", diagnostic)
+		}
+	})
+}
+
+func TestLayeredUnderlayItemImportRetainsNestedEvidenceAndDestinations(t *testing.T) {
+	t.Parallel()
+	type nested struct {
+		Value string `yaml:"value"`
+	}
+	type record struct {
+		ID       string            `yaml:"id"`
+		Name     string            `yaml:"name"`
+		Label    string            `yaml:"label"`
+		Metadata map[string]string `yaml:"metadata"`
+		Children []nested          `yaml:"children"`
+	}
+	type config struct {
+		Catalog struct {
+			Entries []record `yaml:"entries"`
+		} `yaml:"catalog"`
+	}
+
+	directory := t.TempDir()
+	itemPath := writeImportFile(t, directory, "records/item.yml", `configkit:
+  imports:
+    - path: nested/helper.yml
+    - path: children/child.yml
+      destination: [children]
+      placement: sequence-item
+name: authored
+`)
+	helperPath := writeImportFile(t, directory, "records/nested/helper.yml", `configkit:
+  imports:
+    - path: more.yml
+      destination: [metadata]
+id: supplied
+label: helper
+`)
+	morePath := writeImportFile(t, directory, "records/nested/more.yml", "flavor: transitive\n")
+	childPath := writeImportFile(t, directory, "records/children/child.yml", "value: nested\n")
+
+	loaded, err := LoadLayered(
+		Input{Source: NoSource()}, testSecretBinding(),
+		LayeredOptions[config]{Underlays: []Underlay{{Inputs: []Input{{
+			Source: File(itemPath), Imports: true, Destination: Keys("catalog", "entries"), placementMode: placementModeSequenceItem,
+		}}}}},
+	)
+	if err != nil {
+		if loadError, ok := err.(*LoadError); ok {
+			t.Fatalf("LoadLayered: %v, diagnostics %#v", err, loadError.Diagnostics())
+		}
+		t.Fatalf("LoadLayered: %v", err)
+	}
+	result := testLoaded(loaded)
+	if len(result.Config.Catalog.Entries) != 1 || result.Config.Catalog.Entries[0].ID != "supplied" || result.Config.Catalog.Entries[0].Name != "authored" ||
+		result.Config.Catalog.Entries[0].Label != "helper" || result.Config.Catalog.Entries[0].Metadata["flavor"] != "transitive" ||
+		len(result.Config.Catalog.Entries[0].Children) != 1 || result.Config.Catalog.Entries[0].Children[0].Value != "nested" {
+		t.Fatalf("underlay item = %#v", result.Config.Catalog.Entries)
+	}
+
+	sources := result.Sources()
+	wantSources := []struct {
+		path        string
+		destination string
+	}{
+		{path: itemPath, destination: "/catalog/entries"},
+		{path: helperPath, destination: "/catalog/entries/0"},
+		{path: morePath, destination: "/catalog/entries/0/metadata"},
+		{path: childPath, destination: "/catalog/entries/0/children"},
+	}
+	if len(sources) != len(wantSources) {
+		t.Fatalf("sources = %#v", sources)
+	}
+	for index, want := range wantSources {
+		if sources[index].Path != canonicalTestPath(t, want.path) || sources[index].Destination.String() != want.destination {
+			t.Errorf("source %d = %#v, want path %q and destination %q", index+1, sources[index], want.path, want.destination)
+		}
+	}
+
+	for _, test := range []struct {
+		path     Path
+		sourceID string
+	}{
+		{path: Keys("catalog", "entries").Index(0).Key("id"), sourceID: "source-2"},
+		{path: Keys("catalog", "entries").Index(0).Key("metadata").Key("flavor"), sourceID: "source-3"},
+		{path: Keys("catalog", "entries").Index(0).Key("children").Index(0).Key("value"), sourceID: "source-4"},
+	} {
+		info, ok := result.Metadata().Lookup(test.path)
+		if !ok || !info.Explicit || len(info.Origin.Locations) != 1 || info.Origin.Locations[0].SourceID != test.sourceID || info.Origin.Layer != LayerUnderlay {
+			t.Errorf("origin at %s = %#v, %v, want %s in underlay", test.path.String(), info, ok, test.sourceID)
+		}
+		foundInHistory := false
+		for _, change := range result.Metadata().History(test.path) {
+			for _, location := range change.Origin.Locations {
+				foundInHistory = foundInHistory || location.SourceID == test.sourceID
+			}
+		}
+		if !foundInHistory {
+			t.Errorf("history at %s does not retain source %s", test.path.String(), test.sourceID)
+		}
+	}
+}
+
+func TestLoadItemGlobKeepsDefaultModeIndependentAndOptionalMissesAbsent(t *testing.T) {
+	t.Parallel()
+	type item struct {
+		Value string `yaml:"value"`
+	}
+	type config struct {
+		Items []item            `yaml:"items"`
+		Other map[string]string `yaml:"other"`
+	}
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - glob: records/*.yml
+      destination: [items]
+      placement: sequence-item
+    - path: absent/*.yml
+      destination: [items]
+      optional: true
+      placement: sequence-item
+    - path: other.yml
+      destination: [other]
+`)
+	emptyPath := writeImportFile(t, directory, "records/empty.yml", "{}\n")
+	writeImportFile(t, directory, "other.yml", "value: mapping-default\n")
+	result, err := testLoad[config](File(mainPath), Options[config]{Imports: true})
+	if err != nil {
+		t.Fatalf("load item glob: %v", err)
+	}
+	if len(result.Config.Items) != 1 || result.Config.Items[0].Value != "" || result.Config.Other["value"] != "mapping-default" {
+		t.Fatalf("config = %#v", result.Config)
+	}
+	sources := result.Sources()
+	if len(sources) != 3 || sources[1].Path != canonicalTestPath(t, emptyPath) || sources[1].Destination.String() != "/items" || sources[1].placementMode != placementModeSequenceItem || sources[2].placementMode != placementModeMapping || sources[2].Destination.String() != "/other" {
+		t.Fatalf("source placement evidence = %#v", sources)
+	}
+}
+
+func TestLoadMainItemPlacementKeepsItsHelpersInTheItem(t *testing.T) {
+	t.Parallel()
+	type item struct {
+		ID    string `yaml:"id"`
+		Value string `yaml:"value"`
+	}
+	type config struct {
+		Items []item `yaml:"items"`
+	}
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", "configkit:\n  imports:\n    - path: helper.yml\nid: main\n")
+	helperPath := writeImportFile(t, directory, "helper.yml", "value: helper\n")
+	result, err := testLoad[config](File(mainPath), Options[config]{
+		Imports: true, destination: Keys("items"), placementMode: placementModeSequenceItem,
+	})
+	if err != nil {
+		t.Fatalf("load main item: %v", err)
+	}
+	if len(result.Config.Items) != 1 || result.Config.Items[0].ID != "main" || result.Config.Items[0].Value != "helper" {
+		t.Fatalf("main item = %#v", result.Config.Items)
+	}
+	sources := result.Sources()
+	if len(sources) != 2 || sources[0].Destination.String() != "/items" || sources[0].placementMode != placementModeSequenceItem || sources[1].Destination.String() != "/items/0" || sources[1].placementMode != placementModeMapping {
+		t.Fatalf("main item sources = %#v", sources)
+	}
+	if sources[1].Path != canonicalTestPath(t, helperPath) {
+		t.Fatalf("helper path = %q", sources[1].Path)
+	}
+}
+
+func TestItemImportCanJoinAnAuthoredListUnderRegisteredComposition(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		Items []map[string]string `yaml:"items"`
+	}
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: item.yml
+      destination: [items]
+      placement: sequence-item
+`)
+	writeImportFile(t, directory, "item.yml", "configkit: {imports: [{path: helper.yml}]}\nname: imported\n")
+	writeImportFile(t, directory, "helper.yml", "id: helper-id\n")
+	input, diagnostics := assembleBaseInput(File(mainPath), Options[config]{Imports: true})
+	if len(diagnostics) != 0 {
+		t.Fatalf("assemble item import: %#v", diagnostics)
+	}
+	authored := parseDocumentForDecode(t, "items: [{id: authored-id, name: authored}]\n")
+	composed, diagnostics := composeDocumentsWithPolicy(sequencePolicy{identityFields: map[string]string{"/items": "id"}}, authored, input.document)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose authored and imported lists: %#v", diagnostics)
+	}
+	items, ok := documentAtPath(composed.root, Keys("items"))
+	if !ok || items.Kind != document.Sequence || len(items.Sequence) != 2 {
+		t.Fatalf("composed items = %#v", items)
+	}
+	if id, ok := documentAtPath(composed.root, Keys("items").Index(1).Key("id")); !ok || id.Text != "helper-id" {
+		t.Fatalf("imported helper ID = %#v, %v", id, ok)
+	}
+	if origin := composed.origins[Keys("items").Index(1).Key("id").String()]; len(origin.Locations) != 1 || origin.Locations[0].SourceID != "source-3" {
+		t.Fatalf("registered composition origin = %#v", origin)
+	}
+}
+
+func TestParseImportDestinationUsesLiteralStringSegments(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name        string
+		destination string
+		want        Path
+	}{
+		{name: "omitted"},
+		{name: "empty sequence", destination: "      destination: []\n"},
+		{
+			name:        "literal keys",
+			destination: "      destination: ['', '.', '..', 'a/b', '~', '0', configkit2, myextends]\n",
+			want:        Keys("", ".", "..", "a/b", "~", "0", "configkit2", "myextends"),
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			body := "configkit:\n  imports:\n    - path: child.yml\n" + test.destination
+			declarations := parseImportDeclarationsYAML(t, body)
+			if len(declarations) != 1 {
+				t.Fatalf("declarations = %#v", declarations)
+			}
+			got := declarations[0].destination
+			if got.String() != test.want.String() {
+				t.Fatalf("destination = %q, want %q", got.String(), test.want.String())
+			}
+			for index, segment := range got.segments {
+				if segment.kind != pathSegmentKey {
+					t.Errorf("segment %d kind = %v, want mapping key", index, segment.kind)
+				}
+			}
+		})
+	}
+}
+
+func TestParseImportPlacementDefaultsPerDeclaration(t *testing.T) {
+	t.Parallel()
+	declarations := parseImportDeclarationsYAML(t, `configkit:
+  imports:
+    - path: mapping.yml
+    - glob: records/*.yml
+      placement: sequence-item
+`)
+	if len(declarations) != 2 || declarations[0].placement != placementModeMapping || declarations[1].placement != placementModeSequenceItem {
+		t.Fatalf("declaration placements = %#v", declarations)
+	}
+}
+
+func TestParseImportDestinationRejectsInvalidShapesAndMembers(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name      string
+		value     string
+		wantPath  string
+		badMember string
+	}{
+		{name: "null", value: "null", wantPath: "/configkit/imports/0/destination", badMember: "null"},
+		{name: "scalar string", value: "prompts", wantPath: "/configkit/imports/0/destination", badMember: "prompts"},
+		{name: "number", value: "3", wantPath: "/configkit/imports/0/destination", badMember: "3"},
+		{name: "non-string number", value: "[valid, 7]", wantPath: "/configkit/imports/0/destination/1", badMember: "7"},
+		{name: "non-string null", value: "[valid, null]", wantPath: "/configkit/imports/0/destination/1", badMember: "null"},
+		{name: "non-string boolean", value: "[valid, true]", wantPath: "/configkit/imports/0/destination/1", badMember: "true"},
+		{name: "non-string mapping", value: "[valid, {key: value}]", wantPath: "/configkit/imports/0/destination/1", badMember: "{key"},
+		{name: "reserved configkit", value: "[valid, configkit]", wantPath: "/configkit/imports/0/destination/1", badMember: "configkit"},
+		{name: "reserved extends", value: "[valid, extends]", wantPath: "/configkit/imports/0/destination/1", badMember: "extends"},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			body := "configkit:\n  imports:\n    - path: child.yml\n      destination: " + test.value + "\n"
+			parsed, diagnostics := parseImportDeclarationYAML(body)
+			if len(diagnostics) != 1 || diagnostics[0].Code != CodeImportInvalid || diagnostics[0].Path.String() != test.wantPath {
+				t.Fatalf("parse = %#v, want import.invalid at %q", diagnostics, test.wantPath)
+			}
+			line := strings.Split(body, "\n")[3]
+			wantColumn := strings.Index(line, test.badMember) + 1
+			if diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-1" || diagnostics[0].Primary.Line != 4 || diagnostics[0].Primary.Column != wantColumn {
+				t.Fatalf("invalid destination location = %#v, want line 4 column %d (parsed %v)", diagnostics[0].Primary, wantColumn, parsed)
+			}
+		})
+	}
+}
+
+func TestImportDestinationValidationPrecedesOptionalSuppression(t *testing.T) {
+	t.Parallel()
+
+	for _, test := range []struct {
+		name string
+		body string
+		path string
+	}{
+		{
+			name: "optional missing path",
+			body: "configkit:\n  imports:\n    - path: absent.yml\n      optional: true\n      destination: null\n",
+			path: "/configkit/imports/0/destination",
+		},
+		{
+			name: "optional unmatched glob",
+			body: "configkit:\n  imports:\n    - glob: absent/*.yml\n      optional: true\n      destination: [extends]\n",
+			path: "/configkit/imports/0/destination/0",
+		},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", test.body)
+			loadError := requireLoadCode(t, File(mainPath), Options[importTestConfig]{Imports: true}, CodeImportInvalid)
+			if diagnostics := loadError.Diagnostics(); diagnostics[0].Path.String() != test.path {
+				t.Fatalf("diagnostic path = %q, want %q", diagnostics[0].Path.String(), test.path)
+			}
+		})
+	}
+}
+
 func TestLoadImportMissingContainmentAndRegularFileRules(t *testing.T) {
 	t.Run("optional missing", func(t *testing.T) {
 		directory := t.TempDir()
@@ -486,3 +918,21 @@ func parseImportMain(t *testing.T, filename string) parsedSource {
 	}
 	return parsed
 }
+
+func parseImportDeclarationsYAML(t *testing.T, input string) []importDeclaration {
+	t.Helper()
+	declarations, diagnostics := parseImportDeclarationYAML(input)
+	if len(diagnostics) != 0 {
+		t.Fatalf("import parse diagnostics = %#v", diagnostics)
+	}
+	return declarations
+}
+
+func parseImportDeclarationYAML(input string) ([]importDeclaration, []Diagnostic) {
+	parsed, diagnostics := parseSource(Bytes("import fixture", []byte(input)), "source-1", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	_, declarations, diagnostics := splitImportDirectives(parsed.document)
+	return declarations, diagnostics
+}

internal/engine/inheritance_history.go

@@ -1,6 +1,57 @@
 package engine
 
-import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+import (
+	"sort"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type inheritanceHistoryIndex struct {
+	paths pathPrefixIndex
+}
+
+func newInheritanceHistoryIndex(operations []inheritanceOperation) *inheritanceHistoryIndex {
+	if len(operations) == 0 {
+		return nil
+	}
+	index := &inheritanceHistoryIndex{}
+	for operationID, operation := range operations {
+		if operation.control != nil {
+			index.paths.insert(operation.control.path.String(), operationID)
+			continue
+		}
+		if operation.transfer != nil {
+			index.paths.insert(operation.transfer.to.String(), operationID)
+		}
+	}
+	return index
+}
+
+func (index *inheritanceHistoryIndex) matchingOperations(path Path, operations []inheritanceOperation) []inheritanceOperation {
+	if index == nil {
+		return operations
+	}
+	var ids []int
+	seen := make(map[int]struct{})
+	collect := func(id int) {
+		if _, found := seen[id]; found {
+			return
+		}
+		seen[id] = struct{}{}
+		ids = append(ids, id)
+	}
+	pointer := path.String()
+	index.paths.visitAncestors(pointer, collect)
+	index.paths.visitDescendants(pointer, collect)
+	sort.Ints(ids)
+	matching := make([]inheritanceOperation, 0, len(ids))
+	for _, id := range ids {
+		if id >= 0 && id < len(operations) {
+			matching = append(matching, operations[id])
+		}
+	}
+	return matching
+}
 
 // Retain source history at original paths. Structural operations are held once
 // per relationship and projected onto a requested destination path only when

internal/engine/inheritance_history_test.go

@@ -2,6 +2,7 @@ package engine
 
 import (
 	"bytes"
+	"reflect"
 	"strings"
 	"testing"
 
@@ -311,6 +312,51 @@ func TestInheritanceHistoryRetainsControlsAndDisplacedPaths(t *testing.T) {
 	}
 }
 
+func TestIndexedInheritanceHistoryMatchesOperationScan(t *testing.T) {
+	inspection, _ := inheritanceInspectionForTest(t,
+		parseCompositionDocument(t, "source-1", "parent: {branch: {detail: inherited, retained: present}}\n"),
+		parseCompositionDocument(t, "source-2", "child: {extends: parent, branch: replaced}\n"),
+		parseCompositionDocument(t, "source-3", "sibling: {extends: parent}\n"))
+	metadata := inspection.Metadata()
+	if len(metadata.inheritance) < 4 {
+		t.Fatalf("inheritance operations = %d, want multiple control and transfer scopes", len(metadata.inheritance))
+	}
+	queries := []Path{
+		Keys("child"),
+		Keys("child", inheritanceKey),
+		Keys("child", "branch", "detail"),
+		Keys("child", "branch"),
+		Keys("sibling", "branch", "detail"),
+		Path{},
+	}
+	for _, path := range queries {
+		if !metadata.hasHistoricalPath(path) {
+			continue
+		}
+		stored := metadata.history[path.String()]
+		want := historyWithInheritance(path, stored, metadata.inheritance)
+		if got := metadata.History(path); !reflect.DeepEqual(got, want) {
+			t.Errorf("indexed history for %s differs from operation scan:\n got: %#v\nwant: %#v", path, got, want)
+		}
+		unprepared := Metadata{history: metadata.history, historicalPaths: metadata.historicalPaths, inheritance: metadata.inheritance}
+		if got := unprepared.History(path); !reflect.DeepEqual(got, want) {
+			t.Errorf("unprepared history for %s differs from operation scan:\n got: %#v\nwant: %#v", path, got, want)
+		}
+	}
+
+	removed := Keys("child", "branch", "detail")
+	first := metadata.History(removed)
+	if len(first) == 0 || len(first[0].Path.segments) == 0 {
+		t.Fatalf("removed-path history = %#v", first)
+	}
+	first[0].Path.segments[0].key = "mutated"
+	second := cloneMetadata(metadata).History(removed)
+	want := historyWithInheritance(removed, metadata.history[removed.String()], metadata.inheritance)
+	if !reflect.DeepEqual(second, want) {
+		t.Fatalf("returned history mutation affected a repeated or cloned query:\n got: %#v\nwant: %#v", second, want)
+	}
+}
+
 func TestInheritanceHistoryPrecedesApplicationResolution(t *testing.T) {
 	inspection, _ := inheritanceInspectionForTest(t,
 		parseCompositionDocument(t, "source-1", "parent: {value: original}\nchild: {extends: parent}\n"))
@@ -324,6 +370,7 @@ func TestInheritanceHistoryPrecedesApplicationResolution(t *testing.T) {
 	replaceHistoryPath(&final, path, replacement)
 	inspection.final = final
 	inspection.resolution = []resolutionSnapshot{snapshot}
+	inspection.resolutionReplay = coalescedResolutionSnapshots(inspection.resolution)
 	inspection.metadata.history[path.String()] = append(inspection.metadata.history[path.String()], snapshot.change)
 	inspection.metadata.fields[path.String()] = FieldInfo{Explicit: true, Origin: snapshot.change.Origin}
 	history := inspection.Metadata().History(path)

internal/engine/inheritance_load.go

@@ -3,14 +3,28 @@ package engine
 import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 
 func containsInheritanceDirective(root *document.Node) bool {
-	found := false
+	var visit func(*document.Node) bool
-	walkDocument(root, Path{}, func(path Path, _ *document.Node) {
+	visit = func(node *document.Node) bool {
-		if len(path.segments) != 0 && path.segments[len(path.segments)-1].kind == pathSegmentKey &&
+		if node == nil {
-			path.segments[len(path.segments)-1].key == inheritanceKey {
+			return false
-			found = true
 		}
-	})
+		switch node.Kind {
-	return found
+		case document.Mapping:
+			for _, entry := range node.Mapping {
+				if entry.Key == inheritanceKey || visit(entry.Value) {
+					return true
+				}
+			}
+		case document.Sequence:
+			for _, child := range node.Sequence {
+				if visit(child) {
+					return true
+				}
+			}
+		}
+		return false
+	}
+	return visit(root)
 }
 
 func inheritanceVersionDiagnostic(rule *VersionRule, expanded *inheritanceScope) *Diagnostic {
@@ -27,7 +41,7 @@ func inheritanceVersionDiagnostic(rule *VersionRule, expanded *inheritanceScope)
 			}
 		} else if operation.transfer != nil {
 			if relative, within := relativeHistoryPath(operation.transfer.to, rule.Path); within {
-				_, affected = documentAtPath(operation.parent, relative)
+				affected = fragmentVersionClaim(operation.parent, &VersionRule{Path: relative}) != nil
 			} else if pathContains(rule.Path, operation.transfer.to) {
 				affected = true
 			}

internal/engine/inheritance_origin.go

@@ -2,6 +2,7 @@ package engine
 
 import (
 	"slices"
+	"strconv"
 
 	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 )
@@ -74,10 +75,44 @@ func copyInheritanceSubtree(target, incoming map[string]Origin, node *document.N
 	})
 }
 
+type inheritanceStepKey struct {
+	from      string
+	to        string
+	reference string
+	locations string
+}
+
+func inheritanceStepKeyForPaths(from, to, reference Path, locations []Location) inheritanceStepKey {
+	return inheritanceStepKey{
+		from: from.String(), to: to.String(), reference: reference.String(),
+		locations: inheritanceLocationsKey(locations),
+	}
+}
+
+func inheritanceLocationsKey(locations []Location) string {
+	encoded := strconv.AppendInt(nil, int64(len(locations)), 10)
+	encoded = append(encoded, ';')
+	for _, location := range locations {
+		encoded = strconv.AppendInt(encoded, int64(len(location.SourceID)), 10)
+		encoded = append(encoded, ':')
+		encoded = append(encoded, location.SourceID...)
+		encoded = append(encoded, ';')
+		encoded = strconv.AppendInt(encoded, int64(location.Line), 10)
+		encoded = append(encoded, ';')
+		encoded = strconv.AppendInt(encoded, int64(location.Column), 10)
+		encoded = append(encoded, ';')
+	}
+	return string(encoded)
+}
+
 // Materialize concrete steps only for an inspection record. The linked private
 // traces remain compact when one parent supplies many descendant values.
 func projectInheritanceSteps(origin Origin) []InheritanceStep {
 	steps := cloneInheritanceSteps(origin.Inheritance)
+	seen := make(map[inheritanceStepKey]struct{}, len(steps))
+	for _, step := range steps {
+		seen[inheritanceStepKeyForPaths(step.From, step.To, step.Reference, step.Locations)] = struct{}{}
+	}
 	for _, contributor := range origin.contributors {
 		var reverse []*inheritanceTrace
 		for link := contributor.trace; link != nil; link = link.previous {
@@ -91,17 +126,13 @@ func projectInheritanceSteps(origin Origin) []InheritanceStep {
 				continue
 			}
 			next := appendInheritancePath(transfer.to, relative)
-			step := InheritanceStep{
+			key := inheritanceStepKeyForPaths(current, next, transfer.reference, transfer.locations)
-				From: current.clone(), To: next.clone(), Reference: transfer.reference.clone(),
+			if _, found := seen[key]; !found {
-				Locations: cloneLocations(transfer.locations),
+				seen[key] = struct{}{}
-			}
+				steps = append(steps, InheritanceStep{
-			if !slices.ContainsFunc(steps, func(existing InheritanceStep) bool {
+					From: current.clone(), To: next.clone(), Reference: transfer.reference.clone(),
-				return existing.From.String() == step.From.String() &&
+					Locations: cloneLocations(transfer.locations),
-					existing.To.String() == step.To.String() &&
+				})
-					existing.Reference.String() == step.Reference.String() &&
-					slices.Equal(existing.Locations, step.Locations)
-			}) {
-				steps = append(steps, step)
 			}
 			current = next
 		}

internal/engine/inheritance_origin_test.go

@@ -2,6 +2,8 @@ package engine
 
 import (
 	"io/fs"
+	"reflect"
+	"slices"
 	"testing"
 	"testing/fstest"
 
@@ -85,6 +87,165 @@ func TestInheritedOriginsKeepSourcePathsPresenceAndIndependentReplacement(t *tes
 	}
 }
 
+func TestOriginMembershipPreservesLocationAndSourceCoverageRules(t *testing.T) {
+	location := Location{SourceID: "source", Line: 4, Column: 2}
+	otherCoordinates := location
+	otherCoordinates.Line++
+
+	container := Origin{
+		Layer:     LayerOverlay,
+		Operation: ChangeNormalization,
+		Locations: []Location{location},
+	}
+	if !originContainedBy(container, container) {
+		t.Fatal("identical location evidence was not contained")
+	}
+	coordinateDifference := container
+	coordinateDifference.Locations = []Location{otherCoordinates}
+	if originContainedBy(coordinateDifference, container) {
+		t.Fatal("location containment ignored differing coordinates")
+	}
+
+	parent := Keys("parent")
+	child := parent.Key("child")
+	change := Change{Path: parent, Origin: container}
+	descendantOrigin := Origin{
+		Layer:     container.Layer,
+		Operation: container.Operation,
+		Locations: []Location{otherCoordinates},
+	}
+	if !originRepresentedByChange(child, descendantOrigin, change) {
+		t.Fatal("descendant source coverage rejected matching SourceID with different coordinates")
+	}
+	descendantOrigin.Locations[0].SourceID = "another-source"
+	if originRepresentedByChange(child, descendantOrigin, change) {
+		t.Fatal("descendant source coverage accepted an unrecorded SourceID")
+	}
+
+	withContributor := container
+	withContributor.contributors = []inheritanceContributor{{source: parent, location: location}}
+	if originContainedBy(withContributor, container) {
+		t.Fatal("exact location containment ignored the contributor-empty mismatch")
+	}
+	if !originRepresentedByChange(child, withContributor, change) {
+		t.Fatal("descendant source coverage was conflated with contributor containment")
+	}
+}
+
+func TestProjectedInheritanceStepsMatchScanAndRetainOwnership(t *testing.T) {
+	sourcePath := Keys("source", "a/b", "01")
+	firstLocations := []Location{{SourceID: "first;:source", Line: -1, Column: 2}}
+	secondLocations := []Location{
+		{SourceID: "second:;source", Line: 3, Column: -4},
+		{SourceID: "", Line: -5, Column: 6},
+	}
+	firstTransfer := inheritanceTransfer{
+		from: Keys("source"), to: Keys("middle"), reference: Keys("middle", "extends"), locations: firstLocations,
+	}
+	secondTransfer := inheritanceTransfer{
+		from: Keys("middle"), to: Keys("target"), reference: Keys("target", "extends"), locations: secondLocations,
+	}
+	firstTrace := &inheritanceTrace{transfer: &firstTransfer}
+	chain := &inheritanceTrace{previous: firstTrace, transfer: &secondTransfer}
+	firstStep := InheritanceStep{
+		From: sourcePath, To: Keys("middle", "a/b", "01"), Reference: firstTransfer.reference, Locations: firstLocations,
+	}
+
+	duplicateFirstTransfer := firstTransfer
+	duplicateSecondTransfer := secondTransfer
+	duplicateChain := &inheritanceTrace{
+		previous: &inheritanceTrace{transfer: &duplicateFirstTransfer},
+		transfer: &duplicateSecondTransfer,
+	}
+	reversedLocations := []Location{secondLocations[1], secondLocations[0]}
+	reorderedSecondTransfer := secondTransfer
+	reorderedSecondTransfer.locations = reversedLocations
+	reorderedChain := &inheritanceTrace{
+		previous: &inheritanceTrace{transfer: &duplicateFirstTransfer},
+		transfer: &reorderedSecondTransfer,
+	}
+	origin := Origin{
+		Inheritance: []InheritanceStep{firstStep, firstStep},
+		contributors: []inheritanceContributor{
+			{source: sourcePath, trace: chain},
+			{source: sourcePath, trace: duplicateChain},
+			{source: sourcePath, trace: reorderedChain},
+			{source: sourcePath, trace: chain},
+		},
+	}
+
+	want := projectInheritanceStepsByScan(origin)
+	got := projectInheritanceSteps(origin)
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("projected steps differ from ordered scan:\n got: %#v\nwant: %#v", got, want)
+	}
+	if len(got) != 4 || got[0].From.String() != "/source/a~1b/01" || got[0].To.String() != "/middle/a~1b/01" ||
+		!reflect.DeepEqual(got[0], got[1]) || got[2].To.String() != "/target/a~1b/01" ||
+		!reflect.DeepEqual(got[2].Locations, secondLocations) || !reflect.DeepEqual(got[3].Locations, reversedLocations) {
+		t.Fatalf("unexpected duplicate/order/escape projection: %#v", got)
+	}
+
+	got[0].From.segments[0].key = "mutated"
+	got[2].Locations[0].SourceID = "mutated"
+	if repeated := projectInheritanceSteps(origin); !reflect.DeepEqual(repeated, want) {
+		t.Fatalf("returned steps mutated retained evidence:\n got: %#v\nwant: %#v", repeated, want)
+	}
+}
+
+func TestInheritanceLocationsKeyEncodesOrderedLengthPrefixedValues(t *testing.T) {
+	if inheritanceLocationsKey(nil) != inheritanceLocationsKey([]Location{}) {
+		t.Fatal("nil and empty location lists should encode equally")
+	}
+	values := [][]Location{
+		{{SourceID: "a;1;-2;", Line: -3, Column: 4}},
+		{{SourceID: "a", Line: 1, Column: -2}, {SourceID: ";1;-2;", Line: -3, Column: 4}},
+		{{SourceID: ";1;-2;", Line: -3, Column: 4}, {SourceID: "a", Line: 1, Column: -2}},
+		{{SourceID: "é", Line: -3, Column: 4}},
+		{{SourceID: "e", Line: -3, Column: 4}},
+	}
+	keys := make(map[string]int, len(values))
+	for index, locations := range values {
+		key := inheritanceLocationsKey(locations)
+		if previous, found := keys[key]; found {
+			t.Fatalf("location lists %d and %d encoded identically", previous, index)
+		}
+		keys[key] = index
+	}
+}
+
+func projectInheritanceStepsByScan(origin Origin) []InheritanceStep {
+	steps := cloneInheritanceSteps(origin.Inheritance)
+	for _, contributor := range origin.contributors {
+		var reverse []*inheritanceTrace
+		for link := contributor.trace; link != nil; link = link.previous {
+			reverse = append(reverse, link)
+		}
+		current := contributor.source
+		for index := len(reverse) - 1; index >= 0; index-- {
+			transfer := reverse[index].transfer
+			relative, ok := relativeHistoryPath(transfer.from, current)
+			if !ok {
+				continue
+			}
+			next := appendInheritancePath(transfer.to, relative)
+			step := InheritanceStep{
+				From: current.clone(), To: next.clone(), Reference: transfer.reference.clone(),
+				Locations: cloneLocations(transfer.locations),
+			}
+			if !slices.ContainsFunc(steps, func(existing InheritanceStep) bool {
+				return existing.From.String() == step.From.String() &&
+					existing.To.String() == step.To.String() &&
+					existing.Reference.String() == step.Reference.String() &&
+					slices.Equal(existing.Locations, step.Locations)
+			}) {
+				steps = append(steps, step)
+			}
+			current = next
+		}
+	}
+	return steps
+}
+
 func TestInheritedOriginsRetainChainsAndNestedDestinations(t *testing.T) {
 	first := parseCompositionDocument(t, "source-1", `first:
   enabled: false