@dudousxd/nestjs-durable-core 0.49.1 → 0.49.3

package/dist/index.d.cts

@@ -330,6 +330,27 @@ interface WorkflowRun {
     createdAt: Date;
     updatedAt: Date;
 }
+/**
+ * WHAT an event-parked suspended run is waiting on, resolved for display — the engine keeps one
+ * generic `suspended` status (it's what drives recovery/timers/queries), but to a human "waiting on
+ * signal `approve`" reads very differently from "waiting on webhook `stripe-cb`". Computed by the
+ * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
+ * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
+ * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
+ * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
+ * signal name).
+ *
+ * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
+ * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
+ * checkpoint scan to disambiguate — so the client shows a non-event suspend with a live worker as
+ * `running` (it flips off "no worker" the moment a worker returns) rather than guessing "sleeping".
+ * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
+ */
+interface RunWaiting {
+    on: 'signal' | 'webhook' | 'child';
+    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    name: string;
+}
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
 /**
  * The recorded result of a single step at a deterministic logical position (`seq`).
@@ -1784,6 +1805,19 @@ interface WorkflowEngineDeps {
      * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
      */
     remoteAdvanceSilenceMs?: number | undefined;
+    /**
+     * Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
+     * an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
+     * a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
+     * crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
+     * invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
+     * fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
+     * idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
+     * advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
+     * still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
+     * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
+     */
+    reconcileMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1859,6 +1893,7 @@ declare class WorkflowEngine {
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
+    private readonly reconcileMs;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2324,6 +2359,13 @@ declare class WorkflowEngine {
      * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
      */
     private settleRun;
+    /**
+     * A wakeAt to persist on a suspend: the natural timer if the turn produced one (a `ctx.sleep`, a
+     * remote-step deadline), else the {@link reconcileMs} fallback so an event-waiting run (child/signal/
+     * timeout-less remote step) can't be orphaned forever if its wake is lost. `undefined` only when the
+     * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
+     */
+    private reconcileWakeAt;
     private runRemoteExecution;
     /**
      * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
@@ -2732,6 +2774,13 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
+/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
+ *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
+ *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
+ *  on a non-parked run and on gateways/versions that don't compute it. */
+type RunListItem = WorkflowRun & {
+    waiting?: RunWaiting | undefined;
+};
 /** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
  *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
  *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
@@ -2759,7 +2808,10 @@ interface RunGateway {
     /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
     topology(): DurableTopology;
     getRunDetail(runId: string): Promise<RunDetail | null>;
-    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
+     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
+     *  plane sent. */
+    listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2775,6 +2827,25 @@ interface RunGateway {
     subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
 }
 
+/**
+ * Resolve WHAT a suspended run is parked on from the token of the {@link SignalWaiter} it registered.
+ * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
+ * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
+ * the wait in a row without fetching that run's timeline.
+ */
+declare function classifyWaiterToken(token: string): RunWaiting;
+/**
+ * Resolve a suspended run's {@link RunWaiting} from the pending signal waiters (indexed by `runId`).
+ * Event-only by design (see {@link RunWaiting}): a `waitForSignal`/`waitForEvent`/webhook/awaited-child
+ * suspend registers a waiter and gets named here; every other suspend (a bare `ctx.sleep`, an in-flight
+ * remote step, a reconcile-parked orphan) returns `undefined`, so the client layers its own display
+ * state (no-worker, singleton, running) on top — none of which can be told apart from `wakeAt` alone.
+ */
+declare function resolveRunWaiting(run: WorkflowRun, waiterByRun: ReadonlyMap<string, SignalWaiter>): RunWaiting | undefined;
+/** Index signal waiters by `runId`, keeping the first seen per run (a run parks on one waiter at a
+ *  time in the sequential case; the earliest is the one it's blocked on). */
+declare function indexWaitersByRun(waiters: readonly SignalWaiter[]): Map<string, SignalWaiter>;
+
 /**
  * Transforms a payload value as it crosses the store boundary — e.g. encrypt-at-rest, compress, or
  * redact PII. `decode` must be the exact inverse of `encode`. Both are synchronous (use a local
@@ -2838,6 +2909,9 @@ declare class CodecStateStore implements StateStore {
 declare function eventPrefix(name: string): string;
 /** Build the unique waiter token for one `waitForEvent` call (name + match + run position). */
 declare function eventToken(name: string, match: Record<string, unknown> | undefined, runId: string, seq: number): string;
+/** The event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
+ *  dashboard can show "waiting on event `<name>`" instead of the opaque token. */
+declare function eventNameOf(token: string): string;
 /** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
 declare function eventMatchOf(token: string): Record<string, unknown>;
 /** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
@@ -3152,4 +3226,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, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, 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, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, 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, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, 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, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.d.ts

@@ -330,6 +330,27 @@ interface WorkflowRun {
     createdAt: Date;
     updatedAt: Date;
 }
+/**
+ * WHAT an event-parked suspended run is waiting on, resolved for display — the engine keeps one
+ * generic `suspended` status (it's what drives recovery/timers/queries), but to a human "waiting on
+ * signal `approve`" reads very differently from "waiting on webhook `stripe-cb`". Computed by the
+ * store-backed gateway from the run's signal waiters (`listSignalWaiters`, ONE bulk scan), so the
+ * dashboard can NAME the wait in a list row without fetching each run's timeline. `on` is derived from
+ * the waiter token's prefix (see `classifyWaiterToken`): `wh:<runId>:<seq>` ⇒ `webhook`, `child:<id>`
+ * ⇒ `child`, `event:<name>:…` ⇒ `signal` (name decoded), anything else ⇒ `signal` (the token IS the
+ * signal name).
+ *
+ * Deliberately EVENT-only (no timer/step): `wakeAt` alone can't tell a real `ctx.sleep` from the
+ * reconcile-fallback `wakeAt` an event/step suspend now carries, and the store exposes no cheap bulk
+ * checkpoint scan to disambiguate — so the client shows a non-event suspend with a live worker as
+ * `running` (it flips off "no worker" the moment a worker returns) rather than guessing "sleeping".
+ * The detail view (which has the timeline) still distinguishes sleep vs in-flight step precisely.
+ */
+interface RunWaiting {
+    on: 'signal' | 'webhook' | 'child';
+    /** The token/name the run is parked on — the signal name, webhook token, or awaited child id. */
+    name: string;
+}
 type StepKind = 'local' | 'remote' | 'sleep' | 'signal';
 /**
  * The recorded result of a single step at a deterministic logical position (`seq`).
@@ -1784,6 +1805,19 @@ interface WorkflowEngineDeps {
      * one (this rearmed window for heartbeat-aware workers, or the fixed `timeoutMs` otherwise).
      */
     remoteAdvanceSilenceMs?: number | undefined;
+    /**
+     * Fallback re-drive window (ms) for a run that SUSPENDS with no natural timer — i.e. it's waiting on
+     * an EVENT to wake it (a child's completion, a signal, a remote step with no `timeoutMs`) rather than
+     * a `ctx.sleep`. Those events re-drive the run directly; but if the wake is LOST (the delivering pod
+     * crashed / rolled mid-handoff), the run would otherwise sit `suspended` forever with `wakeAt: null` —
+     * invisible to both the timer poller (no `wakeAt`) and crash-recovery (no lease). This stamps a
+     * fallback `wakeAt` so {@link resumeDueTimers} re-drives it after the window; the re-drive is an
+     * idempotent replay (a still-pending dependency re-suspends via the checkpoint guard, a settled one
+     * advances), so it's a safe self-heal, not a retry that can double-dispatch. The primary event path
+     * still wins first for a healthy run (it re-drives long before this fires), so this only ever fires
+     * for a genuinely-orphaned run. Default 5min; set `0` to disable (the prior wake-forever behavior).
+     */
+    reconcileMs?: number | undefined;
     /**
      * Build the public callback URL for a `ctx.webhook()` token (e.g.
      * ``(t) => `https://api.example.com/durable/webhooks/${t}` ``). Populates
@@ -1859,6 +1893,7 @@ declare class WorkflowEngine {
     private readonly leaseMs;
     private readonly maxRecoveryAttempts?;
     private readonly remoteAdvanceSilenceMs?;
+    private readonly reconcileMs;
     private readonly webhookUrl?;
     private readonly traceparent?;
     private readonly context?;
@@ -2324,6 +2359,13 @@ declare class WorkflowEngine {
      * keeps its own lease handling (the TS executor's `finally`, the remote path's caller).
      */
     private settleRun;
+    /**
+     * A wakeAt to persist on a suspend: the natural timer if the turn produced one (a `ctx.sleep`, a
+     * remote-step deadline), else the {@link reconcileMs} fallback so an event-waiting run (child/signal/
+     * timeout-less remote step) can't be orphaned forever if its wake is lost. `undefined` only when the
+     * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
+     */
+    private reconcileWakeAt;
     private runRemoteExecution;
     /**
      * Apply a remote workflow turn's {@link WorkflowDecision}: persist the local steps it ran, then
@@ -2732,6 +2774,13 @@ declare class RemoteWorkflowExecutor implements WorkflowExecutor {
     dispatch(run: WorkflowRun, history: HistoryEvent[], taskId: string, pendingSignals?: WorkflowTask['pendingSignals']): Promise<void>;
 }
 
+/** A run as returned by the gateway's list — the durable run plus an optional {@link RunWaiting}
+ *  descriptor the control plane resolves (what a suspended run is parked on), so the dashboard can
+ *  name the wait in a list row without fetching each run's timeline. Additive: `waiting` is absent
+ *  on a non-parked run and on gateways/versions that don't compute it. */
+type RunListItem = WorkflowRun & {
+    waiting?: RunWaiting | undefined;
+};
 /** Which durable topology a gateway speaks for — surfaced in the dashboard so an operator can tell a
  *  control plane from a tenant at a glance (the store-backed gateway is the operator; the proxy is a
  *  tenant). Cheap, synchronous, local knowledge — no round-trip. */
@@ -2759,7 +2808,10 @@ interface RunGateway {
     /** This deployment's durable role (control plane vs tenant) — synchronous local metadata. */
     topology(): DurableTopology;
     getRunDetail(runId: string): Promise<RunDetail | null>;
-    listRuns(query: RunQuery): Promise<WorkflowRun[]>;
+    /** List runs, each optionally carrying a {@link RunWaiting} descriptor (what a suspended run is
+     *  parked on). The store-backed gateway resolves `waiting`; a proxy relays whatever the control
+     *  plane sent. */
+    listRuns(query: RunQuery): Promise<RunListItem[]>;
     /** Per-group worker health (queue backlog + live worker heartbeats). On the control plane this is
      *  every group; over a tenant proxy the operator scopes it to the tenant's own groups. */
     workerHealth(): Promise<GroupHealth[]>;
@@ -2775,6 +2827,25 @@ interface RunGateway {
     subscribe(runId: string, onEvent: (event: EngineEvent) => void): () => void;
 }
 
+/**
+ * Resolve WHAT a suspended run is parked on from the token of the {@link SignalWaiter} it registered.
+ * The token prefix carries the kind — no extra store lookup and no new persisted field. Used by the
+ * store-backed run gateway to stamp {@link RunWaiting} onto each listed run so the dashboard can name
+ * the wait in a row without fetching that run's timeline.
+ */
+declare function classifyWaiterToken(token: string): RunWaiting;
+/**
+ * Resolve a suspended run's {@link RunWaiting} from the pending signal waiters (indexed by `runId`).
+ * Event-only by design (see {@link RunWaiting}): a `waitForSignal`/`waitForEvent`/webhook/awaited-child
+ * suspend registers a waiter and gets named here; every other suspend (a bare `ctx.sleep`, an in-flight
+ * remote step, a reconcile-parked orphan) returns `undefined`, so the client layers its own display
+ * state (no-worker, singleton, running) on top — none of which can be told apart from `wakeAt` alone.
+ */
+declare function resolveRunWaiting(run: WorkflowRun, waiterByRun: ReadonlyMap<string, SignalWaiter>): RunWaiting | undefined;
+/** Index signal waiters by `runId`, keeping the first seen per run (a run parks on one waiter at a
+ *  time in the sequential case; the earliest is the one it's blocked on). */
+declare function indexWaitersByRun(waiters: readonly SignalWaiter[]): Map<string, SignalWaiter>;
+
 /**
  * Transforms a payload value as it crosses the store boundary — e.g. encrypt-at-rest, compress, or
  * redact PII. `decode` must be the exact inverse of `encode`. Both are synchronous (use a local
@@ -2838,6 +2909,9 @@ declare class CodecStateStore implements StateStore {
 declare function eventPrefix(name: string): string;
 /** Build the unique waiter token for one `waitForEvent` call (name + match + run position). */
 declare function eventToken(name: string, match: Record<string, unknown> | undefined, runId: string, seq: number): string;
+/** The event name embedded in an event waiter token (the 2nd `:`-segment is the base64 name), so a
+ *  dashboard can show "waiting on event `<name>`" instead of the opaque token. */
+declare function eventNameOf(token: string): string;
 /** The match criteria embedded in an event waiter token (the 3rd `:`-segment is the base64 match). */
 declare function eventMatchOf(token: string): Record<string, unknown>;
 /** Whether `payload` satisfies a waiter's `match`: every match key deep-equals the payload's value. */
@@ -3152,4 +3226,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, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, 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, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventPrefix, eventToken, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, 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, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type DurableTopology, type DurableWebhook, DurableWorkflow, 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, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RunAttributeRow, type RunDetail, type RunDispatcher, type RunGateway, type RunListItem, type RunQuery, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunStatus, type RunWaiting, STATE_STORE, STATE_STORE_CANONICAL, type ScheduledWorkflow, type SearchAttributes, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StartOptions, type StartRunMessage, type StateStore, type StepCheckpoint, type StepConfig, type StepDef, type StepDispatchOpts, type StepError, type StepEvent, type StepHandler, type StepInterceptor, type StepInvocation, type StepKind, type StepLogger, type StepOptions, type StepRef, type StepResult, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, WORKFLOW_NAME_KEY, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerHeartbeat, type WorkerStatus, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, applyAttributeQuery, attributeColumnFor, attributeOperand, bindWorkflowClass, breakpointToken, classifyWaiterToken, collectMetrics, createStepLogger, currentWorkflowCtx, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, indexWaitersByRun, matchesAttributes, normalizeAttributeRows, parseDuration, prevCronFireMs, resolveRunWaiting, runInWorkflowCtx, runSchedules, runStepHandler, sanitizeQueueToken, scheduledRunId, sqlComparator, stepConfigOf, stepId, stepNameOf, tenantGroup, workflowName };

package/dist/index.js

@@ -780,6 +780,14 @@ function eventToken(name, match, runId, seq) {
   return `${eventPrefix(name)}${enc(JSON.stringify(match ?? {}))}:${runId}#${seq}`;
 }
 __name(eventToken, "eventToken");
+function eventNameOf(token) {
+  try {
+    return dec(token.split(":")[1] ?? "");
+  } catch {
+    return token;
+  }
+}
+__name(eventNameOf, "eventNameOf");
 function eventMatchOf(token) {
   try {
     return JSON.parse(dec(token.split(":")[2] ?? ""));
@@ -1720,6 +1728,7 @@ var WorkflowEngine = class {
   leaseMs;
   maxRecoveryAttempts;
   remoteAdvanceSilenceMs;
+  reconcileMs;
   webhookUrl;
   traceparent;
   context;
@@ -1790,6 +1799,7 @@ var WorkflowEngine = class {
     this.leaseMs = deps.leaseMs ?? 3e4;
     this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
     this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
+    this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -3134,7 +3144,7 @@ var WorkflowEngine = class {
     }
     await this.store.updateRun(run.id, {
       status: "suspended",
-      wakeAt: outcome.wakeAt,
+      wakeAt: this.reconcileWakeAt(outcome.wakeAt),
       updatedAt
     });
     this.emit({
@@ -3148,6 +3158,16 @@ var WorkflowEngine = class {
       status: "suspended"
     };
   }
+  /**
+  * A wakeAt to persist on a suspend: the natural timer if the turn produced one (a `ctx.sleep`, a
+  * remote-step deadline), else the {@link reconcileMs} fallback so an event-waiting run (child/signal/
+  * timeout-less remote step) can't be orphaned forever if its wake is lost. `undefined` only when the
+  * fallback is disabled (`reconcileMs: 0`). See {@link WorkflowEngineDeps.reconcileMs}.
+  */
+  reconcileWakeAt(wakeAt) {
+    if (wakeAt != null) return wakeAt;
+    return this.reconcileMs != null ? this.clock() + this.reconcileMs : void 0;
+  }
   async runRemoteExecution(run, registered) {
     if (run.status === "cancelling") {
       const error = {
@@ -4283,6 +4303,42 @@ var TERMINAL_RUN_STATUSES = [
   "dead"
 ];
 
+// src/run-waiting.ts
+var WEBHOOK_PREFIX = "wh:";
+var CHILD_PREFIX = "child:";
+var EVENT_PREFIX = "event:";
+function classifyWaiterToken(token) {
+  if (token.startsWith(WEBHOOK_PREFIX)) return {
+    on: "webhook",
+    name: token
+  };
+  if (token.startsWith(CHILD_PREFIX)) return {
+    on: "child",
+    name: token.slice(CHILD_PREFIX.length)
+  };
+  if (token.startsWith(EVENT_PREFIX)) return {
+    on: "signal",
+    name: eventNameOf(token)
+  };
+  return {
+    on: "signal",
+    name: token
+  };
+}
+__name(classifyWaiterToken, "classifyWaiterToken");
+function resolveRunWaiting(run, waiterByRun) {
+  if (run.status !== "suspended") return void 0;
+  const waiter = waiterByRun.get(run.id);
+  return waiter ? classifyWaiterToken(waiter.token) : void 0;
+}
+__name(resolveRunWaiting, "resolveRunWaiting");
+function indexWaitersByRun(waiters) {
+  const byRun = /* @__PURE__ */ new Map();
+  for (const w of waiters) if (!byRun.has(w.runId)) byRun.set(w.runId, w);
+  return byRun;
+}
+__name(indexWaitersByRun, "indexWaitersByRun");
+
 // src/codec-state-store.ts
 var CodecStateStore = class {
   static {
@@ -5037,17 +5093,21 @@ export {
   attributeOperand,
   bindWorkflowClass,
   breakpointToken,
+  classifyWaiterToken,
   collectMetrics,
   createStepLogger,
   currentWorkflowCtx,
   eventMatchOf,
   eventMatches,
+  eventNameOf,
   eventPrefix,
   eventToken,
+  indexWaitersByRun,
   matchesAttributes,
   normalizeAttributeRows,
   parseDuration,
   prevCronFireMs,
+  resolveRunWaiting,
   runInWorkflowCtx,
   runSchedules,
   runStepHandler,