@dudousxd/nestjs-durable-core 0.40.1 → 0.42.0

package/dist/index.d.cts

@@ -683,13 +683,17 @@ interface HistoryEvent {
 }
 /** A decision the workflow function produced at a `seq` that was not yet in history. */
 type WorkflowCommand = 
-/** `ctx.call(remoteStep, input)` — dispatch a remote step and await it. */
+/** `ctx.call(remoteStep, input)` — dispatch a remote step and await it. A worker's
+ *  `ctx.gather_calls([...])` fan-out tags every dispatched call with the same `parallelGroup` so the
+ *  dashboard renders the remote steps as one parallel fan (parity with the gathered `recordStep` /
+ *  `startChild` tags). Undefined for a lone sequential `ctx.call`. */
 {
     kind: 'call';
     seq: number;
     name: string;
     group: string;
     input: unknown;
+    parallelGroup?: string;
 }
 /** `ctx.step(name, body)` — a LOCAL step the worker already ran this turn; the engine persists its
  *  result so replay returns it instead of re-running (durability for side-effectful work).
@@ -833,6 +837,58 @@ interface Transport {
      *  still surfaces. Pairs with {@link groupHealth}. */
     listWorkerGroups?(): Promise<string[]>;
 }
+/** How a worker decides its concurrency, carried in {@link WorkerStatus} so a dashboard can tell a
+ *  fixed knob from a self-regulating one (and, for the latter, where the controller currently sits). */
+interface WorkerConcurrencyStatus {
+    /** `fixed` = the configured `concurrency` number, never moves. `adaptive` = the controller tunes it. */
+    mode: 'fixed' | 'adaptive';
+    /** The concurrency ceiling in effect right now (fixed: the configured value; adaptive: the live limit). */
+    limit: number;
+    /** Adaptive only — the floor the controller won't go below. */
+    min?: number;
+    /** Adaptive only — the ceiling the controller won't exceed. */
+    max?: number;
+}
+/** The adaptive controller's most recent limit change — the "why did it move" a dashboard shows so an
+ *  auto-tuner isn't a black box. Absent until the controller first adjusts (or for a fixed worker). */
+interface WorkerAdjust {
+    /** Epoch ms of the adjustment. */
+    at: number;
+    /** Limit before this change. */
+    from: number;
+    /** Limit after this change. */
+    to: number;
+    /** Why it moved: `ram_ceiling` (hard brake), `backpressure` (errors/stall), `grow` (had headroom),
+     *  `shrink` (latency gradient showed queuing), `cpu_ceiling`. */
+    reason: 'ram_ceiling' | 'cpu_ceiling' | 'backpressure' | 'grow' | 'shrink';
+}
+/** A live snapshot of a worker's execution state, carried in the worker-liveness heartbeat (so it
+ *  rides the existing TTL'd key — no extra round-trip) and surfaced per worker in the dashboard. Every
+ *  field beyond {@link concurrency}/{@link inFlight} is best-effort: a field a runtime can't measure is
+ *  simply omitted. The shape is shared by the TS and Python SDKs so a mixed-language group reports
+ *  uniformly. */
+interface WorkerStatus {
+    /** Which SDK is running this worker — `node` (TS) or `python`. */
+    runtime?: 'node' | 'python';
+    /** The worker's concurrency knob and its live ceiling. */
+    concurrency: WorkerConcurrencyStatus;
+    /** Tasks executing right now (0..limit). With `limit`, this is the saturation a dashboard charts. */
+    inFlight: number;
+    /** Resident set size in bytes, if the runtime can read it. */
+    rssBytes?: number;
+    /** The process memory ceiling in bytes (cgroup `memory.max`, else host total), if known. */
+    rssLimitBytes?: number;
+    /** RSS as a percent of {@link rssLimitBytes} (0..100) — what the adaptive RAM brake watches. */
+    rssPct?: number;
+    /** Process CPU utilisation percent over the last control tick (0..100×cores), if measured. */
+    cpuPct?: number;
+    /** Completed tasks per minute over the recent window — the controller's throughput signal. */
+    throughputPerMin?: number;
+    /** p95 of recent task durations in ms — the latency a dashboard charts against the limit. */
+    p95Ms?: number;
+    /** The adaptive controller's last limit change (absent for a fixed worker or before the first move). */
+    lastAdjust?: WorkerAdjust;
+}
 /** One worker's liveness record — a TTL'd heartbeat a worker refreshes while it's consuming. Its
  *  ABSENCE (the key expired) is the signal: a worker that died or stalled stops refreshing. */
 interface WorkerHeartbeat {
@@ -842,6 +898,9 @@ interface WorkerHeartbeat {
     instanceId: string;
     /** Epoch ms of the worker's most recent heartbeat. */
     lastBeatAt: number;
+    /** The worker's live execution snapshot, when its heartbeat carries one (newer SDKs stamp a JSON
+     *  value; an older SDK's bare-timestamp heartbeat leaves this undefined). */
+    status?: WorkerStatus;
 }
 /** Per-group worker-health snapshot: how much work is queued vs. how many workers are alive to do it.
  *  The actionable alert state is `depth > 0 && liveWorkers.length === 0` — work piling up with no
@@ -2492,4 +2551,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, 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 RetentionPolicy, 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, TERMINAL_RUN_STATUSES, 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 };
+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 RetentionPolicy, 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, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, 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 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

@@ -683,13 +683,17 @@ interface HistoryEvent {
 }
 /** A decision the workflow function produced at a `seq` that was not yet in history. */
 type WorkflowCommand = 
-/** `ctx.call(remoteStep, input)` — dispatch a remote step and await it. */
+/** `ctx.call(remoteStep, input)` — dispatch a remote step and await it. A worker's
+ *  `ctx.gather_calls([...])` fan-out tags every dispatched call with the same `parallelGroup` so the
+ *  dashboard renders the remote steps as one parallel fan (parity with the gathered `recordStep` /
+ *  `startChild` tags). Undefined for a lone sequential `ctx.call`. */
 {
     kind: 'call';
     seq: number;
     name: string;
     group: string;
     input: unknown;
+    parallelGroup?: string;
 }
 /** `ctx.step(name, body)` — a LOCAL step the worker already ran this turn; the engine persists its
  *  result so replay returns it instead of re-running (durability for side-effectful work).
@@ -833,6 +837,58 @@ interface Transport {
      *  still surfaces. Pairs with {@link groupHealth}. */
     listWorkerGroups?(): Promise<string[]>;
 }
