diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index 9d185f5..cdbf789 100644 --- a/docs/roadmap/sequences.md +++ b/docs/roadmap/sequences.md @@ -1,9 +1,9 @@ # Sequence Identity And Combination -Status: feature roadmap with OD-1 through OD-9 settled and follow-up interaction -decisions OD-10 and OD-11 open. The original decisions establish the intended -operations; the new questions address their lifecycle and policy-scope boundaries. -Resolve these questions before preparing a staged implementation plan. This is +Status: feature roadmap with OD-1 through OD-10 settled and follow-up interaction +decision OD-11 open. The original decisions establish the intended operations; +the remaining question addresses nested policy ownership and transfer. +Resolve it before preparing a staged implementation plan. This is not an implementation plan or an implemented contract. ## Motivation @@ -250,8 +250,8 @@ being combined: | `id` | `[namespace, id]` | Error: different identity definitions | | None | `id` | Establish `id` and validate all participating records under it | -OD-10 separately asks whether lower-tier YAML identity is available during the -higher tier's strict composition, before this precedence combination occurs. +OD-10 makes applicable lower-tier YAML identity available during the higher +tier's strict composition, before this precedence combination occurs. An application registration supplies identity when configuration omits it and remains authoritative over explicit declarations. If neither the application nor @@ -289,8 +289,9 @@ in OD-1 below. #### One Operation Per Collection Per Tier -Strictly compose a tier's contributions first, then apply one selected operation -per collection against the accumulated lower sequence. A collection declaration +Resolve applicable collection policy, including available lower-tier identity +under OD-10, before strictly composing a tier's contributions. Then apply one +selected operation per collection against the accumulated lower sequence. A collection declaration governs all contributions to that collection in its tier, including imported and inline records; it does not govern only records in the declaring file. @@ -729,6 +730,42 @@ resurrect policies owned by discarded records. OD-11 addresses nested policy ownership and transfer. CLI overrides remain outside sequence mode selection under OD-8. Strict peer composition and all ordering rules in OD-4 are unchanged. +### Lower-Tier Identity During Strict Composition + +**OD-10: settled.** + +Allow identity established in accumulated lower tiers to inform strict composition +of a higher tier. Resolve applicable collection identity before combining that +tier's peer contributions, using application registrations, available lower-tier +identity, and declarations gathered within the higher tier's relevant scope. +Authors need not repeat a baseline identity declaration solely because the higher +tier contributes the collection through multiple fragments. + +For example, an underlay declares `key: id` for `prompts`; two main-tier fragments +contribute records `[foo]` and `[bar]` without redeclaring a key. The inherited +identity enables those fragments to compose as `[foo, bar]` before the main tier +combines with the accumulated lower collection. If both fragments instead +contribute `foo`, strict composition fails. A selected upsert mode never grants +precedence to peers within the tier. + +This does not turn lower YAML identity into an application-owned constraint. +Determine applicability using OD-3's agreement and replacement rules: append and +upsert require agreement, while whole-sequence replacement may change or discard +YAML-only identity. A replacing collection must not be constrained by an obsolete +lower identity merely because policy resolution precedes strict composition. +Application registrations remain authoritative. Higher-tier declarations do not +retroactively repair invalid lower-tier composition. + +Separate source acquisition from policy-aware composition, or otherwise revise +assembly sequencing, so accumulated lower policy is available before higher-tier +strict composition. The current main-before-underlay composition order is not a +constraint on this design. Preserve the distinction between source acquisition +order, strict within-tier dependency-ready scheduling, and precedence order. +The implementation plan must account explicitly for source records, callbacks, +main-version checks, and failure diagnostics when changing the handoffs. Retain +version ownership and validation semantics; do not use higher-tier replacement +to hide lower-tier structural failures. + ## Architectural Direction The settled collection declaration gives imported and inline records at the same @@ -737,6 +774,8 @@ the relevant scope. OD-3 settles identity agreement and lifetime; OD-4 settles tier-wide operation selection, strict peer composition, and ordering at precedence boundaries. +OD-10 requires resolving applicable lower-tier policy before higher-tier strict +composition, independently of source acquisition order. This requires collection policy to survive import expansion through precedence assembly and the applicable inheritance operations. Correctness includes final @@ -773,30 +812,6 @@ Public API design and test sequencing belong to that later plan. ## Open Decisions -### OD-10. Identity Availability During Strict Tier Composition - -Suppose an underlay declares `key: id`, while two main-tier fragments contribute -`[A]` and `[B]` without declaring a key. Can the underlay identity enable strict -composition of those fragments, or does the main tier first fail as an unidentified -repeated sequence? Lower identity is available at precedence boundaries under -OD-5, but the current [layered lifecycle](../config.md#layered-loading) composes -the main input before acquiring underlays. - -**Recommendation:** Strict composition uses application registrations and -declarations within that tier's relevant scope. Lower-tier YAML identity becomes -available at the precedence boundary. In this example, the main tier needs its -own declaration or an application registration to compose its peer sequences. -This preserves independent tier validation and avoids making a later precedence -step retroactively repair a strict-composition failure. Document this distinction -from the single-contribution case, which can acquire lower identity at precedence. - -**Alternative:** Make accumulated lower-tier identity available before composing -each higher tier. Authors could declare identity once in a baseline and reuse it -for higher-tier peer composition. This requires separating acquisition from -composition or otherwise changing assembly sequencing while reconciling existing -source ordering and main-version checks. It is a viable broader scope if avoiding -repeated declarations justifies that lifecycle change. - ### OD-11. Nested Policy Ownership And Transfer OD-2 allows collection declarations inside imported items, and OD-3 ties YAML-only