eve 0.26.2 → 0.27.1

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

@@ -1,11 +1,12 @@
 /**
  * Utils used by the bundler when transforming code
  */
+import type { WorldCapabilities } from '#compiled/@workflow/world/index.js';
 import type { CryptoKey } from './encryption.js';
 import type { EventsConsumer } from './events-consumer.js';
 import type { QueueItem } from './global.js';
+import type { ReplayPayloadCache } from './replay-payload-cache.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;
@@ -27,6 +28,7 @@ export declare function getStepFunction(stepId: string): StepFunction | undefine
 export interface WorkflowOrchestratorContext {
     runId: string;
     encryptionKey: CryptoKey | undefined;
+    worldCapabilities?: WorldCapabilities;
     globalThis: typeof globalThis;
     eventsConsumer: EventsConsumer;
     /**
@@ -85,23 +87,10 @@ export interface WorkflowOrchestratorContext {
      */
     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.
+     * Invocation-scoped cache of prepared serialized payloads and immutable final
+     * values. Prepared bytes survive fresh replay VMs; object graphs do not.
      */
-    stepHydrationCache?: StepHydrationCache;
+    replayPayloadCache: ReplayPayloadCache;
 }
 /** The kind of branch-deciding delivery a barrier represents. */
 export type DeliveryKind = 'hook' | 'wait';

package/dist/src/compiled/@workflow/core/private.js

@@ -1 +1 @@
-import{c as e}from"../../_chunks/workflow/dist-CttsoN4D.js";const t=Symbol.for(`@workflow/core//registeredSteps`),n=globalThis,r=n[t]??=new Map,i=new Set([`__builtin_response_array_buffer`,`__builtin_response_json`,`__builtin_response_text`]);function a(e){let t=e.split(`//`);if(t.length!==3||t[0]!==`step`)return[];let n=t[1],r=t[2],i=new Set,a=e=>{e!==n&&i.add(e)};if(n.startsWith(`./workflows/`)){let e=n.slice(2);a(`./example/${e}`),a(`./src/${e}`)}else if(n.startsWith(`./example/workflows/`)){let e=n.slice(10);a(`./${e}`),a(`./src/${e}`)}else if(n.startsWith(`./src/workflows/`)){let e=n.slice(6);a(`./${e}`),a(`./example/${e}`)}return Array.from(i,e=>`step//${e}//${r}`)}function o(e){if(i.has(e)){for(let[t,n]of r.entries())if(t.endsWith(`//${e}`))return n}}function s(e,t){r.set(e,t),t.stepId=e}function c(e){let t=r.get(e);if(t)return t;for(let t of a(e)){let e=r.get(t);if(e)return e}let n=o(e);if(n)return n}async function l(e,t,n){if(t===void 0||!e.pendingDeliveryBarriers||e.pendingDeliveryBarriers.size===0)return;let r=[];for(let[i,a]of e.pendingDeliveryBarriers)i<t&&n.includes(a.kind)&&r.push(a.delivered);r.length>0&&await Promise.all(r)}function u(t,n,r){let i=t.pendingDeliveryBarriers;if(!i||n===void 0)return{markDelivered:()=>{}};let a=!1,{promise:o,resolve:s}=e(),c={kind:r,delivered:o};i.set(n,c);let l=()=>{a||(a=!0,i.get(n)===c&&i.delete(n),s())};return d(t,l),{markDelivered:l}}function d(e,t){let n=()=>{e.pendingDeliveries>0?e.promiseQueue.then(()=>{setTimeout(n,0)}):t()};setTimeout(n,0)}export{l as awaitEarlierDeliveries,c as getStepFunction,u as registerDeliveryBarrier,s as registerStepFunction,d as scheduleWhenIdle};
+import{c as e}from"../../_chunks/workflow/dist-CrxV2rsR.js";const t=Symbol.for(`@workflow/core//registeredSteps`),n=globalThis,r=n[t]??=new Map,i=new Set([`__builtin_response_array_buffer`,`__builtin_response_json`,`__builtin_response_text`]);function a(e){let t=e.split(`//`);if(t.length!==3||t[0]!==`step`)return[];let n=t[1],r=t[2],i=new Set,a=e=>{e!==n&&i.add(e)};if(n.startsWith(`./workflows/`)){let e=n.slice(2);a(`./example/${e}`),a(`./src/${e}`)}else if(n.startsWith(`./example/workflows/`)){let e=n.slice(10);a(`./${e}`),a(`./src/${e}`)}else if(n.startsWith(`./src/workflows/`)){let e=n.slice(6);a(`./${e}`),a(`./example/${e}`)}return Array.from(i,e=>`step//${e}//${r}`)}function o(e){if(i.has(e)){for(let[t,n]of r.entries())if(t.endsWith(`//${e}`))return n}}function s(e,t){r.set(e,t),t.stepId=e}function c(e){let t=r.get(e);if(t)return t;for(let t of a(e)){let e=r.get(t);if(e)return e}let n=o(e);if(n)return n}async function l(e,t,n){if(t===void 0||!e.pendingDeliveryBarriers||e.pendingDeliveryBarriers.size===0)return;let r=[];for(let[i,a]of e.pendingDeliveryBarriers)i<t&&n.includes(a.kind)&&r.push(a.delivered);r.length>0&&await Promise.all(r)}function u(t,n,r){let i=t.pendingDeliveryBarriers;if(!i||n===void 0)return{markDelivered:()=>{}};let a=!1,{promise:o,resolve:s}=e(),c={kind:r,delivered:o};i.set(n,c);let l=()=>{a||(a=!0,i.get(n)===c&&i.delete(n),s())};return d(t,l),{markDelivered:l}}function d(e,t){let n=()=>{e.pendingDeliveries>0?e.promiseQueue.then(()=>{setTimeout(n,0)}):t()};setTimeout(n,0)}export{l as awaitEarlierDeliveries,c as getStepFunction,u as registerDeliveryBarrier,s as registerStepFunction,d as scheduleWhenIdle};

