diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index b6341e7..86beef9 100644 --- a/docs/roadmap/sequences.md +++ b/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 -identified the remaining policy-lifetime clarification in OD-12 below. Resolve it -and review the completed roadmap before preparing a staged implementation plan. -This is not an implementation plan or an implemented contract. +Status: feature roadmap with OD-1 through OD-12 settled and ready for a staged +implementation plan. No open design decisions remain in this roadmap. 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 -absent contributions, null collections, and kind mismatches are settled in OD-6. +The policy reset above applies when the collection value is actually replaced. +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 -nothing contributes nothing; it does not erase records supplied elsewhere. +A declaration alone does not clear a collection. OD-12 defines how a key-only +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 -below and review of the completed roadmap. -It should cover ordinary and layered loading, item-local scopes, source-version +The settled roadmap is ready for a staged implementation plan. +The plan 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.