@intentius/chant 0.90.0 → 0.93.0

package/src/workspace/chant-migrations/chud-lexicon-exit-fly-site.ts

@@ -0,0 +1,234 @@
+/**
+ * `chud-lexicon-exit-fly-site` (#2809): declare a migrated repo's Fly site
+ * with the fly lexicon's `FlySite` composite.
+ *
+ * `chud-lexicon-exit` (0.92.0) deleted deploy/site.ts, chud's `ChudLocalSite`
+ * composite, and removed chud's `FlySite` marker from deploy/fly.ts, so the
+ * repo declared no composite instance: `chant workspace graph --composites`
+ * listed none, and nothing told a reader the app component deploys the site.
+ * Per ws-056 the Fly resources stay on the fly lexicon. This migration:
+ *
+ * - rewrites deploy/fly.ts as one `FlySite` instance (`flySite`) with the
+ *   values deploy/fly.ts and deploy/fly-machine.ts declared, and deletes
+ *   deploy/fly-machine.ts, when the two declare exactly the template's
+ *   resources (comments aside). The build's plan has the same App, Volume,
+ *   IP, Secret and one Machine, which the release Op's `flyRelease` finds;
+ * - names `FlySite` in the app component's `composites`, so the listing joins
+ *   the instance to the component.
+ *
+ * A site the project changed keeps its files, and the plan lists the
+ * composite as not moved. The plan is empty unless the app component is the
+ * one `chud-lexicon-exit` wrote and names no composites yet.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, NotMoved, PlannedChange } from "../chant-migrations";
+
+export const CHUD_LEXICON_EXIT_FLY_SITE = "chud-lexicon-exit-fly-site";
+
+const DESCRIPTION = "declare the Fly site with the fly lexicon's FlySite composite, the instance the app component deploys (#2809)";
+
+function readText(dir: string, path: string): string | undefined {
+  const abs = join(dir, path);
+  return existsSync(abs) ? readFileSync(abs, "utf-8") : undefined;
+}
+
+/** The template's Fly site, as deploy/fly.ts and deploy/fly-machine.ts declare it. */
+export interface FlySiteValues {
+  /** The import that gives the app's name, kept as it is: `import { appSlug } from "../app-name.ts";`. */
+  nameImport: string | null;
+  /** The expression the App's name is, as written. */
+  app: string;
+  region: string;
+  machine: string;
+  image: string;
+  port: string;
+  env: string;
+  cpuKind: string;
+  cpus: string;
+  memoryMb: string;
+  volume: { name: string; sizeGb: string; path: string };
+  ip: string;
+  secret: { name: string; value: string };
+}
+
+/** A file's code without its comments and blank lines. */
+function codeOf(text: string): string {
+  return text
+    .replace(/\/\*[\s\S]*?\*\//g, "")
+    .split("\n")
+    .map((l) => l.replace(/\s+$/, ""))
+    .filter((l) => l !== "" && !/^\s*\/\//.test(l))
+    .join("\n");
+}
+
+const STR = `("[^"\\n]*")`;
+const FLY_CODE = new RegExp(
+  "^" +
+    `import \\{ App, Fly, IPAddress, Secret, Volume \\} from "@intentius/chant-lexicon-fly";\\n` +
+    `(?:import \\{ FlySite \\} from "@intentius/chud-runtime/lexicon";\\n)?` +
+    `(?:(import \\{ \\w+ \\} from "\\.\\./app-name\\.ts";)\\n)?` +
+    `const name = ([^;\\n]+);\\n` +
+    `const region = ${STR};\\n` +
+    `export const flyApp = new App\\(\\{ name, org_slug: Fly\\.OrgSlug \\}\\);\\n` +
+    `export const data = new Volume\\(\\{ name: ${STR}, region, size_gb: (\\d+) \\}\\);\\n` +
+    `export const publicIp = new IPAddress\\(\\{ type: ${STR} \\}\\);\\n` +
+    `export const appSecret = new Secret\\(\\{ name: ${STR}, value: ([^\\n]+) \\}\\);` +
+    `(?:\\nexport const flySite = new FlySite\\([^\\n]*\\);)?$`,
+);
+const MACHINE_CODE = new RegExp(
+  [
+    `^import \\{ Machine, MachineConfig, MachineGuest, MachineMount, MachinePort, MachineService \\} from "@intentius/chant-lexicon-fly";`,
+    `export const guest = new MachineGuest\\(\\{ cpu_kind: ${STR}, cpus: (\\d+), memory_mb: (\\d+) \\}\\);`,
+    `export const dataMount = new MachineMount\\(\\{ volume: ${STR}, path: ${STR} \\}\\);`,
+    `export const https = new MachinePort\\(\\{ port: 443, handlers: \\["tls", "http"\\] \\}\\);`,
+    `export const http = new MachinePort\\(\\{ port: 80, handlers: \\["http"\\] \\}\\);`,
+    `export const web = new MachineService\\(\\{ protocol: "tcp", internal_port: (\\d+), ports: \\[https, http\\] \\}\\);`,
+    `export const server = new Machine\\(\\{`,
+    ` {2}name: ${STR},`,
+    ` {2}region: ${STR},`,
+    ` {2}config: new MachineConfig\\(\\{`,
+    ` {4}image: ${STR},`,
+    ` {4}guest,`,
+    ` {4}mounts: \\[dataMount\\],`,
+    ` {4}services: \\[web\\],`,
+    ` {4}env: (\\{[^\\n]*\\}),`,
+    ` {2}\\}\\),`,
+    `\\}\\);$`,
+  ].join("\\n"),
+);
+
+/**
+ * The Fly site's values when deploy/fly.ts and deploy/fly-machine.ts declare
+ * exactly the template's resources (their comments aside), or null. A site
+ * the project changed is left in its files, and the plan says so.
+ */
+export function readFlySite(fly: string, machine: string): FlySiteValues | null {
+  const f = FLY_CODE.exec(codeOf(fly));
+  const m = MACHINE_CODE.exec(codeOf(machine));
+  if (!f || !m) return null;
+  const [, nameImport, app, region, volumeName, sizeGb, ip, secretName, secretValue] = f;
+  const [, cpuKind, cpus, memoryMb, mountVolume, mountPath, port, machineName, machineRegion, image, env] = m;
+  // One region and one Volume: what the composite declares.
+  if (machineRegion !== region || mountVolume !== volumeName) return null;
+  return {
+    nameImport: nameImport ?? null,
+    app,
+    region,
+    machine: machineName,
+    image,
+    port,
+    env,
+    cpuKind,
+    cpus,
+    memoryMb,
+    volume: { name: volumeName, sizeGb, path: mountPath },
+    ip,
+    secret: { name: secretName, value: secretValue },
+  };
+}
+
+/** deploy/fly.ts declaring the site with the fly lexicon's FlySite composite. */
+export function flySiteFile(v: FlySiteValues): string {
+  return `/**
+ * The Fly site, \`fly\` in chant.config.ts's chud.sites, declared with the fly
+ * lexicon's FlySite composite: the App, the Machine that serves the app (Fly's
+ * proxy sends 443 and 80 to its port ${v.port}), the Volume the app's data
+ * lives on, mounted at ${JSON.parse(v.volume.path)}, a public IP and the ${JSON.parse(v.secret.name)}
+ * Secret. \`chant build deploy --lexicon fly\` serializes it to Machines API
+ * requests, with the one Machine a release ships to. \`chant workspace graph
+ * --composites\` lists it as the instance \`flySite\`, which the app component
+ * (app.component.ts) deploys: it names FlySite in its \`composites\`.
+ *
+ * The same declarations apply to a real Fly org (FLY_API_TOKEN, and FLY_ORG
+ * for the org) or to mudflaps, the Machines API emulator, when
+ * FLY_FLAPS_BASE_URL points at it. Fly app names are global; change the name
+ * before the first release to a real org if it is taken.
+ *
+ * No secret value is in the repo. ${JSON.parse(v.secret.name)}'s value comes from the
+ * environment at release time; without it, the release checks the app
+ * already has it (\`fly secrets set ${JSON.parse(v.secret.name)}=...\`) and refuses otherwise.
+ *
+ * \`chant workspace upgrade\` wrote this from deploy/fly.ts and
+ * deploy/fly-machine.ts (its migration ${CHUD_LEXICON_EXIT_FLY_SITE}), with the
+ * same resources, in place of chud's FlySite marker and ChudLocalSite
+ * composite (ws-056). The local site is the studio kit's box service
+ * (arugula-salad/studio, template/).
+ */
+import { Fly, FlySite } from "@intentius/chant-lexicon-fly";
+${v.nameImport ? `${v.nameImport}\n` : ""}
+export const flySite = FlySite({
+  app: ${v.app},
+  org: Fly.OrgSlug,
+  region: ${v.region},
+  machine: ${v.machine},
+  image: ${v.image},
+  port: ${v.port},
+  env: ${v.env},
+  cpuKind: ${v.cpuKind},
+  cpus: ${v.cpus},
+  memoryMb: ${v.memoryMb},
+  volume: { name: ${v.volume.name}, sizeGb: ${v.volume.sizeGb}, path: ${v.volume.path} },
+  ip: ${v.ip},
+  secrets: { ${/^[A-Za-z_$][\w$]*$/.test(JSON.parse(v.secret.name)) ? JSON.parse(v.secret.name) : v.secret.name}: ${v.secret.value} },
+});
+`;
+}
+
+
+const COMPONENT_BARE = '  archetype: "service",\n  dependsOn: [],\n';
+const COMPONENT_NAMED = '  archetype: "service",\n  composites: ["FlySite"],\n  dependsOn: [],\n';
+const COMPONENT_SAID = " * (arugula-salad/studio, template/), and the Fly site's resources stay in\n * fly.ts and fly-machine.ts.\n */";
+const COMPONENT_SAYS =
+  " * (arugula-salad/studio, template/).\n *\n * It deploys the Fly site, the fly lexicon's FlySite composite in fly.ts, and\n * says so in `composites`, so `chant workspace graph --composites` lists the\n * site's instance with this component.\n */";
+/** The release Op's comment on where the Fly requests come from, as chud-lexicon-exit wrote it, and once the site is a FlySite. */
+const RELEASE_SAID = " *   deploy/fly.ts and deploy/fly-machine.ts, into dist/fly.json).";
+const RELEASE_SAYS = " *   the FlySite composite in deploy/fly.ts, into dist/fly.json).";
+
+interface Declaration {
+  members?: Array<{ dir?: string; kind?: string }>;
+}
+
+function planFlySite(ctx: ChantMigrationContext): ChantMigrationPlan | null {
+  const { dir } = ctx;
+  let decl: Declaration | null = null;
+  try {
+    decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "null") as Declaration | null;
+  } catch {
+    decl = null;
+  }
+  const candidates = (decl?.members ?? []).filter((m) => m.kind === "chant" && m.dir).map((m) => posix.normalize(m.dir!));
+  if (!candidates.includes("delivery")) candidates.push("delivery");
+
+  const changes: PlannedChange[] = [];
+  const notMoved: NotMoved[] = [];
+  for (const d of candidates) {
+    const at = (p: string) => posix.join(d, p);
+    const component = readText(dir, at("deploy/app.component.ts"));
+    if (component === undefined || !/its\s+\*?\s*migration chud-lexicon-exit\)/.test(component) || !component.includes(COMPONENT_BARE)) continue;
+
+    const fly = readText(dir, at("deploy/fly.ts"));
+    const machine = readText(dir, at("deploy/fly-machine.ts"));
+    const site = fly !== undefined && machine !== undefined ? readFlySite(fly, machine) : null;
+    if (site) {
+      changes.push({ path: at("deploy/fly.ts"), action: "write", why: "the Fly site as the fly lexicon's FlySite composite, the instance the app component deploys", data: Buffer.from(flySiteFile(site)) });
+      changes.push({ path: at("deploy/fly-machine.ts"), action: "delete", why: "its Machine is the FlySite composite's, in deploy/fly.ts" });
+      const release = readText(dir, at("ops/release.op.ts"));
+      if (release?.includes(RELEASE_SAID)) {
+        changes.push({ path: at("ops/release.op.ts"), action: "write", why: "its comment names the FlySite composite", data: Buffer.from(release.replace(RELEASE_SAID, RELEASE_SAYS)) });
+      }
+    } else if (fly !== undefined) {
+      notMoved.push({ what: `the Fly site as a composite instance (${at("deploy/fly.ts")} is not the template's, so its resources are kept as they are)`, where: "the fly lexicon's FlySite composite: declare the site with it, and the app component, which names FlySite in `composites`, deploys it" });
+    }
+    changes.push({ path: at("deploy/app.component.ts"), action: "write", why: "names FlySite in `composites`", data: Buffer.from(component.replace(COMPONENT_BARE, COMPONENT_NAMED).replace(COMPONENT_SAID, COMPONENT_SAYS)) });
+  }
+  if (changes.length === 0) return null;
+  return { id: CHUD_LEXICON_EXIT_FLY_SITE, description: DESCRIPTION, changes, notMoved, conflicts: [] };
+}
+
+export const chudLexiconExitFlySite: ChantMigration = {
+  id: CHUD_LEXICON_EXIT_FLY_SITE,
+  description: DESCRIPTION,
+  plan: planFlySite,
+};

