Rename selected configuration profiles to overlays

2026-09-23 18:27:29 +00:00
parent 66e080ed34
commit ae91f57bbe
32 changed files with 306 additions and 283 deletions
--- a/docs/config.md
+++ b/docs/config.md
@@ -20,7 +20,7 @@ The zero `Source` is invalid. Constructor argument failures are retained inside
 opaque source and become safe structured diagnostics when the source is consumed.
 File sources can observe file changes between consumptions; byte sources cannot.

-Each source is limited to 8 MiB. A load using imports or an active profile is limited
+Each source is limited to 8 MiB. A load using imports or an active overlay is limited
 to 64 MiB across all accepted sources, 1,024 accepted sources, 64 active import
 edges, and 1,000,000 input nodes in aggregate. Glob expansion separately permits
 1,000,000 visited directory entries, including nonmatches. Reads request at most the
@@ -33,7 +33,7 @@ truncated. Data returned together with a read error is not accepted as partial i
 root `T` must satisfy the application schema contract below. With no options it
 starts from the Go zero value. A `Definition[T].Defaults` factory, when supplied,
 runs exactly once after successful source parsing, schema construction, optional
-schema-version checking, and selected-profile loading. Its result is detached before
+schema-version checking, and selected-overlay loading. Its result is detached before
 input is applied. Resolver-provided mutable values are detached before secret lookup
 and validation, and a final detached copy prevents equal-valued aliases introduced
 by validators from escaping into the returned configuration. The publication copy
