@metaobjectsdev/metadata 0.9.0 → 0.10.0

package/src/loader/validation-passes.ts

@@ -4,13 +4,17 @@
 // warnings. No loader state is read or written — these are pure functions.
 //
 // Exported: validateDataGridSortFields, validateFilterableHasIndex,
-//           validateOriginPaths, validateDataGridFilterValues,
+//           validateOriginPaths, validateDerivedFieldProvidability,
+//           validateDataGridFilterValues,
 //           validateFieldObjectStorage  (called by MetaDataLoader.load() in order).
 // Private:  _findObject, _findField, _findRelationship,
 //           _validateFromPath, _validateViaPath  (helpers, not exported).
 
 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 { refMatchesObject } from "../naming-refs.js";
 import { resolvedSource, type ErrorSource } from "../source.js";
 import {
   TYPE_OBJECT,
@@ -19,10 +23,12 @@ import {
   TYPE_IDENTITY,
   TYPE_ORIGIN,
   TYPE_RELATIONSHIP,
+  TYPE_SOURCE,
   TYPE_TEMPLATE,
 } from "../shared/base-types.js";
 import {
   TEMPLATE_ATTR_PAYLOAD_REF,
+  TEMPLATE_ATTR_RESPONSE_REF,
   TEMPLATE_ATTR_REQUIRED_SLOTS,
   TEMPLATE_ATTR_TEXT_REF,
   TEMPLATE_ATTR_KIND,
@@ -32,7 +38,12 @@ import {
   TEMPLATE_SUBTYPE_OUTPUT,
   TEMPLATE_SUBTYPE_PROMPT,
 } from "../template/template-constants.js";
-import { OBJECT_SUBTYPE_VALUE } from "../core/object/object-constants.js";
+import {
+  OBJECT_SUBTYPE_ENTITY,
+  OBJECT_SUBTYPE_VALUE,
+  OBJECT_SUBTYPE_PROJECTION,
+} 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,
@@ -52,6 +63,7 @@ import {
   FIELD_SUBTYPE_DECIMAL,
   FIELD_SUBTYPE_BOOLEAN,
   FIELD_SUBTYPE_ENUM,
+  FIELD_SUBTYPE_OBJECT,
 } from "../core/field/field-constants.js";
 import { FIELD_ATTR_DB_INDEXED } from "../persistence/db/db-constants.js";
 import { IDENTITY_ATTR_FIELDS } from "../core/identity/identity-constants.js";
@@ -63,7 +75,16 @@ import {
   ORIGIN_AGGREGATE_ATTR_OF,
   ORIGIN_AGGREGATE_ATTR_VIA,
 } from "../persistence/origin/origin-constants.js";
-import { RELATIONSHIP_ATTR_OBJECT_REF } from "../core/relationship/relationship-constants.js";
+import {
+  RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_CARDINALITY,
+  RELATIONSHIP_ATTR_THROUGH,
+  RELATIONSHIP_ATTR_SOURCE_REF_FIELD,
+  RELATIONSHIP_ATTR_SYMMETRIC,
+  CARDINALITY_ONE,
+  CARDINALITY_MANY,
+} from "../core/relationship/relationship-constants.js";
+import { stripPackage } from "../naming.js";
 import {
   FILTER_COMPOSE_OR,
   FILTER_COMPOSE_AND,
@@ -110,9 +131,19 @@ export function validateDataGridSortFields(root: MetaData): ParseError[] {
 // `meta verify` step, not here.
 // ---------------------------------------------------------------------------
 
+/** Recursively collect all template.* nodes anywhere in the metadata tree. */
+function allTemplates(node: MetaData): MetaData[] {
+  const out: MetaData[] = [];
+  for (const c of node.ownChildren()) {
+    if (c.type === TYPE_TEMPLATE) out.push(c);
+    out.push(...allTemplates(c));
+  }
+  return out;
+}
+
 export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
-  for (const tmpl of root.ownChildren().filter((c) => c.type === TYPE_TEMPLATE)) {
+  for (const tmpl of allTemplates(root)) {
     // --- @kind / textRef / email part-ref cross-field rules ---
     // template.output is either a document (@kind absent/"document" → @textRef
     // required) or an email (@kind="email" → @subjectRef + @htmlBodyRef required,
@@ -165,7 +196,7 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
 
     const payloadRef = tmpl.ownAttr(TEMPLATE_ATTR_PAYLOAD_REF);
     if (typeof payloadRef !== "string") continue; // absence handled by the required-attr schema check
-    const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === payloadRef);
+    const payload = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, payloadRef));
     if (!payload || payload.subType !== OBJECT_SUBTYPE_VALUE) {
       // FR5d — @payloadRef is a reference; emit format=resolved with
       // referrer=template FQN, target=the unresolved payloadRef string.
@@ -180,6 +211,18 @@ export function validateTemplatePayloadRefs(root: MetaData): ParseError[] {
       );
       continue;
     }
+    const responseRef = tmpl.ownAttr(TEMPLATE_ATTR_RESPONSE_REF);
+    if (typeof responseRef === "string") {
+      const resVo = root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, responseRef));
+      if (!resVo || resVo.subType !== OBJECT_SUBTYPE_VALUE) {
+        errors.push(
+          new ParseError(
+            `template "${tmpl.name}" @responseRef "${responseRef}" does not resolve to an object.value at root`,
+            { code: "ERR_INVALID_TEMPLATE", source: resolvedSource(tmpl.source, tmpl.fqn(), responseRef) },
+          ),
+        );
+      }
+    }
     const fieldNames = new Set(
       payload.children().filter((c) => c.type === TYPE_FIELD).map((f) => f.name),
     );
@@ -242,6 +285,35 @@ export function validateFilterableHasIndex(root: MetaData): string[] {
   return warnings;
 }
 
+// ---------------------------------------------------------------------------
+// @filterable on a subtype with no operator band (SP-H Unit9)
+// ---------------------------------------------------------------------------
+// A field marked @filterable: true whose subtype has NO entry in OPS_BY_SUBTYPE
+// (e.g. field.object, or any extension subtype without a declared op band)
+// would silently generate a filter type/allowlist with an empty op set — a
+// filter route that rejects every request. Error early instead of shipping
+// broken codegen. → ERR_FILTERABLE_UNSUPPORTED_SUBTYPE.
+
+export function validateFilterableHasSupportedOps(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    // children() — inherited @filterable fields (via extends:/super:) are visible.
+    for (const field of obj.children().filter((c) => c.type === TYPE_FIELD)) {
+      if (field.ownAttr(FIELD_ATTR_FILTERABLE) !== true) continue;
+      if (opsForSubType(field.subType).length > 0) continue;
+      errors.push(
+        new ParseError(
+          `Field "${obj.name}.${field.name}" has @filterable: true but its subtype ` +
+            `"${field.subType}" has no filter-operator band. Remove @filterable, or use a ` +
+            `field subtype that supports filtering (string/enum/uuid/number/currency/date/boolean).`,
+          { code: "ERR_FILTERABLE_UNSUPPORTED_SUBTYPE", source: field.source },
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
 // ---------------------------------------------------------------------------
 // Origin path validation
 //
@@ -257,7 +329,9 @@ export function validateFilterableHasIndex(root: MetaData): string[] {
 // ---------------------------------------------------------------------------
 
 function _findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  // FR-032 — origin heads are FQN-qualified after the desugar/sweep; match on
+  // the effective FQN resolution key (with bare back-compat).
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 function _findField(obj: MetaData, name: string): MetaData | undefined {
@@ -270,6 +344,21 @@ function _findRelationship(obj: MetaData, name: string): MetaData | undefined {
   return obj.children().find((c) => c.type === TYPE_RELATIONSHIP && c.name === name);
 }
 
+/** Resolved `Entity.field` reference target: the entity AND the field node.
+ *  FR-024 B5 inference needs the entity; the B6 extends/origin agreement
+ *  check compares against the field node identity. */
+interface ResolvedFromTarget {
+  readonly entity: MetaData;
+  readonly field: MetaData;
+}
+
+/**
+ * Validate a passthrough `@from` / aggregate `@of` "Entity.field" reference.
+ * Returns the resolved target entity + field on full success (FR-024 B5 —
+ * the inference/cardinality stage needs the entity; B6 agreement needs the
+ * field), or undefined when any error was pushed (malformed shape / unknown
+ * entity / unknown field).
+ */
 function _validateFromPath(
   fromAttr: string,
   root: MetaData,
@@ -278,7 +367,7 @@ function _validateFromPath(
   originSource: ErrorSource,
   errors: ParseError[],
   label: string = "origin.passthrough.@from",
-): void {
+): ResolvedFromTarget | undefined {
   const projectionName = projection.name;
   // FR5d — referrer is `<projection-FQN>::<fieldName>` (the canonical
   // "where the broken reference lives" identifier).
@@ -297,7 +386,7 @@ function _validateFromPath(
         },
       ),
     );
-    return;
+    return undefined;
   }
   const entityName = fromAttr.slice(0, dotIdx);
   const targetFieldName = fromAttr.slice(dotIdx + 1);
@@ -313,7 +402,7 @@ function _validateFromPath(
         },
       ),
     );
-    return;
+    return undefined;
   }
   const sourceField = _findField(sourceObj, targetFieldName);
   if (!sourceField) {
@@ -327,9 +416,16 @@ function _validateFromPath(
         },
       ),
     );
+    return undefined;
   }
+  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.
+ */
 function _validateViaPath(
   viaAttr: string,
   root: MetaData,
@@ -337,7 +433,7 @@ function _validateViaPath(
   fieldName: string,
   originSource: ErrorSource,
   errors: ParseError[],
-): void {
+): MetaData[] | undefined {
   const projectionName = projection.name;
   // FR5d — referrer is `<projection-FQN>::<fieldName>`.
   const referrer = `${projection.fqn()}::${fieldName}`;
@@ -352,7 +448,7 @@ function _validateViaPath(
         },
       ),
     );
-    return;
+    return undefined;
   }
   const [entityName, ...relSegments] = segments as [string, ...string[]];
   let currentObj = _findObject(root, entityName);
