@sanoma-ai/workflows 0.0.0-stage → 0.1.0

package/src/scenarios.ts

@@ -0,0 +1,111 @@
+import { type RunSummary, SanomaClient } from "./client.ts";
+import { resolveConfig, type SanomaConfig } from "./config.ts";
+import type { Principal } from "./define.ts";
+import { type LedgerRecord, memoryLedger } from "./ledger.ts";
+import { type Check, check, drive, loadScenarios, type Scenario, type Scope } from "./scenario.ts";
+import { errorMessage } from "./shared.ts";
+import { startWorker } from "./worker.ts";
+
+/*
+ * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test
+ * framework. Server-side only, like `./scenario`: it loads Cucumber and starts a worker.
+ * `sanoma check` runs every scenario through `runScenarios`; `@sanoma-ai/testing/scenarios` wraps
+ * `runScenario` in a vitest test per scenario.
+ */
+
+export interface RunScenarioOptions {
+  /** A client of the worker that runs the scenario, whose connectors carry the fakes and whose root has the scenarios. */
+  client: SanomaClient;
+  /** What the scenario was loaded from (`loadScenarios`), whose feature files its run is checked against: the resolved config. */
+  scope: Scope;
+  /** Who starts the run. Defaults to `{ id: "scenarios" }`. */
+  startedBy?: Principal;
+  /** How long the run may take, passed to `drive`. */
+  timeoutMs?: number;
+}
+
+/**
+ * Runs a scenario as a sandbox run: starts its workflow with its input, decides its approvals
+ * as it says, and checks the run's ledger against it (`check`: Cucumber runs its `Then` steps).
+ */
+export async function runScenario(
+  scenario: Scenario,
+  { client, scope, startedBy = { id: "scenarios" }, timeoutMs }: RunScenarioOptions,
+): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
+  const runId = await client.start(scenario.workflow, scenario.input, { startedBy, sandbox: scenario.name });
+  const run = await drive(client, runId, scenario, { timeoutMs });
+  const ledger = await client.ledger(runId);
+  return { runId, run, ledger, checks: await check(scope, scenario, ledger) };
+}
+
+/** One step of a scenario that did not hold, or a file whose scenarios could not be read (`step` is then `did not load`). */
+export interface ScenarioFailure {
+  /** The scenario's name, or the feature file's for one that did not load. */
+  scenario: string;
+  step: string;
+  message: string;
+}
+
+export interface RunScenariosOptions {
+  /** The Postgres the worker and the client run on, instead of the config's: a database of its own. */
+  databaseUrl: string;
+  /** Who starts the runs. Defaults to `{ id: "scenarios" }`. */
+  startedBy?: Principal;
+  /** How long each run may take (`drive`'s; 15 seconds by default). */
+  timeoutMs?: number;
+  /** Receives a line per scenario as it ends. */
+  log?: (line: string) => void;
+}
+
+/**
+ * Runs every scenario in `scenarios/` in the config's root, one after another, as sandbox runs
+ * on a worker it starts on `databaseUrl` with an in-memory ledger (the config's `ledger` is not
+ * written), and stops when done. `passed` names the scenarios whose every check held; `failed`
+ * has one entry per step that did not, with `check`'s detail, and one per feature file that
+ * could not be read, with why. A scenario whose run cannot be driven to its end (an approval
+ * with no decision, a run still going after `timeoutMs`) fails with that error at its `When`
+ * step. A config whose root has no `scenarios/`, or none in it, passes nothing and fails nothing.
+ */
+export async function runScenarios(
+  config: SanomaConfig,
+  { databaseUrl, startedBy, timeoutMs, log }: RunScenariosOptions,
+): Promise<{ passed: string[]; failed: ScenarioFailure[] }> {
+  const shared: SanomaConfig = { ...config, databaseUrl, ledger: memoryLedger() };
+  const resolved = resolveConfig(shared);
+  const { scenarios, errors } = await loadScenarios(resolved);
+  const failed: ScenarioFailure[] = errors.map(({ file, message }) => ({
+    scenario: file,
+    step: "did not load",
+    message,
+  }));
+  const passed: string[] = [];
+  if (scenarios.length === 0) return { passed, failed };
+
+  // Quiet: the scenarios call the fakes alone, so no vendor need be configured.
+  const worker = await startWorker(shared, { promote: true, quiet: true });
+  try {
+    const client = await SanomaClient.connect(shared);
+    try {
+      for (const scenario of scenarios) {
+        const before = failed.length;
+        try {
+          const { checks } = await runScenario(scenario, { client, scope: resolved, startedBy, timeoutMs });
+          for (const c of checks) {
+            if (!c.ok) failed.push({ scenario: scenario.name, step: c.step, message: c.detail ?? "did not hold" });
+          }
+        } catch (err) {
+          const when = scenario.steps.find((s) => s.kind === "when")?.text ?? `${scenario.workflow} runs`;
+          failed.push({ scenario: scenario.name, step: when, message: errorMessage(err) });
+        }
+        const ok = failed.length === before;
+        if (ok) passed.push(scenario.name);
+        log?.(`${ok ? "passed" : "failed"} ${scenario.file} › ${scenario.name}`);
+      }
+    } finally {
+      await client.close();
+    }
+  } finally {
+    await worker.stop();
+  }
+  return { passed, failed };
+}

