78 lines
3.8 KiB
Markdown
78 lines
3.8 KiB
Markdown
# ADR 0014: Place and Compose Sequence Items Explicitly
|
|
|
|
## Status
|
|
|
|
Accepted and implemented. The [configuration contract](../config.md#strict-document-composition)
|
|
defines current behavior, and the [consumer guide](../consumers/README.md#identified-prompt-sequences)
|
|
shows the maintained example. The completed roadmap, implementation plan, and
|
|
resolved remediation record are preserved in Git history at `008d2ba` under
|
|
`docs/roadmap/`; see the [development guide](../development.md) for retrieval
|
|
commands.
|
|
|
|
## Date
|
|
|
|
2026-10-16
|
|
|
|
## Context
|
|
|
|
ConfigKit strictly composes independent documents by recursively combining
|
|
mappings and rejecting other overlapping values. This makes two independently
|
|
authored sequence fragments conflict, even when their records are distinct.
|
|
Precedence assembly has a different purpose: a higher-priority present sequence
|
|
replaces the lower-priority sequence as one value. Those existing rules are
|
|
predictable, but they do not express the separate operation of collecting
|
|
independent records while rejecting duplicate identities.
|
|
|
|
Likewise, mapping destinations place a source beneath literal mapping keys, but
|
|
there is no explicit way to state that a source mapping represents one item in a
|
|
sequence. Inferring that intent from document shape or fields would make source
|
|
meaning implicit and change existing placement behavior.
|
|
|
|
## Decision
|
|
|
|
Keep mapping placement as the zero-value behavior and add an explicit item
|
|
placement choice for a source whose mapping should become one element at a
|
|
non-root sequence destination. Item placement provides structure only; it does
|
|
not infer or synthesize identity values.
|
|
|
|
Allow a definition to register literal mapping paths and one literal identity
|
|
field for sequences at those paths. Within each strict composition tier, a
|
|
registered sequence accepts mapping records with a present string identity,
|
|
appends distinct records in contribution order, and rejects repeated exact
|
|
identity strings. Identical registrations coalesce; conflicting identity fields
|
|
for the same path are invalid. Registration does not recursively select paths
|
|
inside sequence records.
|
|
|
|
Keep precedence assembly unchanged. A present higher-priority sequence replaces
|
|
the lower-priority value wholesale, including at a registered path. Registration
|
|
changes strict composition only; it does not turn precedence into append or
|
|
identity-based merging.
|
|
|
|
This decision preserves ConfigKit's distinction between independent
|
|
same-priority contributions and intentional precedence. Explicit source
|
|
placement and definition-owned composition policy make the two required choices
|
|
visible while keeping the existing zero-value load behavior.
|
|
|
|
## Alternatives Considered
|
|
|
|
- **Infer item placement from a source mapping or identity field.** Shape-based
|
|
inference would make ordinary mapping placement depend on document contents
|
|
and would leave the intended destination ambiguous.
|
|
- **Append all overlapping sequences during strict composition.** This would
|
|
change existing conflict semantics at unregistered paths and would not detect
|
|
duplicate records.
|
|
- **Merge matching records recursively by identity.** This would add a second
|
|
recursive merge rule with different conflict and precedence behavior from
|
|
ConfigKit's existing mapping composition and overlay operations.
|
|
- **Use identity to merge sequences across precedence tiers.** This would
|
|
change established whole-value replacement semantics and conflate strict
|
|
composition with precedence.
|
|
|
|
## Consequences
|
|
|
|
Consumers can explicitly place mappings as sequence items and opt selected
|
|
sequences into duplicate-rejecting strict composition. Unregistered sequences
|
|
retain their current strict-conflict behavior, and higher-priority sequences
|
|
continue to replace lower-priority ones. The implementation plan owns the exact
|
|
API, YAML syntax, diagnostics, and implementation status.
|