From 2b278c40749bb0ab894b19e1ea4c6b221ca16fbd Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 17 Nov 2026 20:25:26 +0000 Subject: [PATCH] Settle the ConfigKit upgrade scope and decisions --- docs/roadmap/configkit.md | 129 ++++++++++++++++---------------------- 1 file changed, 53 insertions(+), 76 deletions(-) diff --git a/docs/roadmap/configkit.md b/docs/roadmap/configkit.md index 6c247442..e32fc687 100644 --- a/docs/roadmap/configkit.md +++ b/docs/roadmap/configkit.md @@ -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//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//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.