narratio/docs/roadmap/configkit-v0.3.0.md

Adopt ConfigKit v0.3.0

Status: Accepted — implementation pending

Execution order and stage acceptance checks belong to the implementation plan. This roadmap owns scope, policy, and the target end state.

Goal

Upgrade Narratio from ConfigKit v0.1.2 to the released v0.3.0 while preserving Narratio's configuration contracts. Keep this a bounded dependency-maintenance change, not a new configuration feature or a second configuration refactor.

The upgrade also includes correcting the test-isolation problems discovered during evaluation so that validation does not depend on whether the developer has installed Narratio configuration on the host.

Background and Evaluation

ConfigKit v0.3.0 adds callback-scoped Resolution.InputInfo and Resolution.Source queries and separates its public API from its private engine. The public imports, signatures, secret handling, and existing metadata APIs, including Metadata.HistoricalPaths, remain supported. Its minimum Go version remains 1.25; Narratio's maintained Go 1.26 baseline needs no change. The private YAML dependency remains go.yaml.in/yaml/v4 v4.0.0-rc.6.

The intervening v0.2.0 release allows decimal-integer schema-version input to reach an application's version checker as text. It also rejects signed sequence index tokens such as +0 and -0; literal mapping keys are unaffected. Narratio constructs sequence paths using ConfigKit's index API and does not need a user-facing path migration.

ConfigKit now treats macOS as best-effort. This does not require changing Narratio's Linux amd64/arm64 support or its own best-effort macOS arm64 cross-build gate.

The 2026-09-16 evaluation used the released dependency through a temporary module file, without changing Narratio's tracked files:

• Build, vet, and Linux arm64/macOS arm64 cross-builds passed.
• The ordinary suite exposed one upgrade-related test expectation mismatch: integer party schema versions still fail, but with an application-level unsupported-version diagnostic instead of version.type.
• Configuration race tests passed with that expectation adjusted in a temporary test overlay.
• Three CLI cases failed on both v0.1.2 and v0.3.0 because they assumed no default pipeline configuration was installed. These are pre-existing isolation gaps, not demonstrated ConfigKit regressions. Other packages passed the ordinary suite; the overall suite was not green.

Upstream references are the tagged docs/releases/v0.2.0.md and docs/releases/v0.3.0.md in the ConfigKit repository. Narratio's current owners remain the configuration reference, configuration internals, and architecture policy.

Required Changes

Released dependency

Pin gitea.maximumdirect.net/eric/ConfigKit v0.3.0 in go.mod, refresh go.sum, and retain a tidy module graph. Do not introduce local replacements, a sibling-checkout requirement, vendoring, or workspace-only dependency wiring. Production code must use only ConfigKit's public root package.

Party-version regression coverage

Update TestParsePartyCanonicalRejectsInvalidDocuments in internal/config/party_test.go so that integer schema_version: 1 is tested as an unsupported version rather than a ConfigKit type error. Preserve the required narratio.party.v1 identifier: the upgrade must not make integer party versions valid or introduce coercion for ordinary string fields.

Keep assertions focused on rejection and the unsupported-version meaning, not exact diagnostic prose. Retain meaningful coverage for malformed version input and strict ordinary-field decoding without duplicating ConfigKit's parser suite.

Host-independent CLI tests

Remove installed-configuration assumptions from these failing cases:

• TestExecuteAnalyzeMissingConfigUsesRunStageLoadingPath and TestExecutePublishMissingConfigUsesRunStageLoadingPath in internal/app/analyze_artifacts_commands_test.go;
• the run missing config uses defaults case of TestExecuteMissingRequiredFlags in internal/app/commands_test.go.

Use the existing command dependency/discovery boundaries where possible, or a narrow invocation-local seam if needed, to exercise missing-config behavior against controlled temporary locations. Preserve coverage that these commands route through ordinary configuration discovery. Inspect adjacent missing-config tests for the same assumption and repair affected cases within this boundary.

Tests must neither read operator credentials/configuration nor create, rename, delete, or require absence of files in real system configuration locations. Avoid process-global search-path mutation and do not change production search order merely to satisfy tests. Follow the testing policy when selecting the narrowest durable seam.

Documentation

Update current documentation only where adoption changes an actual claim. Record the dependency upgrade and diagnostic adjustment in the applicable unreleased release note; do not rewrite already-published historical notes. No operator configuration migration is expected. If no unreleased note exists, retain the summary in the implementation completion record until a separate release task selects a version; published notes remain immutable.

Preserved Behavior and Non-Goals

• Pipeline paths remain relative to the root pipeline file, not the importing file that declares a value. Do not adopt the new resolver provenance APIs merely because they are available.
• Imports, profile selection, explicit-null/default semantics, unique base artifact ownership, party expansion, dependency inference, and safe show/diff/source/catalog projections retain their existing behavior.
• Resolve only effective credential references. Profiles can replace or remove unused base credentials, and hidden duplicate definitions remain rejected through historical metadata without independently loading the base.
• Secret bootstrap, redaction, runtime adapter delivery, and resume evidence remain unchanged. The separate Notarius credential-forwarding proposal is not implemented by this upgrade.
• No new schema versions, CLI flags, path policy, supported platforms, Go baseline change, or upstream modifications are required.
• No performance improvement is claimed. The primary benefit is maintaining compatibility with the current upstream library and its explicit public API.

Validation and Target End State

The released dependency works without consumer production-code migration except any narrowly justified testability wiring. Existing valid configurations keep their meaning, and integer party versions remain invalid with a truthful unsupported-version diagnostic. Missing-config tests pass regardless of host installation state.

Acceptance requires the full validation set in the development guide: ordinary and race tests, vet, build, documentation links, and maintained examples. Verify module tidiness and all three Narratio cross-build targets. Recheck profile credential replacement/null removal, hidden duplicate ownership, provenance, and credential-safe inspection through existing regression coverage; add tests only for uncovered meaningful risks. Validation must not rely on skipped failures or temporary test overlays.

Before publication, run the normal release-candidate procedure. Cross-compilation is not native macOS runtime evidence. Tagging, pushing, and release publication are separate actions, not part of implementing this roadmap.