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
|
||||
|
||||
Adopt ConfigKit v0.5.0 and make its sibling inheritance useful and supported in
|
||||
Notarius configuration, particularly for deriving development or testing
|
||||
pipelines from a complete D&D pipeline without duplicating the pipeline body.
|
||||
Adopt `go.maximumdirect.net/configkit` v1.2.1 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.
|
||||
|
||||
ConfigKit owns source composition and inheritance. Notarius continues to own
|
||||
typed configuration, domain defaults and validation, pipeline resolution, and
|
||||
execution. This work does not introduce a second configuration-merging engine.
|
||||
[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
|
||||
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
|
||||
validation sequence. Release preparation and publication remain separate.
|
||||
## Reviewed Baseline And Sources
|
||||
|
||||
## 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
|
||||
`Load` API in `internal/core/config/load.go`. Configuration version 5 supports
|
||||
imports, selected configuration overlays, explicit command overrides, recorded
|
||||
normalization, and redacted effective/explain output. Runtime configuration is
|
||||
detached from the ConfigKit inspection snapshot.
|
||||
- ConfigKit v0.5.0 under `gitea.maximumdirect.net/eric/ConfigKit`;
|
||||
- PromptKit v0.12.0, which consumes that same old ConfigKit package;
|
||||
- Go 1.25.5 and go-yaml v4.0.0-rc.6;
|
||||
- Notarius configuration version 5, imports, overlays, sibling inheritance,
|
||||
declaration-relative application paths, and effective/explanation CLI reports.
|
||||
|
||||
Named pipelines and artifact lanes are mappings; pipeline `steps` and validator
|
||||
chains are sequences. The complete example imports
|
||||
`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.
|
||||
The released v1.2.1 tag in `../ConfigKit` identifies source commit
|
||||
`51ef3144158db1a09fabdbd1c7ae59908c84923b`. Review references:
|
||||
|
||||
Target ConfigKit v0.5.0 at full source commit
|
||||
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. Consult the pinned
|
||||
[release guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md)
|
||||
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,
|
||||
mapping sources, and passive resource contexts. Its Go requirement and YAML
|
||||
dependency are unchanged. The upgrade has not yet been trialed against
|
||||
Notarius's test suite at this review baseline.
|
||||
- [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/)
|
||||
|
||||
All intervening release notes were read in the local checkout. The important
|
||||
changes are:
|
||||
|
||||
| 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
|
||||
|
||||
### Native Sibling Inheritance
|
||||
### Native Loading And Ownership
|
||||
|
||||
Operators can define a named pipeline with `extends: parent-pipeline` and
|
||||
override only the settings that differ. The parent remains an ordinary named,
|
||||
valid pipeline; no abstract-template flag, template registry, or special
|
||||
validation exemption is introduced. Derived pipelines use the existing run,
|
||||
listing, validation, effective-configuration, and explanation commands.
|
||||
Use the new public package and the ordinary `Load` workflow for the application
|
||||
configuration. Defaults, `Resolve`, `Validate`, `VersionRule`, and sensitivity
|
||||
classification remain supported application extension points. The handoff
|
||||
contains fully composed, decoded, normalized, and validated application values.
|
||||
Runtime conversion and catalog-dependent pipeline preparation retain their
|
||||
application ownership.
|
||||
|
||||
Use ConfigKit's native semantics without restricting inheritance to pipelines
|
||||
or implementing a Notarius-specific subset:
|
||||
ConfigKit owns import acquisition, ordering, inheritance, collection operations,
|
||||
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.
|
||||
It is not a path, cross-scope lookup, or multiple-parent expression.
|
||||
- Source precedence is assembled before inheritance, and inheritance runs
|
||||
before typed decoding and application resolution. Inherited input is explicit
|
||||
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.
|
||||
Keep configuration `version: 5`: its typed application shape is unchanged.
|
||||
Explain the deliberate ConfigKit syntax/semantic migration in operator guidance
|
||||
and the eventual minor-release note. Existing files require migration rather
|
||||
than a compatibility pre-parser or legacy control aliases.
|
||||
|
||||
Names are matched by ConfigKit before Notarius's existing identifier trimming.
|
||||
Document exact-key lookup rather than introducing pre-inheritance name rewriting.
|
||||
### Source Controls, Imports, And Composition
|
||||
|
||||
The principal documented workflow is whole-pipeline reuse. Inheritance does not
|
||||
append steps, merge sequences by `id`, or allow a child to override one list
|
||||
element without supplying a replacement list. The same applies to validator
|
||||
chains. Do not disguise this boundary through custom list-merging code.
|
||||
Use source-root `config` controls in Notarius configuration inputs. Update real
|
||||
control blocks and stored declaration pointers, including imported files,
|
||||
overlays, mapping fixtures, and examples. Nested application data named `config`
|
||||
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
|
||||
original declaring file, not the child's file or the invocation directory.
|
||||
Imported parents, overlays, and nested inheritance must retain that behavior.
|
||||
Direct child declarations use their own source context. Built-in relative
|
||||
destinations and CLI-supplied paths keep their existing bases.
|
||||
Enable ConfigKit imports and accept its native path/list, directory, glob,
|
||||
destination, placement, exclusion, recursion, hidden-file, symlink, and
|
||||
requiredness rules. Leave `ImportDefaults` unspecified unless an application
|
||||
choice is explicitly approved. In particular, do not restore former implicit
|
||||
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
|
||||
against the new origin metadata. Make narrowly required corrections if needed;
|
||||
do not assume that successful typed decoding proves correct path resolution.
|
||||
Effective output must agree with the runtime paths, and explanations must retain
|
||||
the upstream derivation evidence through recorded Notarius normalization.
|
||||
Expose native identified sequence operations and inheritance through the source
|
||||
format. Without identity, lists retain native peer-conflict/whole-replacement
|
||||
behavior. Identified lists support strict peer composition and native
|
||||
replace/append/upsert across tiers. Upsert replaces a complete matching record,
|
||||
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
|
||||
unresolved directives reach runtime pipeline/module types. ConfigKit expands
|
||||
relationships once during loading. Notarius's existing binding-profile,
|
||||
validation-policy, and module-default resolution still operate on the resulting
|
||||
configuration; they are not replaced with generic sibling inheritance.
|
||||
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.
|
||||
|
||||
Configuration overlays, pipeline inheritance, and PromptKit `base_profile`
|
||||
inheritance remain distinct mechanisms. The latter still belongs to PromptKit.
|
||||
CLI overrides apply after inheritance and typed decoding, before application
|
||||
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;
|
||||
the new capability belongs to configuration composition. No new CLI flag or
|
||||
inheritance opt-in setting is needed or available upstream.
|
||||
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.
|
||||
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
|
||||
in every input mapping, including dynamic module-option maps and named maps.
|
||||
It is consumed before typed decoding, so it can no longer be ordinary data or
|
||||
an ordinary entry name there. Audit maintained configuration/fixtures for such
|
||||
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.
|
||||
Report the actual selected main file using retained source information; update
|
||||
load/error plumbing rather than making a second discovery pass. Construction of
|
||||
search descriptions remains side-effect-free, and acquisition errors follow
|
||||
ConfigKit's native selected-file behavior.
|
||||
|
||||
Configurations without that collision should retain their existing meaning.
|
||||
Preserve discovery, import rules, overlay selection, explicit CLI override
|
||||
precedence, strict decoding, redaction, defaults, and validation. Existing
|
||||
configuration-stage inheritance does not alter the fixed execution pipeline,
|
||||
artifact contracts, warning policy, or checkpoint identity design.
|
||||
Retain the deliberately selected application path policy: file-authored values
|
||||
use their declaring file, CLI paths use the invocation directory, and relative
|
||||
application defaults use the canonical main file. Use `EntryInfo`, source records,
|
||||
and public resource contexts where appropriate. Native destinations and source
|
||||
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
|
||||
the feature and the newly reserved input key. Release preparation/publication
|
||||
is separate from this work; no exact release number is selected here.
|
||||
Ordinary `Load` is sufficient for current application composition. `LoadLayered`,
|
||||
`MainRelative`, and overlay fallbacks are available when actual bundled/companion
|
||||
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
|
||||
dependencies unchanged unless dependency resolution demonstrably requires it.
|
||||
Continue using ordinary `configkit.Load`, the existing typed defaults factory,
|
||||
and source-aware resolution/validation callbacks.
|
||||
Use v1.1 field-level recording for list leaf normalization. Remove the old
|
||||
blanket whole-sequence coverage wrapper where its only purpose was satisfying
|
||||
the old audit. Record actual structural mutations at their proper scope. Resolve
|
||||
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
|
||||
boundaries. Add only integration adjustments demonstrated necessary by the
|
||||
upstream change. There should be no `Extends` field added to Notarius runtime
|
||||
types and no homegrown inheritance algorithm.
|
||||
Effective/explanation commands delegate to ConfigKit's captured inspection,
|
||||
retaining redaction, presence, source history, and detached ownership. Source
|
||||
lookup APIs support useful diagnostics, including empty import selections when
|
||||
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
|
||||
links to the target commit after inspecting its actual notices. Preserve the
|
||||
selected project grant and reuse unchanged local license texts.
|
||||
## Dependency And Toolchain Boundary
|
||||
|
||||
### 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
|
||||
`dnd-session-development` sibling deriving from `dnd-session`, demonstrating a
|
||||
pipeline-level setting override such as a smaller structural-repair budget.
|
||||
Use already supported values and existing profile sources so the example
|
||||
validates without an invented model/profile dependency. Explain that
|
||||
`llm_profile` is another useful override when the operator supplies that profile.
|
||||
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.
|
||||
|
||||
Retain the runnable parent, minimal example, and existing operational overlay.
|
||||
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.
|
||||
There is also a concrete shared-dependency incompatibility:
|
||||
|
||||
### 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,
|
||||
replacement/null semantics, path bases, reserved-key migration, and limits
|
||||
on step/validator-list composition. Link to the maintained example and pinned
|
||||
upstream rules rather than duplicating the entire upstream manual.
|
||||
- `docs/internal/configuration.md`: describe expansion before typed decoding,
|
||||
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.
|
||||
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.
|
||||
|
||||
The existing ConfigKit architecture decision remains applicable. No new ADR is
|
||||
required solely for consuming the library's composition feature; do not rewrite
|
||||
an accepted ADR or turn new private implementation details into invariants.
|
||||
## Required Repository Work And Acceptance
|
||||
|
||||
## 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.
|
||||
- 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.
|
||||
## Open Decisions
|
||||
|
||||
Configuration and CLI boundary coverage should protect document/path/operational,
|
||||
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.
|
||||
### 1. Resolve The Stable-YAML Conflict With Old PromptKit
|
||||
|
||||
## 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
|
||||
imports, overlays, and typed defaults remain the loading model. Bundled
|
||||
pipeline presets or site-wide default layers need a separate operator-facing
|
||||
design if selected later.
|
||||
- Do not move Go defaults into embedded YAML or mapping sources solely because
|
||||
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.
|
||||
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.
|
||||
|
||||
There are no significant open design decisions at this baseline. Implementation
|
||||
should verify the new metadata behavior and correct concrete integration gaps
|
||||
without broadening the agreed feature scope.
|
||||
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