Record schema integration review findings

This commit is contained in:
2026-11-20 16:09:20 +00:00
parent 3bc16bffe6
commit 4120d784a2

View File

@@ -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.