# 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 v0.5.0 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. - Distinct fields of one artifact or artifact-family entry can compose across base files under ConfigKit's structural rules. Narratio validates the resulting effective entry, and the selected overlay may replace or remove those values. - 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 released v0.5.0 module is now selected directly, and its attribution points to the reviewed commit. Cross-file artifact and family inheritance and disjoint entry composition now pass through Narratio's effective configuration checks. The remaining integration work verifies native provenance, explicit presence, safe projections, and the assembled inspection workflow described below. ## 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.