Clarify sequence policy interactions and rename the roadmap
This commit is contained in:
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user