commandkit/docs/roadmap/configkit-v1.1.0.md

# ConfigKit v1.1.0 adoption

Status: adoption scope selected; implementation has not begun. This roadmap
defines the embedded `ckconfig` dependency and source-report target.
[Selected scope decisions](#selected-scope-decisions) distinguish adoption from
deferred extensions. The [implementation plan](implementation.md) owns stage
order, concrete changes, and validation steps.

## Purpose and authority

Adopt `go.maximumdirect.net/configkit v1.1.0` and expose its capabilities through
CommandKit's existing configuration commands in a neutral, consistent way.
ConfigKit owns configuration loading, composition, resolution, inspection, and
their semantics. CommandKit owns command selection, coordination, presentation,
and invocation outcomes. Adapt upstream capabilities faithfully, using current
upstream terminology, without adding independent guarantees or commentary
qualifying upstream limitations.

This follows the clarified integration goal and the existing
[architecture policy](../policy/architecture.md#backend-and-library-integration).
The [agent](../policy/agents.md), [testing](../policy/testing.md),
[documentation](../policy/documentation.md), [release](../policy/release.md), and
[OSS](../policy/oss.md) policies govern implementation. This roadmap records
the selected target; current contracts remain in GoDoc, the
[CLI reference](../cli.md), and the [consumer guide](../consumers/guide.md) until
implementation lands.

## Current baseline and review evidence

Initial review revision: `60841227b7e2928d3fefd3326f0e3f4694f41e6d`.
API coverage follow-up revision: `7a9e3a1f7cdd0475f06a63ce0aababefe08651bc`;
library code and module selections are unchanged between these revisions.
The completed [dependency alignment roadmap](integration-dependency-alignment.md)
records the preceding vanity migration and releases.

| Component | Current selection |
| --- | --- |
| Core | `go.maximumdirect.net/commandkit v0.3.0`; Go 1.26.0 minimum |
| ckconfig | `go.maximumdirect.net/ckconfig v0.2.0`; Go 1.26.0 minimum |
| ckconfig dependencies | Core v0.3.0, `gitea.maximumdirect.net/eric/ConfigKit v0.8.0`, YAML v4.0.0-rc.6 |
| ckprompt | v0.2.0; ckconfig v0.2.0, old-path ConfigKit v0.8.0 and PromptKit v0.16.0; Go 1.26.0 minimum |
| Maintainer release toolchain | Go 1.26.8, with `GOTOOLCHAIN=local` |

The ConfigKit vanity endpoint and direct Go module discovery resolve v1.1.0 to
published commit `191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9`. Its module declares
Go 1.27.0 and retains the YAML dependency and LGPL-3.0-or-later library grant.
The upstream [v1.0 migration notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md)
and [v1.1 release notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md)
describe the adopted API and behavior changes. Upgrading from v0.8.0 also crosses
the import, collection, CLI-assignment, and discovery changes documented in the
[v0.9 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.9.0.md)
and [v0.10 notes](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v0.10.0.md).

A disposable ckconfig copy passed its complete module suite and maintained
simple example tests on Go 1.27.0 after changing the dependency/import path,
minimum, two source-reader fields, and affected test APIs. This establishes that
the existing adapter structure remains suitable. It did not exercise the
proposed report-field renames, additional source evidence, or a migrated
ckprompt; final implementation still needs validation of those selected changes.

### API coverage findings

The follow-up compared the public API of the pinned v1.1.0 module with
ckconfig's provider facets, adapters, and report projections. These are gaps in
current integration coverage, not necessarily APIs newly introduced in v1.1.0.

| Capability | Current ckconfig exposure | Recommendation |
| --- | --- | --- |
| `SourceInfo.EmptyImportSelections` | Omitted from the source report. | Include in adoption; OD-2. |
| `Result.Metadata()`, `Metadata.Lookup`, and `IsExplicit` | No metadata facet in `View`; explanation reports do not expose explicit input presence. | Prioritize optional field-metadata inspection as the next functional expansion; OD-3. |
| `Metadata.HistoricalPaths` and `History` | Operators must already know a path to request an explanation; metadata history records are not exposed. | Pair path discovery and provenance history with metadata inspection; OD-3. |
| `LoadError.Sources()` and `Source(id)` | Acquired sources support diagnostic context, but `config sources` returns before reporting an inventory on acquisition failure. | Consider failed-load source inspection separately; OD-4. |
| Full `Difference` records | The Go comparison provider returns native records; the CLI reduces them to additions, right-side changes, and deletion paths. | Consider an additional detailed comparison report; OD-5. |
| Structured `Diagnostic` records | Native writers present diagnostic content; there is no structured native diagnostic report. | Lower-priority candidate, coordinated with shared reporting; OD-6. |

The upstream [metadata API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/metadata.go),
[source and diagnostic records](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/records.go),
[load-error API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/diagnostic.go),
and [comparison API](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/diff.go)
own the returned evidence and its semantics.

The current explanation projection covers every field of v1.1.0's
`Explanation`: effective and historical snapshots, origin and inheritance,
reasons, dependencies, and secret-reference names. Improved list-history
behavior can flow through that existing adapter. Metadata queries add distinct
information: explicitness and null state from `FieldInfo`, observed paths
including removed ones, and `Change` records with previous origins and operation
paths. They need not replace the value-oriented explanation report.

`Result.Source(id)` is a convenient lookup of records already available through
the source inventory. A source-ID filter is a possible usability refinement;
it does not inherently require another command or a required lookup method on
every custom source provider. Discovery, import defaults, collection identities,
and field-level resolution recording fit the application-supplied loader.
Source resource contexts and explicit secrets-directory bootstrap primarily
serve application loading and startup; there is no immediate recommendation to
add standard inspection operations for them. A consumer need could motivate
later presentation of their upstream results.

## Targeted end state

### Dependency and toolchain

The [ckconfig module](../../integrations/ckconfig/go.mod) requires
`go.maximumdirect.net/configkit v1.1.0`, and its production code, tests, and
maintained example use that import identity. Raise its consumer minimum to
Go 1.27.0. Retain its core v0.3.0 requirement unless implementation identifies
a concrete need for a newer core API. Core remains independent of ConfigKit
and retains its own Go minimum.

Use a Go 1.27 toolchain for ckconfig dependency preparation and validation.
Update the [maintainer procedure](../release.md#release-toolchain) to select an
available Go 1.27 release and distinguish the per-module consumer minimums.
The existing host-native, workspace-off launcher can use that toolchain without
a new toolchain-selection mechanism.

### Faithful adaptation and reports

Retain the existing scope, loader, comparison, diagnostic, and reporting
structure. Continue using ConfigKit's public results, native rendering, and
diff APIs rather than reproducing its domain logic locally. New collection,
discovery, and resolution features can be used by application loaders through
the adopted library; they do not inherently require additional CLI flags or
CommandKit-owned loading policy.

Align the existing source report with ConfigKit's current vocabulary:

| Current API or report spelling | Target |
| --- | --- |
| `SourceInfo.DestinationUnresolved` | `SourceInfo.DestinationIsFallback` |
| `SourceInfo.VersionCheck` / `SourceVersionCheck` | `SourceInfo.VersionEvidence` / `SourceVersionEvidence` |
| Text/YAML `destination_unresolved` | `destination_is_fallback` |
| Text/YAML `version_check` | `version_evidence` |
| Native main layer value `base` | Native main layer value `main` |

Update DTOs and both report formats together. Preserve the upstream evidence
and its supported presence, null, location, ordering, and redaction information
through adaptation. Use the upstream terms directly in help and documentation;
link to the owning inspection contract for their semantics. Describe the report
migration plainly in the release note. The target uses the new field names
without duplicate legacy report fields.

Include `EmptyImportSelections` as `empty_import_selections` in both text and
YAML source reports under OD-2. Project each declaration path, location, and
native selector in the returned record order. Emit `empty_import_selections: []`
when there are no records. These are planned report changes; update the owning
CLI contract when implemented.

### Deferred inspection expansion

Metadata inspection and path discovery are the next functional work proposed
after adoption (OD-3). Failed-load source inventory, detailed comparison,
and structured diagnostics remain separate later proposals (OD-4 through OD-6).
The [configuration inspection extensions](deferred.md#configuration-inspection-extensions)
record owns their proposed capabilities and design considerations. None is part
of this adoption scope or a new requirement on existing providers.

### Consumer migration and module coordination

Public ckconfig signatures expose ConfigKit types, so switching import identity
requires consumers to migrate the ConfigKit values they pass across those
boundaries. Use the adopted upstream API names in maintained consumers and
fixtures. Known test changes include `Definition.Secret` to `Sensitive` and
`Resolution.Record(..., ChangeNormalization, ...)` to `RecordNormalization`.
Review other removed pre-v1 symbols where actually used.

Migration guidance should link to upstream for source-root `configkit` controls
becoming `config`, `optional` becoming `required` with changed defaults,
identified-collection registrations and operations, and CLI-assignment ordering.
Change affected maintained fixtures when present. Application configuration and
validation choices remain application-owned; CommandKit does not introduce a
compatibility loader or impose new configuration restrictions.

ckprompt's current ConfigKit types come from the old package identity. It cannot
simply select the new ckconfig release while retaining that wiring. Its later
adoption needs a coordinated ConfigKit/PromptKit migration and review of its
own adapters and composed example. Under OD-1, prepare ckconfig independently
first and review ckprompt next. This roadmap does not select an unreviewed
PromptKit release or claim a new matched integration set.

### Independent module compatibility

Once local ckconfig uses the vanity ConfigKit types, the usual three-module
`go.work` selects it for local ckprompt as well. Until ckprompt migrates, its
old-path ConfigKit inspection and comparison types cannot satisfy the new
ckconfig contracts. This is a temporary composition mismatch, even though each
module can be validated independently against its own dependencies.

During that interval, each module's independent validation uses its own declared
dependencies with workspace discovery off. The unchanged ckprompt and composed
example retain published ckconfig v0.2.0 and their existing upstream libraries;
their success does not establish compatibility with migrated local ckconfig.
Development and consumer guidance explain the temporary mismatch. Existing
ignored workspace files remain local; restoring aligned workspace composition
belongs to the later ckprompt migration.

### Release preparation

The target candidate is ckconfig v0.3.0, with full tag
`integrations/ckconfig/v0.3.0`, subject to the existing fresh-version guards.
A pre-v1 minor fits the intentional ConfigKit type-identity, consumer-minimum,
and report-schema changes. Its checked-in note explains these changes and
consumer migration, with the usual immutable licensing footer. Current module
notices describe the selected graph and pinned upstream source.

Adoption includes release preparation, not source publication or hosted
delivery. The existing [release procedure](../release.md) owns those operations
and their separate outcomes when requested; this target adds no release gate.

## Completion evidence

Implementation is complete when ckconfig's actual module metadata and imports
select the new dependency, the selected report changes faithfully expose its
returned evidence, the module suite and maintained consumer pass independently,
and current documentation, notices, and release preparation describe that state.
Completion evidence distinguishes independent module validation from the
temporary workspace composition mismatch. OD-3 through OD-6 remain in deferred
work; their implementation is not a completion condition for adoption. A future
source release is reported separately from implementation completion.

## Selected scope decisions

These dispositions record the user's selected adoption scope.
They define the target, not implemented contracts or authorization to
publish. Deferred features still need focused API and CLI design.

| Decision | Selected disposition | Reason |
| --- | --- | --- |
| OD-1: Integration sequencing | Implement and prepare ckconfig independently first; review ckprompt next. | Independent releases keep adoption focused. Document the temporary workspace mismatch and lack of a newly aligned release pair. |
| OD-2: Empty-import evidence | Include `empty_import_selections`, with `[]` when empty, in text and YAML source reports. | Exposes existing upstream evidence alongside the other report-schema changes. |
| OD-3: Metadata and path discovery | Defer to the next functional work after adoption. | A coherent optional capability needs its own field/history report and command design. |
| OD-4: Failed-load source inventory | Defer to a separate source-inspection enhancement. | Requires source evidence on error and deliberate report/failure coordination. |
| OD-5: Detailed comparison | Defer; retain the existing reduced report during adoption. | A richer form needs a report-selection and compatibility decision. |
| OD-6: Structured diagnostics | Defer; retain native diagnostic rendering during adoption. | Coordinate machine-readable records with shared reporting and outcome delivery. |

Adoption therefore covers dependency and API migration, source-report
terminology and empty-import evidence, documentation and notices, independent
module validation, and ckconfig release preparation. Core retains its own Go
minimum. Application loaders continue to own discovery and loading policy.

Coordinating both integrations before release remains an alternative if a
matched adoption path becomes necessary. It would expand the scope to include
PromptKit review and ckprompt migration; publication would still proceed in
dependency order. The [deferred feature record](deferred.md#configuration-inspection-extensions)
retains the capability proposals and unresolved design choices for OD-3 through
OD-6, plus the possible source-ID filter.