@dudousxd/nestjs-durable-core 0.85.12 → 0.86.0

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
@@ -902,7 +902,8 @@ type RunStatus =
902
902
  * are actually published (a legacy/pre-handshake fleet skips the guard, design §7.7).
903
903
  */
904
904
  | 'blocked' | 'completed' | 'failed' | 'cancelled'
905
- /** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill). Terminal; inspect it. */
905
+ /** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill), or no instance has
906
+ * the run's workflow version registered past `unregisteredWorkflowGraceMs`. Terminal; inspect it. */
906
907
  | 'dead';
907
908
  /** One execution of a workflow. The unit of durability and the unit shown in the dashboard. */
908
909
  interface WorkflowRun {
@@ -4478,6 +4479,17 @@ interface WorkflowEngineDeps {
4478
4479
  * Omit for unlimited (the default — recovery always retries).
4479
4480
  */
4480
4481
  maxRecoveryAttempts?: number | undefined;
4482
+ /**
4483
+ * How long (ms) a run may stay due while NO instance can resume it because its workflow version is
4484
+ * not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
4485
+ * deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
4486
+ * up within seconds. A run that stays unresumable far past that — its workflow was renamed or
4487
+ * deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
4488
+ * run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
4489
+ * counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
4490
+ * the default.
4491
+ */
4492
+ unregisteredWorkflowGraceMs?: number | undefined;
4481
4493
  /**
4482
4494
  * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
4483
4495
  * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
@@ -4629,6 +4641,13 @@ interface ListStalledRunsOptions {
4629
4641
  /** Evaluate as of this clock time. Defaults to the engine clock. */
4630
4642
  now?: number | undefined;
4631
4643
  }
4644
+ /**
4645
+ * Thrown by {@link WorkflowEngine.resume} when nothing registered here (nor an inherited or
4646
+ * convention route) can run the run's pinned `workflow@version`.
4647
+ */
4648
+ declare class WorkflowNotRegistered extends Error {
4649
+ constructor(workflow: string, version: string);
4650
+ }
4632
4651
  /**
4633
4652
  * The orchestrator. Owns workflow state and replays runs deterministically: each step's
4634
4653
  * result is checkpointed, so on resume a completed step returns its saved output instead of
@@ -4651,6 +4670,7 @@ declare class WorkflowEngine {
4651
4670
  */
4652
4671
  private readonly ownLeaseCutoffMs;
4653
4672
  private readonly maxRecoveryAttempts?;
4673
+ private readonly unregisteredWorkflowGraceMs;
4654
4674
  private readonly remoteAdvanceSilenceMs?;
4655
4675
  private readonly reconcileMs;
4656
4676
  private readonly timerBatchSize;
@@ -5372,6 +5392,33 @@ declare class WorkflowEngine {
5372
5392
  * result to skip the resume, or `undefined` to proceed.
5373
5393
  */
5374
5394
  private countRecovery;
5395
+ /** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
5396
+ private announceDead;
5397
+ /** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
5398
+ * pays no await (same rule as {@link resume}). */
5399
+ private isRegisteredHere;
5400
+ /**
5401
+ * Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
5402
+ * remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
5403
+ */
5404
+ private canResolveWorkflow;
5405
+ /**
5406
+ * A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
5407
+ * {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
5408
+ * rolling deploy's skew: the lease is released at once so the pod that still has the version takes
5409
+ * the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
5410
+ * capable pod would have taken the run long ago): dead-letter it.
5411
+ *
5412
+ * The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
5413
+ * count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
5414
+ * orphan never ages.
5415
+ *
5416
+ * Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
5417
+ * `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
5418
+ */
5419
+ private settleUnregistered;
5420
+ /** Log a run skipped for an unregistered workflow — still there, still not progressing. */
5421
+ private logUnregisteredSkip;
5375
5422
  /**
5376
5423
  * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
5377
5424
  * boot. A run still not due re-suspends cheaply without running new work.
@@ -5473,7 +5520,8 @@ declare class WorkflowEngine {
5473
5520
  * Resume each run only if this instance can acquire its recovery lease — so when several
5474
5521
  * replicas recover or poll at once, each run is picked up by exactly one of them.
5475
5522
  *
5476
- * A run this instance cannot resume is SKIPPED, not allowed to abort the batch. The canonical
5523
+ * A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
5524
+ * stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
5477
5525
  * case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
5478
5526
  * and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
5479
5527
  * and every caller here is a recovery sweep. Letting the first such run end the loop means one
@@ -7856,4 +7904,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
7856
7904
  updatedAt: Date;
7857
7905
  } | undefined;
7858
7906
 
7859
- 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 };
7907
+ 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, WorkflowNotRegistered, 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
@@ -902,7 +902,8 @@ type RunStatus =
902
902
  * are actually published (a legacy/pre-handshake fleet skips the guard, design §7.7).
903
903
  */
904
904
  | 'blocked' | 'completed' | 'failed' | 'cancelled'
905
- /** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill). Terminal; inspect it. */
905
+ /** Dead-letter: recovery gave up after `maxRecoveryAttempts` (a poison pill), or no instance has
906
+ * the run's workflow version registered past `unregisteredWorkflowGraceMs`. Terminal; inspect it. */
906
907
  | 'dead';
907
908
  /** One execution of a workflow. The unit of durability and the unit shown in the dashboard. */
908
909
  interface WorkflowRun {
@@ -4478,6 +4479,17 @@ interface WorkflowEngineDeps {
4478
4479
  * Omit for unlimited (the default — recovery always retries).
4479
4480
  */
4480
4481
  maxRecoveryAttempts?: number | undefined;
4482
+ /**
4483
+ * How long (ms) a run may stay due while NO instance can resume it because its workflow version is
4484
+ * not registered anywhere, before it is moved to `dead` (code `workflow_not_registered`). A rolling
4485
+ * deploy skips such a run on purpose (skew protection): the pod still on the prior version picks it
4486
+ * up within seconds. A run that stays unresumable far past that — its workflow was renamed or
4487
+ * deleted — would otherwise be retried and logged on every tick forever. The clock starts when the
4488
+ * run became due (its `wakeAt` for a parked run, its last update otherwise), so a long sleep is not
4489
+ * counted. Default 24h; `0` disables (skip forever). A non-finite or negative value falls back to
4490
+ * the default.
4491
+ */
4492
+ unregisteredWorkflowGraceMs?: number | undefined;
4481
4493
  /**
4482
4494
  * Opt-in liveness deadline (ms) for a remote workflow `advance`. If the worker neither returns a
4483
4495
  * decision NOR sends a run-scoped {@link Heartbeat} within this window, the engine presumes it dead:
@@ -4629,6 +4641,13 @@ interface ListStalledRunsOptions {
4629
4641
  /** Evaluate as of this clock time. Defaults to the engine clock. */
4630
4642
  now?: number | undefined;
4631
4643
  }
4644
+ /**
4645
+ * Thrown by {@link WorkflowEngine.resume} when nothing registered here (nor an inherited or
4646
+ * convention route) can run the run's pinned `workflow@version`.
4647
+ */
4648
+ declare class WorkflowNotRegistered extends Error {
4649
+ constructor(workflow: string, version: string);
4650
+ }
4632
4651
  /**
4633
4652
  * The orchestrator. Owns workflow state and replays runs deterministically: each step's
4634
4653
  * result is checkpointed, so on resume a completed step returns its saved output instead of
@@ -4651,6 +4670,7 @@ declare class WorkflowEngine {
4651
4670
  */
4652
4671
  private readonly ownLeaseCutoffMs;
4653
4672
  private readonly maxRecoveryAttempts?;
4673
+ private readonly unregisteredWorkflowGraceMs;
4654
4674
  private readonly remoteAdvanceSilenceMs?;
4655
4675
  private readonly reconcileMs;
4656
4676
  private readonly timerBatchSize;
@@ -5372,6 +5392,33 @@ declare class WorkflowEngine {
5372
5392
  * result to skip the resume, or `undefined` to proceed.
5373
5393
  */
5374
5394
  private countRecovery;
5395
+ /** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
5396
+ private announceDead;
5397
+ /** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
5398
+ * pays no await (same rule as {@link resume}). */
5399
+ private isRegisteredHere;
5400
+ /**
5401
+ * Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
5402
+ * remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
5403
+ */
5404
+ private canResolveWorkflow;
5405
+ /**
5406
+ * A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
5407
+ * {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
5408
+ * rolling deploy's skew: the lease is released at once so the pod that still has the version takes
5409
+ * the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
5410
+ * capable pod would have taken the run long ago): dead-letter it.
5411
+ *
5412
+ * The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
5413
+ * count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
5414
+ * orphan never ages.
5415
+ *
5416
+ * Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
5417
+ * `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
5418
+ */
5419
+ private settleUnregistered;
5420
+ /** Log a run skipped for an unregistered workflow — still there, still not progressing. */
5421
+ private logUnregisteredSkip;
5375
5422
  /**
5376
5423
  * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
5377
5424
  * boot. A run still not due re-suspends cheaply without running new work.
@@ -5473,7 +5520,8 @@ declare class WorkflowEngine {
5473
5520
  * Resume each run only if this instance can acquire its recovery lease — so when several
5474
5521
  * replicas recover or poll at once, each run is picked up by exactly one of them.
5475
5522
  *
5476
- * A run this instance cannot resume is SKIPPED, not allowed to abort the batch. The canonical
5523
+ * A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
5524
+ * stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
5477
5525
  * case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
5478
5526
  * and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
5479
5527
  * and every caller here is a recovery sweep. Letting the first such run end the loop means one
@@ -7856,4 +7904,4 @@ declare function singletonAdmissionDenialPatch(runs: WorkflowRun[], runId: strin
7856
7904
  updatedAt: Date;
7857
7905
  } | undefined;
7858
7906
 
7859
- 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 };
7907
+ 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, WorkflowNotRegistered, 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.js CHANGED
@@ -4949,6 +4949,22 @@ var NamespaceMismatch = class NamespaceMismatch2 extends Error {
4949
4949
  super("namespace-mismatch");
4950
4950
  }
4951
4951
  };
4952
+ var WorkflowNotRegistered = class extends Error {
4953
+ static {
4954
+ __name(this, "WorkflowNotRegistered");
4955
+ }
4956
+ constructor(workflow, version) {
4957
+ super(`workflow ${workflow}@${version} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
4958
+ this.name = "WorkflowNotRegistered";
4959
+ }
4960
+ };
4961
+ var UNREGISTERED_DEAD_LETTER_FROM = [
4962
+ "pending",
4963
+ "running",
4964
+ "suspended",
4965
+ "cancelling",
4966
+ "blocked"
4967
+ ];
4952
4968
  var WorkflowEngine = class {
4953
4969
  static {
4954
4970
  __name(this, "WorkflowEngine");
@@ -4968,6 +4984,7 @@ var WorkflowEngine = class {
4968
4984
  */
4969
4985
  ownLeaseCutoffMs;
4970
4986
  maxRecoveryAttempts;
4987
+ unregisteredWorkflowGraceMs;
4971
4988
  remoteAdvanceSilenceMs;
4972
4989
  reconcileMs;
4973
4990
  timerBatchSize;
@@ -5154,6 +5171,8 @@ var WorkflowEngine = class {
5154
5171
  this.leaseMs = deps.leaseMs ?? 3e4;
5155
5172
  this.ownLeaseCutoffMs = this.clock() + this.leaseMs;
5156
5173
  this.maxRecoveryAttempts = deps.maxRecoveryAttempts;
5174
+ const grace = deps.unregisteredWorkflowGraceMs;
5175
+ this.unregisteredWorkflowGraceMs = grace !== void 0 && Number.isFinite(grace) && grace >= 0 ? grace : 24 * 60 * 60 * 1e3;
5157
5176
  this.remoteAdvanceSilenceMs = deps.remoteAdvanceSilenceMs;
5158
5177
  this.reconcileMs = deps.reconcileMs === void 0 ? 3e5 : deps.reconcileMs || void 0;
5159
5178
  const stalledAfter = deps.stalledAfterMs;
@@ -5470,13 +5489,19 @@ var WorkflowEngine = class {
5470
5489
  * that is lost brings it back due after that period. False when the transport refused the wakes,
5471
5490
  * so the caller resumes them itself.
5472
5491
  */
5473
- async handOffDue(runs, nowMs) {
5492
+ async handOffDue(runs, nowMs, settled) {
5474
5493
  const claimed = [];
5475
5494
  for (const run of runs) {
5476
5495
  if (this.draining) break;
5477
5496
  if (!await this.store.tryLockRun(run.id, this.instanceId, nowMs + this.leaseMs, nowMs)) {
5478
5497
  continue;
5479
5498
  }
5499
+ if (!this.isRegisteredHere(run) && !await this.canResolveWorkflow(run)) {
5500
+ const result = await this.settleUnregistered(run, nowMs);
5501
+ if (result) settled?.set(run.id, result);
5502
+ else if (result === void 0) this.logUnregisteredSkip(run);
5503
+ continue;
5504
+ }
5480
5505
  try {
5481
5506
  const patch = {
5482
5507
  wakeAt: nowMs + this.leaseMs
@@ -6250,9 +6275,7 @@ var WorkflowEngine = class {
6250
6275
  });
6251
6276
  }
6252
6277
  const registered = this.workflows.get(versionKey(run.workflow, run.workflowVersion)) ?? await this.findInheritedRegistration(run) ?? await this.resolveRemoteByConvention(run);
6253
- if (!registered) {
6254
- throw new Error(`workflow ${run.workflow}@${run.workflowVersion} is not registered \u2014 keep the prior version deployed so in-flight runs can drain (skew protection)`);
6255
- }
6278
+ if (!registered) throw new WorkflowNotRegistered(run.workflow, run.workflowVersion);
6256
6279
  return this.track(this.execute(run, registered.fn));
6257
6280
  }
6258
6281
  /**
@@ -6667,6 +6690,15 @@ var WorkflowEngine = class {
6667
6690
  };
6668
6691
  }
6669
6692
  }
6693
+ if (!this.isRegisteredHere(run) && !await this.canResolveWorkflow(run)) {
6694
+ const settled2 = await this.settleUnregistered(run, nowMs);
6695
+ if (settled2) return {
6696
+ result: settled2,
6697
+ dispatch: false
6698
+ };
6699
+ if (settled2 === void 0) this.logUnregisteredSkip(run);
6700
+ return void 0;
6701
+ }
6670
6702
  const settled = await this.countRecovery(run);
6671
6703
  if (settled) return {
6672
6704
  result: settled,
@@ -6738,25 +6770,10 @@ var WorkflowEngine = class {
6738
6770
  updatedAt: /* @__PURE__ */ new Date()
6739
6771
  });
6740
6772
  await this.store.releaseRunLock(run.id);
6741
- this.emit({
6742
- type: "run.failed",
6743
- runId: run.id,
6744
- workflow: run.workflow,
6745
- namespace: run.namespace,
6746
- error: error2
6747
- });
6748
- this.notifyDead({
6773
+ return this.announceDead({
6749
6774
  ...run,
6750
- status: "dead",
6751
- error: error2,
6752
6775
  recoveryAttempts: attempts
6753
- });
6754
- this.notifyParent(run.id, failedCompletion(error2));
6755
- return {
6756
- runId: run.id,
6757
- status: "dead",
6758
- error: error2
6759
- };
6776
+ }, error2);
6760
6777
  }
6761
6778
  await this.store.updateRun(run.id, {
6762
6779
  recoveryAttempts: attempts,
@@ -6764,6 +6781,85 @@ var WorkflowEngine = class {
6764
6781
  });
6765
6782
  return void 0;
6766
6783
  }
6784
+ /** Tell everyone a run was just written `dead`: events, dead-letter routing, a waiting parent. */
6785
+ announceDead(run, error2) {
6786
+ this.emit({
6787
+ type: "run.failed",
6788
+ runId: run.id,
6789
+ workflow: run.workflow,
6790
+ namespace: run.namespace,
6791
+ error: error2
6792
+ });
6793
+ this.notifyDead({
6794
+ ...run,
6795
+ status: "dead",
6796
+ error: error2
6797
+ });
6798
+ this.notifyParent(run.id, failedCompletion(error2));
6799
+ return {
6800
+ runId: run.id,
6801
+ status: "dead",
6802
+ error: error2
6803
+ };
6804
+ }
6805
+ /** The synchronous half of {@link canResolveWorkflow}: callers check it first, so a registered run
6806
+ * pays no await (same rule as {@link resume}). */
6807
+ isRegisteredHere(run) {
6808
+ return this.workflows.has(versionKey(run.workflow, run.workflowVersion));
6809
+ }
6810
+ /**
6811
+ * Whether this instance can run `run`'s pinned `workflow@version`: registered here, inherited from a
6812
+ * remote ancestor, or routed by convention to a live worker group (the lookup {@link resume} does).
6813
+ */
6814
+ async canResolveWorkflow(run) {
6815
+ if (this.isRegisteredHere(run)) return true;
6816
+ return await this.findInheritedRegistration(run) !== void 0 || await this.resolveRemoteByConvention(run) !== void 0;
6817
+ }
6818
+ /**
6819
+ * A run whose lease this instance holds but whose `workflow@version` nothing here can run (see
6820
+ * {@link WorkflowNotRegistered}). Within {@link unregisteredWorkflowGraceMs} of becoming due it is a
6821
+ * rolling deploy's skew: the lease is released at once so the pod that still has the version takes
6822
+ * the run now, not after the lease expires. Past it, the workflow is gone from the whole fleet (a
6823
+ * capable pod would have taken the run long ago): dead-letter it.
6824
+ *
6825
+ * The age is read off `updatedAt` / `wakeAt`, so every path that would touch either (a recovery
6826
+ * count, a re-pend, a hand-off's lease-long `wakeAt`) must call this BEFORE writing — otherwise an
6827
+ * orphan never ages.
6828
+ *
6829
+ * Returns the `dead` result, `null` when the run left its status meanwhile (a lease-free
6830
+ * `cancel()`: settled, not ours to touch), or `undefined` when it was left for later.
6831
+ */
6832
+ async settleUnregistered(listed, nowMs) {
6833
+ const run = await this.store.getRun(listed.id);
6834
+ if (!run || !UNREGISTERED_DEAD_LETTER_FROM.includes(run.status)) {
6835
+ await this.store.releaseRunLock(listed.id);
6836
+ return null;
6837
+ }
6838
+ const dueSince = Math.max(run.updatedAt.getTime(), run.wakeAt ?? 0);
6839
+ if (this.unregisteredWorkflowGraceMs === 0 || nowMs - dueSince < this.unregisteredWorkflowGraceMs) {
6840
+ await this.store.releaseRunLock(run.id);
6841
+ return void 0;
6842
+ }
6843
+ const error2 = {
6844
+ message: `workflow ${run.workflow}@${run.workflowVersion} is not registered on any live instance (unresumable for over ${this.unregisteredWorkflowGraceMs}ms) \u2014 moved to dead-letter`,
6845
+ code: "workflow_not_registered"
6846
+ };
6847
+ const applied = await (this.store.updateRunIf ?? this.updateRunIfFallback).call(this.store, run.id, [
6848
+ run.status
6849
+ ], {
6850
+ status: "dead",
6851
+ error: error2,
6852
+ updatedAt: /* @__PURE__ */ new Date()
6853
+ });
6854
+ await this.store.releaseRunLock(run.id);
6855
+ if (!applied) return null;
6856
+ console.warn(`[nestjs-durable] run ${run.id}: ${error2.message}`);
6857
+ return this.announceDead(run, error2);
6858
+ }
6859
+ /** Log a run skipped for an unregistered workflow — still there, still not progressing. */
6860
+ logUnregisteredSkip(run) {
6861
+ console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, new WorkflowNotRegistered(run.workflow, run.workflowVersion));
6862
+ }
6767
6863
  /**
6768
6864
  * Resume every suspended run whose durable timer is due. Call periodically (a poller) and on
6769
6865
  * boot. A run still not due re-suspends cheaply without running new work.
@@ -6788,11 +6884,12 @@ var WorkflowEngine = class {
6788
6884
  ...due,
6789
6885
  ...blocked
6790
6886
  ];
6791
- if (await this.handOffDue(runs, nowMs)) {
6792
- return runs.map((run) => ({
6887
+ const settled = /* @__PURE__ */ new Map();
6888
+ if (await this.handOffDue(runs, nowMs, settled)) {
6889
+ return runs.map((run) => settled.get(run.id) ?? {
6793
6890
  runId: run.id,
6794
6891
  status: run.status
6795
- }));
6892
+ });
6796
6893
  }
6797
6894
  }
