@kedge/cli 0.0.0-stage → 0.9.0

package/src/deploy.ts

@@ -0,0 +1,1610 @@
+// `kedge deploy` and `kedge migrate --remote` (docs/proposals/p0.8-cli-agent-kit.md §6).
+// Migrations apply before the Worker, from the plan's own staged bytes. An
+// ordinary deploy is N−1: the previous Worker survives every pending file, by
+// proof or by statement (n1.ts). A core cutover runs behind a maintenance
+// Worker and the fence its migration installs. Every control-plane call is an
+// intent recorded first and closed by evidence, never by time (§3.1); every
+// step runs under an operation this process holds in the ops database, so a
+// lost runner loses nothing and two runners can't both act.
+import { randomBytes } from "node:crypto";
+import { chmodSync, cpSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { maintenanceModule } from "@kedge/runtime-cf/maintenance";
+import { DO_STATE_FORMAT } from "@kedge/runtime-cf/release";
+import { type Cloudflare, UnknownOutcome, type WorkerSettings } from "./cf";
+import type { Lock, LockEntry } from "./compose";
+import { declaredClasses } from "./doctor";
+import type { Manifest } from "./manifest";
+import { type Classified, classify } from "./n1";
+import { type DeploymentRow, type IntentRow, LostOwnership, OperationHeld, type OperationRow, OpsStore } from "./ops";
+import { byCodePoint } from "./order";
+import { schemaOf } from "./schema";
+import {
+  classesKey,
+  dirtyBeyondId,
+  type Git,
+  hashTree,
+  PLACEHOLDER_ID,
+  packageVersions,
+  type StoreNames,
+  sha256,
+  storeNames,
+  type WranglerJson,
+} from "./store";
+
+export const SCOPE = "production";
+/** Core's secrets, generated only at a first deploy and only where missing (§6.1). */
+export const CORE_SECRETS = [
+  "CART_TOKEN_SECRET",
+  "ORDER_TOKEN_SECRET",
+  "KEDGE_AUTH_SECRET_V1",
+  "KEDGE_KEY_PEPPER_V1",
+  "KEDGE_TOTP_KEY_V1",
+] as const;
+/** Publications a cutover's abort must survive: maintenance and the release (§6.3). */
+const CUTOVER_PUBLICATIONS = 2;
+/** For anything done outside Kedge. */
+const OUTSIDE_MARGIN = 10;
+
+export interface Plan {
+  /** A person's --allow-older, kept with the plan so a resume honours it and nothing else does. */
+  allowOlder?: boolean;
+  version: 1;
+  commit: string;
+  release: string;
+  upgradesFrom: string | null;
+  doStateFormat: number;
+  lockSha: string;
+  /** Every composed file's hash: what's staged, and what a resume must reproduce. */
+  files: Record<string, string>;
+  vars: Record<string, string>;
+  /** The effective Wrangler config: wrangler.jsonc with ops's ids and the plan's vars, paths relative. */
+  config: WranglerJson;
+  packages: Record<string, string>;
+  modules: Record<string, string>;
+  /** The admin's staged assets, each file's hash (p0.9 §3.3): a resume must reproduce them too. */
+  assets?: Record<string, string>;
+  window: { from: number; to: number } | null;
+  /** --adopt names a person said are the store's own. */
+  adopt: string[];
+}
+
+export interface Progress {
+  databaseId?: string;
+  queueId?: string;
+  first?: boolean;
+  deploymentId?: string;
+  mode?: "n1" | "cutover";
+  pending?: string[];
+  classified?: Classified[];
+  maintenanceVersion?: string;
+  appVersion?: string;
+  /** The plan `appVersion` was uploaded for: a version is reused only by the plan it was built from. */
+  appFor?: string;
+  /** A rotation's uploaded version, so a recovery can finish activating it. */
+  secretVersion?: string;
+  /**
+   * The release has served: from here the lifecycle is the release's, and maintenance from before it
+   * can never be activated again, whether by a resume, a recovery or a supersede. Never cleared.
+   */
+  released?: boolean;
+  /** The Durable Object migrations serving once released: a maintenance needed after that is built from them. */
+  liveMigrations?: WranglerJson["migrations"];
+  /** Maintenance has been sent: the store may be down, so from here a resume recovers rather than asks for a window. */
+  downtime?: boolean;
+}
+
+export interface Half {
+  bookmark?: string | null;
+  lockSha: string;
+  versionId: string | null;
+  release: string | null;
+  doMigrations: WranglerJson["migrations"] | null;
+  /** The queue consumers deployed: an upload doesn't apply consumer settings, a full deploy does (codex code r13). */
+  consumers?: unknown[] | null;
+  doStateFormat: number | null;
+  crons: string[] | null;
+  settings: WorkerSettings | null;
+  /**
+   * In a before half, the commit being deployed. In an after half, the commit of the
+   * application serving after the operation, carried through secret rotations and recorded
+   * versions, so the stale-job guard always has one to compare (codex code r1).
+   */
+  commit?: string;
+  packages?: Record<string, string>;
+  configSha?: string;
+  config?: WranglerJson;
+  mode?: string;
+  window?: Plan["window"];
+  note?: string;
+}
+
+export interface DeployDeps {
+  cf: Cloudflare;
+  cwd: string;
+  manifest: Manifest | null;
+  lock: Lock;
+  git: Git;
+  /** `wrangler deploy --dry-run --outdir`: bundles the store's code (§6.2). */
+  bundle: (config: string, outdir: string) => void;
+  /** `kedge check --fast`; tests skip it. */
+  checkFast: () => Promise<number>;
+  // biome-ignore lint/suspicious/noExplicitAny: each plugin brings its own options type
+  plugins: readonly import("@kedge/core").PluginInstance<any>[];
+  now?: () => number;
+  log?: (s: string) => void;
+  /** Random secret material; tests make it deterministic. */
+  secret?: () => string;
+  /**
+   * The deploy's environment: a core secret found here (a merchant's vault, exported to the deploy) is
+   * what a first deploy attaches instead of a generated one (codex code r21).
+   */
+  env?: NodeJS.ProcessEnv;
+}
+
+export interface DeployOptions {
+  vars?: Record<string, string>;
+  window?: { from: number; to: number };
+  adopt?: string[];
+  allowOlder?: boolean;
+  resume?: boolean;
+  takeOver?: string;
+  confirmStopped?: boolean;
+}
+
+export class DeployRefused extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "DeployRefused";
+  }
+}
+
+const lockSha = (lock: Lock) => sha256(JSON.stringify(lock.entries.map((e) => [e.file, e.sha256])));
+
+/** The ops database: found or created by exact name, and refused unless it's this store's (§6.1). */
+export async function openOps(
+  cf: Cloudflare,
+  names: StoreNames,
+  now = Date.now,
+): Promise<{ ops: OpsStore; id: string }> {
+  let id = await cf.findD1(names.ops);
+  if (!id) {
+    try {
+      id = await cf.createD1(names.ops);
+    } catch (e) {
+      // Two first deploys contending here both end at the same database (§6.1). Whatever the
+      // error said, the name is what decides: found, it's the other deploy's; the meta check
+      // below refuses a database that isn't Kedge's.
+      id = await cf.findD1(names.ops);
+      if (!id) throw e;
+    }
+  }
+  const dbId = id;
+  const tables = (
+    await cf.queryD1(dbId, "SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE '_cf_%'")
+  ).map((r) => String(r.name));
+  if (tables.length && !tables.includes("kedge_ops_meta"))
+    throw new DeployRefused(`${names.ops} exists and isn't a Kedge operations database: it holds ${tables.join(", ")}`);
+  const ops = new OpsStore((sql, params) => cf.queryD1(dbId, sql, params), now);
+  await ops.init(names.worker);
+  return { ops, id: dbId };
+}
+
+/**
+ * Migrations this operation submitted that aren't proven to have stayed unrun: neither applied,
+ * nor refused by Cloudflare, nor stated never-run by a person. Absence from d1_migrations permits
+ * retrying the same bytes, and nothing else: a late landing would put those bytes under the
+ * filename (codex code r5, r6).
+ */
+export async function uncertainMigrations(ops: OpsStore, opId: string): Promise<IntentRow[]> {
+  return (await ops.intents(SCOPE, opId)).filter(
+    (i) =>
+      i.kind === "migrate" &&
+      i.state !== "done" &&
+      i.state !== "failed" &&
+      !(i.state === "not_executed" && i.resolved_by?.startsWith("stated by")),
+  );
+}
+
+/** The commit of the application serving now: the latest finished operation's after half. */
+function servingCommit(rows: readonly { after_half: string | null }[]): string | undefined {
+  const last = rows.find((r) => r.after_half);
+  return last ? (JSON.parse(last.after_half as string) as Half).commit : undefined;
+}
+
+/**
+ * d1_migrations' names, in the order they were applied; none on a fresh database, where
+ * Wrangler hasn't made the table yet. Asked of sqlite_master, not read from an error:
+ * Cloudflare's answer to a missing table carries a code (7500), not SQLite's text.
+ */
+export async function appliedNames(cf: Cloudflare, databaseId: string): Promise<string[]> {
+  const made = await cf.queryD1(
+    databaseId,
+    "SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = 'd1_migrations'",
+  );
+  if (!made.length) return [];
+  return (await cf.queryD1(databaseId, "SELECT name FROM d1_migrations ORDER BY id")).map((r) => String(r.name));
+}
+
+/**
+ * Doctor's `applied` check (§4.3): what D1 recorded is a prefix of the lock,
+ * and what ops recorded of each file's bytes still matches. Wrangler applies
+ * any file it hasn't recorded, even one numbered below applied ones (research/15).
+ */
+export function appliedProblems(lock: Lock, applied: readonly string[], hashes: ReadonlyMap<string, string>): string[] {
+  const problems: string[] = [];
+  const files = lock.entries.map((e) => e.file);
+  const known = new Set(files);
+  for (const a of applied) if (!known.has(a)) problems.push(`D1 applied ${a}, which kedge.lock.json doesn't list`);
+  const set = new Set(applied);
+  let gap: string | null = null;
+  for (const f of files) {
+    if (!set.has(f)) gap ??= f;
+    else if (gap)
+      problems.push(`${f} is applied but ${gap}, before it in the lock, isn't: wrangler would apply it out of order`);
+  }
+  for (const e of lock.entries) {
+    const h = hashes.get(e.file);
+    if (h !== undefined && h !== e.sha256)
+      problems.push(
+        `${e.file} changed after it was applied (recorded ${h.slice(0, 12)}, lock ${e.sha256.slice(0, 12)})`,
+      );
+  }
+  return problems;
+}
+
+export class Deployer {
+  readonly now: () => number;
+  readonly log: (s: string) => void;
+  readonly names: StoreNames;
+  readonly wrangler: WranglerJson;
+  private ops!: OpsStore;
+  private opId!: string;
+  private plan!: Plan;
+  private progress: Progress = {};
+
+  constructor(private readonly d: DeployDeps) {
+    this.now = d.now ?? Date.now;
+    this.log = d.log ?? ((s) => console.log(s));
+    const s = storeNames(d.cwd);
+    this.names = s.names;
+    this.wrangler = s.config;
+  }
+
+  private dir(...p: string[]) {
+    return join(this.d.cwd, ".kedge", "deploy", ...p);
+  }
+
+  private async step(step: string) {
+    await this.ops.step(SCOPE, this.opId, step, this.progress);
+    this.log(`· ${step}`);
+  }
+
+  /** Runs a control-plane call as an intent: recorded first, closed by its answer, unknown on silence (§3.1). */
+  private async intent<T>(
+    step: string,
+    kind: string,
+    tag: string,
+    detail: unknown,
+    call: () => Promise<T>,
+  ): Promise<T> {
+    const id = await this.ops.openIntent(SCOPE, this.opId, step, kind, tag, detail);
+    try {
+      const out = await call();
+      await this.ops.closeIntent(id, "done", "answer");
+      return out;
+    } catch (e) {
+      await this.ops.closeIntent(id, e instanceof UnknownOutcome ? "unknown" : "failed", "answer");
+      throw e;
+    }
+  }
+
+  private tag(kind: string) {
+    return `kedge:${this.opId}:${kind}:${this.now().toString(36)}`;
+  }
+
+  // ---- the plan (§6.2 step 2) -----------------------------------------------------------------------
+  /** Builds the effective config, bundles and stages; nothing on Cloudflare yet. */
+  async buildPlan(o: DeployOptions, databaseId: string | null, buildDir: string): Promise<Plan> {
+    const g = this.d.git;
+    const commit = g.head();
+    const dirty = dirtyBeyondId(this.d.cwd, g, databaseId ?? this.names.databaseId);
+    if (dirty.length)
+      throw new DeployRefused(`commit first: the worktree has changes (${dirty.slice(0, 5).join(", ")})`);
+    const routes = this.wrangler.routes ?? this.wrangler.route;
+    if (routes !== undefined)
+      throw new DeployRefused(
+        "wrangler.jsonc declares routes: kedge deploy manages cron and settings in P0.8, not routes or custom domains; attach a domain in the dashboard until P0.10",
+      );
+    const vars = { ...(this.wrangler.vars ?? {}), ...(o.vars ?? {}) };
+    const config: WranglerJson = { ...this.wrangler, vars };
+    delete config.build;
+    const dbs = (config.d1_databases ?? []).map((d) =>
+      d.binding === "DB" && databaseId ? { ...d, database_id: databaseId } : d,
+    );
+    config.d1_databases = dbs;
+    rmSync(buildDir, { recursive: true, force: true });
+    mkdirSync(buildDir, { recursive: true });
+    // The admin's assets, staged beside the bundle (p0.9 §3.3): what uploads, and what a resume reproduces.
+    const admin = stageAssets(this.d.cwd, config, join(buildDir, "assets"));
+    // The bundle: from the store's code, with a config whose paths are absolute, and the admin's build
+    // in its code, so a new admin build is new Worker code (p0.9 §2.4).
+    const buildConfig = join(buildDir, "build.wrangler.json");
+    writeFileSync(
+      buildConfig,
+      JSON.stringify({
+        ...config,
+        main: resolve(this.d.cwd, String(config.main ?? "src/index.ts")),
+        // The store's own constants kept, the admin's build beside them (it wins its one name).
+        ...(admin
+          ? {
+              assets: { ...config.assets, directory: join(buildDir, "assets") },
+              define: { ...((config as { define?: Record<string, string> }).define ?? {}), ...admin.define },
+            }
+          : {}),
+      }),
+    );
+    this.d.bundle(buildConfig, join(buildDir, "bundle"));
+    // The plan's SQL is what runs: every composed file, staged as bytes (§6.2).
+    mkdirSync(join(buildDir, "migrations"), { recursive: true });
+    const files: Record<string, string> = {};
+    for (const e of this.d.lock.entries) {
+      const bytes = readFileSync(join(this.d.cwd, "migrations", e.file));
+      if (sha256(bytes) !== e.sha256)
+        throw new DeployRefused(`${e.file} doesn't match kedge.lock.json; run kedge doctor`);
+      writeFileSync(join(buildDir, "migrations", e.file), bytes);
+      files[e.file] = e.sha256;
+    }
+    const m = this.d.manifest;
+    return {
+      version: 1,
+      commit,
+      release: m?.version ?? "workspace",
+      upgradesFrom: m?.upgradesFrom ?? null,
+      doStateFormat: m?.doStateFormat ?? DO_STATE_FORMAT,
+      lockSha: lockSha(this.d.lock),
+      files,
+      vars,
+      config,
+      packages: packageVersions(this.d.cwd),
+      modules: hashTree(join(buildDir, "bundle")),
+      ...(admin ? { assets: hashTree(join(buildDir, "assets")) } : {}),
+      window: o.window ?? null,
+      adopt: o.adopt ?? [],
+    };
+  }
+
+  /** A resume deploys what was planned or nothing (§6.2): the rebuild must reproduce it. */
+  private reproduces(planned: Plan, rebuilt: Plan): string[] {
+    const diffs: string[] = [];
+    if (planned.commit !== rebuilt.commit)
+      diffs.push(`commit ${rebuilt.commit.slice(0, 10)} isn't the plan's ${planned.commit.slice(0, 10)}`);
+    if (JSON.stringify(planned.modules) !== JSON.stringify(rebuilt.modules))
+      diffs.push("the bundle's modules differ from the plan's");
+    if (JSON.stringify(planned.assets ?? null) !== JSON.stringify(rebuilt.assets ?? null))
+      diffs.push("the admin's assets differ from the plan's");
+    if (JSON.stringify(planned.packages) !== JSON.stringify(rebuilt.packages))
+      diffs.push("installed Kedge differs from the plan's");
+    if (JSON.stringify(planned.files) !== JSON.stringify(rebuilt.files))
+      diffs.push("the composed migrations differ from the plan's");
+    return diffs;
+  }
+
+  // ---- resources (§6.1) ------------------------------------------------------------------------------
+  private async own(
+    kind: "d1" | "queue",
+    name: string,
+    find: () => Promise<string | null>,
+    create: () => Promise<string>,
+  ): Promise<string> {
+    const rec = await this.ops.resource(kind, name);
+    if (rec?.id) return rec.id;
+    const found = await find();
+    if (found) {
+      if (rec?.state === "creating" || this.plan.adopt.includes(name)) {
+        await this.ops.recordResource(kind, name, found, "ours");
+        return found;
+      }
+      throw new DeployRefused(
+        `${name} exists and this store never recorded making it; if it's yours, deploy with --adopt ${name}`,
+      );
+    }
+    await this.ops.recordResource(kind, name, null, "creating");
+    let id: string;
+    try {
+      id = await this.intent("provision", "create", `${kind}:${name}`, { kind, name }, create);
+    } catch (e) {
+      if (!(e instanceof UnknownOutcome)) throw e;
+      // A lost answer: the name is ours (recorded first), so a lookup recovers it.
+      const again = await find();
+      if (!again) throw e;
+      id = again;
+    }
+    await this.ops.recordResource(kind, name, id, "ours");
+    return id;
+  }
+
+  private async ownWorker(): Promise<boolean> {
+    const rec = await this.ops.resource("worker", this.names.worker);
+    const exists = await this.d.cf.findWorker(this.names.worker);
+    if (rec) return exists;
+    if (exists && !this.plan.adopt.includes(this.names.worker))
+      throw new DeployRefused(
+        `a Worker named ${this.names.worker} exists and this store never recorded deploying it; if it's this store, deploy with --adopt ${this.names.worker}`,
+      );
+    // Recorded as ours before its first upload (§6.1).
+    await this.ops.recordResource("worker", this.names.worker, null, "ours");
+    return exists;
+  }
+
+  // ---- what's serving (§6.2) ------------------------------------------------------------------------
+  /** The deployment row whose version serves, or null on a first deploy; refuses what nobody recorded. */
+  private async serving(
+    rows: readonly DeploymentRow[],
+  ): Promise<{ row: DeploymentRow | null; versionId: string | null }> {
+    const deps = await this.d.cf.deployments(this.names.worker);
+    const active = deps[0];
+    if (!active) return { row: null, versionId: null };
+    if (active.versions.length !== 1)
+      throw new DeployRefused(
+        `${this.names.worker} serves a split across ${active.versions.length} versions; nobody can say what's serving`,
+      );
+    const versionId = (active.versions[0] as { version_id: string }).version_id;
+    const row = rows.find((r) => (r.after_half ? (JSON.parse(r.after_half) as Half).versionId === versionId : false));
+    if (!row)
+      throw new DeployRefused(
+        `${this.names.worker} serves version ${versionId}, which no deployment recorded (a dashboard edit, a rollback by hand or a plain wrangler secret put?); if it's this store's code, run kedge deploy --record-active --reason "<what>"`,
+      );
+    return { row, versionId };
+  }
+
+  private compatible(row: DeploymentRow | null): void {
+    if (!row) return;
+    this.compatibleWith((JSON.parse(row.after_half ?? "{}") as Half).release);
+  }
+
+  private compatibleWith(release: string | null): void {
+    if (release === null || release === this.plan.release || release === this.plan.upgradesFrom) return;
+    throw new DeployRefused(
+      `the store serves Kedge ${release}; ${this.plan.release} was proven against ${this.plan.upgradesFrom ?? "nothing"}: deploy the releases between in turn (kedge upgrade lists them)`,
+    );
+  }
+
+  private async triggersOf(exists: boolean): Promise<{ crons: string[] | null; settings: WorkerSettings | null }> {
+    if (!exists) return { crons: null, settings: null };
+    return {
+      crons: await this.d.cf.schedules(this.names.worker),
+      settings: await this.d.cf.settings(this.names.worker),
+    };
+  }
+
+  // ---- the run ----------------------------------------------------------------------------------------
+  /** A fresh deploy, or a resume of the held one. */
+  async deploy(o: DeployOptions): Promise<void> {
+    if ((await this.d.checkFast()) !== 0) throw new DeployRefused("kedge check --fast failed");
+    // A merchant's own core secret, checked before anything starts rather than at the upload.
+    for (const s of CORE_SECRETS) {
+      const v = this.d.env?.[s];
+      if (v !== undefined && v.length < 32) throw new DeployRefused(`${s} in the environment is under 32 bytes`);
+    }
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    this.ops = ops;
+    const held = await ops.current(SCOPE);
+    if (o.resume || o.takeOver) {
+      if (!held) throw new DeployRefused("nothing to resume: no operation holds this store");
+      if (!["deploy", "secret", "migrate", "adopt", "record-active"].includes(held.kind))
+        throw new DeployRefused(`the held operation is a ${held.kind}, which kedge deploy can't continue`);
+      const row = o.takeOver ? await this.takeOver(held, o) : await ops.resume(SCOPE, held.op_id);
+      // Every production operation has a way out, or one stopped would hold the store for good (codex code r1).
+      if (row.kind === "secret") return this.recoverSecret(row);
+      if (row.kind === "migrate") return this.migrateRemote(row);
+      if (row.kind === "adopt" || row.kind === "record-active") {
+        this.opId = row.op_id;
+        await this.abandonRecording(`${row.kind} stopped before it finished`);
+        this.log(
+          `released ${row.op_id}: nothing it began changed Cloudflare; run kedge deploy --${row.kind === "adopt" ? "adopt-existing" : "record-active"} again`,
+        );
+        return;
+      }
+      this.opId = row.op_id;
+      this.plan = JSON.parse(row.plan) as Plan;
+      this.progress = JSON.parse(row.progress) as Progress;
+      if (o.vars && Object.entries(o.vars).some(([k, v]) => this.plan.vars?.[k] !== v)) {
+        await this.ops.stop(SCOPE, this.opId);
+        throw new DeployRefused("a resume takes its vars from the plan; a conflicting --var refuses");
+      }
+      // A new window, while nothing is down yet: kept with the plan (codex code r18).
+      if (o.window && !this.progress.downtime) {
+        this.plan.window = o.window;
+        await this.ops.supersede(SCOPE, this.opId, this.plan);
+      }
+    } else {
+      if (held) throw new DeployRefused(new OperationHeld(held).message);
+      const commit = this.d.git.head();
+      const dirty = dirtyBeyondId(this.d.cwd, this.d.git, (await ops.resource("d1", this.names.database))?.id ?? null);
+      if (dirty.length)
+        throw new DeployRefused(`commit first: the worktree has changes (${dirty.slice(0, 5).join(", ")})`);
+      // Provisioning is the operation's first phase (§6.1): the plan freezes the ids it finds.
+      // Every option the plan will need, kept from the start: a run stopped before the plan froze resumes
+      // with them (codex code r26).
+      this.plan = {
+        commit,
+        adopt: o.adopt ?? [],
+        vars: o.vars ?? {},
+        window: o.window ?? null,
+        ...(o.allowOlder ? { allowOlder: true } : {}),
+      } as Plan;
+      this.opId = await ops.start(SCOPE, "deploy", this.plan, "started");
+      this.pending = o;
+    }
+    try {
+      await this.reconcile();
+      await this.run();
+    } catch (e) {
+      await this.end(e);
+      throw e;
+    }
+  }
+
+  /**
+   * After a failure: a refusal before anything was recorded about the store
+   * ends the operation (nothing to resume); anything else stops it, held for
+   * a resume, with its unanswered calls unknown.
+   */
+  private async end(e: unknown): Promise<void> {
+    const clean =
+      e instanceof DeployRefused && !this.progress.deploymentId && (await this.ops.unresolved(SCOPE)).length === 0;
+    if (clean) await this.ops.finish(SCOPE, this.opId, "refused", [this.plan]).catch(() => {});
+    else await this.ops.stop(SCOPE, this.opId).catch(() => {});
+  }
+
+  /** Set while a superseding plan, already built and checked, runs its first pass. */
+  private superseded = false;
+
+  /** Options of a fresh deploy, for the plan built once provisioning knows the ids. */
+  private pending: DeployOptions | null = null;
+
+  /** Builds and freezes the plan, or, on a resume, proves this checkout reproduces it (§6.2). */
+  private async freeze(): Promise<void> {
+    const p = this.progress;
+    const target = this.dir(this.opId);
+    if (this.plan.modules) {
+      const rebuilt = await this.buildPlan(
+        { vars: this.plan.vars, adopt: this.plan.adopt, ...(this.plan.window ? { window: this.plan.window } : {}) },
+        p.databaseId ?? null,
+        `${target}-rebuild`,
+      );
+      const diffs = this.reproduces(this.plan, rebuilt);
+      if (diffs.length) throw new DeployRefused(`this checkout doesn't reproduce the plan:\n  ${diffs.join("\n  ")}`);
+      // A plan saved before its guard ran (a lost answer) is guarded here, before anything mutates (codex code r10).
+      await this.staleGuard(this.plan);
+      rmSync(target, { recursive: true, force: true });
+      cpSync(`${target}-rebuild`, target, { recursive: true });
+      rmSync(`${target}-rebuild`, { recursive: true, force: true });
+      return;
+    }
+    const o = this.pending ?? {};
+    const started = this.plan;
+    this.plan = await this.buildPlan(
+      { ...o, adopt: started.adopt, vars: started.vars, ...(started.window ? { window: started.window } : {}) },
+      p.databaseId ?? null,
+      target,
+    );
+    if (o.allowOlder || started.allowOlder) this.plan.allowOlder = true;
+    await this.staleGuard(this.plan);
+    await this.ops.supersede(SCOPE, this.opId, this.plan);
+  }
+
+  /** An older job mustn't overwrite a newer release (§3.1), unless a person said so with --allow-older. */
+  private async staleGuard(plan: Plan): Promise<void> {
+    const stale = await this.staleness(plan);
+    if (stale) await this.refuse(stale);
+  }
+
+  private async staleness(plan: Plan): Promise<string | null> {
+    const lastCommit = servingCommit(await this.ops.deployments());
+    if (lastCommit && !plan.allowOlder && !this.d.git.isAncestor(lastCommit, plan.commit))
+      return `the last deployment's commit ${lastCommit.slice(0, 10)} isn't an ancestor of ${plan.commit.slice(0, 10)}: an older job mustn't overwrite a newer release (--allow-older if it's meant)`;
+    return null;
+  }
+
+  /**
+   * Adoption and recording write only to the ops database, so an interrupted one is undone, not
+   * continued: its unfinished manifest row removed (a retry of --adopt-existing needs none), and
+   * the operation released. Its resource and applied records are true either way (codex code r9).
+   */
+  private async abandonRecording(outcome: string): Promise<void> {
+    await this.ops.query("DELETE FROM deployment WHERE op_id = ? AND after_half IS NULL", [this.opId]);
+    await this.ops.finish(SCOPE, this.opId, outcome, []);
+  }
+
+  /**
+   * A refusal, ended by end(): finished only when it provably came before any deployment, held
+   * otherwise. A refused corrected plan inside a cutover already in maintenance must not take the
+   * operation, and its recovery, with it (codex code r25).
+   */
+  private async refuse(message: string): Promise<never> {
+    throw new DeployRefused(message);
+  }
+
+  private async takeOver(held: OperationRow, o: DeployOptions): Promise<OperationRow> {
+    if (held.op_id !== o.takeOver) throw new DeployRefused(`the held operation is ${held.op_id}, not ${o.takeOver}`);
+    if (held.executor && !o.confirmStopped)
+      throw new DeployRefused(
+        `${held.op_id} is run by ${held.executor_label}: take over only once it's cancelled, or its Cloudflare token rotated, and say so with --confirm-stopped`,
+      );
+    return this.ops.takeOver(SCOPE, held.op_id, held.executor);
+  }
+
+  /** Before acting, every unknown call is closed by evidence or left for a person (§3.1). */
+  private async reconcile(): Promise<void> {
+    const open = await this.ops.unresolved(SCOPE);
+    const blocking: IntentRow[] = [];
+    for (const i of open) {
+      if (i.kind === "upload") {
+        await this.ops.closeIntent(i.id, "unknown", "uploads never block");
+        continue;
+      }
+      if (i.kind === "migrate") {
+        const files = (JSON.parse(i.detail) as { files: string[] }).files;
+        const applied = new Set(await appliedNames(this.d.cf, this.progress.databaseId as string));
+        if (files.every((f) => applied.has(f))) {
+          await this.ops.closeIntent(i.id, "done", "d1_migrations lists every file");
+          continue;
+        }
+        // An unapplied file re-runs safely: it's atomic and recorded, and a late duplicate fails on its own.
+        await this.ops.closeIntent(i.id, "not_executed", "d1_migrations lacks a file; re-running is safe");
+        continue;
+      }
+      if (i.kind === "create") {
+        const { kind, name } = JSON.parse(i.detail) as { kind: string; name: string };
+        const found = kind === "d1" ? await this.d.cf.findD1(name) : await this.d.cf.findQueue(name);
+        if (found) await this.ops.closeIntent(i.id, "done", "an exact-name lookup found it");
+        else blocking.push(i);
+        continue;
+      }
+      if (i.kind === "activate") {
+        const deps = await this.d.cf.deployments(this.names.worker);
+        const landed = deps.find((d) => d.message?.includes(i.tag));
+        if (landed) {
+          await this.ops.closeIntent(i.id, "done", "the deployment list shows its tag");
+          continue;
+        }
+      }
+      blocking.push(i);
+    }
+    // A class-changing deploy is its own upload: the version it made is the release's. Rebuilt from every
+    // landed one, unresolved until a moment ago or closed by an answer whose progress write a crash lost:
+    // a resume that didn't know it would put maintenance back, a rollback across a class change Cloudflare
+    // refuses (codex code r15, r20).
+    if (!this.progress.released) {
+      const classDeploys = (await this.ops.intents(SCOPE, this.opId)).filter(
+        (i) =>
+          i.kind === "activate" &&
+          i.state === "done" &&
+          (JSON.parse(i.detail) as { classChange?: boolean }).classChange,
+      );
+      if (classDeploys.length) {
+        const deps = await this.d.cf.deployments(this.names.worker);
+        const landed = classDeploys
+          .map((i) => deps.find((d) => d.message?.includes(i.tag))?.versions[0]?.version_id)
+          .find(Boolean);
+        if (landed) {
+          this.progress.appVersion = landed;
+          this.progress.appFor = sha256(JSON.stringify(this.plan));
+          this.progress.released = true;
+          this.progress.liveMigrations = this.plan.config.migrations ?? [];
+          delete this.progress.maintenanceVersion;
+          await this.ops.step(SCOPE, this.opId, "released", this.progress);
+        }
+      }
+    }
+    if (blocking.length)
+      throw new DeployRefused(
+        `calls whose outcome nobody knows block this store:\n${blocking
+          .map((i) => `  ${i.id} ${i.kind} at "${i.step}" (${i.tag})`)
+          .join(
+            "\n",
+          )}\nEach could still land. If you're sure one never took effect: kedge deploy --resolve-intent <id> --not-executed (a call Cloudflare already accepted could still land after it)`,
+      );
+  }
+
+  private async run(): Promise<void> {
+    const p = this.progress;
+    const cf = this.d.cf;
+    await this.step("provision");
+    p.databaseId = await this.own(
+      "d1",
+      this.names.database,
+      () => cf.findD1(this.names.database),
+      () => cf.createD1(this.names.database),
+    );
+    p.queueId = await this.own(
+      "queue",
+      this.names.queue,
+      () => cf.findQueue(this.names.queue),
+      () => cf.createQueue(this.names.queue),
+    );
+    const workerExists = await this.ownWorker();
+    if (p.first === undefined) {
+      // First means never deployed, by the store's history, not merely no Worker today: a deleted Worker
+      // over a surviving database would get new secrets that its stored keys and factors don't match,
+      // and new Durable Objects that forget what the journal and clock knew (codex code r17).
+      const deployed = (await this.ops.deployments()).some((r) => r.after_half);
+      if (deployed && !workerExists)
+        await this.refuse(
+          `${this.names.worker} has been deployed, but no Worker by that name exists now: a deploy would make new secrets and Durable Objects over the surviving database. Restore the Worker (its secrets and objects) before deploying; doctor --remote reports it`,
+        );
+      p.first = !workerExists;
+    }
+    await this.step("provisioned");
+    this.writeDatabaseId(p.databaseId);
+    if (!this.superseded) await this.freeze();
+    this.superseded = false;
+    await this.step("planned");
+
+    // §6.2 steps 3–5: what's applied, what's pending, and whether the running Worker survives it.
+    const applied = await appliedNames(cf, p.databaseId);
+    const problems = appliedProblems(this.d.lock, applied, await this.ops.appliedHashes());
+    if (problems.length) await this.refuse(`the store's migrations don't match the lock:\n  ${problems.join("\n  ")}`);
+    const appliedSet = new Set(applied);
+    const pendingEntries: LockEntry[] = this.d.lock.entries.filter((e) => !appliedSet.has(e.file));
+    p.pending ??= pendingEntries.map((e) => e.file);
+    const staged = (f: string) => readFileSync(this.dir(this.opId, "migrations", f), "utf8");
+    if (!p.classified) {
+      try {
+        p.classified = classify({
+          cwd: this.d.cwd,
+          lock: this.d.lock,
+          pending: pendingEntries,
+          manifest: this.d.manifest,
+          plugins: this.d.plugins,
+          text: staged,
+        });
+      } catch (e) {
+        await this.refuse((e as Error).message);
+      }
+    }
+    const needed = (p.classified ?? []).some((c) => c.mode === "cutover") ? "cutover" : "n1";
+    // A superseding plan can't turn an N−1 deploy into a cutover: the live Worker has had no
+    // maintenance and the window was never checked (codex code r5).
+    if (p.mode === "n1" && needed === "cutover")
+      await this.refuse(
+        "the superseding plan holds a cutover, but this deploy began N−1 with the live Worker serving: end it, then deploy the cutover with --maintenance-window",
+      );
+    p.mode ??= needed;
+    const rows = await this.ops.deployments();
+    // Once the "before" half exists this operation may itself be what serves (maintenance), so what
+    // served before is read from that half, not from Cloudflare.
+    const { row: servingRow, versionId: servingVersion } =
+      p.first || p.deploymentId ? { row: null, versionId: null } : await this.serving(rows);
+    if (!p.deploymentId) this.compatible(servingRow);
+    if (p.mode === "cutover" && !p.first && !p.deploymentId) {
+      const w = this.plan.window;
+      if (!w || this.now() < w.from || this.now() > w.to)
+        await this.refuse(
+          "a pending core migration is a cutover: on a store that has served traffic it needs --maintenance-window <from>/<to>, with now inside it (§6.3)",
+        );
+    }
+    await this.step("classified");
+
+    // §6.5: the "before" half, with the bookmark that belongs to the code that ran before.
+    if (!p.deploymentId) {
+      const t = await this.triggersOf(workerExists);
+      const prior = servingRow ? (JSON.parse(servingRow.after_half ?? "{}") as Half) : null;
+      const before: Half = {
+        bookmark: await cf.bookmark(p.databaseId),
+        lockSha: sha256(
+          JSON.stringify(this.d.lock.entries.filter((e) => appliedSet.has(e.file)).map((e) => [e.file, e.sha256])),
+        ),
+        versionId: servingVersion,
+        release: prior?.release ?? null,
+        doMigrations: prior?.doMigrations ?? null,
+        consumers: prior?.consumers ?? null,
+        doStateFormat: prior?.doStateFormat ?? null,
+        crons: t.crons,
+        settings: t.settings,
+        // The code that ran before, beside the bookmark taken before this deploy's migrations: its commit,
+        // packages and config are the serving manifest's (codex code r19).
+        commit: prior?.commit,
+        packages: prior?.packages,
+        configSha: prior?.configSha,
+        config: prior?.config,
+        mode: p.mode,
+        window: this.plan.window,
+      };
+      p.deploymentId = await this.ops.addDeployment(this.opId, p.mode, before);
+      await this.step("before");
+    }
+    const before = JSON.parse(
+      (rows.find((r) => r.id === p.deploymentId) ?? (await this.ops.deployments()).find((r) => r.id === p.deploymentId))
+        ?.before_half ?? "{}",
+    ) as Half;
+
+    // Maintenance from before the release never comes back once it has served (codex code r4, r15, r16: the
+    // third time, so `released` is a fact of its own that a supersede keeps). After it, only a cutover still
+    // pending needs maintenance, built from the lifecycle that serves now.
+    const cutoverPending = (p.classified ?? []).some((c) => c.mode === "cutover" && !appliedSet.has(c.file));
+    if (p.mode === "cutover" && !p.first && !p.appVersion && (!p.released || cutoverPending))
+      await this.maintenance(before, p.released ? (p.liveMigrations ?? []) : (before.doMigrations ?? []));
+    await this.migrate();
+    await this.release(before);
+    // What's recorded as deployed must be what serves, whichever step a resume came back at.
+    await this.activate("activate", p.appVersion as string);
+    await this.markReleased();
+
+    const after: Half = {
+      lockSha: this.plan.lockSha,
+      commit: this.plan.commit,
+      packages: this.plan.packages,
+      configSha: sha256(JSON.stringify(this.plan.config)),
+      config: this.plan.config,
+      versionId: p.appVersion as string,
+      release: this.plan.release,
+      doMigrations: this.plan.config.migrations ?? [],
+      consumers: this.plan.config.queues?.consumers ?? [],
+      doStateFormat: this.plan.doStateFormat,
+      crons: await cf.schedules(this.names.worker),
+      settings: await cf.settings(this.names.worker),
+    };
+    await this.step("after");
+    await this.ops.completeDeployment(p.deploymentId, after);
+    await this.ops.finish(SCOPE, this.opId, "deployed", [this.plan]);
+    rmSync(this.dir(this.opId), { recursive: true, force: true });
+    this.log(
+      `deployed ${this.names.worker} at version ${after.versionId} (Kedge ${this.plan.release}, ${p.mode}); restore point ${before.bookmark}`,
+    );
+  }
+
+  /**
+   * The first deploy writes the database id over the starter's placeholder:
+   * one known literal, safe where general JSONC editing isn't (§6.1). A real
+   * id that differs from ops's refuses.
+   */
+  private writeDatabaseId(id: string): void {
+    const file = join(this.d.cwd, "wrangler.jsonc");
+    if (!existsSync(file)) return;
+    const text = readFileSync(file, "utf8");
+    if (this.names.databaseId === PLACEHOLDER_ID) {
+      if (text.includes(PLACEHOLDER_ID)) {
+        writeFileSync(file, text.replace(PLACEHOLDER_ID, id));
+        this.log(`wrangler.jsonc now names database ${id}: commit it`);
+      }
+    } else if (this.names.databaseId !== id)
+      throw new DeployRefused(`wrangler.jsonc names database ${this.names.databaseId}, but this store's is ${id}`);
+  }
+
+  // ---- §6.3: maintenance ------------------------------------------------------------------------------
+  /** The release serves: recorded before anything else can run, and kept by every later plan. */
+  private async markReleased(): Promise<void> {
+    const p = this.progress;
+    if (p.released && p.maintenanceVersion === undefined) return;
+    p.released = true;
+    p.liveMigrations = this.plan.config.migrations ?? [];
+    delete p.maintenanceVersion;
+    await this.ops.step(SCOPE, this.opId, "released", p);
+  }
+
+  private async maintenance(before: Half, migrations: NonNullable<WranglerJson["migrations"]>): Promise<void> {
+    const p = this.progress;
+    const cf = this.d.cf;
+    if (!p.maintenanceVersion) {
+      // Abort has to stay executable, so it's checked first: the target must outlive this cutover's publications.
+      const versions = await cf.versions(this.names.worker);
+      const n = versions.findIndex((v) => v.id === before.versionId);
+      const recent = (
+        await this.ops.query("SELECT COUNT(*) AS n FROM intent WHERE kind = 'upload' AND created_at > ?", [
+          this.now() - 7 * 86_400_000,
+        ])
+      )[0];
+      const budget = CUTOVER_PUBLICATIONS + 3 * Number(recent?.n ?? 0) + OUTSIDE_MARGIN;
+      const headroom = n < 0 ? -1 : 99 - n;
+      if (headroom <= budget)
+        await this.refuse(
+          `a cutover could push the serving version out of Cloudflare's 100-version rollback window (headroom ${headroom}, budget ${budget}): redeploy the same release first to freshen it`,
+        );
+      const dir = this.dir(this.opId, "maintenance");
+      mkdirSync(dir, { recursive: true });
+      const classes = declaredClasses(migrations as never);
+      writeFileSync(join(dir, "index.js"), maintenanceModule(classes));
+      // Only the bindings whose classes the stubs export: a release's new class arrives with the release.
+      const bindings = (
+        (this.plan.config.durable_objects as { bindings?: { name: string; class_name: string }[] } | undefined)
+          ?.bindings ?? []
+      ).filter((b) => classes.includes(b.class_name));
+      const config = {
+        ...this.plan.config,
+        // The admin's assets stay (p0.9 §2.5): an open admin shows the maintenance page, not a broken one.
+        ...(this.plan.config.assets
+          ? { assets: { ...this.plan.config.assets, directory: this.dir(this.opId, "assets") } }
+          : {}),
+        durable_objects: { bindings },
+        main: join(dir, "index.js"),
+        // Exactly the serving classes: maintenance changes no lifecycle, so it blocks no rollback.
+        migrations,
+        triggers: { crons: before.crons ?? [] },
+      };
+      delete (config as Record<string, unknown>).build;
+      writeFileSync(join(dir, "wrangler.json"), JSON.stringify(config));
+      await this.step("maintenance-upload");
+      p.maintenanceVersion = await this.intent("maintenance-upload", "upload", this.tag("maintenance"), {}, () =>
+        cf.uploadVersion({ config: join(dir, "wrangler.json"), message: `kedge maintenance ${this.opId}` }),
+      );
+      await this.step("maintenance-uploaded");
+    }
+    // Downtime starts only inside the window, however long preparing took or whenever a resume runs
+    // (codex code r18); once maintenance has been sent, recovering it needs no window.
+    if (!p.downtime) {
+      const w = this.plan.window;
+      if (!w || this.now() < w.from || this.now() > w.to)
+        throw new DeployRefused(
+          "the maintenance window isn't open now: nothing is down yet, so resume inside it, or give a new one with kedge deploy --resume --maintenance-window <from>/<to>",
+        );
+      p.downtime = true;
+      await this.step("maintenance-activate");
+    }
+    await this.activate("maintenance-activate", p.maintenanceVersion);
+  }
+
+  /** One activation: an intent tagged in the deployment's message, single attempt (§3.1). */
+  private async activate(step: string, versionId: string): Promise<void> {
+    const deps = await this.d.cf.deployments(this.names.worker);
+    if (deps[0]?.versions.length === 1 && deps[0].versions[0]?.version_id === versionId) return; // already serving
+    await this.step(step);
+    const tag = this.tag("activate");
+    await this.intent(step, "activate", tag, { versionId }, () =>
+      this.d.cf.activate(this.names.worker, versionId, tag),
+    );
+  }
+
+  // ---- §6.2 step 6: migrations from the staged bytes --------------------------------------------------
+  private async migrate(): Promise<void> {
+    const p = this.progress;
+    const cf = this.d.cf;
+    const applied = new Set(await appliedNames(cf, p.databaseId as string));
+    const pending = (p.pending ?? []).filter((f) => !applied.has(f));
+    for (const f of [...applied]) {
+      const e = this.d.lock.entries.find((x) => x.file === f);
+      if (e) await this.ops.recordApplied(f, e.sha256);
+    }
+    if (pending.length === 0) return;
+    await this.step("migrate");
+    const dir = this.dir(this.opId);
+    for (const f of pending)
+      if (sha256(readFileSync(join(dir, "migrations", f))) !== this.plan.files[f])
+        throw new DeployRefused(`the staged ${f} doesn't match the plan`);
+    const config = join(dir, "migrate.wrangler.json");
+    writeFileSync(
+      config,
+      JSON.stringify({
+        name: this.names.worker,
+        compatibility_date: this.plan.config?.compatibility_date ?? this.wrangler.compatibility_date,
+        d1_databases: [
+          {
+            binding: "DB",
+            database_name: this.names.database,
+            database_id: p.databaseId,
+            migrations_dir: join(dir, "migrations"),
+          },
+        ],
+      }),
+    );
+    try {
+      await this.intent("migrate", "migrate", this.tag("migrate"), { files: pending }, () =>
+        cf.applyMigrations({ config, database: this.names.database }),
+      );
+    } finally {
+      const now = new Set(await appliedNames(cf, p.databaseId as string));
+      for (const f of pending) if (now.has(f)) await this.ops.recordApplied(f, this.plan.files[f] as string);
+    }
+  }
+
+  // ---- §6.2 step 7: the release --------------------------------------------------------------------------
+  private async release(before: Half): Promise<void> {
+    const p = this.progress;
+    const cf = this.d.cf;
+    const dir = this.dir(this.opId);
+    const config = {
+      ...this.plan.config,
+      main: join(dir, "bundle", "index.js"),
+      no_bundle: true,
+      // The staged copy, by absolute path: the release config lives elsewhere than wrangler.jsonc (p0.9 §3.3).
+      ...(this.plan.config.assets ? { assets: { ...this.plan.config.assets, directory: join(dir, "assets") } } : {}),
+    };
+    config.d1_databases = (config.d1_databases ?? []).map((d) =>
+      d.binding === "DB" ? { ...d, database_id: p.databaseId } : d,
+    );
+    delete (config as Record<string, unknown>).build;
+    for (const d of config.d1_databases ?? []) if (d.migrations_dir) d.migrations_dir = join(dir, "migrations");
+    const configFile = join(dir, "release.wrangler.json");
+    writeFileSync(configFile, JSON.stringify(config));
+    // `wrangler deploy` where an upload can't do it: Cloudflare needs it for a class change, and only it
+    // applies queue consumer settings (codex code r13). Unrecorded consumers (an adopted store) count as changed.
+    const classChange =
+      p.first ||
+      classesKey(before.doMigrations ?? []) !== classesKey(this.plan.config.migrations ?? []) ||
+      JSON.stringify(before.consumers ?? null) !== JSON.stringify(this.plan.config.queues?.consumers ?? []);
+    const planKey = sha256(JSON.stringify(this.plan));
+    if (p.appVersion && p.appFor !== planKey) delete p.appVersion;
+    if (!p.appVersion) {
+      // Secrets travel with a tracked version, generated only on a first deploy and only where missing (§6.1).
+      const have = p.first ? new Set(await cf.secretNames(this.names.worker)) : new Set<string>();
+      const generate = p.first ? CORE_SECRETS.filter((s) => !have.has(s)) : [];
+      let secretsFile: string | undefined;
+      if (generate.length) {
+        secretsFile = join(dir, "secrets.json");
+        const secret = this.d.secret ?? (() => randomBytes(32).toString("base64url"));
+        writeFileSync(
+          secretsFile,
+          JSON.stringify(Object.fromEntries(generate.map((s) => [s, this.d.env?.[s] ?? secret()]))),
+          {
+            mode: 0o600,
+          },
+        );
+        chmodSync(secretsFile, 0o600);
+      }
+      try {
+        await this.step("upload");
+        const tag = this.tag(classChange ? "deploy" : "upload");
+        if (classChange) {
+          // Cloudflare requires `wrangler deploy` for a class change; its hidden retry is §12's stated gap.
+          p.appVersion = await this.intent("upload", "activate", tag, { classChange: true }, () =>
+            cf.deployWithClasses({ config: configFile, message: tag, ...(secretsFile ? { secretsFile } : {}) }),
+          );
+        } else {
+          p.appVersion = await this.intent("upload", "upload", tag, {}, () =>
+            cf.uploadVersion({ config: configFile, message: tag, ...(secretsFile ? { secretsFile } : {}) }),
+          );
+        }
+      } finally {
+        if (secretsFile) rmSync(secretsFile, { force: true });
+      }
+      p.appFor = planKey;
+      await this.step("uploaded");
+    }
+    if (!classChange) await this.activate("activate", p.appVersion as string);
+    await this.markReleased();
+    await this.triggers(this.plan.config.triggers?.crons ?? [], { logpush: false, invocationLogs: false });
+  }
+
+  /** Crons and settings, each a single-attempt call read back before it counts (§3.1). */
+  private async triggers(crons: readonly string[], settings: WorkerSettings): Promise<void> {
+    const cf = this.d.cf;
+    const want = [...crons].sort();
+    if (JSON.stringify(await cf.schedules(this.names.worker)) !== JSON.stringify(want)) {
+      await this.step("triggers");
+      await this.intent("triggers", "triggers", this.tag("crons"), { crons: want }, () =>
+        cf.putSchedules(this.names.worker, want),
+      );
+      if (JSON.stringify(await cf.schedules(this.names.worker)) !== JSON.stringify(want))
+        throw new DeployRefused("the cron schedules didn't read back as set");
+    }
+    const s = await cf.settings(this.names.worker);
+    if (s.logpush !== settings.logpush || s.invocationLogs !== settings.invocationLogs) {
+      await this.step("settings");
+      await this.intent("settings", "triggers", this.tag("settings"), settings, () =>
+        cf.patchSettings(this.names.worker, settings),
+      );
+      const back = await cf.settings(this.names.worker);
+      if (back.invocationLogs !== settings.invocationLogs)
+        throw new DeployRefused("the Worker's settings didn't read back as set");
+    }
+  }
+
+  // ---- §6.2: a plan that can't finish is superseded, not edited ---------------------------------------------
+  /**
+   * `kedge deploy --supersede <op-id>`, from the corrected commit after `kedge
+   * generate --supersede`: a new plan under the same operation, refused unless
+   * every applied migration is in the new lock with the same hash and order.
+   * The "before" half stays: it's still the store's real starting point.
+   */
+  async supersede(opId: string): Promise<void> {
+    if ((await this.d.checkFast()) !== 0) throw new DeployRefused("kedge check --fast failed");
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    this.ops = ops;
+    const held = await ops.current(SCOPE);
+    if (!held || held.op_id !== opId) throw new DeployRefused(`no operation ${opId} holds this store`);
+    const row = await ops.resume(SCOPE, opId);
+    this.opId = opId;
+    const old = JSON.parse(row.plan) as Plan;
+    // Reconcile reads the plan a landed release was built from: the old one, until the new one is checked (codex code r20).
+    this.plan = old;
+    this.progress = JSON.parse(row.progress) as Progress;
+    try {
+      await this.reconcile();
+      const applied = await appliedNames(this.d.cf, this.progress.databaseId as string);
+      const lock = this.d.lock.entries;
+      const problems = applied.flatMap((f, i) =>
+        lock[i]?.file !== f
+          ? [`${f} is applied but the new lock has ${lock[i]?.file ?? "nothing"} at its place`]
+          : old.files?.[f] !== undefined && lock[i]?.sha256 !== old.files[f]
+            ? [`${f} is applied, and the new lock changes its bytes`]
+            : [],
+      );
+      if (problems.length)
+        throw new DeployRefused(`the corrected lock doesn't keep what's applied:\n  ${problems.join("\n  ")}`);
+      const next = new Map(lock.map((e) => [e.file, e.sha256]));
+      const changed = (await uncertainMigrations(ops, opId)).flatMap((i) =>
+        (JSON.parse(i.detail) as { files: string[] }).files.filter((f) => next.get(f) !== old.files?.[f]),
+      );
+      if (changed.length)
+        throw new DeployRefused(
+          `${changed.join(", ")} ${changed.length === 1 ? "was" : "were"} submitted and could still land: the corrected lock may retry ${changed.length === 1 ? "it" : "them"} unchanged, not replace ${changed.length === 1 ? "it" : "them"}. Fix forward with a new migration, or a person who knows it never ran says so with --resolve-intent <id> --not-executed`,
+        );
+      this.plan = await this.buildPlan(
+        { vars: old.vars, adopt: old.adopt, ...(old.window ? { window: old.window } : {}) },
+        this.progress.databaseId ?? null,
+        this.dir(opId),
+      );
+      // A replacement answers to the rules any plan does, before it's saved (codex code r11): descended
+      // from what serves, and proven against the release that served before this operation began.
+      if (old.allowOlder) this.plan.allowOlder = true;
+      const stale = await this.staleness(this.plan);
+      if (stale) throw new DeployRefused(stale);
+      const started = this.progress.deploymentId
+        ? (await ops.deployments()).find((r) => r.id === this.progress.deploymentId)
+        : undefined;
+      if (started) this.compatibleWith((JSON.parse(started.before_half) as Half).release);
+      else this.compatible((await this.serving(await ops.deployments())).row);
+      // Classified before it's saved, too: a refused replacement must leave the operation as it was, its
+      // own plan and recovery intact (codex code r25).
+      const pendingNow = this.d.lock.entries.filter((e) => !applied.includes(e.file));
+      let classified: Classified[];
+      try {
+        classified = classify({
+          cwd: this.d.cwd,
+          lock: this.d.lock,
+          pending: pendingNow,
+          manifest: this.d.manifest,
+          plugins: this.d.plugins,
+          text: (f) => readFileSync(this.dir(opId, "migrations", f), "utf8"),
+        });
+      } catch (e) {
+        throw new DeployRefused((e as Error).message);
+      }
+      if (this.progress.mode === "n1" && classified.some((c) => c.mode === "cutover"))
+        throw new DeployRefused(
+          "the superseding plan holds a cutover, but this deploy began N−1 with the live Worker serving: end it, then deploy the cutover with --maintenance-window",
+        );
+      const kept: Progress = { ...this.progress };
+      delete kept.pending;
+      delete kept.classified;
+      delete kept.appVersion;
+      await ops.supersede(SCOPE, opId, this.plan, kept);
+      this.progress = kept;
+      // What's pending is recomputed from the new lock; the deployment and its mode stay.
+      await ops.step(SCOPE, opId, "superseded", this.progress);
+      this.superseded = true;
+      this.log(`superseded ${opId}'s plan with ${this.plan.commit.slice(0, 10)}`);
+      await this.run();
+    } catch (e) {
+      await this.end(e);
+      throw e;
+    }
+  }
+
+  // ---- a person's word: --resolve-intent, --record-active, --abort-cutover --------------------------------
+  async resolveIntent(id: string, notExecuted: boolean): Promise<void> {
+    if (!notExecuted)
+      throw new DeployRefused(
+        "--resolve-intent needs --not-executed: it's a statement that the call never took effect",
+      );
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    const i = await ops.intent(id);
+    // Also a migration reconcile closed for its absence: absence permits a retry, only a person can say it never ran.
+    const restatable = i?.kind === "migrate" && i.state === "not_executed" && !i.resolved_by?.startsWith("stated by");
+    if (!i || (!["open", "unknown"].includes(i.state) && !restatable))
+      throw new DeployRefused(`${id} isn't an unresolved call`);
+    const held = await ops.current(i.scope);
+    if (held?.executor) throw new DeployRefused(`${held.op_id} is running; stop it first`);
+    await ops.closeIntent(id, "not_executed", `stated by ${ops.label}`);
+    this.log(
+      `${id} marked not executed. If Cloudflare had accepted it, it could still land; kedge doctor --remote reports what serves.`,
+    );
+  }
+
+  async recordActive(reason: string): Promise<void> {
+    if (!reason) throw new DeployRefused("--record-active needs --reason");
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    this.ops = ops;
+    // The operation first, then the reads it records (codex code r12).
+    this.opId = await ops.start(SCOPE, "record-active", { reason }, "record");
+    try {
+      await this.recordActiveChecked(reason);
+    } catch (e) {
+      if (!(e instanceof LostOwnership)) await this.abandonRecording(`failed: ${(e as Error).name}`).catch(() => {});
+      throw e;
+    }
+  }
+
+  private async recordActiveChecked(reason: string): Promise<void> {
+    const ops = this.ops;
+    const rows = await ops.deployments();
+    const deps = await this.d.cf.deployments(this.names.worker);
+    const v = deps[0]?.versions;
+    if (v?.length !== 1) throw new DeployRefused("the Worker serves no single version");
+    const last = rows.find((r) => r.after_half);
+    if (!last)
+      throw new DeployRefused(
+        "no deployment is recorded yet: a store deployed before P0.8 enters with --adopt-existing",
+      );
+    const prior = JSON.parse(last.after_half as string) as Half;
+    await this.recordActiveRun(reason, prior, (v[0] as { version_id: string }).version_id);
+  }
+
+  private async recordActiveRun(reason: string, prior: Half, versionId: string): Promise<void> {
+    const ops = this.ops;
+    const id = await ops.addDeployment(this.opId, "recorded", {
+      ...prior,
+      note: `recorded by ${ops.label}: ${reason}`,
+    });
+    await ops.completeDeployment(id, {
+      ...prior,
+      versionId,
+      crons: await this.d.cf.schedules(this.names.worker),
+      settings: await this.d.cf.settings(this.names.worker),
+      note: reason,
+    });
+    await ops.finish(SCOPE, this.opId, "recorded", [{ reason }]);
+    this.log(`recorded version ${versionId} as ${prior.release}`);
+  }
+
+  async abortCutover(): Promise<void> {
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    this.ops = ops;
+    const held = await ops.current(SCOPE);
+    if (!held) throw new DeployRefused("no operation to abort");
+    const row = await ops.resume(SCOPE, held.op_id);
+    this.opId = row.op_id;
+    this.plan = JSON.parse(row.plan) as Plan;
+    this.progress = JSON.parse(row.progress) as Progress;
+    try {
+      const p = this.progress;
+      if (p.mode !== "cutover")
+        throw new DeployRefused("only a cutover is aborted; an N−1 deploy's previous Worker still serves");
+      // A submitted migration absent from d1_migrations may be retried forward, but it isn't proven
+      // not to land: if it lands after the rollback, its fence stops the Worker abort put back (codex code r5).
+      // One that applied is caught below with the fence it installed.
+      const submitted = await uncertainMigrations(ops, this.opId);
+      if (submitted.length)
+        throw new DeployRefused(
+          `a migration was submitted under this operation (${submitted.map((i) => i.id).join(", ")}) and could still land: the only way out is forward (kedge deploy --resume), or a person who knows it never ran says so with --resolve-intent <id> --not-executed`,
+        );
+      const applied = new Set(await appliedNames(this.d.cf, p.databaseId as string));
+      if ((p.pending ?? []).some((f) => applied.has(f)))
+        throw new DeployRefused(
+          "a pending migration has applied, and the fence with it: the only way out is forward (fix it, then kedge generate --supersede)",
+        );
+      const dep = (await ops.deployments()).find((r) => r.id === p.deploymentId);
+      const before = JSON.parse(dep?.before_half ?? "{}") as Half;
+      if (!before.versionId) throw new DeployRefused("no previous version to return to");
+      const versions = await this.d.cf.versions(this.names.worker);
+      if (!versions.some((v) => v.id === before.versionId))
+        throw new DeployRefused(
+          `version ${before.versionId} has left Cloudflare's rollback window: the path is forward`,
+        );
+      await this.reconcile();
+      await this.activate("abort", before.versionId);
+      await this.triggers(before.crons ?? [], before.settings ?? { logpush: false, invocationLogs: false });
+      await ops.completeDeployment(p.deploymentId as string, {
+        ...before,
+        commit: servingCommit((await ops.deployments()).filter((r) => r.id !== p.deploymentId)),
+        note: "cutover aborted",
+      });
+      await ops.finish(SCOPE, this.opId, "aborted", [this.plan]);
+      this.log(`aborted: ${this.names.worker} serves ${before.versionId} again`);
+    } catch (e) {
+      await ops.stop(SCOPE, this.opId).catch(() => {});
+      throw e;
+    }
+  }
+
+  // ---- `kedge secret put|delete`: a keyring rotation as a tracked operation (§3) -----------------------
+  async secret(name: string, value: string | null): Promise<void> {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(name))
+      throw new DeployRefused("a secret's name is upper-case letters, digits and underscores");
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    this.ops = ops;
+    const rows = await ops.deployments();
+    this.plan = { commit: "secret", adopt: [], vars: {} } as unknown as Plan;
+    this.opId = await ops.start(SCOPE, "secret", { name, delete: value === null }, "start");
+    try {
+      await this.reconcile();
+      const { row } = await this.serving(rows);
+      if (!row) throw new DeployRefused("nothing is deployed yet");
+      // Wrangler's `versions secret` copies the newest uploaded version, not the serving one, so an
+      // upload that was never activated would ship with the rotation under the old manifest (codex code r3).
+      const serving = (await this.d.cf.deployments(this.names.worker))[0]?.versions;
+      const newest = [...(await this.d.cf.versions(this.names.worker))].sort((a, b) =>
+        byCodePoint(b.created, a.created),
+      )[0];
+      if (serving?.length !== 1 || serving[0]?.version_id !== newest?.id)
+        throw new DeployRefused(
+          `the newest uploaded version (${newest?.id ?? "none"}) isn't the one serving alone (${serving?.map((v) => v.version_id).join(", ") ?? "none"}): kedge secret would ship it. Finish or roll back that deploy first`,
+        );
+      const prior = JSON.parse(row.after_half as string) as Half;
+      this.progress.deploymentId = await ops.addDeployment(this.opId, "secret", {
+        ...prior,
+        note: `${value === null ? "deleted" : "set"} ${name}`,
+      });
+      await this.step("version");
+      const tag = this.tag("secret");
+      const versionId = await this.intent("version", "upload", tag, { name }, () =>
+        this.d.cf.versionSecret(this.names.worker, name, value, tag),
+      );
+      this.progress.secretVersion = versionId;
+      await this.step("uploaded");
+      await this.activate("activate", versionId);
+      await ops.completeDeployment(this.progress.deploymentId, {
+        ...prior,
+        versionId,
+        crons: await this.d.cf.schedules(this.names.worker),
+        settings: await this.d.cf.settings(this.names.worker),
+        note: `${value === null ? "deleted" : "set"} ${name}`,
+      });
+      await ops.finish(SCOPE, this.opId, "secret", [{ name }]);
+      this.log(`${value === null ? "deleted" : "set"} ${name}: version ${versionId} serves`);
+    } catch (e) {
+      await this.end(e);
+      throw e;
+    }
+  }
+
+  /**
+   * A stopped `kedge secret`, continued by `kedge deploy --resume` or `--take-over`. Its value
+   * was never stored, so it can't be uploaded again: once its calls are closed by evidence,
+   * an activation that landed completes the manifest, and anything short of that releases the
+   * store with the serving version unchanged, for `kedge secret` to be run again.
+   */
+  private async recoverSecret(row: OperationRow): Promise<void> {
+    this.opId = row.op_id;
+    this.plan = JSON.parse(row.plan) as Plan;
+    this.progress = JSON.parse(row.progress) as Progress;
+    const ops = this.ops;
+    const what = JSON.parse(row.plan) as { name?: string; delete?: boolean };
+    try {
+      await this.reconcile();
+      const intents = await ops.intents(SCOPE, this.opId);
+      const landed = intents.find((i) => i.kind === "activate" && i.state === "done");
+      let versionId = landed ? (JSON.parse(landed.detail) as { versionId?: string }).versionId : undefined;
+      if (!versionId) {
+        // Its upload, by the id it recorded or by its tag in the version list, is activated to finish: left
+        // newer than what serves, it would refuse every later rotation (codex code r5).
+        const tags = new Set(intents.filter((i) => i.kind === "upload").map((i) => i.tag));
+        const own =
+          this.progress.secretVersion ??
+          (await this.d.cf.versions(this.names.worker)).find((v) => v.message && tags.has(v.message))?.id;
+        if (own) {
+          await this.activate("activate", own);
+          versionId = own;
+        }
+      }
+      // The manifest this rotation started from: the latest finished one but its own.
+      const prior = (await ops.deployments()).find((r) => r.after_half && r.id !== this.progress.deploymentId);
+      const before = prior ? (JSON.parse(prior.after_half as string) as Half) : null;
+      if (this.progress.deploymentId && before)
+        await ops.completeDeployment(this.progress.deploymentId, {
+          ...before,
+          ...(versionId
+            ? {
+                versionId,
+                crons: await this.d.cf.schedules(this.names.worker),
+                settings: await this.d.cf.settings(this.names.worker),
+              }
+            : {}),
+          note: versionId ? `${what.delete ? "deleted" : "set"} ${what.name}` : `${what.name}: not applied`,
+        });
+      await ops.finish(SCOPE, this.opId, versionId ? "secret" : "secret not applied", [what]);
+      this.log(
+        versionId
+          ? `${what.name} was applied: version ${versionId} serves`
+          : `${what.name} wasn't applied; nothing changed: run kedge secret again`,
+      );
+    } catch (e) {
+      await this.end(e);
+      throw e;
+    }
+  }
+
+  // ---- `kedge migrate --remote`: the shared runner without a Worker deploy (§3) ---------------------------
+  /** A fresh run, or (from `kedge deploy --resume`) the held one, which this checkout's lock must match. */
+  async migrateRemote(held?: OperationRow): Promise<void> {
+    // A resumed run keeps the executor that claimed it.
+    if (!held) this.ops = (await openOps(this.d.cf, this.names, this.now)).ops;
+    const ops = this.ops;
+    const db = await ops.resource("d1", this.names.database);
+    if (!db?.id) throw new DeployRefused("no database is recorded for this store: kedge deploy makes it");
+    this.progress = { databaseId: db.id };
+    const files = Object.fromEntries(this.d.lock.entries.map((e) => [e.file, e.sha256]));
+    if (held) {
+      this.opId = held.op_id;
+      this.plan = JSON.parse(held.plan) as Plan;
+      this.progress = { ...(JSON.parse(held.progress) as Progress), databaseId: db.id };
+      if (JSON.stringify((this.plan as unknown as { files: unknown }).files) !== JSON.stringify(files)) {
+        await ops.stop(SCOPE, this.opId);
+        throw new DeployRefused("this checkout's kedge.lock.json isn't the one the held migrate ran with");
+      }
+    } else {
+      this.plan = { commit: this.d.git.head(), adopt: [], vars: {}, files } as unknown as Plan;
+      this.opId = await ops.start(SCOPE, "migrate", this.plan, "start");
+    }
+    try {
+      await this.reconcile();
+      const dir = this.dir(this.opId, "migrations");
+      mkdirSync(dir, { recursive: true });
+      for (const e of this.d.lock.entries) {
+        const bytes = readFileSync(join(this.d.cwd, "migrations", e.file));
+        if (sha256(bytes) !== e.sha256)
+          throw new DeployRefused(`${e.file} doesn't match kedge.lock.json; run kedge doctor`);
+        writeFileSync(join(dir, e.file), bytes);
+      }
+      const applied = await appliedNames(this.d.cf, db.id);
+      const problems = appliedProblems(this.d.lock, applied, await ops.appliedHashes());
+      if (problems.length)
+        throw new DeployRefused(`the store's migrations don't match the lock:\n  ${problems.join("\n  ")}`);
+      const set = new Set(applied);
+      const pending = this.d.lock.entries.filter((e) => !set.has(e.file));
+      if (pending.length === 0) {
+        await ops.finish(SCOPE, this.opId, "nothing pending", [this.plan]);
+        this.log("migrations are up to date");
+        return;
+      }
+      const classified = classify({
+        cwd: this.d.cwd,
+        lock: this.d.lock,
+        pending,
+        manifest: this.d.manifest,
+        plugins: this.d.plugins,
+        text: (f) => readFileSync(join(dir, f), "utf8"),
+      });
+      if (classified.some((c) => c.mode === "cutover"))
+        throw new DeployRefused(
+          "a pending migration is a cutover: use kedge deploy, which runs it behind the maintenance Worker; applying it here would fence the live Worker's writes",
+        );
+      const m = this.d.manifest;
+      this.plan.release = m?.version ?? "workspace";
+      this.plan.upgradesFrom = m?.upgradesFrom ?? null;
+      this.compatible((await this.serving(await ops.deployments())).row);
+      const bookmark = await this.d.cf.bookmark(db.id);
+      this.progress.pending = pending.map((e) => e.file);
+      await this.step("bookmark");
+      this.log(`restore point before migrating: ${bookmark}`);
+      await this.migrate();
+      await ops.finish(SCOPE, this.opId, "migrated", [{ ...this.plan, bookmark }]);
+      this.log(`applied ${pending.length} migration${pending.length === 1 ? "" : "s"}`);
+    } catch (e) {
+      await this.end(e);
+      throw e;
+    } finally {
+      rmSync(this.dir(this.opId), { recursive: true, force: true });
+    }
+  }
+
+  // ---- §6.1: a store deployed before P0.8 ---------------------------------------------------------------
+  async adoptExisting(release: string, texts: (file: string) => string): Promise<void> {
+    const { ops } = await openOps(this.d.cf, this.names, this.now);
+    this.ops = ops;
+    // The operation first, then every read it decides on: read before, a deploy finishing in between
+    // would be recorded over with what it replaced (codex code r12).
+    this.opId = await ops.start(SCOPE, "adopt", { release }, "adopt");
+    try {
+      await this.adoptChecked(release, texts);
+    } catch (e) {
+      if (!(e instanceof LostOwnership)) await this.abandonRecording(`failed: ${(e as Error).name}`).catch(() => {});
+      throw e;
+    }
+  }
+
+  private async adoptChecked(release: string, texts: (file: string) => string): Promise<void> {
+    const ops = this.ops;
+    if ((await ops.deployments()).length)
+      throw new DeployRefused("--adopt-existing is for a store with no recorded deployment");
+    const cf = this.d.cf;
+    const dbId = await cf.findD1(this.names.database);
+    if (!dbId) throw new DeployRefused(`no database named ${this.names.database}`);
+    if (!(await cf.findWorker(this.names.worker))) throw new DeployRefused(`no Worker named ${this.names.worker}`);
+    const deps = await cf.deployments(this.names.worker);
+    const v = deps[0]?.versions;
+    if (v?.length !== 1) throw new DeployRefused("the Worker serves no single version");
+    const applied = await appliedNames(cf, dbId);
+    const problems = appliedProblems(this.d.lock, applied, new Map());
+    if (problems.length)
+      throw new DeployRefused(`the store's migrations aren't a prefix of the lock:\n  ${problems.join("\n  ")}`);
+    // d1_migrations keeps names, not bytes: the live schema is what can be compared (§6.1).
+    const expected = schemaOf(applied.map(texts)).objects.filter((o) => o.type !== "constraint");
+    const live = await cf.queryD1(
+      dbId,
+      "SELECT type, name, tbl_name AS tbl, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' AND name NOT LIKE '_cf_%' AND name <> 'd1_migrations'",
+    );
+    const norm = (s: unknown) =>
+      String(s ?? "")
+        .replace(/\s+/g, " ")
+        .trim();
+    const want = new Map(expected.map((o) => [`${o.type}:${o.name}`, norm(o.sql)]));
+    const have = new Map(live.map((r) => [`${r.type}:${r.name}`, norm(r.sql)]));
+    const diff = [
+      ...[...want].filter(([k, s]) => have.get(k) !== s).map(([k]) => `${k} differs or is missing`),
+      ...[...have.keys()].filter((k) => !want.has(k)).map((k) => `${k} isn't in the lock's migrations`),
+    ];
+    if (diff.length)
+      throw new DeployRefused(
+        `the live schema isn't what the lock's applied migrations make:\n  ${diff.slice(0, 20).join("\n  ")}`,
+      );
+    await this.adoptRun(release, dbId, applied, (v[0] as { version_id: string }).version_id);
+  }
+
+  private async adoptRun(release: string, dbId: string, applied: readonly string[], versionId: string): Promise<void> {
+    const ops = this.ops;
+    const cf = this.d.cf;
+    await ops.recordResource("d1", this.names.database, dbId, "ours");
+    const qid = await cf.findQueue(this.names.queue);
+    if (qid) await ops.recordResource("queue", this.names.queue, qid, "ours");
+    await ops.recordResource("worker", this.names.worker, null, "ours");
+    for (const f of applied)
+      await ops.recordApplied(f, (this.d.lock.entries.find((e) => e.file === f) as LockEntry).sha256);
+    const half: Half = {
+      lockSha: sha256(
+        JSON.stringify(this.d.lock.entries.filter((e) => applied.includes(e.file)).map((e) => [e.file, e.sha256])),
+      ),
+      versionId,
+      release,
+      doMigrations: this.wrangler.migrations ?? [],
+      doStateFormat: null,
+      crons: await cf.schedules(this.names.worker),
+      settings: await cf.settings(this.names.worker),
+      note: `adopted by ${ops.label} as Kedge ${release}: its migration history's bytes can't be proven, only the schema they made`,
+    };
+    const id = await ops.addDeployment(this.opId, "adopted", { ...half, bookmark: await cf.bookmark(dbId) });
+    await ops.completeDeployment(id, half);
+    await ops.finish(SCOPE, this.opId, "adopted", [{ release }]);
+    this.log(`adopted ${this.names.worker} as Kedge ${release}`);
+  }
+}
+
+/**
+ * `kedge generate --supersede` (§6.2): the lock with its applied prefix kept
+ * byte for byte and the proven-unapplied suffix removed, so the ordinary
+ * composer regenerates the suffix from the corrected sources. D1 recorded
+ * nothing of a file that failed, so reusing its name is safe.
+ */
+export function supersededLock(lock: Lock, applied: readonly string[]): { lock: Lock; removed: string[] } {
+  const problems = appliedProblems(lock, applied, new Map());
+  if (problems.length)
+    throw new DeployRefused(`the store's migrations aren't a prefix of the lock:\n  ${problems.join("\n  ")}`);
+  const keep = lock.entries.slice(0, applied.length);
+  const dropped = lock.entries.slice(applied.length);
+  // A plugin's generation is tracked in the lock's plugin state too; regenerating one isn't this path's.
+  const generated = dropped.filter((e) => /^plugin:[^:]+:(generated|entity|install)/.test(e.source));
+  if (generated.length)
+    throw new DeployRefused(
+      `the unapplied suffix holds a plugin's generated migrations (${generated.map((e) => e.file).join(", ")}): fix the plugin's declaration and supersede with a new generation instead`,
+    );
+  return { lock: { ...lock, entries: keep }, removed: dropped.map((e) => e.file) };
+}
+
+/** The admin build an assets directory holds, from the build.json its build wrote (p0.9 §2.4); null when none. */
+export function adminBuildIn(assetsDir: string): string | null {
+  const file = join(assetsDir, "app", "build.json");
+  return existsSync(file) ? ((JSON.parse(readFileSync(file, "utf8")) as { build?: string }).build ?? null) : null;
+}
+
+/**
+ * Stages the admin's assets (p0.9 §3.3): a copy of the configured directory,
+ * and the build its `app/build.json` names, defined into the Worker's code as
+ * `KEDGE_ADMIN_BUILD`. Null when the store serves no admin.
+ */
+export function stageAssets(
+  cwd: string,
+  config: WranglerJson,
+  to: string,
+): { build: string | null; define: Record<string, string> } | null {
+  const a = config.assets as { directory?: string } | undefined;
+  if (!a?.directory) return null;
+  const from = resolve(cwd, a.directory);
+  if (!existsSync(from))
+    throw new DeployRefused(`wrangler.jsonc's assets directory ${a.directory} doesn't exist: run pnpm install`);
+  rmSync(to, { recursive: true, force: true });
+  cpSync(from, to, { recursive: true, dereference: true });
+  const build = adminBuildIn(to);
+  return { build, define: build ? { KEDGE_ADMIN_BUILD: JSON.stringify(build) } : {} };
+}