@@ -366,7 +462,7 @@ function _validateViaPath(
         },
       ),
     );
-    return;
+    return undefined;
   }
   // FR5d — track the deepest-valid-prefix as we walk. The prefix grows
   // segment-by-segment; on a hop failure the error message names the prefix
@@ -374,6 +470,7 @@ function _validateViaPath(
   // After the entity lookup above, the deepest valid prefix is just the
   // entity name; each successful relationship hop appends a segment.
   const validSegments: string[] = [entityName];
+  const hops: MetaData[] = [];
   for (const relName of relSegments) {
     const rel = _findRelationship(currentObj, relName);
     if (!rel) {
@@ -388,7 +485,7 @@ function _validateViaPath(
           },
         ),
       );
-      return;
+      return undefined;
     }
     const refTarget = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
     if (typeof refTarget !== "string" || refTarget === "") {
@@ -401,7 +498,7 @@ function _validateViaPath(
           },
         ),
       );
-      return;
+      return undefined;
     }
     const nextObj = _findObject(root, refTarget);
     if (!nextObj) {
@@ -418,16 +515,302 @@ function _validateViaPath(
           },
         ),
       );
-      return;
+      return undefined;
     }
     validSegments.push(relName);
+    hops.push(rel);
     currentObj = nextObj;
   }
