@sanoma-ai/workflows 0.2.0 → 0.4.0

package/src/index.ts

@@ -47,6 +47,9 @@ export {
   withoutWriteOnly,
 } from "./resource.ts";
 export { defineConfig, resolveConfig, resolveDatabaseUrl, type ResolvedConfig, type SanomaConfig } from "./config.ts";
+// `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
+// `collection()` itself is at `@sanoma-ai/workflows/data`, for `resources/data.ts`; this tells one apart, as the launcher does.
+export { isCollection } from "./collection.ts";
 export { type CredentialStatus, credentialsOf } from "./env.ts";
 export {
   APPLY_WORKFLOW,
@@ -57,6 +60,8 @@ export {
   type PlanAnswer,
   type PlanStep,
 } from "./apply.ts";
+export { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
+export { isDirect } from "./direct.ts";
 export {
   DRIFT_WORKFLOW,
   type DriftDeclared,
@@ -73,20 +78,32 @@ export {
   approve,
   approvedFor,
   type Decision,
-  definePolicy,
   deny,
   type Policy,
   type PolicyCall,
   type PolicyOp,
   policyOpOf,
+  type PreviewAnswer,
+  type PreviewRequest,
   type RecordedDecision,
 } from "./policy.ts";
 export {
+  cedarPolicy,
+  type CedarPolicySource,
+  loadPolicies,
+  POLICIES_DIR,
+  type PolicyProblem,
+  readPolicyFiles,
+  validatePolicies,
+} from "./cedar.ts";
+export {
+  ApprovalPendingError,
   errorCode,
   type ErrorCode,
   type ErrorInfo,
   type InputIssue,
   invalidInput,
+  NotAdmittedError,
   PolicyDeniedError,
   RejectedError,
   SanomaError,
@@ -116,12 +133,26 @@ export {
 } from "./secret.ts";
 export { resolveRevision, SOURCE_RESOLVE, type Source } from "./source.ts";
 export type { HostCapabilities, HostLifetime, HostOutputs, HostSpec } from "./host.ts";
-export { SanomaClient, type RunsFilter, type RunSummary, type StartOptions, type StoredSecret } from "./client.ts";
+export {
+  type CallOptions,
+  SanomaClient,
+  type RunsFilter,
+  type RunSummary,
+  type StartOptions,
+  type StoredSecret,
+} from "./client.ts";
 // A raw DBOS client on the runtime's database, for tests and tools that read DBOS directly.
 export { dbosClient } from "./db.ts";
 // Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.
 export {
+  AGENTS,
   approverLabel,
+  approverOf,
+  declaresPeople,
+  type PeopleResource,
+  personOf,
+  principalOf,
+  RUNTIME_AGENTS,
   credentialReady,
   DEFAULT_SLEEP_NAME,
   ENDED_STATUSES,

package/src/ledger.ts

@@ -3,7 +3,7 @@ import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { isDeepStrictEqual } from "node:util";
-import { LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
+import { type Db, LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
 import type { Approver, Principal } from "./define.ts";
 import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
 import { shown, warn } from "./log.ts";
@@ -80,13 +80,23 @@ export type LedgerRecord = {
       op?: string;
       /** The held call's `seq`, which its `op.called` record has, for a policy request. */
       opSeq?: number;
+      /** The policies that held the call, by id, for a policy request whose policy names them. */
+      reasons?: string[];
     }
   /** A message the approval ignored: from someone other than the approver, or not a decision. */
   | { type: "approval.refused"; approval: string; by?: string; reason: string }
-  | { type: "approval.decided"; approval: string; decision: "approve" | "reject"; by: string; note?: string }
+  | {
+      type: "approval.decided";
+      approval: string;
+      decision: "approve" | "reject";
+      by: string;
+      note?: string;
+      /** Set when `by` started the run: nobody else could decide (`mayDecide`). */
+      alone?: true;
+    }
   /**
    * A `ctx.sleep` began; `until` is when it ends, in ms since the epoch: the time asked for, or
-   * for a duration the time the sleep started plus the duration, as the runtime saw it. Written
+   * for a duration the record's `at` plus the duration, as the runtime saw it. Written
    * for a time already past too, which waits not at all.
    */
   | {
@@ -292,25 +302,13 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
 
   return {
     async append(record) {
-      const line = lineOf(record);
       const conn = await pool.db();
-      const inserted = await conn
-        .query(
-          `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
-          [record.id, record.runId, record.seq, line],
-        )
-        .catch((err: unknown) => {
-          if (DATA_EXCEPTION.test(pgCode(err))) {
-            throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
-          }
-          throw err;
-        });
-      if (inserted.rows.length) return;
+      if (await insertRecord(conn, record)) return;
       // Another write of the id was first: the record it stored stands.
       const { rows } = await conn.query<{ record: LedgerRecord }>(`SELECT record FROM ${TABLE} WHERE id = $1`, [
         record.id,
       ]);
-      if (rows[0]) warnIfDifferent(rows[0].record, line);
+      if (rows[0]) warnIfDifferent(rows[0].record, lineOf(record));
     },
     async read(runId) {
       const { rows } = await (
@@ -323,6 +321,26 @@ export function postgresLedger(databaseUrl: string): LedgerStore & { close(): Pr
   };
 }
 
+/**
+ * Stores the record in the Postgres ledger's table through `db`, unless one with its id is
+ * stored: true when this one was. What `postgresLedger` appends with, and a direct write
+ * (`SanomaClient.call`) inside the transaction that saves its record.
+ */
+export async function insertRecord(db: Db, record: LedgerRecord): Promise<boolean> {
+  const inserted = await db
+    .query(
+      `INSERT INTO ${TABLE} (id, run_id, seq, record) VALUES ($1, $2, $3, $4::jsonb) ON CONFLICT (id) DO NOTHING RETURNING n`,
+      [record.id, record.runId, record.seq, lineOf(record)],
+    )
+    .catch((err: unknown) => {
+      if (DATA_EXCEPTION.test(pgCode(err))) {
+        throw final(`Ledger record ${record.id} can't be stored: ${errorMessage(err)}`, err);
+      }
+      throw err;
+    });
+  return inserted.rows.length > 0;
+}
+
 /** Keeps records in memory, for tests. */
 export function memoryLedger(): LedgerStore {
   const runs = new Map<string, Map<string, LedgerRecord>>();

package/src/lint.ts

@@ -1,6 +1,7 @@
+import { realpathSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { byPosition, childrenOf, type LintProblem, type Node, parsed, type SourceFile } from "./ast.ts";
-import { readDataFile } from "./datafile.ts";
+import { COLLECTIONS_FILE, readDataFile } from "./datafile.ts";
 import { constsOf, outlineBody, workflowLiterals } from "./outline.ts";
 import { inside, nearestDir, RELATIVE } from "./paths.ts";
 // From src/ and from dist/ alike, the package's own oxlint.json: the one list of allowed names.
@@ -33,7 +34,7 @@ const REFUSED_PACKAGES: [RegExp, string][] = [
 ];
 
 /**
- * What a workflow or policy may import from an author package, besides types: the one list,
+ * What a workflow may import from an author package, besides types: the one list,
  * `allowImportNames` of oxlint.json's `@sanoma-ai/workflows` entry (`sanoma`'s generated
  * `oxlint.json` derives its own entry from it). Everything else is
  * refused: the client, the worker and the app could start runs or approve the run's own
@@ -46,7 +47,7 @@ const WORKFLOW_IMPORTS: readonly string[] =
 const ALLOWED_NAMES = new Set(WORKFLOW_IMPORTS);
 
 const NOT_ALLOWED =
-  `a workflow or policy imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
+  `a workflow imports only ${WORKFLOW_IMPORTS.join(", ")} and types from ` +
   `${AUTHOR_PACKAGES.join(" or ")}: the rest could start runs, approve its own approvals, forge the ledger or read credentials`;
 
 /**
@@ -57,11 +58,12 @@ const NOT_ALLOWED =
 const ERROR_CLASSES = new Set(["DriverError", "SanomaError", "PolicyDeniedError", "RejectedError"]);
 
 /**
- * Checks a workflow or policy file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
+ * Checks a workflow file. Imports allowed: the names in `WORKFLOW_IMPORTS` and any
  * type from `@sanoma-ai/workflows` or `sanoma`, `@sanoma-ai/connector-<vendor>`, `zod`, and relative files. With
- * `filename`, a relative import must stay inside the file's nearest `workflows/` or `policies/`
- * directory, or its own directory when it has neither. No `instanceof` against the runtime's
- * error classes: read `errorCode(err)`.
+ * `filename`, a relative import must stay inside the file's nearest `workflows/` directory, or its
+ * own directory when it has none; the one file outside it a workflow may import is the company's
+ * `resources/data.ts`, its collections (by real path). No
+ * `instanceof` against the runtime's error classes: read `errorCode(err)`.
  *
  * In each workflow's `run` (the literal `defineWorkflow` is called with), it reports what the
  * outline cannot draw, as the worker refuses to start with (`outlineBody`): `ctx` used other
@@ -82,7 +84,7 @@ export function lintWorkflow(input: string | SourceFile, path?: string): LintPro
   const read = typeof input === "string" ? parsed(input, filename ?? "workflow.ts") : input;
   const { program, at } = read;
   const problems = [...read.problems];
-  const root = filename === undefined ? undefined : nearestDir(filename, ["workflows", "policies"]);
+  const root = filename === undefined ? undefined : nearestDir(filename, ["workflows"]);
 
   const checkSource = (node: Node) => {
     const spec: string = node.source.value;
@@ -197,12 +199,27 @@ type RestrictedPath = { name: string; allowImportNames?: string[] };
 
 function whyRefused(spec: string, filename: string | undefined, root: string | undefined): string | undefined {
   if (RELATIVE.test(spec)) {
-    if (filename === undefined || root === undefined || inside(root, join(dirname(filename), spec))) return undefined;
-    const where =
-      basename(root) === "workflows" || basename(root) === "policies" ? `${basename(root)}/` : "this directory";
-    return `it reaches outside ${where}, toward the config and its drivers; ${THROUGH_CTX}`;
+    if (filename === undefined || root === undefined) return undefined;
+    const target = join(dirname(filename), spec);
+    if (inside(root, target)) return undefined;
+    const tree = basename(root) === "workflows";
+    // The collections, which a workflow names in `uses`: the one data file the runtime imports too.
+    if (tree && realPath(target) === realPath(join(dirname(root), "resources", COLLECTIONS_FILE))) return undefined;
+    return (
+      `it reaches outside ${tree ? `${basename(root)}/` : "this directory"}, toward the config and its drivers; ${THROUGH_CTX}` +
+      (tree ? "; of the files outside it, only resources/data.ts (the collections) may be imported" : "")
+    );
   }
   for (const [pattern, reason] of REFUSED_PACKAGES) if (pattern.test(spec)) return reason;
   if (ALLOWED_PACKAGE.test(spec)) return undefined;
   return "import only from `sanoma` (or `@sanoma-ai/workflows`), a `@sanoma-ai/connector-*` package, zod, or a file beside this one";
 }
+
+/** A path's real path, or the path itself when it does not exist. */
+function realPath(path: string): string {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}

package/src/op.ts

@@ -238,6 +238,12 @@ export interface CallContext {
   attempt: number;
   /** The secrets store, for the values `secret()` markers name: `resolveSecrets(input, call.secrets)`. In memory for a fake. */
   secrets: Secrets;
+  /**
+   * Who the call is made as: `run:<runId>` for a call in a run; the person's id for a direct call
+   * (`SanomaClient.call`) and in a run of the built-in `call` workflow. A collection's save
+   * records it as the record's `updatedBy`.
+   */
+  by?: string;
 }
 
 export type DriverFn<I = any, O = unknown> = (input: I, call: CallContext) => Promise<O>;

package/src/outline.ts

@@ -576,7 +576,7 @@ function ctxPath(callee: Node, ctx: string): string[] | undefined {
 }
 
 /** A string literal's value, or a template literal's with nothing interpolated. */
-function stringValue(node: Node): string | undefined {
+export function stringValue(node: Node): string | undefined {
   const n = unwrap(node);
   if (n?.type === "Literal" && typeof n.value === "string") return n.value;
   if (n?.type === "TemplateLiteral" && n.expressions.length === 0) return n.quasis[0]?.value.cooked ?? undefined;

package/src/paths.ts

@@ -1,7 +1,9 @@
-import { basename, dirname, isAbsolute, relative, sep } from "node:path";
+import { readdirSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, sep } from "node:path";
 
-// Where an import may reach, as the lints and the data-file reader all decide it, and the one
-// walk up the directories. Node's `path` only, no parser: the oxlint plugin loads it.
+// Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
+// the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
+// the oxlint plugin loads it.
 
 /** A relative import specifier: `./x.ts`, `../y.ts`. */
 export const RELATIVE = /^\.\.?\//;
@@ -30,3 +32,16 @@ export function inside(dir: string, path: string): boolean {
   const rel = relative(dir, path);
   return rel === "" || (rel.split(sep)[0] !== ".." && !isAbsolute(rel));
 }
+
+/** True when `path` is a directory. */
+export const isDirectory = (path: string): boolean => statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+
+/** The files under `dir` whose name `keep` takes, sorted, outside `node_modules`; none when `dir` is not a directory. */
+export function filesUnder(dir: string, keep: (name: string) => boolean): string[] {
+  if (!isDirectory(dir)) return [];
+  return readdirSync(dir, { recursive: true, withFileTypes: true })
+    .filter((d) => d.isFile() && keep(d.name))
+    .map((d) => join(d.parentPath, d.name))
+    .filter((path) => !relative(dir, path).split(sep).includes("node_modules"))
+    .toSorted();
+}

package/src/person.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { defineConnector } from "./op.ts";
+import { defineResource } from "./resource.ts";
+
+// Who exists in a company: people, agents and groups, declared in data files like any resource,
+// as the runtime's own vendor's types (`sanoma.person`, `sanoma.agent`, `sanoma.group`, imported
+// from "sanoma/resources"). They are `vendorless`: the repo is all there is of them, so they have
+// no driver and no drift. A membership is written on a group only, its members references to the
+// declared people and agents; every agent is in the group `agents` besides. Who a principal is,
+// read from them, is `principalOf` (`shared.ts`).
+
+/** An id or a group's name: one word, as a scenario names an approver. */
+const WORD = z.string().regex(/^\S+$/, 'is one word, such as "ada"');
+const NONE = { immutable: [], vendorOwned: [], writeOnly: [] };
+
+const person = defineResource({
+  vendor: "sanoma",
+  type: "person",
+  title: "Person",
+  identity: "id",
+  schema: z.object({
+    id: WORD,
+    name: z.string().optional(),
+    /** Matched first by a sign-in that vouches for an email (GitHub's, its verified public one). */
+    email: z.email().optional(),
+    /** Their GitHub login, which GitHub sign-in matches, ignoring case, when no email does. */
+    github: z
+      .string()
+      .regex(/^[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?$/, "is a GitHub login, such as ada-ortiz")
+      .optional(),
+  }),
+  fields: NONE,
+  find: ({ id }) => id,
+  vendorless: true,
+});
+
+const agent = defineResource({
+  vendor: "sanoma",
+  type: "agent",
+  title: "Agent",
+  identity: "id",
+  schema: z.object({ id: WORD, name: z.string().optional(), onBehalfOf: WORD.optional() }),
+  fields: { ...NONE, references: { onBehalfOf: { type: "sanoma.person" } } },
+  find: ({ id }) => id,
+  vendorless: true,
+});
+
+const group = defineResource({
+  vendor: "sanoma",
+  type: "group",
+  title: "Group",
+  identity: "name",
+  schema: z.object({ name: WORD, members: z.array(WORD) }),
+  fields: {
+    ...NONE,
+    unordered: ["members"],
+    references: { members: { type: ["sanoma.person", "sanoma.agent"] } },
+  },
+  find: ({ name }) => name,
+  vendorless: true,
+});
+
+/**
+ * What a data file declares the company's people with, imported from "sanoma/resources":
+ * `export const ada = sanoma.person({ id: "ada", name: "Ada Ortiz", github: "ada-ortiz" })`,
+ * `sanoma.agent({ id: "refund-bot", onBehalfOf: bo })` and
+ * `sanoma.group({ name: "finance", members: [ada, refundBot] })`.
+ */
+export const sanoma = { person, agent, group };
+
+/**
+ * The runtime's own connector of the people types: every config's, so its data files may declare
+ * them. Its package is `sanoma`, whose `/resources` entry exports `sanoma`.
+ */
+export const peopleConnector = defineConnector("sanoma", sanoma, { title: "Sanoma", package: "sanoma" });

package/src/plugin.ts

@@ -18,7 +18,7 @@ const plugin = {
         type: "problem",
         docs: {
           description:
-            "A data file under resources/ holds only imports, `export const <name> = <vendor>.<type>({ … })` with literal fields, and `export default [ … ]`",
+            "A data file under resources/ holds only imports, `export const <name> = <vendor>.<type>({ … })` with literal fields, and `export default [ … ]`; resources/data.ts holds only collections, `collection({ … })` from sanoma/data",
         },
       },
       create(context: Context) {

package/src/policy.ts

@@ -1,14 +1,10 @@
-import { z } from "zod";
-import { type ApprovalState, Approver, Covers, type Principal, sameApprover } from "./define.ts";
+import { type ApprovalState, type Approver, type Principal, sameApprover } from "./define.ts";
 import type { Effect, Op } from "./op.ts";
 
 /** An operation as a policy sees it: plain data, without its schemas. */
 export type PolicyOp = Pick<Op, "id" | "vendor" | "resource" | "name" | "effect">;
 
-/**
- * An operation as a policy sees it, for a `PolicyCall`: what the runtime passes, so a policy
- * test can build a call from the connector, `{ op: policyOpOf(shop.order.refund), ... }`.
- */
+/** An operation as a policy sees it, for a `PolicyCall`: what the runtime passes. */
 export const policyOpOf = ({ id, vendor, resource, name, effect }: Op): PolicyOp => ({
   id,
   vendor,
@@ -17,7 +13,7 @@ export const policyOpOf = ({ id, vendor, resource, name, effect }: Op): PolicyOp
   effect,
 });
 
-/** What a policy sees for each operation a run calls. Plain data, so a test can build one by hand. */
+/** What a policy sees for each operation a run calls: plain data. */
 export interface PolicyCall {
   op: PolicyOp;
   /** The same as `op.effect`. */
@@ -33,6 +29,8 @@ export interface PolicyCall {
    * A policy request has `requestedBy: "policy"` and the `op` it held.
    */
   run: { id: string; workflow: string; approvals: readonly ApprovalState[] };
+  /** For a collection's `save` or `delete`: the record as it was, when there was one. */
+  before?: unknown;
 }
 
 /**
@@ -44,88 +42,86 @@ export type Decision =
   | { kind: "deny"; reason: string; reasons?: string[] }
   | ApproveDecision;
 
-/**
- * Hold the call until the approver decides: a person's id, or `{ group }` for anyone in it.
- * The approval covers the held operation, and `covers` adds others, so a policy can let their
- * later calls through once it is approved.
- */
+/** Hold the call until the approver decides: a person's id, or `{ group }` for anyone in it. */
 interface ApproveDecision {
   kind: "approve";
   approver: Approver;
   title?: string;
-  covers?: Op[];
+  reasons?: string[];
 }
 
-const ReasonList = z.array(z.string(), { error: "reasons must be a list of strings" }).optional();
-
-/**
- * Checks a policy's answer. Parsing also copies it, so nothing else the policy returned is kept,
- * and turns `covers` into op ids.
- */
-export const DecisionSchema = z.discriminatedUnion(
-  "kind",
-  [
-    z.object({ kind: z.literal("allow"), reasons: ReasonList }),
-    z.object({ kind: z.literal("deny"), reason: z.string({ error: "deny needs a reason" }), reasons: ReasonList }),
-    z.object({
-      kind: z.literal("approve"),
-      approver: Approver,
-      title: z.string({ error: "the title must be a string" }).optional(),
-      covers: Covers,
-    }),
-  ],
-  { error: "not a decision" },
-);
-
-/**
- * A decision as checked and as the ledger records it: `covers` by op id, and the `version` of
- * the policy that made it, when it has one.
- */
-export type RecordedDecision = z.output<typeof DecisionSchema> & { policyVersion?: string };
+/** A decision as the ledger records it, with the `version` of the policy that made it, when it has one. */
+export type RecordedDecision = Decision & { policyVersion?: string };
 
 export const allow = (reasons?: string[]): Decision =>
   reasons === undefined ? { kind: "allow" } : { kind: "allow", reasons };
 export const deny = (reason: string, reasons?: string[]): Decision =>
   reasons === undefined ? { kind: "deny", reason } : { kind: "deny", reason, reasons };
 
-/** Holds the call for `approver`. `covers` lists other operations the approval also stands for. */
-export function approve(approver: Approver, { title, covers }: { title?: string; covers?: Op[] } = {}): Decision {
+/** Holds the call for `approver`; `reasons`, the rules that held it, as `allow` and `deny` take them. */
+export function approve(approver: Approver, { title, reasons }: { title?: string; reasons?: string[] } = {}): Decision {
   return {
     kind: "approve",
     approver,
     ...(title === undefined ? {} : { title }),
-    ...(covers === undefined ? {} : { covers }),
+    ...(reasons === undefined ? {} : { reasons }),
   };
 }
 
 /**
- * Decides whether a run may make an operation call: allow it, deny it (the run fails),
- * or hold it until someone approves. Runs are replayed after a restart, so a policy must
- * decide the same way every time from the call alone: no clock, randomness or network.
- * `lintWorkflow` checks a policy file for these too. Each decision is recorded once made,
- * and a replay reuses it, but a call interrupted before that is decided again. A policy
- * must not have side effects.
+ * Decides whether a run may make an operation call: allow it, deny it (the run fails), or hold it
+ * until someone approves. A company's is made from its Cedar files (`cedarPolicy`); a repo with
+ * none has `allowAll`. Each decision is recorded once made, and a replay reuses it, but a call
+ * interrupted before that is decided again.
  */
-export type Policy = ((call: PolicyCall) => Decision | Promise<Decision>) & {
-  /** Names this version of the policy, from `definePolicy(fn, { version })`. */
+export type Policy = ((call: PolicyCall) => Decision) & {
+  /** Names this version of the policy: a hash of the Cedar policies' ids and text. */
   readonly version?: string;
+  /** What the policy would answer for each request ahead of the call, its input unknown. */
+  readonly preview: (requests: readonly PreviewRequest[]) => PreviewAnswer[];
+  /**
+   * May `actor` start a run of `workflow` with `input` (the action `workflow:<name>`), given the
+   * run's `approvals` so far (none before it starts)?
+   */
+  readonly start: (
+    actor: Principal,
+    workflow: string,
+    input: unknown,
+    approvals?: readonly ApprovalState[],
+  ) => Decision;
 };
 
-/** A policy, optionally named with a version so a reader can tell which rules decided a call. */
-export function definePolicy(
-  policy: (call: PolicyCall) => Decision | Promise<Decision>,
-  options: { version?: string } = {},
-): Policy {
-  if (typeof policy !== "function") throw new Error("definePolicy expects a function of the call");
-  if (options.version !== undefined && (typeof options.version !== "string" || !options.version.trim())) {
-    throw new Error("definePolicy: `version` must be a non-empty string");
-  }
-  const defined = (call: PolicyCall) => policy(call);
-  return Object.freeze(options.version === undefined ? defined : Object.assign(defined, { version: options.version }));
+/** A question asked ahead of a call: may `principal` take `action` (an operation, or `workflow:<name>` to start one) on `resource` (an operation's target)? */
+export interface PreviewRequest {
+  principal: Principal;
+  action: { id: string; effect?: Effect };
+  resource?: string;
+}
+
+/**
+ * A preview's answer: `depends` when the unknown input decides it. `rule` is the Cedar policy
+ * behind a hold, a deny or a dependence; `approver`, a hold's.
+ */
+export interface PreviewAnswer {
+  answer: "allow" | "hold" | "deny" | "depends";
+  rule?: { id: string; file: string; title?: string; reason?: string };
+  approver?: Approver;
 }
 
-/** Allows every operation call. A config says so explicitly: `policy: allowAll`. */
-export const allowAll: Policy = definePolicy(() => allow());
+/** A policy that decides every call and start as `decide` does, and previews each as `answer`. */
+const decidingAll = (decide: () => Decision, answer: "allow" | "deny"): Policy =>
+  Object.freeze(
+    Object.assign(decide, {
+      start: decide,
+      preview: (requests: readonly PreviewRequest[]): PreviewAnswer[] => requests.map(() => ({ answer })),
+    }),
+  );
+
+/** Allows every operation call and run start: the policy of a repo with no `policies/**\/*.cedar`. */
+export const allowAll: Policy = decidingAll(() => allow(), "allow");
+
+/** Refuses every operation call and run start, and previews each as a deny, saying `reason`. */
+export const denyAll = (reason: string): Policy => decidingAll(() => deny(reason), "deny");
 
 /**
  * True when an approval in the run was approved, covers the operation, and was addressed to