@dudousxd/nestjs-durable-core 0.32.1 → 0.34.0

package/dist/index.d.cts

@@ -283,6 +283,13 @@ interface StepCheckpoint {
     events?: StepEvent[] | undefined;
     /** For sleep steps: epoch ms the sleep elapses at. */
     wakeAt?: number | undefined;
+    /**
+     * Set on the running placeholder checkpoints of the children dispatched by one `ctx.all` call —
+     * a shared tag (`all:<firstSeq>`) grouping the N siblings so the dashboard can render them as one
+     * parallel fan-out. Optional and additive: absent on every non-`all` checkpoint. Mirrors the
+     * Python SDK's `parallelGroup`.
+     */
+    parallelGroup?: string | undefined;
     /**
      * When the step entered the system: for a remote step, when the engine dispatched it to the
      * transport; for a local step, when it began. Queue-wait time = `startedAt − enqueuedAt`.
@@ -570,7 +577,13 @@ interface StepResult {
 interface Heartbeat {
     runId: string;
     seq: number;
-    stepId: string;
+    /**
+     * The in-flight step this beat keeps alive. ABSENT for a RUN-scoped (workflow-turn) heartbeat: a
+     * worker replaying a long workflow turn beats for its `runId` so the engine rearms the run's
+     * `advance` deadline (see `WorkflowEngineDeps.remoteAdvanceSilenceMs`). The engine then keys the
+     * liveness reset by `runId` instead of `stepId`.
+     */
+    stepId?: string | undefined;
     group: string;
 }
 /** engine → workflow worker: advance this run one turn by replaying the function against `history`. */
@@ -636,6 +649,9 @@ type WorkflowCommand =
     startedAt?: number;
     finishedAt?: number;
     events?: StepEvent[];
+    /** A worker's `ctx.gather([...])` tags every step in the parallel fan with the same group, so the
+     *  engine carries it onto the checkpoint and the dashboard renders the fan as one group. */
+    parallelGroup?: string;
 }
 /** `ctx.sleep(ms)` — a durable timer of `ms` duration. The engine computes the absolute deadline
  *  (now + ms) when it applies the command, so the worker never reads the clock (determinism). */
@@ -650,12 +666,15 @@ type WorkflowCommand =
     seq: number;
     signal: string;
 }
