Plan interim ConfigKit upgrade
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user