@@ -43,7 +43,7 @@ The current lifecycle is:

 ```text
 validate options → parse the selected source → traverse/compose enabled imports
-  → build schema → check the optional application version → apply a selected profile
+  → build schema → check the optional application version → apply a selected overlay
  → apply explicit CLI overrides → create and clone defaults → strictly decode
  → recorded application resolution
  → resolve typed secret references → semantic validation → classify secrets
@@ -57,9 +57,9 @@ contributes no source, and continues through defaults, decode, and projection. A
 missing file remains an error; it is never interpreted as no input.

 The current `Options` boundary accepts a defaults factory, `VersionRule`, resolver,
-semantic validator, explicit path and glob imports, one selected profile, and
+semantic validator, explicit path and glob imports, one selected overlay, and
 filesystem context. It also accepts explicit CLI override records, static secret
-tags, and a dynamic path predicate. `NoSource` rejects imports, active profiles,
+tags, and a dynamic path predicate. `NoSource` rejects imports, active overlays,
 and filesystem context as invalid combinations but accepts overrides. Input
 containing a reserved `configkit` mapping key is rejected while imports are
 disabled.
@@ -93,7 +93,7 @@ This is a load-local exception: siblings and unrelated fields, dynamic values,
 integer and float destinations, durations, `Secret`, and text codecs retain ordinary
 strict decoding. The retained source and history stay numeric while typed projection
 and effective YAML contain the resulting string; explanation records this through
-the normal decoding reconciliation event. Fragment, profile, and CLI ownership
+the normal decoding reconciliation event. Fragment, overlay, and CLI ownership
 protections apply before this conversion.

 The checker reports safe, value-free errors and warnings through `Validation.Error`
@@ -109,11 +109,11 @@ successful result. Callback panics remain programming failures.
 key/index distinctions using actual effective and historical container shapes;
 only parsed numeric tokens are resolved contextually. A descendant that never
 existed is not historical merely because an atomic ancestor was replaced. Exact surviving input paths
-are explicit and have a base or profile origin; omitted paths have a default origin.
+are explicit and have a base or overlay origin; omitted paths have a default origin.
 An explicit parent mapping does not make omitted children explicit. Null state and
 available source coordinates are retained. `History` records the Go-zero or application
-default baseline followed by exact base or profile definitions, including
-equal-valued input. Profile replacement removes displaced descendants from effective
+default baseline followed by exact base or overlay definitions, including
+equal-valued input. Overlay replacement removes displaced descendants from effective
 metadata while retaining their base definition and the parent replacement operation
 in history. All metadata queries and returned nested records are detached.

@@ -125,21 +125,21 @@ documentation in [metadata.go](../metadata.go) defines enumeration and path-orde
 details.

 History is chronological: a path can have a synthetic default record, its exact base
-definition, a profile replacement, and a recorded resolution operation. A descendant
+definition, an overlay replacement, and a recorded resolution operation. A descendant
 query uses the ancestor's path for a whole-container or whole-sequence replacement;
 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.

 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 a profile
-has a profile-layer composite origin with the lower contributing locations followed
-by the profile location; an empty mapping is still an explicit container even though
+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
+by the overlay location; an empty mapping is still an explicit container even though
 it contributes no children. Resolution origins are synthetic: they have layer
 `resolution`, no fabricated file location, and a `derived_default` or `normalization`
 operation. Reasons and dependency paths retain first occurrence order with duplicates
 removed. Source records remain ordered as selected source, depth-first imports, the
-selected profile, then synthetic CLI records in supplied order.
+selected overlay, then synthetic CLI records in supplied order.

 ### Secret classification and effective rendering

@@ -189,7 +189,7 @@ historical path. Its effective value and each chronological before/after value a
 parser values. `Present=false` with empty YAML means absence or deletion; explicit
 null is present and renders as `null`. The history starts with the canonical typed
 application-default or Go-zero baseline, then includes only relevant base sources in
-traversal order, the selected profile, supplied CLI records, and audited net
+traversal order, the selected overlay, supplied CLI records, and audited net
 resolution operations. Overlapping parent/child resolution records are rendered
 as one net subtree event with combined reasons and dependencies, rather than
 pretending that the recorded assignments ran in lexical order. Explicit equal
@@ -199,7 +199,7 @@ before domain resolution. Its origin retains the decoded path's source/default
 attribution; its reason identifies static-default retention and canonical decoding.
 This built-in inspection operation is not accepted by `Resolution.Record`.

-Base, profile, and CLI history preserves the policy-validated input representation,
+Base, overlay, and CLI history preserves the policy-validated input representation,
 including a superseded value that could not have decoded into the final Go field.
 Baseline, effective, and resolution values use canonical typed projection. A
 decoding event bridges replayed input and canonical typed values, so intermediate
@@ -338,7 +338,7 @@ found entry path. Resolution changes, additions, removals, and moves do not alte
 this entry view.

 `Resolution.Source(id)` returns a detached record for an already acquired source in
-the same load: the main source, imports, selected profile, and supplied CLI records
+the same load: the main source, imports, selected overlay, and supplied CLI records
 where applicable. Empty and unknown IDs return false. It never reloads input, reads
 the filesystem, resolves symlinks, or looks up credentials. A source path exists
 only when the acquired source has one; defaults and byte, reader, and CLI sources do
@@ -436,41 +436,41 @@ traversal order. Traversal order never authorizes replacement. Composition clone
 the resulting tree and its ordered claim records rather than mutating or aliasing an
 input document.

-## Selected profiles
+## Selected overlays

-`Options.Profile` selects at most one overlay by name. Names must match
+`Options.Overlay` selects at most one overlay by name. Names must match
 `[a-zA-Z0-9_-]+`; they are not paths. The empty name and exact lowercase name
-`default` select no profile, and `profiles/default.yml` is never loaded implicitly.
-Every other name resolves only to `<configuration-root>/profiles/<name>.yml`, with
-no extension fallback, case normalization, inheritance, or profile stack. A selected
-missing profile is an error.
+`default` select no overlay, and `overlays/default.yml` is never loaded implicitly.
+Every other name resolves only to `<configuration-root>/overlays/<name>.yml`, with
+no extension fallback, case normalization, inheritance, or overlay stack. A selected
+missing overlay is an error.

-The profile is a separately policy-validated YAML mapping. It is loaded after the
+The overlay is a separately policy-validated YAML mapping. It is loaded after the
 base import graph is composed and its schema version is checked, but before defaults
-and typed decoding. Profile bytes, nodes, and source records count toward the same
+and typed decoding. Overlay bytes, nodes, and source records count toward the same
 aggregate limits as base inputs. Its canonical path must remain within the configured
 root and must not duplicate a file already present in the base graph.

 Overlay is intentionally distinct from strict composition:

-| Existing lower node | Incoming profile node | Result |
+| Existing lower node | Incoming overlay node | Result |
 | --- | --- | --- |
-| Absent | Value | Retain the profile value |
+| Absent | Value | Retain the overlay value |
 | Value | Absent | Retain the lower value |
 | Mapping | Mapping | Recurse by mapping key |
 | Any other pair of present nodes | Any other pair of present nodes | Replace the entire lower node |

-Scalars, sequences, and null are atomic. Thus a profile sequence replaces rather
+Scalars, sequences, and null are atomic. Thus an overlay sequence replaces rather
 than extends a base sequence, `[]` clears it, null is an explicit replacement, and
 cross-kind replacement is allowed when the final application schema accepts it.
 Replacing a subtree removes all displaced descendants from effective presence and
 origin data; history retains the displaced definitions and identifies the parent
-replacement. Surviving profile paths have profile origins, while recursively shared
+replacement. Surviving overlay paths have overlay origins, while recursively shared
 mapping containers retain their contributing locations.

-A profile may not contain `configkit` anywhere, contribute the configured schema
+An overlay may not contain `configkit` anywhere, contribute the configured schema
 version, or replace an ancestor of that version with a scalar or null. These rules
-apply even if the supplied version text would be unchanged. Profiles cannot mask a
+apply even if the supplied version text would be unchanged. Overlays cannot mask a
 base parse, composition, or version failure because those checks run first.

 ## Explicit CLI overrides
@@ -483,8 +483,8 @@ must never contain the raw argument or configured value. General environment
 variable overlays are an explicit non-goal: environment access is reserved for
 typed secret references.

-Overrides apply after the selected profile and before typed defaults/decoding, so
-the input precedence is application defaults < composed base < selected profile <
+Overrides apply after the selected overlay and before typed defaults/decoding, so
+the input precedence is application defaults < composed base < selected overlay <
 CLI. Recorded resolution, typed secret lookup, and semantic validation follow the
 effective override tree. Overrides also work with `NoSource`.

@@ -506,7 +506,7 @@ configured schema-version path. Unknown fields and effective type mismatches rem
 ordinary strict-decoder errors.

 At most 1,024 records are accepted, and each record creates one synthetic CLI
-source after file/profile sources in supplied order. Override sources share the
+source after file/overlay sources in supplied order. Override sources share the
 1,024-source ceiling. A record has an 8 MiB string-byte limit; override strings and
 source bytes share the 64 MiB aggregate limit. Synthetic mapping keys and values
 count toward the existing 1,000,000-node and depth-256 ceilings. Cycles, named or
@@ -514,7 +514,7 @@ unsupported types, nonfinite floats, and limit excesses fail with safe `override
 diagnostics. Diagnostics and provenance identify the safe `Flag` source, never raw
 arguments or values.

