10 KiB
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 and the workspace reorganization. This document defines the target and required changes; the implementation plan defines the steps for reaching that target.
Reviewed Upstream Release
ConfigKit v0.5.0 identifies commit
dc09959cca4e105f49ec316c6d4ba585bd2340bd. The
release notes,
configuration contract,
and consumer guide
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 owns Narratio's current public semantics; configuration internals 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 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.