Document native library adoption plans
This commit is contained in:
111
docs/roadmap/configkit.md
Normal file
111
docs/roadmap/configkit.md
Normal file
@@ -0,0 +1,111 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user