@sanoma-ai/workflows 0.2.0 → 0.4.0

package/src/config.ts

@@ -4,10 +4,20 @@ import { pathToFileURL } from "node:url";
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { type ApplyDeclared, applyWorkflow } from "./apply.ts";
 import { applySteps } from "./apply-steps.ts";
+import { callWorkflow } from "./call-workflow.ts";
+import {
+  type Collection,
+  collectionsConnector,
+  collectionsDriver,
+  collectionsFake,
+  isCollection,
+} from "./collection.ts";
+import { lazyPool, type LazyPool } from "./db.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 { peopleConnector } from "./person.ts";
 import type { LedgerStore } from "./ledger.ts";
 import {
   type Connector,
@@ -22,19 +32,20 @@ import {
   setupOf,
   VENDOR,
 } from "./op.ts";
+import { policyAt } from "./cedar.ts";
 import type { Policy } from "./policy.ts";
 import { isChangeOp, type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
-import { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS } from "./shared.ts";
+import { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS, CALL_WORKFLOW, DATA_VENDOR } from "./shared.ts";
 import { sourceDriver, sourceOps } from "./source.ts";
 import type { Steps } from "./steps.ts";
 import { computeVersion } from "./version.ts";
 
 /**
- * What a worker runs, on which connectors, under which policy: the argument to `startWorker`.
+ * What a worker runs, on which connectors: the argument to `startWorker`.
  * A project usually keeps it in `sanoma.config.ts` and passes it in; nothing loads that file
  * automatically. The rest is convention: each connector carries its driver and its fake
- * (`withSetup`), the app's name is its `package.json`'s, and the scenarios and data files are
- * `scenarios/` and `resources/` in `root`.
+ * (`withSetup`), the app's name is its `package.json`'s, and the scenarios, data files and
+ * policies are `scenarios/`, `resources/` and `policies/` in `root`.
  */
 export interface SanomaConfig {
   workflows: WorkflowDefinition<any, any>[];
@@ -46,8 +57,6 @@ export interface SanomaConfig {
    * package attaches the maker of.
    */
   connectors: Connector<any, any>[];
-  /** Checked before every operation call. Required: `allowAll` says that every call is allowed. */
-  policy: Policy;
   /**
    * Where the audit record goes. Default: `postgresLedger` on the config's database, which the
    * worker, the app and other processes share; the worker and the client each make their own
@@ -74,8 +83,15 @@ export interface SanomaConfig {
   appName?: never;
   /** @deprecated Gone: the scenarios are `<root>/scenarios/`. Leave it out. */
   scenarios?: never;
+  /** @deprecated Gone: the policy is `<root>/policies/**\/*.cedar`. Leave it out. */
+  policy?: never;
   /** The company's own steps for its scenarios (`defineSteps`), besides those its connectors ship. */
   steps?: Steps[];
+  /**
+   * The company's collections (`collection()`): their operations are `data.<name>.<op>`, their
+   * records in the config's database, and in memory for a sandbox run.
+   */
+  collections?: readonly Collection[];
 }
 
 /** A config, checked, with everything a worker, client or app derives from it. */
@@ -90,7 +106,10 @@ export interface ResolvedConfig {
   version: string;
   /** The DBOS queue runs are started on: `sanoma:<appName>`. */
   queueName: string;
-  /** The operations the connectors declare, by id, and the built-in `sanoma.source.resolve` when one declares a host type. */
+  /**
+   * The operations the connectors declare, by id, the built-in `sanoma.source.resolve` when one
+   * declares a host type, and the collections' (`data.<name>.<op>`).
+   */
   ops: Map<string, Op>;
   /** The drivers' functions, by operation id, each guarded by its driver's `env` (`indexDrivers`). */
   drivers: Map<string, DriverFn>;
@@ -107,12 +126,27 @@ export interface ResolvedConfig {
   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[];
+  /** The config's collections, by name: their operations are in `ops` and `drivers`, their fake in `fakes`, under `DATA_VENDOR`. */
+  collections: ReadonlyMap<string, Collection>;
   /**
-   * By name; each checked against `ops` and `drivers`. The config's, and the built-ins `drift`
-   * (`DRIFT_WORKFLOW`) and `apply` (`APPLY_WORKFLOW`) when its connectors declare resource types.
+   * The pool the collections' driver keeps their records through, when there are any: opened on
+   * its first call, and closed by whoever calls the driver (the worker, and the client, which
+   * calls it directly, when each stops).
+   */
+  dataStore?: LazyPool;
+  /**
+   * By name; each checked against `ops` and `drivers`. The config's, the built-ins `drift`
+   * (`DRIFT_WORKFLOW`) and `apply` (`APPLY_WORKFLOW`) when its connectors declare resource types,
+   * and `call` (`CALL_WORKFLOW`) when an operation may be called directly (`isDirect`).
    */
   workflows: Map<string, WorkflowDefinition<any, any>>;
+  /**
+   * Checked before every operation call and run start: the root's `policies/**\/*.cedar`
+   * (`policyAt`), `allowAll` without any, and one that refuses everything while they have problems.
+   */
   policy: Policy;
+  /** What is wrong in the policies, one printable line each (`file:line:col: <policy id>: <message>`). */
+  policyProblems: string[];
   /** The config's `ledger`, when it gives one; the worker and the client otherwise make `postgresLedger` on `databaseUrl` (`ownedLedger`). */
   ledger?: LedgerStore;
   /**
@@ -162,12 +196,13 @@ export function rootOf(config: Pick<SanomaConfig, "root" | "file">): string | un
 
 /**
  * Checks a config and derives what the runtime needs from it: the drivers and fakes from the
- * connectors' setups (`withSetup`), and from `root`, the app's name (`package.json`) and the
- * scenarios (`scenarios/`). Throws what `startWorker` would refuse, with the same message, so
- * `describeConfig`, `SanomaClient.connect` and the app fail the same way the worker does. It
- * opens nothing and reads no file outside `root`. Each entry
- * point resolves once: the worker and the client when they start, the app at `startApp`, the
- * `sanoma` bin when it loads the config.
+ * connectors' setups (`withSetup`), the collections' operations, driver and fake, and from
+ * `root`, the app's name (`package.json`), the scenarios (`scenarios/`) and the policy
+ * (`policies/`, `policyAt`). Throws what
+ * `startWorker` would refuse, with the same message, so `describeConfig`, `SanomaClient.connect`
+ * and the app fail the same way the worker does. It opens nothing and reads no file outside
+ * `root`. Each entry point resolves once: the worker and the client when they start, the app at
+ * `startApp`, the `sanoma` bin when it loads the config.
  */
 export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   if (!Array.isArray(config.connectors)) {
@@ -177,14 +212,16 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   if (!Array.isArray(config.workflows)) {
     throw new Error("The config needs `workflows`: an array of defineWorkflow definitions");
   }
-  if (typeof config.policy !== "function") {
-    throw new Error("The config needs a `policy`; use `allowAll` to allow every operation call");
-  }
   // An untyped config naming fake drivers would otherwise run live. Delete once sanoma-ops has migrated.
   if (config.drivers !== undefined || config.fakes !== undefined)
     throw new Error(
       "The config's `drivers` and `fakes` are gone: each connector carries its driver and its fake; leave them out",
     );
+  // An untyped config naming its policy would otherwise run allowing everything. Delete once sanoma-ops has migrated.
+  if (config.policy !== undefined) {
+    throw new Error("The config's `policy` is gone: the policy is policies/*.cedar in the root; leave it out");
+  }
+  const collections = collectionsOf(config);
   const ledger = ledgerOf(config);
   const root = rootOf(config);
   const appName = appNameAt(root);
@@ -192,10 +229,26 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const types = resourceTypesOf(config.connectors);
   // Built-in: `sanoma.source.resolve`, which apply and drift call for a host's revision.
   const hosts = [...types.values()].some((type) => type.host);
-  const ops = indexConnectors([...config.connectors, ...(hosts ? [sourceOps] : [])]);
+  // 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;
+  const ops = indexConnectors([
+    ...config.connectors,
+    ...(hosts ? [sourceOps] : []),
+    ...(dataStore ? [collectionsConnector(declared)] : []),
+  ]);
   const driversByVendor = new Map([...makersOf(config.connectors, "driver")].map(([vendor, make]) => [vendor, make()]));
-  const drivers = indexDrivers([...driversByVendor.values(), ...(hosts ? [sourceDriver] : [])], ops);
+  const drivers = indexDrivers(
+    [
+      ...driversByVendor.values(),
+      ...(hosts ? [sourceDriver] : []),
+      ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
+    ],
+    ops,
+  );
   const fakes = makersOf(config.connectors, "fake");
+  if (dataStore) fakes.set(DATA_VENDOR, () => collectionsFake(declared));
   const names = new Map<string, WorkflowDefinition<any, any>>();
   for (const wf of config.workflows) {
     if (BUILT_IN_WORKFLOWS.has(wf.name)) {
@@ -212,16 +265,23 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   }
   // Built-in: checking the resources the data files declare against their vendors, and applying them.
   if (types.size) {
-    const read = () => readDeclared(root, config.connectors, types);
+    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: 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);
+  const { policy, problems: policyProblems } = policyAt(root, { ops, workflows: names, collections });
   return {
     appName,
-    databaseUrl: resolveDatabaseUrl(config),
+    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()] }),
     queueName: `sanoma:${appName}`,
@@ -232,13 +292,46 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     ...(scenarios && { scenarios }),
     types,
     steps: [...new Set([...config.connectors.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
+    collections,
+    ...(dataStore && { dataStore }),
     workflows: names,
-    policy: config.policy,
+    policy,
+    policyProblems,
     ...(ledger !== undefined && { ledger }),
     ...(root !== undefined && { root }),
   };
 }
 
+/**
+ * The config's collections by name, checked: each one `collection()` made, no two with one name,
+ * and no connector of their vendor, `DATA_VENDOR`.
+ */
+function collectionsOf(config: SanomaConfig): Map<string, Collection> {
+  const list: unknown = config.collections ?? [];
+  if (!Array.isArray(list)) {
+    throw new Error("The config's `collections` must be an array of the collections `collection()` declares");
+  }
+  if (config.connectors.some((c) => c[VENDOR].id === DATA_VENDOR)) {
+    throw new Error(
+      `A connector in \`connectors\` is of the vendor "${DATA_VENDOR}", which the collections' operations are of; name it otherwise`,
+    );
+  }
+  const collections = new Map<string, Collection>();
+  for (const c of list) {
+    if (!isCollection(c)) throw new Error("`collections` holds something `collection()` did not make");
+    const other = collections.get(c.name);
+    if (other && other !== c) throw new Error(`Two collections are named "${c.name}"; name each once`);
+    collections.set(c.name, c);
+  }
+  return collections;
+}
+
+/** The config's connectors 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,
+  peopleConnector,
+];
+
 /**
  * What the connectors' setups attach under `key` (`withSetup`), by vendor id in `connectors`
  * order. One vendor's connectors may name one maker, as copies of one connector do, never two.
@@ -295,22 +388,26 @@ function scenariosAt(root: string | undefined): URL | undefined {
 async function readDeclared(
   root: string | undefined,
   connectors: readonly Connector<any, any>[],
+  declarable: ReadonlyMap<string, Resource>,
   types: ReadonlyMap<string, Resource>,
 ): Promise<Omit<ApplyDeclared, "rebinds">> {
   // Loaded when a run reads the files, not with the worker: the reader parses with oxc-parser.
   const { readDataFiles } = await import("./resources.ts");
-  const { resources, bindings, orphans, problems } = readDataFiles(root, connectors, types);
+  const { resources, bindings, orphans, problems } = readDataFiles(root, connectors, declarable);
   return {
-    resources: resources.map(({ id, vendor, type, name, identity, binding, desired, refs }) => ({
-      id,
-      vendor,
-      type,
-      name,
-      ...(identity !== undefined && { identity }),
-      ...(binding !== undefined && { binding }),
-      desired: withoutWriteOnly(types.get(`${vendor}.${type}`)!.fields, desired),
-      refs,
-    })),
+    // Only `types`' resources have a vendor object to check or apply: not the people's (vendorless).
+    resources: resources
+      .filter((r) => types.has(`${r.vendor}.${r.type}`))
+      .map(({ id, vendor, type, name, identity, binding, desired, refs }) => ({
+        id,
+        vendor,
+        type,
+        name,
+        ...(identity !== undefined && { identity }),
+        ...(binding !== undefined && { binding }),
+        desired: withoutWriteOnly(types.get(`${vendor}.${type}`)!.fields, desired),
+        refs,
+      })),
     bindings,
     orphans,
     problems,

package/src/constructors.ts

@@ -0,0 +1,4 @@
+// `@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`, …).
+export { secret, type Secret } from "./secret.ts";
+export { sanoma } from "./person.ts";

package/src/data.ts

@@ -0,0 +1,10 @@
+// `@sanoma-ai/workflows/data`: what a company's `resources/data.ts` declares its collections with.
+export {
+  collection,
+  type Collection,
+  type Field,
+  type FieldType,
+  type RecordOf,
+  type RequiredTextKeys,
+} from "./collection.ts";
+export type { ListQuery, Saved } from "./shared.ts";

package/src/datafile.ts

@@ -1,7 +1,8 @@
-import { basename, dirname, join } from "node:path";
+import { basename, dirname, join, relative } from "node:path";
 import type { Node } from "./ast.ts";
 import { inside, nearestDir, RELATIVE } from "./paths.ts";
 import { type Secret, SECRET_NAME } from "./secret.ts";
+import { checkCollection, errorMessage } from "./shared.ts";
 
 // The one definition of what a data file may hold, over an ESTree program from oxc: the reader
 // (`resources.ts`), `lintResources` (`lint.ts`) and the oxlint plugin (`plugin.ts`) all
@@ -68,11 +69,24 @@ export interface DataFileExport {
   end: number;
 }
 
+/** An `export const name = collection({ … })` in `resources/data.ts`, its declaration one `collection()` takes. */
+export interface DataFileCollection {
+  /** The `export const`'s name. */
+  export: string;
+  /** The collection's name. */
+  name: string;
+  /** The `export const` statement. */
+  start: number;
+  end: number;
+}
+
 export interface DataFile {
   imports: DataFileImport[];
   /** Each `export const` whose value is in the subset. */
   exports: DataFileExport[];
-  /** Every name an `export const` declares, its value in the subset or not. */
+  /** Each collection `resources/data.ts` declares (`COLLECTIONS_FILE`); none in any other data file. */
+  collections: DataFileCollection[];
+  /** Every name an `export const` declares as a resource, its value in the subset or not: none in `resources/data.ts`. */
   declared: string[];
   problems: DataFileProblem[];
 }
@@ -80,8 +94,22 @@ export interface DataFile {
 /** A connector's constructors entry: a package specifier that ends in `/resources`. */
 const CONSTRUCTORS = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*\/resources$/;
 
-/** Where a data file imports `secret` from; checked before `CONSTRUCTORS`, which they match too. */
+/**
+ * Where a data file imports `secret` from, and `sanoma`, the runtime's own resource constructors
+ * (its people: `sanoma.person`, `.agent`, `.group`); checked before `CONSTRUCTORS`, which they match too.
+ */
 export const SECRET_ENTRIES: ReadonlySet<string> = new Set(["sanoma/resources", "@sanoma-ai/workflows/resources"]);
+/** Where `resources/data.ts` imports `collection` from, and the only imports it may make. */
+export const DATA_ENTRIES: ReadonlySet<string> = new Set(["sanoma/data", "@sanoma-ai/workflows/data"]);
+/**
+ * The one data file that holds collections, relative to `resources/`. Workflows and the runtime
+ * import it, so it imports only `collection` from "sanoma/data" and holds nothing else.
+ */
+export const COLLECTIONS_FILE = "data.ts";
+const COLLECTION_CALL = '`export const <name> = collection({ name: "…", key: "…", fields: { … } })`';
+const COLLECTIONS_ONLY =
+  "resources/data.ts holds collections only, since workflows and the runtime import it: " +
+  `\`import { collection } from "sanoma/data"\` and ${COLLECTION_CALL}; declare a connector's resources in another data file`;
 const SECRET_CALL = '`secret("NAME")` or `secret("NAME", { generate: true })`, NAME upper case (A-Z, 0-9 and _)';
 
 const SHAPE =
@@ -101,6 +129,10 @@ const VALUES = "write a string, number, boolean, null, object or array, or name
  * `export const <name> = <vendor>.<type>({ … })`, one per statement, its argument built of
  * strings (template literals without `${}` too), numbers, booleans, null, objects and arrays,
  * and names of resources this file declares or imports; and `export default [a, b]`.
+ * `resources/data.ts` (`COLLECTIONS_FILE`) is the exception, the one data file workflows and the
+ * runtime import: it imports only `collection` from "sanoma/data", and each `export const` is
+ * `collection({ … })` with its values written out (`DataFile.collections`). No other data file
+ * declares a collection, and none imports one.
  *
  * `root` is the directory relative imports must stay in: by default the nearest `resources/`
  * directory above `filename`, else the file's own.
@@ -115,10 +147,15 @@ export function readDataFile(
     problems.push({ start: node.start, end: node.end, message });
   const imports: DataFileImport[] = [];
   const exports: DataFileExport[] = [];
+  const collections: DataFileCollection[] = [];
+  const collectionsFile = relative(root, filename) === COLLECTIONS_FILE;
+  // What the file may hold, for the problems that say so.
+  const shape = collectionsFile ? COLLECTIONS_ONLY : SHAPE;
   // Names a refused import or declaration binds: reported once, where they are bound.
   const refused = new Set<string>();
-  // The local names of `secret`.
+  // The local names of `secret`, and of `collection`.
   const secrets = new Set<string>();
+  const collectionCalls = new Set<string>();
 
   // Imports and top-level names first, each once: imports are hoisted, and a reference may name
   // a resource declared further down. An unexported const is refused where it is declared, not
@@ -155,20 +192,20 @@ export function readDataFile(
         readDefault(s);
         break;
       case "ExportAllDeclaration":
-        fail(s, `export * is not allowed in a data file: ${SHAPE}`);
+        fail(s, `export * is not allowed in a data file: ${shape}`);
         break;
       case "VariableDeclaration": {
         const name = s.declarations[0]?.id?.name;
         fail(
           s,
           name === undefined
-            ? `an unexported declaration is not allowed in a data file: ${SHAPE}`
-            : `\`${s.kind} ${name}\` is not allowed in a data file: export it as a resource, \`export const ${name} = <vendor>.<type>({ … })\`, or write its value where it is used`,
+            ? `an unexported declaration is not allowed in a data file: ${shape}`
+            : `\`${s.kind} ${name}\` is not allowed in a data file: export it as ${collectionsFile ? `a collection, \`export const ${name} = collection({ … })\`` : `a resource, \`export const ${name} = <vendor>.<type>({ … })\``}, or write its value where it is used`,
         );
         break;
       }
       default:
-        fail(s, `${describe(s)} is not allowed in a data file: ${SHAPE}`);
+        fail(s, `${describe(s)} is not allowed in a data file: ${shape}`);
     }
   }
 
@@ -178,6 +215,16 @@ export function readDataFile(
       fail(s, "`import type` is not allowed in a data file: it holds values only, and the constructors type them");
       return;
     }
+    if (collectionsFile !== DATA_ENTRIES.has(spec)) {
+      fail(
+        s.source,
+        collectionsFile
+          ? `import "${spec}" is not allowed in resources/data.ts: ${COLLECTIONS_ONLY}`
+          : `import "${spec}" is not allowed here: collections are declared in resources/data.ts, the one data file workflows and the runtime import; move it there`,
+      );
+      for (const sp of s.specifiers) refused.add(sp.local.name);
+      return;
+    }
     const refusal = whyRefused(spec);
     if (refusal) {
       fail(s.source, `import "${spec}" is not allowed in a data file: ${refusal}`);
@@ -188,16 +235,26 @@ export function readDataFile(
       fail(s, `import "${spec}" is not allowed in a data file: it imports nothing, and a data file runs no code`);
       return;
     }
-    if (SECRET_ENTRIES.has(spec)) {
+    // The one name each of these entries gives a data file.
+    const [only, locals] = SECRET_ENTRIES.has(spec)
+      ? ["secret", secrets]
+      : DATA_ENTRIES.has(spec)
+        ? ["collection", collectionCalls]
+        : [];
+    if (locals) {
       for (const sp of s.specifiers) {
-        if (
-          sp.type === "ImportSpecifier" &&
-          sp.importKind !== "type" &&
-          (sp.imported.name ?? sp.imported.value) === "secret"
-        ) {
-          secrets.add(sp.local.name);
+        const imported =
+          sp.type === "ImportSpecifier" && sp.importKind !== "type" && (sp.imported.name ?? sp.imported.value);
+        if (imported === only) {
+          locals.add(sp.local.name);
+        } else if (imported === "sanoma" && SECRET_ENTRIES.has(spec)) {
+          // The runtime's own constructors, matched to its connector as a connector's are.
+          imports.push({ kind: "constructors", source: spec, imported, local: sp.local.name, start: sp.start });
         } else {
-          fail(sp, `a data file imports only \`secret\` from "${spec}": \`import { secret } from "${spec}"\``);
+          const [names, allowed] = SECRET_ENTRIES.has(spec)
+            ? ["`secret` and `sanoma`", `${only}, sanoma`]
+            : [`\`${only}\``, only];
+          fail(sp, `a data file imports only ${names} from "${spec}": \`import { ${allowed} } from "${spec}"\``);
           refused.add(sp.local.name);
         }
       }
@@ -221,8 +278,11 @@ export function readDataFile(
 
   /** Why an import's specifier is not allowed in a data file, or undefined when it is. */
   function whyRefused(spec: string): string | undefined {
-    if (!RELATIVE.test(spec)) return CONSTRUCTORS.test(spec) ? undefined : IMPORTS;
+    if (!RELATIVE.test(spec)) return CONSTRUCTORS.test(spec) || DATA_ENTRIES.has(spec) ? undefined : IMPORTS;
     if (!spec.endsWith(".ts")) return "name the data file with its `.ts` extension";
+    if (join(dirname(filename), spec) === join(root, COLLECTIONS_FILE)) {
+      return "resources/data.ts holds collections, which no resource names; import resources from other data files";
+    }
     if (!inside(root, join(dirname(filename), spec))) {
       return `it reaches outside ${basename(root)}/; import only other data files`;
     }
@@ -241,7 +301,7 @@ export function readDataFile(
       return;
     }
     if (decl.type !== "VariableDeclaration") {
-      fail(s, `${describe(decl)} is not allowed in a data file: ${SHAPE}`);
+      fail(s, `${describe(decl)} is not allowed in a data file: ${shape}`);
       return;
     }
     if (decl.kind !== "const") {
@@ -259,9 +319,16 @@ export function readDataFile(
     }
     const name: string = d.id.name;
     // A second declaration of the name was reported where it is bound.
-    if (exports.some((e) => e.name === name)) return;
+    if (exports.some((e) => e.name === name) || collections.some((c) => c.export === name)) return;
     const init = d.init;
     const callee = init?.type === "CallExpression" ? init.callee : undefined;
+    // A name a refused import binds was reported with the import.
+    const head = callee?.type === "MemberExpression" ? callee.object : callee;
+    if (head?.type === "Identifier" && refused.has(head.name)) return;
+    if (collectionsFile) {
+      readCollection(s, init, name);
+      return;
+    }
     if (
       callee?.type !== "MemberExpression" ||
       callee.computed ||
@@ -276,7 +343,6 @@ export function readDataFile(
     }
     const vendor: string = callee.object.name;
     const type: string = callee.property.name;
-    if (refused.has(vendor)) return;
     if (imports.find((i) => i.local === vendor)?.kind !== "constructors") {
       fail(
         callee.object,
@@ -295,7 +361,51 @@ export function readDataFile(
     }
   }
 
+  /** An `export const` in resources/data.ts: a collection, its declaration plain values `collection()` takes. */
+  function readCollection(s: Node, init: Node | undefined, name: string) {
+    if (
+      init?.type !== "CallExpression" ||
+      init.callee.type !== "Identifier" ||
+      !collectionCalls.has(init.callee.name)
+    ) {
+      fail(init ?? s, `export const ${name} must be a collection: ${COLLECTIONS_ONLY}`);
+      return;
+    }
+    const [arg] = init.arguments;
+    if (init.arguments.length !== 1 || arg.type !== "ObjectExpression") {
+      fail(init, `collection() takes one object literal: ${COLLECTION_CALL}`);
+      return;
+    }
+    const declaration = value(arg) as { [field: string]: DataValue } | undefined;
+    if (declaration === undefined) {
+      // What value() refused it reported; the collection is still declared here, which the
+      // runtime runs, when its name is written out.
+      const named = arg.properties.find(
+        (p: Node) => p.type === "Property" && !p.computed && keyName(p.key) === "name",
+      )?.value;
+      if (named?.type === "Literal" && typeof named.value === "string") {
+        collections.push({ export: name, name: named.value, start: s.start, end: s.end });
+      }
+      return;
+    }
+    if (Object.keys(declaration).some((k) => !DECLARATION_KEYS.has(k)) || namesDeclaration(declaration)) {
+      fail(arg, `collection() takes \`{ name, key, fields, title? }\`, its values written out: ${COLLECTION_CALL}`);
+      return;
+    }
+    try {
+      checkCollection(declaration);
+    } catch (err) {
+      fail(arg, errorMessage(err));
+      return;
+    }
+    collections.push({ export: name, name: declaration.name as string, start: s.start, end: s.end });
+  }
+
   function readDefault(s: Node) {
+    if (collectionsFile) {
+      fail(s, `export default is not allowed in resources/data.ts: ${COLLECTIONS_ONLY}`);
+      return;
+    }
     const list = s.declaration;
     if (list.type !== "ArrayExpression") {
       fail(list, "export default must list this file's resources: `export default [a, b]`");
@@ -373,6 +483,9 @@ export function readDataFile(
       }
       case "CallExpression":
         if (node.callee.type === "Identifier" && secrets.has(node.callee.name)) return readSecret(node);
+        if (node.callee.type === "Identifier" && collectionCalls.has(node.callee.name)) {
+          return refuse(node, `a collection is declared at the top of resources/data.ts: ${COLLECTION_CALL}`);
+        }
         if (node.callee.type === "Identifier" && node.callee.name === "secret" && !bound.has("secret")) {
           return refuse(node, `import secret to name one: \`import { secret } from "sanoma/resources"\``);
         }
@@ -464,9 +577,16 @@ export function readDataFile(
     return undefined;
   }
 
-  return { imports, exports, declared: [...declared], problems };
+  return { imports, exports, collections, declared: collectionsFile ? [] : [...declared], problems };
 }
 
+/** What `collection()` reads of its declaration. */
+const DECLARATION_KEYS: ReadonlySet<string> = new Set(["name", "key", "fields", "title"]);
+
+/** True when a value names a declaration: a collection's declaration is plain values only. */
+const namesDeclaration = (v: DataValue): boolean =>
+  v instanceof Reference || (typeof v === "object" && v !== null && Object.values(v).some(namesDeclaration));
+
 /** A property's name: an identifier's, or a literal's as a string; undefined for any other key. */
 export const keyName = (key: Node): string | undefined =>
   key.type === "Identifier" ? key.name : key.type === "Literal" ? String(key.value) : undefined;