@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/datafile.ts

@@ -1,6 +1,8 @@
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import type { Node } from "./ast.ts";
 import { inside, nearestDir, RELATIVE } from "./paths.ts";
+import { type Secret, SECRET_NAME } from "./secret.ts";
+import { checkCollection, errorMessage } from "./shared.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
@@ -22,8 +24,26 @@ export class Reference {
   }
 }
 
-/** A value in a data file: a literal, or a reference to a declared resource. */
-export type DataValue = null | boolean | number | string | Reference | DataValue[] | { [field: string]: DataValue };
+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 {
@@ -49,11 +69,24 @@ export interface DataFileExport {
   end: number;
 }
 
+/** An `export const name = collection({ … })` in `resources/data.ts`, its declaration one `collection()` takes. */
+export interface DataFileCollection {
+  /** The `export const`'s name. */
+  export: string;
+  /** The collection's name. */
+  name: string;
+  /** 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. */
+  /** Each collection `resources/data.ts` declares (`COLLECTIONS_FILE`); none in any other data file. */
+  collections: DataFileCollection[];
+  /** Every name an `export const` declares as a resource, its value in the subset or not: none in `resources/data.ts`. */
   declared: string[];
   problems: DataFileProblem[];
 }
@@ -61,12 +94,30 @@ export interface DataFile {
 /** 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, and `sanoma`, the runtime's own resource constructors
+ * (its people: `sanoma.person`, `.agent`, `.group`); checked before `CONSTRUCTORS`, which they match too.
+ */
+export const SECRET_ENTRIES: ReadonlySet<string> = new Set(["sanoma/resources", "@sanoma-ai/workflows/resources"]);
+/** Where `resources/data.ts` imports `collection` from, and the only imports it may make. */
+export const DATA_ENTRIES: ReadonlySet<string> = new Set(["sanoma/data", "@sanoma-ai/workflows/data"]);
+/**
+ * The one data file that holds collections, relative to `resources/`. Workflows and the runtime
+ * import it, so it imports only `collection` from "sanoma/data" and holds nothing else.
+ */
+export const COLLECTIONS_FILE = "data.ts";
+const COLLECTION_CALL = '`export const <name> = collection({ name: "…", key: "…", fields: { … } })`';
+const COLLECTIONS_ONLY =
+  "resources/data.ts holds collections only, since workflows and the runtime import it: " +
+  `\`import { collection } from "sanoma/data"\` and ${COLLECTION_CALL}; declare a connector's resources in another data file`;
+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 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";
 
 /**
@@ -78,6 +129,10 @@ const VALUES = "write a string, number, boolean, null, object or array, or name
  * `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]`.
+ * `resources/data.ts` (`COLLECTIONS_FILE`) is the exception, the one data file workflows and the
+ * runtime import: it imports only `collection` from "sanoma/data", and each `export const` is
+ * `collection({ … })` with its values written out (`DataFile.collections`). No other data file
+ * declares a collection, and none imports one.
  *
  * `root` is the directory relative imports must stay in: by default the nearest `resources/`
  * directory above `filename`, else the file's own.
@@ -92,8 +147,15 @@ export function readDataFile(
     problems.push({ start: node.start, end: node.end, message });
   const imports: DataFileImport[] = [];
   const exports: DataFileExport[] = [];
+  const collections: DataFileCollection[] = [];
+  const collectionsFile = relative(root, filename) === COLLECTIONS_FILE;
+  // What the file may hold, for the problems that say so.
+  const shape = collectionsFile ? COLLECTIONS_ONLY : SHAPE;
   // Names a refused import or declaration binds: reported once, where they are bound.
   const refused = new Set<string>();
+  // The local names of `secret`, and of `collection`.
+  const secrets = new Set<string>();
+  const collectionCalls = 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
@@ -130,20 +192,20 @@ export function readDataFile(
         readDefault(s);
         break;
       case "ExportAllDeclaration":
-        fail(s, `export * is not allowed in a data file: ${SHAPE}`);
+        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`,
+            ? `an unexported declaration is not allowed in a data file: ${shape}`
+            : `\`${s.kind} ${name}\` is not allowed in a data file: export it as ${collectionsFile ? `a collection, \`export const ${name} = collection({ … })\`` : `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}`);
+        fail(s, `${describe(s)} is not allowed in a data file: ${shape}`);
     }
   }
 
@@ -153,6 +215,16 @@ export function readDataFile(
       fail(s, "`import type` is not allowed in a data file: it holds values only, and the constructors type them");
       return;
     }
+    if (collectionsFile !== DATA_ENTRIES.has(spec)) {
+      fail(
+        s.source,
+        collectionsFile
+          ? `import "${spec}" is not allowed in resources/data.ts: ${COLLECTIONS_ONLY}`
+          : `import "${spec}" is not allowed here: collections are declared in resources/data.ts, the one data file workflows and the runtime import; move it there`,
+      );
+      for (const sp of s.specifiers) refused.add(sp.local.name);
+      return;
+    }
     const refusal = whyRefused(spec);
     if (refusal) {
       fail(s.source, `import "${spec}" is not allowed in a data file: ${refusal}`);
@@ -163,6 +235,31 @@ export function readDataFile(
       fail(s, `import "${spec}" is not allowed in a data file: it imports nothing, and a data file runs no code`);
       return;
     }
+    // The one name each of these entries gives a data file.
+    const [only, locals] = SECRET_ENTRIES.has(spec)
+      ? ["secret", secrets]
+      : DATA_ENTRIES.has(spec)
+        ? ["collection", collectionCalls]
+        : [];
+    if (locals) {
+      for (const sp of s.specifiers) {
+        const imported =
+          sp.type === "ImportSpecifier" && sp.importKind !== "type" && (sp.imported.name ?? sp.imported.value);
+        if (imported === only) {
+          locals.add(sp.local.name);
+        } else if (imported === "sanoma" && SECRET_ENTRIES.has(spec)) {
+          // The runtime's own constructors, matched to its connector as a connector's are.
+          imports.push({ kind: "constructors", source: spec, imported, local: sp.local.name, start: sp.start });
+        } else {
+          const [names, allowed] = SECRET_ENTRIES.has(spec)
+            ? ["`secret` and `sanoma`", `${only}, sanoma`]
+            : [`\`${only}\``, only];
+          fail(sp, `a data file imports only ${names} from "${spec}": \`import { ${allowed} } 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}`;
@@ -181,8 +278,11 @@ export function readDataFile(
 
   /** 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 (!RELATIVE.test(spec)) return CONSTRUCTORS.test(spec) || DATA_ENTRIES.has(spec) ? undefined : IMPORTS;
     if (!spec.endsWith(".ts")) return "name the data file with its `.ts` extension";
+    if (join(dirname(filename), spec) === join(root, COLLECTIONS_FILE)) {
+      return "resources/data.ts holds collections, which no resource names; import resources from other data files";
+    }
     if (!inside(root, join(dirname(filename), spec))) {
       return `it reaches outside ${basename(root)}/; import only other data files`;
     }
@@ -201,7 +301,7 @@ export function readDataFile(
       return;
     }
     if (decl.type !== "VariableDeclaration") {
-      fail(s, `${describe(decl)} is not allowed in a data file: ${SHAPE}`);
+      fail(s, `${describe(decl)} is not allowed in a data file: ${shape}`);
       return;
     }
     if (decl.kind !== "const") {
@@ -219,9 +319,16 @@ export function readDataFile(
     }
     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;
+    if (exports.some((e) => e.name === name) || collections.some((c) => c.export === name)) return;
     const init = d.init;
     const callee = init?.type === "CallExpression" ? init.callee : undefined;
+    // A name a refused import binds was reported with the import.
+    const head = callee?.type === "MemberExpression" ? callee.object : callee;
+    if (head?.type === "Identifier" && refused.has(head.name)) return;
+    if (collectionsFile) {
+      readCollection(s, init, name);
+      return;
+    }
     if (
       callee?.type !== "MemberExpression" ||
       callee.computed ||
@@ -236,7 +343,6 @@ export function readDataFile(
     }
     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,
@@ -255,7 +361,51 @@ export function readDataFile(
     }
   }
 
+  /** An `export const` in resources/data.ts: a collection, its declaration plain values `collection()` takes. */
+  function readCollection(s: Node, init: Node | undefined, name: string) {
+    if (
+      init?.type !== "CallExpression" ||
+      init.callee.type !== "Identifier" ||
+      !collectionCalls.has(init.callee.name)
+    ) {
+      fail(init ?? s, `export const ${name} must be a collection: ${COLLECTIONS_ONLY}`);
+      return;
+    }
+    const [arg] = init.arguments;
+    if (init.arguments.length !== 1 || arg.type !== "ObjectExpression") {
+      fail(init, `collection() takes one object literal: ${COLLECTION_CALL}`);
+      return;
+    }
+    const declaration = value(arg) as { [field: string]: DataValue } | undefined;
+    if (declaration === undefined) {
+      // What value() refused it reported; the collection is still declared here, which the
+      // runtime runs, when its name is written out.
+      const named = arg.properties.find(
+        (p: Node) => p.type === "Property" && !p.computed && keyName(p.key) === "name",
+      )?.value;
+      if (named?.type === "Literal" && typeof named.value === "string") {
+        collections.push({ export: name, name: named.value, start: s.start, end: s.end });
+      }
+      return;
+    }
+    if (Object.keys(declaration).some((k) => !DECLARATION_KEYS.has(k)) || namesDeclaration(declaration)) {
+      fail(arg, `collection() takes \`{ name, key, fields, title? }\`, its values written out: ${COLLECTION_CALL}`);
+      return;
+    }
+    try {
+      checkCollection(declaration);
+    } catch (err) {
+      fail(arg, errorMessage(err));
+      return;
+    }
+    collections.push({ export: name, name: declaration.name as string, start: s.start, end: s.end });
+  }
+
   function readDefault(s: Node) {
+    if (collectionsFile) {
+      fail(s, `export default is not allowed in resources/data.ts: ${COLLECTIONS_ONLY}`);
+      return;
+    }
     const list = s.declaration;
     if (list.type !== "ArrayExpression") {
       fail(list, "export default must list this file's resources: `export default [a, b]`");
@@ -332,6 +482,13 @@ export function readDataFile(
         );
       }
       case "CallExpression":
+        if (node.callee.type === "Identifier" && secrets.has(node.callee.name)) return readSecret(node);
+        if (node.callee.type === "Identifier" && collectionCalls.has(node.callee.name)) {
+          return refuse(node, `a collection is declared at the top of resources/data.ts: ${COLLECTION_CALL}`);
+        }
+        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" &&
@@ -369,12 +526,36 @@ export function readDataFile(
       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 = p.key.type === "Identifier" ? p.key.name : p.key.type === "Literal" ? String(p.key.value) : undefined;
+    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")
@@ -396,9 +577,20 @@ export function readDataFile(
     return undefined;
   }
 
-  return { imports, exports, declared: [...declared], problems };
+  return { imports, exports, collections, declared: collectionsFile ? [] : [...declared], problems };
 }
 
+/** What `collection()` reads of its declaration. */
+const DECLARATION_KEYS: ReadonlySet<string> = new Set(["name", "key", "fields", "title"]);
+
+/** True when a value names a declaration: a collection's declaration is plain values only. */
+const namesDeclaration = (v: DataValue): boolean =>
+  v instanceof Reference || (typeof v === "object" && v !== null && Object.values(v).some(namesDeclaration));
+
+/** 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)

package/src/db.ts

@@ -1,11 +1,13 @@
 import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
-import { Client, Pool } from "pg";
+import { setTimeout as delay } from "node:timers/promises";
+import { Client, escapeIdentifier, 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.
+// The runtime's own tables live in the config's database, beside DBOS's: the credentials, the
+// ledger and the collections' records. 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">;
@@ -14,6 +16,8 @@ export type Db = Pick<Pool | Client, "query">;
 export const CREDENTIALS_TABLE = "sanoma_credentials";
 /** Where the Postgres ledger keeps its records. */
 export const LEDGER_TABLE = "sanoma_ledger";
+/** Where the collections keep their records (`collection.ts`): one row per collection and key, the record as JSON. */
+export const DATA_TABLE = "sanoma_data";
 
 /** The runtime's tables, each with the word the messages name it by. */
 const TABLES: readonly [what: string, ddl: string][] = [
@@ -30,13 +34,23 @@ const TABLES: readonly [what: string, ddl: string][] = [
       `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)`,
   ],
+  [
+    "data",
+    `CREATE TABLE IF NOT EXISTS ${DATA_TABLE} (collection text NOT NULL, key text NOT NULL, record jsonb NOT NULL, ` +
+      "updated_at timestamptz NOT NULL DEFAULT now(), updated_by text NOT NULL, PRIMARY KEY (collection, key))",
+  ],
 ];
 
 /** 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"]);
+/**
+ * Postgres's codes for a database, a row type or a table another process made first. Two racing
+ * `CREATE TABLE IF NOT EXISTS` both pass the check, and the loser fails on the table's row type in
+ * `pg_type`: as a unique violation (23505), or as a duplicate object (42710, "type ... already
+ * exists"). Two racing `CREATE DATABASE` fail as 42P04, or on `pg_database` as 23505.
+ */
+const MADE_ALREADY = new Set(["23505", "42P04", "42P07", "42710"]);
 
 /** 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));
@@ -82,6 +96,9 @@ const IDLE_IN_TRANSACTION_TIMEOUT = "60s";
 /** Postgres's code for a statement the role lacks the privilege for. */
 const INSUFFICIENT_PRIVILEGE = "42501";
 
+/** Postgres's code for a database that is not there (`invalid_catalog_name`). */
+const NO_DATABASE = "3D000";
+
 /** A pool opened on first use, once its database is prepared, and ended by `close`. */
 export interface LazyPool {
   db(): Promise<Pool>;
@@ -125,9 +142,9 @@ 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.
+ * credentials, ledger and data tables, and its idle-transaction timeout (`guardIdleTransactions`).
+ * Two processes preparing one database both succeed: the second waits for the first
+ * (`lockPreparation`). A preparation that fails is forgotten, so the next call tries again.
  */
 export function prepareDatabase(databaseUrl: string): Promise<void> {
   let preparing = prepared.get(databaseUrl);
@@ -141,33 +158,86 @@ export function prepareDatabase(databaseUrl: string): Promise<void> {
   return preparing;
 }
 
+/** The error a preparation fails with, its cause `err`. */
+const unprepared = (err: unknown): Error =>
+  new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+
 async function prepare(databaseUrl: string): Promise<void> {
+  const conn = await lockPreparation(databaseUrl).catch((err: unknown) => {
+    throw unprepared(err);
+  });
   try {
-    await DBOS.migrate(databaseUrl);
+    await DBOS.migrate(databaseUrl).catch((err: unknown) => {
+      // A DBOS table made meanwhile by a release from before the lock, mid-upgrade: it is there.
+      if (!madeAlready(err)) throw unprepared(err);
+    });
+    for (const [what, ddl] of TABLES) await createTable(conn, ddl, what);
+    await guardIdleTransactions(conn);
+  } finally {
+    // Ending the session releases the lock; a failure to end it must not hide the preparation's.
+    await conn.end().catch(() => undefined);
+  }
+}
+
+/**
+ * A connection to the database at `databaseUrl` (made first when missing) holding the
+ * preparation's session lock until it ends, so a second process waits, then finds everything
+ * made. Racing `DBOS.migrate`s lose to each other in many ways (40P01, XX000), so the race is
+ * prevented rather than each loss forgiven. The lock is polled, never waited for by a blocked
+ * statement: `CREATE INDEX CONCURRENTLY` waits on that statement's snapshot, a deadlock Postgres
+ * cannot see (the lock's holder is this connection, not the migration's).
+ */
+async function lockPreparation(databaseUrl: string): Promise<Client> {
+  const conn = await connect(databaseUrl).catch(async (err: unknown) => {
+    if (pgCode(err) !== NO_DATABASE) throw err;
+    await createDatabase(databaseUrl);
+    return connect(databaseUrl);
+  });
+  try {
+    const ask = "SELECT pg_try_advisory_lock(hashtext('sanoma.prepareDatabase')) AS locked";
+    while (!(await conn.query<{ locked: boolean }>(ask)).rows[0]!.locked) await delay(50);
+    return conn;
   } 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 });
+    await conn.end().catch(() => undefined);
+    throw err;
   }
-  const conn = new Client({ connectionString: databaseUrl });
+}
+
+async function connect(databaseUrl: string): Promise<Client> {
+  const conn = new Client({ connectionString: databaseUrl, connectionTimeoutMillis: 10_000 });
+  // An error nobody listens for ends the process; the query in flight fails with it.
+  conn.on("error", (err) => warn(`a preparation connection failed: ${errorMessage(err)}`));
   await conn.connect();
+  return conn;
+}
+
+/**
+ * Makes the database at `databaseUrl` through its server's `postgres` database, as `DBOS.migrate`
+ * would. Another process making it first is no failure.
+ */
+async function createDatabase(databaseUrl: string): Promise<void> {
+  const url = new URL(databaseUrl);
+  const name = decodeURI(url.pathname.slice(1));
+  url.pathname = "/postgres";
+  const admin = await connect(url.toString());
   try {
-    for (const [what, ddl] of TABLES) await createTable(conn, ddl, what);
-    await guardIdleTransactions(conn);
+    await admin.query(`CREATE DATABASE ${escapeIdentifier(name)}`);
+  } catch (err) {
+    if (!madeAlready(err)) throw err;
   } finally {
-    await conn.end();
+    await admin.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.
+ * database sets it already. `db` holds the preparation's lock, so one process at a time. 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=%'
@@ -177,9 +247,7 @@ async function guardIdleTransactions(db: Db): Promise<void> {
       END IF;
     END $$`);
   } catch (err) {
-    if (pgCode(err) !== INSUFFICIENT_PRIVILEGE) {
-      throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
-    }
+    if (pgCode(err) !== INSUFFICIENT_PRIVILEGE) throw unprepared(err);
   }
 }
 

package/src/define.ts

@@ -2,20 +2,24 @@ import { fileURLToPath } from "node:url";
 import { getCallSites } from "node:util";
 import { z } from "zod";
 import { isOp, type Op } from "./op.ts";
-import { approverLabel } from "./shared.ts";
 
 /**
- * Who is acting: the person or service that starts a run or decides an approval. `id` is
- * whatever the deployment identifies people by; `groups` are the roles it vouches for.
+ * Who is acting: the person or agent that starts a run, calls an operation or decides an
+ * approval. With people declared (`sanoma.person`, `sanoma.agent`, `sanoma.group` in data files),
+ * a principal is a declared one, its `groups` every group that lists it; an agent is in the group
+ * `agents`, and `onBehalfOf` names the person it acts for.
  */
 export interface Principal {
   id: string;
   groups?: string[];
+  /** For an agent: the id of the person whose instruction it carries. */
+  onBehalfOf?: string;
 }
 
 export const Principal: z.ZodType<Principal> = z.object({
   id: z.string().regex(/\S/, "id must not be blank"),
   groups: z.array(z.string()).optional(),
+  onBehalfOf: z.string().regex(/\S/, "onBehalfOf must not be blank").optional(),
 });
 
 export type Builtin = "approval" | "sleep" | "all";
@@ -29,12 +33,6 @@ export const Approver: z.ZodType<Approver> = z.union(
   { error: 'needs an approver: a name, or { group: "name" }' },
 );
 
-/** Why `by` may not decide the approval, naming who may. */
-export const notApprover = ({ approver }: Pick<ApprovalState, "approver">, by: Principal): string =>
-  typeof approver === "string"
-    ? `${by.id} is not the approver; ${approverLabel(approver)} is`
-    : `${by.id} is not in ${approverLabel(approver)}`;
-
 /** True when the two name the same approver: the same id, or the same group. */
 export const sameApprover = (a: Approver, b: Approver): boolean =>
   typeof a === "string" || typeof b === "string" ? a === b : a.group === b.group;
@@ -92,6 +90,8 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
   opSeq?: number;
   /** For a policy request: the held call's input. */
   input?: unknown;
+  /** For a policy request: the policies that held the call, by id, when the policy names them. */
+  reasons?: string[];
   status: "pending" | "approved" | "rejected";
   requestedAt: number;
   decidedBy?: string;
@@ -99,6 +99,8 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
   note?: string;
   /** The `id` of the decision message the run decided with, when it had one. */
   decidedWith?: string;
+  /** Set when the run's own actor decided it: nobody else could (`mayDecide`). */
+  alone?: true;
   /**
    * Messages that were ignored: decisions sent by someone who may not decide the approval,
    * and messages that were not a decision. `by` is the sender, when the message named one, and