@sanoma-ai/workflows 0.7.1 → 0.8.0

package/src/change-workflow.ts

@@ -0,0 +1,198 @@
+import type {
+  ChangeDecision,
+  ChangeDeploy,
+  ChangeEvent,
+  ChangeFacts,
+  ChangeReport,
+  ChangeState,
+  ChangeVerified,
+  changeOps,
+  MergeInput,
+} from "./change.ts";
+import { ADMIN, ChangeInput, initialChangeState } from "./change.ts";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import { errorCode, isRunControlError, type SanomaError } from "./errors.ts";
+import { approverLabel, type CHANGE_WORKFLOW, errorMessage } from "./shared.ts";
+import type { CheckResult } from "./source.ts";
+
+// The built-in `change` workflow: the life of a change to the company's repository, from its
+// draft to live. It opens the draft's branch as a pull request, checks and plans it, asks the
+// policy, reports Sanoma's review on the host, waits in the Inbox for Publish (the approval),
+// squash-merges, deploys and verifies. A workflow like any other, held to the same lint: every
+// operation goes through `ctx`, and what is no operation is a step of `change-steps.ts`.
+
+/** What the change workflow does that is no operation, each a step of its own (`change-steps.ts`). */
+export interface ChangeSteps {
+  /** `sanoma check` on the draft (`Source.check`), its Permissions grid among it. */
+  check(id: string): Promise<CheckResult>;
+  /** The facts the policy decides the merge on: from the draft's diff, the waiting runs and `check`. */
+  plan(id: string, check: CheckResult): Promise<ChangeFacts>;
+  /** The policy's answer to the merge now, the runtime's rule first: who Publish waits for, or why it is denied. */
+  ahead(merge: MergeInput): Promise<ChangeDecision>;
+  /** Waits for the next event on the change's topic: the one that weighs most of those waiting then, a `merged` or `closed` checked on the host for pull request `number`. */
+  next(number: number): Promise<ChangeEvent>;
+  /** The event that weighs most of those waiting on the topic now, without waiting, checked as `next` does; undefined for none. */
+  queued(number: number): Promise<ChangeEvent | undefined>;
+  /** Withdraws every approval of the run approved for the merge, saying `reason`: none lifts a hold on a newer head. */
+  retire(reason: string): Promise<void>;
+  /** After the merge: the checkout follows `main`, then apply on the declared hosts, as a run of its own this one waits for. */
+  deploy(sha: string): Promise<ChangeDeploy>;
+  /** After an apply on the hosts: drift on them, as a run of its own; undefined with no host. */
+  verify(deploy: ChangeDeploy): Promise<ChangeVerified | undefined>;
+  /** Closes the draft the change merged. */
+  closeDraft(id: string): Promise<void>;
+  /** Publishes where the change is (`CHANGE_EVENT`), for the app. */
+  publish(state: ChangeState): Promise<void>;
+}
+
+/** What the change workflow uses: its four operations, and `approval`. */
+type ChangeUse = (typeof changeOps.change)[keyof typeof changeOps.change] | "approval";
+
+/** The approval Publish is: the Inbox's title for it. */
+const PUBLISH = "Publish the change";
+
+/** The `sanoma` status on the host: pending while it can merge, failure while checks fail or the policy denies; and what it waits for. */
+function reviewOf(decision: ChangeDecision, facts: ChangeFacts): { state: "pending" | "failure"; description: string } {
+  if (decision.answer === "deny") {
+    return { state: "failure", description: `Denied: ${decision.reason ?? "the policy refuses it"}` };
+  }
+  const waits = decision.title ?? `Waits for ${approverLabel(decision.approver ?? { group: ADMIN })} to publish it`;
+  return facts.checksOk
+    ? { state: "pending", description: waits }
+    : { state: "failure", description: `sanoma check fails. ${waits}` };
+}
+
+/**
+ * The change workflow over `ops` (`changeOps`, the built-in connector's) and `steps`:
+ * `resolveConfig` adds it to every config. It `uses` the four operations and `approval`.
+ *
+ * A run is the life of one change (run id `change:<draft>`): each round opens the draft's branch
+ * as a pull request (`open`, which pushes it), checks it (`steps.check`), plans its facts
+ * (`steps.plan`), asks the policy ahead (`steps.ahead`), and reports on the host (`review`). While
+ * the policy denies it, the run waits for what happens next (`steps.next`). Otherwise it asks one
+ * approval, Publish, of the hold's approver (else whoever drafted it), covering the merge, with the
+ * change and its facts as its details; once approved, it merges (`merge`). An event that comes in
+ * meanwhile (`SanomaClient.changeEvent`) withdraws the approval, and the run reads it:
+ * `commits` plans another round, after withdrawing every approval approved for the merge
+ * (`steps.retire`), so none lifts a hold on the new head; `close` closes the pull request; the
+ * pull request `closed` or `merged` on the host ends the change as it is. A rejected Publish
+ * closes it too. A merge whose branch moved plans another round; one the host refuses waits.
+ *
+ * Once merged, the deploy (`steps.deploy`): the checkout follows `main`, then apply on the
+ * declared hosts, as a run this one waits for, then drift on them (`steps.verify`). A `merged` or
+ * `closed` event someone told is checked on the host as it is read (`steps.next`, `steps.queued`); one it does not bear
+ * out plans another round. A Publish withdrawn with no event waits, blocked, for the next one.
+ * Then the draft is closed. Each phase is published (`steps.publish`, `CHANGE_EVENT`); the run's
+ * output is its `ChangeReport`.
+ */
+export function changeWorkflow(
+  ops: typeof changeOps,
+  steps: ChangeSteps,
+): WorkflowDefinition<readonly ChangeUse[], typeof ChangeInput> {
+  return defineWorkflow({
+    // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+    name: "change" satisfies typeof CHANGE_WORKFLOW,
+    title: "Publish a change",
+    trigger: "manual",
+    input: ChangeInput,
+    uses: [ops.change.open, ops.change.review, ops.change.merge, ops.change.close, "approval"],
+    run: async (ctx, input) => {
+      const state = initialChangeState(input);
+      /** Moves the change on, and publishes where it is. */
+      const show = (patch: Partial<ChangeState>) => {
+        Object.assign(state, patch);
+        return steps.publish(state);
+      };
+      let report: ChangeReport | undefined;
+      while (report === undefined) {
+        // An approval is given for a head: one approved for an earlier round lifts no hold on this one.
+        await steps.retire("the change was planned again at a new head");
+        await show({ phase: "opening", decision: undefined, blocked: undefined });
+        const opened = await ctx.sanoma.change.open(input);
+        const pullRequest = { number: opened.number, url: opened.url };
+        await show({ branch: opened.branch, pullRequest, head: opened.head, phase: "checking" });
+        const check = await steps.check(input.id);
+        await show({ check, phase: "planning" });
+        const facts = await steps.plan(input.id, check);
+        const merge = { id: input.id, number: opened.number, head: opened.head, title: input.title, facts };
+        const decision = await steps.ahead(merge);
+        await show({ facts, decision, phase: "reviewing" });
+        await ctx.sanoma.change.review({
+          id: input.id,
+          number: opened.number,
+          head: opened.head,
+          ...reviewOf(decision, facts),
+          ...(input.page !== undefined && { page: input.page }),
+        });
+        // What came in while the round was planned decides it before any approval is asked.
+        let told = await steps.queued(opened.number);
+        let event: ChangeEvent | undefined;
+        let blocked = told === undefined && decision.answer === "deny" ? decision.reason : undefined;
+        if (told === undefined && blocked === undefined) {
+          try {
+            await show({ phase: "waiting" });
+            await ctx.approval(PUBLISH, {
+              approver: decision.approver!,
+              covers: [ops.change.merge],
+              details: JSON.stringify({ change: { id: input.id, title: input.title, branch: opened.branch }, facts }),
+              links: [opened.url, ...(input.page === undefined ? [] : [input.page])],
+            });
+            // An event told while Publish was being asked found no approval to withdraw: it is read before the merge.
+            told = await steps.queued(opened.number);
+            if (told === undefined) {
+              await show({ phase: "merging" });
+              let merged: Awaited<ReturnType<typeof ctx.sanoma.change.merge>>;
+              try {
+                merged = await ctx.sanoma.change.merge(merge);
+              } catch (err) {
+                // Approved, but the policy or the host refuses the merge now: the change waits, as for a refusal.
+                // A hold the policy puts on the merge itself is decided as Publish is, below.
+                if (isRunControlError(err) || errorCode(err)?.startsWith("approval_")) throw err;
+                merged = { outcome: "blocked", reason: errorMessage(err) };
+              }
+              if (merged.outcome === "merged") event = { kind: "merged", sha: merged.sha ?? opened.head };
+              else if (merged.outcome === "closed") event = { kind: "closed" };
+              else if (merged.outcome === "moved") event = { kind: "commits" };
+              else blocked = merged.reason ?? "the host refuses the merge";
+            }
+          } catch (err) {
+            // A withdrawal comes with an event, else Publish was taken back. A rejection of Publish closes the change.
+            const code = errorCode(err);
+            if (code === "approval_withdrawn") {
+              told = await steps.queued(opened.number);
+              if (told === undefined) blocked = "Publish was withdrawn";
+            } else if (code === "approval_rejected") {
+              event = { kind: "close", by: ((err as SanomaError).data.by as { id: string }).id };
+            } else throw err;
+          }
+        }
+        if (blocked !== undefined) {
+          await show({ phase: "blocked", blocked });
+          told = await steps.next(opened.number);
+        }
+        event ??= told!;
+        if (event.kind === "merged") {
+          await show({ phase: "deploying" });
+          const deploy = await steps.deploy(event.sha);
+          const verified = await steps.verify(deploy);
+          await steps.closeDraft(input.id);
+          const merged = { sha: event.sha, at: await ctx.now(), deploy, ...(verified && { verified }) };
+          await show({ phase: "merged", merged });
+          report = {
+            outcome: "merged",
+            head: opened.head,
+            pullRequest,
+            sha: merged.sha,
+            deploy,
+            ...(verified && { verified }),
+          };
+        } else if (event.kind !== "commits") {
+          if (event.kind === "close") await ctx.sanoma.change.close({ id: input.id, number: opened.number });
+          await show({ phase: "closed", ...(event.kind === "close" && { closedBy: event.by }) });
+          report = { outcome: "closed", head: opened.head, pullRequest };
+        }
+      }
+      return report;
+    },
+  });
+}

