Plan adoption of current ConfigKit configuration semantics
This commit is contained in:
@@ -1,229 +1,296 @@
|
|||||||
# ConfigKit 0.5 And Configuration Inheritance
|
# Adopt Current ConfigKit Configuration Semantics
|
||||||
|
|
||||||
## Purpose
|
## Purpose
|
||||||
|
|
||||||
Adopt ConfigKit v0.5.0 and make its sibling inheritance useful and supported in
|
Adopt `go.maximumdirect.net/configkit` v1.2.1 and its native consumer workflow.
|
||||||
Notarius configuration, particularly for deriving development or testing
|
The objective is consistent configuration semantics across ConfigKit-consuming
|
||||||
pipelines from a complete D&D pipeline without duplicating the pipeline body.
|
applications. Existing Notarius composition behavior is a migration baseline,
|
||||||
|
not a compatibility requirement to reproduce through adapters.
|
||||||
|
|
||||||
ConfigKit owns source composition and inheritance. Notarius continues to own
|
[ADR-0020](../adr/0020-delegate-configuration-mechanics-to-configkit.md) owns the
|
||||||
typed configuration, domain defaults and validation, pipeline resolution, and
|
boundary: ConfigKit delivers the final resolved application document; Notarius
|
||||||
execution. This work does not introduce a second configuration-merging engine.
|
supplies application schema, defaults, normalization, validation, and subsequent
|
||||||
|
pipeline resolution. This roadmap defines the target and required work. A later
|
||||||
|
implementation plan will own sequencing. Release publication is separate work.
|
||||||
|
|
||||||
The [implementation plan](implementation.md) owns the ordered work and
|
## Reviewed Baseline And Sources
|
||||||
validation sequence. Release preparation and publication remain separate.
|
|
||||||
|
|
||||||
## Reviewed Baseline
|
Reviewed on 2026-11-17 against Notarius `b9899ea`:
|
||||||
|
|
||||||
Reviewed on 2026-10-03. Notarius pins ConfigKit v0.4.2 and uses its ordinary
|
- ConfigKit v0.5.0 under `gitea.maximumdirect.net/eric/ConfigKit`;
|
||||||
`Load` API in `internal/core/config/load.go`. Configuration version 5 supports
|
- PromptKit v0.12.0, which consumes that same old ConfigKit package;
|
||||||
imports, selected configuration overlays, explicit command overrides, recorded
|
- Go 1.25.5 and go-yaml v4.0.0-rc.6;
|
||||||
normalization, and redacted effective/explain output. Runtime configuration is
|
- Notarius configuration version 5, imports, overlays, sibling inheritance,
|
||||||
detached from the ConfigKit inspection snapshot.
|
declaration-relative application paths, and effective/explanation CLI reports.
|
||||||
|
|
||||||
Named pipelines and artifact lanes are mappings; pipeline `steps` and validator
|
The released v1.2.1 tag in `../ConfigKit` identifies source commit
|
||||||
chains are sequences. The complete example imports
|
`51ef3144158db1a09fabdbd1c7ae59908c84923b`. Review references:
|
||||||
`examples/pipelines/dnd-session.yml`, while the existing development overlay
|
|
||||||
changes operational settings. Relative configured paths are resolved from the
|
|
||||||
file supplying their surviving declaration. The current path resolver uses
|
|
||||||
ConfigKit origin/source metadata and host filesystem paths.
|
|
||||||
|
|
||||||
Target ConfigKit v0.5.0 at full source commit
|
- [Consumer adoption guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/consumers/README.md)
|
||||||
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Consult the pinned
|
- [Configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/config.md)
|
||||||
[release guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md)
|
- [Release notes](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.2.1/docs/releases/)
|
||||||
and [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md).
|
|
||||||
The release adds inheritance, layered loading, filesystem-backed sources,
|
All intervening release notes were read in the local checkout. The important
|
||||||
mapping sources, and passive resource contexts. Its Go requirement and YAML
|
changes are:
|
||||||
dependency are unchanged. The upgrade has not yet been trialed against
|
|
||||||
Notarius's test suite at this review baseline.
|
| Releases | Relevance to Notarius |
|
||||||
|
| --- | --- |
|
||||||
|
| v0.6.0 | Loading/inspection optimizations; Go minimum becomes 1.26.0. No promised application-wide speedup. |
|
||||||
|
| v0.7.0–v0.7.1 | Frozen effective-configuration diffs; maintainer tooling update. |
|
||||||
|
| v0.8.0 | Input destinations, sequence-item placement, source-version checks, and identified sequences. |
|
||||||
|
| v0.9.0 | Expanded imports; imports optional by default; author-declared replace/append/upsert; identified-record inheritance; CLI assignments move after inheritance and decoding. |
|
||||||
|
| v0.10.0–v0.10.2 | Explicit configuration discovery; broader absent-main lifecycle; loading, ownership, acquisition, and history fixes. |
|
||||||
|
| 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. |
|
||||||
|
|
||||||
|
### Current Integration Areas
|
||||||
|
|
||||||
|
`internal/core/config/load.go` supplies ConfigKit's definition and callbacks.
|
||||||
|
`loaded_config.go` privately retains its inspection result and publishes a
|
||||||
|
detached runtime value. `document_paths.go`, `pipeline_document.go`, and
|
||||||
|
`document_normalizer.go` implement application normalization and source tracking.
|
||||||
|
The normalizer currently records whole-list coverage even for leaf edits.
|
||||||
|
|
||||||
|
`internal/cli/configkit_load.go` and `run.go` own selection and diagnostics.
|
||||||
|
`discoverConfigPath` manually probes files before `config.Load` calls ConfigKit.
|
||||||
|
The complete example imports its pipeline through root `configkit`. Current
|
||||||
|
documentation describes unconditionally replacing whole step lists.
|
||||||
|
|
||||||
|
ConfigKit types also appear inside the PromptKit adapter's native source and
|
||||||
|
inspection APIs. That is a distinct integration boundary with the dependency
|
||||||
|
constraint below; a repository-wide import replacement would be incorrect.
|
||||||
|
|
||||||
## Target End State
|
## Target End State
|
||||||
|
|
||||||
### Native Sibling Inheritance
|
### Native Loading And Ownership
|
||||||
|
|
||||||
Operators can define a named pipeline with `extends: parent-pipeline` and
|
Use the new public package and the ordinary `Load` workflow for the application
|
||||||
override only the settings that differ. The parent remains an ordinary named,
|
configuration. Defaults, `Resolve`, `Validate`, `VersionRule`, and sensitivity
|
||||||
valid pipeline; no abstract-template flag, template registry, or special
|
classification remain supported application extension points. The handoff
|
||||||
validation exemption is introduced. Derived pipelines use the existing run,
|
contains fully composed, decoded, normalized, and validated application values.
|
||||||
listing, validation, effective-configuration, and explanation commands.
|
Runtime conversion and catalog-dependent pipeline preparation retain their
|
||||||
|
application ownership.
|
||||||
|
|
||||||
Use ConfigKit's native semantics without restricting inheritance to pipelines
|
ConfigKit owns import acquisition, ordering, inheritance, collection operations,
|
||||||
or implementing a Notarius-specific subset:
|
CLI assignment semantics, limits, source evidence, and frozen inspection. Pass
|
||||||
|
its results and structured failures through the established adapter boundary.
|
||||||
|
Application validation checks the resulting domain configuration; it does not
|
||||||
|
audit superseded contributions or replay structural directives.
|
||||||
|
|
||||||
- `extends` selects one exact key among the mapping's immediate siblings.
|
Keep configuration `version: 5`: its typed application shape is unchanged.
|
||||||
It is not a path, cross-scope lookup, or multiple-parent expression.
|
Explain the deliberate ConfigKit syntax/semantic migration in operator guidance
|
||||||
- Source precedence is assembled before inheritance, and inheritance runs
|
and the eventual minor-release note. Existing files require migration rather
|
||||||
before typed decoding and application resolution. Inherited input is explicit
|
than a compatibility pre-parser or legacy control aliases.
|
||||||
for presence-sensitive defaults, including zero, false, empty, and null.
|
|
||||||
- Child mappings recursively overlay parent mappings; sequences, scalars,
|
|
||||||
and null replace inherited values. Existing typed/domain validation still
|
|
||||||
determines whether the resulting value is valid.
|
|
||||||
- Omitting `extends` retains a lower-priority relationship; `extends: null`
|
|
||||||
cancels the relationship, not arbitrary inherited fields independently.
|
|
||||||
- Root and sequence-element mappings have no sibling namespace for their own
|
|
||||||
string relationship. Nested mappings may have one. In particular, individual
|
|
||||||
entries of the `steps` sequence cannot extend other step entries.
|
|
||||||
- ConfigKit rejects missing/non-mapping parents, invalid directive types, and
|
|
||||||
cycles, and resolves effective relationships even in unselected entries.
|
|
||||||
- Parent definitions receive normal typed decoding and Notarius validation.
|
|
||||||
Inheritance is not a way to hide invalid partial pipeline definitions.
|
|
||||||
- Inherited nested relationships resolve at their destination according to
|
|
||||||
ConfigKit's rules; do not pre-expand or reinterpret them in Notarius.
|
|
||||||
|
|
||||||
Names are matched by ConfigKit before Notarius's existing identifier trimming.
|
### Source Controls, Imports, And Composition
|
||||||
Document exact-key lookup rather than introducing pre-inheritance name rewriting.
|
|
||||||
|
|
||||||
The principal documented workflow is whole-pipeline reuse. Inheritance does not
|
Use source-root `config` controls in Notarius configuration inputs. Update real
|
||||||
append steps, merge sequences by `id`, or allow a child to override one list
|
control blocks and stored declaration pointers, including imported files,
|
||||||
element without supplying a replacement list. The same applies to validator
|
overlays, mapping fixtures, and examples. Nested application data named `config`
|
||||||
chains. Do not disguise this boundary through custom list-merging code.
|
retains native treatment. Former `configkit`/`_configkit` keys are ordinary data;
|
||||||
|
ordinary typed validation governs them. No custom legacy-control scanner is
|
||||||
|
needed.
|
||||||
|
|
||||||
### Paths, Provenance, And Runtime Boundaries
|
This control migration applies to Notarius's application loader. PromptKit
|
||||||
|
operator files and adapter fixtures follow the version of PromptKit that reads
|
||||||
|
them; retain their old control spelling while that separate engine remains old.
|
||||||
|
|
||||||
An inherited relative reference or resource path remains relative to its
|
Enable ConfigKit imports and accept its native path/list, directory, glob,
|
||||||
original declaring file, not the child's file or the invocation directory.
|
destination, placement, exclusion, recursion, hidden-file, symlink, and
|
||||||
Imported parents, overlays, and nested inheritance must retain that behavior.
|
requiredness rules. Leave `ImportDefaults` unspecified unless an application
|
||||||
Direct child declarations use their own source context. Built-in relative
|
choice is explicitly approved. In particular, do not restore former implicit
|
||||||
destinations and CLI-supplied paths keep their existing bases.
|
requiredness or impose a YAML-only directory filter globally. Required deployed
|
||||||
|
fragments, such as the maintained complete pipeline import, should say
|
||||||
|
`required: true` in their declaration so an incomplete installation fails there.
|
||||||
|
Optional imports remain genuinely optional.
|
||||||
|
Use the native main-only source-version default; fragments do not acquire a new
|
||||||
|
mandatory version declaration as a side effect of this upgrade.
|
||||||
|
|
||||||
Review `documentPathBase` and related original-path/normalization handling
|
Expose native identified sequence operations and inheritance through the source
|
||||||
against the new origin metadata. Make narrowly required corrections if needed;
|
format. Without identity, lists retain native peer-conflict/whole-replacement
|
||||||
do not assume that successful typed decoding proves correct path resolution.
|
behavior. Identified lists support strict peer composition and native
|
||||||
Effective output must agree with the runtime paths, and explanations must retain
|
replace/append/upsert across tiers. Upsert replaces a complete matching record,
|
||||||
the upstream derivation evidence through recorded Notarius normalization.
|
retaining its position; it is not a recursive merge of that record. Clearing an
|
||||||
|
append/upsert collection requires explicit replacement with an empty list.
|
||||||
|
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.
|
||||||
|
|
||||||
Keep the ConfigKit boundary private: no upstream inheritance objects or
|
Step identity registration is an explicit decision below. Other identified
|
||||||
unresolved directives reach runtime pipeline/module types. ConfigKit expands
|
collections remain available through author declarations; no broad automatic
|
||||||
relationships once during loading. Notarius's existing binding-profile,
|
`id` inference or universal registration is required. Demonstrate a composed
|
||||||
validation-policy, and module-default resolution still operate on the resulting
|
step list and a derived pipeline using native controls in maintained examples
|
||||||
configuration; they are not replaced with generic sibling inheritance.
|
or small canonical snippets, with behavioral coverage.
|
||||||
|
|
||||||
Configuration overlays, pipeline inheritance, and PromptKit `base_profile`
|
CLI overrides apply after inheritance and typed decoding, before application
|
||||||
inheritance remain distinct mechanisms. The latter still belongs to PromptKit.
|
resolution. Preserve explicit zero/false/empty values. Structural errors cannot
|
||||||
|
be repaired by CLI assignments; document this instead of rebuilding the former
|
||||||
|
override order. Notarius's binding-profile and validation-policy rules remain
|
||||||
|
domain semantics applied to the final configuration.
|
||||||
|
|
||||||
### Compatibility And Upgrade Policy
|
### Native Source Selection And Resources
|
||||||
|
|
||||||
Keep Notarius configuration `version: 5`. The typed runtime shape is unchanged;
|
Replace manual acquisition/probing with ConfigKit source descriptions. Explicit
|
||||||
the new capability belongs to configuration composition. No new CLI flag or
|
`--config` and, when no CLI selection exists, `NOTARIUS_CONFIG` select exclusive
|
||||||
inheritance opt-in setting is needed or available upstream.
|
`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.
|
||||||
|
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.
|
||||||
|
|
||||||
The significant compatibility change is that `extends` becomes a reserved key
|
Report the actual selected main file using retained source information; update
|
||||||
in every input mapping, including dynamic module-option maps and named maps.
|
load/error plumbing rather than making a second discovery pass. Construction of
|
||||||
It is consumed before typed decoding, so it can no longer be ordinary data or
|
search descriptions remains side-effect-free, and acquisition errors follow
|
||||||
an ordinary entry name there. Audit maintained configuration/fixtures for such
|
ConfigKit's native selected-file behavior.
|
||||||
usage and document that affected operator configurations must rename the key
|
|
||||||
or identifier and any associated consumer field. Do not silently strip, alias,
|
|
||||||
or bypass the directive to preserve an incompatible interpretation.
|
|
||||||
|
|
||||||
Configurations without that collision should retain their existing meaning.
|
Retain the deliberately selected application path policy: file-authored values
|
||||||
Preserve discovery, import rules, overlay selection, explicit CLI override
|
use their declaring file, CLI paths use the invocation directory, and relative
|
||||||
precedence, strict decoding, redaction, defaults, and validation. Existing
|
application defaults use the canonical main file. Use `EntryInfo`, source records,
|
||||||
configuration-stage inheritance does not alter the fixed execution pipeline,
|
and public resource contexts where appropriate. Native destinations and source
|
||||||
artifact contracts, warning policy, or checkpoint identity design.
|
coordinates are distinct: a mounted or inherited value keeps its source base.
|
||||||
|
No new target-existence, confinement, symlink, or permission policy is added to
|
||||||
|
application resource paths. ConfigKit's own input-root rules remain upstream.
|
||||||
|
|
||||||
The eventual Notarius release should be a new minor version, explaining both
|
Ordinary `Load` is sufficient for current application composition. `LoadLayered`,
|
||||||
the feature and the newly reserved input key. Release preparation/publication
|
`MainRelative`, and overlay fallbacks are available when actual bundled/companion
|
||||||
is separate from this work; no exact release number is selected here.
|
inputs need them; the upgrade does not require an artificial extra input layer.
|
||||||
|
|
||||||
## Required Work
|
### Lean Application Resolution And Inspection
|
||||||
|
|
||||||
### Dependency And Configuration Integration
|
Replace `InputInfo` with `EntryInfo`, `Definition.Secret` with `Sensitive`,
|
||||||
|
generic `Record` calls with the corresponding named recording methods, and
|
||||||
|
`LayerBase`/`"base"` with `LayerMain`/`"main"` where used. Audit all affected
|
||||||
|
symbols and diagnostic strings against the v1 migration table. Use assignment-
|
||||||
|
and-record helpers when appropriate; named recording methods alone do not mutate
|
||||||
|
the application value.
|
||||||
|
|
||||||
Upgrade `go.mod` and `go.sum` to the exact target. Keep PromptKit and unrelated
|
Use v1.1 field-level recording for list leaf normalization. Remove the old
|
||||||
dependencies unchanged unless dependency resolution demonstrably requires it.
|
blanket whole-sequence coverage wrapper where its only purpose was satisfying
|
||||||
Continue using ordinary `configkit.Load`, the existing typed defaults factory,
|
the old audit. Record actual structural mutations at their proper scope. Resolve
|
||||||
and source-aware resolution/validation callbacks.
|
source-relative values before moving records; fixed entry positions, final
|
||||||
|
positions, historical evidence, and effective origins serve different purposes.
|
||||||
|
Keep map-key relocation bookkeeping only where actual application identifier
|
||||||
|
normalization still needs it. Do not add an independent history-replay engine.
|
||||||
|
|
||||||
Inspect the load, operational-document, path, conversion, inspection, and CLI
|
Effective/explanation commands delegate to ConfigKit's captured inspection,
|
||||||
boundaries. Add only integration adjustments demonstrated necessary by the
|
retaining redaction, presence, source history, and detached ownership. Source
|
||||||
upstream change. There should be no `Extends` field added to Notarius runtime
|
lookup APIs support useful diagnostics, including empty import selections when
|
||||||
types and no homegrown inheritance algorithm.
|
needed, without turning ordinary optional absence into warnings. ConfigKit's
|
||||||
|
`Diff` is available for a later operator-facing comparison command; a new CLI
|
||||||
|
diff or secrets-management workflow is not required for this adoption.
|
||||||
|
|
||||||
Update ConfigKit's factual attribution version and COPYRIGHT/LICENSE/source
|
## Dependency And Toolchain Boundary
|
||||||
links to the target commit after inspecting its actual notices. Preserve the
|
|
||||||
selected project grant and reuse unchanged local license texts.
|
|
||||||
|
|
||||||
### Maintained Example
|
The target is ConfigKit v1.2.1, stable go-yaml v4.0.0, 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.
|
||||||
|
|
||||||
Extend the complete example's imported pipeline definitions with a small
|
PromptKit v0.12.0 exposes **old-path ConfigKit types** through `Config.Sources`,
|
||||||
`dnd-session-development` sibling deriving from `dnd-session`, demonstrating a
|
its source helpers, and inspection. Keep these contained in the LLM adapter
|
||||||
pipeline-level setting override such as a smaller structural-repair budget.
|
until its separate upgrade; ordinary Notarius configuration uses new-path types.
|
||||||
Use already supported values and existing profile sources so the example
|
Prefer neutral scalar/domain handoffs over translating dependency-owned graphs.
|
||||||
validates without an invented model/profile dependency. Explain that
|
|
||||||
`llm_profile` is another useful override when the operator supplies that profile.
|
|
||||||
|
|
||||||
Retain the runnable parent, minimal example, and existing operational overlay.
|
There is also a concrete shared-dependency incompatibility:
|
||||||
Do not duplicate the complete steps list or add a third standalone configuration
|
|
||||||
merely to demonstrate inheritance. Update example-loading/listing expectations
|
|
||||||
for the additional pipeline, checking inherited behavior rather than snapshots
|
|
||||||
of incidental formatting or total line counts.
|
|
||||||
|
|
||||||
### Canonical Documentation
|
- 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`.
|
||||||
|
- Stable go-yaml contains `plugin/loaderlimits` and no `plugin/limit`.
|
||||||
|
- Go selects one version of this shared YAML module, despite ConfigKit itself
|
||||||
|
having two distinct module paths.
|
||||||
|
|
||||||
- `docs/config.md`: own syntax, composition order, exact sibling lookup,
|
Therefore keeping PromptKit v0.12.0 and its unpatched ConfigKit v0.5.0 does not
|
||||||
replacement/null semantics, path bases, reserved-key migration, and limits
|
produce a buildable v1.2.1 target. Resolve the open dependency decision before
|
||||||
on step/validator-list composition. Link to the maintained example and pinned
|
finalizing the implementation plan. Neither a local fork/replace nor silently
|
||||||
upstream rules rather than duplicating the entire upstream manual.
|
ending at ConfigKit v1.2.0 is the target architecture. This planning pass made
|
||||||
- `docs/internal/configuration.md`: describe expansion before typed decoding,
|
no dependency changes and ran no trial application build.
|
||||||
presence and source-aware normalization, and the unchanged runtime boundary.
|
|
||||||
- `docs/integrations/pkg-configkit.md`: update the supported version, public
|
|
||||||
contract links, and integration scope.
|
|
||||||
- `docs/oss/attribution.md`: update the dependency's verified source/notice links.
|
|
||||||
- `docs/cli.md` and consumer guides: update only where navigation or examples
|
|
||||||
benefit from showing selection of the derived pipeline. Do not invent new
|
|
||||||
invocation syntax or duplicate the configuration reference.
|
|
||||||
|
|
||||||
The existing ConfigKit architecture decision remains applicable. No new ADR is
|
## Required Repository Work And Acceptance
|
||||||
required solely for consuming the library's composition feature; do not rewrite
|
|
||||||
an accepted ADR or turn new private implementation details into invariants.
|
|
||||||
|
|
||||||
## Verification 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.
|
||||||
|
- 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
|
||||||
|
normalization cases, including imports in distinct directories and leaf
|
||||||
|
histories after list composition. Test native semantics, not the old behavior.
|
||||||
|
- Retain two top-level configuration examples. Migrate the complete example's
|
||||||
|
required import and demonstrate useful native composition without adding a
|
||||||
|
second application merger or an unnecessary example framework.
|
||||||
|
- Revise `docs/config.md`, `docs/cli.md`, `docs/internal/configuration.md`, and
|
||||||
|
affected operations/subprocess guidance for syntax, search, imports, collections,
|
||||||
|
CLI ordering, origins, and inspection. Update README/toolchain/release guidance
|
||||||
|
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,
|
||||||
|
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.
|
||||||
|
- Verify focused configuration/CLI/LLM tests, full offline tests, vet, a native
|
||||||
|
build, maintained examples and report commands without provider calls, tidy
|
||||||
|
consistency, selected module identities, and affected links. No production
|
||||||
|
inference, fixed performance improvement, new release gate, or broader
|
||||||
|
filesystem/security guarantee is part of acceptance.
|
||||||
|
|
||||||
Use focused Notarius boundary tests, not a duplicate of ConfigKit's full suite:
|
Completion means current native configuration semantics are usable and documented
|
||||||
|
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.
|
||||||
|
|
||||||
- Existing maintained configurations continue loading and resolving.
|
## Open Decisions
|
||||||
- A derived pipeline retains its own identifier and inherits the complete
|
|
||||||
parent pipeline while applying its explicit overrides.
|
|
||||||
- Imports and selected overlays participate in composition before inheritance;
|
|
||||||
explicit CLI overrides keep their documented precedence.
|
|
||||||
- Representative zero/false/null inputs exercise existing presence-sensitive
|
|
||||||
defaulting or validation correctly; null is not universally valid merely
|
|
||||||
because inheritance can represent it.
|
|
||||||
- Replacing a steps or validator sequence does not concatenate or merge it.
|
|
||||||
- References inherited from a parent in another file retain their declaring
|
|
||||||
directory, while child-supplied replacements use the child's directory.
|
|
||||||
- Effective and explanation output remain redacted and expose useful source
|
|
||||||
and inheritance information after application normalization.
|
|
||||||
- Representative invalid inheritance produces ConfigKit load diagnostics through
|
|
||||||
the normal Notarius CLI error path, without a parallel validation engine.
|
|
||||||
- Maintained examples and their imported fragments validate offline without
|
|
||||||
credentials or provider calls.
|
|
||||||
|
|
||||||
Configuration and CLI boundary coverage should protect document/path/operational,
|
### 1. Resolve The Stable-YAML Conflict With Old PromptKit
|
||||||
effective/explanation, and maintained-example behavior. Framework-resolution
|
|
||||||
coverage is appropriate where a distinct handoff risk requires it. Acceptance
|
|
||||||
includes the offline default suite, vet, and build with `GOWORK=off`, dependency
|
|
||||||
tidiness, and documentation diff/link checks appropriate to the changes. The
|
|
||||||
implementation plan owns their sequencing; these checks are not additional
|
|
||||||
permanent release gates.
|
|
||||||
|
|
||||||
## Deferred Capabilities And Non-Goals
|
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.
|
||||||
|
|
||||||
- Do not adopt `LoadLayered` or add a new underlay precedence tier now. Existing
|
Alternative: coordinate the PromptKit adapter's module/API migration with this
|
||||||
imports, overlays, and typed defaults remain the loading model. Bundled
|
cutover and select a current PromptKit release that consumes ConfigKit v1.2.1.
|
||||||
pipeline presets or site-wide default layers need a separate operator-facing
|
This is the cleaner long-term dependency graph and avoids maintaining a legacy
|
||||||
design if selected later.
|
patch, but couples the two implementation work sets. If selected, prepare the
|
||||||
- Do not move Go defaults into embedded YAML or mapping sources solely because
|
PromptKit roadmap before claiming a standalone ConfigKit sprint can finish.
|
||||||
v0.5.0 provides those APIs.
|
|
||||||
- Do not generalize references to arbitrary `fs.FS` resources in this work.
|
|
||||||
`SourceContext` may be used if it materially helps the required path behavior,
|
|
||||||
but its filesystem access rules must not silently replace Notarius's existing
|
|
||||||
host-path contract or introduce new path restrictions.
|
|
||||||
- No abstract templates, multiple inheritance, list-element composition,
|
|
||||||
new template schema, new pipeline scheduler, or extra configuration knobs.
|
|
||||||
- No opt-in gate or Notarius-only prohibition on other valid native inheritance
|
|
||||||
locations; use upstream semantics and existing domain validation.
|
|
||||||
|
|
||||||
There are no significant open design decisions at this baseline. Implementation
|
A temporary ConfigKit v1.2.0 checkpoint can assist that coordinated migration
|
||||||
should verify the new metadata behavior and correct concrete integration gaps
|
because it still selects YAML rc.6, but it does not complete this roadmap's
|
||||||
without broadening the agreed feature scope.
|
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