package/src/shared.ts

@@ -0,0 +1,116 @@
+import type { CredentialStatus } from "./env.ts";
+import type { ApprovalState, Approver, Principal } from "./define.ts";
+import type { ResourceProblem } from "./resources.ts";
+import type { OutlineNode } from "./outline.ts";
+
+// Types only: resource types as a UI reads them. Erased from the bundle.
+export type {
+  Declared,
+  Declaring,
+  FieldReference,
+  References,
+  Resource,
+  ResourceFields,
+  ResourceSpec,
+} from "./resource.ts";
+export type { DeclaredResource, ResourceProblem } from "./resources.ts";
+export type { DriftField, DriftReport, DriftResult, DriftStatus } from "./drift.ts";
+export type { CredentialStatus } from "./env.ts";
+
+// What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
+// Nothing here imports DBOS, Node or zod, so a browser bundle can carry it; the runtime uses the
+// same functions, so a page answers these questions the way a run does.
+
+/**
+ * What a `ctx.sleep` without a `{ name }` is called, in its outline node and its ledger record
+ * (`name`); a name given may not be it.
+ */
+export const DEFAULT_SLEEP_NAME = "Sleep";
+
+/** The built-in drift workflow's name, which a config's own workflows may not take; a UI and the scenarios name its runs by it. */
+export const DRIFT_WORKFLOW = "drift";
+
+/**
+ * Every run status, in the order a run may pass through them: waiting on the queue, running,
+ * waiting for an approval, or ended. `waiting` is `running` with an approval pending.
+ */
+export const RUN_STATUSES = ["queued", "running", "waiting", "finished", "failed", "cancelled"] as const;
+
+/** Where a run is: one of `RUN_STATUSES`, so a new status reaches every list and map of them. */
+export type RunStatus = (typeof RUN_STATUSES)[number];
+
+/** The statuses of a run that has ended: it reads no more decisions. */
+export const ENDED_STATUSES = ["finished", "failed", "cancelled"] as const satisfies readonly RunStatus[];
+
+/** True when the run has finished, failed or been cancelled. */
+export const isEnded = (status: RunStatus): boolean => (ENDED_STATUSES as readonly RunStatus[]).includes(status);
+
+/**
+ * True when `by` may decide the approval: `by.id` is the approver, or `by.groups` holds the
+ * approver group. Pure: everything it reads is already recorded.
+ */
+export function mayDecide(approval: Pick<ApprovalState, "approver">, by: Principal): boolean {
+  const { approver } = approval;
+  return typeof approver === "string" ? approver === by.id : (by.groups?.includes(approver.group) ?? false);
+}
+
+/** Who may decide, as text: the person's id, or "group <name>". */
+export const approverLabel = (approver: Approver): string =>
+  typeof approver === "string" ? approver : `group ${approver.group}`;
+
+/** An error's message, or the value as text when it is not an Error. */
+export const errorMessage = (err: unknown) => (err instanceof Error ? err.message : String(err));
+
+/** True when an outline's op id, a computed segment shown as `*`, could be this op: `a.*.c` fits `a.b.c`. */
+export function fitsOp(pattern: string, op: string): boolean {
+  const want = pattern.split(".");
+  const got = op.split(".");
+  return want.length === got.length && want.every((segment, i) => segment === "*" || segment === got[i]);
+}
+
+/** A node's child lists, in order: the lists a `path`'s segments index into. */
+export const childLists = (node: OutlineNode): OutlineNode[][] => {
+  switch (node.kind) {
+    case "all":
+      return node.branches;
+    case "branch":
+      return node.cases;
+    case "each":
+    case "repeat":
+      return [node.body];
+    case "try":
+      return [node.body, node.handler];
+    default:
+      return [];
+  }
+};
+
+/** Every node of an outline, nested ones included, in order. */
+export function flatten(nodes: readonly OutlineNode[]): OutlineNode[] {
+  return nodes.flatMap((node) => [node, ...flatten(childLists(node).flat())]);
+}
+
+/** Where a data-file problem is, `file:line:column`; undefined for one that is the config's, with no file. */
+export const problemAt = (p: ResourceProblem): string | undefined =>
+  p.file === undefined ? undefined : `${p.file}:${p.line}:${p.column}`;
+
+/**
+ * A problem as one line: `file:line:column: message`, or `file: message` without a position, or
+ * the message alone without a file.
+ */
+export function problemLine(p: { file?: string; line?: number; column?: number; message: string }): string {
+  if (p.file === undefined) return p.message;
+  return p.line === undefined ? `${p.file}: ${p.message}` : `${p.file}:${p.line}:${p.column ?? 1}: ${p.message}`;
+}
+
+/**
+ * Whether a host is this machine: `localhost`, `127.x.x.x` or `::1` (bare, or bracketed as a URL's
+ * `hostname` has it). The one rule for what the app listens on and answers to, and for where the
+ * bin may start Postgres.
+ */
+export const isLoopback = (host: string) =>
+  ["localhost", "::1", "[::1]"].includes(host) || /^127\.\d+\.\d+\.\d+$/.test(host);
+
+/** Whether a driver's environment variable lets it run: set, or unset and optional. */
+export const credentialReady = ({ status, optional }: CredentialStatus): boolean =>
+  status === "set" || (status === "missing" && optional);

