eve 0.70.0 → 0.70.2

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

@@ -29,7 +29,7 @@
  * `node:vm` engine's replay determinism.
  */
 import { SerializationError } from '#compiled/@workflow/errors/index.js';
-import { type Event, type RunInput, type WorkflowRun, type WorldCapabilities } from '#compiled/@workflow/world/index.js';
+import { type Event, type RunInput, type SnapshotMetadata, type WorkflowRun, type WorldCapabilities } from '#compiled/@workflow/world/index.js';
 import { type AttributeChange } from '#compiled/@workflow/world/index.js';
 import { type Snapshot } from '../_quickjs-wasi.js';
 import type { DecryptionKey } from '../serialization/encryption.js';
@@ -165,10 +165,26 @@ export interface QuickJSRuntimeOptions {
     /** Features supported by the World executing this workflow. */
     worldCapabilities?: WorldCapabilities;
     /**
-     * The full event log for the run. Every invocation replays the complete
-     * log from the start (same replay semantics as the `node:vm` engine).
+     * The event log to process. Without a snapshot this is the FULL log and
+     * every invocation replays it from the start (same replay semantics as
+     * the `node:vm` engine). With `existingSnapshot`, this is the delta of
+     * events recorded at/after the snapshot's `eventsCursor` — feeding
+     * already-consumed events is harmless (consumed resolvers are gone and
+     * hook deliveries are deduped in the VM heap), so an imprecise cursor
+     * only costs redundant scanning.
      */
     events: Event[];
+    /**
+     * A previously persisted VM-memory snapshot to restore from, or
+     * null/undefined for a fresh boot + full replay. Restoring skips VM
+     * bootstrap, bundle evaluation, and pre-snapshot re-execution entirely:
+     * the WASM heap resumes at the exact suspension point it was captured
+     * at, and only `events` are processed on top.
+     */
+    existingSnapshot?: {
+        data: Uint8Array;
+        metadata: SnapshotMetadata;
+    } | null;
     /** Encryption key for decrypting event payloads (undefined if unencrypted) */
     encryptionKey?: DecryptionKey;
     /**
@@ -216,6 +232,18 @@ type BaselineEntry = {
 export declare function __clearBaselineSnapshotCacheForTests(): void;
 /** Test-only: observe how a bundle was classified. */
 export declare function __peekBaselineEntryForTests(workflowCode: string): Promise<BaselineEntry | undefined>;
+/**
+ * Continue a monotonic ULID sequence from a persisted last value:
+ * re-implements the `ulid` package's same-timestamp step (Crockford
+ * base32 +1 on the 16-char random part, carrying left; the 10-char time
+ * prefix is preserved — the run's seed timestamp is constant, so the
+ * package would never re-encode it). Byte-for-byte equivalent to what
+ * `monotonicFactory` returns for the same draw position, which is what
+ * keeps correlation ids identical between a snapshot-restored invocation
+ * and a full replay. Exported for tests (equivalence is asserted against
+ * the package itself).
+ */
+export declare function incrementUlidRandom(prev: string): string;
 /**
  * A live QuickJS workflow invocation. When the initial `result` is
  * `suspended`, the VM is kept alive so the caller can feed newly recorded
@@ -233,6 +261,30 @@ export interface QuickJSWorkflowSession {
      * Resets the VM's interrupt budget for the new execution burst.
      */
     continueWithEvents(newEvents: Event[]): Promise<QuickJSRuntimeResult>;
+    /**
+     * Capture and serialize the live VM's memory. Only valid while the
+     * last result was `suspended`. The returned bytes restore via
+     * `existingSnapshot` on a later invocation (pair them with the events
+     * cursor at capture time). `rngDraws` is the seeded PRNG's draw count
+     * at capture — persisted in the snapshot metadata so a restore
+     * fast-forwards the base seed to the same position. `lastUlid` is the
+     * monotonic correlation-id factory's last output (undefined if the
+     * run has drawn none) — persisted so a restore continues the exact
+     * ULID sequence instead of drawing fresh randomness. `serdeRootPtr`
+     * is the host-serde capture root's snapshot-portable token — the
+     * restore path re-adopts it so serde initialization executes no guest
+     * code after user code has run.
+     */
+    snapshot(): {
+        data: Uint8Array;
+        rngDraws: number;
+        lastUlid: string | undefined;
+        serdeRootPtr: number;
+        /** Deterministic clock high-water mark at capture (ms since epoch). */
+        clockMs: number;
+        /** Exact engine build (quickjs-wasi version) that captured the heap. */
+        engineVersion: string;
+    };
     /** Dispose the VM if it is still alive. Safe to call multiple times. */
     dispose(): void;
 }

