21 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. 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:
- The application includes PromptKit's configuration definition/registration and desired bundled or application sources in its ordinary ConfigKit setup.
- ConfigKit composes and resolves the complete application configuration once, applying each component's registered rules.
- 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.
Narrow ConfigKit Addition And Library-Owned Wiring
Adopt the proposed lookup and focused inspection capabilities in ConfigKit's typed value and inspection roadmap. That roadmap records agreed scope, not implemented APIs. Confirm availability before implementation; do not assume the current dependency supplies them. The lookup is:
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:
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:
type Configuration interface {
Value(configkit.Path) (any, bool)
Metadata() configkit.Metadata
SourceContext(string) (configkit.ResourceContext, bool)
InspectSubtree(configkit.Path) (configkit.Inspection, 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.
Retain the inspection view selected at /promptkit for configuration reporting.
This interface sketch is not final; planning must also specify how existing load
diagnostics are retained and forwarded.
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 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.
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.
Focused Configuration Inspection
Accepted: preserve resource listing and inspection, and provide configuration
reporting through ConfigKit's proposed non-generic Inspection view:
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; independent source-version
policies remain deferred.
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.
Deferred 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.
This remains outside both the accepted upstream addition and this migration; neither typed lookup nor focused inspection provides independent version checks.
Guidance For Implementation Planning
Validate The Pattern Against PromptKit
First confirm the final upstream lookup and inspection contracts 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:
- 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.
- 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.
- 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.
- Inspection facade and diagnostics. Retain the native focused view and specify
any public signature changes needed to forward it.
Valuecan succeed without completed-load evidence; do not treat that as proof of a valid inspection view. The proposed upstream method list does not explicitly includeDiagnostics. Resolve forwarding from the original result through PromptKit's consumer-owned interface, or use an upstream view method if supplied. Preserve useful load evidence without inventing component-specific diagnostic classification. - CommandKit integration. Coordinate migration of
ckprompt.ConfigScopeand resource adapters. Its shared loader currently callsInspectConfiguration()for sources and diagnostics even for resource commands; preserve those commands and their diagnostics during migration.ckconfig.Viewcurrently accepts a concrete*configkit.Metadata; forwarding that alone would expose unfiltered path discovery. Use the view's focused enumeration or apply the selected scope in the adapter. A PromptKit overview explanation must request/promptkit: the native empty path still selects the whole application. Keep explicit query paths native and document the broader contextual evidence and ancestor-diff semantics. Preserve operator capabilities rather than promise unchanged method signatures or rebuild ConfigKit behavior in CommandKit.
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
- Mode defaults after composition, null clearing an inherited repair budget,
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.
- Mixed embedded/operator collections, source-relative message/schema references, 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.
- Resource listings, resource reports, and load diagnostics through the migrated
CommandKit adapters; configuration output and overview explanations focused on
/promptkit, with native paths and redaction preserved. - Focused discovery through the adapter despite unfiltered metadata; explicit queries outside the focus and shared source/history context retain native behavior.
- Inspection remains frozen after settings mutation; absent, null, historical-only, and added/removed sections follow upstream semantics. Sibling difference records are excluded while ancestor differences remain; comparison works across different application root types selecting the same scope.
The product direction, including focused inspection, is accepted. Actual PromptKit integration, concrete public API shapes, diagnostic forwarding, CommandKit adapter migration, and the supported shared header policy remain planning work. Strict subtree isolation, a new comparison engine, and independent source-version policies are not required by this design.
Further Candidates
Append additional pre-release considerations here as they arise.