Prepare v0.24.0 release documentation

This commit is contained in:
2026-11-21 18:09:47 +00:00
parent ba5ac651e2
commit 5ea60e9b96
7 changed files with 80 additions and 1565 deletions

View File

@@ -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.

View File

@@ -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/<namespace>`. 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

View File

@@ -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/<namespace>`. File discovery and imports continue
using their existing responsibilities and ConfigKit contexts.
## Machinery The Implementation Can Remove Or Avoid
- Resolver closures that capture one load's input-presence maps. Read the needed
final metadata during capture instead.
- The repair-presence side map once inspection reports the resolved budget.
- The adapter's dependency on `*configkit.Result[document]` and its generic
comparison bridge. Retain a native non-generic view plus diagnostics instead.
- PromptKit-specific resource-version checking.
- A second library configuration load, transferred application context, custom
inspection filtering/rebasing, historical fallback, and registration tracking.
Keep ownership copying at the capture boundary. Application extensions need only
remain in the application result and native inspection; the final implementation
need not copy or carry them into execution objects. No new snapshot or mutation
detection facility is indicated by this check.
## Validation And Limits
The final prototype passed:
```sh
go test -race . -run '^TestHandoffPrototype' -count=3
go vet .
```
Production-file vet also passed for the modified internal configuration and
engine packages. Package-level internal vet encountered baseline tests coupled
to the former private `state.result` field; those tests and the old-layout suite
were intentionally not migrated in this experiment. This is not a claim that a
complete feature implementation or migrated repository-wide suite is finished.
The implementation sprint still needs the separately reviewable dependency
upgrade, final public declarations and ownership adapters, source-helper and
fixture migration, runtime repair-input changes, full-suite validation, and
canonical documentation updates. These are local implementation work, not an
upstream API blocker or a new product decision.

View File

@@ -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/<namespace>` 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.

View File

@@ -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.

View File

@@ -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.