-Override origins are explicit CLI origins. History retains replaced base/profile
+Override origins are explicit CLI origins. History retains replaced base/overlay
 definitions and records equal-value replacements as well as structural changes.
 Caller-owned maps and slices are snapshotted during loading and must not be mutated
 concurrently with the call. The executable `ExampleOverride` shows translating a
--- a/docs/consumers/README.md
+++ b/docs/consumers/README.md
@@ -1,7 +1,7 @@
 # Consumer Adoption Guide

 ConfigKit removes parser setup, strict decoding, presence bookkeeping, import and
-profile traversal, precedence, provenance, secret lookup, and safe inspection from
+selected-overlay traversal, precedence, provenance, secret lookup, and safe inspection from
 applications. Consumers still own their configuration structs, defaults, semantic
 validation, schema-version policy, CLI parsing, runtime matching and conversion,
 resource checks, remote acquisition, and service initialization.
@@ -34,7 +34,7 @@ features appear only when the application needs them:
 result, err := configkit.Load[Config](configkit.File(path), configkit.Options[Config]{
    Definition: rules,
    Imports:    useDeclaredImports,
-    Profile:    selectedConfigProfile,
+    Overlay:    selectedConfigOverlay,
    Overrides:  explicitlySetFlags,
 })
 if err != nil {
@@ -43,8 +43,8 @@ if err != nil {
 return start(result.Config)
 ```

-Simple consumers use neither imports nor profiles. A complex consumer can opt into
-both without redefining their syntax. ConfigKit profiles are configuration overlays;
+Simple consumers use neither imports nor selected overlays. A complex consumer can opt into
+both without redefining their syntax. ConfigKit overlays are configuration overlays;
 they do not select or replace an application's LLM, model, pipeline, report, or
 execution profile concepts.

@@ -100,6 +100,16 @@ The examples preserve domain meaning while adopting one configuration convention
  blocked empty variables remain blocked, and ordinary `Load` never changes the
  process environment.

+### Selected-overlay migration
+
+To adopt the current selected-overlay API, rename `Options.Profile`,
+`LayerProfile`, and `CodeProfile*` references to their `Overlay` equivalents; move
+selected files from `profiles/<name>.yml` to `overlays/<name>.yml`; update any
+handling of the `overlay` layer and `overlay.*` diagnostic strings; then rebuild.
+The [configuration contract](../config.md#selected-overlays) is the canonical
+behavioral reference. Application-owned profile concepts, such as `model_profile`,
+are unchanged, and any CLI flag rename remains the application's decision.
+
 These examples are migration evidence, not completed changes to Narratio, Notarius,
 WeatherReporter, or Seriatim. Updating those repositories, their deployed YAML, CLI
 wiring, runtime catalogs, and operational documentation remains separate downstream
@@ -113,7 +123,7 @@ focused behavioral owner:
 | Roadmap surface | Maintained owner |
 | --- | --- |
 | `Load`, `NoSource`, validation, versions, resolution, `SecretEnv`, overrides, and explanation | Executable examples in [`example_test.go`](../../example_test.go) |
-| Source/import/profile pipeline rules and artifact defaults | Narratio-shaped executable example and fixture |
+| Source/import/selected-overlay pipeline rules and artifact defaults | Narratio-shaped executable example and fixture |
 | Canonical module objects and dynamic option handling | WeatherReporter- and Notarius-shaped examples and migration tests |
 | `LoadSecretsDir`, bootstrap reporting, typed lookup, CLI explanation | `Example_weatherStartup` |
 | Results, metadata, diagnostics, effective output, and writer failures | Focused root-package load, provenance, rendering, and explanation tests |
--- a/docs/development.md
+++ b/docs/development.md
@@ -105,7 +105,7 @@ code changes. Use the component overview to find the corresponding implementatio
 | --- | --- | --- |
 | YAML syntax, diagnostics, parser limits | [Adapter tests](../internal/yaml/parse_test.go), [source translation](../internal/engine/parse_test.go) | `go test ./internal/yaml` and `go test ./internal/engine -run '^TestParseSource'` |
 | File/reader access, imports, globs, containment | [Sources](../internal/engine/source_test.go), [FIFO](../internal/engine/source_fifo_test.go), [imports](../internal/engine/imports_test.go), [globs](../internal/engine/glob_test.go) | `go test ./internal/engine -run 'Source\|Import\|Glob\|Filesystem\|Nonregular\|RegularFile'` |
-| Composition, profiles, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [profiles](../internal/engine/profile_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Profile\|Override'` |
+| Composition, selected overlays, CLI precedence | [Composition](../internal/engine/compose_test.go), [overlay](../internal/engine/overlay_test.go), [selected overlays](../internal/engine/selected_overlay_test.go), [overrides](../internal/engine/override_test.go) | `go test ./internal/engine -run 'Compose\|Overlay\|Override'` |
 | Schema, defaults, projection, cloning | [Schema](../internal/engine/schema_test.go), [decoding](../internal/engine/decode_test.go), [projection](../internal/engine/projection_test.go) | `go test ./internal/engine -run 'Schema\|Decode\|Projection\|Clone\|Inline\|CompareDocument'` |
 | Lifecycle, resolution, validation, callback ownership | [Loading](../internal/engine/load_test.go), [resolution](../internal/engine/resolution_test.go), [validation](../internal/engine/validation_test.go), [ownership](../internal/engine/callback_ownership_test.go), [independence](../internal/engine/independence_test.go) | `go test ./internal/engine -run 'Load\|Resolution\|Validation\|Validator\|Hook\|Callback\|Parallel'` |
 | Paths, metadata, provenance | [Paths](../internal/engine/path_test.go), [metadata](../internal/engine/metadata_test.go), [provenance](../internal/engine/provenance_test.go) | `go test ./internal/engine -run 'Path\|Metadata\|Provenance\|Queries'` |
--- a/docs/internal/extraction.md
+++ b/docs/internal/extraction.md
@@ -137,9 +137,11 @@ permission failures, explicit `conf.d` use, and entry/candidate budgets. This wo
 has no Narratio production equivalent; it uses the selected standard-library
 `path.Match` and bounded `File.ReadDir` adaptation rather than its flat loader.

-### Profiles and overlay
+### Upstream profiles and ConfigKit selected overlays

-Assigned to selected-profile overlay:
+The following upstream symbols and case names retain their original profile
+terminology. ConfigKit adapts their selected-overlay behavior without renaming the
+upstream evidence:

 - Production: `mergeOverlayComposition`, `mergeOverlayNodes`,
  `selectPipelineProfile`, `loadPipelineProfileOverlays`, and
@@ -153,19 +155,21 @@ Assigned to selected-profile overlay:
  `TestLoadPipelineProfilePairResolvesIndependentEffectivePipelines`.
 - Preserve: recursive mapping overlay, atomic scalar/sequence replacement,
  deterministic selection failures, source ownership, and independent results.
- Adapt: load only the selected fixed profile path; lowercase `default` means no
-  overlay. ConfigKit permits null and cross-kind replacement and does not support
-  declared defaults, inheritance, arbitrary profile paths, or validating every
+- Adapt: load only the selected fixed overlay path; lowercase `default` means no
+  selection. ConfigKit permits null and cross-kind replacement and does not support
+  declared defaults, inheritance, arbitrary overlay paths, or validating every
  unselected overlay.

-Implementation record (2026-09-06): `overlayDocuments`, `mergeOverlayMappings`,
-`loadProfileDocument`, and `profileDirectiveDiagnostics` adapt the assigned merge,
-selection, loading, and ownership mechanics. `TestOverlayDocumentsRecursesMappingsAndReplacesAtomicSubtrees`,
-`TestLoadAppliesSelectedProfileAfterBaseAndBeforeDefaults`, profile selection/error,
-directive/version, containment, and budget cases adapt the assigned tests. ConfigKit
+Implementation record (2026-09-06, updated 2026-09-23): `overlayDocuments`,
+`mergeOverlayMappings`, `loadSelectedOverlayDocument`, and
+`overlayDirectiveDiagnostics` adapt the assigned merge, selection, loading, and
+ownership mechanics. `TestOverlayDocumentsRecursesMappingsAndReplacesAtomicSubtrees`,
+`TestLoadAppliesSelectedOverlayAfterBaseAndBeforeDefaults`, selected-overlay
+selection/error, directive/version, containment, and budget cases adapt the assigned
+tests. ConfigKit
 uses exactly one fixed selected `.yml` source, permits null and cross-kind replacement,
-retains displaced descendant history, rejects any profile directive or version-path
-contribution, and counts the profile in aggregate budgets. Narratio's declared
+retains displaced descendant history, rejects any overlay directive or version-path
+contribution, and counts the overlay in aggregate budgets. Narratio's declared
 default, multi-overlay validation, inheritance-like application conventions, and
 null/kind restrictions were not retained.

@@ -196,7 +200,7 @@ previously extracted source claims, overlay displacement records, typed baseline
 and audited resolution snapshots in `load_metadata.go`. The representative
 `TestLayeredProvenanceAgreesWithResolvedSnapshot` adapts Narratio's stable ownership,
 profile ownership, deterministic effective projection, and side-effect-free
-inspection cases across one default/import/profile/resolution workflow. ConfigKit
+inspection cases across one default/import/overlay/resolution workflow. ConfigKit
 adds chronological descendant history for parent and whole-sequence operations,
 composite empty-mapping origins, canonical resolution reasons/dependencies, private
 snapshot agreement, defensive nested copies, and concurrent load isolation. Value
--- a/docs/policy/architecture.md
+++ b/docs/policy/architecture.md
@@ -71,7 +71,7 @@ network provider into the library.
 ## Public API and dependency direction

 Keep one small, coherent public surface for the supported lifecycle. Simple
-single-document consumers must not need import, profile, or provider machinery.
+single-document consumers must not need import, overlay, or provider machinery.
 Do not expose parser-specific nodes, errors, or extension hooks through the
 public API. Parser integration belongs behind a private boundary, as recorded
 in [ADR 0002](../adr/0002-own-yaml-semantics.md).
@@ -106,7 +106,7 @@ same inputs and options. Invalid input must not produce a successful usable
 configuration. Do not run application hooks on invalid typed configuration.

 User-controlled precedence is application defaults, composed base, selected
-profile, then explicitly supplied CLI overrides. Applications own flag parsing;
+overlay, then explicitly supplied CLI overrides. Applications own flag parsing;
 ConfigKit owns overlay semantics and provenance. Domain resolution follows these
 inputs and must remain recorded, not become a hidden override channel.

--- a/docs/roadmap/deferred.md
+++ b/docs/roadmap/deferred.md
@@ -15,7 +15,7 @@ The initial release deliberately excludes:

 - automatic `conf.d` discovery;
 - remote imports, arbitrary providers, and additional configuration formats;
- custom merge strategies, sequence merging, reset operators, and profile inheritance;
+- custom merge strategies, sequence merging, reset operators, and overlay inheritance;
 - parser-specific or custom structural-decoding extension APIs;
 - generic dynamic-subtree conversion and module-registry APIs;
 - automatic schema migrations;
--- a/docs/roadmap/implementation.md
+++ b/docs/roadmap/implementation.md
@@ -1,6 +1,6 @@
 # Configuration Overlay Rename Implementation Plan

-Status: not started. Execute Stage 1, then Stage 2.
+Status: Stage 1 complete. Execute Stage 2.

 ## Scope and operating instructions

@@ -112,6 +112,15 @@ unchanged.
 Stage 1 is complete only with a compiling, passing repository and matching
 current documentation. It is not permission to ship before Stage 2's audit.

+### Completion
+
+Completed 2026-09-23. Renamed the selected configuration feature across the
+facade, engine, maintained consumer, fixtures, contract, and current guidance;
+application-owned `ModelProfile` and `model_profile` remain unchanged. `gofmt` and
+`./scripts/check.sh` passed on Go 1.26.8/linux. Review confirmed the new
+`overlays/<name>.yml` path, `overlay`/`overlay.*` public values, and no retained
+legacy Go declarations or filesystem fallback.
+
 ## Stage 2 — Verify the breaking migration and finalize the handoff

 ### Outcome
--- a/docs/roadmap/overlays.md
+++ b/docs/roadmap/overlays.md
@@ -17,7 +17,7 @@ not authorize publication or changes to downstream repositories.

 The baseline is ConfigKit at `aead20f`, following v0.3.1 and the release-workflow
 simplification. Current behavior is owned by the
-[selected-profile contract](../config.md#selected-profiles). This roadmap owns
+[selected-overlay contract](../config.md#selected-overlays). This roadmap owns
 the unimplemented rename; it is not a new current API reference.

 ## Target terminology and public surface