eve 0.38.1 → 0.38.2

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

@@ -38,15 +38,14 @@ export declare function isFirstInvocation(preloadedEvents: readonly Event[] | un
  * This replaces the `node:vm` replay path (runWorkflow + EventsConsumer)
  * with a QuickJS VM invocation that performs the same full event replay.
  *
- * KNOWN GAP — precondition guard: unlike the node:vm path, no event write
- * in this file participates in the optimistic-concurrency precondition
- * guard (`withPreconditionRetry` + `stateUpdatedAtForCreate`), which
- * protects a writer holding a stale event-log snapshot from clobbering a
- * concurrent one. The engine currently relies on per-(runId,
- * correlationId) event uniqueness (EntityConflictError dedup) alone. This
- * is a deliberate simplification while the engine is experimental — wiring
- * the guard is tracked follow-up work; anyone adding new write paths here
- * should not assume parity with the node engine on this axis.
+ * KNOWN GAP — slot snapshot: unlike the node:vm path, no event write in
+ * this file carries {@link CreateEventParams.eventCount}, so a World never
+ * learns which events the writer had not seen and never reports them back.
+ * The engine currently relies on per-(runId, correlationId) event
+ * uniqueness (EntityConflictError dedup) alone. This is a deliberate
+ * simplification while the engine is experimental — wiring the snapshot is
+ * tracked follow-up work; anyone adding new write paths here should not
+ * assume parity with the node engine on this axis.
  */
 export declare function runWorkflowWithQuickJS(params: {
     workflowCode: string;

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

@@ -1,3 +1,4 @@
+import { type SlotSnapshotParams } from './helpers.js';
 /**
  * Per-invocation accounting of the *non-step* portion of a workflow
  * handler run: deterministic event-log replay, workflow-VM execution
@@ -85,5 +86,12 @@ export declare function handleReplayBudgetExhausted(args: {
     requestId: string | undefined;
     attempt: number;
     limitMs: number;
+    /**
+     * How much of the log the replay that ran out of budget had loaded. Carried
+     * onto the terminal write for the same reason every other write from that
+     * replay carries it: the run is being failed on a view of the log, and the
+     * World should be told which view.
+     */
+    slotSnapshot?: SlotSnapshotParams;
 }): Promise<void>;
 //# sourceMappingURL=replay-budget.d.ts.map

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

@@ -0,0 +1,143 @@
+import type { HookResumeTiming } from '#compiled/@workflow/world/index.js';
+/**
+ * Hook-triggered time-to-resume (TTR): wall-clock from entry into
+ * `resumeHook()` (T0) to the first line of the next durable step (T7), plus a
+ * decomposition into non-overlapping phases that sum exactly to it.
+ *
+ * ```text
+ * T0 resumeHook() entered
+ *      producer_prep   — hook lookup, serialization, encryption
+ * T1 queue publish requested
+ *      queue_delivery  — network + VQS delivery (incl. any affinity re-route)
+ * T2 final consumer's queue handler entered
+ *      resume_setup    — affinity check, hook_received re-ensure, replay preload
+ * T3 replay begins
+ *      replay          — VM/session creation and workflow replay
+ * T4 next durable step encountered
+ *      step_dispatch   — suspension handling, inline batch or queue dispatch
+ * T5 step_started request begins
+ *      step_claim      — the claim round trip
+ * T6 step_started response returned
+ *      step_prepare    — key resolution, argument hydration, context setup
+ * T7 immediately before stepFn.apply()
+ * ```
+ *
+ * The producer's direct `hook_received` POST races the queue publish on the
+ * parallel fast path, so it deliberately has no phase of its own — the two
+ * overlap, and representing both as additive phases would double-count. It
+ * remains visible as a contextual span (`hook.resume`).
+ *
+ * T0/T1 are stamped on the producer's machine and T2..T7 on the consumer's, so
+ * the measurement is subject to cross-machine clock skew. Rather than clamp
+ * (which would break the sum-equals-total property this decomposition exists
+ * for), a non-monotonic boundary set drops the whole sample — see
+ * {@link computeResumeTtrAttributes}.
+ */
+/** What caused the resumption being measured. Only hooks are measured today. */
+export type ResumeTrigger = 'hook';
+/** Which `resumeHook()` dispatch path produced this resume. */
+export type ResumeStrategy = 'parallel' | 'sequential';
+/**
+ * How the consuming invocation initialized its replay state:
+ *
+ * - `hook_preload` — the hoisted `hook_received` write returned a usable
+ *   replay preload, so neither `run_started` nor the initial `events.list` ran.
+ * - `run_started` — the generic `run_started` setup ran (including the fast
+ *   path's fallback, where the hoisted write succeeded but returned no usable
+ *   preload).
+ * - `event_load` — neither setup ran because the run arrived already loaded,
+ *   so setup was a plain event load. No current path produces it (the one
+ *   preloaded-run path, the background-step fall-through, consumes the
+ *   tracking on its own step first); it is the honest default rather than a
+ *   live value, and keeps the dimension total if such a path is added.
+ */
+export type ResumeSetupSource = 'hook_preload' | 'run_started' | 'event_load';
+/** Whether the measured step ran in the resuming invocation or a queued one. */
+export type ResumeStepExecution = 'inline' | 'dispatched';
+/**
+ * The resume boundaries observed so far, threaded from the queue handler into
+ * `executeStep`. Producer fields arrive on the queue message
+ * ({@link HookResumeTiming}); consumer fields are stamped by the invocation
+ * that replays the resume.
+ *
+ * The runtime holds at most one of these per invocation and CONSUMES it when
+ * it hands it to the execution that will attempt the next durable step, so a
+ * later step in the same invocation — or a retry of the same step — never
+ * re-reports the same resumption. Within one inline batch the object is
+ * shared by every step and the {@link ResumeTtrTracking.reported} latch picks
+ * the single reporter.
+ */
+export interface ResumeTtrTracking {
+    trigger: ResumeTrigger;
+    /** Absent only if an older producer omitted it from the queue message. */
+    strategy?: ResumeStrategy;
+    /** T0 — entry into `resumeHook()`. */
+    resumeRequestedAtMs: number;
+    /** T1 — immediately before the queue publish was requested. */
+    queuePublishRequestedAtMs: number;
+    /**
+     * T2 — entry into the FINAL consumer's queue handler. A delivery that
+     * re-routes for deployment affinity never stamps this, so the re-routed hop
+     * stays inside `queue_delivery` where it belongs.
+     */
+    consumerStartedAtMs: number;
+    /** T3 — this invocation's first replay pass. */
+    replayStartedAtMs?: number;
+    /** T4 — replay first encountered a durable step after the resume. */
+    nextStepEncounteredAtMs?: number;
+    setupSource?: ResumeSetupSource;
+    stepExecution: ResumeStepExecution;
+    /**
+     * One-shot latch, set by the step executor once this resumption has been
+     * reported. Every step of an inline batch is handed the SAME tracking
+     * object, so the first one to reach user code takes the measurement and the
+     * rest see this and skip — one resumption, one sample, without pinning the
+     * sample to a step that may lose its create-claim and never run.
+     *
+     * Deliberately not part of {@link HookResumeTiming}: it is invocation-local
+     * state, and a queue message carries the boundaries, not the claim.
+     */
+    reported?: boolean;
+}
+/**
+ * Rebuild tracking from a queue message's timing object. Returns undefined for
+ * a message that carries none (an older producer, or any non-hook delivery) —
+ * the caller then simply reports no TTR.
+ */
+export declare function resumeTrackingFromMessage(timing: HookResumeTiming | undefined, stepExecution: ResumeStepExecution): ResumeTtrTracking | undefined;
+/**
+ * Serialize tracking back onto a queue message, for the case where the
+ * resuming invocation dispatches the next durable step to another invocation
+ * instead of running it inline. Returns undefined when the tracking is not
+ * complete enough to be worth forwarding.
+ */
+export declare function resumeTimingForMessage(tracking: ResumeTtrTracking | undefined): HookResumeTiming | undefined;
+/**
+ * Compute the TTR span attributes for a step that is the first durable step
+ * following a hook resume. Returns undefined — emitting nothing at all — when
+ * any of these hold:
+ *
+ * - the invocation carries no resume tracking (not a hook resume, or an older
+ *   queue message with no timing);
+ * - this is a retry (`attempt !== 1`), which measures a re-execution rather
+ *   than the resumption;
+ * - a required boundary is missing, non-finite, or out of order.
+ *
+ * `step_claim_ms` is the one phase that may be individually omitted. Under
+ * optimistic inline start the `step_started` claim is deliberately NOT awaited
+ * before the body runs, so its completion instant does not exist yet at T7;
+ * rather than invent one, the claim phase is dropped and `step_prepare_ms`
+ * spans T5→T7. The sum-equals-total property holds either way.
+ */
+export declare function computeResumeTtrAttributes(params: {
+    tracking: ResumeTtrTracking | undefined;
+    /** The attempt number of the execution about to run. */
+    attempt: number;
+    /** T5 — `Date.now()` immediately before the `step_started` request. */
+    stepClaimStartedAtMs: number | undefined;
+    /** T6 — `Date.now()` once the `step_started` response returned. */
+    stepClaimCompletedAtMs: number | undefined;
+    /** T7 — `Date.now()` immediately before `stepFn.apply()`. */
+    stepCodeStartedAtMs: number;
+}): Record<string, string | number> | undefined;
+//# sourceMappingURL=resume-latency.d.ts.map

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

@@ -1,7 +1,8 @@
 import type { Event, SerializedData, World } from '#compiled/@workflow/world/index.js';
 import type { PayloadKey } from '../serialization/encryption.js';
-import { type PreconditionSnapshotParams } from './helpers.js';
+import { type SlotSnapshotParams } from './helpers.js';
 import { ReplayRecoveryReporter } from './replay-recovery-reporter.js';
+import { type ResumeTtrTracking } from './resume-latency.js';
 import { type StepLatencyTracking } from './step-latency.js';
 export declare const DEFAULT_STEP_MAX_RETRIES = 3;
 export interface StepExecutorParams {
@@ -59,20 +60,25 @@ export interface StepExecutorParams {
      */
     inlineDeltaSinceCursor?: string;
     /**
-     * Precondition-guard snapshot of the event log 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 event it never loaded. A
-     * guard-enforcing World rejects a stale claim with `PreconditionFailedError`
+     * How much of the run's log the caller's replay had loaded when it scheduled
+     * this step, as the highest slot that log occupies. Seeds the snapshot every
+     * write this executor makes carries; each committed event advances it to its
+     * own slot, so a later write never names a position that predates an earlier
+     * one from the same step.
+     *
+     * It matters most on the lazy inline path, where the `step_started` claim is
+     * the step's FIRST durable write (its `step_created` is deferred): without a
+     * seed the claim would name no position at all, and a replay working from a
+     * stale view could claim — and then commit — a step scheduled without
+     * observing an event it never loaded.
+     *
+     * A World that fences 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 restart its replay. Undefined when the guard is
-     * disabled or the caller has no snapshot; Worlds that don't enforce the guard
-     * ignore it.
+     * abandon the batch and restart its replay. Undefined for a caller with
+     * nothing loaded.
      */
-    preconditionSnapshot?: PreconditionSnapshotParams;
+    slotSnapshot?: SlotSnapshotParams;
     /**
      * Suppress optimistic inline start for this step regardless of
      * `WORKFLOW_OPTIMISTIC_INLINE_START` / `forceOptimisticStart`: take the
@@ -111,6 +117,15 @@ export interface StepExecutorParams {
      * runtime/step-latency.ts.
      */
     latencyTracking?: StepLatencyTracking;
+    /**
+     * Hook-resume TTR telemetry: the boundaries of a hook resumption whose next
+     * durable step is the one this call is about to execute. When set, the
+     * executor closes the measurement against the `step_started` claim and the
+     * wall clock taken immediately before user code, and attaches the total plus
+     * its phase breakdown to this step's `step.execute` span. Set by the runtime
+     * for exactly one step per resumption — see runtime/resume-latency.ts.
+     */
+    resumeTracking?: ResumeTtrTracking;
     /**
      * Authoritative attempt number for this execution, used to bound retries
      * against `maxRetries` BEFORE the body runs. In order to also catch

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 SerializedData, type WorkflowRun, type World } from '#compiled/@workflow/world/index.js';
+import { type SerializedData, type TraceCarrier, type ValidQueueName, type WorkflowRun, type World } from '#compiled/@workflow/world/index.js';
 import type { StepInvocationQueueItem, WorkflowSuspension } from '../global.js';
 import { type LoadedEventLog } from './helpers.js';
 import { ReplayRecoveryReporter } from './replay-recovery-reporter.js';
@@ -11,12 +11,13 @@ export interface SuspensionHandlerParams {
     requestId?: string;
     /**
      * The runtime's loaded event log. Every event creation this suspension makes
-     * is sent with the precondition snapshot derived from it, so a backend that
-     * has recorded an event the replay did not see rejects the write with a 412
-     * instead of accepting a divergent event. The rejection is not retried here:
-     * the event's correlation id was minted by *this* replay's seeded sequence,
-     * so re-committing it against a corrected log would persist an event no
-     * correct replay produces. The caller restarts the replay instead.
+     * names the position it was derived from, so a backend that has recorded
+     * events the replay did not see can report them back on the write — or, if
+     * it would rather refuse than report, reject it with a 412. A rejection is
+     * not retried here: the event's correlation id was minted by *this* replay's
+     * seeded sequence, so re-committing it against a corrected log would persist
+     * an event no correct replay produces. The caller restarts the replay
+     * instead.
      */
     eventLog?: LoadedEventLog;
     /**
@@ -31,6 +32,26 @@ export interface SuspensionHandlerParams {
     runReadyBarrier?: Promise<unknown>;
     /** One-shot telemetry reporter, activated only after replay has recovered. */
     replayRecoveryReporter?: ReplayRecoveryReporter;
+    /**
+     * Resilient step dispatch: when provided (and the per-step eligibility gates
+     * pass — see the step ops below), each newly created non-inline step's
+     * `step_created` write is parallelized with its step-execution queue
+     * publish, and the queue message carries the serialized step input
+     * (`stepInput`) so the consumer can idempotently re-ensure the event if the
+     * direct write failed transiently. Steps queued this way are reported in
+     * {@link SuspensionHandlerResult.queuedStepCorrelationIds} so the caller
+     * skips them in its own dispatch pass. Omitted by callers that must not
+     * queue (terminal drain, tests) — creates then behave exactly as before.
+     */
+    stepDispatch?: {
+        /** The unified workflow queue this run's step messages are published to. */
+        queueName: ValidQueueName;
+        /**
+         * Lazily resolves the trace carrier to stamp on the step messages.
+         * Called at most once per suspension (memoized here).
+         */
+        getTraceCarrier: () => Promise<TraceCarrier>;
+    };
 }
 /**
  * Result of handling a suspension. Returns pending step items so the caller
@@ -48,6 +69,16 @@ export interface SuspensionHandlerResult {
      * into the same batch boundary.
      */
     createdStepCorrelationIds: Set<string>;
+    /**
+     * Correlation IDs of steps this suspension call already published
+     * step-execution queue messages for, via resilient step dispatch (the
+     * `step_created` write parallelized with a `stepInput`-carrying queue
+     * publish). The caller MUST NOT dispatch these again — the message is
+     * already out (a duplicate would be deduped by its idempotency key, but
+     * costs a wasted round-trip). Empty when {@link SuspensionHandlerParams.stepDispatch}
+     * was not provided or no step was eligible.
+     */
+    queuedStepCorrelationIds: Set<string>;
     /**
      * How many events this phase's writes reported back as occupying slots they
      * skipped over, already merged into the caller's `eventLog.events`. Nonzero
@@ -122,5 +153,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, eventLog, runReadyBarrier, replayRecoveryReporter, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
+export declare function handleSuspension({ suspension, world, run, span, requestId, eventLog, runReadyBarrier, replayRecoveryReporter, stepDispatch, }: SuspensionHandlerParams): Promise<SuspensionHandlerResult>;
 //# sourceMappingURL=suspension-handler.d.ts.map

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

@@ -9,11 +9,12 @@ type WorldSpecVersionMetadata = Pick<World, 'specVersion'>;
  * ceiling means a World built against a newer spec than this runtime knows how
  * to read.
  *
- * The range has a floor and a ceiling rather than a single value because a
- * World may opt into a spec version above the default: `world-vercel` declares
- * the slot-identity version so its new runs are created with slot event ids,
- * while every other World stays on the default. An equality check would make
- * this runtime refuse the adapter shipped alongside it.
+ * Both bounds are the same version today, so this currently admits exactly one.
+ * It stays written as a range because the two constants answer different
+ * questions and come apart while a spec bump is staged: the ceiling rises when
+ * this runtime learns to read the next version, the floor when that version
+ * becomes the one Worlds stamp. An equality check against either constant alone
+ * would reject a World during that window.
  */
 export declare function assertWorldSupportsRuntimeProtocol(world: WorldSpecVersionMetadata): void;
 export {};