Files
scriptorium/docs/roadmap/configkit.md

13 KiB

ConfigKit v0.5.0 Adoption

Status And Intent

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, configuration contract, and ADR 0004 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:

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