2026-11-20 15:28:08 +00:00
|
|
|
# Feature Considerations Before The Next Release
|
|
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
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
|
2026-11-20 16:24:16 +00:00
|
|
|
[format reference](../formats.md#schemas).
|
2026-11-20 15:28:08 +00:00
|
|
|
|
|
|
|
|
## 1. Enable One Structured-Output Repair Attempt By Default
|
|
|
|
|
|
2026-11-20 19:10:24 +00:00
|
|
|
**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 |
|
|
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
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
|
2026-11-20 19:10:24 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-20 19:10:24 +00:00
|
|
|
Implementation planning must specify the presence-aware Go shape and migration
|
2026-11-20 19:20:32 +00:00
|
|
|
from the current integer field, and cover omission, null, and explicit zero across
|
2026-11-20 19:10:24 +00:00
|
|
|
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.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
2026-11-21 00:12:38 +00:00
|
|
|
## 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.
|
|
|
|
|
|
2026-11-21 01:50:53 +00:00
|
|
|
### Narrow ConfigKit Addition And Library-Owned Wiring
|
|
|
|
|
|
|
|
|
|
Use ConfigKit's proposed public lookup:
|
|
|
|
|
|
|
|
|
|
```go
|
|
|
|
|
func (r *Result[T]) Value(path Path) (any, bool)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
This is a proposed upstream API, not an implemented dependency assumed by this
|
|
|
|
|
roadmap. 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. Exact supported public settings value/pointer forms belong in planning.
|
|
|
|
|
|
|
|
|
|
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)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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)
|
|
|
|
|
Metadata() configkit.Metadata
|
|
|
|
|
SourceContext(string) (configkit.ResourceContext, bool)
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
|
|
Register desired bundled resources as ordinary underlays before composition;
|
2026-11-21 00:12:38 +00:00
|
|
|
engine construction must not inject another configuration layer into an already
|
2026-11-21 01:50:53 +00:00
|
|
|
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
|
2026-11-21 00:12:38 +00:00
|
|
|
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.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
2026-11-20 19:13:46 +00:00
|
|
|
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
|
2026-11-21 00:12:38 +00:00
|
|
|
appropriate nested location. Source-relative context follows the effective
|
|
|
|
|
contributing field, not the location of the application document or mount point.
|
2026-11-20 19:13:46 +00:00
|
|
|
|
2026-11-21 00:12:38 +00:00
|
|
|
ConfigKit-owned headers and directives retain their native semantics. The
|
2026-11-21 01:50:53 +00:00
|
|
|
application owns its main configuration specification; PromptKit's registration
|
|
|
|
|
must not replace that policy with its standalone document version rule.
|
|
|
|
|
Independent source-version policies are deferred as described below.
|
2026-11-20 19:13:46 +00:00
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
An absent `promptkit` section contributes no application-supplied PromptKit
|
2026-11-21 00:12:38 +00:00
|
|
|
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.
|
|
|
|
|
|
2026-11-21 01:50:53 +00:00
|
|
|
### Explicitly Deferred Capabilities
|
|
|
|
|
|
|
|
|
|
**Scoped configuration inspection:** native section-scoped effective output,
|
|
|
|
|
metadata/history, explanations, and comparison are outside this initial addition.
|
|
|
|
|
`Value` does not supply those capabilities or alter existing redacted inspection.
|
|
|
|
|
Resource inspection still describes PromptKit resources. Planning must state how
|
|
|
|
|
existing `InspectConfiguration` APIs are exposed on the new handoff path; do not
|
|
|
|
|
silently describe whole-application reports as component-scoped or introduce a
|
|
|
|
|
substantial local reporting framework to imitate the deferred feature. Resolve
|
|
|
|
|
any resulting public API availability/migration choice explicitly, without making
|
|
|
|
|
native scoped reporting a prerequisite for engine construction.
|
|
|
|
|
|
|
|
|
|
**Independent source-version policies:** different application and component
|
|
|
|
|
header policies within one load are outside this initial addition. ConfigKit's
|
|
|
|
|
existing shared-policy limitation remains. Planning must document a supported
|
|
|
|
|
source/header arrangement using current semantics, including the consequence for
|
|
|
|
|
application and collection documents declaring different specification versions.
|
|
|
|
|
Do not imply those headers are independently checked, overwrite the application's
|
|
|
|
|
policy, preparse/strip headers, or perform a second load to simulate the deferred
|
|
|
|
|
capability. Standalone construction retains its applicable native version policy.
|
|
|
|
|
|
|
|
|
|
These deferrals narrow the earlier roadmap and broader upstream request. Neither
|
|
|
|
|
capability is claimed to be solved by `Value`; both can be revisited separately.
|
2026-11-20 19:13:46 +00:00
|
|
|
|
2026-11-20 19:20:32 +00:00
|
|
|
## Guidance For Implementation Planning
|
|
|
|
|
|
2026-11-21 01:50:53 +00:00
|
|
|
### Validate The Pattern Against PromptKit
|
|
|
|
|
|
|
|
|
|
First confirm the final upstream lookup contract and availability. The ConfigKit
|
|
|
|
|
agent exercised representative one-library and two-library prototypes using
|
|
|
|
|
existing public callbacks plus a limited top-level lookup shim. Those passed
|
|
|
|
|
checks for defaults, normalization, validation, identities, sensitive inspection,
|
|
|
|
|
trusted secret access, and mounted resource lookup. They were not a production
|
|
|
|
|
`Value` implementation or a real PromptKit integration.
|
|
|
|
|
|
|
|
|
|
Prepare an actual PromptKit prototype demonstrating the typed registration helper,
|
|
|
|
|
one application-owned load, and whole-result engine construction. Also exercise
|
|
|
|
|
the standalone convenience path through the same rules. Focus on these checks:
|
|
|
|
|
|
|
|
|
|
1. **Public settings and callback composition.** Define a supported public settings
|
|
|
|
|
model suitable for ConfigKit decoding; existing typed source helpers are not
|
|
|
|
|
automatically that model. Preserve application callbacks, sensitivity, and
|
|
|
|
|
registrations when adding PromptKit's rules. Demonstrate explicit callback
|
|
|
|
|
ordering with a second representative component, without a registry. Keep
|
|
|
|
|
bundled underlay selection in the original load and specify its consumer API.
|
|
|
|
|
2. **Per-load presence capture.** The current resolver captures input presence and
|
|
|
|
|
repair-budget presence in private maps used later during resource construction.
|
|
|
|
|
Determine which facts can come directly from final metadata and which need
|
|
|
|
|
per-load captured state. Do not rely on historical reconstruction or a shared
|
|
|
|
|
helper closure that associates one load's state with another result. Verify
|
|
|
|
|
independent loads using the same configured definition.
|
|
|
|
|
3. **Ownership and source context.** Capture mutable settings appropriately at
|
|
|
|
|
engine construction. Verify effective origins and filesystem contexts survive
|
|
|
|
|
mounting, inheritance, and overrides. Document mutation-before-handoff behavior;
|
|
|
|
|
no mutation-detection subsystem or ConfigKit deep-copy guarantee is required.
|
|
|
|
|
|
|
|
|
|
Specify the concrete registration, settings, and constructor shapes, source-helper
|
|
|
|
|
adaptations, and migration examples after these checks. Identify any remaining
|
|
|
|
|
concrete gap rather than infer a need for a larger upstream framework. Keep the
|
|
|
|
|
repair-default and handoff changes separately reviewable; the repair work need not
|
|
|
|
|
wait for the proposed upstream lookup. Neither needs a new execution subsystem or
|
|
|
|
|
compatibility resolver.
|
|
|
|
|
|
|
|
|
|
### Focused Validation
|
2026-11-20 19:20:32 +00:00
|
|
|
|
|
|
|
|
- Mode defaults after composition, null clearing an inherited repair budget,
|
2026-11-21 01:50:53 +00:00
|
|
|
explicit zero, positive budgets, and rejection of positive budgets for `none`;
|
|
|
|
|
cover typed and runtime inputs as well as YAML.
|
|
|
|
|
- Concrete budgets in resource inspection and prepared snapshots; actual repair
|
|
|
|
|
counters retain their existing meaning.
|
|
|
|
|
- An application-owned type with siblings, typed component registration, one load,
|
|
|
|
|
and whole-result handoff with no post-load extraction or second load.
|
|
|
|
|
- Equivalent effective resources through registered application loading and
|
|
|
|
|
standalone convenience loading when supplied equivalent sources.
|
|
|
|
|
- Callback preservation and independent per-load state, including repeat loads
|
|
|
|
|
with the same definition and a representative second component.
|
2026-11-21 00:12:38 +00:00
|
|
|
- Mixed embedded/operator collections, source-relative message/schema references,
|
2026-11-21 01:50:53 +00:00
|
|
|
native inheritance and overrides, and effective field context at handoff.
|
|
|
|
|
- Unavailable paths, found nil values, zero/defaulted settings, and wrong section
|
|
|
|
|
types; source presence remains distinct from lookup availability.
|
|
|
|
|
- Missing application settings with bundled defaults enabled and disabled,
|
|
|
|
|
application-owned root keys resembling legacy settings, and unknown fields
|
|
|
|
|
inside `promptkit`.
|
|
|
|
|
- Engine independence from later caller mutation of settings, including nested
|
|
|
|
|
maps and slices; trusted lookup does not replace redacted inspection.
|
|
|
|
|
|
|
|
|
|
The narrower product direction is accepted. Actual PromptKit integration, concrete
|
|
|
|
|
public API shapes, treatment of configuration-inspection availability, and the
|
|
|
|
|
supported shared header policy remain planning work. Do not expand these into the
|
|
|
|
|
deferred scoped-inspection or independent-version features without a new decision.
|
2026-11-20 15:28:08 +00:00
|
|
|
|
|
|
|
|
## Further Candidates
|
|
|
|
|
|
|
|
|
|
Append additional pre-release considerations here as they arise.
|