From 3ef2a9e18e1ff0920843019191ec2355f6d00f58 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 5 Nov 2026 12:48:29 +0000 Subject: [PATCH] Complete the remediation planning assessment --- docs/roadmap/planning-assessment.md | 357 +++++++++++++++++++++++++++- 1 file changed, 354 insertions(+), 3 deletions(-) diff --git a/docs/roadmap/planning-assessment.md b/docs/roadmap/planning-assessment.md index f7102c3..36df1ef 100644 --- a/docs/roadmap/planning-assessment.md +++ b/docs/roadmap/planning-assessment.md @@ -197,7 +197,8 @@ absolute self-ID, embedded child-ID, and standard metaschema cases compiled with zero external loads; a real external reference failed with one load. Crucially, an unused `$defs` entry with an external reference did not trigger a load until compiled explicitly. An example payload containing a literal `$ref` -did not trigger loading. A denying loader alone therefore does not establish +did not trigger loading. Repeating with a retrieval URI different from the +document's explicit ID gave the same results. A denying loader alone does not establish that every declared schema is self-contained. **Recommendation and alternatives:** Retain source-specific root loading, then @@ -221,8 +222,9 @@ external loaders, not root path containment/read helpers. Change runner fields and constructor parameters to `validate.ValidationPreparer`, retaining the nil no-op and nil-plan error behavior. Validator constructors can return their concrete pointer types so existing direct `Validate` callers and preparation -both compile; no public facade signature changes are needed. Replace external -resource success fixtures with early-error cases, retain independent root-source +both compile; update the internal engine Options validator slot to the +preparation interface too. No public facade signature changes are needed. +Replace external resource success fixtures with early-error cases, retain independent root-source tests, and add public `WithSchemaFile` option/replacement/error coverage. ## 4. Specify Ownership And Retention Remedies @@ -431,6 +433,64 @@ implementing or explicitly deferring the optional overlay optimization based on expected benefit and complexity; identify estimates as such. Do not add errors, panics, or silent fallbacks to an infallible facade projection. +### Assessment Record + +**Status:** Assessed; implement the overlay optimization and centralize trusted +copy ownership, retaining distinct acceptance policies. + +**Evidence:** `targets.go:overlayProviderMap` clones the complete lower subtree +at every recursive overlap, then clones replacement values. `convert.go:copyAny` +has fast paths plus `copyReflectValue`; graph callers are prepared details, +client requests, execution targets, and structured schemas. These values have +already crossed an acceptance/copy boundary. `internal/jsonvalue` instead owns +fallible input acceptance and bounded copying. The concrete differences are: + +| Property | Runtime `Copy` / `CopyMap` | Existing facade projection | +| --- | --- | --- | +| Numbers and typed collections | Validates; preserves compatible concrete types and exact `json.Number`. | Copies accepted values without numeric interpretation. | +| Indirection / null | Dereferences and normalizes null, sometimes changing container type. | Reflection preserves pointers/typed nils; fast paths have their existing nil behavior. | +| Keys and errors | General schema keys allowed; provider keys cannot be empty; fallible limits/cycle checks. | Infallible; trusts earlier acceptance; no new checks. | +| Mutation | Returns independent accepted state. | Returns independent client/inspection state. | + +**Measurements:** An external Go test overlay calls the unchanged private +overlay function with nested chains containing two scalar keys per level and +an array leaf; inputs are built outside timing. Go 1.27.3, linux/amd64, +Intel i5-7260U, `-cpu=1 -benchmem -benchtime=50x -count=3`: + +| Depth / width / overlap | Observed ns/op range | B/op | Allocs/op | +| --- | --- | --- | --- | +| 2 / 2 / overlapping | 20,104–34,618 | 9,496 | 236 | +| 12 / 2 / overlapping | 263,387–287,814 | 117,869 | 2,609 | +| 40 / 2 / overlapping | 2,355,659–2,580,220 | about 1,241,620 | about 22,672 | +| 4 / 16 / overlapping | 168,483–178,889 | 65,434 | 1,591 | +| 12 / 2 / disjoint upper root | 49,437–53,966 | 32,496 | 686 | + +Harness: `/tmp/promptkit-assessment-aqn3B8/config_test.go`, mapped only in the +Go invocation by `overlay.json`; command was `go test -mod=readonly -overlay=… +./internal/configuration -run '^$' -bench '^BenchmarkAssessmentOverlay$'` with +the flags above, `GOTOOLCHAIN=local GOWORK=off GOPROXY=off`. Repository sources +were not edited. These are baseline costs, not measured optimized speedups. + +**Recommendation and alternatives:** Clone lower once, then recurse into that +owned result for overlapping built-in maps, copying only upper replacements. +This removes repeated descendant clones without another index or framework; +the measured allocations justify this small construction-time improvement. +Preserve null/array replacement, accepted types, error boundaries, and isolation. + +Put infallible trusted cloning in `internal/jsonvalue.CloneTrusted(any) any` and +route facade nested values through it. Preserve current fast-path/null/type +behavior explicitly. Do not substitute fallible `Copy` and hide its error. +Keep validation traversal separate where normalization differs; share only +structural helpers that actually match. Moving trusted cloning to its existing +owner removes the facade's independent implementation responsibility, but does +not by itself eliminate both traversal algorithms. Forcing one configurable +reflection walker is not justified by this evidence. + +**Plan handoff:** Remove source conversion first; preserve independently +specified mutation/type/nil/schema-key cases. Measure the changed overlay with +these same shapes after implementation; do not promise the timing ranges or +global linear-time validation. No optional optimization is deferred here. + ## 8. Assess Requirement Evidence Accumulation And Traversal **Catalog:** 10, 23. @@ -447,6 +507,44 @@ contract. Keep the algorithmic fix distinct from traversal cleanup. Specify preserved dot/root scopes, inactive computed names, and conservative incomplete analysis. No interpreter, expanded grammar, or expression limit is proposed. +### Assessment Record + +**Status:** Assessed; use owned-set merging and one explicit branch protocol. + +**Evidence:** `requirements.go:evaluateValue` creates fresh missing-name sets; +`eq`/`ne` combine recursive evaluation results using +`mergeConditionEvaluations`, which copies every member into fresh sets on each +merge. Later evaluation reads operand values/known flags, not independent +snapshots of these sets. For a left-heavy tree with n distinct missing names, +the source performs `2 + 3 + … + n` membership insertions in merges, excluding +leaf creation: 9 at n=4, 135 at n=16, and 8,255 at n=128. This is an exact +source-derived work count for the described case, not measured elapsed time. +The ordinary two-name case needs only two such insertions. + +`requirementWalker.visit` repeats branch selection, dependency-delta tracking, +inactive traversal, and limitation recording for IfNode/WithNode. The latter +changes body dot but keeps else dot. Existing known-condition/scope tests compare +against actual Go rendering and remain independent semantic evidence. + +**Recommendation and alternatives:** Treat intermediate evidence sets as owned +by their evaluation result. Merge into the larger existing set, adding only +the smaller set's members (nil sets transfer directly), while combining flags +as now. This removes the repeated copying in the demonstrated left-heavy case +and bounds repeated movement better on balanced trees. A single global mutable +accumulator would complicate branch-local evidence and is not needed. + +Share IfNode/WithNode orchestration through their existing `parse.BranchNode` +representation, handling the With node's body-dot calculation explicitly inside +the narrow helper. Keep recognition/evaluation separately readable; do not +merge the inspector with template execution. A generic visitor/callback +framework or more recognized syntax would not help this defect. + +**Plan handoff:** Protect set union/flag outcomes and representative left-heavy +inspection without asserting helper allocation counts as a durable contract. +Retain known/skipped/unknown branch classification, changed-dot/root access, +inactive computed-name behavior, and meaningful limitation bookkeeping. The +algorithmic fix may land before branch extraction; both remain selected work. + ## 9. Assess Bounded Repair-Feedback Encoding **Catalog:** 17. @@ -464,6 +562,49 @@ cases, or a justified proposed deferral if benefit does not warrant complexity. Any deferral must acknowledge the outstanding allocation issue. Do not cap raw diagnostics, discard stored errors, or assert an exact peak-heap guarantee. +### Assessment Record + +**Status:** Assessed; implement bounded normalization/encoding, not a deferral. + +**Evidence:** `repairer.go:formatRepairDiagnostics` normalizes every complete +diagnostic, marshals the whole list, then marshals complete entries again when +over budget. Truncation also marshals candidate prefixes repeatedly. Full errors +and previous candidate are retained separately from this feedback string. +An external test overlay calls only the unchanged formatter. With Go 1.27.3, +the topic 7 CPU/environment, `-cpu=1 -benchmem -benchtime=20x -count=3`, one +64-byte ASCII diagnostic costs about 780–1,198 ns and 224 B/op. A 1 MiB ASCII +diagnostic costs 5.83–7.99 ms and about 6.81 MB/op; a 1 MiB string repeating +`<&>` plus NUL costs 27.7–39.1 ms and 44.12 MB/op. Observed output lengths are +68, 65,536, and 65,531 bytes respectively. These are baseline aggregate +allocations, not live-heap peaks or measured savings from a replacement. + +Harness: `/tmp/promptkit-assessment-aqn3B8/usecase_test.go` via +`feedback-overlay.json`; `go test -mod=readonly -overlay=… ./internal/usecase +-run '^$' -bench '^BenchmarkAssessmentFeedback$'` with the flags above. Input +strings are built outside timing; input/output lengths are recorded after +timing to avoid Go's ResetTimer clearing custom metrics. A preliminary run +without these metrics found similar allocation magnitudes; the final timings +above are noisy and are not claimed as stable throughput. + +**Recommendation and alternatives:** Preserve the complete-list fast result +when it fits by first attempting bounded construction. If it cannot fit, build +the bounded omission form with the existing reservation/order rules. Process +only each candidate's potentially useful normalized prefix, retaining the +current `strings.ToValidUTF8` behavior for runs of invalid bytes and rune-safe +truncation. Use standard `json.Marshal` on bounded normalized strings and the +existing bounded-prefix selection logic rather than implementing a general +JSON escaper. Escaping may expand bounded scratch space, but must not cause +serialization proportional to an unbounded original diagnostic. A pure +`json.Encoder` into a limited writer is insufficient if it constructs the whole +encoded string before writing. The measured large-string allocation justifies +the focused change; retaining current allocation is not recommended. + +**Plan handoff:** Keep the 64 KiB output rule, ordering, omission marker, valid +JSON, HTML/control escaping, Unicode/invalid-byte normalization, and full stored +errors/candidate. Include fit, exact boundary, oversized single entry, many +entries, and heavily escaped/invalid strings. Measure the same baseline shapes +after implementation; do not make peak-memory or timing values a public promise. + ## 10. Assess Namespace Listing Index Tradeoffs **Catalog:** 20. @@ -480,6 +621,61 @@ while ignoring its construction/retention tradeoff. Recommend a specific layout and query algorithm, or a justified proposed deferral. No pagination, runtime cache, or new ordering/cancellation guarantee is needed. +### Assessment Record + +**Status:** Assessed; use ranges in existing sorted inventories, not a new +persistent namespace index. + +**Evidence:** Configuration captures lexically sorted ID slices in `load.go`. +Its `listing.go` copies the whole slice before engine `filterIdentityList` +scans and appends matches, even for All mode. Qualified IDs for an exact +`namespace + "/"` prefix form a contiguous sorted range; unqualified IDs need +not form one range. The current private inventory interface has no filter input. + +An external overlay benchmark of the unchanged engine filter uses a list +callback matching configuration's whole-slice copy. Synthetic sorted valid IDs +are built outside timing: sparse selects one ID, dense selects half, absent +selects none. Go 1.27.3, same CPU/environment as topic 7, +`-cpu=1 -benchmem -benchtime=100x -count=3`: + +| Total IDs | Mode | ns/op range | B/op | Allocs/op | +| --- | --- | --- | --- | --- | +| 32 | All / sparse / dense / absent | 1,176–1,332 / 759–937 / 1,053–1,875 / 797–819 | 1,472 / 528 / 960 / 512 | 5 / 2 / 4 / 1 | +| 1,024 | All / sparse / dense / absent | 41,851–48,965 / 13,860–19,334 / 38,416–45,031 / 15,258–19,282 | 78,144 / 18,448 / 37,184 / 18,432 | 11 / 2 / 9 / 1 | +| 4,096 | All / sparse / dense / absent | 194,479–202,439 / 92,265–95,215 / 148,209–151,180 / 93,157–94,526 | 305,472 / 65,552 / 166,208 / 65,536 | 14 / 2 / 12 / 1 | + +Harness: `/tmp/promptkit-assessment-aqn3B8/listing_test.go` via +`listing-overlay.json`; `go test -mod=readonly -overlay=… ./internal/engine +-run '^$' -bench '^BenchmarkAssessmentListing$'` with the flags above. This +isolates filtering/copy cost, not full engine construction or public projection. +Repeated namespace requests repeat that measured whole-inventory allocation. + +**Recommendation and alternatives:** Resolve the filter in the engine first. +Pass an internal `configuration.IdentityFilter{All bool, Namespace string}` to +the captured inventory: All copies the complete slice once; named selection +uses binary search to find the prefix's start/end and copies only that range; +empty Namespace with All false scans for unqualified entries directly from +immutable state, without first copying everything. Apply the same selection +to backend/profile IDs and prompt identities, preserving ordering and final +context checks. No public signature changes are needed. + +This selects the audit's sorted-range alternative: named selection has expected +comparison work proportional to log N plus its output, while unqualified +selection remains a scan. Retaining buckets/range maps could reduce repeated +named lookup to a map operation and index unqualified results, but adds per-kind +retained state and construction work even when a consumer never lists resources. +Existing sorting already supplies named ranges with no new persistent index or +additional construction traversal. The measured wasted copying justifies the +simple range remedy, not extra permanent buckets. These cost comparisons are +design estimates; no alternative implementation was benchmarked. + +**Plan handoff:** Update the private inventory interface and its test fakes; +test exact namespace prefixes, prefix-sharing names, mixed unqualified entries, +All/default/view scope, absent results, mutation isolation, and cancellation. +Repeat the baseline measurements after implementation. Do not introduce a +cache, pagination, or a new unqualified-query complexity guarantee. This is a +selected remedy, not a proposed deferral of catalog 20. + ## 11. Select Remaining Refactoring, Test, And Cleanup Boundaries **Catalog:** 11–14, 22, 25, 28–34; consolidate related conclusions above. @@ -501,6 +697,81 @@ ordering dependencies. Do not infer that self-tests justify production helpers, or that lack of example coverage makes supported APIs obsolete. This is not a new deletion sweep, exact helper-design exercise, or complexity-metric target. +### Assessment Record + +**Status:** Assessed; retain focused package boundaries and remove the recorded +residue, not a broader subsystem. + +**Evidence:** Current `validateEffective`, `materializePrompt`, and +`buildExecutionProfiles` match the responsibility mixtures in audit 03. Current +`Coordinator.execute` returns outcome, dispatched, two durations, and start time; +the retry loop independently projects these into evidence and observation. +Graph caller checks reconfirm eight test callers for `capacity.NewClient`, only +the respective self-test for `RelativePath`/`resourceNamespaceFromID`, and no +callers for `stringPtr`. `loaded.backends` is only populated during resolution; +`QueueCapacitySet` is only assigned/asserted. Domain `OutputFormat` duplicates +the validated output contract; runtime `ContentFile` is not populated by prompt +capture. `HashDefinition` marshals these fields, so their deletion changes hashes. +Private reachability `initialEndpoint` and the third `fileSource` result have +the unused roles recorded in audit 12. + +`internal/configuration/bundled_test.go` already has the complete independent +17-profile/model inventory, but uses formatted-map plugin checks. Public bundle, +wire, and smoke tests repeat expected models/defaults. `formatting.go` implements +RunRequest formatting; `types.go` omits its direct API key from JSON. Existing +artifact size-hint tests calculate SHA-256 despite opaque public hash semantics. + +**Recommendation and alternatives:** Use these concrete extraction/removal units: + +- Keep `validateEffective`'s final-resource/index traversal; extract backend, + profile, and prompt record validators with explicit record/path/index inputs. + Keep typed presence interpretation together in execution-profile construction. +- Split prompt materialization into input/metadata projection, message + content/template capture, and output-contract conversion. Retain lazy origin + lookup, source-relative reads, and a single final inspection/hash assembly. + Do not add a second configuration validation pass or generic field schema. +- Replace execute's parallel returns with an `attemptResult` carrying + `Outcome llm.AttemptOutcome`, `Dispatched`, `CapacityWait`, `RequestDuration`, + and `StartedAt`. Share usage/evidence/event projection helpers where the facts + match. Keep built-in retry and injected one-shot control flow separate; release + permits before accounting callbacks/backoff. Topic 5's stage marker remains + independent of attempt accounting. +- Change the initial/repair scheduling test to `generation.NewInjected` with + the same capacity manager, then retire production `capacity/client.go` and + its retention prose. Test capacity primitives directly or with a small + test-only wrapper; preserve FIFO/cancel/race/panic/independent-pool scenarios. +- Keep the complete bundled asset oracle in `internal/configuration/bundled_test.go` + and use structural plugin expectations there. Public option tests own toggles, + order, isolation, and override behavior. Keep a small wire test of a controlled + model/plugin override and a smoke test of configured default selection; do not + repeat the complete maintained model matrix outside its owner. +- Add marker-based formatting tests for RunRequest values/pointers with `%v`, + `%+v`, `%#v`, and direct String/GoString, plus direct-key JSON omission. + Put markers in omitted contents, such as variables, bodies, and execution + settings, not IDs deliberately present in summaries. Do not pin the entire + formatted or serialized shape. +- Replace size-hint literal digests with same-body inline/file hash equality; + retain body/actual-size/read-boundary assertions. Prepare an opaque benchmark + expected hash outside timing instead of independently selecting its algorithm. +- Delete only unused backend presence capture/field list/map and the runtime + queue-presence flag; keep profile/input presence and ConfigKit provenance. + Remove duplicate captured output format/runtime message-file fields and their + unreachable fallback, preserving actual YAML loading and override defaults. + Remove the private probe endpoint echo, discarded helper return, orphan + wrappers/self-tests, and unused pointer helper identified above. + +Keeping existing broad functions is viable but leaves the audited review burden; +a general configuration/attempt framework would obscure the explicit rules. +No evidence justifies either alternative over these small extractions. + +**Plan handoff:** Correct credential, provider-map, and identity comments in their +canonical owners. Update internal assembly/capacity/validation descriptions when +code lands, and consumer/format/wire guidance plus release migration notes for +ownership, schema, accepted source values, and definition hashes. Include topic +3's public schema-file wiring cases. Preserve request override empty-format +defaulting and inspection/preparation hash equality, not literal old hashes. +Independent caller/behavior checks, not graph reachability alone, justify deletion. + ## 12. Consolidate Recommendations For Implementation Planning Review the assessment records in order and reconcile cross-topic choices. @@ -527,3 +798,83 @@ and proportionate validation. Implementation correctness, race regressions, post-change measurements, and release checks remain work for implementation and release preparation. No claim of remediation completion follows from this assessment, and no new recurring release or human-review gate is introduced. + +### Assessment Record + +**Status:** Assessed; all twelve topics have recommendations. No remediation is +implemented, and no catalog entry is proposed for deferral. + +**Evidence and recommendation:** The source review, dependency probe, baseline +measurements, and caller checks recorded above settle the consequential choices. +Keep the roadmap's accepted product scope. Use the following mapping as the +handoff inventory, not as 34 mandatory implementation stages: + +| Catalog | Assessment topic | Recommended remedy | Implementation evidence to retain/add | +| --- | --- | --- | --- | +| 1 | 1 | Select existing Go 1.27.3; document ordinary-development selection. | Actual toolchain version and focused advisory reassessment; no consumer-minimum bump. | +| 2 | 6 | Bounded authentication read and explicit limit reason. | Exact/overflow and inaccurate-length cases, closure, neutral acceptance facts. | +| 3 | 2 | Remove pre-Mapping recursive source expansion. | Direct nested handoff/capture and ConfigKit-deferred cycle diagnostics. | +| 4 | 4 | Artifact result ownership transfer; keep defensive adapter copy. | Public GoDoc, independently owned concurrent returns, adapter isolation. | +| 5 | 2 | Remove lossy number conversion with the same adapter. | Unsupported-number deferred error and supported built-in numeric handoff, not new precision promises. | +| 6 | 3 | Self-contained root plus compiler-enforced reference policy. | Internal/embedded IDs and anchors work; external references, including unused definitions, fail before dispatch. | +| 7 | 5 | Explicit owning-operation category across public mapping. | Nested client/reader causes and specialized public error preservation. | +| 8 | 5 | Record actual response-reader failures separately. | Both decoder stages, retained cause/redaction, malformed versus transport distinction. | +| 9 | 5 | Internal built-in preparation-failure evidence flag. | Invalid diagnostic construction returns an ordinary Go error; intentional reports remain reports. | +| 10 | 8 | Merge owned temporary sets small-to-large. | Representative deep condition outcomes and preserved independent renderer comparisons. | +| 11 | 11 | Test request formatting privacy at its public boundary. | Synthetic-marker assertions for value/pointer formats and direct-key JSON omission. | +| 12 | 11 | Correct credential-inspection GoDoc/example. | Explicit profile environment selection versus backend-derived default. | +| 13 | 11 | Correct provider-map integration summary. | Link to format-owned recursive overlay versus runtime replacement semantics. | +| 14 | 11 | Correct identity/listing comments. | Literal IDs and current collection release-version ownership. | +| 15 | 3 | Public single-schema-file wiring tests. | Real temporary schema, source replacement/precedence, relevant path errors. | +| 16 | 4 | Standalone immutable runner ownership token. | Foreign owner, namespace view, one-shot claim/discard, retained details. | +| 17 | 9 | Bounded normalized-prefix construction and JSON encoding. | Existing output semantics and same-shape post-change allocation measurements. | +| 18 | 4 | Clone accepted normalized session strings. | Existing Unicode/trim/content/hash/wire behavior. | +| 19 | 7 | Clone lower once; overlay into owned descendants. | Null/array/map semantics, input isolation, repeat baseline measurements. | +| 20 | 10 | Select sorted named ranges before copying. | Sparse/absent/mixed/All/view cases, detachment/cancellation, repeat measurements. | +| 21 | 3 | Shared compilation and explicit preparation interface. | Source-specific containment, direct malformed-output ordering, frozen validation. | +| 22 | 11 | Record-specific configuration and capture helpers. | Final-handoff/presence/origin behavior and meaningful error paths. | +| 23 | 8 | Share branch orchestration; separate evaluation/evidence responsibilities. | If/With scope, skipped paths, partial coverage, independent rendering oracle. | +| 24 | 7 | Centralize trusted clone ownership; preserve distinct validation policies. | Concrete types, nils, numbers, schema keys, caller-owned snapshots; no new projection failure. | +| 25 | 11 | Attempt-result value plus shared accounting projections. | Permit lifetime, status-only retry, injected single dispatch, evidence and usage presence. | +| 26 | 6 | OpenRouter authentication protocol in outbound adapter. | Default/override destination, anonymous probe, factual reporting/privacy. | +| 27 | 6 | Direct target detachment; retire unused smoke cloners. | Provider-map errors, facade ownership, live backend metadata copying. | +| 28 | 11 | One independent bundled catalog oracle. | Smaller option, controlled wire, and diagnostic-selection tests. | +| 29 | 11 | Opaque relational artifact hash assertions. | Complete body/actual size and source parity; benchmark setup outside timing. | +| 30 | 11 | Remove unused backend presence bookkeeping. | Explicit zero/default queue behavior and retained operator provenance. | +| 31 | 11 | Remove duplicate captured fields/fallback. | Real content-file capture, override default, hash equality relationships and migration note. | +| 32 | 11 | Remove private endpoint echo and unused directory return. | Actual sanitized HTTP evidence and public schema-file behavior. | +| 33 | 11 | Remove the three orphan helpers and obsolete self-tests. | Caller check plus retained real discovery/identity/listing behavior. | +| 34 | 11 | Move scheduling test to coordinator; remove production wrapper. | FIFO/cancellation/panic/independent-backend assertions remain with owning components. | + +**Dependencies and plan boundaries:** Establish toolchain selection; remove the +source converter before trusted-copy work. Deliver schema policy/shared compiler +and its typed dependency in focused units, with source/wire regressions. Correct +owning errors, stream failures, and diagnostic preparation provenance before +accounting extraction. Authentication bounding/reporting can land before adapter +relocation. Apply the evidence-set fix before branch cleanup where it simplifies +review. Migrate the scheduling test before deleting the wrapper; adjust opaque +hash assertions before removing serialized definition fields. Documentation +corrections and independent cleanup can proceed without waiting on unrelated +performance work. + +Split these into prompt-sized implementation stages rather than one stage per +workstream. Keep consequential defects and optional refactoring separately +reviewable, and update the affected canonical documentation with each behavior +change. Stage-level tests should protect the risks in the table rather than +reproduce every helper branch. The final remediation validation can use the +existing offline workflow without creating additional recurring release gates. + +**Remaining uncertainty and alternatives:** None requires a new product decision +or external publication before planning. Alternatives and rejected complexity +are recorded in the owning topic. Benchmarks of unimplemented alternatives, +post-change peak heap, provider acceptance, and downstream deployments were not +measured and are not claimed. Baseline results establish the avoidable work; +implementation must verify actual improvement and preservation. The schema probe +exposes a concrete unused-definition case that the plan must include, rather +than silently declaring a rejecting loader sufficient. + +**Scope verification:** Only this documentation file is changed in PromptKit. +The temporary harnesses are outside the repository, exercise unchanged code or +the pinned dependency, and make no provider calls. No production implementation, +repository test, module metadata, installed toolchain, public contract, or +release has been changed by the assessment.