23 KiB
ConfigKit v1.2.0 Interim Adoption
Status And Intent
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. 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.
This replaces the completed v0.5.0 roadmap, preserved at
ba24b7a879c95e2b306e0d53eb0b45e043e1b29a:docs/roadmap/configkit.md.
The implementation plan owns the staged changes and
validation for this upgrade. This roadmap owns the target state, scope, and
policy choices; implementation status and stage evidence belong in that plan.
Reviewed Baseline And Target
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.
Application configuration already uses ConfigKit through internal/config:
Document, a fresh defaults factory, a recorded resolver, and a validator define application settings.Settingsconverts the resolved result without another merge.Loadselects an explicit file or runs a localos.Statloop over two system configuration paths, falling back toNoSource. File-backed loads enable imports, one selected overlay, and explicit application CLI overrides.- Application inspection reuses the retained result.
showandexplainuse native writers;sourcesprojectsid,label,layer, and availablepathinto 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.
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:
- Consumer adoption and migration guide.
- Configuration contract.
- v1.2.0 release note.
- v1.0.0 breaking-change inventory.
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 | 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 | Effective-configuration Diff with combined sensitivity protection. Useful future operator functionality, not required for native loading. |
| v0.7.1 | Maintainer-tool update; no application runtime or configuration migration. |
| v0.8.0 | 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 | 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 | Native configuration discovery and expanded absent-main loading. Replace application filesystem probing with a ConfigKit search description. |
| v0.10.1 | Internal consolidation without public migration; inherit the fixes rather than reproduce the machinery. |
| v0.10.2 | Acquisition, cleanup, projection-limit, and collection fixes. Accept corrected upstream diagnostics without adding application limits or recovery machinery. |
| v1.0.0 | 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 | 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 | Main-relative layered companions and derived/fallback overlay contexts. Available for future multi-source application needs; ordinary Load remains appropriate today. |
| v1.2.1 | 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:
- Old and vanity ConfigKit paths have different named Go types.
newEnginecurrently constructs old-pathInputandUnderlayvalues for PromptKit. New-path application overrides and results cannot simply replace those types at that boundary. - 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.0wherever 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
One Native Application Loading Path
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.
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.
ConfigKit-Owned Discovery
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.
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.
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.
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.
Native Source Controls, Imports, And Collections
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.
Leave ImportDefaults unspecified unless a future application requirement
warrants a choice. In particular:
- Imports are optional by default. Indispensable maintained fragments declare
required: true; intentionally optional imports may omit it. Remove oldoptionaldeclarations rather than translate them at runtime. - Native
path,dir, andglobselectors, 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.sequencesfor native identity, append, upsert, and replacement. promptkit_sourceshas 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.
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.
Current Resolution And CLI Lifecycle
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.
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.
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 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.
Inspection And Disclosure
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.
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.
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.
Required Changes And Supporting Material
- 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.
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.
Validation And Completion Criteria
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,
mainprovenance, 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.