@tanstack/ai-durable-stream 0.0.0

package/dist/esm/durable-stream.d.ts

@@ -0,0 +1,83 @@
+import { StreamDurability } from '@tanstack/ai';
+declare const durableStreamCursorBrand: unique symbol;
+/** A validated, versioned offset produced by this adapter. */
+type DurableStreamCursor = string & {
+    readonly [durableStreamCursorBrand]: true;
+};
+/** Adapter offsets also include the Durable Streams protocol sentinels. */
+export type DurableStreamOffset = DurableStreamCursor | '-1' | 'now';
+export interface DurableStreamOptions {
+    /**
+     * Base URL of the Durable Streams server (no trailing slash needed).
+     * Optional when `fetch` is supplied — e.g. a Cloudflare service binding that
+     * ignores the host and dispatches to the bound Worker by path — in which case
+     * an internal placeholder base is used and only the `/streams/...` path
+     * matters.
+     */
+    server?: string;
+    /** Stream-name prefix. Defaults to `runs`. */
+    streamPrefix?: string;
+    /** Fetch implementation. Defaults to the global fetch. */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Headers applied to every create, append, read, and close request. A
+     * resolver is called for every request so credentials can rotate.
+     */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /**
+     * Bounding for the read reconnect loop. After a response-body read failure
+     * mid-window, `read` retries from the last valid position; these cap
+     * consecutive retries and throttle them so a persistently failing backend
+     * surfaces the error instead of looping without end. Normal window
+     * advancement (long-poll) is never throttled.
+     */
+    reconnect?: {
+        /**
+         * Consecutive body-read-failure retries before surfacing the underlying
+         * read error. Default 10.
+         */
+        maxReadFailures?: number;
+        /** Delay between read retries, in ms. Default 250. */
+        delayMs?: number;
+    };
+    /**
+     * Timeout (ms) for a single create / append / close request to the backend.
+     * A stalled backend would otherwise hang chunk delivery or terminalization
+     * indefinitely. Default 30000. Long-poll `read` window advancement is NOT
+     * bounded by this — a caught-up reader may legitimately wait. `snapshot`,
+     * which must always return, IS bounded by it.
+     */
+    operationTimeoutMs?: number;
+    /**
+     * Producer fencing epoch sent as `Producer-Epoch` on every append.
+     *
+     * A backend that fences producers rejects an append whose epoch is below the
+     * highest it has seen, so a zombie host that lost its claim cannot keep
+     * writing to a run a newer host took over. Callers that track a monotonic
+     * per-run driver epoch (`RunRecord.driverEpoch`) should pass it here; the
+     * default of `0` makes every producer look equally current to the backend,
+     * which leaves fencing entirely to the caller's own run claim.
+     */
+    producerEpoch?: number;
+}
+export declare class DurableStreamError extends Error {
+    name: string;
+    constructor(message: string);
+}
+/**
+ * External-URL Durable Streams protocol adapter.
+ *
+ * `request` must name a run — `X-Run-Id` header (what a `@tanstack/ai-client`
+ * POST sends) or `?runId` (what a GET attach sends), resolved by core's
+ * `resolveResumeRunId`. A request that names neither throws rather than
+ * silently producing into an unaddressable stream.
+ *
+ * Returns a plain `StreamDurability`, not an `UpsertableStreamDurability`.
+ * This adapter's offsets embed a backend-assigned Next-Offset cursor, so a
+ * caller cannot choose them; there is no `upsert` implementation to supply.
+ * Omitting `upsert` is the type-level statement that this adapter does not
+ * support caller-supplied offsets, so a consumer requiring that capability
+ * gets a compile error at the wiring site instead of a runtime failure.
+ */
+export declare function durableStream(request: Request, options: DurableStreamOptions): StreamDurability<DurableStreamOffset>;
+export {};

package/dist/esm/durable-stream.js