package/src/steps.ts

@@ -0,0 +1,90 @@
+import type { LedgerRecord } from "./ledger.ts";
+import type { Op } from "./op.ts";
+
+/*
+ * Steps a connector (or a company) ships for its Gherkin tests, as plain data: expressions and
+ * functions, never Cucumber's own registration, which Sanoma does from the config. Kept free of
+ * Cucumber, Gherkin and faker, so a connector's package can import it on its main entry.
+ */
+
+/** Any operation, whatever its input and output. */
+type AnyOp<I = any, O = any> = Op<string, string, string, I, O>;
+
+/**
+ * What a `Given` step sets up before the run: a call through an operation of the run's fake,
+ * with the fields of its input to set (the rest is made up), or a fault to inject into its next
+ * call. `as` names a call's output, so a later step's table of an operation's own test can use
+ * its fields: `$draft.id`.
+ */
+export type Seed =
+  | { op: AnyOp; input: Record<string, unknown>; as?: string }
+  | { op: AnyOp; fault: "failNext" | "rateLimit" | "loseReply" };
+
+/** A call through an operation: what it was given, and what it returned. */
+export interface Call<I, O> {
+  input: I;
+  output: O;
+}
+
+/** A run as a `Then` step reads it. */
+export interface RunView {
+  /** Every record of the run, in order. */
+  readonly records: readonly LedgerRecord[];
+  /** The calls the run made through the operation, in order: those that did not fail. */
+  calls<I, O>(op: AnyOp<I, O>): Call<I, O>[];
+  /** The calls the scenario's `Given` steps made through the operation, to seed the run's fake. */
+  seeded<I, O>(op: AnyOp<I, O>): Call<I, O>[];
+  /** The seeded calls, then the run's own: everything made through the operation. */
+  made<I, O>(op: AnyOp<I, O>): Call<I, O>[];
+}
+
+/**
+ * What a `Then` step expects. `check` reads the run and throws, or returns why the expectation
+ * does not hold; returning nothing passes. `op` and `called` say what the step is about, for the
+ * graph: the operation, and whether it expects a call to it (true) or rules one out (false).
+ */
+export interface Expect {
+  op?: AnyOp;
+  called?: boolean;
+  check(run: RunView): string | undefined | void;
+}
+
+/** One step definition: a Cucumber expression, and what the step says, from its parameters' values. */
+export type StepDefinition =
+  | { kind: "given"; expression: string; fn: (...values: any[]) => Seed }
+  | { kind: "then"; expression: string; fn: (...values: any[]) => Expect };
+
+/** A connector's or a company's steps: `owner` (the vendor, say) heads them in a list of known steps. */
+export interface Steps {
+  readonly owner: string;
+  readonly steps: readonly StepDefinition[];
+}
+
+/**
+ * Declares steps for Gherkin tests, as data the config's scenarios and a connector's own feature
+ * files can use: `given` steps say what to seed (`Seed`), `then` steps what to expect
+ * (`Expect`). A step's function gets its expression's values, in order, and must be pure:
+ * compiling a scenario calls it, and so does the app, whenever a feature file changes.
+ *
+ * ```ts
+ * export const ghostSteps = defineSteps("ghost", ({ given }) => {
+ *   given("a Ghost draft titled {string}", (title: string) => ({ op: ghostOps.post.create, input: { title }, as: "draft" }));
+ * });
+ * ```
+ */
+export function defineSteps(
+  owner: string,
+  define: (steps: {
+    given(expression: string, fn: (...values: any[]) => Seed): void;
+    then(expression: string, fn: (...values: any[]) => Expect): void;
+  }) => void,
+): Steps {
+  const steps: StepDefinition[] = [];
+  define({
+    given: (expression, fn) => void steps.push({ kind: "given", expression, fn }),
+    // Named for Gherkin's keyword; the object goes to `define` only, which never awaits it.
+    // oxlint-disable-next-line unicorn/no-thenable
+    then: (expression, fn) => void steps.push({ kind: "then", expression, fn }),
+  });
+  return Object.freeze({ owner, steps: Object.freeze(steps) });
+}

