From 5ea60e9b96651fd7dfcbc7d05b6f43d131df358f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 21 Nov 2026 18:09:47 +0000 Subject: [PATCH] Prepare v0.24.0 release documentation --- README.md | 7 +- .../0002-shared-configuration-data-model.md | 5 +- docs/releases/v0.24.0.md | 82 +- .../configuration-integration-check.md | 178 ----- docs/roadmap/implementation.md | 724 ------------------ docs/roadmap/next-release-considerations.md | 355 --------- docs/roadmap/remediation.md | 294 ------- 7 files changed, 80 insertions(+), 1565 deletions(-) delete mode 100644 docs/roadmap/configuration-integration-check.md delete mode 100644 docs/roadmap/implementation.md delete mode 100644 docs/roadmap/next-release-considerations.md delete mode 100644 docs/roadmap/remediation.md diff --git a/README.md b/README.md index 293990c..da3d8ef 100644 --- a/README.md +++ b/README.md @@ -45,8 +45,11 @@ boundary and constraints that framework work must preserve. ## Release Guidance -The [v0.24.0 release notes](docs/releases/v0.24.0.md) describe the prepared -message-content hash and its compatibility considerations. +The [v0.24.0 release notes](docs/releases/v0.24.0.md) cover application-owned +configuration loading, prompt-owned schemas, default output repair, and the +prepared message-content hash. Upgrading consumers should review the breaking +configuration and request-API changes in the +[migration guide](docs/consumers/configuration-migration.md#move-settings-under-promptkit). The [v0.23.3 release notes](docs/releases/v0.23.3.md) cover HTTP operation-timeout attribution, custom caller cancellation causes, and response-read error identity. diff --git a/docs/adr/0002-shared-configuration-data-model.md b/docs/adr/0002-shared-configuration-data-model.md index 7b50cd2..6fac24e 100644 --- a/docs/adr/0002-shared-configuration-data-model.md +++ b/docs/adr/0002-shared-configuration-data-model.md @@ -58,5 +58,6 @@ primary benefit is simpler maintenance; performance improvements are secondary. Conversion into execution-ready objects and necessary ownership copies remain. This decision leaves the [ConfigKit ownership boundary](0001-configuration-boundary.md) -unchanged. The [feature roadmap](../roadmap/next-release-considerations.md) and -[implementation plan](../roadmap/implementation.md) track implementation. +unchanged. The [shared-loading guide](../consumers/pkg-promptkit.md#reuse-an-application-owned-load) +describes the implemented consumer workflow; the +[internal overview](../internal/overview.md) describes its implementation. diff --git a/docs/releases/v0.24.0.md b/docs/releases/v0.24.0.md index 04d9632..5cd0204 100644 --- a/docs/releases/v0.24.0.md +++ b/docs/releases/v0.24.0.md @@ -1,18 +1,80 @@ # Promptkit v0.24.0 -This feature release adds an opaque message-content hash to prepared results. -It identifies the ordered prepared message roles and exact text independently -of session identity, cache hints, and other metadata. The existing rendered -prompt hash is unchanged. See the [prepared-result GoDoc](../../types.go) and -[consumer guide](../consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later). +This minor release adds application-owned configuration loading, prompt-owned +schemas, and a prepared message-content hash. It also enables one repair attempt +by default for enabled output validation. This is a breaking pre-v1 release; +consumers upgrading from v0.23.x should review the migration steps below. + +## Added And Changed + +- Applications can embed `promptkit.Settings`, compose Promptkit's rules with + `Configure`, load configuration once through ConfigKit, and pass the entire + result to `NewFromConfig`. `NewEngine` remains the standalone convenience + constructor. See the [shared-loading guide](../consumers/pkg-promptkit.md#reuse-an-application-owned-load) + and [offline preparation example](../../examples/go-library/prepare/main.go). +- Prompts can select inline, source-relative, or explicit-root JSON Schemas. + Collections can supply their own schema root. Schema resources are loaded + during preparation and retained by prepared execution. See the + [schema reference](../formats.md#schemas). +- Prepared results include `MessageContentHash` (`message_content_hash` in + JSON), an opaque equality value for ordered message roles and exact text, + independent of session identity, cache hints, and other metadata. The existing + rendered-prompt hash algorithm is unchanged. See the + [prepared-result GoDoc](../../types.go) and + [preparation guide](../consumers/pkg-promptkit.md#prepare-now-and-execute-the-same-snapshot-later). +- Configuration inspection uses a native ConfigKit view focused on `/promptkit` + and adds `HistoricalPaths`. It retains whole-load evidence and supports + explicit queries outside that focus; comparison can include ancestor changes. + See the [inspection guide](../consumers/pkg-promptkit.md#inspect-the-captured-configuration). + +## Fixes And Efficiency + +- Prompt-input inspection and requirements now retain effective metadata supplied + by application defaults, including inherited input requirements. +- Configuration capture avoids expanding inheritance provenance just to determine + input-field presence, and shares immutable backend defaults across profiles + without overrides while preserving defensive copies at public lookups. +- Schema handling avoids copying inactive runtime schemas and unused slice + capacity. Inline schemas are separate from provider extra-parameter copy limits. + See the [schema reference](../formats.md#schemas) and + [request GoDoc](../../types.go). ## Compatibility And Upgrade -Prepared-result JSON now includes `message_content_hash`; older JSON without it -decodes with an empty value. The new Go struct field is additive, though callers -using positional `PreparedRun` literals may need to adjust them. No configuration -migration is required. ConfigKit is updated to v1.3.0; the Go consumer minimum -remains unchanged. +The [configuration migration guide](../consumers/configuration-migration.md#move-settings-under-promptkit) +owns the full migration walkthrough. In particular: + +- Move complete-document resources and `schema_root` under `promptkit`. + Previous root-level resources are now application data, not Promptkit + resources; IDs and references keep their existing names. `SettingsInput` + mounts wrapperless fragments at `/promptkit`; `CollectionInput` mounts them + at `/promptkit/collections/`. Discovery helpers still produce + root-mounted inputs, so adjust fragment destinations explicitly. +- For an application-owned load, select `BundledOpenRouterUnderlay` before + loading if you want the bundled catalog. Bundling remains default-on for + `NewEngine`; it is not implicitly added by `NewFromConfig`. +- Replace `RunRequest.Validation` values of type `*OutputContract` with + `*OutputContractInput`; its `RepairAttempts` field is a pointer. Omitted or + null budgets now resolve to one for `basic`, `json`, and `json_schema`, or + zero for `none`. Set an explicit zero to retain single-pass behavior. + Runtime replacements still replace the whole contract and resolve their + defaults independently. A failed check may now incur another generation call, + latency, and usage, without guaranteeing a valid result. See the + [output contract](../formats.md#output-contract). +- `PromptOutputInspection.RepairAttempts` is now a resolved integer rather than + an optional pointer, and its JSON includes zero. `OutputContract` remains the + resolved contract type used by prepared details. See the + [inspection GoDoc](../../resource_inspection.go) and [contract GoDoc](../../types.go). +- Schema paths require an explicitly configured applicable root; there is no + implicit working-directory root. Review file references and make schemas + self-contained as described in the [schema reference](../formats.md#schemas). +- Promptkit no longer validates resource-version fields. Applications own version + policy and sensitivity rules for their extension fields; see the + [format reference](../formats.md). + +Older prepared-result JSON without `message_content_hash` decodes with an empty +value. Callers using positional `PreparedRun` literals may need to adjust them. +ConfigKit is updated to v1.4.0; the Go consumer minimum remains 1.27.0. ```sh go get go.maximumdirect.net/promptkit@v0.24.0 diff --git a/docs/roadmap/configuration-integration-check.md b/docs/roadmap/configuration-integration-check.md deleted file mode 100644 index c871aa2..0000000 --- a/docs/roadmap/configuration-integration-check.md +++ /dev/null @@ -1,178 +0,0 @@ -# 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/`. 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/implementation.md b/docs/roadmap/implementation.md deleted file mode 100644 index d524de7..0000000 --- a/docs/roadmap/implementation.md +++ /dev/null @@ -1,724 +0,0 @@ -# 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) and apply -[ADR 0002's shared configuration data exception](../adr/0002-shared-configuration-data-model.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, with ADR 0002's - narrow exception: define the public settings once in `internal/settings` and - expose root aliases. The configuration adapter uses those declarations directly. - No new public settings package or equivalent-model conversion layer is needed. -- 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 - -Declare the following structs once in `internal/settings`, corresponding to the -current adapter records in `internal/configuration/load.go`. Expose each under -the same name in the root package with an alias, such as -`type Settings = settings.Settings`. All configuration fields have explicit -existing snake-case YAML tags; `Application` is the native `map[string]any` field -tagged `yaml:",inline"`. Consumers use the root names in their own typed -configuration and nested composite literals. - -| 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` | - -Move the data declarations for `BackendSmokeTestConfig`, -`ReachabilityProbeConfig`, and `AuthenticationProbeConfig` into the same shared -package and expose their existing root names as aliases. Preserve their fields, -JSON/YAML tags, and documented behavior. These types are nested in settings and -already used by source helpers and reports; moving their declarations avoids an -import cycle without merging those helpers or reports into the settings model. -Keep domain smoke values and meaningful conversions to them separate. - -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. - -The shared package contains data declarations and their field documentation; -loading, normalization, validation, and resource capture stay in their existing -owners. It imports neither the facade nor configuration/engine/domain logic. -The adapter consumes the same settings types as the public API, preserving -nil/empty containers, pointers, and application fields without a settings -conversion round-trip. Root aliases have public GoDoc directing consumers to the -canonical field declarations. Treat the shared declarations as public API, not -as independently changeable private structs. - -Keep necessary conversion and ownership copying into execution values and -resource reports. Runtime requests and resolved output contracts remain outside -this exception; their changes are described separately below. - -### 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 - -Status: complete. The existing suite passed with Go 1.27.4 and ConfigKit v1.4.0. - -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 - -Status: complete. Focused configuration, domain, and public source tests passed. - -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 - -Status: complete. Internal use-case tests and the facade build passed; existing -public test and example call sites remain scheduled for migration below. - -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 Shared Settings Schema And Root Aliases - -Status: complete. Adapter tests and external settings-decoding tests passed; -the standalone envelope retains its existing version field until loader migration. - -Focus: `internal/settings`, root settings aliases, `backends.go`, and the -configuration adapter's data declarations. - -1. Declare the nine settings structs in the model table in `internal/settings`, - with canonical field GoDoc and YAML tags. Add the three backend smoke/probe - declarations there with their existing fields and serialization tags. -2. Expose root aliases for all twelve data types. Keep existing public smoke/probe - names usable in source helpers and resource reports. The shared package has no - loading, normalization, validation, capture, or execution behavior and no - dependency on the root facade. -3. Replace equivalent adapter decoding records with the shared types, including - nested settings. Remove the obsolete `Version` field and retain the inline - application maps at the five selected levels. Preserve Stage 2's pointer - budgets. Do not add duplicate public/internal settings or conversion helpers; - keep settings-to-domain conversion and owned capture where they do real work. -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. Use external-package decoding tests with nested root-name composite literals, - including smoke/probe settings, nil/empty containers, and application maps. - Verify the existing smoke/probe serialization shape and source-helper use - remain supported. Retain known-field and nested-object validation tests; - normalization and post-capture ownership are exercised in subsequent stages. - -Evidence: an external application can declare its field as `promptkit.Settings` -and construct its nested values without importing internal packages. Public and -adapter settings share one declaration set with no conversion layer between them. - -## Stage 5 — Extract Stateless Component Rules At Native Paths - -Status: complete. Focused registration tests passed under the race detector; -the old adapter tests do not compile against the new envelope and remain scheduled -for migration, while metadata capture moves to the next stage. - -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. Pass the - selected settings pointer directly to the internal rules. Normalize it in - place through ConfigKit's recorded operations, preserving application maps. - Leave application defaults/version rules intact; component defaults such as - queue and repair budgets use resolution. No settings conversion or write-back - reconstruction is needed. -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 - -Status: complete. Focused capture tests passed under the race detector, including -mutation isolation and effective cross-filesystem source contexts. The former -generic inspection bridge is removed in the next stage. - -Focus: `internal/configuration/load.go`, `prompts.go`, `targets.go`, and -`resources.go`. - -1. Extract capture from loading: accept the shared 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 - -Status: complete. Focused race-tested checks cover native cross-root comparison, -historical paths, and detached diagnostics; broader facade coverage follows. - -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 - -Status: complete. Focused mounting tests passed for bundled, collection, -ordinary fragment, and sequence-item sources without eager acquisition. - -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 - -Status: complete. Focused constructor tests passed for shared capture, explicit -bundle behavior, and invalid handoffs; broader integration coverage follows. - -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. Pass the selected shared - settings and native evidence directly 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 does not import the facade: keep source-loading orchestration - at the facade/configuration boundary, use the shared settings directly, 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 - -Status: complete. Configuration tests passed under the race detector, source -helper tests passed, and the updated benchmarks ran without thresholds. - -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 - -Status: complete. Internal engine and use-case tests passed under the race -detector using registered loads and captured configuration. - -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 - -Status: complete. The root and internal test suites passed with updated request -inputs, explicit fragment mounts, native paths, and the shared-model boundary. - -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 - -Status: complete. External handoff integration tests passed under the race -detector, including concurrent loads, source contexts, and ownership checks. - -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. Use only root - aliases in consumer declarations; verify normalized fields and retained - application maps are visible to subsequent application callbacks and in the - final result without public/internal settings conversions. -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 - -Status: complete. Focused facade inspection tests passed under the race -detector, including redaction, frozen history, diagnostics, and comparison. - -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 - -Status: complete. All three maintained offline example test packages passed. - -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 - -Status: complete. Canonical guides, GoDoc, architecture, and internal component -descriptions cover the new configuration and repair contracts; local links and -focused tests passed. - -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. Document the implemented shared data package and root aliases - under ADR 0002, preserving its narrow scope and all remaining facade and - ownership constraints. Keep the accepted ADR decisions unchanged; the - ConfigKit handoff boundary in ADR 0001 still applies. -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 - -Status: complete. Final verification passed with Go 1.27.4: `go test -race ./...`, -`go vet ./...`, formatting review, local Markdown link checks, and `git diff --check`. - -1. Review the final code against both feature sections and the integration - assessment, using ADR 0002 and this plan for the shared-model change from the - prototype. Confirm one settings declaration set, one library rule implementation, - one capture path, one assembly path, and no original-result retention for mutable - application config. Check that root aliases cover only the selected settings - and nested data types and that internal packages do not import the facade. - Remove dead generic-result bridges, version checks, resolver side maps, - equivalent-settings conversion scaffolding, and compatibility code left during - staging. Preserve meaningful domain conversions and ownership copies. -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, -one shared public/adapter settings model, 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 deleted file mode 100644 index 26d8934..0000000 --- a/docs/roadmap/next-release-considerations.md +++ /dev/null @@ -1,355 +0,0 @@ -# Feature Considerations Before The Next Release - -Status: items 1 and 2 record accepted design decisions. Review these items before -the next release; this document does not authorize implementation or commit either -item to that release. Implemented schema support is documented in the -[format reference](../formats.md#schemas). - -## 1. Enable One Structured-Output Repair Attempt By Default - -**Accepted:** default to one repair attempt for every validation mode that -supports repair. This gives structurally invalid or empty output one automatic -correction opportunity without requiring each consumer to opt in. - -| Validation mode | Default repair attempts | -| --- | ---: | -| `none` | 0 | -| `basic` | 1 | -| `json` | 1 | -| `json_schema` | 1 | - -Use a presence-aware public input `RepairAttempts` field: omission or final null -selects the mode's default; explicit zero disables repairs. Accepting null is a -deliberate change from the current configuration contract. Authors can clear an -inherited budget with null through ordinary ConfigKit composition; PromptKit -interprets the final value without replaying that composition. - -Retain explicit budgets of two or three -for eligible modes. Keep the existing rejection of positive budgets for `none`. -Choose one rather than two as the default; consumers can opt into another -correction opportunity when appropriate for their workloads. - -Apply defaults after ConfigKit composition, preserving explicit values. Execution -and inspection use the resolved concrete budget. Apply the same mode defaults to -omitted runtime output-contract budgets; runtime contracts still replace the -configured contract completely. Prepared execution retains its resolved budget. - -Confine presence awareness to inputs. A `*int` is the recommended Go input shape: -nil selects the default and a pointer to zero disables repair. Resolved inspection -and prepared details expose the concrete budget; execution uses a concrete integer. -Counters reporting repairs actually performed remain ordinary integers. Do not -propagate optional-value handling into execution or counters solely to accommodate -input defaulting. - -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` - -**Accepted:** the application composes configuration once through ConfigKit and -passes the **entire resolved ConfigKit result** directly to PromptKit. PromptKit -locates the fixed root-level `promptkit` section and consumes only that section -for engine construction, ignoring sibling application settings. Inspection uses -the focused reporting semantics below. The application does not extract, reshape, -serialize, or reload a PromptKit-specific view. Do not add a configurable mounting -key. - -The root-key migration supports this handoff; changing YAML paths alone does not -fulfill the feature. The architectural benefit is a single composition lifecycle -with native source context and provenance, rather than an application bridge -between separately loaded configurations. - -### Current Boundary And Intended Consumer Workflow - -Today, PromptKit accepts configuration sources and runs its own ConfigKit load. -Its typed root document rejects unrelated application fields. Audita, for example, -loads application settings separately, then uses their recorded main-source -context to assemble embedded and companion PromptKit sources for another load. -It does not currently hand PromptKit its resolved application configuration. - -The target workflow is: - -1. The application includes PromptKit's configuration definition/registration and - desired bundled or application sources in its ordinary ConfigKit setup. -2. ConfigKit composes and resolves the complete application configuration once, - applying each component's registered rules. -3. The application passes the whole resolved result to PromptKit, together with - runtime collaborators such as its HTTP client. PromptKit captures its effective - resources and constructs the engine without another configuration load. - -File discovery, source selection, imports, layering, and application overrides -remain application policy. Embedded prompt selection and companion-file imports -join the original load; they do not disappear. The change removes context-transfer -and duplicate-loading machinery, not application-specific execution requests, -profile selection, required-resource checks, or diagnostics policy. - -### ConfigKit v1.4.0 And Library-Owned Wiring - -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. -The Go consumer minimum remains 1.27.0. - -The released lookup is: - -```go -func (r *Result[T]) Value(path Path) (any, bool) -``` - -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. 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 -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, promptkit.RuntimeConfig{}) -``` - -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) - InspectSubtree(configkit.Path) (configkit.Inspection, bool) - Diagnostics() []configkit.Diagnostic -} -``` - -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. -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. - -Register desired bundled resources as ordinary underlays before composition; -engine construction must not inject another configuration layer into an already -resolved result. The sketch omits source assembly for brevity. Apply configured -repair defaults from item 1 during resolution; runtime request defaults remain -separate. - -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. - -### Shared Configuration Data Model - -**Accepted:** use one canonical set of configuration settings for the public API -and internal configuration adapter, under the narrow exception in -[ADR 0002](../adr/0002-shared-configuration-data-model.md) and the -[architecture policy](../policy/architecture.md#shared-configuration-data-exception). -Define the data types in a small internal package and expose them through root -aliases such as `promptkit.Settings`. Include the nested settings and backend -smoke/probe data types so both consumers and the adapter use the same declarations -without an internal dependency on the root package. - -Registration and resource capture use that model directly. Remove duplicate -settings declarations and conversions that only copy equivalent fields between -the facade and adapter. The benefit is simpler field maintenance and fewer -opportunities for the two representations to diverge. - -Source-building helpers retain their composition-oriented values. Runtime -requests, execution objects, and resource reports retain their distinct -representations and useful conversions. Preserve the ownership copies needed -when capturing executable resources. Loading, normalization, validation, and -execution behavior stay outside the shared data package. This is part of the -current configuration migration, not a later facade-wide refactor. - -### Fixed Section And Clean Migration - -Move all PromptKit-owned document settings beneath `promptkit`, including -`promptkit.backends`, `promptkit.profiles`, `promptkit.prompts`, -`promptkit.collections`, and `promptkit.schema_root`. Collection-local fields -remain inside their collection. Runtime collaborators are Go API inputs, not new -YAML fields. - -Make a clean breaking migration with one canonical resolved location. Do not -support legacy root-level resource locations through aliases, automatic detection, -or a second merge/precedence pass. Runtime resource IDs and namespace selection -remain unchanged; the configuration wrapper is not part of a resource ID. - -Preserve convenient standalone files. Individual resource files can still begin -with `id`, and collection files can still contain local `prompts`, `profiles`, -`backends`, and `schema_root` fields without a `promptkit` wrapper. Native ConfigKit -import destinations and PromptKit source helpers mount those fragments at the -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 configuration version policy. PromptKit's registration -preserves that policy; PromptKit-specific resource version validation is removed -as described below. - -An absent `promptkit` section contributes no application-supplied PromptKit -settings; selected bundled underlays can still contribute defaults during the -original load. Old root-level keys such as `prompts` and `profiles` are neither -consumed nor specially rejected by PromptKit: they may be application settings. -Application-specific fields are accepted at the extension points below. The -application's 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. - -### Application-Specific Fields - -**Accepted:** allow additional application-specific fields on prompt, profile, -and backend definitions, on collection definitions, and at the `promptkit` section -level. Use ConfigKit's native string-keyed inline maps (`yaml:",inline"`) in the -public settings model to retain unmatched fields. Recognized fields keep their -typed decoding and semantic validation, including required-field checks. - -Additional fields participate in ordinary ConfigKit composition and remain -available in the resolved application configuration and native configuration -inspection. Applications own their interpretation, validation, and sensitivity -rules. PromptKit ignores these fields during execution; they do not become model -parameters. `extra_params` retains its existing provider-parameter purpose. - -Recommend application-specific grouping, such as an `audita` mapping, to reduce -future field-name collisions; do not require a naming prefix or wrapper. At these -extension points, a misspelled optional PromptKit field can be accepted as an -application field. Accept that tradeoff rather than introduce an extension registry -or custom unknown-field detection. - -These extension points do not change the schemas of nested PromptKit-owned objects -such as output contracts. Maps beneath application-specific keys retain ConfigKit's -ordinary dynamic-value behavior. Standalone and application-owned loading use the -same settings model. - -**Accepted inspection boundary:** retain application-specific fields in the -resolved configuration and ConfigKit-backed `InspectConfiguration()` reports. -`InspectPrompt`, `InspectProfile`, and `InspectBackend` continue to report -PromptKit-understood fields and omit application-specific fields. This keeps -resource reports simple: no additional metadata storage, copying, redaction -integration, or public report fields are needed for these extensions. Applications -can access their fields through the resolved configuration and configuration -inspection; execution objects need not carry them. - -### Focused Configuration Inspection - -**Accepted:** preserve resource listing and inspection, and provide configuration -reporting through ConfigKit v1.4.0's non-generic `Inspection` view: - -```go -inspection, ok := result.InspectSubtree(configkit.Keys("promptkit")) -``` - -PromptKit's `InspectConfiguration()` forwards the view's capabilities without -loading another configuration or rebuilding history, redaction, or comparison. -Both application-owned loading and standalone construction use this reporting -path. This replaces the earlier inspection deferral. - -The view is a reporting focus, not an isolation or access-control boundary. -Accept ConfigKit's native behavior: - -- Effective output renders the selected subtree without enclosing application - mappings, using frozen completed-load values and existing redaction, including - sensitivity inherited from ancestors. Later settings mutation does not change - that evidence. -- Focused enumeration includes paths at or beneath `/promptkit`. Metadata remains - unfiltered, and explicit explanation/history queries use native application - paths and may query outside the focus. Do not rebase paths or add a separate - restriction layer. -- Sources and contextual evidence remain native and may describe other application - settings. Do not assign exclusive source ownership or trim ancestor history and - dependency evidence to manufacture an isolated report. -- Comparison uses ConfigKit's existing frozen-configuration comparison and retains - differences at, beneath, or above the focus. Sibling-only difference records are - excluded, but ancestor records may include changes outside PromptKit. A nonempty - report therefore does not necessarily establish that PromptKit settings changed. - Preserve native ordering, sequence-atomic comparison, and paired redaction; - do not implement a separate subtree comparison algorithm. -- Views compare the same native location even when the application Go root types - differ. Follow upstream's errors for mismatched scopes or unavailable views. -- A valid absent scope still yields a view, allowing history and added/removed - comparisons. Constructor success does not establish effective presence. Rendering - an absent effective value fails without output; explicit null renders normally. - -Application-level inspection remains useful for the whole shared configuration. -The focused view adds convenience and supports existing integrations without -claiming exclusive access to PromptKit information. Resource APIs continue to -select and describe logical prompts, profiles, and backends independently of -configuration-tree paths. - -### Resource Version Validation - -**Accepted:** this migration gives up PromptKit-specific validation of `version` -fields in resource documents, including collection, prompt, and profile -definitions. This is an intentional simplification with a small practical cost, -not an unresolved compatibility requirement or a prerequisite for an upstream -version-policy feature. - -The application retains ownership of ConfigKit's version policy. ConfigKit-owned -headers and directives follow that policy and native composition semantics; -PromptKit adds no separate resource-version checks. Apply this resource decision -to both application-owned loading and standalone construction. Update examples -and migration guidance accordingly, without preparsing or stripping headers or -adding a second load. - -## Integration Evidence And Scope - -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 [implementation plan](implementation.md) owns the concrete API choices, -ordered work, migration steps, and verification needed to reach this target. -The prototype used separate public/internal settings and conversions; the -accepted shared model replaces that experimental boundary arrangement. Its -external-package decoding, registration, and capture paths will be verified -during implementation alongside the existing ownership checks. - -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. diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md deleted file mode 100644 index a16e755..0000000 --- a/docs/roadmap/remediation.md +++ /dev/null @@ -1,294 +0,0 @@ -# Configuration Handoff And Repair Review - -Reviewed implementation stages 1–17 against -[the implementation plan](implementation.md), -[the feature roadmap](next-release-considerations.md), and accepted ADRs -[0001](../adr/0001-configuration-boundary.md) and -[0002](../adr/0002-shared-configuration-data-model.md). -Implementation baseline: `40f8a6825359b4923645256e230a050dfdb00710`; -reviewed changes begin after `248d0db`. - -## Findings - -### 1. Narrow The Pre-Handoff Mutation Wording To The Accepted Expectation - -Status: complete. Priority: P3. Implementation stage: 16. - -Completion: narrowed constructor GoDoc and consumer guidance to the consistency -expectation; reviewed against the roadmap. No runtime behavior changed. - -Locations: `engine.go:280` and `docs/consumers/pkg-promptkit.md:132`. - -`NewFromConfig` says callers **must not mutate** selected settings between loading -and handoff; the consumer guide repeats that blanket instruction. The accepted -roadmap instead asks callers to hand off before changes that invalidate the -frozen inspection/provenance evidence, and expressly treats this as a usage -expectation rather than a new enforcement mechanism. The published wording -prohibits even value-preserving reassignment or copying, which needs no such -restriction. - -Required change: describe the narrower consistency expectation in both owners. -Explain that construction consumes the resolved settings while inspection retains -the completed load's frozen evidence, so callers should keep those consistent at -handoff. Preserve the existing protection against mutation after construction. -No mutation detection, extra validation pass, or new error is needed. - -Verification: review both passages against the feature roadmap's ownership -paragraph; ensure they no longer impose an unconditional mutation prohibition. -This is a documentation correction and does not require a new runtime test. - -### 2. Keep Application-Field Sensitivity Policy With The Application - -Status: complete. Priority: P3. Implementation stage: 16. - -Completion: backend and profile guidance now assigns extension sensitivity and -disclosure to applications, retaining the credential/redaction warning. Reviewed -against the accepted extension contract; no runtime changes were needed. - -Location: `docs/formats.md:235–236`. - -The backend format reference says an unrecognized backend field is application -data and **must not contain secrets**. The accepted extension-point contract -assigns interpretation, validation, and sensitivity rules for those fields to -the application. The implementation follows that contract: inline fields remain -in native inspection, application sensitivity predicates compose with PromptKit's, -and those fields are omitted from resource reports and provider parameters. -The added prohibition unnecessarily narrows the application-owned data contract. - -Required change: retain the useful warning that a raw `api_key` extension is not -a PromptKit credential input and is not automatically redacted by PromptKit. -State that the application owns sensitivity declarations and disclosure policy -for its extension fields, rather than prohibiting their contents. Review the -adjacent profile wording for the same distinction between PromptKit credentials -and application-owned data. Do not add automatic credential behavior or a new -validator for application fields. - -Verification: compare the revised text with the feature roadmap's -application-specific-fields contract and existing focused-inspection sensitivity -coverage. No change to execution or redaction implementation is needed. - -### 3. Preserve Effective Input Metadata Supplied By Application Defaults - -Status: complete. Priority: P2. Implementation stages: 5–6 and 13. - -Completion: capture reports effective required=true and preserves nullable input -metadata from typed values. Public regressions for Go defaults and recorded -collection defaults failed before the fix and pass afterward, alongside focused -race-enabled presence/normalization tests and offline preflight checks. - -Locations: `internal/configuration/load.go:208–216`, -`internal/configuration/prompts.go:174–180`, and -`internal/configuration/resources.go:81–87`. - -The new application-owned loading path preserves ConfigKit `Defaults` and -application resolution callbacks, but the existing input-inspection machinery -still equates `FieldInfo.Explicit == false` with an absent effective value. -`finalFieldState` consequently discards metadata for values supplied by Go -defaults or recorded derived defaults. These are valid final values, not missing -configuration. - -Reproduced through the public API with a completed ConfigKit load whose -`Definition.Defaults` returns a prompt input equivalent to: - -```go -promptkit.PromptInputSettings{ - Name: "doc", Required: true, - ContentType: new("text/plain"), Description: new("default description"), -} -``` - -With a valid prompt and default profile, `NewFromConfig` succeeds. The final -typed input retains those values; native metadata describes their defaulted, -nonnull presence (`Explicit: false`, `Null: false`, default layer), but: - -- `InspectPrompt` returns `Required: nil` instead of the effective true value. -- `InspectRequirements` correctly classifies `doc` as required but returns nil - content type and description, contrary to its effective-metadata contract. -- `ValidateRequest` without `doc` fails with `ErrPromptRender` and a missing - required-input error, confirming that execution uses the true value that - resource inspection fails to report. - -A second public-API reproduction using an application `Resolve` callback and -`RecordDerivedDefault` for an omitted `required` and `content_type` has the same -result. Source-loaded inputs ordinarily have explicit metadata, which is why -the migrated source fixtures and current handoff tests do not expose this gap. - -Required change: capture effective input metadata from the final typed values -and native final metadata without treating source explicitness as a universal -presence test. Preserve the existing ordinary omission/null and explicit -false/empty-string behavior. Keep source provenance in native inspection; -do not inspect raw sources, replay history, reject application defaults, or -rerun resolution to repair the report. - -Verification: add public integration regressions for both Go defaults and -recorded application-derived defaults. Compare `InspectPrompt`, -`InspectRequirements`, and preparation/preflight for the same captured input, -and retain existing source-presence cases. Include a collection case if the fix -introduces separate root/collection handling; the current capture logic is shared. - -### 4. Avoid Expanding Inheritance Provenance For Input-Presence Flags - -Status: complete. Priority: P3. Implementation stage: 6. -Related to finding 3. - -Completion: presence capture now uses typed values and `Metadata.IsExplicit`, -retaining only required-field flags. Removed the unused three-state metadata -records and full-origin queries from this phase. Focused race-enabled default, -inherited-input, explicit-presence, normalization, and requirements tests passed. - -Locations: `internal/configuration/load.go:173–178` and `208–216`. - -Capture calls `Metadata.Lookup` three times per declared input, then retains only -the `Explicit` and `Null` flags. In the selected ConfigKit v1.4.0 implementation, -`Lookup` also materializes and copies the field's complete inheritance-step list. -ConfigKit keeps that evidence compact internally; the full projection is useful -for operator inspection, but unnecessary for these flags. Its public -`Metadata.IsExplicit` method performs the effective-field query without that -projection. - -Complexity: for `I` input declarations and inheritance depths `h_i`, these -presence queries perform `O(I + sum(h_i))` provenance work, apart from path -processing. A chain of `N` prompts inheriting a constant-sized input declaration -has depths `0..N-1`, producing quadratic ancestry-step work and cumulative -temporary allocations merely to capture linear-sized presence data. Reading one -metadata snapshot, as selected in the plan, does not eliminate this per-query -expansion. - -Refactoring opportunity: combine effective typed values/pointer presence with -`Metadata.IsExplicit` where source explicitness is actually needed. Nullable -content-type and description pointers already distinguish retained values from -absent/null metadata for their public reports. Avoid requesting a complete origin -solely to classify presence, while correcting the default-value handling in -finding 3. Presence classification can be linear in the number of declarations, -plus ordinary path-query costs, independent of inheritance-chain length. - -Keep full `Lookup` operations where source origins are genuinely needed for -resource binding. This finding does not propose a different inheritance algorithm, -metadata snapshot policy, inspection contract, or source-origin fallback. - -Verification: preserve inherited, omitted/null, explicit-false, empty-string, and -application-default metadata outcomes. Confirm from the call path that the -presence-only phase no longer projects inheritance steps. No timing threshold or -real-world benchmark is needed to establish that algorithmic change. - -### 5. Share Immutable Backend Defaults Across Profiles Without Overrides - -Status: complete. Priority: P3. Implementation stage: 6. - -Completion: profile construction now reads capture-owned backend definitions -directly and shares immutable provider maps when no overlay is needed. Registry -and runtime lookups remain defensive, and overlays still copy before merging. -Added lookup/overlay isolation coverage and updated internal documentation. -The full `go test -race ./...` suite and `go vet ./...` passed with Go 1.27.4. - -Locations: `internal/configuration/targets.go:27–29` and `68–78`, -`internal/backend/registry.go:39–48`, and -`internal/domain/smoke_diagnostics.go:124–128`. - -Every captured profile selecting a backend calls the registry's defensive-copy -lookup. That lookup deep-copies the backend's provider parameters, and the -profile retains the copied map even when it has no provider-parameter overrides. -Many profiles selecting one backend therefore retain many identical immutable -trees. This is an inherited cost reused by the new capture path, not a newly -introduced regression. The plan selects precomputed execution profiles and -ownership boundaries, not duplication of identical defaults within the owned -snapshot. - -Complexity: for `P` profiles sharing one backend with `S` provider-value nodes and -no profile-level provider maps, this step costs `Theta(P*S)` copying time and -retained parameter storage, despite only `O(P+S)` distinct input data. The cost is -quadratic when both dimensions grow together. Existing ID sorting is additional -work and is not the target of this finding. - -Refactoring opportunity: obtain an owned backend-default snapshot once per -backend and share its provider map read-only among profiles without overrides. -Keep separate merged maps when a profile needs its own provider parameters. -For the no-override case, default-map copying and storage can become `O(P+S)`; -the existing sorting and public result-copy costs remain unchanged. A small -construction-local cache or use of already owned immutable definitions is -sufficient; a general persistent-map framework is unnecessary. - -Preserve defensive `GetBackend` semantics and copies at runtime/caller/client -boundaries. `GetProfile` already detaches the selected target's provider map, so -sharing construction-owned defaults need not expose shared mutable state to -consumers or merge caller requests into retained configuration. - -Verification: review copy placement to establish the reduction, and retain -backend/profile mutation isolation, override-merge, prepared-state ownership, -and injected-client mutation coverage. Do not make internal pointer sharing a -public guarantee or introduce benchmark thresholds. - -## Initial Review Results And Validation - -- Stage 1: ConfigKit v1.4.0, unchanged Go minimum, and commit-pinned attribution - match the selected module and its notices. -- Stages 2–3: configuration and runtime inputs resolve mode-dependent repair - budgets; explicit zero and null/omission, whole-contract replacement, prepared - retention, and existing repair accounting are covered. -- Stages 4–9: shared settings aliases, composed stateless rules, final-metadata - resource capture, native focused inspection, explicit source mounting, and - shared constructor/assembly paths match the target architecture. -- Stages 10–15: migrated tests and maintained offline examples exercise the - changed boundaries, including concurrent loads, cross-filesystem inheritance, - application extensions, ownership, and standalone/handoff equivalence. -- Stages 16–17: canonical documentation is updated, subject to the two wording - corrections above. No additional functional or architectural defect was found. - -Fresh checks passed with Go 1.27.4, `GOTOOLCHAIN=local`, and `GOWORK=off`: -`go test -race ./...` and `go vet ./...`. Changed Go files have no `gofmt` -differences, and the implementation diff passes `git diff --check`. - -This review changes only this findings document; it does not implement fixes. - -## Integration-Focused Follow-Up - -The second review revisited stages 1–17 at their interaction boundaries: the -ConfigKit upgrade and native metadata semantics; repair-input conversion and -prepared budgets; shared settings and application callbacks; capture, inspection, -mounting, and constructor wiring; migrated tests and examples; and their contracts -with the existing runtime. Finding 3 records the newly reproduced integration -gap. Findings 1 and 2 remain unchanged. - -Additional disposable external-package checks, outside the repository, passed -under the race detector for both `NewEngine` and `NewFromConfig`. They combined -configured default repair with continuation, appended messages, direct session -selection, namespace views, frozen prepared execution, structured output, -numeric-presence settings, usage/observer accounting, capacity release, and -single-pass smoke diagnostics. Both default-metadata reproductions failed their -expected inspection assertions, including under the race detector; those failures -are the evidence for finding 3, not failures in the existing test suite. - -Fresh targeted race-enabled tests passed for the public handoff and runtime -contracts, configuration and use-case packages, maintained examples, capacity, -generation, observation, rendering, and validation. No other integration defect -was found. The prior full-suite and vet results remain applicable to unchanged -implementation code. No repository implementation or test files were changed by -this review. - -## Algorithmic Review - -The third review considered stages 1–17 in order, excluding algorithm choices -expressly selected by the plan. Findings 4 and 5 record two local optimization -opportunities; findings 1–3 remain unchanged. No additional ordinary correctness -bug was found. - -- Stages 1–3: checked the selected metadata API costs, constant-time budget - defaulting/conversion, and the unchanged bounded repair/preparation paths. -- Stages 4–6: checked shared data declarations, per-resource normalization and - validation, known-value ownership traversal, presence capture, and profile - construction. Nested resource/input loops traverse distinct data; the two - findings concern hidden work in helper calls rather than loop syntax. -- Stages 7–9: native reporting remains delegated; diagnostic copying is linear - in returned records/locations, and the constructors add no repeated load or - configuration-sized work to ordinary execution. -- Stages 10–15: checked migrated test and example helpers for additional passes - or algorithm changes; they do not introduce another production loader or - runtime resource scan. -- Stages 16–17: checked the findings against the accepted ownership, inspection, - ordering, and configuration-boundary decisions. Deliberate lexical inventories, - native ConfigKit algorithms, and full-prompt repair remain outside reconsideration. - -This was static complexity analysis of PromptKit and the relevant calls into the -selected ConfigKit release. No performance measurements or benchmarks were run. -Implementation code is unchanged, so prior functional validation remains -applicable; this pass validates the findings-document diff only.