diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 6995648..39c14a3 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -1,8 +1,7 @@ # ConfigKit v1 Adoption And Identified Resource Collections -Status: accepted direction; implementation pending. The source-builder API -choice at the end remains open. This roadmap describes future behavior, not -the currently supported configuration format. +Status: accepted direction; implementation pending. This roadmap describes +future behavior, not the currently supported configuration format. ## Purpose @@ -130,6 +129,25 @@ in the assembled list shape, including its index-based paths and provenance. Do not impose a new execution-order meaning on list position or change the existing inventory sorting solely because source resources become lists. +### Go Source-Builder Inputs + +Add an `ID string` field to `ProfileConfig` and `BackendConfig`. Change +`ProfileSource` to accept `[]ProfileConfig` and `BackendSource` to accept +`[]BackendConfig`, replacing their keyed-map inputs. Emit each value as a record +with its explicit `id`, preserving the caller's slice order. Retain +`ProfileConfig.Extends` as a convenient parent-ID string and encode it as +`extends: {id: ...}`. + +This makes Go and YAML resource definitions consistent and preserves duplicate +IDs when callers combine catalogs, allowing ConfigKit to reject them during +loading. The helpers continue encoding sources without independently validating +the final configuration. Preserving input order does not give it execution +significance. Callers that maintain keyed maps can convert them at this boundary. + +Make this public API change as part of the coordinated pre-v1 migration rather +than retaining a second input representation for compatibility. Update callers, +examples, and migration guidance together. + ### Inheritance And Layering Identified siblings inherit using `extends: {id: parent-id}`. This applies to @@ -245,11 +263,12 @@ against the effective field's contributing source after inheritance and upsert. Retain one ConfigKit load and the existing effective-value handoff; source history must not become a second resolver. -Update `BackendSource`, `ProfileSource`, and profile inheritance encoding to emit -the list format, following the open API decision below. Update namespace views, -listing, inspection, prepared execution, and smoke-test selection as needed to -consume the same captured runtime indexes. Do not change their selection or -execution semantics merely to mirror the new configuration representation. +Update `BackendSource`, `ProfileSource`, and their public configuration values to +use explicit-ID slices and encode profile inheritance as an identity reference. +Update namespace views, listing, inspection, prepared execution, and smoke-test +selection as needed to consume the same captured runtime indexes. Do not change +their selection or execution semantics merely to mirror the new configuration +representation. ### 3. Exercise The Integrated Target @@ -270,6 +289,8 @@ Use focused behavioral coverage for the changed boundaries: versions and obsolete resource shapes fail through their owning validators. - Public source builders, namespace lookup, inspection, preparation, validation, smoke tests, and execution still work with the converted catalogs. +- Source builders preserve supplied record order and duplicate IDs for loading; + profile parent-ID strings produce the expected sibling inheritance references. Run the existing suite, relevant vet checks, and maintained offline consumer examples under Go 1.27. Tests require no live provider calls. Reuse existing @@ -282,6 +303,7 @@ Update the [format reference](../formats.md), [consumer migration guide](../cons [Go consumer guide](../consumers/pkg-promptkit.md), source-adapter documentation, GoDoc, and maintained examples as implementation lands. Explain the module/type change, Go minimum, `config:` controls, import requiredness, resource lists, +the source builders' map-to-slice conversion and explicit `ID` fields, mapping-to-record `extends` conversion, removed prompt labels, specification headers, and index-based inspection paths together. @@ -297,23 +319,3 @@ dual-format decoding, source rewriting, catalog discovery conventions, or a compatibility module. Preserve operator choices already supplied by ConfigKit. Once implementation is complete, move durable behavior into its canonical owners and retire this temporary roadmap under repository practice. - -## Open Decisions - -### Go Source-Builder Inputs - -**Recommendation:** retain the keyed-map inputs to `BackendSource` and -`ProfileSource`, translating each key into the emitted record's `id`. Retain -`ProfileConfig.Extends` as a convenient parent-ID string and encode it as -`extends: {id: ...}`. Emit records in deterministic key order. These helpers -already express resource identity and can produce the new configuration shape -without forcing another caller migration. This concerns Go convenience inputs, -not continued support for the old YAML mapping format. Raw ConfigKit sources -remain available for authored order, explicit nulls, and other supported forms. - -**Alternative:** replace those helper inputs with slices of explicit-ID resource -values. This mirrors YAML, makes order caller-controlled, and allows duplicate -IDs to reach normal configuration validation. It also changes public signatures, -requires new ID-bearing values or fields, and makes existing keyed Go catalogs -convert unnecessarily. Choose it if downstream callers need ordered records or -uniform Go/YAML authoring enough to justify that additional API migration.