Document PromptKit configuration ownership and capture
This commit is contained in:
@@ -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.
|
||||
|
||||
92
docs/adr/0019-adopt-native-promptkit-configuration.md
Normal file
92
docs/adr/0019-adopt-native-promptkit-configuration.md
Normal 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.
|
||||
Reference in New Issue
Block a user