@durable-streams/server 0.2.3 → 0.3.0

package/dist/index.cjs

@@ -103,72 +103,180 @@ var StreamStore = class {
 			if (!Number.isFinite(expiryTime) || now >= expiryTime) return true;
 		}
 		if (stream.ttlSeconds !== void 0) {
-			const expiryTime = stream.createdAt + stream.ttlSeconds * 1e3;
+			const expiryTime = stream.lastAccessedAt + stream.ttlSeconds * 1e3;
 			if (now >= expiryTime) return true;
 		}
 		return false;
 	}
 	/**
-	* Get a stream, deleting it if expired.
-	* Returns undefined if stream doesn't exist or is expired.
+	* Get a stream, handling expiry.
+	* Returns undefined if stream doesn't exist or is expired (and has no refs).
+	* Expired streams with refCount > 0 are soft-deleted instead of fully deleted.
 	*/
 	getIfNotExpired(path) {
 		const stream = this.streams.get(path);
 		if (!stream) return void 0;
 		if (this.isExpired(stream)) {
+			if (stream.refCount > 0) {
+				stream.softDeleted = true;
+				return stream;
+			}
 			this.delete(path);
 			return void 0;
 		}
 		return stream;
 	}
 	/**
+	* Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+	*/
+	touchAccess(path) {
+		const stream = this.streams.get(path);
+		if (stream) stream.lastAccessedAt = Date.now();
+	}
+	/**
 	* Create a new stream.
 	* @throws Error if stream already exists with different config
+	* @throws Error if fork source not found, soft-deleted, or offset invalid
 	* @returns existing stream if config matches (idempotent)
 	*/
 	create(path, options = {}) {
-		const existing = this.getIfNotExpired(path);
-		if (existing) {
-			const contentTypeMatches = (normalizeContentType(options.contentType) || `application/octet-stream`) === (normalizeContentType(existing.contentType) || `application/octet-stream`);
-			const ttlMatches = options.ttlSeconds === existing.ttlSeconds;
-			const expiresMatches = options.expiresAt === existing.expiresAt;
-			const closedMatches = (options.closed ?? false) === (existing.closed ?? false);
-			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches) return existing;
+		const existingRaw = this.streams.get(path);
+		if (existingRaw) if (this.isExpired(existingRaw)) {
+			this.streams.delete(path);
+			this.cancelLongPollsForStream(path);
+		} else if (existingRaw.softDeleted) throw new Error(`Stream has active forks — path cannot be reused until all forks are removed: ${path}`);
+		else {
+			const contentTypeMatches = (normalizeContentType(options.contentType) || `application/octet-stream`) === (normalizeContentType(existingRaw.contentType) || `application/octet-stream`);
+			const ttlMatches = options.ttlSeconds === existingRaw.ttlSeconds;
+			const expiresMatches = options.expiresAt === existingRaw.expiresAt;
+			const closedMatches = (options.closed ?? false) === (existingRaw.closed ?? false);
+			const forkedFromMatches = (options.forkedFrom ?? void 0) === existingRaw.forkedFrom;
+			const forkOffsetMatches = options.forkOffset === void 0 || options.forkOffset === existingRaw.forkOffset;
+			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches && forkedFromMatches && forkOffsetMatches) return existingRaw;
 			else throw new Error(`Stream already exists with different configuration: ${path}`);
 		}
+		const isFork = !!options.forkedFrom;
+		let forkOffset = `0000000000000000_0000000000000000`;
+		let sourceContentType;
+		let sourceStream;
+		if (isFork) {
+			sourceStream = this.streams.get(options.forkedFrom);
+			if (!sourceStream) throw new Error(`Source stream not found: ${options.forkedFrom}`);
+			if (sourceStream.softDeleted) throw new Error(`Source stream is soft-deleted: ${options.forkedFrom}`);
+			if (this.isExpired(sourceStream)) throw new Error(`Source stream not found: ${options.forkedFrom}`);
+			sourceContentType = sourceStream.contentType;
+			if (options.forkOffset) forkOffset = options.forkOffset;
+			else forkOffset = sourceStream.currentOffset;
+			const zeroOffset = `0000000000000000_0000000000000000`;
+			if (forkOffset < zeroOffset || sourceStream.currentOffset < forkOffset) throw new Error(`Invalid fork offset: ${forkOffset}`);
+			sourceStream.refCount++;
+		}
+		let contentType = options.contentType;
+		if (!contentType || contentType.trim() === ``) {
+			if (isFork) contentType = sourceContentType;
+		} else if (isFork && normalizeContentType(contentType) !== normalizeContentType(sourceContentType)) throw new Error(`Content type mismatch with source stream`);
+		let effectiveExpiresAt = options.expiresAt;
+		let effectiveTtlSeconds = options.ttlSeconds;
+		if (isFork) {
+			const resolved = this.resolveForkExpiry(options, sourceStream);
+			effectiveExpiresAt = resolved.expiresAt;
+			effectiveTtlSeconds = resolved.ttlSeconds;
+		}
 		const stream = {
 			path,
-			contentType: options.contentType,
+			contentType,
 			messages: [],
-			currentOffset: `0000000000000000_0000000000000000`,
-			ttlSeconds: options.ttlSeconds,
-			expiresAt: options.expiresAt,
+			currentOffset: isFork ? forkOffset : `0000000000000000_0000000000000000`,
+			ttlSeconds: effectiveTtlSeconds,
+			expiresAt: effectiveExpiresAt,
 			createdAt: Date.now(),
-			closed: options.closed ?? false
+			lastAccessedAt: Date.now(),
+			closed: options.closed ?? false,
+			refCount: 0,
+			forkedFrom: isFork ? options.forkedFrom : void 0,
+			forkOffset: isFork ? forkOffset : void 0
 		};