+  return hops;
+}
+
+// ---------------------------------------------------------------------------
+// FR-024 B5 — base-entity derivation, single-hop-unique @via inference, and
+// origin cardinality checks (spec §5–§6; ADR-0029 decisions 5–6).
+// ---------------------------------------------------------------------------
+
+/** A hop relationship's effective @cardinality, or undefined when not declared. */
+function _hopCardinality(rel: MetaData): string | undefined {
+  const v = rel.attr(RELATIONSHIP_ATTR_CARDINALITY);
+  return typeof v === "string" ? v : undefined;
+}
+
+/**
+ * Derive the BASE entity a no-`@via` origin path anchors at (spec §5):
+ *  - an entity (or any non-projection host) is its own base — derived fields
+ *    on multi-source entities anchor at the entity itself;
+ *  - a projection's base is the owner entity of its EXTENDED identity
+ *    (`identity.primary { extends: "Customer.id" }` — declared structurally);
+ *  - fallback (no identity): the single distinct entity targeted by the
+ *    projection's plain field-`extends` refs; >1 distinct entity →
+ *    ERR_AMBIGUOUS_PATH instructing the author to declare an extended
+ *    identity; 0 → ERR_INVALID_ORIGIN (no base derivable, cannot infer).
+ *
+ * Returns undefined when no base is derivable (an error has been pushed).
+ */
+/**
+ * FR-024: the entity NAMED by a node's dotted extends ref — the OWNER part of
+ * `<owner>.<child>...` resolved as an object. This differs from
+ * `superResolved.parent` when the resolved child is INHERITED: `Product.id`
+ * selecting BaseEntity's identity through Product's effective children must
+ * anchor `Product` (what the author wrote), never `BaseEntity` (where the
+ * child physically lives).
+ */
+function _refNamedOwner(node: MetaData, root: MetaData): MetaData | undefined {
+  const ref = node.superRef;
+  if (ref === undefined) return undefined;
+  const lastSep = ref.lastIndexOf("::");
+  const tail = lastSep === -1 ? ref : ref.slice(lastSep + 2);
+  const dot = tail.indexOf(".");
+  if (dot <= 0) return undefined;
+  return _findObject(root, tail.slice(0, dot));
+}
+
+function _deriveBaseEntity(
+  obj: MetaData,
+  root: MetaData,
+  fieldName: string,
+  originSource: ErrorSource,
+  errors: ParseError[],
+): MetaData | undefined {
+  if (obj.subType !== OBJECT_SUBTYPE_PROJECTION) return obj;
+
+  // 1) The extended identity anchors the base entity (declared, not inferred).
+  //    The anchor is the entity NAMED in the ref's owner part — see _refNamedOwner.
+  for (const identity of obj.ownChildren().filter((c) => c.type === TYPE_IDENTITY)) {
+    const extended = identity.superResolved;
+    if (extended !== undefined && extended.type === TYPE_IDENTITY) {
+      const named = _refNamedOwner(identity, root);
+      if (named !== undefined) return named;
+      const owner = extended.parent;
+      if (owner !== undefined && owner.type === TYPE_OBJECT) return owner;
+    }
+  }
+
+  // 2) Fallback: the single distinct entity targeted by plain field-extends —
+  //    again preferring the ref-named owner over the physical declaring ancestor.
+  const targets = new Set<MetaData>();
+  for (const f of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+    const sup = f.superResolved;
+    if (sup === undefined) continue;
+    const named = _refNamedOwner(f, root);
+    const owner = named ?? sup.parent;
+    if (
+      owner !== undefined &&
+      owner.type === TYPE_OBJECT &&
+      owner.subType !== OBJECT_SUBTYPE_VALUE &&
+      owner !== obj
+    ) {
+      targets.add(owner);
+    }
+  }
+  if (targets.size === 1) return [...targets][0];
+  if (targets.size > 1) {
+    const names = [...targets].map((t) => `"${t.name}"`).join(", ");
+    errors.push(
+      new ParseError(
+        `origin on ${obj.name}.${fieldName}: cannot derive the base entity — the projection's fields extend ` +
+          `multiple entities (${names}) and no identity extends an entity identity. Declare an extended identity ` +
+          `(e.g. identity.primary { name: "id", extends: "<Entity>.<identity>" }) to anchor the base entity (FR-024).`,
+        { code: "ERR_AMBIGUOUS_PATH", source: originSource },
+      ),
+    );
+  } else {
+    errors.push(
+      new ParseError(
+        `origin on ${obj.name}.${fieldName}: cannot derive the base entity for @via inference — the projection ` +
+          `has no extended identity and no entity-targeted field extends. Declare an extended identity or an explicit @via (FR-024).`,
+        { code: "ERR_INVALID_ORIGIN", source: originSource },
+      ),
+    );
+  }
+  return undefined;
+}
+
+/**
+ * True when the `@from`/`@of` target entity IS the host's base relation: the
+ * derived base entity itself, or an ancestor on the base's (or the host's)
+ * whole-object extends chain — the legacy `Summary extends Program` projection
+ * style inherits the base relation from its super, so `Program.title` on it is
+ * a base-relation column, not a join.
+ */
+function _isBaseRelationTarget(target: MetaData, base: MetaData, host: MetaData): boolean {
+  for (let cur: MetaData | undefined = base; cur !== undefined; cur = cur.superResolved) {
+    if (cur === target) return true;
+  }
+  for (let cur: MetaData | undefined = host; cur !== undefined; cur = cur.superResolved) {
+    if (cur === target) return true;
+  }
+  return false;
+}
+
+/**
+ * Single-hop-unique `@via` inference (ADR-0029 decision 5): scan the base
+ * entity's EFFECTIVE relationship children for those whose @objectRef resolves
+ * to the `@from`/`@of` target entity. Exactly one → the inferred path (the
+ * caller proceeds exactly as if `@via` were declared with that relationship).
+ * Zero → ERR_INVALID_ORIGIN (cannot infer; multi-hop is always explicit).
+ * More than one → ERR_AMBIGUOUS_PATH naming the candidate relationships.
+ *
+ * Inference stops at single-hop-unique deliberately: the algorithm is part of
+ * the cross-port conformance contract; graph search is not trivially portable.
+ */
+function _inferViaSingleHop(
+  base: MetaData,
+  targetEntity: MetaData,
+  obj: MetaData,
+  fieldName: string,
+  fromAttr: string,
+  label: string,
+  originSource: ErrorSource,
+  errors: ParseError[],
+): MetaData[] | undefined {
+  const candidates = base
+    .children()
+    .filter((c) => c.type === TYPE_RELATIONSHIP)
+    .filter((rel) => {
+      const ref = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+      return typeof ref === "string" && stripPackage(ref) === targetEntity.name;
+    });
+  // FR5d — referrer is `<host-FQN>::<fieldName>`, target is the from/of ref
+  // whose implicit path could not be resolved.
+  const referrer = `${obj.fqn()}::${fieldName}`;
+  if (candidates.length === 1) return [candidates[0] as MetaData];
+  if (candidates.length === 0) {
+    errors.push(
+      new ParseError(
+        `${label} "${fromAttr}" on ${obj.name}.${fieldName}: no @via and no single-hop relationship from base ` +
+          `entity "${base.name}" to "${targetEntity.name}" — cannot infer the path. Declare @via explicitly ` +
+          `(multi-hop paths are always explicit; ADR-0029).`,
+        {
+          code: "ERR_INVALID_ORIGIN",
+          source: resolvedSource(originSource, referrer, fromAttr),
+        },
+      ),
+    );
+    return undefined;
+  }
+  const names = candidates.map((r) => `"${r.name}"`).join(", ");
+  errors.push(
+    new ParseError(
+      `${label} "${fromAttr}" on ${obj.name}.${fieldName}: no @via and ${candidates.length} relationships from ` +
+        `base entity "${base.name}" to "${targetEntity.name}" (${names}) — ambiguous. Declare @via naming one of them (ADR-0029).`,
+      {
+        code: "ERR_AMBIGUOUS_PATH",
+        source: resolvedSource(originSource, referrer, fromAttr),
+      },
+    ),
+  );
+  return undefined;
+}
+
+/**
+ * ADR-0029 decision 6 — a passthrough via-path must be effectively to-one at
+ * EVERY hop. A hop is judged to-many only when it DECLARES `@cardinality:
+ * "many"`: @cardinality is an open string at the metamodel level (Java-
+ * canonical composite forms exist, and legacy fixtures omit it), so an
+ * absent/unknown cardinality is never misjudged.
+ */
+function _checkPassthroughCardinality(
+  hops: readonly MetaData[],
+  obj: MetaData,
+  fieldName: string,
+  originSource: ErrorSource,
+  errors: ParseError[],
+): void {
+  for (const rel of hops) {
+    if (_hopCardinality(rel) === CARDINALITY_MANY) {
+      errors.push(
+        new ParseError(
+          `origin.passthrough on ${obj.name}.${fieldName}: @via hop "${rel.name}" is to-many ` +
+            `(@cardinality "${CARDINALITY_MANY}") — a row-multiplying passthrough — you meant aggregate (ADR-0029).`,
+          { code: "ERR_ORIGIN_CARDINALITY", source: originSource },
+        ),
+      );
+      return;
+    }
+  }
+}
+
+/**
+ * ADR-0029 decision 6 — an aggregate via-path must contain at least one
+ * to-many hop. Conservative on the open @cardinality vocabulary: the error
+ * fires only when the path is PROVABLY to-one (every hop declares
+ * `@cardinality: "one"`); absent/composite cardinalities are not judged.
+ */
+function _checkAggregateCardinality(
+  hops: readonly MetaData[],
+  obj: MetaData,
+  fieldName: string,
+  originSource: ErrorSource,
+  errors: ParseError[],
+): void {
+  if (hops.length === 0) return;
+  const provablyToOne = hops.every((rel) => _hopCardinality(rel) === CARDINALITY_ONE);
+  if (provablyToOne) {
+    errors.push(
+      new ParseError(
+        `origin.aggregate on ${obj.name}.${fieldName}: every @via hop is to-one (@cardinality "${CARDINALITY_ONE}") — ` +
+          `aggregating over a to-one path — you meant passthrough (ADR-0029).`,
+        { code: "ERR_ORIGIN_CARDINALITY", source: originSource },
+      ),
+    );
+  }
+}
+
+/**
+ * FR-024 B6 (spec §4; ADR-0029 decision 7) — extends/origin agreement.
+ *
+ * When a field declares BOTH an entity-nested `extends` (shape lineage) and
+ * an `origin.passthrough` @from (data lineage), the two are independent
+ * statements that must coincide: the resolved @from target must be THE SAME
+ * NODE as the field's resolved extends target — or appear on its extends
+ * chain (a projection field extending another projection's field that
+ * ultimately extends the entity field still agrees). Host-agnostic: applies
+ * on projections, entities, and values (FR-004 payloads may carry both).
+ *
+ * NOT judged:
+ *  - `origin.aggregate` (it computes something new — no passthrough claim);
+ *  - an extends whose target is a TOP-LEVEL abstract field (its parent is
+ *    not an object) — shape-only reuse makes no lineage claim.
+ */
+function _checkExtendsOriginAgreement(
+  field: MetaData,
+  fromField: MetaData,
+  fromAttr: string,
+  obj: MetaData,
+  originSource: ErrorSource,
+  errors: ParseError[],
+): void {
+  const sup = field.superResolved;
+  if (sup === undefined || sup.type !== TYPE_FIELD) return;
+  const supOwner = sup.parent;
+  if (supOwner === undefined || supOwner.type !== TYPE_OBJECT) return;
+  for (let cur: MetaData | undefined = sup; cur !== undefined; cur = cur.superResolved) {
+    if (cur === fromField) return; // shape lineage and data lineage agree
+  }
+  // FR5d resolved envelope: referrer = host::field, target = the @from ref.
+  errors.push(
+    new ParseError(
+      `origin.passthrough on ${obj.name}.${field.name}: @from "${fromAttr}" disagrees with the field's extends ` +
+        `target "${supOwner.name}.${sup.name}" — extends (shape lineage) and origin.passthrough (data lineage) ` +
+        `must point at the same entity field (FR-024).`,
+      {
+        code: "ERR_EXTENDS_ORIGIN_MISMATCH",
+        source: resolvedSource(originSource, `${obj.fqn()}::${field.name}`, fromAttr),
+      },
+    ),
+  );
 }
 
 export function validateOriginPaths(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
   for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    // FR-024 B5: object.value hosts are EXEMPT from @via inference and
+    // cardinality checks — a value's origin.passthrough is FR-015 parameter
+    // lineage (values are constructed, never assembled; spec §7), not an
+    // assembly path. Their @from refs are still resolution-validated.
+    const isValueHost = obj.subType === OBJECT_SUBTYPE_VALUE;
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
       for (const origin of field.ownChildren().filter((c) => c.type === TYPE_ORIGIN)) {
         if (origin.subType === ORIGIN_SUBTYPE_PASSTHROUGH) {
@@ -443,10 +826,32 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             );
             continue;
           }
-          _validateFromPath(from, root, obj, field.name, origin.source, errors);
+          const fromTarget = _validateFromPath(from, root, obj, field.name, origin.source, errors);
+          // FR-024 B6 — extends/origin agreement (host-agnostic; runs whether
+          // @via is explicit, inferred, or a base-relation column).
+          if (fromTarget !== undefined) {
+            _checkExtendsOriginAgreement(field, fromTarget.field, from, obj, origin.source, errors);
+          }
           const via = origin.ownAttr(ORIGIN_PASSTHROUGH_ATTR_VIA);
           if (typeof via === "string" && via !== "") {
-            _validateViaPath(via, root, obj, field.name, origin.source, errors);
+            const hops = _validateViaPath(via, root, obj, field.name, origin.source, errors);
+            if (hops !== undefined) {
+              _checkPassthroughCardinality(hops, obj, field.name, origin.source, errors);
+            }
+          } else if (fromTarget !== undefined && !isValueHost) {
+            // FR-024 §6 — no @via: derive the base entity; a @from targeting
+            // the base relation itself is a plain base column (no checks);
+            // otherwise infer the single-hop-unique path and gate cardinality.
+            const base = _deriveBaseEntity(obj, root, field.name, origin.source, errors);
+            if (base !== undefined && !_isBaseRelationTarget(fromTarget.entity, base, obj)) {
+              const hops = _inferViaSingleHop(
+                base, fromTarget.entity, obj, field.name, from,
+                "origin.passthrough.@from", origin.source, errors,
+              );
+              if (hops !== undefined) {
+                _checkPassthroughCardinality(hops, obj, field.name, origin.source, errors);
+              }
+            }
           }
         } else if (origin.subType === ORIGIN_SUBTYPE_AGGREGATE) {
           const of_ = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_OF);
