@durable-streams/server 0.3.4 → 0.3.5

package/dist/index.cjs

@@ -170,13 +170,17 @@ var StreamStore = class {
 			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;
+			const requestedSub = options.forkSubOffset ?? 0;
+			const existingSub = existingRaw.forkSubOffset ?? 0;
+			const forkSubOffsetMatches = requestedSub === existingSub;
+			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches && forkedFromMatches && forkOffsetMatches && forkSubOffsetMatches) 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;
+		let forkSubOffsetPrefix;
 		if (isFork) {
 			sourceStream = this.streams.get(options.forkedFrom);
 			if (!sourceStream) throw new Error(`Source stream not found: ${options.forkedFrom}`);
@@ -187,6 +191,7 @@ var StreamStore = class {
 			else forkOffset = sourceStream.currentOffset;
 			const zeroOffset = `0000000000000000_0000000000000000`;
 			if (forkOffset < zeroOffset || sourceStream.currentOffset < forkOffset) throw new Error(`Invalid fork offset: ${forkOffset}`);
+			if (options.forkSubOffset && options.forkSubOffset > 0) forkSubOffsetPrefix = this.resolveForkSubOffset(sourceStream, forkOffset, options.forkSubOffset, normalizeContentType(sourceContentType) === `application/json`);
 			sourceStream.refCount++;
 		}
 		let contentType = options.contentType;
@@ -214,6 +219,20 @@ var StreamStore = class {
 			forkedFrom: isFork ? options.forkedFrom : void 0,
 			forkOffset: isFork ? forkOffset : void 0
 		};
+		if (forkSubOffsetPrefix && forkSubOffsetPrefix.length > 0) {
+			const parts = stream.currentOffset.split(`_`).map(Number);
+			const readSeq = parts[0];
+			const byteOffset = parts[1];
+			const newByteOffset = byteOffset + forkSubOffsetPrefix.length + 5;
+			const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
+			stream.messages.push({
+				data: forkSubOffsetPrefix,
+				offset: newOffset,
+				timestamp: Date.now()
+			});
+			stream.currentOffset = newOffset;
+			stream.forkSubOffset = options.forkSubOffset;
+		}
 		if (options.initialData && options.initialData.length > 0) try {
 			this.appendToStream(stream, options.initialData, true);
 		} catch (err) {
@@ -737,6 +756,36 @@ var StreamStore = class {
 	list() {
 		return Array.from(this.streams.keys());
 	}
+	/**
+	* Resolve a sub-offset against a source stream and return the prefix bytes
+	* to materialize as the fork's first own message. Reads from the source
+	* (across its fork chain if any) starting at forkOffset; the first message
+	* returned is the one that starts at forkOffset. Throws if the sub-offset
+	* cannot be satisfied (no message past forkOffset, or overshoots its
+	* content extent).
+	*/
+	resolveForkSubOffset(sourceStream, forkOffset, subOffset, isJSON) {
+		let sourceMessages;
+		if (sourceStream.forkedFrom) sourceMessages = [...this.readForkedMessages(sourceStream.forkedFrom, forkOffset, sourceStream.forkOffset), ...this.readOwnMessages(sourceStream, forkOffset)];
+		else sourceMessages = this.readOwnMessages(sourceStream, forkOffset);
+		if (sourceMessages.length === 0) throw new Error(`Invalid fork sub-offset: no data past forkOffset`);
+		const first = sourceMessages[0];
+		if (isJSON) {
+			const text = new TextDecoder().decode(first.data);
+			const trimmed = text.endsWith(`,`) ? text.slice(0, -1) : text;
+			let values;
+			try {
+				values = JSON.parse(`[${trimmed}]`);
+			} catch {
+				throw new Error(`Invalid fork sub-offset: source JSON is unparseable`);
+			}
+			if (subOffset > values.length) throw new Error(`Invalid fork sub-offset: overshoots source message count`);
+			const prefix = values.slice(0, subOffset).map((v) => JSON.stringify(v));
+			return new TextEncoder().encode(prefix.join(`,`) + `,`);
+		}
+		if (subOffset > first.data.length) throw new Error(`Invalid fork sub-offset: overshoots source message length`);
+		return first.data.slice(0, subOffset);
+	}
 	appendToStream(stream, data, isInitialCreate = false) {
 		let processedData = data;
 		if (normalizeContentType(stream.contentType) === `application/json`) {
@@ -1318,13 +1367,17 @@ var FileBackedStreamStore = class {
 			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);
+			const requestedSub = options.forkSubOffset ?? 0;
+			const existingSub = existingRaw.forkSubOffset ?? 0;
+			const forkSubOffsetMatches = requestedSub === existingSub;
+			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches && forkedFromMatches && forkOffsetMatches && forkSubOffsetMatches) 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;
+		let forkSubOffsetPrefix;
 		if (isFork) {
 			const sourceKey = `stream:${options.forkedFrom}`;
 			sourceMeta = this.db.get(sourceKey);
@@ -1336,6 +1389,7 @@ var FileBackedStreamStore = class {
 			else forkOffset = sourceMeta.currentOffset;
 			const zeroOffset = `0000000000000000_0000000000000000`;
 			if (forkOffset < zeroOffset || sourceMeta.currentOffset < forkOffset) throw new Error(`Invalid fork offset: ${forkOffset}`);
+			if (options.forkSubOffset && options.forkSubOffset > 0) forkSubOffsetPrefix = this.resolveForkSubOffset(options.forkedFrom, forkOffset, options.forkSubOffset, normalizeContentType(sourceContentType) === `application/json`);
 			const freshSource = this.db.get(sourceKey);
 			const updatedSource = {
 				...freshSource,
@@ -1371,11 +1425,39 @@ var FileBackedStreamStore = class {
 			closed: false,
 			forkedFrom: isFork ? options.forkedFrom : void 0,
 			forkOffset: isFork ? forkOffset : void 0,
+			forkSubOffset: void 0,
 			refCount: 0
 		};
 		const tAfterMeta = performance.now();
 		const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 		try {
+			if (forkSubOffsetPrefix && forkSubOffsetPrefix.length > 0) {
+				const lengthBuf = Buffer.allocUnsafe(4);
+				lengthBuf.writeUInt32BE(forkSubOffsetPrefix.length, 0);
+				const frameBuf = Buffer.concat([
+					lengthBuf,
+					Buffer.from(forkSubOffsetPrefix),
+					Buffer.from(`\n`)
+				]);
+				const fd = node_fs.openSync(segmentPath, `wx`);
+				try {
+					let written = 0;
+					while (written < frameBuf.length) {
+						const bytesWritten = node_fs.writeSync(fd, frameBuf, written, frameBuf.length - written, written);
+						if (bytesWritten === 0) throw new Error(`failed to write sub-offset prefix frame`);
+						written += bytesWritten;
+					}
+					node_fs.fsyncSync(fd);
+				} finally {
+					node_fs.closeSync(fd);
+				}
+				const parts = streamMeta.currentOffset.split(`_`).map(Number);
+				const readSeq = parts[0];
+				const byteOffset = parts[1];
+				const newByteOffset = byteOffset + forkSubOffsetPrefix.length + 5;
+				streamMeta.currentOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
+				streamMeta.forkSubOffset = options.forkSubOffset;
+			}
 			await this.db.put(key, streamMeta);
 		} catch (err) {
 			if (isFork && sourceMeta) {
@@ -1389,7 +1471,7 @@ var FileBackedStreamStore = class {
 					this.db.putSync(sourceKey, updatedSource);
 				}
 			}
-			serverLog.error(`[FileBackedStreamStore] Error creating stream (LMDB put):`, err);
+			serverLog.error(`[FileBackedStreamStore] Error creating stream before metadata commit:`, err);
 			throw err;
 		}
 		const tAfterLmdb = performance.now();
@@ -1774,6 +1856,35 @@ var FileBackedStreamStore = class {
 		messages.push(...ownMessages);
 		return messages;
 	}
+	/**
+	* Resolve a fork sub-offset against the source: read the message that
+	* starts at forkOffset and return prefix bytes to materialize as the
+	* fork's first own message. For JSON, parses comma-joined values.
+	*/
+	resolveForkSubOffset(sourcePath, forkOffset, subOffset, isJSON) {
+		const forkByte = Number(forkOffset.split(`_`)[1] ?? 0);
+		const sourceMeta = this.db.get(`stream:${sourcePath}`);
+		if (!sourceMeta) throw new Error(`Source stream not found: ${sourcePath}`);
+		const currentByte = Number(sourceMeta.currentOffset.split(`_`)[1] ?? 0);
+		const messages = this.readForkedMessages(sourcePath, forkByte, currentByte);
+		if (messages.length === 0) throw new Error(`Invalid fork sub-offset: no data past forkOffset`);
+		const first = messages[0];
+		if (isJSON) {
+			const text = new TextDecoder().decode(first.data);
+			const trimmed = text.endsWith(`,`) ? text.slice(0, -1) : text;
+			let values;
+			try {
+				values = JSON.parse(`[${trimmed}]`);
+			} catch {
+				throw new Error(`Invalid fork sub-offset: source JSON is unparseable`);
+			}
+			if (subOffset > values.length) throw new Error(`Invalid fork sub-offset: overshoots source message count`);
+			const prefix = values.slice(0, subOffset).map((v) => JSON.stringify(v));
+			return new TextEncoder().encode(prefix.join(`,`) + `,`);
+		}
+		if (subOffset > first.data.length) throw new Error(`Invalid fork sub-offset: overshoots source message length`);
+		return first.data.slice(0, subOffset);
+	}
 	read(streamPath, offset) {
 		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
@@ -3030,6 +3141,7 @@ const STREAM_SSE_DATA_ENCODING_HEADER = `Stream-SSE-Data-Encoding`;
 const SSE_UP_TO_DATE_FIELD = `upToDate`;
 const STREAM_FORKED_FROM_HEADER = `Stream-Forked-From`;
 const STREAM_FORK_OFFSET_HEADER = `Stream-Fork-Offset`;
+const STREAM_FORK_SUB_OFFSET_HEADER = `Stream-Fork-Sub-Offset`;
 /**
 * Encode data for SSE format.
 * Per SSE spec, each line in the payload needs its own "data:" prefix.
@@ -3255,7 +3367,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, Stream-Forked-From, Stream-Fork-Offset`);
+		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, Stream-Fork-Sub-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`);
@@ -3345,6 +3457,9 @@ var DurableStreamTestServer = class {
 		let contentType = req.headers[`content-type`];
 		const forkedFromHeader = req.headers[STREAM_FORKED_FROM_HEADER.toLowerCase()];
 		const forkOffsetHeader = req.headers[STREAM_FORK_OFFSET_HEADER.toLowerCase()];
+		const forkSubOffsetHeaderRaw = req.headers[STREAM_FORK_SUB_OFFSET_HEADER.toLowerCase()];
+		const forkSubOffsetHeaderPresent = forkSubOffsetHeaderRaw !== void 0;
+		const forkSubOffsetHeader = Array.isArray(forkSubOffsetHeaderRaw) ? forkSubOffsetHeaderRaw[0] : forkSubOffsetHeaderRaw;
 		if (!contentType || contentType.trim() === `` || !/^[\w-]+\/[\w-]+/.test(contentType)) contentType = forkedFromHeader ? void 0 : `application/octet-stream`;
 		const ttlHeader = req.headers[__durable_streams_client.STREAM_TTL_HEADER.toLowerCase()];
 		const expiresAtHeader = req.headers[__durable_streams_client.STREAM_EXPIRES_AT_HEADER.toLowerCase()];
@@ -3386,6 +3501,21 @@ var DurableStreamTestServer = class {
 				return;
 			}
 		}
+		let forkSubOffset;
+		if (forkSubOffsetHeaderPresent) {
+			if (!forkedFromHeader) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Stream-Fork-Sub-Offset requires Stream-Forked-From`);
+				return;
+			}
+			const subOffsetPattern = /^(0|[1-9]\d*)$/;
+			if (forkSubOffsetHeader === void 0 || !subOffsetPattern.test(forkSubOffsetHeader)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid Stream-Fork-Sub-Offset format`);
+				return;
+			}
+			forkSubOffset = parseInt(forkSubOffsetHeader, 10);
+		}
 		const body = await this.readBody(req);
 		const isNew = !this.store.has(path);
 		try {
@@ -3396,7 +3526,8 @@ var DurableStreamTestServer = class {
 				initialData: body.length > 0 ? body : void 0,
 				closed: createClosed,
 				forkedFrom: forkedFromHeader,
-				forkOffset: forkOffsetHeader
+				forkOffset: forkOffsetHeader,
+				forkSubOffset
 			}));
 		} catch (err) {
 			if (err instanceof Error) {
@@ -3405,6 +3536,11 @@ var DurableStreamTestServer = class {
 					res.end(`Source stream not found`);
 					return;
 				}
+				if (err.message.includes(`Invalid fork sub-offset`)) {
+					res.writeHead(400, { "content-type": `text/plain` });
+					res.end(`Invalid fork sub-offset`);
+					return;
+				}
 				if (err.message.includes(`Invalid fork offset`)) {
 					res.writeHead(400, { "content-type": `text/plain` });
 					res.end(`Fork offset beyond source stream length`);

package/dist/index.d.cts

@@ -99,6 +99,13 @@ interface Stream {
   */
   forkOffset?: string;
   /**
+  * User-supplied sub-offset value refining `forkOffset` (Section 4.2 of
+  * PROTOCOL.md). Stored verbatim for idempotent re-creation matching:
+  * bytes for non-JSON forks, flattened message count for JSON forks.
+  * `undefined` and `0` are equivalent.
+  */
+  forkSubOffset?: number;
+  /**
   * Number of forks referencing this stream.
   * Defaults to 0.
   */
@@ -313,6 +320,7 @@ declare class StreamStore {
     closed?: boolean;
     forkedFrom?: string;
     forkOffset?: string;
+    forkSubOffset?: number;
   }): Stream;
   /**
   * Resolve fork expiry per the decision table.
@@ -459,6 +467,15 @@ declare class StreamStore {
   * Get all stream paths.
   */
   list(): Array<string>;
+  /**
+  * Resolve a sub-offset against a source stream and return the prefix bytes
+  * to materialize as the fork's first own message. Reads from the source
+  * (across its fork chain if any) starting at forkOffset; the first message
+  * returned is the one that starts at forkOffset. Throws if the sub-offset
+  * cannot be satisfied (no message past forkOffset, or overshoots its
+  * content extent).
+  */
+  private resolveForkSubOffset;
   private appendToStream;
   private findOffsetIndex;
   private notifyLongPolls;
@@ -571,6 +588,7 @@ declare class FileBackedStreamStore {
     closed?: boolean;
     forkedFrom?: string;
     forkOffset?: string;
+    forkSubOffset?: number;
   }): Promise<Stream>;
   get(streamPath: string): Stream | undefined;
   has(streamPath: string): boolean;
@@ -631,6 +649,12 @@ declare class FileBackedStreamStore {
   * Does NOT check softDeleted -- forks must read through soft-deleted sources.
   */
   private readForkedMessages;
+  /**
+  * Resolve a fork sub-offset against the source: read the message that
+  * starts at forkOffset and return prefix bytes to materialize as the
+  * fork's first own message. For JSON, parses comma-joined values.
+  */
+  private resolveForkSubOffset;
   read(streamPath: string, offset?: string): {
     messages: Array<StreamMessage>;
     upToDate: boolean;

package/dist/index.d.ts

@@ -99,6 +99,13 @@ interface Stream {
   */
   forkOffset?: string;
   /**
+  * User-supplied sub-offset value refining `forkOffset` (Section 4.2 of
+  * PROTOCOL.md). Stored verbatim for idempotent re-creation matching:
+  * bytes for non-JSON forks, flattened message count for JSON forks.
+  * `undefined` and `0` are equivalent.
+  */
+  forkSubOffset?: number;
+  /**
   * Number of forks referencing this stream.
   * Defaults to 0.
   */
@@ -313,6 +320,7 @@ declare class StreamStore {
     closed?: boolean;
     forkedFrom?: string;
     forkOffset?: string;
+    forkSubOffset?: number;
   }): Stream;
   /**
   * Resolve fork expiry per the decision table.
@@ -459,6 +467,15 @@ declare class StreamStore {
   * Get all stream paths.
   */
   list(): Array<string>;
+  /**
+  * Resolve a sub-offset against a source stream and return the prefix bytes
+  * to materialize as the fork's first own message. Reads from the source
+  * (across its fork chain if any) starting at forkOffset; the first message
+  * returned is the one that starts at forkOffset. Throws if the sub-offset
+  * cannot be satisfied (no message past forkOffset, or overshoots its
+  * content extent).
+  */
+  private resolveForkSubOffset;
   private appendToStream;
   private findOffsetIndex;
   private notifyLongPolls;
@@ -571,6 +588,7 @@ declare class FileBackedStreamStore {
     closed?: boolean;
     forkedFrom?: string;
     forkOffset?: string;
+    forkSubOffset?: number;
   }): Promise<Stream>;
   get(streamPath: string): Stream | undefined;
   has(streamPath: string): boolean;
@@ -631,6 +649,12 @@ declare class FileBackedStreamStore {
   * Does NOT check softDeleted -- forks must read through soft-deleted sources.
   */
   private readForkedMessages;
+  /**
+  * Resolve a fork sub-offset against the source: read the message that
+  * starts at forkOffset and return prefix bytes to materialize as the
+  * fork's first own message. For JSON, parses comma-joined values.
+  */
+  private resolveForkSubOffset;
   read(streamPath: string, offset?: string): {
     messages: Array<StreamMessage>;
     upToDate: boolean;

package/dist/index.js

@@ -146,13 +146,17 @@ var StreamStore = class {
 			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;
+			const requestedSub = options.forkSubOffset ?? 0;
+			const existingSub = existingRaw.forkSubOffset ?? 0;
+			const forkSubOffsetMatches = requestedSub === existingSub;
+			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches && forkedFromMatches && forkOffsetMatches && forkSubOffsetMatches) return existingRaw;
 			else throw new Error(`Stream already exists with different configuration: ${path$1}`);
 		}
 		const isFork = !!options.forkedFrom;
 		let forkOffset = `0000000000000000_0000000000000000`;
 		let sourceContentType;
 		let sourceStream;
+		let forkSubOffsetPrefix;
 		if (isFork) {
 			sourceStream = this.streams.get(options.forkedFrom);
 			if (!sourceStream) throw new Error(`Source stream not found: ${options.forkedFrom}`);
@@ -163,6 +167,7 @@ var StreamStore = class {
 			else forkOffset = sourceStream.currentOffset;
 			const zeroOffset = `0000000000000000_0000000000000000`;
 			if (forkOffset < zeroOffset || sourceStream.currentOffset < forkOffset) throw new Error(`Invalid fork offset: ${forkOffset}`);
+			if (options.forkSubOffset && options.forkSubOffset > 0) forkSubOffsetPrefix = this.resolveForkSubOffset(sourceStream, forkOffset, options.forkSubOffset, normalizeContentType(sourceContentType) === `application/json`);
 			sourceStream.refCount++;
 		}
 		let contentType = options.contentType;
@@ -190,6 +195,20 @@ var StreamStore = class {
 			forkedFrom: isFork ? options.forkedFrom : void 0,
 			forkOffset: isFork ? forkOffset : void 0
 		};
+		if (forkSubOffsetPrefix && forkSubOffsetPrefix.length > 0) {
+			const parts = stream.currentOffset.split(`_`).map(Number);
+			const readSeq = parts[0];
+			const byteOffset = parts[1];
+			const newByteOffset = byteOffset + forkSubOffsetPrefix.length + 5;
+			const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
+			stream.messages.push({
+				data: forkSubOffsetPrefix,
+				offset: newOffset,
+				timestamp: Date.now()
+			});
+			stream.currentOffset = newOffset;
+			stream.forkSubOffset = options.forkSubOffset;
+		}
 		if (options.initialData && options.initialData.length > 0) try {
 			this.appendToStream(stream, options.initialData, true);
 		} catch (err) {
@@ -713,6 +732,36 @@ var StreamStore = class {
 	list() {
 		return Array.from(this.streams.keys());
 	}
+	/**
+	* Resolve a sub-offset against a source stream and return the prefix bytes
+	* to materialize as the fork's first own message. Reads from the source
+	* (across its fork chain if any) starting at forkOffset; the first message
+	* returned is the one that starts at forkOffset. Throws if the sub-offset
+	* cannot be satisfied (no message past forkOffset, or overshoots its
+	* content extent).
+	*/
+	resolveForkSubOffset(sourceStream, forkOffset, subOffset, isJSON) {
+		let sourceMessages;
+		if (sourceStream.forkedFrom) sourceMessages = [...this.readForkedMessages(sourceStream.forkedFrom, forkOffset, sourceStream.forkOffset), ...this.readOwnMessages(sourceStream, forkOffset)];
+		else sourceMessages = this.readOwnMessages(sourceStream, forkOffset);
+		if (sourceMessages.length === 0) throw new Error(`Invalid fork sub-offset: no data past forkOffset`);
+		const first = sourceMessages[0];
+		if (isJSON) {
+			const text = new TextDecoder().decode(first.data);
+			const trimmed = text.endsWith(`,`) ? text.slice(0, -1) : text;
+			let values;
+			try {
+				values = JSON.parse(`[${trimmed}]`);
+			} catch {
+				throw new Error(`Invalid fork sub-offset: source JSON is unparseable`);
+			}
+			if (subOffset > values.length) throw new Error(`Invalid fork sub-offset: overshoots source message count`);
+			const prefix = values.slice(0, subOffset).map((v) => JSON.stringify(v));
+			return new TextEncoder().encode(prefix.join(`,`) + `,`);
+		}
+		if (subOffset > first.data.length) throw new Error(`Invalid fork sub-offset: overshoots source message length`);
+		return first.data.slice(0, subOffset);
+	}
 	appendToStream(stream, data, isInitialCreate = false) {
 		let processedData = data;
 		if (normalizeContentType(stream.contentType) === `application/json`) {
@@ -1294,13 +1343,17 @@ var FileBackedStreamStore = class {
 			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);
+			const requestedSub = options.forkSubOffset ?? 0;
+			const existingSub = existingRaw.forkSubOffset ?? 0;
+			const forkSubOffsetMatches = requestedSub === existingSub;
+			if (contentTypeMatches && ttlMatches && expiresMatches && closedMatches && forkedFromMatches && forkOffsetMatches && forkSubOffsetMatches) 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;
+		let forkSubOffsetPrefix;
 		if (isFork) {
 			const sourceKey = `stream:${options.forkedFrom}`;
 			sourceMeta = this.db.get(sourceKey);
@@ -1312,6 +1365,7 @@ var FileBackedStreamStore = class {
 			else forkOffset = sourceMeta.currentOffset;
 			const zeroOffset = `0000000000000000_0000000000000000`;
 			if (forkOffset < zeroOffset || sourceMeta.currentOffset < forkOffset) throw new Error(`Invalid fork offset: ${forkOffset}`);
+			if (options.forkSubOffset && options.forkSubOffset > 0) forkSubOffsetPrefix = this.resolveForkSubOffset(options.forkedFrom, forkOffset, options.forkSubOffset, normalizeContentType(sourceContentType) === `application/json`);
 			const freshSource = this.db.get(sourceKey);
 			const updatedSource = {
 				...freshSource,
@@ -1347,11 +1401,39 @@ var FileBackedStreamStore = class {
 			closed: false,
 			forkedFrom: isFork ? options.forkedFrom : void 0,
 			forkOffset: isFork ? forkOffset : void 0,
+			forkSubOffset: void 0,
 			refCount: 0
 		};
 		const tAfterMeta = performance.now();
 		const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName);
 		try {
+			if (forkSubOffsetPrefix && forkSubOffsetPrefix.length > 0) {
+				const lengthBuf = Buffer.allocUnsafe(4);
+				lengthBuf.writeUInt32BE(forkSubOffsetPrefix.length, 0);
+				const frameBuf = Buffer.concat([
+					lengthBuf,
+					Buffer.from(forkSubOffsetPrefix),
+					Buffer.from(`\n`)
+				]);
+				const fd = fs.openSync(segmentPath, `wx`);
+				try {
+					let written = 0;
+					while (written < frameBuf.length) {
+						const bytesWritten = fs.writeSync(fd, frameBuf, written, frameBuf.length - written, written);
+						if (bytesWritten === 0) throw new Error(`failed to write sub-offset prefix frame`);
+						written += bytesWritten;
+					}
+					fs.fsyncSync(fd);
+				} finally {
+					fs.closeSync(fd);
+				}
+				const parts = streamMeta.currentOffset.split(`_`).map(Number);
+				const readSeq = parts[0];
+				const byteOffset = parts[1];
+				const newByteOffset = byteOffset + forkSubOffsetPrefix.length + 5;
+				streamMeta.currentOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`;
+				streamMeta.forkSubOffset = options.forkSubOffset;
+			}
 			await this.db.put(key, streamMeta);
 		} catch (err) {
 			if (isFork && sourceMeta) {
@@ -1365,7 +1447,7 @@ var FileBackedStreamStore = class {
 					this.db.putSync(sourceKey, updatedSource);
 				}
 			}
-			serverLog.error(`[FileBackedStreamStore] Error creating stream (LMDB put):`, err);
+			serverLog.error(`[FileBackedStreamStore] Error creating stream before metadata commit:`, err);
 			throw err;
 		}
 		const tAfterLmdb = performance.now();
@@ -1750,6 +1832,35 @@ var FileBackedStreamStore = class {
 		messages.push(...ownMessages);
 		return messages;
 	}
+	/**
+	* Resolve a fork sub-offset against the source: read the message that
+	* starts at forkOffset and return prefix bytes to materialize as the
+	* fork's first own message. For JSON, parses comma-joined values.
+	*/
+	resolveForkSubOffset(sourcePath, forkOffset, subOffset, isJSON) {
+		const forkByte = Number(forkOffset.split(`_`)[1] ?? 0);
+		const sourceMeta = this.db.get(`stream:${sourcePath}`);
+		if (!sourceMeta) throw new Error(`Source stream not found: ${sourcePath}`);
+		const currentByte = Number(sourceMeta.currentOffset.split(`_`)[1] ?? 0);
+		const messages = this.readForkedMessages(sourcePath, forkByte, currentByte);
+		if (messages.length === 0) throw new Error(`Invalid fork sub-offset: no data past forkOffset`);
+		const first = messages[0];
+		if (isJSON) {
+			const text = new TextDecoder().decode(first.data);
+			const trimmed = text.endsWith(`,`) ? text.slice(0, -1) : text;
+			let values;
+			try {
+				values = JSON.parse(`[${trimmed}]`);
+			} catch {
+				throw new Error(`Invalid fork sub-offset: source JSON is unparseable`);
+			}
+			if (subOffset > values.length) throw new Error(`Invalid fork sub-offset: overshoots source message count`);
+			const prefix = values.slice(0, subOffset).map((v) => JSON.stringify(v));
+			return new TextEncoder().encode(prefix.join(`,`) + `,`);
+		}
+		if (subOffset > first.data.length) throw new Error(`Invalid fork sub-offset: overshoots source message length`);
+		return first.data.slice(0, subOffset);
+	}
 	read(streamPath, offset) {
 		const streamMeta = this.getMetaIfNotExpired(streamPath);
 		if (!streamMeta) throw new Error(`Stream not found: ${streamPath}`);
@@ -3006,6 +3117,7 @@ const STREAM_SSE_DATA_ENCODING_HEADER = `Stream-SSE-Data-Encoding`;
 const SSE_UP_TO_DATE_FIELD = `upToDate`;
 const STREAM_FORKED_FROM_HEADER = `Stream-Forked-From`;
 const STREAM_FORK_OFFSET_HEADER = `Stream-Fork-Offset`;
+const STREAM_FORK_SUB_OFFSET_HEADER = `Stream-Fork-Sub-Offset`;
 /**
 * Encode data for SSE format.
 * Per SSE spec, each line in the payload needs its own "data:" prefix.
@@ -3231,7 +3343,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, Stream-Forked-From, Stream-Fork-Offset`);
+		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, Stream-Fork-Sub-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`);
@@ -3321,6 +3433,9 @@ var DurableStreamTestServer = class {
 		let contentType = req.headers[`content-type`];
 		const forkedFromHeader = req.headers[STREAM_FORKED_FROM_HEADER.toLowerCase()];
 		const forkOffsetHeader = req.headers[STREAM_FORK_OFFSET_HEADER.toLowerCase()];
+		const forkSubOffsetHeaderRaw = req.headers[STREAM_FORK_SUB_OFFSET_HEADER.toLowerCase()];
+		const forkSubOffsetHeaderPresent = forkSubOffsetHeaderRaw !== void 0;
+		const forkSubOffsetHeader = Array.isArray(forkSubOffsetHeaderRaw) ? forkSubOffsetHeaderRaw[0] : forkSubOffsetHeaderRaw;
 		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()];
@@ -3362,6 +3477,21 @@ var DurableStreamTestServer = class {
 				return;
 			}
 		}
+		let forkSubOffset;
+		if (forkSubOffsetHeaderPresent) {
+			if (!forkedFromHeader) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Stream-Fork-Sub-Offset requires Stream-Forked-From`);
+				return;
+			}
+			const subOffsetPattern = /^(0|[1-9]\d*)$/;
+			if (forkSubOffsetHeader === void 0 || !subOffsetPattern.test(forkSubOffsetHeader)) {
+				res.writeHead(400, { "content-type": `text/plain` });
+				res.end(`Invalid Stream-Fork-Sub-Offset format`);
+				return;
+			}
+			forkSubOffset = parseInt(forkSubOffsetHeader, 10);
+		}
 		const body = await this.readBody(req);
 		const isNew = !this.store.has(path$1);
 		try {
@@ -3372,7 +3502,8 @@ var DurableStreamTestServer = class {
 				initialData: body.length > 0 ? body : void 0,
 				closed: createClosed,
 				forkedFrom: forkedFromHeader,
-				forkOffset: forkOffsetHeader
+				forkOffset: forkOffsetHeader,
+				forkSubOffset
 			}));
 		} catch (err) {
 			if (err instanceof Error) {
@@ -3381,6 +3512,11 @@ var DurableStreamTestServer = class {
 					res.end(`Source stream not found`);
 					return;
 				}
+				if (err.message.includes(`Invalid fork sub-offset`)) {
+					res.writeHead(400, { "content-type": `text/plain` });
+					res.end(`Invalid fork sub-offset`);
+					return;
+				}
 				if (err.message.includes(`Invalid fork offset`)) {
 					res.writeHead(400, { "content-type": `text/plain` });
 					res.end(`Fork offset beyond source stream length`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@durable-streams/server",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Node.js reference server implementation for Durable Streams",
   "author": "Durable Stream contributors",
   "license": "Apache-2.0",
@@ -39,15 +39,15 @@
   "dependencies": {
     "@neophi/sieve-cache": "^1.0.0",
     "lmdb": "^3.3.0",
-    "@durable-streams/client": "0.2.5",
-    "@durable-streams/state": "0.2.8"
+    "@durable-streams/client": "0.2.6",
+    "@durable-streams/state": "0.2.9"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
     "tsdown": "^0.9.0",
     "typescript": "^5.0.0",
     "vitest": "^4.0.0",
-    "@durable-streams/server-conformance-tests": "0.3.3"
+    "@durable-streams/server-conformance-tests": "0.3.4"
   },
   "files": [
     "dist",

package/src/file-store.ts

@@ -87,6 +87,12 @@ interface StreamMetadata {
    * Divergence offset from the source stream.
    */
   forkOffset?: string
+  /**
+   * User-supplied sub-offset value refining `forkOffset` (Section 4.2 of
+   * PROTOCOL.md). Stored verbatim for idempotent re-creation matching:
+   * bytes for non-JSON forks, flattened message count for JSON forks.
+   */
+  forkSubOffset?: number
   /**
    * Number of forks referencing this stream.
    * Defaults to 0. Optional for backward-compatible deserialization from LMDB.
@@ -726,6 +732,7 @@ export class FileBackedStreamStore {
       closed?: boolean
       forkedFrom?: string
       forkOffset?: string
+      forkSubOffset?: number
     } = {}
   ): Promise<Stream> {
     // Use getMetaIfNotExpired to treat expired streams as non-existent
@@ -762,6 +769,12 @@ export class FileBackedStreamStore {
         const forkOffsetMatches =
           options.forkOffset === undefined ||
           options.forkOffset === existingRaw.forkOffset
+        // Sub-offset: undefined and 0 are equivalent. Compare the raw
+        // user-supplied integer (count for JSON, bytes for binary) so the
+        // comparison is independent of how it was resolved internally.
+        const requestedSub = options.forkSubOffset ?? 0
+        const existingSub = existingRaw.forkSubOffset ?? 0
+        const forkSubOffsetMatches = requestedSub === existingSub
 
         if (
           contentTypeMatches &&
@@ -769,7 +782,8 @@ export class FileBackedStreamStore {
           expiresMatches &&
           closedMatches &&
           forkedFromMatches &&
-          forkOffsetMatches
+          forkOffsetMatches &&
+          forkSubOffsetMatches
         ) {
           // Idempotent success - return existing stream
           return this.streamMetaToStream(existingRaw)
@@ -787,6 +801,7 @@ export class FileBackedStreamStore {
     let forkOffset = `0000000000000000_0000000000000000`
     let sourceContentType: string | undefined
     let sourceMeta: StreamMetadata | undefined
+    let forkSubOffsetPrefix: Uint8Array | undefined
 
     if (isFork) {
       const sourceKey = `stream:${options.forkedFrom!}`
@@ -816,6 +831,17 @@ export class FileBackedStreamStore {
         throw new Error(`Invalid fork offset: ${forkOffset}`)
       }
 
+      // Resolve sub-offset against the source. Returns the prefix bytes to
+      // materialize as the fork's first own message.
+      if (options.forkSubOffset && options.forkSubOffset > 0) {
+        forkSubOffsetPrefix = this.resolveForkSubOffset(
+          options.forkedFrom!,
+          forkOffset,
+          options.forkSubOffset,
+          normalizeContentType(sourceContentType) === `application/json`
+        )
+      }
+
       // Atomically increment source refcount in LMDB
       const freshSource = this.db.get(sourceKey) as StreamMetadata
       const updatedSource: StreamMetadata = {
@@ -871,6 +897,7 @@ export class FileBackedStreamStore {
       closed: false, // Set to false initially, will be updated after initial append if needed
       forkedFrom: isFork ? options.forkedFrom : undefined,
       forkOffset: isFork ? forkOffset : undefined,
+      forkSubOffset: undefined,
       refCount: 0,
     }
 
@@ -878,6 +905,52 @@ export class FileBackedStreamStore {
 
     const segmentPath = segmentFile(this.dataDir, streamMeta.directoryName)
     try {
+      // Materialize the sub-offset prefix as the first framed message
+      // in the new segment before persisting metadata or opening the
+      // write stream. The prefix must be fsynced before the LMDB commit
+      // so metadata never acknowledges bytes that are not durable.
+      if (forkSubOffsetPrefix && forkSubOffsetPrefix.length > 0) {
+        const lengthBuf = Buffer.allocUnsafe(4)
+        lengthBuf.writeUInt32BE(forkSubOffsetPrefix.length, 0)
+        const frameBuf = Buffer.concat([
+          lengthBuf,
+          Buffer.from(forkSubOffsetPrefix),
+          Buffer.from(`\n`),
+        ])
+
+        const fd = fs.openSync(segmentPath, `wx`)
+        try {
+          let written = 0
+          while (written < frameBuf.length) {
+            const bytesWritten = fs.writeSync(
+              fd,
+              frameBuf,
+              written,
+              frameBuf.length - written,
+              written
+            )
+            if (bytesWritten === 0) {
+              throw new Error(`failed to write sub-offset prefix frame`)
+            }
+            written += bytesWritten
+          }
+          fs.fsyncSync(fd)
+        } finally {
+          fs.closeSync(fd)
+        }
+
+        const parts = streamMeta.currentOffset.split(`_`).map(Number)
+        const readSeq = parts[0]!
+        const byteOffset = parts[1]!
+        // Match append()'s frame-inclusive offset advance (4-byte length
+        // prefix + payload + 1-byte newline) so reads with a capByte don't
+        // truncate the materialized prefix when later chained-fork resolves.
+        const newByteOffset = byteOffset + forkSubOffsetPrefix.length + 5
+        streamMeta.currentOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`
+        // Persist the user-supplied sub-offset verbatim for idempotent
+        // re-creation matching, not the encoded byte length.
+        streamMeta.forkSubOffset = options.forkSubOffset
+      }
       await this.db.put(key, streamMeta)
     } catch (err) {
       // Rollback source refcount on failure
@@ -893,7 +966,7 @@ export class FileBackedStreamStore {
         }
       }
       serverLog.error(
-        `[FileBackedStreamStore] Error creating stream (LMDB put):`,
+        `[FileBackedStreamStore] Error creating stream before metadata commit:`,
         err
       )
       throw err
@@ -1589,6 +1662,57 @@ export class FileBackedStreamStore {
     return messages
   }
 
+  /**
+   * Resolve a fork sub-offset against the source: read the message that
+   * starts at forkOffset and return prefix bytes to materialize as the
+   * fork's first own message. For JSON, parses comma-joined values.
+   */
+  private resolveForkSubOffset(
+    sourcePath: string,
+    forkOffset: string,
+    subOffset: number,
+    isJSON: boolean
+  ): Uint8Array {
+    const forkByte = Number(forkOffset.split(`_`)[1] ?? 0)
+    // Read source past forkOffset (cap at source's currentOffset by passing
+    // a large cap; we only care about the first message past forkOffset).
+    const sourceMeta = this.db.get(`stream:${sourcePath}`) as
+      | StreamMetadata
+      | undefined
+    if (!sourceMeta) {
+      throw new Error(`Source stream not found: ${sourcePath}`)
+    }
+    const currentByte = Number(sourceMeta.currentOffset.split(`_`)[1] ?? 0)
+    const messages = this.readForkedMessages(sourcePath, forkByte, currentByte)
+    if (messages.length === 0) {
+      throw new Error(`Invalid fork sub-offset: no data past forkOffset`)
+    }
+    const first = messages[0]!
+    if (isJSON) {
+      const text = new TextDecoder().decode(first.data)
+      const trimmed = text.endsWith(`,`) ? text.slice(0, -1) : text
+      let values: Array<unknown>
+      try {
+        values = JSON.parse(`[${trimmed}]`)
+      } catch {
+        throw new Error(`Invalid fork sub-offset: source JSON is unparseable`)
+      }
+      if (subOffset > values.length) {
+        throw new Error(
+          `Invalid fork sub-offset: overshoots source message count`
+        )
+      }
+      const prefix = values.slice(0, subOffset).map((v) => JSON.stringify(v))
+      return new TextEncoder().encode(prefix.join(`,`) + `,`)
+    }
+    if (subOffset > first.data.length) {
+      throw new Error(
+        `Invalid fork sub-offset: overshoots source message length`
+      )
+    }
+    return first.data.slice(0, subOffset)
+  }
+
   read(
     streamPath: string,
     offset?: string

package/src/server.ts

@@ -42,6 +42,7 @@ const SSE_UP_TO_DATE_FIELD = `upToDate`
 // Fork headers (request headers only — not set on responses)
 const STREAM_FORKED_FROM_HEADER = `Stream-Forked-From`
 const STREAM_FORK_OFFSET_HEADER = `Stream-Fork-Offset`
+const STREAM_FORK_SUB_OFFSET_HEADER = `Stream-Fork-Sub-Offset`
 
 /**
  * Encode data for SSE format.
@@ -449,7 +450,7 @@ export class DurableStreamTestServer {
     )
     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`
+      `content-type, authorization, Stream-Seq, Stream-TTL, Stream-Expires-At, Stream-Closed, Producer-Id, Producer-Epoch, Producer-Seq, Stream-Forked-From, Stream-Fork-Offset, Stream-Fork-Sub-Offset`
     )
     res.setHeader(
       `access-control-expose-headers`,
@@ -598,6 +599,13 @@ export class DurableStreamTestServer {
     const forkOffsetHeader = req.headers[
       STREAM_FORK_OFFSET_HEADER.toLowerCase()
     ] as string | undefined
+    const forkSubOffsetHeaderRaw =
+      req.headers[STREAM_FORK_SUB_OFFSET_HEADER.toLowerCase()]
+    // Distinguish "header absent" from "header present but empty"
+    const forkSubOffsetHeaderPresent = forkSubOffsetHeaderRaw !== undefined
+    const forkSubOffsetHeader = Array.isArray(forkSubOffsetHeaderRaw)
+      ? forkSubOffsetHeaderRaw[0]
+      : forkSubOffsetHeaderRaw
 
     // Sanitize content-type: if empty or invalid, use default — but only
     // for non-fork creates. For forks, an omitted Content-Type means "inherit
@@ -667,6 +675,26 @@ export class DurableStreamTestServer {
       }
     }
 
+    // Validate sub-offset if header was present (including empty value)
+    let forkSubOffset: number | undefined
+    if (forkSubOffsetHeaderPresent) {
+      if (!forkedFromHeader) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Stream-Fork-Sub-Offset requires Stream-Forked-From`)
+        return
+      }
+      const subOffsetPattern = /^(0|[1-9]\d*)$/
+      if (
+        forkSubOffsetHeader === undefined ||
+        !subOffsetPattern.test(forkSubOffsetHeader)
+      ) {
+        res.writeHead(400, { "content-type": `text/plain` })
+        res.end(`Invalid Stream-Fork-Sub-Offset format`)
+        return
+      }
+      forkSubOffset = parseInt(forkSubOffsetHeader, 10)
+    }
+
     // Read body if present
     const body = await this.readBody(req)
 
@@ -683,6 +711,7 @@ export class DurableStreamTestServer {
           closed: createClosed,
           forkedFrom: forkedFromHeader,
           forkOffset: forkOffsetHeader,
+          forkSubOffset,
         })
       )
     } catch (err) {
@@ -692,6 +721,11 @@ export class DurableStreamTestServer {
           res.end(`Source stream not found`)
           return
         }
+        if (err.message.includes(`Invalid fork sub-offset`)) {
+          res.writeHead(400, { "content-type": `text/plain` })
+          res.end(`Invalid fork sub-offset`)
+          return
+        }
         if (err.message.includes(`Invalid fork offset`)) {
           res.writeHead(400, { "content-type": `text/plain` })
           res.end(`Fork offset beyond source stream length`)

package/src/store.ts

@@ -247,6 +247,7 @@ export class StreamStore {
       closed?: boolean
       forkedFrom?: string
       forkOffset?: string
+      forkSubOffset?: number
     } = {}
   ): Stream {
     // Check if stream already exists
@@ -280,6 +281,12 @@ export class StreamStore {
         const forkOffsetMatches =
           options.forkOffset === undefined ||
           options.forkOffset === existingRaw.forkOffset
+        // Sub-offset: undefined and 0 are equivalent. Compare the raw
+        // user-supplied integer (count for JSON, bytes for binary) so the
+        // comparison is independent of how it was resolved internally.
+        const requestedSub = options.forkSubOffset ?? 0
+        const existingSub = existingRaw.forkSubOffset ?? 0
+        const forkSubOffsetMatches = requestedSub === existingSub
 
         if (
           contentTypeMatches &&
@@ -287,7 +294,8 @@ export class StreamStore {
           expiresMatches &&
           closedMatches &&
           forkedFromMatches &&
-          forkOffsetMatches
+          forkOffsetMatches &&
+          forkSubOffsetMatches
         ) {
           // Idempotent success - return existing stream
           return existingRaw
@@ -305,6 +313,7 @@ export class StreamStore {
     let forkOffset = `0000000000000000_0000000000000000`
     let sourceContentType: string | undefined
     let sourceStream: Stream | undefined
+    let forkSubOffsetPrefix: Uint8Array | undefined
 
     if (isFork) {
       sourceStream = this.streams.get(options.forkedFrom!)
@@ -333,6 +342,18 @@ export class StreamStore {
         throw new Error(`Invalid fork offset: ${forkOffset}`)
       }
 
+      // Resolve sub-offset against the source. Both binary and JSON return
+      // a synthetic prefix to materialize as the fork's first own message,
+      // because in this store one POST = one message regardless of mode.
+      if (options.forkSubOffset && options.forkSubOffset > 0) {
+        forkSubOffsetPrefix = this.resolveForkSubOffset(
+          sourceStream,
+          forkOffset,
+          options.forkSubOffset,
+          normalizeContentType(sourceContentType) === `application/json`
+        )
+      }
+
       // Increment source refcount
       sourceStream.refCount++
     }
@@ -375,6 +396,27 @@ export class StreamStore {
       forkOffset: isFork ? forkOffset : undefined,
     }
 
+    // Materialize sub-offset prefix as the fork's first own message.
+    if (forkSubOffsetPrefix && forkSubOffsetPrefix.length > 0) {
+      const parts = stream.currentOffset.split(`_`).map(Number)
+      const readSeq = parts[0]!
+      const byteOffset = parts[1]!
+      // Match append()'s frame-inclusive offset advance (4-byte length
+      // prefix + payload + 1-byte newline) so reads with a capByte don't
+      // truncate the materialized prefix when later chained-fork resolves.
+      const newByteOffset = byteOffset + forkSubOffsetPrefix.length + 5
+      const newOffset = `${String(readSeq).padStart(16, `0`)}_${String(newByteOffset).padStart(16, `0`)}`
+      stream.messages.push({
+        data: forkSubOffsetPrefix,
+        offset: newOffset,
+        timestamp: Date.now(),
+      })
+      stream.currentOffset = newOffset
+      // Persist the user-supplied sub-offset verbatim for idempotent
+      // re-creation matching, not the encoded byte length.
+      stream.forkSubOffset = options.forkSubOffset
+    }
+
     // If initial data is provided, append it
     if (options.initialData && options.initialData.length > 0) {
       try {
@@ -1236,6 +1278,67 @@ export class StreamStore {
   // Private helpers
   // ============================================================================
 
+  /**
+   * Resolve a sub-offset against a source stream and return the prefix bytes
+   * to materialize as the fork's first own message. Reads from the source
+   * (across its fork chain if any) starting at forkOffset; the first message
+   * returned is the one that starts at forkOffset. Throws if the sub-offset
+   * cannot be satisfied (no message past forkOffset, or overshoots its
+   * content extent).
+   */
+  private resolveForkSubOffset(
+    sourceStream: Stream,
+    forkOffset: string,
+    subOffset: number,
+    isJSON: boolean
+  ): Uint8Array {
+    // Read source past forkOffset across its fork chain
+    let sourceMessages: Array<StreamMessage>
+    if (sourceStream.forkedFrom) {
+      sourceMessages = [
+        ...this.readForkedMessages(
+          sourceStream.forkedFrom,
+          forkOffset,
+          sourceStream.forkOffset!
+        ),
+        ...this.readOwnMessages(sourceStream, forkOffset),
+      ]
+    } else {
+      sourceMessages = this.readOwnMessages(sourceStream, forkOffset)
+    }
+    if (sourceMessages.length === 0) {
+      throw new Error(`Invalid fork sub-offset: no data past forkOffset`)
+    }
+    const first = sourceMessages[0]!
+    if (isJSON) {
+      // The message data is comma-joined JSON values with a trailing comma
+      // (e.g., `{"a":1},{"b":2},`). Wrap in [...] to parse, take first N
+      // elements, re-encode in the same comma-joined format.
+      const text = new TextDecoder().decode(first.data)
+      const trimmed = text.endsWith(`,`) ? text.slice(0, -1) : text
+      let values: Array<unknown>
+      try {
+        values = JSON.parse(`[${trimmed}]`)
+      } catch {
+        throw new Error(`Invalid fork sub-offset: source JSON is unparseable`)
+      }
+      if (subOffset > values.length) {
+        throw new Error(
+          `Invalid fork sub-offset: overshoots source message count`
+        )
+      }
+      const prefix = values.slice(0, subOffset).map((v) => JSON.stringify(v))
+      return new TextEncoder().encode(prefix.join(`,`) + `,`)
+    }
+    // Binary: take first subOffset bytes
+    if (subOffset > first.data.length) {
+      throw new Error(
+        `Invalid fork sub-offset: overshoots source message length`
+      )
+    }
+    return first.data.slice(0, subOffset)
+  }
+
   private appendToStream(
     stream: Stream,
     data: Uint8Array,

package/src/types.ts

@@ -107,6 +107,14 @@ export interface Stream {
    */
   forkOffset?: string
 
+  /**
+   * User-supplied sub-offset value refining `forkOffset` (Section 4.2 of
+   * PROTOCOL.md). Stored verbatim for idempotent re-creation matching:
+   * bytes for non-JSON forks, flattened message count for JSON forks.
+   * `undefined` and `0` are equivalent.
+   */
+  forkSubOffset?: number
+
   /**
    * Number of forks referencing this stream.
    * Defaults to 0.