-/** `ctx.start_child(workflow, input)` — start a child run with its own lifecycle. */
+/** `ctx.start_child(workflow, input)` — start a child run with its own lifecycle. A worker's
+ *  `ctx.all([...])` fan-out tags every dispatched child with the same `parallelGroup` so the
+ *  dashboard can render the fan as one group (parity with the gathered `recordStep` tag). */
  | {
     kind: 'startChild';
     seq: number;
     workflow: string;
     input: unknown;
+    parallelGroup?: string;
 };
 /** workflow worker → engine: the result of replaying one turn of a remote workflow. */
 interface WorkflowDecision {
@@ -693,6 +712,9 @@ interface WorkflowStepEvent {
     error?: StepError;
     /** Sub-process + log trail the step emitted so far (the handler's p-processes). */
     events?: StepEvent[];
+    /** A worker's `ctx.gather([...])` fan tags every step's lifecycle with the same group so the
+     *  dashboard renders the live fan-out as one group (parity with the `recordStep` tag). */
+    parallelGroup?: string | undefined;
 }
 /**
  * Advances a workflow run one turn. The engine has one per workflow: the default {@link InProcess}
@@ -988,6 +1010,24 @@ interface WorkflowCtx {
      */
     startChild<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, options?: string | ChildCallOptions): Promise<string>;
     startChild(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<string>;
+    /**
+     * Run N children of the SAME workflow **in parallel** and wait for ALL of them: dispatches one
+     * child per entry in `inputs` (concurrently, each with its own durable lifecycle), suspends — zero
+     * compute — until every child reaches a terminal state, then resumes with their outputs in **input
+     * order**. Child ids are group-scoped and stable (`<runId>.all.<firstSeq>.<i>`), and the running
+     * placeholders share a `parallelGroup` tag so the dashboard renders the fan-out as one group.
+     *
+     * `mode` (default `waitAll`): `waitAll` waits for all then throws an aggregate {@link GatherError}
+     * if any failed; `failFast` throws as soon as a failed child is seen (siblings are not cancelled in
+     * v1 — their eventual results are ignored). Empty `inputs` returns `[]` with no side effects. The
+     * wait-all / fan-out counterpart to {@link child}; parity with the Python SDK's `gather_children`.
+     */
+    all<C extends WorkflowClass>(workflow: C, inputs: WorkflowInputOf<C>[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<WorkflowOutputOf<C>[]>;
+    all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<TOutput[]>;
     /**
      * Pause the run at this point until a human resumes it from the dashboard (or
      * `engine.continue(runId)`). Records a visible `pending` checkpoint so the breakpoint shows up
@@ -1257,6 +1297,18 @@ interface WorkflowEngineDeps {
      * Omit for unlimited (the default — recovery always retries).
      */
     maxRecoveryAttempts?: number | undefined;
+    /**
+     * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
+     * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
+     * it rejects the advance with {@link RemoteWorkflowTimeout}, releases the lease, and lets recovery
+     * re-drive (replaying completed steps from history). Each beat REARMS the window, so a worker still
+     * legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
+     * side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
+     * for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
+     * ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
+     * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
+     */
+    remoteAdvanceSilenceMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1330,6 +1382,7 @@ declare class WorkflowEngine {
     private readonly instanceId;
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
+    private readonly remoteAdvanceSilenceMs?;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -1354,7 +1407,9 @@ declare class WorkflowEngine {
     private readonly accumulators;
     /** In-flight remote steps awaiting a worker result, keyed by stepId. */
     private readonly pending;
-    /** Per-step "reset the liveness timer" callbacks, called when a heartbeat arrives. */
+    /** "Reset the liveness timer" callbacks keyed by the beat's target — a stepId (in-flight remote step)
+     *  or a runId (in-flight remote workflow turn) — invoked when a matching heartbeat arrives. The two id
+     *  shapes don't collide in practice: a stepId is `${runId}:${seq}`, a run key is the bare runId. */
     private readonly heartbeatResets;
     private readonly listeners;
     /** Step interceptors (onion middleware around real local-step execution), first = outermost. */
@@ -1751,10 +1806,15 @@ declare class WorkflowEngine {
     /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
     private callRemoteInMemory;
     /**
-     * Await a remote result, but reject with `RemoteStepTimeout` if neither the result nor a heartbeat
-     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`) rearms the
-     * window, so a worker that keeps beating stays alive past `timeoutMs`.
+     * Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
+     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
+     * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
+     * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
+     * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
      */
+    private awaitWithLivenessDeadline;
+    /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
+     *  `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
     private awaitWithHeartbeat;
 }
 /** Raised inside the workflow when a remote worker reports a step failure. */
@@ -1803,6 +1863,29 @@ declare class RemoteStepTimeout extends Error {
     readonly timeoutMs: number;
     constructor(stepId: string, timeoutMs: number);
 }
+/**
+ * Thrown by a remote {@link WorkflowExecutor} (e.g. {@link RemoteWorkflowExecutor}) when an `advance`
+ * does not produce its decision within the configured `timeoutMs` — i.e. the worker is presumed gone
+ * (the decision was dropped by a stall/redelivery or an instance restart spanning the in-memory waiter
+ * map). Crucially this is NOT a run failure: the work may have actually completed and only the decision
+ * was lost. The engine treats it as RECOVERABLE — it releases the run lease and leaves the run
+ * `running` so `recoverIncomplete` re-drives it deterministically (replaying completed steps from
+ * history). Distinct from a real executor error, which still fails the run.
+ *
+ * OPT-IN: only thrown when the executor was constructed with a `timeoutMs`. Absent a timeout, the
+ * engine awaits the decision with its prior (unbounded) behavior — so existing users see no change.
+ *
+ * Known hazard: a timeout that fires while a worker is LEGITIMATELY still executing a not-yet-
+ * checkpointed step will re-drive and re-run that in-flight step → DUPLICATE side effects. Therefore
+ * the timeout is only safe when set GENEROUSLY (longer than the longest legitimate single turn). The
+ * robust fix — a liveness/heartbeat-rearmed deadline so only a genuinely-dead worker re-drives — is the
+ * documented follow-up (see the Track A diagnosis doc, "Part B").
+ */
+declare class RemoteWorkflowTimeout extends Error {
+    readonly taskId: string;
+    readonly timeoutMs: number;
+    constructor(taskId: string, timeoutMs: number);
+}
 /**
  * Thrown on resume when the workflow code no longer matches the recorded history: the step at a
  * logical position has a different name/kind than the checkpoint saved there. This means the
@@ -1816,6 +1899,24 @@ declare class NonDeterminismError extends Error {
     readonly seq: number;
     constructor(runId: string, seq: number, expected: string, recorded: string);
 }
+/**
+ * Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
+ * (input index, child run id, error message) and presents an aggregate message summarizing the count
+ * and the failing ids — the wait-all/fail-fast counterpart to a single child's FatalError. Mirrors
+ * the Python SDK's `GatherFailed`.
+ */
+declare class GatherError extends Error {
+    readonly failures: {
+        index: number;
+        id: string;
+        error: string;
+    }[];
+    constructor(failures: {
+        index: number;
+        id: string;
+        error: string;
+    }[], total?: number);
+}
 declare class WorkflowSuspended extends Error {
     /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
     readonly wakeAt?: number | undefined;
@@ -2059,6 +2160,14 @@ declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string):
  */
 declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 
+/**
+ * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
+ * local-step path (`ctx.step`) and the remote-worker path (`runStepHandler`) so a step records
+ * the same {@link StepEvent} shape wherever it runs — the TypeScript twin of the Python SDK's
+ * `StepContext`.
+ */
+declare function createStepLogger(events: StepEvent[], now: () => number): StepLogger;
+
 /**
  * Does a run's search attributes satisfy EVERY filter (AND)? A missing key never matches (so `ne`
  * on an absent key is false too — the attribute simply isn't there to compare). Empty/undefined
@@ -2218,13 +2327,16 @@ declare class InMemoryStateStore implements StateStore {
 declare class InMemoryTransport implements Transport, ControlPlane {
     private readonly handlers;
     private resultHandler?;
+    private heartbeatHandler?;
     private stepEventHandler?;
     private readonly controlHandlers;
     /** Register a fake worker handler for a step name. */
     handle(name: string, fn: StepHandler): void;
     dispatch(task: RemoteTask): Promise<void>;
     onResult(handler: (result: StepResult) => Promise<void>): void;
-    onHeartbeat(_handler: (beat: Heartbeat) => Promise<void>): void;
+    onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    /** Test hook: deliver a liveness heartbeat to the engine, as a real broker would on its channel. */
+    emitHeartbeat(beat: Heartbeat): Promise<void>;
     /** Workflow step lifecycle: deliver to the engine's handler (async, mirroring a real broker). */
     dispatchStepEvent(event: WorkflowStepEvent): Promise<void>;
     onStepEvent(handler: (event: WorkflowStepEvent) => Promise<void>): void;
@@ -2232,4 +2344,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };

package/dist/index.d.ts

@@ -283,6 +283,13 @@ interface StepCheckpoint {
     events?: StepEvent[] | undefined;
     /** For sleep steps: epoch ms the sleep elapses at. */
     wakeAt?: number | undefined;
+    /**
+     * Set on the running placeholder checkpoints of the children dispatched by one `ctx.all` call —
+     * a shared tag (`all:<firstSeq>`) grouping the N siblings so the dashboard can render them as one
+     * parallel fan-out. Optional and additive: absent on every non-`all` checkpoint. Mirrors the
+     * Python SDK's `parallelGroup`.
+     */
+    parallelGroup?: string | undefined;
     /**
      * When the step entered the system: for a remote step, when the engine dispatched it to the
      * transport; for a local step, when it began. Queue-wait time = `startedAt − enqueuedAt`.
@@ -570,7 +577,13 @@ interface StepResult {
 interface Heartbeat {
     runId: string;
     seq: number;
-    stepId: string;
+    /**
+     * The in-flight step this beat keeps alive. ABSENT for a RUN-scoped (workflow-turn) heartbeat: a
+     * worker replaying a long workflow turn beats for its `runId` so the engine rearms the run's
+     * `advance` deadline (see `WorkflowEngineDeps.remoteAdvanceSilenceMs`). The engine then keys the
+     * liveness reset by `runId` instead of `stepId`.
+     */
+    stepId?: string | undefined;
     group: string;
 }
 /** engine → workflow worker: advance this run one turn by replaying the function against `history`. */
@@ -636,6 +649,9 @@ type WorkflowCommand =
     startedAt?: number;
     finishedAt?: number;
     events?: StepEvent[];
+    /** A worker's `ctx.gather([...])` tags every step in the parallel fan with the same group, so the
+     *  engine carries it onto the checkpoint and the dashboard renders the fan as one group. */
+    parallelGroup?: string;
 }
 /** `ctx.sleep(ms)` — a durable timer of `ms` duration. The engine computes the absolute deadline
  *  (now + ms) when it applies the command, so the worker never reads the clock (determinism). */
@@ -650,12 +666,15 @@ type WorkflowCommand =
     seq: number;
     signal: string;
 }
-/** `ctx.start_child(workflow, input)` — start a child run with its own lifecycle. */
+/** `ctx.start_child(workflow, input)` — start a child run with its own lifecycle. A worker's
+ *  `ctx.all([...])` fan-out tags every dispatched child with the same `parallelGroup` so the
+ *  dashboard can render the fan as one group (parity with the gathered `recordStep` tag). */
  | {
     kind: 'startChild';
     seq: number;
     workflow: string;
     input: unknown;
+    parallelGroup?: string;
 };
 /** workflow worker → engine: the result of replaying one turn of a remote workflow. */
 interface WorkflowDecision {
@@ -693,6 +712,9 @@ interface WorkflowStepEvent {
     error?: StepError;
     /** Sub-process + log trail the step emitted so far (the handler's p-processes). */
     events?: StepEvent[];
+    /** A worker's `ctx.gather([...])` fan tags every step's lifecycle with the same group so the
+     *  dashboard renders the live fan-out as one group (parity with the `recordStep` tag). */
+    parallelGroup?: string | undefined;
 }
 /**
  * Advances a workflow run one turn. The engine has one per workflow: the default {@link InProcess}
@@ -988,6 +1010,24 @@ interface WorkflowCtx {
      */
     startChild<C extends WorkflowClass>(workflow: C, input: WorkflowInputOf<C>, options?: string | ChildCallOptions): Promise<string>;
     startChild(workflow: string, input: unknown, options?: string | ChildCallOptions): Promise<string>;
+    /**
+     * Run N children of the SAME workflow **in parallel** and wait for ALL of them: dispatches one
+     * child per entry in `inputs` (concurrently, each with its own durable lifecycle), suspends — zero
+     * compute — until every child reaches a terminal state, then resumes with their outputs in **input
+     * order**. Child ids are group-scoped and stable (`<runId>.all.<firstSeq>.<i>`), and the running
+     * placeholders share a `parallelGroup` tag so the dashboard renders the fan-out as one group.
+     *
+     * `mode` (default `waitAll`): `waitAll` waits for all then throws an aggregate {@link GatherError}
+     * if any failed; `failFast` throws as soon as a failed child is seen (siblings are not cancelled in
+     * v1 — their eventual results are ignored). Empty `inputs` returns `[]` with no side effects. The
+     * wait-all / fan-out counterpart to {@link child}; parity with the Python SDK's `gather_children`.
+     */
+    all<C extends WorkflowClass>(workflow: C, inputs: WorkflowInputOf<C>[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<WorkflowOutputOf<C>[]>;
+    all<TOutput = unknown>(workflow: string, inputs: unknown[], opts?: {
+        mode?: 'waitAll' | 'failFast';
+    }): Promise<TOutput[]>;
     /**
      * Pause the run at this point until a human resumes it from the dashboard (or
      * `engine.continue(runId)`). Records a visible `pending` checkpoint so the breakpoint shows up
@@ -1257,6 +1297,18 @@ interface WorkflowEngineDeps {
      * Omit for unlimited (the default — recovery always retries).
      */
     maxRecoveryAttempts?: number | undefined;
+    /**
+     * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
+     * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
+     * it rejects the advance with {@link RemoteWorkflowTimeout}, releases the lease, and lets recovery
+     * re-drive (replaying completed steps from history). Each beat REARMS the window, so a worker still
+     * legitimately replaying a long turn (it keeps beating) is never re-driven — closing the duplicate-
+     * side-effect hazard a fixed {@link RemoteWorkflowExecutor} `timeoutMs` cannot avoid. Omit (default)
+     * for the prior unbounded await — byte-identical behavior when unset. If a `RemoteWorkflowExecutor` is
+     * ALSO constructed with its own `timeoutMs`, the shorter of the two deadlines wins; prefer setting only
+     * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
+     */
+    remoteAdvanceSilenceMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1330,6 +1382,7 @@ declare class WorkflowEngine {
     private readonly instanceId;
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
+    private readonly remoteAdvanceSilenceMs?;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -1354,7 +1407,9 @@ declare class WorkflowEngine {
     private readonly accumulators;
     /** In-flight remote steps awaiting a worker result, keyed by stepId. */
     private readonly pending;
-    /** Per-step "reset the liveness timer" callbacks, called when a heartbeat arrives. */
+    /** "Reset the liveness timer" callbacks keyed by the beat's target — a stepId (in-flight remote step)
+     *  or a runId (in-flight remote workflow turn) — invoked when a matching heartbeat arrives. The two id
+     *  shapes don't collide in practice: a stepId is `${runId}:${seq}`, a run key is the bare runId. */
     private readonly heartbeatResets;
     private readonly listeners;
     /** Step interceptors (onion middleware around real local-step execution), first = outermost. */
@@ -1751,10 +1806,15 @@ declare class WorkflowEngine {
     /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
     private callRemoteInMemory;
     /**
-     * Await a remote result, but reject with `RemoteStepTimeout` if neither the result nor a heartbeat
-     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`) rearms the
-     * window, so a worker that keeps beating stays alive past `timeoutMs`.
+     * Await `resultPromise`, but reject with `onTimeout()` if neither it settles nor a heartbeat for `id`
+     * arrives within `timeoutMs`. Each heartbeat (delivered via `transport.onHeartbeat`, looked up in
+     * `heartbeatResets` by `id`) REARMS the window, so a worker that keeps beating stays alive past
+     * `timeoutMs`. Shared by the remote-STEP liveness (keyed by stepId) and the remote-WORKFLOW advance
+     * liveness (keyed by runId); the caller supplies the timeout error and any extra cleanup via `onTimeout`.
      */
+    private awaitWithLivenessDeadline;
+    /** Remote-STEP liveness: await a worker result, timing out (with the step's pending-map cleanup) to
+     *  `RemoteStepTimeout` if it neither lands nor beats within `timeoutMs`. See {@link awaitWithLivenessDeadline}. */
     private awaitWithHeartbeat;
 }
 /** Raised inside the workflow when a remote worker reports a step failure. */
@@ -1803,6 +1863,29 @@ declare class RemoteStepTimeout extends Error {
     readonly timeoutMs: number;
     constructor(stepId: string, timeoutMs: number);
 }
+/**
+ * Thrown by a remote {@link WorkflowExecutor} (e.g. {@link RemoteWorkflowExecutor}) when an `advance`
+ * does not produce its decision within the configured `timeoutMs` — i.e. the worker is presumed gone
+ * (the decision was dropped by a stall/redelivery or an instance restart spanning the in-memory waiter
+ * map). Crucially this is NOT a run failure: the work may have actually completed and only the decision
+ * was lost. The engine treats it as RECOVERABLE — it releases the run lease and leaves the run
+ * `running` so `recoverIncomplete` re-drives it deterministically (replaying completed steps from
+ * history). Distinct from a real executor error, which still fails the run.
+ *
+ * OPT-IN: only thrown when the executor was constructed with a `timeoutMs`. Absent a timeout, the
+ * engine awaits the decision with its prior (unbounded) behavior — so existing users see no change.
+ *
+ * Known hazard: a timeout that fires while a worker is LEGITIMATELY still executing a not-yet-
+ * checkpointed step will re-drive and re-run that in-flight step → DUPLICATE side effects. Therefore
+ * the timeout is only safe when set GENEROUSLY (longer than the longest legitimate single turn). The
+ * robust fix — a liveness/heartbeat-rearmed deadline so only a genuinely-dead worker re-drives — is the
+ * documented follow-up (see the Track A diagnosis doc, "Part B").
+ */
+declare class RemoteWorkflowTimeout extends Error {
+    readonly taskId: string;
+    readonly timeoutMs: number;
+    constructor(taskId: string, timeoutMs: number);
+}
 /**
  * Thrown on resume when the workflow code no longer matches the recorded history: the step at a
  * logical position has a different name/kind than the checkpoint saved there. This means the
@@ -1816,6 +1899,24 @@ declare class NonDeterminismError extends Error {
     readonly seq: number;
     constructor(runId: string, seq: number, expected: string, recorded: string);
 }
+/**
+ * Thrown by `ctx.all` when one or more parallel child workflows fail. Carries the per-item failures
+ * (input index, child run id, error message) and presents an aggregate message summarizing the count
+ * and the failing ids — the wait-all/fail-fast counterpart to a single child's FatalError. Mirrors
+ * the Python SDK's `GatherFailed`.
+ */
+declare class GatherError extends Error {
+    readonly failures: {
+        index: number;
+        id: string;
+        error: string;
+    }[];
+    constructor(failures: {
+        index: number;
+        id: string;
+        error: string;
+    }[], total?: number);
+}
 declare class WorkflowSuspended extends Error {
     /** Epoch ms to auto-resume (durable sleep), or undefined when waiting on an external signal. */
     readonly wakeAt?: number | undefined;
@@ -2059,6 +2160,14 @@ declare function prevCronFireMs(expr: string, nowMs: number, timezone?: string):
  */
 declare function runSchedules(engine: Pick<WorkflowEngine, 'start' | 'getRun'>, schedules: readonly ScheduledWorkflow[], nowMs: number, opts?: RunSchedulesOptions): Promise<string[]>;
 
+/**
+ * A {@link StepLogger} that appends to `events`, stamping each line with `now()`. Shared by the
+ * local-step path (`ctx.step`) and the remote-worker path (`runStepHandler`) so a step records
+ * the same {@link StepEvent} shape wherever it runs — the TypeScript twin of the Python SDK's
+ * `StepContext`.
+ */
+declare function createStepLogger(events: StepEvent[], now: () => number): StepLogger;
+
 /**
  * Does a run's search attributes satisfy EVERY filter (AND)? A missing key never matches (so `ne`
  * on an absent key is false too — the attribute simply isn't there to compare). Empty/undefined
@@ -2218,13 +2327,16 @@ declare class InMemoryStateStore implements StateStore {
 declare class InMemoryTransport implements Transport, ControlPlane {
     private readonly handlers;
     private resultHandler?;
+    private heartbeatHandler?;
     private stepEventHandler?;
     private readonly controlHandlers;
     /** Register a fake worker handler for a step name. */
     handle(name: string, fn: StepHandler): void;
     dispatch(task: RemoteTask): Promise<void>;
     onResult(handler: (result: StepResult) => Promise<void>): void;
-    onHeartbeat(_handler: (beat: Heartbeat) => Promise<void>): void;
+    onHeartbeat(handler: (beat: Heartbeat) => Promise<void>): void;
+    /** Test hook: deliver a liveness heartbeat to the engine, as a real broker would on its channel. */
+    emitHeartbeat(beat: Heartbeat): Promise<void>;
     /** Workflow step lifecycle: deliver to the engine's handler (async, mirroring a real broker). */
     dispatchStepEvent(event: WorkflowStepEvent): Promise<void>;
     onStepEvent(handler: (event: WorkflowStepEvent) => Promise<void>): void;
@@ -2232,4 +2344,4 @@ declare class InMemoryTransport implements Transport, ControlPlane {
     onControl(handler: (msg: ControlMessage) => void): void;
 }
 
-export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };
+export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AttributeFilter, type AttributeOp, type BackoffStrategy, type ChildCallOptions, CodecStateStore, ContinueAsNew, type ControlMessage, type ControlPlane, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, type DurableWebhook, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, EventAccumulators, type EventBatchConfig, FatalError, GatherError, type GroupHealth, type Heartbeat, type HistoryEvent, InMemoryAdmissionBackend, InMemoryStateStore, InMemoryTransport, type MetricsCollector, type MetricsSnapshot, type NamedTransport, NonDeterminismError, type PayloadCodec, type QueueConfig, QueueController, type RemoteStepConfig, type RemoteStepDef, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RunAttributeRow, type RunDispatcher, type RunQuery, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StateStore, type StepCheckpoint, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepResult, type StoreTransaction, type SubProcessHandle, TRANSPORT, TRANSPORT_CANONICAL, type Transport, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerHeartbeat, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, breakpointToken, collectMetrics, createStepLogger, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, remoteStep, runSchedules, runStepHandler, scheduledRunId, sqlComparator, stepId, workflowName };