@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/bus/broker/client.ts

@@ -15,18 +15,21 @@
  * roster cache, and endless reconnect-after-disconnect "storm" are dropped — YAGNI here,
  * see spec B6/Task 4 brief). An unexpected disconnect (host died
  * mid-run) is NOT auto-reconnected: sends silently go nowhere, while in-flight asks/lists
- * reject promptly and clean up their timers — the child keeps executing, mute, never crashing.
+ * reject promptly and clean up their timers. Authenticated result readers are stricter:
+ * one connect attempt, bounded handshake/reads, closed failure replies, never mute success.
  *
  * Pure over an injected socket factory (`net`), mirroring `host.ts`'s `net` param — same
  * transport-injection seam, opposite side of the same fake in tests.
  */
 
-import { randomUUID } from "node:crypto";
+import { randomUUID, timingSafeEqual } from "node:crypto";
 import nodeNet from "node:net";
 import type net from "node:net";
 
 import { createFrameReader, encodeFrame } from "./framing.ts";
-import { type Frame, isFrame } from "./messages.ts";
+import { type Frame, isFrame, isReaderToken } from "./messages.ts";
+import { isReadRequest, isReadReplyFor, readFailure, RESULT_READ_MAX_PENDING, RESULT_READ_TIMEOUT_MS,
+	type ReadReply, type ResultReadRequest } from "../result-reader.ts";
 import type { MsgKind } from "../inproc.ts";
 
 export interface DeliverEvent {
@@ -39,8 +42,10 @@ export interface DeliverEvent {
 }
 
 export interface BrokerClient {
-	/** Connect (capped backoff) and complete the register handshake. */
+	/** Register once. Ordinary comms back off on initial connect; reader grants never retry. */
 	register(): Promise<void>;
+	/** Authenticated bounded read. Failures are fixed closed replies; never a mute success. */
+	read(request: ResultReadRequest, signal?: AbortSignal): Promise<ReadReply>;
 	/** Fire-and-forget; a dead connection silently drops it (spec: "sends report undelivered"). */
 	send(to: string, kind: MsgKind, text: string): void;
 	/** Blocking request; resolves on a matching `replied`, rejects on `signal` abort or the
@@ -63,6 +68,8 @@ export interface MakeBrokerClientDeps {
 	label?: string;
 	group?: string;
 	peers?: boolean;
+	/** Private, one-shot parent grant. Never log this or pass it to a model. */
+	readerToken?: string;
 	/** Injected transport (tests use a paired in-memory fake); defaults to real `node:net`. */
 	net?: typeof import("node:net");
 }
@@ -75,19 +82,17 @@ const ASK_TIMEOUT_MS = 600_000;
 // let a half-open broker pin `contact_peer list/send` until the child idle watchdog fires.
 const LIST_TIMEOUT_MS = 10_000;
 
-function delay(ms: number): Promise<void> {
-	return new Promise((resolve) => {
-		const t = setTimeout(resolve, ms);
-		t.unref?.();
-	});
-}
-
 export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	const netImpl = deps.net ?? nodeNet;
 
 	let socket: net.Socket | undefined;
 	let closed = false;
 	let disconnected = false;
+	let registerStarted = false;
+	let registered = false;
+	let cancelConnect: (() => void) | undefined;
+	let cancelBackoff: (() => void) | undefined;
+	const pendingReads = new Map<string, { request: ResultReadRequest; resolve: (result: ReadReply) => void }>();
 	let registerSettle: { resolve: () => void; reject: (err: Error) => void } | undefined;
 
 	const deliverListeners = new Set<(evt: DeliverEvent) => void>();
@@ -122,9 +127,21 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	function handleFrame(frame: Frame): void {
 		switch (frame.t) {
 			case "registered":
-				registerSettle?.resolve();
+				if (!registerSettle) return;
+				if (frame.handle !== deps.handle || (deps.readerToken !== undefined && (!frame.readerToken
+					|| !timingSafeEqual(Buffer.from(deps.readerToken, "hex"), Buffer.from(frame.readerToken, "hex"))))) {
+					failReaderProtocol();
+					return;
+				}
+				registered = true;
+				registerSettle.resolve();
 				registerSettle = undefined;
 				return;
+			case "result_read_reply": {
+				const pending = pendingReads.get(frame.reqId);
+				if (pending) pending.resolve(isReadReplyFor(frame.result, pending.request) ? frame.result : readFailure("protocol"));
+				return;
+			}
 			case "error":
 				// A correlated error belongs to one request on this connection. Do not let an
 				// unknown/stale correlation id affect the register handshake or another ask.
@@ -132,9 +149,8 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 					pendingAsks.get(frame.msgId)?.reject(new Error(frame.reason));
 					return;
 				}
-				// A bare error is reserved for the register handshake. Older hosts emit this
-				// shape, so keep accepting it for protocol compatibility.
-				registerSettle?.reject(new Error(frame.reason));
+				// A bare error belongs to the register handshake, not an outstanding read.
+				registerSettle?.reject(new Error(deps.readerToken !== undefined ? "Result reader authentication failed." : frame.reason));
 				registerSettle = undefined;
 				return;
 			case "deliver": {
@@ -167,25 +183,43 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		}
 	}
 
+	function failReaderProtocol(): void {
+		registerSettle?.reject(new Error("Result reader protocol failure."));
+		registerSettle = undefined;
+		for (const pending of pendingReads.values()) pending.resolve(readFailure("protocol"));
+		socket?.destroy();
+	}
+
 	function connectOnce(): Promise<net.Socket> {
 		return new Promise((resolve, reject) => {
 			const s = netImpl.connect(deps.endpoint);
 			let settled = false;
+			let timer: ReturnType<typeof setTimeout> | undefined;
+			const finish = (): void => { clearTimeout(timer); cancelConnect = undefined; };
 			const onConnect = (): void => {
 				if (settled) return;
 				settled = true;
+				finish();
 				s.removeListener("error", onError);
 				resolve(s);
 			};
 			const onError = (err: Error): void => {
 				if (settled) return;
 				settled = true;
+				finish();
 				s.removeListener("connect", onConnect);
 				s.destroy();
 				reject(err);
 			};
 			s.once("connect", onConnect);
 			s.once("error", onError);
+			// Permanent sink also covers cancellation before the eventual connect event.
+			s.on("error", () => {});
+			cancelConnect = () => onError(new Error("broker client closed"));
+			if (deps.readerToken !== undefined) {
+				timer = setTimeout(() => onError(new Error("Result reader connection deadline exceeded.")), RESULT_READ_TIMEOUT_MS);
+				timer.unref?.();
+			}
 		});
 	}
 
@@ -198,9 +232,21 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 			try {
 				return await connectOnce();
 			} catch (err) {
+				// Local cancellation is terminal. Waiting on an unref'ed retry timer here
+				// can leave register() pending after the process has no live handles.
+				if (closed) throw new Error("broker client closed");
 				lastErr = err;
 				if (attempt < CONNECT_MAX_ATTEMPTS - 1) {
-					await delay(Math.min(RECONNECT_BASE_MS * 2 ** attempt, RECONNECT_MAX_MS));
+					await new Promise<void>((resolve) => {
+						const finish = (): void => {
+							clearTimeout(timer);
+							cancelBackoff = undefined;
+							resolve();
+						};
+						const timer = setTimeout(finish, Math.min(RECONNECT_BASE_MS * 2 ** attempt, RECONNECT_MAX_MS));
+						timer.unref?.();
+						cancelBackoff = finish;
+					});
 				}
 			}
 		}
