@dudousxd/nestjs-durable-core 0.64.0 → 0.65.0

package/dist/index.cjs

@@ -60,6 +60,8 @@ __export(index_exports, {
   WorkflowBlocked: () => WorkflowBlocked,
   WorkflowEngine: () => WorkflowEngine,
   WorkflowSuspended: () => WorkflowSuspended,
+  aggregateAnnouncements: () => aggregateAnnouncements,
+  announcementsOf: () => announcementsOf,
   applyAttributeQuery: () => applyAttributeQuery,
   attributeColumnFor: () => attributeColumnFor,
   attributeOperand: () => attributeOperand,
@@ -75,6 +77,7 @@ __export(index_exports, {
   currentStep: () => currentStep,
   currentWorkflowCtx: () => currentWorkflowCtx,
   debug: () => debug,
+  describeWorker: () => describeWorker,
   descriptorHash: () => descriptorHash,
   error: () => error,
   eventMatchOf: () => eventMatchOf,
@@ -1103,6 +1106,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 +1119,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 +1157,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 +1192,144 @@ 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({
+      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");
 
 // 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 +1857,30 @@ 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()
+    ];
+  }
   /** Distinct worker groups with a live heartbeat, merged across every transport that can report it. */
   async listWorkerGroups() {
     const groups = /* @__PURE__ */ new Set();
@@ -2093,7 +2281,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 +2309,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 +2392,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,
@@ -2769,6 +2957,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 +3115,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,
@@ -2940,7 +3138,9 @@ var WorkflowEngine = class {
       };
       registered = await this.resolveRemoteByConvention(conventionRun);
     }
-    if (!registered) throw new Error(`workflow ${name} is not registered`);
+    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)})`);
+    }
     await registered.validateInput?.(input);
     const prior = await this.store.getRun(runId);
     if (prior) {
@@ -3147,7 +3347,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 +3408,7 @@ var WorkflowEngine = class {
           namespace: run.namespace,
           error: error2
         });
+        await this.cancelChildren(run.id).catch(() => void 0);
       }
     }
   }
@@ -3911,6 +4137,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 +4220,29 @@ 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() {
+    const descriptors = await this.pool.readAllWorkerDescriptors();
+    const mine = this.namespace === void 0 ? descriptors : descriptors.filter((d) => (d.namespace ?? "default") === this.namespace);
+    return aggregateAnnouncements(mine);
+  }
+  /**
   * 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 +5321,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
@@ -6480,6 +6736,8 @@ var InMemoryTransport = class {
   WorkflowBlocked,
   WorkflowEngine,
   WorkflowSuspended,
+  aggregateAnnouncements,
+  announcementsOf,
   applyAttributeQuery,
   attributeColumnFor,
   attributeOperand,
@@ -6495,6 +6753,7 @@ var InMemoryTransport = class {
   currentStep,
   currentWorkflowCtx,
   debug,
+  describeWorker,
   descriptorHash,
   error,
   eventMatchOf,