# Adopt ConfigKit v0.3.0 Status: Implemented — 2026-09-16 Execution order and stage acceptance checks belong to the [implementation plan](implementation.md). 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](../config.md), [configuration internals](../internal/configuration.md), and [architecture policy](../policy/architecture.md). ## 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](../policy/testing.md) 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](notarius-credential-forwarding.md) 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](../development.md): 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](../release.md). Cross-compilation is not native macOS runtime evidence. Tagging, pushing, and release publication are separate actions, not part of implementing this roadmap.