@metaobjectsdev/metadata 0.24.1 → 0.24.3

package/src/core/vocabulary-rewrite-yaml.ts

@@ -22,12 +22,19 @@
 // span replacement on the original text, and any region not deliberately changed comes back
 // byte-identical. That is the same guarantee the JSON arm makes, by the same means.
 //
+// IT ALSO RESOLVES ATTRIBUTE CONTRADICTIONS (`../attr-contradictions.ts`), matched per NODE
+// rather than per pair — the illegal thing is the PAIR of keys, so the unit is the mapping
+// that holds one node's own keys. `eachNodeBody` below is that walk. Doing it by proximity
+// instead was tried in the JSON arm and took a `fields` belonging to a sibling node.
+//
 // SIGIL-FREE, PER ADR-0006. YAML authoring writes bare attribute keys (`violation:`) and the
 // desugar re-adds the `@` when lowering to canonical JSON. So a rename emits a BARE key here
 // where the JSON arm emits `"@name"`. A leading `@` is still matched on input — an author who
 // wrote one gets it fixed rather than skipped — but is never introduced.
 
 import { LineCounter, isMap, isSeq, parseDocument, type Node, type Pair } from "yaml";
+import { ATTR_CONTRADICTIONS, contradictionScopeMatches } from "../attr-contradictions.js";
+import type { AttrContradiction } from "../attr-contradictions.js";
 import {
   RETIRED_VOCABULARY,
   note,
@@ -163,6 +170,59 @@ function eachPair(
   }
 }
 
