@sanoma-ai/workflows 0.2.0 → 0.4.0

package/src/scenario.ts

@@ -13,6 +13,7 @@ import {
 } from "@cucumber/messages";
 import type { z } from "zod";
 import type { RunSummary, SanomaClient } from "./client.ts";
+import type { Approver } from "./define.ts";
 import type { ResolvedConfig } from "./config.ts";
 import {
   buildLibrary,
@@ -25,22 +26,29 @@ import {
   stepResults,
   StepStatus,
 } from "./cucumber.ts";
-import { errorInfo, SanomaError } from "./errors.ts";
+import { errorCode, errorInfo, SanomaError } from "./errors.ts";
 import { type CallRecord, contains, type CoreExpectation, detailOf, isCall } from "./expectations.ts";
 import type { Fake } from "./fake.ts";
 import { fill, isBug, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
 import { type OutlineNode, outlineWorkflow } from "./outline.ts";
+import { admit, type DeclaredPeople, readPeople } from "./resources.ts";
 import { memorySecrets } from "./secret.ts";
 import {
   APPLY_WORKFLOW,
   BUILT_IN_WORKFLOWS,
+  DATA_VENDOR,
+  declaresPeople,
   DRIFT_WORKFLOW,
   errorMessage,
   fitsOp,
   flatten,
+  groupNamesOf,
   isEnded,
+  principalIdsOf,
+  problemLine,
+  RUNTIME_AGENTS,
 } from "./shared.ts";
 import type { Call, RunView, Seed } from "./steps.ts";
 
@@ -98,9 +106,11 @@ export interface Decision {
 /**
  * What the run should do: call an operation (with at least this input) or not, run the step
  * `name`d in the workflow's outline or not, or a number of `times`, have the policy deny an
- * operation (`denied`) or hold one for an approver (`held`), end a certain way, for a drift
- * run, report the resource `declared` (`<file>#<export>`) clean, gone, absent, or drifted in a
- * field, or for an apply run, create it, or leave it bound to an object (`bound`, its vendor's id).
+ * operation (`denied`, for a `reason` when the step names one) or hold one for an approver
+ * (`held`: a person's id or a group's name, or `{ group }` a group's alone), end a certain way,
+ * for a drift run, report the resource `declared` (`<file>#<export>`) clean, gone, absent, or
+ * drifted in a field, or for an apply run, create it, or leave it bound to an object (`bound`,
+ * its vendor's id).
  * A step whose own code checks the run (a connector's or the company's, or an operation's own
  * test's) is `custom`, with what it is about.
  */
@@ -108,8 +118,8 @@ export type Expectation =
   | { step: string; op: string; input?: unknown; called: boolean }
   | { step: string; name: string; input?: unknown; called: boolean }
   | { step: string; name: string; times: number }
-  | { step: string; op: string; decision: "denied" }
-  | { step: string; op: string; decision: "held"; approver: string }
+  | { step: string; op: string; decision: "denied"; reason?: string }
+  | { step: string; op: string; decision: "held"; approver: Approver }
   | { step: string; outcome: "finished" | "failed"; code?: string }
   | { step: string; declared: string; status: "clean" | "gone" | "absent" }
   | { step: string; declared: string; status: "drifted"; field: string }
@@ -132,6 +142,8 @@ export interface Scenario {
   text: string;
   /** Every step in order, for a list and for marking graph nodes. */
   steps: ScenarioStep[];
+  /** Who starts the run, by id, when a `Given <who> is acting` says: a declared person or agent. */
+  startedBy?: string;
   given: Given[];
   input: unknown;
   decisions: Decision[];
@@ -152,10 +164,14 @@ export interface Check {
 }
 
 /**
- * What steps can name: the config's operations, workflows and resource types by id, the steps
- * its connectors (and the company) ship, and where the feature files are.
+ * What steps can name: the config's operations, workflows, resource types and collections by id,
+ * the steps its connectors (and the company) ship, where the feature files are, and the root
+ * whose data files declare its people.
  */
-export type Scope = Pick<ResolvedConfig, "ops" | "workflows" | "scenarios" | "types" | "steps">;
+export type Scope = Pick<
+  ResolvedConfig,
+  "ops" | "workflows" | "scenarios" | "types" | "collections" | "steps" | "root"
+>;
 
 type Kind = ScenarioStep["kind"];
 type Fault = Extract<Seed, { fault: unknown }>["fault"];
@@ -170,9 +186,13 @@ interface Then {
   verify(run: RunView): string | undefined;
 }
 
-/** What a step of each kind reads into; `any` is a decision, which a step of any keyword may make. */
+/**
+ * What a step of each kind reads into; `any` is a decision, which a step of any keyword may make,
+ * and `actor` a `Given` saying who starts the run (`{who} is acting`), by id.
+ */
 interface Items {
   given: Unstepped<Given>[];
+  actor: string;
   when: When;
   then: Then;
   any: Unstepped<Decision>;
@@ -314,7 +334,9 @@ function builtFor(scope: Scope): Built {
     cached &&
     cached.scope.workflows === scope.workflows &&
     cached.scope.types === scope.types &&
-    cached.scope.steps === scope.steps
+    cached.scope.collections === scope.collections &&
+    cached.scope.steps === scope.steps &&
+    cached.scope.root === scope.root
   ) {
     return cached;
   }
@@ -333,24 +355,59 @@ const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) =>
 
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
-  const { types } = scope;
+  const { types, collections } = scope;
+  // A collection's records are seeded as a resource's objects are, by `data.<name>`, through its operations.
+  const collectionOf = (id: unknown) =>
+    (id as string).startsWith(`${DATA_VENDOR}.`)
+      ? collections.get((id as string).slice(DATA_VENDOR.length + 1))
+      : undefined;
+  const seedable = new Map<string, unknown>([
+    ...types,
+    ...[...collections.keys()].map((n) => [`${DATA_VENDOR}.${n}`, n] as const),
+  ]);
   const parameterTypes: ParameterTypeSpec[] = [
     { name: "op", regexp: /\S+/, transformer: known("operation", scope.ops) },
     { name: "workflow", regexp: /\S+/, transformer: known("workflow", scope.workflows) },
     { name: "who", regexp: /\S+/, transformer: (s) => s },
-    { name: "resource", regexp: /\S+/, transformer: known("resource type", types) },
+    { name: "resource", regexp: /\S+/, transformer: known("resource type", seedable) },
     // A declared resource, as a drift report names it: `<file>#<export>`.
     { name: "declared", regexp: /[^\s#]+#\S+/, transformer: (s) => s },
     { name: "field", regexp: /\S+/, transformer: (s) => s },
   ];
   const opOf = (id: unknown) => scope.ops.get(id as string)!;
   const workflowOf = (name: unknown) => scope.workflows.get(name as string)!;
+  // The people as the root's data files declare them when a step names one (`readPeople`, read
+  // again only once a file changed): while they declare no one, any id and any group go.
+  /** `who`, as a run's start admits them (`admit`): a declared person or agent. */
+  const actorNamed = (who: string) => {
+    const declared = readPeople(scope.root);
+    try {
+      return admit({ id: who }, declared).id;
+    } catch (err) {
+      if (errorCode(err) !== "not_admitted" || declared.problems.length) throw err;
+      const ids = [...principalIdsOf(declared.people), ...RUNTIME_AGENTS].join(", ");
+      throw new Error(`${who} is not a declared person or agent; resources/ declares ${ids}`, { cause: err });
+    }
+  };
+  /** `group`, a declared group or `agents`, while the people's files have no problems. */
+  const groupNamed = (group: string) => {
+    const { people, problems } = readPeople(scope.root);
+    if (problems.length) {
+      throw new Error(
+        `no group can be told while the people's files have problems: ${problems.map(problemLine).join("; ")}`,
+      );
+    }
+    const groups = groupNamesOf(people);
+    if (!declaresPeople(people) || groups.includes(group)) return group;
+    throw new Error(`no group "${group}"; resources/ declares ${groups.join(", ")}`);
+  };
   /** A resource step's object: its type's id, vendor and type, and its import id. */
   const object = (id: unknown, name: unknown) => {
     const { vendor, type } = types.get(id as string)!;
     return { resource: id as string, vendor, type, name: name as string };
   };
   const rules: Rule[] = [
+    { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who as string) },
     {
       kind: "given",
       source: "{op} was called with",
@@ -368,21 +425,32 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       kind: "given",
       source: "{resource} {string} has",
       takes: TAKES_OBJECT,
-      read: ([resource, name], pickle) => [
-        {
-          ...object(resource, name),
-          fields: fieldsFrom(
-            pickle,
-            types.get(resource as string)!.schema,
-            `${resource as string} "${name as string}"`,
-          ),
-        },
-      ],
+      read: ([resource, name], pickle) => {
+        const owner = `${resource as string} "${name as string}"`;
+        const c = collectionOf(resource);
+        if (c) {
+          // The record with its key, the fields the step gives, and the rest made up.
+          const record = shapeOf(opOf(c.save.id).input).record!;
+          const fields = fieldsFrom(pickle, record, owner);
+          if (Object.hasOwn(fields, c.key) && fields[c.key] !== name) {
+            throw new Error(
+              `${c.key} in ${owner} is ${JSON.stringify(fields[c.key])}: it is the key, "${name as string}"`,
+            );
+          }
+          return [{ op: c.save.id, input: { record: fill(record, { ...fields, [c.key]: name }) } }];
+        }
+        return [
+          { ...object(resource, name), fields: fieldsFrom(pickle, types.get(resource as string)!.schema, owner) },
+        ];
+      },
     },
     {
       kind: "given",
       source: "{resource} {string} is gone",
-      read: ([resource, name]) => [{ ...object(resource, name), gone: true }],
+      read: ([resource, name]) => {
+        const c = collectionOf(resource);
+        return [c ? { op: c.delete.id, input: { key: name } } : { ...object(resource, name), gone: true }];
+      },
     },
     {
       kind: "when",
@@ -448,11 +516,22 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
       source: "{op} was denied",
       read: ([op]) => expecting({ op: op as string, decision: "denied" }),
     },
+    {
+      kind: "then",
+      source: "{op} was denied with {string}",
+      read: ([op, reason]) => expecting({ op: op as string, decision: "denied", reason: reason as string }),
+    },
     {
       kind: "then",
       source: "{op} was held for {who}",
       read: ([op, who]) => expecting({ op: op as string, decision: "held", approver: who as string }),
     },
+    {
+      kind: "then",
+      source: "{op} was held for group {string}",
+      read: ([op, group]) =>
+        expecting({ op: op as string, decision: "held", approver: { group: groupNamed(group as string) } }),
+    },
     {
       kind: "then",
       source: "step {string} was called with",
@@ -650,7 +729,8 @@ function lastCall(records: readonly LedgerRecord[]): CallRecord | string {
 
 /** Every step the scope knows, for an error: the generic ones by keyword, then each operation's phrases and each step library's steps under its name. */
 function knownSteps(rules: Rule[]): string {
-  const keyword = (kind: Rule["kind"]) => (kind === "any" ? "Given/When/Then" : kind[0]!.toUpperCase() + kind.slice(1));
+  const keyword = (kind: Rule["kind"]) =>
+    kind === "any" ? "Given/When/Then" : kind === "actor" ? "Given" : kind[0]!.toUpperCase() + kind.slice(1);
   const line = (r: Rule) => `${keyword(r.kind)} ${r.source}${r.takes ? ` (and ${r.takes})` : ""}`;
   const { generic = [], ...groups } = Object.groupBy(rules, (r) => r.group ?? "generic");
   return [
@@ -804,7 +884,9 @@ const ambiguous = (text: string, sources: string[]) =>
 function ruleFor(built: Built, expression: string, pickle: PickleStep): Rule {
   const kind = pickle.type && KINDS[pickle.type];
   if (!kind) throw new Error(`"${pickle.text}" needs a Given, When or Then before it`);
-  const rules = built.byExpression.get(expression)!.filter((r) => r.kind === kind || r.kind === "any");
+  const rules = built.byExpression
+    .get(expression)!
+    .filter((r) => r.kind === kind || r.kind === "any" || (r.kind === "actor" && kind === "given"));
   if (rules.length === 0) throw new Error(noMatch(built, pickle.text));
   if (rules.length > 1)
     throw new Error(
@@ -837,6 +919,11 @@ function compileWorld(built: Built, specs: Map<string, Spec>) {
         const { text } = pickle;
         const step: ScenarioStep = { text, kind: KINDS[pickle.type!]! };
         switch (rule.kind) {
+          case "actor":
+            if (spec.startedBy !== undefined)
+              throw new Error(`${spec.startedBy} is acting already: a run has one actor`);
+            spec.startedBy = rule.read(args, pickle);
+            break;
           case "given": {
             const items = rule.read(args, pickle);
             spec.given.push(...items.map((item) => ({ step: text, ...item }) as Given));
@@ -988,6 +1075,8 @@ function testWorld(built: Built, { driver, fake }: FeatureTarget) {
             throw new Error(
               `"${text}" decides an approval: a step for a scenario in scenarios/, not an operation's own test`,
             );
+          case "actor":
+            throw new Error(`"${text}" says who starts a run: a step for a scenario in scenarios/`);
           case "then": {
             const detail = rule.read(args, pickle).verify(viewOf(records));
             if (detail !== undefined) throw new Error(detail);
@@ -1179,18 +1268,22 @@ async function compile(scope: Scope, dir: string, files: string[]): Promise<Load
 }
 
 /**
- * Each scope's scenarios as last read, with the stamp of the files they were read from. By
- * scope, since what a file means depends on its operations and workflows.
+ * Each scope's scenarios as last read, with the stamp of the files they were read from and the
+ * people they were checked against (`readPeople`'s answer, the same object until a data file
+ * changes). By scope, since what a file means depends on its operations and workflows.
  */
-const loadedByScope = new WeakMap<Scope, { stamp: string; loaded: Promise<LoadedScenarios> }>();
+const loadedByScope = new WeakMap<
+  Scope,
+  { stamp: string; people: DeclaredPeople | undefined; loaded: Promise<LoadedScenarios> }
+>();
 
 /**
  * Every scenario in the `.feature` files under `scenarios` (a `file:` URL to a directory),
  * compiled by Cucumber, with an error for each file that does not compile and each name used
  * twice. No directory, or none given, is no scenarios. Rejects when an operation's phrase names
  * a field it lacks. The files are compiled again only once one is added, removed or written
- * (its name, `mtimeMs` or size changes): until then each call returns the same object, which
- * callers must not change.
+ * (its name, `mtimeMs` or size changes), or the people's data files change: until then each
+ * call returns the same object, which callers must not change.
  */
 export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
   if (!scope.scenarios) return { scenarios: [], errors: [] };
@@ -1206,10 +1299,12 @@ export async function loadScenarios(scope: Scope): Promise<LoadedScenarios> {
       return [file, mtimeMs, size];
     }),
   ]);
+  // None without a root, which declares no one.
+  const people = scope.root === undefined ? undefined : readPeople(scope.root);
   const cached = loadedByScope.get(scope);
-  if (cached?.stamp === stamp) return cached.loaded;
+  if (cached?.stamp === stamp && cached.people === people) return cached.loaded;
   const loaded = files.length ? compile(scope, dir, files) : Promise.resolve({ scenarios: [], errors: [] });
-  loadedByScope.set(scope, { stamp, loaded });
+  loadedByScope.set(scope, { stamp, people, loaded });
   // A compile that throws (a bug) is not kept: the next call tries again.
   loaded.catch(() => {
     if (loadedByScope.get(scope)?.loaded === loaded) loadedByScope.delete(scope);

package/src/scenarios.ts

@@ -18,21 +18,28 @@ export interface RunScenarioOptions {
   client: SanomaClient;
   /** What the scenario was loaded from (`loadScenarios`), whose feature files its run is checked against: the resolved config. */
   scope: Scope;
-  /** Who starts the run. Defaults to `{ id: "scenarios" }`. */
-  startedBy?: Principal;
+  /**
+   * Who starts the run, by id (`"ada"` or `{ id: "ada" }`), unless the scenario says who is acting.
+   * Defaults to `scenarios`, one of the runtime's own agents.
+   */
+  startedBy?: Principal | string;
   /** How long the run may take, passed to `drive`. */
   timeoutMs?: number;
 }
 
 /**
- * Runs a scenario as a sandbox run: starts its workflow with its input, decides its approvals
- * as it says, and checks the run's ledger against it (`check`: Cucumber runs its `Then` steps).
+ * Runs a scenario as a sandbox run: starts its workflow with its input, as whoever it says is
+ * acting, decides its approvals as it says, and checks the run's ledger against it (`check`:
+ * Cucumber runs its `Then` steps).
  */
 export async function runScenario(
   scenario: Scenario,
-  { client, scope, startedBy = { id: "scenarios" }, timeoutMs }: RunScenarioOptions,
+  { client, scope, startedBy = "scenarios", timeoutMs }: RunScenarioOptions,
 ): Promise<{ runId: string; run: RunSummary; ledger: LedgerRecord[]; checks: Check[] }> {
-  const runId = await client.start(scenario.workflow, scenario.input, { startedBy, sandbox: scenario.name });
+  const runId = await client.start(scenario.workflow, scenario.input, {
+    startedBy: scenario.startedBy ?? startedBy,
+    sandbox: scenario.name,
+  });
   const run = await drive(client, runId, scenario, { timeoutMs });
   const ledger = await client.ledger(runId);
   return { runId, run, ledger, checks: await check(scope, scenario, ledger) };
@@ -49,8 +56,8 @@ export interface ScenarioFailure {
 export interface RunScenariosOptions {
   /** The Postgres the worker and the client run on, instead of the config's: a database of its own. */
   databaseUrl: string;
-  /** Who starts the runs. Defaults to `{ id: "scenarios" }`. */
-  startedBy?: Principal;
+  /** Who starts the runs whose scenario does not say who is acting (`runScenario`'s). */
+  startedBy?: Principal | string;
   /** How long each run may take (`drive`'s; 15 seconds by default). */
   timeoutMs?: number;
   /** Receives a line per scenario as it ends. */

package/src/schema.ts

@@ -0,0 +1,261 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type {
+  DetailedError,
+  EntityType,
+  RecordType,
+  SchemaJson,
+  Type,
+  TypeOfAttribute,
+} from "@cedar-policy/cedar-wasm/nodejs";
+import { recordSchemaOf } from "./collection.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { jsonSchemaOf } from "./define.ts";
+import { isObject } from "./resource.ts";
+import { DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
+
+// The Cedar schema a company's policies are validated and decided against: made from the
+// resolved config and the people, in memory for the evaluator, and written as text to
+// `.sanoma/schema.cedarschema` for the policies' author.
+
+const require = createRequire(import.meta.url);
+let wasm: typeof import("@cedar-policy/cedar-wasm/nodejs") | undefined;
+
+/** `@cedar-policy/cedar-wasm`'s Node build, loaded (synchronously, once) on first use, so a process that never decides with Cedar never loads it. */
+export const cedarWasm = () => (wasm ??= require("@cedar-policy/cedar-wasm/nodejs") as typeof wasm)!;
+
+/** The schema as Cedar's JSON format has it. */
+export type CedarSchemaJson = SchemaJson<string>;
+
+/** Where the schema's text is written, under a company's root. */
+export const SCHEMA_FILE = join(".sanoma", "schema.cedarschema");
+
+/** The schema's namespace: policies name `Sanoma::Group::"finance"`, `Sanoma::Action::"effect:money"`. */
+export const NAMESPACE = "Sanoma";
+
+/** The action group every workflow start (`workflow:<name>`) is in. */
+export const START = "start";
+
+const STRING = { type: "EntityOrCommon", name: "String" } as const;
+const LONG = { type: "EntityOrCommon", name: "Long" } as const;
+const BOOL = { type: "EntityOrCommon", name: "Bool" } as const;
+const entity = (name: string) => ({ type: "Entity", name }) as const;
+const record = (attributes: Record<string, TypeOfAttribute<string>>): RecordType<string> & { type: "Record" } => ({
+  type: "Record",
+  attributes,
+});
+const optional = (type: Type<string>): TypeOfAttribute<string> => ({ ...type, required: false });
+
+/**
+ * The Cedar type of a zod schema's parsed value (`io: "output"`: what the policy is given, defaults
+ * filled and transforms applied), through its JSON Schema; undefined when it has none.
+ */
+const typeOf = (schema: Parameters<typeof jsonSchemaOf>[0]) => {
+  const json = jsonSchemaOf(schema, "output");
+  return cedarType(json, { root: json, seen: new Set() });
+};
+
+/** A context's `input`, typed from a zod schema: none when it has no Cedar type. */
+const input = (schema: Parameters<typeof jsonSchemaOf>[0]): Record<string, TypeOfAttribute<string>> => {
+  const type = typeOf(schema);
+  return type ? { input: type } : {};
+};
+
+/** A collection's operations that change a record, whose context has the record as it was (`before`). */
+const WRITES = new Set(["save", "delete"]);
+
+/**
+ * The Cedar schema for a resolved config and its people, namespace `Sanoma`:
+ *
+ * - `entity Group enum [...]`, the declared groups and `agents`, so a policy naming another fails
+ *   validation; `entity Principal in [Group] { onBehalfOf?: Principal }`; `Collection`;
+ *   `Target in [Collection]`; `Workflow`;
+ * - an action per operation id, in its effect's group (`effect:money`), on a `Target`, with
+ *   `context` `{ input, before? }`: `input` from the operation's input schema, `before` the record
+ *   as it was for a collection's `save` and `delete`;
+ * - `workflow:<name>` per workflow, in the group `start`, on a `Workflow`, with its `input`.
+ *
+ * Zod to Cedar, through the JSON Schema of the parsed value: string and enum `String`, integer `Long`, boolean `Bool`,
+ * object a record (its optional and nullable fields optional), array a `Set`; a decimal number
+ * is a `String`; a field with no Cedar type (a union of types, a map, a recursive type) is left
+ * out, so a policy naming it fails validation. Pure: the same config and people give the same schema.
+ */
+function buildSchema(
+  resolved: Pick<ResolvedConfig, "ops" | "workflows" | "collections">,
+  people: readonly PeopleResource[],
+): CedarSchemaJson {
+  const applies = (resource: string, context: Record<string, TypeOfAttribute<string>>) => ({
+    principalTypes: ["Principal"],
+    resourceTypes: [resource],
+    context: record(context),
+  });
+  const actions: CedarSchemaJson[string]["actions"] = { [START]: {} };
+  for (const effect of EFFECTS) actions[`effect:${effect}`] = {};
+  for (const op of [...resolved.ops.values()].toSorted((a, b) => a.id.localeCompare(b.id))) {
+    const collection =
+      op.vendor === DATA_VENDOR && WRITES.has(op.name) ? resolved.collections.get(op.resource) : undefined;
+    const before = collection && typeOf(recordSchemaOf(collection));
+    actions[op.id] = {
+      memberOf: [{ id: `effect:${op.effect}` }],
+      appliesTo: applies("Target", { ...input(op.input), ...(before && { before: optional(before) }) }),
+    };
+  }
+  for (const name of [...resolved.workflows.keys()].toSorted()) {
+    actions[`${WORKFLOW_ACTION}${name}`] = {
+      memberOf: [{ id: START }],
+      appliesTo: applies("Workflow", input(resolved.workflows.get(name)!.input)),
+    };
+  }
+  const entityTypes: Record<string, EntityType<string>> = {
+    Group: { enum: groupNamesOf(people) },
+    Principal: { memberOfTypes: ["Group"], shape: record({ onBehalfOf: optional(entity("Principal")) }) },
+    Collection: {},
+    Target: { memberOfTypes: ["Collection"] },
+    Workflow: {},
+  };
+  return { [NAMESPACE]: { entityTypes, actions } };
+}
+
+const schemas = new WeakMap<object, WeakMap<readonly PeopleResource[], CedarSchemaJson>>();
+
+/**
+ * The Cedar schema for a resolved config and its people (`buildSchema`), made once for each pair:
+ * validating, deciding and writing it share one.
+ */
+export function schemaOf(
+  resolved: Pick<ResolvedConfig, "ops" | "workflows" | "collections">,
+  people: readonly PeopleResource[],
+): CedarSchemaJson {
+  let byPeople = schemas.get(resolved.ops);
+  if (!byPeople) schemas.set(resolved.ops, (byPeople = new WeakMap()));
+  let schema = byPeople.get(people);
+  if (!schema) byPeople.set(people, (schema = buildSchema(resolved, people)));
+  return schema;
+}
+
+/** The schema as Cedar's text, through the package's own `schemaToText`: what `.sanoma/schema.cedarschema` holds. */
+export function schemaText(schema: CedarSchemaJson): string {
+  const answer = cedarWasm().schemaToText(schema);
+  if (answer.type === "failure") {
+    throw new Error(`The Cedar schema does not print: ${answer.errors.map(messageOf).join("; ")}`);
+  }
+  return answer.text;
+}
+
+interface Typing {
+  root: Record<string, unknown>;
+  /** The schemas being typed, to leave a recursive one out. */
+  seen: Set<unknown>;
+}
+
+/** The Cedar type of a JSON Schema (`jsonSchemaOf`'s, draft 2020-12), or undefined when it has none. */
+function cedarType(schema: unknown, typing: Typing): Type<string> | undefined {
+  if (!isObject(schema) || typing.seen.has(schema)) return undefined;
+  if (typeof schema.$ref === "string") {
+    const defs = typing.root.$defs as Record<string, unknown> | undefined;
+    const target = schema.$ref.startsWith("#/$defs/") ? defs?.[schema.$ref.slice("#/$defs/".length)] : undefined;
+    return within(schema, typing, () => cedarType(target, typing));
+  }
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(variants)) {
+    const each = within(schema, typing, () => variants.filter((v) => !isNull(v)).map((v) => cedarType(v, typing)));
+    const first = each[0];
+    return first && each.every((t) => t && JSON.stringify(t) === JSON.stringify(first)) ? first : undefined;
+  }
+  const values = Array.isArray(schema.enum) ? schema.enum : "const" in schema ? [schema.const] : undefined;
+  if (values) {
+    if (values.every((v) => typeof v === "string")) return STRING;
+    if (values.every((v) => Number.isSafeInteger(v))) return LONG;
+    return values.every((v) => typeof v === "boolean") ? BOOL : undefined;
+  }
+  const types = Array.isArray(schema.type) ? schema.type.filter((t) => t !== "null") : [schema.type];
+  if (types.length !== 1) return undefined;
+  switch (types[0]) {
+    case "string":
+    case "number":
+      // Cedar has no decimal number: one is compared as text.
+      return STRING;
+    case "integer":
+      return LONG;
+    case "boolean":
+      return BOOL;
+    case "array": {
+      const element = within(schema, typing, () => cedarType(schema.items, typing));
+      return element && { type: "Set", element };
+    }
+    case "object": {
+      // A map's keys are not known: it has no Cedar type.
+      if (!isObject(schema.properties)) return schema.additionalProperties ? undefined : record({});
+      const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+      const attributes: Record<string, TypeOfAttribute<string>> = {};
+      for (const [name, property] of Object.entries(schema.properties)) {
+        const type = within(schema, typing, () => cedarType(property, typing));
+        if (type) attributes[name] = required.has(name) && !allowsNull(property) ? type : optional(type);
+      }
+      return record(attributes);
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** `type()` with `schema` marked as being typed, so a reference back to it is not followed. */
+function within<T>(schema: unknown, typing: Typing, type: () => T): T {
+  typing.seen.add(schema);
+  try {
+    return type();
+  } finally {
+    typing.seen.delete(schema);
+  }
+}
+
+const isNull = (schema: unknown) => isObject(schema) && schema.type === "null";
+
+/** True when a JSON Schema accepts `null`: its value is then optional in Cedar, which has no null. */
+const allowsNull = (schema: unknown): boolean =>
+  isObject(schema) &&
+  (isNull(schema) ||
+    (Array.isArray(schema.type) && schema.type.includes("null")) ||
+    [schema.anyOf, schema.oneOf].some((v) => Array.isArray(v) && v.some(isNull)));
+
+/** Cedar's message, with its help when it has one. */
+export const messageOf = (e: DetailedError) => (e.help ? `${e.message} (${e.help})` : e.message);
+
+/** An action's context type in the schema: a record, when the action is there. */
+export const contextTypeOf = (schema: CedarSchemaJson, action: string) =>
+  schema[NAMESPACE]?.actions[action]?.appliesTo?.context as (RecordType<string> & { type: "Record" }) | undefined;
+
+/**
+ * A value as Cedar takes it for a type `schemaOf` wrote (`cedarType`'s other side): a record's
+ * fields it declares only, a set's elements, a number where it is a `String` as text. An unknown
+ * (`{ __extn: unknown }`) passes as it is; what does not fit is left out (undefined), as `null` is.
+ */
+export function cedarValue(value: unknown, type: Type<string>): unknown {
+  if (value === null || value === undefined) return undefined;
+  if (isObject(value) && "__extn" in value) return value;
+  const t = type as { type: string; name?: string; element?: Type<string>; attributes?: Record<string, Type<string>> };
+  if (t.attributes) {
+    if (!isObject(value)) return undefined;
+    return Object.fromEntries(
+      Object.entries(t.attributes).flatMap(([name, field]) => {
+        const shaped = cedarValue(value[name], field);
+        return shaped === undefined ? [] : [[name, shaped]];
+      }),
+    );
+  }
+  if (t.type === "Set") {
+    return Array.isArray(value)
+      ? value.map((v) => cedarValue(v, t.element!)).filter((v) => v !== undefined)
+      : undefined;
+  }
+  switch (t.name) {
+    case STRING.name:
+      return typeof value === "string" ? value : typeof value === "number" ? String(value) : undefined;
+    case LONG.name:
+      return Number.isSafeInteger(value) ? value : undefined;
+    case BOOL.name:
+      return typeof value === "boolean" ? value : undefined;
+    default:
+      return undefined;
+  }
+}