@lostgradient/weft 0.22.0 → 0.23.0

package/dist/server/fleet-event-feed.d.ts

@@ -1,40 +1,8 @@
 import { type Storage } from '../storage/interface.ts';
-import { type Cursor, type FeedEventKind, type ReplayLiveSubscribeOptions, type WorkflowEventFeedOptions } from './workflow-event-feed.ts';
+import { type Cursor, type FleetEventAppendOptions, type FleetEventEnvelope, type FleetEventFeedOptions, type FleetEventInput, type FleetWorkflowEventInput, type ReplayLiveSubscribeOptions } from './workflow-event-feed.ts';
+export type { FleetEventAppendOptions, FleetEventEnvelope, FleetEventFeedOptions, FleetEventGapEnvelope, FleetEventInput, FleetWorkflowEventInput, } from './workflow-event-feed.ts';
 /**
- * A single committed record from the fleet-wide event feed — cross-workflow
- * lifecycle and system events, optionally scoped to one `workflowId`.
- * Returned by `FleetEventFeed.replay()` / `FleetEventFeed.subscribe()`, and
- * consumed directly by the `/v1/events/sse` REST route.
- *
- * @example
- * ```ts
- * import type { FleetEventEnvelope } from '@lostgradient/weft/server/handler';
- *
- * declare const envelope: FleetEventEnvelope;
- * console.log(envelope.kind); // e.g. 'workflow:completed'
- * console.log(envelope.workflowId); // string | undefined
- * ```
- */
-export type FleetEventEnvelope = {
-    readonly kind: FeedEventKind;
-    readonly workflowId?: string | undefined;
-    readonly sequence: number;
-    readonly cursor: Cursor;
-    readonly emittedAtMs: number;
-    readonly payload: unknown;
-};
-export type FleetEventInput = {
-    readonly kind: FeedEventKind;
-    readonly workflowId?: string | undefined;
-    readonly emittedAtMs: number;
-    readonly payload: unknown;
-};
-export type FleetWorkflowEventInput = FleetEventInput & {
-    readonly workflowId: string;
-};
-/**
- * The fleet-wide event feed: append cross-workflow events, replay committed
- * history from a cursor, then subscribe for live delivery. This is the shape
+ * Append cross-workflow events, replay history, then subscribe for live delivery. This is the shape
  * of `HandlerOptions.fleetEventFeed` — build a real one with
  * `createFleetEventFeed()` to drive `/v1/events/sse` through `handleRequest()`
  * without `serve()`.
@@ -50,7 +18,7 @@ export type FleetWorkflowEventInput = FleetEventInput & {
  * ```
  */
 export type FleetEventFeed = {
-    append(event: FleetEventInput): Promise<FleetEventEnvelope>;
+    append(event: FleetEventInput, options?: FleetEventAppendOptions): Promise<FleetEventEnvelope>;
     appendWorkflowEventIfPresent(event: FleetWorkflowEventInput): Promise<FleetEventEnvelope | null>;
     replay(options?: {
         fromCursor?: Cursor;
@@ -58,39 +26,21 @@ export type FleetEventFeed = {
     }): AsyncIterable<FleetEventEnvelope>;
     subscribe(options?: ReplayLiveSubscribeOptions<FleetEventEnvelope>): AsyncIterable<FleetEventEnvelope>;
     snapshotTailSequence(): Promise<number>;
+    snapshotRetentionFloor(): Promise<number>;
+    retain(options: {
+        beforeSequence: number;
+        limit?: number;
+    }): Promise<number>;
     dispose(): void;
 };
 /**
  * Build a `FleetEventFeed` backed by the given `Storage` — typically
- * `engine.storage`. Pass the result as `HandlerOptions.fleetEventFeed` to
- * drive `/v1/events/sse` through `handleRequest()` directly, without
- * `serve()`. Call once per storage instance and share the returned feed
- * across every transport that needs it.
- *
- * **This feed does not subscribe to `Engine` events on its own.** `serve()`
- * bridges engine lifecycle events into it via `wireEventBroadcasting()`; a
- * direct `handleRequest()` host that skips `serve()` is responsible for
- * calling `fleetEventFeed.append()` (or `appendWorkflowEventIfPresent()`)
- * itself for whatever events it wants `/v1/events/sse` to carry — e.g. from
- * `engine.addEventListener(...)` handlers wired up separately.
- *
+ * `engine.storage` and share it across every fleet transport.
  * @example
  * ```ts
- * import { Engine, MemoryStorage } from '@lostgradient/weft';
- * import {
- *   createFleetEventFeed,
- *   handleRequest,
- *   type HandlerOptions,
- * } from '@lostgradient/weft/server/handler';
- *
- * const engine = new Engine({ storage: new MemoryStorage() });
- * const fleetEventFeed = createFleetEventFeed(engine.storage);
- * const options: HandlerOptions = { fleetEventFeed };
- *
- * async function handleFleetEventsSse(request: Request): Promise<Response> {
- *   return handleRequest(request, engine, options);
- * }
- * void handleFleetEventsSse;
+ * import { MemoryStorage } from '@lostgradient/weft';
+ * import { createFleetEventFeed } from '@lostgradient/weft/server/handler';
+ * const feed = createFleetEventFeed(new MemoryStorage());
  * ```
  */
-export declare function createFleetEventFeed(storage: Storage, feedOptions?: WorkflowEventFeedOptions): FleetEventFeed;
+export declare function createFleetEventFeed(storage: Storage, feedOptions?: FleetEventFeedOptions): FleetEventFeed;

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 {};