From b76d51157196040d0da8831a639623556fa1943e Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sun, 22 Nov 2026 06:52:56 +0000 Subject: [PATCH] Document native kit integration contracts and ownership --- docs/integrations/pkg-commandkit.md | 111 +++++++++++ docs/integrations/pkg-configkit.md | 84 ++++++-- docs/integrations/pkg-promptkit.md | 293 ++++++++++------------------ docs/roadmap/implementation.md | 21 ++ 4 files changed, 302 insertions(+), 207 deletions(-) create mode 100644 docs/integrations/pkg-commandkit.md diff --git a/docs/integrations/pkg-commandkit.md b/docs/integrations/pkg-commandkit.md new file mode 100644 index 00000000..bf1eb48f --- /dev/null +++ b/docs/integrations/pkg-commandkit.md @@ -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 diff --git a/docs/integrations/pkg-configkit.md b/docs/integrations/pkg-configkit.md index 56807193..ebad94d7 100644 --- a/docs/integrations/pkg-configkit.md +++ b/docs/integrations/pkg-configkit.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. diff --git a/docs/integrations/pkg-promptkit.md b/docs/integrations/pkg-promptkit.md index 032f7326..f43221bb 100644 --- a/docs/integrations/pkg-promptkit.md +++ b/docs/integrations/pkg-promptkit.md @@ -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 diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index b1ecf503..81857c64 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -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