eve 0.22.3 → 0.22.5

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

@@ -2,6 +2,15 @@ import { type World } from '#compiled/@workflow/world/index.js';
 export interface RecreateRunOptions {
     deploymentId?: string;
     specVersion?: number;
+    /**
+     * Queue namespace of the target deployment (e.g. `'eve'` for topics like
+     * `__eve_wkf_workflow_*`). Falls back to `WORKFLOW_QUEUE_NAMESPACE` in
+     * the calling process. Cross-context callers (e.g. the observability
+     * dashboard) must pass the target deployment's namespace explicitly —
+     * a run enqueued to a topic the target deployment has no consumer for
+     * is never picked up.
+     */
+    namespace?: string;
 }
 export interface StopSleepResult {
     /** Number of pending sleeps that were stopped */
@@ -21,6 +30,28 @@ export interface StopSleepOptions {
      * If not provided, all pending sleep calls will be interrupted.
      */
     correlationIds?: string[];
+    /**
+     * Queue namespace of the run's deployment (e.g. `'eve'`), used when
+     * re-enqueueing the run after completing its waits. Falls back to
+     * `WORKFLOW_QUEUE_NAMESPACE` in the calling process. Cross-context
+     * callers (e.g. the observability dashboard) must pass it explicitly.
+     */
+    namespace?: string;
+}
+export interface ReenqueueRunOptions {
+    /**
+     * Queue namespace of the run's deployment (e.g. `'eve'`). Falls back to
+     * `WORKFLOW_QUEUE_NAMESPACE` in the calling process. Cross-context
+     * callers (e.g. the observability dashboard) must pass it explicitly.
+     */
+    namespace?: string;
+}
+export interface CancelRunOptions {
+    /**
+     * Optional free-text reason for the cancellation (max 512 chars), recorded
+     * on the run_cancelled event and surfaced in the run detail view.
+     */
+    cancelReason?: string;
 }
 /**
  * Start a new workflow run based on an existing run.
@@ -28,12 +59,15 @@ export interface StopSleepOptions {
 export declare function recreateRunFromExisting(world: World, runId: string, options?: RecreateRunOptions): Promise<string>;
 /**
  * Cancel a workflow run.
+ *
+ * @param options - Optional cancellation settings. `cancelReason` records a
+ *   free-text reason (max 512 chars) on the run_cancelled event.
  */
-export declare function cancelRun(world: World, runId: string): Promise<void>;
+export declare function cancelRun(world: World, runId: string, options?: CancelRunOptions): Promise<void>;
 /**
  * Re-enqueue a workflow run.
  */
-export declare function reenqueueRun(world: World, runId: string): Promise<void>;
+export declare function reenqueueRun(world: World, runId: string, options?: ReenqueueRunOptions): Promise<void>;
 /**
  * Wake up a workflow run by interrupting pending sleep() calls.
  */

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

@@ -36,6 +36,34 @@ export interface StartOptionsBase {
      * the `experimental_setAttributes` option of the same name.
      */
     allowReservedAttributes?: boolean;
+    /**
+     * The ID of an existing run this run is being replayed from, if any.
+     *
+     * Recorded on the new run's `executionContext` as `replayedFromRunId` so
+     * tooling (e.g. the dashboard runs list) can show that a run originated as
+     * a replay and link back to its source. Set automatically by
+     * {@link recreateRunFromExisting}; there's usually no reason to pass it
+     * directly.
+     *
+     * Must be a run ID: `wrun_` followed by a 26-char ULID. It's a foreign key
+     * to the source run, so `start()` validates the exact shape and rejects
+     * anything else rather than persist a lineage link that points at garbage.
+     */
+    replayedFromRunId?: string;
+    /**
+     * Queue namespace of the target deployment. Scopes the workflow queue
+     * topic to `__{namespace}_wkf_workflow_*` (e.g. `'eve'`) instead of the
+     * default `__wkf_workflow_*`, and is also used for the cross-deployment
+     * capability probe. Falls back to `WORKFLOW_QUEUE_NAMESPACE` in the
+     * calling process.
+     *
+     * Within a deployment the env fallback is correct. Cross-context callers
+     * (e.g. the observability dashboard replaying a run) must pass the
+     * TARGET deployment's namespace explicitly: the env fallback resolves in
+     * the caller's process, and a run enqueued to a topic the target has no
+     * consumer for is never picked up.
+     */
+    namespace?: string;
 }
 export interface StartOptionsWithDeploymentId extends StartOptionsBase {
     /**

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

@@ -1,5 +1,6 @@
 import type { Event, SerializedData, World } from '#compiled/@workflow/world/index.js';
 import type { CryptoKey } from '../encryption.js';
+import { type StepLatencyTracking } from './step-latency.js';
 export interface StepExecutorParams {
     world: World;
     workflowRunId: string;
@@ -28,6 +29,19 @@ export interface StepExecutorParams {
      * carries no payload (the legacy contract).
      */
     lazyStepInput?: SerializedData;
+    /**
+     * Inline step ownership: the queue message ID of the invocation this
+     * executeStep call runs in (from the queue handler's meta). When set, the
+     * `step_started` this call sends is stamped with it — on the lazy paths
+     * (where `lazyStepInput` is present) and on the owned-recovery bare start
+     * (where it is not; the re-stamp keeps a recovered step readable as owned
+     * by this message, since ownership derives from the LATEST start). Wake
+     * replays that observe an actively-owned step suppress the immediate
+     * requeue and enqueue a delayed backstop instead. Omitted on the
+     * background-step path, whose bare start intentionally clears ownership
+     * (the step is queue-owned from that point).
+     */
+    ownerMessageId?: string;
     /**
      * Inline-delta optimization (opt-in). When provided, the cursor of the
      * event log as observed by the caller *before* this step's events were
@@ -55,6 +69,15 @@ export interface StepExecutorParams {
      * outside turbo, where `run_started` was already awaited up front.
      */
     runReadyBarrier?: Promise<unknown>;
+    /**
+     * Latency telemetry (TTFS / STSO): eligibility and anchor timestamps decided
+     * by the orchestrator. When set, this executor computes the final values
+     * against the wall clock taken immediately before user code runs and
+     * attaches them to the step's terminal event. Set only for the first step of
+     * an inline batch, and only on first-attempt executions that qualify — see
+     * runtime/step-latency.ts.
+     */
+    latencyTracking?: StepLatencyTracking;
 }
 /**
  * Inline-delta returned by a step-terminal write when the caller passed

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';
 /**