Narrow resolved configuration handoff to typed value lookup

This commit is contained in:
2026-11-21 01:50:53 +00:00
parent 55276c9429
commit 649bb7dcf2

View File

@@ -86,28 +86,87 @@ join the original load; they do not disappear. The change removes context-transf
and duplicate-loading machinery, not application-specific execution requests,
profile selection, required-resource checks, or diagnostics policy.
### Configuration Rules And Handoff
### Narrow ConfigKit Addition And Library-Owned Wiring
Expose a small public integration surface for PromptKit's configuration rules to
participate in the application's ConfigKit load. Defaults, normalization, field
validation, collection identity constraints, and sensitivity declarations remain
PromptKit-owned rules applied through ConfigKit's native lifecycle. Applications
must not reproduce these rules or depend on PromptKit's internal types.
Use ConfigKit's proposed public lookup:
The exact public registration and result-accepting API shapes require planning.
The handoff must work with an application-owned result type, not require replacing
its configuration model with PromptKit's root document type. Preserve effective
values, source contexts for relative message/schema files, provenance, and native
redaction. A decoded map alone or a serialized section loaded again is not an
equivalent handoff.
```go
func (r *Result[T]) Value(path Path) (any, bool)
```
Register desired bundled defaults as ordinary underlays before composition;
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;
engine construction must not inject another configuration layer into an already
resolved result. Apply configured repair defaults from item 1 during resolution,
so inspection and execution agree. Runtime request defaulting remains separate.
resolved result. The sketch omits source assembly for brevity. Apply configured
repair defaults from item 1 during resolution; runtime request defaults remain
separate.
Retain source-loading construction as a convenience for consumers that want
PromptKit to select its own loading path. It should use the same configuration
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.
@@ -133,11 +192,9 @@ 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 must not impose
its standalone document version on the whole application. Planning must account
for application headers and optional PromptKit fragment headers in the same load,
including the standalone convenience path, without inventing a second header
parser or version-composition pass.
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
@@ -148,87 +205,96 @@ 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.
### Inspection Boundary
### Explicitly Deferred Capabilities
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.
**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.
Prefer native ConfigKit scoped inspection over PromptKit-maintained reporting
adapters. The requirement concerns the public scope and ownership of inspection;
it does not independently promise that ConfigKit never visits sibling data
internally. Do not silently substitute whole-application reporting, reconstruct
source history, or reload a copied section to manufacture a scoped result.
**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.
## Guidance For Implementation Planning
### Start With The Public Integration Contract
### Validate The Pattern Against PromptKit
Prepare a concrete consumer sketch covering registration, one application-owned
load, whole-result engine construction, and PromptKit-scoped inspection. Also show
the standalone source-loading convenience path using the same machinery. Verify
against ConfigKit's selected public API before committing to an implementation
structure. This sketch should demonstrate reduced integration work, not merely
move source-context reconstruction or PromptKit validation into application code.
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.
The earlier ConfigKit v1.3.0 feasibility assessment verified loading a typed
`promptkit` envelope with arbitrary siblings and explaining a section with native
paths, provenance, and redaction. It reported that effective-output writing,
opaque metadata, and comparison APIs were whole-result operations. That assessment
**does not establish support for the expanded application-owned load and
whole-result handoff**. Recheck current capabilities rather than assume that the
envelope alone solves the new integration contract.
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:
Specifically establish:
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.
- How PromptKit's rules compose with an application's configuration definition,
including defaults, normalization, identities, validation, and sensitivity.
- How the public handoff accepts an application-owned resolved result while
retaining usable field contexts and native inspection evidence.
- How selected bundled defaults and standalone fragments join the original load,
with the intended header/version rules.
- How native scoped effective output, metadata/history, explanations, and
comparisons support the inspection boundary, including absent sections.
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.
If public APIs cannot support these responsibilities cleanly, identify the
specific gap and propose a focused upstream capability request before designing
workarounds. Keep such requests about public consumer capabilities, not ConfigKit
internals. A map-copy/reload adapter or an application-maintained duplicate of
PromptKit's configuration rules would defeat the accepted design.
### Implementation Scope And Validation
Then specify input/resolved Go shapes, registration and constructor signatures,
source-helper adaptations, and migration examples. Update identity registrations,
normalization, validation, bundled underlays, and inspection paths together.
Keep the repair-default and resolved-configuration changes separately reviewable;
the repair work need not wait for upstream integration capabilities. Neither needs
a new execution subsystem or a compatibility resolver.
Include focused checks for:
### Focused Validation
- 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.
- An application-owned configuration type with sibling settings, one native load,
and a whole-result handoff that performs no second configuration load.
- Equivalent effective PromptKit resources through registered application loading
and standalone convenience loading when supplied equivalent sources.
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 field provenance surviving the handoff.
- Missing `promptkit` with bundled defaults enabled and disabled, application-owned
root keys that resemble legacy settings, and unknown fields inside `promptkit`.
- Inspection and comparison excluding sibling application values, including a
sibling-only change, while preserving native paths, provenance, and redaction.
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 product direction is accepted. Exact API shapes, upstream capability gaps,
and their consequences remain planning work. If feasibility requires changing the
agreed consumer workflow, surface that decision rather than narrowing the goal to
root-key relocation alone. No implementation feasibility is claimed by this roadmap.
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.
## Further Candidates