@dudousxd/nestjs-durable-core 0.85.8 → 0.85.10

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
@@ -1055,6 +1055,17 @@ interface StepCheckpoint {
1055
1055
  startedAt: Date;
1056
1056
  finishedAt: Date;
1057
1057
  }
1058
+ /** What a step's result changes on its checkpoint: see {@link StateStore.settleCheckpointsIfPending}. */
1059
+ interface StepSettlement {
1060
+ runId: string;
1061
+ seq: number;
1062
+ status: 'completed' | 'failed';
1063
+ output?: unknown;
1064
+ error?: StepError | undefined;
1065
+ events?: StepEvent[] | undefined;
1066
+ startedAt: Date;
1067
+ finishedAt: Date;
1068
+ }
1058
1069
  /**
1059
1070
  * A structured event a step (or its worker) emits while running — a log line and/or a sub-step
1060
1071
  * outcome. The dashboard renders these under the step, so you can see what happened inside a step
@@ -1250,6 +1261,17 @@ interface StateStore {
1250
1261
  * Optional: a store that omits it gets one {@link getCheckpoint} per seq.
1251
1262
  */
1252
1263
  getCheckpoints?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
1264
+ /**
1265
+ * {@link getCheckpoints} as a step result's settle reads them: the same rows, each without its
1266
+ * `input` (left out of the read, not dropped after it). A settle needs the row's status, name,
1267
+ * group and timings, never what the step was called with, and the step being settled is the one
1268
+ * whose input is still fresh: an LLM step's prompt was otherwise read back on every result. The
1269
+ * engine reads through it only when the store also has {@link settleCheckpointsIfPending}, since
1270
+ * the whole-row write it falls back to needs the input.
1271
+ *
1272
+ * Optional: a store that omits it gets {@link getCheckpoints}.
1273
+ */
1274
+ getCheckpointsForSettle?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
1253
1275
  /**
1254
1276
  * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
1255
1277
  * being a single transaction; stores without transactions cannot give the strong guarantee.
@@ -1284,6 +1306,18 @@ interface StateStore {
1284
1306
  * Optional: a store that omits it gets one {@link saveCheckpointIfPending} per entry.
1285
1307
  */
