# 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. 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 for engine construction, ignoring sibling application settings. Inspection uses the focused reporting semantics below. 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. ### ConfigKit v1.4.0 And Library-Owned Wiring Adopt [ConfigKit v1.4.0](../../../ConfigKit/docs/releases/v1.4.0.md) as a prerequisite for the configuration handoff. It releases the typed lookup and focused inspection APIs required here. PromptKit currently selects v1.3.0. The Go consumer minimum remains 1.27.0. The released lookup is: ```go func (r *Result[T]) Value(path Path) (any, bool) ``` It selects an existing typed value from `Result.Config` by configuration path (YAML/schema names). It performs no serialization, conversion, decoding, defaulting, validation, or additional load. It is trusted execution access, including resolved secrets; existing inspection remains redacted. Accept ordinary Go value semantics. Struct values are copied, while maps, slices, and pointers can share state with `Result.Config`; no new ConfigKit deep-copy or frozen-execution guarantee is required. Return the actual terminal value without automatic dereferencing. A found nil pointer differs from an unavailable path; traversal through nil cannot succeed. A declared zero/defaulted field can exist without YAML input, so input presence remains a metadata question. PromptKit checks the selected section's type and handles absence according to its configuration contract. Concrete supported settings forms are specified in the implementation plan. Expose public PromptKit settings and a small typed registration helper using existing ConfigKit APIs. The following is an illustrative consumer sketch, not implemented API names or a complete runnable example: ```go type AppConfig struct { OutputDirectory string `yaml:"output_directory"` PromptKit promptkit.Settings `yaml:"promptkit"` } definition := promptkit.Configure( configkit.Definition[AppConfig]{}, func(c *AppConfig) *promptkit.Settings { return &c.PromptKit }, ) result, err := configkit.Load(source, configkit.Options[AppConfig]{Definition: definition}) // Handle err before continuing. engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{}) ``` One compiler-checked field selector per library is accepted registration wiring, not post-load extraction. The application passes the whole result to the engine. PromptKit's helper composes its defaults, normalization, validation, sensitivity, and sequence identities with existing application rules at full `/promptkit` paths. Callback ordering stays explicit and application-controlled. Do not require applications to duplicate PromptKit rules or use internal types. No ConfigKit component registry, new lifecycle orchestration, or reflection-based registration is needed for this design. The proposed constructor can consume a PromptKit-owned interface such as: ```go type Configuration interface { Value(configkit.Path) (any, bool) InspectSubtree(configkit.Path) (configkit.Inspection, bool) Diagnostics() []configkit.Diagnostic } ``` It selects `Value(configkit.Keys("promptkit"))`, checks its type, and captures resources using native metadata and source contexts. Effective field origins are authoritative; do not recover a missing effective location from historical evidence. A serialized section loaded again is not an equivalent handoff. Retain the inspection view selected at `/promptkit` for configuration reporting. That view also supplies metadata and source contexts during capture, so the constructor interface need not repeat those methods. Load diagnostics come from the original result's `Diagnostics()` method; the inspection view does not supply that method. Retain and forward those records through PromptKit's configuration inspection facade. Register desired bundled resources as ordinary underlays before composition; engine construction must not inject another configuration layer into an already resolved result. The sketch omits source assembly for brevity. Apply configured repair defaults from item 1 during resolution; runtime request defaults remain separate. PromptKit must preserve its existing protection against caller mutation after engine construction by capturing owned settings where needed. A shallow struct copy alone does not detach maps and slices. Callers should hand off before mutating resolved values in ways that invalidate their frozen inspection/provenance evidence. Document this usage expectation rather than add mutation detection or demand a new ConfigKit snapshot facility. Retain source-loading construction as a convenience using the same registration 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 configuration version policy. PromptKit's registration preserves that policy; PromptKit-specific resource version validation is removed as described below. 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. Application-specific fields are accepted at the extension points below. 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. ### Application-Specific Fields **Accepted:** allow additional application-specific fields on prompt, profile, and backend definitions, on collection definitions, and at the `promptkit` section level. Use ConfigKit's native string-keyed inline maps (`yaml:",inline"`) in the public settings model to retain unmatched fields. Recognized fields keep their typed decoding and semantic validation, including required-field checks. Additional fields participate in ordinary ConfigKit composition and remain available in the resolved application configuration and native configuration inspection. Applications own their interpretation, validation, and sensitivity rules. PromptKit ignores these fields during execution; they do not become model parameters. `extra_params` retains its existing provider-parameter purpose. Recommend application-specific grouping, such as an `audita` mapping, to reduce future field-name collisions; do not require a naming prefix or wrapper. At these extension points, a misspelled optional PromptKit field can be accepted as an application field. Accept that tradeoff rather than introduce an extension registry or custom unknown-field detection. These extension points do not change the schemas of nested PromptKit-owned objects such as output contracts. Maps beneath application-specific keys retain ConfigKit's ordinary dynamic-value behavior. Standalone and application-owned loading use the same settings model. **Accepted inspection boundary:** retain application-specific fields in the resolved configuration and ConfigKit-backed `InspectConfiguration()` reports. `InspectPrompt`, `InspectProfile`, and `InspectBackend` continue to report PromptKit-understood fields and omit application-specific fields. This keeps resource reports simple: no additional metadata storage, copying, redaction integration, or public report fields are needed for these extensions. Applications can access their fields through the resolved configuration and configuration inspection; execution objects need not carry them. ### Focused Configuration Inspection **Accepted:** preserve resource listing and inspection, and provide configuration reporting through ConfigKit v1.4.0's non-generic `Inspection` view: ```go inspection, ok := result.InspectSubtree(configkit.Keys("promptkit")) ``` PromptKit's `InspectConfiguration()` forwards the view's capabilities without loading another configuration or rebuilding history, redaction, or comparison. Both application-owned loading and standalone construction use this reporting path. This replaces the earlier inspection deferral. The view is a reporting focus, not an isolation or access-control boundary. Accept ConfigKit's native behavior: - Effective output renders the selected subtree without enclosing application mappings, using frozen completed-load values and existing redaction, including sensitivity inherited from ancestors. Later settings mutation does not change that evidence. - Focused enumeration includes paths at or beneath `/promptkit`. Metadata remains unfiltered, and explicit explanation/history queries use native application paths and may query outside the focus. Do not rebase paths or add a separate restriction layer. - Sources and contextual evidence remain native and may describe other application settings. Do not assign exclusive source ownership or trim ancestor history and dependency evidence to manufacture an isolated report. - Comparison uses ConfigKit's existing frozen-configuration comparison and retains differences at, beneath, or above the focus. Sibling-only difference records are excluded, but ancestor records may include changes outside PromptKit. A nonempty report therefore does not necessarily establish that PromptKit settings changed. Preserve native ordering, sequence-atomic comparison, and paired redaction; do not implement a separate subtree comparison algorithm. - Views compare the same native location even when the application Go root types differ. Follow upstream's errors for mismatched scopes or unavailable views. - A valid absent scope still yields a view, allowing history and added/removed comparisons. Constructor success does not establish effective presence. Rendering an absent effective value fails without output; explicit null renders normally. Application-level inspection remains useful for the whole shared configuration. The focused view adds convenience and supports existing integrations without claiming exclusive access to PromptKit information. Resource APIs continue to select and describe logical prompts, profiles, and backends independently of configuration-tree paths. ### Resource Version Validation **Accepted:** this migration gives up PromptKit-specific validation of `version` fields in resource documents, including collection, prompt, and profile definitions. This is an intentional simplification with a small practical cost, not an unresolved compatibility requirement or a prerequisite for an upstream version-policy feature. The application retains ownership of ConfigKit's version policy. ConfigKit-owned headers and directives follow that policy and native composition semantics; PromptKit adds no separate resource-version checks. Apply this resource decision to both application-owned loading and standalone construction. Update examples and migration guidance accordingly, without preparsing or stripping headers or adding a second load. ## Integration Evidence And Scope The actual PromptKit prototype verified typed registration, one application-owned load, whole-result construction, and standalone loading through shared rules against ConfigKit v1.4.0. It also demonstrated final-metadata presence capture, effective source contexts, owned runtime values, and native focused reporting. See the [integration assessment](configuration-integration-check.md) for evidence and limits. This establishes feasibility, not completed production implementation. The [implementation plan](implementation.md) owns the concrete API choices, ordered work, migration steps, and verification needed to reach this target. The shared configuration-model simplification remains a separate [future idea](future.md#shared-configuration-data-model), rather than a change to the architecture policy or this feature's scope. CommandKit and other consumers own their adapters and presentation. Their adoption is not a prerequisite for implementing PromptKit's resource, inspection, and diagnostic capabilities. Neither accepted feature requires a new execution subsystem, another configuration resolver, or an upstream component framework.