From 4f941f8ba4c9a9ed0afa87b07fe6ba29f131d1c6 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 23 Oct 2026 12:20:18 +0000 Subject: [PATCH] Clarify sequence policy interactions and rename the roadmap --- docs/policy/architecture.md | 2 +- docs/roadmap/future.md | 2 +- docs/roadmap/{roadmap.md => sequences.md} | 46 +++++++++++++++++++++++ 3 files changed, 48 insertions(+), 2 deletions(-) rename docs/roadmap/{roadmap.md => sequences.md} (94%) diff --git a/docs/policy/architecture.md b/docs/policy/architecture.md index 1194a7b..e95a740 100644 --- a/docs/policy/architecture.md +++ b/docs/policy/architecture.md @@ -35,7 +35,7 @@ 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/roadmap.md) tracks the work to implement them; +[sequence roadmap](../roadmap/sequences.md) tracks the work to implement them; the configuration contract continues to describe implemented behavior. ## Success Criteria diff --git a/docs/roadmap/future.md b/docs/roadmap/future.md index 9884f78..aa88101 100644 --- a/docs/roadmap/future.md +++ b/docs/roadmap/future.md @@ -22,7 +22,7 @@ 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](roadmap.md) now selects a narrower design for +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 diff --git a/docs/roadmap/roadmap.md b/docs/roadmap/sequences.md similarity index 94% rename from docs/roadmap/roadmap.md rename to docs/roadmap/sequences.md index ebc8ef8..231f494 100644 --- a/docs/roadmap/roadmap.md +++ b/docs/roadmap/sequences.md @@ -527,6 +527,29 @@ replace without supplying a replacement does not authorize changing the identity of retained records. Explicit mode lifetime is separate from YAML identity lifetime. +### Ancestor Replacement + +Replacing an enclosing mapping can remove a collection without replacing that +collection directly. Apply the same identity and ownership rules to this removal: +discard the removed collection's lower YAML identity, and discard policies owned +by any removed records. Reintroducing the same path later does not restore those +discarded policies. + +Independently declared explicit modes retain their existing persistence rules. +Removing a descendant collection does not remove a mode whose declaring scope +survives. Application registrations remain applicable at matching destinations, +including destinations reintroduced later. Identity newly declared by the +replacing tier follows the existing declaration and ownership rules. + +For example, a root-level declaration establishes `key: id` and `mode: append` +for `[catalog, prompts]`. A higher tier replaces `catalog` with null, removing +the prompts collection and its YAML identity. The independently declared append +mode survives. If a later tier recreates `catalog.prompts`, append requires +identity supplied by a new declaration or an application registration. Without +that identity, loading fails; the later tier can instead explicitly choose +replace. The replacement of `catalog` itself follows ordinary ancestor-value +precedence and does not attempt to append null to the removed prompts list. + ### Declarations Without Sequence Values A key declaration without accompanying records applies immediately to an existing @@ -807,6 +830,19 @@ source-version headers before checking payload identity for collection assembly. A helper can supply an identity component; a consumed header cannot supply one after removal. +Structural controls are likewise unavailable as source identity components. +Check identity against application payload fields, excluding fields acting as +structural directives even when the engine retains them for later processing. +For example, `key: extends` with an item containing `extends: null` does not +supply a null identity: that field cancels inheritance and is consumed. Report +the ordinary missing-identity-component error at the collection/item path using +available origins, without exposing values. Do not defer this failure until +directive consumption or final application validation. + +This rule follows a field's structural role; it does not introduce a broader +restriction on unrelated literal field names. Final application identity checks +continue to examine the effective typed payload under their existing rules. + Validate each identified contribution before combination and check uniqueness in the resulting identified collection, including inheritance operations. Upsert matches across precedence are replacements; duplicates within a contribution @@ -884,6 +920,9 @@ order and test sequencing defined there: scalar identity tuples with exact numeric equality, declaration agreement, pending declarations, explicit-mode persistence, replacement lifetime, and record-owned policy transfer. Choose bookkeeping proportional to these semantics. + Handle descendant collection removal through ancestor replacement, preserving + independently declared modes and application constraints while discarding + removed collection identity and record-owned policies. - **Registration matching:** support literal and arbitrary-mapping-key segments, detect incompatible selector overlap during definition validation, and resolve applicable constraints at concrete placed destinations. Reuse the identity @@ -912,6 +951,8 @@ order and test sequencing defined there: within structural operations. Match dynamic registrations during assembly and inheritance, and against the final effective configuration rather than a saved list of source-backed destinations. + Exclude structural controls from source identity checks even while retaining + those controls for later inheritance processing. - **Documentation and verification:** exercise ordinary and layered loading, imported and inline collections, item-local scopes, version-header consumption, selected overlays, inheritance, typed defaults, CLI, callbacks, and inspection. @@ -930,6 +971,11 @@ order and test sequencing defined there: Verify both constructors feed the same registration model, including mixed exact and dynamic registrations, compound identities, and definition-time rejection of empty identity field sets. + Cover ancestor replacement followed by collection reintroduction, including a + surviving append mode with and without renewed identity, explicit replacement, + and application-registered identity. Verify that `extends: null` cannot supply + an identity component and that structural-control exclusion uses ordinary + value-free missing-identity diagnostics. Update the public contract and consumer examples when behavior lands. The collection-policy and CLI-ordering decisions are accepted in