@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/templates/render-helper.ts

@@ -43,6 +43,7 @@ import {
   TEMPLATE_ATTR_SUBJECT_REF,
   TEMPLATE_ATTR_HTML_BODY_REF,
   TEMPLATE_ATTR_TEXT_BODY_REF,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import {
   verify,
@@ -53,7 +54,7 @@ import {
 } from "@metaobjectsdev/render";
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && refMatchesObject(c, name));
 }
 
 function findTemplate(root: MetaData, name: string): MetaData | undefined {
@@ -192,7 +193,7 @@ export function renderRenderHelper(
 
     return `import { render } from "@metaobjectsdev/render";
 import type { Provider, EmailDocument } from "@metaobjectsdev/render";
-import type { ${payloadRef} } from "./payloads.js";
+import type { ${payloadRef} } from "./${payloadRef}.js";
 
 /**
  * Render the ${templateName} email (subject + html body${typeof textBodyRef === "string" ? " + text body" : ""}) from a
@@ -230,7 +231,7 @@ export function ${fnName}(payload: ${payloadRef}, provider: Provider): EmailDocu
 
   return `import { render } from "@metaobjectsdev/render";
 import type { Provider } from "@metaobjectsdev/render";
-import type { ${payloadRef} } from "./payloads.js";
+import type { ${payloadRef} } from "./${payloadRef}.js";
 
 /**
  * Render the ${templateName} document from a typed ${payloadRef} payload. Wraps the

package/src/templates/routes-file.ts

@@ -15,17 +15,31 @@
 // the existing queries-file template). The entity's Drizzle table const is
 // imported alongside the Zod schemas + constants from the sibling Entity.ts.
 
-import { code, imp } from "ts-poet";
+import { code, imp, joinCode, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
+import {
+  TYPE_FIELD,
+  resolveColumnName,
+} from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
-import { entityModuleSpecifier, relativeModuleSpecifier } from "../import-path.js";
+import { crossEntitySpecifier, entityModuleSpecifier, relativeModuleSpecifier } from "../import-path.js";
 import { GENERATED_HEADER } from "../constants.js";
-import { variableNameFromEntity } from "../naming.js";
+import { variableNameFromEntity, routesHandlerName } from "../naming.js";
 import { isProjection } from "../projection/projection-detector.js";
+import type { RelationEntry } from "../relation-resolver.js";
+import { isTphDiscriminatorBase, tphPlan } from "./tph-discriminator.js";
 
 export function renderRoutesFile(entity: MetaObject, ctx: RenderContext): string {
+  // FR-017 Tier 2 — a TPH discriminator base mounts polymorphic list/get at the
+  // base path plus a full per-subtype CRUD route set scoped to each
+  // discriminator value. (Subtype entities are filtered out of the routes
+  // generator entirely — their routes live here.)
+  if (isTphDiscriminatorBase(entity, ctx.loadedRoot)) {
+    return renderTphRoutesFile(entity, ctx);
+  }
+
   const entityName = entity.name;
-  const handlerName = `${entityName.charAt(0).toLowerCase()}${entityName.slice(1)}Routes`;
+  const handlerName = routesHandlerName(entityName);
   // Import the entity's own file. Same target → relative "./Entity"; cross
   // target → importBase-qualified package path.
   const entityFileSpec = entityModuleSpecifier(
@@ -113,6 +127,19 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   const FastifyInstanceSym = imp("t:FastifyInstance@fastify");
   const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/drizzle-fastify");
 
+  // FR-018 M:N traversal: for each many-to-many navigation declared on this
+  // entity, emit a mountM2mRoute(...) that traverses the junction. The junction
+  // FK columns were derived from the junction's identity.reference children (the
+  // SSOT) by the relation-resolver pre-pass; here we resolve them to physical
+  // column names for the Drizzle two-stage join.
+  const m2mEntries = (ctx.relationMap.get(entityName) ?? []).filter(
+    (e): e is RelationEntry & { junctionEntity: string } => e.junctionEntity !== undefined,
+  );
+  // Two fastify-scope variants: under an apiPrefix the mounts live inside the
+  // register-block (`instance`); otherwise they bind directly to `fastify`.
+  const m2mMountsPrefixed = renderM2mMounts(m2mEntries, entity, ctx, "instance");
+  const m2mMountsFlat = renderM2mMounts(m2mEntries, entity, ctx, "fastify");
+
   const literalImports = code`
 import { db } from ${JSON.stringify(dbImportSpec)};
 import {
@@ -148,7 +175,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
       sortAllowlist: ${entityName}SortAllowlist,
       dialect: ${JSON.stringify(ctx.dialect)},
     });
-  }, { prefix: ${JSON.stringify(ctx.apiPrefix)} });
+${m2mMountsPrefixed}  }, { prefix: ${JSON.stringify(ctx.apiPrefix)} });
 }
 `
     : code`
@@ -172,8 +199,208 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
     sortAllowlist: ${entityName}SortAllowlist,
     dialect: ${JSON.stringify(ctx.dialect)},
   });
-}
+${m2mMountsFlat}}
 `;
 
   return header + literalImports.toString() + body.toString();
 }
+
+/**
+ * Render the M:N traversal mounts for an entity as a single Code fragment to
+ * interpolate INTO the handler-body code template (so the junction/target table
+ * + mountM2mRoute imports hoist with the rest of the body's imports, not inline
+ * mid-function). `fastifyVar` is the in-scope Fastify reference (`instance`
+ * under an apiPrefix register-block, else `fastify`). Returns "" when the entity
+ * has no M:N relationships — CRUD-only output stays byte-identical to before.
+ */
+function renderM2mMounts(
+  entries: ReadonlyArray<RelationEntry & { junctionEntity: string }>,
+  source: MetaObject,
+  ctx: RenderContext,
+  fastifyVar: string,
+): Code | string {
+  if (entries.length === 0) return "";
+  const mounts = entries.map((e) => renderM2mMount(e, source, ctx, fastifyVar));
+  return code`${joinCode(mounts, { on: "\n", trim: false })}
+`;
+}
+
+/**
+ * Render one M:N traversal mount. The junction + target Drizzle table consts are
+ * imported from their sibling entity files (imp() lets ts-poet track + emit the
+ * import). The source/target FK columns + the target PK are resolved to PHYSICAL
+ * column names via resolveColumnName (the runtime two-stage join queries by
+ * column). mountM2mRoute appends `/:id/<relationName>` to the source $path.
+ */
+function renderM2mMount(
+  entry: RelationEntry & { junctionEntity: string },
+  source: MetaObject,
+  ctx: RenderContext,
+  fastifyVar: string,
+): Code {
+  const junctionVarSym = imp(
+    `${variableNameFromEntity(entry.junctionEntity)}@${crossEntitySpecifier(
+      ctx.outputLayout,
+      source.package,
+      ctx.packageOf.get(entry.junctionEntity),
+      entry.junctionEntity,
+      ctx.extStyle,
+    )}`,
+  );
+  const targetVarSym = imp(
+    `${variableNameFromEntity(entry.targetEntity)}@${crossEntitySpecifier(
+      ctx.outputLayout,
+      source.package,
+      ctx.packageOf.get(entry.targetEntity),
+      entry.targetEntity,
+      ctx.extStyle,
+    )}`,
+  );
+  const mountM2mRouteSym = imp("mountM2mRoute@@metaobjectsdev/runtime-ts/drizzle-fastify");
+  const junction = ctx.loadedRoot.findObject(entry.junctionEntity);
+  const target = ctx.loadedRoot.findObject(entry.targetEntity);
+  const sourceColumn = junction
+    ? resolveJunctionColumn(junction, entry.sourceJoinField!, ctx)
+    : entry.sourceJoinField!;
+  const targetColumn = junction
+    ? resolveJunctionColumn(junction, entry.targetJoinField!, ctx)
+    : entry.targetJoinField!;
+  const targetPkColumn = target
+    ? resolveJunctionColumn(target, ctx.pkMap.get(entry.targetEntity)?.fieldName ?? "id", ctx)
+    : "id";
+
+  return code`  ${mountM2mRouteSym}({
+    fastify: ${fastifyVar},
+    path: ${source.name}.$path,
+    relationName: ${JSON.stringify(entry.name)},
+    db,
+    junctionTable: ${junctionVarSym},
+    targetTable: ${targetVarSym},
+    sourceColumn: ${JSON.stringify(sourceColumn)},
+    targetColumn: ${JSON.stringify(targetColumn)},
+    targetPkColumn: ${JSON.stringify(targetPkColumn)},
+    symmetric: ${entry.symmetric ? "true" : "false"},
+  });`;
+}
+
+/** Resolve a field's physical column name on an entity (defaults if missing). */
+function resolveJunctionColumn(entity: MetaObject, fieldName: string, ctx: RenderContext): string {
+  const field = entity.ownChildren().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
+  if (!field) return fieldName;
+  return resolveColumnName(field, ctx.columnNamingStrategy);
+}
+
+/**
+ * FR-017 Tier 2 — the routes file for a TPH discriminator base.
+ *
+ * Mounts a polymorphic list/get route set at the base path (`GET /auths`,
+ * `GET /auths/:id` — rows carry the discriminator by value), then a full
+ * per-subtype CRUD route set at `<basePath>/<discriminatorValue lowercased>`
+ * (`/auths/bridge`, ...). The per-subtype create body OMITS the discriminator
+ * (the URL names the subtype); the runtime helper injects it. The per-subtype
+ * route set is scoped to its discriminator value via the `discriminator` option
+ * (cross-subtype get/update/delete 404; update strips the discriminator).
+ *
+ * Subtype route segment defaults to the lowercased `@discriminatorValue`
+ * (`"Bridge"` → `bridge`) — a robust, value-derived path that matches the
+ * FR-017 design's `/auths/bridge` examples. Fastify resolves the static
+ * `/auths/bridge` ahead of the parametric `/auths/:id`, so the two coexist.
+ */
+function renderTphRoutesFile(base: MetaObject, ctx: RenderContext): string {
+  const baseName = base.name;
+  const handlerName = routesHandlerName(baseName);
+  // Single source of truth for the discriminator field + subtypes + route segments.
+  const plan = tphPlan(base, ctx.loadedRoot)!;
+  const discField = plan.discriminatorField;
+  const tableVar = variableNameFromEntity(baseName);
+
+  const baseFileSpec = entityModuleSpecifier(
+    ctx.selfTarget, ctx.entityModuleTarget, base.package, baseName, ctx.extStyle,
+  );
+  const dbImportSpec = relativeModuleSpecifier(ctx.outputLayout, base.package, ctx.dbImport);
+
+  const FastifyInstanceSym = imp("t:FastifyInstance@fastify");
+  const mountCrudRoutesSym = imp("mountCrudRoutes@@metaobjectsdev/runtime-ts/drizzle-fastify");
+  const dbSym = imp(`db@${dbImportSpec}`);
+  const tableSym = imp(`${tableVar}@${baseFileSpec}`);
+  const baseConstSym = imp(`${baseName}@${baseFileSpec}`);
+  const baseInsertSym = imp(`${baseName}InsertSchema@${baseFileSpec}`);
+  const baseUpdateSym = imp(`${baseName}UpdateSchema@${baseFileSpec}`);
+  const baseFilterSym = imp(`${baseName}FilterAllowlist@${baseFileSpec}`);
+  const baseSortSym = imp(`${baseName}SortAllowlist@${baseFileSpec}`);
+
+  const fastifyRef = ctx.apiPrefix ? "instance" : "fastify";
+  const dialectLit = JSON.stringify(ctx.dialect);
+
+  const polymorphic = code`
+    ${mountCrudRoutesSym}({
+      fastify: ${fastifyRef},
+      path: ${baseConstSym}.$path,
+      db: ${dbSym},
+      table: ${tableSym},
+      insertSchema: ${baseInsertSym},
+      updateSchema: ${baseUpdateSym},
+      filterAllowlist: ${baseFilterSym},
+      sortAllowlist: ${baseSortSym},
+      dialect: ${dialectLit},
+      expose: ["list", "get"],
+    });`;
+
+  const subtypeMounts: Code[] = plan.subtypes.map(({ entity: sub, value, routeSegment: segment }) => {
+    const subFileSpec = entityModuleSpecifier(
+      ctx.selfTarget, ctx.entityModuleTarget, sub.package, sub.name, ctx.extStyle,
+    );
+    const subInsertSym = imp(`${sub.name}InsertSchema@${subFileSpec}`);
+    // FR-017 Tier 3: each subtype carries its OWN filter/sort allowlist
+    // (discriminator excluded — it's pinned by this path).
+    const subFilterSym = imp(`${sub.name}FilterAllowlist@${subFileSpec}`);
+    const subSortSym = imp(`${sub.name}SortAllowlist@${subFileSpec}`);
+    return code`
+    ${mountCrudRoutesSym}({
+      fastify: ${fastifyRef},
+      path: ${baseConstSym}.$path + ${JSON.stringify("/" + segment)},
+      db: ${dbSym},
+      table: ${tableSym},
+      insertSchema: ${subInsertSym}.omit({ ${discField}: true }),
+      updateSchema: ${subInsertSym}.omit({ ${discField}: true }).partial(),
+      filterAllowlist: ${subFilterSym},
+      sortAllowlist: ${subSortSym},
+      dialect: ${dialectLit},
+      discriminator: { column: ${JSON.stringify(discField)}, value: ${JSON.stringify(value)} },
+    });`;
+  });
+
+  const mounts = joinCode([polymorphic, ...subtypeMounts], { on: "\n" });
+
+  const fn = ctx.apiPrefix
+    ? code`
+/**
+ * Mount polymorphic + per-subtype REST endpoints for the ${baseName} TPH hierarchy.
+ *
+ * GET ${baseName}.$path (+ /:id) lists/gets the discriminated union; each
+ * /${baseName}.$path/<subtype> path is a full per-subtype CRUD set.
+ */
+export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
+  await fastify.register(async (instance) => {
+${mounts}
+  }, { prefix: ${JSON.stringify(ctx.apiPrefix)} });
+}
+`
+    : code`
+/**
+ * Mount polymorphic + per-subtype REST endpoints for the ${baseName} TPH hierarchy.
+ *
+ * GET ${baseName}.$path (+ /:id) lists/gets the discriminated union; each
+ * /${baseName}.$path/<subtype> path is a full per-subtype CRUD set.
+ */
+export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
+${mounts}
+}
+`;
+
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Source metadata: ${baseName} (${base.fqn()}) — TPH discriminator base\n` +
+    `// Customize via ${baseName}.extra.ts in this directory (e.g., auth, additional handlers).\n`;
+  return header + fn.toString();
+}

package/src/templates/tph-discriminator.ts

@@ -0,0 +1,232 @@
+// FR-017 Tier 1 — TS discriminated-union + type guards + dispatcher emission.
+//
+// For an entity that carries `@discriminator`, this template emits:
+//   1. `export type <Base> = <Sub1> | <Sub2> | ...` — discriminated union of
+//      every concrete subtype declaring @discriminatorValue against this base.
+//   2. `export function is<Sub>(value: <Base>): value is <Sub>` — one type
+//      guard per subtype, checking the discriminator field's value.
+//   3. `export function parse<Base>(row: unknown): <Base>` — runtime dispatcher
+//      that reads the discriminator off the raw row and parses with the
+//      matching subtype's Zod schema.
+//
+// When the entity does NOT carry @discriminator, returns null. When the entity
+// carries @discriminator but has no concrete subtypes yet (refactor-in-progress
+// shape — covered by FR-014 fixture `tph-discriminator-string-no-subtypes`),
+// returns null too: there are no subtype names to union.
+
+import { code, joinCode, imp, type Code } from "ts-poet";
+import {
+  type MetaObject,
+  type MetaField,
+  type MetaRoot,
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
+  OBJECT_SUBTYPE_ENTITY,
+} from "@metaobjectsdev/metadata";
+
+interface SubtypeBinding {
+  subtype: MetaObject;
+  value: string;
+}
+
+/** One concrete subtype in a {@link TphPlan}. */
+export interface TphSubtypePlan {
+  /** The concrete subtype entity. */
+  entity: MetaObject;
+  /** Its `@discriminatorValue`. */
+  value: string;
+  /** The per-subtype REST route segment (e.g. `"bridge"`). The ONE place this
+   *  rule is derived — see {@link tphRouteSegment}. */
+  routeSegment: string;
+}
+
+/**
+ * The single source of truth for a TPH base's polymorphic shape: the
+ * discriminator field name, the concrete subtypes (stable name-sorted order),
+ * each subtype's `@discriminatorValue`, and its per-subtype route segment.
+ *
+ * Every generator in the stack (entity, queries, routes, hooks, grid, forms)
+ * derives its TPH behavior from this one model rather than re-walking the root
+ * and re-deriving the segment / write-shape independently — so the route-segment
+ * rule and subtype set can never drift between, say, the generated routes and
+ * the generated hooks that call them.
+ */
+export interface TphPlan {
+  base: MetaObject;
+  discriminatorField: string;
+  subtypes: TphSubtypePlan[];
+}
+
+// Memoized per base instance — the plan is pure over the (immutable, fully
+// resolved) post-load model, and a base belongs to exactly one root, so caching
+// by the base node identity is safe and erases the repeated root walks.
+const _tphPlanCache = new WeakMap<MetaObject, TphPlan | null>();
+
+/** The per-subtype REST route segment for a discriminator value. The ONE place
+ *  this rule lives: `routesFile` and the TanStack hooks both read it through the
+ *  plan, so generated hooks can't call a URL the generated routes don't serve. */
+export function tphRouteSegment(discriminatorValue: string): string {
+  return discriminatorValue.toLowerCase();
+}
+
+/** The {@link TphPlan} for a discriminator base, or `null` when `base` is not a
+ *  discriminator base (no `@discriminator`, or no concrete subtypes). */
+export function tphPlan(base: MetaObject, root: MetaRoot): TphPlan | null {
+  const cached = _tphPlanCache.get(base);
+  if (cached !== undefined) return cached;
+  const discriminatorField = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+  let plan: TphPlan | null = null;
+  if (typeof discriminatorField === "string" && discriminatorField !== "") {
+    const bindings = collectConcreteSubtypes(base, root);
+    if (bindings.length > 0) {
+      plan = {
+        base,
+        discriminatorField,
+        subtypes: bindings.map((b) => ({
+          entity: b.subtype,
+          value: b.value,
+          routeSegment: tphRouteSegment(b.value),
+        })),
+      };
+    }
+  }
+  _tphPlanCache.set(base, plan);
+  return plan;
+}
+
+/** True when this entity is a TPH discriminator base — it carries
+ *  `@discriminator` AND at least one concrete subtype declares
+ *  `@discriminatorValue` extending it. This is the predicate the generator
+ *  stack uses to switch into single-table-inheritance emission. */
+export function isTphDiscriminatorBase(obj: MetaObject, root: MetaRoot): boolean {
+  return tphPlan(obj, root) !== null;
+}
+
+/** The concrete subtypes bound to this discriminator base, in stable
+ *  (name-sorted) order. Returns `[]` when `base` is not a discriminator base. */
+export function tphConcreteSubtypes(base: MetaObject, root: MetaRoot): MetaObject[] {
+  return tphPlan(base, root)?.subtypes.map((s) => s.entity) ?? [];
+}
+
+/**
+ * The subtype-only fields that must be folded into the base's single TPH table.
+ * For each concrete subtype, every effective field NOT already on the base is
+ * collected (effective, so fields declared on abstract intermediate levels of a
+ * multi-level hierarchy are captured too). Deduplicated by field name across
+ * subtypes — two subtypes sharing a column name contribute one column. The
+ * caller emits each as a nullable column (rows of other subtypes store NULL).
+ */
+export function collectTphSubtypeFields(base: MetaObject, root: MetaRoot): MetaField[] {
+  const discFieldName = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+  if (typeof discFieldName !== "string" || discFieldName === "") return [];
+
+  const baseFieldNames = new Set(base.fields().map((f) => f.name));
+  const seen = new Set<string>();
+  const out: MetaField[] = [];
+  for (const { subtype } of collectConcreteSubtypes(base, root)) {
+    for (const f of subtype.fields()) {
+      if (baseFieldNames.has(f.name)) continue; // base column — already emitted
+      if (seen.has(f.name)) continue; // shared subtype column — emit once
+      seen.add(f.name);
+      out.push(f);
+    }
+  }
+  return out;
+}
+
+/** Render the TPH union + guards + dispatcher block, or null when the entity
+ *  is not a discriminator-bearing base with at least one concrete subtype. */
+export function renderTphDiscriminatorUnion(
+  base: MetaObject,
+  root: MetaRoot,
+): Code | null {
+  const discFieldName = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+  if (typeof discFieldName !== "string" || discFieldName === "") return null;
+
+  const subtypes = collectConcreteSubtypes(base, root);
+  if (subtypes.length === 0) return null;
+
+  const baseName = base.name;
+
+  // 1. Union type alias. Subtype names are imported lazily via ts-poet `imp()`
+  //    so they resolve cross-module without manual import wiring.
+  const unionMembers: Code[] = subtypes.map((b) => {
+    const sub = imp(`t:${b.subtype.name}@./${b.subtype.name}.js`);
+    return code`${sub}`;
+  });
+  const unionType = code`export type ${baseName} = ${joinCode(unionMembers, { on: " | " })};`;
+
+  // 2. Type guards.
+  const guards: Code[] = subtypes.map((b) => {
+    const sub = imp(`t:${b.subtype.name}@./${b.subtype.name}.js`);
+    return code`
+/** True when value is a ${b.subtype.name} (discriminated by ${discFieldName} === "${b.value}"). */
+export function is${b.subtype.name}(value: ${baseName}): value is ${sub} {
+  return value.${discFieldName} === "${b.value}";
+}`;
+  });
+
+  // 3. Dispatcher. The head-read uses z.object so the discriminator is read
+  //    without committing the row to any subtype yet.
+  const z = imp("z@zod");
+  const enumLiterals = subtypes.map((b) => JSON.stringify(b.value)).join(", ");
+
+  const caseBranches: Code[] = subtypes.map((b) => {
+    const schema = imp(`${b.subtype.name}Schema@./${b.subtype.name}.js`);
+    return code`    case ${JSON.stringify(b.value)}: return ${schema}.parse(row);`;
+  });
+
+  const dispatcher = code`
+/**
+ * Parse a row from the ${baseName} table, dispatching by the
+ * \`${discFieldName}\` discriminator value to the matching subtype's
+ * Zod schema. Throws on unknown discriminator values.
+ */
+export function parse${baseName}(row: unknown): ${baseName} {
+  const head = ${z}.object({ ${discFieldName}: ${z}.enum([${enumLiterals}]) }).parse(row);
+  switch (head.${discFieldName}) {
+${joinCode(caseBranches, { on: "\n" })}
+  }
+}
+`;
+
+  return code`
+${unionType}
+
+${joinCode(guards, { on: "\n" })}
+
+${dispatcher}
+`;
+}
+
+/** Walk every top-level object.entity in the root and return the concrete
+ *  subtypes whose @discriminatorValue is bound to this base via extends.
+ *  Abstract intermediates are skipped (they don't have polymorphic instances). */
+function collectConcreteSubtypes(base: MetaObject, root: MetaRoot): SubtypeBinding[] {
+  const bindings: SubtypeBinding[] = [];
+  for (const obj of root.objects()) {
+    if (obj.subType !== OBJECT_SUBTYPE_ENTITY) continue;
+    if (obj.isAbstract === true) continue;
+    if (obj === base) continue;
+
+    const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+    if (typeof value !== "string" || value === "") continue;
+
+    // Walk this entity's extends chain looking for `base`.
+    let cursor = obj.superResolved;
+    let found = false;
+    while (cursor !== undefined) {
+      if (cursor === base) {
+        found = true;
+        break;
+      }
+      cursor = cursor.superResolved;
+    }
+    if (!found) continue;
+
+    bindings.push({ subtype: obj, value });
+  }
+  // Stable order by subtype name so emission is deterministic.
+  bindings.sort((a, b) => a.subtype.name.localeCompare(b.subtype.name));
+  return bindings;
+}

package/src/templates/value-object-file.ts

@@ -10,16 +10,50 @@
 
 import { joinCode, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
+import type { RenderContext } from "../render-context.js";
 import { renderValueObjectInterface, renderEnumTypeAliases } from "./inferred-types.js";
-import { renderInsertSchemaOnly } from "./zod-validators.js";
+import {
+  renderInsertSchemaOnly,
+  isTphSubtype,
+  renderTphSubtypeReadSchema,
+  tphDiscriminatorPin,
+} from "./zod-validators.js";
+import { renderEntityConstants } from "./entity-constants.js";
+import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
+import { renderFilterType } from "./filter-type.js";
 import { GENERATED_HEADER } from "../constants.js";
 
-export function renderValueObjectFile(obj: MetaObject): string {
-  const enumAliases = renderEnumTypeAliases(obj);
+export function renderValueObjectFile(obj: MetaObject, apiPrefix = "", ctx?: RenderContext): string {
+  const enumAliases = renderEnumTypeAliases(obj, ctx);
+  // FR-017 Tier 2: a TPH subtype lands here (it inherits the base's source.rdb
+  // but declares none of its own). In addition to the insert schema it emits a
+  // full read schema `<Sub>Schema` so parse<Base>(row) can dispatch to it.
+  const tphSubtype = isTphSubtype(obj);
+  const tphReadSchema = tphSubtype ? renderTphSubtypeReadSchema(obj) : null;
+  // FR-017 Tier 3: a TPH subtype also emits its field-metadata constants object
+  // (the `<Sub>` const), so the React form generator can render per-field
+  // labels / rules / inputs the same way it does for ordinary entities.
+  const tphConstants = tphSubtype ? renderEntityConstants(obj, apiPrefix) : null;
+  // FR-017 Tier 3: per-subtype filter + sort allowlists, excluding the
+  // discriminator (it's pinned by the per-subtype route path, so a client must
+  // not filter on it). Included fields are the subtype's own + inherited base
+  // filterable fields. Drives the per-subtype REST routes' filter layer.
+  const discField = tphSubtype ? tphDiscriminatorPin(obj)?.fieldName : undefined;
+  const tphFilterAllowlist = tphSubtype ? renderFilterAllowlist(obj, discField) : null;
+  const tphSortAllowlist = tphSubtype ? renderSortAllowlist(obj, discField) : null;
+  // FR-017 Tier 3: the per-subtype CLIENT filter type, discriminator-excluded —
+  // kept in lockstep with the per-subtype allowlist above so a typed
+  // `<Sub>Filter` can't express a filter the server allowlist would 400.
+  const tphFilterType = tphSubtype ? renderFilterType(obj, discField) : null;
   const sections: Code[] = [
-    renderValueObjectInterface(obj),
+    renderValueObjectInterface(obj, ctx),
     ...(enumAliases !== null ? [enumAliases] : []),
+    ...(tphReadSchema !== null ? [tphReadSchema] : []),
     renderInsertSchemaOnly(obj),
+    ...(tphConstants !== null ? [tphConstants] : []),
+    ...(tphFilterAllowlist !== null ? [tphFilterAllowlist] : []),
+    ...(tphSortAllowlist !== null ? [tphSortAllowlist] : []),
+    ...(tphFilterType !== null ? [tphFilterType] : []),
   ];
   const body = joinCode(sections, { on: "\n" }).toString();
   const header =