feat(metadata): a raw-document vocabulary rewriter, driven by the retirement map

Plan: docs/superpowers/plans/2026-08-21-meta-upgrade-vocabulary-rewriter.md. The engine
behind `meta upgrade` (CLI wiring lands next). Adds `rewrite` to the retirement map and
`rewriteDocument()`, which fixes what can be fixed mechanically and REFUSES the rest.

ONE MAP, NOT TWO. The loader already reads RETIRED_VOCABULARY to explain a failure; the
rewriter reads the same entries to fix it. So the message and the fix cannot drift — the
error says "use @mutability" and the tool writes @mutability for the same reason. A
parameterised `--from X --to Y` would have let those diverge and made the adopter supply the
mapping they came here to be told.

IT CANNOT USE THE LOADER, and that shapes the whole design. Once an attribute is
deregistered, metadata carrying it FAILS THE LOAD — that is what a retirement is. So
load → transform → canonical-serialize is impossible: the input does not load, and the
canonical serializer needs a loaded model. This works on RAW TEXT, which is also the only
reason an upgrade path exists: the adopter installs the new CLI and runs this against
metadata the new CLI refuses. A fixer needing a successful load is a chicken-and-egg with no
exit.

SURGICAL, NOT PARSE-AND-REPRINT. Adopters author JSONC with comments and meaningful key
order. A JSON.parse/stringify round-trip destroys both while reporting success, so every
edit is a span replacement against the original text, collected and applied right-to-left in
one pass — rewriting incrementally would invalidate every later offset. A document with
nothing to change comes back BYTE-IDENTICAL, and that is pinned.

REFUSES WHAT IT CANNOT KNOW. `@status: abandoned` has no `rewrite`, so it is reported with
its guide and left alone. Deleting the node, retyping it, and fixing the residue it describes
are all defensible and only a human knows which; a wrong guess emits metadata that LOADS and
means something different, which is strictly worse than refusing because the adopter would
believe the migration finished. Refusals are reported ALONGSIDE the mechanical changes, so a
partial upgrade is visible rather than silent.

VALUE RETIREMENTS FIRE ONLY ON THE RETIRED VALUES. `@dbColumnType: uuid_array` goes;
`@dbColumnType: jsonb` on the same attribute is live vocabulary and is untouched — removing
it would silently change a column type. Type scoping likewise: `@unique` is retired on
identity.secondary and live on a field, so the rewriter takes an explicit type scope rather
than matching bare names.

A TEST FOUND A REAL DEAD END while I was writing it: the `@dbColumnType` array kinds had
neither a rewrite nor a migration guide, so an adopter hitting them was told the vocabulary
was retired and given nowhere to go. Now mechanically dropped, since the attribute only ever
restated array-ness that `isArray` already carries.

Verified on real output rather than substring assertions: two retired attrs dropped with no
dangling comma and no blank line, comment and key order intact, the judgment case refused
with its guide, line numbers correct. metadata 2463 pass / 0 fail, workspace typecheck 0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: dmealing

docs/superpowers/plans/2026-08-21-meta-upgrade-vocabulary-rewriter.md

