@intentius/chant 0.124.13 → 0.124.14

package/dist/workspace/chant-migrations/chud-lexicon-exit-fly-site.js

@@ -0,0 +1,198 @@
+/**
+ * `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";
+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, path) {
+    const abs = join(dir, path);
+    return existsSync(abs) ? readFileSync(abs, "utf-8") : undefined;
+}
+/** A file's code without its comments and blank lines. */
+function codeOf(text) {
+    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, machine) {
+    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) {
+    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).";
+function planFlySite(ctx) {
+    const { dir } = ctx;
+    let decl = null;
+    try {
+        decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "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 = [];
+    const notMoved = [];
+    for (const d of candidates) {
+        const at = (p) => 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 = {
+    id: CHUD_LEXICON_EXIT_FLY_SITE,
+    description: DESCRIPTION,
+    plan: planFlySite,
+};

package/dist/workspace/chant-migrations/chud-lexicon-exit-live-names.js

@@ -0,0 +1,155 @@
+/**
+ * `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 { applyEdits, readText, CHUD_LEXICON_EXIT } from "./chud-lexicon-exit.js";
+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) {
+    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, memberDir) {
+    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) {
+    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",
+        },
+    ];
+}
+function planLiveNames(ctx) {
+    const { dir } = ctx;
+    let decl = null;
+    try {
+        decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "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 = [];
+    const conflicts = [];
+    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 = {
+    id: CHUD_LEXICON_EXIT_LIVE_NAMES,
+    description: DESCRIPTION,
+    plan: planLiveNames,
+};

package/dist/workspace/chant-migrations/chud-lexicon-exit-rollback.js

@@ -0,0 +1,214 @@
+/**
+ * `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 { CHUD_LEXICON_EXIT } from "./chud-lexicon-exit.js";
+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) {
+    return text.includes(`its migration ${CHUD_LEXICON_EXIT}`) && text.includes("flyRelease(") && text.includes("releasePlan(");
+}
+export function rollbackOp(pointsRel) {
+    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 = [
+    {
+        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)," },
+];
+function readText(dir, path) {
+    const abs = join(dir, path);
+    return existsSync(abs) ? readFileSync(abs, "utf-8") : undefined;
+}
+function planRollback(ctx) {
+    const { dir } = ctx;
+    let decl = null;
+    try {
+        decl = JSON.parse(readText(dir, "chant.workspace.json") ?? "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 = [];
+    const conflicts = [];
+    for (const d of members) {
+        const at = (p) => 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);
+                if (pkg.scripts?.release === "chant run release" && pkg.scripts.rollback === undefined) {
+                    const scripts = {};
+                    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 = {
+    id: CHUD_LEXICON_EXIT_ROLLBACK,
+    description: DESCRIPTION,
+    plan: planRollback,
+};