134 lines
7.9 KiB
Markdown
134 lines
7.9 KiB
Markdown
# ConfigKit v0.5.0 Adoption Roadmap
|
|
|
|
**Last updated:** 2026-10-03
|
|
|
|
**Status:** Complete. The implementation and tests are committed through
|
|
`8175ed8`. Final documentation and example changes were included in the full
|
|
build, test, example-validation, and local-link checks before the documentation
|
|
completion commit. The [historical implementation plan](https://gitea.maximumdirect.net/eric/audita/src/commit/b31955fc97adec707b4e5f9a1b0c43c4cbc66750/docs/roadmap/implementation.md)
|
|
records the ordered work and verification.
|
|
|
|
## Purpose and Baseline
|
|
|
|
Adopt ConfigKit v0.5.0 as an independently reviewable step before PromptKit
|
|
v0.12.0. Use the library's configuration and inheritance conventions while
|
|
preserving Audita's domain ownership and existing operator workflows.
|
|
|
|
At the reviewed Audita revision `6ae1d7cd5f548b26de5787372d3f2249eaa4757d`,
|
|
[go.mod](../../go.mod) selects ConfigKit v0.4.2, PromptKit v0.11.2, and Go
|
|
1.25.5. ConfigKit already owns loading, presence, secret resolution, and
|
|
configuration inspection. Audita's `internal/core/config` supplies typed
|
|
settings, defaults, derived values, and domain validation; `internal/cli`
|
|
selects files, overlays, and explicit overrides. The
|
|
[configuration contract](../config.md) and [CLI contract](../cli.md) own the
|
|
implemented behavior.
|
|
|
|
The reviewed upstream release is
|
|
[ConfigKit v0.5.0](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/releases/v0.5.0.md),
|
|
commit `dc09959cca4e105f49ec316c6d4ba585bd2340bd`. It adds layered underlays,
|
|
caller-owned filesystem sources, mapping sources, source resource contexts, and
|
|
built-in sibling inheritance. The Go minimum and YAML dependency do not change.
|
|
Ordinary `Load` remains available; adopting `LoadLayered` is optional.
|
|
|
|
This roadmap supersedes the completed original adoption plan at this path.
|
|
The [historical roadmap](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md)
|
|
records that earlier migration. Its coordinated breaking-refactor instructions
|
|
and release target do not govern this incremental upgrade.
|
|
|
|
## Target End State
|
|
|
|
- Audita uses the released ConfigKit v0.5.0 module, with no local replacement.
|
|
PromptKit stays at v0.11.2 throughout this adoption unit.
|
|
- Configuration retains the current file-selection, overlay, explicit-override,
|
|
resolution, and validation flow, subject to the reserved-key compatibility
|
|
impact described below. Retain the application schema version, CLI interface,
|
|
and main-file-relative resource rules defined in the current contracts.
|
|
- Application configuration can use ConfigKit's native sibling `extends`
|
|
relationships. Audita does not implement a second inheritance resolver,
|
|
special backend-only syntax, or an opt-in switch around the library feature.
|
|
- Inherited values participate in presence-aware defaults, domain validation,
|
|
secret resolution, and safe inspection just like other effective input.
|
|
In particular, inherited backend settings must not be overwritten merely
|
|
because they were not written directly on the child.
|
|
- Effective settings and explanations remain useful and secret-safe when
|
|
values are inherited. Preserve existing inspection fields and add compact,
|
|
value-free inheritance evidence from ConfigKit's metadata rather than
|
|
reconstructing provenance from YAML.
|
|
- Canonical documentation and a maintained example explain the adopted
|
|
inheritance behavior. Attribution identifies the exact new upstream source.
|
|
|
|
The upstream [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/tag/v0.5.0/docs/config.md#sibling-inheritance)
|
|
owns generic inheritance mechanics. The integration must account for three
|
|
consequences: `extends` is reserved automatically throughout input mappings;
|
|
relationships resolve after source precedence and before typed decoding; and
|
|
inherited zero, false, empty, or null values count as explicit input. An inherited
|
|
value still has to satisfy Audita's field-specific rules. Parent definitions
|
|
also undergo ordinary application validation; inheritance does not introduce
|
|
abstract, validation-exempt backend entries.
|
|
|
|
## Scope and Adoption Boundary
|
|
|
|
Keep the existing `Load` integration unless implementation reveals a concrete
|
|
need to change it. Source-backed defaults, additional operator underlay tiers,
|
|
imports, and source-relative reinterpretation of application paths are outside
|
|
this feature. Their availability upstream does not require expanding Audita's
|
|
configuration surface. Imports and secret-directory bootstrap retain their
|
|
current disabled state.
|
|
|
|
ConfigKit inheritance applies to Audita configuration in this step. PromptKit
|
|
profile formats, profile inheritance, engine construction, embedded prompts,
|
|
and backend catalogs remain governed by the existing PromptKit integration.
|
|
There is no application-owned translation of profile documents in this work.
|
|
|
|
This is an independent ConfigKit adoption ahead of the planned PromptKit
|
|
migration. A separate public release between the two units is optional.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- The released ConfigKit v0.5.0 dependency and exact source attribution are
|
|
adopted; PromptKit remains at v0.11.2 with its existing catalogs.
|
|
- Native inheritance preserves effective endpoints, capacity, explicit zero
|
|
queue capacity, child overrides, and surviving credential references through
|
|
Audita's loading, resolution, and validation boundary.
|
|
- Selected overlays and explicit overrides retain their precedence; omitted
|
|
validation-role selection still derives from the final proposal selection.
|
|
- Null can remove a child's credential while surviving references on parents
|
|
and other unselected backends still follow the existing credential contract.
|
|
- Selected roles use inherited backend settings and share its configured
|
|
capacity under the existing PromptKit runtime contract.
|
|
- Effective settings remain redacted, and both CLI explanations and debug
|
|
configuration origins expose compact, value-free inheritance evidence while
|
|
retaining existing fields and application-derived explanations.
|
|
- A maintained complete example and canonical documentation describe native
|
|
inheritance, its field-validation implications, and the reserved-key
|
|
compatibility impact. Existing workflows and applicable offline checks pass.
|
|
|
|
## Completion and Release Treatment
|
|
|
|
Adoption is complete when the released dependency is pinned, existing workflows
|
|
pass, representative inheritance works through loading and runtime wiring,
|
|
inspection includes value-free inheritance evidence and remains secret-safe,
|
|
and the example, canonical docs, and attribution match the implementation. No
|
|
PromptKit migration or provider behavior change is required to close this unit.
|
|
|
|
Release classification remains provisional. A minor release would be appropriate
|
|
for a backward-compatible addition, but the newly reserved `extends` key can
|
|
invalidate currently valid application configuration. For example, Audita
|
|
currently permits a backend literally named `extends`; ConfigKit v0.5.0 treats
|
|
that mapping key as an inheritance directive rather than a backend ID. Do not
|
|
promise blanket compatibility or settle on a minor release until the final
|
|
compatibility review resolves this impact under the
|
|
[release policy](../policy/release.md). Describe any required migration in the
|
|
canonical documentation and release notes when the upgrade ships. Do not select
|
|
or publish a release as part of roadmap preparation. A later PromptKit
|
|
migration's profile-format compatibility decision belongs to that separate
|
|
feature.
|
|
|
|
## Selected Overlays for Testing
|
|
|
|
This heading preserves links from historical adoption documents. The original
|
|
[overlay plan](https://gitea.maximumdirect.net/eric/audita/src/commit/6ae1d7cd5f548b26de5787372d3f2249eaa4757d/docs/roadmap/configkit.md#selected-overlays-for-testing)
|
|
is historical; current overlay behavior belongs to [configuration](../config.md).
|
|
This upgrade preserves that workflow and adds native ConfigKit inheritance
|
|
without reviving the earlier combined migration plan.
|