@@ -459,9 +864,34 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             );
             continue;
           }
-          _validateFromPath(of_, root, obj, field.name, origin.source, errors, "origin.aggregate.@of");
+          // NOTE (FR-024 B6): NO extends/origin agreement check on aggregates —
+          // an aggregate computes something new (count/sum/…); spec §4 defines
+          // agreement for passthrough only.
+          const ofTarget = _validateFromPath(of_, root, obj, field.name, origin.source, errors, "origin.aggregate.@of");
           const via = origin.ownAttr(ORIGIN_AGGREGATE_ATTR_VIA);
-          if (typeof via !== "string" || via === "") {
+          if (typeof via === "string" && via !== "") {
+            const hops = _validateViaPath(via, root, obj, field.name, origin.source, errors);
+            if (hops !== undefined) {
+              _checkAggregateCardinality(hops, obj, field.name, origin.source, errors);
+            }
+            continue;
+          }
+          // FR-024 §6 — no @via on an aggregate: inference applies only when
+          // @of targets a non-base entity from a non-value host; an aggregate
+          // over the base relation itself still requires an explicit path.
+          if (ofTarget === undefined) continue; // @of did not resolve — no inference to attempt
+          if (isValueHost) {
+            errors.push(
+              new ParseError(
+                `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
+                { code: "ERR_INVALID_ORIGIN", source: origin.source },
+              ),
+            );
+            continue;
+          }
+          const base = _deriveBaseEntity(obj, root, field.name, origin.source, errors);
+          if (base === undefined) continue; // base underivable — error already pushed
+          if (_isBaseRelationTarget(ofTarget.entity, base, obj)) {
             errors.push(
               new ParseError(
                 `origin.aggregate on ${obj.name}.${field.name}: missing @via (aggregates require a relationship path).`,
@@ -470,7 +900,13 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
             );
             continue;
           }
-          _validateViaPath(via, root, obj, field.name, origin.source, errors);
+          const hops = _inferViaSingleHop(
+            base, ofTarget.entity, obj, field.name, of_,
+            "origin.aggregate.@of", origin.source, errors,
+          );
+          if (hops !== undefined) {
+            _checkAggregateCardinality(hops, obj, field.name, origin.source, errors);
+          }
         }
       }
     }
@@ -479,34 +915,94 @@ export function validateOriginPaths(root: MetaData): ParseError[] {
 }
 
 // ---------------------------------------------------------------------------
-// @storage cross-attribute validation
+// FR-024 B6 — derived-field providability (spec §7 population doctrine).
+//
+// An object.ENTITY field carrying any origin.* child is derived (read-only):
+// it does not exist on the writable table — something must PROVIDE it on
+// read. The spec §7 multi-source pattern is a writable table-primary source
+// plus a read-only-kind source (view / materializedView / storedProc /
+// tableFunction, e.g. @role "replica") that carries the derived fields.
+// An entity whose only sources are writable kinds — or that has no source at
+// all — cannot provide an origin-bearing field → ERR_DERIVED_FIELD_NO_READ_SOURCE
+// on that field (plain node-source envelope).
+//
+// Exemptions:
+//  - object.projection — the projection's own source/wire IS the provider;
+//  - object.value — FR-015 lineage; values are constructed, never populated.
+//
+// The rule reads "at least one read-only-kind source, any role". Since the
+// B4b hard cutover (ERR_ENTITY_PRIMARY_SOURCE_READONLY makes a read-only-kind
+// PRIMARY illegal on entities), the only loadable satisfying shape is the
+// strict one — a non-primary-role read-only source (the §7 multi-source
+// pattern: table primary + view replica).
+//
+// Sources are scanned on the EFFECTIVE child view (children()) so an entity
+// inheriting its sources from an abstract base is judged by what it actually
+// has; fields + origins use the own view, mirroring validateOriginPaths.
+// ---------------------------------------------------------------------------
+
+export function validateDerivedFieldProvidability(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root
+    .ownChildren()
+    .filter((c) => c.type === TYPE_OBJECT && c.subType === OBJECT_SUBTYPE_ENTITY)) {
+    const hasReadCapableSource = obj
+      .children()
+      .filter((c) => c.type === TYPE_SOURCE)
+      .some((s) => (s as MetaSource).isReadOnly());
+    if (hasReadCapableSource) continue;
+    for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+      if (!field.ownChildren().some((c) => c.type === TYPE_ORIGIN)) continue;
+      errors.push(
+        new ParseError(
+          `derived field "${obj.name}.${field.name}" carries an origin.* but entity "${obj.name}" declares no ` +
+            `read-capable source — derived fields do not exist on the writable table. Declare a read-only source ` +
+            `(e.g. source.rdb @kind "view" @role "replica") to provide it, or move the field to an object.projection (FR-024 §7).`,
+          { code: "ERR_DERIVED_FIELD_NO_READ_SOURCE", source: field.source },
+        ),
+      );
+    }
+  }
+  return errors;
+}
+
+// ---------------------------------------------------------------------------
+// field.object + @storage cross-attribute validation
 //
-// Rules:
-//   1. @storage requires @objectRef to be present (storage is meaningless
-//      without a referenced object type).
+// Rules (ADR-0013):
+//   1. A field.object ALWAYS requires @objectRef. A field.object models a typed
+//      nested value; without @objectRef it is "an oxymoron at the logical layer".
+//      Genuinely open/untyped JSON uses the physical @dbColumnType: jsonb escape
+//      hatch on field.string, NOT a bare object. → ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF.
+//      (This rule subsumes the legacy @storage-without-@objectRef check —
+//      @storage is only meaningful on a field.object, so the missing-@objectRef
+//      situation now always reports this single, clearer error. One error per
+//      node: when @objectRef is absent we skip the flattened/array check below.)
 //   2. @storage "flattened" requires isArray to be absent or false (cannot
 //      flatten a variable-length array into a fixed column set).
-//
-// Only field.object nodes carry @storage in practice, but the check is applied
-// to every field node that has @storage set — matching the permissive "check
-// what's there" model used by the other validation passes.
 // ---------------------------------------------------------------------------
 
 export function validateFieldObjectStorage(root: MetaData): ParseError[] {
   const errors: ParseError[] = [];
   for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
     for (const field of obj.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
-      const storage = field.ownAttr(FIELD_ATTR_STORAGE);
-      if (storage === undefined || storage === null) continue;
       const objectRef = field.ownAttr(FIELD_ATTR_OBJECT_REF);
-      if (typeof objectRef !== "string" || objectRef.length === 0) {
+      const hasObjectRef = typeof objectRef === "string" && objectRef.length > 0;
+
+      if (field.subType === FIELD_SUBTYPE_OBJECT && !hasObjectRef) {
+        // A field.object with no @objectRef is rejected outright; reporting any
+        // further @storage error on the same node would be redundant.
         errors.push(
           new ParseError(
-            `field "${obj.name}.${field.name}" sets @storage but has no @objectRef`,
-            { code: "ERR_STORAGE_WITHOUT_OBJECT_REF", source: field.source },
+            `field.object "${obj.name}.${field.name}" has no @objectRef; a field.object requires @objectRef. For an open/untyped JSON map use @dbColumnType: jsonb on a field.string instead of a bare object.`,
+            { code: "ERR_OBJECT_FIELD_WITHOUT_OBJECT_REF", source: field.source },
           ),
         );
+        continue;
       }
+
+      const storage = field.ownAttr(FIELD_ATTR_STORAGE);
+      if (storage === undefined || storage === null) continue;
       if (storage === STORAGE_FLATTENED && field.isArray === true) {
         errors.push(
           new ParseError(
@@ -646,6 +1142,156 @@ export function validateDataGridFilterValues(root: MetaData): ParseError[] {
   return errors;
 }
 
+// ---------------------------------------------------------------------------
+// FR-017 — M:N relationship validation (slim vocabulary)
+//
+// Deferred-resolution validation (runs after all files load + extends:
+// resolution, like origin paths), enforcing the cross-port M:N contract:
+//
+//   (a) @symmetric:true is valid only on a self-join (@objectRef == declaring
+//       entity). Otherwise ERR_BAD_ATTR_VALUE.
+//   (b) @symmetric and @sourceRefField are mutually exclusive → ERR_BAD_ATTR_VALUE.
+//   (c) When @through is present: the named entity must exist and declare exactly
+//       two identity.reference children; @sourceRefField (if present) must match
+//       one of those references' FK fields → ERR_INVALID_RELATIONSHIP.
+//   (d) @through / @sourceRefField / @symmetric are invalid on a non-M:N
+//       relationship (@cardinality != "many", or no @through) → ERR_INVALID_RELATIONSHIP.
+//
+// Own-relationships only: a relationship is validated on the entity that declares
+// it (matching the own-attrs policy of the other passes).
+// ---------------------------------------------------------------------------
+
+// The junction's reference view: the validator and the runtime/codegen FK
+// derivation (deriveM2MFields) MUST agree on which references count. Both use
+// the EFFECTIVE view (own + inherited via extends) via referenceIdentities(),
+// so a junction defined through `extends` is treated identically here and at
+// resolution time. (For a junction with no extends, effective == own.)
+function _junctionReferences(junction: MetaData): MetaReferenceIdentity[] {
+  return (junction as MetaObject).referenceIdentities();
+}
+
+/** FK field names declared by a junction's effective identity.reference children. */
+function _junctionReferenceFkFields(junction: MetaData): string[] {
+  const out: string[] = [];
+  for (const ref of _junctionReferences(junction)) {
+    const first = ref.fields[0];
+    if (first) out.push(first);
+  }
+  return out;
+}
+
+function _countJunctionReferences(junction: MetaData): number {
+  return _junctionReferences(junction).length;
+}
+
+export function validateRelationships(root: MetaData): ParseError[] {
+  const errors: ParseError[] = [];
+  for (const obj of root.ownChildren().filter((c) => c.type === TYPE_OBJECT)) {
+    for (const rel of obj.ownChildren().filter((c) => c.type === TYPE_RELATIONSHIP)) {
+      const through = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH);
+      const sourceRefField = rel.ownAttr(RELATIONSHIP_ATTR_SOURCE_REF_FIELD);
+      const symmetric = rel.ownAttr(RELATIONSHIP_ATTR_SYMMETRIC) === true;
+      const cardinality = rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY);
+      const objectRef = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF);
+
+      const hasThrough = typeof through === "string" && through !== "";
+      const hasSourceRefField = typeof sourceRefField === "string" && sourceRefField !== "";
+      const isMany = cardinality === CARDINALITY_MANY;
+      const isM2M = hasThrough && isMany;
+
+      // Rule (d): M:N-only attrs on a non-M:N relationship.
+      if (!isM2M) {
+        if (hasThrough) {
+          errors.push(
+            new ParseError(
+              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_THROUGH} but is not a M:N ` +
+                `relationship (requires @${RELATIONSHIP_ATTR_CARDINALITY}: "${CARDINALITY_MANY}").`,
+              { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+            ),
+          );
+        }
+        if (hasSourceRefField) {
+          errors.push(
+            new ParseError(
+              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} but is not a M:N relationship.`,
+              { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+            ),
+          );
+        }
+        if (symmetric) {
+          errors.push(
+            new ParseError(
+              `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but is not a M:N relationship.`,
+              { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+            ),
+          );
+        }
+        continue;
+      }
+
+      // Rule (b): @symmetric and @sourceRefField are mutually exclusive.
+      if (symmetric && hasSourceRefField) {
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" sets both @${RELATIONSHIP_ATTR_SYMMETRIC} and ` +
+              `@${RELATIONSHIP_ATTR_SOURCE_REF_FIELD}; they are mutually exclusive.`,
+            { code: "ERR_BAD_ATTR_VALUE", source: rel.source },
+          ),
+        );
+      }
+
+      // Rule (a): @symmetric is valid only on a self-join (@objectRef == declaring entity).
+      const isSelfJoin = typeof objectRef === "string" && stripPackage(objectRef) === obj.name;
+      if (symmetric && !isSelfJoin) {
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" sets @${RELATIONSHIP_ATTR_SYMMETRIC} but @${RELATIONSHIP_ATTR_OBJECT_REF} ` +
+              `"${String(objectRef)}" is not the declaring entity "${obj.name}"; @${RELATIONSHIP_ATTR_SYMMETRIC} is self-join-only.`,
+            { code: "ERR_BAD_ATTR_VALUE", source: rel.source },
+          ),
+        );
+      }
+
+      // Rule (c): @through must name an entity declaring exactly two identity.reference children.
+      const junction = _findObject(root, through as string);
+      if (!junction) {
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" does not resolve to an entity.`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: resolvedSource(rel.source, `${obj.fqn()}::${rel.name}`, String(through)) },
+          ),
+        );
+        continue;
+      }
+      const refCount = _countJunctionReferences(junction);
+      if (refCount !== 2) {
+        errors.push(
+          new ParseError(
+            `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_THROUGH} "${through}" must declare exactly two ` +
+              `identity.reference children (one per FK side); found ${refCount}.`,
+            { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+          ),
+        );
+        continue;
+      }
+      // @sourceRefField (if present) must match one of the junction's reference FK fields.
+      if (hasSourceRefField) {
+        const fkFields = _junctionReferenceFkFields(junction);
+        if (!fkFields.includes(sourceRefField as string)) {
+          errors.push(
+            new ParseError(
+              `relationship "${obj.name}.${rel.name}" @${RELATIONSHIP_ATTR_SOURCE_REF_FIELD} "${sourceRefField}" does not match ` +
+                `any identity.reference FK field on junction "${through}". Available: ${fkFields.join(", ") || "(none)"}.`,
+              { code: "ERR_INVALID_RELATIONSHIP", source: rel.source },
+            ),
+          );
+        }
+      }
+    }
+  }
+  return errors;
+}
+
 function checkFilterClauses(
   filter: Record<string, unknown>,
   allow: Map<string, readonly string[]>,