@dudousxd/nestjs-durable-core 0.64.0 → 0.66.0

package/dist/index.cjs

@@ -26,6 +26,7 @@ __export(index_exports, {
   CURRENT_PROTOCOL_VERSION: () => CURRENT_PROTOCOL_VERSION,
   CodecStateStore: () => CodecStateStore,
   ContinueAsNew: () => ContinueAsNew,
+  DEFAULT_PARTITION: () => DEFAULT_PARTITION,
   DURABLE_OPTIONS: () => DURABLE_OPTIONS,
   DURABLE_OPTIONS_CANONICAL: () => DURABLE_OPTIONS_CANONICAL,
   DURABLE_STEP_CONFIG: () => DURABLE_STEP_CONFIG,
@@ -56,25 +57,31 @@ __export(index_exports, {
   TERMINAL_RUN_STATUSES: () => TERMINAL_RUN_STATUSES,
   TRANSPORT: () => TRANSPORT,
   TRANSPORT_CANONICAL: () => TRANSPORT_CANONICAL,
+  VERSION_UNDECLARED_TAG: () => VERSION_UNDECLARED_TAG,
   WORKFLOW_NAME_KEY: () => WORKFLOW_NAME_KEY,
   WorkflowBlocked: () => WorkflowBlocked,
   WorkflowEngine: () => WorkflowEngine,
   WorkflowSuspended: () => WorkflowSuspended,
+  aggregateAnnouncements: () => aggregateAnnouncements,
+  announcementsOf: () => announcementsOf,
   applyAttributeQuery: () => applyAttributeQuery,
   attributeColumnFor: () => attributeColumnFor,
   attributeOperand: () => attributeOperand,
   bindWorkflowClass: () => bindWorkflowClass,
   breakpointToken: () => breakpointToken,
+  buildWorkflowDirectory: () => buildWorkflowDirectory,
   canRoute: () => canRoute,
   capableWorkers: () => capableWorkers,
   classifyWaiterToken: () => classifyWaiterToken,
   clearDurableExecutionWrappers: () => clearDurableExecutionWrappers,
   collectMetrics: () => collectMetrics,
   controlPlaneDescriptor: () => controlPlaneDescriptor,
+  coveredTokens: () => coveredTokens,
   createStepLogger: () => createStepLogger,
   currentStep: () => currentStep,
   currentWorkflowCtx: () => currentWorkflowCtx,
   debug: () => debug,
+  describeWorker: () => describeWorker,
   descriptorHash: () => descriptorHash,
   error: () => error,
   eventMatchOf: () => eventMatchOf,
@@ -95,7 +102,9 @@ __export(index_exports, {
   negotiate: () => negotiate,
   normalizeAttributeRows: () => normalizeAttributeRows,
   normalizeDescriptor: () => normalizeDescriptor,
+  observedAnnouncements: () => observedAnnouncements,
   parseDuration: () => parseDuration,
+  partitionOfToken: () => partitionOfToken,
   planDispatch: () => planDispatch,
   prevCronFireMs: () => prevCronFireMs,
   readSearchAttributes: () => readSearchAttributes,
@@ -1103,6 +1112,9 @@ function normalizeDescriptor(raw) {
     ],
     workflows: raw.workflows ?? [],
     steps: raw.steps ?? [],
+    ...raw.registrations !== void 0 ? {
+      registrations: raw.registrations
+    } : {},
     ...raw.partition !== void 0 ? {
       partition: raw.partition
     } : {},
@@ -1113,6 +1125,23 @@ function normalizeDescriptor(raw) {
   };
 }
 __name(normalizeDescriptor, "normalizeDescriptor");
+function canonicalizeRegistrations(regs) {
+  const canonical = regs.map((r) => ({
+    name: r.name,
+    version: r.version ?? null,
+    group: r.group ?? null,
+    requires: r.requires ? [
+      ...new Set(r.requires)
+    ].sort() : null,
+    origin: r.origin ?? null
+  }));
+  const byJson = /* @__PURE__ */ new Map();
+  for (const entry of canonical) byJson.set(JSON.stringify(entry), entry);
+  return [
+    ...byJson.keys()
+  ].sort().map((k) => byJson.get(k));
+}
+__name(canonicalizeRegistrations, "canonicalizeRegistrations");
 function canonicalizeForHash(d) {
   const set = /* @__PURE__ */ __name((xs) => [
     ...new Set(xs)
@@ -1134,6 +1163,9 @@ function canonicalizeForHash(d) {
     capabilities: set(d.capabilities),
     workflows: set(d.workflows),
     steps: set(d.steps),
+    ...d.registrations !== void 0 ? {
+      registrations: canonicalizeRegistrations(d.registrations)
+    } : {},
     partition: d.partition ?? null,
     namespace: d.namespace ?? null,
     startedAt: d.startedAt
@@ -1166,6 +1198,276 @@ function heartbeatStatus(descriptor, opts = {}) {
   };
 }
 __name(heartbeatStatus, "heartbeatStatus");
+function describeWorker(opts) {
+  const version = CURRENT_PROTOCOL_VERSION;
+  const registrations = [
+    ...opts.registrations ?? []
+  ].sort((a, b) => `${a.name}@${a.version ?? ""}`.localeCompare(`${b.name}@${b.version ?? ""}`));
+  return {
+    instanceId: opts.instanceId,
+    runtime: opts.runtime,
+    sdk: {
+      name: opts.sdk.name,
+      version: opts.sdk.version
+    },
+    protocol: {
+      version,
+      range: [
+        version,
+        version
+      ]
+    },
+    capabilities: [
+      ...LEGACY_V1_CAPABILITIES
+    ],
+    workflows: [
+      ...opts.workflows ?? []
+    ].sort(),
+    steps: [
+      ...opts.steps
+    ].sort(),
+    ...registrations.length > 0 ? {
+      registrations
+    } : {},
+    ...opts.partition ? {
+      partition: opts.partition
+    } : {},
+    ...opts.namespace && opts.namespace !== "default" ? {
+      namespace: opts.namespace
+    } : {},
+    startedAt: opts.startedAt
+  };
+}
+__name(describeWorker, "describeWorker");
+
+// src/handshake/announced.ts
+function announcementsOf(raw) {
+  const d = normalizeDescriptor(raw);
+  const identity = {
+    instanceId: d.instanceId,
+    runtime: d.runtime
+  };
+  const announcements = (d.registrations ?? []).map((reg) => ({
+    ...reg,
+    ...identity
+  }));
+  const covered = new Set(announcements.map((a) => a.name));
+  for (const name of d.workflows) {
+    if (!covered.has(name)) announcements.push({
+      name,
+      ...identity
+    });
+  }
+  return announcements;
+}
+__name(announcementsOf, "announcementsOf");
+function announcementKey(a) {
+  return a.version === void 0 ? a.name : `${a.name}@${a.version}`;
+}
+__name(announcementKey, "announcementKey");
+function stated(values) {
+  return [
+    ...new Set(values.filter((v) => v !== void 0))
+  ].sort();
+}
+__name(stated, "stated");
+function aggregateAnnouncements(descriptors) {
+  const byKey = /* @__PURE__ */ new Map();
+  for (const descriptor of descriptors) {
+    for (const announcement of announcementsOf(descriptor)) {
+      const key = announcementKey(announcement);
+      const bucket = byKey.get(key);
+      if (bucket) bucket.push(announcement);
+      else byKey.set(key, [
+        announcement
+      ]);
+    }
+  }
+  const out = [];
+  for (const [key, announcements] of byKey) {
+    const groups = stated(announcements.map((a) => a.group));
+    const origins = stated(announcements.map((a) => a.origin));
+    const requiresByJson = /* @__PURE__ */ new Map();
+    for (const a of announcements) {
+      if (a.requires === void 0) continue;
+      const canonical = [
+        ...new Set(a.requires)
+      ].sort();
+      requiresByJson.set(JSON.stringify(canonical), canonical);
+    }
+    const requires = [
+      ...requiresByJson.values()
+    ].sort((x, y) => x.join(",").localeCompare(y.join(",")));
+    const disagreements = [];
+    if (groups.length > 1) disagreements.push({
+      axis: "group",
+      values: groups
+    });
+    if (origins.length > 1) disagreements.push({
+      axis: "origin",
+      values: origins
+    });
+    if (requires.length > 1) {
+      disagreements.push({
+        axis: "requires",
+        values: requires.map((r) => r.join(","))
+      });
+    }
+    const first = announcements[0];
+    if (!first) continue;
+    out.push({
+      evidence: "declared",
+      key,
+      name: first.name,
+      ...first.version !== void 0 ? {
+        version: first.version
+      } : {},
+      groups,
+      origins,
+      requires,
+      runtimes: [
+        ...new Set(announcements.map((a) => a.runtime))
+      ].sort(),
+      instances: [
+        ...new Set(announcements.map((a) => a.instanceId))
+      ].sort(),
+      disagreements
+    });
+  }
+  return out.sort((a, b) => a.key.localeCompare(b.key));
+}
+__name(aggregateAnnouncements, "aggregateAnnouncements");
+function observedAnnouncements(heartbeats, covered) {
+  const byToken = /* @__PURE__ */ new Map();
+  for (const beat of heartbeats) {
+    if (!beat.group || covered.has(beat.group)) continue;
+    const instances = byToken.get(beat.group);
+    if (instances) instances.add(beat.instanceId);
+    else byToken.set(beat.group, /* @__PURE__ */ new Set([
+      beat.instanceId
+    ]));
+  }
+  return [
+    ...byToken.entries()
+  ].map(([group, instances]) => ({
+    evidence: "observed",
+    key: group,
+    name: group,
+    groups: [
+      group
+    ],
+    origins: [],
+    requires: [],
+    runtimes: [],
+    instances: [
+      ...instances
+    ].sort(),
+    disagreements: []
+  })).sort((a, b) => a.key.localeCompare(b.key));
+}
+__name(observedAnnouncements, "observedAnnouncements");
+function coveredTokens(announced, descriptors, sanitize) {
+  const tokens = /* @__PURE__ */ new Set();
+  for (const entry of announced) {
+    tokens.add(sanitize(entry.name));
+    for (const group of entry.groups) tokens.add(group);
+  }
+  for (const raw of descriptors) {
+    const d = normalizeDescriptor(raw);
+    for (const step of d.steps) {
+      const token = sanitize(step);
+      tokens.add(token);
+      if (d.partition) tokens.add(`${token}@${d.partition}`);
+    }
+  }
+  return tokens;
+}
+__name(coveredTokens, "coveredTokens");
+
+// src/handshake/directory.ts
+var DEFAULT_PARTITION = "default";
+function partitionOfToken(token) {
+  const at = token.lastIndexOf("@");
+  return at === -1 ? DEFAULT_PARTITION : token.slice(at + 1);
+}
+__name(partitionOfToken, "partitionOfToken");
+function buildWorkflowDirectory(input) {
+  const { descriptors, heartbeats, namespace, supported, sanitize } = input;
+  if (!supported) {
+    return {
+      supported: false,
+      workflows: [],
+      otherPartitions: [],
+      detail: "No transport in this process can read what the fleet advertises, so nothing here was asked and this list is empty for that reason alone. Workers may well be running. A workflow can still be called by name."
+    };
+  }
+  const mine = namespace === void 0 ? void 0 : namespace;
+  const ownDescriptors = mine === void 0 ? descriptors : descriptors.filter((d) => (d.namespace ?? DEFAULT_PARTITION) === mine);
+  const ownBeats = [];
+  const foreign = /* @__PURE__ */ new Map();
+  for (const beat of heartbeats) {
+    if (!beat.group) continue;
+    const partition = partitionOfToken(beat.group);
+    if (mine === void 0 || partition === mine) {
+      ownBeats.push(beat);
+      continue;
+    }
+    const seen = foreign.get(partition);
+    if (seen) {
+      seen.groups.add(beat.group);
+      seen.instances.add(beat.instanceId);
+    } else {
+      foreign.set(partition, {
+        groups: /* @__PURE__ */ new Set([
+          beat.group
+        ]),
+        instances: /* @__PURE__ */ new Set([
+          beat.instanceId
+        ])
+      });
+    }
+  }
+  const declared = aggregateAnnouncements(ownDescriptors);
+  const observed = observedAnnouncements(ownBeats, coveredTokens(declared, ownDescriptors, sanitize));
+  const workflows = [
+    ...declared,
+    ...observed
+  ].sort((a, b) => a.key.localeCompare(b.key));
+  const otherPartitions = [
+    ...foreign.entries()
+  ].map(([partition, seen]) => ({
+    partition,
+    groups: [
+      ...seen.groups
+    ].sort(),
+    instances: [
+      ...seen.instances
+    ].sort()
+  })).sort((a, b) => a.partition.localeCompare(b.partition));
+  return {
+    supported: true,
+    workflows,
+    otherPartitions,
+    detail: describeDirectory(workflows, otherPartitions, mine)
+  };
+}
+__name(buildWorkflowDirectory, "buildWorkflowDirectory");
+function summarize(names, limit = 3) {
+  if (names.length <= limit) return names.join(", ");
+  return `${names.slice(0, limit).join(", ")} and ${names.length - limit} more`;
+}
+__name(summarize, "summarize");
+function describeDirectory(workflows, otherPartitions, namespace) {
+  const here = namespace === void 0 ? "this deployment" : `partition "${namespace}"`;
+  const elsewhere = otherPartitions.length === 0 ? "" : ` Live workers were seen on ${otherPartitions.map((p) => `"${p.partition}" (${summarize(p.groups)})`).join(", ")}, which ${here} does not route to \u2014 a worker on the wrong partition looks exactly like no worker at all, so it is named here rather than left out.`;
+  if (workflows.length === 0) {
+    return `The fleet was asked just now and nothing is live in ${here}, so this list is empty because the deployment is empty \u2014 not because the question could not be put.${elsewhere}`;
+  }
+  const observed = workflows.filter((w) => w.evidence === "observed").length;
+  const declaredNote = observed === 0 ? "" : ` ${observed} of them ${observed === 1 ? "is" : "are"} known only from a live queue: the worker serving ${observed === 1 ? "it" : "them"} publishes no description, so ${observed === 1 ? "its" : "their"} version, origin and runtime are genuinely unknown and a version pinned against ${observed === 1 ? "it" : "them"} cannot be checked.`;
+  return `Every workflow a live worker in ${here} can execute, read just now. A worker that stops beating drops off this list within about half a minute.${declaredNote}${elsewhere}`;
+}
+__name(describeDirectory, "describeDirectory");
 
 // src/handshake/negotiate.ts
 var rangesOverlap = /* @__PURE__ */ __name((a, b) => Math.max(a[0], b[0]) <= Math.min(a[1], b[1]), "rangesOverlap");
@@ -1693,6 +1995,60 @@ var TransportPool = class {
     }
     return descriptors;
   }
+  /**
+  * Every live descriptor in the deployment, merged across every transport that can report them and
+  * de-duplicated by `instanceId` — one worker publishes the same descriptor under each token it
+  * consumes, and it must count once. Returns `[]` when no transport implements
+  * {@link Transport.readAllWorkerDescriptors} (a pure in-process pool advertises nothing).
+  *
+  * First writer wins on a duplicate id: the copies are the same bytes by construction (one process,
+  * one descriptor, published N times), so there is nothing to choose between. Two DIFFERENT
+  * processes sharing an `instanceId` would collapse into one here — that is a misconfiguration the
+  * fleet already suffers from (they also share heartbeat and descriptor keys, so they overwrite each
+  * other's advertisement), not something this read can repair.
+  */
+  async readAllWorkerDescriptors() {
+    const byInstance = /* @__PURE__ */ new Map();
+    for (const { transport } of this.transports) {
+      if (!transport.readAllWorkerDescriptors) continue;
+      for (const descriptor of await transport.readAllWorkerDescriptors()) {
+        if (!byInstance.has(descriptor.instanceId)) byInstance.set(descriptor.instanceId, descriptor);
+      }
+    }
+    return [
+      ...byInstance.values()
+    ];
+  }
+  /**
+  * Every live worker heartbeat in the deployment, merged across every transport that can report
+  * them and de-duplicated by `(group, instanceId)` — the same worker is one beat per token, and two
+  * transports scanning the same keyspace must not double-count it.
+  *
+  * Returns `[]` when no transport implements {@link Transport.readAllWorkerHeartbeats}, which is
+  * indistinguishable from "nothing is beating" on its own — {@link introspectsFleet} is what tells
+  * those apart, and the directory reads it rather than guessing from an empty array.
+  */
+  async readAllWorkerHeartbeats() {
+    const seen = /* @__PURE__ */ new Map();
+    for (const { transport } of this.transports) {
+      if (!transport.readAllWorkerHeartbeats) continue;
+      for (const beat of await transport.readAllWorkerHeartbeats()) {
+        const key = `${beat.group}\0${beat.instanceId}`;
+        if (!seen.has(key)) seen.set(key, beat);
+      }
+    }
+    return [
+      ...seen.values()
+    ];
+  }
+  /**
+  * Can ANY transport here introspect the fleet — descriptors or heartbeats? This is the difference
+  * between "the fleet is empty" and "nobody asked", and it is a property of the POOL rather than of
+  * a read's result, so it stays answerable when both reads legitimately come back empty.
+  */
+  get introspectsFleet() {
+    return this.transports.some(({ transport }) => transport.readAllWorkerDescriptors || transport.readAllWorkerHeartbeats);
+  }
   /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
   async listWorkerGroups() {
     const groups = /* @__PURE__ */ new Set();
@@ -2093,7 +2449,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     return unwrapCompletion(await waitForSignal(`task:${runId}:${name}`), `task "${name}"`);
   }, "task");
   const child = /* @__PURE__ */ __name(async (workflow2, input, options) => {
-    const { childId, priority } = normalizeChildOptions(options);
+    const { childId, priority, version } = normalizeChildOptions(options);
     const current = pos.next();
     const id = childId ?? `${runId}.child.${current}`;
     const existing = await readCheckpoint(current);
@@ -2121,7 +2477,7 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
       }));
       return unwrapCompletion(buffered.payload, `child "${id}"`);
     }
-    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id, priority);
+    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id, priority, version);
     if (!existing) {
       await writeCheckpoint(instantCheckpoint({
         runId,
@@ -2204,12 +2560,12 @@ function createWorkflowCtx(host, runId, compensations, workflow = "", searchAttr
     return outputs;
   }, "all");
   const startChild = /* @__PURE__ */ __name(async (workflow2, input, options) => {
-    const { childId, priority } = normalizeChildOptions(options);
+    const { childId, priority, version } = normalizeChildOptions(options);
     const current = pos.next();
     const id = childId ?? `${runId}.child.${current}`;
     const existing = await readCheckpoint(current);
     if (existing && existing.status === "completed") return existing.output;
-    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id, priority);
+    if (!await store.getRun(id)) host.startChild(workflowName(workflow2), input, id, priority, version);
     await writeCheckpoint(instantCheckpoint({
       runId,
       seq: current,
@@ -2457,6 +2813,7 @@ function mergeTags(staticTags, runTags) {
 __name(mergeTags, "mergeTags");
 var BREAKPOINT = "breakpoint";
 var isBreakpoint = /* @__PURE__ */ __name((cp) => cp.status === "pending" && cp.name.startsWith(BREAKPOINT), "isBreakpoint");
+var VERSION_UNDECLARED_TAG = "version:undeclared";
 var versionKey = /* @__PURE__ */ __name((name, version) => `${name}@${version}`, "versionKey");
 function stepGroup(step, runNamespace) {
   return tenantGroup(sanitizeQueueToken(step.name), step.partition ?? runNamespace);
@@ -2769,6 +3126,15 @@ var WorkflowEngine = class {
     const reg = this.workflows.get(versionKey(name, version));
     return reg?.hasBody ? reg.fn : void 0;
   }
+  /** The registered versions of `name`, for the pinned-start error — "2 is not registered" is a
+  *  guess-the-typo error without them, and the answer (which versions this deploy actually carries)
+  *  is right here. `none` when the name is unknown entirely. */
+  registeredVersions(name) {
+    const versions = [
+      ...this.workflows.values()
+    ].filter((w) => w.name === name).map((w) => w.version);
+    return versions.length ? versions.join(", ") : "none";
+  }
   /**
   * Register a workflow whose body runs in another SDK (e.g. Python). The engine owns the run exactly
   * as for a TS workflow — it persists checkpoints, recovers, runs timers — but advances it by handing
@@ -2918,12 +3284,13 @@ var WorkflowEngine = class {
   }
   async start(workflow, input, runId, opts) {
     const name = workflowName(workflow);
-    let registered = this.latest.get(name);
-    if (!registered) {
+    const pinned = opts?.version;
+    let registered = pinned === void 0 ? this.latest.get(name) : this.workflows.get(versionKey(name, pinned));
+    if (!registered && pinned === void 0) {
       const ancestor = await this.findRemoteAncestor(runId);
       if (ancestor) registered = this.synthesizeRemoteChild(name, ancestor.version, ancestor);
     }
-    if (!registered) {
+    if (!registered && pinned === void 0) {
       const conventionRun = {
         id: runId,
         workflow: name,
@@ -2938,9 +3305,13 @@ var WorkflowEngine = class {
         createdAt: /* @__PURE__ */ new Date(),
         updatedAt: /* @__PURE__ */ new Date()
       };
-      registered = await this.resolveRemoteByConvention(conventionRun);
+      registered = await this.resolveRemoteByConvention(conventionRun, {
+        askFleetForVersion: true
+      });
+    }
+    if (!registered) {
+      throw new Error(pinned === void 0 ? `workflow ${name} is not registered` : `workflow ${versionKey(name, pinned)} is not registered \u2014 a pinned start never falls back to the newest version (registered: ${this.registeredVersions(name)})`);
     }
-    if (!registered) throw new Error(`workflow ${name} is not registered`);
     await registered.validateInput?.(input);
     const prior = await this.store.getRun(runId);
     if (prior) {
@@ -2952,10 +3323,16 @@ var WorkflowEngine = class {
       };
     }
     const now = /* @__PURE__ */ new Date();
-    const tags = mergeTags(registered.tags, registered.singleton ? [
+    const stampedTags = [
       ...opts?.tags ?? [],
-      this.singletons.tag(registered.singleton, input)
-    ] : opts?.tags);
+      ...registered.singleton ? [
+        this.singletons.tag(registered.singleton, input)
+      ] : [],
+      ...registered.versionDeclared === false ? [
+        VERSION_UNDECLARED_TAG
+      ] : []
+    ];
+    const tags = mergeTags(registered.tags, stampedTags);
     if (registered.singleton) {
       await this.singletons.assertCapacity(name, registered.singleton, input);
     }
@@ -3065,14 +3442,15 @@ var WorkflowEngine = class {
   * Recomputed per call (never memoized into `this.workflows`) so it stays correct if group
   * liveness changes between calls, exactly as {@link synthesizeRemoteChild} does.
   */
-  async resolveRemoteByConvention(run) {
+  async resolveRemoteByConvention(run, opts = {}) {
     const group = tenantGroup(sanitizeQueueToken(run.workflow), run.namespace);
     const liveTransport = await this.pool.transportWithLiveGroup(group);
     if (!liveTransport) return void 0;
     const executor = new RemoteWorkflowExecutor(liveTransport, run.workflow, run.namespace);
+    const declared = opts.askFleetForVersion ? await this.declaredVersion(liveTransport, group, run.workflow) : void 0;
     return {
       name: run.workflow,
-      version: run.workflowVersion,
+      version: declared ?? run.workflowVersion,
       fn: /* @__PURE__ */ __name(() => {
         throw new Error(`remote workflow ${run.workflow} has no local body`);
       }, "fn"),
@@ -3080,10 +3458,46 @@ var WorkflowEngine = class {
       remote: {
         group,
         executor
-      }
+      },
+      ...opts.askFleetForVersion ? {
+        versionDeclared: declared !== void 0
+      } : {}
     };
   }
   /**
+  * The version the LIVE fleet declares for `workflow` on `group`, or `undefined` when it declares
+  * none — which is a fact about the fleet, not a failure to read it.
+  *
+  * The read is the descriptor advertisement, scoped to the one group being resolved: the workers on
+  * that queue, their `registrations`, the entry whose `name` matches. That is where a version can
+  * come from at all — a heartbeat has no room for one, so a worker on an SDK too old to publish a
+  * descriptor declares nothing and the caller is told so rather than handed a default.
+  *
+  * `undefined` when the announcers DISAGREE, and deliberately: two live workers claiming different
+  * versions of one name is a deployment in the middle of something, and picking either would stamp
+  * a run with a version half the fleet does not serve. Undeclared is the honest reading of a
+  * contradiction, and it is the reading that refuses to let a pin pass on a coin flip.
+  */
+  async declaredVersion(transport, group, workflow) {
+    if (!transport.readWorkerDescriptors) return void 0;
+    let descriptors;
+    try {
+      descriptors = await transport.readWorkerDescriptors(group);
+    } catch {
+      return void 0;
+    }
+    const versions = /* @__PURE__ */ new Set();
+    for (const announced of aggregateAnnouncements(descriptors)) {
+      if (announced.name === workflow && announced.version !== void 0) {
+        versions.add(announced.version);
+      }
+    }
+    const only = [
+      ...versions
+    ];
+    return only.length === 1 ? only[0] : void 0;
+  }
+  /**
   * Walk the parent chain of `childRunId` to the nearest ancestor registered as REMOTE, returning its
   * registration (or `undefined` if there is none). The parent of an awaited child is found via its
   * live `child:<childId>` signal waiter — present for as long as the parent is suspended awaiting the
@@ -3147,7 +3561,32 @@ var WorkflowEngine = class {
   /**
   * Cancel in-flight runs that have outlived their workflow's `executionTimeout`. Call it from the
   * timer poller alongside {@link resumeDueTimers}. A timed-out run is moved to `cancelled` with an
-  * `execution_timeout` error (terminal, so a late step result can't resurrect it).
+  * `execution_timeout` error (terminal, so a late step result can't resurrect it), AND its children
+  * are cascaded exactly as an explicit {@link cancel} cascades them.
+  *
+  * WHY THE TERMINAL WRITE IS DIRECT, not a call to {@link cancel}. Two reasons, both still standing:
+  * the run must land with the `execution_timeout` error `cancel` knows nothing about (`cancel` writes
+  * a plain `cancelled`, and the code is what a dashboard/alert distinguishes a timeout by), and this
+  * is a SCAN — it walks every in-flight run of every timed workflow on every poller tick, so it must
+  * not pay `cancel`'s per-run re-read and singleton/control-plane work on runs it isn't cancelling.
+  * The cascade below is charged only to the runs that ACTUALLY timed out, which are rare by
+  * construction; the scan itself is unchanged.
+  *
+  * The subtree, though, has no reason to differ, and before this it did: a timed-out parent's
+  * children kept running with the parent gone and nothing pointing at them — a silent orphan you
+  * could only find by reading the runs table by hand. {@link cancelChildren} is the SAME recursive
+  * walk `cancel` uses, so children of children go too, and it inherits that path's two guards:
+  * `cancel` returns early on a run that is already `completed`/`cancelled`/`dead` (a child that beat
+  * the sweep to the finish is never clobbered, and a re-cancel is a no-op), and it writes the
+  * parent's terminal status BEFORE recursing, so a cyclic parent→child graph terminates on the
+  * second visit instead of looping. Two pollers sweeping the same run concurrently therefore write
+  * the same terminal state twice and cascade into already-cancelled children — idempotent, not
+  * corrupting. The one window it does NOT close is the pre-existing check-then-write race an
+  * explicit `cancel` has always had (a child that completes between `cancel`'s read and its write);
+  * closing that needs a compare-and-set in the store contract, not a change here.
+  *
+  * Cascade failures are swallowed per subtree for the same reason `cancelChildren` swallows them per
+  * child: one unreachable child must not abort the sweep and leave every LATER timed-out run alive.
   */
   async sweepTimeouts(now = this.clock()) {
     for (const reg of new Set(this.latest.values())) {
@@ -3183,6 +3622,7 @@ var WorkflowEngine = class {
           namespace: run.namespace,
           error: error2
         });
+        await this.cancelChildren(run.id).catch(() => void 0);
       }
     }
   }
@@ -3911,6 +4351,10 @@ var WorkflowEngine = class {
   * `child:<id>` waiter) and fire-and-forget (`ctx.startChild`, found via its `spawn:<id>`
   * checkpoint). Recursive, so a whole subtree is cancelled; the terminal guard in `cancel` stops it
   * at finished / already-cancelled runs (no loops, no re-cancel).
+  *
+  * Two callers, deliberately the same walk: an explicit {@link cancel}, and {@link sweepTimeouts}
+  * when a parent hits its `executionTimeout` — a timed-out parent's subtree dies the same way an
+  * explicitly cancelled one's does, or the children are orphans nobody is holding a reference to.
   */
   async cancelChildren(parentRunId, opts) {
     for (const id of await this.getRunChildren(parentRunId)) {
@@ -3990,6 +4434,50 @@ var WorkflowEngine = class {
     return out;
   }
   /**
+  * What workflows the LIVE fleet announces it can execute — the deployment-wide registry a picker
+  * ("call this existing workflow") needs, and the one question this engine's own registry cannot
+  * answer. {@link workflowBody} answers only for this process, and a missing body is ambiguous: it
+  * means "not registered here", but equally "registered via {@link registerRemote} against another
+  * SDK" or "a group resolved by convention against a worker". An inferred answer would therefore
+  * differ per replica. This one does not: every pod folds the same published announcements.
+  *
+  * Scoped like every other poll surface — an engine WITH a `namespace` sees only workers in it, and
+  * an operator (namespace unset) sees the whole deployment ("ver tudo = ausência de namespace"). A
+  * descriptor that states no namespace is `default`, matching how a single-tenant fleet publishes.
+  *
+  * Cost: one advertisement scan per CALL, on demand. Nothing is added to the poll loop and nothing
+  * is retained — no pod holds a table of the fleet's registrations. Empty when no transport can
+  * introspect the advertisement keyspace (a pure in-process transport advertises nothing).
+  *
+  * Workflows only, and deliberately: see the "steps are out of scope" note in `handshake/announced`.
+  */
+  async announcedWorkflows() {
+    return (await this.workflowDirectory()).workflows;
+  }
+  /**
+  * {@link announcedWorkflows}, plus the thing a list of workflows can never say: why it is the
+  * length it is. See {@link WorkflowDirectory} for the three states an empty array used to collapse
+  * into one — "nobody asked", "nothing is live", and the partition mismatch that reads exactly like
+  * the second from the caller's side.
+  *
+  * Two live reads, both on demand and neither retained: the descriptor advertisement (what workers
+  * SAY they serve) and the heartbeat keyspace (what is demonstrably consuming a queue right now).
+  * The second is why a worker on an SDK too old to publish a descriptor appears here at all — it
+  * beats and never describes itself, and reading only descriptors reported such a fleet as empty
+  * while `resolveRemoteByConvention`, a few lines away in this same class, was routing calls to it
+  * off those very keys. Two answers out of one Redis, disagreeing. Now they agree, and the entry
+  * says which of the two kinds of evidence it rests on rather than flattening them together.
+  */
+  async workflowDirectory() {
+    return buildWorkflowDirectory({
+      descriptors: await this.pool.readAllWorkerDescriptors(),
+      heartbeats: await this.pool.readAllWorkerHeartbeats(),
+      namespace: this.namespace,
+      supported: this.pool.introspectsFleet,
+      sanitize: sanitizeQueueToken
+    });
+  }
+  /**
   * The routing groups of every in-flight run's still-`pending` remote step — the queues where work is
   * dispatched and awaiting a worker. Folded into {@link workerHealth} so a step waiting on a group
   * that is NEITHER a registration NOR heartbeating (the exact shape of a run stuck on an offline
@@ -5068,10 +5556,13 @@ var WorkflowEngine = class {
       // namespace) is the one executing the parent. Otherwise an operator recovery-resuming a
       // `davi-local` pipeline would stamp its `processing` child `default` and it would leak off the
       // tenant's worker pool onto the shared/dev workers.
-      startChild: /* @__PURE__ */ __name((workflow, input, id, priority) => {
+      startChild: /* @__PURE__ */ __name((workflow, input, id, priority, version) => {
         this.startChildDeferred(workflow, input, id, {
           priority,
-          namespace: parentNamespace
+          namespace: parentNamespace,
+          // Absent unless the body pinned one (`ctx.child(ref, input, { version })`) — an omitted
+          // pin must stay omitted, so the child keeps resolving `latest` exactly as before.
+          version
         });
       }, "startChild"),
       // Deferred for the same reentrancy reason as `startChild` above. `cancel()` is already
@@ -6446,6 +6937,7 @@ var InMemoryTransport = class {
   CURRENT_PROTOCOL_VERSION,
   CodecStateStore,
   ContinueAsNew,
+  DEFAULT_PARTITION,
   DURABLE_OPTIONS,
   DURABLE_OPTIONS_CANONICAL,
   DURABLE_STEP_CONFIG,
@@ -6476,25 +6968,31 @@ var InMemoryTransport = class {
   TERMINAL_RUN_STATUSES,
   TRANSPORT,
   TRANSPORT_CANONICAL,
+  VERSION_UNDECLARED_TAG,
   WORKFLOW_NAME_KEY,
   WorkflowBlocked,
   WorkflowEngine,
   WorkflowSuspended,
+  aggregateAnnouncements,
+  announcementsOf,
   applyAttributeQuery,
   attributeColumnFor,
   attributeOperand,
   bindWorkflowClass,
   breakpointToken,
+  buildWorkflowDirectory,
   canRoute,
   capableWorkers,
   classifyWaiterToken,
   clearDurableExecutionWrappers,
   collectMetrics,
   controlPlaneDescriptor,
+  coveredTokens,
   createStepLogger,
   currentStep,
   currentWorkflowCtx,
   debug,
+  describeWorker,
   descriptorHash,
   error,
   eventMatchOf,
@@ -6515,7 +7013,9 @@ var InMemoryTransport = class {
   negotiate,
   normalizeAttributeRows,
   normalizeDescriptor,
+  observedAnnouncements,
   parseDuration,
+  partitionOfToken,
   planDispatch,
   prevCronFireMs,
   readSearchAttributes,