6798
6895
  const waiterByRun = indexWaitersByRun(await listSignalWaitersOfRuns(this.store, [
@@ -6873,8 +6970,13 @@ var WorkflowEngine = class {
6873
6970
  const nowMs = this.clock();
6874
6971
  const acquired = await this.store.tryLockRun(runId, this.instanceId, nowMs + this.leaseMs, nowMs);
6875
6972
  if (!acquired) return null;
6876
- return this.resumeImplicit(runId).catch((err) => {
6973
+ return this.resumeImplicit(runId).catch(async (err) => {
6877
6974
  if (err instanceof NamespaceMismatch) return null;
6975
+ if (err instanceof WorkflowNotRegistered) {
6976
+ const run = await this.store.getRun(runId);
6977
+ const settled = run ? await this.settleUnregistered(run, nowMs) : null;
6978
+ if (settled !== void 0) return settled;
6979
+ }
6878
6980
  throw err;
6879
6981
  });
6880
6982
  }
@@ -7129,7 +7231,8 @@ var WorkflowEngine = class {
7129
7231
  * Resume each run only if this instance can acquire its recovery lease — so when several
7130
7232
  * replicas recover or poll at once, each run is picked up by exactly one of them.
7131
7233
  *
7132
- * A run this instance cannot resume is SKIPPED, not allowed to abort the batch. The canonical
7234
+ * A run this instance cannot resume is SKIPPED, not allowed to abort the batch (a run whose workflow
7235
+ * stays registered nowhere past `unregisteredWorkflowGraceMs` is dead-lettered instead). The canonical
7133
7236
  * case is skew protection: mid-rolling-deploy a pod leases a run whose workflow it does not have
7134
7237
  * and `resume` throws by design — but the rest of the batch is runs it can drive perfectly well,
7135
7238
  * and every caller here is a recovery sweep. Letting the first such run end the loop means one
@@ -7153,6 +7256,11 @@ var WorkflowEngine = class {
7153
7256
  const settled = onLocked ? await onLocked(run) : void 0;
7154
7257
  results.push(settled ?? await this.resumeImplicit(run.id));
7155
7258
  } catch (error2) {
7259
+ if (error2 instanceof WorkflowNotRegistered) {
7260
+ const settled = await this.settleUnregistered(run, nowMs).catch(() => void 0);
7261
+ if (settled) results.push(settled);
7262
+ if (settled !== void 0) continue;
7263
+ }
7156
7264
  console.error(`[nestjs-durable] could not resume run ${run.id} (${run.workflow}@${run.workflowVersion}); leaving it for another instance:`, error2);
7157
7265
  }
7158
7266
  }
@@ -12913,6 +13021,7 @@ export {
12913
13021
  WORKFLOW_NAME_KEY,
12914
13022
  WorkflowBlocked,
12915
13023
  WorkflowEngine,
13024
+ WorkflowNotRegistered,
12916
13025
  WorkflowSuspended,
12917
13026
  aggregateAnnouncements,
12918
13027
  aggregatesCheckpoints,