150 lines
8.4 KiB
Markdown
150 lines
8.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
|
|
|
|
### Discovery Locations and Import Selection — Resolved
|
|
|
|
An explicit `--config` selects exactly that file. A missing, inaccessible, or
|
|
invalid explicit file is an error; do not fall back to discovery.
|
|
|
|
Without an explicit file, search in this order using ConfigKit's native presets
|
|
and filename rules with application name `audita`:
|
|
|
|
1. `WorkingDirectory` for project-local configuration.
|
|
2. `UserConfigDirectory` for personal configuration.
|
|
3. `UnixSystemDirectories` for system configuration.
|
|
|
|
Select the first matching file. Do not merge every discovered file or continue
|
|
searching after a selected file fails to load. Additional composition is explicit
|
|
through native imports and overlays. Recommend explicit configuration paths for
|
|
automation so its selection does not depend on the working directory.
|
|
|
|
Enable native imports for operator configuration sources, retaining upstream
|
|
defaults and declaration-level controls. Imports compose peer documents, not
|
|
higher-priority override layers. Missing optional imports may be absent;
|
|
operators use `required: true` for essential inputs. Invalid declarations,
|
|
unreadable selected files, and composition conflicts retain native errors.
|
|
|
|
Behavior when automatic discovery finds no file remains a separate open decision
|
|
below. This does not reopen the selected search order or import support.
|
|
|
|
### 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. Apply the resolved [PromptKit ownership decision](promptkit.md#backend-and-credential-ownership--resolved):
|
|
remove Audita's separate backend mapping and LLM credential references from
|
|
its application schema. Native PromptKit resources own those settings and
|
|
their resolution. Coordinate the hard cutover and examples here, using the
|
|
resolved discovery and import policy above.
|
|
|
|
## 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.
|
|
|
|
Check explicit-file selection without fallback, native working/user/system
|
|
search precedence, and terminal errors for a selected invalid file. Verify
|
|
optional and required imports and peer-composition errors through Audita's
|
|
integration. Cover discovery exhaustion after its behavior is selected below.
|
|
|
|
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
|
|
|
|
### No Configuration File Found
|
|
|
|
**Recommendation:** use ConfigKit's optional-search behavior: continue with
|
|
embedded defaults, underlays, and explicit CLI settings, then validate what the
|
|
requested command needs. A missing main file alone should not prevent resource
|
|
inspection or execution whose required inputs are otherwise supplied. Do not
|
|
invent an implicit model/profile choice to make incomplete execution settings
|
|
pass validation. Define filesystem context explicitly where overlays or relative
|
|
resource inputs need it; do not infer a base from unsuccessful search candidates.
|
|
|
|
This follows the native absent-main lifecycle and supports lightweight command
|
|
invocations. It requires clear errors for missing command-specific inputs and
|
|
inspection that accurately shows that no main file was selected.
|
|
|
|
**Alternative:** require a discovered configuration file for configuration-dependent
|
|
commands, while keeping help/version independent. This gives deployments a
|
|
mandatory configuration anchor, but rejects otherwise sufficient defaults and
|
|
CLI settings and adds a requirement without an identified domain need. Explicit
|
|
file errors remain terminal under either choice.
|
|
|
|
### Application Schema Version
|
|
|
|
**Recommendation:** design the application schema around the target ownership
|
|
boundaries, then choose its version to describe that contract. Keeping `version: 2`
|
|
is reasonable only if its meaning remains coherent; compatibility with existing
|
|
files is not a selection criterion. Do not confuse the application schema version
|
|
with the library version or PromptKit's source header.
|
|
|
|
**Alternative:** introduce a new application schema version if backend or
|
|
credential ownership changes make existing files misleading. It provides a clear
|
|
migration boundary; the version alone does not explain the new contract, so
|
|
hard-cutover guidance still needs to describe it. Decide from the final schema,
|
|
not from dependency version numbers alone, and do not add legacy-schema support.
|