@sanoma-ai/workflows 0.2.0 → 0.4.0

package/src/sdk.ts

@@ -0,0 +1,211 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+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";
+
+// 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
+// augments `sanoma/site`'s `Register`, so it is type-checked only through the sites' generated
+// tsconfig, never the company's root one (Node, no DOM).
+
+/** Where `writeApi` writes, under a company's root. */
+export const API_FILE = join(".sanoma", "api.ts");
+
+const API_NAME_PROBLEM = "A site calls this workflow api.";
+
+/** `describeConfig`'s problem on a workflow whose api name is taken: `taken` says by what. */
+export const apiNameProblem = (api: string, taken: string) => `${API_NAME_PROBLEM}${api}, ${taken}: rename it`;
+
+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
+ * 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`.
+ */
+export function generateApi(description: ConfigDescription): { source: string; problems: string[] } {
+  const problems: string[] = [];
+  const members: string[] = [];
+  for (const wf of description.workflows) {
+    const taken = wf.problems.filter((p) => p.message.startsWith(API_NAME_PROBLEM));
+    if (taken.length) problems.push(...taken.map((p) => problemLine({ file: wf.file, ...p })));
+    else members.push(workflowMember(wf));
+  }
+  // The ops are sorted by id, so by vendor and then resource.
+  const direct = description.ops.filter((op) => op.direct && op.vendor !== DATA_VENDOR);
+  for (const [vendor, ops] of Map.groupBy(direct, (op) => op.vendor)) {
+    const title = description.vendors[vendor]?.title ?? vendor;
+    const resources = [...Map.groupBy(ops, (op) => op.resource)].map(([resource, own]) =>
+      member(undefined, resource, block(own.map(opMember))),
+    );
+    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)}>`),
+    );
+    members.push(member("The company's collections.", DATA_VENDOR, block(data)));
+  }
+  const source = [
+    "// Generated by sanoma from sanoma.config.ts and the connectors it names; do not edit.",
+    "// The types of `api` from sanoma/site: what a site may call, as the person on the page.",
+    'import type { CollectionApi, OpFn, WorkflowFn } from "sanoma/site";',
+    ...description.collections.map(
+      (c) => `\n${jsdoc(`A record of ${c.title ?? c.name}.`)}type ${recordName(c)} = ${typeOf(c.record)};`,
+    ),
+    "",
+    `interface CompanyApi ${block(members)}`,
+    "",
+    'declare module "sanoma/site" {',
+    "  interface Register {",
+    "    api: CompanyApi;",
+    "  }",
+    "}",
+    "",
+    "export {};",
+    "",
+  ].join("\n");
+  return { source, problems };
+}
+
+/**
+ * Writes `<root>/.sanoma/api.ts` (`generateApi`) when its text differs from the file's, so an
+ * editor or a dev server sees no change when there is none; `wrote` says whether it did.
+ */
+export async function writeApi(
+  root: string,
+  description: ConfigDescription,
+): Promise<{ wrote: boolean; file: string }> {
+  const file = join(root, API_FILE);
+  return { wrote: await writeChanged(file, generateApi(description).source), file };
+}
+
+/**
+ * The generated files, each written when its text changed: `.sanoma/api.ts` (`writeApi`) and the
+ * Cedar schema's text, `.sanoma/schema.cedarschema` (`schemaText` of `schemaOf`). `wrote` lists
+ * those written, relative to the root.
+ */
+export async function writeGenerated(
+  root: string,
+  description: ConfigDescription,
+  schema: CedarSchemaJson,
+): Promise<{ wrote: string[] }> {
+  const [api, cedar] = await Promise.all([
+    writeApi(root, description),
+    writeChanged(join(root, SCHEMA_FILE), schemaText(schema)),
+  ]);
+  return { wrote: [...(api.wrote ? [API_FILE] : []), ...(cedar ? [SCHEMA_FILE] : [])] };
+}
+
+/** Writes `text` to `file` unless the file holds it already; true when it wrote. */
+async function writeChanged(file: string, text: string): Promise<boolean> {
+  if ((await readFile(file, "utf8").catch(() => undefined)) === text) return false;
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, text);
+  return true;
+}
+
+const workflowMember = (wf: WorkflowEntry) =>
+  member(
+    `${wf.title ?? wf.name}: the workflow \`${wf.name}\`${wf.builtin ? ", built in" : ""}.`,
+    apiNameOf(wf.name),
+    `WorkflowFn<${typeOf(wf.input)}, unknown>`,
+  );
+
+const opMember = (op: OpEntry) =>
+  member(
+    `${op.description ? `${op.description}\n\n` : ""}\`${op.id}\`, a ${op.effect}.`,
+    op.name,
+    `OpFn<${typeOf(op.input)}, unknown>`,
+  );
+
+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 JSON Schema as a TypeScript type, for the kinds a start form draws (`fieldsOf` in the app):
+ * strings (a date-time among them), numbers, integers, booleans, enums and constants, objects and
+ * arrays, each property with its description, and unions of those, `null` among them (a
+ * collection's date, a date or a date-time; a nullable field); anything else is `unknown`.
+ */
+const typeOf = (schema: unknown): string => union(alternatives(schema));
+
+/** One type of several: `unknown` when any is. */
+function union(types: string[]): string {
+  const distinct = new Set(types);
+  return distinct.has("unknown") ? "unknown" : [...distinct].join(" | ");
+}
+
+/** The types a schema allows, one per alternative. */
+function alternatives(schema: unknown): string[] {
+  if (!isObject(schema)) return ["unknown"];
+  if ("const" in schema && !isObject(schema.const) && !Array.isArray(schema.const)) {
+    return [JSON.stringify(schema.const)];
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length && schema.enum.every((v) => v === null || !isObject(v))) {
+    return schema.enum.map((v) => JSON.stringify(v));
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length) return schema.anyOf.flatMap(alternatives);
+  if (Array.isArray(schema.type) && schema.type.length) {
+    return schema.type.flatMap((type) => alternatives({ ...schema, type }));
+  }
+  switch (schema.type) {
+    case "string":
+      return ["string"];
+    case "number":
+    case "integer":
+      return ["number"];
+    case "boolean":
+      return ["boolean"];
+    case "null":
+      return ["null"];
+    case "array": {
+      const item = typeOf(schema.items);
+      return [new Set(alternatives(schema.items)).size > 1 && item !== "unknown" ? `(${item})[]` : `${item}[]`];
+    }
+    case "object":
+      return [isObject(schema.properties) ? objectType(schema) : "Record<string, unknown>"];
+    default:
+      return ["unknown"];
+  }
+}
+
+function objectType(schema: Schema): string {
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const lines = Object.entries(schema.properties as Schema).map(([name, prop]) => {
+    const doc = isObject(prop) && typeof prop.description === "string" ? jsdoc(prop.description) : "";
+    return `${doc}${key(name)}${required.has(name) ? "" : "?"}: ${typeOf(prop)};`;
+  });
+  // An object that takes other keys too.
+  if (schema.additionalProperties !== undefined && schema.additionalProperties !== false) {
+    lines.push("[key: string]: unknown;");
+  }
+  return block(lines);
+}
+
+/** A property's name, quoted when it is not an identifier. */
+const key = (name: string) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+
+/** A member, under its JSDoc when there is one. */
+const member = (doc: string | undefined, name: string, type: string) =>
+  `${doc ? jsdoc(doc) : ""}${key(name)}: ${type};`;
+
+/** `{ … }` around lines, each indented a level (a nested block's lines with it); `{}` for none. */
+const block = (lines: string[]) =>
+  lines.length ? `{\n${lines.map((l) => l.replace(/^(?=.)/gm, "  ")).join("\n")}\n}` : "{}";
+
+/** A JSDoc comment and the line break after it; `*\/` in the text cannot end it. */
+function jsdoc(text: string): string {
+  const lines = text.replaceAll("*/", "*\\/").split("\n");
+  return lines.length === 1
+    ? `/** ${lines[0]} */\n`
+    : `/**\n${lines.map((l) => ` *${l ? ` ${l}` : ""}`).join("\n")}\n */\n`;
+}

package/src/shared.ts

@@ -1,6 +1,9 @@
+import type { RunSummary } from "./client.ts";
 import type { CredentialStatus } from "./env.ts";
 import type { ApprovalState, Approver, Principal } from "./define.ts";
-import type { ResourceProblem } from "./resources.ts";
+import type { LedgerRecord } from "./ledger.ts";
+import type { Effect } from "./op.ts";
+import type { DeclaredResource, ResourceProblem } from "./resources.ts";
 import type { OutlineNode } from "./outline.ts";
 
 // Types only: resource types as a UI reads them. Erased from the bundle.
@@ -37,8 +40,117 @@ export const DRIFT_WORKFLOW = "drift";
  */
 export const APPLY_WORKFLOW = "apply";
 
-/** The workflows the runtime adds itself, which a config's own may not be named: drift and apply. */
-export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([DRIFT_WORKFLOW, APPLY_WORKFLOW]);
+/**
+ * The vendor of the collections' operations, `data.<collection>.<op>`: a collection's `get`,
+ * `list`, `save` and `delete`. No connector may take it.
+ */
+export const DATA_VENDOR = "data";
+
+/** Every effect an operation may have, each an action group (`effect:<effect>`) of the Cedar schema. */
+export const EFFECTS = ["read", "write", "publish", "send", "money", "access"] as const satisfies readonly Effect[];
+
+/** What a workflow start's action id starts with, as a policy names it: `workflow:<name>`. */
+export const WORKFLOW_ACTION = "workflow:";
+
+/** 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-]*$/;
+
+/**
+ * A record of a collection as `get`, `list` and `save` answer it: its key, the record, and when
+ * and by whom it was last saved (`updatedBy`: a person's id, or `run:<id>` for a run). A record
+ * saved under an older declaration comes back as it is stored, with `issues` saying where the
+ * fields no longer accept it.
+ */
+export type Saved<R = Record<string, unknown>> = {
+  key: string;
+  record: R;
+  /** ISO 8601. */
+  updatedAt: string;
+  updatedBy: string;
+  issues?: { path: (string | number)[]; message: string }[];
+};
+
+/**
+ * What a collection's `list` takes: fields equal to a value or within a range (`where`), the
+ * field to sort by (`-field` for descending; by key otherwise), and how many at most (1 to
+ * 1000, default 100).
+ */
+export type ListQuery<R> = {
+  where?: { [F in keyof R]?: Exclude<R[F], undefined> | Range<Exclude<R[F], undefined>> };
+  order?: (keyof R & string) | `-${keyof R & string}`;
+  limit?: number;
+};
+
+type Range<V> = { gt?: V; gte?: V; lt?: V; lte?: V };
+
+/** How many records a collection's `list` answers: `default` when the query names no `limit`, `max` at most. */
+export const LIST_LIMIT = { default: 100, max: 1000 } as const;
+
+/** The kinds of value a field holds: text, a number, true or false, a date (ISO 8601) or a person's id. */
+export const FIELD_TYPES = ["text", "number", "boolean", "date", "person"] as const;
+
+const COLLECTION_NAME = /^[a-z][a-zA-Z0-9]*$/;
+const FIELD_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const KINDS = `${FIELD_TYPES.map((t) => `"${t}"`).join(", ")}, { type, optional: true } or { enum: [...] }`;
+const isRecord = (v: unknown): v is Record<string, unknown> => typeof v === "object" && v !== null && !Array.isArray(v);
+
+/**
+ * Throws unless `collection()` takes this declaration: the name a lowercase letter then letters
+ * and digits, at least one field, each a type, the type marked optional or an enum of distinct
+ * strings, the key a required text field, the title a string. `collection()` and the reader of
+ * `resources/data.ts` both ask it, so `sanoma check` refuses what the runtime would.
+ */
+export function checkCollection(declaration: { name?: unknown; key?: unknown; fields?: unknown; title?: unknown }) {
+  const { name, key, fields, title } = declaration;
+  const where = `collection("${String(name)}")`;
+  if (typeof name !== "string" || !COLLECTION_NAME.test(name)) {
+    throw new Error(`${where}: the name must be a lowercase letter, then letters and digits, such as "outbound"`);
+  }
+  if (!isRecord(fields) || !Object.keys(fields).length) {
+    throw new Error(`${where}: it needs fields, by name: each one of ${KINDS}`);
+  }
+  for (const [field, kind] of Object.entries(fields)) checkField(where, field, kind);
+  const keyKind: unknown = typeof key === "string" && Object.hasOwn(fields, key) ? fields[key] : undefined;
+  if (!(keyKind === "text" || (isRecord(keyKind) && keyKind.type === "text" && keyKind.optional === undefined))) {
+    throw new Error(`${where}: the key "${String(key)}" must be one of its fields, a required "text" one`);
+  }
+  if (title !== undefined && typeof title !== "string") throw new Error(`${where}: the title must be a string`);
+}
+
+/** Throws unless `kind` is a field `collection()` takes: a type, the type marked optional, or an enum of distinct strings. */
+function checkField(where: string, field: string, kind: unknown): void {
+  const refused = (why: string) => new Error(`${where}: the field "${field}" ${why}`);
+  if (!FIELD_NAME.test(field)) throw refused("must be named with letters, digits and _, not a digit first");
+  const types: readonly unknown[] = FIELD_TYPES;
+  const kinds = `is ${JSON.stringify(kind)}; a field is one of ${KINDS}`;
+  if (typeof kind === "string") {
+    if (!types.includes(kind)) throw refused(kinds);
+    return;
+  }
+  if (!isRecord(kind)) throw refused(kinds);
+  const { type, enum: values, optional, ...rest } = kind;
+  if (Object.keys(rest).length || (type === undefined) === (values === undefined)) throw refused(kinds);
+  if (optional !== undefined && optional !== true) throw refused("may only be marked `optional: true`");
+  if (type !== undefined && !types.includes(type)) throw refused(kinds);
+  if (
+    values !== undefined &&
+    (!Array.isArray(values) ||
+      !values.length ||
+      values.some((v) => typeof v !== "string") ||
+      new Set(values).size < values.length)
+  ) {
+    throw refused("needs an enum of distinct strings, at least one");
+  }
+}
+
+/**
+ * The built-in call workflow's name: one operation that may be called directly (`isDirect`),
+ * made a run when the policy holds a direct call for an approval.
+ */
+export const CALL_WORKFLOW = "call";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply and call. */
+export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([DRIFT_WORKFLOW, APPLY_WORKFLOW, CALL_WORKFLOW]);
 
 /**
  * Every run status, in the order a run may pass through them: waiting on the queue, running,
@@ -56,12 +168,124 @@ export const ENDED_STATUSES = ["finished", "failed", "cancelled"] as const satis
 export const isEnded = (status: RunStatus): boolean => (ENDED_STATUSES as readonly RunStatus[]).includes(status);
 
 /**
- * True when `by` may decide the approval: `by.id` is the approver, or `by.groups` holds the
- * approver group. Pure: everything it reads is already recorded.
+ * Why the run's own actor may not decide an approval on it: separation of duties (`mayDecide`),
+ * while someone else could decide it.
+ */
+export const OWN_CHANGE = "own change";
+
+/** A run as `mayDecide` reads it: who started it, its own actor. */
+type DecidedRun = { actor?: Pick<Principal, "id"> | undefined };
+
+/**
+ * True when `by` may decide the approval on `run`: `by.id` is the approver, or `by.groups` holds
+ * the approver group. The run's own actor is refused only while someone else could decide (separation
+ * of duties): the approver is a group with another declared person in `people` (an agent does not
+ * count). Pure: everything it reads is passed in.
+ */
+export const mayDecide = (
+  approval: Pick<ApprovalState, "approver">,
+  by: Principal,
+  run: DecidedRun,
+  people: readonly PeopleResource[],
+): boolean => refusalOf(approval, by, run, people) === undefined;
+
+/** Why `by` may not decide the approval on `run` (`mayDecide`), naming who may, or `OWN_CHANGE`; undefined when they may. */
+export function refusalOf(
+  { approver }: Pick<ApprovalState, "approver">,
+  by: Principal,
+  run: DecidedRun,
+  people: readonly PeopleResource[],
+): string | undefined {
+  if (typeof approver === "string") {
+    return approver === by.id ? undefined : `${by.id} is not the approver; ${approverLabel(approver)} is`;
+  }
+  if (!by.groups?.includes(approver.group)) return `${by.id} is not in ${approverLabel(approver)}`;
+  if (by.id !== run.actor?.id) return undefined;
+  const someoneElse = personsOf(people).some(
+    ({ id }) => id !== by.id && principalOf(id, people)?.groups?.includes(approver.group),
+  );
+  return someoneElse ? OWN_CHANGE : undefined;
+}
+
+/** A declared resource as the people functions read it: only the runtime's people types count. */
+export type PeopleResource = Pick<DeclaredResource, "vendor" | "type" | "desired">;
+
+/** The group every agent is in, the runtime's own among them: no data file declares it. */
+export const AGENTS = "agents";
+
+/** The runtime's own agents (scenarios, the host check, scheduled runs), declared whether a data file names them or not. */
+export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", "schedule"];
+
+/** The declared resources of one of the runtime's people types, by `desired`. */
+const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>
+  resources.flatMap((r) => (r.vendor === "sanoma" && r.type === type ? [r.desired as T] : []));
+
+type PersonFields = { id: string; name?: string; email?: string; github?: string };
+type AgentFields = { id: string; onBehalfOf?: string };
+type GroupFields = { name: string; members: string[] };
+
+/** The groups a policy may name and a principal may be in: the declared ones and `agents`, sorted. */
+export const groupNamesOf = (resources: readonly PeopleResource[]): string[] =>
+  [...new Set([...peopleOfType<GroupFields>(resources, "group").map((g) => g.name), AGENTS])].toSorted();
+
+/** The declared people (`sanoma.person`), in the order declared: not agents, who never sign in. */
+export const personsOf = (resources: readonly PeopleResource[]): PersonFields[] =>
+  peopleOfType<PersonFields>(resources, "person");
+
+/** The ids of the declared people and agents (not the runtime's own). */
+export const principalIdsOf = (resources: readonly PeopleResource[]): string[] =>
+  [...personsOf(resources), ...peopleOfType<AgentFields>(resources, "agent")].map((p) => p.id);
+
+/** True when the data files declare a person, agent or group: then only a declared principal is admitted. */
+export const declaresPeople = (resources: readonly PeopleResource[]): boolean =>
+  resources.some((r) => r.vendor === "sanoma");
+
+/**
+ * The principal a declared person or agent (or one of the runtime's own agents) acts as, read
+ * from the data files' resources: its id, every group that lists it (and `agents` for an agent),
+ * sorted, and an agent's `onBehalfOf`. Undefined for an id nobody declares.
  */
-export function mayDecide(approval: Pick<ApprovalState, "approver">, by: Principal): boolean {
-  const { approver } = approval;
-  return typeof approver === "string" ? approver === by.id : (by.groups?.includes(approver.group) ?? false);
+export function principalOf(id: string, resources: readonly PeopleResource[]): Principal | undefined {
+  const agent = peopleOfType<AgentFields>(resources, "agent").find((a) => a.id === id);
+  const isAgent = agent !== undefined || RUNTIME_AGENTS.includes(id);
+  if (!isAgent && !peopleOfType<PersonFields>(resources, "person").some((p) => p.id === id)) return undefined;
+  const groups = peopleOfType<GroupFields>(resources, "group")
+    .filter((g) => g.members.includes(id))
+    .map((g) => g.name);
+  return {
+    id,
+    groups: [...new Set(isAgent ? [...groups, AGENTS] : groups)].toSorted(),
+    ...(agent?.onBehalfOf !== undefined && { onBehalfOf: agent.onBehalfOf }),
+  };
+}
+
+/**
+ * Who `name` is as an approver: a declared group's name (or `agents`) as `{ group }`, else a
+ * declared person's or agent's id; undefined when it is neither.
+ */
+export function approverOf(name: string, resources: readonly PeopleResource[]): Approver | undefined {
+  if (groupNamesOf(resources).includes(name)) return { group: name };
+  return principalOf(name, resources) && name;
+}
+
+/** True for two strings the same but for case: an email or a GitHub login. */
+const same = (a: string | undefined, b: string | undefined) =>
+  a !== undefined && b !== undefined && a.toLowerCase() === b.toLowerCase();
+
+/**
+ * The id of the declared person a sign-in vouches for, or undefined: by email first, then by
+ * GitHub login (each ignoring case), then by id. Never an agent's: agents do not sign in.
+ */
+export function personOf(
+  login: { email?: string; github?: string; id?: string },
+  resources: readonly PeopleResource[],
+): string | undefined {
+  const people = personsOf(resources);
+  return (
+    people.find((p) => same(p.email, login.email)) ??
+    people.find((p) => same(p.github, login.github)) ??
+    people.find((p) => login.id !== undefined && p.id === login.id)
+  )?.id;
 }
 
 /** Who may decide, as text: the person's id, or "group <name>". */
@@ -124,3 +348,42 @@ export const isLoopback = (host: string) =>
 /** Whether a driver's environment variable lets it run: set, or unset and optional. */
 export const credentialReady = ({ status, optional }: CredentialStatus): boolean =>
   status === "set" || (status === "missing" && optional);
+
+/**
+ * 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
+ * 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());
+
+/**
+ * A workflow as a site's `api` has it (`api.<apiNameOf(name)>`), started as the person on the
+ * page. Called, it starts a run and resolves with its output once the run ends, or rejects with
+ * its error; `start` gives the run's id at once, and the rest read runs of this workflow.
+ */
+export interface WorkflowFn<I, O> {
+  (input: I): Promise<O>;
+  /** Starts a run with this input, and answers with its id. */
+  start(input: I): Promise<{ runId: string }>;
+  /** The run's output once it ends, or its error; `run_running` when it has not ended within `waitMs` (at most 20 s). */
+  result(runId: string, waitMs?: number): Promise<O>;
+  /** The newest finished run's output, and when it finished (ms since the epoch); null when none has. */
+  latest(): Promise<{ runId: string; output: O; at: number } | null>;
+  /** Its latest runs, newest first. */
+  runs(query?: { limit?: number }): Promise<RunSummary[]>;
+  /** The run's approvals, decided and waiting. */
+  approvals(runId: string): Promise<ApprovalState[]>;
+  /** The run's ledger records, in order. */
+  ledger(runId: string): Promise<LedgerRecord[]>;
+}
+
+/** An operation a site may call directly (a read, or a collection's write), as the person on the page. */
+export type OpFn<I, O> = (input: I) => Promise<O>;
+
+/** A collection as a site's `api.data.<name>` has it: its four operations (`Saved`, `ListQuery`). */
+export interface CollectionApi<R> {
+  get: OpFn<{ key: string }, Saved<R> | null>;
+  list(query?: ListQuery<R>): Promise<Saved<R>[]>;
+  save: OpFn<{ record: R }, Saved<R>>;
+  delete: OpFn<{ key: string }, { deleted: boolean }>;
+}