Plan the ConfigKit upgrade and test isolation

docs/roadmap/configkit-v0.3.0.md

@@ -0,0 +1,149 @@
+# Adopt ConfigKit v0.3.0
+
+Status: Accepted — implementation pending
+
+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.