package/dist/src/compiled/@workflow/core/runtime/quickjs-snapshot-codec.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Encoding of the per-run VM snapshots the QuickJS engine persists through
+ * `world.experimental_snapshots` (compress, then encrypt on save; the inverse
+ * on load), and the checks a stored snapshot must pass before its heap is
+ * handed to the engine.
+ *
+ * A snapshot is executable state: bytecode, closures and pending
+ * continuations that run with access to every host callback. So a load
+ * treats storage as untrusted input:
+ *
+ * - The restore-relevant metadata is sealed INSIDE the encrypted payload,
+ *   bound to the run id, and must equal the metadata the World returned.
+ *   With an encryption key that makes the pairing authenticated: bytes from
+ *   one snapshot can't be combined with another's metadata (a wrong cursor
+ *   silently replays from the wrong log position), and nothing
+ *   restore-relevant can be edited in the plaintext envelope. Without a key
+ *   the same check still catches torn or mismatched writes.
+ * - A run that has an encryption key only accepts encrypted snapshots, so a
+ *   plaintext blob written to storage can't bypass encryption.
+ * - Decompression is capped, so a small compressed blob can't inflate
+ *   without bound.
+ * - Numeric fields that drive host-side work before the VM exists (the PRNG
+ *   fast-forward runs `rngDraws` synchronous draws) are bounded.
+ */
+import type { SnapshotMetadata } from '#compiled/@workflow/world/index.js';
+import { type RunPayloadKeys } from '../serialization/encryption.js';
+/**
+ * Plaintext size ceiling for persisted VM snapshots. A heap beyond this
+ * costs more to store, encrypt and decompress than the replay it saves.
+ * Captures over it are not saved, and loads refuse to inflate past it.
+ */
+export declare const MAX_SNAPSHOT_PLAINTEXT_BYTES: number;
+/**
+ * Upper bound on `rngDraws` accepted from a stored snapshot. The restore
+ * fast-forwards the run's PRNG that many draws synchronously before the VM
+ * exists (about 70 ns per draw), so an unbounded value is a hang. A run that
+ * legitimately drew more than this restores by full replay instead.
+ */
+export declare const MAX_SNAPSHOT_RNG_DRAWS = 10000000;
+/** Why a stored snapshot was not restored. */
+export type SnapshotRejectReason = 'unencrypted' | 'undecryptable' | 'too_large' | 'malformed' | 'metadata_mismatch' | 'out_of_bounds';
+export declare class SnapshotRejectedError extends Error {
+    readonly reason: SnapshotRejectReason;
+    constructor(reason: SnapshotRejectReason, message: string);
+}
+/**
+ * Bounds on metadata values the runtime acts on before it can validate the
+ * heap itself. Checked on the World-supplied metadata before any decrypt or
+ * decompress work, so an out-of-range value costs nothing.
+ */
+export declare function checkSnapshotMetadataBounds(metadata: SnapshotMetadata): string | undefined;
+/**
+ * Encode a captured heap for storage: frame it with its sealed metadata,
+ * compress, then encrypt (ciphertext doesn't compress, so compression comes
+ * first). Returns the bytes to hand to `experimental_snapshots.save`.
+ */
+export declare function sealSnapshot(params: {
+    runId: string;
+    heap: Uint8Array;
+    metadata: SnapshotMetadata;
+    encryptionKey: RunPayloadKeys | undefined;
+}): Promise<Uint8Array>;
+/**
+ * Decode stored snapshot bytes back to the heap image, enforcing every
+ * check in the module doc. Throws {@link SnapshotRejectedError}; the caller
+ * treats that as a miss and falls back to full replay.
+ */
+export declare function openSnapshot(params: {
+    runId: string;
+    stored: Uint8Array;
+    metadata: SnapshotMetadata;
+    encryptionKey: RunPayloadKeys | undefined;
+}): Promise<Uint8Array>;
+//# sourceMappingURL=quickjs-snapshot-codec.d.ts.map

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

@@ -1,4 +1,5 @@
 import type { RunRetention, World } from '#compiled/@workflow/world/index.js';
+import { type DynamicStartOptions } from './dynamic-workflow.js';
 import { type HealthCheckResult } from './helpers.js';
 import { Run } from './run.js';
 /**
@@ -191,6 +192,7 @@ export interface StartOptionsWithoutDeploymentId extends StartOptionsBase {
  * Options for starting a workflow run.
  */
 export type StartOptions = StartOptionsWithDeploymentId | StartOptionsWithoutDeploymentId;
