Document the internal complexity refactor roadmap

README.md

@@ -17,7 +17,8 @@ then report domain errors and warnings through read-only semantic validation. Se
 tags and a path predicate drive deterministic redacted effective YAML. Typed secret
 references resolve environment names before validation, and explicit
 secrets-directory bootstrap is available as a separate startup operation. Explicit
-CLI override records apply above overlays. Value explanation is available through
+CLI override records apply after inheritance and typed decoding, before application
+resolution. 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. The root
@@ -26,12 +27,14 @@ the [configuration contract](docs/config.md#effective-configuration-diffs) and
 [consumer guide](docs/consumers/README.md#effective-configuration-diffs) describe
 its safe changed-region records and maintained workflows.
 
-Sources can also be explicitly placed as sequence items, and definitions can
-register selected sequences to append records with distinct string IDs during
-strict composition. Higher-priority sequences still replace lower-priority
-sequences as whole values. See the [sequence contract](docs/config.md#strict-document-composition),
-[maintained prompt example](docs/consumers/README.md#identified-prompt-sequences),
-and [ADR 0014](docs/adr/0014-sequence-placement-and-composition.md).
+Sources can also be explicitly placed as sequence items. Configuration
+declarations and application registrations can give selected sequences scalar
+identities and choose how they combine across precedence and inheritance.
+Strict peers combine distinct records, while higher-priority collections can
+replace, append, or upsert whole records. See the
+[sequence contract](docs/config.md#strict-document-composition),
+[maintained catalog examples](docs/consumers/README.md#identified-prompt-sequences),
+and [ADR 0017](docs/adr/0017-collection-sequence-policy.md).
 
 Imports are also explicit: a source may name files, search declared directories,
 or select files with path globs. Applications can set load-wide import defaults
@@ -76,12 +79,13 @@ mappings combine, while overlapping non-mapping definitions are errors. Between
 precedence tiers, mappings combine recursively, retaining omitted lower-priority
 children; other values replace lower-priority values. The main document and its
 imports form one strictly composed tier. Explicit underlay groups sit below it
-and above typed defaults; a selected overlay and explicit CLI overrides sit
-above it. The [configuration contract](docs/config.md#strict-document-composition)
-owns the detailed combination rules and input-specific constraints. At
-definition-registered paths only, strict composition can append records with
-distinct explicit IDs; ordinary and unregistered sequences keep their conflict
-or whole-value replacement behavior.
+and above typed defaults; a selected overlay applies before inheritance, while
+explicit CLI overrides apply after decoding and before application resolution.
+The [configuration contract](docs/config.md#strict-document-composition) owns
+the detailed combination rules and input-specific constraints. Declared or
+registered collections combine distinct identified records within strict tiers
+and use their selected operation at precedence boundaries; other sequences keep
+their strict-conflict and whole-value-replacement behavior.
 
 The [architecture goals](docs/policy/architecture.md#success-criteria) explain
 these priorities and how genuine new needs can justify extending the shared

docs/adr/0017-collection-sequence-policy.md

@@ -138,6 +138,6 @@ Record inheritance also requires parent lookup by identity and checking for
 missing parents and cycles. Copied settings retain the same source, history,
 and sensitivity information as mapping-sibling inheritance.
 
-The configuration contract will define declaration syntax, identity comparison,
-omission and empty-value behavior, and diagnostics when the feature is
-implemented.
+The [configuration contract](../config.md#strict-document-composition) defines
+declaration syntax, identity comparison, omission and empty-value behavior, and
+diagnostics for the implemented feature.

docs/adr/0018-cli-after-structural-resolution.md

@@ -80,5 +80,5 @@ must remain consistent throughout loading.
 CLI input can no longer add or cancel inheritance relationships or bypass an
 earlier error in source assembly or inheritance. It also cannot fix a value that
 fails the earlier decoding step. Semantic validation still runs after overrides
-and application resolution. The configuration contract and consumer guidance
-must explain these behavior changes when they are implemented.
+and application resolution. The [configuration contract](../config.md#explicit-cli-overrides)
+and [consumer guidance](../consumers/README.md) describe this behavior.

docs/config.md

@@ -52,10 +52,11 @@ preserves already validated secret state without rereading the environment.
 The current lifecycle is:
 
 ```text
-validate options → parse the selected source → traverse/compose enabled imports
+validate options → parse the selected source → extract source controls and
+  traverse/strictly compose enabled imports
   → build schema → check the optional application version → apply a selected overlay
-  → apply explicit CLI overrides → expand sibling inheritance
-  → create and clone defaults → strictly decode
+  → expand sibling inheritance
+  → create and clone defaults → strictly decode → apply explicit CLI overrides
   → recorded application resolution
   → resolve typed secret references → semantic validation → classify secrets
   → snapshot configuration and metadata
@@ -70,15 +71,16 @@ missing file remains an error; it is never interpreted as no input.
 `Options` accepts the application definition, ordinary-source `Destination` and
 `PlacementMode`, explicit imports, one selected overlay, filesystem
 context, explicit CLI overrides, and shared source-version controls. The definition
-may register strict sequence composition paths through
-`SequenceCompositions`. Its zero-valued placement mode places the source mapping
+may register sequence identities through `Definition.SequenceIdentities`. Its
+zero-valued placement mode places the source mapping
 at the destination; `sequence-item` explicitly wraps the mapping as one item at a
 non-root destination. Unknown modes, invalid destinations, and invalid or
 conflicting sequence registrations fail before source acquisition. Overlay and
-CLI coordinates remain rooted at the application root. `NoSource` rejects
+CLI coordinates remain rooted at the application root. Ordinary `Load` recognizes
+source-root collection declarations whether or not imports are enabled; an
+`imports` declaration still requires imports to be enabled. `NoSource` rejects
 imports, active overlays, and filesystem context as invalid combinations but
-accepts overrides. Input containing a reserved `configkit` mapping key is rejected
-while imports are disabled.
+accepts overrides and remains an absent source rather than an empty document.
 
 Every source, options, schema, version, defaults, decode, resolution, or validation
 failure returns a nil result and a `*LoadError`. Successful results contain caller-owned `Config`, detached
@@ -128,16 +130,20 @@ nothing. Underlay groups are listed from lowest to highest priority. Repeating
 a file within one group remains an import/repetition error; the same reusable
 source may be selected again in another tier.
 
-ConfigKit acquires and composes the main input first, constructs the schema,
-and checks the optional application version from the main tier only. Underlay
-roots cannot claim that version path (`underlay.version`); imported fragments
-retain `import.version` protection. It then acquires and composes underlay
-groups in order, recursively combines the groups, and applies the main tier,
-one selected overlay, and explicit CLI overrides. Scalar, sequence, and null
-definitions replace lower values between tiers; mappings combine recursively.
-Syntax and strict-composition errors inside a tier cannot be masked by a
-higher-priority tier. Defaults, typed decoding, resolution, secret lookup,
-validation, and publication run once on the final assembled input.
+ConfigKit acquires the main input first and constructs the schema. It then
+acquires and strictly composes underlay groups from lowest to highest priority,
+passing each group's accumulated lower collection policy into the next group.
+Each group is applied once as a precedence tier. The main tier is then composed
+with the accumulated underlay policy, and the optional application version is
+checked against that composed main tier only. Underlay roots cannot claim that
+version path (`underlay.version`); imported fragments retain `import.version`
+protection. ConfigKit then applies the selected overlay and resolves inheritance.
+Scalar, sequence, and null definitions replace lower values between tiers unless
+a collection policy defines the sequence operation; mappings combine recursively.
+After successful defaults and typed decoding, CLI overrides are applied to that
+typed configuration before application resolution. Syntax, strict-composition,
+inheritance, and decoding errors cannot be masked by a CLI override. Resolution,
+secret lookup, validation, and publication run once on the resulting values.
 
 An active layered overlay requires `LayeredOptions.OverlayFilesystem` explicitly,
 independent of the main source's namespace. Its name and root-relative lookup
@@ -147,7 +153,10 @@ Ordinary `Load` continues to infer its selected-overlay context from its source.
 
 Source IDs follow acquisition order—main and its depth-first imports, then each
 underlay tier's inputs and depth-first imports, then overlay and CLI—even though
-history follows precedence order. Source `Layer` describes precedence while
+history follows precedence order. Default main-version checking happens after
+underlay composition because the main tier inherits the accumulated collection
+policy. Enabled per-source version checks retain acquisition order and source
+local headers. Source `Layer` describes precedence while
 `Kind` describes acquisition. Underlay records use `LayerUnderlay` and a
 one-based `UnderlayIndex` giving their original tier position; all other records
 have index zero. Explicit empty groups and `NoSource` consume no source ID.
@@ -213,35 +222,55 @@ is recorded in [ADR 0011](adr/0011-input-destinations.md) and
 
 Any input mapping may declare `extends: name` to inherit from the mapping named
 `name` among its immediate siblings. Names are exact keys, including the empty
-string; lookup does not search ancestor or unrelated scopes. The document root
-and a sequence-element mapping have no sibling namespace for their own string
-relationship, though mappings nested inside them can have one. An `extends`
+string; lookup does not search ancestor or unrelated scopes. A mapping inside a
+sequence can also participate in record inheritance when that sequence has an
+effective identity declaration from `configkit.sequences` or an application
+registration. In that case, `extends` is a mapping containing exactly the
+sequence's identity fields, with scalar values; lookup is limited to that final
+sequence. The document root and a sequence-element mapping without an effective
+identity declaration have no sibling namespace for non-null string
+relationships, though mappings nested inside them can have one. An `extends`
 value of null cancels a relationship without looking up a parent. Other value
-types, missing or non-mapping parents, and cycles fail the load with value-free
-diagnostics.
+types, incomplete or extra reference fields, missing parents, and cycles fail
+the load with value-free diagnostics.
 
-Within each sibling scope, direct mapping definitions resolve by dependency
-readiness. A parent is resolved before a child; among currently eligible
-definitions, the lexically smallest canonical semantic pointer is selected,
-including newly eligible definitions as soon as their parent completes. This
-ordering governs inheritance operations and their history, controls, and
-transfers. It does not reorder the mappings in the resulting configuration.
+Within each mapping sibling scope or identified sequence, direct definitions
+resolve by dependency readiness. A parent is resolved before a child; among
+currently eligible definitions, the lexically smallest canonical semantic
+pointer is selected, including newly eligible definitions as soon as their
+parent completes. This ordering governs inheritance operations and their
+history, controls, and transfers. It does not reorder mappings or sequence
+records in the resulting configuration.
 
 `extends` is reserved structural input across ordinary and layered loads, every
 source kind, imports, selected overlays, and explicit CLI overrides. It is
 consumed before typed decoding and need not appear in the application's Go
 types. Applications previously using `extends` as an ordinary YAML field must
 rename that key and its field. No collection registration or keyword setup is
-required.
+required for mapping-sibling relationships; identified-sequence relationships
+require effective identity fields for that collection.
 
 ConfigKit completes strict composition within tiers and precedence assembly
-between tiers before resolving relationships. An omitted `extends` retains a
-lower-priority relationship; `extends: null` cancels it while preserving the
-child's own settings. Superseded references are historical evidence, not active
-relationships to validate. Each child recursively overlays its own settings
-over its resolved parent: explicit zero, false, empty string, sequence, and
-null values replace inherited values, while mappings combine recursively.
-The child retains its key. All effective relationships resolve, including
+between tiers before resolving relationships. Only records that survive that
+assembly participate in identified-sequence lookup: an upserted parent supplies
+its final record, a replaced parent is unavailable, and a higher replacement
+without `extends` supersedes a lower relationship. An omitted `extends` retains
+a lower-priority mapping-sibling relationship; an identified record's effective
+directive depends on the record that survives assembly. `extends: null` cancels
+a relationship while preserving the child's own settings. Superseded references
+are historical evidence, not active relationships to validate. Each child
+recursively overlays its own settings over its resolved parent: explicit zero,
+false, empty string, and
+null values replace inherited values, while mappings combine recursively. For
+identified records, the child's identity fields and their origins remain its
+own; parent identity fields do not contribute to the payload.
+Sequences at collection destinations use the shared collection operation with
+the parent as lower input and the child as higher input. The destination's
+explicit mode applies; otherwise a copied identity selects upsert and an
+unkeyed destination replaces. A parent's explicit mode does not move to a
+different destination. Sequences outside collection destinations remain atomic
+replacements.
+All effective relationships resolve, including
 entries the application may never select for execution. Partial parent
 definitions undergo normal typed decoding and application-owned validation,
 not a special structural exemption.
@@ -423,10 +452,11 @@ the descendant can therefore retain history after `Lookup` stops reporting it as
 effective. Equal-valued input is still an explicit base definition, while a derived
 value for absent input remains non-explicit.
 
-Appending registered records during strict composition assigns each contribution
-its assembled sequence index in history. A later precedence tier that supplies a
-sequence records replacement at the sequence path; history does not imply
-identity-based merging across tiers.
+Strict composition assigns contributed records their assembled sequence positions
+in history. Across tiers, history follows the selected
+[collection operation](#strict-document-composition), including append and
+whole-record upsert. Incoming contributions use their assigned positions, and
+replaced payload remains available as historical evidence.
 
 A mapping assembled from the selected file and imports has one composite base origin
 whose locations follow [scoped assembly order](#explicit-imports), not source-record
@@ -501,30 +531,33 @@ historical path. Its effective value and each chronological before/after value a
 parser values. `Present=false` with empty YAML means absence or deletion; explicit
 null is present and renders as `null`. The history starts with the canonical typed
 application-default or Go-zero baseline, followed by relevant underlay and main-tier
-contributions in precedence order, the selected overlay, supplied CLI records,
-and audited net resolution operations. Within each strict tier, replay follows
+contributions in precedence order, the selected overlay, and structural inheritance
+events. Typed defaulting and decoding reconcile that source history before supplied
+CLI records and audited net resolution operations. Within each strict tier, replay follows
 [scoped assembly order](#explicit-imports), not source-record acquisition order.
-Structural inheritance events appear after source replay
-and before typed reconciliation, including consumed or canceled `extends` input
-and equal-valued child replacements. Overlapping parent/child resolution records
+Inheritance events include consumed or canceled `extends` input and equal-valued
+child replacements. Overlapping parent/child resolution records
 are rendered
 as one net subtree event with combined reasons and dependencies, rather than
 pretending that the recorded assignments ran in lexical order. Explicit equal
-writes remain visible. When input replay
-differs from the final typed input, a `ChangeDecoding` event records the transition
-before domain resolution. Its origin retains the decoded path's source/default
-attribution; its reason identifies static-default retention and canonical decoding.
-This built-in inspection operation is not accepted by `Resolution.Record`.
+writes remain visible. When structural replay differs from the pre-CLI typed input,
+a `ChangeDecoding` event records retained defaults and canonical decoding. CLI
+contributions then retain their raw input representation while effective and
+resolution values use the typed projection. This built-in inspection operation is
+not accepted by `Resolution.Record`.
 
 Base, overlay, and CLI history preserves the policy-validated input representation,
 including a superseded value that could not have decoded into the final Go field.
 Baseline, effective, and resolution values use canonical typed projection. A
 decoding event bridges replayed input and canonical typed values, so intermediate
 null/scalar replacements cannot incorrectly imply permanent default removal. Mapping
-queries reconstruct each source or override contribution, while sequences remain
-atomic: a descendant history identifies its presence before and after the containing
-sequence replacement without implying element-wise merging. Removed paths remain
-explainable; unknown and malformed paths return false.
+queries reconstruct each source or override contribution. A sequence snapshot
+represents the collection at that point in replay, and sequence diffs remain
+atomic. Descendant queries describe their presence and values before and after
+containing sequence operations. Combination follows the
+[collection operation tables](#strict-document-composition); upsert replaces
+matching records in full. Removed paths remain explainable; unknown and malformed
+paths return false.
 
 Every snapshot applies the same historical tag, predicate, and recorded-dependency
 sensitivity closure as effective rendering before YAML is exposed. A redacted scalar
@@ -611,13 +644,15 @@ must resolve to a nonempty value. Secret references work in typed structs, maps,
 pointers, slices, and arrays. A dynamic `any` value does not establish secret
 semantics and cannot contain `Secret`; applications must use a typed slot.
 
-ConfigKit resolves only the effective names after recorded application resolution
-and before semantic validation. Each unique name is read with `os.LookupEnv` once
-per load. Validation can inspect the credential through the deliberately named
-`Value()` accessor and distinguish success with `IsResolved()`. Later loads read
-the environment again, and cloned defaults are rebuilt from names so a previously
-resolved result cannot retain a stale credential. `Load` never writes to the
-environment.
+ConfigKit resolves only the effective names after CLI assignment and recorded
+application resolution, and before semantic validation. CLI overrides may supply
+or replace a typed secret reference; lookup uses that effective name and retains
+its effective source location for diagnostics. Each unique name is read with
+`os.LookupEnv` once per load. Validation can inspect the credential through the
+deliberately named `Value()` accessor and distinguish success with `IsResolved()`.
+Later loads read the environment again, and cloned defaults are rebuilt from names
+so a previously resolved result cannot retain a stale credential. `Load` never
+writes to the environment.
 
 Credential bytes are held only in the per-load lookup state and the trusted returned
 configuration, and are returned only by `Value`. Secret formatting uses a safe
@@ -681,18 +716,19 @@ files when appropriate; ConfigKit stores no implicit global report.
 
 ### Recorded application resolution
 
-An optional `Definition.Resolve` callback runs after successful typed decoding. It
-receives the working configuration and a per-load `Resolution` context. The context's
+An optional `Definition.Resolve` callback runs after successful defaults, typed
+decoding, and explicit CLI assignment. It receives the working configuration and a
+per-load `Resolution` context. The context's
 `IsExplicit` query uses surviving input presence, so explicit false, zero, empty, and
 null are never confused with absence or static defaults.
 
 `Resolution.InputInfo(path)` returns detached effective metadata from the fixed
-decoded entry state, before application resolution runs. It includes retained static
-defaults, preserves explicit null, and uses the same exact semantic path matching as
-`Metadata.Lookup`; missing, malformed, and key/index-shape-mismatched paths return
-false without diagnostics. Its `Explicit` value agrees with `IsExplicit` for every
-found entry path. Resolution changes, additions, removals, and moves do not alter
-this entry view.
+post-decode entry state, including explicit CLI overrides, before application
+resolution runs. It includes retained static defaults, preserves explicit null, and
+uses the same exact semantic path matching as `Metadata.Lookup`; missing,
+malformed, and key/index-shape-mismatched paths return false without diagnostics.
+Its `Explicit` value agrees with `IsExplicit` for every found entry path. Resolution
+changes, additions, removals, and moves do not alter this entry view.
 
 `Resolution.Source(id)` returns a detached record for an already acquired source in
 the same load: the main source, imports, selected overlay, and supplied CLI records
@@ -767,8 +803,11 @@ live services as a substitute for configuration validation.
 
 ## Strict document composition
 
-ConfigKit strictly composes parsed base documents when `Options.Imports` is true.
-Application defaults do not participate in this operation.
+Ordinary `Load` applies strict document composition to its parsed source scope;
+`Options.Imports` adds imported documents as peers in that scope. Application
+defaults do not participate. With imports disabled, the single source still has
+its controls extracted and any declared or registered collection identity is
+validated, but there are no imported peers to combine.
 
 | Existing node | Incoming node | Result |
 | --- | --- | --- |
@@ -779,46 +818,139 @@ Application defaults do not participate in this operation.
 | Any other pair of present nodes | Any other pair of present nodes | `compose.conflict` |
 
 Every non-mapping overlap is a conflict, even when values are equal, except for
-sequence/sequence contributions at a registered sequence-composition path. Nulls
-remain atomic conflicts. Unregistered sequences conflict when repeated and are
-never joined by index. Disjoint entries under shared mappings compose, making
-stable keyed mappings the natural representation for independently contributed
-entries.
+sequence/sequence contributions at a destination with effective identity from an
+application registration, a current YAML `key` declaration, or retained lower
+policy. Nulls remain atomic conflicts.
+Sequences without effective identity conflict when repeated and are never joined
+by index. Disjoint entries under shared mappings compose, making stable keyed
+mappings the natural representation for independently contributed entries.
 
-`Definition.SequenceCompositions` registers literal mapping paths and one literal
-`IdentityField` for sequences that should compose independently authored records.
-Registration paths follow input-destination key rules: parsed numeric tokens are
-literal mapping keys, explicit index segments and reserved `configkit` or
-mapping-valued `extends` segments are invalid, and the root registration is
-harmless and unused. The identity field is one literal string key; neither the
-field name nor identity strings are normalized.
-At each registered path, every actual sequence contribution in a strict tier is
-validated, including a singleton contribution: each record must be a mapping with
-a present string identity field. Distinct exact identity strings append in source
-and list order; duplicate identities conflict even if the records are otherwise
-equal or disjoint. Empty identity strings are valid. Malformed records produce
-`compose.invalid`; duplicate identities produce `compose.conflict`, with the
-sequence container and source locations identifying a duplicate without exposing
-identity values. Missing paths and non-sequence values do not fail by themselves.
-Identical registrations coalesce; conflicting registrations at one path and
-invalid registration paths produce `options.invalid`. Unused and root registrations
-are allowed and have no effect.
+`Definition.SequenceIdentities` contains registrations created by
+`SequenceIdentityAt` or `SequenceIdentityMatching`. The exact form accepts a
+mapping-only `Path`; the matching form accepts literal-key and any-mapping-key
+segments created by `SequenceLiteralKey` and `SequenceAnyMappingKey`. A literal
+`"*"` key is distinct from the wildcard constructor. Parsed numeric path tokens
+remain literal mapping keys; explicit index segments and reserved `configkit` or
+mapping-valued `extends` segments are invalid. The root selector is harmless under
+the mapping-root schema. Selector segments consume one mapping level and match a
+complete destination; an any-mapping-key segment matches exactly one key, not an
+arbitrary prefix or suffix. Each registration requires one or more literal,
+direct field names; compound field sets are normalized as sets, and field names
+are not otherwise normalized. The same field-set and scalar-equality rules apply
+to YAML `key` declarations.
 
-Registration changes strict composition only. Each underlay group and the main
-tier has independent duplicate-identity state. Precedence assembly is unchanged:
-a present higher-priority sequence replaces the lower sequence as one value,
-including at a registered path. Overlays, CLI overrides, defaults, inheritance,
-and application resolution do not run the registered identity check. The accepted
-rationale is recorded in [ADR 0014](adr/0014-sequence-placement-and-composition.md).
-The [maintained prompt catalog](consumers/README.md#identified-prompt-sequences)
-shows item path and glob imports, helper-supplied identity, and main-tier
-replacement of a lower-priority sequence.
+At each selected path, records must provide every effective identity field as a
+scalar string, number, boolean, or explicit null. Field names form a set, so
+order and repetition do not affect compound identity. The type-tagged tuple
+preserves category distinctions: strings compare exactly, including empty
+strings; numbers, booleans, and null remain distinct categories. Finite numbers
+compare by exact mathematical value, so `1`, `1.0`, and `1e0` are equal, as are
+`0` and `-0`, without floating-point rounding. Distinct tuples append in source
+and list order; duplicate tuples conflict even when records are otherwise equal
+or disjoint. Malformed records produce `compose.invalid`; duplicate identities
+produce `compose.conflict`, with paths and source locations identifying a
+duplicate without exposing identity values. Missing paths and non-sequence values
+do not fail by themselves. Equivalent overlapping registrations coalesce.
+Incompatible overlaps and invalid registrations produce `options.invalid` before
+source acquisition. Unused and root registrations are allowed and have no effect.
+
+Registrations provide identity for strict composition, sequence operations,
+inheritance lookup, and final validation. Dynamic selectors apply at concrete
+strict-composition, inheritance, and final-result destinations without requiring
+the application to enumerate mapping keys. Each strict tier has independent
+duplicate-identity state among its peers; layered precedence and inheritance
+then apply the collection operation described below.
+
+Final registration checks run in both ordinary and layered loads after effective
+secret lookup and before application semantic validation. They examine actual
+final typed sequences, including values introduced by defaults, CLI, or recorded
+resolution; they do not require path existence or sequence shape. Diagnostics
+use concrete collection and item paths and available source locations, without
+exposing identity or credential values. The guarantee ends when loading publishes
+successfully and does not cover later caller mutations.
+YAML-only identity is enforced during structural composition, precedence, and
+identified inheritance; it carries no final-result guarantee after typed
+defaults, CLI, or application resolution. Applications that need that guarantee
+register the identity constraint.
+The [maintained catalog examples](consumers/README.md#identified-prompt-sequences)
+show strict peers, precedence operations, inheritance, dynamic destinations, and
+the distinction between YAML-only declarations and application registrations.
 When an enabled source-version mode is selected, declarations are checked in each
 source's own coordinates before placement and composition. Accepted non-main
 headers are consumed before strict composition and cannot supply a registered
 record identity. Final typed decoding and application validation still run on the
 completed configuration.
 
+Ordinary sources, layered inputs, and selected overlays may declare collection
+behavior under `configkit.sequences` at the document root. Each entry has a
+required literal `destination` and may specify `key` as one string or a nonempty
+list of strings, plus a `mode` of `replace`, `append`, or `upsert`. These
+controls are removed before application decoding. A declaration destination is
+relative to that source's placement, so a mounted fragment's declaration is
+mounted with its values. Declarations from strict peers must agree on identity
+fields and on any explicitly supplied mode; omission expresses no mode
+preference. They apply even when the declaring source has no value at that
+destination: a key validates an existing retained sequence or remains pending
+until records arrive, while a mode-only declaration affects later combinations
+without recombining earlier tiers. A key supplies the identity used by `append`
+and `upsert` and is checked against any application registration.
+
+Strict peers at an identified destination first combine distinct records in
+source and list order. Duplicate identities among peers or within one
+contribution fail under every mode. After strict composition, precedence and
+inheritance use one operation for the assembled incoming collection:
+
+| Mode | Behavior at source-precedence and inheritance boundaries |
+| --- | --- |
+| `replace` | Replace the complete lower sequence with the assembled higher sequence. |
+| `append` | Retain lower records and append higher records; duplicate identities fail. |
+| `upsert` | Replace matching records in full at their lower positions, retain unmatched lower records, and append new identities. |
+
+Upsert replaces the complete matched record; it does not recursively merge
+record fields. Append and upsert require identity. With no explicit mode in the
+current tier, an explicit lower mode persists; if none exists, effective identity
+selects upsert and its absence selects replace. Inferred modes do not persist.
+Explicit modes persist at their destination until changed by a higher explicit
+mode, independently of YAML identity lifetime. A declaration alone does not
+clear or recombine a collection.
+
+The presence and value kind at a precedence or inheritance boundary determine
+whether a collection changes:
+
+| Higher contribution | `replace` | `append` / `upsert` |
+| --- | --- | --- |
+| Absent | Leave the lower value unchanged. | Leave the lower value unchanged. |
+| Explicit `[]` | Clear the sequence. | Contribute no records. |
+| Explicit null or another non-sequence value | Replace the lower value, subject to application schema. | Error; the operation requires a sequence. |
+
+An absent lower value can be initialized by an incoming sequence under any mode.
+A present lower null or other non-sequence value is not absence: append and
+upsert cannot combine with it. An empty sequence still requires a valid mode and
+identity where applicable. Null used as an identity component inside a record is
+distinct from null used as the collection value.
+
+Declarations govern ordinary strict source composition, including loads with
+imports disabled, and each strict scope in layered loading. Before composing a
+higher tier's peers, ConfigKit makes applicable lower identity and explicit mode
+available; after peer composition, the tier applies its resolved operation
+against the lower collection. Selected overlays use the same collection policy
+after the base source graph is composed. During mapping-sibling inheritance, a
+parent's YAML identity can follow its collection to the child destination, while
+the parent's explicit operation stays at the parent destination. The child
+destination selects its operation; absent one, effective identity implies
+upsert and its absence implies replace. Whole-sequence replacement discards
+lower YAML identity and uses the replacing scope's key declaration, if any;
+without one, the collection is unkeyed unless an application registration still
+supplies identity. Replacement discards policies owned by removed records, while
+an independently declared explicit mode and application registration remain
+applicable. Item-local
+policies follow their owning records: retaining a record retains its rules, while
+whole-record upsert replacement discards the displaced record's rules. Matching
+identity or reusing an index does not transfer them. These policies do not change
+CLI behavior: CLI sequence assignments replace whole sequences after decoding.
+A root `configkit.imports` declaration still requires `Options.Imports`;
+`NoSource` has no declaration scope.
+
 An empty mapping contributes no child definitions. Two empty mappings compose, and
 an empty mapping neither clears nor conflicts with another mapping's children.
 Shared mapping containers retain all contributing value locations as their composite
@@ -843,7 +975,9 @@ and typed decoding. Overlay bytes, nodes, and source records count toward the sa
 aggregate limits as base inputs. Its canonical path must remain within the configured
 root and must not duplicate a file already present in the base graph.
 
-Overlay is intentionally distinct from strict composition:
+Collection destinations follow the
+[collection operation and presence rules](#strict-document-composition) above.
+The following table describes ordinary overlay behavior elsewhere:
 
 | Existing lower node | Incoming overlay node | Result |
 | --- | --- | --- |
@@ -852,18 +986,24 @@ Overlay is intentionally distinct from strict composition:
 | Mapping | Mapping | Recurse by mapping key |
 | Any other pair of present nodes | Any other pair of present nodes | Replace the entire lower node |
 
-Scalars, sequences, and null are atomic. Thus an overlay sequence replaces rather
-than extends a base sequence, `[]` clears it, null is an explicit replacement, and
-cross-kind replacement is allowed when the final application schema accepts it.
+Under these ordinary rules, scalars, sequences, and null are atomic. An overlay
+sequence replaces rather than extends a base sequence, `[]` clears it, null is an
+explicit replacement, and cross-kind replacement is allowed when the final
+application schema accepts it.
 Replacing a subtree removes all displaced descendants from effective presence and
 origin data; history retains the displaced definitions and identifies the parent
 replacement. Surviving overlay paths have overlay origins, while recursively shared
 mapping containers retain their contributing locations.
 
-An overlay may not contain `configkit` anywhere, contribute the configured schema
-version, or replace an ancestor of that version with a scalar or null. These rules
-apply even if the supplied version text would be unchanged. Overlays cannot mask a
-base parse, composition, or version failure because those checks run first.
+An overlay may contain only root `configkit.sequences` declarations; overlay
+imports and nested directives are rejected. Sequence declarations are removed
+before application decoding. At declared or registered sequence destinations,
+`replace`, `append`, and `upsert` use the same identity and policy rules as source
+composition. Other overlay sequences remain atomic replacements. An overlay may
+not contribute the configured schema version or replace an ancestor of that
+version with a scalar or null. These rules apply even if the supplied version
+text would be unchanged. Overlays cannot mask a base parse, composition, or
+version failure because those checks run first.
 
 ## Explicit CLI overrides
 
@@ -875,10 +1015,16 @@ must never contain the raw argument or configured value. General environment
 variable overlays are an explicit non-goal: environment access is reserved for
 typed secret references.
 
-Overrides apply after the selected overlay and before typed defaults/decoding, so
-the input precedence is application defaults < composed base < selected overlay <
-CLI. Recorded resolution, typed secret lookup, and semantic validation follow the
-effective override tree. Overrides also work with `NoSource`.
+Overrides are prepared after source assembly and inheritance, then assigned after
+typed defaults and decoding and before application resolution. The order is:
+defaults and decoded sources < CLI < application resolution. A CLI mapping
+recursively overlays the decoded mapping; a CLI sequence replaces the complete
+decoded sequence regardless of source collection operations. Inheritance and
+typed defaulting do not run again after CLI assignment. Earlier parsing,
+composition, inheritance, and decoding failures remain errors even if an override
+would replace the failing value. Recorded resolution, typed secret lookup, and
+semantic validation use the effective post-override values. Overrides also work
+with `NoSource`.
 
 Values are converted directly into ConfigKit's owned tree without YAML parsing or
 string coercion. Supported values are `nil`, built-in strings and booleans, all
@@ -889,7 +1035,8 @@ false, and zero remain intentional; empty sequences replace whole lists; and map
 values recursively overlay existing mappings. Map keys are sorted canonically and
 sequence order is preserved.
 
-All records are detached and validated before any is applied. Root and explicit
+All records are detached and validated before any is applied. They cannot create
+`configkit` or `extends` controls. Root and explicit
 sequence-index paths are invalid; parsed numeric tokens remain mapping keys. A path
 may create missing mapping ancestors but cannot traverse an existing scalar, null,
 or sequence. Duplicate and ancestor/descendant-overlapping records are rejected.
@@ -906,8 +1053,12 @@ unsupported types, nonfinite floats, and limit excesses fail with safe `override
 diagnostics. Diagnostics and provenance identify the safe `Flag` source, never raw
 arguments or values.
 
-Override origins are explicit CLI origins. History retains replaced base/overlay
-definitions and records equal-value replacements as well as structural changes.
+Override origins are explicit CLI origins. Resolution receives CLI values with
+their explicit-presence and source information. Absence-based defaults preserve
+those values, while recorded normalization and derivation may change them. History
+retains replaced source definitions and records equal-value replacements as well
+as structural changes. Secret lookup and validation use post-resolution values
+with their effective source locations.
 Caller-owned maps and slices are snapshotted during loading and must not be mutated
 concurrently with the call. The executable `ExampleOverride` shows translating a
 parser's explicit-set state into records while preserving an explicitly supplied
@@ -915,9 +1066,11 @@ zero.
 
 ## Explicit imports
 
-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 `path`,
+Imports are opt-in. With `Options.Imports` enabled, a document may use its root
+`configkit` mapping for `imports` and `sequences` controls. Ordinary `Load` may use
+`sequences` without enabling imports, but an `imports` field still requires
+`Options.Imports`. ConfigKit removes recognized root controls before application
+decoding. Each imports sequence item is a mapping with exactly one `path`,
 `dir`, or `glob` selector. `path` and `dir` accept a string or a list of strings;
 `glob` accepts one path pattern string. The optional `required` boolean controls
 whether an empty selection or a missing named path is an error. Its default is
@@ -927,8 +1080,8 @@ 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`.
+key below the root is invalid. With imports disabled, root imports and nested
+`configkit` keys remain `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
@@ -976,6 +1129,12 @@ filenames unrestricted; a non-nil empty slice selects none. Defaults do not make
 a field applicable to selectors that do not support it, and load calls snapshot
 the supplied pointers and slice before source acquisition.
 
+A source's `configkit.sequences` declarations apply independently of import
+enablement; a `configkit.imports` declaration still requires `Options.Imports`.
+Sequence identities can be supplied either by these YAML declarations or by
+application registrations. The [strict composition contract](#strict-document-composition)
+defines their agreement, operation, and lifetime rules.
+
 Acquisition visits declarations in authored order and each declaration's selected
 paths in namespace-path lexical order, preserving source-record and version-callback
 order. Ordinary mapping contributions in a main tier are assembled dependency-first:
@@ -987,9 +1146,10 @@ mapping scope, with helpers before the bodies that import them. Those local scop
 do not use application collection policies and are not flattened into the outer
 schedule. Item positions and diagnostic paths follow the resulting assembly order.
 Each underlay group likewise acquires its inputs before dependency-ready assembly
-in one strict scope. Independent groups remain separate precedence tiers; a higher
-tier still replaces a lower tier's sequence values wholesale. Assembly order never
-permits replacement.
+in one strict scope. Independent groups remain separate precedence tiers; at a
+declared or registered destination, the assembled higher sequence uses the
+resolved collection operation against the lower sequence. Other sequences retain
+whole-value replacement between tiers. Assembly order never permits replacement.
 
 Acquisition order and resolution order serve different purposes: acquisition
 assigns source records and callback order, while the shared scheduler determines
@@ -1020,13 +1180,17 @@ Each declaration may include `placement: mapping` or
 including every match of a glob; placement is not inherited. Sequence-item
 placement requires a nonempty effective destination and wraps the imported
 mapping as one element of a sequence there. It does not split source sequences
-or infer identity fields. Repeated sequences still conflict unless their path is
-registered through `Definition.SequenceCompositions`; registration does not
-change placement or precedence behavior. Sequence records retain source
-locations through placement and history; indexes describe their assembled
-positions while source coordinates continue to identify the declaring files.
-Header/version policy and final application validation retain their existing
-owners and timing; sequence registration is a strict-composition rule only.
+or infer identity fields. Repeated sequences combine only when the destination
+has an applicable YAML identity declaration or application registration; source
+placement remains independent of collection identity and operation. Sequence
+records retain source locations through placement and history; indexes describe
+their assembled positions while source coordinates continue to identify the
+declaring files.
+Header/version policy retains its existing owner and timing. Application
+registrations also enforce identity on the final effective typed configuration;
+YAML-only declarations are enforced at structural combination and inheritance
+boundaries. The [configuration contract](#strict-document-composition) defines
+these validation boundaries.
 
 An item import first opens a local mapping scope. Its body and ordinary helper
 imports compose within that record. An omitted helper destination or

docs/consumers/README.md

@@ -21,7 +21,7 @@ sanitized shapes using only ConfigKit and the Go standard library:
 | Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
 | Effective configuration diff | Same-type frozen effective comparisons for two selected files or base-versus-overlay impact | Source/options selection and consumer-owned safe presentation |
 | Shared source-version checks | One `Definition.Version` policy for accepted declarations across participating source documents, with optional or required declarations and sanitized evidence | Choosing which declarations the application accepts; final assembled schema and domain validation |
-| Identified prompt sequences | Explicit item path/glob imports, helper-supplied IDs, reusable single-field registration, and main-tier replacement of a lower-priority collection | Prompt meaning and final domain validation |
+| Sequence catalogs | Declared collection operations, record inheritance, typed CLI and resolution, inspection, exact and wildcard application registrations | Catalog meaning and final domain validation |
 
 The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
 executable examples and ordinary tests. It contains no private application data,
@@ -184,36 +184,35 @@ import, source-location, and ownership behavior.
 
 ## Identified prompt sequences
 
-[`LoadPromptCatalog`](../../examples/consumers/prompt_catalog.go) uses one
-definition registration for the literal `prompts` path and `id` field. Its
-load-wide filename defaults accept two patterns, an explicit directory
-declaration overrides those patterns, and an exclusion omits one matching
-candidate. A nested ordinary helper import supplies an item's ID. A separate
-empty optional directory search is read from `SourceInfo.ImportSelections`.
-The executable example prints both the scheduled prompt order and the single
-empty-search outcome; the behavior test also follows a mounted resource through
-its effective metadata origin to the declaring source context. The completed
-main sequence replaces the lower-priority default collection as one value.
-The maintained [executable example and behavior tests](../../examples/consumers/prompt_catalog_test.go)
-show the scheduled result, empty-search inspection, excluded candidate, and
-resource lookup without a consumer-side discovery pass. The corresponding
-[complex fixture](../../examples/consumers/testdata/prompt-catalog/config.yml)
-and [simple required-file fixture](../../examples/consumers/testdata/prompt-catalog/simple.yml)
-are complete local examples.
+[`LoadPromptCatalog`](../../examples/consumers/prompt_catalog.go) shows the
+smaller import-focused adoption path: a registered `prompts.id` identity,
+directory and glob selection, a helper import that supplies an item's ID, and
+resource lookup through the effective source context. Its executable examples
+and tests are in
+[`prompt_catalog_test.go`](../../examples/consumers/prompt_catalog_test.go), with
+complete [catalog](../../examples/consumers/testdata/prompt-catalog/config.yml)
+and [required-file](../../examples/consumers/testdata/prompt-catalog/simple.yml)
+fixtures.
 
-[`LoadRequiredPromptCatalog`](../../examples/consumers/prompt_catalog.go) and
-[`Example_requiredPromptCatalog`](../../examples/consumers/prompt_catalog_test.go)
-keep the smaller adoption path visible: one explicitly required file import,
-the same identity registration, and the same application validation.
+[`LoadSequenceCatalog`](../../examples/consumers/sequence_catalog.go) integrates
+an underlay declaration, imported main fragments, identified-record inheritance,
+selected overlay `append`, `upsert`, and `replace`, a typed CLI override, and
+recorded application resolution. Its tests and runnable example demonstrate
+stable output order, whole-record upsert, provenance/history inspection,
+resource lookup for inherited records, and secret-safe explanation in
+[`sequence_catalog_test.go`](../../examples/consumers/sequence_catalog_test.go).
+[`LoadNamespacedMapCatalog`](../../examples/consumers/sequence_catalog.go) adds
+an exact root registration and a wildcard namespace registration, showing that
+each concrete sequence has an independent identity scope. The same tests show
+that a YAML identity declaration without an application registration does not
+create final-result identity enforcement.
 
-The example's `validatePromptCatalog` remains application-owned. It checks that
-prompt names and message lists satisfy this consumer's requirements after
-ConfigKit has composed, projected, and decoded the configuration. It does not
-add recursive record merging, identity-based overlay, or final uniqueness checks
-after defaults and resolution. See the [strict composition contract](../config.md#strict-document-composition),
-[import syntax](../config.md#explicit-imports), and
-[ADR 0014](../adr/0014-sequence-placement-and-composition.md) for the exact
-boundaries.
+The examples keep prompt meaning and domain checks in the consuming application.
+The [configuration contract](../config.md#strict-document-composition) owns
+declaration, identity, operation, ownership, and final-validation semantics;
+[sibling inheritance](../config.md#sibling-inheritance) defines record
+relationships, and the [CLI contract](../config.md#explicit-cli-overrides) owns
+override ordering.
 
 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

docs/development.md

@@ -135,12 +135,13 @@ Current behavior belongs to the configuration contract's
 [input destinations](config.md#input-destinations),
 [imports](config.md#explicit-imports), and
 [shared source-version checks](config.md#shared-source-version-checks) sections.
-Explicit sequence-item placement and registered strict composition are owned by
-the [strict composition](config.md#strict-document-composition) and
-[imports](config.md#explicit-imports) sections. The
-[maintained prompt catalog](consumers/README.md#identified-prompt-sequences)
-shows the current consumer boundary, and [ADR 0014](adr/0014-sequence-placement-and-composition.md)
-records the decision.
+Explicit sequence-item placement, collection operations, identity registration,
+and final registered-identity validation are owned by the
+[strict composition](config.md#strict-document-composition) section;
+[imports](config.md#explicit-imports) owns acquisition and scheduling. The
+[maintained sequence catalog](consumers/README.md#identified-prompt-sequences)
+shows the consumer boundary, and [ADR 0017](adr/0017-collection-sequence-policy.md)
+records the collection decision.
 
 The completed sequence-composition roadmap, implementation plan, and resolved
 remediation record are preserved in Git history at `008d2ba` under
@@ -218,6 +219,7 @@ code changes. Use the component overview to find the corresponding implementatio
 | Import defaults, empty-selection evidence, and dependency-ready ordering | [Defaults and facade evidence](../facade_import_defaults_test.go), [engine import evidence](../internal/engine/import_evidence_test.go), [scheduler](../internal/engine/dependency_order_test.go), [scheduling integrations](../internal/engine/imports_test.go) | `go test ./internal/engine -run 'Import|ScheduleDependencies|Inheritance'`, `go test . -run 'ImportDefaults|FacadeImport'`, and `go test ./examples/consumers` |
 | 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'` |
+| Sequence identity, declarations, and operations | [Identity](../internal/engine/sequence_identity_test.go), [registrations](../internal/engine/sequence_registration_test.go), [declarations](../internal/engine/sequence_declaration_test.go), [combination](../internal/engine/sequence_combine_test.go), [final facade validation](../facade_final_sequence_identity_test.go), and [consumer catalog](../examples/consumers/sequence_catalog_test.go) | `go test ./internal/engine -run 'Sequence\|Collection'`, `go test . -run 'SequenceIdentity\|SequenceRegistration'`, and `go test ./examples/consumers` |
 | 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` |
@@ -230,6 +232,7 @@ code changes. Use the component overview to find the corresponding implementatio
 | 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` |
+| Identified-sequence scaling evidence | [Mixed-upsert benchmark](../internal/engine/sequence_combine_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkSequenceMixedUpsert$' -benchmem` |
 | Inheritance scaling evidence | [Expansion benchmarks](../internal/engine/inheritance_bench_test.go) | `go test ./internal/engine -run '^$' -bench '^BenchmarkInheritance' -benchmem` |
 | Documentation links and dependency isolation | [Link checks](../documentation_test.go), [import boundary](../import_boundary_test.go), [public boundary](../public_boundary_test.go) | `go test . -run 'TestLocalDocumentationLinks\|TestDependencyImportBoundary\|TestPublicFacadeBoundary'` |
 | Development check behavior | [Development checker test](../development_check_test.go) | `go test . -run '^TestDevelopmentCheckHandlesFilenamesAndStopsOnFailure$'` |

docs/internal/imports.md

@@ -65,11 +65,18 @@ returns a closed cycle rotated to its smallest key; blocked dependents are not
 reported as cycle members.
 
 Import composition schedules a main tier or one underlay group as a single
-strict-scope graph. Item contributions own nested local strict-mapping scopes;
-their helpers complete before the item is placed in its outer scope. Inheritance
-uses the same ready-node rule inside each sibling mapping scope, while preserving
-the authored mapping order in its output. These scopes do not flatten into one
-global graph, and independent precedence tiers remain separate.
+strict-scope graph. Applicable collection declarations are gathered for the
+scope before peer composition, including identity inherited from lower tiers.
+Identified peer sequences then combine distinct records in assembled source and
+list order; after the strict scope completes, layered assembly applies the
+resolved collection operation against the lower value, as defined by the
+[configuration contract](../config.md#strict-document-composition). Item
+contributions own nested local strict-mapping scopes; their helpers complete
+before the item is placed in its outer scope. Inheritance uses the same
+ready-node rule inside each sibling mapping scope, while preserving the authored
+mapping order in its output.
+These scopes do not flatten into one global graph, and independent precedence
+tiers remain separate.
 
 The main owners are [`import_selection.go`](../../internal/engine/import_selection.go),
 [`directory_walk.go`](../../internal/engine/directory_walk.go),

docs/internal/overview.md

@@ -9,12 +9,13 @@ Implemented component owners:
 
 - `internal/engine` owns host and native-filesystem source acquisition,
   grouped strict composition, recursive precedence assembly, per-input mapping
-  and sequence-item placement, definition-registered distinct-ID sequence
-  composition within strict tiers, and immediate-parent-relative import
-  placement within that assembly. Higher-priority sequences replace lower
-  sequences as whole values. The engine also owns dependency-ready,
-  destination-local sibling inheritance before typed decoding, plus shared
-  source-version checking with sanitized declaration evidence.
+  and sequence-item placement, YAML collection declarations and operations for
+  identified sequences, and application identity registrations for strict
+  composition, inheritance, and final validation. It applies the selected
+  collection operation at precedence boundaries and owns dependency-ready,
+  destination-local inheritance before typed decoding. CLI assignment follows
+  inheritance and decoding, before application resolution. The engine also owns
+  shared source-version checking with sanitized declaration evidence.
   Explicit import discovery supports declared paths, directory searches, and
   globs; load-wide defaults and source-local empty-selection evidence cross the
   root facade without changing acquisition order. Import and inheritance
@@ -56,9 +57,10 @@ 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 [strict composition contract](../config.md#strict-document-composition)
-owns sequence placement, registration, replacement, and history behavior; the
-[consumer guide](../consumers/README.md#identified-prompt-sequences) shows the
-maintained example.
+owns sequence declarations, identity, operations, ownership, and final
+validation; [CLI overrides](../config.md#explicit-cli-overrides) own override
+ordering. The [consumer guide](../consumers/README.md#identified-prompt-sequences)
+links maintained workflow examples.
 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
@@ -74,5 +76,7 @@ records the source-version decision.
 sequence placement and composition. [ADR 0015](../adr/0015-shared-dependency-ready-ordering.md)
 records the shared dependency-ready ordering decision; [ADR
 0016](../adr/0016-independent-import-controls.md) records the independent
-selection controls. The [import internals](imports.md) document candidate and
+selection controls. [ADR 0017](../adr/0017-collection-sequence-policy.md) and
+[ADR 0018](../adr/0018-cli-after-structural-resolution.md) record collection
+operations and CLI ordering. The [import internals](imports.md) document candidate and
 namespace identities, discovery and scheduling, and the bounded algorithms.

docs/policy/architecture.md

@@ -32,11 +32,11 @@ structure as implemented when its changes land.
 Constraints must reflect deliberately selected requirements and decisions.
 Do not promote incidental implementation choices into architectural invariants.
 
-The collection-policy and CLI-ordering requirements below reflect accepted
-[ADR 0017](../adr/0017-collection-sequence-policy.md) and
-[ADR 0018](../adr/0018-cli-after-structural-resolution.md). The
-[sequence roadmap](../roadmap/sequences.md) tracks the work to implement them;
-the configuration contract continues to describe implemented behavior.
+The implemented collection-policy and CLI-ordering constraints below reflect
+accepted [ADR 0017](../adr/0017-collection-sequence-policy.md) and
+[ADR 0018](../adr/0018-cli-after-structural-resolution.md). The configuration
+contract owns their current behavior; these architectural constraints describe
+the system boundaries and guarantees that guide changes to that behavior.
 
 ## Success Criteria
 
@@ -373,8 +373,8 @@ as records survive, move, or are replaced. Identity diagnostics use paths and
 available origin information without exposing identity values. The guarantee
 requires no new mutation-history system or exact reconstruction of causes for
 records supplied by defaults or callbacks. Exact identity equality, declaration
-syntax, presence cases, and operation tables belong in the configuration contract
-when implemented; the roadmap owns those details until then.
+syntax, presence cases, and operation tables belong in the
+[configuration contract](../config.md#strict-document-composition).
 
 ## Ownership And Confidentiality
 

docs/roadmap/complexity.md

@@ -0,0 +1,221 @@
+# Internal Complexity Refactoring Roadmap
+
+Status: proposed target state. This roadmap defines a behavior-preserving
+refactor; a later implementation plan will define stages and exact private
+signatures and file names.
+
+## Purpose
+
+Make ConfigKit's import, inheritance, and projection implementation easier to
+understand, review, and change while preserving its public APIs and configuration
+behavior. Concentrate on functions that coordinate several responsibilities and
+carry substantial shared state.
+
+The target is clearer responsibility and ownership. Adding a few well-named
+helpers, private records, or focused files can serve that target even when total
+line count increases. Complexity measurements help locate candidates; they do
+not establish function-size limits, score thresholds, or release gates.
+
+The [architecture policy](../policy/architecture.md) owns package and ownership
+constraints. The [configuration contract](../config.md) and exported Go comments
+remain authoritative for consumer behavior.
+
+## Current Baseline
+
+Reviewed baseline: `7a83704f43ef9870db33661231cdff5d6ee502f7`.
+
+The root facade delegates to a cohesive private engine, supported by the ordered
+document representation and YAML adapter. Most functions are small. The
+complexity audit identified these concentrated maintenance costs:
+
+| Area | Current implementation | Required improvement |
+| --- | --- | --- |
+| Imports | `imports.go` spans acquisition, item-local composition, and evidence projection. Private loading variants pass long positional argument lists. Source admission and directory selection contain substantial mixed control flow. | Give import entry points explicit, cohesive inputs and separate the responsibilities of acquisition, scope assembly, and evidence projection. |
+| Inheritance | `applyInheritanceScopeTemplates` coordinates payload preparation, parent combination, policy ownership, origins, history, and accounting in one executor. | Keep one readable executor with focused operations and explicit state handoffs. |
+| Projection | `valueOperation.project` combines type dispatch with struct flattening, map and sequence traversal, scalar conversion, sensitivity, and accounting. | Retain clear dispatch while moving substantial value-kind handling into focused helpers. |
+
+The implemented inventory belongs to the
+[component overview](../internal/overview.md). Existing import flow and scheduling
+are described in [import internals](../internal/imports.md).
+
+## Target Architecture
+
+The refactor stays within `internal/engine`. The root facade, `internal/document`,
+and `internal/yaml` retain their existing responsibilities and dependency
+direction. Focused files and ordinary private functions express the new internal
+organization. Package extraction is outside this roadmap's selected design.
+
+`executeLoadRequest` remains the visible coordinator of the shared load lifecycle.
+Its phase order should remain easy to follow. Helpers expose meaningful work and
+results rather than distributing that order across a generic execution framework.
+
+Existing shared mechanisms remain shared: recursive mapping combination,
+identified-sequence operations, dependency-ready scheduling, schema descriptors,
+and projection/accounting state. New helper boundaries make their ownership and
+use clearer without creating parallel implementations.
+
+### Imports: Cohesive Inputs And Scope Ownership
+
+Import loading has a clear private entry surface using named request/context
+fields for related inputs. Reuse the existing load-request, acquisition-scope,
+and traversal models where they fit. Consolidate forwarding variants whose only
+purpose is passing another optional positional argument through the chain.
+Retain convenience helpers when they express a useful, distinct operation.
+
+Keep these state lifetimes identifiable:
+
+- Load-wide state: accounting, shared inclusion/repetition information,
+  namespaces, and source-version processing.
+- Acquisition requests: source and filesystem context, placement, declarations,
+  applicable policy, and the relevant assembly handoff.
+- Composition scopes: peer contributions, item-local helpers, record ownership,
+  and pending declarations.
+- Evidence: physical source records, effective destinations, origins, and retained
+  history projections.
+
+Group acquisition, pending-item assembly, and evidence projection in focused
+files. A caller should be able to identify which operation acquires resources,
+which composes already acquired content, and which projects retained evidence.
+Shared mutable state has a visible owner; a request record need not duplicate
+state already held by that owner.
+
+Within dense admission, directory-selection, and declaration-parsing routines,
+extract coherent operations where that reduces nested, mixed responsibilities.
+Preserve the existing selection algorithms and host/native filesystem behavior.
+Resource ownership and closure remain explicit across success and failure paths.
+
+The resulting flow preserves the distinction among acquisition order, strict
+scope scheduling, and precedence. Completing a helper scope before placing its
+item remains part of the same import flow. Ordinary and layered loading continue
+to share the applicable mechanisms.
+
+### Inheritance: One Executor With Explicit Phases
+
+Keep the mapping and identified-sequence adapters and their shared template
+executor. The executor coordinates focused operations for:
+
+- Preparing child payload, directives, and destination-local state.
+- Preparing the resolved parent payload and applicable inherited policy.
+- Combining values through the existing mapping and sequence mechanisms.
+- Producing policy, origin, replacement, and replay evidence from that combination.
+- Accounting for expansion and retained history under the existing budgets.
+
+These are responsibility boundaries, not a required helper count or a new
+scheduler. Small private result records are appropriate when related outputs
+otherwise travel through long argument lists or implicit mutations.
+
+Authored templates, resolved values, scoped policy, and inspection evidence remain
+distinguishable. Immutable borrowed inputs and owned mutable results have clear
+lifetimes. Nested instructions remain available for destination-local evaluation.
+For identified-record inheritance, the child's own identity fields and origins
+remain intact; the parent's identity fields are excluded from inherited payload
+and its history, as the current contract requires.
+
+One sequence-operation result continues to drive value construction, record
+ownership, origins, and historical position projection. Helpers consume that
+evidence directly. Scheduling remains dependency-ready, enclosing relationships
+resolve before nested ones, and assembled sequence order remains unchanged.
+
+### Projection: Explicit Value-Kind Handlers
+
+Keep `projectConfiguration` as the schema-checked entry and `valueOperation` as
+the owner of per-operation traversal and accounting state. The central dispatch
+clearly selects the appropriate handling for pointers, dynamic values, structs,
+maps, sequences, and scalars.
+
+Substantial struct, map, and sequence work lives in focused handlers. Struct
+projection retains declaration order, inline flattening, collision diagnostics,
+and sensitivity propagation. Map projection retains deterministic key ordering.
+Scalar conversion retains the existing number, duration, text-codec, and secret
+reference representations.
+
+Depth and node accounting retain their existing meaning, including flattened
+containers. Cycle tracking stays active through recursive child traversal and
+is balanced on error paths as well as success. Passing state through a helper
+does not introduce another full-tree projection or an unnecessary ownership copy.
+
+Cloning and source-value construction remain distinct operations with their
+existing semantics. Reuse small helpers when the semantics coincide; keep the
+projection refactor centered on making the existing traversal readable.
+
+## Behavior And Scope Preservation
+
+The implementation preserves:
+
+- Root-owned public types, signatures, supported import paths, and facade boundaries.
+- Supported source forms, opt-ins, import controls, placement, acquisition and
+  composition ordering, and source/version evidence.
+- Strict peer composition, precedence operations, identity agreement and lifetime,
+  record ownership, and destination-local inheritance.
+- The load lifecycle, including typed defaults, post-decode CLI assignment,
+  recorded application resolution, and final validation.
+- Explicit presence, provenance, history, sensitivity, resource contexts, and
+  detached publication/query results.
+- Established diagnostic codes, semantic paths, source coordinates, ordering,
+  resource lifetime, and existing limit behavior.
+
+The owning contracts define the extent of these obligations. Incidental private
+call sequences, exact helper names, and allocation counts do not acquire new
+guarantees through this roadmap. The work adds no consumer options, configuration
+syntax, dependencies, or complexity-based gates.
+
+## Relationship To Remediation And Other Work
+
+[Remediation](remediation.md) owns the identified correctness and algorithmic
+efficiency findings. Several overlap these files, particularly item-scope
+application matching and inheritance policy localization.
+
+Use the documented contract and completed remediation as the behavioral baseline.
+Keep corrective changes reviewable under their findings, and retain their
+regressions through this refactor. The later implementation plan should coordinate
+overlapping work and select its starting revision rather than duplicating the
+remediation plan here. These structural changes do not close a finding merely
+because its function moved or became smaller.
+
+The pending [discovery roadmap](discovery.md) remains separate feature work.
+Import cleanup should leave clear private boundaries for future use without
+implementing discovery behavior as part of this refactor.
+
+## Work Needed And Validation
+
+Implementation needs to consolidate import inputs and adapters, separate import
+responsibilities, extract inheritance operations with explicit outputs, and
+decompose projection handling. Remove superseded private plumbing as its callers
+migrate. Review the resulting call flow for repeated traversals, policy scans,
+copies, or hidden state transitions introduced by extraction.
+
+Reuse the existing behavioral suites under the
+[development guide](../development.md) and [testing policy](../policy/testing.md):
+
+- Imports: selection, scheduling, source/version evidence, placement, helper scopes,
+  ordinary/layered equivalence, filesystem failures, and resource lifetime.
+- Inheritance: mapping and record relationships, nested destination resolution,
+  cancellation and replacement, policy ownership, history, sensitivity, and
+  independent loads.
+- Projection: schema/decoding agreement, inline fields, text codecs, nil/empty
+  values, cycles and budgets, secrets, and detached results.
+
+Add focused regressions only where a consequential handoff risk lacks coverage.
+Tests should continue to describe behavior as private functions and files move.
+Use the existing everyday check and applicable ownership race checks during
+implementation. Complexity measurements can inform review; acceptance does not
+depend on numerical scores or a new benchmark campaign.
+
+Update the component overview and import internals to describe the implemented
+ownership and file responsibilities when the refactor lands. Update contributor
+navigation and test-owner references where moves affect them. Public behavior
+continues to be defined by its current canonical owners.
+
+## Completion Criteria
+
+- Import callers pass cohesive named inputs, with clearly owned load-wide and
+  scope-local state and fewer redundant forwarding variants.
+- Import acquisition, item assembly, and evidence projection are easy to locate
+  and follow across focused private files.
+- Inheritance orchestration exposes value, policy, evidence, and accounting work
+  without requiring readers to reconstruct their interaction from one large body.
+- Projection dispatch and substantial value-kind handlers have clear boundaries
+  and share the original operation state correctly.
+- Existing APIs and contracted behavior, including completed remediation, remain
+  covered by the relevant behavioral and ownership checks.
+- Internal documentation matches the resulting implementation.

docs/roadmap/discovery.md

@@ -0,0 +1,381 @@
+# Composable Configuration Discovery Roadmap
+
+Status: proposal with OD-1 through OD-5 and the final review clarifications
+settled and integrated below.
+This document describes future work, not an implemented contract. A staged
+implementation plan will follow review of the complete roadmap.
+
+## Purpose And Ownership
+
+Make ordinary file-based loading concise for applications that want conventional
+configuration locations. ConfigKit supplies useful built-in candidate lists and
+an ordered selection operation. Consumers continue to own main-file search
+conventions: they choose which lists apply, their order, custom candidates, and
+whether a configuration file is required.
+
+A consumer can select one preset for a simple application or compose several
+presets and custom path lists. The application supplies an explicit slug where
+needed to construct conventional paths. ConfigKit does not infer application
+identity from the executable name or enable discovery for existing explicit
+sources.
+
+Discovery selects one source for the existing loading lifecycle. It does not
+create additional configuration tiers or merge every matching file. Existing
+layered loading remains available when consumers intentionally combine sources.
+
+## Current Baseline
+
+The [source contract](../config.md#sources) provides explicit host files, native
+filesystem files, bytes, readers, mappings, and `NoSource()`. A missing explicit
+file fails. The zero source is invalid. There is no conventional main-file search.
+
+[Ordinary loading](../config.md#single-source-loading) infers a selected overlay's
+filesystem context from the main source. `NoSource()` currently rejects enabled
+imports, active overlays, and filesystem context. In
+[layered loading](../config.md#layered-loading), an absent main input can coexist
+with underlays; a selected overlay requires an explicit `OverlayFilesystem`.
+These distinctions matter when an optional search finds nothing.
+
+The [architecture policy](../policy/architecture.md#responsibility-boundaries)
+assigns search conventions to consumers and currently excludes implicit main-file
+discovery. The addition should clarify that consumers may explicitly select
+library-provided search conventions. Consumer ownership remains unchanged.
+
+## Agreed Direction
+
+### Filename Groups, Directory Searches, And Search Presets
+
+Organize discovery around three composable descriptions. These are ordered lists:
+their order determines precedence.
+
+**Filename groups** provide reusable, ordered filename templates. The built-in
+groups are:
+
+| Group | Filenames, in order |
+| --- | --- |
+| Named | `<appname>.yml`, `<appname>.yaml` |
+| Generic | `config.yml`, `config.yaml`, `main.yml`, `main.yaml` |
+
+`<appname>` is the application slug supplied by the consumer.
+
+**Directory searches** pair a directory with an ordered list of filename groups.
+The default selection is `[Named, Generic]`, producing the six filenames above
+in that order. A directory search may select different groups or reverse their
+precedence, such as `[Generic, Named]`, while retaining each group's internal
+order. Consumers can also supply custom filenames, subject to the literal
+single-component rules under OD-5 below.
+
+**Search presets** bundle ordered directory searches. Consumers can select a
+complete preset for the simple case or compose presets, custom directory searches,
+and explicit file candidates in their desired order. Explicit file candidates
+are literal paths and receive no filename expansion.
+
+### Ordered Expansion And Concatenation
+
+The selection model is **ordered expansion and concatenation**, followed by
+first-match selection:
+
+1. Expand the selected presets into directory searches in their supplied order.
+2. For each directory search, concatenate its selected filename groups in order,
+   substitute the application slug where needed, and join each filename to that
+   directory.
+3. Concatenate the resulting candidate lists, preserving the positions of custom
+   directory searches and explicit file candidates.
+4. Try candidates in order, stopping at the first selected file or an error as
+   described below.
+
+Directory priority comes before filename priority: exhaust one directory's
+filenames before trying the next directory. When several directories share a
+filename list, their expansion is a Cartesian product traversed directory first.
+Different directories may select different lists, so ordered expansion and
+concatenation describes the complete model. Set union does not express its
+precedence semantics.
+
+The eventual documentation should explain this model using the applicable
+mathematical nomenclature: ordered lists, ordered concatenation, and Cartesian
+product where a shared filename list applies. Retain these names in relevant
+implementation comments where they help readers understand the operations. The
+model describes ordering without requiring eager construction of every candidate.
+
+### Unix System Preset
+
+The agreed Unix system preset is:
+
+| Directory, in search order | Filename groups, in order |
+| --- | --- |
+| `/usr/local/etc/<appname>` | `[Named, Generic]` |
+| `/etc/<appname>` | `[Named, Generic]` |
+| `/etc` | `[Named]` |
+
+This produces 14 candidates: six in each application-specific directory, then
+`/etc/<appname>.yml` and `/etc/<appname>.yaml`. For example,
+`/usr/local/etc/<appname>/main.yaml` precedes
+`/etc/<appname>/<appname>.yml`. Selecting only `Named` for `/etc` is an ordinary
+directory-search description; the selection algorithm needs no special exception.
+
+### Additional Presets (OD-1 — Settled)
+
+Provide the following independently selectable presets alongside Unix system.
+Within each preset, search directories in the order shown:
+
+| Preset | Directory | Filename groups, in order |
+| --- | --- | --- |
+| User configuration | `<user-config-dir>/<appname>` | `[Named, Generic]` |
+| User configuration | `<user-config-dir>` | `[Named]` |
+| Home directory | `<home>/.<appname>` | `[Named, Generic]` |
+| Home directory | `<home>` | `[Named]` |
+| Working directory | Current working directory | `[Named]` |
+
+Resolve the user-configuration base with
+[`os.UserConfigDir`](https://pkg.go.dev/os#UserConfigDir), the home base with
+[`os.UserHomeDir`](https://pkg.go.dev/os#UserHomeDir), and the working-directory
+base with [`os.Getwd`](https://pkg.go.dev/os#Getwd). Adopt the Go helpers'
+platform-specific directory and environment behavior, including their errors;
+the settled OD-2 rules below govern how discovery handles resolution errors.
+
+The goal is to support familiar conventions through idiomatic Go. This feature
+does not add a separate XDG compatibility layer or XDG system preset. A selected
+user-configuration base has no additional hard-coded `<home>/.config` fallback.
+The Home directory preset is a separate, explicit choice.
+
+The working-directory preset searches only that directory and uses application-named
+files; it does not walk ancestor directories. The consumer chooses precedence
+between all presets. Selecting one does not automatically select any others.
+
+### Illustrative Consumer API
+
+Names below are illustrative and are not implemented Go API:
+
+```go
+// A simple system-wide application.
+source := configkit.SearchConfig("myapp", configkit.UnixSystemDirectories())
+```
+
+```go
+// A consumer-selected working-directory, user, then system search.
+source := configkit.SearchConfig(
+    "myapp",
+    configkit.WorkingDirectory(),
+    configkit.UserConfigDirectory(),
+    configkit.UnixSystemDirectories(),
+)
+```
+
+```go
+// Explicit custom candidates followed by a selected conventional fallback.
+source := configkit.SearchConfig(
+    "myapp",
+    configkit.Paths("/run/myapp/config.yml", "/opt/myapp/config.yaml"),
+    configkit.UnixSystemDirectories(),
+)
+```
+
+Use the resulting source with ordinary loading or as a layered main input. Custom
+searches and file lists participate at their specified position; they do not
+silently append unselected presets. Reordering presets or their directory
+searches changes search priority.
+
+### Selection And Failure Behavior
+
+| Situation | Selected behavior |
+| --- | --- |
+| Candidate is absent | Continue to the next candidate. |
+| A candidate file is selected | Stop searching and load that file. |
+| Candidate is inaccessible, unreadable, or not an accepted file type | Fail using normal source diagnostics. |
+| Selected file fails parsing, version checks, composition, decoding, or validation | Fail without trying another candidate. |
+| Entire search has no match | Absence is permitted by default; follow the shared absent-main lifecycle settled under OD-3 below. |
+| Entire search has no match and is required | Fail with a diagnostic explaining the unsuccessful search. |
+| Caller explicitly uses `File(path)` | Retain existing exclusive-file behavior, including errors for a missing file. |
+
+Requiredness applies to the complete search, not to each preset or directory.
+Permitting an absent file does not waive application version, schema, or domain
+requirements; the remaining lifecycle may still reject an incomplete configuration.
+
+Perform discovery before parsing the chosen main file. Do not implement fallback
+by repeatedly running complete loads. Defaults, application resolution, secret
+lookup, and final validation retain their existing lifecycle execution rules.
+Once a file has been selected, later failure does not restart discovery.
+
+### Construction And Filesystem Behavior
+
+Constructors describe the search without filesystem access. Resolve dynamic base
+directories and access candidate files during loading, so reusable descriptions
+can observe changes on subsequent loads. Do not change the process working
+directory or environment.
+
+Reuse the host-file acquisition rules for selected files, including regular-file
+checks, symlink handling, resource ownership, and source limits. The feature does
+not require a new filesystem traversal engine, recursive directory search, or
+new file-size limits. Candidate filenames and groups are bounded by their
+explicit descriptions, rather than by scanning unrelated directories.
+
+The exact Go names, constructors, and representation of search-wide options
+belong in the implementation plan. Keep the public surface root-owned and keep
+the single-preset case concise.
+
+### Unavailable Bases And Platform Applicability (OD-2 — Settled)
+
+Resolve directory bases only as the ordered search reaches them. Once an earlier
+candidate is selected, later searches do not resolve their bases. Static invalid
+search arguments still fail ordinary option validation before source acquisition.
+An explicitly empty filename selection skips directory resolution as specified
+under OD-4; it has no candidates to locate.
+
+If a selected directory's base cannot be resolved, stop and report the error.
+A missing directory or candidate file beneath a resolved base allows the search
+to continue; a directory-resolution error does not. This distinction also applies
+to optional searches: permitting no match does not suppress errors encountered
+while searching. Preserve the agreed errors for inaccessible or unreadable
+candidates.
+
+Treat using the Unix system preset on an unsupported platform as an explicit
+configuration error when that preset is reached. Specify its supported platforms
+in the implementation plan. Do not translate the Unix preset into a different
+platform's convention. User, home, and working-directory presets use their native
+Go directory helpers.
+
+This keeps search priority predictable when directory resolution fails. Consumers
+select the presets appropriate to their application and environment; this proposal
+does not add an option to skip unavailable bases or unsupported presets.
+
+### No Match, Imports, And Selected Overlays (OD-3 — Settled)
+
+Use a shared absent-main lifecycle for optional no-match and explicit `NoSource()`.
+Allow imports to be enabled when the main file is absent: there are no main-file
+import declarations to process, and enablement does not introduce automatic
+directory scanning. Other actual sources retain their normal import behavior.
+In layered loads, process underlays normally and retain the existing explicit
+`OverlayFilesystem` requirement for an active overlay.
+
+For ordinary loads with an active overlay and no main file, require an explicit
+filesystem context to locate the overlay. Do not infer an overlay root from the
+first or last searched directory. A missing selected overlay remains an error;
+absence of a main file does not silently disable a requested overlay.
+
+For an absent main input, a host filesystem context specifying only `Root` is
+sufficient to locate the overlay; no main-file `BaseDir` is needed. If discovery
+selects a host file, retain the normal file-context rules: the selected file
+determines its base directory, an explicit `BaseDir` is rejected, and the file
+must be contained within any supplied root. This allows one root-only context
+to work with both selected and absent main inputs, subject to those existing
+root and containment checks. An invalid context is an error, not a reason to
+resume discovery.
+
+Defaults, CLI overrides, application resolution, and validation continue through
+the normal lifecycle. Main-version checking receives an absent main input and
+may reject it under the application's existing policy. Create no synthetic empty
+document or source record for the absent main file.
+
+This deliberately relaxes the current `NoSource()` restrictions on imports and
+on overlays with explicit context. Both ways of obtaining an absent main input
+have the same behavior. Implementation must cover this lifecycle change as well
+as candidate selection.
+
+### Empty Composition And Implicit Preset Selection (OD-4 — Settled)
+
+Require explicit preset or search selection to activate a convention. Supplying
+no presets or custom searches produces no candidates and activates no implicit
+fallback. Empty custom path lists and explicitly empty filename-group selections
+also contribute no candidates. An empty component does not prevent later
+components from contributing candidates.
+
+A directory search with an explicitly empty filename selection does not resolve
+its directory base. Static argument validation still applies. This gives empty
+selections their no-candidate meaning without introducing directory-resolution
+errors for a search that cannot select a file.
+
+If the complete search is empty, an optional search follows the absent-main
+lifecycle settled under OD-3; a required search fails as exhausted. Empty lists
+are valid, supporting consumers that construct their searches programmatically.
+
+Distinguish omission from an explicitly empty filename selection for a directory
+search. Omitting the selection uses the agreed `[Named, Generic]` default;
+explicitly selecting an empty list means no filenames. The eventual API must
+represent both intentions clearly. Presets retain their specified filename groups.
+
+Selecting a single preset keeps the simple case concise. Search-wide requiredness
+provides the check for consumers that must find a configuration file.
+
+### Slugs And Custom Path Interpretation (OD-5 — Settled)
+
+Require a nonempty single-component application slug whenever a selected search
+uses it to construct a directory or filename. Reject path separators, `.` and
+`..`, and forms unusable as that component on the target platform. Preserve
+spelling and case; do not trim, lowercase, or impose a kebab-case naming scheme.
+Validation keeps the slug from changing the intended directory structure without
+imposing a separate naming style.
+
+Searches that do not use the slug do not require one. Examples include explicit
+file candidates and a custom directory searched with only Generic filenames.
+
+Treat custom paths as literal host paths. Resolve relative paths against the
+working directory at load time. Do not expand shell variables, `~`, or wildcard
+syntax. Consumers can construct expanded paths themselves; User and Home presets
+provide the common directory-resolution conveniences. These rules keep custom
+paths consistent with explicit file loading.
+
+Custom filenames within directory searches are literal single filename
+components. They cannot be absolute paths or contain subdirectory components;
+use custom directory searches or explicit file candidates for those layouts.
+They receive no application-name placeholder expansion. The Named group supplies
+application-name expansion, while consumers may construct custom filenames
+themselves before supplying them.
+
+### Placement, Provenance, And Existing Features
+
+The selected file participates as the actual file source. Preserve its physical
+identity, effective placement, source origin, and passive resource context.
+Relative imports and relative application resources use the selected file's
+normal context. Discovery does not relocate overlay or CLI coordinates.
+
+Missing candidates are not acquired sources and do not create source IDs,
+configuration history, or explicit input presence. An entirely absent search
+contributes no synthetic empty configuration file. Diagnostics should distinguish
+an exhausted required search from a failed candidate. Existing selected-source
+inspection remains the foundation; a new public per-attempt trace is not needed
+for this proposal.
+
+Preserve collection policies, inheritance, source-version rules, CLI ordering,
+final validation, and frozen inspection after selection. Search-list order does
+not change precedence among underlays, the main input, an overlay, and CLI values.
+An explicitly selected overlay is not another main-file fallback candidate.
+
+## Work Needed From The Baseline
+
+The subsequent implementation plan should cover:
+
+- Define filename-group, directory-search, preset, and search-source representations,
+  slug validation, and a search-wide requiredness option. Keep construction
+  separate from acquisition and the simple preset selection concise. Distinguish
+  omitted and explicitly empty directory-search filename selections.
+- Implement ordered expansion and concatenation for presets, filename groups,
+  custom searches, and explicit file candidates, followed by first-match selection
+  through existing file access. Resolve each source once per consumption before
+  entering its parse and composition lifecycle.
+- Integrate selected and absent outcomes with ordinary and layered main inputs,
+  placement, imports, application version checking, and overlay contexts according
+  to OD-3, including root-only host contexts for absent main inputs and normal
+  file-context checks when a file is selected. Preserve ownership and close
+  acquired handles on success and failure.
+- Preserve real selected-source metadata and safe diagnostics without treating
+  absent candidates as configuration contributions.
+- Exercise preset, directory, filename-group, and filename ordering, reversed
+  group precedence, the Unix system preset's 14 candidates and named-only `/etc`
+  search, custom-list composition, both filename extensions, no-match behavior,
+  empty components and searches, omitted versus empty filename selections,
+  skipped directory resolution for empty filename selections, slug-dependent and
+  slug-independent searches, literal custom paths and filename components,
+  required searches, unavailable preset bases, errors that must stop fallback,
+  repeated loads, and untouched explicit `File`
+  behavior. Cover imports, overlays, underlays, defaults, CLI, source versions,
+  source contexts, and source-list/inspection evidence at their boundaries.
+- Clarify the architecture policy's consumer-selected discovery boundary. Record
+  any warranted durable ownership decision in an ADR; keep preset filenames and
+  API mechanics in their canonical contract when implemented. Update consumer
+  examples and the configuration contract when the feature lands. Explain the
+  three-part discovery model and its mathematical terminology in the eventual
+  documentation, with simple preset selection and custom composition examples.
+
+This roadmap does not change implementation, policy, or ADRs by itself. Coordinate
+implementation with the ongoing sequence integration audit rather than assuming
+its in-progress changes are part of a fixed implementation baseline.

docs/roadmap/future.md

@@ -6,112 +6,19 @@ commitments. Adopting a candidate requires an explicit design decision and a
 separate plan. Significant architectural exclusions and their rationale belong
 in ADRs; this document does not maintain a list of rejected proposals.
 
-## 1. Identified record sequences
+## 1. Recursive body merging for identified records
 
-Status: deferred. PromptKit proposed this capability from its retired proposal 2,
-**Namespaced Collections As Identified Records**. The original proposal is in the
-PromptKit repository at
-`b5866dd:docs/roadmap/configuration-collections-identified-records.md`.
-PromptKit selected mounted mappings instead; this feature is not a dependency
-of that design or a request to restore multiple installed prompt versions.
+Status: deferred. The implemented
+[collection policy](../config.md#strict-document-composition) uses `upsert` to
+replace a complete matched record. Recursive merging of fields inside matching
+records remains a separate candidate and would revisit the whole-record update
+boundary selected by [ADR 0017](../adr/0017-collection-sequence-policy.md).
 
-A narrower [sequence placement and composition feature](../config.md#strict-document-composition)
-is implemented: consumers can place imported mappings as sequence items and
-register a single literal string identity field for duplicate-rejecting strict
-composition. Precedence still replaces sequences as whole values. This entry
-tracks broader identified-record behavior that remains deferred and is not part
-of that implemented contract.
-
-The active [sequence roadmap](sequences.md) now selects a narrower design for
-collection policy, compound scalar identities, final application-registered
-identity validation, and inheritance within identified sequences. It owns those
-selected behaviors and their remaining decisions. The original broader proposal
-below remains background for further consideration, particularly recursive
-combination of matching record bodies; it does not override the active roadmap.
-
-### Motivation and proposed behavior
-
-Allow applications to declare that selected sequences contain records identified
-by explicit fields, while retaining sequence-shaped output for slice decoding
-and effective YAML. This could make composite identities and independently
-authored catalogs more convenient than encoding identity in nested mapping keys.
-Current [composition](../config.md#strict-document-composition) appends distinct
-records only at explicitly registered paths; other sequences remain atomic.
-Selected [overlays](../config.md#selected-overlays) always treat sequences
-atomically.
-
-The proposed broader opt-in registration would extend the current reusable
-application definition from one identity field to a composite identity made of
-an ordered, nonempty set of distinct direct string-field names. For example,
-records at `profiles` could be identified by `(namespace, id)`. Records
-`(provider, brief)`
-and `(application, brief)` would coexist, and a later layer could update the
-provider record's temperature while retaining its backend and model.
-
-The requested semantics, all still subject to design review, are:
-
-- Match exact string tuples, preserving component boundaries and spelling,
-  including empty strings. Every contribution supplies its complete identity;
-  defaults, inheritance, filenames, and normalization do not supply it.
-- Retain distinct identities. Matching records from strict peers recursively
-  compose disjoint body fields and conflict on overlapping non-mapping body
-  values, even equal values. Equal identity fields act as structural keys rather
-  than conflicts and retain their contributing source evidence.
-- Higher layers recursively overlay matching bodies. A changed identity denotes
-  a different record, not a rename. Proposed ordering is first contribution in
-  precedence-assembly order; matching records keep position and new ones append.
-- Reject malformed identities, non-mapping records, non-null non-sequence values
-  at registered paths, and duplicate tuples within one source sequence. Later
-  layers cannot repair malformed structural identity in an acquired contribution.
-- Treat an empty registered sequence as contributing no records; whole-path null
-  retains ordinary conflict/replacement semantics. Unregistered sequences,
-  including nested message lists, retain existing atomic behavior.
-- Support record inheritance within the same registered sequence using an
-  `extends` mapping containing the complete parent tuple. Resolve only final
-  active relationships after precedence, preserve the child's identity, overlay
-  its body on the parent's body, and consume the directive before decoding.
-  Preserve cancellation, missing-parent/cycle errors, and declaring resource
-  contexts. Existing string-based mapping-sibling inheritance stays unchanged.
-
-Integrate ordinary and layered loads, imports, mounted paths, selected overlays,
-and whole-sequence CLI overrides. Keep origins, presence, history, sensitivity,
-and resource contexts attached to the correct record despite different source
-and final indexes. Diagnostics must retain source locations without exposing
-sensitive identity values. Final inspection may use snapshot-specific sequence
-indexes; existing atomic sequence diffs need not become identity-aware.
-
-Successful results would have valid, unique identities, including after defaults
-and application resolution, without a second merge or inheritance pass. Existing
-source-version checks remain independent; consumed headers cannot supply missing
-record identities. No identity-selector path syntax, arbitrary merge callbacks,
-wildcard registration, per-record deletion/rename operator, multiple inheritance,
-or cross-path parent references are requested.
-
-### Questions to resolve before implementation
-
-- **Need and delivery scope:** does an active consumer benefit enough to justify
-  the added semantics over keyed mappings? Are composite identities required?
-  Staging composition before inheritance is possible but would leave part of
-  the request incomplete.
-- **Defaults and callbacks:** do default records merge by identity or retain
-  existing sequence-replacement behavior? How are callback-created duplicates,
-  identity edits, and reordering validated and reflected in provenance?
-- **Null, empty, and order:** what happens when null clears a collection and a
-  later layer reintroduces records? How do absent and explicitly empty sequences
-  interact with defaults and first-contribution order?
-- **Inheritance references:** how do peers compose relationship declarations,
-  and how are complete references enforced without assembling partial tuples
-  accidentally? What happens if identity fields overlap structural controls?
-- **Registration paths:** how do overlapping registrations and paths beneath
-  sequence indexes behave when assembly changes those indexes?
-- **Evidence and lifecycle:** how are record identities mapped between source
-  trees, history, inheritance, callback snapshots, and final indexes without
-  mixing records' provenance or sensitivity? Where do identity checks run relative
-  to header consumption and other structural processing?
-
-Keep the feature deferred until its consumer value and full lifecycle design
-justify reconsidering the sequence-merging exclusion. A correct final sequence
-alone would not establish correct inspection or disclosure behavior.
+Consider this only in response to a concrete consumer need. A proposal would need
+to define conflicts for overlapping body fields, removal of omitted fields,
+presence and ordering, and how provenance, history, sensitivity, and resource
+context follow partially retained records. Any change requires a new decision and
+implementation plan; this entry does not alter current upsert behavior.
 
 ## 2. Required version declarations for selected sources
 

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Sequence Identity And Combination Implementation Plan
 
-Status: ready for implementation; no stages completed.
+Status: all thirty stages complete.
 
 Audience: a Luna coding agent implementing one numbered stage per prompt, in
 order. This plan starts at commit
@@ -175,6 +175,9 @@ Validation: `go test ./internal/engine -run 'SequenceIdentity|SequenceNumber'`
 and the everyday check. Retain the old registration path until its adapters are
 replaced; do not generalize unrelated YAML scalar decoding.
 
+**Completion:** Implemented and verified with the focused identity tests and
+`./scripts/check.sh`.
+
 ## Stage 2 — Compile Exact And Dynamic Application Constraints
 
 Scope: private registration model, selector matching, overlap validation.
@@ -196,6 +199,9 @@ Scope: private registration model, selector matching, overlap validation.
 Validation: focused registration/selector tests and the everyday check. This
 stage does not export the replacement API or add final-result validation yet.
 
+**Completion:** Implemented and verified with focused registration/selector
+tests and `./scripts/check.sh`.
+
 ## Stage 3 — Parse Collection Declarations Without Filesystem Coupling
 
 Scope: private parser and directive extraction helpers, initially unit-tested
@@ -228,6 +234,9 @@ in Stages 13 and 14 respectively.
 Validation: focused declaration/parser tests, existing import-spec tests, and the
 everyday check. Existing import-only behavior remains intact during preparation.
 
+**Completion:** Implemented and verified with focused declaration/parser and
+import-spec tests plus `./scripts/check.sh`.
+
 ## Stage 4 — Reconcile Declarations And Select Collection Operations
 
 Scope: pure agreement and operation-selection helpers, independent of loading
@@ -251,6 +260,9 @@ and of the ownership transformations introduced next.
 Validation: focused policy-agreement/selection tests and the everyday check.
 Do not activate collection combination or implement the ownership layer here.
 
+**Completion:** Implemented and verified with focused collection-policy tests and
+`./scripts/check.sh`.
+
 ## Stage 5 — Track Policy Lifetime And Record Ownership
 
 Scope: private scoped-state transformations built on Stage 4's resolution helpers.
@@ -275,6 +287,9 @@ Scope: private scoped-state transformations built on Stage 4's resolution helper
 Validation: focused collection-policy tests and the everyday check. This stage
 must not add path-existence, shape, nullability, or global YAML final-check rules.
 
+**Completion:** Implemented and verified with focused collection-policy tests,
+`go test -race ./internal/engine`, and `./scripts/check.sh`.
+
 ## Stage 6 — Implement The Shared Sequence Operations
 
 Scope: a pure document-level combination helper, not separate implementations
@@ -297,6 +312,9 @@ for overlays and inheritance.
 Validation: focused combination tests and the everyday check. Do not change the
 ordinary recursive mapping rule or add unkeyed append.
 
+**Completion:** Implemented and verified with focused sequence-combination tests
+and `./scripts/check.sh`.
+
 ## Stage 7 — Extend Sequence History Representation And Replay
 
 Scope: represent and replay sequence operations without yet changing all metadata
@@ -319,6 +337,9 @@ projection consumers or public precedence.
 Validation: sequence/history/replay tests and the everyday check. Keep current
 append/replace callers working through the extended descriptors.
 
+**Completion:** Implemented and verified with focused sequence-history tests and
+`./scripts/check.sh`.
+
 ## Stage 8 — Project Sequence Origins And Inspection Evidence
 
 Scope: use the prepared item mappings consistently in metadata consumers.
@@ -338,6 +359,10 @@ Scope: use the prepared item mappings consistently in metadata consumers.
 Validation: metadata/history/sequence/provenance/sensitivity tests,
 `go test -race ./internal/engine`, and the everyday check.
 
+**Completion:** Implemented and verified with focused projection, history,
+sequence, provenance, and sensitivity tests, `go test -race ./internal/engine`,
+and `./scripts/check.sh`.
+
 ## Stage 9 — Separate Per-Input Acquisition From Composition
 
 Scope: a behavior-preserving acquired-input handoff; grouped underlay coordination
@@ -362,6 +387,10 @@ is the next stage.
 Validation: the focused suites above and the everyday check. This refactor must
 not change source IDs or turn acquisition order into precedence order.
 
+**Completion:** Implemented and verified with focused acquisition, scheduling,
+placement, source-version, layered-equivalence, resource-lifetime, and context
+tests plus `./scripts/check.sh`.
+
 ## Stage 10 — Separate Underlay-Group Acquisition From Composition
 
 Scope: behavior-preserving group coordination in `load_request.go`, using the
@@ -384,6 +413,10 @@ per-input handoff already prepared in Stage 9.
 Validation: grouped/layered, import scheduling, version, destination, and
 resource-context tests plus the everyday check.
 
+**Completion:** Implemented and verified with focused grouped/layered,
+import-scheduling, version, destination, and resource-context tests plus
+`./scripts/check.sh`.
+
 ## Stage 11 — Compose Strict Collections With Resolved Identity
 
 Scope: the policy-aware strict composition core. Nested pending-item scope
@@ -407,6 +440,9 @@ Validation: composition and sequence identity tests plus the everyday check.
 Keep unregistered non-mapping conflicts unchanged. Public load activation remains
 in the later integration stages.
 
+**Completion:** Implemented and verified with focused composition, collection
+policy, and sequence identity tests plus `./scripts/check.sh`.
+
 ## Stage 12 — Integrate Policy-Aware Item And Helper Scopes
 
 Scope: adapt pending-item/helper composition to Stage 11's core using the acquired
@@ -430,6 +466,10 @@ scope boundaries from Stages 9–10.
 Validation: item/destination/import/composition/source-version tests and the
 everyday check. Keep current public behavior until load-path activation.
 
+**Completion:** Implemented and verified with focused item-scope, destination,
+import, composition, collection-policy, and source-version tests plus
+`./scripts/check.sh`.
+
 ## Stage 13 — Activate Ordinary Source Collection Declarations
 
 Scope: ordinary `Load` base-source assembly, excluding activation of the new
@@ -453,6 +493,10 @@ selected-overlay policy surface until Stage 14.
 Validation: ordinary-load, import, composition, and metadata tests plus
 the everyday check. Include one public ordinary-load declaration example test.
 
+**Completion:** Implemented and verified with ordinary-load, import, composition,
+metadata, sequence-item, and source-version tests, the public ordinary-load
+example, and `./scripts/check.sh`.
+
 ## Stage 14 — Activate Selected Overlay Collection Policies
 
 Scope: ordinary loading's selected overlay and shared precedence integration,
@@ -475,6 +519,10 @@ using the source/declaration handoff already active in Stage 13.
 Validation: ordinary-load, overlay, composition, policy, and metadata tests plus
 the everyday check.
 
+**Completion:** Implemented and verified with ordinary overlay-operation,
+sequence-policy, source-version, and metadata tests. Validation commands:
+`go test ./internal/engine -count=1` and `./scripts/check.sh`.
+
 ## Stage 15 — Integrate Lower Policy Across Layered Assembly
 
 Scope: source-backed underlay coordination and the layered selected-overlay path,
@@ -508,6 +556,12 @@ Do not absorb unfinished work from Stages 5–14 into this stage.
 Validation: layered/grouped, source-version, dependency scheduling, destination,
 and metadata tests plus the everyday check.
 
+**Completion:** Implemented lower collection-policy propagation across underlay
+groups, main composition, and layered overlays. Verified policy-only lower
+tiers, inherited identity and explicit mode, explicit replacement, source
+version behavior, sequence history, and consumer examples. Validation:
+`go test ./internal/engine -count=1` and `./scripts/check.sh`.
+
 ## Stage 16 — Verify Replacement And Nested Policy Ownership End To End
 
 Scope: the consequential lifetime cases across the now-active source assembly.
@@ -532,6 +586,12 @@ Scope: the consequential lifetime cases across the now-active source assembly.
 Validation: focused policy/sequence/layered/ownership tests,
 `go test -race ./internal/engine`, and the everyday check.
 
+**Completion:** Updated layered precedence to transfer incoming item-owned
+collection policies through sequence identity projections. Verified retained,
+upserted, and replaced records, ancestor retirement and reintroduction, renewed
+identity, and append-mode ownership. Validation: `go test -race ./internal/engine`
+and `./scripts/check.sh`.
+
 ## Stage 17 — Prepare Inheritance Policy And Template Transport
 
 Scope: behavior-preserving inheritance state transport, before activating
@@ -553,6 +613,11 @@ collection-aware inheritance operations in Stage 18.
 Validation: existing inheritance, ownership, history, and resource-context tests,
 focused transport tests, and the everyday check.
 
+**Completion:** Implemented detached collection-policy transport through
+inheritance templates and expansion operations while preserving current values
+and nested instructions. Verified focused inheritance/history/resource tests,
+`go test -race ./internal/engine`, and `./scripts/check.sh`.
+
 ## Stage 18 — Apply Collection Policy During Mapping-Sibling Inheritance
 
 Scope: activate shared collection operations using the prepared template/state
@@ -576,6 +641,12 @@ handoff; existing mapping-sibling relationship selection remains unchanged.
 Validation: inheritance, history, provenance, sensitivity, and resource-context
 tests plus the everyday check. No identified-record parent lookup is active yet.
 
+**Completion:** Activated collection-aware sequence operations at mapping-sibling
+inheritance destinations, including identity transfer, destination-local modes,
+record-owned policy projection, and application registrations. Verified focused
+inheritance and sequence tests, `go test -race ./internal/engine`, and
+`./scripts/check.sh`.
+
 ## Stage 19 — Build Identified-Record Inheritance Graphs
 
 Scope: relationship extraction/validation and shared scheduling for sequence
@@ -603,6 +674,11 @@ scopes; test these helpers before activating payload expansion.
 
 Validation: focused inheritance graph/reference tests and the everyday check.
 
+**Completion:** Added private identified-sequence graph validation and stable
+dependency scheduling for complete scalar identity references, without changing
+the active mapping-sibling expansion path. Verified focused graph/reference tests
+and `./scripts/check.sh`.
+
 ## Stage 20 — Prepare Reusable Inheritance Scope Execution
 
 Scope: remove mapping-container assumptions from the private template executor
@@ -626,6 +702,10 @@ Validation: inheritance execution, scheduling, history, and budget tests plus
 the everyday check. This refactor does not introduce new parent-reference forms
 or change public loading semantics yet.
 
+**Completion:** Implemented reusable mapping and identified-sequence scope
+execution with focused inheritance/scheduling/history/budget tests,
+`go test -race ./internal/engine`, and `./scripts/check.sh`.
+
 ## Stage 21 — Resolve Record Inheritance With Ownership And Evidence
 
 Scope: integrate Stage 19's graphs and Stage 20's executor into the structural
@@ -652,6 +732,11 @@ expansion phase, with values and inspection working together.
 Validation: all inheritance and cross-feature inspection tests,
 `go test -race ./internal/engine`, and the everyday check.
 
+**Completion:** Activated identified-record inheritance after tier assembly,
+including nested collection relationships, ownership and inspection evidence.
+Verified inheritance/inspection regressions, `go test -race ./internal/engine`,
+and `./scripts/check.sh`.
+
 ## Stage 22 — Expose The Root-Owned Registration API
 
 Scope: the settled facade surface and migration of in-repository callers.
@@ -675,6 +760,11 @@ Scope: the settled facade surface and migration of in-repository callers.
 Validation: root sequence/facade, registration, public/dependency-boundary, and
 consumer example tests plus the everyday check.
 
+**Completion:** Exposed the root-owned exact and dynamic sequence identity
+registration API, migrated maintained callers, and removed the old single-field
+registration adapters. Verified facade, registration, inheritance,
+public/dependency-boundary, and consumer example tests plus `./scripts/check.sh`.
+
 ## Stage 23 — Separate Reusable CLI Override Preparation
 
 Scope: mechanical preparation refactor and a privately tested post-structural
@@ -696,6 +786,11 @@ validation entry, without changing current CLI processing order.
 Validation: override preparation/source tests and the everyday check. Keep
 ordinary/layered behavior unchanged; typed assignment is the next stage.
 
+**Completion:** Extracted detached override preparation batches with stable
+synthetic source ordering and added a privately exercised post-structural
+directive check for `extends`. Existing early override behavior remains active.
+Verified focused override tests and `./scripts/check.sh`.
+
 ## Stage 24 — Implement Schema-Aware Post-Decode CLI Assignment
 
 Scope: a private typed assignment helper using Stage 23's prepared overrides,
@@ -719,6 +814,11 @@ Validation: override, decode, schema, projection, and ownership tests plus the
 everyday check. Only the helper is added here; the shared lifecycle does not
 switch until its inspection/context support is prepared in Stage 25.
 
+**Completion:** Added private schema-aware post-decode CLI assignment with
+detached typed results, canonical projection, updated presence/origins, and
+preserved pre-CLI/raw override snapshots. Verified focused override, decode,
+schema, projection, and ownership tests plus `./scripts/check.sh`.
+
 ## Stage 25 — Prepare Post-Decode CLI Inspection And Effective Context
 
 Scope: prepare history, resolution-input, and secret-lookup context handling;
@@ -743,6 +843,12 @@ retain the existing public CLI lifecycle until Stage 26.
 Validation: history/metadata/resolution/secret tests and the everyday check.
 Public activation must not require a later stage to repair these mechanisms.
 
+**Completion:** Prepared detached post-decode inspection, resolution metadata,
+and effective secret-reference/location handoffs using existing history
+machinery. Verified the private target pipeline and unchanged public-load
+regressions with focused history/metadata/resolution/secret tests and
+`./scripts/check.sh`.
+
 ## Stage 26 — Activate CLI After Decoding In The Shared Lifecycle
 
 Scope: activate ADR 0018 through both loading paths using Stages 23–25's complete
@@ -772,6 +878,13 @@ assignment, inspection, and effective-value handoffs.
 Validation: override/lifecycle/resolution/inheritance/history/secret tests,
 `go test -race ./...`, and the everyday check.
 
+**Completion:** Activated typed CLI assignment after structural expansion and
+decoding in the shared load lifecycle, including resolution, history, and
+effective secret-reference context. Removed early application and replay fallback
+paths, updated contracts and examples, and revised obsolete relationship-change
+expectations. Verified focused lifecycle and secret tests, `go test -race ./...`,
+and `./scripts/check.sh`.
+
 ## Stage 27 — Enforce Final Application Identity Constraints
 
 Scope: the final-result guarantee, not another combination or inheritance phase.
@@ -800,6 +913,15 @@ Scope: the final-result guarantee, not another combination or inheritance phase.
 Validation: final identity, selector, facade, defaults/resolution/override, and
 secret tests plus the everyday check.
 
+**Completion:** Added shared final identity validation to the ordinary and layered
+load lifecycle after effective secret lookup and before application validation.
+It traverses the final typed projection with compiled selectors and reports
+concrete paths and available locations without exposing identity or credential
+values. Added facade and lifecycle coverage for late defaults, CLI, resolution,
+dynamic namespaces, typed numeric equality, ignored unmatched shapes, and nil
+results on failure. Updated registration comments and the configuration contract.
+Verified focused facade and engine tests plus `./scripts/check.sh`.
+
 ## Stage 28 — Exercise Representative Consumer Workflows
 
 Scope: a small number of meaningful integrations, not a Cartesian test matrix.
@@ -826,6 +948,23 @@ Scope: a small number of meaningful integrations, not a Cartesian test matrix.
 Validation: `go test ./examples/consumers`, focused root integration tests,
 `go test -race ./...`, and the everyday check.
 
+**Completion:** Added an executable source-backed catalog that combines an
+underlay identity declaration, imported main fragments, identified record
+inheritance, all three selected overlay operations, typed CLI assignment, and
+recorded application resolution. Its checks demonstrate stable operation order,
+complete matched-record replacement, final metadata and history inspection,
+inherited resource lookup through source context, and secret-safe explanation.
+Added a typed-map example with exact and wildcard registrations, independent
+uniqueness across concrete collections, and a YAML-only identity example that
+shows the absence of final application enforcement without registration. Audited
+the existing helper-composed parent reference, source-version control consumption,
+pending declarations, lower-tier identity before peer composition, and policy
+replacement ownership coverage; added a consumer regression for a dynamic
+collection destination introduced by inheritance. Verified
+`go test ./examples/consumers -count=1`,
+`go test . -run 'Facade.*(Inheritance|Sequence|Override)' -count=1`,
+`go test -race ./...`, and `./scripts/check.sh`.
+
 ## Stage 29 — Reconcile Documentation
 
 Scope: finish the current-contract narrative. Code cleanup belongs with the
@@ -854,6 +993,15 @@ Validation: local documentation-link checks and whitespace review; run relevant
 example tests if executable examples changed. Reuse Stage 28's successful
 code/race validation when its covered content is unchanged.
 
+**Completion:** Reconciled the configuration contract for identity equality,
+selectors, declarations, operation selection and presence, ownership,
+inheritance, final registered-identity validation, and post-decode CLI ordering.
+Updated consumer, root, internal, development, and architecture guidance; removed
+implemented behavior from the deferred feature list while retaining recursive
+body merging as future work. Updated ADR implementation references and preserved
+intentional historical references. Verified maintained prose/example searches,
+`go test . -run '^TestLocalDocumentationLinks$' -count=1`, and `git diff --check`.
+
 ## Stage 30 — Audit Scaling And Verify The Completed Target
 
 Scope: a bounded implementation review and final validation, not another broad
@@ -883,6 +1031,37 @@ from Stages 28–29 if their covered content is unchanged. Record completed scop
 validation, benchmark commands/qualitative findings, and any real remaining
 issues accurately. No new timing thresholds or release gates are introduced.
 
+**Completion:** Audited the shared indexed sequence-combination and identity
+validation paths, declaration gathering, numeric normalization, ownership and
+selector-path handling, adapters, dependencies, boundaries, and limits. Removed
+per-declaration temporary-slice allocation while retaining detached declaration
+ownership. Added a mixed-size identified-sequence upsert benchmark because the
+existing assembly benchmarks did not exercise this path. Its allocations grew
+roughly in proportion to record count from 128 to 2,048 records; elapsed times
+were similarly proportional in this short run and are descriptive only.
+
+Benchmark command:
+
+```sh
+go test ./internal/engine -run '^$' -bench '^(BenchmarkComposeWideMappings|BenchmarkUnderlay(BroadCatalog|ManySmallTiers)|BenchmarkOverlay(RecursiveMappings|ManyApplications)|BenchmarkInheritance(Expansion|IndependentScopes)|BenchmarkSequenceMixedUpsert)$' -benchmem -benchtime=100ms
+```
+
+The benchmark reported mixed-upsert results of 278,009 B and 2,337 allocations
+per operation at 128 records; 1,122,177 B and 9,253 allocations at 512; and
+4,521,839 B and 36,925 allocations at 2,048. No thresholds are implied. The
+code review found shared combination and identity algorithms, indexed matching
+and mapping access, declaration grouping by destination, coefficient/exponent
+numeric normalization without magnitude expansion, operation-local ownership
+and selector traversal, no remaining early-CLI adapter, and no newly introduced
+dependencies, public internal types, background work, release machinery, or
+sequence-specific resource limits. Obsolete registration names remain only in
+historical or roadmap text.
+
+Verified with `./scripts/check.sh`, `go test -race ./...`,
+`go test . -run 'TestLocalDocumentationLinks|TestDependencyImportBoundary|TestPublicFacadeBoundary' -count=1`,
+`git diff --check`, and the benchmark command above. No remaining implementation
+issues were found.
+
 Acceptance: all roadmap operations and lifecycle boundaries work through ordinary
 and layered loads; values and inspection agree; application constraints hold on
 successful final results; deferred behavior and YAML-only guarantees have not

docs/roadmap/remediation.md

@@ -0,0 +1,905 @@
+# Sequence Implementation Review Remediation
+
+Status: findings 1–17 are complete. The algorithm audit below identifies six
+additional open findings, numbered 18–23. This record introduces no new release
+gate.
+
+Reviewed commit: `0be7cdb00eff576fda6b30c0600b2134d4e2e086`.
+Implementation range: `bc6b977..0be7cdb`.
+Authority: the [sequence roadmap](sequences.md),
+[implementation plan](implementation.md),
+[ADR 0017](../adr/0017-collection-sequence-policy.md), and
+[ADR 0018](../adr/0018-cli-after-structural-resolution.md).
+
+The public facade, shared identity/composition machinery, scoped policies,
+identified-record inheritance, post-decode CLI phase, and final registered
+identity validation are present. The findings below concern remaining
+correctness, contract-alignment, documentation, and scaling gaps.
+
+Validation on the reviewed commit:
+
+- `./scripts/check.sh` passed with Go 1.26.10 on Linux.
+- `go test -race ./...` passed.
+- Public-API probes outside the repository reproduced findings 1–9. The probes
+  used labeled byte sources, defaults, and an in-memory filesystem; they did not
+  change implementation files or use external services.
+- Finding 10 follows directly from the maintained text; finding 11 follows from
+  the prefix-scan loop, not a timing comparison or performance threshold.
+
+Validation after the initial remediation: `./scripts/check.sh` and
+`go test -race ./...` passed with Go 1.26.10 on Linux. The original public-API
+probes for findings 1–9 now demonstrate the required corrected behavior.
+
+Validation after integration remediation: the everyday check, full race suite,
+and local documentation/public-boundary checks passed with the same toolchain.
+The original and follow-up public-API probes demonstrate corrected behavior for
+findings 1–9 and 12–15, including unrelated underlay payload at an old version
+index. The accumulated-copy correction is verified by code inspection and
+ownership regressions; the contract corrections are verified against the
+implemented operations and replay. Each additional finding has its own completion
+record and commit.
+
+P1 denotes the highest-priority correctness issue here; P2 denotes normal-priority
+work needed to complete the selected behavior. Preserve the agreed scope while
+fixing these issues. In particular, do not resolve failures by restricting valid
+identity fields, requiring repeated declarations, changing merge semantics, or
+adding limits.
+
+## 1. Preserve Retained Explicit Values In Nested CLI Mapping Assignments — P1
+
+Status: [x] Complete.
+
+Completion: override metadata now reads the actual target subtree through one
+shared lookup. Ordinary/layered regressions preserve retained values, including
+zero and false, their explicit origins, and absence-based resolver behavior.
+Verified `go test ./internal/engine -run 'Override|CLI' -count=1` and
+`./scripts/check.sh`.
+
+Owner: [`applyDecodedOverrides`](../../internal/engine/override_decode.go),
+especially lines 59–60 and the presence/origin update helpers.
+
+The helpers receive the complete configuration projection as `existing`, but
+interpret it as the subtree at the override path. A partial nested mapping
+therefore treats retained input children as absent and drops their presence and
+origins. `fillDefaultOrigins` subsequently labels those retained values as defaults.
+
+Reproduction: load the following into ordinary nested Go structs:
+
+```yaml
+settings:
+  nested:
+    a: 1
+    b: 2
+```
+
+Apply an override at `[settings]` with value
+`map[string]any{"nested": map[string]any{"a": 3}}`. The typed value of `b`
+initially remains 2, but `Metadata.Lookup([settings,nested,b])` reports
+`Explicit: false` and a default origin. Calling `Default` for that field in
+application resolution then changes the explicitly supplied 2 to the fallback
+value. This violates presence-based defaulting, not merely presentation.
+
+Required remediation: use the actual existing target subtree when updating
+presence/origins, preserving retained descendants and removing genuinely replaced
+ones. Keep override batches detached and preserve the selected post-decode order.
+Add regressions for nested partial mappings, retained zero/false values, metadata,
+and an absence-based resolver default that must not overwrite retained input.
+
+## 2. Read Upsert Origins At Input Paths And Write Them At Output Paths — P2
+
+Status: [x] Complete.
+
+Completion: sequence origin copying now separates incoming and effective paths
+for precedence and inheritance. A regression covers reordered matches, appended
+records, composite origins, and actual resource reads from distinct declaring
+directories. Verified focused origin/inheritance/overlay/provenance tests,
+`go test -race ./internal/engine`, and `./scripts/check.sh`.
+
+Owners: [`applyOverlaySequenceEvidence`](../../internal/engine/overlay.go),
+particularly lines 369 and 381, and the analogous sequence-origin copying in
+[`inheritance_collection.go`](../../internal/engine/inheritance_collection.go).
+
+The overlay helper supplies an output-index path to an origin lookup whose keys
+are still incoming-index paths. When those positions differ and another incoming
+record occupies the output index, metadata takes that other record's source
+location. The same defect was reproduced through mapping-sibling inheritance;
+its helper uses the same single-path copying pattern.
+
+Reproduction: an underlay supplies IDs `[a,b]`; the main source declares `key: id`
+and supplies `[b*,a*]`. The result is correctly `[a*,b*]`, but the value origin
+for final `a*` is the source line of `b*`, and vice versa. In the probe the two
+value lines were 7 and 9; final index 0 incorrectly reported line 7 instead of 9.
+With separately authored records this can select a different source/context.
+
+Required remediation: use the operation's input-to-output projection for origin
+subtree reads as well as writes. Preserve composite contributing origins, not
+just node-location fallbacks. Test reordered upserts and appended records with
+distinct source files/locations, including nested fields, inheritance operations,
+and declaring resource contexts.
+
+## 3. Apply Tier Sequence Operations To Historical Contributions — P2
+
+Status: [x] Complete.
+
+Completion: per-source history now composes strict item projections with the
+tier operation, including nested application prefixes and local sequence replay.
+Regressions cover all three operations, multiple peers, retained records, removed
+fields, source attribution, and a subsequent overlay without a false decoding
+event. Verified focused history tests, `go test -race ./internal/engine`, and
+`./scripts/check.sh`.
+
+Owner: [`applyOverlayWithCollectionPolicy`](../../internal/engine/overlay.go),
+lines 76–84, and existing sequence-history projection/replay.
+
+For composed tiers, `applications` is nonempty. This branch appends the tier's
+original strict-composition applications without incorporating the newly computed
+precedence sequence descriptors. Replay consequently performs a whole-list
+replacement or strict append rather than the actual cross-tier upsert/append.
+The later decoding reconciliation conceals the mismatch by attributing a
+structural combination to typed defaults/decoding.
+
+Reproduction: lower `[a,b]` and higher `[b*,a*]` correctly yield `[a*,b*]`.
+`Explain([items])` instead shows the main contribution producing `[b*,a*]`, then
+a `decoding` event reordering it to `[a*,b*]` with the reason "applied retained
+defaults and canonical typed decoding". No decoder performed that reordering.
+
+Required remediation: project each retained per-source application through the
+tier's selected operation while keeping peer composition distinct from tier
+precedence. Do not collapse authored sources or fake decoding events. Cover
+upsert, append, unmatched retained records, reordered matches, removed fields,
+multiple higher-tier peers, and a subsequent selected overlay. Replay should
+agree with structural assembly before real decoding reconciliation.
+
+## 4. Reproject Nested Source Destinations After Cross-Tier Item Movement — P2
+
+Status: [x] Complete.
+
+Completion: layered assembly projects incoming source destinations and version
+classification evidence with the same item assignments used for values/history.
+Earlier contributions retain their historical coordinates, physical identities
+and contexts. Main/underlay regressions cover reordered upserts, append, replace,
+nested helpers, and source-local version evidence. Verified focused destination,
+origin and source-version tests, focused race coverage, and `./scripts/check.sh`.
+
+Owners: [`projectAcquiredDestinations`](../../internal/engine/imports.go) and the
+sequence-operation handoff in [`assembleLayeredInput`](../../internal/engine/load_request.go).
+
+Source destinations are projected while composing their own tier, but are not
+reprojected when that tier's records move to accumulated-list positions. Nested
+helper source records can therefore point at a different final record.
+
+Reproduction: lower `items` contains `[a,b]`. Main imports a single `b` record
+with `placement: sequence-item` into `[items]`; that record imports a helper
+mapping supplying its value. Upsert retains `a` at index 0 and places the higher
+`b` at index 1. `Sources()` nevertheless reports the surviving helper's destination
+as `/items/0`, its tier-local position, rather than `/items/1`.
+
+Required remediation: carry the sequence operation's projection through nested
+source-destination/evidence updates at precedence boundaries. Keep physical
+source identity and passive resource contexts unchanged, and preserve historical
+meaning for displaced contributions rather than relabeling them as survivors.
+Test a retained lower record followed by an imported higher record, reordered
+matches, and nested helpers. Check version-evidence projection where applicable.
+
+## 5. Honor Identity Reset On Actual Inheritance Replacement — P2
+
+Status: [x] Complete.
+
+Completion: inheritance resolves identity against actual child-value presence,
+discarding parent YAML identity for an explicit replacement while preserving
+agreement for retained values and authoritative application constraints. Added
+policy-state and public-load regressions for changed/unkeyed/non-sequence
+replacements, application agreement/conflict, and mode-only/append/upsert cases.
+Verified focused inheritance tests and `./scripts/check.sh`.
+
+Owners: [`inheritanceCollectionResolution` and `mergeInheritanceCollectionPolicies`](../../internal/engine/inheritance_collection.go),
+especially lines 79–80 and 121.
+
+These paths reconcile the parent's YAML identity before accounting for actual
+replacement, and treat the parent's collection as retained even when the child
+supplies a replacing value. This is stronger than the selected identity lifetime
+and differs from source-tier replacement.
+
+Reproduction:
+
+```yaml
+configkit:
+  sequences:
+    - destination: [base, items]
+      key: id
+    - destination: [child, items]
+      key: name
+      mode: replace
+base:
+  items:
+    - id: a
+      value: parent
+child:
+  extends: base
+  items:
+    - name: b
+      value: child
+```
+
+Loading fails with `sequence.conflict` at `/child/items`. It should succeed:
+actual whole-sequence replacement may discard the parent's YAML identity and
+establish `name`. Authoritative application constraints must still apply.
+
+Required remediation: distinguish actual replacement from a mode-only declaration
+before identity agreement and transfer. Test a changed key, replacement with no
+new key becoming unkeyed, permitted non-sequence replacement, and an agreeing or
+conflicting application registration. Preserve rejection of identity changes
+without a replacement value and during append/upsert.
+
+## 6. Enforce Collection Operations Beneath Newly Added Ancestors — P2
+
+Status: [x] Complete.
+
+Completion: copying a mapping now visits nested collection operations with absent
+lower values, preserving ordinary ancestor removal and whole-record semantics.
+Incoming record-owned policy transfers through the same operation. Regressions
+cover absent/empty/null ancestors, identity and kind failures, empty and valid
+initialization, and later inheritance using an imported item's nested identity.
+Corrected an older test that deferred the required error until a later tier.
+Verified focused merge/collection/inheritance tests, focused ownership race
+coverage, and `./scripts/check.sh`.
+
+Owners: [`mergeRecursiveMappings`](../../internal/engine/recursive_merge.go) and
+[`mergeOverlayMappingsWithCollectionPolicy`](../../internal/engine/overlay.go).
+
+When an incoming ancestor mapping is absent below, the recursive merger clones
+the entire subtree and invokes only its ancestor-level added hook. Nested
+collection resolutions are not visited. This bypasses their operation rules;
+the subsequent declaration-only policy update does not replace those checks.
+
+Reproduction: combine a lower `{}` with this main tier:
+
+```yaml
+configkit:
+  sequences:
+    - destination: [group, items]
+      mode: append
+group:
+  items:
+    - id: a
+```
+
+Loading succeeds despite append having no identity definition. Placing the same
+sequence directly at `[items]` correctly fails. The validity of an operation
+must not depend on whether an enclosing mapping already existed.
+
+Required remediation: account for applicable nested collection policies when
+adding/copying an ancestor subtree, including owned-policy transfer. Test absent
+and present enclosing mappings, append/upsert without identity, explicit empty
+lists, invalid non-sequence contributions, and valid identified initialization.
+Do not turn this into a general path-existence or shape constraint: ordinary
+ancestor replacement/removal retains its documented meaning.
+
+## 7. Validate Final Typed Identity Fields As Payload, Not Directives — P2
+
+Status: [x] Complete.
+
+Completion: shared identity lookup now distinguishes structural records from
+effective payload/reference mappings. Final validation includes literal `extends`
+fields while structural source checks still exclude actual directives. Facade
+regressions cover defaults and recorded resolution, string/null components, and
+duplicate rejection. Verified those regressions and existing structural identity
+and inheritance coverage through `./scripts/check.sh`.
+
+Owners: [`validateFinalSequenceIdentities`](../../internal/engine/final_identity.go)
+and [`newSequenceMappingIndex`](../../internal/engine/sequence_identity.go).
+
+The final validator reuses structural record lookup, which excludes every
+`extends` entry. At this phase there is no structural processing: typed defaults
+and application resolution can produce ordinary payload with that literal name.
+The roadmap expressly distinguishes structural-control exclusion from final
+typed-payload validation; this reuse introduces an extra restriction.
+
+Reproduction: a defaults-only `Catalog` with `Items []map[string]any` containing
+`{"extends": "application-data"}`, registered with
+`SequenceIdentityAt(Keys("items"), "extends")`, fails with a missing identity
+field at `/items/0/extends`, even though the effective field is present.
+
+Required remediation: distinguish structural-payload lookup from final payload
+lookup. Preserve rejection when a source tries to use an actual consumed
+directive as identity. Test final fields supplied by defaults and recorded
+resolution, including a null component, without adding a broader name ban.
+
+## 8. Retain Nonfatal Main-Version Diagnostics In Layered Loads — P2
+
+Status: [x] Complete.
+
+Completion: layered assembly returns nonfatal main-version diagnostics on success
+and alongside later failures; the shared caller stops only for errors. Regression
+coverage verifies ordinary/layered warning parity, exactly one checker call, and
+warnings retained with later structural or decoding errors. Verified through
+`./scripts/check.sh`, including existing source-version ordering coverage.
+
+Owner: [`assembleLayeredInput`](../../internal/engine/load_request.go), lines 143–152.
+
+The moved default-mode version-check call returns its diagnostics only when they
+contain errors. Warning-only diagnostics are discarded. Ordinary loading still
+retains the same warnings.
+
+Reproduction: a `VersionRule.Check` that calls
+`validation.Warning(Keys("version"), "test warning")` and returns nil yields one
+`version.warning` through ordinary `Load`, but zero diagnostics through
+`LoadLayered` with the same main input and default source-version mode.
+
+Required remediation: carry warnings from the single main-tier check into the
+shared diagnostic accumulator on successful layered loads. Preserve checker
+ownership, invocation count, and the selected acquisition/composition ordering.
+Add ordinary/layered parity and warning-plus-later-error regressions.
+
+## 9. Identify Conflicting Application Registrations In Diagnostics — P2
+
+Status: [x] Complete.
+
+Completion: definition validation retains original one-based registration
+positions and names both positions in each overlap diagnostic. No input path or
+new public diagnostic structure is invented. A mixed-selector regression verifies
+multiple conflicts even after an earlier invalid registration is skipped.
+Verified registration/facade coverage through `./scripts/check.sh`.
+
+Owner: [`compileSequenceIdentityPolicy`](../../internal/engine/sequence_registration.go),
+lines 119–128.
+
+Incompatible dynamic overlaps produce only a generic `options.invalid` message,
+an empty configuration path, and no related information. Neither registration
+is identified. The roadmap requires definition-time errors to identify the
+conflicting registrations without inventing a concrete input destination.
+
+Reproduction: register `collections -> AnyMappingKey -> items` using `id`, and
+`collections -> foo -> items` using `name`. Even with `NoSource`, the error is
+only "overlapping sequence registrations must use the same identity fields".
+With multiple registrations the caller cannot identify the conflicting pair.
+
+Required remediation: retain original registration positions and identify both
+in safe definition diagnostics, for example through positional message context.
+No new public diagnostic structure is required solely for this. Test mixed exact
+and dynamic registrations and multiple conflicts, without asserting complete
+English wording or exposing identity values.
+
+## 10. Remove Stale Public Contract Descriptions — P2
+
+Status: [x] Complete.
+
+Completion: the public definition comment now describes final registered-identity
+validation and its shape/lifetime boundaries. Selected-overlay prose explicitly
+separates ordinary replacement from collection policy and links to the canonical
+operation/presence tables. Verified against the implementation, local-link tests,
+and `git diff --check`; no runtime behavior changed.
+
+Owners: [`Definition.SequenceIdentities`](../../lifecycle.go), lines 18–21, and
+the [selected-overlay contract](../config.md#selected-overlays).
+
+The exported definition-field comment still says registrations do not validate
+identities introduced by defaults, CLI, or callbacks. Final validation is now
+implemented and the registration constructors correctly document it.
+
+The selected-overlay table and following paragraph also still unconditionally
+describe sequences as atomic replacements and `[]` as clearing. A later paragraph
+describes collection operations, but does not make the earlier unconditional
+claims accurate: identified collections infer upsert, and `[]` then contributes
+no records rather than clearing.
+
+Required remediation: make the symbol comment describe its implemented final
+guarantee and boundaries, and qualify the overlay table/paragraph for collection
+policy. Link to the canonical collection tables rather than duplicating them.
+Keep YAML-only enforcement distinct from registered final validation.
+
+## 11. Remove The Quadratic Prefix Scan In Item Policy Projection — P2
+
+Status: [x] Complete.
+
+Completion: assigned sequence ranges now supply item offsets directly. Handoffs
+without a range lazily accumulate prefix lengths, visiting each preceding
+contribution once rather than rescanning every prefix. Regression coverage keeps
+inline and policy-less contributions in the correct positions with complete,
+partial, or absent ranges. Existing ownership/placement tests remain intact.
+Verified focused item-policy tests, `./scripts/check.sh`, `go test -race ./...`,
+and inspection of the remaining error-only prefix-scan callers. No new benchmark
+fixture or performance threshold was needed for this bounded change.
+
+Owner: [`projectNestedCollectionPolicies`](../../internal/engine/imports.go),
+especially line 968; the scanned helper is `priorSequenceLength` in the same file.
+
+For every item with local collection policy, the loop scans all preceding
+contributions to calculate `itemIndex`, then overwrites that result when the
+already-indexed sequence range is available. For N such items this performs
+`0 + 1 + ... + (N-1)` contribution visits, excluding path lookup costs, despite
+the common case already having the exact assigned index. This is introduced
+quadratic work in the feature's independently authored-record path.
+
+Required remediation: use the existing assigned range first. If a genuine
+fallback is necessary, maintain per-destination prefix lengths in one pass
+rather than rescanning every prefix. Preserve scope and ordering semantics;
+do not add limits, pooling, or a new public cache. Keep ownership/placement
+regressions and add a representative many-item/local-policy benchmark only if
+needed to exercise the path. A wall-clock threshold is not required.
+
+## Integration Audit Baseline And Scope
+
+Reviewed commit: `8d40983271de5239312eb0a2896737be88c5abdc`.
+
+This follow-up reviews the interaction of collection policy, identified-record
+inheritance, dynamic registrations, and post-decode CLI assignment with existing
+source placement, source-version checking, typed decoding, inspection, resource
+contexts, and ownership boundaries. The accepted ADRs and current configuration
+contract remain the authority; the findings require integration corrections,
+not additional consumer restrictions or new feature choices.
+
+Validation:
+
+- `./scripts/check.sh` and `go test -race ./...` pass with Go 1.26.10 on Linux.
+- Isolated public-API probes outside the repository reproduce findings 12–15.
+  They use labeled byte sources and an in-memory filesystem, with no external
+  services, real credentials, or repository implementation changes.
+- Finding 16 follows from the per-item deep-copy loop; no timing claim or
+  performance threshold is needed. Finding 17 follows from maintained contract
+  text that contradicts the implemented collection operations.
+- Positive comparisons include sequence-valued identity replacement, ancestor
+  retirement through source tiers, quoted versions after item movement, and an
+  append overlay that preserves the main record's version.
+
+## 12. Complete Identity Retirement Across Replacement Shapes — P2
+
+Status: [x] Complete.
+
+Completion: source composition and inheritance now prepare eligible lower policy
+from actual replacement paths before agreement. Removed identity and record state
+cannot constrain a new pending key or reappear in later inheritance. Shared mode
+selection preserves explicit-mode persistence and authoritative registrations.
+Regressions cover null/scalar/mapping/list replacement, ancestor removal with a
+new key, reintroduction, and retained/application-constrained conflicts. Verified
+focused retirement/inheritance tests, engine ownership race coverage, and
+`./scripts/check.sh`.
+
+Owners: [`resolveStrictCollectionPolicies`](../../internal/engine/compose.go),
+especially its `sequencePresent` reset condition;
+[`mergeInheritanceCollectionPolicies`](../../internal/engine/inheritance_collection.go);
+and ancestor-replacement handling in
+[`applyInheritanceScopeTemplates`](../../internal/engine/inheritance_schedule.go).
+
+Policy agreement and retirement still treat some actual replacements as retained
+collections. This has three observable effects under the same selected lifetime
+rule:
+
+1. Source precedence accepts a replacement sequence with a new YAML key, but
+   rejects the equivalent replacement by null or a scalar. For example, a lower
+   tier declaring `key: id` for `[items]` with `items: [{id: old}]`, followed by
+   a main tier declaring `key: name, mode: replace` with `items: null`, fails with
+   `sequence.conflict` at `/items`. Replacing null with `42` also fails; replacing
+   it with `[{name: new}]` succeeds. Null/scalar replacement should discard the
+   lower identity and retain the newly declared key as pending policy, subject
+   to the application's schema and constraints.
+2. Removing an ancestor while declaring a new pending key for its removed
+   descendant fails before the replacement occurs. A lower
+   `group: {items: [{id: old}]}` with key `id`, followed by `group: null` and a
+   root declaration of key `name` for `[group, items]`, fails at `/group/items`.
+   The analogous `base`/`child` inheritance case fails at `/child/group/items`.
+   The old collection is being removed rather than retained.
+3. Inheritance can resurrect removed identity even without a conflicting new
+   declaration. This input fails with a missing `id` at
+   `/grandchild/group/items/0/id`:
+
+   ```yaml
+   configkit:
+     sequences: [{destination: [base, group, items], key: id}]
+   base: {group: {items: [{id: old}]}}
+   child:
+     extends: base
+     group: null
+   grandchild:
+     extends: child
+     group: {items: [{name: new}]}
+   ```
+
+   The same remove/reintroduce operations through source tiers succeed. The
+   inherited descendant identity remains in policy state after its enclosing
+   mapping is removed, so the grandchild incorrectly receives the old key.
+
+Required remediation: account for actual value and ancestor replacement before
+deciding which lower identity participates in agreement, and retire removed
+descendant/record-owned state during inheritance as during source precedence.
+Retained inheritance templates must not reestablish discarded identity later.
+Preserve authoritative application constraints, independently owned mode
+persistence, pending declarations, and rejection of key changes when values are
+genuinely retained. Cover direct non-sequence replacement, ancestor removal with
+a new pending key, and removal followed by reintroduction across both contexts.
+Do not require repeated keys or narrow permitted null/scalar shapes to avoid
+these cases.
+
+## 13. Keep Metadata History In Post-Decode CLI Order — P2
+
+Status: [x] Complete.
+
+Completion: metadata history is assembled from the pre-CLI source view, with CLI
+events appended separately; inheritance is projected before CLI and resolution.
+Effective fields still describe post-CLI values. Regressions verify chronological
+origins and resolver dependencies for ordinary/layered mapping and record
+inheritance, including equal-valued assignments. Verified history/override
+coverage and `./scripts/check.sh`.
+
+Owners: [`historyWithInheritance`](../../internal/engine/inheritance_history.go)
+and the source/CLI metadata handoff in
+[`preparePostDecodeOverrideContext`](../../internal/engine/override_context.go).
+
+The value explanation follows the new lifecycle, but `Metadata.History` still
+inserts inheritance after stored CLI changes. `historyWithInheritance` splits
+only at `LayerResolution`, reflecting the former CLI-before-inheritance order.
+The reconstructed source view can also append an authored source origin after
+the CLI event.
+
+Reproduction: load `base: {value: parent}` and
+`child: {extends: base, value: authored}`, then override `[child, value]` with
+`"cli"`. The final value and `Metadata.Lookup` correctly report CLI provenance.
+`Explain` reports source → inheritance → CLI. `Metadata.History` instead reports
+source → CLI → source → inheritance and ends with a source/inheritance origin.
+This violates chronological metadata history and disagrees with the effective
+origin and the value explanation.
+
+Required remediation: assemble metadata history in the implemented source,
+inheritance, CLI, and resolution order, preserving the real origins and
+dependencies of those events. Cover ordinary/layered loading, mapping and record
+inheritance, equal-valued CLI writes, and a later recorded resolver change at the
+appropriate existing test owners. Do not impose a new exact event-count or
+message-format contract.
+
+## 14. Carry Main-Version Coordinates Through Sequence Movement — P2
+
+Status: [x] Complete.
+
+Completion: the effective version rule now follows the main declaration through
+strict placement, tier combination, and inheritance without changing source-local
+checker/evidence paths. Underlay and overlay ownership checks use assigned record
+positions, including whole-record removal; integer conversion remains confined
+to the actual main header. Regressions cover mounted/indexed paths, appended and
+matched records, integer/string parity, unrelated version payload, imported
+underlay claims, and inheritance. Corrected an older ownership fixture to target
+the actual matching main record. Verified source-version regressions,
+`./scripts/check.sh`, and `go test -race ./internal/engine`.
+
+Owners: [`effectiveSourceVersionRuleForPlacement`](../../internal/engine/source_version.go),
+the main-tier projection handoff in
+[`assembleLayeredInput`](../../internal/engine/load_request.go), and use of
+the effective rule in [`executeLoadRequest`](../../internal/engine/load.go).
+
+Source destinations and version-evidence sensitivity paths follow item movement,
+but the rule used for integer-version decoding retains the original item index.
+Consequently an accepted integer header can fail decoding after an otherwise
+valid upsert placement.
+
+Reproduction with the public API:
+
+- Main input is `id: main` and `version: 4`, placed as one sequence item at
+  `Keys("items")`.
+- A lower input contributes the sequence item `id: lower` at the same destination.
+- Register identity `id` for `[items]`, select `SourceVersionModeIfPresent`, and
+  use `VersionRule.Path = Keys("version")` with an accepting checker.
+- Decode into records with `ID string` and `Version string`.
+
+The checker accepts `4` exactly once. Upsert places the main record at index 1,
+but decoding fails with `decode.type` at `/items/1/version`. The integer-to-string
+exception is still tied to `/items/0/version`. Quoting the identical version as
+`'4'` succeeds. A source-local indexed header path, without item placement,
+reproduces the same problem when its record moves during upsert.
+
+Required remediation: carry the main declaration's effective coordinates through
+the existing item projections into decoding and audit the associated ownership
+protection handoffs for the same stale-coordinate assumption. Preserve
+source-local checker/evidence paths, checker invocation count, main-only
+ownership, and the narrow integer-to-string exception. Cover moved existing and
+newly appended main records, integer/string parity, and protection of the actual
+main header after movement. Do not prohibit supported indexed paths or mounted
+main records as a workaround.
+
+## 15. Exclude Parent Identity From Inherited History Payload — P2
+
+Status: [x] Complete.
+
+Completion: retained record-inheritance operations now exclude parent identity
+from their payload and origin projection. Replay preserves the child's own
+identity before taking field, record, sequence, or root snapshots, without
+inventing inheritance events for retained identity fields. Regressions cover
+single and compound identities, explicit child provenance, ordinary inherited
+payload, and the parent's original history. Verified inheritance/inspection
+coverage, `./scripts/check.sh`, and `go test -race ./internal/engine`.
+
+Owners: inheritance operation construction in
+[`applyInheritanceScopeTemplates`](../../internal/engine/inheritance_schedule.go),
+[`appendInheritanceExplanation`](../../internal/engine/inheritance_explain.go),
+and transferred-origin projection in
+[`inheritance_history.go`](../../internal/engine/inheritance_history.go).
+
+Identified-record value construction excludes the parent's identity fields, but
+the retained history operation still supplies the complete parent record and
+its identity origins to the older mapping-inheritance replay machinery.
+
+Reproduction:
+
+```yaml
+configkit:
+  sequences: [{destination: [items], key: id}]
+items:
+  - id: base
+    value: parent
+  - id: child
+    extends: {id: base}
+```
+
+The effective child ID and origin are correct. However,
+`Explain(Keys("items").Index(1).Key("id"))` reports `child` → `base` → `child`,
+attributing the intermediate value to an inheritance operation and the parent's
+ID location. `Metadata.History` likewise claims an inherited parent-ID
+contribution. That identity is expressly excluded from inherited payload; it was
+never an applied value at the child path.
+
+Required remediation: make history replay and transferred-origin projection use
+the same identity exclusion as value construction. Preserve the child's authored
+identity and presence, ordinary inherited payload history, and the parent record's
+own source history at its original path. Cover compound identities and identity
+fields alongside inherited payload at both record and ancestor queries; keep the
+existing inspection API and sensitivity behavior.
+
+## 16. Avoid Deep-Copying Accumulated Item Policies Per Record — P2
+
+Status: [x] Complete.
+
+Completion: item projection now takes one owned policy copy per destination,
+updates that local state incrementally, and stores it once after projection.
+Incoming scopes still cross detached ownership boundaries. Inspection confirms
+that accumulated record scopes are no longer deep-copied per item; no timing
+threshold or benchmark campaign was needed. Existing stable-index, sparse-range,
+fallback-offset, and ownership coverage passes, with a new regression for
+interleaved destinations, distinct record owners, and sibling/cross-load mutation
+independence. Verified focused item-policy tests, `./scripts/check.sh`, and
+`go test -race ./...`.
+
+Owners: [`projectNestedCollectionPolicies`](../../internal/engine/imports.go)
+and its use of copying `collectionPolicyScope.at` / `set` helpers in
+[`collection_policy_state.go`](../../internal/engine/collection_policy_state.go).
+
+The prefix-scan correction in finding 11 is present, but a separate quadratic
+cost remains on the same independently authored-record path. For every imported
+item with local policy, `at` deep-clones the destination's accumulated record
+order and every retained record's nested scope. After adding one owner, `set`
+deep-clones the growing policy again. With N fixed-size item-local policies at
+one destination, this copies approximately `1 + 2 + ... + N` retained scopes,
+even when every assigned sequence range is available.
+
+This follows directly from the loop and `cloneCollectionPolicy`; no busy-host
+timing comparison is required. It is an integration cost from reusing detached
+read/write helpers within private incremental construction, rather than from
+the required final ownership copies.
+
+Required remediation: construct each destination's owned record-policy state
+without repeatedly cloning all earlier records, retaining necessary copies at
+ownership boundaries. Preserve record ordering, distinct owners, sparse assigned
+positions, fallback offsets, and cross-load detachment. Reuse the existing item
+policy and ownership tests; add allocation/scaling evidence only where useful.
+Do not introduce public caches, pooling, new caps, or performance thresholds.
+
+## 17. Reconcile Legacy Sequence-History Contract Text — P2
+
+Status: [x] Complete.
+
+Completion: metadata and explanation prose now describe history through the
+selected collection operation, assigned item positions, and displaced payload.
+The text distinguishes sequence snapshots and atomic diffs from append/upsert
+combination and links to the canonical operation tables. Whole-record upsert,
+existing queries, and sensitivity guarantees are unchanged. Verified against
+replay/combination code, local documentation-link tests, and `git diff --check`;
+the unchanged runtime is covered by the preceding everyday and full race checks.
+
+Owner: the metadata/provenance and explanation sections of
+[`docs/config.md`](../config.md#layered-metadata).
+
+The metadata section still says that a later tier supplying a sequence records
+replacement at the sequence path and that history does not imply identity-based
+merging across tiers. That describes the former unconditional replacement model,
+not the implemented append/upsert history or the collection operation tables in
+the same document. The explanation paragraph about atomic sequences also needs
+review so readers can distinguish snapshot/diff granularity from collection
+combination semantics.
+
+Required remediation: describe history for the selected collection operation and
+link to the canonical operation tables. Preserve the existing atomic sequence
+snapshot/diff behavior and whole-record upsert semantics; correcting the prose
+does not authorize recursive record-field merging, a new query API, or broader
+history guarantees.
+
+## Algorithm Audit Baseline And Scope
+
+Reviewed commit: `c73daf891d0f29c96f7026bdabcccb571f44a751`.
+Feature baseline: `4f941f8ba4c9a9ed0afa87b07fe6ba29f131d1c6`.
+
+This audit examines the sequence identity/operation, scoped-policy, inheritance,
+inspection, and post-decode CLI algorithms, including the completed corrections
+above. The intervening discovery roadmap commits add no implementation to audit.
+The accepted scheduler, deterministic ordering, exact numeric normalization,
+selector trie, and deliberately pairwise registration-overlap validation remain
+selected design choices; they are not findings here.
+
+Evidence and validation:
+
+- Code inspection establishes the complexity of findings 19–23 on bounded-depth
+  inputs with linear-sized results. Required result/history copies and genuinely
+  growing inheritance output are excluded from the alleged excess work. Bounds
+  describe internal operations, not new public performance guarantees.
+- An isolated public-API probe reproduces finding 18 using an in-memory
+  filesystem, without external services or real credentials.
+- Temporary tests supplied through a Go overlay, outside the repository, checked
+  all 768 combinations of append/upsert/replace over the 16 unique-ID lists drawn
+  from three IDs. Stable ordering, duplicate rejection, and whole-record payload
+  replacement agreed with an independent reference calculation.
+- A structural overlay test confirmed that 4, 8, and 16 one-item contributions
+  retain 10, 36, and 136 reverse-index cells respectively in `indexSequenceRanges`.
+  These are representation counts, not timing or real-world benchmark results.
+- `go test ./internal/engine -run 'Sequence|Collection|Inheritance|Override|SourceVersion|Metadata|History' -count=1`
+  passed with Go 1.26.10 on Linux. Passing existing tests does not cover the
+  incorrect selector scope or establish efficient growth.
+
+The following are focused corrections within the selected model. This review
+changes only the remediation record.
+
+## 18. Match Application Registrations In Effective Item Coordinates — P2
+
+Status: [ ] Open.
+
+Owner: `composePendingItems` in
+[`imports.go`](../../internal/engine/imports.go), especially its local
+`composeDocumentsWithCollectionPolicy` call; the current
+`TestPendingItemCompositionAppliesApplicationIdentityConstraints` in
+[`item_policy_test.go`](../../internal/engine/item_policy_test.go) also needs review.
+
+Pending item/helper documents are composed in item-local coordinates while the
+unchanged global application selector policy is supplied to their composer.
+A registration for root `[prompts]` therefore also constrains an unrelated
+`[items, 0, prompts]` collection before placement. This contradicts complete,
+effective-destination matching and makes an otherwise unused registration reject
+valid configuration. Application selectors do not traverse sequence indexes.
+
+Reproduction: main imports `item.yml` with destination `[items]` and placement
+`sequence-item`. The item contains `id: outer` and
+`prompts: [{text: payload}]`. Loading succeeds without a registration; adding
+only `SequenceIdentityAt(Keys("prompts"), "id")` fails with `compose.invalid`
+at `/items/0/prompts/0/id`, although no root `prompts` collection exists.
+
+Required remediation: separate item-local YAML policy from application matching
+in effective coordinates, including nested helper scopes. Preserve applicable
+outer collection constraints without reinterpreting global selectors as local
+ones. Add ordinary/layered regressions for unused root and dynamic selectors
+alongside imported item-local collections. Correct tests that pin the accidental
+scope; do not change selector meaning or require consumers to remove valid rules.
+
+## 19. Avoid Dense Global-Position Storage For Sparse Item Projections — P2
+
+Status: [ ] Open.
+
+Owners: `newSequenceItemProjectionIndex` in
+[`sequence_projection.go`](../../internal/engine/sequence_projection.go),
+`indexSequenceRange` / `projectedCompositionOrigins` in
+[`compose.go`](../../internal/engine/compose.go), and contribution indexing in
+[`history.go`](../../internal/engine/history.go).
+
+The reverse projection slice is sized to `maxOutput + 1`, even for one incoming
+item assigned to a late assembled position. `indexSequenceRange` materializes
+these indexes for ordinary contiguous append ranges too. With N one-item sources
+contributing to one sequence, reverse slices retain `1 + 2 + ... + N` cells.
+Initialization time and simultaneously retained auxiliary storage are therefore
+quadratic despite only N actual mappings. Origin/history projection constructs
+the same representation through additional callers. Finding 16's policy-copy
+correction does not remove this independent cost.
+
+Required remediation: retain arithmetic start/end lookup for contiguous ranges
+and use storage proportional to actual mappings for scattered positions, such as
+a sparse reverse map. Audit shared callers and avoid rebuilding equivalent indexes
+inside item queries. Preserve bidirectional lookup, absent positions, upsert
+replacement evidence, ordering, and detached results. Verify the representation
+on many one-item sources and noncontiguous upserts; add no timing threshold or
+collection-size limit.
+
+## 20. Remove Full Metadata Scans Per CLI Replacement Leaf — P2
+
+Status: [ ] Open.
+
+Owners: `updateOverridePresence`, `deletePresencePathSubtree`, and
+`updateOverrideOrigins` in
+[`override_decode.go`](../../internal/engine/override_decode.go).
+
+Every replaced scalar or subtree scans all presence keys, then all origin keys,
+to find matching prefixes. A single partial-mapping override updating N scalar
+children in an N-field configuration performs quadratic map-entry visits. This
+does not require N CLI sources or growing historical output: the same effective
+maps remain approximately N entries throughout the update.
+
+Required remediation: delete affected entries by walking the already known
+existing subtree, or use one batch-local prefix index where needed. Retain
+necessary copies at ownership boundaries without rescanning unrelated paths for
+each leaf. Preserve retained explicit zero/false values, removal of replaced
+descendants, null/kind changes, origin attribution, and detached loads. Use the
+existing nested CLI and ownership regressions plus focused broad-mapping coverage;
+do not change override semantics or impose batch limits.
+
+## 21. Localize Inheritance Policy Work To The Relevant Scope — P2
+
+Status: [ ] Open.
+
+Owners: `inheritancePolicyScopeAtPath` in
+[`inheritance.go`](../../internal/engine/inheritance.go), graph preparation in
+[`inheritance_schedule.go`](../../internal/engine/inheritance_schedule.go),
+and policy handoff/retirement in
+[`inheritance_walk.go`](../../internal/engine/inheritance_walk.go).
+
+Scope localization scans every entry in the supplied policy table for each
+definition. Mapping graph preparation also clones the full supplied table, and
+the walker passes its global table to each independent scope and scans that table
+again during replacement. For S scopes or siblings and P unrelated collection
+policies, these paths perform repeated S-by-P work and copies.
+
+For example, N independent mapping groups can each contain a constant-sized
+`base`/`child extends base` pair and one YAML collection declaration beneath its
+base. Input, expanded values, and relationship evidence remain linear in N, but
+each group's graph/localization visits or clones the other groups' policies.
+This is separate from necessary expansion along a genuinely growing parent chain
+and from the selected dependency scheduler.
+
+Required remediation: partition or index policies by semantic scope once and
+carry the relevant state through traversal, including efficient descendant
+retirement as inheritance introduces or removes destinations. Clone owned
+in-scope state rather than unrelated global state. Preserve record owners,
+pending declarations, mode lifetime, destination-local registration matching,
+and independent templates. Verify wide independent groups and nested item scopes;
+do not replace the agreed scheduling algorithm or add global caches.
+
+## 22. Index Fallback Location Lookup During Effective Projection — P2
+
+Status: [ ] Open.
+
+Owner: `documentWithMetadataLocations` in
+[`override_context.go`](../../internal/engine/override_context.go), using
+`nearestDocumentLocation` in
+[`validation.go`](../../internal/engine/validation.go).
+
+The new effective-projection walk calls the unindexed nearest-location helper
+for each field lacking a real origin location, often once for its mapping entry
+and again for its value. Each call starts at the fallback root and linearly scans
+mapping entries. With N authored root fields and N different default-only root
+fields, each default's failed lookup scans all N authored keys: quadratic work
+for linear-sized input and output. The shared lifecycle calls this path even
+without CLI assignments or a resolver.
+
+Required remediation: share an indexed fallback lookup or traverse corresponding
+containers together while carrying the nearest available location. Existing
+`documentLookup` / mapping-index machinery can support bounded-depth lookups
+without repeated wide scans. Preserve nearest-ancestor fallback, source IDs,
+synthetic locations, secret-reference diagnostics, and publication ownership.
+Exercise mixed authored/default-only broad mappings; do not weaken attribution
+or skip needed location attachment to avoid the work.
+
+## 23. Index Repeated Collection-Policy Document Lookups — P2
+
+Status: [ ] Open.
+
+Owners: `mergeOverlayMappingsWithCollectionPolicy` in
+[`overlay.go`](../../internal/engine/overlay.go) and
+`mergeInheritanceCollectionPolicies` in
+[`inheritance_collection.go`](../../internal/engine/inheritance_collection.go).
+
+These routines loop over collection policies/declarations and call plain
+`documentAtPath` for each destination. That helper linearly searches every
+mapping on the path. N independent collections below N sibling mapping keys
+therefore cause quadratic mapping-entry searches when checking which lower
+policies the incoming tier touches. The inheritance parent/child lookups and
+retained-value declaration checks have the same pattern. YAML declarations alone
+can establish these policies; the deliberately pairwise application-registration
+overlap check is not involved.
+
+Required remediation: reuse a document lookup built once for each stable input
+tree, or use the already collected claims where their scope is sufficient.
+Index a mutated result only after its value-changing phase, rather than retaining
+a stale lookup. Preserve absent destinations, non-sequence pending declarations,
+literal key/index distinctions, retirement, and error locations. Verify broad
+independent collections across precedence and inheritance; no new public cache,
+shape requirement, or performance gate is needed.

docs/roadmap/sequences.md

@@ -28,9 +28,8 @@ sequences, selected overlays, and sibling inheritance. Typed defaults, CLI
 assignments, and application resolution retain their own combination semantics;
 CLI application moves later in the loading lifecycle.
 
-This scope is narrower than the deferred
-[identified-record sequences proposal](future.md#1-identified-record-sequences).
-Automatic recursive merging of matching records remains outside this scope;
+Automatic recursive merging of matching records remains deferred
+(see [future work](future.md#1-recursive-body-merging-for-identified-records));
 explicit inheritance between distinct records is included. The initial
 declaration surface is `configkit.sequences`; `key` and `mode` shorthand on
 imports is deferred. Application lists remain

example_test.go

@@ -19,6 +19,28 @@ func ExampleLoad() {
 	// Output: {true 3} <nil>
 }
 
+func ExampleLoad_sequenceDeclaration() {
+	type Item struct {
+		ID string `yaml:"id"`
+	}
+	type Config struct {
+		Items []Item `yaml:"items"`
+	}
+	result, err := configkit.Load[Config](configkit.Bytes("catalog.yml", []byte(`configkit:
+  sequences:
+    - destination: [items]
+      key: id
+items:
+  - id: prompt
+`)))
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	fmt.Println(result.Config.Items[0].ID)
+	// Output: prompt
+}
+
 func ExampleNoSource() {
 	type Config struct {
 		Workers int `yaml:"workers"`
@@ -154,8 +176,15 @@ func ExampleOverride() {
 		})
 	}
 	result, err := configkit.Load(configkit.NoSource(), configkit.Options[Config]{
-		Definition: configkit.Definition[Config]{Defaults: func() Config { return Config{Workers: 4} }},
-		Overrides:  overrides,
+		Definition: configkit.Definition[Config]{
+			Defaults: func() Config { return Config{Workers: 4} },
+			Resolve: func(configuration *Config, resolution *configkit.Resolution) error {
+				configkit.Default(resolution, configkit.Keys("workers"), &configuration.Workers, 100,
+					"preserve an explicitly supplied worker count")
+				return nil
+			},
+		},
+		Overrides: overrides,
 	})
 	fmt.Println(result.Config.Workers, result.Sources()[0].Label, err)
 	// Output: 0 --workers <nil>

examples/consumers/prompt_catalog.go

@@ -45,10 +45,9 @@ func LoadRequiredPromptCatalog(mainPath string) (*configkit.Result[PromptCatalog
 
 func promptCatalogDefinition() configkit.Definition[PromptCatalogConfig] {
 	return configkit.Definition[PromptCatalogConfig]{
-		SequenceCompositions: []configkit.SequenceComposition{{
-			Path:          configkit.Keys("prompts"),
-			IdentityField: "id",
-		}},
+		SequenceIdentities: []configkit.SequenceIdentity{
+			configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+		},
 		Validate: validatePromptCatalog,
 	}
 }

examples/consumers/sequence_catalog.go

@@ -0,0 +1,134 @@
+package consumers
+
+import (
+	"errors"
+	"fmt"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+// SequenceCatalogConfig is a source-backed prompt catalog with an application
+// supplied run label and a value derived from that label during resolution.
+type SequenceCatalogConfig struct {
+	RunLabel      string                 `yaml:"run_label"`
+	ResolvedLabel string                 `yaml:"resolved_label"`
+	Prompts       []SequenceCatalogEntry `yaml:"prompts"`
+}
+
+// SequenceCatalogEntry keeps prompt meaning, resources, and credentials in the
+// consuming application while ConfigKit handles collection assembly.
+type SequenceCatalogEntry struct {
+	ID          string           `yaml:"id"`
+	Name        string           `yaml:"name"`
+	Description string           `yaml:"description"`
+	Messages    []string         `yaml:"messages"`
+	Resource    string           `yaml:"resource"`
+	Credential  configkit.Secret `yaml:"credential"`
+}
+
+// LoadSequenceCatalog assembles imported main fragments over a file-backed
+// underlay, applies one selected collection overlay, then resolves and validates
+// the resulting application configuration.
+func LoadSequenceCatalog(mainPath, overlayName, runLabel string) (*configkit.Result[SequenceCatalogConfig], error) {
+	root := filepath.Dir(mainPath)
+	filesystem := configkit.NewFilesystem("sequence catalog", os.DirFS(root))
+	filesystemContext := &configkit.FilesystemContext{BaseDir: ".", Root: ".", FS: &filesystem}
+	definition := configkit.Definition[SequenceCatalogConfig]{
+		SequenceIdentities: []configkit.SequenceIdentity{
+			configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+		},
+		Resolve: func(configuration *SequenceCatalogConfig, resolution *configkit.Resolution) error {
+			configuration.ResolvedLabel = "for:" + configuration.RunLabel
+			resolution.Record(configkit.Keys("resolved_label"), configkit.ChangeNormalization,
+				"derive the resolved label from the selected run label", configkit.Keys("run_label"))
+			return nil
+		},
+		Validate: validateSequenceCatalog,
+	}
+	return configkit.LoadLayered(configkit.Input{
+		Source:  filesystem.File(filepath.Base(mainPath)),
+		Imports: true,
+	}, configkit.LayeredOptions[SequenceCatalogConfig]{
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: filesystem.File("underlay.yml"),
+		}}}},
+		Overlay:           overlayName,
+		OverlayFilesystem: filesystemContext,
+		Overrides: []configkit.Override{{
+			Path: configkit.Keys("run_label"), Value: runLabel, Flag: "--run-label",
+		}},
+		Definition: definition,
+	})
+}
+
+// ReadSequenceCatalogResource follows the final prompt field's source context,
+// including when record inheritance retained a resource from an underlay.
+func ReadSequenceCatalogResource(result *configkit.Result[SequenceCatalogConfig], promptID string) (string, error) {
+	if result == nil {
+		return "", errors.New("sequence catalog result is nil")
+	}
+	for index, prompt := range result.Config.Prompts {
+		if prompt.ID != promptID {
+			continue
+		}
+		resourcePath := configkit.Keys("prompts").Index(index).Key("resource")
+		info, found := result.Metadata().Lookup(resourcePath)
+		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 source context is unavailable")
+		}
+		data, err := fs.ReadFile(context.FS, path.Join(context.BaseDir, prompt.Resource))
+		if err != nil {
+			return "", fmt.Errorf("read prompt resource: %w", err)
+		}
+		return string(data), nil
+	}
+	return "", fmt.Errorf("prompt %q is unavailable", promptID)
+}
+
+func validateSequenceCatalog(configuration *SequenceCatalogConfig, validation *configkit.Validation) {
+	for index, prompt := range configuration.Prompts {
+		if strings.TrimSpace(prompt.Name) == "" {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("name"), "must not be empty")
+		}
+		if len(prompt.Messages) == 0 {
+			validation.Error(configkit.Keys("prompts").Index(index).Key("messages"), "must contain at least one message")
+		}
+	}
+	if len(configuration.Prompts) == 0 {
+		validation.Error(configkit.Keys("prompts"), "must contain at least one prompt")
+	}
+}
+
+// NamespacedMapCatalogConfig demonstrates typed application maps whose
+// independent prompt sequences use root and dynamic namespace registrations.
+type NamespacedMapCatalogConfig struct {
+	Prompts     []map[string]any          `yaml:"prompts"`
+	Collections map[string]map[string]any `yaml:"collections"`
+}
+
+// LoadNamespacedMapCatalog applies the same scalar identity constraint to one
+// root collection and each namespace's independently scoped collection.
+func LoadNamespacedMapCatalog(source configkit.Source) (*configkit.Result[NamespacedMapCatalogConfig], error) {
+	selector := configkit.SequenceSelector{
+		configkit.SequenceLiteralKey("collections"),
+		configkit.SequenceAnyMappingKey(),
+		configkit.SequenceLiteralKey("prompts"),
+	}
+	return configkit.Load(source, configkit.Options[NamespacedMapCatalogConfig]{
+		Definition: configkit.Definition[NamespacedMapCatalogConfig]{
+			SequenceIdentities: []configkit.SequenceIdentity{
+				configkit.SequenceIdentityAt(configkit.Keys("prompts"), "id"),
+				configkit.SequenceIdentityMatching(selector, "id"),
+			},
+		},
+	})
+}

examples/consumers/sequence_catalog_test.go

@@ -0,0 +1,239 @@
+package consumers_test
+
+import (
+	"bytes"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+	"gitea.maximumdirect.net/eric/ConfigKit/examples/consumers"
+)
+
+func Example_sequenceCatalog() {
+	const oldSecret = "CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET"
+	const newSecret = "CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET"
+	restoreOld, restoreNew := preserveEnvironment(oldSecret), preserveEnvironment(newSecret)
+	defer restoreOld()
+	defer restoreNew()
+	_ = os.Setenv(oldSecret, "disposable-old-example-credential")
+	_ = os.Setenv(newSecret, "disposable-new-example-credential")
+
+	result, err := consumers.LoadSequenceCatalog(fixture("sequence-catalog", "config.yml"), "upsert", "preview")
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+	ids := make([]string, 0, len(result.Config.Prompts))
+	for _, prompt := range result.Config.Prompts {
+		ids = append(ids, prompt.ID)
+	}
+	shared := configkit.Keys("prompts").Index(1).Key("name")
+	info, _ := result.Metadata().Lookup(shared)
+	resource, resourceErr := consumers.ReadSequenceCatalogResource(result, "concise")
+	fmt.Println(ids, result.Config.ResolvedLabel, info.Explicit, len(result.Metadata().History(shared)), resource, resourceErr == nil, err)
+	// Output: [foundation shared welcome concise extra] for:preview true 2 Foundation resource text.
+	//  true <nil>
+}
+
+func TestSequenceCatalogSelectedOverlayOperations(t *testing.T) {
+	const oldSecret = "CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET"
+	const newSecret = "CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET"
+	t.Setenv(oldSecret, "sequence-catalog-old-canary")
+	t.Setenv(newSecret, "sequence-catalog-new-canary")
+
+	tests := []struct {
+		name    string
+		wantIDs []string
+		shared  *consumers.SequenceCatalogEntry
+	}{
+		{name: "append", wantIDs: []string{"foundation", "shared", "welcome", "concise", "extra"}},
+		{name: "upsert", wantIDs: []string{"foundation", "shared", "welcome", "concise", "extra"}, shared: &consumers.SequenceCatalogEntry{ID: "shared", Name: "Shared replacement", Messages: []string{"Replacement message"}, Credential: configkit.SecretEnv(newSecret)}},
+		{name: "replace", wantIDs: []string{"replacement", "last"}},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := consumers.LoadSequenceCatalog(fixture("sequence-catalog", "config.yml"), test.name, "test")
+			if err != nil {
+				var loadError *configkit.LoadError
+				if errors.As(err, &loadError) {
+					t.Fatalf("load selected overlay: %v (%#v)", err, loadError.Diagnostics())
+				}
+				t.Fatal(err)
+			}
+			gotIDs := make([]string, 0, len(result.Config.Prompts))
+			for _, prompt := range result.Config.Prompts {
+				gotIDs = append(gotIDs, prompt.ID)
+			}
+			if strings.Join(gotIDs, ",") != strings.Join(test.wantIDs, ",") {
+				t.Fatalf("prompt order = %v, want %v", gotIDs, test.wantIDs)
+			}
+			if test.shared == nil {
+				return
+			}
+			shared := result.Config.Prompts[1]
+			if shared.ID != test.shared.ID || shared.Name != test.shared.Name || len(shared.Messages) != 1 ||
+				shared.Messages[0] != test.shared.Messages[0] || shared.Description != "" || shared.Resource != "" || shared.Credential.EnvName() != newSecret {
+				t.Fatalf("upsert did not replace the complete matched record: %#v", shared)
+			}
+		})
+	}
+}
+
+func TestSequenceCatalogInspectionTracksResourcesAndSecretHistory(t *testing.T) {
+	const oldSecret = "CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET"
+	const newSecret = "CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET"
+	const oldCanary = "sequence-catalog-old-canary"
+	const newCanary = "sequence-catalog-new-canary"
+	t.Setenv(oldSecret, oldCanary)
+	t.Setenv(newSecret, newCanary)
+
+	result, err := consumers.LoadSequenceCatalog(fixture("sequence-catalog", "config.yml"), "upsert", "history")
+	if err != nil {
+		var loadError *configkit.LoadError
+		if errors.As(err, &loadError) {
+			t.Fatalf("load sequence catalog: %v (%#v)", err, loadError.Diagnostics())
+		}
+		t.Fatal(err)
+	}
+	resourcePath := configkit.Keys("prompts").Index(3).Key("resource")
+	resourceInfo, found := result.Metadata().Lookup(resourcePath)
+	if !found || len(resourceInfo.Origin.Locations) != 1 || len(resourceInfo.Origin.Inheritance) != 1 {
+		t.Fatalf("inherited resource inspection = %#v, %v", resourceInfo, found)
+	}
+	resource, err := consumers.ReadSequenceCatalogResource(result, "concise")
+	if err != nil || resource != "Foundation resource text.\n" {
+		t.Fatalf("resource from inherited source context = %q, %v", resource, err)
+	}
+	if len(result.Metadata().History(configkit.Keys("resolved_label"))) == 0 {
+		t.Fatal("recorded CLI-driven resolution was absent from final inspection")
+	}
+	credentialPath := configkit.Keys("prompts").Index(1).Key("credential")
+	credentialHistory := result.Metadata().History(credentialPath)
+	if len(credentialHistory) == 0 {
+		t.Fatal("upsert did not retain the replaced secret reference in history")
+	}
+	var explanation bytes.Buffer
+	if err := result.WriteExplanation(&explanation, credentialPath); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(explanation.String(), oldCanary) || strings.Contains(explanation.String(), newCanary) {
+		t.Fatalf("secret explanation exposed a credential value: %s", explanation.String())
+	}
+}
+
+func TestNamespacedTypedMapIdentityScopesAreIndependent(t *testing.T) {
+	source := configkit.Bytes("namespaced maps", []byte(`
+prompts:
+  - id: shared
+    text: root prompt
+collections:
+  team:
+    prompts:
+      - id: shared
+        text: team prompt
+  operations:
+    prompts:
+      - id: shared
+        text: operations prompt
+`))
+	result, err := consumers.LoadNamespacedMapCatalog(source)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Config.Prompts[0]["text"] != "root prompt" ||
+		result.Config.Collections["team"]["prompts"].([]any)[0].(map[string]any)["text"] != "team prompt" ||
+		result.Config.Collections["operations"]["prompts"].([]any)[0].(map[string]any)["text"] != "operations prompt" {
+		t.Fatalf("typed map collections = %#v", result.Config)
+	}
+}
+
+func TestNamespacedTypedMapIdentityFindsCollectionsIntroducedByInheritance(t *testing.T) {
+	result, err := consumers.LoadNamespacedMapCatalog(configkit.Bytes("inherited namespace", []byte(`
+collections:
+  source:
+    prompts:
+      - id: shared
+        text: inherited prompt
+  copied:
+    extends: source
+`)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	copied := result.Config.Collections["copied"]["prompts"].([]any)
+	if len(copied) != 1 || copied[0].(map[string]any)["text"] != "inherited prompt" {
+		t.Fatalf("inherited typed-map collection = %#v", result.Config.Collections["copied"])
+	}
+}
+
+func Example_yamlDeclaredIdentityOnly() {
+	result, err := configkit.Load(configkit.Bytes("YAML identity only", []byte(`
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+prompts:
+  - id: initial
+`)), configkit.Options[map[string]any]{
+		Overrides: []configkit.Override{{
+			Path: configkit.Keys("prompts"),
+			Value: []any{
+				map[string]any{"id": "same"},
+				map[string]any{"id": "same"},
+			},
+			Flag: "--prompts",
+		}},
+	})
+	fmt.Println(len(result.Config["prompts"].([]any)), err)
+	// Output: 2 <nil>
+}
+
+func TestYAMLDeclaredIdentityDoesNotRegisterFinalTypedConstraint(t *testing.T) {
+	result, err := configkit.Load(configkit.Bytes("YAML identity only", []byte(`
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+prompts:
+  - id: initial
+`)), configkit.Options[map[string]any]{
+		Overrides: []configkit.Override{{
+			Path: configkit.Keys("prompts"),
+			Value: []any{
+				map[string]any{"id": "same"},
+				map[string]any{"id": "same"},
+			},
+			Flag: "--prompts",
+		}},
+	})
+	if err != nil {
+		t.Fatalf("YAML-only identity incorrectly became an application constraint: %v", err)
+	}
+	prompts := result.Config["prompts"].([]any)
+	if len(prompts) != 2 || prompts[0].(map[string]any)["id"] != prompts[1].(map[string]any)["id"] {
+		t.Fatalf("CLI result = %#v", result.Config)
+	}
+}
+
+func TestNamespacedTypedMapRejectsDuplicatesWithinOneCollection(t *testing.T) {
+	_, err := consumers.LoadNamespacedMapCatalog(configkit.Bytes("duplicate namespace", []byte(`
+collections:
+  team:
+    prompts:
+      - id: duplicate
+      - id: duplicate
+`)))
+	var loadError *configkit.LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 ||
+		loadError.Diagnostics()[0].Code != configkit.CodeComposeConflict ||
+		loadError.Diagnostics()[0].Path.String() != "/collections/team/prompts" {
+		diagnostics := []configkit.Diagnostic(nil)
+		if loadError != nil {
+			diagnostics = loadError.Diagnostics()
+		}
+		t.Fatalf("duplicate namespaced identity error = %v (%#v)", err, diagnostics)
+	}
+}

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

@@ -1,4 +1,8 @@
 configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: replace
   imports:
     - dir: prompts
       exclude: [generated-ignored.yml]

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

@@ -1,3 +1,8 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: replace
 prompts:
   - id: invalid
     name: Invalid prompt

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

@@ -0,0 +1,7 @@
+run_label: source-default
+configkit:
+  imports:
+    - dir: fragments
+      pattern: '*.yml'
+      destination: [prompts]
+      placement: sequence-item

examples/consumers/testdata/sequence-catalog/foundation.txt

@@ -0,0 +1 @@
+Foundation resource text.

examples/consumers/testdata/sequence-catalog/fragments/01-welcome.yml

@@ -0,0 +1,4 @@
+id: welcome
+name: Welcome
+messages: [Welcome message]
+credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/fragments/02-concise.yml

@@ -0,0 +1,3 @@
+id: concise
+extends: {id: foundation}
+name: Concise

examples/consumers/testdata/sequence-catalog/overlays/append.yml

@@ -0,0 +1,10 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: append
+prompts:
+  - id: extra
+    name: Extra
+    messages: [Extra message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/overlays/replace.yml

@@ -0,0 +1,14 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: replace
+prompts:
+  - id: replacement
+    name: Replacement
+    messages: [Replacement message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET
+  - id: last
+    name: Last
+    messages: [Last message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/overlays/upsert.yml

@@ -0,0 +1,14 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: upsert
+prompts:
+  - id: shared
+    name: Shared replacement
+    messages: [Replacement message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_NEW_SECRET
+  - id: extra
+    name: Extra
+    messages: [Extra message]
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

examples/consumers/testdata/sequence-catalog/underlay.yml

@@ -0,0 +1,18 @@
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+      mode: append
+prompts:
+  - id: foundation
+    name: Foundation
+    description: Shared foundation instruction
+    messages: [Foundation message]
+    resource: foundation.txt
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET
+  - id: shared
+    name: Shared draft
+    description: This field must not survive a whole-record replacement
+    messages: [Draft message]
+    resource: shared.txt
+    credential: CONFIGKIT_SEQUENCE_CATALOG_OLD_SECRET

facade_final_sequence_identity_test.go

@@ -0,0 +1,249 @@
+package configkit_test
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func TestFinalSequenceIdentityTreatsLateExtendsFieldsAsPayload(t *testing.T) {
+	for _, phase := range []string{"defaults", "resolution"} {
+		for _, component := range []any{"application-data", nil} {
+			for _, duplicate := range []bool{false, true} {
+				t.Run(fmt.Sprintf("%s/%v/duplicate=%t", phase, component, duplicate), func(t *testing.T) {
+					items := []any{map[string]any{"extends": component}}
+					if duplicate {
+						items = append(items, map[string]any{"extends": component})
+					}
+					definition := configkit.Definition[map[string]any]{
+						SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "extends")},
+						Defaults: func() map[string]any {
+							if phase == "defaults" {
+								return map[string]any{"items": items}
+							}
+							return map[string]any{}
+						},
+					}
+					if phase == "resolution" {
+						definition.Resolve = func(value *map[string]any, resolution *configkit.Resolution) error {
+							(*value)["items"] = items
+							resolution.Record(configkit.Keys("items"), configkit.ChangeNormalization, "supply application payload")
+							return nil
+						}
+					}
+					loaded, err := configkit.Load(configkit.NoSource(), configkit.Options[map[string]any]{Definition: definition})
+					if duplicate {
+						loadErr := requireFacadeLoadError(t, err)
+						diagnostics := loadErr.Diagnostics()
+						if loaded != nil || len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeSequenceConflict || diagnostics[0].Path.String() != "/items" {
+							t.Fatalf("duplicate effective payload diagnostics = %#v", diagnostics)
+						}
+						return
+					}
+					if err != nil || loaded == nil {
+						t.Fatalf("ordinary effective identity was interpreted as a directive: %v", err)
+					}
+					value := loaded.Config["items"].([]any)[0].(map[string]any)
+					if actual, present := value["extends"]; !present || actual != component {
+						t.Fatalf("effective payload = %#v", value)
+					}
+				})
+			}
+		}
+	}
+}
+
+func TestFinalSequenceIdentityValidatesLateValues(t *testing.T) {
+	identity := configkit.SequenceIdentityAt(configkit.Keys("items"), "id")
+	for _, source := range []string{"defaults", "CLI", "resolution"} {
+		for _, shape := range []string{"duplicate", "missing", "non-scalar"} {
+			t.Run(source+"/"+shape, func(t *testing.T) {
+				items := finalIdentityRecords(shape)
+				definition := configkit.Definition[map[string]any]{
+					SequenceIdentities: []configkit.SequenceIdentity{identity},
+					Defaults: func() map[string]any {
+						if source == "defaults" {
+							return map[string]any{"items": items}
+						}
+						return map[string]any{}
+					},
+				}
+				options := configkit.Options[map[string]any]{Definition: definition}
+				switch source {
+				case "CLI":
+					options.Overrides = []configkit.Override{{Path: configkit.Keys("items"), Value: items, Flag: "--items"}}
+				case "resolution":
+					options.Definition.Resolve = func(value *map[string]any, resolution *configkit.Resolution) error {
+						(*value)["items"] = items
+						resolution.Record(configkit.Keys("items"), configkit.ChangeNormalization, "create effective records")
+						return nil
+					}
+				}
+				result, err := configkit.Load(configkit.NoSource(), options)
+				if result != nil {
+					t.Fatalf("invalid final identities returned a result: %#v", result.Config)
+				}
+				loadErr := requireFacadeLoadError(t, err)
+				if len(loadErr.Diagnostics()) != 1 {
+					t.Fatalf("diagnostics = %#v", loadErr.Diagnostics())
+				}
+				diagnostic := loadErr.Diagnostics()[0]
+				wantCode, wantPath := configkit.CodeSequenceInvalid, "/items/0/id"
+				if shape == "duplicate" {
+					wantCode, wantPath = configkit.CodeSequenceConflict, "/items"
+				}
+				if diagnostic.Code != wantCode || diagnostic.Path.String() != wantPath {
+					t.Fatalf("diagnostic = %#v, want %s at %s", diagnostic, wantCode, wantPath)
+				}
+				if source == "CLI" && (diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-1") {
+					t.Fatalf("CLI identity diagnostic lost its source: %#v", diagnostic)
+				}
+			})
+		}
+	}
+}
+
+func TestFinalSequenceIdentityMatchesLateDynamicNamespaces(t *testing.T) {
+	selector := configkit.SequenceSelector{
+		configkit.SequenceLiteralKey("collections"),
+		configkit.SequenceAnyMappingKey(),
+		configkit.SequenceLiteralKey("items"),
+	}
+	for _, source := range []string{"defaults", "CLI", "resolution"} {
+		t.Run(source, func(t *testing.T) {
+			name := map[string]string{"defaults": "team", "CLI": "cloud", "resolution": "orbit"}[source]
+			path := configkit.Keys("collections", name, "items")
+			items := finalIdentityRecords("duplicate")
+			definition := configkit.Definition[map[string]any]{
+				SequenceIdentities: []configkit.SequenceIdentity{
+					configkit.SequenceIdentityMatching(selector, "id"),
+				},
+				Defaults: func() map[string]any {
+					if source == "defaults" {
+						return map[string]any{"collections": map[string]any{name: map[string]any{"items": items}}}
+					}
+					return map[string]any{}
+				},
+			}
+			options := configkit.Options[map[string]any]{Definition: definition}
+			switch source {
+			case "CLI":
+				options.Overrides = []configkit.Override{{Path: path, Value: items, Flag: "--items"}}
+			case "resolution":
+				options.Definition.Resolve = func(value *map[string]any, resolution *configkit.Resolution) error {
+					(*value)["collections"] = map[string]any{name: map[string]any{"items": items}}
+					resolution.Record(configkit.Keys("collections"), configkit.ChangeNormalization, "create namespaced records")
+					return nil
+				}
+			}
+			result, err := configkit.Load(configkit.NoSource(), options)
+			if result != nil {
+				t.Fatalf("invalid dynamic identity returned a result: %#v", result.Config)
+			}
+			loadErr := requireFacadeLoadError(t, err)
+			if diagnostics := loadErr.Diagnostics(); len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeSequenceConflict || diagnostics[0].Path.String() != path.String() {
+				t.Fatalf("dynamic identity diagnostics = %#v", diagnostics)
+			}
+		})
+	}
+}
+
+func TestFinalSequenceIdentityAppliesToLayeredLoads(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{
+		SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "id")},
+		Defaults: func() map[string]any {
+			return map[string]any{"items": finalIdentityRecords("duplicate")}
+		},
+	}
+	result, err := configkit.LoadLayered(configkit.Input{Source: configkit.NoSource()}, configkit.LayeredOptions[map[string]any]{Definition: definition})
+	if result != nil {
+		t.Fatalf("invalid layered final identities returned a result: %#v", result.Config)
+	}
+	loadErr := requireFacadeLoadError(t, err)
+	if diagnostics := loadErr.Diagnostics(); len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeSequenceConflict {
+		t.Fatalf("layered identity diagnostics = %#v", diagnostics)
+	}
+}
+
+func TestFinalSequenceIdentityUsesTypedNumbersAndIgnoresUnmatchedShapes(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{
+		SequenceIdentities: []configkit.SequenceIdentity{
+			configkit.SequenceIdentityAt(configkit.Keys("items"), "id"),
+			configkit.SequenceIdentityAt(configkit.Keys("unmatched"), "id"),
+		},
+	}
+	_, err := configkit.Load(configkit.NoSource(), configkit.Options[map[string]any]{
+		Definition: configkit.Definition[map[string]any]{
+			SequenceIdentities: definition.SequenceIdentities,
+			Defaults: func() map[string]any {
+				return map[string]any{"items": []any{
+					map[string]any{"id": int64(1)}, map[string]any{"id": float64(1)},
+				}}
+			},
+		},
+	})
+	loadErr := requireFacadeLoadError(t, err)
+	if diagnostics := loadErr.Diagnostics(); len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeSequenceConflict {
+		t.Fatalf("typed numeric identity diagnostics = %#v", diagnostics)
+	}
+
+	valid, err := configkit.Load(configkit.Mapping("valid", map[string]any{
+		"items": []any{
+			map[string]any{"id": nil}, map[string]any{"id": true},
+			map[string]any{"id": int64(1)}, map[string]any{"id": "one"},
+		},
+		"other": []any{map[string]any{"id": "same"}, map[string]any{"id": "same"}},
+	}), configkit.Options[map[string]any]{Definition: definition})
+	if err != nil || valid == nil {
+		t.Fatalf("valid scalar identities and unmatched duplicate sequence = %#v, %v", valid, err)
+	}
+	if _, err := configkit.Load(configkit.Mapping("other-shapes", map[string]any{"items": nil}), configkit.Options[map[string]any]{Definition: definition}); err != nil {
+		t.Fatalf("null at a registered path was validated as an identity sequence: %v", err)
+	}
+}
+
+func TestFinalSequenceIdentityDiagnosticDoesNotRevealResolvedSecrets(t *testing.T) {
+	const canary = "FINAL-IDENTITY-CREDENTIAL-CANARY"
+	const secretName = "CONFIGKIT_FINAL_IDENTITY_SECRET"
+	t.Setenv(secretName, canary)
+	type item struct {
+		ID    string           `yaml:"id"`
+		Token configkit.Secret `yaml:"token"`
+	}
+	type config struct {
+		Items []item `yaml:"items"`
+	}
+	definition := configkit.Definition[config]{
+		SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "id")},
+		Defaults: func() config {
+			return config{Items: []item{
+				{ID: "duplicate", Token: configkit.SecretEnv(secretName)},
+				{ID: "duplicate", Token: configkit.SecretEnv(secretName)},
+			}}
+		},
+	}
+	result, err := configkit.Load(configkit.NoSource(), configkit.Options[config]{Definition: definition})
+	if result != nil {
+		t.Fatalf("duplicate identity returned a result: %#v", result.Config)
+	}
+	if err == nil || strings.Contains(err.Error(), canary) {
+		t.Fatalf("identity diagnostic leaked a resolved secret: %v", err)
+	}
+	loadErr := requireFacadeLoadError(t, err)
+	if diagnostics := loadErr.Diagnostics(); len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeSequenceConflict {
+		t.Fatalf("secret-bearing identity diagnostics = %#v", diagnostics)
+	}
+}
+
+func finalIdentityRecords(shape string) []any {
+	switch shape {
+	case "duplicate":
+		return []any{map[string]any{"id": "same"}, map[string]any{"id": "same"}}
+	case "missing":
+		return []any{map[string]any{"other": "value"}}
+	default:
+		return []any{map[string]any{"id": map[string]any{"nested": "value"}}}
+	}
+}

facade_import_lifecycle_test.go

@@ -40,8 +40,8 @@ entries:
 		Imports:    true,
 		Filesystem: &FilesystemContext{Root: "bundle", FS: &filesystem},
 		Definition: Definition[map[string]any]{
-			Version:              &VersionRule{Path: Keys("version"), Check: func(Version, *Validation) error { return nil }},
-			SequenceCompositions: []SequenceComposition{{Path: Keys("services", "records"), IdentityField: "id"}},
+			Version:            &VersionRule{Path: Keys("version"), Check: func(Version, *Validation) error { return nil }},
+			SequenceIdentities: []SequenceIdentity{SequenceIdentityAt(Keys("services", "records"), "id")},
 			Secret: func(candidate Path) bool {
 				return candidate.String() == "/services/records/0/version"
 			},
@@ -105,8 +105,8 @@ entries:
 		Imports:    true,
 		Filesystem: &FilesystemContext{Root: "bundle", FS: &filesystem},
 		Definition: Definition[map[string]any]{
-			Version:              &VersionRule{Path: Keys("version"), Check: func(Version, *Validation) error { return nil }},
-			SequenceCompositions: []SequenceComposition{{Path: Keys("services", "records"), IdentityField: "version"}},
+			Version:            &VersionRule{Path: Keys("version"), Check: func(Version, *Validation) error { return nil }},
+			SequenceIdentities: []SequenceIdentity{SequenceIdentityAt(Keys("services", "records"), "version")},
 			Secret: func(candidate Path) bool {
 				return candidate.String() == "/services/records/0/version"
 			},

facade_inheritance_test.go

@@ -91,6 +91,214 @@ func TestFacadeInheritancePreservesPresenceOriginsAndHistory(t *testing.T) {
 	}
 }
 
+func TestFacadeIdentifiedInheritanceResolvesChainsAndNestedCollections(t *testing.T) {
+	const secretName = "CONFIGKIT_IDENTIFIED_INHERITANCE_SECRET"
+	const canary = "IDENTIFIED-INHERITANCE-SECRET-CANARY"
+	t.Setenv(secretName, canary)
+	type step struct {
+		ID    string `yaml:"id"`
+		Value string `yaml:"value"`
+	}
+	type job struct {
+		ID         string                       `yaml:"id"`
+		Name       string                       `yaml:"name"`
+		Credential configkit.Secret             `yaml:"credential"`
+		Resource   string                       `yaml:"resource"`
+		Steps      []step                       `yaml:"steps"`
+		Settings   map[string]map[string]string `yaml:"settings"`
+	}
+	type configuration struct {
+		Jobs []job `yaml:"jobs"`
+	}
+	input := []byte(`jobs:
+- id: child
+  extends: {id: parent}
+  name: child-name
+- id: parent
+  extends: {id: base}
+- id: base
+  name: base-name
+  credential: CONFIGKIT_IDENTIFIED_INHERITANCE_SECRET
+  resource: icon.txt
+  steps:
+    - id: base-step
+      value: base-step-value
+    - id: second-step
+      value: second-step-value
+  settings:
+    primary: {value: base-setting}
+    secondary: {extends: primary}
+`)
+	filesystem := configkit.NewFilesystem("identified-bundle", fstest.MapFS{
+		"config/identified.yml": &fstest.MapFile{Data: input},
+		"config/icon.txt":       &fstest.MapFile{Data: []byte("identified-parent-resource")},
+	})
+	registrations := []configkit.SequenceIdentity{
+		configkit.SequenceIdentityAt(configkit.Keys("jobs"), "id"),
+	}
+	result, err := configkit.Load(filesystem.File("config/identified.yml"), configkit.Options[configuration]{
+		Definition: configkit.Definition[configuration]{
+			SequenceIdentities: registrations,
+			Secret: func(path configkit.Path) bool {
+				return path.String() == "/jobs/0/credential" || path.String() == "/jobs/1/credential" || path.String() == "/jobs/2/credential"
+			},
+		},
+	})
+	if err != nil {
+		if loadError, ok := err.(*configkit.LoadError); ok {
+			t.Fatalf("load identified inheritance: %v (%#v)", err, loadError.Diagnostics())
+		}
+		t.Fatal(err)
+	}
+	if len(result.Config.Jobs) != 3 || result.Config.Jobs[0].ID != "child" || result.Config.Jobs[1].ID != "parent" || result.Config.Jobs[2].ID != "base" {
+		t.Fatalf("inherited job positions and identities = %#v", result.Config.Jobs)
+	}
+	child := result.Config.Jobs[0]
+	if child.Name != "child-name" || child.Credential.Value() != canary || child.Resource != "icon.txt" || len(child.Steps) != 2 {
+		t.Fatalf("inherited child = %#v", child)
+	}
+	if got := []string{child.Steps[0].ID, child.Steps[1].ID}; strings.Join(got, ",") != "base-step,second-step" {
+		t.Fatalf("inherited nested steps = %v", got)
+	}
+	if child.Steps[0].Value != "base-step-value" || child.Steps[1].Value != "second-step-value" || child.Settings["secondary"]["value"] != "base-setting" {
+		t.Fatalf("inherited nested collection and mapping = %#v", child)
+	}
+	credentialPath := configkit.Keys("jobs").Index(0).Key("credential")
+	credentialInfo, found := result.Metadata().Lookup(credentialPath)
+	if !found || len(credentialInfo.Origin.Inheritance) != 2 {
+		t.Fatalf("inherited secret provenance = %#v, %v", credentialInfo, found)
+	}
+	resourceInfo, found := result.Metadata().Lookup(configkit.Keys("jobs").Index(0).Key("resource"))
+	if !found || len(resourceInfo.Origin.Inheritance) != 2 || len(resourceInfo.Origin.Locations) != 1 {
+		t.Fatalf("inherited resource provenance = %#v, %v", resourceInfo, found)
+	}
+	context, found := result.SourceContext(resourceInfo.Origin.Locations[0].SourceID)
+	if !found || context.BaseDir != "config" || context.FS == nil {
+		t.Fatalf("inherited resource context = %#v, %v", context, found)
+	}
+	resource, readErr := fs.ReadFile(context.FS, context.BaseDir+"/"+child.Resource)
+	if readErr != nil || string(resource) != "identified-parent-resource" {
+		t.Fatalf("inherited resource = %q, %v", resource, readErr)
+	}
+	resourceHistory, found := result.Explain(configkit.Keys("jobs").Index(0).Key("resource"))
+	if !found || len(resourceHistory.History) == 0 {
+		t.Fatalf("inherited resource history = %#v, %v", resourceHistory, found)
+	}
+	credentialHistory, found := result.Explain(credentialPath)
+	if !found || !credentialHistory.Effective.Redacted {
+		t.Fatalf("inherited secret explanation = %#v, %v", credentialHistory, found)
+	}
+	identityInfo, found := result.Metadata().Lookup(configkit.Keys("jobs").Index(0).Key("id"))
+	if !found || !identityInfo.Explicit || len(identityInfo.Origin.Inheritance) != 0 ||
+		len(identityInfo.Origin.Locations) != 1 {
+		t.Fatalf("child identity origin and presence = %#v, %v", identityInfo, found)
+	}
+	if _, found := result.Metadata().Lookup(configkit.Keys("jobs").Index(0).Key("extends")); found {
+		t.Fatal("identified record relationship remained in effective metadata")
+	}
+	var rendered bytes.Buffer
+	if err := result.WriteEffective(&rendered); err != nil || strings.Contains(rendered.String(), canary) || strings.Contains(rendered.String(), "extends:") {
+		t.Fatalf("effective inherited configuration = %q, %v", rendered.String(), err)
+	}
+}
+
+func TestFacadeIdentifiedInheritanceFailureDoesNotRevealSecretCanary(t *testing.T) {
+	const secretName = "CONFIGKIT_IDENTIFIED_INHERITANCE_FAILURE_SECRET"
+	const canary = "IDENTIFIED-INHERITANCE-FAILURE-CANARY"
+	t.Setenv(secretName, canary)
+	type job struct {
+		ID         string           `yaml:"id"`
+		Credential configkit.Secret `yaml:"credential"`
+	}
+	type configuration struct {
+		Jobs []job `yaml:"jobs"`
+	}
+	input := []byte(`jobs:
+- id: child
+  extends: {id: missing}
+  credential: CONFIGKIT_IDENTIFIED_INHERITANCE_FAILURE_SECRET
+`)
+	_, err := configkit.Load(configkit.Bytes("identified-failure.yml", input), configkit.Options[configuration]{
+		Definition: configkit.Definition[configuration]{
+			SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("jobs"), "id")},
+			Secret:             func(path configkit.Path) bool { return path.String() == "/jobs/0/credential" },
+		},
+	})
+	if err == nil || strings.Contains(err.Error(), canary) {
+		t.Fatalf("identified inheritance failure = %v; secret canary must remain undisclosed", err)
+	}
+}
+
+func TestFacadeLayeredIdentifiedInheritanceUsesSurvivingRecords(t *testing.T) {
+	policy := func(mode string) string {
+		return "configkit:\n  sequences:\n    - destination: [jobs]\n      key: id\n      mode: " + mode + "\n"
+	}
+	tests := []struct {
+		name        string
+		lower       string
+		higher      string
+		wantCode    configkit.Code
+		wantValue   string
+		wantSuccess bool
+	}{
+		{
+			name:      "upserted parent supplies its final payload",
+			lower:     policy("upsert") + "jobs: [{id: parent, value: lower}]\n",
+			higher:    policy("upsert") + "jobs: [{id: parent, value: higher}, {id: child, extends: {id: parent}}]\n",
+			wantValue: "higher", wantSuccess: true,
+		},
+		{
+			name:     "replacement removes a lower parent before lookup",
+			lower:    policy("upsert") + "jobs: [{id: parent, value: lower}]\n",
+			higher:   policy("replace") + "jobs: [{id: child, extends: {id: parent}}]\n",
+			wantCode: configkit.CodeInheritanceMissing,
+		},
+		{
+			name:      "upserted child without a directive replaces the invalid lower child",
+			lower:     policy("upsert") + "jobs: [{id: child, extends: {id: missing}, value: lower}]\n",
+			higher:    policy("upsert") + "jobs: [{id: child, value: higher}]\n",
+			wantValue: "higher", wantSuccess: true,
+		},
+		{
+			name:     "self-reference cannot resolve through a lower predecessor",
+			lower:    policy("upsert") + "jobs: [{id: parent, value: lower}]\n",
+			higher:   policy("upsert") + "jobs: [{id: parent, extends: {id: parent}, value: higher}]\n",
+			wantCode: configkit.CodeInheritanceCycle,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			result, err := configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main.yml", []byte(test.higher))}, configkit.LayeredOptions[map[string]any]{
+				Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("lower.yml", []byte(test.lower))}}}},
+			})
+			if test.wantSuccess {
+				if err != nil {
+					t.Fatal(err)
+				}
+				jobs, ok := result.Config["jobs"].([]any)
+				if !ok || len(jobs) == 0 {
+					t.Fatalf("assembled jobs = %#v", result.Config["jobs"])
+				}
+				child, ok := jobs[len(jobs)-1].(map[string]any)
+				if !ok || child["value"] != test.wantValue {
+					t.Fatalf("surviving record = %#v, want inherited value %q", jobs[len(jobs)-1], test.wantValue)
+				}
+				return
+			}
+			loadError, ok := err.(*configkit.LoadError)
+			if !ok {
+				t.Fatalf("load error = %v, want code %s", err, test.wantCode)
+			}
+			for _, diagnostic := range loadError.Diagnostics() {
+				if diagnostic.Code == test.wantCode {
+					return
+				}
+			}
+			t.Fatalf("load diagnostics = %#v, want code %s", loadError.Diagnostics(), test.wantCode)
+		})
+	}
+}
+
 func TestFacadeInheritanceLayeredPrecedenceAndSourceContext(t *testing.T) {
 	filesystem := configkit.NewFilesystem("bundle", fstest.MapFS{
 		"config/main.yml":          &fstest.MapFile{Data: []byte("entries: {child: {extends: parent}}\n")},
@@ -206,27 +414,24 @@ func TestFacadeInheritanceFailureStopsLaterCallbacks(t *testing.T) {
 	}
 }
 
-func TestFacadeInheritanceResolvesAfterImportsAndCLIReferenceChange(t *testing.T) {
+func TestFacadeCLIOverridesCannotChangeInheritanceRelationship(t *testing.T) {
 	filesystem := configkit.NewFilesystem("bundle", fstest.MapFS{
 		"main.yml":   &fstest.MapFile{Data: []byte("configkit: {imports: [{path: parent.yml}]}\nentries: {child: {extends: first}}\n")},
 		"parent.yml": &fstest.MapFile{Data: []byte("entries: {first: {count: 1}, second: {count: 2}}\n")},
 	})
-	result, err := configkit.Load(filesystem.File("main.yml"), configkit.Options[inheritedConfiguration]{
+	_, err := configkit.Load(filesystem.File("main.yml"), configkit.Options[inheritedConfiguration]{
 		Imports: true, Overrides: []configkit.Override{{Path: configkit.Keys("entries", "child", "extends"), Value: "second", Flag: "--extends"}},
 	})
-	if err != nil || result.Config.Entries["child"].Count != 2 {
-		t.Fatalf("import and CLI reference = %#v, %v", result, err)
-	}
-	history := result.Metadata().History(configkit.Keys("entries", "child", "extends"))
-	if len(history) < 3 || history[len(history)-1].Origin.Operation != configkit.ChangeInheritance {
-		t.Fatalf("superseded reference history = %#v", history)
+	loadError, ok := err.(*configkit.LoadError)
+	if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeOverrideDirective {
+		t.Fatalf("CLI inheritance relationship change = %v", err)
 	}
 	conflicting := configkit.NewFilesystem("bundle", fstest.MapFS{
 		"main.yml":   &fstest.MapFile{Data: []byte("configkit: {imports: [{path: parent.yml}]}\nentries: {child: {extends: first}, first: {count: 3}}\n")},
 		"parent.yml": &fstest.MapFile{Data: []byte("entries: {first: {count: 1}}\n")},
 	})
 	_, err = configkit.Load[inheritedConfiguration](conflicting.File("main.yml"), configkit.Options[inheritedConfiguration]{Imports: true})
-	loadError, ok := err.(*configkit.LoadError)
+	loadError, ok = err.(*configkit.LoadError)
 	if !ok || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != configkit.CodeComposeConflict {
 		t.Fatalf("strict conflict before expansion = %v", err)
 	}

facade_sequence_identity_test.go

@@ -0,0 +1,240 @@
+package configkit_test
+
+import (
+	"errors"
+	"strings"
+	"testing"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+func TestFacadeSequenceIdentitySnapshotsSelectorsAndFields(t *testing.T) {
+	fields := []string{"namespace", "id", "id"}
+	selector := configkit.SequenceSelector{
+		configkit.SequenceLiteralKey("collections"),
+		configkit.SequenceAnyMappingKey(),
+		configkit.SequenceLiteralKey("prompts"),
+	}
+	identity := configkit.SequenceIdentityMatching(selector, fields...)
+	selector[1] = configkit.SequenceLiteralKey("other")
+	fields[0] = "changed"
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{identity}}
+
+	underlay := configkit.Mapping("underlay", map[string]any{"collections": map[string]any{
+		"team": map[string]any{"prompts": []any{map[string]any{"namespace": "team", "id": "kept"}}},
+	}})
+	main := configkit.Mapping("main", map[string]any{"collections": map[string]any{
+		"team": map[string]any{"prompts": []any{map[string]any{"namespace": "team", "id": "added"}}},
+	}})
+	loaded, err := configkit.LoadLayered(configkit.Input{Source: main}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition,
+		Underlays:  []configkit.Underlay{{Inputs: []configkit.Input{{Source: underlay}}}},
+	})
+	if err != nil {
+		t.Fatalf("load after mutating constructor inputs: %v", err)
+	}
+	prompts := loaded.Config["collections"].(map[string]any)["team"].(map[string]any)["prompts"].([]any)
+	if len(prompts) != 2 {
+		t.Fatalf("registered compound identity did not append records: %#v", prompts)
+	}
+}
+
+func TestFacadeSequenceIdentityUsesExactAndDynamicSelectors(t *testing.T) {
+	dynamic := configkit.SequenceIdentityMatching(configkit.SequenceSelector{
+		configkit.SequenceLiteralKey("collections"),
+		configkit.SequenceAnyMappingKey(),
+		configkit.SequenceLiteralKey("prompts"),
+	}, "id")
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{
+		configkit.SequenceIdentityAt(configkit.Keys("prompts"), "namespace", "id"),
+		dynamic,
+	}}
+	underlay := configkit.Mapping("underlay", map[string]any{
+		"prompts": []any{map[string]any{"namespace": "alpha", "id": "same"}},
+		"collections": map[string]any{
+			"team":  map[string]any{"prompts": []any{map[string]any{"id": "team-one"}}},
+			"cloud": map[string]any{"prompts": []any{map[string]any{"id": "cloud-one"}}},
+		},
+	})
+	main := configkit.Mapping("main", map[string]any{
+		"prompts": []any{map[string]any{"namespace": "beta", "id": "same"}},
+		"collections": map[string]any{
+			"team":  map[string]any{"prompts": []any{map[string]any{"id": "team-two"}}},
+			"cloud": map[string]any{"prompts": []any{map[string]any{"id": "cloud-two"}}},
+		},
+	})
+	loaded, err := configkit.LoadLayered(configkit.Input{Source: main}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition,
+		Underlays:  []configkit.Underlay{{Inputs: []configkit.Input{{Source: underlay}}}},
+	})
+	if err != nil {
+		t.Fatalf("load mixed exact and dynamic registrations: %v", err)
+	}
+	rootRecords := loaded.Config["prompts"].([]any)
+	if len(rootRecords) != 2 {
+		t.Fatalf("compound root identities = %#v", rootRecords)
+	}
+	collections := loaded.Config["collections"].(map[string]any)
+	for _, name := range []string{"team", "cloud"} {
+		prompts := collections[name].(map[string]any)["prompts"].([]any)
+		if len(prompts) != 2 {
+			t.Errorf("dynamic prompts for %q = %#v", name, prompts)
+		}
+	}
+}
+
+func TestFacadeSequenceIdentityLiteralStarIsNotWildcard(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{
+		configkit.SequenceIdentityMatching(configkit.SequenceSelector{
+			configkit.SequenceLiteralKey("collections"),
+			configkit.SequenceLiteralKey("*"),
+			configkit.SequenceLiteralKey("prompts"),
+		}, "id"),
+	}}
+	underlay := configkit.Mapping("underlay", map[string]any{"collections": map[string]any{
+		"*":    map[string]any{"prompts": []any{map[string]any{"id": "one"}}},
+		"team": map[string]any{"prompts": []any{map[string]any{"id": "team-one"}}},
+	}})
+	main := configkit.Mapping("main", map[string]any{"collections": map[string]any{
+		"*":    map[string]any{"prompts": []any{map[string]any{"id": "two"}}},
+		"team": map[string]any{"prompts": []any{map[string]any{"id": "team-two"}}},
+	}})
+	_, err := configkit.LoadLayered(configkit.Input{Source: configkit.Mapping("main", map[string]any{})}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition,
+		Underlays:  []configkit.Underlay{{Inputs: []configkit.Input{{Source: underlay}, {Source: main}}}},
+	})
+	loadErr := requireFacadeLoadError(t, err)
+	if len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Path.String() != "/collections/team/prompts" {
+		t.Fatalf("literal star registration also matched another key: %#v", loadErr.Diagnostics())
+	}
+
+	wildcard := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{
+		configkit.SequenceIdentityMatching(configkit.SequenceSelector{
+			configkit.SequenceLiteralKey("collections"),
+			configkit.SequenceAnyMappingKey(),
+			configkit.SequenceLiteralKey("prompts"),
+		}, "id"),
+	}}
+	loaded, err := configkit.LoadLayered(configkit.Input{Source: configkit.Mapping("main", map[string]any{})}, configkit.LayeredOptions[map[string]any]{
+		Definition: wildcard,
+		Underlays:  []configkit.Underlay{{Inputs: []configkit.Input{{Source: underlay}, {Source: main}}}},
+	})
+	if err != nil {
+		t.Fatalf("wildcard registration did not match mapping keys: %v", err)
+	}
+	for name, raw := range loaded.Config["collections"].(map[string]any) {
+		if got := len(raw.(map[string]any)["prompts"].([]any)); got != 2 {
+			t.Errorf("wildcard result for %q has %d records", name, got)
+		}
+	}
+}
+
+func TestFacadeSequenceIdentityRejectsInvalidDefinitionsBeforeReadingSource(t *testing.T) {
+	tests := []struct {
+		name     string
+		identity configkit.SequenceIdentity
+		wantPath string
+	}{
+		{
+			name:     "index path",
+			identity: configkit.SequenceIdentityAt(configkit.Keys("records").Index(0), "id"),
+			wantPath: "/records/0",
+		},
+		{
+			name:     "empty fields",
+			identity: configkit.SequenceIdentityAt(configkit.Keys("records")),
+			wantPath: "/records",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			reader := strings.NewReader("records: []\n")
+			_, err := configkit.Load(configkit.Reader("input.yml", reader), configkit.Options[map[string]any]{
+				Definition: configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{test.identity}},
+			})
+			loadErr := requireFacadeLoadError(t, err)
+			if len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != configkit.CodeOptionsInvalid || loadErr.Diagnostics()[0].Path.String() != test.wantPath {
+				t.Fatalf("definition diagnostics = %#v", loadErr.Diagnostics())
+			}
+			if reader.Len() == 0 {
+				t.Fatal("source was read before registration validation")
+			}
+		})
+	}
+}
+
+func TestFacadeSequenceIdentityOverlapFailsBeforeSourceAccess(t *testing.T) {
+	selector := configkit.SequenceSelector{configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey()}
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{
+		configkit.SequenceIdentityMatching(selector, "id"),
+		configkit.SequenceIdentityMatching(configkit.SequenceSelector{
+			configkit.SequenceLiteralKey("collections"), configkit.SequenceLiteralKey("team"),
+		}, "slug"),
+	}}
+	reader := strings.NewReader("collections: {}\n")
+	_, err := configkit.Load(configkit.Reader("input.yml", reader), configkit.Options[map[string]any]{Definition: definition})
+	loadErr := requireFacadeLoadError(t, err)
+	if len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Code != configkit.CodeOptionsInvalid {
+		t.Fatalf("overlap diagnostics = %#v", loadErr.Diagnostics())
+	}
+	if reader.Len() == 0 {
+		t.Fatal("source was read before overlapping registrations were rejected")
+	}
+}
+
+func TestFacadeSequenceIdentityConstraintsApplyAtInheritedDestinations(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{
+		configkit.SequenceIdentityMatching(configkit.SequenceSelector{
+			configkit.SequenceLiteralKey("entries"),
+			configkit.SequenceLiteralKey("child"),
+			configkit.SequenceLiteralKey("collections"),
+			configkit.SequenceAnyMappingKey(),
+			configkit.SequenceLiteralKey("prompts"),
+		}, "id"),
+	}}
+	loaded, err := configkit.Load(configkit.Bytes("main", []byte(`jobs:
+entries:
+  parent:
+    collections:
+      team:
+        prompts: [{id: inherited, text: base}]
+  child:
+    extends: parent
+    collections:
+      team:
+        prompts: [{id: added, text: child}]
+`)), configkit.Options[map[string]any]{Definition: definition})
+	if err != nil {
+		t.Fatalf("load with dynamic inherited destination: %v", err)
+	}
+	child := loaded.Config["entries"].(map[string]any)["child"].(map[string]any)
+	prompts := child["collections"].(map[string]any)["team"].(map[string]any)["prompts"].([]any)
+	if len(prompts) != 2 {
+		t.Fatalf("inherited dynamic collection = %#v, want parent and child records", prompts)
+	}
+}
+
+func TestFacadeSequenceIdentityLoadsUseIndependentScopes(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{
+		configkit.SequenceIdentityMatching(configkit.SequenceSelector{
+			configkit.SequenceLiteralKey("collections"), configkit.SequenceAnyMappingKey(),
+		}, "id"),
+	}}
+	for _, source := range []string{"first", "second"} {
+		loaded, err := configkit.Load(configkit.Mapping(source, map[string]any{"collections": map[string]any{
+			source: []any{map[string]any{"id": "reused"}},
+		}}), configkit.Options[map[string]any]{Definition: definition})
+		if err != nil || len(loaded.Config["collections"].(map[string]any)[source].([]any)) != 1 {
+			t.Fatalf("independent load %q = %#v, %v", source, loaded, err)
+		}
+	}
+}
+
+func requireFacadeLoadError(t *testing.T, err error) *configkit.LoadError {
+	t.Helper()
+	var loadErr *configkit.LoadError
+	if !errors.As(err, &loadErr) {
+		t.Fatalf("error = %v, want *LoadError", err)
+	}
+	return loadErr
+}

facade_sequence_test.go

@@ -21,7 +21,7 @@ func TestFacadeNoSourcePreservesAbsenceWithSequencePolicy(t *testing.T) {
 				definition.Defaults = func() map[string]any { return map[string]any{"fallback": true} }
 			}
 			if registered {
-				definition.SequenceCompositions = []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}
+				definition.SequenceIdentities = []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("records"), "id")}
 			}
 			ordinary, err := configkit.Load(configkit.NoSource(), configkit.Options[map[string]any]{Definition: definition})
 			if err != nil {
@@ -63,7 +63,7 @@ func TestFacadeItemHelperHistoryPreservesScheduledPlacement(t *testing.T) {
 		"child-helper.yml": {Data: []byte("text: nested helper\n")},
 	})
 	result, err := configkit.Load(filesystem.File("main.yml"), configkit.Options[map[string]any]{
-		Imports: true, Definition: configkit.Definition[map[string]any]{SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}},
+		Imports: true, Definition: configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("records"), "id")}},
 	})
 	if err != nil {
 		t.Fatal(err)
@@ -107,8 +107,14 @@ func TestFacadeRegisteredReplacementExplainsRemovedDescendants(t *testing.T) {
 		{"removed field", []any{map[string]any{"id": "main"}}, configkit.Keys("records").Index(0).Key("text")},
 	} {
 		t.Run(test.name, func(t *testing.T) {
-			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Mapping("main", map[string]any{"records": test.upper})}, configkit.LayeredOptions[map[string]any]{
-				Definition: configkit.Definition[map[string]any]{SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}},
+			mainYAML := "configkit:\n  sequences:\n    - destination: [records]\n      key: id\n      mode: replace\n"
+			if len(test.upper) == 0 {
+				mainYAML += "records: []\n"
+			} else {
+				mainYAML += "records: [{id: main}]\n"
+			}
+			result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Bytes("main", []byte(mainYAML))}, configkit.LayeredOptions[map[string]any]{
+				Definition: configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("records"), "id")}},
 				Underlays:  []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Mapping("lower", map[string]any{"records": []any{map[string]any{"id": "one", "text": "old"}, map[string]any{"id": "two"}}})}}}},
 			})
 			if err != nil {
@@ -137,7 +143,7 @@ func TestFacadeItemConflictDiagnosticsFollowEnclosingIndexes(t *testing.T) {
 		"bad.yml":    {Data: []byte("id: bad\nconfigkit: {imports: [{path: helper.yml}]}\n")},
 		"helper.yml": {Data: []byte("id: duplicate-field\n")},
 	})
-	definition := configkit.Definition[map[string]any]{SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}}
+	definition := configkit.Definition[map[string]any]{SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("records"), "id")}}
 	for _, test := range []struct {
 		name, file, path  string
 		grouped, itemMain bool
@@ -194,7 +200,7 @@ func TestFacadeItemConflictDiagnosticsFollowEnclosingIndexes(t *testing.T) {
 
 func TestFacadeSequencePlacementControlsAcrossLoadEntryPoints(t *testing.T) {
 	definition := configkit.Definition[map[string]any]{
-		SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("entries"), IdentityField: "id"}},
+		SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("entries"), "id")},
 	}
 	ordinary, err := configkit.Load(configkit.Mapping("ordinary", map[string]any{"id": "one"}), configkit.Options[map[string]any]{
 		Definition: definition, Destination: configkit.Keys("entries"), PlacementMode: configkit.PlacementModeSequenceItem,
@@ -240,8 +246,8 @@ func TestFacadeSequencePlacementControlsAcrossLoadEntryPoints(t *testing.T) {
 	if err != nil {
 		t.Fatalf("registered sequence precedence load: %v", err)
 	}
-	if got := precedence.Config["entries"].([]any); len(got) != 1 || got[0].(map[string]any)["id"] != "main" {
-		t.Fatalf("higher-priority list did not replace the lower sequence: %#v", precedence.Config)
+	if got := precedence.Config["entries"].([]any); len(got) != 2 || got[0].(map[string]any)["id"] != "lower" || got[1].(map[string]any)["id"] != "main" {
+		t.Fatalf("registered upsert did not retain the lower sequence: %#v", precedence.Config)
 	}
 
 	for _, test := range []struct {
@@ -295,7 +301,7 @@ items:
 	result, err := configkit.Load(configkit.File(mainPath), configkit.Options[map[string]any]{
 		Imports: true,
 		Definition: configkit.Definition[map[string]any]{
-			SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("items"), IdentityField: "id"}},
+			SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "id")},
 			Resolve: func(_ *map[string]any, resolution *configkit.Resolution) error {
 				for _, id := range []string{"source-2", "source-3"} {
 					source, ok := resolution.Source(id)
@@ -455,15 +461,17 @@ func TestFacadeNestedItemFallbackUsesNearestResolvedContainer(t *testing.T) {
 	}
 }
 
-func TestFacadeSequenceCompositionRegistrationPathIsDetached(t *testing.T) {
-	registrations := []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}}
+func TestFacadeSequenceIdentityRegistrationIsDetached(t *testing.T) {
+	fields := []string{"id"}
+	path := configkit.Keys("records")
+	registration := configkit.SequenceIdentityAt(path, fields...)
+	fields[0] = "changed"
 	definition := configkit.Definition[map[string]any]{
-		SequenceCompositions: registrations,
+		SequenceIdentities: []configkit.SequenceIdentity{registration},
 		Version: &configkit.VersionRule{
 			Path: configkit.Keys("version"),
 			Check: func(configkit.Version, *configkit.Validation) error {
-				registrations[0].Path = configkit.Keys("other")
-				registrations[0].IdentityField = "changed"
+				path = configkit.Keys("other")
 				return nil
 			},
 		},
@@ -506,6 +514,31 @@ func TestFacadeSourceInfoPlacementCopiesAndZeroValues(t *testing.T) {
 	}
 }
 
+func TestLayeredSequenceUpsertHistoryRetainsLowerTierRecords(t *testing.T) {
+	definition := configkit.Definition[map[string]any]{
+		SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("entries"), "id")},
+	}
+	result, err := configkit.LoadLayered[map[string]any](configkit.Input{Source: configkit.Bytes("main", []byte("entries: [{id: main}]\n"))}, configkit.LayeredOptions[map[string]any]{
+		Definition: definition,
+		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{
+			Source: configkit.Bytes("lower", []byte("entries: [{id: lower}]\n")),
+		}}}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for index, id := range []string{"lower", "main"} {
+		path := configkit.Keys("entries").Index(index).Key("id")
+		explanation, ok := result.Explain(path)
+		if !ok || !explanation.Effective.Present || explanation.Effective.YAML != id+"\n" || len(explanation.History) == 0 {
+			t.Fatalf("tier history at %s = %#v, %v", path.String(), explanation, ok)
+		}
+		if explanation.History[len(explanation.History)-1].After.YAML != id+"\n" {
+			t.Fatalf("tier history at %s does not retain final record: %#v", path.String(), explanation.History)
+		}
+	}
+}
+
 func TestFacadeSequenceReplacementKeepsTypedAndHistoricalEvidenceAligned(t *testing.T) {
 	type record struct {
 		ID       string  `yaml:"id"`
@@ -523,7 +556,12 @@ func TestFacadeSequenceReplacementKeepsTypedAndHistoricalEvidenceAligned(t *test
 	directory := t.TempDir()
 	mainPath := filepath.Join(directory, "main.yml")
 	underlayPath := filepath.Join(directory, "underlay.yml")
-	if err := os.WriteFile(mainPath, []byte(`entries:
+	if err := os.WriteFile(mainPath, []byte(`configkit:
+  sequences:
+    - destination: [entries]
+      key: id
+      mode: replace
+entries:
   - id: current
     count: 0
     enabled: false
@@ -559,7 +597,7 @@ func TestFacadeSequenceReplacementKeepsTypedAndHistoricalEvidenceAligned(t *test
 	result, err := configkit.LoadLayered(configkit.Input{Source: configkit.File(mainPath)}, configkit.LayeredOptions[configuration]{
 		Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.File(underlayPath), Imports: true}}}},
 		Definition: configkit.Definition[configuration]{
-			SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("entries"), IdentityField: "id"}},
+			SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("entries"), "id")},
 			Secret: func(path configkit.Path) bool {
 				return path.String() == "/entries/0/token" || path.String() == "/entries/1/token"
 			},

facade_sequence_version_test.go

@@ -0,0 +1,197 @@
+package configkit_test
+
+import (
+	"fmt"
+	"testing"
+	"testing/fstest"
+
+	configkit "gitea.maximumdirect.net/eric/ConfigKit"
+)
+
+type movedVersionItem struct {
+	ID      string `yaml:"id"`
+	Version string `yaml:"version"`
+}
+
+type movedVersionCatalog struct {
+	Items []movedVersionItem `yaml:"items"`
+}
+
+func TestMainVersionDecodingFollowsSequenceMovement(t *testing.T) {
+	t.Parallel()
+	for _, mounted := range []bool{false, true} {
+		for _, matching := range []bool{false, true} {
+			for _, version := range []string{"4", "'4'"} {
+				t.Run(fmt.Sprintf("mounted=%t/matched=%t/%s", mounted, matching, version), func(t *testing.T) {
+					body := "items: [{id: main, version: " + version + "}]\n"
+					path := configkit.Keys("items").Index(0).Key("version")
+					main := configkit.Input{}
+					if mounted {
+						body, path = "id: main\nversion: "+version+"\n", configkit.Keys("version")
+						main.Destination, main.PlacementMode = configkit.Keys("items"), configkit.PlacementModeSequenceItem
+					}
+					main.Source = configkit.Bytes("main", []byte(body))
+					keep := "{id: keep}"
+					if mounted {
+						keep = "{id: keep, version: ordinary}"
+					}
+					lower := "items: [" + keep + "]\n"
+					if matching {
+						lower = "items: [" + keep + ", {id: main}]\n"
+					}
+					calls := 0
+					loaded, err := configkit.LoadLayered(main, configkit.LayeredOptions[movedVersionCatalog]{
+						SourceVersionMode: configkit.SourceVersionModeIfPresent,
+						Underlays:         []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("lower", []byte(lower))}}}},
+						Definition: configkit.Definition[movedVersionCatalog]{
+							SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "id")},
+							Version: &configkit.VersionRule{Path: path, Check: func(version configkit.Version, _ *configkit.Validation) error {
+								calls++
+								if !version.Present || version.Text != "4" {
+									t.Errorf("checked version = %#v", version)
+								}
+								return nil
+							}},
+						},
+					})
+					if err != nil {
+						t.Fatal(err)
+					}
+					if calls != 1 || len(loaded.Config.Items) != 2 || loaded.Config.Items[1].ID != "main" || loaded.Config.Items[1].Version != "4" {
+						t.Fatalf("moved main = %#v, checker calls = %d", loaded.Config, calls)
+					}
+					if mounted && loaded.Config.Items[0].Version != "ordinary" {
+						t.Fatal("unrelated underlay payload was treated as the main declaration")
+					}
+					for _, source := range loaded.Sources() {
+						if source.Layer == configkit.LayerBase && source.VersionCheck.Path.String() != path.String() {
+							t.Fatal("effective movement changed source-local version evidence")
+						}
+					}
+				})
+			}
+		}
+	}
+}
+
+func TestOverlayVersionProtectionUsesAssignedRecordPositions(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name, payload string
+		code          configkit.Code
+	}{
+		{name: "change main header", payload: "[{id: main, version: changed}]", code: configkit.CodeOverlayVersion},
+		{name: "remove main header", payload: "[{id: main}]", code: configkit.CodeOverlayVersion},
+		{name: "other record version", payload: "[{id: keep, version: ordinary}]"},
+		{name: "new record version", payload: "[{id: new, version: ordinary}]"},
+		{name: "only main header gets integer conversion", payload: "[{id: new, version: 5}]", code: configkit.CodeDecodeType},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			files := configkit.NewFilesystem("catalog", fstest.MapFS{
+				"overlays/test.yml": {Data: []byte("items: " + test.payload + "\n")},
+			})
+			calls := 0
+			loaded, err := configkit.LoadLayered(configkit.Input{
+				Source: configkit.Bytes("main", []byte("id: main\nversion: 4\n")), Destination: configkit.Keys("items"), PlacementMode: configkit.PlacementModeSequenceItem,
+			}, configkit.LayeredOptions[movedVersionCatalog]{
+				SourceVersionMode: configkit.SourceVersionModeIfPresent,
+				Overlay:           "test", OverlayFilesystem: &configkit.FilesystemContext{FS: &files, BaseDir: ".", Root: "."},
+				Underlays: []configkit.Underlay{{Inputs: []configkit.Input{{Source: configkit.Bytes("lower", []byte("items: [{id: keep}]\n"))}}}},
+				Definition: configkit.Definition[movedVersionCatalog]{
+					SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "id")},
+					Version:            &configkit.VersionRule{Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { calls++; return nil }},
+				},
+			})
+			if calls != 1 {
+				t.Fatalf("checker calls = %d", calls)
+			}
+			if test.code != "" {
+				loadErr := requireFacadeLoadError(t, err)
+				if loaded != nil || len(loadErr.Diagnostics()) != 1 || loadErr.Diagnostics()[0].Code != test.code {
+					t.Fatalf("version diagnostics = %#v", loadErr.Diagnostics())
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if loaded.Config.Items[1].Version != "4" {
+				t.Fatal("unrelated overlay changed main header")
+			}
+		})
+	}
+}
+
+func TestUnderlayVersionProtectionUsesMainRecordPosition(t *testing.T) {
+	t.Parallel()
+	for _, imported := range []bool{false, true} {
+		t.Run(fmt.Sprintf("imported=%t", imported), func(t *testing.T) {
+			payload := "items: [{id: keep}, {id: main, version: forbidden}]\n"
+			lower := configkit.Input{Source: configkit.Bytes("lower", []byte(payload))}
+			want := configkit.CodeUnderlayVersion
+			if imported {
+				files := configkit.NewFilesystem("lower", fstest.MapFS{
+					"main.yml":     {Data: []byte("configkit: {imports: [{path: fragment.yml}]}\n")},
+					"fragment.yml": {Data: []byte(payload)},
+				})
+				lower.Source, lower.Imports = files.File("main.yml"), true
+				want = configkit.CodeImportVersion
+			}
+			calls := 0
+			result, err := configkit.LoadLayered(configkit.Input{
+				Source:      configkit.Bytes("main", []byte("id: main\nversion: 4\n")),
+				Destination: configkit.Keys("items"), PlacementMode: configkit.PlacementModeSequenceItem,
+			}, configkit.LayeredOptions[movedVersionCatalog]{
+				SourceVersionMode: configkit.SourceVersionModeIfPresent,
+				Underlays:         []configkit.Underlay{{Inputs: []configkit.Input{lower}}},
+				Definition: configkit.Definition[movedVersionCatalog]{
+					SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("items"), "id")},
+					Version:            &configkit.VersionRule{Path: configkit.Keys("version"), Check: func(configkit.Version, *configkit.Validation) error { calls++; return nil }},
+				},
+			})
+			failure := requireFacadeLoadError(t, err)
+			if result != nil || calls != 1 || len(failure.Diagnostics()) != 1 || failure.Diagnostics()[0].Code != want || failure.Diagnostics()[0].Path.String() != "/items/1/version" {
+				t.Fatalf("result=%#v calls=%d diagnostics=%#v", result, calls, failure.Diagnostics())
+			}
+		})
+	}
+}
+
+func TestMainVersionFollowsInheritedSequenceMovement(t *testing.T) {
+	t.Parallel()
+	for _, parentID := range []string{"keep", "main"} {
+		t.Run(parentID, func(t *testing.T) {
+			body := "base: {items: [{id: " + parentID + ", version: ordinary}]}\nchild:\n  extends: base\n  items: [{id: main, version: 4}]\n"
+			type config struct {
+				Base, Child movedVersionCatalog
+			}
+			calls := 0
+			result, err := configkit.Load(configkit.Bytes("main", []byte(body)), configkit.Options[config]{
+				SourceVersionMode: configkit.SourceVersionModeIfPresent,
+				Definition: configkit.Definition[config]{
+					SequenceIdentities: []configkit.SequenceIdentity{
+						configkit.SequenceIdentityAt(configkit.Keys("base", "items"), "id"),
+						configkit.SequenceIdentityAt(configkit.Keys("child", "items"), "id"),
+					},
+					Version: &configkit.VersionRule{Path: configkit.Keys("child", "items").Index(0).Key("version"), Check: func(configkit.Version, *configkit.Validation) error { calls++; return nil }},
+				},
+			})
+			if calls != 1 {
+				t.Fatalf("checker calls = %d", calls)
+			}
+			if parentID == "main" {
+				failure := requireFacadeLoadError(t, err)
+				if result != nil || len(failure.Diagnostics()) != 1 || failure.Diagnostics()[0].Code != configkit.CodeInheritanceVersion {
+					t.Fatalf("diagnostics = %#v", failure.Diagnostics())
+				}
+				return
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(result.Config.Child.Items) != 2 || result.Config.Child.Items[1].Version != "4" || result.Config.Child.Items[0].Version != "ordinary" {
+				t.Fatalf("inherited items = %#v", result.Config.Child.Items)
+			}
+		})
+	}
+}

facade_source_version_mode_test.go

@@ -23,9 +23,9 @@ func TestFacadeSourceVersionEvidenceFollowsAssembledSequenceRanges(t *testing.T)
 		for _, sensitivePath := range []string{"", fmt.Sprintf("/records/%d/version", index), fmt.Sprintf("/records/%d", index)} {
 			t.Run(fmt.Sprintf("grouped=%t/secret=%s", grouped, sensitivePath), func(t *testing.T) {
 				definition := configkit.Definition[map[string]any]{
-					SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}},
-					Version:              &configkit.VersionRule{Path: configkit.Keys("records").Index(0).Key("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil }},
-					Secret:               func(path configkit.Path) bool { return sensitivePath != "" && path.String() == sensitivePath },
+					SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("records"), "id")},
+					Version:            &configkit.VersionRule{Path: configkit.Keys("records").Index(0).Key("version"), Check: func(configkit.Version, *configkit.Validation) error { return nil }},
+					Secret:             func(path configkit.Path) bool { return sensitivePath != "" && path.String() == sensitivePath },
 				}
 				first := "records: [{id: first, version: first-version}]\n"
 				child := "records: [{id: child, version: PRIVATE-VERSION-CANARY}]\n"
@@ -86,8 +86,8 @@ func TestFacadeSourceVersionOwnershipAcceptsContextualIndexes(t *testing.T) {
 	for _, grouped := range []bool{false, true} {
 		for _, path := range []configkit.Path{configkit.Keys("records").Index(0).Key("version"), parsed} {
 			definition := configkit.Definition[map[string]any]{
-				SequenceCompositions: []configkit.SequenceComposition{{Path: configkit.Keys("records"), IdentityField: "id"}},
-				Version:              &configkit.VersionRule{Path: path, Check: func(configkit.Version, *configkit.Validation) error { return nil }},
+				SequenceIdentities: []configkit.SequenceIdentity{configkit.SequenceIdentityAt(configkit.Keys("records"), "id")},
+				Version:            &configkit.VersionRule{Path: path, Check: func(configkit.Version, *configkit.Validation) error { return nil }},
 			}
 			first := "records: [{id: first, version: first}]\n"
 			child := "records: [{id: child, version: child}]\n"
@@ -104,11 +104,7 @@ func TestFacadeSourceVersionOwnershipAcceptsContextualIndexes(t *testing.T) {
 			if err != nil || result == nil {
 				t.Fatalf("grouped=%t path=%#v: %v", grouped, path, err)
 			}
-			want := 2
-			if grouped {
-				want = 1
-			}
-			if len(result.Config["records"].([]any)) != want {
+			if len(result.Config["records"].([]any)) != 2 {
 				t.Fatal("version path changed composition")
 			}
 		}

internal/engine/collection_ancestor_test.go

@@ -0,0 +1,106 @@
+package engine
+
+import (
+	"errors"
+	"fmt"
+	"testing"
+	"testing/fstest"
+)
+
+func TestNestedCollectionInitializationIsIndependentOfAncestorPresence(t *testing.T) {
+	t.Parallel()
+	for _, ancestor := range []string{"{}", "group: {}", "group: null"} {
+		for _, test := range []struct {
+			mode, key, value string
+			valid            bool
+		}{
+			{mode: "append", value: "[{id: a}]"},
+			{mode: "upsert", value: "[{id: a}]"},
+			{mode: "append", value: "[]"},
+			{mode: "upsert", value: "[]"},
+			{mode: "append", key: ", key: id", value: "{}"},
+			{mode: "upsert", key: ", key: id", value: "null"},
+			{mode: "append", key: ", key: id", value: "[{id: a}]", valid: true},
+			{mode: "upsert", key: ", key: id", value: "[]", valid: true},
+		} {
+			t.Run(fmt.Sprintf("%s/%s/%s/%s", ancestor, test.mode, test.key, test.value), func(t *testing.T) {
+				main := "configkit:\n  sequences: [{destination: [group, items], mode: " + test.mode + test.key + "}]\ngroup: {items: " + test.value + "}\n"
+				loaded, err := testGroupedLoad(loadRequest[map[string]any]{
+					main:      loadInput{source: Bytes("main", []byte(main))},
+					underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte(ancestor))}}}},
+				})
+				if test.valid {
+					if err != nil || loaded == nil {
+						t.Fatalf("valid initialization failed: %v", err)
+					}
+					return
+				}
+				var loadErr *LoadError
+				if !errors.As(err, &loadErr) || loaded != nil {
+					t.Fatalf("invalid collection operation succeeded: %#v, %v", loaded, err)
+				}
+				diagnostics := loadErr.Diagnostics()
+				if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != "/group/items" {
+					t.Fatalf("operation diagnostics = %#v", diagnostics)
+				}
+			})
+		}
+	}
+}
+
+func TestAddedAncestorTransfersNestedRecordPolicies(t *testing.T) {
+	t.Parallel()
+	type record struct {
+		ID    string           `yaml:"id"`
+		Steps []map[string]any `yaml:"steps"`
+	}
+	type config struct {
+		Group struct {
+			Items []record `yaml:"items"`
+		} `yaml:"group"`
+	}
+	files := fstest.MapFS{
+		"main.yml": {Data: []byte(`configkit:
+  sequences: [{destination: [group, items], key: id}]
+  imports: [{path: base.yml, destination: [group, items], placement: sequence-item}]
+group:
+  items: [{id: child, extends: {id: base}, steps: [{name: child}]}]
+`)},
+		"base.yml": {Data: []byte("configkit:\n  sequences: [{destination: [steps], key: name}]\nid: base\nsteps: [{name: base}]\n")},
+	}
+	loaded, err := testGroupedLoad(loadRequest[config]{
+		main:      loadInput{source: NewFilesystem("catalog", files).File("main.yml"), imports: true},
+		underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte("{}"))}}}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, item := range loaded.Config.Group.Items {
+		if item.ID == "child" {
+			if len(item.Steps) != 2 || item.Steps[0]["name"] != "base" || item.Steps[1]["name"] != "child" {
+				t.Fatalf("record-local identity was lost when adding its ancestor: %#v", item.Steps)
+			}
+			return
+		}
+	}
+	t.Fatal("missing child record")
+}
+
+func TestInheritanceChecksCollectionOperationUnderAddedAncestor(t *testing.T) {
+	t.Parallel()
+	_, err := testLoad[map[string]any](Bytes("inheritance", []byte(`configkit:
+  sequences: [{destination: [child, group, items], mode: append}]
+base: {}
+child:
+  extends: base
+  group: {items: [{id: a}]}
+`)))
+	var loadErr *LoadError
+	if !errors.As(err, &loadErr) {
+		t.Fatalf("missing nested operation error: %v", err)
+	}
+	diagnostics := loadErr.Diagnostics()
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != "/child/group/items" {
+		t.Fatalf("nested inheritance operation diagnostics = %#v", diagnostics)
+	}
+}

internal/engine/collection_policy.go

@@ -0,0 +1,209 @@
+package engine
+
+type collectionPolicy struct {
+	identityFields      []string
+	identityPresent     bool
+	identityLocation    *Location
+	explicitMode        sequenceMode
+	explicitModePresent bool
+	modeLocation        *Location
+	recordOrder         []*collectionRecordOwner
+	recordPolicies      map[*collectionRecordOwner]collectionPolicyScope
+}
+
+type collectionPolicyResolution struct {
+	policy                     collectionPolicy
+	operation                  sequenceMode
+	declarations               []sequenceDeclarationSpec
+	declarationsPresent        bool
+	identityDeclarationPresent bool
+	modeDeclarationPresent     bool
+	applicationIdentityFields  []string
+	applicationIdentityPresent bool
+	effectiveIdentityFields    []string
+}
+
+// resolveCollectionPolicy reconciles declarations for one destination before
+// peers are composed. The caller supplies only lower policy that is applicable
+// to this destination; record survival and ownership are resolved elsewhere.
+func resolveCollectionPolicy(
+	destination Path,
+	declarations []sequenceDeclarationSpec,
+	applicationIdentityFields []string,
+	lower *collectionPolicy,
+) (collectionPolicyResolution, []Diagnostic) {
+	normalizedDeclarations := cloneSequenceDeclarations(declarations)
+	for index := range normalizedDeclarations {
+		declaration := &normalizedDeclarations[index]
+		if !declaration.identityPresent {
+			continue
+		}
+		fields, err := normalizeSequenceIdentityFields(declaration.identityFields)
+		if err != nil {
+			return collectionPolicyResolution{}, []Diagnostic{{
+				Code: CodeSequenceInvalid, Severity: SeverityError, Path: destination.clone(),
+				Message: "collection identity declaration requires at least one field",
+				Primary: collectionDeclarationLocation(declaration.identityLocation, declaration.location),
+			}}
+		}
+		declaration.identityFields = fields
+	}
+	normalizedApplicationIdentityFields := cloneStrings(applicationIdentityFields)
+	if len(applicationIdentityFields) != 0 {
+		var err error
+		normalizedApplicationIdentityFields, err = normalizeSequenceIdentityFields(applicationIdentityFields)
+		if err != nil {
+			return collectionPolicyResolution{}, []Diagnostic{{
+				Code: CodeOptionsInvalid, Severity: SeverityError, Path: destination.clone(),
+				Message: "application collection identity fields are invalid",
+			}}
+		}
+	}
+	result := collectionPolicyResolution{
+		declarations:               normalizedDeclarations,
+		declarationsPresent:        len(normalizedDeclarations) != 0,
+		applicationIdentityFields:  normalizedApplicationIdentityFields,
+		applicationIdentityPresent: len(normalizedApplicationIdentityFields) != 0,
+	}
+
+	var diagnostics []Diagnostic
+	var declaredIdentityFields []string
+	var declaredIdentityLocation *Location
+	var declaredMode sequenceMode
+	var declaredModeLocation *Location
+	for _, declaration := range normalizedDeclarations {
+		if declaration.identityPresent {
+			result.identityDeclarationPresent = true
+			if declaredIdentityFields == nil {
+				declaredIdentityFields = cloneStrings(declaration.identityFields)
+				declaredIdentityLocation = collectionDeclarationLocation(declaration.identityLocation, declaration.location)
+			} else if !equalSequenceIdentityFields(declaredIdentityFields, declaration.identityFields) {
+				diagnostics = append(diagnostics, collectionPolicyConflictDiagnostic(
+					destination, declaredIdentityLocation,
+					collectionDeclarationLocation(declaration.identityLocation, declaration.location),
+					"collection identity declarations conflict",
+				))
+			}
+		}
+		if declaration.modePresent {
+			result.modeDeclarationPresent = true
+			if declaredMode == 0 {
+				declaredMode = declaration.mode
+				declaredModeLocation = collectionDeclarationLocation(declaration.modeLocation, declaration.location)
+			} else if declaredMode != declaration.mode {
+				diagnostics = append(diagnostics, collectionPolicyConflictDiagnostic(
+					destination, declaredModeLocation,
+					collectionDeclarationLocation(declaration.modeLocation, declaration.location),
+					"collection operation declarations conflict",
+				))
+			}
+		}
+	}
+	if len(diagnostics) != 0 {
+		return collectionPolicyResolution{}, canonicalDiagnostics(diagnostics)
+	}
+
+	if lower != nil && lower.identityPresent && declaredIdentityFields != nil && !equalSequenceIdentityFields(lower.identityFields, declaredIdentityFields) {
+		diagnostics = append(diagnostics, collectionPolicyConflictDiagnostic(
+			destination, declaredIdentityLocation,
+			collectionDeclarationLocation(lower.identityLocation, Location{}),
+			"collection identity declaration conflicts with retained identity",
+		))
+	}
+	if result.applicationIdentityPresent {
+		if declaredIdentityFields != nil && !equalSequenceIdentityFields(normalizedApplicationIdentityFields, declaredIdentityFields) {
+			diagnostics = append(diagnostics, collectionPolicyConflictDiagnostic(
+				destination, declaredIdentityLocation, nil,
+				"collection identity declaration conflicts with application constraint",
+			))
+		}
+		if lower != nil && lower.identityPresent && !equalSequenceIdentityFields(normalizedApplicationIdentityFields, lower.identityFields) {
+			diagnostics = append(diagnostics, collectionPolicyConflictDiagnostic(
+				destination, declaredIdentityLocation,
+				collectionDeclarationLocation(lower.identityLocation, Location{}),
+				"retained collection identity conflicts with application constraint",
+			))
+		}
+	}
+	if len(diagnostics) != 0 {
+		return collectionPolicyResolution{}, canonicalDiagnostics(diagnostics)
+	}
+
+	if declaredIdentityFields != nil {
+		result.policy.identityFields = declaredIdentityFields
+		result.policy.identityPresent = true
+		result.policy.identityLocation = cloneLocation(declaredIdentityLocation)
+	} else if lower != nil && lower.identityPresent {
+		result.policy.identityFields = cloneStrings(lower.identityFields)
+		result.policy.identityPresent = true
+		result.policy.identityLocation = cloneLocation(lower.identityLocation)
+	}
+	if result.applicationIdentityPresent {
+		result.effectiveIdentityFields = cloneStrings(normalizedApplicationIdentityFields)
+	} else if result.policy.identityPresent {
+		result.effectiveIdentityFields = cloneStrings(result.policy.identityFields)
+	}
+
+	if result.modeDeclarationPresent {
+		result.policy.explicitMode = declaredMode
+		result.policy.explicitModePresent = true
+		result.policy.modeLocation = cloneLocation(declaredModeLocation)
+	} else if lower != nil && lower.explicitModePresent {
+		result.policy.explicitMode = lower.explicitMode
+		result.policy.explicitModePresent = true
+		result.policy.modeLocation = cloneLocation(lower.modeLocation)
+	}
+	result.operation = collectionOperationMode(declaredMode, result.policy.explicitMode, len(result.effectiveIdentityFields) != 0)
+
+	return result, nil
+}
+
+func collectionOperationMode(current, retained sequenceMode, identified bool) sequenceMode {
+	if current != 0 {
+		return current
+	}
+	if retained != 0 {
+		return retained
+	}
+	if identified {
+		return sequenceModeUpsert
+	}
+	return sequenceModeReplace
+}
+
+func cloneSequenceDeclarations(declarations []sequenceDeclarationSpec) []sequenceDeclarationSpec {
+	if declarations == nil {
+		return nil
+	}
+	cloned := make([]sequenceDeclarationSpec, len(declarations))
+	for index, declaration := range declarations {
+		cloned[index] = declaration
+		cloned[index].path = declaration.path.clone()
+		cloned[index].destination = declaration.destination.clone()
+		cloned[index].identityFields = cloneStrings(declaration.identityFields)
+		cloned[index].identityLocation = cloneLocation(declaration.identityLocation)
+		cloned[index].modeLocation = cloneLocation(declaration.modeLocation)
+	}
+	return cloned
+}
+
+func collectionDeclarationLocation(specific *Location, fallback Location) *Location {
+	if specific != nil {
+		return cloneLocation(specific)
+	}
+	if fallback != (Location{}) {
+		return cloneLocation(&fallback)
+	}
+	return nil
+}
+
+func collectionPolicyConflictDiagnostic(path Path, primary, related *Location, message string) Diagnostic {
+	diagnostic := Diagnostic{
+		Code: CodeSequenceConflict, Severity: SeverityError,
+		Path: path.clone(), Message: message, Primary: cloneLocation(primary),
+	}
+	if related != nil {
+		diagnostic.Related = []Location{*cloneLocation(related)}
+	}
+	return diagnostic
+}

internal/engine/collection_policy_state.go

@@ -0,0 +1,258 @@
+package engine
+
+import (
+	"sort"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+type collectionPolicyScope struct {
+	collections map[string]collectionPolicyEntry
+}
+
+type collectionPolicyEntry struct {
+	destination Path
+	policy      collectionPolicy
+}
+
+type collectionRecordPolicy struct {
+	owner *collectionRecordOwner
+	scope collectionPolicyScope
+}
+
+// The nonzero field ensures simultaneously live record owners have distinct
+// addresses. The token is per-record ownership, not a source or identity key.
+type collectionRecordOwner struct {
+	marker byte
+}
+
+type projectedCollectionPolicy struct {
+	path   Path
+	policy collectionPolicy
+}
+
+func newCollectionRecordPolicy() collectionRecordPolicy {
+	return collectionRecordPolicy{owner: &collectionRecordOwner{marker: 1}}
+}
+
+func retainedCollectionRecordPolicy(record collectionRecordPolicy) collectionRecordPolicy {
+	return collectionRecordPolicy{
+		owner: record.owner,
+		scope: cloneCollectionPolicyScope(record.scope),
+	}
+}
+
+func replacedCollectionRecordPolicy() collectionRecordPolicy {
+	return newCollectionRecordPolicy()
+}
+
+func (policy *collectionPolicy) setRecordPolicy(record collectionRecordPolicy) {
+	if record.owner == nil {
+		record.owner = newCollectionRecordPolicy().owner
+	}
+	if policy.recordPolicies == nil {
+		policy.recordPolicies = make(map[*collectionRecordOwner]collectionPolicyScope)
+	}
+	if _, exists := policy.recordPolicies[record.owner]; !exists {
+		policy.recordOrder = append(policy.recordOrder, record.owner)
+	}
+	policy.recordPolicies[record.owner] = cloneCollectionPolicyScope(record.scope)
+}
+
+func (policy *collectionPolicy) setRecordPolicyAt(index int, record collectionRecordPolicy) {
+	if index < 0 {
+		return
+	}
+	if record.owner == nil {
+		record.owner = newCollectionRecordPolicy().owner
+	}
+	if policy.recordPolicies == nil {
+		policy.recordPolicies = make(map[*collectionRecordOwner]collectionPolicyScope)
+	}
+	for len(policy.recordOrder) <= index {
+		owner := newCollectionRecordPolicy().owner
+		policy.recordOrder = append(policy.recordOrder, owner)
+		policy.recordPolicies[owner] = collectionPolicyScope{}
+	}
+	delete(policy.recordPolicies, policy.recordOrder[index])
+	policy.recordOrder[index] = record.owner
+	policy.recordPolicies[record.owner] = cloneCollectionPolicyScope(record.scope)
+}
+
+func (policy collectionPolicy) recordPolicyAt(index int) (collectionRecordPolicy, bool) {
+	if index < 0 || index >= len(policy.recordOrder) {
+		return collectionRecordPolicy{}, false
+	}
+	owner := policy.recordOrder[index]
+	scope, ok := policy.recordPolicies[owner]
+	if !ok {
+		return collectionRecordPolicy{}, false
+	}
+	return collectionRecordPolicy{owner: owner, scope: cloneCollectionPolicyScope(scope)}, true
+}
+
+func collectionPolicyForReplacement(lower *collectionPolicy, current collectionPolicy) collectionPolicy {
+	result := cloneCollectionPolicy(current)
+	if !current.explicitModePresent && lower != nil && lower.explicitModePresent {
+		result.explicitMode = lower.explicitMode
+		result.explicitModePresent = true
+		result.modeLocation = cloneLocation(lower.modeLocation)
+	}
+	return result
+}
+
+// collectionPolicyWithoutValue keeps identity and record ownership because no
+// collection value was replaced. A key-only declaration can remain pending
+// when no sequence is present, or validate the retained sequence immediately.
+func collectionPolicyWithoutValue(
+	lower *collectionPolicy,
+	current collectionPolicy,
+	retainedValue *document.Node,
+	path Path,
+) (collectionPolicy, []Diagnostic) {
+	result := collectionPolicy{}
+	if lower != nil {
+		result = cloneCollectionPolicy(*lower)
+	}
+	if lower != nil && lower.identityPresent && current.identityPresent && !equalSequenceIdentityFields(lower.identityFields, current.identityFields) {
+		return collectionPolicy{}, []Diagnostic{collectionPolicyConflictDiagnostic(
+			path, current.identityLocation, lower.identityLocation,
+			"collection identity declaration conflicts with retained identity",
+		)}
+	}
+	if current.identityPresent {
+		result.identityFields = cloneStrings(current.identityFields)
+		result.identityPresent = true
+		result.identityLocation = cloneLocation(current.identityLocation)
+	}
+	if current.explicitModePresent {
+		result.explicitMode = current.explicitMode
+		result.explicitModePresent = true
+		result.modeLocation = cloneLocation(current.modeLocation)
+	}
+	if current.identityPresent && retainedValue != nil && retainedValue.Kind == document.Sequence {
+		_, diagnostics := validateSequenceIdentity(retainedValue, path, result.identityFields, sequenceIdentityDiagnosticCodes{
+			invalid: CodeSequenceInvalid, conflict: CodeSequenceConflict,
+		})
+		if len(diagnostics) != 0 {
+			return collectionPolicy{}, diagnostics
+		}
+	}
+	return result, nil
+}
+
+func (scope *collectionPolicyScope) set(destination Path, policy collectionPolicy) {
+	if scope.collections == nil {
+		scope.collections = make(map[string]collectionPolicyEntry)
+	}
+	scope.collections[destination.String()] = collectionPolicyEntry{
+		destination: destination.clone(), policy: cloneCollectionPolicy(policy),
+	}
+}
+
+func (scope collectionPolicyScope) at(destination Path) (collectionPolicy, bool) {
+	entry, ok := scope.collections[destination.String()]
+	if !ok {
+		return collectionPolicy{}, false
+	}
+	return cloneCollectionPolicy(entry.policy), true
+}
+
+// retireCollectionPoliciesAtOrBelow clears YAML identity and record-owned state
+// below a replaced ancestor while retaining independently scoped explicit modes.
+func (scope *collectionPolicyScope) retireCollectionPoliciesAtOrBelow(ancestor Path) {
+	if scope == nil {
+		return
+	}
+	for key, entry := range scope.collections {
+		if !pathHasPrefix(entry.destination, ancestor) {
+			continue
+		}
+		clearCollectionIdentity(&entry.policy)
+		scope.collections[key] = entry
+	}
+}
+
+func projectCollectionPolicyScope(scope collectionPolicyScope, prefix Path) []projectedCollectionPolicy {
+	keys := make([]string, 0, len(scope.collections))
+	for key := range scope.collections {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	var projected []projectedCollectionPolicy
+	for _, key := range keys {
+		entry := scope.collections[key]
+		concrete := appendDestination(prefix, entry.destination)
+		projected = append(projected, projectedCollectionPolicy{path: concrete, policy: cloneCollectionPolicy(entry.policy)})
+		for index, owner := range entry.policy.recordOrder {
+			if recordScope, ok := entry.policy.recordPolicies[owner]; ok {
+				projected = append(projected, projectCollectionPolicyScope(recordScope, concrete.Index(index))...)
+			}
+		}
+	}
+	return projected
+}
+
+func cloneCollectionPolicyScope(scope collectionPolicyScope) collectionPolicyScope {
+	if scope.collections == nil {
+		return collectionPolicyScope{}
+	}
+	cloned := collectionPolicyScope{collections: make(map[string]collectionPolicyEntry, len(scope.collections))}
+	for key, entry := range scope.collections {
+		cloned.collections[key] = collectionPolicyEntry{
+			destination: entry.destination.clone(), policy: cloneCollectionPolicy(entry.policy),
+		}
+	}
+	return cloned
+}
+
+func cloneCollectionPolicyScopeForInheritance(scope collectionPolicyScope) collectionPolicyScope {
+	if scope.collections == nil {
+		return collectionPolicyScope{}
+	}
+	cloned := collectionPolicyScope{collections: make(map[string]collectionPolicyEntry, len(scope.collections))}
+	for key, entry := range scope.collections {
+		cloned.collections[key] = collectionPolicyEntry{
+			destination: entry.destination.clone(), policy: cloneCollectionPolicyForInheritance(entry.policy),
+		}
+	}
+	return cloned
+}
+
+func cloneCollectionPolicy(policy collectionPolicy) collectionPolicy {
+	cloned := policy
+	cloned.identityFields = cloneStrings(policy.identityFields)
+	cloned.identityLocation = cloneLocation(policy.identityLocation)
+	cloned.modeLocation = cloneLocation(policy.modeLocation)
+	if policy.recordOrder != nil {
+		cloned.recordOrder = append([]*collectionRecordOwner(nil), policy.recordOrder...)
+	}
+	if policy.recordPolicies != nil {
+		cloned.recordPolicies = make(map[*collectionRecordOwner]collectionPolicyScope, len(policy.recordPolicies))
+		for owner, scope := range policy.recordPolicies {
+			cloned.recordPolicies[owner] = cloneCollectionPolicyScope(scope)
+		}
+	}
+	return cloned
+}
+
+func cloneCollectionPolicyForInheritance(policy collectionPolicy) collectionPolicy {
+	cloned := policy
+	cloned.identityFields = cloneStrings(policy.identityFields)
+	cloned.identityLocation = cloneLocation(policy.identityLocation)
+	cloned.modeLocation = cloneLocation(policy.modeLocation)
+	if policy.recordOrder != nil {
+		cloned.recordOrder = make([]*collectionRecordOwner, 0, len(policy.recordOrder))
+	}
+	if policy.recordPolicies != nil {
+		cloned.recordPolicies = make(map[*collectionRecordOwner]collectionPolicyScope, len(policy.recordPolicies))
+		for _, sourceOwner := range policy.recordOrder {
+			owner := newCollectionRecordPolicy().owner
+			cloned.recordOrder = append(cloned.recordOrder, owner)
+			if sourceScope, ok := policy.recordPolicies[sourceOwner]; ok {
+				cloned.recordPolicies[owner] = cloneCollectionPolicyScopeForInheritance(sourceScope)
+			}
+		}
+	}
+	return cloned
+}

internal/engine/collection_policy_state_test.go

@@ -0,0 +1,292 @@
+package engine
+
+import (
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestCollectionPolicyWithoutValueRetainsIdentityAndMode(t *testing.T) {
+	lower := collectionPolicy{
+		identityFields:      []string{"id"},
+		identityPresent:     true,
+		explicitMode:        sequenceModeAppend,
+		explicitModePresent: true,
+	}
+	lower.setRecordPolicy(newCollectionRecordPolicy())
+	current := collectionPolicy{explicitMode: sequenceModeReplace, explicitModePresent: true}
+	retained, diagnostics := collectionPolicyWithoutValue(&lower, current, nil, Keys("prompts"))
+	if len(diagnostics) != 0 || !retained.identityPresent || !reflect.DeepEqual(retained.identityFields, []string{"id"}) {
+		t.Fatalf("no-value replace reset identity: %#v, %#v", retained, diagnostics)
+	}
+	if retained.explicitMode != sequenceModeReplace || !retained.explicitModePresent || len(retained.recordOrder) != 1 {
+		t.Fatalf("no-value policy update lost mode or record ownership: %#v", retained)
+	}
+	retainedRecord, _ := retained.recordPolicyAt(0)
+	lowerRecord, _ := lower.recordPolicyAt(0)
+	if retainedRecord.owner != lowerRecord.owner {
+		t.Fatal("no-value policy update changed record ownership")
+	}
+}
+
+func TestCollectionPolicyWithoutValueLeavesAbsentAndNonSequenceDestinationsUnconstrained(t *testing.T) {
+	current := collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+	for _, value := range []*document.Node{nil, parsePolicyNode(t, "value: scalar\n").Mapping[0].Value} {
+		retained, diagnostics := collectionPolicyWithoutValue(nil, current, value, Keys("prompts"))
+		if len(diagnostics) != 0 || !retained.identityPresent || !reflect.DeepEqual(retained.identityFields, []string{"id"}) {
+			t.Fatalf("pending identity at absent/non-sequence destination = %#v, %#v", retained, diagnostics)
+		}
+	}
+}
+
+func TestCollectionPolicyWithoutValueValidatesRetainedSequenceImmediately(t *testing.T) {
+	current := collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+	valid := parsePolicyNode(t, "items: [{id: one}, {id: two}]\n").Mapping[0].Value
+	retained, diagnostics := collectionPolicyWithoutValue(nil, current, valid, Keys("prompts"))
+	if len(diagnostics) != 0 || !retained.identityPresent {
+		t.Fatalf("valid retained records were rejected: %#v, %#v", retained, diagnostics)
+	}
+
+	invalid := parsePolicyNode(t, "items: [{name: missing-id}]\n").Mapping[0].Value
+	retained, diagnostics = collectionPolicyWithoutValue(nil, current, invalid, Keys("prompts"))
+	if !reflect.DeepEqual(retained, collectionPolicy{}) || len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != "/prompts/0/id" {
+		t.Fatalf("invalid retained records = %#v, %#v", retained, diagnostics)
+	}
+}
+
+func TestCollectionPolicyWithoutValueRejectsIdentityChange(t *testing.T) {
+	lower := collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+	current := collectionPolicy{identityFields: []string{"name"}, identityPresent: true}
+	retained, diagnostics := collectionPolicyWithoutValue(&lower, current, nil, Keys("prompts"))
+	if !reflect.DeepEqual(retained, collectionPolicy{}) || len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict {
+		t.Fatalf("no-value identity change = %#v, %#v", retained, diagnostics)
+	}
+}
+
+func TestCollectionPolicyLifetimePersistenceAndReplacementTable(t *testing.T) {
+	tests := []struct {
+		name            string
+		current         collectionPolicy
+		replaceValue    bool
+		wantIdentity    []string
+		wantIdentitySet bool
+		wantMode        sequenceMode
+		wantRecords     int
+	}{
+		{
+			name: "mode-only replace declaration does not reset retained identity",
+			current: collectionPolicy{
+				explicitMode: sequenceModeReplace, explicitModePresent: true,
+			},
+			wantIdentity: []string{"id"}, wantIdentitySet: true,
+			wantMode: sequenceModeReplace, wantRecords: 1,
+		},
+		{
+			name:            "whole-sequence replacement resets lower identity",
+			replaceValue:    true,
+			wantIdentitySet: false,
+			wantMode:        sequenceModeAppend,
+			wantRecords:     0,
+		},
+		{
+			name:            "replacement can establish a new identity",
+			current:         collectionPolicy{identityFields: []string{"name"}, identityPresent: true},
+			replaceValue:    true,
+			wantIdentity:    []string{"name"},
+			wantIdentitySet: true,
+			wantMode:        sequenceModeAppend,
+			wantRecords:     0,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			lower := collectionPolicy{
+				identityFields: []string{"id"}, identityPresent: true,
+				explicitMode: sequenceModeAppend, explicitModePresent: true,
+			}
+			lower.setRecordPolicy(newCollectionRecordPolicy())
+			var got collectionPolicy
+			if test.replaceValue {
+				got = collectionPolicyForReplacement(&lower, test.current)
+			} else {
+				var diagnostics []Diagnostic
+				got, diagnostics = collectionPolicyWithoutValue(&lower, test.current, nil, Keys("prompts"))
+				if len(diagnostics) != 0 {
+					t.Fatalf("policy diagnostics = %#v", diagnostics)
+				}
+			}
+			if got.identityPresent != test.wantIdentitySet || !reflect.DeepEqual(got.identityFields, test.wantIdentity) || got.explicitMode != test.wantMode || len(got.recordOrder) != test.wantRecords {
+				t.Fatalf("transition result = %#v", got)
+			}
+		})
+	}
+}
+
+func TestCollectionPolicyValueReplacementResetsIdentityButRetainsExplicitMode(t *testing.T) {
+	lower := collectionPolicy{
+		identityFields:      []string{"id"},
+		identityPresent:     true,
+		explicitMode:        sequenceModeAppend,
+		explicitModePresent: true,
+	}
+	lower.setRecordPolicy(newCollectionRecordPolicy())
+	current := collectionPolicy{identityFields: []string{"name"}, identityPresent: true}
+	replaced := collectionPolicyForReplacement(&lower, current)
+	if !replaced.identityPresent || !reflect.DeepEqual(replaced.identityFields, []string{"name"}) {
+		t.Fatalf("replacement identity was not reset: %#v", replaced)
+	}
+	if replaced.explicitMode != sequenceModeAppend || !replaced.explicitModePresent || len(replaced.recordOrder) != 0 {
+		t.Fatalf("replacement failed to retain explicit mode or retire lower record policy: %#v", replaced)
+	}
+
+	cleared := collectionPolicyForReplacement(&lower, collectionPolicy{})
+	if cleared.identityPresent || len(cleared.identityFields) != 0 || cleared.explicitMode != sequenceModeAppend || !cleared.explicitModePresent {
+		t.Fatalf("replacement without a new key did not clear YAML identity while retaining mode: %#v", cleared)
+	}
+}
+
+func TestCollectionRecordRetentionAndReplacementUseOpaqueOwners(t *testing.T) {
+	oldRecord := newCollectionRecordPolicy()
+	oldRecord.scope.set(Keys("steps"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	retained := retainedCollectionRecordPolicy(oldRecord)
+	if retained.owner != oldRecord.owner {
+		t.Fatal("retained record did not keep its owner")
+	}
+	if got, ok := retained.scope.at(Keys("steps")); !ok || !got.identityPresent {
+		t.Fatalf("retained record lost its local policy: %#v, %t", got, ok)
+	}
+	if retained.scope.collections["/steps"].policy.identityFields[0] = "changed"; oldRecord.scope.collections["/steps"].policy.identityFields[0] != "id" {
+		t.Fatal("retained record policy aliases its source")
+	}
+
+	// A whole-record replacement at the same list position, even with equal
+	// authored identity/source metadata, receives new ownership and no old rules.
+	replacement := replacedCollectionRecordPolicy()
+	if replacement.owner == oldRecord.owner || len(replacement.scope.collections) != 0 {
+		t.Fatal("replacement record inherited discarded owner policy")
+	}
+}
+
+func TestCollectionPolicyAncestorRetirementPreservesIndependentMode(t *testing.T) {
+	var scope collectionPolicyScope
+	owner := newCollectionRecordPolicy()
+	owner.scope.set(Keys("steps"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	scope.set(Keys("catalog", "prompts"), collectionPolicyWithRecords(collectionPolicy{
+		identityFields:      []string{"id"},
+		identityPresent:     true,
+		explicitMode:        sequenceModeAppend,
+		explicitModePresent: true,
+	}, owner))
+	scope.retireCollectionPoliciesAtOrBelow(Keys("catalog"))
+	policy, ok := scope.at(Keys("catalog", "prompts"))
+	if !ok || policy.identityPresent || len(policy.recordOrder) != 0 || policy.explicitMode != sequenceModeAppend || !policy.explicitModePresent {
+		t.Fatalf("ancestor retirement = %#v, %t", policy, ok)
+	}
+	reintroduced, diagnostics := collectionPolicyWithoutValue(&policy, collectionPolicy{}, nil, Keys("catalog", "prompts"))
+	if len(diagnostics) != 0 || reintroduced.identityPresent || reintroduced.explicitMode != sequenceModeAppend {
+		t.Fatalf("retired identity was resurrected while mode persisted: %#v, %#v", reintroduced, diagnostics)
+	}
+}
+
+func TestEqualOuterIdentitiesHaveDistinctRecordOwners(t *testing.T) {
+	retained := newCollectionRecordPolicy()
+	replacement := replacedCollectionRecordPolicy()
+	if retained.owner == replacement.owner {
+		t.Fatal("replacement with the same outer identity reused the old owner")
+	}
+	if retained.owner == nil || replacement.owner == nil {
+		t.Fatal("record owner token is missing")
+	}
+}
+
+func TestCollectionPolicyScopesKeepRootAndItemRulesIndependent(t *testing.T) {
+	var root collectionPolicyScope
+	root.set(Keys("steps"), collectionPolicy{identityFields: []string{"root-id"}, identityPresent: true})
+	owner := newCollectionRecordPolicy()
+	owner.scope.set(Keys("steps"), collectionPolicy{identityFields: []string{"item-id"}, identityPresent: true})
+	root.set(Keys("items"), collectionPolicyWithRecords(collectionPolicy{}, owner))
+
+	root.retireCollectionPoliciesAtOrBelow(Keys("steps"))
+	rootPolicy, ok := root.at(Keys("steps"))
+	if !ok || rootPolicy.identityPresent {
+		t.Fatalf("root-local policy was not retired: %#v", rootPolicy)
+	}
+	itemPolicy, ok := root.at(Keys("items"))
+	if !ok || len(itemPolicy.recordOrder) != 1 {
+		t.Fatalf("unrelated item owner disappeared: %#v", itemPolicy)
+	}
+	itemRecord, _ := itemPolicy.recordPolicyAt(0)
+	nested, ok := itemRecord.scope.at(Keys("steps"))
+	if !ok || !nested.identityPresent || !reflect.DeepEqual(nested.identityFields, []string{"item-id"}) {
+		t.Fatalf("item-local policy was coupled to root destination: %#v", nested)
+	}
+}
+
+func TestCollectionPolicyProjectionUsesConcretePlacement(t *testing.T) {
+	first := newCollectionRecordPolicy()
+	first.scope.set(Keys("steps"), collectionPolicy{identityFields: []string{"step"}, identityPresent: true})
+	second := newCollectionRecordPolicy()
+	second.scope.set(Keys("steps"), collectionPolicy{explicitMode: sequenceModeAppend, explicitModePresent: true})
+	var scope collectionPolicyScope
+	scope.set(Keys("items"), collectionPolicyWithRecords(collectionPolicy{}, first, second))
+
+	projected := projectCollectionPolicyScope(scope, Keys("mounted"))
+	if len(projected) != 3 {
+		t.Fatalf("projected policies = %#v", projected)
+	}
+	want := []string{"/mounted/items", "/mounted/items/0/steps", "/mounted/items/1/steps"}
+	for index, policy := range projected {
+		if policy.path.String() != want[index] {
+			t.Fatalf("projected path[%d] = %q, want %q", index, policy.path.String(), want[index])
+		}
+	}
+}
+
+func TestCollectionPolicyInheritanceCopiesOwnersAndState(t *testing.T) {
+	owner := newCollectionRecordPolicy()
+	owner.scope.set(Keys("steps"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	original := collectionPolicyWithRecords(collectionPolicy{}, owner)
+	copy := cloneCollectionPolicyForInheritance(original)
+	copyOwner := copy.recordOrder[0]
+	if copyOwner == owner.owner {
+		t.Fatal("inheritance copy retained the source record owner")
+	}
+	copy.recordPolicies[copyOwner].collections["/steps"].policy.identityFields[0] = "changed"
+	if owner.scope.collections["/steps"].policy.identityFields[0] != "id" {
+		t.Fatal("inheritance copy aliases source policy")
+	}
+}
+
+func TestAcquisitionScopeCloneOwnsCollectionPolicyCopy(t *testing.T) {
+	owner := newCollectionRecordPolicy()
+	owner.scope.set(Keys("steps"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	var scope acquisitionScope
+	scope.collectionPolicies.set(Keys("items"), collectionPolicyWithRecords(collectionPolicy{}, owner))
+	cloned := cloneAcquisitionScope(scope)
+	clonedOwner := cloned.collectionPolicies.collections["/items"].policy.recordOrder[0]
+	cloned.collectionPolicies.collections["/items"].policy.recordPolicies[clonedOwner].collections["/steps"].policy.identityFields[0] = "changed"
+	sourceOwner := scope.collectionPolicies.collections["/items"].policy.recordOrder[0]
+	if scope.collectionPolicies.collections["/items"].policy.recordPolicies[sourceOwner].collections["/steps"].policy.identityFields[0] != "id" {
+		t.Fatal("acquisition scope clone aliases collection policy")
+	}
+	if clonedOwner != owner.owner {
+		t.Fatal("acquisition scope clone changed record ownership")
+	}
+}
+
+func collectionPolicyWithRecords(policy collectionPolicy, records ...collectionRecordPolicy) collectionPolicy {
+	for _, record := range records {
+		policy.setRecordPolicy(record)
+	}
+	return policy
+}
+
+func parsePolicyNode(t *testing.T, input string) *document.Node {
+	t.Helper()
+	parsed, diagnostics := parseSource(Bytes("collection-policy-state.yml", []byte(input)), "collection-policy-state", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("parse policy value: %#v", diagnostics)
+	}
+	return parsed.document
+}

internal/engine/collection_policy_test.go

@@ -0,0 +1,192 @@
+package engine
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestResolveCollectionPolicyReconcilesDeclarationsBeforeComposition(t *testing.T) {
+	declarations := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      key: [namespace, id]
+      mode: append
+    - destination: [prompts]
+      key: [id, namespace, id]
+    - destination: [prompts]
+      mode: append
+`, rootDirectiveContextSource).sequences
+
+	resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), declarations, nil, nil)
+	if len(diagnostics) != 0 {
+		t.Fatalf("policy diagnostics = %#v", diagnostics)
+	}
+	if !resolved.declarationsPresent || !resolved.identityDeclarationPresent || !resolved.modeDeclarationPresent {
+		t.Fatalf("declaration presence was lost: %#v", resolved)
+	}
+	wantFields := []string{"id", "namespace"}
+	if !reflect.DeepEqual(resolved.policy.identityFields, wantFields) || !reflect.DeepEqual(resolved.effectiveIdentityFields, wantFields) {
+		t.Fatalf("effective identity = %#v / %#v, want %#v", resolved.policy.identityFields, resolved.effectiveIdentityFields, wantFields)
+	}
+	if !resolved.policy.identityPresent || !resolved.policy.explicitModePresent || resolved.policy.explicitMode != sequenceModeAppend || resolved.operation != sequenceModeAppend {
+		t.Fatalf("resolved explicit policy = %#v, operation %d", resolved.policy, resolved.operation)
+	}
+	if len(resolved.declarations) != 3 || resolved.declarations[0].identityLocation == nil || resolved.declarations[2].location.Line == 0 {
+		t.Fatalf("declaration locations were not retained: %#v", resolved.declarations)
+	}
+}
+
+func TestResolveCollectionPolicyRejectsConflictingPeersAtBothSites(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+	}{
+		{
+			name: "identity fields",
+			body: `configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+    - destination: [prompts]
+      key: name
+`,
+		},
+		{
+			name: "explicit modes",
+			body: `configkit:
+  sequences:
+    - destination: [prompts]
+      mode: append
+    - destination: [prompts]
+      mode: replace
+`,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			declarations := extractSequenceDeclarationsYAML(t, test.body, rootDirectiveContextSource).sequences
+			resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), declarations, nil, nil)
+			if !reflect.DeepEqual(resolved, collectionPolicyResolution{}) || len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict {
+				t.Fatalf("resolution/diagnostics = %#v / %#v", resolved, diagnostics)
+			}
+			diagnostic := diagnostics[0]
+			if diagnostic.Path.String() != "/prompts" || diagnostic.Primary == nil || len(diagnostic.Related) != 1 {
+				t.Fatalf("conflict does not identify both declaration sites: %#v", diagnostic)
+			}
+			if diagnostic.Primary.SourceID != "sequence-declarations" || diagnostic.Related[0].SourceID != "sequence-declarations" || diagnostic.Primary.Line == diagnostic.Related[0].Line {
+				t.Fatalf("conflict locations = %#v and %#v", diagnostic.Primary, diagnostic.Related)
+			}
+		})
+	}
+}
+
+func TestResolveCollectionPolicySelectsCurrentThenRetainedExplicitMode(t *testing.T) {
+	lower := &collectionPolicy{
+		identityFields:      []string{"id"},
+		identityPresent:     true,
+		explicitMode:        sequenceModeAppend,
+		explicitModePresent: true,
+		modeLocation:        &Location{SourceID: "lower", Line: 2},
+	}
+	current := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      mode: upsert
+`, rootDirectiveContextSource).sequences
+	resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), current, nil, lower)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeUpsert || resolved.policy.explicitMode != sequenceModeUpsert || !resolved.policy.explicitModePresent {
+		t.Fatalf("current mode did not override retained mode: %#v, %#v", resolved, diagnostics)
+	}
+
+	resolved, diagnostics = resolveCollectionPolicy(Keys("prompts"), nil, nil, lower)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeAppend || resolved.policy.explicitMode != sequenceModeAppend || !resolved.policy.explicitModePresent {
+		t.Fatalf("omitted current mode did not retain lower explicit mode: %#v, %#v", resolved, diagnostics)
+	}
+	if !reflect.DeepEqual(resolved.effectiveIdentityFields, []string{"id"}) {
+		t.Fatalf("retained identity = %#v", resolved.effectiveIdentityFields)
+	}
+}
+
+func TestResolveCollectionPolicyInfersWithoutPersistingMode(t *testing.T) {
+	keyOnly := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+`, rootDirectiveContextSource).sequences
+	resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), keyOnly, nil, nil)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeUpsert || resolved.policy.explicitModePresent {
+		t.Fatalf("identity-based mode inference = %#v, %#v", resolved, diagnostics)
+	}
+
+	resolved, diagnostics = resolveCollectionPolicy(Keys("prompts"), nil, []string{"id"}, nil)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeUpsert || resolved.policy.identityPresent || !resolved.applicationIdentityPresent {
+		t.Fatalf("application identity was not kept distinct from YAML policy: %#v, %#v", resolved, diagnostics)
+	}
+
+	noIdentity := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+`, rootDirectiveContextSource).sequences
+	resolved, diagnostics = resolveCollectionPolicy(Keys("prompts"), noIdentity, nil, nil)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeReplace || resolved.policy.explicitModePresent {
+		t.Fatalf("unkeyed mode inference = %#v, %#v", resolved, diagnostics)
+	}
+
+	explicitDefault := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      mode: replace
+`, rootDirectiveContextSource).sequences
+	resolved, diagnostics = resolveCollectionPolicy(Keys("prompts"), explicitDefault, nil, nil)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeReplace || !resolved.policy.explicitModePresent {
+		t.Fatalf("explicit default mode lost its presence: %#v, %#v", resolved, diagnostics)
+	}
+}
+
+func TestResolveCollectionPolicyChecksKeyOnlyAgainstApplicationConstraint(t *testing.T) {
+	declarations := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      key: [namespace, id]
+`, rootDirectiveContextSource).sequences
+	resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), declarations, []string{"id", "namespace", "id"}, nil)
+	if len(diagnostics) != 0 || resolved.operation != sequenceModeUpsert || !reflect.DeepEqual(resolved.effectiveIdentityFields, []string{"id", "namespace"}) {
+		t.Fatalf("equivalent key-only declaration was rejected: %#v, %#v", resolved, diagnostics)
+	}
+
+	resolved, diagnostics = resolveCollectionPolicy(Keys("prompts"), declarations, []string{"slug"}, nil)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict {
+		t.Fatalf("conflicting key-only declaration = %#v, %#v", resolved, diagnostics)
+	}
+	if diagnostics[0].Primary == nil || diagnostics[0].Path.String() != "/prompts" || len(diagnostics[0].Related) != 0 {
+		t.Fatalf("application conflict diagnostic = %#v", diagnostics[0])
+	}
+}
+
+func TestResolveCollectionPolicyChecksRetainedIdentityAgainstApplicationConstraint(t *testing.T) {
+	lower := &collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+	resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), nil, []string{"name"}, lower)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict || diagnostics[0].Path.String() != "/prompts" {
+		t.Fatalf("retained/application conflict = %#v, %#v", resolved, diagnostics)
+	}
+}
+
+func TestResolveCollectionPolicyRequiresCurrentIdentityToAgreeWithRetainedIdentity(t *testing.T) {
+	declarations := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      key: name
+`, rootDirectiveContextSource).sequences
+	lower := &collectionPolicy{
+		identityFields:   []string{"id"},
+		identityPresent:  true,
+		identityLocation: &Location{SourceID: "lower", Line: 4},
+	}
+	resolved, diagnostics := resolveCollectionPolicy(Keys("prompts"), declarations, nil, lower)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict || diagnostics[0].Path.String() != "/prompts" {
+		t.Fatalf("current/retained identity conflict = %#v, %#v", resolved, diagnostics)
+	}
+	if diagnostics[0].Primary == nil || len(diagnostics[0].Related) != 1 || diagnostics[0].Related[0].SourceID != "lower" {
+		t.Fatalf("current/retained conflict locations = %#v", diagnostics[0])
+	}
+}

internal/engine/collection_retirement.go

@@ -0,0 +1,81 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// A true entry replaces the collection itself as well as its descendants;
+// false records ordinary ancestor replacement without selecting a collection
+// operation at that exact path.
+type collectionReplacementPaths map[string]bool
+
+func (paths collectionReplacementPaths) contains(path Path, includeExact bool) bool {
+	for length := 0; length <= len(path.segments); length++ {
+		prefix := Path{segments: path.segments[:length]}
+		inclusive, found := paths[prefix.String()]
+		if found && (length < len(path.segments) || includeExact && inclusive) {
+			return true
+		}
+	}
+	return false
+}
+
+// lowerCollectionPoliciesForClaims makes replacement eligibility independent of
+// declaration order. It removes only old YAML identity/record state; new pending
+// declarations and application constraints are reconciled afterward.
+func lowerCollectionPoliciesForClaims(
+	lower collectionPolicyScope,
+	claims []compositionClaim,
+	declarations map[string][]sequenceDeclarationSpec,
+	application sequencePolicy,
+) (collectionPolicyScope, collectionReplacementPaths) {
+	byPath := make(map[string]compositionClaim, len(claims))
+	rootPath := ""
+	if len(claims) != 0 {
+		rootPath = claims[0].path.String()
+	}
+	for _, claim := range claims {
+		byPath[claim.path.String()] = claim
+	}
+	replaced := make(collectionReplacementPaths)
+	for key, claim := range byPath {
+		old, hasOld := lower.collections[key]
+		current := declarations[key]
+		if claim.kind == document.Mapping && (key == rootPath || !hasOld && len(current) == 0) {
+			continue // Ordinary mapping combination preserves descendants.
+		}
+		mode := sequenceMode(0)
+		identity := old.policy.identityPresent
+		for _, declaration := range current {
+			identity = identity || declaration.identityPresent
+			if mode == 0 && declaration.modePresent {
+				mode = declaration.mode
+			}
+		}
+		retainedMode := sequenceMode(0)
+		if old.policy.explicitModePresent {
+			retainedMode = old.policy.explicitMode
+		}
+		_, registered := application.identityFieldsAt(claim.path)
+		mode = collectionOperationMode(mode, retainedMode, identity || registered)
+		if mode == sequenceModeReplace {
+			replaced[key] = true
+		} else if claim.kind != document.Mapping && claim.kind != document.Sequence {
+			replaced[key] = false
+		}
+	}
+	result := cloneCollectionPolicyScope(lower)
+	for key, entry := range result.collections {
+		if replaced.contains(entry.destination, true) {
+			clearCollectionIdentity(&entry.policy)
+			result.collections[key] = entry
+		}
+	}
+	return result, replaced
+}
+
+func clearCollectionIdentity(policy *collectionPolicy) {
+	policy.identityFields = nil
+	policy.identityPresent = false
+	policy.identityLocation = nil
+	policy.recordOrder = nil
+	policy.recordPolicies = nil
+}

internal/engine/collection_retirement_test.go

@@ -0,0 +1,111 @@
+package engine
+
+import (
+	"errors"
+	"testing"
+)
+
+func TestSourceReplacementRetiresIdentityForEveryValueKind(t *testing.T) {
+	t.Parallel()
+	for _, value := range []string{"null", "42", "{}", "[{name: new}]"} {
+		t.Run(value, func(t *testing.T) {
+			lower := "configkit:\n  sequences: [{destination: [items], key: id}]\nitems: [{id: old}]\n"
+			main := "configkit:\n  sequences: [{destination: [items], key: name, mode: replace}]\nitems: " + value + "\n"
+			loaded, err := testGroupedLoad(loadRequest[map[string]any]{
+				main:      loadInput{source: Bytes("main", []byte(main))},
+				underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte(lower))}}}},
+			})
+			if err != nil || loaded == nil {
+				t.Fatalf("replacement retained obsolete identity: %v", err)
+			}
+		})
+	}
+}
+
+func TestAncestorRemovalCanEstablishPendingReplacementIdentity(t *testing.T) {
+	t.Parallel()
+	for _, inheritance := range []bool{false, true} {
+		name := "tiers"
+		if inheritance {
+			name = "inheritance"
+		}
+		t.Run(name, func(t *testing.T) {
+			var loaded *testResult[map[string]any]
+			var err error
+			if inheritance {
+				loaded, err = testLoad[map[string]any](Bytes("source", []byte(`configkit:
+  sequences:
+    - {destination: [base, group, items], key: id}
+    - {destination: [child, group, items], key: name}
+base: {group: {items: [{id: old}]}}
+child:
+  extends: base
+  group: null
+grandchild:
+  extends: child
+  group: {items: [{name: new}]}
+`)))
+			} else {
+				loaded, err = testGroupedLoad(loadRequest[map[string]any]{
+					main: loadInput{source: Bytes("main", []byte("group: {items: [{name: new}]}\n"))},
+					underlays: []loadGroup{
+						{inputs: []loadInput{{source: Bytes("base", []byte("configkit:\n  sequences: [{destination: [group, items], key: id}]\ngroup: {items: [{id: old}]}\n"))}}},
+						{inputs: []loadInput{{source: Bytes("remove", []byte("configkit:\n  sequences: [{destination: [group, items], key: name}]\ngroup: null\n"))}}},
+					},
+				})
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			value := loaded.Config
+			if inheritance {
+				value = value["grandchild"].(map[string]any)
+			}
+			items := value["group"].(map[string]any)["items"].([]any)
+			if len(items) != 1 || items[0].(map[string]any)["name"] != "new" {
+				t.Fatalf("reintroduced collection = %#v", items)
+			}
+		})
+	}
+}
+
+func TestInheritanceAncestorRetirementDoesNotResurrectOldIdentity(t *testing.T) {
+	t.Parallel()
+	_, err := testLoad[map[string]any](Bytes("source", []byte(`configkit:
+  sequences: [{destination: [base, group, items], key: id}]
+base: {group: {items: [{id: old}]}}
+child:
+  extends: base
+  group: null
+grandchild:
+  extends: child
+  group: {items: [{name: new}]}
+`)))
+	if err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestReplacementRetirementPreservesApplicationConstraintsAndRetainedKeys(t *testing.T) {
+	t.Parallel()
+	for _, withValue := range []bool{false, true} {
+		main := "configkit:\n  sequences: [{destination: [items], key: name, mode: replace}]\n"
+		if withValue {
+			main += "items: null\n"
+		}
+		definition := Definition[map[string]any]{}
+		if withValue {
+			definition.sequenceIdentityRegistrations = []sequenceIdentityRegistration{{
+				selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"},
+			}}
+		}
+		_, err := testGroupedLoad(loadRequest[map[string]any]{
+			main: loadInput{source: Bytes("main", []byte(main))}, definition: definition,
+			underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte("configkit:\n  sequences: [{destination: [items], key: id}]\nitems: [{id: old}]\n"))}}}},
+		})
+		var loadErr *LoadError
+		if !errors.As(err, &loadErr) || len(loadErr.Diagnostics()) == 0 || loadErr.Diagnostics()[0].Code != CodeSequenceConflict {
+			t.Fatalf("retirement bypassed identity agreement: %v", err)
+		}
+	}
+}

internal/engine/compose.go

@@ -6,16 +6,17 @@ import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
 // precedence layers. Claims remain ordered by source and declaration traversal;
 // origins retain every source that contributes to a composite mapping.
 type composedDocument struct {
-	root           *document.Node
-	acquisition    []acquisitionScope
-	importGraph    importInclusionGraph
-	claims         []compositionClaim
-	sequenceRanges []sequenceRange
-	origins        map[string]Origin
-	overlays       []overlayRecord
-	applications   []historyApplication
-	inputBytes     int64
-	inputNodes     int
+	root               *document.Node
+	acquisition        []acquisitionScope
+	importGraph        importInclusionGraph
+	collectionPolicies collectionPolicyScope
+	claims             []compositionClaim
+	sequenceRanges     []sequenceRange
+	origins            map[string]Origin
+	overlays           []overlayRecord
+	applications       []historyApplication
+	inputBytes         int64
+	inputNodes         int
 }
 
 type sequenceHistoryMode uint8
@@ -23,13 +24,16 @@ type sequenceHistoryMode uint8
 const (
 	sequenceHistoryReplace sequenceHistoryMode = iota + 1
 	sequenceHistoryAppend
+	sequenceHistoryMapped
 )
 
 type sequenceHistoryContribution struct {
-	path   Path
-	mode   sequenceHistoryMode
-	offset int
-	length int
+	path         Path
+	mode         sequenceHistoryMode
+	offset       int
+	length       int
+	items        []sequenceItemProjection
+	replacements []sequenceItemReplacement
 }
 
 // assemblyAccumulator owns one mutable working document. Acquired trees held by
@@ -51,10 +55,11 @@ func cloneComposedDocument(base *composedDocument) *composedDocument {
 	}
 	return &composedDocument{
 		root: document.Clone(base.root), claims: cloneCompositionClaims(base.claims),
-		acquisition:    cloneAcquisitionScopes(base.acquisition),
-		importGraph:    base.importGraph.clone(),
-		sequenceRanges: cloneSequenceRanges(base.sequenceRanges),
-		origins:        cloneOriginIndex(base.origins), overlays: cloneOverlayRecords(base.overlays),
+		acquisition:        cloneAcquisitionScopes(base.acquisition),
+		importGraph:        base.importGraph.clone(),
+		collectionPolicies: cloneCollectionPolicyScope(base.collectionPolicies),
+		sequenceRanges:     cloneSequenceRanges(base.sequenceRanges),
+		origins:            cloneOriginIndex(base.origins), overlays: cloneOverlayRecords(base.overlays),
 		applications: cloneHistoryApplications(base.applications),
 		inputBytes:   base.inputBytes, inputNodes: base.inputNodes,
 	}
@@ -80,6 +85,48 @@ type sequenceRange struct {
 	path        Path
 	start       int
 	end         int
+	items       []sequenceItemProjection
+	projection  sequenceItemProjectionIndex
+}
+
+func (assigned sequenceRange) projections() []sequenceItemProjection {
+	if assigned.items != nil {
+		return append([]sequenceItemProjection{}, assigned.items...)
+	}
+	return sequenceItemProjections(assigned.end-assigned.start, assigned.start)
+}
+
+func (assigned sequenceRange) outputForInput(inputIndex int) (int, bool) {
+	if assigned.projection.outputByInput != nil {
+		return assigned.projection.outputForInput(inputIndex)
+	}
+	if assigned.items != nil {
+		return newSequenceItemProjectionIndex(assigned.items).outputForInput(inputIndex)
+	}
+	if inputIndex < 0 || inputIndex >= assigned.end-assigned.start {
+		return 0, false
+	}
+	return assigned.start + inputIndex, true
+}
+
+func (assigned sequenceRange) inputForOutput(outputIndex int) (int, bool) {
+	if assigned.projection.inputByOutput != nil {
+		return assigned.projection.inputForOutput(outputIndex)
+	}
+	if assigned.items != nil {
+		return newSequenceItemProjectionIndex(assigned.items).inputForOutput(outputIndex)
+	}
+	if outputIndex < assigned.start || outputIndex >= assigned.end {
+		return 0, false
+	}
+	return outputIndex - assigned.start, true
+}
+
+func indexSequenceRange(assigned sequenceRange) sequenceRange {
+	if assigned.projection.outputByInput == nil && assigned.projection.inputByOutput == nil {
+		assigned.projection = newSequenceItemProjectionIndex(assigned.projections())
+	}
+	return assigned
 }
 
 // composeDocuments recursively joins disjoint mapping entries. Source order
@@ -93,6 +140,17 @@ func composeDocuments(inputs ...*document.Node) (*composedDocument, []Diagnostic
 // sequence rules when policy contains registrations. The ordinary adapter above
 // deliberately preserves the existing unregistered behavior for current callers.
 func composeDocumentsWithPolicy(policy sequencePolicy, inputs ...*document.Node) (*composedDocument, []Diagnostic) {
+	return composeDocumentsWithCollectionPolicy(policy, collectionPolicyScope{}, nil, inputs...)
+}
+
+// composeDocumentsWithCollectionPolicy resolves collection declarations and
+// eligible lower policy before strictly composing completed peer documents.
+func composeDocumentsWithCollectionPolicy(
+	policy sequencePolicy,
+	lower collectionPolicyScope,
+	declarations []sequenceDeclarationSpec,
+	inputs ...*document.Node,
+) (*composedDocument, []Diagnostic) {
 	if len(inputs) == 0 {
 		return nil, []Diagnostic{compositionInvalidDiagnostic("strict composition requires at least one document", nil)}
 	}
@@ -110,6 +168,13 @@ func composeDocumentsWithPolicy(policy sequencePolicy, inputs ...*document.Node)
 		collected.append(input, Path{}, sourceIndex)
 	}
 
+	identityFieldsByPath, collectionPolicies, diagnostics := resolveStrictCollectionPolicies(
+		collected.ordered, policy, lower, declarations,
+	)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+
 	checked := make(map[string]struct{}, len(collected.byPath))
 	for _, claim := range collected.ordered {
 		pointer := claim.path.String()
@@ -118,13 +183,13 @@ func composeDocumentsWithPolicy(policy sequencePolicy, inputs ...*document.Node)
 		}
 		checked[pointer] = struct{}{}
 		claims := collected.byPath[pointer]
-		if len(claims) < 2 || allMappingClaims(claims) || (allSequenceClaims(claims) && policy.registered(claim.path)) {
+		if len(claims) < 2 || allMappingClaims(claims) || (allSequenceClaims(claims) && len(identityFieldsByPath[pointer]) != 0) {
 			continue
 		}
 		return nil, []Diagnostic{compositionConflictDiagnostic(claim.path, claims)}
 	}
 
-	validated, ranges, diagnostics := validateRegisteredSequences(collected.ordered, policy)
+	validated, ranges, diagnostics := validateRegisteredSequences(collected.ordered, identityFieldsByPath)
 	if len(diagnostics) != 0 {
 		return nil, diagnostics
 	}
@@ -132,7 +197,7 @@ func composeDocumentsWithPolicy(policy sequencePolicy, inputs ...*document.Node)
 	root := document.Clone(inputs[0])
 	index := new(mappingIndex)
 	for sourceIndex, input := range inputs[1:] {
-		mergeComposedMappings(root, input, Path{}, index, sourceIndex+1, policy, validated)
+		mergeComposedMappings(root, input, Path{}, index, sourceIndex+1, identityFieldsByPath, validated)
 	}
 	applications := make([]historyApplication, 0, len(inputs))
 	seenSequences := make(map[string]bool)
@@ -159,11 +224,12 @@ func composeDocumentsWithPolicy(policy sequencePolicy, inputs ...*document.Node)
 	origins := projectedCompositionOrigins(inputs, ranges)
 	completeCompositionOrigins(root, Path{}, origins)
 	return &composedDocument{
-		root:           root,
-		claims:         cloneCompositionClaims(collected.ordered),
-		sequenceRanges: cloneSequenceRanges(ranges),
-		origins:        origins,
-		applications:   applications,
+		root:               root,
+		collectionPolicies: collectionPolicies,
+		claims:             cloneCompositionClaims(collected.ordered),
+		sequenceRanges:     cloneSequenceRanges(ranges),
+		origins:            origins,
+		applications:       applications,
 	}, nil
 }
 
@@ -219,71 +285,128 @@ type validatedSequence struct {
 	items []*document.Node
 }
 
-func validateRegisteredSequences(claims []compositionClaim, policy sequencePolicy) (map[string]map[int]validatedSequence, []sequenceRange, []Diagnostic) {
+func resolveStrictCollectionPolicies(
+	claims []compositionClaim,
+	applicationPolicy sequencePolicy,
+	lower collectionPolicyScope,
+	declarations []sequenceDeclarationSpec,
+) (map[string][]string, collectionPolicyScope, []Diagnostic) {
+	paths := make([]Path, 0, len(claims)+len(declarations))
+	seen := make(map[string]bool, len(claims)+len(declarations))
+	valuePresent := make(map[string]bool)
+	declarationsByPath := make(map[string][]sequenceDeclarationSpec, len(declarations))
+	for _, claim := range claims {
+		if len(lower.collections) != 0 {
+			valuePresent[claim.path.String()] = true
+		}
+		if claim.kind != document.Sequence {
+			continue
+		}
+		key := claim.path.String()
+		if !seen[key] {
+			seen[key] = true
+			paths = append(paths, claim.path.clone())
+		}
+	}
+	for _, declaration := range declarations {
+		key := declaration.destination.String()
+		declarationsByPath[key] = append(declarationsByPath[key], declaration)
+		if !seen[key] {
+			seen[key] = true
+			paths = append(paths, declaration.destination.clone())
+		}
+	}
+
+	identityFieldsByPath := make(map[string][]string)
+	effectiveLower := lower
+	if len(lower.collections) != 0 {
+		effectiveLower, _ = lowerCollectionPoliciesForClaims(lower, claims, declarationsByPath, applicationPolicy)
+	}
+	collectionPolicies := cloneCollectionPolicyScope(effectiveLower)
+	var diagnostics []Diagnostic
+	for _, path := range paths {
+		key := path.String()
+		currentDeclarations := declarationsByPath[key]
+
+		lowerEntry, hasLower := effectiveLower.collections[key]
+		var lowerPolicy *collectionPolicy
+		if hasLower {
+			copy := cloneCollectionPolicy(lowerEntry.policy)
+			lowerPolicy = &copy
+		}
+		applicationIdentity, _ := applicationPolicy.identityFieldsAt(path)
+
+		resolution, found := resolveCollectionPolicy(path, currentDeclarations, applicationIdentity, lowerPolicy)
+		if len(found) != 0 {
+			diagnostics = append(diagnostics, found...)
+			continue
+		}
+		if len(resolution.effectiveIdentityFields) != 0 {
+			identityFieldsByPath[key] = cloneStrings(resolution.effectiveIdentityFields)
+		}
+
+		policyForPath := resolution.policy
+		if hasLower && !valuePresent[key] {
+			// A declaration without a new value changes policy metadata but
+			// leaves retained record ownership untouched.
+			policyForPath = cloneCollectionPolicy(lowerEntry.policy)
+			policyForPath.identityFields = cloneStrings(resolution.policy.identityFields)
+			policyForPath.identityPresent = resolution.policy.identityPresent
+			policyForPath.identityLocation = cloneLocation(resolution.policy.identityLocation)
+			policyForPath.explicitMode = resolution.policy.explicitMode
+			policyForPath.explicitModePresent = resolution.policy.explicitModePresent
+			policyForPath.modeLocation = cloneLocation(resolution.policy.modeLocation)
+		}
+		if collectionPolicies.collections == nil {
+			collectionPolicies.collections = make(map[string]collectionPolicyEntry)
+		}
+		collectionPolicies.collections[key] = collectionPolicyEntry{destination: path.clone(), policy: policyForPath}
+	}
+	return identityFieldsByPath, collectionPolicies, canonicalDiagnostics(diagnostics)
+}
+
+func validateRegisteredSequences(claims []compositionClaim, identityFieldsByPath map[string][]string) (map[string]map[int]validatedSequence, []sequenceRange, []Diagnostic) {
 	itemsByPath := make(map[string]map[int]validatedSequence)
-	identitiesByPath := make(map[string]map[string]Location)
+	identitiesByPath := make(map[string]map[string]document.Location)
 	lengthsByPath := make(map[string]int)
 	var ranges []sequenceRange
 	for _, claim := range claims {
 		if claim.kind != document.Sequence {
 			continue
 		}
-		identityField, registered := policy.identityFields[claim.path.String()]
-		if !registered {
+		identityFields := identityFieldsByPath[claim.path.String()]
+		if len(identityFields) == 0 {
 			continue
 		}
 		node := claim.node
 		pathKey := claim.path.String()
 		identities := identitiesByPath[pathKey]
 		if identities == nil {
-			identities = make(map[string]Location, len(node.Sequence))
+			identities = make(map[string]document.Location, len(node.Sequence))
 			identitiesByPath[pathKey] = identities
 		}
 		start := lengthsByPath[pathKey]
 		contribution := validatedSequence{items: node.Sequence}
-		for itemIndex, item := range node.Sequence {
-			itemPath := claim.path.Index(start + itemIndex)
-			if item == nil || item.Kind != document.Mapping {
-				location := (*Location)(nil)
-				if item != nil {
-					converted := publicLocation(item.Location)
-					location = &converted
-				}
-				return nil, nil, []Diagnostic{{
-					Code: CodeComposeInvalid, Severity: SeverityError,
-					Path: itemPath, Message: "registered sequence items must be mappings", Primary: location,
-				}}
-			}
-			fieldIndex := documentEntryIndex(item.Mapping, identityField)
-			if fieldIndex < 0 {
-				location := publicLocation(item.Location)
-				return nil, nil, []Diagnostic{{
-					Code: CodeComposeInvalid, Severity: SeverityError,
-					Path: itemPath, Message: "registered sequence item is missing its identity field",
-					Primary: &location,
-				}}
-			}
-			field := item.Mapping[fieldIndex].Value
-			if field == nil || field.Kind != document.String {
-				location := publicLocation(item.Mapping[fieldIndex].ValueLocation)
-				if field != nil {
-					location = publicLocation(field.Location)
-				}
-				return nil, nil, []Diagnostic{{
-					Code: CodeComposeInvalid, Severity: SeverityError,
-					Path: itemPath.Key(identityField), Message: "registered sequence identity must be a string",
-					Primary: &location,
-				}}
-			}
-			if first, duplicate := identities[field.Text]; duplicate {
-				current := publicLocation(field.Location)
+		records, diagnostics := validateNormalizedSequenceIdentityFrom(node, claim.path, identityFields, sequenceIdentityDiagnosticCodes{
+			invalid: CodeComposeInvalid, conflict: CodeComposeConflict,
+		}, start, sequenceStructuralRecord)
+		if len(diagnostics) != 0 {
+			return nil, nil, diagnostics
+		}
+		byIndex := make([]sequenceIdentityRecord, len(node.Sequence))
+		for _, record := range records {
+			byIndex[record.index] = record
+		}
+		for _, record := range byIndex {
+			if first, duplicate := identities[record.tuple]; duplicate {
+				current := publicLocation(record.location)
 				return nil, nil, []Diagnostic{{
 					Code: CodeComposeConflict, Severity: SeverityError,
 					Path: claim.path.clone(), Message: "registered sequence contains duplicate identities",
-					Primary: &first, Related: []Location{current},
+					Primary: ptrLocation(publicLocation(first)), Related: []Location{current},
 				}}
 			}
-			identities[field.Text] = publicLocation(field.Location)
+			identities[record.tuple] = record.location
 		}
 		if itemsByPath[pathKey] == nil {
 			itemsByPath[pathKey] = make(map[int]validatedSequence)
@@ -297,7 +420,7 @@ func validateRegisteredSequences(claims []compositionClaim, policy sequencePolic
 	return itemsByPath, ranges, nil
 }
 
-func mergeComposedMappings(target, incoming *document.Node, path Path, index *mappingIndex, sourceIndex int, policy sequencePolicy, validated map[string]map[int]validatedSequence) {
+func mergeComposedMappings(target, incoming *document.Node, path Path, index *mappingIndex, sourceIndex int, identityFieldsByPath map[string][]string, validated map[string]map[int]validatedSequence) {
 	for _, incomingEntry := range incoming.Mapping {
 		entryPath := path.Key(incomingEntry.Key)
 		position := index.find(target, incomingEntry.Key)
@@ -308,7 +431,7 @@ func mergeComposedMappings(target, incoming *document.Node, path Path, index *ma
 			continue
 		}
 		current := target.Mapping[position].Value
-		if current.Kind == document.Sequence && incomingEntry.Value.Kind == document.Sequence && policy.registered(entryPath) {
+		if current.Kind == document.Sequence && incomingEntry.Value.Kind == document.Sequence && len(identityFieldsByPath[entryPath.String()]) != 0 {
 			contribution := validated[entryPath.String()][sourceIndex]
 			if contribution.items != nil {
 				for _, item := range contribution.items {
@@ -317,20 +440,15 @@ func mergeComposedMappings(target, incoming *document.Node, path Path, index *ma
 			}
 			continue
 		}
-		mergeDisjointMappingsAtPath(current, incomingEntry.Value, entryPath, index, sourceIndex, policy, validated)
+		mergeDisjointMappingsAtPath(current, incomingEntry.Value, entryPath, index, sourceIndex, identityFieldsByPath, validated)
 	}
 }
 
-func mergeDisjointMappingsAtPath(target, incoming *document.Node, path Path, index *mappingIndex, sourceIndex int, policy sequencePolicy, validated map[string]map[int]validatedSequence) {
+func mergeDisjointMappingsAtPath(target, incoming *document.Node, path Path, index *mappingIndex, sourceIndex int, identityFieldsByPath map[string][]string, validated map[string]map[int]validatedSequence) {
 	if target.Kind != document.Mapping || incoming.Kind != document.Mapping {
 		return
 	}
-	mergeComposedMappings(target, incoming, path, index, sourceIndex, policy, validated)
-}
-
-func (p sequencePolicy) registered(path Path) bool {
-	_, ok := p.identityFields[path.String()]
-	return ok
+	mergeComposedMappings(target, incoming, path, index, sourceIndex, identityFieldsByPath, validated)
 }
 
 func cloneSequenceRanges(ranges []sequenceRange) []sequenceRange {
@@ -338,6 +456,11 @@ func cloneSequenceRanges(ranges []sequenceRange) []sequenceRange {
 	for i, assigned := range ranges {
 		cloned[i] = assigned
 		cloned[i].path = assigned.path.clone()
+		if assigned.items != nil {
+			cloned[i].items = append([]sequenceItemProjection{}, assigned.items...)
+		}
+		cloned[i].projection.outputByInput = append([]int(nil), assigned.projection.outputByInput...)
+		cloned[i].projection.inputByOutput = append([]int(nil), assigned.projection.inputByOutput...)
 	}
 	return cloned
 }
@@ -377,12 +500,22 @@ func documentEntryIndex(entries []document.Entry, key string) int {
 
 func projectedCompositionOrigins(inputs []*document.Node, ranges []sequenceRange) map[string]Origin {
 	origins := make(map[string]Origin)
-	rangeBySourcePath := make(map[sequenceRangeKey]int, len(ranges))
-	for index, assigned := range ranges {
-		rangeBySourcePath[sequenceRangeKey{sourceIndex: assigned.sourceIndex, path: assigned.path.String()}] = index
+	sequencesBySource := make([][]sequenceHistoryContribution, len(inputs))
+	for _, assigned := range ranges {
+		sequencesBySource[assigned.sourceIndex] = append(sequencesBySource[assigned.sourceIndex], sequenceHistoryContribution{
+			path: assigned.path.clone(), mode: sequenceHistoryMapped, items: assigned.projections(),
+		})
 	}
 	for sourceIndex, input := range inputs {
-		collectProjectedCompositionOrigins(input, Path{}, Path{}, sourceIndex, ranges, rangeBySourcePath, origins)
+		application := historyApplication{value: input, sequences: sequencesBySource[sourceIndex]}
+		application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+		walkHistoryApplication(application, func(_, effective Path, node *document.Node) {
+			pointer := effective.String()
+			origin := origins[pointer]
+			origin.Layer = LayerBase
+			origin.Locations = append(origin.Locations, publicLocation(node.Location))
+			origins[pointer] = origin
+		})
 	}
 	return origins
 }
@@ -400,39 +533,12 @@ func indexSequenceRanges(ranges []sequenceRange) sequenceRangeIndex {
 	}
 	index := make(sequenceRangeIndex, len(ranges))
 	for _, assigned := range ranges {
+		assigned = indexSequenceRange(assigned)
 		index[sequenceRangeKey{sourceIndex: assigned.sourceIndex, path: assigned.path.String()}] = assigned
 	}
 	return index
 }
 
-// Keep local paths for matching Stage 2 ranges and effective paths for emitted
-// evidence. The paths are transformed segment by segment; pointer strings are
-// only used as map keys after projection is complete.
-func collectProjectedCompositionOrigins(node *document.Node, localPath, effectivePath Path, sourceIndex int, ranges []sequenceRange, rangeBySourcePath map[sequenceRangeKey]int, origins map[string]Origin) {
-	pointer := effectivePath.String()
-	origin := origins[pointer]
-	origin.Layer = LayerBase
-	origin.Locations = append(origin.Locations, publicLocation(node.Location))
-	origins[pointer] = origin
-
-	switch node.Kind {
-	case document.Mapping:
-		for _, entry := range node.Mapping {
-			collectProjectedCompositionOrigins(entry.Value, localPath.Key(entry.Key), effectivePath.Key(entry.Key), sourceIndex, ranges, rangeBySourcePath, origins)
-		}
-	case document.Sequence:
-		start := 0
-		if rangeIndex, ok := rangeBySourcePath[sequenceRangeKey{sourceIndex: sourceIndex, path: localPath.String()}]; ok {
-			start = ranges[rangeIndex].start
-		}
-		for index, child := range node.Sequence {
-			localChild := localPath.Index(index)
-			effectiveChild := effectivePath.Index(start + index)
-			collectProjectedCompositionOrigins(child, localChild, effectiveChild, sourceIndex, ranges, rangeBySourcePath, origins)
-		}
-	}
-}
-
 func applyCompositionOrigins(decoded *decodedConfiguration, origins map[string]Origin) {
 	for pointer, origin := range origins {
 		if _, present := decoded.presence[pointer]; present {

internal/engine/compose_test.go

@@ -10,17 +10,20 @@ import (
 )
 
 func TestComposeWideRegisteredCollectionsPreservesEvidenceAndReplay(t *testing.T) {
-	policy := sequencePolicy{identityFields: make(map[string]string)}
+	registrations := make([]sequenceIdentityRegistration, 0, 128)
 	var inputs []*document.Node
 	for source := 0; source < 3; source++ {
 		var text strings.Builder
 		for collection := 0; collection < 128; collection++ {
 			key := fmt.Sprintf("records%d", collection)
-			policy.identityFields[Keys(key).String()] = "id"
+			registrations = append(registrations, sequenceIdentityRegistration{
+				selector: sequenceIdentitySelector{literalSequenceSelector(key)}, identityFields: []string{"id"},
+			})
 			fmt.Fprintf(&text, "%s: [{id: source%d}]\n", key, source)
 		}
 		inputs = append(inputs, parseCompositionDocument(t, fmt.Sprintf("source-%d", source), text.String()))
 	}
+	policy := mustCompileSequenceIdentityPolicy(t, registrations)
 	composed, diagnostics := composeDocumentsWithPolicy(policy, inputs...)
 	if len(diagnostics) != 0 {
 		t.Fatal(diagnostics)
@@ -242,7 +245,7 @@ func TestComposeDocumentsAppendsRegisteredSequencesAndReturnsRanges(t *testing.T
 	first := parseCompositionDocument(t, "source-1", "records: [{id: '', left: 1}, {id: ' spaced ', right: 1}]\nother: [one]\n")
 	second := parseCompositionDocument(t, "source-2", "records: [{id: ' ', text: second}]\n")
 	firstBefore, secondBefore := document.Clone(first), document.Clone(second)
-	policy := sequencePolicy{identityFields: map[string]string{"/records": "id"}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}})
 
 	composed, diagnostics := composeDocumentsWithPolicy(policy, first, second)
 	if len(diagnostics) != 0 {
@@ -287,10 +290,10 @@ escaped/~:
       name: escaped-second-name
 `)
 	firstBefore, secondBefore := document.Clone(first), document.Clone(second)
-	policy := sequencePolicy{identityFields: map[string]string{
-		Keys("mounted", "records").String(): "id",
-		Keys("escaped/~", "7").String():     "id",
-	}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{
+		{selector: sequenceIdentitySelector{literalSequenceSelector("mounted"), literalSequenceSelector("records")}, identityFields: []string{"id"}},
+		{selector: sequenceIdentitySelector{literalSequenceSelector("escaped/~"), literalSequenceSelector("7")}, identityFields: []string{"id"}},
+	})
 
 	composed, diagnostics := composeDocumentsWithPolicy(policy, first, second)
 	if len(diagnostics) != 0 {
@@ -357,6 +360,78 @@ escaped/~:
 	}
 }
 
+func TestProjectedCompositionOriginsUseNoncontiguousItemMappings(t *testing.T) {
+	lowerRoot := parseCompositionDocument(t, "lower", `records:
+  - id: first
+    label: equal
+  - id: middle
+  - id: last
+    nested: {old: lower}
+`)
+	higherRoot := parseCompositionDocument(t, "higher", `records:
+  - id: last
+    nested: {new: higher}
+  - id: first
+    label: equal
+  - id: added
+`)
+	lower, _ := documentAtPath(lowerRoot, Keys("records"))
+	higher, _ := documentAtPath(higherRoot, Keys("records"))
+	combined, diagnostics := combineSequence(
+		lower, higher, sequenceCombinationPolicy(sequenceModeUpsert, "id"),
+		sequenceCombinationContext{destination: Keys("records")},
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("combine diagnostics = %#v", diagnostics)
+	}
+	inputs := []*document.Node{lowerRoot, higherRoot}
+	ranges := []sequenceRange{
+		{
+			sourceIndex: 0, path: Keys("records"), start: 0, end: 3,
+			items: combined.lowerItems,
+		}, {
+			sourceIndex: 1, path: Keys("records"), start: 0, end: 3,
+			items: combined.higherItems,
+		},
+	}
+	origins := projectedCompositionOrigins(inputs, ranges)
+	if got, want := sequenceIdentityValues(combined.value, "id"), []string{"first", "middle", "last", "added"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("combined IDs = %#v, want %#v", got, want)
+	}
+	for path, want := range map[string][]string{
+		"/records/0/label":      {"higher"},
+		"/records/1/id":         {"lower"},
+		"/records/2/nested/new": {"higher"},
+		"/records/3/id":         {"higher"},
+		"/records/0/nested/new": nil,
+		"/records/2/nested/old": nil,
+	} {
+		origin := origins[path]
+		var got []string
+		for _, location := range origin.Locations {
+			got = append(got, location.SourceID)
+		}
+		if !reflect.DeepEqual(got, want) {
+			t.Errorf("origin sources at %s = %#v, want %#v", path, got, want)
+		}
+	}
+}
+
+func TestCloneSequenceRangesPreservesPreparedProjection(t *testing.T) {
+	ranges := []sequenceRange{{
+		start: 0, end: 1,
+		projection: newSequenceItemProjectionIndex([]sequenceItemProjection{{inputIndex: 0, outputIndex: 4}}),
+	}}
+	cloned := cloneSequenceRanges(ranges)
+	if output, ok := cloned[0].outputForInput(0); !ok || output != 4 {
+		t.Fatalf("cloned projection = %d, %v; want output index 4", output, ok)
+	}
+	cloned[0].projection.outputByInput[0] = 9
+	if output, ok := ranges[0].outputForInput(0); !ok || output != 4 {
+		t.Fatalf("cloned projection aliases original: %d, %v", output, ok)
+	}
+}
+
 func TestComposeDocumentsValidatesRegisteredSequenceSingletons(t *testing.T) {
 	tests := []struct {
 		name     string
@@ -365,15 +440,12 @@ func TestComposeDocumentsValidatesRegisteredSequenceSingletons(t *testing.T) {
 		wantCode Code
 	}{
 		{name: "nonmapping item", body: "records: [plain]\n", path: "/records/0", wantCode: CodeComposeInvalid},
-		{name: "missing identity", body: "records: [{name: plain}]\n", path: "/records/0", wantCode: CodeComposeInvalid},
-		{name: "null identity", body: "records: [{id: null}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
-		{name: "numeric identity", body: "records: [{id: 12}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
-		{name: "boolean identity", body: "records: [{id: false}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
+		{name: "missing identity", body: "records: [{name: plain}]\n", path: "/records/0/id", wantCode: CodeComposeInvalid},
 	}
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
 			_, diagnostics := composeDocumentsWithPolicy(
-				sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+				mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}}),
 				parseCompositionDocument(t, "source-1", test.body),
 			)
 			if len(diagnostics) != 1 || diagnostics[0].Code != test.wantCode || diagnostics[0].Path.String() != test.path {
@@ -386,14 +458,138 @@ func TestComposeDocumentsValidatesRegisteredSequenceSingletons(t *testing.T) {
 	}
 }
 
+func TestComposeDocumentsUsesLowerIdentityForStrictPeers(t *testing.T) {
+	path := Keys("records")
+	lower := collectionPolicyScope{collections: map[string]collectionPolicyEntry{
+		path.String(): {
+			destination: path,
+			policy:      collectionPolicy{identityFields: []string{"id"}, identityPresent: true},
+		},
+	}}
+	composed, diagnostics := composeDocumentsWithCollectionPolicy(
+		sequencePolicy{}, lower, nil,
+		parseCompositionDocument(t, "source-1", "records: [{id: first}]\n"),
+		parseCompositionDocument(t, "source-2", "records: [{id: second}]\n"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose strict peers with lower identity: %#v", diagnostics)
+	}
+	value, present := documentAtPath(composed.root, path)
+	if !present || value.Kind != document.Sequence || len(value.Sequence) != 2 {
+		t.Fatalf("composed records = %#v, %v; want two strict peer records", value, present)
+	}
+	resolved, present := composed.collectionPolicies.collections[path.String()]
+	if !present || !resolved.policy.identityPresent || !reflect.DeepEqual(resolved.policy.identityFields, []string{"id"}) {
+		t.Fatalf("composed collection policy = %#v, %v; want retained lower identity", resolved, present)
+	}
+	clone := cloneComposedDocument(composed)
+	resolved.policy.identityFields[0] = "mutated"
+	if !reflect.DeepEqual(clone.collectionPolicies.collections[path.String()].policy.identityFields, []string{"id"}) {
+		t.Fatal("cloned composition shares mutable collection identity fields")
+	}
+}
+
+func TestComposeDocumentsResolvesDeclarationsBeforePeerComposition(t *testing.T) {
+	path := Keys("records")
+	declaration := func(source string, line int, fields ...string) sequenceDeclarationSpec {
+		location := Location{SourceID: source, Line: line}
+		return sequenceDeclarationSpec{
+			destination: path, identityFields: fields, identityPresent: true,
+			identityLocation: &location,
+		}
+	}
+
+	_, diagnostics := composeDocumentsWithCollectionPolicy(
+		sequencePolicy{}, collectionPolicyScope{},
+		[]sequenceDeclarationSpec{declaration("source-1", 2, "id"), declaration("source-2", 4, "name")},
+		parseCompositionDocument(t, "source-1", "left: true\n"),
+		parseCompositionDocument(t, "source-2", "right: true\n"),
+	)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict || diagnostics[0].Path.String() != "/records" {
+		t.Fatalf("conflicting policy-only declarations = %#v", diagnostics)
+	}
+	if diagnostics[0].Primary == nil || len(diagnostics[0].Related) != 1 {
+		t.Fatalf("declaration conflict lacks both locations: %#v", diagnostics[0])
+	}
+
+	composed, diagnostics := composeDocumentsWithCollectionPolicy(
+		sequencePolicy{}, collectionPolicyScope{},
+		[]sequenceDeclarationSpec{declaration("source-1", 2, "tenant", "id"), declaration("source-2", 4, "id", "tenant")},
+		parseCompositionDocument(t, "source-1", "records: [{tenant: true, id: null}, {tenant: \"alpha\", id: 1}]\n"),
+		parseCompositionDocument(t, "source-2", "records: [{id: 1.0, tenant: \"beta\"}, {id: \"1\", tenant: \"alpha\"}]\n"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose normalized compound identities: %#v", diagnostics)
+	}
+	value, present := documentAtPath(composed.root, path)
+	if !present || len(value.Sequence) != 4 {
+		t.Fatalf("compound identity records = %#v, %v; want four distinct records", value, present)
+	}
+
+	_, diagnostics = composeDocumentsWithCollectionPolicy(
+		sequencePolicy{}, collectionPolicyScope{},
+		[]sequenceDeclarationSpec{declaration("source-1", 2, "id")},
+		parseCompositionDocument(t, "source-1", "records: [{id: 1}]\n"),
+		parseCompositionDocument(t, "source-2", "records: [{id: 1.0}]\n"),
+	)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeConflict || diagnostics[0].Path.String() != "/records" {
+		t.Fatalf("equivalent numeric peer identities = %#v", diagnostics)
+	}
+}
+
+func TestComposeDocumentsReplacementDoesNotBorrowLowerYAMLIdentity(t *testing.T) {
+	path := Keys("records")
+	lower := collectionPolicyScope{collections: map[string]collectionPolicyEntry{
+		path.String(): {
+			destination: path,
+			policy:      collectionPolicy{identityFields: []string{"id"}, identityPresent: true},
+		},
+	}}
+	declaration := sequenceDeclarationSpec{destination: path, mode: sequenceModeReplace, modePresent: true}
+	_, diagnostics := composeDocumentsWithCollectionPolicy(
+		sequencePolicy{}, lower, []sequenceDeclarationSpec{declaration},
+		parseCompositionDocument(t, "source-1", "records: [{name: first}]\n"),
+		parseCompositionDocument(t, "source-2", "records: [{name: second}]\n"),
+	)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeConflict || diagnostics[0].Path.String() != "/records" {
+		t.Fatalf("replacement peers borrowing lower identity = %#v", diagnostics)
+	}
+
+	identityReplacement := sequenceDeclarationSpec{
+		destination: path, identityFields: []string{"name"}, identityPresent: true,
+		mode: sequenceModeReplace, modePresent: true,
+	}
+	composed, diagnostics := composeDocumentsWithCollectionPolicy(
+		sequencePolicy{}, lower, []sequenceDeclarationSpec{identityReplacement},
+		parseCompositionDocument(t, "source-1", "records: [{name: first}]\n"),
+		parseCompositionDocument(t, "source-2", "records: [{name: second}]\n"),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("replacement with a new identity declaration: %#v", diagnostics)
+	}
+	resolved := composed.collectionPolicies.collections[path.String()].policy
+	if !reflect.DeepEqual(resolved.identityFields, []string{"name"}) || !resolved.identityPresent {
+		t.Fatalf("replacement collection identity = %#v; want name", resolved)
+	}
+
+	_, diagnostics = composeDocumentsWithCollectionPolicy(
+		mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}}), lower,
+		[]sequenceDeclarationSpec{declaration},
+		parseCompositionDocument(t, "source-1", "records: [{name: replacement}]\n"),
+	)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeInvalid || diagnostics[0].Path.String() != "/records/0/id" {
+		t.Fatalf("replacement ignored application identity constraint = %#v", diagnostics)
+	}
+}
+
 func TestComposeDocumentsReportsAssignedPathForMalformedRegisteredSequenceContribution(t *testing.T) {
 	_, diagnostics := composeDocumentsWithPolicy(
-		sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+		mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}}),
 		parseCompositionDocument(t, "source-1", "records: [{id: first}]\n"),
 		parseCompositionDocument(t, "source-2", "records: [{name: malformed}]\n"),
 	)
-	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeInvalid || diagnostics[0].Path.String() != "/records/1" {
-		t.Fatalf("diagnostics = %#v, want invalid item at /records/1", diagnostics)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeInvalid || diagnostics[0].Path.String() != "/records/1/id" {
+		t.Fatalf("diagnostics = %#v, want invalid identity field at /records/1/id", diagnostics)
 	}
 	if diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "source-2" {
 		t.Fatalf("malformed item location = %#v, want source-2", diagnostics[0].Primary)
@@ -420,7 +616,7 @@ func TestComposeDocumentsRejectsRegisteredDuplicateIdentities(t *testing.T) {
 				inputs = append(inputs, parseCompositionDocument(t, "source-2", test.second))
 			}
 			_, diagnostics := composeDocumentsWithPolicy(
-				sequencePolicy{identityFields: map[string]string{"/records": "id"}}, inputs...,
+				mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}}), inputs...,
 			)
 			if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeConflict || diagnostics[0].Path.String() != "/records" {
 				t.Fatalf("diagnostics = %#v, want duplicate conflict at /records", diagnostics)
@@ -438,9 +634,12 @@ func TestComposeDocumentsRejectsRegisteredDuplicateIdentities(t *testing.T) {
 }
 
 func TestComposeDocumentsSkipsMissingAndNonSequenceRegistrations(t *testing.T) {
-	policy := sequencePolicy{identityFields: map[string]string{
-		"/absent": "id", "/not-a-sequence": "id", "/catalog": "id", "/catalog/records": "id",
-	}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{
+		{selector: sequenceIdentitySelector{literalSequenceSelector("absent")}, identityFields: []string{"id"}},
+		{selector: sequenceIdentitySelector{literalSequenceSelector("not-a-sequence")}, identityFields: []string{"id"}},
+		{selector: sequenceIdentitySelector{literalSequenceSelector("catalog")}, identityFields: []string{"id"}},
+		{selector: sequenceIdentitySelector{literalSequenceSelector("catalog"), literalSequenceSelector("records")}, identityFields: []string{"id"}},
+	})
 	composed, diagnostics := composeDocumentsWithPolicy(policy, parseCompositionDocument(t, "source-1", `
 not-a-sequence: null
 catalog:
@@ -454,7 +653,7 @@ catalog:
 	}
 
 	composed, diagnostics = composeDocumentsWithPolicy(
-		sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+		mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}}),
 		parseCompositionDocument(t, "source-1", "records: []\n"),
 		parseCompositionDocument(t, "source-2", "records: []\n"),
 	)
@@ -471,7 +670,7 @@ catalog:
 
 func TestComposeDocumentsKeepsUnregisteredSequenceConflicts(t *testing.T) {
 	_, diagnostics := composeDocumentsWithPolicy(
-		sequencePolicy{identityFields: map[string]string{"/registered": "id"}},
+		mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("registered")}, identityFields: []string{"id"}}}),
 		parseCompositionDocument(t, "source-1", "unregistered: [one]\n"),
 		parseCompositionDocument(t, "source-2", "unregistered: [two]\n"),
 	)
@@ -491,7 +690,7 @@ func TestComposeDocumentsKeepsNonSequenceRegisteredOverlapsConflicting(t *testin
 	for _, test := range tests {
 		t.Run(test.name, func(t *testing.T) {
 			_, diagnostics := composeDocumentsWithPolicy(
-				sequencePolicy{identityFields: map[string]string{"/records": "id"}},
+				mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}}),
 				parseCompositionDocument(t, "source-1", test.first),
 				parseCompositionDocument(t, "source-2", test.second),
 			)

internal/engine/destination_accounting_test.go

@@ -34,7 +34,7 @@ func TestDestinationPlacementCountsAgainstSharedNodeBudget(t *testing.T) {
 		t.Run(test.name, func(t *testing.T) {
 			t.Parallel()
 			accounting := &importAccounting{nodes: limits.nodes - perInput + test.delta}
-			composition, _, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{
+			composition, _, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{{
 				source: empty, destination: destination,
 			}}}, 1, nil, accounting)
 			if test.wantError {
@@ -62,7 +62,7 @@ func TestMultipleMountedInputsSharePlacementCharges(t *testing.T) {
 	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)
+	composition, _, _, diagnostics := testAcquireUnderlayGroup(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)
 	}
@@ -107,7 +107,7 @@ id: parent
 	} {
 		t.Run(test.name, func(t *testing.T) {
 			accounting := &importAccounting{nodes: limits.nodes - wantNodes + test.delta}
-			composition, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{
+			composition, sources, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{{
 				source: File(mainPath), imports: true, destination: destination, placementMode: placementModeSequenceItem,
 			}, {
 				source: Mapping("other", map[string]any{"id": "other"}), destination: otherDestination, placementMode: placementModeSequenceItem,
@@ -160,7 +160,7 @@ func TestImportedEmptyBodiesChargeEachDestinationWrapper(t *testing.T) {
 		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{{
+			composition, sources, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{{
 				source: mainSource, imports: true, destination: destination,
 			}}}, 1, nil, accounting)
 			if test.wantError {
@@ -387,7 +387,7 @@ func TestNoSourceAndRootPlacementAddNoWrapperCharges(t *testing.T) {
 	t.Parallel()
 
 	accounting := &importAccounting{}
-	composition, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{
+	composition, sources, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{
 		{source: NoSource(), destination: Keys("absent")},
 		{source: Mapping("root", map[string]any{})},
 	}}, 1, nil, accounting)
@@ -431,7 +431,13 @@ func TestSelectedOverlayAndCLIUsePlacementNodeCharges(t *testing.T) {
 			overrides: []Override{override},
 		}
 		accounting := &importAccounting{nodes: limits.nodes - baseNodes - overrideNodes + 1}
-		_, diagnostics := assembleLayeredInput(request, assembledInput{}, accounting)
+		input, diagnostics := assembleLayeredInput(request, assembledInput{}, accounting)
+		if len(diagnostics) != 0 {
+			t.Fatalf("assembly diagnostics = %#v", diagnostics)
+		}
+		_, diagnostics = preparePostStructuralOverrides(overridePreparationInput{
+			root: input.document, inputBytes: accounting.bytes, inputNodes: accounting.nodes,
+		}, input.sources, request.overrides, nil, limits)
 		if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverrideLimitExceeded {
 			t.Fatalf("override diagnostics = %#v", diagnostics)
 		}

internal/engine/destination_integration_test.go

@@ -197,8 +197,8 @@ func TestLayeredItemVersionProtectionTracksAssignedPeerIndexes(t *testing.T) {
 	t.Parallel()
 
 	definition := Definition[map[string]any]{
-		Version:               &VersionRule{Path: Keys("schema", "version"), Check: func(Version, *Validation) error { return nil }},
-		sequenceRegistrations: []sequenceRegistration{{path: Keys("catalog", "entries"), identityField: "id"}},
+		Version:                       &VersionRule{Path: Keys("schema", "version"), Check: func(Version, *Validation) error { return nil }},
+		sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("catalog"), literalSequenceSelector("entries")}, identityFields: []string{"id"}}},
 	}
 	item := func(label string, value map[string]any) Input {
 		return Input{Source: Mapping(label, value), Destination: Keys("catalog", "entries"), placementMode: placementModeSequenceItem}
@@ -209,7 +209,7 @@ func TestLayeredItemVersionProtectionTracksAssignedPeerIndexes(t *testing.T) {
 	main := item("main", map[string]any{"id": "main", "schema": map[string]any{"version": "v1"}})
 
 	t.Run("same assigned main path is protected", func(t *testing.T) {
-		_, err := LoadLayered(main, testSecretBinding(), options(item("underlay", map[string]any{"id": "underlay", "schema": nil})))
+		_, err := LoadLayered(main, testSecretBinding(), options(item("underlay", map[string]any{"id": "main", "schema": nil})))
 		if got := groupedErrorCode(t, err); got != CodeUnderlayVersion {
 			t.Fatalf("protected item claim code = %s, want %s", got, CodeUnderlayVersion)
 		}
@@ -224,7 +224,7 @@ func TestLayeredItemVersionProtectionTracksAssignedPeerIndexes(t *testing.T) {
 			t.Fatalf("unrelated appended peer rejected: %v", err)
 		}
 		entries := layeredMapValue(t, testLoaded(loaded).Config, "catalog", "entries").([]any)
-		if len(entries) != 1 || entries[0].(map[string]any)["id"] != "main" {
+		if len(entries) != 3 || entries[0].(map[string]any)["id"] != "first" || entries[1].(map[string]any)["id"] != "peer" || entries[2].(map[string]any)["id"] != "main" {
 			t.Fatalf("main item projection = %#v", entries)
 		}
 	})

internal/engine/directives.go

@@ -9,29 +9,104 @@ import (
 
 const directiveKey = "configkit"
 
+type rootDirectiveContext uint8
+
+const (
+	rootDirectiveContextImportsOnly rootDirectiveContext = iota + 1
+	rootDirectiveContextSource
+	rootDirectiveContextOverlay
+	rootDirectiveContextLayered
+)
+
+type rootDirectiveExtraction struct {
+	body             *document.Node
+	imports          []importDeclarationSpec
+	sequences        []sequenceDeclarationSpec
+	importsPresent   bool
+	sequencesPresent bool
+}
+
 func splitImportDirectives(root *document.Node) (*document.Node, []importDeclarationSpec, []Diagnostic) {
+	extracted, diagnostics := extractRootDirectives(root, rootDirectiveContextImportsOnly)
+	if len(diagnostics) != 0 {
+		return nil, nil, diagnostics
+	}
+	return extracted.body, extracted.imports, nil
+}
+
+func extractRootDirectives(root *document.Node, context rootDirectiveContext) (rootDirectiveExtraction, []Diagnostic) {
+	if root == nil {
+		return rootDirectiveExtraction{}, nil
+	}
 	body := document.Clone(root)
-	var declarations []importDeclarationSpec
 	directiveIndex := -1
 	for index, entry := range body.Mapping {
 		if entry.Key != directiveKey {
 			continue
 		}
 		directiveIndex = index
-		parsed, diagnostics := parseImportSpecificationDirective(entry.Value, Keys(directiveKey))
+		extracted, diagnostics := parseRootDirectiveBlock(entry.Value, Keys(directiveKey), context)
 		if len(diagnostics) != 0 {
-			return nil, nil, diagnostics
+			return rootDirectiveExtraction{}, diagnostics
 		}
-		declarations = parsed
-		break
-	}
-	if directiveIndex >= 0 {
-		body.Mapping = append(body.Mapping[:directiveIndex], body.Mapping[directiveIndex+1:]...)
+		extracted.body = body
+		if directiveIndex >= 0 {
+			extracted.body.Mapping = append(extracted.body.Mapping[:directiveIndex], extracted.body.Mapping[directiveIndex+1:]...)
+		}
+		if diagnostics := nestedDirectiveDiagnostics(extracted.body, Path{}); len(diagnostics) != 0 {
+			return rootDirectiveExtraction{}, diagnostics
+		}
+		return extracted, nil
 	}
 	if diagnostics := nestedDirectiveDiagnostics(body, Path{}); len(diagnostics) != 0 {
-		return nil, nil, diagnostics
+		return rootDirectiveExtraction{}, diagnostics
 	}
-	return body, declarations, nil
+	return rootDirectiveExtraction{body: body}, nil
+}
+
+func parseRootDirectiveBlock(node *document.Node, directivePath Path, context rootDirectiveContext) (rootDirectiveExtraction, []Diagnostic) {
+	if node == nil || node.Kind != document.Mapping {
+		return rootDirectiveExtraction{}, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, directivePath, "configuration directive must be a mapping", node)}
+	}
+	var extracted rootDirectiveExtraction
+	var diagnostics []Diagnostic
+	for _, entry := range node.Mapping {
+		fieldPath := directivePath.Key(entry.Key)
+		switch entry.Key {
+		case "imports":
+			extracted.importsPresent = true
+			if context == rootDirectiveContextOverlay {
+				diagnostics = append(diagnostics, nodeImportDiagnostic(CodeOverlayDirective, fieldPath, "overlays cannot contain imports", entry.Value))
+				continue
+			}
+			if context != rootDirectiveContextImportsOnly && context != rootDirectiveContextSource && context != rootDirectiveContextLayered {
+				diagnostics = append(diagnostics, nodeImportDiagnostic(CodeImportInvalid, fieldPath, "directive extraction context is invalid", entry.Value))
+				continue
+			}
+			parsed, issues := parseImportDeclarations(entry.Value, fieldPath)
+			extracted.imports = append(extracted.imports, parsed...)
+			diagnostics = append(diagnostics, issues...)
+		case "sequences":
+			extracted.sequencesPresent = true
+			if context == rootDirectiveContextImportsOnly {
+				diagnostics = append(diagnostics, sequenceDeclarationDiagnostic(fieldPath, "sequence declarations are not enabled in this extraction context", entry.Value))
+				continue
+			}
+			if context != rootDirectiveContextSource && context != rootDirectiveContextOverlay && context != rootDirectiveContextLayered {
+				diagnostics = append(diagnostics, sequenceDeclarationDiagnostic(fieldPath, "directive extraction context is invalid", entry.Value))
+				continue
+			}
+			parsed, issues := parseSequenceDeclarationDirective(entry.Value, fieldPath)
+			extracted.sequences = append(extracted.sequences, parsed...)
+			diagnostics = append(diagnostics, issues...)
+		default:
+			diagnostics = append(diagnostics, nodeImportDiagnostic(CodeImportInvalid, fieldPath, "configuration directive field is not recognized", entry.Value))
+		}
+	}
+	if len(diagnostics) != 0 {
+		return rootDirectiveExtraction{}, canonicalDiagnostics(diagnostics)
+	}
+	return extracted, nil
 }
 
 func nestedDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic {
@@ -91,10 +166,11 @@ func fragmentVersionClaimWithIndex(root *document.Node, rule *VersionRule, sourc
 				return current
 			}
 			if assigned, found := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: currentPath.String()}]; found {
-				if index < assigned.start || index >= assigned.end {
+				projected, ok := assigned.inputForOutput(index)
+				if !ok {
 					return nil
 				}
-				index -= assigned.start
+				index = projected
 			}
 			if index < 0 || index >= len(current.Sequence) {
 				return nil
@@ -143,24 +219,28 @@ func nodeImportDiagnostic(code Code, path Path, message string, node *document.N
 	return Diagnostic{Code: code, Severity: SeverityError, Path: path, Message: message, Primary: &location}
 }
 
-func overlayDirectiveDiagnostics(node *document.Node, current Path) []Diagnostic {
+func overlayDirectiveDiagnostics(node *document.Node, current Path, allowSequences ...bool) []Diagnostic {
+	sequencesAllowed := len(allowSequences) != 0 && allowSequences[0]
 	if node.Kind == document.Mapping {
 		for _, entry := range node.Mapping {
 			childPath := current.Key(entry.Key)
 			if entry.Key == directiveKey {
+				if sequencesAllowed && len(current.segments) == 0 && entry.Value != nil && entry.Value.Kind == document.Mapping && len(entry.Value.Mapping) == 1 && entry.Value.Mapping[0].Key == "sequences" {
+					continue
+				}
 				location := publicLocation(entry.KeyLocation)
 				return []Diagnostic{{
 					Code: CodeOverlayDirective, Severity: SeverityError, Path: childPath,
-					Message: "overlays cannot contain configuration directives", Primary: &location,
+					Message: "overlays may contain only root collection sequence declarations", Primary: &location,
 				}}
 			}
-			if diagnostics := overlayDirectiveDiagnostics(entry.Value, childPath); len(diagnostics) != 0 {
+			if diagnostics := overlayDirectiveDiagnostics(entry.Value, childPath, sequencesAllowed); len(diagnostics) != 0 {
 				return diagnostics
 			}
 		}
 	} else if node.Kind == document.Sequence {
 		for index, child := range node.Sequence {
-			if diagnostics := overlayDirectiveDiagnostics(child, current.Index(index)); len(diagnostics) != 0 {
+			if diagnostics := overlayDirectiveDiagnostics(child, current.Index(index), sequencesAllowed); len(diagnostics) != 0 {
 				return diagnostics
 			}
 		}
@@ -189,3 +269,72 @@ func disabledDirectiveDiagnostics(node *document.Node, path Path) []Diagnostic {
 	}
 	return diagnostics
 }
+
+func disabledRootImportDiagnostics(node *document.Node) []Diagnostic {
+	if node == nil || node.Kind != document.Mapping {
+		return nil
+	}
+	var rootDirective *document.Node
+	var rootLocation document.Location
+	var foundRootDirective bool
+	for index := range node.Mapping {
+		if node.Mapping[index].Key == directiveKey {
+			rootDirective = node.Mapping[index].Value
+			rootLocation = node.Mapping[index].KeyLocation
+			foundRootDirective = true
+			break
+		}
+	}
+	if foundRootDirective {
+		if rootDirective == nil || rootDirective.Kind != document.Mapping {
+			return disabledDirectiveDiagnostic(rootLocation)
+		}
+		for _, directive := range rootDirective.Mapping {
+			if directive.Key == "imports" {
+				return disabledDirectiveDiagnostic(rootLocation)
+			}
+		}
+	}
+	for _, entry := range node.Mapping {
+		if entry.Key == directiveKey {
+			continue
+		}
+		if diagnostic := disabledNestedDirectiveDiagnostics(entry.Value, Path{}.Key(entry.Key)); len(diagnostic) != 0 {
+			return diagnostic
+		}
+	}
+	return nil
+}
+
+func disabledNestedDirectiveDiagnostics(node *document.Node, path Path) []Diagnostic {
+	if node.Kind == document.Mapping {
+		for _, entry := range node.Mapping {
+			childPath := path.Key(entry.Key)
+			if entry.Key == directiveKey {
+				location := Location{SourceID: entry.KeyLocation.SourceID, Line: entry.KeyLocation.Line, Column: entry.KeyLocation.Column}
+				return []Diagnostic{{
+					Code: CodeImportDisabled, Severity: SeverityError, Path: childPath,
+					Message: "configuration directives require imports to be enabled", Primary: &location,
+				}}
+			}
+			if diagnostics := disabledNestedDirectiveDiagnostics(entry.Value, childPath); len(diagnostics) != 0 {
+				return diagnostics
+			}
+		}
+	} else if node.Kind == document.Sequence {
+		for index, child := range node.Sequence {
+			if diagnostics := disabledNestedDirectiveDiagnostics(child, path.Index(index)); len(diagnostics) != 0 {
+				return diagnostics
+			}
+		}
+	}
+	return nil
+}
+
+func disabledDirectiveDiagnostic(location document.Location) []Diagnostic {
+	public := Location{SourceID: location.SourceID, Line: location.Line, Column: location.Column}
+	return []Diagnostic{{
+		Code: CodeImportDisabled, Severity: SeverityError, Path: Keys(directiveKey),
+		Message: "configuration directives require imports to be enabled", Primary: &public,
+	}}
+}

internal/engine/explain.go

@@ -76,20 +76,55 @@ func (r *Inspection) Explain(path Path) (Explanation, bool) {
 
 	// Intermediate input replacements do not permanently suppress defaults:
 	// decoding applies them to the final input tree. Show that reconciliation
-	// explicitly, including canonical scalar conversions, before domain changes.
+	// explicitly before typed CLI contributions and domain resolution.
+	decodedInput := r.preCLI
+	decodedOrigins := r.preCLIOrigins
 	replayed, _ := documentAtPath(working, path)
-	decoded, _ := documentAtPathWithLookup(r.input, path, r.immutableLookup)
+	decoded, _ := documentAtPathWithLookup(decodedInput, path, r.immutableLookup)
 	if !configurationValuesEqual(replayed, decoded) {
+		origin := cloneOrigin(decodedOrigins[path.String()])
+		origin.Operation = ChangeDecoding
+		explanation.History = append(explanation.History, ValueChange{
+			Before:  valueSnapshot(working, path, r.secrets),
+			After:   valueSnapshotWithLookup(decodedInput, path, r.secrets, r.immutableLookup),
+			Origin:  origin,
+			Reasons: []string{"applied retained defaults and canonical typed decoding"},
+		})
+	}
+
+	working = document.Clone(decodedInput)
+	for _, application := range r.postDecodeApps {
+		operationPath, relevant := applicationOperationPath(application, path, r.immutableLookup)
+		var before ValueSnapshot
+		if relevant {
+			before = valueSnapshot(working, path, r.secrets)
+		}
+		applyHistoryApplication(&working, application, replayIndex)
+		if !relevant {
+			continue
+		}
+		after := valueSnapshot(working, path, r.secrets)
+		if !before.Present && !after.Present {
+			continue
+		}
+		explanation.History = append(explanation.History, ValueChange{
+			Before: before,
+			After:  after,
+			Origin: historyApplicationOrigin(application, operationPath, r.immutableLookup),
+		})
+	}
+	replayed, _ = documentAtPath(working, path)
+	effectiveInput, _ := documentAtPathWithLookup(r.input, path, r.immutableLookup)
+	if !configurationValuesEqual(replayed, effectiveInput) {
 		origin := cloneOrigin(r.inputOrigins[path.String()])
 		origin.Operation = ChangeDecoding
 		explanation.History = append(explanation.History, ValueChange{
 			Before:  valueSnapshot(working, path, r.secrets),
 			After:   valueSnapshotWithLookup(r.input, path, r.secrets, r.immutableLookup),
 			Origin:  origin,
-			Reasons: []string{"applied retained defaults and canonical typed decoding"},
+			Reasons: []string{"applied the typed CLI assignment"},
 		})
 	}
-
 	working = document.Clone(r.input)
 	for _, snapshot := range r.resolutionReplay {
 		relevant := pathsIntersect(snapshot.change.Path, path)

internal/engine/explain_test.go

@@ -351,6 +351,10 @@ func TestExplanationReconcilesDefaultsAfterInputReplacement(t *testing.T) {
 					opts.Overlay = "p"
 				}
 				result, err := testLoad(File(main), opts)
+				if cli && base == "replaced-text" {
+					requireSecretLoadCode(t, err, CodeDecodeType)
+					return
+				}
 				if err != nil {
 					t.Fatal(err)
 				}
@@ -360,6 +364,18 @@ func TestExplanationReconcilesDefaultsAfterInputReplacement(t *testing.T) {
 						t.Fatal("missing explanation")
 					}
 					last := explanation.History[len(explanation.History)-1]
+					if cli && path.String() == "/m" {
+						if last.After != explanation.Effective || last.Origin.Layer != LayerCLI || last.Origin.Operation != "" {
+							t.Fatalf("CLI assignment was not the final history event: %#v", explanation)
+						}
+						continue
+					}
+					if cli && path.String() == "/m/a" {
+						if explanation.Effective.Present {
+							t.Fatalf("CLI map override retained descendants discarded by source null: %#v", explanation)
+						}
+						continue
+					}
 					if last.After != explanation.Effective || last.Origin.Operation != ChangeDecoding {
 						t.Fatalf("history does not reconcile final value: %#v", explanation)
 					}

internal/engine/final_identity.go

@@ -0,0 +1,51 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+func validateFinalSequenceIdentities(root *document.Node, policy sequencePolicy) []Diagnostic {
+	if root == nil || policy.selectorTrie == nil {
+		return nil
+	}
+	var diagnostics []Diagnostic
+	var visit func(*document.Node, Path, []*sequenceSelectorTrie)
+	visit = func(node *document.Node, path Path, states []*sequenceSelectorTrie) {
+		if node == nil {
+			return
+		}
+		if node.Kind == document.Sequence {
+			var fields []string
+			for _, state := range states {
+				if state.terminal {
+					fields = state.fields
+					break
+				}
+			}
+			if fields != nil {
+				_, issues := validateNormalizedSequenceIdentityFrom(node, path, fields, sequenceIdentityDiagnosticCodes{
+					invalid: CodeSequenceInvalid, conflict: CodeSequenceConflict,
+				}, 0, sequencePayloadRecord)
+				diagnostics = append(diagnostics, issues...)
+			}
+			return
+		}
+		if node.Kind != document.Mapping {
+			return
+		}
+		for _, entry := range node.Mapping {
+			next := make([]*sequenceSelectorTrie, 0, len(states)*2)
+			for _, state := range states {
+				if literal := state.literals[entry.Key]; literal != nil {
+					next = append(next, literal)
+				}
+				if state.wildcard != nil {
+					next = append(next, state.wildcard)
+				}
+			}
+			if len(next) != 0 {
+				visit(entry.Value, path.Key(entry.Key), next)
+			}
+		}
+	}
+	visit(root, Path{}, []*sequenceSelectorTrie{policy.selectorTrie})
+	return canonicalDiagnostics(diagnostics)
+}

internal/engine/history.go

@@ -42,15 +42,15 @@ func (c *retainedNodeCounter) add(root *document.Node) bool {
 
 // History applications borrow immutable policy-validated input trees. Metadata
 // records answer presence and origin queries; replay reconstructs value changes.
-// Replay reconciles with canonical decoding before domain resolution so both
-// contracts agree on the effective result without retaining a tree per field.
+// Replay reconciles with canonical decoding, applies supplied CLI contributions,
+// then records domain resolution without retaining a tree per field.
 type historyApplication struct {
 	layer           Layer
 	path            Path
 	value           *document.Node
 	origin          Origin
 	sequences       []sequenceHistoryContribution
-	sequencesByPath map[string]sequenceHistoryContribution
+	sequencesByPath map[string]sequenceHistoryContributionIndex
 }
 
 func cloneHistoryApplications(values []historyApplication) []historyApplication {
@@ -92,7 +92,14 @@ func walkHistoryApplication(application historyApplication, visit func(local, ef
 			for index, child := range node.Sequence {
 				effectiveIndex := index
 				if projected {
-					effectiveIndex += contribution.offset
+					if contribution.mode == sequenceHistoryMapped {
+						effectiveIndex = contribution.outputForInput(index)
+						if effectiveIndex < 0 {
+							continue
+						}
+					} else {
+						effectiveIndex += contribution.offset
+					}
 				}
 				walk(child, local.Index(index), effective.Index(effectiveIndex))
 			}
@@ -112,7 +119,18 @@ func historyApplicationLocalPath(application historyApplication, effective Path)
 	for _, segment := range relative.segments {
 		if contribution, found := sequenceHistoryAt(application.sequencesByPath, local); found {
 			index, valid := schemaIndex(segment)
-			if !valid || segment.kind == pathSegmentKey || index < contribution.offset || index >= contribution.offset+contribution.length {
+			if !valid || segment.kind == pathSegmentKey {
+				return Path{}, false
+			}
+			if contribution.mode == sequenceHistoryMapped {
+				inputIndex := contribution.inputForOutput(index)
+				if inputIndex < 0 {
+					return Path{}, false
+				}
+				local = local.Index(inputIndex)
+				continue
+			}
+			if index < contribution.offset || index >= contribution.offset+contribution.length {
 				return Path{}, false
 			}
 			local = local.Index(index - contribution.offset)
@@ -149,6 +167,16 @@ func applicationOperationPath(application historyApplication, query Path, lookup
 					return container, true
 				}
 			}
+			indexed, _ := sequenceHistoryAt(application.sequencesByPath, contribution.path)
+			if indexed.mode == sequenceHistoryMapped && len(query.segments) > len(container.segments) {
+				outputIndex, valid := schemaIndex(query.segments[len(container.segments)])
+				_, replaced := indexed.replacedOutputs[outputIndex]
+				if valid && replaced {
+					if _, present := documentAtPathWithLookup(application.value, local, lookup); !ok || !present {
+						return container.Index(outputIndex), true
+					}
+				}
+			}
 			if !ok {
 				continue
 			}
@@ -206,14 +234,14 @@ func applyHistoryApplication(root **document.Node, application historyApplicatio
 		mergeHistoryDocumentAtPath(root, application.value, Path{}, index, application.sequencesByPath)
 		return
 	}
-	mergeHistoryAtPath(root, application.path, application.value, index)
+	mergeHistoryAtPath(root, application.path, application.value, index, application.sequencesByPath)
 }
 
 func mergeHistoryDocument(target **document.Node, incoming *document.Node, index *mappingIndex) {
 	mergeHistoryDocumentAtPath(target, incoming, Path{}, index, nil)
 }
 
-func mergeHistoryDocumentAtPath(target **document.Node, incoming *document.Node, path Path, index *mappingIndex, sequences map[string]sequenceHistoryContribution) {
+func mergeHistoryDocumentAtPath(target **document.Node, incoming *document.Node, path Path, index *mappingIndex, sequences map[string]sequenceHistoryContributionIndex) {
 	if incoming == nil {
 		return
 	}
@@ -238,23 +266,53 @@ func mergeHistoryDocumentAtPath(target **document.Node, incoming *document.Node,
 	}
 }
 
-func sequenceHistoryAt(contributions map[string]sequenceHistoryContribution, path Path) (sequenceHistoryContribution, bool) {
+func sequenceHistoryAt(contributions map[string]sequenceHistoryContributionIndex, path Path) (sequenceHistoryContributionIndex, bool) {
 	contribution, found := contributions[path.String()]
 	return contribution, found
 }
 
-func indexSequenceHistoryContributions(values []sequenceHistoryContribution) map[string]sequenceHistoryContribution {
+type sequenceHistoryContributionIndex struct {
+	sequenceHistoryContribution
+	projection      sequenceItemProjectionIndex
+	replacedOutputs map[int]struct{}
+}
+
+func indexSequenceHistoryContributions(values []sequenceHistoryContribution) map[string]sequenceHistoryContributionIndex {
 	if len(values) == 0 {
 		return nil
 	}
-	index := make(map[string]sequenceHistoryContribution, len(values))
+	index := make(map[string]sequenceHistoryContributionIndex, len(values))
 	for _, value := range values {
-		index[value.path.String()] = value
+		contribution := sequenceHistoryContributionIndex{sequenceHistoryContribution: value}
+		if value.mode == sequenceHistoryMapped {
+			contribution.projection = newSequenceItemProjectionIndex(value.items)
+			contribution.replacedOutputs = make(map[int]struct{}, len(value.replacements))
+			for _, replacement := range value.replacements {
+				contribution.replacedOutputs[replacement.outputIndex] = struct{}{}
+			}
+		}
+		index[value.path.String()] = contribution
 	}
 	return index
 }
 
-func applySequenceHistory(target **document.Node, incoming *document.Node, contribution sequenceHistoryContribution) {
+func (contribution sequenceHistoryContributionIndex) outputForInput(inputIndex int) int {
+	outputIndex, ok := contribution.projection.outputForInput(inputIndex)
+	if !ok {
+		return -1
+	}
+	return outputIndex
+}
+
+func (contribution sequenceHistoryContributionIndex) inputForOutput(outputIndex int) int {
+	inputIndex, ok := contribution.projection.inputForOutput(outputIndex)
+	if !ok {
+		return -1
+	}
+	return inputIndex
+}
+
+func applySequenceHistory(target **document.Node, incoming *document.Node, contribution sequenceHistoryContributionIndex) {
 	if incoming == nil || incoming.Kind != document.Sequence {
 		return
 	}
@@ -262,6 +320,18 @@ func applySequenceHistory(target **document.Node, incoming *document.Node, contr
 		*target = document.Clone(incoming)
 		return
 	}
+	if contribution.mode == sequenceHistoryMapped {
+		for _, projection := range contribution.items {
+			if projection.inputIndex < 0 || projection.inputIndex >= len(incoming.Sequence) || projection.outputIndex < 0 {
+				continue
+			}
+			for len((*target).Sequence) <= projection.outputIndex {
+				(*target).Sequence = append((*target).Sequence, nil)
+			}
+			(*target).Sequence[projection.outputIndex] = document.Clone(incoming.Sequence[projection.inputIndex])
+		}
+		return
+	}
 	for _, item := range incoming.Sequence {
 		(*target).Sequence = append((*target).Sequence, document.Clone(item))
 	}
@@ -275,13 +345,15 @@ func cloneSequenceHistoryContributions(values []sequenceHistoryContribution) []s
 	for index, value := range values {
 		cloned[index] = value
 		cloned[index].path = value.path.clone()
+		cloned[index].items = append([]sequenceItemProjection(nil), value.items...)
+		cloned[index].replacements = append([]sequenceItemReplacement(nil), value.replacements...)
 	}
 	return cloned
 }
 
-func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node, index *mappingIndex) {
+func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node, index *mappingIndex, sequences map[string]sequenceHistoryContributionIndex) {
 	if root == nil || *root == nil || len(path.segments) == 0 {
-		mergeHistoryDocument(root, incoming, index)
+		mergeHistoryDocumentAtPath(root, incoming, Path{}, index, sequences)
 		return
 	}
 	current := *root
@@ -292,7 +364,7 @@ func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node
 				return
 			}
 			if segmentIndex == len(path.segments)-1 {
-				mergeHistoryDocument(&current.Sequence[position], incoming, index)
+				mergeHistoryDocumentAtPath(&current.Sequence[position], incoming, Path{}, index, sequences)
 				return
 			}
 			current = current.Sequence[position]
@@ -306,7 +378,7 @@ func mergeHistoryAtPath(root **document.Node, path Path, incoming *document.Node
 			if position < 0 {
 				index.append(current, document.Entry{Key: segment.key, Value: document.Clone(incoming)})
 			} else {
-				mergeHistoryDocument(&current.Mapping[position].Value, incoming, index)
+				mergeHistoryDocumentAtPath(&current.Mapping[position].Value, incoming, Path{}, index, sequences)
 			}
 			return
 		}

internal/engine/history_sequence_test.go

@@ -10,7 +10,10 @@ import (
 )
 
 func TestSequenceHistoryReplaysAppendAtAssignedIndexes(t *testing.T) {
-	policy := sequencePolicy{identityFields: map[string]string{"/records": "id", "/other": "id"}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{
+		{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}},
+		{selector: sequenceIdentitySelector{literalSequenceSelector("other")}, identityFields: []string{"id"}},
+	})
 	first := parseCompositionDocument(t, "source-1", "records: [{id: a, value: first}]\nother: [{id: x}]\n")
 	second := parseCompositionDocument(t, "source-2", "records: [{id: b, value: second}]\nother: [{id: y}]\n")
 	composed, diagnostics := composeDocumentsWithPolicy(policy, first, second)
@@ -75,8 +78,76 @@ func TestSequenceHistoryReplaysAppendAtAssignedIndexes(t *testing.T) {
 	}
 }
 
+func TestTierSequenceHistoryReplaysSelectedOperation(t *testing.T) {
+	t.Parallel()
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{
+		selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"},
+	}})
+	for _, test := range []struct {
+		name string
+		mode sequenceMode
+	}{{"append", sequenceModeAppend}, {"upsert", sequenceModeUpsert}, {"replace", sequenceModeReplace}} {
+		t.Run(test.name, func(t *testing.T) {
+			mode := test.mode
+			lower, diagnostics := composeDocumentsWithPolicy(policy, parseCompositionDocument(t, "lower", "records: [{id: a, removed: old}, {id: b, value: old, removed: old}]\n"))
+			if len(diagnostics) != 0 {
+				t.Fatal(diagnostics)
+			}
+			secondID := "d"
+			if mode == sequenceModeUpsert {
+				secondID = "b"
+			}
+			declarations := []sequenceDeclarationSpec{{destination: Keys("records"), modePresent: true, mode: mode}}
+			higher, diagnostics := composeDocumentsWithCollectionPolicy(policy, lower.collectionPolicies, declarations,
+				parseCompositionDocument(t, "first-peer", "records: [{id: c, value: first}]\n"),
+				parseCompositionDocument(t, "second-peer", "records: [{id: "+secondID+", value: second}]\n"),
+			)
+			if len(diagnostics) != 0 {
+				t.Fatal(diagnostics)
+			}
+			assembly := newAssemblyAccumulator(lower)
+			if diagnostics := assembly.applyOverlayWithCollectionPolicy(higher.root, higher.origins, higher.collectionPolicies, higher.applications, LayerBase, policy, declarations); len(diagnostics) != 0 {
+				t.Fatal(diagnostics)
+			}
+			if len(assembly.current.applications) != 3 {
+				t.Fatalf("source applications = %d, want all three sources", len(assembly.current.applications))
+			}
+			if mode == sequenceModeUpsert {
+				query := Keys("records").Index(1).Key("value")
+				if _, relevant := applicationOperationPath(assembly.current.applications[1], query, nil); relevant {
+					t.Fatal("first peer was attributed to another peer's upserted record")
+				}
+				origin := historyApplicationOrigin(assembly.current.applications[2], query, nil)
+				if len(origin.Locations) != 1 || origin.Locations[0].SourceID != "second-peer" {
+					t.Fatalf("upsert history source = %#v", origin)
+				}
+			}
+			working := parseCompositionDocument(t, "initial", "{}\n")
+			index := new(mappingIndex)
+			for _, application := range assembly.current.applications {
+				applyHistoryApplication(&working, application, index)
+			}
+			if !configurationValuesEqual(working, assembly.current.root) {
+				t.Fatal("tier history differs from structural assembly before decoding")
+			}
+			overlay := parseCompositionDocument(t, "overlay", "records: [{id: c, value: overlay}]\n")
+			declarations[0].mode = sequenceModeUpsert
+			if diagnostics := assembly.applyOverlayWithCollectionPolicy(overlay, nil, collectionPolicyScope{}, nil, LayerOverlay, policy, declarations); len(diagnostics) != 0 {
+				t.Fatal(diagnostics)
+			}
+			applyHistoryApplication(&working, assembly.current.applications[3], index)
+			if !configurationValuesEqual(working, assembly.current.root) {
+				t.Fatal("subsequent overlay history differs from structural assembly")
+			}
+		})
+	}
+}
+
 func TestSequenceHistoryPreservesTierReplacementAndEmptyLists(t *testing.T) {
-	policy := sequencePolicy{identityFields: map[string]string{"/records": "id", "/independent": "id"}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{
+		{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}},
+		{selector: sequenceIdentitySelector{literalSequenceSelector("independent")}, identityFields: []string{"id"}},
+	})
 	first, diagnostics := composeDocumentsWithPolicy(policy,
 		parseCompositionDocument(t, "underlay-1a", "records: [{id: shared}]\nindependent: [{id: x}]\n"),
 		parseCompositionDocument(t, "underlay-1b", "records: [{id: lower}]\n"),
@@ -145,10 +216,53 @@ func TestHistoryMergeSupportsSemanticIndexedPrefixes(t *testing.T) {
 	if !present || value.Text != "new" {
 		t.Fatalf("indexed helper replay = %#v, %v", value, present)
 	}
+
+	root = parseCompositionDocument(t, "base", "records: [{id: one, helper: {items: [{id: a}]}}]\n")
+	application.value = parseCompositionDocument(t, "helper", "items: [{id: b}]\n")
+	application.sequences = []sequenceHistoryContribution{{path: Keys("items"), mode: sequenceHistoryAppend, offset: 1, length: 1}}
+	application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+	applyHistoryApplication(&root, application, new(mappingIndex))
+	items, present := documentAtPath(root, Keys("records").Index(0).Key("helper").Key("items"))
+	if !present || len(items.Sequence) != 2 {
+		t.Fatalf("indexed helper lost its local sequence operation: %#v", items)
+	}
+}
+
+func TestLayeredUpsertExplanationFollowsStructuralOrder(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		Records []map[string]any `yaml:"records"`
+	}
+	loaded, err := testGroupedLoad(loadRequest[config]{
+		main:      loadInput{source: Bytes("main", []byte("configkit:\n  sequences: [{destination: [records], key: id}]\nrecords: [{id: b, value: new-b}, {id: c, value: new-c}, {id: a, value: new-a}]\n"))},
+		underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte("records: [{id: a, value: old-a}, {id: b, value: old-b, removed: old}]\n"))}}}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	explanation, ok := loaded.Explain(Keys("records"))
+	if !ok || len(explanation.History) == 0 {
+		t.Fatal("missing collection history")
+	}
+	for _, change := range explanation.History {
+		if change.Origin.Operation == ChangeDecoding {
+			t.Fatal("structural upsert was misreported as a decoding reconciliation")
+		}
+	}
+	if last := explanation.History[len(explanation.History)-1]; last.After.YAML != explanation.Effective.YAML || last.Origin.Layer != LayerBase {
+		t.Fatalf("main contribution did not produce the effective collection: %#v", last)
+	}
+	removed, ok := loaded.Explain(Keys("records").Index(1).Key("removed"))
+	if !ok || len(removed.History) == 0 || removed.Effective.Present {
+		t.Fatalf("missing displaced field history: %#v, %v", removed, ok)
+	}
+	if last := removed.History[len(removed.History)-1]; last.After.Present || last.Origin.Layer != LayerBase || last.Origin.Operation == ChangeDecoding {
+		t.Fatalf("upsert removal attribution = %#v", last)
+	}
 }
 
 func TestProjectedSequenceHistoryAgreesAcrossMetadataAndExplanation(t *testing.T) {
-	policy := sequencePolicy{identityFields: map[string]string{"/records": "id"}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}})
 	composed, diagnostics := composeDocumentsWithPolicy(policy,
 		parseCompositionDocument(t, "first", "records: [{id: first, token: public}]"),
 		parseCompositionDocument(t, "second", "records: [{id: second, token: private}]"),
@@ -165,7 +279,7 @@ func TestProjectedSequenceHistoryAgreesAcrossMetadataAndExplanation(t *testing.T
 
 	inspection := &Inspection{
 		metadata: metadata, baseline: &document.Node{Kind: document.Mapping},
-		input: composed.root, final: composed.root, applications: composed.applications,
+		input: composed.root, preCLI: composed.root, final: composed.root, applications: composed.applications,
 	}
 	inspection.secrets = classifySecretPaths(nil, func(candidate Path) bool {
 		return reflect.DeepEqual(candidate, path)
@@ -193,7 +307,7 @@ func TestProjectedSequenceHistoryAgreesAcrossMetadataAndExplanation(t *testing.T
 }
 
 func TestReplacedProjectedSensitiveRecordRemainsRedacted(t *testing.T) {
-	policy := sequencePolicy{identityFields: map[string]string{"/records": "id"}}
+	policy := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}})
 	composed, diagnostics := composeDocumentsWithPolicy(policy,
 		parseCompositionDocument(t, "first", "records: [{id: first, token: public}]"),
 		parseCompositionDocument(t, "second", "records: [{id: second, token: PRIVATE-RECORD-CANARY}]"),
@@ -212,7 +326,7 @@ func TestReplacedProjectedSensitiveRecordRemainsRedacted(t *testing.T) {
 	finalizeMetadataPaths(&metadata, final, applications)
 	inspection := &Inspection{
 		metadata: metadata, baseline: &document.Node{Kind: document.Mapping},
-		input: final, final: final, applications: applications,
+		input: final, preCLI: final, final: final, applications: applications,
 	}
 	inspection.secrets = classifySecretPaths(nil, func(candidate Path) bool {
 		return reflect.DeepEqual(candidate, path)
@@ -230,6 +344,241 @@ func TestReplacedProjectedSensitiveRecordRemainsRedacted(t *testing.T) {
 	}
 }
 
+func TestMappedUpsertProjectsSensitiveReplacementEvidence(t *testing.T) {
+	lowerRoot := parseCompositionDocument(t, "lower", `records:
+  - id: first
+  - id: middle
+  - id: last
+    token: MAPPED-SECRET-CANARY
+`)
+	higherRoot := parseCompositionDocument(t, "higher", `records:
+  - id: last
+    token: visible
+  - id: first
+  - id: added
+`)
+	lower, _ := documentAtPath(lowerRoot, Keys("records"))
+	higher, _ := documentAtPath(higherRoot, Keys("records"))
+	combined, diagnostics := combineSequence(
+		lower, higher,
+		sequenceCombinationPolicy(sequenceModeUpsert, "id"),
+		sequenceCombinationContext{destination: Keys("records")},
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("combine diagnostics = %#v", diagnostics)
+	}
+	secretPath := Keys("records").Index(2).Key("token")
+	secretNode, present := documentAtPath(lowerRoot, Keys("records").Index(2).Key("token"))
+	if !present {
+		t.Fatal("sensitive source token is missing")
+	}
+	secretNode.Sensitive = true
+	application := historyApplication{
+		layer: LayerOverlay, value: higherRoot,
+		sequences: []sequenceHistoryContribution{{
+			path: Keys("records"), mode: sequenceHistoryMapped,
+			items: combined.higherItems, replacements: combined.replacements,
+		}},
+	}
+	application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+	applications := []historyApplication{{value: lowerRoot}, application}
+	replayed := &document.Node{Kind: document.Mapping}
+	for _, current := range applications {
+		applyHistoryApplication(&replayed, current, new(mappingIndex))
+	}
+	replayedRecords, _ := documentAtPath(replayed, Keys("records"))
+	if !reflect.DeepEqual(replayedRecords.Sequence, combined.value.Sequence) {
+		t.Fatalf("replayed value = %#v, want combination = %#v", replayedRecords.Sequence, combined.value.Sequence)
+	}
+	finalRoot := document.Clone(lowerRoot)
+	finalRecords, _ := documentAtPath(finalRoot, Keys("records"))
+	finalRecords.Sequence = document.Clone(combined.value).Sequence
+
+	var metadata Metadata
+	finalizeMetadataPaths(&metadata, finalRoot, applications)
+	inspection := &Inspection{
+		metadata: metadata, baseline: &document.Node{Kind: document.Mapping},
+		input: finalRoot, preCLI: finalRoot, final: finalRoot, applications: applications,
+	}
+	secretRule := func(candidate Path) bool { return reflect.DeepEqual(candidate, secretPath) }
+	inspection.secrets = classifySecretPaths(nil, secretRule, metadata, finalRoot, applications)
+	explanation, ok := inspection.Explain(secretPath)
+	if !ok || !explanation.Effective.Redacted {
+		t.Fatalf("mapped replacement explanation = %#v, %v", explanation, ok)
+	}
+	var rendered bytes.Buffer
+	if err := inspection.WriteExplanation(&rendered, secretPath); err != nil {
+		t.Fatal(err)
+	}
+	if strings.Contains(rendered.String(), "MAPPED-SECRET-CANARY") || !strings.Contains(rendered.String(), "[REDACTED]") {
+		t.Fatalf("mapped replacement history leaked or was not redacted: %s", rendered.String())
+	}
+}
+
+func TestSequenceHistoryReplaysCombinationEvidence(t *testing.T) {
+	tests := []struct {
+		name      string
+		operation sequenceMode
+		lower     string
+		higher    string
+	}{
+		{
+			name:      "append",
+			operation: sequenceModeAppend,
+			lower:     "records: [{id: first}, {id: last}]\n",
+			higher:    "records: [{id: added}]\n",
+		},
+		{
+			name:      "upsert",
+			operation: sequenceModeUpsert,
+			lower: `records:
+  - id: first
+    label: same
+    nested: {removed: lower}
+  - id: middle
+  - id: last
+    nested: {removed: lower}
+`,
+			higher: `records:
+  - id: last
+    nested: {kept: higher}
+  - id: first
+    label: same
+  - id: added
+`,
+		},
+		{
+			name:      "replace",
+			operation: sequenceModeReplace,
+			lower:     "records: [{id: discarded}]\n",
+			higher:    "records: [{id: replacement}]\n",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			lowerRoot := parseCompositionDocument(t, "lower", test.lower)
+			higherRoot := parseCompositionDocument(t, "higher", test.higher)
+			lower, _ := documentAtPath(lowerRoot, Keys("records"))
+			higher, _ := documentAtPath(higherRoot, Keys("records"))
+			fields := []string(nil)
+			if test.operation != sequenceModeReplace {
+				fields = []string{"id"}
+			}
+			combined, diagnostics := combineSequence(lower, higher, sequenceCombinationPolicy(test.operation, fields...), sequenceCombinationContext{destination: Keys("records")})
+			if len(diagnostics) != 0 {
+				t.Fatalf("combine diagnostics = %#v", diagnostics)
+			}
+
+			mode := sequenceHistoryMapped
+			if test.operation == sequenceModeReplace {
+				mode = sequenceHistoryReplace
+			}
+			length := 0
+			if mode == sequenceHistoryReplace {
+				length = len(combined.higherItems)
+			}
+			application := historyApplication{
+				layer: LayerOverlay,
+				value: higherRoot,
+				sequences: []sequenceHistoryContribution{{
+					path: Keys("records"), mode: mode, length: length,
+					items: combined.higherItems, replacements: combined.replacements,
+				}},
+			}
+			application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+			replayed := document.Clone(lowerRoot)
+			applyHistoryApplication(&replayed, application, new(mappingIndex))
+			got, present := documentAtPath(replayed, Keys("records"))
+			if !present || !reflect.DeepEqual(got.Sequence, combined.value.Sequence) {
+				t.Fatalf("replayed sequence = %#v, want combination = %#v", got, combined.value.Sequence)
+			}
+		})
+	}
+}
+
+func TestMappedSequenceHistoryReplacesWholeRecordsAndKeepsDisplacedEvidence(t *testing.T) {
+	lowerRoot := parseCompositionDocument(t, "lower", `records:
+  - id: first
+    label: same
+  - id: middle
+  - id: last
+    nested: {removed: LOWER-CANARY}
+`)
+	higherRoot := parseCompositionDocument(t, "higher", `records:
+  - id: last
+    nested: {kept: higher}
+  - id: first
+    label: same
+  - id: added
+`)
+	lower, _ := documentAtPath(lowerRoot, Keys("records"))
+	higher, _ := documentAtPath(higherRoot, Keys("records"))
+	combined, diagnostics := combineSequence(
+		lower, higher,
+		sequenceCombinationPolicy(sequenceModeUpsert, "id"),
+		sequenceCombinationContext{destination: Keys("records")},
+	)
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	application := historyApplication{
+		layer: LayerOverlay, value: higherRoot,
+		sequences: []sequenceHistoryContribution{{
+			path: Keys("records"), mode: sequenceHistoryMapped,
+			items: combined.higherItems, replacements: combined.replacements,
+		}},
+	}
+	application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+	clonedApplications := cloneHistoryApplications([]historyApplication{application})
+	clonedApplications[0].sequences[0].items[0].outputIndex = 99
+	clonedApplications[0].sequences[0].replacements[0].outputIndex = 99
+	if application.sequences[0].items[0].outputIndex == 99 || application.sequences[0].replacements[0].outputIndex == 99 {
+		t.Fatal("cloned mapped history aliases its source projections")
+	}
+
+	query := Keys("records").Index(2).Key("nested").Key("removed")
+	operationPath, relevant := applicationOperationPath(application, query, nil)
+	if !relevant || operationPath.String() != "/records/2" {
+		t.Fatalf("removed descendant operation = %s, %v", operationPath.String(), relevant)
+	}
+	localPath, ok := historyApplicationLocalPath(application, Keys("records").Index(2).Key("nested").Key("kept"))
+	if !ok || localPath.String() != "/records/0/nested/kept" {
+		t.Fatalf("mapped effective path localizes to %s, %v", localPath.String(), ok)
+	}
+	origin := historyApplicationOrigin(application, operationPath, nil)
+	if len(origin.Locations) != 1 || origin.Locations[0].SourceID != "higher" {
+		t.Fatalf("replacement operation origin = %#v", origin)
+	}
+	var walkedMappedPath bool
+	walkHistoryApplication(application, func(local, effective Path, _ *document.Node) {
+		if local.String() == "/records/0/nested/kept" && effective.String() == "/records/2/nested/kept" {
+			walkedMappedPath = true
+		}
+	})
+	if !walkedMappedPath {
+		t.Fatal("history walk did not project a noncontiguous incoming item")
+	}
+
+	replayed := document.Clone(lowerRoot)
+	applyHistoryApplication(&replayed, application, new(mappingIndex))
+	sequence, _ := documentAtPath(replayed, Keys("records"))
+	if _, present := documentAtPath(sequence.Sequence[2], Keys("nested", "removed")); present {
+		t.Fatal("whole-record replacement retained an omitted descendant")
+	}
+	if value, present := documentAtPath(sequence.Sequence[2], Keys("nested", "kept")); !present || value.Text != "higher" {
+		t.Fatalf("replacement descendant = %#v, %v", value, present)
+	}
+	if sequence.Sequence[1].Mapping[0].Value.Text != "middle" {
+		t.Fatal("unchanged neighboring record moved or changed")
+	}
+	if value, present := documentAtPath(lowerRoot, Keys("records").Index(2).Key("nested").Key("removed")); !present || value.Text != "LOWER-CANARY" {
+		t.Fatalf("displaced lower contribution was not retained as raw history: %#v, %v", value, present)
+	}
+	if got := application.sequences[0].replacements; !reflect.DeepEqual(got, combined.replacements) || len(got) != 2 {
+		t.Fatalf("replacement evidence lost equal-valued or noncontiguous events: %#v", got)
+	}
+}
+
 func mustParsePath(t *testing.T, value string) Path {
 	t.Helper()
 	path, err := ParsePath(value)

internal/engine/import_spec.go

@@ -193,18 +193,26 @@ func parseImportSpecificationDirective(node *document.Node, directivePath Path)
 			diagnostics = append(diagnostics, nodeImportDiagnostic(CodeImportInvalid, fieldPath, "configuration directive field is not recognized", entry.Value))
 			continue
 		}
-		if entry.Value.Kind != document.Sequence {
-			diagnostics = append(diagnostics, nodeImportDiagnostic(CodeImportInvalid, fieldPath, "imports must be a sequence", entry.Value))
+		parsed, issues := parseImportDeclarations(entry.Value, fieldPath)
+		specs = append(specs, parsed...)
+		diagnostics = append(diagnostics, issues...)
+	}
+	return specs, canonicalDiagnostics(diagnostics)
+}
+
+func parseImportDeclarations(node *document.Node, declarationPath Path) ([]importDeclarationSpec, []Diagnostic) {
+	if node == nil || node.Kind != document.Sequence {
+		return nil, []Diagnostic{nodeImportDiagnostic(CodeImportInvalid, declarationPath, "imports must be a sequence", node)}
+	}
+	var specs []importDeclarationSpec
+	var diagnostics []Diagnostic
+	for index, declarationNode := range node.Sequence {
+		spec, issues := parseImportDeclarationSpec(declarationNode, declarationPath.Index(index))
+		if len(issues) != 0 {
+			diagnostics = append(diagnostics, issues...)
 			continue
 		}
-		for index, declarationNode := range entry.Value.Sequence {
-			spec, issues := parseImportDeclarationSpec(declarationNode, fieldPath.Index(index))
-			if len(issues) != 0 {
-				diagnostics = append(diagnostics, issues...)
-				continue
-			}
-			specs = append(specs, spec)
-		}
+		specs = append(specs, spec)
 	}
 	return specs, canonicalDiagnostics(diagnostics)
 }

internal/engine/imports.go

@@ -46,12 +46,13 @@ type importAccounting struct {
 }
 
 type importTraversal struct {
-	access       *filesystemAccess
-	accounting   *importAccounting
-	limits       importLimits
-	rule         *VersionRule
-	versionState *sourceVersionState
-	defaults     importDefaults
+	access           *filesystemAccess
+	accounting       *importAccounting
+	limits           importLimits
+	rule             *VersionRule
+	versionState     *sourceVersionState
+	directiveContext rootDirectiveContext
+	defaults         importDefaults
 
 	scope        acquisitionScope
 	itemScope    bool
@@ -166,12 +167,17 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 	if versionState != nil {
 		defaults = snapshotImportDefaults(versionState.importDefaults)
 	}
+	directiveContext := rootDirectiveContextImportsOnly
+	if processing != nil && processing.directiveContext != 0 {
+		directiveContext = processing.directiveContext
+	}
 	state := importTraversal{
 		access: access, accounting: accounting, limits: limits, rule: rule, versionState: versionState,
-		defaults: defaults,
-		scope:    acquisitionScope{owner: mainNodeKey, destination: destination.clone()},
-		sources:  []SourceInfo{mainInfo},
-		active:   make(map[resourceIdentity]int), visited: visited,
+		directiveContext: directiveContext,
+		defaults:         defaults,
+		scope:            acquisitionScope{owner: mainNodeKey, destination: destination.clone()},
+		sources:          []SourceInfo{mainInfo},
+		active:           make(map[resourceIdentity]int), visited: visited,
 		importGraph: newImportInclusionGraph(),
 	}
 	if mainIsItem {
@@ -201,10 +207,12 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 	state.stack = append(state.stack, mainRoute)
 	var body *document.Node
 	var declarations []importDeclarationSpec
+	var sequenceDeclarations []sequenceDeclarationSpec
 	var diagnostics []Diagnostic
 	if processing != nil {
 		body = processing.payload
 		declarations = processing.imports
+		sequenceDeclarations = cloneSequenceDeclarations(processing.sequences)
 	} else {
 		body, declarations, diagnostics = splitImportDirectives(main.document)
 	}
@@ -213,6 +221,7 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 			state.scope.contributions = append(state.scope.contributions, acquiredContribution{
 				source: cloneSourceInfo(mainInfo), identity: mainNodeKey, role: importRoleMain,
 				scopeOwner: mainNodeKey, payload: body, document: body, processing: processing,
+				sequenceDeclarations: cloneSequenceDeclarations(sequenceDeclarations),
 			})
 			diagnostics = state.walkDeclarations(basePath, declarations, 0, Path{})
 		} else {
@@ -228,6 +237,7 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 					source: cloneSourceInfo(mainInfo), payload: body, document: placed,
 					identity: mainNodeKey, role: importRoleMain, scopeOwner: mainNodeKey,
 					destination: destination.clone(), processing: processing,
+					sequenceDeclarations: cloneSequenceDeclarations(sequenceDeclarations),
 				})
 				diagnostics = state.walkDeclarations(basePath, declarations, 0, destination)
 			}
@@ -235,9 +245,6 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 	}
 	if len(diagnostics) == 0 {
 		state.scheduleAcquisitionScopes(&state.scope)
-		if !deferAssembly {
-			diagnostics = state.composePendingItems(&state.scope)
-		}
 	}
 
 	closeErr := access.close()
@@ -250,19 +257,19 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 	if closeErr != nil {
 		return nil, cloneSourceInfos(state.sources), []Diagnostic{importDiagnostic(CodeImportRead, "configuration root could not be closed", nil)}
 	}
-	if deferAssembly {
-		acquisition := state.scope
-		if mainIsItem {
-			localScope := state.scope
-			acquisition = acquisitionScope{
-				owner: mainNodeKey, destination: destination.clone(),
-				contributions: []acquiredContribution{{
-					source: cloneSourceInfo(mainInfo), payload: body, identity: mainNodeKey,
-					role: importRoleMain, scopeOwner: mainNodeKey, destination: destination.clone(),
-					processing: processing, pendingItem: &localScope,
-				}},
-			}
+	acquisition := state.scope
+	if mainIsItem {
+		localScope := state.scope
+		acquisition = acquisitionScope{
+			owner: mainNodeKey, destination: destination.clone(),
+			contributions: []acquiredContribution{{
+				source: cloneSourceInfo(mainInfo), payload: body, identity: mainNodeKey,
+				role: importRoleMain, scopeOwner: mainNodeKey, destination: destination.clone(),
+				processing: processing, sequenceDeclarations: cloneSequenceDeclarations(sequenceDeclarations), pendingItem: &localScope,
+			}},
 		}
+	}
+	if deferAssembly {
 		if diagnostic := reservePendingItemPlacements(&acquisition, limits, accounting); diagnostic != nil {
 			return nil, cloneSourceInfos(state.sources), []Diagnostic{*diagnostic}
 		}
@@ -271,20 +278,65 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 			importGraph: state.importGraph.clone(), inputBytes: accounting.bytes, inputNodes: accounting.nodes,
 		}, cloneSourceInfos(state.sources), nil
 	}
-	if mainIsItem {
-		localScope := state.scope
+	acquired := &composedDocument{
+		acquisition: []acquisitionScope{cloneAcquisitionScope(acquisition)},
+		importGraph: state.importGraph.clone(), inputBytes: accounting.bytes, inputNodes: accounting.nodes,
+	}
+	input := assembledInput{
+		parsed: main, composition: acquired, acquisition: cloneAcquisitionScopes(acquired.acquisition),
+		sources: state.sources, versionState: versionState, accounting: accounting,
+	}
+	composed, diagnostics := composeAcquiredInputWithPolicies(input, collectionPolicyScope{}, policy)
+	return composed, cloneSourceInfos(state.sources), diagnostics
+}
+
+// composeAcquiredInputWithPolicy is the per-input adapter from retained
+// acquisition scopes to the established strict-composition behavior. It uses
+// the already acquired documents and graph; source handles are closed before
+// this handoff.
+func composeAcquiredInputWithPolicies(input assembledInput, lower collectionPolicyScope, policy sequencePolicy) (*composedDocument, []Diagnostic) {
+	if input.composition == nil || input.composition.root != nil || len(input.composition.acquisition) == 0 {
+		return input.composition, nil
+	}
+	acquired := input.composition
+	if len(acquired.acquisition) != 1 {
+		return nil, []Diagnostic{importDiagnostic(CodeImportInvalid, "acquired input has an invalid composition scope", nil)}
+	}
+	scope := cloneAcquisitionScope(acquired.acquisition[0])
+	var rule *VersionRule
+	if input.versionState != nil {
+		rule = input.versionState.effectiveRule
+	}
+	accounting := input.accounting
+	if accounting == nil {
+		accounting = &importAccounting{sources: len(input.sources), bytes: acquired.inputBytes, nodes: acquired.inputNodes}
+	}
+	traversal := importTraversal{
+		accounting: accounting,
+		limits:     defaultImportLimits(), rule: rule, versionState: input.versionState,
+		importGraph: acquired.importGraph.clone(),
+	}
+	if len(scope.contributions) == 1 && scope.contributions[0].role == importRoleMain && scope.contributions[0].pendingItem != nil {
+		main := scope.contributions[0]
+		localScope := cloneAcquisitionScope(*main.pendingItem)
+		if diagnostics := traversal.composePendingItems(&localScope, policy); len(diagnostics) != 0 {
+			return nil, prependCompositionDiagnosticPaths(diagnostics, main.destination.Index(0))
+		}
 		documents := make([]*document.Node, 0, len(localScope.contributions))
 		for _, contribution := range localScope.contributions {
 			documents = append(documents, contribution.document)
 		}
-		completed, failures := composeDocuments(documents...)
-		if len(failures) != 0 {
-			return nil, cloneSourceInfos(state.sources), prependCompositionDiagnosticPaths(failures, destination.Index(0))
+		completed, diagnostics := composeDocumentsWithCollectionPolicy(
+			policy, localScope.collectionPolicies,
+			acquiredSequenceDeclarations(localScope), documents...,
+		)
+		if len(diagnostics) != 0 {
+			return nil, prependCompositionDiagnosticPaths(diagnostics, main.destination.Index(0))
 		}
-		if versionState != nil {
-			protectionRule := versionState.localRule
-			if versionState.mode == sourceVersionModeDefault && protectionRule != nil {
-				prefix := destination.Index(0)
+		if input.versionState != nil {
+			protectionRule := input.versionState.localRule
+			if input.versionState.mode == sourceVersionModeDefault && protectionRule != nil {
+				prefix := main.destination.Index(0)
 				relative, inside := relativeHistoryPath(prefix, protectionRule.Path)
 				if !inside || !matchesPathShape(Path{segments: protectionRule.Path.segments[:len(prefix.segments)]}, prefix) {
 					protectionRule = nil
@@ -298,56 +350,84 @@ func loadImportedWithAccessTrackedAndProcessingPolicyDeferred(access *filesystem
 				if rule != nil {
 					diagnostic.Path = rule.Path.clone()
 				}
-				return nil, cloneSourceInfos(state.sources), []Diagnostic{*diagnostic}
+				return nil, []Diagnostic{*diagnostic}
 			}
 		}
 		completed.acquisition = []acquisitionScope{cloneAcquisitionScope(localScope)}
 		projectNestedEvidence(completed, localScope)
-		_, placed, err := placeDocumentWithMode(completed.root, destination, placementModeSequenceItem, body.Location, maxDocumentDepth, maxDocumentNodes)
+		_, placed, err := placeDocumentWithMode(completed.root, main.destination, placementModeSequenceItem, main.payload.Location, maxDocumentDepth, maxDocumentNodes)
 		if err != nil {
-			return nil, cloneSourceInfos(state.sources), []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, main.source.ID, "configuration exceeds the source depth or node limit after destination placement")}
+			return nil, []Diagnostic{sourceDiagnostic(CodeSourceLimitExceeded, main.source.ID, "configuration exceeds the source depth or node limit after destination placement")}
 		}
-		placementNodes := destinationWrapperNodeCountForMode(destination, placementModeSequenceItem)
-		if accounting.nodes+placementNodes > limits.nodes {
-			return nil, cloneSourceInfos(state.sources), []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", nil)}
+		if !main.placementCharged {
+			placementNodes := destinationWrapperNodeCountForMode(main.destination, placementModeSequenceItem)
+			if accounting.nodes+placementNodes > traversal.limits.nodes {
+				return nil, []Diagnostic{importDiagnostic(CodeImportLimitExceeded, "configuration exceeds the aggregate node limit", main.source.ImportedFrom)}
+			}
+			accounting.nodes += placementNodes
 		}
-		accounting.nodes += placementNodes
-		composed, failures := composeDocumentsWithPolicy(policy, placed)
-		if composed != nil {
-			synthetic := acquisitionScope{contributions: []acquiredContribution{{
-				source: cloneSourceInfo(mainInfo), payload: completed.root, document: placed,
-				identity: mainNodeKey, role: importRoleMain, scopeOwner: mainNodeKey,
-				destination: destination.clone(), processing: processing, nested: completed,
-			}}}
-			synthetic.owner = mainNodeKey
-			projectNestedEvidence(composed, synthetic)
-			projectAcquiredDestinations(composed, synthetic, state.sources)
-			composed.acquisition = []acquisitionScope{cloneAcquisitionScope(synthetic)}
-			composed.inputBytes = accounting.bytes
-			composed.inputNodes = accounting.nodes
-			composed.importGraph = state.importGraph.clone()
+		composition, diagnostics := composeDocumentsWithPolicy(policy, placed)
+		if len(diagnostics) != 0 {
+			return nil, diagnostics
 		}
-		return composed, cloneSourceInfos(state.sources), failures
+		synthetic := acquisitionScope{owner: main.scopeOwner, contributions: []acquiredContribution{{
+			source: cloneSourceInfo(main.source), payload: completed.root, document: placed,
+			identity: main.identity, role: importRoleMain, scopeOwner: main.scopeOwner,
+			destination: main.destination.clone(), processing: main.processing, nested: completed,
+		}}}
+		projectNestedEvidence(composition, synthetic)
+		projectAcquiredDestinations(composition, synthetic, input.sources)
+		composition.acquisition = []acquisitionScope{cloneAcquisitionScope(synthetic)}
+		composition.inputBytes = accounting.bytes
+		composition.inputNodes = accounting.nodes
+		composition.importGraph = acquired.importGraph.clone()
+		return composition, nil
 	}
-	documents := make([]*document.Node, 0, len(state.scope.contributions))
-	for _, contribution := range state.scope.contributions {
+	return composeAcquiredScopeWithPolicy(
+		&scope, lower, policy, acquired.importGraph, input.sources, rule, input.versionState, accounting,
+	)
+}
+
+// composeAcquiredScopeWithPolicy is shared by per-input and underlay-group
+// handoffs. Lower policy is carried separately from registered application
+// constraints; current strict composition continues to use its existing rules.
+func composeAcquiredScopeWithPolicy(
+	scope *acquisitionScope,
+	lower collectionPolicyScope,
+	policy sequencePolicy,
+	graph importInclusionGraph,
+	sources []SourceInfo,
+	rule *VersionRule,
+	versionState *sourceVersionState,
+	accounting *importAccounting,
+) (*composedDocument, []Diagnostic) {
+	traversal := importTraversal{
+		accounting: accounting, limits: defaultImportLimits(), rule: rule,
+		versionState: versionState, importGraph: graph.clone(),
+	}
+	if diagnostics := traversal.composePendingItems(scope, policy); len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	documents := make([]*document.Node, 0, len(scope.contributions))
+	for _, contribution := range scope.contributions {
 		documents = append(documents, contribution.document)
 	}
-	composed, diagnostics := composeDocumentsWithPolicy(policy, documents...)
-	if composed != nil {
-		if diagnostic := importedVersionClaim(documents, state.scope, composed, rule); diagnostic != nil {
-			return nil, cloneSourceInfos(state.sources), []Diagnostic{*diagnostic}
-		}
+	composition, diagnostics := composeDocumentsWithCollectionPolicy(
+		policy, lower, acquiredSequenceDeclarations(*scope), documents...,
+	)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
 	}
-	if composed != nil {
-		projectNestedEvidence(composed, state.scope)
-		projectAcquiredDestinations(composed, state.scope, state.sources)
-		composed.acquisition = []acquisitionScope{cloneAcquisitionScope(state.scope)}
-		composed.inputBytes = accounting.bytes
-		composed.inputNodes = accounting.nodes
-		composed.importGraph = state.importGraph.clone()
+	if diagnostic := importedVersionClaim(documents, *scope, composition, rule); diagnostic != nil {
+		return nil, []Diagnostic{*diagnostic}
 	}
-	return composed, cloneSourceInfos(state.sources), diagnostics
+	projectNestedEvidence(composition, *scope)
+	projectAcquiredDestinations(composition, *scope, sources)
+	composition.acquisition = []acquisitionScope{cloneAcquisitionScope(*scope)}
+	composition.inputBytes = accounting.bytes
+	composition.inputNodes = accounting.nodes
+	composition.importGraph = graph.clone()
+	return composition, nil
 }
 
 func reservePendingItemPlacements(scope *acquisitionScope, limits importLimits, accounting *importAccounting) *Diagnostic {
@@ -547,25 +627,37 @@ func (s *importTraversal) visitPath(candidate selectedImportCandidate, spec impo
 
 	var body *document.Node
 	var declarations []importDeclarationSpec
+	var sequenceDeclarations []sequenceDeclarationSpec
 	var diagnostics []Diagnostic
 	var processing *sourceVersionProcessingResult
+	directiveContext := s.directiveContext
+	if directiveContext == 0 {
+		directiveContext = rootDirectiveContextImportsOnly
+	}
 	if s.versionState != nil && s.versionState.mode != sourceVersionModeDefault {
 		versionDestination := destination
 		if s.itemScope {
 			versionDestination = appendDestination(s.itemPrefix.Index(0), destination)
 		}
-		processed, failures := s.versionState.process(root, sourceVersionContribution, versionDestination, sourceID, policy.placement)
+		processed, failures := s.versionState.processWithDirectiveContext(root, sourceVersionContribution, versionDestination, sourceID, policy.placement, directiveContext)
 		if len(failures) != 0 {
 			return failures
 		}
 		processing = &processed
 		body, declarations = processed.payload, processed.imports
 	} else {
-		body, declarations, diagnostics = splitImportDirectives(root)
-		if len(diagnostics) != 0 {
-			return diagnostics
+		versionDestination := destination
+		if s.itemScope {
+			versionDestination = appendDestination(s.itemPrefix.Index(0), destination)
 		}
+		processed := processSourceVersionWithDirectiveContext(root, s.rule, sourceVersionContribution, versionDestination, sourceVersionModeDefault, directiveContext)
+		if len(processed.diagnostics) != 0 {
+			return processed.diagnostics
+		}
+		processing = &processed
+		body, declarations = processed.payload, processed.imports
 	}
+	sequenceDeclarations = cloneSequenceDeclarations(processing.sequences)
 	placementDestination := destination
 	mode := placementModeMapping
 	if policy.placement == placementModeSequenceItem {
@@ -582,7 +674,7 @@ func (s *importTraversal) visitPath(candidate selectedImportCandidate, spec impo
 		s.active[identity] = len(s.stack)
 		s.visited[identity] = route
 		s.stack = append(s.stack, route)
-		diagnostics := s.visitItemSource(canonical, nodeKey, destination, relativeDestination, depth, info, body, declarations, processing)
+		diagnostics := s.visitItemSource(canonical, nodeKey, destination, relativeDestination, depth, info, body, declarations, sequenceDeclarations, processing)
 		delete(s.active, identity)
 		s.stack = s.stack[:len(s.stack)-1]
 		return diagnostics
@@ -601,6 +693,7 @@ func (s *importTraversal) visitPath(candidate selectedImportCandidate, spec impo
 		source: cloneSourceInfo(info), payload: body, document: placed,
 		identity: nodeKey, role: role, scopeOwner: s.scope.owner,
 		destination: placementDestination.clone(), relativeDestination: relativeDestination.clone(), processing: processing,
+		sequenceDeclarations: cloneSequenceDeclarations(sequenceDeclarations),
 	})
 	s.active[identity] = len(s.stack)
 	s.visited[identity] = route
@@ -631,7 +724,7 @@ func (s *importTraversal) sourceDestination(destination Path) Path {
 	return s.itemFallback.clone()
 }
 
-func (s *importTraversal) visitItemSource(canonical string, identity importNodeKey, destination, relativeDestination Path, depth int, info SourceInfo, body *document.Node, declarations []importDeclarationSpec, processing *sourceVersionProcessingResult) []Diagnostic {
+func (s *importTraversal) visitItemSource(canonical string, identity importNodeKey, destination, relativeDestination Path, depth int, info SourceInfo, body *document.Node, declarations []importDeclarationSpec, sequenceDeclarations []sequenceDeclarationSpec, processing *sourceVersionProcessingResult) []Diagnostic {
 	parentScope := s.scope
 	parentItemScope, parentPrefix, parentFallback := s.itemScope, s.itemPrefix, s.itemFallback
 	s.scope = acquisitionScope{owner: identity}
@@ -645,7 +738,7 @@ func (s *importTraversal) visitItemSource(canonical string, identity importNodeK
 	s.scope.contributions = append(s.scope.contributions, acquiredContribution{
 		source: cloneSourceInfo(info), payload: body, document: body,
 		identity: identity, role: importRoleItem, scopeOwner: identity,
-		processing: processing,
+		processing: processing, sequenceDeclarations: cloneSequenceDeclarations(sequenceDeclarations),
 	})
 	diagnostics := s.walkDeclarations(s.access.dir(canonical), declarations, depth, Path{})
 	itemScope := s.scope
@@ -672,21 +765,24 @@ func (s *importTraversal) scheduleAcquisitionScopes(scope *acquisitionScope) {
 	}
 }
 
-func (s *importTraversal) composePendingItems(scope *acquisitionScope) []Diagnostic {
+func (s *importTraversal) composePendingItems(scope *acquisitionScope, policy sequencePolicy) []Diagnostic {
 	for index := range scope.contributions {
 		contribution := &scope.contributions[index]
 		if contribution.pendingItem == nil {
 			continue
 		}
 		itemScope := contribution.pendingItem
-		if diagnostics := s.composePendingItems(itemScope); len(diagnostics) != 0 {
+		if diagnostics := s.composePendingItems(itemScope, policy); len(diagnostics) != 0 {
 			return projectItemDiagnosticPaths(diagnostics, *scope, contribution.destination, index)
 		}
 		documents := make([]*document.Node, 0, len(itemScope.contributions))
 		for _, nested := range itemScope.contributions {
 			documents = append(documents, nested.document)
 		}
-		completed, diagnostics := composeDocuments(documents...)
+		completed, diagnostics := composeDocumentsWithCollectionPolicy(
+			policy, itemScope.collectionPolicies,
+			acquiredSequenceDeclarations(*itemScope), documents...,
+		)
 		if len(diagnostics) != 0 {
 			return projectItemDiagnosticPaths(diagnostics, *scope, contribution.destination, index)
 		}
@@ -713,6 +809,18 @@ func (s *importTraversal) composePendingItems(scope *acquisitionScope) []Diagnos
 	return nil
 }
 
+func acquiredSequenceDeclarations(scope acquisitionScope) []sequenceDeclarationSpec {
+	var declarations []sequenceDeclarationSpec
+	for _, contribution := range scope.contributions {
+		projected := cloneSequenceDeclarations(contribution.sequenceDeclarations)
+		for index := range projected {
+			projected[index].destination = appendDestination(contribution.relativeDestination, projected[index].destination)
+		}
+		declarations = append(declarations, projected...)
+	}
+	return declarations
+}
+
 func importedVersionClaim(documents []*document.Node, scope acquisitionScope, composed *composedDocument, rule *VersionRule) *Diagnostic {
 	if composed == nil || rule == nil {
 		return nil
@@ -817,8 +925,13 @@ func projectNestedEvidence(composed *composedDocument, scope acquisitionScope) {
 			projectedApplications = append(projectedApplications, applications[sourceIndex])
 			continue
 		}
-		start := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: contribution.destination.String()}].start
-		prefix := contribution.destination.Index(start)
+		itemIndex := 0
+		if assigned, found := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: contribution.destination.String()}]; found {
+			if projected, ok := assigned.outputForInput(0); ok {
+				itemIndex = projected
+			}
+		}
+		prefix := contribution.destination.Index(itemIndex)
 		if sourceIndex < len(applications) {
 			outer := applications[sourceIndex]
 			structural := document.Clone(outer.value)
@@ -840,6 +953,71 @@ func projectNestedEvidence(composed *composedDocument, scope acquisitionScope) {
 		projectNestedOrigins(composed.origins, contribution.nested.root, contribution.nested.origins, prefix)
 	}
 	composed.applications = projectedApplications
+	projectNestedCollectionPolicies(composed, scope, ranges)
+}
+
+func projectNestedCollectionPolicies(composed *composedDocument, scope acquisitionScope, ranges map[sequenceRangeKey]sequenceRange) {
+	if composed == nil {
+		return
+	}
+	type itemPolicyProjection struct {
+		destination Path
+		policy      collectionPolicy
+		base        int
+	}
+	projected := make(map[string]*itemPolicyProjection)
+	var prefixLengths map[string]int
+	for sourceIndex, contribution := range scope.contributions {
+		if prefixLengths != nil && sourceIndex > 0 {
+			addSequencePrefixLengths(scope.contributions[sourceIndex-1].document, Path{}, prefixLengths)
+		}
+		if contribution.nested == nil || len(contribution.nested.collectionPolicies.collections) == 0 {
+			continue
+		}
+		key := contribution.destination.String()
+		assigned := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: key}]
+		itemIndex, found := assigned.outputForInput(0)
+		if !found {
+			// Normal composition supplies the assignment directly. For a
+			// handoff without ranges, scan each preceding tree only once.
+			if prefixLengths == nil {
+				prefixLengths = make(map[string]int)
+				for _, previous := range scope.contributions[:sourceIndex] {
+					addSequencePrefixLengths(previous.document, Path{}, prefixLengths)
+				}
+			}
+			itemIndex = prefixLengths[key]
+		}
+		working, initialized := projected[key]
+		if !initialized {
+			// Read one owned copy per destination, then add each incoming
+			// record without recopying earlier records and their scopes.
+			policy, _ := composed.collectionPolicies.at(contribution.destination)
+			working = &itemPolicyProjection{destination: contribution.destination, policy: policy, base: len(policy.recordOrder)}
+			projected[key] = working
+		}
+		working.policy.setRecordPolicyAt(working.base+itemIndex, collectionRecordPolicy{
+			owner: newCollectionRecordPolicy().owner,
+			scope: contribution.nested.collectionPolicies,
+		})
+	}
+	for _, working := range projected {
+		composed.collectionPolicies.set(working.destination, working.policy)
+	}
+}
+
+func addSequencePrefixLengths(node *document.Node, path Path, lengths map[string]int) {
+	if node == nil {
+		return
+	}
+	if node.Kind == document.Sequence {
+		lengths[path.String()] += len(node.Sequence)
+		return
+	}
+	// Contribution destinations select mapping paths, not sequence members.
+	for _, entry := range node.Mapping {
+		addSequencePrefixLengths(entry.Value, path.Key(entry.Key), lengths)
+	}
 }
 
 func projectNestedOrigins(target map[string]Origin, root *document.Node, origins map[string]Origin, prefix Path) {
@@ -875,7 +1053,12 @@ func projectAcquiredDestinations(composed *composedDocument, scope acquisitionSc
 			}
 			contributionPrefix := prefix
 			contributionInsideItem := insideItem
-			start := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: contribution.destination.String()}].start
+			itemIndex := 0
+			if assigned, found := ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: contribution.destination.String()}]; found {
+				if projected, ok := assigned.outputForInput(0); ok {
+					itemIndex = projected
+				}
+			}
 			if contribution.source.placementMode == placementModeSequenceItem {
 				container := appendDestination(contributionPrefix, contribution.destination)
 				contribution.source.Destination = container.clone()
@@ -885,7 +1068,7 @@ func projectAcquiredDestinations(composed *composedDocument, scope acquisitionSc
 					sources[position].Destination = container
 					sources[position].destinationUnresolved = false
 				}
-				contributionPrefix = appendDestination(container, Path{}.Index(start))
+				contributionPrefix = appendDestination(container, Path{}.Index(itemIndex))
 				contributionInsideItem = true
 				projectSourceVersionEvidence(contribution.processing, contributionPrefix, nil, sourceIndex)
 			} else if contributionInsideItem {
@@ -928,7 +1111,9 @@ func projectSourceVersionEvidence(processing *sourceVersionProcessingResult, des
 				}
 				item, ok := schemaIndex(path.segments[position])
 				if ok && path.segments[position].kind != pathSegmentKey {
-					path.segments[position] = pathSegment{kind: pathSegmentIndex, index: assigned.start + item}
+					if outputIndex, projected := assigned.outputForInput(item); projected {
+						path.segments[position] = pathSegment{kind: pathSegmentIndex, index: outputIndex}
+					}
 				}
 			}
 			paths[index] = path

internal/engine/imports_test.go

@@ -115,7 +115,7 @@ tasks: [{id: z-parent}]
 
 	input, diagnostics := assembleBaseInput[config](File(mainPath), Options[config]{
 		Imports:        true,
-		sequencePolicy: sequencePolicy{identityFields: map[string]string{"/tasks": "id"}},
+		sequencePolicy: mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("tasks")}, identityFields: []string{"id"}}}),
 	})
 	if len(diagnostics) != 0 {
 		t.Fatalf("assemble imports: %#v", diagnostics)
@@ -525,6 +525,141 @@ func TestLoadMainItemPlacementKeepsItsHelpersInTheItem(t *testing.T) {
 	}
 }
 
+func TestProjectAcquiredDestinationsUsesMappedSequenceItemIndex(t *testing.T) {
+	child := &composedDocument{}
+	childScope := acquisitionScope{contributions: []acquiredContribution{{
+		source: SourceInfo{ID: "nested-source"}, destination: Keys("settings"),
+	}}}
+	child.acquisition = []acquisitionScope{childScope}
+	composed := &composedDocument{sequenceRanges: []sequenceRange{{
+		sourceIndex: 0, path: Keys("records"), start: 0, end: 1,
+		items: []sequenceItemProjection{{inputIndex: 0, outputIndex: 2}},
+	}}}
+	scope := acquisitionScope{contributions: []acquiredContribution{{
+		source:      SourceInfo{ID: "outer-source", placementMode: placementModeSequenceItem},
+		destination: Keys("records"), nested: child,
+	}}}
+	sources := []SourceInfo{{ID: "outer-source"}, {ID: "nested-source"}}
+
+	projectAcquiredDestinations(composed, scope, sources)
+	if got, want := sources[0].Destination.String(), "/records"; got != want {
+		t.Errorf("outer source destination = %q, want %q", got, want)
+	}
+	if got, want := sources[1].Destination.String(), "/records/2/settings"; got != want {
+		t.Errorf("nested source destination = %q, want %q", got, want)
+	}
+}
+
+func TestProjectNestedEvidenceUsesMappedSequenceItemIndex(t *testing.T) {
+	outer := historyApplication{
+		value: parseCompositionDocument(t, "outer-source", "records: [{id: outer}]\n"),
+		sequences: []sequenceHistoryContribution{{
+			path: Keys("records"), mode: sequenceHistoryMapped,
+			items: []sequenceItemProjection{{inputIndex: 0, outputIndex: 2}},
+		}},
+	}
+	outer.sequencesByPath = indexSequenceHistoryContributions(outer.sequences)
+	nestedRoot := parseCompositionDocument(t, "nested-source", "settings: {value: nested}\n")
+	nestedOrigin := Origin{Layer: LayerBase, Locations: []Location{{SourceID: "nested-source"}}}
+	nested := &composedDocument{
+		root: nestedRoot, applications: []historyApplication{{value: nestedRoot}},
+		origins: map[string]Origin{"/settings/value": nestedOrigin},
+	}
+	scope := acquisitionScope{contributions: []acquiredContribution{{
+		source: SourceInfo{ID: "outer-source"}, destination: Keys("records"), nested: nested,
+	}}}
+	composed := &composedDocument{
+		applications: []historyApplication{outer},
+		sequenceRanges: []sequenceRange{{
+			sourceIndex: 0, path: Keys("records"), start: 0, end: 1,
+			items: []sequenceItemProjection{{inputIndex: 0, outputIndex: 2}},
+		}},
+		origins: make(map[string]Origin),
+	}
+
+	projectNestedEvidence(composed, scope)
+	if got, want := composed.applications[1].path.String(), "/records/2"; got != want {
+		t.Fatalf("nested history application path = %q, want %q", got, want)
+	}
+	if origin := composed.origins["/records/2/settings/value"]; len(origin.Locations) != 1 || origin.Locations[0].SourceID != "nested-source" {
+		t.Fatalf("nested origin = %#v", origin)
+	}
+	query := Keys("records").Index(2).Key("settings").Key("value")
+	if operation, relevant := applicationOperationPath(composed.applications[1], query, nil); !relevant || operation.String() != query.String() {
+		t.Fatalf("nested historical query = %s, %v", operation.String(), relevant)
+	}
+	replayed := parseCompositionDocument(t, "lower", "records: [{id: first}, {id: middle}, {id: last}]\n")
+	for _, application := range composed.applications {
+		applyHistoryApplication(&replayed, application, new(mappingIndex))
+	}
+	if value, present := documentAtPath(replayed, query); !present || value.Text != "nested" {
+		t.Fatalf("replayed nested value = %#v, %v", value, present)
+	}
+	composed.applications[1].path.segments[0].key = "detached"
+	if got := nested.applications[0].path.String(); got != "" {
+		t.Fatalf("projected nested history path aliases its source: %q", got)
+	}
+}
+
+func TestDeferredInputCompositionUsesRetainedAcquisitionScopes(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: item.yml
+      destination: [records]
+      placement: sequence-item
+name: main
+`)
+	itemPath := writeImportFile(t, directory, "item.yml", `configkit:
+  imports:
+    - path: helper.yml
+id: item
+`)
+	helperPath := writeImportFile(t, directory, "helper.yml", "value: acquired\n")
+	accounting := &importAccounting{}
+	input, diagnostics := assembleBaseInputTracked(File(mainPath), Options[struct{}]{
+		Imports: true, Filesystem: &FilesystemContext{Root: directory}, deferAssembly: true,
+	}, Path{}, accounting, nil, nil)
+	if len(diagnostics) != 0 {
+		t.Fatalf("acquire input: %#v", diagnostics)
+	}
+	if input.composition == nil || input.composition.root != nil || len(input.composition.acquisition) != 1 {
+		t.Fatalf("acquisition handoff was composed early: %#v", input.composition)
+	}
+	if len(input.sources) != 3 || input.sources[0].ID != "source-1" || input.sources[1].ID != "source-2" || input.sources[2].ID != "source-3" {
+		t.Fatalf("acquired source order/identity = %#v", input.sources)
+	}
+	if _, err := os.Stat(itemPath); err != nil {
+		t.Fatalf("item source disappeared before composition: %v", err)
+	}
+	if _, err := os.Stat(helperPath); err != nil {
+		t.Fatalf("helper source disappeared before composition: %v", err)
+	}
+
+	composition, diagnostics := compositionForInputWithPolicy(input, sequencePolicy{})
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose acquired input: %#v", diagnostics)
+	}
+	if value, present := documentAtPath(composition.root, Keys("name")); !present || value.Text != "main" {
+		t.Fatalf("main value = %#v, %v", value, present)
+	}
+	for path, want := range map[string]string{
+		"/records/0/id":    "item",
+		"/records/0/value": "acquired",
+	} {
+		value, present := documentAtPath(composition.root, mustParsePath(t, path))
+		if !present || value.Text != want {
+			t.Errorf("composed %s = %#v, %v; want %q", path, value, present, want)
+		}
+	}
+	if got, want := input.sources[1].Destination.String(), "/records"; got != want {
+		t.Errorf("item destination = %q, want %q", got, want)
+	}
+	if got, want := input.sources[2].Destination.String(), "/records/0"; got != want {
+		t.Errorf("helper destination = %q, want %q", got, want)
+	}
+}
+
 func TestItemImportCanJoinAnAuthoredListUnderRegisteredComposition(t *testing.T) {
 	t.Parallel()
 	type config struct {
@@ -544,7 +679,7 @@ func TestItemImportCanJoinAnAuthoredListUnderRegisteredComposition(t *testing.T)
 		t.Fatalf("assemble item import: %#v", diagnostics)
 	}
 	authored := parseDocumentForDecode(t, "items: [{id: authored-id, name: authored}]\n")
-	composed, diagnostics := composeDocumentsWithPolicy(sequencePolicy{identityFields: map[string]string{"/items": "id"}}, authored, input.document)
+	composed, diagnostics := composeDocumentsWithPolicy(mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}), authored, input.document)
 	if len(diagnostics) != 0 {
 		t.Fatalf("compose authored and imported lists: %#v", diagnostics)
 	}
@@ -874,7 +1009,7 @@ func TestItemContributionsUseDependencyReadySchedules(t *testing.T) {
 		type config struct {
 			Items []item `yaml:"items"`
 		}
-		definition := Definition[config]{sequenceRegistrations: []sequenceRegistration{{path: Keys("items"), identityField: "id"}}}
+		definition := Definition[config]{sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}}
 		directory := t.TempDir()
 		mainPath := writeImportFile(t, directory, "main.yml", `configkit:
   imports:

internal/engine/inheritance.go

@@ -7,10 +7,13 @@ const inheritanceKey = "extends"
 // These private records keep structural evidence separate from acquired source
 // records. Later inspection can project a transfer onto individual descendants.
 type inheritanceTransfer struct {
-	from      Path
-	to        Path
-	reference Path
-	locations []Location
+	from              Path
+	to                Path
+	reference         Path
+	locations         []Location
+	policyTemplates   []collectionPolicyScope
+	templatePolicies  collectionPolicyScope
+	projectedPolicies []projectedCollectionPolicy
 }
 
 type inheritanceControl struct {
@@ -20,22 +23,129 @@ type inheritanceControl struct {
 }
 
 type inheritanceScope struct {
-	root         *document.Node
-	origins      map[string]Origin
-	transfers    []inheritanceTransfer
-	controls     []inheritanceControl
-	replacements []inheritanceReplacement
-	operations   []inheritanceOperation
+	root               *document.Node
+	origins            map[string]Origin
+	collectionPolicies collectionPolicyScope
+	transfers          []inheritanceTransfer
+	controls           []inheritanceControl
+	replacements       []inheritanceReplacement
+	operations         []inheritanceOperation
 }
 
 type inheritanceOperation struct {
-	control          *inheritanceControl
-	transfer         *inheritanceTransfer
-	controlOrigin    Origin
-	parent           *document.Node
-	effective        *document.Node
-	parentOrigins    map[string]Origin
-	effectiveOrigins map[string]Origin
+	control           *inheritanceControl
+	transfer          *inheritanceTransfer
+	controlOrigin     Origin
+	parent            *document.Node
+	effective         *document.Node
+	parentOrigins     map[string]Origin
+	effectiveOrigins  map[string]Origin
+	parentPolicies    []collectionPolicyScope
+	templatePolicies  collectionPolicyScope
+	effectivePolicies []collectionPolicyScope
+	sequences         []sequenceHistoryContribution
+	identityFields    []string
+}
+
+func cloneInheritancePolicyTemplates(templates []collectionPolicyScope) []collectionPolicyScope {
+	if templates == nil {
+		return nil
+	}
+	cloned := make([]collectionPolicyScope, len(templates))
+	for index, template := range templates {
+		cloned[index] = cloneCollectionPolicyScopeForInheritance(template)
+	}
+	return cloned
+}
+
+func cloneProjectedInheritancePolicies(policies []projectedCollectionPolicy) []projectedCollectionPolicy {
+	if policies == nil {
+		return nil
+	}
+	cloned := make([]projectedCollectionPolicy, len(policies))
+	for index, policy := range policies {
+		cloned[index] = projectedCollectionPolicy{
+			path: policy.path.clone(), policy: cloneCollectionPolicyForInheritance(policy.policy),
+		}
+	}
+	return cloned
+}
+
+func cloneInheritanceTransfer(transfer inheritanceTransfer) inheritanceTransfer {
+	cloned := transfer
+	cloned.from = transfer.from.clone()
+	cloned.to = transfer.to.clone()
+	cloned.reference = transfer.reference.clone()
+	cloned.locations = append([]Location(nil), transfer.locations...)
+	cloned.policyTemplates = cloneInheritancePolicyTemplates(transfer.policyTemplates)
+	cloned.templatePolicies = cloneCollectionPolicyScopeForInheritance(transfer.templatePolicies)
+	cloned.projectedPolicies = cloneProjectedInheritancePolicies(transfer.projectedPolicies)
+	return cloned
+}
+
+func cloneInheritanceOperations(operations []inheritanceOperation) []inheritanceOperation {
+	if operations == nil {
+		return nil
+	}
+	cloned := make([]inheritanceOperation, len(operations))
+	for index, operation := range operations {
+		cloned[index] = operation
+		if operation.control != nil {
+			control := *operation.control
+			control.path = operation.control.path.clone()
+			control.locations = append([]Location(nil), operation.control.locations...)
+			cloned[index].control = &control
+		}
+		if operation.transfer != nil {
+			transfer := cloneInheritanceTransfer(*operation.transfer)
+			cloned[index].transfer = &transfer
+		}
+		cloned[index].parent = document.Clone(operation.parent)
+		cloned[index].effective = document.Clone(operation.effective)
+		cloned[index].parentOrigins = cloneOriginIndex(operation.parentOrigins)
+		cloned[index].effectiveOrigins = cloneOriginIndex(operation.effectiveOrigins)
+		cloned[index].parentPolicies = cloneInheritancePolicyTemplates(operation.parentPolicies)
+		cloned[index].templatePolicies = cloneCollectionPolicyScopeForInheritance(operation.templatePolicies)
+		cloned[index].effectivePolicies = cloneInheritancePolicyTemplates(operation.effectivePolicies)
+		cloned[index].sequences = cloneSequenceHistoryContributions(operation.sequences)
+		cloned[index].identityFields = cloneStrings(operation.identityFields)
+	}
+	return cloned
+}
+
+func inheritancePolicyScopeAtPath(scope collectionPolicyScope, prefix Path) collectionPolicyScope {
+	localized := collectionPolicyScope{}
+	for _, entry := range scope.collections {
+		if relative, inside := relativeHistoryPath(prefix, entry.destination); inside {
+			localized.set(relative, cloneCollectionPolicyForInheritance(entry.policy))
+			continue
+		}
+		relative, inside := relativeHistoryPath(entry.destination, prefix)
+		if !inside || len(relative.segments) == 0 || relative.segments[0].kind != pathSegmentIndex {
+			continue
+		}
+		record, found := entry.policy.recordPolicyAt(relative.segments[0].index)
+		if !found {
+			continue
+		}
+		remainder := Path{segments: append([]pathSegment(nil), relative.segments[1:]...)}
+		for _, nested := range inheritancePolicyScopeAtPath(record.scope, remainder).collections {
+			localized.set(nested.destination, cloneCollectionPolicyForInheritance(nested.policy))
+		}
+	}
+	return localized
+}
+
+func projectInheritancePolicyTemplates(templates []collectionPolicyScope, prefix Path) []projectedCollectionPolicy {
+	var projected []projectedCollectionPolicy
+	for _, template := range templates {
+		for _, policy := range projectCollectionPolicyScope(template, prefix) {
+			projected = append(projected, projectedCollectionPolicy{
+				path: policy.path.clone(), policy: cloneCollectionPolicyForInheritance(policy.policy),
+			})
+		}
+	}
+	return projected
 }
 
 // A replacement retains the displaced source/derivation record while the

internal/engine/inheritance_collection.go

@@ -0,0 +1,305 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+func projectInheritanceCollectionPolicies(scope collectionPolicyScope, prefix Path) collectionPolicyScope {
+	projected := collectionPolicyScope{}
+	for _, entry := range scope.collections {
+		policy := cloneCollectionPolicyForInheritance(entry.policy)
+		stripInheritanceModes(&policy)
+		projected.set(appendDestination(prefix, entry.destination), policy)
+	}
+	return projected
+}
+
+func projectCurrentInheritanceCollectionPolicies(scope collectionPolicyScope, prefix Path) collectionPolicyScope {
+	projected := collectionPolicyScope{}
+	for _, entry := range scope.collections {
+		projected.set(appendDestination(prefix, entry.destination), cloneCollectionPolicyForInheritance(entry.policy))
+	}
+	return projected
+}
+
+func projectInheritancePolicyRoots(target *collectionPolicyScope, scope collectionPolicyScope, prefix Path) {
+	for _, entry := range scope.collections {
+		target.set(appendDestination(prefix, entry.destination), cloneCollectionPolicyForInheritance(entry.policy))
+	}
+}
+
+func stripInheritanceModes(policy *collectionPolicy) {
+	if policy == nil {
+		return
+	}
+	policy.explicitMode = 0
+	policy.explicitModePresent = false
+	policy.modeLocation = nil
+	for owner, nested := range policy.recordPolicies {
+		for key, entry := range nested.collections {
+			stripInheritanceModes(&entry.policy)
+			nested.collections[key] = entry
+		}
+		policy.recordPolicies[owner] = nested
+	}
+}
+
+func inheritanceDeclarationsAt(path Path, policy collectionPolicy) []sequenceDeclarationSpec {
+	if !policy.identityPresent && !policy.explicitModePresent {
+		return nil
+	}
+	return []sequenceDeclarationSpec{{
+		destination:    path.clone(),
+		identityFields: cloneStrings(policy.identityFields), identityPresent: policy.identityPresent,
+		identityLocation: cloneLocation(policy.identityLocation),
+		mode:             policy.explicitMode, modePresent: policy.explicitModePresent,
+		modeLocation: cloneLocation(policy.modeLocation),
+	}}
+}
+
+func inheritanceCollectionResolution(
+	path Path,
+	lowerScope, higherScope collectionPolicyScope,
+	applicationPolicy sequencePolicy,
+	incoming *document.Node,
+) (collectionPolicyResolution, collectionPolicy, collectionPolicy, bool, []Diagnostic) {
+	lower, hasLower := lowerScope.at(path)
+	higher, hasHigher := higherScope.at(path)
+	applicationIdentity, registered := applicationPolicy.identityFieldsAt(path)
+	if !hasLower && !hasHigher && !registered {
+		return collectionPolicyResolution{}, collectionPolicy{}, collectionPolicy{}, false, nil
+	}
+	lowerForResolution := cloneCollectionPolicy(lower)
+	// The parent policy is copied to a different sibling destination. Its YAML
+	// identity follows the inherited collection, but its explicit mode does not.
+	lowerForResolution.explicitMode = 0
+	lowerForResolution.explicitModePresent = false
+	lowerForResolution.modeLocation = nil
+	if incoming != nil && higher.explicitModePresent && higher.explicitMode == sequenceModeReplace {
+		// Actual replacement discards the parent's YAML identity before
+		// agreement. A mode-only declaration still governs retained records.
+		lowerForResolution = collectionPolicy{}
+	}
+	var lowerPointer *collectionPolicy
+	if hasLower {
+		lowerPointer = &lowerForResolution
+	}
+	resolution, diagnostics := resolveCollectionPolicy(
+		path, inheritanceDeclarationsAt(path, higher), applicationIdentity, lowerPointer,
+	)
+	return resolution, lower, higher, true, diagnostics
+}
+
+func mergeInheritanceCollectionPolicies(
+	parent, child collectionPolicyScope,
+	parentRootPath Path,
+	parentValue, childValue *document.Node,
+	applicationPolicy sequencePolicy,
+	replaced collectionReplacementPaths,
+) (collectionPolicyScope, []Diagnostic) {
+	result := cloneCollectionPolicyScopeForInheritance(parent)
+	paths := make(map[string]Path, len(parent.collections)+len(child.collections))
+	for key, entry := range parent.collections {
+		paths[key] = entry.destination.clone()
+	}
+	for key, entry := range child.collections {
+		paths[key] = entry.destination.clone()
+	}
+	var diagnostics []Diagnostic
+	for _, path := range paths {
+		relative, inside := relativeHistoryPath(parentRootPath, path)
+		var retained, incoming *document.Node
+		if inside {
+			if !replaced.contains(path, false) {
+				retained, _ = documentAtPath(parentValue, relative)
+			}
+			incoming, _ = documentAtPath(childValue, relative)
+		}
+		resolution, lower, _, active, issues := inheritanceCollectionResolution(path, parent, child, applicationPolicy, incoming)
+		if len(issues) != 0 {
+			diagnostics = append(diagnostics, issues...)
+			continue
+		}
+		if !active {
+			continue
+		}
+		var lowerPointer *collectionPolicy
+		if _, found := parent.at(path); found {
+			lower.explicitMode = 0
+			lower.explicitModePresent = false
+			lower.modeLocation = nil
+			lowerPointer = &lower
+		}
+		policy := resolution.policy
+		if incoming == nil || resolution.operation != sequenceModeReplace {
+			var foundDiagnostics []Diagnostic
+			policy, foundDiagnostics = collectionPolicyWithoutValue(lowerPointer, resolution.policy, retained, path)
+			if len(foundDiagnostics) != 0 {
+				diagnostics = append(diagnostics, foundDiagnostics...)
+				continue
+			}
+		}
+		if higher, ok := child.at(path); ok {
+			policy = inheritanceRecordPoliciesFromHigher(policy, higher)
+		}
+		result.set(path, policy)
+	}
+	return result, canonicalDiagnostics(diagnostics)
+}
+
+func inheritanceRecordPoliciesFromHigher(policy, higher collectionPolicy) collectionPolicy {
+	if len(higher.recordOrder) == 0 {
+		return policy
+	}
+	policy.recordOrder = nil
+	policy.recordPolicies = nil
+	for index := range higher.recordOrder {
+		if record, found := higher.recordPolicyAt(index); found {
+			policy.setRecordPolicyAt(index, currentCollectionRecordPolicy(record))
+		}
+	}
+	return policy
+}
+
+func inheritedCollectionRecordPolicy(record collectionRecordPolicy) collectionRecordPolicy {
+	cloned := cloneCollectionPolicyForInheritance(collectionPolicy{
+		recordOrder:    []*collectionRecordOwner{record.owner},
+		recordPolicies: map[*collectionRecordOwner]collectionPolicyScope{record.owner: record.scope},
+	})
+	if len(cloned.recordOrder) == 0 {
+		return newCollectionRecordPolicy()
+	}
+	owner := cloned.recordOrder[0]
+	scope := cloned.recordPolicies[owner]
+	for key, entry := range scope.collections {
+		stripInheritanceModes(&entry.policy)
+		scope.collections[key] = entry
+	}
+	return collectionRecordPolicy{owner: owner, scope: scope}
+}
+
+func currentCollectionRecordPolicy(record collectionRecordPolicy) collectionRecordPolicy {
+	cloned := cloneCollectionPolicyForInheritance(collectionPolicy{
+		recordOrder:    []*collectionRecordOwner{record.owner},
+		recordPolicies: map[*collectionRecordOwner]collectionPolicyScope{record.owner: record.scope},
+	})
+	if len(cloned.recordOrder) == 0 {
+		return newCollectionRecordPolicy()
+	}
+	owner := cloned.recordOrder[0]
+	return collectionRecordPolicy{owner: owner, scope: cloned.recordPolicies[owner]}
+}
+
+func applyInheritanceSequencePolicy(
+	path Path,
+	combined sequenceCombinationResult,
+	resolution collectionPolicyResolution,
+	lowerScope, higherScope collectionPolicyScope,
+) collectionPolicy {
+	policy := cloneCollectionPolicyForInheritance(resolution.policy)
+	policy.recordOrder = nil
+	policy.recordPolicies = nil
+	if combined.value == nil || combined.value.Kind != document.Sequence {
+		return policy
+	}
+
+	lowerPolicy, hasLower := lowerScope.at(path)
+	higherPolicy, hasHigher := higherScope.at(path)
+	lowerProjection := newSequenceItemProjectionIndex(combined.lowerItems)
+	higherProjection := newSequenceItemProjectionIndex(combined.higherItems)
+	for outputIndex := range combined.value.Sequence {
+		if higherIndex, exists := higherProjection.inputForOutput(outputIndex); exists {
+			if record, found := higherPolicy.recordPolicyAt(higherIndex); hasHigher && found {
+				policy.setRecordPolicyAt(outputIndex, currentCollectionRecordPolicy(record))
+			} else {
+				policy.setRecordPolicyAt(outputIndex, replacedCollectionRecordPolicy())
+			}
+			continue
+		}
+		if lowerIndex, exists := lowerProjection.inputForOutput(outputIndex); exists && hasLower {
+			if record, found := lowerPolicy.recordPolicyAt(lowerIndex); found {
+				policy.setRecordPolicyAt(outputIndex, inheritedCollectionRecordPolicy(record))
+			}
+		}
+	}
+	return policy
+}
+
+func applyInheritanceSequenceOrigins(
+	result *inheritanceScope,
+	origins, incomingOrigins map[string]Origin,
+	path Path,
+	lower, higher *document.Node,
+	combined sequenceCombinationResult,
+	operation sequenceMode,
+) {
+	if operation == sequenceModeReplace {
+		if lower != nil {
+			displaced := displacedOrigins(lower, origins, path)
+			result.replacements = append(result.replacements, inheritanceReplacement{
+				path: path.clone(), before: lower, after: higher,
+				previous: displaced, effective: cloneOrigin(incomingOrigins[path.String()]),
+			})
+			deleteOriginSubtree(origins, path, lower)
+		}
+		mergeInheritanceOrigin(origins, path, incomingOrigins[path.String()])
+		if higher != nil && higher.Kind != document.Sequence {
+			copyInheritanceSubtree(origins, incomingOrigins, higher, path)
+		}
+		for _, projection := range combined.higherItems {
+			if higher != nil && higher.Kind == document.Sequence && projection.inputIndex >= 0 && projection.inputIndex < len(higher.Sequence) {
+				copyInheritanceSubtreeAt(origins, incomingOrigins, higher.Sequence[projection.inputIndex], path.Index(projection.inputIndex), path.Index(projection.outputIndex))
+			}
+		}
+		return
+	}
+
+	mergeInheritanceOrigin(origins, path, incomingOrigins[path.String()])
+	for _, replacement := range combined.replacements {
+		if lower == nil || lower.Kind != document.Sequence || replacement.lowerIndex < 0 || replacement.lowerIndex >= len(lower.Sequence) ||
+			higher == nil || higher.Kind != document.Sequence || replacement.higherIndex < 0 || replacement.higherIndex >= len(higher.Sequence) {
+			continue
+		}
+		lowerPath := path.Index(replacement.lowerIndex)
+		higherPath := path.Index(replacement.higherIndex)
+		outputPath := path.Index(replacement.outputIndex)
+		previous := displacedOrigins(lower.Sequence[replacement.lowerIndex], origins, lowerPath)
+		deleteOriginSubtree(origins, lowerPath, lower.Sequence[replacement.lowerIndex])
+		copyInheritanceSubtreeAt(origins, incomingOrigins, higher.Sequence[replacement.higherIndex], higherPath, outputPath)
+		result.replacements = append(result.replacements, inheritanceReplacement{
+			path: outputPath, before: lower.Sequence[replacement.lowerIndex], after: higher.Sequence[replacement.higherIndex],
+			previous: previous, effective: cloneOrigin(incomingOrigins[higherPath.String()]),
+		})
+	}
+	for _, projection := range combined.higherItems {
+		if higher != nil && higher.Kind == document.Sequence && projection.inputIndex >= 0 && projection.inputIndex < len(higher.Sequence) {
+			copyInheritanceSubtreeAt(origins, incomingOrigins, higher.Sequence[projection.inputIndex], path.Index(projection.inputIndex), path.Index(projection.outputIndex))
+		}
+	}
+}
+
+func validateRegisteredInheritanceSequences(root *document.Node, rootPath Path, applicationPolicy sequencePolicy) []Diagnostic {
+	var diagnostics []Diagnostic
+	var visit func(*document.Node, Path)
+	visit = func(node *document.Node, path Path) {
+		if node == nil {
+			return
+		}
+		if node.Kind == document.Sequence {
+			if fields, registered := applicationPolicy.identityFieldsAt(path); registered {
+				if _, issues := validateSequenceIdentity(node, path, fields, sequenceCombinationIdentityCodes); len(issues) != 0 {
+					diagnostics = append(diagnostics, issues...)
+				}
+			}
+			for index, item := range node.Sequence {
+				visit(item, path.Index(index))
+			}
+			return
+		}
+		if node.Kind == document.Mapping {
+			for _, entry := range node.Mapping {
+				visit(entry.Value, path.Key(entry.Key))
+			}
+		}
+	}
+	visit(root, rootPath)
+	return canonicalDiagnostics(diagnostics)
+}

internal/engine/inheritance_collection_test.go

@@ -0,0 +1,369 @@
+package engine
+
+import (
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestInheritanceReplacementResetsOnlyReplacedYamlIdentity(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name, key, value, applicationKey string
+		mode                             sequenceMode
+		wantFields                       []string
+		conflict                         bool
+	}{
+		{name: "changed key", key: "name", value: "[{name: child}]", mode: sequenceModeReplace, wantFields: []string{"name"}},
+		{name: "unkeyed replacement", value: "[{name: child}]", mode: sequenceModeReplace},
+		{name: "non-sequence replacement", value: "42", mode: sequenceModeReplace},
+		{name: "agreeing application", key: "name", value: "[{name: child}]", applicationKey: "name", mode: sequenceModeReplace, wantFields: []string{"name"}},
+		{name: "conflicting application", key: "name", value: "[{name: child}]", applicationKey: "id", mode: sequenceModeReplace, conflict: true},
+		{name: "application still validates replacement", value: "[{name: child}]", applicationKey: "id", mode: sequenceModeReplace, conflict: true},
+		{name: "mode-only key change", key: "name", mode: sequenceModeReplace, conflict: true},
+		{name: "mode-only keeps identity", mode: sequenceModeReplace, wantFields: []string{"id"}},
+		{name: "append key change", key: "name", value: "[{name: child}]", mode: sequenceModeAppend, conflict: true},
+		{name: "upsert key change", key: "name", value: "[{name: child}]", mode: sequenceModeUpsert, conflict: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			input := "base: {items: [{id: parent}]}\nchild:\n  extends: base\n"
+			if test.value != "" {
+				input += "  items: " + test.value + "\n"
+			}
+			root := parseItemPolicyDocument(t, "replacement", input)
+			policies := collectionPolicyScope{}
+			policies.set(Keys("base", "items"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+			higher := collectionPolicy{explicitMode: test.mode, explicitModePresent: true}
+			if test.key != "" {
+				higher.identityFields, higher.identityPresent = []string{test.key}, true
+			}
+			policies.set(Keys("child", "items"), higher)
+			application := sequencePolicy{}
+			if test.applicationKey != "" {
+				application = mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{
+					selector: sequenceIdentitySelector{literalSequenceSelector("child"), literalSequenceSelector("items")}, identityFields: []string{test.applicationKey},
+				}})
+			}
+			expanded, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, application, defaultProjectionLimits())
+			if test.conflict {
+				wantCode := CodeSequenceConflict
+				if test.applicationKey != "" && test.key == "" {
+					wantCode = CodeSequenceInvalid
+				}
+				if len(diagnostics) == 0 || diagnostics[0].Code != wantCode || diagnostics[0].Path.String() != "/child/items" && diagnostics[0].Path.String() != "/child/items/0/id" {
+					t.Fatalf("missing identity/constraint failure: %#v", diagnostics)
+				}
+				return
+			}
+			if len(diagnostics) != 0 {
+				t.Fatal(diagnostics)
+			}
+			policy, found := expanded.collectionPolicies.at(Keys("child", "items"))
+			if !found || !reflect.DeepEqual(policy.identityFields, test.wantFields) || policy.identityPresent != (test.wantFields != nil) {
+				t.Fatalf("effective YAML identity = %#v, want %v", policy, test.wantFields)
+			}
+			if test.value != "" {
+				actual, _ := documentAtPath(expanded.root, Keys("child", "items"))
+				want, _ := documentAtPath(root, Keys("child", "items"))
+				if !configurationValuesEqual(actual, want) {
+					t.Fatal("explicit replacement retained parent payload")
+				}
+			}
+		})
+	}
+}
+
+func TestLoadInheritanceReplacementUsesNewYamlKey(t *testing.T) {
+	t.Parallel()
+	loaded, err := testLoad[map[string]any](Bytes("replacement", []byte(`configkit:
+  sequences:
+    - {destination: [base, items], key: id}
+    - {destination: [child, items], key: name, mode: replace}
+base: {items: [{id: parent}]}
+child:
+  extends: base
+  items: [{name: child}]
+`)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	value, found := loaded.Explain(Keys("child", "items"))
+	if !found || value.Effective.YAML != "- name: child\n" {
+		t.Fatalf("replacement payload = %#v", value)
+	}
+}
+
+func TestInheritanceCombinesIdentifiedSequencesAtDestination(t *testing.T) {
+	root := parseItemPolicyDocument(t, "inheritance-values", `base:
+  items:
+    - id: shared
+      value: parent
+child:
+  extends: base
+  items:
+    - id: shared
+      value: child
+`)
+	modeLocation := Location{SourceID: "base-policy", Line: 4, Column: 5}
+	policy := collectionPolicy{
+		identityFields: []string{"id"}, identityPresent: true,
+		explicitMode: sequenceModeAppend, explicitModePresent: true, modeLocation: &modeLocation,
+	}
+	policies := collectionPolicyScope{}
+	policies.set(Keys("base", "items"), policy)
+
+	expanded, diagnostics := expandInheritanceWithCollectionRules(
+		root, nil, policies, sequencePolicy{}, defaultProjectionLimits(),
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("expand identified inheritance: %#v", diagnostics)
+	}
+	items, found := documentAtPath(expanded.root, Keys("child", "items"))
+	if !found || items.Kind != document.Sequence || len(items.Sequence) != 1 {
+		t.Fatalf("child items = %#v, found %t; parent mode should not force an append", items, found)
+	}
+	if value, exists := documentAtPath(items.Sequence[0], Keys("value")); !exists || value.Text != "child" {
+		t.Fatalf("matched record = %#v, want complete child replacement", items.Sequence[0])
+	}
+	childPolicy, found := expanded.collectionPolicies.at(Keys("child", "items"))
+	if !found || !childPolicy.identityPresent || childPolicy.identityFields[0] != "id" {
+		t.Fatalf("inherited destination identity = %#v, found %t; scope=%#v", childPolicy, found, expanded.collectionPolicies.collections)
+	}
+	if childPolicy.explicitModePresent {
+		t.Fatalf("parent explicit mode leaked to a different destination: %#v", childPolicy)
+	}
+
+	var transfer *inheritanceOperation
+	for index := range expanded.operations {
+		if expanded.operations[index].transfer != nil && expanded.operations[index].transfer.to.String() == "/child" {
+			transfer = &expanded.operations[index]
+			break
+		}
+	}
+	if transfer == nil || len(transfer.sequences) != 1 || transfer.sequences[0].path.String() != "/child/items" || len(transfer.sequences[0].replacements) != 1 {
+		t.Fatalf("inheritance sequence projection = %#v, want one mapped replacement", transfer)
+	}
+	if origin, exists := expanded.origins["/child/items/0/value"]; !exists || len(origin.Locations) == 0 || origin.Locations[0].SourceID != "inheritance-values" {
+		t.Fatalf("replacement origin lost the child's source context: %#v", origin)
+	}
+}
+
+func TestLoadAppliesYamlCollectionIdentityDuringSiblingInheritance(t *testing.T) {
+	input := `configkit:
+  sequences:
+    - destination: [base, items]
+      key: id
+      mode: append
+base:
+  items:
+    - id: shared
+      value: parent
+child:
+  extends: base
+  items:
+    - id: shared
+      value: child
+`
+	loaded, err := Load[map[string]any](Bytes("inheritance-policy", []byte(input)), testSecretBinding())
+	if err != nil {
+		if loadError, ok := err.(*LoadError); ok {
+			t.Fatalf("load inherited collection policy: %v; diagnostics=%#v", err, loadError.Diagnostics())
+		}
+		t.Fatal(err)
+	}
+	value, found := loaded.Inspection.Explain(Keys("child", "items").Index(0).Key("value"))
+	if !found || value.Effective.YAML != "child\n" {
+		t.Fatalf("inherited sequence value = %#v, found %t", value, found)
+	}
+	if len(value.History) == 0 {
+		t.Fatal("inherited sequence replacement has no inspection history")
+	}
+	parentValueVisible, childValueVisible := false, false
+	for _, change := range value.History {
+		parentValueVisible = parentValueVisible || change.Before.YAML == "parent\n" || change.After.YAML == "parent\n"
+		childValueVisible = childValueVisible || change.After.YAML == "child\n"
+	}
+	if !parentValueVisible || !childValueVisible {
+		t.Fatalf("sequence replacement history omitted its parent or child value: %#v", value.History)
+	}
+}
+
+func TestInheritanceUsesDestinationExplicitModeAndApplicationConstraint(t *testing.T) {
+	t.Run("destination append", func(t *testing.T) {
+		root := parseItemPolicyDocument(t, "append", `base:
+  items:
+    - id: base
+child:
+  extends: base
+  items:
+    - id: child
+`)
+		policies := collectionPolicyScope{}
+		policies.set(Keys("base", "items"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+		childLocation := Location{SourceID: "child-policy", Line: 4, Column: 5}
+		policies.set(Keys("child", "items"), collectionPolicy{
+			identityFields: []string{"id"}, identityPresent: true,
+			explicitMode: sequenceModeAppend, explicitModePresent: true, modeLocation: &childLocation,
+		})
+		expanded, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+		if len(diagnostics) != 0 {
+			t.Fatalf("expand with destination append: %#v", diagnostics)
+		}
+		items, _ := documentAtPath(expanded.root, Keys("child", "items"))
+		if len(items.Sequence) != 2 || items.Sequence[0].Mapping[0].Value.Text != "base" || items.Sequence[1].Mapping[0].Value.Text != "child" {
+			t.Fatalf("appended items = %#v", items)
+		}
+	})
+
+	t.Run("new matching namespace", func(t *testing.T) {
+		root := parseItemPolicyDocument(t, "dynamic", `base:
+  enabled: true
+child:
+  extends: base
+  extensions:
+    - id: duplicate
+    - id: duplicate
+`)
+		applicationPolicy, diagnostics := compileSequenceIdentityPolicy([]sequenceIdentityRegistration{{
+			selector: sequenceIdentitySelector{
+				{kind: sequenceSelectorLiteral, key: "child"},
+				{kind: sequenceSelectorLiteral, key: "extensions"},
+			},
+			identityFields: []string{"id"},
+		}})
+		if len(diagnostics) != 0 {
+			t.Fatalf("compile identity constraint: %#v", diagnostics)
+		}
+		_, diagnostics = expandInheritanceWithCollectionRules(root, nil, collectionPolicyScope{}, applicationPolicy, defaultProjectionLimits())
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict || diagnostics[0].Path.String() != "/child/extensions" {
+			t.Fatalf("dynamic application constraint diagnostics = %#v", diagnostics)
+		}
+	})
+}
+
+func TestInheritanceReplacementModesAndCancellation(t *testing.T) {
+	for _, test := range []struct {
+		name  string
+		value string
+		kind  document.Kind
+	}{
+		{name: "empty sequence", value: "[]", kind: document.Sequence},
+		{name: "null", value: "null", kind: document.Null},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			root := parseItemPolicyDocument(t, "replacement", "base:\n  items:\n    - id: prior\nchild:\n  extends: base\n  items: "+test.value+"\n")
+			policies := collectionPolicyScope{}
+			policies.set(Keys("base", "items"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+			policies.set(Keys("child", "items"), collectionPolicy{
+				identityFields: []string{"id"}, identityPresent: true,
+				explicitMode: sequenceModeReplace, explicitModePresent: true,
+			})
+			expanded, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+			if len(diagnostics) != 0 {
+				t.Fatalf("expand replacement: %#v", diagnostics)
+			}
+			items, found := documentAtPath(expanded.root, Keys("child", "items"))
+			if !found || items.Kind != test.kind || (items.Kind == document.Sequence && len(items.Sequence) != 0) {
+				t.Fatalf("replacement value = %#v, found %t", items, found)
+			}
+		})
+	}
+
+	for _, value := range []string{"null", "{}"} {
+		t.Run("append rejects "+value, func(t *testing.T) {
+			root := parseItemPolicyDocument(t, "append-kind", "base:\n  items: [{id: prior}]\nchild:\n  extends: base\n  items: "+value+"\n")
+			policies := collectionPolicyScope{}
+			policies.set(Keys("base", "items"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+			policies.set(Keys("child", "items"), collectionPolicy{
+				identityFields: []string{"id"}, identityPresent: true,
+				explicitMode: sequenceModeAppend, explicitModePresent: true,
+			})
+			_, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+			if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != "/child/items" {
+				t.Fatalf("append kind diagnostics = %#v", diagnostics)
+			}
+		})
+	}
+
+	t.Run("incompatible inherited identity", func(t *testing.T) {
+		root := parseItemPolicyDocument(t, "identity", `base:
+  items: [{id: one}]
+child:
+  extends: base
+  items: [{id: two}]
+`)
+		policies := collectionPolicyScope{}
+		policies.set(Keys("base", "items"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+		policies.set(Keys("child", "items"), collectionPolicy{identityFields: []string{"slug"}, identityPresent: true})
+		_, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict || diagnostics[0].Path.String() != "/child/items" {
+			t.Fatalf("identity conflict diagnostics = %#v", diagnostics)
+		}
+	})
+
+	t.Run("cancelled relationship", func(t *testing.T) {
+		root := parseItemPolicyDocument(t, "cancel", `base:
+  items: [{id: parent}]
+child:
+  extends: null
+  items: [{id: local}]
+`)
+		policies := collectionPolicyScope{}
+		policies.set(Keys("base", "items"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+		expanded, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+		if len(diagnostics) != 0 {
+			t.Fatalf("expand cancelled relationship: %#v", diagnostics)
+		}
+		if _, found := expanded.collectionPolicies.at(Keys("child", "items")); found {
+			t.Fatal("cancelled relationship transferred the parent's collection policy")
+		}
+	})
+}
+
+func TestInheritanceReplacementRetiresRecordLocalCollectionPolicy(t *testing.T) {
+	root := parseItemPolicyDocument(t, "record-scope", `base:
+  items:
+    - id: shared
+      children:
+        - key: old
+child:
+  extends: base
+  items:
+    - id: shared
+      children:
+        - key: new
+`)
+	nested := collectionPolicy{identityFields: []string{"key"}, identityPresent: true, explicitMode: sequenceModeAppend, explicitModePresent: true}
+	recordScope := collectionPolicyScope{}
+	recordScope.set(Keys("children"), nested)
+	outer := collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+	outer.setRecordPolicyAt(0, newCollectionRecordPolicy())
+	owner := outer.recordOrder[0]
+	outer.recordPolicies[owner] = recordScope
+	policies := collectionPolicyScope{}
+	policies.set(Keys("base", "items"), outer)
+
+	expanded, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("expand replacement record: %#v", diagnostics)
+	}
+	children, found := documentAtPath(expanded.root, Keys("child", "items").Index(0).Key("children"))
+	if !found || children.Kind != document.Sequence || len(children.Sequence) != 1 {
+		t.Fatalf("replacement children = %#v, found %t", children, found)
+	}
+	if key, exists := documentAtPath(children.Sequence[0], Keys("key")); !exists || key.Text != "new" {
+		t.Fatalf("replacement child = %#v, want only new record", children.Sequence[0])
+	}
+	childPolicy, exists := expanded.collectionPolicies.at(Keys("child", "items"))
+	if !exists {
+		t.Fatal("inherited outer collection policy is missing")
+	}
+	record, found := childPolicy.recordPolicyAt(0)
+	if !found {
+		t.Fatal("replacement item has no independent record owner")
+	}
+	if nestedPolicy, exists := record.scope.at(Keys("children")); exists && nestedPolicy.explicitModePresent {
+		t.Fatalf("replaced record retained its former nested operation: %#v", nestedPolicy)
+	}
+}

internal/engine/inheritance_explain.go

@@ -25,6 +25,12 @@ func appendInheritanceExplanation(explanation *Explanation, working **document.N
 		}
 		before := valueSnapshot(*working, query, secrets)
 		replaceHistoryPath(working, operation.transfer.to, operation.parent)
+		// A record keeps its own identity throughout inheritance. Restore it
+		// before taking enclosing snapshots as well as direct field snapshots.
+		for _, field := range operation.identityFields {
+			identity, _ := documentAtPath(operation.effective, Keys(field))
+			replaceHistoryPath(working, operation.transfer.to.Key(field), identity)
+		}
 		afterParent := valueSnapshot(*working, query, secrets)
 		parent, parentPresent := transferredOperationOrigin(operation, operationPathForQuery(operation.transfer.to, query))
 		if pathsIntersect(operation.transfer.to, query) && parentPresent {

internal/engine/inheritance_history.go

@@ -1,6 +1,7 @@
 package engine
 
 import (
+	"slices"
 	"sort"
 
 	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
@@ -73,13 +74,13 @@ func applyInheritanceMetadata(metadata *Metadata, raw *document.Node, rawOrigins
 	})
 	applyOverlayMetadata(&sourceView, overlays)
 	metadata.history = sourceView.history
-	metadata.inheritance = append([]inheritanceOperation(nil), expansion.operations...)
+	metadata.inheritance = cloneInheritanceOperations(expansion.operations)
 }
 
 func historyWithInheritance(path Path, stored []Change, operations []inheritanceOperation) []Change {
 	split := len(stored)
 	for index, change := range stored {
-		if change.Origin.Layer == LayerResolution {
+		if change.Origin.Layer == LayerCLI || change.Origin.Layer == LayerResolution {
 			split = index
 			break
 		}
@@ -114,7 +115,7 @@ func projectedInheritanceChanges(query Path, operation inheritanceOperation) []C
 		return []Change{{Path: operation.control.path.clone(), Origin: origin,
 			Dependencies: []Path{operation.control.path.clone()}}}
 	}
-	if operation.transfer == nil || !pathsIntersect(operation.transfer.to, query) {
+	if operation.transfer == nil || !pathsIntersect(operation.transfer.to, query) || inheritanceOperationIdentity(operation, query) {
 		return nil
 	}
 	path := query
@@ -155,6 +156,9 @@ func projectedInheritanceChanges(query Path, operation inheritanceOperation) []C
 }
 
 func transferredOperationOrigin(operation inheritanceOperation, destination Path) (Origin, bool) {
+	if inheritanceOperationIdentity(operation, destination) {
+		return Origin{}, false
+	}
 	relative, ok := relativeHistoryPath(operation.transfer.to, destination)
 	if !ok {
 		return Origin{}, false
@@ -168,3 +172,12 @@ func transferredOperationOrigin(operation inheritanceOperation, destination Path
 		operation.transfer.from, operation.transfer.to, *operation.transfer)
 	return transferred[destination.String()], true
 }
+
+func inheritanceOperationIdentity(operation inheritanceOperation, path Path) bool {
+	if operation.transfer == nil || len(operation.identityFields) == 0 {
+		return false
+	}
+	relative, within := relativeHistoryPath(operation.transfer.to, path)
+	return within && len(relative.segments) != 0 && relative.segments[0].kind != pathSegmentIndex &&
+		slices.Contains(operation.identityFields, relative.segments[0].key)
+}

internal/engine/inheritance_history_test.go

@@ -126,7 +126,7 @@ func inheritanceInspectionFromComposition(t *testing.T, composed *composedDocume
 	applyInheritanceMetadata(&metadata, composed.root, composed.origins, composed.overlays, expanded)
 	finalizeMetadataPaths(&metadata, expanded.root, composed.applications, baseline, composed.root)
 	return &Inspection{
-		metadata: metadata, baseline: baseline, input: expanded.root,
+		metadata: metadata, baseline: baseline, input: expanded.root, preCLI: expanded.root,
 		inputOrigins: expanded.origins, final: expanded.root,
 		applications: composed.applications, inheritance: expanded.operations,
 	}, expanded

internal/engine/inheritance_identified.go

@@ -0,0 +1,172 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+type identifiedInheritanceTemplate struct {
+	item          *document.Node
+	path          Path
+	tuple         string
+	parent        int
+	hasParent     bool
+	cancelled     bool
+	directive     *document.Node
+	directivePath Path
+}
+
+type identifiedInheritanceGraph struct {
+	scope      *document.Node
+	scopePath  Path
+	fields     []string
+	nodes      []identifiedInheritanceTemplate
+	edges      []dependencyEdge
+	byIdentity map[string]int
+}
+
+func sequenceHasIdentifiedInheritanceReferences(sequence *document.Node) bool {
+	if sequence == nil || sequence.Kind != document.Sequence {
+		return false
+	}
+	for _, item := range sequence.Sequence {
+		if directive, found := inheritanceDirective(item); found && directive.Value.Kind != document.Null {
+			return true
+		}
+	}
+	return false
+}
+
+// analyzeIdentifiedInheritanceGraph validates relationships inside one
+// identified sequence. It prepares a graph only; mapping-sibling expansion
+// remains the active inheritance behavior until the reusable scope executor is
+// activated.
+func analyzeIdentifiedInheritanceGraph(sequence *document.Node, scopePath Path, identityFields []string) (*identifiedInheritanceGraph, []Diagnostic) {
+	if sequence == nil || sequence.Kind != document.Sequence {
+		var primary *Location
+		if sequence != nil {
+			location := publicLocation(sequence.Location)
+			primary = &location
+		}
+		return nil, []Diagnostic{{
+			Code: CodeSequenceInvalid, Severity: SeverityError, Path: scopePath.clone(),
+			Message: "identified inheritance scope must be a sequence", Primary: primary,
+		}}
+	}
+	fields, err := normalizeSequenceIdentityFields(identityFields)
+	if err != nil {
+		location := publicLocation(sequence.Location)
+		return nil, []Diagnostic{{
+			Code: CodeSequenceInvalid, Severity: SeverityError, Path: scopePath.clone(),
+			Message: "identified inheritance scope requires identity fields", Primary: &location,
+		}}
+	}
+	lookup, diagnostics := validateNormalizedSequenceIdentityFrom(
+		sequence, scopePath, fields, sequenceCombinationIdentityCodes, 0, sequenceStructuralRecord,
+	)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	graph := &identifiedInheritanceGraph{
+		scope: sequence, scopePath: scopePath.clone(), fields: cloneStrings(fields),
+		nodes:      make([]identifiedInheritanceTemplate, len(sequence.Sequence)),
+		byIdentity: make(map[string]int, len(lookup)),
+	}
+	for tuple, record := range lookup {
+		graph.byIdentity[tuple] = record.index
+		graph.nodes[record.index] = identifiedInheritanceTemplate{
+			item: sequence.Sequence[record.index], path: scopePath.Index(record.index), tuple: tuple,
+		}
+	}
+
+	for index := range graph.nodes {
+		node := &graph.nodes[index]
+		directive, found := inheritanceDirective(node.item)
+		if !found {
+			continue
+		}
+		node.directive = directive.Value
+		node.directivePath = node.path.Key(inheritanceKey)
+		referenceLocation := publicLocation(directive.Value.Location)
+		switch directive.Value.Kind {
+		case document.Null:
+			node.cancelled = true
+		case document.Mapping:
+			reference, issues := identifiedInheritanceReference(directive.Value, node.directivePath, fields)
+			if len(issues) != 0 {
+				return nil, issues
+			}
+			parent, exists := graph.byIdentity[reference]
+			if !exists {
+				return nil, []Diagnostic{inheritanceDiagnostic(
+					CodeInheritanceMissing, node.directivePath, referenceLocation, nil,
+					"referenced record does not exist in this collection",
+				)}
+			}
+			node.parent = parent
+			node.hasParent = true
+			graph.edges = append(graph.edges, dependencyEdge{prerequisite: parent, dependent: index})
+		default:
+			return nil, []Diagnostic{inheritanceDiagnostic(
+				CodeInheritanceInvalid, node.directivePath, referenceLocation, nil,
+				"identified record inheritance reference must be a mapping or null",
+			)}
+		}
+	}
+	return graph, nil
+}
+
+func identifiedInheritanceReference(reference *document.Node, path Path, identityFields []string) (string, []Diagnostic) {
+	allowed := make(map[string]struct{}, len(identityFields))
+	for _, field := range identityFields {
+		allowed[field] = struct{}{}
+	}
+	seen := make(map[string]struct{}, len(reference.Mapping))
+	for _, entry := range reference.Mapping {
+		if _, ok := allowed[entry.Key]; !ok {
+			return "", []Diagnostic{inheritanceDiagnostic(
+				CodeInheritanceInvalid, path.Key(entry.Key), publicLocation(entry.Value.Location), nil,
+				"identified record inheritance reference has an unsupported field",
+			)}
+		}
+		seen[entry.Key] = struct{}{}
+	}
+	for _, field := range identityFields {
+		if _, ok := seen[field]; !ok {
+			return "", []Diagnostic{inheritanceDiagnostic(
+				CodeInheritanceInvalid, path.Key(field), publicLocation(reference.Location), nil,
+				"identified record inheritance reference is missing an identity field",
+			)}
+		}
+	}
+	index := newSequenceMappingIndex(reference, sequencePayloadRecord)
+	tuple, _, missing, invalid := index.identity(identityFields)
+	if missing != "" || invalid >= 0 || invalid == -2 {
+		value := reference
+		fieldPath := path.Key(missing)
+		if invalid >= 0 && invalid < len(reference.Mapping) {
+			value = reference.Mapping[invalid].Value
+			fieldPath = path.Key(reference.Mapping[invalid].Key)
+		}
+		location := publicLocation(value.Location)
+		return "", []Diagnostic{inheritanceDiagnostic(
+			CodeInheritanceInvalid, fieldPath, location, nil,
+			"identified record inheritance identity fields must be scalar values",
+		)}
+	}
+	return tuple, nil
+}
+
+func (graph *identifiedInheritanceGraph) schedule() ([]int, []Diagnostic) {
+	keys := make([]dependencyKey, len(graph.nodes))
+	for index, node := range graph.nodes {
+		keys[index] = dependencyKey{"record", graph.scopePath.String(), node.path.String()}
+	}
+	order, cycle := scheduleDependencies(keys, graph.edges)
+	if len(cycle) == 0 {
+		return order, nil
+	}
+	parent, child := graph.nodes[cycle[0]], graph.nodes[cycle[1]]
+	return nil, []Diagnostic{inheritanceDiagnostic(
+		CodeInheritanceCycle, child.directivePath, publicLocation(child.directive.Location),
+		[]Location{publicLocation(parent.item.Location)},
+		"identified record inheritance contains a cycle",
+	)}
+}

internal/engine/inheritance_identified_test.go

@@ -0,0 +1,373 @@
+package engine
+
+import (
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func parseIdentifiedInheritanceSequence(t *testing.T, sourceID, input string) *document.Node {
+	t.Helper()
+	var indented strings.Builder
+	indented.WriteString("jobs:\n")
+	for _, line := range strings.Split(strings.TrimSuffix(input, "\n"), "\n") {
+		indented.WriteString("  ")
+		indented.WriteString(line)
+		indented.WriteByte('\n')
+	}
+	root := parseItemPolicyDocument(t, sourceID, indented.String())
+	sequence, found := documentAtPath(root, Keys("jobs"))
+	if !found || sequence.Kind != document.Sequence {
+		t.Fatalf("identified sequence missing from test document: %#v", root)
+	}
+	return sequence
+}
+
+func TestIdentifiedInheritanceGraphSchedulesForwardReferencesInPlace(t *testing.T) {
+	sequence := parseIdentifiedInheritanceSequence(t, "identified-graph", `- id: 2
+  tenant: acme
+  extends: {id: 1.0, tenant: acme}
+- id: 1e0
+  tenant: acme
+  extends: {id: 0, tenant: acme}
+- id: 0
+  tenant: acme
+- id: 3
+  tenant: acme
+  extends: null
+`)
+	path := Keys("jobs")
+	graph, diagnostics := analyzeIdentifiedInheritanceGraph(sequence, path, []string{"tenant", "id"})
+	if len(diagnostics) != 0 {
+		t.Fatalf("analyze identified graph: %#v", diagnostics)
+	}
+	if len(graph.edges) != 2 {
+		t.Fatalf("edges = %#v, want the two links in the inheritance chain", graph.edges)
+	}
+	order, diagnostics := graph.schedule()
+	if len(diagnostics) != 0 {
+		t.Fatalf("schedule identified graph: %#v", diagnostics)
+	}
+	if len(order) != 4 || order[0] != 2 || order[1] != 1 || order[2] != 0 {
+		t.Fatalf("schedule = %v, want the forward parent chain before its children", order)
+	}
+	if graph.nodes[0].path.String() != "/jobs/0" || graph.nodes[0].item != sequence.Sequence[0] ||
+		!graph.nodes[3].cancelled || len(graph.nodes[3].directivePath.segments) == 0 {
+		t.Fatalf("graph nodes changed authored positions or cancellation: %#v", graph.nodes)
+	}
+	if _, found := graph.byIdentity[graph.nodes[1].tuple]; !found {
+		t.Fatal("identity index does not contain the parent record")
+	}
+}
+
+func TestIdentifiedInheritanceScopeAdapterReusesTemplateExecution(t *testing.T) {
+	sequence := parseIdentifiedInheritanceSequence(t, "identified-scope", `- id: child-a
+  tenant: team-a
+  extends: {id: parent-a, tenant: team-a}
+  settings: {child: a}
+- id: parent-a
+  tenant: team-a
+  settings: {parent: a}
+- id: child-b
+  tenant: team-b
+  extends: {id: parent-b, tenant: team-b}
+  settings: {child: b}
+- id: parent-b
+  tenant: team-b
+  settings: {parent: b}
+`)
+	path := Keys("jobs")
+	graph, diagnostics := analyzeIdentifiedInheritanceGraph(sequence, path, []string{"tenant", "id"})
+	if len(diagnostics) != 0 {
+		t.Fatalf("analyze identified graph: %#v", diagnostics)
+	}
+	policies := collectionPolicyScope{}
+	policies.set(path.Index(1).Key("steps"), collectionPolicy{
+		identityFields: []string{"step-id"}, identityPresent: true,
+	})
+	result, diagnostics := applyIdentifiedInheritanceTemplates(graph, defaultProjectionLimits(), nil, policies, sequencePolicy{})
+	if len(diagnostics) != 0 {
+		t.Fatalf("apply identified templates: %#v", diagnostics)
+	}
+	if got := len(result.root.Sequence); got != 4 {
+		t.Fatalf("result sequence length = %d, want 4", got)
+	}
+	for index, want := range []string{"child-a", "parent-a", "child-b", "parent-b"} {
+		id, found := documentAtPath(result.root.Sequence[index], Path{}.Key("id"))
+		if !found || id.Text != want {
+			t.Fatalf("result identity at index %d = %#v, found %t; want %q", index, id, found, want)
+		}
+	}
+	for index, want := range []string{"a", "b"} {
+		value, found := documentAtPath(result.root.Sequence[index*2], Path{}.Key("settings").Key("parent"))
+		if !found || value.Text != want {
+			t.Fatalf("inherited value at record %d = %#v, found %t; want %q", index*2, value, found, want)
+		}
+	}
+	if len(result.transfers) != 2 || result.transfers[0].from.String() != "/jobs/1" || result.transfers[0].to.String() != "/jobs/0" ||
+		result.transfers[1].from.String() != "/jobs/3" || result.transfers[1].to.String() != "/jobs/2" {
+		t.Fatalf("record transfers = %#v, want independent transfers at authored positions", result.transfers)
+	}
+	if len(result.controls) != 2 || result.controls[0].path.String() != "/jobs/0/extends" || result.controls[1].path.String() != "/jobs/2/extends" {
+		t.Fatalf("relationship controls = %#v, want paths from child positions", result.controls)
+	}
+	if len(result.operations) != 4 || result.operations[1].transfer == nil || result.operations[1].transfer.to.String() != "/jobs/0" ||
+		result.operations[3].transfer == nil || result.operations[3].transfer.to.String() != "/jobs/2" {
+		t.Fatalf("relationship history operations = %#v, want transfer evidence at child positions", result.operations)
+	}
+	if _, found := result.origins[path.Index(0).Key("id").String()]; !found {
+		t.Fatal("resolved sequence output did not retain the child identity origin path")
+	}
+	projectedPolicy, found := result.collectionPolicies.at(path.Index(0).Key("steps"))
+	if !found || !projectedPolicy.identityPresent || len(projectedPolicy.identityFields) != 1 || projectedPolicy.identityFields[0] != "step-id" {
+		t.Fatalf("inherited nested collection policy = %#v, found %t", projectedPolicy, found)
+	}
+	adapter := identifiedSequenceInheritanceScope{graph: graph, policies: policies}
+	fields := adapter.templates()[0].identityFields
+	if len(fields) != 2 || fields[0] != "id" || fields[1] != "tenant" {
+		t.Fatalf("payload identity fields = %v, want [id tenant]", fields)
+	}
+	templates := adapter.templates()
+	parentPolicy, found := templates[1].collectionPolicies.at(Keys("steps"))
+	if !found || len(parentPolicy.identityFields) != 1 || parentPolicy.identityFields[0] != "step-id" {
+		t.Fatalf("parent nested policy = %#v, found %t", parentPolicy, found)
+	}
+	if _, found := templates[0].collectionPolicies.at(Keys("steps")); found {
+		t.Fatal("nested policy from one record leaked into a sibling template")
+	}
+	parentPolicy.identityFields[0] = "changed"
+	templates[1].collectionPolicies.set(Keys("steps"), parentPolicy)
+	reused, found := adapter.templates()[1].collectionPolicies.at(Keys("steps"))
+	if !found || len(reused.identityFields) != 1 || reused.identityFields[0] != "step-id" {
+		t.Fatal("reusing the adapter observed a mutation to a prior template snapshot")
+	}
+	if sequence.Sequence[0].Mapping[0].Value.Text != "child-a" {
+		t.Fatal("executing the sequence adapter mutated its source scope")
+	}
+}
+
+func TestIdentifiedInheritanceResolvesNestedCollectionsAtEachDestination(t *testing.T) {
+	root := parseItemPolicyDocument(t, "identified-nested", `jobs:
+  - id: child
+    extends: {id: parent}
+  - id: parent
+    extends: {id: base}
+    steps:
+      - id: child-step
+        extends: {id: parent-step}
+        value: child-value
+      - id: parent-step
+        value: parent-value
+  - id: base
+    steps:
+      - id: base-step
+        value: base-value
+`)
+	identity := collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+	policies := collectionPolicyScope{}
+	policies.set(Keys("jobs"), identity)
+	for index := 0; index < 3; index++ {
+		policies.set(Keys("jobs").Index(index).Key("steps"), identity)
+	}
+	expanded, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("expand nested identified inheritance: %#v", diagnostics)
+	}
+	steps, found := documentAtPath(expanded.root, Keys("jobs").Index(0).Key("steps"))
+	if !found || steps.Kind != document.Sequence || len(steps.Sequence) != 3 {
+		t.Fatalf("child nested steps = %#v, found %t", steps, found)
+	}
+	for index, want := range []string{"base-step", "child-step", "parent-step"} {
+		id, exists := documentAtPath(steps.Sequence[index], Keys("id"))
+		if !exists || id.Text != want {
+			t.Fatalf("child step %d identity = %#v, found %t; want %q", index, id, exists, want)
+		}
+	}
+	value, found := documentAtPath(steps.Sequence[1], Keys("value"))
+	if !found || value.Text != "child-value" {
+		t.Fatalf("nested record inheritance = %#v, found %t", value, found)
+	}
+	if containsInheritanceDirective(expanded.root) {
+		t.Fatal("a nested record relationship remained after destination-local expansion")
+	}
+	childIdentity, found := expanded.origins["/jobs/0/id"]
+	if !found || len(childIdentity.Locations) == 0 || childIdentity.Locations[0].SourceID != "identified-nested" {
+		t.Fatalf("child identity origin = %#v, found %t", childIdentity, found)
+	}
+	if _, found := expanded.origins["/jobs/0/steps/1/value"]; !found {
+		t.Fatal("nested inherited value did not retain its destination origin")
+	}
+	for _, replacement := range expanded.replacements {
+		if replacement.path.String() == "/jobs/0/id" {
+			t.Fatal("parent identity was treated as payload replaced by the child's identity")
+		}
+	}
+}
+
+func TestIdentifiedInheritanceRespectsOutputNodeBudget(t *testing.T) {
+	root := parseItemPolicyDocument(t, "identified-budget", `jobs:
+  - id: child
+    extends: {id: parent}
+  - id: parent
+    value: inherited
+`)
+	policies := collectionPolicyScope{}
+	policies.set(Keys("jobs"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	baseline, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, defaultProjectionLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("unbounded identified inheritance: %#v", diagnostics)
+	}
+	outputNodes, within := inheritanceLowerBoundCount(baseline.root, -1)
+	if !within || outputNodes < 2 {
+		t.Fatalf("identified output node count = %d, within %t", outputNodes, within)
+	}
+	limits := defaultProjectionLimits()
+	limits.nodes = outputNodes
+	if result, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, limits); result == nil || len(diagnostics) != 0 {
+		t.Fatalf("at output-node boundary: result = %#v, diagnostics = %#v", result, diagnostics)
+	}
+	limits.nodes = outputNodes - 1
+	if result, diagnostics := expandInheritanceWithCollectionRules(root, nil, policies, sequencePolicy{}, limits); result != nil ||
+		len(diagnostics) != 1 || diagnostics[0].Code != CodeSchemaProjectionLimit {
+		t.Fatalf("below output-node boundary: result = %#v, diagnostics = %#v", result, diagnostics)
+	}
+}
+
+func TestIdentifiedInheritanceRequiresChildIdentityBeforeParentLookup(t *testing.T) {
+	sequence := parseIdentifiedInheritanceSequence(t, "missing-child-field", `- id: child
+  extends: {id: parent, tenant: acme}
+- id: parent
+  tenant: acme
+`)
+	_, diagnostics := analyzeIdentifiedInheritanceGraph(sequence, Keys("jobs"), []string{"id", "tenant"})
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != "/jobs/0/tenant" {
+		t.Fatalf("missing child identity diagnostics = %#v", diagnostics)
+	}
+}
+
+func TestIdentifiedInheritanceRejectsMalformedAndMissingReferences(t *testing.T) {
+	tests := []struct {
+		name     string
+		value    string
+		wantCode Code
+	}{
+		{name: "string shorthand", value: "extends: parent\n", wantCode: CodeInheritanceInvalid},
+		{name: "sequence shorthand", value: "extends: [{id: parent, tenant: acme}]\n", wantCode: CodeInheritanceInvalid},
+		{name: "missing component", value: "extends: {id: parent}\n", wantCode: CodeInheritanceInvalid},
+		{name: "extra component", value: "extends: {id: parent, tenant: acme, extra: value}\n", wantCode: CodeInheritanceInvalid},
+		{name: "mapping component", value: "extends: {id: {nested: value}, tenant: acme}\n", wantCode: CodeInheritanceInvalid},
+		{name: "missing parent", value: "extends: {id: missing, tenant: acme}\n", wantCode: CodeInheritanceMissing},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			sequence := parseIdentifiedInheritanceSequence(t, "bad-reference", "- id: child\n  tenant: acme\n  "+test.value)
+			_, diagnostics := analyzeIdentifiedInheritanceGraph(sequence, Keys("jobs"), []string{"id", "tenant"})
+			if len(diagnostics) != 1 || diagnostics[0].Code != test.wantCode || diagnostics[0].Path.String() != "/jobs/0/extends" && diagnostics[0].Code != CodeInheritanceInvalid {
+				t.Fatalf("diagnostics = %#v", diagnostics)
+			}
+			if diagnostics[0].Code == CodeInheritanceMissing && diagnostics[0].Path.String() != "/jobs/0/extends" {
+				t.Fatalf("missing-parent path = %s", diagnostics[0].Path)
+			}
+		})
+	}
+}
+
+func TestIdentifiedInheritanceGraphFindsSelfAndLongerCycles(t *testing.T) {
+	for _, input := range []string{
+		`- id: self
+  tenant: acme
+  extends: {id: self, tenant: acme}
+`,
+		`- id: alpha
+  tenant: acme
+  extends: {id: beta, tenant: acme}
+- id: beta
+  tenant: acme
+  extends: {id: gamma, tenant: acme}
+- id: gamma
+  tenant: acme
+  extends: {id: alpha, tenant: acme}
+`,
+	} {
+		graph, diagnostics := analyzeIdentifiedInheritanceGraph(parseIdentifiedInheritanceSequence(t, "cycle", input), Keys("jobs"), []string{"id", "tenant"})
+		if len(diagnostics) != 0 {
+			t.Fatalf("analyze cycle graph: %#v", diagnostics)
+		}
+		_, diagnostics = graph.schedule()
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeInheritanceCycle || diagnostics[0].Path.String() == "" {
+			t.Fatalf("cycle diagnostics = %#v", diagnostics)
+		}
+		if diagnostics[0].Primary == nil || diagnostics[0].Primary.SourceID != "cycle" {
+			t.Fatalf("cycle primary location = %#v", diagnostics[0].Primary)
+		}
+	}
+}
+
+func TestIdentifiedInheritanceScopesCannotReferenceOtherCollections(t *testing.T) {
+	other := parseIdentifiedInheritanceSequence(t, "other-collection", `- id: parent
+  tenant: acme
+`)
+	_, diagnostics := analyzeIdentifiedInheritanceGraph(other, Keys("other"), []string{"id", "tenant"})
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	first := parseIdentifiedInheritanceSequence(t, "first-collection", `- id: child
+  tenant: acme
+  extends: {id: parent, tenant: acme}
+`)
+	_, diagnostics = analyzeIdentifiedInheritanceGraph(first, Keys("first"), []string{"id", "tenant"})
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeInheritanceMissing {
+		t.Fatalf("cross-collection reference diagnostics = %#v", diagnostics)
+	}
+}
+
+func TestIdentifiedInheritanceAcceptsStrictlyComposedParentReference(t *testing.T) {
+	left := parseCompositionDocument(t, "reference-left", "extends: {id: parent}\n")
+	right := parseCompositionDocument(t, "reference-right", "extends: {tenant: acme}\n")
+	reference, diagnostics := composeDocuments(left, right)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose disjoint reference helpers: %#v", diagnostics)
+	}
+	child, diagnostics := composeDocuments(parseCompositionDocument(t, "child-fields", "id: child\ntenant: acme\n"), reference.root)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose child fields and reference: %#v", diagnostics)
+	}
+	parent := parseCompositionDocument(t, "parent", "id: parent\ntenant: acme\n")
+	sequence := &document.Node{Kind: document.Sequence, Sequence: []*document.Node{child.root, parent}}
+	graph, diagnostics := analyzeIdentifiedInheritanceGraph(sequence, Keys("jobs"), []string{"id", "tenant"})
+	if len(diagnostics) != 0 {
+		t.Fatalf("analyze composed reference: %#v", diagnostics)
+	}
+	if len(graph.edges) != 1 || graph.edges[0] != (dependencyEdge{prerequisite: 1, dependent: 0}) {
+		t.Fatalf("composed reference edge = %#v", graph.edges)
+	}
+
+	_, diagnostics = composeDocuments(
+		parseCompositionDocument(t, "overlap-a", "extends: {id: first}\n"),
+		parseCompositionDocument(t, "overlap-b", "extends: {id: second}\n"),
+	)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeConflict {
+		t.Fatalf("overlapping reference fields should conflict during strict composition: %#v", diagnostics)
+	}
+}
+
+func TestIdentifiedInheritanceValidatesOnlySurvivingRelationships(t *testing.T) {
+	lower := parseIdentifiedInheritanceSequence(t, "superseded", `- id: shared
+  extends: {id: absent, tenant: acme}
+`)
+	higher := parseIdentifiedInheritanceSequence(t, "cancelled", `- id: shared
+  extends: null
+`)
+	resolution := collectionPolicyResolution{
+		operation: sequenceModeUpsert, effectiveIdentityFields: []string{"id"},
+	}
+	combined, diagnostics := combineSequence(lower, higher, resolution, sequenceCombinationContext{destination: Keys("jobs")})
+	if len(diagnostics) != 0 {
+		t.Fatalf("combine surviving reference: %#v", diagnostics)
+	}
+	graph, diagnostics := analyzeIdentifiedInheritanceGraph(combined.value, Keys("jobs"), []string{"id"})
+	if len(diagnostics) != 0 || len(graph.edges) != 0 || !graph.nodes[0].cancelled {
+		t.Fatalf("superseded missing reference was validated: graph=%#v diagnostics=%#v", graph, diagnostics)
+	}
+}

internal/engine/inheritance_identity_history_test.go

@@ -0,0 +1,87 @@
+package engine
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+)
+
+func TestRecordInheritanceHistoryPreservesChildIdentity(t *testing.T) {
+	t.Parallel()
+	for _, compound := range []bool{false, true} {
+		t.Run(fmt.Sprintf("compound=%t", compound), func(t *testing.T) {
+			key, reference := "id", "{id: base}"
+			identities := map[string]string{"id": "child"}
+			if compound {
+				key, reference = "[id, tenant]", "{id: base, tenant: parent-team}"
+				identities["tenant"] = "child-team"
+			}
+			body := "configkit:\n  sequences: [{destination: [items], key: " + key + "}]\nitems:\n  - id: base\n    tenant: parent-team\n    value: inherited\n  - id: child\n    tenant: child-team\n    extends: " + reference + "\n"
+			loaded, err := testLoad(Bytes("records", []byte(body)), Options[map[string]any]{})
+			if err != nil {
+				t.Fatal(err)
+			}
+			child := Keys("items").Index(1)
+			for field, want := range identities {
+				path := child.Key(field)
+				info, found := loaded.Metadata().Lookup(path)
+				if !found || !info.Explicit || len(info.Origin.Inheritance) != 0 {
+					t.Fatalf("child identity provenance = %#v, found %t", info, found)
+				}
+				for _, change := range loaded.Metadata().History(path) {
+					if change.Origin.Operation == ChangeInheritance {
+						t.Fatalf("child identity received inheritance history: %#v", change)
+					}
+				}
+				explanation, found := loaded.Explain(path)
+				if !found {
+					t.Fatalf("missing identity explanation at %s", path)
+				}
+				for _, change := range explanation.History {
+					for _, snapshot := range []ValueSnapshot{change.Before, change.After} {
+						if snapshot.Present && snapshot.YAML != want+"\n" {
+							t.Fatalf("child identity snapshot = %q, want %q", snapshot.YAML, want)
+						}
+					}
+				}
+			}
+			for _, query := range []Path{child, Keys("items"), {}} {
+				explanation, found := loaded.Explain(query)
+				if !found {
+					t.Fatalf("missing ancestor explanation at %s", query)
+				}
+				relative, _ := relativeHistoryPath(query, child)
+				for _, change := range explanation.History {
+					for _, snapshot := range []ValueSnapshot{change.Before, change.After} {
+						if !snapshot.Present {
+							continue
+						}
+						wrapped := "snapshot:\n  " + strings.ReplaceAll(snapshot.YAML, "\n", "\n  ") + "\n"
+						root := parseItemPolicyDocument(t, "history", wrapped)
+						for field, want := range identities {
+							value, present := documentAtPath(root, appendDestination(Keys("snapshot"), relative.Key(field)))
+							if present && value.Text != want {
+								t.Fatalf("ancestor %s snapshot has child %s = %q", query, field, value.Text)
+							}
+						}
+					}
+				}
+			}
+			payload, found := loaded.Explain(child.Key("value"))
+			if !found || payload.Effective.YAML != "inherited\n" {
+				t.Fatalf("inherited payload = %#v, found %t", payload, found)
+			}
+			inherited := false
+			for _, change := range payload.History {
+				inherited = inherited || change.Origin.Operation == ChangeInheritance
+			}
+			if !inherited {
+				t.Fatal("ordinary inherited payload lost its history")
+			}
+			parent, found := loaded.Explain(Keys("items").Index(0).Key("id"))
+			if !found || parent.Effective.YAML != "base\n" || len(parent.History) == 0 {
+				t.Fatalf("parent identity history = %#v, found %t", parent, found)
+			}
+		})
+	}
+}

internal/engine/inheritance_load.go

@@ -27,11 +27,12 @@ func containsInheritanceDirective(root *document.Node) bool {
 	return visit(root)
 }
 
-func inheritanceVersionDiagnostic(rule *VersionRule, expanded *inheritanceScope) *Diagnostic {
+func projectInheritanceVersion(rule *VersionRule, expanded *inheritanceScope) (*VersionRule, *Diagnostic) {
 	if rule == nil || expanded == nil {
-		return nil
+		return rule, nil
 	}
 	for _, operation := range expanded.operations {
+		rule = projectVersionRule(rule, operation.sequences)
 		var location Location
 		var affected bool
 		if operation.control != nil {
@@ -50,18 +51,18 @@ func inheritanceVersionDiagnostic(rule *VersionRule, expanded *inheritanceScope)
 			}
 		}
 		if affected {
-			return &Diagnostic{
+			return rule, &Diagnostic{
 				Code: CodeInheritanceVersion, Severity: SeverityError, Path: rule.Path.clone(),
 				Message: "inheritance cannot change the schema-version path", Primary: &location,
 			}
 		}
 	}
-	return nil
+	return rule, nil
 }
 
 func inheritanceOperations(expanded *inheritanceScope) []inheritanceOperation {
 	if expanded == nil {
 		return nil
 	}
-	return expanded.operations
+	return cloneInheritanceOperations(expanded.operations)
 }

internal/engine/inheritance_origin.go

@@ -70,8 +70,14 @@ func mergeInheritanceOrigin(origins map[string]Origin, path Path, incoming Origi
 }
 
 func copyInheritanceSubtree(target, incoming map[string]Origin, node *document.Node, root Path) {
-	walkDocument(node, root, func(path Path, _ *document.Node) {
-		target[path.String()] = cloneOrigin(incoming[path.String()])
+	copyInheritanceSubtreeAt(target, incoming, node, root, root)
+}
+
+func copyInheritanceSubtreeAt(target, incoming map[string]Origin, node *document.Node, from, to Path) {
+	walkDocument(node, Path{}, func(relative Path, _ *document.Node) {
+		source := appendDestination(from, relative)
+		destination := appendDestination(to, relative)
+		target[destination.String()] = cloneOrigin(incoming[source.String()])
 	})
 }
 

internal/engine/inheritance_schedule.go

@@ -7,28 +7,39 @@ import (
 )
 
 type inheritanceTemplate struct {
-	name         string
-	entry        document.Entry
-	path         Path
-	parent       int
-	hasParent    bool
-	hasDirective bool
-	cancelled    bool
-	directive    document.Entry
+	name               string
+	entry              document.Entry
+	path               Path
+	collectionPolicies collectionPolicyScope
+	parent             int
+	hasParent          bool
+	hasDirective       bool
+	cancelled          bool
+	directive          document.Entry
 }
 
 type inheritanceGraph struct {
-	scope     *document.Node
-	scopePath Path
-	nodes     []inheritanceTemplate
-	edges     []dependencyEdge
-	byName    map[string]int
+	scope              *document.Node
+	scopePath          Path
+	collectionPolicies collectionPolicyScope
+	applicationPolicy  sequencePolicy
+	nodes              []inheritanceTemplate
+	edges              []dependencyEdge
+	byName             map[string]int
 }
 
 // analyzeInheritanceGraph retains only direct mapping siblings as graph nodes.
 // It validates declarations separately from applying their templates, leaving
 // nested scopes for the existing destination-local walk.
 func analyzeInheritanceGraph(scope *document.Node, scopePath Path) (*inheritanceGraph, []Diagnostic) {
+	return analyzeInheritanceGraphWithPolicies(scope, scopePath, collectionPolicyScope{})
+}
+
+func analyzeInheritanceGraphWithPolicies(scope *document.Node, scopePath Path, policies collectionPolicyScope) (*inheritanceGraph, []Diagnostic) {
+	return analyzeInheritanceGraphWithCollectionRules(scope, scopePath, policies, sequencePolicy{})
+}
+
+func analyzeInheritanceGraphWithCollectionRules(scope *document.Node, scopePath Path, policies collectionPolicyScope, applicationPolicy sequencePolicy) (*inheritanceGraph, []Diagnostic) {
 	if scope == nil || scope.Kind != document.Mapping {
 		return nil, []Diagnostic{{
 			Code: CodeInheritanceInvalid, Severity: SeverityError, Path: scopePath,
@@ -38,6 +49,7 @@ func analyzeInheritanceGraph(scope *document.Node, scopePath Path) (*inheritance
 
 	graph := &inheritanceGraph{
 		scope: scope, scopePath: scopePath,
+		collectionPolicies: cloneCollectionPolicyScopeForInheritance(policies), applicationPolicy: applicationPolicy,
 		byName: make(map[string]int, len(scope.Mapping)),
 	}
 	entries := make(map[string]document.Entry, len(scope.Mapping))
@@ -57,6 +69,7 @@ func analyzeInheritanceGraph(scope *document.Node, scopePath Path) (*inheritance
 		graph.byName[name] = index
 		graph.nodes = append(graph.nodes, inheritanceTemplate{
 			name: name, entry: entries[name], path: scopePath.Key(name),
+			collectionPolicies: inheritancePolicyScopeAtPath(policies, scopePath.Key(name)),
 		})
 	}
 
@@ -115,7 +128,15 @@ func (graph *inheritanceGraph) schedule() ([]int, []Diagnostic) {
 }
 
 func expandSiblingDefinitionsWithOrigins(scope *document.Node, scopePath Path, limits projectionLimits, inputOrigins map[string]Origin, budget ...*retainedNodeCounter) (*inheritanceScope, []Diagnostic) {
-	graph, diagnostics := analyzeInheritanceGraph(scope, scopePath)
+	return expandSiblingDefinitionsWithPolicies(scope, scopePath, limits, inputOrigins, collectionPolicyScope{}, budget...)
+}
+
+func expandSiblingDefinitionsWithPolicies(scope *document.Node, scopePath Path, limits projectionLimits, inputOrigins map[string]Origin, policies collectionPolicyScope, budget ...*retainedNodeCounter) (*inheritanceScope, []Diagnostic) {
+	return expandSiblingDefinitionsWithCollectionRules(scope, scopePath, limits, inputOrigins, policies, sequencePolicy{}, budget...)
+}
+
+func expandSiblingDefinitionsWithCollectionRules(scope *document.Node, scopePath Path, limits projectionLimits, inputOrigins map[string]Origin, policies collectionPolicyScope, applicationPolicy sequencePolicy, budget ...*retainedNodeCounter) (*inheritanceScope, []Diagnostic) {
+	graph, diagnostics := analyzeInheritanceGraphWithCollectionRules(scope, scopePath, policies, applicationPolicy)
 	if len(diagnostics) != 0 {
 		return nil, diagnostics
 	}
@@ -123,44 +144,56 @@ func expandSiblingDefinitionsWithOrigins(scope *document.Node, scopePath Path, l
 	if len(diagnostics) != 0 {
 		return nil, diagnostics
 	}
-	return applyInheritanceTemplates(graph, order, limits, inputOrigins, budget...)
+	result, diagnostics := applyInheritanceTemplates(graph, order, limits, inputOrigins, budget...)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	return result, nil
 }
 
 // applyInheritanceTemplates builds detached templates in the supplied
 // dependency-ready order while retaining the existing origins, merge history,
 // and node-accounting evidence. The root keeps its authored mapping order.
 func applyInheritanceTemplates(graph *inheritanceGraph, order []int, limits projectionLimits, inputOrigins map[string]Origin, budget ...*retainedNodeCounter) (*inheritanceScope, []Diagnostic) {
-	resolved := make([]*document.Node, len(graph.nodes))
-	resolvedOrigins := make([]map[string]Origin, len(graph.nodes))
+	return applyInheritanceScopeTemplates(mappingInheritanceScope{graph: graph}, order, limits, inputOrigins, budget...)
+}
+
+func applyInheritanceScopeTemplates(adapter inheritanceScopeAdapter, order []int, limits projectionLimits, inputOrigins map[string]Origin, budget ...*retainedNodeCounter) (*inheritanceScope, []Diagnostic) {
+	templates := adapter.templates()
+	resolved := make([]*document.Node, len(templates))
+	resolvedOrigins := make([]map[string]Origin, len(templates))
+	resolvedPolicyTemplates := make([][]collectionPolicyScope, len(templates))
+	resolvedPolicies := make([]collectionPolicyScope, len(templates))
 	result := &inheritanceScope{}
 	counter := newRetainedNodeCounter(historyNodeLimit)
 	if len(budget) != 0 {
 		counter = budget[0]
 	}
-	retained := 1 // scope mapping node
-	for _, entry := range graph.scope.Mapping {
-		if entry.Value.Kind == document.Mapping {
+	retained := 1 // scope container node
+	for _, slot := range adapter.slots() {
+		if slot.hasTemplate || slot.value.Kind == document.Mapping {
 			continue
 		}
 		remaining := limits.nodes - retained - 1
 		if limits.nodes >= 0 && remaining < 0 {
-			return nil, []Diagnostic{inheritanceBudgetDiagnostic(graph.scopePath.Key(entry.Key), entry.Value.Location)}
+			return nil, []Diagnostic{inheritanceBudgetDiagnostic(slot.path, slot.value.Location)}
 		}
-		count, within := inheritanceLowerBoundCount(entry.Value, remaining)
+		count, within := inheritanceLowerBoundCount(slot.value, remaining)
 		if !within {
-			return nil, []Diagnostic{inheritanceBudgetDiagnostic(graph.scopePath.Key(entry.Key), entry.Value.Location)}
+			return nil, []Diagnostic{inheritanceBudgetDiagnostic(slot.path, slot.value.Location)}
 		}
 		retained += 1 + count
 	}
 
 	for _, index := range order {
-		node := graph.nodes[index]
+		node := templates[index]
+		templatePolicies := cloneCollectionPolicyScopeForInheritance(node.collectionPolicies)
 		payload := withoutInheritanceDirective(node.entry.Value)
 		operationStart, replacementStart := len(result.operations), len(result.replacements)
 		childOrigins := directInheritanceOrigins(payload, node.path, inputOrigins)
 		if node.hasDirective {
 			control := inheritanceControl{
-				path:      node.path.Key(inheritanceKey),
+				path:      node.directivePath,
 				locations: []Location{publicLocation(node.directive.Value.Location)},
 				cancelled: node.cancelled,
 			}
@@ -171,7 +204,7 @@ func applyInheritanceTemplates(graph *inheritanceGraph, order []int, limits proj
 			})
 		}
 		if limits.nodes >= 0 {
-			remaining := limits.nodes - retained - 1 // the sibling key
+			remaining := limits.nodes - retained - adapter.slotOverhead()
 			within := inheritanceLowerBoundWithin(payload, remaining)
 			if node.hasParent {
 				within = inheritanceOverlayLowerBoundWithin(resolved[node.parent], payload, remaining)
@@ -183,14 +216,46 @@ func applyInheritanceTemplates(graph *inheritanceGraph, order []int, limits proj
 
 		if node.hasParent {
 			parent := resolved[node.parent]
-			merged := document.Clone(parent)
+			parentPolicies := cloneInheritancePolicyTemplates(resolvedPolicyTemplates[node.parent])
+			effectivePolicies := append(cloneInheritancePolicyTemplates(parentPolicies), cloneCollectionPolicyScopeForInheritance(templatePolicies))
+			parentPolicyScope := projectInheritanceCollectionPolicies(resolvedPolicies[node.parent], node.path)
+			childPolicyScope := projectCurrentInheritanceCollectionPolicies(templatePolicies, node.path)
+			var replaced collectionReplacementPaths
+			if len(parentPolicyScope.collections) != 0 || len(childPolicyScope.collections) != 0 {
+				claims := compositionClaims{byPath: make(map[string][]compositionClaim)}
+				claims.append(payload, node.path, 0)
+				declarations := make(map[string][]sequenceDeclarationSpec, len(childPolicyScope.collections))
+				for key, entry := range childPolicyScope.collections {
+					declarations[key] = inheritanceDeclarationsAt(entry.destination, entry.policy)
+				}
+				parentPolicyScope, replaced = lowerCollectionPoliciesForClaims(parentPolicyScope, claims.ordered, declarations, adapter.applicationPolicy())
+			}
+			merged := inheritanceParentPayload(parent, node.identityFields)
+			historyParent := parent
+			if len(node.identityFields) != 0 {
+				// The retained parent snapshot is the inherited payload, before
+				// child fields are applied, with parent identity excluded.
+				historyParent = document.Clone(merged)
+			}
+			mergedPolicyScope, policyDiagnostics := mergeInheritanceCollectionPolicies(
+				parentPolicyScope, childPolicyScope, node.path, parent, payload, adapter.applicationPolicy(), replaced,
+			)
+			if len(policyDiagnostics) != 0 {
+				return nil, policyDiagnostics
+			}
 			transfer := inheritanceTransfer{
-				from: graph.nodes[node.parent].path, to: node.path,
-				reference: node.path.Key(inheritanceKey),
-				locations: []Location{publicLocation(node.directive.Value.Location)},
+				from: templates[node.parent].path, to: node.path,
+				reference:       node.directivePath,
+				locations:       []Location{publicLocation(node.directive.Value.Location)},
+				policyTemplates: parentPolicies, templatePolicies: cloneCollectionPolicyScopeForInheritance(templatePolicies),
+				projectedPolicies: projectInheritancePolicyTemplates(
+					[]collectionPolicyScope{resolvedPolicies[node.parent]}, node.path,
+				),
 			}
 			mergedOrigins := transferredInheritanceOrigins(resolvedOrigins[node.parent], transfer.from, node.path, transfer)
 			mergeInheritanceOrigin(mergedOrigins, node.path, childOrigins[node.path.String()])
+			var sequenceContributions []sequenceHistoryContribution
+			var combinationDiagnostics []Diagnostic
 			mergeRecursiveMappings(merged, payload, node.path, new(mappingIndex), recursiveMergeHooks{
 				added: func(childPath Path, incoming *document.Node) {
 					copyInheritanceSubtree(mergedOrigins, childOrigins, incoming, childPath)
@@ -207,21 +272,74 @@ func applyInheritanceTemplates(graph *inheritanceGraph, order []int, limits proj
 					deleteOriginSubtree(mergedOrigins, childPath, existing)
 					copyInheritanceSubtree(mergedOrigins, childOrigins, incoming, childPath)
 				},
+				merge: func(childPath Path, existing, incoming *document.Node) (*document.Node, bool) {
+					resolution, _, _, active, issues := inheritanceCollectionResolution(
+						childPath, parentPolicyScope, childPolicyScope, adapter.applicationPolicy(), incoming,
+					)
+					if len(issues) != 0 {
+						combinationDiagnostics = append(combinationDiagnostics, issues...)
+						return existing, false
+					}
+					if !active {
+						return nil, false
+					}
+					lowerValue := existing
+					combined, problems := combineSequence(lowerValue, incoming, resolution, sequenceCombinationContext{destination: childPath})
+					if len(problems) != 0 {
+						combinationDiagnostics = append(combinationDiagnostics, problems...)
+						return existing, false
+					}
+					policy := applyInheritanceSequencePolicy(
+						childPath, combined, resolution, parentPolicyScope, childPolicyScope,
+					)
+					mergedPolicyScope.set(childPath, policy)
+					applyInheritanceSequenceOrigins(
+						result, mergedOrigins, childOrigins, childPath, lowerValue, incoming, combined, resolution.operation,
+					)
+					history := sequenceHistoryContribution{path: childPath.clone(), mode: sequenceHistoryMapped}
+					if resolution.operation == sequenceModeReplace {
+						history.mode = sequenceHistoryReplace
+						if incoming != nil && incoming.Kind == document.Sequence {
+							history.length = len(incoming.Sequence)
+						}
+					} else {
+						history.items = append([]sequenceItemProjection(nil), combined.higherItems...)
+						history.replacements = append([]sequenceItemReplacement(nil), combined.replacements...)
+					}
+					sequenceContributions = append(sequenceContributions, history)
+					return combined.value, true
+				},
 			})
+			preserveInheritanceIdentityFields(merged, payload, node.identityFields)
+			if len(combinationDiagnostics) != 0 {
+				return nil, canonicalDiagnostics(combinationDiagnostics)
+			}
+			if problems := validateRegisteredInheritanceSequences(merged, node.path, adapter.applicationPolicy()); len(problems) != 0 {
+				return nil, problems
+			}
 			merged.Location = node.entry.Value.Location
 			resolved[index], resolvedOrigins[index] = merged, mergedOrigins
+			resolvedPolicies[index] = inheritancePolicyScopeAtPath(mergedPolicyScope, node.path)
 			result.transfers = append(result.transfers, transfer)
 			result.operations = append(result.operations, inheritanceOperation{
-				transfer: &transfer, parent: parent, effective: merged,
+				transfer: &transfer, parent: historyParent, effective: merged,
 				parentOrigins: resolvedOrigins[node.parent], effectiveOrigins: mergedOrigins,
+				parentPolicies:    cloneInheritancePolicyTemplates(parentPolicies),
+				templatePolicies:  cloneCollectionPolicyScopeForInheritance(templatePolicies),
+				effectivePolicies: cloneInheritancePolicyTemplates(effectivePolicies),
+				sequences:         cloneSequenceHistoryContributions(sequenceContributions),
+				identityFields:    cloneStrings(node.identityFields),
 			})
+			resolvedPolicyTemplates[index] = effectivePolicies
 		} else {
 			resolved[index] = document.Clone(payload)
 			resolvedOrigins[index] = childOrigins
+			resolvedPolicyTemplates[index] = []collectionPolicyScope{templatePolicies}
+			resolvedPolicies[index] = cloneCollectionPolicyScopeForInheritance(templatePolicies)
 		}
 
 		count, _ := inheritanceLowerBoundCount(resolved[index], limits.nodes)
-		retained += 1 + count
+		retained += adapter.slotOverhead() + count
 		for _, operation := range result.operations[operationStart:] {
 			if !counter.add(operation.parent) || !counter.add(operation.effective) {
 				return nil, []Diagnostic{inheritanceHistoryBudgetDiagnostic(node.path, node.entry.Value.Location)}
@@ -234,26 +352,27 @@ func applyInheritanceTemplates(graph *inheritanceGraph, order []int, limits proj
 		}
 	}
 
-	root := *graph.scope
-	root.Mapping = make([]document.Entry, len(graph.scope.Mapping))
-	result.origins = directInheritanceOrigins(&document.Node{Kind: document.Mapping, Location: graph.scope.Location}, graph.scopePath, inputOrigins)
-	for i, entry := range graph.scope.Mapping {
-		root.Mapping[i] = entry
-		if index, found := graph.byName[entry.Key]; found {
-			root.Mapping[i].Value = resolved[index]
+	root := adapter.rebuild(resolved)
+	result.collectionPolicies = collectionPolicyScope{}
+	result.origins = directInheritanceOrigins(&document.Node{Kind: root.Kind, Location: root.Location}, adapter.scopePath(), inputOrigins)
+	for _, slot := range adapter.slots() {
+		if slot.hasTemplate {
+			index := slot.template
+			projectInheritancePolicyRoots(&result.collectionPolicies, resolvedPolicies[index], templates[index].path)
 			for pointer, origin := range resolvedOrigins[index] {
 				result.origins[pointer] = origin
 			}
 			continue
 		}
-		root.Mapping[i].Value = document.Clone(entry.Value)
-		for pointer, origin := range directInheritanceOrigins(entry.Value, graph.scopePath.Key(entry.Key), inputOrigins) {
+		localPolicies := inheritancePolicyScopeAtPath(adapter.collectionPolicies(), slot.path)
+		projectInheritancePolicyRoots(&result.collectionPolicies, localPolicies, slot.path)
+		for pointer, origin := range directInheritanceOrigins(slot.value, slot.path, inputOrigins) {
 			result.origins[pointer] = origin
 		}
 	}
-	result.root = &root
+	result.root = root
 	if !inheritanceLowerBoundWithin(result.root, limits.nodes) {
-		return nil, []Diagnostic{inheritanceBudgetDiagnostic(graph.scopePath, graph.scope.Location)}
+		return nil, []Diagnostic{inheritanceBudgetDiagnostic(adapter.scopePath(), adapter.scope().Location)}
 	}
 	return result, nil
 }

internal/engine/inheritance_schedule_test.go

@@ -110,6 +110,91 @@ beta:
 	}
 }
 
+func TestInheritanceTransportsReusableCollectionPolicyTemplates(t *testing.T) {
+	root := parseItemPolicyDocument(t, "templates", `base:
+  prompts:
+    - id: shared
+      children:
+        derived:
+          extends: nested-base
+          own: destination-local
+        nested-base:
+          inherited: source-value
+first:
+  extends: base
+second:
+  extends: base
+`)
+
+	policyLocation := Location{SourceID: "base-resource", Line: 2, Column: 3}
+	nestedLocation := Location{SourceID: "nested-resource", Line: 5, Column: 11}
+	nested := collectionPolicy{identityFields: []string{"key"}, identityPresent: true, identityLocation: &nestedLocation}
+	recordScope := collectionPolicyScope{}
+	recordScope.set(Keys("children", "prompts"), nested)
+	basePolicy := collectionPolicy{identityFields: []string{"id"}, identityPresent: true, identityLocation: &policyLocation}
+	basePolicy.setRecordPolicyAt(0, collectionRecordPolicy{owner: newCollectionRecordPolicy().owner, scope: recordScope})
+	policies := collectionPolicyScope{}
+	policies.set(Keys("base", "prompts"), basePolicy)
+
+	got, diagnostics := expandSiblingDefinitionsWithPolicies(root, Path{}, defaultProjectionLimits(), nil, policies)
+	if len(diagnostics) != 0 {
+		t.Fatalf("expand sibling templates: %#v", diagnostics)
+	}
+	withoutPolicies, diagnostics := expandSiblingDefinitionsWithOrigins(root, Path{}, defaultProjectionLimits(), nil)
+	if len(diagnostics) != 0 {
+		t.Fatalf("expand sibling templates without policy: %#v", diagnostics)
+	}
+	if !reflect.DeepEqual(got.root, withoutPolicies.root) {
+		t.Fatalf("policy transport changed inherited values:\n got %#v\nwant %#v", got.root, withoutPolicies.root)
+	}
+	var transfers []inheritanceOperation
+	for _, operation := range got.operations {
+		if operation.transfer != nil {
+			transfers = append(transfers, operation)
+		}
+	}
+	if len(transfers) != 2 {
+		t.Fatalf("transfer operations = %d, want two destination transfers", len(transfers))
+	}
+
+	for index, destination := range []string{"/first", "/second"} {
+		operation := transfers[index]
+		if operation.transfer == nil || len(operation.transfer.projectedPolicies) != 2 {
+			t.Fatalf("transfer %d projected policies = %#v, want collection and record-local policy", index, operation.transfer)
+		}
+		projected := operation.transfer.projectedPolicies
+		if projected[0].path.String() != destination+"/prompts" || projected[1].path.String() != destination+"/prompts/0/children/prompts" {
+			t.Fatalf("transfer %d policy paths = %q, %q", index, projected[0].path, projected[1].path)
+		}
+		if got := projected[0].policy.identityLocation; got == nil || *got != policyLocation {
+			t.Fatalf("transfer %d collection declaration location = %#v", index, got)
+		}
+		if got := projected[1].policy.identityLocation; got == nil || *got != nestedLocation {
+			t.Fatalf("transfer %d record-local declaration location = %#v", index, got)
+		}
+		if len(operation.templatePolicies.collections) != 0 {
+			t.Fatalf("transfer %d unexpectedly copied parent YAML policy onto child template", index)
+		}
+	}
+
+	first, second := transfers[0].transfer.projectedPolicies[0].policy, transfers[1].transfer.projectedPolicies[0].policy
+	if first.recordOrder[0] == second.recordOrder[0] {
+		t.Fatal("destination policy templates share a mutable record owner")
+	}
+	first.identityFields[0] = "changed"
+	if second.identityFields[0] != "id" {
+		t.Fatalf("mutating one destination changed another: %v", second.identityFields)
+	}
+	if basePolicy.identityFields[0] != "id" {
+		t.Fatalf("mutating a destination changed the source template: %v", basePolicy.identityFields)
+	}
+
+	firstValue, found := documentAtPath(got.root.Mapping[1].Value, Keys("prompts").Index(0).Key("children").Key("derived").Key("extends"))
+	if !found || firstValue.Text != "nested-base" {
+		t.Fatalf("nested template instruction = %#v, found %t; want original instruction retained", firstValue, found)
+	}
+}
+
 func TestInheritanceExpansionInterleavesUnequalBranches(t *testing.T) {
 	root := parseCompositionDocument(t, "branches", `a-grandchild:
   extends: z-child

internal/engine/inheritance_scope.go

@@ -0,0 +1,197 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// inheritanceScopeAdapter keeps relationship execution independent from the
+// container that owns the records. Adapters are private preparation machinery;
+// public loading continues to use mapping scopes until record inheritance is
+// activated separately.
+type inheritanceScopeAdapter interface {
+	scope() *document.Node
+	scopePath() Path
+	collectionPolicies() collectionPolicyScope
+	applicationPolicy() sequencePolicy
+	templates() []inheritanceExecutionTemplate
+	slots() []inheritanceScopeSlot
+	slotOverhead() int
+	rebuild(resolved []*document.Node) *document.Node
+}
+
+type inheritanceExecutionTemplate struct {
+	entry              document.Entry
+	path               Path
+	collectionPolicies collectionPolicyScope
+	parent             int
+	hasParent          bool
+	hasDirective       bool
+	cancelled          bool
+	directive          document.Entry
+	directivePath      Path
+	identityFields     []string
+}
+
+type inheritanceScopeSlot struct {
+	value       *document.Node
+	path        Path
+	template    int
+	hasTemplate bool
+}
+
+type mappingInheritanceScope struct{ graph *inheritanceGraph }
+
+func (scope mappingInheritanceScope) scope() *document.Node { return scope.graph.scope }
+func (scope mappingInheritanceScope) scopePath() Path       { return scope.graph.scopePath }
+func (scope mappingInheritanceScope) collectionPolicies() collectionPolicyScope {
+	return scope.graph.collectionPolicies
+}
+func (scope mappingInheritanceScope) applicationPolicy() sequencePolicy {
+	return scope.graph.applicationPolicy
+}
+func (scope mappingInheritanceScope) slotOverhead() int { return 1 }
+func (scope mappingInheritanceScope) templates() []inheritanceExecutionTemplate {
+	result := make([]inheritanceExecutionTemplate, len(scope.graph.nodes))
+	for index, node := range scope.graph.nodes {
+		var directive document.Entry
+		if node.hasDirective {
+			directive = node.directive
+		}
+		result[index] = inheritanceExecutionTemplate{
+			entry: node.entry, path: node.path,
+			collectionPolicies: node.collectionPolicies, parent: node.parent,
+			hasParent: node.hasParent, hasDirective: node.hasDirective,
+			cancelled: node.cancelled, directive: directive,
+			directivePath: node.path.Key(inheritanceKey),
+		}
+	}
+	return result
+}
+func (scope mappingInheritanceScope) slots() []inheritanceScopeSlot {
+	result := make([]inheritanceScopeSlot, len(scope.graph.scope.Mapping))
+	for index, entry := range scope.graph.scope.Mapping {
+		slot := inheritanceScopeSlot{
+			value: entry.Value, path: scope.graph.scopePath.Key(entry.Key),
+		}
+		if template, ok := scope.graph.byName[entry.Key]; ok {
+			slot.template, slot.hasTemplate = template, true
+		}
+		result[index] = slot
+	}
+	return result
+}
+func (scope mappingInheritanceScope) rebuild(resolved []*document.Node) *document.Node {
+	root := *scope.graph.scope
+	root.Mapping = make([]document.Entry, len(scope.graph.scope.Mapping))
+	for index, entry := range scope.graph.scope.Mapping {
+		root.Mapping[index] = entry
+		if template, ok := scope.graph.byName[entry.Key]; ok {
+			root.Mapping[index].Value = resolved[template]
+		} else {
+			root.Mapping[index].Value = document.Clone(entry.Value)
+		}
+	}
+	return &root
+}
+
+type identifiedSequenceInheritanceScope struct {
+	graph       *identifiedInheritanceGraph
+	policies    collectionPolicyScope
+	application sequencePolicy
+}
+
+func (scope identifiedSequenceInheritanceScope) scope() *document.Node { return scope.graph.scope }
+func (scope identifiedSequenceInheritanceScope) scopePath() Path       { return scope.graph.scopePath }
+func (scope identifiedSequenceInheritanceScope) collectionPolicies() collectionPolicyScope {
+	return scope.policies
+}
+func (scope identifiedSequenceInheritanceScope) applicationPolicy() sequencePolicy {
+	return scope.application
+}
+func (scope identifiedSequenceInheritanceScope) slotOverhead() int { return 0 }
+func (scope identifiedSequenceInheritanceScope) templates() []inheritanceExecutionTemplate {
+	result := make([]inheritanceExecutionTemplate, len(scope.graph.nodes))
+	for index, node := range scope.graph.nodes {
+		result[index] = inheritanceExecutionTemplate{
+			entry: document.Entry{Value: node.item}, path: node.path,
+			collectionPolicies: inheritancePolicyScopeAtPath(scope.policies, node.path),
+			parent:             node.parent, hasParent: node.hasParent,
+			hasDirective: node.directive != nil, cancelled: node.cancelled,
+			directive: document.Entry{Value: node.directive}, directivePath: node.directivePath,
+			identityFields: scope.graph.fields,
+		}
+	}
+	return result
+}
+func (scope identifiedSequenceInheritanceScope) slots() []inheritanceScopeSlot {
+	result := make([]inheritanceScopeSlot, len(scope.graph.nodes))
+	for index, node := range scope.graph.nodes {
+		result[index] = inheritanceScopeSlot{
+			value: node.item, path: node.path, template: index, hasTemplate: true,
+		}
+	}
+	return result
+}
+func (scope identifiedSequenceInheritanceScope) rebuild(resolved []*document.Node) *document.Node {
+	root := *scope.graph.scope
+	root.Sequence = make([]*document.Node, len(scope.graph.nodes))
+	for index := range root.Sequence {
+		root.Sequence[index] = resolved[index]
+	}
+	return &root
+}
+
+func preserveInheritanceIdentityFields(merged, child *document.Node, fields []string) {
+	if len(fields) == 0 || merged == nil || merged.Kind != document.Mapping || child == nil || child.Kind != document.Mapping {
+		return
+	}
+	for _, field := range fields {
+		for _, entry := range child.Mapping {
+			if entry.Key != field {
+				continue
+			}
+			for index := range merged.Mapping {
+				if merged.Mapping[index].Key == field {
+					merged.Mapping[index] = document.Entry{Key: field, Value: document.Clone(entry.Value)}
+					break
+				}
+			}
+			break
+		}
+	}
+}
+
+func inheritanceParentPayload(parent *document.Node, identityFields []string) *document.Node {
+	cloned := document.Clone(parent)
+	if len(identityFields) == 0 || cloned == nil || cloned.Kind != document.Mapping {
+		return cloned
+	}
+	excluded := make(map[string]struct{}, len(identityFields))
+	for _, field := range identityFields {
+		excluded[field] = struct{}{}
+	}
+	kept := cloned.Mapping[:0]
+	for _, entry := range cloned.Mapping {
+		if _, omit := excluded[entry.Key]; !omit {
+			kept = append(kept, entry)
+		}
+	}
+	cloned.Mapping = kept
+	return cloned
+}
+
+func applyIdentifiedInheritanceTemplates(
+	graph *identifiedInheritanceGraph,
+	limits projectionLimits,
+	inputOrigins map[string]Origin,
+	policies collectionPolicyScope,
+	application sequencePolicy,
+	budget ...*retainedNodeCounter,
+) (*inheritanceScope, []Diagnostic) {
+	order, diagnostics := graph.schedule()
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	adapter := identifiedSequenceInheritanceScope{
+		graph: graph, policies: policies, application: application,
+	}
+	return applyInheritanceScopeTemplates(adapter, order, limits, inputOrigins, budget...)
+}

internal/engine/inheritance_walk.go

@@ -8,14 +8,16 @@ import (
 )
 
 type inheritanceWalker struct {
-	nodes        int // logical non-directive nodes in the entire working tree
-	origins      map[string]Origin
-	limits       projectionLimits
-	retained     *retainedNodeCounter
-	transfers    []inheritanceTransfer
-	controls     []inheritanceControl
-	replacements []inheritanceReplacement
-	operations   []inheritanceOperation
+	nodes              int // logical non-directive nodes in the entire working tree
+	origins            map[string]Origin
+	collectionPolicies collectionPolicyScope
+	applicationPolicy  sequencePolicy
+	limits             projectionLimits
+	retained           *retainedNodeCounter
+	transfers          []inheritanceTransfer
+	controls           []inheritanceControl
+	replacements       []inheritanceReplacement
+	operations         []inheritanceOperation
 }
 
 // expandInheritanceTree resolves each destination scope after its enclosing
@@ -25,10 +27,26 @@ func expandInheritanceTree(input *document.Node, limits projectionLimits) (*inhe
 }
 
 func expandInheritanceWithOrigins(input *document.Node, inputOrigins map[string]Origin, limits projectionLimits) (*inheritanceScope, []Diagnostic) {
-	return expandInheritanceWithBudgets(input, inputOrigins, limits, historyNodeLimit)
+	return expandInheritanceWithPolicies(input, inputOrigins, collectionPolicyScope{}, limits)
 }
 
 func expandInheritanceWithBudgets(input *document.Node, inputOrigins map[string]Origin, limits projectionLimits, historyLimit int) (*inheritanceScope, []Diagnostic) {
+	return expandInheritanceWithPolicyBudgets(input, inputOrigins, collectionPolicyScope{}, limits, historyLimit)
+}
+
+func expandInheritanceWithPolicies(input *document.Node, inputOrigins map[string]Origin, policies collectionPolicyScope, limits projectionLimits) (*inheritanceScope, []Diagnostic) {
+	return expandInheritanceWithCollectionRules(input, inputOrigins, policies, sequencePolicy{}, limits)
+}
+
+func expandInheritanceWithPolicyBudgets(input *document.Node, inputOrigins map[string]Origin, policies collectionPolicyScope, limits projectionLimits, historyLimit int) (*inheritanceScope, []Diagnostic) {
+	return expandInheritanceWithCollectionRuleBudgets(input, inputOrigins, policies, sequencePolicy{}, limits, historyLimit)
+}
+
+func expandInheritanceWithCollectionRules(input *document.Node, inputOrigins map[string]Origin, policies collectionPolicyScope, applicationPolicy sequencePolicy, limits projectionLimits) (*inheritanceScope, []Diagnostic) {
+	return expandInheritanceWithCollectionRuleBudgets(input, inputOrigins, policies, applicationPolicy, limits, historyNodeLimit)
+}
+
+func expandInheritanceWithCollectionRuleBudgets(input *document.Node, inputOrigins map[string]Origin, policies collectionPolicyScope, applicationPolicy sequencePolicy, limits projectionLimits, historyLimit int) (*inheritanceScope, []Diagnostic) {
 	if input == nil || input.Kind != document.Mapping {
 		return nil, []Diagnostic{{Code: CodeInheritanceInvalid, Severity: SeverityError,
 			Message: "inheritance requires a mapping document root"}}
@@ -44,7 +62,9 @@ func expandInheritanceWithBudgets(input *document.Node, inputOrigins map[string]
 	}
 	walker := inheritanceWalker{
 		nodes: nodes, limits: limits, origins: origins,
-		retained: newRetainedNodeCounter(historyLimit),
+		collectionPolicies: cloneCollectionPolicyScopeForInheritance(policies),
+		applicationPolicy:  applicationPolicy,
+		retained:           newRetainedNodeCounter(historyLimit),
 	}
 	if problem := walker.visit(&root, Path{}, true); problem != nil {
 		return nil, []Diagnostic{*problem}
@@ -53,8 +73,10 @@ func expandInheritanceWithBudgets(input *document.Node, inputOrigins map[string]
 		return nil, []Diagnostic{*problem}
 	}
 	return &inheritanceScope{
-		root: root, origins: walker.origins, transfers: walker.transfers,
-		controls: walker.controls, replacements: walker.replacements, operations: walker.operations,
+		root: root, origins: walker.origins,
+		collectionPolicies: cloneCollectionPolicyScopeForInheritance(walker.collectionPolicies),
+		transfers:          walker.transfers,
+		controls:           walker.controls, replacements: walker.replacements, operations: walker.operations,
 	}, nil
 }
 
@@ -90,11 +112,21 @@ func (w *inheritanceWalker) visit(node **document.Node, path Path, unscoped bool
 			if limits.nodes >= 0 {
 				limits.nodes -= w.nodes - before
 			}
-			resolved, diagnostics := expandSiblingDefinitionsWithOrigins(*node, path, limits, w.origins, w.retained)
+			resolved, diagnostics := expandSiblingDefinitionsWithCollectionRules(
+				*node, path, limits, w.origins, w.collectionPolicies, w.applicationPolicy, w.retained,
+			)
 			if len(diagnostics) != 0 {
 				return &diagnostics[0]
 			}
 			*node = resolved.root
+			for pointer, entry := range w.collectionPolicies.collections {
+				if pathHasPrefix(entry.destination, path) {
+					delete(w.collectionPolicies.collections, pointer)
+				}
+			}
+			for _, entry := range resolved.collectionPolicies.collections {
+				w.collectionPolicies.set(entry.destination, entry.policy)
+			}
 			deleteOriginSubtree(w.origins, path, original)
 			for pointer, origin := range resolved.origins {
 				w.origins[pointer] = origin
@@ -126,6 +158,11 @@ func (w *inheritanceWalker) visit(node **document.Node, path Path, unscoped bool
 			}
 		}
 	case document.Sequence:
+		if sequenceHasIdentifiedInheritanceReferences(*node) {
+			if problem := w.expandIdentifiedSequence(node, path); problem != nil {
+				return problem
+			}
+		}
 		working := **node
 		working.Sequence = slices.Clone(working.Sequence)
 		*node = &working
@@ -139,6 +176,60 @@ func (w *inheritanceWalker) visit(node **document.Node, path Path, unscoped bool
 	return nil
 }
 
+func (w *inheritanceWalker) expandIdentifiedSequence(node **document.Node, path Path) *Diagnostic {
+	policy, hasPolicy := w.collectionPolicies.at(path)
+	applicationFields, _ := w.applicationPolicy.identityFieldsAt(path)
+	var lower *collectionPolicy
+	if hasPolicy {
+		lower = &policy
+	}
+	resolution, policyDiagnostics := resolveCollectionPolicy(path, nil, applicationFields, lower)
+	if len(policyDiagnostics) != 0 {
+		return &policyDiagnostics[0]
+	}
+	// Without an identity rule, retain the existing diagnostic for a reference
+	// that has no enclosing sibling scope. A null cancellation needs no lookup.
+	if len(resolution.effectiveIdentityFields) == 0 {
+		return nil
+	}
+	original := *node
+	graph, diagnostics := analyzeIdentifiedInheritanceGraph(*node, path, resolution.effectiveIdentityFields)
+	if len(diagnostics) != 0 {
+		return &diagnostics[0]
+	}
+	before, _ := inheritanceLowerBoundCount(*node, -1)
+	limits := w.limits
+	if limits.nodes >= 0 {
+		limits.nodes -= w.nodes - before
+	}
+	resolved, diagnostics := applyIdentifiedInheritanceTemplates(
+		graph, limits, w.origins, w.collectionPolicies, w.applicationPolicy, w.retained,
+	)
+	if len(diagnostics) != 0 {
+		return &diagnostics[0]
+	}
+	*node = resolved.root
+	for pointer, entry := range w.collectionPolicies.collections {
+		if pathHasPrefix(entry.destination, path) {
+			delete(w.collectionPolicies.collections, pointer)
+		}
+	}
+	for _, entry := range resolved.collectionPolicies.collections {
+		w.collectionPolicies.set(entry.destination, entry.policy)
+	}
+	deleteOriginSubtree(w.origins, path, original)
+	for pointer, origin := range resolved.origins {
+		w.origins[pointer] = origin
+	}
+	w.transfers = append(w.transfers, resolved.transfers...)
+	w.controls = append(w.controls, resolved.controls...)
+	w.replacements = append(w.replacements, resolved.replacements...)
+	w.operations = append(w.operations, resolved.operations...)
+	after, _ := inheritanceLowerBoundCount(*node, -1)
+	w.nodes += after - before
+	return nil
+}
+
 func scopeHasInheritanceDefinitions(scope *document.Node) bool {
 	for _, entry := range scope.Mapping {
 		if entry.Value.Kind != document.Mapping {

internal/engine/item_policy_test.go

@@ -0,0 +1,471 @@
+package engine
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+	yamladapter "gitea.maximumdirect.net/eric/ConfigKit/internal/yaml"
+)
+
+func parseItemPolicyDocument(t *testing.T, sourceID, input string) *document.Node {
+	t.Helper()
+	root, issues := yamladapter.Parse(strings.NewReader(input), sourceID, yamladapter.Limits{
+		Depth: maxDocumentDepth, Nodes: maxDocumentNodes,
+	})
+	if len(issues) != 0 {
+		t.Fatalf("parse document: %#v", issues)
+	}
+	return root
+}
+
+func TestPendingItemCompositionKeepsLocalDeclarationsAndHelperIdentity(t *testing.T) {
+	t.Parallel()
+
+	declaration := sequenceDeclarationSpec{
+		destination: Keys("prompts"), identityFields: []string{"id"}, identityPresent: true,
+	}
+	itemScope := acquisitionScope{contributions: []acquiredContribution{
+		{
+			document:             parseItemPolicyDocument(t, "item", "name: authored\nprompts:\n  - id: authored\n"),
+			sequenceDeclarations: []sequenceDeclarationSpec{declaration},
+		},
+		{
+			document: parseItemPolicyDocument(t, "helper", "id: supplied\nprompts:\n  - id: helper\n"),
+		},
+	}}
+	outer := acquisitionScope{contributions: []acquiredContribution{{
+		source:      SourceInfo{ID: "item"},
+		payload:     parseItemPolicyDocument(t, "outer", "{}\n"),
+		destination: Keys("items"), pendingItem: &itemScope,
+	}}}
+
+	composed, diagnostics := composeAcquiredScopeWithPolicy(
+		&outer, collectionPolicyScope{}, sequencePolicy{}, newImportInclusionGraph(), nil, nil, nil, &importAccounting{},
+	)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose pending item scope: %#v", diagnostics)
+	}
+
+	item := outer.contributions[0].payload
+	if got, ok := documentAtPath(item, Keys("id")); !ok || got == nil || got.Text != "supplied" {
+		t.Fatalf("helper-supplied record identity = %#v", got)
+	}
+	if got, ok := documentAtPath(item, Keys("prompts")); !ok || got == nil || got.Kind != document.Sequence || len(got.Sequence) != 2 {
+		t.Fatalf("composed prompts = %#v, want two identified entries", got)
+	}
+	itemPolicy, ok := composed.collectionPolicies.at(Keys("items"))
+	if !ok {
+		t.Fatalf("projected item collection policy missing")
+	}
+	owned, ok := itemPolicy.recordPolicyAt(0)
+	if !ok {
+		t.Fatalf("projected item owner missing: %#v", itemPolicy)
+	}
+	if policy, ok := owned.scope.at(Keys("prompts")); !ok || !policy.identityPresent || len(policy.identityFields) != 1 || policy.identityFields[0] != "id" {
+		t.Fatalf("item-owned prompt policy = %#v, %v", policy, ok)
+	}
+	if _, ok := composed.collectionPolicies.at(Keys("prompts")); ok {
+		t.Fatal("item-local declaration escaped its owning record")
+	}
+}
+
+func TestPendingItemCompositionProjectsNestedIdentityDiagnostics(t *testing.T) {
+	t.Parallel()
+
+	childScope := acquisitionScope{contributions: []acquiredContribution{
+		{document: parseItemPolicyDocument(t, "child", "prompts:\n  - id: same\n"), sequenceDeclarations: []sequenceDeclarationSpec{{
+			destination: Keys("prompts"), identityFields: []string{"id"}, identityPresent: true,
+		}}},
+		{document: parseItemPolicyDocument(t, "child-helper", "prompts:\n  - id: same\n")},
+	}}
+	itemScope := acquisitionScope{contributions: []acquiredContribution{{
+		document: parseItemPolicyDocument(t, "item", "name: parent\n"),
+	}, {
+		source: SourceInfo{ID: "child"}, payload: parseItemPolicyDocument(t, "child", "{}\n"),
+		destination: Keys("children"), pendingItem: &childScope,
+	}}}
+	outer := acquisitionScope{contributions: []acquiredContribution{{
+		source: SourceInfo{ID: "item"}, payload: parseItemPolicyDocument(t, "outer", "{}\n"),
+		destination: Keys("items"), pendingItem: &itemScope,
+	}}}
+
+	traversal := importTraversal{accounting: &importAccounting{}, limits: defaultImportLimits()}
+	diagnostics := traversal.composePendingItems(&outer, sequencePolicy{})
+	if len(diagnostics) != 1 {
+		t.Fatalf("diagnostics = %#v, want one conflict", diagnostics)
+	}
+	if diagnostics[0].Code != CodeComposeConflict || diagnostics[0].Path.String() != "/items/0/children/0/prompts" {
+		t.Fatalf("diagnostic = %#v, want projected collection path", diagnostics[0])
+	}
+	if strings.Contains(fmt.Sprint(diagnostics[0]), "same") {
+		t.Fatalf("diagnostic disclosed identity value: %v", diagnostics[0])
+	}
+}
+
+func TestPendingItemCompositionAppliesApplicationIdentityConstraints(t *testing.T) {
+	t.Parallel()
+
+	itemScope := acquisitionScope{contributions: []acquiredContribution{{
+		document: parseItemPolicyDocument(t, "item", "prompts:\n  - text: missing-id\n"),
+	}}}
+	outer := acquisitionScope{contributions: []acquiredContribution{{
+		source: SourceInfo{ID: "item"}, payload: parseItemPolicyDocument(t, "outer", "{}\n"),
+		destination: Keys("items"), pendingItem: &itemScope,
+	}}}
+	policy, diagnostics := compileSequenceIdentityPolicy([]sequenceIdentityRegistration{{
+		selector: sequenceIdentitySelector{literalSequenceSelector("prompts")}, identityFields: []string{"id"},
+	}})
+	if len(diagnostics) != 0 {
+		t.Fatalf("compile application identity: %#v", diagnostics)
+	}
+
+	traversal := importTraversal{accounting: &importAccounting{}, limits: defaultImportLimits()}
+	diagnostics = traversal.composePendingItems(&outer, policy)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeComposeInvalid || diagnostics[0].Path.String() != "/items/0/prompts/0/id" {
+		t.Fatalf("application identity diagnostics = %#v", diagnostics)
+	}
+}
+
+func TestReplacingOuterCollectionRetiresDiscardedItemIdentity(t *testing.T) {
+	t.Parallel()
+
+	outerPath := Keys("items")
+	nestedPath := Keys("items").Index(0).Key("prompts")
+	lower := collectionPolicyScope{}
+	outerPolicy := collectionPolicy{}
+	outerPolicy.setRecordPolicy(newCollectionRecordPolicy())
+	lower.set(outerPath, outerPolicy)
+	lower.set(nestedPath, collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+
+	declarations := []sequenceDeclarationSpec{{
+		destination: outerPath, mode: sequenceModeReplace, modePresent: true,
+	}}
+	input := parseItemPolicyDocument(t, "replacement", "items:\n  - prompts:\n      - text: new\n")
+	composed, diagnostics := composeDocumentsWithCollectionPolicy(sequencePolicy{}, lower, declarations, input)
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose replacement: %#v", diagnostics)
+	}
+	policy, ok := composed.collectionPolicies.at(nestedPath)
+	if !ok || policy.identityPresent || len(policy.recordOrder) != 0 {
+		t.Fatalf("discarded nested owner policy = %#v, %v", policy, ok)
+	}
+}
+
+func TestNestedItemPolicyProjectionUsesStableOutputIndexes(t *testing.T) {
+	t.Parallel()
+
+	itemsPath := Keys("items")
+	outerPolicy := collectionPolicy{}
+	retainedScope := collectionPolicyScope{}
+	retainedScope.set(Keys("retained"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	outerPolicy.setRecordPolicy(collectionRecordPolicy{owner: newCollectionRecordPolicy().owner, scope: retainedScope})
+	composed := &composedDocument{collectionPolicies: collectionPolicyScope{}}
+	composed.collectionPolicies.set(itemsPath, outerPolicy)
+
+	firstScope := collectionPolicyScope{}
+	firstScope.set(Keys("prompts"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	secondScope := collectionPolicyScope{}
+	secondScope.set(Keys("prompts"), collectionPolicy{identityFields: []string{"slug"}, identityPresent: true})
+	scope := acquisitionScope{contributions: []acquiredContribution{
+		{document: parseItemPolicyDocument(t, "first", "items:\n  - id: first\n"), destination: itemsPath, nested: &composedDocument{collectionPolicies: firstScope}},
+		{document: parseItemPolicyDocument(t, "second", "items:\n  - id: second\n"), destination: itemsPath, nested: &composedDocument{collectionPolicies: secondScope}},
+	}}
+
+	projectNestedCollectionPolicies(composed, scope, nil)
+	policy, ok := composed.collectionPolicies.at(itemsPath)
+	if !ok || len(policy.recordOrder) != 3 {
+		t.Fatalf("record-owned policies = %#v, %v; want retained plus two item scopes", policy, ok)
+	}
+	for index, wantField := range []string{"id", "id", "slug"} {
+		record, ok := policy.recordPolicyAt(index)
+		if !ok {
+			t.Fatalf("record policy %d missing", index)
+		}
+		path := Keys("retained")
+		if index != 0 {
+			path = Keys("prompts")
+		}
+		nested, ok := record.scope.at(path)
+		if !ok || !nested.identityPresent || len(nested.identityFields) != 1 || nested.identityFields[0] != wantField {
+			t.Errorf("record policy %d = %#v, %v; want %q", index, nested, ok, wantField)
+		}
+	}
+}
+
+func TestItemPolicyProjectionCountsContributionsWithoutLocalPolicy(t *testing.T) {
+	t.Parallel()
+	items := Keys("items")
+	for _, assignments := range []map[int]int{nil, {1: 2, 3: 4}, {1: 2}, {3: 4}} {
+		t.Run(fmt.Sprint(assignments), func(t *testing.T) {
+			local := collectionPolicyScope{}
+			local.set(Keys("steps"), collectionPolicy{identityFields: []string{"name"}, identityPresent: true})
+			scope := acquisitionScope{contributions: []acquiredContribution{
+				{document: parseItemPolicyDocument(t, "inline", "items: [{id: inline-a}, {id: inline-b}]\n")},
+				{document: parseItemPolicyDocument(t, "first", "items: [{id: first}]\n"), destination: items, nested: &composedDocument{collectionPolicies: local}},
+				{document: parseItemPolicyDocument(t, "gap", "items: [{id: gap}]\n"), destination: items},
+				{document: parseItemPolicyDocument(t, "second", "items: [{id: second}]\n"), destination: items, nested: &composedDocument{collectionPolicies: local}},
+			}}
+			ranges := make(map[sequenceRangeKey]sequenceRange)
+			for sourceIndex, output := range assignments {
+				ranges[sequenceRangeKey{sourceIndex: sourceIndex, path: items.String()}] = sequenceRange{start: output, end: output + 1}
+			}
+			composed := &composedDocument{}
+			projectNestedCollectionPolicies(composed, scope, ranges)
+			policy, _ := composed.collectionPolicies.at(items)
+			if len(policy.recordOrder) != 5 {
+				t.Fatalf("record policies = %d, want 5 positions", len(policy.recordOrder))
+			}
+			for index := range 5 {
+				record, _ := policy.recordPolicyAt(index)
+				_, found := record.scope.at(Keys("steps"))
+				if found != (index == 2 || index == 4) {
+					t.Errorf("local policy at item %d = %t", index, found)
+				}
+			}
+		})
+	}
+}
+
+func TestItemPolicyProjectionDetachesRepeatedScopes(t *testing.T) {
+	t.Parallel()
+	local := collectionPolicyScope{}
+	local.set(Keys("steps"), collectionPolicy{identityFields: []string{"id"}, identityPresent: true})
+	scope := acquisitionScope{}
+	ranges := make(map[sequenceRangeKey]sequenceRange)
+	for index, destination := range []string{"items", "other", "items"} {
+		path := Keys(destination)
+		scope.contributions = append(scope.contributions, acquiredContribution{
+			document: parseItemPolicyDocument(t, "item", destination+": [{}]\n"), destination: path,
+			nested: &composedDocument{collectionPolicies: local},
+		})
+		output := 0
+		if index == 2 {
+			output = 1
+		}
+		ranges[sequenceRangeKey{sourceIndex: index, path: path.String()}] = sequenceRange{start: output, end: output + 1}
+	}
+	first, second := &composedDocument{}, &composedDocument{}
+	projectNestedCollectionPolicies(first, scope, ranges)
+	projectNestedCollectionPolicies(second, scope, ranges)
+	policy := first.collectionPolicies.collections[Keys("items").String()].policy
+	if len(policy.recordOrder) != 2 || policy.recordOrder[0] == policy.recordOrder[1] {
+		t.Fatal("separately placed records did not retain distinct owners")
+	}
+	other := second.collectionPolicies.collections[Keys("items").String()].policy
+	if policy.recordOrder[0] == other.recordOrder[0] {
+		t.Fatal("independent projections reused a record owner")
+	}
+	// Mutate stored state directly: a detached query result would conceal an
+	// accidental alias between incrementally constructed record scopes.
+	steps := Keys("steps").String()
+	firstRecord := policy.recordPolicies[policy.recordOrder[0]]
+	firstRecord.collections[steps].policy.identityFields[0] = "changed"
+	for _, check := range []struct {
+		composed *composedDocument
+		path     Path
+		index    int
+	}{
+		{first, Keys("items"), 1}, {first, Keys("other"), 0},
+		{second, Keys("items"), 0}, {second, Keys("items"), 1}, {second, Keys("other"), 0},
+	} {
+		outer, _ := check.composed.collectionPolicies.at(check.path)
+		record, found := outer.recordPolicyAt(check.index)
+		identity, present := record.scope.at(Keys("steps"))
+		if !found || !present || !reflect.DeepEqual(identity.identityFields, []string{"id"}) {
+			t.Fatalf("mutation leaked into %s item %d: %#v", check.path, check.index, identity)
+		}
+	}
+	if local.collections[steps].policy.identityFields[0] != "id" {
+		t.Fatal("projected state mutated the incoming scope")
+	}
+	local.collections[steps].policy.identityFields[0] = "source-changed"
+	if other.recordPolicies[other.recordOrder[0]].collections[steps].policy.identityFields[0] != "id" {
+		t.Fatal("incoming scope remained aliased to projected state")
+	}
+}
+
+func TestOverlaySequenceTransfersIncomingItemPolicyOwnership(t *testing.T) {
+	path := Keys("records")
+	registered := mustCompileSequenceIdentityPolicy(t, []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("records")}, identityFields: []string{"id"}}})
+	makePolicies := func(childKey string) collectionPolicyScope {
+		local := collectionPolicyScope{}
+		local.set(Keys("steps"), collectionPolicy{
+			identityFields: []string{childKey}, identityPresent: true,
+			explicitMode: sequenceModeAppend, explicitModePresent: true,
+		})
+		record := newCollectionRecordPolicy()
+		record.scope = local
+		outer := collectionPolicy{identityFields: []string{"id"}, identityPresent: true}
+		outer.setRecordPolicy(record)
+		scope := collectionPolicyScope{}
+		scope.set(path, outer)
+		return scope
+	}
+	checkPolicy := func(t *testing.T, scope collectionPolicyScope, index int, key string) {
+		t.Helper()
+		outer, ok := scope.at(path)
+		if !ok {
+			t.Fatal("outer collection policy missing")
+		}
+		record, ok := outer.recordPolicyAt(index)
+		if !ok {
+			t.Fatalf("record policy %d missing", index)
+		}
+		local, ok := record.scope.at(Keys("steps"))
+		if !ok || !local.identityPresent || !reflect.DeepEqual(local.identityFields, []string{key}) || !local.explicitModePresent || local.explicitMode != sequenceModeAppend {
+			t.Fatalf("record %d nested policy = %#v, %v; want key %q and append", index, local, ok, key)
+		}
+	}
+
+	tests := []struct {
+		name         string
+		lower        string
+		higher       string
+		declarations []sequenceDeclarationSpec
+		wantRecords  int
+	}{
+		{
+			name:        "upserting the same outer identity replaces its local policy",
+			lower:       "records: [{id: same, steps: [{id: old}]}]\n",
+			higher:      "records: [{id: same, steps: [{slug: new}]}]\n",
+			wantRecords: 1,
+		},
+		{
+			name:        "retained and appended outer records keep independent policies",
+			lower:       "records: [{id: lower, steps: [{id: old}]}]\n",
+			higher:      "records: [{id: higher, steps: [{slug: new}]}]\n",
+			wantRecords: 2,
+		},
+		{
+			name:   "whole sequence replacement transfers new local policy",
+			lower:  "records: [{id: same, steps: [{id: old}]}]\n",
+			higher: "records: [{id: same, steps: [{slug: new}]}]\n",
+			declarations: []sequenceDeclarationSpec{{
+				destination: path, mode: sequenceModeReplace, modePresent: true,
+			}},
+			wantRecords: 1,
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			lowerRoot := parseItemPolicyDocument(t, "lower", test.lower)
+			incomingRoot := parseItemPolicyDocument(t, "higher", test.higher)
+			assembly := newAssemblyAccumulator(&composedDocument{
+				root: lowerRoot, collectionPolicies: makePolicies("id"), origins: make(map[string]Origin),
+			})
+			if diagnostics := assembly.applyOverlayWithCollectionPolicy(
+				incomingRoot, nil, makePolicies("slug"), nil, LayerBase, registered, test.declarations,
+			); len(diagnostics) != 0 {
+				t.Fatalf("overlay diagnostics = %#v", diagnostics)
+			}
+			outer, ok := assembly.current.collectionPolicies.at(path)
+			if !ok || len(outer.recordOrder) != test.wantRecords {
+				t.Fatalf("outer record policies = %#v, %v", outer, ok)
+			}
+			if test.wantRecords == 2 {
+				checkPolicy(t, assembly.current.collectionPolicies, 0, "id")
+				checkPolicy(t, assembly.current.collectionPolicies, 1, "slug")
+			} else {
+				checkPolicy(t, assembly.current.collectionPolicies, 0, "slug")
+			}
+		})
+	}
+}
+
+func TestAncestorReplacementRequiresIdentityWhenRetainedModeReturns(t *testing.T) {
+	path := Keys("catalog", "prompts")
+	newAssembly := func(t *testing.T) *assemblyAccumulator {
+		t.Helper()
+		policy := collectionPolicy{
+			identityFields: []string{"id"}, identityPresent: true,
+			explicitMode: sequenceModeAppend, explicitModePresent: true,
+		}
+		scope := collectionPolicyScope{}
+		scope.set(path, policy)
+		return newAssemblyAccumulator(&composedDocument{
+			root:               parseItemPolicyDocument(t, "base", "catalog:\n  prompts: [{id: old}]\n"),
+			collectionPolicies: scope, origins: make(map[string]Origin),
+		})
+	}
+	removeAncestor := func(t *testing.T, assembly *assemblyAccumulator) {
+		t.Helper()
+		if diagnostics := assembly.applyOverlayWithCollectionPolicy(
+			parseItemPolicyDocument(t, "remove", "catalog: null\n"), nil, collectionPolicyScope{}, nil,
+			LayerBase, sequencePolicy{}, nil,
+		); len(diagnostics) != 0 {
+			t.Fatalf("ancestor removal diagnostics = %#v", diagnostics)
+		}
+	}
+
+	t.Run("retained append mode requires a renewed identity", func(t *testing.T) {
+		assembly := newAssembly(t)
+		removeAncestor(t, assembly)
+		policy, ok := assembly.current.collectionPolicies.at(path)
+		if !ok || policy.identityPresent || !policy.explicitModePresent || policy.explicitMode != sequenceModeAppend {
+			t.Fatalf("retired collection policy = %#v, %v", policy, ok)
+		}
+		diagnostics := assembly.applyOverlayWithCollectionPolicy(
+			parseItemPolicyDocument(t, "reintroduction", "catalog:\n  prompts: [{id: restored, name: restored}]\n"), nil,
+			collectionPolicyScope{}, nil, LayerBase, sequencePolicy{}, nil,
+		)
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid {
+			t.Fatalf("append without renewed identity diagnostics = %#v", diagnostics)
+		}
+	})
+
+	t.Run("a renewed key restores the retained append mode", func(t *testing.T) {
+		assembly := newAssembly(t)
+		removeAncestor(t, assembly)
+		declaration := sequenceDeclarationSpec{
+			destination: path, identityFields: []string{"name"}, identityPresent: true,
+		}
+		diagnostics := assembly.applyOverlayWithCollectionPolicy(
+			parseItemPolicyDocument(t, "keyed", "catalog:\n  prompts: [{name: next}]\n"), nil,
+			collectionPolicyScope{}, nil, LayerBase, sequencePolicy{}, []sequenceDeclarationSpec{declaration},
+		)
+		if len(diagnostics) != 0 {
+			t.Fatalf("renewed identity diagnostics = %#v", diagnostics)
+		}
+		policy, ok := assembly.current.collectionPolicies.at(path)
+		if !ok || !policy.identityPresent || !reflect.DeepEqual(policy.identityFields, []string{"name"}) || !policy.explicitModePresent || policy.explicitMode != sequenceModeAppend {
+			t.Fatalf("renewed collection policy = %#v, %v", policy, ok)
+		}
+	})
+}
+
+func TestItemSourceVersionProcessingConsumesDeclarationsBeforeComposition(t *testing.T) {
+	t.Parallel()
+
+	root := parseItemPolicyDocument(t, "item", `version: v1
+configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+prompts:
+  - id: example
+`)
+	rule := &VersionRule{Path: Keys("version"), Check: func(version Version, _ *Validation) error {
+		if !version.Present || version.Text != "v1" {
+			t.Errorf("version = %#v, want v1", version)
+		}
+		return nil
+	}}
+	processed := processSourceVersionWithDirectiveContext(
+		root, rule, sourceVersionContribution, Keys("items").Index(0), sourceVersionModeRequired, rootDirectiveContextSource,
+	)
+	if len(processed.diagnostics) != 0 {
+		t.Fatalf("process item source version: %#v", processed.diagnostics)
+	}
+	if len(processed.sequences) != 1 || !processed.sequences[0].identityPresent {
+		t.Fatalf("extracted item declarations = %#v", processed.sequences)
+	}
+	if _, ok := documentAtPath(processed.payload, Keys("version")); ok {
+		t.Fatalf("consumed version header remains in item payload: %#v", processed.payload)
+	}
+	if _, ok := documentAtPath(processed.payload, Keys("configkit")); ok {
+		t.Fatalf("consumed controls remain in item payload: %#v", processed.payload)
+	}
+}

internal/engine/load.go

@@ -17,7 +17,7 @@ type Definition[T any] struct {
 	Version  *VersionRule
 	Secret   func(Path) bool
 
-	sequenceRegistrations []sequenceRegistration
+	sequenceIdentityRegistrations []sequenceIdentityRegistration
 }
 
 // Options contains the application definition and per-load input selections.
@@ -35,6 +35,7 @@ type Options[T any] struct {
 	placementMode           placementMode
 	sequencePolicy          sequencePolicy
 	deferAssembly           bool
+	directiveContext        rootDirectiveContext
 	importDefaultsValidated bool
 }
 
@@ -92,6 +93,10 @@ type Inspection struct {
 	baseline         *document.Node
 	input            *document.Node
 	inputOrigins     map[string]Origin
+	structuralInput  *document.Node
+	preCLI           *document.Node
+	preCLIOrigins    map[string]Origin
+	postDecodeApps   []historyApplication
 	final            *document.Node
 	immutableLookup  *documentLookup
 	resolution       []resolutionSnapshot
@@ -145,13 +150,13 @@ func Load[T any](source Source, secrets SecretBinding, supplied ...Options[T]) (
 
 func loadWithSecretLookup[T any](source Source, secrets SecretBinding, lookup secretLookup, supplied ...Options[T]) (*Loaded[T], error) {
 	options, diagnostics := selectOptions(source, supplied)
-	policy, policyDiagnostics := compileSequencePolicy(options.Definition.sequenceRegistrations)
+	policy, policyDiagnostics := compileSequenceIdentityPolicy(options.Definition.sequenceIdentityRegistrations)
 	diagnostics = append(diagnostics, policyDiagnostics...)
 	if len(diagnostics) != 0 {
 		return nil, (&diagnosticAccumulator{diagnostics: diagnostics}).loadError()
 	}
 	definition := options.Definition
-	definition.sequenceRegistrations = nil
+	definition.sequenceIdentityRegistrations = nil
 	request := loadRequest[T]{
 		main:       loadInput{source: source, imports: options.Imports, filesystem: options.Filesystem, destination: options.destination.clone(), placementMode: options.placementMode},
 		definition: definition, importDefaults: snapshotImportDefaults(options.importDefaults), sequencePolicy: policy, overlay: options.Overlay,
@@ -168,11 +173,14 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 	mainOptions := Options[T]{Definition: request.definition, Imports: request.main.imports, Filesystem: request.main.filesystem, destination: request.main.destination.clone(), placementMode: request.main.placementMode}
 	mainOptions.importDefaults = snapshotImportDefaults(request.importDefaults)
 	mainOptions.sequencePolicy = request.sequencePolicy
+	mainOptions.deferAssembly = true
 	mainOptions.SourceVersionMode = request.sourceVersionMode
 	mainOptions.Definition.Version = request.protectionVersion()
-	mainOptions.Overrides = request.overrides
 	if request.ordinary {
 		mainOptions.Overlay = request.overlay
+		mainOptions.directiveContext = rootDirectiveContextSource
+	} else {
+		mainOptions.directiveContext = rootDirectiveContextLayered
 	}
 
 	var schema *schemaDescriptor
@@ -205,14 +213,7 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 			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.document != nil {
+	if request.ordinary && (input.document != nil || input.composition != nil) {
 		input.composition, diagnostics = compositionForInputWithPolicy(input, request.sequencePolicy)
 		if len(diagnostics) != 0 {
 			accumulator.add(diagnostics...)
@@ -220,7 +221,16 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 		}
 		input.document = input.composition.root
 	}
+	if request.sourceVersionMode == sourceVersionModeDefault && request.ordinary {
+		versionDiagnostics := checkVersion(request.definition.Version, input.document)
+		accumulator.add(versionDiagnostics...)
+		if hasErrors(versionDiagnostics) {
+			return nil, accumulator.loadError()
+		}
+	}
 	if request.ordinary {
+		versionState.locateMainVersion(input.document)
+		mainOptions.Definition.Version = versionState.effectiveRule
 		input, diagnostics = applyInputLayers(request.main.source, mainOptions, input)
 	} else {
 		input, diagnostics = assembleLayeredInput(request, input, accounting)
@@ -228,9 +238,10 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 	accumulator.add(versionState.diagnostics[reportedVersionDiagnostics:]...)
 	accumulator.sources = input.sources
 	accumulator.add(diagnostics...)
-	if len(diagnostics) != 0 {
+	if hasErrors(diagnostics) {
 		return nil, accumulator.loadError()
 	}
+	request.effectiveVersion = versionState.effectiveRule
 	if request.ordinary && input.parsed.source != nil {
 		baseSources := make([]SourceInfo, 0, len(input.sources))
 		for _, source := range input.sources {
@@ -253,20 +264,38 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 			accumulator.add(problems...)
 			return nil, accumulator.loadError()
 		}
-		expanded, problems := expandInheritanceWithOrigins(composition.root, composition.origins, defaultProjectionLimits())
+		expanded, problems := expandInheritanceWithCollectionRules(
+			composition.root, composition.origins, composition.collectionPolicies, request.sequencePolicy, defaultProjectionLimits(),
+		)
 		if len(problems) != 0 {
 			accumulator.add(problems...)
 			return nil, accumulator.loadError()
 		}
-		if problem := inheritanceVersionDiagnostic(request.protectionVersion(), expanded); problem != nil {
+		effectiveVersion, problem := projectInheritanceVersion(request.protectionVersion(), expanded)
+		if problem != nil {
 			accumulator.add(*problem)
 			return nil, accumulator.loadError()
 		}
+		request.effectiveVersion = effectiveVersion
+		versionState.effectiveRule = effectiveVersion
 		input.composition = composition
 		input.inheritance = expanded
 		input.document = expanded.root
 	}
 
+	base := overridePreparationInput{root: input.document}
+	if input.composition != nil {
+		base.inputBytes = input.composition.inputBytes
+		base.inputNodes = input.composition.inputNodes
+	}
+	preparedOverrides, diagnostics := preparePostStructuralOverrides(base, input.sources, request.overrides, request.protectionVersion(), defaultImportLimits())
+	accumulator.add(diagnostics...)
+	if hasErrors(diagnostics) {
+		return nil, accumulator.loadError()
+	}
+	input.sources = preparedOverrides.sources
+	accumulator.sources = input.sources
+
 	decodeDefinition := request.definition
 	decodeDefinition.Version = request.protectionVersion()
 	decoded, diagnostics := decodeLoadInput(schema, decodeDefinition, input)
@@ -274,12 +303,25 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 	if len(diagnostics) != 0 {
 		return nil, accumulator.loadError()
 	}
-	resolved, diagnostics := resolveLoadInput(schema, request.definition, input, decoded)
+	decodeContext := decodeContext{}
+	if decodeDefinition.Version != nil {
+		decodeContext.versionPath = &decodeDefinition.Version.Path
+	}
+	assigned, issues := applyDecodedOverrides(schema, decoded, preparedOverrides, decodeContext)
+	if len(issues) != 0 {
+		for _, issue := range issues {
+			accumulator.add(diagnosticFromDecodeIssue(issue))
+		}
+		return nil, accumulator.loadError()
+	}
+	postDecode := preparePostDecodeOverrideContext(input, decoded, assigned)
+	resolved, diagnostics := resolveLoadInput(schema, request.definition, input, postDecode)
 	accumulator.add(diagnostics...)
 	if hasErrors(diagnostics) {
 		return nil, accumulator.loadError()
 	}
-	if !historyNodesWithinLimit(decoded.baseline, decoded.final, resolved.final, resolved.applications, resolved.snapshots, input.inheritance) {
+	historyApplications := append(cloneHistoryApplications(resolved.applications), cloneHistoryApplications(resolved.postDecodeApps)...)
+	if !historyNodesWithinLimit(decoded.baseline, decoded.final, resolved.final, historyApplications, resolved.snapshots, input.inheritance) {
 		accumulator.add(Diagnostic{Code: CodeExplainLimitExceeded, Severity: SeverityError, Message: "retained configuration history exceeds the node limit"})
 		return nil, accumulator.loadError()
 	}
@@ -290,13 +332,18 @@ func executeLoadRequest[T any](request loadRequest[T], secrets SecretBinding, lo
 		accumulator.add(*ownershipIssue)
 		return nil, accumulator.loadError()
 	}
-	secretResolution := resolveSecretReferences(reflect.ValueOf(&configuration).Elem(), schema, input.document, lookup)
+	secretResolution := resolveSecretReferences(reflect.ValueOf(&configuration).Elem(), schema, resolved.referenceInput, lookup)
 	accumulator.add(secretResolution.diagnostics...)
 	if hasErrors(secretResolution.diagnostics) {
 		return nil, accumulator.loadError()
 	}
+	identityDiagnostics := validateFinalSequenceIdentities(resolved.referenceInput, request.sequencePolicy)
+	accumulator.add(identityDiagnostics...)
+	if hasErrors(identityDiagnostics) {
+		return nil, accumulator.loadError()
+	}
 	if request.definition.Validate != nil {
-		diagnostics = runValidation(&configuration, request.definition.Validate, schema, resolved.final, input.document, secretResolution.lookups)
+		diagnostics = runValidation(&configuration, request.definition.Validate, schema, resolved.final, resolved.referenceInput, secretResolution.lookups)
 		accumulator.add(diagnostics...)
 		if hasErrors(diagnostics) {
 			return nil, accumulator.loadError()

internal/engine/load_input.go

@@ -16,36 +16,42 @@ type assembledInput struct {
 	sources      []SourceInfo
 	contexts     map[string]ResourceContext
 	versionState *sourceVersionState
+	accounting   *importAccounting
 }
 
 // acquiredContribution keeps a source-local payload beside its placed document.
 // The latter is used for composition; the former preserves the acquisition
 // boundary for later scoped assembly and evidence.
 type acquiredContribution struct {
-	source              SourceInfo
-	identity            importNodeKey
-	role                importContributionRole
-	scopeOwner          importNodeKey
-	payload             *document.Node
-	document            *document.Node
-	destination         Path
-	relativeDestination Path
-	processing          *sourceVersionProcessingResult
-	nested              *composedDocument
-	pendingItem         *acquisitionScope
-	placementCharged    bool
+	source               SourceInfo
+	identity             importNodeKey
+	role                 importContributionRole
+	scopeOwner           importNodeKey
+	payload              *document.Node
+	document             *document.Node
+	destination          Path
+	relativeDestination  Path
+	processing           *sourceVersionProcessingResult
+	sequenceDeclarations []sequenceDeclarationSpec
+	nested               *composedDocument
+	pendingItem          *acquisitionScope
+	placementCharged     bool
 }
 
 // acquisitionScope is the ordered strict mapping scope produced by one input
 // and its ordinary imports.
 type acquisitionScope struct {
-	owner         importNodeKey
-	destination   Path
-	contributions []acquiredContribution
+	owner              importNodeKey
+	destination        Path
+	contributions      []acquiredContribution
+	collectionPolicies collectionPolicyScope
 }
 
 func cloneAcquisitionScope(scope acquisitionScope) acquisitionScope {
-	cloned := acquisitionScope{owner: scope.owner, destination: scope.destination.clone()}
+	cloned := acquisitionScope{
+		owner: scope.owner, destination: scope.destination.clone(),
+		collectionPolicies: cloneCollectionPolicyScope(scope.collectionPolicies),
+	}
 	if scope.contributions != nil {
 		cloned.contributions = make([]acquiredContribution, len(scope.contributions))
 		for index, contribution := range scope.contributions {
@@ -54,7 +60,8 @@ func cloneAcquisitionScope(scope acquisitionScope) acquisitionScope {
 				role: contribution.role, scopeOwner: contribution.scopeOwner, payload: contribution.payload,
 				document: contribution.document, destination: contribution.destination.clone(),
 				relativeDestination: contribution.relativeDestination.clone(), processing: contribution.processing,
-				nested: cloneComposedDocument(contribution.nested), pendingItem: cloneAcquisitionScopePointer(contribution.pendingItem),
+				sequenceDeclarations: cloneSequenceDeclarations(contribution.sequenceDeclarations),
+				nested:               cloneComposedDocument(contribution.nested), pendingItem: cloneAcquisitionScopePointer(contribution.pendingItem),
 				placementCharged: contribution.placementCharged,
 			}
 		}
@@ -102,7 +109,7 @@ func assembleBaseInputTrackedForRole[T any](source Source, options Options[T], d
 		parsed.source.Destination = destination.clone()
 		parsed.source.placementMode = options.placementMode
 	}
-	input := assembledInput{parsed: parsed, document: parsed.document, sources: sourceInfos(parsed.source), versionState: versionState}
+	input := assembledInput{parsed: parsed, document: parsed.document, sources: sourceInfos(parsed.source), versionState: versionState, accounting: accounting}
 	if len(diagnostics) != 0 {
 		input.sources = sourceInfos(parsed.source)
 		// Mapping value issues already identify application content. Other early
@@ -116,13 +123,70 @@ func assembleBaseInputTrackedForRole[T any](source Source, options Options[T], d
 		}
 		return input, diagnostics
 	}
+	directiveContext := options.directiveContext
+	if directiveContext == 0 {
+		directiveContext = rootDirectiveContextImportsOnly
+	}
 	if !options.Imports && parsed.document != nil {
-		if diagnostics := disabledDirectiveDiagnostics(parsed.document, Path{}); len(diagnostics) != 0 {
-			return input, diagnostics
+		var directiveDiagnostics []Diagnostic
+		if directiveContext == rootDirectiveContextSource || directiveContext == rootDirectiveContextLayered {
+			directiveDiagnostics = disabledRootImportDiagnostics(parsed.document)
+		} else {
+			directiveDiagnostics = disabledDirectiveDiagnostics(parsed.document, Path{})
+		}
+		if len(directiveDiagnostics) != 0 {
+			return input, directiveDiagnostics
 		}
 	}
 	var versionProcessing *sourceVersionProcessingResult
-	if versionState != nil && versionState.mode != sourceVersionModeDefault {
+	if directiveContext == rootDirectiveContextSource {
+		var sourceID string
+		if parsed.source != nil {
+			sourceID = parsed.source.ID
+		}
+		var processed sourceVersionProcessingResult
+		var failures []Diagnostic
+		if versionState != nil {
+			processed, failures = versionState.processWithDirectiveContext(parsed.document, role, destination, sourceID, options.placementMode, directiveContext)
+		} else {
+			processed = processSourceVersionWithDirectiveContext(parsed.document, options.Definition.Version, role, destination, sourceVersionModeDefault, directiveContext)
+			failures = processed.diagnostics
+		}
+		if len(failures) != 0 {
+			return input, failures
+		}
+		versionProcessing = &processed
+		if role == sourceVersionMain && versionState != nil {
+			versionState.mainProcessing = &processed
+		}
+	} else if directiveContext == rootDirectiveContextLayered {
+		extracted, failures := extractRootDirectives(parsed.document, rootDirectiveContextLayered)
+		if len(failures) != 0 {
+			return input, failures
+		}
+		processed := sourceVersionProcessingResult{
+			payload: extracted.body, imports: extracted.imports, sequences: extracted.sequences,
+			directiveContext: rootDirectiveContextLayered,
+		}
+		if versionState != nil && versionState.mode != sourceVersionModeDefault {
+			var sourceID string
+			if parsed.source != nil {
+				sourceID = parsed.source.ID
+			}
+			versionProcessed, versionFailures := versionState.process(extracted.body, role, destination, sourceID, options.placementMode)
+			if len(versionFailures) != 0 {
+				return input, versionFailures
+			}
+			versionProcessed.imports = extracted.imports
+			versionProcessed.sequences = append(cloneSequenceDeclarations(extracted.sequences), versionProcessed.sequences...)
+			versionProcessed.directiveContext = rootDirectiveContextLayered
+			processed = versionProcessed
+			if role == sourceVersionMain {
+				versionState.mainProcessing = &processed
+			}
+		}
+		versionProcessing = &processed
+	} else if versionState != nil && versionState.mode != sourceVersionModeDefault {
 		var sourceID string
 		if parsed.source != nil {
 			sourceID = parsed.source.ID
@@ -168,6 +232,10 @@ func assembleBaseInputTrackedForRole[T any](source Source, options Options[T], d
 		localPayload := input.document
 		input.document = placed
 		identity := importKeyForMainSource(parsed.source)
+		var sequenceDeclarations []sequenceDeclarationSpec
+		if versionProcessing != nil {
+			sequenceDeclarations = cloneSequenceDeclarations(versionProcessing.sequences)
+		}
 		input.acquisition = []acquisitionScope{{
 			owner:       identity,
 			destination: destination.clone(),
@@ -175,6 +243,7 @@ func assembleBaseInputTrackedForRole[T any](source Source, options Options[T], d
 				source: cloneSourceInfo(*parsed.source), payload: localPayload,
 				identity: identity, role: importRoleMain, scopeOwner: identity,
 				document: placed, destination: destination.clone(), processing: versionProcessing,
+				sequenceDeclarations: sequenceDeclarations,
 			}},
 		}}
 		rawNodes := countInputNodes(parsed.document)
@@ -218,7 +287,7 @@ func registerAcquiredSource(source Source, context *FilesystemContext, info *Sou
 }
 
 func applyInputLayers[T any](source Source, options Options[T], input assembledInput) (assembledInput, []Diagnostic) {
-	if !activeOverlay(options.Overlay) && len(options.Overrides) == 0 {
+	if !activeOverlay(options.Overlay) {
 		return input, nil
 	}
 	composition, diagnostics := compositionForInputWithPolicy(input, options.sequencePolicy)
@@ -229,7 +298,7 @@ func applyInputLayers[T any](source Source, options Options[T], input assembledI
 	if activeOverlay(options.Overlay) {
 		input.sources, diagnostics = loadSelectedOverlayIntoWithVersion(
 			source, options.Filesystem, input.parsed, assembly, input.sources,
-			options.Overlay, options.Definition.Version, defaultImportLimits(), input.versionState,
+			options.Overlay, options.Definition.Version, defaultImportLimits(), input.versionState, options.sequencePolicy,
 		)
 		if len(diagnostics) != 0 {
 			return input, diagnostics
@@ -240,33 +309,44 @@ func applyInputLayers[T any](source Source, options Options[T], input assembledI
 		}
 		mergeResourceContexts(&input.contexts, contexts)
 	}
-	if len(options.Overrides) != 0 {
-		input.sources, diagnostics = assembly.applyOverrides(
-			input.sources, options.Overrides, options.Definition.Version, defaultImportLimits(),
-		)
-		if len(diagnostics) != 0 {
-			return input, diagnostics
-		}
-	}
 	input.composition = assembly.current
 	input.document = assembly.current.root
 	return input, nil
 }
 
-// compositionForInput initializes one handoff for overlays and CLI, including
-// defaults-only CLI input. Raw source bytes and mapping keys retain their budgets.
+// compositionForInput initializes the structural handoff used by inheritance
+// expansion. Raw source bytes and mapping keys retain their budgets.
 func compositionForInput(input assembledInput) (*composedDocument, []Diagnostic) {
 	return compositionForInputWithPolicy(input, sequencePolicy{})
 }
 
 func compositionForInputWithPolicy(input assembledInput, policy sequencePolicy) (*composedDocument, []Diagnostic) {
+	return compositionForInputWithPolicies(input, collectionPolicyScope{}, policy)
+}
+
+func compositionForInputWithPolicies(input assembledInput, lower collectionPolicyScope, policy sequencePolicy) (*composedDocument, []Diagnostic) {
 	if input.composition != nil {
+		if input.composition.root == nil && len(input.composition.acquisition) != 0 {
+			return composeAcquiredInputWithPolicies(input, lower, policy)
+		}
 		return input.composition, nil
 	}
+	if len(input.acquisition) != 0 {
+		acquired := &composedDocument{acquisition: cloneAcquisitionScopes(input.acquisition)}
+		if input.accounting != nil {
+			acquired.inputBytes = input.accounting.bytes
+			acquired.inputNodes = input.accounting.nodes
+		} else {
+			acquired.inputBytes = input.parsed.bytes
+			acquired.inputNodes = countInputNodes(input.parsed.document)
+		}
+		input.composition = acquired
+		return composeAcquiredInputWithPolicies(input, lower, policy)
+	}
 	if input.document == nil {
 		return &composedDocument{root: &document.Node{Kind: document.Mapping}, origins: make(map[string]Origin)}, nil
 	}
-	composition, diagnostics := composeDocumentsWithPolicy(policy, input.document)
+	composition, diagnostics := composeDocumentsWithCollectionPolicy(policy, lower, nil, input.document)
 	if len(diagnostics) != 0 {
 		return nil, diagnostics
 	}

internal/engine/load_request.go

@@ -37,15 +37,25 @@ type loadInput struct {
 
 type loadGroup struct{ inputs []loadInput }
 
+type acquiredUnderlayGroup struct {
+	index       int
+	scopes      []acquisitionScope
+	importGraph importInclusionGraph
+	sources     []SourceInfo
+	contexts    map[string]ResourceContext
+	inputBytes  int64
+	inputNodes  int
+}
+
 func loadGroupedWithSecretLookup[T any](request loadRequest[T], secrets SecretBinding, lookup secretLookup) (*Loaded[T], error) {
 	request.ordinary = false
 	var diagnostics []Diagnostic
 	request.importDefaults = snapshotImportDefaults(request.importDefaults)
 	diagnostics = append(diagnostics, validateImportDefaults(request.importDefaults)...)
-	policy, policyDiagnostics := compileSequencePolicy(request.definition.sequenceRegistrations)
+	policy, policyDiagnostics := compileSequenceIdentityPolicy(request.definition.sequenceIdentityRegistrations)
 	request.sequencePolicy = policy
 	diagnostics = append(diagnostics, policyDiagnostics...)
-	request.definition.sequenceRegistrations = nil
+	request.definition.sequenceIdentityRegistrations = nil
 	mainOptions, mainDiagnostics := selectOptions(request.main.source, []Options[T]{{
 		Definition: request.definition, Imports: request.main.imports, Filesystem: request.main.filesystem, destination: request.main.destination.clone(),
 		SourceVersionMode: request.sourceVersionMode, placementMode: request.main.placementMode,
@@ -82,46 +92,114 @@ 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))
+	var assembly *assemblyAccumulator
+	mainSourceCount := len(input.sources)
+	mainEvidence := input.versionState.evidenceSince(0)
+	projectVersion := sequenceVersionPath(request.protectionVersion())
 	for index, group := range request.underlays {
-		composition, sources, contexts, diagnostics := acquireUnderlayGroupWithPolicyVersion(group, index+1, request.protectionVersion(), accounting, input.versionState, request.sequencePolicy)
-		input.sources = append(input.sources, sources...)
-		mergeResourceContexts(&input.contexts, contexts)
+		evidenceStart := len(input.versionState.evidenceSince(0))
+		acquired, diagnostics := acquireUnderlayGroupScopes(group, index+1, request.protectionVersion(), accounting, input.versionState, request.sequencePolicy)
+		mergeResourceContexts(&input.contexts, acquired.contexts)
+		if len(diagnostics) != 0 {
+			input.sources = append(input.sources, acquired.sources...)
+			return input, diagnostics
+		}
+		var lower collectionPolicyScope
+		if assembly != nil && assembly.current != nil {
+			lower = assembly.current.collectionPolicies
+		}
+		protectionRule := request.protectionVersion()
+		if projectVersion {
+			// The main item's final position is known only after tier assembly.
+			// Source-local checks still run during acquisition above.
+			protectionRule = nil
+		}
+		composition, diagnostics := composeUnderlayGroup(acquired, protectionRule, request.sequencePolicy, lower)
+		sourceStart := len(input.sources)
+		input.sources = append(input.sources, acquired.sources...)
 		if len(diagnostics) != 0 {
 			return input, diagnostics
 		}
 		if composition != nil {
-			groups = append(groups, composition)
+			if assembly == nil {
+				assembly = newAssemblyAccumulator(composition)
+			} else {
+				var declarations []sequenceDeclarationSpec
+				for _, scope := range composition.acquisition {
+					declarations = append(declarations, acquiredSequenceDeclarations(scope)...)
+				}
+				operations, diagnostics := assembly.applyOverlayWithCollectionProjection(
+					composition.root, composition.origins, composition.collectionPolicies, composition.applications, LayerUnderlay,
+					request.sequencePolicy, declarations,
+				)
+				if len(diagnostics) != 0 {
+					return input, diagnostics
+				}
+				projectTierSourceDestinations(input.sources[sourceStart:], input.versionState.evidenceSince(evidenceStart), operations)
+			}
 		}
 	}
 
-	var assembly *assemblyAccumulator
-	for _, group := range groups {
-		if assembly == nil {
-			assembly = newAssemblyAccumulator(group)
-			continue
+	mainPresent := input.document != nil || input.composition != nil || len(input.acquisition) != 0
+	var mainComposition *composedDocument
+	if mainPresent {
+		var lower collectionPolicyScope
+		if assembly != nil && assembly.current != nil {
+			lower = assembly.current.collectionPolicies
 		}
-		if diagnostics := assembly.applyOverlay(group.root, group.origins, group.applications, LayerUnderlay); len(diagnostics) != 0 {
-			return input, diagnostics
-		}
-	}
-	if input.document != nil {
-		mainComposition, diagnostics := compositionForInputWithPolicy(input, request.sequencePolicy)
+		var diagnostics []Diagnostic
+		mainComposition, diagnostics = compositionForInputWithPolicies(input, lower, request.sequencePolicy)
 		if len(diagnostics) != 0 {
 			return input, diagnostics
 		}
-		if assembly == nil {
-			assembly = newAssemblyAccumulator(mainComposition)
-		} else if diagnostics := assembly.applyOverlay(mainComposition.root, mainComposition.origins, mainComposition.applications, LayerBase); len(diagnostics) != 0 {
-			return input, diagnostics
+	}
+	var versionDiagnostics []Diagnostic
+	if request.sourceVersionMode == sourceVersionModeDefault {
+		var mainRoot *document.Node
+		if mainComposition != nil {
+			mainRoot = mainComposition.root
+		} else if input.document != nil {
+			mainRoot = input.document
+		}
+		versionDiagnostics = checkVersion(request.definition.Version, mainRoot)
+		if hasErrors(versionDiagnostics) {
+			return input, versionDiagnostics
 		}
 	}
-	if assembly == nil && (activeOverlay(request.overlay) || len(request.overrides) != 0) {
+	if mainComposition != nil {
+		input.versionState.locateMainVersion(mainComposition.root)
+		if assembly == nil {
+			assembly = newAssemblyAccumulator(mainComposition)
+		} else {
+			var declarations []sequenceDeclarationSpec
+			for _, scope := range mainComposition.acquisition {
+				declarations = append(declarations, acquiredSequenceDeclarations(scope)...)
+			}
+			operations, diagnostics := assembly.applyOverlayWithCollectionProjection(
+				mainComposition.root, mainComposition.origins, mainComposition.collectionPolicies, mainComposition.applications, LayerBase,
+				request.sequencePolicy, declarations,
+			)
+			if len(diagnostics) != 0 {
+				return input, append(versionDiagnostics, diagnostics...)
+			}
+			projectTierSourceDestinations(input.sources[:mainSourceCount], mainEvidence, operations)
+			input.versionState.projectMainVersion(operations)
+		}
+	}
+	if input.versionState != nil {
+		request.effectiveVersion = input.versionState.effectiveRule
+	}
+	if projectVersion && assembly != nil {
+		if diagnostic := projectedUnderlayVersionDiagnostic(assembly.current.applications, input.sources, request.protectionVersion()); diagnostic != nil {
+			return input, append(versionDiagnostics, *diagnostic)
+		}
+	}
+	if assembly == nil && activeOverlay(request.overlay) {
 		composition, _ := compositionForInput(assembledInput{})
 		assembly = newAssemblyAccumulator(composition)
 	}
 	if assembly == nil {
-		return input, nil
+		return input, versionDiagnostics
 	}
 	assembly.current.inputBytes = accounting.bytes
 	assembly.current.inputNodes = accounting.nodes
@@ -131,37 +209,23 @@ 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 = loadSelectedOverlayIntoWithVersion(selection, request.overlayFilesystem, selected, assembly, input.sources, request.overlay, request.protectionVersion(), defaultImportLimits(), input.versionState)
+		overlayPolicy := []sequencePolicy{request.sequencePolicy}
+		input.sources, diagnostics = loadSelectedOverlayIntoWithVersion(selection, request.overlayFilesystem, selected, assembly, input.sources, request.overlay, request.protectionVersion(), defaultImportLimits(), input.versionState, overlayPolicy...)
 		if len(diagnostics) != 0 {
-			return input, diagnostics
+			return input, append(versionDiagnostics, diagnostics...)
 		}
 		contexts, diagnostic := contextsForAcquiredSources(selection, request.overlayFilesystem, selected.source, input.sources[len(input.sources)-1:])
 		if diagnostic != nil {
-			return input, []Diagnostic{*diagnostic}
+			return input, append(versionDiagnostics, *diagnostic)
 		}
 		mergeResourceContexts(&input.contexts, contexts)
 	}
-	if len(request.overrides) != 0 {
-		var diagnostics []Diagnostic
-		input.sources, diagnostics = assembly.applyOverrides(input.sources, request.overrides, request.protectionVersion(), defaultImportLimits())
-		if len(diagnostics) != 0 {
-			return input, diagnostics
-		}
-	}
 	input.composition = assembly.current
 	input.document = assembly.current.root
-	return input, nil
+	return input, versionDiagnostics
 }
 
-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) {
-	return acquireUnderlayGroupWithPolicyVersion(group, index, rule, accounting, versionState, sequencePolicy{})
-}
-
-func acquireUnderlayGroupWithPolicyVersion(group loadGroup, index int, rule *VersionRule, accounting *importAccounting, versionState *sourceVersionState, policy sequencePolicy) (*composedDocument, []SourceInfo, map[string]ResourceContext, []Diagnostic) {
+func acquireUnderlayGroupScopes(group loadGroup, index int, rule *VersionRule, accounting *importAccounting, versionState *sourceVersionState, policy sequencePolicy) (*acquiredUnderlayGroup, []Diagnostic) {
 	initialBytes, initialNodes := accounting.bytes, accounting.nodes
 	visited := make(map[resourceIdentity]importRoute)
 	hostToken := &namespaceToken{}
@@ -173,15 +237,14 @@ func acquireUnderlayGroupWithPolicyVersion(group loadGroup, index int, rule *Ver
 			}
 		}
 	}
-	var scopes []acquisitionScope
+	acquiredGroup := &acquiredUnderlayGroup{index: index}
 	inclusionGraph := newImportInclusionGraph()
-	var sources []SourceInfo
-	var contexts map[string]ResourceContext
 	for inputIndex, contribution := range group.inputs {
 		options := Options[struct{}]{
 			Imports: contribution.imports, Filesystem: contribution.filesystem,
 			Definition: Definition[struct{}]{Version: rule}, destination: contribution.destination.clone(),
 			placementMode: contribution.placementMode, sequencePolicy: policy, deferAssembly: true,
+			directiveContext: rootDirectiveContextLayered,
 			importDefaults: func() importDefaults {
 				if versionState == nil {
 					return importDefaults{}
@@ -193,11 +256,11 @@ func acquireUnderlayGroupWithPolicyVersion(group loadGroup, index int, rule *Ver
 		for _, source := range acquired.sources {
 			source.Layer = LayerUnderlay
 			source.UnderlayIndex = index
-			sources = append(sources, source)
+			acquiredGroup.sources = append(acquiredGroup.sources, source)
 		}
-		mergeResourceContexts(&contexts, acquired.contexts)
+		mergeResourceContexts(&acquiredGroup.contexts, acquired.contexts)
 		if len(diagnostics) != 0 {
-			return nil, sources, contexts, projectPriorInputDiagnosticPaths(diagnostics, scopes)
+			return acquiredGroup, projectPriorInputDiagnosticPaths(diagnostics, acquiredGroup.scopes)
 		}
 		if acquired.document == nil && len(acquired.acquisition) == 0 {
 			continue
@@ -219,59 +282,66 @@ func acquireUnderlayGroupWithPolicyVersion(group loadGroup, index int, rule *Ver
 		for scopeIndex := range inputScopes {
 			reanchorAcquisitionScope(&inputScopes[scopeIndex], keyMap, anchors)
 		}
-		scopes = append(scopes, inputScopes...)
+		acquiredGroup.scopes = append(acquiredGroup.scopes, inputScopes...)
 		mergeImportInclusionGraph(&inclusionGraph, inputGraph)
 	}
-	groupScope := scheduleAcquisitionGroup(scopes, inclusionGraph)
-	traversal := importTraversal{accounting: accounting, limits: defaultImportLimits(), rule: rule, importGraph: inclusionGraph}
-	if diagnostics := traversal.composePendingItems(&groupScope); len(diagnostics) != 0 {
-		return nil, sources, contexts, diagnostics
+	acquiredGroup.importGraph = inclusionGraph.clone()
+	acquiredGroup.inputBytes = accounting.bytes - initialBytes
+	acquiredGroup.inputNodes = accounting.nodes - initialNodes
+	return acquiredGroup, nil
+}
+
+func composeUnderlayGroup(acquired *acquiredUnderlayGroup, rule *VersionRule, policy sequencePolicy, lower collectionPolicyScope) (*composedDocument, []Diagnostic) {
+	if acquired == nil {
+		return nil, nil
+	}
+	groupScope := scheduleAcquisitionGroup(acquired.scopes, acquired.importGraph)
+	if len(groupScope.contributions) == 0 {
+		return nil, nil
+	}
+	groupScope.owner = importNodeKey{namespaceKind: "group", namespaceAnchor: explicitNamespaceAnchor(acquired.index, 0), resourceKind: "scope"}
+	for contributionIndex := range groupScope.contributions {
+		groupScope.contributions[contributionIndex].scopeOwner = groupScope.owner
+	}
+	accounting := &importAccounting{
+		sources: len(acquired.sources), bytes: acquired.inputBytes, nodes: acquired.inputNodes,
+	}
+	composition, diagnostics := composeAcquiredScopeWithPolicy(
+		&groupScope, lower, policy, acquired.importGraph, acquired.sources, nil, nil, accounting,
+	)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
 	}
 	var documents []*document.Node
 	for _, contribution := range groupScope.contributions {
 		documents = append(documents, contribution.document)
 	}
-	if len(documents) == 0 {
-		return nil, sources, contexts, nil
-	}
-	composition, diagnostics := composeDocumentsWithPolicy(policy, documents...)
-	if len(diagnostics) != 0 {
-		return nil, sources, contexts, diagnostics
-	}
 	if composition != nil && rule != nil {
 		ranges := indexSequenceRanges(composition.sequenceRanges)
-		for sourceIndex, document := range documents {
+		for sourceIndex, input := range documents {
 			if groupScope.contributions[sourceIndex].role == importRoleMain {
 				continue
 			}
-			if node := fragmentVersionClaimWithIndex(document, rule, sourceIndex, ranges); node != nil {
+			if node := fragmentVersionClaimWithIndex(input, rule, sourceIndex, ranges); node != nil {
 				location := publicLocation(node.Location)
-				return nil, sources, contexts, []Diagnostic{{
+				return nil, []Diagnostic{{
 					Code: CodeImportVersion, Severity: SeverityError, Path: rule.Path.clone(),
 					Message: "imported fragments cannot contribute to the schema-version path", Primary: &location,
 				}}
 			}
 		}
-		for sourceIndex, document := range documents {
-			if node := fragmentVersionClaimWithIndex(document, rule, sourceIndex, ranges); node != nil {
+		for sourceIndex, input := range documents {
+			if node := fragmentVersionClaimWithIndex(input, rule, sourceIndex, ranges); node != nil {
 				location := publicLocation(node.Location)
-				return nil, sources, contexts, []Diagnostic{{
+				return nil, []Diagnostic{{
 					Code: CodeUnderlayVersion, Severity: SeverityError, Path: rule.Path.clone(),
 					Message: "underlay inputs cannot contribute to the schema-version path", Primary: &location,
 				}}
 			}
 		}
 	}
-	composition.inputBytes = accounting.bytes - initialBytes
-	composition.inputNodes = accounting.nodes - initialNodes
-	groupScope.owner = importNodeKey{namespaceKind: "group", namespaceAnchor: explicitNamespaceAnchor(index, 0), resourceKind: "scope"}
-	for contributionIndex := range groupScope.contributions {
-		groupScope.contributions[contributionIndex].scopeOwner = groupScope.owner
-	}
-	composition.acquisition = []acquisitionScope{cloneAcquisitionScope(groupScope)}
-	composition.importGraph = inclusionGraph.clone()
-	projectNestedEvidence(composition, groupScope)
-	projectAcquiredDestinations(composition, groupScope, sources)
+	composition.inputBytes = acquired.inputBytes
+	composition.inputNodes = acquired.inputNodes
 	for pointer, origin := range composition.origins {
 		origin.Layer = LayerUnderlay
 		composition.origins[pointer] = origin
@@ -279,7 +349,7 @@ func acquireUnderlayGroupWithPolicyVersion(group loadGroup, index int, rule *Ver
 	for index := range composition.applications {
 		composition.applications[index].layer = LayerUnderlay
 	}
-	return composition, sources, contexts, nil
+	return composition, nil
 }
 
 func nativeTokenForLoadInput(input loadInput) *namespaceToken {

internal/engine/load_request_test.go

@@ -46,7 +46,7 @@ items: [{id: b}]
 			{source: File(zRoot), imports: true},
 			{source: File(bRoot), imports: true},
 		}}},
-		definition: Definition[map[string]any]{sequenceRegistrations: []sequenceRegistration{{path: Keys("items"), identityField: "id"}}},
+		definition: Definition[map[string]any]{sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}},
 	}
 	result, err := testGroupedLoad(request)
 	if err != nil {
@@ -73,6 +73,50 @@ items: [{id: b}]
 	}
 }
 
+func TestUnderlayGroupAcquisitionRetainsScopesUntilComposition(t *testing.T) {
+	filesystem := NewFilesystem("handoff", fstest.MapFS{
+		"main.yml":  &fstest.MapFile{Data: []byte("configkit: {imports: [{path: child.yml}]}\nmain: retained\n")},
+		"child.yml": &fstest.MapFile{Data: []byte("child: retained\n")},
+	})
+	accounting := &importAccounting{}
+	group := loadGroup{inputs: []loadInput{{source: filesystem.File("main.yml"), imports: true}}}
+	acquired, diagnostics := acquireUnderlayGroupScopes(group, 2, nil, accounting, nil, sequencePolicy{})
+	if len(diagnostics) != 0 {
+		t.Fatalf("acquire underlay group: %#v", diagnostics)
+	}
+	if acquired == nil || acquired.index != 2 || len(acquired.scopes) != 1 || len(acquired.scopes[0].contributions) != 2 {
+		t.Fatalf("acquisition handoff lost its source scope: %#v", acquired)
+	}
+	if len(acquired.sources) != 2 || acquired.sources[0].UnderlayIndex != 2 || acquired.sources[1].ID != "source-2" {
+		t.Fatalf("acquired source evidence = %#v", acquired.sources)
+	}
+	if acquired.inputBytes != int64(len("configkit: {imports: [{path: child.yml}]}\nmain: retained\n")+len("child: retained\n")) {
+		t.Fatalf("group input byte accounting = %d", acquired.inputBytes)
+	}
+
+	composition, diagnostics := composeUnderlayGroup(acquired, nil, sequencePolicy{}, collectionPolicyScope{})
+	if len(diagnostics) != 0 {
+		t.Fatalf("compose acquired group: %#v", diagnostics)
+	}
+	for key, want := range map[string]string{"main": "retained", "child": "retained"} {
+		value, present := documentAtPath(composition.root, Keys(key))
+		if !present || value.Text != want {
+			t.Errorf("composed %s = %#v, %v; want %q", key, value, present, want)
+		}
+	}
+	if composition.inputBytes != acquired.inputBytes || len(composition.acquisition) != 1 || len(composition.acquisition[0].contributions) != 2 {
+		t.Fatalf("composed group handoff = %#v", composition)
+	}
+
+	empty, diagnostics := acquireUnderlayGroupScopes(loadGroup{}, 3, nil, accounting, nil, sequencePolicy{})
+	if len(diagnostics) != 0 || len(empty.scopes) != 0 {
+		t.Fatalf("empty group acquisition = %#v, %#v", empty, diagnostics)
+	}
+	if composition, diagnostics := composeUnderlayGroup(empty, nil, sequencePolicy{}, collectionPolicyScope{}); len(diagnostics) != 0 || composition != nil {
+		t.Fatalf("empty group composition = %#v, %#v", composition, diagnostics)
+	}
+}
+
 func TestUnderlayNamespaceAnchorsUseInputPositionsAndFilesystemIdentity(t *testing.T) {
 	firstNamespace := NewFilesystem("same-label", fstest.MapFS{
 		"root.yml":  &fstest.MapFile{Data: []byte("items: [{id: first}]\n")},
@@ -88,7 +132,7 @@ func TestUnderlayNamespaceAnchorsUseInputPositionsAndFilesystemIdentity(t *testi
 			{source: secondNamespace.File("root.yml")},
 			{source: firstNamespace.File("later.yml")},
 		}}},
-		definition: Definition[map[string]any]{sequenceRegistrations: []sequenceRegistration{{path: Keys("items"), identityField: "id"}}},
+		definition: Definition[map[string]any]{sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}},
 	}
 	result, err := testGroupedLoad(request)
 	if err != nil {
@@ -119,7 +163,7 @@ func TestUnderlayItemConflictUsesScheduledGroupIndex(t *testing.T) {
 			{source: File(zItem), destination: Keys("items"), placementMode: placementModeSequenceItem},
 			{source: File(aItem), destination: Keys("items"), placementMode: placementModeSequenceItem},
 		}}},
-		definition: Definition[map[string]any]{sequenceRegistrations: []sequenceRegistration{{path: Keys("items"), identityField: "id"}}},
+		definition: Definition[map[string]any]{sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}},
 	}
 	_, err := testGroupedLoad(request)
 	loadError, ok := err.(*LoadError)
@@ -163,7 +207,7 @@ func TestUnderlayItemHelperConflictUsesScheduledGroupIndex(t *testing.T) {
 			{source: File(zBad), imports: true, destination: Keys("items"), placementMode: placementModeSequenceItem},
 			{source: File(aGood), destination: Keys("items"), placementMode: placementModeSequenceItem},
 		}}},
-		definition: Definition[map[string]any]{sequenceRegistrations: []sequenceRegistration{{path: Keys("items"), identityField: "id"}}},
+		definition: Definition[map[string]any]{sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}},
 	}
 	_, err := testGroupedLoad(request)
 	loadError, ok := err.(*LoadError)
@@ -311,6 +355,69 @@ func TestGroupedLoadAbsentMainAndVersionProtection(t *testing.T) {
 	}
 }
 
+func TestLayeredCollectionPolicyFlowsBetweenTiers(t *testing.T) {
+	t.Parallel()
+
+	policyOnly := Bytes("lower-policy", []byte("configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: append\n"))
+	duplicate := func(name string) loadInput {
+		return loadInput{source: Bytes(name, []byte("items: [{id: repeated}]\n"))}
+	}
+	request := loadRequest[map[string]any]{
+		main: loadInput{source: NoSource()},
+		underlays: []loadGroup{
+			{inputs: []loadInput{{source: policyOnly}}},
+			{inputs: []loadInput{duplicate("first-peer"), duplicate("second-peer")}},
+		},
+	}
+	if _, err := testGroupedLoad(request); err != nil && groupedErrorCode(t, err) != CodeComposeConflict {
+		loadErr, _ := err.(*LoadError)
+		t.Fatalf("higher strict group code = %s, want %s: %#v", groupedErrorCode(t, err), CodeComposeConflict, loadErr.Diagnostics())
+	} else if err == nil {
+		t.Fatal("higher strict group accepted duplicate inherited identities")
+	}
+
+	request = loadRequest[map[string]any]{
+		main: loadInput{source: NoSource()},
+		underlays: []loadGroup{
+			{inputs: []loadInput{{source: Bytes("lower", []byte("configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: append\nitems: [{id: repeated}]\n"))}}},
+			{inputs: []loadInput{duplicate("higher")}},
+		},
+	}
+	if _, err := testGroupedLoad(request); err == nil || groupedErrorCode(t, err) != CodeSequenceConflict {
+		t.Fatalf("higher tier did not inherit explicit append mode: %v", err)
+	}
+
+	request = loadRequest[map[string]any]{
+		main:      loadInput{source: Bytes("main", []byte("configkit:\n  sequences:\n    - destination: [items]\n      key: name\n      mode: replace\nitems: [{name: higher}]\n"))},
+		underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte("configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: append\nitems: [{id: lower}]\n"))}}}},
+	}
+	result, err := testGroupedLoad(request)
+	if err != nil || !reflect.DeepEqual(result.Config["items"], []any{map[string]any{"name": "higher"}}) {
+		var diagnostics []Diagnostic
+		if loadErr, ok := err.(*LoadError); ok {
+			diagnostics = loadErr.Diagnostics()
+		}
+		t.Fatalf("replacement did not retire lower identity: %#v, %v (%#v)", result, err, diagnostics)
+	}
+
+	filesystem := NewFilesystem("overlay", fstest.MapFS{
+		"overlays/testing.yml": &fstest.MapFile{Data: []byte("configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: append\nitems: [{id: overlay}]\n")},
+	})
+	definition := Definition[map[string]any]{sequenceIdentityRegistrations: []sequenceIdentityRegistration{{selector: sequenceIdentitySelector{literalSequenceSelector("items")}, identityFields: []string{"id"}}}}
+	request = loadRequest[map[string]any]{
+		main:       loadInput{source: Bytes("main", []byte("items: [{id: main}]\n"))},
+		underlays:  []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte("items: [{id: lower}]\n"))}}}},
+		definition: definition, sequencePolicy: mustCompileSequenceIdentityPolicy(t, definition.sequenceIdentityRegistrations),
+		overlay: "testing", overlayFilesystem: &FilesystemContext{Root: ".", BaseDir: ".", FS: &filesystem},
+	}
+	result, err = testGroupedLoad(request)
+	if err != nil || !reflect.DeepEqual(result.Config["items"], []any{
+		map[string]any{"id": "lower"}, map[string]any{"id": "main"}, map[string]any{"id": "overlay"},
+	}) {
+		t.Fatalf("layered selected overlay sequence policy = %#v, %v", result, err)
+	}
+}
+
 func TestGroupedLoadStrictConflictsRepetitionAndBudgets(t *testing.T) {
 	main := loadInput{source: Bytes("main", []byte("port: 5\n"))}
 	request := loadRequest[groupedConfig]{
@@ -349,18 +456,27 @@ func TestGroupedLoadStrictConflictsRepetitionAndBudgets(t *testing.T) {
 
 	accounting := &importAccounting{sources: maxImportSources - 1}
 	group := loadGroup{inputs: []loadInput{{source: Mapping("first", map[string]any{})}, {source: Mapping("second", map[string]any{})}}}
-	_, _, _, diagnostics := acquireUnderlayGroup(group, 1, nil, accounting)
+	_, _, _, diagnostics := testAcquireUnderlayGroup(group, 1, nil, accounting)
 	if len(diagnostics) == 0 || diagnostics[0].Code != CodeSourceLimitExceeded {
 		t.Fatalf("shared source budget = %#v", diagnostics)
 	}
 	accounting = &importAccounting{bytes: maxTotalBytes - 2}
 	group.inputs = []loadInput{{source: Mapping("first", map[string]any{"port": "one"})}}
-	_, _, _, diagnostics = acquireUnderlayGroup(group, 1, nil, accounting)
+	_, _, _, diagnostics = testAcquireUnderlayGroup(group, 1, nil, accounting)
 	if len(diagnostics) == 0 || diagnostics[0].Code != CodeSourceLimitExceeded {
 		t.Fatalf("shared byte budget = %#v", diagnostics)
 	}
 }
 
+func testAcquireUnderlayGroup(group loadGroup, index int, rule *VersionRule, accounting *importAccounting) (*composedDocument, []SourceInfo, map[string]ResourceContext, []Diagnostic) {
+	acquired, diagnostics := acquireUnderlayGroupScopes(group, index, rule, accounting, nil, sequencePolicy{})
+	if len(diagnostics) != 0 {
+		return nil, acquired.sources, acquired.contexts, diagnostics
+	}
+	composition, diagnostics := composeUnderlayGroup(acquired, rule, sequencePolicy{}, collectionPolicyScope{})
+	return composition, acquired.sources, acquired.contexts, diagnostics
+}
+
 func TestGroupedLoadInvalidIntermediateTypeCanBeReplaced(t *testing.T) {
 	request := loadRequest[groupedConfig]{
 		main:      loadInput{source: Bytes("main", []byte("port: 9\n"))},
@@ -402,11 +518,11 @@ func TestGroupedAccountingChargesMixedOccurrencesOnce(t *testing.T) {
 		"child-two.yml": &fstest.MapFile{Data: []byte(child)},
 	})
 	accounting := &importAccounting{}
-	first, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{source: filesystem.File("one.yml"), imports: true}}}, 1, nil, accounting)
+	first, sources, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{{source: filesystem.File("one.yml"), imports: true}}}, 1, nil, accounting)
 	if len(diagnostics) != 0 || first == nil || len(sources) != 2 || accounting.sources != 2 || accounting.bytes != int64(len(one)+len(child)) {
 		t.Fatalf("first acquisition = %#v, %#v, %#v, accounting %#v", first, sources, diagnostics, accounting)
 	}
-	second, sources, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{source: filesystem.File("two.yml"), imports: true}}}, 2, nil, accounting)
+	second, sources, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{{source: filesystem.File("two.yml"), imports: true}}}, 2, nil, accounting)
 	if len(diagnostics) != 0 || second == nil || len(sources) != 2 || sources[0].ID != "source-3" || sources[1].ID != "source-4" || accounting.sources != 4 || accounting.bytes != int64(len(one)+len(two)+2*len(child)) {
 		t.Fatalf("second acquisition = %#v, %#v, %#v, accounting %#v", second, sources, diagnostics, accounting)
 	}
@@ -433,7 +549,7 @@ func TestGroupedGlobEntryBudgetIsShared(t *testing.T) {
 		"parts/b.yml": &fstest.MapFile{Data: []byte("right: two\n")},
 	})
 	accounting := &importAccounting{entries: maxGlobEntries - 1}
-	_, _, _, diagnostics := acquireUnderlayGroup(loadGroup{inputs: []loadInput{{source: filesystem.File("main.yml"), imports: true}}}, 1, nil, accounting)
+	_, _, _, diagnostics := testAcquireUnderlayGroup(loadGroup{inputs: []loadInput{{source: filesystem.File("main.yml"), imports: true}}}, 1, nil, accounting)
 	if len(diagnostics) == 0 || diagnostics[0].Code != CodeImportLimitExceeded || accounting.entries <= maxGlobEntries {
 		t.Fatalf("shared glob budget = %#v, accounting %#v", diagnostics, accounting)
 	}

internal/engine/load_result.go

@@ -15,6 +15,11 @@ type resolvedLoad[T any] struct {
 	final           *document.Node
 	snapshots       []resolutionSnapshot
 	applications    []historyApplication
+	postDecodeApps  []historyApplication
+	structuralInput *document.Node
+	preCLI          *document.Node
+	preCLIOrigins   map[string]Origin
+	referenceInput  *document.Node
 	versionEvidence []*sourceVersionEvidence
 	inheritance     *inheritanceScope
 	contexts        map[string]ResourceContext
@@ -46,24 +51,16 @@ func decodeLoadInput[T any](schema *schemaDescriptor, definition Definition[T],
 	return decoded, nil
 }
 
-func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T], input assembledInput, decoded decodedConfiguration) (resolvedLoad[T], []Diagnostic) {
+func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T], input assembledInput, prepared postDecodeOverrideContext) (resolvedLoad[T], []Diagnostic) {
 	var diagnostics []Diagnostic
+	decoded := prepared.decoded
 	configuration := decoded.value.Interface().(T)
-	metadata := metadataFromDecoded(decoded)
-	if input.inheritance != nil {
-		applyInheritanceMetadata(&metadata, input.composition.root, input.composition.origins, input.composition.overlays, input.inheritance)
-	} else if input.composition != nil {
-		applyOverlayMetadata(&metadata, input.composition.overlays)
-	}
+	metadata := prepared.metadata
 	final := decoded.final
+	referenceInput := prepared.referenceInput
 	var resolutionSnapshots []resolutionSnapshot
 	if definition.Resolve != nil {
-		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)
+		resolved := runResolution(&configuration, definition.Resolve, schema, decoded, referenceInput, prepared.resolution)
 		diagnostics = append(diagnostics, resolved.diagnostics...)
 		if hasErrors(resolved.diagnostics) {
 			return resolvedLoad[T]{}, diagnostics
@@ -71,6 +68,7 @@ func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T],
 		final = resolved.final
 		resolutionSnapshots = resolved.snapshots
 		applyResolutionMetadata(&metadata, resolved)
+		referenceInput = documentWithMetadataLocations(final, metadata, input.document)
 	}
 	applications := []historyApplication(nil)
 	if input.composition != nil {
@@ -82,7 +80,13 @@ func resolveLoadInput[T any](schema *schemaDescriptor, definition Definition[T],
 	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
+	return resolvedLoad[T]{
+		configuration: configuration, decoded: decoded, metadata: metadata, final: final,
+		snapshots: resolutionSnapshots, applications: applications,
+		postDecodeApps: cloneHistoryApplications(prepared.postDecodeApps), structuralInput: document.Clone(prepared.structuralInput),
+		preCLI: document.Clone(prepared.preCLI), preCLIOrigins: cloneOrigins(prepared.preCLIOrigins), referenceInput: referenceInput,
+		versionEvidence: versionEvidence, inheritance: input.inheritance, contexts: input.contexts,
+	}, diagnostics
 }
 
 func detachLoadConfiguration[T any](schema *schemaDescriptor, configuration T, mode secretCloneMode) (T, *Diagnostic) {
@@ -105,12 +109,15 @@ 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 := classifySecretPathsWithEvidence(schema, definition.Secret, metadata, final, applications, resolved.versionEvidence, decoded.baseline, decoded.final)
+	structuralInput := document.Clone(resolved.structuralInput)
+	preCLI := document.Clone(resolved.preCLI)
+	allApplications := append(cloneHistoryApplications(applications), cloneHistoryApplications(resolved.postDecodeApps)...)
+	finalizeMetadataPaths(&metadata, final, allApplications, decoded.baseline, resolved.structuralInput, resolved.preCLI, decoded.final)
+	secrets := classifySecretPathsWithEvidence(schema, definition.Secret, metadata, final, allApplications, resolved.versionEvidence, decoded.baseline, resolved.structuralInput, resolved.preCLI, 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 {
+	retainedTrees := make([]*document.Node, 0, len(allApplications)+5)
+	retainedTrees = append(retainedTrees, decoded.final, final, structuralInput, preCLI)
+	for _, application := range allApplications {
 		retainedTrees = append(retainedTrees, application.value)
 	}
 	inspection := &Inspection{
@@ -121,6 +128,10 @@ func publishLoadResult[T any](schema *schemaDescriptor, definition Definition[T]
 		baseline:         decoded.baseline,
 		input:            decoded.final,
 		inputOrigins:     cloneOriginIndex(decoded.origins),
+		structuralInput:  structuralInput,
+		preCLI:           preCLI,
+		preCLIOrigins:    cloneOrigins(resolved.preCLIOrigins),
+		postDecodeApps:   cloneHistoryApplications(resolved.postDecodeApps),
 		final:            final,
 		immutableLookup:  buildDocumentLookup(retainedTrees...),
 		resolution:       resolutionSnapshots,

internal/engine/ordinary_sequence_test.go

@@ -0,0 +1,210 @@
+package engine
+
+import (
+	"errors"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+type ordinarySequenceItem struct {
+	ID string `yaml:"id"`
+}
+
+type ordinarySequenceRecord struct {
+	ID       string                 `yaml:"id"`
+	Children []ordinarySequenceItem `yaml:"children"`
+}
+
+type ordinarySequenceConfig struct {
+	Items   []ordinarySequenceItem `yaml:"items"`
+	Catalog struct {
+		Items []ordinarySequenceItem `yaml:"items"`
+	} `yaml:"catalog"`
+	Records []ordinarySequenceRecord `yaml:"records"`
+}
+
+func TestOrdinaryLoadAcceptsDeclarationsWithoutImports(t *testing.T) {
+	result, err := testLoad[ordinarySequenceConfig](Bytes("catalog.yml", []byte(`configkit:
+  sequences:
+    - destination: [items]
+      key: id
+items:
+  - id: prompt
+`)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(result.Config.Items, []ordinarySequenceItem{{ID: "prompt"}}) {
+		t.Fatalf("items = %#v", result.Config.Items)
+	}
+	if _, ok := result.Metadata().Lookup(Keys("configkit")); ok {
+		t.Fatal("collection controls reached application metadata")
+	}
+	items, ok := result.Metadata().Lookup(Keys("items"))
+	if !ok || !items.Explicit || len(items.Origin.Locations) != 1 {
+		t.Fatalf("items metadata = %#v, %v", items, ok)
+	}
+}
+
+func TestOrdinaryLoadKeepsDisabledImportRejection(t *testing.T) {
+	_, err := testLoad[ordinarySequenceConfig](Bytes("disabled.yml", []byte(`configkit:
+  imports: [{path: fragment.yml}]
+  sequences: [{destination: [items], key: id}]
+`)))
+	if err == nil {
+		t.Fatal("source with disabled imports succeeded")
+	}
+	var loadError *LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 || loadError.Diagnostics()[0].Code != CodeImportDisabled {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+func TestOrdinaryLoadValidatesSingletonCollectionIdentity(t *testing.T) {
+	_, err := testLoad[ordinarySequenceConfig](Bytes("missing-identity.yml", []byte(`configkit:
+  sequences:
+    - destination: [items]
+      key: id
+items: [{}]
+`)))
+	if err == nil {
+		t.Fatal("singleton sequence without identity succeeded")
+	}
+	var loadError *LoadError
+	if !errors.As(err, &loadError) || len(loadError.Diagnostics()) != 1 || loadError.Diagnostics()[0].Code != CodeComposeInvalid {
+		t.Fatalf("error = %#v", err)
+	}
+}
+
+func TestOrdinaryLoadCombinesImportedCollectionPeers(t *testing.T) {
+	tests := []struct {
+		name     string
+		second   string
+		want     []ordinarySequenceItem
+		wantCode Code
+	}{
+		{name: "distinct identities", second: "items: [{id: second}]\n", want: []ordinarySequenceItem{{ID: "first"}, {ID: "second"}}},
+		{name: "duplicate peer identity", second: "items: [{id: first}]\n", wantCode: CodeComposeConflict},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: first.yml
+    - path: second.yml
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+`)
+			writeImportFile(t, directory, "first.yml", "items: [{id: first}]\n")
+			writeImportFile(t, directory, "second.yml", test.second)
+
+			result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Imports: true})
+			if test.wantCode != "" {
+				if result != nil || err == nil {
+					t.Fatalf("result, err = %#v, %v", result, err)
+				}
+				var loadError *LoadError
+				if !errors.As(err, &loadError) || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != test.wantCode {
+					t.Fatalf("error = %#v", err)
+				}
+				return
+			}
+			if err != nil {
+				var loadError *LoadError
+				if errors.As(err, &loadError) {
+					t.Fatalf("diagnostics = %#v", loadError.Diagnostics())
+				}
+				t.Fatal(err)
+			}
+			if !reflect.DeepEqual(result.Config.Items, test.want) {
+				t.Fatalf("items = %#v, want %#v", result.Config.Items, test.want)
+			}
+			inline, err := testLoad[ordinarySequenceConfig](Bytes("inline.yml", []byte(`configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+items: [{id: first}, {id: second}]
+`)))
+			if err != nil {
+				t.Fatal(err)
+			}
+			if !reflect.DeepEqual(result.Config.Items, inline.Config.Items) {
+				t.Fatalf("imported items %#v differ from inline items %#v", result.Config.Items, inline.Config.Items)
+			}
+		})
+	}
+}
+
+func TestImportedCollectionDeclarationsUseRelativePlacement(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: first.yml
+      destination: [catalog]
+    - path: second.yml
+      destination: [catalog]
+`)
+	fragment := `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+items: [{id: ITEM}]
+`
+	writeImportFile(t, directory, "first.yml", strings.ReplaceAll(fragment, "ITEM", "first"))
+	writeImportFile(t, directory, "second.yml", strings.ReplaceAll(fragment, "ITEM", "second"))
+
+	result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Imports: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []ordinarySequenceItem{{ID: "first"}, {ID: "second"}}
+	if !reflect.DeepEqual(result.Config.Catalog.Items, want) {
+		t.Fatalf("catalog items = %#v, want %#v", result.Config.Catalog.Items, want)
+	}
+}
+
+func TestSequenceItemSourceAppliesItsCollectionDeclarations(t *testing.T) {
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  imports:
+    - path: item.yml
+      destination: [records]
+      placement: sequence-item
+`)
+	writeImportFile(t, directory, "item.yml", `configkit:
+  sequences:
+    - destination: [children]
+      key: id
+      mode: append
+id: parent
+children: [{id: child}]
+`)
+	result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Imports: true})
+	if err != nil {
+		t.Fatal(err)
+	}
+	want := []ordinarySequenceRecord{{ID: "parent", Children: []ordinarySequenceItem{{ID: "child"}}}}
+	if !reflect.DeepEqual(result.Config.Records, want) {
+		t.Fatalf("records = %#v, want %#v", result.Config.Records, want)
+	}
+}
+
+func TestOrdinaryLoadAllowsDeclarationsWithoutValues(t *testing.T) {
+	result, err := testLoad[ordinarySequenceConfig](Bytes("policy.yml", []byte(`configkit:
+  sequences:
+    - destination: [items]
+      key: id
+`)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if result.Config.Items != nil {
+		t.Fatalf("items = %#v, want absent", result.Config.Items)
+	}
+}

internal/engine/overlay.go

@@ -52,8 +52,211 @@ func (a *assemblyAccumulator) applyOverlay(overlay *document.Node, incomingOrigi
 	return nil
 }
 
+// applyOverlayWithCollectionPolicy is the shared recursive-precedence entry for
+// overlays. The caller supplies only the policy and declarations owned by this
+// contribution; layered loading can use the same operation when its lifecycle
+// reaches this boundary.
+func (a *assemblyAccumulator) applyOverlayWithCollectionPolicy(
+	overlay *document.Node,
+	incomingOrigins map[string]Origin,
+	incomingPolicies collectionPolicyScope,
+	applications []historyApplication,
+	layer Layer,
+	sequencePolicy sequencePolicy,
+	declarations []sequenceDeclarationSpec,
+) []Diagnostic {
+	_, diagnostics := a.applyOverlayWithCollectionProjection(overlay, incomingOrigins, incomingPolicies, applications, layer, sequencePolicy, declarations)
+	return diagnostics
+}
+
+// applyOverlayWithCollectionProjection also returns the incoming tier's item
+// assignments so acquisition evidence can follow the same operation as values.
+func (a *assemblyAccumulator) applyOverlayWithCollectionProjection(
+	overlay *document.Node,
+	incomingOrigins map[string]Origin,
+	incomingPolicies collectionPolicyScope,
+	applications []historyApplication,
+	layer Layer,
+	sequencePolicy sequencePolicy,
+	declarations []sequenceDeclarationSpec,
+) ([]sequenceHistoryContribution, []Diagnostic) {
+	if a == nil || a.current == nil || a.current.root == nil || a.current.root.Kind != document.Mapping || overlay == nil || overlay.Kind != document.Mapping {
+		return nil, invalidOverlayDocument()
+	}
+	mergeOriginContribution(a.current.origins, Path{}, incomingOrigin(incomingOrigins, Path{}, overlay, layer))
+	sequences, diagnostics := mergeOverlayMappingsWithCollectionPolicy(a, overlay, incomingOrigins, incomingPolicies, layer, sequencePolicy, declarations)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	if len(applications) == 0 {
+		application := historyApplication{layer: layer, value: overlay, sequences: sequences}
+		application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+		a.current.applications = append(a.current.applications, application)
+	} else {
+		for _, application := range projectTierHistoryApplications(applications, sequences) {
+			application.layer = layer
+			a.current.applications = append(a.current.applications, application)
+		}
+	}
+	return sequences, nil
+}
+
+func mergeOverlayMappingsWithCollectionPolicy(
+	assembly *assemblyAccumulator,
+	overlay *document.Node,
+	incomingOrigins map[string]Origin,
+	incomingPolicies collectionPolicyScope,
+	layer Layer,
+	sequencePolicy sequencePolicy,
+	declarations []sequenceDeclarationSpec,
+) ([]sequenceHistoryContribution, []Diagnostic) {
+	result := assembly.current
+	claims := compositionClaims{byPath: make(map[string][]compositionClaim)}
+	claims.append(overlay, Path{}, 0)
+	identityFieldsByPath, resolvedPolicies, diagnostics := resolveStrictCollectionPolicies(
+		claims.ordered, sequencePolicy, result.collectionPolicies, declarations,
+	)
+	if len(diagnostics) != 0 {
+		return nil, diagnostics
+	}
+	declarationsByPath := make(map[string][]sequenceDeclarationSpec, len(declarations))
+	registeredPaths := make(map[string]Path)
+	for _, declaration := range declarations {
+		key := declaration.destination.String()
+		declarationsByPath[key] = append(declarationsByPath[key], declaration)
+		registeredPaths[key] = declaration.destination.clone()
+	}
+	registered := make(map[string]bool)
+	for _, claim := range claims.ordered {
+		if claim.kind == document.Sequence {
+			if _, ok := sequencePolicy.identityFieldsAt(claim.path); ok {
+				registered[claim.path.String()] = true
+				registeredPaths[claim.path.String()] = claim.path.clone()
+			}
+		}
+	}
+	for key := range declarationsByPath {
+		registered[key] = true
+	}
+	for key := range result.collectionPolicies.collections {
+		if node, found := documentAtPath(overlay, result.collectionPolicies.collections[key].destination); found && node != nil {
+			registered[key] = true
+			registeredPaths[key] = result.collectionPolicies.collections[key].destination.clone()
+		}
+	}
+
+	resolutions := make(map[string]collectionPolicyResolution, len(registered))
+	for key := range registered {
+		path := registeredPaths[key]
+		policy, hasPolicy := resolvedPolicies.at(path)
+		if !hasPolicy {
+			continue
+		}
+		operation := sequenceModeReplace
+		if policy.explicitModePresent {
+			operation = policy.explicitMode
+		} else if len(identityFieldsByPath[key]) != 0 {
+			operation = sequenceModeUpsert
+		}
+		resolutions[key] = collectionPolicyResolution{
+			policy: policy, operation: operation,
+			effectiveIdentityFields: cloneStrings(identityFieldsByPath[key]),
+		}
+	}
+
+	sequenceApplications := make(map[string]sequenceHistoryContribution)
+	policyValues := make(map[string]bool)
+	var combinationDiagnostics []Diagnostic
+	mergeOverlayMappingsWithHooks(result.root, overlay, Path{}, &assembly.index,
+		recursiveMergeHooks{
+			added: func(path Path, incoming *document.Node) {
+				collectOverlayOriginsFrom(result.origins, incomingOrigins, incoming, path, layer)
+			},
+			combined: func(path Path, incoming *document.Node) {
+				mergeOriginContribution(result.origins, path, incomingOrigin(incomingOrigins, path, incoming, layer))
+			},
+			replaced: func(path Path, existing, incoming *document.Node) {
+				assembly.current.collectionPolicies.retireCollectionPoliciesAtOrBelow(path)
+				recordOverlayReplacement(result, path, existing, incoming, layer, true, incomingOrigins)
+			},
+			merge: func(path Path, existing, incoming *document.Node) (*document.Node, bool) {
+				resolution, active := resolutions[path.String()]
+				if !active {
+					return nil, false
+				}
+				combined, issues := combineSequence(existing, incoming, resolution, sequenceCombinationContext{destination: path})
+				if len(issues) != 0 {
+					combinationDiagnostics = append(combinationDiagnostics, issues...)
+					return existing, false
+				}
+				applyOverlaySequenceEvidence(result, path, existing, incoming, combined, resolution, incomingOrigins, incomingPolicies, layer)
+				policyValues[path.String()] = true
+				history := sequenceHistoryContribution{path: path.clone(), mode: sequenceHistoryMapped}
+				if resolution.operation == sequenceModeReplace {
+					history.mode = sequenceHistoryReplace
+					if incoming != nil && incoming.Kind == document.Sequence {
+						history.length = len(incoming.Sequence)
+					}
+				} else {
+					history.items = append([]sequenceItemProjection(nil), combined.higherItems...)
+					history.replacements = append([]sequenceItemReplacement(nil), combined.replacements...)
+				}
+				sequenceApplications[path.String()] = history
+				return combined.value, true
+			},
+		},
+	)
+	if len(combinationDiagnostics) != 0 {
+		return nil, canonicalDiagnostics(combinationDiagnostics)
+	}
+
+	for key, grouped := range declarationsByPath {
+		if policyValues[key] {
+			continue
+		}
+		path := grouped[0].destination
+		applicationIdentity, _ := sequencePolicy.identityFieldsAt(path)
+		current, diagnostics := resolveCollectionPolicy(path, grouped, applicationIdentity, nil)
+		if len(diagnostics) != 0 {
+			combinationDiagnostics = append(combinationDiagnostics, diagnostics...)
+			continue
+		}
+		lower, found := assembly.current.collectionPolicies.at(path)
+		var lowerPolicy *collectionPolicy
+		if found {
+			lowerPolicy = &lower
+		}
+		retained, _ := documentAtPath(assembly.current.root, path)
+		if retained != nil && retained.Kind == document.Sequence && len(current.effectiveIdentityFields) != 0 {
+			if _, issues := validateSequenceIdentity(retained, path, current.effectiveIdentityFields, sequenceIdentityDiagnosticCodes{invalid: CodeSequenceInvalid, conflict: CodeSequenceConflict}); len(issues) != 0 {
+				combinationDiagnostics = append(combinationDiagnostics, issues...)
+				continue
+			}
+		}
+		policy, issues := collectionPolicyWithoutValue(lowerPolicy, current.policy, retained, path)
+		if len(issues) != 0 {
+			combinationDiagnostics = append(combinationDiagnostics, issues...)
+			continue
+		}
+		assembly.current.collectionPolicies.set(path, policy)
+	}
+	if len(combinationDiagnostics) != 0 {
+		return nil, canonicalDiagnostics(combinationDiagnostics)
+	}
+	keys := make([]string, 0, len(sequenceApplications))
+	for key := range sequenceApplications {
+		keys = append(keys, key)
+	}
+	slices.Sort(keys)
+	sequences := make([]sequenceHistoryContribution, 0, len(keys))
+	for _, key := range keys {
+		sequences = append(sequences, sequenceApplications[key])
+	}
+	return sequences, nil
+}
+
 func mergeOverlayMappings(result *composedDocument, target, overlay *document.Node, current Path, layer Layer, recordReplacements bool, incomingOrigins map[string]Origin, index *mappingIndex) {
-	mergeRecursiveMappings(target, overlay, current, index, recursiveMergeHooks{
+	mergeOverlayMappingsWithHooks(target, overlay, current, index, recursiveMergeHooks{
 		added: func(path Path, incoming *document.Node) {
 			collectOverlayOriginsFrom(result.origins, incomingOrigins, incoming, path, layer)
 		},
@@ -78,22 +281,165 @@ func mergeOverlayMappings(result *composedDocument, target, overlay *document.No
 	})
 }
 
+func mergeOverlayMappingsWithHooks(
+	target, overlay *document.Node,
+	current Path,
+	index *mappingIndex,
+	hooks recursiveMergeHooks,
+) {
+	mergeRecursiveMappings(target, overlay, current, index, hooks)
+}
+
+func recordOverlayReplacement(
+	result *composedDocument,
+	path Path,
+	existing, incoming *document.Node,
+	layer Layer,
+	recordReplacement bool,
+	incomingOrigins map[string]Origin,
+) {
+	var displaced []displacedDefinition
+	var previous Origin
+	if existing != nil {
+		displaced = displacedOrigins(existing, result.origins, path)
+		previous = cloneOrigin(result.origins[path.String()])
+		deleteOriginSubtree(result.origins, path, existing)
+	}
+	collectOverlayOriginsFrom(result.origins, incomingOrigins, incoming, path, layer)
+	if recordReplacement && existing != nil {
+		result.overlays = append(result.overlays, overlayRecord{
+			change: Change{
+				Path: path.clone(), Origin: incomingOrigin(incomingOrigins, path, incoming, layer),
+				Previous: previousOrigins(previous),
+			},
+			displaced: displaced,
+		})
+	}
+}
+
+func applyOverlaySequenceEvidence(
+	result *composedDocument,
+	path Path,
+	lower, higher *document.Node,
+	combined sequenceCombinationResult,
+	resolution collectionPolicyResolution,
+	incomingOrigins map[string]Origin,
+	incomingPolicies collectionPolicyScope,
+	layer Layer,
+) {
+	lowerPolicy, hadLowerPolicy := result.collectionPolicies.at(path)
+	if resolution.operation == sequenceModeReplace {
+		var lowerValue *collectionPolicy
+		if hadLowerPolicy {
+			lowerValue = &lowerPolicy
+		}
+		result.collectionPolicies.retireCollectionPoliciesAtOrBelow(path)
+		resolution.policy = collectionPolicyForReplacement(lowerValue, resolution.policy)
+	}
+
+	if combined.value == nil || combined.value.Kind != document.Sequence {
+		recordOverlayReplacement(result, path, lower, higher, layer, true, incomingOrigins)
+		result.collectionPolicies.set(path, resolution.policy)
+		return
+	}
+
+	if resolution.operation == sequenceModeReplace {
+		var displaced []displacedDefinition
+		var previous Origin
+		if lower != nil {
+			displaced = displacedOrigins(lower, result.origins, path)
+			previous = cloneOrigin(result.origins[path.String()])
+			deleteOriginSubtree(result.origins, path, lower)
+		}
+		mergeOriginContribution(result.origins, path, incomingOrigin(incomingOrigins, path, higher, layer))
+		for _, projection := range combined.higherItems {
+			if higher != nil && higher.Kind == document.Sequence && projection.inputIndex >= 0 && projection.inputIndex < len(higher.Sequence) {
+				source := higher.Sequence[projection.inputIndex]
+				collectOverlayOriginsAt(result.origins, incomingOrigins, source, path.Index(projection.inputIndex), path.Index(projection.outputIndex), layer)
+			}
+		}
+		if lower != nil {
+			result.overlays = append(result.overlays, overlayRecord{
+				change: Change{
+					Path: path.clone(), Origin: incomingOrigin(incomingOrigins, path, higher, layer),
+					Previous: previousOrigins(previous),
+				}, displaced: displaced,
+			})
+		}
+	} else {
+		mergeOriginContribution(result.origins, path, incomingOrigin(incomingOrigins, path, higher, layer))
+		for _, replacement := range combined.replacements {
+			lowerPath := path.Index(replacement.lowerIndex)
+			higherPath := path.Index(replacement.higherIndex)
+			outputPath := path.Index(replacement.outputIndex)
+			if lower == nil || lower.Kind != document.Sequence || replacement.lowerIndex < 0 || replacement.lowerIndex >= len(lower.Sequence) ||
+				higher == nil || higher.Kind != document.Sequence || replacement.higherIndex < 0 || replacement.higherIndex >= len(higher.Sequence) {
+				continue
+			}
+			lowerItem := lower.Sequence[replacement.lowerIndex]
+			higherItem := higher.Sequence[replacement.higherIndex]
+			displaced := displacedOrigins(lowerItem, result.origins, lowerPath)
+			previous := cloneOrigin(result.origins[lowerPath.String()])
+			deleteOriginSubtree(result.origins, lowerPath, lowerItem)
+			collectOverlayOriginsAt(result.origins, incomingOrigins, higherItem, higherPath, outputPath, layer)
+			result.overlays = append(result.overlays, overlayRecord{
+				change: Change{
+					Path: outputPath.clone(), Origin: incomingOrigin(incomingOrigins, higherPath, higherItem, layer),
+					Previous: previousOrigins(previous),
+				},
+				displaced: displaced,
+			})
+		}
+		for _, projection := range combined.higherItems {
+			if higher != nil && higher.Kind == document.Sequence && projection.inputIndex >= 0 && projection.inputIndex < len(higher.Sequence) {
+				higherItem := higher.Sequence[projection.inputIndex]
+				collectOverlayOriginsAt(result.origins, incomingOrigins, higherItem, path.Index(projection.inputIndex), path.Index(projection.outputIndex), layer)
+			}
+		}
+	}
+
+	policy := cloneCollectionPolicy(resolution.policy)
+	policy.recordOrder = nil
+	policy.recordPolicies = nil
+	lowerProjection := newSequenceItemProjectionIndex(combined.lowerItems)
+	higherProjection := newSequenceItemProjectionIndex(combined.higherItems)
+	incomingCollection, hasIncomingCollection := incomingPolicies.at(path)
+	for outputIndex := range combined.value.Sequence {
+		if higherIndex, replaced := higherProjection.inputForOutput(outputIndex); replaced {
+			if record, found := incomingCollection.recordPolicyAt(higherIndex); hasIncomingCollection && found {
+				policy.setRecordPolicyAt(outputIndex, retainedCollectionRecordPolicy(record))
+			} else {
+				policy.setRecordPolicyAt(outputIndex, replacedCollectionRecordPolicy())
+			}
+			continue
+		}
+		if hadLowerPolicy && resolution.operation != sequenceModeReplace {
+			if lowerIndex, retained := lowerProjection.inputForOutput(outputIndex); retained {
+				if record, found := lowerPolicy.recordPolicyAt(lowerIndex); found {
+					policy.setRecordPolicyAt(outputIndex, retainedCollectionRecordPolicy(record))
+				}
+			}
+		} else {
+			policy.setRecordPolicyAt(outputIndex, replacedCollectionRecordPolicy())
+		}
+	}
+	result.collectionPolicies.set(path, policy)
+}
+
 func collectOverlayOrigins(origins map[string]Origin, node *document.Node, path Path, layer Layer) {
 	collectOverlayOriginsFrom(origins, nil, node, path, layer)
 }
 
 func collectOverlayOriginsFrom(origins, incomingOrigins map[string]Origin, node *document.Node, path Path, layer Layer) {
-	origins[path.String()] = incomingOrigin(incomingOrigins, path, node, layer)
-	switch node.Kind {
-	case document.Mapping:
-		for _, entry := range node.Mapping {
-			collectOverlayOriginsFrom(origins, incomingOrigins, entry.Value, path.Key(entry.Key), layer)
-		}
-	case document.Sequence:
-		for index, child := range node.Sequence {
-			collectOverlayOriginsFrom(origins, incomingOrigins, child, path.Index(index), layer)
-		}
-	}
+	collectOverlayOriginsAt(origins, incomingOrigins, node, path, path, layer)
+}
+
+func collectOverlayOriginsAt(origins, incomingOrigins map[string]Origin, node *document.Node, from, to Path, layer Layer) {
+	walkDocument(node, Path{}, func(relative Path, value *document.Node) {
+		source := appendDestination(from, relative)
+		destination := appendDestination(to, relative)
+		origins[destination.String()] = incomingOrigin(incomingOrigins, source, value, layer)
+	})
 }
 
 func mergeOverlayOrigin(origins map[string]Origin, path Path, location document.Location, layer Layer) {

internal/engine/override.go

@@ -19,9 +19,28 @@ type preparedOverride struct {
 	nodes  int
 }
 
-func prepareOverrides(base *composedDocument, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) ([]preparedOverride, []SourceInfo, []Diagnostic) {
+// preparedOverrideBatch owns all override values and synthetic source records
+// needed to apply one CLI batch after its preparation checks succeed.
+type preparedOverrideBatch struct {
+	overrides []preparedOverride
+	sources   []SourceInfo
+}
+
+type overridePreparationInput struct {
+	root       *document.Node
+	inputBytes int64
+	inputNodes int
+}
+
+// preparePostStructuralOverrides snapshots CLI input for typed assignment after
+// structural expansion, when inheritance directives can no longer be supplied.
+func preparePostStructuralOverrides(base overridePreparationInput, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) (preparedOverrideBatch, []Diagnostic) {
+	return prepareOverrideBatch(base, sources, overrides, rule, limits)
+}
+
+func prepareOverrideBatch(base overridePreparationInput, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) (preparedOverrideBatch, []Diagnostic) {
 	if len(overrides) > maxOverrides || len(sources)+len(overrides) > limits.sources {
-		return nil, cloneSourceInfos(sources), []Diagnostic{{
+		return preparedOverrideBatch{sources: cloneSourceInfos(sources)}, []Diagnostic{{
 			Code: CodeOverrideLimitExceeded, Severity: SeverityError,
 			Message: "configuration overrides exceed the record or source-count limit",
 		}}
@@ -37,7 +56,7 @@ func prepareOverrides(base *composedDocument, sources []SourceInfo, overrides []
 		}
 	}
 	if len(diagnostics) != 0 {
-		return nil, cloneSourceInfos(sources), canonicalDiagnostics(diagnostics)
+		return preparedOverrideBatch{sources: cloneSourceInfos(sources)}, canonicalDiagnostics(diagnostics)
 	}
 
 	prepared := make([]preparedOverride, len(overrides))
@@ -89,7 +108,7 @@ func prepareOverrides(base *composedDocument, sources []SourceInfo, overrides []
 			})
 			continue
 		}
-		if pathContainsDirective(override.Path) {
+		if pathContainsDirective(override.Path) || pathContainsInheritanceDirective(override.Path) {
 			diagnostics = append(diagnostics, Diagnostic{
 				Code: CodeOverrideDirective, Severity: SeverityError, Path: override.Path.clone(),
 				Message: "configuration overrides cannot create configuration directives", Primary: location,
@@ -106,7 +125,7 @@ func prepareOverrides(base *composedDocument, sources []SourceInfo, overrides []
 			diagnostics = append(diagnostics, diagnostic)
 			continue
 		}
-		if relative, ok := overrideDirectivePath(value, Path{}); ok {
+		if relative, ok := overrideStructuralDirectivePath(value, Path{}); ok {
 			diagnostics = append(diagnostics, Diagnostic{
 				Code: CodeOverrideDirective, Severity: SeverityError, Path: appendOverridePath(override.Path, relative),
 				Message: "configuration overrides cannot create configuration directives", Primary: location,
@@ -136,10 +155,10 @@ func prepareOverrides(base *composedDocument, sources []SourceInfo, overrides []
 		usedNodes += nodes
 	}
 	if len(diagnostics) != 0 {
-		return nil, allSources, canonicalDiagnostics(diagnostics)
+		return preparedOverrideBatch{sources: allSources}, canonicalDiagnostics(diagnostics)
 	}
 
-	return prepared, allSources, nil
+	return preparedOverrideBatch{overrides: prepared, sources: allSources}, nil
 }
 
 func validOverrideLabel(label string) bool {
@@ -191,26 +210,42 @@ func pathContainsDirective(path Path) bool {
 	return false
 }
 
+func pathContainsInheritanceDirective(path Path) bool {
+	for _, segment := range path.segments {
+		if segment.key == inheritanceKey {
+			return true
+		}
+	}
+	return false
+}
+
 func appendOverridePath(base, relative Path) Path {
 	result := base.clone()
 	result.segments = append(result.segments, clonePathSegments(relative.segments, 0)...)
 	return result
 }
 
-func overrideDirectivePath(node *document.Node, path Path) (Path, bool) {
+func overrideStructuralDirectivePath(node *document.Node, path Path) (Path, bool) {
+	return overrideStructuralDirectivePathAt(node, path)
+}
+
+func overrideStructuralDirectivePathAt(node *document.Node, path Path) (Path, bool) {
+	if node == nil {
+		return Path{}, false
+	}
 	if node.Kind == document.Mapping {
 		for _, entry := range node.Mapping {
 			child := path.Key(entry.Key)
-			if entry.Key == directiveKey {
+			if entry.Key == directiveKey || entry.Key == inheritanceKey {
 				return child, true
 			}
-			if found, ok := overrideDirectivePath(entry.Value, child); ok {
+			if found, ok := overrideStructuralDirectivePathAt(entry.Value, child); ok {
 				return found, true
 			}
 		}
 	} else if node.Kind == document.Sequence {
 		for index, child := range node.Sequence {
-			if found, ok := overrideDirectivePath(child, path.Index(index)); ok {
+			if found, ok := overrideStructuralDirectivePathAt(child, path.Index(index)); ok {
 				return found, true
 			}
 		}

internal/engine/override_apply.go

@@ -1,110 +0,0 @@
-package engine
-
-import (
-	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
-)
-
-func applyOverrides(base *composedDocument, sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) (*composedDocument, []SourceInfo, []Diagnostic) {
-	if len(overrides) == 0 {
-		return base, cloneSourceInfos(sources), nil
-	}
-	assembly := newAssemblyAccumulator(cloneComposedDocument(base))
-	allSources, diagnostics := assembly.applyOverrides(sources, overrides, rule, limits)
-	if len(diagnostics) != 0 {
-		return nil, allSources, diagnostics
-	}
-	return assembly.current, allSources, nil
-}
-
-func (a *assemblyAccumulator) applyOverrides(sources []SourceInfo, overrides []Override, rule *VersionRule, limits importLimits) ([]SourceInfo, []Diagnostic) {
-	if len(overrides) == 0 {
-		return cloneSourceInfos(sources), nil
-	}
-	prepared, allSources, diagnostics := prepareOverrides(a.current, sources, overrides, rule, limits)
-	if len(diagnostics) != 0 {
-		return allSources, diagnostics
-	}
-	for _, override := range prepared {
-		applyPreparedOverride(a.current, override, &a.index)
-		a.current.inputBytes += override.bytes
-		a.current.inputNodes += override.nodes
-	}
-	return allSources, nil
-}
-
-func applyPreparedOverride(result *composedDocument, override preparedOverride, index *mappingIndex) {
-	location := document.Location{SourceID: override.source.ID}
-	mergeOverlayOrigin(result.origins, Path{}, location, LayerCLI)
-	current := result.root
-	currentPath := Path{}
-	for segmentIndex, segment := range override.path.segments {
-		path := currentPath.Key(segment.key)
-		position := index.find(current, segment.key)
-		if segmentIndex < len(override.path.segments)-1 {
-			if position < 0 {
-				child := &document.Node{Kind: document.Mapping, Location: location, Mapping: []document.Entry{}}
-				index.append(current, document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: child})
-				collectOverlayOrigins(result.origins, child, path, LayerCLI)
-				current = child
-			} else {
-				current = current.Mapping[position].Value
-				mergeOverlayOrigin(result.origins, path, location, LayerCLI)
-			}
-			currentPath = path
-			continue
-		}
-
-		previous := cloneOrigin(result.origins[path.String()])
-		var displaced []displacedDefinition
-		if position < 0 {
-			incoming := document.Clone(override.value)
-			index.append(current, document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: incoming})
-			collectOverlayOrigins(result.origins, incoming, path, LayerCLI)
-		} else {
-			existing := current.Mapping[position].Value
-			displaced = affectedOverrideOrigins(existing, override.value, result.origins, path, index)
-			if existing.Kind == document.Mapping && override.value.Kind == document.Mapping {
-				mergeOverlayOrigin(result.origins, path, location, LayerCLI)
-				mergeOverlayMappings(result, existing, override.value, path, LayerCLI, false, nil, index)
-			} else {
-				deleteOriginSubtree(result.origins, path, existing)
-				current.Mapping[position] = document.Entry{Key: segment.key, KeyLocation: location, ValueLocation: location, Value: document.Clone(override.value)}
-				collectOverlayOrigins(result.origins, current.Mapping[position].Value, path, LayerCLI)
-			}
-		}
-		result.overlays = append(result.overlays, overlayRecord{change: Change{
-			Path: path.clone(), Origin: overlayOrigin(LayerCLI, location), Previous: previousOrigins(previous),
-		}, displaced: displaced})
-		result.applications = append(result.applications, historyApplication{
-			layer: LayerCLI, path: path.clone(), value: override.value,
-			origin: overlayOrigin(LayerCLI, location),
-		})
-	}
-}
-
-func affectedOverrideOrigins(existing, incoming *document.Node, origins map[string]Origin, path Path, index *mappingIndex) []displacedDefinition {
-	var displaced []displacedDefinition
-	collectAffectedOverrideOrigins(&displaced, existing, incoming, origins, path, index)
-	return sortDisplacedDefinitions(displaced)
-}
-
-func collectAffectedOverrideOrigins(displaced *[]displacedDefinition, existing, incoming *document.Node, origins map[string]Origin, path Path, index *mappingIndex) {
-	if existing.Kind != document.Mapping || incoming.Kind != document.Mapping {
-		collectDisplacedOrigins(displaced, existing, origins, path, Origin{})
-		return
-	}
-	*displaced = append(*displaced, displacedDefinition{path: path.clone(), origin: cloneOrigin(origins[path.String()])})
-	for _, entry := range incoming.Mapping {
-		position := index.find(existing, entry.Key)
-		if position < 0 {
-			continue
-		}
-		childPath := path.Key(entry.Key)
-		childExisting := existing.Mapping[position].Value
-		if childExisting.Kind == document.Mapping && entry.Value.Kind == document.Mapping {
-			collectAffectedOverrideOrigins(displaced, childExisting, entry.Value, origins, childPath, index)
-		} else {
-			collectDisplacedOrigins(displaced, childExisting, origins, childPath, Origin{})
-		}
-	}
-}

internal/engine/override_context.go

@@ -0,0 +1,239 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// postDecodeOverrideContext keeps the structural, typed pre-CLI, and effective
+// post-CLI views distinct while preparing the existing inspection machinery.
+type postDecodeOverrideContext struct {
+	structuralInput *document.Node
+	preCLI          *document.Node
+	preCLIOrigins   map[string]Origin
+	decoded         decodedConfiguration
+	metadata        Metadata
+	resolution      resolutionInput
+	sources         []SourceInfo
+	applications    []historyApplication
+	postDecodeApps  []historyApplication
+	referenceInput  *document.Node
+}
+
+func preparePostDecodeOverrideContext(input assembledInput, before decodedConfiguration, assigned decodedOverrideResult) postDecodeOverrideContext {
+	after := before
+	after.value = assigned.value
+	after.presence = cloneInputPresence(assigned.presence)
+	after.origins = cloneOrigins(assigned.origins)
+	after.final = document.Clone(assigned.final)
+
+	metadata := metadataFromDecoded(before)
+	cliRecords := overrideMetadataRecords(before, assigned.overrides)
+	var structuralOverlays []overlayRecord
+	if input.inheritance != nil && input.composition != nil {
+		structuralOverlays = input.composition.overlays
+		applyInheritanceMetadata(&metadata, input.composition.root, input.composition.origins, structuralOverlays, input.inheritance)
+	} else if input.composition != nil {
+		structuralOverlays = input.composition.overlays
+		applyOverlayMetadata(&metadata, structuralOverlays)
+	}
+	if len(cliRecords) != 0 {
+		metadata.fields = make(map[string]FieldInfo)
+		collectFieldInfo(after.final, Path{}, after, metadata.fields)
+		appendPostDecodeCLIHistory(&metadata, cliRecords)
+	}
+
+	sources := cloneSourceInfos(input.sources)
+	knownSources := make(map[string]bool, len(sources)+len(assigned.overrides))
+	for _, source := range sources {
+		knownSources[source.ID] = true
+	}
+	for _, override := range assigned.overrides {
+		if !knownSources[override.source.ID] {
+			sources = append(sources, cloneSourceInfo(override.source))
+			knownSources[override.source.ID] = true
+		}
+	}
+	if input.versionState != nil {
+		sources = sourceInfosWithVersionEvidence(sources, input.versionState.evidence, nil, true)
+	}
+	resolution := newResolutionInput(metadata, assigned.final, sources, input.contexts)
+
+	applications := structuralHistoryApplications(input)
+	var postDecodeApps []historyApplication
+	for _, override := range assigned.overrides {
+		postDecodeApps = append(postDecodeApps, historyApplication{
+			layer:  LayerCLI,
+			path:   override.path.clone(),
+			value:  document.Clone(override.value),
+			origin: overlayOrigin(LayerCLI, document.Location{SourceID: override.source.ID}),
+		})
+	}
+	allApplications := append(cloneHistoryApplications(applications), cloneHistoryApplications(postDecodeApps)...)
+	finalizeMetadataPaths(&metadata, assigned.final, allApplications, input.document, before.final)
+
+	return postDecodeOverrideContext{
+		structuralInput: document.Clone(input.document),
+		preCLI:          document.Clone(before.final),
+		preCLIOrigins:   cloneOrigins(before.origins),
+		decoded:         after,
+		metadata:        metadata,
+		resolution:      resolution,
+		sources:         sources,
+		applications:    applications,
+		postDecodeApps:  postDecodeApps,
+		referenceInput:  documentWithMetadataLocations(assigned.final, metadata, input.document),
+	}
+}
+
+// Source history is already assembled, with inheritance projected at query time.
+// Reuse overlay event construction for CLI changes without reapplying displaced
+// source definitions after those later assignments.
+func appendPostDecodeCLIHistory(metadata *Metadata, records []overlayRecord) {
+	cli := Metadata{fields: metadata.fields}
+	applyOverlayMetadata(&cli, records)
+	for pointer, history := range cli.history {
+		for _, change := range history {
+			if change.Origin.Layer == LayerCLI {
+				appendInputChangeEvent(metadata.history, nil, pointer, change)
+			}
+		}
+	}
+}
+
+func overrideMetadataRecords(before decodedConfiguration, overrides []preparedOverride) []overlayRecord {
+	if len(overrides) == 0 {
+		return nil
+	}
+	lookup := buildDocumentLookup(before.final)
+	records := make([]overlayRecord, 0, len(overrides))
+	for _, override := range overrides {
+		location := document.Location{SourceID: override.source.ID}
+		previous := cloneOrigin(before.origins[override.path.String()])
+		var displaced []displacedDefinition
+		if existing, ok := documentAtPathWithLookup(before.final, override.path, lookup); ok {
+			displaced = affectedOverrideOrigins(existing, override.value, before.origins, override.path, new(mappingIndex))
+		}
+		records = append(records, overlayRecord{change: Change{
+			Path: override.path.clone(), Origin: overlayOrigin(LayerCLI, location), Previous: previousOrigins(previous),
+		}, displaced: displaced})
+	}
+	return records
+}
+
+func affectedOverrideOrigins(existing, incoming *document.Node, origins map[string]Origin, path Path, index *mappingIndex) []displacedDefinition {
+	var displaced []displacedDefinition
+	collectAffectedOverrideOrigins(&displaced, existing, incoming, origins, path, index)
+	return sortDisplacedDefinitions(displaced)
+}
+
+func collectAffectedOverrideOrigins(displaced *[]displacedDefinition, existing, incoming *document.Node, origins map[string]Origin, path Path, index *mappingIndex) {
+	if existing.Kind != document.Mapping || incoming.Kind != document.Mapping {
+		collectDisplacedOrigins(displaced, existing, origins, path, Origin{})
+		return
+	}
+	*displaced = append(*displaced, displacedDefinition{path: path.clone(), origin: cloneOrigin(origins[path.String()])})
+	for _, entry := range incoming.Mapping {
+		position := index.find(existing, entry.Key)
+		if position < 0 {
+			continue
+		}
+		childPath := path.Key(entry.Key)
+		childExisting := existing.Mapping[position].Value
+		if childExisting.Kind == document.Mapping && entry.Value.Kind == document.Mapping {
+			collectAffectedOverrideOrigins(displaced, childExisting, entry.Value, origins, childPath, index)
+		} else {
+			collectDisplacedOrigins(displaced, childExisting, origins, childPath, Origin{})
+		}
+	}
+}
+
+func (context postDecodeOverrideContext) historyApplications() []historyApplication {
+	applications := cloneHistoryApplications(context.applications)
+	return append(applications, cloneHistoryApplications(context.postDecodeApps)...)
+}
+
+func structuralHistoryApplications(input assembledInput) []historyApplication {
+	if input.composition != nil {
+		return cloneHistoryApplications(input.composition.applications)
+	}
+	if input.document == nil {
+		return nil
+	}
+	return []historyApplication{{layer: LayerBase, value: document.Clone(input.document)}}
+}
+
+// documentWithMetadataLocations attaches effective origin coordinates to a
+// canonical typed projection for secret and validation diagnostics.
+func documentWithMetadataLocations(root *document.Node, metadata Metadata, fallback ...*document.Node) *document.Node {
+	located := document.Clone(root)
+	if located == nil {
+		return nil
+	}
+	var fallbackRoot *document.Node
+	if len(fallback) != 0 {
+		fallbackRoot = fallback[0]
+	}
+	var visit func(*document.Node, Path)
+	visit = func(node *document.Node, path Path) {
+		pointer := path.String()
+		if info, exists := metadata.fields[pointer]; exists {
+			if location, ok := metadataFieldLocation(metadata, pointer, info.Origin); ok {
+				node.Location = location
+			} else if location, ok := nearestDocumentLocation(fallbackRoot, path); ok {
+				node.Location = location
+			}
+		} else if location, ok := nearestDocumentLocation(fallbackRoot, path); ok {
+			node.Location = location
+		}
+		switch node.Kind {
+		case document.Mapping:
+			for index := range node.Mapping {
+				entry := &node.Mapping[index]
+				childPath := path.Key(entry.Key)
+				if info, exists := metadata.fields[childPath.String()]; exists {
+					if location, ok := metadataFieldLocation(metadata, childPath.String(), info.Origin); ok {
+						entry.KeyLocation = location
+						entry.ValueLocation = location
+					} else if location, ok := nearestDocumentLocation(fallbackRoot, childPath); ok {
+						entry.KeyLocation = location
+						entry.ValueLocation = location
+					}
+				} else if location, ok := nearestDocumentLocation(fallbackRoot, childPath); ok {
+					entry.KeyLocation = location
+					entry.ValueLocation = location
+				}
+				visit(entry.Value, childPath)
+			}
+		case document.Sequence:
+			for index, child := range node.Sequence {
+				visit(child, path.Index(index))
+			}
+		}
+	}
+	visit(located, Path{})
+	return located
+}
+
+func metadataFieldLocation(metadata Metadata, pointer string, origin Origin) (document.Location, bool) {
+	if location, ok := latestOriginDocumentLocation(origin); ok {
+		return location, true
+	}
+	for index := len(metadata.history[pointer]) - 1; index >= 0; index-- {
+		change := metadata.history[pointer][index]
+		if location, ok := latestOriginDocumentLocation(change.Origin); ok {
+			return location, true
+		}
+		for prior := len(change.Previous) - 1; prior >= 0; prior-- {
+			if location, ok := latestOriginDocumentLocation(change.Previous[prior]); ok {
+				return location, true
+			}
+		}
+	}
+	return document.Location{}, false
+}
+
+func latestOriginDocumentLocation(origin Origin) (document.Location, bool) {
+	if len(origin.Locations) == 0 {
+		return document.Location{}, false
+	}
+	location := origin.Locations[len(origin.Locations)-1]
+	return document.Location{SourceID: location.SourceID, Line: location.Line, Column: location.Column}, true
+}

internal/engine/override_context_test.go

@@ -0,0 +1,155 @@
+package engine
+
+import (
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestPostDecodeOverrideContextOrdersDecodeCLIAndResolutionEvidence(t *testing.T) {
+	t.Parallel()
+	type item struct {
+		Name    string `yaml:"name"`
+		Enabled bool   `yaml:"enabled"`
+	}
+	type config struct {
+		Version string  `yaml:"version"`
+		Rate    float64 `yaml:"rate"`
+		Count   int     `yaml:"count"`
+		Items   []item  `yaml:"items"`
+		APIKey  Secret  `yaml:"api_key"`
+		Derived int     `yaml:"derived"`
+	}
+	defaults := config{Version: "default", Rate: 2, Count: 7, Items: []item{{Name: "default"}}, APIKey: SecretEnv("DEFAULT_SECRET")}
+	structural := parseDocumentForDecode(t, "version: 1\nrate: 1.20\ncount: 5\nitems: [{name: old, enabled: true}]\napi_key: BASE_SECRET\n")
+	setOverrideTestDocumentSource(structural, "source-1")
+	versionPath := Keys("version")
+	schema, schemaIssue := buildSchema(reflect.TypeFor[config](), testSecretBinding())
+	if schemaIssue != nil {
+		t.Fatalf("buildSchema() issue = %#v", schemaIssue)
+	}
+	decoded, issues := decodeConfigurationWithContext(schema, reflect.ValueOf(defaults), structural, decodeContext{versionPath: &versionPath})
+	if len(issues) != 0 {
+		t.Fatalf("decodeConfigurationWithContext() issues = %#v", issues)
+	}
+	sources := []SourceInfo{{ID: "source-1", Label: "main input", Layer: LayerBase, Kind: SourceKindMapping}}
+	contexts := map[string]ResourceContext{"source-1": {BaseDir: "/config"}}
+	input := assembledInput{document: structural, sources: sources, contexts: contexts}
+	batch, diagnostics := preparePostStructuralOverrides(overridePreparationInput{root: structural}, sources, []Override{
+		{Path: Keys("rate"), Value: 1.2, Flag: "--rate"},
+		{Path: Keys("count"), Value: 5, Flag: "--count"},
+		{Path: Keys("items"), Value: []any{map[string]any{"name": "new"}}, Flag: "--items"},
+		{Path: Keys("api_key"), Value: "CLI_SECRET", Flag: "--api-key"},
+	}, nil, defaultImportLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("preparePostStructuralOverrides() diagnostics = %#v", diagnostics)
+	}
+	assigned, issues := applyDecodedOverrides(schema, decoded, batch, decodeContext{versionPath: &versionPath})
+	if len(issues) != 0 {
+		t.Fatalf("applyDecodedOverrides() issues = %#v", issues)
+	}
+	prepared := preparePostDecodeOverrideContext(input, decoded, assigned)
+	if prepared.structuralInput == structural || prepared.preCLI == decoded.final || prepared.decoded.final == assigned.preCLI ||
+		prepared.decoded.final == assigned.final || prepared.referenceInput == assigned.final {
+		t.Fatal("structural, pre-CLI, post-CLI, and located snapshots are not detached")
+	}
+	if raw, ok := documentAtPath(prepared.structuralInput, Keys("version")); !ok || raw.Kind != document.Number || raw.Text != "1" {
+		t.Fatalf("structural version = %#v", raw)
+	}
+	if typed, ok := documentAtPath(prepared.preCLI, Keys("version")); !ok || typed.Kind != document.String || typed.Text != "1" {
+		t.Fatalf("pre-CLI typed version = %#v", typed)
+	}
+	if prepared.metadata.fields["/count"].Origin.Layer != LayerCLI || !prepared.metadata.fields["/count"].Explicit {
+		t.Fatalf("equal-value CLI metadata = %#v", prepared.metadata.fields["/count"])
+	}
+	if prepared.decoded.origins["/count"].Layer != LayerCLI || prepared.decoded.presence["/count"].location.SourceID != batch.overrides[1].source.ID {
+		t.Fatalf("post-CLI metadata maps = %#v / %#v", prepared.decoded.origins["/count"], prepared.decoded.presence["/count"])
+	}
+	if _, explicit := prepared.decoded.presence["/items/0/enabled"]; explicit {
+		t.Fatal("replaced list retained discarded-child presence")
+	}
+	if len(prepared.applications) != 1 || len(prepared.postDecodeApps) != len(batch.overrides) || len(prepared.historyApplications()) != 1+len(batch.overrides) {
+		t.Fatalf("history applications = structural:%d CLI:%d all:%d", len(prepared.applications), len(prepared.postDecodeApps), len(prepared.historyApplications()))
+	}
+	if len(prepared.sources) != len(sources)+len(batch.overrides) || prepared.sources[len(prepared.sources)-1].Layer != LayerCLI {
+		t.Fatalf("prepared source order = %#v", prepared.sources)
+	}
+	if prepared.resolution.contexts["source-1"].BaseDir != "/config" {
+		t.Fatalf("resolution source contexts = %#v", prepared.resolution.contexts)
+	}
+	if info, ok := prepared.resolution.lookup(Keys("count")); !ok || !info.Explicit || info.Origin.Layer != LayerCLI {
+		t.Fatalf("resolution entry count = %#v, %v", info, ok)
+	}
+	cliSource := batch.overrides[3].source.ID
+	if source, ok := prepared.resolution.source(cliSource); !ok || source.Layer != LayerCLI || source.Label != "--api-key" {
+		t.Fatalf("resolution CLI source = %#v, %v", source, ok)
+	}
+
+	inspection := Inspection{
+		metadata: prepared.metadata, baseline: decoded.baseline, input: assigned.final, inputOrigins: assigned.origins,
+		structuralInput: prepared.structuralInput, preCLI: prepared.preCLI, preCLIOrigins: prepared.preCLIOrigins,
+		postDecodeApps: prepared.postDecodeApps, final: assigned.final,
+		applications: prepared.applications,
+		immutableLookup: buildDocumentLookup(prepared.structuralInput, prepared.preCLI, assigned.final,
+			prepared.applications[0].value, prepared.postDecodeApps[0].value, prepared.postDecodeApps[1].value,
+			prepared.postDecodeApps[2].value, prepared.postDecodeApps[3].value),
+	}
+	rateExplanation, ok := inspection.Explain(Keys("rate"))
+	if !ok {
+		t.Fatal("Explain(rate) did not return a history")
+	}
+	if len(rateExplanation.History) != 4 || rateExplanation.History[0].Origin.Layer != LayerDefault ||
+		rateExplanation.History[1].Origin.Layer != LayerBase || rateExplanation.History[2].Origin.Operation != ChangeDecoding ||
+		rateExplanation.History[3].Origin.Layer != LayerCLI {
+		t.Fatalf("rate history order = %#v", rateExplanation.History)
+	}
+
+	configuration := assigned.value.Interface().(config)
+	resolver := func(value *config, resolution *Resolution) error {
+		if info, found := resolution.InputInfo(Keys("count")); !found || !info.Explicit || info.Origin.Layer != LayerCLI {
+			t.Errorf("resolver input info = %#v, %v", info, found)
+		}
+		if source, found := resolution.Source(cliSource); !found || source.Layer != LayerCLI {
+			t.Errorf("resolver CLI source = %#v, %v", source, found)
+		}
+		Default(resolution, Keys("count"), &value.Count, 99, "fill missing count")
+		Default(resolution, Keys("derived"), &value.Derived, 42, "derive default")
+		value.APIKey = SecretEnv("RESOLVED_SECRET")
+		resolution.Record(Keys("api_key"), ChangeNormalization, "select effective secret reference")
+		return nil
+	}
+	resolved := runResolution(&configuration, resolver, schema, prepared.decoded, prepared.referenceInput, prepared.resolution)
+	if len(resolved.diagnostics) != 0 || configuration.Count != 5 || configuration.Derived != 42 {
+		t.Fatalf("resolution = %#v, configuration = %#v", resolved, configuration)
+	}
+	applyResolutionMetadata(&prepared.metadata, resolved)
+	effectiveReferenceInput := documentWithMetadataLocations(resolved.final, prepared.metadata)
+	if node, ok := documentAtPath(effectiveReferenceInput, Keys("api_key")); !ok || node.Text != "RESOLVED_SECRET" || node.Location.SourceID != cliSource {
+		t.Fatalf("effective reference/location = %#v", node)
+	}
+	missing := resolveSecretReferences(reflect.ValueOf(&configuration).Elem(), schema, effectiveReferenceInput, func(name string) (string, bool) {
+		if name != "RESOLVED_SECRET" {
+			t.Errorf("secret lookup name = %q", name)
+		}
+		return "", false
+	})
+	if len(missing.diagnostics) != 1 || missing.diagnostics[0].Code != CodeSecretUnset || missing.diagnostics[0].Primary == nil || missing.diagnostics[0].Primary.SourceID != cliSource {
+		t.Fatalf("secret failure handoff = %#v", missing.diagnostics)
+	}
+}
+
+func setOverrideTestDocumentSource(node *document.Node, sourceID string) {
+	if node == nil {
+		return
+	}
+	node.Location.SourceID = sourceID
+	for index := range node.Mapping {
+		node.Mapping[index].KeyLocation.SourceID = sourceID
+		node.Mapping[index].ValueLocation.SourceID = sourceID
+		setOverrideTestDocumentSource(node.Mapping[index].Value, sourceID)
+	}
+	for _, child := range node.Sequence {
+		setOverrideTestDocumentSource(child, sourceID)
+	}
+}

internal/engine/override_decode.go

@@ -0,0 +1,226 @@
+package engine
+
+import (
+	"reflect"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+// decodedOverrideResult keeps the typed pre-CLI projection and raw CLI
+// contributions alongside the effective typed value and its inspection data.
+type decodedOverrideResult struct {
+	value     reflect.Value
+	preCLI    *document.Node
+	final     *document.Node
+	presence  map[string]inputPresence
+	origins   map[string]Origin
+	overrides []preparedOverride
+}
+
+// applyDecodedOverrides assigns prepared CLI values to a detached, decoded
+// configuration. Each sparse mapping is decoded against the current typed
+// value, preserving omitted mapping fields while replacing supplied sequences.
+func applyDecodedOverrides(
+	schema *schemaDescriptor,
+	decoded decodedConfiguration,
+	batch preparedOverrideBatch,
+	context decodeContext,
+) (decodedOverrideResult, []decodeIssue) {
+	if schema == nil || schema.root == nil || !decoded.value.IsValid() || decoded.value.Type() != schema.root.typeOf || decoded.final == nil {
+		return decodedOverrideResult{}, []decodeIssue{{code: CodeSchemaUnsupportedType, message: "decoded configuration does not match the schema"}}
+	}
+
+	preCLI := document.Clone(decoded.final)
+	working, cloneIssue := cloneConfiguration(schema, decoded.value, defaultProjectionLimits())
+	if cloneIssue != nil {
+		return decodedOverrideResult{}, []decodeIssue{decodeIssueFromProjection(cloneIssue)}
+	}
+	presence := cloneInputPresence(decoded.presence)
+	origins := cloneOrigins(decoded.origins)
+	var lookup *documentLookup
+	if len(batch.overrides) != 0 {
+		lookup = buildDocumentLookup(decoded.final)
+	}
+
+	for _, override := range batch.overrides {
+		if len(override.path.segments) == 0 {
+			return decodedOverrideResult{}, []decodeIssue{{code: CodeOverrideInvalidPath, message: "configuration override path is invalid", location: document.Location{SourceID: override.source.ID}}}
+		}
+		input, issue := decodedOverrideInput(override)
+		if issue != nil {
+			return decodedOverrideResult{}, []decodeIssue{*issue}
+		}
+		updated, issues := decodeValue(input, working, schema.root, Path{}, schema, context)
+		if len(issues) != 0 {
+			return decodedOverrideResult{}, issues
+		}
+		working = updated
+
+		location := document.Location{SourceID: override.source.ID}
+		recordOverrideAncestors(presence, origins, override.path, location)
+		// Prepared paths cannot overlap, so other assignments cannot change
+		// this target's pre-CLI subtree.
+		existing, _ := documentAtPathWithLookup(decoded.final, override.path, lookup)
+		updateOverridePresence(presence, existing, override.value, override.path, location)
+		updateOverrideOrigins(origins, existing, override.value, override.path, location)
+	}
+	final, projectionIssue := projectConfiguration(schema, working, defaultProjectionLimits())
+	if projectionIssue != nil {
+		return decodedOverrideResult{}, []decodeIssue{decodeIssueFromProjection(projectionIssue)}
+	}
+
+	// New fields created by decoding a partial mapping into a previously nil
+	// pointer have no input origin. Fill those gaps as defaults while retaining
+	// all surviving source and CLI contributions already in the origin map.
+	fillDefaultOrigins(final, Path{}, origins)
+
+	return decodedOverrideResult{
+		value:     working,
+		preCLI:    preCLI,
+		final:     final,
+		presence:  presence,
+		origins:   origins,
+		overrides: clonePreparedOverrides(batch.overrides),
+	}, nil
+}
+
+func recordOverrideAncestors(presence map[string]inputPresence, origins map[string]Origin, path Path, location document.Location) {
+	mergeOverlayOrigin(origins, Path{}, location, LayerCLI)
+	prefix := Path{}
+	for index, segment := range path.segments {
+		prefix = prefix.Key(segment.key)
+		if index == len(path.segments)-1 {
+			break
+		}
+		pointer := prefix.String()
+		if _, exists := presence[pointer]; !exists {
+			presence[pointer] = inputPresence{location: location}
+		}
+		mergeOverlayOrigin(origins, prefix, location, LayerCLI)
+	}
+}
+
+func decodedOverrideInput(override preparedOverride) (*document.Node, *decodeIssue) {
+	location := document.Location{SourceID: override.source.ID}
+	value := document.Clone(override.value)
+	if value == nil {
+		return nil, &decodeIssue{code: CodeOverrideInvalidPath, path: override.path.clone(), message: "configuration override value is invalid", location: location}
+	}
+	for index := len(override.path.segments) - 1; index >= 0; index-- {
+		segment := override.path.segments[index]
+		if segment.kind == pathSegmentIndex {
+			return nil, &decodeIssue{code: CodeOverrideInvalidPath, path: override.path.clone(), message: "configuration override path is invalid", location: location}
+		}
+		value = &document.Node{
+			Kind:     document.Mapping,
+			Location: location,
+			Mapping: []document.Entry{{
+				Key: segment.key, KeyLocation: location, ValueLocation: location, Value: value,
+			}},
+		}
+	}
+	return value, nil
+}
+
+func cloneInputPresence(input map[string]inputPresence) map[string]inputPresence {
+	cloned := make(map[string]inputPresence, len(input))
+	for path, value := range input {
+		cloned[path] = value
+	}
+	return cloned
+}
+
+func cloneOrigins(input map[string]Origin) map[string]Origin {
+	cloned := make(map[string]Origin, len(input))
+	for path, value := range input {
+		cloned[path] = cloneOrigin(value)
+	}
+	return cloned
+}
+
+func clonePreparedOverrides(input []preparedOverride) []preparedOverride {
+	cloned := make([]preparedOverride, len(input))
+	for index, value := range input {
+		cloned[index] = preparedOverride{
+			path:   value.path.clone(),
+			value:  document.Clone(value.value),
+			source: value.source,
+			bytes:  value.bytes,
+			nodes:  value.nodes,
+		}
+	}
+	return cloned
+}
+
+func updateOverridePresence(presence map[string]inputPresence, existing, incoming *document.Node, path Path, location document.Location) {
+	if existing != nil && existing.Kind == document.Mapping && incoming.Kind == document.Mapping {
+		if _, exists := presence[path.String()]; !exists {
+			presence[path.String()] = inputPresence{location: location}
+		}
+		var index mappingIndex
+		for _, entry := range incoming.Mapping {
+			childPath := path.Key(entry.Key)
+			position := index.find(existing, entry.Key)
+			var previous *document.Node
+			if position >= 0 {
+				previous = existing.Mapping[position].Value
+			}
+			updateOverridePresence(presence, previous, entry.Value, childPath, location)
+		}
+		return
+	}
+
+	deletePresencePathSubtree(presence, path)
+	collectPresence(incoming, path, presence)
+}
+
+func deletePresencePathSubtree(presence map[string]inputPresence, path Path) {
+	pointer := path.String()
+	for candidate := range presence {
+		if candidate == pointer || strings.HasPrefix(candidate, pointer+"/") {
+			delete(presence, candidate)
+		}
+	}
+}
+
+func updateOverrideOrigins(origins map[string]Origin, existing, incoming *document.Node, path Path, location document.Location) {
+	if existing != nil && existing.Kind == document.Mapping && incoming.Kind == document.Mapping {
+		mergeOverlayOrigin(origins, path, location, LayerCLI)
+		var index mappingIndex
+		for _, entry := range incoming.Mapping {
+			childPath := path.Key(entry.Key)
+			position := index.find(existing, entry.Key)
+			var previous *document.Node
+			if position >= 0 {
+				previous = existing.Mapping[position].Value
+			}
+			updateOverrideOrigins(origins, previous, entry.Value, childPath, location)
+		}
+		return
+	}
+
+	pointer := path.String()
+	for candidate := range origins {
+		if candidate == pointer || strings.HasPrefix(candidate, pointer+"/") {
+			delete(origins, candidate)
+		}
+	}
+	collectOverlayOrigins(origins, incoming, path, LayerCLI)
+}
+
+func fillDefaultOrigins(node *document.Node, path Path, origins map[string]Origin) {
+	if _, exists := origins[path.String()]; !exists {
+		origins[path.String()] = Origin{Layer: LayerDefault}
+	}
+	switch node.Kind {
+	case document.Mapping:
+		for _, entry := range node.Mapping {
+			fillDefaultOrigins(entry.Value, path.Key(entry.Key), origins)
+		}
+	case document.Sequence:
+		for index, child := range node.Sequence {
+			fillDefaultOrigins(child, path.Index(index), origins)
+		}
+	}
+}

internal/engine/override_history_order_test.go

@@ -0,0 +1,93 @@
+package engine
+
+import "testing"
+
+func TestCLIHistoryFollowsInheritanceAndPrecedesResolution(t *testing.T) {
+	t.Parallel()
+	for _, test := range []struct {
+		name                             string
+		layered, records, equal, resolve bool
+	}{
+		{name: "ordinary mapping"},
+		{name: "layered mapping equal with resolution", layered: true, equal: true, resolve: true},
+		{name: "ordinary records equal", records: true, equal: true},
+		{name: "layered records with resolution", layered: true, records: true, resolve: true},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			body := "base: {value: parent}\nchild: {extends: base, value: authored}\n"
+			query, parent := Keys("child", "value"), Keys("base", "value")
+			cliValue := "cli"
+			if test.equal {
+				cliValue = "authored"
+			}
+			override := Override{Path: query, Value: cliValue, Flag: "--value"}
+			if test.records {
+				body = "configkit:\n  sequences: [{destination: [items], key: id}]\nitems: [{id: base, value: parent}, {id: child, extends: {id: base}}]\n"
+				query, parent = Keys("items").Index(1).Key("value"), Keys("items").Index(0).Key("value")
+				if test.equal {
+					cliValue = "parent"
+				}
+				override = Override{Path: Keys("items"), Value: []any{map[string]any{"id": "base", "value": "parent"}, map[string]any{"id": "child", "value": cliValue}}, Flag: "--items"}
+			}
+			definition := Definition[map[string]any]{}
+			if test.resolve {
+				definition.Resolve = func(value *map[string]any, resolution *Resolution) error {
+					recorded := query
+					if test.records {
+						(*value)["items"].([]any)[1].(map[string]any)["value"] = "resolved"
+						recorded = Keys("items")
+					} else {
+						(*value)["child"].(map[string]any)["value"] = "resolved"
+					}
+					resolution.Record(recorded, ChangeNormalization, "normalize after CLI", parent)
+					return nil
+				}
+			}
+			source := Bytes("source", []byte(body))
+			var loaded *testResult[map[string]any]
+			var err error
+			if test.layered {
+				loaded, err = testGroupedLoad(loadRequest[map[string]any]{main: loadInput{source: source}, definition: definition, overrides: []Override{override}})
+			} else {
+				loaded, err = testLoad(source, Options[map[string]any]{Definition: definition, Overrides: []Override{override}})
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			history := loaded.Metadata().History(query)
+			inherited, cli, resolved := false, false, false
+			for _, change := range history {
+				if change.Origin.Operation == ChangeInheritance {
+					if cli {
+						t.Fatal("inheritance reported after CLI")
+					}
+					inherited = true
+				} else if change.Origin.Layer == LayerBase && cli {
+					t.Fatal("source definition reappeared after CLI")
+				}
+				if change.Origin.Layer == LayerCLI {
+					if !inherited || resolved {
+						t.Fatal("CLI reported outside its lifecycle phase")
+					}
+					cli = true
+				}
+				if change.Origin.Layer == LayerResolution {
+					if !cli {
+						t.Fatal("resolution reported before CLI")
+					}
+					resolved = true
+					if len(change.Dependencies) != 1 || change.Dependencies[0].String() != parent.String() {
+						t.Fatalf("resolution dependencies = %#v", change.Dependencies)
+					}
+				}
+			}
+			if !inherited || !cli || resolved != test.resolve {
+				t.Fatalf("missing lifecycle history: %#v", history)
+			}
+			info, _ := loaded.Metadata().Lookup(query)
+			if history[len(history)-1].Origin.Layer != info.Origin.Layer {
+				t.Fatal("last history origin disagrees with effective metadata")
+			}
+		})
+	}
+}

internal/engine/override_lifecycle_test.go

@@ -0,0 +1,268 @@
+package engine
+
+import (
+	"reflect"
+	"testing"
+)
+
+func TestNestedCLIOverridePreservesRetainedInputPresence(t *testing.T) {
+	t.Parallel()
+	type nested struct {
+		Changed int  `yaml:"changed"`
+		Count   int  `yaml:"count"`
+		Zero    int  `yaml:"zero"`
+		Enabled bool `yaml:"enabled"`
+	}
+	type settings struct {
+		Nested nested `yaml:"nested"`
+	}
+	type config struct {
+		Settings settings `yaml:"settings"`
+	}
+	for _, layered := range []bool{false, true} {
+		name := "ordinary"
+		if layered {
+			name = "layered"
+		}
+		t.Run(name, func(t *testing.T) {
+			source := Bytes("input", []byte("settings:\n  nested:\n    changed: 1\n    count: 2\n    zero: 0\n    enabled: false\n"))
+			definition := Definition[config]{Resolve: func(value *config, resolution *Resolution) error {
+				for _, key := range []string{"count", "zero", "enabled"} {
+					info, ok := resolution.InputInfo(Keys("settings", "nested", key))
+					if !ok || !info.Explicit || info.Origin.Layer != LayerBase {
+						t.Errorf("retained %s input info = %#v, %v", key, info, ok)
+					}
+				}
+				Default(resolution, Keys("settings", "nested", "count"), &value.Settings.Nested.Count, 99, "fill missing count")
+				Default(resolution, Keys("settings", "nested", "zero"), &value.Settings.Nested.Zero, 99, "fill missing zero")
+				Default(resolution, Keys("settings", "nested", "enabled"), &value.Settings.Nested.Enabled, true, "fill missing enabled")
+				return nil
+			}}
+			overrides := []Override{{Path: Keys("settings"), Value: map[string]any{"nested": map[string]any{"changed": 3}}, Flag: "--settings"}}
+			var result *testResult[config]
+			var err error
+			if layered {
+				result, err = testGroupedLoad(loadRequest[config]{main: loadInput{source: source}, definition: definition, overrides: overrides})
+			} else {
+				result, err = testLoad(source, Options[config]{Definition: definition, Overrides: overrides})
+			}
+			if err != nil {
+				t.Fatal(err)
+			}
+			if got, want := result.Config.Settings.Nested, (nested{Changed: 3, Count: 2}); got != want {
+				t.Fatalf("resolved nested values = %#v, want %#v", got, want)
+			}
+			for _, key := range []string{"count", "zero", "enabled"} {
+				info, ok := result.Metadata().Lookup(Keys("settings", "nested", key))
+				if !ok || !info.Explicit || info.Origin.Layer != LayerBase || len(info.Origin.Locations) != 1 || info.Origin.Locations[0].SourceID != "source-1" {
+					t.Errorf("retained %s metadata = %#v, %v", key, info, ok)
+				}
+			}
+			info, ok := result.Metadata().Lookup(Keys("settings", "nested", "changed"))
+			if !ok || !info.Explicit || info.Origin.Layer != LayerCLI {
+				t.Errorf("changed metadata = %#v, %v", info, ok)
+			}
+		})
+	}
+}
+
+func TestPostDecodeOverrideLifecycleMatchesOrdinaryAndLayeredLoads(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		Count   int `yaml:"count"`
+		Derived int `yaml:"derived"`
+	}
+	input := Bytes("settings.yml", []byte("count: 4\n"))
+	defaultsCalls := 0
+	definition := Definition[config]{
+		Defaults: func() config {
+			defaultsCalls++
+			return config{Count: 9, Derived: 1}
+		},
+		Resolve: func(value *config, resolution *Resolution) error {
+			info, ok := resolution.InputInfo(Keys("count"))
+			if !ok || !info.Explicit || info.Origin.Layer != LayerCLI {
+				t.Errorf("resolution count info = %#v, %v", info, ok)
+			}
+			if source, ok := resolution.Source("source-2"); !ok || source.Layer != LayerCLI {
+				t.Errorf("resolution CLI source = %#v, %v", source, ok)
+			}
+			Default(resolution, Keys("count"), &value.Count, 99, "preserve explicit count")
+			Default(resolution, Keys("derived"), &value.Derived, value.Count*2, "derive from CLI count", Keys("count"))
+			Normalize(resolution, Keys("count"), &value.Count, value.Count+1, "normalize after CLI")
+			return nil
+		},
+	}
+	options := Options[config]{Definition: definition, Overrides: []Override{{Path: Keys("count"), Value: 4, Flag: "--count"}}}
+	ordinary, err := testLoad(input, options)
+	if err != nil {
+		t.Fatal(err)
+	}
+	layered, err := testGroupedLoad(loadRequest[config]{
+		main: loadInput{source: input}, definition: definition,
+		overrides: []Override{{Path: Keys("count"), Value: 4, Flag: "--count"}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if defaultsCalls != 2 {
+		t.Fatalf("defaults factory calls = %d, want once per load", defaultsCalls)
+	}
+	for name, result := range map[string]*testResult[config]{"ordinary": ordinary, "layered": layered} {
+		if result.Config.Count != 5 || result.Config.Derived != 8 {
+			t.Errorf("%s resolved configuration = %#v", name, result.Config)
+		}
+		if got := historyLayers(result.Metadata().History(Keys("count"))); !reflect.DeepEqual(got, []Layer{LayerDefault, LayerBase, LayerCLI, LayerResolution}) {
+			t.Errorf("%s count history layers = %#v", name, got)
+		}
+		info, ok := result.Metadata().Lookup(Keys("count"))
+		if !ok || info.Origin.Layer != LayerResolution {
+			t.Errorf("%s final count origin = %#v, %v", name, info, ok)
+		}
+	}
+	if !reflect.DeepEqual(ordinary.Config, layered.Config) ||
+		!reflect.DeepEqual(ordinary.Metadata().History(Keys("count")), layered.Metadata().History(Keys("count"))) {
+		t.Fatalf("ordinary and layered results differ: %#v / %#v", ordinary.Config, layered.Config)
+	}
+}
+
+func TestNoSourceOverridesReachResolutionAfterDefaults(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		Count   int `yaml:"count"`
+		Derived int `yaml:"derived"`
+	}
+	calls := 0
+	result, err := testLoad(NoSource(), Options[config]{
+		Definition: Definition[config]{
+			Defaults: func() config {
+				calls++
+				return config{Count: 2}
+			},
+			Resolve: func(value *config, resolution *Resolution) error {
+				info, ok := resolution.InputInfo(Keys("count"))
+				if !ok || !info.Explicit || info.Origin.Layer != LayerCLI {
+					t.Errorf("resolution count info = %#v, %v", info, ok)
+				}
+				Default(resolution, Keys("count"), &value.Count, 10, "preserve CLI value")
+				Default(resolution, Keys("derived"), &value.Derived, value.Count*3, "derive from CLI count")
+				return nil
+			},
+		},
+		Overrides: []Override{{Path: Keys("count"), Value: 4, Flag: "--count"}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if calls != 1 || result.Config.Count != 4 || result.Config.Derived != 12 {
+		t.Fatalf("defaults-only CLI result = %#v, defaults calls %d", result.Config, calls)
+	}
+	if sources := result.Sources(); len(sources) != 1 || sources[0].Layer != LayerCLI {
+		t.Fatalf("defaults-only CLI sources = %#v", sources)
+	}
+}
+
+func TestCLISequenceAssignmentReplacesAppendAndUpsertResults(t *testing.T) {
+	t.Parallel()
+	type item struct {
+		ID string `yaml:"id"`
+	}
+	type config struct {
+		Items []item `yaml:"items"`
+	}
+	declaration := func(mode string, id string) Source {
+		return Bytes(id, []byte("configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: "+mode+"\nitems: [{id: "+id+"}]\n"))
+	}
+	result, err := testGroupedLoad(loadRequest[config]{
+		main:      loadInput{source: declaration("upsert", "main")},
+		underlays: []loadGroup{{inputs: []loadInput{{source: declaration("append", "underlay")}}}},
+		overrides: []Override{{Path: Keys("items"), Value: []any{map[string]any{"id": "cli"}}, Flag: "--items"}},
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(result.Config.Items, []item{{ID: "cli"}}) {
+		t.Fatalf("CLI sequence assignment = %#v, want complete replacement", result.Config.Items)
+	}
+}
+
+func TestCLISecretReferenceUsesEffectiveLookupAndLocation(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		APIKey Secret `yaml:"api_key"`
+	}
+	options := Options[config]{
+		Definition: Definition[config]{Defaults: func() config { return config{APIKey: SecretEnv("DEFAULT_SECRET")} }},
+		Overrides:  []Override{{Path: Keys("api_key"), Value: "CLI_SECRET", Flag: "--api-key"}},
+	}
+	source := Bytes("secret-input", []byte("api_key: BASE_SECRET\n"))
+	t.Run("effective reference is looked up", func(t *testing.T) {
+		calls := 0
+		result, err := testLoadWithSecretLookup(source, func(name string) (string, bool) {
+			calls++
+			if name != "CLI_SECRET" {
+				t.Errorf("secret lookup name = %q", name)
+			}
+			return "effective-credential", true
+		}, options)
+		if err != nil || calls != 1 || result.Config.APIKey.Value() != "effective-credential" {
+			t.Fatalf("CLI secret result = %#v, calls %d, error %v", result, calls, err)
+		}
+		info, ok := result.Metadata().Lookup(Keys("api_key"))
+		if !ok || info.Origin.Layer != LayerCLI {
+			t.Fatalf("CLI secret origin = %#v, %v", info, ok)
+		}
+	})
+	t.Run("missing effective reference uses CLI location", func(t *testing.T) {
+		result, err := testLoadWithSecretLookup(source, func(name string) (string, bool) {
+			if name != "CLI_SECRET" {
+				t.Errorf("secret lookup name = %q", name)
+			}
+			return "", false
+		}, options)
+		if result != nil {
+			t.Fatalf("missing secret returned a result: %#v", result)
+		}
+		loadErr, ok := err.(*LoadError)
+		if !ok || len(loadErr.Diagnostics()) != 1 {
+			t.Fatalf("missing secret error = %v", err)
+		}
+		diagnostic := loadErr.Diagnostics()[0]
+		if diagnostic.Code != CodeSecretUnset || diagnostic.Primary == nil || diagnostic.Primary.SourceID != "source-2" {
+			t.Fatalf("missing secret diagnostic = %#v", diagnostic)
+		}
+	})
+}
+
+func TestCLIOverridesCannotHideEarlierFailuresOrAddInheritance(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		Count  int            `yaml:"count"`
+		Child  map[string]any `yaml:"child"`
+		Parent map[string]any `yaml:"parent"`
+	}
+	t.Run("decode error", func(t *testing.T) {
+		_, err := testLoad(Bytes("bad-count", []byte("count: invalid\n")), Options[config]{
+			Overrides: []Override{{Path: Keys("count"), Value: 3, Flag: "--count"}},
+		})
+		requireSecretLoadCode(t, err, CodeDecodeType)
+	})
+	t.Run("inheritance error", func(t *testing.T) {
+		_, err := testLoad(Bytes("missing-parent", []byte("child: {extends: missing, value: source}\n")), Options[config]{
+			Overrides: []Override{{Path: Keys("child"), Value: map[string]any{"value": "cli"}, Flag: "--child"}},
+		})
+		requireSecretLoadCode(t, err, CodeInheritanceMissing)
+	})
+	t.Run("cannot add relationship", func(t *testing.T) {
+		_, err := testLoad(Bytes("new-relationship", []byte("child: {value: source}\nparent: {value: parent}\n")), Options[config]{
+			Overrides: []Override{{Path: Keys("child"), Value: map[string]any{"extends": "parent"}, Flag: "--child"}},
+		})
+		requireSecretLoadCode(t, err, CodeOverrideDirective)
+	})
+	t.Run("cannot cancel relationship", func(t *testing.T) {
+		_, err := testLoad(Bytes("cancel-relationship", []byte("child: {extends: parent}\nparent: {value: parent}\n")), Options[config]{
+			Overrides: []Override{{Path: Keys("child", "extends"), Value: nil, Flag: "--extends"}},
+		})
+		requireSecretLoadCode(t, err, CodeOverrideDirective)
+	})
+}

internal/engine/override_test.go

@@ -440,9 +440,91 @@ func TestOverrideAggregateLimitsFailBeforeApplication(t *testing.T) {
 		t.Fatal(diagnostics)
 	}
 	base.inputNodes = 1
-	result, sources, diagnostics := applyOverrides(base, nil, []Override{{Path: Keys("value"), Value: "x", Flag: "--value"}}, nil, importLimits{sources: 1, bytes: 1, nodes: 2})
-	if result != nil || len(sources) != 1 || len(diagnostics) != 1 || diagnostics[0].Code != CodeOverrideLimitExceeded || len(base.root.Mapping) != 0 {
-		t.Fatalf("bounded apply = %#v, %#v, %#v; base %#v", result, sources, diagnostics, base.root)
+	_, diagnostics = preparePostStructuralOverrides(overridePreparationInput{
+		root: base.root, inputBytes: base.inputBytes, inputNodes: base.inputNodes,
+	}, nil, []Override{{Path: Keys("value"), Value: "x", Flag: "--value"}}, nil, importLimits{sources: 1, bytes: 1, nodes: 2})
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverrideLimitExceeded || len(base.root.Mapping) != 0 {
+		t.Fatalf("bounded preparation = %#v; base %#v", diagnostics, base.root)
+	}
+}
+
+func TestPreparedOverrideBatchDetachesInputsAndAllocatesSourcesInOrder(t *testing.T) {
+	base, diagnostics := composeDocuments(parseCompositionDocument(t, "base", "settings: {}\n"))
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	sources := []SourceInfo{{ID: "source-1", Label: "base", Layer: LayerBase, Kind: SourceKindMapping}}
+	firstValue := map[string]any{"nested": map[string]any{"name": "original"}}
+	secondValue := []any{map[string]any{"enabled": true}}
+	batch, diagnostics := preparePostStructuralOverrides(overridePreparationInput{
+		root: base.root, inputBytes: base.inputBytes, inputNodes: base.inputNodes,
+	}, sources, []Override{
+		{Path: Keys("settings", "first"), Value: firstValue, Flag: "--first"},
+		{Path: Keys("settings", "second"), Value: secondValue, Flag: "--second"},
+	}, nil, defaultImportLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("prepare post-structural overrides: %#v", diagnostics)
+	}
+	if len(batch.overrides) != 2 || len(batch.sources) != 3 {
+		t.Fatalf("prepared counts = %d overrides, %d sources", len(batch.overrides), len(batch.sources))
+	}
+	for index, want := range []string{"source-2", "source-3"} {
+		if batch.overrides[index].source.ID != want || batch.sources[index+1].ID != want {
+			t.Errorf("prepared source %d = %#v / %#v, want %s", index, batch.overrides[index].source, batch.sources[index+1], want)
+		}
+	}
+	if batch.sources[1].Label != "--first" || batch.sources[2].Label != "--second" {
+		t.Fatalf("synthetic source order = %#v", batch.sources)
+	}
+
+	firstValue["nested"].(map[string]any)["name"] = "changed after preparation"
+	preparedName, found := documentAtPath(batch.overrides[0].value, Keys("nested", "name"))
+	if !found || preparedName.Text != "original" {
+		t.Fatalf("prepared override aliases input value: %#v, %v", preparedName, found)
+	}
+	preparedName.Text = "changed prepared snapshot"
+	if firstValue["nested"].(map[string]any)["name"] != "changed after preparation" {
+		t.Fatal("prepared override mutation changed caller input")
+	}
+	batch.sources[0].Label = "changed batch source"
+	if sources[0].Label != "base" {
+		t.Fatal("prepared source list aliases the input source list")
+	}
+	if len(base.root.Mapping) != 1 || base.root.Mapping[0].Value.Kind != document.Mapping || len(base.root.Mapping[0].Value.Mapping) != 0 {
+		t.Fatalf("preparation mutated assembled input: %#v", base.root)
+	}
+}
+
+func TestPostStructuralOverridePreparationRejectsInheritanceDirectives(t *testing.T) {
+	base, diagnostics := composeDocuments(parseCompositionDocument(t, "base", "child: {}\nitems: []\n"))
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	tests := []struct {
+		name     string
+		override Override
+		path     string
+	}{
+		{
+			name:     "supplied path",
+			override: Override{Path: Keys("child", "extends"), Value: "parent", Flag: "--extends"},
+			path:     "/child/extends",
+		},
+		{
+			name:     "nested value",
+			override: Override{Path: Keys("items"), Value: []any{map[string]any{"extends": "parent"}}, Flag: "--items"},
+			path:     "/items/0/extends",
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, diagnostics := preparePostStructuralOverrides(overridePreparationInput{
+				root: base.root, inputBytes: base.inputBytes, inputNodes: base.inputNodes,
+			}, nil, []Override{test.override}, nil, defaultImportLimits())
+			if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverrideDirective || diagnostics[0].Path.String() != test.path {
+				t.Fatalf("post-structural diagnostics = %#v, want directive at %s", diagnostics, test.path)
+			}
+		})
 	}
 }
 
@@ -468,3 +550,139 @@ func fmtLoadError(loadError *LoadError) string {
 	_ = WriteDiagnostics(&output, loadError.Diagnostics())
 	return loadError.Error() + output.String()
 }
+
+func TestApplyDecodedOverridesUsesSchemaAndPreservesTypedOwnership(t *testing.T) {
+	t.Parallel()
+	type child struct {
+		Name    string `yaml:"name"`
+		Enabled bool   `yaml:"enabled"`
+	}
+	type config struct {
+		Nested  child            `yaml:"nested"`
+		Labels  map[string]child `yaml:"labels"`
+		Items   []child          `yaml:"items"`
+		Empty   []string         `yaml:"empty"`
+		Count   int              `yaml:"count"`
+		Enabled bool             `yaml:"enabled"`
+		Label   string           `yaml:"label"`
+		Small   namedSmall       `yaml:"small"`
+		Text    validatedText    `yaml:"text"`
+		Delay   time.Duration    `yaml:"delay"`
+		APIKey  Secret           `yaml:"api_key"`
+		Maybe   *string          `yaml:"maybe"`
+	}
+	defaultMaybe := "default"
+	defaults := config{
+		Nested: child{Name: "default", Enabled: true},
+		Labels: map[string]child{"default": {Name: "default", Enabled: true}},
+		Items:  []child{{Name: "default", Enabled: true}},
+		Empty:  []string{"default"},
+		Count:  8, Enabled: true, Label: "default", Small: 7, Text: "default", Delay: time.Second,
+		Maybe: &defaultMaybe,
+	}
+	input := parseDocumentForDecode(t, "nested: {name: source, enabled: true}\nlabels: {old: {name: source, enabled: true}}\nitems: [{name: discarded, enabled: true}]\nempty: [source]\ncount: 7\nenabled: true\nlabel: source\nsmall: 3\ntext: source\ndelay: 1s\napi_key: SOURCE_SECRET\nmaybe: source\n")
+	schema, schemaIssue := buildSchema(reflect.TypeFor[config](), testSecretBinding())
+	if schemaIssue != nil {
+		t.Fatalf("buildSchema() issue = %#v", schemaIssue)
+	}
+	decoded, decodeIssues := decodeConfiguration(schema, reflect.ValueOf(defaults), input)
+	if len(decodeIssues) != 0 {
+		t.Fatalf("decodeConfiguration() issues = %#v", decodeIssues)
+	}
+	batch, diagnostics := preparePostStructuralOverrides(overridePreparationInput{root: input}, nil, []Override{
+		{Path: Keys("nested"), Value: map[string]any{"enabled": false}, Flag: "--nested"},
+		{Path: Keys("labels"), Value: map[string]any{
+			"old": map[string]any{"enabled": false}, "new": map[string]any{"name": "cli"},
+		}, Flag: "--labels"},
+		{Path: Keys("items"), Value: []any{map[string]any{"name": "replacement"}}, Flag: "--items"},
+		{Path: Keys("empty"), Value: []any{}, Flag: "--empty"},
+		{Path: Keys("count"), Value: 0, Flag: "--count"},
+		{Path: Keys("enabled"), Value: false, Flag: "--enabled"},
+		{Path: Keys("label"), Value: "", Flag: "--label"},
+		{Path: Keys("small"), Value: 0, Flag: "--small"},
+		{Path: Keys("text"), Value: "cli text", Flag: "--text"},
+		{Path: Keys("delay"), Value: "250ms", Flag: "--delay"},
+		{Path: Keys("api_key"), Value: "CLI_SECRET", Flag: "--api-key"},
+		{Path: Keys("maybe"), Value: nil, Flag: "--maybe"},
+	}, nil, defaultImportLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("preparePostStructuralOverrides() diagnostics = %#v", diagnostics)
+	}
+	result, issues := applyDecodedOverrides(schema, decoded, batch, decodeContext{})
+	if len(issues) != 0 {
+		t.Fatalf("applyDecodedOverrides() issues = %#v", issues)
+	}
+	got := result.value.Interface().(config)
+	if got.Nested != (child{Name: "source", Enabled: false}) || !reflect.DeepEqual(got.Labels, map[string]child{
+		"default": {Name: "default", Enabled: true},
+		"old":     {Name: "source", Enabled: false},
+		"new":     {Name: "cli"},
+	}) || !reflect.DeepEqual(got.Items, []child{{Name: "replacement"}}) || got.Count != 0 || got.Enabled ||
+		got.Empty == nil || len(got.Empty) != 0 || got.Label != "" || got.Small != 0 ||
+		got.Text != "cli text" || got.Delay != 250*time.Millisecond || got.APIKey.name != "CLI_SECRET" || got.Maybe != nil {
+		t.Fatalf("post-decode configuration = %#v", got)
+	}
+	if result.preCLI == result.final || !reflect.DeepEqual(result.preCLI, decoded.final) || len(result.overrides) != len(batch.overrides) {
+		t.Fatalf("result snapshots/contributions = pre:%p final:%p overrides:%d", result.preCLI, result.final, len(result.overrides))
+	}
+	if _, explicit := result.presence["/items/0/enabled"]; explicit {
+		t.Fatalf("replacement list inherited presence from its discarded item: %#v", result.presence)
+	}
+	if result.presence["/items/0/name"].location.SourceID != batch.overrides[2].source.ID ||
+		result.presence["/nested"].location.SourceID != "source-1" ||
+		result.origins["/items/0/name"].Layer != LayerCLI || result.origins["/nested/name"].Layer != LayerBase ||
+		result.origins["/nested/enabled"].Layer != LayerCLI || result.origins["/labels/default/name"].Layer != LayerDefault {
+		t.Fatalf("presence/origins = %#v / %#v", result.presence, result.origins)
+	}
+	if node, ok := documentAtPath(result.final, Keys("items").Index(0).Key("enabled")); !ok || node.Kind != document.Boolean || node.Text != "false" {
+		t.Fatalf("replacement list default projection = %#v", node)
+	}
+
+	got.Labels["new"] = child{Name: "mutated"}
+	result.overrides[0].value.Mapping[0].Value.Text = "changed"
+	if decoded.value.Interface().(config).Labels["old"].Name != "source" || batch.overrides[0].value.Mapping[0].Value.Text != "false" {
+		t.Fatal("post-decode result mutation reached the pre-CLI value or prepared batch")
+	}
+}
+
+func TestApplyDecodedOverridesRejectsSchemaErrorsWithoutPartialResult(t *testing.T) {
+	t.Parallel()
+	type config struct {
+		Nested struct {
+			Kept int `yaml:"kept"`
+		} `yaml:"nested"`
+		Count int `yaml:"count"`
+	}
+	input := parseDocumentForDecode(t, "nested: {kept: 1}\ncount: 2\n")
+	schema := mustSchemaFor[config](t)
+	decoded, issues := decodeConfiguration(schema, reflect.ValueOf(config{}), input)
+	if len(issues) != 0 {
+		t.Fatalf("decodeConfiguration() issues = %#v", issues)
+	}
+	for _, test := range []struct {
+		name     string
+		override Override
+		code     Code
+	}{
+		{name: "unknown nested field", override: Override{Path: Keys("nested"), Value: map[string]any{"unknown": 1}, Flag: "--nested"}, code: CodeDecodeUnknownField},
+		{name: "invalid type", override: Override{Path: Keys("count"), Value: "not an integer", Flag: "--count"}, code: CodeDecodeType},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			batch, diagnostics := preparePostStructuralOverrides(overridePreparationInput{root: input}, nil, []Override{test.override}, nil, defaultImportLimits())
+			if len(diagnostics) != 0 {
+				t.Fatalf("preparePostStructuralOverrides() diagnostics = %#v", diagnostics)
+			}
+			result, issues := applyDecodedOverrides(schema, decoded, batch, decodeContext{})
+			if len(issues) == 0 || issues[0].code != test.code {
+				t.Fatalf("decode issues = %#v, want code %q", issues, test.code)
+			}
+			if result.value.IsValid() || result.final != nil {
+				t.Fatalf("failed assignment returned a partial result: %#v", result)
+			}
+			original := decoded.value.Interface().(config)
+			if original.Count != 2 || original.Nested.Kept != 1 {
+				t.Fatal("failed assignment mutated the pre-CLI decoded value")
+			}
+		})
+	}
+}

internal/engine/records.go

@@ -105,6 +105,8 @@ const (
 	CodeImportRepeated      Code = "import.repeated"
 	CodeImportLimitExceeded Code = "import.limit_exceeded"
 	CodeImportVersion       Code = "import.version"
+	CodeSequenceInvalid     Code = "sequence.invalid"
+	CodeSequenceConflict    Code = "sequence.conflict"
 	CodeUnderlayVersion     Code = "underlay.version"
 
 	CodeOverlayInvalid       Code = "overlay.invalid"

internal/engine/recursive_merge.go

@@ -9,6 +9,7 @@ type recursiveMergeHooks struct {
 	added    func(Path, *document.Node)
 	combined func(Path, *document.Node)
 	replaced func(Path, *document.Node, *document.Node)
+	merge    func(Path, *document.Node, *document.Node) (*document.Node, bool)
 }
 
 // mergeRecursiveMappings changes an owned mapping and never aliases incoming
@@ -18,16 +19,31 @@ func mergeRecursiveMappings(target, incoming *document.Node, current Path, index
 		path := current.Key(entry.Key)
 		position := index.find(target, entry.Key)
 		if position < 0 {
-			cloned := entry
-			cloned.Value = document.Clone(entry.Value)
-			index.append(target, cloned)
+			if hooks.merge != nil {
+				if merged, handled := hooks.merge(path, nil, entry.Value); handled {
+					cloned := entry
+					cloned.Value = cloneMergeSubtree(merged, path, hooks.merge)
+					index.append(target, cloned)
+					continue
+				}
+			}
 			if hooks.added != nil {
 				hooks.added(path, entry.Value)
 			}
+			cloned := entry
+			cloned.Value = cloneMergeSubtree(entry.Value, path, hooks.merge)
+			index.append(target, cloned)
 			continue
 		}
 
 		existing := target.Mapping[position].Value
+		if hooks.merge != nil {
+			if merged, handled := hooks.merge(path, existing, entry.Value); handled {
+				target.Mapping[position] = entry
+				target.Mapping[position].Value = cloneMergeSubtree(merged, path, hooks.merge)
+				continue
+			}
+		}
 		if existing.Kind == document.Mapping && entry.Value.Kind == document.Mapping {
 			if hooks.combined != nil {
 				hooks.combined(path, entry.Value)
@@ -40,6 +56,28 @@ func mergeRecursiveMappings(target, incoming *document.Node, current Path, index
 			hooks.replaced(path, existing, entry.Value)
 		}
 		target.Mapping[position] = entry
-		target.Mapping[position].Value = document.Clone(entry.Value)
+		target.Mapping[position].Value = cloneMergeSubtree(entry.Value, path, hooks.merge)
 	}
 }
+
+// A copied mapping can contain collection operations even though its ancestor
+// has no retained mapping. Visit those operations with absent lower values.
+// Ordinary origin/replacement hooks already accounted for the whole subtree;
+// do not replay them for every descendant. Records inside sequences remain whole.
+func cloneMergeSubtree(incoming *document.Node, path Path, merge func(Path, *document.Node, *document.Node) (*document.Node, bool)) *document.Node {
+	if incoming == nil || incoming.Kind != document.Mapping || merge == nil {
+		return document.Clone(incoming)
+	}
+	cloned := *incoming
+	cloned.Mapping = make([]document.Entry, len(incoming.Mapping))
+	for index, entry := range incoming.Mapping {
+		childPath := path.Key(entry.Key)
+		value := entry.Value
+		if merged, handled := merge(childPath, nil, value); handled {
+			value = merged
+		}
+		entry.Value = cloneMergeSubtree(value, childPath, merge)
+		cloned.Mapping[index] = entry
+	}
+	return &cloned
+}

internal/engine/selected_overlay.go

@@ -41,7 +41,11 @@ func loadSelectedOverlayInto(source Source, context *FilesystemContext, main par
 	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) {
+func loadSelectedOverlayIntoWithVersion(source Source, context *FilesystemContext, main parsedSource, base *assemblyAccumulator, sources []SourceInfo, name string, rule *VersionRule, limits importLimits, versionState *sourceVersionState, policies ...sequencePolicy) ([]SourceInfo, []Diagnostic) {
+	var policy sequencePolicy
+	if len(policies) != 0 {
+		policy = policies[0]
+	}
 	if nativeContext(source, context) {
 		access, basePath, mainPath, diagnostic := nativeFilesystemAccess(source, context)
 		if diagnostic != nil {
@@ -50,7 +54,10 @@ func loadSelectedOverlayIntoWithVersion(source Source, context *FilesystemContex
 		if diagnostic := validateNativeDirectories(access, basePath, mainPath); diagnostic != nil {
 			return cloneSourceInfos(sources), []Diagnostic{*diagnostic}
 		}
-		return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState)
+		if len(policies) == 0 {
+			return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState)
+		}
+		return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState, policy)
 	}
 	rootPath, _, _, diagnostic := importFilesystem(source, context, main)
 	if diagnostic != nil {
@@ -62,14 +69,21 @@ func loadSelectedOverlayIntoWithVersion(source Source, context *FilesystemContex
 		value.Primary = nil
 		return cloneSourceInfos(sources), []Diagnostic{value}
 	}
-	return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState)
+	if len(policies) == 0 {
+		return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState)
+	}
+	return loadSelectedOverlayWithAccessAndVersion(access, base, sources, name, rule, limits, versionState, policy)
 }
 
 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) {
+func loadSelectedOverlayWithAccessAndVersion(access *filesystemAccess, base *assemblyAccumulator, sources []SourceInfo, name string, rule *VersionRule, limits importLimits, versionState *sourceVersionState, policies ...sequencePolicy) ([]SourceInfo, []Diagnostic) {
+	var policy sequencePolicy
+	if len(policies) != 0 {
+		policy = policies[0]
+	}
 	closed := false
 	defer func() {
 		if !closed {
@@ -131,18 +145,34 @@ func loadSelectedOverlayWithAccessAndVersion(access *filesystemAccess, base *ass
 	if base.current.inputNodes+nodeCount > limits.nodes {
 		return sources, []Diagnostic{importDiagnostic(CodeOverlayLimitExceeded, "selected overlay exceeds the aggregate node limit", overlayLocation)}
 	}
-	if diagnostics := overlayDirectiveDiagnostics(overlayRoot, Path{}); len(diagnostics) != 0 {
+	if diagnostics := overlayDirectiveDiagnostics(overlayRoot, Path{}, len(policies) != 0); len(diagnostics) != 0 {
 		return sources, diagnostics
 	}
-	overlayPayload := overlayRoot
-	if versionState != nil && versionState.mode != sourceVersionModeDefault {
-		processed, failures := versionState.process(overlayRoot, sourceVersionContribution, Path{}, sourceID, placementModeMapping)
-		if len(failures) != 0 {
-			return sources, failures
+	var processed sourceVersionProcessingResult
+	var failures []Diagnostic
+	if len(policies) != 0 {
+		if versionState != nil {
+			processed, failures = versionState.processWithDirectiveContext(
+				overlayRoot, sourceVersionContribution, Path{}, sourceID, placementModeMapping, rootDirectiveContextOverlay,
+			)
+		} else {
+			processed = processSourceVersionWithDirectiveContext(
+				overlayRoot, rule, sourceVersionContribution, Path{}, sourceVersionModeDefault, rootDirectiveContextOverlay,
+			)
+			failures = processed.diagnostics
+		}
+	} else {
+		if versionState != nil && versionState.mode != sourceVersionModeDefault {
+			processed, failures = versionState.process(overlayRoot, sourceVersionContribution, Path{}, sourceID, placementModeMapping)
+		} else {
+			processed = sourceVersionProcessingResult{payload: overlayRoot}
 		}
-		overlayPayload = processed.payload
 	}
-	if versionNode := fragmentVersionClaim(overlayPayload, rule); versionNode != nil {
+	if len(failures) != 0 {
+		return sources, failures
+	}
+	overlayPayload := processed.payload
+	if versionNode := fragmentVersionClaim(overlayPayload, rule); len(policies) == 0 && versionNode != nil {
 		location := publicLocation(versionNode.Location)
 		return sources, []Diagnostic{{
 			Code: CodeOverlayVersion, Severity: SeverityError, Path: rule.Path.clone(),
@@ -155,8 +185,26 @@ func loadSelectedOverlayWithAccessAndVersion(access *filesystemAccess, base *ass
 		return sources, []Diagnostic{importDiagnostic(CodeImportRead, "configuration root could not be closed after reading the selected overlay", nil)}
 	}
 
-	if diagnostics := base.applyOverlay(overlayPayload, nil, nil, LayerOverlay); len(diagnostics) != 0 {
-		return sources, diagnostics
+	var overlayDiagnostics []Diagnostic
+	if len(policies) != 0 {
+		overlayDiagnostics = base.applyOverlayWithCollectionPolicy(overlayPayload, nil, collectionPolicyScope{}, nil, LayerOverlay, policy, processed.sequences)
+	} else {
+		overlayDiagnostics = base.applyOverlay(overlayPayload, nil, nil, LayerOverlay)
+	}
+	if len(overlayDiagnostics) != 0 {
+		return sources, overlayDiagnostics
+	}
+	if len(policies) != 0 {
+		// The selected overlay retains one application with the actual item
+		// assignments. Raw list indexes cannot identify an upsert's destination.
+		application := base.current.applications[len(base.current.applications)-1]
+		if node := versionClaimFromApplication(application, rule); node != nil {
+			location := publicLocation(node.Location)
+			return sources, []Diagnostic{{
+				Code: CodeOverlayVersion, Severity: SeverityError, Path: rule.Path.clone(),
+				Message: "overlays cannot contribute to or replace the schema-version path", Primary: &location,
+			}}
+		}
 	}
 	base.current.inputBytes += int64(len(data))
 	base.current.inputNodes += nodeCount

internal/engine/selected_overlay_test.go

@@ -94,6 +94,263 @@ value: scalar
 	}
 }
 
+func TestLoadSelectedOverlayAppliesCollectionOperationsAndEvidence(t *testing.T) {
+	t.Parallel()
+	type item struct {
+		ID       string `yaml:"id"`
+		Value    string `yaml:"value"`
+		Children []item `yaml:"children"`
+	}
+	type config struct {
+		Items []item `yaml:"items"`
+	}
+	tests := []struct {
+		name    string
+		mode    string
+		overlay string
+		want    []item
+	}{
+		{
+			name: "append",
+			mode: "append",
+			overlay: `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+items: [{id: c, value: added}]
+`,
+			want: []item{{ID: "a", Value: "old"}, {ID: "b", Value: "kept"}, {ID: "c", Value: "added"}},
+		},
+		{
+			name: "upsert replaces complete records at retained positions",
+			mode: "upsert",
+			overlay: `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: upsert
+items: [{id: a, value: new}]
+`,
+			want: []item{{ID: "a", Value: "new"}, {ID: "b", Value: "kept"}},
+		},
+		{
+			name: "replace",
+			mode: "replace",
+			overlay: `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: replace
+items: [{id: c, value: replacement}]
+`,
+			want: []item{{ID: "c", Value: "replacement"}},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", "items: [{id: a, value: old, children: [{id: child}]}, {id: b, value: kept}]\n")
+			writeImportFile(t, directory, "overlays/testing.yml", test.overlay)
+			result, err := testLoad[config](File(mainPath), Options[config]{Overlay: "testing"})
+			if err != nil {
+				t.Fatal(err)
+			}
+			if len(result.Config.Items) != len(test.want) {
+				t.Fatalf("items = %#v, want %#v", result.Config.Items, test.want)
+			}
+			for index, want := range test.want {
+				if result.Config.Items[index].ID != want.ID || result.Config.Items[index].Value != want.Value {
+					t.Fatalf("items[%d] = %#v, want id %q value %q", index, result.Config.Items[index], want.ID, want.Value)
+				}
+			}
+			if _, found := result.Metadata().Lookup(Keys("configkit")); found {
+				t.Fatal("overlay collection controls reached application metadata")
+			}
+			if test.mode == "append" {
+				base, _ := result.Metadata().Lookup(Keys("items").Index(0).Key("value"))
+				added, _ := result.Metadata().Lookup(Keys("items").Index(2).Key("value"))
+				if base.Origin.Layer != LayerBase || added.Origin.Layer != LayerOverlay {
+					t.Fatalf("append origins = base %#v added %#v", base.Origin, added.Origin)
+				}
+				history := result.Metadata().History(Keys("items").Index(2).Key("value"))
+				if len(history) == 0 || history[len(history)-1].Origin.Layer != LayerOverlay {
+					t.Fatalf("append history = %#v", history)
+				}
+			}
+			if test.mode == "upsert" {
+				if _, found := result.Metadata().Lookup(Keys("items").Index(0).Key("children").Index(0)); found {
+					t.Fatal("upsert retained a discarded child")
+				}
+				history := result.Metadata().History(Keys("items").Index(0).Key("children").Index(0))
+				if len(history) < 2 {
+					t.Fatalf("discarded child history = %#v", history)
+				}
+			}
+		})
+	}
+}
+
+func TestLoadSelectedOverlayReconcilesPendingAndRetainedCollectionPolicy(t *testing.T) {
+	t.Parallel()
+	requireCode := func(t *testing.T, main, overlay string, code Code) {
+		t.Helper()
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", main)
+		writeImportFile(t, directory, "overlays/testing.yml", overlay)
+		_, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Overlay: "testing"})
+		var loadError *LoadError
+		if !errors.As(err, &loadError) || len(loadError.Diagnostics()) == 0 || loadError.Diagnostics()[0].Code != code {
+			t.Fatalf("load error = %#v, want %s", err, code)
+		}
+	}
+	t.Run("key only validates retained records", func(t *testing.T) {
+		requireCode(t, "items: [{id: duplicate}, {id: duplicate}]\n", `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+`, CodeSequenceConflict)
+	})
+
+	t.Run("mode only retains lower identity", func(t *testing.T) {
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+items: [{id: base}]
+`)
+		writeImportFile(t, directory, "overlays/testing.yml", `configkit:
+  sequences:
+    - destination: [items]
+      mode: append
+items: [{id: overlay}]
+`)
+		result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Overlay: "testing"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if !reflect.DeepEqual(result.Config.Items, []ordinarySequenceItem{{ID: "base"}, {ID: "overlay"}}) {
+			t.Fatalf("items = %#v", result.Config.Items)
+		}
+	})
+
+	t.Run("lower explicit mode remains active when overlay omits it", func(t *testing.T) {
+		directory := t.TempDir()
+		mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+items: [{id: base}]
+`)
+		writeImportFile(t, directory, "overlays/testing.yml", "items: [{id: overlay}]\n")
+		result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Overlay: "testing"})
+		if err != nil || !reflect.DeepEqual(result.Config.Items, []ordinarySequenceItem{{ID: "base"}, {ID: "overlay"}}) {
+			t.Fatalf("retained operation = %#v, %v", result, err)
+		}
+	})
+
+	t.Run("overlay identity must agree with retained identity", func(t *testing.T) {
+		requireCode(t, `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+items: [{id: base}]
+`, `configkit:
+  sequences:
+    - destination: [items]
+      key: slug
+items: [{id: overlay}]
+`, CodeSequenceConflict)
+	})
+
+	t.Run("replace accepts null and append rejects it", func(t *testing.T) {
+		for _, test := range []struct {
+			mode string
+			want Code
+		}{
+			{mode: "replace"},
+			{mode: "append", want: CodeSequenceInvalid},
+		} {
+			overlay := "configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: " + test.mode + "\nitems: null\n"
+			if test.want != "" {
+				requireCode(t, "items: [{id: base}]\n", overlay, test.want)
+				continue
+			}
+			directory := t.TempDir()
+			mainPath := writeImportFile(t, directory, "main.yml", "items: [{id: base}]\n")
+			writeImportFile(t, directory, "overlays/testing.yml", overlay)
+			result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Overlay: "testing"})
+			if err != nil || result.Config.Items != nil {
+				t.Fatalf("replace null = %#v, %v", result, err)
+			}
+		}
+	})
+
+	t.Run("empty contributions and kind mismatches", func(t *testing.T) {
+		for _, test := range []struct {
+			name, mode, value string
+			want              int
+			wantCode          Code
+		}{
+			{name: "append empty", mode: "append", value: "[]", want: 1},
+			{name: "upsert empty", mode: "upsert", value: "[]", want: 1},
+			{name: "replace empty", mode: "replace", value: "[]", want: 0},
+			{name: "append mapping", mode: "append", value: "{id: overlay}", wantCode: CodeSequenceInvalid},
+		} {
+			t.Run(test.name, func(t *testing.T) {
+				overlay := "configkit:\n  sequences:\n    - destination: [items]\n      key: id\n      mode: " + test.mode + "\nitems: " + test.value + "\n"
+				if test.wantCode != "" {
+					requireCode(t, "items: [{id: base}]\n", overlay, test.wantCode)
+					return
+				}
+				directory := t.TempDir()
+				mainPath := writeImportFile(t, directory, "main.yml", "items: [{id: base}]\n")
+				writeImportFile(t, directory, "overlays/testing.yml", overlay)
+				result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Overlay: "testing"})
+				if err != nil || len(result.Config.Items) != test.want {
+					t.Fatalf("%s result = %#v, %v", test.name, result, err)
+				}
+			})
+		}
+	})
+}
+
+func TestLoadSelectedOverlayKeepsCollectionPoliciesIndependent(t *testing.T) {
+	t.Parallel()
+	directory := t.TempDir()
+	mainPath := writeImportFile(t, directory, "main.yml", `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+      mode: append
+    - destination: [catalog, items]
+      key: id
+      mode: append
+items: [{id: base}]
+catalog: {items: [{id: catalog-base}]}
+`)
+	writeImportFile(t, directory, "overlays/testing.yml", `configkit:
+  sequences:
+    - destination: [items]
+      mode: upsert
+    - destination: [catalog, items]
+      mode: append
+items: [{id: base}]
+catalog: {items: [{id: catalog-overlay}]}
+`)
+	result, err := testLoad[ordinarySequenceConfig](File(mainPath), Options[ordinarySequenceConfig]{Overlay: "testing"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reflect.DeepEqual(result.Config.Items, []ordinarySequenceItem{{ID: "base"}}) ||
+		!reflect.DeepEqual(result.Config.Catalog.Items, []ordinarySequenceItem{{ID: "catalog-base"}, {ID: "catalog-overlay"}}) {
+		t.Fatalf("independent overlay policies = items %#v, catalog %#v", result.Config.Items, result.Config.Catalog.Items)
+	}
+}
+
 func TestLoadOverlaySelectionUsesOneFixedYAMLFile(t *testing.T) {
 	directory := t.TempDir()
 	mainPath := writeImportFile(t, directory, "main.yml", "settings: {kept: base}\n")

internal/engine/sequence_combine.go

@@ -0,0 +1,256 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+type sequenceCombinationContext struct {
+	destination Path
+}
+
+type sequenceItemProjection struct {
+	inputIndex  int
+	outputIndex int
+}
+
+type sequenceItemReplacement struct {
+	lowerIndex  int
+	higherIndex int
+	outputIndex int
+}
+
+type sequenceCombinationResult struct {
+	value          *document.Node
+	lowerItems     []sequenceItemProjection
+	higherItems    []sequenceItemProjection
+	replacements   []sequenceItemReplacement
+	appendedHigher []int
+	discardedLower []int
+}
+
+func combineSequence(
+	lower, higher *document.Node,
+	policy collectionPolicyResolution,
+	context sequenceCombinationContext,
+) (sequenceCombinationResult, []Diagnostic) {
+	if higher == nil {
+		return unchangedSequenceValue(lower), nil
+	}
+	switch policy.operation {
+	case sequenceModeReplace:
+		return replaceSequence(lower, higher, policy.effectiveIdentityFields, context)
+	case sequenceModeAppend, sequenceModeUpsert:
+		return combineIdentifiedSequences(lower, higher, policy.operation, policy.effectiveIdentityFields, context)
+	default:
+		return sequenceCombinationResult{}, []Diagnostic{sequenceCombinationDiagnostic(
+			context.destination, "sequence operation is invalid", higher,
+		)}
+	}
+}
+
+func unchangedSequenceValue(lower *document.Node) sequenceCombinationResult {
+	result := sequenceCombinationResult{value: document.Clone(lower)}
+	if lower != nil && lower.Kind == document.Sequence {
+		result.lowerItems = sequenceItemProjections(len(lower.Sequence), 0)
+	}
+	return result
+}
+
+func replaceSequence(
+	lower, higher *document.Node,
+	identityFields []string,
+	context sequenceCombinationContext,
+) (sequenceCombinationResult, []Diagnostic) {
+	if higher.Kind == document.Sequence && len(identityFields) != 0 {
+		if _, diagnostics := validateSequenceIdentity(higher, context.destination, identityFields, sequenceCombinationIdentityCodes); len(diagnostics) != 0 {
+			return sequenceCombinationResult{}, diagnostics
+		}
+	}
+	result := sequenceCombinationResult{value: document.Clone(higher)}
+	if higher.Kind == document.Sequence {
+		result.higherItems = sequenceItemProjections(len(higher.Sequence), 0)
+	}
+	if lower != nil && lower.Kind == document.Sequence {
+		result.discardedLower = sequenceIndexes(len(lower.Sequence))
+	}
+	return result, nil
+}
+
+func combineIdentifiedSequences(
+	lower, higher *document.Node,
+	operation sequenceMode,
+	identityFields []string,
+	context sequenceCombinationContext,
+) (sequenceCombinationResult, []Diagnostic) {
+	if higher.Kind != document.Sequence {
+		return sequenceCombinationResult{}, []Diagnostic{sequenceCombinationDiagnostic(
+			context.destination, "append and upsert require a sequence contribution", higher,
+		)}
+	}
+	if lower != nil && lower.Kind != document.Sequence {
+		return sequenceCombinationResult{}, []Diagnostic{sequenceCombinationDiagnostic(
+			context.destination, "append and upsert require a lower sequence or an absent lower value", lower,
+		)}
+	}
+	if len(identityFields) == 0 {
+		return sequenceCombinationResult{}, []Diagnostic{sequenceCombinationDiagnostic(
+			context.destination, "append and upsert require an identity definition", higher,
+		)}
+	}
+
+	higherIndex, diagnostics := validateSequenceIdentity(higher, context.destination, identityFields, sequenceCombinationIdentityCodes)
+	if len(diagnostics) != 0 {
+		return sequenceCombinationResult{}, diagnostics
+	}
+	var lowerIndex map[string]sequenceIdentityRecord
+	if lower != nil {
+		lowerIndex, diagnostics = validateSequenceIdentity(lower, context.destination, identityFields, sequenceCombinationIdentityCodes)
+		if len(diagnostics) != 0 {
+			return sequenceCombinationResult{}, diagnostics
+		}
+	}
+	if operation == sequenceModeAppend {
+		if duplicate := duplicateAcrossSequenceContributions(lowerIndex, higherIndex, context.destination); duplicate != nil {
+			return sequenceCombinationResult{}, []Diagnostic{*duplicate}
+		}
+	}
+
+	if operation == sequenceModeAppend {
+		return appendSequenceItems(lower, higher), nil
+	}
+	if operation == sequenceModeUpsert {
+		return upsertSequenceItems(lower, higher, lowerIndex, higherIndex), nil
+	}
+	return sequenceCombinationResult{}, []Diagnostic{sequenceCombinationDiagnostic(
+		context.destination, "sequence operation is invalid", higher,
+	)}
+}
+
+func appendSequenceItems(lower, higher *document.Node) sequenceCombinationResult {
+	lowerCount := 0
+	if lower != nil {
+		lowerCount = len(lower.Sequence)
+	}
+	items := make([]*document.Node, 0, lowerCount+len(higher.Sequence))
+	if lower != nil {
+		items = append(items, lower.Sequence...)
+	}
+	items = append(items, higher.Sequence...)
+	return sequenceCombinationResult{
+		value:          cloneSequenceWithItems(higher, items),
+		lowerItems:     sequenceItemProjections(lowerCount, 0),
+		higherItems:    sequenceItemProjections(len(higher.Sequence), lowerCount),
+		appendedHigher: sequenceIndexes(len(higher.Sequence)),
+	}
+}
+
+func upsertSequenceItems(
+	lower, higher *document.Node,
+	lowerIndex, higherIndex map[string]sequenceIdentityRecord,
+) sequenceCombinationResult {
+	lowerCount := 0
+	var lowerItems []*document.Node
+	if lower != nil {
+		lowerCount = len(lower.Sequence)
+		lowerItems = lower.Sequence
+	}
+	matchedLower := make(map[int]sequenceIdentityRecord, len(higherIndex))
+	matchedLowerByHigher := make([]int, len(higher.Sequence))
+	for index := range matchedLowerByHigher {
+		matchedLowerByHigher[index] = -1
+	}
+	for tuple, incoming := range higherIndex {
+		if retained, exists := lowerIndex[tuple]; exists {
+			matchedLower[retained.index] = incoming
+			matchedLowerByHigher[incoming.index] = retained.index
+		}
+	}
+	items := make([]*document.Node, lowerCount, lowerCount+len(higher.Sequence))
+	result := sequenceCombinationResult{
+		lowerItems:  make([]sequenceItemProjection, 0, lowerCount-len(matchedLower)),
+		higherItems: sequenceItemProjections(len(higher.Sequence), 0),
+	}
+	for lowerPosition, item := range lowerItems {
+		if incoming, replaced := matchedLower[lowerPosition]; replaced {
+			items[lowerPosition] = higher.Sequence[incoming.index]
+			result.higherItems[incoming.index].outputIndex = lowerPosition
+			result.replacements = append(result.replacements, sequenceItemReplacement{
+				lowerIndex: lowerPosition, higherIndex: incoming.index, outputIndex: lowerPosition,
+			})
+			continue
+		}
+		items[lowerPosition] = item
+		result.lowerItems = append(result.lowerItems, sequenceItemProjection{inputIndex: lowerPosition, outputIndex: lowerPosition})
+	}
+	for higherPosition := range higher.Sequence {
+		if matchedLowerByHigher[higherPosition] >= 0 {
+			continue
+		}
+		outputIndex := len(items)
+		items = append(items, higher.Sequence[higherPosition])
+		result.appendedHigher = append(result.appendedHigher, higherPosition)
+		result.higherItems[higherPosition].outputIndex = outputIndex
+	}
+	result.value = cloneSequenceWithItems(higher, items)
+	return result
+}
+
+func duplicateAcrossSequenceContributions(
+	lowerIndex, higherIndex map[string]sequenceIdentityRecord,
+	path Path,
+) *Diagnostic {
+	higherTuples := make([]string, len(higherIndex))
+	for tuple, record := range higherIndex {
+		higherTuples[record.index] = tuple
+	}
+	for _, tuple := range higherTuples {
+		if lower, exists := lowerIndex[tuple]; exists {
+			higher := higherIndex[tuple]
+			primary := publicLocation(lower.location)
+			related := publicLocation(higher.location)
+			return &Diagnostic{
+				Code: CodeSequenceConflict, Severity: SeverityError, Path: path.clone(),
+				Message: "sequence contributions contain a duplicate identity",
+				Primary: &primary, Related: []Location{related},
+			}
+		}
+	}
+	return nil
+}
+
+func cloneSequenceWithItems(template *document.Node, items []*document.Node) *document.Node {
+	cloned := *template
+	cloned.Mapping = nil
+	cloned.Sequence = make([]*document.Node, len(items))
+	for index, item := range items {
+		cloned.Sequence[index] = document.Clone(item)
+	}
+	return &cloned
+}
+
+func sequenceItemProjections(length, outputOffset int) []sequenceItemProjection {
+	projections := make([]sequenceItemProjection, length)
+	for index := range projections {
+		projections[index] = sequenceItemProjection{inputIndex: index, outputIndex: index + outputOffset}
+	}
+	return projections
+}
+
+func sequenceIndexes(length int) []int {
+	indexes := make([]int, length)
+	for index := range indexes {
+		indexes[index] = index
+	}
+	return indexes
+}
+
+func sequenceCombinationDiagnostic(path Path, message string, node *document.Node) Diagnostic {
+	var primary *Location
+	if node != nil {
+		location := publicLocation(node.Location)
+		primary = &location
+	}
+	return Diagnostic{Code: CodeSequenceInvalid, Severity: SeverityError, Path: path.clone(), Message: message, Primary: primary}
+}
+
+var sequenceCombinationIdentityCodes = sequenceIdentityDiagnosticCodes{
+	invalid: CodeSequenceInvalid, conflict: CodeSequenceConflict,
+}

internal/engine/sequence_combine_bench_test.go

@@ -0,0 +1,42 @@
+package engine
+
+import (
+	"strconv"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func BenchmarkSequenceMixedUpsert(b *testing.B) {
+	for _, size := range []int{128, 512, 2048} {
+		b.Run(strconv.Itoa(size), func(b *testing.B) {
+			lower := benchmarkSequenceRecords(0, size, "lower")
+			higher := benchmarkSequenceRecords(size/2, size, "higher")
+			context := sequenceCombinationContext{destination: Keys("items")}
+			identityFields := []string{"id"}
+			b.ReportAllocs()
+			b.ResetTimer()
+			for range b.N {
+				if _, diagnostics := combineIdentifiedSequences(
+					lower, higher, sequenceModeUpsert, identityFields, context,
+				); len(diagnostics) != 0 {
+					b.Fatal(diagnostics)
+				}
+			}
+		})
+	}
+}
+
+func benchmarkSequenceRecords(start, count int, value string) *document.Node {
+	items := make([]*document.Node, count)
+	for index := range count {
+		items[index] = &document.Node{
+			Kind: document.Mapping,
+			Mapping: []document.Entry{
+				{Key: "id", Value: &document.Node{Kind: document.String, Text: "item-" + strconv.Itoa(start+index)}},
+				{Key: "value", Value: &document.Node{Kind: document.String, Text: value}},
+			},
+		}
+	}
+	return &document.Node{Kind: document.Sequence, Sequence: items}
+}

internal/engine/sequence_combine_test.go

@@ -0,0 +1,302 @@
+package engine
+
+import (
+	"reflect"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestCombineSequenceOperationsAndItemEvidence(t *testing.T) {
+	tests := []struct {
+		name             string
+		lower            string
+		higher           string
+		operation        sequenceMode
+		want             []string
+		wantLower        []sequenceItemProjection
+		wantHigher       []sequenceItemProjection
+		wantReplacements []sequenceItemReplacement
+		wantAppended     []int
+		wantDiscarded    []int
+	}{
+		{
+			name:  "replace uses only higher records",
+			lower: "items: [{id: a}, {id: b}]\n", higher: "items: [{id: b, text: revised}]\n",
+			operation: sequenceModeReplace, want: []string{"b"},
+			wantHigher: []sequenceItemProjection{{inputIndex: 0, outputIndex: 0}}, wantDiscarded: []int{0, 1},
+		},
+		{
+			name:  "append retains then appends",
+			lower: "items: [{id: a}, {id: b}]\n", higher: "items: [{id: c}]\n",
+			operation: sequenceModeAppend, want: []string{"a", "b", "c"},
+			wantLower:  []sequenceItemProjection{{inputIndex: 0, outputIndex: 0}, {inputIndex: 1, outputIndex: 1}},
+			wantHigher: []sequenceItemProjection{{inputIndex: 0, outputIndex: 2}}, wantAppended: []int{0},
+		},
+		{
+			name:      "upsert replaces whole records in place and appends new records",
+			lower:     "items: [{id: a, text: old}, {id: b}, {id: c, remove: true}]\n",
+			higher:    "items: [{id: c, text: revised}, {id: a, text: revised}, {id: d}]\n",
+			operation: sequenceModeUpsert, want: []string{"a", "b", "c", "d"},
+			wantLower:        []sequenceItemProjection{{inputIndex: 1, outputIndex: 1}},
+			wantHigher:       []sequenceItemProjection{{inputIndex: 0, outputIndex: 2}, {inputIndex: 1, outputIndex: 0}, {inputIndex: 2, outputIndex: 3}},
+			wantReplacements: []sequenceItemReplacement{{lowerIndex: 0, higherIndex: 1, outputIndex: 0}, {lowerIndex: 2, higherIndex: 0, outputIndex: 2}},
+			wantAppended:     []int{2},
+		},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			lower := sequenceFromYAML(t, test.lower)
+			higher := sequenceFromYAML(t, test.higher)
+			policy := sequenceCombinationPolicy(test.operation, "id")
+			result, diagnostics := combineSequence(lower, higher, policy, sequenceCombinationContext{destination: Keys("items")})
+			if len(diagnostics) != 0 {
+				t.Fatalf("combination diagnostics = %#v", diagnostics)
+			}
+			if got := sequenceIdentityValues(result.value, "id"); !reflect.DeepEqual(got, test.want) {
+				t.Fatalf("combined IDs = %#v, want %#v", got, test.want)
+			}
+			if !reflect.DeepEqual(result.lowerItems, test.wantLower) || !reflect.DeepEqual(result.higherItems, test.wantHigher) || !reflect.DeepEqual(result.replacements, test.wantReplacements) || !reflect.DeepEqual(result.appendedHigher, test.wantAppended) || !reflect.DeepEqual(result.discardedLower, test.wantDiscarded) {
+				t.Fatalf("item evidence = %#v", result)
+			}
+		})
+	}
+}
+
+func TestCombineSequenceDistinguishesAbsenceFromNullAndKindMismatch(t *testing.T) {
+	policy := sequenceCombinationPolicy(sequenceModeAppend, "id")
+	retained := sequenceFromYAML(t, "items: [{id: lower}]\n")
+	unchanged, diagnostics := combineSequence(retained, nil, policy, sequenceCombinationContext{destination: Keys("items")})
+	if len(diagnostics) != 0 || !reflect.DeepEqual(sequenceIdentityValues(unchanged.value, "id"), []string{"lower"}) || len(unchanged.lowerItems) != 1 {
+		t.Fatalf("absent higher value changed lower sequence: %#v, %#v", unchanged, diagnostics)
+	}
+
+	tests := []struct {
+		name   string
+		lower  string
+		higher string
+	}{
+		{name: "null higher value", lower: "items: [{id: lower}]\n", higher: "items: null\n"},
+		{name: "mapping higher value", lower: "items: [{id: lower}]\n", higher: "items: {id: higher}\n"},
+		{name: "null lower value", lower: "items: null\n", higher: "items: []\n"},
+		{name: "scalar lower value", lower: "items: blocked\n", higher: "items: []\n"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			result, issues := combineSequence(sequenceFromYAML(t, test.lower), sequenceFromYAML(t, test.higher), policy, sequenceCombinationContext{destination: Keys("items")})
+			if result.value != nil || len(issues) != 1 || issues[0].Code != CodeSequenceInvalid || issues[0].Path.String() != "/items" {
+				t.Fatalf("kind mismatch result = %#v, %#v", result, issues)
+			}
+		})
+	}
+
+	for _, operation := range []sequenceMode{sequenceModeAppend, sequenceModeUpsert} {
+		result, issues := combineSequence(nil, sequenceFromYAML(t, "items: null\n"), sequenceCombinationPolicy(operation, "id"), sequenceCombinationContext{destination: Keys("items")})
+		if result.value != nil || len(issues) != 1 || issues[0].Code != CodeSequenceInvalid {
+			t.Fatalf("null incoming value under operation %d = %#v, %#v", operation, result, issues)
+		}
+	}
+}
+
+func TestReplaceSequenceAllowsNullAndNonSequenceValues(t *testing.T) {
+	for _, test := range []struct {
+		name     string
+		higher   string
+		wantKind document.Kind
+	}{
+		{name: "null", higher: "items: null\n", wantKind: document.Null},
+		{name: "mapping", higher: "items: {value: replacement}\n", wantKind: document.Mapping},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			lower := sequenceFromYAML(t, "items: [{id: lower}]\n")
+			higher := sequenceFromYAML(t, test.higher)
+			result, diagnostics := combineSequence(lower, higher, sequenceCombinationPolicy(sequenceModeReplace), sequenceCombinationContext{destination: Keys("items")})
+			if len(diagnostics) != 0 || result.value == nil || result.value.Kind != test.wantKind || !reflect.DeepEqual(result.discardedLower, []int{0}) {
+				t.Fatalf("replacement result = %#v, %#v", result, diagnostics)
+			}
+		})
+	}
+	result, diagnostics := combineSequence(sequenceFromYAML(t, "items: null\n"), sequenceFromYAML(t, "items: [{id: new}]\n"), sequenceCombinationPolicy(sequenceModeReplace), sequenceCombinationContext{destination: Keys("items")})
+	if len(diagnostics) != 0 || !reflect.DeepEqual(sequenceIdentityValues(result.value, "id"), []string{"new"}) {
+		t.Fatalf("replacement over explicit lower null = %#v, %#v", result, diagnostics)
+	}
+}
+
+func TestCombineSequenceRequiresIdentityForAppendAndUpsertEvenWhenEmpty(t *testing.T) {
+	for _, operation := range []sequenceMode{sequenceModeAppend, sequenceModeUpsert} {
+		result, diagnostics := combineSequence(nil, sequenceFromYAML(t, "items: []\n"), sequenceCombinationPolicy(operation), sequenceCombinationContext{destination: Keys("items")})
+		if result.value != nil || len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid {
+			t.Fatalf("empty input bypassed identity requirement for operation %d: %#v, %#v", operation, result, diagnostics)
+		}
+	}
+	for _, operation := range []sequenceMode{sequenceModeAppend, sequenceModeUpsert} {
+		result, diagnostics := combineSequence(nil, sequenceFromYAML(t, "items: [{name: no-id}]\n"), sequenceCombinationPolicy(operation, "id"), sequenceCombinationContext{destination: Keys("items")})
+		if result.value != nil || len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != "/items/0/id" {
+			t.Fatalf("missing identity for operation %d = %#v, %#v", operation, result, diagnostics)
+		}
+	}
+}
+
+func TestCombineSequenceValidatesDuplicatesWithinEachContributionInEveryMode(t *testing.T) {
+	duplicate := "items: [{id: same}, {id: same}]\n"
+	for _, operation := range []sequenceMode{sequenceModeReplace, sequenceModeAppend, sequenceModeUpsert} {
+		_, diagnostics := combineSequence(nil, sequenceFromYAML(t, duplicate), sequenceCombinationPolicy(operation, "id"), sequenceCombinationContext{destination: Keys("items")})
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict {
+			t.Fatalf("higher duplicate under operation %d = %#v", operation, diagnostics)
+		}
+	}
+	for _, operation := range []sequenceMode{sequenceModeAppend, sequenceModeUpsert} {
+		_, diagnostics := combineSequence(sequenceFromYAML(t, duplicate), sequenceFromYAML(t, "items: [{id: other}]\n"), sequenceCombinationPolicy(operation, "id"), sequenceCombinationContext{destination: Keys("items")})
+		if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict {
+			t.Fatalf("lower duplicate under operation %d = %#v", operation, diagnostics)
+		}
+	}
+}
+
+func TestAppendSequenceRejectsDuplicatesAcrossContributions(t *testing.T) {
+	const identityCanary = "identity-canary-64"
+	lower := sequenceFromYAML(t, "items: [{id: "+identityCanary+"}]\n")
+	higher := sequenceFromYAML(t, "items: [{id: "+identityCanary+"}]\n")
+	_, diagnostics := combineSequence(lower, higher, sequenceCombinationPolicy(sequenceModeAppend, "id"), sequenceCombinationContext{destination: Keys("items")})
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict || diagnostics[0].Path.String() != "/items" || diagnostics[0].Primary == nil || len(diagnostics[0].Related) != 1 {
+		t.Fatalf("cross-contribution duplicate = %#v", diagnostics)
+	}
+	if strings.Contains(diagnostics[0].Message, identityCanary) {
+		t.Fatalf("identity value leaked in diagnostic: %#v", diagnostics[0])
+	}
+}
+
+func TestCombineSequenceReplacementResetsLowerIdentity(t *testing.T) {
+	lower := sequenceFromYAML(t, "items: [{id: old}]\n")
+	higher := sequenceFromYAML(t, "items: [{name: new}]\n")
+	policy := sequenceCombinationPolicy(sequenceModeReplace, "name")
+	result, diagnostics := combineSequence(lower, higher, policy, sequenceCombinationContext{destination: Keys("items")})
+	if len(diagnostics) != 0 || !reflect.DeepEqual(sequenceIdentityValues(result.value, "name"), []string{"new"}) || !reflect.DeepEqual(result.discardedLower, []int{0}) {
+		t.Fatalf("replacement applied obsolete identity: %#v, %#v", result, diagnostics)
+	}
+}
+
+func TestCombineSequenceDifferentIdentityDeclarationsConflict(t *testing.T) {
+	declarations := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [items]
+      key: id
+    - destination: [items]
+      key: name
+`, rootDirectiveContextSource).sequences
+	if _, diagnostics := resolveCollectionPolicy(Keys("items"), declarations, nil, nil); len(diagnostics) != 1 || diagnostics[0].Code != CodeSequenceConflict {
+		t.Fatalf("different collection key declarations = %#v", diagnostics)
+	}
+}
+
+func TestCombineSequenceEmptyInputsAndStableOrder(t *testing.T) {
+	for _, operation := range []sequenceMode{sequenceModeAppend, sequenceModeUpsert} {
+		lower := sequenceFromYAML(t, "items: [{id: a}, {id: b}]\n")
+		empty := sequenceFromYAML(t, "items: []\n")
+		result, diagnostics := combineSequence(lower, empty, sequenceCombinationPolicy(operation, "id"), sequenceCombinationContext{destination: Keys("items")})
+		if len(diagnostics) != 0 || !reflect.DeepEqual(sequenceIdentityValues(result.value, "id"), []string{"a", "b"}) {
+			t.Fatalf("empty higher sequence under operation %d = %#v, %#v", operation, result, diagnostics)
+		}
+	}
+	result, diagnostics := combineSequence(nil, sequenceFromYAML(t, "items: []\n"), sequenceCombinationPolicy(sequenceModeReplace, "id"), sequenceCombinationContext{destination: Keys("items")})
+	if len(diagnostics) != 0 || result.value == nil || result.value.Kind != document.Sequence || len(result.value.Sequence) != 0 {
+		t.Fatalf("explicit replacement with empty input = %#v, %#v", result, diagnostics)
+	}
+}
+
+func TestCombineSequenceInitializesAbsentLowerCollection(t *testing.T) {
+	higher := sequenceFromYAML(t, "items: [{id: first}, {id: second}]\n")
+	for _, operation := range []sequenceMode{sequenceModeReplace, sequenceModeAppend, sequenceModeUpsert} {
+		result, diagnostics := combineSequence(nil, higher, sequenceCombinationPolicy(operation, "id"), sequenceCombinationContext{destination: Keys("items")})
+		if len(diagnostics) != 0 || !reflect.DeepEqual(sequenceIdentityValues(result.value, "id"), []string{"first", "second"}) {
+			t.Fatalf("absent lower collection under operation %d = %#v, %#v", operation, result, diagnostics)
+		}
+	}
+}
+
+func TestCombineSequenceClonesInputsAndDoesNotMutatePolicy(t *testing.T) {
+	for _, test := range []struct {
+		name      string
+		operation sequenceMode
+	}{
+		{name: "replace", operation: sequenceModeReplace},
+		{name: "append", operation: sequenceModeAppend},
+		{name: "upsert", operation: sequenceModeUpsert},
+	} {
+		t.Run(test.name, func(t *testing.T) {
+			lower := sequenceFromYAML(t, "items: [{id: a, text: original}]\n")
+			higherID := "b"
+			if test.operation == sequenceModeUpsert {
+				higherID = "a"
+			}
+			higher := sequenceFromYAML(t, "items: [{id: "+higherID+", text: incoming}]\n")
+			policy := sequenceCombinationPolicy(test.operation, "id")
+			policyCopy := append([]string(nil), policy.effectiveIdentityFields...)
+			result, diagnostics := combineSequence(lower, higher, policy, sequenceCombinationContext{destination: Keys("items")})
+			if len(diagnostics) != 0 {
+				t.Fatal(diagnostics)
+			}
+			for _, item := range result.value.Sequence {
+				for entryIndex := range item.Mapping {
+					if item.Mapping[entryIndex].Key == "text" {
+						item.Mapping[entryIndex].Value.Text = "changed"
+					}
+				}
+			}
+			if lower.Sequence[0].Mapping[1].Value.Text != "original" || higher.Sequence[0].Mapping[1].Value.Text != "incoming" {
+				t.Fatal("combined result aliases a mutable input node")
+			}
+			if !reflect.DeepEqual(policy.effectiveIdentityFields, policyCopy) {
+				t.Fatal("combination mutated the resolved policy")
+			}
+		})
+	}
+}
+
+func TestCombineSequenceEquivalentIdentityFieldSets(t *testing.T) {
+	lower := sequenceFromYAML(t, "items: [{id: a, namespace: one}]\n")
+	higher := sequenceFromYAML(t, "items: [{namespace: one, id: b}]\n")
+	policy, diagnostics := resolveCollectionPolicy(Keys("items"), extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [items]
+      key: [namespace, id, id]
+`, rootDirectiveContextSource).sequences, nil, nil)
+	if len(diagnostics) != 0 {
+		t.Fatal(diagnostics)
+	}
+	result, diagnostics := combineSequence(lower, higher, policy, sequenceCombinationContext{destination: Keys("items")})
+	if len(diagnostics) != 0 || !reflect.DeepEqual(sequenceIdentityValues(result.value, "id"), []string{"a", "b"}) {
+		t.Fatalf("equivalent identity policy failed: %#v, %#v", result, diagnostics)
+	}
+}
+
+func sequenceCombinationPolicy(operation sequenceMode, fields ...string) collectionPolicyResolution {
+	normalized, _ := normalizeSequenceIdentityFields(fields)
+	return collectionPolicyResolution{operation: operation, effectiveIdentityFields: normalized}
+}
+
+func sequenceFromYAML(t *testing.T, input string) *document.Node {
+	t.Helper()
+	parsed := parsePolicyNode(t, input)
+	if len(parsed.Mapping) != 1 || parsed.Mapping[0].Key != "items" {
+		t.Fatalf("sequence fixture root = %#v", parsed.Mapping)
+	}
+	return parsed.Mapping[0].Value
+}
+
+func sequenceIdentityValues(sequence *document.Node, field string) []string {
+	if sequence == nil || sequence.Kind != document.Sequence {
+		return nil
+	}
+	values := make([]string, len(sequence.Sequence))
+	for index, item := range sequence.Sequence {
+		for _, entry := range item.Mapping {
+			if entry.Key == field {
+				values[index] = entry.Value.Text
+				break
+			}
+		}
+	}
+	return values
+}

internal/engine/sequence_declaration.go

@@ -0,0 +1,158 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+type sequenceMode uint8
+
+const (
+	sequenceModeReplace sequenceMode = iota + 1
+	sequenceModeAppend
+	sequenceModeUpsert
+)
+
+type sequenceDeclarationSpec struct {
+	path                Path
+	location            Location
+	destination         Path
+	destinationLocation Location
+	identityFields      []string
+	identityPresent     bool
+	identityLocation    *Location
+	mode                sequenceMode
+	modePresent         bool
+	modeLocation        *Location
+}
+
+func parseSequenceDeclarationDirective(node *document.Node, directivePath Path) ([]sequenceDeclarationSpec, []Diagnostic) {
+	if node == nil || node.Kind != document.Sequence {
+		return nil, []Diagnostic{sequenceDeclarationDiagnostic(directivePath, "sequences must be a sequence", node)}
+	}
+	declarations := make([]sequenceDeclarationSpec, 0, len(node.Sequence))
+	var diagnostics []Diagnostic
+	for index, declarationNode := range node.Sequence {
+		declaration, issues := parseSequenceDeclarationSpec(declarationNode, directivePath.Index(index))
+		if len(issues) != 0 {
+			diagnostics = append(diagnostics, issues...)
+			continue
+		}
+		declarations = append(declarations, declaration)
+	}
+	return declarations, canonicalDiagnostics(diagnostics)
+}
+
+func parseSequenceDeclarationSpec(node *document.Node, declarationPath Path) (sequenceDeclarationSpec, []Diagnostic) {
+	if node == nil || node.Kind != document.Mapping {
+		return sequenceDeclarationSpec{}, []Diagnostic{sequenceDeclarationDiagnostic(declarationPath, "sequence declaration must be a mapping", node)}
+	}
+	declaration := sequenceDeclarationSpec{
+		path:     declarationPath.clone(),
+		location: publicLocation(node.Location),
+	}
+	destinationPresent := false
+	for _, entry := range node.Mapping {
+		fieldPath := declarationPath.Key(entry.Key)
+		switch entry.Key {
+		case "destination":
+			destinationPresent = true
+			destination, diagnostic := parseImportDestination(entry.Value, fieldPath)
+			if diagnostic != nil {
+				diagnostic.Code = CodeSequenceInvalid
+				return sequenceDeclarationSpec{}, []Diagnostic{*diagnostic}
+			}
+			declaration.destination = destination
+			declaration.destinationLocation = publicLocation(entry.Value.Location)
+		case "key":
+			fields, locations, errIndex, valid := parseSequenceIdentityFieldSet(entry.Value)
+			if !valid {
+				badPath := fieldPath
+				badNode := entry.Value
+				message := "key must be a string or nonempty list of strings"
+				if errIndex >= 0 && entry.Value != nil {
+					badPath = fieldPath.Index(errIndex)
+					if errIndex < len(entry.Value.Sequence) {
+						badNode = entry.Value.Sequence[errIndex]
+					}
+				}
+				return sequenceDeclarationSpec{}, []Diagnostic{sequenceDeclarationDiagnostic(badPath, message, badNode)}
+			}
+			declaration.identityFields = fields
+			declaration.identityPresent = true
+			location := publicLocation(entry.Value.Location)
+			if len(locations) != 0 {
+				location = publicLocation(locations[0])
+			}
+			declaration.identityLocation = &location
+		case "mode":
+			if entry.Value == nil || entry.Value.Kind != document.String {
+				return sequenceDeclarationSpec{}, []Diagnostic{sequenceDeclarationDiagnostic(fieldPath, "mode must be replace, append, or upsert", entry.Value)}
+			}
+			mode, ok := parseSequenceMode(entry.Value.Text)
+			if !ok {
+				return sequenceDeclarationSpec{}, []Diagnostic{sequenceDeclarationDiagnostic(fieldPath, "mode must be replace, append, or upsert", entry.Value)}
+			}
+			declaration.mode = mode
+			declaration.modePresent = true
+			location := publicLocation(entry.Value.Location)
+			declaration.modeLocation = &location
+		default:
+			return sequenceDeclarationSpec{}, []Diagnostic{sequenceDeclarationDiagnostic(fieldPath, "sequence declaration field is not recognized", entry.Value)}
+		}
+	}
+	if !destinationPresent {
+		return sequenceDeclarationSpec{}, []Diagnostic{sequenceDeclarationDiagnostic(declarationPath.Key("destination"), "sequence declaration requires a destination", node)}
+	}
+	return declaration, nil
+}
+
+func parseSequenceIdentityFieldSet(node *document.Node) ([]string, []document.Location, int, bool) {
+	if node == nil {
+		return nil, nil, -1, false
+	}
+	var fields []string
+	var locations []document.Location
+	switch node.Kind {
+	case document.String:
+		fields = []string{node.Text}
+		locations = []document.Location{node.Location}
+	case document.Sequence:
+		if len(node.Sequence) == 0 {
+			return nil, nil, -1, false
+		}
+		for index, member := range node.Sequence {
+			if member == nil || member.Kind != document.String {
+				return nil, nil, index, false
+			}
+			fields = append(fields, member.Text)
+			locations = append(locations, member.Location)
+		}
+	default:
+		return nil, nil, -1, false
+	}
+	normalized, err := normalizeSequenceIdentityFields(fields)
+	if err != nil {
+		return nil, nil, -1, false
+	}
+	return normalized, locations, -1, true
+}
+
+func parseSequenceMode(value string) (sequenceMode, bool) {
+	switch value {
+	case "replace":
+		return sequenceModeReplace, true
+	case "append":
+		return sequenceModeAppend, true
+	case "upsert":
+		return sequenceModeUpsert, true
+	default:
+		return 0, false
+	}
+}
+
+func sequenceDeclarationDiagnostic(path Path, message string, node *document.Node) Diagnostic {
+	var primary *Location
+	if node != nil {
+		location := publicLocation(node.Location)
+		primary = &location
+	}
+	return Diagnostic{Code: CodeSequenceInvalid, Severity: SeverityError, Path: path, Message: message, Primary: primary}
+}

internal/engine/sequence_declaration_test.go

@@ -0,0 +1,172 @@
+package engine
+
+import (
+	"reflect"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestParseSequenceDeclarationPresenceAndRelativeDestination(t *testing.T) {
+	tests := []struct {
+		name             string
+		declaration      string
+		wantIdentity     bool
+		wantMode         bool
+		wantIdentityList []string
+		wantModeValue    sequenceMode
+	}{
+		{name: "destination only is a no-op", declaration: "destination: [prompts]"},
+		{name: "key only", declaration: "destination: [prompts]\n      key: id", wantIdentity: true, wantIdentityList: []string{"id"}},
+		{name: "mode only", declaration: "destination: [prompts]\n      mode: append", wantMode: true, wantModeValue: sequenceModeAppend},
+		{name: "combined", declaration: "destination: [prompts]\n      key: [namespace, id, id]\n      mode: upsert", wantIdentity: true, wantMode: true, wantIdentityList: []string{"id", "namespace"}, wantModeValue: sequenceModeUpsert},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			extracted := extractSequenceDeclarationsYAML(t, "configkit:\n  sequences:\n    - "+test.declaration+"\n", rootDirectiveContextSource)
+			if !extracted.sequencesPresent || len(extracted.sequences) != 1 {
+				t.Fatalf("extraction = %#v", extracted)
+			}
+			declaration := extracted.sequences[0]
+			if declaration.destination.String() != "/prompts" || declaration.path.String() != "/configkit/sequences/0" {
+				t.Fatalf("relative destination or declaration path changed: %#v", declaration)
+			}
+			if declaration.location.SourceID != "sequence-declarations" || declaration.location.Line == 0 || declaration.destinationLocation.SourceID != "sequence-declarations" || declaration.destinationLocation.Line == 0 {
+				t.Fatalf("declaration source locations were not retained: %#v", declaration)
+			}
+			if declaration.identityPresent != test.wantIdentity || declaration.modePresent != test.wantMode {
+				t.Fatalf("presence = key:%t mode:%t, want key:%t mode:%t", declaration.identityPresent, declaration.modePresent, test.wantIdentity, test.wantMode)
+			}
+			if !reflect.DeepEqual(declaration.identityFields, test.wantIdentityList) || declaration.mode != test.wantModeValue {
+				t.Fatalf("parsed fields/mode = %#v/%d", declaration.identityFields, declaration.mode)
+			}
+			if declaration.identityPresent && (declaration.identityLocation == nil || declaration.identityLocation.SourceID != "sequence-declarations" || declaration.identityLocation.Line == 0) {
+				t.Fatalf("identity location missing: %#v", declaration)
+			}
+			if declaration.modePresent && (declaration.modeLocation == nil || declaration.modeLocation.SourceID != "sequence-declarations" || declaration.modeLocation.Line == 0) {
+				t.Fatalf("mode location missing: %#v", declaration)
+			}
+		})
+	}
+}
+
+func TestParseSequenceDeclarationNormalizesEquivalentFieldSets(t *testing.T) {
+	extracted := extractSequenceDeclarationsYAML(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      key: [namespace, id, id]
+    - destination: [prompts]
+      key: [id, namespace]
+`, rootDirectiveContextSource)
+	if len(extracted.sequences) != 2 || !reflect.DeepEqual(extracted.sequences[0].identityFields, extracted.sequences[1].identityFields) {
+		t.Fatalf("equivalent declarations were not normalized: %#v", extracted.sequences)
+	}
+}
+
+func TestExtractRootDirectivesCombinesImportsAndSequencesWithPresence(t *testing.T) {
+	extracted := extractSequenceDeclarationsYAML(t, `configkit:
+  imports: [{path: fragments/base.yaml}]
+  sequences: []
+value: true
+`, rootDirectiveContextSource)
+	if !extracted.importsPresent || len(extracted.imports) != 1 || !extracted.sequencesPresent || len(extracted.sequences) != 0 {
+		t.Fatalf("mixed extraction = %#v", extracted)
+	}
+	if extracted.body == nil || extracted.body.Kind != document.Mapping || len(extracted.body.Mapping) != 1 || extracted.body.Mapping[0].Key != "value" {
+		t.Fatalf("directive controls were not removed from payload: %#v", extracted.body)
+	}
+}
+
+func TestExtractRootDirectivesAllowsSequencesButRejectsOverlayImports(t *testing.T) {
+	_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, `configkit:
+  imports: [{path: fragments/base.yaml}]
+  sequences: [{destination: [prompts], key: id}]
+`), rootDirectiveContextOverlay)
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeOverlayDirective || diagnostics[0].Path.String() != "/configkit/imports" {
+		t.Fatalf("overlay diagnostics = %#v, want imports-only rejection", diagnostics)
+	}
+
+	extracted, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, `configkit:
+  sequences: [{destination: [prompts], key: id}]
+`), rootDirectiveContextOverlay)
+	if len(diagnostics) != 0 || !extracted.sequencesPresent || len(extracted.sequences) != 1 {
+		t.Fatalf("overlay sequence extraction = %#v, %#v", extracted, diagnostics)
+	}
+}
+
+func TestParseSequenceDeclarationRejectsMalformedForms(t *testing.T) {
+	tests := []struct {
+		name string
+		body string
+		path string
+	}{
+		{name: "sequences wrong type", body: "configkit: {sequences: nope}\n", path: "/configkit/sequences"},
+		{name: "declaration wrong type", body: "configkit: {sequences: [nope]}\n", path: "/configkit/sequences/0"},
+		{name: "missing destination", body: "configkit: {sequences: [{key: id}]}\n", path: "/configkit/sequences/0/destination"},
+		{name: "destination wrong type", body: "configkit: {sequences: [{destination: nope}]}\n", path: "/configkit/sequences/0/destination"},
+		{name: "reserved destination", body: "configkit: {sequences: [{destination: [configkit]}]}\n", path: "/configkit/sequences/0/destination/0"},
+		{name: "key wrong type", body: "configkit: {sequences: [{destination: [prompts], key: true}]}\n", path: "/configkit/sequences/0/key"},
+		{name: "empty key set", body: "configkit: {sequences: [{destination: [prompts], key: []}]}\n", path: "/configkit/sequences/0/key"},
+		{name: "key member wrong type", body: "configkit: {sequences: [{destination: [prompts], key: [id, null]}]}\n", path: "/configkit/sequences/0/key/1"},
+		{name: "mode wrong type", body: "configkit: {sequences: [{destination: [prompts], mode: true}]}\n", path: "/configkit/sequences/0/mode"},
+		{name: "unknown mode", body: "configkit: {sequences: [{destination: [prompts], mode: merge}]}\n", path: "/configkit/sequences/0/mode"},
+		{name: "unknown declaration field", body: "configkit: {sequences: [{destination: [prompts], append: true}]}\n", path: "/configkit/sequences/0/append"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			_, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, test.body), rootDirectiveContextSource)
+			if len(diagnostics) == 0 || diagnostics[0].Code != CodeSequenceInvalid || diagnostics[0].Path.String() != test.path {
+				t.Fatalf("diagnostics = %#v, want %s at %s", diagnostics, CodeSequenceInvalid, test.path)
+			}
+			if diagnostics[0].Primary == nil || diagnostics[0].Primary.Line == 0 {
+				t.Fatalf("diagnostic has no source location: %#v", diagnostics[0])
+			}
+		})
+	}
+}
+
+func TestSequenceDeclarationsDoNotTriggerVersionOverlapWhenHeaderIsAbsent(t *testing.T) {
+	root := parseRootDirectiveDocument(t, `configkit:
+  sequences:
+    - destination: [prompts]
+      key: id
+version: v1
+`)
+	presentPath, err := ParsePath("/configkit/sequences/0/destination")
+	if err != nil {
+		t.Fatal(err)
+	}
+	present := resolveSourceVersionPath(root, presentPath)
+	if !sourceVersionHeaderControlOverlap(root, present) {
+		t.Fatal("present version header beneath a sequence control did not overlap")
+	}
+	absentPath, err := ParsePath("/configkit/sequences/1/destination")
+	if err != nil {
+		t.Fatal(err)
+	}
+	absent := resolveSourceVersionPath(root, absentPath)
+	if absent.present {
+		t.Fatal("missing version header was reported present")
+	}
+	if sourceVersionHeaderControlOverlap(root, absent) {
+		t.Fatal("absent version header beneath a sequence control was treated as overlap")
+	}
+}
+
+func extractSequenceDeclarationsYAML(t *testing.T, input string, context rootDirectiveContext) rootDirectiveExtraction {
+	t.Helper()
+	extracted, diagnostics := extractRootDirectives(parseRootDirectiveDocument(t, input), context)
+	if len(diagnostics) != 0 {
+		t.Fatalf("root directive diagnostics = %#v", diagnostics)
+	}
+	return extracted
+}
+
+func parseRootDirectiveDocument(t *testing.T, input string) *document.Node {
+	t.Helper()
+	parsed, diagnostics := parseSource(Bytes("sequence-declarations.yml", []byte(input)), "sequence-declarations", defaultParseLimits())
+	if len(diagnostics) != 0 {
+		t.Fatalf("source parse diagnostics = %#v", diagnostics)
+	}
+	return parsed.document
+}

internal/engine/sequence_destination_projection_test.go

@@ -0,0 +1,102 @@
+package engine
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+	"testing/fstest"
+)
+
+func TestLayeredSequenceProjectsNestedSourceDestinations(t *testing.T) {
+	t.Parallel()
+	type catalog struct {
+		Items []map[string]any `yaml:"items"`
+	}
+	for _, mode := range []string{"upsert", "append", "replace"} {
+		for _, underlay := range []bool{false, true} {
+			t.Run(fmt.Sprintf("%s/underlay=%t", mode, underlay), func(t *testing.T) {
+				files := fstest.MapFS{}
+				for _, id := range []string{"a", "b", "c"} {
+					files[id+"/record.yml"] = &fstest.MapFile{Data: []byte("configkit: {imports: [{path: helper.yml}]}\nid: " + id + "\n")}
+					files[id+"/helper.yml"] = &fstest.MapFile{Data: []byte("value: " + id + "\n")}
+				}
+				files["main.yml"] = &fstest.MapFile{Data: []byte("configkit:\n  sequences: [{destination: [items], key: id, mode: " + mode + "}]\n  imports: [{glob: '*/record.yml', destination: [items], placement: sequence-item}]\n")}
+				lower := "items: [{id: b}, {id: a}, {id: keep}]\n"
+				want := map[string]int{"a": 1, "b": 0, "c": 3}
+				if mode == "append" {
+					lower = "items: [{id: keep}]\n"
+					want = map[string]int{"a": 1, "b": 2, "c": 3}
+				} else if mode == "replace" {
+					want = map[string]int{"a": 0, "b": 1, "c": 2}
+				}
+				incoming := loadInput{source: NewFilesystem("catalog", files).File("main.yml"), imports: true}
+				request := loadRequest[catalog]{main: incoming, underlays: []loadGroup{{inputs: []loadInput{{source: Bytes("lower", []byte(lower))}}}}}
+				if underlay {
+					request.main = loadInput{source: NoSource()}
+					request.underlays = append(request.underlays, loadGroup{inputs: []loadInput{incoming}})
+				}
+				loaded, err := testGroupedLoad(request)
+				if err != nil {
+					t.Fatal(err)
+				}
+				helpers := 0
+				for _, source := range loaded.Sources() {
+					if !strings.HasSuffix(source.Path, "/helper.yml") {
+						continue
+					}
+					helpers++
+					context, ok := loaded.SourceContext(source.ID)
+					if !ok {
+						t.Fatal("missing declaring context")
+					}
+					index, ok := want[context.BaseDir]
+					if !ok || source.Destination.String() != Keys("items").Index(index).String() {
+						t.Errorf("%s destination = %s, want item %d", context.BaseDir, source.Destination, index)
+					}
+					if loaded.Config.Items[index]["value"] != context.BaseDir {
+						t.Errorf("source destination identifies another record: %#v", loaded.Config.Items[index])
+					}
+				}
+				if helpers != 3 {
+					t.Fatalf("retained %d helpers, want 3", helpers)
+				}
+			})
+		}
+	}
+}
+
+func TestTierProjectionPreservesSourceLocalVersionEvidence(t *testing.T) {
+	t.Parallel()
+	local := Keys("version")
+	destination := Keys("items").Index(0).Key("details")
+	lower := &sourceVersionEvidence{sourceID: "lower", path: local, destination: destination.clone()}
+	higher := &sourceVersionEvidence{
+		sourceID: "higher", path: local, resolvedPath: local,
+		destination: destination.clone(), version: Version{Text: "accepted"},
+		projectedPaths: []Path{appendDestination(destination, local), destination.clone()},
+	}
+	sources := []SourceInfo{{ID: "higher", Path: "record/helper.yml", Destination: destination.clone()}}
+	state := &sourceVersionState{evidence: []*sourceVersionEvidence{lower, higher}}
+	projectTierSourceDestinations(sources, state.evidenceSince(1), []sequenceHistoryContribution{{
+		path: Keys("items"), mode: sequenceHistoryMapped,
+		items: []sequenceItemProjection{{inputIndex: 0, outputIndex: 1}},
+	}})
+	want := Keys("items").Index(1).Key("details")
+	if sources[0].Destination.String() != want.String() || sources[0].Path != "record/helper.yml" || higher.destination.String() != want.String() {
+		t.Fatalf("projected source/evidence = %#v, %#v", sources, higher)
+	}
+	if lower.destination.String() != destination.String() || lower.projectedPaths != nil {
+		t.Fatal("incoming projection relabeled a lower historical contribution")
+	}
+	if higher.path.String() != local.String() || higher.resolvedPath.String() != local.String() {
+		t.Fatal("projection changed source-local version coordinates")
+	}
+	paths := higher.sensitivityPaths()
+	if len(paths) != 2 || paths[0].String() != want.Key("version").String() || paths[1].String() != want.String() {
+		t.Fatalf("projected sensitivity paths = %#v", paths)
+	}
+	check := sourceVersionCheckForEvidence(higher, newDiffSensitivity(map[string]bool{want.String(): true}, nil), false)
+	if !check.Redacted || check.Version.Text != "" || check.Path.String() != local.String() {
+		t.Fatalf("version classification did not use effective coordinates: %#v", check)
+	}
+}

internal/engine/sequence_history_projection.go

@@ -0,0 +1,107 @@
+package engine
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+
+// projectTierHistoryApplications composes each strict source's local projection
+// with the tier operation. The retained source values stay in authored coordinates.
+func projectTierHistoryApplications(applications []historyApplication, operations []sequenceHistoryContribution) []historyApplication {
+	mapped := false
+	for _, operation := range operations {
+		mapped = mapped || operation.mode == sequenceHistoryMapped
+	}
+	if !mapped {
+		return applications
+	}
+	projections := indexSequenceHistoryContributions(operations)
+	projected := cloneHistoryApplications(applications)
+	for index, original := range applications {
+		application := &projected[index]
+		if path, found := projectSequenceOperationPath(original.path, projections); found {
+			application.path = path
+		}
+		for sequenceIndex, source := range original.sequences {
+			container := appendDestination(original.path, source.path)
+			operation, active := projections[container.String()]
+			if !active || operation.mode != sequenceHistoryMapped {
+				continue
+			}
+			value, found := documentAtPath(original.value, source.path)
+			if !found || value.Kind != document.Sequence {
+				continue
+			}
+			sourceIndex := application.sequencesByPath[source.path.String()]
+			contribution := sequenceHistoryContribution{path: source.path.clone(), mode: sequenceHistoryMapped}
+			for inputIndex := range value.Sequence {
+				tierIndex := source.offset + inputIndex
+				if source.mode == sequenceHistoryMapped {
+					tierIndex = sourceIndex.outputForInput(inputIndex)
+				}
+				outputIndex, present := operation.projection.outputForInput(tierIndex)
+				if !present {
+					continue
+				}
+				contribution.items = append(contribution.items, sequenceItemProjection{inputIndex: inputIndex, outputIndex: outputIndex})
+				if _, replaced := operation.replacedOutputs[outputIndex]; replaced {
+					// Upsert replacements retain their lower-list position.
+					contribution.replacements = append(contribution.replacements, sequenceItemReplacement{
+						lowerIndex: outputIndex, higherIndex: inputIndex, outputIndex: outputIndex,
+					})
+				}
+			}
+			application.sequences[sequenceIndex] = contribution
+		}
+		application.sequencesByPath = indexSequenceHistoryContributions(application.sequences)
+	}
+	return projected
+}
+
+func projectSequenceOperationPath(path Path, projections map[string]sequenceHistoryContributionIndex) (Path, bool) {
+	projected := path.clone()
+	for index, segment := range path.segments {
+		if segment.kind != pathSegmentIndex {
+			continue
+		}
+		prefix := Path{segments: path.segments[:index]}
+		operation, found := projections[prefix.String()]
+		if !found || operation.mode != sequenceHistoryMapped {
+			continue
+		}
+		outputIndex, found := operation.projection.outputForInput(segment.index)
+		if !found {
+			return Path{}, false
+		}
+		projected.segments[index].index = outputIndex
+	}
+	return projected, true
+}
+
+// Project only incoming sources. Lower/displaced sources retain the coordinates
+// of their own historical contribution, rather than becoming incoming survivors.
+func projectTierSourceDestinations(sources []SourceInfo, versions []*sourceVersionEvidence, operations []sequenceHistoryContribution) {
+	if len(operations) == 0 {
+		return
+	}
+	projections := indexSequenceHistoryContributions(operations)
+	for index := range sources {
+		if path, found := projectSequenceOperationPath(sources[index].Destination, projections); found {
+			sources[index].Destination = path
+		}
+	}
+	for _, evidence := range versions {
+		if evidence == nil {
+			continue
+		}
+		paths := evidence.sensitivityPaths()
+		projected := make([]Path, len(paths))
+		for index, path := range paths {
+			projected[index] = path.clone()
+			if destination, found := projectSequenceOperationPath(path, projections); found {
+				projected[index] = destination
+			}
+		}
+		evidence.projectedPaths = projected
+		if path, found := projectSequenceOperationPath(evidence.destination, projections); found {
+			evidence.destination = path
+		}
+	}
+}

internal/engine/sequence_identity.go

@@ -0,0 +1,287 @@
+package engine
+
+import (
+	"bytes"
+	"encoding/binary"
+	"errors"
+	"math/big"
+	"sort"
+	"strings"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+var (
+	errEmptySequenceIdentityFields      = errors.New("sequence identity requires at least one field")
+	errInvalidSequenceIdentityNumber    = errors.New("invalid sequence identity number")
+	errUnsupportedSequenceIdentityValue = errors.New("unsupported sequence identity value")
+)
+
+type sequenceIdentityDiagnosticCodes struct {
+	invalid  Code
+	conflict Code
+}
+
+type sequenceIdentityRecord struct {
+	tuple    string
+	index    int
+	location document.Location
+}
+
+type sequenceIdentityContext uint8
+
+const (
+	sequenceStructuralRecord sequenceIdentityContext = iota
+	sequencePayloadRecord
+)
+
+// normalizeSequenceIdentityFields treats identity field names as a set.
+func normalizeSequenceIdentityFields(fields []string) ([]string, error) {
+	if len(fields) == 0 {
+		return nil, errEmptySequenceIdentityFields
+	}
+	normalized := append([]string(nil), fields...)
+	sort.Strings(normalized)
+	write := 0
+	for _, field := range normalized {
+		if write != 0 && normalized[write-1] == field {
+			continue
+		}
+		normalized[write] = field
+		write++
+	}
+	return normalized[:write], nil
+}
+
+// normalizeSequenceIdentityNumber returns coefficient and exponent without
+// expanding powers of ten. The represented value is coefficient * 10^exponent.
+func normalizeSequenceIdentityNumber(value string) (string, error) {
+	if value == "" {
+		return "", errInvalidSequenceIdentityNumber
+	}
+	negative := false
+	if value[0] == '-' {
+		negative = true
+		value = value[1:]
+	}
+	if value == "" {
+		return "", errInvalidSequenceIdentityNumber
+	}
+
+	exponent := new(big.Int)
+	if index := strings.IndexAny(value, "eE"); index >= 0 {
+		if strings.IndexAny(value[index+1:], "eE") >= 0 {
+			return "", errInvalidSequenceIdentityNumber
+		}
+		text := value[index+1:]
+		if text == "" {
+			return "", errInvalidSequenceIdentityNumber
+		}
+		if _, ok := exponent.SetString(text, 10); !ok {
+			return "", errInvalidSequenceIdentityNumber
+		}
+		value = value[:index]
+	}
+
+	point := strings.IndexByte(value, '.')
+	if point >= 0 && strings.IndexByte(value[point+1:], '.') >= 0 {
+		return "", errInvalidSequenceIdentityNumber
+	}
+	integerPart := value
+	fractionPart := ""
+	if point >= 0 {
+		integerPart = value[:point]
+		fractionPart = value[point+1:]
+	}
+	if integerPart == "" || (point >= 0 && fractionPart == "") {
+		return "", errInvalidSequenceIdentityNumber
+	}
+	if len(integerPart) > 1 && integerPart[0] == '0' {
+		return "", errInvalidSequenceIdentityNumber
+	}
+	digits := integerPart + fractionPart
+	for _, digit := range digits {
+		if digit < '0' || digit > '9' {
+			return "", errInvalidSequenceIdentityNumber
+		}
+	}
+	coefficient := strings.TrimLeft(digits, "0")
+	if coefficient == "" {
+		return "0e0", nil
+	}
+	exponent.Sub(exponent, big.NewInt(int64(len(fractionPart))))
+	trimmed := strings.TrimRight(coefficient, "0")
+	exponent.Add(exponent, big.NewInt(int64(len(coefficient)-len(trimmed))))
+	coefficient = trimmed
+	if negative {
+		coefficient = "-" + coefficient
+	}
+	return coefficient + "e" + exponent.String(), nil
+}
+
+func sequenceScalarIdentityComponent(node *document.Node) (byte, string, error) {
+	if node == nil {
+		return 0, "", errUnsupportedSequenceIdentityValue
+	}
+	switch node.Kind {
+	case document.String:
+		return 's', node.Text, nil
+	case document.Number:
+		normalized, err := normalizeSequenceIdentityNumber(node.Text)
+		return 'n', normalized, err
+	case document.Boolean:
+		if node.Text != "true" && node.Text != "false" {
+			return 0, "", errUnsupportedSequenceIdentityValue
+		}
+		return 'b', node.Text, nil
+	case document.Null:
+		return 'z', "", nil
+	default:
+		return 0, "", errUnsupportedSequenceIdentityValue
+	}
+}
+
+func sequenceIdentityTuple(values []*document.Node) (string, error) {
+	var encoded bytes.Buffer
+	for _, value := range values {
+		kind, component, err := sequenceScalarIdentityComponent(value)
+		if err != nil {
+			return "", err
+		}
+		encoded.WriteByte(kind)
+		var length [binary.MaxVarintLen64]byte
+		n := binary.PutUvarint(length[:], uint64(len(component)))
+		encoded.Write(length[:n])
+		encoded.WriteString(component)
+	}
+	return encoded.String(), nil
+}
+
+// sequenceMappingIndex is built once per record. Structural lookup excludes the
+// directive's occurrence; effective payload and reference mappings keep all keys.
+type sequenceMappingIndex struct {
+	entries []document.Entry
+	byKey   map[string]int
+}
+
+func newSequenceMappingIndex(record *document.Node, context sequenceIdentityContext) sequenceMappingIndex {
+	index := sequenceMappingIndex{byKey: make(map[string]int)}
+	if record == nil || record.Kind != document.Mapping {
+		return index
+	}
+	index.entries = record.Mapping
+	directiveIndex := -1
+	if directive, exists := inheritanceDirective(record); context == sequenceStructuralRecord && exists {
+		for entryIndex := range record.Mapping {
+			if record.Mapping[entryIndex].Key == directive.Key && record.Mapping[entryIndex].KeyLocation == directive.KeyLocation {
+				directiveIndex = entryIndex
+				break
+			}
+		}
+	}
+	for entryIndex, entry := range record.Mapping {
+		if entryIndex == directiveIndex {
+			continue
+		}
+		if _, exists := index.byKey[entry.Key]; !exists {
+			index.byKey[entry.Key] = entryIndex
+		}
+	}
+	return index
+}
+
+func (index sequenceMappingIndex) identity(fields []string) (string, []document.Location, string, int) {
+	values := make([]*document.Node, len(fields))
+	locations := make([]document.Location, len(fields))
+	for fieldIndex, field := range fields {
+		entryIndex, exists := index.byKey[field]
+		if !exists {
+			return "", nil, field, -1
+		}
+		entry := index.entries[entryIndex]
+		if entry.Value == nil || (entry.Value.Kind != document.String && entry.Value.Kind != document.Number && entry.Value.Kind != document.Boolean && entry.Value.Kind != document.Null) {
+			return "", nil, field, entryIndex
+		}
+		if _, _, err := sequenceScalarIdentityComponent(entry.Value); err != nil {
+			return "", nil, field, entryIndex
+		}
+		values[fieldIndex] = entry.Value
+		locations[fieldIndex] = entry.ValueLocation
+		if entry.Value != nil && entry.Value.Location != (document.Location{}) {
+			locations[fieldIndex] = entry.Value.Location
+		}
+	}
+	tuple, err := sequenceIdentityTuple(values)
+	if err != nil {
+		return "", nil, fields[0], -2
+	}
+	return tuple, locations, "", -3
+}
+
+// validateSequenceIdentity checks mapping shape, direct identity fields, and
+// uniqueness in one tuple-to-first-location index. It does not alter the nodes.
+func validateSequenceIdentity(sequence *document.Node, path Path, fields []string, codes sequenceIdentityDiagnosticCodes) (map[string]sequenceIdentityRecord, []Diagnostic) {
+	return validateSequenceIdentityFrom(sequence, path, fields, codes, 0)
+}
+
+func validateSequenceIdentityFrom(sequence *document.Node, path Path, fields []string, codes sequenceIdentityDiagnosticCodes, startIndex int) (map[string]sequenceIdentityRecord, []Diagnostic) {
+	normalized, err := normalizeSequenceIdentityFields(fields)
+	if err != nil {
+		location := (*Location)(nil)
+		if sequence != nil {
+			converted := publicLocation(sequence.Location)
+			location = &converted
+		}
+		return nil, []Diagnostic{{Code: codes.invalid, Severity: SeverityError, Path: path, Message: "sequence identity requires at least one field", Primary: location}}
+	}
+	return validateNormalizedSequenceIdentityFrom(sequence, path, normalized, codes, startIndex, sequenceStructuralRecord)
+}
+
+func validateNormalizedSequenceIdentityFrom(sequence *document.Node, path Path, normalized []string, codes sequenceIdentityDiagnosticCodes, startIndex int, context sequenceIdentityContext) (map[string]sequenceIdentityRecord, []Diagnostic) {
+	if sequence == nil || sequence.Kind != document.Sequence {
+		location := (*Location)(nil)
+		if sequence != nil {
+			converted := publicLocation(sequence.Location)
+			location = &converted
+		}
+		return nil, []Diagnostic{{Code: codes.invalid, Severity: SeverityError, Path: path, Message: "identified collection must be a sequence", Primary: location}}
+	}
+
+	firstByTuple := make(map[string]sequenceIdentityRecord, len(sequence.Sequence))
+	for itemIndex, item := range sequence.Sequence {
+		itemPath := path.Index(startIndex + itemIndex)
+		if item == nil || item.Kind != document.Mapping {
+			var primary *Location
+			if item != nil {
+				converted := publicLocation(item.Location)
+				primary = &converted
+			}
+			return nil, []Diagnostic{{Code: codes.invalid, Severity: SeverityError, Path: itemPath, Message: "identified collection items must be mappings", Primary: primary}}
+		}
+		mapping := newSequenceMappingIndex(item, context)
+		tuple, locations, missing, entryIndex := mapping.identity(normalized)
+		if entryIndex == -1 {
+			location := publicLocation(item.Location)
+			return nil, []Diagnostic{{Code: codes.invalid, Severity: SeverityError, Path: itemPath.Key(missing), Message: "identified collection item is missing an identity field", Primary: &location}}
+		}
+		if entryIndex == -2 || entryIndex >= 0 {
+			location := publicLocation(item.Location)
+			fieldPath := itemPath.Key(missing)
+			if entryIndex >= 0 {
+				location = publicLocation(item.Mapping[entryIndex].ValueLocation)
+				if value := item.Mapping[entryIndex].Value; value != nil {
+					location = publicLocation(value.Location)
+				}
+			}
+			return nil, []Diagnostic{{Code: codes.invalid, Severity: SeverityError, Path: fieldPath, Message: "identity fields must be scalar values", Primary: &location}}
+		}
+		if first, duplicate := firstByTuple[tuple]; duplicate {
+			current := publicLocation(locations[0])
+			return nil, []Diagnostic{{Code: codes.conflict, Severity: SeverityError, Path: path, Message: "identified collection contains duplicate identities", Primary: ptrLocation(publicLocation(first.location)), Related: []Location{current}}}
+		}
+		firstByTuple[tuple] = sequenceIdentityRecord{tuple: tuple, index: itemIndex, location: locations[0]}
+	}
+	return firstByTuple, nil
+}
+
+func ptrLocation(location Location) *Location { return &location }

internal/engine/sequence_identity_test.go

@@ -0,0 +1,209 @@
+package engine
+
+import (
+	"math/big"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+
+	"gitea.maximumdirect.net/eric/ConfigKit/internal/document"
+)
+
+func TestNormalizeSequenceIdentityFields(t *testing.T) {
+	got, err := normalizeSequenceIdentityFields([]string{"name", "id", "id", ""})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := []string{"", "id", "name"}; !reflect.DeepEqual(got, want) {
+		t.Fatalf("normalized fields = %#v, want %#v", got, want)
+	}
+	if _, err := normalizeSequenceIdentityFields(nil); err == nil {
+		t.Fatal("empty field set unexpectedly succeeded")
+	}
+}
+
+func TestNormalizeSequenceIdentityNumbers(t *testing.T) {
+	tests := []struct {
+		left, right string
+		equal       bool
+	}{
+		{left: "1", right: "1.0", equal: true},
+		{left: "1", right: "1e0", equal: true},
+		{left: "0", right: "-0.000e999", equal: true},
+		{left: "0.0012300", right: "123e-5", equal: true},
+		{left: "9007199254740992", right: "9007199254740993", equal: false},
+		{left: "1.0000000000000000001", right: "1.0000000000000000002", equal: false},
+	}
+	for _, test := range tests {
+		left, leftErr := normalizeSequenceIdentityNumber(test.left)
+		right, rightErr := normalizeSequenceIdentityNumber(test.right)
+		if leftErr != nil || rightErr != nil {
+			t.Fatalf("normalize(%q, %q) errors = %v, %v", test.left, test.right, leftErr, rightErr)
+		}
+		if (left == right) != test.equal {
+			t.Errorf("normalize(%q) = %q; normalize(%q) = %q; equal = %t, want %t", test.left, left, test.right, right, left == right, test.equal)
+		}
+	}
+}
+
+func TestNormalizeSequenceIdentityNumberLargeExponentWithoutExpansion(t *testing.T) {
+	exponent := "999999999999999999999999999999999999999999999999999999999999999999999999999999999999"
+	left, err := normalizeSequenceIdentityNumber("1e" + exponent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	plusOne, ok := new(big.Int).SetString(exponent, 10)
+	if !ok {
+		t.Fatal("test exponent did not parse")
+	}
+	plusOne.Add(plusOne, big.NewInt(1))
+	right, err := normalizeSequenceIdentityNumber("10e" + exponent)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if want := "1e" + plusOne.String(); right != want {
+		t.Fatalf("normalized large exponent = %q, want %q", right, want)
+	}
+	if left == right {
+		t.Fatal("unequal large exponents normalized to equal values")
+	}
+}
+
+func TestSequenceIdentityTupleUsesTypeTagsAndLengthBoundaries(t *testing.T) {
+	tests := []struct {
+		name  string
+		left  []*document.Node
+		right []*document.Node
+		equal bool
+	}{
+		{name: "empty string differs from null", left: []*document.Node{stringNode("")}, right: []*document.Node{nullNode()}, equal: false},
+		{name: "empty strings match exactly", left: []*document.Node{stringNode("")}, right: []*document.Node{stringNode("")}, equal: true},
+		{name: "explicit null matches explicit null", left: []*document.Node{nullNode()}, right: []*document.Node{nullNode()}, equal: true},
+		{name: "string and number differ", left: []*document.Node{stringNode("1")}, right: []*document.Node{numberNode("1.0")}, equal: false},
+		{name: "boolean and number differ", left: []*document.Node{booleanNode("true")}, right: []*document.Node{numberNode("1")}, equal: false},
+		{name: "compound boundaries are encoded", left: []*document.Node{stringNode("ab"), stringNode("c")}, right: []*document.Node{stringNode("a"), stringNode("bc")}, equal: false},
+		{name: "number spelling is normalized", left: []*document.Node{numberNode("1")}, right: []*document.Node{numberNode("1e0")}, equal: true},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			left, leftErr := sequenceIdentityTuple(test.left)
+			right, rightErr := sequenceIdentityTuple(test.right)
+			if leftErr != nil || rightErr != nil {
+				t.Fatalf("tuple errors = %v, %v", leftErr, rightErr)
+			}
+			if (left == right) != test.equal {
+				t.Fatalf("tuple equality = %t, want %t", left == right, test.equal)
+			}
+		})
+	}
+}
+
+func TestValidateSequenceIdentityUsesOneTupleIndexAndPreservesNodes(t *testing.T) {
+	first := identityRecord(map[string]*document.Node{
+		"namespace": stringNode("support"),
+		"id":        numberNode("1.0"),
+	})
+	second := identityRecord(map[string]*document.Node{
+		"id":        numberNode("1e0"),
+		"namespace": stringNode("support"),
+	})
+	sequence := &document.Node{Kind: document.Sequence, Location: document.Location{SourceID: "source", Line: 1}, Sequence: []*document.Node{first, second}}
+	_, diagnostics := validateSequenceIdentity(sequence, Keys("prompts"), []string{"namespace", "id", "id"}, sequenceIdentityDiagnosticCodes{invalid: CodeComposeInvalid, conflict: CodeComposeConflict})
+	if len(diagnostics) != 1 {
+		t.Fatalf("diagnostics = %#v, want one duplicate diagnostic", diagnostics)
+	}
+	diagnostic := diagnostics[0]
+	if diagnostic.Code != CodeComposeConflict || diagnostic.Path.String() != "/prompts" || diagnostic.Primary == nil || len(diagnostic.Related) != 1 {
+		t.Fatalf("duplicate diagnostic = %#v", diagnostic)
+	}
+	if diagnostic.Message == "" || strings.Contains(diagnostic.Message, "support") || strings.Contains(diagnostic.Message, "1.0") {
+		t.Fatalf("diagnostic unexpectedly contains identity data: %#v", diagnostic)
+	}
+	if first.Mapping[0].Value.Text != "1.0" || second.Mapping[0].Value.Text != "1e0" {
+		t.Fatalf("identity validation rewrote authored values: %q, %q", first.Mapping[0].Value.Text, second.Mapping[0].Value.Text)
+	}
+}
+
+func TestValidateSequenceIdentityReportsMalformedFieldsWithoutValues(t *testing.T) {
+	tests := []struct {
+		name     string
+		item     *document.Node
+		wantPath string
+	}{
+		{name: "non-mapping item", item: stringNode("private"), wantPath: "/items/0"},
+		{name: "missing field", item: identityRecord(map[string]*document.Node{"other": stringNode("private")}), wantPath: "/items/0/id"},
+		{name: "mapping field", item: identityRecord(map[string]*document.Node{"id": {Kind: document.Mapping}}), wantPath: "/items/0/id"},
+		{name: "sequence field", item: identityRecord(map[string]*document.Node{"id": {Kind: document.Sequence}}), wantPath: "/items/0/id"},
+	}
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			sequence := &document.Node{Kind: document.Sequence, Sequence: []*document.Node{test.item}}
+			_, diagnostics := validateSequenceIdentity(sequence, Keys("items"), []string{"id"}, sequenceIdentityDiagnosticCodes{invalid: CodeOptionsInvalid, conflict: CodeComposeConflict})
+			if len(diagnostics) != 1 || diagnostics[0].Code != CodeOptionsInvalid || diagnostics[0].Path.String() != test.wantPath {
+				t.Fatalf("diagnostics = %#v", diagnostics)
+			}
+			if diagnostics[0].Message == "" || strings.Contains(diagnostics[0].Message, "private") {
+				t.Fatalf("diagnostic exposed value or lacked message: %#v", diagnostics[0])
+			}
+		})
+	}
+}
+
+func TestSequenceIdentityExcludesStructuralExtendsField(t *testing.T) {
+	item := identityRecord(map[string]*document.Node{
+		"extends": nullNode(),
+		"name":    stringNode("ordinary payload"),
+	})
+	sequence := &document.Node{Kind: document.Sequence, Sequence: []*document.Node{item}}
+	_, diagnostics := validateSequenceIdentity(sequence, Keys("items"), []string{"extends"}, sequenceIdentityDiagnosticCodes{invalid: CodeComposeInvalid, conflict: CodeComposeConflict})
+	if len(diagnostics) != 1 || diagnostics[0].Path.String() != "/items/0/extends" || diagnostics[0].Code != CodeComposeInvalid {
+		t.Fatalf("diagnostics = %#v, want structural field treated as absent", diagnostics)
+	}
+}
+
+func TestSequenceIdentityUsesLiteralPunctuationFieldNames(t *testing.T) {
+	item := identityRecord(map[string]*document.Node{"metadata.id": stringNode("literal"), "metadata": identityRecord(map[string]*document.Node{"id": stringNode("nested")})})
+	sequence := &document.Node{Kind: document.Sequence, Sequence: []*document.Node{item}}
+	identities, diagnostics := validateSequenceIdentity(sequence, Keys("items"), []string{"metadata.id"}, sequenceIdentityDiagnosticCodes{invalid: CodeComposeInvalid, conflict: CodeComposeConflict})
+	if len(diagnostics) != 0 {
+		t.Fatalf("diagnostics = %#v", diagnostics)
+	}
+	if len(identities) != 1 {
+		t.Fatalf("identity index has %d entries, want 1", len(identities))
+	}
+}
+
+func TestValidateSequenceIdentityUsesCallerDiagnosticCodes(t *testing.T) {
+	item := identityRecord(map[string]*document.Node{"id": stringNode("same")})
+	sequence := &document.Node{Kind: document.Sequence, Sequence: []*document.Node{item, document.Clone(item)}}
+	_, diagnostics := validateSequenceIdentity(sequence, Keys("items"), []string{"id"}, sequenceIdentityDiagnosticCodes{invalid: CodeOptionsInvalid, conflict: CodeValidateMutation})
+	if len(diagnostics) != 1 || diagnostics[0].Code != CodeValidateMutation {
+		t.Fatalf("diagnostics = %#v, want caller-selected conflict code", diagnostics)
+	}
+}
+
+func identityRecord(fields map[string]*document.Node) *document.Node {
+	entries := make([]document.Entry, 0, len(fields))
+	keys := make([]string, 0, len(fields))
+	for key := range fields {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		value := fields[key]
+		entries = append(entries, document.Entry{Key: key, Value: value, ValueLocation: value.Location})
+	}
+	return &document.Node{Kind: document.Mapping, Mapping: entries, Location: document.Location{SourceID: "source", Line: 2}}
+}
+
+func stringNode(value string) *document.Node {
+	return &document.Node{Kind: document.String, Text: value}
+}
+func numberNode(value string) *document.Node {
+	return &document.Node{Kind: document.Number, Text: value}
+}
+func booleanNode(value string) *document.Node {
+	return &document.Node{Kind: document.Boolean, Text: value}
+}
+func nullNode() *document.Node { return &document.Node{Kind: document.Null} }