@sanoma-ai/workflows 0.7.1 → 0.8.1

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,6 +16,7 @@ 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";
@@ -37,11 +40,12 @@ import {
 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 { 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";
@@ -56,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
@@ -106,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. */
@@ -118,6 +132,8 @@ 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;
   /**
@@ -151,7 +167,16 @@ export interface ResolvedConfig {
   models: ReadonlyMap<string, NonNullable<ConnectorSetup["model"]>>;
   /** 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>;
-  /** `scenarios/` in `root`, as a `file:` URL, when that directory exists. */
+  /**
+   * 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 (and `sanoma.wakeup`, beside a host type), by `<vendor>.<type>`: what the drift workflow checks and scenarios seed. */
   types: ReadonlyMap<string, Resource>;
@@ -258,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)
@@ -279,16 +304,18 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
   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([
     ...running,
     changeOps,
-    ...(hosts ? [sourceOps] : []),
+    appsListOps,
+    ...(hostTyped ? [sourceOps] : []),
     ...(dataStore ? [collectionsConnector(declared)] : []),
   ]);
   checkWakeupOps(types, ops);
@@ -298,18 +325,20 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
   const driversByVendor = instanceFakes
     ? new Map([...instanceFakes].map(([vendor, fake]) => [vendor, fake.driver]))
     : 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),
+      ...sandboxDrivers,
+      ...(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`);
     }
@@ -324,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);
@@ -344,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,
@@ -352,7 +386,8 @@ export function resolveConfig(config: SanomaConfig, options: ResolveOptions = {}
     ...(instanceFakes && { instanceFakes }),
     logins: makersOf(config.connectors, "login"),
     models: makersOf(config.connectors, "model"),
-    remotes: new Map([...makersOf(config.connectors, "remote")].map(([vendor, make]) => [vendor, make()])),
+    remotes,
+    hosts,
     ...(scenarios && { scenarios }),
     types,
     steps: [...new Set([...running.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
@@ -391,6 +426,12 @@ function collectionsOf(config: SanomaConfig): Map<string, Collection> {
   return collections;
 }
 
+/**
+ * The built-in drivers no fake implements that a sandbox run calls beside its fakes (`seedSandbox`):
+ * those that need no credentials and change nothing, as `sanoma.apps.list` (GitHub's public search).
+ */
+export const sandboxDrivers: readonly Driver[] = [appsListDriver];
+
 /**
  * `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
@@ -479,11 +520,14 @@ 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}/`);
 }
 
 /**

package/src/db.ts

@@ -101,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`).

package/src/deadlines.ts

@@ -14,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;

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. */

package/src/demo.ts

@@ -2,9 +2,9 @@ import type { SanomaClient } from "./client.ts";
 import type { ResolvedConfig } from "./config.ts";
 import { DATA_TABLE } from "./db.ts";
 import { applyGivens } from "./sandbox.ts";
-import { loadScenarios, type Moment } from "./scenario.ts";
+import { type Given, loadScenarios, type Moment } from "./scenario.ts";
 import { memorySecrets } from "./secret.ts";
-import { errorMessage } from "./shared.ts";
+import { DATA_VENDOR, errorMessage } from "./shared.ts";
 
 /*
  * A demo: a company repo run on its connectors' fakes, with the world its scenarios describe.
@@ -27,20 +27,43 @@ export interface DemoState {
 const states = new WeakMap<ResolvedConfig, DemoState>();
 
 /**
- * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * A half of a demo's seed (`reseed`'s `only`): what goes into its `database` (the runs cancelled,
+ * `sanoma_data` emptied, the worlds' collection records, the moments' runs), or into its `memory`
+ * (the instance's fakes reset, the worlds' vendor objects and calls). A copy of a seeded database
+ * holds the first half but not the second, which a process over it applies to its own fakes.
+ */
+export type SeedHalf = "database" | "memory";
+
+/** Which half a world's `Given` goes to: a collection's operation the database, anything else memory; a fault both, each refusing it. */
+const halfOf = (g: Given, resolved: ResolvedConfig): SeedHalf | undefined =>
+  "fault" in g ? undefined : "op" in g && resolved.ops.get(g.op)?.vendor === DATA_VENDOR ? "database" : "memory";
+
+/**
+ * Seeds the demo instance afresh: cancels the app's unfinished runs (`cancelUnfinished`: the last
+ * seed's moments among them), empties the collections' table, resets the instance's fakes,
  * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
  * saved through the collections' driver, its vendor objects put in the fakes), then starts each
  * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
- * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
- * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ * `only` seeds one half (`SeedHalf`). `resolved` is the resolution the worker and `client` run
+ * on, made with `fakes: "instance"`. A world or a moment that fails is a problem in the state it
+ * returns, and the rest go on.
  */
