From 49ea85680e0a90e14ea66b19e8a0cafef3982a42 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 13:13:49 +0000 Subject: [PATCH] Record configuration handoff integration results --- .../configuration-integration-check.md | 172 ++++++++++++++++++ docs/roadmap/next-release-considerations.md | 21 ++- 2 files changed, 186 insertions(+), 7 deletions(-) create mode 100644 docs/roadmap/configuration-integration-check.md diff --git a/docs/roadmap/configuration-integration-check.md b/docs/roadmap/configuration-integration-check.md new file mode 100644 index 0000000..9c6555b --- /dev/null +++ b/docs/roadmap/configuration-integration-check.md @@ -0,0 +1,172 @@ +# Application Configuration Handoff Integration Check + +Status: completed integration assessment, not production implementation. +Background and accepted scope: [next-release considerations](next-release-considerations.md#2-consume-application-resolved-configuration-under-promptkit). + +## Conclusion + +The proposed one-load handoff works against PromptKit's real configuration +adapter, engine assembly, renderer, preparation, validation, and runner. ConfigKit +v1.4.0 supplies the needed capabilities. No upstream enhancement or additional +configuration lifecycle is required before implementation planning. + +Keep the implementation centered on typed registration, owned resource capture, +and native focused inspection. The existing execution subsystem can remain. + +## Baseline And Experiment + +- PromptKit baseline: `16f8197`. +- Dependency selected in the disposable copy: published + `go.maximumdirect.net/configkit v1.4.0`. +- Toolchain: locally installed Go 1.27.4, `GOTOOLCHAIN=local`, `GOWORK=off`. +- Prototype: `/tmp/promptkit-handoff-check.OXPnVY`, copied from the baseline. + Production source and dependency files were not changed. + +The experiment added ordinary public settings declarations in the root facade, +with explicit typed conversions to the internal adapter. It did not expose +internal representations through public aliases. Native inline maps retain +application fields at the five accepted extension points. Existing typed source +helpers remain a separate concept from the settings model used for decoding. + +An external-package consumer embedded those settings in an application-owned Go +type, registered PromptKit rules, loaded application and library sources once, and +passed the whole result to the prototype constructor. The constructor captured +resources and reused PromptKit's existing engine assembly. Standalone construction +used the same rules and capture path after its own single load. + +The temporary copy is exploratory evidence, not a patch ready to merge. Its +generated conversion boilerplate and experimental names are not proposed as a +new generator or a finalized public API. + +## Results + +| Area | Evidence | +| --- | --- | +| Callback composition | Application defaults, version acceptance, resolution, validation warnings, sensitivity, and sequence identities survived registration. A second component ran explicitly after PromptKit normalization. | +| Independent loads | Reusing one configured definition preserved omitted versus explicit input values across successive loads. Concurrent independent loads passed under the race detector. | +| Final presence | Final native metadata supplied required/content-type/description presence, including inherited values, normalized text, explicit false, omission, and nullable metadata. Resolver-side capture was unnecessary for the tested facts. | +| Source context | A mounted collection inherited messages and schemas from one filesystem while an overriding message used another. Capture opened effective message files without reopening configuration documents. Inherited schemas remained usable during preparation and execution. | +| Ownership | Later mutations to model pointers, input slices, nested provider maps, schema paths, and inline schema maps/arrays did not change captured execution. Inspection stayed frozen. | +| Extension fields | Section, collection, backend, profile, and prompt extensions survived composition and normalization. Focused configuration output retained them with application sensitivity. Prompt resource reporting omitted them, and they did not become provider parameters. Nested output objects remained strict. | +| Missing and invalid sections | Missing fields, declared zero settings, typed nil pointers, explicit null, and empty settings were exercised. Bundles contributed only when selected before loading. Wrong section types failed construction. Legacy-looking application root keys were left to the application. | +| Resource helpers | Wrapperless collection documents and `id`-first prompt files mounted through native destinations/item placement; resource IDs and listings were unchanged by the wrapper. | +| Inspection | The actual PromptKit facade forwarded diagnostics, focused output, enumeration, explanations, and cross-root-type comparisons. Native checks also covered absent/null scopes, historical-only paths, additions/removals, sibling exclusion, atomic ancestor differences, and ancestor sensitivity. Metadata and explicit queries remained unfiltered. | +| Version ownership | The application retained its own version rule. Resource-level `version` fields could be application data without a PromptKit-specific version check. | +| Repair presence | The prototype's pointer-valued configuration budget selected mode defaults after composition. Omission/null, explicit zero, budgets two/three, `none` rejection of positive budgets, and null clearing an inherited budget passed. Captured budgets were concrete. | + +The repair checks establish compatibility of configuration defaulting with the +handoff. They do not constitute implementation or validation of the separate +runtime output-contract API migration or the complete repair-default feature. + +## Simplest Supported Integration + +### Registration + +Retain a small generic helper accepting an existing `configkit.Definition[T]` +and a `func(*T) *Settings` selector. The experiment preserved existing callbacks, +appended library sequence registrations, combined sensitivity predicates, and +left application defaults and version policy intact. Existing callbacks ran +before library callbacks; a consumer could wrap the returned callbacks to run +another component afterward. No component registry was needed. + +Keep actual normalization and validation in one internal rule implementation. +Public settings conversions are ordinary facade boundary work, not another +composition pass. Capture owned execution values after successful loading. +The existing public source-construction types need not become the decoding model +merely because some fields resemble it. + +### Whole-Result Constructor + +The consumer-owned constructor interface can be smaller than the roadmap sketch: + +```go +type Configuration interface { + Value(configkit.Path) (any, bool) + InspectSubtree(configkit.Path) (configkit.Inspection, bool) + Diagnostics() []configkit.Diagnostic +} +``` + +The native inspection view already supplies `Metadata()` and `SourceContext()`. +A test passed a wrapper exposing precisely the three methods above, rather than +relying on accidental access to additional `Result[T]` methods. + +The constructor selects `/promptkit`, accepts the public settings value or +pointer, obtains the focused view, captures diagnostics from the original result, +and captures the runtime resources. Missing/nil settings contribute no resources; +an incompatible nonnil section type returns an ordinary construction error. +It performs no configuration load or implicit bundled-resource injection. + +The prototype retained the inspection view and diagnostics, rather than retaining +the mutable whole application result. One detached metadata snapshot served +construction-time presence and origin lookup; runtime did not need a provenance +resolver. Filesystem capabilities needed for schema preparation remained on +captured resource bindings. + +Stored diagnostics require the existing detached-return behavior: copy their +primary location and related-location slice when returning them. The prototype +checked that mutating returned diagnostics did not alter a later report. This is +small ownership work, not another diagnostics or inspection implementation. + +Final constructor spelling and runtime-options packaging belong in the staged +plan. The experiment reused the existing `Config` argument for runtime +collaborators; production API design should make clear that handoff construction +does not use its source-loading fields. + +### Inspection And Source Assembly + +Retain the existing reporting facade and add scoped enumeration: + +```go +func (v ConfigurationInspection) HistoricalPaths() []configkit.Path +``` + +Its existing `Metadata`, `Sources`, `Diagnostics`, `Explain`, `WriteEffective`, +`WriteExplanation`, and `Diff` signatures can remain, with focused semantics +documented as accepted in the feature roadmap. Delegate comparison directly to +the native views. `/promptkit` selects a PromptKit overview; the native empty path +still selects the whole application for explicit explanation. + +Expose bundled resources as an ordinary underlay already mounted at `/promptkit`. +Applications include it before their original load. Standalone construction +selects that underlay before loading and then invokes the shared capture path. +Use native destinations for wrapperless fragments, and update `CollectionInput` +to `/promptkit/collections/`. File discovery and imports continue +using their existing responsibilities and ConfigKit contexts. + +## Machinery The Implementation Can Remove Or Avoid + +- Resolver closures that capture one load's input-presence maps. Read the needed + final metadata during capture instead. +- The repair-presence side map once inspection reports the resolved budget. +- The adapter's dependency on `*configkit.Result[document]` and its generic + comparison bridge. Retain a native non-generic view plus diagnostics instead. +- PromptKit-specific resource-version checking. +- A second library configuration load, transferred application context, custom + inspection filtering/rebasing, historical fallback, and registration tracking. + +Keep ownership copying at the capture boundary. Application extensions need only +remain in the application result and native inspection; the final implementation +need not copy or carry them into execution objects. No new snapshot or mutation +detection facility is indicated by this check. + +## Validation And Limits + +The final prototype passed: + +```sh +go test -race . -run '^TestHandoffPrototype' -count=3 +go vet . +``` + +Production-file vet also passed for the modified internal configuration and +engine packages. Package-level internal vet encountered baseline tests coupled +to the former private `state.result` field; those tests and the old-layout suite +were intentionally not migrated in this experiment. This is not a claim that a +complete feature implementation or migrated repository-wide suite is finished. + +The implementation sprint still needs the separately reviewable dependency +upgrade, final public declarations and ownership adapters, source-helper and +fixture migration, runtime repair-input changes, full-suite validation, and +canonical documentation updates. These are local implementation work, not an +upstream API blocker or a new product decision. diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index b918162..5ff1d13 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -149,8 +149,6 @@ 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) InspectSubtree(configkit.Path) (configkit.Inspection, bool) Diagnostics() []configkit.Diagnostic } @@ -161,6 +159,8 @@ 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. Retain the inspection view selected at `/promptkit` for configuration reporting. +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 @@ -318,6 +318,12 @@ adding a second load. ### Validate The Pattern Against PromptKit +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. + ConfigKit's released APIs and maintained [one-library](../../../ConfigKit/examples/consumers/result_component.go) and [two-library](../../../ConfigKit/examples/consumers/result_composition.go) examples @@ -328,12 +334,13 @@ 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 new -PromptKit handoff remains to be implemented and verified. +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. -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: +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