@durable-streams/server 0.3.2 → 0.3.4

package/dist/index.cjs

@@ -24,13 +24,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const node_http = __toESM(require("node:http"));
 const node_zlib = __toESM(require("node:zlib"));
+const __durable_streams_client = __toESM(require("@durable-streams/client"));
 const node_fs = __toESM(require("node:fs"));
 const node_path = __toESM(require("node:path"));
 const node_crypto = __toESM(require("node:crypto"));
 const lmdb = __toESM(require("lmdb"));
 const __neophi_sieve_cache = __toESM(require("@neophi/sieve-cache"));
-const node_fs_promises = __toESM(require("node:fs/promises"));
-const __durable_streams_client = __toESM(require("@durable-streams/client"));
+const node_net = __toESM(require("node:net"));
 const __durable_streams_state = __toESM(require("@durable-streams/state"));
 
 //#region src/store.ts
@@ -73,17 +73,35 @@ function processJsonAppend(data, isInitialCreate = false) {
 	} else result = JSON.stringify(parsed) + `,`;
 	return new TextEncoder().encode(result);
 }
-/**
-* Format JSON mode response by wrapping in array brackets.
-* Strips trailing comma before wrapping.
-*/
-function formatJsonResponse(data) {
-	if (data.length === 0) return new TextEncoder().encode(`[]`);
-	let text = new TextDecoder().decode(data);
-	text = text.trimEnd();
+function decodeStoredJsonMessage(data) {
+	let text = new TextDecoder().decode(data).trimEnd();
 	if (text.endsWith(`,`)) text = text.slice(0, -1);
-	const wrapped = `[${text}]`;
-	return new TextEncoder().encode(wrapped);
+	return text;
+}
+function enrichJsonValueWithOffset(parsed, offset) {
+	if (!parsed || typeof parsed !== `object` || Array.isArray(parsed)) return JSON.stringify(parsed);
+	const candidate = parsed;
+	const headers = candidate.headers;
+	if (!headers || typeof headers !== `object`) return JSON.stringify(parsed);
+	const isStateChange = typeof headers.operation === `string`;
+	const isStateControl = typeof headers.control === `string`;
+	if (!isStateChange && !isStateControl) return JSON.stringify(parsed);
+	return JSON.stringify({
+		...candidate,
+		headers: {
+			...headers,
+			offset
+		}
+	});
+}
+function formatJsonMessages(messages) {
+	if (messages.length === 0) return new TextEncoder().encode(`[]`);
+	const items = messages.flatMap((message) => {
+		const rawFragment = decodeStoredJsonMessage(message.data);
+		const parsed = JSON.parse(`[${rawFragment}]`);
+		return parsed.map((value) => enrichJsonValueWithOffset(value, message.offset));
+	});
+	return new TextEncoder().encode(`[${items.join(`,`)}]`);
 }
 var StreamStore = class {
 	streams = new Map();
@@ -621,6 +639,7 @@ var StreamStore = class {
 	formatResponse(path, messages) {
 		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
+		if (normalizeContentType(stream.contentType) === `application/json`) return formatJsonMessages(messages);
 		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
 		const concatenated = new Uint8Array(totalSize);
 		let offset = 0;
@@ -628,7 +647,6 @@ var StreamStore = class {
 			concatenated.set(msg.data, offset);
 			offset += msg.data.length;
 		}
-		if (normalizeContentType(stream.contentType) === `application/json`) return formatJsonResponse(concatenated);
 		return concatenated;
 	}
 	/**
@@ -728,7 +746,8 @@ var StreamStore = class {
 		const parts = stream.currentOffset.split(`_`).map(Number);
 		const readSeq = parts[0];
 		const byteOffset = parts[1];
-		const newByteOffset = byteOffset + processedData.length;
+		const FRAME_OVERHEAD = 5;
+		const newByteOffset = byteOffset + FRAME_OVERHEAD + processedData.length;
 		const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
 		const message = {
 			data: processedData,
@@ -772,6 +791,48 @@ var StreamStore = class {
 	}
 };
 
+//#endregion
+//#region src/log.ts
+const streamsLogFile = process.env.STREAMS_LOG_FILE;
+async function appendLogLine(line) {
+	if (!streamsLogFile) return;
+	const fs = await import(`node:fs/promises`);
+	const path = await import(`node:path`);
+	await fs.mkdir(path.dirname(streamsLogFile), { recursive: true });
+	await fs.appendFile(streamsLogFile, `${line}\n`);
+}
+function serializeArg(arg) {
+	if (arg instanceof Error) return arg.stack ?? arg.message;
+	if (typeof arg === `string`) return arg;
+	try {
+		return JSON.stringify(arg);
+	} catch {
+		return String(arg);
+	}
+}
+function write(level, args) {
+	const line = args.map(serializeArg).join(` `);
+	const formatted = `[${level}] ${line}`;
+	if (level === `error`) console.error(formatted);
+	else if (level === `warn`) console.warn(formatted);
+	else console.info(formatted);
+	appendLogLine(formatted).catch(() => void 0);
+}
+const serverLog = {
+	info(...args) {
+		write(`info`, args);
+	},
+	warn(...args) {
+		write(`warn`, args);
+	},
+	error(...args) {
+		write(`error`, args);
+	},
+	event(obj, msg) {
+		write(`info`, [msg, obj]);
+	}
+};
+
 //#endregion
 //#region src/path-encoding.ts
 const MAX_ENCODED_LENGTH = 200;
@@ -808,82 +869,6 @@ function decodeStreamPath(encoded) {
 	return Buffer.from(padded, `base64`).toString(`utf-8`);
 }
 
-//#endregion
-//#region src/file-manager.ts
-var StreamFileManager = class {
-	constructor(streamsDir) {
-		this.streamsDir = streamsDir;
-	}
-	/**
-	* Create a directory for a new stream and initialize the first segment file.
-	* Returns the absolute path to the stream directory.
-	*/
-	async createStreamDirectory(streamPath) {
-		const encoded = encodeStreamPath(streamPath);
-		const dir = node_path.join(this.streamsDir, encoded);
-		await node_fs_promises.mkdir(dir, { recursive: true });
-		const segmentPath = node_path.join(dir, `segment_00000.log`);
-		await node_fs_promises.writeFile(segmentPath, ``);
-		return dir;
-	}
-	/**
-	* Delete a stream directory and all its contents.
-	*/
-	async deleteStreamDirectory(streamPath) {
-		const encoded = encodeStreamPath(streamPath);
-		const dir = node_path.join(this.streamsDir, encoded);
-		await node_fs_promises.rm(dir, {
-			recursive: true,
-			force: true
-		});
-	}
-	/**
-	* Delete a directory by its exact name (used for unique directory names).
-	*/
-	async deleteDirectoryByName(directoryName) {
-		const dir = node_path.join(this.streamsDir, directoryName);
-		await node_fs_promises.rm(dir, {
-			recursive: true,
-			force: true
-		});
-	}
-	/**
-	* Get the absolute path to a stream's directory.
-	* Returns null if the directory doesn't exist.
-	*/
-	async getStreamDirectory(streamPath) {
-		const encoded = encodeStreamPath(streamPath);
-		const dir = node_path.join(this.streamsDir, encoded);
-		try {
-			await node_fs_promises.access(dir);
-			return dir;
-		} catch {
-			return null;
-		}
-	}
-	/**
-	* List all stream paths by scanning the streams directory.
-	*/
-	async listStreamPaths() {
-		try {
-			const entries = await node_fs_promises.readdir(this.streamsDir, { withFileTypes: true });
-			return entries.filter((e) => e.isDirectory()).map((e) => decodeStreamPath(e.name));
-		} catch {
-			return [];
-		}
-	}
-	/**
-	* Get the path to a segment file within a stream directory.
-	*
-	* @param streamDir - Absolute path to the stream directory
-	* @param index - Segment index (0-based)
-	*/
-	getSegmentPath(streamDir, index) {
-		const paddedIndex = String(index).padStart(5, `0`);
-		return node_path.join(streamDir, `segment_${paddedIndex}.log`);
-	}
-};
-
 //#endregion
 //#region src/file-store.ts
 var FileHandlePool = class {
@@ -891,7 +876,7 @@ var FileHandlePool = class {
 	constructor(maxSize) {
 		this.cache = new __neophi_sieve_cache.SieveCache(maxSize, { evictHook: (_key, handle) => {
 			this.closeHandle(handle).catch((err) => {
-				console.error(`[FileHandlePool] Error closing evicted handle:`, err);
+				serverLog.error(`[FileHandlePool] Error closing evicted handle:`, err);
 			});
 		} });
 	}
@@ -899,41 +884,70 @@ var FileHandlePool = class {
 		let handle = this.cache.get(filePath);
 		if (!handle) {
 			const stream = node_fs.createWriteStream(filePath, { flags: `a` });
-			handle = { stream };
+			handle = {
+				stream,
+				syncLeader: null
+			};
 			this.cache.set(filePath, handle);
 		}
 		return handle.stream;
 	}
 	/**
+	* Open a write stream eagerly so the first write does not pay the lazy
+	* `open()` stall. Resolves once the underlying fd is ready.
+	*/
+	async openWriteStream(filePath) {
+		const stream = this.getWriteStream(filePath);
+		const fd = stream.fd;
+		if (typeof fd === `number`) return stream;
+		await new Promise((resolve, reject) => {
+			stream.once(`open`, () => resolve());
+			stream.once(`error`, (err) => reject(err));
+		});
+		return stream;
+	}
+	/**
 	* Flush a specific file to disk immediately.
-	* This is called after each append to ensure durability.
+	* Concurrent callers on the same fd share one in-flight fdatasync: the
+	* first caller issues the syscall, later arrivals during that window wait
+	* for it to finish and then issue a fresh syscall (because their writes
+	* may have landed after the in-flight syscall started). This preserves
+	* durability without adding scheduling latency.
 	*/
-	async fsyncFile(filePath) {
+	fsyncFile(filePath) {
 		const handle = this.cache.get(filePath);
-		if (!handle) return;
-		return new Promise((resolve, reject) => {
-			const fd = handle.stream.fd;
-			if (typeof fd !== `number`) {
-				const onOpen = (openedFd) => {
-					handle.stream.off(`error`, onError);
-					node_fs.fdatasync(openedFd, (err) => {
-						if (err) reject(err);
-						else resolve();
-					});
-				};
-				const onError = (err) => {
-					handle.stream.off(`open`, onOpen);
-					reject(err);
-				};
-				handle.stream.once(`open`, onOpen);
-				handle.stream.once(`error`, onError);
-				return;
-			}
-			node_fs.fdatasync(fd, (err) => {
-				if (err) reject(err);
-				else resolve();
-			});
+		if (!handle) return Promise.reject(new Error(`[FileHandlePool] Cannot fsync: handle not found for ${filePath}`));
+		const existing = handle.syncLeader;
+		if (existing && existing.scheduled) return existing.promise;
+		let resolveFn;
+		let rejectFn;
+		const promise = new Promise((res, rej) => {
+			resolveFn = res;
+			rejectFn = rej;
 		});
+		const leader = {
+			promise,
+			scheduled: true
+		};
+		handle.syncLeader = leader;
+		const runSyscall = (fd$1) => {
+			leader.scheduled = false;
+			node_fs.fdatasync(fd$1, (err) => {
+				if (handle.syncLeader === leader) handle.syncLeader = null;
+				if (err) rejectFn(err);
+				else resolveFn();
+			});
+		};
+		const fd = handle.stream.fd;
+		if (typeof fd === `number`) runSyscall(fd);
+		else {
+			handle.stream.once(`open`, (openedFd) => runSyscall(openedFd));
+			handle.stream.once(`error`, (err) => {
+				if (handle.syncLeader === leader) handle.syncLeader = null;
+				rejectFn(err);
+			});
+		}
+		return promise;
 	}
 	async closeAll() {
 		const promises = [];
@@ -969,13 +983,15 @@ function generateUniqueDirectoryName(streamPath) {
 	const random = (0, node_crypto.randomBytes)(4).toString(`hex`);
 	return `${encoded}~${timestamp}~${random}`;
 }
+function segmentFile(dataDir, dirName) {
+	return node_path.join(dataDir, `streams`, `${dirName}.log`);
+}
 /**
 * File-backed implementation of StreamStore.
 * Maintains the same interface as the in-memory StreamStore for drop-in compatibility.
 */
 var FileBackedStreamStore = class {
 	db;
-	fileManager;
 	fileHandlePool;
 	pendingLongPolls = [];
 	dataDir;
@@ -995,9 +1011,12 @@ var FileBackedStreamStore = class {
 		this.dataDir = options.dataDir;
 		this.db = (0, lmdb.open)({
 			path: node_path.join(this.dataDir, `metadata.lmdb`),
-			compression: true
+			compression: true,
+			noMemInit: true,
+			cache: true,
+			sharedStructuresKey: Symbol.for(`structures`)
 		});
-		this.fileManager = new StreamFileManager(node_path.join(this.dataDir, `streams`));
+		node_fs.mkdirSync(node_path.join(this.dataDir, `streams`), { recursive: true });
 		const maxFileHandles = options.maxFileHandles ?? 100;
 		this.fileHandlePool = new FileHandlePool(maxFileHandles);
 		this.recover();
@@ -1007,7 +1026,7 @@ var FileBackedStreamStore = class {
 	* Validates that LMDB metadata matches actual file contents and reconciles any mismatches.
 	*/
 	recover() {
-		console.log(`[FileBackedStreamStore] Starting recovery...`);
+		serverLog.info(`[FileBackedStreamStore] Starting recovery...`);
 		let recovered = 0;
 		let reconciled = 0;
 		let errors = 0;
@@ -1020,9 +1039,9 @@ var FileBackedStreamStore = class {
 			if (typeof key !== `string`) continue;
 			const streamMeta = value;
 			const streamPath = key.replace(`stream:`, ``);
-			const segmentPath = node_path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
+			const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 			if (!node_fs.existsSync(segmentPath)) {
-				console.warn(`[FileBackedStreamStore] Recovery: Stream file missing for ${streamPath}, removing from LMDB`);
+				serverLog.warn(`[FileBackedStreamStore] Recovery: Stream file missing for ${streamPath}, removing from LMDB`);
 				this.db.removeSync(key);
 				errors++;
 				continue;
@@ -1036,7 +1055,7 @@ var FileBackedStreamStore = class {
 				trueOffset = `${String(0).padStart(16, `0`)}_${String(logicalBytes).padStart(16, `0`)}`;
 			} else trueOffset = physicalOffset;
 			if (trueOffset !== streamMeta.currentOffset) {
-				console.warn(`[FileBackedStreamStore] Recovery: Offset mismatch for ${streamPath}: LMDB says ${streamMeta.currentOffset}, file says ${trueOffset}. Reconciling to file.`);
+				serverLog.warn(`[FileBackedStreamStore] Recovery: Offset mismatch for ${streamPath}: LMDB says ${streamMeta.currentOffset}, file says ${trueOffset}. Reconciling to file.`);
 				const reconciledMeta = {
 					...streamMeta,
 					currentOffset: trueOffset
@@ -1046,10 +1065,10 @@ var FileBackedStreamStore = class {
 			}
 			recovered++;
 		} catch (err) {
-			console.error(`[FileBackedStreamStore] Error recovering stream:`, err);
+			serverLog.error(`[FileBackedStreamStore] Error recovering stream:`, err);
 			errors++;
 		}
-		console.log(`[FileBackedStreamStore] Recovery complete: ${recovered} streams, ${reconciled} reconciled, ${errors} errors`);
+		serverLog.info(`[FileBackedStreamStore] Recovery complete: ${recovered} streams, ${reconciled} reconciled, ${errors} errors`);
 	}
 	/**
 	* Scan a segment file to compute the true last offset.
@@ -1059,19 +1078,16 @@ var FileBackedStreamStore = class {
 		try {
 			const fileContent = node_fs.readFileSync(segmentPath);
 			let filePos = 0;
-			let currentDataOffset = 0;
 			while (filePos < fileContent.length) {
 				if (filePos + 4 > fileContent.length) break;
 				const messageLength = fileContent.readUInt32BE(filePos);
-				filePos += 4;
-				if (filePos + messageLength > fileContent.length) break;
-				filePos += messageLength;
-				if (filePos < fileContent.length) filePos += 1;
-				currentDataOffset += messageLength;
+				const frameEnd = filePos + 4 + messageLength + 1;
+				if (frameEnd > fileContent.length) break;
+				filePos = frameEnd;
 			}
-			return `0000000000000000_${String(currentDataOffset).padStart(16, `0`)}`;
+			return `0000000000000000_${String(filePos).padStart(16, `0`)}`;
 		} catch (err) {
-			console.error(`[FileBackedStreamStore] Error scanning file ${segmentPath}:`, err);
+			serverLog.error(`[FileBackedStreamStore] Error scanning file ${segmentPath}:`, err);
 			return `0000000000000000_0000000000000000`;
 		}
 	}
@@ -1339,6 +1355,7 @@ var FileBackedStreamStore = class {
 			effectiveTtlSeconds = resolved.ttlSeconds;
 		}
 		const key = `stream:${streamPath}`;
+		const t0 = performance.now();
 		const streamMeta = {
 			path: streamPath,
 			contentType,
@@ -1356,11 +1373,10 @@ var FileBackedStreamStore = class {
 			forkOffset: isFork ? forkOffset : void 0,
 			refCount: 0
 		};
-		const streamDir = node_path.join(this.dataDir, `streams`, streamMeta.directoryName);
+		const tAfterMeta = performance.now();
+		const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 		try {
-			node_fs.mkdirSync(streamDir, { recursive: true });
-			const segmentPath = node_path.join(streamDir, `segment_00000.log`);
-			node_fs.writeFileSync(segmentPath, ``);
+			await this.db.put(key, streamMeta);
 		} catch (err) {
 			if (isFork && sourceMeta) {
 				const sourceKey = `stream:${options.forkedFrom}`;
@@ -1373,10 +1389,18 @@ var FileBackedStreamStore = class {
 					this.db.putSync(sourceKey, updatedSource);
 				}
 			}
-			console.error(`[FileBackedStreamStore] Error creating stream directory:`, err);
+			serverLog.error(`[FileBackedStreamStore] Error creating stream (LMDB put):`, err);
+			throw err;
+		}
+		const tAfterLmdb = performance.now();
+		try {
+			await this.fileHandlePool.openWriteStream(segmentPath);
+		} catch (err) {
+			this.db.removeSync(key);
+			serverLog.error(`[FileBackedStreamStore] Error creating stream (file open):`, err);
 			throw err;
 		}
-		this.db.putSync(key, streamMeta);
+		const tAfterOpen = performance.now();
 		if (options.initialData && options.initialData.length > 0) try {
 			await this.append(streamPath, options.initialData, {
 				contentType: options.contentType,
@@ -1396,12 +1420,24 @@ var FileBackedStreamStore = class {
 			}
 			throw err;
 		}
+		const tAfterAppend = performance.now();
 		if (options.closed) {
 			const updatedMeta = this.db.get(key);
 			updatedMeta.closed = true;
-			this.db.putSync(key, updatedMeta);
+			await this.db.put(key, updatedMeta);
 		}
 		const updated = this.db.get(key);
+		const totalMs = performance.now() - t0;
+		if (totalMs > 50) serverLog.event({
+			event: `store.create`,
+			path: streamPath,
+			totalMs: +totalMs.toFixed(2),
+			metaMs: +(tAfterMeta - t0).toFixed(2),
+			lmdbMs: +(tAfterLmdb - tAfterMeta).toFixed(2),
+			openMs: +(tAfterOpen - tAfterLmdb).toFixed(2),
+			appendMs: +(tAfterAppend - tAfterOpen).toFixed(2),
+			initBytes: options.initialData?.length ?? 0
+		}, `store.create slow`);
 		return this.streamMetaToStream(updated);
 	}
 	get(streamPath) {
@@ -1442,13 +1478,10 @@ var FileBackedStreamStore = class {
 		if (!streamMeta) return;
 		const forkedFrom = streamMeta.forkedFrom;
 		this.cancelLongPollsForStream(streamPath);
-		const segmentPath = node_path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
-		this.fileHandlePool.closeFileHandle(segmentPath).catch((err) => {
-			console.error(`[FileBackedStreamStore] Error closing file handle:`, err);
-		});
+		const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 		this.db.removeSync(key);
-		this.fileManager.deleteDirectoryByName(streamMeta.directoryName).catch((err) => {
-			console.error(`[FileBackedStreamStore] Error deleting stream directory:`, err);
+		this.fileHandlePool.closeFileHandle(segmentPath).then(() => node_fs.promises.unlink(segmentPath)).catch((err) => {
+			serverLog.error(`[FileBackedStreamStore] Error cleaning up stream file:`, err);
 		});
 		if (forkedFrom) {
 			const parentKey = `stream:${forkedFrom}`;
@@ -1519,10 +1552,11 @@ var FileBackedStreamStore = class {
 		const parts = streamMeta.currentOffset.split(`_`).map(Number);
 		const readSeq = parts[0];
 		const byteOffset = parts[1];
-		const newByteOffset = byteOffset + processedData.length;
+		const FRAME_OVERHEAD = 5;
+		const newByteOffset = byteOffset + FRAME_OVERHEAD + processedData.length;
 		const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
-		const streamDir = node_path.join(this.dataDir, `streams`, streamMeta.directoryName);
-		const segmentPath = node_path.join(streamDir, `segment_00000.log`);
+		const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
+		const tAppendStart = performance.now();
 		const stream = this.fileHandlePool.getWriteStream(segmentPath);
 		const lengthBuf = Buffer.allocUnsafe(4);
 		lengthBuf.writeUInt32BE(processedData.length, 0);
@@ -1537,12 +1571,14 @@ var FileBackedStreamStore = class {
 				else resolve();
 			});
 		});
+		const tAfterWrite = performance.now();
 		const message = {
 			data: processedData,
 			offset: newOffset,
 			timestamp: Date.now()
 		};
 		await this.fileHandlePool.fsyncFile(segmentPath);
+		const tAfterFsync = performance.now();
 		const updatedProducers = { ...streamMeta.producers };
 		if (producerResult && producerResult.status === `accepted`) updatedProducers[producerResult.producerId] = producerResult.proposedState;
 		let closedBy = void 0;
@@ -1561,7 +1597,19 @@ var FileBackedStreamStore = class {
 			closedBy: closedBy ?? streamMeta.closedBy
 		};
 		const key = `stream:${streamPath}`;
-		this.db.putSync(key, updatedMeta);
+		await this.db.put(key, updatedMeta);
+		const tAfterLmdb = performance.now();
+		const appendTotal = tAfterLmdb - tAppendStart;
+		if (appendTotal > 50) serverLog.event({
+			event: `store.append`,
+			path: streamPath,
+			totalMs: +appendTotal.toFixed(2),
+			writeMs: +(tAfterWrite - tAppendStart).toFixed(2),
+			fsyncMs: +(tAfterFsync - tAfterWrite).toFixed(2),
+			lmdbMs: +(tAfterLmdb - tAfterFsync).toFixed(2),
+			bytes: processedData.length,
+			isInitial: options.isInitialCreate ?? false
+		}, `store.append slow`);
 		this.notifyLongPolls(streamPath);
 		if (options.close) this.notifyLongPollsClosed(streamPath);
 		if (producerResult || options.close) return {
@@ -1654,7 +1702,7 @@ var FileBackedStreamStore = class {
 				},
 				producers: updatedProducers
 			};
-			this.db.putSync(key, updatedMeta);
+			await this.db.put(key, updatedMeta);
 			this.notifyLongPollsClosed(streamPath);
 			return {
 				finalOffset: streamMeta.currentOffset,
@@ -1688,7 +1736,7 @@ var FileBackedStreamStore = class {
 				const messageData = fileContent.subarray(filePos, filePos + messageLength);
 				filePos += messageLength;
 				filePos += 1;
-				physicalDataOffset += messageLength;
+				physicalDataOffset += messageLength + 5;
 				const logicalOffset = baseByteOffset + physicalDataOffset;
 				if (capByte !== void 0 && logicalOffset > capByte) break;
 				if (logicalOffset > startByte) messages.push({
@@ -1698,7 +1746,7 @@ var FileBackedStreamStore = class {
 				});
 			}
 		} catch (err) {
-			console.error(`[FileBackedStreamStore] Error reading segment file:`, err);
+			serverLog.error(`[FileBackedStreamStore] Error reading segment file:`, err);
 		}
 		return messages;
 	}
@@ -1720,7 +1768,7 @@ var FileBackedStreamStore = class {
 				messages.push(...inherited);
 			}
 		}
-		const segmentPath = node_path.join(this.dataDir, `streams`, sourceMeta.directoryName, `segment_00000.log`);
+		const segmentPath = segmentFile(this.dataDir, sourceMeta.directoryName);
 		const sourceBaseByte = sourceMeta.forkOffset ? Number(sourceMeta.forkOffset.split(`_`)[1] ?? 0) : 0;
 		const ownMessages = this.readMessagesFromSegmentFile(segmentPath, startByte, sourceBaseByte, capByte);
 		messages.push(...ownMessages);
@@ -1747,11 +1795,11 @@ var FileBackedStreamStore = class {
 				const inherited = this.readForkedMessages(streamMeta.forkedFrom, startByte, forkByte);
 				messages.push(...inherited);
 			}
-			const segmentPath = node_path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
+			const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 			const ownMessages = this.readMessagesFromSegmentFile(segmentPath, startByte, forkByte);
 			messages.push(...ownMessages);
 		} else {
-			const segmentPath = node_path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
+			const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 			const ownMessages = this.readMessagesFromSegmentFile(segmentPath, startByte, 0);
 			messages.push(...ownMessages);
 		}
@@ -1822,6 +1870,7 @@ var FileBackedStreamStore = class {
 	formatResponse(streamPath, messages) {
 		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		if (normalizeContentType(streamMeta.contentType) === `application/json`) return formatJsonMessages(messages);
 		const totalSize = messages.reduce((sum, m) => sum + m.data.length, 0);
 		const concatenated = new Uint8Array(totalSize);
 		let offset = 0;
@@ -1829,7 +1878,6 @@ var FileBackedStreamStore = class {
 			concatenated.set(msg.data, offset);
 			offset += msg.data.length;
 		}
-		if (normalizeContentType(streamMeta.contentType) === `application/json`) return formatJsonResponse(concatenated);
 		return concatenated;
 	}
 	getCurrentOffset(streamPath) {
@@ -1849,7 +1897,7 @@ var FileBackedStreamStore = class {
 		const entries = Array.from(range);
 		for (const { key } of entries) this.db.removeSync(key);
 		this.fileHandlePool.closeAll().catch((err) => {
-			console.error(`[FileBackedStreamStore] Error closing handles:`, err);
+			serverLog.error(`[FileBackedStreamStore] Error closing handles:`, err);
 		});
 	}
 	/**
@@ -2003,30 +2051,985 @@ function handleCursorCollision(currentCursor, previousCursor, options = {}) {
 	return generateResponseCursor(previousCursor, options);
 }
 
+//#endregion
+//#region src/crypto.ts
+/**
+* Generate a unique wake ID.
+*/
+function generateWakeId() {
+	return `w_${(0, node_crypto.randomBytes)(12).toString(`hex`)}`;
+}
+const WEBHOOK_KEYPAIR = (0, node_crypto.generateKeyPairSync)(`ed25519`);
+const WEBHOOK_PUBLIC_JWK = buildWebhookPublicJwk();
+function buildWebhookPublicJwk() {
+	const exported = WEBHOOK_KEYPAIR.publicKey.export({ format: `jwk` });
+	if (exported.kty !== `OKP` || exported.crv !== `Ed25519` || !exported.x) throw new Error(`Failed to export Ed25519 webhook signing key`);
+	const thumbprintInput = JSON.stringify({
+		crv: exported.crv,
+		kty: exported.kty,
+		x: exported.x
+	});
+	const kid = `ds_${(0, node_crypto.createHash)(`sha256`).update(thumbprintInput).digest(`base64url`)}`;
+	return {
+		kty: `OKP`,
+		crv: `Ed25519`,
+		x: exported.x,
+		kid,
+		use: `sig`,
+		alg: `EdDSA`
+	};
+}
+function getWebhookSigningKeyId() {
+	return WEBHOOK_PUBLIC_JWK.kid;
+}
+function getWebhookJwks() {
+	return { keys: [{ ...WEBHOOK_PUBLIC_JWK }] };
+}
+/**
+* Sign a webhook payload for the Webhook-Signature header.
+* Format: t=<timestamp>,kid=<key_id>,ed25519=<base64url_signature>
+*/
+function signWebhookPayload(body) {
+	const timestamp = Math.floor(Date.now() / 1e3);
+	const payload = `${timestamp}.${body}`;
+	const signature = (0, node_crypto.sign)(null, Buffer.from(payload), WEBHOOK_KEYPAIR.privateKey).toString(`base64url`);
+	return `t=${timestamp},kid=${WEBHOOK_PUBLIC_JWK.kid},ed25519=${signature}`;
+}
+const TOKEN_KEY = (0, node_crypto.randomBytes)(32);
+/**
+* Generate a signed callback token.
+* Token format: base64url(json_payload).base64url(hmac_signature)
+* Payload: { consumer_id, epoch, exp }
+*/
+function generateCallbackToken(consumerId, epoch) {
+	const payload = {
+		sub: consumerId,
+		epoch,
+		exp: Math.floor(Date.now() / 1e3) + 3600,
+		jti: (0, node_crypto.randomBytes)(8).toString(`hex`)
+	};
+	const payloadStr = Buffer.from(JSON.stringify(payload)).toString(`base64url`);
+	const sig = (0, node_crypto.createHmac)(`sha256`, TOKEN_KEY).update(payloadStr).digest(`base64url`);
+	return `${payloadStr}.${sig}`;
+}
+/**
+* Validate a callback token. Returns the decoded payload or null.
+* On success, includes `exp` (unix seconds) so callers can decide
+* whether the token needs refreshing.
+*/
+function validateCallbackToken(token, consumerId) {
+	const parts = token.split(`.`);
+	if (parts.length !== 2) return {
+		valid: false,
+		code: `TOKEN_INVALID`
+	};
+	const [payloadStr, sig] = parts;
+	const expectedSig = (0, node_crypto.createHmac)(`sha256`, TOKEN_KEY).update(payloadStr).digest(`base64url`);
+	try {
+		if (!(0, node_crypto.timingSafeEqual)(Buffer.from(sig), Buffer.from(expectedSig))) return {
+			valid: false,
+			code: `TOKEN_INVALID`
+		};
+	} catch {
+		return {
+			valid: false,
+			code: `TOKEN_INVALID`
+		};
+	}
+	let payload;
+	try {
+		payload = JSON.parse(Buffer.from(payloadStr, `base64url`).toString());
+	} catch {
+		return {
+			valid: false,
+			code: `TOKEN_INVALID`
+		};
+	}
+	if (payload.sub !== consumerId) return {
+		valid: false,
+		code: `TOKEN_INVALID`
+	};
+	const now = Math.floor(Date.now() / 1e3);
+	if (now > payload.exp) return {
+		valid: false,
+		code: `TOKEN_EXPIRED`
+	};
+	return {
+		valid: true,
+		exp: payload.exp,
+		epoch: payload.epoch
+	};
+}
+
+//#endregion
+//#region src/glob.ts
+/**
+* Glob pattern matching for webhook subscription patterns.
+*
+* Supports:
+* - `*` matches exactly one path segment
+* - `**` matches zero or more path segments (recursive)
+* - Literal segments match exactly
+*/
+/**
+* Match a stream path against a glob pattern.
+*/
+function globMatch(pattern, path) {
+	const patternParts = splitPath(pattern);
+	const pathParts = splitPath(path);
+	return matchParts(patternParts, 0, pathParts, 0);
+}
+function splitPath(p) {
+	return p.replace(/^\/+/, ``).replace(/\/+$/, ``).split(`/`).filter((s) => s.length > 0);
+}
+function matchParts(pattern, pi, path, si) {
+	while (pi < pattern.length && si < path.length) {
+		const seg = pattern[pi];
+		if (seg === `**`) {
+			for (let i = si; i <= path.length; i++) if (matchParts(pattern, pi + 1, path, i)) return true;
+			return false;
+		}
+		if (seg === `*`) {
+			pi++;
+			si++;
+			continue;
+		}
+		const decodedSeg = seg.replace(/%2[Aa]/g, `*`);
+		if (decodedSeg !== path[si]) return false;
+		pi++;
+		si++;
+	}
+	while (pi < pattern.length && pattern[pi] === `**`) pi++;
+	return pi === pattern.length && si === path.length;
+}
+
+//#endregion
+//#region src/subscription-manager.ts
+const DEFAULT_LEASE_TTL_MS = 3e4;
+const MIN_LEASE_TTL_MS = 1e3;
+const MAX_LEASE_TTL_MS = 10 * 6e4;
+const ZERO_OFFSET = `0000000000000000_0000000000000000`;
+const BEFORE_FIRST_OFFSET = `-1`;
+const MAX_RETRY_DELAY_MS = 6e4;
+function compareOffsets(a, b) {
+	if (a < b) return -1;
+	if (a > b) return 1;
+	return 0;
+}
+function normalizeRelativePath(path) {
+	return path.replace(/^\/+/, ``).replace(/\/+$/, ``);
+}
+function toAbsoluteStreamPath(streamPath) {
+	return `/v1/stream/${normalizeRelativePath(streamPath)}`;
+}
+function toStreamRelativePath(absolutePath) {
+	const streamRoot = `/v1/stream/`;
+	if (!absolutePath.startsWith(streamRoot)) return null;
+	const path = absolutePath.slice(streamRoot.length);
+	if (path === `__ds` || path.startsWith(`__ds/`)) return null;
+	return path.length > 0 ? path : null;
+}
+function stableConfigHash(input) {
+	const canonical = {
+		type: input.type,
+		pattern: input.pattern,
+		streams: [...new Set(input.streams)].sort(),
+		webhook: input.webhook ? { url: input.webhook.url } : void 0,
+		wake_stream: input.wake_stream,
+		lease_ttl_ms: input.lease_ttl_ms,
+		description: input.description
+	};
+	return (0, node_crypto.createHash)(`sha256`).update(JSON.stringify(canonical)).digest(`hex`);
+}
+function isPrivateOrLinkLocalIpv4(host) {
+	const parts = host.split(`.`).map((part) => Number(part));
+	if (parts.length !== 4 || parts.some((part) => !Number.isInteger(part))) return false;
+	const [a, b] = parts;
+	return a === 10 || a === 127 || a === 0 || a === 172 && b >= 16 && b <= 31 || a === 192 && b === 168 || a === 169 && b === 254;
+}
+function isLocalDevHost(host) {
+	return host === `localhost` || /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
+}
+function validateWebhookUrl(rawUrl) {
+	let url;
+	try {
+		url = new URL(rawUrl);
+	} catch {
+		return {
+			ok: false,
+			message: `webhook.url must be a valid URL`
+		};
+	}
+	const host = url.hostname.toLowerCase();
+	if (url.protocol === `http:`) {
+		if (isLocalDevHost(host)) return { ok: true };
+		return {
+			ok: false,
+			message: `http webhook URLs are only allowed for localhost or 127.0.0.x`
+		};
+	}
+	if (url.protocol !== `https:`) return {
+		ok: false,
+		message: `webhook.url must use https`
+	};
+	if (host === `localhost`) return {
+		ok: false,
+		message: `localhost webhook URLs must use http for dev`
+	};
+	if ((0, node_net.isIP)(host) === 4 && isPrivateOrLinkLocalIpv4(host)) return {
+		ok: false,
+		message: `webhook.url must not target private or link-local hosts`
+	};
+	if ((0, node_net.isIP)(host) === 6) return {
+		ok: false,
+		message: `IPv6 webhook hosts are not accepted by the reference server`
+	};
+	return { ok: true };
+}
+var SubscriptionManager = class {
+	subscriptions = new Map();
+	streamStore;
+	callbackBaseUrl;
+	webhooksEnabled;
+	isShuttingDown = false;
+	constructor(opts) {
+		this.callbackBaseUrl = opts.callbackBaseUrl;
+		this.streamStore = opts.streamStore;
+		this.webhooksEnabled = opts.webhooksEnabled ?? true;
+	}
+	createOrConfirm(id, input) {
+		const configHash = stableConfigHash(input);
+		const existing = this.subscriptions.get(id);
+		if (existing) {
+			if (existing.config_hash !== configHash) return { error: {
+				code: `SUBSCRIPTION_ALREADY_EXISTS`,
+				message: `Subscription already exists with different configuration`
+			} };
+			return {
+				subscription: existing,
+				created: false
+			};
+		}
+		if (input.type === `webhook`) {
+			if (!this.webhooksEnabled) return { error: {
+				code: `INVALID_REQUEST`,
+				message: `webhook subscriptions are not enabled on this server`
+			} };
+			if (!input.webhook) return { error: {
+				code: `INVALID_REQUEST`,
+				message: `webhook subscriptions require webhook.url`
+			} };
+			const validation = validateWebhookUrl(input.webhook.url);
+			if (!validation.ok) return { error: {
+				code: `WEBHOOK_URL_REJECTED`,
+				message: validation.message
+			} };
+		}
+		if (input.type === `pull-wake` && !input.wake_stream) return { error: {
+			code: `INVALID_REQUEST`,
+			message: `pull-wake subscriptions require wake_stream`
+		} };
+		const subscription = {
+			id,
+			type: input.type,
+			pattern: input.pattern,
+			webhook: input.webhook ? { url: input.webhook.url } : void 0,
+			wake_stream: input.wake_stream,
+			lease_ttl_ms: input.lease_ttl_ms,
+			description: input.description,
+			created_at: new Date().toISOString(),
+			status: `active`,
+			config_hash: configHash,
+			streams: new Map(),
+			generation: 0,
+			wake_id: null,
+			wake_snapshot: new Map(),
+			token: null,
+			holder: null,
+			lease_timer: null,
+			retry_count: 0,
+			retry_timer: null,
+			next_attempt_at: null
+		};
+		for (const stream of input.streams) this.linkStream(subscription, stream, `explicit`, this.getTailOffset(stream));
+		if (input.pattern) {
+			for (const stream of this.listStreams()) if (globMatch(input.pattern, stream)) this.linkStream(subscription, stream, `glob`, this.getTailOffset(stream));
+		}
+		this.subscriptions.set(id, subscription);
+		return {
+			subscription,
+			created: true
+		};
+	}
+	get(id) {
+		return this.subscriptions.get(id);
+	}
+	delete(id) {
+		const subscription = this.subscriptions.get(id);
+		if (!subscription) return false;
+		this.clearLease(subscription);
+		if (subscription.retry_timer) clearTimeout(subscription.retry_timer);
+		this.subscriptions.delete(id);
+		return true;
+	}
+	addExplicitStreams(id, streams) {
+		const subscription = this.get(id);
+		if (!subscription) return false;
+		for (const stream of streams) this.linkStream(subscription, stream, `explicit`, this.getTailOffset(stream));
+		return true;
+	}
+	removeExplicitStream(id, streamPath) {
+		const subscription = this.get(id);
+		if (!subscription) return false;
+		const normalized = normalizeRelativePath(streamPath);
+		const link = subscription.streams.get(normalized);
+		if (!link) return true;
+		link.link_types.delete(`explicit`);
+		if (link.link_types.size === 0) subscription.streams.delete(normalized);
+		return true;
+	}
+	async onStreamAppend(absolutePath) {
+		if (this.isShuttingDown) return;
+		for (const subscription of this.subscriptions.values()) {
+			const relative = toStreamRelativePath(absolutePath);
+			if (!relative) continue;
+			if (subscription.pattern && globMatch(subscription.pattern, relative)) {
+				const existing = subscription.streams.get(relative);
+				this.linkStream(subscription, relative, `glob`, existing?.acked_offset ?? BEFORE_FIRST_OFFSET);
+			}
+			if (subscription.streams.has(relative)) await this.maybeWake(subscription, relative);
+		}
+	}
+	onStreamDeleted(absolutePath) {
+		for (const subscription of this.subscriptions.values()) {
+			const relative = toStreamRelativePath(absolutePath);
+			if (relative) subscription.streams.delete(relative);
+		}
+	}
+	async handleWebhookCallback(id, token, request) {
+		const subscription = this.get(id);
+		if (!subscription) return this.errorResponse(404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+		const fenced = this.validateWakeToken(subscription, token, request);
+		if (fenced) return fenced;
+		const ackError = this.applyAcks(subscription, request);
+		if (ackError) return ackError;
+		this.extendLease(subscription);
+		let nextWake = false;
+		if (request.done === true) {
+			this.clearLease(subscription);
+			subscription.token = null;
+			subscription.holder = null;
+			subscription.wake_id = null;
+			subscription.wake_snapshot.clear();
+			nextWake = await this.triggerNextWakeIfPending(subscription);
+		}
+		return {
+			status: 200,
+			body: {
+				ok: true,
+				next_wake: nextWake
+			}
+		};
+	}
+	async claim(id, worker) {
+		const subscription = this.get(id);
+		if (!subscription) return this.errorResponse(404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+		if (subscription.type !== `pull-wake`) return this.errorResponse(400, `INVALID_REQUEST`, `Subscription is not pull-wake`);
+		if (subscription.holder) return {
+			status: 409,
+			body: { error: {
+				code: `ALREADY_CLAIMED`,
+				current_holder: subscription.holder,
+				generation: subscription.generation
+			} }
+		};
+		if (!this.hasPendingWork(subscription)) return this.errorResponse(409, `NO_PENDING_WORK`, `Subscription has no pending work`);
+		if (!subscription.wake_id) await this.createWake(subscription, this.firstPendingStream(subscription));
+		subscription.holder = worker;
+		subscription.token = generateCallbackToken(this.tokenSubject(subscription), subscription.generation);
+		this.extendLease(subscription);
+		return {
+			status: 200,
+			body: {
+				wake_id: subscription.wake_id,
+				generation: subscription.generation,
+				token: subscription.token,
+				streams: this.streamInfos(subscription),
+				lease_ttl_ms: subscription.lease_ttl_ms
+			}
+		};
+	}
+	async ack(id, token, request) {
+		const subscription = this.get(id);
+		if (!subscription) return this.errorResponse(404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+		if (subscription.type !== `pull-wake`) return this.errorResponse(400, `INVALID_REQUEST`, `Subscription is not pull-wake`);
+		const fenced = this.validateWakeToken(subscription, token, request);
+		if (fenced) return fenced;
+		const ackError = this.applyAcks(subscription, request);
+		if (ackError) return ackError;
+		this.extendLease(subscription);
+		let nextWake = false;
+		if (request.done === true) {
+			this.clearLease(subscription);
+			subscription.token = null;
+			subscription.holder = null;
+			subscription.wake_id = null;
+			subscription.wake_snapshot.clear();
+			nextWake = await this.triggerNextWakeIfPending(subscription);
+		}
+		return {
+			status: 200,
+			body: {
+				ok: true,
+				next_wake: nextWake
+			}
+		};
+	}
+	async release(id, token, request) {
+		const subscription = this.get(id);
+		if (!subscription) return this.errorResponse(404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+		if (subscription.type !== `pull-wake`) return this.errorResponse(400, `INVALID_REQUEST`, `Subscription is not pull-wake`);
+		const fenced = this.validateWakeToken(subscription, token, request);
+		if (fenced) return fenced;
+		this.clearLease(subscription);
+		subscription.token = null;
+		subscription.holder = null;
+		subscription.wake_id = null;
+		subscription.wake_snapshot.clear();
+		await this.triggerNextWakeIfPending(subscription);
+		return { status: 204 };
+	}
+	serialize(subscription) {
+		return {
+			id: subscription.id,
+			subscription_id: subscription.id,
+			type: subscription.type,
+			pattern: subscription.pattern,
+			streams: this.streamInfos(subscription).map((stream) => ({
+				path: stream.path,
+				link_type: stream.link_type,
+				acked_offset: stream.acked_offset
+			})),
+			webhook: subscription.webhook ? {
+				url: subscription.webhook.url,
+				signing: this.webhookSigningMetadata()
+			} : void 0,
+			wake_stream: subscription.wake_stream,
+			lease_ttl_ms: subscription.lease_ttl_ms,
+			created_at: subscription.created_at,
+			status: subscription.status,
+			description: subscription.description
+		};
+	}
+	getWebhookJwks() {
+		return getWebhookJwks();
+	}
+	shutdown() {
+		this.isShuttingDown = true;
+		for (const subscription of this.subscriptions.values()) {
+			this.clearLease(subscription);
+			if (subscription.retry_timer) clearTimeout(subscription.retry_timer);
+		}
+		this.subscriptions.clear();
+	}
+	async maybeWake(subscription, triggeredBy) {
+		if (subscription.wake_id || subscription.holder) return;
+		if (!this.hasPendingWork(subscription)) return;
+		await this.createWake(subscription, triggeredBy);
+	}
+	async createWake(subscription, triggeredBy) {
+		subscription.generation++;
+		subscription.wake_id = generateWakeId();
+		subscription.wake_snapshot = new Map(this.streamInfos(subscription).map((stream) => [stream.path, stream.tail_offset]));
+		if (subscription.type === `webhook`) {
+			subscription.token = generateCallbackToken(this.tokenSubject(subscription), subscription.generation);
+			this.extendLease(subscription);
+			this.deliverWebhook(subscription, [triggeredBy]);
+			return;
+		}
+		await this.writePullWakeEvent(subscription, triggeredBy);
+	}
+	async deliverWebhook(subscription, triggeredBy) {
+		if (!subscription.webhook || !subscription.wake_id || !subscription.token) return;
+		const body = JSON.stringify({
+			subscription_id: subscription.id,
+			wake_id: subscription.wake_id,
+			generation: subscription.generation,
+			streams: this.streamInfos(subscription),
+			callback_url: this.subscriptionActionUrl(subscription, `callback`),
+			callback_token: subscription.token
+		});
+		const headers = {
+			"content-type": `application/json`,
+			"webhook-signature": signWebhookPayload(body)
+		};
+		try {
+			const response = await fetch(subscription.webhook.url, {
+				method: `POST`,
+				headers,
+				body
+			});
+			if (!response.ok) {
+				this.scheduleWebhookRetry(subscription, triggeredBy);
+				return;
+			}
+			subscription.status = `active`;
+			subscription.retry_count = 0;
+			subscription.next_attempt_at = null;
+			let parsed = null;
+			try {
+				parsed = await response.json();
+			} catch {
+				parsed = null;
+			}
+			if (parsed?.done === true) {
+				this.autoAckWakeSnapshot(subscription);
+				this.clearLease(subscription);
+				subscription.token = null;
+				subscription.holder = null;
+				subscription.wake_id = null;
+				subscription.wake_snapshot.clear();
+				await this.triggerNextWakeIfPending(subscription);
+			}
+		} catch (err) {
+			serverLog.warn(`[subscriptions] webhook delivery failed:`, err);
+			this.scheduleWebhookRetry(subscription, triggeredBy);
+		}
+	}
+	scheduleWebhookRetry(subscription, triggeredBy) {
+		if (this.isShuttingDown) return;
+		subscription.retry_count++;
+		const baseDelay = Math.min(1e3 * Math.pow(2, Math.max(0, subscription.retry_count - 1)), MAX_RETRY_DELAY_MS);
+		const jitter = baseDelay * .2 * (Math.random() * 2 - 1);
+		const delay = Math.max(0, Math.round(baseDelay + jitter));
+		subscription.status = `failed`;
+		subscription.next_attempt_at = Date.now() + delay;
+		if (subscription.retry_timer) clearTimeout(subscription.retry_timer);
+		subscription.retry_timer = setTimeout(() => {
+			subscription.retry_timer = null;
+			this.deliverWebhook(subscription, triggeredBy);
+		}, delay);
+	}
+	async writePullWakeEvent(subscription, streamPath) {
+		if (!subscription.wake_stream) return;
+		const wakeStream = toAbsoluteStreamPath(subscription.wake_stream);
+		if (!this.streamStore.has(wakeStream)) {
+			serverLog.warn(`[subscriptions] wake stream does not exist: ${wakeStream}`);
+			return;
+		}
+		const event = {
+			type: `wake`,
+			subscription_id: subscription.id,
+			stream: streamPath,
+			generation: subscription.generation,
+			ts: Date.now()
+		};
+		await Promise.resolve(this.streamStore.append(wakeStream, new TextEncoder().encode(JSON.stringify(event))));
+	}
+	autoAckWakeSnapshot(subscription) {
+		for (const [stream, tail] of subscription.wake_snapshot) {
+			const link = subscription.streams.get(stream);
+			if (link) link.acked_offset = tail;
+		}
+	}
+	applyAcks(subscription, request) {
+		if (!request.acks) return null;
+		for (const ack of request.acks) {
+			const stream = normalizeRelativePath(ack.stream ?? ack.path ?? ``);
+			const link = subscription.streams.get(stream);
+			if (!stream || !link) return this.errorResponse(409, `INVALID_OFFSET`, `Ack references an unknown subscription stream`);
+			if (ack.offset === BEFORE_FIRST_OFFSET) return this.errorResponse(409, `INVALID_OFFSET`, `Ack offset must not be -1`);
+			if (compareOffsets(ack.offset, link.acked_offset) < 0) return this.errorResponse(409, `INVALID_OFFSET`, `Ack offset regresses the committed cursor`);
+			if (compareOffsets(ack.offset, this.getTailOffset(stream)) > 0) return this.errorResponse(409, `INVALID_OFFSET`, `Ack offset is beyond stream tail`);
+		}
+		for (const ack of request.acks) {
+			const stream = normalizeRelativePath(ack.stream ?? ack.path ?? ``);
+			subscription.streams.get(stream).acked_offset = ack.offset;
+		}
+		return null;
+	}
+	validateWakeToken(subscription, token, request) {
+		const tokenResult = validateCallbackToken(token, this.tokenSubject(subscription));
+		if (!tokenResult.valid) return this.errorResponse(401, tokenResult.code, tokenResult.code === `TOKEN_EXPIRED` ? `Token expired` : `Token invalid`);
+		if (tokenResult.epoch !== subscription.generation || request.generation !== subscription.generation || request.wake_id !== subscription.wake_id) return this.errorResponse(409, `FENCED`, `Wake generation is stale`);
+		return null;
+	}
+	async triggerNextWakeIfPending(subscription) {
+		if (!this.hasPendingWork(subscription)) return false;
+		await this.createWake(subscription, this.firstPendingStream(subscription));
+		return true;
+	}
+	hasPendingWork(subscription) {
+		return this.streamInfos(subscription).some((stream) => stream.has_pending);
+	}
+	firstPendingStream(subscription) {
+		return this.streamInfos(subscription).find((stream) => stream.has_pending)?.path ?? ``;
+	}
+	streamInfos(subscription) {
+		return Array.from(subscription.streams.values()).map((link) => {
+			const tail = this.getTailOffset(link.path);
+			return {
+				path: link.path,
+				link_type: link.link_types.has(`explicit`) ? `explicit` : `glob`,
+				acked_offset: link.acked_offset,
+				tail_offset: tail,
+				has_pending: compareOffsets(tail, link.acked_offset) > 0
+			};
+		});
+	}
+	linkStream(subscription, streamPath, linkType, ackedOffset) {
+		const normalized = normalizeRelativePath(streamPath);
+		const existing = subscription.streams.get(normalized);
+		if (existing) {
+			existing.link_types.add(linkType);
+			return existing;
+		}
+		const link = {
+			path: normalized,
+			link_types: new Set([linkType]),
+			acked_offset: ackedOffset
+		};
+		subscription.streams.set(normalized, link);
+		return link;
+	}
+	listStreams() {
+		return this.streamStore.list().map((path) => toStreamRelativePath(path)).filter((path) => path !== null);
+	}
+	getTailOffset(streamPath) {
+		return this.streamStore.get(toAbsoluteStreamPath(streamPath))?.currentOffset ?? ZERO_OFFSET;
+	}
+	subscriptionActionUrl(subscription, action) {
+		const url = new URL(`/v1/stream/__ds/subscriptions/${encodeURIComponent(subscription.id)}/${action}`, this.callbackBaseUrl);
+		return url.toString();
+	}
+	webhookJwksUrl() {
+		const url = new URL(`/v1/stream/__ds/jwks.json`, this.callbackBaseUrl);
+		return url.toString();
+	}
+	webhookSigningMetadata() {
+		return {
+			alg: `ed25519`,
+			kid: getWebhookSigningKeyId(),
+			jwks_url: this.webhookJwksUrl()
+		};
+	}
+	extendLease(subscription) {
+		this.clearLease(subscription);
+		subscription.lease_timer = setTimeout(() => {
+			subscription.lease_timer = null;
+			subscription.holder = null;
+			subscription.token = null;
+			subscription.wake_id = null;
+			subscription.wake_snapshot.clear();
+			this.triggerNextWakeIfPending(subscription);
+		}, subscription.lease_ttl_ms);
+	}
+	clearLease(subscription) {
+		if (subscription.lease_timer) {
+			clearTimeout(subscription.lease_timer);
+			subscription.lease_timer = null;
+		}
+	}
+	tokenSubject(subscription) {
+		return `subscription:${subscription.id}`;
+	}
+	errorResponse(status, code, message) {
+		return {
+			status,
+			body: { error: {
+				code,
+				message
+			} }
+		};
+	}
+};
+
+//#endregion
+//#region src/subscription-routes.ts
+const RESERVED_CONTROL_PREFIX = `/v1/stream/__ds`;
+const SUBSCRIPTION_PREFIX = `${RESERVED_CONTROL_PREFIX}/subscriptions/`;
+const JWKS_PATH = `${RESERVED_CONTROL_PREFIX}/jwks.json`;
+const ERROR_STATUS = {
+	INVALID_REQUEST: 400,
+	SUBSCRIPTION_NOT_FOUND: 404,
+	SUBSCRIPTION_ALREADY_EXISTS: 409,
+	WEBHOOK_URL_REJECTED: 400,
+	TOKEN_INVALID: 401,
+	TOKEN_EXPIRED: 401,
+	FENCED: 409,
+	ALREADY_CLAIMED: 409,
+	NO_PENDING_WORK: 409,
+	INVALID_OFFSET: 409
+};
+var SubscriptionRoutes = class {
+	manager;
+	constructor(manager) {
+		this.manager = manager;
+	}
+	async handleRequest(method, path, req, res) {
+		if (path === JWKS_PATH) {
+			this.handleJwks(method, res);
+			return true;
+		}
+		const route = this.parseRoute(path);
+		if (!route) {
+			if (path === RESERVED_CONTROL_PREFIX || path.startsWith(`${RESERVED_CONTROL_PREFIX}/`)) {
+				this.writeError(res, 404, `SUBSCRIPTION_NOT_FOUND`, `Durable Streams control route not found`);
+				return true;
+			}
+			return false;
+		}
+		try {
+			switch (route.action) {
+				case `base`:
+					await this.handleBase(route, method, req, res);
+					return true;
+				case `streams`:
+					await this.handleStreams(route, method, req, res);
+					return true;
+				case `stream`:
+					this.handleStream(route, method, res);
+					return true;
+				case `callback`:
+					await this.handleCallback(route, req, res);
+					return true;
+				case `claim`:
+					await this.handleClaim(route, req, res);
+					return true;
+				case `ack`:
+					await this.handleAck(route, req, res);
+					return true;
+				case `release`:
+					await this.handleRelease(route, req, res);
+					return true;
+			}
+		} catch (err) {
+			if (err instanceof SyntaxError) {
+				this.writeError(res, 400, `INVALID_REQUEST`, `Invalid JSON body`);
+				return true;
+			}
+			throw err;
+		}
+	}
+	async handleBase(route, method, req, res) {
+		if (method === `PUT`) {
+			const parsed = await this.readJson(req);
+			const input = this.parseCreateInput(parsed);
+			if (`error` in input) {
+				this.writeError(res, 400, `INVALID_REQUEST`, input.error);
+				return;
+			}
+			const result = this.manager.createOrConfirm(route.subscriptionId, input.value);
+			if (`error` in result) {
+				this.writeError(res, ERROR_STATUS[result.error.code], result.error.code, result.error.message);
+				return;
+			}
+			this.writeJson(res, result.created ? 201 : 200, this.manager.serialize(result.subscription));
+			return;
+		}
+		if (method === `GET`) {
+			const subscription = this.manager.get(route.subscriptionId);
+			if (!subscription) {
+				this.writeError(res, 404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+				return;
+			}
+			this.writeJson(res, 200, this.manager.serialize(subscription));
+			return;
+		}
+		if (method === `DELETE`) {
+			this.manager.delete(route.subscriptionId);
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+		this.methodNotAllowed(res);
+	}
+	handleJwks(method, res) {
+		if (method !== `GET`) {
+			this.methodNotAllowed(res);
+			return;
+		}
+		res.writeHead(200, {
+			"content-type": `application/jwk-set+json`,
+			"cache-control": `public, max-age=300`
+		});
+		res.end(JSON.stringify(this.manager.getWebhookJwks()));
+	}
+	async handleStreams(route, method, req, res) {
+		if (method !== `POST`) {
+			this.methodNotAllowed(res);
+			return;
+		}
+		const parsed = await this.readJson(req);
+		const streams = parsed.streams;
+		if (!Array.isArray(streams) || streams.some((stream) => typeof stream !== `string` || stream.length === 0)) {
+			this.writeError(res, 400, `INVALID_REQUEST`, `streams must be a non-empty string array`);
+			return;
+		}
+		const ok = this.manager.addExplicitStreams(route.subscriptionId, streams.map(normalizeRelativePath));
+		if (!ok) {
+			this.writeError(res, 404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+			return;
+		}
+		res.writeHead(204);
+		res.end();
+	}
+	handleStream(route, method, res) {
+		if (method !== `DELETE`) {
+			this.methodNotAllowed(res);
+			return;
+		}
+		const ok = this.manager.removeExplicitStream(route.subscriptionId, route.streamPath ?? ``);
+		if (!ok) {
+			this.writeError(res, 404, `SUBSCRIPTION_NOT_FOUND`, `Subscription not found`);
+			return;
+		}
+		res.writeHead(204);
+		res.end();
+	}
+	async handleCallback(route, req, res) {
+		const token = this.readBearerToken(req);
+		if (!token) {
+			this.writeError(res, 401, `TOKEN_INVALID`, `Missing or malformed Authorization header`);
+			return;
+		}
+		const body = await this.readJson(req);
+		const result = await this.manager.handleWebhookCallback(route.subscriptionId, token, body);
+		this.writeManagerResult(res, result);
+	}
+	async handleClaim(route, req, res) {
+		const parsed = await this.readJson(req);
+		const worker = parsed.worker;
+		if (typeof worker !== `string` || worker.length === 0) {
+			this.writeError(res, 400, `INVALID_REQUEST`, `worker must be a non-empty string`);
+			return;
+		}
+		const result = await this.manager.claim(route.subscriptionId, worker);
+		this.writeManagerResult(res, result);
+	}
+	async handleAck(route, req, res) {
+		const token = this.readBearerToken(req);
+		if (!token) {
+			this.writeError(res, 401, `TOKEN_INVALID`, `Missing or malformed Authorization header`);
+			return;
+		}
+		const body = await this.readJson(req);
+		const result = await this.manager.ack(route.subscriptionId, token, body);
+		this.writeManagerResult(res, result);
+	}
+	async handleRelease(route, req, res) {
+		const token = this.readBearerToken(req);
+		if (!token) {
+			this.writeError(res, 401, `TOKEN_INVALID`, `Missing or malformed Authorization header`);
+			return;
+		}
+		const body = await this.readJson(req);
+		const result = await this.manager.release(route.subscriptionId, token, body);
+		this.writeManagerResult(res, result);
+	}
+	parseCreateInput(value) {
+		if (!value || typeof value !== `object`) return { error: `Request body must be a JSON object` };
+		const payload = value;
+		if (payload.type !== `webhook` && payload.type !== `pull-wake`) return { error: `type must be "webhook" or "pull-wake"` };
+		const type = payload.type;
+		const pattern = typeof payload.pattern === `string` && payload.pattern.length > 0 ? normalizeRelativePath(payload.pattern) : void 0;
+		const streams = Array.isArray(payload.streams) && payload.streams.length > 0 ? payload.streams.map((stream) => typeof stream === `string` ? normalizeRelativePath(stream) : null) : [];
+		if (streams.some((stream) => stream === null)) return { error: `streams must contain only strings` };
+		if (!pattern && streams.length === 0) return { error: `At least one of pattern or streams is required` };
+		const leaseTtl = payload.lease_ttl_ms === void 0 ? DEFAULT_LEASE_TTL_MS : payload.lease_ttl_ms;
+		if (typeof leaseTtl !== `number` || !Number.isInteger(leaseTtl) || leaseTtl < MIN_LEASE_TTL_MS || leaseTtl > MAX_LEASE_TTL_MS) return { error: `lease_ttl_ms must be an integer from 1000 to 600000` };
+		let webhook;
+		if (type === `webhook`) {
+			const rawWebhook = payload.webhook;
+			if (!rawWebhook || typeof rawWebhook !== `object`) return { error: `webhook subscriptions require webhook.url` };
+			const url = rawWebhook.url;
+			if (typeof url !== `string` || url.length === 0) return { error: `webhook subscriptions require webhook.url` };
+			webhook = { url };
+		}
+		const wakeStream = typeof payload.wake_stream === `string` && payload.wake_stream.length > 0 ? normalizeRelativePath(payload.wake_stream) : void 0;
+		if (type === `pull-wake` && !wakeStream) return { error: `pull-wake subscriptions require wake_stream` };
+		return { value: {
+			type,
+			pattern,
+			streams,
+			webhook,
+			wake_stream: wakeStream,
+			lease_ttl_ms: leaseTtl,
+			description: typeof payload.description === `string` ? payload.description : void 0
+		} };
+	}
+	parseRoute(path) {
+		if (!path.startsWith(SUBSCRIPTION_PREFIX)) return null;
+		const rest = path.slice(SUBSCRIPTION_PREFIX.length);
+		const parts = rest.split(`/`);
+		const subscriptionId = parts[0] ? decodeURIComponent(parts[0]) : ``;
+		if (!subscriptionId) return null;
+		const tail = parts.slice(1);
+		if (tail.length === 0) return {
+			subscriptionId,
+			action: `base`
+		};
+		if (tail[0] === `streams` && tail.length === 1) return {
+			subscriptionId,
+			action: `streams`
+		};
+		if (tail[0] === `streams` && tail.length > 1) return {
+			subscriptionId,
+			action: `stream`,
+			streamPath: normalizeRelativePath(decodeURIComponent(tail.slice(1).join(`/`)))
+		};
+		if (tail.length === 1 && [
+			`callback`,
+			`claim`,
+			`ack`,
+			`release`
+		].includes(tail[0])) return {
+			subscriptionId,
+			action: tail[0]
+		};
+		return null;
+	}
+	readBearerToken(req) {
+		const authHeader = req.headers.authorization;
+		if (!authHeader || !authHeader.startsWith(`Bearer `)) return null;
+		return authHeader.slice(`Bearer `.length);
+	}
+	async readJson(req) {
+		const chunks = [];
+		for await (const chunk of req) chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		const raw = Buffer.concat(chunks).toString(`utf8`);
+		return raw.length > 0 ? JSON.parse(raw) : {};
+	}
+	writeManagerResult(res, result) {
+		if (result.status === 204) {
+			res.writeHead(204);
+			res.end();
+			return;
+		}
+		this.writeJson(res, result.status, result.body ?? {});
+	}
+	writeJson(res, status, body) {
+		res.writeHead(status, { "content-type": `application/json` });
+		res.end(JSON.stringify(body));
+	}
+	writeError(res, status, code, message) {
+		this.writeJson(res, status, { error: {
+			code,
+			message
+		} });
+	}
+	methodNotAllowed(res) {
+		res.writeHead(405, { "content-type": `text/plain` });
+		res.end(`Method not allowed`);
+	}
+};
+
 //#endregion
 //#region src/server.ts
-const STREAM_OFFSET_HEADER = `Stream-Next-Offset`;
-const STREAM_CURSOR_HEADER = `Stream-Cursor`;
-const STREAM_UP_TO_DATE_HEADER = `Stream-Up-To-Date`;
-const STREAM_SEQ_HEADER = `Stream-Seq`;
-const STREAM_TTL_HEADER = `Stream-TTL`;
-const STREAM_EXPIRES_AT_HEADER = `Stream-Expires-At`;
 const STREAM_SSE_DATA_ENCODING_HEADER = `Stream-SSE-Data-Encoding`;
-const PRODUCER_ID_HEADER = `Producer-Id`;
-const PRODUCER_EPOCH_HEADER = `Producer-Epoch`;
-const PRODUCER_SEQ_HEADER = `Producer-Seq`;
-const PRODUCER_EXPECTED_SEQ_HEADER = `Producer-Expected-Seq`;
-const PRODUCER_RECEIVED_SEQ_HEADER = `Producer-Received-Seq`;
-const SSE_OFFSET_FIELD = `streamNextOffset`;
-const SSE_CURSOR_FIELD = `streamCursor`;
 const SSE_UP_TO_DATE_FIELD = `upToDate`;
-const SSE_CLOSED_FIELD = `streamClosed`;
-const STREAM_CLOSED_HEADER = `Stream-Closed`;
 const STREAM_FORKED_FROM_HEADER = `Stream-Forked-From`;
 const STREAM_FORK_OFFSET_HEADER = `Stream-Fork-Offset`;
-const OFFSET_QUERY_PARAM = `offset`;
-const LIVE_QUERY_PARAM = `live`;
-const CURSOR_QUERY_PARAM = `cursor`;
 /**
 * Encode data for SSE format.
 * Per SSE spec, each line in the payload needs its own "data:" prefix.
@@ -2080,6 +3083,8 @@ var DurableStreamTestServer = class {
 	isShuttingDown = false;
 	/** Injected faults for testing retry/resilience */
 	injectedFaults = new Map();
+	subscriptionManager = null;
+	subscriptionRoutes = null;
 	constructor(options = {}) {
 		if (options.dataDir) this.store = new FileBackedStreamStore({ dataDir: options.dataDir });
 		else this.store = new StreamStore();
@@ -2094,7 +3099,8 @@ var DurableStreamTestServer = class {
 			cursorOptions: {
 				intervalSeconds: options.cursorIntervalSeconds,
 				epoch: options.cursorEpoch
-			}
+			},
+			webhooks: options.webhooks ?? false
 		};
 	}
 	/**
@@ -2105,7 +3111,7 @@ var DurableStreamTestServer = class {
 		return new Promise((resolve, reject) => {
 			this.server = (0, node_http.createServer)((req, res) => {
 				this.handleRequest(req, res).catch((err) => {
-					console.error(`Request error:`, err);
+					serverLog.error(`Request error:`, err);
 					if (!res.headersSent) {
 						res.writeHead(500, { "content-type": `text/plain` });
 						res.end(`Internal server error`);
@@ -2117,6 +3123,12 @@ var DurableStreamTestServer = class {
 				const addr = this.server.address();
 				if (typeof addr === `string`) this._url = addr;
 				else if (addr) this._url = `http://${this.options.host}:${addr.port}`;
+				this.subscriptionManager = new SubscriptionManager({
+					callbackBaseUrl: this._url,
+					streamStore: this.store,
+					webhooksEnabled: this.options.webhooks
+				});
+				this.subscriptionRoutes = new SubscriptionRoutes(this.subscriptionManager);
 				resolve(this._url);
 			});
 		});
@@ -2127,6 +3139,11 @@ var DurableStreamTestServer = class {
 	async stop() {
 		if (!this.server) return;
 		this.isShuttingDown = true;
+		if (this.subscriptionManager) {
+			this.subscriptionManager.shutdown();
+			this.subscriptionManager = null;
+			this.subscriptionRoutes = null;
+		}
 		if (`cancelAllWaits` in this.store) this.store.cancelAllWaits();
 		for (const res of this.activeSSEResponses) res.end();
 		this.activeSSEResponses.clear();
@@ -2267,6 +3284,10 @@ var DurableStreamTestServer = class {
 			}
 			if (fault.truncateBodyBytes !== void 0 || fault.corruptBody || fault.injectSseEvent) res._injectedFault = fault;
 		}
+		if (this.subscriptionRoutes && method) {
+			const handled = await this.subscriptionRoutes.handleRequest(method, path, req, res);
+			if (handled) return;
+		}
 		try {
 			switch (method) {
 				case `PUT`:
@@ -2325,9 +3346,9 @@ var DurableStreamTestServer = class {
 		const forkedFromHeader = req.headers[STREAM_FORKED_FROM_HEADER.toLowerCase()];
 		const forkOffsetHeader = req.headers[STREAM_FORK_OFFSET_HEADER.toLowerCase()];
 		if (!contentType || contentType.trim() === `` || !/^[\w-]+\/[\w-]+/.test(contentType)) contentType = forkedFromHeader ? void 0 : `application/octet-stream`;
-		const ttlHeader = req.headers[STREAM_TTL_HEADER.toLowerCase()];
-		const expiresAtHeader = req.headers[STREAM_EXPIRES_AT_HEADER.toLowerCase()];
-		const closedHeader = req.headers[STREAM_CLOSED_HEADER.toLowerCase()];
+		const ttlHeader = req.headers[__durable_streams_client.STREAM_TTL_HEADER.toLowerCase()];
+		const expiresAtHeader = req.headers[__durable_streams_client.STREAM_EXPIRES_AT_HEADER.toLowerCase()];
+		const closedHeader = req.headers[__durable_streams_client.STREAM_CLOSED_HEADER.toLowerCase()];
 		const createClosed = closedHeader === `true`;
 		if (ttlHeader && expiresAtHeader) {
 			res.writeHead(400, { "content-type": `text/plain` });
@@ -2410,12 +3431,13 @@ var DurableStreamTestServer = class {
 			contentType: resolvedContentType,
 			timestamp: Date.now()
 		}));
+		if (isNew && body.length > 0) await this.notifyStreamAppend(path);
 		const headers = {
 			"content-type": resolvedContentType,
-			[STREAM_OFFSET_HEADER]: stream.currentOffset
+			[__durable_streams_client.STREAM_OFFSET_HEADER]: stream.currentOffset
 		};
 		if (isNew) headers[`location`] = `${this._url}${path}`;
-		if (stream.closed) headers[STREAM_CLOSED_HEADER] = `true`;
+		if (stream.closed) headers[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 		res.writeHead(isNew ? 201 : 200, headers);
 		res.end();
 	}
@@ -2435,13 +3457,13 @@ var DurableStreamTestServer = class {
 			return;
 		}
 		const headers = {
-			[STREAM_OFFSET_HEADER]: stream.currentOffset,
+			[__durable_streams_client.STREAM_OFFSET_HEADER]: stream.currentOffset,
 			"cache-control": `no-store`
 		};
 		if (stream.contentType) headers[`content-type`] = stream.contentType;
-		if (stream.closed) headers[STREAM_CLOSED_HEADER] = `true`;
-		if (stream.ttlSeconds !== void 0) headers[STREAM_TTL_HEADER] = String(stream.ttlSeconds);
-		if (stream.expiresAt) headers[STREAM_EXPIRES_AT_HEADER] = stream.expiresAt;
+		if (stream.closed) headers[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
+		if (stream.ttlSeconds !== void 0) headers[__durable_streams_client.STREAM_TTL_HEADER] = String(stream.ttlSeconds);
+		if (stream.expiresAt) headers[__durable_streams_client.STREAM_EXPIRES_AT_HEADER] = stream.expiresAt;
 		const closedSuffix = stream.closed ? `:c` : ``;
 		headers[`etag`] = `"${Buffer.from(path).toString(`base64`)}:-1:${stream.currentOffset}${closedSuffix}"`;
 		res.writeHead(200, headers);
@@ -2462,16 +3484,16 @@ var DurableStreamTestServer = class {
 			res.end(`Stream is gone`);
 			return;
 		}
-		const offset = url.searchParams.get(OFFSET_QUERY_PARAM) ?? void 0;
-		const live = url.searchParams.get(LIVE_QUERY_PARAM);
-		const cursor = url.searchParams.get(CURSOR_QUERY_PARAM) ?? void 0;
+		const offset = url.searchParams.get(__durable_streams_client.OFFSET_QUERY_PARAM) ?? void 0;
+		const live = url.searchParams.get(__durable_streams_client.LIVE_QUERY_PARAM);
+		const cursor = url.searchParams.get(__durable_streams_client.CURSOR_QUERY_PARAM) ?? void 0;
 		if (offset !== void 0) {
 			if (offset === ``) {
 				res.writeHead(400, { "content-type": `text/plain` });
 				res.end(`Empty offset parameter`);
 				return;
 			}
-			const allOffsets = url.searchParams.getAll(OFFSET_QUERY_PARAM);
+			const allOffsets = url.searchParams.getAll(__durable_streams_client.OFFSET_QUERY_PARAM);
 			if (allOffsets.length > 1) {
 				res.writeHead(400, { "content-type": `text/plain` });
 				res.end(`Multiple offset parameters not allowed`);
@@ -2503,12 +3525,12 @@ var DurableStreamTestServer = class {
 		const effectiveOffset = offset === `now` ? stream.currentOffset : offset;
 		if (offset === `now` && live !== `long-poll`) {
 			const headers$1 = {
-				[STREAM_OFFSET_HEADER]: stream.currentOffset,
-				[STREAM_UP_TO_DATE_HEADER]: `true`,
+				[__durable_streams_client.STREAM_OFFSET_HEADER]: stream.currentOffset,
+				[__durable_streams_client.STREAM_UP_TO_DATE_HEADER]: `true`,
 				[`cache-control`]: `no-store`
 			};
 			if (stream.contentType) headers$1[`content-type`] = stream.contentType;
-			if (stream.closed) headers$1[STREAM_CLOSED_HEADER] = `true`;
+			if (stream.closed) headers$1[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 			const isJsonMode = stream.contentType?.includes(`application/json`);
 			const responseBody = isJsonMode ? `[]` : ``;
 			res.writeHead(200, headers$1);
@@ -2521,9 +3543,9 @@ var DurableStreamTestServer = class {
 		if (live === `long-poll` && clientIsCaughtUp && messages.length === 0) {
 			if (stream.closed) {
 				res.writeHead(204, {
-					[STREAM_OFFSET_HEADER]: stream.currentOffset,
-					[STREAM_UP_TO_DATE_HEADER]: `true`,
-					[STREAM_CLOSED_HEADER]: `true`
+					[__durable_streams_client.STREAM_OFFSET_HEADER]: stream.currentOffset,
+					[__durable_streams_client.STREAM_UP_TO_DATE_HEADER]: `true`,
+					[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`
 				});
 				res.end();
 				return;
@@ -2533,10 +3555,10 @@ var DurableStreamTestServer = class {
 			if (result.streamClosed) {
 				const responseCursor = generateResponseCursor(cursor, this.options.cursorOptions);
 				res.writeHead(204, {
-					[STREAM_OFFSET_HEADER]: effectiveOffset ?? stream.currentOffset,
-					[STREAM_UP_TO_DATE_HEADER]: `true`,
-					[STREAM_CURSOR_HEADER]: responseCursor,
-					[STREAM_CLOSED_HEADER]: `true`
+					[__durable_streams_client.STREAM_OFFSET_HEADER]: effectiveOffset ?? stream.currentOffset,
+					[__durable_streams_client.STREAM_UP_TO_DATE_HEADER]: `true`,
+					[__durable_streams_client.STREAM_CURSOR_HEADER]: responseCursor,
+					[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`
 				});
 				res.end();
 				return;
@@ -2545,11 +3567,11 @@ var DurableStreamTestServer = class {
 				const responseCursor = generateResponseCursor(cursor, this.options.cursorOptions);
 				const currentStream$1 = this.store.get(path);
 				const timeoutHeaders = {
-					[STREAM_OFFSET_HEADER]: effectiveOffset ?? stream.currentOffset,
-					[STREAM_UP_TO_DATE_HEADER]: `true`,
-					[STREAM_CURSOR_HEADER]: responseCursor
+					[__durable_streams_client.STREAM_OFFSET_HEADER]: effectiveOffset ?? stream.currentOffset,
+					[__durable_streams_client.STREAM_UP_TO_DATE_HEADER]: `true`,
+					[__durable_streams_client.STREAM_CURSOR_HEADER]: responseCursor
 				};
-				if (currentStream$1?.closed) timeoutHeaders[STREAM_CLOSED_HEADER] = `true`;
+				if (currentStream$1?.closed) timeoutHeaders[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 				res.writeHead(204, timeoutHeaders);
 				res.end();
 				return;
@@ -2561,12 +3583,12 @@ var DurableStreamTestServer = class {
 		if (stream.contentType) headers[`content-type`] = stream.contentType;
 		const lastMessage = messages[messages.length - 1];
 		const responseOffset = lastMessage?.offset ?? stream.currentOffset;
-		headers[STREAM_OFFSET_HEADER] = responseOffset;
-		if (live === `long-poll`) headers[STREAM_CURSOR_HEADER] = generateResponseCursor(cursor, this.options.cursorOptions);
-		if (upToDate) headers[STREAM_UP_TO_DATE_HEADER] = `true`;
+		headers[__durable_streams_client.STREAM_OFFSET_HEADER] = responseOffset;
+		if (live === `long-poll`) headers[__durable_streams_client.STREAM_CURSOR_HEADER] = generateResponseCursor(cursor, this.options.cursorOptions);
+		if (upToDate) headers[__durable_streams_client.STREAM_UP_TO_DATE_HEADER] = `true`;
 		const currentStream = this.store.get(path);
 		const clientAtTail = responseOffset === currentStream?.currentOffset;
-		if (currentStream?.closed && clientAtTail && upToDate) headers[STREAM_CLOSED_HEADER] = `true`;
+		if (currentStream?.closed && clientAtTail && upToDate) headers[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 		const startOffset = offset ?? `-1`;
 		const closedSuffix = currentStream?.closed && clientAtTail && upToDate ? `:c` : ``;
 		const etag = `"${Buffer.from(path).toString(`base64`)}:${startOffset}:${responseOffset}${closedSuffix}"`;
@@ -2639,10 +3661,10 @@ var DurableStreamTestServer = class {
 			const streamIsClosed = currentStream?.closed ?? false;
 			const clientAtTail = controlOffset === currentStream.currentOffset;
 			const responseCursor = generateResponseCursor(cursor, this.options.cursorOptions);
-			const controlData = { [SSE_OFFSET_FIELD]: controlOffset };
-			if (streamIsClosed && clientAtTail) controlData[SSE_CLOSED_FIELD] = true;
+			const controlData = { [__durable_streams_client.SSE_OFFSET_FIELD]: controlOffset };
+			if (streamIsClosed && clientAtTail) controlData[__durable_streams_client.SSE_CLOSED_FIELD] = true;
 			else {
-				controlData[SSE_CURSOR_FIELD] = responseCursor;
+				controlData[__durable_streams_client.SSE_CURSOR_FIELD] = responseCursor;
 				if (upToDate) controlData[SSE_UP_TO_DATE_FIELD] = true;
 			}
 			res.write(`event: control\n`);
@@ -2652,8 +3674,8 @@ var DurableStreamTestServer = class {
 			if (upToDate) {
 				if (currentStream?.closed) {
 					const finalControlData = {
-						[SSE_OFFSET_FIELD]: currentOffset,
-						[SSE_CLOSED_FIELD]: true
+						[__durable_streams_client.SSE_OFFSET_FIELD]: currentOffset,
+						[__durable_streams_client.SSE_CLOSED_FIELD]: true
 					};
 					res.write(`event: control\n`);
 					res.write(encodeSSEData(JSON.stringify(finalControlData)));
@@ -2664,8 +3686,8 @@ var DurableStreamTestServer = class {
 				if (this.isShuttingDown || !isConnected) break;
 				if (result.streamClosed && result.messages.length === 0) {
 					const finalControlData = {
-						[SSE_OFFSET_FIELD]: currentOffset,
-						[SSE_CLOSED_FIELD]: true
+						[__durable_streams_client.SSE_OFFSET_FIELD]: currentOffset,
+						[__durable_streams_client.SSE_CLOSED_FIELD]: true
 					};
 					res.write(`event: control\n`);
 					res.write(encodeSSEData(JSON.stringify(finalControlData)));
@@ -2676,16 +3698,16 @@ var DurableStreamTestServer = class {
 					const streamAfterWait = this.store.get(path);
 					if (streamAfterWait?.closed) {
 						const closedControlData = {
-							[SSE_OFFSET_FIELD]: currentOffset,
-							[SSE_CLOSED_FIELD]: true
+							[__durable_streams_client.SSE_OFFSET_FIELD]: currentOffset,
+							[__durable_streams_client.SSE_CLOSED_FIELD]: true
 						};
 						res.write(`event: control\n`);
 						res.write(encodeSSEData(JSON.stringify(closedControlData)));
 						break;
 					}
 					const keepAliveData = {
-						[SSE_OFFSET_FIELD]: currentOffset,
-						[SSE_CURSOR_FIELD]: keepAliveCursor,
+						[__durable_streams_client.SSE_OFFSET_FIELD]: currentOffset,
+						[__durable_streams_client.SSE_CURSOR_FIELD]: keepAliveCursor,
 						[SSE_UP_TO_DATE_FIELD]: true
 					};
 					res.write(`event: control\n` + encodeSSEData(JSON.stringify(keepAliveData)));
@@ -2700,12 +3722,12 @@ var DurableStreamTestServer = class {
 	*/
 	async handleAppend(path, req, res) {
 		const contentType = req.headers[`content-type`];
-		const seq = req.headers[STREAM_SEQ_HEADER.toLowerCase()];
-		const closedHeader = req.headers[STREAM_CLOSED_HEADER.toLowerCase()];
+		const seq = req.headers[__durable_streams_client.STREAM_SEQ_HEADER.toLowerCase()];
+		const closedHeader = req.headers[__durable_streams_client.STREAM_CLOSED_HEADER.toLowerCase()];
 		const closeStream = closedHeader === `true`;
-		const producerId = req.headers[PRODUCER_ID_HEADER.toLowerCase()];
-		const producerEpochStr = req.headers[PRODUCER_EPOCH_HEADER.toLowerCase()];
-		const producerSeqStr = req.headers[PRODUCER_SEQ_HEADER.toLowerCase()];
+		const producerId = req.headers[__durable_streams_client.PRODUCER_ID_HEADER.toLowerCase()];
+		const producerEpochStr = req.headers[__durable_streams_client.PRODUCER_EPOCH_HEADER.toLowerCase()];
+		const producerSeqStr = req.headers[__durable_streams_client.PRODUCER_SEQ_HEADER.toLowerCase()];
 		const hasProducerHeaders = producerId !== void 0 || producerEpochStr !== void 0 || producerSeqStr !== void 0;
 		const hasAllProducerHeaders = producerId !== void 0 && producerEpochStr !== void 0 && producerSeqStr !== void 0;
 		if (hasProducerHeaders && !hasAllProducerHeaders) {
@@ -2760,10 +3782,10 @@ var DurableStreamTestServer = class {
 				}
 				if (closeResult$1.producerResult?.status === `duplicate`) {
 					res.writeHead(204, {
-						[STREAM_OFFSET_HEADER]: closeResult$1.finalOffset,
-						[STREAM_CLOSED_HEADER]: `true`,
-						[PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
-						[PRODUCER_SEQ_HEADER]: closeResult$1.producerResult.lastSeq.toString()
+						[__durable_streams_client.STREAM_OFFSET_HEADER]: closeResult$1.finalOffset,
+						[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`,
+						[__durable_streams_client.PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
+						[__durable_streams_client.PRODUCER_SEQ_HEADER]: closeResult$1.producerResult.lastSeq.toString()
 					});
 					res.end();
 					return;
@@ -2771,7 +3793,7 @@ var DurableStreamTestServer = class {
 				if (closeResult$1.producerResult?.status === `stale_epoch`) {
 					res.writeHead(403, {
 						"content-type": `text/plain`,
-						[PRODUCER_EPOCH_HEADER]: closeResult$1.producerResult.currentEpoch.toString()
+						[__durable_streams_client.PRODUCER_EPOCH_HEADER]: closeResult$1.producerResult.currentEpoch.toString()
 					});
 					res.end(`Stale producer epoch`);
 					return;
@@ -2784,8 +3806,8 @@ var DurableStreamTestServer = class {
 				if (closeResult$1.producerResult?.status === `sequence_gap`) {
 					res.writeHead(409, {
 						"content-type": `text/plain`,
-						[PRODUCER_EXPECTED_SEQ_HEADER]: closeResult$1.producerResult.expectedSeq.toString(),
-						[PRODUCER_RECEIVED_SEQ_HEADER]: closeResult$1.producerResult.receivedSeq.toString()
+						[__durable_streams_client.PRODUCER_EXPECTED_SEQ_HEADER]: closeResult$1.producerResult.expectedSeq.toString(),
+						[__durable_streams_client.PRODUCER_RECEIVED_SEQ_HEADER]: closeResult$1.producerResult.receivedSeq.toString()
 					});
 					res.end(`Producer sequence gap`);
 					return;
@@ -2794,17 +3816,17 @@ var DurableStreamTestServer = class {
 					const stream = this.store.get(path);
 					res.writeHead(409, {
 						"content-type": `text/plain`,
-						[STREAM_CLOSED_HEADER]: `true`,
-						[STREAM_OFFSET_HEADER]: stream?.currentOffset ?? ``
+						[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`,
+						[__durable_streams_client.STREAM_OFFSET_HEADER]: stream?.currentOffset ?? ``
 					});
 					res.end(`Stream is closed`);
 					return;
 				}
 				res.writeHead(204, {
-					[STREAM_OFFSET_HEADER]: closeResult$1.finalOffset,
-					[STREAM_CLOSED_HEADER]: `true`,
-					[PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
-					[PRODUCER_SEQ_HEADER]: producerSeq.toString()
+					[__durable_streams_client.STREAM_OFFSET_HEADER]: closeResult$1.finalOffset,
+					[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`,
+					[__durable_streams_client.PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
+					[__durable_streams_client.PRODUCER_SEQ_HEADER]: producerSeq.toString()
 				});
 				res.end();
 				return;
@@ -2816,8 +3838,8 @@ var DurableStreamTestServer = class {
 				return;
 			}
 			res.writeHead(204, {
-				[STREAM_OFFSET_HEADER]: closeResult.finalOffset,
-				[STREAM_CLOSED_HEADER]: `true`
+				[__durable_streams_client.STREAM_OFFSET_HEADER]: closeResult.finalOffset,
+				[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`
 			});
 			res.end();
 			return;
@@ -2850,10 +3872,10 @@ var DurableStreamTestServer = class {
 				if (producerResult?.status === `duplicate`) {
 					const stream = this.store.get(path);
 					res.writeHead(204, {
-						[STREAM_OFFSET_HEADER]: stream?.currentOffset ?? ``,
-						[STREAM_CLOSED_HEADER]: `true`,
-						[PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
-						[PRODUCER_SEQ_HEADER]: producerResult.lastSeq.toString()
+						[__durable_streams_client.STREAM_OFFSET_HEADER]: stream?.currentOffset ?? ``,
+						[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`,
+						[__durable_streams_client.PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
+						[__durable_streams_client.PRODUCER_SEQ_HEADER]: producerResult.lastSeq.toString()
 					});
 					res.end();
 					return;
@@ -2861,29 +3883,30 @@ var DurableStreamTestServer = class {
 				const closedStream = this.store.get(path);
 				res.writeHead(409, {
 					"content-type": `text/plain`,
-					[STREAM_CLOSED_HEADER]: `true`,
-					[STREAM_OFFSET_HEADER]: closedStream?.currentOffset ?? ``
+					[__durable_streams_client.STREAM_CLOSED_HEADER]: `true`,
+					[__durable_streams_client.STREAM_OFFSET_HEADER]: closedStream?.currentOffset ?? ``
 				});
 				res.end(`Stream is closed`);
 				return;
 			}
 			if (!producerResult || producerResult.status === `accepted`) {
-				const responseHeaders$1 = { [STREAM_OFFSET_HEADER]: message$1.offset };
-				if (producerEpoch !== void 0) responseHeaders$1[PRODUCER_EPOCH_HEADER] = producerEpoch.toString();
-				if (producerSeq !== void 0) responseHeaders$1[PRODUCER_SEQ_HEADER] = producerSeq.toString();
-				if (streamClosed) responseHeaders$1[STREAM_CLOSED_HEADER] = `true`;
+				const responseHeaders$1 = { [__durable_streams_client.STREAM_OFFSET_HEADER]: message$1.offset };
+				if (producerEpoch !== void 0) responseHeaders$1[__durable_streams_client.PRODUCER_EPOCH_HEADER] = producerEpoch.toString();
+				if (producerSeq !== void 0) responseHeaders$1[__durable_streams_client.PRODUCER_SEQ_HEADER] = producerSeq.toString();
+				if (streamClosed) responseHeaders$1[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 				const statusCode = producerId !== void 0 ? 200 : 204;
 				res.writeHead(statusCode, responseHeaders$1);
 				res.end();
+				await this.notifyStreamAppend(path);
 				return;
 			}
 			switch (producerResult.status) {
 				case `duplicate`: {
 					const dupHeaders = {
-						[PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
-						[PRODUCER_SEQ_HEADER]: producerResult.lastSeq.toString()
+						[__durable_streams_client.PRODUCER_EPOCH_HEADER]: producerEpoch.toString(),
+						[__durable_streams_client.PRODUCER_SEQ_HEADER]: producerResult.lastSeq.toString()
 					};
-					if (streamClosed) dupHeaders[STREAM_CLOSED_HEADER] = `true`;
+					if (streamClosed) dupHeaders[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 					res.writeHead(204, dupHeaders);
 					res.end();
 					return;
@@ -2891,7 +3914,7 @@ var DurableStreamTestServer = class {
 				case `stale_epoch`: {
 					res.writeHead(403, {
 						"content-type": `text/plain`,
-						[PRODUCER_EPOCH_HEADER]: producerResult.currentEpoch.toString()
+						[__durable_streams_client.PRODUCER_EPOCH_HEADER]: producerResult.currentEpoch.toString()
 					});
 					res.end(`Stale producer epoch`);
 					return;
@@ -2903,18 +3926,27 @@ var DurableStreamTestServer = class {
 				case `sequence_gap`:
 					res.writeHead(409, {
 						"content-type": `text/plain`,
-						[PRODUCER_EXPECTED_SEQ_HEADER]: producerResult.expectedSeq.toString(),
-						[PRODUCER_RECEIVED_SEQ_HEADER]: producerResult.receivedSeq.toString()
+						[__durable_streams_client.PRODUCER_EXPECTED_SEQ_HEADER]: producerResult.expectedSeq.toString(),
+						[__durable_streams_client.PRODUCER_RECEIVED_SEQ_HEADER]: producerResult.receivedSeq.toString()
 					});
 					res.end(`Producer sequence gap`);
 					return;
 			}
 		}
 		const message = result;
-		const responseHeaders = { [STREAM_OFFSET_HEADER]: message.offset };
-		if (closeStream) responseHeaders[STREAM_CLOSED_HEADER] = `true`;
+		const responseHeaders = { [__durable_streams_client.STREAM_OFFSET_HEADER]: message.offset };
+		if (closeStream) responseHeaders[__durable_streams_client.STREAM_CLOSED_HEADER] = `true`;
 		res.writeHead(204, responseHeaders);
 		res.end();
+		await this.notifyStreamAppend(path);
+	}
+	async notifyStreamAppend(path) {
+		if (!this.subscriptionManager) return;
+		try {
+			await this.subscriptionManager.onStreamAppend(path);
+		} catch (err) {
+			serverLog.error(`[server] subscription append hook failed:`, err);
+		}
 	}
 	/**
 	* Handle DELETE - delete stream
@@ -2937,6 +3969,7 @@ var DurableStreamTestServer = class {
 			path,
 			timestamp: Date.now()
 		}));
+		if (this.subscriptionManager) this.subscriptionManager.onStreamDeleted(path);
 		res.writeHead(204);
 		res.end();
 	}
@@ -3071,9 +4104,13 @@ exports.DEFAULT_CURSOR_INTERVAL_SECONDS = DEFAULT_CURSOR_INTERVAL_SECONDS
 exports.DurableStreamTestServer = DurableStreamTestServer
 exports.FileBackedStreamStore = FileBackedStreamStore
 exports.StreamStore = StreamStore
+exports.SubscriptionManager = SubscriptionManager
+exports.SubscriptionRoutes = SubscriptionRoutes
 exports.calculateCursor = calculateCursor
 exports.createRegistryHooks = createRegistryHooks
 exports.decodeStreamPath = decodeStreamPath
 exports.encodeStreamPath = encodeStreamPath
 exports.generateResponseCursor = generateResponseCursor
-exports.handleCursorCollision = handleCursorCollision
+exports.globMatch = globMatch
+exports.handleCursorCollision = handleCursorCollision
+exports.validateWebhookUrl = validateWebhookUrl