eric/ConfigKit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Settle how sequence inheritance references compose

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-23 01:40:37 +00:00
parent 40430e787c
commit 3298eb916c
1 changed files with 27 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

72
docs/roadmap/roadmap.md
View File

@@ -1,10 +1,9 @@
# Sequence Identity And Combination Roadmap # Sequence Identity And Combination Roadmap
Status: feature roadmap with the accepted scope extended to inheritance between Status: settled feature roadmap, ready for a staged implementation plan. This
identified sequence records. The remaining decision is recorded under is the targeted end state, not an implemented contract. The subsequent plan will
[Open Decisions](#open-decisions). This is the targeted end state, not an specify execution order, the exact Go API, internal bookkeeping, and validation
implemented contract. The subsequent implementation plan will specify execution stages.
order, the exact Go API, internal bookkeeping, and validation stages.
## Purpose And Scope ## Purpose And Scope
@@ -556,8 +555,21 @@ Use mapping-form references for both single and compound keys. With
`extends: {namespace: shared, id: base}`. Match components using the collection's `extends: {namespace: shared, id: base}`. Match components using the collection's
field-set and scalar-equality rules, including mathematical numeric equality. field-set and scalar-equality rules, including mathematical numeric equality.
`extends: {id: null}` selects a null-valued identity; `extends: null` cancels a `extends: {id: null}` selects a null-valued identity; `extends: null` cancels a
relationship. The remaining question about assembling reference mappings is relationship.
recorded under [Open Decisions](#open-decisions).
Parent-reference mappings use ordinary strict mapping composition. Item-local
helper imports may supply disjoint fields of a compound reference; overlapping
fields conflict, even when equal. For example, a helper's
`extends: {namespace: shared}` and the importing record's `extends: {id: base}`
compose into `extends: {namespace: shared, id: base}`. This assembles one record;
it does not permit strict peers to contribute duplicate record identities.
Before parent lookup, require the surviving effective reference mapping to contain
exactly the collection's identity fields, with supported scalar values. Missing
or extra fields fail. Validate the completed reference during inheritance, rather
than requiring each helper contribution to be independently complete. Superseded
references remain historical evidence; earlier strict-composition conflicts
remain errors.
Every record must supply its complete own identity before inheritance. Preserve Every record must supply its complete own identity before inheritance. Preserve
the child's identity fields and inherit only the parent's nonidentity payload; the child's identity fields and inherit only the parent's nonidentity payload;
@@ -754,6 +766,8 @@ order and test sequencing defined there:
Cover single and compound parent references, scalar equality, forward references Cover single and compound parent references, scalar equality, forward references
and chains, missing parents and cycles, parent replacement/removal, child identity and chains, missing parents and cycles, parent replacement/removal, child identity
preservation, nested destination policy, cancellation, and stable output order. preservation, nested destination policy, cancellation, and stable output order.
Verify helper-composed references, overlapping reference fields, missing or extra
fields, and replacement of references together with their containing records.
Update the public contract and consumer examples when behavior lands. Update the public contract and consumer examples when behavior lands.
The collection-policy and CLI-ordering decisions are accepted in The collection-policy and CLI-ordering decisions are accepted in
@@ -765,44 +779,12 @@ These govern the target architecture; the configuration contract continues to
describe implemented behavior until the feature lands. This roadmap does not describe implemented behavior until the feature lands. This roadmap does not
select migration machinery. select migration machinery.
The added identified-sequence sibling scope requires an architectural follow-up Before implementation, finalize the ADR 0017 revision for inheritance within
before implementation: record the extension to the scope retained by identified sequences, update the supersession status of
[ADR 0009](../adr/0009-sibling-inheritance.md) and ADR 0017, and align the [ADR 0009](../adr/0009-sibling-inheritance.md), and align the architecture policy.
architecture policy. Their existing scope statements do not yet describe this Preserve ADR 0009's decision content and the final application-registration
addition. Keep the final application-registration guarantee unchanged. guarantee. These architectural revisions remain subject to review.
After settling the decision below, the implementation plan should translate this No open feature decisions remain. The implementation plan should translate this
end state into reviewable stages without adding guarantees, restrictions, or end state into reviewable stages without adding guarantees, restrictions, or
combination semantics. combination semantics.
## Open Decisions
### Assembly And Validation Of Parent References
The effective reference must identify one parent by its complete identity. Should
each supplied reference be complete independently, or may item-local helper
imports compose its fields before inheritance resolves it?
**Recommendation:** use ordinary strict mapping composition for the reference,
then require the effective mapping to contain exactly the collection's identity
fields, with scalar values, before parent lookup. Disjoint helper contributions
may assemble a compound reference; overlapping fields conflict under the usual
strict rules, even when equal. This follows the existing ability of helpers to
assemble a record and its identity, and avoids special atomic-composition rules
for this one mapping. A partial contribution alone cannot select a parent.
Authors must understand that disjoint contributions form one reference.
Whole-record upsert still replaces the directive with its containing record,
so this choice does not merge old and new reference components across matching
records in different tiers. It also does not permit strict peers to contribute
duplicate record identities. Validate the surviving effective reference in the
inheritance phase, consistent with existing treatment of superseded relationships.
**Alternative:** treat each non-null reference mapping as one complete, atomic
selector. Require exactly the identity fields in each declaration; two supplied
selectors conflict under strict composition even if their fields are disjoint.
This makes the relationship self-contained and prevents helpers from accidentally
constructing an unintended compound parent identity. It needs special treatment
of directive mappings and prevents intentional composition that ordinary record
fields support. Keep whole-record replacement and active-relationship timing
unchanged under either choice.