Plan configuration handoff and repair defaults

This commit is contained in:
2026-11-21 13:42:10 +00:00
parent 07aaee8ef6
commit 515649fee0
2 changed files with 660 additions and 129 deletions

View File

@@ -41,12 +41,9 @@ 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.
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`
@@ -91,9 +88,8 @@ profile selection, required-resource checks, or diagnostics policy.
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;
make the dependency upgrade separately reviewable before the configuration
refactor. The Go consumer minimum remains 1.27.0.
focused inspection APIs required here. PromptKit currently selects v1.3.0.
The Go consumer minimum remains 1.27.0.
The released lookup is:
@@ -113,7 +109,8 @@ 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.
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
@@ -132,7 +129,7 @@ definition := promptkit.Configure(
result, err := configkit.Load(source,
configkit.Options[AppConfig]{Definition: definition})
// Handle err before continuing.
engine, err := promptkit.NewFromConfig(result)
engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{})
```
One compiler-checked field selector per library is accepted registration wiring,
@@ -163,8 +160,7 @@ 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. Concrete PromptKit API names
remain implementation-planning work.
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
@@ -314,122 +310,22 @@ to both application-owned loading and standalone construction. Update examples
and migration guidance accordingly, without preparsing or stripping headers or
adding a second load.
## Guidance For Implementation Planning
## Integration Evidence And Scope
### Validate The Pattern Against PromptKit
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 actual PromptKit prototype check is complete; see the
[integration assessment](configuration-integration-check.md) for evidence,
the smaller three-method handoff interface, and remaining implementation work.
The checklist below records what the check needed to establish and guides
implementation coverage; production implementation is not complete.
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.
ConfigKit's released APIs and maintained
[one-library](../../../ConfigKit/examples/consumers/result_component.go) and
[two-library](../../../ConfigKit/examples/consumers/result_composition.go) examples
provide the integration starting point. They demonstrate typed registration,
whole-result handoff, owned settings capture, native inspection, and effective
source context without another load.
The release review passed PromptKit's full test suite against the published
v1.4.0 module using a temporary dependency file and Go 1.27.4. ConfigKit's focused
lookup, inspection, comparison, history, and component-example checks also passed.
This establishes compatibility with PromptKit's existing implementation. The
isolated prototype now also verifies the proposed handoff pattern; the production
handoff remains to be implemented.
The prototype demonstrates the typed registration helper,
one application-owned load, and whole-result engine construction. It also exercises
the standalone convenience path through the same rules. The checks cover:
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.
Include inline application-field maps at the accepted extension points and
preserve those values during PromptKit normalization.
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.
4. **Inspection facade and diagnostics.** Retain the native focused view and specify
public signatures for its operations and load-diagnostic forwarding. Obtain
diagnostics from the original result's `Diagnostics()` method through
PromptKit's consumer-owned interface. Expose focused enumeration
alongside native metadata and query operations. A PromptKit overview explanation
selects `/promptkit`; the native empty path selects the whole application.
Document what the interfaces do: their inputs, operations, outputs, and errors,
and how registration, loading, and engine construction fit together. Keep this
guidance concrete; hypothetical misuse does not call for registration tracking,
another validation lifecycle, or defensive caveats.
CommandKit neutrally exposes upstream PromptKit APIs. Any adapter updates are
routine downstream adoption, not a constraint on PromptKit's public API or a
prerequisite for completing this migration. PromptKit's implementation plan covers
its own resource, inspection, and diagnostic capabilities; CommandKit owns how
those are presented through CLI commands.
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 configuration refactor. 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 additional fields
at each accepted extension point. Recognized fields retain type and semantic
validation; nested PromptKit-owned objects retain their existing schemas.
- Additional fields survive native composition, inheritance, normalization, and
configuration inspection, including application-defined sensitivity. They remain
available to application validation and do not enter provider requests merely
because they appear on a resource definition.
- Resource inspection omits application-specific fields while configuration
inspection retains them under ConfigKit's native sensitivity rules.
- 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 PromptKit's
public APIs; configuration output and overview explanations focused on
`/promptkit`, with native paths and redaction preserved.
- Focused enumeration alongside 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, removal of resource-version
validation, and the configuration-only inspection of application-specific fields,
is settled. No product decisions remain before implementation planning.
Concrete public API shapes, diagnostic forwarding, and verification of the actual
PromptKit integration are implementation-planning work.
## Further Candidates
Append additional pre-release considerations here as they arise.
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.