eve 0.75.0 → 0.76.0

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

@@ -77,6 +77,16 @@ export declare class WorkflowSuspension extends Error {
     attributeCount: number;
     hookDisposedCount: number;
     abortCount: number;
+    /**
+     * Correlation ids of the open hooks that workflow code was waiting on a
+     * payload for when the VM went idle, i.e. the hooks whose `hook_received`
+     * could change what this suspension leads to. A hook absent from the set has
+     * no waiting consumer, so a payload landing for it is buffered and inert
+     * until the first `await`. `undefined` when the suspension was built without
+     * the workflow context that tracks awaiters, which callers must read as
+     * "every open hook is observed". See `runtime/out-of-band-observation.ts`.
+     */
+    observedHookIds?: ReadonlySet<string>;
     constructor(itemsInput: Map<string, QueueItem>, global: typeof globalThis);
     static is(value: unknown): value is WorkflowSuspension;
 }

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

@@ -1,2 +1,2 @@
-import"../../_chunks/workflow/dist-DmXynLVH.js";import{$r as e,Br as t,Gr as n,Jr as r,K as i,Kr as a,Qr as o,Sr as s,T as c,Ur as l,Zr as u,ei as d,i as f,q as p,qr as m,x as h}from"../../_chunks/workflow/serialization-vDozzDhh.js";import{d as g,i as _}from"../../_chunks/workflow/dist-T5NnW-0k.js";import{a as v,i as y,r as b,t as x}from"../../_chunks/workflow/attribute-changes-CSqvJx6j.js";import{n as S}from"../../_chunks/workflow/resume-hook-CvENCrxc.js";import{t as C}from"../../_chunks/workflow/sleep-BMqbraZM.js";function w(e){y(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,w)}function T(e){y(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,T)}function E({schema:e}={}){function t(e){y(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await S(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
+import"../../_chunks/workflow/dist-CyBgVS7g.js";import{$r as e,Br as t,Gr as n,Jr as r,K as i,Kr as a,Qr as o,Sr as s,T as c,Ur as l,Zr as u,ei as d,i as f,q as p,qr as m,x as h}from"../../_chunks/workflow/serialization-DPdYS_w2.js";import{d as g,i as _}from"../../_chunks/workflow/dist-T5NnW-0k.js";import{a as v,i as y,r as b,t as x}from"../../_chunks/workflow/attribute-changes-BW-kbMMn.js";import{n as S}from"../../_chunks/workflow/resume-hook-DMsV_b4n.js";import{t as C}from"../../_chunks/workflow/sleep-BY6leHh8.js";function w(e){y(`createHook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-hook`,w)}function T(e){y(`createWebhook()`,`https://workflow-sdk.dev/docs/api-reference/workflow/create-webhook`,T)}function E({schema:e}={}){function t(e){y(`defineHook().create()`,`https://workflow-sdk.dev/docs/api-reference/workflow/define-hook`,t)}return{create:t,async resume(t,n){if(!e?.[`~standard`])return await S(t,n);let r=e[`~standard`].validate(n);if(r instanceof Promise&&(r=await r),r.issues){let e=r.issues.map(e=>{let t=e.path?.map(e=>String(typeof e==`object`&&e?e.key:e)).join(`.`);return t?`  at "${t}": ${e.message}`:`  ${e.message}`});throw Error(`Hook payload did not match the defined schema:\n${e.join(`
 `)}`)}return await S(t,r.value)}}}async function D(e,t={}){let n=p.getStore(),r=n?.workflowMetadata?.workflowRunId;if(!r)throw new _(`setAttributes() must be called from a 'use workflow' or 'use step' function. Calling it from plain host code is not supported.`);let i={type:`step`,stepId:n.stepMetadata.stepId,attempt:n.stepMetadata.attempt},a=x(e,t,i);if(a.length!==0){if(n.runReadyBarrier)try{await n.runReadyBarrier}catch{}await(await l()).events.create(r,{eventType:`attr_set`,specVersion:8,eventData:{changes:a,writer:i,...t.allowReservedAttributes===!0?{allowReservedAttributes:!0}:{}}})}}function O(){let e=p.getStore();return e||b(`getStepMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-step-metadata`,O),e.stepMetadata}function k(){let e=p.getStore();return e||v(`getWorkflowMetadata()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-workflow-metadata`,k),e.workflowMetadata}function A(l={}){let g=p.getStore();g||v(`getWritable()`,`https://workflow-sdk.dev/docs/api-reference/workflow/get-writable`,A);let{namespace:_}=l,y=g.workflowMetadata.workflowRunId,b=i(y,_);g.writables??=new Map;let x=g.writables,S=x.get(b);if(S)return S.writable;let C=n();C.deferReleaseSettlement=g.streamStates!==void 0;let w=c(h(globalThis,g.ops,y,g.encryptionKey,!0,g.runReadyBarrier),g.encryptionKey),T=new f(y,b,g.runReadyBarrier);g.streamStates??=[],g.streamStates.push(C),g.ops.push(C.promise),a(w.readable,T,C).catch(()=>{});let E=r(w.writable,C);return m(E,C),Object.defineProperty(E,u,{value:b,writable:!1}),Object.defineProperty(E,d,{value:y,writable:!1}),g.workflowDeploymentId&&Object.defineProperty(E,o,{value:g.workflowDeploymentId,writable:!1}),s(g.encryptionKey)&&Object.defineProperty(E,e,{value:t(g.encryptionKey.keyPair.publicKey),writable:!1}),x.set(b,{writable:E,state:C}),E}export{_ as FatalError,g as RetryableError,w as createHook,T as createWebhook,E as defineHook,O as getStepMetadata,k as getWorkflowMetadata,A as getWritable,D as setAttributes,C as sleep};

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

@@ -44,6 +44,17 @@ export interface WorkflowOrchestratorContext {
      * Using Map instead of Array for O(1) lookup/delete operations.
      */
     invocationsQueue: Map<string, QueueItem>;
+    /**
+     * Per open hook, a probe for whether workflow code is currently waiting on
+     * its next payload (an `await hook`, a pending `for await` iteration, or a
+     * `.then` on it). Registered by `createHook` and dropped once the hook can
+     * receive nothing more. Snapshotted into
+     * {@link WorkflowSuspension.observedHookIds} when a suspension is raised.
+     *
+     * Optional so older/out-of-tree contexts (and lightweight test harnesses)
+     * degrade to "every open hook is observed".
+     */
+    hookPayloadAwaiters?: Map<string, () => boolean>;
     onWorkflowError: (error: Error) => void;
     /**
      * Mints the ULID body of a correlation id. Every entity a replay creates

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

@@ -1 +1 @@
-import{a as e,c as t,i as n,n as r,o as i,r as a,s as o,t as s}from"../../_chunks/workflow/private-Dlf90Zvn.js";export{s as awaitEarlierDeliveries,r as getStepFunction,a as hasParkedCommittedDelivery,n as isDeliveryIdle,e as registerDeliveryBarrier,i as registerStepFunction,o as scheduleWhenIdle,t as scheduleWorkflowSuspension};
+import{a as e,c as t,i as n,n as r,o as i,r as a,s as o,t as s}from"../../_chunks/workflow/private-tQUuwBoQ.js";export{s as awaitEarlierDeliveries,r as getStepFunction,a as hasParkedCommittedDelivery,n as isDeliveryIdle,e as registerDeliveryBarrier,i as registerStepFunction,o as scheduleWhenIdle,t as scheduleWorkflowSuspension};

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

@@ -139,15 +139,43 @@ export declare function isResilientStepDispatchEnabled(): boolean;
 export declare function isBatchTransitionsEnabled(): boolean;
 /**
  * Ceiling on events per `createBatch` call from the batched fan-out fold.
- * Mirrors the server's transaction budgets with a comfortable margin: each
- * fan-out event costs 2 transaction items server-side (entity + event row)
- * against the 100-item DynamoDB cap, and inline payloads count against a
- * 768 KB byte budget, so 32 events stays well under both, and a fan-out larger
- * than this commits in successive batches (split batches lose
- * cross-batch atomicity, which is exactly today's per-event-write crash
- * surface, and every batch still converges on retry via per-event 409s).
+ * The server's transaction budgets are the hard limit: each fan-out event
+ * costs 2 transaction items server-side (entity + event row) against the
+ * 100-item DynamoDB cap, and inline payloads count against a 768 KB byte
+ * budget. A fan-out larger than this commits in successive batches, all in
+ * flight at once (split batches lose cross-batch atomicity, which is exactly
+ * the per-event-write crash surface, and every batch still converges on retry
+ * via per-event 409s).
+ *
+ * Within the budget the value is a latency trade, measured on durabench
+ * production sweeps (Vercel World, iad1, `Promise.all` of N one-step branches,
+ * 100 ms of work and 1 KB JSON each, 2026-10-07, every candidate built off the
+ * same commit and interleaved in one sweep):
+ *
+ * - A queued (non-inline) branch's message is published only once the chunk
+ *   carrying its `step_created` commits, then goes out in that chunk's
+ *   batched publish, and both hops slow down as the chunk grows. Smaller
+ *   chunks start the queued branches sooner: at 64 branches the queued
+ *   branches' median `step_started` moved from ~570 ms after `run_started` at
+ *   32 to ~460 ms at 16, and the last branch's first line from 967 to 875 ms
+ *   (p50, 45 runs each); at 128 branches, from 4,059 to 3,855 ms (20 runs).
+ * - More chunks are more concurrent `createBatch` requests per run, and the
+ *   inline branches' pair chunk is one of them. From about 16 concurrent
+ *   chunks the first (inline) branch slows down: at 128 branches 8 per chunk
+ *   cost it ~120 ms, and at 256 branches 4, 8 and 12 per chunk cost it ~470,
+ *   ~120 and ~140 ms. At 16 a 256-branch fan-out is 16 plain chunks, at the
+ *   edge of that (+~100 ms, not significant over 20 runs); at 24 and 32 it
+ *   is flat.
+ *
+ * 16 is the largest value with a clear last-branch gain at 64 and 128
+ * branches and no first-branch or join regression there; an 8-branch fan-out
+ * fits one chunk either way. It also keeps the default inline pairs (two rows
+ * per inline step, `MAX_INLINE_STEPS` = 3) in one chunk. A
+ * `WORKFLOW_MAX_INLINE_STEPS` above 8 spills the pairs into more than one pair
+ * chunk; they commit concurrently and all of them gate the inline bodies, so
+ * that degrades latency, not correctness.
  */
-export declare const MAX_BATCH_FANOUT_EVENTS = 32;
+export declare const MAX_BATCH_FANOUT_EVENTS = 16;
 /**
  * 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*

package/dist/src/compiled/@workflow/core/runtime/helpers.js

@@ -1 +1 @@
-import{C as e,D as t,E as n,O as r,S as i,T as a,_ as o,a as s,b as c,c as l,d as u,f as d,g as f,h as p,i as m,k as h,l as g,m as _,n as v,o as y,p as b,r as x,s as S,t as C,u as w,v as T,w as E,x as D,y as O}from"../../../_chunks/workflow/helpers-BXCuoPUb.js";export{C as DYNAMIC_WORKFLOW_VERSION,v as REPLAY_RESOLVE_DATA,x as SLOT_GAP_RECHECK_ATTEMPTS,m as absorbSkippedSlotReport,s as appendEventLog,y as appendUniqueEvents,S as findEventSlotGap,l as getQueueOverhead,g as getWorkflowQueueName,w as handleHealthCheckMessage,u as healthCheck,d as insertEventByEventId,b as isSlotGapCheckEnabled,_ as loadWorkflowRunEvents,p as maxEventSlot,f as memoizeEncryptionKey,o as mergeReportedEvents,T as parseHealthCheckPayload,O as preconditionEventDelta,c as queueMessage,D as queueMessages,i as resolveRunEncryptionKey,e as rootRunIdFrom,E as runDispatchContext,a as settleEventSlotGap,n as slotSnapshotParams,t as stepDispatchIdempotencyKey,r as withHealthCheck,h as withReplayDelta};
+import{C as e,D as t,E as n,O as r,S as i,T as a,_ as o,a as s,b as c,c as l,d as u,f as d,g as f,h as p,i as m,k as h,l as g,m as _,n as v,o as y,p as b,r as x,s as S,t as C,u as w,v as T,w as E,x as D,y as O}from"../../../_chunks/workflow/helpers-DlLD3ov_.js";export{C as DYNAMIC_WORKFLOW_VERSION,v as REPLAY_RESOLVE_DATA,x as SLOT_GAP_RECHECK_ATTEMPTS,m as absorbSkippedSlotReport,s as appendEventLog,y as appendUniqueEvents,S as findEventSlotGap,l as getQueueOverhead,g as getWorkflowQueueName,w as handleHealthCheckMessage,u as healthCheck,d as insertEventByEventId,b as isSlotGapCheckEnabled,_ as loadWorkflowRunEvents,p as maxEventSlot,f as memoizeEncryptionKey,o as mergeReportedEvents,T as parseHealthCheckPayload,O as preconditionEventDelta,c as queueMessage,D as queueMessages,i as resolveRunEncryptionKey,e as rootRunIdFrom,E as runDispatchContext,a as settleEventSlotGap,n as slotSnapshotParams,t as stepDispatchIdempotencyKey,r as withHealthCheck,h as withReplayDelta};

package/dist/src/compiled/@workflow/core/runtime/lifecycle-hooks.d.ts

@@ -16,8 +16,7 @@ interface RunHookParams {
     run: Run<unknown>;
 }
 /** Parameters passed to an {@link WorkflowLifecycleHooks.onRunCompleted} handler. */
-export interface RunCompletedHookParams extends RunHookParams {
-}
+export type RunCompletedHookParams = RunHookParams;
 /**
  * Parameters passed to an {@link WorkflowLifecycleHooks.onRunFailed}
  * handler.
@@ -31,7 +30,9 @@ export interface RunFailedHookParams extends RunHookParams {
      *
      * This `WorkflowRunFailedError` has an `errorCode` carrying the failure
      * classification (e.g. `USER_ERROR`, `RUNTIME_ERROR`). Its `cause` is
-     * the hydrated persisted value (registered Error subclass identity preserved).
+     * the hydrated persisted value. Custom serialization revives registered
+     * classes using the runtime's module copy, which may differ from the
+     * handler's copy. Use error-class `.is()` helpers rather than `instanceof`.
      * If hydration fails, `cause` is a generic Error, matching
      * `run.returnValue`'s fallback.
      */
@@ -53,9 +54,12 @@ export interface WorkflowLifecycleHooks {
  * centralized reporting (e.g. forwarding failed runs to Sentry) without
  * wrapping every workflow body.
  *
- * Register early in the process lifecycle so handlers exist before the first
- * run finishes: in Next.js, `instrumentation.ts` is the natural place; in any
- * other app, any module that loads at startup works.
+ * Register in the host process that executes workflows, before it handles
+ * requests, never in a workflow or step. In Next.js 16.3+ use
+ * `instrumentation.ts`; restart `next dev` after editing handlers. App startup
+ * registration does not reach the separate flow functions emitted by the
+ * Vercel Build Output API integrations. See the lifecycle hooks guide for
+ * framework-specific support and registration locations.
  *
  * Semantics:
  * - Handlers run on the host (full Node.js), never inside the workflow VM.

package/dist/src/compiled/@workflow/core/runtime/out-of-band-observation.d.ts

@@ -0,0 +1,159 @@
+import type { QueueItem } from '../global.js';
+/**
+ * Whether any event an out-of-band writer could append right now is able to
+ * change the decisions a suspension leads to. Computed once per suspension
+ * that schedules inline steps, and exposed for the run-ahead gate described
+ * below. Nothing consumes it for control flow yet; the runtime records it on
+ * the invocation span so the eligible share of boundaries can be measured.
+ *
+ * ## Writers
+ *
+ * The orchestrator replaying the run is one writer. Every other writer is
+ * out-of-band to it:
+ *
+ * | Writer | Event | Path-changing when |
+ * |---|---|---|
+ * | webhook / `resumeHook()` | `hook_received` | workflow code is waiting on that hook's next payload |
+ * | another run's `createHook({ experimental_force })` | `hook_disposed` | same: it rejects waiting payload awaiters, and later awaits |
+ * | a step's `AbortController.abort()` | `hook_received` on a system hook | always: `signal.aborted` and abort listeners are read synchronously, with no `then` to observe |
+ * | wait timer | `wait_completed` | the wait is due (see below) |
+ * | `run.wakeUp()` / dashboard "cancel sleeps" | `wait_completed` | any time; not detected, see below |
+ * | step executors in other invocations | `step_completed` / `step_failed` / `step_retrying` | unknown: step promises are native, so their awaiters are invisible |
+ * | `runs.cancel()` | `run_cancelled` | never changes a decision; it ends the run (see "Pipeline depth") |
+ * | `setAttributes()` API | `attr_set` | never: workflow code writes attributes but cannot read them |
+ *
+ * ## Why an unawaited hook is inert
+ *
+ * On the node:vm engine a `hook_received` for a hook with no waiting consumer
+ * is hydrated and buffered as an UNARMED delivery barrier (`workflow/hook.ts`).
+ * Step results do not order behind unarmed barriers, the log-order-draws
+ * turnstile only waits on armed ones, and the workflow clock advances on
+ * delivery rather than consumption (`WorkflowOrchestratorContext.advanceClock`),
+ * so the buffered payload moves neither the step results around it nor
+ * `Date.now()`. A replay over a log with the payload inserted at any position
+ * after the hook's creation, and before its first await, makes the same
+ * decisions as one without it. The first `then()` on the hook is visible to the
+ * runtime because `Hook` is a custom thenable, which is what
+ * `WorkflowSuspension.observedHookIds` records.
+ *
+ * Over-reporting is possible and safe: a `.then` left behind by a settled
+ * `Promise.race` keeps its hook observed although the branch that would read
+ * it is gone.
+ *
+ * The QuickJS engine advances its clock on every event it reads, unclaimed
+ * payloads included, so this argument does not hold there. Its suspensions do
+ * not carry `observedHookIds`, which classifies every open hook as observed.
+ *
+ * ## Waits
+ *
+ * Sleep promises are native, so whether anything still awaits a wait cannot be
+ * told. A wait is instead classified by time: one whose `resumeAt` falls within
+ * the invocation's inline window plus the clock-skew allowance
+ * (`OPEN_WAIT_CLOCK_SKEW_MS`) can have its timer fire while this invocation is
+ * still deciding, and counts as path-changing; one due later cannot. The
+ * caller computes this from both the log and the suspension's own queue,
+ * because either can hold a wait the other lacks.
+ *
+ * `run.wakeUp()` completes waits regardless of `resumeAt`, so a far-future
+ * wait is only inert with respect to its own timer. Today that is a delayed
+ * wake at worst. Under run-ahead it is not (see below), so run-ahead has to
+ * close that gap before it relies on {@link OutOfBandObservation.inert} with
+ * any wait open, for example by treating every open wait as observed while a
+ * pipeline is in flight, or by having wake-ups enqueue a delivery instead of
+ * writing `wait_completed` directly.
+ *
+ * ## Intended use: de-opting run-ahead
+ *
+ * Run-ahead: once an inline step's body returns, feed its result to the
+ * retained VM and continue to the next boundary without waiting for the
+ * `step_completed` write (and the inline delta it carries) to come back, so
+ * consecutive steps overlap their writes. It requires a single-orchestrator
+ * guarantee whose stale holders are fenced (their writes refused, not merely
+ * their lease taken), which does not exist yet. Without it a second
+ * orchestrator is a writer this classification does not cover.
+ *
+ * Run-ahead removes the property today's replays rest on: a replay's view is a
+ * *prefix* of the log, and anything it missed lands after everything it read.
+ * A speculative view is the committed prefix plus this invocation's own
+ * in-flight writes, and an out-of-band event can commit *between* those writes.
+ * A later fresh replay sees it there. If the event was path-changing, that
+ * replay decides differently from the writes already committed after it,
+ * which is a corrupted log, not a late observation. {@link inert} is the
+ * condition under which such an interleaving cannot change any decision.
+ *
+ * The gate, once run-ahead exists:
+ *
+ * 1. Evaluate at every boundary, before issuing that boundary's writes.
+ *    Observation changes as code runs: the first `await hook` turns a hook
+ *    from inert to observed.
+ * 2. `inert === false`: do not run ahead past this boundary. Drain the
+ *    in-flight writes, fold their skipped-slot reports and deltas into the
+ *    log, and let the VM consume them in log order before deciding. That is
+ *    today's per-step cost, paid only at these boundaries.
+ * 3. `inert === true`: run ahead. Events the in-flight writes report back are
+ *    for entities nobody waits on; folding them buffers them, which changes no
+ *    decision already taken.
+ * 4. A boundary where code is waiting on a hook with nothing else to run needs
+ *    no drain to be safe: suspending without a payload only delays the run.
+ *    It still drains before parking, so a payload already committed below an
+ *    in-flight write is acted on now.
+ *
+ * ## Pipeline depth
+ *
+ * Run-ahead must cap how many steps it executes past the last write it has
+ * seen confirmed, independently of this classification:
+ *
+ * - Cancellation. `run_cancelled` never changes a decision, but every step
+ *   body started after it committed is a side effect the user asked not to
+ *   happen. The depth bounds that to the cap.
+ * - Lost invocations. Writes that never land (crash, timeout, lost lease) are
+ *   re-executed by whoever recovers the run, so every unconfirmed step is a
+ *   possible duplicate side effect.
+ * - Drain cost. Rule 2 above waits for every in-flight write; the cap bounds
+ *   how long a sync point can stall.
+ * - Exposure. The writers this classification cannot see (`run.wakeUp()`,
+ *   other step executors, a stale orchestrator) can only interleave inside the
+ *   in-flight window, which the cap keeps short.
+ *
+ * A small fixed depth (one or two unconfirmed steps) captures most of the
+ * latency win, since each extra step only saves one more round trip, and
+ * should be tunable per deployment like the other inline-loop knobs.
+ */
+export interface OutOfBandObservation {
+    /** Open user hooks with workflow code waiting on their next payload. */
+    observedHookCount: number;
+    /** Open user hooks nobody is waiting on: their payloads are inert. */
+    unobservedHookCount: number;
+    /**
+     * Open user hooks with unknown observation, because the suspension carried
+     * no `observedHookIds`. Counted as path-changing.
+     */
+    unknownHookCount: number;
+    /** Open `AbortController` system hooks: always path-changing. */
+    abortSignalHookCount: number;
+    /**
+     * Pending steps this invocation does not execute itself. Their terminal
+     * events come from another executor, and their awaiters cannot be seen, so
+     * any of them is counted as path-changing.
+     */
+    externalStepCount: number;
+    /** An open wait can fire before this invocation's inline window ends. */
+    waitDue: boolean;
+    /**
+     * No writer this classification can see is able to append an event that
+     * changes the decisions this suspension leads to. Excludes `run.wakeUp()`
+     * and a second orchestrator; see the module documentation.
+     */
+    inert: boolean;
+}
+export declare function observeOutOfBandWriters(input: {
+    /** The suspension's queue: every open hook, wait, and pending step. */
+    items: readonly QueueItem[];
+    /** `WorkflowSuspension.observedHookIds`. */
+    observedHookIds: ReadonlySet<string> | undefined;
+    /** Steps this invocation executes itself (inline or as owner recovery). */
+    selfExecutedStepIds: ReadonlySet<string>;
+    /** Whether an open wait is due within the invocation's inline window. */
+    waitDue: boolean;
+}): OutOfBandObservation;
+//# sourceMappingURL=out-of-band-observation.d.ts.map

package/dist/src/compiled/@workflow/core/runtime/vm-mode.d.ts

@@ -41,6 +41,14 @@ export declare function getWorkflowVmFromEnv(env?: NodeJS.ProcessEnv): WorkflowV
  * unknown value.
  */
 export declare function useQuickJSVm(workflowRun: Pick<WorkflowRun, 'executionContext'>): boolean;
+/**
+ * Snapshot threshold the QuickJS engine uses when neither the run's
+ * `executionContext` nor `WORKFLOW_SNAPSHOT_THRESHOLD` specifies one.
+ * Short runs (most workflows) never reach it and so never pay the
+ * snapshot cost; long-running runs stop scaling their resume cost with
+ * total event-log length. Set `WORKFLOW_SNAPSHOT_THRESHOLD=0` to opt out.
+ */
+export declare const DEFAULT_QUICKJS_SNAPSHOT_THRESHOLD = 1000;
 /**
  * Read and validate the `WORKFLOW_SNAPSHOT_THRESHOLD` env var.
  *
@@ -49,9 +57,9 @@ export declare function useQuickJSVm(workflowRun: Pick<WorkflowRun, 'executionCo
  * invocations restore the VM and replay only the events recorded since —
  * instead of re-executing the workflow from the top against the full log.
  *
- * `0` (or unset) disables snapshotting entirely: short-lived runs never
- * pay the snapshot cost, while long/forever runs can opt in. `1`
- * effectively snapshots at every suspension.
+ * When unset, the QuickJS engine uses
+ * {@link DEFAULT_QUICKJS_SNAPSHOT_THRESHOLD}. `0` explicitly disables
+ * snapshotting. `1` effectively snapshots at every suspension.
  *
  * Returns the configured threshold, or `undefined` if unset/empty.
  * Throws {@link WorkflowRuntimeError} for non-integer or negative values.
@@ -62,12 +70,28 @@ export declare function getSnapshotThresholdFromEnv(env?: NodeJS.ProcessEnv): nu
  * `executionContext.snapshotThreshold` (set by the SDK at `start()` when
  * `WORKFLOW_SNAPSHOT_THRESHOLD` is set on the client) wins so a run keeps
  * the policy it started with; otherwise the handler's env var; otherwise
- * `0` (disabled). Only consulted by the QuickJS engine.
+ * {@link DEFAULT_QUICKJS_SNAPSHOT_THRESHOLD}. Only consulted by the QuickJS
+ * engine.
  *
  * Throws on an invalid value. The workflow handler uses
  * {@link getSnapshotThresholdForHandler}, which doesn't.
  */
 export declare function getSnapshotThreshold(workflowRun: WorkflowRun): number;
+/**
+ * The snapshot threshold explicitly configured for a run (stamped into its
+ * `executionContext` or set via `WORKFLOW_SNAPSHOT_THRESHOLD` on the
+ * handler), or `undefined` when the run falls back to
+ * {@link DEFAULT_QUICKJS_SNAPSHOT_THRESHOLD}.
+ *
+ * Throws on an invalid value.
+ */
+export declare function getConfiguredSnapshotThreshold(workflowRun: WorkflowRun): number | undefined;
+/**
+ * Whether the run's snapshot threshold was explicitly configured rather
+ * than falling back to {@link DEFAULT_QUICKJS_SNAPSHOT_THRESHOLD}. Never
+ * throws: an invalid value counts as configured.
+ */
+export declare function isSnapshotThresholdConfigured(workflowRun: WorkflowRun): boolean;
 /**
  * {@link getSnapshotThreshold} for the workflow handler: an invalid value
  * disables snapshotting (with a warning through `onInvalid`) instead of