diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md new file mode 100644 index 0000000..12796c9 --- /dev/null +++ b/docs/roadmap/implementation.md @@ -0,0 +1,635 @@ +# Next-Release Configuration And Repair Implementation Plan + +## Objective And Authority + +Implement both accepted features in +[next-release-considerations.md](next-release-considerations.md): mode-dependent +repair defaults and application-owned, one-load configuration handoff under +`promptkit`. The [integration assessment](configuration-integration-check.md) +establishes feasibility against ConfigKit v1.4.0; it is evidence, not production +code to merge wholesale. + +Baseline: PromptKit `07aaee8`, ConfigKit v1.3.0, consumer Go minimum 1.27.0. +Reinspect the working tree before starting. Preserve unrelated work. Read +[development](../development.md) and the applicable policies, especially +[agents](../policy/agents.md), [architecture](../policy/architecture.md), +[testing](../policy/testing.md), [documentation](../policy/documentation.md), and +[OSS](../policy/oss.md). Preserve the accepted +[configuration boundary ADR](../adr/0001-configuration-boundary.md). + +The audience is a Luna coding agent. Execute the numbered stages in order as a +single end-to-end sprint. Each stage bounds one prompt's work; it is not a +human-review, upstream-publication, or intermediate green-build gate. Intermediate +commits may contain expected compilation failures or unmigrated fixtures. Record +those honestly and continue to the dependent stage. Do not add temporary legacy +loaders or compatibility types merely to keep intermediate states compiling. +Run focused checks when their dependencies are ready; final correctness requires +the complete end state and validation in Stage 17. Follow the commit policy for +completed, nonempty units; do not create empty commits. + +## Scope And Design Decisions + +- Use the published ConfigKit v1.4.0 module without local replacements. Keep the + consumer minimum at Go 1.27.0. No sibling-repository change is needed. +- Keep the root facade and internal implementation boundary. The shared-model + proposal in [future.md](future.md#shared-configuration-data-model) is not part + of this sprint: no public aliases for internal settings and no new public + settings package. Use explicit facade data declarations and typed conversions. +- ConfigKit owns acquisition, composition, inheritance, source-version policy, + and native inspection. PromptKit interprets final values and captures its + resources. Do not inspect raw contributions or replay history for execution. +- The canonical location is fixed at `/promptkit`. Runtime IDs and namespace + rules do not acquire that prefix. Remove PromptKit-specific resource-version + checks; do not introduce legacy-path detection or another merge pass. +- Registration supplies normalizers, final-value validators, sensitivity, and + sequence identities. Engine construction captures resources without loading + configuration again. Both constructors share capture and engine assembly. +- Retain the runner, repair loop, prepared-execution ownership, capacity pools, + schema preparation, observers, and model clients. Change only the inputs and + wiring needed here; preserve their substantive behavior. +- Application fields remain in resolved settings and native configuration + inspection. Resource inspection and execution use PromptKit-understood fields. + Do not add extension registries, provider parameters, or extension-specific + resource-report payloads. + +### Public API To Implement + +Use the following names and shapes. Public declarations have GoDoc; the code and +canonical docs become their owners when implemented. + +```go +type Configuration interface { + Value(configkit.Path) (any, bool) + InspectSubtree(configkit.Path) (configkit.Inspection, bool) + Diagnostics() []configkit.Diagnostic +} + +func Configure[T any](definition configkit.Definition[T], + selectSettings func(*T) *Settings) configkit.Definition[T] + +type RuntimeConfig struct { + Timeout time.Duration + HTTPClient *http.Client + TransientRetries *int +} + +func NewFromConfig(result Configuration, cfg RuntimeConfig, + opts ...Option) (*Engine, error) + +func SettingsInput(source configkit.Source) configkit.Input +func BundledOpenRouterUnderlay() configkit.Underlay +func (v ConfigurationInspection) HistoricalPaths() []configkit.Path +``` + +`RuntimeConfig` has the existing `Config` runtime-field semantics. Keep the +existing `Config` fields and `NewEngine(Config, ...Option)` API rather than +requiring unrelated changes to its struct literals. The new constructor has no +source fields. Existing collaborator options apply to either constructor; +`WithBundledOpenRouter` selects sources only for `NewEngine` and has no effect on +an already resolved handoff. Nil options keep their existing behavior. + +Registration takes a nonnil selector for the application's field. A selector +returning nil means that optional settings section has no values to normalize or +validate; do not allocate it just to register rules. Preserve application +`Defaults` and `Version`. Run pre-existing `Resolve` first, then PromptKit +resolution, propagating its error. Run pre-existing `Validate` first, then +PromptKit validation. OR the sensitivity predicates and append PromptKit sequence +identities using an owned registration slice. Consumers can wrap the returned +callbacks to run other work afterward. No registration tracking is required. + +Handoff accepts `Settings`, `*Settings`, an unavailable selection, or a nil +selection at the fixed path. Missing/nil selections contribute no resources; +other section types fail with `ErrInvalidConfig`. Distinguish lookup availability +from explicit input presence using final metadata. A nil result or an unavailable +native inspection view also fails construction; do not synthesize inspection by +loading again. Ordinary construction failures preserve their underlying causes +through the existing public error mapping. + +The application includes PromptKit's rules in its original successful load, +through `Configure` or equivalent explicit callback composition. Construction +does not rerun that lifecycle or track which helper registered the rules. + +### Settings Model + +Add ordinary root-package structs with these fields, corresponding to the +current adapter records in `internal/configuration/load.go`. All configuration +fields have explicit existing snake-case YAML tags; `Application` is the native +`map[string]any` field tagged `yaml:",inline"`. + +| Public type | Fields | +| --- | --- | +| `Settings` | `SchemaRoot *string`; `Backends []BackendSettings`; `Profiles []ProfileSettings`; `Prompts []PromptSettings`; `Collections map[string]CollectionSettings`; `Application` | +| `CollectionSettings` | `ReleaseVersion, SchemaRoot *string`; the same three resource slices; `Application` | +| `BackendSettings` | `ID string`; `Endpoint, APIKeyEnv *string`; `ConcurrencyLimit, QueueCapacity *int`; `ExtraParams map[string]any`; `SmokeTests *BackendSmokeTestConfig`; `Application` | +| `ProfileSettings` | `ID string`; `Backend, Endpoint, Model *string`; `Temperature, TopP *float64`; `MaxTokens, TimeoutSeconds *int`; `ServiceTier, ReasoningEffort, APIKeyEnv *string`; `APIKeyRequired *bool`; `ExtraParams map[string]any`; `Application` | +| `PromptSettings` | `ID string`; `DefaultProfile, Description, SessionID *string`; `Inputs []PromptInputSettings`; `Messages []PromptMessageSettings`; `Output *PromptOutputSettings`; `Application` | +| `PromptInputSettings` | `Name string`; `Required bool`; `ContentType, Description *string` | +| `PromptMessageSettings` | `Role, Content, ContentFile *string`; `CacheControl *PromptCacheControlSettings` | +| `PromptCacheControlSettings` | `Type, TTL *string` | +| `PromptOutputSettings` | `Format, ValidationMode *string`; `Schema any`; `SchemaFile, SchemaPath *string`; `RepairAttempts *int` | + +Reuse the existing public backend smoke/probe data types, whose fields and YAML +bindings already match. Keep all nested PromptKit-owned objects strict. No +`Version` or `Extends` field is needed in this effective settings model: ConfigKit +handles inheritance controls before decoding, and resource `version` data can +reside in the allowed inline maps. Existing `PromptConfig`, `ProfileConfig`, and +`BackendConfig` remain source-construction values, including their `Extends` +fields; they are not substitutes for these decoding types. + +Provide corresponding internal adapter data types where needed for typed +conversion; public signatures do not expose them. Conversions preserve nil versus +empty containers, pointers, all known fields, and application maps through +normalization. They do not serialize, decode again, or apply precedence. + +### Repair Input And Resolved Types + +Keep public `OutputContract` and internal `domain.OutputContract` as resolved +values with `RepairAttempts int`. Add public `OutputContractInput` with the same +format, validation mode, schema, and schema-path fields, but +`RepairAttempts *int` (`json:"repair_attempts,omitempty"`). Change +`RunRequest.Validation` to `*OutputContractInput`, preserving its field name and +whole-contract replacement semantics. Add the corresponding internal request +input value rather than putting optional budgets on execution contracts. + +Configuration `PromptOutputConfig.RepairAttempts`, settings budgets, and runtime +input budgets use pointers. Nil (including final YAML/JSON null) selects zero for +`none`, one for `basic`, `json`, or `json_schema`. Explicit zero disables repair; +two and three remain supported. Existing validation rejects negative budgets, +budgets above three, unknown validation modes, and positive budgets for `none`. +Do not introduce a default validation mode or change existing format defaults. + +Public `PromptOutputInspection.RepairAttempts` becomes a concrete `int`, emitted +even when zero; prepared details continue using resolved `OutputContract`. +Actual repair counters remain unchanged integers. Resolve configured budgets +after composition; resolve replacement budgets from the replacement's mode, +without inheriting the prompt's budget. Resolve defaults once, before execution. + +### Source And Inspection Decisions + +- Keep `PromptSource`, `ProfileSource`, `BackendSource`, and `SchemaRootSource` + producing wrapperless settings fragments. `SettingsInput` mounts a source at + `/promptkit`, with ordinary mapping placement and imports disabled by default; + callers may adjust native input fields. This avoids double-wrapping fragments + mounted in collections. +- `CollectionInput` mounts at `/promptkit/collections/` and keeps its + existing namespace validation and enabled-import default. `id`-first files use + native sequence-item placement at `/promptkit/prompts`, `/promptkit/profiles`, + or `/promptkit/backends`, including collection-local equivalents. +- Keep directory/filesystem discovery helpers as source selection with their + existing root destination and discovery/context semantics. Full documents use + the canonical wrapper. Callers mounting discovered wrapperless fragments set + their native destinations explicitly; do not detect document shapes. +- `BundledOpenRouterUnderlay` returns the existing bundled fragment mounted at + `/promptkit`. Applications select it before their load. `NewEngine` still + defaults it on, placing it before caller underlays without mutating them. +- The standalone load uses an envelope containing `PromptKit Settings` and an + inline map for other root settings. Root keys resembling old resource keys + are not specially consumed or rejected. There is no PromptKit version rule + or forced source-version mode; application-owned loads retain their own rules. +- Retain the existing reporting methods and zero-view behavior. Add + `HistoricalPaths() []configkit.Path`, returning nil for the zero facade view. + Use native `Inspection` operations; diagnostics are captured separately from + the original result. Keep the native paths and focused semantics in the feature + roadmap, including unfiltered metadata/explicit queries and ancestor diffs. + +## Stage 1 — Upgrade The ConfigKit Dependency + +Purpose: isolate the prerequisite dependency change from the refactor. + +1. Update `go.mod` and `go.sum` to ConfigKit v1.4.0 using the published module. + Keep `go 1.27.0` and unrelated dependency selections unchanged unless module + resolution demonstrably requires a change. +2. Inspect that release's actual notices and update its entry and exact upstream + commit links in `docs/oss/attribution.md` under the OSS policy. Retain applicable + existing license texts; do not infer new licensing requirements from the bump. +3. Run the existing suite against the dependency update while the old layout is + still intact. Use the newest installed local Go patch with `GOTOOLCHAIN=local` + and `GOWORK=off`. Record the result and keep this change separately reviewable. + +Evidence: published v1.4.0 is selected, attribution matches, and the unchanged +configuration implementation still passes its tests. This is ordinary development +validation, not an approval gate before Stage 2. + +## Stage 2 — Resolve Configuration Repair Defaults + +Focus: `internal/domain`, configuration output decoding/resolution/capture, +resource inspection, and their narrow tests. + +1. Add one small source-neutral mode/budget defaulting helper used by both + configuration and runtime input resolution. Keep existing output-contract + legality in the domain validation boundary; do not duplicate the mode table + across adapters. +2. Change the configuration budget to `*int`. During final-value resolution, + record the default at the individual `output/repair_attempts` path when nil. + Use a recorded normalization that also handles explicit null; an absent-only + default operation must not skip null. Leave nonnil explicit values unchanged. +3. Capture the concrete integer into the domain output contract. Remove the + repair-presence side map and report the actual resolved budget in resource + inspection, including zero. Update the public inspection field and converter. +4. Keep `PromptOutputConfig` source-helper pointers: nil omits a field and a + pointer to zero emits zero. Raw native configuration can express null. +5. Add focused configuration cases for each eligible mode, `none`, omission, + null, zero, two/three, rejected bounds, and null clearing an inherited budget. + Verify effective inspection records the resolved value. Preserve required + output fields and schema-selection rules. + +Evidence: YAML and typed source inputs produce the selected concrete budgets, +with no change to actual-attempt counters or the repair loop. + +## Stage 3 — Separate Runtime Contract Inputs From Resolved Contracts + +Focus: `types.go`, `convert.go`, `internal/domain/domain.go`, request ownership, +`internal/usecase/runner.go`, and focused runtime tests. + +1. Introduce the public/internal input types described above and update + `RunRequest.Validation`, conversions, and relevant request-copy/formatting + paths. Copy the optional budget at the existing request-ownership boundary. + Preserve existing schema ownership and request privacy rules, without adding + a guarantee about concurrent caller writes. +2. Update `resolveOutputContract` to resolve an input replacement into a concrete + contract using the shared helper. Keep replacement rather than merge, existing + empty-format handling, inactive-schema dropping, inline schema decoding, + schema-root binding, and public error identities. +3. Keep configured contracts, prepared runs, validator/repair inputs, and + `RunPrepared` concrete. Prepared execution must not recalculate defaults or + consult later request/configuration mutations. +4. Test omitted versus explicit-zero replacement budgets, eligible defaults, + `none` and invalid budgets, a replacement independent of the configured + budget, and prepared retention. Use an offline client returning invalid then + valid output to prove one default repair; use explicit zero to prove no repair. + Keep existing exhaustion, cancellation, transient retry, and usage tests. + +Evidence: the input API distinguishes default from zero while execution and +accounting continue consuming resolved integers. Broader call-site migration is +assigned to Stages 11 and 12; do not retain a legacy request-input alternative. + +## Stage 4 — Add The Public Settings Schema And Facade Conversions + +Focus: a root settings file and internal configuration data declarations. + +1. Declare the nine public settings structs in the model table, with precise + GoDoc and YAML tags; reuse the existing backend smoke/probe structs. +2. Adapt the internal settings records to expose only the internal data boundary + needed for explicit conversions. Remove their obsolete `Version` field. + Add inline application maps at the five selected levels only. +3. Implement straightforward typed conversion in both directions. Preserve all + values and unknown maps when returning normalized settings to the application. + Do not use JSON/YAML round-trips, reflection-based registration, or public + aliases to internal types. A new code-generation subsystem is unnecessary. +4. Keep existing source helpers independent. Do not add `Extends` to the effective + schema or silently change primitive/null rules such as `Required bool`. +5. Add small decoding/conversion tests covering nested known fields, nil/empty + containers, and retained application maps. Resource provider maps and nested + owned object schemas retain their current validation. + +Evidence: an external application can declare its field as `promptkit.Settings` +without importing internal packages, and normalization can round-trip all fields. + +## Stage 5 — Extract Stateless Component Rules At Native Paths + +Focus: `internal/configuration/load.go`, `resolve_prompts.go`, +`resolve_targets.go`, sensitivity paths, and public `Configure` wiring. + +1. Separate configuration rules from `loaded` state. Keep one internal + normalization/validation implementation and the current source-neutral domain + checks. Prefix resource bases, schema roots, validation paths, sensitivity + matching, and sequence registrations with `/promptkit`. +2. Register `id` identities for the three root resource lists and wildcard + collection equivalents. Leave collection/resource runtime identity formation + unchanged. Existing application registrations remain present. +3. Remove the resolver's input-presence capture closure. Presence will come from + final metadata in Stage 6, not a shared mutable map tied to one load. +4. Remove `checkConfigurationVersion` and PromptKit's `VersionRule` installation. + Do not preparse sources, strip version fields, or install a replacement + resource-version policy. +5. Implement `Configure` with the callback composition specified above. Convert + selected public settings for the internal rules, write normalized settings + back, and preserve application maps. Leave application defaults/version rules + intact; component defaults such as queue and repair budgets use resolution. +6. Cover callback error propagation, native sensitivity, application validation, + and registration preservation in focused tests. Do not add detection that a + consumer registered a particular helper or used a particular callback order. + +Evidence: rules can be reused across loads, including concurrent loads, without +capturing another load's resource state or taking over application version policy. + +## Stage 6 — Capture Owned Resources From Final Settings And A Native View + +Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and +`resources.go`. + +1. Extract capture from loading: accept converted effective settings plus the + native focused `configkit.Inspection` and detached load diagnostics. This + adapter operation is not another ConfigKit lifecycle. +2. Read a final metadata snapshot once for construction and share it across + prompt input presence and field-origin lookup. Replace resolver-side input + maps with capture-time facts, retaining only the facts resource/requirement + reports actually use. Do not query history to infer presence or origins. +3. Resolve content files and schema bindings through the effective field's + origin and the view's `SourceContext`. Preserve mixed filesystems, imports, + mounting, inheritance, overrides, and existing resource containment behavior. + Keep schema reading/compilation at the existing preparation boundary. +4. Detach retained known settings: nested provider maps, schema values, scalar + pointers, resource slices, and collection maps as needed by runtime and + resource inspection. Reuse existing ownership helpers where suitable; a + shallow struct copy or the current trusted cloner's nonrecursive struct case + is not sufficient by itself. Prefer explicit ownership of known data over + cloning arbitrary application extension values. +5. Build the current backend/profile indexes, compiled prompts/hashes, + requirement snapshots, capacity policies, inventories, and collection labels. + Resource reports omit application maps. Preserve partial-profile completion + and all unrelated selection behavior. +6. Retain the native reporting view, diagnostics, and required resource bindings, + rather than the mutable whole application result. The frozen native view can + retain whole-application evidence; do not manufacture isolation or retain + metadata as an execution-time resolver. + +Evidence: capture constructs the same executable resources independently of the +application's root Go type and later mutation of its settings. + +## Stage 7 — Replace Generic Inspection Storage With The Focused View + +Focus: `internal/configuration/inspection.go` and +`configuration_inspection.go`. + +1. Remove the dependency on `*configkit.Result[document]` and `capturedResult()`. + Retain the native non-generic view and diagnostics in the adapter report. +2. Forward existing reporting methods. Add `HistoricalPaths` through both + boundaries, retaining the facade's established nil/zero receiver behavior. +3. Delegate comparisons to native `Inspection.Diff`; remove the generic-result + comparison bridge if no longer needed. Keep the facade's zero-view + `ErrInvalidConfig` and preserve other native errors. +4. Return owned diagnostic records, including copies of `Primary` and `Related`. + Obtain these diagnostics from the original result during handoff, not from the + view, which does not have a diagnostics method. +5. Do not filter metadata, explicit queries, full source catalogs, dependencies, + ancestor differences, or native redaction. Do not rebase paths. + +Evidence: the same facade supports views from different application root types, +without custom redaction/history/diff implementations or access to typed config. + +## Stage 8 — Mount Bundles And Standalone Fragments Explicitly + +Focus: `configuration_sources.go`, public source helpers, and +`internal/configuration/bundled.go`. + +1. Add `SettingsInput` and `BundledOpenRouterUnderlay` with the source decisions + above. The latter can delegate to the internal bundle helper; it does not read + the bundle during construction of the underlay. +2. Change `CollectionInput`'s destination, preserving imports and caller-adjustable + context. Keep typed source mapping functions wrapperless. Do not change file + discovery or add automatic wrapper/item detection. +3. Mount the embedded OpenRouter fragment with native `Input.Destination`. + Keep the existing asset as a fragment rather than making two copies for + root and collection use. Preserve bundled IDs and resource content. +4. Test ordinary fragments, wrapperless collection files, an `id`-first file with + native item placement, and their source-relative references. Verify creating + helpers alone performs no source acquisition. + +Evidence: convenient resource fragments still compose into the sole resolved +location, with no shape recognition or second merge pass. + +## Stage 9 — Wire Whole-Result And Standalone Engine Construction + +Focus: root `engine.go`, new configuration facade wiring, +`internal/engine/engine.go`, and the former adapter load entry point. + +1. Add public `Configuration`, `RuntimeConfig`, and `NewFromConfig`. Select + `Value(Keys("promptkit"))`, handle the accepted terminal forms, obtain the + focused view, and capture original-result diagnostics. Forward converted + settings and native evidence to the internal capture operation. +2. Map nil/unavailable inspection, wrong section type, invalid options, and + capture failures through `ErrInvalidConfig`. Preserve wrapped ConfigKit errors + on the source-loading path. Do not run `Configure`, normalize again, inject + bundles, or load any source inside the handoff constructor. +3. Extract shared engine assembly after capture. Preserve runtime settings, + option application order, injected collaborators, capacity ownership, + namespace views, ordinary runner/repair wiring, and diagnostic clients. +4. Make `NewEngine` assemble its selected underlays/main, run one ConfigKit + lifecycle with the public settings envelope and `Configure`, and call the + same handoff/capture/assembly path. A nil main uses `NoSource` as before. + Use the standalone envelope and version behavior specified above. +5. Remove the obsolete independent loader path and mutable typed-result storage. + The internal engine need not import the facade: keep source loading and + public model translation at the facade/configuration boundary and pass the + captured adapter value inward for assembly. +6. Document before-handoff mutation expectations rather than adding equality, + provenance-consistency, or registration checks. Existing after-construction + mutation protection remains. + +Evidence: both constructors own the same runtime resources and use the same +rules, with a single load only on the source-loading path. + +## Stage 10 — Migrate Internal Configuration And Source Tests + +Focus: `internal/configuration/*_test.go` and source-helper contract tests. + +1. Migrate effective-tree paths and document wrappers; leave explicitly mounted + collection/item fragments wrapperless. Update helper tests to the chosen + destinations and unchanged discovery semantics. +2. Replace tests coupled to `state.result.Config`, `capturedResult()`, and resolver + presence maps with resource outcomes or native inspection behavior. Remove + tests whose sole contract was the retired PromptKit resource-version rule. +3. Retain final-effective-value checks, type/semantic errors, resource-ID rules, + collection labels, normalization origins, source context, missing files, + schema capture, listings, and configured capacity behavior. +4. Update repair default expectations deliberately. Tests about unrelated behavior + that require single-pass execution should configure explicit zero; do not + depend accidentally on the changed default. +5. Keep benchmarks representative of the new paths without adding performance + thresholds or a new benchmark acceptance gate. + +Evidence: migrated adapter and source tests protect the new public behavior +rather than the removed private storage representation. + +## Stage 11 — Migrate Internal Engine And Execution Tests + +Focus: existing `internal/engine` and `internal/usecase` tests and their fixtures. + +1. Change internal request replacements to the new input type and pointer + budgets; keep resolved contracts and prepared expectations concrete. +2. Adapt internal engine assembly tests to captured configuration rather than + the retired source-loading entry point. Use the same internal rules/capture + in test setup or an external test package where appropriate; do not introduce + a root-package import cycle or restore a second production loader for tests. +3. Migrate documents and paths to the nested location, retaining native fragment + placement where used. Configure explicit zero when a test needs single-pass + behavior independently of the changed default. +4. Preserve focused tests for generation errors, transient retries, repair + accounting/exhaustion, cancellation, deadlines, observers, continuation, + concurrency, smoke diagnostics, and prepared ownership. Run affected packages + as they become ready; record any still-dependent fixture migrations. + +Evidence: execution tests use the new input/capture boundaries without changing +unrelated runtime contracts or adding test-only source interpretation. + +## Stage 12 — Migrate Existing Public Facade Call Sites And Fixtures + +Focus: existing root-package contract tests and their configuration fixtures. + +1. Change request replacements to `OutputContractInput` and pointer budgets; + leave resolved expectations as `OutputContract`. Preserve tests for zero, + inactive schema, request privacy/ownership, invalid contracts, and prepared + snapshots rather than mechanically changing their meaning. +2. Wrap whole documents beneath `promptkit`; mount programmatic source fragments + with `SettingsInput` or explicit native destinations. Update fixture paths in + native explanations without changing runtime IDs or stored references. +3. Migrate comparison fixtures and concrete inspection budgets to the new + reporting semantics. Keep application root keys unconsumed instead of making + legacy detection pass. +4. Retain existing public error, ownership, selection, diagnostic, execution, and + hash coverage. Tests requiring no repair should select explicit zero. +5. Run `go test . ./internal/...` as packages become ready to find missed call + sites and repair them; examples migrate in Stage 15. A broad failure from one + missing mount is not permission to delete coverage or loosen expectations + unrelated to the two approved changes. + +Evidence: existing substantive facade APIs remain exercised under the new input +and configuration contracts; expected test call-site migrations are complete. + +## Stage 13 — Add Application-Owned Handoff Integration Coverage + +Focus: a small external-package root integration test group, with real ConfigKit +and PromptKit collaborators and an offline model client. + +1. Define an application with sibling settings, `Settings`, and a representative + second component. Preserve callbacks, defaults, version policy, registrations, + sensitivity, normalization order, and validation diagnostics. Reuse the same + configured definition across independent and concurrent loads. +2. Load once and hand the entire result to `NewFromConfig`. Also use a wrapper + exposing only the three `Configuration` methods. Single-use/counted sources + can prove construction does not reacquire configuration; expected message and + schema resource reads must remain allowed. +3. Combine embedded-like and operator filesystems, collection/item placement, + sibling inheritance, and an override from another source. Verify effective + message and schema contexts through preparation and an ordinary offline run. +4. Compare equivalent application-owned and standalone resource reports, + inventories, and prepared execution details. Include bundles selected before + the load and application-only loading without bundles. +5. Exercise missing fields, declared zero settings, typed nil, explicit null, + wrong types, and old-looking application root keys. Test application fields at + all five extension points through composition, application validation, + normalization, configuration reporting, and exclusion from resource reports + and model parameters. Keep recognized and nested-owned-field failures. +6. Mutate caller settings after construction: pointers, slices, nested provider + maps, inline schema arrays/maps, and file-selection strings. Verify owned + resource reports and preparation/run behavior remain captured. Do not invent + before-handoff mutation detection or snapshot filesystem guarantees. + +Evidence: a consumer can use the complete new workflow without extraction, +serialization, another load, or knowledge of internal types. + +## Stage 14 — Add Focused Inspection Integration Coverage + +Focus: the public configuration-inspection facade, reusing minimal fixtures. + +1. Verify focused effective output, native redaction including ancestor and + application sensitivity, frozen evidence after caller mutation, and detached + diagnostics forwarded from the original result. +2. Verify scoped `HistoricalPaths` alongside unfiltered `Metadata`; explicit + outside-focus explanations/history remain native. Test `/promptkit` as the + overview location and the empty native path as whole-application explanation. + Source catalogs/contextual evidence remain whole-load evidence. +3. Verify comparison through PromptKit across different application Go root + types: changed PromptKit data is reported; sibling-only records are excluded; + ancestor records retain native behavior. Cover added/removed, absent, null, + and historical-only sections and native errors where relevant to the facade. + An absent effective scope fails rendering without output; explicit null + renders normally. +4. Preserve zero-facade error behavior and writer-error identity. Do not duplicate + ConfigKit's entire comparison/history/redaction suite; use representative + boundary cases to prove delegation and focused semantics. + +Evidence: inspection is convenient reporting focus with no claim of isolation +or independent comparison implementation. + +## Stage 15 — Update The Three Maintained Offline Examples + +Focus: `examples/go-library/{prepare,run,observe}` and their tests/assets. + +1. Update preparation to demonstrate an application-owned typed root, explicit + `Configure`, a single load of the existing synthetic collections, and + `NewFromConfig`. Preserve inventory, scoped selection, preparation, and source + context outcomes. Prefix native inspection paths. +2. Keep execution demonstrating standalone `NewEngine`, using explicit mounts or + wrapped documents and its existing offline client. +3. Migrate observation's source assembly and runtime replacement types. Preserve + its controlled retries and application-directed proposal/assessment flow; + explicitly configure repair budgets where they determine example accounting. +4. Keep wrapperless fragments where mounted. Remove obsolete version-policy + explanations/fixtures rather than replacing them with source preprocessing. +5. Run the example tests and review their semantic assertions. Keep the existing + examples as maintained artifacts instead of copying the disposable prototype + or creating another example framework. + +Evidence: both construction workflows are demonstrated by tested, credential-free +consumer examples with no paid or live inference calls. + +## Stage 16 — Update Canonical Contracts And Migration Guidance + +Focus: GoDoc, `README.md`, `docs/formats.md`, +`docs/consumers/pkg-promptkit.md`, `docs/consumers/configuration-migration.md`, +and `docs/internal/{overview,sources,runner}.md`. + +1. Document the new public declarations, callback ordering, supported terminal + types, errors, ownership, and runtime-only settings. Link complete workflows + to the maintained examples and exact field contracts to GoDoc/formats. +2. Explain canonical nesting, all five extension points, nested strictness, + source-fragment mounts, application version ownership, bundled-underlay + selection, and ignored old root resource keys. Update ConfigKit references + needed for these contracts to the selected release. +3. Document request migration from `OutputContract` to `OutputContractInput`, + nil/null versus explicit zero, concrete inspection budgets, mode defaults, + and possible added latency/usage only after failed validation. State that a + correction is not guaranteed. Preserve runtime replacement and counter meaning. +4. Explain focused reporting, including full metadata and explicit outside-focus + queries, native ancestor diffs, frozen evidence, and original-load diagnostics. + Remove assertions that the report is exclusively a PromptKit configuration. +5. Update implemented package responsibilities and the architecture policy's + current engine-loading description to the shared registered-load/capture + arrangement. Retain its facade and data-ownership constraints; do not adopt + the future shared-model exception or alter the accepted ADR. +6. Search current documentation/examples for stale old paths, integer runtime + inputs, source-version enforcement, and old repair defaults. Preserve + published release notes as historical records. This sprint does not prepare + or publish a release; subsequent minor-release notes must explain these + intentional pre-1.0 compatibility changes. + +Evidence: implemented contracts have canonical owners and a practical migration +path, with no future behavior described as implemented before it lands. + +## Stage 17 — Complete End-To-End Verification And Remove Superseded Machinery + +1. Review the final code against both feature sections and the integration + assessment. Confirm one library rule implementation, one capture path, one + assembly path, and no original-result retention for mutable application config. + Remove dead generic-result bridges, version checks, resolver side maps, + temporary conversion scaffolding, and compatibility code left during staging. +2. Confirm application extensions stay in loaded settings and frozen native + inspection without needing to be carried into execution. Final capture uses + effective metadata only; ordinary runs do not analyze provenance. Preserve + existing hash semantics except changes naturally caused by newly effective + repair budgets; do not add a cross-release hash guarantee. +3. Review tests under the testing policy: internal tests own focused mechanics; + external-package tests own the facade handoff; examples prove representative + workflows. Consolidate redundant prototype-style cases and keep meaningful + ownership, concurrency, source-context, and error regressions. +4. Format changed Go files. With the latest installed local Go patch selected, + `GOTOOLCHAIN=local`, and `GOWORK=off`, run `go test -race ./...` and + `go vet ./...`. The full suite includes the maintained examples; a second + example execution or separate build is not another completion gate. +5. Review changed Markdown links and run `git diff --check`. Inspect complete + diffs/status for unrelated changes, local replacements/workspaces, generated + artifacts, credentials, accidental upstream copies, and stale references. +6. Commit completed, nonempty work with plain-English messages and report final + validation, compatibility changes, and any unfinished work. Do not tag, push, + publish, wait for CI, or require downstream CommandKit/Audita changes to finish + this sprint. Completed planning documents can be retired during subsequent + release preparation under the documentation policy. + +Completion requires implemented repair defaults for configuration and runtime +inputs, an application-owned single-load handoff, equivalent standalone loading, +all selected extension/inspection behavior, owned execution capture, migrated +consumer examples/docs, and successful final validation. No product decision +remains open; private helper names and file organization may follow the existing +code without changing these public shapes or scope. diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index 5ff1d13..7d4f44b 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -41,12 +41,9 @@ Counters reporting repairs actually performed remain ordinary integers. Do not propagate optional-value handling into execution or counters solely to accommodate input defaulting. -Implementation planning must specify the presence-aware Go shape and migration -from the current integer field, and cover omission, null, and explicit zero across -configuration, typed helpers, and runtime contracts. Document that repair runs -only after failed validation and can add generation latency and usage. Existing -repair accounting, exhaustion, cancellation, and transient-retry semantics remain -unchanged; the change does not promise successful correction. +Repair runs only after failed validation and can add generation latency and +usage. Existing repair accounting, exhaustion, cancellation, and transient-retry +semantics remain unchanged; the change does not promise successful correction. ## 2. Consume Application-Resolved Configuration Under `promptkit` @@ -91,9 +88,8 @@ profile selection, required-resource checks, or diagnostics policy. Adopt [ConfigKit v1.4.0](../../../ConfigKit/docs/releases/v1.4.0.md) as a prerequisite for the configuration handoff. It releases the typed lookup and -focused inspection APIs required here. PromptKit currently selects v1.3.0; -make the dependency upgrade separately reviewable before the configuration -refactor. The Go consumer minimum remains 1.27.0. +focused inspection APIs required here. PromptKit currently selects v1.3.0. +The Go consumer minimum remains 1.27.0. The released lookup is: @@ -113,7 +109,8 @@ 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. +contract. Concrete supported settings forms are specified in the implementation +plan. Expose public PromptKit settings and a small typed registration helper using existing ConfigKit APIs. The following is an illustrative consumer sketch, not @@ -132,7 +129,7 @@ definition := promptkit.Configure( result, err := configkit.Load(source, configkit.Options[AppConfig]{Definition: definition}) // Handle err before continuing. -engine, err := promptkit.NewFromConfig(result) +engine, err := promptkit.NewFromConfig(result, promptkit.RuntimeConfig{}) ``` One compiler-checked field selector per library is accepted registration wiring, @@ -163,8 +160,7 @@ 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 -remain implementation-planning work. +through PromptKit's configuration inspection facade. Register desired bundled resources as ordinary underlays before composition; engine construction must not inject another configuration layer into an already @@ -314,122 +310,22 @@ to both application-owned loading and standalone construction. Update examples and migration guidance accordingly, without preparsing or stripping headers or adding a second load. -## Guidance For Implementation Planning +## Integration Evidence And Scope -### Validate The Pattern Against PromptKit +The actual PromptKit prototype verified typed registration, one application-owned +load, whole-result construction, and standalone loading through shared rules +against ConfigKit v1.4.0. It also demonstrated final-metadata presence capture, +effective source contexts, owned runtime values, and native focused reporting. +See the [integration assessment](configuration-integration-check.md) for evidence +and limits. This establishes feasibility, not completed production implementation. -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. +The [implementation plan](implementation.md) owns the concrete API choices, +ordered work, migration steps, and verification needed to reach this target. +The shared configuration-model simplification remains a separate +[future idea](future.md#shared-configuration-data-model), rather than a change to +the architecture policy or this feature's scope. -ConfigKit's released APIs and maintained -[one-library](../../../ConfigKit/examples/consumers/result_component.go) and -[two-library](../../../ConfigKit/examples/consumers/result_composition.go) examples -provide the integration starting point. They demonstrate typed registration, -whole-result handoff, owned settings capture, native inspection, and effective -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 -isolated prototype now also verifies the proposed handoff pattern; the production -handoff remains to be implemented. - -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 - 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. - Include inline application-field maps at the accepted extension points and - preserve those values during PromptKit normalization. -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. -4. **Inspection facade and diagnostics.** Retain the native focused view and specify - public signatures for its operations and load-diagnostic forwarding. Obtain - diagnostics from the original result's `Diagnostics()` method through - PromptKit's consumer-owned interface. Expose focused enumeration - alongside native metadata and query operations. A PromptKit overview explanation - selects `/promptkit`; the native empty path selects the whole application. - -Document what the interfaces do: their inputs, operations, outputs, and errors, -and how registration, loading, and engine construction fit together. Keep this -guidance concrete; hypothetical misuse does not call for registration tracking, -another validation lifecycle, or defensive caveats. - -CommandKit neutrally exposes upstream PromptKit APIs. Any adapter updates are -routine downstream adoption, not a constraint on PromptKit's public API or a -prerequisite for completing this migration. PromptKit's implementation plan covers -its own resource, inspection, and diagnostic capabilities; CommandKit owns how -those are presented through CLI commands. - -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 configuration refactor. Neither needs a new execution subsystem or -compatibility resolver. - -### Focused Validation - -- Mode defaults after composition, null clearing an inherited repair budget, - 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 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 additional fields - at each accepted extension point. Recognized fields retain type and semantic - validation; nested PromptKit-owned objects retain their existing schemas. -- Additional fields survive native composition, inheritance, normalization, and - configuration inspection, including application-defined sensitivity. They remain - available to application validation and do not enter provider requests merely - because they appear on a resource definition. -- Resource inspection omits application-specific fields while configuration - inspection retains them under ConfigKit's native sensitivity rules. -- Engine independence from later caller mutation of settings, including nested - maps and slices; trusted lookup does not replace redacted inspection. -- Resource listings, resource reports, and load diagnostics through PromptKit's - public APIs; configuration output and overview explanations focused on - `/promptkit`, with native paths and redaction preserved. -- Focused enumeration alongside unfiltered metadata; explicit - queries outside the focus and shared source/history context retain native behavior. -- Inspection remains frozen after settings mutation; absent, null, historical-only, - and added/removed sections follow upstream semantics. Sibling difference records - are excluded while ancestor differences remain; comparison works across different - application root types selecting the same scope. - -The product direction, including focused inspection, removal of resource-version -validation, and the configuration-only inspection of application-specific fields, -is settled. No product decisions remain before implementation planning. -Concrete public API shapes, diagnostic forwarding, and verification of the actual -PromptKit integration are implementation-planning work. - -## Further Candidates - -Append additional pre-release considerations here as they arise. +CommandKit and other consumers own their adapters and presentation. Their adoption +is not a prerequisite for implementing PromptKit's resource, inspection, and +diagnostic capabilities. Neither accepted feature requires a new execution +subsystem, another configuration resolver, or an upstream component framework.