Document native kit integration contracts and ownership
This commit is contained in:
111
docs/integrations/pkg-commandkit.md
Normal file
111
docs/integrations/pkg-commandkit.md
Normal 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
|
||||
@@ -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.
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user