@sanoma-ai/workflows 0.0.0-stage → 0.2.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/secret.ts

@@ -0,0 +1,92 @@
+import { randomBytes } from "node:crypto";
+import { DriverError } from "./op.ts";
+
+// Secrets are named, never written: `secret("NAME")` in a data file is a marker for a value in
+// the company's secrets store (the credentials table), allowed only at a write-only field. The
+// marker is what declarations, checkpoints and the ledger hold; a driver resolves it
+// (`resolveSecrets`) just before the vendor call. The `./resources` entry, which data files import
+// `secret` from (`sanoma/resources` re-exports it).
+
+/** What `secret()` makes: a plain object, so it reads the same as JSON and across copies of this package. */
+export interface Secret {
+  readonly $secret: string;
+  /** When none is stored, apply makes the value (`generateSecret`) and stores it before the vendor call. */
+  readonly generate?: true;
+}
+
+/** A secret's name: an environment variable's, upper case. */
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * True for one of sanoma's own secrets (`SANOMA_…`, its key and database URLs among them): only a
+ * host, which runs the company, is given them, at its `secrets` input (`HostSpec`); never a vendor.
+ */
+export const isSanomaSecret = (name: string) => name.startsWith("SANOMA_");
+
+/**
+ * Names a stored secret for a write-only field of a data file: `secret("SUPABASE_DB_PASSWORD",
+ * { generate: true })`. With `generate`, apply makes the value when none is stored.
+ */
+export function secret(name: string, options?: { generate: true }): Secret {
+  if (!SECRET_NAME.test(name)) {
+    throw new Error(`secret("${name}"): a secret's name is an environment variable's, upper case: A-Z, 0-9 and _`);
+  }
+  return Object.freeze(options?.generate ? { $secret: name, generate: true as const } : { $secret: name });
+}
+
+/** True for a secret marker, `{ $secret: "NAME" }`. */
+export const isSecret = (value: unknown): value is Secret =>
+  typeof value === "object" && value !== null && typeof (value as { $secret?: unknown }).$secret === "string";
+
+/** The secrets store, as a driver sees it (`CallContext.secrets`). */
+export interface Secrets {
+  /** The stored value, or undefined when there is none. */
+  get(name: string): Promise<string | undefined>;
+  /** The stored value; when there is none, `make()`'s, stored first. */
+  ensure(name: string, make: () => string): Promise<string>;
+}
+
+/** A value for a secret with `generate`: 32 random bytes, base64url. */
+export const generateSecret = (): string => randomBytes(32).toString("base64url");
+
+/** `T` with each secret marker's place holding its value: what `resolveSecrets` returns. */
+export type Resolved<T> = T extends Secret
+  ? string
+  : T extends readonly (infer I)[]
+    ? Resolved<I>[]
+    : T extends object
+      ? { [K in keyof T]: Resolved<T[K]> }
+      : T;
+
+/**
+ * `value` with each secret marker in it replaced by the stored value: generated and stored first
+ * for one with `generate` and none stored. A marker naming nothing stored fails the call, for good.
+ */
+export async function resolveSecrets<T>(value: T, secrets: Secrets): Promise<Resolved<T>> {
+  const resolve = async (v: unknown): Promise<unknown> => {
+    if (isSecret(v)) {
+      const stored = v.generate ? await secrets.ensure(v.$secret, generateSecret) : await secrets.get(v.$secret);
+      if (stored === undefined) {
+        throw new DriverError(`The secret ${v.$secret} is not set: store it before applying`, { retryable: false });
+      }
+      return stored;
+    }
+    if (Array.isArray(v)) return Promise.all(v.map(resolve));
+    if (typeof v !== "object" || v === null) return v;
+    const entries = await Promise.all(Object.entries(v).map(async ([k, item]) => [k, await resolve(item)] as const));
+    return Object.fromEntries(entries);
+  };
+  return (await resolve(value)) as Resolved<T>;
+}
+
+/** A secrets store in memory, for fakes, sandbox runs and tests. */
+export function memorySecrets(initial: Record<string, string> = {}): Secrets {
+  const values = new Map(Object.entries(initial));
+  return {
+    get: async (name) => values.get(name),
+    async ensure(name, make) {
+      if (!values.has(name)) values.set(name, make());
+      return values.get(name)!;
+    },
+  };
+}

