fix(metadata): five retirements named a release that was never cut

The `@emit*` family retired in 0.25.0, but every entry — and the migration
guide's own header — said `0.24.6`. That version does not exist: the line went
0.24.5 → 0.25.0 when the breaking batch made it a MINOR, and the `since`
strings were authored while 0.24.6 was still the expected next number.

It is user-facing. `formatRetirementNote` renders "retired in 0.24.6 — …" into
the load error an adopter gets for `@emitRoutes`, and sends them to a CHANGELOG
entry that isn't there — the exact failure #337 built this map to prevent, since
an adopter who cannot find the decision reads the error as a registration bug.

Nothing caught it because the gate that exists checks the version's SHAPE:

    expect(e.since).toMatch(/^\d+\.\d+\.\d+$/)

and `0.24.6` matches that perfectly. So the new check asks whether the release
happened, against the CHANGELOG headings — the same way the adjacent test
already resolves each `migration` path against the file that must exist.

It deliberately does NOT require every `since` to be a shipped release. A
retirement is authored before the release carrying it, under `[Unreleased]`,
where the number is a forecast; failing that would make the gate red for the
whole development window. The rule is narrower: a `since` BELOW the version we
currently ship must have shipped. That is false exactly when a forecast is
superseded, and it fires at the release bump — the moment the guess becomes
wrong. Verified green → red → green by restamping one entry 0.24.6.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01At3v6M6uqECZ2Sb5eUv6YY

Author: dmealing

docs/features/migrations/emit-attrs-to-generator-config.md

@@ -1,7 +1,7 @@
 # Migration: the `@emit*` attributes become generator configuration
 
 **Applies to:** `@emitRoutes`, `@emitTanstack`, `@emitForm`, `@emitAngular`, `@emitGrid`
-**Retired in:** 0.24.6 · **Ports affected:** TypeScript only
+**Retired in:** 0.25.0 · **Ports affected:** TypeScript only
 **Automatic fix:** `meta upgrade --apply`
 
 ## What changed

scripts/test-doc-examples.ts

