Align adoption plans with main-relative loading releases

This commit is contained in:
2026-11-10 15:49:05 +00:00
parent 0c7622375f
commit 40420a217a
6 changed files with 187 additions and 119 deletions

View File

@@ -1,6 +1,6 @@
# ConfigKit Adoption Outline
**Updated:** 2026-11-09
**Updated:** 2026-11-10
**Status:** Target decisions resolved; implementation pending. The
[master roadmap](library-adoption.md) owns shared policy and dependency selection;
@@ -12,16 +12,16 @@ 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.
Adopt ConfigKit v1.2.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).
[v1 API migration](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.0.0.md),
[v1.2 release](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/releases/v1.2.0.md),
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
## Agreed Direction and Migration Work
@@ -69,10 +69,32 @@ operators use `required: true` for essential inputs. Invalid declarations,
unreadable selected files, and composition conflicts retain native errors.
The PromptKit outline owns [automatic prompt sources](promptkit.md#automatic-prompt-sources--resolved).
Those resource imports compose in the engine's operator underlay independently
of main application-file selection, using the same native import semantics.
Keep application configuration discovery and PromptKit resource acquisition
distinct while sharing their supported ConfigKit mechanisms.
Those imports compose in a separate engine underlay, using the selected
application main's recorded context under the shared rule below. Keep application
and PromptKit schemas separate while sharing native loading mechanisms.
### Companion Resource Base and Overlays — Resolved
Use the selected main application configuration file's directory as the lookup
base for automatic glossary and prompt companions and named overlays. This applies
to both explicit `--config` and native discovery. Follow ConfigKit's resolved
context: host symlinks use the canonical target directory; a wider containment
root does not move the lookup base. Transitive imports retain their declaring
file's native context, and embedded inputs retain their own filesystem namespace.
For application-owned glossary import declarations, use a non-file underlay
`Input` with `Imports: true` and `MainRelative: configkit.MainRelative()`.
ConfigKit binds it during the single `LoadLayered` call. PromptKit's separate
loader uses the application result's recorded main context, as specified in its
[automatic source contract](promptkit.md#automatic-prompt-sources--resolved).
Do not duplicate main discovery or perform a preliminary full configuration load.
Select native `overlays/<name>.yml` beside the main file. Let `LoadLayered` derive
its overlay context; do not supply an invocation-directory `OverlayFilesystem`
or `OverlayFallback`. No overlay selection loads no overlay; an active selection
requires a usable context and the named file. Aggregate `overlays.yml` is deferred
upstream and is outside this adoption. ConfigKit v1.2.0 satisfies the upstream
API requirement for this decision.
### No Configuration File Found — Resolved
@@ -87,11 +109,14 @@ mechanisms. Report missing command-specific settings clearly; do not invent an
implicit model or profile selection to make incomplete execution settings pass.
Inspection must accurately show that no main file was selected.
Define filesystem context explicitly where overlays or relative resource inputs
need it; do not infer a base from unsuccessful search candidates. Preserve the
native absent-main lifecycle instead of manufacturing a placeholder file or
source record. Explicit-file errors and failures loading a selected discovered
file remain terminal.
When no main context exists, skip automatic optional glossary and prompt
companion imports; retain embedded defaults and explicitly supplied settings.
Do not install a working-directory fallback or infer a base from unsuccessful
search candidates. Use ConfigKit's native absent-base behavior for the glossary
underlay and omit automatic operator prompt inputs in the separate engine load.
An explicitly selected overlay without a usable context fails. Preserve genuine
absent-main evidence rather than manufacturing a placeholder source. Explicit
file errors and failures loading a selected discovered file remain terminal.
### Target Boundaries
@@ -106,7 +131,7 @@ propagate parent edits through resolved children. Native source provenance uses
PromptKit [owns backend and credential resources](promptkit.md#backend-and-credential-ownership--resolved).
Audita's v3 schema has no separate backend or LLM credential registry. Native
[automatic resource sources](promptkit.md#automatic-prompt-sources--resolved)
remain independent of main application-file discovery.
use the application main context while retaining their separate schema and tiers.
The v3 schema includes the glossary roadmap's [scope and inheritance model](glossary-stages.md#configuration-scope--resolved),
[typed handoff](glossary-stages.md#list-inputs-and-configuration-handoff--resolved),
@@ -139,8 +164,11 @@ integration. Verify that discovery exhaustion permits inspection and sufficientl
configured processing, while incomplete processing reports its missing inputs.
Cover absent-main provenance and filesystem context for selected overlays or
relative resources without weakening explicit-file error behavior.
Verify that application main-file selection and exhaustion preserve the separate
automatic PromptKit source context and precedence specified in its outline.
Verify that explicit and discovered mains outside the working directory anchor
companions and overlays beside the selected file. Cover a broader containment
root, native source evidence, and absent-main skipping without a working-directory
fallback. Verify PromptKit receives the same application context while retaining
its separate schema and precedence, through processing and inspection alike.
Verify acceptance of the final version-3 schema and rejection of obsolete
application versions. Check that no-main-file loading uses version-3 defaults,
@@ -153,6 +181,7 @@ 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
The main-relative companion/overlay request is fulfilled by ConfigKit v1.2.0.
No further 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.