@sanoma-ai/workflows 0.7.0 → 0.8.0

package/src/config.ts

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DBOS } from "@dbos-inc/dbos-sdk";
@@ -6,6 +6,8 @@ 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 { changeSteps } from "./change-steps.ts";
+import { changeWorkflow } from "./change-workflow.ts";
 import {
   type Collection,
   collectionsConnector,
@@ -14,10 +16,11 @@ import {
   isCollection,
 } from "./collection.ts";
 import { lazyPool, type LazyPool } from "./db.ts";
+import { isDirectory, kindDirs, SCENARIOS_DIR } from "./paths.ts";
 import { callerFile, type Use, type WorkflowDefinition } from "./define.ts";
 import { DRIFT_WORKFLOW, driftWorkflow } from "./drift.ts";
 import { statusesOf, unconfigured } from "./env.ts";
-import type { Fake } from "./fake.ts";
+import { type Fake, fakeSanomaWakeup } from "./fake.ts";
 import { peopleConnector } from "./person.ts";
 import type { LedgerStore } from "./ledger.ts";
 import {
@@ -32,17 +35,21 @@ import {
   checkConnector,
   setupOf,
   VENDOR,
+  withSetup,
 } from "./op.ts";
 import { type CedarPolicySource, policyAt } from "./cedar.ts";
 import type { Policy } from "./policy.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 { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS, CALL_WORKFLOW, CHANGE_WORKFLOW, DATA_VENDOR } from "./shared.ts";
+import { type RemoteHalf, sourceDriver, sourceOps } from "./source.ts";
+import { appsListDriver, appsListOps } from "./apps-list.ts";
 import type { Steps } from "./steps.ts";
 import { checkSchedule } from "./schedules.ts";
-import { computeVersion } from "./version.ts";
+import { changeCodeOf, computeVersion } from "./version.ts";
 import type { DeclaredResource } from "./resources.ts";
 import { checkWakeupOps, type DeclaredWakeup } from "./wakeup.ts";
+import { sanomaWakeupDriver, wakeupSteps } from "./wakeup-driver.ts";
+import { wakeupOps } from "./wakeup-type.ts";
 import { checkDatabaseOps } from "./database.ts";
 
 /**
@@ -53,7 +60,11 @@ import { checkDatabaseOps } from "./database.ts";
  * policies are `scenarios/`, `resources/` and `policies/` in `root`.
  */
 export interface SanomaConfig {
-  workflows: WorkflowDefinition<any, any>[];
+  /**
+   * Workflows besides those the launcher finds (`sanoma` imports every file of `workflows/` and
+   * each app's `apps/<app>/workflows/`): listing one it finds as well is no second one.
+   */
+  workflows?: WorkflowDefinition<any, any>[];
   /**
    * The connectors (from `defineConnector`, as their packages export them). The worker takes
    * each operation's effect, schemas and retry setting from here, not from the workflow, and
@@ -103,6 +114,12 @@ export interface SanomaConfig {
    * that sets it and declares a wakeup of its own.
    */
   wakeup?: true;
+  /**
+   * What the app says when it runs this repo as a demo (`sanoma demo`): `start`, the URL its
+   * banner's "Start with these apps" opens, such as the hosted wizard with the demo's apps
+   * chosen; without one, the banner has no such link.
+   */
+  demo?: { start?: string };
 }
 
 /** A config, checked, with everything a worker, client or app derives from it. */
@@ -115,12 +132,14 @@ export interface ResolvedConfig {
   databaseUrl: string;
   /** The DBOS application version: `<appName>@<DBOS__APPVERSION, or a hash of the workflows>`. */
   version: string;
+  /** The hash of the built-in change workflow's own code (`changeCodeOf`), which each change run carries. */
+  changeCode: string;
   /** The DBOS queue runs are started on: `sanoma:<appName>`. */
   queueName: string;
   /**
    * 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>`).
+   * every config), `sanoma.source.resolve` and `sanoma.wakeup`'s 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`). */
@@ -146,9 +165,20 @@ export interface ResolvedConfig {
   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. */
+  /** The remote halves the connectors attach, made once for this resolution, by vendor id in `connectors` order: `remoteFor` finds a URL's. */
+  remotes: ReadonlyMap<string, RemoteHalf>;
+  /**
+   * The resources the data files under `root` declare whose type is a host (`<file>#<export>`),
+   * read at each call: what a change's deploy and a push to `main` apply. None when no connector
+   * declares a host type.
+   */
+  hosts(): Promise<string[]>;
+  /**
+   * `root`, as a `file:` URL, when `scenarios/` or an app's `apps/<app>/scenarios/` in it is a
+   * directory: the feature files under those, each named by its path from the root.
+   */
   scenarios?: URL;
-  /** The resource types the connectors declare, by `<vendor>.<type>`: what the drift workflow checks and scenarios seed. */
+  /** The resource types the connectors declare (and `sanoma.wakeup`, beside a host type), by `<vendor>.<type>`: what the drift workflow checks and scenarios seed. */
   types: ReadonlyMap<string, Resource>;
   /** The steps scenarios can use besides the generic ones: each connector's (`withSetup`), once each, then the config's own. */
   steps: readonly Steps[];
@@ -253,8 +283,8 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
     throw new Error("The config needs `connectors`: the connectors its workflows call, as their packages export them");
   }
   for (const connector of config.connectors as unknown[]) checkConnector(connector);
-  if (!Array.isArray(config.workflows)) {
-    throw new Error("The config needs `workflows`: an array of defineWorkflow definitions");
+  if (config.workflows !== undefined && !Array.isArray(config.workflows)) {
+    throw new Error("The config's `workflows`, when given, is an array of defineWorkflow definitions");
   }
   // An untyped config naming fake drivers would otherwise run live. Delete once sanoma-ops has migrated.
   if (config.drivers !== undefined || config.fakes !== undefined)
@@ -270,39 +300,45 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
   const root = rootOf(config);
   const appName = appNameAt(root);
   const scenarios = scenariosAt(root);
-  const types = resourceTypesOf(config.connectors);
+  // With the built-in `sanoma.wakeup` when they declare a host type.
+  const running = withBuiltIns(config.connectors);
+  const types = resourceTypesOf(running);
   // Built-in: `sanoma.source.resolve`, which apply and drift call for a host's revision.
-  const hosts = [...types.values()].some((type) => type.host);
+  const hostTyped = [...types.values()].some((type) => type.host);
   // Built-in: the collections' operations, `data.<name>.<op>`, on the config's database.
   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`).
+  // Built-in, in every config: a change's operations, which the template's policy names
+  // (`sanoma.change.merge`), and the listing of apps a page may call (`sanoma.apps.list`).
   const ops = indexConnectors([
-    ...config.connectors,
+    ...running,
     changeOps,
-    ...(hosts ? [sourceOps] : []),
+    appsListOps,
+    ...(hostTyped ? [sourceOps] : []),
     ...(dataStore ? [collectionsConnector(declared)] : []),
   ]);
   checkWakeupOps(types, ops);
   checkDatabaseOps(types, ops);
-  const fakes = makersOf(config.connectors, "fake");
-  const instanceFakes = options.fakes === "instance" ? instanceFakesOf(config.connectors, fakes) : undefined;
+  const fakes = makersOf(running, "fake");
+  const instanceFakes = options.fakes === "instance" ? instanceFakesOf(running, 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()]));
+    : new Map([...makersOf(running, "driver")].map(([vendor, make]) => [vendor, make()]));
+  const remotes = new Map([...makersOf(config.connectors, "remote")].map(([vendor, make]) => [vendor, make()]));
   const drivers = indexDrivers(
     [
       ...driversByVendor.values(),
-      changeDriver(),
-      ...(hosts ? [sourceDriver] : []),
+      changeDriver(remotes),
+      appsListDriver,
+      ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
     ops,
   );
   if (dataStore) fakes.set(DATA_VENDOR, () => collectionsFake(declared));
   const names = new Map<string, WorkflowDefinition<any, any>>();
-  for (const wf of config.workflows) {
+  for (const wf of config.workflows ?? []) {
     if (BUILT_IN_WORKFLOWS.has(wf.name)) {
       throw new Error(`A workflow is named "${wf.name}", the name of a built-in workflow; name it otherwise`);
     }
@@ -317,17 +353,21 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
     names.set(wf.name, wf);
   }
   // Built-in: checking the resources the data files declare against their vendors, and applying them.
+  const connectors = connectorsOf(config);
+  // The types the data files may declare: the vendors' and the people's, whose resources are left out.
+  const declarable = resourceTypesOf(connectors);
+  const read = () => readDeclared(root, connectors, declarable, types);
   if (types.size) {
-    const connectors = connectorsOf(config);
-    // The types the data files may declare: the vendors' and the people's, whose resources are left out.
-    const declarable = resourceTypesOf(connectors);
-    const read = () => readDeclared(root, connectors, declarable, types);
     names.set(
       DRIFT_WORKFLOW,
       driftWorkflow(types, ops, drivers, () => DBOS.runStep(read, { name: "drift:data-files" })),
     );
     names.set(APPLY_WORKFLOW, applyWorkflow(types, ops, drivers, applySteps(appName, root, read)));
   }
+  // Built-in, in every config: the life of a change, which deploys to the declared hosts after its merge.
+  const hosts = async () =>
+    (await read()).resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.host).map((r) => r.id);
+  names.set(CHANGE_WORKFLOW, changeWorkflow(changeOps, changeSteps({ remotes, hosts })));
   // Built-in: a direct call the policy holds for an approval, made a run, when any operation may be called directly.
   const call = callWorkflow(ops, drivers, types);
   if (call.uses.length) names.set(CALL_WORKFLOW, call);
@@ -337,6 +377,7 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
     databaseUrl,
     // The built-in's code and operations are part of the app's version, like the config's own.
     version: computeVersion({ appName, workflows: [...names.values()] }),
+    changeCode: changeCodeOf(names.get(CHANGE_WORKFLOW)!),
     queueName: `sanoma:${appName}`,
     ops,
     drivers,
@@ -345,9 +386,11 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
     ...(instanceFakes && { instanceFakes }),
     logins: makersOf(config.connectors, "login"),
     models: makersOf(config.connectors, "model"),
+    remotes,
+    hosts,
     ...(scenarios && { scenarios }),
     types,
-    steps: [...new Set([...config.connectors.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
+    steps: [...new Set([...running.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
     collections,
     ...(dataStore && { dataStore }),
     workflows: names,
@@ -383,9 +426,32 @@ function collectionsOf(config: SanomaConfig): Map<string, Collection> {
   return collections;
 }
 
-/** The config's connectors and the runtime's people types' (`peopleConnector`): what its data files are read against. */
+/**
+ * `sanoma.wakeup`, the runtime's own: the type's operations and `sanoma.wakeup.register` (effect
+ * `write`), which the worker registers each deadline through before it stops, with its live
+ * driver (`sanomaWakeupDriver`), its fake (`fakeSanomaWakeup`) and its step. `withBuiltIns`
+ * merges it into every config with a host type.
+ */
+export const sanomaWakeup = withSetup(wakeupOps, {
+  driver: sanomaWakeupDriver,
+  fake: fakeSanomaWakeup,
+  steps: wakeupSteps,
+});
+
+/**
+ * The connectors and, when they declare a host type, the runtime's own wakeup (`sanoma.wakeup`),
+ * the fallback for a host with no clock of its own: what a config runs on. The same array when
+ * they declare none.
+ */
+const withBuiltIns = (connectors: Connector<any, any>[]): Connector<any, any>[] =>
+  [...resourceTypesOf(connectors).values()].some((type) => type.host) ? [...connectors, sanomaWakeup] : connectors;
+
+/**
+ * The config's connectors (with `sanoma.wakeup` when they declare a host type) and the runtime's
+ * people types' (`peopleConnector`): what its data files are read against.
+ */
 export const connectorsOf = (config: Pick<SanomaConfig, "connectors">): Connector<any, any>[] => [
-  ...config.connectors,
+  ...withBuiltIns(config.connectors),
   peopleConnector,
 ];
 
@@ -448,18 +514,21 @@ function appNameAt(root: string | undefined): string {
   return typeof named === "string" && named.trim() ? named.trim() : "sanoma";
 }
 
-/** `<root>/scenarios/`, as a `file:` URL to the directory (with its trailing slash), when it is a directory. */
+/**
+ * The root, as a `file:` URL to the directory (with its trailing slash), when `<root>/scenarios/`
+ * or an app's `apps/<app>/scenarios/` is a directory: the scenarios are the feature files there,
+ * each named by its path from the root (`scenarioFiles`).
+ */
 function scenariosAt(root: string | undefined): URL | undefined {
-  const dir = root === undefined ? undefined : join(root, "scenarios");
-  if (dir === undefined || !statSync(dir, { throwIfNoEntry: false })?.isDirectory()) return undefined;
-  return pathToFileURL(`${dir}/`);
+  if (root === undefined || !kindDirs(root, SCENARIOS_DIR).some(isDirectory)) return undefined;
+  return pathToFileURL(`${root}/`);
 }
 
 /**
  * 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.
+ * files and the lockfile, only when the config has a wakeup type (`sanoma.wakeup` beside any host type).
  */
 export async function declaredWakeup(config: SanomaConfig): Promise<DeclaredWakeup | undefined> {
   const connectors = connectorsOf(config);

package/src/constructors.ts

@@ -1,4 +1,10 @@
+import { sanoma as people } from "./person.ts";
+import { wakeup } from "./wakeup-type.ts";
+
 // `@sanoma-ai/workflows/resources`: what a data file imports from the runtime: `secret`, which
-// names a stored secret, and `sanoma`, the constructors of its people types (`sanoma.person`, …).
+// names a stored secret, and `sanoma`, the constructors of its people types (`sanoma.person`, …)
+// and of its wakeup, `sanoma.wakeup({ host })`.
 export { secret, type Secret } from "./secret.ts";
-export { sanoma } from "./person.ts";
+
+/** The runtime's own constructors: the people types' and the wakeup's. */
+export const sanoma = { ...people, wakeup };

package/src/db.ts

@@ -19,10 +19,9 @@ 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.
+ * The instance's side of its wakeup: one row, made with the table. `at` is the deadline last
+ * registered, `stopped_at` when the worker last stopped itself (the schedules backfill from it),
+ * `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. */
@@ -52,9 +51,8 @@ const TABLES: readonly [what: string, ddl: string][] = [
   ],
   [
     "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`,
+    `CREATE TABLE IF NOT EXISTS ${WAKEUP_TABLE} (id integer PRIMARY KEY CHECK (id = 1), at timestamptz, ` +
+      `stopped_at timestamptz, last_error text); INSERT INTO ${WAKEUP_TABLE} (id) VALUES (1) ON CONFLICT (id) DO NOTHING`,
   ],
   [
     "chats",
@@ -103,6 +101,29 @@ export function openPool(databaseUrl: string, what: string): Pool {
  */
 export const DBOS_DATABASE_OPTIONS = { systemDatabaseIdleTransactionTimeoutMs: 0 } as const;
 
+/**
+ * Stamps the change runs `ids` still unfinished on another version with the application version
+ * `version`, so DBOS gives them to a worker of that version: those it stamped, each with its status
+ * (a PENDING one is the caller's to queue again). DBOS has no call for it (a run's version is set at
+ * its start, `forkWorkflow` makes a new id, `rewindWorkflow` takes only an ended run), so this is the
+ * runtime's one write to DBOS's own tables, in its schema `dbos` (dbos-sdk 5.2.11). One statement:
+ * of two workers stamping a run, one does.
+ */
+export async function stampVersion(
+  db: Db,
+  ids: readonly string[],
+  version: string,
+): Promise<{ id: string; pending: boolean }[]> {
+  const { rows } = await db.query<{ workflow_uuid: string; status: string }>(
+    `UPDATE dbos.workflow_status SET application_version = $1
+     WHERE workflow_uuid = ANY($2) AND name = 'change' AND status IN ('PENDING', 'ENQUEUED')
+       AND application_version <> $1
+     RETURNING workflow_uuid, status`,
+    [version, ids],
+  );
+  return rows.map((r) => ({ id: r.workflow_uuid, pending: r.status === "PENDING" }));
+}
+
 /**
  * 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`).
@@ -297,68 +318,20 @@ export async function createTable(db: Db, ddl: string, what: string): Promise<vo
   }
 }
 
-// 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],
-  );
-}
+// The wakeup row's writes: one worker registers per instance (the supervisor runs one at a time,
+// and a deploy stops the old container before the new one starts), so none names a worker.
 
-/** 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 wakeup took `at`. */
+export async function recordWakeupRegistration(db: Db, at: string): Promise<void> {
+  await db.query(`UPDATE ${WAKEUP_TABLE} SET at = $1, last_error = NULL WHERE id = 1`, [at]);
 }
 
-/** 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,
-  ]);
+/** Records why the last registration failed. */
+export async function recordWakeupError(db: Db, error: string): Promise<void> {
+  await db.query(`UPDATE ${WAKEUP_TABLE} SET last_error = $1 WHERE id = 1`, [error]);
 }
 
-/**
- * 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);
-  }
+/** Records that the worker stops itself now. */
+export async function recordWakeupStop(db: Db): Promise<void> {
+  await db.query(`UPDATE ${WAKEUP_TABLE} SET stopped_at = now() WHERE id = 1`);
 }

package/src/deadlines.ts

@@ -1,7 +1,8 @@
+import { randomUUID } from "node:crypto";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { dbosStatusesOf } from "./client.ts";
 import type { Db } from "./db.ts";
-import { nextWakeupGeneration, recordWakeupError, recordWakeupRegistration, recordWakeupStop } from "./db.ts";
+import { recordWakeupError, recordWakeupRegistration, recordWakeupStop } from "./db.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { warn } from "./log.ts";
 import type { CallContext, DriverFn, Op } from "./op.ts";
@@ -13,8 +14,11 @@ import type { WakeupRegistration } from "./wakeup.ts";
 // blocked in a `ctx` wait, and until when. DBOS sees both as PENDING. A worker that registers a
 // wakeup stops itself once nothing can run before the next deadline (`stopWhenIdle`).
 
-/** What a run blocked in a `ctx` wait waits for: a sleep, until its deadline, or an approval's decision, which has none. */
-export type Wait = { kind: "sleep"; until: number } | { kind: "approval" };
+/**
+ * What a run blocked in a wait waits for: a sleep, until its deadline; or, with no deadline, an
+ * approval's decision, a message (a change run's `ChangeEvent`), or another run it started.
+ */
+export type Wait = { kind: "sleep"; until: number } | { kind: "approval" | "message" | "run" };
 
 /** A deadline besides the sleeping runs', such as a schedule's next fire; undefined for none. */
 export type DeadlineSource = () => Date | undefined;
@@ -124,18 +128,15 @@ export async function idle(deadlines: Deadlines, scope: IdleScope, horizonMs: nu
   return (await DBOS.getLatestApplicationVersion()).versionName !== scope.version;
 }
 
-/** What `onStopped` hears when the worker stopped itself: the deadline it registered (null for none) and its generation. */
+/** What `onStopped` hears when the worker stopped itself: the deadline it registered, null for none. */
 export interface SelfStop {
   at: string | null;
-  generation: number;
 }
 
 /** What the stop rule acts on: the wakeup row, the wakeup's register operation, and the worker. */
 export interface StopRule {
   /** The wakeup row's database. */
   db: () => Promise<Db>;
-  /** This worker's id on the row (`owner`), fresh for each worker. */
-  owner: string;
   /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
   wakeup: string;
   /** The wakeup type's register operation, and its driver (none when the connector attaches none). */
@@ -150,12 +151,12 @@ export interface StopRule {
 }
 
 /**
- * Checks every `everyMs` whether the worker is `idle`; when it is, counts the wakeup row's
- * generation up, registers the next deadline with the wakeup (none when there is no deadline at
- * all), and stops the worker, then tells `onStopped`. A failed registration is recorded on the
- * row and logged once for each new message, and the worker keeps running: the next check tries
- * again with a new generation. A run that arrives while it registers keeps the worker up, since
- * the worker must be idle twice, with the same deadline, before it stops. `close` ends the checks.
+ * Checks every `everyMs` whether the worker is `idle`; when it is, registers the next deadline
+ * with the wakeup, replacing what it held (none when there is no deadline at all), and stops the
+ * worker, then tells `onStopped`. A failed registration is recorded on the row and logged once for
+ * each new message, and the worker keeps running: the next check tries again. A run that arrives
+ * while it registers keeps the worker up, since the worker must be idle twice, with the same
+ * deadline, before it stops. `close` ends the checks.
  */
 export function stopWhenIdle(rule: StopRule): { close(): void } {
   let closed = false;
@@ -171,30 +172,23 @@ export function stopWhenIdle(rule: StopRule): { close(): void } {
     const next = rule.deadlines.nextDeadline();
     const at = next?.toISOString() ?? null;
     const db = await rule.db();
-    const generation = await nextWakeupGeneration(db, rule.owner);
-    if (generation === undefined) {
-      // A worker claims the row only when it starts, so this one never gets it back.
-      warn("another worker registers this instance's wakeups now, so this one keeps running and stops checking");
-      closed = true;
-      return false;
-    }
     if (at !== null) {
       try {
-        await registerWakeup(rule, { at, generation });
+        await registerWakeup(rule, { at });
       } catch (err) {
         const message = errorMessage(err);
-        await recordWakeupError(db, rule.owner, generation, message);
+        await recordWakeupError(db, message);
         problem(`could not register the wakeup at ${at}, so the worker keeps running: ${message}`);
         return false;
       }
-      await recordWakeupRegistration(db, rule.owner, generation, at);
+      await recordWakeupRegistration(db, at);
     }
     lastProblem = undefined;
     if (closed || !(await rule.idle()) || rule.deadlines.nextDeadline()?.toISOString() !== next?.toISOString())
       return false;
-    await recordWakeupStop(db, rule.owner, generation);
+    await recordWakeupStop(db);
     await rule.stop().catch((err: unknown) => warn(`the worker could not stop cleanly: ${errorMessage(err)}`));
-    rule.onStopped?.({ at, generation });
+    rule.onStopped?.({ at });
     return true;
   };
 
@@ -222,13 +216,16 @@ export function stopWhenIdle(rule: StopRule): { close(): void } {
 
 /**
  * Calls the wakeup's register operation, as `SanomaClient.call` calls a driver: its input parsed,
- * a `CallContext` of the runtime's, and no ledger record, which is a run's. The idempotency key
- * is the generation's, so a retried registration is one registration.
+ * a `CallContext` of the runtime's, and no ledger record, which is a run's.
  */
-async function registerWakeup({ register: { op, fn }, secrets, wakeup }: StopRule, registration: WakeupRegistration) {
+export async function registerWakeup(
+  { register: { op, fn }, secrets, wakeup }: Pick<StopRule, "register" | "secrets" | "wakeup">,
+  registration: WakeupRegistration,
+) {
   if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
-  // Every database counts generations from 0, so the key names the wakeup too.
-  const key = `wakeup:${wakeup}:${registration.generation}`;
+  // Fresh each time: a repeat of an earlier `at` after another registration must re-arm it, so no
+  // two registrations share a key (real drivers never dedupe on it anyway).
+  const key = `wakeup:${wakeup}:${randomUUID()}`;
   const context: CallContext = { idempotencyKey: key, runId: key, opId: op.id, attempt: 1, secrets, by: WAKEUP_AGENT };
   await fn(op.input.parse(registration), context);
 }

package/src/define.ts

@@ -2,6 +2,8 @@ import { fileURLToPath } from "node:url";
 import { getCallSites } from "node:util";
 import { z } from "zod";
 import { isOp, type Op } from "./op.ts";
+import { appOfFile } from "./paths.ts";
+import { type DATA_VENDOR, qualified } from "./shared.ts";
 
 /**
  * Who is acting: the person or agent that starts a run, calls an operation or decides an
@@ -171,19 +173,27 @@ export interface StepOptions {
 
 type OpsOf<U extends readonly Use[]> = Extract<U[number], Op>;
 
-type CtxOps<O extends Op> = {
-  readonly [V in O["vendor"]]: {
-    readonly [R in Extract<O, { vendor: V }>["resource"]]: {
-      readonly [N in Extract<O, { vendor: V; resource: R }>["name"]]: Extract<
-        O,
-        { vendor: V; resource: R; name: N }
-      > extends Op<any, any, any, infer I, infer Out>
-        ? (input: I, options?: StepOptions) => Promise<Out>
-        : never;
-    };
+type VendorCtx<O extends Op, V> = {
+  readonly [R in Extract<O, { vendor: V }>["resource"]]: {
+    readonly [N in Extract<O, { vendor: V; resource: R }>["name"]]: Extract<
+      O,
+      { vendor: V; resource: R; name: N }
+    > extends Op<any, any, any, infer I, infer Out>
+      ? (input: I, options?: StepOptions) => Promise<Out>
+      : never;
   };
 };
 
+/**
+ * `ctx.<vendor>.<resource>.<op>`. An app's collections are `ctx.data.<app>.<name>` at run time,
+ * a folder's name no type knows: that level is untyped (`any`), the root's collections typed.
+ */
+type CtxOps<O extends Op> = {
+  readonly [V in O["vendor"]]: V extends typeof DATA_VENDOR
+    ? VendorCtx<O, V> & { readonly [app: string]: any }
+    : VendorCtx<O, V>;
+};
+
 interface ApprovalCtx {
   /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection, `WithdrawnError` on a withdrawal. */
   approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
@@ -256,7 +266,10 @@ export type Trigger = "manual" | { readonly schedule: string; readonly timezone?
 
 export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S extends z.ZodType = z.ZodType> {
   readonly kind: "workflow";
+  /** Its name, as written at the root; in an app's folder, `<app>.<name>` (`app`). */
   readonly name: string;
+  /** The app whose folder defined it (`apps/<app>/`), from its `file`; absent for one at the root. */
+  readonly app?: string;
   readonly title?: string;
   readonly trigger: Trigger;
   readonly input: S;
@@ -273,8 +286,13 @@ export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S
 /** The ids of the operations a workflow `uses`, in the order declared. */
 export const opIdsOf = (wf: Pick<WorkflowDefinition, "uses">): string[] => wf.uses.filter(isOp).map((op) => op.id);
 
+/**
+ * Defines a workflow in its own file. Its `name` is a lowercase letter, then lowercase letters,
+ * digits and dashes; in an app's folder (`apps/<app>/`, `appOfFile`) the runtime names it
+ * `<app>.<name>`, so two apps may each have a `sync`.
+ */
 export function defineWorkflow<const U extends readonly Use[], S extends z.ZodType>(
-  def: Omit<WorkflowDefinition<U, S>, "kind" | "file">,
+  def: Omit<WorkflowDefinition<U, S>, "kind" | "file" | "app">,
 ): WorkflowDefinition<U, S> {
   if (!/^[a-z][a-z0-9-]*$/.test(def.name)) {
     throw new Error(`Workflow name "${def.name}" must be lowercase letters, digits and dashes`);
@@ -293,7 +311,8 @@ export function defineWorkflow<const U extends readonly Use[], S extends z.ZodTy
         "its outline is read from the file, and a run is held to the outline",
     );
   }
-  return Object.freeze({ kind: "workflow", ...def, file });
+  const app = appOfFile(file);
+  return Object.freeze({ kind: "workflow", ...def, name: qualified(app, def.name), ...(app && { app }), file });
 }
 
 /** True when `{}` parses: a schema zod can check only asynchronously is taken as accepting it, and the run parses it. */