Settle the ConfigKit upgrade scope and decisions
This commit is contained in:
@@ -2,11 +2,14 @@
|
|||||||
|
|
||||||
## Purpose
|
## 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
|
The objective is consistent configuration semantics across ConfigKit-consuming
|
||||||
applications. Existing Notarius composition behavior is a migration baseline,
|
applications. Existing Notarius composition behavior is a migration baseline,
|
||||||
not a compatibility requirement to reproduce through adapters.
|
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
|
[ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md) owns the
|
||||||
boundary: ConfigKit delivers the final resolved application document; Notarius
|
boundary: ConfigKit delivers the final resolved application document; Notarius
|
||||||
supplies application schema, defaults, normalization, validation, and subsequent
|
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,
|
- Notarius configuration version 5, imports, overlays, sibling inheritance,
|
||||||
declaration-relative application paths, and effective/explanation CLI reports.
|
declaration-relative application paths, and effective/explanation CLI reports.
|
||||||
|
|
||||||
The released v1.2.1 tag in `../ConfigKit` identifies source commit
|
The target v1.2.0 tag in `../ConfigKit` identifies source commit
|
||||||
`51ef3144158db1a09fabdbd1c7ae59908c84923b`. Review references:
|
`c1c7e87f2cdf77a0cbf3327831ac05578e756b9e`. Review references:
|
||||||
|
|
||||||
- [Consumer adoption guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/consumers/README.md)
|
- [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.1/docs/config.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.1/docs/releases/)
|
- [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
|
All intervening release notes were read in the local checkout. The important
|
||||||
changes are:
|
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.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.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.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
|
### 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,
|
composition. Final Notarius checks still validate stage order, supported modules,
|
||||||
reference dependencies, and unique application identifiers.
|
reference dependencies, and unique application identifiers.
|
||||||
|
|
||||||
Step identity registration is an explicit decision below. Other identified
|
Register `id` for `/pipelines/<any-mapping-key>/steps` through
|
||||||
collections remain available through author declarations; no broad automatic
|
`SequenceIdentityMatching`. Step IDs already carry application meaning and
|
||||||
`id` inference or universal registration is required. Demonstrate a composed
|
uniqueness requirements. Native identity permits independently imported steps
|
||||||
step list and a derived pipeline using native controls in maintained examples
|
and supplies the ordinary upsert default for overlays and inheritance. Authors
|
||||||
or small canonical snippets, with behavioral coverage.
|
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
|
CLI overrides apply after inheritance and typed decoding, before application
|
||||||
resolution. Preserve explicit zero/false/empty values. Structural errors cannot
|
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
|
Replace manual acquisition/probing with ConfigKit source descriptions. Explicit
|
||||||
`--config` and, when no CLI selection exists, `NOTARIUS_CONFIG` select exclusive
|
`--config` and, when no CLI selection exists, `NOTARIUS_CONFIG` select exclusive
|
||||||
`File` sources: a missing selected file fails instead of searching elsewhere.
|
`File` sources: a missing selected file fails instead of searching elsewhere.
|
||||||
For default discovery use `SearchConfig` with an approved search convention;
|
For default discovery use `SearchConfig` with `UnixSystemDirectories()`.
|
||||||
the recommended Unix-system preset and its alternative are recorded below.
|
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
|
Use a required search for commands that require a configuration file, preserving
|
||||||
their need for a selected configuration. This does not impose requiredness on
|
their need for a selected configuration. This does not impose requiredness on
|
||||||
all imports or on separate defaults-only programmatic loads.
|
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
|
## 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
|
of 1.27.0. Update the selected release-validation toolchain, setup guidance, and
|
||||||
actual configured build/CI environments consistently. Minimum and validation
|
actual configured build/CI environments consistently. Minimum and validation
|
||||||
patch remain separate choices. Include Go and configuration migration impact in
|
patch remain separate choices. Include Go and configuration migration impact in
|
||||||
the eventual release note; patch releases cannot raise the Go minimum.
|
the eventual release note; patch releases cannot raise the Go minimum.
|
||||||
|
|
||||||
PromptKit v0.12.0 exposes **old-path ConfigKit types** through `Config.Sources`,
|
PromptKit v0.12.0 exposes **old-path ConfigKit types** through `Config.Sources`,
|
||||||
its source helpers, and inspection. Keep these contained in the LLM adapter
|
its source helpers, and inspection. The approved intermediate architecture
|
||||||
until its separate upgrade; ordinary Notarius configuration uses new-path types.
|
retains old-path ConfigKit v0.5.0 for that dependency while ordinary Notarius
|
||||||
Prefer neutral scalar/domain handoffs over translating dependency-owned graphs.
|
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.
|
- 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`.
|
- 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
|
- Go selects one version of this shared YAML module, despite ConfigKit itself
|
||||||
having two distinct module paths.
|
having two distinct module paths.
|
||||||
|
|
||||||
Therefore keeping PromptKit v0.12.0 and its unpatched ConfigKit v0.5.0 does not
|
Targeting v1.2.0 avoids that specific package-removal conflict using released
|
||||||
produce a buildable v1.2.1 target. Resolve the open dependency decision before
|
dependencies, without maintaining an upstream compatibility patch. Verify the
|
||||||
finalizing the implementation plan. Neither a local fork/replace nor silently
|
mixed dependency graph and native build early in implementation; no trial build
|
||||||
ending at ConfigKit v1.2.0 is the target architecture. This planning pass made
|
has yet established full compatibility. This work set is complete at v1.2.0
|
||||||
no dependency changes and ran no trial application build.
|
when its native semantics and integration pass acceptance, independently of the
|
||||||
|
later PromptKit upgrade.
|
||||||
|
|
||||||
## Required Repository Work And Acceptance
|
## Required Repository Work And Acceptance
|
||||||
|
|
||||||
- Migrate application-side dependency imports, APIs, diagnostics, source
|
- Migrate application-side dependency imports, APIs, diagnostics, source
|
||||||
declarations, inspection, and discovery; resolve the PromptKit/YAML boundary
|
declarations, inspection, and discovery. Verify coexistence of new-path
|
||||||
through the approved dependency path. Native builds must pass at completion.
|
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,
|
- Update real-file loading, imports, overlays, inheritance, CLI assignment,
|
||||||
path-origin, failure, and ownership tests under `internal/core/config` and
|
path-origin, failure, and ownership tests under `internal/core/config` and
|
||||||
`internal/cli`. Add representative collection composition and step-reference
|
`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;
|
and affected dependency integration references. Preserve accepted ADR history;
|
||||||
ADR-0020 already supplies the durable ownership rationale.
|
ADR-0020 already supplies the durable ownership rationale.
|
||||||
- Update `docs/oss/attribution.md` from actual selected module revisions and
|
- 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.
|
and newly selected transitive dependencies. Preserve the application grant.
|
||||||
Upstream ReleaseKit is maintainer tooling; adopting it as Notarius release
|
Upstream ReleaseKit is maintainer tooling; adopting it as Notarius release
|
||||||
machinery or adding its gates is outside this feature.
|
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
|
directives at runtime. The old ConfigKit 0.5 roadmap is replaced by this feature
|
||||||
scope; unrelated completed plans and review findings remain separate records.
|
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**
|
The dependency approach, Unix-system discovery preset, and application step
|
||||||
for the old ConfigKit module used by PromptKit, adapting it to stable go-yaml.
|
identity registration are approved decisions. No significant open decisions
|
||||||
If upstream supports that patch, the two module identities can coexist briefly
|
remain for this feature roadmap.
|
||||||
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.
|
|
||||||
|
|||||||
Reference in New Issue
Block a user