effect-durable-agent-cloudflare 0.1.0-alpha.22 → 0.1.0-alpha.23

package/dist/{session-controller-BGfz1DdS.js → session-controller-BnNMF12R.js}

@@ -1,6 +1,7 @@
 import "effect-durable-agent/services/prompt-projector";
 import * as Layer from "effect/Layer";
 import * as Effect from "effect/Effect";
+import * as Exit from "effect/Exit";
 import * as Schema from "effect/Schema";
 import { ContextRebasedPayload, DurableEventEnvelope, SummaryCreatedPayload, assistantMessageCommittedEventType, assistantMessageImportedEventType, assistantPartialCommittedEventType, commandAdmittedEventType, commandCancelledEventType, commandCompletedEventType, commandFailedEventType, commandStartedEventType, contextRebasedEventType, decodeDurableEventSync, effectDurableAgentNamespace, steeringMessageQueuedEventType, summaryCreatedEventType, systemMessageCommittedEventType, userMessageCommittedEventType } from "effect-durable-agent/types/events";
 import { SequenceNumber, SessionId, SummaryId, durablePosition } from "effect-durable-agent/types/core";
@@ -20,7 +21,8 @@ import { EDAKeepAlive } from "effect-durable-agent/services/keep-alive";
 import { EDAReducerRegistry } from "effect-durable-agent/services/reducer-registry";
 import { makeEDARuntimeLayer } from "effect-durable-agent/services/runtime-layer";
 import { SessionEventObserver } from "effect-durable-agent/services/session-event-observer";
