Document native kit integration contracts and ownership

This commit is contained in:
2026-11-22 06:52:56 +00:00
parent aa4ce04683
commit b76d511571
4 changed files with 302 additions and 207 deletions

View File

@@ -1,21 +1,71 @@
# ConfigKit Integration
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 uses `go.maximumdirect.net/configkit` at `v1.4.0` from
[the selected release](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0).
[go.mod](../../go.mod) owns the declared version; [attribution](../oss/attribution.md#configkit)
owns notices/source revision. The [tagged consumer guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/consumers/README.md)
and [configuration contract](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/config.md)
own native loading, presence, inheritance, inspection, and error semantics.
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).
## One Application-Owned Result
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).
Notarius supplies a typed application document containing native
`promptkit.Settings`, and composes its definition with `promptkit.Configure`.
Application version/default/path/normalization/validation rules and native
resource identity/sensitivity rules participate in the same load.
Production composition selects the main source and calls `configkit.LoadLayered`.
It supplies bundled provider, embedded application, and main-relative operator
underlays before the selected main/import/overlay/explicit override layers.
Native filesystem/destination/source contexts remain attached; the application
does not flatten resources or reimplement source composition.
[Configuration](../config.md#configuration-discovery-and-precedence) owns
Notarius's selected sources/precedence; the upstream
[layered-input guide](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/consumers/README.md#native-filesystem-and-layered-input)
owns the library mechanism.
The successful `*configkit.Result[config.Document]` supplies runtime conversion,
inspection, and `promptkit.NewFromConfig`. That handoff performs no second load,
callback run, or YAML round-trip. Runtime pipeline configuration is independently
owned; the original result retains native resource evidence and contexts.
See [PromptKit integration](pkg-promptkit.md) and the upstream
[component handoff](https://forge.maximumdirect.net/base-layer/configkit/src/tag/v1.4.0/docs/consumers/README.md#component-handoff).
## Inspection And Invocation Selection
CommandKit's [ckconfig integration](pkg-commandkit.md#configuration-scopes)
adapts the original result for whole-application and focused PromptKit views.
Focused presentation does not load another document: whole-load validation and
source/findings context remain, while explicit metadata/explanation paths retain
native application-root coordinates.
The invocation-owned loader retains complete selections, including supplied
overlay/override values, and lazily builds one engine for each retained result.
Distinct comparison sides cannot accidentally reuse the same selection.
This is not process-global persistent configuration caching.
Inspection delegates to native result views, diagnostics, explanations, and diff.
ConfigKit sensitivity and PromptKit's composed sensitivity apply together.
Do not infer that arbitrary application text is safe, or replace marked-secret
omissions with heuristic content scrubbing. Exact syntax/selection behavior
belongs in [Configuration](../config.md) and [CLI Reference](../cli.md#configuration-commands).
## Application Ownership And Verification
Notarius owns application document meaning, source-aware operational paths,
runtime conversion, catalog-dependent pipeline resolution, and physical runtime
initialization. ConfigKit does not parse transcripts, construct pipeline modules,
materialize execution references, or allocate run storage.
[Configuration Internals](../internal/configuration.md) locates those implementations.
[Native settings tests](../../internal/core/config/native_settings_test.go),
[loader tests](../../internal/cli/native_load_test.go), and
[scope/diff tests](../../internal/cli/application_test.go) verify the real selected
libraries, retained origins/settings, frozen inspection, secret handling, and
selection isolation. [Assembled recovery](../../internal/cli/recovery_contract_test.go)
uses that same handoff through actual domain execution.
There is no parallel old-path ConfigKit integration or translation layer.
When upgrading, review the composed definition, original-result and source-context
handoff, focused views, and selected native command integration against the new
public contracts; do not infer compatibility from a successful module download.