@sanoma-ai/workflows 0.5.0 → 0.7.0

package/src/approvals.ts

@@ -1,13 +1,13 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
 import { z } from "zod";
 import { type ApprovalRequest, type ApprovalResult, type ApprovalState, Principal } from "./define.ts";
-import { RejectedError } from "./errors.ts";
+import { RejectedError, WithdrawnError } from "./errors.ts";
 import { entry, write } from "./ledger.ts";
 import { warn } from "./log.ts";
 import type { Placed } from "./call.ts";
 import type { Run } from "./run.ts";
 import { readPeople } from "./resources.ts";
-import { approverLabel, OWN_CHANGE, refusalOf } from "./shared.ts";
+import { approverLabel, isVisitor, OWN_CHANGE, refusalOf } from "./shared.ts";
 
 // The wire contract between a run waiting on approvals and whoever decides them. The client
 // imports this file and never the worker's.
@@ -37,8 +37,31 @@ export const ApprovalMessage = z.object({
 });
 export type ApprovalMessage = z.infer<typeof ApprovalMessage>;
 
+/**
+ * A withdrawal of a pending approval, as sent to a run on the approval's topic: `withdraw` says
+ * why, and `by` who withdraws it, which the run checks (`withdrawalRefusal`) and records. `id`
+ * names the message as a decision's does; `SanomaClient.withdraw` sets one.
+ */
+export const ApprovalWithdrawal = z.object({
+  withdraw: z.string().trim().min(1),
+  by: Principal,
+  id: z.string().optional(),
+});
+export type ApprovalWithdrawal = z.infer<typeof ApprovalWithdrawal>;
+
 const statusOf = (decision: ApprovalMessage["decision"]) => (decision === "approve" ? "approved" : "rejected");
 
