diff --git a/docs/roadmap/sequences.md b/docs/roadmap/sequences.md index d3fcdf5..97c327f 100644 --- a/docs/roadmap/sequences.md +++ b/docs/roadmap/sequences.md @@ -118,6 +118,31 @@ The lower record's `temperature` is discarded. Subsequent defaulting or other lifecycle operations retain their separately defined semantics. Recursive field-by-field overlay of matching records is outside this selected operation. +### Selected Overlay Control + +Selected overlay authors must be able to choose any of the three operations +for a sequence supplied by the overlay, including records authored inline. +The operation applies against the existing effective sequence at that path. +For an existing sequence `[foo, bar]`: + +| Overlay contribution | Selected operation | Result | +| --- | --- | --- | +| `[foo*]` | Replacement by identity | `[foo*, bar]` | +| `[baz]` | Append | `[foo, bar, baz]` | +| `[bar, baz]` | Whole-sequence replacement | `[bar, baz]` | + +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. + +An import-only declaration mechanism cannot cover inline overlay sequences. +OD-2 must provide an overlay-authorable declaration site, and OD-5 must select +operation names and omission behavior. The current +[selected-overlay contract](../config.md#selected-overlays) prohibits `configkit` +in overlays. Any new control syntax must explicitly account for that boundary; +supporting sequence controls does not itself require enabling overlay imports. + ### Optional Application-Owned Identity Constraints Retain an interface through which applications may register a collection and @@ -234,24 +259,27 @@ produce a final collection that no longer satisfies that identity declaration. ### OD-2. Where Does Configuration Declare Collection Policy? -Is `key` on a `sequence-item` import sufficient, or should configuration have a -collection declaration that also covers inline sequences, ordinary mapping -imports containing sequences, and selected overlays? How does such a declaration -address a collection inside an imported item? +Where should configuration declare collection identity and combination choices +for imported items, inline sequences, and sequences supplied by ordinary mapping +imports? Selected overlays must support author selection of all three operations +for inline sequences. How does a declaration address a collection inside an +imported item? **Initial recommendation:** Define one destination-scoped collection policy -model first. Evaluate a configuration-level declaration alongside import syntax -against these workflows before selecting the surface. Collection identity must -apply consistently to all participating records at that destination, including -inline records. Resolve relative destinations and item-local scopes using their -existing ownership boundaries. +model first. Prefer a configuration-level collection declaration usable in base +sources and selected overlays, with import annotations considered as shorthand. +This gives inline and imported records a common policy surface. Collection +identity must apply consistently to all participating records at that +destination. Resolve relative destinations and item-local scopes using their +existing ownership boundaries. Define the sequence controls accepted in overlays +explicitly, including their relationship to the current `configkit` prohibition. -**Alternative:** Limit this feature to policies declared on item imports. This -keeps the initial syntax small and directly serves imported prompt collections, -but leaves inline-only collections and overlay-authored append without a natural -declaration site. A separate collection declaration covers those cases at the -cost of more configuration structure; an import shorthand would require a clear -relationship to that declaration. +**Alternative:** Put controls beside each sequence through a local wrapper or +directive form. This keeps the operation close to the affected value and supports +inline overlay records, but requires distinguishing control syntax from +application data and defining how imported contributions share that policy. +A configuration-level declaration adds path references and configuration +structure; import shorthand also needs a clear relationship to that declaration. ### OD-3. What Constitutes Identity, And When Can It Change? @@ -274,12 +302,13 @@ support more schemas but add type-equality and addressing rules. A load-wide fix identity definition simplifies agreement across tiers; allowing a replacement to establish a new definition gives independently authored layers more flexibility. -### OD-4. What Does An Import's Combination Choice Control? +### OD-4. What Does A Combination Choice Control? -What happens when peer imports into 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. +What happens when peer imports or 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 @@ -351,10 +380,10 @@ version headers? precedence assembly. Validate records at the relevant collection assembly boundaries and uniqueness across each combined result. Preserve existing typed-default and application-resolution semantics unless their inclusion is -explicitly chosen. Decide selected-overlay coverage with OD-2; it is part of -source precedence but currently has no import declaration site. Account for -item-local helpers and source-version consumption before deciding identity is -available, consistent with the current lifecycle. +explicitly chosen. Selected-overlay combination is included in the settled scope; +its declaration mechanism remains under OD-2. Account for item-local helpers and +source-version consumption before deciding identity is available, consistent +with the current lifecycle. The settled OD-1 guarantee covers final validation of application constraints. Validating the final collection does not itself change how defaults, inheritance,