From 649bb7dcf22d76aa8d51aceceba313f10b6ec6d3 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 01:50:53 +0000 Subject: [PATCH] Narrow resolved configuration handoff to typed value lookup --- docs/roadmap/next-release-considerations.md | 244 +++++++++++++------- 1 file changed, 155 insertions(+), 89 deletions(-) diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index 0aca558..cbc8332 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -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