@lostgradient/weft 0.2.1 → 0.4.0

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

@@ -1,62 +1,9 @@
-/**
- * `WorkflowEventFeed` — transport-neutral event replay + live-tail
- * contract shared by REST SSE, WebSocket watch/stream, and JSON-RPC
- * subscribe. Track 8 design decision 5 and 6.
- *
- * **Atomic handoff ordering** (the only sequence that avoids both
- * duplicates and gaps when a subscriber joins mid-stream):
- *
- *   1. Register a live listener into a bounded in-memory buffer.
- *      From this moment, every newly-emitted event is captured.
- *   2. Snapshot the current live-tail sequence `S` (read once).
- *   3. Stream storage replay from `fromCursor` up to and including `S`.
- *   4. Drain the buffer, dropping any envelope with `sequence <= S`
- *      (already replayed) and emitting the rest.
- *   5. Continue emitting live envelopes directly as the listener fires.
- *
- * Buffer bound is configurable (default 1000 envelopes per subscription).
- * Overflow closes the subscription with a `SubscriptionOverflow` signal
- * (the iterable terminates; the caller reopens with its last delivered
- * cursor). Unbounded-memory-growth is not an option here.
- *
- * **Cursor is opaque.** `encodeCursor(sequence)` and
- * `decodeCursor(cursor)` are the only code that knows the representation
- * — REST `Last-Event-ID`, WS `?resumeFrom=`, and JSON-RPC `fromCursor`
- * all round-trip through this module.
- */
 import type { WeftEventMap } from '../core/events.ts';
-/**
- * Discriminator string carried on every envelope. The union covers:
- *
- *   - Dispatched `WeftEventMap` event names (`workflow:started`,
- *     `activity:completed`, `stream:token`, …) — emitted when a
- *     future log entry type corresponds to a runtime `Event`.
- *   - Durable log entry types not in `WeftEventMap`
- *     (`workflow:checkpoint` — the only one today; add others here
- *     as new log kinds land).
- *   - Selector-scoped synthetic kinds (`stream:chunk`) for records
- *     that are not dispatched `Event` objects at all.
- *   - An open `(string & {})` tail so third-party event kinds don't
- *     fail typechecking at the envelope construction site while
- *     IntelliSense still suggests the known literals.
- *
- * Cross-transport consumers match on `selector` first, then on
- * `kind` within that selector. This union is extensible and preserves
- * completion for known kinds, but the open-string tail means it does
- * not by itself reject arbitrary or misspelled string literals.
- */
+/** Discriminator string carried on every feed envelope. */
 export type FeedEventKind = keyof WeftEventMap | 'workflow:checkpoint' | 'stream:chunk' | (string & {});
 /** Opaque cursor. Only `encodeCursor` / `decodeCursor` know the format. */
 export type Cursor = string;
-/**
- * Encode a non-negative integer sequence as an opaque cursor. The
- * current encoding is the decimal string form of the sequence, matching
- * the existing `sequence-cursor.ts` public representation so REST
- * `Last-Event-ID` / `?after=` clients continue to work unchanged. The
- * encoding is intentionally not part of the public API — a future
- * migration to base64 / hex / compact binary can happen without
- * breaking anything that goes through this module.
- */
+/** Encode a non-negative integer sequence as an opaque cursor. */
 export declare function encodeCursor(sequence: number): Cursor;
 /**
  * Decode an opaque cursor back to its sequence. `-1` is the initial
@@ -64,12 +11,6 @@ export declare function encodeCursor(sequence: number): Cursor;
  */
 export declare function decodeCursor(cursor: Cursor): number | null;
 export type EventSelector = 'events' | 'tokens';
