@dudousxd/nestjs-durable-core 0.65.0 → 0.67.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,6 +57,7 @@ __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,
@@ -67,12 +69,14 @@ __export(index_exports, {
   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,
@@ -85,6 +89,7 @@ __export(index_exports, {
   eventNameOf: () => eventNameOf,
   eventPrefix: () => eventPrefix,
   eventToken: () => eventToken,
+  facetOrigin: () => facetOrigin,
   hasDurableExecutionWrappers: () => hasDurableExecutionWrappers,
   heartbeatStatus: () => heartbeatStatus,
   indexWaitersByRun: () => indexWaitersByRun,
@@ -94,11 +99,14 @@ __export(index_exports, {
   isWorkflowControlFlowSignal: () => isWorkflowControlFlowSignal,
   log: () => log,
   matchesAttributes: () => matchesAttributes,
+  mergeRunFacetRows: () => mergeRunFacetRows,
   missingCapabilities: () => missingCapabilities,
   negotiate: () => negotiate,
   normalizeAttributeRows: () => normalizeAttributeRows,
   normalizeDescriptor: () => normalizeDescriptor,
+  observedAnnouncements: () => observedAnnouncements,
   parseDuration: () => parseDuration,
+  partitionOfToken: () => partitionOfToken,
   planDispatch: () => planDispatch,
   prevCronFireMs: () => prevCronFireMs,
   readSearchAttributes: () => readSearchAttributes,
@@ -1310,6 +1318,7 @@ function aggregateAnnouncements(descriptors) {
     const first = announcements[0];
     if (!first) continue;
     out.push({
+      evidence: "declared",
       key,
       name: first.name,
       ...first.version !== void 0 ? {
@@ -1330,6 +1339,137 @@ function aggregateAnnouncements(descriptors) {
   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");
@@ -1881,6 +2021,36 @@ var TransportPool = class {
       ...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();
@@ -2645,6 +2815,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);
@@ -3136,7 +3307,9 @@ 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)})`);
@@ -3152,10 +3325,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);
     }
@@ -3265,14 +3444,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"),
@@ -3280,10 +3460,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
@@ -4238,9 +4454,30 @@ var WorkflowEngine = class {
   * Workflows only, and deliberately: see the "steps are out of scope" note in `handshake/announced`.
   */
   async announcedWorkflows() {
-    const descriptors = await this.pool.readAllWorkerDescriptors();
-    const mine = this.namespace === void 0 ? descriptors : descriptors.filter((d) => (d.namespace ?? "default") === this.namespace);
-    return aggregateAnnouncements(mine);
+    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
@@ -5871,6 +6108,33 @@ var TERMINAL_RUN_STATUSES = [
   "dead"
 ];
 
+// src/run-facets.ts
+function facetOrigin(origin) {
+  return origin?.trim() ? origin : null;
+}
+__name(facetOrigin, "facetOrigin");
+function mergeRunFacetRows(rows) {
+  const cells = /* @__PURE__ */ new Map();
+  for (const row of rows) {
+    const origin = facetOrigin(row.origin);
+    const key = JSON.stringify([
+      row.status,
+      origin
+    ]);
+    const cell = cells.get(key);
+    if (cell) cell.count += row.count;
+    else cells.set(key, {
+      status: row.status,
+      origin,
+      count: row.count
+    });
+  }
+  return [
+    ...cells.values()
+  ];
+}
+__name(mergeRunFacetRows, "mergeRunFacetRows");
+
 // src/run-gateway.ts
 var RunGateway = class {
   static {
@@ -5885,9 +6149,18 @@ var CodecStateStore = class {
   }
   inner;
   codec;
+  /**
+  * Forwarded verbatim — a facet cell counts `status`/`origin`, neither of which the codec touches
+  * (it encodes payloads: input/output/error). Bound as a PROPERTY, and only when the inner store
+  * actually aggregates, so `store.runFacets?.()` still reports absence through the wrapper instead
+  * of resolving to a silently wrong empty result.
+  */
+  runFacets;
   constructor(inner, codec) {
     this.inner = inner;
     this.codec = codec;
+    const facets = inner.runFacets;
+    if (facets) this.runFacets = (query) => facets.call(inner, query);
   }
   enc(v) {
     return v === void 0 ? void 0 : this.codec.encode(v);
@@ -6585,7 +6858,9 @@ var InMemoryStateStore = class {
     }
     return out;
   }
-  async listRuns(query) {
+  /** Every run satisfying `query`'s predicates, unsorted and unpaged — the shared body of
+  *  {@link listRuns} (which then sorts + pages it) and {@link runFacets} (which groups it). */
+  matching(query) {
     let runs = [
       ...this.runs.values()
     ];
@@ -6594,7 +6869,8 @@ var InMemoryStateStore = class {
     if (query.statuses) runs = runs.filter((r) => query.statuses?.includes(r.status));
     if (query.tag) runs = runs.filter((r) => r.tags?.includes(query.tag));
     if (query.namespace !== void 0) runs = runs.filter((r) => r.namespace === query.namespace);
-    if (query.origin !== void 0) runs = runs.filter((r) => r.origin === query.origin);
+    if (query.origin === null) runs = runs.filter((r) => r.origin == null);
+    else if (query.origin !== void 0) runs = runs.filter((r) => r.origin === query.origin);
     if (query.attributes?.length) {
       let candidates = null;
       for (const f of query.attributes) {
@@ -6613,6 +6889,10 @@ var InMemoryStateStore = class {
       this.lastAttributeCandidates = ids.size;
       runs = runs.filter((r) => ids.has(r.id));
     }
+    return runs;
+  }
+  async listRuns(query) {
+    const runs = this.matching(query);
     runs.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
     const offset = query.offset ?? 0;
     const limit = query.limit ?? runs.length;
@@ -6620,6 +6900,13 @@ var InMemoryStateStore = class {
       ...r
     }));
   }
+  async runFacets(query) {
+    return mergeRunFacetRows(this.matching(query).map((run) => ({
+      status: run.status,
+      origin: run.origin,
+      count: 1
+    })));
+  }
   async listCheckpoints(runId) {
     const rows = [
       ...this.checkpoints.values()
@@ -6702,6 +6989,7 @@ var InMemoryTransport = class {
   CURRENT_PROTOCOL_VERSION,
   CodecStateStore,
   ContinueAsNew,
+  DEFAULT_PARTITION,
   DURABLE_OPTIONS,
   DURABLE_OPTIONS_CANONICAL,
   DURABLE_STEP_CONFIG,
@@ -6732,6 +7020,7 @@ var InMemoryTransport = class {
   TERMINAL_RUN_STATUSES,
   TRANSPORT,
   TRANSPORT_CANONICAL,
+  VERSION_UNDECLARED_TAG,
   WORKFLOW_NAME_KEY,
   WorkflowBlocked,
   WorkflowEngine,
@@ -6743,12 +7032,14 @@ var InMemoryTransport = class {
   attributeOperand,
   bindWorkflowClass,
   breakpointToken,
+  buildWorkflowDirectory,
   canRoute,
   capableWorkers,
   classifyWaiterToken,
   clearDurableExecutionWrappers,
   collectMetrics,
   controlPlaneDescriptor,
+  coveredTokens,
   createStepLogger,
   currentStep,
   currentWorkflowCtx,
@@ -6761,6 +7052,7 @@ var InMemoryTransport = class {
   eventNameOf,
   eventPrefix,
   eventToken,
+  facetOrigin,
   hasDurableExecutionWrappers,
   heartbeatStatus,
   indexWaitersByRun,
@@ -6770,11 +7062,14 @@ var InMemoryTransport = class {
   isWorkflowControlFlowSignal,
   log,
   matchesAttributes,
+  mergeRunFacetRows,
   missingCapabilities,
   negotiate,
   normalizeAttributeRows,
   normalizeDescriptor,
+  observedAnnouncements,
   parseDuration,
+  partitionOfToken,
   planDispatch,
   prevCronFireMs,
   readSearchAttributes,