@lostgradient/weft 0.22.1 → 0.23.1

package/dist/server/fleet-event-feed.js

@@ -1,110 +1,127 @@
 import { decode, encode } from "../core/codec.js";
+import { PersistedDataCorruptError } from "../core/persisted-data-incompatible-error.js";
 import {
   KEYS,
+  MAX_BATCH_OPERATIONS,
   storageConditionalBatch
 } from "../storage/interface.js";
+import {
+  createDurableSubscription,
+  createSerialOperationQueue
+} from "./replay-live-feed-internals.js";
 import {
   createReplayLiveFeed,
   decodeCursor,
   encodeCursor
 } from "./workflow-event-feed.js";
-const MAX_WORKFLOW_OWNED_APPEND_ATTEMPTS = 5;
+const DEFAULT_RETENTION_BATCH_SIZE = 100, REPLAY_PAGE_SIZE = 128;
 export function createFleetEventFeed(storage, feedOptions) {
-  const listeners = new Set;
-  let sequenceInitPromise = null, nextSequence = null, appendChain = Promise.resolve();
-  const replayLiveFeed = createReplayLiveFeed({
+  if (!storage.capabilities().conditionalBatch)
+    throw Error("Fleet event feeds require storage with conditional batch support.");
+  const livePollIntervalMs = feedOptions?.livePollIntervalMs ?? 100;
+  if (!Number.isSafeInteger(livePollIntervalMs) || livePollIntervalMs < 1)
+    throw RangeError("Fleet event live poll interval must be positive.");
+  const listeners = new Set, disposalController = new AbortController, enqueueAppend = createSerialOperationQueue(), backend = {
     replay: replayPersistedFleetEvents,
     snapshotTailSequence,
     subscribeLive
-  }, feedOptions);
-  async function initializeNextSequence() {
-    if (nextSequence !== null)
-      return nextSequence;
-    if (sequenceInitPromise)
-      return sequenceInitPromise;
-    sequenceInitPromise = snapshotTailSequence().then((tailSequence) => {
-      nextSequence = tailSequence + 1;
-      return nextSequence;
-    }).catch((error) => {
-      sequenceInitPromise = null;
-      throw error;
-    });
-    return sequenceInitPromise;
-  }
-  async function append(event) {
-    return appendInternal(event);
+  }, replayLiveFeed = createReplayLiveFeed(backend);
+  async function append(event, options) {
+    const appended = await enqueueAppend(() => appendInternal(event, async () => options?.conditions ?? [], options?.operations ?? []));
+    if (appended === null)
+      throw Error("Fleet event append conditions unexpectedly disappeared.");
+    return appended;
   }
   async function appendWorkflowEventIfPresent(event) {
-    return appendInternal(event, async () => {
+    return enqueueAppend(() => appendInternal(event, async () => {
       const workflowValue = await storage.get(KEYS.workflow(event.workflowId));
       if (workflowValue === null)
         return null;
       return [{ key: KEYS.workflow(event.workflowId), expectedValue: workflowValue }];
-    });
+    }, []));
   }
-  async function appendInternal(event, loadConditions) {
-    const appended = appendChain.then(async () => {
-      for (let attempt = 1;attempt <= MAX_WORKFLOW_OWNED_APPEND_ATTEMPTS; attempt += 1) {
-        const conditions = loadConditions === void 0 ? void 0 : await loadConditions();
-        if (conditions === null)
-          return null;
-        const sequence = await initializeNextSequence(), envelope = {
-          kind: event.kind,
-          sequence,
-          cursor: encodeCursor(sequence),
-          emittedAtMs: event.emittedAtMs,
-          ...event.workflowId !== void 0 ? { workflowId: event.workflowId } : {},
-          payload: event.payload
-        }, operations = [
-          { type: "put", key: KEYS.fleetEvent(sequence), value: encode(envelope) },
-          { type: "put", key: KEYS.fleetEventTail(), value: encode({ sequence }) }
-        ];
-        if (event.workflowId !== void 0)
-          operations.push({
-            type: "put",
-            key: KEYS.fleetEventByWorkflow(event.workflowId, sequence),
-            value: new Uint8Array
-          });
-        if (conditions === void 0)
-          await storage.batch(operations);
-        else if (!await storageConditionalBatch(storage, [...conditions], operations))
-          continue;
-        nextSequence = sequence + 1;
-        fireLive(envelope);
-        return envelope;
-      }
-      throw Error(`Fleet event append for workflow "${event.workflowId ?? "<none>"}" lost its storage precondition after ${MAX_WORKFLOW_OWNED_APPEND_ATTEMPTS} attempts.`);
-    });
-    appendChain = appended.then(() => {
-      return;
-    }, () => {
-      return;
-    });
-    return appended;
+  async function appendInternal(event, loadConditions, callerOperations = [], maxAttempts = 25) {
+    if (event.kind === "fleet:gap")
+      throw RangeError("The fleet:gap event kind is reserved for retention notices.");
+    for (let attempt = 1;attempt <= maxAttempts; attempt += 1) {
+      const conditions = loadConditions === void 0 ? [] : await loadConditions();
+      if (conditions === null)
+        return null;
+      const authority = await loadTailAuthority(storage);
+      if (authority === null)
+        continue;
+      const { tail, tailValue } = authority, sequence = tail + 1, envelope = createFleetEventEnvelope(event, sequence), operations = createFleetEventOperations(envelope, callerOperations);
+      if (!await storageConditionalBatch(storage, [{ key: KEYS.fleetEventTail(), expectedValue: tailValue }, ...conditions], operations))
+        continue;
+      fireLive(envelope);
+      return envelope;
+    }
+    throw Error(`Fleet event append for workflow "${event.workflowId ?? "<none>"}" lost its storage precondition after ${maxAttempts} attempts.`);
   }
   async function* replayPersistedFleetEvents(options) {
-    const scanOptions = options.afterSequence >= 0 ? { gt: KEYS.fleetEvent(options.afterSequence) } : void 0;
-    for await (const [key, value] of storage.scan(KEYS.fleetEventPrefix(), scanOptions)) {
-      const sequence = parseFleetEventSequenceFromKey(key);
-      if (sequence === null || sequence <= options.afterSequence)
-        continue;
-      const decoded = decodeStorageValue(value);
-      if (!isFleetEventEnvelope(decoded))
+    let deliveredSequence = options.afterSequence, gapCursor = options.requestedCursor ?? (options.afterSequence < 0 ? "-1" : encodeCursor(options.afterSequence));
+    while (!0) {
+      const page = await loadConsistentReplayPage(storage, deliveredSequence);
+      if (deliveredSequence < page.floor - 1) {
+        deliveredSequence = page.floor - 1;
+        yield createGapEnvelope(deliveredSequence, gapCursor, page.floor);
+        gapCursor = encodeCursor(deliveredSequence);
         continue;
-      yield decoded;
+      }
+      for (const envelope of page.envelopes) {
+        deliveredSequence = envelope.sequence;
+        yield envelope;
+      }
+      if (page.envelopes.length < REPLAY_PAGE_SIZE)
+        return;
     }
   }
   async function snapshotTailSequence() {
-    const storedTail = await storage.get(KEYS.fleetEventTail()), decodedTail = storedTail === null ? null : decodeStorageValue(storedTail);
+    const storedTail = await storage.get(KEYS.fleetEventTail()), decodedTail = storedTail === null ? null : decodeStorageValue(storedTail, KEYS.fleetEventTail());
+    if (storedTail !== null && !isTailRecord(decodedTail))
+      throw new PersistedDataCorruptError(KEYS.fleetEventTail());
     if (isTailRecord(decodedTail))
       return decodedTail.sequence;
     for await (const [key] of storage.scan(KEYS.fleetEventPrefix(), { reverse: !0 })) {
       const sequence = parseFleetEventSequenceFromKey(key);
       if (sequence !== null)
         return sequence;
+      throw new PersistedDataCorruptError(key);
     }
     return -1;
   }
+  async function snapshotRetentionFloor() {
+    const value = await storage.get(KEYS.fleetEventWatermark());
+    if (value === null)
+      return 0;
+    const decoded = decodeStorageValue(value, KEYS.fleetEventWatermark());
+    if (!isFloorRecord(decoded))
+      throw new PersistedDataCorruptError(KEYS.fleetEventWatermark());
+    return decoded.firstRetainedSequence;
+  }
+  async function retain(options) {
+    validateRetentionOptions(options);
+    const requestedLimit = options.limit ?? DEFAULT_RETENTION_BATCH_SIZE, limit = Math.min(requestedLimit, Math.floor((MAX_BATCH_OPERATIONS - 1) / 2));
+    for (let attempt = 1;attempt <= 25; attempt += 1) {
+      const watermarkValue = await storage.get(KEYS.fleetEventWatermark()), floor = decodeRetentionFloorOrThrow(watermarkValue), tail = await snapshotTailSequence(), target = Math.min(options.beforeSequence, tail + 1);
+      if (target <= floor)
+        return 0;
+      const recordsToDelete = await collectRetentionRecords(storage, target, limit), deletedThrough = recordsToDelete.at(-1)?.key, deletedThroughSequence = deletedThrough === void 0 ? floor : parseFleetEventSequenceFromKey(deletedThrough) + 1, newFloor = recordsToDelete.length < limit ? target : deletedThroughSequence, operations = [
+        ...recordsToDelete.flatMap(({ key, workflowId, sequence }) => [
+          { type: "delete", key },
+          ...workflowId === void 0 ? [] : [{ type: "delete", key: KEYS.fleetEventByWorkflow(workflowId, sequence) }]
+        ]),
+        {
+          type: "put",
+          key: KEYS.fleetEventWatermark(),
+          value: encode({ firstRetainedSequence: newFloor })
+        }
+      ];
+      if (await storageConditionalBatch(storage, [{ key: KEYS.fleetEventWatermark(), expectedValue: watermarkValue }], operations))
+        return recordsToDelete.length;
+    }
+    throw Error("Fleet event retention lost its storage precondition after 25 attempts.");
+  }
   function subscribeLive(listener) {
     listeners.add(listener);
     return () => {
@@ -122,21 +139,152 @@ export function createFleetEventFeed(storage, feedOptions) {
     append,
     appendWorkflowEventIfPresent,
     replay: (options) => replayLiveFeed.replay(options),
-    subscribe: (options) => replayLiveFeed.subscribe(options),
+    subscribe: (options) => createDurableSubscription(backend, {
+      pollIntervalMs: livePollIntervalMs,
+      lifecycleSignal: disposalController.signal
+    }, options),
     snapshotTailSequence,
+    snapshotRetentionFloor,
+    retain,
     dispose() {
+      disposalController.abort();
       listeners.clear();
       replayLiveFeed.dispose();
     }
   };
 }
-function decodeStorageValue(value) {
+async function loadTailAuthority(storage) {
+  const tailValue = await storage.get(KEYS.fleetEventTail()), tail = tailValue === null ? -1 : decodeTailOrThrow(tailValue);
+  if (await highestFleetEventSequence(storage) > tail) {
+    const refreshedTailValue = await storage.get(KEYS.fleetEventTail());
+    if (!bytesEqual(refreshedTailValue, tailValue))
+      return null;
+    throw new PersistedDataCorruptError(KEYS.fleetEventTail());
+  }
+  return { tail, tailValue };
+}
+async function loadConsistentReplayPage(storage, afterSequence) {
+  for (let attempt = 1;attempt <= 25; attempt += 1) {
+    const floorValue = await storage.get(KEYS.fleetEventWatermark()), floor = decodeRetentionFloorOrThrow(floorValue), envelopes = [], scanOptions = {
+      ...afterSequence >= 0 ? { gt: KEYS.fleetEvent(afterSequence) } : {},
+      limit: REPLAY_PAGE_SIZE
+    };
+    for await (const [key, value] of storage.scan(KEYS.fleetEventPrefix(), scanOptions)) {
+      const sequence = parseFleetEventSequenceFromKey(key);
+      if (sequence === null)
+        throw new PersistedDataCorruptError(key);
+      if (sequence <= afterSequence)
+        continue;
+      const decoded = decodeStorageValue(value, key);
+      if (!isFleetEventEnvelope(decoded) || decoded.sequence !== sequence)
+        throw new PersistedDataCorruptError(key);
+      envelopes.push(decoded);
+    }
+    const refreshedFloorValue = await storage.get(KEYS.fleetEventWatermark());
+    if (bytesEqual(refreshedFloorValue, floorValue))
+      return { floor, envelopes };
+  }
+  throw Error("Fleet event replay could not obtain a stable retention snapshot.");
+}
+function createGapEnvelope(sequence, requestedCursor, firstRetainedSequence) {
+  return {
+    kind: "fleet:gap",
+    sequence,
+    cursor: encodeCursor(sequence),
+    emittedAtMs: 0,
+    payload: { requestedCursor, firstRetainedSequence }
+  };
+}
+function bytesEqual(left, right) {
+  if (left === null || right === null)
+    return left === right;
+  if (left.byteLength !== right.byteLength)
+    return !1;
+  return left.every((value, index) => value === right[index]);
+}
+function createFleetEventEnvelope(event, sequence) {
+  return {
+    kind: event.kind,
+    sequence,
+    cursor: encodeCursor(sequence),
+    emittedAtMs: event.emittedAtMs,
+    ...event.workflowId === void 0 ? {} : { workflowId: event.workflowId },
+    payload: event.payload
+  };
+}
+function createFleetEventOperations(envelope, callerOperations) {
+  return [
+    ...callerOperations,
+    { type: "put", key: KEYS.fleetEvent(envelope.sequence), value: encode(envelope) },
+    { type: "put", key: KEYS.fleetEventTail(), value: encode({ sequence: envelope.sequence }) },
+    ...envelope.workflowId === void 0 ? [] : [
+      {
+        type: "put",
+        key: KEYS.fleetEventByWorkflow(envelope.workflowId, envelope.sequence),
+        value: new Uint8Array
+      }
+    ]
+  ];
+}
+function validateRetentionOptions(options) {
+  if (!Number.isSafeInteger(options.beforeSequence) || options.beforeSequence < 0)
+    throw RangeError("Fleet event retention sequence must be a non-negative safe integer.");
+  const limit = options.limit ?? DEFAULT_RETENTION_BATCH_SIZE;
+  if (!Number.isSafeInteger(limit) || limit < 1)
+    throw RangeError("Fleet event retention limit must be positive.");
+}
+async function collectRetentionRecords(storage, target, limit) {
+  const records = [];
+  for await (const [key, value] of storage.scan(KEYS.fleetEventPrefix(), {
+    lt: KEYS.fleetEvent(target),
+    limit
+  })) {
+    const sequence = parseFleetEventSequenceFromKey(key);
+    if (sequence === null)
+      throw new PersistedDataCorruptError(key);
+    if (sequence < target) {
+      const envelope = decodeStorageValue(value, key);
+      if (!isFleetEventEnvelope(envelope) || envelope.sequence !== sequence)
+        throw new PersistedDataCorruptError(key);
+      records.push({
+        key,
+        sequence,
+        ...envelope.workflowId === void 0 ? {} : { workflowId: envelope.workflowId }
+      });
+    }
+  }
+  return records;
+}
+function decodeRetentionFloorOrThrow(value) {
+  if (value === null)
+    return 0;
+  const decoded = decodeStorageValue(value, KEYS.fleetEventWatermark());
+  if (!isFloorRecord(decoded))
+    throw new PersistedDataCorruptError(KEYS.fleetEventWatermark());
+  return decoded.firstRetainedSequence;
+}
+function decodeStorageValue(value, key) {
   try {
     return decode(value);
   } catch {
-    return null;
+    throw new PersistedDataCorruptError(key);
   }
 }
+function decodeTailOrThrow(value) {
+  const decoded = decodeStorageValue(value, KEYS.fleetEventTail());
+  if (!isTailRecord(decoded))
+    throw new PersistedDataCorruptError(KEYS.fleetEventTail());
+  return decoded.sequence;
+}
+async function highestFleetEventSequence(storage) {
+  for await (const [key] of storage.scan(KEYS.fleetEventPrefix(), { reverse: !0, limit: 1 })) {
+    const sequence = parseFleetEventSequenceFromKey(key);
+    if (sequence === null)
+      throw new PersistedDataCorruptError(key);
+    return sequence;
+  }
+  return -1;
+}
 function parseFleetEventSequenceFromKey(key) {
   if (!key.startsWith(KEYS.fleetEventPrefix()))
     return null;
@@ -149,6 +297,12 @@ function parseFleetEventSequenceFromKey(key) {
 function isTailRecord(value) {
   return typeof value === "object" && value !== null && "sequence" in value && Number.isSafeInteger(value.sequence);
 }
+function isFloorRecord(value) {
+  if (typeof value !== "object" || value === null)
+    return !1;
+  const firstRetainedSequence = value.firstRetainedSequence;
+  return Number.isSafeInteger(firstRetainedSequence) && firstRetainedSequence >= 0;
+}
 function isFleetEventEnvelope(value) {
   if (typeof value !== "object" || value === null)
     return !1;

package/dist/server/handler/index.d.ts

@@ -15,7 +15,7 @@ export { authContextToPrincipal } from './auth-context-principal.ts';
 export { isOperationFaultLike, type HandlerOptions } from './route-dispatch.ts';
 export { extractRouteParameters, getRequiredRouteParameter } from './route-matching.ts';
 export { createEngineEventFeedBackend } from '../engine-event-feed-backend.ts';
-export { createFleetEventFeed, type FleetEventEnvelope, type FleetEventFeed, } from '../fleet-event-feed.ts';
+export { createFleetEventFeed, type FleetEventAppendOptions, type FleetEventEnvelope, type FleetEventFeed, type FleetEventFeedOptions, type FleetEventGapEnvelope, type FleetEventInput, type FleetWorkflowEventInput, } from '../fleet-event-feed.ts';
 export { createWorkflowEventFeed, type Cursor, type EventEnvelope, type WorkflowEventFeed, type WorkflowEventFeedBackend, } from '../workflow-event-feed.ts';
 /**
  * Pure HTTP request handler. Maps Request to Response.

package/dist/server/index.d.ts

@@ -409,13 +409,15 @@ export interface WeftServer extends AsyncDisposable {
     /**
      * Mark a terminal task's result as adopted — the durable assertion that
      * whatever consumed the result (a workflow's own checkpoint, or other
-     * application logic) has durably incorporated it. `resultDigest` must
-     * match the terminal record's `resultDigest` from {@link getTaskResult}.
-     * Returns `true` once adopted; `false` if the record is not currently
-     * terminal or the digest does not match. Only adopted terminal records
-     * become eligible for {@link ServeOptions.taskRetentionWindowMs} reaping.
+     * application logic) has durably incorporated it. Resolved records require
+     * the `resultDigest` returned by {@link getTaskResult}; cancelled and
+     * retry-exhausted records omit their private synthetic digest and expose a
+     * token-safe `adoptionToken` instead. Returns `true` once adopted; `false` if
+     * the record is not currently terminal or the required digest does not
+     * match. Only adopted terminal records become eligible for
+     * {@link ServeOptions.taskRetentionWindowMs} reaping.
      */
-    adoptTaskResult(operationId: string, resultDigest: string): Promise<boolean>;
+    adoptTaskResult(operationId: string, adoptionKey: string): Promise<boolean>;
     /** Send a shutdown message to a specific worker and wait for it to disconnect. Returns true if the worker was found. */
     shutdownWorker(workerId: string, options?: {
         timeoutMs?: number;

package/dist/server/operations/event-stream-contracts.js

@@ -1,12 +1,25 @@
 import { z } from "zod";
-export const fleetEventEnvelopeSchema = z.object({
+const committedFleetEventEnvelopeSchema = z.object({
   kind: z.string(),
   workflowId: z.string().optional(),
   sequence: z.number(),
   cursor: z.string(),
   emittedAtMs: z.number(),
   payload: z.unknown()
-}), workflowEventEnvelopeSchema = z.object({
+}), fleetEventGapEnvelopeSchema = z.object({
+  kind: z.literal("fleet:gap"),
+  sequence: z.number(),
+  cursor: z.string(),
+  emittedAtMs: z.number(),
+  payload: z.object({
+    requestedCursor: z.string(),
+    firstRetainedSequence: z.number()
+  })
+});
+export const fleetEventEnvelopeSchema = z.union([
+  committedFleetEventEnvelopeSchema,
+  fleetEventGapEnvelopeSchema
+]), workflowEventEnvelopeSchema = z.object({
   kind: z.string(),
   workflowId: z.string(),
   selector: z.enum(["events", "tokens"]),

package/dist/server/operations/fleet-events-sse.js

@@ -67,6 +67,8 @@ function isAsyncIterable(value) {
   return typeof value[Symbol.asyncIterator] === "function";
 }
 function matchesFleetEventFilter(envelope, input) {
+  if (envelope.kind === "fleet:gap")
+    return !0;
   if (input.workflowId !== void 0 && envelope.workflowId !== input.workflowId)
     return !1;
   if (input.kind !== void 0 && envelope.kind !== input.kind)
@@ -84,6 +86,7 @@ function createFleetEventsIterable(input, context) {
       signal: controller.signal,
       replayLimit: MAX_FLEET_SSE_REPLAY_EVENTS,
       filterEnvelope: (envelope) => matchesFleetEventFilter(envelope, input),
+      countReplayEnvelope: (envelope) => envelope.kind !== "fleet:gap",
       onReplayComplete,
       createReplayLimitError: (count, limit) => invalidParamsFault(`Fleet event replay window is ${count} matching events; maximum is ${limit}. Supply a more recent fromCursor.`)
     };

package/dist/server/operations/fleet-events-subscription.js

@@ -46,6 +46,7 @@ export const fleetEventsSubscriptionOperation = defineOperation({
       signal: controller.signal,
       replayLimit: MAX_FLEET_SUBSCRIPTION_REPLAY_EVENTS,
       filterEnvelope: (envelope) => matchesFleetEventFilter(envelope, input),
+      countReplayEnvelope: (envelope) => envelope.kind !== "fleet:gap",
       onReplayComplete,
       createReplayLimitError: (count, limit) => fleetReplayLimitFault(count, limit)
     }), { close: () => controller.abort() });
@@ -60,6 +61,8 @@ function fleetReplayLimitFault(count, limit) {
   return invalidParamsFault(`Fleet event replay window is ${count} matching events; maximum is ${limit}. Supply a more recent fromCursor.`);
 }
 function matchesFleetEventFilter(envelope, input) {
+  if (envelope.kind === "fleet:gap")
+    return !0;
   if (!matchesWorkflowIdFilter(envelope, input.workflowId))
     return !1;
   if (!matchesKindFilter(envelope, input.kind))

package/dist/server/replay-live-feed-internals.d.ts

@@ -8,6 +8,12 @@
  * @module server/replay-live-feed-internals
  */
 import type { ReplayLiveFeedBackend, ReplayLiveSubscribeOptions, SequencedEventEnvelope } from './workflow-event-feed.ts';
+export declare function createSerialOperationQueue(): <T>(operation: () => Promise<T>) => Promise<T>;
+type DurableSubscriptionOptions = {
+    readonly pollIntervalMs: number;
+    readonly lifecycleSignal?: AbortSignal;
+};
+export declare function createDurableSubscription<TEnvelope extends SequencedEventEnvelope>(backend: ReplayLiveFeedBackend<TEnvelope>, options: DurableSubscriptionOptions, args?: ReplayLiveSubscribeOptions<TEnvelope>): AsyncIterable<TEnvelope>;
 /** Thrown when a replay window exceeds the caller's configured limit. */
 export declare class ReplayWindowExceededError extends Error {
     readonly count: number;
@@ -17,3 +23,4 @@ export declare class ReplayWindowExceededError extends Error {
 export declare function replayUpTo<TEnvelope extends SequencedEventEnvelope>(backend: ReplayLiveFeedBackend<TEnvelope>, afterSequence: number, snapshot: number, signal: AbortSignal | undefined, replayOptions: ReplayLiveSubscribeOptions<TEnvelope> | undefined): AsyncIterable<TEnvelope>;
 export declare function shouldDeliverEnvelope<TEnvelope extends SequencedEventEnvelope>(envelope: TEnvelope, replayOptions: ReplayLiveSubscribeOptions<TEnvelope> | undefined): boolean;
 export declare function drainLive<TEnvelope extends SequencedEventEnvelope>(buffer: TEnvelope[], snapshot: number, signal: AbortSignal | undefined, overflowed: () => boolean, installWaker: (fn: (() => void) | null) => void): AsyncIterable<TEnvelope>;
+export {};

package/dist/server/replay-live-feed-internals.js

@@ -1,3 +1,96 @@
+export function createSerialOperationQueue() {
+  let queue = Promise.resolve();
+  return (operation) => {
+    const result = queue.then(operation, operation);
+    queue = result.then(() => {
+      return;
+    }, () => {
+      return;
+    });
+    return result;
+  };
+}
+export function createDurableSubscription(backend, options, args) {
+  const requestedAfter = decodeRequestedCursor(args?.fromCursor), signal = args?.signal === void 0 ? options.lifecycleSignal : options.lifecycleSignal === void 0 ? args.signal : AbortSignal.any([args.signal, options.lifecycleSignal]);
+  let waker = null, cleanedUp = !1;
+  const wake = () => {
+    const pending = waker;
+    waker = null;
+    pending?.();
+  }, unsubscribe = backend.subscribeLive(wake), cleanup = () => {
+    if (cleanedUp)
+      return;
+    cleanedUp = !0;
+    signal?.removeEventListener("abort", cleanup);
+    unsubscribe();
+    wake();
+  };
+  signal?.addEventListener("abort", cleanup, { once: !0 });
+  if (signal?.aborted)
+    cleanup();
+  async function* generator() {
+    try {
+      if (signal?.aborted)
+        return;
+      const snapshot = await backend.snapshotTailSequence();
+      yield* replayUpTo(backend, requestedAfter, snapshot, signal, args);
+      if (signal?.aborted)
+        return;
+      args?.onReplayComplete?.();
+      yield* tailDurableEvents(backend, snapshot, signal, args, options.pollIntervalMs, (next) => {
+        waker = next;
+      });
+    } finally {
+      cleanup();
+    }
+  }
+  return generator();
+}
+async function* tailDurableEvents(backend, snapshot, signal, args, pollIntervalMs, installWaker) {
+  let deliveredSequence = snapshot;
+  while (!0) {
+    if (signal?.aborted)
+      break;
+    let found = !1;
+    for await (const envelope of backend.replay({ afterSequence: deliveredSequence })) {
+      if (signal?.aborted)
+        break;
+      found = !0;
+      deliveredSequence = Math.max(deliveredSequence, envelope.sequence);
+      if (shouldDeliverEnvelope(envelope, args))
+        yield envelope;
+    }
+    if (found)
+      continue;
+    await waitForAppendOrPoll(pollIntervalMs, signal, installWaker);
+  }
+}
+function decodeRequestedCursor(cursor) {
+  if (cursor === void 0)
+    return -1;
+  if (!/^(?:-1|\d+)$/.test(cursor))
+    throw Error("Invalid cursor");
+  const sequence = Number(cursor);
+  if (!Number.isSafeInteger(sequence) || sequence < -1)
+    throw Error("Invalid cursor");
+  return sequence;
+}
+async function waitForAppendOrPoll(pollIntervalMs, signal, installWaker) {
+  let timer;
+  await new Promise((resolve) => {
+    const finish = () => {
+      if (timer !== void 0)
+        clearTimeout(timer);
+      installWaker(null);
+      resolve();
+    };
+    installWaker(finish);
+    timer = setTimeout(finish, pollIntervalMs);
+    if (signal?.aborted)
+      finish();
+  });
+}
+
 export class ReplayWindowExceededError extends Error {
   count;
   limit;
@@ -10,22 +103,29 @@ export class ReplayWindowExceededError extends Error {
 }
 export async function* replayUpTo(backend, afterSequence, snapshot, signal, replayOptions) {
   let replayCount = 0;
-  for await (const envelope of backend.replay({ afterSequence })) {
+  const backendOptions = createBackendReplayOptions(afterSequence, replayOptions?.fromCursor);
+  for await (const envelope of backend.replay(backendOptions)) {
     if (envelope.sequence > snapshot)
       break;
     if (signal?.aborted)
       return;
     if (!shouldDeliverEnvelope(envelope, replayOptions))
       continue;
-    if (shouldCountReplayEnvelope(envelope, replayOptions)) {
-      replayCount += 1;
-      const replayLimit = replayOptions?.replayLimit;
-      if (replayLimit !== void 0 && replayCount > replayLimit)
-        throw createReplayLimitError(replayOptions, replayCount, replayLimit);
-    }
+    replayCount = updateReplayCount(envelope, replayOptions, replayCount);
     yield envelope;
   }
 }
+function updateReplayCount(envelope, replayOptions, replayCount) {
+  if (!shouldCountReplayEnvelope(envelope, replayOptions))
+    return replayCount;
+  const nextCount = replayCount + 1, replayLimit = replayOptions?.replayLimit;
+  if (replayLimit !== void 0 && nextCount > replayLimit)
+    throw createReplayLimitError(replayOptions, nextCount, replayLimit);
+  return nextCount;
+}
+function createBackendReplayOptions(afterSequence, requestedCursor) {
+  return requestedCursor === void 0 ? { afterSequence } : { afterSequence, requestedCursor };
+}
 export function shouldDeliverEnvelope(envelope, replayOptions) {
   return replayOptions?.filterEnvelope?.(envelope) ?? !0;
 }