# 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.