-/**
- * Unified event envelope delivered by the feed. Transports serialize
- * this directly (REST SSE `data:` line, WS JSON frame, JSON-RPC
- * `weft.events.deliver` params). `kind` narrows `payload` shape in
- * caller code via discriminated-union typing.
- */
 export type EventEnvelope = {
     readonly kind: FeedEventKind;
     readonly workflowId: string;
@@ -79,88 +20,68 @@ export type EventEnvelope = {
     readonly emittedAtMs: number;
     readonly payload: unknown;
 };
-/**
- * Pluggable storage + live-event source. The in-memory implementation
- * is used by unit tests; the production implementation wraps
- * `engine.storage` event scans + `EngineEventTarget` subscription.
- */
 export type WorkflowEventFeedBackend = {
-    /**
-     * Yield persisted envelopes with `sequence > afterSequence` in
-     * sequence order. `afterSequence: -1` means "from the beginning."
-     */
     replay(options: {
         workflowId: string;
         selector: EventSelector;
         afterSequence: number;
     }): AsyncIterable<EventEnvelope>;
-    /**
-     * Snapshot the current tail sequence for a workflow. Used in the
-     * atomic-handoff sequence to bound the replay scan. Returns -1 if
-     * no events have been emitted yet.
-     */
     snapshotTailSequence(workflowId: string, selector: EventSelector): Promise<number>;
-    /**
-     * Register a live listener. Returns an unsubscribe function.
-     *
-     * Contract:
-     *   - Envelopes MUST be delivered in monotonically increasing
-     *     sequence order. The feed's live-buffer drain relies on this
-     *     for its dedupe logic — an out-of-order emission would cause
-     *     the feed to advance `lastDelivered` past a later-arriving
-     *     lower-sequence event and silently drop it.
-     *   - The listener SHOULD be invoked synchronously from the
-     *     event-emitter context. Backends that defer to a microtask
-     *     (or later) still work correctly because the feed's listener
-     *     buffers envelopes off the fast path, but synchronous delivery
-     *     minimizes handoff latency.
-     *   - Listener exceptions MUST NOT propagate to the backend's
-     *     event-emitter; the in-memory implementation wraps each
-     *     invocation in try/catch. Production backends should match.
-     */
     subscribeLive(workflowId: string, selector: EventSelector, listener: (envelope: EventEnvelope) => void): () => void;
 };
 export type WorkflowEventFeed = {
-    /**
-     * Replay stored events only. No live subscription. Yields every
-     * envelope with `sequence > decodeCursor(fromCursor)` up to an
-     * optional `limit`, in sequence order, then completes.
-     */
     replay(options: {
         workflowId: string;
         selector: EventSelector;
         fromCursor?: Cursor;
         limit?: number;
     }): AsyncIterable<EventEnvelope>;
-    /**
-     * Replay + live-tail. Implements the atomic-handoff sequence so a
-     * subscriber joining mid-stream sees every event exactly once.
-     * Caller controls termination via `signal.abort()` or by exiting
-     * the `for await` loop (the feed cleans up the live listener).
-     */
     subscribe(options: {
         workflowId: string;
         selector: EventSelector;
-        fromCursor?: Cursor;
-        signal?: AbortSignal;
-    }): AsyncIterable<EventEnvelope>;
-    /** Tear down any feed-level resources (no-op for the in-memory path). */
+    } & ReplayLiveSubscribeOptions<EventEnvelope>): AsyncIterable<EventEnvelope>;
     dispose(): void;
 };
 export type WorkflowEventFeedOptions = {
     /** Max envelopes the live buffer holds before overflow terminates the subscription. */
     liveBufferSize?: number;
 };
