@sanoma-ai/workflows 0.2.0 → 0.4.1

package/src/db.ts

@@ -1,11 +1,13 @@
 import { DBOS, DBOSClient } from "@dbos-inc/dbos-sdk";
-import { Client, Pool } from "pg";
+import { setTimeout as delay } from "node:timers/promises";
+import { Client, escapeIdentifier, Pool } from "pg";
 import { warn } from "./log.ts";
 import { errorMessage } from "./shared.ts";
 
-// The runtime's own tables live in the config's database, beside DBOS's: the credentials and the
-// ledger. What they share is here: the one preparation of a database, a pool that opens once it
-// is prepared and survives a dropped connection, and a table creation two processes may race.
+// The runtime's own tables live in the config's database, beside DBOS's: the credentials, the
+// ledger and the collections' records. What they share is here: the one preparation of a
+// database, a pool that opens once it is prepared and survives a dropped connection, and a table
+// creation two processes may race.
 
 /** A connection or a pool: what the queries take. */
 export type Db = Pick<Pool | Client, "query">;
@@ -14,6 +16,8 @@ export type Db = Pick<Pool | Client, "query">;
 export const CREDENTIALS_TABLE = "sanoma_credentials";
 /** Where the Postgres ledger keeps its records. */
 export const LEDGER_TABLE = "sanoma_ledger";
+/** Where the collections keep their records (`collection.ts`): one row per collection and key, the record as JSON. */
+export const DATA_TABLE = "sanoma_data";
 
 /** The runtime's tables, each with the word the messages name it by. */
 const TABLES: readonly [what: string, ddl: string][] = [
@@ -30,13 +34,23 @@ const TABLES: readonly [what: string, ddl: string][] = [
       `run_id text NOT NULL, seq integer NOT NULL, record jsonb NOT NULL); ` +
       `CREATE INDEX IF NOT EXISTS ${LEDGER_TABLE}_run_seq ON ${LEDGER_TABLE} (run_id, seq, n)`,
   ],
+  [
+    "data",
+    `CREATE TABLE IF NOT EXISTS ${DATA_TABLE} (collection text NOT NULL, key text NOT NULL, record jsonb NOT NULL, ` +
+      "updated_at timestamptz NOT NULL DEFAULT now(), updated_by text NOT NULL, PRIMARY KEY (collection, key))",
+  ],
 ];
 
 /** The Postgres error code of `err`, or an empty string when it has none. */
 export const pgCode = (err: unknown): string => (err as { code?: unknown } | null)?.code?.toString() ?? "";
 
-/** Postgres's codes for a row type or a table another process made first. */
-const MADE_ALREADY = new Set(["23505", "42P07"]);
+/**
+ * Postgres's codes for a database, a row type or a table another process made first. Two racing
+ * `CREATE TABLE IF NOT EXISTS` both pass the check, and the loser fails on the table's row type in
+ * `pg_type`: as a unique violation (23505), or as a duplicate object (42710, "type ... already
+ * exists"). Two racing `CREATE DATABASE` fail as 42P04, or on `pg_database` as 23505.
+ */
+const MADE_ALREADY = new Set(["23505", "42P04", "42P07", "42710"]);
 
 /** True for the failure of a create that another process won: what was to be made is there. */
 export const madeAlready = (err: unknown): boolean => MADE_ALREADY.has(pgCode(err));
@@ -82,6 +96,9 @@ const IDLE_IN_TRANSACTION_TIMEOUT = "60s";
 /** Postgres's code for a statement the role lacks the privilege for. */
 const INSUFFICIENT_PRIVILEGE = "42501";
 
