244 lines
13 KiB
Markdown
244 lines
13 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. Rely on ConfigKit's assembly and
|
|
metadata features; validate Narratio's effective domain configuration without
|
|
adding acceptance rules about how that configuration was authored.
|
|
|
|
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.
|
|
|
|
### Effective configuration and native provenance
|
|
|
|
Remove Narratio's one-base-file-per-artifact/family restriction. If ConfigKit
|
|
accepts composition of one entry from several files, Narratio accepts that
|
|
entry when its effective domain values are valid. ConfigKit continues to reject
|
|
structural conflicts under its own contract. Narratio does not reconstruct
|
|
declaration history to add another conflict rule or reject domain values that
|
|
were removed or replaced before the final configuration handoff.
|
|
|
|
Domain validation concerns the effective configuration, including application
|
|
resolution and family expansion. Family publication requires an applicable
|
|
effective publish configuration, not separate evidence that the section was
|
|
explicitly authored rather than defaulted. Existing checks on destinations,
|
|
dependencies, identities, and effective publish rules remain.
|
|
|
|
Retain `config sources` and useful provenance in `config artifacts`. Consume
|
|
ConfigKit's public source, origin, presence, history, and explanation APIs as
|
|
intended. A thin formatting/projection layer may add Narratio-specific family,
|
|
character, and party context. It must not duplicate upstream source tracking,
|
|
inheritance analysis, or derivation bookkeeping.
|
|
|
|
An entry can have several contributors. Report the evidence ConfigKit provides
|
|
without inventing a unique defining-file guarantee or choosing an arbitrary
|
|
contributor as the owner. Keep logical artifact IDs independent of source files.
|
|
Small representation changes needed for truthful composite provenance belong
|
|
to this adoption; retiring inspection commands does not.
|
|
|
|
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.
|
|
|
|
ConfigKit owns parsing, source composition, structural inheritance, presence,
|
|
provenance, and secret resolution. Narratio owns its schema, domain defaults,
|
|
semantic normalization and validation, campaign/family resolution, and runtime
|
|
use. Supported defaults, resolver, and validator callbacks remain appropriate;
|
|
there is no requirement to move them after `Load` merely to establish this
|
|
ownership boundary. ConfigKit presence APIs remain suitable for absence-based
|
|
defaults, and native metadata remains suitable for operator inspection and
|
|
existing party ordering.
|
|
|
|
Layered loading, embedded configuration sources, programmatic mapping sources,
|
|
and source-relative resource rebasing are available upstream but are outside
|
|
this focused adoption. Do not relax empty/null default semantics or change
|
|
party ordering just to avoid using useful native APIs.
|
|
|
|
## 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
|
|
|
|
Delete the duplicate-definition check and its obsolete declaration-accounting
|
|
tests. Remove the family-publish explicit-declaration gate and metadata retained
|
|
only for that gate. Use existing final-value domain checks instead.
|
|
|
|
Simplify source and artifact-definition projections around ConfigKit's public
|
|
metadata. Remove duplicated tracking or inferred ownership where native evidence
|
|
already provides the needed information. Retain application context and
|
|
formatting that actually serve operators. Use the completed load's evidence
|
|
rather than reparsing sources or performing a second base-only load that could
|
|
resolve superseded credential references.
|
|
|
|
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.
|
|
|
|
### Policy alignment
|
|
|
|
Revise the Configuration section of the
|
|
[architecture policy](../policy/architecture.md) to record this responsibility
|
|
boundary: native loading and metadata belong to ConfigKit; Narratio owns domain
|
|
meaning and fail-fast effective validation. Explicitly permit supported
|
|
callbacks and native provenance inspection. Remove wording inconsistent with
|
|
the established explicit-presence/defaulting semantics rather than introducing
|
|
a new empty-value policy. General agent, testing, documentation, and OSS
|
|
policies need no broad revisions for this feature.
|
|
|
|
### 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.
|
|
|
|
Replace documentation of the one-base-file restriction with ConfigKit's
|
|
composition contract and Narratio's effective-value validation boundary.
|
|
Describe any inspection representation changes without promising a unique
|
|
defining file for a composite entry.
|
|
|
|
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 cross-file artifact/family inheritance and
|
|
valid disjoint contributions to one entry. Verify that effective invalid
|
|
configuration still fails before execution and that structural conflicts still
|
|
surface as ConfigKit errors. Old source-history rejection tests are retired or
|
|
rewritten for the new contract, including overlay replacement/removal cases.
|
|
Verify inherited explicit values against Narratio's defaulting rules, credential
|
|
safety, native 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; valid composition is not rejected by Narratio's declaration
|
|
history checks. Effective domain errors fail before execution. Native provenance
|
|
remains inspectable without unique-file assumptions; effective projections,
|
|
explicit-presence defaulting, and credential handling retain their semantics.
|
|
|
|
Maintained guidance and examples explain native inheritance and the reserved
|
|
`extends` key, and the architecture policy reflects the ConfigKit/Narratio
|
|
boundary. 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.
|