@metaobjectsdev/runtime-ts 0.9.0 → 0.10.0

package/src/n2m-resolver.ts

@@ -1,28 +1,48 @@
-// Two-stage N:M: first query the join entity for FK pairs, then query the target entity for the rows.
-// The relationship declares @joinEntity + @joinFields: [sourceJoinField, targetJoinField].
-
-import type { ColumnNamingStrategy, MetaData } from "@metaobjectsdev/metadata";
+// Two-stage M:N resolution.
+//
+// A M:N relationship declares only the slim FR-018 vocabulary on the source
+// entity: `@cardinality: "many"` + `@objectRef: <target>` + `@through:
+// <junction>` (plus optional `@sourceRefField` / `@symmetric` for self-joins).
+// It does NOT restate the junction FK columns — those are DERIVED from the
+// junction entity's two `identity.reference` children via the shared
+// `deriveM2MFields` helper (the SSOT for FK direction, the same one the loader
+// validator + every other port use). This kills the pre-FR-018 stopgap that
+// read `@joinEntity` / `@joinFields` off the relationship.
+//
+// Resolution has three modes (see the FR-018 design):
+//   1. Hetero (source != target): junction WHERE sourceField (IN|=) source.pk,
+//      collect targetField, then target WHERE pk IN (...).
+//   2. Directed self-join (`@sourceRefField`): identical traversal; the helper
+//      has already picked which junction FK is the source side.
+//   3. Symmetric self-join (`@symmetric: true`): single-row storage, union on
+//      read — junction WHERE sourceField (IN|=) id OR targetField (IN|=) id;
+//      for each row the related id is whichever FK column is NOT the source id.
+
+import type { ColumnNamingStrategy, MetaData, MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
 import {
   TYPE_OBJECT, TYPE_FIELD, TYPE_RELATIONSHIP,
-  RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF,
-  RELATIONSHIP_ATTR_JOIN_ENTITY, RELATIONSHIP_ATTR_JOIN_FIELDS,
+  RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF, RELATIONSHIP_ATTR_THROUGH,
   CARDINALITY_MANY,
   DEFAULT_COLUMN_NAMING_STRATEGY,
   resolveColumnName,
+  deriveM2MFields,
 } from "@metaobjectsdev/metadata";
+import type { MetaRelationship } from "@metaobjectsdev/metadata";
 import { MetadataError } from "./errors.js";
 import { buildSelectSpec, resolvePkFields } from "./query-builder.js";
-import type { SelectSpec, PrimitiveValue, Row } from "./persistence-driver.js";
+import type { SelectSpec, WhereClause, PrimitiveValue, Row } from "./persistence-driver.js";
 
 export interface N2mDescriptor {
-  /** Entity that declares the relationship (source of the lookup; its PK feeds sourceJoinField). */
+  /** Entity that declares the relationship (source of the lookup; its PK feeds sourceField). */
   sourceEntityName: string;
   targetEntityName: string;
   joinEntityName: string;
-  /** Field name on the join entity holding the source-side FK. */
+  /** Junction FK field holding the source-side key (derived from the junction's references). */
   sourceJoinField: string;
-  /** Field name on the join entity holding the target-side FK. */
+  /** Junction FK field holding the target-side key (derived from the junction's references). */
   targetJoinField: string;
+  /** Undirected self-join: union both junction FK columns at read time. */
+  symmetric: boolean;
 }
 
 export interface N2mLazyOutput {
@@ -31,12 +51,9 @@ export interface N2mLazyOutput {
   makeTargetSpec: (joinRows: Row[]) => SelectSpec | null;
 }
 
-export interface N2mBatchOutput {
-  joinSpec: SelectSpec;
-  makeTargetSpec: (joinRows: Row[]) => SelectSpec | null;
-}
+export type N2mBatchOutput = N2mLazyOutput;
 
-/** Returns null if the named relationship is not N:M — caller should try resolveRelationDescriptor. */
+/** Returns null if the named relationship is not M:N — caller should try resolveRelationDescriptor. */
 export function resolveN2mDescriptor(
   sourceEntity: MetaData,
   relationName: string,
@@ -46,29 +63,37 @@ export function resolveN2mDescriptor(
     if (child.type !== TYPE_RELATIONSHIP) continue;
     if (child.name !== relationName) continue;
     if (child.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
-    const targetEntityName = child.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
-    const joinEntityName = child.ownAttr(RELATIONSHIP_ATTR_JOIN_ENTITY) as string | undefined;
-    const joinFields = child.ownAttr(RELATIONSHIP_ATTR_JOIN_FIELDS);
-    if (!targetEntityName || !joinEntityName || !Array.isArray(joinFields) || joinFields.length !== 2) {
+    if (child.ownAttr(RELATIONSHIP_ATTR_THROUGH) === undefined) continue; // 1:N many — not M:N.
+
+    const rel = child as MetaRelationship;
+    const targetEntityName = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+    const joinEntityName = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+    if (!targetEntityName || !joinEntityName) {
       throw new MetadataError(
-        `N:M relationship '${relationName}' on '${sourceEntity.name}' requires @objectRef + @joinEntity + @joinFields: [sourceFk, targetFk]`,
+        `M:N relationship '${relationName}' on '${sourceEntity.name}' requires @objectRef + @through`,
         { entity: sourceEntity.name },
       );
     }
-    const targetExists = root.ownChildren().some((c) => c.type === TYPE_OBJECT && c.name === targetEntityName);
-    if (!targetExists) {
-      throw new MetadataError(`Target entity '${targetEntityName}' not found`, { entity: sourceEntity.name });
-    }
-    const joinExists = root.ownChildren().some((c) => c.type === TYPE_OBJECT && c.name === joinEntityName);
-    if (!joinExists) {
-      throw new MetadataError(`Join entity '${joinEntityName}' not found`, { entity: sourceEntity.name });
+
+    // Derive the [sourceFK, targetFK] junction columns from the junction's two
+    // identity.reference children (handles hetero / directed / symmetric).
+    let fields;
+    try {
+      fields = deriveM2MFields(rel, sourceEntity as MetaObject, root as MetaRoot);
+    } catch (e) {
+      throw new MetadataError(
+        `M:N relationship '${relationName}' on '${sourceEntity.name}': ${(e as Error).message}`,
+        { entity: sourceEntity.name },
+      );
     }
+
     return {
       sourceEntityName: sourceEntity.name,
       targetEntityName,
       joinEntityName,
-      sourceJoinField: String(joinFields[0]),
-      targetJoinField: String(joinFields[1]),
+      sourceJoinField: fields.sourceField,
+      targetJoinField: fields.targetField,
+      symmetric: rel.symmetric,
     };
   }
   return null;
@@ -80,21 +105,7 @@ export function buildN2mLazySpecs(
   root: MetaData,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
 ): N2mLazyOutput {
-  const joinEntity = mustGetEntity(root, desc.joinEntityName);
-  const targetEntity = mustGetEntity(root, desc.targetEntityName);
-  const sourcePkField = resolvePkFields(mustGetEntity(root, desc.sourceEntityName))[0]!;
-  const sourcePkValue = sourceRecord[sourcePkField];
-
-  const joinSpec = buildSelectSpec(joinEntity, { [desc.sourceJoinField]: sourcePkValue as PrimitiveValue }, {}, undefined, strategy);
-
-  const makeTargetSpec = (joinRows: Row[]): SelectSpec | null => {
-    const targetIds = collectTargetIds(joinRows, desc.targetJoinField, joinEntity, strategy);
-    if (targetIds.length === 0) return null;
-    const targetPkField = resolvePkFields(targetEntity)[0]!;
-    return buildSelectSpec(targetEntity, { [targetPkField]: targetIds }, {}, undefined, strategy);
-  };
-
-  return { joinSpec, makeTargetSpec };
+  return buildSpecs(desc, sourceRecord, root, strategy);
 }
 
 export function buildN2mBatchSpecs(
@@ -103,51 +114,126 @@ export function buildN2mBatchSpecs(
   root: MetaData,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
 ): N2mBatchOutput {
+  return buildSpecs(desc, sourceRecords, root, strategy);
+}
+
+// Single + batch share one code path: a single record is the one-element case.
+function buildSpecs(
+  desc: N2mDescriptor,
+  source: Row | Row[],
+  root: MetaData,
+  strategy: ColumnNamingStrategy,
+): N2mLazyOutput {
   const joinEntity = mustGetEntity(root, desc.joinEntityName);
   const targetEntity = mustGetEntity(root, desc.targetEntityName);
-  const sourcePkField = resolvePkFields(mustGetEntity(root, desc.sourceEntityName))[0]!;
-  const sourceIds = collectIds(sourceRecords, sourcePkField);
+  const sourceEntity = mustGetEntity(root, desc.sourceEntityName);
+  const sourcePkField = resolvePkFields(sourceEntity)[0]!;
+
+  const records = Array.isArray(source) ? source : [source];
+  const sourceIds = collectIds(records, sourcePkField);
+  const sourceIdSet = new Set<PrimitiveValue>(sourceIds);
+
+  const sourceCol = resolveJoinColumnName(joinEntity, desc.sourceJoinField, strategy);
+  const targetCol = resolveJoinColumnName(joinEntity, desc.targetJoinField, strategy);
 
-  const joinSpec = buildSelectSpec(joinEntity, { [desc.sourceJoinField]: sourceIds }, {}, undefined, strategy);
+  // buildSelectSpec compiles a filter on the entity's fields; for symmetric we
+  // need an OR across two columns, which the filter DSL can't express. So we
+  // build the join spec directly off buildSelectSpec then swap in the where.
+  const joinSpec = buildSelectSpec(joinEntity, undefined, {}, undefined, strategy);
+  joinSpec.where = desc.symmetric
+    ? { kind: "or", clauses: [inOrEq(sourceCol, sourceIds), inOrEq(targetCol, sourceIds)] }
+    : inOrEq(sourceCol, sourceIds);
 
   const makeTargetSpec = (joinRows: Row[]): SelectSpec | null => {
-    const targetIds = collectTargetIds(joinRows, desc.targetJoinField, joinEntity, strategy);
+    const targetIds = desc.symmetric
+      ? collectSymmetricTargetIds(joinRows, sourceCol, targetCol, sourceIdSet)
+      : collectColumnIds(joinRows, targetCol);
     if (targetIds.length === 0) return null;
     const targetPkField = resolvePkFields(targetEntity)[0]!;
-    return buildSelectSpec(targetEntity, { [targetPkField]: targetIds }, {}, undefined, strategy);
+    // PK values are always string|number; the IN filter type excludes boolean.
+    const ids = targetIds.filter((v): v is string | number => typeof v !== "boolean");
+    return buildSelectSpec(targetEntity, { [targetPkField]: ids }, {}, undefined, strategy);
   };
 
   return { joinSpec, makeTargetSpec };
 }
 
+/** `= x` for a single id, `IN (...)` for many (degenerate empty → IN [] = no rows). */
+function inOrEq(column: string, ids: PrimitiveValue[]): WhereClause {
+  return ids.length === 1
+    ? { kind: "eq", column, value: ids[0]! }
+    : { kind: "in", column, values: ids };
+}
+
 function mustGetEntity(root: MetaData, name: string): MetaData {
   const e = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
   if (!e) throw new MetadataError(`Entity '${name}' not found`, { entity: name });
   return e;
 }
 
-function collectIds(records: Row[], pkField: string): (string | number)[] {
+function collectIds(records: Row[], pkField: string): PrimitiveValue[] {
   const seen = new Set<PrimitiveValue>();
   for (const r of records) {
     const v = r[pkField];
     if (v === null || v === undefined) continue;
     seen.add(v as PrimitiveValue);
   }
-  return [...seen] as (string | number)[];
+  return [...seen];
 }
 
-function collectTargetIds(
-  joinRows: Row[], targetJoinField: string, joinEntity: MetaData, strategy: ColumnNamingStrategy,
-): (string | number)[] {
-  // joinRows are raw column-keyed (driver hasn't been to-JS-row'd yet); resolve the metadata field name to its DB column.
-  const dbColumn = resolveJoinColumnName(joinEntity, targetJoinField, strategy);
+/** Distinct values of a raw (column-keyed) join column. */
+function collectColumnIds(joinRows: Row[], dbColumn: string): PrimitiveValue[] {
   const seen = new Set<PrimitiveValue>();
   for (const r of joinRows) {
     const v = r[dbColumn];
     if (v === null || v === undefined) continue;
     seen.add(v as PrimitiveValue);
   }
-  return [...seen] as (string | number)[];
+  return [...seen];
+}
+
+/**
+ * Symmetric union-on-read: this gathers the set of related ids to FETCH for the
+ * second-stage query. For each junction row (a,b) that surfaced via the
+ * `a IN ids OR b IN ids` join filter, the related endpoint is the column that is
+ * NOT a source — EXCEPT when BOTH columns are sources (two mutually-related
+ * records queried in the same batch), where both must be fetched so the
+ * eager-include grouping can attach a→b AND b→a. A self-loop row (a==b, a a
+ * source) yields a itself.
+ *
+ * Membership is compared by string-coerced key: the source ids come from the
+ * in-process source record (e.g. a JS number) while the junction FK values come
+ * straight off the driver, where a BIGINT key arrives as a string. Comparing
+ * raw would miss the match (number 1 !== string "1"); string keys bridge it.
+ */
+function collectSymmetricTargetIds(
+  joinRows: Row[], sourceCol: string, targetCol: string, sourceIds: Set<PrimitiveValue>,
+): PrimitiveValue[] {
+  const sourceKeys = new Set<string>([...sourceIds].map(String));
+  const seen = new Set<PrimitiveValue>();
+  const add = (v: PrimitiveValue | null | undefined): void => {
+    if (v === null || v === undefined) return;
+    seen.add(v);
+  };
+  for (const r of joinRows) {
+    const a = r[sourceCol] as PrimitiveValue | null | undefined;
+    const b = r[targetCol] as PrimitiveValue | null | undefined;
+    const aIsSource = a !== null && a !== undefined && sourceKeys.has(String(a));
+    const bIsSource = b !== null && b !== undefined && sourceKeys.has(String(b));
+    // When a is a source, b is its related id; when b is a source, a is its
+    // related id. Both can hold at once (mutually-related batch members) — fetch
+    // both endpoints then. Falls back to "the non-matched column" when only one
+    // side matched (the common single-source-lookup case).
+    if (aIsSource) add(b);
+    if (bIsSource) add(a);
+    if (!aIsSource && !bIsSource) {
+      // Row surfaced via the join filter but neither column string-matches a
+      // source id (e.g. number/string skew not bridged here) — keep prior
+      // behavior: take whichever side is present.
+      add(a ?? b);
+    }
+  }
+  return [...seen];
 }
 
 export function resolveJoinColumnName(

package/src/object-manager.ts

@@ -1,7 +1,7 @@
 import type { MetaData } from "@metaobjectsdev/metadata";
 import {
   TYPE_OBJECT, TYPE_FIELD,
-  FIELD_SUBTYPE_INT, FIELD_SUBTYPE_SHORT, FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL,
 } from "@metaobjectsdev/metadata";
 import type {
@@ -11,8 +11,9 @@ import type {
 import {
   buildSelectSpec, buildCountSpec, buildInsertSpec, buildUpdateSpec, buildDeleteSpec,
   resolvePkFields, compileFilter,
-  type Filter, type QueryOpts,
+  type Filter, type QueryOpts, type DiscriminatorScope,
 } from "./query-builder.js";
+import { tphSubtypeOf, type TphSubtype } from "./tph.js";
 import {
   buildNameMap, resolveTableName, DEFAULT_COLUMN_NAMING_STRATEGY,
   type ColumnNamingStrategy, type EntityNameMap,
@@ -81,6 +82,20 @@ export class ObjectManager {
     return m;
   }
 
+  /** TPH discriminator scope for a subtype entity, or undefined for non-TPH. */
+  private tphScope(entity: MetaData): DiscriminatorScope | undefined {
+    const t = tphSubtypeOf(entity);
+    return t ? { field: t.field, value: t.value } : undefined;
+  }
+
+  /** AND the TPH discriminator predicate into a filter (subtype-scoped reads). */
+  private scopeFilter(filter: Filter | undefined, tph: TphSubtype | null): Filter | undefined {
+    if (tph === null) return filter;
+    const disc = { [tph.field]: { $eq: tph.value } } as Filter;
+    if (filter === undefined) return disc;
+    return { $and: [filter, disc] } as Filter;
+  }
+
   async findById(entityName: string, id: unknown, opts: ReadOpts = {}): Promise<Row | null> {
     const entity = this.requireEntity(entityName);
     const pkField = resolvePkFields(entity)[0]!;
@@ -90,7 +105,8 @@ export class ObjectManager {
   async findFirst(entityName: string, filter: Filter, opts: ReadOpts = {}): Promise<Row | null> {
     const entity = this.requireEntity(entityName);
     const driver = opts.tx ?? this.driver;
-    const spec = buildSelectSpec(entity, filter, { ...opts, limit: 1 }, undefined, this.columnNamingStrategy);
+    const scoped = this.scopeFilter(filter, tphSubtypeOf(entity));
+    const spec = buildSelectSpec(entity, scoped, { ...opts, limit: 1 }, undefined, this.columnNamingStrategy);
     const row = await driver.selectOne(spec);
     if (row === null) return null;
     const jsRow = this.toJsRow(entity, row);
@@ -103,7 +119,8 @@ export class ObjectManager {
   async findMany(entityName: string, filter?: Filter, opts: ReadOpts = {}): Promise<Row[]> {
     const entity = this.requireEntity(entityName);
     const driver = opts.tx ?? this.driver;
-    const spec = buildSelectSpec(entity, filter, opts, undefined, this.columnNamingStrategy);
+    const scoped = this.scopeFilter(filter, tphSubtypeOf(entity));
+    const spec = buildSelectSpec(entity, scoped, opts, undefined, this.columnNamingStrategy);
     const rows = (await driver.selectMany(spec)).map((r) => this.toJsRow(entity, r));
     if (opts.include && opts.include.length > 0) {
       await this.attachIncludes(entity, rows, opts.include, driver);
@@ -114,7 +131,8 @@ export class ObjectManager {
   async count(entityName: string, filter?: Filter, opts: Pick<ReadOpts, "tx"> = {}): Promise<number> {
     const entity = this.requireEntity(entityName);
     const driver = opts.tx ?? this.driver;
-    return driver.count(buildCountSpec(entity, filter, this.columnNamingStrategy));
+    const scoped = this.scopeFilter(filter, tphSubtypeOf(entity));
+    return driver.count(buildCountSpec(entity, scoped, this.columnNamingStrategy));
   }
 
   async load(refString: string): Promise<Row | null> {
@@ -145,7 +163,11 @@ export class ObjectManager {
     const entity = this.requireEntity(entityName);
     const driver = opts.tx ?? this.driver;
 
-    const restricted = this.applyViewRestriction(entity, data, opts.view);
+    const restricted0 = this.applyViewRestriction(entity, data, opts.view);
+    // FR-017 TPH: a subtype create injects its discriminator value (the entity
+    // names the subtype; the caller never sets it).
+    const tph = tphSubtypeOf(entity);
+    const restricted = tph ? { ...restricted0, [tph.field]: tph.value } : restricted0;
     const ident = resolveIdentity(entity, restricted);
     const merged: Row = { ...restricted, ...ident.values };
 
@@ -164,7 +186,15 @@ export class ObjectManager {
     const entity = this.requireEntity(entityName);
     const driver = opts.tx ?? this.driver;
 
-    const restricted = this.applyViewRestriction(entity, data, opts.view);
+    const restricted0 = this.applyViewRestriction(entity, data, opts.view);
+    // FR-017 TPH: the discriminator is immutable — a subtype can't be changed
+    // into another subtype, so strip it from the patch before validating/writing.
+    const tph = tphSubtypeOf(entity);
+    let restricted = restricted0;
+    if (tph && tph.field in restricted0) {
+      const { [tph.field]: _omit, ...rest } = restricted0;
+      restricted = rest;
+    }
 
     // Partial mode: only validate fields the caller actually passed; absent keys are untouched.
     const validation = runValidators(entity, restricted, { partial: true });
@@ -173,7 +203,8 @@ export class ObjectManager {
     }
 
     const coerced = coerceRowOnWrite(entity, restricted, driver.dialect);
-    const spec = buildUpdateSpec(entity, coerced, id, this.columnNamingStrategy);
+    // FR-017 TPH: scope the by-id update to the subtype (cross-subtype → not found).
+    const spec = buildUpdateSpec(entity, coerced, id, this.columnNamingStrategy, this.tphScope(entity));
     const dbRow = await driver.update(spec);
     if (dbRow === null) {
       const mode = opts.ifMissing ?? DEFAULT_IF_MISSING;
@@ -186,7 +217,8 @@ export class ObjectManager {
   async delete(entityName: string, id: unknown, opts: WriteOpts = {}): Promise<boolean> {
     const entity = this.requireEntity(entityName);
     const driver = opts.tx ?? this.driver;
-    const spec = buildDeleteSpec(entity, id, this.columnNamingStrategy);
+    // FR-017 TPH: scope the by-id delete to the subtype (cross-subtype → not found).
+    const spec = buildDeleteSpec(entity, id, this.columnNamingStrategy, this.tphScope(entity));
     const n = await driver.delete(spec);
     if (n === 0) {
       const mode = opts.ifMissing ?? DEFAULT_IF_MISSING;
@@ -334,16 +366,33 @@ export class ObjectManager {
         const sourceJoinDbCol = resolveJoinColumnName(joinEntity, n2m.sourceJoinField, this.columnNamingStrategy);
         const targetJoinDbCol = resolveJoinColumnName(joinEntity, n2m.targetJoinField, this.columnNamingStrategy);
         const targetPk = resolvePkFields(target)[0]!;
-        const targetById = new Map(targetRows.map((r) => [r[targetPk], r]));
-        const grouped = new Map<unknown, Row[]>();
+        // Key everything by String(): the join rows are raw (a BIGINT FK arrives
+        // as a string from the driver) while the JS rows' keys are coerced, so a
+        // number↔string mismatch would silently drop matches.
+        const key = (v: unknown): string | null => (v === null || v === undefined ? null : String(v));
+        const targetById = new Map(targetRows.map((r) => [key(r[targetPk]), r]));
+        const sourceKeys = new Set(records.map((r) => key(r[sourcePk])));
+        const grouped = new Map<string, Row[]>();
+        const attach = (ownerKey: string | null, relatedKey: string | null): void => {
+          if (ownerKey === null) return;
+          const t = relatedKey === null ? undefined : targetById.get(relatedKey);
+          if (!t) return;
+          if (!grouped.has(ownerKey)) grouped.set(ownerKey, []);
+          grouped.get(ownerKey)!.push(t);
+        };
         for (const j of joinRows) {
-          const sk = j[sourceJoinDbCol];
-          const tk = j[targetJoinDbCol];
-          if (!grouped.has(sk)) grouped.set(sk, []);
-          const t = targetById.get(tk);
-          if (t) grouped.get(sk)!.push(t);
+          const a = key(j[sourceJoinDbCol]);
+          const b = key(j[targetJoinDbCol]);
+          if (n2m.symmetric) {
+            // Union-on-read: a row (a,b) relates a↔b. Attach to whichever
+            // endpoint(s) are in this batch; the related id is the OTHER one.
+            if (a !== null && sourceKeys.has(a)) attach(a, b);
+            if (b !== null && a !== b && sourceKeys.has(b)) attach(b, a);
+          } else {
+            attach(a, b);
+          }
         }
-        for (const r of records) r[inc] = grouped.get(r[sourcePk]) ?? [];
+        for (const r of records) r[inc] = grouped.get(key(r[sourcePk]) ?? "\0") ?? [];
         continue;
       }
 
@@ -444,7 +493,7 @@ function formatValidationMessage(entityName: string, errors: { field: string; ru
 }
 
 const NUMERIC_SUBTYPES = new Set([
-  FIELD_SUBTYPE_INT, FIELD_SUBTYPE_SHORT, FIELD_SUBTYPE_BYTE,
+  FIELD_SUBTYPE_INT,
   FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT, FIELD_SUBTYPE_DECIMAL,
 ]);
 

package/src/persistence-driver.ts

@@ -12,7 +12,8 @@ export type WhereClause =
   | { kind: "in"; column: string; values: PrimitiveValue[] }
   | { kind: "like"; column: string; pattern: string }
   | { kind: "isNull"; column: string; not: boolean }
-  | { kind: "and"; clauses: WhereClause[] };
+  | { kind: "and"; clauses: WhereClause[] }
+  | { kind: "or"; clauses: WhereClause[] };
 
 export interface OrderBy {
   column: string;

package/src/query-builder.ts

@@ -38,13 +38,15 @@ export interface QueryOpts {
 }
 
 export function resolvePkFields(entity: MetaData): string[] {
-  const primary = entity.ownChildren().find(
+  // Effective children (own + inherited via super) so a TPH subtype resolves
+  // the discriminator base's primary identity (FR-017).
+  const primary = entity.children().find(
     (c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_PRIMARY,
   );
   if (!primary) {
     throw new MetadataError(`Entity '${entity.name}' has no primary identity`, { entity: entity.name });
   }
-  const attr = primary.ownAttr(IDENTITY_ATTR_FIELDS);
+  const attr = primary.attr(IDENTITY_ATTR_FIELDS);
   if (!Array.isArray(attr) || attr.length === 0) {
     throw new MetadataError(`Entity '${entity.name}' primary identity has no @fields`, { entity: entity.name });
   }
@@ -53,14 +55,15 @@ export function resolvePkFields(entity: MetaData): string[] {
 
 function listFieldNames(entity: MetaData): string[] {
   const out: string[] = [];
-  for (const child of entity.ownChildren()) {
+  // Effective children so a TPH subtype's column set is base fields + own.
+  for (const child of entity.children()) {
     if (child.type === TYPE_FIELD) out.push(child.name);
   }
   return out;
 }
 
 function getField(entity: MetaData, fieldName: string): MetaData {
-  const f = entity.ownChildren().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
+  const f = entity.children().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
   if (!f) {
     throw new MetadataError(
       `Unknown field '${fieldName}' on entity '${entity.name}'`,
@@ -208,9 +211,32 @@ export function buildInsertSpec(
   };
 }
 
+/**
+ * A TPH discriminator scope: AND'd into the by-id where so a subtype-scoped
+ * update/delete only matches rows of that subtype (a row of a different
+ * subtype is invisible → not found). `field` is the discriminator FIELD name;
+ * the column is resolved via the entity's naming strategy.
+ */
+export interface DiscriminatorScope {
+  field: string;
+  value: PrimitiveValue;
+}
+
+function byIdWhere(
+  entity: MetaData, id: unknown, scope: DiscriminatorScope | undefined,
+  strategy: ColumnNamingStrategy,
+): WhereClause {
+  const pkColumn = resolveColumnName(getField(entity, resolvePkFields(entity)[0]!), strategy);
+  const pkEq: WhereClause = { kind: "eq", column: pkColumn, value: id as PrimitiveValue };
+  if (scope === undefined) return pkEq;
+  const discColumn = resolveColumnName(getField(entity, scope.field), strategy);
+  return { kind: "and", clauses: [pkEq, { kind: "eq", column: discColumn, value: scope.value }] };
+}
+
 export function buildUpdateSpec(
   entity: MetaData, data: Row, id: unknown,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+  scope?: DiscriminatorScope,
 ): UpdateSpec {
   const values = rowToColumns(entity, data, strategy);
   const pkFields = resolvePkFields(entity);
@@ -220,11 +246,10 @@ export function buildUpdateSpec(
       { entity: entity.name },
     );
   }
-  const pkColumn = resolveColumnName(getField(entity, pkFields[0]!), strategy);
   return {
     table: resolveTableName(entity),
     values,
-    where: { kind: "eq", column: pkColumn, value: id as PrimitiveValue },
+    where: byIdWhere(entity, id, scope, strategy),
     returning: listFieldNames(entity).map((f) => resolveColumnName(getField(entity, f), strategy)),
   };
 }
@@ -232,6 +257,7 @@ export function buildUpdateSpec(
 export function buildDeleteSpec(
   entity: MetaData, id: unknown,
   strategy: ColumnNamingStrategy = DEFAULT_COLUMN_NAMING_STRATEGY,
+  scope?: DiscriminatorScope,
 ): DeleteSpec {
   const pkFields = resolvePkFields(entity);
   if (pkFields.length !== 1) {
@@ -240,9 +266,8 @@ export function buildDeleteSpec(
       { entity: entity.name },
     );
   }
-  const pkColumn = resolveColumnName(getField(entity, pkFields[0]!), strategy);
   return {
     table: resolveTableName(entity),
-    where: { kind: "eq", column: pkColumn, value: id as PrimitiveValue },
+    where: byIdWhere(entity, id, scope, strategy),
   };
 }

package/src/tph.ts

@@ -0,0 +1,46 @@
+// FR-017 — table-per-hierarchy (TPH) discriminator resolution for the runtime.
+//
+// A TPH SUBTYPE is an entity that declares `@discriminatorValue` and `extends`
+// (transitively) a base that declares `@discriminator`. The ObjectManager uses
+// this to:
+//   - inject the discriminator value on create (the entity names the subtype;
+//     the caller never sets it);
+//   - scope every read/update/delete to the subtype (a row of a different
+//     subtype is invisible), mirroring the generated per-subtype route's
+//     cross-subtype 404 and the drizzle-fastify `discriminator` option;
+//   - treat the discriminator as immutable (stripped from update patches).
+//
+// The discriminator FIELD name lives on the base (`@discriminator`); the VALUE
+// lives on the subtype (`@discriminatorValue`). For deep hierarchies the base
+// may be any ancestor, so we walk the resolved super chain to find it.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import { OBJECT_ATTR_DISCRIMINATOR, OBJECT_ATTR_DISCRIMINATOR_VALUE } from "@metaobjectsdev/metadata";
+
+export interface TphSubtype {
+  /** The discriminator field NAME (declared on the base via `@discriminator`). */
+  field: string;
+  /** This subtype's discriminator VALUE (declared via `@discriminatorValue`). */
+  value: string;
+}
+
+/**
+ * If `entity` is a TPH subtype, return its discriminator field + value; else
+ * null. A subtype declares `@discriminatorValue` and inherits `@discriminator`
+ * from an ancestor in its resolved super chain.
+ */
+export function tphSubtypeOf(entity: MetaData): TphSubtype | null {
+  const value = entity.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+  if (value === undefined || value === null) return null;
+
+  // Walk the resolved super chain to find the @discriminator-bearing ancestor.
+  let ancestor: MetaData | undefined = entity.superResolved;
+  while (ancestor !== undefined) {
+    const field = ancestor.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+    if (field !== undefined && field !== null) {
+      return { field: String(field), value: String(value) };
+    }
+    ancestor = ancestor.superResolved;
+  }
+  return null;
+}