package/src/change.ts

@@ -1,15 +1,35 @@
 import { z } from "zod";
 import type { ApprovalState, Approver } from "./define.ts";
-import { defineConnector, defineDriver, type Driver, DriverError } from "./op.ts";
+import { errorInfo } from "./errors.ts";
+import { type CallContext, 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";
+import { currentRun } from "./run.ts";
+import type { Secrets } from "./secret.ts";
+import {
+  APPLY_WORKFLOW,
+  CHANGE_MERGE,
+  CHANGE_WORKFLOW,
+  DRAFT_ID,
+  errorMessage,
+  groupNamesOf,
+  type PeopleResource,
+} from "./shared.ts";
+import {
+  type CheckResult,
+  type RemoteContext,
+  type RemoteHalf,
+  remoteFor,
+  type RepoRef,
+  type Source,
+  type SourceHost,
+} 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.
+// runs it (`change-workflow.ts`): its four operations on the built-in connector `sanoma` and their
+// driver over the repository's host, 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
@@ -24,14 +44,14 @@ export const ChangeFacts = z.object({
   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`). */
+  /** Whether the change edits the rules: a policy (the root's or an app's) 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}$/),
+  id: z.string().regex(DRAFT_ID),
   title: z.string().min(1),
   body: z.string().optional(),
   page: z.string().url().optional(),
@@ -114,13 +134,169 @@ export function reservedFor(
   return undefined;
 }
 
-const notBuilt = async (): Promise<never> => {
-  throw new DriverError("not built", { retryable: false });
-};
+/** The branch a change merges into. */
+export const BASE = "main";
 
-/** 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 } });
+/** The company's credentials for a host, as its remote half asks for them (`Secrets` puts the environment first). */
+const remoteContext = (secrets: Secrets): RemoteContext => ({
+  async secrets(names) {
+    const found = await Promise.all(names.map(async (name) => [name, await secrets.get(name)] as const));
+    return new Map(found.filter((entry): entry is readonly [string, string] => Boolean(entry[1])));
+  },
+});
+
+/** The worker's repository, read from the run; a `DriverError` outside one, or for a worker given none. */
+export function sourceOfRun(): Source {
+  const source = currentRun.getStore()?.state.source;
+  if (!source) {
+    throw new DriverError("This worker was given no repository (`source`), so it cannot change one", {
+      retryable: false,
+    });
+  }
+  return source;
+}
+
+/** Each host opened, by its remote half, the secrets it reads and the clone URL: its token is minted once and kept while it holds. */
+const openedHosts = new WeakMap<RemoteHalf, WeakMap<Secrets, Map<string, SourceHost>>>();
+
+/**
+ * The company's repository and its host: `source`, by default the worker's for a call made in a
+ * run (a change's driver and its steps, `sourceOfRun`), the clone URL of its `origin`, and that
+ * repository (`repo`) on the host whose connector's remote half matches the URL, opened once per
+ * remote half, secrets and URL, so its token is kept between calls. A `DriverError` when the
+ * repository has no remote (`no_remote`: saving is publishing then, there is nothing to review a
+ * branch on) or no connector is for its host (`no_remote_half`).
+ */
+export async function repositoryOf(
+  remotes: ReadonlyMap<string, RemoteHalf>,
+  secrets: Secrets,
+  source: Source = sourceOfRun(),
+): Promise<{ source: Source; url: string; repo: RepoRef; host: SourceHost }> {
+  const url = await source.remoteUrl?.();
+  if (!url) {
+    throw new DriverError("saving is publishing: this repository has no remote", {
+      retryable: false,
+      vendorCode: "no_remote",
+    });
+  }
+  const found = remoteFor(remotes, url);
+  if (!found) {
+    throw new DriverError(`No connector's remote half is for ${url}: add the connector of its host`, {
+      retryable: false,
+      vendorCode: "no_remote_half",
+    });
+  }
+  const bySecrets = openedHosts.get(found.remote) ?? new WeakMap<Secrets, Map<string, SourceHost>>();
+  openedHosts.set(found.remote, bySecrets);
+  const byUrl = bySecrets.get(secrets) ?? new Map<string, SourceHost>();
+  bySecrets.set(secrets, byUrl);
+  const host = byUrl.get(url) ?? found.remote.open(found.repo, remoteContext(secrets));
+  byUrl.set(url, host);
+  return { source, url, repo: found.repo, host };
+}
+
+/**
+ * Fast-forwards the checkout to the host's `main` (`Source.follow`), as a deploy does first so the
+ * hosts and what apply reads are main's: the revision after, why it did not, or the error, never
+ * thrown (what is merged is merged; a deploy that cannot follow still applies).
+ */
+export async function followBase(
+  remotes: ReadonlyMap<string, RemoteHalf>,
+  secrets: Secrets,
+  source?: Source,
+): Promise<{ revision: string } | { skipped: string } | { error: string }> {
+  try {
+    const { source: at, url, host } = await repositoryOf(remotes, secrets, source);
+    if (!at.follow) return { skipped: "this repository cannot follow its remote" };
+    const moved = await at.follow({ url, token: await host.token(), ref: BASE });
+    return "revision" in moved ? { revision: moved.revision } : moved;
+  } catch (err) {
+    return { error: errorMessage(err) };
+  }
+}
+
+/**
+ * The driver of a change's operations, over the repository the worker was given (`source`, read
+ * from the run) and its host (`remotes`, the connectors' remote halves: `remoteFor` its
+ * `origin`, opened once and kept: `repositoryOf`).
+ *
+ * - `open` pushes the draft's branch and opens its pull request into `main` (the open one when it
+ *   has one): safe to retry. Its `head` is the branch's commit as pushed.
+ * - `review` sets the `sanoma` status on the head, linking to the change page: `pending`, or
+ *   `failure`; never `success`, which only a merge sets.
+ * - `merge` reads the pull request: merged already (a retry whose answer was lost) or closed are
+ *   answered as they are; a branch at another commit than `head`, on the host or in the draft, is
+ *   `moved`. Else it sets the status `success` and squash-merges at `head`: the host's `head_moved`
+ *   is `moved`, `not_mergeable` is `blocked` with the host's reason. The branch is then deleted,
+ *   as far as it can be.
+ * - `close` closes the pull request.
+ */
+export function changeDriver(remotes: ReadonlyMap<string, RemoteHalf>): Driver {
+  const open = (call: CallContext) => repositoryOf(remotes, call.secrets);
+  return defineDriver(changeOps, {
+    change: {
+      async open({ id, title, body }, call) {
+        const { source, url, host } = await open(call);
+        if (!source.draft || !source.drafts || !source.push) {
+          throw new DriverError("This repository keeps no drafts, so it has no change to open", { retryable: false });
+        }
+        if (!(await source.drafts()).includes(id)) {
+          throw new DriverError(`There is no open draft "${id}" to send for review`, {
+            retryable: false,
+            vendorCode: "no_draft",
+          });
+        }
+        const { branch } = await source.draft(id);
+        // The head is read before the push: a commit made in the draft meanwhile is the next round's.
+        const head = await source.head(branch);
+        await source.push({ url, token: await host.token(), ref: branch });
+        const pr = await host.openPullRequest({ branch, base: BASE, title, body: body ?? "" });
+        return { number: pr.number, url: pr.url, head, branch };
+      },
+      async review({ head, state, description, page }, call) {
+        const { host } = await open(call);
+        await host.setStatus({ sha: head, state, description, ...(page !== undefined && { targetUrl: page }) });
+        return {};
+      },
+      async merge({ number, head, title }, call) {
+        const { source, host } = await open(call);
+        const pr = await host.pullRequest(number);
+        if (pr.state === "merged")
+          return { outcome: "merged" as const, ...(pr.mergeSha !== undefined && { sha: pr.mergeSha }) };
+        if (pr.state === "closed") return { outcome: "closed" as const };
+        // Commits the run has not planned: pushed to the host, or made in the draft and not pushed yet.
+        const local = await Promise.resolve(source.head(pr.branch)).catch(() => undefined);
+        if (pr.head !== head || (local !== undefined && local !== head)) return { outcome: "moved" as const };
+        await host.setStatus({ sha: head, state: "success", description: "Published through Sanoma" });
+        let sha: string;
+        try {
+          ({ sha } = await host.mergePullRequest(number, {
+            sha: head,
+            method: "squash",
+            title: `${title} (#${number})`,
+          }));
+        } catch (err) {
+          // Not merged: Sanoma's status on the head goes back to failing, so the host does not merge it either.
+          const reason = errorMessage(err);
+          await host
+            .setStatus({ sha: head, state: "failure", description: `Not published: ${reason}`.slice(0, 140) })
+            .catch(() => undefined);
+          const { vendorCode: code } = errorInfo(err);
+          if (code === "head_moved") return { outcome: "moved" as const };
+          if (code === "not_mergeable") return { outcome: "blocked" as const, reason };
+          throw err;
+        }
+        // Best effort: a branch left behind holds nothing the merge did not take.
+        await host.deleteBranch?.(pr.branch).catch(() => undefined);
+        return { outcome: "merged" as const, sha };
+      },
+      async close({ number }, call) {
+        const { host } = await open(call);
+        await host.closePullRequest(number);
+        return { closed: true as const };
+      },
+    },
+  });
 }
 
 /**
@@ -137,15 +313,20 @@ export function touchesOf(files: readonly string[]): string[] {
 }
 
 /** 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"];
+export const ADMIN = "admin";
+/**
+ * Whether a path in `touches` is the rules whatever `rules` says: the policies, the root's or an
+ * app's (`apps/crm/policies/`), and the template's people file.
+ */
+export const isRules = (path: string) =>
+  path === "policies/" || path === "resources/people.ts" || /^apps\/[^/]+\/policies\/$/.test(path);
 /** 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
+ * change to the rules (`facts.rules`, or `touches` naming `policies/`, an app's `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`.
@@ -158,7 +339,7 @@ export function runtimeHold(
 ): 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 (!facts || !(facts.rules || facts.touches.some(isRules))) 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: ` +
@@ -171,12 +352,44 @@ export function runtimeHold(
   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 };
+/**
+ * What a change run is told (on `CHANGE_TOPIC`): new commits on its branch, a close someone asked
+ * for, or its pull request closed or merged on the host.
+ */
+export const ChangeEventSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("commits") }),
+  z.object({ kind: z.literal("close"), by: z.string().min(1) }),
+  z.object({ kind: z.literal("closed") }),
+  z.object({ kind: z.literal("merged"), sha: z.string().min(1) }),
+]);
+export type ChangeEvent = z.infer<typeof ChangeEventSchema>;
+
+/** What a merge is asked with: the change, its pull request at the head planned, and the facts. */
+export type MergeInput = z.input<typeof changeOps.change.merge.input>;
+
+/**
+ * The policy's answer to a change's merge, asked ahead (`ChangeState.decision`): `allow`, `hold`
+ * for the approver and title the policy gave, or `deny` with its reason. An allowed or held change
+ * has an `approver`, whose approval is Publish: the hold's, else whoever drafted it.
+ */
+export type ChangeDecision = NonNullable<ChangeState["decision"]>;
+
+/**
+ * What became of the deploy after a merge: the checkout fast-forwarded to `main` (`follow`: the
+ * revision, why not, or its error), then the apply run on the declared hosts, when any.
+ */
+export interface ChangeDeploy {
+  follow: { revision: string } | { skipped: string } | { error: string };
+  /** The apply run, restricted to the declared hosts' ids (`<file>#<export>`), and its error when it failed. */
+  apply?: { runId: string; hosts: string[]; error?: string };
+}
+
+/** The drift run that read the hosts back after their apply, and the hosts it found not as declared. */
+export interface ChangeVerified {
+  runId: string;
+  drifted: string[];
+  error?: string;
+}
 
 /** Where a change is, as its run publishes it (`CHANGE_EVENT`) for the app. */
 export interface ChangeState {
@@ -208,15 +421,32 @@ export interface ChangeState {
   };
   /** 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 } };
+  merged?: { sha: string; at: number; deploy?: ChangeDeploy; verified?: ChangeVerified };
+  /** Why the change cannot merge now: the policy denies it, or the host refuses the merge. */
   blocked?: string;
+  /** Who closed it, when someone asked (a `close` event, or a rejection of the Publish approval). */
+  closedBy?: string;
 }
 
