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

# 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.