Record remaining sequence lifecycle decisions

docs/roadmap/sequences.md

@@ -1,8 +1,10 @@
 # Sequence Identity And Combination
 
-Status: feature roadmap with OD-1 through OD-7 settled. This document captures
+Status: feature roadmap with OD-1 through OD-7 settled and follow-up interaction
-the targeted behavior for review before preparing a staged implementation plan.
+decisions OD-8 through OD-11 open. The original decisions establish the intended
-It is not an implementation plan or an implemented contract.
+operations; the new questions address their lifecycle and policy-scope boundaries.
+Resolve these questions before preparing a staged implementation plan. This is
+not an implementation plan or an implemented contract.
 
 ## Motivation
 
@@ -114,6 +116,7 @@ relative to the declaring source's placement: a fragment mounted under
 `catalog` can declare `[prompts]` locally. A sequence-item source can declare a
 nested collection within its own item without referring to an eventual numeric
 index. Preserve those source and item-local scope boundaries.
+OD-11 addresses policy ownership when enclosing records are replaced or inherited.
 
 Identity and mode can be supplied independently. Omitted identity can use an
 application registration; an explicit matching declaration is accepted, and a
@@ -127,6 +130,7 @@ and inheritance boundaries, as detailed in OD-7. A lower tier's
 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 are settled in OD-4.
+OD-9 addresses which controls survive source precedence for later inheritance.
 
 Permit sequence declarations in selected overlays and make their use independent
 of filesystem import enablement. This deliberately changes the current blanket
@@ -244,6 +248,9 @@ 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.
+
 An application registration supplies identity when configuration omits it and
 remains authoritative over explicit declarations. If neither the application nor
 either participating collection supplies an identity, append and replacement by
@@ -601,9 +608,10 @@ application-supplied mapping sources. Typed `Definition.Defaults` remain the
 initial decoded state: supplied sequences replace default sequences. Source
 `mode: append` does not append to a typed default list.
 
-CLI overrides retain explicit replacement for supplied sequences. Application
+CLI overrides retain explicit replacement for supplied sequences. OD-8 addresses
-resolution retains its existing assignment and recorded-transformation semantics;
+how that intent interacts with inheritance, which currently runs afterward.
-ConfigKit does not automatically combine a callback's assigned sequence with
+Application resolution retains its existing assignment and recorded-transformation
+semantics; ConfigKit does not automatically combine a callback's assigned sequence with
 its previous value. Application-registered identities still receive final
 validation under OD-1, independently of how these stages produce their values.
 
@@ -658,7 +666,121 @@ 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 review of this settled roadmap.
+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
 processing, identity validation, precedence, inheritance, and inspection together.
 Public API design and test sequencing belong to that later plan.
+
+## Open Decisions
+
+### OD-8. CLI Replacement And Subsequent Inheritance
+
+The current lifecycle applies CLI overrides before resolving inheritance, as
+specified in [ADR 0009](../adr/0009-sibling-inheritance.md). OD-7 preserves CLI
+sequence replacement while introducing identity-aware inheritance. Without an
+explicit interaction rule, inherited `[A, B]` and a CLI-supplied local `[C]` could
+produce `[A, B, C]` under inferred upsert, undoing the CLI's replacement intent.
+An application registration can supply identity even if replacement discards a
+lower YAML-only declaration.
+
+**Recommendation:** Preserve lifecycle ordering and carry explicit CLI sequence
+replacement intent through inheritance at the overridden destination. The result
+in this example should remain `[C]`, including when a YAML declaration selects
+append or upsert. No additional caller flag should be needed. Identity constraints
+and ordinary validation still apply; replacement intent does not bypass them.
+This preserves CLI authority while allowing CLI-supplied `extends` directives to
+participate in the existing inheritance pass.
+
+Define coverage for sequences supplied directly and sequences inside a supplied
+mapping, as well as empty sequences and explicit null replacements. Coordinate
+with OD-11 when overridden content is subsequently inherited elsewhere; avoid
+turning a destination's override into a load-wide replacement policy.
+
+**Alternative:** Resolve inheritance before applying CLI overrides. CLI values
+would then naturally be last and would need no inheritance replacement marker.
+However, this changes the established lifecycle: CLI-supplied or cancelled
+relationships would no longer affect that inheritance pass, and relationships
+that the CLI would supersede could be resolved or rejected prematurely. Supporting
+those cases would require additional lifecycle design beyond sequence combination.
+
+### OD-9. Which Controls Survive Until Inheritance?
+
+OD-4 prevents a lower tier's mode from selecting a later tier's operation, while
+OD-7 retains destination controls for inheritance after source assembly. The
+roadmap needs an explicit rule for a collection left untouched by a higher tier,
+a newly supplied sequence with no mode, and declarations supplied without values.
+For example, does an unrelated selected overlay erase a main source's explicit
+replace instruction for a collection that later inherits records?
+
+**Recommendation:** Distinguish untouched collections from new contributions.
+Retain relevant controls for an untouched collection's later inheritance. When
+a higher tier supplies a new sequence contribution, select its operation from
+that tier's declarations and the effective-identity default; do not reuse the
+lower mode. Permit a declaration without a sequence value to control later
+inheritance without clearing the collection. Express these cases in a policy
+lifetime table covering absent values, key-only and mode-only declarations,
+explicit operations, and replacement of a collection or an enclosing subtree.
+Identity changes must still satisfy OD-3.
+
+This preserves intentional inheritance controls across unrelated overlays while
+keeping each new sequence contribution's precedence operation local to its tier.
+
+**Alternative:** Maintain a destination policy independently of value survival,
+letting higher explicit policy fields override lower ones and omissions inherit
+them. This makes declaration-only configuration straightforward, but modes can
+become sticky when new values arrive. Applying that policy only to inheritance
+would preserve OD-4 at the cost of two distinct policy-resolution rules; applying
+it to source precedence would require revisiting OD-4.
+
+### 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
+identity to surviving collections. Specify what happens to those policies when
+an enclosing record is upserted, replaced, moved, or copied through inheritance.
+For example, replacing record `foo` wholesale must account for the old record's
+declaration governing `foo.steps`; keeping the numeric index alone does not
+establish that the old policy still belongs there.
+
+**Recommendation:** Attach item-local policies to their owning contributions so
+they follow surviving records independently of numeric indexes. Whole-record
+replacement discards policies owned by the discarded record. Distinguish inherited
+collection identity from operation instructions: copied identity may follow a
+surviving collection, while the inheriting destination selects its operation under
+OD-7. Application registrations remain constraints at their registered destinations.
+Provide nested examples showing retained records, replaced records, inherited
+copies, and agreement with declarations at the destination. This protects the
+established whole-record replacement semantics and prevents stale policies from
+attaching to unrelated records after reindexing.
+
+**Alternative:** Keep configuration policies solely in a destination registry and
+rebind them after structural changes. This offers centralized lookup, but numeric
+paths cannot safely identify changing records, and item-local declarations still
+need ownership information to distinguish policies that should survive from
+policies whose declaring records were discarded. Requiring declarations again at
+each inherited destination reduces transfer rules but makes reusable fragments
+more repetitive and would narrow the current identity-follows-collection model.