eve 0.22.4 → 0.22.5

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

@@ -0,0 +1,131 @@
+import type { Event } from '#compiled/@workflow/world/index.js';
+/**
+ * Client-side latency measurement (TTFS / STSO) threaded from the
+ * orchestrator's inline execution path into `executeStep`.
+ *
+ * TTFS (time-to-first-step) measures run creation → the first step's body
+ * beginning to execute. STSO (step-to-step overhead) measures the previous
+ * step's terminal event → the next step's body beginning to execute. Both are
+ * attached to the step's terminal event so a backend can emit latency metrics
+ * from the event write alone, without extra event-log queries.
+ *
+ * Eligibility is decided by the orchestrator (which owns the event log) via
+ * {@link computeStepLatencyTracking}; the final values are computed by
+ * `executeStep` right before user code runs via
+ * {@link computeStepLatencyEventData}.
+ */
+export interface StepLatencyTracking {
+    /**
+     * Epoch ms of run creation (from the run-id ULID, falling back to the run
+     * snapshot's `createdAt`). Present only when the step qualifies for TTFS.
+     */
+    ttfsAnchorMs?: number;
+    /**
+     * Wall-clock ms this invocation spent committing `hook_created` events
+     * before the first step (fire-and-forget `createHook()` ahead of the first
+     * step commits in the same suspension batch). Subtracted from TTFS so the
+     * metric reflects runtime overhead rather than the user's hook writes.
+     */
+    preStepBlockingMs?: number;
+    /**
+     * Epoch ms the first pre-step `attr_set` write began (its client-stamped
+     * `occurredAt`, falling back to `createdAt`). When present, the TTFS
+     * measurement ENDS here instead of at the step's code start: a
+     * workflow-body `experimental_setAttributes` before the first step
+     * resolves through an extra replay (see the `hasAttributeEvents` branch in
+     * runtime.ts), so everything from this write until the step body runs is
+     * the duration of the setAttributes call — which is subtracted by ending
+     * the measurement at the point where the step would otherwise have been
+     * scheduled.
+     */
+    preStepAttrStartMs?: number;
+    /**
+     * Epoch ms the previous step's terminal event was recorded (its
+     * client-stamped `occurredAt`, falling back to `createdAt`). Present only
+     * when the step qualifies for STSO.
+     */
+    prevStepEndMs?: number;
+    /** Number of unique terminal steps already in the event log. */
+    stepCount?: number;
+    /** Number of events already in the event log. */
+    eventCount?: number;
+    /** Whether turbo mode is active for this invocation. */
+    turbo: boolean;
+}
+/** Latency telemetry attached to a step's terminal event's `eventData`. */
+export interface StepLatencyEventData {
+    ttfs?: number;
+    stso?: number;
+    stepCount?: number;
+    eventCount?: number;
+    optimizations?: string[];
+}
+/**
+ * Decide, from the orchestrator's view of the event log, whether the inline
+ * step batch about to execute qualifies for TTFS and/or STSO measurement.
+ * Returns undefined when neither applies. Called once per batch; the result
+ * is passed to the batch's first step only, so a parallel first batch emits a
+ * single sample rather than one per sibling.
+ */
+export declare function computeStepLatencyTracking(params: {
+    /** The orchestrator's current in-memory event log (ascending order). */
+    events: Event[];
+    /**
+     * Whether this invocation's initial event load contained nothing beyond
+     * run_created/run_started/attr_set. Pre-existing hook events were written
+     * by an earlier invocation, so the time they added (including the queue
+     * hop back to this invocation) is unmeasurable and disqualifies TTFS.
+     * attr_set is permitted: a redelivery can land after a committed pre-step
+     * attr_set, and the detour it marks is subtracted via `preStepAttrStartMs`
+     * regardless of which invocation wrote it.
+     */
+    invocationStartedClean: boolean;
+    /** Epoch ms of run creation, if recoverable. Absent disqualifies TTFS. */
+    runCreatedAtMs: number | undefined;
+    /** See {@link StepLatencyTracking.preStepBlockingMs}. */
+    preStepBlockingMs: number;
+    /**
+     * The accumulator's value as of the suspension that wrote the run's first
+     * attr_set (its hook phase runs before its attr writes). When the
+     * measurement ends at the attr write, only hook time from before that
+     * point may be subtracted — later hook writes fall outside the measured
+     * window. Undefined when no attr suspension happened in this invocation
+     * (e.g. the attr_set was loaded from a redelivery's snapshot, where no
+     * same-invocation hook time precedes it).
+     */
+    preStepBlockingBeforeAttrMs: number | undefined;
+    /**
+     * Whether the suspension that scheduled this batch also created waits.
+     * Those `wait_created` writes are not in `events` yet (they were committed
+     * by this very suspension pass), so they must be reported separately. A
+     * wait disqualifies both measurements.
+     */
+    suspensionHasWaits: boolean;
+    /**
+     * Whether the suspension that scheduled this batch also created hooks
+     * (also not in `events` yet). Hooks keep TTFS eligible — their measured
+     * write time is subtracted via `preStepBlockingMs` — but disqualify STSO,
+     * which is only meaningful for a pure back-to-back step gap.
+     */
+    suspensionCreatedHooks: boolean;
+    /** Whether turbo mode is active for this invocation. */
+    turbo: boolean;
+}): StepLatencyTracking | undefined;
+/**
+ * Compute the latency telemetry to attach to the step's terminal event.
+ * Called by `executeStep` with the wall-clock timestamp taken immediately
+ * before user step code runs. Returns undefined when there is nothing to
+ * report (no tracking, or a retry attempt — retries measure neither TTFS nor
+ * STSO).
+ */
+export declare function computeStepLatencyEventData(params: {
+    tracking: StepLatencyTracking | undefined;
+    /** `Date.now()` taken immediately before user step code began executing. */
+    stepCodeStartedAtMs: number;
+    attempt: number;
+    /** Whether this step was started lazily (no separate step_created write). */
+    lazyStepStart: boolean;
+    /** Whether the body ran optimistically, without awaiting step_started. */
+    optimisticStart: boolean;
+}): StepLatencyEventData | undefined;
+//# sourceMappingURL=step-latency.d.ts.map

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

