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

@@ -0,0 +1,111 @@
# CommandKit Integration
Notarius declares its CLI through the selected native modules:
| Module | Selected release | Attribution |
| --- | --- | --- |
| `go.maximumdirect.net/commandkit` | [v0.7.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0) | [CommandKit](../oss/attribution.md#commandkit) |
| `go.maximumdirect.net/ckconfig` | [v0.10.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/README.md) | [ckconfig](../oss/attribution.md#commandkit-ckconfig) |
| `go.maximumdirect.net/ckprompt` | [v0.11.0](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/README.md) | [ckprompt](../oss/attribution.md#commandkit-ckprompt) |
[go.mod](../../go.mod) owns declared versions. The integrations are independently
versioned modules in the CommandKit repository; their selected tags/source
revisions are not the root module's tag. The [tagged consumer guide][consumer]
and [CLI contract][cli] own native declaration, parser, reporter, and outcome
mechanics. [Notarius CLI Reference](../cli.md) owns the installed product surface.
## Application Construction And Inputs
Notarius supplies identity, declarations, loaders, and domain handlers to
`commandkit.New`. Native help/version and installed shell completion need no
configuration, engine, provider, or run storage. Application pipeline commands
coexist with the full selected configuration/PromptKit suites; adoption is
implemented, not deferred behind a manual dispatcher.
The run convenience route is `commandkit.Alias`, not a forwarding handler.
Typed flags/arguments carry native `Supplied` values, preserving omission and
explicit empty/false/zero. Native parsing, repeated-value handling, mode ordering,
formats, and progress remain CommandKit-owned. The application chooses the
applicable inputs and their domain validation; it does not reconstruct parsing
or recursively execute another command.
## Configuration Scopes
Notarius installs a `ckconfig.Suite` with invocation state and two adapters:
`FromConfigKit` for the application and `FromConfigKitSubtree` for the native
PromptKit subtree. Both use the original successful application result, not
an engine-owned second configuration load. Overrides are enabled because the
loader actually passes native override records into its selected load.
The selected [adapter API](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckconfig%2Fv0.10.0/integrations/ckconfig/configkit_adapter.go)
owns acquisition/focused-view semantics. Focused display/discovery retains native
root-relative explicit paths, whole-load validation, and source/findings evidence.
The application owns complete-selection result/engine reuse; comparisons retain
distinct sides including overlay/override presence. Native reports/differences
replace copied effective-configuration DTOs.
[ConfigKit integration](pkg-configkit.md) owns the load boundary and
[Configuration Internals](../internal/configuration.md) locates its implementation.
## PromptKit Suite And Run Overrides
Notarius installs `FromEngine` with request validation, request preparation,
smoke testing, namespace selection, and scoped convenience aliases through
`Declarations`. Standard upstream request builders are used without copied
inspection/probe implementations. The engine loader uses the same original
result and invocation state as configuration inspection/runtime.
Inspection/requirements do not call a provider. Concrete validation/preview
perform native request preparation; explicit smoke tests can perform network or
model work and retain native supported/applicable/result distinctions.
Pipeline validation is separately application-owned offline preflight, not a
mode added to native configuration validation.
Application run inputs reuse `NewResourceFlags` and `NewExecutionFlags`, selecting
profile/session and execution controls while leaving prompt/source inputs
module-owned. Native execution overrides reach initial, continuation, and nested
validator requests without mutating loaded settings. The selected
[request-flag API](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/integrations%2Fckprompt%2Fv0.11.0/integrations/ckprompt/request_flags.go)
owns those reusable values; [PromptKit integration](pkg-promptkit.md) owns engine
execution. Exact installed syntax belongs in [CLI Reference](../cli.md).
## Reports, Diagnostics, And Outcomes
Handlers submit ordinary values through `Invocation.Reporter().Report`, with a
native text template where appropriate. JSON/YAML render the same report value;
there is no Notarius-wide envelope or separate success serializer.
The [completion contract](../cli.md#completion-report) is intentionally small;
domain artifacts, not a saved report, are the durable deliverables.
Native reporting handles result/diagnostic destinations, visibility, progress,
and delivery evidence. Application findings retain process-warning versus
advisory classification. Fallback qualification remains in the report even when
optional warnings are hidden. Requested capture is application work independent
of native verbosity; on success it finishes after publication and before reporting.
Application outcomes retain operation causes separately from native rendering,
output-write, and diagnostic-delivery failures. Post-publication failure retains
valid artifacts/available locations without rerun or repeated terminalization;
failed stdout can be partial. Standard commands keep their native classifications,
including diff differences; [CLI Reference](../cli.md#output-streams-and-exit-statuses)
owns exact statuses/caller behavior. See the upstream
[reporting guide](https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md#invocation-reporting).
## Verification And Ownership
[Application tests](../../internal/cli/application_test.go),
[pipeline/preflight tests](../../internal/cli/pipeline_commands_test.go),
[native override tests](../../internal/cli/execution_overrides_test.go),
[real executable checks](../../internal/cli/native_process_test.go), and
[result-boundary tests](../../internal/cli/run_result_command_test.go) exercise
the actual kits with fake providers and temporary files. [Assembled recovery](../../internal/cli/recovery_contract_test.go)
verifies the same shared load/engine through domain work and publication/capture.
[CLI Internals](../internal/cli.md) locates declarations and orchestration;
[Operations](../operations.md) owns state handling and
[subprocess guidance](../consumers/subprocess.md) owns consumer workflow.
On dependency upgrades, review the core and separately versioned integrations,
installed capabilities, supplied-value/selection behavior, native outcomes,
and notices together rather than assuming root-version parity.
[consumer]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/consumers/guide.md
[cli]: https://forge.maximumdirect.net/base-layer/commandkit/src/tag/v0.7.0/docs/cli.md

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.

View File

@@ -1,212 +1,125 @@
# PromptKit Integration
Notarius pins
[`gitea.maximumdirect.net/eric/promptkit` v0.12.0](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0)
as its in-process prompt engine. The upstream
[Go package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
owns the public engine API, and the upstream
[format reference](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md)
owns prompt, profile, and schema file contracts.
Notarius uses `go.maximumdirect.net/promptkit` at `v0.24.0` from
[the selected release](https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0).
[go.mod](../../go.mod) owns the version and [attribution](../oss/attribution.md#promptkit)
owns notices/source revision. The [tagged Go consumer guide][consumer] and
[format reference][formats] own native API, resource, and schema mechanics.
## Supported Boundary
## Configuration And Resources
Notarius relies on the root `promptkit` package to:
The application embeds native `promptkit.Settings`, composes rules with
`Configure`, and supplies its successful original ConfigKit result to
`NewFromConfig`. It selects the bundled OpenRouter underlay before loading;
engine construction does not add sources or reinterpret YAML.
[ConfigKit integration](pkg-configkit.md) owns that shared load boundary and
the upstream [application-owned-load guide][handoff] owns the library contract.
- construct an `Engine` with filesystem-backed prompt, schema, and optional
operator and application-fallback profile sources;
- prepare one frozen execution from a `RunRequest` with named inline artifacts,
variables, a direct session ID, prompt identity, profile selection, and
optional appended rendered messages, then
record credential-redacted details and run that exact execution;
- return rendered debug material, validated structured output, selected
profile, backend, effective model metadata, and token usage;
- compose profile and backend mappings through `ConfigurationSources`,
`ProfileSource`, and `BackendSource`, retaining filesystem roots with
`FilesystemInputs` and `DirectoryInputs`;
- register the optional conventional `local` backend with `BackendSource`,
`BackendLocal`, and `LocalBackend`;
- distinguish structured-output validation failure from execution failure; and
- identify a missing explicit profile through `ErrProfileNotFound` and backend
admission exhaustion through `ErrCapacityExceeded`.
Ordinary embedded prompt/profile declarations retain native filesystem contexts.
Main-relative operator companions, main imports, overlays, and explicit overrides
participate in the same application result. Qualified resources, whole-record
replacement/inheritance, null/presence, schema roots, and operator selection
belong in [Configuration](../config.md#promptkit-profiles), not a private
profile/catalog parser.
The pinned
[`BackendSource`, `BackendLocal`, and `LocalBackend` API](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/backends.go)
owns keyed backend configuration and backend-capacity semantics. The
[package consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/consumers/pkg-promptkit.md)
describes source-group assembly.
Prompt declarations select default output contracts and schemas. Native
preparation resolves the selected schema and performs structural validation/
repair; Notarius does not register response schemas or pin omitted native repair
counts. Intrinsic durable artifact schemas remain application codec contracts.
Native backend/profile configuration is available directly; no conventional
local-backend wrapper or separate operator profile file setting is required.
For one completion, the adapter calls `PrepareExecution`, takes a
caller-owned `Details` snapshot, and calls `RunPrepared` for that same opaque
prepared execution. It defers `Discard` for every unexecuted handle. Explicit
profile preflight uses `Engine.InspectProfile`; it does not prepare a synthetic
prompt. PromptKit's prepared handle, inspection result, and capacity-error
types stay inside the Notarius LLM adapter.
One captured engine serves every model role in an invocation. Runtime-only
client/HTTP settings and an optional native `LLMClient` injection remain native
construction options. Request-specific execution/transient-retry selections remain
requests, not mutation of captured settings. Notarius adds no blanket transport
retry/repair or backend-admission defaults; declared profiles and native policy
control effective values.
When a PromptKit profile and runtime override leave `temperature`, `max_tokens`,
or `top_p` unset, Notarius leaves that control unset as well. Compatible
providers therefore apply their own defaults; an operator that requires a
specific sampling value must select it explicitly in the profile or runtime
override.
## Execution, Interpretation, And Continuation
Notarius does not use PromptKit's optional `ArtifactReader`. It materializes
source and reference content itself and supplies owned inline artifacts at the
adapter boundary. It also retains responsibility for pipeline retries,
scheduling, debug persistence, redaction, profile provenance, and conversion
from private model responses into durable domain artifacts.
Modules build `RunRequest` with selected prompt/profile/session, owned inline
artifacts and variables; they interpret `RunResult` into typed domain values.
Notarius materializes source/references and contextual identity projections
before execution. It uses native session selection rather than a compatibility
prompt variable. [CLI Reference](../cli.md#run-wide-llm-overrides) owns run-wide
controls and [Module Internals](../internal/modules.md) owns the extension recipe.
Notarius sends one stable effective session through PromptKit's direct session
field, which is authoritative for provider session behavior. It also retains
the same value as the `session_id` prompt variable for maintained prompt
compatibility. The generated identifier is 76 ASCII characters, within
PromptKit's 256-code-point session limit. Session IDs are non-secret
correlation identifiers and may be exposed to providers and provider
observability. The CLI contract owns generation and override behavior.
The shared producer path uses ordinary `Run`, or the retained prepared handle
described below. Native error and validation status are checked before
interpretation, including structural failure with no Go error.
The application assesses usable candidates through its complete configured chain.
Notarius records PromptKit's selected backend ID and effective reasoning
setting as optional run-manifest provenance. Endpoint-only profiles have no
backend ID. Debug prompt material also retains the selected backend ID and
PromptKit's stable lower-case `effective_model_params` JSON, which may include
`backend_id`. Notarius production configuration exposes one optional
conventional `local` registration. It does not expose a general user-defined
PromptKit backend registry. Endpoint-only profiles remain supported unchanged.
For actionable semantic correction, native `Coordinate` starts from a captured
exchange. Fixed inputs and prior responses remain in growing native history;
the follow-up adds new findings/assignment, not manually replayed latest-only
messages. Every delivered usable revision, including the final allowed response,
receives complete assessment. Native stopped/exhausted status is not domain
acceptance. Result-less failures do not recover earlier proposals, and undelivered
responses are unassessed. See the [continuation/coordination guide][continuation].
Notarius retains its application-wide scheduled client around the PromptKit
adapter. PromptKit may apply a narrower limit for the selected backend;
endpoint-only profiles have no such backend limit. The adapter translates
PromptKit capacity rejection into the provider-neutral Notarius
`ErrLLMCapacityExceeded` contract. It may include the normalized selected
backend ID in safe diagnostic context, without exposing PromptKit's capacity
error type. PromptKit's built-in client retries eligible transient HTTP failures
with its v0.12.0 default of two additional attempts per generation; Notarius
keeps pipeline-stage retries outside that completion boundary.
LLM validators call the same engine directly and return domain judgments or
unavailable assessment, without a producer turn loop. Native typed errors/causes
remain inspectable; Notarius adds context/disposition rather than a
provider-neutral replacement error taxonomy. Caller cancellation and native
operation timeouts remain distinguishable.
The adapter projects built-in generation failures as the application-owned
`LLMGenerationError`, retaining a safe failure kind, HTTP status when present,
and retry-exhaustion attempt count. Transport, malformed successful envelopes,
provider statuses, and generic generation failures remain distinct without
exposing PromptKit error values to Notarius callers.
## Prepared Reuse, Admission, And Execution Facts
## Profile Sources And Compatibility
For eligible cached producers, `PrepareExecution` supplies initial
`Details().MessageContentHash`; a miss executes that same handle with
`RunPrepared`, and unused handles are discarded. A hit reuses the accepted typed
artifact or checked plan without native execution, exchange restoration,
semantic reassessment, or historical usage. Correction retains the initial key.
Native preparation does not reserve model capacity; the [prepared-handle contract][prepared]
owns lifecycle. [Operations](../operations.md#accepted-result-cache-and-recovery)
owns Notarius reuse policy and [State Internals](../internal/state.md) its implementation.
Notarius gives PromptKit the configured operator profile source, registered
application fallback profile assets, and optional backend configuration
through the same construction path for inspection and execution. PromptKit
owns source precedence, strict group composition, and recursive field overlay:
omitted operator fields retain lower-layer values, while supplied fields
replace them. The application group retains registered filesystem roots; the
operator may be one file with native imports or a recursively discovered
directory. Imports resolve resources from their declaring file. Prompt and
profile definitions are validated after source composition, so a malformed
lower-layer value superseded by a valid overlay is not separately audited. A
malformed final effective definition fails construction. The operator
configuration and deployment workflow are defined in
[Configuration](../config.md#promptkit-profiles) and
[Operations](../operations.md#promptkit-profile-deployment).
Native backend admission is independent of application ready-job workers.
No global LLM scheduler, extra admission queue, or application retry extends native
budgets. Completed producer turns release admission before assessment, so nested
validators can use the same limited backend. Strict/permissive terminal handling
and supported fallback remain application choices; [Configuration](../config.md#producer-controls)
owns those controls.
PromptKit and ConfigKit own `extends` inheritance under the
[pinned format rules](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/formats.md).
Notarius records the selected leaf identity and resolved target without parsing
or merging inheritance. `api_key_env` names the environment variable; inspection
does not check whether it is set. PromptKit's effective `api_key_required`
metadata is supported in file-backed profiles and reported as metadata, not
as an availability check. Whether a usable credential reaches the provider
remains an execution concern.
One invocation `ExecutionGroup` enrolls actual initial, continuation, and nested
validator calls once through composed observers. Native run/parent identity,
terminal coverage, and unknown usage remain native facts, not copied totals or
a durable profile ledger. The upstream [execution-facts guide][observations]
owns grouping semantics.
PromptKit accepts only the `developer`, `system`, `user`, and
`assistant` text-chat roles after normalizing case and surrounding whitespace.
Maintained Notarius prompt definitions use only `system` and `user`.
Optional capture retains available prepared/results/raw response/full exchange
views plus application context, without another preparation or model call.
Native credential omissions and ConfigKit marked-secret views remain intact;
ordinary content is not heuristically rewritten. Debug serialization is private,
not a consumer protocol. [Operations](../operations.md#debug-bundles) owns handling.
For application-owned semantic correction, Notarius uses PromptKit's
`RunRequest.AppendedMessages` after the ordinary rendered prompt. It supplies
exactly two messages in order: the latest validated producer response with
role `assistant`, then deterministic validation guidance with role `user`.
It never exposes a general caller-selected role API, accumulates earlier
correction turns, or changes the ordinary prompt prefix. Ordinary requests
leave appended messages unset.
## Inspection, Preflight, And Verification
PromptKit preserves supplied content but does not own Notarius's correction
bounds. Notarius rejects invalid UTF-8, blank, or oversized assistant material
(at most 1 MiB), guidance (at most 64 KiB), and combined content (at most
1,114,112 bytes) before preparing the request. The transport-neutral
application contract owns defensive copying and these limits. Default request
and terminal summaries retain only safe counts, digests, identities, and usage;
complete appended messages remain limited to the explicitly requested detailed
debug trace.
[CommandKit/ckprompt](pkg-commandkit.md) supplies resource inspection,
requirements, concrete request validation/preparation, namespaces, and explicit
smoke testing through the same loaders. Offline pipeline preflight checks declared
prompts and applicable profiles without synthetic requests, execution input reads,
credential lookup, or provider work. Partial profiles can pass inspection while
concrete preparation remains a later readiness boundary. Smoke execution is explicit.
PromptKit obtains its maintained OpenRouter and Rakestrawhome backend and
profile catalogs from independently versioned transitive modules. Notarius
does not import or register either catalog; PromptKit retains catalog source,
identity, precedence, credential, and capacity ownership.
The selected integration modules are
[`promptkit-backend-openrouter/v3`](../oss/attribution.md#promptkit-openrouter-catalog)
and
[`promptkit-backend-rakestrawhome/v3`](../oss/attribution.md#promptkit-rakestrawhome-catalog),
both pinned at `v3.20260930.0` for this compatibility boundary.
[Native schema tests](../../internal/cli/native_schema_load_test.go),
[producer tests](../../internal/framework/pipeline/producer_test.go),
[nested assessment](../../internal/framework/pipeline/native_assessment_test.go),
and [assembled recovery](../../internal/cli/recovery_contract_test.go) verify the
selected integration using real libraries and fake providers. They cover custom
contracts, native status/causes, final-turn assessment, same-backend liveness,
initial-key reuse, fallback qualification, and observations without production
model-quality claims.
External catalog profile names and settings can change between dependency
releases, including removal without aliases. Review directly selected IDs and
inherited `extends` values when upgrading. An application-owned alias that
inherits an external profile does not freeze that profile's settings.
PromptKit's opt-in `promptkit-openrouter-standard` and
`promptkit-openrouter-auto` names provide name continuity within its
selected-and-tested dependency scope, not a fixed model or provider availability
guarantee. See the upstream
[catalog compatibility policy](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.12.0/docs/policy/release.md#catalog-profile-compatibility).
[LLM Integration Internals](../internal/llm.md) locates current call sites.
An upgrade requires reviewing these native contracts, declaration/schema
contexts, command integrations, retained domain behavior, and notices together;
there is no private completion adapter to preserve.
Use a complete operator-owned profile with explicit backend or endpoint, model,
and settings when those choices must remain operator-controlled. The embedded
`dnd-extraction` fallback already follows this model and does not inherit an
external catalog profile. An upgrade updates Notarius's compiled-in catalog
checkpoint identity so prior profile-source checkpoints are not reused.
Notarius supports this boundary against PromptKit v0.12.0. Its native sources,
prepared-execution, inspection, and typed capacity APIs are used as public
upstream contracts; other PromptKit APIs or file-format behavior are not
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
history contracts; the profile command is a separate Notarius-owned projection
of copied, provider-neutral metadata. None of these views reads credential
values or predicts provider defaults. See the public [CLI reference](../cli.md#config-effective),
[explanation](../cli.md#config-explain), and
[profile](../cli.md#config-profile) entries for their syntax and output
contracts.
## Notarius Ownership
[LLM Runtime Internals](../internal/llm.md) describes how Notarius mounts
module assets, maps its transport-neutral completion contract, prepares and
executes requests, validates output, records provenance, captures debug
material, redacts errors, and preserves timeout ownership.
PromptKit provider error details do not cross the ordinary completion boundary.
Notarius exposes a provider-neutral generation category and optional status;
redacted provider details are retained only in requested debug material.
[D&D Module Internals](../internal/dnd.md) owns the embedded
`dnd-extraction` fallback profile and the maintained D&D prompt defaults.
[Configuration](../config.md#promptkit-profiles) defines how a Notarius
configuration selects one PromptKit profile source and optionally registers
the conventional local backend.
PromptKit API or format changes outside this boundary are not implicitly
supported. Updating the pinned version requires reviewing the adapter and
profile/configuration contracts against the upstream documentation. Maintained
production prompts use PromptKit's bounded structural-repair contract; their
current declaration is one additional repair attempt. Notarius retains the
transport-neutral boundary and does not expose PromptKit types to modules.
The v0.12.0 upgrade replaces the removed option-based configuration API with
native ConfigKit-backed sources and keyed documents; release pins and notices
are listed in the [canonical attribution](../oss/attribution.md#promptkit).
See the canonical [PromptKit attribution](../oss/attribution.md#promptkit),
[OpenRouter catalog notice](../oss/attribution.md#promptkit-openrouter-catalog),
and [Rakestrawhome catalog notice](../oss/attribution.md#promptkit-rakestrawhome-catalog).
[consumer]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md
[formats]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/formats.md
[handoff]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#reuse-an-application-owned-load
[continuation]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#coordinate-application-directed-turns
[prepared]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later
[observations]: https://forge.maximumdirect.net/base-layer/promptkit/src/tag/v0.24.0/docs/consumers/pkg-promptkit.md#collect-selected-execution-facts

View File

@@ -2142,6 +2142,27 @@ implementation; inspect native asset paths/IDs and retained domain regression te
## Stage 44: Align The Kit Integration Contracts
**Status:** Complete. Updated ConfigKit and PromptKit integration contracts and
added CommandKit/ckconfig/ckprompt integration guidance for the actual selected
vanity-path releases. The guides describe one typed application result, native
contexts/focused views, captured engine/resources, direct requests/continuation,
prepared result reuse, independent admission, observations, and the fully installed
native command/reporting boundary. Removed old dual configuration engines,
catalog/adaptor APIs, latest-only replay, wrapper retry limits, scheduler/error
translations, copied inspection, and durable accounting claims. Public policy
and internals link to their canonical owners rather than copied upstream manuals.
Compared current definition/loaders, suite declarations, reusable overrides,
preflight, producer/validator calls, and reporting with selected module API/docs.
Verified Go module release metadata and the separately tagged integration module
paths; notices match all five selected source hashes. All 48 local links and
20 tagged upstream destinations/anchors resolve against repository/module sources.
The one historical release link to an old integration heading remains unchanged
under release-history policy. Configuration, CLI, preflight, pipeline, and module
integration tests and vet pass, as do removal searches and `git diff --check`.
No dependency, runtime behavior, notice material, or published history changed.
Orientation/planning reconciliation and final acceptance remain next.
**Goal:** describe Notarius's actual use of all three native libraries.
**Inspect/change:** `docs/integrations/{pkg-configkit,pkg-promptkit}.md`; create