@namzu/sdk 49.0.0 → 50.1.0

package/src/types/session/records.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod'
 import { type EntityIdKind, isEntityId } from '../../utils/id.js'
+import {
+	STRUCTURED_RESULT_MAX_BYTES,
+	parseStructuredResultJson,
+} from '../../utils/structured-result-json.js'
+import { HarnessBindingSchema, HarnessJournalTransitionSchema } from '../harness/schema.js'
 import type { HITLDecisionRequest, HITLResumeDecision } from '../hitl/index.js'
 import type {
 	CheckpointId,
@@ -11,7 +16,7 @@ import type {
 	TopicId,
 	TurnId,
 } from '../ids/index.js'
-import type { Message } from '../message/index.js'
+import { type Message, isRuntimeContextMessageSource } from '../message/index.js'
 import type { ActorRef } from './actor.js'
 import { CostInfoSchema, TokenUsageSchema, TurnBudgetBindingSchema } from './checkpoint.js'
 import {
@@ -70,7 +75,15 @@ const MESSAGE_ROLES = new Set(['system', 'user', 'assistant', 'tool'])
  * schema checks the discriminant and leaves the content to the message types.
  */
 const messageBody = z.custom<Message>(
-	(value) => isPlainObject(value) && MESSAGE_ROLES.has(value.role as string),
+	(value) => {
+		if (!isPlainObject(value) || !MESSAGE_ROLES.has(value.role as string)) return false
+		const source = value.source
+		return (
+			!isPlainObject(source) ||
+			source.type !== 'runtime-context' ||
+			isRuntimeContextMessageSource(source)
+		)
+	},
 	{ message: 'expected a message with a system, user, assistant or tool role' },
 )
 
@@ -276,6 +289,16 @@ const spill = z
 	})
 	.strict()
 
