@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.1

package/src/loader/validation-passes.ts

@@ -13,7 +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 { ParseError } from "../errors.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 +32,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 +61,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 +84,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,
@@ -441,6 +444,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 +478,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 +649,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 +676,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 +778,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 +1029,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 +1146,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 +1167,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 +1190,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 +1203,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 +1217,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 },
         ),
       );
     }
@@ -1109,8 +1247,8 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
       for (const origin of field.ownChildren().filter((c) => c.type === TYPE_ORIGIN)) {
         // #210 — assembly origins live on projections. A value-hosted field may
-        // not carry origin.aggregate / origin.computed / origin.collection /
-        // origin.first: a value is constructed — by a caller or by embedding —
+        // not carry origin.aggregate / origin.computed / origin.first:
+        // a value is constructed — by a caller or by embedding —
         // never assembled from a backing store. origin.passthrough STAYS legal
         // on a value (FR-015 parameter lineage; the B5 exemption below).
         if (
@@ -1156,9 +1294,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 +1381,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 +1484,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 +1579,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 +2097,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 +2133,77 @@ 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.
+      if (hasFieldsAttr && hasExpr) {
         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 },
+            `${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}.)`,
+            { 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 },
             ),
           );
         }
@@ -1997,7 +2270,7 @@ function checkFilterClauses(
 //   - a plain (extends-bound / no-origin) or origin.passthrough or origin.computed
 //     field → addressable (a base/joined column, or an inlined row-level expression).
 //   - an aggregate-derived field (origin.aggregate — count/sum/…/any/all/collect —
-//     or origin.first / origin.collection) → NOT addressable: a WHERE runs before
+//     or origin.first) → NOT addressable: a WHERE runs before
 //     aggregation, so it cannot see an aggregate (post-aggregate filtering is HAVING,
 //     a separate later extension). Fail-closed → ERR_BAD_ATTR_FILTER.
 //   - a ref naming no declared field → dangling → ERR_BAD_ATTR_FILTER.

package/src/naming-refs.ts

@@ -37,7 +37,6 @@ import {
   ORIGIN_PASSTHROUGH_ATTR_VIA,
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
-  ORIGIN_COLLECTION_ATTR_VIA,
 } from "./persistence/origin/origin-constants.js";
 import { SOURCE_ATTR_PARAMETER_REF } from "./persistence/source/source-constants.js";
 import { TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF } from "./template/template-constants.js";
@@ -63,10 +62,9 @@ export const REF_BEARING_ATTR_NAMES: ReadonlySet<string> = new Set<string>([
   RELATIONSHIP_ATTR_THROUGH, // ADR-0042: the M:N junction ref joins the desugar+resolution set.
   IDENTITY_REFERENCE_ATTR_REFERENCES,
   ORIGIN_PASSTHROUGH_ATTR_FROM,
-  ORIGIN_PASSTHROUGH_ATTR_VIA, // = ORIGIN_AGGREGATE_ATTR_VIA = ORIGIN_COLLECTION_ATTR_VIA ("via")
+  ORIGIN_PASSTHROUGH_ATTR_VIA, // = ORIGIN_AGGREGATE_ATTR_VIA ("via")
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
-  ORIGIN_COLLECTION_ATTR_VIA,
   SOURCE_ATTR_PARAMETER_REF,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_RESPONSE_REF,

package/src/parser-core.ts

@@ -29,9 +29,16 @@ 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 { resolveSuperRef, isChildTargetingRef } from "./super-resolve.js";
+import {
+  resolveSuperRef,
+  isChildTargetingRef,
+  extendsTargetCompatible,
+  EXTENDS_TARGET_MISMATCH_RULE,
+} from "./super-resolve.js";
 import { JsonPathBuilder } from "./json-path.js";
 import { getYamlPosition, type YamlPosition } from "./core/yaml-positions.js";
 import {
@@ -422,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 },
       );
     }
@@ -607,12 +619,18 @@ function parseNodeFresh(
       // FR-024 — a dotted child-targeting ref must resolve to a node of the
       // SAME type and subtype as the extending node. Dotted-only check; the
       // shipped top-level extends behavior is unchanged.
+      //
+      // The predicate is IMPORTED, not restated: this eager path and
+      // super-resolve's deferred path are two doors onto one rule, and they
+      // previously held independent copies of the boolean — so #310's relaxation
+      // applied to one would have left the other refusing, on whichever path a
+      // given loader configuration happens to take.
       if (
         isChildTargetingRef(model.superRef) &&
-        (superModel.type !== model.type || superModel.subType !== model.subType)
+        !extendsTargetCompatible(model, superModel)
       ) {
         throw new ParseError(
-          `the extends target '${model.superRef}' is ${superModel.type}.${superModel.subType} but the extending node '${model.fqn()}' is ${model.type}.${model.subType} — a dotted extends must target a node of the same type and subtype`,
+          `the extends target '${model.superRef}' is ${superModel.type}.${superModel.subType} but the extending node '${model.fqn()}' is ${model.type}.${model.subType} — ${EXTENDS_TARGET_MISMATCH_RULE}`,
           {
             code: "ERR_EXTENDS_TARGET_MISMATCH",
             source: resolvedSource(errSource(), model.fqn(), model.superRef),
@@ -1253,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() },
           ),
         );