@dudousxd/nestjs-durable-core 0.57.0 → 0.59.0

package/dist/index.cjs

@@ -23,6 +23,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   CONTROL_FLOW_SIGNAL: () => CONTROL_FLOW_SIGNAL,
+  CURRENT_PROTOCOL_VERSION: () => CURRENT_PROTOCOL_VERSION,
   CodecStateStore: () => CodecStateStore,
   ContinueAsNew: () => ContinueAsNew,
   DURABLE_OPTIONS: () => DURABLE_OPTIONS,
@@ -39,6 +40,8 @@ __export(index_exports, {
   InMemoryAdmissionBackend: () => InMemoryAdmissionBackend,
   InMemoryStateStore: () => InMemoryStateStore,
   InMemoryTransport: () => InMemoryTransport,
+  LEGACY_V1_CAPABILITIES: () => LEGACY_V1_CAPABILITIES,
+  LEGACY_V1_PROTOCOL: () => LEGACY_V1_PROTOCOL,
   NonDeterminismError: () => NonDeterminismError,
   QueueController: () => QueueController,
   RemoteStepError: () => RemoteStepError,
@@ -53,6 +56,7 @@ __export(index_exports, {
   TRANSPORT: () => TRANSPORT,
   TRANSPORT_CANONICAL: () => TRANSPORT_CANONICAL,
   WORKFLOW_NAME_KEY: () => WORKFLOW_NAME_KEY,
+  WorkflowBlocked: () => WorkflowBlocked,
   WorkflowEngine: () => WorkflowEngine,
   WorkflowSuspended: () => WorkflowSuspended,
   applyAttributeQuery: () => applyAttributeQuery,
@@ -60,23 +64,35 @@ __export(index_exports, {
   attributeOperand: () => attributeOperand,
   bindWorkflowClass: () => bindWorkflowClass,
   breakpointToken: () => breakpointToken,
+  canRoute: () => canRoute,
+  capableWorkers: () => capableWorkers,
   classifyWaiterToken: () => classifyWaiterToken,
   collectMetrics: () => collectMetrics,
+  controlPlaneDescriptor: () => controlPlaneDescriptor,
   createStepLogger: () => createStepLogger,
   currentWorkflowCtx: () => currentWorkflowCtx,
+  descriptorHash: () => descriptorHash,
   eventMatchOf: () => eventMatchOf,
   eventMatches: () => eventMatches,
   eventNameOf: () => eventNameOf,
   eventPrefix: () => eventPrefix,
   eventToken: () => eventToken,
+  heartbeatStatus: () => heartbeatStatus,
   indexWaitersByRun: () => indexWaitersByRun,
   isEventToken: () => isEventToken,
+  isLegacyDescriptor: () => isLegacyDescriptor,
   isWorkflowControlFlowSignal: () => isWorkflowControlFlowSignal,
   matchesAttributes: () => matchesAttributes,
+  missingCapabilities: () => missingCapabilities,
+  negotiate: () => negotiate,
   normalizeAttributeRows: () => normalizeAttributeRows,
+  normalizeDescriptor: () => normalizeDescriptor,
   parseDuration: () => parseDuration,
+  planDispatch: () => planDispatch,
   prevCronFireMs: () => prevCronFireMs,
   readSearchAttributes: () => readSearchAttributes,
+  requiredCapabilities: () => requiredCapabilities,
+  resolveRouting: () => resolveRouting,
   resolveRunWaiting: () => resolveRunWaiting,
   runInWorkflowCtx: () => runInWorkflowCtx,
   runSchedules: () => runSchedules,
@@ -913,6 +929,358 @@ function eventMatches(payload, match) {
 }
 __name(eventMatches, "eventMatches");
 
+// src/handshake/descriptor.ts
+var CURRENT_PROTOCOL_VERSION = 1;
+var LEGACY_V1_PROTOCOL = {
+  version: 1,
+  range: [
+    1,
+    1
+  ]
+};
+var LEGACY_V1_CAPABILITIES = Object.freeze([
+  "saga",
+  "signals",
+  "search-attributes",
+  "priority",
+  "entities",
+  "child-workflows",
+  "singleton",
+  "schedules",
+  "continue-as-new",
+  "queries",
+  "cancellation"
+]);
+function isLegacyDescriptor(raw) {
+  return raw.protocol === void 0;
+}
+__name(isLegacyDescriptor, "isLegacyDescriptor");
+function normalizeDescriptor(raw) {
+  return {
+    instanceId: raw.instanceId,
+    runtime: raw.runtime,
+    sdk: raw.sdk ?? {
+      name: "unknown",
+      version: "0"
+    },
+    protocol: raw.protocol ?? {
+      ...LEGACY_V1_PROTOCOL
+    },
+    capabilities: raw.capabilities ?? [
+      ...LEGACY_V1_CAPABILITIES
+    ],
+    workflows: raw.workflows ?? [],
+    steps: raw.steps ?? [],
+    ...raw.partition !== void 0 ? {
+      partition: raw.partition
+    } : {},
+    ...raw.namespace !== void 0 ? {
+      namespace: raw.namespace
+    } : {},
+    startedAt: raw.startedAt ?? 0
+  };
+}
+__name(normalizeDescriptor, "normalizeDescriptor");
+function canonicalizeForHash(d) {
+  const set = /* @__PURE__ */ __name((xs) => [
+    ...new Set(xs)
+  ].sort(), "set");
+  return {
+    instanceId: d.instanceId,
+    runtime: d.runtime,
+    sdk: {
+      name: d.sdk.name,
+      version: d.sdk.version
+    },
+    protocol: {
+      version: d.protocol.version,
+      range: [
+        d.protocol.range[0],
+        d.protocol.range[1]
+      ]
+    },
+    capabilities: set(d.capabilities),
+    workflows: set(d.workflows),
+    steps: set(d.steps),
+    partition: d.partition ?? null,
+    namespace: d.namespace ?? null,
+    startedAt: d.startedAt
+  };
+}
+__name(canonicalizeForHash, "canonicalizeForHash");
+function fnv1a64Hex(input) {
+  const OFFSET = 0xcbf29ce484222325n;
+  const PRIME = 0x100000001b3n;
+  const MASK = 0xffffffffffffffffn;
+  let hash = OFFSET;
+  for (let i = 0; i < input.length; i += 1) {
+    hash ^= BigInt(input.charCodeAt(i) & 255);
+    hash ^= BigInt(input.charCodeAt(i) >> 8 & 255);
+    hash = hash * PRIME & MASK;
+  }
+  return hash.toString(16).padStart(16, "0");
+}
+__name(fnv1a64Hex, "fnv1a64Hex");
+function descriptorHash(descriptor) {
+  const canonical = canonicalizeForHash(normalizeDescriptor(descriptor));
+  return fnv1a64Hex(JSON.stringify(canonical));
+}
+__name(descriptorHash, "descriptorHash");
+function heartbeatStatus(descriptor, opts = {}) {
+  return {
+    ts: opts.ts ?? Date.now(),
+    status: opts.status ?? "up",
+    descriptorHash: descriptorHash(descriptor)
+  };
+}
+__name(heartbeatStatus, "heartbeatStatus");
+
+// src/handshake/negotiate.ts
+var rangesOverlap = /* @__PURE__ */ __name((a, b) => Math.max(a[0], b[0]) <= Math.min(a[1], b[1]), "rangesOverlap");
+var difference = /* @__PURE__ */ __name((a, b) => {
+  const bset = new Set(b);
+  return [
+    ...new Set(a)
+  ].filter((x) => !bset.has(x)).sort();
+}, "difference");
+var intersection = /* @__PURE__ */ __name((a, b) => {
+  const bset = new Set(b);
+  return [
+    ...new Set(a)
+  ].filter((x) => bset.has(x)).sort();
+}, "intersection");
+function negotiate(localRaw, remoteRaw, opts = {}) {
+  const local = normalizeDescriptor(localRaw);
+  const remote = normalizeDescriptor(remoteRaw);
+  const localRange = local.protocol.range;
+  const remoteRange = remote.protocol.range;
+  const shared = intersection(local.capabilities, remote.capabilities);
+  const missingOnRemote = difference(local.capabilities, remote.capabilities);
+  const missingOnLocal = difference(remote.capabilities, local.capabilities);
+  const capabilities = {
+    shared,
+    missingOnRemote,
+    missingOnLocal
+  };
+  if (!rangesOverlap(localRange, remoteRange)) {
+    return {
+      outcome: "incompatible",
+      negotiatedProtocol: null,
+      protocol: {
+        localRange,
+        remoteRange
+      },
+      capabilities,
+      reason: {
+        code: "protocol.incompatible",
+        message: `no common protocol major: local speaks [${localRange[0]}, ${localRange[1]}], remote speaks [${remoteRange[0]}, ${remoteRange[1]}]`,
+        detail: {
+          localRange,
+          remoteRange
+        }
+      },
+      local,
+      remote
+    };
+  }
+  const negotiatedProtocol = Math.min(localRange[1], remoteRange[1]);
+  const required = opts.required ?? [];
+  const missingRequired = difference(required, remote.capabilities);
+  if (missingRequired.length > 0) {
+    return {
+      outcome: "degraded",
+      negotiatedProtocol,
+      protocol: {
+        localRange,
+        remoteRange
+      },
+      capabilities,
+      reason: {
+        code: "capability.unavailable",
+        message: `remote is missing required capability(ies): ${missingRequired.join(", ")}`,
+        detail: {
+          missingRequired,
+          missingOnRemote,
+          missingOnLocal
+        }
+      },
+      local,
+      remote
+    };
+  }
+  if (missingOnRemote.length > 0 || missingOnLocal.length > 0) {
+    const parts = [];
+    if (missingOnRemote.length > 0) parts.push(`remote lacks ${missingOnRemote.join(", ")}`);
+    if (missingOnLocal.length > 0) parts.push(`local lacks ${missingOnLocal.join(", ")}`);
+    return {
+      outcome: "degraded",
+      negotiatedProtocol,
+      protocol: {
+        localRange,
+        remoteRange
+      },
+      capabilities,
+      reason: {
+        code: "capability.unavailable",
+        message: `capability mismatch: ${parts.join("; ")}`,
+        detail: {
+          missingOnRemote,
+          missingOnLocal
+        }
+      },
+      local,
+      remote
+    };
+  }
+  return {
+    outcome: "compatible",
+    negotiatedProtocol,
+    protocol: {
+      localRange,
+      remoteRange
+    },
+    capabilities,
+    local,
+    remote
+  };
+}
+__name(negotiate, "negotiate");
+
+// src/handshake/routing.ts
+function requiredCapabilities(handler) {
+  const list = Array.isArray(handler) ? handler : handler.requires ?? [];
+  return [
+    ...new Set(list)
+  ];
+}
+__name(requiredCapabilities, "requiredCapabilities");
+function canRoute(handler, worker) {
+  const required = requiredCapabilities(handler);
+  if (required.length === 0) return true;
+  const advertised = new Set(normalizeDescriptor(worker).capabilities);
+  return required.every((cap) => advertised.has(cap));
+}
+__name(canRoute, "canRoute");
+function missingCapabilities(handler, worker) {
+  const advertised = new Set(normalizeDescriptor(worker).capabilities);
+  return requiredCapabilities(handler).filter((cap) => !advertised.has(cap));
+}
+__name(missingCapabilities, "missingCapabilities");
+function capableWorkers(handler, workers) {
+  return workers.filter((w) => canRoute(handler, w));
+}
+__name(capableWorkers, "capableWorkers");
+function resolveRouting(handler, workers) {
+  const requires = requiredCapabilities(handler);
+  const capable = capableWorkers(handler, workers).map(normalizeDescriptor);
+  if (capable.length > 0) {
+    return {
+      status: "routable",
+      workers: capable,
+      requires
+    };
+  }
+  const suffix = requires.length > 0 ? ` (requires ${requires.join(", ")})` : "";
+  return {
+    status: "blocked",
+    reason: `blocked: no compatible worker${suffix}`,
+    requires
+  };
+}
+__name(resolveRouting, "resolveRouting");
+
+// src/handshake/dispatch-routing.ts
+function controlPlaneDescriptor(opts) {
+  const version = CURRENT_PROTOCOL_VERSION;
+  return {
+    instanceId: opts.instanceId,
+    runtime: "node",
+    sdk: opts.sdk ?? {
+      name: "@dudousxd/nestjs-durable-core",
+      version: String(version)
+    },
+    protocol: opts.protocol ?? {
+      version,
+      range: [
+        version,
+        version
+      ]
+    },
+    capabilities: opts.capabilities ?? [],
+    workflows: [],
+    steps: [],
+    ...opts.partition !== void 0 ? {
+      partition: opts.partition
+    } : {},
+    ...opts.namespace !== void 0 ? {
+      namespace: opts.namespace
+    } : {},
+    startedAt: opts.startedAt ?? 0
+  };
+}
+__name(controlPlaneDescriptor, "controlPlaneDescriptor");
+var WorkflowBlocked = class extends Error {
+  static {
+    __name(this, "WorkflowBlocked");
+  }
+  plan;
+  constructor(plan) {
+    super(plan.reason), this.plan = plan;
+    this.name = "WorkflowBlocked";
+  }
+};
+function planDispatch(requires, liveDescriptors, cp, token) {
+  const required = requiredCapabilities({
+    requires
+  });
+  const workers = liveDescriptors.map(normalizeDescriptor);
+  const capable = workers.filter((w) => canRoute({
+    requires
+  }, w));
+  const compatible = capable.filter((w) => negotiate(cp, w).outcome !== "incompatible");
+  if (compatible.length > 0) return {
+    status: "routable",
+    workers: compatible
+  };
+  if (capable.length > 0) {
+    const workerRanges = capable.map((w) => w.protocol.range);
+    return {
+      status: "blocked",
+      code: "protocol.incompatible",
+      reason: `blocked: no protocol-compatible worker${required.length > 0 ? ` (requires ${required.join(", ")})` : ""}`,
+      requires: required,
+      diagnostics: {
+        code: "protocol.incompatible",
+        token,
+        requires: required,
+        liveWorkers: workers.length,
+        controlPlaneRange: cp.protocol.range,
+        workerRanges,
+        controlPlane: cp,
+        workers
+      }
+    };
+  }
+  const advertised = new Set(workers.flatMap((w) => w.capabilities));
+  const missingCapabilities2 = required.filter((cap) => !advertised.has(cap));
+  return {
+    status: "blocked",
+    code: "capability.unavailable",
+    reason: `blocked: no compatible worker${required.length > 0 ? ` (requires ${required.join(", ")})` : ""}`,
+    requires: required,
+    diagnostics: {
+      code: "capability.unavailable",
+      token,
+      requires: required,
+      liveWorkers: workers.length,
+      missingCapabilities: missingCapabilities2,
+      controlPlane: cp,
+      workers
+    }
+  };
+}
+__name(planDispatch, "planDispatch");
+
 // src/tenant-group.ts
 function tenantGroup(baseGroup, tenant) {
   return tenant !== void 0 && tenant !== "" && tenant !== "default" ? `${baseGroup}@${tenant}` : baseGroup;
@@ -1177,6 +1545,22 @@ var TransportPool = class {
       transport.onStartRun?.(handler);
     }
   }
+  /**
+  * The live handshake descriptors advertised for `group` (design §7.2), merged across every transport
+  * that can report them. Returns `[]` when NO transport implements
+  * {@link Transport.readWorkerDescriptors} (a pure in-process pool) OR when descriptors are supported
+  * but none is published — both are the "guard disengaged / legacy assume-compatible" case, so the
+  * engine's routing guard treats an empty result identically (design §7.7).
+  */
+  async readWorkerDescriptors(group) {
+    const descriptors = [];
+    for (const { transport } of this.transports) {
+      if (transport.readWorkerDescriptors) {
+        descriptors.push(...await transport.readWorkerDescriptors(group));
+      }
+    }
+    return descriptors;
+  }
   /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
   async listWorkerGroups() {
     const groups = /* @__PURE__ */ new Set();
@@ -1272,6 +1656,8 @@ function resolveStepPolicy(config, opts) {
   if (jitter !== void 0) policy.jitter = jitter;
   const timeoutMs = opts?.timeoutMs ?? config?.timeoutMs;
   if (timeoutMs !== void 0) policy.timeoutMs = timeoutMs;
+  const requires = opts?.requires ?? config?.requires;
+  if (requires !== void 0) policy.requires = requires;
   return policy;
 }
 __name(resolveStepPolicy, "resolveStepPolicy");
@@ -1977,6 +2363,10 @@ var WorkflowEngine = class {
   eventBufferTtlMs;
   remoteRedispatchMs;
   remoteRedispatchMax;
+  /** How long a `blocked` run waits before the recovery poll re-checks the live fleet (design §7.5). */
+  blockedPollMs;
+  /** This engine's control-plane handshake descriptor — negotiated against each worker (design §7.3). */
+  cpDescriptor;
   webhookUrl;
   traceparent;
   context;
@@ -2048,6 +2438,13 @@ var WorkflowEngine = class {
     this.eventBufferTtlMs = deps.eventBufferTtlMs || void 0;
     this.remoteRedispatchMs = deps.remoteRedispatchMs || void 0;
     this.remoteRedispatchMax = Math.max(1, deps.remoteRedispatchMax ?? 10);
+    this.blockedPollMs = deps.blockedPollMs ?? 5e3;
+    this.cpDescriptor = controlPlaneDescriptor({
+      instanceId: `cp-${this.instanceId}`,
+      ...this.namespace !== void 0 ? {
+        namespace: this.namespace
+      } : {}
+    });
     this.webhookUrl = deps.webhookUrl;
     this.traceparent = deps.traceparent;
     this.context = deps.context;
@@ -2201,6 +2598,7 @@ var WorkflowEngine = class {
       searchAttributesSchema: opts?.searchAttributesSchema,
       onEvent: opts?.onEvent,
       eventBatch: opts?.eventBatch,
+      requires: opts?.requires,
       // A real, retained in-process body — so `workflowBody` can hand it to an in-app worker, and so
       // it is NOT confused with the throwing stub `registerRemote` installs for a body-less remote.
       hasBody: true
@@ -2249,6 +2647,7 @@ var WorkflowEngine = class {
       singleton: opts.singleton,
       executionTimeoutMs: opts.executionTimeout != null ? parseDuration(opts.executionTimeout) : void 0,
       validateInput: opts.validateInput,
+      requires: opts.requires,
       remote: {
         group: opts.group,
         executor: opts.executor
@@ -2732,9 +3131,13 @@ var WorkflowEngine = class {
   */
   async resumeDueTimers(nowMs = this.clock()) {
     const due = await this.store.listDueTimers(nowMs, this.namespace);
-    if (due.length === 0) return [];
+    const blocked = await this.dueBlockedRuns(nowMs);
+    if (due.length === 0 && blocked.length === 0) return [];
     const waiterByRun = indexWaitersByRun(await this.store.listSignalWaiters(""));
-    return this.resumeLeased(due, nowMs, (run) => this.reconcileSignalWaiter(run, waiterByRun.get(run.id)));
+    return this.resumeLeased([
+      ...due,
+      ...blocked
+    ], nowMs, (run) => this.reconcileSignalWaiter(run, waiterByRun.get(run.id)));
   }
   /**
   * The reconcile safety net's per-run check (see {@link resumeDueTimers}): if this suspended run has
@@ -2817,7 +3220,10 @@ var WorkflowEngine = class {
   * inline — or null if the run is unknown. The dashboard "retry" goes through here so it can't block
   * the HTTP request on workflow execution.
   */
-  async requeue(runId) {
+  async requeue(runId, _seen) {
+    const seen = _seen ?? /* @__PURE__ */ new Set();
+    if (seen.has(runId)) return null;
+    seen.add(runId);
     const run = await this.store.getRun(runId);
     if (!run) return null;
     if (run.status === "failed" || run.status === "dead") {
@@ -2841,12 +3247,28 @@ var WorkflowEngine = class {
             status: "running",
             output: void 0
           });
+          const childId = cp.name.slice("signal:child:".length);
+          const parked = [];
+          for (; ; ) {
+            const buffered = await this.store.takeBufferedSignal(`child:${childId}`);
+            if (!buffered) break;
+            parked.push(buffered.payload);
+          }
+          for (const payload of parked) await this.store.bufferSignal(`child:${childId}`, payload);
+          const bufferedSuccess = parked.some((payload) => typeof payload === "object" && payload !== null && payload.ok === true);
+          if (!bufferedSuccess) {
+            const child = await this.store.getRun(childId);
+            if (child && (child.status === "failed" || child.status === "dead")) {
+              await this.requeue(childId, seen);
+            }
+          }
         }
       }
     }
     await this.store.releaseRunLock(runId);
     await this.store.updateRun(runId, {
       status: "pending",
+      error: void 0,
       updatedAt: /* @__PURE__ */ new Date()
     });
     await this.runDispatcher.dispatch(runId);
@@ -3166,6 +3588,10 @@ var WorkflowEngine = class {
   */
   notifyParent(runId, completion) {
     void this.signal(`child:${runId}`, completion).catch(() => void 0);
+    const at = runId.lastIndexOf("~retry~");
+    if (at !== -1 && completion.ok) {
+      void this.signal(`child:${runId.slice(0, at)}`, completion).catch(() => void 0);
+    }
   }
   /**
   * Deferred child start shared by the in-process ctx host and the remote `startChild` command.
@@ -3620,6 +4046,7 @@ var WorkflowEngine = class {
         error: outcome.error
       };
     }
+    if (outcome.kind === "blocked") return this.parkBlocked(run, outcome.blocked);
     const latest = await this.store.getRun(run.id);
     if (latest?.status === "cancelled") {
       return {
@@ -3719,6 +4146,8 @@ var WorkflowEngine = class {
         status: "suspended"
       };
     }
+    const wfPlan = await this.planRoute(tenantGroup(sanitizeQueueToken(remote.group), void 0), registered.requires);
+    if (wfPlan?.status === "blocked") return this.parkBlocked(run, wfPlan);
     const history = await this.remoteHistory(run.id);
     if (remote.executor.dispatch) {
       const taskId = `${run.id}:wf:${globalThis.crypto.randomUUID().slice(0, 8)}`;
@@ -4142,6 +4571,15 @@ var WorkflowEngine = class {
           status: "completed"
         };
       }
+      if (err instanceof WorkflowBlocked) {
+        if (this.cancelRequested.has(run.id)) {
+          return this.compensateAndCancel(run, compensations, replay);
+        }
+        return this.settleRun(run, {
+          kind: "blocked",
+          blocked: err.plan
+        });
+      }
       if (err instanceof WorkflowSuspended) {
         if (this.cancelRequested.has(run.id)) {
           return this.compensateAndCancel(run, compensations, replay);
@@ -4488,6 +4926,85 @@ var WorkflowEngine = class {
       run: result
     };
   }
+  /**
+  * Plan a dispatch to `token` for a handler requiring `requires` (handshake design §7.5). Returns:
+  * - `undefined` — NO live descriptors published on this token: the guard does not engage, so a
+  *   pre-handshake fleet (or an in-process transport that advertises none) keeps flowing exactly as
+  *   before (design §7.7);
+  * - a `routable` plan — ≥1 live worker is capability-capable AND protocol-compatible (dispatch);
+  * - a `blocked` plan — descriptors exist but none can run it (park the run, never dispatch into it).
+  */
+  async planRoute(token, requires) {
+    const descriptors = await this.pool.readWorkerDescriptors(token);
+    if (descriptors.length === 0) return void 0;
+    return planDispatch(requires ?? [], descriptors, this.cpDescriptor, token);
+  }
+  /** Throw {@link WorkflowBlocked} when no live worker can run a dispatch to `token` — so the caller's
+  *  run-execution catch parks the run `blocked` (with the plan) instead of persisting a `pending`
+  *  checkpoint + dispatching into a queue nobody consumes (design §7.5). A no-op when the guard does
+  *  not engage (no descriptors) or a capable+compatible worker exists. */
+  async ensureRoutable(token, requires) {
+    const plan = await this.planRoute(token, requires);
+    if (plan?.status === "blocked") throw new WorkflowBlocked(plan);
+  }
+  /**
+  * Park a run `blocked` (handshake design §7.5/§7.6): no live worker on its next-dispatch group is
+  * capability-capable + protocol-compatible. Persists the `blocked` status with a human reason + the
+  * machine `code` + a `wakeAt` so the blocked-recovery poll re-drives it, emits the LOUD structured
+  * `capability.unavailable`/`protocol.incompatible` diagnostics (both descriptors + the precise delta),
+  * and releases the run lease so any instance can re-drive it. Re-checks the persisted status first so
+  * a concurrent cancel/complete is never clobbered. `releaseRunLock` is idempotent, so a caller whose
+  * own `finally` also releases (the run-execution path) is safe.
+  */
+  async parkBlocked(run, blocked) {
+    const current = await this.store.getRun(run.id);
+    if (current && (current.status === "cancelled" || current.status === "completed")) {
+      await this.store.releaseRunLock(run.id);
+      return {
+        runId: run.id,
+        status: current.status,
+        output: current.output,
+        error: current.error
+      };
+    }
+    const error = {
+      message: blocked.reason,
+      code: blocked.code,
+      retryable: true
+    };
+    await this.store.updateRun(run.id, {
+      status: "blocked",
+      error,
+      wakeAt: this.clock() + this.blockedPollMs,
+      updatedAt: /* @__PURE__ */ new Date()
+    });
+    this.emit({
+      type: "run.blocked",
+      runId: run.id,
+      workflow: run.workflow,
+      namespace: run.namespace,
+      error,
+      requires: blocked.requires,
+      diagnostics: blocked.diagnostics
+    });
+    await this.store.releaseRunLock(run.id);
+    return {
+      runId: run.id,
+      status: "blocked",
+      error
+    };
+  }
+  /** Runs parked `blocked` whose recovery poll is due (`wakeAt <= nowMs`), namespace-scoped like
+  *  {@link resumeDueTimers}. Re-driving one re-checks the live fleet: it dispatches if a
+  *  capable+compatible worker has appeared, else re-parks with a fresh `wakeAt` (design §7.5). */
+  async dueBlockedRuns(nowMs) {
+    const blocked = await this.store.listRuns({
+      statuses: [
+        "blocked"
+      ]
+    });
+    return blocked.filter((r) => (this.namespace === void 0 || r.namespace === void 0 || r.namespace === this.namespace) && r.wakeAt !== void 0 && r.wakeAt <= nowMs);
+  }
   async callRemote(runId, seq, step, input, queue, transport, replay, admission) {
     const existing = replay?.get(seq) ?? await this.store.getCheckpoint(runId, seq);
     if (existing && existing.name !== step.name) {
@@ -4553,6 +5070,7 @@ var WorkflowEngine = class {
       if (this.clock() < existing.wakeAt) throw new WorkflowSuspended(existing.wakeAt);
       attempt = existing.attempts + 1;
     }
+    await this.ensureRoutable(tenantGroup(sanitizeQueueToken(step.name), step.partition), step.requires);
     const id = stepId(runId, seq);
     if (queue && this.admission.handles(queue)) {
       const decision = await this.admission.tryAdmit(queue, {
@@ -4739,6 +5257,7 @@ var WorkflowEngine = class {
   /** In-memory await path for a remote step with a liveness `timeoutMs` (re-dispatch on timeout). */
   async callRemoteInMemory(runId, seq, step, input, transport) {
     if (this.pool.size === 0) throw new Error("remote steps require a Transport");
+    await this.ensureRoutable(tenantGroup(sanitizeQueueToken(step.name), step.partition), step.requires);
     const validInput = step.input ? step.input.parse(input) : input;
     const id = stepId(runId, seq);
     const enqueuedAt = /* @__PURE__ */ new Date();
@@ -5638,6 +6157,7 @@ var InMemoryTransport = class {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONTROL_FLOW_SIGNAL,
+  CURRENT_PROTOCOL_VERSION,
   CodecStateStore,
   ContinueAsNew,
   DURABLE_OPTIONS,
@@ -5654,6 +6174,8 @@ var InMemoryTransport = class {
   InMemoryAdmissionBackend,
   InMemoryStateStore,
   InMemoryTransport,
+  LEGACY_V1_CAPABILITIES,
+  LEGACY_V1_PROTOCOL,
   NonDeterminismError,
   QueueController,
   RemoteStepError,
@@ -5668,6 +6190,7 @@ var InMemoryTransport = class {
   TRANSPORT,
   TRANSPORT_CANONICAL,
   WORKFLOW_NAME_KEY,
+  WorkflowBlocked,
   WorkflowEngine,
   WorkflowSuspended,
   applyAttributeQuery,
@@ -5675,23 +6198,35 @@ var InMemoryTransport = class {
   attributeOperand,
   bindWorkflowClass,
   breakpointToken,
+  canRoute,
+  capableWorkers,
   classifyWaiterToken,
   collectMetrics,
+  controlPlaneDescriptor,
   createStepLogger,
   currentWorkflowCtx,
+  descriptorHash,
   eventMatchOf,
   eventMatches,
   eventNameOf,
   eventPrefix,
   eventToken,
+  heartbeatStatus,
   indexWaitersByRun,
   isEventToken,
+  isLegacyDescriptor,
   isWorkflowControlFlowSignal,
   matchesAttributes,
+  missingCapabilities,
+  negotiate,
   normalizeAttributeRows,
+  normalizeDescriptor,
   parseDuration,
+  planDispatch,
   prevCronFireMs,
   readSearchAttributes,
+  requiredCapabilities,
+  resolveRouting,
   resolveRunWaiting,
   runInWorkflowCtx,
   runSchedules,