+export type SequencedEventEnvelope = {
+    readonly sequence: number;
+    readonly cursor: Cursor;
+};
+export type ReplayLiveFeedBackend<TEnvelope extends SequencedEventEnvelope> = {
+    replay(options: {
+        afterSequence: number;
+    }): AsyncIterable<TEnvelope>;
+    snapshotTailSequence(): Promise<number>;
+    subscribeLive(listener: (envelope: TEnvelope) => void): () => void;
+};
+export type ReplayLiveFeed<TEnvelope extends SequencedEventEnvelope> = {
+    replay(options?: {
+        fromCursor?: Cursor;
+        limit?: number;
+    }): AsyncIterable<TEnvelope>;
+    subscribe(options?: ReplayLiveSubscribeOptions<TEnvelope>): AsyncIterable<TEnvelope>;
+    dispose(): void;
+};
+export type ReplayLiveSubscribeOptions<TEnvelope extends SequencedEventEnvelope> = {
+    fromCursor?: Cursor;
+    signal?: AbortSignal;
+    replayLimit?: number;
+    filterEnvelope?: (envelope: TEnvelope) => boolean;
+    countReplayEnvelope?: (envelope: TEnvelope) => boolean;
+    createReplayLimitError?: (count: number, limit: number) => unknown;
+};
+export declare class ReplayWindowExceededError extends Error {
+    readonly count: number;
+    readonly limit: number;
+    constructor(count: number, limit: number);
+}
+export declare function createReplayLiveFeed<TEnvelope extends SequencedEventEnvelope>(backend: ReplayLiveFeedBackend<TEnvelope>, options?: WorkflowEventFeedOptions): ReplayLiveFeed<TEnvelope>;
 export declare function createWorkflowEventFeed(backend: WorkflowEventFeedBackend, options?: WorkflowEventFeedOptions): WorkflowEventFeed;
 export type InMemoryEventBackend = WorkflowEventFeedBackend & {
-    /** Append an envelope to storage (used by tests). */
     append(envelope: EventEnvelope): Promise<void>;
-    /**
-     * Emit a live event to any active listener WITHOUT persisting it
-     * to storage. Used by tests to simulate the race between storage
-     * writes and live dispatch. Production backends emit and persist in
-     * one step.
-     */
     emitLive(envelope: EventEnvelope): Promise<void>;
 };
 export declare function createInMemoryEventBackend(): InMemoryEventBackend;

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

@@ -12,18 +12,31 @@ export function decodeCursor(cursor) {
     return null;
   return value;
 }
+function decodeCursorOrThrow(cursor) {
+  const sequence = decodeCursor(cursor);
+  if (sequence === null)
+    throw Error("Invalid cursor");
+  return sequence;
+}
+
+export class ReplayWindowExceededError extends Error {
+  count;
+  limit;
+  constructor(count, limit) {
+    super(`Replay window is ${count} events; maximum is ${limit}.`);
+    this.count = count;
+    this.limit = limit;
+    this.name = "ReplayWindowExceededError";
+  }
+}
 const DEFAULT_LIVE_BUFFER_SIZE = 1000;
