Plan application-owned ConfigKit resolution and whole-result handoff

This commit is contained in:
2026-11-21 00:12:38 +00:00
parent aae523c916
commit 55276c9429

View File

@@ -48,17 +48,77 @@ only after failed validation and can add generation latency and usage. Existing
repair accounting, exhaustion, cancellation, and transient-retry semantics remain repair accounting, exhaustion, cancellation, and transient-retry semantics remain
unchanged; the change does not promise successful correction. unchanged; the change does not promise successful correction.
## 2. Place Configuration Under A Root-Level `promptkit` Key ## 2. Consume Application-Resolved Configuration Under `promptkit`
**Accepted:** move all PromptKit-owned configuration beneath the fixed root-level **Accepted:** the application composes configuration once through ConfigKit and
`promptkit` key. This gives applications a distinct configuration section for passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit
PromptKit alongside their other settings. Do not add a configurable mounting key. locates the fixed root-level `promptkit` section and consumes only that section,
ignoring sibling application settings. The application does not extract, reshape,
serialize, or reload a PromptKit-specific view. Do not add a configurable mounting
key.
The resolved structure includes `promptkit.backends`, `promptkit.profiles`, The root-key migration supports this handoff; changing YAML paths alone does not
`promptkit.prompts`, `promptkit.collections`, and `promptkit.schema_root`. fulfill the feature. The architectural benefit is a single composition lifecycle
Collection-local fields remain inside their collection. ConfigKit-owned source with native source context and provenance, rather than an application bridge
headers and directives retain their native semantics and locations; they do not between separately loaded configurations.
automatically move inside `promptkit`.
### Current Boundary And Intended Consumer Workflow
Today, PromptKit accepts configuration sources and runs its own ConfigKit load.
Its typed root document rejects unrelated application fields. Audita, for example,
loads application settings separately, then uses their recorded main-source
context to assemble embedded and companion PromptKit sources for another load.
It does not currently hand PromptKit its resolved application configuration.
The target workflow is:
1. The application includes PromptKit's configuration definition/registration and
desired bundled or application sources in its ordinary ConfigKit setup.
2. ConfigKit composes and resolves the complete application configuration once,
applying each component's registered rules.
3. The application passes the whole resolved result to PromptKit, together with
runtime collaborators such as its HTTP client. PromptKit captures its effective
resources and constructs the engine without another configuration load.
File discovery, source selection, imports, layering, and application overrides
remain application policy. Embedded prompt selection and companion-file imports
join the original load; they do not disappear. The change removes context-transfer
and duplicate-loading machinery, not application-specific execution requests,
profile selection, required-resource checks, or diagnostics policy.
### Configuration Rules And Handoff
Expose a small public integration surface for PromptKit's configuration rules to
participate in the application's ConfigKit load. Defaults, normalization, field
validation, collection identity constraints, and sensitivity declarations remain
PromptKit-owned rules applied through ConfigKit's native lifecycle. Applications
must not reproduce these rules or depend on PromptKit's internal types.
The exact public registration and result-accepting API shapes require planning.
The handoff must work with an application-owned result type, not require replacing
its configuration model with PromptKit's root document type. Preserve effective
values, source contexts for relative message/schema files, provenance, and native
redaction. A decoded map alone or a serialized section loaded again is not an
equivalent handoff.
Register desired bundled defaults as ordinary underlays before composition;
engine construction must not inject another configuration layer into an already
resolved result. Apply configured repair defaults from item 1 during resolution,
so inspection and execution agree. Runtime request defaulting remains separate.
Retain source-loading construction as a convenience for consumers that want
PromptKit to select its own loading path. It should use the same configuration
rules and engine-capture path: load once, then hand off the result. Do not maintain
two independent implementations of configuration semantics. Existing source
selection choices remain available subject to the accepted layout migration.
### Fixed Section And Clean Migration
Move all PromptKit-owned document settings beneath `promptkit`, including
`promptkit.backends`, `promptkit.profiles`, `promptkit.prompts`,
`promptkit.collections`, and `promptkit.schema_root`. Collection-local fields
remain inside their collection. Runtime collaborators are Go API inputs, not new
YAML fields.
Make a clean breaking migration with one canonical resolved location. Do not Make a clean breaking migration with one canonical resolved location. Do not
support legacy root-level resource locations through aliases, automatic detection, support legacy root-level resource locations through aliases, automatic detection,
@@ -69,24 +129,26 @@ Preserve convenient standalone files. Individual resource files can still begin
with `id`, and collection files can still contain local `prompts`, `profiles`, with `id`, and collection files can still contain local `prompts`, `profiles`,
`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit `backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit
import destinations and PromptKit source helpers mount those fragments at the import destinations and PromptKit source helpers mount those fragments at the
appropriate nested location. This is fragment composition, not support for two appropriate nested location. Source-relative context follows the effective
alternative application configuration layouts. Source-relative resource context contributing field, not the location of the application document or mount point.
must continue to follow the effective contributing field.
PromptKit owns validation of its section, not sibling application settings. ConfigKit-owned headers and directives retain their native semantics. The
Implementation planning must verify the ConfigKit loading boundary so that application owns its main configuration specification; PromptKit must not impose
unrelated application sections can coexist without PromptKit interpreting or its standalone document version on the whole application. Planning must account
rejecting their contents. Keep field validation within PromptKit's section. for application headers and optional PromptKit fragment headers in the same load,
including the standalone convenience path, without inventing a second header
parser or version-composition pass.
An absent `promptkit` section contributes no application-supplied PromptKit An absent `promptkit` section contributes no application-supplied PromptKit
settings; bundled defaults can still operate. Old root-level keys such as settings; selected bundled underlays can still contribute defaults during the
`prompts` and `profiles` are neither consumed nor specially rejected by PromptKit: original load. Old root-level keys such as `prompts` and `profiles` are neither
they may be legitimate application-owned settings. Unknown fields inside consumed nor specially rejected by PromptKit: they may be application settings.
`promptkit` remain configuration errors. This does not bypass ConfigKit's own Unknown fields inside `promptkit` remain configuration errors. The application's
document/composition validation. Migration documentation must explain that an own validation and ConfigKit's document/composition rules still apply to the
unmigrated application document can load without contributing its intended whole document. Migration guidance must explain that unmigrated resources are
resources, with a missing prompt becoming apparent when selected. Do not add not loaded and can therefore produce missing-resource errors when selected.
legacy-layout detection to compensate for that consequence.
### Inspection Boundary
Scope `InspectConfiguration` value reports and comparisons to PromptKit's section, Scope `InspectConfiguration` value reports and comparisons to PromptKit's section,
retaining actual `promptkit.…` paths and relevant source provenance. Unrelated retaining actual `promptkit.…` paths and relevant source provenance. Unrelated
@@ -94,33 +156,56 @@ application values must not become part of PromptKit's reports or comparisons
merely because they share an input document. Preserve native ConfigKit redaction merely because they share an input document. Preserve native ConfigKit redaction
and explanation semantics. Resource inspection remains resource-scoped. and explanation semantics. Resource inspection remains resource-scoped.
Implementation planning must cover: Prefer native ConfigKit scoped inspection over PromptKit-maintained reporting
adapters. The requirement concerns the public scope and ownership of inspection;
- Updating bundled underlays, source helpers, import destinations, identity it does not independently promise that ConfigKit never visits sibling data
registrations, normalization, and validation to the new paths using ordinary internally. Do not silently substitute whole-application reporting, reconstruct
ConfigKit composition. source history, or reload a copied section to manufacture a scoped result.
- Reflecting nested paths in configuration inspection and diagnostics while
preserving resource inspection and runtime IDs.
- Migration guidance for application documents and explicit import destinations,
including schema roots; standalone fragments should not need extra wrappers.
- Focused coverage for sibling application settings, mounted collections and
resources, default overlays, and source-relative message/schema resolution.
## Guidance For Implementation Planning ## Guidance For Implementation Planning
The product decisions above are accepted. Begin planning with a focused feasibility ### Start With The Public Integration Contract
check of ConfigKit's public loading and inspection APIs: establish how to validate
the `promptkit` section while allowing siblings, and how to scope effective-value
reports, explanations, and comparisons while retaining native paths, provenance,
and redaction. Do not reconstruct resolved configuration or source history, add a
second composition pass, or quietly broaden inspection to the whole application.
If the public API cannot support this boundary, report the specific gap and options
before committing to an implementation design.
Then specify the concrete input/resolved Go shapes, source-helper adaptations, Prepare a concrete consumer sketch covering registration, one application-owned
and migration examples. Keep the repair-default and configuration-root changes load, whole-result engine construction, and PromptKit-scoped inspection. Also show
separately reviewable even if delivered in the same release. Neither needs a new the standalone source-loading convenience path using the same machinery. Verify
execution subsystem or a compatibility resolver. against ConfigKit's selected public API before committing to an implementation
structure. This sketch should demonstrate reduced integration work, not merely
move source-context reconstruction or PromptKit validation into application code.
The earlier ConfigKit v1.3.0 feasibility assessment verified loading a typed
`promptkit` envelope with arbitrary siblings and explaining a section with native
paths, provenance, and redaction. It reported that effective-output writing,
opaque metadata, and comparison APIs were whole-result operations. That assessment
**does not establish support for the expanded application-owned load and
whole-result handoff**. Recheck current capabilities rather than assume that the
envelope alone solves the new integration contract.
Specifically establish:
- How PromptKit's rules compose with an application's configuration definition,
including defaults, normalization, identities, validation, and sensitivity.
- How the public handoff accepts an application-owned resolved result while
retaining usable field contexts and native inspection evidence.
- How selected bundled defaults and standalone fragments join the original load,
with the intended header/version rules.
- How native scoped effective output, metadata/history, explanations, and
comparisons support the inspection boundary, including absent sections.
If public APIs cannot support these responsibilities cleanly, identify the
specific gap and propose a focused upstream capability request before designing
workarounds. Keep such requests about public consumer capabilities, not ConfigKit
internals. A map-copy/reload adapter or an application-maintained duplicate of
PromptKit's configuration rules would defeat the accepted design.
### Implementation Scope And Validation
Then specify input/resolved Go shapes, registration and constructor signatures,
source-helper adaptations, and migration examples. Update identity registrations,
normalization, validation, bundled underlays, and inspection paths together.
Keep the repair-default and resolved-configuration changes separately reviewable;
the repair work need not wait for upstream integration capabilities. Neither needs
a new execution subsystem or a compatibility resolver.
Include focused checks for: Include focused checks for:
@@ -129,15 +214,21 @@ Include focused checks for:
budgets for `none`; cover typed and runtime inputs as well as YAML. budgets for `none`; cover typed and runtime inputs as well as YAML.
- Concrete budgets in inspection and prepared snapshots, with actual repair - Concrete budgets in inspection and prepared snapshots, with actual repair
counters retaining their existing meaning. counters retaining their existing meaning.
- An application-owned configuration type with sibling settings, one native load,
and a whole-result handoff that performs no second configuration load.
- Equivalent effective PromptKit resources through registered application loading
and standalone convenience loading when supplied equivalent sources.
- Mixed embedded/operator collections, source-relative message/schema references,
native inheritance and overrides, and field provenance surviving the handoff.
- Missing `promptkit` with bundled defaults enabled and disabled, application-owned - Missing `promptkit` with bundled defaults enabled and disabled, application-owned
root keys that resemble legacy settings, and unknown fields inside `promptkit`. root keys that resemble legacy settings, and unknown fields inside `promptkit`.
- Inspection and comparison excluding sibling application values, including a - Inspection and comparison excluding sibling application values, including a
change confined to a sibling section, while PromptKit paths and explanations sibling-only change, while preserving native paths, provenance, and redaction.
retain native provenance and redaction behavior.
No further product decisions are currently identified. Public API details and the The product direction is accepted. Exact API shapes, upstream capability gaps,
ConfigKit feasibility check remain planning work, not evidence that implementation and their consequences remain planning work. If feasibility requires changing the
has already been validated. agreed consumer workflow, surface that decision rather than narrowing the goal to
root-key relocation alone. No implementation feasibility is claimed by this roadmap.
## Further Candidates ## Further Candidates