7.9 KiB
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.
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. Place Configuration Under A Root-Level promptkit Key
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.
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.
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. This is fragment composition, not support for two
alternative application configuration layouts. Source-relative resource context
must continue to follow the effective contributing field.
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.
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.
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.
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.
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.
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.
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.
- Missing
promptkitwith bundled defaults enabled and disabled, application-owned root keys that resemble legacy settings, and unknown fields insidepromptkit. - 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.
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.
Further Candidates
Append additional pre-release considerations here as they arise.