+/** A node's own key set: the mapping that a `<type>.<subType>:` key introduces. */
+interface NodeBody {
+  readonly items: readonly Pair[];
+  readonly flow: boolean;
+}
+
+/**
+ * Visit every node BODY in the document.
+ *
+ * The unit is the body rather than the pair because a contradiction is a property of a
+ * SIBLING SET. `body.items` is exactly this node's own keys — a child node lives inside the
+ * value of a `children:` pair, so it is reached by recursion and never mistaken for a
+ * sibling.
+ */
+function eachNodeBody(node: unknown, visit: (typeKey: string, body: NodeBody) => void): void {
+  if (isMap(node)) {
+    for (const pair of node.items) {
+      const k = keyText(pair.key);
+      if (k !== undefined && TYPE_KEY.test(k) && isMap(pair.value)) {
+        visit(k, { items: pair.value.items as Pair[], flow: pair.value.flow === true });
+      }
+      if (pair.value != null) eachNodeBody(pair.value, visit);
+    }
+    return;
+  }
+  if (isSeq(node)) {
+    for (const item of node.items) eachNodeBody(item as Node, visit);
+  }
+}
+
+/** An authored `@` must not hide a key from either table; the sigil is never introduced. */
+function bareKey(pair: Pair): string | undefined {
+  const k = keyText(pair.key);
+  if (k === undefined) return undefined;
+  return k.startsWith("@") ? k.slice(1) : k;
+}
+
+/** True when `keep` holds one of the entry's `keepValues` (or the entry names none,
+ *  in which case mere presence is the contradiction). Mirrors the JSON rewriter's
+ *  `keepValueMatches` — one rule, two doors, and a divergence here is a file format
+ *  silently migrating differently from the other. */
+function keepValueMatches(pair: Pair, c: AttrContradiction): boolean {
+  if (c.keepValues === undefined) return true;
+  const v = (pair.value as { value?: unknown } | null)?.value;
+  return typeof v === "string" && c.keepValues.includes(v);
+}
+
+/** Does this pair carry a string that actually says something? */
+function suppliesText(pair: Pair): boolean {
+  const v = (pair.value as { value?: unknown } | null)?.value;
+  return typeof v === "string" && v.trim().length > 0;
+}
+
 /**
  * Rewrite retired vocabulary in one raw YAML metadata document.
  *
@@ -188,6 +248,47 @@ export function rewriteYamlDocument(source: string, opts: RewriteOpts = {}): Yam
   const inWindow = (e: RetiredEntry): boolean =>
     opts.maxVersion === undefined || atOrBefore(e.since, opts.maxVersion);
 
+  // ── Attribute contradictions: two LIVE attrs that may not sit on one node ──
+  //
+  // THE TWO SIDES ARE ASKED DIFFERENT QUESTIONS, mirroring the loader's Rule 1a exactly
+  // (`validation-passes.ts`, `hasFieldsAttr` vs `hasExpr`) and the JSON arm's copy of it.
+  // The DROP side counts on PRESENCE — an empty `fields: []` beside `expr` is still a
+  // declaration of both, and is the case where the discard is total. The KEEP side counts
+  // only when it supplies a key, so a blank `expr: ""` beside `fields` is a plain column
+  // index the loader accepts and this must leave alone.
+  //
+  // IT SEES ONLY THIS NODE'S OWN KEYS. A node declaring `expr` while INHERITING `fields`
+  // through `extends` contradicts itself in the loaded model and not on the page; no
+  // raw-document rewriter can resolve a super-reference, so that stays the loader's refusal.
+  eachNodeBody(doc.contents, (typeKey, body) => {
+    for (const c of ATTR_CONTRADICTIONS) {
+      if (opts.maxVersion !== undefined && !atOrBefore(c.since, opts.maxVersion)) continue;
+      if (!contradictionScopeMatches(c, typeKey)) continue;
+      // `keep` must be present AND, when the entry names values, hold one of them —
+      // otherwise status and implementedBy would contradict on every status.
+      if (!body.items.some(
+        (p) => bareKey(p) === c.keep && suppliesText(p) && keepValueMatches(p, c),
+      )) continue;
+
+      for (const pair of body.items) {
+        if (bareKey(pair) !== c.drop) continue;
+        const span = pairSpan(pair);
+        if (span === undefined) continue;
+        const d = dropSpan(source, span, body.flow);
+        // Undeletable in place (a sequence item's leading key) — leave it, and let the
+        // loader keep refusing rather than reshape the author's sequence.
+        if (d === undefined) continue;
+        edits.push({ ...d, text: "" });
+        changes.push({
+          attr: c.drop,
+          from: c.drop,
+          to: `(removed — ${c.keep} keys this node)`,
+          line: lineOf(span.keyStart),
+        });
+      }
+    }
+  });
+
   eachPair(doc.contents, undefined, (pair, scope, flow) => {
     const key = keyText(pair.key);
     if (key === undefined) return;
@@ -240,6 +341,13 @@ export function rewriteYamlDocument(source: string, opts: RewriteOpts = {}): Yam
       const rw = entry.rewrite;
       if (rw === undefined) refuse();
       else if (rw.kind === "renameAttr") {
+        // NOTE — the JSON rewriter refuses a rename onto a key the node already declares,
+        // because two `"@counterexample"` members in one object parse silently with the
+        // last one winning. YAML needs no such guard: a duplicate key is a hard PARSE
+        // ERROR, so the same document fails loudly on the next load rather than quietly
+        // losing the author's surviving sentence. Same rule, different blast radius —
+        // if `eachPair` ever gains sibling access, mirror the JSON guard here anyway.
+        //
         // Preserve the author's quoting style; YAML keys are usually bare, but a quoted key
         // must stay quoted or the surrounding style stops being self-consistent.
         const rawKey = source.slice(span.keyStart, span.keyEnd);

package/src/errors.ts

@@ -196,6 +196,16 @@ export const ERROR_CODES = [
   // @fields), whichever is declared supplies no key, or a named field does not exist
   // on the owning entity's effective (resolved via extends) field set.
   "ERR_INVALID_INDEX",
+  // FR-039 — a requirement.* with @status: retired declares @implementedBy. Refused
+  // rather than exempted: a retired capability has no implementation BY DEFINITION,
+  // so forbidding the attribute makes the dangling-reference class unreachable
+  // instead of silently tolerated (which is what 0.24.0 removed the old vocabulary
+  // over — 29 unresolvable refs across 14 entries reported as zero).
+  "ERR_REQUIREMENT_RETIRED_HAS_IMPLEMENTORS",
+  // FR-039 — @supersededBy on a requirement whose @status is not `retired`. The
+  // attribute names what REPLACED a withdrawn capability; on a live one there is
+  // nothing to have replaced it.
+  "ERR_REQUIREMENT_SUPERSEDED_BY_NOT_RETIRED",
   // #195 — origin.computed @expr: the expression tree's inferred root type does
   // not equal the carrying field's declared field.<subType>. A computed column's
   // type is DERIVED from its expression, never asserted (no @convert escape),

package/src/index.ts

@@ -299,5 +299,14 @@ export {
   retirementHint,
 } from "./retired-vocabulary.js";
 export type { RetirementNote, RetiredEntry, VocabularyRewrite } from "./retired-vocabulary.js";
+// Its sibling: pairs of LIVE attributes that may not sit on one node. Same two consumers,
+// same reason — a retirement removes a name, a contradiction refuses a combination.
+export {
+  ATTR_CONTRADICTIONS,
+  contradictionsFor,
+  contradictionScopeMatches,
+  contradictionHint,
+} from "./attr-contradictions.js";
+export type { AttrContradiction } from "./attr-contradictions.js";
 export { rewriteDocument } from "./vocabulary-rewrite.js";
 export type { RewriteResult, RewriteChange, RewriteRefusal, RewriteOpts } from "./vocabulary-rewrite.js";

package/src/loader/meta-data-loader.ts

@@ -18,7 +18,7 @@ import { ParseError } from "../errors.js";
 import type { LoaderWarning } from "../source.js";
 import { codeSource, resolvedSource } from "../source.js";
 import { parseJson } from "../parser-json.js";
-import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter } from "./validation-passes.js";
+import { validateDataGridSortFields, validateFilterableHasIndex, validateFilterableHasSupportedOps, validateSortableHasSupportedSubtype, validateOriginPaths, validateDerivedFieldProvidability, validateDataGridFilterValues, validateFieldObjectStorage, validateFieldMap, validateTemplatePayloadRefs, validateFieldDefaults, validateRelationships, validateIndexLookupFields, validateProjectionFilter, validateRetiredRequirementLinks } from "./validation-passes.js";
 import { runRegisteredValidation } from "./validation-registry.js";
 import { validateSourceRoles } from "../persistence/source/validate-source-roles.js";
 import { validateSourceEscapes } from "../persistence/source/validate-source-escapes.js";
@@ -611,6 +611,11 @@ export class MetaDataLoader {
       // (ADR-0039: resolving accessor, so inherited fields via extends are visible).
       errors.push(...validateIndexLookupFields(root));
 
+      // FR-039 — a retired requirement carries no @implementedBy (refused, not
+      // exempted, so the dangling-ref class is unreachable) and @supersededBy is
+      // legal only on `retired`.
+      errors.push(...validateRetiredRequirementLinks(root));
+
       // Phase 2 — validation DERIVED FROM THE TYPE REGISTRY: each node's TypeDefinition
       // carries its reference descriptors + imperative validator, run as one recursive walk
       // over a built-once symbol table. A downstream provider's custom type validates itself

package/src/loader/validation-passes.ts

@@ -13,6 +13,7 @@
 import type { MetaData } from "../shared/meta-data.js";
 import type { MetaObject } from "../core/object/meta-object.js";
 import type { MetaReferenceIdentity } from "../core/identity/meta-identity.js";
+import { contradictionHint, contradictionsFor } from "../attr-contradictions.js";
 import { ParseError, type ErrorCode } from "../errors.js";
 import { resolveObjectRef, didYouMeanHint } from "../naming-refs.js";
 import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "../shared/structural.js";
@@ -135,6 +136,13 @@ import {
   opsForSubType,
   opsForField,
 } from "../core/query/query-constants.js";
+import {
+  REQUIREMENT,
+  REQUIREMENT_ATTR_STATUS,
+  REQUIREMENT_ATTR_IMPLEMENTED_BY,
+  REQUIREMENT_ATTR_SUPERSEDED_BY,
+  REQUIREMENT_STATUS_RETIRED,
+} from "../core/requirement/requirement-constants.js";
 
 // ---------------------------------------------------------------------------
 // Layout dataGrid @defaultSortField validation
@@ -2165,15 +2173,25 @@ export function validateIndexLookupFields(root: MetaData): ParseError[] {
       const hasExpr = typeof exprRaw === "string" && exprRaw.trim().length > 0;
 
       // Rule 1a: exactly one of @fields / @expr may be DECLARED.
+      //
+      // The closing sentence comes from `attr-contradictions.ts`, which is also what
+      // `meta upgrade` rewrites from — so the fix an adopter is TOLD about and the edit
+      // the tool MAKES are one statement, and a change to either moves both. #337 is the
+      // reason it names the command at all: an adopter shown only that their metadata is
+      // invalid concludes the tool has a bug, because nothing points at the way out.
       if (hasFieldsAttr && hasExpr) {
+        const contradiction = contradictionsFor(label).find(
+          (c) => c.drop === INDEX_ATTR_FIELDS && c.keep === IDENTITY_ATTR_EXPR,
+        );
         errors.push(
           new ParseError(
+            // The site states WHICH node broke the rule; the table states the RULE and the
+            // fix. Splitting it that way is what keeps one copy of each.
             `${label} "${node.name}" on "${obj.name}" declares BOTH ` +
-              `@${INDEX_ATTR_FIELDS} and @${IDENTITY_ATTR_EXPR}; they are the two ` +
-              `mutually exclusive ways to key an index. @${IDENTITY_ATTR_EXPR} is used ` +
-              `INSTEAD of @${INDEX_ATTR_FIELDS} — drop one. ` +
-              `(Declaring both previously loaded but silently discarded ` +
-              `@${INDEX_ATTR_FIELDS}.)`,
+              `@${INDEX_ATTR_FIELDS} and @${IDENTITY_ATTR_EXPR}: ` +
+              (contradiction === undefined
+                ? `@${IDENTITY_ATTR_EXPR} is used INSTEAD of @${INDEX_ATTR_FIELDS} — drop one.`
+                : contradictionHint(contradiction)),
             { code: "ERR_INVALID_INDEX", source: node.source },
           ),
         );
@@ -2392,3 +2410,75 @@ function checkProjectionFilterRefs(
     }
   }
 }
+
+// ---------------------------------------------------------------------------
+// FR-039 — a retired requirement's link vocabulary
+//
+// Two rules, and the first is the whole structural point of the FR.
+//
+//   1. `@status: retired` may NOT carry `@implementedBy`. Not exempt from the
+//      dangling-reference check — REFUSED. 0.24.0 removed the previous retired
+//      vocabulary because `verify` was SILENT on dangling refs for it, hiding 29
+//      unresolvable references across 14 entries in one estate while reporting
+//      zero. That silence was a deliberate EXEMPTION, so the fix was diagnosed as
+//      "delete the vocabulary". Forbidding the attribute makes the bug class
+//      UNREACHABLE instead: a retired capability has no implementation by
+//      definition, so its references cannot dangle because they cannot exist.
+//
+//   2. `@supersededBy` is legal ONLY on `retired`. It names what REPLACED a
+//      withdrawn capability; on a live one there is nothing to have replaced it.
+//      Resolution of the reference itself is `verify`'s job (it owns every other
+//      @implementedBy-style resolution) — the loader owns the shape.
+//
+// Runs in every port. `requirement.*` gate logic otherwise lives only in the TS
+// CLI, which is exactly why THIS rule belongs in the loader: a Java or Python
+// estate would otherwise be free to author the shape the rule exists to prevent.
+//
+// ADR-0039: children()/attr() throughout — never own* — so a requirement that
+// inherits its status through `extends` is judged on its EFFECTIVE status.
+// ---------------------------------------------------------------------------
+
+export function validateRetiredRequirementLinks(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+
+  const walk = (node: MetaData): void => {
+    for (const child of node.children()) {
+      if (child.type === REQUIREMENT) {
+        const status = child.attr(REQUIREMENT_ATTR_STATUS);
+        const isRetired = status === REQUIREMENT_STATUS_RETIRED;
+
+        if (isRetired && child.attr(REQUIREMENT_ATTR_IMPLEMENTED_BY) !== undefined) {
+          errors.push(
+            new ParseError(
+              `requirement.${child.subType} "${child.name}" is @status: ` +
+                `${REQUIREMENT_STATUS_RETIRED} and declares @${REQUIREMENT_ATTR_IMPLEMENTED_BY}. ` +
+                `A retired capability has no implementation — that is what retiring it means. ` +
+                `Delete the attribute; if the nodes are still there, the capability is not retired. ` +
+                `What used to implement it belongs in \`notes\`, and what REPLACED it in ` +
+                `@${REQUIREMENT_ATTR_SUPERSEDED_BY}.`,
+              { code: "ERR_REQUIREMENT_RETIRED_HAS_IMPLEMENTORS", source: child.source },
+            ),
+          );
+        }
+
+        if (!isRetired && child.attr(REQUIREMENT_ATTR_SUPERSEDED_BY) !== undefined) {
+          errors.push(
+            new ParseError(
+              `requirement.${child.subType} "${child.name}" declares ` +
+                `@${REQUIREMENT_ATTR_SUPERSEDED_BY} but its @${REQUIREMENT_ATTR_STATUS} is ` +
+                `"${status ?? "(absent)"}". That attribute names the requirement which REPLACED a ` +
+                `withdrawn one, so it is legal only on @${REQUIREMENT_ATTR_STATUS}: ` +
+                `${REQUIREMENT_STATUS_RETIRED}.`,
+              { code: "ERR_REQUIREMENT_SUPERSEDED_BY_NOT_RETIRED", source: child.source },
+            ),
+          );
+        }
+      }
+      // Hierarchy IS nesting, so a retired requirement can sit at any depth.
+      walk(child);
+    }
+  };
+
+  walk(root);
+  return errors;
+}

package/src/registry-manifest.ts

@@ -112,7 +112,7 @@ interface ManifestType {
  * constant read `"0.10"`). Bump with that script — never by hand — so the manifest and
  * all four port constants move together.
  */
