diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md index 4e4a6b8..03d5340 100644 --- a/docs/roadmap/remediation.md +++ b/docs/roadmap/remediation.md @@ -67,12 +67,83 @@ input and returned details must not change retained details. If inactive schema values are omitted, assert omission and successful preparation instead. Retain the existing active-schema ownership coverage. +## 2. P2 — Keep Lightweight Prompt Selection Independent Of Inline Schemas + +Status: open. Identified by the follow-up integration audit. Relevant stages: +1, 3, and 5. + +Locations: + +- `internal/configuration/prompts.go:147`: the internal requirement-selection + snapshot includes the complete output contract. +- `internal/configuration/prompts.go:351`: `ownPromptInspection` now calls + `ownOutputContract`, which deep-copies the inline schema. +- `internal/usecase/requirements_inspection.go:38`: dependency inspection obtains + this snapshot to select the prompt and its default profile. +- `internal/usecase/smoke_selection.go:41`: prompt-selected diagnostics use the + same metadata lookup, independently of their private diagnostic schema. + +### Evidence And Impact + +The production path is `resolvePromptInspection` → `GetPromptInspection` → +`ownPromptInspection` → `ownOutputContract` → `CloneTrusted(schema)`. +`InspectRequirements` consumes only `PromptID` and `DefaultProfileID` from that +selection; its input/template analysis separately uses `GetRequirementSnapshot`. +Smoke target selection likewise consumes only prompt identity/default profile. +Neither caller reads the selected prompt's output contract. + +Before this feature, copying that output contract copied scalar fields. With an +inline schema of S nodes/container entries, every such lookup now adds O(S) time +and container allocations, in addition to its previous input-metadata copy. +A large schema annotation is enough to impose this cost without changing any +template requirement or diagnostic selection. File-backed schemas do not impose +an equivalent document-copy cost on these paths, creating an avoidable difference +between otherwise equivalent schema forms. No timing measurements are needed to +establish the extra traversal. + +### Required Outcome + +Keep internal identity/default-profile selection separate from output-schema +payloads. Narrow the selection projection or omit unused output-contract data +there, rather than copying a full schema to satisfy ownership of a value that +neither caller needs. Preserve full, detached schema metadata for the public +`InspectPrompt` resource view and for actual execution preparation. Do not +introduce a schema-size limit or weaken snapshot ownership as a workaround. + +Retain existing requirements and smoke-selection behavioral tests; verify both +paths still select the same prompt/profile and that application schema files +remain unopened. Prefer a narrow internal value boundary over a benchmark gate +or tests coupled to incidental copier call counts. + +## 3. P3 — Scope The Existing Request-Value Limit Documentation + +Status: open. Identified by the follow-up integration audit. Relevant stages: +1, 6, and 8. + +`types.go:82–86` still says generically that excessively deep or large +JSON-shaped request values are rejected. The new `OutputContract.Schema` route +deliberately uses standard JSON encoding/decoding and trusted document copying, +without the provider-extra copier's depth/node bounds. The format reference +already describes that exemption under Schemas. + +An offline public-API check successfully prepared a runtime inline schema with +an `examples` array containing 100,001 null entries. That exceeds the bounded +copier's 100,000-node budget but is correctly accepted by the schema path. +The code follows the accepted design; the older broad GoDoc no longer accurately +describes all JSON-shaped request values after this addition. + +Update the `RunRequest` GoDoc to scope the existing limits to the request fields +that actually use them, and distinguish inline schema documents. Preserve the +general ownership statements. Do not add bounds to schemas to make the old +wording true. This is a documentation correction, not a request for new limit +options, schema guarantees, or additional runtime validation. + ## Review Coverage And Validation -The remaining stages' configuration/root capture, effective source context, -selection/clearing, shared compilation, request replacement, provider/repair -integration, smoke isolation, mixed collections, and documentation migration were -reviewed without another actionable finding. +The initial implementation review covered configuration/root capture, effective +source context, selection/clearing, shared compilation, request replacement, +provider/repair integration, smoke isolation, mixed collections, and documentation +migration without identifying another actionable finding in that pass. On the reviewed commit, using Go 1.27.4 with `GOTOOLCHAIN=local` and `GOWORK=off`: @@ -82,3 +153,18 @@ On the reviewed commit, using Go 1.27.4 with `GOTOOLCHAIN=local` and `GOWORK=off covered by the passing suite. This review changes no implementation code. + +### Follow-Up Integration Audit + +Reviewed the same implementation code at `3bc16bf` (the preceding commit added +only this findings document). All eight stages were revisited with particular +attention to their existing callers and data projections. Findings 2 and 3 are +additional to the still-open ownership finding, not duplicates of it. + +An additional offline public-API diagnostic exercised detached `OnPrepared` and +injected-client schemas, a repaired file-backed run, an inline replacement during +`Coordinate`, a prepared run after source removal, and a later ordinary +preparation failure. Those interactions passed. It also confirmed acceptance of +the large inline annotation described in finding 3. The earlier race-suite/vet +results apply to the unchanged implementation; no live provider calls or +performance measurements were used.