@@ -0,0 +1,72 @@
+import type { Event } from '#compiled/@workflow/world/index.js';
+import type { StepInvocationQueueItem } from '../global.js';
+/**
+ * Inline step ownership helpers for the pending-step dispatch decision table
+ * in runtime.ts (workflow#2780). Ownership state itself is derived per-replay
+ * from the event log by the step consumer in step.ts and surfaced on
+ * StepInvocationQueueItem; these functions interpret that state at dispatch
+ * time.
+ */
+/**
+ * Whether inline step ownership is active for a pending step: created,
+ * latest `step_started` carries an owner stamp, and no `step_retrying` has
+ * been observed (from `step_retrying` on, the step is queue-owned by its
+ * delayed retry handoff / replay requeue, so ownership is permanently
+ * lapsed for the correlation ID).
+ */
+export declare function isStepOwnershipActive(step: StepInvocationQueueItem): boolean;
+/**
+ * Seconds left on an owned step's liveness lease, anchored at its latest
+ * `step_started`. 0 means the lease has expired (or the start timestamp is
+ * missing — the degraded mode for worlds whose events lack usable
+ * timestamps), in which case dispatch falls back to the immediate enqueue.
+ *
+ * The result is clamped to the configured lease: `lastStartedAt` is the
+ * server-stamped event `createdAt` while `nowMs` is the local clock, so a
+ * client running behind the server would otherwise compute a remainder
+ * LONGER than the lease itself — and with the lease tuned to the 900s cap,
+ * a `delaySeconds` above the queue's per-message maximum, which SQS-backed
+ * worlds reject outright (the wake replay's enqueue would throw and ride
+ * the redelivery loop). The clamp makes skew strictly harmless; remaining
+ * time can never legitimately exceed the full lease anyway.
+ */
+export declare function stepLeaseRemainingSeconds(step: StepInvocationQueueItem, nowMs: number): number;
+/**
+ * Idempotency key for the delayed backstop wake of an inline-owned step.
+ *
+ * The key is scoped to the current OWNERSHIP EPOCH — the timestamp of the
+ * latest `step_started` — not just the correlation ID. Within one epoch,
+ * every wake replay derives the same key, so fan-out stays capped at one
+ * pending backstop per step. But when owner recovery re-stamps the step
+ * (queue redelivery of the owning message → new `step_started` → new
+ * `lastStartedAt`), the key CHANGES. This is load-bearing for liveness:
+ * queues dedupe an idempotency key for the lifetime of the original
+ * message — including while a delivery of it is in flight — so a backstop
+ * that fires during a refreshed lease and tries to re-arm under a fixed key
+ * would dedupe against ITSELF and be dropped, leaving no escape hatch if
+ * the recovered owner later dies without further redeliveries. The epoch
+ * suffix gives the re-arm a fresh key. Pending backstops are bounded by the
+ * number of ownership epochs, i.e. the queue's redelivery budget for the
+ * owning message.
+ *
+ * The epoch value comes from the persisted event's `createdAt`, so every
+ * replayer derives the same key. Callers only build backstops when the
+ * lease has time remaining, which requires `lastStartedAt` to be set.
+ *
+ * The key must also never be the step message's own `idempotencyKey`
+ * (the bare correlation ID): the owner's retry handoff enqueues the step
+ * under that key with a short backoff, and a pending backstop sharing it
+ * would absorb the retry — turning a 1s backoff into a full-lease stall.
+ */
+export declare function backstopIdempotencyKey(step: StepInvocationQueueItem): string;
+/**
+ * Whether any of the given pending correlation IDs is inline-owned by
+ * `messageId` per the raw event log: its LATEST `step_started` carries
+ * `ownerMessageId === messageId` and no `step_retrying` follows it. Used by
+ * the background-step fast path, which sees raw events (not the replay's
+ * queueItems), to decide whether to fall through to the main loop so this
+ * invocation can recover a step it owns instead of returning and leaving it
+ * to the delayed backstop.
+ */
+export declare function hasPendingStepOwnedByMessage(events: Event[], pendingCorrelationIds: Set<string | undefined>, messageId: string): boolean;
+//# sourceMappingURL=step-ownership.d.ts.map

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

