Files
scriptorium/docs/roadmap/configkit.md

218 lines
12 KiB
Markdown

# ConfigKit v0.5.0 Adoption
## Status And Intent
Implemented in Scriptorium's current source on 2026-10-03; release preparation
remains separate work.
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 retains the target state, rationale, compatibility scope, and
deferred work. Implementation sequencing and completion evidence were recorded
in a separate work plan. 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 exploratory evidence informed adoption; the focused
regression coverage and full validation are recorded by the completed
implementation work.
## 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 maintained backend example demonstrates reusable complete parent settings
and a child with meaningful explicit replacements, including zero queue
capacity and a false dynamic parameter. Parameter names and values are
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.
## Scope Delivered
- **Dependency and attribution:** selected the published ConfigKit v0.5.0 tag
and updated its exact-commit attribution links without changing unrelated
dependencies or historical release records.
- **Integration and coverage:** retained the single configuration-loading
pipeline and added focused configuration and CLI tests for inheritance,
presence, provenance, source assembly, inspection, runtime conversion, and
Promptkit registration behavior.
- **Maintained example and documentation:** added a runnable backend-inheritance
configuration and updated its README, configuration, CLI, architecture, and
source-internals references while leaving CLI syntax and deferred interfaces
unchanged.
- **Validation and release handoff:** completed the deterministic tests, race
tests, vet, build, diff, link, and example-command checks. Release-note
preparation and publication remain separate work under the existing
development and release policies.
## 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 delivered: 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.