Simplify the ConfigKit adoption plan
This commit is contained in:
@@ -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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user