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.

View File

@@ -7,6 +7,12 @@ choices, and rationale. This plan covers Narratio's upgrade from v0.4.2 to
v0.5.0 and integration with native sibling inheritance. Audita adoption and
workspace reorganization remain subsequent, separately planned work.
ConfigKit owns source assembly and native provenance. Narratio validates the
effective domain configuration and exposes the library's metadata to operators.
This revision replaces the earlier plan to repair declaration-history counting
with removal of that additional acceptance rule. It retains supported callbacks,
presence-sensitive defaults, party ordering, and provenance inspection.
The reviewed upstream revision is
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`.
Use the released module, not a local replacement. The pinned
@@ -34,12 +40,17 @@ than requiring changes to every listed file.
domain validation, and current path-resolution rules. Native inheritance is
available wherever ConfigKit and Narratio's schema permit it, with no new
collection allowlist, opt-in flag, or Narratio-owned inheritance engine.
- Distinguish original declarations from inherited contributors. Preserve
genuine duplicate-base rejection and truthful provenance. Parent entries
remain ordinary entries subject to existing domain rules.
- Trust ConfigKit's structural acceptance rules. Remove Narratio's
one-base-file-per-entry check rather than making it inheritance-aware. Validate
resulting domain values; source history is diagnostic evidence, not another
acceptance gate. Parent entries that survive composition remain ordinary
entries subject to applicable domain rules.
- Use native presence and provenance APIs for defaults and operator inspection.
Keep supported callbacks and party ordering. Do not impose post-`Load` callback
relocation, relaxed empty/null semantics, or retirement of `config sources`.
- Keep invocation-owned secrets bootstrap and shared exact-name credential
forwarding unchanged. Do not introduce a second base load, file reparse, or
historical-secret lookup to recover declaration information.
historical-secret lookup to reconstruct provenance or validate old input.
- Tests use temporary files, controlled synthetic secrets, and real internal
collaborators. No downstream executable, sibling checkout, cloud service,
or paid provider is needed. Protect integration behavior rather than
@@ -48,6 +59,11 @@ than requiring changes to every listed file.
suitable validation. Report blockers and incomplete work accurately. If a
review-only task needs no source fix, retain useful behavioral coverage and
report that result rather than making a cosmetic rewrite.
- Update affected canonical documentation with each implemented behavior change.
In particular, Stage 2 updates the removed authoring restrictions and Stage 3
updates changed inspection meanings. Stage 6 consolidates the policy review,
inheritance guidance, and example; it is not a reason to leave earlier
completed commits describing obsolete behavior.
Do not adopt layered loading, new source types, source-relative rebasing,
abstract artifacts, automatic YAML conversion, new execution selection rules,
@@ -82,79 +98,89 @@ Complete when the released dependency and notices agree and current focused
tests pass. The cross-file inheritance defect is addressed in the next stage;
this stage does not claim that new inheritance behavior is fully integrated.
## Stage 2: Correct direct declaration accounting
## Stage 2: Remove source-authoring acceptance gates
Purpose: allow distinct artifact and family keys to inherit across imported
files while preserving existing duplicate-declaration rejection.
Purpose: accept structurally composed configuration from ConfigKit and reject
only invalid effective Narratio domain configuration.
Read `internal/config/pipeline_configkit.go`, particularly
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`, and
`internal/config/pipeline_configkit_test.go`. Inspect the public ConfigKit
`Metadata.History`, `HistoricalPaths`, `Origin`, and `ChangeKind` contracts.
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`,
`pipeline_configkit_test.go`, and `expandFamilyPublishRules` and its tests in
`internal/config/artifact_families.go` and `artifact_families_test.go`.
1. Add package-boundary regression fixtures with a valid parent in one imported
file and a child using `extends` in another. Cover ordinary artifacts and
artifact families. Give parent and child distinct valid output paths or
family patterns, and provide canonical-party context for expanded families.
Both keys remain ordinary domain entries; child IDs must stay their own.
2. Adjust declaration accounting using retained public metadata. In v0.5.0,
original base-input events have `LayerBase` and no origin operation;
projected transfers carry `ChangeInheritance`. Count original base
declarations, not these transfers or subsequent decoding/resolution events.
Consumed structural `extends` paths are not artifact declarations.
3. Keep the historical-path check, including original declarations erased by
a selected overlay. Do not switch to surviving effective keys only or count
all displaced origins as fresh declarations. Reuse a small package-local
helper only if it makes the next stage clearer.
4. Retain `TestPipelineConfigKitRejectsDuplicateBaseDeclarations`, including
disjoint fields supplied to the same key, container removal, and removal of
Scriptorium by an overlay. An overlay may still modify an existing entry.
Add only any missing regression case needed to exercise the new filter.
1. Delete `rejectDuplicateBaseDefinitions` and its invocation. Do not replace
it with filtering of inheritance events, direct-declaration counting, or
another source-history validator.
2. Replace `TestPipelineConfigKitRejectsDuplicateBaseDeclarations` with behavior
coverage showing that disjoint contributions to one artifact/family compose
successfully when the resulting domain entry is valid. Check selected-overlay
replacement/removal without Narratio rejecting superseded declarations.
3. Add cross-file artifact and family inheritance regressions. Supply valid
surviving parent and child entries with distinct output destinations, and
campaign/party context for family expansion. Verify child identities and
effective fields; the inheritance regression must fail on the old check.
4. Remove the `publishDeclared` gate in `expandFamilyPublishRules`, its metadata
population, and state retained only for that gate. Validate family publication
against the effective `Publish` value, whether authored or supplied by defaults.
Preserve the missing-effective-publish check, ordinary enablement behavior,
destination validation, and conflicts between effective publish rules.
Update the test that currently fabricates an explicit-declaration flag.
5. Retain effective-domain rejection, including invalid artifacts, unresolved
dependencies, and destination collisions under current rules. Reuse existing
tests where adequate. Retain a representative structural-conflict check at
the loader boundary; ConfigKit owns the full conflict/precedence matrix.
Verify with `go test ./internal/config`. The positive cross-file regression
should expose the baseline defect before the fix. Assert loaded values and
identities, or the duplicate category and relevant sources, without matching an
entire diagnostic or ConfigKit's private event ordering.
Verify with `go test ./internal/config`. Assert effective outcomes and safe
error categories, not entire diagnostic text or private metadata event order.
Do not run a separate base-only load to validate overwritten input.
Complete when cross-file inheritance loads and expands correctly, and actual
duplicates still fail even when the overlay hides them. Do not use the direct
declaration filter to remove contributor evidence from inspection.
Complete when valid cross-file composition/inheritance succeeds and invalid
effective configuration still fails before execution, without authored-source
acceptance gates. Keep native metadata available for the next stage.
## Stage 3: Preserve contributor provenance and family ownership
## Stage 3: Simplify provenance inspection around native APIs
Purpose: keep inspection useful when one entry contains values from several
files, without confusing its defining file with those contributors.
Purpose: preserve useful operator inspection without a parallel provenance
system or a unique-defining-file contract for composite entries.
Read `internal/config/artifact_catalog.go`,
`internal/config/artifact_families.go`, `internal/config/effective_pipeline.go`,
and metadata-to-ownership projection in `pipeline_configkit.go`. Inspect the
focused catalog, family, and effective-source tests.
Read `internal/config/artifact_catalog.go`, `artifact_families.go`,
`effective_pipeline.go`, `effective_digest.go`, and the metadata projection in
`pipeline_configkit.go`. Inspect `internal/app/config_commands_test.go`,
`config_artifacts_test.go`, and ConfigKit's public metadata contracts.
1. Exercise the inherited configurations from Stage 2 through
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Check inherited
values against their actual parent contributors and child overrides against
the child/overlay contributors. Keep historical definition evidence distinct
from effective field ownership.
2. Preserve `DefinitionSources` aggregation, including inherited contributors.
Do not relabel all inherited values as authored in the child's file.
3. Correct `artifactFamilySource` where its first inherited field currently
selects the parent's file. For an explicitly declared child family, identify
its original declaration using retained metadata: use its base defining file
when present, or its overlay defining file for an overlay-only family.
Overlay edits to a base family do not relocate its base definition.
4. Retain the existing fallback for entries without a direct declaration or
programmatically constructed configuration. Do not restrict valid enclosing
inheritance merely to force every entry into a single-file ownership model.
5. Keep logical `SourceID`, artifact keys, family/character/party provenance,
existing source roles, and inspection interfaces. Update projections only
where inherited evidence is otherwise lost or incorrectly attributed.
1. Keep `config sources` and provenance-bearing `config artifacts` output.
Use public ConfigKit sources, effective origins, history, and explanations
for the information they own. Keep presence queries and recorded callbacks
where needed; retaining returned metadata is not duplicating its implementation.
2. Review existing helper/state layers for duplicated tracking. Remove redundant
cached field-ownership reconstruction where the same result is available
directly from retained metadata. Keep a small projection where needed for
Narratio's generated family/character/party context and output formatting.
Do not add a provenance service, custom ancestry graph, or second source parse.
3. Exercise Stage 2's inherited and multi-file entries through
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Report actual
contributors and child overrides. Keep historical definition evidence
distinguishable from effective field origins as exposed by ConfigKit.
4. Replace `artifactFamilySource`'s arbitrary first-contributor ownership with
native source/origin evidence. Do not infer a unique base defining file or
implement a new declaration-accounting algorithm. Composite origins may have
several sources; preserve them using existing repeated source records and
comma-separated catalog source lists. Adjust the runtime-only representation
minimally where a single-source field cannot carry that evidence.
5. Preserve logical artifact IDs, family/character identities, party provenance,
inspection command names, and read-only behavior. Retain existing headers
where their meanings remain accurate; explain that family source evidence may
be composite instead of promising a unique defining file. Do not change
native-metadata-based party ordering merely to avoid library APIs.
Verify with `go test ./internal/config`. Cover an explicitly declared child
family inheriting from another file and a selected-overlay contribution. Check
meaningful records and source identities, not a complete formatted snapshot.
Verify with `go test ./internal/config ./internal/app`. Cover a child family
inheriting across files, an entry composed from disjoint files, and an overlay
override. Check meaningful source records, logical identities, and absence of
secret values rather than full formatted snapshots or upstream event ordering.
Complete when contributor reporting remains truthful and generated members
identify their child family definition rather than an arbitrary inherited field.
Complete when native provenance remains useful and truthful, redundant tracking
is removed where practical, and no acceptance rule depends on contributor count
or an inferred defining file. Application derivation context remains available.
## Stage 4: Verify inherited presence, domain resolution, and path bases
@@ -186,7 +212,10 @@ the relevant domain validators.
newly normalize other path fields merely to make their behavior uniform.
5. Fix any demonstrated Narratio integration defect at its existing defaulting
or domain-resolution owner. Use ConfigKit presence and recorded operations;
do not recreate structural inheritance or weaken ordinary validation.
retain supported defaults/resolver/validator callbacks. There is no required
move to post-`Load` functions. Do not recreate structural inheritance, inspect
old input to add acceptance rules, or relax empty/null semantics to avoid
using the library's presence API.
Verify with `go test ./internal/config`. Keep coverage representative; generic
missing-parent, cycle, resource-context, and expansion-limit matrices belong to
@@ -230,37 +259,48 @@ rewrite adapters or duplicate those tests simply because input can be inherited.
Complete when resolved values, not source layout or secret bytes, determine
effective comparison, and inherited credentials obey the existing safe boundary.
## Stage 6: Document inheritance and maintain a small example
## Stage 6: Align policy, document inheritance, and maintain an example
Purpose: make the adopted behavior understandable and usable without expanding
Narratio's configuration surface.
Read `docs/config.md`, `docs/internal/configuration.md`, `examples/README.md`,
the production/testing bundle, and `TestExamplesLoadAndValidate` in
`docs/policy/architecture.md`, the production/testing bundle, and
`TestExamplesLoadAndValidate` in
`internal/config/load_validate_test.go`. Follow the documentation policy.
1. Add native sibling inheritance guidance to the configuration reference.
1. Revise only the project-specific Configuration section of the architecture
policy to record the implemented boundary: ConfigKit owns loading, assembly,
inheritance, presence, secrets, and provenance; Narratio owns domain meaning
and fail-fast effective validation. Permit native metadata inspection and
supported callbacks. Align the ambiguous empty-value statement with existing
explicit-presence defaults, not a new blank/null policy. Leave general
upstream agent, testing, documentation, and OSS policy wording unchanged.
2. Add native sibling inheritance guidance to the configuration reference.
Explain exact sibling lookup, overlay-before-inheritance resolution,
explicit presence, ordinary parent validation, distinct child identity,
and cross-file declaration/contributor distinctions. Link to the pinned
upstream contract for detailed syntax and structural rules.
2. Explain the reserved `extends` key throughout ConfigKit inputs, including
and native contributor inspection. Remove the one-base-file restriction and
describe acceptance of ConfigKit-composed entries. Update family-publish
guidance for effective configuration rather than explicit authoring. Link to
the pinned upstream contract for detailed syntax and structural rules.
3. Explain the reserved `extends` key throughout ConfigKit inputs, including
dynamic artifact IDs and prompt-variable mappings. Operators must rename
existing ordinary-data keys with that name; there is no opt-in or automatic
conversion. Campaign, session, and party inputs also use ConfigKit.
3. Clarify the existing statement that overlays cannot inherit: overlay files
4. Clarify the existing statement that overlays cannot inherit: overlay files
cannot inherit or stack, but the selected overlay may supply native sibling
directives within its values. Keep imports and overlay selection unchanged.
4. Update configuration internals for inheritance before typed decoding,
original-declaration counting, contributor projection, and the safe
5. Update configuration internals for inheritance before typed decoding,
removal of authoring gates, thin native contributor projection, and the safe
effective boundary. Describe implemented mechanisms, linking to the public
reference for their operator-facing meaning.
5. In `examples/production-testing/overlays/testing.yml`, add
reference for their operator-facing meaning. Update `docs/cli.md` where source
output now reports composite evidence rather than a unique defining file.
6. In `examples/production-testing/overlays/testing.yml`, add
`extends: session_recap` to the existing `testing_notes` artifact. Keep its
disabled status and distinct output override. It inherits the imported
parent's prompt/input and the parent's testing profile after overlay
application. The parent remains an ordinary artifact.
6. Update the example guide and extend existing example validation to check
7. Update the example guide and extend existing example validation to check
those inherited fields. Preserve the bundle's current identities and
artifact count; no new example root or template convention is necessary.
@@ -287,14 +327,16 @@ package coverage rather than repeating its entire matrix at the CLI boundary.
catalog, and diff through existing command entry points. Use a campaign/party
fixture for family inspection, and paired overlays with equivalent inherited
and explicitly expanded values when testing command-level diff equality.
2. Check semantic output: resolved child values, expected contributor/defining
2. Check semantic output: resolved child values, native contributor/origin
sources, logical artifact identities, and no secret values. Keep inspection
read-only with respect to session/runtime state, as existing tests establish.
Do not invoke downstream applications or add CLI modes or columns.
Do not invoke downstream applications or introduce new inspection modes.
3. Review the combined diff against `config.md` and this plan. Confirm that
ConfigKit v0.5.0 is selected, attribution links use the reviewed revision,
no optional loading feature was adopted, and no Audita/workspace change or
compatibility shim slipped into scope.
authoring-history acceptance checks were removed, native inspection and
presence semantics remain, and policy reflects that boundary. Confirm no
optional loading feature, Audita/workspace change, or compatibility shim
slipped into scope.
4. Run `go test ./...`, `go test -race ./...`, `go vet ./...`,
`go build ./...`, `go mod tidy -diff`, and `git diff --check` against the
final source. These reuse existing repository checks, not new release gates.
@@ -314,6 +356,8 @@ outside this implementation pass.
## Open Questions
None required for this adoption. Existing decisions select native inheritance,
current loading/path/credential semantics, and ConfigKit before Audita before
workspace work. Eventual release preparation must account for the reserved-key
compatibility impact under the release policy; no version is selected here.
native metadata inspection and callbacks, effective-domain validation instead
of authoring-history gates, current path/credential/presence semantics, and
ConfigKit before Audita before workspace work. Eventual release preparation must
account for the reserved-key compatibility impact and inspection representation
changes under the release policy; no version is selected here.