@sanoma-ai/workflows 0.7.1 → 0.8.1

package/src/index.ts

@@ -61,6 +61,9 @@ export {
   type ResolvedConfig,
   type SanomaConfig,
 } from "./config.ts";
+// An app's `app.ts` (`defineApp`), and where the launcher finds an app's workflows and data file.
+export { type AppDefinition, type AppEntry, defineApp, readApps } from "./apps.ts";
+export { appFolders, APPS_DIR, filesUnder, kindDirs } from "./paths.ts";
 // `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
 // `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
 export { isCollection } from "./collection.ts";
@@ -76,12 +79,15 @@ export {
 } from "./apply.ts";
 export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
 export {
+  type ChangeDecision,
+  type ChangeDeploy,
   type ChangeEvent,
   ChangeFacts,
   ChangeInput,
   changeOps,
   type ChangeReport,
   type ChangeState,
+  type ChangeVerified,
   runtimeHold,
   touchesOf,
 } from "./change.ts";
@@ -125,6 +131,7 @@ export {
   ApprovalPendingError,
   errorCode,
   type ErrorCode,
+  vendorCodeOf,
   type ErrorInfo,
   type InputIssue,
   invalidInput,
@@ -161,9 +168,12 @@ export {
   type Secrets,
 } from "./secret.ts";
 export {
+  type AppMerge,
   type CheckResult,
   type Draft,
+  draftBranch,
   type DraftDiff,
+  draftOf,
   type HostEnforcement,
   type PullRequest,
   type RemoteContext,
@@ -196,6 +206,8 @@ export {
 } from "./wakeup.ts";
 export {
   type CallOptions,
+  type ChangesFilter,
+  type ChangeView,
   type ClientOptions,
   SanomaClient,
   type RunsFilter,
@@ -217,12 +229,14 @@ export {
   CHANGE_MERGE,
   CHANGE_OPEN,
   CHANGE_REVIEW,
+  CHANGE_TOPIC,
   CHANGE_WORKFLOW,
   declaresPeople,
   type PeopleResource,
   personOf,
   principalOf,
   RUNTIME_AGENTS,
+  HOST_CHECK_AGENT,
   SCHEDULE_AGENT,
   credentialReady,
   DEFAULT_SLEEP_NAME,

package/src/lint.ts

@@ -1,9 +1,9 @@
 import { realpathSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { byPosition, childrenOf, type LintProblem, type Node, parsed, type SourceFile } from "./ast.ts";
 import { COLLECTIONS_FILE, readDataFile } from "./datafile.ts";
 import { constsOf, outlineBody, workflowLiterals } from "./outline.ts";
-import { inside, nearestDir, RELATIVE } from "./paths.ts";
+import { APPS_DIR, inside, nearestDir, RELATIVE } from "./paths.ts";
 // From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
 import oxlint from "../oxlint.json" with { type: "json" };
 
@@ -203,11 +203,14 @@ function whyRefused(spec: string, filename: string | undefined, root: string | u
     const target = join(dirname(filename), spec);
     if (inside(root, target)) return undefined;
     const tree = basename(root) === "workflows";
-    // The collections, which a workflow names in `uses`: the one data file the runtime imports too.
-    if (tree && realPath(target) === realPath(join(dirname(root), "resources", COLLECTIONS_FILE))) return undefined;
+    // The collections, which a workflow names in `uses`: the one data file the runtime imports too,
+    // the root's or an app's (`apps/<app>/resources/data.ts`), wherever the workflow is.
+    if (tree && isCollectionsFile(realPath(target), realPath(dirname(root)))) return undefined;
     return (
       `it reaches outside ${tree ? `${basename(root)}/` : "this directory"}, toward the config and its drivers; ${THROUGH_CTX}` +
-      (tree ? "; of the files outside it, only resources/data.ts (the collections) may be imported" : "")
+      (tree
+        ? "; of the files outside it, only resources/data.ts (the collections, the root's or an app's apps/<app>/resources/data.ts) may be imported"
+        : "")
     );
   }
   for (const [pattern, reason] of REFUSED_PACKAGES) if (pattern.test(spec)) return reason;
@@ -215,6 +218,18 @@ function whyRefused(spec: string, filename: string | undefined, root: string | u
   return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
 }
 
+/**
+ * Whether `target` is a collections file of the company whose workflows' tree is in `base` (the
+ * root, or an app's `apps/<app>/`): `<root>/resources/data.ts` or `<root>/apps/<app>/resources/data.ts`.
+ */
+function isCollectionsFile(target: string, base: string): boolean {
+  const root = basename(dirname(base)) === APPS_DIR ? dirname(dirname(base)) : base;
+  const parts = relative(root, target).split(sep);
+  const [first, app] = parts;
+  const rest = first === APPS_DIR && app !== undefined ? parts.slice(2) : parts;
+  return rest.length === 2 && rest[0] === "resources" && rest[1] === COLLECTIONS_FILE;
+}
+
 /** A path's real path, or the path itself when it does not exist. */
 function realPath(path: string): string {
   try {

package/src/outline.ts

@@ -1,6 +1,6 @@
 import { childrenOf, type Node, readSource, type SourceFile } from "./ast.ts";
 import { opIdsOf, type WorkflowDefinition } from "./define.ts";
-import { childLists, DEFAULT_SLEEP_NAME, fitsOp, flatten } from "./shared.ts";
+import { childLists, DATA_VENDOR, DEFAULT_SLEEP_NAME, fitsOp, flatten, writtenName } from "./shared.ts";
 
 /**
  * What a workflow's `run` calls through `ctx`, in the order it makes the calls, with the loops,
@@ -118,8 +118,10 @@ export function outlineWithSource(
     return { outline: { error: `${file.file} could not be parsed: ${why}` }, found: false };
   }
   const consts = constsOf(file.program);
-  const fn = runIn(file.program, wf.name, consts);
-  if (!fn) return { outline: { error: `${file.file} holds no workflow named "${wf.name}"` }, found: false };
+  // An app's workflow is found by the name its file writes, without the app.
+  const name = writtenName(wf);
+  const fn = runIn(file.program, name, consts);
+  if (!fn) return { outline: { error: `${file.file} holds no workflow named "${name}"` }, found: false };
   const { nodes, problems } = outlineBody(fn, { consts, source: file.source });
   if (problems.length) {
     const lines = problems.map((p) => {
@@ -219,8 +221,8 @@ const DEFAULT_LIKE = (name: string) =>
 /** Two steps given one name, and how to tell them apart. */
 const TWICE = (name: string, fix: string) =>
   `two steps of this workflow are named "${name}": a name given is one step's, so a test or the graph can tell them apart; ${fix}`;
-/** A name given that reads as an operation's id: what an unnamed call is called. */
-const OP_ID = /^[\w-]+(\.[\w-]+){2}$/;
+/** A name given that reads as an operation's id, four segments only for an app's collection: what an unnamed call is called. */
+const OP_ID = new RegExp(String.raw`^([\w-]+(\.[\w-]+){2}|${DATA_VENDOR}(\.[\w-]+){3})$`);
 
 /** Where a function's body starts: its own statement rules, nothing of the caller's. */
 const bodyOf = (fn: Node): Where => ({ fn, inCatch: false });
@@ -424,7 +426,7 @@ export function outlineBody(
             { kind: "sleep", path, span: span(node), name: nameIn(args[1]) ?? DEFAULT_SLEEP_NAME },
           ];
         default:
-          if (members.length === 3) {
+          if (isOpPath(members)) {
             // A computed id's own name is the operation it calls, known only in a run.
             const name = nameIn(args[1]) ?? (id.includes("*") ? undefined : id);
             return [
@@ -564,6 +566,13 @@ function switchArms(node: Node): Node[] {
   return node.cases.some((c: Node) => c.test === null) ? arms : [...arms, null];
 }
 
+/**
+ * Whether a path on `ctx` is an operation's: `<vendor>.<resource>.<op>`, or an app's collection's,
+ * `data.<app>.<collection>.<op>` (a computed vendor may be either).
+ */
+const isOpPath = (members: readonly string[]): boolean =>
+  members.length === 3 || (members.length === 4 && (members[0] === DATA_VENDOR || members[0] === "*"));
+
 /** The member names from `ctx` to the callee, `*` for a computed one, when the callee is on `ctx`. */
 function ctxPath(callee: Node, ctx: string): string[] | undefined {
   const path: string[] = [];

package/src/paths.ts

@@ -1,5 +1,6 @@
-import { readdirSync, statSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { APP_NAME } from "./shared.ts";
 
 // Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
 // the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
@@ -45,3 +46,57 @@ export function filesUnder(dir: string, keep: (name: string) => boolean): string
     .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
     .toSorted();
 }
+
+/** Where a company's apps are, under its root: `apps/<app>/`. */
+export const APPS_DIR = "apps";
+
+/** Each directory's company root (the nearest one with a `sanoma.config.ts`, short of a `node_modules`), once found. */
+const roots = new Map<string, string>();
+
+/** Whether `dir` is a company's root: it holds a `sanoma.config.ts`. */
+const isCompany = (dir: string) => existsSync(join(dir, "sanoma.config.ts"));
+
+/**
+ * The app a file is in: `<app>` for a file under `<root>/apps/<app>/`, where the root is the
+ * nearest directory above it with a `sanoma.config.ts` (an app keeps its own `package.json`,
+ * and its own config when merged from a company's repo: then the company is the one whose
+ * `apps/` holds it; a `node_modules` ends the search: the file is a package's, not a company's);
+ * undefined for a file at the root or outside any company. `defineWorkflow` and `collection()` name what they declare by it.
+ */
+export function appOfFile(file: string | undefined): string | undefined {
+  if (file === undefined) return undefined;
+  const dir = dirname(resolve(file));
+  let root: string | null | undefined = roots.get(dir);
+  if (root === undefined) {
+    root =
+      upFrom<string | null>(dir, (d) => (basename(d) === "node_modules" ? null : isCompany(d) ? d : undefined)) ?? null;
+    // An app merged from a company's repo keeps that repo's config: the company is the one above.
+    if (root !== null && basename(dirname(root)) === APPS_DIR && isCompany(dirname(dirname(root)))) {
+      root = dirname(dirname(root));
+    }
+    // Found roots only: a directory that is no company's yet may become one (`sanoma` in an empty folder).
+    if (root !== null) roots.set(dir, root);
+  }
+  if (root === null) return undefined;
+  const [top, app, ...rest] = relative(root, file).split(sep);
+  return top === APPS_DIR && app !== undefined && rest.length && APP_NAME.test(app) ? app : undefined;
+}
+
+/** The apps' folders under `root` whose names are an `APP_NAME`, sorted: `apps/<app>/`, absolute. */
+export function appFolders(root: string): string[] {
+  const dir = join(root, APPS_DIR);
+  if (!isDirectory(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && APP_NAME.test(d.name))
+    .map((d) => join(dir, d.name))
+    .toSorted();
+}
+
+/** Where a kind of file is under `root`: `<root>/<kind>`, then each app's `apps/<app>/<kind>`, whether or not they exist. */
+export const kindDirs = (root: string, kind: string): string[] => [
+  join(root, kind),
+  ...appFolders(root).map((app) => join(app, kind)),
+];
+
+/** Where a company's scenarios are, under its root and each app's folder. */
+export const SCENARIOS_DIR = "scenarios";

package/src/resources.ts

@@ -1,5 +1,5 @@
 import { readFileSync, statSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
+import { dirname, relative, resolve, sep } from "node:path";
 import { parsed } from "./ast.ts";
 import {
   type DataFile,
@@ -11,7 +11,7 @@ import {
 } from "./datafile.ts";
 import { type Binding, type Bindings, LOCKFILE, readLockfile } from "./lockfile.ts";
 import { type Connector, VENDOR } from "./op.ts";
-import { filesUnder } from "./paths.ts";
+import { APPS_DIR, filesUnder, kindDirs } from "./paths.ts";
 import { peopleConnector, sanoma } from "./person.ts";
 import { wakeupOps } from "./wakeup-type.ts";
 import type { Span } from "./outline.ts";
@@ -28,6 +28,7 @@ import {
   personOf,
   principalOf,
   problemLine,
+  qualified,
   RUNTIME_AGENTS,
   VISITORS,
 } from "./shared.ts";
@@ -65,9 +66,9 @@ export interface DeclaredResource {
 export interface DeclaredCollection {
   /** `<file>#<export>`, as a resource's: `resources/data.ts#outbound`. */
   id: string;
-  /** `resources/data.ts`. */
+  /** `resources/data.ts`, or an app's `apps/<app>/resources/data.ts`. */
   file: string;
-  /** The collection's name, its operations' middle segment (`data.<name>.get`). */
+  /** The collection's name, its operations' middle segments (`data.<name>.get`): an app's with its app, `crm.contacts`. */
   name: string;
   /** Its `export const` statement, as UTF-16 offsets into the file's text. */
   span: Span;
@@ -119,7 +120,8 @@ const peopleRead = new Map<string, { stamp: string; read: DeclaredPeople }>();
 
 /** Each data file under `root` with its size and modification time: unchanged while the files are. */
 const filesStamp = (root: string) =>
-  dataFilesUnder(join(root, "resources"))
+  kindDirs(root, "resources")
+    .flatMap(dataFilesUnder)
     .map((path) => {
       // Gone since it was listed (an editor's save by rename): stamped as such, and read next time.
       const stat = statSync(path, { bigint: true, throwIfNoEntry: false });
@@ -134,6 +136,13 @@ const RESERVED_GROUPS: ReadonlyMap<string, string> = new Map([
   [ANONYMOUS, "who a public page runs as when nobody is signed in"],
 ]);
 
+/**
+ * A person, agent or group declared in an app's data file: refused, because the people are the
+ * company's, so neither the policy (`readPeople`) nor `describeConfig` counts it.
+ */
+export const inAppPeople = (r: DeclaredResource): boolean =>
+  r.vendor === "sanoma" && Object.hasOwn(sanoma, r.type) && r.file.startsWith(`${APPS_DIR}/`);
+
 /**
  * The people, agents and groups the data files under `root` declare (`sanoma.person`, `.agent`,
  * `.group`), read without running them, as `principalOf` takes them, with what is wrong in their
@@ -147,9 +156,16 @@ export function readPeople(root: string | undefined): DeclaredPeople {
   if (cached?.stamp === stamp) return cached.read;
   // With the wakeup's type, which the same constructors declare: read, and only the people's kept.
   const read = readDataFiles(root, [peopleConnector, wakeupOps], undefined, (source) => DECLARES_PEOPLE.test(source));
-  const people = read.resources.filter((r) => Object.hasOwn(sanoma, r.type));
+  const ofPeople = read.resources.filter((r) => Object.hasOwn(sanoma, r.type));
+  const people = ofPeople.filter((r) => !inAppPeople(r));
   // The people are never bound, so the lockfile's problems are not theirs.
   const own = read.problems.filter((p) => p.file !== LOCKFILE);
+  for (const r of ofPeople.filter(inAppPeople)) {
+    own.push({
+      file: r.file,
+      message: `${r.id} declares a ${r.type} in an app: the people are the company's, declared in resources/ at the root`,
+    });
+  }
   const ids = new Map<string, DeclaredResource>();
   for (const r of people) {
     if (r.type === "group") {
@@ -262,7 +278,8 @@ export function readDataFiles(
 
   const files = new Map<string, FileEntry>();
   const left = new Set<string>();
-  for (const path of dataFilesUnder(join(root, "resources"))) {
+  // The root's, then each app's: a data file imports only from its own `resources/`.
+  for (const [dir, path] of kindDirs(root, "resources").flatMap((d) => dataFilesUnder(d).map((p) => [d, p] as const))) {
     const rel = relative(root, path).split(sep).join("/");
     const source = readFileSync(path, "utf8");
     if (partial && !partial(source)) {
@@ -270,7 +287,7 @@ export function readDataFiles(
       continue;
     }
     const { program, problems: syntax, at } = parsed(source, path);
-    const data = readDataFile(program, path, join(root, "resources"));
+    const data = readDataFile(program, path, dir);
     const problem = (offset: number, message: string) => problems.push({ file: rel, ...at(offset), message });
     for (const p of syntax) problems.push({ file: rel, ...p });
     for (const p of data.problems) problem(p.start, p.message);
@@ -465,7 +482,8 @@ export function readDataFiles(
     data.collections.map((c) => ({
       id: `${rel}#${c.export}`,
       file: rel,
-      name: c.name,
+      // An app's, `apps/<app>/resources/data.ts`, is named with its app, as `collection()` names it.
+      name: qualified(rel.startsWith(`${APPS_DIR}/`) ? rel.split("/")[1] : undefined, c.name),
       span: [c.start, c.end] as Span,
     })),
   );

package/src/run.ts

@@ -71,6 +71,11 @@ export interface WorkerState {
   workflows: Map<string, WorkflowDefinition<any, any>>;
   /** Each workflow's outline, by name: read once when the worker starts, every run is held to it (`call_not_in_outline`). */
   outlines: Map<string, WorkflowOutline>;
+  /**
+   * Starts a run of the workflow `name` as `runId` (an id the run already has returns it): how a
+   * built-in starts another as its child, as the change run starts apply and drift.
+   */
+  startRun(name: string, runId: string, args: RunArgs): Promise<{ getResult(): Promise<unknown> }>;
   /**
    * Set when the worker stops, before DBOS shuts down. DBOS abandons a stopped worker's run
    * functions, which then fail as their next DBOS call finds the database closed. Such a failure,

package/src/sandbox.ts

@@ -1,5 +1,5 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
-import { indexDrivers } from "./config.ts";
+import { indexDrivers, sandboxDrivers } from "./config.ts";
 import { opIdsOf } from "./define.ts";
 import { SanomaError } from "./errors.ts";
 import type { Fake, ResourceFake } from "./fake.ts";
@@ -178,10 +178,7 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
       const fakes = instance ?? new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
       const drivers = instance
         ? state.drivers
-        : indexDrivers(
-            [...fakes.values()].map((f) => f.driver),
-            state.ops,
-          );
+        : indexDrivers([...Array.from(fakes.values(), (f) => f.driver), ...sandboxDrivers], state.ops);
       // What the scenario seeds is checked by `applyGivens`.
       const missing = opIdsOf(state.workflows.get(run.workflow)!).filter((id) => !drivers.has(id));
       if (missing.length) {

package/src/scenario.ts

@@ -1,5 +1,5 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative, sep } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 import type { ISupportCodeLibrary } from "@cucumber/cucumber/api";
@@ -33,6 +33,7 @@ import { fill, isBug, objectUnder, restOf, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
+import { isDirectory, kindDirs, SCENARIOS_DIR } from "./paths.ts";
 import { isObject } from "./resource.ts";
 import { admit, type DeclaredPeople, readPeople } from "./resources.ts";
 import { memorySecrets } from "./secret.ts";
@@ -1231,6 +1232,15 @@ function featureFiles(dir: string): string[] {
     .toSorted();
 }
 
+/**
+ * A company's scenarios: the `.feature` files under `scenarios/` in `root`, then under each app's
+ * `apps/<app>/scenarios/`, relative to `root`, with `/` between directories.
+ */
+const scenarioFiles = (root: string): string[] =>
+  kindDirs(root, SCENARIOS_DIR).flatMap((dir) =>
+    isDirectory(dir) ? featureFiles(dir).map((file) => `${relative(root, dir).split(sep).join("/")}/${file}`) : [],
+  );
+
 /** What `loadScenarios` returns. */
 export interface LoadedScenarios {
   scenarios: Scenario[];
@@ -1383,8 +1393,8 @@ const loadedByScope = new WeakMap<
 >();
 
 /**
- * Every scenario in the `.feature` files under `scenarios` (a `file:` URL to a directory),
- * compiled by Cucumber, with an error for each file that does not compile and each name used
+ * Every scenario in the `.feature` files under `scenarios/` and each app's `apps/<app>/scenarios/`
+ * in `scenarios` (a `file:` URL to the root), each named by its path from there, compiled by Cucumber, with an error for each file that does not compile and each name used
  * twice. No directory, or none given, is no scenarios. Rejects when an operation's phrase names
  * a field it lacks. The files are compiled again only once one is added, removed or written
  * (its name, `mtimeMs` or size changes), or the people's data files change: until then each
@@ -1396,7 +1406,7 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
   if (!existsSync(dir)) return { scenarios: [], errors: [] };
   // Built first, so a phrase naming a field its input lacks rejects even with no feature files.
   builtFor(scope);
-  const files = featureFiles(dir);
+  const files = scenarioFiles(dir);
   const stamp = JSON.stringify([
     dir,
     files.map((file) => {

package/src/scenarios.ts

@@ -6,7 +6,7 @@ import { type Check, check, drive, loadScenarios, type Scenario, type Scope } fr
 import { errorMessage } from "./shared.ts";
 import { startWorker } from "./worker.ts";
 
-export { type DemoState, demoState, reseed } from "./demo.ts";
+export { type DemoState, demoState, reseed, type SeedHalf } from "./demo.ts";
 
 /*
  * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test

package/src/sdk.ts

@@ -3,7 +3,7 @@ import { dirname, join } from "node:path";
 import type { CollectionEntry, ConfigDescription, OpEntry, WorkflowEntry } from "./describe.ts";
 import { isObject } from "./resource.ts";
 import { type CedarSchemaJson, SCHEMA_FILE, schemaText } from "./schema.ts";
-import { apiNameOf, DATA_VENDOR, problemLine } from "./shared.ts";
+import { apiNameOf, DATA_VENDOR, problemLine, writtenName } from "./shared.ts";
 
 // A company's generated SDK, `.sanoma/api.ts`: the types of a site's `api` from `sanoma/site`,
 // written from `describeConfig` (types and JSDoc only: `api` itself is one generic client). It
@@ -24,7 +24,7 @@ type Schema = Record<string, unknown>;
  * `.sanoma/api.ts` for a description: one record type per collection, and `CompanyApi` (not `Api`,
  * which inside `declare module "sanoma/site"` is the module's own), one member per
  * workflow (`apiNameOf`), per vendor of the operations a person may call directly (`OpEntry.direct`,
- * by resource) and `data` for the collections, each with its JSDoc; then `Register`'s
+ * by resource) and `data` for the collections (an app's under its name), each with its JSDoc; then `Register`'s
  * augmentation. Pure: the same description gives the same text. A workflow whose api name another
  * has, `describeConfig`'s problem on its entry, is left out, and its problem is in `problems`.
  */
@@ -46,9 +46,16 @@ export function generateApi(description: ConfigDescription): { source: string; p
     members.push(member(`${title}: the operations a person may call directly.`, vendor, block(resources)));
   }
   if (description.collections.length) {
-    const data = description.collections.map((c) =>
-      member(collectionDoc(c), c.name, `CollectionApi<${recordName(c)}>`),
-    );
+    // The root's by name, then each app's under its name: `api.data.crm.contacts`.
+    const collectionMember = (c: CollectionEntry) =>
+      member(collectionDoc(c), writtenName(c), `CollectionApi<${recordName(c)}>`);
+    const byApp = Map.groupBy(description.collections, (c) => c.app);
+    const data = [
+      ...(byApp.get(undefined) ?? []).map(collectionMember),
+      ...[...byApp]
+        .filter(([app]) => app !== undefined)
+        .map(([app, own]) => member(`The ${app} app's collections.`, app!, block(own.map(collectionMember)))),
+    ];
     members.push(member("The company's collections.", DATA_VENDOR, block(data)));
   }
   const source = [
@@ -127,8 +134,15 @@ const opMember = (op: OpEntry) =>
 const collectionDoc = (c: CollectionEntry) =>
   `${c.title ?? c.name}: the collection \`${c.name}\`, keyed by \`${c.key}\`.`;
 
-/** A collection's record type's name: `outbound` gives `OutboundRecord`, never `CompanyApi` nor an imported type's. */
-const recordName = (c: CollectionEntry) => `${c.name[0]!.toUpperCase()}${c.name.slice(1)}Record`;
+/**
+ * A collection's record type's name: `outbound` gives `OutboundRecord`, an app's `crm.contacts`
+ * `CrmContactsRecord`; never `CompanyApi` nor an imported type's.
+ */
+const recordName = (c: CollectionEntry) =>
+  `${c.name
+    .split(".")
+    .map((part) => `${part[0]!.toUpperCase()}${part.slice(1)}`)
+    .join("")}Record`;
 
 /**
  * A JSON Schema as a TypeScript type, for the kinds a start form draws (`fieldsOf` in the app):

package/src/shared.ts

@@ -22,12 +22,16 @@ export type { DeclaredResource, ResourceProblem } from "./resources.ts";
 export type { DriftField, DriftReport, DriftResult, DriftStatus } from "./drift.ts";
 export type { ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 export type { CredentialStatus } from "./env.ts";
-export type { ChangeEvent, ChangeFacts, ChangeReport, ChangeState } from "./change.ts";
+export type { ChangeDeploy, ChangeEvent, ChangeFacts, ChangeReport, ChangeState, ChangeVerified } from "./change.ts";
+export type { AvailableApp, AvailableApps } from "./apps-list.ts";
 
 // What a UI in the browser may use from the runtime, besides types: `@sanoma-ai/workflows/shared`.
 // Nothing here imports DBOS, Node or zod, so a browser bundle can carry it; the runtime uses the
 // same functions, so a page answers these questions the way a run does.
 
+// Sanoma's claims, data (`sanoma/claims` re-exports them).
+export * from "./claims.ts";
+
 /**
  * What a `ctx.sleep` without a `{ name }` is called, in its outline node and its ledger record
  * (`name`); a name given may not be it.
@@ -76,6 +80,36 @@ export function previewRequests(
 /** A site's folder name under `sites/`, its URL segment: what the app mounts and `readSites` reads. */
 export const SITE_NAME = /^[a-z][a-z0-9-]*$/;
 
+/**
+ * An app's folder name under `apps/`: a lowercase letter, then lowercase letters and digits. It
+ * prefixes the names of what the folder declares (`qualified`), and is a segment of `ctx.data`,
+ * `api.data` and a site's path, so it is an identifier and a URL segment alike.
+ */
+export const APP_NAME = /^[a-z][a-z0-9]*$/;
+
+/** A name declared under `apps/<app>/` as the runtime has it, `<app>.<name>`; one declared at the root as it is. */
+export const qualified = (app: string | undefined, name: string): string =>
+  app === undefined ? name : `${app}.${name}`;
+
+/** A workflow's or collection's name as its file writes it, `qualified`'s undone: without its app. */
+export const writtenName = ({ name, app }: { name: string; app?: string }): string =>
+  app === undefined ? name : name.slice(app.length + 1);
+
+/**
+ * A site's key: its folder's name at the root, `<app>/<site>` in an app, so its pages are under
+ * `/sites/<key>`. What `readSites` names a site by, and the app's build mounts it at.
+ */
+export const siteKey = (app: string | undefined, site: string): string => (app === undefined ? site : `${app}/${site}`);
+
+/** A site's key (`siteKey`): a `SITE_NAME`, or an `APP_NAME`, `/` and a `SITE_NAME`, as a host's `domains` names a site. */
+export const SITE_KEY = /^([a-z][a-z0-9]*\/)?[a-z][a-z0-9-]*$/;
+
+/** A site's folder, relative to the root, by its key: `sites/<name>`, or an app's `apps/<app>/sites/<name>`. */
+export function siteDir(key: string): string {
+  const [app, site] = key.split("/");
+  return site === undefined ? `sites/${key}` : `apps/${app}/sites/${site}`;
+}
+
 /**
  * A public site's language, as `defineSite({ locales })` names it: a BCP 47 language tag of a
  * language and subtags (`en`, `fr`, `pt-BR`), which is also its URL segment (`/pt-BR/…`) and a
@@ -101,7 +135,7 @@ export function domainsOf(text: string): Record<string, string> {
   const domains: Record<string, string> = {};
   for (const pair of text.split(",")) {
     const [site = "", domain = "", ...rest] = pair.trim().split("=");
-    if (!SITE_NAME.test(site) || !DOMAIN_NAME.test(domain) || rest.length || Object.hasOwn(domains, site)) {
+    if (!SITE_KEY.test(site) || !DOMAIN_NAME.test(domain) || rest.length || Object.hasOwn(domains, site)) {
       throw new Error(
         `SANOMA_DOMAINS has "${pair}": write <site>=<hostname>, each site once, such as www=sanoma.example`,
       );
@@ -211,6 +245,16 @@ export const CALL_WORKFLOW = "call";
  */
 export const CHANGE_WORKFLOW = "change";
 
+/**
+ * The draft a change's run is of: `change:<id>` (its first run) or `change:<id>~<n>` (a later
+ * one); undefined for any other run id.
+ */
+export const changeIdOf = (runId: string): string | undefined => CHANGE_RUN.exec(runId)?.[1];
+
+/** What a draft's id may be (`ChangeInput.id`), the part of its branch and its change's run ids after `draft/` and `change:`. */
+export const DRAFT_ID = /^[\w-]{1,64}$/;
+const CHANGE_RUN = new RegExp(`^change:(${DRAFT_ID.source.slice(1, -1)})(?:~\\d+)?$`);
+
 /** Opens a change: its draft's branch pushed and a pull request opened for it. */
 export const CHANGE_OPEN = "sanoma.change.open";
 /** Reports Sanoma's review of a change to its host (the `sanoma` commit status). */
@@ -221,6 +265,14 @@ export const CHANGE_MERGE = "sanoma.change.merge";
 export const CHANGE_CLOSE = "sanoma.change.close";
 /** The DBOS event a change run publishes its `ChangeState` on. */
 export const CHANGE_EVENT = "change";
+/**
+ * The `recv` topic a change run is told what happened to its change on (a `ChangeEvent`): never an
+ * approval's, whose topic is its id (`approval-<n>`).
+ */
+export const CHANGE_TOPIC = "change:event";
+
+/** Lists the apps on GitHub with Sanoma's claims: the one runtime operation a page may call (`isDirect`). */
+export const APPS_LIST = "sanoma.apps.list";
 
 /** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call and change. */
 export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([
@@ -324,8 +376,10 @@ export const ANONYMOUS_PRINCIPAL: Principal = Object.freeze({ id: ANONYMOUS, gro
 export const WAKEUP_AGENT = "wakeup";
 /** The runtime's agent a scheduled run is started by (`trigger: { schedule }`): the policy decides its starts. */
 export const SCHEDULE_AGENT = "schedule";
+/** The runtime's agent that checks and deploys the hosts: drift's, and apply's after a push to `main` (`SanomaClient.remoteEvent`). */
+export const HOST_CHECK_AGENT = "host-check";
 /** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration), declared whether a data file names them or not. */
-export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", SCHEDULE_AGENT, WAKEUP_AGENT];
+export const RUNTIME_AGENTS: readonly string[] = ["scenarios", HOST_CHECK_AGENT, SCHEDULE_AGENT, WAKEUP_AGENT];
 
 /** The declared resources of one of the runtime's people types, by `desired`. */
 const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>
@@ -467,10 +521,11 @@ export const credentialReady = ({ status, optional }: CredentialStatus): boolean
 
 /**
  * A workflow's name in a site's `api`: kebab-case made camelCase, `outbound-next` as
- * `api.outboundNext`. `describeConfig` reports two workflows that come out the same, or one that
+ * `api.outboundNext`, and an app's workflow one name with its app, `crm.follow-up` as
+ * `api.crmFollowUp`. `describeConfig` reports two workflows that come out the same, or one that
  * comes out as a vendor's id or `data`, as a problem on the workflow.
  */
-export const apiNameOf = (name: string): string => name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
+export const apiNameOf = (name: string): string => name.replace(/[-.]([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 
 /**
  * A workflow as a site's `api` has it (`api.<apiNameOf(name)>`), started as the person on the