Document sequence composition for consumers

docs/adr/0014-sequence-placement-and-composition.md

@@ -2,8 +2,10 @@
 
 ## Status
 
-Accepted. Implementation status and sequencing are tracked in the
-[sequence composition implementation plan](../roadmap/implementation.md).
+Accepted and implemented. The [configuration contract](../config.md#strict-document-composition)
+defines current behavior, and the [consumer guide](../consumers/README.md#identified-prompt-sequences)
+shows the maintained example. Implementation status and delivery sequencing
+are tracked in the [implementation plan](../roadmap/implementation.md).
 
 ## Date
 

docs/config.md

@@ -154,6 +154,11 @@ have index zero. Explicit empty groups and `NoSource` consume no source ID.
 Byte, source, node, and glob-entry budgets are shared across the load, while
 the existing per-source and import-depth bounds still apply.
 
+When a source mapping is explicitly placed as an item, its effective destination
+is the sequence container. After assembly assigns an index, nested source
+destinations are projected through that item. Physical source locations and
+resource contexts continue to identify the declaring source.
+
 #### Input destinations
 
 `Input.Destination` places the source's application mapping beneath a path
@@ -411,6 +416,11 @@ the descendant can therefore retain history after `Lookup` stops reporting it as
 effective. Equal-valued input is still an explicit base definition, while a derived
 value for absent input remains non-explicit.
 
+Appending registered records during strict composition assigns each contribution
+its assembled sequence index in history. A later precedence tier that supplies a
+sequence records replacement at the sequence path; history does not imply
+identity-based merging across tiers.
+
 A mapping assembled from the selected file and imports has one composite base origin
 whose locations retain source traversal order. A mapping also visited by an overlay
 has an overlay-layer composite origin with the lower contributing locations followed
@@ -790,6 +800,14 @@ a present higher-priority sequence replaces the lower sequence as one value,
 including at a registered path. Overlays, CLI overrides, defaults, inheritance,
 and application resolution do not run the registered identity check. The accepted
 rationale is recorded in [ADR 0014](adr/0014-sequence-placement-and-composition.md).
+The [maintained prompt catalog](consumers/README.md#identified-prompt-sequences)
+shows item path and glob imports, helper-supplied identity, and main-tier
+replacement of a lower-priority sequence.
+When an enabled source-version mode is selected, declarations are checked in each
+source's own coordinates before placement and composition. Accepted non-main
+headers are consumed before strict composition and cannot supply a registered
+record identity. Final typed decoding and application validation still run on the
+completed configuration.
 
 An empty mapping contributes no child definitions. Two empty mappings compose, and
 an empty mapping neither clears nor conflicts with another mapping's children.
@@ -932,7 +950,11 @@ placement requires a nonempty effective destination and wraps the imported
 mapping as one element of a sequence there. It does not split source sequences
 or infer identity fields. Repeated sequences still conflict unless their path is
 registered through `Definition.SequenceCompositions`; registration does not
-change placement or precedence behavior.
+change placement or precedence behavior. Sequence records retain source
+locations through placement and history; indexes describe their assembled
+positions while source coordinates continue to identify the declaring files.
+Header/version policy and final application validation retain their existing
+owners and timing; sequence registration is a strict-composition rule only.
 
 An item import first opens a local mapping scope. Its body and ordinary helper
 imports compose within that record. An omitted helper destination or

docs/consumers/README.md

@@ -21,6 +21,7 @@ sanitized shapes using only ConfigKit and the Go standard library:
 | Named presets | One-load sibling inheritance, explicit false, nested destination resolution, and source/derivation inspection | Choosing and executing a preset |
 | Effective configuration diff | Same-type frozen effective comparisons for two selected files or base-versus-overlay impact | Source/options selection and consumer-owned safe presentation |
 | Shared source-version checks | One `Definition.Version` policy for accepted declarations across participating source documents, with optional or required declarations and sanitized evidence | Choosing which declarations the application accepts; final assembled schema and domain validation |
+| Identified prompt sequences | Explicit item path/glob imports, helper-supplied IDs, reusable single-field registration, and main-tier replacement of a lower-priority collection | Prompt meaning and final domain validation |
 
 The YAML under [`testdata`](../../examples/consumers/testdata) is loaded by the
 executable examples and ordinary tests. It contains no private application data,
@@ -163,6 +164,24 @@ relative resources, and strict peer conflicts. The
 [configuration contract](../config.md#input-destinations) owns shared placement,
 import, source-location, and ownership behavior.
 
+## Identified prompt sequences
+
+[`LoadPromptCatalog`](../../examples/consumers/prompt_catalog.go) uses one
+definition registration for the literal `prompts` path and `id` field. Its main
+file imports one prompt by path and others by glob, placing each source as an
+item. A nested ordinary helper import supplies an item's ID. The main tier
+strictly appends the distinct records in contribution order; its completed
+sequence replaces the lower-priority default collection as one value.
+
+The example's `validatePromptCatalog` remains application-owned. It checks that
+prompt names and message lists satisfy this consumer's requirements after
+ConfigKit has composed, projected, and decoded the configuration. It does not
+add recursive record merging, identity-based overlay, or final uniqueness checks
+after defaults and resolution. See the [strict composition contract](../config.md#strict-document-composition),
+[import syntax](../config.md#explicit-imports), and
+[ADR 0014](../adr/0014-sequence-placement-and-composition.md) for the exact
+boundaries.
+
 Known module catalogs should use canonical object entries with a module identifier
 and typed options. A small union struct is sufficient when the available option
 fields are known; validation selects which fields apply to each module. Runtime-

docs/development.md

@@ -131,6 +131,12 @@ Current behavior belongs to the configuration contract's
 [input destinations](config.md#input-destinations),
 [imports](config.md#explicit-imports), and
 [shared source-version checks](config.md#shared-source-version-checks) sections.
+Explicit sequence-item placement and registered strict composition are owned by
+the [strict composition](config.md#strict-document-composition) and
+[imports](config.md#explicit-imports) sections. The
+[maintained prompt catalog](consumers/README.md#identified-prompt-sequences)
+shows the current consumer boundary, and [ADR 0014](adr/0014-sequence-placement-and-composition.md)
+records the decision.
 Potential enhancements are tracked in [future features](roadmap/future.md).
 
 Install the Go version required by `go.mod` or a compatible newer toolchain.

docs/internal/overview.md

@@ -9,9 +9,12 @@ Implemented component owners:
 
 - `internal/engine` owns host and native-filesystem source acquisition,
   grouped strict composition, recursive precedence assembly, per-input mapping
-  placement and immediate-parent-relative import placement within that
-  assembly, destination-local sibling inheritance before typed decoding, and
-  shared source-version checking with sanitized declaration evidence.
+  and sequence-item placement, definition-registered distinct-ID sequence
+  composition within strict tiers, and immediate-parent-relative import
+  placement within that assembly. Higher-priority sequences replace lower
+  sequences as whole values. The engine also owns destination-local sibling
+  inheritance before typed decoding, plus shared source-version checking with
+  sanitized declaration evidence.
   It retains each source's effective placement alongside physical source
   identity and owns schema
   inspection, lifecycle coordination, callback auditing,
@@ -48,6 +51,10 @@ The [configuration contract](../config.md) owns implemented YAML and lifecycle
 semantics, including [input destinations](../config.md#input-destinations),
 [shared source-version checks](../config.md#shared-source-version-checks), and
 [effective configuration diffs](../config.md#effective-configuration-diffs).
+The [strict composition contract](../config.md#strict-document-composition)
+owns sequence placement, registration, replacement, and history behavior; the
+[consumer guide](../consumers/README.md#identified-prompt-sequences) shows the
+maintained example.
 The [consumer adoption guide](../consumers/README.md) owns application guidance.
 The [architecture policy](../policy/architecture.md) owns contributor
 boundaries; [ADR 0006](../adr/0006-public-facade.md) records the facade decision
@@ -59,3 +66,5 @@ and [release procedure](../release.md) for source-candidate gates. [ADR
 post-assembly structural operation. [ADR 0012](../adr/0012-relative-import-destinations.md)
 records the relative-import extension; [ADR 0013](../adr/0013-shared-source-version-checks.md)
 records the source-version decision.
+[ADR 0014](../adr/0014-sequence-placement-and-composition.md) records explicit
+sequence placement and composition.

docs/policy/architecture.md

@@ -163,19 +163,22 @@ framework on this library.
 
 Within a configuration tier, independent contributions use strict composition:
 shared mappings combine recursively, while overlapping non-mapping definitions
-are conflicts, including equal values. Between precedence tiers, intentional
-overlay combines mappings recursively, retains omitted lower-priority children,
+are conflicts, including equal values, except that sequences at explicitly
+registered paths append records with distinct present string identities. Between
+precedence tiers, intentional overlay combines mappings recursively, retains
+omitted lower-priority children,
 and replaces other present values according to the existing overlay rules.
 Tier precedence is explicit; traversal order within a tier establishes stable
 reporting, not permission to override. The distinction and its rationale are
 recorded in [ADR 0001](../adr/0001-separate-composition-and-overlay.md).
 
-At definition-registered sequence paths, strict composition appends mapping
-records with distinct present string identities and rejects duplicates.
-Placement and registration are explicit source and definition controls; they do
-not change precedence replacement. The [configuration contract](../config.md#strict-document-composition)
-defines the behavior, and [ADR 0014](../adr/0014-sequence-placement-and-composition.md)
-records the decision.
+Sequence-item placement and sequence registration are explicit source and
+definition controls; registration does not change precedence replacement. The
+[configuration contract](../config.md#strict-document-composition) defines the
+behavior, [ADR 0014](../adr/0014-sequence-placement-and-composition.md) records
+the decision, and the [consumer guide](../consumers/README.md#identified-prompt-sequences)
+shows the implemented subset. This feature does not authorize arbitrary
+configurable merge strategies.
 
 The main document and its imports form a strictly composed tier. Explicit
 underlay groups compose strictly within each group, then combine recursively

docs/roadmap/future.md

@@ -15,11 +15,12 @@ PromptKit repository at
 PromptKit selected mounted mappings instead; this feature is not a dependency
 of that design or a request to restore multiple installed prompt versions.
 
-A narrower [sequence placement and composition roadmap](sequence-composition.md)
-now covers placing source mappings as sequence items, single-field identities,
-duplicate rejection during strict composition, and whole-sequence replacement
-between precedence layers. The additional capabilities below remain deferred
-and are not requirements of that roadmap.
+A narrower [sequence placement and composition feature](../config.md#strict-document-composition)
+is implemented: consumers can place imported mappings as sequence items and
+register a single literal string identity field for duplicate-rejecting strict
+composition. Precedence still replaces sequences as whole values. This entry
+tracks broader identified-record behavior that remains deferred and is not part
+of that implemented contract.
 
 ### Motivation and proposed behavior
 
@@ -27,13 +28,16 @@ Allow applications to declare that selected sequences contain records identified
 by explicit fields, while retaining sequence-shaped output for slice decoding
 and effective YAML. This could make composite identities and independently
 authored catalogs more convenient than encoding identity in nested mapping keys.
-Current [composition](../config.md#strict-document-composition) and
-[overlay](../config.md#selected-overlays) treat sequences atomically.
+Current [composition](../config.md#strict-document-composition) appends distinct
+records only at explicitly registered paths; other sequences remain atomic.
+Selected [overlays](../config.md#selected-overlays) always treat sequences
+atomically.
 
-The proposed opt-in registration belongs in the reusable application definition:
-an exact effective sequence path after input/import placement, plus an ordered,
-nonempty set of distinct direct string-field names. For example, records at
-`profiles` could be identified by `(namespace, id)`. Records `(provider, brief)`
+The proposed broader opt-in registration would extend the current reusable
+application definition from one identity field to a composite identity made of
+an ordered, nonempty set of distinct direct string-field names. For example,
+records at `profiles` could be identified by `(namespace, id)`. Records
+`(provider, brief)`
 and `(application, brief)` would coexist, and a later layer could update the
 provider record's temperature while retaining its backend and model.
 

docs/roadmap/implementation.md

@@ -1,6 +1,6 @@
 # Implementation Plan: Sequence Placement and Composition
 
-Status: implementation in progress; stages 1–12 completed.
+Status: implementation in progress; stages 1–13 completed.
 
 ## Purpose and authority
 
@@ -756,6 +756,24 @@ Validation: executable example/consumer tests, local documentation-link tests,
 whitespace review, and `./scripts/check.sh`.
 Completion: current docs and tested public examples describe what actually lands.
 
+Completion evidence: the canonical configuration contract and architecture
+policy now describe placement, registered strict composition, version/header
+boundaries, source containers, history, and unchanged precedence. README,
+consumer, development, and internal guides link to those contracts and the
+maintained prompt-catalog example. The example uses disposable in-repository
+fixtures to demonstrate path/glob item imports, a helper-supplied identity,
+strict composition, whole-sequence replacement of defaults, and consumer-owned
+validation. The feature roadmap and ADR status point to the implemented contract
+and delivery record; broader composite-identity behavior remains deferred.
+These checks passed with Go `go1.26.9 linux/amd64`:
+
+- `GOTOOLCHAIN=local GOPROXY=off go test ./examples/consumers`
+- `GOTOOLCHAIN=local GOPROXY=off go test -race ./...`
+- `GOTOOLCHAIN=local GOPROXY=off ./scripts/check.sh`
+- `git diff --check`
+
+No environmental limitation affected validation; checks ran on Linux/amd64.
+
 ## Stage 14 — Review the completed unit and hand off
 
 - Read the complete implementation diff against `2051177` and the feature

docs/roadmap/sequence-composition.md

@@ -1,8 +1,9 @@
 # Sequence-Item Placement and Identity-Based Composition
 
-Status: design decisions settled; not implemented. This roadmap owns the target
-state and accepted behavior. The [implementation plan](implementation.md) owns
-concrete API/syntax choices, execution order, validation, and progress.
+Status: implemented. This roadmap records the target state and accepted behavior.
+The [configuration contract](../config.md#strict-document-composition) defines
+the current behavior, and the [implementation plan](implementation.md) records
+delivery sequencing and validation.
 
 ## Goal and current baseline
 
@@ -11,13 +12,12 @@ files. Placement makes a source mapping one sequence item; identity-based strict
 composition combines distinct items and rejects repeated identities. These are
 complementary operations, with explicit consumer opt-in.
 
-Current [input destinations](../config.md#input-destinations) place source
-mappings beneath mapping-key paths. Imports support immediate-parent-relative
-destinations. Current [strict composition](../config.md#strict-document-composition)
-combines mappings recursively and rejects other overlaps, while
-[precedence assembly](../config.md#layered-loading) and
-[selected overlays](../config.md#selected-overlays) replace sequences wholesale.
-Neither sequence-item placement nor sequence-composition registration exists today.
+Sources can explicitly place mappings as sequence items at non-root destinations,
+and definitions can register literal sequence paths with one literal string
+identity field for duplicate-rejecting strict composition. Ordinary unregistered
+sequences retain strict conflict behavior. [Precedence assembly](../config.md#layered-loading)
+and [selected overlays](../config.md#selected-overlays) continue to replace
+sequences wholesale. The canonical contract documents the exact rules and limits.
 
 This roadmap covers a narrower feature than the
 [identified record sequences candidate](future.md#1-identified-record-sequences).