eve 0.13.3 → 0.13.5

package/dist/src/compiled/@workflow/core/private.d.ts

@@ -5,6 +5,7 @@ import type { CryptoKey } from './encryption.js';
 import type { EventsConsumer } from './events-consumer.js';
 import type { QueueItem } from './global.js';
 import type { Serializable } from './schemas.js';
+import type { StepHydrationCache } from './step-hydration-cache.js';
 export type StepFunction<Args extends Serializable[] = any[], Result extends Serializable | unknown = unknown> = ((...args: Args) => Promise<Result>) & {
     maxRetries?: number;
     stepId?: string;
@@ -46,8 +47,10 @@ export interface WorkflowOrchestratorContext {
     promiseQueue: Promise<void>;
     /**
      * Counter of in-flight async data delivery operations (step result
-     * hydration, hook payload hydration). Suspensions must wait for this
-     * to reach 0 before firing, to avoid preempting data delivery.
+     * hydration, hook payload hydration, abort signal hydration). Suspensions
+     * must wait for this to reach 0 before firing, to avoid preempting data
+     * delivery — e.g. dehydrating a step's arguments while an abort that should
+     * be reflected in those arguments is still hydrating its reason.
      */
     pendingDeliveries: number;
     /**
@@ -81,6 +84,24 @@ export interface WorkflowOrchestratorContext {
      * that do not initialize it degrade gracefully to the previous behavior.
      */
     pendingDeliveryBarriers?: Map<number, DeliveryBarrierEntry>;
+    /**
+     * Per-run memoization cache for hydrated step return values, keyed by the
+     * `step_completed` event id. Owned by the inline replay loop in `runtime.ts`
+     * and threaded through each `runWorkflow` call so it survives across replay
+     * iterations of the SAME run (a fresh context is created each iteration) but
+     * never leaks across unrelated runs.
+     *
+     * On replay K of a sequential N-step workflow, the step consumer would
+     * otherwise re-decrypt and re-parse the results of all K already-completed
+     * steps — O(N²) across an invocation. This cache makes a completed step's
+     * result available in O(1) on subsequent replays. Only primitive results are
+     * memoized, so a shared reference can never let one replay's mutation leak
+     * into the next; see `step-hydration-cache.ts` for the full rationale.
+     *
+     * Optional so contexts that do not initialize it (test harnesses) degrade
+     * gracefully to re-hydrating every replay — identical to previous behavior.
+     */
+    stepHydrationCache?: StepHydrationCache;
 }
 /** The kind of branch-deciding delivery a barrier represents. */
 export type DeliveryKind = 'hook' | 'wait';
@@ -129,6 +150,18 @@ export declare function registerDeliveryBarrier(ctx: WorkflowOrchestratorContext
  * if > 0, wait for promiseQueue → repeat. This handles the multi-round
  * delivery pattern where each hook payload delivery cycle appends new
  * async work to the promiseQueue.
+ *
+ * The initial `setTimeout(0)` macrotask is load-bearing and must NOT be
+ * downgraded to a microtask (`queueMicrotask`/`Promise.resolve().then`).
+ * `pendingDeliveries` only guards the host-side hydration window; between a
+ * delivery's `resolve()` and the workflow VM body running its continuation to
+ * register the next subscriber, `pendingDeliveries` is already 0 even though
+ * the VM is mid-reaction. Node does not guarantee a microtask scheduled in
+ * the host context settles after the cross-VM promise chain (resolve in host
+ * → workflow code in VM → subscribe back in host); the macrotask boundary
+ * gives that chain time to run, so the suspension does not preempt a sibling
+ * delivery still in flight. Empirically, replacing it with `queueMicrotask`
+ * breaks hook/sleep `Promise.race` ordering (CorruptedEventLogError).
  */
 export declare function scheduleWhenIdle(ctx: WorkflowOrchestratorContext, fn: () => void): void;
 export {};

package/dist/src/compiled/@workflow/core/runtime/constants.d.ts

@@ -48,5 +48,78 @@ export declare function getReplayTimeoutMs(): number;
  */
 export declare function _resetReplayTimeoutWarnCacheForTests(): void;
 export declare const REPLAY_TIMEOUT_MAX_RETRIES = 3;
+/**
+ * Default maximum number of steps the owned-inline path runs inline (in
+ * parallel) per suspension. The rest are queued to background handlers. Each
+ * inline step is created lazily — its `step_created` is folded into the
+ * `step_started` that `executeStep` sends — so inlining N steps saves N queue
+ * round-trips for a `Promise.all`-style fan-out. `1` reproduces the
+ * single-inline-step behavior exactly (useful kill-switch).
+ *
+ * Override via `WORKFLOW_MAX_INLINE_STEPS` (clamped to
+ * `MIN_MAX_INLINE_STEPS`..`MAX_MAX_INLINE_STEPS`).
+ */
+export declare const MAX_INLINE_STEPS = 3;
+/** Lower bound for the inline-steps env override (1 = single inline step). */
+export declare const MIN_MAX_INLINE_STEPS = 1;
+/**
+ * Upper bound for the inline-steps env override. Inline bodies run in parallel
+ * within one function invocation, so this caps memory/CPU fan-out per handler.
+ */
+export declare const MAX_MAX_INLINE_STEPS = 16;
+/**
+ * Resolve the effective max number of inline steps for the current process.
+ *
+ * Reads `process.env.WORKFLOW_MAX_INLINE_STEPS` lazily so tests and
+ * deployments can override per invocation. Invalid / out-of-range values fall
+ * back to a safe value (no throw — the env var is an escape hatch) and emit a
+ * one-time warning so misconfiguration is observable.
+ */
+export declare function getMaxInlineSteps(): number;
+/**
+ * Whether optimistic inline step start is enabled. When on, the owned-inline
+ * path begins running a brand-new step's body *before* its lazy `step_started`
+ * network call resolves (the input is already known locally), awaiting the
+ * `step_started` only before the terminal write.
+ *
+ * This can run a step body more than once when handlers race for the same
+ * step's create-claim — both run the body before one wins. That is unsafe for
+ * steps with non-idempotent side effects; in particular, two concurrent runs
+ * of a step that writes to the workflow stream (e.g. an AI agent streaming
+ * tokens) can interleave and corrupt the stream data. So the optimization is
+ * **off by default** and must be explicitly opted into per deployment.
+ *
+ * Reads `process.env.WORKFLOW_OPTIMISTIC_INLINE_START` lazily. Default OFF;
+ * enabled only by an explicit `'1'` / `'true'`.
+ */
+export declare function isOptimisticInlineStartEnabled(): boolean;
+/**
+ * Whether an operator has **explicitly disabled** optimistic inline start via
+ * `WORKFLOW_OPTIMISTIC_INLINE_START=0` / `=false`. Distinct from "unset": unset
+ * leaves the optimization off by default but lets turbo force it on; an explicit
+ * `0`/`false` is an operator opt-out that turbo must honor (turbo's forced
+ * optimistic start still runs a step body before `step_started`/`run_started` is
+ * confirmed, the property such an operator is opting out of), so
+ * `forceOptimisticStart` defers to this. Reads the env var lazily.
+ */
+export declare function isOptimisticInlineStartExplicitlyDisabled(): boolean;
+/**
+ * Whether "turbo mode" is enabled. Turbo mode fast-paths the *first delivery of
+ * the first invocation* of a run (detected by the entrypoint via `runInput`
+ * presence + `metadata.attempt === 1`): it backgrounds the `run_started` event
+ * creation, skips the initial event-log load (nothing has been written yet),
+ * and forces optimistic inline step start for that invocation — independent of
+ * `WORKFLOW_OPTIMISTIC_INLINE_START`.
+ *
+ * Forcing optimistic start is safe here because the first delivery has no
+ * concurrent peer handler to race the step create-claim, so a step body runs
+ * exactly once. That single-handler guarantee ends as soon as the run creates a
+ * hook or wait (which introduce resume/parallel invocations), so the runtime
+ * exits turbo at that point.
+ *
+ * Reads `process.env.WORKFLOW_TURBO` lazily. Default **ON**; disabled only by an
+ * explicit `'0'` / `'false'` (case-insensitive).
+ */
+export declare function isTurboEnabled(): boolean;
 export declare const REPLAY_DIVERGENCE_MAX_RETRIES = 3;
 //# sourceMappingURL=constants.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/get-port-lazy.d.ts

@@ -7,4 +7,19 @@
  * dependency is invisible to bundler static analysis.
  */
 export declare function getPortLazy(): Promise<number | undefined>;
+/**
+ * Resets the per-process port cache. Intended for tests; not used on the hot
+ * path. Callers must let any in-flight lookup settle (await the pending
+ * `getPortLazy()` call) before resetting: clearing `_inFlight` here does not
+ * cancel an already-scheduled resolution, so a late `.then` could otherwise
+ * repopulate `_cachedPort` after the reset and bleed into the next test.
+ */
+export declare function resetPortCacheForTesting(): void;
+/**
+ * Installs a fake port resolver and clears the cache. Test-only seam: the real
+ * resolver is loaded via `createRequire` with a runtime-built specifier (to
+ * hide it from bundlers), which also defeats module mocking, so injection is
+ * the only deterministic way to exercise the caching contract.
+ */
+export declare function setPortResolverForTesting(fn: () => Promise<number | undefined>): void;
 //# sourceMappingURL=get-port-lazy.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/run-id-time.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extracts the run's creation timestamp (epoch milliseconds) from a `wrun_`
+ * run ID by decoding the embedded ULID time component.
+ *
+ * Returns `undefined` when `runId` is not a decodable `wrun_<ulid>` (e.g. a
+ * legacy/non-ULID id, or a test fixture like `wrun_test`); callers fall back to
+ * an authoritative timestamp from the run snapshot (`createdAt`) in that case.
+ */
+export declare function runIdCreatedAt(runId: string): number | undefined;
+//# sourceMappingURL=run-id-time.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/step-executor.d.ts

@@ -1,4 +1,4 @@
-import type { World } from '#compiled/@workflow/world/index.js';
+import type { Event, SerializedData, World } from '#compiled/@workflow/world/index.js';
 import type { CryptoKey } from '../encryption.js';
 export interface StepExecutorParams {
     world: World;
@@ -16,14 +16,74 @@ export interface StepExecutorParams {
      * as possibly containing compressed payloads (specVersion >= 5).
      */
     runSpecVersion?: number;
+    /**
+     * Lazy step start: the already-dehydrated step input. When provided, the
+     * `step_started` event carries this input so the world creates the step on
+     * the fly (no separate `step_created` round-trip). Set by the owned-inline
+     * path for the step whose `step_created` the suspension handler deferred.
+     * The world's atomic create-claim is the exactly-one-owner gate: losing it
+     * surfaces as `EntityConflictError` → `{ type: 'skipped' }`, so a handler
+     * that did not win the create never runs the body. Omitted on every other
+     * path, where the step already has a `step_created` and `step_started`
+     * carries no payload (the legacy contract).
+     */
+    lazyStepInput?: SerializedData;
+    /**
+     * Inline-delta optimization (opt-in). When provided, the cursor of the
+     * event log as observed by the caller *before* this step's events were
+     * written. It is threaded into the step-terminal `events.create` so a
+     * supporting World can return the delta of events written since (see
+     * {@link import('@workflow/world').CreateEventParams.sinceCursor}).
+     * Only set this when `correlationId`-based ownership guarantees this
+     * handler is the sole inline writer for the run on this iteration.
+     */
+    inlineDeltaSinceCursor?: string;
+    /**
+     * Force optimistic inline start regardless of
+     * `WORKFLOW_OPTIMISTIC_INLINE_START`. Set by turbo mode on the first delivery
+     * of the first invocation, where forcing it is safe: there is no concurrent
+     * peer handler to race the create-claim, so the body runs exactly once. Only
+     * meaningful together with `lazyStepInput` (a brand-new lazy step).
+     */
+    forceOptimisticStart?: boolean;
+    /**
+     * Turbo mode only: a promise that resolves once the backgrounded
+     * `run_started` has landed. When set, the lazy/optimistic `step_started` is
+     * chained on it so the step is never created before its run exists. The body
+     * still runs immediately against locally-synthesized state — only the network
+     * write waits — so the `run_started` round-trip overlaps the body. `undefined`
+     * outside turbo, where `run_started` was already awaited up front.
+     */
+    runReadyBarrier?: Promise<unknown>;
+}
+/**
+ * Inline-delta returned by a step-terminal write when the caller passed
+ * {@link StepExecutorParams.inlineDeltaSinceCursor} and the World supports
+ * the optimization. `events` are the events written strictly after that
+ * cursor (this step's events plus anything interleaved in-band), `cursor`
+ * is the position past the last one, and `hasMore` signals a further page
+ * (the caller then falls back to a full incremental fetch). Absent when
+ * the World did not return a delta.
+ */
+export interface InlineEventDelta {
+    events: Event[];
+    cursor: string | null;
+    hasMore: boolean;
 }
 /**
  * Result of a step execution attempt. The caller decides what to do
  * based on the result type (e.g., queue workflow continuation, replay inline, etc.).
+ *
+ * `inlineDelta` is attached to a `completed` result when the caller
+ * requested it via {@link StepExecutorParams.inlineDeltaSinceCursor} and
+ * the World returned one. Step failures are rare and not the inline
+ * optimization's target, so the `failed` path leaves it to the normal
+ * incremental fetch.
  */
 export type StepExecutionResult = {
     type: 'completed';
     hasPendingOps?: boolean;
+    inlineDelta?: InlineEventDelta;
 } | {
     type: 'failed';
 } | {

package/dist/src/compiled/@workflow/core/runtime/suspension-handler.d.ts

@@ -1,5 +1,5 @@
 import type { Span } from '#compiled/@opentelemetry/api/index.js';
-import { type WorkflowRun, type World } from '#compiled/@workflow/world/index.js';
+import { type SerializedData, type WorkflowRun, type World } from '#compiled/@workflow/world/index.js';
 import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
 export interface SuspensionHandlerParams {
     suspension: WorkflowSuspension;
@@ -7,6 +7,16 @@ export interface SuspensionHandlerParams {
     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
@@ -24,6 +34,24 @@ export interface SuspensionHandlerResult {
      * 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
@@ -41,6 +69,14 @@ export interface SuspensionHandlerResult {
     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;
 }
 /**
  * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).
@@ -51,5 +87,5 @@ export interface SuspensionHandlerResult {
  * 1. Hooks are processed first to prevent race conditions with webhook receivers
  * 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/src/compiled/@workflow/core/runtime.d.ts

@@ -20,5 +20,6 @@ export { createWorld, getWorld, getWorldHandlers, setWorld, } from './runtime/wo
  */
 export declare function workflowEntrypoint(workflowCode: string, options?: {
     namespace?: string;
+    routeModuleBodyStartedAt?: number;
 }): (req: Request) => Promise<Response>;
 //# sourceMappingURL=runtime.d.ts.map