@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/src/datafile.ts

@@ -0,0 +1,481 @@
+import { basename, dirname, join } from "node:path";
+import type { Node } from "./ast.ts";
+import { inside, nearestDir, RELATIVE } from "./paths.ts";
+import { type Secret, SECRET_NAME } from "./secret.ts";
+
+// The one definition of what a data file may hold, over an ESTree program from oxc: the reader
+// (`resources.ts`), `lintResources` (`lint.ts`) and the oxlint plugin (`plugin.ts`) all
+// read a file through `readDataFile`. Type imports only, so the plugin, which oxlint hands its
+// own tree, never loads oxc-parser.
+
+/** Something a data file may not hold, at UTF-16 offsets into its text. */
+export interface DataFileProblem {
+  start: number;
+  end: number;
+  message: string;
+}
+
+/** A name in a data file that refers to a declared resource: one imported from a data file, or exported by this one. */
+export class Reference {
+  readonly name: string;
+  constructor(name: string) {
+    this.name = name;
+  }
+}
+
+const REFERENCE = Symbol.for("sanoma.reference");
+Object.defineProperty(Reference.prototype, REFERENCE, { value: true });
+
+/** True for a `Reference`, made by any copy of this package: read by a registered symbol, not `instanceof`. */
+export const isReference = (value: unknown): value is Reference =>
+  typeof value === "object" && value !== null && REFERENCE in value;
+
+/** What `secret("NAME")` stands for in a data file: its marker, `{ $secret: "NAME", generate?: true }`. */
+export type SecretRef = Secret;
+
+/** A value in a data file: a literal, a reference to a declared resource, or a secret's marker. */
+export type DataValue =
+  | null
+  | boolean
+  | number
+  | string
+  | Reference
+  | SecretRef
+  | DataValue[]
+  | { [field: string]: DataValue };
+
+/** An `import { name } from "…"`: of a connector's constructors (`from "…/resources"`), or of another data file's resource. */
+export interface DataFileImport {
+  kind: "constructors" | "file";
+  /** The specifier as written. */
+  source: string;
+  /** The name the other module exports. */
+  imported: string;
+  /** The name it has in this file. */
+  local: string;
+  start: number;
+}
+
+/** An `export const name = vendor.type({ … })`. */
+export interface DataFileExport {
+  name: string;
+  /** The local name of the constructors it calls (`github`). */
+  vendor: string;
+  type: string;
+  desired: { [field: string]: DataValue };
+  /** The `export const` statement. */
+  start: number;
+  end: number;
+}
+
+export interface DataFile {
+  imports: DataFileImport[];
+  /** Each `export const` whose value is in the subset. */
+  exports: DataFileExport[];
+  /** Every name an `export const` declares, its value in the subset or not. */
+  declared: string[];
+  problems: DataFileProblem[];
+}
+
+/** A connector's constructors entry: a package specifier that ends in `/resources`. */
+const CONSTRUCTORS = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*\/resources$/;
+
+/** Where a data file imports `secret` from; checked before `CONSTRUCTORS`, which they match too. */
+export const SECRET_ENTRIES: ReadonlySet<string> = new Set(["sanoma/resources", "@sanoma-ai/workflows/resources"]);
+const SECRET_CALL = '`secret("NAME")` or `secret("NAME", { generate: true })`, NAME upper case (A-Z, 0-9 and _)';
+
+const SHAPE =
+  "a data file holds only imports, `export const <name> = <vendor>.<type>({ … })` and `export default [ … ]`";
+const IMPORTS =
+  "import resource constructors from a connector's resources entry " +
+  '(`import { github } from "@sanoma-ai/connector-github/resources"`) ' +
+  'and resources from other data files (`import { site } from "./github.ts"`), and `secret` from "sanoma/resources"';
+const VALUES = "write a string, number, boolean, null, object or array, or name a declared resource";
+
+/**
+ * Reads a data file's program without running it: its imports, each `export const` resource
+ * with its fields evaluated, and everything outside the data-file subset as a problem that says
+ * what to write instead.
+ *
+ * The subset: named imports, from a connector's `…/resources` entry or a `.ts` data file;
+ * `export const <name> = <vendor>.<type>({ … })`, one per statement, its argument built of
+ * strings (template literals without `${}` too), numbers, booleans, null, objects and arrays,
+ * and names of resources this file declares or imports; and `export default [a, b]`.
+ *
+ * `root` is the directory relative imports must stay in: by default the nearest `resources/`
+ * directory above `filename`, else the file's own.
+ */
+export function readDataFile(
+  program: Node,
+  filename: string,
+  root: string = nearestDir(filename, ["resources"]),
+): DataFile {
+  const problems: DataFileProblem[] = [];
+  const fail = (node: { start: number; end: number }, message: string) =>
+    problems.push({ start: node.start, end: node.end, message });
+  const imports: DataFileImport[] = [];
+  const exports: DataFileExport[] = [];
+  // Names a refused import or declaration binds: reported once, where they are bound.
+  const refused = new Set<string>();
+  // The local names of `secret`.
+  const secrets = new Set<string>();
+
+  // Imports and top-level names first, each once: imports are hoisted, and a reference may name
+  // a resource declared further down. An unexported const is refused where it is declared, not
+  // again where it is used.
+  const bound = new Set<string>();
+  const bind = (id: Node) => {
+    if (bound.has(id.name)) fail(id, `${id.name} is declared twice in this file: give each its own name`);
+    bound.add(id.name);
+  };
+  const declared = new Set<string>();
+  for (const s of program.body) {
+    if (s.type === "ImportDeclaration") {
+      for (const sp of s.specifiers) bind(sp.local);
+      readImport(s);
+      continue;
+    }
+    const decl = s.type === "ExportNamedDeclaration" ? s.declaration : s;
+    if (decl?.type !== "VariableDeclaration") continue;
+    for (const d of decl.declarations) {
+      if (d.id.type !== "Identifier") continue;
+      bind(d.id);
+      (decl === s ? refused : declared).add(d.id.name);
+    }
+  }
+
+  for (const s of program.body) {
+    switch (s.type) {
+      case "ImportDeclaration":
+        break;
+      case "ExportNamedDeclaration":
+        readExport(s);
+        break;
+      case "ExportDefaultDeclaration":
+        readDefault(s);
+        break;
+      case "ExportAllDeclaration":
+        fail(s, `export * is not allowed in a data file: ${SHAPE}`);
+        break;
+      case "VariableDeclaration": {
+        const name = s.declarations[0]?.id?.name;
+        fail(
+          s,
+          name === undefined
+            ? `an unexported declaration is not allowed in a data file: ${SHAPE}`
+            : `\`${s.kind} ${name}\` is not allowed in a data file: export it as a resource, \`export const ${name} = <vendor>.<type>({ … })\`, or write its value where it is used`,
+        );
+        break;
+      }
+      default:
+        fail(s, `${describe(s)} is not allowed in a data file: ${SHAPE}`);
+    }
+  }
+
+  function readImport(s: Node) {
+    const spec: string = s.source.value;
+    if (s.importKind === "type") {
+      fail(s, "`import type` is not allowed in a data file: it holds values only, and the constructors type them");
+      return;
+    }
+    const refusal = whyRefused(spec);
+    if (refusal) {
+      fail(s.source, `import "${spec}" is not allowed in a data file: ${refusal}`);
+      for (const sp of s.specifiers) refused.add(sp.local.name);
+      return;
+    }
+    if (!s.specifiers.length) {
+      fail(s, `import "${spec}" is not allowed in a data file: it imports nothing, and a data file runs no code`);
+      return;
+    }
+    if (SECRET_ENTRIES.has(spec)) {
+      for (const sp of s.specifiers) {
+        if (
+          sp.type === "ImportSpecifier" &&
+          sp.importKind !== "type" &&
+          (sp.imported.name ?? sp.imported.value) === "secret"
+        ) {
+          secrets.add(sp.local.name);
+        } else {
+          fail(sp, `a data file imports only \`secret\` from "${spec}": \`import { secret } from "${spec}"\``);
+          refused.add(sp.local.name);
+        }
+      }
+      return;
+    }
+    for (const sp of s.specifiers) {
+      if (sp.type !== "ImportSpecifier") {
+        const how = sp.type === "ImportNamespaceSpecifier" ? `import * as ${sp.local.name}` : `import ${sp.local.name}`;
+        fail(sp, `${how} is not allowed in a data file: import the names you use, \`import { name } from "${spec}"\``);
+        continue;
+      }
+      if (sp.importKind === "type") {
+        fail(sp, "`type` imports are not allowed in a data file: it holds values only, and the constructors type them");
+        continue;
+      }
+      const imported: string = sp.imported.name ?? sp.imported.value;
+      const kind = RELATIVE.test(spec) ? "file" : "constructors";
+      imports.push({ kind, source: spec, imported, local: sp.local.name, start: sp.start });
+    }
+  }
+
+  /** Why an import's specifier is not allowed in a data file, or undefined when it is. */
+  function whyRefused(spec: string): string | undefined {
+    if (!RELATIVE.test(spec)) return CONSTRUCTORS.test(spec) ? undefined : IMPORTS;
+    if (!spec.endsWith(".ts")) return "name the data file with its `.ts` extension";
+    if (!inside(root, join(dirname(filename), spec))) {
+      return `it reaches outside ${basename(root)}/; import only other data files`;
+    }
+    return undefined;
+  }
+
+  function readExport(s: Node) {
+    const decl = s.declaration;
+    if (!decl) {
+      fail(
+        s,
+        s.source
+          ? `export … from "${s.source.value}" is not allowed in a data file: import what you reference, and export only resources declared here`
+          : "export { … } is not allowed in a data file: export each resource where it is declared, `export const name = <vendor>.<type>({ … })`",
+      );
+      return;
+    }
+    if (decl.type !== "VariableDeclaration") {
+      fail(s, `${describe(decl)} is not allowed in a data file: ${SHAPE}`);
+      return;
+    }
+    if (decl.kind !== "const") {
+      fail(s, `\`export ${decl.kind}\` is not allowed in a data file: use \`export const\``);
+      return;
+    }
+    if (decl.declarations.length !== 1) {
+      fail(s, "declare one resource per `export const`");
+      return;
+    }
+    const [d] = decl.declarations;
+    if (d.id.type !== "Identifier") {
+      fail(d.id, "an `export const` names one resource: `export const name = <vendor>.<type>({ … })`");
+      return;
+    }
+    const name: string = d.id.name;
+    // A second declaration of the name was reported where it is bound.
+    if (exports.some((e) => e.name === name)) return;
+    const init = d.init;
+    const callee = init?.type === "CallExpression" ? init.callee : undefined;
+    if (
+      callee?.type !== "MemberExpression" ||
+      callee.computed ||
+      callee.object.type !== "Identifier" ||
+      callee.property.type !== "Identifier"
+    ) {
+      fail(
+        init ?? d,
+        `export const ${name} must be a resource constructor call, \`<vendor>.<type>({ … })\`, with <vendor> imported from a connector's resources entry`,
+      );
+      return;
+    }
+    const vendor: string = callee.object.name;
+    const type: string = callee.property.name;
+    if (refused.has(vendor)) return;
+    if (imports.find((i) => i.local === vendor)?.kind !== "constructors") {
+      fail(
+        callee.object,
+        `${vendor} is not a connector's resource constructors: import it from the connector's resources entry, \`import { ${vendor} } from "@sanoma-ai/connector-${vendor}/resources"\``,
+      );
+      return;
+    }
+    const [arg] = init.arguments;
+    if (init.arguments.length !== 1 || arg.type !== "ObjectExpression") {
+      fail(init, `${vendor}.${type} takes one object literal: \`${vendor}.${type}({ … })\``);
+      return;
+    }
+    const desired = value(arg);
+    if (desired !== undefined) {
+      exports.push({ name, vendor, type, desired: desired as DataFileExport["desired"], start: s.start, end: s.end });
+    }
+  }
+
+  function readDefault(s: Node) {
+    const list = s.declaration;
+    if (list.type !== "ArrayExpression") {
+      fail(list, "export default must list this file's resources: `export default [a, b]`");
+      return;
+    }
+    for (const el of list.elements) {
+      if (el?.type !== "Identifier") {
+        fail(el ?? list, "export default must list this file's resources by name: `export default [a, b]`");
+      } else if (!declared.has(el.name)) {
+        fail(el, `${el.name} is not declared in this file: export default lists this file's resources`);
+      }
+    }
+  }
+
+  /** The value an expression stands for, or undefined (with a problem) when the subset has none. */
+  function value(node: Node): DataValue | undefined {
+    switch (node.type) {
+      case "Literal":
+        if (node.regex) return refuse(node, "a regular expression is not allowed in a data file: write it as a string");
+        if (node.bigint !== undefined && node.bigint !== null)
+          return refuse(node, "a bigint is not allowed in a data file: write a number, or a string");
+        return node.value as null | boolean | number | string;
+      case "TemplateLiteral":
+        if (node.expressions.length) {
+          return refuse(node, "a template with `${…}` is not allowed in a data file: write the string out");
+        }
+        return node.quasis[0].value.cooked as string;
+      case "UnaryExpression":
+        if (node.operator === "-" && node.argument.type === "Literal" && typeof node.argument.value === "number") {
+          return -node.argument.value;
+        }
+        return refuse(node, `\`${node.operator}\` is not allowed in a data file: write the value out`);
+      case "ArrayExpression": {
+        const items: DataValue[] = [];
+        let ok = true;
+        for (const el of node.elements) {
+          const item =
+            el === null
+              ? refuse(node, "an empty array slot is not allowed in a data file: write null")
+              : el.type === "SpreadElement"
+                ? refuse(el, "a spread is not allowed in a data file: write the items out, so the reader sees each")
+                : value(el);
+          if (item === undefined) ok = false;
+          else items.push(item);
+        }
+        return ok ? items : undefined;
+      }
+      case "ObjectExpression": {
+        const fields = new Map<string, DataValue>();
+        let ok = true;
+        for (const p of node.properties) {
+          const field = property(p);
+          if (field && fields.has(field[0])) fail(p, `${field[0]} is given twice: give each field once`);
+          if (!field || fields.has(field[0])) ok = false;
+          else fields.set(...field);
+        }
+        // fromEntries makes each field an own property, even one named `__proto__`.
+        return ok ? Object.fromEntries(fields) : undefined;
+      }
+      case "Identifier":
+        return reference(node);
+      case "MemberExpression": {
+        let base = node;
+        while (base.type === "MemberExpression") base = base.object;
+        if (base.type === "Identifier" && base.name === "process") {
+          return refuse(
+            node,
+            "process is not allowed in a data file: it is read without running, so it cannot read the environment; write the value out, and leave secrets to drivers",
+          );
+        }
+        return refuse(
+          node,
+          "member access is not allowed in a data file: write the value out, or name the resource itself (`site`), not one of its fields",
+        );
+      }
+      case "CallExpression":
+        if (node.callee.type === "Identifier" && secrets.has(node.callee.name)) return readSecret(node);
+        if (node.callee.type === "Identifier" && node.callee.name === "secret" && !bound.has("secret")) {
+          return refuse(node, `import secret to name one: \`import { secret } from "sanoma/resources"\``);
+        }
+        return refuse(
+          node,
+          node.callee.type === "MemberExpression" &&
+            node.callee.object.type === "Identifier" &&
+            imports.some((i) => i.kind === "constructors" && i.local === node.callee.object.name)
+            ? "a resource is declared at the top of a data file: give it its own `export const` and name it here"
+            : "a call is not allowed in a data file: write the value out; the reader never runs code",
+        );
+      case "NewExpression":
+        return refuse(node, "`new` is not allowed in a data file: write the value out (a date as an ISO 8601 string)");
+      case "ArrowFunctionExpression":
+      case "FunctionExpression":
+        return refuse(
+          node,
+          "a function is not allowed in a data file: a field holds a value, and code belongs in a workflow",
+        );
+      case "TSAsExpression":
+      case "TSSatisfiesExpression":
+      case "TSTypeAssertion":
+      case "TSNonNullExpression":
+        return refuse(
+          node,
+          "a type assertion is not allowed in a data file: leave it out; the constructor types the value",
+        );
+      default:
+        return refuse(node, `${describe(node)} is not allowed in a data file: ${VALUES}`);
+    }
+  }
+
+  function property(p: Node): [string, DataValue] | undefined {
+    if (p.type === "SpreadElement") {
+      return refuse(p, "a spread is not allowed in a data file: write the fields out, so the reader sees each");
+    }
+    if (p.kind !== "init" || p.method) {
+      return refuse(p, "a method or accessor is not allowed in a data file: a field holds a value");
+    }
+    if (p.computed) return refuse(p.key, "a computed key is not allowed in a data file: write the field's name");
+    const key = keyName(p.key);
+    if (key === undefined) return refuse(p.key, "write the field's name, or a string");
+    if (key === "$secret") return refuse(p.key, `name a secret with ${SECRET_CALL}`);
+    const v = value(p.value);
+    return v === undefined ? undefined : [key, v];
+  }
+
+  /** A `secret(…)` call's marker: literal arguments only. */
+  function readSecret(node: Node): SecretRef | undefined {
+    const [name, options, ...extra] = node.arguments;
+    if (name?.type !== "Literal" || typeof name.value !== "string" || extra.length) {
+      return refuse(node, `write the secret's name as a string: ${SECRET_CALL}`);
+    }
+    if (!SECRET_NAME.test(name.value))
+      return refuse(name, `${JSON.stringify(name.value)} is not a secret's name: ${SECRET_CALL}`);
+    if (options === undefined) return { $secret: name.value };
+    const [generate, ...others] = options.type === "ObjectExpression" ? options.properties : [];
+    if (
+      others.length ||
+      generate?.type !== "Property" ||
+      generate.computed ||
+      (generate.key.name ?? generate.key.value) !== "generate" ||
+      generate.value.type !== "Literal" ||
+      typeof generate.value.value !== "boolean"
+    ) {
+      return refuse(options, `a secret's options are \`{ generate: true }\` or none: ${SECRET_CALL}`);
+    }
+    return generate.value.value ? { $secret: name.value, generate: true } : { $secret: name.value };
+  }
+
+  function reference(node: Node): Reference | undefined {
+    const name: string = node.name;
+    if (name === "undefined")
+      return refuse(node, "undefined is not allowed in a data file: leave the field out, or write null");
+    const imported = imports.find((i) => i.local === name);
+    if (imported?.kind === "constructors") {
+      return refuse(node, `${name} is a connector's resource constructors, not a resource: name a declared resource`);
+    }
+    if (imported || declared.has(name)) return new Reference(name);
+    if (refused.has(name)) return undefined;
+    return refuse(
+      node,
+      `${name} is not a resource this file declares or imports from a data file: write the value out, or import the resource`,
+    );
+  }
+
+  function refuse(node: { start: number; end: number }, message: string): undefined {
+    fail(node, message);
+    return undefined;
+  }
+
+  return { imports, exports, declared: [...declared], problems };
+}
+
+/** A property's name: an identifier's, or a literal's as a string; undefined for any other key. */
+export const keyName = (key: Node): string | undefined =>
+  key.type === "Identifier" ? key.name : key.type === "Literal" ? String(key.value) : undefined;
+
+/** A node's kind, for a message: `a function declaration`, `an if statement`. */
+function describe(node: Node): string {
+  const words = String(node.type)
+    .replace(/^TS/, "TypeScript ")
+    .replace(/([a-z])([A-Z])/g, "$1 $2")
+    .toLowerCase();
+  return `${/^[aeiou]/.test(words) ? "an" : "a"} ${words}`;
+}

