Narrow resolved configuration handoff to typed value lookup
This commit is contained in:
@@ -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,
|
and duplicate-loading machinery, not application-specific execution requests,
|
||||||
profile selection, required-resource checks, or diagnostics policy.
|
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
|
Use ConfigKit's proposed public lookup:
|
||||||
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.
|
|
||||||
|
|
||||||
The exact public registration and result-accepting API shapes require planning.
|
```go
|
||||||
The handoff must work with an application-owned result type, not require replacing
|
func (r *Result[T]) Value(path Path) (any, bool)
|
||||||
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.
|
|
||||||
|
|
||||||
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
|
engine construction must not inject another configuration layer into an already
|
||||||
resolved result. Apply configured repair defaults from item 1 during resolution,
|
resolved result. The sketch omits source assembly for brevity. Apply configured
|
||||||
so inspection and execution agree. Runtime request defaulting remains separate.
|
repair defaults from item 1 during resolution; runtime request defaults remain
|
||||||
|
separate.
|
||||||
|
|
||||||
Retain source-loading construction as a convenience for consumers that want
|
PromptKit must preserve its existing protection against caller mutation after
|
||||||
PromptKit to select its own loading path. It should use the same configuration
|
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
|
rules and engine-capture path: load once, then hand off the result. Do not maintain
|
||||||
two independent implementations of configuration semantics. Existing source
|
two independent implementations of configuration semantics. Existing source
|
||||||
selection choices remain available subject to the accepted layout migration.
|
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.
|
contributing field, not the location of the application document or mount point.
|
||||||
|
|
||||||
ConfigKit-owned headers and directives retain their native semantics. The
|
ConfigKit-owned headers and directives retain their native semantics. The
|
||||||
application owns its main configuration specification; PromptKit must not impose
|
application owns its main configuration specification; PromptKit's registration
|
||||||
its standalone document version on the whole application. Planning must account
|
must not replace that policy with its standalone document version rule.
|
||||||
for application headers and optional PromptKit fragment headers in the same load,
|
Independent source-version policies are deferred as described below.
|
||||||
including the standalone convenience path, without inventing a second header
|
|
||||||
parser or version-composition pass.
|
|
||||||
|
|
||||||
An absent `promptkit` section contributes no application-supplied PromptKit
|
An absent `promptkit` section contributes no application-supplied PromptKit
|
||||||
settings; selected bundled underlays can still contribute defaults during the
|
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
|
whole document. Migration guidance must explain that unmigrated resources are
|
||||||
not loaded and can therefore produce missing-resource errors when selected.
|
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,
|
**Scoped configuration inspection:** native section-scoped effective output,
|
||||||
retaining actual `promptkit.…` paths and relevant source provenance. Unrelated
|
metadata/history, explanations, and comparison are outside this initial addition.
|
||||||
application values must not become part of PromptKit's reports or comparisons
|
`Value` does not supply those capabilities or alter existing redacted inspection.
|
||||||
merely because they share an input document. Preserve native ConfigKit redaction
|
Resource inspection still describes PromptKit resources. Planning must state how
|
||||||
and explanation semantics. Resource inspection remains resource-scoped.
|
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
|
**Independent source-version policies:** different application and component
|
||||||
adapters. The requirement concerns the public scope and ownership of inspection;
|
header policies within one load are outside this initial addition. ConfigKit's
|
||||||
it does not independently promise that ConfigKit never visits sibling data
|
existing shared-policy limitation remains. Planning must document a supported
|
||||||
internally. Do not silently substitute whole-application reporting, reconstruct
|
source/header arrangement using current semantics, including the consequence for
|
||||||
source history, or reload a copied section to manufacture a scoped result.
|
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
|
## 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
|
First confirm the final upstream lookup contract and availability. The ConfigKit
|
||||||
load, whole-result engine construction, and PromptKit-scoped inspection. Also show
|
agent exercised representative one-library and two-library prototypes using
|
||||||
the standalone source-loading convenience path using the same machinery. Verify
|
existing public callbacks plus a limited top-level lookup shim. Those passed
|
||||||
against ConfigKit's selected public API before committing to an implementation
|
checks for defaults, normalization, validation, identities, sensitive inspection,
|
||||||
structure. This sketch should demonstrate reduced integration work, not merely
|
trusted secret access, and mounted resource lookup. They were not a production
|
||||||
move source-context reconstruction or PromptKit validation into application code.
|
`Value` implementation or a real PromptKit integration.
|
||||||
|
|
||||||
The earlier ConfigKit v1.3.0 feasibility assessment verified loading a typed
|
Prepare an actual PromptKit prototype demonstrating the typed registration helper,
|
||||||
`promptkit` envelope with arbitrary siblings and explaining a section with native
|
one application-owned load, and whole-result engine construction. Also exercise
|
||||||
paths, provenance, and redaction. It reported that effective-output writing,
|
the standalone convenience path through the same rules. Focus on these checks:
|
||||||
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.
|
|
||||||
|
|
||||||
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,
|
Specify the concrete registration, settings, and constructor shapes, source-helper
|
||||||
including defaults, normalization, identities, validation, and sensitivity.
|
adaptations, and migration examples after these checks. Identify any remaining
|
||||||
- How the public handoff accepts an application-owned resolved result while
|
concrete gap rather than infer a need for a larger upstream framework. Keep the
|
||||||
retaining usable field contexts and native inspection evidence.
|
repair-default and handoff changes separately reviewable; the repair work need not
|
||||||
- How selected bundled defaults and standalone fragments join the original load,
|
wait for the proposed upstream lookup. Neither needs a new execution subsystem or
|
||||||
with the intended header/version rules.
|
compatibility resolver.
|
||||||
- How native scoped effective output, metadata/history, explanations, and
|
|
||||||
comparisons support the inspection boundary, including absent sections.
|
|
||||||
|
|
||||||
If public APIs cannot support these responsibilities cleanly, identify the
|
### Focused Validation
|
||||||
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:
|
|
||||||
|
|
||||||
- Mode defaults after composition, null clearing an inherited repair budget,
|
- Mode defaults after composition, null clearing an inherited repair budget,
|
||||||
explicit zero, explicit positive budgets, and the existing rejection of positive
|
explicit zero, positive budgets, and rejection of positive budgets for `none`;
|
||||||
budgets for `none`; cover typed and runtime inputs as well as YAML.
|
cover typed and runtime inputs as well as YAML.
|
||||||
- Concrete budgets in inspection and prepared snapshots, with actual repair
|
- Concrete budgets in resource inspection and prepared snapshots; actual repair
|
||||||
counters retaining their existing meaning.
|
counters retain their existing meaning.
|
||||||
- An application-owned configuration type with sibling settings, one native load,
|
- An application-owned type with siblings, typed component registration, one load,
|
||||||
and a whole-result handoff that performs no second configuration load.
|
and whole-result handoff with no post-load extraction or second load.
|
||||||
- Equivalent effective PromptKit resources through registered application loading
|
- Equivalent effective resources through registered application loading and
|
||||||
and standalone convenience loading when supplied equivalent sources.
|
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,
|
- Mixed embedded/operator collections, source-relative message/schema references,
|
||||||
native inheritance and overrides, and field provenance surviving the handoff.
|
native inheritance and overrides, and effective field context at handoff.
|
||||||
- Missing `promptkit` with bundled defaults enabled and disabled, application-owned
|
- Unavailable paths, found nil values, zero/defaulted settings, and wrong section
|
||||||
root keys that resemble legacy settings, and unknown fields inside `promptkit`.
|
types; source presence remains distinct from lookup availability.
|
||||||
- Inspection and comparison excluding sibling application values, including a
|
- Missing application settings with bundled defaults enabled and disabled,
|
||||||
sibling-only change, while preserving native paths, provenance, and redaction.
|
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,
|
The narrower product direction is accepted. Actual PromptKit integration, concrete
|
||||||
and their consequences remain planning work. If feasibility requires changing the
|
public API shapes, treatment of configuration-inspection availability, and the
|
||||||
agreed consumer workflow, surface that decision rather than narrowing the goal to
|
supported shared header policy remain planning work. Do not expand these into the
|
||||||
root-key relocation alone. No implementation feasibility is claimed by this roadmap.
|
deferred scoped-inspection or independent-version features without a new decision.
|
||||||
|
|
||||||
## Further Candidates
|
## Further Candidates
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user