From 55276c94292b7e4518eb6139849a22c7053e505c Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 00:12:38 +0000 Subject: [PATCH] Plan application-owned ConfigKit resolution and whole-result handoff --- docs/roadmap/next-release-considerations.md | 195 ++++++++++++++------ 1 file changed, 143 insertions(+), 52 deletions(-) diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index ddd9356..0aca558 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -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 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 -`promptkit` key. This gives applications a distinct configuration section for -PromptKit alongside their other settings. Do not add a configurable mounting key. +**Accepted:** the application composes configuration once through ConfigKit and +passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit +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`, -`promptkit.prompts`, `promptkit.collections`, and `promptkit.schema_root`. -Collection-local fields remain inside their collection. ConfigKit-owned source -headers and directives retain their native semantics and locations; they do not -automatically move inside `promptkit`. +The root-key migration supports this handoff; changing YAML paths alone does not +fulfill the feature. The architectural benefit is a single composition lifecycle +with native source context and provenance, rather than an application bridge +between separately loaded configurations. + +### 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 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`, `backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit import destinations and PromptKit source helpers mount those fragments at the -appropriate nested location. This is fragment composition, not support for two -alternative application configuration layouts. Source-relative resource context -must continue to follow the effective contributing field. +appropriate nested location. Source-relative context follows the effective +contributing field, not the location of the application document or mount point. -PromptKit owns validation of its section, not sibling application settings. -Implementation planning must verify the ConfigKit loading boundary so that -unrelated application sections can coexist without PromptKit interpreting or -rejecting their contents. Keep field validation within PromptKit's section. +ConfigKit-owned headers and directives retain their native semantics. The +application owns its main configuration specification; PromptKit must not impose +its standalone document version on the whole application. Planning must account +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 -settings; bundled defaults can still operate. Old root-level keys such as -`prompts` and `profiles` are neither consumed nor specially rejected by PromptKit: -they may be legitimate application-owned settings. Unknown fields inside -`promptkit` remain configuration errors. This does not bypass ConfigKit's own -document/composition validation. Migration documentation must explain that an -unmigrated application document can load without contributing its intended -resources, with a missing prompt becoming apparent when selected. Do not add -legacy-layout detection to compensate for that consequence. +settings; selected bundled underlays can still contribute defaults during the +original load. Old root-level keys such as `prompts` and `profiles` are neither +consumed nor specially rejected by PromptKit: they may be application settings. +Unknown fields inside `promptkit` remain configuration errors. The application's +own validation and ConfigKit's document/composition rules still apply to the +whole document. Migration guidance must explain that unmigrated resources are +not loaded and can therefore produce missing-resource errors when selected. + +### Inspection Boundary Scope `InspectConfiguration` value reports and comparisons to PromptKit's section, 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 and explanation semantics. Resource inspection remains resource-scoped. -Implementation planning must cover: - -- Updating bundled underlays, source helpers, import destinations, identity - registrations, normalization, and validation to the new paths using ordinary - ConfigKit composition. -- 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. +Prefer native ConfigKit scoped inspection over PromptKit-maintained reporting +adapters. The requirement concerns the public scope and ownership of inspection; +it does not independently promise that ConfigKit never visits sibling data +internally. Do not silently substitute whole-application reporting, reconstruct +source history, or reload a copied section to manufacture a scoped result. ## Guidance For Implementation Planning -The product decisions above are accepted. Begin planning with a focused feasibility -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. +### Start With The Public Integration Contract -Then specify the concrete input/resolved Go shapes, source-helper adaptations, -and migration examples. Keep the repair-default and configuration-root changes -separately reviewable even if delivered in the same release. Neither needs a new -execution subsystem or a compatibility resolver. +Prepare a concrete consumer sketch covering registration, one application-owned +load, whole-result engine construction, and PromptKit-scoped inspection. Also show +the standalone source-loading convenience path using the same machinery. Verify +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: @@ -129,15 +214,21 @@ Include focused checks for: budgets for `none`; cover typed and runtime inputs as well as YAML. - Concrete budgets in inspection and prepared snapshots, with actual repair 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 root keys that resemble legacy settings, and unknown fields inside `promptkit`. - Inspection and comparison excluding sibling application values, including a - change confined to a sibling section, while PromptKit paths and explanations - retain native provenance and redaction behavior. + sibling-only change, while preserving native paths, provenance, and redaction. -No further product decisions are currently identified. Public API details and the -ConfigKit feasibility check remain planning work, not evidence that implementation -has already been validated. +The product direction is accepted. Exact API shapes, upstream capability gaps, +and their consequences remain planning work. If feasibility requires changing the +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