-import { EDAWebSocketDeliveryCheckpoint, EDA_WEB_SOCKET_PING_MESSAGE, EDA_WEB_SOCKET_PONG_MESSAGE, EDA_WS_CLOSE_PROTOCOL_ERROR, EDA_WS_CLOSE_SEND_FAILED, SubscriberId, checkpointWebSocketDeliveryState, decodeEDAWebSocketClientMessage, defaultEDAWebSocketFlowControl, deliveryHelloFrame, encodeEDAWebSocketServerFrame, makeWebSocketDeliveryState, onClientAck, onDurableEvents, onEphemeralEvent, onHostSuppressedFrame, restoreWebSocketDeliveryState } from "effect-durable-agent/websocket";
+import { EDATranscriptClientFrame, EDATranscriptDeliveryCheckpoint, EDAWebSocketDeliveryCheckpoint, EDA_WEB_SOCKET_PING_MESSAGE, EDA_WEB_SOCKET_PONG_MESSAGE, EDA_WEB_SOCKET_PROTOCOL_VERSION, EDA_WS_CLOSE_LAGGED, EDA_WS_CLOSE_PROTOCOL_ERROR, EDA_WS_CLOSE_SEND_FAILED, EDA_WS_CLOSE_TRANSCRIPT_RESUBSCRIBE, SubscriberId, checkpointTranscriptDelivery, checkpointWebSocketDeliveryState, decodeEDAWebSocketClientMessage, defaultEDATranscriptDeliveryLimits, defaultEDAWebSocketFlowControl, deliveryHelloFrame, edaTranscriptNegotiation, edaTranscriptUpdateFrameText, encodeEDATranscriptServerFrame, encodeEDATranscriptUpdate, encodeEDAWebSocketServerFrame, enqueueTranscriptRequest, laggedCloseReason, makeTranscriptDeliveryState, makeWebSocketDeliveryState, onClientAck, onDurableEvents, onEphemeralEvent, onHostSuppressedFrame, onTranscriptAck, pumpTranscriptTransfer, restoreTranscriptDeliveryState, restoreWebSocketDeliveryState, startTranscriptUpdate, transcriptAckTimedOut, transcriptDeliveryCapacity, utf8ByteLength } from "effect-durable-agent/websocket";
+import { defaultTranscriptSubscriptionPolicy, emptyTranscriptActiveContentState, foldTranscriptActiveContent, planTranscriptUpdate, readTranscriptSubscription, transcriptActiveContentOf, transcriptSubscriptionBaseOf } from "effect-durable-agent/transcript";
 /**
 * Alarm-backed in-memory keepalive for a raw Durable Object host.
 *
@@ -986,13 +988,27 @@ const EDAWebSocketAttachment = Schema.Struct({
 		state: Schema.Unknown
 	}))
 });
+/**
+* State required to resume a transcript-window socket after hibernation: the transport receipts,
+* the applied cut, the subscription base and unanswered requests. Staged chunk data is never
+* persisted; a checkpoint that names a transfer cannot resume it.
+*/
+const EDATranscriptWebSocketAttachment = Schema.Struct({
+	kind: Schema.Literal("eda-transcript-v1"),
+	sessionId: SessionId,
+	subscriberId: SubscriberId,
+	trace: EDATraceMetadata,
+	delivery: EDATranscriptDeliveryCheckpoint
+});
+/** Either socket kind an EDA Durable Object accepts. */
+const EDAAnyWebSocketAttachment = Schema.Union([EDAWebSocketAttachment, EDATranscriptWebSocketAttachment]);
 /** Decode and classify an attachment read from Cloudflare's structured-clone boundary. */
 const decodeWebSocketAttachment = async (input) => {
 	if (input === null || input === void 0) return { _tag: "Missing" };
 	try {
 		return {
 			_tag: "Decoded",
-			attachment: await Effect.runPromise(Schema.decodeUnknownEffect(EDAWebSocketAttachment)(input))
+			attachment: await Effect.runPromise(Schema.decodeUnknownEffect(EDAAnyWebSocketAttachment)(input))
 		};
 	} catch {
 		return { _tag: "Malformed" };
@@ -1000,6 +1016,505 @@ const decodeWebSocketAttachment = async (input) => {
 };
 /** Encode before serialization so schema transformations cannot leak into attachments. */
 const encodeWebSocketAttachment = (attachment) => Schema.encodeSync(EDAWebSocketAttachment)(attachment);
+/** Encode a transcript socket attachment for Cloudflare's structured-clone boundary. */
+const encodeTranscriptWebSocketAttachment = (attachment) => Schema.encodeSync(EDATranscriptWebSocketAttachment)(attachment);
+//#endregion
+//#region src/websocket/transcript-sockets.ts
+const defaultActiveContentCadenceMs = 50;
+/** Largest client frame accepted; requests are persisted, so this bounds the attachment too. */
+const maxClientFrameLength = 2048;
+const decodeClientFrame = Schema.decodeUnknownExit(EDATranscriptClientFrame);
+/**
+* Owns transcript-window sockets: the window data source beneath the frame encoder.
+*
+* Every subscriber is served strictly in order. Committed changes are coalesced to the complete
+* boundary a store read returns; a request is answered by one read at one cut; and each update is
+* sent from its own captured snapshot before the next is planned.
+*
+* **Publication fence.** Append publication, ephemeral publication and window capture share one
+* fence: the active-content accumulator folds every published event in order, and a capture is
+* served with live content only when the accumulator has folded exactly the window's cut. Durable
+* commit precedes live publication, so a window read between the two would otherwise pair a
+* committed inference with its stale live parts. A capture that would cross the fence waits for
+* publication to catch up.
+*/
+var EDATranscriptSockets = class {
+	options;
+	sockets = /* @__PURE__ */ new Map();
+	active = emptyTranscriptActiveContentState;
+	timerArmed = false;
+	background = /* @__PURE__ */ new Set();
+	flowControl;
+	policy;
+	limits;
+	cadenceMs;
+	fenceWaitMs;
+	maxTotalStagedBytes;
+	schedule;
+	now;
+	constructor(options) {
+		this.options = options;
+		this.flowControl = options.flowControl ?? defaultEDAWebSocketFlowControl;
+		this.policy = options.subscriptionPolicy ?? defaultTranscriptSubscriptionPolicy;
+		this.limits = options.deliveryLimits ?? defaultEDATranscriptDeliveryLimits;
+		this.cadenceMs = options.activeContentCadenceMs ?? 50;
+		this.fenceWaitMs = options.fenceWaitMs ?? 1e3;
+		this.maxTotalStagedBytes = options.maxTotalStagedBytes ?? 33554432;
+		this.schedule = options.schedule ?? ((delayMs, run) => {
+			setTimeout(run, delayMs);
+		});
+		this.now = options.now ?? Date.now;
+	}
+	has(webSocket) {
+		return this.sockets.has(webSocket);
+	}
+	/** Transcript sockets this isolate holds, for hosts that cannot enumerate accepted sockets. */
+	webSockets() {
+		return [...this.sockets.keys()];
+	}
+	/**
+	* Register a freshly accepted socket and greet it. Synchronous so the attachment exists before
+	* any platform callback can observe the socket.
+	*/
+	accept(input) {
+		const socket = {
+			sessionId: input.sessionId,
+			subscriberId: SubscriberId.make(crypto.randomUUID()),
+			trace: input.trace,
+			delivery: makeTranscriptDeliveryState(this.flowControl),
+			queue: Promise.resolve(),
+			dirty: false,
+			sentActiveRevision: void 0,
+			last: void 0,
+			fenceWaitingSinceMs: void 0,
+			scheduledDrain: void 0,
+			stagedBytes: 0,
+			activeSentAtMs: void 0,
+			cadenceDue: false
+		};
+		this.sockets.set(input.webSocket, socket);
+		if (!this.persist(input.webSocket, socket)) return;
+		this.sendText(input.webSocket, encodeEDATranscriptServerFrame({
+			_tag: "hello",
+			protocolVersion: EDA_WEB_SOCKET_PROTOCOL_VERSION,
+			subscriberId: socket.subscriberId,
+			resumeSeq: 0,
+			flowControl: this.flowControl,
+			negotiation: edaTranscriptNegotiation
+		}));
+	}
+	/**
+	* Adopt a socket that survived hibernation. A socket that was mid-transfer lost its staged
+	* chunks with the isolate: it is closed, and the client reconnects and resubscribes.
+	*/
+	restore(webSocket, attachment) {
+		const restored = restoreTranscriptDeliveryState(this.flowControl, attachment.delivery);
+		if (restored._tag === "TransferLost") {
+			this.close(webSocket, EDA_WS_CLOSE_TRANSCRIPT_RESUBSCRIBE, "transfer-lost");
+			return false;
+		}
+		this.sockets.set(webSocket, {
+			sessionId: attachment.sessionId,
+			subscriberId: attachment.subscriberId,
+			trace: attachment.trace,
+			delivery: restored.state,
+			queue: Promise.resolve(),
+			dirty: true,
+			sentActiveRevision: void 0,
+			last: void 0,
+			fenceWaitingSinceMs: void 0,
+			scheduledDrain: void 0,
+			stagedBytes: 0,
+			activeSentAtMs: void 0,
+			cadenceDue: false
+		});
+		return true;
+	}
+	closed(webSocket) {
+		this.sockets.delete(webSocket);
+	}
+	/**
+	* Observe one published event, in publication order. Folds it into the active-content
+	* accumulator synchronously, then lets each listed subscriber act on it: a durable event
+	* schedules a read at the new boundary; changed live content is coalesced to the display
+	* cadence.
+	*
+	* Reads are scheduled, not awaited, so subscribers never hold the session's append gate. The
+	* fence does not need the gate: every capture is checked against the accumulator's folded head
+	* when its read resolves.
+	*/
+	onPublished(event, webSockets) {
+		const revision = this.active.revision;
+		this.active = foldTranscriptActiveContent(this.active, event);
+		if (event.event.durability !== "durable") {
+			if (this.active.revision !== revision) this.armCadence();
+			return;
+		}
+		for (const webSocket of webSockets) {
+			const socket = this.sockets.get(webSocket);
+			if (socket === void 0) continue;
+			socket.dirty = true;
+			this.track(this.drain(webSocket, socket));
+		}
+	}
+	/** Serve sockets restored from hibernation after a publication was folded. */
+	serveRestored(webSockets) {
+		for (const webSocket of webSockets) {
+			const socket = this.sockets.get(webSocket);
+			if (socket === void 0) continue;
+			socket.dirty = true;
+			this.track(this.drain(webSocket, socket));
+		}
+	}
+	/**
+	* The session's log was destroyed: live content belongs to a log that no longer exists and
+	* every subscription names its incarnation. Close transcript sockets so clients resubscribe.
+	*/
+	reset() {
+		this.active = emptyTranscriptActiveContentState;
+		for (const webSocket of [...this.sockets.keys()]) this.close(webSocket, EDA_WS_CLOSE_TRANSCRIPT_RESUBSCRIBE, "session-reset");
+	}
+	async message(webSocket, message) {
+		const socket = this.sockets.get(webSocket);
+		if (socket === void 0) {
+			this.close(webSocket, EDA_WS_CLOSE_PROTOCOL_ERROR, "protocol");
+			return;
+		}
+		if (message === EDA_WEB_SOCKET_PING_MESSAGE) {
+			this.sendText(webSocket, EDA_WEB_SOCKET_PONG_MESSAGE);
+			return;
+		}
+		if (message.length > maxClientFrameLength) {
+			this.protocolError(webSocket, "Client frame too large");
+			return;
+		}
+		let json;
+		try {
+			json = JSON.parse(message);
+		} catch {
+			this.protocolError(webSocket, "Malformed client frame");
+			return;
+		}
+		const decoded = decodeClientFrame(json);
+		if (Exit.isFailure(decoded)) {
+			this.protocolError(webSocket, "Unknown client frame");
+			return;
+		}
+		const frame = decoded.value;
+		if (frame._tag === "ping") return;
+		await this.enqueue(webSocket, socket, async () => {
+			if (frame._tag === "ack") {
+				const acked = onTranscriptAck(socket.delivery, frame);
+				if (acked._tag === "ProtocolError") {
+					this.protocolError(webSocket, acked.message);
+					return;
+				}
+				if (acked._tag === "Ignored") return;
+				socket.delivery = acked.state;
+				if (!this.persist(webSocket, socket)) return;
+			} else {
+				const queued = enqueueTranscriptRequest(socket.delivery, frame, this.limits);
+				if (queued === void 0) {
+					this.protocolError(webSocket, "Too many unanswered transcript requests");
+					return;
+				}
+				socket.delivery = queued;
+				if (!this.persist(webSocket, socket)) return;
+			}
+			await this.drainNow(webSocket, socket);
+		});
+	}
+	/** Wait for scheduled reads and cadence flushes; for orderly shutdown and tests. */
+	async settled() {
+		while (this.background.size > 0) await Promise.all([...this.background]);
+	}
+	/**
+	* Own scheduled subscriber work until it settles. Drains never reject: `enqueue` contains every
+	* failure and closes the socket.
+	*/
+	track(work) {
+		const tracked = work.finally(() => {
+			this.background.delete(tracked);
+		});
+		this.background.add(tracked);
+	}
+	armCadence() {
+		if (this.timerArmed) return;
+		this.timerArmed = true;
+		this.schedule(this.cadenceMs, () => {
+			this.timerArmed = false;
+			for (const [webSocket, socket] of this.sockets) {
+				socket.cadenceDue = true;
+				this.track(this.drain(webSocket, socket));
+			}
+		});
+	}
+	/**
+	* Schedule one drain, coalescing with a drain that is scheduled but not yet running. A drain
+	* that is already running re-checks `dirty` before it returns, so nothing is missed.
+	*/
+	drain(webSocket, socket) {
+		if (socket.scheduledDrain !== void 0) return socket.scheduledDrain;
+		const scheduled = this.enqueue(webSocket, socket, () => {
+			socket.scheduledDrain = void 0;
+			return this.drainNow(webSocket, socket);
+		});
+		socket.scheduledDrain = scheduled;
+		return scheduled;
+	}
+	/** Send everything this subscriber is owed, one complete update at a time. */
+	async drainNow(webSocket, socket) {
+		for (;;) {
+			if (this.sockets.get(webSocket) !== socket) return;
+			const nowMs = this.now();
+			if (transcriptAckTimedOut(socket.delivery, nowMs)) {
+				this.sendText(webSocket, encodeEDATranscriptServerFrame({
+					_tag: "lagged",
+					resumeSeq: socket.delivery.appliedThroughSeq,
+					reason: "ack-timeout"
+				}));
+				this.close(webSocket, EDA_WS_CLOSE_LAGGED, laggedCloseReason(socket.delivery.appliedThroughSeq));
+				return;
+			}
+			if (socket.delivery.transfer !== void 0) {
+				const pumped = pumpTranscriptTransfer(socket.delivery, nowMs);
+				if (pumped.frames.length === 0) return;
+				socket.delivery = pumped.state;
+				if (pumped.state.transfer === void 0) socket.stagedBytes = 0;
+				if (!this.persistAndSend(webSocket, socket, pumped.frames)) return;
+				continue;
+			}
+			if (transcriptDeliveryCapacity(socket.delivery) <= 0) return;
+			const request = socket.delivery.requests[0];
+			const base = socket.delivery.subscription;
+			if (request === void 0) {
+				if (base === void 0) return;
+				if (!socket.dirty) {
+					if (socket.sentActiveRevision === this.active.revision) {
+						socket.cadenceDue = false;
+						return;
+					}
+					if (!(socket.cadenceDue || socket.activeSentAtMs === void 0 || nowMs - socket.activeSentAtMs >= this.cadenceMs)) {
+						this.armCadence();
+						return;
+					}
+					const sent = await this.sendActiveOnly(webSocket, socket);
+					if (sent === "NeedsRead") {
+						socket.dirty = true;
+						continue;
+					}
+					if (sent === "Failed") return;
+					continue;
+				}
+			}
+			const subscriptionRequest = request === void 0 ? { _tag: "Refresh" } : toSubscriptionRequest(request);
+			socket.dirty = false;
+			const read = await Effect.runPromiseExit(readTranscriptSubscription(this.options.transcriptStore, base, subscriptionRequest, this.policy));
+			if (this.sockets.get(webSocket) !== socket) return;
+			if (Exit.isFailure(read)) {
+				await Effect.runPromise(Effect.logError("EDA transcript window read failed", {
+					cause: read.cause,
+					subscriberId: socket.subscriberId
+				}));
+				this.close(webSocket, EDA_WS_CLOSE_SEND_FAILED, "read-failed");
+				return;
+			}
+			const { window, patchBase } = read.value;
+			const active = this.active;
+			const fenced = !(window.readiness._tag === "Ready") || window.throughSeq === active.publishedThroughSeq || window.throughSeq > active.publishedThroughSeq && active.inference === void 0;
+			if (!fenced) {
+				socket.fenceWaitingSinceMs ??= nowMs;
+				if (nowMs - socket.fenceWaitingSinceMs < this.fenceWaitMs) {
+					socket.dirty = true;
+					this.armCadence();
+					return;
+				}
+			}
+			socket.fenceWaitingSinceMs = void 0;
+			const update = planTranscriptUpdate({
+				patchBase,
+				window,
+				updateSeq: socket.delivery.nextUpdateSeq,
+				activeContent: fenced ? transcriptActiveContentOf(active) : [],
+				includeActiveContent: !fenced || socket.sentActiveRevision !== active.revision || window.readiness._tag === "Ready" && socket.last !== void 0 && socket.last.readiness._tag !== "Ready",
+				...request?.requestId === void 0 ? {} : { requestId: request.requestId }
+			});
+			const remaining = request === void 0 ? socket.delivery.requests : socket.delivery.requests.slice(1);
+			if (request === void 0 && this.isNoop(socket, update)) continue;
+			if (!await this.start(webSocket, socket, update, transcriptSubscriptionBaseOf(window), remaining)) return;
+			socket.sentActiveRevision = active.revision;
+			if (update.activeContent !== void 0) {
+				socket.cadenceDue = false;
+				socket.activeSentAtMs = this.now();
+			}
+			socket.last = {
+				readiness: window.readiness,
+				hasOlder: window.hasOlder,
+				hasNewer: window.hasNewer,
+				dependencyIds: update.dependencyIds
+			};
+		}
+	}
+	/**
+	* Publish changed live content without a store read. Valid only while the accumulator has
+	* folded exactly the subscriber's last cut; otherwise a commit is pending and a read is needed.
+	*/
+	async sendActiveOnly(webSocket, socket) {
+		const base = socket.delivery.subscription;
+		const last = socket.last;
+		const active = this.active;
+		if (last !== void 0 && last.readiness._tag !== "Ready") {
+			socket.sentActiveRevision = active.revision;
+			return "Sent";
+		}
+		if (base === void 0 || last === void 0 || active.publishedThroughSeq !== base.throughSeq) return "NeedsRead";
+		const update = {
+			updateSeq: socket.delivery.nextUpdateSeq,
+			mode: "patch",
+			incarnation: base.incarnation,
+			version: base.version,
+			throughSeq: base.throughSeq,
+			...base.coverage === void 0 ? {} : { coverage: base.coverage },
+			hasOlder: last.hasOlder,
+			hasNewer: last.hasNewer,
+			readiness: last.readiness,
+			records: [],
+			dependencies: [],
+			dependencyIds: last.dependencyIds,
+			activeContent: transcriptActiveContentOf(active)
+		};
+		if (!await this.start(webSocket, socket, update, base, socket.delivery.requests)) return "Failed";
+		socket.sentActiveRevision = active.revision;
+		socket.cadenceDue = false;
+		socket.activeSentAtMs = this.now();
+		return "Sent";
+	}
+	/** A refresh that changes nothing the client holds is not sent. */
+	isNoop(socket, update) {
+		const base = socket.delivery.subscription;
+		const last = socket.last;
+		return base !== void 0 && last !== void 0 && update.mode === "patch" && update.records.length === 0 && update.dependencies.length === 0 && update.activeContent === void 0 && update.throughSeq === base.throughSeq && update.hasOlder === last.hasOlder && update.hasNewer === last.hasNewer && JSON.stringify(update.coverage) === JSON.stringify(base.coverage) && JSON.stringify(update.readiness) === JSON.stringify(last.readiness);
+	}
+	async start(webSocket, socket, update, subscription, requests) {
+		const encodedUpdate = encodeEDATranscriptUpdate(update);
+		const bytes = utf8ByteLength(encodedUpdate);
+		if (utf8ByteLength(edaTranscriptUpdateFrameText(socket.delivery.nextFrameId, encodedUpdate)) > this.flowControl.maxFrameBytes && this.stagedBytes() + bytes > this.maxTotalStagedBytes) {
+			this.close(webSocket, EDA_WS_CLOSE_TRANSCRIPT_RESUBSCRIBE, "staging-budget");
+			return false;
+		}
+		const started = startTranscriptUpdate({
+			...socket.delivery,
+			requests
+		}, {
+			update,
+			encodedUpdate,
+			subscription
+		}, this.limits, this.now());
+		if (started._tag === "TooLarge") {
+			await Effect.runPromise(Effect.logError("EDA transcript update exceeds the staging bound", {
+				bytes: started.bytes,
+				subscriberId: socket.subscriberId
+			}));
+			this.close(webSocket, EDA_WS_CLOSE_SEND_FAILED, "update-too-large");
+			return false;
+		}
+		socket.delivery = started.state;
+		socket.stagedBytes = started.state.transfer === void 0 ? 0 : bytes;
+		return this.persistAndSend(webSocket, socket, started.frames);
+	}
+	/** Bytes of chunked updates still being transferred, across every socket of this object. */
+	stagedBytes() {
+		let total = 0;
+		for (const socket of this.sockets.values()) total += socket.stagedBytes;
+		return total;
+	}
+	/** Persist the checkpoint before any frame it accounts for becomes client-visible. */
+	persistAndSend(webSocket, socket, frames) {
+		if (!this.persist(webSocket, socket)) return false;
+		for (const frame of frames) if (!this.sendText(webSocket, frame)) return false;
+		return true;
+	}
+	persist(webSocket, socket) {
+		try {
+			webSocket.serializeAttachment(encodeTranscriptWebSocketAttachment(EDATranscriptWebSocketAttachment.make({
+				kind: "eda-transcript-v1",
+				sessionId: socket.sessionId,
+				subscriberId: socket.subscriberId,
+				trace: socket.trace,
+				delivery: checkpointTranscriptDelivery(socket.delivery)
+			})));
+			return true;
+		} catch (error) {
+			Effect.runSync(Effect.logError("EDA transcript socket attachment failed", {
+				error,
+				subscriberId: socket.subscriberId
+			}));
+			this.close(webSocket, EDA_WS_CLOSE_SEND_FAILED, "attachment-failed");
+			return false;
+		}
+	}
+	sendText(webSocket, text) {
+		try {
+			webSocket.send(text);
+			return true;
+		} catch (error) {
+			Effect.runSync(Effect.logWarning("EDA transcript socket send failed", { error }));
+			this.close(webSocket, EDA_WS_CLOSE_SEND_FAILED, "send-failed");
+			return false;
+		}
+	}
+	protocolError(webSocket, message) {
+		this.sendText(webSocket, encodeEDATranscriptServerFrame({
+			_tag: "error",
+			message: message.slice(0, 120)
+		}));
+		this.close(webSocket, EDA_WS_CLOSE_PROTOCOL_ERROR, "protocol");
+	}
+	enqueue(webSocket, socket, operation) {
+		const run = async () => {
+			try {
+				await operation();
+			} catch (error) {
+				await Effect.runPromise(Effect.logError("EDA transcript socket operation failed", {
+					error,
+					subscriberId: socket.subscriberId
+				}));
+				this.close(webSocket, EDA_WS_CLOSE_SEND_FAILED, "subscriber-failed");
+			}
+		};
+		const next = socket.queue.then(run);
+		socket.queue = next;
+		return next;
+	}
+	close(webSocket, code, reason) {
+		this.sockets.delete(webSocket);
+		try {
+			webSocket.close(code, reason);
+		} catch {}
+	}
+};
+const toSubscriptionRequest = (frame) => {
+	switch (frame._tag) {
+		case "subscribe": return {
+			_tag: "Subscribe",
+			tail: frame.tail ?? false,
+			...frame.range === void 0 ? {} : { range: frame.range },
+			...frame.since === void 0 ? {} : { since: frame.since },
+			...frame.count === void 0 ? {} : { count: frame.count }
+		};
+		case "page": return {
+			_tag: "Page",
+			direction: frame.direction,
+			cursor: frame.cursor,
+			count: frame.count
+		};
+		case "retain": return {
+			_tag: "Retain",
+			from: frame.from,
+			to: frame.to
+		};
+	}
+};
 //#endregion
 //#region src/websocket/connection-manager.ts
 /**
@@ -1010,8 +1525,33 @@ var EDAWebSocketConnectionManager = class {
 	options;
 	observerLayer = SessionEventObserver.FromHandler((event) => Effect.tryPromise(() => this.fanoutPublishedEvent(event)).pipe(Effect.catchCause((cause) => Effect.logError("EDA WebSocket event observer recovered from a host failure", { cause }))));
 	sockets = /* @__PURE__ */ new Map();
+	transcript;
 	constructor(options) {
 		this.options = options;
+		this.transcript = options.transcript === void 0 ? void 0 : new EDATranscriptSockets(options.transcript);
+	}
+	/** Whether this host serves transcript-window sockets. */
+	get supportsTranscript() {
+		return this.transcript !== void 0;
+	}
+	/**
+	* Accept a transcript-window socket. Reads are storage-level, so this never prepares the
+	* session runtime. Call immediately after `ctx.acceptWebSocket()`.
+	*/
+	acceptTranscript(input) {
+		if (this.transcript === void 0) {
+			this.close(input.webSocket, EDA_WS_CLOSE_PROTOCOL_ERROR, "unsupported");
+			return;
+		}
+		this.transcript.accept(input);
+	}
+	/** The session's log was destroyed: close transcript sockets and drop live content. */
+	resetTranscript() {
+		this.transcript?.reset();
+	}
+	/** Wait for scheduled transcript flushes; for orderly shutdown and tests. */
+	async settled() {
+		await this.transcript?.settled();
 	}
 	resolveProjection(id) {
 		if (id === void 0) return void 0;
@@ -1055,7 +1595,13 @@ var EDAWebSocketConnectionManager = class {
 			}
 			return;
 		}
-		const state = await this.restore(webSocket);
+		const restored = await this.restore(webSocket);
+		if (restored === "transcript") {
+			await this.transcript?.message(webSocket, message);
+			return;
+		}
+		if (restored === "closed") return;
+		const state = restored;
 		if (state === void 0) {
 			this.close(webSocket, EDA_WS_CLOSE_PROTOCOL_ERROR, "protocol");
 			return;
@@ -1074,6 +1620,7 @@ var EDAWebSocketConnectionManager = class {
 	}
 	closed(webSocket) {
 		this.sockets.delete(webSocket);
+		this.transcript?.closed(webSocket);
 	}
 	async flushDeferredCatchUp(sessionId) {
 		const deliveries = [];
@@ -1088,11 +1635,22 @@ var EDAWebSocketConnectionManager = class {
 		await Promise.all(deliveries);
 	}
 	async fanoutPublishedEvent(event) {
-		const webSockets = /* @__PURE__ */ new Set([...this.options.getWebSockets?.() ?? [], ...this.sockets.keys()]);
+		const heldTranscriptSockets = new Set(this.transcript?.webSockets() ?? []);
+		this.transcript?.onPublished(event, [...heldTranscriptSockets]);
+		const webSockets = /* @__PURE__ */ new Set([
+			...this.options.getWebSockets?.() ?? [],
+			...this.sockets.keys(),
+			...this.transcript?.webSockets() ?? []
+		]);
 		const deliveries = [];
+		const transcriptSockets = [];
 		for (const webSocket of webSockets) {
 			const state = await this.restore(webSocket);
-			if (state === void 0) continue;
+			if (state === "transcript") {
+				transcriptSockets.push(webSocket);
+				continue;
+			}
+			if (state === void 0 || state === "closed") continue;
 			deliveries.push(this.enqueue(webSocket, state, async () => {
 				if (event.event.durability !== "durable") {
 					await this.interpret(webSocket, state, onEphemeralEvent(state.delivery, event, Date.now()));
@@ -1111,16 +1669,28 @@ var EDAWebSocketConnectionManager = class {
 				await this.readAndDeliver(webSocket, state, state.delivery.sentDurableThroughSeq);
 			}));
 		}
+		this.transcript?.serveRestored(transcriptSockets.filter((webSocket) => !heldTranscriptSockets.has(webSocket)));
 		await Promise.all(deliveries);
 	}
 	async restore(webSocket) {
 		const existing = this.sockets.get(webSocket);
 		if (existing !== void 0) return existing;
+		if (this.transcript?.has(webSocket) === true) return "transcript";
 		const decoded = await decodeWebSocketAttachment(webSocket.deserializeAttachment());
 		if (decoded._tag !== "Decoded") {
 			this.close(webSocket, EDA_WS_CLOSE_PROTOCOL_ERROR, "protocol");
 			return;
 		}
+		const restoredMeanwhile = this.sockets.get(webSocket);
+		if (restoredMeanwhile !== void 0) return restoredMeanwhile;
+		if (this.transcript?.has(webSocket) === true) return "transcript";
+		if (decoded.attachment.kind === "eda-transcript-v1") {
+			if (this.transcript === void 0) {
+				this.close(webSocket, EDA_WS_CLOSE_PROTOCOL_ERROR, "protocol");
+				return;
+			}
+			return this.transcript.restore(webSocket, decoded.attachment) ? "transcript" : "closed";
+		}
 		const attachment = decoded.attachment;
 		const projectionState = attachment.projection === void 0 ? void 0 : await this.decodeProjectionState(attachment.projection.id, attachment.projection.state);
 		if (attachment.projection !== void 0 && projectionState === void 0) {
@@ -1328,7 +1898,8 @@ var EDASessionController = class {
 				"eda.seq.after": afterSeq
 			})))),
 			webSocketProjection: options.webSocketProjection,
-			webSocketProtocol: options.webSocketProtocol
+			webSocketProtocol: options.webSocketProtocol,
+			...options.transcriptSockets === void 0 ? {} : { transcript: options.transcriptSockets }
 		});
 		this.runtime = new EDASessionRuntime({
 			...options,
@@ -1415,6 +1986,21 @@ var EDASessionController = class {
 	acceptPreparedEventWebSocket(input) {
 		return this.webSockets.accept(input);
 	}
+	/** Whether transcript-window sockets are served. */
+	get supportsTranscriptWebSocket() {
+		return this.webSockets.supportsTranscript;
+	}
+	/**
+	* Register a transcript-window socket right after the host accepted it. Never prepares the
+	* model runtime: windows are storage-level reads.
+	*/
+	acceptTranscriptWebSocket(input) {
+		this.webSockets.acceptTranscript({
+			sessionId: input.sessionId,
+			trace: input.trace ?? makeRootEDATraceMetadata(),
+			webSocket: input.webSocket
+		});
+	}
 	webSocketMessage(webSocket, message) {
 		return this.webSockets.message(webSocket, message);
 	}
@@ -1426,6 +2012,7 @@ var EDASessionController = class {
 	}
 	async destroy(_input) {
 		await this.runtime.destroy();
+		this.webSockets.resetTranscript();
 	}
 	async alarm(input) {
 		if (input !== void 0) await this.prepareSession(input.sessionId);
@@ -1460,6 +2047,6 @@ const hostSpanOptions = (trace, attributes) => ({
 	...trace.parent === null ? {} : { parent: toEdaExternalSpan(trace.parent) }
 });
 //#endregion
-export { EDAWebSocketProjectionId as n, makeEDADurableObjectRuntimeLayer as r, EDASessionController as t };
+export { makeEDADurableObjectRuntimeLayer as i, defaultActiveContentCadenceMs as n, EDAWebSocketProjectionId as r, EDASessionController as t };
 
-//# sourceMappingURL=session-controller-BGfz1DdS.js.map
+//# sourceMappingURL=session-controller-BnNMF12R.js.map