-export const METAMODEL_VERSION = "0.12";
+export const METAMODEL_VERSION = "0.13";
 
 /** The full canonical manifest. All collections are sorted for byte-stability. */
 interface RegistryManifest {

package/src/retired-vocabulary.ts

@@ -25,6 +25,11 @@
 // 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.
 //
+// ITS SIBLING IS `attr-contradictions.ts` — pairs of LIVE attributes that may not sit on one
+// node. Same two consumers (the loader's diagnostic and the `meta upgrade` rewriter), same
+// reason for existing; kept apart because a retirement matches ONE name while a contradiction
+// matches a PAIR, and merging them would give every entry here fields it can never use.
+//
 // 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
@@ -91,6 +96,7 @@ export interface RetiredEntry extends RetirementNote {
 }
 
 const REQUIREMENT_MIGRATION = "docs/features/migrations/verified-by-retirement.md";
+const RETIRED_STATUS_MIGRATION = "docs/features/migrations/retired-status-restore.md";
 
 export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
   // ── 0.24.0: `@violation` is renamed `@counterexample` ──
@@ -124,21 +130,58 @@ export const RETIRED_VOCABULARY: readonly RetiredEntry[] = [
     // behaviour anyone else can observe.
     rewrite: { kind: "dropAttr" },
   },
+  // (@supersededBy is NOT retired vocabulary. 0.24.0 deregistered it; FR-039 registers
+  // it again on `retired` only, and this time it RESOLVES — which is what the
+  // 2026-08-10 ruling asked for at point 4 and never got. An entry here would make
+  // `meta upgrade` delete an attribute the loader now accepts.)
+  // ── FR-039 (0.24.2): `abandoned` / `superseded` become `retired` ──
+  //
+  // These were retired in 0.24.0 on the rule that a requirement never journals what
+  // happened, and `meta upgrade` REFUSED them because what becomes of a retired
+  // capability's record was judgement. FR-039 restores the capability under a name
+  // that states the standing rule rather than the history — `retired` means "this
+  // must not be rebuilt" — so the edit is no longer a judgement call and the tool
+  // can make it.
+  //
+  // TWO entries rather than one value-map, because the rewriter's `renameAttrValue`
+  // carries a single `fromValue` and `attrValues` already scopes each occurrence to
+  // the value it fires on. `otherwise` is therefore unreachable, and is `refuse` so
+  // that a future third member cannot be silently dropped by this entry.
+  //
+  // `@implementedBy` on one of these is handled by ATTR_CONTRADICTIONS, not here —
+  // it is a live attribute made illegal by a sibling's VALUE, which is a different
+  // match shape. Both passes run in one `meta upgrade`, so a legacy entry carrying
+  // both is fully repaired in a single run rather than rewritten into a file that
+  // still will not load.
   {
-    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",
+    attrValues: ["abandoned"],
+    since: "0.24.2",
+    why: "a retired capability is recorded as `retired`, which states the standing rule " +
+         "(do not rebuild this) rather than narrating what happened to it",
+    migration: RETIRED_STATUS_MIGRATION,
+    rewrite: {
+      kind: "renameAttrValue",
+      toAttr: "status",
+      fromValue: "abandoned",
+      toValue: "retired",
+      otherwise: "refuse",
+    },
   },
   {
     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,
+    attrValues: ["superseded"],
+    since: "0.24.2",
+    why: "`superseded` was `retired` plus a pointer, and the pointer is @supersededBy — " +
+         "which is registered again, and now RESOLVES",
+    migration: RETIRED_STATUS_MIGRATION,
+    rewrite: {
+      kind: "renameAttrValue",
+      toAttr: "status",
+      fromValue: "superseded",
+      toValue: "retired",
+      otherwise: "refuse",
+    },
   },
 
   // ── FR-037 R1: @readOnly becomes the @mutability enum (0.24.0) ──

package/src/vocabulary-rewrite.ts

@@ -40,12 +40,20 @@
 // (flow mappings, `{ name: x, readOnly: true }`) was not matched at all. YAML's value extent
 // is not derivable by scanning; JSON's is.
 //
+// IT ALSO RESOLVES ATTRIBUTE CONTRADICTIONS — two LIVE attributes that may not sit on one
+// node (`attr-contradictions.ts`). Same machinery, different match: a retirement finds one
+// key, a contradiction finds a PAIR inside one node body, which is exactly what `scopeRanges`
+// already answers. Doing it by proximity instead ("a `fields` with an `expr` near it") was
+// tried and took a `fields` whose neighbouring `expr` belonged to a SIBLING node.
+//
 // IT REFUSES WHAT IT CANNOT KNOW. A retirement with no `rewrite` (`@status: abandoned`) is
 // reported, never guessed at. Deleting the node, retyping it, and fixing the residue it
 // describes are all defensible, and a wrong guess emits metadata that LOADS and means
 // something different — strictly worse than leaving it alone, because the adopter would
 // believe the migration finished.
 
+import { ATTR_CONTRADICTIONS, contradictionScopeMatches } from "./attr-contradictions.js";
+import type { AttrContradiction } from "./attr-contradictions.js";
 import {
   RETIRED_VOCABULARY,
   note,
@@ -158,15 +166,71 @@ function scopeRanges(source: string): ScopeRange[] {
   return ranges;
 }
 
-/** The type key governing `offset` — the innermost body containing it. */
-function scopeAt(ranges: readonly ScopeRange[], offset: number): string | undefined {
+/** The innermost node body containing `offset`. */
+function scopeRangeAt(ranges: readonly ScopeRange[], offset: number): ScopeRange | undefined {
   let best: ScopeRange | undefined;
   for (const r of ranges) {
     if (offset <= r.bodyStart || offset >= r.bodyEnd) continue;
     // Properly nested ranges: the innermost containing one starts last.
     if (best === undefined || r.bodyStart > best.bodyStart) best = r;
   }
-  return best?.typeKey;
+  return best;
+}
+
+/** The type key governing `offset`. Derived from the range so the two cannot disagree —
+ *  a retirement asks WHICH type, a contradiction asks WHICH NODE, and answering them from
+ *  two separate walks is how the pair-matching would drift from the scoping. */
+function scopeAt(ranges: readonly ScopeRange[], offset: number): string | undefined {
+  return scopeRangeAt(ranges, offset)?.typeKey;
+}
+
+/** One key occurrence: where the key starts, and where its value begins. */
+interface KeySite {
+  readonly keyStart: number;
+  readonly afterKey: number;
+}
+
+/** Every place `attr` appears as a key inside `range`'s OWN body — a nested node's key of
+ *  the same name belongs to that node, not to this one. Containment alone is not enough:
+ *  a node body contains its children's bodies, so the innermost enclosing range must BE
+ *  this range. That identity test is what proximity matching cannot express. */
+function ownKeys(
+  source: string,
+  ranges: readonly ScopeRange[],
+  range: ScopeRange,
+  attr: string,
+): KeySite[] {
+  const out: KeySite[] = [];
+  const re = keyPattern(attr);
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(source)) !== null) {
+    if (m.index <= range.bodyStart || m.index >= range.bodyEnd) continue;
+    if (scopeRangeAt(ranges, m.index)?.bodyStart !== range.bodyStart) continue;
+    out.push({ keyStart: m.index, afterKey: m.index + m[0].length });
+  }
+  return out;
+}
+
+
+/** True when `keep` holds one of the entry's `keepValues` (or the entry names none,
+ *  in which case mere presence is the contradiction). */
+function keepValueMatches(source: string, site: KeySite, c: AttrContradiction): boolean {
+  if (c.keepValues === undefined) return true;
+  const raw = valueSpan(source, site.afterKey)?.raw;
+  if (raw === undefined) return false;
+  return c.keepValues.some((v) => rawEquals(raw, v));
+}
+
+/** Does this key carry a string that actually says something? */
+function suppliesText(source: string, site: KeySite): boolean {
+  const raw = valueSpan(source, site.afterKey)?.raw;
+  if (raw === undefined) return false;
+  try {
+    const v: unknown = JSON.parse(raw);
+    return typeof v === "string" && v.trim().length > 0;
+  } catch {
+    return false;
+  }
 }
 
 /**
@@ -282,6 +346,49 @@ export function rewriteDocument(source: string, opts: RewriteOpts = {}): Rewrite
     }
   }
 
+  // ── Attribute contradictions: two LIVE attrs that may not sit on one node ──
+  //
+  // Matched per NODE, not per occurrence, because the illegal thing is the pair. `ownKeys`
+  // supplies the node-identity test the proximity approach could not: a `@fields` and an
+  // `@expr` that merely appear near each other may belong to different siblings.
+  //
+  // THE TWO SIDES ARE ASKED DIFFERENT QUESTIONS, mirroring the loader's Rule 1a exactly
+  // (`validation-passes.ts`, `hasFieldsAttr` vs `hasExpr`). The DROP side counts on
+  // PRESENCE — `@fields: []` beside `@expr` is still a declaration of both, and is the case
+  // where the discard is total. The KEEP side counts only when it actually supplies a key,
+  // so `@expr: ""` beside `@fields` is a plain column index the loader accepts and this
+  // must not touch. If those two predicates ever diverge, this deletes an attribute from a
+  // document that was loading.
+  //
+  // IT SEES ONLY THIS NODE'S OWN TEXT. A node declaring `@expr` while INHERITING `@fields`
+  // through `extends` contradicts itself in the loaded model and not on the page, and no
+  // raw-text rewriter can resolve a super-reference. That case stays a refusal from the
+  // loader — correctly, since the fix is on the parent and is the adopter's call.
+  for (const range of ranges) {
+    for (const c of ATTR_CONTRADICTIONS) {
+      if (opts.maxVersion !== undefined && !atOrBefore(c.since, opts.maxVersion)) continue;
+      if (!contradictionScopeMatches(c, range.typeKey)) continue;
+      // `keep` must be present AND, when the entry names values, hold one of them —
+      // otherwise @status and @implementedBy would contradict on every status.
+      if (!ownKeys(source, ranges, range, c.keep).some(
+        (k) => suppliesText(source, k) && keepValueMatches(source, k, c),
+      )) continue;
+
+      for (const site of ownKeys(source, ranges, range, c.drop)) {
+        const span = valueSpan(source, site.afterKey);
+        if (span === undefined) continue;
+        const { start, end } = dropSpan(source, site.keyStart, span.end);
+        edits.push({ start, end, text: "" });
+        changes.push({
+          attr: c.drop,
+          from: c.drop,
+          to: `(removed — @${c.keep} keys this node)`,
+          line: lineAt(source, site.keyStart),
+        });
+      }
+    }
+  }
+
   for (const entry of RETIRED_VOCABULARY.filter((e) => e.attr !== undefined && inWindow(e))) {
     const attr = entry.attr as string;
     const re = keyPattern(attr);
@@ -293,8 +400,9 @@ export function rewriteDocument(source: string, opts: RewriteOpts = {}): Rewrite
       const afterKey = m.index + m[0].length;
 
       // Scope is decided HERE, per occurrence, from the enclosing node.
-      const scope = scopeAt(ranges, keyStart);
-      if (scope === undefined || !scopeMatches(entry, scope)) continue;
+      const scopeRange = scopeRangeAt(ranges, keyStart);
+      const scope = scopeRange?.typeKey;
+      if (scope === undefined || scopeRange === undefined || !scopeMatches(entry, scope)) continue;
 
       const line = lineAt(source, keyStart);
       const span = valueSpan(source, afterKey);
@@ -325,8 +433,18 @@ export function rewriteDocument(source: string, opts: RewriteOpts = {}): Rewrite
       const rw = entry.rewrite;
       if (rw === undefined) refuse();
       else if (rw.kind === "renameAttr") {
-        edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.to}"` });
-        changes.push({ attr, from: attr, to: rw.to, line });
+        // A rename onto a key the node ALREADY declares would emit a duplicate — two
+        // `"@counterexample"` members in one object, where JSON parsers silently take
+        // the last and the author's surviving text is the one that loses. Refuse
+        // instead: which of the two sentences is the real one is exactly the judgement
+        // `meta upgrade` does not make.
+        const target = ownKeys(source, ranges, scopeRange, rw.to)
+          .filter((k) => k.keyStart !== keyStart);
+        if (target.length > 0) refuse();
+        else {
+          edits.push({ start: keyStart, end: keyEnd, text: `"@${rw.to}"` });
+          changes.push({ attr, from: attr, to: rw.to, line });
+        }
       } else if (rw.kind === "dropAttr") drop();
       else if (span === undefined) continue;
       else if (rawEquals(span.raw, rw.fromValue)) {