+/** Postgres's code for a database that is not there (`invalid_catalog_name`). */
+const NO_DATABASE = "3D000";
+
 /** A pool opened on first use, once its database is prepared, and ended by `close`. */
 export interface LazyPool {
   db(): Promise<Pool>;
@@ -125,9 +142,9 @@ const prepared = new Map<string, Promise<void>>();
  * Makes the database at `databaseUrl` ready for the runtime, once per process and URL: the
  * database itself and DBOS's tables when they are not there yet (as a worker's launch makes
  * them; credentials may be set, and a ledger read, before any worker has run), then the
- * credentials and ledger tables, and its idle-transaction timeout (`guardIdleTransactions`).
- * Two processes preparing one database both succeed. A
- * preparation that fails is forgotten, so the next call tries again.
+ * credentials, ledger and data tables, and its idle-transaction timeout (`guardIdleTransactions`).
+ * Two processes preparing one database both succeed: the second waits for the first
+ * (`lockPreparation`). A preparation that fails is forgotten, so the next call tries again.
  */
 export function prepareDatabase(databaseUrl: string): Promise<void> {
   let preparing = prepared.get(databaseUrl);
@@ -141,33 +158,86 @@ export function prepareDatabase(databaseUrl: string): Promise<void> {
   return preparing;
 }
 
+/** The error a preparation fails with, its cause `err`. */
+const unprepared = (err: unknown): Error =>
+  new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+
 async function prepare(databaseUrl: string): Promise<void> {
+  const conn = await lockPreparation(databaseUrl).catch((err: unknown) => {
+    throw unprepared(err);
+  });
   try {
-    await DBOS.migrate(databaseUrl);
+    await DBOS.migrate(databaseUrl).catch((err: unknown) => {
+      // A DBOS table made meanwhile by a release from before the lock, mid-upgrade: it is there.
+      if (!madeAlready(err)) throw unprepared(err);
+    });
+    for (const [what, ddl] of TABLES) await createTable(conn, ddl, what);
+    await guardIdleTransactions(conn);
+  } finally {
+    // Ending the session releases the lock; a failure to end it must not hide the preparation's.
+    await conn.end().catch(() => undefined);
+  }
+}
+
+/**
+ * A connection to the database at `databaseUrl` (made first when missing) holding the
+ * preparation's session lock until it ends, so a second process waits, then finds everything
+ * made. Racing `DBOS.migrate`s lose to each other in many ways (40P01, XX000), so the race is
+ * prevented rather than each loss forgiven. The lock is polled, never waited for by a blocked
+ * statement: `CREATE INDEX CONCURRENTLY` waits on that statement's snapshot, a deadlock Postgres
+ * cannot see (the lock's holder is this connection, not the migration's).
+ */
+async function lockPreparation(databaseUrl: string): Promise<Client> {
+  const conn = await connect(databaseUrl).catch(async (err: unknown) => {
+    if (pgCode(err) !== NO_DATABASE) throw err;
+    await createDatabase(databaseUrl);
+    return connect(databaseUrl);
+  });
+  try {
+    const ask = "SELECT pg_try_advisory_lock(hashtext('sanoma.prepareDatabase')) AS locked";
+    while (!(await conn.query<{ locked: boolean }>(ask)).rows[0]!.locked) await delay(50);
+    return conn;
   } catch (err) {
-    // The database, or a DBOS table, made by another process meanwhile: it is there.
-    if (!madeAlready(err)) throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
+    await conn.end().catch(() => undefined);
+    throw err;
   }
-  const conn = new Client({ connectionString: databaseUrl });
+}
+
+async function connect(databaseUrl: string): Promise<Client> {
+  const conn = new Client({ connectionString: databaseUrl, connectionTimeoutMillis: 10_000 });
+  // An error nobody listens for ends the process; the query in flight fails with it.
+  conn.on("error", (err) => warn(`a preparation connection failed: ${errorMessage(err)}`));
   await conn.connect();
+  return conn;
+}
+
+/**
+ * Makes the database at `databaseUrl` through its server's `postgres` database, as `DBOS.migrate`
+ * would. Another process making it first is no failure.
+ */
+async function createDatabase(databaseUrl: string): Promise<void> {
+  const url = new URL(databaseUrl);
+  const name = decodeURI(url.pathname.slice(1));
+  url.pathname = "/postgres";
+  const admin = await connect(url.toString());
   try {
-    for (const [what, ddl] of TABLES) await createTable(conn, ddl, what);
-    await guardIdleTransactions(conn);
+    await admin.query(`CREATE DATABASE ${escapeIdentifier(name)}`);
+  } catch (err) {
+    if (!madeAlready(err)) throw err;
   } finally {
-    await conn.end();
+    await admin.end();
   }
 }
 
 /**
  * Sets `idle_in_transaction_session_timeout` on the database, for each session that starts after,
  * as DBOS would per connection (`DBOS_DATABASE_OPTIONS`), unless the server, the role or the
- * database sets it already. One process at a time (an advisory lock), so two preparing at once
- * both succeed. A role that may not alter the database leaves it, quietly: its administrator decides.
+ * database sets it already. `db` holds the preparation's lock, so one process at a time. A role
+ * that may not alter the database leaves it, quietly: its administrator decides.
  */
 async function guardIdleTransactions(db: Db): Promise<void> {
   try {
     await db.query(`DO $$ BEGIN
-      PERFORM pg_advisory_xact_lock(hashtext('sanoma.idle_in_transaction_session_timeout'));
       IF current_setting('idle_in_transaction_session_timeout') = '0' AND NOT EXISTS (
         SELECT FROM pg_db_role_setting s JOIN pg_database d ON d.oid = s.setdatabase, unnest(s.setconfig) c
         WHERE d.datname = current_database() AND s.setrole = 0 AND c LIKE 'idle_in_transaction_session_timeout=%'
@@ -177,9 +247,7 @@ async function guardIdleTransactions(db: Db): Promise<void> {
       END IF;
     END $$`);
   } catch (err) {
-    if (pgCode(err) !== INSUFFICIENT_PRIVILEGE) {
-      throw new Error(`could not prepare the database: ${errorMessage(err)}`, { cause: err });
-    }
+    if (pgCode(err) !== INSUFFICIENT_PRIVILEGE) throw unprepared(err);
   }
 }
 

package/src/define.ts

@@ -2,20 +2,24 @@ import { fileURLToPath } from "node:url";
 import { getCallSites } from "node:util";
 import { z } from "zod";
 import { isOp, type Op } from "./op.ts";
-import { approverLabel } from "./shared.ts";
 
 /**
- * Who is acting: the person or service that starts a run or decides an approval. `id` is
- * whatever the deployment identifies people by; `groups` are the roles it vouches for.
+ * Who is acting: the person or agent that starts a run, calls an operation or decides an
+ * approval. With people declared (`sanoma.person`, `sanoma.agent`, `sanoma.group` in data files),
+ * a principal is a declared one, its `groups` every group that lists it; an agent is in the group
+ * `agents`, and `onBehalfOf` names the person it acts for.
  */
 export interface Principal {
   id: string;
   groups?: string[];
+  /** For an agent: the id of the person whose instruction it carries. */
+  onBehalfOf?: string;
 }
 
 export const Principal: z.ZodType<Principal> = z.object({
   id: z.string().regex(/\S/, "id must not be blank"),
   groups: z.array(z.string()).optional(),
+  onBehalfOf: z.string().regex(/\S/, "onBehalfOf must not be blank").optional(),
 });
 
 export type Builtin = "approval" | "sleep" | "all";
@@ -29,12 +33,6 @@ export const Approver: z.ZodType<Approver> = z.union(
   { error: 'needs an approver: a name, or { group: "name" }' },
 );
 
-/** Why `by` may not decide the approval, naming who may. */
-export const notApprover = ({ approver }: Pick<ApprovalState, "approver">, by: Principal): string =>
-  typeof approver === "string"
-    ? `${by.id} is not the approver; ${approverLabel(approver)} is`
-    : `${by.id} is not in ${approverLabel(approver)}`;
-
 /** True when the two name the same approver: the same id, or the same group. */
 export const sameApprover = (a: Approver, b: Approver): boolean =>
   typeof a === "string" || typeof b === "string" ? a === b : a.group === b.group;
@@ -92,6 +90,8 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
   opSeq?: number;
   /** For a policy request: the held call's input. */
   input?: unknown;
+  /** For a policy request: the policies that held the call, by id, when the policy names them. */
+  reasons?: string[];
   status: "pending" | "approved" | "rejected";
   requestedAt: number;
   decidedBy?: string;
@@ -99,6 +99,8 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
   note?: string;
   /** The `id` of the decision message the run decided with, when it had one. */
   decidedWith?: string;
+  /** Set when the run's own actor decided it: nobody else could (`mayDecide`). */
+  alone?: true;
   /**
    * Messages that were ignored: decisions sent by someone who may not decide the approval,
    * and messages that were not a decision. `by` is the sender, when the message named one, and
@@ -193,7 +195,10 @@ interface AllCtx {
 }
 
 interface BaseCtx {
-  /** The current time, recorded so replays see the same value. Use instead of `Date.now()`. */
+  /**
+   * The current time in epoch milliseconds, recorded so replays see the same value. Use instead
+   * of `Date.now()`, which the lint refuses; a date is `new Date(await ctx.now()).toISOString()`.
+   */
   now(): Promise<number>;
   readonly runId: string;
 }