-export function createWorkflowEventFeed(backend, options) {
+export function createReplayLiveFeed(backend, options) {
   const bufferSize = options?.liveBufferSize ?? DEFAULT_LIVE_BUFFER_SIZE;
   async function* replay(args) {
-    const afterSequence = args.fromCursor !== void 0 ? decodeCursor(args.fromCursor) ?? -1 : -1;
+    const afterSequence = args?.fromCursor !== void 0 ? decodeCursorOrThrow(args.fromCursor) : -1;
     let yielded = 0;
-    for await (const envelope of backend.replay({
-      workflowId: args.workflowId,
-      selector: args.selector,
-      afterSequence
-    })) {
-      if (args.limit !== void 0 && yielded >= args.limit)
+    for await (const envelope of backend.replay({ afterSequence })) {
+      if (args?.limit !== void 0 && yielded >= args.limit)
         return;
       yield envelope;
       yielded += 1;
@@ -32,7 +45,9 @@ export function createWorkflowEventFeed(backend, options) {
   function subscribe(args) {
     const buffer = [];
     let bufferOverflowed = !1, waker = null;
-    const unsubscribe = backend.subscribeLive(args.workflowId, args.selector, (envelope) => {
+    const signal = args?.signal, fromCursor = args?.fromCursor, requestedAfter = fromCursor !== void 0 ? decodeCursorOrThrow(fromCursor) : -1, unsubscribe = backend.subscribeLive((envelope) => {
+      if (!shouldDeliverEnvelope(envelope, args))
+        return;
       if (buffer.length >= bufferSize)
         bufferOverflowed = !0;
       else
@@ -49,22 +64,20 @@ export function createWorkflowEventFeed(backend, options) {
         fire();
       }
     };
-    args.signal?.addEventListener("abort", onAbort);
+    signal?.addEventListener("abort", onAbort);
     async function* generator() {
       try {
-        if (args.signal?.aborted)
+        if (signal?.aborted)
+          return;
+        const snapshot = await backend.snapshotTailSequence();
+        yield* replayUpTo(backend, requestedAfter, snapshot, signal, args);
+        if (signal?.aborted)
           return;
-        const snapshot = await backend.snapshotTailSequence(args.workflowId, args.selector), requestedAfter = args.fromCursor !== void 0 ? decodeCursor(args.fromCursor) ?? -1 : -1;
-        if (snapshot > requestedAfter) {
-          yield* replayUpTo(backend, args, requestedAfter, snapshot);
-          if (args.signal?.aborted)
-            return;
-        }
-        yield* drainLive(buffer, snapshot, args.signal, () => bufferOverflowed, (w) => {
+        yield* drainLive(buffer, snapshot, signal, () => bufferOverflowed, (w) => {
           waker = w;
         });
       } finally {
-        args.signal?.removeEventListener("abort", onAbort);
+        signal?.removeEventListener("abort", onAbort);
         unsubscribe();
       }
     }
@@ -76,19 +89,71 @@ export function createWorkflowEventFeed(backend, options) {
     dispose() {}
   };
 }
-async function* replayUpTo(backend, args, afterSequence, snapshot) {
-  for await (const envelope of backend.replay({
-    workflowId: args.workflowId,
-    selector: args.selector,
-    afterSequence
-  })) {
+export function createWorkflowEventFeed(backend, options) {
+  function createScopedFeed(workflowId, selector) {
+    return createReplayLiveFeed({
+      replay: ({ afterSequence }) => backend.replay({ workflowId, selector, afterSequence }),
+      snapshotTailSequence: () => backend.snapshotTailSequence(workflowId, selector),
+      subscribeLive: (listener) => backend.subscribeLive(workflowId, selector, listener)
+    }, options);
+  }
+  async function* replay(args) {
+    const replayOptions = {};
+    if (args.fromCursor !== void 0)
+      replayOptions.fromCursor = args.fromCursor;
+    if (args.limit !== void 0)
+      replayOptions.limit = args.limit;
+    yield* createScopedFeed(args.workflowId, args.selector).replay(replayOptions);
+  }
+  function subscribe(args) {
+    const subscribeOptions = {};
+    if (args.fromCursor !== void 0)
+      subscribeOptions.fromCursor = args.fromCursor;
+    if (args.signal !== void 0)
+      subscribeOptions.signal = args.signal;
+    if (args.replayLimit !== void 0)
+      subscribeOptions.replayLimit = args.replayLimit;
+    if (args.filterEnvelope !== void 0)
+      subscribeOptions.filterEnvelope = args.filterEnvelope;
+    if (args.countReplayEnvelope !== void 0)
+      subscribeOptions.countReplayEnvelope = args.countReplayEnvelope;
+    if (args.createReplayLimitError !== void 0)
+      subscribeOptions.createReplayLimitError = args.createReplayLimitError;
+    return createScopedFeed(args.workflowId, args.selector).subscribe(subscribeOptions);
+  }
+  return {
+    replay,
+    subscribe,
+    dispose() {}
+  };
+}
+async function* replayUpTo(backend, afterSequence, snapshot, signal, replayOptions) {
+  let replayCount = 0;
+  for await (const envelope of backend.replay({ afterSequence })) {
     if (envelope.sequence > snapshot)
       break;
-    if (args.signal?.aborted)
+    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);
+    }
     yield envelope;
   }
 }
+function shouldDeliverEnvelope(envelope, replayOptions) {
+  return replayOptions?.filterEnvelope?.(envelope) ?? !0;
+}
+function shouldCountReplayEnvelope(envelope, replayOptions) {
+  return replayOptions?.countReplayEnvelope?.(envelope) ?? !0;
+}
+function createReplayLimitError(replayOptions, count, limit) {
+  return replayOptions?.createReplayLimitError?.(count, limit) ?? new ReplayWindowExceededError(count, limit);
+}
 function flushPendingBuffer(buffer, watermark) {
   const batch = [];
   let newWatermark = watermark, head = buffer.shift();
@@ -115,7 +180,7 @@ async function* drainLive(buffer, snapshot, signal, overflowed, installWaker) {
   let watermark = snapshot;
   while (!0) {
     if (signal?.aborted || overflowed())
-      return;
+      break;
     const { batch, newWatermark } = flushPendingBuffer(buffer, watermark);
     watermark = newWatermark;
     for (const envelope of batch) {