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