package/src/describe.ts

@@ -1,29 +1,56 @@
 import type { z } from "zod";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
-import { resolveConfig, type SanomaConfig } from "./config.ts";
+import { type Field, recordSchemaOf } from "./collection.ts";
+import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
 import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
+import { isDirect } from "./direct.ts";
 import { lintWorkflow } from "./lint.ts";
 import { type Effect, VENDOR, type VendorInfo } from "./op.ts";
 import { type Outline, outlineWithSource } from "./outline.ts";
 import { allowAll, policyOpOf } from "./policy.ts";
 import { type ResourceFields, resourceTypesOf } from "./resource.ts";
-import { type DataFiles, type DeclaredResource, readDataFiles, type ResourceProblem } from "./resources.ts";
-import { BUILT_IN_WORKFLOWS } from "./shared.ts";
+import {
+  type DataFiles,
+  type DeclaredCollection,
+  type DeclaredResource,
+  readDataFiles,
+  type ResourceProblem,
+} from "./resources.ts";
+import { apiNameProblem } from "./sdk.ts";
+import { apiNameOf, BUILT_IN_WORKFLOWS, DATA_VENDOR, problemLine } from "./shared.ts";
+import { readSites, type SiteEntry } from "./sites.ts";
 
 // `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
 export { outlineWorkflow, type Outline, type OutlineNode, type Span } from "./outline.ts";
 // The reader parses data files with oxc-parser too.
 export type { LintProblem } from "./ast.ts";
 export {
+  admit,
   readDataFiles,
-  readResources,
+  readPeople,
   type DataFiles,
+  type DeclaredCollection,
+  type DeclaredPeople,
   type DeclaredResource,
   type ResourceProblem,
 } from "./resources.ts";
 // The writer: setting a resource's fields in its data file, and rendering a new one.
 export { formatOptions, renderDataFile, setFields, type DataFileContent } from "./writer.ts";
 export { Reference, type DataValue } from "./datafile.ts";