@@ -0,0 +1,12 @@
+import type { StepExecutionResult } from './step-executor.js';
+/**
+ * Run `execute` unless an execution for the same run + step correlation ID is
+ * already in flight in this process. The winner's result is returned to the
+ * winner; a loser awaits the winner's settlement (success OR failure) and
+ * then returns `{ type: 'skipped' }` so its caller acks without running the
+ * body. A winner failure is not propagated to the loser — the winner's own
+ * queue message redelivers and drives the retry, so exactly one message
+ * keeps owning the outcome.
+ */
+export declare function runStepSingleFlight(runId: string, correlationId: string, execute: () => Promise<StepExecutionResult>): Promise<StepExecutionResult>;
+//# sourceMappingURL=step-single-flight.d.ts.map

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

@@ -77,6 +77,13 @@ export interface SuspensionHandlerResult {
      * inline start (a hook introduces later resume invocations that could race).
      */
     hasHookEvents: boolean;
+    /**
+     * Wall-clock ms spent committing this suspension's `hook_created` events
+     * (0 when it created none). The caller accumulates this across iterations
+     * and subtracts it from the TTFS latency measurement, so time spent
+     * durably creating the user's hooks doesn't count as runtime overhead.
+     */
+    hookCreationMs: number;
 }
 /**
  * Handles a workflow suspension by processing all pending operations (hooks, steps, waits).

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

@@ -4,7 +4,7 @@ export { WorkflowSuspension } from './global.js';
 export { type HealthCheckEndpoint, type HealthCheckOptions, type HealthCheckResult, healthCheck, } from './runtime/helpers.js';
 export { getHookByToken, resumeHook, resumeWebhook, } from './runtime/resume-hook.js';
 export { getRun, Run, type WorkflowReadableStream, type WorkflowReadableStreamOptions, } from './runtime/run.js';
-export { cancelRun, listStreams, type ReadStreamOptions, type RecreateRunOptions, readStream, recreateRunFromExisting, reenqueueRun, type StopSleepOptions, type StopSleepResult, wakeUpRun, } from './runtime/runs.js';
+export { type CancelRunOptions, cancelRun, 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 { createWorld, createWorldFromModule, getWorld, getWorldHandlers, setWorld, type WorldFactoryModule, } from './runtime/world.js';
 /**