From 3bc16bffe686f2039b60fab27b17efa3da73f1e0 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Fri, 20 Nov 2026 15:56:42 +0000 Subject: [PATCH] Record schema snapshot ownership finding --- docs/roadmap/remediation.md | 84 +++++++++++++++++++++++++++++++++++++ 1 file changed, 84 insertions(+) create mode 100644 docs/roadmap/remediation.md diff --git a/docs/roadmap/remediation.md b/docs/roadmap/remediation.md new file mode 100644 index 0000000..4e4a6b8 --- /dev/null +++ b/docs/roadmap/remediation.md @@ -0,0 +1,84 @@ +# Prompt-Owned Schema Review Findings + +Reviewed commit `e9a12d4` against all eight stages of +[implementation.md](implementation.md) and the accepted +[feature roadmap](prompt-owned-schemas.md). + +## 1. P2 — Inactive Runtime Schema Values Break Snapshot Ownership + +Status: open. Relevant stages: 1 and 6. + +Locations: + +- `internal/usecase/runner.go:688`: `resolveOutputContract` retains the caller's + raw `Schema` value outside JSON Schema mode. +- `internal/jsonvalue/trusted.go:20`: `cloneTrustedReflect` recursively copies + maps, slices, pointers, and arrays, but returns struct values unchanged. +- `convert.go:339`: public output-contract projections rely on that copier. + +### Evidence And Impact + +A public-API reproduction supplies this JSON-encodable Go value in a runtime +replacement using `ValidationNone`: + +```go +type schemaValue struct { + Properties map[string]any `json:"properties"` +} +original := schemaValue{Properties: map[string]any{"title": "original"}} +``` + +After successful `PrepareExecution`, mutating +`handle.Details().OutputContract.Schema.(schemaValue).Properties["title"]` +changes both `original.Properties` and the value returned by a later `Details()`. +The reproduction printed `details mutation` for both values. A caller changing +its original map after preparation likewise changes retained details. + +This violates the existing caller-owned `Details`/frozen-snapshot contract. +The schema is inactive, so this reproduction does not change output validation; +it still exposes shared mutable state and can introduce races when callers rely +on the documented ownership boundary. Active runtime schemas take the JSON +encoding/decoding path and do not exhibit this particular problem. + +### Required Outcome And Refactoring Opportunity + +Ensure accepted inactive runtime schema inputs cannot create aliases between +caller storage, returned details/notifications, and retained state. Preserve the +accepted rule that inactive schema values are ignored: do not fix this by adding +schema-validation or JSON-encodability requirements to non-schema modes. + +The simplest approach worth considering is to omit the new inactive runtime +`Schema` value from execution-owned snapshots. Keep configured-resource +inspection's declared schema metadata and the established inactive `SchemaPath` +behavior separate. Alternatively, if inactive inline values are retained in +prepared projections, their copying must actually satisfy the ownership contract +for accepted inputs, including JSON-encodable structs with mutable fields. +Avoid expanding this into a general arbitrary-Go-object cloning API. + +The new `TestInactiveSchemaDoesNotInterpretCyclicValue` also asserts preservation +of a cyclic map's graph topology. Ignoring inactive schema values was requested; +preserving arbitrary inactive object graphs was not. That incidental assertion +should not prevent the simpler solution. Keep a test for successful handling of +inactive cyclic/unencodable values, without imposing graph-preservation behavior +unless deliberately adopted. + +Add a focused public regression for the struct/map case: mutations of caller +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. + +## 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. + +On the reviewed commit, using Go 1.27.4 with `GOTOOLCHAIN=local` and `GOWORK=off`: + +- `go test -race ./...` passed, including the maintained offline examples. +- `go vet ./...` passed. +- The separate public-API reproduction above confirmed the ownership bug not + covered by the passing suite. + +This review changes no implementation code.