93 lines
4.9 KiB
Markdown
93 lines
4.9 KiB
Markdown
|
|
# 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.
|