@dudousxd/nestjs-durable-core 0.85.6 → 0.85.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -1242,11 +1242,28 @@ interface StateStore {
1242
1242
  */
1243
1243
  deleteRuns?(runIds: string[]): Promise<void>;
1244
1244
  getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
1245
+ /**
1246
+ * The run's checkpoints at `seqs`, in `seq` order; a seq with no checkpoint is left out, and an
1247
+ * empty `seqs` reads nothing. The engine reads a batch of one run's step results' checkpoints
1248
+ * through it, one call per batch.
1249
+ *
1250
+ * Optional: a store that omits it gets one {@link getCheckpoint} per seq.
1251
+ */
1252
+ getCheckpoints?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
1245
1253
  /**
1246
1254
  * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
1247
1255
  * being a single transaction; stores without transactions cannot give the strong guarantee.
1248
1256
  */
1249
1257
  saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
1258
+ /**
1259
+ * {@link saveCheckpoint} for many checkpoints in one call: each is written (inserted, or
1260
+ * overwriting the row at its `(runId, seq)`), in a few statements and one transaction, so a
1261
+ * rejection writes nothing. The entries name distinct rows. The engine writes a step fan's new
1262
+ * `pending` checkpoints through it before dispatching them.
1263
+ *
1264
+ * Optional: a store that omits it gets one {@link saveCheckpoint} per checkpoint.
1265
+ */
1266
+ saveCheckpoints?(checkpoints: StepCheckpoint[]): Promise<void>;
1250
1267
  /**
1251
1268
  * Overwrite the checkpoint at `(runId, seq)` with `checkpoint`, but only while the stored row is
1252
1269
  * still `pending`; resolves whether it wrote. The engine writes a dispatched step's row from two
@@ -2328,6 +2345,15 @@ interface RunConsumerOptions extends RunQueueOptions {
2328
2345
  interface Transport {
2329
2346
  /** engine → worker */
2330
2347
  dispatch(task: RemoteTask): Promise<void>;
2348
+ /**
2349
+ * {@link dispatch} for many tasks in a few broker calls. Rejects if any task may not have been
2350
+ * dispatched (some may have been: the engine then dispatches the batch again one task at a time,
2351
+ * and a task delivered twice runs twice, as any redelivery does). The engine sends a step fan's
2352
+ * new steps through it.
2353
+ *
2354
+ * Optional: a transport that omits it gets one {@link dispatch} per task.
2355
+ */
2356
+ dispatchMany?(tasks: RemoteTask[]): Promise<void>;
2331
2357
  /** worker → engine: a step finished (ok or error). */
2332
2358
  onResult(handler: (result: StepResult) => Promise<void>): void;
2333
2359
  /** worker → engine: liveness signal for an in-flight long step. */
@@ -4679,6 +4705,23 @@ declare class WorkflowEngine {
4679
4705
  private readonly wakeTurns;
4680
4706
  /** Re-checks scheduled for runs whose wake found another instance's lease (see {@link execute}). */
4681
4707
  private readonly leaseRetries;
4708
+ /**
4709
+ * Runs whose scheduled re-check resumes them whatever happened meanwhile. Without an entry the
4710
+ * re-check only stood for fan wakes kept as requests, and resumes the run only if a request is
4711
+ * still there: the turn that held the lease takes them once it ends (see {@link retryDroppedWake}).
4712
+ */
4713
+ private readonly unconditionalRechecks;
4714
+ /** Runs a generic wake request was written for in the current re-check cycle (see {@link execute}). */
4715
+ private readonly genericWakeRequested;
4716
+ /** Why each run is being woken on this instance, until the turn that answers it starts. */
4717
+ private readonly wakeReasons;
4718
+ /**
4719
+ * The step fans each executing turn on this instance read with nothing in flight: first seq -> the
4720
+ * highest seq read. Written by {@link callRemoteAll}, read once the turn ends.
4721
+ */
4722
+ private readonly turnSettledFans;
4723
+ /** The wake requests each executing turn on this instance serves (see {@link noteServedWakes}). */
4724
+ private readonly turnServedWakes;
4682
4725
  /**
4683
4726
  * Every run turn and child start this instance takes on itself, under one budget of
4684
4727
  * {@link LOCAL_RUN_CONCURRENCY}: the runs it dispatches to itself, a fan's deferred child starts,
@@ -5003,6 +5046,8 @@ declare class WorkflowEngine {
5003
5046
  * terminal too.
5004
5047
  */
5005
5048
  resume(runId: string): Promise<RunResult>;
5049
+ /** Record why `runId` is being woken: a step fan's barrier opening, or (`undefined`) anything else. */
5050
+ private noteWakeReason;
5006
5051
  /**
5007
5052
  * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
5008
5053
  * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
@@ -5742,19 +5787,48 @@ declare class WorkflowEngine {
5742
5787
  /**
5743
5788
  * Keep a wake that found `runId`'s lease held by a turn executing elsewhere, durably, so that turn
5744
5789
  * runs again once it ends instead of suspending on a snapshot that predates what the wake brought
5745
- * (a signal, a child's completion). The request is a buffered signal on a token no workflow waits
5746
- * on; the holder takes it after it releases the lease ({@link honorWakeRequests}).
5790
+ * (a signal, a child's completion). The request is a buffered event under a name no workflow waits
5791
+ * on. It stays until a turn that started after it has settled: the holder looks at it after it
5792
+ * releases the lease ({@link honorWakeRequests}), and the turn that serves it drops it.
5747
5793
  *
5748
5794
  * Written first and looked at second, against a holder that releases first and looks second:
5749
5795
  * whichever look runs last sees the other side's write. So when the run is no longer executing by
5750
- * the time this re-reads it, the holder may have looked already, and this side takes the request
5751
- * and wakes the run itself once the lease is free.
5796
+ * the time this re-reads it, the holder may have looked already, and this side wakes the run
5797
+ * itself once the lease is free ({@link retryDroppedWake}). While the holder still runs, the run is
5798
+ * made due when the holder's lease runs out, so a holder that goes down before it settles leaves
5799
+ * the run to any instance's timer poll; a holder that settles sets the run's timer itself.
5752
5800
  */
5753
5801
  private requestWakeAfterTurn;
5754
- /** After a turn that suspended released its lease: run again if a wake was kept for it. */
5802
+ /**
5803
+ * After a turn that suspended released its lease: drop the wakes it served, and run again if a
5804
+ * wake was kept for it meanwhile, unless every such wake was a fan wake this turn already saw: it
5805
+ * read that fan with nothing in flight, at least as far as the batch that opened its barrier.
5806
+ * The run is made due before it is woken, so if this instance goes down before that turn runs,
5807
+ * the timer poll of another instance runs it once this instance's hold on it would have lapsed.
5808
+ */
5755
5809
  private honorWakeRequests;
5756
- /** Take every wake request kept for `runId`; true when there was one. */
5757
- private takeWakeRequests;
5810
+ /**
5811
+ * The wake requests kept for `runId`. With `legacy`, also those an older engine kept as buffered
5812
+ * signals, which are taken as they are read.
5813
+ */
5814
+ private listWakeRequests;
5815
+ /** Delete `requests` (the ones kept as buffered events). */
5816
+ private dropWakeRequests;
5817
+ /**
5818
+ * Record, for the turn executing `runId` here, the wakes kept for the run so far. Called before the
5819
+ * turn reads the run's state, so the turn serves them: they are dropped once it has settled, and
5820
+ * until then stay for whoever runs the run next.
5821
+ */
5822
+ private noteServedWakes;
5823
+ /**
5824
+ * Right after a turn of `runId` wrote its suspension, while it still holds the lease: if a wake
5825
+ * was kept for the run during the turn that the turn did not see, keep the run due when the lease
5826
+ * runs out. The suspension overwrote the timer the instance keeping the wake set, and this instance
5827
+ * may go down before it looks at the wake once it has released the lease.
5828
+ */
5829
+ private keepDueForKeptWakes;
5830
+ /** Bring a suspended run's timer forward to `at` (never later than the one it has). */
5831
+ private makeDueBy;
5758
5832
  /**
5759
5833
  * A wake that found the run leased by another instance is dropped, and normally that is fine: the
5760
5834
  * holder's turn either sees what the wake wrote, or re-checks once it releases the lease
@@ -6101,6 +6175,11 @@ declare class WorkflowEngine {
6101
6175
  * capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
6102
6176
  private dueBlockedRuns;
6103
6177
  private callRemote;
6178
+ /**
6179
+ * Whether a `pending` step a turn just read only waits for its result: {@link callRemote} would
6180
+ * suspend on it without writing (no redispatch deadline to stamp, the one stamped not yet due).
6181
+ */
6182
+ private stepIsWaiting;
6104
6183
  /**
6105
6184
  * `ctx.all` over a `@Step`: one durable step per input, dispatched together, joined once. The ctx
6106
6185
  * reserves the whole position block up front, so replay re-derives the same seqs.
@@ -6113,7 +6192,11 @@ declare class WorkflowEngine {
6113
6192
  * barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
6114
6193
  */
6115
6194
  private callRemoteAll;
6116
- /** Write the `pending` checkpoints of a step fan's new steps, then dispatch them. */
6195
+ /**
6196
+ * Write the `pending` checkpoints of a step fan's new steps, then dispatch them: one
6197
+ * {@link StateStore.saveCheckpoints} call and one {@link TransportPool.dispatchMany} for the
6198
+ * batch, where the store and transport have them.
6199
+ */
6117
6200
  private sendStepFan;
6118
6201
  /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
6119
6202
  private noteSettledHere;
@@ -6128,6 +6211,12 @@ declare class WorkflowEngine {
6128
6211
  * call rejecting means it wrote nothing, so the entries are then written one by one.
6129
6212
  */
6130
6213
  private savePendingCheckpoints;
6214
+ /**
6215
+ * The checkpoints of one run at distinct `seqs`, each as its own outcome: one
6216
+ * {@link StateStore.getCheckpoints} call when the store has it, else one read each. The batch
6217
+ * call rejecting falls back to one read each, so a failing read fails only its own entry.
6218
+ */
6219
+ private readCheckpoints;
6131
6220
  /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
6132
6221
  * dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
6133
6222
  * {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
@@ -6147,9 +6236,10 @@ declare class WorkflowEngine {
6147
6236
  *
6148
6237
  * Results of one run are settled in batches: the first starts a batch, and the ones that arrive
6149
6238
  * while it is being written form the next. Under load a wide fan's results are written by one
6150
- * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked once
6151
- * per batch, not once per result. A result resolves only once its own write has committed, so the
6152
- * transport acknowledges nothing that is not durable yet.
6239
+ * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked only
6240
+ * by a batch with no more of the fan's results queued behind it. A result resolves only once its
6241
+ * own write has committed, so the transport acknowledges nothing that is not durable yet. How
6242
+ * large a batch gets is bounded by how many results the transport hands over at once.
6153
6243
  */
6154
6244
  private completeRemoteResult;
6155
6245
  /** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
@@ -6158,6 +6248,11 @@ declare class WorkflowEngine {
6158
6248
  * Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
6159
6249
  * that resume replays every write of the batch, so a second would only replay it again. A result
6160
6250
  * whose read or write failed resolves its error, and the transport redelivers just that one.
6251
+ *
6252
+ * `queuedIn(from, to)` says whether a result for a seq in that range is already waiting for this
6253
+ * run's next batch on this instance. A fan with one waiting is not asked its barrier: that result
6254
+ * asks it once its own batch is written (as a settle, or as a redelivery of a settled step), so
6255
+ * under a backlog the barrier is read once per drained queue rather than once per batch.
6161
6256
  */
6162
6257
  private completeRemoteResults;
6163
6258
  /**
@@ -6172,7 +6267,8 @@ declare class WorkflowEngine {
6172
6267
  * retry needs the parent to schedule it). Without it every result would replay the whole parent,
6173
6268
  * which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
6174
6269
  * for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
6175
- * re-suspends, a lost one strands the run.
6270
+ * re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
6271
+ * that result (see {@link completeRemoteResults}).
6176
6272
  */
6177
6273
  private stepFanStillRunning;
6178
6274
  /** How many steps of a step fan's seq range are still `pending`. */
@@ -6893,6 +6989,10 @@ declare class CodecStateStore implements StateStore {
6893
6989
  readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
6894
6990
  /** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
6895
6991
  readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
6992
+ /** Encodes each checkpoint written. Bound only when the inner store has it. */
6993
+ readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
6994
+ /** Decodes each checkpoint read. Bound only when the inner store has it. */
6995
+ readonly getCheckpoints?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
6896
6996
  /** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
6897
6997
  readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
6898
6998
  /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
@@ -7438,7 +7538,9 @@ declare class InMemoryStateStore implements StateStore {
7438
7538
  deleteRuns(runIds: string[]): Promise<void>;
7439
7539
  pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
7440
7540
  getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
7541
+ getCheckpoints(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
7441
7542
  saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
7543
+ saveCheckpoints(checkpoints: StepCheckpoint[]): Promise<void>;
7442
7544
  saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
7443
7545
  saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
7444
7546
  listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
package/dist/index.d.ts CHANGED
@@ -1242,11 +1242,28 @@ interface StateStore {
1242
1242
  */
1243
1243
  deleteRuns?(runIds: string[]): Promise<void>;
1244
1244
  getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
1245
+ /**
1246
+ * The run's checkpoints at `seqs`, in `seq` order; a seq with no checkpoint is left out, and an
1247
+ * empty `seqs` reads nothing. The engine reads a batch of one run's step results' checkpoints
1248
+ * through it, one call per batch.
1249
+ *
1250
+ * Optional: a store that omits it gets one {@link getCheckpoint} per seq.
1251
+ */
1252
+ getCheckpoints?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
1245
1253
  /**
1246
1254
  * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
1247
1255
  * being a single transaction; stores without transactions cannot give the strong guarantee.
1248
1256
  */
1249
1257
  saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
1258
+ /**
1259
+ * {@link saveCheckpoint} for many checkpoints in one call: each is written (inserted, or
1260
+ * overwriting the row at its `(runId, seq)`), in a few statements and one transaction, so a
1261
+ * rejection writes nothing. The entries name distinct rows. The engine writes a step fan's new
1262
+ * `pending` checkpoints through it before dispatching them.
1263
+ *
1264
+ * Optional: a store that omits it gets one {@link saveCheckpoint} per checkpoint.
1265
+ */
1266
+ saveCheckpoints?(checkpoints: StepCheckpoint[]): Promise<void>;
1250
1267
  /**
1251
1268
  * Overwrite the checkpoint at `(runId, seq)` with `checkpoint`, but only while the stored row is
1252
1269
  * still `pending`; resolves whether it wrote. The engine writes a dispatched step's row from two
@@ -2328,6 +2345,15 @@ interface RunConsumerOptions extends RunQueueOptions {
2328
2345
  interface Transport {
2329
2346
  /** engine → worker */
2330
2347
  dispatch(task: RemoteTask): Promise<void>;
2348
+ /**
2349
+ * {@link dispatch} for many tasks in a few broker calls. Rejects if any task may not have been
2350
+ * dispatched (some may have been: the engine then dispatches the batch again one task at a time,
2351
+ * and a task delivered twice runs twice, as any redelivery does). The engine sends a step fan's
2352
+ * new steps through it.
2353
+ *
2354
+ * Optional: a transport that omits it gets one {@link dispatch} per task.
2355
+ */
2356
+ dispatchMany?(tasks: RemoteTask[]): Promise<void>;
2331
2357
  /** worker → engine: a step finished (ok or error). */
2332
2358
  onResult(handler: (result: StepResult) => Promise<void>): void;
2333
2359
  /** worker → engine: liveness signal for an in-flight long step. */
@@ -4679,6 +4705,23 @@ declare class WorkflowEngine {
4679
4705
  private readonly wakeTurns;
4680
4706
  /** Re-checks scheduled for runs whose wake found another instance's lease (see {@link execute}). */
4681
4707
  private readonly leaseRetries;
4708
+ /**
4709
+ * Runs whose scheduled re-check resumes them whatever happened meanwhile. Without an entry the
4710
+ * re-check only stood for fan wakes kept as requests, and resumes the run only if a request is
4711
+ * still there: the turn that held the lease takes them once it ends (see {@link retryDroppedWake}).
4712
+ */
4713
+ private readonly unconditionalRechecks;
4714
+ /** Runs a generic wake request was written for in the current re-check cycle (see {@link execute}). */
4715
+ private readonly genericWakeRequested;
4716
+ /** Why each run is being woken on this instance, until the turn that answers it starts. */
4717
+ private readonly wakeReasons;
4718
+ /**
4719
+ * The step fans each executing turn on this instance read with nothing in flight: first seq -> the
4720
+ * highest seq read. Written by {@link callRemoteAll}, read once the turn ends.
4721
+ */
4722
+ private readonly turnSettledFans;
4723
+ /** The wake requests each executing turn on this instance serves (see {@link noteServedWakes}). */
4724
+ private readonly turnServedWakes;
4682
4725
  /**
4683
4726
  * Every run turn and child start this instance takes on itself, under one budget of
4684
4727
  * {@link LOCAL_RUN_CONCURRENCY}: the runs it dispatches to itself, a fan's deferred child starts,
@@ -5003,6 +5046,8 @@ declare class WorkflowEngine {
5003
5046
  * terminal too.
5004
5047
  */
5005
5048
  resume(runId: string): Promise<RunResult>;
5049
+ /** Record why `runId` is being woken: a step fan's barrier opening, or (`undefined`) anything else. */
5050
+ private noteWakeReason;
5006
5051
  /**
5007
5052
  * {@link resume} for every IMPLICIT wake-up — a delivered signal/child completion, a late step
5008
5053
  * result, a due timer, a redelivered dispatch, a queue-slot wake. A `failed` run is terminal to
@@ -5742,19 +5787,48 @@ declare class WorkflowEngine {
5742
5787
  /**
5743
5788
  * Keep a wake that found `runId`'s lease held by a turn executing elsewhere, durably, so that turn
5744
5789
  * runs again once it ends instead of suspending on a snapshot that predates what the wake brought
5745
- * (a signal, a child's completion). The request is a buffered signal on a token no workflow waits
5746
- * on; the holder takes it after it releases the lease ({@link honorWakeRequests}).
5790
+ * (a signal, a child's completion). The request is a buffered event under a name no workflow waits
5791
+ * on. It stays until a turn that started after it has settled: the holder looks at it after it
5792
+ * releases the lease ({@link honorWakeRequests}), and the turn that serves it drops it.
5747
5793
  *
5748
5794
  * Written first and looked at second, against a holder that releases first and looks second:
5749
5795
  * whichever look runs last sees the other side's write. So when the run is no longer executing by
5750
- * the time this re-reads it, the holder may have looked already, and this side takes the request
5751
- * and wakes the run itself once the lease is free.
5796
+ * the time this re-reads it, the holder may have looked already, and this side wakes the run
5797
+ * itself once the lease is free ({@link retryDroppedWake}). While the holder still runs, the run is
5798
+ * made due when the holder's lease runs out, so a holder that goes down before it settles leaves
5799
+ * the run to any instance's timer poll; a holder that settles sets the run's timer itself.
5752
5800
  */
5753
5801
  private requestWakeAfterTurn;
5754
- /** After a turn that suspended released its lease: run again if a wake was kept for it. */
5802
+ /**
5803
+ * After a turn that suspended released its lease: drop the wakes it served, and run again if a
5804
+ * wake was kept for it meanwhile, unless every such wake was a fan wake this turn already saw: it
5805
+ * read that fan with nothing in flight, at least as far as the batch that opened its barrier.
5806
+ * The run is made due before it is woken, so if this instance goes down before that turn runs,
5807
+ * the timer poll of another instance runs it once this instance's hold on it would have lapsed.
5808
+ */
5755
5809
  private honorWakeRequests;
5756
- /** Take every wake request kept for `runId`; true when there was one. */
5757
- private takeWakeRequests;
5810
+ /**
5811
+ * The wake requests kept for `runId`. With `legacy`, also those an older engine kept as buffered
5812
+ * signals, which are taken as they are read.
5813
+ */
5814
+ private listWakeRequests;
5815
+ /** Delete `requests` (the ones kept as buffered events). */
5816
+ private dropWakeRequests;
5817
+ /**
5818
+ * Record, for the turn executing `runId` here, the wakes kept for the run so far. Called before the
5819
+ * turn reads the run's state, so the turn serves them: they are dropped once it has settled, and
5820
+ * until then stay for whoever runs the run next.
5821
+ */
5822
+ private noteServedWakes;
5823
+ /**
5824
+ * Right after a turn of `runId` wrote its suspension, while it still holds the lease: if a wake
5825
+ * was kept for the run during the turn that the turn did not see, keep the run due when the lease
5826
+ * runs out. The suspension overwrote the timer the instance keeping the wake set, and this instance
5827
+ * may go down before it looks at the wake once it has released the lease.
5828
+ */
5829
+ private keepDueForKeptWakes;
5830
+ /** Bring a suspended run's timer forward to `at` (never later than the one it has). */
5831
+ private makeDueBy;
5758
5832
  /**
5759
5833
  * A wake that found the run leased by another instance is dropped, and normally that is fine: the
5760
5834
  * holder's turn either sees what the wake wrote, or re-checks once it releases the lease
@@ -6101,6 +6175,11 @@ declare class WorkflowEngine {
6101
6175
  * capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
6102
6176
  private dueBlockedRuns;
6103
6177
  private callRemote;
6178
+ /**
6179
+ * Whether a `pending` step a turn just read only waits for its result: {@link callRemote} would
6180
+ * suspend on it without writing (no redispatch deadline to stamp, the one stamped not yet due).
6181
+ */
6182
+ private stepIsWaiting;
6104
6183
  /**
6105
6184
  * `ctx.all` over a `@Step`: one durable step per input, dispatched together, joined once. The ctx
6106
6185
  * reserves the whole position block up front, so replay re-derives the same seqs.
@@ -6113,7 +6192,11 @@ declare class WorkflowEngine {
6113
6192
  * barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
6114
6193
  */
6115
6194
  private callRemoteAll;
6116
- /** Write the `pending` checkpoints of a step fan's new steps, then dispatch them. */
6195
+ /**
6196
+ * Write the `pending` checkpoints of a step fan's new steps, then dispatch them: one
6197
+ * {@link StateStore.saveCheckpoints} call and one {@link TransportPool.dispatchMany} for the
6198
+ * batch, where the store and transport have them.
6199
+ */
6117
6200
  private sendStepFan;
6118
6201
  /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
6119
6202
  private noteSettledHere;
@@ -6128,6 +6211,12 @@ declare class WorkflowEngine {
6128
6211
  * call rejecting means it wrote nothing, so the entries are then written one by one.
6129
6212
  */
6130
6213
  private savePendingCheckpoints;
6214
+ /**
6215
+ * The checkpoints of one run at distinct `seqs`, each as its own outcome: one
6216
+ * {@link StateStore.getCheckpoints} call when the store has it, else one read each. The batch
6217
+ * call rejecting falls back to one read each, so a failing read fails only its own entry.
6218
+ */
6219
+ private readCheckpoints;
6131
6220
  /** Enqueue a remote step task to its worker group via the transport pool. Shared by the initial
6132
6221
  * dispatch, the opt-in self-heal re-dispatch (see `remoteRedispatchMs`), and the explicit
6133
6222
  * {@link redispatchPending}. Carries the current trace/context so a re-dispatch is traceable. */
@@ -6147,9 +6236,10 @@ declare class WorkflowEngine {
6147
6236
  *
6148
6237
  * Results of one run are settled in batches: the first starts a batch, and the ones that arrive
6149
6238
  * while it is being written form the next. Under load a wide fan's results are written by one
6150
- * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked once
6151
- * per batch, not once per result. A result resolves only once its own write has committed, so the
6152
- * transport acknowledges nothing that is not durable yet.
6239
+ * {@link StateStore.saveCheckpointsIfPending} call per batch, and the fan's barrier is asked only
6240
+ * by a batch with no more of the fan's results queued behind it. A result resolves only once its
6241
+ * own write has committed, so the transport acknowledges nothing that is not durable yet. How
6242
+ * large a batch gets is bounded by how many results the transport hands over at once.
6153
6243
  */
6154
6244
  private completeRemoteResult;
6155
6245
  /** Settle `queue` (a run's queued results) batch by batch until it is empty, then retire it. */
@@ -6158,6 +6248,11 @@ declare class WorkflowEngine {
6158
6248
  * Settle a batch of one run's step results. At most one of them resolves `true` (resume the run):
6159
6249
  * that resume replays every write of the batch, so a second would only replay it again. A result
6160
6250
  * whose read or write failed resolves its error, and the transport redelivers just that one.
6251
+ *
6252
+ * `queuedIn(from, to)` says whether a result for a seq in that range is already waiting for this
6253
+ * run's next batch on this instance. A fan with one waiting is not asked its barrier: that result
6254
+ * asks it once its own batch is written (as a settle, or as a redelivery of a settled step), so
6255
+ * under a backlog the barrier is read once per drained queue rather than once per batch.
6161
6256
  */
6162
6257
  private completeRemoteResults;
6163
6258
  /**
@@ -6172,7 +6267,8 @@ declare class WorkflowEngine {
6172
6267
  * retry needs the parent to schedule it). Without it every result would replay the whole parent,
6173
6268
  * which makes a fan of N steps cost O(N²) checkpoint reads. `barriers` holds the answer per fan
6174
6269
  * for the rest of a batch. A barrier that cannot be read counts as open: a spare resume replays and
6175
- * re-suspends, a lost one strands the run.
6270
+ * re-suspends, a lost one strands the run. A fan with a result waiting in `queuedIn` is left to
6271
+ * that result (see {@link completeRemoteResults}).
6176
6272
  */
6177
6273
  private stepFanStillRunning;
6178
6274
  /** How many steps of a step fan's seq range are still `pending`. */
@@ -6893,6 +6989,10 @@ declare class CodecStateStore implements StateStore {
6893
6989
  readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
6894
6990
  /** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
6895
6991
  readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
6992
+ /** Encodes each checkpoint written. Bound only when the inner store has it. */
6993
+ readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
6994
+ /** Decodes each checkpoint read. Bound only when the inner store has it. */
6995
+ readonly getCheckpoints?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
6896
6996
  /** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
6897
6997
  readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
6898
6998
  /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
@@ -7438,7 +7538,9 @@ declare class InMemoryStateStore implements StateStore {
7438
7538
  deleteRuns(runIds: string[]): Promise<void>;
7439
7539
  pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
7440
7540
  getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
7541
+ getCheckpoints(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
7441
7542
  saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
7543
+ saveCheckpoints(checkpoints: StepCheckpoint[]): Promise<void>;
7442
7544
  saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
7443
7545
  saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
7444
7546
  listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;