@@ -0,0 +1,577 @@
+import { resolveResumeRunId } from "@tanstack/ai";
+//#region src/durable-stream.ts
+/** Resolve after `ms`, or immediately once `signal` aborts. Never rejects. */
+function abortableDelay(ms, signal) {
+	if (ms <= 0 || signal?.aborted) return Promise.resolve();
+	return new Promise((resolve) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			resolve();
+		};
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+var DurableStreamError = class extends Error {
+	name = "DurableStreamError";
+	constructor(message) {
+		super(`durableStream: ${message}`);
+	}
+};
+var CURSOR_PREFIX = "tanstack-ai-ds:v1:";
+var READ_ABORTED = Symbol("read aborted");
+/**
+* Hard ceiling on the SSE windows a single `snapshot` will pull before it gives
+* up. A snapshot stops at the first control frame that reports the reader caught
+* up (`upToDate`), so a conforming backend ends it in one or two windows. This
+* only fires for a backend that keeps handing out advancing windows without ever
+* reporting `upToDate`, where the alternative is a read that never returns.
+*/
+var SNAPSHOT_MAX_WINDOWS = 1e3;
+var ResponseBodyReadFailure = class extends Error {
+	readError;
+	name = "ResponseBodyReadFailure";
+	constructor(readError) {
+		super("response body read failed");
+		this.readError = readError;
+	}
+};
+function assertTransportField(value, name) {
+	if (value.trim().length === 0 || /[\r\n]/.test(value)) throw new DurableStreamError(`${name} must be non-empty and contain no CR/LF`);
+	return value;
+}
+function assertRunId(value) {
+	return assertTransportField(value, "runId");
+}
+function isDurableStreamCursor(value) {
+	return value.startsWith(CURSOR_PREFIX);
+}
+function isCursorPayload(value) {
+	return typeof value === "object" && value !== null && "v" in value && value.v === 1 && "backendOffset" in value && typeof value.backendOffset === "string" && "seq" in value && typeof value.seq === "number" && Number.isSafeInteger(value.seq) && value.seq > 0;
+}
+function encodeCursor(payload) {
+	assertTransportField(payload.backendOffset, "backend offset");
+	if (!Number.isSafeInteger(payload.seq) || payload.seq < 1) throw new DurableStreamError(`invalid record sequence: ${payload.seq}`);
+	const cursor = `${CURSOR_PREFIX}${encodeURIComponent(JSON.stringify(payload))}`;
+	if (!isDurableStreamCursor(cursor)) throw new DurableStreamError("failed to encode cursor");
+	return cursor;
+}
+function decodeCursor(cursor) {
+	if (!isDurableStreamCursor(cursor)) throw new DurableStreamError("invalid or unsupported resume offset");
+	let parsed;
+	try {
+		parsed = JSON.parse(decodeURIComponent(cursor.slice(18)));
+	} catch {
+		throw new DurableStreamError("invalid or unsupported resume offset");
+	}
+	if (!isCursorPayload(parsed)) throw new DurableStreamError("invalid or unsupported resume offset");
+	assertTransportField(parsed.backendOffset, "backend offset");
+	return parsed;
+}
+function safeSearchParam(request, key) {
+	try {
+		return new URL(request.url).searchParams.get(key);
+	} catch {
+		return null;
+	}
+}
+function parseResumeOffset(raw) {
+	if (raw === null || raw === "-1" || raw === "now") return raw;
+	decodeCursor(raw);
+	if (!isDurableStreamCursor(raw)) throw new DurableStreamError("invalid or unsupported resume offset");
+	return raw;
+}
+async function* readLines(body, signal) {
+	const reader = body.getReader();
+	const decoder = new TextDecoder();
+	let buffer = "";
+	let completed = false;
+	let cancelled = false;
+	let readFailed = false;
+	try {
+		for (;;) {
+			let result;
+			try {
+				result = await readWithAbort(reader, signal);
+			} catch (error) {
+				readFailed = true;
+				throw new ResponseBodyReadFailure(error);
+			}
+			if (result === READ_ABORTED) {
+				cancelled = true;
+				await reader.cancel(signal?.reason);
+				return;
+			}
+			if (result.done) {
+				completed = true;
+				break;
+			}
+			buffer += decoder.decode(result.value, { stream: true });
+			const parts = buffer.split("\n");
+			buffer = parts.pop() ?? "";
+			for (const raw of parts) yield raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+		}
+		buffer += decoder.decode();
+		if (buffer.length > 0) yield buffer.endsWith("\r") ? buffer.slice(0, -1) : buffer;
+	} finally {
+		try {
+			if (!completed && !cancelled && !readFailed) await reader.cancel();
+		} finally {
+			reader.releaseLock();
+		}
+	}
+}
+function readWithAbort(reader, signal) {
+	if (!signal) return reader.read();
+	if (signal.aborted) return Promise.resolve(READ_ABORTED);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(READ_ABORTED);
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		reader.read().then((result) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(result);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(error);
+		});
+	});
+}
+async function* parseSseEvents(body, signal) {
+	let current = {};
+	let hasField = false;
+	for await (const line of readLines(body, signal)) {
+		if (line === "") {
+			if (hasField) yield current;
+			current = {};
+			hasField = false;
+			continue;
+		}
+		if (line.startsWith(":")) continue;
+		const colon = line.indexOf(":");
+		const field = colon === -1 ? line : line.slice(0, colon);
+		let value = colon === -1 ? "" : line.slice(colon + 1);
+		if (value.startsWith(" ")) value = value.slice(1);
+		if (field === "event") {
+			current.event = value;
+			hasField = true;
+		} else if (field === "data") {
+			current.data = current.data === void 0 ? value : `${current.data}\n${value}`;
+			hasField = true;
+		}
+	}
+	if (hasField) yield current;
+}
+function isStreamChunk(value) {
+	return typeof value === "object" && value !== null && "type" in value && typeof value.type === "string";
+}
+function isWireRecord(value) {
+	return typeof value === "object" && value !== null && "v" in value && value.v === 1 && "seq" in value && typeof value.seq === "number" && Number.isSafeInteger(value.seq) && value.seq > 0 && "chunk" in value && isStreamChunk(value.chunk);
+}
+function parseDataRecords(data) {
+	if (data === void 0) throw new DurableStreamError("data event had no payload");
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		throw new DurableStreamError("data event contained invalid JSON");
+	}
+	if (!Array.isArray(parsed)) throw new DurableStreamError("data event payload must be a JSON array");
+	const records = [];
+	for (const value of parsed) {
+		if (!isWireRecord(value)) throw new DurableStreamError("data event contained an invalid record");
+		records.push(value);
+	}
+	return records;
+}
+function optionalBoolean(value, name) {
+	const field = name === "upToDate" ? "upToDate" in value ? value.upToDate : void 0 : "streamClosed" in value ? value.streamClosed : void 0;
+	if (field === void 0) return void 0;
+	if (typeof field !== "boolean") throw new DurableStreamError(`control field ${name} must be boolean`);
+	return field;
+}
+function parseControlFrame(data) {
+	if (data === void 0) throw new DurableStreamError("control event had no payload");
+	let parsed;
+	try {
+		parsed = JSON.parse(data);
+	} catch {
+		throw new DurableStreamError("control event contained invalid JSON");
+	}
+	if (typeof parsed !== "object" || parsed === null) throw new DurableStreamError("control event payload must be an object");
+	if (!("streamNextOffset" in parsed) || typeof parsed.streamNextOffset !== "string") throw new DurableStreamError("control event requires string streamNextOffset");
+	const streamNextOffset = assertTransportField(parsed.streamNextOffset, "control streamNextOffset");
+	let streamCursor;
+	if ("streamCursor" in parsed) {
+		if (typeof parsed.streamCursor !== "string") throw new DurableStreamError("control streamCursor must be a string");
+		streamCursor = assertTransportField(parsed.streamCursor, "control streamCursor");
+	}
+	const upToDate = optionalBoolean(parsed, "upToDate");
+	const streamClosed = optionalBoolean(parsed, "streamClosed");
+	if (streamClosed !== true && streamCursor === void 0) throw new DurableStreamError("open control event requires string streamCursor");
+	return {
+		streamNextOffset,
+		...streamCursor === void 0 ? {} : { streamCursor },
+		...upToDate === void 0 ? {} : { upToDate },
+		...streamClosed === void 0 ? {} : { streamClosed }
+	};
+}
+function requireNextOffset(response, operation) {
+	const offset = response.headers.get("Stream-Next-Offset");
+	if (offset === null || offset.trim().length === 0) throw new DurableStreamError(`${operation} response missing non-empty Stream-Next-Offset`);
+	return assertTransportField(offset, `${operation} Stream-Next-Offset`);
+}
+function httpFailure(operation, response) {
+	return new DurableStreamError(`failed to ${operation} (${response.status} ${response.statusText})`);
+}
+/**
+* External-URL Durable Streams protocol adapter.
+*
+* `request` must name a run — `X-Run-Id` header (what a `@tanstack/ai-client`
+* POST sends) or `?runId` (what a GET attach sends), resolved by core's
+* `resolveResumeRunId`. A request that names neither throws rather than
+* silently producing into an unaddressable stream.
+*
+* Returns a plain `StreamDurability`, not an `UpsertableStreamDurability`.
+* This adapter's offsets embed a backend-assigned Next-Offset cursor, so a
+* caller cannot choose them; there is no `upsert` implementation to supply.
+* Omitting `upsert` is the type-level statement that this adapter does not
+* support caller-supplied offsets, so a consumer requiring that capability
+* gets a compile error at the wiring site instead of a runtime failure.
+*/
+function durableStream(request, options) {
+	const fetchFn = options.fetch ?? globalThis.fetch;
+	if (options.server === void 0 && options.fetch === void 0) throw new DurableStreamError("server is required unless a fetch implementation is provided");
+	const rawServer = options.server ?? "https://durable-streams.internal";
+	assertTransportField(rawServer, "server URL");
+	try {
+		new URL(rawServer);
+	} catch {
+		throw new DurableStreamError(`invalid server URL: ${JSON.stringify(rawServer)}`);
+	}
+	const server = rawServer.replace(/\/+$/, "");
+	const maxReadFailures = options.reconnect?.maxReadFailures ?? 10;
+	const readRetryDelayMs = options.reconnect?.delayMs ?? 250;
+	const operationTimeoutMs = options.operationTimeoutMs ?? 3e4;
+	const fetchWithTimeout = async (url, init) => {
+		const controller = new AbortController();
+		const timer = setTimeout(() => {
+			controller.abort(new DurableStreamError(`request exceeded operationTimeoutMs (${operationTimeoutMs}ms)`));
+		}, operationTimeoutMs);
+		try {
+			return await fetchFn(url, {
+				...init,
+				signal: controller.signal
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	const prefix = assertTransportField(options.streamPrefix ?? "runs", "streamPrefix");
+	const resumeOffset = parseResumeOffset(request.headers.get("Last-Event-ID") ?? safeSearchParam(request, "offset"));
+	const requestedRunId = resolveResumeRunId(request);
+	if (requestedRunId === null) throw new DurableStreamError(resumeOffset === null ? "a runId is required: send it as an X-Run-Id header or a ?runId query param" : "resume offset requires a runId");
+	const runId = assertRunId(requestedRunId);
+	const streamUrl = `${server}/streams/${encodeURIComponent(`${prefix}/${runId}`)}`;
+	let createPromise;
+	let createdHere = false;
+	let appendTailOffset;
+	let nextSeq = 1;
+	let seqSeeded = false;
+	let seedPromise;
+	const producerId = crypto.randomUUID();
+	const producerEpoch = options.producerEpoch ?? 0;
+	if (!Number.isSafeInteger(producerEpoch) || producerEpoch < 0) throw new DurableStreamError(`producerEpoch must be a non-negative safe integer: ${producerEpoch}`);
+	let producerSeq = 0;
+	let closePromise;
+	/**
+	* Raise the append counter past a sequence already present in the log.
+	*
+	* Called for every record any read observes — including records the reader
+	* then dedups away — so both `snapshot` (the alignment path a takeover
+	* already runs) and a plain `read` teach this instance the log's tail.
+	*/
+	const observeSeq = (seq) => {
+		if (seq >= nextSeq) nextSeq = seq + 1;
+	};
+	const resolveHeaders = async (required) => {
+		const configured = typeof options.headers === "function" ? await options.headers() : options.headers;
+		const headers = new Headers(configured);
+		if (required) new Headers(required).forEach((value, key) => headers.set(key, value));
+		return headers;
+	};
+	const ensureCreated = () => {
+		if (createPromise) return createPromise;
+		createPromise = (async () => {
+			const response = await fetchWithTimeout(streamUrl, {
+				method: "PUT",
+				headers: await resolveHeaders({ "Content-Type": "application/json" })
+			});
+			if (!response.ok) throw httpFailure("create stream", response);
+			const offset = requireNextOffset(response, "create");
+			createdHere = response.status === 201;
+			appendTailOffset = offset;
+			return offset;
+		})().catch((error) => {
+			createPromise = void 0;
+			throw error;
+		});
+		return createPromise;
+	};
+	/**
+	* The one window-pulling loop behind both `read` and `snapshot`.
+	*
+	* `stopWhenUpToDate` is the only difference between them. The protocol's
+	* control frame carries `upToDate: true` when the backend has handed the
+	* reader everything the stream currently holds; a live `read` ignores that and
+	* keeps long-polling for more, while a `snapshot` returns there. That makes a
+	* snapshot bounded even on a stream nobody ever closed.
+	*/
+	const readWindows = async function* (offset, signal, stopWhenUpToDate) {
+		let backendOffset;
+		let deliveredThroughSeq = 0;
+		if (offset === "-1" || offset === "now") backendOffset = offset;
+		else {
+			const cursor = decodeCursor(offset);
+			backendOffset = cursor.backendOffset;
+			deliveredThroughSeq = cursor.seq;
+		}
+		let streamCursor;
+		let consecutiveReadFailures = 0;
+		let windowsPulled = 0;
+		for (;;) {
+			if (signal?.aborted) return;
+			windowsPulled += 1;
+			if (stopWhenUpToDate && windowsPulled > SNAPSHOT_MAX_WINDOWS) throw new DurableStreamError(`snapshot read ${SNAPSHOT_MAX_WINDOWS} windows without the backend reporting upToDate`);
+			const requestOffset = backendOffset;
+			const requestCursor = streamCursor;
+			const url = new URL(streamUrl);
+			url.searchParams.set("offset", backendOffset);
+			url.searchParams.set("live", "sse");
+			if (streamCursor !== void 0) url.searchParams.set("cursor", streamCursor);
+			let response;
+			try {
+				response = await fetchFn(url, {
+					method: "GET",
+					headers: await resolveHeaders(),
+					signal
+				});
+			} catch (error) {
+				if (signal?.aborted) return;
+				throw error;
+			}
+			if (!response.ok) throw httpFailure("read", response);
+			if (!response.body) throw new DurableStreamError("read response had no body");
+			let dataStartOffset = backendOffset;
+			let sawControl = false;
+			let dataAwaitingControl = false;
+			let yieldedData = false;
+			let previousResponseSeq = 0;
+			try {
+				for await (const event of parseSseEvents(response.body, signal)) {
+					if (signal?.aborted) return;
+					if (event.event === "data") {
+						dataAwaitingControl = true;
+						for (const record of parseDataRecords(event.data)) {
+							if (record.seq <= previousResponseSeq) throw new DurableStreamError("data records must have strictly increasing sequences");
+							previousResponseSeq = record.seq;
+							observeSeq(record.seq);
+							if (record.seq <= deliveredThroughSeq) continue;
+							deliveredThroughSeq = record.seq;
+							yieldedData = true;
+							yield {
+								offset: encodeCursor({
+									v: 1,
+									backendOffset: dataStartOffset,
+									seq: record.seq
+								}),
+								chunk: record.chunk
+							};
+						}
+						continue;
+					}
+					if (event.event === "control") {
+						const control = parseControlFrame(event.data);
+						backendOffset = control.streamNextOffset;
+						streamCursor = control.streamCursor;
+						dataStartOffset = backendOffset;
+						sawControl = true;
+						dataAwaitingControl = false;
+						if (control.streamClosed === true) return;
+						if (stopWhenUpToDate && control.upToDate === true) return;
+						continue;
+					}
+					throw new DurableStreamError(`unexpected SSE event type: ${JSON.stringify(event.event)}`);
+				}
+			} catch (error) {
+				if (signal?.aborted) return;
+				if (error instanceof ResponseBodyReadFailure) {
+					if (yieldedData || sawControl && (backendOffset !== requestOffset || streamCursor !== requestCursor)) {
+						consecutiveReadFailures += 1;
+						if (consecutiveReadFailures > maxReadFailures) throw error.readError;
+						await abortableDelay(readRetryDelayMs, signal);
+						continue;
+					}
+					throw error.readError;
+				}
+				throw error;
+			}
+			consecutiveReadFailures = 0;
+			if (signal?.aborted) return;
+			if (dataAwaitingControl || !sawControl) throw new DurableStreamError("read SSE window ended without a matching control event");
+			if (backendOffset === requestOffset && streamCursor === requestCursor) throw new DurableStreamError("read SSE window ended without advancing offset or cursor");
+		}
+	};
+	/**
+	* One bounded pass over everything the log currently holds.
+	*
+	* Two things bound it. `readWindows(..., stopWhenUpToDate=true)` returns at
+	* the first control frame reporting the reader caught up, and
+	* `SNAPSHOT_MAX_WINDOWS` catches a backend that keeps handing out advancing
+	* windows without ever saying so. Neither covers a backend that simply never
+	* answers — `upToDate` is an optional protocol field, read windows
+	* deliberately skip `fetchWithTimeout` (a caught-up live reader may wait),
+	* and an empty still-open log has nothing to send. That shape would park the
+	* fetch forever, so the snapshot carries its own `operationTimeoutMs`
+	* deadline. Timing out is a loud failure, never a truncated result: an
+	* aborted `readWindows` ends its iteration quietly, so the flag is rechecked
+	* after the loop and thrown.
+	*
+	* `ensureCreated()` first, exactly as `append` and `read` do. A snapshot of a
+	* stream the backend does not hold yet must answer "nothing has been
+	* delivered", not reject: `sandboxRunDriver`'s `pipe` calls
+	* `awaitLogQuiescence` — two `snapshot()` reads — BEFORE the first append, so
+	* the very first producer of every durable run snapshots a stream no `PUT` has
+	* created. Reading straight through would surface that as
+	* `httpFailure('read', ...)` and fail the run at its first chunk. It also keeps
+	* this adapter's contract identical to core's `memoryStream`, which resolves to
+	* `[]` for an unknown run; two `StreamDurability` implementations must not
+	* disagree about so basic a case. `ensureCreated` is idempotent and memoised,
+	* so this costs nothing once the stream exists.
+	*/
+	const collectSnapshot = async () => {
+		await ensureCreated();
+		const controller = new AbortController();
+		let timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			controller.abort(new DurableStreamError(`snapshot exceeded operationTimeoutMs (${operationTimeoutMs}ms)`));
+		}, operationTimeoutMs);
+		try {
+			const entries = [];
+			for await (const entry of readWindows("-1", controller.signal, true)) entries.push(entry);
+			if (timedOut) throw new DurableStreamError(`snapshot exceeded operationTimeoutMs (${operationTimeoutMs}ms) before the backend reported upToDate`);
+			seqSeeded = true;
+			return entries;
+		} finally {
+			clearTimeout(timer);
+		}
+	};
+	/**
+	* Learn where the log ends before this instance appends to it for the first
+	* time.
+	*
+	* A takeover host is handed a fresh adapter for a run whose log already holds
+	* `seq 1..N`, and nothing in the protocol reports a record count, so the tail
+	* has to be read. One bounded read per instance, and the alignment `snapshot()`
+	* a takeover already performs satisfies it.
+	*
+	* A brand-new run pays nothing, and must not: the seeding read cannot be on the
+	* producer's critical path. `upToDate` is an optional protocol field and an
+	* empty still-open log has nothing to send, so on a backend that omits it the
+	* read has to run its `operationTimeoutMs` deadline out and then fail — the
+	* producer would wait on a reader that is waiting on the producer, and every
+	* fresh run on such a backend would die of a synthetic error. `createdHere`
+	* settles it without a request: a stream this instance brought into existence
+	* provably holds no records, so `nextSeq` is already correct at 1.
+	*/
+	const ensureSeqSeeded = () => {
+		if (seqSeeded) return Promise.resolve();
+		if (seedPromise) return seedPromise;
+		seedPromise = (async () => {
+			await ensureCreated();
+			if (createdHere) {
+				seqSeeded = true;
+				return;
+			}
+			await collectSnapshot();
+		})().catch((error) => {
+			seedPromise = void 0;
+			throw error;
+		});
+		return seedPromise;
+	};
+	return {
+		resumeFrom: () => resumeOffset,
+		append: async (chunks) => {
+			if (chunks.length === 0) return [];
+			await ensureSeqSeeded();
+			const batchStartOffset = appendTailOffset ?? await ensureCreated();
+			const firstSeq = nextSeq;
+			const records = chunks.map((chunk, index) => ({
+				v: 1,
+				seq: firstSeq + index,
+				chunk
+			}));
+			observeSeq(firstSeq + records.length - 1);
+			const requestProducerSeq = producerSeq;
+			producerSeq += 1;
+			const requestInit = {
+				method: "POST",
+				headers: await resolveHeaders({
+					"Content-Type": "application/json",
+					"Producer-Id": producerId,
+					"Producer-Epoch": String(producerEpoch),
+					"Producer-Seq": String(requestProducerSeq)
+				}),
+				body: JSON.stringify(records)
+			};
+			let response;
+			try {
+				response = await fetchWithTimeout(streamUrl, requestInit);
+			} catch (firstError) {
+				try {
+					response = await fetchWithTimeout(streamUrl, requestInit);
+				} catch (retryError) {
+					throw new AggregateError([firstError, retryError], "durableStream: append failed before its outcome could be confirmed");
+				}
+			}
+			if (!response.ok) throw httpFailure("append", response);
+			appendTailOffset = requireNextOffset(response, "append");
+			return records.map((record) => encodeCursor({
+				v: 1,
+				backendOffset: batchStartOffset,
+				seq: record.seq
+			}));
+		},
+		close: () => {
+			if (closePromise) return closePromise;
+			closePromise = (async () => {
+				await ensureCreated();
+				const response = await fetchWithTimeout(streamUrl, {
+					method: "POST",
+					headers: await resolveHeaders({ "Stream-Closed": "true" })
+				});
+				if (!response.ok) throw httpFailure("close", response);
+				const nextOffset = requireNextOffset(response, "close");
+				if (response.headers.get("Stream-Closed")?.toLowerCase() !== "true") throw new DurableStreamError("close response missing Stream-Closed: true");
+				appendTailOffset = nextOffset;
+			})().catch((error) => {
+				closePromise = void 0;
+				throw error;
+			});
+			return closePromise;
+		},
+		read: (offset, signal) => readWindows(offset, signal, false),
+		snapshot: () => collectSnapshot()
+	};
+}
+//#endregion
+export { DurableStreamError, durableStream };
+
+//# sourceMappingURL=durable-stream.js.map