Files
promptkit/docs/roadmap/configuration-integration-check.md

179 lines
11 KiB
Markdown

# 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.
Subsequent design decision: [ADR 0002](../adr/0002-shared-configuration-data-model.md)
selects one shared settings model exposed through root aliases. The assessment
below records the experiment as run; its separate settings declarations and
conversions are superseded by the [implementation plan](implementation.md).
## 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.
The prototype's public settings conversions were ordinary facade boundary work,
not another composition pass; the selected shared model removes them. 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/<namespace>`. 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.