@sanoma-ai/workflows 0.5.0 → 0.7.0

package/src/config.ts

@@ -5,6 +5,7 @@ import { DBOS } from "@dbos-inc/dbos-sdk";
 import { type ApplyDeclared, applyWorkflow } from "./apply.ts";
 import { applySteps } from "./apply-steps.ts";
 import { callWorkflow } from "./call-workflow.ts";
+import { changeDriver, changeOps, reservedFor } from "./change.ts";
 import {
   type Collection,
   collectionsConnector,
@@ -34,11 +35,15 @@ import {
 } from "./op.ts";
 import { type CedarPolicySource, policyAt } from "./cedar.ts";
 import type { Policy } from "./policy.ts";
-import { isChangeOp, type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
+import { type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
 import { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS, CALL_WORKFLOW, DATA_VENDOR } from "./shared.ts";
 import { sourceDriver, sourceOps } from "./source.ts";
 import type { Steps } from "./steps.ts";
+import { checkSchedule } from "./schedules.ts";
 import { computeVersion } from "./version.ts";
+import type { DeclaredResource } from "./resources.ts";
+import { checkWakeupOps, type DeclaredWakeup } from "./wakeup.ts";
+import { checkDatabaseOps } from "./database.ts";
 
 /**
  * What a worker runs, on which connectors: the argument to `startWorker`.
@@ -65,7 +70,7 @@ export interface SanomaConfig {
    * only, for tests.
    */
   ledger?: LedgerStore;
-  /** Postgres for the runtime. Defaults to `SANOMA_DATABASE_URL`, then the local docker compose database. */
+  /** Postgres for the runtime. Defaults to `SANOMA_DATABASE_URL`, then `DEFAULT_DATABASE_URL`. */
   databaseUrl?: string;
   /** The file that defined the config, absolute, when known. Set by `defineConfig` from its call site. */
   file?: string;
@@ -92,6 +97,12 @@ export interface SanomaConfig {
    * records in the config's database, and in memory for a sandbox run.
    */
   collections?: readonly Collection[];
+  /**
+   * Run the wakeup service inside this instance (`sanoma serve`), for other instances' wakeups
+   * to register with. An instance that runs it must not stop, so `startWorker` refuses a config
+   * that sets it and declares a wakeup of its own.
+   */
+  wakeup?: true;
 }
 
 /** A config, checked, with everything a worker, client or app derives from it. */
@@ -107,8 +118,9 @@ export interface ResolvedConfig {
   /** The DBOS queue runs are started on: `sanoma:<appName>`. */
   queueName: string;
   /**
-   * The operations the connectors declare, by id, the built-in `sanoma.source.resolve` when one
-   * declares a host type, and the collections' (`data.<name>.<op>`).
+   * The operations the connectors declare, by id, the built-in `sanoma.change.*` (`changeOps`, in
+   * every config), `sanoma.source.resolve` when one declares a host type, and the collections'
+   * (`data.<name>.<op>`).
    */
   ops: Map<string, Op>;
   /** The drivers' functions, by operation id, each guarded by its driver's `env` (`indexDrivers`). */
@@ -118,10 +130,22 @@ export interface ResolvedConfig {
    * `connectors` order: what `drivers` indexes and the credentials are read from (`credentialsOf`).
    */
   driversByVendor: Map<string, Driver>;
-  /** The makers of the fakes the connectors attach, by vendor id in `connectors` order: each sandbox run makes its own. */
+  /**
+   * The makers of the fakes the connectors attach, by vendor id in `connectors` order: each
+   * sandbox run makes its own. Resolved with `fakes: "instance"`, each gives its vendor's
+   * instance fake (`instanceFakes`).
+   */
   fakes: Map<string, () => Fake<any, any>>;
+  /**
+   * Resolved with `fakes: "instance"` (a demo): each vendor's one fake, by vendor id, made once
+   * for this resolution. Each is its vendor's driver (`driversByVendor`), so live runs, sandbox
+   * runs and direct calls all call it, and the world's Givens seed it (`applyGivens`).
+   */
+  instanceFakes?: ReadonlyMap<string, Fake<any, any>>;
   /** The makers of the login halves the connectors attach, by vendor id in `connectors` order: the app makes one per public site that names it. */
   logins: ReadonlyMap<string, NonNullable<ConnectorSetup["login"]>>;
+  /** The makers of the model halves the connectors attach, by vendor id in `connectors` order: the app makes each once for its model registry. */
+  models: ReadonlyMap<string, NonNullable<ConnectorSetup["model"]>>;
   /** `scenarios/` in `root`, as a `file:` URL, when that directory exists. */
   scenarios?: URL;
   /** The resource types the connectors declare, by `<vendor>.<type>`: what the drift workflow checks and scenarios seed. */
@@ -160,6 +184,11 @@ export interface ResolvedConfig {
   root?: string;
 }
 
+/**
+ * The database when neither the config nor `SANOMA_DATABASE_URL` names one: the dev Postgres
+ * `pnpm db:up` starts in this checkout. The `sanoma` launcher never falls back to it: with no
+ * URL named it starts the company's own Postgres and sets `SANOMA_DATABASE_URL` to it.
+ */
 export const DEFAULT_DATABASE_URL = "postgresql://postgres:dbos@localhost:5433/sanoma";
 
 /** Returns the config, with the file it is called from as its `file`: its directory is the config's `root`. */
@@ -198,6 +227,17 @@ export function rootOf(config: Pick<SanomaConfig, "root" | "file">): string | un
       : undefined;
 }
 
+/** What `resolveConfig` is given besides the config. */
+export interface ResolveOptions {
+  /**
+   * `"instance"`: run the whole instance on the connectors' fakes, as a demo does: each vendor's
+   * driver is one fake made for this resolution (`instanceFakes`), which every run and call
+   * shares. The collections stay on the config's database. Refused for a vendor whose connector
+   * attaches a driver and no fake, which would otherwise run live.
+   */
+  fakes?: "instance";
+}
+
 /**
  * Checks a config and derives what the runtime needs from it: the drivers and fakes from the
  * connectors' setups (`withSetup`), the collections' operations, driver and fake, and from
@@ -208,7 +248,7 @@ export function rootOf(config: Pick<SanomaConfig, "root" | "file">): string | un
  * `root`. Each entry point resolves once: the worker and the client when they start, the app at
  * `startApp`, the `sanoma` bin when it loads the config.
  */
-export function resolveConfig(config: SanomaConfig): ResolvedConfig {
+export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}): ResolvedConfig {
   if (!Array.isArray(config.connectors)) {
     throw new Error("The config needs `connectors`: the connectors its workflows call, as their packages export them");
   }
@@ -237,21 +277,29 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const databaseUrl = resolveDatabaseUrl(config);
   const declared = [...collections.values()];
   const dataStore = declared.length ? lazyPool(databaseUrl, "data") : undefined;
+  // Built-in, in every config: a change's operations, which the template's policy names (`sanoma.change.merge`).
   const ops = indexConnectors([
     ...config.connectors,
+    changeOps,
     ...(hosts ? [sourceOps] : []),
     ...(dataStore ? [collectionsConnector(declared)] : []),
   ]);
-  const driversByVendor = new Map([...makersOf(config.connectors, "driver")].map(([vendor, make]) => [vendor, make()]));
+  checkWakeupOps(types, ops);
+  checkDatabaseOps(types, ops);
+  const fakes = makersOf(config.connectors, "fake");
+  const instanceFakes = options.fakes === "instance" ? instanceFakesOf(config.connectors, fakes) : undefined;
+  const driversByVendor = instanceFakes
+    ? new Map([...instanceFakes].map(([vendor, fake]) => [vendor, fake.driver]))
+    : new Map([...makersOf(config.connectors, "driver")].map(([vendor, make]) => [vendor, make()]));
   const drivers = indexDrivers(
     [
       ...driversByVendor.values(),
+      changeDriver(),
       ...(hosts ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
     ops,
   );
-  const fakes = makersOf(config.connectors, "fake");
   if (dataStore) fakes.set(DATA_VENDOR, () => collectionsFake(declared));
   const names = new Map<string, WorkflowDefinition<any, any>>();
   for (const wf of config.workflows) {
@@ -259,6 +307,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       throw new Error(`A workflow is named "${wf.name}", the name of a built-in workflow; name it otherwise`);
     }
     checkUses(wf, ops, drivers, types);
+    checkSchedule(wf);
     const other = names.get(wf.name);
     if (other && other !== wf) {
       throw new Error(
@@ -293,7 +342,9 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     drivers,
     driversByVendor,
     fakes,
+    ...(instanceFakes && { instanceFakes }),
     logins: makersOf(config.connectors, "login"),
+    models: makersOf(config.connectors, "model"),
     ...(scenarios && { scenarios }),
     types,
     steps: [...new Set([...config.connectors.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
@@ -360,6 +411,25 @@ function makersOf<K extends keyof ConnectorSetup>(
   return makers;
 }
 
+/**
+ * Each vendor's one fake, made now, for `resolveConfig`'s `fakes: "instance"`; `fakes` (the
+ * makers) then give these. Refuses a connector that attaches a driver and no fake.
+ */
+function instanceFakesOf(
+  connectors: readonly Connector<any, any>[],
+  fakes: Map<string, () => Fake<any, any>>,
+): Map<string, Fake<any, any>> {
+  const live = [...makersOf(connectors, "driver").keys()].filter((vendor) => !fakes.has(vendor));
+  if (live.length) {
+    throw new Error(
+      `The instance runs on fakes, but the connector of ${live.join(", ")} attaches no fake, so it would run live; attach one (\`withSetup\`) or leave it out`,
+    );
+  }
+  const made = new Map([...fakes].map(([vendor, make]) => [vendor, make()]));
+  for (const [vendor, fake] of made) fakes.set(vendor, () => fake);
+  return made;
+}
+
 /**
  * The `name` of `<root>/package.json`, kept whole (`@acme/ops`), when that file exists and names
  * one; else "sanoma", as for a config with no `root`. Never a `package.json` above the root: a
@@ -385,6 +455,33 @@ function scenariosAt(root: string | undefined): URL | undefined {
   return pathToFileURL(`${dir}/`);
 }
 
+/**
+ * The one wakeup the config's data files declare, or undefined: with none, and with one the reader
+ * leaves out for a problem (its declaration's or its host's; several wakeups are each one).
+ * Undefined means the instance has no wakeup, so it must not stop. Server-side: it reads the data
+ * files and the lockfile, only when a connector declares a wakeup type.
+ */
+export async function declaredWakeup(config: SanomaConfig): Promise<DeclaredWakeup | undefined> {
+  const connectors = connectorsOf(config);
+  const types = resourceTypesOf(connectors);
+  if (![...types.values()].some((type) => type.wakeup)) return undefined;
+  // Loaded when it is needed, not with the worker: the reader parses with oxc-parser.
+  const { readDataFiles } = await import("./resources.ts");
+  const { resources } = readDataFiles(rootOf(config), connectors, types);
+  const typeOf = (r: DeclaredResource) => types.get(`${r.vendor}.${r.type}`)!;
+  const declared = resources.find((r) => typeOf(r).wakeup);
+  if (!declared) return undefined;
+  const type = typeOf(declared);
+  const host = resources.find((r) => r.id === declared.refs[type.wakeup!.inputs.host]);
+  return {
+    id: declared.id,
+    type,
+    declared,
+    ...(declared.binding !== undefined && { binding: declared.binding }),
+    ...(host && { host: { id: host.id, type: typeOf(host) } }),
+  };
+}
+
 /**
  * The data files under `root` and the lockfile beside them, in one read, as a drift or apply run
  * records them: each resource with its binding, without its write-only values (a secret marker
@@ -478,7 +575,8 @@ function guarded(vendor: string, env: DriverEnv, fn: DriverFn): DriverFn {
  * Every operation a workflow uses must be one the config's connectors declare, with a driver.
  * The workflow normally imports the same connector object; a copy is accepted only if it
  * declares the same effect and retry setting, and the worker's declaration is used either way.
- * None may change a declared resource (`isChangeOp`): only the built-in apply workflow does.
+ * None may use an operation a built-in workflow alone calls (`reservedFor`): a declared resource's
+ * change, which only apply makes, or a change's step, which only the change workflow takes.
  */
 function checkUses(
   wf: WorkflowDefinition<any, any>,
@@ -489,11 +587,10 @@ function checkUses(
   const problems: string[] = [];
   for (const op of (wf.uses as readonly Use[]).filter(isOp)) {
     const known = ops.get(op.id);
+    const reserved = known && reservedFor(known, types);
     if (!known) problems.push(`${op.id} is not declared by any connector in \`connectors\``);
-    else if (isChangeOp(known, types)) {
-      problems.push(
-        `${op.id} changes a declared resource, which only ${APPLY_WORKFLOW} does: change the data file instead`,
-      );
+    else if (reserved) {
+      problems.push(`${op.id} ${reserved.does}, which only ${reserved.workflow} does: ${reserved.instead} instead`);
     } else if (known !== op && (known.effect !== op.effect || known.idempotent !== op.idempotent)) {
       problems.push(
         `${op.id} is declared with effect "${op.effect}"${op.idempotent ? " (idempotent)" : ""}, ` +

package/src/database.ts

@@ -0,0 +1,152 @@
+import type { z } from "zod";
+import { hasPath } from "./host.ts";
+import { DriverError, type Op } from "./op.ts";
+import type { AfterCreate, Resource } from "./resource.ts";
+import type { Secrets } from "./secret.ts";
+import { RESOURCE_OPS } from "./wakeup.ts";
+
+// The `Database` contract: what a resource type that holds the company's database (a Neon
+// project, a Supabase project) declares about itself, beside `Host` and `Wakeup`, so databases
+// are swappable and one conformance kit decides whether one works. Going live chooses one by it.
+
+/** What a database can do, for choosing one: declared, never checked at runtime. */
+export interface DatabaseCapabilities {
+  /** Its compute scales to zero and wakes on the next connection (Neon's). */
+  pauses: boolean;
+  /** It makes copy-on-write branches that carry the data, each with its own URL. */
+  branch: boolean;
+}
+
+/** What a database's state says of it. */
+export interface DatabaseOutputs {
+  healthy: boolean;
+}
+
+/**
+ * A resource type's `database`: the fields it takes going live's choices in, by dotted path into
+ * its declared fields, the operation that stores its URL, and how its state reads.
+ */
+export interface DatabaseSpec {
+  capabilities: DatabaseCapabilities;
+  inputs: {
+    /** Where it runs, one of `regions` when the type lists them. */
+    region: string;
+    /** Its compute's size, when the vendor takes one: absent for its default. */
+    size?: string;
+  };
+  /**
+   * The id of the operation that stores the database's URL, `<vendor>.<group>.<op>`, an
+   * operation of the type's own vendor: in the type's own group beside `read` and `import`
+   * (`neon.project.storeUrl`), or in a group of its own (`supabase.database.storeUrl`, which
+   * predates the contract), never a resource type's own operation. It takes the new object's
+   * binding id as `ref` or `id` and the data file's export as `export`, and stores the URL that
+   * carries `LISTEN` (the direct one, or a session pooler's; never a transaction-mode pooler's)
+   * as the secret `SANOMA_DATABASE_URL_<EXPORT>`, never returning it. The type's `afterCreate`
+   * calls it, so apply stores the URL once it makes the database.
+   */
+  storeUrl: string;
+  /** The regions `inputs.region` takes, for a choice; absent when the vendor's list is not known here. */
+  regions?: readonly string[];
+  outputs: (state: Record<string, unknown>) => DatabaseOutputs;
+}
+
+/**
+ * The secret a database's `storeUrl` stores its URL in, for the data file's export that declares
+ * it: `store` → `SANOMA_DATABASE_URL_STORE`, `mainStore` → `SANOMA_DATABASE_URL_MAIN_STORE`.
+ */
+export const databaseUrlSecret = (exportName: string): string =>
+  `SANOMA_DATABASE_URL_${exportName.replaceAll(/([a-z0-9])([A-Z])/g, "$1_$2").toUpperCase()}`;
+
+/**
+ * A `storeUrl`'s store: `url` as `databaseUrlSecret(exportName)`, whose name it returns. The store
+ * only adds: a secret that holds another URL (another database, or a password since changed) is
+ * refused, not kept, with a `DriverError` (`stale`) that begins `where` and names what else it
+ * could be (`others`).
+ */
+export async function storeDatabaseUrl(
+  secrets: Secrets,
+  exportName: string,
+  url: string,
+  { where, others }: { where: string; others: string },
+): Promise<{ secret: string }> {
+  const secret = databaseUrlSecret(exportName);
+  if ((await secrets.ensure(secret, () => url)) !== url) {
+    throw new DriverError(`${where}: ${secret} holds another URL (${others}); delete it to store this one`, {
+      retryable: false,
+      vendorCode: "stale",
+    });
+  }
+  return { secret };
+}
+
+/**
+ * Throws what is wrong with a resource type's `database`: a type apply cannot change (not
+ * `writable`), one apply may recreate without asking (`stateless`: a database holds data), an
+ * input that names no field, a capability that is not a boolean, a `storeUrl` that is not an
+ * operation of its vendor or is one of the type's resource operations, or that `afterCreate`
+ * does not call, `regions` that is not a list of strings, `outputs` that is not a function.
+ * Whether the connector has that operation, and it takes `{ ref | id, export }`, is
+ * `checkDatabaseOps`'s, which `resolveConfig` runs.
+ */
+export function checkDatabase(
+  what: string,
+  database: DatabaseSpec,
+  type: {
+    vendor: string;
+    type: string;
+    schema: z.ZodObject;
+    writable?: boolean;
+    stateless?: boolean;
+    afterCreate?: readonly AfterCreate[];
+  },
+): void {
+  const problems: string[] = [];
+  if (!type.writable) problems.push("it must be writable, so apply can create and update it");
+  if (type.stateless) problems.push("it must not be stateless: it holds data, so apply asks before it deletes one");
+  const capabilities: Partial<DatabaseCapabilities> = database.capabilities ?? {};
+  for (const name of ["pauses", "branch"] as const) {
+    if (typeof capabilities[name] !== "boolean") problems.push(`capabilities.${name} must be true or false`);
+  }
+  const { region, size } = database.inputs ?? {};
+  if (typeof region !== "string" || !hasPath(type.schema, region)) problems.push(`region names no field (${region})`);
+  if (size !== undefined && !hasPath(type.schema, size)) problems.push(`size names no field (${size})`);
+  const storeUrl: unknown = database.storeUrl;
+  const [vendor, group, name, ...more] = typeof storeUrl === "string" ? storeUrl.split(".") : [];
+  if (vendor !== type.vendor || !/^\w+$/.test(group ?? "") || !/^\w+$/.test(name ?? "") || more.length) {
+    problems.push(`storeUrl must name an operation of its vendor, ${type.vendor}.<group>.<op> (${String(storeUrl)})`);
+  } else if (group === type.type && RESOURCE_OPS.has(name!)) {
+    problems.push(`storeUrl must be an operation of its own, not the type's ${name}`);
+  } else if (!type.afterCreate?.some((step) => step.op === storeUrl)) {
+    problems.push(`afterCreate must call ${storeUrl}, so apply stores the URL once it makes one`);
+  }
+  if (
+    database.regions !== undefined &&
+    (!Array.isArray(database.regions) || database.regions.some((r) => typeof r !== "string" || !r))
+  ) {
+    problems.push("regions must be a list of region names");
+  }
+  if (typeof database.outputs !== "function") problems.push("outputs must be a function of the state");
+  if (problems.length) throw new Error(`${what}: its database: ${problems.join("; ")}`);
+}
+
+/**
+ * Throws when a database type's `storeUrl` is not among the config's operations, is one of a
+ * resource type's own, or does not take `{ ref | id, export }`. Here rather than in
+ * `defineResource`, which sees one type before its package merges in the operations it adds
+ * (Supabase's pattern), as `checkWakeupOps`.
+ */
+export function checkDatabaseOps(types: ReadonlyMap<string, Resource>, ops: ReadonlyMap<string, Op>): void {
+  for (const [id, type] of types) {
+    if (!type.database) continue;
+    const op = ops.get(type.database.storeUrl);
+    if (!op)
+      throw new Error(`${id}: its database's storeUrl, ${type.database.storeUrl}, is no operation of its connector`);
+    if (types.has(`${op.vendor}.${op.resource}`) && RESOURCE_OPS.has(op.name)) {
+      throw new Error(`${id}: its database's storeUrl, ${op.id}, is a resource type's own operation`);
+    }
+    // By its fields, not a sample's parse: an id or export with a format of its own is still one.
+    const has = (field: string) => hasPath(op.input, field);
+    if (!(has("export") && (has("ref") || has("id"))))
+      throw new Error(`${id}: its database's storeUrl, ${op.id}, must take { ref or id, export }`);
+  }
+}

package/src/db.ts

@@ -5,9 +5,9 @@ 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, 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.
+// ledger, the collections' records, the wakeup's row and the operator agent's chats. 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">;
@@ -18,6 +18,17 @@ export const CREDENTIALS_TABLE = "sanoma_credentials";
 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 instance's side of its wakeup: one row, made with the table. `owner` is the worker that
+ * registers, `generation` counts registrations up, `at` is the deadline registered, `stopped_at`
+ * when the worker last stopped, `registered_at` when the wakeup last took one, `last_error` why
+ * the last registration failed.
+ */
+export const WAKEUP_TABLE = "sanoma_wakeup";
+/** The operator agent's chats (`chats.ts`): who each is for, its engine and its draft. */
+export const CHATS_TABLE = "sanoma_chats";
+/** Each chat's messages, the AI SDK's UI messages as JSON, in `seq` order. */
+export const CHAT_MESSAGES_TABLE = "sanoma_chat_messages";
 
 /** The runtime's tables, each with the word the messages name it by. */
 const TABLES: readonly [what: string, ddl: string][] = [
@@ -39,6 +50,23 @@ const TABLES: readonly [what: string, ddl: string][] = [
     `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))",
   ],
+  [
+    "wakeup",
+    `CREATE TABLE IF NOT EXISTS ${WAKEUP_TABLE} (id integer PRIMARY KEY CHECK (id = 1), owner uuid, ` +
+      "generation bigint NOT NULL DEFAULT 0, at timestamptz, stopped_at timestamptz, registered_at timestamptz, " +
+      `last_error text); INSERT INTO ${WAKEUP_TABLE} (id) VALUES (1) ON CONFLICT (id) DO NOTHING`,
+  ],
+  [
+    "chats",
+    `CREATE TABLE IF NOT EXISTS ${CHATS_TABLE} (id text PRIMARY KEY, person text NOT NULL, engine text NOT NULL, ` +
+      "draft_id text, title text NOT NULL, created_at timestamptz NOT NULL DEFAULT now()); " +
+      `CREATE INDEX IF NOT EXISTS ${CHATS_TABLE}_person ON ${CHATS_TABLE} (person, created_at)`,
+  ],
+  [
+    "chat messages",
+    `CREATE TABLE IF NOT EXISTS ${CHAT_MESSAGES_TABLE} (chat_id text NOT NULL REFERENCES ${CHATS_TABLE} (id) ` +
+      "ON DELETE CASCADE, id text NOT NULL, seq integer NOT NULL, message jsonb NOT NULL, PRIMARY KEY (chat_id, id))",
+  ],
 ];
 
 /** The Postgres error code of `err`, or an empty string when it has none. */
@@ -142,7 +170,7 @@ 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, ledger and data tables, and its idle-transaction timeout (`guardIdleTransactions`).
+ * credentials, ledger, data, wakeup and chat 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.
  */
@@ -188,11 +216,7 @@ async function prepare(databaseUrl: string): Promise<void> {
  * 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);
-  });
+  const conn = await connectMaking(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);
@@ -203,6 +227,15 @@ async function lockPreparation(databaseUrl: string): Promise<Client> {
   }
 }
 
+/** A connection to the database at `databaseUrl`, made first when it is not there (`createDatabase`). */
+export async function connectMaking(databaseUrl: string): Promise<Client> {
+  return connect(databaseUrl).catch(async (err: unknown) => {
+    if (pgCode(err) !== NO_DATABASE) throw err;
+    await createDatabase(databaseUrl);
+    return connect(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.
@@ -263,3 +296,69 @@ export async function createTable(db: Db, ddl: string, what: string): Promise<vo
     throw new Error(`could not prepare the ${what} table: ${errorMessage(err)}`, { cause: err });
   }
 }
+
+// The wakeup row's reads and writes. Every write after the claim names the owner: a worker
+// another process has replaced since (a second instance on the database) changes nothing.
+
+// `at` is the deadline registered for the row's generation, null until one is: a new generation
+// (each start and each stop attempt) clears it, so a wake registered earlier is stale.
+
+/** Makes `owner` the worker that registers the instance's wakeups; a running worker needs no wake registered before. */
+export async function claimWakeup(db: Db, owner: string): Promise<void> {
+  await db.query(`UPDATE ${WAKEUP_TABLE} SET owner = $1, generation = generation + 1, at = NULL WHERE id = 1`, [owner]);
+}
+
+/** Counts the row's generation up while `owner` still owns it: the new generation, or undefined when another worker owns the row now. */
+export async function nextWakeupGeneration(db: Db, owner: string): Promise<number | undefined> {
+  const { rows } = await db.query<{ generation: string }>(
+    `UPDATE ${WAKEUP_TABLE} SET generation = generation + 1, at = NULL WHERE id = 1 AND owner = $1 RETURNING generation`,
+    [owner],
+  );
+  return rows[0] && Number(rows[0].generation);
+}
+
+/** Records that the wakeup took `at` for `generation`. */
+export async function recordWakeupRegistration(db: Db, owner: string, generation: number, at: string): Promise<void> {
+  await db.query(
+    `UPDATE ${WAKEUP_TABLE} SET at = $3, registered_at = now(), last_error = NULL WHERE id = 1 AND owner = $1 AND generation = $2`,
+    [owner, generation, at],
+  );
+}
+
+/** Records why registering `generation` failed. */
+export async function recordWakeupError(db: Db, owner: string, generation: number, error: string): Promise<void> {
+  await db.query(`UPDATE ${WAKEUP_TABLE} SET last_error = $3 WHERE id = 1 AND owner = $1 AND generation = $2`, [
+    owner,
+    generation,
+    error,
+  ]);
+}
+
+/** Records that the worker stops now, with `generation` registered. */
+export async function recordWakeupStop(db: Db, owner: string, generation: number): Promise<void> {
+  await db.query(`UPDATE ${WAKEUP_TABLE} SET stopped_at = now() WHERE id = 1 AND owner = $1 AND generation = $2`, [
+    owner,
+    generation,
+  ]);
+}
+
+/**
+ * True when `generation` is the wakeup row's and the worker stopped with it: the wake
+ * `/wake?generation=N` asks for is the one the worker last registered before it stopped, not
+ * one a later stop replaced, nor one registered by a worker that then kept running. For the
+ * route's supervisor, which decides on its own what a wake means when no wakeup is declared.
+ */
+export async function shouldWake(databaseUrl: string, generation: number): Promise<boolean> {
+  await prepareDatabase(databaseUrl);
+  const conn = await connect(databaseUrl);
+  try {
+    const { rows } = await conn.query<{ current: boolean }>(
+      `SELECT generation = $1 AND at IS NOT NULL AND stopped_at >= registered_at ` +
+        `AS current FROM ${WAKEUP_TABLE} WHERE id = 1`,
+      [generation],
+    );
+    return rows[0]?.current === true;
+  } finally {
+    await conn.end().catch(() => undefined);
+  }
+}