Files
scriptorium/docs/roadmap/configkit.md

233 lines
13 KiB
Markdown
Raw Normal View History

2026-10-03 17:16:02 +00:00
# ConfigKit v0.5.0 Adoption
## 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.