@durable-streams/server 0.2.3 → 0.3.0

package/src/file-store.ts

@@ -45,6 +45,12 @@ interface StreamMetadata {
   ttlSeconds?: number
   expiresAt?: string
   createdAt: number
+  /**
+   * Timestamp of the last read or write (for TTL renewal).
+   * Optional for backward-compatible deserialization from LMDB (old records won't have it).
+   * Falls back to createdAt when missing.
+   */
+  lastAccessedAt?: number
   segmentCount: number
   totalBytes: number
   /**
@@ -73,6 +79,23 @@ interface StreamMetadata {
     epoch: number
     seq: number
   }
+  /**
+   * Source stream path (set when this stream is a fork).
+   */
+  forkedFrom?: string
+  /**
+   * Divergence offset from the source stream.
+   */
+  forkOffset?: string
+  /**
+   * Number of forks referencing this stream.
+   * Defaults to 0. Optional for backward-compatible deserialization from LMDB.
+   */
+  refCount?: number
+  /**
+   * Whether this stream is logically deleted but retained for fork readers.
+   */
+  softDeleted?: boolean
 }
 
 /**
@@ -277,7 +300,19 @@ export class FileBackedStreamStore {
         }
 
         // Scan file to compute true offset
-        const trueOffset = this.scanFileForTrueOffset(segmentPath)
+        // For forks, physical file bytes need to be added to forkOffset base
+        const physicalOffset = this.scanFileForTrueOffset(segmentPath)
+        const physicalBytes = Number(physicalOffset.split(`_`)[1] ?? 0)
+
+        let trueOffset: string
+        if (streamMeta.forkOffset) {
+          // Fork: logical offset = forkOffset base + physical bytes in own file
+          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
+        }
 
         // Check if offset matches
         if (trueOffset !== streamMeta.currentOffset) {
@@ -379,9 +414,14 @@ export class FileBackedStreamStore {
       ttlSeconds: meta.ttlSeconds,
       expiresAt: meta.expiresAt,
       createdAt: meta.createdAt,
+      lastAccessedAt: meta.lastAccessedAt ?? meta.createdAt,
       producers,
       closed: meta.closed,
       closedBy: meta.closedBy,
+      forkedFrom: meta.forkedFrom,
+      forkOffset: meta.forkOffset,
+      refCount: meta.refCount ?? 0,
+      softDeleted: meta.softDeleted,
     }
   }
 
@@ -507,6 +547,21 @@ export class FileBackedStreamStore {
     return meta.producers[producerId]?.epoch
   }
 
+  /**
+   * Update lastAccessedAt to now. Called on reads and appends (not HEAD).
+   */
+  touchAccess(streamPath: string): void {
+    const key = `stream:${streamPath}`
+    const meta = this.db.get(key) as StreamMetadata | undefined
+    if (meta) {
+      const updatedMeta: StreamMetadata = {
+        ...meta,
+        lastAccessedAt: Date.now(),
+      }
+      this.db.putSync(key, updatedMeta)
+    }
+  }
+
   /**
    * Check if a stream is expired based on TTL or Expires-At.
    */
@@ -522,9 +577,10 @@ export class FileBackedStreamStore {
       }
     }
 
