@@ -47,6 +47,9 @@ import type { AttrSchema, TypeRegistry } from "./registry.js";
 import { childRuleMatches } from "./registry.js";
 import { TYPE_FIELD, TYPE_METADATA } from "./shared/base-types.js";
 import { ATTR_SUBTYPE_PROPERTIES } from "./core/attr/attr-constants.js";
+// #337: turns "unknown X" into "retired in V — here is the migration". Changes no load
+// outcome; retired vocabulary still fails with the same code.
+import { retiredAttr, retiredAttrValue, retirementHint } from "./retired-vocabulary.js";
 import {
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_VALUES,
@@ -164,10 +167,17 @@ function validateNode(
       // @-attr still fails — only the `properties` subtype is exempt.)
       if (inst.subType === ATTR_SUBTYPE_PROPERTIES) continue;
       if (!byName.has(inst.name)) {
+        // #337: if we RETIRED this name, say so. "Not declared by any registered
+        // provider" is true and reads as "your metadata is malformed", which sent one
+        // adopter to file a registration bug against a deliberate, documented breaking
+        // change. Unrecognised names still report generically — a typo is a typo.
+        const retired = retiredAttr(typeKey, inst.name);
         errors.push(
           new ParseError(
             `Unknown attribute '@${inst.name}' on ${nodeLabel(node)} — ` +
-              `not declared by any registered provider for ${typeKey}`,
+              (retired !== undefined
+                ? retirementHint(retired)
+                : `not declared by any registered provider for ${typeKey}`),
             { code: "ERR_UNKNOWN_ATTR", source: node.source },
           ),
         );
@@ -290,11 +300,16 @@ function validateNode(
           ? []
           : [value];
       for (const bad of offenders) {
+        // #337: a member we REMOVED reads very differently from a member that never
+        // existed. `@status: abandoned` was valid one release ago, so "not one of the
+        // allowed values" invites the reader to conclude the enum is broken.
+        const retiredValue = retiredAttrValue(typeKey, inst.name, bad);
         errors.push(
           new ParseError(
             `${nodeLabel(node)} attribute '@${inst.name}' has value ` +
               `'${String(bad)}' which is not one of the allowed values: ` +
-              `${allowed.map((v) => String(v)).join(", ")}`,
+              `${allowed.map((v) => String(v)).join(", ")}` +
+              (retiredValue !== undefined ? ` — ${retirementHint(retiredValue)}` : ""),
             { code: "ERR_BAD_ATTR_VALUE", source: node.source },
           ),
         );
 
@@ -29,6 +29,8 @@ import { MetaRoot } from "./shared/meta-root.js";
 import { MetaAttr } from "./core/attr/meta-attr.js";
 import { canonicalSerialize, inferAttrSubType } from "./serializer-json.js";
 import { ParseError, type ErrorCode } from "./errors.js";
+// #337 — see retired-vocabulary.ts. Diagnostic only; no load outcome changes.
+import { retiredSubType, retirementHint } from "./retired-vocabulary.js";
 import { resolvedSource, type ErrorSource, type LoaderWarning, type Contributor } from "./source.js";
 import { semanticDiff } from "./semantic-diff.js";
 import {
@@ -427,8 +429,13 @@ export function buildTree(parsed: unknown, opts: ParseOptions): ParseResult {
       _currentPath!.pushKey(rootKey);
       const src = errSource();
       _currentPath!.pop();
+      // Same hint at the ROOT door. No retired subtype is root-legal today, so this arm
+      // is currently unreachable — wired anyway, because "fixed one door, left the
+      // other" is how a rule ends up half-true and passing every probe.
+      const retiredRoot = retiredSubType(rootType, rootSubType);
       throw new ParseError(
-        `Unknown root type "${rootType}.${rootSubType}" — not registered`,
+        `Unknown root type "${rootType}.${rootSubType}" — ` +
+          (retiredRoot !== undefined ? retirementHint(retiredRoot) : "not registered"),
         { code: rootTypeCode, source: src },
       );
     }
@@ -1264,9 +1271,13 @@ function processChildren(
         const childTypeCode = explicit && registry.allSubTypesOf(childType).length > 0
           ? "ERR_UNKNOWN_SUBTYPE" as const
           : "ERR_UNKNOWN_TYPE" as const;
+        // #337: a subtype we RETIRED (origin.collection) gets its retirement and its
+        // migration, not a bare "not registered" that reads like a broken install.
+        const retiredChild = retiredSubType(childType, childSubType);
         errors.push(
           new ParseError(
-            `Unknown type "${childType}.${childSubType}" — not registered`,
+            `Unknown type "${childType}.${childSubType}" — ` +
+              (retiredChild !== undefined ? retirementHint(retiredChild) : "not registered"),
             { code: childTypeCode, source: errSource() },
           ),
         );
 
@@ -0,0 +1,189 @@
+// server/typescript/packages/metadata/src/retired-vocabulary.ts
+//
+// Vocabulary this project USED to register, and what to do instead.
+//
+// WHY THIS EXISTS (#337). Under ADR-0023 the registry is strict and sealed, so retired
+// vocabulary fails the load — correctly. But the message it failed with said the attribute
+// was "not declared by any registered provider", which tells an author their metadata is
+// malformed when the truth is that the vocabulary was retired ON PURPOSE, in a named
+// release, with a written migration. An adopter read that error, concluded the tool had a
+// registration bug, filed it as one, and argued against a decision whose reasoning they had
+// never seen — because nothing in the error pointed at it. The migration guide answered
+// their objection precisely. They never found it.
+//
+// THIS CHANGES NO LOAD OUTCOME. Retired vocabulary still fails, with the same error code,
+// at the same site. Only the message gains a sentence. That is deliberate: making any of
+// these load again would undo an adjudicated breaking change, and a "helpful" shim is how a
+// retirement quietly stops being one.
+//
+// SCOPE IS BY TYPE, NEVER BY BARE NAME. `@unique` is retired on `identity.secondary` and
+// perfectly live on a field; a name-only match would brand a valid declaration as retired,
+// which is worse than the generic message it replaces. Every entry names the type it
+// applies to, and `*` means "every subtype of this type" — never "every type".
+//
+// A GENUINE TYPO MUST STAY GENERIC. This map is consulted only after the normal check has
+// already decided to fail, and it returns undefined for anything it does not recognise, so
+// `@maxLenght` still reports as an unknown attribute. The map speaks only where it KNOWS.
+//
+// CROSS-PORT: this is a DIAGNOSTIC, not registered vocabulary — it affects no registry
+// manifest and no load outcome, so it carries no registry-conformance obligation. The other
+// four ports fail identically today, just with the generic message; mirroring this map is a
+// per-port ergonomics follow-up, not a conformance gap.
+
+/** What a reader needs at the moment their load fails. */
+export interface RetirementNote {
+  /** The release that retired it. */
+  readonly since: string;
+  /** One line: what it was, and why it went. */
+  readonly why: string;
+  /** The vocabulary that replaced it, when something did. */
+  readonly replacedBy?: string;
+  /** Repo-relative migration guide. */
+  readonly migration?: string;
+}
+
+/** One retirement. `subTypes: "*"` means every subtype of `type`. */
+export interface RetiredEntry extends RetirementNote {
+  readonly type: string;
+  /** `*` for every subtype of `type`, else the exact subtype. */
+  readonly subType: string;
+  /** Retired ATTRIBUTE name (no `@`), when the attribute itself went. */
+  readonly attr?: string;
+  /** Retired VALUES of a surviving attribute, when only some members went. */
+  readonly attrValues?: readonly string[];
+  /** Set when the SUBTYPE itself was retired (`attr`/`attrValues` absent). */
+  readonly isSubTypeRetirement?: boolean;
+}
+
+const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
+
+export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
+  // ── FR-038: the requirement vocabulary becomes prescriptive-only (0.24.0) ──
+  {
+    type: "requirement", subType: "*", attr: "verifiedBy",
+    since: "0.24.0",
+    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,
+  },
+  {
+    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,
+  },
+  {
+    type: "requirement", subType: "*", attr: "status",
+    attrValues: ["abandoned", "superseded"],
+    since: "0.24.0",
+    why: "retiring a capability is DELETING its requirement; version control holds that it " +
+         "existed, and `notes` on a surviving entry holds what a reader still needs",
+    migration: REQUIREMENT_MIGRATION,
+  },
+
+  // ── FR-037 R1: @readOnly becomes the @mutability enum (0.24.0) ──
+  {
+    type: "field", subType: "*", attr: "readOnly",
+    since: "0.24.0",
+    why: "a boolean could not express write-once, so the axis became an enum",
+    replacedBy: "@mutability",
+    migration: "docs/features/migrations/readonly-to-mutability.md",
+  },
+
+  // ── FR-037 R2: origin.collection retires to reserved-not-registered (0.24.0) ──
+  {
+    type: "origin", subType: "collection", isSubTypeRetirement: true,
+    since: "0.24.0",
+    why: "it duplicated `origin.aggregate @agg: collect` on a strictly smaller attribute " +
+         "set, and nothing dispatched on it",
+    replacedBy: "origin.aggregate @agg: collect",
+    migration: "docs/features/migrations/origin-collection-retirement.md",
+  },
+
+  // ── ADR-0040: uniqueness lives in the TYPE, not an attribute (0.15.1) ──
+  {
+    type: "identity", subType: "secondary", attr: "unique",
+    since: "0.15.1",
+    why: "`identity.secondary` is now always a unique alternate key — uniqueness is encoded " +
+         "in the type, so the attribute had nothing left to say",
+    replacedBy: "index.lookup (for a NON-unique retrieval index)",
+    migration: "docs/features/migrations/identity-secondary-to-index-lookup.md",
+  },
+
+  // ── Metamodel 1.0: @dbColumnType slim-and-derive (0.15.0) ──
+  {
+    type: "field", subType: "*", attr: "dbColumnType",
+    attrValues: ["uuid_array", "text_array"],
+    since: "0.15.0",
+    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",
+  },
+];
+
+/** True when `entry` governs `typeKey` (`"<type>.<subType>"`). */
+function scopeMatches(entry: RetiredEntry, typeKey: string): boolean {
+  const dot = typeKey.indexOf(".");
+  if (dot < 0) return false;
+  const type = typeKey.slice(0, dot);
+  const subType = typeKey.slice(dot + 1);
+  if (entry.type !== type) return false;
+  return entry.subType === "*" || entry.subType === subType;
+}
+
+function note(entry: RetiredEntry): RetirementNote {
+  const out: RetirementNote = { since: entry.since, why: entry.why };
+  return {
+    ...out,
+    ...(entry.replacedBy !== undefined ? { replacedBy: entry.replacedBy } : {}),
+    ...(entry.migration !== undefined ? { migration: entry.migration } : {}),
+  };
+}
+
+/**
+ * The attribute NAME itself was retired for this type. Returns undefined for an attr whose
+ * name is unknown here — a typo must keep reporting as a typo.
+ *
+ * An entry carrying `attrValues` is a VALUE retirement on a surviving attribute, so it is
+ * deliberately not matched here: `@status` is still perfectly good vocabulary.
+ */
+export function retiredAttr(typeKey: string, attrName: string): RetirementNote | undefined {
+  const hit = RETIRED_VOCABULARY.find(
+    (e) => e.attr === attrName && e.attrValues === undefined && scopeMatches(e, typeKey),
+  );
+  return hit === undefined ? undefined : note(hit);
+}
+
+/** A specific VALUE of a surviving attribute was retired. */
+export function retiredAttrValue(
+  typeKey: string,
+  attrName: string,
+  value: unknown,
+): RetirementNote | undefined {
+  if (typeof value !== "string") return undefined;
+  const hit = RETIRED_VOCABULARY.find(
+    (e) => e.attr === attrName && e.attrValues?.includes(value) === true && scopeMatches(e, typeKey),
+  );
+  return hit === undefined ? undefined : note(hit);
+}
+
+/** The SUBTYPE itself was retired (`origin.collection`). */
+export function retiredSubType(type: string, subType: string): RetirementNote | undefined {
+  const hit = RETIRED_VOCABULARY.find(
+    (e) => e.isSubTypeRetirement === true && e.type === type && e.subType === subType,
+  );
+  return hit === undefined ? undefined : note(hit);
+}
+
+/**
+ * The sentence appended to a failing diagnostic. Kept here rather than at each call site so
+ * all three failure sites word a retirement identically — an adopter who has seen one
+ * recognises the next.
+ */
+export function retirementHint(n: RetirementNote): string {
+  const parts = [`retired in ${n.since} — ${n.why}`];
+  if (n.replacedBy !== undefined) parts.push(`Use ${n.replacedBy} instead.`);
+  if (n.migration !== undefined) parts.push(`Migration: ${n.migration}.`);
+  return parts.join(". ").replace(/\.\./g, ".");
+}