Document PromptKit configuration ownership and capture

This commit is contained in:
2026-10-04 14:12:11 +00:00
parent 169a94f7ea
commit 4aba4f5672
6 changed files with 215 additions and 62 deletions

View File

@@ -83,35 +83,38 @@ retain an empty backend ID, which the published JSON omits. Successful
completion responses and recorded profile manifests identify the adapter
provider as `promptkit`.
The CLI's profile-inspection engine and the production adapter use the same
profile-source construction to apply the configured profile directory or file,
the optional registered fallback profile assets, and the optional conventional
`local` backend. Preflight therefore resolves the same profile sources and
backend membership as runtime without performing generation. Fallback assets
are mounted only when at least one source is registered. The production D&D
registrar contributes its `dnd-extraction` fallback, and the maintained D&D
prompts select that logical ID by default. PromptKit owns source precedence and
profile parsing and inheritance: an operator-provided matching profile takes precedence over a
fallback profile without Notarius merging either document.
When the registration is absent, a profile selecting `backend: local` fails
inspection instead of falling back to a built-in or endpoint-only target.
The CLI's profile-inspection engine and production adapter use the same source
assembly: PromptKit catalogs, one application group containing registered
prompts and fallback profiles, the selected operator file or directory, and
the optional final `local` backend registration. Execution, preflight, and
inspection therefore capture the same effective definitions. PromptKit and
ConfigKit compose recursively across groups while retaining each input's file
context; inputs within a group compose strictly. Operator imports are enabled
for the selected operator input, and imports retain their declaring file's
relative resource roots. PromptKit validates final effective definitions at
engine construction. It does not run a separate audit that rejects a malformed
definition superseded by a later overlay. The D&D registrar contributes its
`dnd-extraction` fallback, and maintained D&D prompts select that logical ID
by default. A profile selecting `backend: local` requires the optional local
registration.
Before execution, the adapter also contributes a non-secret checkpoint
fingerprint for the effective PromptKit profile source. It combines the
identity of PromptKit's compiled-in profile catalog with a deterministic digest
of every YAML profile in the configured profile directory, or of the configured
profile file, and a deterministic digest of the flattened fallback profile
assets. The fingerprint contains neither profile content nor source paths. It
covers inherited pipeline profiles, explicit binding profiles, and
prompt-selected defaults, so changing a model or other profile setting cannot
reuse checkpoints created under the
prior profile source. This cache identity is independent of durable
profile provenance: run manifests continue to list only profiles actually
observed during LLM calls. When the local backend is registered, a second
fingerprint hashes its trimmed endpoint behind a stable marker. Changing that
semantic execution target invalidates checkpoint reuse. The raw endpoint is not
stored in checkpoint identity, and the local concurrency limit is excluded
because it changes scheduling rather than execution semantics.
Each engine captures its definitions at construction. A later source-file edit
does not mutate an existing engine; constructing a new engine captures the
updated view. Before execution, the adapter computes one immutable,
versioned `promptkit_configuration` checkpoint identity from public captured
inspection APIs. The private digest covers captured effective configuration,
all effective profile targets and credential-policy metadata (including
provider parameters), and every effective prompt ID/version and captured
content hash. The identity also includes PromptKit and the selected OpenRouter
and Rakestrawhome catalog versions. Local-backend concurrency settings remain
excluded because they affect scheduling; its endpoint is represented only in
the private digest, never as checkpoint metadata. Neither the private digest
payload, raw sources, paths, endpoints, provider parameters, nor prompt bodies
are published. An existing engine retains its identity after files change; a
new engine gets the identity of its newly captured definitions. This replaces
the former live-file profile and local-endpoint fingerprints. Run manifests
remain independent and list only profile choices actually observed during LLM
calls.
## Shared Provider-Call Limit
@@ -140,11 +143,16 @@ only by the Notarius scheduler.
## Prompt And Schema Assets
An `AssetRegistry` collects prompt, schema, and optional fallback-profile
filesystems from production module families. It flattens registered roots into
the corresponding PromptKit filesystems and rejects invalid roots, unreadable
assets, duplicate paths, and missing prompt or schema files during preparation.
Fallback assets receive a safe content digest for checkpoint identity; raw
paths and bytes are never included. The framework’s `promptfs` helper combines
filesystems from production module families. It retains each registered root's
filesystem context when constructing PromptKit's application source group.
Schema files are supplied separately through the engine's schema filesystem;
PromptKit reads and validates a selected schema while preparing that request,
not while constructing the configuration snapshot. Prompt and fallback
definitions are validated after native source composition, and referenced
prompt content is captured with the engine. Checkpoint identity uses captured
prompt content hashes rather than rescanning live files or hashing only
content-file paths. Raw paths and bytes are never included. The framework’s
`promptfs` helper combines
module-selected prompt files with reusable domain fragments without making the
framework depend on D&D content.
@@ -294,6 +302,10 @@ When debug recording is enabled, the pipeline decorates the shared client. The
wrapper records prepared prompt and response material, timing, selected profile
and backend, effective model parameters, and call identifiers in the run’s
debug bundle, including material available from a failed structured completion.
The profile-inspection CLI projects copied values into its Notarius-owned
neutral JSON DTO; effective configuration and explanation remain PromptKit's
redacted YAML and source-history views. Credential names and `APIKeyRequired`
metadata are configuration metadata, not credential-availability checks.
Effective parameters use PromptKit's stable lower-case JSON field names and may
include `backend_id`. For a successful completion, a debug-write failure is
surfaced; when the completion already failed, its call error remains the