+/**
+ * Why `by` may not withdraw the approval of a run `starter` started, or undefined when they may:
+ * the starter may withdraw what their own run asks (never a visitor, as every anonymous one shares
+ * an id), anyone else only as one who may decide it.
+ */
+export const withdrawalRefusal = (
+  approval: Pick<ApprovalState, "approver">,
+  by: Principal,
+  starter: string | undefined,
+): string | undefined => (by.id === starter && !isVisitor(by) ? undefined : refusalOf(approval, by, {}, []));
+
 /** The sender's id, from a message that may not be a valid decision. */
 function senderOf(raw: unknown): string | undefined {
   const by = typeof raw === "object" && raw !== null ? (raw as { by?: unknown }).by : undefined;
@@ -64,7 +87,8 @@ export interface HeldCall {
 
 /**
  * Waits, durably, for a decision from someone who may make it (`mayDecide`: the run's own actor
- * only while nobody else could). Throws `RejectedError` on a rejection. Without `held`, the workflow asked
+ * only while nobody else could). Throws `RejectedError` on a rejection and `WithdrawnError` on a
+ * withdrawal (`ApprovalWithdrawal`). Without `held`, the workflow asked
  * (`ctx.approval`); with it, the policy did, and `place` is the held call's outline node and name
  * (none for a run's start, which is no call in the outline).
  */
@@ -111,7 +135,10 @@ export async function awaitApproval(
     ),
   );
   for (;;) {
-    const raw = await DBOS.recv<unknown>(topicOf(state.id), { timeoutSeconds: 24 * 60 * 60 });
+    // A decision comes from a request (`SanomaClient.decide`), which wakes a stopped worker: no deadline.
+    const raw = await run.state.deadlines.waiting(run.id, { kind: "approval" }, () =>
+      DBOS.recv<unknown>(topicOf(state.id), { timeoutSeconds: 24 * 60 * 60 }),
+    );
     if (raw === null || raw === undefined) {
       warn(`run ${run.id}: approval ${state.id} ("${title}") is still waiting for ${approverLabel(state.approver)}`);
       continue;
@@ -119,6 +146,18 @@ export async function awaitApproval(
     const at = await DBOS.now();
     const parsed = ApprovalMessage.safeParse(raw);
     const msg = parsed.success ? parsed.data : undefined;
+    const withdrawal = msg ? undefined : ApprovalWithdrawal.safeParse(raw).data;
+    if (withdrawal) {
+      const { withdraw: reason, by, id } = withdrawal;
+      const refused = withdrawalRefusal(state, by, run.actor.id);
+      if (refused === undefined) {
+        state.decidedWith = id;
+        await withdrawn(run, [state], reason, at, by.id);
+        throw new WithdrawnError(title, state.id, reason);
+      }
+      await refuse(run, state, { by: by.id, ...(id === undefined ? {} : { id }), at, reason: refused });
+      continue;
+    }
     // The people matter only when the run's own actor decides (`refusalOf`): then they are read as
     // the data files declare them now, in a step, so a replay decides the same. While those files
     // have problems, someone else may be missing from them, so the starter is refused.
@@ -135,22 +174,12 @@ export async function awaitApproval(
         : (refusalOf(state, msg.by, run, []) ?? null);
     if (!msg || refusal !== null) {
       const by = msg?.by.id ?? senderOf(raw);
-      const reason = refusal ?? "not a valid decision message";
-      state.refused.push({
+      await refuse(run, state, {
         ...(by === undefined ? {} : { by }),
         ...(msg?.id === undefined ? {} : { id: msg.id }),
         at,
-        reason,
+        reason: refusal ?? "not a valid decision message",
       });
-      await DBOS.setEvent(APPROVALS_EVENT, all);
-      await write(
-        run,
-        entry(
-          run,
-          { type: "approval.refused", approval: state.id, ...(by === undefined ? {} : { by }), reason },
-          { key: `${state.id}:refused:${state.refused.length}`, at },
-        ),
-      );
       continue;
     }
     // The run's own actor decides only when nobody else could, which the record says.
@@ -191,3 +220,47 @@ const heldOf = ({ seq, reasons }: HeldCall) => ({
   ...(seq !== undefined && { opSeq: seq }),
   ...(reasons !== undefined && { reasons }),
 });
+
+/**
+ * Withdraws every approval of the run that is approved and covers the operation `covering`, so
+ * none lifts a hold on it again (`approvedFor` reads only approved ones): as a change does when it
+ * gets a new commit. Called from the run's own body, never a step: the approvals it finds and the
+ * records it writes depend only on the run's history, so a replay does the same.
+ */
+export async function withdrawApprovals(run: Run, covering: string, reason: string): Promise<void> {
+  const retired = run.approvals.filter((a) => a.status === "approved" && a.covers.includes(covering));
+  if (!retired.length) return;
+  await withdrawn(run, retired, reason, await DBOS.now());
+}
+
+/** Records a message the approval ignored, on the approval and in the ledger. */
+async function refuse(run: Run, state: ApprovalState, refused: ApprovalState["refused"][number]) {
+  state.refused.push(refused);
+  await DBOS.setEvent(APPROVALS_EVENT, run.approvals);
+  const { by, reason, at } = refused;
+  await write(
+    run,
+    entry(
+      run,
+      { type: "approval.refused", approval: state.id, ...(by === undefined ? {} : { by }), reason },
+      { key: `${state.id}:refused:${state.refused.length}`, at },
+    ),
+  );
+}
+
+/**
+ * Withdraws the approvals (by `by`, when someone rather than the run does) and publishes them as a
+ * decision is: the list, then the ledger, then each one's decision event.
+ */
+async function withdrawn(run: Run, approvals: readonly ApprovalState[], reason: string, at: number, by?: string) {
+  const who = by === undefined ? {} : { by };
+  for (const a of approvals) {
+    Object.assign(a, { status: "withdrawn", withdrawnReason: reason, withdrawnAt: at });
+    if (by !== undefined) a.withdrawnBy = by;
+  }
+  await DBOS.setEvent(APPROVALS_EVENT, run.approvals);
+  for (const a of approvals) {
+    await write(run, entry(run, { type: "approval.withdrawn", approval: a.id, ...who, reason }, { key: a.id, at }));
+  }
+  for (const a of approvals) await DBOS.setEvent(decisionEventOf(a.id), a);
+}

package/src/call.ts

@@ -31,11 +31,12 @@ import { type CallContext, isOp, type Op } from "./op.ts";
 import { callAt, callName, type CallNode } from "./outline.ts";
 import { allowAll, type Decision, type Policy, type PolicyCall, policyOpOf, type RecordedDecision } from "./policy.ts";
 import type { Run, StartHold, WorkerState } from "./run.ts";
-import { isChangeOp } from "./resource.ts";
+import { reservedFor, runtimeHold } from "./change.ts";
+import { readPeople } from "./resources.ts";
 import {
-  APPLY_WORKFLOW,
   approverLabel,
   CALL_WORKFLOW,
+  CHANGE_MERGE,
   DATA_VENDOR,
   errorMessage,
   fitsOp,
@@ -276,11 +277,16 @@ function targetOf(op: Op, input: unknown): { target?: string } {
 
 /**
  * Asks the policy about one call, with the record a collection's `save` or
- * `delete` replaces as `before` (`beforeOf`). Runs inside a step, so it must have no side effects
- * of its own.
+ * `delete` replaces as `before` (`beforeOf`). The runtime's own rule first (`runtimeHold`, over
+ * the running instance's people): while it holds or denies, the company's policy is not asked.
+ * Runs inside a step, so it must have no side effects of its own.
  */
 export async function decide(run: Run, op: Op, input: unknown): Promise<RecordedDecision> {
   const seen = { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) };
+  // Only a merge is the rule's: no other call reads the people's files.
+  const held =
+    op.id === CHANGE_MERGE ? runtimeHold(op.id, input, seen.approvals, readPeople(run.state.root).people) : undefined;
+  if (held) return held;
   const { policy } = run.state;
   // Keyed by the call (`seq` was taken for it), so a fake answers each read afresh.
   const before = await beforeOf(policy, op, input, run.state.collections, (get, key) =>
@@ -299,7 +305,7 @@ const driverOf = (run: Run, id: string) => (run.sandbox === undefined ? run.stat
 /** The secrets a run's calls read: its own in a sandbox run, else the stored ones. */
 const secretsOf = (run: Run) => (run.sandbox === undefined ? run.state.secrets : run.fakeSecrets!);
 
-/** One call of `op` as `actor` in `run`, as a policy sees it. */
+/** One call of `op` as `actor` in `run`, as a policy sees it: a merge's `entity`, the change's facts. */
 const callOf = (op: Op, input: unknown, actor: Principal, run: PolicyCall["run"]): PolicyCall => ({
   op: policyOpOf(op),
   effect: op.effect,
@@ -307,6 +313,7 @@ const callOf = (op: Op, input: unknown, actor: Principal, run: PolicyCall["run"]
   input,
   actor,
   run,
+  ...(op.id === CHANGE_MERGE && { entity: (input as { facts: Record<string, unknown> }).facts }),
 });
 
 /**
@@ -413,9 +420,11 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
         : `No connector or fake for ${id} in this worker: no fake its connectors attach implements it`,
     );
   }
-  // Only apply changes a declared resource; `resolveConfig` refuses any other workflow that uses such an operation.
-  if (isChangeOp(op, run.state.types) && run.workflow !== APPLY_WORKFLOW) {
-    throw new SanomaError("invalid_input", `${op.id} changes a declared resource, which only ${APPLY_WORKFLOW} does`, {
+  // Only apply changes a declared resource, and only change takes a change's steps; `resolveConfig`
+  // refuses any other workflow that uses such an operation.
+  const reserved = reservedFor(op, run.state.types);
+  if (reserved && run.workflow !== reserved.workflow) {
+    throw new SanomaError("invalid_input", `${op.id} ${reserved.does}, which only ${reserved.workflow} does`, {
       op: op.id,
       workflow: run.workflow,
     });
@@ -452,7 +461,9 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
         reasons: decision.reasons,
       });
     } catch (err) {
-      if (errorCode(err) === "approval_rejected") {
+      // A rejection or a withdrawal stops the call: it is recorded as failed, naming the approval.
+      const code = errorCode(err);
+      if (code === "approval_rejected" || code === "approval_withdrawn") {
         const approval = (err as SanomaError).data.approvalId as string;
         const record = entry(run, { ...call, approval, error: errorInfo(err), durationMs: 0 }, { seq });
         await writeFailure(run, record, err);
@@ -567,29 +578,29 @@ async function all(run: Run, list: unknown, node: string): Promise<unknown[]> {
 
 /**
  * Waits, durably, until the time or for the duration the request names, and records when it
- * ends. For a duration that is the record's `at` plus the duration, one read of the runtime's
- * clock (`Date.now()`, which adds no DBOS call): a replay may compute another, but the store keeps
- * the first record with the id, so the record says what the first execution waited for.
+ * ends. For a duration that is the record's `at` plus the duration. The start is DBOS's clock
+ * (`DBOS.now()`, a step), so a replay reads back the first execution's and computes the same
+ * deadline: the one the worker's deadlines register while the run waits.
  */
 async function sleep(run: Run, raw: unknown, at: Placed) {
   const req = checkSleep(raw);
   const seq = run.seq++;
-  const started = Date.now();
-  let until: number;
-  let ms: number;
-  if ("until" in req) {
-    until = typeof req.until === "number" ? req.until : Date.parse(req.until);
-    ms = until - (await DBOS.now());
-  } else {
-    ms =
-      (req.ms ?? 0) +
-      (req.seconds ?? 0) * 1_000 +
-      (req.minutes ?? 0) * 60_000 +
-      (req.hours ?? 0) * 3_600_000 +
-      (req.days ?? 0) * 86_400_000;
-    until = started + ms;
-  }
+  const started = await DBOS.now();
+  const until =
+    "until" in req
+      ? typeof req.until === "number"
+        ? req.until
+        : Date.parse(req.until)
+      : started +
+        (req.ms ?? 0) +
+        (req.seconds ?? 0) * 1_000 +
+        (req.minutes ?? 0) * 60_000 +
+        (req.hours ?? 0) * 3_600_000 +
+        (req.days ?? 0) * 86_400_000;
+  const ms = until - started;
   await write(run, entry(run, { type: "sleep.started", ...at, until }, { seq, at: started }));
-  // A time already past waits not at all, and adds no step. A sandbox run never waits.
-  if (ms > 0 && run.sandbox === undefined) await DBOS.sleep(ms);
+  // A time already past waits not at all, and adds no sleep step. A sandbox run never waits.
+  if (ms > 0 && run.sandbox === undefined) {
+    await run.state.deadlines.waiting(run.id, { kind: "sleep", until }, () => DBOS.sleep(ms));
+  }
 }

package/src/cedar.ts

@@ -21,7 +21,7 @@ import {
   VISITOR_DENIED,
 } from "./policy.ts";
 import { admit, readPeople } from "./resources.ts";
-import { cedarValue, cedarWasm, contextTypeOf, messageOf, NAMESPACE, schemaOf } from "./schema.ts";
+import { cedarValue, cedarWasm, contextTypeOf, messageOf, NAMESPACE, schemaOf, shapeOf } from "./schema.ts";
 import {
   ANONYMOUS,
   approverLabel,
@@ -287,17 +287,30 @@ export function cedarPolicy(
     return { refusing: refusing?.p, holds };
   };
 
-  /** What `request` is about: a workflow start on its `Workflow`, an operation on its target, in its collection for `data`. */
+  /** The entity type `action` acts on, as the schema has it. */
+  const appliesTo = (action: string) => schema[NAMESPACE]?.actions[action]?.appliesTo?.resourceTypes?.[0];
+
+  /**
+   * What `request` is about: a workflow start on its `Workflow`; an operation on its target, in its
+   * collection for `data`; one on an entity type with attributes (a merge's `Change`) with those `entity` gives.
+   */
   const requestOf = (
     principal: Principal,
     action: string,
     target: string | undefined,
     context: (names: string[]) => Record<string, unknown>,
+    entity: (names: string[]) => Record<string, unknown>,
   ) => {
     const entities = directory.entities(principal);
+    const on = appliesTo(action);
+    const shape = on === undefined ? undefined : shapeOf(schema, on);
     let resource;
     if (action.startsWith(WORKFLOW_ACTION)) {
       resource = uid("Workflow", action.slice(WORKFLOW_ACTION.length));
+    } else if (shape) {
+      resource = uid(on!, target ?? action);
+      const attrs = cedarValue(entity(Object.keys(shape.attributes)), shape) ?? {};
+      entities.push({ uid: resource, attrs: attrs as Record<string, CedarValueJson>, parents: [] });
     } else {
       resource = uid("Target", target ?? action);
       const op = resolved.ops.get(action);
@@ -316,7 +329,8 @@ export function cedarPolicy(
 
   /**
    * May `actor` take `action` on `target` with `context`, given the run's `approvals` so far; at a
-   * start or a direct call (`atStart`), a visitor only where a company permit lets it in.
+   * start or a direct call (`atStart`), a visitor only where a company permit lets it in. `entity`,
+   * the attributes of what it acts on, when that has any (a `Change`).
    */
   const authorize = (
     actor: Principal,
@@ -325,13 +339,15 @@ export function cedarPolicy(
     context: Record<string, unknown>,
     approvals: PolicyCall["run"]["approvals"],
     atStart: boolean,
+    entity: Record<string, unknown> = {},
   ): Decision => {
     const principal = directory.principal(actor);
+    const attrs = () => entity;
     /** The answer of the policy set `id`. */
     const ask = (id: string) => {
       const check = (asked: Record<string, unknown>) =>
         cedar.statefulIsAuthorized({
-          ...requestOf(principal, action, target, () => asked),
+          ...requestOf(principal, action, target, () => asked, attrs),
           preparsedSchemaName: set,
           validateRequest: true,
           preparsedPolicySetId: id,
@@ -342,7 +358,7 @@ export function cedarPolicy(
       // action's groups given as entities: a policy reading a field the record lacks fails, so denies.
       const { before, ...rest } = context;
       if (answer.type === "success" || before === undefined || check(rest).type === "failure") return answer;
-      const request = requestOf(principal, action, target, () => context);
+      const request = requestOf(principal, action, target, () => context, attrs);
       const groups = schema[NAMESPACE]?.actions[action]?.memberOf ?? [];
       request.entities.push({ uid: request.action, attrs: {}, parents: groups.map((g) => uid("Action", g.id)) });
       return cedar.statefulIsAuthorized({ ...request, preparsedPolicySetId: id });
@@ -388,6 +404,7 @@ export function cedarPolicy(
       { input: call.input, ...(call.before !== undefined && { before: call.before }) },
       call.run.approvals,
       call.run.workflow === CALL_WORKFLOW,
+      call.entity,
     );
 
   const start = (actor: Principal, workflow: string, input: unknown, approvals: readonly ApprovalState[] = []) =>
@@ -398,7 +415,8 @@ export function cedarPolicy(
       const principal = directory.principal(actor);
       const partial = (asked: Record<string, string>) => {
         const answer = cedar.isAuthorizedPartial({
-          ...requestOf(principal, action.id, resource, unknown),
+          // A change's facts unknown too: a rule on them depends, one on any change holds.
+          ...requestOf(principal, action.id, resource, unknown, unknown),
           schema,
           validateRequest: false,
           policies: { staticPolicies: asked },

package/src/change.ts

@@ -0,0 +1,222 @@
+import { z } from "zod";
+import type { ApprovalState, Approver } from "./define.ts";
+import { defineConnector, defineDriver, type Driver, DriverError } from "./op.ts";
+import { approve, approvedFor, type Decision, deny } from "./policy.ts";
+import { isChangeOp, type Resource } from "./resource.ts";
+import { APPLY_WORKFLOW, CHANGE_MERGE, CHANGE_WORKFLOW, groupNamesOf, type PeopleResource } from "./shared.ts";
+import type { CheckResult } from "./source.ts";
+
+// A change: how a draft of the company's repository goes live, as the built-in `change` workflow
+// runs it (lane C5): its four operations on the built-in connector `sanoma`, the facts a policy
+// decides its merge on (the attributes of its `Sanoma::Change`), and the runtime's own rule that
+// a change to the rules waits for `admin`, before any company policy is asked.
+
+/**
+ * What the planner finds in a change, before the policy is asked: the attributes of the
+ * `Sanoma::Change` that `sanoma.change.merge` acts on, so a rule reads `resource.touches`.
+ */
+export const ChangeFacts = z.object({
+  /** Every path the change edits and each of its parent directories (`touchesOf`). */
+  touches: z.array(z.string()),
+  /** How many waiting runs are of a workflow the change edits, which the publish cannot move. */
+  strandedRuns: z.number().int(),
+  /** Those runs' ids. */
+  stranded: z.array(z.string()),
+  /** Whether `sanoma check` passed on the change. */
+  checksOk: z.boolean(),
+  /** Whether the change edits the rules: a policy or a people file, which wait for `admin` (`runtimeHold`). */
+  rules: z.boolean(),
+});
+export type ChangeFacts = z.infer<typeof ChangeFacts>;
+
+/** What opening a change takes: its draft's id, and the pull request's title, body and the change page's link. */
+export const ChangeInput = z.object({
+  id: z.string().regex(/^[\w-]{1,64}$/),
+  title: z.string().min(1),
+  body: z.string().optional(),
+  page: z.string().url().optional(),
+});
+export type ChangeInput = z.infer<typeof ChangeInput>;
+
+/** The change a call acts on: its policy target. */
+const target = ({ id }: { id: string }) => `change:${id}`;
+/** A change once it has a pull request: its draft's id and the pull request's number. */
+const opened = { id: ChangeInput.shape.id, number: z.number().int().positive() };
+
+/** The operations of a change, on the built-in connector `sanoma`: only the `change` workflow calls them. */
+export const changeOps = defineConnector("sanoma", {
+  change: {
+    open: {
+      effect: "write",
+      idempotent: true,
+      description: "Open a change: push its draft's branch and open a pull request for it",
+      input: ChangeInput,
+      output: z.object({ number: z.number().int(), url: z.string(), head: z.string(), branch: z.string() }),
+      target,
+      phrases: { expect: "change {id} is opened" },
+    },
+    review: {
+      effect: "write",
+      idempotent: true,
+      description: "Report Sanoma's review of a change on its pull request",
+      input: z.object({
+        ...opened,
+        head: z.string(),
+        state: z.enum(["pending", "failure"]),
+        description: z.string(),
+        page: z.string().url().optional(),
+      }),
+      output: z.object({}),
+      target,
+      phrases: { expect: "change {id} is reviewed" },
+    },
+    merge: {
+      effect: "write",
+      idempotent: true,
+      description: "Merge a change's pull request",
+      input: z.object({ ...opened, head: z.string(), title: z.string(), facts: ChangeFacts }),
+      output: z.object({
+        outcome: z.enum(["merged", "closed", "moved", "blocked"]),
+        sha: z.string().optional(),
+        reason: z.string().optional(),
+      }),
+      target,
+      phrases: { expect: "change {id} is merged" },
+    },
+    close: {
+      effect: "write",
+      idempotent: true,
+      description: "Close a change's pull request without merging it",
+      input: z.object(opened),
+      output: z.object({ closed: z.literal(true) }),
+      target,
+      phrases: { expect: "change {id} is closed" },
+    },
+  },
+});
+
+/**
+ * The built-in workflow that alone may call `op`, what the operation does and what to do instead:
+ * `apply` for a writable resource type's change operations (`isChangeOp`), `change` for
+ * `sanoma.change.*`; undefined for any other. `resolveConfig` refuses a workflow that uses one, and
+ * a run's call of one outside its workflow fails.
+ */
+export function reservedFor(
+  op: { readonly vendor: string; readonly resource: string; readonly name: string },
+  types: ReadonlyMap<string, Pick<Resource, "writable">>,
+): { workflow: string; does: string; instead: string } | undefined {
+  if (isChangeOp(op, types)) {
+    return { workflow: APPLY_WORKFLOW, does: "changes a declared resource", instead: "change the data file" };
+  }
+  if (op.vendor === "sanoma" && op.resource === "change") {
+    return { workflow: CHANGE_WORKFLOW, does: "changes the company's repository", instead: "send a draft for review" };
+  }
+  return undefined;
+}
+
+const notBuilt = async (): Promise<never> => {
+  throw new DriverError("not built", { retryable: false });
+};
+
+/** A placeholder: lane C5 replaces it with the driver over the repository's host. */
+export function changeDriver(): Driver {
+  return defineDriver(changeOps, { change: { open: notBuilt, review: notBuilt, merge: notBuilt, close: notBuilt } });
+}
+
+/**
+ * Each path, relative to the root with `/` between its parts, and each of its parent directories
+ * with a trailing `/`, sorted, each once: what a rule asks with `touches.contains("resources/finance/")`.
+ */
+export function touchesOf(files: readonly string[]): string[] {
+  const touches = new Set<string>();
+  for (const file of files) {
+    touches.add(file);
+    for (let end = file.indexOf("/"); end > 0; end = file.indexOf("/", end + 1)) touches.add(file.slice(0, end + 1));
+  }
+  return [...touches].toSorted();
+}
+
+/** The group the runtime holds a change to the rules for. */
+const ADMIN = "admin";
+/** The paths in `touches` that are the rules whatever `rules` says: the policies, and the template's people file. */
+const RULES = ["policies/", "resources/people.ts"];
+/** The runtime rule's id, as a hold's `reasons` name it. */
+const RULES_WAIT_FOR_ADMIN = "sanoma:rules-wait-for-admin";
+
+/**
+ * The runtime's own rule, asked before any company policy and under `allowAll` too: a merge of a
+ * change to the rules (`facts.rules`, or `touches` naming `policies/` or `resources/people.ts`) waits for `admin`, whoever made it, until an approval
+ * addressed to `admin` covering the merge is approved; denied while no data file declares the
+ * group. Undefined for anything else, which the company's policy alone decides. `people` are the
+ * running instance's, never the change's, so a change cannot add its author to `admin`.
+ */
+export function runtimeHold(
+  opId: string,
+  input: unknown,
+  approvals: readonly ApprovalState[],
+  people: readonly PeopleResource[],
+): Decision | undefined {
+  const facts = opId === CHANGE_MERGE ? (input as { facts?: ChangeFacts }).facts : undefined;
+  // The planner's `rules`, or what `touches` already says: a fact left false cannot skip the rule.
+  if (!facts || !(facts.rules || RULES.some((path) => facts.touches.includes(path)))) return undefined;
+  if (!groupNamesOf(people).includes(ADMIN)) {
+    return deny(
+      `A change to the policies or the people waits for the group "${ADMIN}", which no data file declares: ` +
+        `declare it in resources/people.ts`,
+      [RULES_WAIT_FOR_ADMIN],
+    );
+  }
+  const approver: Approver = { group: ADMIN };
+  if (approvedFor(approvals, CHANGE_MERGE, approver)) return undefined;
+  return approve(approver, { title: "A change to the rules waits for admin", reasons: [RULES_WAIT_FOR_ADMIN] });
+}
+
+/** What a change run is told while it waits: new commits on its branch, a close asked for, or its pull request closed or merged on the host. */
+export type ChangeEvent =
+  | { kind: "commits" }
+  | { kind: "close"; by: string }
+  | { kind: "closed" }
+  | { kind: "merged"; sha: string };
+
+/** Where a change is, as its run publishes it (`CHANGE_EVENT`) for the app. */
+export interface ChangeState {
+  id: string;
+  branch: string;
+  title: string;
+  page?: string;
+  phase:
+    | "opening"
+    | "planning"
+    | "checking"
+    | "reviewing"
+    | "waiting"
+    | "merging"
+    | "deploying"
+    | "merged"
+    | "closed"
+    | "blocked";
+  pullRequest?: { number: number; url: string };
+  head?: string;
+  facts?: ChangeFacts;
+  check?: CheckResult;
+  decision?: {
+    answer: "allow" | "hold" | "deny";
+    approver?: Approver;
+    title?: string;
+    reasons?: string[];
+    reason?: string;
+  };
+  /** The review card on the host: unavailable in this version. */
+  card: { status: "unavailable"; reason: string };
+  merged?: { sha: string; at: number; deploy?: { runId?: string; followed?: string; skipped?: string } };
+  blocked?: string;
+}
+
+/** How a change run ended. */
+export interface ChangeReport {
+  outcome: "merged" | "closed";
+  head: string;
+  pullRequest: { number: number; url: string };
+  sha?: string;
+  deploy?: { runId?: string };
+}