+/** The review card on the host, which this version does not write. */
+export const NO_CARD = { status: "unavailable", reason: "This version writes no review card on the host" } as const;
+
+/** Where a change is before its run has opened it. */
+export const initialChangeState = (input: ChangeInput): ChangeState => ({
+  id: input.id,
+  branch: "",
+  title: input.title,
+  ...(input.page !== undefined && { page: input.page }),
+  phase: "opening",
+  card: NO_CARD,
+});
+
 /** How a change run ended. */
 export interface ChangeReport {
   outcome: "merged" | "closed";
   head: string;
   pullRequest: { number: number; url: string };
   sha?: string;
-  deploy?: { runId?: string };
+  deploy?: ChangeDeploy;
+  verified?: ChangeVerified;
 }

package/src/claims.ts

@@ -0,0 +1,79 @@
+// Sanoma's claims: what Sanoma says about connectors and apps that their authors cannot say about
+// their own (the tier, whether Sanoma reviewed it, what it blocks), and the solutions, each a kind
+// of customer with the apps that cover their problems and one demo repository. Data, changed by
+// pull request; `sanoma/claims` re-exports it, so a company and its sites import it statically.
+// Browser-safe: nothing here imports anything. Everything else about a connector or an app is
+// its author's, read from npm or GitHub (`sanoma.apps.list`), never copied here.
+
+/**
+ * Whose a connector or an app is: Sanoma's own, its vendor's (checked by Sanoma), or anyone's. With
+ * no claim, `official` is read from the name (the `@sanoma-ai/` scope, the `Sanoma-AI` owner).
+ */
+export const TIERS = ["official", "vendor-verified", "community"] as const;
+export type Tier = (typeof TIERS)[number];
+
+/** What Sanoma says of a connector package, by its npm name. */
+export interface ConnectorClaim {
+  tier: Tier;
+  /** Whether Sanoma read its code. */
+  reviewed: boolean;
+  /** Versions Sanoma blocks. */
+  blocked?: string[];
+}
+
+/** What Sanoma says of an app's source repository, by `<owner>/<repo>` on GitHub. */
+export interface AppClaim {
+  tier: Tier;
+  /** Whether Sanoma read its code. */
+  reviewed: boolean;
+  /** Commits Sanoma blocks, by their full id. */
+  blocked?: string[];
+  /** The solutions it belongs to, by id. */
+  solutions: string[];
+}
+
+/**
+ * A solution: a kind of customer and the apps that cover their problems, with the one public demo
+ * repository (a fictional business of that kind, those apps merged under `apps/`) that a visitor
+ * meets it in.
+ */
+export interface SolutionClaim {
+  /** The solution's name, as its page heads it. */
+  title: string;
+  /** The kind of customer it is for, in their words: "property managers". */
+  kind: string;
+  /** Its apps' source repositories, `<owner>/<repo>`. */
+  apps: string[];
+  /** Its demo: the company repository, `<owner>/<repo>`, and where it runs once it does. */
+  demo: { repo: string; url?: string };
+}
+
+/** Sanoma's claims, each keyed as its kind is named: a package, a repository, a solution's id. */
+export interface Claims {
+  connectors: Readonly<Record<string, ConnectorClaim>>;
+  apps: Readonly<Record<string, AppClaim>>;
+  solutions: Readonly<Record<string, SolutionClaim>>;
+}
+
+/** Sanoma's claims. Empty until the first outside connector, the first app and the first solution exist. */
+export const claims: Claims = {
+  connectors: {},
+  apps: {},
+  solutions: {},
+};
+
+/** A connector package's tier: its claim's, else official for the `@sanoma-ai/` scope and community otherwise. */
+export const connectorTier = (pkg: string, from: Claims = claims): Tier =>
+  from.connectors[pkg]?.tier ?? (pkg.startsWith("@sanoma-ai/") ? "official" : "community");
+
+/** The claim on the app whose source is `repo` (`<owner>/<repo>`, as GitHub names it, in any case). */
+export const appClaim = (repo: string, from: Claims = claims): AppClaim | undefined =>
+  Object.entries(from.apps).find(([key]) => key.toLowerCase() === repo.toLowerCase())?.[1];
+
+/** The GitHub owner whose repositories are Sanoma's own. */
+export const SANOMA_ORG = "Sanoma-AI";
+
+/** An app source's tier: its claim's, else official for the `Sanoma-AI` owner's and community otherwise. */
+export const appTier = (repo: string, from: Claims = claims): Tier =>
+  appClaim(repo, from)?.tier ??
+  (repo.toLowerCase().startsWith(`${SANOMA_ORG.toLowerCase()}/`) ? "official" : "community");