Plan configuration handoff and repair defaults
This commit is contained in:
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user