experimental-a2 0.2.0 → 0.4.0

package/dist/devtools-server.js

@@ -1,5 +1,7 @@
-import { n as serverInspection, t as DEVTOOLS_TIMINGS } from "./inspection-E7qbD0Xj.js";
+import { n as InspectionUnsupportedError, r as serverInspection, t as DEVTOOLS_TIMINGS } from "./inspection-DaxB5jM2.js";
+import { c as encodeDevtoolsCapture, n as DEVTOOLS_CAPTURE_MEDIA_TYPE, o as DEVTOOLS_SESSION_PAGE_MAX_LIMIT, s as devtoolsSessionRevision, t as DEVTOOLS_CAPABILITIES } from "./devtools-kJJaORn-.js";
 //#region src/devtools-app.ts
+/** Private browser application served by `experimental-a2/devtools/server`. */
 const escapeText = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 const escapeAttribute = (value) => escapeText(value).replaceAll("\"", "&quot;");
 const formatDuration = (milliseconds) => {
@@ -322,6 +324,91 @@ const request = async (resource, params = {}) => {
   return response.json()
 }
 
+const detailRevision = async (detail) => {
+  const timestamp = (value) => value === null ? null : new Date(value).getTime()
+  const bytes = new TextEncoder().encode(JSON.stringify({
+    events: detail.events.map((event) => [
+      event.id,
+      event.index,
+      event.cause?.index ?? null,
+      event.cause?.attempt ?? null,
+      timestamp(event.processedAt),
+      event.processedByAttempt,
+      timestamp(event.firstClaimedAt),
+      timestamp(event.lastClaimedAt),
+      event.attemptCount,
+      event.failureCount,
+      timestamp(event.lastFailedAt),
+      event.lastFailedAttempt,
+      event.lastError,
+      timestamp(event.failedAt),
+    ]),
+    snapshots: detail.snapshots.map((snapshot) => [
+      snapshot.reducerName,
+      snapshot.index,
+      snapshot.updatedAt === null ? 0 : new Date(snapshot.updatedAt).getTime(),
+    ]),
+  }))
+  const digest = await crypto.subtle.digest('SHA-256', bytes)
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('')
+}
+
+const requestDetail = async (contract, session) => {
+  const events = []
+  let snapshots = []
+  let cursor = null
+  let throughIndex = null
+  const seenCursors = new Set()
+  do {
+    const page = await request('session', {
+      contract,
+      session,
+      limit: ${250},
+      cursor,
+    })
+    if ('revision' in page) return page
+    if (page.contract !== contract || page.sessionId !== session) {
+      throw new Error('Session page identity changed during inspection.')
+    }
+    if (throughIndex === null) {
+      throughIndex = page.throughIndex
+      snapshots = page.snapshots
+    } else if (page.throughIndex !== throughIndex || page.snapshots.length > 0) {
+      throw new Error('Session page frontier changed during inspection.')
+    }
+    for (const event of page.events) {
+      if (event.index !== events.length + 1 || event.index > throughIndex) {
+        throw new Error('Session event pages are not contiguous.')
+      }
+      events.push(event)
+    }
+    if (page.cursor !== null) {
+      if (
+        page.events.length === 0 ||
+        events.length === throughIndex ||
+        seenCursors.has(page.cursor)
+      ) {
+        throw new Error('Session cursor did not advance.')
+      }
+      seenCursors.add(page.cursor)
+    }
+    cursor = page.cursor
+  } while (cursor !== null)
+  if (throughIndex !== events.length) {
+    throw new Error('Session event pages ended before their frozen frontier.')
+  }
+  const detail = {
+    protocolVersion: ${1},
+    contract,
+    sessionId: session,
+    revision: '',
+    events,
+    snapshots,
+  }
+  detail.revision = await detailRevision(detail)
+  return detail
+}
+
 const watchUrl = () => {
   const url = new URL('_a2/watch', document.baseURI)
   url.searchParams.set('contract', state.contract)
@@ -411,10 +498,7 @@ const loadSessions = async (reset) => {
 
 const loadDetail = async () => {
   if (!state.contract || !state.session) return
-  state.detail = await request('session', {
-    contract: state.contract,
-    session: state.session,
-  })
+  state.detail = await requestDetail(state.contract, state.session)
   state.error = null
   render()
 }
@@ -715,7 +799,7 @@ const renderMain = () => {
     return main
   }
   if (!state.detail) {
-    main.append(node('div', 'empty', 'Reading the durable log…'))
+    main.append(node('div', 'empty', 'Reading the durable store…'))
     return main
   }
 
@@ -825,7 +909,7 @@ if (bootstrap) {
 */
 const MARKER = "/_a2/";
 const encoder = new TextEncoder();
-const isProduction = () => typeof process !== "undefined" && process.env?.["NODE_ENV"] === "production";
+const isDevelopment = () => typeof process !== "undefined" && process.env?.["NODE_ENV"] === "development";
 const headers = (contentType) => ({
 	"content-type": contentType,
 	"cache-control": "no-store",
@@ -846,59 +930,91 @@ const notFound = () => new Response("Not found", {
 const badRequest = (message) => json({ error: message }, { status: 400 });
 const unavailable = (message) => json({ error: message }, { status: 501 });
 const wireSummary = (session) => ({
-	...session,
+	sessionId: session.sessionId,
+	eventCount: session.eventCount,
+	pendingCount: session.pendingCount,
+	failedCount: session.failedCount,
+	attemptCount: session.attemptCount,
+	failureCount: session.failureCount,
 	firstEventAt: session.firstEventAt.toISOString(),
 	updatedAt: session.updatedAt.toISOString()
 });
 const wireEvent = (event) => ({
-	...event,
+	id: event.id,
+	type: event.type,
+	payload: event.payload,
+	index: event.index,
+	sessionId: event.sessionId,
 	createdAt: event.createdAt.toISOString(),
+	cause: event.cause === null ? null : {
+		index: event.cause.index,
+		attempt: event.cause.attempt,
+		...event.cause.batchSize === void 0 ? {} : { batchSize: event.cause.batchSize }
+	},
+	lane: event.lane,
 	processedAt: event.processedAt?.toISOString() ?? null,
+	processedByAttempt: event.processedByAttempt,
+	returnedEventIds: event.returnedEventIds,
 	firstClaimedAt: event.firstClaimedAt?.toISOString() ?? null,
 	lastClaimedAt: event.lastClaimedAt?.toISOString() ?? null,
+	attemptCount: event.attemptCount,
+	claimHolder: event.claimHolder,
+	claimExpiresAt: event.claimExpiresAt?.toISOString() ?? null,
+	failureCount: event.failureCount,
 	lastFailedAt: event.lastFailedAt?.toISOString() ?? null,
+	lastFailedAttempt: event.lastFailedAttempt,
+	lastError: event.lastError,
 	failedAt: event.failedAt?.toISOString() ?? null
 });
 const wireSnapshot = (snapshot) => ({
-	...snapshot,
+	reducerName: snapshot.reducerName,
+	index: snapshot.index,
 	updatedAt: snapshot.updatedAt.getTime() === 0 ? null : snapshot.updatedAt.toISOString()
 });
 const sessionRevision = async (detail) => {
-	const serialized = JSON.stringify({
-		events: detail.events.map((event) => [
-			event.id,
-			event.index,
-			event.cause?.index ?? null,
-			event.cause?.attempt ?? null,
-			event.processedAt?.getTime() ?? null,
-			event.processedByAttempt,
-			event.firstClaimedAt?.getTime() ?? null,
-			event.lastClaimedAt?.getTime() ?? null,
-			event.attemptCount,
-			event.failureCount,
-			event.lastFailedAt?.getTime() ?? null,
-			event.lastFailedAttempt,
-			event.lastError,
-			event.failedAt?.getTime() ?? null
-		]),
-		snapshots: detail.snapshots.map((snapshot) => [
-			snapshot.reducerName,
-			snapshot.index,
-			snapshot.updatedAt.getTime()
-		])
+	return devtoolsSessionRevision({
+		events: detail.events.map(wireEvent),
+		snapshots: detail.snapshots.map(wireSnapshot)
 	});
-	const digest = await crypto.subtle.digest("SHA-256", encoder.encode(serialized));
-	return [...new Uint8Array(digest)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
 };
 const wireDetail = async (contract, sessionId, detail) => ({
+	protocolVersion: 1,
 	contract,
 	sessionId,
 	revision: await sessionRevision(detail),
 	events: detail.events.map(wireEvent),
 	snapshots: detail.snapshots.map(wireSnapshot)
 });
+const readCompleteSession = async (inspection, sessionId) => {
+	const events = [];
+	let snapshots = [];
+	let afterIndex = 0;
+	let throughIndex;
+	for (;;) {
+		const page = await inspection.readSessionPage(sessionId, {
+			afterIndex,
+			limit: 250,
+			...throughIndex === void 0 ? {} : { throughIndex }
+		});
+		if (throughIndex === void 0) {
+			throughIndex = page.throughIndex;
+			snapshots = page.snapshots;
+		} else if (page.throughIndex !== throughIndex) throw new Error("inspection session frontier changed between pages");
+		if (events.length + page.events.length > page.throughIndex) throw new Error("inspection session page crossed its frozen frontier");
+		events.push(...page.events);
+		if (page.nextIndex === null) break;
+		if (events.length === page.throughIndex) throw new Error("inspection session cursor continued past its frontier");
+		if (page.nextIndex <= afterIndex) throw new Error("inspection session cursor did not advance");
+		afterIndex = page.nextIndex;
+	}
+	if (throughIndex !== events.length) throw new Error("inspection session ended before its frozen frontier");
+	return {
+		events,
+		snapshots
+	};
+};
 const readRevision = async (inspection, sessionId) => {
-	const detail = await inspection.readSession(sessionId);
+	const detail = await readCompleteSession(inspection, sessionId);
 	return {
 		detail,
 		revision: await sessionRevision(detail)
@@ -930,7 +1046,7 @@ const bootstrapState = async (url, servers) => {
 		bootstrap.cursor = page.cursor;
 		bootstrap.session = (requestedContract === contract ? url.searchParams.get("session") : null) ?? page.sessions[0]?.sessionId ?? null;
 		if (!bootstrap.session) return bootstrap;
-		const detail = await inspection.readSession(bootstrap.session);
+		const detail = await readCompleteSession(inspection, bootstrap.session);
 		if (detail.events.length === 0) {
 			bootstrap.error = `session '${bootstrap.session}' was not found`;
 			return bootstrap;
@@ -951,6 +1067,30 @@ const inspectionOf = (servers, contractName) => {
 	if (!server) return notFound();
 	return serverInspection.get(server) ?? unavailable(`contract '${contractName}' is not an inspectable A2 server`);
 };
+const encodeSessionCursor = (contract, sessionId, cursor) => JSON.stringify([
+	1,
+	contract,
+	sessionId,
+	cursor.throughIndex,
+	cursor.afterIndex
+]);
+const parseSessionCursor = (value, contract, sessionId) => {
+	let decoded;
+	try {
+		decoded = JSON.parse(value);
+	} catch {
+		return badRequest("cursor is invalid");
+	}
+	if (!Array.isArray(decoded) || decoded.length !== 5 || decoded[0] !== 1 || !Number.isSafeInteger(decoded[3]) || !Number.isSafeInteger(decoded[4]) || decoded[3] < 1 || decoded[4] < 1 || decoded[4] >= decoded[3]) return badRequest("cursor is invalid");
+	if (decoded[1] !== contract || decoded[2] !== sessionId) return badRequest("cursor does not belong to this contract and session");
+	return {
+		throughIndex: decoded[3],
+		afterIndex: decoded[4]
+	};
+};
+const captureFilename = (contract, sessionId) => {
+	return `${`${contract}-${sessionId}`.replaceAll(/[^a-zA-Z0-9._-]/g, "_").slice(0, 160) || "a2-session"}.a2log`;
+};
 const watchResponse = (request, inspection, sessionId, initial) => {
 	let stopped = false;
 	let timeout = null;
@@ -1014,10 +1154,10 @@ const watchResponse = (request, inspection, sessionId, initial) => {
 	} });
 };
 const authorizeRequest = async (request, authorize) => {
-	if (!authorize) return isProduction() ? notFound() : null;
+	if (!authorize) return isDevelopment() ? null : notFound();
 	const result = await authorize(request);
 	if (result instanceof Response) return result;
-	return result ? null : notFound();
+	return result === true ? null : notFound();
 };
 function createDevtools(options) {
 	if (!options || !Array.isArray(options.servers) || options.servers.length === 0) throw new TypeError("createDevtools expects at least one A2 server");
@@ -1051,8 +1191,13 @@ function createDevtools(options) {
 			}
 			if (resource === "app.js") return new Response(DEVTOOLS_APP_JS, { headers: headers("text/javascript; charset=utf-8") });
 			if (resource === "app.css") return new Response(DEVTOOLS_APP_CSS, { headers: headers("text/css; charset=utf-8") });
-			if (resource === "contracts") return json({ contracts: [...servers.keys()].map((name) => ({ name })) });
-			const inspection = inspectionOf(servers, url.searchParams.get("contract"));
+			if (resource === "contracts") return json({
+				protocolVersion: 1,
+				contracts: [...servers.keys()].map((name) => ({ name }))
+			});
+			if (resource === "capabilities") return json(DEVTOOLS_CAPABILITIES);
+			const contractName = url.searchParams.get("contract");
+			const inspection = inspectionOf(servers, contractName);
 			if (inspection instanceof Response) return inspection;
 			try {
 				if (resource === "sessions") {
@@ -1065,18 +1210,54 @@ function createDevtools(options) {
 						...cursor !== null ? { cursor } : {}
 					});
 					return json({
+						protocolVersion: 1,
 						cursor: page.cursor,
 						sessions: page.sessions.map(wireSummary)
 					});
 				}
 				const sessionId = url.searchParams.get("session");
 				if (!sessionId) return badRequest("session is required");
-				const detail = await inspection.readSession(sessionId);
+				if (resource === "session" && (url.searchParams.has("limit") || url.searchParams.has("cursor"))) {
+					const requestedLimit = Number(url.searchParams.get("limit") ?? 250);
+					if (!Number.isSafeInteger(requestedLimit) || requestedLimit < 1) return badRequest("limit must be a positive integer");
+					const limit = Math.min(requestedLimit, DEVTOOLS_SESSION_PAGE_MAX_LIMIT);
+					const cursorValue = url.searchParams.get("cursor");
+					const cursor = cursorValue === null ? {
+						afterIndex: 0,
+						throughIndex: void 0
+					} : parseSessionCursor(cursorValue, contractName, sessionId);
+					if (cursor instanceof Response) return cursor;
+					const page = await inspection.readSessionPage(sessionId, {
+						afterIndex: cursor.afterIndex,
+						limit,
+						...cursor.throughIndex === void 0 ? {} : { throughIndex: cursor.throughIndex }
+					});
+					if (page.throughIndex === 0) return notFound();
+					const response = {
+						protocolVersion: 1,
+						contract: contractName,
+						sessionId,
+						throughIndex: page.throughIndex,
+						cursor: page.nextIndex === null ? null : encodeSessionCursor(contractName, sessionId, {
+							throughIndex: page.throughIndex,
+							afterIndex: page.nextIndex
+						}),
+						events: page.events.map(wireEvent),
+						snapshots: page.snapshots.map(wireSnapshot)
+					};
+					return json(response);
+				}
+				const detail = await readCompleteSession(inspection, sessionId);
 				if (detail.events.length === 0) return notFound();
-				if (resource === "session") return json(await wireDetail(url.searchParams.get("contract"), sessionId, detail));
+				const wired = await wireDetail(contractName, sessionId, detail);
+				if (resource === "session") return json(wired);
+				if (resource === "export") return new Response(await encodeDevtoolsCapture(wired), { headers: {
+					...headers(`${DEVTOOLS_CAPTURE_MEDIA_TYPE}; charset=utf-8`),
+					"content-disposition": `attachment; filename="${captureFilename(wired.contract, sessionId)}"`
+				} });
 				if (resource === "watch") return watchResponse(request, inspection, sessionId, detail);
 			} catch (error) {
-				if (error instanceof TypeError && error.message.includes("does not support inspection")) return unavailable(error.message);
+				if (error instanceof InspectionUnsupportedError) return unavailable(error.message);
 				throw error;
 			}
 			return notFound();

package/dist/devtools.d.ts

@@ -0,0 +1,2 @@
+import { C as parseDevtoolsCapture, S as encodeDevtoolsCapture, _ as DevtoolsSessionsResponse, a as DEVTOOLS_SESSION_PAGE_LIMIT, b as DevtoolsWireSnapshot, c as DevtoolsCapture, d as DevtoolsCaptureManifest, f as DevtoolsCaptureRecord, g as DevtoolsSessionPage, h as DevtoolsSessionDetail, i as DEVTOOLS_PROTOCOL_VERSION, l as DevtoolsCaptureEvent, m as DevtoolsContractsResponse, n as DEVTOOLS_CAPTURE_MEDIA_TYPE, o as DEVTOOLS_SESSION_PAGE_MAX_LIMIT, p as DevtoolsCaptureSnapshot, r as DEVTOOLS_CAPTURE_VERSION, s as DevtoolsCapabilities, t as DEVTOOLS_CAPABILITIES, u as DevtoolsCaptureFooter, v as DevtoolsWireEvent, w as verifyDevtoolsCapture, x as devtoolsSessionRevision, y as DevtoolsWireSessionSummary } from "./devtools-J_jZ2vQf.js";
+export { DEVTOOLS_CAPABILITIES, DEVTOOLS_CAPTURE_MEDIA_TYPE, DEVTOOLS_CAPTURE_VERSION, DEVTOOLS_PROTOCOL_VERSION, DEVTOOLS_SESSION_PAGE_LIMIT, DEVTOOLS_SESSION_PAGE_MAX_LIMIT, DevtoolsCapabilities, DevtoolsCapture, DevtoolsCaptureEvent, DevtoolsCaptureFooter, DevtoolsCaptureManifest, DevtoolsCaptureRecord, DevtoolsCaptureSnapshot, DevtoolsContractsResponse, DevtoolsSessionDetail, DevtoolsSessionPage, DevtoolsSessionsResponse, DevtoolsWireEvent, DevtoolsWireSessionSummary, DevtoolsWireSnapshot, devtoolsSessionRevision, encodeDevtoolsCapture, parseDevtoolsCapture, verifyDevtoolsCapture };

package/dist/devtools.js

@@ -0,0 +1,2 @@
+import { a as DEVTOOLS_SESSION_PAGE_LIMIT, c as encodeDevtoolsCapture, i as DEVTOOLS_PROTOCOL_VERSION, l as parseDevtoolsCapture, n as DEVTOOLS_CAPTURE_MEDIA_TYPE, o as DEVTOOLS_SESSION_PAGE_MAX_LIMIT, r as DEVTOOLS_CAPTURE_VERSION, s as devtoolsSessionRevision, t as DEVTOOLS_CAPABILITIES, u as verifyDevtoolsCapture } from "./devtools-kJJaORn-.js";
+export { DEVTOOLS_CAPABILITIES, DEVTOOLS_CAPTURE_MEDIA_TYPE, DEVTOOLS_CAPTURE_VERSION, DEVTOOLS_PROTOCOL_VERSION, DEVTOOLS_SESSION_PAGE_LIMIT, DEVTOOLS_SESSION_PAGE_MAX_LIMIT, devtoolsSessionRevision, encodeDevtoolsCapture, parseDevtoolsCapture, verifyDevtoolsCapture };

package/dist/{errors-BJRMd-h6.js → errors-BQuJpe82.js}

@@ -11,13 +11,13 @@ var A2Error = class extends Error {
 	}
 };
 /**
-* Wrap an arbitrary thrown value as LOG_UNAVAILABLE, preserving the
+* Wrap an arbitrary thrown value as STORE_UNAVAILABLE, preserving the
 * original as `cause`. A2Errors pass through untouched — they already
 * carry their own meaning.
 */
-function asLogUnavailable(err) {
+function asStoreUnavailable(err) {
 	if (err instanceof A2Error) return err;
-	return new A2Error("LOG_UNAVAILABLE", "the log backend failed", { cause: err });
+	return new A2Error("STORE_UNAVAILABLE", "the store backend failed", { cause: err });
 }
 //#endregion
-export { asLogUnavailable as n, A2Error as t };
+export { asStoreUnavailable as n, A2Error as t };

package/dist/{errors-xL_JTXsY.d.ts → errors-W6nwJ-fm.d.ts}

@@ -6,7 +6,7 @@
  * A single class serializes cleanly across the push-route boundary and
  * keeps `instanceof` checks working after bundling.
  */
-type A2ErrorCode = "INVALID_PAYLOAD" | "UNKNOWN_EVENT_TYPE" | "PARTIAL_DUPLICATE_BATCH" | "LOG_UNAVAILABLE" | "LOG_NOT_CONFIGURED";
+type A2ErrorCode = "INVALID_PAYLOAD" | "UNKNOWN_EVENT_TYPE" | "PARTIAL_DUPLICATE_BATCH" | "SUPERSEDED_ATTEMPT" | "CLAIM_EXPIRED" | "STORE_UNAVAILABLE" | "STORE_NOT_CONFIGURED" | "UNKNOWN_PRESENCE_FIELD" | "PRESENCE_NOT_SUPPORTED";
 declare class A2Error extends Error {
   readonly code: A2ErrorCode;
   /** e.g. the Standard Schema issues for INVALID_PAYLOAD */

package/dist/http.d.ts

@@ -1,36 +1,55 @@
-import { a as Event } from "./log-ldf5g8Cx.js";
-import { PushedEvent } from "./server.js";
-import { t as A2Error } from "./errors-xL_JTXsY.js";
+import { a as EventDefs, c as PresencePatch, l as PresenceSnapshot } from "./contract-jIfaR085.js";
+import { a as Event } from "./store-C3sNAaBT.js";
+import { _ as Session, f as PushedEvent, i as DrainableServer, p as PushedPresence } from "./server-YtPq7hjw.js";
+import { t as A2Error } from "./errors-W6nwJ-fm.js";
 //#region src/http.d.ts
+/**
+ * Create one scheduler callback route for servers sharing the same configured
+ * scheduler. Configuration mistakes throw immediately while the route module
+ * is evaluated, before a delivery can be acknowledged by the wrong adapter.
+ */
+declare function schedulerHandler(firstServer: DrainableServer, ...servers: DrainableServer[]): (req: Request) => Promise<Response>;
 /** The push envelope: what a client POSTs to append events. */
 type PushBody = {
   sessionId: string;
   /** Branded: `session.append` accepts these directly (the push route
-   * path); schema validation still happens inside `append`. */
+   * path); schema validation still happens inside `append`. Empty only
+   * for a presence-only push. */
   events: PushedEvent[];
+  /** Branded like `events`: `session.setPresence` accepts it whole;
+   * field validation still happens inside `setPresence`. */
+  presence?: PushedPresence;
 };
 /**
- * Validate the push envelope — `{ sessionId, events }` — throwing
- * `INVALID_PAYLOAD` on a malformed body. Payload validation against the
- * machine's schemas happens in `append`, not here.
+ * Validate the push envelope — `{ sessionId, events, presence? }` —
+ * throwing `INVALID_PAYLOAD` on a malformed body. Payload validation
+ * against the machine's schemas happens in `append` and `setPresence`,
+ * not here. Either plane may appear alone: a presence-only push has no
+ * (or empty) `events`.
  */
 declare function parsePushBody(req: Request): Promise<PushBody>;
 /**
  * Pipe a live event iterable into an SSE `Response`. Each event is one
- * frame — `id:` carries the log index, `data:` the JSON event. A
+ * frame — `id:` carries the event-log index, `data:` the JSON event. A
+ * `stream({ presence: true })` iterable also yields presence items,
+ * which ride as named frames old clients skip: `event:
+ * presence-snapshot` first (the map, ISO dates), then `event: presence`
+ * per patch — no `id:`, presence never advances the resume frontier. A
  * disconnecting client cancels the stream, which closes the underlying
  * subscription. Two kinds of comment frames ride along: a `: connected`
  * prelude that flushes headers immediately, and a `: ping` heartbeat
  * every 15 seconds so clients (and proxies) can tell a quiet stream
  * from a dead connection — the session client's stall watchdog counts
- * on it.
+ * on it. When the platform exposes an invocation deadline, the response
+ * closes cleanly one second before it so the client reconnects without
+ * a platform-timeout failure.
  */
-declare function sseResponse(iterable: AsyncIterable<Event>): Response;
+declare function sseResponse(iterable: AsyncIterable<Event | PresencePatch | PresenceSnapshot>): Response;
 /**
  * Serialize an error into the documented wire shape,
  * `{ error: { code, message, details } }`, with the mapped status
- * (400 for caller bugs, 503 for LOG_UNAVAILABLE). Non-A2Errors become a
- * 503 LOG_UNAVAILABLE — from the client's perspective an unknown server
+ * (400 for caller bugs, 503 for STORE_UNAVAILABLE). Non-A2Errors become a
+ * 503 STORE_UNAVAILABLE — from the client's perspective an unknown server
  * failure is retryable-once, not a protocol contract.
  */
 declare function errorResponse(error: unknown): Response;
@@ -40,5 +59,44 @@ declare function errorResponse(error: unknown): Response;
  * sides branch on identical codes.
  */
 declare function deserializeError(body: unknown): A2Error | null;
+/**
+ * The structural socket `sessionSocket` speaks against — satisfied by
+ * `ws` and by `@vercel/functions`' upgraded socket alike, so the
+ * platform upgrade API stays out of the library. `message` data
+ * arrives as whatever the platform delivers (string, Buffer,
+ * ArrayBuffer, or fragments); `sessionSocket` normalizes defensively.
+ */
+type A2Socket = {
+  send(data: string): void;
+  on(event: "message", listener: (data: unknown) => void): void;
+  on(event: "close", listener: () => void): void;
+  on(event: "error", listener: (error: unknown) => void): void;
+  close(code?: number, reason?: string): void;
+  /** Bytes queued but not yet transmitted — when exposed, the down
+   * pump uses it for backpressure (`SOCKET_TIMINGS`). */
+  bufferedAmount?: number;
+};
+type SessionSocketOptions = {
+  /** The resume frontier, from the upgrade URL's query — the same
+   * parameter the SSE GET reads. */
+  startAfter?: number;
+  /** The `stream()` presence opt-in — the server decides, same rule as
+   * the SSE route. */
+  presence?: boolean;
+  /** Epoch ms: close cleanly (code 1000) at this time, ahead of a known
+   * platform deadline, so clients reconnect on our schedule. */
+  deadline?: number;
+};
+/**
+ * Speak the A2 socket protocol (specs/a2-api.md §13) against one
+ * session: the live stream pumps down as `kind`-framed JSON with a
+ * `ping` heartbeat on the SSE cadence; `push` frames come up through
+ * the same validation seams as `parsePushBody` (same provenance brand,
+ * same `validatePush` calls, once per plane) and are answered with an
+ * ack; `presence` frames are fire-and-forget. Socket close or error
+ * tears the pump down and releases the store subscription; the stream
+ * ending closes the socket.
+ */
+declare function sessionSocket<D extends EventDefs>(session: Session<D>, socket: A2Socket, options?: SessionSocketOptions): void;
 //#endregion
-export { PushBody, deserializeError, errorResponse, parsePushBody, sseResponse };
+export { A2Socket, PushBody, SessionSocketOptions, deserializeError, errorResponse, parsePushBody, schedulerHandler, sessionSocket, sseResponse };