+/** How a worker decides its concurrency, carried in {@link WorkerStatus} so a dashboard can tell a
+ *  fixed knob from a self-regulating one (and, for the latter, where the controller currently sits). */
+interface WorkerConcurrencyStatus {
+    /** `fixed` = the configured `concurrency` number, never moves. `adaptive` = the controller tunes it. */
+    mode: 'fixed' | 'adaptive';
+    /** The concurrency ceiling in effect right now (fixed: the configured value; adaptive: the live limit). */
+    limit: number;
+    /** Adaptive only — the floor the controller won't go below. */
+    min?: number;
+    /** Adaptive only — the ceiling the controller won't exceed. */
+    max?: number;
+}
+/** The adaptive controller's most recent limit change — the "why did it move" a dashboard shows so an
+ *  auto-tuner isn't a black box. Absent until the controller first adjusts (or for a fixed worker). */
+interface WorkerAdjust {
+    /** Epoch ms of the adjustment. */
+    at: number;
+    /** Limit before this change. */
+    from: number;
+    /** Limit after this change. */
+    to: number;
+    /** Why it moved: `ram_ceiling` (hard brake), `backpressure` (errors/stall), `grow` (had headroom),
+     *  `shrink` (latency gradient showed queuing), `cpu_ceiling`. */
+    reason: 'ram_ceiling' | 'cpu_ceiling' | 'backpressure' | 'grow' | 'shrink';
+}
+/** A live snapshot of a worker's execution state, carried in the worker-liveness heartbeat (so it
+ *  rides the existing TTL'd key — no extra round-trip) and surfaced per worker in the dashboard. Every
+ *  field beyond {@link concurrency}/{@link inFlight} is best-effort: a field a runtime can't measure is
+ *  simply omitted. The shape is shared by the TS and Python SDKs so a mixed-language group reports
+ *  uniformly. */
+interface WorkerStatus {
+    /** Which SDK is running this worker — `node` (TS) or `python`. */
+    runtime?: 'node' | 'python';
+    /** The worker's concurrency knob and its live ceiling. */
+    concurrency: WorkerConcurrencyStatus;
+    /** Tasks executing right now (0..limit). With `limit`, this is the saturation a dashboard charts. */
+    inFlight: number;
+    /** Resident set size in bytes, if the runtime can read it. */
+    rssBytes?: number;
+    /** The process memory ceiling in bytes (cgroup `memory.max`, else host total), if known. */
+    rssLimitBytes?: number;
+    /** RSS as a percent of {@link rssLimitBytes} (0..100) — what the adaptive RAM brake watches. */
+    rssPct?: number;
+    /** Process CPU utilisation percent over the last control tick (0..100×cores), if measured. */
+    cpuPct?: number;
+    /** Completed tasks per minute over the recent window — the controller's throughput signal. */
+    throughputPerMin?: number;
+    /** p95 of recent task durations in ms — the latency a dashboard charts against the limit. */
+    p95Ms?: number;
+    /** The adaptive controller's last limit change (absent for a fixed worker or before the first move). */
+    lastAdjust?: WorkerAdjust;
+}
 /** One worker's liveness record — a TTL'd heartbeat a worker refreshes while it's consuming. Its
  *  ABSENCE (the key expired) is the signal: a worker that died or stalled stops refreshing. */
 interface WorkerHeartbeat {
@@ -842,6 +898,9 @@ interface WorkerHeartbeat {
     instanceId: string;
     /** Epoch ms of the worker's most recent heartbeat. */
     lastBeatAt: number;
+    /** The worker's live execution snapshot, when its heartbeat carries one (newer SDKs stamp a JSON
+     *  value; an older SDK's bare-timestamp heartbeat leaves this undefined). */
+    status?: WorkerStatus;
 }
 /** Per-group worker-health snapshot: how much work is queued vs. how many workers are alive to do it.
  *  The actionable alert state is `depth > 0 && liveWorkers.length === 0` — work piling up with no
@@ -2492,4 +2551,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, 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 RetentionPolicy, 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, TERMINAL_RUN_STATUSES, 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 };
+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 RetentionPolicy, 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, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type Transport, 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 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.js

@@ -2990,6 +2990,7 @@ var WorkflowEngine = class {
           error: cmd.error
         });
       } else if (cmd.kind === "call") {
+        if (await this.store.getCheckpoint(run.id, cmd.seq)) continue;
         await this.store.saveCheckpoint(stepCheckpoint({
           runId: run.id,
           seq: cmd.seq,
@@ -3001,7 +3002,11 @@ var WorkflowEngine = class {
           workerGroup: cmd.group,
           enqueuedAt: at,
           startedAt: at,
-          finishedAt: at
+          finishedAt: at,
+          // A `ctx.gather_calls([...])` fan-out stamps every dispatched `call` in the fan with the
+          // same group, so the dashboard renders the remote steps as one parallel fan (parity with
+          // the gathered `recordStep`/`startChild` tags). Undefined for a lone sequential `ctx.call`.
+          parallelGroup: cmd.parallelGroup
         }));
         await this.pool.dispatch({
           runId: run.id,