@metaobjectsdev/metadata 0.24.0-rc.1 → 0.24.1

package/dist/loader/validation-passes.js

@@ -15,13 +15,14 @@ import { PACKAGE_SEPARATOR, CHILD_REF_SEPARATOR } from "../shared/structural.js"
 import { resolvedSource } from "../source.js";
 import { TYPE_OBJECT, TYPE_FIELD, TYPE_LAYOUT, TYPE_IDENTITY, TYPE_ORIGIN, TYPE_RELATIONSHIP, TYPE_SOURCE, TYPE_TEMPLATE, TYPE_INDEX, } from "../shared/base-types.js";
 import { INDEX_SUBTYPE_LOOKUP, INDEX_ATTR_FIELDS, } from "../core/index/index-constants.js";
+import { IDENTITY_SUBTYPE_SECONDARY } from "../core/identity/identity-constants.js";
 import { MetaIndex } from "../core/index/meta-index.js";
 import { TEMPLATE_ATTR_PAYLOAD_REF, TEMPLATE_ATTR_RESPONSE_REF, TEMPLATE_ATTR_REQUIRED_SLOTS, TEMPLATE_ATTR_TEXT_REF, TEMPLATE_ATTR_KIND, TEMPLATE_KIND_EMAIL, TEMPLATE_ATTR_SUBJECT_REF, TEMPLATE_ATTR_HTML_BODY_REF, TEMPLATE_SUBTYPE_OUTPUT, TEMPLATE_SUBTYPE_PROMPT, } from "../template/template-constants.js";
 import { OBJECT_SUBTYPE_ENTITY, OBJECT_SUBTYPE_VALUE, OBJECT_SUBTYPE_PROJECTION, OBJECT_PROJECTION_ATTR_FILTER, } from "../core/object/object-constants.js";
 import { MetaSource } from "../persistence/source/meta-source.js";
 import { LAYOUT_SUBTYPE_DATA_GRID, LAYOUT_DATA_GRID_ATTR_DEFAULT_SORT_FIELD, LAYOUT_DATA_GRID_ATTR_FILTER, } from "../presentation/layout/layout-constants.js";
-import { FIELD_ATTR_FILTERABLE, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_STORAGE, STORAGE_FLATTENED, FIELD_ATTR_DEFAULT, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL, FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT, FIELD_SUBTYPE_MAP, FIELD_ATTR_REQUIRED, FIELD_ATTR_VALUE_TYPE, FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, 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_FILTERABLE, FIELD_ATTR_SORTABLE, FIELD_ATTR_OBJECT_REF, FIELD_ATTR_STORAGE, STORAGE_FLATTENED, FIELD_ATTR_DEFAULT, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL, FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_ENUM, FIELD_SUBTYPE_OBJECT, FIELD_SUBTYPE_MAP, FIELD_ATTR_REQUIRED, FIELD_ATTR_VALUE_TYPE, FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_DATE, FIELD_SUBTYPE_TIME, FIELD_SUBTYPE_TIMESTAMP, FIELD_SUBTYPE_UUID, } from "../core/field/field-constants.js";
+import { FIELD_ATTR_DB_INDEXED, IDENTITY_ATTR_EXPR } from "../persistence/db/db-constants.js";
 import { IDENTITY_ATTR_FIELDS, IDENTITY_SUBTYPE_REFERENCE, IDENTITY_REFERENCE_ATTR_REFERENCES, } from "../core/identity/identity-constants.js";
 import { ORIGIN_SUBTYPE_PASSTHROUGH, ORIGIN_SUBTYPE_AGGREGATE, ORIGIN_SUBTYPE_COMPUTED, ORIGIN_SUBTYPE_FIRST, ORIGIN_PASSTHROUGH_ATTR_FROM, ORIGIN_PASSTHROUGH_ATTR_VIA, ORIGIN_PASSTHROUGH_ATTR_CONVERT, ORIGIN_AGGREGATE_ATTR_AGG, ORIGIN_AGGREGATE_ATTR_OF, ORIGIN_AGGREGATE_ATTR_VIA, ORIGIN_AGGREGATE_ATTR_FILTER, ORIGIN_ATTR_DISTINCT, ORIGIN_ATTR_ORDER_BY, ORIGIN_COMPUTED_ATTR_EXPR, ORIGIN_FIRST_ATTR_OF, ORIGIN_FIRST_ATTR_VIA, ORIGIN_FIRST_ATTR_FILTER, AGG_ANY, AGG_ALL, AGG_COLLECT, ASSEMBLY_ORIGIN_SUBTYPES, } from "../persistence/origin/origin-constants.js";
 import { inferExprType, validateExprNode, } from "../core/attr/meta-attr-expression.js";