package/dist/src/compiled/@workflow/core/replay-payload-cache.d.ts

@@ -0,0 +1,56 @@
+import type { Event, WorkflowRun } from '#compiled/@workflow/world/index.js';
+import type { CryptoKey } from './encryption.js';
+import { type PreparedReplayPayload, type ReplayPayloadPreparer } from './serialization.js';
+type ReplayPayloadField = 'result' | 'error' | 'payload';
+/**
+ * Invocation-scoped cache for replay payload hydration.
+ *
+ * A workflow invocation may replay the same event log through several fresh
+ * VMs. This cache keeps the VM-independent decrypt/decompress result across
+ * those replays. Deserialization still runs against each VM's globals so every
+ * replay receives fresh object graphs and correctly revived Workflow objects.
+ *
+ * Successful prepared plaintext remains resident for the invocation lifetime.
+ * Its memory cost is the sum of decrypted and decompressed payload sizes, but
+ * it never crosses workflow runs or queue deliveries.
+ */
+export declare class ReplayPayloadCache {
+    private readonly encryptionKey;
+    private readonly preparer;
+    private readonly preparedPayloads;
+    private readonly primitiveStepResults;
+    constructor(encryptionKey: CryptoKey | undefined, preparer?: ReplayPayloadPreparer);
+    /**
+     * Start every missing binary preparation before workflow execution. Failures
+     * are intentionally retained: the ordered event consumer must observe the
+     * original rejection before that entry becomes retryable.
+     */
+    prewarm(workflowRun: WorkflowRun, events: Event[]): Promise<void>;
+    /** Return the workflow input after shared host-side preparation. */
+    prepareWorkflowInput(workflowRun: WorkflowRun): Promise<PreparedReplayPayload>;
+    /**
+     * Return an event payload after shared host-side preparation. A rejected
+     * preparation is evicted only after this ordered consumer requests it, so a
+     * later replay can retry without hiding the original failure.
+     */
+    prepareEventPayload(eventId: string, field: ReplayPayloadField, value: unknown): Promise<PreparedReplayPayload>;
+    /**
+     * Reuse final step values only when sharing them across VMs is unobservable.
+     * Objects and large strings/bigints always run `hydrate` again, producing a
+     * fresh VM-specific value from the separately cached prepared payload.
+     */
+    getStepResult(eventId: string, hydrate: () => Promise<unknown>): Promise<unknown>;
+    /**
+     * Consumer-facing lookup. Binary payloads share preparation; legacy values
+     * bypass the cache because their flattened representation may be mutated.
+     */
+    private consumePreparation;
+    /** Start preparation once and share the exact in-flight promise. */
+    private ensurePreparation;
+    /** Normalize synchronous and asynchronous preparers to one promise contract. */
+    private runPreparation;
+    private workflowInputKey;
+    private eventPayloadKey;
+}
+export {};
+//# sourceMappingURL=replay-payload-cache.d.ts.map

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

@@ -85,6 +85,17 @@ export declare const MAX_MAX_INLINE_STEPS = 16;
  * one-time warning so misconfiguration is observable.
  */
 export declare function getMaxInlineSteps(): number;