+export type { DynamicStartOptions, DynamicWorkflowOptions, DynamicWorkflowStepReference, } from './dynamic-workflow.js';
 /**
  * Represents an imported workflow function.
  */
@@ -213,4 +215,6 @@ export declare function start<TArgs extends unknown[], TResult>(workflow: Workfl
 export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options: StartOptionsWithDeploymentId): Promise<Run<unknown>>;
 export declare function start<TArgs extends unknown[], TResult>(workflow: WorkflowFunction<TArgs, TResult> | WorkflowMetadata, args: TArgs, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
 export declare function start<TResult>(workflow: WorkflowFunction<[], TResult> | WorkflowMetadata, options?: StartOptionsWithoutDeploymentId): Promise<Run<TResult>>;
+export declare function start(source: string, args: unknown[], options: DynamicStartOptions): Promise<Run<unknown>>;
+export declare function start(source: string, options: DynamicStartOptions): Promise<Run<unknown>>;
 //# sourceMappingURL=start.d.ts.map

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

@@ -41,4 +41,48 @@ export declare function getWorkflowVmFromEnv(env?: NodeJS.ProcessEnv): WorkflowV
  * unknown value.
  */
 export declare function useQuickJSVm(workflowRun: Pick<WorkflowRun, 'executionContext'>): boolean;
+/**
+ * Read and validate the `WORKFLOW_SNAPSHOT_THRESHOLD` env var.
+ *
+ * The threshold is the number of processed events after which the QuickJS
+ * engine persists a VM-memory snapshot at suspension, so subsequent
+ * 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.
+ *
+ * Returns the configured threshold, or `undefined` if unset/empty.
+ * Throws {@link WorkflowRuntimeError} for non-integer or negative values.
+ */
+export declare function getSnapshotThresholdFromEnv(env?: NodeJS.ProcessEnv): number | undefined;
+/**
+ * Resolve the snapshot threshold for a run: the run's stamped
+ * `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.
+ *
+ * Throws on an invalid value. The workflow handler uses
+ * {@link getSnapshotThresholdForHandler}, which doesn't.
+ */
+export declare function getSnapshotThreshold(workflowRun: WorkflowRun): number;
+/**
+ * {@link getSnapshotThreshold} for the workflow handler: an invalid value
+ * disables snapshotting (with a warning through `onInvalid`) instead of
+ * throwing. Snapshotting is an optimization, and a throw here would fail
+ * every invocation of every QuickJS run on the deployment into a retry
+ * loop over a config typo. `start()` still rejects an invalid client-side
+ * value up front.
+ */
+export declare function getSnapshotThresholdForHandler(workflowRun: WorkflowRun, onInvalid: (message: string) => void): number;
+/**
+ * Whether `WORKFLOW_SNAPSHOT_ALLOW_UNENCRYPTED` opts the handler into
+ * persisting VM snapshots for runs without an encryption key. A snapshot is
+ * executable VM state that also holds the run's in-memory data, so by
+ * default the runtime only snapshots runs whose World supplies an
+ * encryption key (which also authenticates the snapshot on restore).
+ */
+export declare function isUnencryptedSnapshottingAllowed(env?: NodeJS.ProcessEnv): boolean;
 //# sourceMappingURL=vm-mode.d.ts.map

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

@@ -5,7 +5,7 @@ export { type HealthCheckOptions, type HealthCheckResult, healthCheck, } from '.
 export { getHookByToken, type Hook, type ResumedHook, resumeHook, resumeWebhook, } from './runtime/resume-hook.js';
 export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, type WorkflowRunWritableStreamOptions, } from './runtime/run.js';
 export { type CancelRunOptions, cancelRun, cancelRuns, listStreams, type ReadStreamOptions, type RecreateRunOptions, type ReenqueueRunOptions, readStream, recreateRunFromExisting, reenqueueRun, type StopSleepOptions, type StopSleepResult, wakeUpRun, } from './runtime/runs.js';
-export { type StartOptions, type StartOptionsBase, type StartOptionsWithDeploymentId, type StartOptionsWithoutDeploymentId, start, } from './runtime/start.js';
+export { type DynamicStartOptions, type DynamicWorkflowOptions, type DynamicWorkflowStepReference, type StartOptions, type StartOptionsBase, type StartOptionsWithDeploymentId, type StartOptionsWithoutDeploymentId, start, } from './runtime/start.js';
 export { createWorld, createWorldFromModule, getWorld, getWorldHandlers, setWorld, type WorldFactoryModule, } from './runtime/world.js';
 /**
  * Creates a single route which handles workflow execution requests,