Simplify the ConfigKit adoption plan

This commit is contained in:
2026-10-04 12:42:58 +00:00
parent fe9817f354
commit 2850498043
2 changed files with 204 additions and 119 deletions

View File

@@ -5,7 +5,9 @@
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.
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
@@ -81,25 +83,32 @@ 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
### Effective configuration and native 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.
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.
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.
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.
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.
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.
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.
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
@@ -112,10 +121,19 @@ 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. Narratio continues to own its domain rules; ConfigKit
owns structural inheritance, presence, provenance, and secret resolution.
this focused adoption. Do not relax empty/null default semantics or change
party ordering just to avoid using useful native APIs.
## Required Changes
@@ -127,14 +145,17 @@ 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.
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.
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.
@@ -142,6 +163,17 @@ 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
@@ -156,6 +188,11 @@ 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
@@ -164,11 +201,13 @@ 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.
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
@@ -180,12 +219,14 @@ suite against the selected released module before completing the upgrade.
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.
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. Attribution identifies the selected upstream revision. Focused
`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.