1286
1308
  saveCheckpointsIfPending?(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
1309
+ /**
1310
+ * Settle steps from their results: per entry and in input order, while the row at `(runId, seq)`
1311
+ * is still `pending`, write the entry's `status`, `output`, `error`, `events`, `startedAt` and
1312
+ * `finishedAt` (an absent one is stored empty) and leave every other column as it is stored;
1313
+ * resolves whether each entry wrote. Claims like {@link saveCheckpointsIfPending}: a later entry for
1314
+ * a row an earlier one settled loses, and a rejection writes nothing. The engine settles a batch of
1315
+ * one run's step results through it, so a step's `input` (an LLM prompt, say) is not written again
1316
+ * when its result lands.
1317
+ *
1318
+ * Optional: a store that omits it gets {@link saveCheckpointsIfPending} with the whole rows.
1319
+ */
1320
+ settleCheckpointsIfPending?(settlements: StepSettlement[]): Promise<boolean[]>;
1287
1321
  /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
1288
1322
  listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
1289
1323
  /**
@@ -1497,6 +1531,17 @@ interface StateStore {
1497
1531
  */
1498
1532
  runValueFacets?(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
1499
1533
  listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
1534
+ /**
1535
+ * {@link listCheckpoints} as a turn replays it: the same rows in the same order, except that a
1536
+ * `completed` row comes without its `input` (left out of the read, not dropped after it). Replay
1537
+ * only needs a completed step's output; a still-open or failed step keeps its input, since a
1538
+ * re-dispatch or a retry writes it again. The engine reads a run's replay snapshot through it on
1539
+ * every turn, where re-reading every finished step's input would make each turn cost the size of
1540
+ * the whole history.
1541
+ *
1542
+ * Optional: a store that omits it gets {@link listCheckpoints}.
1543
+ */
1544
+ listCheckpointsForReplay?(runId: string): Promise<StepCheckpoint[]>;
1500
1545
  /**
1501
1546
  * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
1502
1547
  * `undefined` if none. A targeted read that avoids fetching + deserializing every checkpoint just to
@@ -1527,6 +1572,16 @@ interface StateStore {
1527
1572
  * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
1528
1573
  * and counts in JS, which loads the whole run on every result of a fan.
1529
1574
  */
1575
+ /**
1576
+ * Whether any of the run's checkpoints with `fromSeq <= seq <= toSeq` has one of `statuses`: the
1577
+ * question the join barrier of a step fan actually asks on each batch of results ("is any step of
1578
+ * the fan still `pending`?"). A store reads it from the TOP of the range down and stops at the first
1579
+ * match: a fan's steps are dispatched in seq order, so its highest seqs are the last to settle, and
1580
+ * the answer comes from the first rows read instead of a count over the whole range.
1581
+ *
1582
+ * Optional: a store that omits it still works — the engine asks {@link countCheckpoints} instead.
1583
+ */
1584
+ hasCheckpoints?(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<boolean>;
1530
1585
  countCheckpoints?(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
1531
1586
  /**
1532
1587
  * The run's checkpoints aggregated into {@link CheckpointStat} buckets — one per
@@ -2008,6 +2063,9 @@ type RunRequestKind = {
2008
2063
  runId: string;
2009
2064
  group: string;
2010
2065
  query: FanPageQuery;
2066
+ } | {
2067
+ kind: 'getRun';
2068
+ runId: string;
2011
2069
  } | {
2012
2070
  kind: 'listRuns';
2013
2071
  query: RunQuery;
@@ -5485,6 +5543,8 @@ declare class WorkflowEngine {
5485
5543
  * checkpoint that is already settled, which the next turn replays past — so it cannot loop.
5486
5544
  */
5487
5545
  private redriveSettledSteps;
5546
+ /** Whether the step at `seq` is settled: a `COUNT` when the store has one, else its checkpoint. */
5547
+ private stepSettled;
5488
5548
  /**
5489
5549
  * {@link redriveSettledSteps} for a step fan: once the turn that suspended on it released its lease,
5490
5550
  * re-drive the run if no step of the fan is still `pending` — the last result landed on another
@@ -5993,6 +6053,13 @@ declare class WorkflowEngine {
5993
6053
  /** Earliest clock time a step's lease is worth LOOKING at again (`stepId` → clock ms) — the read
5994
6054
  * throttle for {@link rearmStepLease}, the step-scoped sibling of {@link decisionDeadlineRearms}. */
5995
6055
  private readonly stepLeaseRearms;
6056
+ /**
6057
+ * {@link stepLeaseRearms} for the steps of a fan this instance sent, by run: one entry per sent
6058
+ * block of consecutive seqs instead of one per step, since they share the lease stamped at send.
6059
+ */
6060
+ private readonly fanLeaseRearms;
6061
+ private noteFanLease;
6062
+ private fanLeaseLookAgainAt;
5996
6063
  /**
5997
6064
  * A step-scoped heartbeat for a durably-suspended remote step: push its LEASE forward so a worker
5998
6065
  * that is still working on it is never presumed dead and double-dispatched. The durable counterpart
@@ -6196,6 +6263,13 @@ declare class WorkflowEngine {
6196
6263
  * barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
6197
6264
  */
6198
6265
  private callRemoteAll;
6266
+ /**
6267
+ * The checkpoints of a step fan's seqs, by seq. A settled one is taken from the turn's snapshot
6268
+ * (`replay`), since nothing but a turn of the run changes it once settled; one the snapshot holds
6269
+ * `pending`, or does not hold, is read again, as {@link callRemote} does for a single step: its
6270
+ * result may have landed since. The fan's last turn so reads nothing it already read.
6271
+ */
6272
+ private fanCheckpoints;
6199
6273
  /**
6200
6274
  * Write the `pending` checkpoints of a step fan's new steps, then dispatch them: one
6201
6275
  * {@link StateStore.saveCheckpoints} call and one {@link TransportPool.dispatchMany} for the
@@ -6204,8 +6278,17 @@ declare class WorkflowEngine {
6204
6278
  private sendStepFan;
6205
6279
  /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
6206
6280
  private noteSettledHere;
6207
- /** Record `key` in a "happened here recently" map, pruning entries older than a lease. */
6281
+ /**
6282
+ * Record `key` in a "happened here recently" map and drop the entries older than a lease. A key is
6283
+ * re-inserted at the end, so the map stays in the order its keys were noted and the stale ones are
6284
+ * all at its front: pruning stops at the first fresh entry instead of walking the whole map.
6285
+ */
6208
6286
  private noteRecent;
6287
+ /**
6288
+ * The run's checkpoints as a turn replays them: {@link StateStore.listCheckpointsForReplay} when
6289
+ * the store has it (no input on a completed row), else {@link StateStore.listCheckpoints}.
6290
+ */
6291
+ private replayCheckpoints;
6209
6292
  /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
6210
6293
  private savePendingCheckpoint;
6211
6294
  /**
@@ -6215,6 +6298,14 @@ declare class WorkflowEngine {
6215
6298
  * call rejecting means it wrote nothing, so the entries are then written one by one.
6216
6299
  */
6217
6300
  private savePendingCheckpoints;
6301
+ /**
6302
+ * Settle steps of one run at distinct seqs from their results ({@link StepSettlement}s, `settled[i]`
6303
+ * being the `pending` row `settlements[i]` settles): one
6304
+ * {@link StateStore.settleCheckpointsIfPending} call when the store has it, which writes only what
6305
+ * a result changes, else the whole rows through {@link savePendingCheckpoints}. Never rejects as a
6306
+ * whole, the same way.
6307
+ */
6308
+ private settlePendingCheckpoints;
6218
6309
  /**
6219
6310
  * The checkpoints of one run at distinct `seqs`, each as its own outcome: one
6220
6311
  * {@link StateStore.getCheckpoints} call when the store has it, else one read each. The batch
@@ -6275,8 +6366,8 @@ declare class WorkflowEngine {
6275
6366
  * that result (see {@link completeRemoteResults}).
6276
6367
  */
6277
6368
  private stepFanStillRunning;
6278
- /** How many steps of a step fan's seq range are still `pending`. */
6279
- private stepFanPending;
6369
+ /** Whether any step of a step fan's seq range is still `pending`. */
6370
+ private stepFanHasPending;
6280
6371
  /**
6281
6372
  * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
6282
6373
  * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
@@ -6993,10 +7084,20 @@ declare class CodecStateStore implements StateStore {
6993
7084
  readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
6994
7085
  /** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
6995
7086
  readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
7087
+ /** Encodes each settlement's payloads like {@link saveCheckpoint}. Bound only when the inner store
7088
+ * has it, so the engine's whole-row fallback still kicks in through the wrapper. */
7089
+ readonly settleCheckpointsIfPending?: (settlements: StepSettlement[]) => Promise<boolean[]>;
6996
7090
  /** Encodes each checkpoint written. Bound only when the inner store has it. */
6997
7091
  readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
7092
+ /** Decodes each checkpoint read like {@link listCheckpoints}. Bound only when the inner store has
7093
+ * it, so the engine's full-read fallback still kicks in through the wrapper. */
7094
+ readonly listCheckpointsForReplay?: (runId: string) => Promise<StepCheckpoint[]>;
7095
+ /** Decodes each checkpoint read. Bound only when the inner store has it. */
7096
+ readonly getCheckpointsForSettle?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
6998
7097
  /** Decodes each checkpoint read. Bound only when the inner store has it. */
6999
7098
  readonly getCheckpoints?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
7099
+ /** Forwarded verbatim — reads no payload. Bound only when the inner store has it. */
7100
+ readonly hasCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<boolean>;
7000
7101
  /** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
7001
7102
  readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
7002
7103
  /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
@@ -7040,6 +7141,7 @@ declare class CodecStateStore implements StateStore {
7040
7141
  private encRun;
7041
7142
  private decRun;
7042
7143
  private encCp;
7144
+ private encSettlement;
7043
7145
  private decCp;
7044
7146
  private encSpec;
7045
7147
  private encSchedule;
@@ -7162,6 +7264,19 @@ type Subscribable = {
7162
7264
  */
7163
7265
  declare function collectMetrics(engine: Subscribable): MetricsCollector;
7164
7266
 
7267
+ /**
7268
+ * An event another instance produced and the control plane re-delivered here. Every instance hears
7269
+ * every run's lifecycle, so a consumer that RECORDS events (Telescope, a metrics counter, a trace
7270
+ * exporter) would record each one once per pod; such consumers skip the events marked remote.
7271
+ *
7272
+ * The mark is a non-enumerable property under a registered symbol, so it never reaches a serialized
7273
+ * event and a consumer can test for it without importing this module.
7274
+ */
7275
+ declare const REMOTE_EVENT: unique symbol;
7276
+ declare function markRemoteEvent<E extends object>(event: E): E;
7277
+ /** Whether `event` was produced by another instance and re-delivered here over the control plane. */
7278
+ declare function isRemoteEvent(event: object): boolean;
7279
+
7165
7280
  /**
7166
7281
  * The origin (see {@link import('./interfaces').WorkflowRun.origin}) stamped onto runs of the
7167
7282
  * workflows this package registers ITSELF — the built-in `__entity` runner behind durable entities
@@ -7543,10 +7658,12 @@ declare class InMemoryStateStore implements StateStore {
7543
7658
  pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
7544
7659
  getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
7545
7660
  getCheckpoints(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
7661
+ getCheckpointsForSettle(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
7546
7662
  saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
7547
7663
  saveCheckpoints(checkpoints: StepCheckpoint[]): Promise<void>;
7548
7664
  saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
7549
7665
  saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
7666
+ settleCheckpointsIfPending(settlements: StepSettlement[]): Promise<boolean[]>;
7550
7667
  listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
7551
7668
  listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
7552
7669
  listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
@@ -7612,12 +7729,14 @@ declare class InMemoryStateStore implements StateStore {
7612
7729
  deleteSchedule(id: string): Promise<boolean>;
7613
7730
  listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
7614
7731
  listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
7732
+ listCheckpointsForReplay(runId: string): Promise<StepCheckpoint[]>;
7615
7733
  private runCheckpoints;
7616
7734
  checkpointStats(runId: string, opts?: {
7617
7735
  group?: string | undefined;
7618
7736
  }): Promise<CheckpointStat[]>;
7619
7737
  queryCheckpoints(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
7620
7738
  getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
7739
+ hasCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<boolean>;
7621
7740
  countCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
7622
7741
  listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
7623
7742
  }
@@ -7717,4 +7836,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
7717
7836
  updatedAt: Date;
7718
7837
  } | undefined;
7719
7838
 
7720
- export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, StandardSchemaV1, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
7839
+ export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, StandardSchemaV1, 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 StepScope, type StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
package/dist/index.d.ts CHANGED
@@ -1055,6 +1055,17 @@ interface StepCheckpoint {
1055
1055
  startedAt: Date;
1056
1056
  finishedAt: Date;
1057
1057
  }
1058
+ /** What a step's result changes on its checkpoint: see {@link StateStore.settleCheckpointsIfPending}. */
1059
+ interface StepSettlement {
1060
+ runId: string;
1061
+ seq: number;
1062
+ status: 'completed' | 'failed';
1063
+ output?: unknown;
1064
+ error?: StepError | undefined;
1065
+ events?: StepEvent[] | undefined;
1066
+ startedAt: Date;
1067
+ finishedAt: Date;
1068
+ }
1058
1069
  /**
1059
1070
  * A structured event a step (or its worker) emits while running — a log line and/or a sub-step
1060
1071
  * outcome. The dashboard renders these under the step, so you can see what happened inside a step
@@ -1250,6 +1261,17 @@ interface StateStore {
1250
1261
  * Optional: a store that omits it gets one {@link getCheckpoint} per seq.
1251
1262
  */
1252
1263
  getCheckpoints?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
1264
+ /**
1265
+ * {@link getCheckpoints} as a step result's settle reads them: the same rows, each without its
1266
+ * `input` (left out of the read, not dropped after it). A settle needs the row's status, name,
1267
+ * group and timings, never what the step was called with, and the step being settled is the one
1268
+ * whose input is still fresh: an LLM step's prompt was otherwise read back on every result. The
1269
+ * engine reads through it only when the store also has {@link settleCheckpointsIfPending}, since
1270
+ * the whole-row write it falls back to needs the input.
1271
+ *
1272
+ * Optional: a store that omits it gets {@link getCheckpoints}.
1273
+ */
1274
+ getCheckpointsForSettle?(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
1253
1275
  /**
1254
1276
  * Persist a checkpoint and advance the run atomically. Durable semantics depend on this
1255
1277
  * being a single transaction; stores without transactions cannot give the strong guarantee.
@@ -1284,6 +1306,18 @@ interface StateStore {
1284
1306
  * Optional: a store that omits it gets one {@link saveCheckpointIfPending} per entry.
1285
1307
  */
1286
1308
  saveCheckpointsIfPending?(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
1309
+ /**
1310
+ * Settle steps from their results: per entry and in input order, while the row at `(runId, seq)`
1311
+ * is still `pending`, write the entry's `status`, `output`, `error`, `events`, `startedAt` and
1312
+ * `finishedAt` (an absent one is stored empty) and leave every other column as it is stored;
1313
+ * resolves whether each entry wrote. Claims like {@link saveCheckpointsIfPending}: a later entry for
1314
+ * a row an earlier one settled loses, and a rejection writes nothing. The engine settles a batch of
1315
+ * one run's step results through it, so a step's `input` (an LLM prompt, say) is not written again
1316
+ * when its result lands.
1317
+ *
1318
+ * Optional: a store that omits it gets {@link saveCheckpointsIfPending} with the whole rows.
1319
+ */
1320
+ settleCheckpointsIfPending?(settlements: StepSettlement[]): Promise<boolean[]>;
1287
1321
  /** Used by recovery on boot to find runs to resume (crashed, left `running`). */
1288
1322
  listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
1289
1323
  /**
@@ -1497,6 +1531,17 @@ interface StateStore {
1497
1531
  */
1498
1532
  runValueFacets?(axis: RunValueAxis, query: RunFacetQuery, opts?: RunValueFacetOptions): Promise<RunValueFacetRow[]>;
1499
1533
  listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
1534
+ /**
1535
+ * {@link listCheckpoints} as a turn replays it: the same rows in the same order, except that a
1536
+ * `completed` row comes without its `input` (left out of the read, not dropped after it). Replay
1537
+ * only needs a completed step's output; a still-open or failed step keeps its input, since a
1538
+ * re-dispatch or a retry writes it again. The engine reads a run's replay snapshot through it on
1539
+ * every turn, where re-reading every finished step's input would make each turn cost the size of
1540
+ * the whole history.
1541
+ *
1542
+ * Optional: a store that omits it gets {@link listCheckpoints}.
1543
+ */
1544
+ listCheckpointsForReplay?(runId: string): Promise<StepCheckpoint[]>;
1500
1545
  /**
1501
1546
  * The LATEST checkpoint for `runId` whose `name` equals `name` exactly (highest `seq` wins), or
1502
1547
  * `undefined` if none. A targeted read that avoids fetching + deserializing every checkpoint just to
@@ -1527,6 +1572,16 @@ interface StateStore {
1527
1572
  * Optional: a store that omits it still works — the engine falls back to {@link listCheckpoints}
1528
1573
  * and counts in JS, which loads the whole run on every result of a fan.
1529
1574
  */
1575
+ /**
1576
+ * Whether any of the run's checkpoints with `fromSeq <= seq <= toSeq` has one of `statuses`: the
1577
+ * question the join barrier of a step fan actually asks on each batch of results ("is any step of
1578
+ * the fan still `pending`?"). A store reads it from the TOP of the range down and stops at the first
1579
+ * match: a fan's steps are dispatched in seq order, so its highest seqs are the last to settle, and
1580
+ * the answer comes from the first rows read instead of a count over the whole range.
1581
+ *
1582
+ * Optional: a store that omits it still works — the engine asks {@link countCheckpoints} instead.
1583
+ */
1584
+ hasCheckpoints?(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<boolean>;
1530
1585
  countCheckpoints?(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
1531
1586
  /**
1532
1587
  * The run's checkpoints aggregated into {@link CheckpointStat} buckets — one per
@@ -2008,6 +2063,9 @@ type RunRequestKind = {
2008
2063
  runId: string;
2009
2064
  group: string;
2010
2065
  query: FanPageQuery;
2066
+ } | {
2067
+ kind: 'getRun';
2068
+ runId: string;
2011
2069
  } | {
2012
2070
  kind: 'listRuns';
2013
2071
  query: RunQuery;
@@ -5485,6 +5543,8 @@ declare class WorkflowEngine {
5485
5543
  * checkpoint that is already settled, which the next turn replays past — so it cannot loop.
5486
5544
  */
5487
5545
  private redriveSettledSteps;
5546
+ /** Whether the step at `seq` is settled: a `COUNT` when the store has one, else its checkpoint. */
5547
+ private stepSettled;
5488
5548
  /**
5489
5549
  * {@link redriveSettledSteps} for a step fan: once the turn that suspended on it released its lease,
5490
5550
  * re-drive the run if no step of the fan is still `pending` — the last result landed on another
@@ -5993,6 +6053,13 @@ declare class WorkflowEngine {
5993
6053
  /** Earliest clock time a step's lease is worth LOOKING at again (`stepId` → clock ms) — the read
5994
6054
  * throttle for {@link rearmStepLease}, the step-scoped sibling of {@link decisionDeadlineRearms}. */
5995
6055
  private readonly stepLeaseRearms;
6056
+ /**
6057
+ * {@link stepLeaseRearms} for the steps of a fan this instance sent, by run: one entry per sent
6058
+ * block of consecutive seqs instead of one per step, since they share the lease stamped at send.
6059
+ */
6060
+ private readonly fanLeaseRearms;
6061
+ private noteFanLease;
6062
+ private fanLeaseLookAgainAt;
5996
6063
  /**
5997
6064
  * A step-scoped heartbeat for a durably-suspended remote step: push its LEASE forward so a worker
5998
6065
  * that is still working on it is never presumed dead and double-dispatched. The durable counterpart
@@ -6196,6 +6263,13 @@ declare class WorkflowEngine {
6196
6263
  * barrier ({@link stepFanStillRunning}) then wakes the parent once per wave, not once per result.
6197
6264
  */
6198
6265
  private callRemoteAll;
6266
+ /**
6267
+ * The checkpoints of a step fan's seqs, by seq. A settled one is taken from the turn's snapshot
6268
+ * (`replay`), since nothing but a turn of the run changes it once settled; one the snapshot holds
6269
+ * `pending`, or does not hold, is read again, as {@link callRemote} does for a single step: its
6270
+ * result may have landed since. The fan's last turn so reads nothing it already read.
6271
+ */
6272
+ private fanCheckpoints;
6199
6273
  /**
6200
6274
  * Write the `pending` checkpoints of a step fan's new steps, then dispatch them: one
6201
6275
  * {@link StateStore.saveCheckpoints} call and one {@link TransportPool.dispatchMany} for the
@@ -6204,8 +6278,17 @@ declare class WorkflowEngine {
6204
6278
  private sendStepFan;
6205
6279
  /** Remember a step settled here, forgetting entries older than a lease so the map stays small. */
6206
6280
  private noteSettledHere;
6207
- /** Record `key` in a "happened here recently" map, pruning entries older than a lease. */
6281
+ /**
6282
+ * Record `key` in a "happened here recently" map and drop the entries older than a lease. A key is
6283
+ * re-inserted at the end, so the map stays in the order its keys were noted and the stale ones are
6284
+ * all at its front: pruning stops at the first fresh entry instead of walking the whole map.
6285
+ */
6208
6286
  private noteRecent;
6287
+ /**
6288
+ * The run's checkpoints as a turn replays them: {@link StateStore.listCheckpointsForReplay} when
6289
+ * the store has it (no input on a completed row), else {@link StateStore.listCheckpoints}.
6290
+ */
6291
+ private replayCheckpoints;
6209
6292
  /** {@link StateStore.saveCheckpointIfPending}, or a plain save on a store without it. */
6210
6293
  private savePendingCheckpoint;
6211
6294
  /**
@@ -6215,6 +6298,14 @@ declare class WorkflowEngine {
6215
6298
  * call rejecting means it wrote nothing, so the entries are then written one by one.
6216
6299
  */
6217
6300
  private savePendingCheckpoints;
6301
+ /**
6302
+ * Settle steps of one run at distinct seqs from their results ({@link StepSettlement}s, `settled[i]`
6303
+ * being the `pending` row `settlements[i]` settles): one
6304
+ * {@link StateStore.settleCheckpointsIfPending} call when the store has it, which writes only what
6305
+ * a result changes, else the whole rows through {@link savePendingCheckpoints}. Never rejects as a
6306
+ * whole, the same way.
6307
+ */
6308
+ private settlePendingCheckpoints;
6218
6309
  /**
6219
6310
  * The checkpoints of one run at distinct `seqs`, each as its own outcome: one
6220
6311
  * {@link StateStore.getCheckpoints} call when the store has it, else one read each. The batch
@@ -6275,8 +6366,8 @@ declare class WorkflowEngine {
6275
6366
  * that result (see {@link completeRemoteResults}).
6276
6367
  */
6277
6368
  private stepFanStillRunning;
6278
- /** How many steps of a step fan's seq range are still `pending`. */
6279
- private stepFanPending;
6369
+ /** Whether any step of a step fan's seq range is still `pending`. */
6370
+ private stepFanHasPending;
6280
6371
  /**
6281
6372
  * Apply a remote workflow-turn {@link WorkflowDecision} durably — runs on WHATEVER instance receives
6282
6373
  * it over the broker (the dispatching one may be gone, or a point-to-point broker handed it to a
@@ -6993,10 +7084,20 @@ declare class CodecStateStore implements StateStore {
6993
7084
  readonly saveCheckpointIfPending?: (checkpoint: StepCheckpoint) => Promise<boolean>;
6994
7085
  /** Encodes each checkpoint like {@link saveCheckpoint}. Bound only when the inner store has it. */
6995
7086
  readonly saveCheckpointsIfPending?: (checkpoints: StepCheckpoint[]) => Promise<boolean[]>;
7087
+ /** Encodes each settlement's payloads like {@link saveCheckpoint}. Bound only when the inner store
7088
+ * has it, so the engine's whole-row fallback still kicks in through the wrapper. */
7089
+ readonly settleCheckpointsIfPending?: (settlements: StepSettlement[]) => Promise<boolean[]>;
6996
7090
  /** Encodes each checkpoint written. Bound only when the inner store has it. */
6997
7091
  readonly saveCheckpoints?: (checkpoints: StepCheckpoint[]) => Promise<void>;
7092
+ /** Decodes each checkpoint read like {@link listCheckpoints}. Bound only when the inner store has
7093
+ * it, so the engine's full-read fallback still kicks in through the wrapper. */
7094
+ readonly listCheckpointsForReplay?: (runId: string) => Promise<StepCheckpoint[]>;
7095
+ /** Decodes each checkpoint read. Bound only when the inner store has it. */
7096
+ readonly getCheckpointsForSettle?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
6998
7097
  /** Decodes each checkpoint read. Bound only when the inner store has it. */
6999
7098
  readonly getCheckpoints?: (runId: string, seqs: number[]) => Promise<StepCheckpoint[]>;
7099
+ /** Forwarded verbatim — reads no payload. Bound only when the inner store has it. */
7100
+ readonly hasCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<boolean>;
7000
7101
  /** Forwarded verbatim — a count reads no payload. Bound only when the inner store has it. */
7001
7102
  readonly countCheckpoints?: (runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]) => Promise<number>;
7002
7103
  /** Forwarded verbatim — retention selects by status/updatedAt/scope, never by payload. Bound only
@@ -7040,6 +7141,7 @@ declare class CodecStateStore implements StateStore {
7040
7141
  private encRun;
7041
7142
  private decRun;
7042
7143
  private encCp;
7144
+ private encSettlement;
7043
7145
  private decCp;
7044
7146
  private encSpec;
7045
7147
  private encSchedule;
@@ -7162,6 +7264,19 @@ type Subscribable = {
7162
7264
  */
7163
7265
  declare function collectMetrics(engine: Subscribable): MetricsCollector;
7164
7266
 
7267
+ /**
7268
+ * An event another instance produced and the control plane re-delivered here. Every instance hears
7269
+ * every run's lifecycle, so a consumer that RECORDS events (Telescope, a metrics counter, a trace
7270
+ * exporter) would record each one once per pod; such consumers skip the events marked remote.
7271
+ *
7272
+ * The mark is a non-enumerable property under a registered symbol, so it never reaches a serialized
7273
+ * event and a consumer can test for it without importing this module.
7274
+ */
7275
+ declare const REMOTE_EVENT: unique symbol;
7276
+ declare function markRemoteEvent<E extends object>(event: E): E;
7277
+ /** Whether `event` was produced by another instance and re-delivered here over the control plane. */
7278
+ declare function isRemoteEvent(event: object): boolean;
7279
+
7165
7280
  /**
7166
7281
  * The origin (see {@link import('./interfaces').WorkflowRun.origin}) stamped onto runs of the
7167
7282
  * workflows this package registers ITSELF — the built-in `__entity` runner behind durable entities
@@ -7543,10 +7658,12 @@ declare class InMemoryStateStore implements StateStore {
7543
7658
  pruneTerminalRuns(policy: RetentionPolicy, nowMs: number, limit: number): Promise<number>;
7544
7659
  getCheckpoint(runId: string, seq: number): Promise<StepCheckpoint | null>;
7545
7660
  getCheckpoints(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
7661
+ getCheckpointsForSettle(runId: string, seqs: number[]): Promise<StepCheckpoint[]>;
7546
7662
  saveCheckpoint(checkpoint: StepCheckpoint): Promise<void>;
7547
7663
  saveCheckpoints(checkpoints: StepCheckpoint[]): Promise<void>;
7548
7664
  saveCheckpointIfPending(checkpoint: StepCheckpoint): Promise<boolean>;
7549
7665
  saveCheckpointsIfPending(checkpoints: StepCheckpoint[]): Promise<boolean[]>;
7666
+ settleCheckpointsIfPending(settlements: StepSettlement[]): Promise<boolean[]>;
7550
7667
  listOrphanedRuns(nowMs: number, limit: number, namespace?: string, ownedBy?: OwnedLeaseReclaim): Promise<WorkflowRun[]>;
7551
7668
  listIncompleteRuns(namespace?: string): Promise<WorkflowRun[]>;
7552
7669
  listPendingRuns(limit: number, namespace?: string): Promise<WorkflowRun[]>;
@@ -7612,12 +7729,14 @@ declare class InMemoryStateStore implements StateStore {
7612
7729
  deleteSchedule(id: string): Promise<boolean>;
7613
7730
  listSchedules(query: ScheduleQuery): Promise<ScheduleRecord[]>;
7614
7731
  listCheckpoints(runId: string): Promise<StepCheckpoint[]>;
7732
+ listCheckpointsForReplay(runId: string): Promise<StepCheckpoint[]>;
7615
7733
  private runCheckpoints;
7616
7734
  checkpointStats(runId: string, opts?: {
7617
7735
  group?: string | undefined;
7618
7736
  }): Promise<CheckpointStat[]>;
7619
7737
  queryCheckpoints(runId: string, query: CheckpointQuery): Promise<StepCheckpoint[]>;
7620
7738
  getLatestCheckpointByName(runId: string, name: string): Promise<StepCheckpoint | undefined>;
7739
+ hasCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<boolean>;
7621
7740
  countCheckpoints(runId: string, fromSeq: number, toSeq: number, statuses: StepCheckpoint['status'][]): Promise<number>;
7622
7741
  listCheckpointsByNamePrefix(runId: string, prefixes: string[]): Promise<StepCheckpoint[]>;
7623
7742
  }
@@ -7717,4 +7836,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
7717
7836
  updatedAt: Date;
7718
7837
  } | undefined;
7719
7838
 
7720
- export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, StandardSchemaV1, 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 StepScope, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };
7839
+ export { type AccumulatorHost, type Admission, type AdmissionBackend, type AdmissionItem, type AllOptions, type AllSettledOptions, type AllStepsOptions, type AllStepsSettledOptions, type AnnouncedWorkflow, type AnnouncementEvidence, type AttributeFilter, type AttributeOp, type AttributePredicateOperand, type AttributeValue, type BackoffStrategy, type BlockedDispatch, type BlockedResolution, type BufferedSignalRow, CHILD_EDGE_PREFIXES, CONTROL_FLOW_SIGNAL, CORE_ORIGIN, CURRENT_PROTOCOL_VERSION, type CapabilityRequirement, type CheckpointAggregatingStore, type CheckpointNameKind, type CheckpointQuery, type CheckpointStat, type ChildCallOptions, type ChildWait, CodecStateStore, type CodecStateStoreOptions, type ConcurrencyConfig, ConcurrencyLimitError, type ConcurrencyQuota, ContinueAsNew, type ControlMessage, type ControlPlane, DEFAULT_CONCURRENCY_STATUSES, DEFAULT_PARTITION, DEFAULT_STALLED_AFTER_MS, DURABLE_OPTIONS, DURABLE_OPTIONS_CANONICAL, DURABLE_STEP_CONFIG, DURABLE_STEP_NAME, type Disagreement, type DispatchDiagnostics, type DispatchPlan, type DurableExecution, type DurableExecutionWrapper, type DurableTopology, type DurableWebhook, DurableWorkflow, type DynamicWorkflowCtx, ENGINE_MINTED_TAG_PREFIXES, ENTITY_WORKFLOW, EVENT_BUFFER_SCAN_LIMIT, EVENT_TOKEN_PREFIX, type EngineEvent, type EngineEventType, type EngineListener, Entities, type EntityConfig, type EntityHandler, type EntityHost, type EntityWorkflowHost, EventAccumulators, type EventBatchConfig, FAN_SUMMARY_FAILURES, type FanJoin, type FanPage, type FanPageQuery, type FanSummary, type FanWait, FatalError, type FindStalledRunsOptions, GatherError, type GatherItemFailure, type GroupHealth, HANDOFF_SEQ_BASE, type Heartbeat, type HeartbeatSighting, type HeartbeatStatus, type HistoryEvent, InMemoryAdmissionBackend, InMemoryRunQueue, InMemoryStateStore, InMemoryTransport, type InferSearchAttributes, LEGACY_V1_CAPABILITIES, LEGACY_V1_PROTOCOL, type ListStalledRunsOptions, type MetricsCollector, type MetricsSnapshot, type NamedTransport, type NegotiateOptions, type NegotiationOutcome, type NegotiationReason, type NegotiationResult, NestedWorkflowCallError, NonDeterminismError, type OnErrorInput, type OnErrorRoute, type OwnedLeaseReclaim, type PartitionSighting, type PayloadCodec, type QueueConfig, QueueController, REMOTE_EVENT, RUN_HISTORY_FIXTURE_VERSION, RUN_VALUE_FACET_LIMIT, RUN_VALUE_FACET_SCAN, type RawWorkerDescriptor, RemoteStepError, RemoteStepTimeout, type RemoteTask, RemoteWorkflowExecutor, RemoteWorkflowTimeout, type RetentionPolicy, type RoutableDispatch, type RoutableResolution, type RoutingResolution, type RunAttributeRow, type RunConsumerOptions, type RunDetail, type RunDetailOptions, type RunDispatch, type RunDispatcher, type RunFacetQuery, type RunFacetRow, RunGateway, type RunListItem, type RunQuery, type RunQueueOptions, type RunReply, type RunReplyResult, type RunRequest, type RunRequestKind, type RunResult, type RunSchedulesOptions, type RunScope, type RunStatus, type RunValueAxis, type RunValueFacetOptions, type RunValueFacetOrder, type RunValueFacetRow, type RunWaiting, SINGLETON_ACTIVE_STATUSES, SINGLETON_ADMITTED_TAG, SINGLETON_RESERVED_TAGS, SINGLETON_TRACKED_TAG, STATE_STORE, STATE_STORE_CANONICAL, SUMMARY_CHILD_LIMIT, type ScalarAttributeFilter, ScheduleAlreadyExistsError, ScheduleClient, type ScheduleClientOptions, type ScheduleDescription, type ScheduleHost, type ScheduleListQuery, ScheduleNotFoundError, type ScheduleOptions, type ScheduleQuery, type ScheduleRecord, type ScheduledWorkflow, type SchemaIssue, type SchemaValidationCode, SchemaValidationError, type SearchAttributes, type SearchAttributesSchema, type Settled, SignalTimeoutError, type SignalWaiter, type SingletonConfig, SingletonQueueFullError, type StalePendingStep, type StalledRunInfo, StandardSchemaV1, 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 StepScope, type StepSettlement, type StepUndo, type StoreTransaction, type SubProcessHandle, TERMINAL_RUN_STATUSES, TRANSPORT, TRANSPORT_CANONICAL, type TenantEvent, type TenantTokenSource, type TenantVerifier, type Transport, type UndoOf, type UpdateResult, type UpdateValidator, VERSION_UNDECLARED_TAG, type VerifiedTenant, WORKFLOW_NAME_KEY, type WireDates, type WorkerAdjust, type WorkerConcurrencyStatus, type WorkerDescriptor, type WorkerHeartbeat, type WorkerLifecycle, type WorkerStatus, type WorkflowAnnouncement, WorkflowBlocked, type WorkflowClass, type WorkflowCommand, type WorkflowCtx, type WorkflowDecision, type WorkflowDirectory, WorkflowEngine, type WorkflowEngineDeps, type WorkflowExecutor, type WorkflowHandler, type WorkflowInputOf, type WorkflowOutputOf, type WorkflowRef, type WorkflowRegistration, type WorkflowRun, type WorkflowStartClient, type WorkflowStepEvent, WorkflowSuspended, type WorkflowTask, aggregateAnnouncements, aggregatesCheckpoints, announcementsOf, applyAttributeQuery, assertConcurrency, assertRoutes, attributeColumnFor, attributeOperand, attributePredicateOperands, axisIsRunColumn, bindWorkflowClass, breakpointToken, buildWorkflowDirectory, canRoute, capableWorkers, checkpointNameKind, checkpointStatsOf, childIdsOf, classifyWaiterToken, clearDurableExecutionWrappers, clearTerminalSingletonAdmission, codeAndDetails, codeOf, collectMetrics, concurrencyTag, controlPlaneDescriptor, countRuns, coveredTokens, createStepLogger, currentStep, currentStepScope, currentWorkflowCtx, debug, describeWorker, descriptorHash, detailsOf, error, etagMatches, eventMatchOf, eventMatches, eventNameOf, eventPrefix, eventToken, facetOrigin, fanPageBounds, fanPageEtag, findStalledRuns, foldedCount, getRunsByIds, handoffHandlerId, handoffName, hasDurableExecutionWrappers, heartbeatStatus, hmacTenantVerifier, indexWaitersByRun, info, isEngineMintedTag, isEventToken, isFailedMember, isLegacyDescriptor, isNonEmptyRunScope, isRemoteEvent, isWorkflowControlFlowSignal, legacySingletonHolders, listSignalWaitersOfRuns, liveHandoff, log, markRemoteEvent, matchesAttributes, mergeRunFacetRows, mergeRunValueFacetRows, missingCapabilities, negotiate, nextCronFireMs, normalizeAttributeRows, normalizeDescriptor, observedAnnouncements, onErrorRunId, pageFan, pageFanFromStore, parentRunIdOf, parseDuration, parseWebhookToken, partitionOfToken, planDispatch, poolNamespace, prevCronFireMs, queryCheckpointsOf, readRunsByIds, readSearchAttributes, requiredCapabilities, resolveConcurrency, resolveRouting, resolveRunWaiting, resolveTenantToken, resolveWireTenant, retiredHandoffName, routeFor, runDetailEtag, runDurableExecution, runInStepLogger, runInStepScope, runInWorkflowCtx, runOutsideWorkflowCtx, runSchedules, runStepHandler, runValueFacetsFromRuns, sanitizeQueueToken, scheduleRunIdAt, scheduledRunId, signTenantToken, singletonAdmissionDenialPatch, singletonAdmissionTags, sqlComparator, stepConfigOf, stepId, stepNameOf, sub, subEvent, subProcess, summarizeFan, summarizeRunFromStore, summarizeTimeline, tenantGroup, useDurableExecution, warn, withSingletonTracked, withoutSingletonMarkers, workflowName };