eve 0.75.0 → 0.75.1

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