# Feature Considerations Before The Next Release Status: items 1 and 2 record accepted design decisions. Review these items before the next release; this document does not authorize implementation or commit either item to that release. Implemented schema support is documented in the [format reference](../formats.md#schemas). ## 1. Enable One Structured-Output Repair Attempt By Default **Accepted:** default to one repair attempt for every validation mode that supports repair. This gives structurally invalid or empty output one automatic correction opportunity without requiring each consumer to opt in. | Validation mode | Default repair attempts | | --- | ---: | | `none` | 0 | | `basic` | 1 | | `json` | 1 | | `json_schema` | 1 | Use a presence-aware public input `RepairAttempts` field: omission or final null selects the mode's default; explicit zero disables repairs. Accepting null is a deliberate change from the current configuration contract. Authors can clear an inherited budget with null through ordinary ConfigKit composition; PromptKit interprets the final value without replaying that composition. Retain explicit budgets of two or three for eligible modes. Keep the existing rejection of positive budgets for `none`. Choose one rather than two as the default; consumers can opt into another correction opportunity when appropriate for their workloads. Apply defaults after ConfigKit composition, preserving explicit values. Execution and inspection use the resolved concrete budget. Apply the same mode defaults to omitted runtime output-contract budgets; runtime contracts still replace the configured contract completely. Prepared execution retains its resolved budget. Confine presence awareness to inputs. A `*int` is the recommended Go input shape: nil selects the default and a pointer to zero disables repair. Resolved inspection and prepared details expose the concrete budget; execution uses a concrete integer. Counters reporting repairs actually performed remain ordinary integers. Do not propagate optional-value handling into execution or counters solely to accommodate input defaulting. Implementation planning must specify the presence-aware Go shape and migration from the current integer field, and cover omission, null, and explicit zero across configuration, typed helpers, and runtime contracts. Document that repair runs 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. Consume Application-Resolved Configuration Under `promptkit` **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 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, or a second merge/precedence pass. Runtime resource IDs and namespace selection remain unchanged; the configuration wrapper is not part of a resource ID. 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. Source-relative context follows the effective contributing field, not the location of the application document or mount point. 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; 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 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. 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 ### Start With The Public Integration Contract 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: - Mode defaults after composition, null clearing an inherited repair budget, explicit zero, explicit positive budgets, and the existing rejection of positive 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 sibling-only change, while preserving native paths, provenance, and redaction. 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 Append additional pre-release considerations here as they arise.