package/src/workspace/chant-migrations/chud-lexicon-exit-live-names.ts

@@ -0,0 +1,164 @@
+/**
+ * `chud-lexicon-exit-live-names` (#2833): join the migrated `app` component
+ * to the Machine its release Op ships to, so `chant components status --live`
+ * reads it reconciled instead of stale.
+ *
+ * `chud-lexicon-exit` (0.92.0) rewrote `deploy/app.component.ts` off chud's
+ * app component, and wrote no `liveNames` on it. `components status --live`
+ * joins a component to live entities by name (`Component.liveNames`, falling
+ * back to the component's own name), and the component is `app` while the
+ * Machine the release Op ships to is some other entity. With no `liveNames`,
+ * the identity fallback looks for an entity named `app`, finds none, and the
+ * status reads `stale` even right after a release.
+ *
+ * This migration adds `liveNames: [<name>]` to the app component chant
+ * wrote, deriving `<name>` from what the member's Fly resources actually
+ * declare (#2839) rather than assuming one: while `deploy/fly-machine.ts`
+ * still declares the Machine directly, it is the entity `server`, its own
+ * top-level export. Once chant#2809's `FlySite` migration has taken over
+ * (deploy/fly.ts declares the site with the fly lexicon's `FlySite`
+ * composite and `fly-machine.ts` is gone), the composite expands its
+ * `machine` member under the site's own instance name, so the Machine is
+ * `<instance>Machine` — `flySiteMachine` for the instance name the FlySite
+ * migration writes (`flySite`), but read from the file rather than assumed,
+ * since a person may rename the export. The two migrations run in registry
+ * order (`FlySite` first), so a fresh upgrade that takes both always sees the
+ * post-`FlySite` shape by the time this one plans.
+ *
+ * It looks for the component `chud-lexicon-exit` left (by its own comment and
+ * shape) and inserts the field after `dependsOn: [],` rather than next to
+ * `archetype` — chant#2809's `FlySite` migration recognises the component by
+ * the exact, contiguous text `archetype: "service",\n  dependsOn: [],\n`, so
+ * anything inserted between those two lines (by either migration, in either
+ * order) would stop it from finding a component whose `composites` a person
+ * later removes. Anchoring after `dependsOn` instead keeps that pair intact
+ * whichever of the two migrations plans first.
+ *
+ * The plan is empty once `liveNames` already names the Machine this would
+ * derive. A component whose `liveNames` is exactly `["server"]` — this
+ * migration's own hardcoded output before #2839 — is corrected once the
+ * Machine it names is gone (`FlySite` has since taken over); any other
+ * hand-set value is left alone, on the same "by any hand" rule the empty
+ * case follows. It is a conflict when the component still reads as
+ * chud-lexicon-exit's but the `dependsOn: [],` line the edit anchors on is
+ * gone, or neither `deploy/fly.ts` nor `deploy/fly-machine.ts` says what the
+ * Machine's live name is — either way a person needs to add the mapping by
+ * hand.
+ */
+
+import { posix } from "node:path";
+import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, PlanConflict, PlannedChange } from "../chant-migrations";
+import { applyEdits, readText, CHUD_LEXICON_EXIT, type Edit } from "./chud-lexicon-exit";
+
+export const CHUD_LEXICON_EXIT_LIVE_NAMES = "chud-lexicon-exit-live-names";
+
+const DESCRIPTION = "join the app component to the Machine its release Op ships to, so components status --live reads it (#2833)";
+
+/** The app component `chud-lexicon-exit` writes, recognised by its own comment and shape (composites or not, ws-056's FlySite migration may have added one). */
+function isExitAppComponent(text: string): boolean {
+  return text.includes("wrote this from chud's app component") && text.includes(`migration ${CHUD_LEXICON_EXIT}`) && /name:\s*"app"/.test(text);
+}
+
+/** This migration's own hardcoded output before #2839, worth correcting once the Machine it names no longer exists. */
+const BAD_DEFAULT = 'liveNames: ["server"]';
+
+/**
+ * The live name of the Machine the member's release Op ships to, derived
+ * from what `deploy/fly.ts` and `deploy/fly-machine.ts` actually declare
+ * (#2839): `<instance>Machine`, from the export name a `FlySite` composite
+ * instance is declared under, once chant#2809's migration has taken over; the
+ * entity `server`, `fly-machine.ts`'s own top-level export, while that file
+ * still declares the Machine directly. Neither shape: null, so the caller
+ * leaves it to a person rather than guessing.
+ */
+function machineLiveName(dir: string, memberDir: string): string | null {
+  const fly = readText(dir, posix.join(memberDir, "deploy/fly.ts"));
+  const instance = fly !== undefined ? /^export const (\w+) = FlySite\(/m.exec(fly)?.[1] : undefined;
+  if (instance) return `${instance}Machine`;
+  if (readText(dir, posix.join(memberDir, "deploy/fly-machine.ts")) !== undefined) return "server";
+  return null;
+}
+
+function liveNamesEdits(name: string): Edit[] {
+  return [
+    {
+      find: /dependsOn: \[\],\n/,
+      replace: `dependsOn: [],\n  liveNames: ["${name}"],\n`,
+      required: "the dependsOn: [] line",
+    },
+    {
+      // Best-effort: names the Machine in the component's own doc comment, when
+      // it still reads as chud-lexicon-exit left it. Not required — an edited
+      // comment is left alone. The caller only reaches this when the component
+      // has no liveNames yet, so this never double-fires.
+      find: " * records no release. The local site is the studio kit's box service\n * (arugula-salad/studio, template/), and the Fly site's resources stay in\n * fly.ts and fly-machine.ts.\n",
+      replace:
+        " * records no release. The local site is the studio kit's box service\n" +
+        " * (arugula-salad/studio, template/), and the Fly site's resources stay in\n" +
+        " * fly.ts and fly-machine.ts. Its live name is the Machine the release Op\n" +
+        ` * ships to, the entity ${name} (chant#2833), which\n` +
+        " * `chant components status --live` observes for it.\n",
+    },
+  ];
+}
+
+interface Declaration {
+  members?: Array<{ dir?: string; kind?: string }>;
+}
+
+function planLiveNames(ctx: ChantMigrationContext): ChantMigrationPlan | null {
+  const { dir } = ctx;
+  let decl: Declaration | null = null;
+  try {
+    decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "null") as Declaration | null;
+  } catch {
+    decl = null;
+  }
+  const candidates = (decl?.members ?? []).filter((m) => m.kind === "chant" && m.dir).map((m) => posix.normalize(m.dir!));
+  if (!candidates.includes("delivery")) candidates.push("delivery");
+
+  const changes: PlannedChange[] = [];
+  const conflicts: PlanConflict[] = [];
+  for (const d of candidates) {
+    const path = posix.join(d, "deploy/app.component.ts");
+    const text = readText(dir, path);
+    if (text === undefined || !isExitAppComponent(text)) continue;
+
+    if (/liveNames:/.test(text)) {
+      // Already there, by any hand: nothing to add. Correct it only when it
+      // is exactly this migration's own bad default and the Machine it names
+      // is gone — any other value, including the right one, is left alone.
+      if (!text.includes(BAD_DEFAULT)) continue;
+      const name = machineLiveName(dir, d);
+      if (name === null || name === "server") continue;
+      changes.push({
+        path,
+        action: "write",
+        why: `liveNames: ["${name}"]: the app component joins the Machine the FlySite composite gives it now, in place of the entity this migration wrongly assumed (#2839)`,
+        data: Buffer.from(text.replace(BAD_DEFAULT, `liveNames: ["${name}"]`)),
+      });
+      continue;
+    }
+
+    const name = machineLiveName(dir, d);
+    if (name === null) {
+      conflicts.push({ path, reason: "cannot tell the Machine's live name from deploy/fly.ts or deploy/fly-machine.ts. Add liveNames to the app component by hand, then run the upgrade again" });
+      continue;
+    }
+    const edited = applyEdits(text, liveNamesEdits(name));
+    if (edited.missing.length > 0) {
+      conflicts.push({ path, reason: `cannot find ${edited.missing.join("; ")}. Add liveNames: ["${name}"] to the app component by hand, then run the upgrade again` });
+      continue;
+    }
+    if (edited.text === text) continue;
+    changes.push({ path, action: "write", why: `liveNames: ["${name}"]: the app component joins the Machine its release Op ships to`, data: Buffer.from(edited.text) });
+  }
+  if (changes.length === 0 && conflicts.length === 0) return null;
+  return { id: CHUD_LEXICON_EXIT_LIVE_NAMES, description: DESCRIPTION, changes, notMoved: [], conflicts };
+}
+
+export const chudLexiconExitLiveNames: ChantMigration = {
+  id: CHUD_LEXICON_EXIT_LIVE_NAMES,
+  description: DESCRIPTION,
+  plan: planLiveNames,
+};

