2026-11-20 15:56:42 +00:00
|
|
|
|
# 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.
|
|
|
|
|
|
|
2026-11-20 16:09:20 +00:00
|
|
|
|
## 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.
|
|
|
|
|
|
|
2026-11-20 15:56:42 +00:00
|
|
|
|
## Review Coverage And Validation
|
|
|
|
|
|
|
2026-11-20 16:09:20 +00:00
|
|
|
|
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.
|
2026-11-20 15:56:42 +00:00
|
|
|
|
|
|
|
|
|
|
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.
|
2026-11-20 16:09:20 +00:00
|
|
|
|
|
|
|
|
|
|
### 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.
|