@metaobjectsdev/metadata 0.24.0 → 0.24.2

package/src/loader/validation-passes.ts

@@ -13,7 +13,8 @@
 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 { ParseError } from "../errors.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";
 import { resolvedSource, type ErrorSource } from "../source.js";
@@ -32,6 +33,8 @@ import {
   INDEX_SUBTYPE_LOOKUP,
   INDEX_ATTR_FIELDS,
 } from "../core/index/index-constants.js";
+import { IDENTITY_SUBTYPE_SECONDARY } from "../core/identity/identity-constants.js";
+import type { MetaIdentity } from "../core/identity/meta-identity.js";
 import { MetaIndex } from "../core/index/meta-index.js";
 import {
   TEMPLATE_ATTR_PAYLOAD_REF,
@@ -59,6 +62,7 @@ import {
 } from "../presentation/layout/layout-constants.js";
 import {
   FIELD_ATTR_FILTERABLE,
+  FIELD_ATTR_SORTABLE,
   FIELD_ATTR_OBJECT_REF,
   FIELD_ATTR_STORAGE,
   STORAGE_FLATTENED,
@@ -81,7 +85,7 @@ import {
   FIELD_SUBTYPE_TIMESTAMP,
   FIELD_SUBTYPE_UUID,
 } from "../core/field/field-constants.js";
-import { FIELD_ATTR_DB_INDEXED } from "../persistence/db/db-constants.js";
+import { FIELD_ATTR_DB_INDEXED, IDENTITY_ATTR_EXPR } from "../persistence/db/db-constants.js";
 import {
   IDENTITY_ATTR_FIELDS,
   IDENTITY_SUBTYPE_REFERENCE,
@@ -132,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
@@ -441,6 +452,26 @@ export function validateFilterableHasSupportedOps(root: MetaData): ParseError[]
     for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
       // ADR-0039: resolving — a concrete field may inherit @filterable via extends.
       if (field.attr(FIELD_ATTR_FILTERABLE) !== true) continue;
+
+      // #335 Half B — an ARRAY field has no operator band either. Every FR-009
+      // operator (eq/ne/gt/gte/lt/lte/in/like/isNull) is a scalar comparison;
+      // none applies to a collection column. The allowlist template does not
+      // consult isArray and falls through to the "string" band, so this
+      // previously emitted a `like` rule against a text[] column — SQL that
+      // cannot execute. Same reason as the subtype check below, so same code.
+      // ADR-0039: resolvedIsArray(), never the own `isArray` flag.
+      if (field.resolvedIsArray()) {
+        errors.push(
+          new ParseError(
+            `Field "${obj.name}.${field.name}" has @filterable: true but is an array ` +
+              `(isArray: true). No filter operator applies to a collection column. ` +
+              `Remove @filterable from this field.`,
+            { code: "ERR_FILTERABLE_UNSUPPORTED_SUBTYPE", source: field.source },
+          ),
+        );
+        continue;
+      }
+
       if (opsForSubType(field.subType).length > 0) continue;
       errors.push(
         new ParseError(
@@ -455,6 +486,40 @@ export function validateFilterableHasSupportedOps(root: MetaData): ParseError[]
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// @sortable on a subtype or shape that cannot be ordered (#335 Half B)
+// ---------------------------------------------------------------------------
+// @sortable defaults FROM @filterable, so it is independently set only when
+// explicit — and nothing validated it, while @filterable has had a hard error
+// since SP-H Unit9. A @sortable JSON or array column emits a sort entry over a
+// column no dialect can ORDER BY meaningfully. → ERR_SORTABLE_UNSUPPORTED_SUBTYPE.
+
+export function validateSortableHasSupportedSubtype(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  // ADR-0039: root has no super; children()==ownChildren() but resolving is the default.
+  for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
+    // children() — inherited @sortable fields (via extends:/super:) are visible.
+    for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
+      // ADR-0039: resolving — a concrete field may inherit @sortable via extends.
+      if (field.attr(FIELD_ATTR_SORTABLE) !== true) continue;
+      // ADR-0039: resolvedIsArray(), never the own `isArray` flag.
+      const isArray = field.resolvedIsArray();
+      if (!isArray && opsForSubType(field.subType).length > 0) continue;
+      errors.push(
+        new ParseError(
+          `Field "${obj.name}.${field.name}" has @sortable: true but ` +
+            (isArray
+              ? `is an array (isArray: true) — a collection column has no ordering.`
+              : `its subtype "${field.subType}" cannot be ordered.`) +
+            ` Remove @sortable from this field.`,
+          { code: "ERR_SORTABLE_UNSUPPORTED_SUBTYPE", source: field.source },
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
 // ---------------------------------------------------------------------------
 // Origin path validation
 //
@@ -592,10 +657,25 @@ function _validateFromPath(
   return { entity: sourceObj, field: sourceField };
 }
 
+/** A fully-walked `@via` path: the relationship hop nodes in path order, and
+ *  the TERMINAL entity reached after the last hop. Both fall out of one walk,
+ *  so they are returned together — recovering the terminal with a second walk
+ *  means maintaining a second copy of the ADR-0042 package-resolution rule.
+ *  Shape mirrors `_validateFromPath`'s `ResolvedFromTarget`, which returns a
+ *  pair for the same reason. */
+interface WalkedViaPath {
+  hops: MetaData[];
+  terminal: MetaData;
+}
+
 /**
- * Validate an explicit `@via` "Entity.rel[.rel...]" path. Returns the walked
- * relationship hop nodes (in path order) on full success — FR-024 B5 runs the
- * cardinality checks over them — or undefined when any error was pushed.
+ * Validate an explicit `@via` "Entity.rel[.rel...]" path. On full success
+ * returns the walked relationship hop nodes (in path order) — FR-024 B5 runs
+ * the cardinality checks over them — together with the terminal entity node
+ * (#335: a whole-object `@agg:collect` has no `@of` entity, so `@orderBy` keys
+ * and value-object members resolve against the terminal instead). Returns
+ * undefined when any error was pushed, so `terminal` is defined exactly when
+ * `hops` is.
  */
 function _validateViaPath(
   viaAttr: string,
@@ -604,7 +684,7 @@ function _validateViaPath(
   fieldName: string,
   originSource: ErrorSource,
   errors: ParseError[],
-): MetaData[] | undefined {
+): WalkedViaPath | undefined {
   const projectionName = projection.name;
   // FR5d — referrer is `<projection-FQN>::<fieldName>`.
   const referrer = `${projection.fqn()}::${fieldName}`;
@@ -706,7 +786,8 @@ function _validateViaPath(
     hops.push(rel);
     currentObj = nextObj;
   }
-  return hops;
+  // currentObj is the terminal: every earlier exit returned undefined.
+  return { hops, terminal: currentObj };
 }
 
 // ---------------------------------------------------------------------------
@@ -956,6 +1037,58 @@ function _checkAggregateCardinality(
   }
 }
 
+/**
+ * #335 — a whole-object `@agg:collect` projects EXACTLY the declared value
+ * object's members, each matched by NAME against the `@via` terminal entity.
+ *
+ * Two rules, both fail-closed:
+ *  - a member with no matching field on the terminal is unresolvable. Failing
+ *    OPEN here is how #270 turned a curated value object into the full entity,
+ *    invisible in a diff because the metadata still read as curated.
+ *  - a matched member must agree on BOTH type axes (#185 type-preserving
+ *    doctrine), so a scalar member cannot bind an array field or vice versa.
+ *
+ * Both refusals carry a whole-object-specific code — ERR_COLLECT_MEMBER_UNRESOLVED
+ * for the unmatched member, ERR_COLLECT_WHOLE_OBJECT for the type disagreement.
+ * The latter is deliberately NOT the scalar arm's ERR_INVALID_ORIGIN: a loader
+ * that still requires @of rejects this metadata with ERR_INVALID_ORIGIN too, so
+ * sharing the code would make a corpus fixture pass on a port that implements
+ * nothing (the corpus compares only code + source, never message text).
+ */
+function _checkCollectMembers(
+  refTarget: MetaData,
+  terminal: MetaData,
+  obj: MetaData,
+  field: MetaData,
+  src: ErrorSource,
+  errors: ParseError[],
+): void {
+  // ADR-0039: resolving — a value object may inherit members via extends, and
+  // the terminal entity may inherit fields; own-only would silently skip
+  // inherited members, which is exactly the #270 bug class this guards.
+  const terminalFields = terminal.children().filter((c) => c.type === TYPE_FIELD);
+  for (const member of refTarget.children().filter((c) => c.type === TYPE_FIELD)) {
+    const match = terminalFields.find((f) => f.name === member.name);
+    if (match === undefined) {
+      errors.push(new ParseError(
+        `origin.aggregate @agg:collect on ${obj.name}.${field.name}: value-object member ` +
+          `'${member.name}' has no matching field on '${terminal.name}' — a whole-object ` +
+          `rollup projects exactly the declared members.`,
+        { code: "ERR_COLLECT_MEMBER_UNRESOLVED", source: src }));
+      continue;
+    }
+    const memberLabel = _typeLabel(member);
+    const matchLabel = _typeLabel(match);
+    if (memberLabel !== matchLabel) {
+      errors.push(new ParseError(
+        `origin.aggregate @agg:collect on ${obj.name}.${field.name}: value-object member ` +
+          `'${member.name}' is ${memberLabel} but '${terminal.name}.${match.name}' ` +
+          `is ${matchLabel} — a whole-object rollup preserves each member's type.`,
+        { code: "ERR_COLLECT_WHOLE_OBJECT", source: src }));
+    }
+  }
+}
+
 /**
  * FR-024 B6 (spec §4; ADR-0029 decision 7) — extends/origin agreement.
  *
@@ -1021,6 +1154,17 @@ function _checkExtendsOriginAgreement(
  * FR-015 stored-proc parameter refs the retired ERR_PARAMETER_REF_PASSTHROUGH_
  * TYPE_MISMATCH used to cover).
  */
+/**
+ * Both type axes in one comparable token. Subtype names never contain "[]", so
+ * equal labels ⇔ same subType AND same array-ness. Nullability is deliberately
+ * NOT judged — an outer-join view legitimately widens NOT NULL.
+ * ADR-0039: resolvedIsArray(), never the own `isArray` flag — a field may
+ * inherit its array-ness via extends.
+ */
+function _typeLabel(field: MetaData): string {
+  return `field.${field.subType}${field.resolvedIsArray() ? "[]" : ""}`;
+}
+
 function _checkPassthroughType(
   field: MetaData,
   fromField: MetaData,
@@ -1031,11 +1175,8 @@ function _checkPassthroughType(
   errors: ParseError[],
 ): void {
   if (convert) return; // deliberate type change acknowledged
-  // Compare both axes at once via the type-label: subtype names never contain
-  // "[]", so equal labels ⇔ same subType AND same array-ness (nullability is
-  // deliberately not judged — an outer-join view legitimately widens NOT NULL).
-  const declared = `field.${field.subType}${field.resolvedIsArray() ? "[]" : ""}`;
-  const source = `field.${fromField.subType}${fromField.resolvedIsArray() ? "[]" : ""}`;
+  const declared = _typeLabel(field);
+  const source = _typeLabel(fromField);
   if (declared === source) return;
   errors.push(
     new ParseError(
@@ -1057,6 +1198,10 @@ function _checkPassthroughType(
  * and carries no vocabulary. Shared by `@agg:collect` (element order) and
  * `origin.first` (row selection). A missing related entity means a prior error
  * already fired — skip silently.
+ *
+ * `code` lets the whole-object `@agg:collect` arm report ERR_COLLECT_WHOLE_OBJECT
+ * instead; it defaults to ERR_INVALID_ORIGIN so the scalar `@of` and `origin.first`
+ * call sites keep their existing envelope byte-for-byte.
  */
 function _validateOrderByKeys(
   orderBy: unknown,
@@ -1066,6 +1211,7 @@ function _validateOrderByKeys(
   label: string,
   originSource: ErrorSource,
   errors: ParseError[],
+  code: ErrorCode = "ERR_INVALID_ORIGIN",
 ): void {
   if (!Array.isArray(orderBy) || relatedEntity === undefined) return;
   for (const raw of orderBy) {
@@ -1079,14 +1225,14 @@ function _validateOrderByKeys(
       errors.push(
         new ParseError(
           `${label} on ${obj.name}.${fieldName}: @orderBy key "${raw}" — no such field "${key}" on ${relatedEntity.name}.`,
-          { code: "ERR_INVALID_ORIGIN", source: originSource },
+          { code, source: originSource },
         ),
       );
     } else if (dir !== undefined && !(SORT_ORDER_VALUES as readonly string[]).includes(dir)) {
       errors.push(
         new ParseError(
           `${label} on ${obj.name}.${fieldName}: @orderBy key "${raw}" — direction must be one of ${SORT_ORDER_VALUES.join("|")}.`,
-          { code: "ERR_INVALID_ORIGIN", source: originSource },
+          { code, source: originSource },
         ),
       );
     }
@@ -1156,9 +1302,9 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
           // ADR-0039: own — origin.* never inherits (ADR-0029).
           const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            const hops = _validateViaPath(via, root, obj, field.name, origin.source, errors);
-            if (hops !== undefined) {
-              _checkPassthroughCardinality(hops, obj, field.name, origin.source, errors);
+            const walked = _validateViaPath(via, root, obj, field.name, origin.source, errors);
+            if (walked !== undefined) {
+              _checkPassthroughCardinality(walked.hops, obj, field.name, origin.source, errors);
             }
           } else if (fromTarget !== undefined && !isValueHost) {
             // FR-024 §6 — no @via: derive the base entity; a @from targeting
@@ -1243,17 +1389,89 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
                 `origin.aggregate @agg:${String(agg)} on ${obj.name}.${field.name}: requires an explicit @via (a quantifier has no @of to infer the path from).`,
                 { code: "ERR_INVALID_ORIGIN", source: src }));
             } else {
-              const hops = _validateViaPath(via, root, obj, field.name, src, errors);
-              if (hops !== undefined) _checkAggregateCardinality(hops, obj, field.name, src, errors);
+              const walked = _validateViaPath(via, root, obj, field.name, src, errors);
+              if (walked !== undefined) _checkAggregateCardinality(walked.hops, obj, field.name, src, errors);
             }
             continue;
           }
 
-          // --- count/sum/avg/min/max/collect: @of REQUIRED ---
+          // --- @of: REQUIRED for count/sum/avg/min/max; OPTIONAL for collect ---
+          // #335 — an @of-absent collect is a WHOLE-OBJECT rollup: collect the
+          // related rows as an array of the field's declared @objectRef value
+          // object rather than an array of one scalar column.
           if (!ofPresent) {
-            errors.push(new ParseError(
-              `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
-              { code: "ERR_INVALID_ORIGIN", source: src }));
+            if (!isCollect) {
+              errors.push(new ParseError(
+                `origin.aggregate on ${obj.name}.${field.name}: missing @of.`,
+                { code: "ERR_INVALID_ORIGIN", source: src }));
+              continue;
+            }
+            // Whole-object rollup. The carrying field must be a field.object
+            // naming a value object, and @via must be explicit (there is no @of
+            // entity to infer the single-hop relation from).
+            // ADR-0039: resolving — @objectRef may be inherited via extends.
+            const objectRef = field.attr(FIELD_ATTR_OBJECT_REF);
+            if (field.subType !== FIELD_SUBTYPE_OBJECT || typeof objectRef !== "string" || objectRef === "") {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:collect on ${obj.name}.${field.name}: @of is omitted, so this is a ` +
+                  `whole-object rollup — the carrying field must be a field.object declaring @objectRef ` +
+                  `(add @of to collect a single column instead).`,
+                { code: "ERR_COLLECT_WHOLE_OBJECT", source: src }));
+              continue;
+            }
+            // #210's value-only rule is PAYLOAD-scoped and never reaches a
+            // projection-hosted field, so this branch enforces it itself.
+            // Without it an @objectRef to an entity silently rolls up the FULL
+            // entity — the #270 shape, this time baked into DDL.
+            // ADR-0042 — a bare @objectRef resolves in the DECLARING owner's
+            // package (an inherited field resolves in the package that
+            // declared it) — same rule _checkNestedPayloadRefsValueOnly uses.
+            const refOwner = field.parent ?? obj;
+            const refPkg = refOwner.package ?? refOwner.fileDefaultPackage ?? "";
+            const refTarget = resolveObjectRef(root, objectRef, refPkg).node;
+            if (refTarget !== undefined && refTarget.subType !== OBJECT_SUBTYPE_VALUE) {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:collect on ${obj.name}.${field.name}: @objectRef '${objectRef}' ` +
+                  `resolves to ${TYPE_OBJECT}.${refTarget.subType} — a whole-object rollup must target an ` +
+                  `object.value (#210, ADR-0028).`,
+                { code: "ERR_SUBTYPE_RULE_VIOLATION", source: src }));
+              continue;
+            }
+            // ADR-0039: own — origin.* never inherits (ADR-0029).
+            const viaAttr = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
+            if (typeof viaAttr !== "string" || viaAttr === "") {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:collect on ${obj.name}.${field.name}: @via is required on a ` +
+                  `whole-object rollup — there is no @of entity to infer the relationship from.`,
+                { code: "ERR_COLLECT_WHOLE_OBJECT", source: src }));
+              continue;
+            }
+            // @distinct is refused on the object form. It is NOT an engine limit
+            // (both engines dedupe JSON objects); it is a guaranteed no-op
+            // whenever the value object carries the entity's primary key, which
+            // is the common case, and a silent no-op is worse than a refusal.
+            if (hasDistinct) {
+              errors.push(new ParseError(
+                `origin.aggregate @agg:collect on ${obj.name}.${field.name}: @distinct is not supported on a ` +
+                  `whole-object rollup (it is a no-op whenever the value object carries the primary key).`,
+                { code: "ERR_COLLECT_WHOLE_OBJECT", source: src }));
+              continue;
+            }
+            // One walk yields both the hops (cardinality) and the terminal
+            // entity (@orderBy keys, member resolution). An invalid @via
+            // (e.g. single-segment "A") returns undefined having already
+            // pushed its own error, so everything downstream is skipped and
+            // no second, misleadingly-scoped error is emitted.
+            const via = _validateViaPath(viaAttr, root, obj, field.name, src, errors);
+            if (via !== undefined) {
+              _checkAggregateCardinality(via.hops, obj, field.name, src, errors);
+              // @orderBy keys resolve against the @via TERMINAL entity, not @of.
+              _validateOrderByKeys(orderBy, via.terminal, obj, field.name, "origin.aggregate @agg:collect", src, errors,
+                "ERR_COLLECT_WHOLE_OBJECT");
+              if (refTarget !== undefined) {
+                _checkCollectMembers(refTarget, via.terminal, obj, field, src, errors);
+              }
+            }
             continue;
           }
           // NOTE (FR-024 B6): NO extends/origin agreement check on aggregates —
@@ -1274,9 +1492,9 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
           // ADR-0039: own — origin.* never inherits (ADR-0029).
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            const hops = _validateViaPath(via, root, obj, field.name, src, errors);
-            if (hops !== undefined) {
-              _checkAggregateCardinality(hops, obj, field.name, src, errors);
+            const walked = _validateViaPath(via, root, obj, field.name, src, errors);
+            if (walked !== undefined) {
+              _checkAggregateCardinality(walked.hops, obj, field.name, src, errors);
             }
             continue;
           }
@@ -1369,8 +1587,8 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
           // @via — explicit (validated + cardinality) or single-hop-unique inferred.
           const via = origin.ownAttr(ORIGIN_FIRST_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            const hops = _validateViaPath(via, root, obj, field.name, src, errors);
-            if (hops !== undefined) _checkAggregateCardinality(hops, obj, field.name, src, errors);
+            const walked = _validateViaPath(via, root, obj, field.name, src, errors);
+            if (walked !== undefined) _checkAggregateCardinality(walked.hops, obj, field.name, src, errors);
           } else if (ofTarget !== undefined) {
             // (A value host never reaches here — the #210 assembly-origin
             // check above already rejected origin.first on a value.)
@@ -1887,12 +2105,32 @@ export function validateRelationships(root: MetaData): ParseError[] {
 // (defaultValidationRegistry → a declarative reference descriptor with dottedFieldPath).
 
 // ---------------------------------------------------------------------------
-// index.lookup @fields resolution (Task 3)
+// Index-key resolution for index.lookup AND identity.secondary (#342)
+//
+// An index declares its key EXACTLY ONE of two ways: plain columns (@fields) or
+// a key expression (@expr, e.g. `lower(email)` / `(payload->>'device_id')`).
+// The registry has always said so — @expr is described as "Used INSTEAD of
+// @fields" — and `migrate-ts` has always implemented it that way
+// (`columns: expr ? [] : cols`, expected-schema.ts). Only the LOADER disagreed,
+// requiring @fields unconditionally, which made an expression index
+// unreachable: omitting @fields failed to load, and the one spelling that DID
+// load (@fields AND @expr) had its @fields silently discarded by the engine.
+//
+// So the two rules below are one rule — the key is @fields XOR @expr:
+//   - NEITHER: nothing declares the key.
+//   - BOTH: contradictory, and previously half-honored. Rejected rather than
+//     given a precedence rule, because an accepted-but-half-ignored declaration
+//     is exactly the silent-wrong-output the sealed strict registry exists to
+//     prevent (cf. ERR_SQL_BODY_WITH_UNMANAGED — @sql vs @unmanaged is the same
+//     "two mutually exclusive non-default states of one axis" shape).
+//
+// Applies to identity.secondary too: per ADR-0040 uniqueness lives in the TYPE,
+// so identity.secondary IS a unique index and keys itself identically. Both
+// carry @expr from the same db provider, and migrate-ts branches on @expr for
+// both — the loader was the only tier treating them differently.
 //
-// Every index.lookup on an entity must name at least one field, and every
-// named field must exist in the entity's EFFECTIVE (resolved) field set.
-// ADR-0039: use children() / MetaIndex.fields() — never own* — so that a
-// field inherited via extends still resolves correctly.
+// ADR-0039: children() / MetaIndex.fields() — never own* — so a field inherited
+// via extends still resolves.
 // ---------------------------------------------------------------------------
 
 export function validateIndexLookupFields(root: MetaData): ParseError[] {
@@ -1903,34 +2141,87 @@ export function validateIndexLookupFields(root: MetaData): ParseError[] {
     const effectiveFieldNames = new Set(
       obj.children().filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
     );
-    for (const node of obj.children().filter(
-      (c) => c.type === TYPE_INDEX && c.subType === INDEX_SUBTYPE_LOOKUP,
-    )) {
-      // MetaIndex.fields() uses the resolving attr() accessor per ADR-0039.
-      const idx = node as MetaIndex;
-      const fields = idx.fields();
-
-      // Rule 1: must have at least one field.
-      if (fields.length === 0) {
+    const keyed = obj.children().filter(
+      (c) =>
+        (c.type === TYPE_INDEX && c.subType === INDEX_SUBTYPE_LOOKUP) ||
+        (c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_SECONDARY),
+    );
+    for (const node of keyed) {
+      const label = `${node.type}.${node.subType}`;
+      // PRESENCE vs CONTENT are two different questions here, and conflating them
+      // is a bug in both directions:
+      //
+      //   - The CONTRADICTION check needs PRESENCE. `@fields: []` alongside @expr
+      //     is still a declaration of both, and keying it on non-emptiness let the
+      //     total-discard spelling load clean while `@fields: ["x"]` + @expr was
+      //     refused — the rule missing exactly the case it exists to catch.
+      //   - The KEY-RESOLUTION check needs normalized CONTENT, via the guarded
+      //     accessor. Reading the raw attr with a cast meant a scalar `@fields: 5`
+      //     threw an uncaught TypeError out of load() in TS while the other three
+      //     ports reported a clean error.
+      //
+      // The guarded accessor is the fix for the second and the OBSTACLE for the
+      // first — it collapses absent, scalar and explicit `[]` to the same `[]` —
+      // so the two questions are asked separately and never routed through one
+      // predicate. ADR-0039: both reads resolve through extends.
+      const hasFieldsAttr = node.attr(IDENTITY_ATTR_FIELDS) !== undefined;
+      // MetaIndex.fields() / MetaIdentity.fields are the same guarded read
+      // (`Array.isArray(f) ? f : []`); never re-hand-roll it.
+      const fields =
+        node instanceof MetaIndex ? node.fields() : (node as MetaIdentity).fields;
+      const exprRaw = node.attr(IDENTITY_ATTR_EXPR);
+      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(
-            `index.lookup "${idx.name}" on "${obj.name}" has no @${INDEX_ATTR_FIELDS}; ` +
-              `at least one field is required`,
-            { code: "ERR_INVALID_INDEX", source: idx.source },
+            // 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}: ` +
+              (contradiction === undefined
+                ? `@${IDENTITY_ATTR_EXPR} is used INSTEAD of @${INDEX_ATTR_FIELDS} — drop one.`
+                : contradictionHint(contradiction)),
+            { code: "ERR_INVALID_INDEX", source: node.source },
           ),
         );
         continue;
       }
 
+      // Rule 1b: whichever is declared must actually supply a key.
+      if (fields.length === 0 && !hasExpr) {
+        errors.push(
+          new ParseError(
+            `${label} "${node.name}" on "${obj.name}" declares no key: ` +
+              `it must have @${INDEX_ATTR_FIELDS} (one or more columns) or ` +
+              `@${IDENTITY_ATTR_EXPR} (a key expression)`,
+            { code: "ERR_INVALID_INDEX", source: node.source },
+          ),
+        );
+        continue;
+      }
       // Rule 2: every named field must resolve against the entity's effective field set.
+      // An expression index has no @fields to resolve — @expr is raw SQL over the
+      // physical columns, deliberately not parsed here (ADR-0023 keeps the grammar
+      // closed only where the loader owns it).
       for (const fieldName of fields) {
         if (!effectiveFieldNames.has(fieldName)) {
           errors.push(
             new ParseError(
-              `index.lookup "${idx.name}" on "${obj.name}" references field "${fieldName}" ` +
+              `${label} "${node.name}" on "${obj.name}" references field "${fieldName}" ` +
                 `which does not exist on "${obj.name}". ` +
                 `Available fields: ${[...effectiveFieldNames].join(", ") || "(none)"}`,
-              { code: "ERR_INVALID_INDEX", source: idx.source },
+              { code: "ERR_INVALID_INDEX", source: node.source },
             ),
           );
         }
@@ -2119,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;
+}