Plan ConfigKit inheritance adoption

This commit is contained in:
2026-10-03 17:16:02 +00:00
parent 9849c6bda2
commit 8b6c12f912

View File

@@ -1,232 +1,232 @@
# ConfigKit Adoption # ConfigKit v0.5.0 Adoption
## Status And Intent ## Status And Intent
Implemented feature direction, drafted on 2026-09-26 and delivered through the Accepted feature direction, recorded on 2026-10-03; implementation is pending.
historical plan at This roadmap replaces the completed initial ConfigKit adoption roadmap. That
`git show 8452b54809b99425a97940da485daaa48c77aeb8:docs/roadmap/implementation.md`. earlier work and its resolved decisions remain available in Git at
This roadmap records the target behavior and changes from the reviewed baseline; `9849c6b:docs/roadmap/configkit.md`.
that Git record owns sequencing, concrete interfaces, and verification evidence.
The user is adopting ConfigKit across an application suite to standardize The maintainer is adopting ConfigKit across an application suite to standardize
configuration semantics. Scriptorium will make a clean cutover to ConfigKit's configuration semantics. This update continues that native integration by
native conventions, including intentional breaking changes. Preserving the adopting ConfigKit v0.5.0 and exposing its automatic sibling inheritance.
legacy loader's behavior is not a goal: there will be no parallel legacy loader, An intentional configuration compatibility change is accepted. The target
compatibility mode, or recreation of the old merging rules. retains Scriptorium's existing discovery and application path policies rather
than expanding the configuration interface merely because upstream added
library APIs.
Alignment applies to application configuration, not to Promptkit-owned prompt, This document owns the desired end state and required changes. A later
profile, or schema definitions. Departures from ConfigKit conventions require an implementation plan will own ordered implementation instructions. The
application-specific reason or a genuine ownership boundary, not backward [architecture policy](../policy/architecture.md),
compatibility alone. The [architecture policy](../policy/architecture.md) and [configuration contract](../config.md), and
[ADR 0004](../adr/0004-definition-boundary.md) remain the scope boundaries. [ADR 0004](../adr/0004-definition-boundary.md) establish the existing application
and framework ownership boundaries.
## Reviewed Baseline (Historical) ## Reviewed Baseline And Upstream Target
Scriptorium consumes Promptkit v0.11.0. Its `internal/config` package uses The baseline is Scriptorium v0.15.0 at
yaml.v3 directly and manually applies defaults, file settings, and CLI overrides. `9849c6b`, selecting ConfigKit v0.4.2 and Promptkit v0.11.2.
It has a parser-specific integer decoder, ignores empty string overrides, and Application configuration already uses a shared ConfigKit-native
treats an empty configuration file as defaults-only input. It has no application `Document`, defaults factory, recorded resolver, validator, and `Load`
configuration imports, selected overlays, or provenance/inspection interface. boundary. Runtime conversion uses the resolved document without a second merge.
The [configuration reference](../config.md), [CLI reference](../cli.md), and Execution and the `config validate`, `show`, `sources`, and `explain`
[source internals](../internal/sources.md) own the current behavior. commands share that pipeline.
The reviewed ConfigKit release is v0.4.0 at commit Current source selection is an explicit `--config` file, the first existing
`e6ced0d3d1194b58e0b3dc8970089471ba175258`. Adopt that published release as the documented system configuration file, or defaults-only loading. File-backed
initial target, rather than a sibling checkout or unpublished replacement. loads enable explicit imports and one named overlay; explicit application CLI
Its canonical references are: flags supply override records. Application path values remain relative to the
process working directory. Backend definitions are independent mappings, with
no application-owned inheritance implementation.
- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/config.md). The upstream target is the published ConfigKit v0.5.0 release at full commit
- [Consumer adoption guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/consumers/README.md). `dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Canonical references are:
- [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/e6ced0d3d1194b58e0b3dc8970089471ba175258/docs/releases/v0.4.0.md).
ConfigKit requires Go 1.25, within Scriptorium's existing toolchain requirement. - [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/releases/v0.5.0.md).
It selects `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Removing Scriptorium's direct parser - [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md).
usage does not remove yaml.v3 from the dependency graph: Promptkit still uses it. - [Sibling inheritance](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance).
The initial review passed ConfigKit's default test suite and Scriptorium's - [Consumer examples](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md).
configuration and CLI tests; that is baseline evidence, not migration validation.
## Target Ownership And Loading Model The release retains the Go 1.25 minimum, the existing
`go.yaml.in/yaml/v4 v4.0.0-rc.6` dependency, and the library's
LGPL-3.0-or-later grant. No Promptkit upgrade is needed for this work.
| Owner | Responsibility | An isolated review using a temporary module file passed Scriptorium's existing
| --- | --- | test suite and build against v0.5.0. CLI checks confirmed effective backend
| ConfigKit | Application YAML policy, source acquisition, composition, overlays, typed decoding, explicit override application, provenance, and redacted inspection. | inheritance, explicit zero and false replacements, and inheritance explanation.
| Scriptorium | Source discovery, application schema and defaults, CLI parsing, recorded application normalization, semantic validation, command prerequisites, and runtime conversion. | They also confirmed that a literal `extra_params.extends` accepted by v0.4.2
| Promptkit | Framework definition formats, backend semantics, credential lookup, engine defaults, and prompt execution. | fails under v0.5.0. This evidence supports adoption; it does not establish
completion of the planned regression coverage, race testing, or vet checks.
`internal/config` becomes a small application-specific ConfigKit integration, ## Targeted End State
not a second general-purpose configuration framework. Execution and inspection
share one configuration definition and loading pipeline. Defaults, selected base
and imports, selected overlay, and explicit application CLI overrides participate
in ConfigKit's lifecycle; resolution and validation follow its upstream rules.
Normalization that changes inspected values is recorded through its resolver.
Runtime conversion does not perform a hidden second merge or apply new defaults
after the inspection snapshot has been created.
Scriptorium retains its application field names and domain meanings unless a Scriptorium selects ConfigKit v0.5.0 through its public root package and keeps
specific change below requires otherwise. ConfigKit's public root API replaces the existing single configuration loading lifecycle. Native sibling inheritance
direct YAML decoding and parser-specific hooks. Application defaults remain is available in application configuration wherever upstream permits it, without
Scriptorium-owned; omitted framework settings still delegate to Promptkit. an application-specific opt-in, collection registry, merging implementation,
Backend conversion retains deterministic registration and engine-scoped shared or compatibility preprocessing.
capacity state. This work does not change the HTTP request contract or move
configuration loading into each HTTP request.
## Native Configuration Semantics The primary user benefit is sharing settings among named backend definitions.
A child backend may inherit its parent's endpoint, API-key environment
reference, provider parameters, concurrency limit, and queue capacity, then
replace selected values. The resolved backend retains its own ID and reaches
Promptkit through the existing deterministic runtime conversion and registration.
The target accepts ConfigKit's upstream YAML grammar, schema binding, limits, ConfigKit owns structural inheritance, value presence, provenance, history,
composition, and value-presence rules without a legacy preprocessing layer. and explanation. Scriptorium owns its schema, discovery, normalization,
Migration-visible changes include: application validation, and runtime mapping. Promptkit continues to own backend
semantics, credential lookup, framework definitions, and execution.
- An existing empty file is invalid; `{}` expresses an empty application mapping. ### Inheritance Semantics And Application Consequences
Defaults-only operation with no discovered file uses `NoSource` instead.
- Explicit empty strings, false values, and zeroes replace defaults. They are
not silently treated as omission. Application validation still decides whether
a resulting value is meaningful for its field or selected command.
- Null follows the application's declared nullable types. It is not a universal
spelling for omission. Scalars and structs do not accept null merely because
the former parser tolerated it.
- Anchors, aliases, merge keys, explicit tags, additional documents, unsupported
scalar spellings, and coercions rejected by ConfigKit are rejected here too.
- ConfigKit's reserved `configkit` key and resource limits apply, including in
dynamic application data. These constraints do not apply to independently
loaded Promptkit definitions or HTTP request bodies.
- Dynamic integers in backend `extra_params` use ConfigKit's `int64`
representation. Runtime mapping preserves their supported value semantics
rather than reserializing through YAML or demanding the old Go scalar type.
Presence remains meaningful at the framework boundary: omitted/null The target uses upstream semantics directly; the linked upstream contract
`transient_retries` delegates to Promptkit, while explicit zero disables retries; remains the canonical detailed specification:
omitted backend queue capacity differs from explicit zero. Application HTTP
size defaults and zero-as-unlimited behavior remain. No new value ranges or
backend restrictions are introduced merely to adopt the library.
## Discovery, Imports, Overlays, And Paths - An input mapping can use `extends: NAME` to inherit from one named immediate
sibling mapping. Relationships resolve after imports, overlays, and explicit
CLI overrides have assembled the input, and before typed decoding.
- Child mappings recursively combine with their resolved parents. Explicit
zero, false, empty-string, sequence, and null values replace inherited values
according to ConfigKit's rules. Normal schema constraints still apply; null
is not newly accepted for every application field.
- `extends: null` cancels a relationship. Invalid references and cycles fail
through upstream structured diagnostics. Quoting the key does not make it
ordinary data.
- Inherited values count as explicit input. ConfigKit retains inheritance
derivation and displaced history for inspection; Scriptorium's normalization
continues to be recorded after decoding.
- All effective relationships resolve, including definitions a particular
invocation does not select. Inheritance is not lazy backend selection.
- Parent backend entries remain configured backends. They are not abstract
templates and receive the same existing Promptkit registration and validation
treatment as other backends. This adoption adds no template-only collection,
registration suppression, or validation exemption.
Source discovery remains Scriptorium-owned. The target retains the documented The backend example should demonstrate reusable complete parent settings and
explicit `--config` selection and ordered system-location search. An explicitly a child with meaningful explicit replacements, including zero queue capacity
empty config path is invalid rather than an implicit request for a default file. and a false dynamic parameter. Parameter names and values must be illustrative
If neither implicit candidate exists, loading uses defaults only; a selected and contain no credentials.
file that fails loading is not silently replaced with defaults. No implicit
working-directory configuration search, environment overlay, or directory scan
is added.
Application configuration supports ConfigKit's explicit path and glob imports. ### Inspection And Credential Handling
Imports compose disjoint definitions; repeated non-mapping definitions are
conflicts, not last-writer-wins overrides. There is no implicit `conf.d` scan.
An optional `--config-overlay` selects ConfigKit's one named overlay using its `config show` presents the final resolved settings; `config explain` exposes
standard `overlays/<name>.yml` location, naming rules, and merge behavior. No upstream inheritance origins and history, including consumed directive history
overlay is selected by default. Selecting an active overlay without a base where supported. Both continue to use ConfigKit's native writers and the same
source follows ConfigKit's rejection of overlays with `NoSource`; Scriptorium result used by execution. Inheritance creates no additional acquired source:
does not invent a root. Application overlays do not replace `--profile`, `config sources` retains its existing application DTO and source-list contract.
`profile_dir`, or Promptkit's execution-profile selection. No new JSON fields or source layer are needed solely for inheritance.
Use the selected file's canonical directory as ConfigKit's default import and The maintainer's existing inspection policy remains: ordinary `extra_params`,
overlay root. This root governs configuration source traversal only. Values of including historical values, and `api_key_env` names remain visible.
`prompt_dir`, `profile_dir`, `schema_dir`, and `server.artifact_root` retain Scriptorium does not resolve API-key values through ConfigKit, add secret tags
working-directory-relative interpretation; absolute values remain absolute. to environment-reference names, or introduce sensitivity heuristics.
This is an explicit application path policy, not an upstream requirement or a Promptkit resolves the selected credential values. Inheriting an environment
legacy parsing mode. ConfigKit's consumer examples demonstrate alternatives but reference does not eagerly read it or change credential ownership.
do not mandate source-file-relative application paths. This adoption does not
extend import containment to application data or alter HTTP artifact containment.
## CLI Overrides And Configuration Inspection ### Existing Application Contracts
Only flags explicitly supplied by the user become ConfigKit application The target retains current configuration discovery, defaults, explicit imports,
override records. Parser defaults do not overwrite file or overlay settings. one selected overlay, explicit CLI override mapping, and command prerequisites.
Explicit empty values are not dropped. The existing invocation-specific prompt, It continues using ordinary `configkit.Load`; the new `LoadLayered` API is
profile, input, model, timeout, output, and reporting options remain invocation not required to obtain inheritance.
state rather than new application configuration fields. In particular, the
run/render retry flag remains a request override; it does not mutate the engine's
application retry setting or backend state.
Expose application configuration validation, effective redacted YAML, source Application path values, including inherited values, retain their documented
provenance, and explanation of an individual configuration path. These are working-directory-relative meaning. The new source-resource contexts do not
included features, not merely library capabilities available for future work. implicitly rebase `prompt_dir`, `profile_dir`, `schema_dir`, or
They use ConfigKit diagnostics and inspection records from the shared loading `server.artifact_root`.
pipeline, including defaults, imports, overlays, explicit CLI values, and
recorded normalization. No separate inspection-only interpretation is maintained.
Configuration inspection does not execute prompts, make provider calls, or Promptkit prompt, profile, and schema files continue to be parsed by Promptkit.
resolve API-key values. Application validation is not a promise that every ConfigKit's new directive has no effect on those independently loaded formats
Promptkit backend or definition is valid or that a provider is reachable. or on HTTP request payloads. Engine-scoped backend capacity coordination and
Command-specific execution prerequisites remain with the relevant command; request independence remain governed by the existing architecture.
inspection can explain an incomplete application configuration without requiring
an executable prompt selection. The interface is a CLI configuration command
family, not a second CLI framework or an HTTP configuration endpoint; the
implementation plan specifies its concrete commands and mappings.
Safe diagnostics must not restore raw parser errors or configuration values ## Compatibility And Release Impact
that ConfigKit deliberately suppresses. Effective output and explanation use
the upstream redacted renderers; they are inspection output, not guaranteed
reloadable configuration. Under the maintainer's selected policy, backend
`extra_params` are visible in effective output and explanation, including
historical values. There is no blanket container masking, sensitive-key heuristic,
or new selective-redaction configuration surface.
## Credential Boundary And Deferred Features ConfigKit now reserves `extends` in every application input mapping, including
dynamic backend `extra_params` and nested provider data. A previously literal
key can fail inheritance validation or be consumed and change effective data.
The reservation can also collide with a named mapping entry such as a backend
ID equal to `extends`. This is a real configuration compatibility change,
not merely a new optional syntax.
Existing `api_key_env` values remain environment-name strings passed to Promptkit. Migration guidance must distinguish structural configuration names from
They do not become ConfigKit `Secret` fields. ConfigKit eagerly resolves effective provider-defined parameter names. Application-owned names can be renamed
typed references and requires nonempty values; that would change Promptkit's where appropriate. A provider-required literal parameter cannot generally be
optional/required and selected-credential behavior. This departure from the renamed without changing the provider contract; quoting the key is not an
secret-reference feature is an ownership decision, not compatibility plumbing. escape. The selected upstream version has no inheritance opt-out or literal-key
Raw API-key fields remain unsupported under the existing architecture policy. escape. A concrete need for such a parameter should be addressed upstream,
rather than by silently adding a second Scriptorium configuration parser.
This limitation applies to application configuration, not to Promptkit-owned
profile definitions.
API-key values are the only secrets requiring ConfigKit redaction in this The reviewed maintained examples and fixtures contain no `extends` keys.
adoption. The application configuration holds environment-variable names, not Ordinary configurations without the newly reserved key should retain their
those values, so inspection neither resolves nor contains the actual keys. meaning, subject to validation of the integration.
Reference names remain visible. Do not tag `api_key_env` as secret merely to
hide its name, add an eager key lookup, or mask unrelated application settings.
The existing raw-key prohibition and Promptkit boundary provide the protection
without introducing a redundant credential-bearing configuration field.
Secrets-directory bootstrap and application schema versioning are deferred until The intended release is a new minor version, currently v0.16.0, under the
there is a concrete application need. Their availability in ConfigKit does not [release policy](../policy/release.md). Its release note should identify the
make them mandatory. Hot reload, runtime resource replacement, remote imports, inheritance feature and reserved-key migration impact. Final version selection
automatic migrations, and general environment-variable overlays are outside and publication remain release preparation work; this roadmap adds no
this adoption. These are scope limits for this feature, not new permanent publication gate or recurring upstream probe.
prohibitions on future explicitly requested work.
## Required Changes And Completion Criteria ## Work Needed From The Baseline
- Replace manual decoding/default/override machinery with the shared ConfigKit - **Dependency and attribution maintenance:** update `go.mod` and `go.sum`
integration and retain only application-specific discovery, rules, and mapping. to the published v0.5.0 tag. Update ConfigKit's version and exact-commit
- Support imports and selected overlays across commands that load application source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md` under the
configuration, and deliver the configuration inspection capabilities above. [OSS policy](../policy/oss.md). Existing standard license texts remain
- Update application configuration types, presence handling, CLI explicit-set applicable; check the selected upstream notices. Leave unrelated dependencies
mapping, and diagnostics to match the selected native semantics. and historical release records alone.
- Update maintained examples and canonical configuration, CLI, operations, - **Integration review:** verify the existing `internal/config` definition,
architecture, and internal documentation when behavior lands. Upstream generic loading, normalization, and runtime conversion preserve resolved inherited
contracts remain linked rather than copied into a competing specification. values and explicit presence. Make only changes needed for that integration;
- Add proportionate integration coverage for the cutover: defaults-only input, upstream already implements the inheritance machinery.
explicit values and nulls, imports/conflicts, overlays, CLI precedence, - **Application coverage:** add representative tests at the configuration and
inspection agreement and API-key non-disclosure, visible dynamic backend CLI boundaries for inherited backend settings, explicit zero/false and
parameters, unchanged credential ownership, and representative nullable replacements, interaction with an imported parent and selected
execution/server startup. overlay, explainable derivation, and reserved-key failure. Verify inherited
ConfigKit owns exhaustive parser and composition tests; Scriptorium tests its backend settings reach existing runtime mapping or registration. Use small
adoption and application boundaries. fixtures and behavior assertions rather than duplicating ConfigKit's
- Pin the published dependency and maintain ConfigKit and YAML attribution under exhaustive inheritance, parser, or metadata matrix.
the [OSS policy](../policy/oss.md), using imported-commit source/notice links - **Maintained examples:** add a runnable application configuration example
and applicable standard and companion license texts. under `examples/` showing backend inheritance, and link it from the owning
- Document migration in a release appropriate for the intentional breaking configuration documentation. Validate it through the real application
configuration changes under the [release policy](../policy/release.md). loading and inspection path without credentials or provider calls.
Release selection and publication remain separate preparation work; this - **Current documentation:** update `docs/config.md` with the user-facing
roadmap adds no release gate, network probe, or new distribution format. inheritance support and compatibility guidance. Update relevant dependency
references in `docs/development.md` and `docs/policy/architecture.md`;
reflect integration mechanics in `docs/internal/sources.md` and adapter
documentation where needed. CLI syntax is unchanged; update CLI documentation
only where its inspection description needs clarification. Link the pinned
upstream contract rather than copying its full specification.
- **Validation and release handoff:** run the existing deterministic suite,
race suite, vet, build, diff checks, and affected example/link checks. Prepare
accurate minor-release migration information when preparing the release.
Routine checks remain governed by the existing development and release
policies, rather than becoming new requirements introduced by this roadmap.
Completion means one ConfigKit-native application configuration path serves ## Deferred Scope
execution and inspection, the selected user-facing features work, and migrated
examples and regression coverage demonstrate the documented semantics. It does
not require adopting every ConfigKit feature or changing Promptkit definitions.
## Resolved Inspection Policy Ordered source underlays, caller-owned filesystem sources, mapping sources,
and source-resource contexts remain available library capabilities rather than
new Scriptorium interfaces in this adoption. The application has no current
requirement for bundled defaults, extra defaults-file selection, alternative
configuration media, or source-relative application resources.
On 2026-09-26 the maintainer selected no redaction for `extra_params` and limited This work does not add underlay flags, embedded configuration bundles,
the relevant secret to the API key. Inspection therefore preserves parameter schema versioning, secret-directory bootstrap, hot reload, or new HTTP
values and environment-reference names, while actual API-key values remain configuration endpoints. These are scope choices for this work set, not
outside the application configuration pipeline. Visibility is intentional; permanent prohibitions on future requested features.
this is not a promise to detect secrets placed inside arbitrary parameter values.
The delivered `config show` and `config explain` commands use ConfigKit's ## Completion Criteria
inspection writers without secret tags or a second redaction path. Both
effective and historical parameter values remain visible; `api_key_env` names Adoption is complete when the published dependency is selected; native
remain visible while Promptkit alone resolves selected credential values. inheritance works through the shared execution and inspection pipeline;
backend values and explicit replacements reach the existing runtime boundary;
focused tests and a maintained example demonstrate the integration; and
current documentation and attribution describe the selected version accurately.
The reserved-key compatibility impact must be explicit, and established
credential visibility, path interpretation, discovery, and framework ownership
must remain intact. No significant decisions remain open within this agreed
scope.