Settle sequence combination scope and ordering

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
+identity as `B` and a different payload. The outcomes and ordering shown are
-shown is the recommendation discussed below.
+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
+records, replacement behavior, and ordering shown are settled, including the
-recommendation under OD-4.
+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,
+OD-3 settles identity agreement and lifetime; OD-4 settles tier-wide operation
-then apply one collection operation from the higher tier against the lower
+selection, strict peer composition, and ordering at precedence boundaries.
-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.
 
 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