+
+/**
+ * The resources the config's data files declare, read without importing or running them; throws
+ * one error listing every problem, each at `file:line:column`, for a test or CI to fail on.
+ * `describeConfig` lists the same, with the problems beside them instead.
+ */
+export function readResources(config: SanomaConfig): DeclaredResource[] {
+  const { resources, problems } = readDataFiles(rootOf(config), connectorsOf(config));
+  if (problems.length) {
+    const lines = problems.map((p) => `  ${problemLine(p)}`);
+    throw new Error(`The resources' data files have problems:\n${lines.join("\n")}`);
+  }
+  return resources;
+}
 export {
   LOCKFILE,
   readLockfile,
@@ -34,6 +61,12 @@ export {
   type Bindings,
   type Rebind,
 } from "./lockfile.ts";
+// What the sites call, read from their source: a workflow's Used by.
+export { readSites, type SiteCall, type SiteEntry } 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.
+export { SCHEMA_FILE, schemaOf, schemaText, type CedarSchemaJson } from "./schema.ts";
 // The apply workflow's plan and report, which the app renders.
 export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 
@@ -43,7 +76,7 @@ export interface WorkflowEntry {
   title?: string;
   trigger: "manual";
   /**
-   * Set for a workflow the runtime adds itself, `drift` or `apply`, rather than the config: a label. It
+   * Set for a workflow the runtime adds itself, `drift`, `apply` or `call`, rather than the config: a label. It
    * starts like any other.
    */
   builtin?: true;
@@ -84,6 +117,8 @@ export interface OpEntry {
   description?: string;
   /** How a scenario's steps name it: Cucumber expressions over its input's fields. */
   phrases?: { given?: string; expect?: string };
+  /** Whether it may be called directly, outside a run (`isDirect`): the one rule, read here, never derived again. */
+  direct: boolean;
   /** What a call sends, as JSON Schema (`io: "input"`: fields with defaults are optional). */
   input: Record<string, unknown>;
   /** What a call returns once its schema has parsed the vendor's reply (`io: "output"`). */
@@ -124,6 +159,22 @@ export interface ResourceTypeEntry {
   ops: string[];
 }
 
+/** A collection the config declares (`collection()`). */
+export interface CollectionEntry {
+  name: string;
+  title?: string;
+  /** The field each record is found by. */
+  key: string;
+  /** Its fields as declared. */
+  fields: Record<string, Field>;
+  /** What `save` accepts, as JSON Schema, with `$id` `sanoma:collection/<name>`. */
+  record: Record<string, unknown>;
+  /** Its operations' ids: `data.<name>.get`, `.list`, `.save` and `.delete`. */
+  ops: string[];
+  /** Where `resources/data.ts` declares it, read as the data files are; absent for one declared elsewhere. */
+  declared?: DeclaredCollection;
+}
+
 /**
  * A plain-JSON description of what a config can do: its workflows, the operations they call,
  * and whether a policy gates them. The app server builds it from the config and sends it to the
@@ -139,6 +190,8 @@ export interface ConfigDescription {
   vendors: Record<string, VendorEntry>;
   /** The resource types the connectors declare, by `id`. */
   resourceTypes: ResourceTypeEntry[];
+  /** The config's collections, by name. */
+  collections: CollectionEntry[];
   /**
    * The resources the data files under `resources/` declare, by file and then in file order,
    * less any with a problem and any that names one.
@@ -148,8 +201,16 @@ export interface ConfigDescription {
   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. */
   problems: ResourceProblem[];
-  /** `defined` is false for `allowAll`. */
-  policy: { defined: boolean; version?: string };
+  /**
+   * `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.
+   */
+  policy: { defined: boolean; version?: string; problems?: string[] };
+  /**
+   * The sites under `sites/`, by name, with what each calls (`readSites`), and its calls to what
+   * the config does not have as its problems; none when the root has no `sites/`.
+   */
+  sites: SiteEntry[];
 }
 
 /**
@@ -157,7 +218,8 @@ export interface ConfigDescription {
  * credentials (`SanomaClient.credentials` gives their statuses) and what is wrong in a workflow's
  * file, which the worker refuses when it reads the outline: that is data, on each workflow's
  * entry, as the data files' problems are, `problems`, beside the resources read without any.
- * Each workflow's file is read and parsed once, however many workflows it defines.
+ * Each workflow's file is read and parsed once, however many workflows it defines. The sites'
+ * code is read too (`readSites`): what each calls, and its calls to what the config lacks as its problems.
  */
 export function describeConfig(config: SanomaConfig): ConfigDescription {
   const resolved = resolveConfig(config);
@@ -168,7 +230,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     const { id, info } = connector[VENDOR];
     vendors[id] ??= vendorEntry(id, info, resolved.fakes.has(id));
   }
-  const resources = resourceTypesOf(config.connectors);
+  const resources = resourceTypesOf(connectorsOf(config));
   // Each resource type's state is described once, on its entry, and referenced from its operations.
   const refs = new Map<z.ZodType, string>([...resources].map(([id, r]) => [r.schema, resourceTypeUri(id)]));
   const resourceTypes: ResourceTypeEntry[] = [...resources]
@@ -186,11 +248,26 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     }))
     .toSorted((a, b) => a.id.localeCompare(b.id));
 
