@intentius/chant 0.79.0 → 0.81.0

package/src/workspace/lineage-migrations.ts

@@ -0,0 +1,343 @@
+/**
+ * Template migrations (#2550, D9).
+ *
+ * A template ships its migrations beside its files, under
+ * `.chant/migrations/`, one JSON file each. The metadata is data: an id, the
+ * template versions it applies `from` (a template id and a version range), the
+ * version it brings the scope `to`, a body, and a post-condition. The body is
+ * either a closed list of declarative steps or a module, marked
+ * `"type": "code"`, which runs only when the caller allows code.
+ *
+ * `chant workspace upgrade` plans a chain from the scope's version to the
+ * target: every migration whose `to` lies in between, ordered by `to`. Each
+ * must accept the version the scope has reached when its turn comes. When one
+ * does not, a migration is missing from the chain, and the upgrade is refused
+ * rather than applied in part.
+ *
+ * Migrations run inside the upgrade's staging worktree, before the per-file
+ * merge. A `move` or `delete` updates the lineage too, so the merge that
+ * follows compares the right merge base with the new version.
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, posix } from "node:path";
+import { pathToFileURL } from "node:url";
+import { z } from "zod";
+import { LockError, type Lineage } from "./lineage-lock";
+import { compareVersions, formatVersion, parseVersion, satisfies, validateRange, VersionRangeError, type Version } from "./lineage-version";
+
+/** Where a template keeps its migrations, relative to the template's directory. */
+export const MIGRATIONS_DIR = ".chant/migrations";
+
+const RelPath = z
+  .string()
+  .min(1)
+  .refine((p) => {
+    const n = posix.normalize(p);
+    return !n.startsWith("/") && n !== ".." && !n.startsWith("../") && !p.includes("\\");
+  }, "must be a relative path inside the scope");
+
+/** The declarative steps. Closed: a step chant does not know is refused. */
+const StepSchema = z.discriminatedUnion("op", [
+  /** Move a file. The lineage entry moves with it, merge base included. */
+  z.strictObject({ op: z.literal("move"), from: RelPath, to: RelPath }),
+  /** Delete a file and drop it from the lineage. */
+  z.strictObject({ op: z.literal("delete"), path: RelPath }),
+  /** Replace every occurrence of a literal string in a file. */
+  z.strictObject({ op: z.literal("replace"), path: RelPath, find: z.string().min(1), with: z.string() }),
+  /** Set a value in a JSON file at a JSON Pointer, creating objects on the way. */
+  z.strictObject({ op: z.literal("json-set"), path: RelPath, pointer: z.string().startsWith("/"), value: z.unknown() }),
+  /** Remove a key from a JSON file at a JSON Pointer. */
+  z.strictObject({ op: z.literal("json-delete"), path: RelPath, pointer: z.string().startsWith("/") }),
+]);
+export type MigrationStep = z.infer<typeof StepSchema>;
+
+/** What must hold after a migration ran. Every check must pass. */
+const PostSchema = z.discriminatedUnion("check", [
+  z.strictObject({ check: z.literal("exists"), path: RelPath }),
+  z.strictObject({ check: z.literal("absent"), path: RelPath }),
+  z.strictObject({ check: z.literal("contains"), path: RelPath, text: z.string().min(1) }),
+  z.strictObject({ check: z.literal("not-contains"), path: RelPath, text: z.string().min(1) }),
+]);
+export type MigrationCheck = z.infer<typeof PostSchema>;
+
+const Range = z.string().min(1).superRefine((r, ctx) => {
+  try {
+    validateRange(r);
+  } catch (err) {
+    ctx.addIssue({ code: "custom", message: err instanceof VersionRangeError ? err.message : String(err) });
+  }
+});
+
+const MigrationSchema = z.strictObject({
+  $schema: z.string().optional(),
+  /** Unique within the template. Recorded in the lock once applied. */
+  id: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/, "letters, digits, '.', '_' and '-'"),
+  description: z.string().optional(),
+  from: z.strictObject({
+    /** The template id the migration applies to. Omitted, it applies to the template it ships in. */
+    template: z.string().min(1).optional(),
+    /** The versions it can be applied to. */
+    versions: Range,
+  }),
+  /** The version the scope is at once the migration ran. */
+  to: z.string().refine((v) => parseVersion(v) !== null, "must be a version, such as 2.0.0"),
+  body: z.discriminatedUnion("type", [
+    z.strictObject({ type: z.literal("declarative"), steps: z.array(StepSchema).min(1) }),
+    /**
+     * Code: a module in the migrations directory whose default export is
+     * `async ({ dir }) => void`, run with the scope directory as `dir`.
+     */
+    z.strictObject({ type: z.literal("code"), module: RelPath }),
+  ]),
+  post: z.array(PostSchema).default([]),
+});
+export type Migration = z.infer<typeof MigrationSchema>;
+
+export class MigrationError extends LockError {
+  override name = "MigrationError";
+}
+
+export interface LoadedMigration {
+  migration: Migration;
+  /** The file it was read from, relative to the template directory. */
+  file: string;
+}
+
+/**
+ * Read the migrations out of a template's files (relative path to bytes).
+ * Returns them and the files that remain once `.chant/migrations/` is taken
+ * out: migrations are the template's, never copied into a project.
+ */
+export function splitMigrations(files: Map<string, Buffer>): { migrations: LoadedMigration[]; modules: Map<string, Buffer>; files: Map<string, Buffer> } {
+  const rest = new Map<string, Buffer>();
+  const migrations: LoadedMigration[] = [];
+  const modules = new Map<string, Buffer>();
+  const prefix = `${MIGRATIONS_DIR}/`;
+  for (const [path, data] of files) {
+    if (!path.startsWith(prefix)) {
+      rest.set(path, data);
+      continue;
+    }
+    const rel = path.slice(prefix.length);
+    if (!rel.endsWith(".json")) {
+      modules.set(rel, data);
+      continue;
+    }
+    let raw: unknown;
+    try {
+      raw = JSON.parse(data.toString("utf-8"));
+    } catch (err) {
+      throw new MigrationError(`${path} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const parsed = MigrationSchema.safeParse(raw);
+    if (!parsed.success) {
+      throw new MigrationError(
+        `invalid migration ${path}: ${parsed.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("; ")}`,
+      );
+    }
+    migrations.push({ migration: parsed.data, file: path });
+  }
+  const ids = new Set<string>();
+  for (const { migration, file } of migrations) {
+    if (ids.has(migration.id)) throw new MigrationError(`migration id "${migration.id}" is used twice (${file})`);
+    ids.add(migration.id);
+    if (migration.body.type === "code" && !modules.has(migration.body.module)) {
+      throw new MigrationError(`${file}: its code module ${MIGRATIONS_DIR}/${migration.body.module} is not in the template`);
+    }
+  }
+  return { migrations, modules, files: rest };
+}
+
+// ── Planning ─────────────────────────────────────────────────────────────────
+
+export interface MigrationPlan {
+  /** In the order they run. */
+  chain: LoadedMigration[];
+  from: Version | null;
+  to: Version | null;
+}
+
+/**
+ * The migrations that take `lineage` from its version to `targetRef`, in order.
+ *
+ * Refused, with a {@link MigrationError}:
+ * - a target below the scope's version;
+ * - a pending migration when either end of the upgrade is not a version, so
+ *   no chain can be computed;
+ * - a gap: a migration in range whose `from` does not accept the version the
+ *   scope has reached by then.
+ */
+export function planMigrations(lineage: Lineage, targetRef: string | undefined, available: LoadedMigration[]): MigrationPlan {
+  const from = parseVersion(lineage.ref);
+  const to = parseVersion(targetRef);
+  if (from && to && compareVersions(to, from) < 0) {
+    throw new MigrationError(`the target ${targetRef} (${formatVersion(to)}) is older than the scope's ${lineage.ref} (${formatVersion(from)}); an upgrade only goes forward`);
+  }
+  const applied = new Set(lineage.migrations);
+  const mine = available.filter(
+    ({ migration: m }) => (m.from.template === undefined || m.from.template === lineage.template) && !applied.has(m.id),
+  );
+  if (mine.length === 0) return { chain: [], from, to };
+
+  if (!from || !to) {
+    const which = !from ? `the scope's ref ${lineage.ref ?? "(none)"}` : `the target ${targetRef ?? "(none)"}`;
+    throw new MigrationError(
+      `the template has ${mine.length} migration(s) not yet applied (${mine.map((m) => m.migration.id).join(", ")}), but ${which} is not a version, so no chain can be planned. Pin tagged versions, such as v1.2.0.`,
+    );
+  }
+
+  const inRange = mine
+    .map((m) => ({ ...m, target: parseVersion(m.migration.to)! }))
+    .filter((m) => compareVersions(m.target, from) > 0 && compareVersions(m.target, to) <= 0)
+    .sort((a, b) => compareVersions(a.target, b.target) || a.migration.id.localeCompare(b.migration.id));
+
+  const chain: LoadedMigration[] = [];
+  let at = from;
+  let i = 0;
+  while (i < inRange.length) {
+    const step = inRange[i].target;
+    const group = inRange.filter((m) => compareVersions(m.target, step) === 0);
+    for (const m of group) {
+      if (!satisfies(at, m.migration.from.versions)) {
+        throw new MigrationError(
+          `gap in the migration chain: ${m.migration.id} (${m.file}) upgrades ${m.migration.from.versions} to ${m.migration.to}, but the scope is at ${formatVersion(at)} when it would run. A migration that brings ${formatVersion(at)} into ${m.migration.from.versions} is missing, so the upgrade is refused.`,
+        );
+      }
+      chain.push({ migration: m.migration, file: m.file });
+    }
+    at = step;
+    i += group.length;
+  }
+  return { chain, from, to };
+}
+
+// ── Running ──────────────────────────────────────────────────────────────────
+
+export interface RunMigrationOptions {
+  /** The scope directory in the staging worktree. */
+  dir: string;
+  lineage: Lineage;
+  /** Code modules from the template, relative to its migrations directory. */
+  modules: Map<string, Buffer>;
+  /** Run `"type": "code"` bodies. Without it, a chain holding one is refused. */
+  allowCode: boolean;
+  /** Where a code module is written before it is imported. */
+  scratch: string;
+  /** Told of each file a declarative step moves, so a caller keyed by path (the merge base) can follow. */
+  onMove?: (from: string, to: string) => void;
+}
+
+/** Refuse a chain holding code when code is not allowed, before anything runs. */
+export function assertCodeAllowed(chain: LoadedMigration[], allowCode: boolean): void {
+  const code = chain.filter((m) => m.migration.body.type === "code");
+  if (code.length > 0 && !allowCode) {
+    throw new MigrationError(
+      `the chain includes ${code.length} code migration(s) (${code.map((m) => m.migration.id).join(", ")}), which run the template's own code. Read them, then pass --allow-code to run them.`,
+    );
+  }
+}
+
+/** Run one migration in the worktree, then its post-condition. Updates `lineage`. */
+export async function runMigration(m: LoadedMigration, opts: RunMigrationOptions): Promise<void> {
+  const { migration } = m;
+  const body = migration.body;
+  if (body.type === "code") {
+    if (!opts.allowCode) throw new MigrationError(`${migration.id} is a code migration; pass --allow-code to run it`);
+    const file = join(opts.scratch, "migrations", body.module);
+    mkdirSync(dirname(file), { recursive: true });
+    for (const [rel, data] of opts.modules) {
+      const abs = join(opts.scratch, "migrations", rel);
+      mkdirSync(dirname(abs), { recursive: true });
+      writeFileSync(abs, data);
+    }
+    const mod = (await import(pathToFileURL(file).href)) as { default?: unknown };
+    if (typeof mod.default !== "function") throw new MigrationError(`${migration.id}: ${body.module} has no default export function`);
+    await (mod.default as (ctx: { dir: string }) => unknown)({ dir: opts.dir });
+  } else {
+    for (const step of body.steps) {
+      applyStep(step, opts.dir, opts.lineage, migration.id);
+      if (step.op === "move") opts.onMove?.(step.from, step.to);
+    }
+  }
+  const failed = migration.post.filter((c) => !holds(c, opts.dir));
+  if (failed.length > 0) {
+    throw new MigrationError(
+      `migration ${migration.id} ran, but its post-condition does not hold: ${failed.map(describeCheck).join("; ")}. The upgrade is refused.`,
+    );
+  }
+  opts.lineage.migrations.push(migration.id);
+}
+
+function applyStep(step: MigrationStep, dir: string, lineage: Lineage, id: string): void {
+  const abs = (p: string) => join(dir, p);
+  const need = (p: string) => {
+    if (!existsSync(abs(p))) throw new MigrationError(`migration ${id}: ${step.op} needs ${p}, which is not in the scope`);
+  };
+  switch (step.op) {
+    case "move": {
+      need(step.from);
+      if (existsSync(abs(step.to))) throw new MigrationError(`migration ${id}: cannot move ${step.from} to ${step.to}, which exists`);
+      mkdirSync(dirname(abs(step.to)), { recursive: true });
+      renameSync(abs(step.from), abs(step.to));
+      const entry = lineage.files[step.from];
+      if (entry) {
+        delete lineage.files[step.from];
+        lineage.files[step.to] = entry;
+      }
+      return;
+    }
+    case "delete":
+      if (existsSync(abs(step.path))) rmSync(abs(step.path));
+      delete lineage.files[step.path];
+      return;
+    case "replace": {
+      need(step.path);
+      const text = readFileSync(abs(step.path), "utf-8");
+      writeFileSync(abs(step.path), text.split(step.find).join(step.with));
+      return;
+    }
+    case "json-set":
+    case "json-delete": {
+      need(step.path);
+      let doc: unknown;
+      try {
+        doc = JSON.parse(readFileSync(abs(step.path), "utf-8"));
+      } catch {
+        throw new MigrationError(`migration ${id}: ${step.path} is not valid JSON`);
+      }
+      const keys = step.pointer.slice(1).split("/").map((k) => k.replace(/~1/g, "/").replace(/~0/g, "~"));
+      const last = keys.pop()!;
+      let node = doc as Record<string, unknown>;
+      for (const k of keys) {
+        if (typeof node[k] !== "object" || node[k] === null) {
+          if (step.op === "json-delete") return;
+          node[k] = {};
+        }
+        node = node[k] as Record<string, unknown>;
+      }
+      if (step.op === "json-set") node[last] = step.value;
+      else delete node[last];
+      writeFileSync(abs(step.path), JSON.stringify(doc, null, 2) + "\n");
+      return;
+    }
+  }
+}
+
+function holds(c: MigrationCheck, dir: string): boolean {
+  const abs = join(dir, c.path);
+  switch (c.check) {
+    case "exists":
+      return existsSync(abs);
+    case "absent":
+      return !existsSync(abs);
+    case "contains":
+      return existsSync(abs) && readFileSync(abs, "utf-8").includes(c.text);
+    case "not-contains":
+      return !existsSync(abs) || !readFileSync(abs, "utf-8").includes(c.text);
+  }
+}
+
+function describeCheck(c: MigrationCheck): string {
+  return "text" in c ? `${c.check} ${JSON.stringify(c.text)} in ${c.path}` : `${c.path} ${c.check}`;
+}

package/src/workspace/lineage-update.ts

@@ -0,0 +1,160 @@
+/**
+ * Bring one lineage scope to a new version of its source, file by file,
+ * without deleting the project's edits (#2540, ws-038).
+ *
+ * For each path, three hashes decide what happens: the merge base recorded in
+ * the lock, the source's new version, and the file in the tree.
+ *
+ * | tree            | source                   | result                                  |
+ * |-----------------|--------------------------|-----------------------------------------|
+ * | equals base     | anything                 | replaced (or removed) by the source     |
+ * | equals source   | anything                 | kept; base moves to the source          |
+ * | edited          | unchanged from base      | kept; base stays                        |
+ * | edited          | changed, merges cleanly  | merged; base moves to the source (*)    |
+ * | edited          | changed or removed       | kept; a manual step                     |
+ * | deleted         | unchanged from base      | stays deleted                           |
+ * | deleted         | changed                  | stays deleted; a manual step            |
+ * | untracked file  | adds the same path       | kept; a manual step                     |
+ *
+ * The table is for `owned` files. A `seed` file is never touched again, and a
+ * `generated` file is left for its command to rebuild (D9, D14). Files in the
+ * scope directory that the lineage does not list are never touched. This is
+ * the per-file rule of ws-005.
+ *
+ * (*) Only when the caller passes {@link MergeOptions}: the merge base's
+ * content, rebuilt by `chant workspace upgrade` (#2550), and a merge function.
+ * A file merges only when every hunk is clean; otherwise it is kept as it was
+ * and becomes one manual step. `chant vendor pull` passes no base, since a
+ * vendor source keeps no history to rebuild it from, so every conflicting
+ * path there is a manual step.
+ */
+
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { contentDigest, declaredFilesAt, defaultFileClass, fileHash, type Lineage, type ManualStep } from "./lineage-lock";
+
+export interface UpdateResult {
+  written: string[];
+  /** Edited files that took the source's changes through a clean three-way merge. */
+  merged: string[];
+  /** `seed` files, which an update never touches, and `generated` files, which their command rebuilds. */
+  skipped: Array<{ path: string; class: "seed" | "generated"; command?: string }>;
+  removed: string[];
+  kept: string[];
+  manualSteps: ManualStep[];
+}
+
+/** The three-way merge, for `chant workspace upgrade`. */
+export interface MergeOptions {
+  /** The merge base's content, by path. A path missing here cannot be merged. */
+  base: Map<string, Buffer>;
+  /** Merged bytes, or null when a hunk conflicts. */
+  merge: (base: Buffer, ours: Buffer, theirs: Buffer) => Buffer | null;
+}
+
+/**
+ * Apply `upstream` (relative path to bytes) to the scope directory `dir`,
+ * updating `lineage` in place: its files, digest and manual steps. Open manual
+ * steps for paths this update touches again are replaced, others are kept.
+ */
+export function applyUpstream(dir: string, lineage: Lineage, upstream: Map<string, Buffer>, merging?: MergeOptions): UpdateResult {
+  const result: UpdateResult = { written: [], merged: [], skipped: [], removed: [], kept: [], manualSteps: [] };
+  const steps = new Map(lineage.manualSteps.map((s) => [s.path, s]));
+  const paths = new Set([...Object.keys(lineage.files), ...upstream.keys()]);
+  // The declaration's generated list is read again on every update, so a
+  // file the member lists after the lock was written is rebuilt, not merged,
+  // and a file it marks hand-written is merged like any other (#2541).
+  const declared = declaredFilesAt(dir);
+
+  for (const path of [...paths].sort()) {
+    const abs = join(dir, path);
+    const recorded = lineage.files[path];
+    if (recorded && declared.has(path)) lineage.files[path] = { ...defaultFileClass(path, declared), sha256: recorded.sha256 };
+    const entry = lineage.files[path];
+    if (entry && entry.class !== "owned") {
+      // D9: a seed is written once, and a generated file is rebuilt by its
+      // command rather than merged. Neither is written here.
+      result.skipped.push({ path, class: entry.class, ...(entry.command ? { command: entry.command } : {}) });
+      continue;
+    }
+    const base = lineage.files[path]?.sha256;
+    const incoming = upstream.get(path);
+    const theirs = incoming ? fileHash(incoming) : undefined;
+    const local = existsSync(abs) ? fileHash(readFileSync(abs)) : undefined;
+    const step = (reason: ManualStep["reason"]): void => {
+      const s: ManualStep = { path, reason, upstream: theirs ?? null };
+      steps.set(path, s);
+      result.manualSteps.push(s);
+    };
+    const record = (sha: string): void => {
+      lineage.files[path] = { ...(lineage.files[path] ?? defaultFileClass(path, declared)), sha256: sha };
+      steps.delete(path);
+    };
+
+    if (theirs === undefined) {
+      // The source no longer has the file.
+      if (local === undefined || local === base) {
+        if (local !== undefined) {
+          rmSync(abs);
+          result.removed.push(path);
+        }
+        delete lineage.files[path];
+        steps.delete(path);
+      } else {
+        step("removed-upstream");
+        result.kept.push(path);
+      }
+      continue;
+    }
+
+    if (local === theirs) {
+      record(theirs);
+      continue;
+    }
+    if (local === undefined) {
+      if (base === undefined) {
+        write(abs, incoming!);
+        result.written.push(path);
+        record(theirs);
+      } else if (base === theirs) {
+        steps.delete(path);
+      } else {
+        step("deleted-locally");
+      }
+      continue;
+    }
+    if (base !== undefined && local === base) {
+      write(abs, incoming!);
+      result.written.push(path);
+      record(theirs);
+      continue;
+    }
+    // The tree has its own version of the file.
+    if (base !== undefined && base === theirs) {
+      result.kept.push(path);
+      steps.delete(path);
+      continue;
+    }
+    const baseData = merging?.base.get(path);
+    if (merging && baseData && fileHash(baseData) === base) {
+      const merged = merging.merge(baseData, readFileSync(abs), incoming!);
+      if (merged) {
+        writeFileSync(abs, merged);
+        result.merged.push(path);
+        record(theirs);
+        continue;
+      }
+    }
+    result.kept.push(path);
+    step(base === undefined ? "exists-locally" : "changed-locally");
+  }
+
+  lineage.manualSteps = [...steps.values()].sort((a, b) => a.path.localeCompare(b.path));
+  lineage.address = { ...(lineage.address ?? {}), digest: contentDigest(upstream) };
+  return result;
+}
+
+function write(abs: string, data: Buffer): void {
+  mkdirSync(dirname(abs), { recursive: true });
+  writeFileSync(abs, data);
+}

package/src/workspace/lineage-upgrade-cli.ts

@@ -0,0 +1,151 @@
+/**
+ * `chant workspace upgrade [<scope>] [--to <ref>] [--allow-code] [--dry-run]
+ * [--output <file>] [--json]` (#2550).
+ *
+ * Stages the upgrade in a worktree (see ./lineage-upgrade.ts), then decides
+ * its gate. The gate is `workspace-upgrade/<scope>` on the gate ledger, and it
+ * binds the digest of the patch the staging produced. The first run records
+ * the pending fact and exits 3, the code `chant run` gives a gated run. After
+ * `chant approve workspace-upgrade <scope>`, the same command stages the same
+ * patch, finds the approval for its digest, and applies the patch to the tree.
+ * A patch that differs from the approved one needs a new approval.
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { formatError, formatInfo, formatSuccess, formatWarning } from "../cli/format";
+import type { CommandContext } from "../cli/registry";
+import { approveCommand, describeGateMismatch, evaluateGate, gitGateLedgerPort, type GateLedgerPort } from "../op/gate";
+import { WORKSPACE_UPGRADE_GATE_OP } from "../op/gate-name";
+import { LockError } from "./lineage-lock";
+import { applyStagedUpgrade, describeStaged, stageUpgrade, type ChantRunner, type StagedUpgrade } from "./lineage-upgrade";
+
+const USAGE = "chant workspace upgrade [<scope>] [--to <ref>] [--allow-code] [--dry-run] [--output <patch file>] [--json]";
+
+/** The exit code of a gated upgrade: the same as `chant run`'s gated run. */
+export const UPGRADE_GATED_EXIT = 3;
+
+export interface UpgradeCommandOptions {
+  root: string;
+  scope?: string;
+  to?: string;
+  allowCode?: boolean;
+  dryRun?: boolean;
+  output?: string;
+  json?: boolean;
+  /** For tests. */
+  runChant?: ChantRunner;
+  ledger?: GateLedgerPort;
+  now?: string;
+}
+
+export type UpgradeOutcome = "up-to-date" | "checks-failed" | "dry-run" | "gated" | "applied";
+
+export interface UpgradeCommandResult {
+  outcome: UpgradeOutcome;
+  exitCode: number;
+  staged?: Omit<StagedUpgrade, "dispose" | "patch" | "worktree" | "worktreeProject" | "lock">;
+}
+
+/** The command, with its output. Returns the exit code and what happened. */
+export async function upgradeCommand(opts: UpgradeCommandOptions): Promise<UpgradeCommandResult> {
+  const staged = await stageUpgrade({
+    root: opts.root,
+    scope: opts.scope,
+    to: opts.to,
+    allowCode: opts.allowCode,
+    runChant: opts.runChant,
+  });
+  try {
+    const { dispose: _d, patch: _p, worktree: _w, worktreeProject: _wp, lock: _l, ...view } = staged;
+    const report = (outcome: UpgradeOutcome, exitCode: number, extra: Record<string, unknown> = {}): UpgradeCommandResult => {
+      if (opts.json) console.log(JSON.stringify({ outcome, ...view, ...extra }, null, 2));
+      return { outcome, exitCode, staged: view };
+    };
+    if (!opts.json) console.log(describeStaged(staged).join("\n"));
+
+    if (!opts.json && !staged.lock.tracked) {
+      console.error(
+        formatWarning({
+          message: `${staged.lock.path} is not tracked by git (a .gitignore covers it), so it is written beside the patch rather than in it. Commit it with \`git add -f\` so the lineage travels with the project.`,
+        }),
+      );
+    }
+    if (!staged.changed) {
+      if (!opts.json) console.error(formatSuccess(`scope "${staged.scope}" is already at ${staged.to ?? "its source"}; nothing to upgrade`));
+      return report("up-to-date", 0);
+    }
+    if (opts.output) writeFileSync(resolve(opts.output), staged.patch);
+    if (!staged.checksOk) {
+      if (!opts.json) {
+        for (const c of staged.checks.filter((c) => c.status === "failed")) {
+          console.error(formatError({ message: `${c.name} failed in the staging worktree`, hint: c.detail }));
+        }
+        console.error(formatError({ message: "the upgrade was not gated: its checks must pass first. The tree is unchanged." }));
+      }
+      return report("checks-failed", 1);
+    }
+    if (opts.dryRun) {
+      if (!opts.json) console.error(formatInfo("--dry-run: staged and checked; no gate recorded, the tree is unchanged"));
+      return report("dry-run", 0);
+    }
+
+    const gate = staged.scope;
+    const check = await evaluateGate(opts.ledger ?? gitGateLedgerPort({ cwd: staged.repo }), {
+      op: WORKSPACE_UPGRADE_GATE_OP,
+      gate,
+      description: `upgrade ${staged.template} ${staged.from ?? ""} -> ${staged.to ?? ""} in scope ${staged.scope}`.replace(/\s+/g, " "),
+      planDigest: staged.digest,
+      ...(staged.governance ? { approval: staged.governance.approval } : {}),
+      ...(opts.now ? { now: opts.now } : {}),
+    });
+    if (!check.satisfied) {
+      if (!opts.json) {
+        if (check.mismatch) console.error(formatWarning({ message: describeGateMismatch(WORKSPACE_UPGRADE_GATE_OP, gate, check.mismatch) }));
+        if (check.pushWarning) console.error(formatWarning({ message: check.pushWarning }));
+        if (check.quorum) console.error(formatInfo(`approvals so far: ${check.quorum.approvers.length} of ${check.quorum.need}`));
+        console.error(
+          formatInfo(
+            `Gated: the patch ${staged.digest} waits for approval. Review it (--output <file> writes it), then run \`${approveCommand(WORKSPACE_UPGRADE_GATE_OP, gate)}\` and repeat this command to apply it.`,
+          ),
+        );
+      }
+      return report("gated", UPGRADE_GATED_EXIT, { pending: check.pending });
+    }
+
+    applyStagedUpgrade(staged);
+    if (!opts.json) {
+      console.error(formatSuccess(`applied the approved upgrade of "${staged.scope}" (${staged.digest}), approved by ${check.resolution.resolvedBy}. Review and commit it.`));
+      if (staged.manualSteps.length > 0) {
+        console.error(formatInfo(`${staged.manualSteps.length} manual step(s) are open; \`chant workspace check\` fails until each is merged and resolved.`));
+      }
+    }
+    return report("applied", 0, { approvedBy: check.resolution.resolvedBy });
+  } finally {
+    staged.dispose();
+  }
+}
+
+export async function runWorkspaceUpgrade(ctx: CommandContext): Promise<number> {
+  const { args } = ctx;
+  if (args.extraPositional2) {
+    console.error(formatError({ message: `unexpected argument: ${args.extraPositional2}`, hint: USAGE }));
+    return 1;
+  }
+  try {
+    const result = await upgradeCommand({
+      root: process.cwd(),
+      scope: args.extraPositional,
+      to: args.migrateTo,
+      allowCode: args.allowCode,
+      dryRun: args.dryRun,
+      output: args.output,
+      json: args.json,
+    });
+    return result.exitCode;
+  } catch (err) {
+    if (!(err instanceof LockError)) throw err;
+    console.error(formatError({ message: err.message, hint: USAGE }));
+    return 1;
+  }
+}