Settle the ConfigKit upgrade scope and decisions
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user