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
|
Upgrade Narratio from ConfigKit v0.4.2 to v0.5.0 and integrate its native
|
||||||
sibling inheritance with Narratio's configuration validation and inspection.
|
sibling inheritance with Narratio's configuration validation and inspection.
|
||||||
Keep the upgrade focused on the existing loading model and the adjustments
|
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
|
This adoption precedes [Audita adoption](audita.md) and the
|
||||||
[workspace reorganization](workspace.md). This document defines the target
|
[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
|
values. Normal domain validation still determines whether a resulting value
|
||||||
is acceptable.
|
is acceptable.
|
||||||
|
|
||||||
### Declaration ownership and provenance
|
### Effective configuration and native provenance
|
||||||
|
|
||||||
Distinguish direct base declarations from inherited contributions. A child
|
Remove Narratio's one-base-file-per-artifact/family restriction. If ConfigKit
|
||||||
declared in one file may inherit from a separately declared parent in another
|
accepts composition of one entry from several files, Narratio accepts that
|
||||||
file without becoming a duplicate declaration.
|
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
|
Domain validation concerns the effective configuration, including application
|
||||||
by multiple base files, including disjoint contributions and declarations
|
resolution and family expansion. Family publication requires an applicable
|
||||||
later removed by an overlay. Inheritance is not permission to merge multiple
|
effective publish configuration, not separate evidence that the section was
|
||||||
direct declarations of the same key.
|
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.
|
Retain `config sources` and useful provenance in `config artifacts`. Consume
|
||||||
Existing source and artifact inspection must describe inherited contributors
|
ConfigKit's public source, origin, presence, history, and explanation APIs as
|
||||||
accurately without presenting them as conflicting declarations. ConfigKit's
|
intended. A thin formatting/projection layer may add Narratio-specific family,
|
||||||
retained metadata remains the source of that evidence.
|
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
|
An entry can have several contributors. Report the evidence ConfigKit provides
|
||||||
child family declaration; inherited parent files remain contributor evidence.
|
without inventing a unique defining-file guarantee or choosing an arbitrary
|
||||||
Keep existing logical artifact IDs and inspection interfaces.
|
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
|
Effective configuration, diffs, and digests continue to reflect resolved
|
||||||
domain values. Equivalent inherited and explicitly authored configurations
|
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
|
overlays, domain resolution, credential bootstrap, and exact-name credential
|
||||||
forwarding. Preserve current path bases and read-only inspection workflows.
|
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,
|
Layered loading, embedded configuration sources, programmatic mapping sources,
|
||||||
and source-relative resource rebasing are available upstream but are outside
|
and source-relative resource rebasing are available upstream but are outside
|
||||||
this focused adoption. Narratio continues to own its domain rules; ConfigKit
|
this focused adoption. Do not relax empty/null default semantics or change
|
||||||
owns structural inheritance, presence, provenance, and secret resolution.
|
party ordering just to avoid using useful native APIs.
|
||||||
|
|
||||||
## Required Changes
|
## Required Changes
|
||||||
|
|
||||||
@@ -127,14 +145,17 @@ commit's source and notice links. Existing applicable license texts can remain.
|
|||||||
|
|
||||||
### Configuration integration
|
### Configuration integration
|
||||||
|
|
||||||
Adjust the existing duplicate-definition check to identify direct declarations
|
Delete the duplicate-definition check and its obsolete declaration-accounting
|
||||||
using public ConfigKit history and origin metadata. Preserve genuine duplicate
|
tests. Remove the family-publish explicit-declaration gate and metadata retained
|
||||||
detection while excluding structural transfers from declaration counting.
|
only for that gate. Use existing final-value domain checks instead.
|
||||||
Use the completed load's retained evidence rather than reparsing files or
|
|
||||||
performing a second load that could resolve superseded credential references.
|
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
|
Keep effective rendering and digest construction grounded in the existing safe
|
||||||
typed projection, with credential identities rather than resolved values.
|
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
|
engine, collection registration, alternative keyword, or compatibility loader
|
||||||
is needed.
|
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
|
### Compatibility and operator guidance
|
||||||
|
|
||||||
Document that `extends` is now reserved structural input throughout ConfigKit
|
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
|
selected overlay may contribute sibling inheritance directives; this does not
|
||||||
add inheritance or stacking between overlay files.
|
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
|
Update the configuration reference, internal configuration guide, and a small
|
||||||
maintained example when implementation lands. Preserve each field's current
|
maintained example when implementation lands. Preserve each field's current
|
||||||
path-resolution rule when its value is inherited. Record the reserved-key
|
path-resolution rule when its value is inherited. Record the reserved-key
|
||||||
@@ -164,11 +201,13 @@ conversion is outside this feature.
|
|||||||
|
|
||||||
### Verification
|
### Verification
|
||||||
|
|
||||||
Add focused Narratio coverage for the confirmed cross-file artifact inheritance
|
Add focused Narratio coverage for cross-file artifact/family inheritance and
|
||||||
gap and the corresponding artifact-family behavior. Retain coverage for real
|
valid disjoint contributions to one entry. Verify that effective invalid
|
||||||
duplicate declarations, including those hidden by overlay replacement or
|
configuration still fails before execution and that structural conflicts still
|
||||||
removal. Verify inherited explicit values against Narratio's defaulting rules,
|
surface as ConfigKit errors. Old source-history rejection tests are retired or
|
||||||
credential safety, contributor reporting, and equivalent effective projections.
|
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
|
Concentrate tests on Narratio's integration behavior. ConfigKit's own tests own
|
||||||
its generic inheritance algorithm and source lifecycle. Narratio's default
|
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
|
Narratio selects the released ConfigKit v0.5.0 module without a local checkout
|
||||||
replacement. Cross-file artifact and family inheritance works through the
|
replacement. Cross-file artifact and family inheritance works through the
|
||||||
ordinary loader, while genuinely duplicated base declarations remain invalid.
|
ordinary loader; valid composition is not rejected by Narratio's declaration
|
||||||
Inspection distinguishes declaration ownership from inherited contributors;
|
history checks. Effective domain errors fail before execution. Native provenance
|
||||||
effective projections and credential handling retain their existing semantics.
|
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
|
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
|
regression coverage and the existing suite pass without implementing Audita or
|
||||||
workspace changes as part of this upgrade.
|
workspace changes as part of this upgrade.
|
||||||
|
|
||||||
|
|||||||
@@ -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
|
v0.5.0 and integration with native sibling inheritance. Audita adoption and
|
||||||
workspace reorganization remain subsequent, separately planned work.
|
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
|
The reviewed upstream revision is
|
||||||
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`.
|
`dc09959cca4e105f49ec316c6d4ba585bd2340bd`, tagged `v0.5.0`.
|
||||||
Use the released module, not a local replacement. The pinned
|
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
|
domain validation, and current path-resolution rules. Native inheritance is
|
||||||
available wherever ConfigKit and Narratio's schema permit it, with no new
|
available wherever ConfigKit and Narratio's schema permit it, with no new
|
||||||
collection allowlist, opt-in flag, or Narratio-owned inheritance engine.
|
collection allowlist, opt-in flag, or Narratio-owned inheritance engine.
|
||||||
- Distinguish original declarations from inherited contributors. Preserve
|
- Trust ConfigKit's structural acceptance rules. Remove Narratio's
|
||||||
genuine duplicate-base rejection and truthful provenance. Parent entries
|
one-base-file-per-entry check rather than making it inheritance-aware. Validate
|
||||||
remain ordinary entries subject to existing domain rules.
|
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
|
- Keep invocation-owned secrets bootstrap and shared exact-name credential
|
||||||
forwarding unchanged. Do not introduce a second base load, file reparse, or
|
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
|
- Tests use temporary files, controlled synthetic secrets, and real internal
|
||||||
collaborators. No downstream executable, sibling checkout, cloud service,
|
collaborators. No downstream executable, sibling checkout, cloud service,
|
||||||
or paid provider is needed. Protect integration behavior rather than
|
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
|
suitable validation. Report blockers and incomplete work accurately. If a
|
||||||
review-only task needs no source fix, retain useful behavioral coverage and
|
review-only task needs no source fix, retain useful behavioral coverage and
|
||||||
report that result rather than making a cosmetic rewrite.
|
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,
|
Do not adopt layered loading, new source types, source-relative rebasing,
|
||||||
abstract artifacts, automatic YAML conversion, new execution selection rules,
|
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;
|
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.
|
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
|
Purpose: accept structurally composed configuration from ConfigKit and reject
|
||||||
files while preserving existing duplicate-declaration rejection.
|
only invalid effective Narratio domain configuration.
|
||||||
|
|
||||||
Read `internal/config/pipeline_configkit.go`, particularly
|
Read `internal/config/pipeline_configkit.go`, particularly
|
||||||
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`, and
|
`pipelineMetadataFromConfigKit` and `rejectDuplicateBaseDefinitions`,
|
||||||
`internal/config/pipeline_configkit_test.go`. Inspect the public ConfigKit
|
`pipeline_configkit_test.go`, and `expandFamilyPublishRules` and its tests in
|
||||||
`Metadata.History`, `HistoricalPaths`, `Origin`, and `ChangeKind` contracts.
|
`internal/config/artifact_families.go` and `artifact_families_test.go`.
|
||||||
|
|
||||||
1. Add package-boundary regression fixtures with a valid parent in one imported
|
1. Delete `rejectDuplicateBaseDefinitions` and its invocation. Do not replace
|
||||||
file and a child using `extends` in another. Cover ordinary artifacts and
|
it with filtering of inheritance events, direct-declaration counting, or
|
||||||
artifact families. Give parent and child distinct valid output paths or
|
another source-history validator.
|
||||||
family patterns, and provide canonical-party context for expanded families.
|
2. Replace `TestPipelineConfigKitRejectsDuplicateBaseDeclarations` with behavior
|
||||||
Both keys remain ordinary domain entries; child IDs must stay their own.
|
coverage showing that disjoint contributions to one artifact/family compose
|
||||||
2. Adjust declaration accounting using retained public metadata. In v0.5.0,
|
successfully when the resulting domain entry is valid. Check selected-overlay
|
||||||
original base-input events have `LayerBase` and no origin operation;
|
replacement/removal without Narratio rejecting superseded declarations.
|
||||||
projected transfers carry `ChangeInheritance`. Count original base
|
3. Add cross-file artifact and family inheritance regressions. Supply valid
|
||||||
declarations, not these transfers or subsequent decoding/resolution events.
|
surviving parent and child entries with distinct output destinations, and
|
||||||
Consumed structural `extends` paths are not artifact declarations.
|
campaign/party context for family expansion. Verify child identities and
|
||||||
3. Keep the historical-path check, including original declarations erased by
|
effective fields; the inheritance regression must fail on the old check.
|
||||||
a selected overlay. Do not switch to surviving effective keys only or count
|
4. Remove the `publishDeclared` gate in `expandFamilyPublishRules`, its metadata
|
||||||
all displaced origins as fresh declarations. Reuse a small package-local
|
population, and state retained only for that gate. Validate family publication
|
||||||
helper only if it makes the next stage clearer.
|
against the effective `Publish` value, whether authored or supplied by defaults.
|
||||||
4. Retain `TestPipelineConfigKitRejectsDuplicateBaseDeclarations`, including
|
Preserve the missing-effective-publish check, ordinary enablement behavior,
|
||||||
disjoint fields supplied to the same key, container removal, and removal of
|
destination validation, and conflicts between effective publish rules.
|
||||||
Scriptorium by an overlay. An overlay may still modify an existing entry.
|
Update the test that currently fabricates an explicit-declaration flag.
|
||||||
Add only any missing regression case needed to exercise the new filter.
|
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
|
Verify with `go test ./internal/config`. Assert effective outcomes and safe
|
||||||
should expose the baseline defect before the fix. Assert loaded values and
|
error categories, not entire diagnostic text or private metadata event order.
|
||||||
identities, or the duplicate category and relevant sources, without matching an
|
Do not run a separate base-only load to validate overwritten input.
|
||||||
entire diagnostic or ConfigKit's private event ordering.
|
|
||||||
|
|
||||||
Complete when cross-file inheritance loads and expands correctly, and actual
|
Complete when valid cross-file composition/inheritance succeeds and invalid
|
||||||
duplicates still fail even when the overlay hides them. Do not use the direct
|
effective configuration still fails before execution, without authored-source
|
||||||
declaration filter to remove contributor evidence from inspection.
|
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
|
Purpose: preserve useful operator inspection without a parallel provenance
|
||||||
files, without confusing its defining file with those contributors.
|
system or a unique-defining-file contract for composite entries.
|
||||||
|
|
||||||
Read `internal/config/artifact_catalog.go`,
|
Read `internal/config/artifact_catalog.go`, `artifact_families.go`,
|
||||||
`internal/config/artifact_families.go`, `internal/config/effective_pipeline.go`,
|
`effective_pipeline.go`, `effective_digest.go`, and the metadata projection in
|
||||||
and metadata-to-ownership projection in `pipeline_configkit.go`. Inspect the
|
`pipeline_configkit.go`. Inspect `internal/app/config_commands_test.go`,
|
||||||
focused catalog, family, and effective-source tests.
|
`config_artifacts_test.go`, and ConfigKit's public metadata contracts.
|
||||||
|
|
||||||
1. Exercise the inherited configurations from Stage 2 through
|
1. Keep `config sources` and provenance-bearing `config artifacts` output.
|
||||||
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Check inherited
|
Use public ConfigKit sources, effective origins, history, and explanations
|
||||||
values against their actual parent contributors and child overrides against
|
for the information they own. Keep presence queries and recorded callbacks
|
||||||
the child/overlay contributors. Keep historical definition evidence distinct
|
where needed; retaining returned metadata is not duplicating its implementation.
|
||||||
from effective field ownership.
|
2. Review existing helper/state layers for duplicated tracking. Remove redundant
|
||||||
2. Preserve `DefinitionSources` aggregation, including inherited contributors.
|
cached field-ownership reconstruction where the same result is available
|
||||||
Do not relabel all inherited values as authored in the child's file.
|
directly from retained metadata. Keep a small projection where needed for
|
||||||
3. Correct `artifactFamilySource` where its first inherited field currently
|
Narratio's generated family/character/party context and output formatting.
|
||||||
selects the parent's file. For an explicitly declared child family, identify
|
Do not add a provenance service, custom ancestry graph, or second source parse.
|
||||||
its original declaration using retained metadata: use its base defining file
|
3. Exercise Stage 2's inherited and multi-file entries through
|
||||||
when present, or its overlay defining file for an overlay-only family.
|
`EffectiveArtifactCatalog` and `EffectivePipelineSources`. Report actual
|
||||||
Overlay edits to a base family do not relocate its base definition.
|
contributors and child overrides. Keep historical definition evidence
|
||||||
4. Retain the existing fallback for entries without a direct declaration or
|
distinguishable from effective field origins as exposed by ConfigKit.
|
||||||
programmatically constructed configuration. Do not restrict valid enclosing
|
4. Replace `artifactFamilySource`'s arbitrary first-contributor ownership with
|
||||||
inheritance merely to force every entry into a single-file ownership model.
|
native source/origin evidence. Do not infer a unique base defining file or
|
||||||
5. Keep logical `SourceID`, artifact keys, family/character/party provenance,
|
implement a new declaration-accounting algorithm. Composite origins may have
|
||||||
existing source roles, and inspection interfaces. Update projections only
|
several sources; preserve them using existing repeated source records and
|
||||||
where inherited evidence is otherwise lost or incorrectly attributed.
|
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
|
Verify with `go test ./internal/config ./internal/app`. Cover a child family
|
||||||
family inheriting from another file and a selected-overlay contribution. Check
|
inheriting across files, an entry composed from disjoint files, and an overlay
|
||||||
meaningful records and source identities, not a complete formatted snapshot.
|
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
|
Complete when native provenance remains useful and truthful, redundant tracking
|
||||||
identify their child family definition rather than an arbitrary inherited field.
|
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
|
## 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.
|
newly normalize other path fields merely to make their behavior uniform.
|
||||||
5. Fix any demonstrated Narratio integration defect at its existing defaulting
|
5. Fix any demonstrated Narratio integration defect at its existing defaulting
|
||||||
or domain-resolution owner. Use ConfigKit presence and recorded operations;
|
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
|
Verify with `go test ./internal/config`. Keep coverage representative; generic
|
||||||
missing-parent, cycle, resource-context, and expansion-limit matrices belong to
|
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
|
Complete when resolved values, not source layout or secret bytes, determine
|
||||||
effective comparison, and inherited credentials obey the existing safe boundary.
|
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
|
Purpose: make the adopted behavior understandable and usable without expanding
|
||||||
Narratio's configuration surface.
|
Narratio's configuration surface.
|
||||||
|
|
||||||
Read `docs/config.md`, `docs/internal/configuration.md`, `examples/README.md`,
|
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.
|
`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,
|
Explain exact sibling lookup, overlay-before-inheritance resolution,
|
||||||
explicit presence, ordinary parent validation, distinct child identity,
|
explicit presence, ordinary parent validation, distinct child identity,
|
||||||
and cross-file declaration/contributor distinctions. Link to the pinned
|
and native contributor inspection. Remove the one-base-file restriction and
|
||||||
upstream contract for detailed syntax and structural rules.
|
describe acceptance of ConfigKit-composed entries. Update family-publish
|
||||||
2. Explain the reserved `extends` key throughout ConfigKit inputs, including
|
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
|
dynamic artifact IDs and prompt-variable mappings. Operators must rename
|
||||||
existing ordinary-data keys with that name; there is no opt-in or automatic
|
existing ordinary-data keys with that name; there is no opt-in or automatic
|
||||||
conversion. Campaign, session, and party inputs also use ConfigKit.
|
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
|
cannot inherit or stack, but the selected overlay may supply native sibling
|
||||||
directives within its values. Keep imports and overlay selection unchanged.
|
directives within its values. Keep imports and overlay selection unchanged.
|
||||||
4. Update configuration internals for inheritance before typed decoding,
|
5. Update configuration internals for inheritance before typed decoding,
|
||||||
original-declaration counting, contributor projection, and the safe
|
removal of authoring gates, thin native contributor projection, and the safe
|
||||||
effective boundary. Describe implemented mechanisms, linking to the public
|
effective boundary. Describe implemented mechanisms, linking to the public
|
||||||
reference for their operator-facing meaning.
|
reference for their operator-facing meaning. Update `docs/cli.md` where source
|
||||||
5. In `examples/production-testing/overlays/testing.yml`, add
|
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
|
`extends: session_recap` to the existing `testing_notes` artifact. Keep its
|
||||||
disabled status and distinct output override. It inherits the imported
|
disabled status and distinct output override. It inherits the imported
|
||||||
parent's prompt/input and the parent's testing profile after overlay
|
parent's prompt/input and the parent's testing profile after overlay
|
||||||
application. The parent remains an ordinary artifact.
|
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
|
those inherited fields. Preserve the bundle's current identities and
|
||||||
artifact count; no new example root or template convention is necessary.
|
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
|
catalog, and diff through existing command entry points. Use a campaign/party
|
||||||
fixture for family inspection, and paired overlays with equivalent inherited
|
fixture for family inspection, and paired overlays with equivalent inherited
|
||||||
and explicitly expanded values when testing command-level diff equality.
|
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
|
sources, logical artifact identities, and no secret values. Keep inspection
|
||||||
read-only with respect to session/runtime state, as existing tests establish.
|
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
|
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,
|
ConfigKit v0.5.0 is selected, attribution links use the reviewed revision,
|
||||||
no optional loading feature was adopted, and no Audita/workspace change or
|
authoring-history acceptance checks were removed, native inspection and
|
||||||
compatibility shim slipped into scope.
|
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 ./...`,
|
4. Run `go test ./...`, `go test -race ./...`, `go vet ./...`,
|
||||||
`go build ./...`, `go mod tidy -diff`, and `git diff --check` against the
|
`go build ./...`, `go mod tidy -diff`, and `git diff --check` against the
|
||||||
final source. These reuse existing repository checks, not new release gates.
|
final source. These reuse existing repository checks, not new release gates.
|
||||||
@@ -314,6 +356,8 @@ outside this implementation pass.
|
|||||||
## Open Questions
|
## Open Questions
|
||||||
|
|
||||||
None required for this adoption. Existing decisions select native inheritance,
|
None required for this adoption. Existing decisions select native inheritance,
|
||||||
current loading/path/credential semantics, and ConfigKit before Audita before
|
native metadata inspection and callbacks, effective-domain validation instead
|
||||||
workspace work. Eventual release preparation must account for the reserved-key
|
of authoring-history gates, current path/credential/presence semantics, and
|
||||||
compatibility impact under the release policy; no version is selected here.
|
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