-export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Promise<DemoState> {
+export async function reseed(
+  client: SanomaClient,
+  resolved: ResolvedConfig,
+  { only }: { only?: SeedHalf } = {},
+): Promise<DemoState> {
   const fakes = resolved.instanceFakes;
   if (!fakes) throw new Error('reseed seeds an instance on fakes: resolve its config with `fakes: "instance"`');
+  const into = (half: SeedHalf) => only === undefined || only === half;
   // Read first, so scenarios that cannot be read at all leave the instance as it was.
   const { scenarios, errors } = await loadScenarios(resolved);
-  if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
-  for (const fake of fakes.values()) fake.reset();
+  if (into("database")) {
+    // The last seed's moments, and whatever a visitor started since, end here: nothing is kept.
+    await client.cancelUnfinished();
+    if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
+  }
+  if (into("memory")) for (const fake of fakes.values()) fake.reset();
   const state: DemoState = {
     seededAt: new Date().toISOString(),
     worlds: [],
@@ -49,28 +72,36 @@ export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Pr
   };
   const secrets = memorySecrets();
   for (const world of scenarios.filter((s) => s.workflow === undefined)) {
+    // Each Given keeps its place in the world, so its call's idempotency key is the same in either half.
+    const kept = [...world.given.entries()].filter(([, g]) => {
+      const half = halfOf(g, resolved);
+      return half === undefined || into(half);
+    });
     try {
-      await applyGivens(world, {
-        kind: "instance",
-        drivers: resolved.drivers,
-        fakes,
-        ops: resolved.ops,
-        call: (i, opId) => ({
-          idempotencyKey: `world:${world.name}:${i}`,
-          runId: `world:${world.name}`,
-          opId,
-          attempt: 1,
-          secrets,
-          // Who its records are by: whoever it says is acting, else the runtime's own agent.
-          by: world.startedBy ?? "scenarios",
-        }),
-      });
+      await applyGivens(
+        { name: world.name, given: kept.map(([, g]) => g) },
+        {
+          kind: "instance",
+          drivers: resolved.drivers,
+          fakes,
+          ops: resolved.ops,
+          call: (i, opId) => ({
+            idempotencyKey: `world:${world.name}:${kept[i]![0]}`,
+            runId: `world:${world.name}`,
+            opId,
+            attempt: 1,
+            secrets,
+            // Who its records are by: whoever it says is acting, else the runtime's own agent.
+            by: world.startedBy ?? "scenarios",
+          }),
+        },
+      );
       state.worlds.push(world.name);
     } catch (err) {
       state.problems.push(`world "${world.name}": ${errorMessage(err)}`);
     }
   }
-  for (const s of scenarios) {
+  for (const s of into("database") ? scenarios : []) {
     if (!s.moment || s.workflow === undefined) continue;
     try {
       const runId = await client.start(s.workflow, s.input, { sandbox: s.name, startedBy: s.moment.person });

package/src/describe.ts

@@ -1,5 +1,6 @@
 import { join } from "node:path";
 import type { z } from "zod";
+import { type AppEntry, appsAt } from "./apps.ts";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { type Field, recordSchemaOf } from "./collection.ts";
 import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
@@ -14,6 +15,7 @@ import {
   type DataFiles,
   type DeclaredCollection,
   type DeclaredResource,
+  inAppPeople,
   readDataFiles,
   type ResourceProblem,
 } from "./resources.ts";
@@ -62,8 +64,19 @@ export {
   type Bindings,
   type Rebind,
 } from "./lockfile.ts";
+// The apps under `apps/`, read without running their `app.ts`.
+export { crossAppImports, readApps, type AppEntry } from "./apps.ts";
 // What the sites call, read from their source: a workflow's Used by.
-export { readSites, type SiteCall, type SiteEntry, type SitePage, siteContentPages, siteLocales } from "./sites.ts";
+export {
+  readSites,
+  type SiteCall,
+  type SiteEntry,
+  type SitePage,
+  siteContentPages,
+  siteIcons,
+  siteLocales,
+  sitesUnder,
+} from "./sites.ts";
 // The generated SDK, `.sanoma/api.ts`: a site's `api` typed from this description.
 export { API_FILE, generateApi, writeApi, writeGenerated } from "./sdk.ts";
 // The Cedar schema, `.sanoma/schema.cedarschema`: what a company's policies are validated and decided against.
@@ -76,7 +89,10 @@ export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanS
 
 /** What a workflow is, read from its definition: enough to draw a start form and show what it may call. */
 export interface WorkflowEntry {
+  /** Its name: `<app>.<name>` for one an app's folder defines. */
   name: string;
+  /** The app whose folder defines it (`apps/<app>/workflows/`); absent for one at the root. */
+  app?: string;
   title?: string;
   /** `manual`, or the schedule it starts on (`defineWorkflow`'s `trigger`). */
   trigger: Trigger;
@@ -166,7 +182,10 @@ export interface ResourceTypeEntry {
 
 /** A collection the config declares (`collection()`). */
 export interface CollectionEntry {
+  /** Its name: `<app>.<name>` for one an app's `resources/data.ts` declares. */
   name: string;
+  /** The app whose folder declares it (`apps/<app>/resources/data.ts`); absent for one at the root. */
+  app?: string;
   title?: string;
   /** The field each record is found by. */
   key: string;
@@ -204,8 +223,14 @@ export interface ConfigDescription {
   resources: DeclaredResource[];
   /** Each binding in the lockfile (`LOCKFILE`) whose key no data file declares, as `readDataFiles` reports it. */
   orphans: DataFiles["orphans"];
-  /** What is wrong in the data files (`readDataFiles`), each at its file, relative to the root, line and column. A workflow's are on its entry. */
+  /**
+   * What is wrong in the data files (`readDataFiles`) and the apps (a folder of `apps/` that is no
+   * app, an `app.ts` that cannot be read, a collection or site at the root named as an app is),
+   * each at its file, relative to the root, line and column. A workflow's are on its entry.
+   */
   problems: ResourceProblem[];
+  /** The apps under `apps/` (`readApps`), by name. Each workflow, collection and site an app declares names it (`app`). */
+  apps: AppEntry[];
   /**
    * `defined` when the root has `policies/**\/*.cedar` (else the policy is `allowAll`), with their
    * `version`, or while they have `problems` (`policyProblems`), none: then every call and start is refused.
@@ -258,6 +283,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   const collections: CollectionEntry[] = [...resolved.collections.values()]
     .map((c) => ({
       name: c.name,
+      ...(c.app !== undefined && { app: c.app }),
       ...(c.title !== undefined && { title: c.title }),
       key: c.key,
       fields: c.fields,
@@ -294,6 +320,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
         ];
     return {
       name: wf.name,
+      ...(wf.app !== undefined && { app: wf.app }),
       title: wf.title,
       trigger: wf.trigger,
       ...(builtin && { builtin: true as const }),
@@ -308,6 +335,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   });
   workflows.sort((a, b) => a.name.localeCompare(b.name));
   addApiNameProblems(workflows, new Set(ops.map((op) => op.vendor)));
+  const { apps, problems: appProblems } = appsAt(resolved.root);
   const sites = readSites(
     resolved.root,
     { workflows, collections, ops },
@@ -323,9 +351,16 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     vendors,
     resourceTypes,
     collections,
-    resources: dataFiles.resources,
+    // An app's people are refused (`readPeople`), so the grid and the People page never show them.
+    resources: dataFiles.resources.filter((r) => !inAppPeople(r)),
     orphans: dataFiles.orphans,
-    problems: [...dataFiles.problems, ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read)],
+    problems: [
+      ...dataFiles.problems,
+      ...appProblems,
+      ...appClashes(apps, collections, sites),
+      ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read),
+    ],
+    apps,
     policy: {
       defined: resolved.policy !== allowAll,
       ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
@@ -335,6 +370,34 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   };
 }
 
+/** That the root's `kind` `name`, in `file`, is named as an app is. */
+const appClash = (kind: string, name: string, file: string): ResourceProblem => ({
+  file,
+  line: 1,
+  column: 1,
+  message: `the ${kind} ${name} is named as the app apps/${name} is: name it otherwise`,
+});
+
+/**
+ * A collection or site at the root named as an app is: `api.data.<app>` and `/sites/<app>/` are
+ * the app's, so the root's would take its place.
+ */
+function appClashes(
+  apps: readonly AppEntry[],
+  collections: readonly CollectionEntry[],
+  sites: readonly SiteEntry[],
+): ResourceProblem[] {
+  const names = new Set(apps.map((app) => app.name));
+  return [
+    ...collections
+      .filter((c) => c.app === undefined && names.has(c.name))
+      .map((c) => appClash("collection", c.name, c.declared?.file ?? "resources/data.ts")),
+    ...sites
+      .filter((site) => site.app === undefined && names.has(site.name))
+      .map((site) => appClash("site", site.name, `sites/${site.name}`)),
+  ];
+}
+
 /**
  * Each site a host's `domains` (its type's `host.inputs.domains`) names that is not a public
  * site, and each domain it gives more than one site, at the host's declaration: the app serves

package/src/direct.ts

@@ -1,15 +1,19 @@
 import type { Op } from "./op.ts";
 import { isResourceOp } from "./resource.ts";
-import { DATA_VENDOR } from "./shared.ts";
+import { APPS_LIST, DATA_VENDOR } from "./shared.ts";
 
 /**
  * Whether an operation may be called directly, outside a run (`SanomaClient.call`), as the
- * person: a collection's (`data.<name>.<op>`), or a `read` that is neither the runtime's own
- * (the vendor `sanoma`) nor a resource type's (`isResourceOp`), which only drift and apply call.
+ * person: a collection's (`data.<name>.<op>`), the runtime's listing of apps (`sanoma.apps.list`,
+ * which a page calls), or a `read` that is neither the runtime's own (the vendor `sanoma`) nor a
+ * resource type's (`isResourceOp`), which only drift and apply call.
  * Anything else (an effect at a vendor) is a workflow's. The one rule: the built-in `call`
  * workflow, the SDK and the app read it, from here or from `OpEntry.direct`, and never derive it.
  */
 export const isDirect = (
-  op: Pick<Op, "vendor" | "resource" | "effect">,
+  op: Pick<Op, "id" | "vendor" | "resource" | "effect">,
   types: ReadonlyMap<string, unknown>,
-): boolean => op.vendor === DATA_VENDOR || (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));
+): boolean =>
+  op.vendor === DATA_VENDOR ||
+  op.id === APPS_LIST ||
+  (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));

package/src/errors.ts

@@ -51,6 +51,9 @@ export function errorCode(e: unknown): ErrorCode | undefined {
   return code !== undefined && KNOWN.has(code) ? (code as ErrorCode) : undefined;
 }
 
+/** A `DriverError`'s `vendorCode` (`no_token`, `bad_signature`), read as a property: undefined for anything else. */
+export const vendorCodeOf = (e: unknown): string | undefined => own<string>(e, "vendorCode", "string");
+
 /**
  * True when the error says trying again would only repeat it (`retryable: false`), as a
  * `DriverError` for a vendor's final answer or a ledger store for a corrupt file does. Read as