@@ -168,7 +168,7 @@ const CASES: readonly Case[] = [
   // starts flagging correct documentation gets switched off, and then catches nothing.
   {
     // The exact shape that motivated the work: a retired attribute two lines above the
-    // `...` that hid it. `@emitTanstack` is retired vocabulary as of 0.24.6 (FR-040 —
+    // `...` that hid it. `@emitTanstack` is retired vocabulary as of 0.25.0 (FR-040 —
     // the @emit* family left the model), which is what makes it the right fixture and
     // not merely an unused name: this is a spelling the docs really did teach.
     name: "an elision no longer hides a retired attribute",

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

@@ -255,7 +255,7 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     // caught this exists to prevent.
     rewrite: { kind: "dropAttr" },
   },
-  // ── FR-040: the @emit* family leaves the model (0.24.6) ──
+  // ── FR-040: the @emit* family leaves the model (0.25.0) ──
   //
   // Five attributes — @emitRoutes, @emitTanstack, @emitForm, @emitGrid, @emitAngular — were
   // READ by the TypeScript generators as per-entity kill switches, and documented as THE way
@@ -280,7 +280,7 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   // run also warns by name, rather than letting the file appear with no explanation.
   {
     type: "object", subType: "*", attr: "emitRoutes",
-    since: "0.24.6",
+    since: "0.25.0",
     why: "it was never registered vocabulary, so the opt-out we documented passed `meta gen` " +
          "and failed `meta verify`",
     replacedBy: "the routes generator's own `filter` — routesFile({ filter: (e) => … })",
@@ -289,7 +289,7 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   },
   {
     type: "object", subType: "*", attr: "emitTanstack",
-    since: "0.24.6",
+    since: "0.25.0",
     why: "it was never registered vocabulary, so the opt-out we documented passed `meta gen` " +
          "and failed `meta verify`",
     replacedBy: "the `filter` option on tanstackQuery() / tanstackGrid() / tanstackGridHook()",
@@ -298,7 +298,7 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   },
   {
     type: "object", subType: "*", attr: "emitForm",
-    since: "0.24.6",
+    since: "0.25.0",
     why: "it was never registered vocabulary, and its own doc comment described it backwards " +
          "— as opt-IN via `true`, while the code implemented opt-OUT via `false`",
     replacedBy: "formFile({ filter: (e) => … })",
@@ -307,7 +307,7 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   },
   {
     type: "object", subType: "*", attr: "emitAngular",
-    since: "0.24.6",
+    since: "0.25.0",
     why: "it was never registered vocabulary, and unlike its four siblings it was not even a " +
          "named constant — just a bare string literal in four generators",
     replacedBy: "the `filter` option on the Angular generators",
@@ -319,7 +319,7 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     // ANDed with the built-in gates and can only ever narrow. It became a generator OPTION,
     // which must be passed to BOTH grid generators — they emit a matched pair of files.
     type: "object", subType: "*", attr: "emitGrid",
-    since: "0.24.6",
+    since: "0.25.0",
     why: "it was never registered vocabulary, and being an opt-IN it could not be expressed " +
          "by a generator filter, which only ever narrows",
     replacedBy: "the `tphSubtypeGrids` option on BOTH tanstackGrid() and tanstackGridHook()",

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

@@ -12,7 +12,7 @@
 // fails, with the same error code. Only the message improves.
 
 import { describe, test, expect } from "bun:test";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import {
   retiredAttr,
@@ -116,6 +116,46 @@ describe("the map itself", () => {
     }
   });
 
+  // The shape check above passed on `0.24.6` — a release that was never cut. The @emit*
+  // retirements were authored while 0.24.6 was the expected next version, the line was
+  // renumbered to 0.25.0 when the breaking batch made it a MINOR, and the `since` strings
+  // stayed behind. Nothing noticed: no test reads the number, and the message it feeds
+  // ("retired in 0.24.6 — …") sends an adopter to a CHANGELOG entry that does not exist.
+  //
+  // A version is ALLOWED to have no heading while it is genuinely the upcoming release —
+  // a retirement is authored before the release that carries it, under `[Unreleased]`. So
+  // the rule is: a `since` BELOW the version we currently ship must have shipped. That is
+  // false exactly when a planned number is superseded, and it fails at the release bump,
+  // which is when the mistake becomes real.
+  test("every `since` below the current version names a release the CHANGELOG carries", () => {
+    const repoRoot = resolve(import.meta.dir, "../../../../..");
+    const changelog = readFileSync(join(repoRoot, "CHANGELOG.md"), "utf8");
+    const shipped = new Set(
+      [...changelog.matchAll(/^## \[(\d+\.\d+\.\d+)\]/gm)].map((m) => m[1] as string),
+    );
+    const current = JSON.parse(
+      readFileSync(join(import.meta.dir, "../package.json"), "utf8"),
+    ).version as string;
+
+    const order = (v: string): number[] => v.split(".").map(Number);
+    const below = (a: string, b: string): boolean => {
+      const [x, y] = [order(a), order(b)];
+      for (let i = 0; i < 3; i++) {
+        if ((x[i] as number) !== (y[i] as number)) return (x[i] as number) < (y[i] as number);
+      }
+      return false;
+    };
+
+    for (const e of RETIRED_VOCABULARY) {
+      if (!below(e.since, current) || shipped.has(e.since)) continue;
+      throw new Error(
+        `${e.type}.${e.subType} ${e.attr ?? ""}: retired in ${e.since}, but no such release — ` +
+          `we ship ${current} and the CHANGELOG has no [${e.since}] heading. ` +
+          `A planned version was superseded; restamp it with the release that carried it.`,
+      );
+    }
+  });
+
   test("every entry says something about what to do instead", () => {
     for (const e of RETIRED_VOCABULARY) {
       expect((e.replacedBy ?? "") + (e.migration ?? "") + e.why).not.toBe("");

server/typescript/packages/sdk/test/agent-context-capability-grounding.test.ts

@@ -41,7 +41,7 @@ const DELIBERATELY_NAMED_RETIRED_OR_CUT = new Set<string>([
   "@violation",     // renamed to @counterexample
   "@verifiedBy",    // dropped — it proved a NAME existed, never that the test verified the claim
   "@supersededBy",  // dropped — a requirement is prescriptive, never a journal
-  // FR-040 (0.24.6) — the @emit* family. Named for the same reason as the requirement rows
+  // FR-040 (0.25.0) — the @emit* family. Named for the same reason as the requirement rows
   // above, one step further: these were never REGISTERED AT ALL. They were read off metadata
   // by the TS generators and documented as the per-entity opt-out, so they passed `meta gen`
   // (open load) and failed `meta verify` (strict). The audit skill names all five so an