@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/persona/model-participants.ts

@@ -29,6 +29,7 @@ import { createHash } from "node:crypto";
 
 import { memberBaseLabel, parseRosterMember, type RosterMember, type RosterSpec } from "../orchestration/roster.ts";
 import { knownParams } from "../orchestration/strategy.ts";
+import type { ThinkingLevel } from "../core/types.ts";
 import type { StrategyParam } from "../orchestration/sdk.ts";
 
 /** Where a participant's effective model came from — in precedence order. */
@@ -58,6 +59,12 @@ export interface ModelParticipant {
 	model?: string;
 	/** Which step of the precedence supplied `model`. */
 	source: ModelSource;
+	/** The member's SPEC-level effort — exactly the value that lands in `AgentRunSpec.thinking`
+	 *  when a strategy spreads `rosterSpec(member)`. Never resolved against agent defaults or the
+	 *  configured child effort (the engines own that precedence): the row shows what the launch
+	 *  spec carried, the same rule the delegate launch rows follow. Absent when none was declared
+	 *  (absence renders nothing); an explicit `off` is a declared value and is kept. */
+	thinking?: ThinkingLevel;
 	/** Someone already chose this participant's model (inline, a saved assignment, or the agent's own
 	 *  frontmatter) ⇒ never a picker candidate. The session default is deliberately NOT counted. */
 	assigned: boolean;
@@ -135,6 +142,7 @@ function fromSpec(spec: RosterSpec, origin: "roster" | "param", param: string |
 		...(param ? { param } : {}),
 		...(model ? { model } : {}),
 		source,
+		...(spec.thinking ? { thinking: spec.thinking } : {}),
 		assigned: source === "inline" || source === "assignment" || source === "agent",
 	};
 }
@@ -191,16 +199,13 @@ function isAgentName(value: unknown): boolean {
 	return typeof value === "string" && value.trim().length > 0 && !/\s/.test(value.trim());
 }
 
-/** Every participant a run really spawns: the roster first (in run order), then auxiliary actors. */
-export function collectModelParticipants(input: ParticipantInput): ModelParticipant[] {
+/** Every declared execution occurrence, including repeated assignment keys with different pins. */
+export function collectModelParticipantOccurrences(input: ParticipantInput): ModelParticipant[] {
 	const out: ModelParticipant[] = [];
-	const seen = new Set<string>();
 	for (const raw of input.members ?? []) {
 		const spec = toSpec(raw);
 		if (!spec) continue;
 		const p = fromSpec(spec, "roster", undefined, input);
-		if (seen.has(p.key)) continue;
-		seen.add(p.key);
 		out.push(p);
 	}
 	const schema = input.schema ?? (input.strategy ? knownParams(input.strategy) : undefined);
@@ -210,14 +215,22 @@ export function collectModelParticipants(input: ParticipantInput): ModelParticip
 			const spec = auxActorSpec(input, paramName, param);
 			if (!spec) continue;
 			const p = fromSpec(spec, "param", paramName, input);
-			if (seen.has(p.key)) continue;
-			seen.add(p.key);
 			out.push(p);
 		}
 	}
 	return out;
 }
 
+/** One row per assignment key for model setup. Repeated execution occurrences share that choice. */
+export function collectModelParticipants(input: ParticipantInput): ModelParticipant[] {
+	const seen = new Set<string>();
+	return collectModelParticipantOccurrences(input).filter((p) => {
+		if (seen.has(p.key)) return false;
+		seen.add(p.key);
+		return true;
+	});
+}
+
 /** The participants a picker may still ask about: nobody has chosen a model for them, and this
  *  session has not already asked (and been dismissed) for that key. The caller records the keys it
  *  asks about BEFORE asking, so a dismissal is remembered too. */

package/src/persona/orchestrate.ts