package/src/workspace/chant-migrations/chud-lexicon-exit-rollback.ts

@@ -0,0 +1,223 @@
+/**
+ * `chud-lexicon-exit-rollback` (#2800): give a repo `chud-lexicon-exit`
+ * migrated the rollback Op chud had, on chant's own steps.
+ *
+ * `chud-lexicon-exit` shipped in 0.92.0 with a release Op that ships the app
+ * member to Fly as a source tree (#2782), and it deleted chud's rollback Op
+ * because nothing in chant could take that site back yet. This migration
+ * writes `ops/rollback.op.ts` beside the release Op, and a `rollback` script.
+ * A repo `chud-lexicon-exit` migrates from now on gets both, since this
+ * migration is planned after it in the same upgrade.
+ *
+ * The rollback is an Op rather than `chant components rollback` because the
+ * release is one: the release Op archives, plans, gates, ships and records,
+ * and the app component only runs the supply chain. Rolling back through the
+ * component would put publish and rollback in two places, which the boundary
+ * between Ops and components says not to do (components/backends-reference).
+ *
+ * The plan is empty unless the member's release Op is the one
+ * `chud-lexicon-exit` wrote, and once the rollback Op is there. A file at
+ * `ops/rollback.op.ts` that is not this one is a conflict.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import type { ChantMigration, ChantMigrationContext, ChantMigrationPlan, PlanConflict, PlannedChange } from "../chant-migrations";
+import { CHUD_LEXICON_EXIT } from "./chud-lexicon-exit";
+
+export const CHUD_LEXICON_EXIT_ROLLBACK = "chud-lexicon-exit-rollback";
+
+const DESCRIPTION = "add the rollback Op to a repo chud-lexicon-exit migrated: the previous source release back on the Fly site (#2800)";
+
+/** The release Op `chud-lexicon-exit` writes, recognised by what it holds. */
+function isExitReleaseOp(text: string): boolean {
+  return text.includes(`its migration ${CHUD_LEXICON_EXIT}`) && text.includes("flyRelease(") && text.includes("releasePlan(");
+}
+
+export function rollbackOp(pointsRel: string): string {
+  return `/**
+ * Rollback: put the release the Fly site served before the latest one back
+ * on it, once the rollback plan is approved, and record it.
+ *
+ * \`chant workspace upgrade\` wrote this (its migration ${CHUD_LEXICON_EXIT_ROLLBACK})
+ * in place of chud's rollback Op, beside the release Op (ops/release.op.ts):
+ *
+ * - Plan reads the \`fly\` release ledger. The release it goes back to is the
+ *   one the site served before the latest release the release Op shipped
+ *   (\`to: "sha256:..."\` on the plan step picks another). Its plan is read
+ *   back from chant/lifecycle, its commit's app member is archived again, and
+ *   the run stops unless the archive hashes to the digest that plan
+ *   recorded. The rollback plan names both releases and the archive, and is
+ *   named by its own sha256. Build writes the Fly app's requests.
+ * - The \`rollback\` gate approves that plan's digest: \`chant approve rollback
+ *   rollback --plan <digest>\`. It takes the ship gate's approver count and
+ *   Cedar policy (decisions/ship-skip.cedar.ts, \`log-only\`): a rollback has
+ *   no ship-skip answer, so only people pass it.
+ * - Roll back reads the archive again, refused unless it still hashes to the
+ *   planned digest, before any call to Fly. The Machine config the release
+ *   Op recorded for that release must carry exactly that tree under
+ *   /srv/app, or nothing changes. Then that config goes back on the Machine,
+ *   files and start command included, and the Machine must be started with
+ *   that release (and healthy at \`chud.sites.fly.url\` when set). Migrations
+ *   are not undone: the data stays where the later release left it.
+ * - Record appends the restored release to the \`fly\` release ledger, with
+ *   \`restores\` naming it, the actor who ran the rollback and the approver.
+ *
+ * Running it again changes nothing: the same ledger plans the same rollback,
+ * so its approval holds, the Machine already serves the release, and the
+ * ledger is written once. A release shipped after the rollback is the latest
+ * one again, so the next rollback goes back from it.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Op, phase, gate, build, releaseRollbackPlan, releaseRollbackRecord } from "@intentius/chant/op";
+import { parsePoints, quorumOf } from "@intentius/chant/workspace/points";
+import { flyRollback } from "@intentius/chant-lexicon-fly";
+import project from "../chant.config.ts";
+import { shipSkipPolicy } from "../decisions/ship-skip.cedar.ts";
+
+/** The environment the release Op ships to. */
+const ENV = "fly";
+/** Where the release Op put the files on the Machine. */
+const INTO = "/srv/app";
+const params = project.buildParams;
+/** The Fly site's public URL, when chant.config.ts gives one: the restored release is verified at its health endpoint too. */
+const siteUrl = (project as { chud?: { sites?: { fly?: { url?: string } } } }).chud?.sites?.fly?.url;
+
+const pointsFile = fileURLToPath(new URL(${JSON.stringify(pointsRel)}, import.meta.url));
+const shipSkipPoint = parsePoints(readFileSync(pointsFile, "utf-8"), pointsFile)["ship-skip"];
+
+const plan = releaseRollbackPlan({ id: "plan", component: "app", env: ENV });
+
+export default Op({
+  name: "rollback",
+  overview: \`Put the previous release of \${params.name.default} back on Fly once the rollback plan is approved.\`,
+  phases: [
+    phase("Plan", [plan, build(".", { script: "build:fly" })]),
+    phase("Gate", [
+      gate("rollback", {
+        plan: plan.out.digest,
+        description: \`Roll \${params.name.default} on \${ENV} back to its previous release\`,
+        approval: { quorum: quorumOf(shipSkipPoint), policy: shipSkipPolicy, mode: "log-only" },
+      }),
+    ]),
+    phase("Roll back", [
+      flyRollback({
+        environment: ENV,
+        component: "app",
+        plan: "dist/fly.json",
+        to: plan.out.to,
+        source: { archive: plan.out.archive, digest: plan.out.archiveDigest, dir: plan.out.dir, into: INTO },
+        verify: { url: siteUrl, healthPath: params.appHealth.default },
+      }),
+    ]),
+    phase("Record", [releaseRollbackRecord({ plan: plan.out.file, digest: plan.out.digest, approval: { op: "rollback", gate: "rollback" } })]),
+  ],
+});
+`;
+}
+
+/** The release Op's sentence about the rollback, as chud-lexicon-exit wrote it, and what it says once the rollback Op is there. */
+const RELEASE_SAID = /\), and rolling the site back to the previous\n \* release \(INTENTIUS\/chant#2800\)\. /;
+const RELEASE_SAYS = "). ops/rollback.op.ts rolls the site back to the\n * previous release. ";
+
+/** The root docs' lines `chud-lexicon-exit` wrote without a rollback (#2805), and what they say once it is there. Each is left alone when not found. */
+const DOC_EDITS: Array<{ path: string; find: string; replace: string }> = [
+  {
+    path: "README.md",
+    find: "the release Op (Check, the ship-skip decision point, then the ship gate), the app component's supply chain,",
+    replace: "the release Op (Check, the ship-skip decision point, then the ship gate) and the rollback Op, the app component's supply chain,",
+  },
+  {
+    path: "README.md",
+    find: "npm run release      # ship it\n",
+    replace: "npm run release      # ship it\nnpm run rollback     # chant run rollback: the previous release back, through its gate\n",
+  },
+  { path: "CLAUDE.md", find: "`ops/` (the release Op),", replace: "`ops/` (the release and rollback Ops)," },
+];
+
+interface Declaration {
+  members?: Array<{ name?: string; dir?: string; kind?: string }>;
+}
+
+function readText(dir: string, path: string): string | undefined {
+  const abs = join(dir, path);
+  return existsSync(abs) ? readFileSync(abs, "utf-8") : undefined;
+}
+
+function planRollback(ctx: ChantMigrationContext): ChantMigrationPlan | null {
+  const { dir } = ctx;
+  let decl: Declaration | null = null;
+  try {
+    decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "null") as Declaration | null;
+  } catch {
+    decl = null;
+  }
+  const candidates = (decl?.members ?? []).filter((m) => m.kind === "chant" && m.dir).map((m) => posix.normalize(m.dir!));
+  if (!candidates.includes("delivery")) candidates.push("delivery");
+  const members = candidates.filter((d) => {
+    const release = readText(dir, posix.join(d, "ops/release.op.ts"));
+    return release !== undefined && isExitReleaseOp(release);
+  });
+  if (members.length === 0) return null;
+
+  const changes: PlannedChange[] = [];
+  const conflicts: PlanConflict[] = [];
+  for (const d of members) {
+    const at = (p: string) => posix.join(d, p);
+    const opPath = at("ops/rollback.op.ts");
+    const text = rollbackOp(posix.relative(at("ops"), "decisions/points.json"));
+    const current = readText(dir, opPath);
+    if (current === undefined) {
+      changes.push({ path: opPath, action: "write", why: "chant's rollback Op: Plan from the release ledger with the archive checked again, the rollback gate, Roll back on Fly, and Record", data: Buffer.from(text) });
+    } else if (current !== text && !current.includes(`its migration ${CHUD_LEXICON_EXIT_ROLLBACK}`)) {
+      conflicts.push({ path: opPath, reason: "exists and is not the rollback Op this migration writes. Move it aside or delete it, then run the upgrade again" });
+      continue;
+    }
+
+    // The release Op's comment named the rollback as not chant's yet.
+    const releasePath = at("ops/release.op.ts");
+    const release = readText(dir, releasePath)!;
+    const said = RELEASE_SAID.exec(release);
+    if (said) {
+      changes.push({ path: releasePath, action: "write", why: "its comment names ops/rollback.op.ts", data: Buffer.from(release.replace(RELEASE_SAID, RELEASE_SAYS)) });
+    }
+
+    const pkgPath = at("package.json");
+    const pkgText = readText(dir, pkgPath);
+    if (pkgText !== undefined) {
+      try {
+        const pkg = JSON.parse(pkgText) as { scripts?: Record<string, string> };
+        if (pkg.scripts?.release === "chant run release" && pkg.scripts.rollback === undefined) {
+          const scripts: Record<string, string> = {};
+          for (const [k, v] of Object.entries(pkg.scripts)) {
+            scripts[k] = v;
+            if (k === "release") scripts.rollback = "chant run rollback";
+          }
+          const next = JSON.stringify({ ...pkg, scripts }, null, 2) + "\n";
+          changes.push({ path: pkgPath, action: "write", why: "adds `rollback`: chant run rollback", data: Buffer.from(next) });
+        }
+      } catch {
+        conflicts.push({ path: pkgPath, reason: "is not JSON" });
+      }
+    }
+  }
+  if (conflicts.length === 0) {
+    for (const path of [...new Set(DOC_EDITS.map((e) => e.path))]) {
+      const text = readText(dir, path);
+      if (text === undefined) continue;
+      let next = text;
+      for (const e of DOC_EDITS.filter((x) => x.path === path)) {
+        if (next.includes(e.find) && !next.includes(e.replace)) next = next.replace(e.find, e.replace);
+      }
+      if (next !== text) changes.push({ path, action: "write", why: "names the rollback Op", data: Buffer.from(next) });
+    }
+  }
+  return { id: CHUD_LEXICON_EXIT_ROLLBACK, description: DESCRIPTION, changes, notMoved: [], conflicts };
+}
+
+export const chudLexiconExitRollback: ChantMigration = {
+  id: CHUD_LEXICON_EXIT_ROLLBACK,
+  description: DESCRIPTION,
+  plan: planRollback,
+};