Settle the ConfigKit upgrade scope and decisions

This commit is contained in:
2026-11-17 20:25:26 +00:00
parent db32d31708
commit 2b278c4074

View File

@@ -2,11 +2,14 @@
## Purpose
Adopt `go.maximumdirect.net/configkit` v1.2.1 and its native consumer workflow.
Adopt `go.maximumdirect.net/configkit` v1.2.0 and its native consumer workflow.
The objective is consistent configuration semantics across ConfigKit-consuming
applications. Existing Notarius composition behavior is a migration baseline,
not a compatibility requirement to reproduce through adapters.
This work set retains PromptKit v0.12.0 and go-yaml v4.0.0-rc.6. ConfigKit
v1.2.1 and stable go-yaml v4.0.0 belong to the subsequent PromptKit upgrade.
[ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md) owns the
boundary: ConfigKit delivers the final resolved application document; Notarius
supplies application schema, defaults, normalization, validation, and subsequent
@@ -23,12 +26,12 @@ Reviewed on 2026-11-17 against Notarius `b9899ea`:
- Notarius configuration version 5, imports, overlays, sibling inheritance,
declaration-relative application paths, and effective/explanation CLI reports.
The released v1.2.1 tag in `../ConfigKit` identifies source commit
`51ef3144158db1a09fabdbd1c7ae59908c84923b`. Review references:
The target v1.2.0 tag in `../ConfigKit` identifies source commit
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. Review references:
- [Consumer adoption guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/consumers/README.md)
- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/config.md)
- [Release notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/releases/)
- [Consumer adoption guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/consumers/README.md)
- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/config.md)
- [Release notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.0/docs/releases/)
All intervening release notes were read in the local checkout. The important
changes are:
@@ -43,7 +46,7 @@ changes are:
| v1.0.0 | New module path, source-root `config` controls, public API cleanup, source lookup, and Go 1.27.0 minimum. |
| v1.1.0 | Field-level normalization inside lists; identity-aware provenance/history across record movement. |
| v1.2.0 | Main-relative companion inputs and layered overlay context selection. |
| v1.2.1 | Stable go-yaml v4.0.0 and loader-plugin adaptation. |
| v1.2.1 (reviewed, deferred) | Stable go-yaml v4.0.0 and loader-plugin adaptation; adopted with the subsequent PromptKit upgrade. |
### Current Integration Areas
@@ -118,11 +121,15 @@ Dependency-ready assembly order, not a Notarius sorting or append pass, controls
composition. Final Notarius checks still validate stage order, supported modules,
reference dependencies, and unique application identifiers.
Step identity registration is an explicit decision below. Other identified
collections remain available through author declarations; no broad automatic
`id` inference or universal registration is required. Demonstrate a composed
step list and a derived pipeline using native controls in maintained examples
or small canonical snippets, with behavioral coverage.
Register `id` for `/pipelines/<any-mapping-key>/steps` through
`SequenceIdentityMatching`. Step IDs already carry application meaning and
uniqueness requirements. Native identity permits independently imported steps
and supplies the ordinary upsert default for overlays and inheritance. Authors
can explicitly select replacement or append. Other identified collections
remain available through author declarations; no broad automatic `id` inference
or universal registration is required. Demonstrate a composed step list and a
derived pipeline using native controls in maintained examples or small canonical
snippets, with behavioral coverage.
CLI overrides apply after inheritance and typed decoding, before application
resolution. Preserve explicit zero/false/empty values. Structural errors cannot
@@ -135,8 +142,11 @@ domain semantics applied to the final configuration.
Replace manual acquisition/probing with ConfigKit source descriptions. Explicit
`--config` and, when no CLI selection exists, `NOTARIUS_CONFIG` select exclusive
`File` sources: a missing selected file fails instead of searching elsewhere.
For default discovery use `SearchConfig` with an approved search convention;
the recommended Unix-system preset and its alternative are recorded below.
For default discovery use `SearchConfig` with `UnixSystemDirectories()`.
The native preset fits Notarius's sysadmin-focused deployment and includes the
existing installed location among its conventional candidates. Document its
candidate names/order and native first-selected-file failure behavior. User,
home, and working-directory presets are not enabled by this choice.
Use a required search for commands that require a configuration file, preserving
their need for a selected configuration. This does not impose requiredness on
all imports or on separate defaults-only programmatic loads.
@@ -184,18 +194,22 @@ diff or secrets-management workflow is not required for this adoption.
## Dependency And Toolchain Boundary
The target is ConfigKit v1.2.1, stable go-yaml v4.0.0, and a Go consumer minimum
The target is ConfigKit v1.2.0, go-yaml v4.0.0-rc.6, and a Go consumer minimum
of 1.27.0. Update the selected release-validation toolchain, setup guidance, and
actual configured build/CI environments consistently. Minimum and validation
patch remain separate choices. Include Go and configuration migration impact in
the eventual release note; patch releases cannot raise the Go minimum.
PromptKit v0.12.0 exposes **old-path ConfigKit types** through `Config.Sources`,
its source helpers, and inspection. Keep these contained in the LLM adapter
until its separate upgrade; ordinary Notarius configuration uses new-path types.
Prefer neutral scalar/domain handoffs over translating dependency-owned graphs.
its source helpers, and inspection. The approved intermediate architecture
retains old-path ConfigKit v0.5.0 for that dependency while ordinary Notarius
configuration uses new-path ConfigKit v1.2.0. Keep each package's types inside
its owning integration boundary. Prefer neutral scalar/domain handoffs over
translating dependency-owned graphs. Maintain the old PromptKit format for its
operator files and fixtures during this work set.
There is also a concrete shared-dependency incompatibility:
The selected intermediate versions share YAML rc.6. A direct v1.2.1 upgrade
would introduce a shared-dependency incompatibility:
- ConfigKit v1.2.1 requires stable go-yaml v4.0.0.
- Old-path ConfigKit v0.5.0 imports `go.yaml.in/yaml/v4/plugin/limit`.
@@ -203,17 +217,19 @@ There is also a concrete shared-dependency incompatibility:
- Go selects one version of this shared YAML module, despite ConfigKit itself
having two distinct module paths.
Therefore keeping PromptKit v0.12.0 and its unpatched ConfigKit v0.5.0 does not
produce a buildable v1.2.1 target. Resolve the open dependency decision before
finalizing the implementation plan. Neither a local fork/replace nor silently
ending at ConfigKit v1.2.0 is the target architecture. This planning pass made
no dependency changes and ran no trial application build.
Targeting v1.2.0 avoids that specific package-removal conflict using released
dependencies, without maintaining an upstream compatibility patch. Verify the
mixed dependency graph and native build early in implementation; no trial build
has yet established full compatibility. This work set is complete at v1.2.0
when its native semantics and integration pass acceptance, independently of the
later PromptKit upgrade.
## Required Repository Work And Acceptance
- Migrate application-side dependency imports, APIs, diagnostics, source
declarations, inspection, and discovery; resolve the PromptKit/YAML boundary
through the approved dependency path. Native builds must pass at completion.
declarations, inspection, and discovery. Verify coexistence of new-path
ConfigKit v1.2.0, old-path v0.5.0, PromptKit v0.12.0, and YAML rc.6 without
dependency forks or replacements. Native builds must pass at completion.
- Update real-file loading, imports, overlays, inheritance, CLI assignment,
path-origin, failure, and ownership tests under `internal/core/config` and
`internal/cli`. Add representative collection composition and step-reference
@@ -228,7 +244,7 @@ no dependency changes and ran no trial application build.
and affected dependency integration references. Preserve accepted ADR history;
ADR-0020 already supplies the durable ownership rationale.
- Update `docs/oss/attribution.md` from actual selected module revisions and
notices, including coexistence of old/new ConfigKit if applicable, stable YAML,
notices, including both selected ConfigKit module identities, retained YAML rc.6,
and newly selected transitive dependencies. Preserve the application grant.
Upstream ReleaseKit is maintainer tooling; adopting it as Notarius release
machinery or adding its gates is outside this feature.
@@ -243,54 +259,15 @@ on a coherent dependency graph, with final domain validation and no unresolved
directives at runtime. The old ConfigKit 0.5 roadmap is replaced by this feature
scope; unrelated completed plans and review findings remain separate records.
## Open Decisions
## Deferred To The PromptKit Upgrade
### 1. Resolve The Stable-YAML Conflict With Old PromptKit
The next work set upgrades PromptKit together with ConfigKit v1.2.1 and stable
go-yaml v4.0.0. Its roadmap will cover PromptKit's module/API and source-format
migration, replace the temporary old-path ConfigKit integration, and remove old
dependencies when no longer used. It will also update the relevant tests,
inspection/checkpoint integration, documentation, and attribution for the final
selected graph. That later work does not gate completion of this v1.2.0 scope.
Recommendation: seek a narrowly scoped **released upstream compatibility patch**
for the old ConfigKit module used by PromptKit, adapting it to stable go-yaml.
If upstream supports that patch, the two module identities can coexist briefly
and Notarius can complete its ConfigKit upgrade before the separate PromptKit
feature migration. This preserves the desired ordering using supported releases
rather than adding application-owned compatibility machinery. No such patch is
assumed to exist or assigned an invented release number here.
Alternative: coordinate the PromptKit adapter's module/API migration with this
cutover and select a current PromptKit release that consumes ConfigKit v1.2.1.
This is the cleaner long-term dependency graph and avoids maintaining a legacy
patch, but couples the two implementation work sets. If selected, prepare the
PromptKit roadmap before claiming a standalone ConfigKit sprint can finish.
A temporary ConfigKit v1.2.0 checkpoint can assist that coordinated migration
because it still selects YAML rc.6, but it does not complete this roadmap's
v1.2.1 target. Dependency patches/forks inside Notarius are not the recommendation.
### 2. Default Main-File Search Convention
Recommendation: use ConfigKit's `UnixSystemDirectories()` preset for default
Notarius discovery, with `SearchOptions.Required` enabled. It fits the
sysadmin-focused deployment, retains the existing installed location among its
candidates, and shares conventional names/order with other ConfigKit consumers.
Explicit CLI/environment selections remain exclusive file choices. Document the
new candidates and native first-selected-file failure behavior.
Alternative: use `SearchPaths` containing only the current installed default
`/usr/local/etc/notarius/config.yml`. This still delegates acquisition to ConfigKit
and minimizes discovery changes, but offers less convention sharing. User/home
or working-directory presets can be selected deliberately if a broader discovery
workflow is desired; they are not silently enabled by the recommended preset.
### 3. Application Identity For Pipeline Steps
Recommendation: register `id` for `/pipelines/<any-mapping-key>/steps` using
`SequenceIdentityMatching`. Step IDs already have application significance and
uniqueness checks. Native identity makes independently imported steps composable
and gives overlays/inheritance the ordinary upsert default. Authors can explicitly
select replacement or append. Document the full-record upsert rule and clearing
semantics, and exercise reference-dependent paths after composition.
Alternative: leave sequence registrations empty and let authors opt in with
source-local `config.sequences` declarations. This is also ConfigKit-native and
preserves ordinary unregistered-list replacement when no declaration is supplied,
but each composed pipeline must declare its collection identity. In either case,
avoid automatic identity inference for validator chains or other unrelated lists.
The dependency approach, Unix-system discovery preset, and application step
identity registration are approved decisions. No significant open decisions
remain for this feature roadmap.