@dudousxd/nestjs-durable-core 0.63.0 → 0.65.0

package/dist/index.js

@@ -481,6 +481,57 @@ function backoffDelay(attempt, options) {
 }
 __name(backoffDelay, "backoffDelay");
 
+// src/execution-hooks.ts
+var wrappers = [];
+function useDurableExecution(wrapper) {
+  wrappers.push(wrapper);
+  return () => {
+    const i = wrappers.indexOf(wrapper);
+    if (i >= 0) wrappers.splice(i, 1);
+  };
+}
+__name(useDurableExecution, "useDurableExecution");
+function clearDurableExecutionWrappers() {
+  wrappers.length = 0;
+}
+__name(clearDurableExecutionWrappers, "clearDurableExecutionWrappers");
+function hasDurableExecutionWrappers() {
+  return wrappers.length > 0;
+}
+__name(hasDurableExecutionWrappers, "hasDurableExecutionWrappers");
+async function runDurableExecution(execution, body) {
+  if (wrappers.length === 0) return body();
+  let outcome;
+  const inner = /* @__PURE__ */ __name(async () => {
+    try {
+      const value = await body();
+      outcome = {
+        ok: true,
+        value
+      };
+      return value;
+    } catch (error2) {
+      outcome = {
+        ok: false,
+        error: error2
+      };
+      throw error2;
+    }
+  }, "inner");
+  const chain = wrappers.reduceRight((next, wrapper) => () => wrapper(execution, next), inner);
+  try {
+    await chain();
+  } catch (error2) {
+    if (outcome === void 0) throw error2;
+  }
+  if (outcome === void 0) {
+    throw new Error("a durable execution wrapper returned without calling next() \u2014 the unit of work never ran");
+  }
+  if (outcome.ok) return outcome.value;
+  throw outcome.error;
+}
+__name(runDurableExecution, "runDurableExecution");
+
 // src/step-logger.ts
 function withDuration(start, now, data) {
   if (data && typeof data === "object" && "durationMs" in data) {
@@ -622,7 +673,14 @@ async function runStepHandler(task, handler) {
   } : result, "withEvents");
   try {
     const logger = createStepLogger(events, Date.now);
-    const output = await runInStepLogger(logger, () => handler(task.input, logger));
+    const output = await runDurableExecution({
+      unit: "step",
+      runId: task.runId,
+      workflow: void 0,
+      name: task.name,
+      seq: task.seq,
+      attempt: task.attempt
+    }, async () => runInStepLogger(logger, () => handler(task.input, logger)));
     return withEvents({
       ...base,
       status: "completed",
@@ -923,6 +981,9 @@ function normalizeDescriptor(raw) {
     ],
     workflows: raw.workflows ?? [],
     steps: raw.steps ?? [],
+    ...raw.registrations !== void 0 ? {
+      registrations: raw.registrations
+    } : {},
     ...raw.partition !== void 0 ? {
       partition: raw.partition
     } : {},
@@ -933,6 +994,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)
@@ -954,6 +1032,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
@@ -986,6 +1067,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");
@@ -1513,6 +1732,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();
@@ -1913,7 +2156,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);
@@ -1941,7 +2184,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,
@@ -2024,12 +2267,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,
@@ -2589,6 +2832,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
@@ -2738,12 +2990,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,
@@ -2760,7 +3013,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) {
@@ -2967,7 +3222,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())) {
@@ -3003,6 +3283,7 @@ var WorkflowEngine = class {
           namespace: run.namespace,
           error: error2
         });
+        await this.cancelChildren(run.id).catch(() => void 0);
       }
     }
   }
@@ -3731,6 +4012,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)) {
@@ -3810,6 +4095,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
@@ -4524,8 +4832,31 @@ var WorkflowEngine = class {
       error: error2
     };
   }
-  /** The run body, lease held + renewed by {@link execute}. */
-  async runExecution(run, fn, registered) {
+  /**
+  * The run body, lease held + renewed by {@link execute}, wrapped in the registered
+  * {@link runDurableExecution} wrappers so an observability scope covers ONE WHOLE TURN.
+  *
+  * The wrap goes here — around the entire turn — rather than tightly around the `fn(ctx, input)`
+  * call, because the store writes that bracket the body (the `pending` → `running` transition, the
+  * step checkpoints, the terminal `settleRun` update) are exactly the queries an operator wants
+  * correlated to the turn that issued them. Narrowing the wrap to the body would leave them
+  * uncorrelated for the sake of a purity that buys nothing.
+  *
+  * Only the TS path is wrapped. {@link runRemoteExecution} does not execute a body at all — it
+  * dispatches a workflow task and awaits the worker's decision — so a scope opened there would
+  * describe a dispatch, not an execution, and would mislead anyone reading the trace.
+  */
+  runExecution(run, fn, registered) {
+    return runDurableExecution({
+      unit: "workflow",
+      runId: run.id,
+      workflow: run.workflow,
+      name: void 0,
+      seq: void 0,
+      attempt: void 0
+    }, () => this.runExecutionTurn(run, fn, registered));
+  }
+  async runExecutionTurn(run, fn, registered) {
     if (run.status === "cancelling") this.cancelRequested.add(run.id);
     if (run.status === "pending") {
       await this.store.updateRun(run.id, {
@@ -4865,10 +5196,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
@@ -6276,6 +6610,8 @@ export {
   WorkflowBlocked,
   WorkflowEngine,
   WorkflowSuspended,
+  aggregateAnnouncements,
+  announcementsOf,
   applyAttributeQuery,
   attributeColumnFor,
   attributeOperand,
@@ -6284,12 +6620,14 @@ export {
   canRoute,
   capableWorkers,
   classifyWaiterToken,
+  clearDurableExecutionWrappers,
   collectMetrics,
   controlPlaneDescriptor,
   createStepLogger,
   currentStep,
   currentWorkflowCtx,
   debug,
+  describeWorker,
   descriptorHash,
   error,
   eventMatchOf,
@@ -6297,6 +6635,7 @@ export {
   eventNameOf,
   eventPrefix,
   eventToken,
+  hasDurableExecutionWrappers,
   heartbeatStatus,
   indexWaitersByRun,
   info,
@@ -6316,6 +6655,7 @@ export {
   requiredCapabilities,
   resolveRouting,
   resolveRunWaiting,
+  runDurableExecution,
   runInStepLogger,
   runInWorkflowCtx,
   runSchedules,
@@ -6330,6 +6670,7 @@ export {
   subEvent,
   subProcess,
   tenantGroup,
+  useDurableExecution,
   warn,
   workflowName
 };