@workflow/core 5.0.0-beta.3 → 5.0.0-beta.31

package/dist/runtime/suspension-handler.d.ts

@@ -1,24 +1,98 @@
 import type { Span } from '@opentelemetry/api';
-import { type WorkflowRun, type World } from '@workflow/world';
-import type { WorkflowSuspension } from '../global.js';
+import { type SerializedData, type WorkflowRun, type World } from '@workflow/world';
+import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
 export interface SuspensionHandlerParams {
     suspension: WorkflowSuspension;
     world: World;
     run: WorkflowRun;
     span?: Span;
     requestId?: string;
+    /**
+     * Turbo mode only: a promise that resolves once the backgrounded
+     * `run_started` has landed (the run exists). When present, every world write
+     * this suspension performs (`hook_created`, `wait_created`, eager overflow
+     * `step_created`, …) is gated on it so the write never races ahead of the
+     * run's creation. The pure inline hot path defers all of its steps and writes
+     * nothing here, so it never awaits this barrier. `undefined` outside turbo,
+     * where `run_started` was already awaited up front.
+     */
+    runReadyBarrier?: Promise<unknown>;
 }
+/**
+ * Result of handling a suspension. Returns pending step items so the caller
+ * can decide which to execute inline vs queue to background.
+ */
 export interface SuspensionHandlerResult {
-    timeoutSeconds?: number;
+    /** Pending step items with events created but NOT queued */
+    pendingSteps: StepInvocationQueueItem[];
+    /**
+     * Correlation IDs for which this suspension call actually wrote the
+     * step_created event (as opposed to catching EntityConflictError because
+     * a concurrent handler wrote it first). Only the handler that wrote the
+     * step_created event should queue / inline-execute the step — this
+     * guarantees a single owner per step, even when multiple handlers race
+     * into the same batch boundary.
+     */
+    createdStepCorrelationIds: Set<string>;
+    /**
+     * The steps whose `step_created` writes were intentionally deferred so the
+     * caller can run them inline via lazy `step_started` events (which create
+     * the step on the fly), saving one world round-trip per inline step. Up to
+     * `getMaxInlineSteps()` steps are deferred; the caller runs them inline in
+     * parallel and queues the rest. Empty when no step was deferred (nothing
+     * pending, or a `hook.getConflict()` awaiter is present so nothing is
+     * executed inline). The caller passes each `dehydratedInput` straight to
+     * `executeStep`, which sends it as the `step_started` payload. The atomic
+     * create-claim inside each `step_started` is the exactly-one-owner gate that
+     * the standalone `step_created` provided before: the loser of the race gets
+     * `EntityConflictError` → `skipped` and does not run the body.
+     */
+    lazyInlineSteps: Array<{
+        correlationId: string;
+        stepName: string;
+        dehydratedInput: SerializedData;
+    }>;
+    /**
+     * The soonest pending wait, if any: seconds until it elapses and the
+     * correlationId of the wait that produced that timeout. The
+     * correlationId seeds the idempotency key for the wait-continuation
+     * queue message so that repeated suspension passes over the same
+     * pending wait collapse into a single delayed continuation.
+     */
+    waitTimeout?: {
+        seconds: number;
+        correlationId: string;
+    };
+    /** Whether a hook conflict was detected (should re-invoke immediately) */
+    hasHookConflict: boolean;
+    /** Whether a `hook.getConflict()` awaiter needs the workflow to continue immediately */
+    hasAwaitedHookCreation: boolean;
+    /** Whether native workflow attribute events were written for replay. */
+    hasAttributeEvents: boolean;
+    /**
+     * Whether this suspension created any hook (`hook_created`) events. Unlike
+     * `hasHookConflict` / `hasAwaitedHookCreation`, this is true even for a plain
+     * fire-and-forget hook with no conflict and no awaiter. Turbo mode uses it to
+     * detect "a hook was created this suspension" and stop forcing optimistic
+     * inline start (a hook introduces later resume invocations that could race).
+     */
+    hasHookEvents: boolean;
+    /**
+     * Wall-clock ms spent committing this suspension's `hook_created` events
+     * (0 when it created none). The caller accumulates this across iterations
+     * and subtracts it from the TTFS latency measurement, so time spent
+     * durably creating the user's hooks doesn't count as runtime overhead.
+     */
+    hookCreationMs: number;
 }
 /**
  * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).
- * Uses an event-sourced architecture where entities (steps, hooks) are created atomically
- * with their corresponding events via events.create().
+ * Creates events for all operations but does NOT queue step messages — returns the pending
+ * steps so the caller can decide which to execute inline vs queue to background.
  *
  * Processing order:
  * 1. Hooks are processed first to prevent race conditions with webhook receivers
- * 2. Steps and waits are processed in parallel after hooks complete
+ * 2. Step events and wait events are created in parallel
  */
-export declare function handleSuspension({ suspension, world, run, span, requestId, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
+export declare function handleSuspension({ suspension, world, run, span, requestId, runReadyBarrier, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
 //# sourceMappingURL=suspension-handler.d.ts.map

package/dist/runtime/suspension-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"suspension-handler.d.ts","sourceRoot":"","sources":["../../src/runtime/suspension-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAO/C,OAAO,EAIL,KAAK,WAAW,EAChB,KAAK,KAAK,EACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAIV,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAwBtB,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,WAAW,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,UAAU,EACV,KAAK,EACL,GAAG,EACH,IAAI,EACJ,SAAS,GACV,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAgS5D"}
+{"version":3,"file":"suspension-handler.d.ts","sourceRoot":"","sources":["../../src/runtime/suspension-handler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAQ/C,OAAO,EAGL,KAAK,cAAc,EAGnB,KAAK,WAAW,EAChB,KAAK,KAAK,EACX,MAAM,iBAAiB,CAAC;AAEzB,OAAO,KAAK,EAGV,uBAAuB,EAEvB,kBAAkB,EACnB,MAAM,cAAc,CAAC;AAOtB,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,kBAAkB,CAAC;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,GAAG,EAAE,WAAW,CAAC;IACjB,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC;CACpC;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC,4DAA4D;IAC5D,YAAY,EAAE,uBAAuB,EAAE,CAAC;IACxC;;;;;;;OAOG;IACH,yBAAyB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACvC;;;;;;;;;;;;OAYG;IACH,eAAe,EAAE,KAAK,CAAC;QACrB,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,eAAe,EAAE,cAAc,CAAC;KACjC,CAAC,CAAC;IACH;;;;;;OAMG;IACH,WAAW,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,0EAA0E;IAC1E,eAAe,EAAE,OAAO,CAAC;IACzB,wFAAwF;IACxF,sBAAsB,EAAE,OAAO,CAAC;IAChC,wEAAwE;IACxE,kBAAkB,EAAE,OAAO,CAAC;IAC5B;;;;;;OAMG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB;;;;;OAKG;IACH,cAAc,EAAE,MAAM,CAAC;CACxB;AAgED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,EACrC,UAAU,EACV,KAAK,EACL,GAAG,EACH,IAAI,EACJ,SAAS,EACT,eAAe,GAChB,EAAE,uBAAuB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CA8e5D"}