package/src/db.ts

@@ -0,0 +1,197 @@
+import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
+import { Client, Pool } from "pg";
+import { warn } from "./log.ts";
+import { errorMessage } from "./shared.ts";
+
+// The runtime's own tables live in the config's database, beside DBOS's: the credentials and the
+// ledger. What they share is here: the one preparation of a database, a pool that opens once it
+// is prepared and survives a dropped connection, and a table creation two processes may race.
+
+/** A connection or a pool: what the queries take. */
+export type Db = Pick<Pool | Client, "query">;
+
+/** Where the credentials set from the app live. */
+export const CREDENTIALS_TABLE = "sanoma_credentials";
+/** Where the Postgres ledger keeps its records. */
+export const LEDGER_TABLE = "sanoma_ledger";
+
+/** The runtime's tables, each with the word the messages name it by. */
+const TABLES: readonly [what: string, ddl: string][] = [
+  [
+    "credentials",
+    `CREATE TABLE IF NOT EXISTS ${CREDENTIALS_TABLE} (name text PRIMARY KEY, value text NOT NULL, ` +
+      "set_by text NOT NULL, set_at timestamptz NOT NULL DEFAULT now())",
+  ],
+  [
+    "ledger",
+    // `n` is the write order, `id` the record's, which the first write of takes, and `seq` the
+    // record's place in its run: a run reads in `seq` order, then write order.
+    `CREATE TABLE IF NOT EXISTS ${LEDGER_TABLE} (n bigserial PRIMARY KEY, id text NOT NULL UNIQUE, ` +
+      `run_id text NOT NULL, seq integer NOT NULL, record jsonb NOT NULL); ` +
+      `CREATE INDEX IF NOT EXISTS ${LEDGER_TABLE}_run_seq ON ${LEDGER_TABLE} (run_id, seq, n)`,
+  ],
+];
+
+/** The Postgres error code of `err`, or an empty string when it has none. */
+export const pgCode = (err: unknown): string => (err as { code?: unknown } | null)?.code?.toString() ?? "";
+
+/** Postgres's codes for a row type or a table another process made first. */
+const MADE_ALREADY = new Set(["23505", "42P07"]);
+
+/** True for the failure of a create that another process won: what was to be made is there. */
+export const madeAlready = (err: unknown): boolean => MADE_ALREADY.has(pgCode(err));
+
+/**
+ * A pool on the config's database for `what` (a word for the messages). An idle connection that
+ * drops (Postgres restarted) is replaced on the next query; unheard, it would end the process.
+ */
+export function openPool(databaseUrl: string, what: string): Pool {
+  const pool = new Pool({ connectionString: databaseUrl });
+  pool.on("error", (err) => warn(`a ${what} connection failed: ${errorMessage(err)}`));
+  return pool;
+}
+
+/**
+ * What every DBOS handle on the config's database is given (`DBOS.setConfig`, `dbosClient`): DBOS
+ * is told not to set Postgres's `idle_in_transaction_session_timeout` on each connection of its
+ * pool. It sends that `SET` from the pool's `connect` event without awaiting it (dbos-sdk 5.2.11,
+ * dist/src/system_database.js:691), so the pool hands the connection out while it runs: two
+ * queries at once on one client, which pg deprecates. `prepareDatabase` sets the same 60 s guard
+ * on the database instead. Remove the switch when DBOS awaits its `SET`.
+ */
+export const DBOS_DATABASE_OPTIONS = { systemDatabaseIdleTransactionTimeoutMs: 0 } as const;
+
+/**
+ * A DBOS client of the app `applicationName` on the database at `databaseUrl`, as every client of
+ * the runtime, its tests and `@sanoma-ai/testing` make one (`DBOS_DATABASE_OPTIONS`).
+ */
+export const dbosClient = (databaseUrl: string, applicationName?: string): Promise<DBOSClient> =>
+  DBOSClient.create({
+    systemDatabaseUrl: databaseUrl,
+    ...(applicationName !== undefined && { applicationName }),
+    ...DBOS_DATABASE_OPTIONS,
+  });
+
+/**
+ * The `idle_in_transaction_session_timeout` `prepareDatabase` sets: DBOS's own default
+ * (`DEFAULT_IDLE_TRANSACTION_TIMEOUT_MS`, 60_000, in dbos-sdk 5.2.11 dist/src/system_database.js),
+ * how long a frozen or unreachable client may hold the system database's locks.
+ */
+const IDLE_IN_TRANSACTION_TIMEOUT = "60s";
+
+/** Postgres's code for a statement the role lacks the privilege for. */
+const INSUFFICIENT_PRIVILEGE = "42501";
+
+/** A pool opened on first use, once its database is prepared, and ended by `close`. */
+export interface LazyPool {
+  db(): Promise<Pool>;
+  close(): Promise<void>;
+}
+
+/**
+ * A pool for `what` on the database at `databaseUrl`, opened on the first `db()` once the
+ * database is prepared (`prepareDatabase`). A preparation that fails lets the pool go, so the
+ * next `db()` tries again. `close` ends the pool, for good: a `db()` after it is refused.
+ */
+export function lazyPool(databaseUrl: string, what: string): LazyPool {
+  let pool: Pool | undefined;
+  let closed = false;
+  return {
+    async db() {
+      if (closed) throw new Error(`the ${what} store is closed`);
+      const current = (pool ??= openPool(databaseUrl, what));
+      try {
+        await prepareDatabase(databaseUrl);
+      } catch (err) {
+        if (pool === current) pool = undefined;
+        await current.end().catch(() => undefined);
+        throw err;
+      }
+      return current;
+    },
+    async close() {
+      closed = true;
+      const current = pool;
+      pool = undefined;
+      await current?.end();
+    },
+  };
+}
+
+/** Each database prepared, or being prepared, by its URL. A failed preparation is forgotten. */
+const prepared = new Map<string, Promise<void>>();
+
+/**
+ * Makes the database at `databaseUrl` ready for the runtime, once per process and URL: the
+ * database itself and DBOS's tables when they are not there yet (as a worker's launch makes
+ * them; credentials may be set, and a ledger read, before any worker has run), then the
+ * credentials and ledger tables, and its idle-transaction timeout (`guardIdleTransactions`).
+ * Two processes preparing one database both succeed. A
+ * preparation that fails is forgotten, so the next call tries again.
+ */
+export function prepareDatabase(databaseUrl: string): Promise<void> {
+  let preparing = prepared.get(databaseUrl);
+  if (!preparing) {
+    preparing = prepare(databaseUrl).catch((err: unknown) => {
+      if (prepared.get(databaseUrl) === preparing) prepared.delete(databaseUrl);
+      throw err;
+    });
+    prepared.set(databaseUrl, preparing);
+  }
+  return preparing;
+}
+
+async function prepare(databaseUrl: string): Promise<void> {
+  try {
+    await DBOS.migrate(databaseUrl);
+  } catch (err) {
+    // The database, or a DBOS table, made by another process meanwhile: it is there.
+    if (!madeAlready(err)) throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+  }
+  const conn = new Client({ connectionString: databaseUrl });
+  await conn.connect();
+  try {
+    for (const [what, ddl] of TABLES) await createTable(conn, ddl, what);
+    await guardIdleTransactions(conn);
+  } finally {
+    await conn.end();
+  }
+}
+
+/**
+ * Sets `idle_in_transaction_session_timeout` on the database, for each session that starts after,
+ * as DBOS would per connection (`DBOS_DATABASE_OPTIONS`), unless the server, the role or the
+ * database sets it already. One process at a time (an advisory lock), so two preparing at once
+ * both succeed. A role that may not alter the database leaves it, quietly: its administrator decides.
+ */
+async function guardIdleTransactions(db: Db): Promise<void> {
+  try {
+    await db.query(`DO $$ BEGIN
+      PERFORM pg_advisory_xact_lock(hashtext('sanoma.idle_in_transaction_session_timeout'));
+      IF current_setting('idle_in_transaction_session_timeout') = '0' AND NOT EXISTS (
+        SELECT FROM pg_db_role_setting s JOIN pg_database d ON d.oid = s.setdatabase, unnest(s.setconfig) c
+        WHERE d.datname = current_database() AND s.setrole = 0 AND c LIKE 'idle_in_transaction_session_timeout=%'
+      ) THEN
+        EXECUTE format('ALTER DATABASE %I SET idle_in_transaction_session_timeout = %L', current_database(),
+          '${IDLE_IN_TRANSACTION_TIMEOUT}');
+      END IF;
+    END $$`);
+  } catch (err) {
+    if (pgCode(err) !== INSUFFICIENT_PRIVILEGE) {
+      throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+    }
+  }
+}
+
+/**
+ * Runs `ddl` (`CREATE TABLE IF NOT EXISTS`, and the like) on `db`. Two processes racing to create
+ * the same table both succeed; any other failure names the `what` table, with its cause.
+ */
+export async function createTable(db: Db, ddl: string, what: string): Promise<void> {
+  try {
+    await db.query(ddl);
+  } catch (err) {
+    if (madeAlready(err)) return;
+    throw new Error(`could not prepare the ${what} table: ${errorMessage(err)}`, { cause: err });
+  }
+}