diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index c7ff81d..354979c 100644 --- a/docs/roadmap/sequences.md +++ b/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 -the targeted behavior for review before preparing a staged implementation plan. -It is not an implementation plan or an implemented contract. +Status: feature roadmap with OD-1 through OD-7 settled and follow-up interaction +decisions OD-8 through 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 +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 -resolution retains its existing assignment and recorded-transformation semantics; -ConfigKit does not automatically combine a callback's assigned sequence with +CLI overrides retain explicit replacement for supplied sequences. OD-8 addresses +how that intent interacts with inheritance, which currently runs afterward. +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.