@@ -73,6 +73,7 @@ export interface RunStrategyDeps {
 	/** Per-agent lifecycle, for live UI (which roster agent is running/done + its result).
 	 *  `key` is a run-unique display id (disambiguates same-agent roster-role members). */
 	onAgentStatus?: (agent: string, status: AgentStatus, result?: AgentResult, key?: string) => void;
+	onAgentResult?: SDKDeps["onAgentResult"];
 	/** Per-agent streaming progress (rolling output), for live UI. */
 	onAgentProgress?: (agent: string, progress: AgentProgress, key?: string) => void;
 	/** Called as each agent starts with a handle to abort just that agent (UI stop). */
@@ -110,6 +111,7 @@ export async function runPersonaStrategy(
 	if (deps.onModelFallback) sdkDeps.onModelFallback = deps.onModelFallback;
 	if (deps.log) sdkDeps.log = deps.log;
 	if (deps.onAgentStatus) sdkDeps.onAgentStatus = deps.onAgentStatus;
+	if (deps.onAgentResult) sdkDeps.onAgentResult = deps.onAgentResult;
 	if (deps.onAgentProgress) sdkDeps.onAgentProgress = deps.onAgentProgress;
 	if (deps.onAgentStart) sdkDeps.onAgentStart = deps.onAgentStart;
 	if (deps.onAgentSteerable) sdkDeps.onAgentSteerable = deps.onAgentSteerable;

package/src/persona/persona.ts

@@ -244,7 +244,7 @@ export function expandCouncilPreset(draft: CouncilDraft, presets: Record<string,
 /** Per-call council selection. `persona` borrows only that persona's expanded
  * council declaration; it never activates the persona or imports its prompt,
  * model, tools, or permissions. Explicit strategy/roster/params remain local
- * overrides for backward compatibility. */
+ * overrides of those defaults. */
 export interface CouncilInvocation {
 	persona?: string | undefined;
 	strategy?: string | undefined;

package/src/results/archive.ts

@@ -0,0 +1,281 @@
+import { randomUUID } from "node:crypto";
+import {
+	createTerminalResultRecord, isResultRef, pageStoredBody, parseTerminalResultInput,
+	parseTerminalResultRecord, payloadBytes,
+} from "./record.ts";
+import {
+	TERMINAL_RESULT_ENTRY, RESULT_MAX_ENTRIES, RESULT_MAX_PAYLOAD_BYTES, RESULT_LIST_DEFAULT, RESULT_LIST_MAX,
+	type ArchiveEvidence, type ArchiveFailure, type ResultListRequest, type ResultPage, type ResultReadRequest,
+	type ResultStorage, type ResultSummary, type ResultSummaryPage, type ResultWarning, type SaveOutcome,
+	type TerminalResultArchiveDeps, type TerminalResultInput, type TerminalResultRecord,
+} from "./types.ts";
+
+interface RetainedResult {
+	record: TerminalResultRecord;
+	storage: ResultStorage;
+	storageError?: string;
+}
+interface SourceResult { data: unknown; index: number; retained?: RetainedResult }
+type Lookup = { kind: "missing" } | { kind: "ambiguous" | "corrupt" } | {
+	kind: "found"; record: TerminalResultRecord; index: number; retained?: RetainedResult;
+};
+
+function identity(data: unknown): { ref?: string; originKey?: string } {
+	try {
+		if (data === null || typeof data !== "object") return {};
+		const value = data as Record<string, unknown>;
+		return {
+			...(isResultRef(value.ref) ? { ref: value.ref } : {}),
+			...(typeof value.originKey === "string" && value.originKey.length <= 1024 ? { originKey: value.originKey } : {}),
+		};
+	} catch { return {}; }
+}
+
+function summary(record: TerminalResultRecord, storage: ResultStorage): ResultSummary {
+	// Parse again to detach optional usage too; callers never receive our mutable state.
+	const copy = parseTerminalResultRecord(record)!;
+	const { body: _body, payloadHash: _hash, ...metadata } = copy;
+	return { ...metadata, storage };
+}
+
+function validQuery(value: unknown, keys: readonly string[]): boolean {
+	try {
+		if (value === null || typeof value !== "object") return false;
+		const proto: unknown = Object.getPrototypeOf(value);
+		if (proto !== Object.prototype && proto !== null) return false;
+		return Reflect.ownKeys(value).every((key) => {
+			const descriptor = Object.getOwnPropertyDescriptor(value, key);
+			return typeof key === "string" && keys.includes(key) && descriptor?.enumerable === true && "value" in descriptor;
+		});
+	} catch { return false; }
+}
+
+function errorDetail(error: unknown): string {
+	try {
+		const text = error instanceof Error ? error.message : String(error);
+		return text.slice(0, 2048);
+	} catch { return "Storage callback threw an unreadable error"; }
+}
+
+/** One session-file owner, fixed at construction by the adapter. No filesystem, Pi imports,
+ * replay, wake or worker lifecycle. Native history is scanned without caching report bodies;
+ * even over-quota/corrupt histories leave valid unrelated reports queryable. Local accepted
+ * records and uncertain append reservations are bounded by the SAME count/byte ceilings.
+ * The native entry array is a host-owned immutable snapshot: its initial length is pinned so
+ * a host that appends to that same array cannot double-charge our own reserved writes.
+ */
+export class TerminalResultArchive {
+	private readonly deps: TerminalResultArchiveDeps;
+	private hydrated = false;
+	private hydrating = false;
+	private history: readonly unknown[] = [];
+	private historyLength = 0;
+	private historyCount = 0;
+	private chargedEntries = 0;
+	private chargedPayloadBytes: number | null = 0;
+	private localBytes = 0;
+	private readonly retained: RetainedResult[] = [];
+	private readonly warnings = new Set<ResultWarning>();
+	private saving = false;
+
+	constructor(deps: TerminalResultArchiveDeps) {
+		// Copy callbacks/flags: mutating a caller's dependency object cannot retarget this owner.
+		this.deps = { ...deps };
+	}
+
+	save(input: TerminalResultInput): SaveOutcome {
+		if (this.saving || this.hydrating) return this.failure("busy", "A terminal result save or history accounting is already in progress");
+		this.saving = true;
+		try { this.hydrate(); return this.saveInput(input); }
+		finally { this.saving = false; }
+	}
+
+	read(request: ResultReadRequest): ResultPage {
+		if (this.hydrating) return this.failure("busy", "Terminal result history accounting is in progress");
+		this.hydrate();
+		if (!validQuery(request, ["ref", "offset", "limit"]) || !isResultRef(request.ref)) {
+			return this.failure("invalid", "Expected result:<UUID> and an optional stored-body offset/limit");
+		}
+		const found = this.lookup("ref", request.ref);
+		if (found.kind === "missing") return this.failure("unavailable", "Result reference is unavailable in this owning session");
+		if (found.kind !== "found") return this.failure(found.kind, "Result identity is ambiguous or corrupt in this owning session");
+		const page = pageStoredBody(found.record, request.offset, request.limit);
+		if (!page) return this.failure("invalid", "Invalid stored-body UTF-16 offset or read limit (2..16000); surrogate pairs cannot be split");
+		return {
+			ok: true, summary: summary(found.record, this.storage(found.retained)), ...page,
+			...this.evidence(found.record, found.retained),
+		};
+	}
+
+	list(request: ResultListRequest = {}): ResultSummaryPage {
+		if (this.hydrating) return this.failure("busy", "Terminal result history accounting is in progress");
+		this.hydrate();
+		if (!validQuery(request, ["cursor", "limit"])) return this.failure("invalid", "Expected a result-list query");
+		const cursor = request.cursor === undefined ? 0 : request.cursor;
+		const limit = request.limit === undefined ? RESULT_LIST_DEFAULT : request.limit;
+		if (!Number.isSafeInteger(cursor) || cursor < 0 || cursor > this.historyCount + this.retained.length
+			|| !Number.isInteger(limit) || limit < 1 || limit > RESULT_LIST_MAX) {
+			return this.failure("invalid", "Invalid result list cursor or limit (1..50)");
+		}
+		const results: ResultSummary[] = [];
+		let nextCursor: number | undefined;
+		for (const source of this.sources()) {
+			if (source.index < cursor) continue;
+			const record = parseTerminalResultRecord(source.data);
+			if (!record) continue;
+			const found = this.lookup("ref", record.ref);
+			if (found.kind !== "found" || found.index !== source.index) continue;
+			if (results.length === limit) { nextCursor = source.index; break; }
+			results.push(summary(record, this.storage(found.retained)));
+		}
+		return { ok: true, results, ...(nextCursor === undefined ? {} : { nextCursor }), ...this.evidence() };
+	}
+
+	private saveInput(value: unknown): SaveOutcome {
+		const input = parseTerminalResultInput(value);
+		if (!input) return this.failure("invalid", "Invalid terminal result projection or metadata limits");
+		const existing = this.lookup("originKey", input.originKey);
+		if (existing.kind === "ambiguous" || existing.kind === "corrupt") {
+			return this.failure(existing.kind, "The origin already has an ambiguous or corrupt result");
+		}
+		if (existing.kind === "found") {
+			const candidate = createTerminalResultRecord(input, existing.record.ref, input.createdAt ?? existing.record.createdAt);
+			if (JSON.stringify(parseTerminalResultRecord(candidate)) !== JSON.stringify(existing.record)) {
+				return this.failure("conflict", "The immutable origin already belongs to a different terminal payload");
+			}
+			return this.receipt(existing.record, existing.retained, true);
+		}
+		let record: TerminalResultRecord;
+		try {
+			const ref = this.deps.makeRef === undefined ? `result:${randomUUID()}` : this.deps.makeRef();
+			if (!isResultRef(ref)) return this.failure("invalid", "Reference factory must return result:<UUID>");
+			const collision = this.lookup("ref", ref);
+			if (collision.kind !== "missing") return this.failure(collision.kind === "found" ? "conflict" : collision.kind, "Generated result reference is already occupied");
+			record = createTerminalResultRecord(input, ref, input.createdAt ?? (this.deps.clock === undefined ? Date.now() : this.deps.clock()));
+		} catch (error) { return this.failure("invalid", errorDetail(error)); }
+		const cost = payloadBytes(record);
+		if (this.chargedEntries >= RESULT_MAX_ENTRIES || this.localBytes + cost > RESULT_MAX_PAYLOAD_BYTES
+			|| (this.chargedPayloadBytes !== null && this.chargedPayloadBytes + cost > RESULT_MAX_PAYLOAD_BYTES)) {
+			return this.failure("quota", "Terminal result lifetime payload/count quota exhausted; append-only storage is not reclaimed");
+		}
+		// Reserve before invoking host code. A throw may occur AFTER a physical/session commit.
+		// Never retry this origin into another entry or treat memory retention as proof of durability.
+		this.chargedEntries++;
+		if (this.chargedPayloadBytes !== null) this.chargedPayloadBytes += cost;
+		this.localBytes += cost;
+		const retained: RetainedResult = { record, storage: "memory-only" };
+		this.retained.push(retained);
+		if (this.deps.persistent && this.chargedPayloadBytes !== null) {
+			try {
+				this.deps.append(TERMINAL_RESULT_ENTRY, parseTerminalResultRecord(record)!);
+				retained.storage = "session-entry";
+			} catch (error) { retained.storageError = errorDetail(error); }
+		}
+		return this.receipt(record, retained, false);
+	}
+
+	private storage(retained: RetainedResult | undefined): ResultStorage {
+		return retained?.storage ?? (this.deps.persistent ? "session-entry" : "memory-only");
+	}
+
+	private receipt(record: TerminalResultRecord, retained: RetainedResult | undefined, idempotent: boolean): SaveOutcome {
+		const storage = this.storage(retained);
+		return {
+			ok: true, ref: record.ref, storage, summary: summary(record, storage), idempotent,
+			...(retained?.storageError === undefined ? {} : { storageError: retained.storageError }),
+			...this.evidence(record, retained),
+		};
+	}
+
+	private hydrate(): void {
+		if (this.hydrated) return;
+		this.hydrated = true;
+		this.hydrating = true;
+		if (!this.deps.persistent) this.warnings.add("no-session-storage");
+		try {
+			const entries = this.deps.entries();
+			if (!Array.isArray(entries)) throw new Error("Invalid owning-session entry list");
+			this.history = entries;
+			this.historyLength = entries.length;
+			for (const source of this.sources()) {
+				this.chargedEntries++;
+				try {
+					const cost = payloadBytes(source.data);
+					if (this.chargedPayloadBytes !== null) this.chargedPayloadBytes += cost;
+					if (!Number.isSafeInteger(this.chargedPayloadBytes)) this.disablePersistence();
+				} catch { this.disablePersistence(); }
+				if (!parseTerminalResultRecord(source.data)) this.warnings.add("invalid-history");
+			}
+			this.historyCount = this.chargedEntries;
+		} catch { this.disablePersistence(); }
+		finally { this.hydrating = false; }
+	}
+
+	private *sources(): Generator<SourceResult> {
+		let index = 0;
+		for (let i = 0; i < this.historyLength; i++) {
+			try {
+				const raw = this.history[i];
+				if (raw === null || typeof raw !== "object") continue;
+				const entry = raw as Record<string, unknown>;
+				if (entry.type !== "custom" || entry.customType !== TERMINAL_RESULT_ENTRY) continue;
+				// Count the entry even when reading its data throws.
+				let data: unknown;
+				try { data = entry.data; } catch { this.disablePersistence(); }
+				yield { data, index: index++ };
+			} catch { this.disablePersistence(); }
+		}
+		for (const retained of this.retained) yield { data: retained.record, index: index++, retained };
+	}
+
+	/** Two bounded-memory scans, not a report cache or an unbounded identity index. */
+	private lookup(key: "ref" | "originKey", value: string): Lookup {
+		let first: { record: TerminalResultRecord; source: SourceResult } | undefined;
+		for (const source of this.sources()) {
+			if (identity(source.data)[key] !== value) continue;
+			const record = parseTerminalResultRecord(source.data);
+			if (!record) return { kind: "corrupt" };
+			first = { record, source };
+			break;
+		}
+		if (!first) return { kind: "missing" };
+		const canonical = JSON.stringify(first.record);
+		for (const source of this.sources()) {
+			if (source.index === first.source.index) continue;
+			const id = identity(source.data);
+			if (id.ref !== first.record.ref && id.originKey !== first.record.originKey) continue;
+			const record = parseTerminalResultRecord(source.data);
+			if (!record) return { kind: "corrupt" };
+			if (JSON.stringify(record) !== canonical) {
+				this.warnings.add("ambiguous-history");
+				return { kind: "ambiguous" };
+			}
+			this.warnings.add("duplicate-history");
+		}
+		return {
+			kind: "found", record: first.record, index: first.source.index,
+			...(first.source.retained === undefined ? {} : { retained: first.source.retained }),
+		};
+	}
+
+	private disablePersistence(): void {
+		this.chargedPayloadBytes = null;
+		this.warnings.add("accounting-unavailable");
+	}
+
+	private evidence(record?: TerminalResultRecord, retained?: RetainedResult): ArchiveEvidence {
+		const warnings = new Set(this.warnings);
+		if (record?.truncated) warnings.add("body-truncated");
+		if (retained?.storageError !== undefined) warnings.add("append-failed");
+		return {
+			accounting: {
+				chargedEntries: this.chargedEntries, chargedPayloadBytes: this.chargedPayloadBytes,
+				persistenceDisabled: !this.deps.persistent || this.chargedPayloadBytes === null,
+			}, warnings: [...warnings],
+		};
+	}
+
+	private failure(reason: ArchiveFailure["reason"], message: string): ArchiveFailure {
+		return { ok: false, reason, message, ...this.evidence() };
+	}
+}

package/src/results/record.ts

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { isThinkingLevel } from "../core/types.ts";
+import {
+	RESULT_MAX_BODY_CHARS, RESULT_MAX_RECORD_BYTES, RESULT_READ_DEFAULT, RESULT_READ_MAX,
+	type TerminalResultInput, type TerminalResultRecord, type TerminalUsage,
+} from "./types.ts";
+
+const INPUT_KEYS = ["originKey", "originRunId", "status", "agent", "label", "model", "thinkingRequested",
+	"thinkingEffective", "usage", "createdAt", "body", "provenance", "error"];
+const RECORD_KEYS = [...INPUT_KEYS, "version", "ref", "payloadHash", "originalChars", "storedChars", "truncated"];
+const USAGE_KEYS = ["input", "output", "cacheRead", "cacheWrite", "cost", "turns"];
+const REF_PATTERN = /^result:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+export function isResultRef(value: unknown): value is string {
+	return typeof value === "string" && REF_PATTERN.test(value);
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return false;
+	const proto: unknown = Object.getPrototypeOf(value);
+	return proto === Object.prototype || proto === null;
+}
+
+function onlyKeys(value: Record<string, unknown>, keys: readonly string[]): boolean {
+	return Reflect.ownKeys(value).every((key) => {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		return typeof key === "string" && keys.includes(key) && descriptor?.enumerable === true && "value" in descriptor;
+	});
+}
+
+function text(value: unknown, max: number): value is string {
+	return typeof value === "string" && value.trim().length > 0 && value.length <= max && !value.includes("\0");
+}
+
+function counter(value: unknown): value is number {
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function usage(value: unknown): value is TerminalUsage {
+	return object(value) && onlyKeys(value, USAGE_KEYS) && counter(value.input) && counter(value.output)
+		&& ["cacheRead", "cacheWrite", "turns"].every((key) => value[key] === undefined || counter(value[key]))
+		&& (value.cost === undefined || (typeof value.cost === "number" && Number.isFinite(value.cost)
+			&& value.cost >= 0 && value.cost <= Number.MAX_SAFE_INTEGER));
+}
+
+function validFields(value: Record<string, unknown>): boolean {
+	return text(value.originKey, 1024) && text(value.agent, 128)
+		&& (value.status === "done" || value.status === "failed" || value.status === "stopped")
+		&& (value.provenance === "result-output" || value.provenance === "partial-output" || value.provenance === "error")
+		&& typeof value.body === "string"
+		&& (value.originRunId === undefined || text(value.originRunId, 128))
+		&& (value.label === undefined || text(value.label, 256))
+		&& (value.model === undefined || text(value.model, 512))
+		&& (value.error === undefined || (typeof value.error === "string" && value.error.length <= 2048))
+		&& (value.createdAt === undefined || counter(value.createdAt))
+		&& (value.thinkingRequested === undefined || isThinkingLevel(value.thinkingRequested))
+		&& (value.thinkingEffective === undefined || isThinkingLevel(value.thinkingEffective))
+		&& (value.usage === undefined || usage(value.usage));
+}
+
+/** Fixed key order and detached metadata for canonical equality and caller immutability. */
+function fields(value: TerminalResultInput): TerminalResultInput {
+	const u = value.usage;
+	return {
+		originKey: value.originKey, status: value.status, agent: value.agent,
+		...(value.originRunId === undefined ? {} : { originRunId: value.originRunId }),
+		...(value.label === undefined ? {} : { label: value.label }),
+		...(value.model === undefined ? {} : { model: value.model }),
+		...(value.thinkingRequested === undefined ? {} : { thinkingRequested: value.thinkingRequested }),
+		...(value.thinkingEffective === undefined ? {} : { thinkingEffective: value.thinkingEffective }),
+		...(u === undefined ? {} : { usage: {
+			input: u.input, output: u.output,
+			...(u.cacheRead === undefined ? {} : { cacheRead: u.cacheRead }),
+			...(u.cacheWrite === undefined ? {} : { cacheWrite: u.cacheWrite }),
+			...(u.cost === undefined ? {} : { cost: u.cost }),
+			...(u.turns === undefined ? {} : { turns: u.turns }),
+		} }),
+		...(value.createdAt === undefined ? {} : { createdAt: value.createdAt }),
+		body: value.body, provenance: value.provenance,
+		...(value.error === undefined ? {} : { error: value.error }),
+	};
+}
+
+export function parseTerminalResultInput(value: unknown): TerminalResultInput | undefined {
+	try {
+		if (!object(value) || !onlyKeys(value, INPUT_KEYS) || !validFields(value)) return undefined;
+		return fields(value as unknown as TerminalResultInput);
+	} catch { return undefined; }
+}
+
+/** Actual serialized DATA bytes. Undefined/circular/unserializable data has no safe cost. */
+export function payloadBytes(value: unknown): number {
+	const json = JSON.stringify(value);
+	if (json === undefined) throw new Error("Terminal result payload is not JSON serializable");
+	return Buffer.byteLength(json, "utf8");
+}
+
+/** Cut positions are UTF-16 offsets; preserve an existing high/low surrogate pair. */
+function safeEnd(body: string, end: number): number {
+	const before = body.charCodeAt(end - 1);
+	const after = body.charCodeAt(end);
+	return before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff ? end - 1 : end;
+}
+
+export function createTerminalResultRecord(input: TerminalResultInput, ref: string, createdAt: number): TerminalResultRecord {
+	if (!isResultRef(ref) || !counter(createdAt)) throw new Error("Invalid terminal result reference or timestamp");
+	const canonical = fields(input);
+	// Hash the original body separately so canonicalization need not allocate a JSON-escaped
+	// copy of an arbitrarily large input. Hash UTF-16LE: distinct lone surrogates stay distinct.
+	const bodyHash = createHash("sha256").update(canonical.body, "utf16le").digest("hex");
+	// Timestamp equality is checked on the canonical record itself: explicitly supplying
+	// the original default timestamp must not change content identity on a repeat save.
+	const { createdAt: _timestamp, ...content } = canonical;
+	const payloadHash = createHash("sha256").update(JSON.stringify({ ...content, body: bodyHash })).digest("hex");
+	const record: TerminalResultRecord = {
+		...canonical, version: 1, ref, createdAt, payloadHash,
+		body: "", originalChars: input.body.length, storedChars: 0, truncated: input.body.length > 0,
+	};
+	const setLength = (length: number): void => {
+		record.body = input.body.slice(0, safeEnd(input.body, length));
+		record.storedChars = record.body.length;
+		record.truncated = record.storedChars < record.originalChars;
+	};
+	let low = 0;
+	let high = Math.min(input.body.length, RESULT_MAX_BODY_CHARS);
+	while (low < high) {
+		const mid = Math.ceil((low + high) / 2);
+		setLength(mid);
+		if (payloadBytes(record) <= RESULT_MAX_RECORD_BYTES) low = mid;
+		else high = mid - 1;
+	}
+	setLength(low);
+	if (payloadBytes(record) > RESULT_MAX_RECORD_BYTES) throw new Error("Terminal result metadata exceeds record quota");
+	return record;
+}
+
+/** Strict, detached version-1 DATA. No rendering, instructions, callbacks or AgentResult blobs. */
+export function parseTerminalResultRecord(value: unknown): TerminalResultRecord | undefined {
+	try {
+		if (!object(value) || !onlyKeys(value, RECORD_KEYS) || !validFields(value)
+			|| value.version !== 1 || !isResultRef(value.ref) || !counter(value.createdAt)
+			|| typeof value.payloadHash !== "string" || !/^[0-9a-f]{64}$/.test(value.payloadHash)
+			|| !counter(value.originalChars) || !counter(value.storedChars) || typeof value.truncated !== "boolean"
+			|| typeof value.body !== "string" || value.body.length > RESULT_MAX_BODY_CHARS
+			|| value.storedChars !== value.body.length || value.originalChars < value.storedChars
+			|| value.truncated !== (value.originalChars > value.storedChars)
+			|| payloadBytes(value) > RESULT_MAX_RECORD_BYTES) return undefined;
+		return {
+			...fields(value as unknown as TerminalResultInput), version: 1, ref: value.ref, createdAt: value.createdAt,
+			payloadHash: value.payloadHash, originalChars: value.originalChars,
+			storedChars: value.storedChars, truncated: value.truncated,
+		};
+	} catch { return undefined; }
+}
+
+export interface StoredBodyPage { body: string; offset: number; nextOffset?: number; endOfStoredBody: boolean }
+
+export function pageStoredBody(record: TerminalResultRecord, offset = 0, limit = RESULT_READ_DEFAULT): StoredBodyPage | undefined {
+	if (!counter(offset) || offset > record.body.length || safeEnd(record.body, offset) !== offset
+		|| !Number.isInteger(limit) || limit < 2 || limit > RESULT_READ_MAX) return undefined;
+	const end = safeEnd(record.body, Math.min(record.body.length, offset + limit));
+	return {
+		body: record.body.slice(offset, end), offset, endOfStoredBody: end === record.body.length,
+		...(end < record.body.length ? { nextOffset: end } : {}),
+	};
+}