package/src/version.ts

@@ -0,0 +1,86 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { jsonSchemaOf, opIdsOf, type WorkflowDefinition } from "./define.ts";
+import { upFrom } from "./paths.ts";
+
+/** This package's version. A unit test keeps it equal to package.json. */
+export const RUNTIME_VERSION = "0.1.0";
+
+/**
+ * The sequence of DBOS calls the runtime makes around each `ctx` call: policy step, approval
+ * events and messages, the driver step. Bump it whenever that sequence changes, even without a
+ * package release, so a run in flight on the old layout is not replayed against the new one.
+ * 2: calls run in program order; a decision event per approval (2026-10-07).
+ */
+export const STEP_LAYOUT = 2;
+
+let dbosVersion: string | undefined;
+
+/** The installed DBOS SDK's version, read from its package.json (which its exports don't expose). */
+function installedDbosVersion(): string {
+  dbosVersion ??= upFrom(dirname(createRequire(import.meta.url).resolve("@dbos-inc/dbos-sdk")), (dir) => {
+    let pkg: { name?: string; version?: string };
+    try {
+      pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8")) as typeof pkg;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw err;
+    }
+    return pkg.name === "@dbos-inc/dbos-sdk" && pkg.version ? pkg.version : undefined;
+  });
+  if (!dbosVersion) throw new Error("Cannot find the package.json of @dbos-inc/dbos-sdk");
+  return dbosVersion;
+}
+
+/**
+ * The application version DBOS stamps on every run, always `<appName>@…`: DBOS version names
+ * are unique per system database across apps. A worker recovers and dequeues only runs of its
+ * own version, so the version must change whenever replaying an old run on the new code could
+ * go wrong.
+ *
+ * It is a hash of the app name, `RUNTIME_VERSION`, `STEP_LAYOUT`, the installed DBOS version,
+ * and for each workflow its name, the source text of its `run` function, the ids of the
+ * operations it uses and its input schema as JSON Schema: DBOS's own automatic versioning, over
+ * the workflow code instead of the runtime's one registration wrapper. The hash cannot see
+ * functions `run` calls that live elsewhere (their source is not reachable from the definition),
+ * op schemas, drivers or the policy. DBOS's `DBOS__APPVERSION` environment variable names a
+ * version instead (a git commit, say), still prefixed with the app name.
+ */
+export function computeVersion({
+  appName,
+  workflows: definitions,
+}: {
+  /** The resolved config's `appName`. */
+  appName: string;
+  workflows: readonly WorkflowDefinition<any, any>[];
+}): string {
+  const named = process.env.DBOS__APPVERSION?.trim();
+  if (named) return `${appName}@${named}`;
+  const workflows = definitions
+    .map(
+      (wf) =>
+        [
+          wf.name,
+          wf.run.toString(),
+          opIdsOf(wf),
+          // The input schema is parsed outside steps on replay, so a change to it must change the version.
+          inputSchemaOf(wf),
+        ] as const,
+    )
+    .toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  const hash = createHash("sha256")
+    .update(JSON.stringify([appName, RUNTIME_VERSION, STEP_LAYOUT, installedDbosVersion(), ...workflows]))
+    .digest("hex");
+  return `${appName}@${hash}`;
+}
+
+/** The workflow's input schema as the hash sees it: its JSON Schema, or its text when zod can't convert it. */
+function inputSchemaOf(wf: WorkflowDefinition<any, any>): unknown {
+  try {
+    return jsonSchemaOf(wf.input);
+  } catch {
+    return String(wf.input);
+  }
+}