-    // Check TTL (relative to creation time)
+    // Check TTL (sliding window from last access)
     if (meta.ttlSeconds !== undefined) {
-      const expiryTime = meta.createdAt + meta.ttlSeconds * 1000
+      const lastAccessed = meta.lastAccessedAt ?? meta.createdAt
+      const expiryTime = lastAccessed + meta.ttlSeconds * 1000
       if (now >= expiryTime) {
         return true
       }
@@ -535,7 +591,8 @@ export class FileBackedStreamStore {
 
   /**
    * 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.
    */
   private getMetaIfNotExpired(streamPath: string): StreamMetadata | undefined {
     const key = `stream:${streamPath}`
@@ -544,6 +601,15 @@ export class FileBackedStreamStore {
       return undefined
     }
     if (this.isExpired(meta)) {
+      if ((meta.refCount ?? 0) > 0) {
+        // Expired with refs: soft-delete instead of full delete
+        if (!meta.softDeleted) {
+          const updatedMeta: StreamMetadata = { ...meta, softDeleted: true }
+          this.db.putSync(key, updatedMeta)
+          return updatedMeta
+        }
+        return meta
+      }
       // Delete expired stream
       this.delete(streamPath)
       return undefined
@@ -551,6 +617,36 @@ export class FileBackedStreamStore {
     return meta
   }
 
+  /**
+   * Resolve fork expiry per the decision table.
+   * Forks have independent lifetimes — no capping at source expiry.
+   */
+  private resolveForkExpiry(
+    opts: { ttlSeconds?: number; expiresAt?: string },
+    sourceMeta: StreamMetadata
+  ): { ttlSeconds?: number; expiresAt?: string } {
+    // Fork explicitly requests TTL — use it
+    if (opts.ttlSeconds !== undefined) {
+      return { ttlSeconds: opts.ttlSeconds }
+    }
+
+    // Fork explicitly requests Expires-At — use it
+    if (opts.expiresAt) {
+      return { expiresAt: opts.expiresAt }
+    }
+
+    // No expiry requested — inherit from source
+    if (sourceMeta.ttlSeconds !== undefined) {
+      return { ttlSeconds: sourceMeta.ttlSeconds }
+    }
+    if (sourceMeta.expiresAt) {
+      return { expiresAt: sourceMeta.expiresAt }
+    }
+
+    // Source has no expiry either
+    return {}
+  }
+
   /**
    * Close the store, closing all file handles and database.
    * All data is already fsynced on each append, so no final flush needed.
@@ -572,35 +668,130 @@ export class FileBackedStreamStore {
       expiresAt?: string
       initialData?: Uint8Array
       closed?: boolean
+      forkedFrom?: string
+      forkOffset?: string
     } = {}
   ): Promise<Stream> {
     // Use getMetaIfNotExpired to treat expired streams as non-existent
-    const existing = this.getMetaIfNotExpired(streamPath)
-
-    if (existing) {
-      // Check if config matches (idempotent create)
-      // MIME types are case-insensitive per RFC 2045
-      const normalizeMimeType = (ct: string | undefined) =>
-        (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) {
-        // Idempotent success - return existing stream
-        return this.streamMetaToStream(existing)
-      } else {
-        // Config mismatch - conflict
+    const existingRaw = this.db.get(`stream:${streamPath}`) as
+      | StreamMetadata
+      | undefined
+
+    if (existingRaw) {
+      if (this.isExpired(existingRaw)) {
+        // Expired: delete and proceed with creation
+        this.delete(streamPath)
+      } else if (existingRaw.softDeleted) {
+        // Soft-deleted streams block new creation
         throw new Error(
-          `Stream already exists with different configuration: ${streamPath}`
+          `Stream has active forks — path cannot be reused until all forks are removed: ${streamPath}`
         )
+      } else {
+        // Check if config matches (idempotent create)
+        // MIME types are case-insensitive per RFC 2045
+        const normalizeMimeType = (ct: string | undefined) =>
+          (ct ?? `application/octet-stream`).toLowerCase()
+        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 ?? undefined) === existingRaw.forkedFrom
+        // Only compare forkOffset when explicitly provided; when omitted the
+        // server resolves a default at creation time, so a second PUT that
+        // also omits it should still be considered idempotent.
+        const forkOffsetMatches =
+          options.forkOffset === undefined ||
+          options.forkOffset === existingRaw.forkOffset
+
+        if (
+          contentTypeMatches &&
+          ttlMatches &&
+          expiresMatches &&
+          closedMatches &&
+          forkedFromMatches &&
+          forkOffsetMatches
+        ) {
+          // Idempotent success - return existing stream
+          return this.streamMetaToStream(existingRaw)
+        } else {
+          // Config mismatch - conflict
+          throw new Error(
+            `Stream already exists with different configuration: ${streamPath}`
+          )
+        }
       }
     }
 
+    // Fork creation: validate source stream and resolve fork parameters
+    const isFork = !!options.forkedFrom
+    let forkOffset = `0000000000000000_0000000000000000`
+    let sourceContentType: string | undefined
+    let sourceMeta: StreamMetadata | undefined
+
+    if (isFork) {
+      const sourceKey = `stream:${options.forkedFrom!}`
+      sourceMeta = this.db.get(sourceKey) as StreamMetadata | undefined
+      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
+
+      // Resolve fork offset: use provided or source's currentOffset
+      if (options.forkOffset) {
+        forkOffset = options.forkOffset
+      } else {
+        forkOffset = sourceMeta.currentOffset
+      }
+
+      // Validate: zeroOffset <= forkOffset <= source.currentOffset
+      const zeroOffset = `0000000000000000_0000000000000000`
+      if (forkOffset < zeroOffset || sourceMeta.currentOffset < forkOffset) {
+        throw new Error(`Invalid fork offset: ${forkOffset}`)
+      }
+
+      // Atomically increment source refcount in LMDB
+      const freshSource = this.db.get(sourceKey) as StreamMetadata
+      const updatedSource: StreamMetadata = {
+        ...freshSource,
+        refCount: (freshSource.refCount ?? 0) + 1,
+      }
+      this.db.putSync(sourceKey, updatedSource)
+    }
+
+    // Determine content type: use options, or inherit from source if fork
+    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`)
+    }
+
+    // Compute effective expiry for forks
+    let effectiveExpiresAt = options.expiresAt
+    let effectiveTtlSeconds = options.ttlSeconds
+    if (isFork) {
+      const resolved = this.resolveForkExpiry(options, sourceMeta!)
+      effectiveExpiresAt = resolved.expiresAt
+      effectiveTtlSeconds = resolved.ttlSeconds
+    }
+
     // Define key for LMDB operations
     const key = `stream:${streamPath}`
 
@@ -609,16 +800,20 @@ export class FileBackedStreamStore {
     // This prevents the closed check from rejecting the initial append
     const streamMeta: StreamMetadata = {
       path: streamPath,
-      contentType: options.contentType,
-      currentOffset: `0000000000000000_0000000000000000`,
+      contentType,
+      currentOffset: isFork ? forkOffset : `0000000000000000_0000000000000000`,
       lastSeq: undefined,
-      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, // Set to false initially, will be updated after initial append if needed
+      forkedFrom: isFork ? options.forkedFrom : undefined,
+      forkOffset: isFork ? forkOffset : undefined,
+      refCount: 0,
     }
 
     // Create stream directory and empty segment file immediately
@@ -633,6 +828,18 @@ export class FileBackedStreamStore {
       const segmentPath = path.join(streamDir, `segment_00000.log`)
       fs.writeFileSync(segmentPath, ``)
     } catch (err) {
+      // Rollback source refcount on failure
+      if (isFork && sourceMeta) {
+        const sourceKey = `stream:${options.forkedFrom!}`
+        const freshSource = this.db.get(sourceKey) as StreamMetadata | undefined
+        if (freshSource) {
+          const updatedSource: StreamMetadata = {
+            ...freshSource,
+            refCount: Math.max(0, (freshSource.refCount ?? 0) - 1),
+          }
+          this.db.putSync(sourceKey, updatedSource)
+        }
+      }
       console.error(
         `[FileBackedStreamStore] Error creating stream directory:`,
         err
@@ -645,10 +852,28 @@ export class FileBackedStreamStore {
 
     // Append initial data if provided
     if (options.initialData && options.initialData.length > 0) {
-      await this.append(streamPath, options.initialData, {
-        contentType: options.contentType,
-        isInitialCreate: true,
-      })
+      try {
+        await this.append(streamPath, options.initialData, {
+          contentType: options.contentType,
+          isInitialCreate: true,
+        })
+      } catch (err) {
+        // Rollback source refcount on failure
+        if (isFork && sourceMeta) {
+          const sourceKey = `stream:${options.forkedFrom!}`
+          const freshSource = this.db.get(sourceKey) as
+            | StreamMetadata
+            | undefined
+          if (freshSource) {
+            const updatedSource: StreamMetadata = {
+              ...freshSource,
+              refCount: Math.max(0, (freshSource.refCount ?? 0) - 1),
+            }
+            this.db.putSync(sourceKey, updatedSource)
+          }
+        }
+        throw err
+      }
     }
 
     // Now set closed flag if requested (after initial append succeeded)
@@ -665,11 +890,15 @@ export class FileBackedStreamStore {
 
   get(streamPath: string): Stream | undefined {
     const meta = this.getMetaIfNotExpired(streamPath)
-    return meta ? this.streamMetaToStream(meta) : undefined
+    if (!meta) return undefined
+    return this.streamMetaToStream(meta)
   }
 
   has(streamPath: string): boolean {
-    return this.getMetaIfNotExpired(streamPath) !== undefined
+    const meta = this.getMetaIfNotExpired(streamPath)
+    if (!meta) return false
+    if (meta.softDeleted) return false
+    return true
   }
 
   delete(streamPath: string): boolean {
@@ -680,11 +909,39 @@ export class FileBackedStreamStore {
       return false
     }
 
+    // Already soft-deleted: idempotent success
+    if (streamMeta.softDeleted) {
+      return true
+    }
+
+    // If there are forks referencing this stream, soft-delete
+    if ((streamMeta.refCount ?? 0) > 0) {
+      const updatedMeta: StreamMetadata = { ...streamMeta, softDeleted: true }
+      this.db.putSync(key, updatedMeta)
+      this.cancelLongPollsForStream(streamPath)
+      return true
+    }
+
+    // RefCount == 0: full delete with cascade
+    this.deleteWithCascade(streamPath)
+    return true
+  }
+
+  /**
+   * Fully delete a stream and cascade to soft-deleted parents
+   * whose refcount drops to zero.
+   */
+  private deleteWithCascade(streamPath: string): void {
+    const key = `stream:${streamPath}`
+    const streamMeta = this.db.get(key) as StreamMetadata | undefined
+    if (!streamMeta) return
+
+    const forkedFrom = streamMeta.forkedFrom
+
     // Cancel any pending long-polls for this stream
     this.cancelLongPollsForStream(streamPath)
 
     // Close any open file handle for this stream's segment file
-    // This is important especially on Windows where open handles block deletion
     const segmentPath = path.join(
       this.dataDir,
       `streams`,
@@ -699,7 +956,6 @@ export class FileBackedStreamStore {
     this.db.removeSync(key)
 
     // Delete files using unique directory name (async, but don't wait)
-    // Safe to reuse stream path immediately since new creation gets new directory
     this.fileManager
       .deleteDirectoryByName(streamMeta.directoryName)
       .catch((err: Error) => {
@@ -709,7 +965,24 @@ export class FileBackedStreamStore {
         )
       })
 
-    return true
+    // If this stream is a fork, decrement the source's refcount
+    if (forkedFrom) {
+      const parentKey = `stream:${forkedFrom}`
+      const parentMeta = this.db.get(parentKey) as StreamMetadata | undefined
+      if (parentMeta) {
+        const newRefCount = Math.max(0, (parentMeta.refCount ?? 0) - 1)
+        const updatedParent: StreamMetadata = {
+          ...parentMeta,
+          refCount: newRefCount,
+        }
+        this.db.putSync(parentKey, updatedParent)
+
+        // If parent refcount hit 0 and parent is soft-deleted, cascade
+        if (newRefCount === 0 && updatedParent.softDeleted) {
+          this.deleteWithCascade(forkedFrom)
+        }
+      }
+    }
   }
 
   async append(
@@ -723,6 +996,11 @@ export class FileBackedStreamStore {
       throw new Error(`Stream not found: ${streamPath}`)
     }
 
+    // Guard against soft-deleted streams
+    if (streamMeta.softDeleted) {
+      throw new Error(`Stream is soft-deleted: ${streamPath}`)
+    }
+
     // Check if stream is closed
     if (streamMeta.closed) {
       // Check if this is a duplicate of the closing request (idempotent retry)
@@ -1075,57 +1353,30 @@ export class FileBackedStreamStore {
     }
   }
 
-  read(
-    streamPath: string,
-    offset?: string
-  ): { messages: Array<StreamMessage>; upToDate: boolean } {
-    const streamMeta = this.getMetaIfNotExpired(streamPath)
-
-    if (!streamMeta) {
-      throw new Error(`Stream not found: ${streamPath}`)
-    }
-
-    // Parse offsets
-    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
-
-    // Early return if no data available
-    if (streamMeta.currentOffset === `0000000000000000_0000000000000000`) {
-      return { messages: [], upToDate: true }
-    }
-
-    // If start offset is at or past current offset, return empty
-    if (startByte >= currentByte) {
-      return { messages: [], upToDate: true }
-    }
-
-    // Get segment file path using unique directory name
-    const streamDir = path.join(
-      this.dataDir,
-      `streams`,
-      streamMeta.directoryName
-    )
-    const segmentPath = path.join(streamDir, `segment_00000.log`)
+  /**
+   * 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
+   */
+  private readMessagesFromSegmentFile(
+    segmentPath: string,
+    startByte: number,
+    baseByteOffset: number,
+    capByte?: number
+  ): Array<StreamMessage> {
+    const messages: Array<StreamMessage> = []
 
-    // Check if file exists
     if (!fs.existsSync(segmentPath)) {
-      return { messages: [], upToDate: true }
+      return messages
     }
 
-    // Read and parse messages from file
-    const messages: Array<StreamMessage> = []
-
     try {
-      // Calculate file position from offset
-      // We need to read from the beginning and skip to the right position
-      // because the file has framing overhead
       const fileContent = fs.readFileSync(segmentPath)
       let filePos = 0
-      let currentDataOffset = 0
+      let physicalDataOffset = 0
 
       while (filePos < fileContent.length) {
         // Read message length (4 bytes)
@@ -1146,22 +1397,161 @@ export class FileBackedStreamStore {
         // Skip newline
         filePos += 1
 
-        // Calculate this message's offset (end position)
-        const messageOffset = currentDataOffset + messageLength
+        // Calculate this message's logical offset (end position)
+        physicalDataOffset += messageLength
+        const logicalOffset = baseByteOffset + physicalDataOffset
+
+        // Stop if we've exceeded the cap
+        if (capByte !== undefined && logicalOffset > capByte) {
+          break
+        }
 
-        // Only include messages after start offset
-        if (messageOffset > startByte) {
+        // Only include messages after start byte
+        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, // Not stored in MVP
           })
         }
-
-        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.
+   */
+  private readForkedMessages(
+    sourcePath: string,
+    startByte: number,
+    capByte: number
+  ): Array<StreamMessage> {
+    const sourceKey = `stream:${sourcePath}`
+    const sourceMeta = this.db.get(sourceKey) as StreamMetadata | undefined
+    if (!sourceMeta) {
+      return []
+    }
+
+    const messages: Array<StreamMessage> = []
+
+    // If source is also a fork and we need messages before source's forkOffset,
+    // recursively read from source's source
+    if (sourceMeta.forkedFrom && sourceMeta.forkOffset) {
+      const sourceForkByte = Number(sourceMeta.forkOffset.split(`_`)[1] ?? 0)
+
+      if (startByte < sourceForkByte) {
+        // Cap at the minimum of source's forkByte and our capByte
+        const inheritedCap = Math.min(sourceForkByte, capByte)
+        const inherited = this.readForkedMessages(
+          sourceMeta.forkedFrom,
+          startByte,
+          inheritedCap
+        )
+        messages.push(...inherited)
+      }
+    }
+
+    // Read source's own segment file
+    // For a fork source, its own data starts at physical byte 0 in its segment file,
+    // but the logical offsets need to account for its own forkOffset base
+    const segmentPath = path.join(
+      this.dataDir,
+      `streams`,
+      sourceMeta.directoryName,
+      `segment_00000.log`
+    )
+
+    // The base offset for this source's own data is its forkOffset (if it's a fork) or 0
+    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: string,
+    offset?: string
+  ): { messages: Array<StreamMessage>; upToDate: boolean } {
+    const streamMeta = this.getMetaIfNotExpired(streamPath)
+
+    if (!streamMeta) {
+      throw new Error(`Stream not found: ${streamPath}`)
+    }
+
+    // Parse offsets
+    const startOffset = offset ?? `0000000000000000_0000000000000000`
+    const startByte = Number(startOffset.split(`_`)[1] ?? 0)
+    const currentByte = Number(streamMeta.currentOffset.split(`_`)[1] ?? 0)
+
+    // Early return if no data available
+    if (streamMeta.currentOffset === `0000000000000000_0000000000000000`) {
+      return { messages: [], upToDate: true }
+    }
+
+    // If start offset is at or past current offset, return empty
+    if (startByte >= currentByte) {
+      return { messages: [], upToDate: true }
+    }
+
+    const messages: Array<StreamMessage> = []
+
+    // For forked streams, stitch inherited and own messages
+    if (streamMeta.forkedFrom && streamMeta.forkOffset) {
+      const forkByte = Number(streamMeta.forkOffset.split(`_`)[1] ?? 0)
+
+      // If offset is before the forkOffset, read from source chain
+      if (startByte < forkByte) {
+        const inherited = this.readForkedMessages(
+          streamMeta.forkedFrom,
+          startByte,
+          forkByte
+        )
+        messages.push(...inherited)
+      }
+
+      // Read fork's own segment file with offset translation
+      // Physical bytes in file start at 0, but logical offsets start at forkOffset
+      const segmentPath = path.join(
+        this.dataDir,
+        `streams`,
+        streamMeta.directoryName,
+        `segment_00000.log`
+      )
+      const ownMessages = this.readMessagesFromSegmentFile(
+        segmentPath,
+        startByte,
+        forkByte
+      )
+      messages.push(...ownMessages)
+    } else {
+      // Non-forked stream: read from segment file directly
+      const segmentPath = path.join(
+        this.dataDir,
+        `streams`,
+        streamMeta.directoryName,
+        `segment_00000.log`
+      )
+      const ownMessages = this.readMessagesFromSegmentFile(
+        segmentPath,
+        startByte,
+        0
+      )
+      messages.push(...ownMessages)
     }
 
     return { messages, upToDate: true }
@@ -1182,6 +1572,17 @@ export class FileBackedStreamStore {
       throw new Error(`Stream not found: ${streamPath}`)
     }
 
+    // For forks: if offset is in the inherited range (< forkOffset),
+    // read and return immediately instead of long-polling
+    if (
+      streamMeta.forkedFrom &&
+      streamMeta.forkOffset &&
+      offset < streamMeta.forkOffset
+    ) {
+      const { messages } = this.read(streamPath, offset)
+      return { messages, timedOut: false }
+    }
+
     // If stream is closed and client is at tail, return immediately
     if (streamMeta.closed && offset === streamMeta.currentOffset) {
       return { messages: [], timedOut: false, streamClosed: true }