Retire completed roadmaps before the next release

README.md

@@ -20,7 +20,11 @@ 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.
 
 ```go
 type Config struct {
@@ -64,12 +68,14 @@ 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.
 
-The [configuration contract](docs/config.md) describes implemented behavior. The
-[consumer adoption guide](docs/consumers/README.md) provides maintained simple
-native-filesystem, layered, and sibling-inheritance examples alongside the migration shapes.
-See the [development guide](docs/development.md) for repository orientation and the
-[release procedure](docs/release.md) for maintainer-only candidate and publication
-steps.
+The [configuration contract](docs/config.md) describes implemented behavior,
+including [input destinations](docs/config.md#input-destinations). The
+[consumer adoption guide](docs/consumers/README.md) provides maintained simple,
+layered, and mounted-collection examples alongside the migration shapes. The
+accepted placement decision is recorded in [ADR 0011](docs/adr/0011-input-destinations.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,30 @@ 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), 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)}
+	return 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)}
+}
+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)}

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/config.md

@@ -149,9 +149,46 @@ 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.
 
+#### 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 the placement for each acquired input source,
+including imports. 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. Returned source
+records are detached copies.
+
 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 +306,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
@@ -423,6 +521,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
@@ -711,9 +849,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
-fields are `import.invalid`. A `configkit` key below the root is invalid. With
-imports disabled, any occurrence remains `import.disabled`.
+string `path` or `glob`, an optional boolean `optional`, and an optional
+`destination` sequence of strings. Every destination string is one literal
+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

docs/consumers/README.md

@@ -17,7 +17,10 @@ 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 |
 
 The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
 executable examples and ordinary tests. It contains no private application data,
@@ -51,6 +54,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 +122,47 @@ 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.
+
 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 +242,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,6 +39,8 @@ 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 |
@@ -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
@@ -105,6 +110,29 @@ git show 8e91a2b:docs/roadmap/startup-benchmark.md
 Remaining optimization candidates belong to
 [deferred scope](roadmap/deferred.md#deferred-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.
+Possible follow-ups remain in [deferred scope](roadmap/deferred.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:
@@ -151,17 +179,20 @@ 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'` |

docs/internal/overview.md

@@ -8,11 +8,16 @@ 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
-  sibling inheritance before typed decoding. It also owns schema
+  grouped strict composition, recursive precedence assembly, per-input mapping
+  placement and immediate-parent-relative import placement within that
+  assembly, destination-local sibling inheritance before typed decoding, and
+  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 +26,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 +45,17 @@ 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
-guidance. The [architecture policy](../policy/architecture.md) owns contributor
-boundaries, and [ADR 0006](../adr/0006-public-facade.md) records the facade
+semantics, including [input destinations](../config.md#input-destinations),
+[shared source-version checks](../config.md#shared-source-version-checks), and
+[effective configuration diffs](../config.md#effective-configuration-diffs).
+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.

docs/policy/architecture.md

@@ -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`.
@@ -201,6 +210,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.

docs/release.md

@@ -82,7 +82,7 @@ go list -m gitea.maximumdirect.net/eric/ReleaseKit
 "$releasekit_bin" version
 ```
 
-The module-selected executable is ReleaseKit v0.3.0. Use the built executable
+The module-selected executable is ReleaseKit v0.4.1. Use the built executable
 for publication to preserve its exit status and publication-state diagnostics.
 `go run` maps a nonzero child exit status to 1. ReleaseKit's child Go commands
 use the `go` found on `PATH` with `GOTOOLCHAIN=local`; keep the selected

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/roadmap/deferred.md

@@ -23,16 +23,34 @@ The following remain deliberately excluded:
 - automatic schema migrations;
 - hot reload, runtime resource replacement, and remote resource validation;
 - a bundled CLI framework or application commands; and
-- configuration diffs and fingerprints.
+- configuration 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.
 
+Effective configuration diffs are implemented over frozen successful-load
+inspections; their current comparison and disclosure contract is in the
+[configuration contract](../config.md#effective-configuration-diffs), with
+consumer workflows in the [adoption guide](../consumers/README.md#effective-configuration-diffs).
+Fingerprints remain deferred.
+
 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.
 
+## Possible source-version follow-ups
+
+Independent collection or subtree specification policies were outside the
+completed shared source-version feature and remain possible future work, with
+no committed delivery plan. Current [source-version checks](../config.md#shared-source-version-checks)
+use one application-owned policy across participating documents. Reconsider
+independent policies if concrete consumer needs justify a separate design
+decision; this is not a permanent prohibition. The original request and its
+selected scope remain at `e4270c9:docs/roadmap/promptkit-feature-request.md` in
+Git history. Existing sequence-composition and cross-scope inheritance deferrals
+above also remain unchanged.
+
 ## Deferred performance experiments
 
 The completed performance audit left these internal optimization candidates for

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/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/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_source_version_mode_test.go

@@ -0,0 +1,748 @@
+package configkit_test
+
+import (
+	"bytes"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+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

@@ -5,7 +5,7 @@ go 1.26.0
 require go.yaml.in/yaml/v4 v4.0.0-rc.6
 
 require (
-	gitea.maximumdirect.net/eric/ReleaseKit v0.3.0 // indirect
+	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
 )

go.sum

@@ -1,5 +1,5 @@
-gitea.maximumdirect.net/eric/ReleaseKit v0.3.0 h1:aTMn+50MEpHpHI2RoCCmJYsy7Ohrpa+RSva63Kq0/tU=
-gitea.maximumdirect.net/eric/ReleaseKit v0.3.0/go.mod h1:LVodqNQ3OIKv9NBq+fFeyMByd1lHY25YOmmpah/NaNI=
+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=

internal/engine/destination.go

@@ -0,0 +1,128 @@
+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")
+)
+
+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) {
+	normalized, err := normalizeDestination(destination)
+	if err != nil {
+		return Path{}, nil, err
+	}
+	if body == nil {
+		return normalized, nil, nil
+	}
+	if !destinationWithinLimits(body, normalized, maxDepth, maxNodes) {
+		return normalized, nil, errDestinationLimit
+	}
+
+	placed := body
+	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 {
+	if body == nil {
+		return true
+	}
+	if maxDepth < 0 || maxNodes < 0 || !destination.valid() {
+		return false
+	}
+	segments := len(destination.segments)
+	if segments > maxDepth || segments > maxNodes/2 {
+		return false
+	}
+	wrapperNodes := destinationWrapperNodeCount(destination)
+	for _, segment := range destination.segments {
+		if segment.kind != pathSegmentKey {
+			return false
+		}
+	}
+	if documentDepth(body) > maxDepth-segments {
+		return false
+	}
+	return countInputNodes(body) <= maxNodes-wrapperNodes
+}
+
+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,379 @@
+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 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,568 @@
+package engine
+
+import (
+	"path/filepath"
+	"testing"
+	"testing/fstest"
+)
+
+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)
+		}
+	}
+
+	composed, diagnostics := composeDocuments(state.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,463 @@
+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)
+		}
+	})
+}
+
+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,118 @@
+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"`
+}
+
+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,206 @@
+package engine
+
+import (
+	"errors"
+	"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 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)
+	}
+}

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
-	sources     []SourceInfo
+	diagnostics  []Diagnostic
+	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),
 	}
 }
 

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,11 @@ import (
 const directiveKey = "configkit"
 
 type importDeclaration struct {
-	path     string
-	glob     string
-	optional bool
-	location Location
+	path        string
+	glob        string
+	destination Path
+	optional    bool
+	location    Location
 }
 
 func splitImportDirectives(root *document.Node) (*document.Node, []importDeclaration, []Diagnostic) {
@@ -90,6 +91,27 @@ 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
 		default:
 			return importDeclaration{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, fieldPath, "import declaration field is not recognized", entry.Value)}
 		}

internal/engine/imports.go

@@ -45,10 +45,11 @@ type importAccounting struct {
 }
 
 type importTraversal struct {
-	access     *filesystemAccess
-	accounting *importAccounting
-	limits     importLimits
-	rule       *VersionRule
+	access       *filesystemAccess
+	accounting   *importAccounting
+	limits       importLimits
+	rule         *VersionRule
+	versionState *sourceVersionState
 
 	documents []*document.Node
 	sources   []SourceInfo
@@ -58,16 +59,28 @@ type importTraversal struct {
 }
 
 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)
+}
+
+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) (*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 loadImportedWithAccessTrackedAndProcessing(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, versionState, processing)
 	}
 	rootPath, basePath, mainPath, diagnostic := importFilesystem(source, context, main)
 	if diagnostic != nil {
@@ -82,14 +95,26 @@ func loadImportedDocumentsTracked(source Source, context *FilesystemContext, mai
 	if hostToken != nil {
 		access.token = hostToken
 	}
-	return loadImportedWithAccessTracked(access, basePath, mainPath, main, rule, limits, accounting, visited)
+	return loadImportedWithAccessTrackedAndProcessing(access, basePath, mainPath, main, destination, rule, limits, accounting, visited, versionState, processing)
 }
 
 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) {
 	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 +127,7 @@ func loadImportedWithAccessTracked(access *filesystemAccess, basePath, mainPath
 		}
 	}
 	mainInfo := cloneSourceInfo(*main.source)
+	mainInfo.Destination = destination.clone()
 	if mainPath != "" {
 		mainInfo.Path = mainPath
 	}
@@ -117,7 +143,7 @@ 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),
 		sources:   []SourceInfo{mainInfo},
 		active:    make(map[resourceIdentity]int), visited: visited,
@@ -138,10 +164,27 @@ 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)
-		diagnostics = state.walkDeclarations(basePath, declarations, 0)
+		_, 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.documents = append(state.documents, placed)
+			diagnostics = state.walkDeclarations(basePath, declarations, 0, destination)
+		}
 	}
 
 	closeErr := access.close()