@@ -0,0 +1,82 @@
+# `meta upgrade` — a vocabulary rewriter driven by the retirement map
+
+Retiring vocabulary currently costs every adopter a manual sweep. This adds `meta upgrade`,
+which rewrites what can be rewritten and **refuses** what needs judgment, driven by the same
+map the loader already uses to explain a retirement.
+
+## The constraint that shapes everything
+
+**The rewriter cannot use the loader.** Once an attribute is deregistered, metadata carrying
+it fails the load — that is the entire point of the retirement. So load → transform →
+canonical-serialize is impossible: the input does not load, and the canonical serializer
+needs a loaded model.
+
+It operates on the **raw document**. That is also what makes the upgrade path exist: an
+adopter installs the new CLI, runs the fixer against metadata the new CLI *refuses*, and only
+then does anything else work. A fixer needing a successful load would be a chicken-and-egg
+with no exit.
+
+Second-order: **surgical text edits, never parse-and-reprint.** Adopters author JSONC with
+comments and meaningful key order; a round-trip through `JSON.parse`/`stringify` destroys
+both. Same distinction the repo already draws between ts-poet (greenfield emit) and ts-morph
+(in-place edit).
+
+## One map, not two
+
+`RETIRED_VOCABULARY` (shipped, `metadata/src/retired-vocabulary.ts`) already declares
+`since` / `why` / `replacedBy` / `migration`, and the loader reads it to explain a failure.
+The rewriter reads the **same** entries, so the message and the fix cannot drift: the error
+says "use `@counterexample`" and the fixer writes `@counterexample` for the same reason.
+
+## Mechanical vs judgment
+
+Not every retirement is automatable, and the tool must not pretend:
+
+| retirement | transform | automatable |
+|---|---|---|
+| `@violation` → `@counterexample` | key rename | yes |
+| `@readOnly: true` → `@mutability: "readOnly"` | key + value | yes |
+| `@verifiedBy` | drop the attr | yes |
+| `@status: abandoned` | delete node / retype / fix residue | **no — judgment** |
+
+`RetiredEntry` gains an optional `rewrite`. Present ⇒ the fixer applies it. **Absent ⇒ the
+fixer refuses that node and prints the migration guide**, the same detect-and-refuse posture
+used for the D1 primary-key move rather than emitting something un-appliable.
+
+## Tasks
+
+### 1. `rewrite` on `RetiredEntry`
+`{ kind: "renameAttr", to }` · `{ kind: "dropAttr" }` · `{ kind: "renameAttrValue", toAttr, toValue }`.
+Absent ⇒ judgment. Tests: every entry either carries a `rewrite` or names a `migration`;
+no entry claims a rewrite it cannot perform.
+
+### 2. The rewriter
+`rewriteDocument(text, opts) → { text, changes[], refusals[] }`, pure, no filesystem.
+- surgical: unchanged regions byte-identical, comments and key order preserved
+- JSON and YAML (YAML authoring is sigil-free — a rename there is the bare key)
+- reports every change with line numbers, and every refusal with its guide
+
+### 3. `meta upgrade`
+Dry-run + diff by DEFAULT (repo convention); `--apply` writes. `--to <version>` bounds which
+retirements apply. Non-zero exit when refusals remain, so CI cannot call a partial upgrade
+done.
+
+### 4. Dogfood
+Run it against this repo's own metadata and fixtures before shipping. Any refuse-case we hit
+is one an adopter would have hit.
+
+### 5. The rename — `@violation` → `@counterexample`
+Five ports, spec files, embedded definitions, `expected-registry.json`, fixtures, docs,
+skills, agent-context trees. **Breaking**, so it needs a MINOR and a `metamodelVersion` move.
+`registry-conformance` fails any port that misses it — mechanical work with a hard backstop.
+
+**Sequencing note:** `0.24.0-rc.5` is soaking. Tasks 1–4 are additive and land safely; task 5
+is breaking and belongs to the next MINOR, not to 0.24.0.
+
+## Verification
+
+- the rewriter is proven on a document with comments, odd key order, and both formats
+- a judgment case is **refused**, not silently skipped, and the exit code reflects it
+- our own corpus round-trips: rewrite → load → canonical-serialize is byte-identical to
+  loading the hand-migrated original
+- the gate is proven able to fail

server/typescript/packages/metadata/src/index.ts

@@ -287,3 +287,17 @@ export {
   stripPackage,
 } from "./naming.js";
 export type { EntityNameMap, ColumnNamingStrategy } from "./naming.js";
+
+// Retired vocabulary: the map the loader reads to explain a retirement, and the raw-document
+// rewriter `meta upgrade` drives from the SAME entries — so the error message and the fix
+// cannot drift apart.
+export {
+  RETIRED_VOCABULARY,
+  retiredAttr,
+  retiredAttrValue,
+  retiredSubType,
+  retirementHint,
+} from "./retired-vocabulary.js";
+export type { RetirementNote, RetiredEntry, VocabularyRewrite } from "./retired-vocabulary.js";
+export { rewriteDocument } from "./vocabulary-rewrite.js";
+export type { RewriteResult, RewriteChange, RewriteRefusal, RewriteOpts } from "./vocabulary-rewrite.js";

