112 lines
6.4 KiB
Markdown
112 lines
6.4 KiB
Markdown
# ConfigKit Adoption Outline
|
|
|
|
**Updated:** 2026-11-07
|
|
|
|
**Status:** Initial outline. The [master roadmap](library-adoption.md) owns the
|
|
agreed adoption policy, reviewed versions, shared sequencing, and completion.
|
|
|
|
## Baseline and Target
|
|
|
|
Audita currently uses ConfigKit v0.7.1 through its former import path. Its
|
|
[configuration contract](../config.md) describes application file discovery,
|
|
overlays, defaults, inheritance, secret references, and explicit CLI settings.
|
|
|
|
Adopt ConfigKit v1.1.0 and its stable public API as the configuration foundation.
|
|
Use its native loading, discovery, presence, composition, resolution, diagnostics,
|
|
and inspection mechanisms. Audita supplies domain types and validation; retain
|
|
custom loading behavior only for a demonstrated domain requirement. Standard
|
|
operator access is implemented through the [CommandKit outline](commandkit.md).
|
|
|
|
The main upstream references are the
|
|
[v1 API migration](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.0.0.md),
|
|
[v1.1 release](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/releases/v1.1.0.md),
|
|
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/191015e289d7f2b91abb9fdd9c4f2f5cf75b4de9/docs/config.md).
|
|
|
|
## Agreed Direction and Migration Work
|
|
|
|
1. Move imports to `go.maximumdirect.net/configkit` with the coordinated
|
|
PromptKit cutover. Raise the toolchain as specified by the master roadmap.
|
|
Replace `Resolution.Record` uses with the appropriate dedicated recording
|
|
method; review affected metadata and diagnostics APIs, not only compilation.
|
|
Relevant renamed concepts include `EntryInfo`, `Sensitive`, `LayerMain`,
|
|
version evidence, and destination fallback. Typed `Secret` and its field tag
|
|
retain their spelling.
|
|
2. Adopt the native lifecycle: source composition and inheritance, typed decoding,
|
|
explicit CLI assignments, then application resolution and validation. CLI
|
|
assignments do not repair earlier decoding failures, alter inheritance
|
|
relationships, or propagate parent edits through already resolved children.
|
|
Update the current loading-order explanation and realistic integration tests.
|
|
3. Migrate genuine source-root control blocks to `config:` where present.
|
|
Distinguish application schema versions from source version evidence; do not
|
|
impose headers on every fragment merely because the API supports them.
|
|
4. Use identified collections where records have meaningful identity. ConfigKit
|
|
upsert replaces matching records in full; inspection follows registered
|
|
identities through movement, while list diffs remain atomic. Preserve ordinary
|
|
ordered/repeated `pipeline.modules` entries and empty-pipeline semantics:
|
|
these express Audita domain behavior, so uniqueness/upsert is inappropriate.
|
|
5. Integrate native source discovery and standard inspection instead of retaining
|
|
equivalent private infrastructure. Adopt source diagnostics, explanation,
|
|
history, normalization, and safe effective output through ckconfig. Account
|
|
for the provenance label changing from `base` to `main`.
|
|
6. Reconcile application configuration fields with PromptKit's native resource
|
|
ownership. Do not force PromptKit backend duplication into the Audita schema
|
|
simply to preserve today's layout. The [PromptKit outline](promptkit.md)
|
|
owns that boundary decision; coordinate any resulting application schema and
|
|
credential migration here.
|
|
|
|
## Documentation and Acceptance
|
|
|
|
Update [configuration](../config.md), relevant [CLI](../cli.md) behavior,
|
|
[change recipes](../internal/cli-config.md), maintained examples, migration
|
|
guidance, and attribution as the corresponding behavior lands. Public docs
|
|
remain descriptions of implemented behavior until then.
|
|
|
|
Acceptance should demonstrate native file selection, source composition,
|
|
overlays, explicit false/zero/empty values, derived settings, and secret handling
|
|
through real ConfigKit loading. Cover the changed inheritance/assignment order,
|
|
source errors, useful failure evidence, and secret-safe inspection. Reuse upstream
|
|
coverage for generic grammar rather than copying its test matrix. Verify the
|
|
standard ckconfig surface through the assembled CLI and run the full application
|
|
suite at the coordinated migration boundary.
|
|
|
|
The earlier passing configuration suite is useful baseline evidence, not proof
|
|
that operators see unchanged semantics. Native semantics and clear migration are
|
|
the target; preserving incidental old output or validation order is not.
|
|
|
|
## Upstream Requests
|
|
|
|
No ConfigKit change request is currently identified. Prefer adapting Audita to
|
|
its stable supported API. Record any necessary exception with a concrete domain
|
|
requirement and the smallest integration boundary that satisfies it.
|
|
|
|
## Open Decisions
|
|
|
|
### Discovery Locations and Import Selection
|
|
|
|
**Recommendation:** replace custom discovery with ConfigKit's supported search
|
|
API, then select documented paths and import options based on suite conventions.
|
|
Evaluate the current system-only search and disabled imports rather than carrying
|
|
them forward automatically. Native API adoption is agreed; the exact search
|
|
locations and import defaults still need selection before changing operator
|
|
behavior. Preserve explicit-path error evidence and distinguish optional from
|
|
required imports using native semantics.
|
|
|
|
**Alternative:** configure the native API with today's two system locations and
|
|
imports disabled. This eases installation migration and remains supported, but
|
|
should be retained only if deployment requirements justify it; historical behavior
|
|
alone does not satisfy the suite-alignment objective. Conversely, enabling all
|
|
possible searches/imports without a selected convention can load unintended
|
|
sources and is not required for full API adoption.
|
|
|
|
### Application Schema Version
|
|
|
|
**Recommendation:** retain `version: 2` only if the resulting application fields
|
|
and meaning remain coherent after PromptKit ownership is settled. Do not confuse
|
|
it with the library version or PromptKit's source header. This avoids meaningless
|
|
schema churn while allowing deliberate field migration.
|
|
|
|
**Alternative:** introduce a new application schema version if backend or
|
|
credential ownership changes make existing files misleading. It provides a clear
|
|
migration boundary, at the cost of updating files and guidance. Decide from the
|
|
final schema, not from dependency version numbers alone.
|