From aae523c91621231b28a72e51abd381c05867e99d Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 19:20:32 +0000 Subject: [PATCH] Clarify repair defaults and configuration inspection boundaries --- docs/roadmap/next-release-considerations.md | 68 +++++++++++++++++++-- 1 file changed, 63 insertions(+), 5 deletions(-) diff --git a/docs/roadmap/next-release-considerations.md b/docs/roadmap/next-release-considerations.md index 46ea0b9..ddd9356 100644 --- a/docs/roadmap/next-release-considerations.md +++ b/docs/roadmap/next-release-considerations.md @@ -18,8 +18,13 @@ correction opportunity without requiring each consumer to opt in. | `json` | 1 | | `json_schema` | 1 | -Use a presence-aware public `RepairAttempts` field: omission selects the mode's -default; explicit zero disables repairs. Retain explicit budgets of two or three +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. @@ -29,8 +34,15 @@ 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. + Implementation planning must specify the presence-aware Go shape and migration -from the current integer field, and cover omission versus explicit zero across +from the current integer field, and cover omission, null, and explicit zero across configuration, typed helpers, and runtime contracts. Document that repair runs only after failed validation and can add generation latency and usage. Existing repair accounting, exhaustion, cancellation, and transient-retry semantics remain @@ -66,6 +78,22 @@ Implementation planning must verify the ConfigKit loading boundary so that unrelated application sections can coexist without PromptKit interpreting or rejecting their contents. Keep field validation within PromptKit's section. +An absent `promptkit` section contributes no application-supplied PromptKit +settings; bundled defaults can still operate. Old root-level keys such as +`prompts` and `profiles` are neither consumed nor specially rejected by PromptKit: +they may be legitimate application-owned settings. Unknown fields inside +`promptkit` remain configuration errors. This does not bypass ConfigKit's own +document/composition validation. Migration documentation must explain that an +unmigrated application document can load without contributing its intended +resources, with a missing prompt becoming apparent when selected. Do not add +legacy-layout detection to compensate for that consequence. + +Scope `InspectConfiguration` value reports and comparisons to PromptKit's section, +retaining actual `promptkit.…` paths and relevant source provenance. Unrelated +application values must not become part of PromptKit's reports or comparisons +merely because they share an input document. Preserve native ConfigKit redaction +and explanation semantics. Resource inspection remains resource-scoped. + Implementation planning must cover: - Updating bundled underlays, source helpers, import destinations, identity @@ -78,8 +106,38 @@ Implementation planning must cover: - Focused coverage for sibling application settings, mounted collections and resources, default overlays, and source-relative message/schema resolution. -No product decisions remain open for these two items. Concrete API shapes and -loader integration remain implementation-planning work. +## Guidance For Implementation Planning + +The product decisions above are accepted. Begin planning with a focused feasibility +check of ConfigKit's public loading and inspection APIs: establish how to validate +the `promptkit` section while allowing siblings, and how to scope effective-value +reports, explanations, and comparisons while retaining native paths, provenance, +and redaction. Do not reconstruct resolved configuration or source history, add a +second composition pass, or quietly broaden inspection to the whole application. +If the public API cannot support this boundary, report the specific gap and options +before committing to an implementation design. + +Then specify the concrete input/resolved Go shapes, source-helper adaptations, +and migration examples. Keep the repair-default and configuration-root changes +separately reviewable even if delivered in the same release. Neither needs a new +execution subsystem or a compatibility resolver. + +Include focused checks for: + +- Mode defaults after composition, null clearing an inherited repair budget, + explicit zero, explicit positive budgets, and the existing rejection of positive + budgets for `none`; cover typed and runtime inputs as well as YAML. +- Concrete budgets in inspection and prepared snapshots, with actual repair + counters retaining their existing meaning. +- Missing `promptkit` with bundled defaults enabled and disabled, application-owned + root keys that resemble legacy settings, and unknown fields inside `promptkit`. +- Inspection and comparison excluding sibling application values, including a + change confined to a sibling section, while PromptKit paths and explanations + retain native provenance and redaction behavior. + +No further product decisions are currently identified. Public API details and the +ConfigKit feasibility check remain planning work, not evidence that implementation +has already been validated. ## Further Candidates