@@ -208,6 +254,7 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	}
 
 	function rejectAllPending(reason: string): void {
+		for (const p of pendingReads.values()) p.resolve(readFailure("unavailable"));
 		for (const p of pendingAsks.values()) p.reject(new Error(reason));
 		pendingAsks.clear();
 		for (const p of pendingLists.values()) p.reject(new Error(reason));
@@ -215,7 +262,11 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	}
 
 	async function register(): Promise<void> {
-		const s = await connectWithBackoff();
+		if (registerStarted || closed) throw new Error("broker register is one-shot or closed");
+		registerStarted = true;
+		if (deps.readerToken !== undefined && !isReaderToken(deps.readerToken)) throw new Error("Result reader protocol failure.");
+		// Ordinary comms retain initial-connect backoff. A result grant never reconnects/replays.
+		const s = await (deps.readerToken !== undefined ? connectOnce() : connectWithBackoff());
 		if (closed) {
 			s.destroy();
 			throw new Error("broker client closed");
@@ -226,16 +277,19 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 			createFrameReader(
 				(raw) => {
 					if (isFrame(raw)) handleFrame(raw);
+					else if (deps.readerToken !== undefined) failReaderProtocol();
 				},
-				() => s.destroy(),
+				() => { if (deps.readerToken !== undefined) failReaderProtocol(); else s.destroy(); },
 			),
 		);
 		s.on("error", () => {
+			if (deps.readerToken !== undefined) s.destroy();
 			/* The close event rejects in-flight requests; this listener only prevents an
 			 * unhandled socket error from taking down the child. */
 		});
 		s.once("close", () => {
-			socket = undefined;
+			if (socket === s) socket = undefined;
+			registered = false;
 			// A peer-initiated drop (host teardown/crash) between connect and the handshake
 			// reply would otherwise leave register() pending for the child's whole life.
 			registerSettle?.reject(new Error("connection closed during register"));
@@ -248,10 +302,20 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		});
 
 		return new Promise<void>((resolve, reject) => {
-			registerSettle = { resolve, reject };
+			const timer = deps.readerToken !== undefined ? setTimeout(() => {
+				registerSettle?.reject(new Error("Result reader handshake deadline exceeded."));
+				registerSettle = undefined;
+				s.destroy();
+			}, RESULT_READ_TIMEOUT_MS) : undefined;
+			timer?.unref?.();
+			registerSettle = {
+				resolve: () => { clearTimeout(timer); resolve(); },
+				reject: (error) => { clearTimeout(timer); reject(error); },
+			};
 			write({
 				t: "register",
 				handle: deps.handle,
+				...(deps.readerToken !== undefined ? { readerToken: deps.readerToken } : {}),
 				...(deps.label !== undefined ? { label: deps.label } : {}),
 				...(deps.group !== undefined ? { group: deps.group } : {}),
 				...(deps.peers !== undefined ? { peers: deps.peers } : {}),
@@ -259,6 +323,37 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		});
 	}
 
+	function read(request: ResultReadRequest, signal?: AbortSignal): Promise<ReadReply> {
+		if (signal?.aborted) return Promise.resolve(readFailure("cancelled"));
+		if (!isReadRequest(request)) return Promise.resolve(readFailure("invalid"));
+		if (deps.readerToken === undefined) return Promise.resolve(readFailure("denied"));
+		if (closed || disconnected || !registered || !socket) return Promise.resolve(readFailure("unavailable"));
+		if (pendingReads.size >= RESULT_READ_MAX_PENDING) return Promise.resolve(readFailure("busy"));
+		const reqId = randomUUID();
+		// Snapshot caller data so mutation after dispatch cannot alter correlation checks.
+		const snapshot = { ...request };
+		return new Promise((resolve) => {
+			const finish = (result: ReadReply): void => {
+				if (!pendingReads.delete(reqId)) return;
+				clearTimeout(timer);
+				signal?.removeEventListener("abort", onAbort);
+				resolve(result);
+			};
+			const cancel = (result: ReadReply): void => {
+				finish(result);
+				write({ t: "result_read_cancel", reqId });
+			};
+			const onAbort = (): void => cancel(readFailure("cancelled"));
+			const timer = setTimeout(() => cancel(readFailure("timeout")), RESULT_READ_TIMEOUT_MS);
+			timer.unref?.();
+			pendingReads.set(reqId, { request: snapshot, resolve: finish });
+			signal?.addEventListener("abort", onAbort, { once: true });
+			try {
+				socket!.write(encodeFrame({ t: "result_read", reqId, ...snapshot }));
+			} catch { finish(readFailure("unavailable")); socket?.destroy(); }
+		});
+	}
+
 	function send(to: string, kind: MsgKind, text: string): void {
 		write({ t: "send", to, kind, text, msgId: randomUUID(), expectsReply: false });
 	}
@@ -357,6 +452,9 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 	function close(): void {
 		if (closed) return;
 		closed = true;
+		registered = false;
+		cancelConnect?.();
+		cancelBackoff?.();
 		const s = socket;
 		if (s) {
 			write({ t: "bye" });
@@ -375,5 +473,5 @@ export function makeBrokerClient(deps: MakeBrokerClientDeps): BrokerClient {
 		rejectAllPending("broker client closed");
 	}
 
-	return { register, send, ask, reply, list, onDeliver, onSteer, onClose, close };
+	return { register, read, send, ask, reply, list, onDeliver, onSteer, onClose, close };
 }

package/src/bus/broker/host.ts

@@ -29,17 +29,23 @@
  */
 
 import { existsSync, unlinkSync } from "node:fs";
+import { randomBytes, timingSafeEqual } from "node:crypto";
 import nodeNet from "node:net";
 import type net from "node:net";
 
 import { createFrameReader, encodeFrame } from "./framing.ts";
 import { type Frame, isFrame } from "./messages.ts";
 import type { InProcessBus } from "../inproc.ts";
+import { isReadReplyFor, readFailure, RESULT_READ_MAX_FRAME_BYTES, RESULT_READ_MAX_PENDING,
+	RESULT_READ_MAX_REQUESTS, RESULT_READ_TIMEOUT_MS, type PreparedResultReader, type ReadReply,
+	type ScopedReader } from "../result-reader.ts";
 
 export interface BrokerHost {
 	endpoint: string;
 	close(): Promise<void>;
 	connectedHandles(): string[];
+	/** Parent-only preflight. Reserve before bus/adapter registration or spawning. */
+	prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader>;
 	/** Pushes a `steer` frame directly to a connected handle (spec B4) — the supervisor's own
 	 *  live voice, NOT a bus envelope (it bypasses `bus.send`/the outbound drain entirely, so
 	 *  it can't be mistaken for a peer/child message on the wire). Returns false (a harmless
@@ -158,6 +164,39 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 	const sockets = new Set<net.Socket>();
 	const expected = new Set<string>();
 	const pendingSteer = new Map<string, string[]>();
+	type Grant = { token: Buffer; reader: ScopedReader; active: boolean; bound: boolean; stop?: () => void; revoke: () => void };
+	const grants = new Map<string, Grant>();
+	let closed = false;
+
+	function revokeReader(reader: ScopedReader): void {
+		try { reader.revoke(); } catch { /* cleanup cannot leak callback errors or strand siblings */ }
+	}
+
+	async function prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader> {
+		if (closed || signal?.aborted || !handle || handle.length > 256 || handle === deps.supervisorHandle
+			|| connections.has(handle) || grants.has(handle) || expected.has(handle) || bus.participants().includes(handle)) {
+			revokeReader(reader);
+			throw new Error("Result reader preparation refused.");
+		}
+		const token = randomBytes(32);
+		const grant: Grant = { token, reader, active: true, bound: false, revoke: () => {
+			if (!grant.active) return;
+			grant.active = false;
+			signal?.removeEventListener("abort", grant.revoke);
+			if (grants.get(handle) === grant) {
+				grants.delete(handle);
+				expected.delete(handle);
+				pendingSteer.delete(handle);
+			}
+			token.fill(0);
+			grant.stop?.();
+			revokeReader(reader);
+		} };
+		grants.set(handle, grant);
+		expected.add(handle);
+		signal?.addEventListener("abort", grant.revoke, { once: true });
+		return { token: token.toString("hex"), revoke: grant.revoke, wasBound: () => grant.bound };
+	}
 
 	function flushPendingSteer(handle: string): void {
 		const conn = connections.get(handle);
@@ -207,10 +246,19 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		let handle: string | undefined;
 		let group: string | undefined;
 		const pendingAsks = new Map<string, AbortController>();
+		let ended = false;
+		let boundGrant: Grant | undefined;
+		const seenReads = new Set<string>();
+		const pendingReads = new Map<string, { ac: AbortController; finish: (result?: ReadReply) => void }>();
 
 		const write = (frame: Frame): void => {
 			try {
-				socket.write(encodeFrame(frame));
+				const encoded = encodeFrame(frame);
+				if (frame.t === "result_read_reply" && encoded.length > RESULT_READ_MAX_FRAME_BYTES) {
+					socket.write(encodeFrame({ t: "result_read_reply", reqId: frame.reqId, result: readFailure("protocol") }));
+					return;
+				}
+				socket.write(encoded);
 			} catch {
 				/* peer went away mid-write */
 			}
@@ -220,6 +268,11 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		const conn = { write };
 
 		const cleanup = (): void => {
+			if (ended) return;
+			ended = true;
+			for (const pending of pendingReads.values()) { pending.finish(); pending.ac.abort(); }
+			seenReads.clear();
+			boundGrant?.revoke();
 			for (const ac of pendingAsks.values()) ac.abort();
 			pendingAsks.clear();
 			// `bye` releases the handle while `handle` stays set (the socket's own `close`
@@ -233,10 +286,55 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		const errorReason = (error: unknown): string => error instanceof Error ? error.message : String(error);
 
 		const dispatch = (frame: Frame): void => {
+			if (ended) return;
 			switch (frame.t) {
+				case "result_read": {
+					const grant = boundGrant;
+					const respond = (result: ReadReply): void => write({ t: "result_read_reply", reqId: frame.reqId, result });
+					if (!handle || connections.get(handle) !== conn || !grant?.active) { respond(readFailure("denied")); return; }
+					if (seenReads.has(frame.reqId)) {
+						const pending = pendingReads.get(frame.reqId);
+						pending?.finish();
+						pending?.ac.abort();
+						respond(readFailure("protocol"));
+						return;
+					}
+					if (seenReads.size >= RESULT_READ_MAX_REQUESTS) { grant.revoke(); return; }
+					seenReads.add(frame.reqId);
+					if (pendingReads.size >= RESULT_READ_MAX_PENDING) { respond(readFailure("busy")); return; }
+					const { t: _t, reqId, ...request } = frame;
+					const ac = new AbortController();
+					const finish = (result?: ReadReply): void => {
+						if (pendingReads.get(reqId)?.ac !== ac) return;
+						pendingReads.delete(reqId);
+						clearTimeout(timer);
+						if (result && !ended && grant.active && handle && connections.get(handle) === conn) respond(result);
+					};
+					const timer = setTimeout(() => { finish(readFailure("timeout")); ac.abort(); }, RESULT_READ_TIMEOUT_MS);
+					timer.unref?.();
+					pendingReads.set(reqId, { ac, finish });
+					void Promise.resolve().then(() => {
+						if (ac.signal.aborted || !grant.active) return readFailure("revoked");
+						return grant.reader.read(request, ac.signal);
+					}).then((result) => {
+						try { finish(isReadReplyFor(result, request) ? result : readFailure("protocol")); }
+						catch { finish(readFailure("protocol")); }
+					}, () => finish(readFailure("unavailable")));
+					return;
+				}
+				case "result_read_cancel": {
+					const pending = pendingReads.get(frame.reqId);
+					pending?.finish(readFailure("cancelled"));
+					pending?.ac.abort();
+					return;
+				}
 				case "register": {
+					const reject = (reason: string): void => {
+						write({ t: "error", reason });
+						if (frame.readerToken !== undefined || grants.has(frame.handle)) socket.destroy();
+					};
 					if (frame.handle === deps.supervisorHandle) {
-						write({ t: "error", reason: "reserved handle" });
+						reject("reserved handle");
 						return;
 					}
 					// Registration is one-shot per socket and exclusive per handle: a
@@ -244,19 +342,31 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 					// would then unregister a handle it no longer owns (or leak the one it
 					// silently abandoned).
 					if (handle) {
-						write({ t: "error", reason: "already registered" });
+						reject("already registered");
 						return;
 					}
 					if (connections.has(frame.handle)) {
-						write({ t: "error", reason: `handle already connected: ${frame.handle}` });
+						reject("handle already connected");
 						return;
 					}
+					const grant = grants.get(frame.handle);
+					// A supplied unknown/expired token never falls through to ordinary registration.
+					if (grant || frame.readerToken !== undefined) {
+						if (!grant?.active || grant.bound || !frame.readerToken
+							|| !timingSafeEqual(grant.token, Buffer.from(frame.readerToken, "hex"))) {
+							reject("result reader authentication failed");
+							return;
+						}
+						grant.bound = true;
+						boundGrant = grant;
+						grant.stop = () => { if (!ended) { cleanup(); socket.destroy(); } };
+					}
 					handle = frame.handle;
 					group = frame.group;
 					bus.register(handle);
 					connections.set(handle, conn);
 					if (frame.peers) peerRegistry.set(handle, { handle, label: frame.label ?? handle, group: frame.group ?? "" });
-					write({ t: "registered", handle });
+					write({ t: "registered", handle, ...(frame.readerToken ? { readerToken: frame.readerToken } : {}) });
 					drain(handle);
 					flushPendingSteer(handle);
 					return;
@@ -324,6 +434,8 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 		const handleFrame = (raw: unknown): void => {
 			if (!isFrame(raw)) {
 				write({ t: "error", reason: "invalid frame" });
+				if (boundGrant || (typeof raw === "object" && raw !== null
+					&& ("readerToken" in raw || ("t" in raw && String(raw.t).startsWith("result_read"))))) socket.destroy();
 				return;
 			}
 			try {
@@ -337,8 +449,9 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 			}
 		};
 
-		socket.on("data", createFrameReader(handleFrame, (e) => {
-			write({ t: "error", reason: e.message });
+		socket.on("data", createFrameReader(handleFrame, () => {
+			// JSON parser diagnostics can contain the private registration token.
+			write({ t: "error", reason: "invalid frame" });
 			socket.destroy();
 		}));
 		socket.on("error", () => socket.destroy());
@@ -350,9 +463,9 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 
 	const server = await bindServer(netImpl, deps.endpoint, handleConnection);
 
-	let closed = false;
 	return {
 		endpoint: deps.endpoint,
+		prepareResultReader,
 		connectedHandles: () => [...connections.keys()],
 		steer(handle: string, text: string): boolean {
 			const conn = connections.get(handle);
@@ -370,12 +483,14 @@ export async function startBrokerHost(deps: StartBrokerHostDeps): Promise<Broker
 			expected.add(handle);
 		},
 		forget(handle: string): void {
+			grants.get(handle)?.revoke();
 			expected.delete(handle);
 			pendingSteer.delete(handle);
 		},
 		async close(): Promise<void> {
 			if (closed) return;
 			closed = true;
+			for (const grant of grants.values()) grant.revoke();
 			unsubBus();
 			expected.clear();
 			pendingSteer.clear();

package/src/bus/broker/messages.ts

@@ -5,14 +5,28 @@
  * `messages.ts` validation STYLE (structural per-field checks, one explicit assert per
  * case) but drops presence/sessions/attachments/broadcasts entirely (YAGNI here).
  *
+ * Authenticated result_read/result_read_reply/result_read_cancel frames extend the same
+ * connection with a closed bounded page contract. No archive summaries or client grants.
  * Pure module: no Pi imports, unit-tested.
  */
 
 import type { MsgKind } from "../inproc.ts";
+import { closedRecord, isReadReply, isReadRequest, type ReadReply, type ResultReadRequest } from "../result-reader.ts";
+
+export function isReaderToken(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{64}$/.test(value);
+}
+
+function isRequestId(value: unknown): value is string {
+	return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value);
+}
 
 export type Frame =
-	| { t: "register"; handle: string; label?: string; group?: string; peers?: boolean }
-	| { t: "registered"; handle: string }
+	| { t: "register"; handle: string; label?: string; group?: string; peers?: boolean; readerToken?: string }
+	| { t: "registered"; handle: string; readerToken?: string }
+	| ({ t: "result_read"; reqId: string } & ResultReadRequest)
+	| { t: "result_read_reply"; reqId: string; result: ReadReply }
+	| { t: "result_read_cancel"; reqId: string }
 	| { t: "send"; to: string; kind: MsgKind; text: string; msgId: string; expectsReply: boolean }
 	| { t: "cancel"; msgId: string }
 	| { t: "deliver"; from: string; fromLabel?: string; kind: MsgKind; text: string; msgId: string; expectsReply: boolean }
@@ -39,14 +53,27 @@ function isPeerEntry(value: unknown): value is { handle: string; label: string }
 export function isFrame(value: unknown): value is Frame {
 	if (!isRecord(value)) return false;
 	switch (value.t) {
+		case "result_read": {
+			if (!closedRecord(value, ["t", "reqId", "ref", "offset", "limit"]) || !isRequestId(value.reqId)) return false;
+			const { t: _t, reqId: _id, ...request } = value;
+			return isReadRequest(request);
+		}
+		case "result_read_reply":
+			return closedRecord(value, ["t", "reqId", "result"]) && isRequestId(value.reqId) && isReadReply(value.result);
+		case "result_read_cancel":
+			return closedRecord(value, ["t", "reqId"]) && isRequestId(value.reqId);
 		case "register": {
-			if (typeof value.handle !== "string") return false;
+			if (!closedRecord(value, ["t", "handle", "label", "group", "peers", "readerToken"])) return false;
+			if ("readerToken" in value && !isReaderToken(value.readerToken)) return false;
+			if (typeof value.handle !== "string" || value.handle.length === 0 || value.handle.length > 256) return false;
 			if (value.label !== undefined && typeof value.label !== "string") return false;
 			if (value.group !== undefined && typeof value.group !== "string") return false;
 			return value.peers === undefined || typeof value.peers === "boolean";
 		}
 		case "registered":
-			return typeof value.handle === "string";
+			return closedRecord(value, ["t", "handle", "readerToken"]) && typeof value.handle === "string"
+				&& value.handle.length > 0 && value.handle.length <= 256
+				&& (!("readerToken" in value) || isReaderToken(value.readerToken));
 		case "send":
 			return (
 				typeof value.to === "string" &&