@@ -0,0 +1,161 @@
+// server/typescript/packages/cli/src/commands/upgrade.ts
+//
+// `meta upgrade` — rewrite retired vocabulary in this project's metadata.
+//
+// DELIBERATELY NOT `meta migrate`. That command owns DATABASE SCHEMA (ADR-0015) and an
+// adopter reading `migrate` expects DDL. Overloading it with a metadata rewrite would make
+// the most destructive command in the toolchain ambiguous about what it touches.
+//
+// IT DOES NOT LOAD THE METADATA, and cannot. Once vocabulary is deregistered, metadata
+// carrying it fails the load — which is exactly the state this command exists to repair. So
+// it resolves the file SET through `resolveCollection` (the single authority on where
+// metadata lives) and hands each file's RAW TEXT to the rewriter. See
+// `metadata/src/vocabulary-rewrite.ts` for why that is the only workable shape.
+//
+// DRY-RUN BY DEFAULT, per this repo's convention for anything that edits committed files.
+// `--apply` writes. Refusals exit NON-ZERO even when every mechanical change succeeded, so
+// CI cannot mistake a partial upgrade for a finished one.
+
+import { readFile, writeFile } from "node:fs/promises";
+import { relative } from "node:path";
+import { resolveCollection } from "@metaobjectsdev/sdk";
+import { rewriteDocument, type RewriteResult } from "@metaobjectsdev/metadata";
+import { log } from "../lib/log.js";
+
+interface UpgradeFlags {
+  apply: boolean;
+  maxVersion?: string;
+  projectRoot?: string;
+}
+
+function parseArgs(argv: string[]): UpgradeFlags {
+  const flags: UpgradeFlags = { apply: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] as string;
+    if (a === "--apply") flags.apply = true;
+    else if (a === "--to") {
+      const v = argv[++i];
+      if (v === undefined) throw new Error("--to needs a version");
+      flags.maxVersion = v;
+    } else if (a.startsWith("--to=")) flags.maxVersion = a.slice("--to=".length);
+    else if (a === "--help" || a === "-h") throw new Error("__help__");
+    else if (!a.startsWith("-")) flags.projectRoot = a;
+    else throw new Error(`unknown option: ${a}`);
+  }
+  return flags;
+}
+
+/**
+ * The node type a document's keys belong to.
+ *
+ * Retirements are TYPE-SCOPED — `@unique` is retired on `identity.secondary` and live on a
+ * field — so the rewriter needs a scope per occurrence, not per file. A metadata file holds
+ * many types, so we run the rewriter once per type key present in the text. Cheap, and it
+ * keeps the scoping decision in one place (the map) rather than smeared across a parser we
+ * deliberately do not have.
+ */
+function typeKeysIn(text: string): string[] {
+  const keys = new Set<string>();
+  const re = /"([a-z]+)\.([A-Za-z*]+)"\s*:/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text)) !== null) keys.add(`${m[1]}.${m[2]}`);
+  return [...keys];
+}
+
+/** Run every type scope present in the document, threading the text through each pass. */
+function rewriteAllScopes(text: string, maxVersion: string | undefined): RewriteResult {
+  const changes: RewriteResult["changes"][number][] = [];
+  const refusals: RewriteResult["refusals"][number][] = [];
+  let current = text;
+  for (const typeKeyHint of typeKeysIn(text)) {
+    const r = rewriteDocument(current, {
+      typeKeyHint,
+      ...(maxVersion !== undefined ? { maxVersion } : {}),
+    });
+    current = r.text;
+    changes.push(...r.changes);
+    refusals.push(...r.refusals);
+  }
+  return { text: current, changes, refusals };
+}
+
+export async function upgradeCommand(args: string[], cwd: string): Promise<number> {
+  let flags: UpgradeFlags;
+  try {
+    flags = parseArgs(args);
+  } catch (err) {
+    if ((err as Error).message === "__help__") {
+      log.info(
+        "meta upgrade [<project>] [--to <version>] [--apply]\n\n" +
+          "  Rewrites retired metadata vocabulary. Previews by default; --apply writes.\n" +
+          "  Retirements needing a human decision are REFUSED and listed with their guide.",
+      );
+      return 0;
+    }
+    log.error((err as Error).message);
+    return 2;
+  }
+
+  const projectRoot = flags.projectRoot ?? cwd;
+
+  let files: readonly string[];
+  try {
+    files = (await resolveCollection(projectRoot)).files;
+  } catch (err) {
+    log.error((err as Error).message);
+    return 1;
+  }
+
+  let totalChanges = 0;
+  let totalRefusals = 0;
+  let filesChanged = 0;
+
+  for (const file of files) {
+    const before = await readFile(file, "utf8");
+    const r = rewriteAllScopes(before, flags.maxVersion);
+    if (r.changes.length === 0 && r.refusals.length === 0) continue;
+
+    const rel = relative(projectRoot, file);
+    log.info(`\n${rel}`);
+    for (const c of r.changes) log.info(`  ${c.line}: @${c.from} → ${c.to}`);
+    for (const f of r.refusals) {
+      log.warn(
+        `  ${f.line}: @${f.attr}${f.value !== undefined ? `: ${f.value}` : ""} — needs a decision. ` +
+          `Retired in ${f.since}. ${f.migration !== undefined ? `See ${f.migration}` : f.why}`,
+      );
+    }
+
+    totalChanges += r.changes.length;
+    totalRefusals += r.refusals.length;
+    if (r.changes.length > 0) {
+      filesChanged++;
+      if (flags.apply) await writeFile(file, r.text, "utf8");
+    }
+  }
+
+  log.info("");
+  if (totalChanges === 0 && totalRefusals === 0) {
+    log.info("meta upgrade — no retired vocabulary found.");
+    return 0;
+  }
+
+  if (flags.apply) {
+    log.info(`meta upgrade — rewrote ${totalChanges} declaration(s) across ${filesChanged} file(s).`);
+  } else {
+    log.info(
+      `meta upgrade — ${totalChanges} declaration(s) in ${filesChanged} file(s) can be rewritten. ` +
+        `Re-run with --apply to write.`,
+    );
+  }
+
+  // Non-zero while ANY refusal stands, applied or not. A partial upgrade that exited 0 would
+  // let CI record the migration as done while metadata still fails to load.
+  if (totalRefusals > 0) {
+    log.error(
+      `${totalRefusals} declaration(s) need a human decision and were left untouched — ` +
+        `see the guides listed above.`,
+    );
+    return 1;
+  }
+  return 0;
+}
@@ -23,6 +23,7 @@ COMMANDS:
   export                Flatten loaded metadata to one canonical JSON artifact
   docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
