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

@@ -1,19 +1,21 @@
# ConfigKit Integration
Notarius uses the public root package
[`gitea.maximumdirect.net/eric/ConfigKit`](https://gitea.maximumdirect.net/eric/ConfigKit)
at v0.5.0 for version 5 configuration acquisition, imports, overlays, explicit
overrides, native sibling inheritance, diagnostics, and safe inspection
rendering. ConfigKit composes source precedence and inheritance before typed
decoding; Notarius does not perform a second inheritance merge.
Notarius application configuration uses
[`go.maximumdirect.net/configkit`](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e)
at v1.2.0 for source selection, imports, overlays, identified collections,
inheritance, explicit overrides, diagnostics, and frozen inspection. Imports
and inheritance precede typed decoding; CLI assignments follow decoding and
precede application resolution. Notarius does not repeat source composition.
Notarius owns the typed document, domain defaults and validation, runtime
conversion, catalog-dependent pipeline resolution, source-aware configured
paths, and command discovery. It uses only ConfigKit's public path, result,
diagnostic, and resolution-source APIs. Upstream documentation owns general
ConfigKit semantics; [Configuration](../config.md) owns Notarius's file and
operator contract. See the pinned upstream [v0.5.0 release notes](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/releases/v0.5.0.md)
and [configuration contract](https://gitea.maximumdirect.net/eric/ConfigKit/src/commit/dc09959cca4e105f49ec316c6d4ba585bd2340bd/docs/config.md).
Notarius supplies the document schema, defaults, normalization, validation,
and the step identity registration. It owns runtime conversion and subsequent
catalog-dependent pipeline resolution. `LoadSource` receives the CLI's chosen
source; retained main-source evidence supplies the selected path. See
[Configuration](../config.md) for the operator contract and the pinned
upstream [consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/consumers/README.md)
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/docs/config.md).
See the canonical [ConfigKit attribution](../oss/attribution.md#configkit) for
its license and notices.
PromptKit v0.12.0 separately retains old-path ConfigKit v0.5.0 for its exposed
source and inspection types. The two module identities share YAML v4.0.0-rc.6;
their named types remain inside their owning boundaries. See the
[PromptKit integration](pkg-promptkit.md) and [attribution](../oss/attribution.md#configkit).

View File

@@ -166,6 +166,11 @@ implicitly supported. A dependency upgrade requires reviewing the adapter,
profile-source construction, and this compatibility statement against the
pinned upstream documentation.
PromptKit v0.12.0 exposes old-path ConfigKit v0.5.0 types and reads its operator
documents with that engine. Notarius application configuration uses the separate
new-path ConfigKit integration; the adapter does not translate source graphs
between the two.
Captured inspection describes one engine's immutable effective view. Source
edits require constructing a new engine to become visible. Effective and
explanation reports retain PromptKit's redacted configuration and source

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,

View File

@@ -18,6 +18,21 @@ License and notices: [CC BY-SA 4.0](licenses/CC-BY-SA-4.0.txt) |
## ConfigKit
Selected module: `go.maximumdirect.net/configkit` at `v1.2.0`.
Copyright (C) 2026 Eric Rakestraw
SPDX-License-Identifier: LGPL-3.0-or-later
License and notices: [LGPL 3.0](licenses/LGPL-3.0.txt) |
[GPL 3.0](licenses/GPL-3.0.txt) |
[COPYRIGHT](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/COPYRIGHT) |
[LICENSE](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e/LICENSE).
[Source](https://forge.maximumdirect.net/base-layer/configkit/src/commit/c1c7e87f2cdf77a0cbf3327831ac05578e756b9e).
## ConfigKit (old module path)
Selected module: `gitea.maximumdirect.net/eric/ConfigKit` at `v0.5.0`.
Copyright (C) 2026 Eric Rakestraw

View File

@@ -434,6 +434,12 @@ Prompt size: public references and concise consumer/workflow adjustments.
## Stage 10 — Update Integration References And Attribution
**Complete.** Internal and integration references describe the selected-source
handoff and mixed dependency ownership. Attribution records both ConfigKit
module identities against their pinned notices. Selected module and compiled
dependency inspection found no additional runtime component; upstream release
tooling remains unadopted. Module metadata was tidied after the imports landed.
Goal: make ownership and the temporary mixed graph accurately documented.
Work:

3
go.mod
View File

@@ -7,9 +7,6 @@ require (
gitea.maximumdirect.net/eric/promptkit v0.12.0
github.com/santhosh-tekuri/jsonschema/v6 v6.0.2
go.maximumdirect.net/configkit v1.2.0
)
require (
go.yaml.in/yaml/v4 v4.0.0-rc.6
golang.org/x/text v0.40.0
)