From 12f6045da0b49205c3832a1e68e2792fcba4f1c1 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 22 Oct 2026 14:08:55 +0000 Subject: [PATCH] Settle sequence combination scope and ordering --- docs/roadmap/sequences.md | 134 ++++++++++++++++++++++++-------------- 1 file changed, 84 insertions(+), 50 deletions(-) diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index 09d5c77..f399568 100644 --- a/docs/roadmap/sequences.md +++ b/docs/roadmap/sequences.md @@ -80,8 +80,8 @@ controls belong to the collection declaration; import shorthand is deferred. The intended results can be expressed without settling operation names. Letters below denote record identities; `B*` is a higher-tier record with the same -identity as `B` and a different payload. The outcomes are settled; the ordering -shown is the recommendation discussed below. +identity as `B` and a different payload. The outcomes and ordering shown are +settled below. | Lower-tier sequence | Higher-tier sequence | Operation | Proposed result | | --- | --- | --- | --- | @@ -124,7 +124,7 @@ Mode describes the current tier's combination instruction. A lower tier's `append` does not silently select append for a later overlay. Gather collection declarations before composing their relevant scope so their effect does not depend on which contribution is assembled first. Identity agreement is settled -in OD-3; operation agreement and omission among peers remain under OD-4. +in OD-3; operation agreement and omission among peers are settled in OD-4. Permit sequence declarations in selected overlays and make their use independent of filesystem import enablement. This deliberately changes the current blanket @@ -271,6 +271,80 @@ absent contributions, null collections, and kind mismatches remain under OD-6. These structural rules do not settle final-result enforcement for YAML-only identity declarations, which remains the OD-1 follow-up. +### Combination Scope, Declarations, And Ordering + +**OD-4: settled.** + +#### 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 +governs all contributions to that collection in its tier, including imported and +inline records; it does not govern only records in the declaring file. + +Collection scope is the resolved destination within its composition scope. +Resolve relative destinations first and preserve separate item-local scopes for +collections inside different imported items. Apply the same combination +semantics to selected overlay contributions. + +For example, with an agreed identity, higher-tier fragments contributing `[C]` +and `[D]` assemble `[C, D]`. Against lower `[A, B]`, append or replacement by +identity produces `[A, B, C, D]`; whole-sequence replacement produces `[C, D]`. +The tier operation does not sequentially replace peer source contributions. + +#### Operation Agreement And Omission + +Coalesce agreeing explicit modes for the same collection within a tier and +reject conflicting explicit modes. Omission expresses no preference; apply the +default only after reconciling declarations. + +| Modes declared within one tier | Effective operation | +| --- | --- | +| `append` and `append` | `append` | +| `append` and omitted | `append` | +| `replace` and omitted | `replace` | +| `append` and `replace` | Error | +| All omitted | Default selected under OD-5 | + +Explicitly selecting the default is a real instruction and can conflict with +another explicit selection. Different modes in different tiers are valid; a +lower tier's mode does not carry forward. Neither a root declaration nor a later +declaration wins over conflicting peers. Diagnostics identify the collection +destination and conflicting declaration locations. Mode names remain +illustrative pending OD-5. + +#### Strict Duplicate Handling + +Duplicate identities among peer contributions or within one contributed list +remain strict-composition errors under all three modes. For example, peer +fragments contributing `[B]` and `[B*]` conflict even under replacement by +identity: neither has higher precedence. Lower `[B]` and higher `[B*]` can +instead produce `[B*]` at a precedence boundary. Whole-sequence replacement +does not permit duplicate identities within an identified higher-tier sequence. + +#### Ordering + +Retain existing dependency-ready source scheduling within each tier and authored +item order within each list. Gathering collection declarations does not change +assembly order, and identity values do not sort records. + +Across tiers: + +- Append retains lower records in order, followed by higher records in assembled + order. +- Whole-sequence replacement retains only the higher sequence, in its assembled + order. +- Replacement by identity replaces matched records in their existing lower + positions and appends new identities in higher-tier order. + +For example, lower `[A, B, C]` and higher `[C*, A*, D]` produce +`[A*, B, C*, D]` under replacement by identity. Updating a record's contents +preserves its position; whole-sequence replacement gives the higher tier control +of the complete sequence order. + +OD-5 retains default selection and operation naming. Absent contributions, empty +sequences, null, and kind mismatches remain under OD-6. + ### Whole-Record Replacement By Identity The third cross-tier operation replaces each matching lower record with the @@ -310,8 +384,8 @@ For an existing sequence `[foo, bar]`: Here `foo*` has the same identity as `foo` and supplies its complete replacement record. Append retains its duplicate-identity error semantics. The retained -records and replacement behavior are settled; ordering shown follows the -recommendation under OD-4. +records, replacement behavior, and ordering shown are settled, including the +OD-4 rule that matched records retain their lower positions. The settled OD-2 collection declaration supplies the overlay authoring surface. OD-5 retains operation naming and default selection. The current @@ -362,27 +436,14 @@ identity values. The guarantee requires neither a new mutation-history system nor exact causal reconstruction for records supplied by defaults or callbacks. Final enforcement for identities declared only in YAML is not settled here. -## Initial Architectural Direction +## Architectural Direction The settled collection declaration gives imported and inline records at the same destination a shared identity policy. Declarations are gathered before composing the relevant scope. -The initial recommendation is to compose each tier's contributions strictly, -then apply one collection operation from the higher tier against the lower -sequence. A collection declaration would therefore govern its tier's contribution -at that destination, without sequentially erasing peer contributions. Multiple -agreeing operation declarations could coalesce; conflicting explicit operations -would produce errors. Identity declaration agreement is already settled in OD-3. - -For append, the ordering recommendation is to retain lower-tier item order and -then the higher tier's assembled item order. For replacement by identity, retain -the position of each replaced record and append new identities in higher-tier -order. Existing dependency-ready scheduling would continue to determine assembly -order within a tier. Whole-sequence replacement would retain only the higher -tier's assembled sequence. Ordering and the treatment of peer operation -declarations remain recommendations awaiting agreement, not changes to the -current ordering contract. +OD-3 settles identity agreement and lifetime; OD-4 settles tier-wide operation +selection, strict peer composition, and ordering at precedence boundaries. This requires collection policy to survive import expansion through precedence assembly. Correctness includes final values, projected item paths, source @@ -432,39 +493,12 @@ Limiting YAML-only identity to assembly keeps policy lifetime narrower, but late operations could produce a final collection that no longer satisfies that identity declaration. -### OD-4. What Does A Combination Choice Control? - -What happens when peer collection declarations at the same destination -request different operations, or when some contributions omit the operation? -Settle ordering for replacement by identity, including where replaced records -and new identities appear. Apply the same operation semantics to selected -overlay contributions. - -**Initial recommendation:** Assemble one strict sequence per destination in -each tier, then apply its agreed operation at the precedence boundary. Reject -conflicting explicit choices within a tier. This preserves peer composition and -prevents declaration or scheduling order from granting replacement authority. -Define how omitted choices use the effective operation within the current tier; -OD-2 settles that a lower tier's mode is not inherited by a later tier. -Duplicate identities among peers would remain strict-composition errors under -all three cross-tier operations. For replacement -by identity, keep matched records in their lower-tier positions and append new -identities in higher-tier order. - -**Alternative:** Apply collection declarations as sequential operations on their -associated source contributions. This permits deliberate resets within a tier, -but a replacement can discard peer contributions and would require an explicitly -selected operation-order model. - -For ordering, moving replaced records to their higher-tier contribution positions -is another viable choice. It gives the higher layer more influence over ordering, -but changing a record's payload could also move it relative to retained records. - ### OD-5. What Is The Default Operation And Its Syntax? Choose names for the three `mode` values and decide the default operation. OD-2 settles the declaration structure and accepts explicit selection of the -default. Omission among peer declarations remains under OD-4. +default. OD-4 settles omission as no preference among peer declarations, with the +default applied after reconciliation. **Initial recommendation:** Keep whole-sequence replacement as the cross-tier default and make append and replacement by identity explicit. Lists can represent