@@ -287,6 +288,19 @@ export function validateFilterableHasSupportedOps(root) {
             // 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(`Field "${obj.name}.${field.name}" has @filterable: true but its subtype ` +
@@ -297,6 +311,35 @@ export function validateFilterableHasSupportedOps(root) {
     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) {
+    const errors = [];
+    // 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
 //
 // Walks every projection's fields, finds `origin` (TYPE_ORIGIN) children,
@@ -393,9 +436,13 @@ function _validateFromPath(fromAttr, root, projection, fieldName, originSource,
     return { entity: sourceObj, field: sourceField };
 }
 /**
- * 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, root, projection, fieldName, originSource, errors) {
     const projectionName = projection.name;
@@ -470,7 +517,8 @@ function _validateViaPath(viaAttr, root, projection, fieldName, originSource, er
         hops.push(rel);
         currentObj = nextObj;
     }
-    return hops;
+    // currentObj is the terminal: every earlier exit returned undefined.
+    return { hops, terminal: currentObj };
 }
 // ---------------------------------------------------------------------------
 // FR-024 B5 — base-entity derivation, single-hop-unique @via inference, and
@@ -663,6 +711,46 @@ function _checkAggregateCardinality(hops, obj, fieldName, originSource, errors)
             `aggregating over a to-one path — you meant passthrough (ADR-0029).`, { code: "ERR_ORIGIN_CARDINALITY", source: originSource }));
     }
 }
+/**
+ * #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, terminal, obj, field, src, errors) {
+    // 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.
  *
@@ -718,14 +806,21 @@ function _checkExtendsOriginAgreement(field, fromField, fromAttr, obj, originSou
  * 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) {
+    return `field.${field.subType}${field.resolvedIsArray() ? "[]" : ""}`;
+}
 function _checkPassthroughType(field, fromField, fromAttr, convert, obj, originSource, errors) {
     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(`origin.passthrough on ${obj.name}.${field.name}: field is ${declared} but its @from source ` +
@@ -742,8 +837,12 @@ function _checkPassthroughType(field, fromField, fromAttr, convert, obj, originS
  * 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, relatedEntity, obj, fieldName, label, originSource, errors) {
+function _validateOrderByKeys(orderBy, relatedEntity, obj, fieldName, label, originSource, errors, code = "ERR_INVALID_ORIGIN") {
     if (!Array.isArray(orderBy) || relatedEntity === undefined)
         return;
     for (const raw of orderBy) {
@@ -755,10 +854,10 @@ function _validateOrderByKeys(orderBy, relatedEntity, obj, fieldName, label, ori
         // ADR-0039: resolving — an ordering key may target an inherited field.
         const target = relatedEntity.children().find((f) => f.type === TYPE_FIELD && f.name === key);
         if (target === undefined) {
-            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 }));
+            errors.push(new ParseError(`${label} on ${obj.name}.${fieldName}: @orderBy key "${raw}" — no such field "${key}" on ${relatedEntity.name}.`, { code, source: originSource }));
         }
         else if (dir !== undefined && !SORT_ORDER_VALUES.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 }));
+            errors.push(new ParseError(`${label} on ${obj.name}.${fieldName}: @orderBy key "${raw}" — direction must be one of ${SORT_ORDER_VALUES.join("|")}.`, { code, source: originSource }));
         }
     }
 }
@@ -778,8 +877,8 @@ export function validateOriginPaths(root) {
         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 (isValueHost &&
@@ -813,9 +912,9 @@ export function validateOriginPaths(root) {
                     // 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) {
@@ -880,15 +979,78 @@ export function validateOriginPaths(root) {
                             errors.push(new 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 —
@@ -907,9 +1069,9 @@ export function validateOriginPaths(root) {
                     // 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;
                     }
@@ -987,9 +1149,9 @@ export function validateOriginPaths(root) {
                     // @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
@@ -1402,12 +1564,32 @@ export function validateRelationships(root) {
 // NOTE: identity.reference @references resolution moved to the validation registry
 // (defaultValidationRegistry → a declarative reference descriptor with dottedFieldPath).
 // ---------------------------------------------------------------------------
-// index.lookup @fields resolution (Task 3)
+// Index-key resolution for index.lookup AND identity.secondary (#342)
 //
-// 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.
+// 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.
+//
+// ADR-0039: children() / MetaIndex.fields() — never own* — so a field inherited
+// via extends still resolves.
 // ---------------------------------------------------------------------------
 export function validateIndexLookupFields(root) {
     const errors = [];
@@ -1415,22 +1597,58 @@ export function validateIndexLookupFields(root) {
     for (const obj of root.children().filter((c) => c.type === TYPE_OBJECT)) {
         // Effective (resolved) field names — includes inherited fields via extends.
         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;
-            const fields = idx.fields();
-            // Rule 1: must have at least one field.
-            if (fields.length === 0) {
-                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 }));
+        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.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(`${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}" ` +
+                    errors.push(new ParseError(`${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 }));
+                        `Available fields: ${[...effectiveFieldNames].join(", ") || "(none)"}`, { code: "ERR_INVALID_INDEX", source: node.source }));
                 }
             }
         }