package/src/shared.ts

@@ -0,0 +1,126 @@
+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 { ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.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";
+
+/**
+ * The built-in apply workflow's name: the only workflow that may call a writable resource type's
+ * change operations (`create`, `update`, `delete`).
+ */
+export const APPLY_WORKFLOW = "apply";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift and apply. */
+export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([DRIFT_WORKFLOW, APPLY_WORKFLOW]);
+
+/**
+ * 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/source.ts

@@ -0,0 +1,82 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { z } from "zod";
+import { defineConnector, defineDriver, DriverError } from "./op.ts";
+
+// Where a company's files live, and how a change to them is recorded: a git repository on this
+// machine, or one a host cloned. The runtime's writers (the app's Adopt, apply's lockfile) change
+// files under `root`, then commit them through it. The launcher makes one; a config without one
+// writes the files and commits nothing.
+
+/** A company's repository, as the runtime writes to it. */
+export interface Source {
+  /** The repository's root directory. */
+  root: string;
+  /**
+   * Records the files at `paths`, relative to `root`, as one change by `author` (who made it, as
+   * the app names them: a login or a typed name). Its revision; undefined when nothing changed.
+   */
+  commit(change: {
+    paths: string[];
+    message: string;
+    author: string;
+  }): { revision: string } | undefined | Promise<{ revision: string } | undefined>;
+  /** The revision `ref` names, the checked-out one by default. */
+  head(ref?: string): string | Promise<string>;
+  /** Pushes `ref` to the repository at `url`, signed in with `token`. */
+  push?(target: { url: string; token: string; ref: string }): void | Promise<void>;
+}
+
+/**
+ * The built-in operation `sanoma.source.resolve`: the commit `ref` names in the repository at
+ * `url` now, by `git ls-remote` (a branch first, then a tag, peeled; a full commit id is itself).
+ * Apply calls it to fill a host's revision before it plans, and drift to see a merge. `resolveConfig`
+ * registers it when a connector declares a host type.
+ */
+export const sourceOps = defineConnector("sanoma", {
+  source: {
+    resolve: {
+      effect: "read",
+      idempotent: true,
+      description: "Resolve a branch or tag of a git repository to the commit it names now",
+      input: z.object({ url: z.string().min(1), ref: z.string().min(1) }),
+      output: z.object({ revision: z.string() }),
+      target: ({ url, ref }: { url: string; ref: string }) => `${url}#${ref}`,
+    },
+  },
+});
+
+export const SOURCE_RESOLVE = "sanoma.source.resolve" satisfies typeof sourceOps.source.resolve.id;
+
+/** The driver of `sanoma.source.resolve`: git on this machine, with its own credential helpers. */
+export const sourceDriver = defineDriver(sourceOps, {
+  source: { resolve: async ({ url, ref }) => ({ revision: await resolveRevision(url, ref) }) },
+});
+
+const COMMIT = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
+
+/** The commit `ref` (a branch, a tag, `HEAD`, a full ref or a commit id) names in the repository at `url`. */
+export async function resolveRevision(url: string, ref: string): Promise<string> {
+  if (COMMIT.test(ref)) return ref;
+  const { stdout } = await promisify(execFile)("git", ["ls-remote", "--", url, ref, `${ref}^{}`], {
+    // Never a prompt for credentials: a repository that needs them and has none fails.
+    env: { ...process.env, GIT_TERMINAL_PROMPT: "0" },
+    timeout: 30_000,
+  }).catch((err: { stderr?: string; message: string }) => {
+    throw new DriverError(`git ls-remote ${url} failed: ${err.stderr?.trim() || err.message}`, {
+      retryable: true,
+      cause: err,
+    });
+  });
+  const refs = new Map(
+    stdout.split("\n").flatMap((line) => {
+      const [sha, name] = line.split("\t");
+      return sha && name ? [[name, sha] as const] : [];
+    }),
+  );
+  for (const name of [`refs/heads/${ref}`, `refs/tags/${ref}^{}`, `refs/tags/${ref}`, ref]) {
+    const sha = refs.get(name);
+    if (sha) return sha;
+  }
+  throw new DriverError(`${url} has no branch or tag ${ref}`, { retryable: false, vendorCode: "no_such_ref" });
+}

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.2.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);
+  }
+}