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

@@ -1,6 +1,7 @@
# ADR-0010: Use workload-oriented LLM profile defaults
**Status:** Accepted
**Status:** Accepted; profile source replacement behavior superseded by
[ADR-0019](0019-adopt-native-promptkit-configuration.md)
**Date:** 2026-08-03
## Context
@@ -23,11 +24,13 @@ intentional exceptions, and the run-wide CLI profile override has highest
precedence.
The D&D family owns an embedded fallback profile named `dnd-extraction`.
Operators may provide a complete profile with the same ID through a PromptKit
filesystem source. PromptKit selects the higher-precedence matching definition;
Notarius does not merge profile documents. Production, development, and local
deployments can therefore use different execution policy behind one unchanged
pipeline ID.
Operators may configure the same ID through a PromptKit filesystem source. The
original decision specified that an operator definition replaced the fallback
as a complete profile; that source-composition clause has been superseded by
[ADR-0019](0019-adopt-native-promptkit-configuration.md), which adopts native
recursive overlays. The workload-oriented identity and D&D ownership decision
remain in force. Production, development, and local deployments can therefore
use different execution policy behind one unchanged pipeline ID.
## Alternatives considered
@@ -42,8 +45,8 @@ pipeline ID.
## Consequences
Pipeline configuration expresses workload intent rather than a specific
provider or model. Operators can replace the complete execution policy without
editing bindings, while binding-level and run-wide exceptions remain available.
Profile changes affect resolved pipeline and checkpoint identity, so they may
provider or model. Operators can configure execution policy without editing
bindings, while binding-level and run-wide exceptions remain available. Profile
changes affect resolved pipeline and checkpoint identity, so they may
intentionally cause work to be recomputed. The D&D fallback becomes a
maintained application execution-policy asset.

View File

@@ -0,0 +1,92 @@
# ADR-0019: Adopt native PromptKit configuration sources
**Status:** Accepted
**Date:** 2026-10-04
## Context
PromptKit v0.12 replaces its former source options with ConfigKit-backed
configuration sources, keyed documents, recursive overlays, and native
inheritance. Notarius must choose how application-owned prompt and fallback
assets, operator configuration, and the optional local backend reach PromptKit
without recreating source parsing or inheritance in the adapter. Runtime,
preflight, and operator inspection must agree about the effective definitions.
Notarius also captures checkpoint identity for the PromptKit configuration
used by an execution engine. That identity must follow the engine's captured
definition state rather than re-reading mutable source files, and must not
publish credentials, prompt bodies, provider parameters, or source paths.
## Decision
Use PromptKit's public v0.12 native source APIs as the only PromptKit
configuration boundary. Assemble PromptKit catalogs, registered application
prompt and fallback inputs, the optional operator file or recursively selected
directory, and the optional Notarius local backend registration in that order.
Use native ConfigKit imports and PromptKit/ConfigKit composition behavior;
retain each filesystem input's resource context. Inputs within a group compose
strictly, and later groups recursively overlay earlier ones. PromptKit owns
definition parsing, exact-key `extends` inheritance, and final effective-value
validation. Notarius does not provide a legacy parser, compatibility alias,
filename-priority merger, whole-profile replacement shim, or alternate
inheritance engine.
Execution, explicit-profile preflight, and configuration inspection use the
same source construction. Each constructed engine captures its effective
definitions. Edits to source files take effect for a newly constructed engine,
not an existing one. Derive the private versioned
`promptkit_configuration` checkpoint identity from public captured inspection
and definition APIs, including effective configuration, profile targets and
credential-policy metadata, captured prompt hashes, and the PromptKit and
selected catalog identities. Retain only the digest as checkpoint metadata;
keep all digest inputs private. Exclude local-backend concurrency settings
because they affect scheduling rather than execution semantics.
Keep PromptKit types and source assembly inside the LLM integration boundary.
The CLI may project copied profile fields into a Notarius-owned neutral JSON
contract. PromptKit's effective and explanation reports remain upstream
redacted configuration and source-history views. Neither inspection path reads
credential values or contacts a provider.
## Compatibility
The migration to v0.12 keyed configuration is an intentional external file
format change. Operators must migrate `id`/`version` embedded fields and
`base_profile` to native keyed documents and `extends`. Notarius does not
silently accept the former option-based API or file format. Notarius's own
version 5 configuration contract and loader decision in
[ADR-0018](0018-adopt-configkit.md) remain in force; this decision concerns
PromptKit definitions and source composition.
The workload-oriented profile identity and D&D fallback ownership in
[ADR-0010](0010-workload-oriented-llm-profile-defaults.md) remain in force.
Only that ADR's former claim that a matching operator profile completely
replaces the fallback has been superseded: native recursive overlays retain
unspecified inherited fields.
## Alternatives considered
- Keep the removed PromptKit option-based configuration API or add a
compatibility parser. This would fork the supported upstream contract and
preserve legacy format machinery.
- Merge profile documents inside Notarius or restore whole-profile
replacement. This would duplicate upstream composition behavior and make
inspection, preflight, and runtime easier to diverge.
- Re-read and hash source files for checkpoint identity. This could describe
mutable files rather than the definitions captured by the engine and would
duplicate upstream discovery and composition.
- Expose upstream inspection structs directly as CLI output. This would bind
the public Notarius contract to dependency-owned Go types.
## Consequences
PromptKit remains the owner of its native configuration semantics, while
Notarius owns which registered and operator sources are assembled and when an
engine is reconstructed. A valid later overlay can supersede an earlier
definition; validation applies to the final effective definitions rather than
as a separate audit of every superseded value. Configuration reports can
contain ordinary prompt and provider parameters, so operators own the
destination and retention of explicitly requested reports even though
credential-shaped fields are redacted. PromptKit upgrades require review of
the source adapter, captured identity, reports, and the pinned upstream
contracts.