From 3298eb916cc1bddee71a2f6114f50901faf8ebcf Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 23 Oct 2026 01:40:37 +0000 Subject: [PATCH] Settle how sequence inheritance references compose --- docs/roadmap/roadmap.md | 72 ++++++++++++++++------------------------- 1 file changed, 27 insertions(+), 45 deletions(-) diff --git a/docs/roadmap/roadmap.md b/docs/roadmap/roadmap.md index 631a905..605ffb9 100644 --- a/docs/roadmap/roadmap.md +++ b/docs/roadmap/roadmap.md @@ -1,10 +1,9 @@ # Sequence Identity And Combination Roadmap -Status: feature roadmap with the accepted scope extended to inheritance between -identified sequence records. The remaining decision is recorded under -[Open Decisions](#open-decisions). This is the targeted end state, not an -implemented contract. The subsequent implementation plan will specify execution -order, the exact Go API, internal bookkeeping, and validation stages. +Status: settled feature roadmap, ready for a staged implementation plan. This +is the targeted end state, not an implemented contract. The subsequent plan will +specify execution order, the exact Go API, internal bookkeeping, and validation +stages. ## 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 field-set and scalar-equality rules, including mathematical numeric equality. `extends: {id: null}` selects a null-valued identity; `extends: null` cancels a -relationship. The remaining question about assembling reference mappings is -recorded under [Open Decisions](#open-decisions). +relationship. + +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 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 and chains, missing parents and cycles, parent replacement/removal, child identity 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. 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 select migration machinery. -The added identified-sequence sibling scope requires an architectural follow-up -before implementation: record the extension to the scope retained by -[ADR 0009](../adr/0009-sibling-inheritance.md) and ADR 0017, and align the -architecture policy. Their existing scope statements do not yet describe this -addition. Keep the final application-registration guarantee unchanged. +Before implementation, finalize the ADR 0017 revision for inheritance within +identified sequences, update the supersession status of +[ADR 0009](../adr/0009-sibling-inheritance.md), and align the architecture policy. +Preserve ADR 0009's decision content and the final application-registration +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 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.