+/**
+ * Optional client-side override for the server-supplied per-run event ceiling.
+ * When set to a positive integer, the runtime clamps the server's limit *down*
+ * to this value (never raises it) so enforcement can be exercised without a
+ * server-side change. `undefined` (unset) ⇒ use the server value as-is.
+ *
+ * Reads `process.env.WORKFLOW_MAX_EVENTS_OVERRIDE` lazily so tests and
+ * deployments can override per invocation. Invalid values fall back to unset
+ * (no throw — the env var is an escape hatch) and emit a one-time warning.
+ */
+export declare function getMaxEventsOverride(): number | undefined;
 /**
  * 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`

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

@@ -89,10 +89,12 @@ export interface MutableEventLog {
     cursor: string | null;
 }
 /**
- * Whether the optimistic-concurrency guard for event creation is enabled
- * (`WORKFLOW_PRECONDITION_GUARD=1`, set where the runtime executes). Off by
- * default: replay-context creates only send a `stateUpdatedAt` snapshot (and
- * can therefore be rejected with 412 by the backend) when it is enabled.
+ * Whether the optimistic-concurrency guard for event creation is enabled.
+ * **On by default** where the runtime executes: replay-context creates send a
+ * `stateUpdatedAt` snapshot (and can be rejected with 412 by a supporting
+ * backend) unless `WORKFLOW_PRECONDITION_GUARD` is set to `0`. Backends without
+ * guard support ignore the snapshot, so enabling by default is
+ * backward-compatible.
  */
 export declare function isPreconditionGuardEnabled(): boolean;
 /**

package/dist/src/compiled/@workflow/core/runtime/resume-hook.d.ts

@@ -5,6 +5,9 @@ import { type CryptoKey } from '../encryption.js';
  * and hydrate the `metadata` property if it was set from within
  * the workflow run.
  *
+ * A Hook kept by minimum retention remains available here after its run ends,
+ * but cannot be resumed.
+ *
  * @param token - The unique token identifying the hook
  */
 export declare function getHookByToken(token: string): Promise<Hook>;
@@ -17,7 +20,7 @@ export declare function getHookByToken(token: string): Promise<Hook>;
  * @param tokenOrHook - The unique token identifying the hook, or the hook object itself
  * @param payload - The data payload to send to the hook
  * @returns Promise resolving to the hook
- * @throws Error if the hook is not found or if there's an error during the process
+ * @throws {HookNotFoundError} If the Hook does not exist or its run has ended
  *
  * @example
  *

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

@@ -1,6 +1,7 @@
 import type { Event, SerializedData, World } from '#compiled/@workflow/world/index.js';
 import type { CryptoKey } from '../encryption.js';
 import { type StepLatencyTracking } from './step-latency.js';
+export declare const DEFAULT_STEP_MAX_RETRIES = 3;
 export interface StepExecutorParams {
     world: World;
     workflowRunId: string;
@@ -54,6 +55,33 @@ export interface StepExecutorParams {
      * handler is the sole inline writer for the run on this iteration.
      */
     inlineDeltaSinceCursor?: string;
+    /**
+     * Precondition-guard snapshot (epoch ms of the latest event the caller's
+     * replay loaded) to attach to this step's `step_started` claim. On the lazy
+     * inline path the claim is the step's FIRST durable write (its
+     * `step_created` is deferred), so without this the claim would bypass the
+     * optimistic-concurrency guard entirely: a replay working from a stale view
+     * could claim — and then commit — a step scheduled without observing an
+     * out-of-band event. A guard-enforcing World rejects a stale claim with
+     * `PreconditionFailedError` (412); executeStep does NOT translate that
+     * rejection (re-claiming in place would still commit the stale schedule),
+     * so it propagates for the caller to abandon the batch and force a fresh
+     * replay. Undefined when the guard is disabled or the caller has no
+     * snapshot; Worlds that don't enforce the guard ignore it.
+     */
+    stateUpdatedAt?: number;
+    /**
+     * Suppress optimistic inline start for this step regardless of
+     * `WORKFLOW_OPTIMISTIC_INLINE_START` / `forceOptimisticStart`: take the
+     * await-then-run path so the body only runs after the `step_started` claim
+     * succeeds. Set by the runtime for guard-enforced batches that are
+     * stale-sensitive (an open hook means an out-of-band event can make the
+     * scheduling view stale): the guard's 412 fence can reject a stale claim's
+     * durable writes, but it cannot un-run a body that optimistic start began
+     * before the claim settled — awaiting the claim extends the fence to user
+     * code. Wins over `forceOptimisticStart` and the env flag.
+     */
+    suppressOptimisticStart?: boolean;
     /**
      * Force optimistic inline start regardless of
      * `WORKFLOW_OPTIMISTIC_INLINE_START`. Set by turbo mode on the first delivery
@@ -80,6 +108,17 @@ export interface StepExecutorParams {
      * runtime/step-latency.ts.
      */
     latencyTracking?: StepLatencyTracking;
+    /**
+     * Authoritative attempt number for this execution, used to bound retries
+     * against `maxRetries` BEFORE the body runs. In order to also catch
+     * step timeouts (which we can't have catch handlers for), we determine
+     * the attempt count based as follows:
+     * - Inline (combined handler): the number of `step_started` events already
+     *   in the event log for this step, plus one for the attempt about to run.
+     * - Background (queue-dispatched): the queue delivery count
+     *   (`metadata.attempt`), which increments on every redelivery.
+     */
+    authoritativeAttempt?: number;
 }
 /**
  * Inline-delta returned by a step-terminal write when the caller passed