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

Settle the sequence identity registration API

Browse Source
This commit is contained in:
Eric Rakestraw
2026-10-23 12:09:44 +00:00
parent a5f0b92ee9
commit 749cf6868c
1 changed files with 47 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

82
docs/roadmap/roadmap.md
View File

@@ -1,10 +1,9 @@
# Sequence Identity And Combination Roadmap # Sequence Identity And Combination Roadmap
Status: feature roadmap with dynamic application identity constraints included. Status: settled feature roadmap, ready for a staged implementation plan. This
The remaining registration API 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, exact Go names and signatures, internal bookkeeping,
implemented contract. The subsequent plan will specify execution order, exact and validation stages.
Go names and signatures, internal bookkeeping, and validation stages.
## Purpose And Scope ## Purpose And Scope
@@ -227,6 +226,37 @@ a path to exist, be non-null, or have sequence shape. The application schema and
validation own those requirements. Final-result enforcement for application validation own those requirements. Final-result enforcement for application
registrations is defined under [Validation And Diagnostics](#validation-and-diagnostics). registrations is defined under [Validation And Diagnostics](#validation-and-diagnostics).
### Application Registration API
Use one public sequence-identity registration type, collected in one field on
`Definition`. Each registration contains an explicit destination selector and
its identity fields. Exact and dynamic registrations share matching, overlap
validation, identity comparison, and lifecycle behavior.
Provide two constructors returning that same registration type:
- An exact-path convenience constructor accepting a literal `Path` and identity
field names. It converts the path into a selector containing literal segments.
- An explicit-selector constructor accepting a structural selector and identity
field names, for destinations that include arbitrary mapping keys.
Both constructors accept identity fields as variadic strings, so one-field and
compound identities use the same construction form. Apply the settled field-set
rules, including deduplication. Invalid registrations, including an empty identity
field set, fail during application-definition validation.
Existing `Path` values retain their literal meaning throughout ConfigKit. The
exact-path constructor supplies convenience at the registration boundary; dynamic
matching uses the explicit selector type. Both forms can appear together in the
same definition field.
Replace the current registration shape with this model. Preserving the existing
`SequenceComposition` fields and `Definition.SequenceCompositions` spelling is not
a requirement, and no compatibility facade is needed solely to retain that syntax.
Choose names centered on sequence identity, reflecting its role in composition,
inheritance, and final validation. Exact Go type, field, and constructor names
and signatures belong in the implementation plan.
### Dynamic Application Registration Destinations ### Dynamic Application Registration Destinations
Allow applications to register identity for collections whose containing mapping Allow applications to register identity for collections whose containing mapping
@@ -844,10 +874,12 @@ The implementation plan should cover these connected changes, with execution
order and test sequencing defined there: order and test sequencing defined there:
- **Declarations and public API:** extend application registration to the settled - **Declarations and public API:** extend application registration to the settled
identity model and explicit structural selectors while preserving literal identity model with one public registration type and definition field, an
`Path` semantics. Parse and consume `configkit.sequences` across supported source exact-path convenience constructor, and an explicit-selector constructor.
forms and selected overlays; preserve placement-relative and item-local scopes. Preserve literal `Path` semantics. Parse and consume `configkit.sequences` across
Keep sequence declarations independent of filesystem import enablement. supported source forms and selected overlays; preserve placement-relative and
item-local scopes. Keep sequence declarations independent of filesystem import
enablement.
- **Identity and policy representation:** implement field-set comparison, typed - **Identity and policy representation:** implement field-set comparison, typed
scalar identity tuples with exact numeric equality, declaration agreement, scalar identity tuples with exact numeric equality, declaration agreement,
pending declarations, explicit-mode persistence, replacement lifetime, and pending declarations, explicit-mode persistence, replacement lifetime, and
@@ -895,6 +927,9 @@ order and test sequencing defined there:
preserve ordinary strict-peer and upsert behavior. Check YAML disagreement under preserve ordinary strict-peer and upsert behavior. Check YAML disagreement under
replace, harmless absent or empty collections, schema-owned shape requirements, replace, harmless absent or empty collections, schema-owned shape requirements,
unrelated sequences remaining unselected, and concrete-path diagnostics. unrelated sequences remaining unselected, and concrete-path diagnostics.
Verify both constructors feed the same registration model, including mixed
exact and dynamic registrations, compound identities, and definition-time
rejection of empty identity field sets.
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
@@ -912,29 +947,6 @@ status while preserving its decision content. The architecture policy is aligned
Dynamic selectors extend the destinations covered by application registration; Dynamic selectors extend the destinations covered by application registration;
they retain the accepted application authority and final-validation boundary. they retain the accepted application authority and final-validation boundary.
After settling the API decision below, the implementation plan should translate No open feature decisions remain. The implementation plan should translate this
this end state into reviewable stages without adding guarantees, restrictions, end state into reviewable stages without adding guarantees, restrictions, or
or combination semantics. combination semantics.
## Open Decisions
### Registration API Shape
The selector's behavior and definition-time overlap validation are settled. How
should the public registration represent exact destinations alongside selectors
containing arbitrary-mapping-key segments?
**Recommendation:** use one registration model with an explicit selector type
whose segments distinguish literal keys from arbitrary mapping keys. Provide a
straightforward way to construct an exact selector from a literal `Path`.
Both forms then share identity fields, validation, and lifecycle behavior, while
ordinary `Path` remains unchanged. This requires a small new public type, but
keeps one registration surface and avoids mutually exclusive destination fields.
Exact Go names and constructor signatures belong in the implementation plan.
**Alternative:** retain exact-path registrations and add a separate dynamic
registration form, normalizing both into the same internal selector model.
This keeps exact registration familiar for simple consumers, but introduces two
public forms with the same identity rules and requires overlap validation across
both. Both choices must preserve the settled matching and enforcement behavior;
neither introduces selector syntax into ordinary paths or YAML destinations.