2026-10-03 17:16:02 +00:00
|
|
|
# ConfigKit v0.5.0 Adoption
|
2026-09-26 17:27:11 +00:00
|
|
|
|
|
|
|
|
## Status And Intent
|
|
|
|
|
|
2026-10-03 17:16:02 +00:00
|
|
|
Accepted feature direction, recorded on 2026-10-03; implementation is pending.
|
|
|
|
|
This roadmap replaces the completed initial ConfigKit adoption roadmap. That
|
|
|
|
|
earlier work and its resolved decisions remain available in Git at
|
|
|
|
|
`9849c6b:docs/roadmap/configkit.md`.
|
|
|
|
|
|
|
|
|
|
The maintainer is adopting ConfigKit across an application suite to standardize
|
|
|
|
|
configuration semantics. This update continues that native integration by
|
|
|
|
|
adopting ConfigKit v0.5.0 and exposing its automatic sibling inheritance.
|
|
|
|
|
An intentional configuration compatibility change is accepted. The target
|
|
|
|
|
retains Scriptorium's existing discovery and application path policies rather
|
|
|
|
|
than expanding the configuration interface merely because upstream added
|
|
|
|
|
library APIs.
|
|
|
|
|
|
|
|
|
|
This document owns the desired end state and required changes. A later
|
|
|
|
|
implementation plan will own ordered implementation instructions. The
|
|
|
|
|
[architecture policy](../policy/architecture.md),
|
|
|
|
|
[configuration contract](../config.md), and
|
|
|
|
|
[ADR 0004](../adr/0004-definition-boundary.md) establish the existing application
|
|
|
|
|
and framework ownership boundaries.
|
|
|
|
|
|
|
|
|
|
## Reviewed Baseline And Upstream Target
|
|
|
|
|
|
|
|
|
|
The baseline is Scriptorium v0.15.0 at
|
|
|
|
|
`9849c6b`, selecting ConfigKit v0.4.2 and Promptkit v0.11.2.
|
|
|
|
|
Application configuration already uses a shared ConfigKit-native
|
|
|
|
|
`Document`, defaults factory, recorded resolver, validator, and `Load`
|
|
|
|
|
boundary. Runtime conversion uses the resolved document without a second merge.
|
|
|
|
|
Execution and the `config validate`, `show`, `sources`, and `explain`
|
|
|
|
|
commands share that pipeline.
|
|
|
|
|
|
|
|
|
|
Current source selection is an explicit `--config` file, the first existing
|
|
|
|
|
documented system configuration file, or defaults-only loading. File-backed
|
|
|
|
|
loads enable explicit imports and one named overlay; explicit application CLI
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The upstream target is the published ConfigKit v0.5.0 release at full commit
|
|
|
|
|
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Canonical references are:
|
|
|
|
|
|
|
|
|
|
- [Release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/releases/v0.5.0.md).
|
|
|
|
|
- [Configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md).
|
|
|
|
|
- [Sibling inheritance](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md#sibling-inheritance).
|
|
|
|
|
- [Consumer examples](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/consumers/README.md).
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
inheritance, explicit zero and false replacements, and inheritance explanation.
|
|
|
|
|
They also confirmed that a literal `extra_params.extends` accepted by v0.4.2
|
|
|
|
|
fails under v0.5.0. This evidence supports adoption; it does not establish
|
|
|
|
|
completion of the planned regression coverage, race testing, or vet checks.
|
|
|
|
|
|
|
|
|
|
## Targeted End State
|
|
|
|
|
|
|
|
|
|
Scriptorium selects ConfigKit v0.5.0 through its public root package and keeps
|
|
|
|
|
the existing single configuration loading lifecycle. Native sibling inheritance
|
|
|
|
|
is available in application configuration wherever upstream permits it, without
|
|
|
|
|
an application-specific opt-in, collection registry, merging implementation,
|
|
|
|
|
or compatibility preprocessing.
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
ConfigKit owns structural inheritance, value presence, provenance, history,
|
|
|
|
|
and explanation. Scriptorium owns its schema, discovery, normalization,
|
|
|
|
|
application validation, and runtime mapping. Promptkit continues to own backend
|
|
|
|
|
semantics, credential lookup, framework definitions, and execution.
|
|
|
|
|
|
|
|
|
|
### Inheritance Semantics And Application Consequences
|
|
|
|
|
|
|
|
|
|
The target uses upstream semantics directly; the linked upstream contract
|
|
|
|
|
remains the canonical detailed specification:
|
|
|
|
|
|
|
|
|
|
- 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.
|
|
|
|
|
|
|
|
|
|
The backend example should demonstrate reusable complete parent settings and
|
|
|
|
|
a child with meaningful explicit replacements, including zero queue capacity
|
|
|
|
|
and a false dynamic parameter. Parameter names and values must be illustrative
|
|
|
|
|
and contain no credentials.
|
|
|
|
|
|
|
|
|
|
### Inspection And Credential Handling
|
|
|
|
|
|
|
|
|
|
`config show` presents the final resolved settings; `config explain` exposes
|
|
|
|
|
upstream inheritance origins and history, including consumed directive history
|
|
|
|
|
where supported. Both continue to use ConfigKit's native writers and the same
|
|
|
|
|
result used by execution. Inheritance creates no additional acquired source:
|
|
|
|
|
`config sources` retains its existing application DTO and source-list contract.
|
|
|
|
|
No new JSON fields or source layer are needed solely for inheritance.
|
|
|
|
|
|
|
|
|
|
The maintainer's existing inspection policy remains: ordinary `extra_params`,
|
|
|
|
|
including historical values, and `api_key_env` names remain visible.
|
|
|
|
|
Scriptorium does not resolve API-key values through ConfigKit, add secret tags
|
|
|
|
|
to environment-reference names, or introduce sensitivity heuristics.
|
|
|
|
|
Promptkit resolves the selected credential values. Inheriting an environment
|
|
|
|
|
reference does not eagerly read it or change credential ownership.
|
|
|
|
|
|
|
|
|
|
### Existing Application Contracts
|
|
|
|
|
|
|
|
|
|
The target retains current configuration discovery, defaults, explicit imports,
|
|
|
|
|
one selected overlay, explicit CLI override mapping, and command prerequisites.
|
|
|
|
|
It continues using ordinary `configkit.Load`; the new `LoadLayered` API is
|
|
|
|
|
not required to obtain inheritance.
|
|
|
|
|
|
|
|
|
|
Application path values, including inherited values, retain their documented
|
|
|
|
|
working-directory-relative meaning. The new source-resource contexts do not
|
|
|
|
|
implicitly rebase `prompt_dir`, `profile_dir`, `schema_dir`, or
|
|
|
|
|
`server.artifact_root`.
|
|
|
|
|
|
|
|
|
|
Promptkit prompt, profile, and schema files continue to be parsed by Promptkit.
|
|
|
|
|
ConfigKit's new directive has no effect on those independently loaded formats
|
|
|
|
|
or on HTTP request payloads. Engine-scoped backend capacity coordination and
|
|
|
|
|
request independence remain governed by the existing architecture.
|
|
|
|
|
|
|
|
|
|
## Compatibility And Release Impact
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Migration guidance must distinguish structural configuration names from
|
|
|
|
|
provider-defined parameter names. Application-owned names can be renamed
|
|
|
|
|
where appropriate. A provider-required literal parameter cannot generally be
|
|
|
|
|
renamed without changing the provider contract; quoting the key is not an
|
|
|
|
|
escape. The selected upstream version has no inheritance opt-out or literal-key
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
The reviewed maintained examples and fixtures contain no `extends` keys.
|
|
|
|
|
Ordinary configurations without the newly reserved key should retain their
|
|
|
|
|
meaning, subject to validation of the integration.
|
|
|
|
|
|
|
|
|
|
The intended release is a new minor version, currently v0.16.0, under the
|
|
|
|
|
[release policy](../policy/release.md). Its release note should identify the
|
|
|
|
|
inheritance feature and reserved-key migration impact. Final version selection
|
|
|
|
|
and publication remain release preparation work; this roadmap adds no
|
|
|
|
|
publication gate or recurring upstream probe.
|
|
|
|
|
|
|
|
|
|
## Work Needed From The Baseline
|
|
|
|
|
|
|
|
|
|
- **Dependency and attribution maintenance:** update `go.mod` and `go.sum`
|
|
|
|
|
to the published v0.5.0 tag. Update ConfigKit's version and exact-commit
|
|
|
|
|
source, COPYRIGHT, and LICENSE links in `docs/oss/attribution.md` under the
|
|
|
|
|
[OSS policy](../policy/oss.md). Existing standard license texts remain
|
|
|
|
|
applicable; check the selected upstream notices. Leave unrelated dependencies
|
|
|
|
|
and historical release records alone.
|
|
|
|
|
- **Integration review:** verify the existing `internal/config` definition,
|
|
|
|
|
loading, normalization, and runtime conversion preserve resolved inherited
|
|
|
|
|
values and explicit presence. Make only changes needed for that integration;
|
|
|
|
|
upstream already implements the inheritance machinery.
|
|
|
|
|
- **Application coverage:** add representative tests at the configuration and
|
|
|
|
|
CLI boundaries for inherited backend settings, explicit zero/false and
|
|
|
|
|
nullable replacements, interaction with an imported parent and selected
|
|
|
|
|
overlay, explainable derivation, and reserved-key failure. Verify inherited
|
|
|
|
|
backend settings reach existing runtime mapping or registration. Use small
|
|
|
|
|
fixtures and behavior assertions rather than duplicating ConfigKit's
|
|
|
|
|
exhaustive inheritance, parser, or metadata matrix.
|
|
|
|
|
- **Maintained examples:** add a runnable application configuration example
|
|
|
|
|
under `examples/` showing backend inheritance, and link it from the owning
|
|
|
|
|
configuration documentation. Validate it through the real application
|
|
|
|
|
loading and inspection path without credentials or provider calls.
|
|
|
|
|
- **Current documentation:** update `docs/config.md` with the user-facing
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
## Deferred Scope
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
This work does not add underlay flags, embedded configuration bundles,
|
|
|
|
|
schema versioning, secret-directory bootstrap, hot reload, or new HTTP
|
|
|
|
|
configuration endpoints. These are scope choices for this work set, not
|
|
|
|
|
permanent prohibitions on future requested features.
|
|
|
|
|
|
|
|
|
|
## Completion Criteria
|
|
|
|
|
|
|
|
|
|
Adoption is complete when the published dependency is selected; native
|
|
|
|
|
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.
|