Plan interim ConfigKit upgrade

This commit is contained in:
2026-11-17 20:27:12 +00:00
parent ba24b7a879
commit a5d8394313

View File

@@ -1,217 +1,354 @@
# ConfigKit v0.5.0 Adoption
# ConfigKit v1.2.0 Interim 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`.
Drafted on 2026-11-17. The maintainer selected an interim ConfigKit v1.2.0
upgrade, followed by ConfigKit v1.2.1 as part of the upcoming PromptKit upgrade.
This roadmap describes that interim target and the changes needed to reach it;
it is not an implementation plan or a claim that the upgrade has landed.
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.
configuration semantics. Scriptorium should use the selected ConfigKit's native
loading path, rather than reproduce older processing rules for compatibility.
Configuration migration is acceptable. Application schema and deployment choices
remain Scriptorium's responsibilities under
[ADR 0005](../adr/0005-configkit-boundary.md).
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.
This replaces the completed v0.5.0 roadmap, preserved at
`ba24b7a879c95e2b306e0d53eb0b45e043e1b29a:docs/roadmap/configkit.md`.
The existing [implementation document](implementation.md) concerns the previous
PromptKit work set and is not the implementation plan for this upgrade.
## Reviewed Baseline And Upstream Target
## Reviewed Baseline And 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.
The reviewed Scriptorium revision is
`ba24b7a879c95e2b306e0d53eb0b45e043e1b29a`. Its selected modules are
`gitea.maximumdirect.net/eric/ConfigKit v0.5.0` and
`gitea.maximumdirect.net/eric/promptkit v0.12.0`, with
`go.yaml.in/yaml/v4 v4.0.0-rc.6`. The consumer Go minimum is 1.25.5; release
validation and hosted builds select Go 1.26.11.
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.
Application configuration already uses ConfigKit through `internal/config`:
The upstream target is the published ConfigKit v0.5.0 release at full commit
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Canonical references are:
- `Document`, a fresh defaults factory, a recorded resolver, and a validator
define application settings. `Settings` converts the resolved result without
another merge.
- `Load` selects an explicit file or runs a local `os.Stat` loop over two system
configuration paths, falling back to `NoSource`. File-backed loads enable
imports, one selected overlay, and explicit application CLI overrides.
- Application inspection reuses the retained result. `show` and `explain` use
native writers; `sources` projects `id`, `label`, `layer`, and available
`path` into a Scriptorium-owned JSON array.
- Application path values are working-directory-relative. Framework source
selectors are translated separately into ConfigKit values accepted by
PromptKit's current public API.
- [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 interim target is `go.maximumdirect.net/configkit v1.2.0` at full commit
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. The locally available v1.2.0 tag and
remotely verified published tag identify that same commit. 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.
- [Consumer adoption and migration guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/consumers/README.md).
- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
- [v1.2.0 release note](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md).
- [v1.0.0 breaking-change inventory](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md).
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.
The interim target requires Go 1.27.0 and retains go-yaml v4.0.0-rc.6. PromptKit
stays at v0.12.0 and continues selecting old-path ConfigKit v0.5.0. ConfigKit's
code grant remains LGPL-3.0-or-later. This review examined release notes, public
contracts, Scriptorium's integration, and a focused dependency compatibility
experiment; it did not migrate or validate the full application against v1.2.0.
## Intervening Release Review
All published releases after the selected v0.5.0 through v1.2.1 were reviewed.
Notes through v1.2.0 are linked at the interim target revision. The v1.2.1 note
is linked at its own commit and describes deliberately deferred work.
| Release | Consumer-facing change and adoption consequence |
| --- | --- |
| [v0.6.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.6.0.md) | Loading/inspection improvements and Go 1.26.0 minimum. Obtain improvements through the dependency; no Scriptorium performance guarantee or benchmark gate follows. |
| [v0.7.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.7.0.md) | Effective-configuration `Diff` with combined sensitivity protection. Useful future operator functionality, not required for native loading. |
| [v0.7.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.7.1.md) | Maintainer-tool update; no application runtime or configuration migration. |
| [v0.8.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.8.0.md) | Input destinations, sequence-item placement, shared source-version checks, and initial identified sequences. Authored imports can use applicable placement; application version policy and Go identity registrations remain opt-in. |
| [v0.9.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.9.0.md) | Expanded imports/defaults, author-declared collection operations, identified-record inheritance, and dependency-ready ordering. Imports become optional by default; CLI assignment moves after inheritance and typed decoding. Migrate old syntax and lifecycle assumptions. |
| [v0.10.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.0.md) | Native configuration discovery and expanded absent-main loading. Replace application filesystem probing with a ConfigKit search description. |
| [v0.10.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.1.md) | Internal consolidation without public migration; inherit the fixes rather than reproduce the machinery. |
| [v0.10.2](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v0.10.2.md) | Acquisition, cleanup, projection-limit, and collection fixes. Accept corrected upstream diagnostics without adding application limits or recovery machinery. |
| [v1.0.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md) | New module identity, Go 1.27.0, source-root `config` controls, API cleanup, `main` provenance, source lookup, and inspection fixes. These require migration. |
| [v1.1.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.1.0.md) | Field-level resolution recording within lists and identity-aware history for registered collections. Remove redundant whole-list normalization recording when leaf records cover all edits. |
| [v1.2.0](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md) | Main-relative layered companions and derived/fallback overlay contexts. Available for future multi-source application needs; ordinary `Load` remains appropriate today. |
| [v1.2.1](https://forge.maximumdirect.net/base-layer/configkit/src/commit/51ef3144158db1a09fabdbd1c7ae59908c84923b/docs/releases/v1.2.1.md) | Stable go-yaml v4 and loader-plugin adaptation. Deferred to the PromptKit upgrade because of the shared dependency obstacle below. |
Upstream release-tool changes do not require Scriptorium to adopt ReleaseKit or
copy upstream publication procedures.
## Dependency Boundary And Sequencing
There are two distinct compatibility issues, not just import renaming:
1. Old and vanity ConfigKit paths have different named Go types. `newEngine`
currently constructs old-path `Input` and `Underlay` values for PromptKit.
New-path application overrides and results cannot simply replace those
types at that boundary.
2. Both paths select the same go-yaml v4 module through Go's module graph.
ConfigKit v1.2.1 requires v4.0.0. Old ConfigKit v0.5.0 imports
`go.yaml.in/yaml/v4/plugin/limit`, which is absent from stable v4.
An isolated temporary module requiring only old ConfigKit v0.5.0 and go-yaml
v4.0.0 failed a package compile check:
`go test -mod=mod -run '^$' gitea.maximumdirect.net/eric/ConfigKit`.
Package setup failed at that missing import; the selected module graph was
verified. This is a compile-time dependency conflict, not evidence of a
Scriptorium runtime failure. Repository source and dependency files were untouched.
Retaining old-path adapter imports alone cannot bridge v1.2.1, but the selected
v1.2.0 target still declares the same YAML prerelease as the existing stack.
The interim graph deliberately contains both ConfigKit module identities:
- Application loading, overrides, callbacks, diagnostics, and application
inspection use `go.maximumdirect.net/configkit v1.2.0`.
- Framework construction and captured framework inspection retain
`gitea.maximumdirect.net/eric/ConfigKit v0.5.0` wherever PromptKit v0.12.0's
public API requires its types.
- Both share `go.yaml.in/yaml/v4 v4.0.0-rc.6`. Validate the complete selected
graph, including transitive requirements; agreement of direct requirements
alone is not proof that the application works.
Use clear local import aliases where both packages are needed. Build each
owner's values directly with its own public types; serialization or a new
cross-version facade is unnecessary. Framework JSON Pointer parsing and writers
must use the old owner's types, while application diagnostics use the new
owner's types. Review shared source DTOs for named layer-type assignments.
Runtime `AppSettings` and application-owned selector values can continue to
cross the existing adapter boundary without transporting a ConfigKit result
into PromptKit.
The upcoming PromptKit roadmap owns migration to a compatible framework release,
ConfigKit v1.2.1, stable YAML, and removal of old ConfigKit imports and notices
when no longer used. PromptKit v0.23.2 already demonstrates that dependency
combination, but selecting and assessing its full migration remains later work.
This interim upgrade uses published dependencies without local replacements or
copied loaders under the existing architecture policy.
The two loaders deliberately have different format generations during this
interval. Migrate application documents and their imports to v1.2.0 controls;
framework files selected for PromptKit remain governed by its v0.12.0 contract,
including any old ConfigKit import controls it supports. Do not bulk-rename
controls across all YAML files or parse framework documents with the new
application loader.
## 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.
### One Native Application Loading Path
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.
`internal/config` consumes the public `go.maximumdirect.net/configkit` package.
All command families use one definition and one completed application load per
selection. Runtime settings come from `result.Config`; inspection uses that
result's captured public views.
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.
Ordinary `configkit.Load` remains the entry point. A main file with imports and
an overlay does not require artificial underlay groups, embedded defaults, or a
new configuration abstraction. Fresh typed defaults, recorded normalization,
and final domain validation remain definition callbacks.
### Inheritance Semantics And Application Consequences
### ConfigKit-Owned Discovery
The target uses upstream semantics directly; the linked upstream contract
remains the canonical detailed specification:
An explicit `--config` selects `configkit.File` exclusively. Omission selects
`SearchConfig` with ordered `SearchPaths` for
`/usr/local/etc/scriptorium/config.yml` and `/etc/scriptorium/config.yml`.
Delete the `os.Stat` loop and hand-written discovery errors; ConfigKit owns
selection, acquisition, absence, and structured diagnostics.
- 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.
These locations are application-selected deployment conventions, not a
compatibility implementation of library processing. ConfigKit does not mandate
one search convention. Its directory presets consider additional filenames and,
in some cases, platform constraints; adopting those or adding user/home/current
directory discovery is a separate application choice.
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.
Use an optional search and native defaults. Exhaustion contributes no fabricated
source; a selected-file error terminates loading. Enable imports directly:
an absent main has no declarations to traverse, so no existence precheck is
necessary.
### Inspection And Credential Handling
Keep the overlay-name selector and delegate its processing. The current CLI has
no independent overlay filesystem root; without a selected main or explicit
context, an active overlay cannot be located. Report ConfigKit's outcome rather
than create a permanent application prohibition on overlays without a main.
The library supports that combination when an appropriate context is supplied.
`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.
### Native Source Controls, Imports, And Collections
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.
Application sources use root `config` controls, including fragments and selected
overlays where their controls are allowed. Rename genuine old control blocks in
maintained application examples and fixtures. Do not introduce aliases or
runtime rewriting. Nested `config`, and former `configkit` and `_configkit`
names, follow ordinary schema rules rather than a global reserved-key rule.
### Existing Application Contracts
Leave `ImportDefaults` unspecified unless a future application requirement
warrants a choice. In particular:
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.
- Imports are optional by default. Indispensable maintained fragments declare
`required: true`; intentionally optional imports may omit it. Remove old
`optional` declarations rather than translate them at runtime.
- Native `path`, `dir`, and `glob` selectors, lists, filters, recursion,
destinations, and item placement are available wherever ConfigKit allows.
Directory filename selection is unrestricted by default; YAML-only examples
should author a pattern. Hidden/symlink discovery follows native defaults,
not application filtering.
- Strict peer composition, dependency-ready assembly, inheritance, and
collection policy remain upstream responsibilities. Sources can declare
`config.sequences` for native identity, append, upsert, and replacement.
- `promptkit_sources` has no application identity field. Add no identity
registration, inferred path identity, duplicate prohibition, or forced
replacement solely for this upgrade. Ordinary unkeyed lists replace across
precedence boundaries; authored collection policy may change that behavior.
CLI lists remain whole-list replacements after decoding.
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`.
Import and overlay containment remain library behavior. Application resource
strings such as `schema_dir`, framework selectors, and HTTP artifact roots are
not source-control paths; ConfigKit does not automatically rebase them. Keep
their working-directory-relative interpretation in this scope. Source-relative
resource behavior would require a separate application choice using public
origin/context APIs. No broader filesystem sandbox is introduced.
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.
### Current Resolution And CLI Lifecycle
## Compatibility And Release Impact
Adopt assembly, inheritance, typed defaults/decoding, explicit CLI assignment,
recorded resolution, credential processing where applicable, and validation in
the current upstream order. Source syntax, composition, inheritance, and decoding
failures cannot be repaired by later CLI overrides. Valid decoded values can
still be replaced before application validation.
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.
Continue mapping only explicitly visited flags to public `Override` records,
with safe labels and supported built-in values. Preserve explicit empty, false,
zero, and allowed null values according to the application schema. Recorded
normalization may change those values through native helpers.
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.
Migrate used removed symbols, especially the resolver's generic `Record` call,
to current APIs. Leaf `Normalize` calls now cover individual edits within the
equal-length `promptkit_sources` list; a second whole-list record is unnecessary.
Do not add identity merely to obtain field auditing. Future membership/order
changes use the applicable native container-recording rules.
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 v1 inventory also includes `EntryInfo`, `Sensitive`,
`SourceVersionModeMainOnly`, `SourceVersionEvidence`,
`EmptyImportSelections`, `DestinationIsFallback`, `SearchPaths`,
`FollowSymlinks`/`IncludeHidden`, `LayerMain`, and
`CodeHistoryLimitExceeded`. Update actual uses and tests; this list does not
require implementing features that Scriptorium does not use.
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.
### Inspection And Disclosure
## Scope Delivered
Keep `config validate`, `show`, `sources`, and `explain` as the application
inspection surface. Native writers own effective YAML and explanation semantics,
including improved list-field history. Retain the small application source DTO;
its main layer now reports `main`, not `base`. Acquisition order is not
composition order, and load-local source IDs are not durable identities.
- **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.
Source lookup, empty optional-selection evidence, and placement metadata remain
available through public results for future focused operator enhancements.
Adoption does not require dumping every source field into the CLI schema.
Existing stream separation, writer-error handling, and application-versus-framework
inspection boundaries remain applicable.
## Deferred Scope
The application document has no raw API-key field. Migration adds no sensitivity
heuristics, redaction of environment names, or redaction of ordinary provider
parameters. API-key values remain the secret requiring protection; PromptKit
owns framework credential handling. The accepted scoped native redaction of
framework configuration inspection is separate from application inspection.
The renamed `Sensitive` hook does not establish a broader disclosure policy.
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.
## Required Changes And Supporting Material
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.
- Update dependency/import identity, used symbols, discovery construction,
normalization records, diagnostics, and application/CLI fixtures. Keep the
PromptKit-owned old types isolated from new application types and retain the
shared YAML prerelease in the selected graph.
- Raise `go.mod`'s consumer minimum to 1.27.0 and select a supported Go 1.27
release patch for validation and builds. Update current 1.26.11 release
instructions and the hosted image together; no higher consumer patch minimum
or extra platform matrix is implied.
- Migrate application composition examples to `config.imports`, with explicit
requiredness where they depend on a fragment. Demonstrate one useful native
collection composition on the selector list without adding a schema identity
field or universal registration.
- Update configuration/CLI contracts, contributor/toolchain guidance,
architecture dependency descriptions, source/adapter internals, and affected
README/example navigation. Correct obsolete source-internals text about
sorting application backend IDs: those backends were removed and selector
order is meaningful. Preserve accepted ADR decisions and historical notes.
- Update ConfigKit attribution to identify both the new application module at
v1.2.0 and the old module at v0.5.0 still used with PromptKit. Preserve each
revision's applicable notices and exact-commit links, using separate factual
component entries where needed. Leave unchanged PromptKit and YAML selections
and notices accurate; do not prematurely claim stable YAML adoption. Inspect
other affected selected runtime dependencies under the OSS policy.
- Preserve existing faithful LGPL/GPL and other applicable standard texts;
verify changed upstream project notices under the OSS policy. Maintainer
tool requirements may affect module selection without becoming runtime
imports. Their presence alone requires neither Scriptorium tool adoption nor
attribution for tools not incorporated into its distributed material.
## Completion Criteria
The eventual release should be a new minor version under the adopted release
policy: consumer minimum and configuration contracts change. Notes should
explain control-block migration, required imports, CLI ordering, provenance
naming, and the intentional application/framework version split. Exact version
selection and publication remain separate preparation work.
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.
## Validation And Completion Criteria
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.
The eventual implementation is complete when:
- The published graph selects application ConfigKit v1.2.0, old-path ConfigKit
v0.5.0 for PromptKit v0.12.0, and go-yaml v4.0.0-rc.6. It builds with each
boundary using its owner's public types and without a cross-version shim.
- Explicit-file, native discovery, exhaustion/defaults-only, and selected-file
error cases use one native load. Inspection and execution share the
application definition and resolution boundary.
- Representative application tests cover new controls, optional/required
imports, an applicable expanded selector/placement, native collection and
overlay behavior, and changed CLI timing. Distinguish decode failures from
domain validation that CLI values can legitimately affect.
- Leaf normalization, explicit zero/false/null handling, `main` provenance,
and selector-list explanation work through the public result and CLI without
duplicating upstream's exhaustive test matrix.
- Render and representative CLI/HTTP execution continue through PromptKit
v0.12.0, including shared capacity and existing artifact handling. Application
v1.2.0 controls and inspection do not reinterpret framework configuration as
if its independent loader had also been upgraded.
- Documentation, examples, attribution, and toolchains match the implemented
graph and semantics. Run applicable development checks and existing release
target builds. Add no recurring synchronization checks, scanners, provider
probes, performance promises, or publication gates merely for this upgrade.
No implementation or full target-graph test pass is claimed by this review.
## Plausible Future Work Outside This Adoption
The upcoming PromptKit upgrade includes ConfigKit v1.2.1 and stable go-yaml,
unifies ConfigKit's module identity, and retires this temporary framework
boundary. Completing this v1.2.0 roadmap does not require that later work.
`config diff` could expose native effective-value comparison for two files or
an overlay's impact using safe snapshots, not rendered-text comparison. It is
useful operator work, but not necessary to standardize existing loading semantics
and remains a separately scoped enhancement.
Layered application underlays, main-relative companions, bundled defaults,
additional discovery locations, source-relative resources, source-detail
inspection, and source-version policy remain available for concrete future
needs. This scope also leaves HTTP configuration inspection, hot reload, and
secrets-directory bootstrap for separate consideration. None is permanently
prohibited by this roadmap.
## Confirmed Sequencing Decision
The maintainer selected v1.2.0 as the complete target of this work set so native
application adoption can precede the larger PromptKit migration. The tradeoff is
temporary coexistence of two ConfigKit generations and deferred stable YAML.
A coordinated cutover to both latest dependencies was considered; it avoids
that intermediate state but would combine the larger framework API migration
with application configuration work. The selected scope keeps those work sets
separate and carries an explicit retirement handoff to the PromptKit roadmap.
No significant product decisions remain open within this interim scope.