@gscdump/sdk 1.4.0 → 1.4.2

package/dist/v1/realtime.mjs

@@ -0,0 +1,1012 @@
+import { utf8Size } from "../utf8.mjs";
+import { GSCDUMP_REALTIME_ACK_POLICY, GSCDUMP_REALTIME_CLOSE_CODES, GSCDUMP_REALTIME_CONNECTION_POLICY, GSCDUMP_REALTIME_LIMITS, GSCDUMP_REALTIME_PING, GSCDUMP_REALTIME_PONG, GSCDUMP_REALTIME_PROTOCOL_VERSION, GSCDUMP_REALTIME_SUBPROTOCOL, REALTIME_V1_EVENT_NAMES, REALTIME_V1_RESOURCE_TYPES, createRealtimeV1Schemas } from "@gscdump/contracts/v1/realtime";
+const GSCDUMP_REALTIME_V1_SDK_VERSION = "1.4.2";
+var GscdumpRealtimeV1Error = class extends Error {
+	tag = "GscdumpRealtimeV1Error";
+	code;
+	retryable;
+	terminal;
+	details;
+	cause;
+	constructor(options) {
+		super(options.message);
+		this.name = "GscdumpRealtimeV1Error";
+		this.code = options.code;
+		this.retryable = options.retryable;
+		this.terminal = options.terminal;
+		this.details = options.details ?? {};
+		this.cause = options.cause;
+	}
+};
+var StaleEpochError = class extends Error {
+	constructor() {
+		super("The realtime connection epoch is no longer active.");
+		this.name = "StaleEpochError";
+	}
+};
+function createMemoryCursorStore() {
+	let value = null;
+	return {
+		load: () => value,
+		save: (cursor) => {
+			value = { ...cursor };
+		}
+	};
+}
+function defaultRuntime() {
+	return {
+		createSocket(url, protocols) {
+			if (typeof globalThis.WebSocket !== "function") throw new GscdumpRealtimeV1Error({
+				code: "runtime_unavailable",
+				message: "This runtime does not provide WebSocket; inject a realtime runtime port.",
+				retryable: false,
+				terminal: true
+			});
+			return new globalThis.WebSocket(url, [...protocols]);
+		},
+		setTimeout: (handler, ms) => globalThis.setTimeout(handler, ms),
+		clearTimeout: (handle) => globalThis.clearTimeout(handle),
+		random: () => Math.random(),
+		now: () => Date.now()
+	};
+}
+const UTF8_DECODER = new TextDecoder();
+const REALTIME_EVENT_NAMES = new Set(REALTIME_V1_EVENT_NAMES);
+const REALTIME_RESOURCE_TYPES = new Set(REALTIME_V1_RESOURCE_TYPES);
+const APPLIED_EVENT_CACHE_MAX = 1e4;
+async function messageText(raw) {
+	if (typeof raw === "string") return raw;
+	if (raw instanceof ArrayBuffer) return UTF8_DECODER.decode(raw);
+	if (ArrayBuffer.isView(raw)) return UTF8_DECODER.decode(new Uint8Array(raw.buffer, raw.byteOffset, raw.byteLength));
+	if (typeof Blob !== "undefined" && raw instanceof Blob) return raw.text();
+	throw new TypeError("Realtime frames must be text or UTF-8 binary data.");
+}
+function compareSequence(left, right) {
+	const a = BigInt(left);
+	const b = BigInt(right);
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+function nextSequence(sequence) {
+	return (BigInt(sequence) + 1n).toString();
+}
+function laterCursor(left, right) {
+	return compareSequence(left.sequence, right.sequence) >= 0 ? left : right;
+}
+function sameCursor(left, right) {
+	return left?.streamId === right?.streamId && left?.sequence === right?.sequence;
+}
+function parseErrorDetails(cause) {
+	if (typeof cause === "object" && cause !== null && "issues" in cause) return { issues: cause.issues };
+	return {};
+}
+function safeRandom(random) {
+	const value = random();
+	return Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : .5;
+}
+function createGscdumpRealtimeV1Client(options) {
+	const schemas = createRealtimeV1Schemas();
+	const runtime = options.runtime ?? defaultRuntime();
+	const cursorStore = options.cursorStore ?? createMemoryCursorStore();
+	const sdkVersion = options.sdkVersion ?? "1.4.2";
+	if (!sdkVersion) throw new TypeError("sdkVersion cannot be empty.");
+	let running = false;
+	let epoch = 0;
+	let reconnectTimer;
+	let heartbeatTimer;
+	let rotationTimer;
+	let current = null;
+	let immediateExpiredTicketRetry = true;
+	let cursor = null;
+	let streamId = null;
+	let head = null;
+	let attempt = 0;
+	let transport = "idle";
+	let freshness = "unknown";
+	let lastError = null;
+	const eventFailures = /* @__PURE__ */ new Map();
+	const appliedEventIds = /* @__PURE__ */ new Set();
+	const appliedEventOrder = [];
+	let appliedEventCursor = 0;
+	function getSnapshot() {
+		return {
+			transport,
+			freshness,
+			attempt,
+			streamId,
+			cursor: cursor ? { ...cursor } : null,
+			head: head ? { ...head } : null,
+			error: lastError
+		};
+	}
+	function observe(observation) {
+		if (!options.onObservation) return;
+		try {
+			Promise.resolve(options.onObservation(observation)).catch(() => {});
+		} catch {}
+	}
+	function emitState() {
+		observe({
+			type: "state",
+			state: getSnapshot()
+		});
+	}
+	function setState(nextTransport, nextFreshness = freshness) {
+		transport = nextTransport;
+		freshness = nextFreshness;
+		emitState();
+	}
+	function reportError(error) {
+		lastError = error;
+		observe({
+			type: "error",
+			error,
+			state: getSnapshot()
+		});
+		emitState();
+	}
+	function clearTimer(handle) {
+		if (handle !== void 0) runtime.clearTimeout(handle);
+	}
+	function clearConnectionTimers() {
+		clearTimer(heartbeatTimer);
+		clearTimer(rotationTimer);
+		heartbeatTimer = void 0;
+		rotationTimer = void 0;
+	}
+	function ensureEpoch(context) {
+		if (!running || current !== context || context.closed || context.epoch !== epoch) throw new StaleEpochError();
+	}
+	function closeSocket(context, code, reason) {
+		if (context.closed) return;
+		context.closed = true;
+		if (current === context) {
+			current = null;
+			epoch++;
+		}
+		clearConnectionTimers();
+		try {
+			context.socket.close(code, reason);
+		} catch {}
+	}
+	function reconnectBackoff() {
+		const exponent = Math.max(0, attempt - 1);
+		const cap = Math.min(GSCDUMP_REALTIME_CONNECTION_POLICY.reconnectMaxDelayMs, GSCDUMP_REALTIME_CONNECTION_POLICY.reconnectBaseDelayMs * 2 ** exponent);
+		return cap / 2 + safeRandom(runtime.random) * cap / 2;
+	}
+	function scheduleReconnect(context, reason, minimumDelayMs = 0, immediate = false) {
+		if (!running) return;
+		if (context) closeSocket(context, GSCDUMP_REALTIME_CLOSE_CODES.internalError, reason);
+		clearTimer(reconnectTimer);
+		attempt++;
+		const delay = immediate ? minimumDelayMs : Math.max(minimumDelayMs, reconnectBackoff());
+		setState("waiting", freshness === "unknown" || freshness === "degraded" ? freshness : "stale");
+		reconnectTimer = runtime.setTimeout(() => {
+			reconnectTimer = void 0;
+			beginAttempt();
+		}, delay);
+	}
+	function terminal(error, context = current) {
+		running = false;
+		clearTimer(reconnectTimer);
+		reconnectTimer = void 0;
+		if (context) closeSocket(context, GSCDUMP_REALTIME_CLOSE_CODES.normal, "terminal");
+		freshness = "degraded";
+		transport = "terminal";
+		reportError(error);
+	}
+	function assertStream(value, context, label) {
+		if (value.streamId !== context.ticket.head.streamId) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: `${label} did not match the ticket's exact stream.`,
+			retryable: false,
+			terminal: true,
+			details: {
+				expected: context.ticket.head.streamId,
+				received: value.streamId
+			}
+		});
+	}
+	function sendJson(context, value) {
+		ensureEpoch(context);
+		const serialized = JSON.stringify(value);
+		if (utf8Size(serialized) > GSCDUMP_REALTIME_LIMITS.clientFrameMaxBytes) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "The generated client frame exceeded the v1 size limit.",
+			retryable: false,
+			terminal: true
+		});
+		try {
+			context.socket.send(serialized);
+		} catch (cause) {
+			throw new GscdumpRealtimeV1Error({
+				code: "socket_error",
+				message: "Could not send a realtime client frame.",
+				retryable: true,
+				terminal: false,
+				cause
+			});
+		}
+	}
+	function sendAck(context, appliedCursor) {
+		sendJson(context, schemas.ackFrame.parse({
+			type: "ack",
+			cursor: appliedCursor
+		}));
+	}
+	function eventDedupeKey(stream, id) {
+		return `${stream}:${id}`;
+	}
+	function rememberEvent(stream, id) {
+		const key = eventDedupeKey(stream, id);
+		if (appliedEventIds.has(key)) return;
+		appliedEventIds.add(key);
+		if (appliedEventOrder.length < APPLIED_EVENT_CACHE_MAX) appliedEventOrder.push(key);
+		else {
+			const oldest = appliedEventOrder[appliedEventCursor];
+			if (oldest) appliedEventIds.delete(oldest);
+			appliedEventOrder[appliedEventCursor] = key;
+			appliedEventCursor = (appliedEventCursor + 1) % APPLIED_EVENT_CACHE_MAX;
+		}
+	}
+	function eventFailureKey(event) {
+		return `${event.cursor?.streamId ?? "ephemeral"}:${event.id}:${event.cursor?.sequence ?? "ephemeral"}`;
+	}
+	function eventForRequiredEffect(event) {
+		return REALTIME_EVENT_NAMES.has(event.name) && event.eventVersion === 1 ? event : {
+			...event,
+			data: null
+		};
+	}
+	function eventAdvisories(event) {
+		if (!REALTIME_EVENT_NAMES.has(event.name)) observe({
+			type: "advisory",
+			code: "unknown_event",
+			event
+		});
+		else if (event.eventVersion !== 1) observe({
+			type: "advisory",
+			code: "unsupported_event_version",
+			event
+		});
+		if (event.changes.some((change) => !REALTIME_RESOURCE_TYPES.has(change.type))) observe({
+			type: "advisory",
+			code: "unknown_resource",
+			event
+		});
+	}
+	async function saveCursor(context, nextCursor) {
+		ensureEpoch(context);
+		await cursorStore.save(nextCursor);
+		ensureEpoch(context);
+	}
+	async function performResync(context, request) {
+		ensureEpoch(context);
+		setState("handshaking", "resyncing");
+		try {
+			await options.resync(request);
+			ensureEpoch(context);
+		} catch (cause) {
+			if (cause instanceof StaleEpochError || !running || current !== context || context.closed) return;
+			terminal(new GscdumpRealtimeV1Error({
+				code: "resync_failed",
+				message: `Realtime resync failed (${request.reason}).`,
+				retryable: false,
+				terminal: true,
+				details: {
+					reason: request.reason,
+					resumeAfter: request.resumeAfter
+				},
+				cause
+			}), context);
+			return;
+		}
+		try {
+			await saveCursor(context, request.resumeAfter);
+		} catch (cause) {
+			if (cause instanceof StaleEpochError || !running || current !== context || context.closed) return;
+			terminal(new GscdumpRealtimeV1Error({
+				code: "cursor_store_failed",
+				message: "Realtime resync completed, but its resume cursor could not be persisted.",
+				retryable: false,
+				terminal: true,
+				details: { resumeAfter: request.resumeAfter },
+				cause
+			}), context);
+			return;
+		}
+		cursor = { ...request.resumeAfter };
+		eventFailures.clear();
+		emitState();
+		scheduleReconnect(context, "resync-complete", 0, true);
+	}
+	async function handleEventFailure(context, event, code, cause) {
+		if (cause instanceof StaleEpochError) return;
+		ensureEpoch(context);
+		const key = eventFailureKey(event);
+		const failures = (eventFailures.get(key) ?? 0) + 1;
+		eventFailures.set(key, failures);
+		const error = new GscdumpRealtimeV1Error({
+			code,
+			message: code === "effect_failed" ? `The required effect rejected for durable event ${event.id}.` : `The cursor store rejected durable event ${event.id}.`,
+			retryable: failures < GSCDUMP_REALTIME_ACK_POLICY.effectRetryBeforeUnsafeResync,
+			terminal: false,
+			details: {
+				eventId: event.id,
+				sequence: event.cursor?.sequence,
+				failures
+			},
+			cause
+		});
+		freshness = "degraded";
+		reportError(error);
+		if (failures < GSCDUMP_REALTIME_ACK_POLICY.effectRetryBeforeUnsafeResync) {
+			scheduleReconnect(context, code);
+			return;
+		}
+		const eventCursor = event.cursor;
+		if (!eventCursor) return;
+		const resumeAfter = context.head ? laterCursor(context.head, eventCursor) : eventCursor;
+		await performResync(context, {
+			reason: "effect_application_failed",
+			source: "client",
+			streamId: eventCursor.streamId,
+			previousCursor: cursor,
+			resumeAfter,
+			failedEvent: event,
+			cause
+		});
+	}
+	async function applyDurableEvent(context, event) {
+		ensureEpoch(context);
+		assertStream(event.cursor, context, "event cursor");
+		if (context.replayThrough && compareSequence(event.cursor.sequence, context.replayThrough.sequence) > 0) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "A live event arrived before the declared replay completed.",
+			retryable: false,
+			terminal: true
+		});
+		if (!context.replaying && (!context.head || compareSequence(event.cursor.sequence, context.head.sequence) > 0)) {
+			context.head = { ...event.cursor };
+			head = { ...event.cursor };
+		}
+		if (!cursor) {
+			await performResync(context, {
+				reason: "initial_cursor_missing",
+				source: "client",
+				streamId: event.cursor.streamId,
+				previousCursor: null,
+				resumeAfter: context.head ? laterCursor(context.head, event.cursor) : event.cursor
+			});
+			return;
+		}
+		assertStream(cursor, context, "stored cursor");
+		if (compareSequence(event.cursor.sequence, cursor.sequence) <= 0) {
+			sendAck(context, cursor);
+			return;
+		}
+		if (event.cursor.sequence !== nextSequence(cursor.sequence)) {
+			const resumeAfter = context.head ? laterCursor(context.head, event.cursor) : event.cursor;
+			await performResync(context, {
+				reason: "sequence_gap",
+				source: "client",
+				streamId: event.cursor.streamId,
+				previousCursor: cursor,
+				resumeAfter
+			});
+			return;
+		}
+		setState(context.replaying ? "replaying" : "live", "applying");
+		const effectEvent = eventForRequiredEffect(event);
+		if (!appliedEventIds.has(eventDedupeKey(event.cursor.streamId, event.id))) try {
+			await options.applyEvent(effectEvent);
+			ensureEpoch(context);
+		} catch (cause) {
+			await handleEventFailure(context, event, "effect_failed", cause);
+			return;
+		}
+		try {
+			await saveCursor(context, event.cursor);
+		} catch (cause) {
+			await handleEventFailure(context, event, "cursor_store_failed", cause);
+			return;
+		}
+		cursor = { ...event.cursor };
+		rememberEvent(event.cursor.streamId, event.id);
+		eventFailures.delete(eventFailureKey(event));
+		sendAck(context, cursor);
+		freshness = context.replaying ? "stale" : "fresh";
+		transport = context.replaying ? "replaying" : "live";
+		emitState();
+		eventAdvisories(effectEvent);
+		observe({
+			type: "event",
+			event: effectEvent,
+			cursor: { ...cursor }
+		});
+	}
+	function scheduleHeartbeat(context) {
+		clearTimer(heartbeatTimer);
+		heartbeatTimer = runtime.setTimeout(() => {
+			heartbeatTimer = void 0;
+			if (!running || current !== context || context.closed) return;
+			const staleFor = runtime.now() - context.lastPongAt;
+			if (staleFor >= GSCDUMP_REALTIME_CONNECTION_POLICY.staleAfterMs) {
+				const error = new GscdumpRealtimeV1Error({
+					code: "heartbeat_stale",
+					message: "Realtime heartbeat became stale.",
+					retryable: true,
+					terminal: false,
+					details: { staleFor }
+				});
+				freshness = "stale";
+				reportError(error);
+				scheduleReconnect(context, "heartbeat-stale");
+				return;
+			}
+			try {
+				context.socket.send(GSCDUMP_REALTIME_PING);
+			} catch (cause) {
+				reportError(new GscdumpRealtimeV1Error({
+					code: "socket_error",
+					message: "Could not send the realtime heartbeat.",
+					retryable: true,
+					terminal: false,
+					cause
+				}));
+				scheduleReconnect(context, "heartbeat-send");
+				return;
+			}
+			scheduleHeartbeat(context);
+		}, GSCDUMP_REALTIME_CONNECTION_POLICY.heartbeatIntervalMs);
+	}
+	function scheduleRotation(context, expiresAt) {
+		clearTimer(rotationTimer);
+		const delay = Math.max(0, Date.parse(expiresAt) - runtime.now() - GSCDUMP_REALTIME_CONNECTION_POLICY.connectionRefreshBeforeExpiryMs);
+		rotationTimer = runtime.setTimeout(() => {
+			rotationTimer = void 0;
+			if (running && current === context && !context.closed) scheduleReconnect(context, "connection-expiry-rotation", 0, true);
+		}, delay);
+	}
+	async function handleReady(context, frame) {
+		ensureEpoch(context);
+		if (context.ready) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "The server sent more than one ready frame.",
+			retryable: false,
+			terminal: true
+		});
+		assertStream(frame, context, "ready frame");
+		assertStream(frame.head, context, "ready head");
+		assertStream(frame.replayFloor, context, "ready replay floor");
+		if (compareSequence(frame.head.sequence, context.ticket.head.sequence) < 0) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "The ready head regressed behind the ticket head.",
+			retryable: false,
+			terminal: true,
+			details: {
+				ticketHead: context.ticket.head,
+				readyHead: frame.head
+			}
+		});
+		const expiresAt = Date.parse(frame.expiresAt);
+		if (!Number.isFinite(expiresAt) || expiresAt <= runtime.now() || expiresAt - runtime.now() > context.ticket.maxConnectionSeconds * 1e3) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "The ready frame carried an invalid signed connection expiry.",
+			retryable: false,
+			terminal: true,
+			details: { expiresAt: frame.expiresAt }
+		});
+		context.ready = true;
+		context.head = { ...frame.head };
+		context.lastPongAt = runtime.now();
+		head = { ...frame.head };
+		streamId = frame.streamId;
+		attempt = 0;
+		lastError = null;
+		scheduleHeartbeat(context);
+		scheduleRotation(context, frame.expiresAt);
+		if (!cursor) {
+			await performResync(context, {
+				reason: "initial_cursor_missing",
+				source: "client",
+				streamId: frame.streamId,
+				previousCursor: null,
+				resumeAfter: frame.head
+			});
+			return;
+		}
+		if (cursor.streamId !== frame.streamId) {
+			await performResync(context, {
+				reason: "stream_mismatch",
+				source: "client",
+				streamId: frame.streamId,
+				previousCursor: cursor,
+				resumeAfter: frame.head
+			});
+			return;
+		}
+		if (compareSequence(cursor.sequence, frame.head.sequence) > 0) {
+			await performResync(context, {
+				reason: "sequence_gap",
+				source: "client",
+				streamId: frame.streamId,
+				previousCursor: cursor,
+				resumeAfter: frame.head
+			});
+			return;
+		}
+		if (compareSequence(cursor.sequence, frame.replayFloor.sequence) < 0) {
+			await performResync(context, {
+				reason: "cursor_expired",
+				source: "client",
+				streamId: frame.streamId,
+				previousCursor: cursor,
+				resumeAfter: frame.head
+			});
+			return;
+		}
+		if (sameCursor(cursor, frame.head)) {
+			context.replaying = false;
+			setState("live", "fresh");
+		} else {
+			context.replaying = true;
+			setState("replaying", "stale");
+		}
+	}
+	async function processFrame(context, frame) {
+		ensureEpoch(context);
+		if (frame.type === "ready") {
+			await handleReady(context, frame);
+			return;
+		}
+		if (frame.type === "error") {
+			const retryable = !(frame.error.code === "invalid_frame" || frame.error.code === "protocol_mismatch" || frame.error.code === "policy_violation") && frame.error.retryable;
+			const error = new GscdumpRealtimeV1Error({
+				code: frame.error.code === "internal_error" || frame.error.code === "overloaded" ? "socket_error" : "protocol_error",
+				message: frame.error.message,
+				retryable,
+				terminal: !retryable,
+				details: {
+					serverCode: frame.error.code,
+					retryAfter: frame.error.retryAfter
+				}
+			});
+			reportError(error);
+			if (retryable) {
+				context.retryAfterMs = frame.error.retryAfter === void 0 ? void 0 : frame.error.retryAfter * 1e3;
+				scheduleReconnect(context, "server-error", context.retryAfterMs);
+			} else terminal(error, context);
+			return;
+		}
+		if (!context.ready) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: `The server sent ${frame.type} before ready.`,
+			retryable: false,
+			terminal: true
+		});
+		if (frame.type === "replay.begin") {
+			assertStream(frame.through, context, "replay through cursor");
+			if (frame.after) assertStream(frame.after, context, "replay after cursor");
+			if (context.replayThrough) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "The server sent a nested replay.begin frame.",
+				retryable: false,
+				terminal: true
+			});
+			if (!sameCursor(frame.after, cursor)) {
+				await performResync(context, {
+					reason: "sequence_gap",
+					source: "client",
+					streamId: context.ticket.head.streamId,
+					previousCursor: cursor,
+					resumeAfter: frame.through
+				});
+				return;
+			}
+			if (!context.head || !sameCursor(frame.through, context.head)) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "The replay boundary did not match the ready head.",
+				retryable: false,
+				terminal: true
+			});
+			context.replaying = true;
+			context.replayThrough = { ...frame.through };
+			setState("replaying", "stale");
+			return;
+		}
+		if (frame.type === "replay.end") {
+			assertStream(frame.through, context, "replay end cursor");
+			if (!context.replaying || !context.replayThrough || !sameCursor(context.replayThrough, frame.through) || !sameCursor(cursor, frame.through)) {
+				await performResync(context, {
+					reason: "sequence_gap",
+					source: "client",
+					streamId: frame.through.streamId,
+					previousCursor: cursor,
+					resumeAfter: context.head ? laterCursor(context.head, frame.through) : frame.through
+				});
+				return;
+			}
+			context.replaying = false;
+			context.replayThrough = null;
+			setState("live", "fresh");
+			return;
+		}
+		if (frame.type === "resync.required") {
+			assertStream(frame.scope, context, "resync scope");
+			assertStream(frame.resumeAfter, context, "resync cursor");
+			const minimumSequence = context.head && cursor ? laterCursor(context.head, cursor).sequence : context.head?.sequence ?? cursor?.sequence;
+			if (minimumSequence !== void 0 && compareSequence(frame.resumeAfter.sequence, minimumSequence) < 0) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "The resync cursor regressed behind observed stream state.",
+				retryable: false,
+				terminal: true,
+				details: {
+					minimumSequence,
+					resumeAfter: frame.resumeAfter
+				}
+			});
+			await performResync(context, {
+				reason: frame.reason,
+				source: "server",
+				streamId: frame.scope.streamId,
+				previousCursor: cursor,
+				resumeAfter: frame.resumeAfter
+			});
+			return;
+		}
+		if (frame.type === "batch") {
+			if (context.replaying && !context.replayThrough) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "A replay batch arrived before replay.begin.",
+				retryable: false,
+				terminal: true
+			});
+			for (const event of frame.events) {
+				ensureEpoch(context);
+				await applyDurableEvent(context, event);
+			}
+			return;
+		}
+		if (frame.type === "event") {
+			if (frame.delivery === "ephemeral") {
+				const observedEvent = eventForRequiredEffect(frame);
+				eventAdvisories(observedEvent);
+				observe({
+					type: "event",
+					event: observedEvent,
+					cursor: cursor ? { ...cursor } : null
+				});
+				return;
+			}
+			if (context.replaying && !context.replayThrough) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "A durable replay event arrived before replay.begin.",
+				retryable: false,
+				terminal: true
+			});
+			await applyDurableEvent(context, frame);
+		}
+	}
+	async function processRawMessage(context, raw) {
+		ensureEpoch(context);
+		const text = await messageText(raw);
+		ensureEpoch(context);
+		if (text === GSCDUMP_REALTIME_PONG) {
+			context.lastPongAt = runtime.now();
+			return;
+		}
+		const textBytes = utf8Size(text);
+		if (textBytes > GSCDUMP_REALTIME_LIMITS.outboundFrameMaxBytes) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "A server frame exceeded the v1 outbound frame limit.",
+			retryable: false,
+			terminal: true
+		});
+		let rawFrame;
+		try {
+			rawFrame = JSON.parse(text);
+		} catch (cause) {
+			throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "The server sent malformed realtime JSON.",
+				retryable: false,
+				terminal: true,
+				cause
+			});
+		}
+		const parsed = schemas.serverFrame.safeParse(rawFrame);
+		if (!parsed.success) throw new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "The server frame did not match the v1 protocol.",
+			retryable: false,
+			terminal: true,
+			details: parseErrorDetails(parsed.error),
+			cause: parsed.error
+		});
+		if (parsed.data.type === "event") {
+			if (textBytes > (parsed.data.delivery === "durable" ? GSCDUMP_REALTIME_LIMITS.durableEventMaxBytes : GSCDUMP_REALTIME_LIMITS.ephemeralEventMaxBytes)) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: `A ${parsed.data.delivery} event exceeded its v1 size limit.`,
+				retryable: false,
+				terminal: true
+			});
+		}
+		if (parsed.data.type === "batch") {
+			for (const event of parsed.data.events) if (utf8Size(JSON.stringify(event)) > GSCDUMP_REALTIME_LIMITS.durableEventMaxBytes) throw new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: "A durable event inside a batch exceeded its v1 size limit.",
+				retryable: false,
+				terminal: true
+			});
+		}
+		await processFrame(context, parsed.data);
+	}
+	function handleFrameQueueError(context, cause) {
+		if (cause instanceof StaleEpochError || !running || current !== context) return;
+		const error = cause instanceof GscdumpRealtimeV1Error ? cause : new GscdumpRealtimeV1Error({
+			code: "protocol_error",
+			message: "Realtime frame processing failed.",
+			retryable: false,
+			terminal: true,
+			cause
+		});
+		if (error.terminal) {
+			terminal(error, context);
+			return;
+		}
+		reportError(error);
+		scheduleReconnect(context, error.code);
+	}
+	async function loadCursor(ticket) {
+		let stored;
+		try {
+			stored = await cursorStore.load();
+		} catch (cause) {
+			throw new GscdumpRealtimeV1Error({
+				code: "cursor_store_failed",
+				message: "Could not load the realtime cursor.",
+				retryable: false,
+				terminal: true,
+				cause
+			});
+		}
+		if (stored === null) return null;
+		const parsed = schemas.cursor.safeParse(stored);
+		if (!parsed.success) {
+			reportError(new GscdumpRealtimeV1Error({
+				code: "cursor_store_failed",
+				message: "The stored realtime cursor was invalid; a full resync is required.",
+				retryable: true,
+				terminal: false,
+				details: parseErrorDetails(parsed.error),
+				cause: parsed.error
+			}));
+			return null;
+		}
+		if (parsed.data.streamId !== ticket.head.streamId) return null;
+		return parsed.data;
+	}
+	async function provideFreshTicket() {
+		let raw;
+		try {
+			raw = await options.ticketProvider();
+		} catch (cause) {
+			throw new GscdumpRealtimeV1Error({
+				code: "ticket_provider_failed",
+				message: "The realtime ticket provider rejected.",
+				retryable: true,
+				terminal: false,
+				cause
+			});
+		}
+		const parsed = schemas.ticketResponseClient.safeParse(raw);
+		if (!parsed.success) throw new GscdumpRealtimeV1Error({
+			code: "ticket_invalid",
+			message: "The realtime ticket response did not match the v1 contract.",
+			retryable: false,
+			terminal: true,
+			details: parseErrorDetails(parsed.error),
+			cause: parsed.error
+		});
+		if (Date.parse(parsed.data.data.expiresAt) <= runtime.now()) throw new GscdumpRealtimeV1Error({
+			code: "ticket_invalid",
+			message: "The realtime ticket had already expired locally.",
+			retryable: true,
+			terminal: false,
+			details: { localExpiry: true }
+		});
+		return parsed.data.data;
+	}
+	async function beginAttempt() {
+		if (!running) return;
+		const attemptEpoch = ++epoch;
+		setState("ticketing", freshness === "fresh" ? "stale" : freshness);
+		let ticket;
+		try {
+			ticket = await provideFreshTicket();
+		} catch (cause) {
+			if (!running || epoch !== attemptEpoch) return;
+			const error = cause instanceof GscdumpRealtimeV1Error ? cause : new GscdumpRealtimeV1Error({
+				code: "ticket_provider_failed",
+				message: "Could not obtain a realtime ticket.",
+				retryable: true,
+				terminal: false,
+				cause
+			});
+			if (error.code === "ticket_invalid" && error.details.localExpiry === true && immediateExpiredTicketRetry) {
+				immediateExpiredTicketRetry = false;
+				beginAttempt();
+				return;
+			}
+			reportError(error);
+			if (error.terminal) terminal(error, null);
+			else scheduleReconnect(null, error.code);
+			return;
+		}
+		immediateExpiredTicketRetry = true;
+		if (!running || epoch !== attemptEpoch) return;
+		try {
+			cursor = await loadCursor(ticket);
+		} catch (cause) {
+			if (!running || epoch !== attemptEpoch) return;
+			terminal(cause, null);
+			return;
+		}
+		if (!running || epoch !== attemptEpoch) return;
+		streamId = ticket.head.streamId;
+		head = { ...ticket.head };
+		emitState();
+		let socket;
+		try {
+			socket = runtime.createSocket(ticket.socketUrl, [ticket.protocol, ticket.ticket]);
+		} catch (cause) {
+			terminal(cause instanceof GscdumpRealtimeV1Error ? cause : new GscdumpRealtimeV1Error({
+				code: "runtime_unavailable",
+				message: "Could not create the realtime WebSocket.",
+				retryable: false,
+				terminal: true,
+				cause
+			}), null);
+			return;
+		}
+		const context = {
+			epoch: attemptEpoch,
+			socket,
+			ticket,
+			accepted: false,
+			ready: false,
+			closed: false,
+			replaying: false,
+			replayThrough: null,
+			lastPongAt: runtime.now(),
+			head: null,
+			retryAfterMs: void 0,
+			frameQueue: Promise.resolve()
+		};
+		current = context;
+		setState("connecting", freshness);
+		socket.onopen = () => {
+			if (!running || current !== context || context.closed) return;
+			context.accepted = true;
+			if (socket.protocol !== GSCDUMP_REALTIME_SUBPROTOCOL) {
+				terminal(new GscdumpRealtimeV1Error({
+					code: "protocol_error",
+					message: "The WebSocket did not select gscdump.v1.",
+					retryable: false,
+					terminal: true,
+					details: { selectedProtocol: socket.protocol }
+				}), context);
+				return;
+			}
+			setState("handshaking", cursor ? "stale" : "unknown");
+			try {
+				const hello = schemas.helloFrame.parse({
+					type: "hello",
+					protocolVersion: GSCDUMP_REALTIME_PROTOCOL_VERSION,
+					sdkVersion,
+					resume: cursor
+				});
+				sendJson(context, hello);
+			} catch (cause) {
+				handleFrameQueueError(context, cause);
+			}
+		};
+		socket.onmessage = (event) => {
+			if (!running || current !== context || context.closed) return;
+			const work = context.frameQueue.then(() => processRawMessage(context, event.data));
+			context.frameQueue = work.catch((cause) => {
+				handleFrameQueueError(context, cause);
+			});
+		};
+		socket.onerror = (cause) => {
+			if (!running || current !== context || context.closed) return;
+			const error = new GscdumpRealtimeV1Error({
+				code: context.accepted ? "socket_error" : "upgrade_rejected",
+				message: context.accepted ? "The accepted realtime socket emitted an opaque error." : "The realtime WebSocket upgrade was rejected or failed opaquely.",
+				retryable: true,
+				terminal: false,
+				cause
+			});
+			reportError(error);
+			scheduleReconnect(context, error.code);
+		};
+		socket.onclose = (event) => {
+			if (context.closed || current !== context) return;
+			current = null;
+			epoch++;
+			clearConnectionTimers();
+			const code = event.code ?? 1006;
+			if (!running) return;
+			if (!context.accepted) {
+				reportError(new GscdumpRealtimeV1Error({
+					code: "upgrade_rejected",
+					message: "The realtime WebSocket upgrade failed opaquely.",
+					retryable: true,
+					terminal: false,
+					details: { closeCode: code }
+				}));
+				scheduleReconnect(null, "upgrade-rejected");
+				return;
+			}
+			if (code === GSCDUMP_REALTIME_CLOSE_CODES.normal) {
+				running = false;
+				setState("stopped", "unknown");
+				return;
+			}
+			if (code === GSCDUMP_REALTIME_CLOSE_CODES.protocolError || code === GSCDUMP_REALTIME_CLOSE_CODES.policyViolation) {
+				terminal(new GscdumpRealtimeV1Error({
+					code: "protocol_error",
+					message: `The realtime server closed with terminal code ${code}.`,
+					retryable: false,
+					terminal: true,
+					details: {
+						closeCode: code,
+						reason: event.reason
+					}
+				}), null);
+				return;
+			}
+			if (code === GSCDUMP_REALTIME_CLOSE_CODES.maximumLifetime) {
+				scheduleReconnect(null, "maximum-lifetime", 0, true);
+				return;
+			}
+			if (code === 1006 || code === GSCDUMP_REALTIME_CLOSE_CODES.internalError || code === GSCDUMP_REALTIME_CLOSE_CODES.serviceRestart || code === GSCDUMP_REALTIME_CLOSE_CODES.overloadedOrAckLag) {
+				scheduleReconnect(null, `close-${code}`, context.retryAfterMs);
+				return;
+			}
+			terminal(new GscdumpRealtimeV1Error({
+				code: "protocol_error",
+				message: `The realtime server used an unsupported close code ${code}.`,
+				retryable: false,
+				terminal: true,
+				details: {
+					closeCode: code,
+					reason: event.reason
+				}
+			}), null);
+		};
+	}
+	async function start() {
+		if (running) return;
+		running = true;
+		attempt = 0;
+		lastError = null;
+		immediateExpiredTicketRetry = true;
+		freshness = cursor ? "stale" : "unknown";
+		await beginAttempt();
+	}
+	function stop() {
+		running = false;
+		clearTimer(reconnectTimer);
+		reconnectTimer = void 0;
+		if (current) closeSocket(current, GSCDUMP_REALTIME_CLOSE_CODES.normal, "manual");
+		else epoch++;
+		setState("stopped", "unknown");
+	}
+	return {
+		start,
+		stop,
+		getSnapshot
+	};
+}
+export { GSCDUMP_REALTIME_V1_SDK_VERSION, GscdumpRealtimeV1Error, createGscdumpRealtimeV1Client };