Settle sequence identity declarations without values

docs/roadmap/sequences.md

@@ -1,9 +1,8 @@
 # Sequence Identity And Combination
 
-Status: feature roadmap with OD-1 through OD-11 settled. A whole-roadmap review
+Status: feature roadmap with OD-1 through OD-12 settled and ready for a staged
-identified the remaining policy-lifetime clarification in OD-12 below. Resolve it
+implementation plan. No open design decisions remain in this roadmap. This is
-and review the completed roadmap before preparing a staged implementation plan.
+not an implementation plan or an implemented contract.
-This is not an implementation plan or an implemented contract.
 
 ## Motivation
 
@@ -261,13 +260,15 @@ records, including uniqueness within each contribution.
 
 #### Replacement And Policy Lifetime
 
-YAML-owned identity follows the collection that survives an operation:
+YAML-owned identity follows the collection that survives an operation. OD-12
+also permits declarations pending at absent or non-sequence destinations.
 
 | Operation | Effective YAML-owned identity |
 | --- | --- |
 | Append | Retain or establish the agreed identity |
 | Replacement by identity | Retain or establish the agreed identity |
 | Whole-sequence replacement | Use the replacing tier's declaration and discard the lower collection's YAML-only identity |
+| Replacement by null or another non-sequence value | Discard the lower YAML-only identity; retain any identity explicitly declared by the replacing tier under OD-12 |
 
 Without an application constraint, whole-sequence replacement may introduce a
 different identity, such as replacing an `id`-keyed collection with a `name`-keyed
@@ -277,8 +278,9 @@ removal directive is needed.
 
 Application registrations continue to constrain the replacement collection.
 If the application requires `id`, declaring `name` is invalid under every mode.
-The policy reset above applies when a sequence is actually replaced; effects of
+The policy reset above applies when the collection value is actually replaced.
-absent contributions, null collections, and kind mismatches are settled in OD-6.
+OD-6 defines the value effects of absence, null, and kind mismatches; OD-12
+defines the corresponding declaration-only and identity-lifetime rules.
 YAML-only identity declarations receive assembly-time enforcement, as settled
 in OD-1 below.
 
@@ -525,8 +527,10 @@ At a collection's precedence boundary:
 | Explicit `[]` | Clear the sequence | Contribute no records |
 | Explicit null or another non-sequence value | Ordinary replacement, subject to application schema | Error: the operation requires a sequence |
 
-A declaration alone does not clear a collection. An optional import selecting
+A declaration alone does not clear a collection. OD-12 defines how a key-only
-nothing contributes nothing; it does not erase records supplied elsewhere.
+declaration validates a retained sequence or remains pending when no sequence
+exists. An optional import selecting nothing contributes nothing; it does not
+erase records supplied elsewhere.
 An absent lower collection can be initialized by an incoming sequence under
 any mode, subject to identity requirements. An explicitly null or other
 non-sequence lower value is distinct from absence: append and upsert against it
@@ -827,6 +831,35 @@ removed. This preserves OD-9's persistence rule for applicable explicit modes
 without retaining declarations owned by discarded records. The implementation
 plan should choose the bookkeeping needed to preserve these distinctions.
 
+### Identity Declarations Without Sequence Values
+
+**OD-12: settled.**
+
+Allow identity declarations without accompanying records. Apply a declaration to
+an existing retained sequence immediately, checking identity agreement and
+validating its records. Do not recombine earlier tiers. For example, if a lower
+tier supplies an unkeyed `prompts` sequence and a higher tier only declares
+`destination: [prompts], key: id`, the retained records must satisfy that identity
+at this boundary.
+
+If the collection is absent, retain the declaration in its owning scope for later
+contributions without requiring the collection to exist. An otherwise empty
+underlay can therefore establish identity for main-tier fragments under OD-10.
+Item-local declarations remain subject to OD-11's ownership rules.
+
+Merely declaring replace without supplying a replacement value does not authorize
+changing a retained collection's identity. Actual replacement of the collection
+by null or another non-sequence value discards the lower YAML-only identity,
+retains any identity explicitly declared by the replacing tier, and preserves
+application constraints. This extends OD-3's replacement rule to non-sequence
+values.
+
+An explicit identity declaration can remain pending at an absent or non-sequence
+destination without independently imposing a shape requirement. OD-6 still
+governs whether an attempted operation on a non-sequence value fails. These rules
+allow baseline policy declarations while keeping identity removal tied to actual
+replacement. Explicit mode persistence remains governed by OD-9.
+
 ## Architectural Direction
 
 The settled collection declaration gives imported and inline records at the same
@@ -865,50 +898,7 @@ architecture policy before implementation. The current ADR and contracts remain
 authoritative until that decision is made. This draft neither changes them nor
 selects migration machinery.
 
-A staged implementation plan should follow resolution of the open decisions
+The settled roadmap is ready for a staged implementation plan.
-below and review of the completed roadmap.
+The plan should cover ordinary and layered loading, item-local scopes, source-version
-It should cover ordinary and layered loading, item-local scopes, source-version
 processing, identity validation, precedence, inheritance, and inspection together.
 Public API design and test sequencing belong to that later plan.
-
-## Open Decisions
-
-### OD-12. Identity Declarations Without Sequence Values
-
-OD-9 defines a mode-only declaration without accompanying records. Clarify the
-corresponding behavior for `key`, including a declaration made before any sequence
-exists, and complete OD-3's identity-lifetime rule for non-sequence replacement.
-These cases must have defined results before the implementation plan chooses how
-to store collection policy.
-
-For example, a lower tier supplies an unkeyed `prompts` sequence and a higher tier
-only declares `destination: [prompts], key: id`. Does this validate and identify
-the retained sequence immediately? Can a declaration in an otherwise empty
-underlay establish identity for main-tier fragments under OD-10? Conversely, if
-an identified sequence is replaced by null, does its old YAML identity disappear?
-OD-6 specifies the resulting values but does not fully specify these policy effects.
-
-**Recommendation:** Allow identity declarations without accompanying records.
-Apply the declaration to a retained sequence immediately, checking identity
-agreement and validating its records; do not recombine earlier tiers. If the
-collection is absent, retain the declaration in its owning scope for later
-contributions without requiring the collection to exist. Merely declaring replace
-without supplying a replacement value does not authorize changing a retained
-collection's identity. Extend OD-3's replacement rule to any actual replacement
-of the collection by a non-sequence value: discard the lower YAML-only identity,
-retain any identity explicitly declared by the replacing tier, and preserve
-application constraints. An explicit declaration can remain pending at an absent
-or non-sequence destination without independently imposing a shape requirement;
-OD-6 still governs whether an attempted operation on a non-sequence value fails.
-These rules allow baseline policy declarations while keeping identity removal
-tied to actual replacement. Explicit mode persistence remains governed by OD-9.
-
-**Alternative:** Require a YAML identity declaration to have a sequence in the
-same tier. This keeps YAML identity attached only to concrete sequence values
-and reduces pending-policy cases, but prevents policy-only baseline files and
-requires authors to repeat declarations beside later contributions. It also
-makes identity declarations less flexible than the settled mode declarations.
-For non-sequence replacement, retaining the lower YAML identity until another
-sequence appears is another viable choice; it supports persistent schema-like
-policy, but conflicts with the current distinction between collection-owned
-YAML identity and application-owned constraints and would require revisiting OD-3.