@sanoma-ai/workflows 0.5.0 → 0.7.0

package/src/deadlines.ts

@@ -0,0 +1,234 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { dbosStatusesOf } from "./client.ts";
+import type { Db } from "./db.ts";
+import { nextWakeupGeneration, recordWakeupError, recordWakeupRegistration, recordWakeupStop } from "./db.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { warn } from "./log.ts";
+import type { CallContext, DriverFn, Op } from "./op.ts";
+import type { Secrets } from "./secret.ts";
+import { errorMessage, WAKEUP_AGENT } from "./shared.ts";
+import type { WakeupRegistration } from "./wakeup.ts";
+
+// What a worker knows of its own runs that DBOS cannot tell it: which are executing and which are
+// blocked in a `ctx` wait, and until when. DBOS sees both as PENDING. A worker that registers a
+// wakeup stops itself once nothing can run before the next deadline (`stopWhenIdle`).
+
+/** What a run blocked in a `ctx` wait waits for: a sleep, until its deadline, or an approval's decision, which has none. */
+export type Wait = { kind: "sleep"; until: number } | { kind: "approval" };
+
+/** A deadline besides the sleeping runs', such as a schedule's next fire; undefined for none. */
+export type DeadlineSource = () => Date | undefined;
+
+/** What a worker shows of its runs' deadlines (`Worker.deadlines`). */
+export interface Deadlines {
+  /**
+   * Adds a deadline besides the sleeping runs', read each time `nextDeadline` is: a fixed time
+   * (a schedule's next fire), never one counted from now, which would never let the worker stop.
+   */
+  addSource(source: DeadlineSource): void;
+  /** The earliest deadline: a sleeping run's `until`, or a source's. Undefined when there is none. */
+  nextDeadline(): Date | undefined;
+  /** How many runs are inside their body and in no wrapped wait: executing, or replaying. */
+  readonly busy: number;
+  /** What the run waits for while it is blocked in a wrapped wait; undefined otherwise. */
+  waitOf(runId: string): Wait | undefined;
+}
+
+/** The registry a worker's runs report to, through `running` and `waiting`. */
+export interface DeadlineRegistry extends Deadlines {
+  /** Runs a run's body, counted busy but while it is in `waiting`. */
+  running<T>(runId: string, body: () => Promise<T>): Promise<T>;
+  /** Runs `fn`, the live wait itself (`DBOS.sleep`, `DBOS.recv`), with the run counted as waiting for `wait`. */
+  waiting<T>(runId: string, wait: Wait, fn: () => Promise<T>): Promise<T>;
+}
+
+/** A registry of its own for each worker: two copies of the package in one process never share one. */
+export function deadlineRegistry(): DeadlineRegistry {
+  // Each run inside its body, with what it waits for while it is blocked.
+  const runs = new Map<string, Wait | undefined>();
+  const sources: DeadlineSource[] = [];
+  return {
+    addSource(source) {
+      sources.push(source);
+    },
+    nextDeadline() {
+      const times = [
+        ...[...runs.values()].flatMap((wait) => (wait?.kind === "sleep" ? [wait.until] : [])),
+        ...sources.flatMap((source) => source()?.getTime() ?? []),
+      ];
+      return times.length ? new Date(Math.min(...times)) : undefined;
+    },
+    get busy() {
+      return [...runs.values()].filter((wait) => wait === undefined).length;
+    },
+    waitOf: (runId) => runs.get(runId),
+    async running(runId, body) {
+      runs.set(runId, undefined);
+      try {
+        return await body();
+      } finally {
+        runs.delete(runId);
+      }
+    },
+    async waiting(runId, wait, fn) {
+      // Every wait is inside a run's body; one outside is left uncounted rather than counted busy for good.
+      if (!runs.has(runId)) return fn();
+      runs.set(runId, wait);
+      try {
+        return await fn();
+      } finally {
+        if (runs.has(runId)) runs.set(runId, undefined);
+      }
+    },
+  };
+}
+
+/** The worker `idle` asks about: the app, the version it runs, and its queue. */
+export type IdleScope = Pick<ResolvedConfig, "appName" | "version" | "queueName">;
+
+/**
+ * True when a run on `queue` (none for a run started outside a queue) is this worker's to run: on
+ * its own queue, or on one of DBOS's, where recovery puts runs.
+ */
+export const onOwnQueue = (queue: string | undefined, queueName: string): boolean =>
+  !queue || queue === queueName || queue.startsWith("_dbos_");
+
+/**
+ * True when nothing this worker would run can run within `horizonMs`: no run of its is executing
+ * or replaying; none of its version is queued (or queued without one, while it is the latest) on
+ * its queue or DBOS's own (recovery queues there); each PENDING run of its version is blocked in
+ * a wrapped wait; and the next deadline is past the horizon. A run of another version or queue
+ * is not this worker's to run, so it never holds the worker up.
+ */
+export async function idle(deadlines: Deadlines, scope: IdleScope, horizonMs: number): Promise<boolean> {
+  if (deadlines.busy > 0) return false;
+  const next = deadlines.nextDeadline();
+  if (next && next.getTime() <= Date.now() + horizonMs) return false;
+  const runs = await DBOS.listWorkflows({
+    applicationName: scope.appName,
+    status: dbosStatusesOf("queued", "running"),
+    loadInput: false,
+    loadOutput: false,
+  });
+  const ours = runs.filter((r) => onOwnQueue(r.queueName, scope.queueName));
+  if (
+    ours.some(
+      (r) => r.status === "PENDING" && r.applicationVersion === scope.version && !deadlines.waitOf(r.workflowID),
+    )
+  )
+    return false;
+  const queued = ours.filter((r) => r.status !== "PENDING");
+  if (queued.some((r) => r.applicationVersion === scope.version)) return false;
+  // DBOS gives a run queued without a version to the app's latest version.
+  if (!queued.some((r) => !r.applicationVersion)) return true;
+  return (await DBOS.getLatestApplicationVersion()).versionName !== scope.version;
+}
+
+/** What `onStopped` hears when the worker stopped itself: the deadline it registered (null for none) and its generation. */
+export interface SelfStop {
+  at: string | null;
+  generation: number;
+}
+
+/** What the stop rule acts on: the wakeup row, the wakeup's register operation, and the worker. */
+export interface StopRule {
+  /** The wakeup row's database. */
+  db: () => Promise<Db>;
+  /** This worker's id on the row (`owner`), fresh for each worker. */
+  owner: string;
+  /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
+  wakeup: string;
+  /** The wakeup type's register operation, and its driver (none when the connector attaches none). */
+  register: { op: Op; fn: DriverFn | undefined };
+  secrets: Secrets;
+  deadlines: Deadlines;
+  idle: () => Promise<boolean>;
+  everyMs: number;
+  /** Stops the worker (`Worker.stop`). */
+  stop: () => Promise<void>;
+  onStopped?: ((stopped: SelfStop) => void) | undefined;
+}
+
+/**
+ * Checks every `everyMs` whether the worker is `idle`; when it is, counts the wakeup row's
+ * generation up, registers the next deadline with the wakeup (none when there is no deadline at
+ * all), and stops the worker, then tells `onStopped`. A failed registration is recorded on the
+ * row and logged once for each new message, and the worker keeps running: the next check tries
+ * again with a new generation. A run that arrives while it registers keeps the worker up, since
+ * the worker must be idle twice, with the same deadline, before it stops. `close` ends the checks.
+ */
+export function stopWhenIdle(rule: StopRule): { close(): void } {
+  let closed = false;
+  let timer: NodeJS.Timeout | undefined;
+  let lastProblem: string | undefined;
+  const problem = (message: string) => {
+    if (message !== lastProblem) warn(message);
+    lastProblem = message;
+  };
+
+  const tryStop = async (): Promise<boolean> => {
+    if (!(await rule.idle())) return false;
+    const next = rule.deadlines.nextDeadline();
+    const at = next?.toISOString() ?? null;
+    const db = await rule.db();
+    const generation = await nextWakeupGeneration(db, rule.owner);
+    if (generation === undefined) {
+      // A worker claims the row only when it starts, so this one never gets it back.
+      warn("another worker registers this instance's wakeups now, so this one keeps running and stops checking");
+      closed = true;
+      return false;
+    }
+    if (at !== null) {
+      try {
+        await registerWakeup(rule, { at, generation });
+      } catch (err) {
+        const message = errorMessage(err);
+        await recordWakeupError(db, rule.owner, generation, message);
+        problem(`could not register the wakeup at ${at}, so the worker keeps running: ${message}`);
+        return false;
+      }
+      await recordWakeupRegistration(db, rule.owner, generation, at);
+    }
+    lastProblem = undefined;
+    if (closed || !(await rule.idle()) || rule.deadlines.nextDeadline()?.toISOString() !== next?.toISOString())
+      return false;
+    await recordWakeupStop(db, rule.owner, generation);
+    await rule.stop().catch((err: unknown) => warn(`the worker could not stop cleanly: ${errorMessage(err)}`));
+    rule.onStopped?.({ at, generation });
+    return true;
+  };
+
+  const check = async () => {
+    timer = undefined;
+    if (closed) return;
+    const stopped = await tryStop().catch((err: unknown) => {
+      problem(`could not check whether the worker may stop: ${errorMessage(err)}`);
+      return false;
+    });
+    if (!stopped && !closed) schedule();
+  };
+  const schedule = () => {
+    timer = setTimeout(() => void check(), rule.everyMs);
+    timer.unref();
+  };
+  schedule();
+  return {
+    close() {
+      closed = true;
+      clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * Calls the wakeup's register operation, as `SanomaClient.call` calls a driver: its input parsed,
+ * a `CallContext` of the runtime's, and no ledger record, which is a run's. The idempotency key
+ * is the generation's, so a retried registration is one registration.
+ */
+async function registerWakeup({ register: { op, fn }, secrets, wakeup }: StopRule, registration: WakeupRegistration) {
+  if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
+  // Every database counts generations from 0, so the key names the wakeup too.
+  const key = `wakeup:${wakeup}:${registration.generation}`;
+  const context: CallContext = { idempotencyKey: key, runId: key, opId: op.id, attempt: 1, secrets, by: WAKEUP_AGENT };
+  await fn(op.input.parse(registration), context);
+}

package/src/define.ts

@@ -92,12 +92,23 @@ export interface ApprovalState extends Omit<ApprovalRequest, "covers"> {
   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";
+  /**
+   * `withdrawn`: it no longer stands, as when its change got a new commit. A pending approval is
+   * withdrawn by a message (`SanomaClient.withdraw`), an approved one by its run
+   * (`withdrawApprovals`); either way it lets nothing through and takes no decision.
+   */
+  status: "pending" | "approved" | "rejected" | "withdrawn";
+  /** Why it was withdrawn, once it is. */
+  withdrawnReason?: string;
+  /** When it was withdrawn, once it is. */
+  withdrawnAt?: number;
+  /** Who withdrew it, when someone did rather than its run (`withdrawApprovals`). */
+  withdrawnBy?: string;
   requestedAt: number;
   decidedBy?: string;
   decidedAt?: number;
   note?: string;
-  /** The `id` of the decision message the run decided with, when it had one. */
+  /** The `id` of the decision or withdrawal 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;
@@ -174,7 +185,7 @@ type CtxOps<O extends Op> = {
 };
 
 interface ApprovalCtx {
-  /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection. */
+  /** Waits, durably, until the approver (or someone in the approver group) approves. Throws `RejectedError` on a rejection, `WithdrawnError` on a withdrawal. */
   approval(title: string, request: ApprovalRequest): Promise<ApprovalResult>;
 }
 
@@ -235,11 +246,19 @@ export function jsonSchemaOf(
   });
 }
 
+/**
+ * How a workflow starts: `manual` (by hand, or from code), or on a schedule, `schedule` a cron
+ * expression of five fields (minute, hour, day of month, month, day of week) read in `timezone`,
+ * an IANA time zone (`Europe/Amsterdam`), UTC without one. A scheduled run is started by the
+ * runtime's `schedule` agent with the input `{}`, as the policy allows; it can still be started by hand.
+ */
+export type Trigger = "manual" | { readonly schedule: string; readonly timezone?: string };
+
 export interface WorkflowDefinition<U extends readonly Use[] = readonly Use[], S extends z.ZodType = z.ZodType> {
   readonly kind: "workflow";
   readonly name: string;
   readonly title?: string;
-  readonly trigger: "manual";
+  readonly trigger: Trigger;
   readonly input: S;
   /** Every operation and built-in the workflow may call. `ctx` is built from this list and nothing else. */
   readonly uses: U;
@@ -260,6 +279,13 @@ export function defineWorkflow<const U extends readonly Use[], S extends z.ZodTy
   if (!/^[a-z][a-z0-9-]*$/.test(def.name)) {
     throw new Error(`Workflow name "${def.name}" must be lowercase letters, digits and dashes`);
   }
+  checkTrigger(def.name, def.trigger);
+  // A scheduled run starts with no input of its own.
+  if (def.trigger !== "manual" && !acceptsEmpty(def.input)) {
+    throw new Error(
+      `Workflow "${def.name}": a scheduled run starts with the input {}, which its input schema refuses: make each field optional or give it a default`,
+    );
+  }
   const file = callerFile();
   if (file === undefined) {
     throw new Error(
@@ -270,6 +296,47 @@ export function defineWorkflow<const U extends readonly Use[], S extends z.ZodTy
   return Object.freeze({ kind: "workflow", ...def, file });
 }
 
+/** True when `{}` parses: a schema zod can check only asynchronously is taken as accepting it, and the run parses it. */
+function acceptsEmpty(schema: z.ZodType): boolean {
+  try {
+    return schema.safeParse({}).success;
+  } catch {
+    return true;
+  }
+}
+
+/** Throws what is wrong with a workflow's `trigger`: not `manual` or a schedule, five fields, in a time zone there is. */
+function checkTrigger(name: string, trigger: unknown): void {
+  if (trigger === "manual") return;
+  const { schedule, timezone } = (typeof trigger === "object" && trigger !== null ? trigger : {}) as {
+    schedule?: unknown;
+    timezone?: unknown;
+  };
+  if (typeof schedule !== "string") {
+    throw new Error(`Workflow "${name}": its trigger is "manual" or { schedule, timezone? }`);
+  }
+  if (schedule.trim().split(/\s+/).length !== 5) {
+    throw new Error(
+      `Workflow "${name}": its schedule "${schedule}" is a cron expression of five fields: minute, hour, day of month, month, day of week`,
+    );
+  }
+  if (timezone !== undefined && !isTimeZone(timezone)) {
+    throw new Error(
+      `Workflow "${name}": its timezone "${String(timezone)}" is no IANA time zone, such as "Europe/Amsterdam"`,
+    );
+  }
+}
+
+const isTimeZone = (zone: unknown): boolean => {
+  // An offset (`+05:30`), which Intl takes too, is no IANA zone name.
+  if (typeof zone !== "string" || /^[+-]/.test(zone)) return false;
+  try {
+    return Boolean(new Intl.DateTimeFormat("en", { timeZone: zone }));
+  } catch {
+    return false;
+  }
+};
+
 /**
  * The file of the code that called the function calling this one (`defineWorkflow`'s caller),
  * from V8's call sites, as a path; undefined where there is none.

package/src/demo.ts

@@ -0,0 +1,87 @@
+import type { SanomaClient } from "./client.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { DATA_TABLE } from "./db.ts";
+import { applyGivens } from "./sandbox.ts";
+import { loadScenarios, type Moment } from "./scenario.ts";
+import { memorySecrets } from "./secret.ts";
+import { errorMessage } from "./shared.ts";
+
+/*
+ * A demo: a company repo run on its connectors' fakes, with the world its scenarios describe.
+ * Re-exported from `@sanoma-ai/workflows/scenarios`, server-side, since it loads Cucumber.
+ */
+
+/** What the last `reseed` of an instance did: what the demo's banner shows. */
+export interface DemoState {
+  /** When it was seeded, as an ISO timestamp. */
+  seededAt: string;
+  /** The worlds applied, by scenario name. */
+  worlds: string[];
+  /** Each moment started and left waiting: who it is for, where they land, its scenario and its run. */
+  moments: (Moment & { scenario: string; runId: string })[];
+  /** What could not be done, one line each: a feature file that did not load, a world or a moment that failed. */
+  problems: string[];
+}
+
+/** Each instance's last reseed, by its resolution. */
+const states = new WeakMap<ResolvedConfig, DemoState>();
+
+/**
+ * Seeds the demo instance afresh: empties the collections' table, resets the instance's fakes,
+ * applies every world (a scenario with no `When`) to the instance (`applyGivens`: its records
+ * saved through the collections' driver, its vendor objects put in the fakes), then starts each
+ * moment as a sandbox run by its person, left undriven, so its first approval waits for them.
+ * `resolved` is the resolution the worker and `client` run on, made with `fakes: "instance"`.
+ * A world or a moment that fails is a problem in the state it returns, and the rest go on.
+ */
+export async function reseed(client: SanomaClient, resolved: ResolvedConfig): Promise<DemoState> {
+  const fakes = resolved.instanceFakes;
+  if (!fakes) throw new Error('reseed seeds an instance on fakes: resolve its config with `fakes: "instance"`');
+  // Read first, so scenarios that cannot be read at all leave the instance as it was.
+  const { scenarios, errors } = await loadScenarios(resolved);
+  if (resolved.dataStore) await (await resolved.dataStore.db()).query(`TRUNCATE ${DATA_TABLE}`);
+  for (const fake of fakes.values()) fake.reset();
+  const state: DemoState = {
+    seededAt: new Date().toISOString(),
+    worlds: [],
+    moments: [],
+    problems: errors.map((e) => e.message),
+  };
+  const secrets = memorySecrets();
+  for (const world of scenarios.filter((s) => s.workflow === undefined)) {
+    try {
+      await applyGivens(world, {
+        kind: "instance",
+        drivers: resolved.drivers,
+        fakes,
+        ops: resolved.ops,
+        call: (i, opId) => ({
+          idempotencyKey: `world:${world.name}:${i}`,
+          runId: `world:${world.name}`,
+          opId,
+          attempt: 1,
+          secrets,
+          // Who its records are by: whoever it says is acting, else the runtime's own agent.
+          by: world.startedBy ?? "scenarios",
+        }),
+      });
+      state.worlds.push(world.name);
+    } catch (err) {
+      state.problems.push(`world "${world.name}": ${errorMessage(err)}`);
+    }
+  }
+  for (const s of scenarios) {
+    if (!s.moment || s.workflow === undefined) continue;
+    try {
+      const runId = await client.start(s.workflow, s.input, { sandbox: s.name, startedBy: s.moment.person });
+      state.moments.push({ ...s.moment, scenario: s.name, runId });
+    } catch (err) {
+      state.problems.push(`moment "${s.name}": ${errorMessage(err)}`);
+    }
+  }
+  states.set(resolved, state);
+  return state;
+}
+
+/** What the instance's last `reseed` did, or undefined before its first. */
+export const demoState = (resolved: ResolvedConfig): DemoState | undefined => states.get(resolved);

package/src/describe.ts

@@ -3,7 +3,7 @@ import type { z } from "zod";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { type Field, recordSchemaOf } from "./collection.ts";
 import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
-import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
+import { type Builtin, jsonSchemaOf, opIdsOf, type Trigger, type Use } from "./define.ts";
 import { isDirect } from "./direct.ts";
 import { lintWorkflow } from "./lint.ts";
 import { type Effect, VENDOR, type VendorInfo } from "./op.ts";
@@ -63,11 +63,14 @@ export {
   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";
+export { readSites, type SiteCall, type SiteEntry, type SitePage, siteContentPages, siteLocales } 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 Permissions grid: the app's page and `sanoma check`'s `checked` event compute it the one way.
+export { columnPrincipal, permissionsGrid, type PermissionsGrid, type PermissionsRow } from "./grid.ts";
+export { previewRequests } from "./shared.ts";
 // The apply workflow's plan and report, which the app renders.
 export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanStep } from "./apply.ts";
 
@@ -75,7 +78,8 @@ export type { ApplyInput, ApplyPlan, ApplyReport, ApplyResult, PlanAnswer, PlanS
 export interface WorkflowEntry {
   name: string;
   title?: string;
-  trigger: "manual";
+  /** `manual`, or the schedule it starts on (`defineWorkflow`'s `trigger`). */
+  trigger: Trigger;
   /**
    * Set for a workflow the runtime adds itself, `drift`, `apply` or `call`, rather than the config: a label. It
    * starts like any other.
@@ -359,14 +363,22 @@ function domainProblems(
       const others = `${names.length === 2 ? "both " : ""}${names.slice(0, -1).join(", ")}`;
       messages.push(`${domain} is the domain of ${others} and ${names.at(-1)}`);
     }
-    if (!messages.length || root === undefined) continue;
-    const file = read(join(root, resource.file));
-    const at = typeof file === "string" ? {} : file.at(resource.span[0]);
-    for (const message of messages) problems.push({ file: resource.file, ...at, message });
+    if (root !== undefined) problems.push(...messages.map((message) => problemAt(root, resource, read, message)));
   }
   return problems;
 }
 
+/** `message` at a declaration's `export const`. */
+function problemAt(
+  root: string,
+  resource: DeclaredResource,
+  read: (path: string) => SourceFile | string,
+  message: string,
+): ResourceProblem {
+  const file = read(join(root, resource.file));
+  return { file: resource.file, ...(typeof file === "string" ? {} : file.at(resource.span[0])), message };
+}
+
 /**
  * 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

package/src/errors.ts

@@ -6,6 +6,7 @@ import { CALL_WORKFLOW, errorMessage } from "./shared.ts";
 const CODES = [
   "policy_denied",
   "approval_rejected",
+  "approval_withdrawn",
   "not_approver",
   "no_pending_approval",
   "already_decided",
@@ -132,6 +133,19 @@ export class RejectedError extends SanomaError {
   }
 }
 
+/** Thrown into the run when the approval it waits on is withdrawn. The run fails with it unless it catches it. */
+export class WithdrawnError extends SanomaError {
+  /**
+   * @param title The approval's title.
+   * @param approvalId The approval's id in the run, such as "approval-2".
+   * @param reason Why it was withdrawn.
+   */
+  constructor(title: string, approvalId: string, reason: string) {
+    super("approval_withdrawn", `"${title}" was withdrawn: ${reason}`, { title, approvalId, reason });
+    this.name = "WithdrawnError";
+  }
+}
+
 /**
  * The wrapper, given the original's own `code` and `data` when it has one of our codes, so
  * `errorCode` reads the same through it: a denied call whose ledger write failed too is still

package/src/fake.ts

@@ -7,6 +7,7 @@ import {
   DriverError,
   type OpIdOf,
   type Specs,
+  withSetup,
 } from "./op.ts";
 
 /*
@@ -154,3 +155,14 @@ export function defineFake<V extends string, S extends Specs, T extends Record<s
     },
   };
 }
+
+/**
+ * `connector` set up with this fake instead of the one its package attaches, for a test or a demo
+ * that seeds or reads the fake its runs call: live runs call its driver, and sandbox runs call it
+ * too, since its maker gives this very one. A driver swap alone is `withSetup(connector, { driver })`,
+ * which keeps the package's fake, so each sandbox run has one of its own. The operations are the
+ * same.
+ */
+export function withFake<C extends Connector<any, any>>(connector: C, fake: Fake<any, any>): C {
+  return withSetup(connector, { driver: () => fake.driver, fake: () => fake });
+}

package/src/grid.ts

@@ -0,0 +1,100 @@
+import type { ResolvedConfig } from "./config.ts";
+import type { Principal } from "./define.ts";
+import type { ConfigDescription } from "./describe.ts";
+import type { PreviewAnswer, PreviewRequest } from "./policy.ts";
+import {
+  AGENTS,
+  ANONYMOUS,
+  ANONYMOUS_PRINCIPAL,
+  groupNamesOf,
+  previewRequests,
+  VISITORS,
+  visitorPrincipal,
+} from "./shared.ts";
+
+// The Permissions grid: what the policy would answer each group, for every workflow's start, the
+// operations it may call, and each direct operation. A pure function of a resolved config's policy
+// and its description, so the app's Permissions page and `sanoma check` (a draft's grid, on its
+// `checked` event) compute it the one way, and a change is reviewed as one grid against another.
+
+/** A row of the grid: a workflow (its start) or an operation, and the policy's answer for each column. */
+export interface PermissionsRow {
+  id: string;
+  title?: string;
+  cells: PreviewAnswer[];
+}
+
+/**
+ * The grid: its columns (`null` for someone in no group, then the declared groups, `agents` and
+ * `visitors`, sorted, then `anonymous`), a row for each workflow's start, with a row for each
+ * operation it uses (`ops`, in its order), and a row for each operation a person may call
+ * directly, each with a cell per column.
+ */
+export interface PermissionsGrid {
+  groups: (string | null)[];
+  workflows: (PermissionsRow & { ops: PermissionsRow[] })[];
+  ops: PermissionsRow[];
+}
+
+/**
+ * Whom the `agents` column's agent acts for: a hold `@hold("on-behalf-of")` asks them. Only an
+ * agent acts for someone, so in any other column that hold refuses, as it does a person.
+ */
+const ACTS_FOR = "whom it acts for";
+
+/** Whom a column of the grid asks about: someone in the group alone, a visitor, or `anonymous`. */
+export function columnPrincipal(group: string | null): Principal {
+  if (group === null) return { id: "group:", groups: [] };
+  if (group === ANONYMOUS) return ANONYMOUS_PRINCIPAL;
+  if (group === VISITORS) return visitorPrincipal("grid", "visitor");
+  return { id: `group:${group}`, groups: [group], ...(group === AGENTS && { onBehalfOf: ACTS_FOR }) };
+}
+
+/**
+ * The grid of `resolved`'s policy over `description`: for someone in no group, then for each
+ * group, the declared ones, `agents` and `visitors` (the visitors' only beside a public site),
+ * then for `anonymous`, what the policy would answer someone in it alone (`columnPrincipal`), the
+ * input unknown (`Policy.preview`), for the start of each of the config's own workflows, by name,
+ * each with the operations it uses, in the order it declares them (`previewRequests`), then each
+ * operation a person may call directly, by id.
+ */
+export function permissionsGrid(
+  { policy }: Pick<ResolvedConfig, "policy">,
+  description: ConfigDescription,
+): PermissionsGrid {
+  // A visitor's columns only beside a public site, where there are visitors.
+  const visitors = description.sites.some((site) => site.public);
+  const groups = [
+    null,
+    ...groupNamesOf(description.resources).filter((g) => visitors || g !== VISITORS),
+    ...(visitors ? [ANONYMOUS] : []),
+  ];
+  const opsById = new Map(description.ops.map((op) => [op.id, op]));
+  const workflows = description.workflows.filter((w) => !w.builtin);
+  const direct = description.ops.filter((op) => op.direct).toSorted((a, b) => a.id.localeCompare(b.id));
+  // Every row's question, in the grid's order: each workflow's start, then the operations it may
+  // call, as the run form asks them; then each direct operation.
+  const asked = workflows.map((w) => previewRequests(w, opsById));
+  const requests: Omit<PreviewRequest, "principal">[] = [
+    ...asked.flat(),
+    ...direct.map(({ id, effect }) => ({ action: { id, effect } })),
+  ];
+  const columns = groups.map((group) => {
+    const principal = columnPrincipal(group);
+    return policy.preview(requests.map((request) => ({ ...request, principal })));
+  });
+  const rows = requests.map(({ action: { id } }, i): PermissionsRow => ({
+    id,
+    cells: columns.map((answers) => answers[i]!),
+  }));
+  // Each workflow's rows, as many as it asked: its start, then one per operation it may call.
+  let at = 0;
+  return {
+    groups,
+    workflows: workflows.map(({ name, title }, i) => {
+      const [start, ...called] = rows.slice(at, (at += asked[i]!.length));
+      return { ...start!, id: name, ...(title !== undefined && { title }), ops: called };
+    }),
+    ops: rows.slice(at),
+  };
+}