@@ -175,8 +218,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,20 +237,20 @@ 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, 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, 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 Path, depth int) []Diagnostic {
 	location := declaration.location
 	if depth > s.limits.depth {
 		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the active import-depth limit", &location)}
@@ -260,7 +304,7 @@ 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: destination.clone(), Layer: LayerBase, Kind: kind, ImportedFrom: &location}
 	if kind == SourceKindFilesystem {
 		info.namespace = s.access.token
 	}
@@ -287,24 +331,48 @@ func (s *importTraversal) visitPath(basePath string, declaration importDeclarati
 	}
 	s.accounting.nodes += nodeCount
 
-	body, declarations, diagnostics := splitImportDirectives(root)
-	if len(diagnostics) != 0 {
-		return diagnostics
+	var body *document.Node
+	var declarations []importDeclaration
+	var diagnostics []Diagnostic
+	if s.versionState != nil && s.versionState.mode != sourceVersionModeDefault {
+		processed, failures := s.versionState.process(root, sourceVersionContribution, destination, sourceID)
+		if len(failures) != 0 {
+			return failures
+		}
+		body, declarations = processed.payload, processed.imports
+	} else {
+		body, declarations, diagnostics = splitImportDirectives(root)
+		if len(diagnostics) != 0 {
+			return diagnostics
+		}
 	}
-	if versionNode := fragmentVersionClaim(body, s.rule); versionNode != nil {
+	_, placed, err := placeDocument(body, destination, body.Location, maxDocumentDepth, maxDocumentNodes)
+	if err != nil {
+		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the source depth or node limit after destination placement", &location)}
+	}
+	placementNodes := destinationWrapperNodeCount(destination)
+	if s.accounting.nodes+placementNodes > s.limits.nodes {
+		return []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", &location)}
+	}
+	s.accounting.nodes += placementNodes
+	protectionRule := s.rule
+	if s.versionState != nil && s.versionState.effectiveRule != nil {
+		protectionRule = s.versionState.effectiveRule
+	}
+	if versionNode := fragmentVersionClaim(placed, protectionRule); versionNode != nil {
 		versionLocation := publicLocation(versionNode.Location)
 		return []Diagnostic{{
-			Code: CodeImportVersion, Severity: SeverityError, Path: s.rule.Path.clone(),
+			Code: CodeImportVersion, Severity: SeverityError, Path: protectionRule.Path.clone(),
 			Message: "imported fragments cannot contribute to the schema-version path", Primary: &versionLocation,
 		}}
 	}
 
 	route := importRoute{canonical: canonical, locations: currentRoute.locations}
-	s.documents = append(s.documents, body)
+	s.documents = append(s.documents, placed)
 	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

internal/engine/imports_test.go

@@ -166,6 +166,105 @@ func TestLoadImportDirectiveValidationAndTemporaryGlobGate(t *testing.T) {
 	}
 }
 
+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 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 +585,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_load.go

@@ -41,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_secret_test.go

@@ -92,6 +92,40 @@ func TestInheritanceSensitivityIncludesSchemaTaggedSource(t *testing.T) {
 	}
 }
 
+func TestSourceVersionEvidenceSensitivityFollowsInheritanceAndDisplacedHistory(t *testing.T) {
+	const canary = "EVIDENCE-INHERITANCE-CANARY"
+	input := parseCompositionDocument(t, "source-1", "parent: {branch: {token: "+canary+", plain: visible}}\nchild: {extends: parent, branch: public}\n")
+	inspection, _ := inheritanceInspectionForTest(t, input)
+	secretPath := Keys("parent", "branch", "token")
+	evidence := &sourceVersionEvidence{
+		path: secretPath.clone(), resolvedPath: secretPath.clone(),
+		version:   Version{Present: true, Text: canary},
+		ancestors: []sourceVersionAncestor{{}, {path: Keys("parent")}, {path: Keys("parent", "branch")}, {path: secretPath.clone()}},
+	}
+	inspection.secrets = classifySecretPathsWithEvidence(nil, func(path Path) bool {
+		return path.String() == secretPath.String()
+	}, inspection.metadata, inspection.final, inspection.applications, []*sourceVersionEvidence{evidence}, inspection.input)
+
+	path := Keys("child", "branch", "token")
+	explanation, found := inspection.Explain(path)
+	if !found || explanation.Effective.Present {
+		t.Fatalf("displaced inherited path = %#v, %v", explanation, found)
+	}
+	for _, change := range explanation.History {
+		if strings.Contains(change.Before.YAML, canary) || strings.Contains(change.After.YAML, canary) ||
+			(change.After.Present && !change.After.Redacted) {
+			t.Fatalf("displaced inherited canary escaped redaction: %#v", explanation.History)
+		}
+	}
+	plain, found := inspection.Explain(Keys("parent", "branch", "plain"))
+	if !found || plain.Effective.Redacted || plain.Effective.YAML != "visible\n" {
+		t.Fatalf("neighboring value was classified with evidence: %#v, %v", plain, found)
+	}
+	if _, found := inspection.Metadata().Lookup(Keys("evidence-only")); found {
+		t.Fatal("evidence classification created a metadata path")
+	}
+}
+
 func TestInheritedSecretReferencesResolveOnlyAfterExpansion(t *testing.T) {
 	type entry struct {
 		Credential Secret `yaml:"credential"`

internal/engine/layered.go

@@ -2,11 +2,12 @@ package engine
 
 import "os"
 
-// Input selects one source and its independent import policy.
+// Input selects one source, its destination, and its independent import policy.
 type Input struct {
-	Source     Source
-	Imports    bool
-	Filesystem *FilesystemContext
+	Source      Source
+	Imports     bool
+	Filesystem  *FilesystemContext
+	Destination Path
 }
 
 // Underlay contains strictly composed contributions at one precedence tier.
@@ -15,6 +16,7 @@ type Underlay struct{ Inputs []Input }
 // LayeredOptions selects lower-priority tiers and final application rules.
 type LayeredOptions[T any] struct {
 	Definition        Definition[T]
+	SourceVersionMode sourceVersionMode
 	Underlays         []Underlay
 	Overlay           string
 	OverlayFilesystem *FilesystemContext
@@ -32,8 +34,12 @@ func LoadLayered[T any](main Input, secrets SecretBinding, supplied ...LayeredOp
 		options = supplied[0]
 	}
 	request := loadRequest[T]{
-		main:       loadInput{source: main.Source, imports: main.Imports, filesystem: main.Filesystem},
-		definition: options.Definition, overlay: options.Overlay,
+		main: loadInput{
+			source: main.Source, imports: main.Imports, filesystem: main.Filesystem,
+			destination: main.Destination.clone(),
+		},
+		definition: options.Definition, sourceVersionMode: options.SourceVersionMode,
+		overlay:           options.Overlay,
 		overlayFilesystem: options.OverlayFilesystem,
 		overrides:         append([]Override(nil), options.Overrides...),
 		underlays:         make([]loadGroup, len(options.Underlays)),
@@ -43,6 +49,7 @@ func LoadLayered[T any](main Input, secrets SecretBinding, supplied ...LayeredOp
 		for inputIndex, input := range underlay.Inputs {
 			request.underlays[index].inputs[inputIndex] = loadInput{
 				source: input.Source, imports: input.Imports, filesystem: input.Filesystem,
+				destination: input.Destination.clone(),
 			}
 		}
 	}

internal/engine/load.go

@@ -22,11 +22,12 @@ type Definition[T any] struct {
 // Imports enables explicit path and glob imports; Overlay selects one fixed overlay;
 // Overrides contains only values explicitly supplied by an application CLI.
 type Options[T any] struct {
-	Definition Definition[T]
-	Imports    bool
-	Overlay    string
-	Filesystem *FilesystemContext
-	Overrides  []Override
+	Definition        Definition[T]
+	Imports           bool
+	Overlay           string
+	Filesystem        *FilesystemContext
+	Overrides         []Override
+	SourceVersionMode sourceVersionMode
 }
 
 // FilesystemContext supplies filesystem roots for imports and overlays.
@@ -143,6 +144,8 @@ func loadWithSecretLookup[T any](source Source, secrets SecretBinding, lookup se
 		main:       loadInput{source: source, imports: options.Imports, filesystem: options.Filesystem},
 		definition: options.Definition, overlay: options.Overlay,
 		overrides: options.Overrides, ordinary: true,
+		sourceVersionMode: options.SourceVersionMode,
+		effectiveVersion:  effectiveSourceVersionRule(options.Definition.Version, Path{}, options.SourceVersionMode),
 	}
 	return executeLoadRequest(request, secrets, lookup)
 }
@@ -151,31 +154,55 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 	accumulator := diagnosticAccumulator{}
 	accounting := &importAccounting{}
 	mainOptions := Options[T]{Definition: request.definition, Imports: request.main.imports, Filesystem: request.main.filesystem}
+	mainOptions.SourceVersionMode = request.sourceVersionMode
+	mainOptions.Definition.Version = request.protectionVersion()
+	mainOptions.Overrides = request.overrides
 	if request.ordinary {
 		mainOptions.Overlay = request.overlay
 	}
 
-	input, diagnostics := assembleBaseInputTracked(request.main.source, mainOptions, accounting, nil, nil)
+	var schema *schemaDescriptor
+	if request.sourceVersionMode != sourceVersionModeDefault {
+		var schemaIssue *schemaIssue
+		schema, schemaIssue = buildSchema(reflect.TypeFor[T](), secrets)
+		if schemaIssue != nil {
+			accumulator.add(diagnosticFromSchemaIssue(schemaIssue))
+			return nil, accumulator.loadError()
+		}
+	}
+	versionState := &sourceVersionState{
+		localRule: request.definition.Version, effectiveRule: request.protectionVersion(), mode: request.sourceVersionMode,
+	}
+	accumulator.versionState = versionState
+	input, diagnostics := assembleBaseInputTrackedWithVersion(request.main.source, mainOptions, request.main.destination, accounting, nil, nil, versionState)
 	accumulator.sources = input.sources
+	accumulator.add(versionState.diagnostics...)
+	reportedVersionDiagnostics := len(versionState.diagnostics)
 	accumulator.add(diagnostics...)
-	if len(diagnostics) != 0 {
+	if hasErrors(diagnostics) {
 		return nil, accumulator.loadError()
 	}
-	schema, schemaIssue := buildSchema(reflect.TypeFor[T](), secrets)
-	if schemaIssue != nil {
-		accumulator.add(diagnosticFromSchemaIssue(schemaIssue))
-		return nil, accumulator.loadError()
+	if schema == nil {
+		var schemaIssue *schemaIssue
+		schema, schemaIssue = buildSchema(reflect.TypeFor[T](), secrets)
+		if schemaIssue != nil {
+			accumulator.add(diagnosticFromSchemaIssue(schemaIssue))
+			return nil, accumulator.loadError()
+		}
 	}
-	versionDiagnostics := checkVersion(request.definition.Version, input.document)
-	accumulator.add(versionDiagnostics...)
-	if hasErrors(versionDiagnostics) {
-		return nil, accumulator.loadError()
+	if request.sourceVersionMode == sourceVersionModeDefault {
+		versionDiagnostics := checkVersion(request.definition.Version, input.document)
+		accumulator.add(versionDiagnostics...)
+		if hasErrors(versionDiagnostics) {
+			return nil, accumulator.loadError()
+		}
 	}
 	if request.ordinary {
-		input, diagnostics = applyInputLayers(request.main.source, Options[T]{Definition: request.definition, Overlay: request.overlay, Filesystem: request.main.filesystem, Overrides: request.overrides}, input)
+		input, diagnostics = applyInputLayers(request.main.source, mainOptions, input)
 	} else {
 		input, diagnostics = assembleLayeredInput(request, input, accounting)
 	}
+	accumulator.add(versionState.diagnostics[reportedVersionDiagnostics:]...)
 	accumulator.sources = input.sources
 	accumulator.add(diagnostics...)
 	if len(diagnostics) != 0 {
@@ -208,7 +235,7 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 			accumulator.add(problems...)
 			return nil, accumulator.loadError()
 		}
-		if problem := inheritanceVersionDiagnostic(request.definition.Version, expanded); problem != nil {
+		if problem := inheritanceVersionDiagnostic(request.protectionVersion(), expanded); problem != nil {
 			accumulator.add(*problem)
 			return nil, accumulator.loadError()
 		}
@@ -217,7 +244,9 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 		input.document = expanded.root
 	}
 
-	decoded, diagnostics := decodeLoadInput(schema, request.definition, input)
+	decodeDefinition := request.definition
+	decodeDefinition.Version = request.protectionVersion()
+	decoded, diagnostics := decodeLoadInput(schema, decodeDefinition, input)
 	accumulator.add(diagnostics...)
 	if len(diagnostics) != 0 {
 		return nil, accumulator.loadError()

internal/engine/load_input.go

@@ -8,36 +8,80 @@ import (
 
 // assembledInput is the source/document handoff across schema and version checks.
 type assembledInput struct {
-	parsed      parsedSource
-	document    *document.Node
-	composition *composedDocument
-	inheritance *inheritanceScope
-	sources     []SourceInfo
-	contexts    map[string]ResourceContext
+	parsed       parsedSource
+	document     *document.Node
+	composition  *composedDocument
+	inheritance  *inheritanceScope
+	sources      []SourceInfo
+	contexts     map[string]ResourceContext
+	versionState *sourceVersionState
 }
 
 func assembleBaseInput[T any](source Source, options Options[T]) (assembledInput, []Diagnostic) {
-	return assembleBaseInputTracked(source, options, &importAccounting{}, nil, nil)
+	return assembleBaseInputTracked(source, options, Path{}, &importAccounting{}, nil, nil)
 }
 
-func assembleBaseInputTracked[T any](source Source, options Options[T], accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken) (assembledInput, []Diagnostic) {
+func assembleBaseInputTracked[T any](source Source, options Options[T], destination Path, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken) (assembledInput, []Diagnostic) {
+	return assembleBaseInputTrackedWithVersion(source, options, destination, accounting, visited, hostToken, nil)
+}
+
+func assembleBaseInputTrackedWithVersion[T any](source Source, options Options[T], destination Path, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken, versionState *sourceVersionState) (assembledInput, []Diagnostic) {
+	return assembleBaseInputTrackedForRole(source, options, destination, accounting, visited, hostToken, versionState, sourceVersionMain)
+}
+
+func assembleBaseInputTrackedForRole[T any](source Source, options Options[T], destination Path, accounting *importAccounting, visited map[resourceIdentity]importRoute, hostToken *namespaceToken, versionState *sourceVersionState, role sourceVersionRole) (assembledInput, []Diagnostic) {
 	limits := defaultImportLimits()
 	parseLimits := defaultParseLimits()
 	parseLimits.source.remaining = limits.bytes - accounting.bytes
 	parsed, diagnostics := parseSource(source, "source-"+strconv.Itoa(accounting.sources+1), parseLimits)
-	input := assembledInput{parsed: parsed, document: parsed.document}
+	if parsed.source != nil {
+		parsed.source.Destination = destination.clone()
+	}
+	input := assembledInput{parsed: parsed, document: parsed.document, sources: sourceInfos(parsed.source), versionState: versionState}
 	if len(diagnostics) != 0 {
 		input.sources = sourceInfos(parsed.source)
+		// Mapping value issues already identify application content. Other early
+		// failures describe source syntax or access, not a placed value.
+		if source.kind == sourceMapping && source.mapIssue != nil && len(destination.segments) != 0 {
+			for index := range diagnostics {
+				relative := diagnostics[index].Path
+				segments := clonePathSegments(destination.segments, len(relative.segments))
+				diagnostics[index].Path = Path{segments: append(segments, relative.segments...)}
+			}
+		}
 		return input, diagnostics
 	}
+	if !options.Imports && parsed.document != nil {
+		if diagnostics := disabledDirectiveDiagnostics(parsed.document, Path{}); len(diagnostics) != 0 {
+			return input, diagnostics
+		}
+	}
+	var versionProcessing *sourceVersionProcessingResult
+	if versionState != nil && versionState.mode != sourceVersionModeDefault {
+		var sourceID string
+		if parsed.source != nil {
+			sourceID = parsed.source.ID
+		}
+		processed, failures := versionState.process(parsed.document, role, destination, sourceID)
+		if len(failures) != 0 {
+			return input, failures
+		}
+		versionProcessing = &processed
+		if role == sourceVersionMain {
+			versionState.mainProcessing = &processed
+		}
+	}
 	if options.Imports {
-		input.composition, input.sources, diagnostics = loadImportedDocumentsTracked(source, options.Filesystem, parsed, options.Definition.Version, limits, accounting, visited, hostToken)
+		input.composition, input.sources, diagnostics = loadImportedDocumentsTrackedWithProcessing(source, options.Filesystem, parsed, destination, options.Definition.Version, limits, accounting, visited, hostToken, versionState, versionProcessing)
 		if len(diagnostics) != 0 {
 			return input, diagnostics
 		}
 		input.document = input.composition.root
 	} else {
 		input.sources = sourceInfos(parsed.source)
+		if versionProcessing != nil {
+			input.document = versionProcessing.payload
+		}
 		if options.Filesystem != nil && !activeOverlay(options.Overlay) {
 			if diagnostic := validateFilesystemContext(source, options.Filesystem, parsed); diagnostic != nil {
 				return input, []Diagnostic{*diagnostic}
@@ -45,10 +89,14 @@ func assembleBaseInputTracked[T any](source Source, options Options[T], accounti
 		}
 	}
 	if !options.Imports && input.document != nil {
-		if diagnostics := disabledDirectiveDiagnostics(input.document, Path{}); len(diagnostics) != 0 {
-			return input, diagnostics
+		_, placed, err := placeDocument(input.document, destination, input.document.Location, parseLimits.document.Depth, parseLimits.document.Nodes)
+		if err != nil {
+			return input, []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, parsed.source.ID, "configuration exceeds the source depth or node limit after destination placement")}
 		}
-		if accounting.sources+1 > limits.sources || accounting.bytes+parsed.bytes > limits.bytes || accounting.nodes+countInputNodes(input.document) > limits.nodes {
+		input.document = placed
+		rawNodes := countInputNodes(parsed.document)
+		placementNodes := destinationWrapperNodeCount(destination)
+		if accounting.sources+1 > limits.sources || accounting.bytes+parsed.bytes > limits.bytes || accounting.nodes+rawNodes+placementNodes > limits.nodes {
 			return input, []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, parsed.source.ID, "configuration exceeds the aggregate input limit")}
 		}
 		if diagnostic := registerAcquiredSource(source, options.Filesystem, parsed.source, visited, hostToken); diagnostic != nil {
@@ -56,7 +104,7 @@ func assembleBaseInputTracked[T any](source Source, options Options[T], accounti
 		}
 		accounting.sources++
 		accounting.bytes += parsed.bytes
-		accounting.nodes += countInputNodes(input.document)
+		accounting.nodes += rawNodes + placementNodes
 	}
 	if !activeOverlay(options.Overlay) || options.Imports {
 		contexts, diagnostic := contextsForAcquiredSources(source, options.Filesystem, parsed.source, input.sources)
@@ -96,9 +144,9 @@ func applyInputLayers[T any](source Source, options Options[T], input assembledI
 	}
 	assembly := newAssemblyAccumulator(composition)
 	if activeOverlay(options.Overlay) {
-		input.sources, diagnostics = loadSelectedOverlayInto(
+		input.sources, diagnostics = loadSelectedOverlayIntoWithVersion(
 			source, options.Filesystem, input.parsed, assembly, input.sources,
-			options.Overlay, options.Definition.Version, defaultImportLimits(),
+			options.Overlay, options.Definition.Version, defaultImportLimits(), input.versionState,
 		)
 		if len(diagnostics) != 0 {
 			return input, diagnostics

internal/engine/load_request.go

@@ -10,16 +10,26 @@ type loadRequest[T any] struct {
 	main              loadInput
 	underlays         []loadGroup
 	definition        Definition[T]
+	sourceVersionMode sourceVersionMode
+	effectiveVersion  *VersionRule
 	overlay           string
 	overlayFilesystem *FilesystemContext
 	overrides         []Override
 	ordinary          bool
 }
 
+func (request loadRequest[T]) protectionVersion() *VersionRule {
+	if request.effectiveVersion != nil {
+		return request.effectiveVersion
+	}
+	return request.definition.Version
+}
+
 type loadInput struct {
-	source     Source
-	imports    bool
-	filesystem *FilesystemContext
+	source      Source
+	imports     bool
+	filesystem  *FilesystemContext
+	destination Path
 }
 
 type loadGroup struct{ inputs []loadInput }
@@ -27,12 +37,25 @@ type loadGroup struct{ inputs []loadInput }
 func loadGroupedWithSecretLookup[T any](request loadRequest[T], secrets SecretBinding, lookup secretLookup) (*Loaded[T], error) {
 	request.ordinary = false
 	var diagnostics []Diagnostic
+	if normalized, err := normalizeDestination(request.main.destination); err != nil {
+		diagnostics = append(diagnostics, invalidDestinationDiagnostic(request.main.destination))
+	} else {
+		request.main.destination = normalized
+	}
+	request.effectiveVersion = effectiveSourceVersionRule(request.definition.Version, request.main.destination, request.sourceVersionMode)
 	_, mainDiagnostics := selectOptions(request.main.source, []Options[T]{{
 		Definition: request.definition, Imports: request.main.imports, Filesystem: request.main.filesystem,
+		SourceVersionMode: request.sourceVersionMode,
 	}})
 	diagnostics = append(diagnostics, mainDiagnostics...)
-	for _, group := range request.underlays {
-		for _, input := range group.inputs {
+	for groupIndex := range request.underlays {
+		for inputIndex := range request.underlays[groupIndex].inputs {
+			input := &request.underlays[groupIndex].inputs[inputIndex]
+			if normalized, err := normalizeDestination(input.destination); err != nil {
+				diagnostics = append(diagnostics, invalidDestinationDiagnostic(input.destination))
+			} else {
+				input.destination = normalized
+			}
 			_, inputDiagnostics := selectOptions(input.source, []Options[T]{{Imports: input.imports, Filesystem: input.filesystem}})
 			diagnostics = append(diagnostics, inputDiagnostics...)
 		}
@@ -56,7 +79,7 @@ func loadGroupedWithSecretLookup[T any](request loadRequest[T], secrets SecretBi
 func assembleLayeredInput[T any](request loadRequest[T], input assembledInput, accounting *importAccounting) (assembledInput, []Diagnostic) {
 	groups := make([]*composedDocument, 0, len(request.underlays))
 	for index, group := range request.underlays {
-		composition, sources, contexts, diagnostics := acquireUnderlayGroup(group, index+1, request.definition.Version, accounting)
+		composition, sources, contexts, diagnostics := acquireUnderlayGroupWithVersion(group, index+1, request.protectionVersion(), accounting, input.versionState)
 		input.sources = append(input.sources, sources...)
 		mergeResourceContexts(&input.contexts, contexts)
 		if len(diagnostics) != 0 {
@@ -103,7 +126,7 @@ func assembleLayeredInput[T any](request loadRequest[T], input assembledInput, a
 		selection := Source{kind: sourceBytes}
 		selected := parsedSource{document: &document.Node{Kind: document.Mapping}, source: &SourceInfo{}}
 		var diagnostics []Diagnostic
-		input.sources, diagnostics = loadSelectedOverlayInto(selection, request.overlayFilesystem, selected, assembly, input.sources, request.overlay, request.definition.Version, defaultImportLimits())
+		input.sources, diagnostics = loadSelectedOverlayIntoWithVersion(selection, request.overlayFilesystem, selected, assembly, input.sources, request.overlay, request.protectionVersion(), defaultImportLimits(), input.versionState)
 		if len(diagnostics) != 0 {
 			return input, diagnostics
 		}
@@ -115,7 +138,7 @@ func assembleLayeredInput[T any](request loadRequest[T], input assembledInput, a
 	}
 	if len(request.overrides) != 0 {
 		var diagnostics []Diagnostic
-		input.sources, diagnostics = assembly.applyOverrides(input.sources, request.overrides, request.definition.Version, defaultImportLimits())
+		input.sources, diagnostics = assembly.applyOverrides(input.sources, request.overrides, request.protectionVersion(), defaultImportLimits())
 		if len(diagnostics) != 0 {
 			return input, diagnostics
 		}
@@ -126,6 +149,10 @@ func assembleLayeredInput[T any](request loadRequest[T], input assembledInput, a
 }
 
 func acquireUnderlayGroup(group loadGroup, index int, rule *VersionRule, accounting *importAccounting) (*composedDocument, []SourceInfo, map[string]ResourceContext, []Diagnostic) {
+	return acquireUnderlayGroupWithVersion(group, index, rule, accounting, nil)
+}
+
+func acquireUnderlayGroupWithVersion(group loadGroup, index int, rule *VersionRule, accounting *importAccounting, versionState *sourceVersionState) (*composedDocument, []SourceInfo, map[string]ResourceContext, []Diagnostic) {
 	initialBytes, initialNodes := accounting.bytes, accounting.nodes
 	visited := make(map[resourceIdentity]importRoute)
 	hostToken := &namespaceToken{}
@@ -134,7 +161,7 @@ func acquireUnderlayGroup(group loadGroup, index int, rule *VersionRule, account
 	var contexts map[string]ResourceContext
 	for _, contribution := range group.inputs {
 		options := Options[struct{}]{Imports: contribution.imports, Filesystem: contribution.filesystem, Definition: Definition[struct{}]{Version: rule}}
-		acquired, diagnostics := assembleBaseInputTracked(contribution.source, options, accounting, visited, hostToken)
+		acquired, diagnostics := assembleBaseInputTrackedForRole(contribution.source, options, contribution.destination, accounting, visited, hostToken, versionState, sourceVersionContribution)
 		for _, source := range acquired.sources {
 			source.Layer = LayerUnderlay
 			source.UnderlayIndex = index

internal/engine/load_result.go

@@ -9,14 +9,15 @@ import (
 // resolvedLoad carries typed phase outputs needed for validation and publication;
 // it owns no source access, options, or long-lived schema state.
 type resolvedLoad[T any] struct {
-	configuration T
-	decoded       decodedConfiguration
-	metadata      Metadata
-	final         *document.Node
-	snapshots     []resolutionSnapshot
-	applications  []historyApplication
-	inheritance   *inheritanceScope
-	contexts      map[string]ResourceContext
+	configuration   T
+	decoded         decodedConfiguration
+	metadata        Metadata
+	final           *document.Node
+	snapshots       []resolutionSnapshot
+	applications    []historyApplication
+	versionEvidence []*sourceVersionEvidence
+	inheritance     *inheritanceScope
+	contexts        map[string]ResourceContext
 }
 
 func decodeLoadInput[T any](schema *schemaDescriptor, definition Definition[T], input assembledInput) (decodedConfiguration, []Diagnostic) {
@@ -57,7 +58,11 @@ func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T],
 	final := decoded.final
 	var resolutionSnapshots []resolutionSnapshot
 	if definition.Resolve != nil {
-		entry := newResolutionInput(metadata, decoded.final, input.sources, input.contexts)
+		sources := input.sources
+		if input.versionState != nil {
+			sources = sourceInfosWithVersionEvidence(sources, input.versionState.evidence, nil, true)
+		}
+		entry := newResolutionInput(metadata, decoded.final, sources, input.contexts)
 		resolved := runResolution(&configuration, definition.Resolve, schema, decoded, input.document, entry)
 		diagnostics = append(diagnostics, resolved.diagnostics...)
 		if hasErrors(resolved.diagnostics) {
@@ -73,7 +78,11 @@ func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T],
 	} else if input.document != nil {
 		applications = []historyApplication{{layer: LayerBase, value: input.document}}
 	}
-	return resolvedLoad[T]{configuration: configuration, decoded: decoded, metadata: metadata, final: final, snapshots: resolutionSnapshots, applications: applications, inheritance: input.inheritance, contexts: input.contexts}, diagnostics
+	var versionEvidence []*sourceVersionEvidence
+	if input.versionState != nil {
+		versionEvidence = append(versionEvidence, input.versionState.evidence...)
+	}
+	return resolvedLoad[T]{configuration: configuration, decoded: decoded, metadata: metadata, final: final, snapshots: resolutionSnapshots, applications: applications, versionEvidence: versionEvidence, inheritance: input.inheritance, contexts: input.contexts}, diagnostics
 }
 
 func detachLoadConfiguration[T any](schema *schemaDescriptor, configuration T, mode secretCloneMode) (T, *Diagnostic) {
@@ -97,7 +106,8 @@ func publishLoadResult[T any](schema *schemaDescriptor, definition Definition[T]
 	decoded, metadata := resolved.decoded, resolved.metadata
 	final, applications, resolutionSnapshots := resolved.final, resolved.applications, resolved.snapshots
 	finalizeMetadataPaths(&metadata, final, applications, decoded.baseline, decoded.final)
-	secrets := classifySecretPaths(schema, definition.Secret, metadata, final, applications, decoded.baseline, decoded.final)
+	secrets := classifySecretPathsWithEvidence(schema, definition.Secret, metadata, final, applications, resolved.versionEvidence, decoded.baseline, decoded.final)
+	sources := sourceInfosWithVersionEvidence(accumulator.sources, resolved.versionEvidence, secrets, false)
 	retainedTrees := make([]*document.Node, 0, len(applications)+2)
 	retainedTrees = append(retainedTrees, decoded.final, final)
 	for _, application := range applications {
@@ -105,7 +115,7 @@ func publishLoadResult[T any](schema *schemaDescriptor, definition Definition[T]
 	}
 	inspection := &Inspection{
 		metadata:         metadata,
-		sources:          cloneSourceInfos(accumulator.sources),
+		sources:          sources,
 		contexts:         cloneResourceContexts(resolved.contexts),
 		diagnostics:      canonicalDiagnostics(accumulator.diagnostics),
 		baseline:         decoded.baseline,

internal/engine/load_test.go

@@ -463,6 +463,41 @@ func TestLoadVersionReportSuppressesReturnedErrorTextAndDefaults(t *testing.T) {
 	}
 }
 
+func TestVersionWarningDoesNotSuppressReturnedError(t *testing.T) {
+	t.Parallel()
+
+	type config struct{}
+	versionPath := Keys("schema_version")
+	result, err := testLoad(Bytes("version.yml", []byte("{}\n")), Options[config]{
+		Definition: Definition[config]{Version: &VersionRule{
+			Path: versionPath,
+			Check: func(_ Version, validation *Validation) error {
+				validation.Warning(versionPath, "review schema compatibility")
+				return errors.New("CANARY_VERSION_ERROR")
+			},
+		}},
+	})
+	if result != nil || err == nil {
+		t.Fatalf("result = %#v, err = %v", result, err)
+	}
+	var loadError *LoadError
+	if !errors.As(err, &loadError) {
+		t.Fatalf("error type = %T", err)
+	}
+	diagnostics := loadError.Diagnostics()
+	var warning, hookFailure bool
+	for _, diagnostic := range diagnostics {
+		if strings.Contains(diagnostic.Message, "CANARY") {
+			t.Fatalf("returned checker error text was exposed: %#v", diagnostic)
+		}
+		warning = warning || diagnostic.Code == CodeVersionWarning && diagnostic.Severity == SeverityWarning
+		hookFailure = hookFailure || diagnostic.Code == CodeVersionHookFailed && diagnostic.Severity == SeverityError
+	}
+	if !warning || !hookFailure {
+		t.Fatalf("diagnostics = %#v", diagnostics)
+	}
+}
+
 func TestLoadMetadataReflectsDefaultsInputAndDetachedRecords(t *testing.T) {
 	t.Parallel()
 

internal/engine/options.go

@@ -33,6 +33,11 @@ func selectOptions[T any](source Source, supplied []Options[T]) (Options[T], []D
 			diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "schema-version rule requires a checker"))
 		}
 	}
+	if options.SourceVersionMode != sourceVersionModeDefault && options.SourceVersionMode != sourceVersionModeIfPresent && options.SourceVersionMode != sourceVersionModeRequired {
+		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "source-version mode is invalid"))
+	} else if options.SourceVersionMode != sourceVersionModeDefault && (definition.Version == nil || !definition.Version.Path.valid() || definition.Version.Check == nil) {
+		diagnostics = append(diagnostics, optionDiagnostic(CodeOptionsInvalid, "source-version checking requires a valid version rule and checker"))
+	}
 	return options, canonicalDiagnostics(diagnostics)
 }
 

internal/engine/records.go

@@ -186,13 +186,24 @@ type SourceInfo struct {
 	ID            string
 	Label         string
 	Path          string
+	Destination   Path
 	Layer         Layer
 	Kind          SourceKind
 	UnderlayIndex int
 	ImportedFrom  *Location
+	VersionCheck  *SourceVersionCheck
 	namespace     *namespaceToken
 }
 
+// SourceVersionCheck is a detached, public-safe record of a source-local
+// version declaration observed during an enabled load.
+type SourceVersionCheck struct {
+	Path     Path
+	Version  Version
+	Location *Location
+	Redacted bool
+}
+
 // Diagnostic is a safe structured problem report. Message and source labels must
 // never contain configuration values or other secrets.
 type Diagnostic struct {
@@ -260,9 +271,21 @@ func cloneLocations(locations []Location) []Location {
 
 func cloneSourceInfo(source SourceInfo) SourceInfo {
 	source.ImportedFrom = cloneLocation(source.ImportedFrom)
+	source.Destination = source.Destination.clone()
+	source.VersionCheck = cloneSourceVersionCheck(source.VersionCheck)
 	return source
 }
 
+func cloneSourceVersionCheck(value *SourceVersionCheck) *SourceVersionCheck {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	cloned.Path = value.Path.clone()
+	cloned.Location = cloneLocation(value.Location)
+	return &cloned
+}
+
 func cloneSourceInfos(sources []SourceInfo) []SourceInfo {
 	if sources == nil {
 		return nil

internal/engine/secret.go

@@ -8,6 +8,10 @@ type secretDependency struct {
 }
 
 func classifySecretPaths(schema *schemaDescriptor, predicate func(Path) bool, metadata Metadata, final *document.Node, applications []historyApplication, projections ...*document.Node) map[string]bool {
+	return classifySecretPathsWithEvidence(schema, predicate, metadata, final, applications, nil, projections...)
+}
+
+func classifySecretPathsWithEvidence(schema *schemaDescriptor, predicate func(Path) bool, metadata Metadata, final *document.Node, applications []historyApplication, evidence []*sourceVersionEvidence, projections ...*document.Node) map[string]bool {
 	paths := make(map[string]Path)
 	for _, application := range applications {
 		walkDocument(application.value, application.path, func(path Path, _ *document.Node) {
@@ -71,17 +75,41 @@ func classifySecretPaths(schema *schemaDescriptor, predicate func(Path) bool, me
 		classifyProjection(tree)
 	}
 	classifyProjection(final)
-	for pointer, path := range paths {
+	classifyPath := func(path Path) {
 		if root, ok := schemaSecretRoot(schema, path); ok {
 			secret[root.String()] = true
 		}
 		if predicate != nil && predicate(path.clone()) {
-			secret[pointer] = true
+			secret[path.String()] = true
+		}
+	}
+	for _, path := range paths {
+		classifyPath(path)
+	}
+	// Classify each original evidence shape before folding results into pointer
+	// sensitivity. Numeric mapping keys and sequence indices can share a pointer.
+	for _, item := range evidence {
+		if item == nil {
+			continue
+		}
+		candidate := item.resolvedPath
+		if !candidate.valid() {
+			candidate = item.path
+		}
+		classifyPath(addSecretEvidencePath(paths, item.destination, candidate))
+		for _, ancestor := range item.ancestors {
+			classifyPath(addSecretEvidencePath(paths, item.destination, ancestor.path))
 		}
 	}
 	return closeSecretDependencies(paths, secret, dependencies, inherited)
 }
 
+func addSecretEvidencePath(paths map[string]Path, destination, local Path) Path {
+	path := appendDestination(destination, local)
+	addSecretPath(paths, path.String())
+	return path
+}
+
 func addSecretPath(paths map[string]Path, pointer string) {
 	if existing, found := paths[pointer]; found && existing.valid() {
 		// Accumulator keys already match their paths' canonical spelling. History

internal/engine/secret_classification_test.go

@@ -1,6 +1,9 @@
 package engine
 
-import "testing"
+import (
+	"reflect"
+	"testing"
+)
 
 func TestSecretPathCollectionKeepsParsedContributions(t *testing.T) {
 	for _, pointer := range []string{"", "/", "/records/0", "/records/a~1b~0/01"} {
@@ -77,3 +80,123 @@ func TestSecretPredicateReceivesDetachedHistoricalPath(t *testing.T) {
 		t.Fatalf("classification after predicate mutation = %#v, predicate called: %v", classified, seen)
 	}
 }
+
+func TestSourceVersionEvidenceSensitivityUsesOriginalMountedPaths(t *testing.T) {
+	const canary = "PRIVATE-VERSION-CANARY"
+	type credential struct {
+		Value  string `yaml:"credential" configkit:"secret"`
+		Public string `yaml:"public"`
+	}
+	type account struct {
+		Token string `yaml:"token"`
+	}
+	type tenant struct {
+		Groups   map[string][]credential `yaml:"groups"`
+		Account  account                 `yaml:"account" configkit:"secret"`
+		Settings map[string]string       `yaml:"settings"`
+		Labels   map[string]string       `yaml:"labels"`
+	}
+	type configuration struct {
+		Tenant tenant `yaml:"tenant"`
+	}
+	schema, issue := buildSchema(reflect.TypeFor[configuration](), testSecretBinding())
+	if issue != nil {
+		t.Fatal(issue)
+	}
+
+	destination := Keys("tenant")
+	sequencePath := Keys("groups").Key("blue").Index(2).Key("credential")
+	accountPath := Keys("account", "token")
+	predicatePath := Keys("settings", "private")
+	nullPath := Keys("settings", "nullable")
+	absentPath := Keys("settings", "missing")
+	publicPath := Keys("labels", "public")
+	evidence := []*sourceVersionEvidence{
+		{
+			path: sequencePath.clone(), resolvedPath: sequencePath.clone(), destination: destination.clone(),
+			version:   Version{Present: true, Text: canary},
+			ancestors: []sourceVersionAncestor{{}, {path: Keys("groups")}, {path: Keys("groups").Key("blue")}, {path: Keys("groups").Key("blue").Index(2)}, {path: sequencePath.clone()}},
+		},
+		{
+			path: accountPath.clone(), resolvedPath: accountPath.clone(), destination: destination.clone(),
+			version:   Version{Present: true, Text: canary},
+			ancestors: []sourceVersionAncestor{{}, {path: Keys("account")}, {path: accountPath.clone()}},
+		},
+		{path: predicatePath.clone(), resolvedPath: predicatePath.clone(), destination: destination.clone(), version: Version{Present: true, Text: canary}},
+		{path: nullPath.clone(), resolvedPath: nullPath.clone(), destination: destination.clone(), version: Version{Present: true, Null: true}},
+		{path: absentPath.clone(), resolvedPath: absentPath.clone(), destination: destination.clone()},
+		{path: publicPath.clone(), resolvedPath: publicPath.clone(), destination: destination.clone(), version: Version{Present: true, Text: canary}},
+	}
+
+	final := parseCompositionDocument(t, "final", "tenant:\n  groups:\n    blue:\n      - public: shifted-neighbor\n  labels:\n    public: visible\n")
+	var sawOriginalSequencePath, sawAncestorPredicate bool
+	classified := classifySecretPathsWithEvidence(schema, func(path Path) bool {
+		if path.String() == appendDestination(destination, predicatePath).String() {
+			return true
+		}
+		if path.String() == appendDestination(destination, nullPath).String() {
+			return true
+		}
+		if path.String() == appendDestination(destination, absentPath).String() {
+			return true
+		}
+		if path.String() == appendDestination(destination, Keys("account")).String() {
+			sawAncestorPredicate = true
+			return true
+		}
+		if path.String() == appendDestination(destination, sequencePath).String() {
+			sawOriginalSequencePath = len(path.segments) == 5 && path.segments[3].kind == pathSegmentIndex && path.segments[3].index == 2
+		}
+		return false
+	}, Metadata{}, final, []historyApplication{{path: destination, value: final}}, evidence)
+
+	for _, path := range []Path{
+		appendDestination(destination, sequencePath),
+		appendDestination(destination, Keys("account")),
+		appendDestination(destination, predicatePath),
+		appendDestination(destination, nullPath),
+		appendDestination(destination, absentPath),
+	} {
+		if !classified[path.String()] {
+			t.Errorf("evidence path %s was not classified: %#v", path, classified)
+		}
+	}
+	shiftedNeighbor := appendDestination(destination, Keys("groups").Key("blue").Index(0).Key("public"))
+	if classified[shiftedNeighbor.String()] {
+		t.Fatalf("shifted neighboring payload was classified from declaration evidence: %#v", classified)
+	}
+	if classified[appendDestination(destination, publicPath).String()] || !sawOriginalSequencePath || !sawAncestorPredicate {
+		t.Fatalf("unclassified or semantic evidence candidates = %#v; original path seen %v, ancestor predicate seen %v", classified, sawOriginalSequencePath, sawAncestorPredicate)
+	}
+}
+
+func TestSourceVersionEvidenceClassificationKeepsCollidingShapes(t *testing.T) {
+	t.Parallel()
+	type header struct {
+		Version string `yaml:"version" configkit:"secret"`
+	}
+	type configuration struct {
+		Meta map[string]header `yaml:"meta"`
+	}
+	schema, issue := buildSchema(reflect.TypeFor[configuration](), testSecretBinding())
+	if issue != nil {
+		t.Fatal(issue)
+	}
+	keyPath := Keys("meta", "0", "version")
+	indexPath := Keys("meta").Index(0).Key("version")
+	for _, reverse := range []bool{false, true} {
+		evidence := []*sourceVersionEvidence{{resolvedPath: keyPath}, {resolvedPath: indexPath}}
+		if reverse {
+			evidence[0], evidence[1] = evidence[1], evidence[0]
+		}
+		var sawKey, sawIndex bool
+		classified := classifySecretPathsWithEvidence(schema, func(path Path) bool {
+			sawKey = sawKey || reflect.DeepEqual(path, keyPath)
+			sawIndex = sawIndex || reflect.DeepEqual(path, indexPath)
+			return false
+		}, Metadata{}, nil, nil, evidence)
+		if !classified[keyPath.String()] || !sawKey || !sawIndex {
+			t.Errorf("reverse=%v: classified=%v, key seen=%v, index seen=%v", reverse, classified, sawKey, sawIndex)
+		}
+	}
+}

internal/engine/selected_overlay.go

@@ -38,6 +38,10 @@ func loadSelectedOverlayDocument(source Source, context *FilesystemContext, main
 }
 
 func loadSelectedOverlayInto(source Source, context *FilesystemContext, main parsedSource, base *assemblyAccumulator, sources []SourceInfo, name string, rule *VersionRule, limits importLimits) ([]SourceInfo, []Diagnostic) {
+	return loadSelectedOverlayIntoWithVersion(source, context, main, base, sources, name, rule, limits, nil)
+}
+
+func loadSelectedOverlayIntoWithVersion(source Source, context *FilesystemContext, main parsedSource, base *assemblyAccumulator, sources []SourceInfo, name string, rule *VersionRule, limits importLimits, versionState *sourceVersionState) ([]SourceInfo, []Diagnostic) {
 	if nativeContext(source, context) {
 		access, basePath, mainPath, diagnostic := nativeFilesystemAccess(source, context)
 		if diagnostic != nil {
@@ -46,7 +50,7 @@ func loadSelectedOverlayInto(source Source, context *FilesystemContext, main par
 		if diagnostic := validateNativeDirectories(access, basePath, mainPath); diagnostic != nil {
 			return cloneSourceInfos(sources), []Diagnostic{*diagnostic}
 		}
-		return loadSelectedOverlayWithAccess(access, base, sources, name, rule, limits)
+		return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState)
 	}
 	rootPath, _, _, diagnostic := importFilesystem(source, context, main)
 	if diagnostic != nil {
@@ -58,10 +62,14 @@ func loadSelectedOverlayInto(source Source, context *FilesystemContext, main par
 		value.Primary = nil
 		return cloneSourceInfos(sources), []Diagnostic{value}
 	}
-	return loadSelectedOverlayWithAccess(access, base, sources, name, rule, limits)
+	return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState)
 }
 
 func loadSelectedOverlayWithAccess(access *filesystemAccess, base *assemblyAccumulator, sources []SourceInfo, name string, rule *VersionRule, limits importLimits) ([]SourceInfo, []Diagnostic) {
+	return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, nil)
+}
+
+func loadSelectedOverlayWithAccessAndVersion(access *filesystemAccess, base *assemblyAccumulator, sources []SourceInfo, name string, rule *VersionRule, limits importLimits, versionState *sourceVersionState) ([]SourceInfo, []Diagnostic) {
 	closed := false
 	defer func() {
 		if !closed {
@@ -126,7 +134,15 @@ func loadSelectedOverlayWithAccess(access *filesystemAccess, base *assemblyAccum
 	if diagnostics := overlayDirectiveDiagnostics(overlayRoot, Path{}); len(diagnostics) != 0 {
 		return sources, diagnostics
 	}
-	if versionNode := fragmentVersionClaim(overlayRoot, rule); versionNode != nil {
+	overlayPayload := overlayRoot
+	if versionState != nil && versionState.mode != sourceVersionModeDefault {
+		processed, failures := versionState.process(overlayRoot, sourceVersionContribution, Path{}, sourceID)
+		if len(failures) != 0 {
+			return sources, failures
+		}
+		overlayPayload = processed.payload
+	}
+	if versionNode := fragmentVersionClaim(overlayPayload, rule); versionNode != nil {
 		location := publicLocation(versionNode.Location)
 		return sources, []Diagnostic{{
 			Code: CodeOverlayVersion, Severity: SeverityError, Path: rule.Path.clone(),
@@ -139,7 +155,7 @@ func loadSelectedOverlayWithAccess(access *filesystemAccess, base *assemblyAccum
 		return sources, []Diagnostic{importDiagnostic(CodeImportRead, "configuration root could not be closed after reading the selected overlay", nil)}
 	}
 
-	if diagnostics := base.applyOverlay(overlayRoot, nil, nil, LayerOverlay); len(diagnostics) != 0 {
+	if diagnostics := base.applyOverlay(overlayPayload, nil, nil, LayerOverlay); len(diagnostics) != 0 {
 		return sources, diagnostics
 	}
 	base.current.inputBytes += int64(len(data))

internal/engine/source_version.go

@@ -0,0 +1,433 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+type sourceVersionMode uint8
+
+const (
+	sourceVersionModeDefault sourceVersionMode = iota
+	sourceVersionModeIfPresent
+	sourceVersionModeRequired
+)
+
+// SourceVersionModeFromFacade converts the root-owned public mode while
+// keeping the engine's policy type private. Unknown values remain intact for
+// pre-acquisition validation.
+func SourceVersionModeFromFacade(value uint8) sourceVersionMode {
+	return sourceVersionMode(value)
+}
+
+type sourceVersionRole uint8
+
+const (
+	sourceVersionMain sourceVersionRole = iota
+	sourceVersionContribution
+)
+
+type sourceVersionAncestor struct {
+	path Path
+	kind document.Kind
+}
+
+type sourceVersionEvidence struct {
+	sourceID     string
+	path         Path
+	resolvedPath Path
+	destination  Path
+	version      Version
+	location     *Location
+	ancestors    []sourceVersionAncestor
+	absence      sourceVersionPathAbsence
+	checked      bool
+	redacted     bool
+}
+
+type sourceVersionState struct {
+	localRule      *VersionRule
+	effectiveRule  *VersionRule
+	mode           sourceVersionMode
+	mainProcessing *sourceVersionProcessingResult
+	evidence       []*sourceVersionEvidence
+	diagnostics    []Diagnostic
+}
+
+func sourceInfosWithVersionEvidence(sources []SourceInfo, evidence []*sourceVersionEvidence, secrets map[string]bool, conservative bool) []SourceInfo {
+	result := cloneSourceInfos(sources)
+	if len(evidence) == 0 {
+		return result
+	}
+	sensitivity := newDiffSensitivity(secrets, nil)
+	for _, item := range evidence {
+		if item == nil || item.sourceID == "" {
+			continue
+		}
+		for index := range result {
+			if result[index].ID == item.sourceID {
+				result[index].VersionCheck = sourceVersionCheckForEvidence(item, sensitivity, conservative)
+				break
+			}
+		}
+	}
+	return result
+}
+
+func sourceVersionCheckForEvidence(evidence *sourceVersionEvidence, sensitivity *diffSensitivity, conservative bool) *SourceVersionCheck {
+	path := evidence.resolvedPath
+	if !path.valid() {
+		path = evidence.path
+	}
+	version := evidence.version
+	redacted := evidence.redacted
+	if conservative {
+		redacted = redacted || version.Text != ""
+	} else if sensitivity.isSensitiveAtOrAbove(appendDestination(evidence.destination, path).String()) {
+		redacted = true
+	}
+	if redacted {
+		version.Text = ""
+	}
+	return &SourceVersionCheck{
+		Path: path.clone(), Version: version, Location: cloneLocation(evidence.location), Redacted: redacted,
+	}
+}
+
+func (state *sourceVersionState) process(root *document.Node, role sourceVersionRole, destination Path, sourceID string) (sourceVersionProcessingResult, []Diagnostic) {
+	if state == nil || state.mode == sourceVersionModeDefault {
+		return sourceVersionProcessingResult{}, nil
+	}
+	result := processSourceVersion(root, state.localRule, role, destination, state.mode)
+	if result.evidence != nil {
+		result.evidence.sourceID = sourceID
+		state.evidence = append(state.evidence, result.evidence)
+	}
+	var failures []Diagnostic
+	for _, diagnostic := range result.diagnostics {
+		if diagnostic.Severity == SeverityWarning {
+			state.diagnostics = append(state.diagnostics, diagnostic)
+		} else if diagnostic.Severity == SeverityError {
+			failures = append(failures, diagnostic)
+		}
+	}
+	return result, failures
+}
+
+type sourceVersionProcessingResult struct {
+	payload     *document.Node
+	imports     []importDeclaration
+	evidence    *sourceVersionEvidence
+	diagnostics []Diagnostic
+}
+
+func effectiveSourceVersionRule(local *VersionRule, destination Path, mode sourceVersionMode) *VersionRule {
+	if local == nil {
+		return nil
+	}
+	if mode == sourceVersionModeDefault {
+		return local
+	}
+	effective := *local
+	effective.Path = Path{
+		segments: append(clonePathSegments(destination.segments, len(local.Path.segments)), local.Path.segments...),
+		invalid:  destination.invalid || local.Path.invalid,
+	}
+	return &effective
+}
+
+type sourceVersionPathAbsence uint8
+
+const (
+	sourceVersionPathPresent sourceVersionPathAbsence = iota
+	sourceVersionPathInvalid
+	sourceVersionMemberMissing
+	sourceVersionIndexUnavailable
+	sourceVersionPathObstructed
+)
+
+type sourceVersionPath struct {
+	node         *document.Node
+	present      bool
+	absence      sourceVersionPathAbsence
+	nearest      document.Location
+	resolvedPath Path
+	ancestors    []sourceVersionAncestor
+}
+
+func processSourceVersion(root *document.Node, rule *VersionRule, role sourceVersionRole, destination Path, mode sourceVersionMode) sourceVersionProcessingResult {
+	if role != sourceVersionMain && role != sourceVersionContribution {
+		return sourceVersionProcessingResult{diagnostics: []Diagnostic{sourceVersionOptionsDiagnostic("source role is invalid")}}
+	}
+	if mode != sourceVersionModeDefault && mode != sourceVersionModeIfPresent && mode != sourceVersionModeRequired {
+		return sourceVersionProcessingResult{diagnostics: []Diagnostic{sourceVersionOptionsDiagnostic("source-version mode is invalid")}}
+	}
+	if mode != sourceVersionModeDefault && (rule == nil || rule.Check == nil || !rule.Path.valid()) {
+		return sourceVersionProcessingResult{diagnostics: []Diagnostic{sourceVersionOptionsDiagnostic("source-version checking requires a valid version rule and checker")}}
+	}
+	if root == nil {
+		if role == sourceVersionMain && mode != sourceVersionModeDefault {
+			return sourceVersionProcessingResult{diagnostics: canonicalDiagnostics(reportVersion(rule, Version{}, nil))}
+		}
+		return sourceVersionProcessingResult{}
+	}
+
+	payload, imports, diagnostics := splitImportDirectives(root)
+	if len(diagnostics) != 0 {
+		return sourceVersionProcessingResult{diagnostics: diagnostics}
+	}
+	result := sourceVersionProcessingResult{payload: payload, imports: imports}
+	if mode == sourceVersionModeDefault {
+		return result
+	}
+
+	resolved := resolveSourceVersionPath(root, rule.Path)
+	evidence := &sourceVersionEvidence{
+		path: rule.Path.clone(), resolvedPath: resolved.resolvedPath,
+		destination: destination.clone(), ancestors: resolved.ancestors,
+		absence: resolved.absence,
+	}
+	location := resolved.nearest
+	if resolved.present {
+		location = resolved.node.Location
+	}
+	if locationKnown(location) {
+		public := publicLocation(location)
+		evidence.location = &public
+	}
+	result.evidence = evidence
+
+	interpreted := interpretVersion(rule, root)
+	evidence.version = interpreted.version
+	if resolved.present && sourceVersionControlOverlap(root, evidence.resolvedPath) {
+		evidence.redactText()
+		result.payload = nil
+		result.diagnostics = []Diagnostic{sourceVersionOverlapDiagnostic(rule, evidence)}
+		return result
+	}
+	if hasErrors(interpreted.diagnostics) {
+		evidence.redactText()
+		result.payload = nil
+		result.diagnostics = canonicalDiagnostics(interpreted.diagnostics)
+		return result
+	}
+	if !interpreted.version.Present {
+		if mode == sourceVersionModeRequired {
+			evidence.redactText()
+			result.payload = nil
+			result.diagnostics = []Diagnostic{sourceVersionMissingDiagnostic(rule, evidence)}
+			return result
+		}
+		if role == sourceVersionContribution {
+			return result
+		}
+	}
+
+	evidence.checked = true
+	result.diagnostics = canonicalDiagnostics(reportVersion(rule, interpreted.version, root))
+	if hasErrors(result.diagnostics) {
+		evidence.redactText()
+		result.payload = nil
+		return result
+	}
+	if role == sourceVersionContribution && interpreted.version.Present {
+		if !removeSourceVersionNode(result.payload, evidence.resolvedPath) {
+			evidence.redactText()
+			result.payload = nil
+			result.diagnostics = []Diagnostic{sourceVersionOptionsDiagnostic("selected source version could not be removed from its owned payload")}
+			return result
+		}
+	}
+	return result
+}
+
+func sourceVersionOptionsDiagnostic(message string) Diagnostic {
+	return Diagnostic{Code: CodeOptionsInvalid, Severity: SeverityError, Message: message}
+}
+
+func sourceVersionMissingDiagnostic(rule *VersionRule, evidence *sourceVersionEvidence) Diagnostic {
+	return Diagnostic{
+		Code: CodeVersionError, Severity: SeverityError, Path: rule.Path.clone(),
+		Message: "required schema version is missing", Primary: cloneLocation(evidence.location),
+	}
+}
+
+func sourceVersionOverlapDiagnostic(rule *VersionRule, evidence *sourceVersionEvidence) Diagnostic {
+	return Diagnostic{
+		Code: CodeVersionError, Severity: SeverityError, Path: rule.Path.clone(),
+		Message: "schema version path overlaps a structural directive", Primary: cloneLocation(evidence.location),
+	}
+}
+
+func (evidence *sourceVersionEvidence) redactText() {
+	if evidence == nil {
+		return
+	}
+	evidence.version.Text = ""
+	evidence.redacted = true
+}
+
+func resolveSourceVersionPath(root *document.Node, path Path) sourceVersionPath {
+	// Refine only segments whose container shape is known, keeping the full
+	// requested suffix when lookup stops before the declaration.
+	resolved := sourceVersionPath{absence: sourceVersionPathInvalid, resolvedPath: path.clone()}
+	if root == nil || !path.valid() {
+		return resolved
+	}
+	current := root
+	resolved.nearest = current.Location
+	resolved.ancestors = append(resolved.ancestors, sourceVersionAncestor{kind: current.Kind})
+	for position, segment := range path.segments {
+		switch current.Kind {
+		case document.Mapping:
+			if segment.kind == pathSegmentIndex {
+				resolved.absence = sourceVersionPathObstructed
+				return resolved
+			}
+			resolved.resolvedPath.segments[position] = pathSegment{kind: pathSegmentKey, key: segment.key}
+			found := false
+			for _, entry := range current.Mapping {
+				if entry.Key == segment.key {
+					current = entry.Value
+					found = true
+					break
+				}
+			}
+			if !found {
+				resolved.absence = sourceVersionMemberMissing
+				return resolved
+			}
+		case document.Sequence:
+			index, ok := schemaIndex(segment)
+			if !ok {
+				resolved.absence = sourceVersionIndexUnavailable
+				return resolved
+			}
+			resolved.resolvedPath.segments[position] = pathSegment{kind: pathSegmentIndex, index: index}
+			if index >= len(current.Sequence) {
+				resolved.absence = sourceVersionIndexUnavailable
+				return resolved
+			}
+			current = current.Sequence[index]
+		default:
+			resolved.absence = sourceVersionPathObstructed
+			return resolved
+		}
+		resolved.nearest = current.Location
+		resolved.ancestors = append(resolved.ancestors, sourceVersionAncestor{
+			path: Path{segments: clonePathSegments(resolved.resolvedPath.segments[:position+1], 0)}, kind: current.Kind,
+		})
+	}
+	resolved.node = current
+	resolved.present = true
+	resolved.absence = sourceVersionPathPresent
+	return resolved
+}
+
+func sourceVersionControlOverlap(root *document.Node, path Path) bool {
+	if root == nil || !path.valid() {
+		return false
+	}
+	if root.Kind == document.Mapping {
+		for _, entry := range root.Mapping {
+			if entry.Key == directiveKey && pathHasPrefix(path, Keys(directiveKey)) {
+				return true
+			}
+		}
+	}
+	return sourceVersionInheritanceOverlap(root, Path{}, path)
+}
+
+func sourceVersionInheritanceOverlap(node *document.Node, current, path Path) bool {
+	if node == nil {
+		return false
+	}
+	if node.Kind == document.Mapping {
+		if _, found := inheritanceDirective(node); found {
+			controlPath := current.Key(inheritanceKey)
+			if pathHasPrefix(path, controlPath) {
+				return true
+			}
+		}
+		for _, entry := range node.Mapping {
+			if entry.Key == inheritanceKey {
+				continue
+			}
+			if sourceVersionInheritanceOverlap(entry.Value, current.Key(entry.Key), path) {
+				return true
+			}
+		}
+	} else if node.Kind == document.Sequence {
+		for index, child := range node.Sequence {
+			if sourceVersionInheritanceOverlap(child, current.Index(index), path) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+func pathHasPrefix(path, prefix Path) bool {
+	if !path.valid() || !prefix.valid() || len(prefix.segments) > len(path.segments) {
+		return false
+	}
+	for index, segment := range prefix.segments {
+		candidate := path.segments[index]
+		if candidate.kind != segment.kind || candidate.key != segment.key || candidate.index != segment.index {
+			return false
+		}
+	}
+	return true
+}
+
+func removeSourceVersionNode(root *document.Node, path Path) bool {
+	if root == nil || !path.valid() || len(path.segments) == 0 {
+		return false
+	}
+	current := root
+	for _, segment := range path.segments[:len(path.segments)-1] {
+		switch current.Kind {
+		case document.Mapping:
+			if segment.kind == pathSegmentIndex {
+				return false
+			}
+			found := false
+			for _, entry := range current.Mapping {
+				if entry.Key == segment.key {
+					current = entry.Value
+					found = true
+					break
+				}
+			}
+			if !found {
+				return false
+			}
+		case document.Sequence:
+			index, ok := schemaIndex(segment)
+			if !ok || index >= len(current.Sequence) {
+				return false
+			}
+			current = current.Sequence[index]
+		default:
+			return false
+		}
+	}
+	last := path.segments[len(path.segments)-1]
+	switch current.Kind {
+	case document.Mapping:
+		if last.kind == pathSegmentIndex {
+			return false
+		}
+		for index, entry := range current.Mapping {
+			if entry.Key == last.key {
+				current.Mapping = append(current.Mapping[:index], current.Mapping[index+1:]...)
+				return true
+			}
+		}
+	case document.Sequence:
+		index, ok := schemaIndex(last)
+		if !ok || index >= len(current.Sequence) {
+			return false
+		}
+		current.Sequence = append(current.Sequence[:index], current.Sequence[index+1:]...)
+		return true
+	}
+	return false
+}

internal/engine/validation.go

@@ -187,34 +187,59 @@ func validationValueMutations(before, after *document.Node) []Diagnostic {
 	return diagnostics
 }
 
+type versionCheckResult struct {
+	version     Version
+	diagnostics []Diagnostic
+}
+
 func checkVersion(rule *VersionRule, root *document.Node) []Diagnostic {
+	return checkVersionResult(rule, root).diagnostics
+}
+
+func checkVersionResult(rule *VersionRule, root *document.Node) versionCheckResult {
 	if rule == nil {
-		return nil
+		return versionCheckResult{}
 	}
-	version := Version{}
+	result := interpretVersion(rule, root)
+	if hasErrors(result.diagnostics) {
+		result.diagnostics = canonicalDiagnostics(result.diagnostics)
+		return result
+	}
+	result.diagnostics = append(result.diagnostics, reportVersion(rule, result.version, root)...)
+	result.diagnostics = canonicalDiagnostics(result.diagnostics)
+	return result
+}
+
+func interpretVersion(rule *VersionRule, root *document.Node) versionCheckResult {
+	result := versionCheckResult{}
 	node, present := documentAtPath(root, rule.Path)
 	if present {
-		version.Present = true
+		result.version.Present = true
 		switch node.Kind {
 		case document.Null:
-			version.Null = true
+			result.version.Null = true
 		case document.String:
-			version.Text = node.Text
+			result.version.Text = node.Text
 		case document.Number:
 			if isIntegerVersion(node) {
-				version.Text = node.Text
-				break
+				result.version.Text = node.Text
+				return result
 			}
 			fallthrough
 		default:
 			location, _ := nearestDocumentLocation(root, rule.Path)
 			primary := documentLocationPointer(location)
-			return []Diagnostic{{
+			result.diagnostics = []Diagnostic{{
 				Code: CodeVersionType, Severity: SeverityError, Path: rule.Path.clone(),
 				Message: "schema version must be a string, integer, or null", Primary: primary,
 			}}
+			return result
 		}
 	}
+	return result
+}
+
+func reportVersion(rule *VersionRule, version Version, root *document.Node) []Diagnostic {
 	state := &validationState{
 		active: true, errorCode: CodeVersionError, warningCode: CodeVersionWarning,
 		invalidPath: CodeVersionError, document: root,
@@ -229,7 +254,7 @@ func checkVersion(rule *VersionRule, root *document.Node) []Diagnostic {
 			Message: "schema-version check failed", Primary: documentLocationPointer(location),
 		})
 	}
-	return canonicalDiagnostics(state.diagnostics)
+	return state.diagnostics
 }
 
 func isIntegerVersion(node *document.Node) bool {

layered.go

@@ -2,13 +2,18 @@ package configkit
 
 import "gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
 
-// Input selects one source, whether its imports are enabled, and any explicit
-// filesystem context. A zero Source is invalid; use NoSource() for an omitted
-// main input. Sources keep their documented reuse and reader ownership rules.
+// Input selects one source, its application destination, whether its imports are
+// enabled, and any explicit filesystem context. A zero Source is invalid; use
+// NoSource() for an omitted main input. Sources keep their documented reuse and
+// reader ownership rules.
 type Input struct {
-	Source     Source
-	Imports    bool
-	Filesystem *FilesystemContext
+	Source Source
+	// Destination establishes the mapping path for Source. Imports inherit this
+	// path or append a relative destination declared in YAML. Its zero value
+	// keeps root placement.
+	Destination Path
+	Imports     bool
+	Filesystem  *FilesystemContext
 }
 
 // Underlay contains inputs that must compose strictly within one tier. Tiers
@@ -18,8 +23,14 @@ type Underlay struct{ Inputs []Input }
 // LayeredOptions selects lower-priority tiers and final application rules.
 // An active Overlay requires an explicit OverlayFilesystem; an inactive overlay
 // ignores it. Overrides remain explicit CLI records, not general mappings.
+// SourceVersionMode applies one declaration policy to main, underlay, import,
+// and selected overlay documents. Enabled modes interpret the version path
+// source-locally, consume accepted non-main declarations, and protect main's
+// destination-prefixed path. The zero value preserves existing behavior; see
+// the shared source-version contract in docs/config.md.
 type LayeredOptions[T any] struct {
 	Definition        Definition[T]
+	SourceVersionMode SourceVersionMode
 	Underlays         []Underlay
 	Overlay           string
 	OverlayFilesystem *FilesystemContext
@@ -46,13 +57,15 @@ func LoadLayered[T any](main Input, supplied ...LayeredOptions[T]) (*Result[T],
 func toEngineInput(input Input) engine.Input {
 	return engine.Input{
 		Source: input.Source.toEngine(), Imports: input.Imports,
-		Filesystem: toEngineFilesystemContext(input.Filesystem),
+		Filesystem: toEngineFilesystemContext(input.Filesystem), Destination: toEnginePath(input.Destination),
 	}
 }
 
 func toEngineLayeredOptions[T any](options LayeredOptions[T]) engine.LayeredOptions[T] {
 	result := engine.LayeredOptions[T]{
-		Definition: toEngineDefinition(options.Definition), Overlay: options.Overlay,
+		Definition:        toEngineDefinition(options.Definition),
+		SourceVersionMode: engine.SourceVersionModeFromFacade(uint8(options.SourceVersionMode)),
+		Overlay:           options.Overlay,
 		OverlayFilesystem: toEngineFilesystemContext(options.OverlayFilesystem),
 	}
 	if options.Underlays != nil {

lifecycle.go

@@ -17,15 +17,42 @@ type Definition[T any] struct {
 	Secret   func(Path) bool
 }
 
+// SourceVersionMode controls schema-version declarations across one complete
+// load. The zero value preserves the existing main-only effective-path check
+// and its protected-path behavior. Enabled modes check participating documents
+// at source-local Definition.Version.Path coordinates and consume accepted
+// non-main declarations. See the shared source-version contract in docs/config.md.
+type SourceVersionMode uint8
+
+const (
+	// SourceVersionModeDefault preserves the existing main-version check and
+	// rejects version-path contributions from imported, underlay, and overlay
+	// payloads.
+	SourceVersionModeDefault SourceVersionMode = iota
+	// SourceVersionModeIfPresent checks each participating document that has a
+	// declaration. A missing main declaration still reaches the checker; an
+	// absent non-main declaration skips it. Accepted non-main declarations are
+	// consumed before composition.
+	SourceVersionModeIfPresent
+	// SourceVersionModeRequired requires a declaration in each participating
+	// document. NoSource retains the existing absent-main checker behavior.
+	// Accepted non-main declarations are consumed before composition.
+	SourceVersionModeRequired
+)
+
 // Options contains the application definition and per-load input selections.
 // Imports enables explicit path and glob imports; Overlay selects one fixed overlay;
 // Overrides contains only values explicitly supplied by an application CLI.
+// Enabled source-version modes interpret Definition.Version.Path in each
+// document's local coordinates. Main protection remains at that path prefixed
+// by the main input's Destination.
 type Options[T any] struct {
-	Definition Definition[T]
-	Imports    bool
-	Overlay    string
-	Filesystem *FilesystemContext
-	Overrides  []Override
+	Definition        Definition[T]
+	Imports           bool
+	Overlay           string
+	Filesystem        *FilesystemContext
+	Overrides         []Override
+	SourceVersionMode SourceVersionMode
 }
 
 // FilesystemContext supplies roots for imports and overlays. With FS nil,
@@ -53,7 +80,10 @@ type Override struct {
 type Resolution struct{ value *engine.Resolution }
 
 // VersionRule declares the input path and application checker for a schema version.
-// At that path, string and decimal-integer input is supplied as Version.Text.
+// Default source-version mode interprets Path as the existing effective path;
+// enabled modes interpret it in each participating document's local coordinates.
+// At the selected path, strings and strict decimal integers supply their exact
+// spelling as Version.Text. See docs/config.md for the complete contract.
 type VersionRule struct {
 	Path  Path
 	Check func(Version, *Validation) error
@@ -226,9 +256,10 @@ func (v *Validation) engineContext() *engine.Validation {
 
 func toEngineOptions[T any](options Options[T]) engine.Options[T] {
 	result := engine.Options[T]{
-		Definition: toEngineDefinition(options.Definition),
-		Imports:    options.Imports,
-		Overlay:    options.Overlay,
+		Definition:        toEngineDefinition(options.Definition),
+		Imports:           options.Imports,
+		Overlay:           options.Overlay,
+		SourceVersionMode: engine.SourceVersionModeFromFacade(uint8(options.SourceVersionMode)),
 	}
 	if options.Filesystem != nil {
 		result.Filesystem = toEngineFilesystemContext(options.Filesystem)

records.go

@@ -182,16 +182,41 @@ type Location struct {
 // SourceInfo describes a source discovered during a load. Kind identifies its
 // acquisition, independent of Layer. Path is canonical for a host file and
 // namespace-relative for a filesystem file; synthetic sources have no Path.
+// Destination is the effective mapping path where this source contributes.
 // UnderlayIndex is the one-based original underlay position, or zero for other
 // sources. ImportedFrom identifies the declaration that included this source.
 type SourceInfo struct {
-	ID            string
-	Label         string
-	Path          string
+	ID    string
+	Label string
+	Path  string
+	// Destination is the effective mapping path. Imports inherit their declaring
+	// document's path unless they append a YAML destination; overlay and CLI
+	// sources use the root path.
+	Destination   Path
 	Layer         Layer
 	Kind          SourceKind
 	UnderlayIndex int
 	ImportedFrom  *Location
+	// VersionCheck is sanitized evidence for source-local declaration processing
+	// in an enabled source-version load. It is nil when that processing did not
+	// occur, including default mode and synthetic CLI sources. During callbacks
+	// and failed loads, text is conservatively withheld; successful final source
+	// records reflect completed sensitivity classification.
+	VersionCheck *SourceVersionCheck
+}
+
+// SourceVersionCheck describes a source-local version declaration observed
+// during an enabled load. A non-nil record with Present false records observed
+// absence, but does not imply that a checker ran or accepted a value. Text is
+// empty when sensitivity classification or conservative callback-time/failed-
+// load redaction withholds it; Present and Null retain their meaning. Copies
+// returned by source queries are detached. See docs/config.md for disclosure
+// and lifecycle details.
+type SourceVersionCheck struct {
+	Path     Path
+	Version  Version
+	Location *Location
+	Redacted bool
 }
 
 // Diagnostic is a safe structured problem report. Message and source labels must
@@ -260,10 +285,22 @@ func cloneLocations(locations []Location) []Location {
 }
 
 func cloneSourceInfo(source SourceInfo) SourceInfo {
+	source.Destination = source.Destination.clone()
 	source.ImportedFrom = cloneLocation(source.ImportedFrom)
+	source.VersionCheck = cloneSourceVersionCheck(source.VersionCheck)
 	return source
 }
 
+func cloneSourceVersionCheck(value *SourceVersionCheck) *SourceVersionCheck {
+	if value == nil {
+		return nil
+	}
+	cloned := *value
+	cloned.Path = value.Path.clone()
+	cloned.Location = cloneLocation(value.Location)
+	return &cloned
+}
+
 func cloneSourceInfos(sources []SourceInfo) []SourceInfo {
 	if sources == nil {
 		return nil

records_test.go

@@ -20,3 +20,47 @@ func TestOverlayPublicValues(t *testing.T) {
 		}
 	}
 }
+
+func TestSourceInfoDestinationConversionsAndCopies(t *testing.T) {
+	destination := Keys("collections", "a/b", "0")
+	public := SourceInfo{ID: "source-1", Destination: destination}
+	internal := toEngineSourceInfo(public)
+	if internal.Destination.String() != destination.String() {
+		t.Fatalf("engine destination = %q, want %q", internal.Destination.String(), destination.String())
+	}
+	converted := fromEngineSourceInfo(internal)
+	if converted.Destination.String() != destination.String() {
+		t.Fatalf("public destination = %q, want %q", converted.Destination.String(), destination.String())
+	}
+	copy := cloneSourceInfo(converted)
+	copy.Destination = Path{}
+	if converted.Destination.String() != destination.String() {
+		t.Fatalf("source record destination changed through clone: %q", converted.Destination.String())
+	}
+}
+
+func TestSourceVersionCheckConversionsAndCopies(t *testing.T) {
+	path := Keys("records").Index(2).Key("version")
+	source := SourceInfo{
+		ID: "source-1",
+		VersionCheck: &SourceVersionCheck{
+			Path: path, Version: Version{Present: true, Text: "123"},
+			Location: &Location{SourceID: "source-1", Line: 4, Column: 8},
+		},
+	}
+	internal := toEngineSourceInfo(source)
+	if internal.VersionCheck == nil || internal.VersionCheck.Path.String() != path.String() ||
+		internal.VersionCheck.Version.Text != "123" || internal.VersionCheck.Location == nil || internal.VersionCheck.Location.Line != 4 {
+		t.Fatalf("engine source version check = %#v", internal.VersionCheck)
+	}
+	converted := fromEngineSourceInfo(internal)
+	copy := cloneSourceInfo(converted)
+	copy.VersionCheck.Path = Keys("changed")
+	copy.VersionCheck.Version.Text = "changed"
+	copy.VersionCheck.Location.Line = 99
+	copy.VersionCheck.Redacted = true
+	if converted.VersionCheck.Path.String() != path.String() || converted.VersionCheck.Version.Text != "123" ||
+		converted.VersionCheck.Location.Line != 4 || converted.VersionCheck.Redacted {
+		t.Fatalf("source version check changed through a detached copy: %#v", converted.VersionCheck)
+	}
+}