server/typescript/packages/metadata/src/retired-vocabulary.ts

@@ -42,7 +42,23 @@ export interface RetirementNote {
   readonly migration?: string;
 }
 
-/** One retirement. `subTypes: "*"` means every subtype of `type`. */
+/**
+ * The mechanical fix, when one exists.
+ *
+ * ABSENT MEANS JUDGMENT — `@status: abandoned` can be resolved by deleting the node, by
+ * retyping it, or by fixing the residue it describes, and only a human knows which. A tool
+ * that guessed would emit metadata that LOADS and means something different, which is worse
+ * than refusing: the adopter would believe the migration finished.
+ */
+export type VocabularyRewrite =
+  /** The attribute name changed; the value is untouched. */
+  | { readonly kind: "renameAttr"; readonly to: string }
+  /** The attribute went away with no replacement — drop it. */
+  | { readonly kind: "dropAttr" }
+  /** Both the name and the value changed (`@readOnly: true` → `@mutability: "readOnly"`). */
+  | { readonly kind: "renameAttrValue"; readonly toAttr: string; readonly fromValue: unknown; readonly toValue: unknown };
+
+/** One retirement. `subType: "*"` means every subtype of `type`. */
 export interface RetiredEntry extends RetirementNote {
   readonly type: string;
   /** `*` for every subtype of `type`, else the exact subtype. */
@@ -53,6 +69,9 @@ export interface RetiredEntry extends RetirementNote {
   readonly attrValues?: readonly string[];
   /** Set when the SUBTYPE itself was retired (`attr`/`attrValues` absent). */
   readonly isSubTypeRetirement?: boolean;
+  /** How `meta upgrade` fixes it. Absent ⇒ the human decides; the tool refuses and
+   *  prints `migration`. */
+  readonly rewrite?: VocabularyRewrite;
 }
 
 const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
@@ -65,13 +84,17 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     why: "it asked you to name a test, and verify could only check that the NAME occurred " +
          "somewhere in your test sources — never that the named test verified the claim",
     migration: REQUIREMENT_MIGRATION,
+    // Nothing replaced it, so the fix is removal. Safe to automate: the attribute drove no
+    // behaviour anyone else can observe.
+    rewrite: { kind: "dropAttr" },
   },
   {
     type: "requirement", subType: "*", attr: "supersededBy",
     since: "0.24.0",
     why: "a requirement is prescriptive — it states what should be true and is never a " +
          "journal of what happened",
     migration: REQUIREMENT_MIGRATION,
+    rewrite: { kind: "dropAttr" },
   },
   {
     type: "requirement", subType: "*", attr: "status",
@@ -89,6 +112,11 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     why: "a boolean could not express write-once, so the axis became an enum",
     replacedBy: "@mutability",
     migration: "docs/features/migrations/readonly-to-mutability.md",
+    // Key AND value: `@readOnly: true` becomes `@mutability: "readOnly"`. Only the `true`
+    // arm is mechanical — `@readOnly: false` was the default and simply goes away, which
+    // the rewriter treats as a drop rather than inventing a mutability the author never
+    // stated.
+    rewrite: { kind: "renameAttrValue", toAttr: "mutability", fromValue: true, toValue: "readOnly" },
   },
 
   // ── FR-037 R2: origin.collection retires to reserved-not-registered (0.24.0) ──
@@ -119,6 +147,16 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     why: "array-ness is DERIVED from `isArray`, so an array-flavoured physical type restated " +
          "something the model already knew",
     replacedBy: "isArray: true on the field",
+    // On a VALUE-scoped entry, `dropAttr` means "drop it when the value is one of the
+    // retired ones" — never unconditionally. `@dbColumnType: jsonb` is live vocabulary on
+    // the same attribute, and removing it would silently change the column type.
+    //
+    // Safe because the attribute said nothing the model did not already know: the field
+    // carrying `uuid_array` necessarily has `isArray: true`, which is where array-ness now
+    // comes from. There is no guide for this one, so without the rewrite an adopter would
+    // be told it is retired and given nowhere to go — which is what the dead-end test that
+    // caught this exists to prevent.
+    rewrite: { kind: "dropAttr" },
   },
 ];