diff --git a/docs/roadmap/roadmap.md b/docs/roadmap/roadmap.md index e7946c5..ebc8ef8 100644 --- a/docs/roadmap/roadmap.md +++ b/docs/roadmap/roadmap.md @@ -1,10 +1,9 @@ # Sequence Identity And Combination Roadmap -Status: feature roadmap with dynamic application identity constraints included. -The remaining registration API decision is recorded under -[Open Decisions](#open-decisions). This is the targeted end state, not an -implemented contract. The subsequent plan will specify execution order, exact -Go names and signatures, 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, exact Go names and signatures, internal bookkeeping, +and validation stages. ## 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 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 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: - **Declarations and public API:** extend application registration to the settled - identity model and explicit structural selectors while preserving literal - `Path` semantics. Parse and consume `configkit.sequences` across supported source - forms and selected overlays; preserve placement-relative and item-local scopes. - Keep sequence declarations independent of filesystem import enablement. + identity model with one public registration type and definition field, an + exact-path convenience constructor, and an explicit-selector constructor. + Preserve literal `Path` semantics. Parse and consume `configkit.sequences` across + 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 scalar identity tuples with exact numeric equality, declaration agreement, 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 replace, harmless absent or empty collections, schema-owned shape requirements, 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. 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; they retain the accepted application authority and final-validation boundary. -After settling the API decision below, the implementation plan should translate -this end state into reviewable stages without adding guarantees, restrictions, -or 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. +No open feature decisions remain. The implementation plan should translate this +end state into reviewable stages without adding guarantees, restrictions, or +combination semantics.