203 lines
10 KiB
Markdown
203 lines
10 KiB
Markdown
# Adopt ConfigKit v0.5.0
|
|
|
|
## Purpose
|
|
|
|
Upgrade Narratio from ConfigKit v0.4.2 to v0.5.0 and integrate its native
|
|
sibling inheritance with Narratio's configuration validation and inspection.
|
|
Keep the upgrade focused on the existing loading model and the adjustments
|
|
needed to consume the new release correctly.
|
|
|
|
This adoption precedes [Audita adoption](audita.md) and the
|
|
[workspace reorganization](workspace.md). This document defines the target
|
|
and required changes; [the implementation plan](implementation.md) defines
|
|
the steps for reaching that target.
|
|
|
|
## Reviewed Upstream Release
|
|
|
|
ConfigKit v0.5.0 identifies commit
|
|
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`. The
|
|
[release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md),
|
|
[configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md),
|
|
and [consumer guide](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/consumers/README.md)
|
|
own the upstream behavior.
|
|
|
|
The release introduces native `extends` relationships between sibling mappings,
|
|
layered loading with ordered underlays, caller-owned filesystem and mapping
|
|
sources, and passive source-resource contexts. Inheritance preserves explicit
|
|
presence, provenance, and secret classification.
|
|
|
|
The existing loading API remains available. ConfigKit's minimum Go line, YAML
|
|
dependency, and LGPL-3.0-or-later license are unchanged. Narratio can retain its
|
|
current Go toolchain and ordinary loading calls.
|
|
|
|
## Current Baseline
|
|
|
|
The [configuration reference](../config.md) owns Narratio's current public
|
|
semantics; [configuration internals](../internal/configuration.md) describe
|
|
loading and inspection.
|
|
|
|
- Pipeline loading uses ConfigKit with explicit additive imports and one
|
|
selected overlay, typed defaults, recorded resolution, and domain validation.
|
|
- Campaign, session, and canonical-party inputs use separate single-source
|
|
loads. Secret-directory bootstrap remains an explicit invocation operation.
|
|
- Fields with root-relative pipeline path semantics retain that base when their
|
|
declarations move into imports. For example, enabled Notarius configuration
|
|
and working-directory paths resolve from the root pipeline directory.
|
|
- Narratio adds a declaration-ownership check: each artifact or artifact-family
|
|
key may be declared by only one base file. Overlay modifications are allowed.
|
|
- Source inspection and artifact catalogs consume retained ConfigKit metadata.
|
|
Effective show, diff, and digest projections describe the resolved domain
|
|
configuration rather than source layout.
|
|
|
|
The review selected v0.5.0 through a temporary module file and ran Narratio's
|
|
existing test suite successfully. An additional probe exposed an integration
|
|
gap: a child artifact inheriting from a parent in another imported file is
|
|
rejected as declared by multiple base files. The same definitions in one file
|
|
load successfully. The check currently counts inherited history contributions
|
|
as if they were direct declarations.
|
|
|
|
## Targeted End State
|
|
|
|
### Native inheritance
|
|
|
|
Use ConfigKit's built-in sibling inheritance wherever its input contract and
|
|
Narratio's domain schema permit it. ConfigKit resolves `extends` after source
|
|
composition and overlay precedence, before typed decoding and application
|
|
resolution. Narratio receives the resulting typed configuration.
|
|
|
|
Inheritance can reduce repetition between artifacts and artifact families,
|
|
including definitions in separate imported files. Distinct child keys retain
|
|
their identities. Each resulting entry undergoes ordinary Narratio validation,
|
|
family expansion, dependency resolution, and execution selection.
|
|
|
|
Parent entries remain ordinary domain entries. They must satisfy applicable
|
|
validation and participate in the effective configuration. This adoption does
|
|
not introduce abstract artifacts or a separate template registry. Operators
|
|
must override inherited fields where needed to keep the resulting configuration
|
|
valid, such as output destinations.
|
|
|
|
Inherited false, zero, empty, and null input retains ConfigKit's explicit
|
|
presence semantics. Narratio's absence-based defaults must not refill such
|
|
values. Normal domain validation still determines whether a resulting value
|
|
is acceptable.
|
|
|
|
### Declaration ownership and provenance
|
|
|
|
Distinguish direct base declarations from inherited contributions. A child
|
|
declared in one file may inherit from a separately declared parent in another
|
|
file without becoming a duplicate declaration.
|
|
|
|
Retain the existing rejection of one artifact or family key directly declared
|
|
by multiple base files, including disjoint contributions and declarations
|
|
later removed by an overlay. Inheritance is not permission to merge multiple
|
|
direct declarations of the same key.
|
|
|
|
Keep defining-file ownership distinct from value-contributor provenance.
|
|
Existing source and artifact inspection must describe inherited contributors
|
|
accurately without presenting them as conflicting declarations. ConfigKit's
|
|
retained metadata remains the source of that evidence.
|
|
|
|
For generated family members, the family's defining source identifies the
|
|
child family declaration; inherited parent files remain contributor evidence.
|
|
Keep existing logical artifact IDs and inspection interfaces.
|
|
|
|
Effective configuration, diffs, and digests continue to reflect resolved
|
|
domain values. Equivalent inherited and explicitly authored configurations
|
|
should have equivalent effective projections, regardless of their provenance.
|
|
Stage reuse continues to use existing semantic evidence.
|
|
|
|
### Loading and ownership boundaries
|
|
|
|
Retain ordinary ConfigKit loading, centralized typed defaults, imports, selected
|
|
overlays, domain resolution, credential bootstrap, and exact-name credential
|
|
forwarding. Preserve current path bases and read-only inspection workflows.
|
|
|
|
Layered loading, embedded configuration sources, programmatic mapping sources,
|
|
and source-relative resource rebasing are available upstream but are outside
|
|
this focused adoption. Narratio continues to own its domain rules; ConfigKit
|
|
owns structural inheritance, presence, provenance, and secret resolution.
|
|
|
|
## Required Changes
|
|
|
|
### Dependency and attribution
|
|
|
|
Update `go.mod` and `go.sum` to ConfigKit v0.5.0. Update its entry in
|
|
[attribution](../oss/attribution.md) to the selected version and the reviewed
|
|
commit's source and notice links. Existing applicable license texts can remain.
|
|
|
|
### Configuration integration
|
|
|
|
Adjust the existing duplicate-definition check to identify direct declarations
|
|
using public ConfigKit history and origin metadata. Preserve genuine duplicate
|
|
detection while excluding structural transfers from declaration counting.
|
|
Use the completed load's retained evidence rather than reparsing files or
|
|
performing a second load that could resolve superseded credential references.
|
|
|
|
Review source ownership and artifact-definition projections against the new
|
|
inheritance metadata. Update only where needed to report contributors correctly.
|
|
Keep effective rendering and digest construction grounded in the existing safe
|
|
typed projection, with credential identities rather than resolved values.
|
|
|
|
Use ConfigKit's native operation directly. No application-owned inheritance
|
|
engine, collection registration, alternative keyword, or compatibility loader
|
|
is needed.
|
|
|
|
### Compatibility and operator guidance
|
|
|
|
Document that `extends` is now reserved structural input throughout ConfigKit
|
|
loads, including dynamic mappings such as artifact IDs and prompt variables.
|
|
Operators using that key as ordinary data must rename it. Inheritance is active
|
|
without an opt-in switch; imports and overlay-file selection remain separately
|
|
controlled as before.
|
|
|
|
Explain native sibling lookup, inherited explicit presence, and the requirement
|
|
that parent and child entries satisfy Narratio's domain rules. Link to the
|
|
pinned upstream contract for detailed inheritance semantics. Clarify that a
|
|
selected overlay may contribute sibling inheritance directives; this does not
|
|
add inheritance or stacking between overlay files.
|
|
|
|
Update the configuration reference, internal configuration guide, and a small
|
|
maintained example when implementation lands. Preserve each field's current
|
|
path-resolution rule when its value is inherited. Record the reserved-key
|
|
compatibility impact in the eventual release note; automatic configuration
|
|
conversion is outside this feature.
|
|
|
|
### Verification
|
|
|
|
Add focused Narratio coverage for the confirmed cross-file artifact inheritance
|
|
gap and the corresponding artifact-family behavior. Retain coverage for real
|
|
duplicate declarations, including those hidden by overlay replacement or
|
|
removal. Verify inherited explicit values against Narratio's defaulting rules,
|
|
credential safety, contributor reporting, and equivalent effective projections.
|
|
|
|
Concentrate tests on Narratio's integration behavior. ConfigKit's own tests own
|
|
its generic inheritance algorithm and source lifecycle. Narratio's default
|
|
tests remain offline, use temporary configuration bundles and controlled secret
|
|
values, and do not depend on the sibling ConfigKit checkout. Run the existing
|
|
suite against the selected released module before completing the upgrade.
|
|
|
|
## Completion Criteria
|
|
|
|
Narratio selects the released ConfigKit v0.5.0 module without a local checkout
|
|
replacement. Cross-file artifact and family inheritance works through the
|
|
ordinary loader, while genuinely duplicated base declarations remain invalid.
|
|
Inspection distinguishes declaration ownership from inherited contributors;
|
|
effective projections and credential handling retain their existing semantics.
|
|
|
|
Maintained guidance and examples explain native inheritance and the reserved
|
|
`extends` key. Attribution identifies the selected upstream revision. Focused
|
|
regression coverage and the existing suite pass without implementing Audita or
|
|
workspace changes as part of this upgrade.
|
|
|
|
## Relationship To Subsequent Work
|
|
|
|
ConfigKit adoption provides a verified configuration baseline for the later
|
|
Audita and workspace features. It makes no changes to subprocess destinations,
|
|
session layout, or cleanup behavior.
|
|
|
|
Audita adoption then migrates downstream profiles and adds adapter support for
|
|
explicit report/debug destinations. Audita owns its separate ConfigKit and
|
|
PromptKit dependencies. Shared latest-attempt links, final workspace paths, and
|
|
retention protection remain part of the workspace reorganization, so those
|
|
facilities are implemented once at their shared owner.
|