Settle source builders on explicit-ID slices

docs/roadmap/configkit.md

@@ -1,8 +1,7 @@
 # ConfigKit v1 Adoption And Identified Resource Collections
 
-Status: accepted direction; implementation pending. The source-builder API
+Status: accepted direction; implementation pending. This roadmap describes
-choice at the end remains open. This roadmap describes future behavior, not
+future behavior, not the currently supported configuration format.
-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
+Update `BackendSource`, `ProfileSource`, and their public configuration values to
-the list format, following the open API decision below. Update namespace views,
+use explicit-ID slices and encode profile inheritance as an identity reference.
-listing, inspection, prepared execution, and smoke-test selection as needed to
+Update namespace views, listing, inspection, prepared execution, and smoke-test
-consume the same captured runtime indexes. Do not change their selection or
+selection as needed to consume the same captured runtime indexes. Do not change
-execution semantics merely to mirror the new configuration representation.
+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.