+  const dataFiles = readDataFiles(resolved.root, connectorsOf(config), resources);
+  const declared = new Map(dataFiles.collections.map((d) => [d.name, d]));
+  const collections: CollectionEntry[] = [...resolved.collections.values()]
+    .map((c) => ({
+      name: c.name,
+      ...(c.title !== undefined && { title: c.title }),
+      key: c.key,
+      fields: c.fields,
+      record: { $id: `sanoma:collection/${c.name}`, ...toJsonSchema(recordSchemaOf(c), `${c.name} record`, "input") },
+      ops: [c.get, c.list, c.save, c.delete].map((op) => op.id),
+      ...(declared.has(c.name) && { declared: declared.get(c.name) }),
+    }))
+    .toSorted((a, b) => a.name.localeCompare(b.name));
+
   const ops: OpEntry[] = [...resolved.ops.values()].map((op) => ({
     ...policyOpOf(op),
     idempotent: op.idempotent,
     description: op.description,
     ...(op.phrases && { phrases: op.phrases }),
+    direct: isDirect(op, resolved.types),
     input: toJsonSchema(op.input, `${op.id} input`, "input", refs),
     output: toJsonSchema(op.output, `${op.id} output`, "output", refs),
   }));
@@ -225,7 +302,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     };
   });
   workflows.sort((a, b) => a.name.localeCompare(b.name));
