Document ConfigKit integration and dependency attribution

This commit is contained in:
2026-11-17 20:58:22 +00:00
parent 244f258413
commit 74e0f454e9
8 changed files with 65 additions and 27 deletions

View File

@@ -35,8 +35,11 @@ options before dispatch so that a missing production dependency fails as a
command error rather than reaching execution.
Commands that need configuration use one shared ConfigKit-backed loader. The
CLI discovers the file, passes the requested overlay and only explicit
configuration-valued run overrides, and receives a **LoadedConfig**. The
CLI constructs an exclusive file source for an explicit flag or environment
selection, or a native required search source, then passes it to `LoadSource`
with the requested overlay and only explicit configuration-valued run overrides.
It receives a **LoadedConfig** and uses its retained main-source path for
invocation provenance without a second search. The
configured discovery and precedence contract is in
[Configuration](../config.md), while the loading and resolution mechanics are
in [Configuration Internals](configuration.md).

View File

@@ -15,12 +15,12 @@ runs anything.
| Boundary | Inputs | Outputs | Does not own |
| --- | --- | --- | --- |
| Loading | Selected file path, overlay, overrides, and invocation directory | **LoadedConfig** with ConfigKit inspection metadata and a populated **Config** | Choosing the file path or reporting a command result. |
| Loading | Selected ConfigKit source, overlay, overrides, and invocation directory | **LoadedConfig** with ConfigKit inspection metadata and a populated **Config** | Choosing the source or reporting a command result. |
| Validation | **Config** | Structural configuration errors with pipeline, lane, or binding context | Module availability, capabilities, or construction. |
| Resolution | Valid **Config**, selected pipeline and lanes, runtime reference changes, LLM override, and module catalog | **EffectiveConfig** with a **ResolvedPipeline** | Materializing reference bytes, preparing modules, execution, or filesystem state. |
| Inspection | **LoadedConfig** and an optional JSON Pointer | Redacted effective YAML or explanation text | Pipeline selection, module preparation, or provider work. |
The CLI discovers a configuration file, invokes this package, and supplies the
The CLI describes the selected source, invokes this package, and supplies the
result to the framework. Configuration never reads an input file, constructs a
module, or creates output, cache, or debug paths. Those responsibilities remain
at their respective [CLI](cli.md), [pipeline](pipeline.md), and
@@ -28,11 +28,16 @@ at their respective [CLI](cli.md), [pipeline](pipeline.md), and
## Loading And Validation
ConfigKit composes the selected root, imports, optional selected overlay, and
explicit CLI overrides in precedence order, then expands native sibling
inheritance before typed decoding. The document definition supplies typed
`Load` selects an exclusive file; `LoadSource` accepts the CLI's source and
enables imports through the same definition and callback path. ConfigKit composes
the main input, imports, and optional overlay, then expands native inheritance
before typed decoding. Explicit CLI assignments follow decoding and precede
application resolution. The document definition supplies typed
defaults and structural validation; Notarius's recorded resolution changes
normalize configured paths after decode. Path normalization follows the source
normalize configured paths after decode. Reference paths resolve before key
normalization moves their source coordinates. Ordinary list leaf edits are
recorded at the leaf; a changed step identity requires a covering list record.
Actual map-key moves retain structural records. Path normalization follows the source
of the surviving value, including a value copied through inheritance, rather
than the inheritance directive's location. Inherited input remains explicit
for presence-sensitive behavior, including zero, false, and empty values;
@@ -47,7 +52,8 @@ for the operator syntax and field rules. Only
variables do not participate in loading. Version 5 decoding rejects scalar
module bindings and scalar external references. ConfigKit retains redacted,
historical inspection metadata while **LoadedConfig** keeps that implementation
detail private behind effective and explanation writers.
detail private behind effective and explanation writers. `MainSourcePath` reads
the non-imported main file from retained sources, and runtime conversion stays detached.
**Config.Validate** checks configuration-only invariants before resolution. It
rejects incompatible profile sources, invalid state-surface values, unsupported

View File

@@ -98,6 +98,10 @@ definition superseded by a later overlay. The D&D registrar contributes its
by default. A profile selecting `backend: local` requires the optional local
registration.
This PromptKit integration uses the old-path ConfigKit v0.5.0 types exposed by
PromptKit v0.12.0. Application configuration uses the distinct new-path
ConfigKit package; those named types do not cross the adapter boundary.
Each engine captures its definitions at construction. A later source-file edit
does not mutate an existing engine; constructing a new engine captures the
updated view. Before execution, the adapter computes one immutable,