+  upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
@@ -377,6 +378,10 @@ export async function run(argv: string[]): Promise<number> {
       const { verifyCommand } = await import("./commands/verify.js");
       return verifyCommand(rest, cwd);
     }
+    case "upgrade": {
+      const { upgradeCommand } = await import("./commands/upgrade.js");
+      return upgradeCommand(rest, cwd);
+    }
     case "prompt-snapshot": {
       const { promptSnapshotCommand } = await import("./commands/prompt-snapshot.js");
       return promptSnapshotCommand(rest, cwd);
 
@@ -16,6 +16,7 @@ COMMANDS:
   export                Flatten loaded metadata to one canonical JSON artifact
   docs <metadata> --out <dir>  Generate neutral metadata documentation (entity + template pages; --site for HTML site)
   verify                Drift gate — subverbs: --templates / --db / --codegen (bare = --templates)
+  upgrade               Rewrite retired metadata vocabulary (previews; --apply writes)
   prompt-snapshot       Snapshot rendered template.* output; --check gates drift
   migrate               Diff metadata vs live DB; emit migration SQL files
   --version, -v         Print version
 
@@ -0,0 +1,118 @@
+// `meta upgrade` end-to-end, against real files on disk.
+//
+// The unit tests prove the rewriter transforms text. These prove the COMMAND does the right
+// thing to a project: previews without writing, writes only under --apply, and — the one
+// that matters for CI — exits NON-ZERO while any refusal stands, so a partial upgrade
+// cannot be recorded as a finished one.
+
+import { describe, test, expect, afterAll } from "bun:test";
+import { mkdtemp, rm, mkdir, writeFile, readFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { upgradeCommand } from "../src/commands/upgrade.js";
+
+const dirs: string[] = [];
+afterAll(async () => {
+  for (const d of dirs) await rm(d, { recursive: true, force: true });
+});
+
+async function project(meta: string): Promise<string> {
+  const root = await mkdtemp(join(tmpdir(), "meta-upgrade-"));
+  dirs.push(root);
+  await mkdir(join(root, "metaobjects"), { recursive: true });
+  await writeFile(join(root, "metaobjects", "meta.json"), meta, "utf8");
+  return root;
+}
+
+const WITH_RETIRED = `{
+  "metadata.root": {
+    "package": "acme::shop",
+    "children": [
+      { "requirement.functional": {
+          "name": "orderRecord",
+          "@level": 4,
+          "@status": "live",
+          "@statement": "An order records what was bought",
+          "@violation": "An order that cannot say what was bought",
+          "@verifiedBy": ["OrderServiceTest"]
+      }}
+    ]
+  }
+}`;
+
+const NEEDS_DECISION = `{
+  "metadata.root": {
+    "package": "acme::shop",
+    "children": [
+      { "requirement.functional": {
+          "name": "oldThing",
+          "@level": 4,
+          "@status": "abandoned",
+          "@statement": "Something we stopped doing",
+          "@violation": "n/a"
+      }}
+    ]
+  }
+}`;
+
+const CLEAN = `{
+  "metadata.root": {
+    "package": "acme::shop",
+    "children": [
+      { "requirement.functional": {
+          "name": "orderRecord",
+          "@level": 4,
+          "@status": "live",
+          "@statement": "An order records what was bought",
+          "@violation": "An order that cannot say what was bought"
+      }}
+    ]
+  }
+}`;
+
+describe("meta upgrade", () => {
+  test("PREVIEWS without writing by default", async () => {
+    const root = await project(WITH_RETIRED);
+    const code = await upgradeCommand([root], root);
+    expect(code).toBe(0);
+    // Untouched on disk — the default must never edit committed files.
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toBe(WITH_RETIRED);
+  });
+
+  test("--apply rewrites the file", async () => {
+    const root = await project(WITH_RETIRED);
+    expect(await upgradeCommand([root, "--apply"], root)).toBe(0);
+    const after = await readFile(join(root, "metaobjects", "meta.json"), "utf8");
+    expect(after).not.toContain("@verifiedBy");
+    // Everything else survives, byte-for-byte in the untouched regions.
+    expect(after).toContain('"@statement": "An order records what was bought"');
+    expect(after).toContain('"name": "orderRecord"');
+  });
+
+  test("a project with nothing retired exits 0 and is untouched", async () => {
+    const root = await project(CLEAN);
+    expect(await upgradeCommand([root, "--apply"], root)).toBe(0);
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toBe(CLEAN);
+  });
+
+  // The CI-facing contract. A refusal means the metadata still will not load, so exiting 0
+  // would let a pipeline record the migration as complete while the build is broken.
+  test("EXITS NON-ZERO when a decision is still required", async () => {
+    const root = await project(NEEDS_DECISION);
+    expect(await upgradeCommand([root, "--apply"], root)).toBe(1);
+    // And leaves the judgment case alone rather than guessing.
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toContain('"abandoned"');
+  });
+
+  test("--to bounds which retirements apply", async () => {
+    const root = await project(WITH_RETIRED);
+    // @verifiedBy retired in 0.24.0, so a 0.23.0 ceiling must leave it alone.
+    expect(await upgradeCommand([root, "--to", "0.23.0", "--apply"], root)).toBe(0);
+    expect(await readFile(join(root, "metaobjects", "meta.json"), "utf8")).toContain("@verifiedBy");
+  });
+
+  test("rejects an unknown flag with exit 2", async () => {
+    const root = await project(CLEAN);
+    expect(await upgradeCommand([root, "--nope"], root)).toBe(2);
+  });
+});
@@ -222,15 +222,29 @@ export function rewriteDocument(source: string, opts: RewriteOpts): RewriteResul
         changes.push({ attr, from: attr, to: rw.to, line });
       } else if (rw.kind === "dropAttr") {
         if (span === undefined) continue;
-        // Take the trailing comma and the line's own whitespace with it, so removing a
-        // middle key does not leave a dangling `,` or a blank line behind.
+        // Take the TRAILING comma and the line's own whitespace, so removing a middle key
+        // leaves neither a dangling `,` nor a blank line.
         let end = span.end;
         while (end < source.length && /[ \t]/.test(source[end] ?? "")) end++;
-        if (source[end] === ",") end++;
+        const hadTrailingComma = source[end] === ",";
+        if (hadTrailingComma) end++;
+
         let start = keyStart;
         while (start > 0 && /[ \t]/.test(source[start - 1] ?? "")) start--;
+
+        // THE LAST-KEY CASE, found by dogfooding rather than by the unit tests above: when
+        // the retired attr is last in its object there IS no trailing comma — the comma
+        // belongs to the PRECEDING key. Dropping without taking it leaves `"...",\n}`,
+        // which does not parse. A tool whose whole job is producing loadable metadata
+        // cannot emit invalid JSON.
+        if (!hadTrailingComma) {
+          let back = start;
+          while (back > 0 && /[\s]/.test(source[back - 1] ?? "")) back--;
+          if (source[back - 1] === ",") start = back - 1;
+        }
+
         if (source[start - 1] === "\n" && source[end] === "\n") end++;
-        else if (start > 0 && source[start - 1] !== "\n") start = keyStart;
+        else if (start > 0 && source[start - 1] !== "\n" && hadTrailingComma) start = keyStart;
         edits.push({ start, end, text: "" });
         changes.push({ attr, from: attr, to: "(removed)", line });
       } else {
 
@@ -33,6 +33,10 @@ describe("mechanical rewrites", () => {
     expect(r.text).toContain('"@level": 4');
     expect(r.changes).toHaveLength(1);
     expect(r.changes[0]?.attr).toBe("verifiedBy");
+    // Substring assertions alone are what let the trailing-comma bug through — they were
+    // all true of a document that no longer parsed. Every drop case now proves the result
+    // is still valid JSON.
+    expect(() => JSON.parse(r.text)).not.toThrow();
   });
 
   test("rewrites key AND value for @readOnly", () => {
@@ -73,6 +77,34 @@ describe("surgical editing", () => {
     expect(r.text.indexOf('"@statement"')).toBeLessThan(r.text.indexOf('"@level"'));
   });
 
+  // Caught by dogfooding against a real fixture, not by the tests above — the drop cases
+  // there all had a following key, so the trailing comma was always there to consume. When
+  // the retired attr is LAST, the comma belongs to the PRECEDING key and dropping naively
+  // leaves `"...",\n}` — invalid JSON, from a tool whose entire job is producing loadable
+  // metadata.
+  test("dropping the LAST key does not leave a trailing comma", () => {
+    const src = `{
+  "requirement.architectural": {
+    "name": "MoneyIsExactMinorUnits",
+    "@statement": "Amounts are exact integer minor units",
+    "@verifiedBy": ["MoneyRoundingTest"]
+  }
+}`;
+    const r = rewriteDocument(src, { typeKeyHint: "requirement.architectural" });
+    expect(r.text).not.toContain("@verifiedBy");
+    // The real assertion: the result must still parse.
+    expect(() => JSON.parse(r.text)).not.toThrow();
+    expect(JSON.parse(r.text)["requirement.architectural"]["@statement"]).toBe(
+      "Amounts are exact integer minor units",
+    );
+  });
+
+  test("dropping the ONLY key leaves a valid empty object", () => {
+    const src = `{ "requirement.functional": { "@verifiedBy": ["T"] } }`;
+    const r = rewriteDocument(src, { typeKeyHint: "requirement.functional" });
+    expect(() => JSON.parse(r.text)).not.toThrow();
+  });
+
   test("a document with nothing to change comes back BYTE-IDENTICAL", () => {
     const src = `{
   "requirement.functional": {