Files
narratio/docs/roadmap/config.md

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.