-  const dataFiles = readDataFiles(resolved.root, config.connectors, resources);
+  addApiNameProblems(workflows, new Set(ops.map((op) => op.vendor)));
 
   return {
     appName: resolved.appName,
@@ -234,16 +311,42 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     ops,
     vendors,
     resourceTypes,
+    collections,
     resources: dataFiles.resources,
     orphans: dataFiles.orphans,
     problems: dataFiles.problems,
     policy: {
       defined: resolved.policy !== allowAll,
       ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
+      ...(resolved.policyProblems.length ? { problems: resolved.policyProblems } : {}),
     },
+    sites: readSites(resolved.root, { workflows, collections, ops }),
   };
 }
 
+/**
+ * A site's `api` names each workflow `apiNameOf(name)` beside the vendors' operations and the
+ * collections (`api.data`), so a workflow whose name comes out as another's, a vendor's id or
+ * `data` is a problem, at 1:1 of its file. A built-in is never the one renamed.
+ */
+function addApiNameProblems(workflows: WorkflowEntry[], vendors: ReadonlySet<string>) {
+  for (const wf of workflows) {
+    if (wf.builtin) continue;
+    const api = apiNameOf(wf.name);
+    const others = workflows.filter((other) => other !== wf && apiNameOf(other.name) === api);
+    const taken = others.length
+      ? `as workflow ${others.map((other) => `"${other.name}"`).join(" and ")} is`
+      : api === DATA_VENDOR
+        ? "which is the collections'"
+        : vendors.has(api)
+          ? `which is the vendor ${api}'s operations`
+          : api === "then"
+            ? "which a promise would take for its own"
+            : undefined;
+    if (taken) wf.problems.push({ line: 1, column: 1, message: apiNameProblem(api, taken) });
+  }
+}
+
 /** `fn`, called once per argument for as long as the returned function lives. */
 function memoised<A, R>(fn: (arg: A) => R): (arg: A) => R {
   const seen = new Map<A, R>();

package/src/direct.ts

@@ -0,0 +1,15 @@
+import type { Op } from "./op.ts";
+import { isResourceOp } from "./resource.ts";
+import { 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.
+ * 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">,
+  types: ReadonlyMap<string, unknown>,
+): boolean => op.vendor === DATA_VENDOR || (op.effect === "read" && op.vendor !== "sanoma" && !isResourceOp(op, types));

package/src/errors.ts

@@ -1,7 +1,7 @@
 import { Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import type { z } from "zod";
 import type { Principal } from "./define.ts";
-import { errorMessage } from "./shared.ts";
+import { CALL_WORKFLOW, errorMessage } from "./shared.ts";
 
 const CODES = [
   "policy_denied",
@@ -15,6 +15,8 @@ const CODES = [
   "run_ended",
   "run_running",
   "call_not_in_outline",
+  "approval_pending",
+  "not_admitted",
 ] as const;
 
 /**
@@ -79,6 +81,39 @@ export class PolicyDeniedError extends SanomaError {
   }
 }
 
+/**
+ * Thrown by a direct call (`SanomaClient.call`) the policy holds for an approval: the call is now
+ * run `runId` of the built-in `call` workflow, which makes it once approved.
+ */
+export class ApprovalPendingError extends SanomaError {
+  constructor(op: string, runId: string) {
+    super("approval_pending", `${op} needs an approval: it waits in run ${runId}`, {
+      runId,
+      workflow: CALL_WORKFLOW,
+      op,
+    });
+    this.name = "ApprovalPendingError";
+  }
+}
+
+/**
+ * Thrown when the data files declare people (`sanoma.person`, in `resources/people.ts` by
+ * convention) and not this principal's id: nothing is started, called or decided.
+ */
+export class NotAdmittedError extends SanomaError {
+  /** `problems`: what is wrong in the people's files, while nobody is admitted. */
+  constructor(id: string, problems: readonly string[] = []) {
+    super(
+      "not_admitted",
+      problems.length
+        ? `${id} cannot be admitted while the people's files have problems: ${problems.join("; ")}`
+        : `${id} is not declared in resources/people.ts`,
+      { principal: id, ...(problems.length && { problems }) },
+    );
+    this.name = "NotAdmittedError";
+  }
+}
+
 /** Thrown into the run when an approver rejects. The run fails with it. */
 export class RejectedError extends SanomaError {
   /**

package/src/expectations.ts

@@ -83,9 +83,13 @@ const words = (d: RecordedDecision) =>
 /** What the policy decided for the calls, each decision once: `allowed and held for finance`. */
 const decisions = (calls: CallRecord[]) => [...new Set(calls.map((r) => words(r.decision)))].join(" and ");
 
-/** True when `who` names the approver: a person by id, or a group by its name. */
-const isApprover = (approver: Approver, who: string) =>
-  typeof approver === "string" ? approver === who : approver.group === who;
+/** True when `who` names the approver: a person by id, or a group by its name; `{ group }` the group alone. */
+const isApprover = (approver: Approver, who: Approver) =>
+  typeof who !== "string"
+    ? typeof approver !== "string" && approver.group === who.group
+    : typeof approver === "string"
+      ? approver === who
+      : approver.group === who;
 
 /** How a drift report found a resource, as words: `clean`, `gone`, `drifted in has_wiki, topics`. */
 const found = (r: DriftResult) =>
@@ -144,9 +148,9 @@ function applyDetail(
  * Why an expectation of the generic steps does not hold against a run's ledger records, or
  * undefined when it does. A call is an `op.called` record without an `error`; one with an error
  * (a policy denial, a rejected approval, a vendor's final failure) was attempted, not made. An
- * operation `was denied` when the policy's decision on some call to it is `deny`, and `was held
- * for` an approver when an approval for that approver holds it: one the policy asked for on its
- * call, or one that `covers` it. A drift or apply expectation reads the report a finished run
+ * operation `was denied` when the policy's decision on some call to it is `deny` (for the `reason`
+ * expected, when there is one), and `was held for` an approver (a group alone, as `{ group }`) when
+ * an approval for that approver holds it: one the policy asked for on its call, or one that `covers` it. A drift or apply expectation reads the report a finished run
  * of it returned. A step named in the workflow's outline is read by the `name` its records carry
  * (its calls made, and `waitsOf`); a record written before steps had names has none.
  */
@@ -158,13 +162,18 @@ export function detailOf(e: CoreExpectation, records: readonly LedgerRecord[]):
   if ("decision" in e) {
     const tries = callsTo(e.op);
     if (e.decision === "denied") {
-      if (tries.some((r) => r.decision.kind === "deny")) return undefined;
+      const denials = tries.flatMap(({ decision: d }) => (d.kind === "deny" ? [d.reason] : []));
+      if (denials.some((reason) => e.reason === undefined || reason === e.reason)) return undefined;
+      if (denials.length) {
+        const said = [...new Set(denials)].map((reason) => JSON.stringify(reason)).join(" and ");
+        return `${e.op} was denied with ${said}, not ${JSON.stringify(e.reason)}`;
+      }
       return tries.length ? `${e.op} was ${decisions(tries)}, not denied` : `no call to ${e.op}`;
     }
     const holds = records.filter(isRequest).filter((r) => r.op === e.op || r.covers.includes(e.op));
     if (holds.some((r) => isApprover(r.approver, e.approver))) return undefined;
     return holds.length
-      ? `${e.op} was held for ${[...new Set(holds.map((r) => approverLabel(r.approver)))].join(" and ")}, not ${e.approver}`
+      ? `${e.op} was held for ${[...new Set(holds.map((r) => approverLabel(r.approver)))].join(" and ")}, not ${approverLabel(e.approver)}`
       : tries.length
         ? `${e.op} was ${decisions(tries)}, not held`
         : `no call to ${e.op}`;

package/src/fill.ts

@@ -19,6 +19,21 @@ export function fill(schema: z.ZodType, given: Record<string, unknown>): unknown
 export const shapeOf = (schema: z.ZodType): Record<string, z.ZodType> =>
   schema instanceof z.ZodObject ? schema.shape : {};
 
+/** The schema of a field an object schema does not name, when it takes such fields (`z.looseObject`, `.catchall`). */
+export function restOf(schema: z.ZodType): z.ZodType | undefined {
+  const rest = schema instanceof z.ZodObject ? (schema.def.catchall as z.ZodType | undefined) : undefined;
+  return rest instanceof z.ZodNever ? undefined : rest;
+}
+
+/** The object schema under `schema`'s optional, nullable and default wrappers, if it is one. */
+export function objectUnder(schema: z.ZodType): z.ZodObject | undefined {
+  let inner = schema;
+  while (inner instanceof z.ZodOptional || inner instanceof z.ZodNullable || inner instanceof z.ZodDefault) {
+    inner = inner.unwrap() as z.ZodType;
+  }
+  return inner instanceof z.ZodObject ? inner : undefined;
+}
+
 /** A mistake in code (ours, or a fake's), not in what it was given: thrown as it is, never reported as data. */
 export const isBug = (err: unknown) =>
   err instanceof TypeError || err instanceof RangeError || err instanceof ReferenceError;