@sanoma-ai/workflows 0.7.0 → 0.8.0

package/dist/change-workflow.js

@@ -0,0 +1,161 @@
+import { ADMIN, ChangeInput, initialChangeState } from "./change.js";
+import { defineWorkflow } from "./define.js";
+import { errorCode, isRunControlError } from "./errors.js";
+import { approverLabel, errorMessage } from "./shared.js";
+/** 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, facts) {
+    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, steps) {
+    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",
+        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) => {
+                Object.assign(state, patch);
+                return steps.publish(state);
+            };
+            let report;
+            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;
+                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;
+                            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.data.by.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;
+        },
+    });
+}
+//# sourceMappingURL=change-workflow.js.map

package/dist/change-workflow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"change-workflow.js","sourceRoot":"","sources":["../src/change-workflow.ts"],"names":[],"mappings":"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"}

package/dist/change.d.ts

@@ -3,8 +3,9 @@ import type { ApprovalState, Approver } from "./define.ts";
 import { type Driver } from "./op.ts";
 import { type Decision } from "./policy.ts";
 import { type Resource } from "./resource.ts";
+import type { Secrets } from "./secret.ts";
 import { type PeopleResource } from "./shared.ts";
-import type { CheckResult } from "./source.ts";
+import { type CheckResult, type RemoteHalf, type RepoRef, type Source, type SourceHost } from "./source.ts";
 /**
  * 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`.
@@ -139,33 +140,123 @@ export declare function reservedFor(op: {
     does: string;
     instead: string;
 } | undefined;
-/** A placeholder: lane C5 replaces it with the driver over the repository's host. */
-export declare function changeDriver(): Driver;
+/** The branch a change merges into. */
+export declare const BASE = "main";
+/** The worker's repository, read from the run; a `DriverError` outside one, or for a worker given none. */
+export declare function sourceOfRun(): Source;
+/**
+ * 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 declare function repositoryOf(remotes: ReadonlyMap<string, RemoteHalf>, secrets: Secrets, source?: Source): Promise<{
+    source: Source;
+    url: string;
+    repo: RepoRef;
+    host: SourceHost;
+}>;
+/**
+ * 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 declare function followBase(remotes: ReadonlyMap<string, RemoteHalf>, secrets: Secrets, source?: Source): Promise<{
+    revision: string;
+} | {
+    skipped: string;
+} | {
+    error: string;
+}>;
+/**
+ * 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 declare function changeDriver(remotes: ReadonlyMap<string, RemoteHalf>): Driver;
 /**
  * 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 declare function touchesOf(files: readonly string[]): string[];
+/** The group the runtime holds a change to the rules for. */
+export declare 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 declare const isRules: (path: string) => boolean;
 /**
  * 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`.
  */
 export declare function runtimeHold(opId: string, input: unknown, approvals: readonly ApprovalState[], people: readonly PeopleResource[]): Decision | undefined;
-/** 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 declare const ChangeEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"commits">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"close">;
+    by: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"closed">;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"merged">;
+    sha: z.ZodString;
+}, z.core.$strip>], "kind">;
+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 {
     id: string;
@@ -195,14 +286,21 @@ export interface ChangeState {
     merged?: {
         sha: string;
         at: number;
-        deploy?: {
-            runId?: string;
-            followed?: string;
-            skipped?: string;
-        };
+        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 declare const NO_CARD: {
+    readonly status: "unavailable";
+    readonly reason: "This version writes no review card on the host";
+};
+/** Where a change is before its run has opened it. */
+export declare const initialChangeState: (input: ChangeInput) => ChangeState;
 /** How a change run ended. */
 export interface ChangeReport {
     outcome: "merged" | "closed";
@@ -212,8 +310,7 @@ export interface ChangeReport {
         url: string;
     };
     sha?: string;
-    deploy?: {
-        runId?: string;
-    };
+    deploy?: ChangeDeploy;
+    verified?: ChangeVerified;
 }
 export {};

package/dist/change.js

@@ -1,12 +1,16 @@
 import { z } from "zod";
+import { errorInfo } from "./errors.js";
 import { defineConnector, defineDriver, DriverError } from "./op.js";
 import { approve, approvedFor, deny } from "./policy.js";
 import { isChangeOp } from "./resource.js";
-import { APPLY_WORKFLOW, CHANGE_MERGE, CHANGE_WORKFLOW, groupNamesOf } from "./shared.js";
+import { currentRun } from "./run.js";
+import { APPLY_WORKFLOW, CHANGE_MERGE, CHANGE_WORKFLOW, DRAFT_ID, errorMessage, groupNamesOf, } from "./shared.js";
+import { remoteFor, } from "./source.js";
 // 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
  * `Sanoma::Change` that `sanoma.change.merge` acts on, so a rule reads `resource.touches`.
@@ -20,12 +24,12 @@ 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(),
 });
 /** 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(),
@@ -100,12 +104,162 @@ export function reservedFor(op, types) {
     }
     return undefined;
 }
-const notBuilt = async () => {
-    throw new DriverError("not built", { retryable: false });
-};
-/** A placeholder: lane C5 replaces it with the driver over the repository's host. */
-export function changeDriver() {
-    return defineDriver(changeOps, { change: { open: notBuilt, review: notBuilt, merge: notBuilt, close: notBuilt } });
+/** The branch a change merges into. */
+export const BASE = "main";
+/** The company's credentials for a host, as its remote half asks for them (`Secrets` puts the environment first). */
+const remoteContext = (secrets) => ({
+    async secrets(names) {
+        const found = await Promise.all(names.map(async (name) => [name, await secrets.get(name)]));
+        return new Map(found.filter((entry) => Boolean(entry[1])));
+    },
+});
+/** The worker's repository, read from the run; a `DriverError` outside one, or for a worker given none. */
+export function sourceOfRun() {
+    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();
+/**
+ * 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, secrets, source = sourceOfRun()) {
+    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();
+    openedHosts.set(found.remote, bySecrets);
+    const byUrl = bySecrets.get(secrets) ?? new Map();
+    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, secrets, source) {
+    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) {
+    const open = (call) => 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", ...(pr.mergeSha !== undefined && { sha: pr.mergeSha }) };
+                if (pr.state === "closed")
+                    return { outcome: "closed" };
+                // 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" };
+                await host.setStatus({ sha: head, state: "success", description: "Published through Sanoma" });
+                let sha;
+                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" };
+                    if (code === "not_mergeable")
+                        return { outcome: "blocked", 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", sha };
+            },
+            async close({ number }, call) {
+                const { host } = await open(call);
+                await host.closePullRequest(number);
+                return { closed: true };
+            },
+        },
+    });
 }
 /**
  * Each path, relative to the root with `/` between its parts, and each of its parent directories
@@ -121,14 +275,18 @@ export function touchesOf(files) {
     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"];
+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) => 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`.
@@ -136,7 +294,7 @@ const RULES_WAIT_FOR_ADMIN = "sanoma:rules-wait-for-admin";
 export function runtimeHold(opId, input, approvals, people) {
     const facts = opId === CHANGE_MERGE ? input.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))))
+    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: ` +
@@ -147,4 +305,25 @@ export function runtimeHold(opId, input, approvals, people) {
         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 (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) }),
+]);
+/** 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" };
+/** Where a change is before its run has opened it. */
+export const initialChangeState = (input) => ({
+    id: input.id,
+    branch: "",
+    title: input.title,
+    ...(input.page !== undefined && { page: input.page }),
+    phase: "opening",
+    card: NO_CARD,
+});
 //# sourceMappingURL=change.js.map