+const structuredResultSpill = spill
+	.extend({
+		path: text.regex(/^tool-results\/[a-f0-9]{64}\.txt$/),
+		manifest: text.regex(/^tool-results\/[a-f0-9]{64}\.txt\.manifest\.json$/),
+		bytes: positive.max(STRUCTURED_RESULT_MAX_BYTES),
+	})
+	.refine((ref) => ref.manifest === `${ref.path}.manifest.json`, {
+		message: 'a structured spill manifest must name its body',
+	})
+
 const subSessionKind = z.enum(['agent_spawn', 'user_handoff', 'intervention'])
 
 const actorRef = z.custom<ActorRef>(
@@ -319,6 +342,7 @@ function inTurn<T extends string, S extends z.ZodRawShape>(type: T, shape: S) {
 // Session
 
 export const SessionStartedRecordSchema = recordSchema('session_started', {
+	harness: HarnessBindingSchema.optional(),
 	projectId,
 	tenantId: tenantId.optional(),
 	topicId: topicId.optional(),
@@ -340,6 +364,7 @@ export const SessionStartedRecordSchema = recordSchema('session_started', {
 })
 
 export const SessionUpdatedRecordSchema = recordSchema('session_updated', {
+	harness: HarnessJournalTransitionSchema.optional(),
 	title: text.optional(),
 	titleSource: z.enum(['derived', 'named']).optional(),
 	archived: z.boolean().optional(),
@@ -382,6 +407,8 @@ export const TurnCompletedRecordSchema = inTurn('turn_completed', {
 	/** The settled answer, or a preview of it when `resultSpill` holds the whole text. */
 	result: text,
 	resultSpill: spill.optional(),
+	/** Accepted JSON stored separately; settlement.structuredOutput is then absent. */
+	structuredOutputSpill: structuredResultSpill.optional(),
 	stopReason: stopReason.optional(),
 	cancelCause: cancelCause.optional(),
 	budget: tokenBudgetSummary.optional(),
@@ -787,6 +814,83 @@ export const SessionRecordSchema = z
 				message: `${r.type} happens only inside a turn and must carry turnId`,
 			})
 		}
+		if (
+			r.type === 'tool_completed' &&
+			r.inputFailure !== undefined &&
+			(!['invalid_json', 'schema_validation', 'input_truncated'].includes(
+				r.inputFailure as string,
+			) ||
+				r.isError !== true)
+		) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['inputFailure'],
+				message: 'inputFailure must classify a failed tool admission',
+			})
+		}
+		if (
+			r.type === 'tool_completed' &&
+			r.skipped !== undefined &&
+			(r.skipped !== true || r.isError !== false || r.inputFailure !== undefined)
+		) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				path: ['skipped'],
+				message: 'skipped must classify a non-error pre-tool hook skip without an input failure',
+			})
+		}
+		if (
+			r.type === 'tool_completed' &&
+			(r.structuredResultJson !== undefined || r.structuredResultSpill !== undefined)
+		) {
+			let validJson = false
+			try {
+				if (r.structuredResultSpill !== undefined) {
+					validJson =
+						r.structuredResultJson === undefined &&
+						structuredResultSpill.safeParse(r.structuredResultSpill).success
+				} else {
+					parseStructuredResultJson(r.structuredResultJson)
+					validJson = true
+				}
+			} catch {
+				// Retained evidence is never repaired or downgraded to a preview.
+			}
+			if (
+				!validJson ||
+				r.toolName !== 'structured_output' ||
+				r.isError !== false ||
+				r.skipped !== undefined ||
+				r.inputFailure !== undefined ||
+				r.via !== undefined
+			) {
+				context.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: [
+						r.structuredResultSpill !== undefined
+							? 'structuredResultSpill'
+							: 'structuredResultJson',
+					],
+					message:
+						'structured result evidence must hold JSON or a spill from a successful direct structured_output execution, never both',
+				})
+			}
+		}
+		if (r.type === 'turn_completed' && r.structuredOutputSpill !== undefined) {
+			const settlement = r.settlement as Record<string, unknown>
+			if (
+				settlement.status !== 'completed' ||
+				settlement.resultSource !== 'structured_output' ||
+				settlement.structuredOutput !== undefined
+			) {
+				context.addIssue({
+					code: z.ZodIssueCode.custom,
+					path: ['structuredOutputSpill'],
+					message:
+						'a structured output spill requires a completed structured_output settlement without inline structuredOutput',
+				})
+			}
+		}
 		if (r.type === 'message') {
 			const content = r.content as { role: unknown }
 			if (r.role !== content.role) {
@@ -851,6 +955,14 @@ export type SessionEventRecord<T extends PersistedSessionEventType = PersistedSe
 	T extends PersistedSessionEventType
 		? Omit<EventOf<T>, 'sessionId' | 'turnId' | 'lineage' | 'v' | 'seq' | 'generation'> &
 				RecordEnvelope &
+				(T extends 'tool_completed'
+					? { readonly structuredResultSpill?: z.infer<typeof structuredResultSpill> }
+					: T extends 'turn_completed'
+						? {
+								readonly resultSpill?: z.infer<typeof spill>
+								readonly structuredOutputSpill?: z.infer<typeof structuredResultSpill>
+							}
+						: unknown) &
 				(T extends TurnBoundSessionEventType ? { readonly turnId: TurnId } : unknown)
 		: never
 

package/src/types/session/step.ts

@@ -159,6 +159,8 @@ export interface StepToolResult {
 	/** Text form, after the model-visible output budget was applied. */
 	output: string
 	isError: boolean
+	/** The pre-tool hook skipped this call; its receipt is not an executed answer. */
+	skipped?: true
 	durationMs: number
 }
 

package/src/types/session/store.ts

@@ -16,7 +16,7 @@ import type {
 	SubSessionKind,
 } from '../../types/session/sub-session.js'
 import type { SessionSummaryRef } from '../../types/summary/ref.js'
-import type { SessionId, TenantId } from '../ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
 import type { ProjectId, SubSessionId, SummaryId, TopicId } from '../session/ids.js'
 
 /**
@@ -145,6 +145,10 @@ export interface SessionView {
  * callers never get a fallback and must branch on missing explicitly.
  */
 export interface SessionStore {
+	/** Explicit opt-in to immutable turn-keyed summaries. Omission does not support child continuation. */
+	readonly supportsInvocationSummaries?: boolean
+	/** Opt in only when updateSession and recordSummary enforce owner-version CAS. */
+	readonly supportsOwnerVersionCas?: boolean
 	// Project CRUD ------------------------------------------------------------
 
 	createProject(params: CreateProjectParams, tenantId: TenantId): Promise<Project>
@@ -241,7 +245,8 @@ export interface SessionStore {
 	 * into.
 	 *
 	 * **In-process only, stated rather than implied.** `DiskSessionStore`
-	 * writes atomically, but its read-compare-write is not a critical section,
+	 * serializes session writes across instances using the same root within a
+	 * process. Its read-compare-write is not a cross-process critical section,
 	 * so two PROCESSES can still both pass the check. Closing that needs a
 	 * lease with an expiry — not a PID registry, because a Session is durable
 	 * and written from hosts where a PID is not a checkable fact. The same
@@ -359,21 +364,30 @@ export interface SessionStore {
 	 * writes commit as one logical unit; mid-crash recovery is replay via
 	 * `SessionSummaryMaterializer.recover()`.
 	 *
-	 * Rejects with {@link SessionAlreadySummarizedError} if a summary already
-	 * exists for the session (re-materialization forbidden; see
-	 * session-hierarchy.md §4.7 immutability invariant).
+	 * Summaries are immutable per `(sessionRef, turnRef)`. An absent `turnRef`
+	 * preserves the original single conversation-summary contract. A supplied
+	 * `turnRef` seals one invocation without replacing any previous summary.
+	 * Rejects a different summary at an already sealed key.
+	 * With expectedOwnerVersion, refuse before persisting or flipping status if
+	 * the current session owner changed. Omission preserves the legacy behavior.
 	 */
 	recordSummary(
 		summary: SessionSummaryRef & { materializedBy: 'kernel' },
 		tenantId: TenantId,
+		expectedOwnerVersion?: number,
 	): Promise<void>
 
 	/**
-	 * Loads the persisted summary for a session. Returns `null` when none has
-	 * been materialized. Cross-tenant reads reject with `TenantIsolationError`
-	 * (Convention #17).
+	 * Loads the original conversation summary, or the exact invocation summary
+	 * when `turnId` is supplied. Returns `null` when that key is unsealed; it
+	 * never substitutes the original or newest summary for a missing invocation.
+	 * Cross-tenant reads reject with `TenantIsolationError` (Convention #17).
 	 */
-	getSummary(sessionId: SessionId, tenantId: TenantId): Promise<SessionSummaryRef | null>
+	getSummary(
+		sessionId: SessionId,
+		tenantId: TenantId,
+		turnId?: TurnId,
+	): Promise<SessionSummaryRef | null>
 }
 
 /**

package/src/types/session/tool-execution.ts

@@ -14,6 +14,12 @@ export interface CompletedToolRecord {
 	readonly toolName: string
 	readonly result: string
 	readonly isError: boolean
+	/** Trusted admission classification retained with the completion, absent in legacy records. */
+	readonly inputFailure?: 'invalid_json' | 'schema_validation' | 'input_truncated'
+	/** Trusted pre-tool hook skip, absent in legacy records; the tool produced no output. */
+	readonly skipped?: true
+	/** Opt-in screened, post-hook JSON from a successful structured_output; independent of the bounded receipt. */
+	readonly structuredResultJson?: string
 }
 
 /** The latest recorded execution boundary of a tool call, not its inferred external effect. */

package/src/types/structured-output/index.ts

@@ -17,8 +17,19 @@ export interface StructuredOutputConfig<TSchema extends z.ZodType = z.ZodType> {
 	mode?: 'tool' | 'native'
 
 	/**
-	 * Turns spent re-prompting when the model answers in prose or fails
-	 * validation. Defaults to {@link DEFAULT_STRUCTURED_OUTPUT_RETRIES}.
+	 * Tool mode only. Default `receipt` settles from the bounded tool message.
+	 * `durable` also records the screened, post-hook JSON before preview capping,
+	 * so a truncated preview does not destroy the candidate. The session log's
+	 * record size limit still applies. This is execution evidence, not acceptance;
+	 * recovered batches retain the existing fresh-inference settlement policy.
+	 */
+	toolResultRetention?: 'receipt' | 'durable'
+
+	/**
+	 * Correction opportunities after missing output or model-argument validation
+	 * failure. Default 2; zero stops after the first invalid response. Tool-mode
+	 * prose and invalid output calls share a checkpointed counter, once per response.
+	 * Host review rejections use the separate maxReviews allowance.
 	 *
 	 * Bounded so a model that cannot satisfy the schema fails loudly rather
 	 * than iterating against `maxIterations`.

package/src/types/summary/ref.ts

@@ -20,7 +20,7 @@
  * `session/summary/errors.ts` — they are NOT pure shapes.
  */
 
-import type { SessionId, TenantId } from '../ids/index.js'
+import type { SessionId, TenantId, TurnId } from '../ids/index.js'
 import type { SummaryId } from '../session/ids.js'
 import type { DeliverableRef } from './deliverable.js'
 
@@ -53,6 +53,8 @@ export interface SessionSummaryKeyDecision {
 export interface SessionSummaryRef {
 	readonly id: SummaryId
 	readonly sessionRef: SessionId
+	/** Immutable completion of one invocation; omission is the legacy conversation summary. */
+	readonly turnRef?: TurnId
 	readonly tenantId: TenantId
 	readonly outcome: SessionSummaryOutcome
 	readonly deliverables: readonly DeliverableRef[]

package/src/types/tool/index.ts

@@ -7,6 +7,7 @@ import type { CodeNavigationProvider } from '../code-navigation/index.js'
 import type { ToolResultGuardrailSpec } from '../guardrail/index.js'
 import type { SessionId, TurnId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
+import type { BackgroundJobOutputWaitOptions, BackgroundJobOutputWaitResult } from '../job/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { Sandbox } from '../sandbox/index.js'
 import type { ToolPresentation } from './presentation.js'
@@ -117,7 +118,13 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 	}
-	get(id: string): { id: string; status: string; exitCode?: number }
+	get(id: string): { id: string; status: string; exitCode?: number; error?: string }
+	/**
+	 * Resolves once the process exists or failed to start (`error` says why).
+	 * Optional: a host that cannot tell may omit it, and `bash` then replies
+	 * without waiting.
+	 */
+	awaitStarted?(id: string): Promise<{ readonly error?: string }>
 	read(
 		id: string,
 		opts?: { fromOffset?: number },
@@ -127,6 +134,7 @@ export interface BackgroundJobRegistryRef {
 		droppedBytes: number
 		status: string
 		exitCode?: number
+		error?: string
 	}
 	kill(id: string): Promise<{ id: string; status: string }>
 	list(): readonly { id: string; command: string; status: string }[]
@@ -144,12 +152,19 @@ export interface BackgroundJobRegistryRef {
 		id: string
 		status: string
 		exitCode?: number
+		error?: string
 	}>
+	/** Observe a bounded literal output condition. Does not express exit-wait intent. */
+	waitForOutput?(
+		id: string,
+		opts: BackgroundJobOutputWaitOptions,
+	): Promise<BackgroundJobOutputWaitResult>
 	/**
 	 * Say that the model is waiting on this job, so the turn stays open for it
 	 * when the model stops calling tools.
 	 *
-	 * Called by `wait_for_job` and nothing else. The kernel holds a finishing
+	 * Called only by the exit mode of `wait_for_job`. Output readiness does not
+	 * mark a job here. The kernel holds a finishing
 	 * run open — bounded, and for no model tokens — only for a job marked
 	 * here; a job nobody marked never delays a turn, which is what a dev server
 	 * or a watcher needs. Optional for the reason `waitForExit` is: a host
@@ -758,6 +773,14 @@ export interface ToolResult {
 	 * the child's turn fails with {@link ToolHandoff.reason} instead.
 	 */
 	handoff?: ToolHandoff
+	/**
+	 * What this call did, as typed fields for the PERSON's view: the exit code
+	 * and the two streams of a command, the path and size of a read, whether a
+	 * write created the file. `output` stays the model's text and is not
+	 * derived from these; a host that headlines a row reads these and never
+	 * the prose. A host-side override of the output (a redaction) drops them.
+	 */
+	facts?: import('./presentation.js').ToolFacts
 }
 
 /**
@@ -776,8 +799,10 @@ export interface ToolHandoff {
  * `bash` reads it as bash does. `sh` reads it for a shell that may be bash or
  * a POSIX shell such as `dash`: every construct the two read differently
  * makes the line opaque, so a line that is not opaque means the same in both.
+ * `cmd` identifies native Windows CMD; its commands are conservatively opaque
+ * until a matching parser is available. It is never read as POSIX shell text.
  */
-export type ShellDialect = 'bash' | 'sh'
+export type ShellDialect = 'bash' | 'sh' | 'cmd'
 
 export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInput> {
 	name: string
@@ -901,7 +926,8 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 * may be bash or a POSIX shell, and every construct the two read
 	 * differently makes the line opaque, so no allow rule approves it. The
 	 * shipped `bash` tool answers `bash` when it will spawn bash on the host
-	 * and `sh` inside a sandbox, whose guest may not have bash.
+	 * and `sh` inside a sandbox, whose guest may not have bash. Native Windows
+	 * CMD reports `cmd`, whose command-specific permission reading is opaque.
 	 */
 	commandDialect?: (context: { readonly sandboxed: boolean }) => ShellDialect
 	/**
@@ -1167,12 +1193,20 @@ export interface PreparedToolExecution {
 /** Result of decoding a tool input at the execution boundary. */
 export type ToolPreparationResult =
 	| { readonly success: true; readonly prepared: PreparedToolExecution }
-	| { readonly success: false; readonly result: ToolExecutionResult }
+	| {
+			readonly success: false
+			readonly result: ToolExecutionResult
+			/** Zod rejected the input; other preparation failures leave this absent. */
+			readonly inputFailure?: 'schema_validation'
+	  }
 
 export * from './repair.js'
 
 export type {
 	ToolCallView,
+	ToolFacts,
+	ToolFailureReason,
 	ToolPresentation,
 	ToolResultView,
+	ToolTextWindow,
 } from './presentation.js'

package/src/types/tool/presentation.ts

@@ -33,6 +33,20 @@ export type ToolCallView =
 			 * what did not happen ("Cancelled — nothing was saved").
 			 */
 			readonly outcome?: 'cancelled'
+			/**
+			 * For a result: a person answered No to this call at review, so it
+			 * never ran. `label` names what it was about (the file, the command)
+			 * and `note` is what the person said, in their own words and capped
+			 * at 4,000 characters. Set only from the review answer, never read
+			 * out of text; a refusal by policy does not carry it.
+			 */
+			readonly declined?: { readonly note?: string }
+			/**
+			 * For a call: what the call is about, as fields. A host headlines the
+			 * row ("Read a.ts", "Searched for export") from these and never from
+			 * the text of `label`.
+			 */
+			readonly facts?: ToolFacts
 	  }
 	/**
 	 * A change to a document. `path` is optional because not every diff is
@@ -50,6 +64,113 @@ export type ToolCallView =
 	/** A command and what it printed. */
 	| { readonly kind: 'terminal'; readonly command?: string; readonly output: string }
 
+/**
+ * A bounded window onto a block of text: the first lines, the last lines, and
+ * how much lay between. Small enough to travel in an event, and enough for a
+ * host to show "head, tail, Show more" without holding the whole output.
+ */
+export interface ToolTextWindow {
+	/** The first lines, or the whole text when it fit. */
+	readonly head: string
+	/** The last lines, present only when lines were left out between `head` and it. */
+	readonly tail?: string
+	/** Lines left out between `head` and `tail`. */
+	readonly omittedLines?: number
+	/** Lines in the whole text. */
+	readonly totalLines: number
+	/** Bytes in the whole text. */
+	readonly totalBytes: number
+}
+
+/** Why a call did not do what it was asked, as a kind a host can phrase for a person. */
+export type ToolFailureReason =
+	| 'not_found'
+	| 'permission_denied'
+	| 'not_a_file'
+	| 'already_exists'
+	| 'blocked'
+	| 'needs_administrator'
+	| 'unknown_tool'
+	| 'timed_out'
+	| 'invalid_input'
+
+/**
+ * What a call was about and what came of it, as typed fields.
+ *
+ * `output` is written for the model and its wording is the model's interface.
+ * A person is shown a different thing, and reading their screen out of the
+ * model's prose is how "STDOUT:" and "1 replacement(s)" reached it. These are
+ * the same facts the tool already knew, stated once, so a host never has to
+ * read text to learn an exit code, a file name or whether a file was created.
+ *
+ * Every field but `kind` is optional: the same shape describes a call that is
+ * still running (what it was asked) and one that finished (what it did).
+ * Paths are as the tool resolved them; a host shortens them for display.
+ */
+export type ToolFacts =
+	| {
+			readonly kind: 'command'
+			/** The command line, on the call. */
+			readonly command?: string
+			readonly exitCode?: number
+			readonly timedOut?: boolean
+			/** The signal that ended it, when one did. */
+			readonly signal?: string
+			readonly stdout?: ToolTextWindow
+			readonly stderr?: ToolTextWindow
+			/** The output was not text; nothing of it is in `stdout`/`stderr`. */
+			readonly binary?: { readonly bytes: number }
+			/** The command was handed to a background job instead of being waited on. */
+			readonly background?: true
+	  }
+	| {
+			readonly kind: 'read'
+			readonly path: string
+			/** The file is not text; the person is told so instead of being shown its bytes. */
+			readonly binary?: boolean
+			readonly bytes?: number
+			readonly totalLines?: number
+			readonly returnedLines?: number
+			/** Only a window of the file was returned. */
+			readonly partial?: boolean
+	  }
+	| {
+			readonly kind: 'search'
+			readonly pattern: string
+			readonly path?: string
+			readonly matches?: number
+			readonly filesMatched?: number
+			readonly filesSearched?: number
+			readonly truncated?: boolean
+	  }
+	| {
+			readonly kind: 'list'
+			readonly pattern: string
+			readonly path?: string
+			readonly count?: number
+			readonly truncated?: boolean
+	  }
+	| {
+			readonly kind: 'edit'
+			readonly path?: string
+			readonly replacements?: number
+	  }
+	| {
+			readonly kind: 'write'
+			readonly path: string
+			/** `wrote` when the file's earlier state could not be established. */
+			readonly operation: 'created' | 'updated' | 'unchanged' | 'wrote'
+			readonly bytes?: number
+			readonly added?: number
+			readonly removed?: number
+	  }
+	| {
+			readonly kind: 'failure'
+			readonly reason: ToolFailureReason
+			/** What it was about: a path, or the tool's name for `unknown_tool`. */
+			readonly subject?: string
+	  }
+
 /** The same shapes, for what a call produced. */
 export type ToolResultView = ToolCallView
 

package/src/utils/json-snapshot.ts

@@ -1,5 +1,14 @@
-/** Clone JSON data without invoking getters or silently dropping values. */
-export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unknown {
+/**
+ * Clone JSON data without invoking getters or silently dropping values.
+ * Raw schema input may preserve its plain-object prototypes; prepared outputs
+ * keep the default canonical shape used by durable JSON round-trips.
+ */
+export function cloneJsonValue(
+	value: unknown,
+	freeze: boolean,
+	path = '$',
+	preserveObjectPrototype = false,
+): unknown {
 	const active = new WeakSet<object>()
 	const copies = new WeakMap<object, object>()
 
@@ -23,8 +32,16 @@ export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unk
 		active.add(candidate)
 		try {
 			if (Array.isArray(candidate)) {
+				if (preserveObjectPrototype && Object.getPrototypeOf(candidate) !== Array.prototype) {
+					throw new TypeError(`${at} must be an ordinary array for raw preparation`)
+				}
 				const extra = Reflect.ownKeys(candidate).filter(
-					(key) => key !== 'length' && (typeof key !== 'string' || !/^(0|[1-9]\d*)$/.test(key)),
+					(key) =>
+						key !== 'length' &&
+						(typeof key !== 'string' ||
+							!/^(0|[1-9]\d*)$/.test(key) ||
+							(preserveObjectPrototype &&
+								(Number(key) >= candidate.length || Number(key) > 0xffff_fffe))),
 				)
 				if (extra.length > 0) throw new TypeError(`${at} has non-JSON array properties`)
 				const result: unknown[] = new Array(candidate.length)
@@ -45,12 +62,12 @@ export function cloneJsonValue(value: unknown, freeze: boolean, path = '$'): unk
 			if (prototype !== Object.prototype && prototype !== null) {
 				throw new TypeError(`${at} must be a plain JSON object`)
 			}
-			// JSON does not preserve prototypes. Canonicalize both admitted plain
-			// shapes to an ordinary object so a disk checkpoint round-trip compares
-			// equal to a fresh preparation of the same semantic value. Properties
-			// are still defined explicitly, so a literal "__proto__" key remains
-			// data rather than changing this object's prototype.
-			const result: Record<string, unknown> = {}
+			// Raw schema input can depend on its prototype. Prepared output instead
+			// canonicalizes both admitted shapes so a disk checkpoint round-trip
+			// compares equal to a fresh preparation of the same JSON value. Explicit
+			// data properties keep a literal "__proto__" key from changing either.
+			const result: Record<string, unknown> =
+				preserveObjectPrototype && prototype === null ? Object.create(null) : {}
 			copies.set(candidate, result)
 			for (const key of Reflect.ownKeys(candidate)) {
 				if (typeof key !== 'string') throw new TypeError(`${at} has a symbol property`)

package/src/utils/structured-result-json.ts

@@ -0,0 +1,10 @@
+import { cloneJsonValue } from './json-snapshot.js'
+
+/** Maximum UTF-8 JSON body retained by opt-in structured result spills. */
+export const STRUCTURED_RESULT_MAX_BYTES = 16 * 1024 * 1024
+
+/** Decode retained result evidence without coercing non-JSON values or rerunning a schema. */
+export function parseStructuredResultJson(text: unknown): unknown {
+	if (typeof text !== 'string') throw new TypeError('Structured result evidence must be JSON text')
+	return cloneJsonValue(JSON.parse(text), false)
+}