package/src/worker.ts

@@ -0,0 +1,253 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { buildCtx, isInfrastructureError } from "./call.ts";
+import { dbosStatusesOf } from "./client.ts";
+import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
+import { watchCredentials } from "./credentials.ts";
+import { DBOS_DATABASE_OPTIONS, prepareDatabase } from "./db.ts";
+import type { WorkflowDefinition } from "./define.ts";
+import { credentialsOf, unconfigured, unconfiguredSummary } from "./env.ts";
+import { errorInfo, parseOrThrow } from "./errors.ts";
+import { entry, ownedLedger, skipped, write, writeFailure } from "./ledger.ts";
+import { dbosLogger, quietIfSandbox, setLogLevel, warn } from "./log.ts";
+import { lineStartsOf, readSource } from "./ast.ts";
+import { callsOf, outlineWithSource } from "./outline.ts";
+import type { Run, RunArgs, WorkerState, WorkflowOutline } from "./run.ts";
+import { errorMessage } from "./shared.ts";
+
+export interface Worker {
+  /**
+   * The vendors whose drivers could not run when the worker started, in the config's order: a
+   * live call to one fails, saying why (`unconfigured` in env.ts), until its variables are set.
+   * The worker names them in one line at start, unless started `quiet`.
+   */
+  readonly unconfigured: readonly string[];
+  stop(): Promise<void>;
+}
+
+// DBOS registrations are process-wide and survive shutdown, so a name is registered once, and
+// its function reads the state of the worker running when a run starts, definition and all; the
+// run keeps that state.
+let current: WorkerState | undefined;
+const registered = new Set<string>();
+
+export interface WorkerOptions {
+  /** The least severe level of the runtime's and DBOS's messages to show, for the whole process: `warn` by default. */
+  logLevel?: string;
+  /**
+   * Start without naming the vendors not configured yet (`unconfigured` still does): for a worker
+   * whose runs use the fakes alone, as `runScenarios`'s.
+   */
+  quiet?: boolean;
+  /**
+   * Make this worker's version the app's latest, so runs queued without a version come here.
+   * A brand-new version becomes the latest on its own; set this only when deliberately starting
+   * a worker on a version seen before (a rollback). Off by default, because an old instance
+   * restarting during a rolling deploy would otherwise take the new workers' runs.
+   */
+  promote?: boolean;
+}
+
+/**
+ * Registers the workflows, connects to Postgres and recovers any runs that were interrupted.
+ * When a driver declares variables the environment leaves unset, it first loads their stored
+ * values into `process.env` and keeps them current while it runs. It starts whether or not they
+ * are all there: it prints one line naming the vendors that lack one (`unconfigured`), and a live
+ * call to such a vendor fails, saying why, as the call's own final failure, until they are set.
+ */
+export async function startWorker(config: SanomaConfig, options: WorkerOptions = {}): Promise<Worker> {
+  // Check everything before touching the state a running worker reads.
+  const resolved = resolveConfig(config);
+  setLogLevel(options.logLevel);
+  // The config's own, or a Postgres store made for this worker, which `stop` then closes.
+  const ledger = ownedLedger(resolved);
+  const state: WorkerState = {
+    app: resolved.appName,
+    ops: resolved.ops,
+    drivers: resolved.drivers,
+    fakes: resolved.fakes,
+    ...(resolved.scenarios && { scenarios: resolved.scenarios }),
+    types: resolved.types,
+    steps: resolved.steps,
+    policy: resolved.policy,
+    ledger: ledger.store,
+    workflows: resolved.workflows,
+    outlines: new Map([...resolved.workflows].map(([name, wf]) => [name, outlineOf(wf)])),
+    stopped: false,
+  };
+  const credentials = await watchCredentials(resolved.databaseUrl, resolved.driversByVendor);
+  const worker: Worker = {
+    unconfigured: [...credentialsOf(resolved.driversByVendor, (name) => process.env[name])]
+      .filter(([vendor, statuses]) => unconfigured(vendor, statuses))
+      .map(([vendor]) => vendor),
+    async stop() {
+      state.stopped = true;
+      // Each is closed whatever the one before did; the first failure is what stop throws.
+      let failed: { error: unknown } | undefined;
+      for (const close of [() => DBOS.shutdown(), () => credentials.close(), () => ledger.close()]) {
+        await close().catch((error: unknown) => (failed ??= { error }));
+      }
+      if (failed) throw failed.error;
+    },
+  };
+  // Runs recovered during launch start before it returns, so they must already find this
+  // state. If starting fails, a worker still running in the process gets its own back, once
+  // DBOS has stopped: until then a run DBOS dispatches finds this state stopped, and is refused.
+  const previous = current;
+  let launched = false;
+  try {
+    for (const name of resolved.workflows.keys()) {
+      if (!registered.has(name)) {
+        register(name);
+        registered.add(name);
+      }
+    }
+    current = state;
+    // Before DBOS's pool connects, so its connections start with the database's idle-transaction
+    // timeout (`DBOS_DATABASE_OPTIONS`); once per process and database.
+    await prepareDatabase(resolved.databaseUrl);
+    DBOS.setConfig({
+      name: resolved.appName,
+      systemDatabaseUrl: resolved.databaseUrl,
+      ...DBOS_DATABASE_OPTIONS,
+      // A logger of our own replaces DBOS's OTLP log export, so only while DBOS exports none (it
+      // does on DBOS Cloud); its level is then the threshold `setLogLevel` set, DBOS's own `logLevel` unread.
+      ...(process.env.DBOS__CLOUD === "true" ? { logLevel: options.logLevel ?? "warn" } : { logger: dbosLogger }),
+      applicationVersion: resolved.version,
+    });
+    await DBOS.launch();
+    launched = true;
+    // DBOS gives runs queued without a version only to the app's latest version, which is the
+    // newest one registered. A worker started on code seen before (a rollback) is not it.
+    const latest = (await DBOS.getLatestApplicationVersion()).versionName;
+    if (latest !== resolved.version) {
+      if (options.promote) await DBOS.setLatestApplicationVersion(resolved.version);
+      else {
+        warn(
+          `this worker runs version ${resolved.version} but the app's latest is ${latest}; ` +
+            "runs queued without a version go to the latest. Start with { promote: true } to take them here",
+        );
+      }
+    }
+    await DBOS.registerQueue(resolved.queueName);
+    await warnAboutStrandedRuns(resolved);
+    const summary = unconfiguredSummary(worker.unconfigured, resolved.driversByVendor.size);
+    if (summary && !options.quiet) warn(summary);
+  } catch (err) {
+    // Once DBOS is launched, the caller gets no worker to stop: stop it here, so no run goes on
+    // in a worker nobody holds, and the next startWorker launches afresh.
+    let stopFailed: { error: unknown } | undefined;
+    if (launched) await worker.stop().catch((error: unknown) => (stopFailed = { error }));
+    else {
+      await credentials
+        .close()
+        .catch((e: unknown) => warn(`closing the credentials listener failed: ${errorMessage(e)}`));
+    }
+    current = previous;
+    if (stopFailed) {
+      throw new AggregateError(
+        [err, stopFailed.error],
+        `${errorMessage(err)} (and stopping DBOS failed too: ${errorMessage(stopFailed.error)})`,
+        { cause: err },
+      );
+    }
+    throw err;
+  }
+  return worker;
+}
+
+/**
+ * The workflow's outline, read from its file, which every run is held to. A workflow whose
+ * outline cannot be read does not start: nothing could say where its calls are.
+ */
+function outlineOf(wf: WorkflowDefinition<any, any>): WorkflowOutline {
+  const { outline, source } = outlineWithSource(wf, readSource(wf.file));
+  if ("error" in outline) {
+    throw new Error(
+      `Workflow "${wf.name}" cannot be outlined, so its runs could not be held to its code: ${outline.error}`,
+    );
+  }
+  return { file: outline.file, lineStarts: lineStartsOf(source!), calls: callsOf(outline.nodes) };
+}
+
+/**
+ * Warns about unfinished runs this worker will never pick up: started on another version of
+ * the app, or queued on another queue (such as the single "sanoma" queue before queues were
+ * named per app, or the sandbox queue before sandbox runs went on the app's).
+ */
+async function warnAboutStrandedRuns({ appName, version, queueName }: ResolvedConfig) {
+  const runs = await DBOS.listWorkflows({
+    status: dbosStatusesOf("queued", "running"),
+    applicationName: appName,
+    loadInput: false,
+    loadOutput: false,
+  });
+  const otherVersion = runs.filter((r) => r.applicationVersion && r.applicationVersion !== version);
+  // Recovery moves a worker's own runs to DBOS's internal queues, which are fine.
+  const otherQueue = runs.filter(
+    (r) => !otherVersion.includes(r) && r.queueName && r.queueName !== queueName && !r.queueName.startsWith("_dbos_"),
+  );
+  if (!otherVersion.length && !otherQueue.length) return;
+  const ids = [...otherVersion, ...otherQueue].map((r) => r.workflowID);
+  warn(
+    `${otherVersion.length} unfinished run(s) of "${appName}" belong to another version and ${otherQueue.length} ` +
+      `wait on another queue, so this worker (version ${version}, queue ${queueName}) will not run them: ` +
+      `${ids.slice(0, 5).join(", ")}${ids.length > 5 ? ", …" : ""}. Run the version that started them, or move each ` +
+      `with DBOSClient.forkWorkflow(id, step, { applicationVersion: "${version}", queueName: "${queueName}" }) ` +
+      `and cancel the original; resumeWorkflow(id, { queueName: "${queueName}" }) moves a run on this version to this queue.`,
+  );
+}
+
+/** Registers the name with DBOS: its runs take the definition of that name from the running worker. */
+function register(name: string) {
+  DBOS.registerWorkflow((args: RunArgs) => quietIfSandbox(args.sandbox !== undefined, () => runWorkflow(name, args)), {
+    name,
+  });
+}
+
+/** One run of the workflow registered as `name`, on the state of the worker running when it starts. */
+async function runWorkflow(name: string, { input, startedBy, sandbox }: RunArgs): Promise<unknown> {
+  const state = current;
+  // A stopped worker's state stays current while DBOS shuts down.
+  if (!state || state.stopped) throw new Error(`Run of "${name}" started with no worker running`);
+  const wf = state.workflows.get(name);
+  const outline = state.outlines.get(name);
+  // Registered by an earlier worker in this process, whose config had it; this one's has not.
+  if (!wf || !outline) throw new Error(`Run of "${name}" refused: this worker's config has no workflow of that name`);
+  const run: Run = {
+    id: DBOS.workflowID!,
+    workflow: wf.name,
+    actor: startedBy,
+    ...(sandbox === undefined ? {} : { sandbox }),
+    approvals: [],
+    seq: 0,
+    tail: Promise.resolve(),
+    inAll: false,
+    ended: false,
+    outline,
+    state,
+  };
+  await write(run, entry(run, { type: "run.started", input }));
+  let output: unknown;
+  try {
+    try {
+      // The one parse of the input: the client checked it, but sent it as given.
+      const parsed = parseOrThrow(wf.input, input, `The input does not match ${wf.name}'s schema`);
+      if (sandbox !== undefined) {
+        // Imported here, so a live worker never loads the Gherkin parser or faker.
+        const { seedSandbox } = await import("./sandbox.ts");
+        await seedSandbox(run, sandbox);
+      }
+      output = await wf.run(buildCtx(wf, run), parsed);
+    } finally {
+      // Before the outcome is written: a call still queued must find the run ended.
+      run.ended = true;
+    }
+  } catch (err) {
+    const record = entry(run, { type: "run.failed", error: errorInfo(err) });
+    if (isInfrastructureError(err, state)) skipped(record, `the run was interrupted (${errorMessage(err)})`);
+    else await writeFailure(run, record, err);
+    throw err;
+  }
+  await write(run, entry(run, { type: "run.finished", output }));
+  return output;
+}