-		if (options.initialData && options.initialData.length > 0) this.appendToStream(stream, options.initialData, true);
+		if (options.initialData && options.initialData.length > 0) try {
+			this.appendToStream(stream, options.initialData, true);
+		} catch (err) {
+			if (isFork && sourceStream) sourceStream.refCount--;
+			throw err;
+		}
 		this.streams.set(path, stream);
 		return stream;
 	}
 	/**
+	* Resolve fork expiry per the decision table.
+	* Forks have independent lifetimes — no capping at source expiry.
+	*/
+	resolveForkExpiry(opts, sourceMeta) {
+		if (opts.ttlSeconds !== void 0) return { ttlSeconds: opts.ttlSeconds };
+		if (opts.expiresAt) return { expiresAt: opts.expiresAt };
+		if (sourceMeta.ttlSeconds !== void 0) return { ttlSeconds: sourceMeta.ttlSeconds };
+		if (sourceMeta.expiresAt) return { expiresAt: sourceMeta.expiresAt };
+		return {};
+	}
+	/**
 	* Get a stream by path.
 	* Returns undefined if stream doesn't exist or is expired.
+	* Returns soft-deleted streams (caller should check stream.softDeleted).
 	*/
 	get(path) {
-		return this.getIfNotExpired(path);
+		const stream = this.streams.get(path);
+		if (!stream) return void 0;
+		if (this.isExpired(stream)) {
+			if (stream.refCount > 0) {
+				stream.softDeleted = true;
+				return stream;
+			}
+			this.delete(path);
+			return void 0;
+		}
+		return stream;
 	}
 	/**
-	* Check if a stream exists (and is not expired).
+	* Check if a stream exists, is not expired, and is not soft-deleted.
 	*/
 	has(path) {
-		return this.getIfNotExpired(path) !== void 0;
+		const stream = this.get(path);
+		if (!stream) return false;
+		if (stream.softDeleted) return false;
+		return true;
 	}
 	/**
 	* Delete a stream.
+	* If the stream has forks (refCount > 0), it is soft-deleted instead of fully removed.
+	* Returns true if the stream was found and deleted (or soft-deleted).
 	*/
 	delete(path) {
+		const stream = this.streams.get(path);
+		if (!stream) return false;
+		if (stream.softDeleted) return true;
+		if (stream.refCount > 0) {
+			stream.softDeleted = true;
+			return true;
+		}
+		this.deleteWithCascade(path);
+		return true;
+	}
+	/**
+	* Fully delete a stream and cascade to soft-deleted parents
+	* whose refcount drops to zero.
+	*/
+	deleteWithCascade(path) {
+		const stream = this.streams.get(path);
+		if (!stream) return;
+		const forkedFrom = stream.forkedFrom;
+		this.streams.delete(path);
 		this.cancelLongPollsForStream(path);
-		return this.streams.delete(path);
+		if (forkedFrom) {
+			const parent = this.streams.get(forkedFrom);
+			if (parent) {
+				parent.refCount--;
+				if (parent.refCount < 0) parent.refCount = 0;
+				if (parent.refCount === 0 && parent.softDeleted) this.deleteWithCascade(forkedFrom);
+			}
+		}
 	}
 	/**
 	* Validate producer state WITHOUT mutating.
@@ -281,6 +389,7 @@ var StreamStore = class {
 	append(path, data, options = {}) {
 		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
+		if (stream.softDeleted) throw new Error(`Stream is soft-deleted: ${path}`);
 		if (stream.closed) {
 			if (options.producerId && stream.closedBy && stream.closedBy.producerId === options.producerId && stream.closedBy.epoch === options.producerEpoch && stream.closedBy.seq === options.producerSeq) return {
 				message: null,
@@ -357,6 +466,7 @@ var StreamStore = class {
 	closeStream(path) {
 		const stream = this.getIfNotExpired(path);
 		if (!stream) return null;
+		if (stream.softDeleted) throw new Error(`Stream is soft-deleted: ${path}`);
 		const alreadyClosed = stream.closed ?? false;
 		stream.closed = true;
 		this.notifyLongPollsClosed(path);
@@ -424,15 +534,26 @@ var StreamStore = class {
 	}
 	/**
 	* Read messages from a stream starting at the given offset.
+	* For forked streams, stitches messages from the source chain and the fork's own messages.
 	* @throws Error if stream doesn't exist or is expired
 	*/
 	read(path, offset) {
 		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
-		if (!offset || offset === `-1`) return {
-			messages: [...stream.messages],
-			upToDate: true
-		};
+		if (!offset || offset === `-1`) {
+			if (stream.forkedFrom) {
+				const inherited = this.readForkedMessages(stream.forkedFrom, void 0, stream.forkOffset);
+				return {
+					messages: [...inherited, ...stream.messages],
+					upToDate: true
+				};
+			}
+			return {
+				messages: [...stream.messages],
+				upToDate: true
+			};
+		}
+		if (stream.forkedFrom) return this.readFromFork(stream, offset);
 		const offsetIndex = this.findOffsetIndex(stream, offset);
 		if (offsetIndex === -1) return {
 			messages: [],
@@ -444,6 +565,55 @@ var StreamStore = class {
 		};
 	}
 	/**
+	* Read from a forked stream, stitching inherited and own messages.
+	*/
+	readFromFork(stream, offset) {
+		const messages = [];
+		if (offset < stream.forkOffset) {
+			const inherited = this.readForkedMessages(stream.forkedFrom, offset, stream.forkOffset);
+			messages.push(...inherited);
+		}
+		const ownMessages = this.readOwnMessages(stream, offset);
+		messages.push(...ownMessages);
+		return {
+			messages,
+			upToDate: true
+		};
+	}
+	/**
+	* Read a stream's own messages starting after the given offset.
+	*/
+	readOwnMessages(stream, offset) {
+		const offsetIndex = this.findOffsetIndex(stream, offset);
+		if (offsetIndex === -1) return [];
+		return stream.messages.slice(offsetIndex);
+	}
+	/**
+	* Recursively read messages from a fork's source chain.
+	* Reads from source (and its sources if also forked), capped at forkOffset.
+	* Does NOT check softDeleted — forks must read through soft-deleted sources.
+	*/
+	readForkedMessages(sourcePath, offset, capOffset) {
+		const source = this.streams.get(sourcePath);
+		if (!source) return [];
+		const messages = [];
+		if (source.forkedFrom && (!offset || offset < source.forkOffset)) {
+			const inherited = this.readForkedMessages(
+				source.forkedFrom,
+				offset,
+				// Cap at the minimum of source's forkOffset and our capOffset
+				source.forkOffset < capOffset ? source.forkOffset : capOffset
+);
+			messages.push(...inherited);
+		}
+		for (const msg of source.messages) {
+			if (offset && msg.offset <= offset) continue;
+			if (msg.offset > capOffset) break;
+			messages.push(msg);
+		}
+		return messages;
+	}
+	/**
 	* Format messages for response.
 	* For JSON mode, wraps concatenated data in array brackets.
 	* @throws Error if stream doesn't exist or is expired
@@ -468,6 +638,13 @@ var StreamStore = class {
 	async waitForMessages(path, offset, timeoutMs) {
 		const stream = this.getIfNotExpired(path);
 		if (!stream) throw new Error(`Stream not found: ${path}`);
+		if (stream.forkedFrom && offset < stream.forkOffset) {
+			const { messages: messages$1 } = this.read(path, offset);
+			return {
+				messages: messages$1,
+				timedOut: false
+			};
+		}
 		const { messages } = this.read(path, offset);
 		if (messages.length > 0) return {
 			messages,
@@ -843,7 +1020,14 @@ var FileBackedStreamStore = class {
 				errors++;
 				continue;
 			}
-			const trueOffset = this.scanFileForTrueOffset(segmentPath);
+			const physicalOffset = this.scanFileForTrueOffset(segmentPath);
+			const physicalBytes = Number(physicalOffset.split(`_`)[1] ?? 0);
+			let trueOffset;
+			if (streamMeta.forkOffset) {
+				const forkBaseByte = Number(streamMeta.forkOffset.split(`_`)[1] ?? 0);
+				const logicalBytes = forkBaseByte + physicalBytes;
+				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.`);
 				const reconciledMeta = {
@@ -902,9 +1086,14 @@ var FileBackedStreamStore = class {
 			ttlSeconds: meta.ttlSeconds,
 			expiresAt: meta.expiresAt,
 			createdAt: meta.createdAt,
+			lastAccessedAt: meta.lastAccessedAt ?? meta.createdAt,
 			producers,
 			closed: meta.closed,
-			closedBy: meta.closedBy
+			closedBy: meta.closedBy,
+			forkedFrom: meta.forkedFrom,
+			forkOffset: meta.forkOffset,
+			refCount: meta.refCount ?? 0,
+			softDeleted: meta.softDeleted
 		};
 	}
 	/**
@@ -1000,6 +1189,20 @@ var FileBackedStreamStore = class {
 		return meta.producers[producerId]?.epoch;
 	}
 	/**
+	* Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+	*/
+	touchAccess(streamPath) {
+		const key = `stream:${streamPath}`;
+		const meta = this.db.get(key);
+		if (meta) {
+			const updatedMeta = {
+				...meta,
+				lastAccessedAt: Date.now()
+			};
+			this.db.putSync(key, updatedMeta);
+		}
+	}
+	/**
 	* Check if a stream is expired based on TTL or Expires-At.
 	*/
 	isExpired(meta) {
@@ -1009,26 +1212,50 @@ var FileBackedStreamStore = class {
 			if (!Number.isFinite(expiryTime) || now >= expiryTime) return true;
 		}
 		if (meta.ttlSeconds !== void 0) {
-			const expiryTime = meta.createdAt + meta.ttlSeconds * 1e3;
+			const lastAccessed = meta.lastAccessedAt ?? meta.createdAt;
+			const expiryTime = lastAccessed + meta.ttlSeconds * 1e3;
 			if (now >= expiryTime) return true;
 		}
 		return false;
 	}
 	/**
 	* Get stream metadata, deleting it if expired.
-	* Returns undefined if stream doesn't exist or is expired.
+	* Returns undefined if stream doesn't exist or is expired (and has no refs).
+	* Expired streams with refCount > 0 are soft-deleted instead of fully deleted.
 	*/
 	getMetaIfNotExpired(streamPath) {
 		const key = `stream:${streamPath}`;
 		const meta = this.db.get(key);
 		if (!meta) return void 0;
 		if (this.isExpired(meta)) {
+			if ((meta.refCount ?? 0) > 0) {
+				if (!meta.softDeleted) {
+					const updatedMeta = {
+						...meta,
+						softDeleted: true
+					};
+					this.db.putSync(key, updatedMeta);
+					return updatedMeta;
+				}
+				return meta;
+			}
 			this.delete(streamPath);
 			return void 0;
 		}
 		return meta;
 	}
 	/**
+	* Resolve fork expiry per the decision table.
+	* Forks have independent lifetimes — no capping at source expiry.
+	*/
+	resolveForkExpiry(opts, sourceMeta) {
+		if (opts.ttlSeconds !== void 0) return { ttlSeconds: opts.ttlSeconds };
+		if (opts.expiresAt) return { expiresAt: opts.expiresAt };
+		if (sourceMeta.ttlSeconds !== void 0) return { ttlSeconds: sourceMeta.ttlSeconds };
+		if (sourceMeta.expiresAt) return { expiresAt: sourceMeta.expiresAt };
+		return {};
+	}
+	/**
 	* Close the store, closing all file handles and database.
 	* All data is already fsynced on each append, so no final flush needed.
 	*/
@@ -1037,29 +1264,70 @@ var FileBackedStreamStore = class {
 		await this.db.close();
 	}
 	async create(streamPath, options = {}) {
-		const existing = this.getMetaIfNotExpired(streamPath);
-		if (existing) {
+		const existingRaw = this.db.get(`stream:${streamPath}`);
+		if (existingRaw) if (this.isExpired(existingRaw)) this.delete(streamPath);
+		else if (existingRaw.softDeleted) throw new Error(`Stream has active forks — path cannot be reused until all forks are removed: ${streamPath}`);
+		else {
 			const normalizeMimeType = (ct) => (ct ?? `application/octet-stream`).toLowerCase();
-			const contentTypeMatches = normalizeMimeType(options.contentType) === normalizeMimeType(existing.contentType);
-			const ttlMatches = options.ttlSeconds === existing.ttlSeconds;
-			const expiresMatches = options.expiresAt === existing.expiresAt;
-			const closedMatches = (options.closed ?? false) === (existing.closed ?? false);
-			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches) return this.streamMetaToStream(existing);
+			const contentTypeMatches = normalizeMimeType(options.contentType) === normalizeMimeType(existingRaw.contentType);
+			const ttlMatches = options.ttlSeconds === existingRaw.ttlSeconds;
+			const expiresMatches = options.expiresAt === existingRaw.expiresAt;
+			const closedMatches = (options.closed ?? false) === (existingRaw.closed ?? false);
+			const forkedFromMatches = (options.forkedFrom ?? void 0) === existingRaw.forkedFrom;
+			const forkOffsetMatches = options.forkOffset === void 0 || options.forkOffset === existingRaw.forkOffset;
+			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches && forkedFromMatches && forkOffsetMatches) return this.streamMetaToStream(existingRaw);
 			else throw new Error(`Stream already exists with different configuration: ${streamPath}`);
 		}
+		const isFork = !!options.forkedFrom;
+		let forkOffset = `0000000000000000_0000000000000000`;
+		let sourceContentType;
+		let sourceMeta;
+		if (isFork) {
+			const sourceKey = `stream:${options.forkedFrom}`;
+			sourceMeta = this.db.get(sourceKey);
+			if (!sourceMeta) throw new Error(`Source stream not found: ${options.forkedFrom}`);
+			if (sourceMeta.softDeleted) throw new Error(`Source stream is soft-deleted: ${options.forkedFrom}`);
+			if (this.isExpired(sourceMeta)) throw new Error(`Source stream not found: ${options.forkedFrom}`);
+			sourceContentType = sourceMeta.contentType;
+			if (options.forkOffset) forkOffset = options.forkOffset;
+			else forkOffset = sourceMeta.currentOffset;
+			const zeroOffset = `0000000000000000_0000000000000000`;
+			if (forkOffset < zeroOffset || sourceMeta.currentOffset < forkOffset) throw new Error(`Invalid fork offset: ${forkOffset}`);
+			const freshSource = this.db.get(sourceKey);
+			const updatedSource = {
+				...freshSource,
+				refCount: (freshSource.refCount ?? 0) + 1
+			};
+			this.db.putSync(sourceKey, updatedSource);
+		}
+		let contentType = options.contentType;
+		if (!contentType || contentType.trim() === ``) {
+			if (isFork) contentType = sourceContentType;
+		} else if (isFork && normalizeContentType(contentType) !== normalizeContentType(sourceContentType)) throw new Error(`Content type mismatch with source stream`);
+		let effectiveExpiresAt = options.expiresAt;
+		let effectiveTtlSeconds = options.ttlSeconds;
+		if (isFork) {
+			const resolved = this.resolveForkExpiry(options, sourceMeta);
+			effectiveExpiresAt = resolved.expiresAt;
+			effectiveTtlSeconds = resolved.ttlSeconds;
+		}
 		const key = `stream:${streamPath}`;
 		const streamMeta = {
 			path: streamPath,
-			contentType: options.contentType,
-			currentOffset: `0000000000000000_0000000000000000`,
+			contentType,
+			currentOffset: isFork ? forkOffset : `0000000000000000_0000000000000000`,
 			lastSeq: void 0,
-			ttlSeconds: options.ttlSeconds,
-			expiresAt: options.expiresAt,
+			ttlSeconds: effectiveTtlSeconds,
+			expiresAt: effectiveExpiresAt,
 			createdAt: Date.now(),
+			lastAccessedAt: Date.now(),
 			segmentCount: 1,
 			totalBytes: 0,
 			directoryName: generateUniqueDirectoryName(streamPath),
-			closed: false
+			closed: false,
+			forkedFrom: isFork ? options.forkedFrom : void 0,
+			forkOffset: isFork ? forkOffset : void 0,
+			refCount: 0
 		};
 		const streamDir = node_path.join(this.dataDir, `streams`, streamMeta.directoryName);
 		try {
@@ -1067,14 +1335,40 @@ var FileBackedStreamStore = class {
 			const segmentPath = node_path.join(streamDir, `segment_00000.log`);
 			node_fs.writeFileSync(segmentPath, ``);
 		} catch (err) {
+			if (isFork && sourceMeta) {
+				const sourceKey = `stream:${options.forkedFrom}`;
+				const freshSource = this.db.get(sourceKey);
+				if (freshSource) {
+					const updatedSource = {
+						...freshSource,
+						refCount: Math.max(0, (freshSource.refCount ?? 0) - 1)
+					};
+					this.db.putSync(sourceKey, updatedSource);
+				}
+			}
 			console.error(`[FileBackedStreamStore] Error creating stream directory:`, err);
 			throw err;
 		}
 		this.db.putSync(key, streamMeta);
-		if (options.initialData && options.initialData.length > 0) await this.append(streamPath, options.initialData, {
-			contentType: options.contentType,
-			isInitialCreate: true
-		});
+		if (options.initialData && options.initialData.length > 0) try {
+			await this.append(streamPath, options.initialData, {
+				contentType: options.contentType,
+				isInitialCreate: true
+			});
+		} catch (err) {
+			if (isFork && sourceMeta) {
+				const sourceKey = `stream:${options.forkedFrom}`;
+				const freshSource = this.db.get(sourceKey);
+				if (freshSource) {
+					const updatedSource = {
+						...freshSource,
+						refCount: Math.max(0, (freshSource.refCount ?? 0) - 1)
+					};
+					this.db.putSync(sourceKey, updatedSource);
+				}
+			}
+			throw err;
+		}
 		if (options.closed) {
 			const updatedMeta = this.db.get(key);
 			updatedMeta.closed = true;
@@ -1085,15 +1379,41 @@ var FileBackedStreamStore = class {
 	}
 	get(streamPath) {
 		const meta = this.getMetaIfNotExpired(streamPath);
-		return meta ? this.streamMetaToStream(meta) : void 0;
+		if (!meta) return void 0;
+		return this.streamMetaToStream(meta);
 	}
 	has(streamPath) {
-		return this.getMetaIfNotExpired(streamPath) !== void 0;
+		const meta = this.getMetaIfNotExpired(streamPath);
+		if (!meta) return false;
+		if (meta.softDeleted) return false;
+		return true;
 	}
 	delete(streamPath) {
 		const key = `stream:${streamPath}`;
 		const streamMeta = this.db.get(key);
 		if (!streamMeta) return false;
+		if (streamMeta.softDeleted) return true;
+		if ((streamMeta.refCount ?? 0) > 0) {
+			const updatedMeta = {
+				...streamMeta,
+				softDeleted: true
+			};
+			this.db.putSync(key, updatedMeta);
+			this.cancelLongPollsForStream(streamPath);
+			return true;
+		}
+		this.deleteWithCascade(streamPath);
+		return true;
+	}
+	/**
+	* Fully delete a stream and cascade to soft-deleted parents
+	* whose refcount drops to zero.
+	*/
+	deleteWithCascade(streamPath) {
+		const key = `stream:${streamPath}`;
+		const streamMeta = this.db.get(key);
+		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) => {
@@ -1103,11 +1423,24 @@ var FileBackedStreamStore = class {
 		this.fileManager.deleteDirectoryByName(streamMeta.directoryName).catch((err) => {
 			console.error(`[FileBackedStreamStore] Error deleting stream directory:`, err);
 		});
-		return true;
+		if (forkedFrom) {
+			const parentKey = `stream:${forkedFrom}`;
+			const parentMeta = this.db.get(parentKey);
+			if (parentMeta) {
+				const newRefCount = Math.max(0, (parentMeta.refCount ?? 0) - 1);
+				const updatedParent = {
+					...parentMeta,
+					refCount: newRefCount
+				};
+				this.db.putSync(parentKey, updatedParent);
+				if (newRefCount === 0 && updatedParent.softDeleted) this.deleteWithCascade(forkedFrom);
+			}
+		}
 	}
 	async append(streamPath, data, options = {}) {
 		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		if (streamMeta.softDeleted) throw new Error(`Stream is soft-deleted: ${streamPath}`);
 		if (streamMeta.closed) {
 			if (options.producerId && streamMeta.closedBy && streamMeta.closedBy.producerId === options.producerId && streamMeta.closedBy.epoch === options.producerEpoch && streamMeta.closedBy.seq === options.producerSeq) return {
 				message: null,
@@ -1292,34 +1625,21 @@ var FileBackedStreamStore = class {
 			releaseLock();
 		}
 	}
-	read(streamPath, offset) {
-		const streamMeta = this.getMetaIfNotExpired(streamPath);
-		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
-		const startOffset = offset ?? `0000000000000000_0000000000000000`;
-		const startParts = startOffset.split(`_`).map(Number);
-		const startByte = startParts[1] ?? 0;
-		const currentParts = streamMeta.currentOffset.split(`_`).map(Number);
-		const currentSeq = currentParts[0] ?? 0;
-		const currentByte = currentParts[1] ?? 0;
-		if (streamMeta.currentOffset === `0000000000000000_0000000000000000`) return {
-			messages: [],
-			upToDate: true
-		};
-		if (startByte >= currentByte) return {
-			messages: [],
-			upToDate: true
-		};
-		const streamDir = node_path.join(this.dataDir, `streams`, streamMeta.directoryName);
-		const segmentPath = node_path.join(streamDir, `segment_00000.log`);
-		if (!node_fs.existsSync(segmentPath)) return {
-			messages: [],
-			upToDate: true
-		};
+	/**
+	* Read messages from a specific segment file.
+	* @param segmentPath - Path to the segment file
+	* @param startByte - Start byte offset (skip messages at or before this offset)
+	* @param baseByteOffset - Base byte offset to add to physical offsets (for fork stitching)
+	* @param capByte - Optional cap: stop reading when logical offset exceeds this value
+	* @returns Array of messages with properly computed offsets
+	*/
+	readMessagesFromSegmentFile(segmentPath, startByte, baseByteOffset, capByte) {
 		const messages = [];
+		if (!node_fs.existsSync(segmentPath)) return messages;
 		try {
 			const fileContent = node_fs.readFileSync(segmentPath);
 			let filePos = 0;
-			let currentDataOffset = 0;
+			let physicalDataOffset = 0;
 			while (filePos < fileContent.length) {
 				if (filePos + 4 > fileContent.length) break;
 				const messageLength = fileContent.readUInt32BE(filePos);
@@ -1328,16 +1648,72 @@ var FileBackedStreamStore = class {
 				const messageData = fileContent.subarray(filePos, filePos + messageLength);
 				filePos += messageLength;
 				filePos += 1;
-				const messageOffset = currentDataOffset + messageLength;
-				if (messageOffset > startByte) messages.push({
+				physicalDataOffset += messageLength;
+				const logicalOffset = baseByteOffset + physicalDataOffset;
+				if (capByte !== void 0 && logicalOffset > capByte) break;
+				if (logicalOffset > startByte) messages.push({
 					data: new Uint8Array(messageData),
-					offset: `${String(currentSeq).padStart(16, `0`)}_${String(messageOffset).padStart(16, `0`)}`,
+					offset: `${String(0).padStart(16, `0`)}_${String(logicalOffset).padStart(16, `0`)}`,
 					timestamp: 0
 				});
-				currentDataOffset = messageOffset;
 			}
 		} catch (err) {
-			console.error(`[FileBackedStreamStore] Error reading file:`, err);
+			console.error(`[FileBackedStreamStore] Error reading segment file:`, err);
+		}
+		return messages;
+	}
+	/**
+	* Recursively read messages from a fork's source chain.
+	* Reads from source (and its sources if also forked), capped at capByte.
+	* Does NOT check softDeleted -- forks must read through soft-deleted sources.
+	*/
+	readForkedMessages(sourcePath, startByte, capByte) {
+		const sourceKey = `stream:${sourcePath}`;
+		const sourceMeta = this.db.get(sourceKey);
+		if (!sourceMeta) return [];
+		const messages = [];
+		if (sourceMeta.forkedFrom && sourceMeta.forkOffset) {
+			const sourceForkByte = Number(sourceMeta.forkOffset.split(`_`)[1] ?? 0);
+			if (startByte < sourceForkByte) {
+				const inheritedCap = Math.min(sourceForkByte, capByte);
+				const inherited = this.readForkedMessages(sourceMeta.forkedFrom, startByte, inheritedCap);
+				messages.push(...inherited);
+			}
+		}
+		const segmentPath = node_path.join(this.dataDir, `streams`, sourceMeta.directoryName, `segment_00000.log`);
+		const sourceBaseByte = sourceMeta.forkOffset ? Number(sourceMeta.forkOffset.split(`_`)[1] ?? 0) : 0;
+		const ownMessages = this.readMessagesFromSegmentFile(segmentPath, startByte, sourceBaseByte, capByte);
+		messages.push(...ownMessages);
+		return messages;
+	}
+	read(streamPath, offset) {
+		const streamMeta = this.getMetaIfNotExpired(streamPath);
+		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		const startOffset = offset ?? `0000000000000000_0000000000000000`;
+		const startByte = Number(startOffset.split(`_`)[1] ?? 0);
+		const currentByte = Number(streamMeta.currentOffset.split(`_`)[1] ?? 0);
+		if (streamMeta.currentOffset === `0000000000000000_0000000000000000`) return {
+			messages: [],
+			upToDate: true
+		};
+		if (startByte >= currentByte) return {
+			messages: [],
+			upToDate: true
+		};
+		const messages = [];
+		if (streamMeta.forkedFrom && streamMeta.forkOffset) {
+			const forkByte = Number(streamMeta.forkOffset.split(`_`)[1] ?? 0);
+			if (startByte < forkByte) {
+				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 ownMessages = this.readMessagesFromSegmentFile(segmentPath, startByte, forkByte);
+			messages.push(...ownMessages);
+		} else {
+			const segmentPath = node_path.join(this.dataDir, `streams`, streamMeta.directoryName, `segment_00000.log`);
+			const ownMessages = this.readMessagesFromSegmentFile(segmentPath, startByte, 0);
+			messages.push(...ownMessages);
 		}
 		return {
 			messages,
@@ -1347,6 +1723,13 @@ var FileBackedStreamStore = class {
 	async waitForMessages(streamPath, offset, timeoutMs) {
 		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
+		if (streamMeta.forkedFrom && streamMeta.forkOffset && offset < streamMeta.forkOffset) {
+			const { messages: messages$1 } = this.read(streamPath, offset);
+			return {
+				messages: messages$1,
+				timedOut: false
+			};
+		}
 		if (streamMeta.closed && offset === streamMeta.currentOffset) return {
 			messages: [],
 			timedOut: false,
@@ -1599,6 +1982,8 @@ 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`;
@@ -1813,7 +2198,7 @@ var DurableStreamTestServer = class {
 		const method = req.method?.toUpperCase();
 		res.setHeader(`access-control-allow-origin`, `*`);
 		res.setHeader(`access-control-allow-methods`, `GET, POST, PUT, DELETE, HEAD, OPTIONS`);
-		res.setHeader(`access-control-allow-headers`, `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At, Stream-Closed, Producer-Id, Producer-Epoch, Producer-Seq`);
+		res.setHeader(`access-control-allow-headers`, `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At, Stream-Closed, Producer-Id, Producer-Epoch, Producer-Seq, Stream-Forked-From, Stream-Fork-Offset`);
 		res.setHeader(`access-control-expose-headers`, `Stream-Next-Offset, Stream-Cursor, Stream-Up-To-Date, Stream-Closed, Producer-Epoch, Producer-Seq, Producer-Expected-Seq, Producer-Received-Seq, etag, content-type, content-encoding, vary`);
 		res.setHeader(`x-content-type-options`, `nosniff`);
 		res.setHeader(`cross-origin-resource-policy`, `cross-origin`);
@@ -1864,7 +2249,13 @@ var DurableStreamTestServer = class {
 					res.end(`Method not allowed`);
 			}
 		} catch (err) {
-			if (err instanceof Error) if (err.message.includes(`not found`)) {
+			if (err instanceof Error) if (err.message.includes(`active forks`)) {
+				res.writeHead(409, { "content-type": `text/plain` });
+				res.end(`stream was deleted but still has active forks — path cannot be reused until all forks are removed`);
+			} else if (err.message.includes(`soft-deleted`)) {
+				res.writeHead(410, { "content-type": `text/plain` });
+				res.end(`Stream is gone`);
+			} else if (err.message.includes(`not found`)) {
 				res.writeHead(404, { "content-type": `text/plain` });
 				res.end(`Stream not found`);
 			} else if (err.message.includes(`already exists with different configuration`)) {
@@ -1896,6 +2287,8 @@ var DurableStreamTestServer = class {
 		const expiresAtHeader = req.headers[STREAM_EXPIRES_AT_HEADER.toLowerCase()];
 		const closedHeader = req.headers[STREAM_CLOSED_HEADER.toLowerCase()];
 		const createClosed = closedHeader === `true`;
+		const forkedFromHeader = req.headers[STREAM_FORKED_FROM_HEADER.toLowerCase()];
+		const forkOffsetHeader = req.headers[STREAM_FORK_OFFSET_HEADER.toLowerCase()];
 		if (ttlHeader && expiresAtHeader) {
 			res.writeHead(400, { "content-type": `text/plain` });
 			res.end(`Cannot specify both Stream-TTL and Stream-Expires-At`);
@@ -1924,24 +2317,60 @@ var DurableStreamTestServer = class {
 				return;
 			}
 		}
+		if (forkOffsetHeader) {
+			const validOffsetPattern = /^\d+_\d+$/;
+			if (!validOffsetPattern.test(forkOffsetHeader)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid Stream-Fork-Offset format`);
+				return;
+			}
+		}
 		const body = await this.readBody(req);
 		const isNew = !this.store.has(path);
-		await Promise.resolve(this.store.create(path, {
-			contentType,
-			ttlSeconds,
-			expiresAt: expiresAtHeader,
-			initialData: body.length > 0 ? body : void 0,
-			closed: createClosed
-		}));
+		try {
+			await Promise.resolve(this.store.create(path, {
+				contentType,
+				ttlSeconds,
+				expiresAt: expiresAtHeader,
+				initialData: body.length > 0 ? body : void 0,
+				closed: createClosed,
+				forkedFrom: forkedFromHeader,
+				forkOffset: forkOffsetHeader
+			}));
+		} catch (err) {
+			if (err instanceof Error) {
+				if (err.message.includes(`Source stream not found`)) {
+					res.writeHead(404, { "content-type": `text/plain` });
+					res.end(`Source stream not found`);
+					return;
+				}
+				if (err.message.includes(`Invalid fork offset`)) {
+					res.writeHead(400, { "content-type": `text/plain` });
+					res.end(`Fork offset beyond source stream length`);
+					return;
+				}
+				if (err.message.includes(`soft-deleted`)) {
+					res.writeHead(409, { "content-type": `text/plain` });
+					res.end(`source stream was deleted but still has active forks`);
+					return;
+				}
+				if (err.message.includes(`Content type mismatch`)) {
+					res.writeHead(409, { "content-type": `text/plain` });
+					res.end(`Content type mismatch with source stream`);
+					return;
+				}
+			}
+			throw err;
+		}
 		const stream = this.store.get(path);
 		if (isNew && this.options.onStreamCreated) await Promise.resolve(this.options.onStreamCreated({
 			type: `created`,
 			path,
-			contentType,
+			contentType: stream.contentType ?? contentType,
 			timestamp: Date.now()
 		}));
 		const headers = {
-			"content-type": contentType,
+			"content-type": stream.contentType ?? contentType,
 			[STREAM_OFFSET_HEADER]: stream.currentOffset
 		};
 		if (isNew) headers[`location`] = `${this._url}${path}`;
@@ -1959,12 +2388,19 @@ var DurableStreamTestServer = class {
 			res.end();
 			return;
 		}
+		if (stream.softDeleted) {
+			res.writeHead(410, { "content-type": `text/plain` });
+			res.end();
+			return;
+		}
 		const headers = {
 			[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;
 		const closedSuffix = stream.closed ? `:c` : ``;
 		headers[`etag`] = `"${Buffer.from(path).toString(`base64`)}:-1:${stream.currentOffset}${closedSuffix}"`;
 		res.writeHead(200, headers);
@@ -1980,6 +2416,11 @@ var DurableStreamTestServer = class {
 			res.end(`Stream not found`);
 			return;
 		}
+		if (stream.softDeleted) {
+			res.writeHead(410, { "content-type": `text/plain` });
+			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;
@@ -2034,6 +2475,7 @@ var DurableStreamTestServer = class {
 			return;
 		}
 		let { messages, upToDate } = this.store.read(path, effectiveOffset);
+		this.store.touchAccess(path);
 		const clientIsCaughtUp = effectiveOffset && effectiveOffset === stream.currentOffset || offset === `now`;
 		if (live === `long-poll` && clientIsCaughtUp && messages.length === 0) {
 			if (stream.closed) {
@@ -2046,6 +2488,7 @@ var DurableStreamTestServer = class {
 				return;
 			}
 			const result = await this.store.waitForMessages(path, effectiveOffset ?? stream.currentOffset, this.options.longPollTimeout);
+			this.store.touchAccess(path);
 			if (result.streamClosed) {
 				const responseCursor = generateResponseCursor(cursor, this.options.cursorOptions);
 				res.writeHead(204, {
@@ -2138,6 +2581,7 @@ var DurableStreamTestServer = class {
 		const isJsonStream = stream?.contentType?.includes(`application/json`);
 		while (isConnected && !this.isShuttingDown) {
 			const { messages, upToDate } = this.store.read(path, currentOffset);
+			this.store.touchAccess(path);
 			for (const message of messages) {
 				let dataPayload;
 				if (useBase64) dataPayload = Buffer.from(message.data).toString(`base64`);
@@ -2175,6 +2619,7 @@ var DurableStreamTestServer = class {
 					break;
 				}
 				const result = await this.store.waitForMessages(path, currentOffset, this.options.longPollTimeout);
+				this.store.touchAccess(path);
 				if (this.isShuttingDown || !isConnected) break;
 				if (result.streamClosed) {
 					const finalControlData = {
@@ -2357,6 +2802,7 @@ var DurableStreamTestServer = class {
 		let result;
 		if (producerId !== void 0) result = await this.store.appendWithProducer(path, body, appendOptions);
 		else result = await Promise.resolve(this.store.append(path, body, appendOptions));
+		this.store.touchAccess(path);
 		if (result && typeof result === `object` && `message` in result) {
 			const { message: message$1, producerResult, streamClosed } = result;
 			if (streamClosed && !message$1) {
@@ -2433,12 +2879,18 @@ var DurableStreamTestServer = class {
 	* Handle DELETE - delete stream
 	*/
 	async handleDelete(path, res) {
-		if (!this.store.has(path)) {
+		const existing = this.store.get(path);
+		if (existing?.softDeleted) {
+			res.writeHead(410, { "content-type": `text/plain` });
+			res.end(`Stream is gone`);
+			return;
+		}
+		const deleted = this.store.delete(path);
+		if (!deleted) {
 			res.writeHead(404, { "content-type": `text/plain` });
 			res.end(`Stream not found`);
 			return;
 		}
-		this.store.delete(path);
 		if (this.options.onStreamDeleted) await Promise.resolve(this.options.onStreamDeleted({
 			type: `deleted`,
 			path,