@sanoma-ai/workflows 0.7.0 → 0.8.0

package/src/sites.ts

@@ -1,11 +1,11 @@
 import { existsSync, readdirSync } from "node:fs";
-import { join, relative, sep } from "node:path";
+import { basename, join, relative, sep } from "node:path";
 import { childrenOf, type LintProblem, type Node, readSource, type SourceFile } from "./ast.ts";
 import { type CedarPolicySource, visitorPermits } from "./cedar.ts";
 import { keyName } from "./datafile.ts";
 import type { ConfigDescription } from "./describe.ts";
 import { stringValue, unwrap } from "./outline.ts";
-import { filesUnder, isDirectory } from "./paths.ts";
+import { APPS_DIR, appFolders, filesUnder, isDirectory } from "./paths.ts";
 import { START } from "./schema.ts";
 import {
   ANONYMOUS,
@@ -14,6 +14,7 @@ import {
   DATA_VENDOR,
   LOCALE,
   SITE_NAME,
+  siteKey,
   VISITORS,
   WORKFLOW_ACTION,
 } from "./shared.ts";
@@ -64,12 +65,16 @@ export interface SitePage {
   content?: string;
 }
 
-/** A site, `sites/<name>/`, and what it calls. */
+/** A site, `sites/<name>/` or an app's `apps/<app>/sites/<name>/`, and what it calls. */
 export interface SiteEntry {
-  /** Its folder's name, where it is mounted: `/sites/<name>`. */
+  /** Its folder's name, `<app>/<name>` for an app's (`siteKey`): where it is mounted, `/sites/<name>`. */
   name: string;
+  /** The app whose folder holds it (`apps/<app>/sites/`); absent for one at the root. */
+  app?: string;
   /** `defineSite({ title })` in its `site.ts`, when that is a string literal. */
   title?: string;
+  /** `defineSite({ icon })` in its `site.ts`: a Lucide icon's name, as written. */
+  icon?: string;
   /** `defineSite({ public: true })`: served to visitors, not people. */
   public?: true;
   /** `defineSite({ login })`, the connector whose login half signs visitors in, as written: one that names none is among `problems`. */
@@ -109,12 +114,14 @@ const PARAMS: ReadonlySet<string> = new Set(["params"]);
 const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLazyFileRoute"]);
 
 /**
- * The sites under `root`: each folder of `sites/` with a `routes/` whose name is a URL segment,
- * by name (as `@sanoma-ai/app/build`'s `sitesOf` mounts them). Reads `routes/**` and
+ * The sites under `root` (`sitesUnder`): each folder of `sites/`, then of each app's
+ * `apps/<app>/sites/`, with a `routes/` whose name is a URL segment, by key (as
+ * `@sanoma-ai/app/build`'s `sitesOf` mounts them). Reads `routes/**` and
  * `components/**` (`.ts` and `.tsx`, less tests and declarations) of each with oxc, never running
  * them: each page (`SitePage`, from a route's id), each `<RunForm workflow="…" />` and each use of `api`, both imported from `sanoma/site`,
  * called or passed on (`queryFn: api.data.leads.list`):
- * `api.<name>` and `api.<name>.<method>` are a workflow, `api.data.<collection>.<op>` a collection,
+ * `api.<name>` and `api.<name>.<method>` are a workflow, `api.data.<collection>.<op>` (an app's
+ * `api.data.<app>.<collection>.<op>`) a collection,
  * and `api.<vendor>.<resource>.<op>` an operation. A name that is not written out (a variable, a
  * template with holes, a computed member) is skipped, as is a use through a namespace import or a
  * destructured `api`. A call to what `description` does not have, or to an operation a page may
@@ -133,9 +140,11 @@ export function readSites(
   policies?: readonly CedarPolicySource[],
 ): SiteEntry[] {
   if (root === undefined) return [];
-  const dir = join(root, "sites");
   const workflows = new Set(description.workflows.map((wf) => wf.name));
   const collections = new Set(description.collections.map((c) => c.name));
+  // `api.data.<app>.<collection>` passed on as a value reads as a call of `<app>`'s method: it is none.
+  const isAppCollection = ({ kind, name, method }: Written) =>
+    kind === "collection" && collections.has(`${name}.${method}`);
   const ops = new Map(description.ops.map((op) => [op.id, op]));
   // A workflow's api name to its name: two of one api name are a problem on the workflows.
   const byApiName = new Map(description.workflows.map((wf) => [apiNameOf(wf.name), wf.name]));
@@ -193,11 +202,11 @@ export function readSites(
     return { call: { kind, target, via, ...at }, ...(problem && { problem }) };
   };
 
-  return siteNames(dir).map((name) => {
-    const read = readSiteFiles(root, name);
-    const resolved = read.flatMap(({ uses }) => uses.map(resolve));
+  return sitesUnder(root).map(({ name, app, dir }) => {
+    const read = readSiteFiles(root, dir);
+    const resolved = read.flatMap(({ uses }) => uses.filter((use) => !isAppCollection(use)).map(resolve));
     const pages = pagesOf(read);
-    const siteFile = `sites/${name}/site.ts`;
+    const siteFile = `${dir}/site.ts`;
     const { problems: optionProblems, ...options } = siteOptionsOf(join(root, siteFile), connectors);
     const calls = resolved.map((r) => r.call);
     const problems = [
@@ -212,7 +221,7 @@ export function readSites(
     const warnings = options.public
       ? read.flatMap(({ route, warning }) => (warning && !pages.get(route!.path)?.content ? [warning] : []))
       : [];
-    return { name, ...options, pages: sorted, calls, problems, warnings };
+    return { name, ...(app && { app }), ...options, pages: sorted, calls, problems, warnings };
   });
 }
 
@@ -225,9 +234,9 @@ function pagesOf(read: readonly { route?: SitePage }[]): Map<string, SitePage> {
   return pages;
 }
 
-/** Each of site `name`'s files under `root`, as `readSiteFile` reads it, by path. */
-const readSiteFiles = (root: string, name: string) =>
-  SITE_DIRS.flatMap((sub) => filesUnder(join(root, "sites", name, sub), isSource))
+/** Each file of the site in `dir` (relative to `root`), as `readSiteFile` reads it, by path. */
+const readSiteFiles = (root: string, dir: string) =>
+  SITE_DIRS.flatMap((sub) => filesUnder(join(root, dir, sub), isSource))
     .toSorted()
     .flatMap((path) => {
       const file = readSource(path);
@@ -241,8 +250,8 @@ const readSiteFiles = (root: string, name: string) =>
  */
 export function siteContentPages(root: string): Record<string, string> {
   return Object.fromEntries(
-    siteNames(join(root, "sites")).flatMap((name) =>
-      [...pagesOf(readSiteFiles(root, name)).values()].flatMap(({ path, content }) =>
+    sitesUnder(root).flatMap(({ dir }) =>
+      [...pagesOf(readSiteFiles(root, dir)).values()].flatMap(({ path, content }) =>
         content ? [[path, content]] : [],
       ),
     ),
@@ -257,13 +266,44 @@ export function siteContentPages(root: string): Record<string, string> {
 export function siteLocales(root: string): Record<string, string[]> {
   const none = new Set<string>();
   return Object.fromEntries(
-    siteNames(join(root, "sites")).flatMap((name) => {
-      const { locales } = siteOptionsOf(join(root, "sites", name, "site.ts"), { vendors: none, logins: none });
+    sitesUnder(root).flatMap(({ name, dir }) => {
+      const { locales } = siteOptionsOf(join(root, dir, "site.ts"), { vendors: none, logins: none });
       return locales ? [[name, locales]] : [];
     }),
   );
 }
 
+/**
+ * Each site's icon (`defineSite({ icon })`, a Lucide icon's name as written) under `root`, by name,
+ * for the sites whose `site.ts` gives one: the icons the app's build bundles (`virtual:sanoma/icons`).
+ * Read as `readSites` reads it, never run.
+ */
+export function siteIcons(root: string): Record<string, string> {
+  const none = new Set<string>();
+  return Object.fromEntries(
+    sitesUnder(root).flatMap(({ name, dir }) => {
+      const { icon } = siteOptionsOf(join(root, dir, "site.ts"), { vendors: none, logins: none });
+      return icon === undefined ? [] : [[name, icon]];
+    }),
+  );
+}
+
+/**
+ * The sites under `root`, by key (`siteKey`): each folder of `sites/` with a `routes/` whose name
+ * is a URL segment, then each app's `apps/<app>/sites/`, with its folder relative to `root`.
+ */
+export const sitesUnder = (root: string): { name: string; app?: string; dir: string }[] => [
+  ...siteNames(join(root, "sites")).map((name) => ({ name, dir: `sites/${name}` })),
+  ...appFolders(root).flatMap((folder) => {
+    const app = basename(folder);
+    return siteNames(join(folder, "sites")).map((name) => ({
+      name: siteKey(app, name),
+      app,
+      dir: `${APPS_DIR}/${app}/sites/${name}`,
+    }));
+  }),
+];
+
 /** The sites in `dir`: each folder with a `routes/` whose name is a URL segment, sorted. */
 const siteNames = (dir: string): string[] =>
   isDirectory(dir)
@@ -379,9 +419,12 @@ function contentKind(callee: Node, content: ReadonlySet<string>): string | undef
 function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" | "name" | "method"> | undefined {
   const path = memberPath(member, api);
   if (!path?.length) return undefined;
-  const [first, second, third] = path as [string, ...string[]];
+  const [first, second] = path as [string, ...string[]];
+  // `api.data.<collection>.<op>`, or an app's, `api.data.<app>.<collection>.<op>`.
   if (first === DATA_VENDOR)
-    return path.length === 3 ? { kind: "collection", name: second!, method: third } : undefined;
+    return path.length === 3 || path.length === 4
+      ? { kind: "collection", name: path.slice(1, -1).join("."), method: path.at(-1) }
+      : undefined;
   if (path.length === 3) return { kind: "op", name: path.join(".") };
   if (path.length > 2) return undefined;
   return { kind: "workflow", name: first, ...(second !== undefined && { method: second }) };
@@ -414,14 +457,14 @@ const unread = (what: string, as: string) => `${what} is read without running si
 /**
  * What `site.ts` says of its site, read without running it, and what is wrong there: its default
  * export must be `defineSite({ … })` written out, so it can be read at all; then `title` when it is
- * a string, `public`, `login` and `locales`, which must be literals. `login` is kept as written; one on a
+ * a string, `icon`, `public`, `login` and `locales`, which must be literals. `login` is kept as written; one on a
  * site that is not public, or naming no connector of the config with a login half, is a problem.
  * `locales` is kept only when it has no problem.
  */
 function siteOptionsOf(
   path: string,
   connectors: SiteConnectors,
-): Pick<SiteEntry, "title" | "public" | "login" | "locales"> & { problems: LintProblem[] } {
+): Pick<SiteEntry, "title" | "icon" | "public" | "login" | "locales"> & { problems: LintProblem[] } {
   const file = readSource(path);
   if (typeof file === "string") return { problems: [] };
   const problems: LintProblem[] = [...file.problems];
@@ -453,6 +496,8 @@ function siteOptionsOf(
     options?.properties.findLast((p: Node) => isWritten(p) && keyName(p.key) === name);
 
   const title = stringValue(property("title")?.value);
+  // Cosmetic: one that is not a string (tsc refuses it) is shown as none, never a problem that stops a site.
+  const icon = stringValue(property("icon")?.value);
   const publicAt = property("public");
   const flag = unwrap(publicAt?.value);
   const isPublic = flag?.type === "Literal" && flag.value === true;
@@ -495,6 +540,7 @@ function siteOptionsOf(
   if (localesMessage) problem(localesAt, localesMessage);
   return {
     ...(title !== undefined && { title }),
+    ...(icon !== undefined && { icon }),
     ...(isPublic && { public: true as const }),
     ...(login !== undefined && { login }),
     ...(localesAt && !localesMessage && isPublic && !loginAt && { locales }),

package/src/source.ts

@@ -28,8 +28,9 @@ export interface Source {
   /** Pushes `ref` to the repository at `url`, signed in with `token` (a draft by its `branch`). */
   push?(target: { url: string; token: string; ref: string }): void | Promise<void>;
   /**
-   * The draft `id` (letters, digits, `_` and `-`), opened: made from the checked-out revision the
-   * first time, then the same one, edits and all, until its branch is deleted.
+   * The draft `id` (letters, digits, `_` and `-`), opened on its branch (`draftBranch`): made from
+   * the checked-out revision the first time, then the same one, edits and all, until its branch is
+   * deleted.
    */
   draft?(id: string): Promise<Draft>;
   /** The open drafts' ids, sorted. */
@@ -47,13 +48,27 @@ export interface Source {
   /** The URL of the repository this one was cloned from (`origin`); undefined when it has none. */
   remoteUrl?(): Promise<string | undefined>;
   /**
-   * Fast-forwards the checked-out branch to `ref` in the repository at `url`, signed in with
-   * `token`, as `push` is: only when `ref` is checked out, nothing is uncommitted and the remote's
-   * `ref` contains it; otherwise `skipped`, saying why. The checked-out revision after.
+   * Fast-forwards the branch `ref` to `ref` in the repository at `url`, signed in with `token`, as
+   * `push` is, where it is checked out: the root's checked-out branch, or an open draft's (by its
+   * `branch`), whose new commits on the host it takes so. Only when nothing is uncommitted there
+   * and the remote's `ref` contains it; otherwise `skipped`, saying why. The revision after.
    */
   follow?(target: { url: string; token: string; ref: string }): Promise<{ revision: string } | { skipped: string }>;
+  /**
+   * How many commits the source repository of the app `folder` (the URL its `apps/<folder>/app.ts`
+   * names) has on its default branch that the checked-out one lacks, of those changing what an
+   * update merges (`apps/<folder>/` and `package.json`): fetched now. An error when the app names
+   * no source.
+   */
+  behind?(folder: string): Promise<number>;
 }
 
+/** The branch of the draft `id`, as a source names it: `draft/<id>`. */
+export const draftBranch = (id: string) => `draft/${id}`;
+
+/** The draft whose branch `branch` is (`draftBranch`), or undefined for a branch that is no draft's. */
+export const draftOf = (branch: string) => (branch.startsWith("draft/") ? branch.slice("draft/".length) : undefined);
+
 /**
  * A draft: a checkout of its own, at `root`, on `branch`, which `commit` records in as
  * `Source.commit` does in its root. Its `node_modules` may be the root's own install, linked in:
@@ -63,6 +78,36 @@ export interface Draft {
   branch: string;
   root: string;
   commit: Source["commit"];
+  /**
+   * Takes an app into the draft: fetches `ref` (the default branch by default) of the repository
+   * at `url`, a source (a public company repo with one `apps/<folder>/`), and merges it in with its
+   * history (`--allow-unrelated-histories`), as one merge commit by `author`. What it merges is
+   * `apps/<folder>/` and `package.json`; every other file stays the draft's. `folder` may be left
+   * out when the source has one app. Refused when the draft has `apps/<folder>/` already.
+   */
+  take?(app: { url: string; ref?: string; folder?: string; author: string }): Promise<AppMerge>;
+  /**
+   * Merges the new commits of the app `folder`'s source (the URL its `app.ts` names, its default
+   * branch) into the draft, by `author`, as `take` merges: `apps/<folder>/` and `package.json`.
+   */
+  update?(app: { folder: string; author: string }): Promise<AppMerge>;
+}
+
+/**
+ * What taking or updating an app merged into a draft. A line both sides changed is committed with
+ * git's markers in its file (ours, the merge base and theirs), so the draft's checks fail until the
+ * agent resolves it; a file one side deleted stays as the draft had it. The merge commit keeps the
+ * source's history either way.
+ */
+export interface AppMerge {
+  /** The app's folder: `apps/<folder>/`. */
+  folder: string;
+  /** The draft's commit after the merge. */
+  revision: string;
+  /** The source's commits the merge brought in that change the app's folder or `package.json`; 0 when the draft had them all, and nothing was merged. */
+  merged: number;
+  /** The files git could not merge, relative to the root, committed with conflict markers; empty when it merged clean. */
+  conflicts: string[];
 }
 
 /** A draft's change: the files it touches, relative to the root, and git's `--stat` of it. */
@@ -135,3 +180,121 @@ export async function resolveRevision(url: string, ref: string): Promise<string>
   }
   throw new DriverError(`${url} has no branch or tag ${ref}`, { retryable: false, vendorCode: "no_such_ref" });
 }
+
+// A git host's side of a change: the pull request a branch is reviewed in, merged through and
+// closed by, the `sanoma` commit status the review card links from, whether the host refuses a
+// change to `main` that is not a merge, and the host's webhooks. A connector carries it as its
+// remote half (`ConnectorSetup.remote`), the way a login or a model half is carried.
+
+/** A repository on a host: `owner/name`. */
+export interface RepoRef {
+  owner: string;
+  name: string;
+}
+
+/** A pull request (a merge request, on a host that calls it so), as a change follows it. */
+export interface PullRequest {
+  number: number;
+  /** Its page on the host. */
+  url: string;
+  /** The branch it merges. */
+  branch: string;
+  /** The branch's commit it was read at. */
+  head: string;
+  state: "open" | "closed" | "merged";
+  /** The commit its merge made on the base branch, once merged. */
+  mergeSha?: string;
+}
+
+/**
+ * Whether the host refuses a change to a branch that does not follow the rules: `pullRequest`
+ * when a direct push is refused (every change is a merge), `check` when a merge needs the
+ * `sanoma` status to pass. `reason` says why neither can be read or held, such as a plan that
+ * has no rules.
+ */
+export interface HostEnforcement {
+  pullRequest: boolean;
+  check: boolean;
+  reason?: string;
+}
+
+/**
+ * One repository on a host, opened by its remote half with the company's credentials, read when
+ * a call needs them; a half may keep a token for a few minutes (its README says how long), so a
+ * token stored later is used soon after. A failure is a `DriverError` (retryable as the host's
+ * status says).
+ */
+export interface SourceHost {
+  /**
+   * A token that writes to the repository: the company's app's on the host when it is installed
+   * on the owner, else a person's token (`prefer: "token"` asks for that one first). It is never
+   * logged; a push signs in with it. A `DriverError` whose `vendorCode` is `no_token` when there is
+   * neither.
+   */
+  token(prefer?: "app" | "token"): Promise<string>;
+  /** The pull request of `branch`: the open one, else the latest; undefined when it has none. */
+  pullRequestFor(branch: string): Promise<PullRequest | undefined>;
+  pullRequest(number: number): Promise<PullRequest>;
+  /** Opens a pull request of `branch` into `base`; the open one when `branch` has one already. */
+  openPullRequest(request: { branch: string; base: string; title: string; body: string }): Promise<PullRequest>;
+  /**
+   * Squash-merges pull request `number` when its branch is still at `sha`, as one commit titled
+   * `title`. A `DriverError` whose `vendorCode` is `head_moved` when the branch moved on, and
+   * `not_mergeable` when the host refuses the merge (a conflict, a rule).
+   */
+  mergePullRequest(number: number, merge: { sha: string; method: "squash"; title?: string }): Promise<{ sha: string }>;
+  closePullRequest(number: number): Promise<void>;
+  /** Deletes `branch`; nothing when it is gone already. */
+  deleteBranch?(branch: string): Promise<void>;
+  /** Sets the `sanoma` status on commit `sha`, linking to `targetUrl`. */
+  setStatus(status: {
+    sha: string;
+    state: "pending" | "success" | "failure";
+    description: string;
+    targetUrl?: string;
+  }): Promise<void>;
+  /** What the host enforces on `base` (see `HostEnforcement`). */
+  enforcement(base: string): Promise<HostEnforcement>;
+  /** Uploads a PNG the pull request's comment shows; its URL. */
+  uploadImage?(png: Uint8Array, name: string): Promise<string>;
+  /** Writes the pull request's comment that carries `marker`, once: a second call edits it. */
+  upsertComment?(number: number, marker: string, body: string): Promise<void>;
+}
+
+/** What a host's webhook says happened: a branch pushed, or a pull request closed (merged or not). */
+export type RemoteEvent =
+  | { kind: "pushed"; repo: RepoRef; branch: string; head: string }
+  | { kind: "closed"; repo: RepoRef; branch: string; number: number; merged: boolean; sha?: string };
+
+/** What a remote half reads the company's credentials with, as a login or a model half reads them. */
+export interface RemoteContext {
+  /** Secrets' values by name: the environment's first, then the stored credentials (`LoginContext.secrets`). */
+  secrets(names: readonly string[]): Promise<Map<string, string>>;
+}
+
+/** A connector's remote half (`ConnectorSetup.remote`): a git host's repositories, made once per resolved config. */
+export interface RemoteHalf {
+  /** The repository a clone URL of this host names, or undefined for another host's. */
+  matches(url: string): RepoRef | undefined;
+  /** The repository `repo`, with the company's credentials. */
+  open(repo: RepoRef, context: RemoteContext): SourceHost;
+  /**
+   * The events a webhook request carries, once its signature is verified: throws for a missing or
+   * bad signature, and answers `[]` for an event the change workflow does not follow.
+   */
+  webhook?(request: Request, context: RemoteContext): Promise<RemoteEvent[]>;
+  /** The accounts the company's app on the host is installed on: where it acts with no person's token. */
+  owners?(context: RemoteContext): Promise<{ login: string; kind: "user" | "organization" }[]>;
+}
+
+/** The remote half among `remotes` (`ResolvedConfig.remotes`) whose host `url` is on, with its vendor and the repository. */
+export function remoteFor(
+  remotes: ReadonlyMap<string, RemoteHalf>,
+  url: string,
+): { vendor: string; remote: RemoteHalf; repo: RepoRef } | undefined {
+  for (const [vendor, remote] of remotes) {
+    const repo = remote.matches(url);
+    if (repo) return { vendor, remote, repo };
+  }
+  return undefined;
+}

package/src/supervisor.ts

@@ -1,5 +1,4 @@
-import { resolveConfig, type SanomaConfig } from "./config.ts";
-import { shouldWake } from "./db.ts";
+import type { SanomaConfig } from "./config.ts";
 import type { SelfStop } from "./deadlines.ts";
 import { warn } from "./log.ts";
 import { errorMessage } from "./shared.ts";
@@ -21,10 +20,11 @@ export interface Supervisor {
    */
   resume(): Promise<void>;
   /**
-   * A wakeup's `GET /wake?generation=N`: `resume` when the worker stopped with `generation`
-   * registered (`shouldWake`); a no-op for any other, and while one starts or runs.
+   * A wakeup's `GET /wake`: `resume` when the worker stopped itself; a no-op while one starts or
+   * runs. A wake that arrives late, twice or for a replaced registration starts a worker that
+   * finds nothing to do and stops again on its own check.
    */
-  wake(generation: number): Promise<void>;
+  wake(): Promise<void>;
   /** Stops the worker running or starting, and starts none again. */
   stop(): Promise<void>;
 }
@@ -53,7 +53,6 @@ export async function superviseWorker(config: SanomaConfig, options: SupervisorO
   let closed = false;
   // A write while the worker starts or runs, since it began starting.
   let heard = false;
-  let databaseUrl: string | undefined;
 
   const launch = async () => {
     heard = false;
@@ -64,7 +63,7 @@ export async function superviseWorker(config: SanomaConfig, options: SupervisorO
   const selfStopped = (stopped: SelfStop) => {
     worker = undefined;
     if (closed) return;
-    // Resumed first, so `stopped` is false when `onStopped` (the exit rule) looks.
+    // Resumed first, so `stopped` is false when `onStopped` looks.
     if (heard) void supervisor.resume();
     onStopped?.(stopped);
   };
@@ -89,11 +88,7 @@ export async function superviseWorker(config: SanomaConfig, options: SupervisorO
           starting = undefined;
         }));
     },
-    async wake(generation) {
-      if (!supervisor.stopped) return;
-      databaseUrl ??= resolveConfig(config).databaseUrl;
-      if (await shouldWake(databaseUrl, generation)) await supervisor.resume();
-    },
+    wake: () => (supervisor.stopped ? supervisor.resume() : Promise.resolve()),
     async stop() {
       closed = true;
       await starting;

package/src/version.ts

@@ -63,24 +63,33 @@ export function computeVersion({
 }): 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}`;
+  const workflows = definitions.map(codeOf).toSorted(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+  return `${appName}@${sha256([appName, RUNTIME_VERSION, STEP_LAYOUT, installedDbosVersion(), ...workflows])}`;
 }
 
+/**
+ * A hash of the built-in `change` workflow's own code, which each change run carries (its
+ * `changeCode` attribute) so a worker on another version of the app may take it over
+ * (`carryChangeRuns` in worker.ts): what `computeVersion` hashes of that one workflow, with
+ * `RUNTIME_VERSION`, `STEP_LAYOUT` and the installed DBOS version. Never the company's workflows
+ * nor `DBOS__APPVERSION`, so a merge that changes only the company's code leaves it as it is.
+ */
+export function changeCodeOf(change: WorkflowDefinition<any, any>): string {
+  return sha256([RUNTIME_VERSION, STEP_LAYOUT, installedDbosVersion(), codeOf(change)]);
+}
+
+const sha256 = (parts: unknown[]) => createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+
+/** What the hashes read of a workflow: its name, the source of its `run`, its operations and its input schema. */
+const codeOf = (wf: WorkflowDefinition<any, any>) =>
+  [
+    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;
+
 /** 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 {