Files
promptkit/docs/roadmap/remediation.md

3.9 KiB

Prompt-Owned Schema Review Findings

Reviewed commit e9a12d4 against all eight stages of implementation.md and the accepted feature roadmap.

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:

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.