@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/templates/mermaid-er.ts

@@ -5,20 +5,28 @@
 // D5: the notes attr is NEVER emitted. Per the Documentation Provider design.
 
 import type { MetaObject, MetaRoot } from "@metaobjectsdev/metadata";
-import { DOC_ATTR_DESCRIPTION } from "@metaobjectsdev/metadata";
+import {
+  DOC_ATTR_DESCRIPTION,
+  FIELD_SUBTYPE_OBJECT,
+  FIELD_ATTR_OBJECT_REF,
+  OBJECT_SUBTYPE_VALUE,
+} from "@metaobjectsdev/metadata";
 import { readDocAttrs } from "./jsdoc.js";
 
-/** Render a docs/model.md body: Mermaid erDiagram + per-entity prose. Abstract
- *  entities are excluded — they have no physical table to put in a diagram
- *  (matches migrate-ts/expected-schema.ts's same filter). */
-export function renderMermaidModel(root: MetaRoot): string {
+/** Render JUST the fenced ```mermaid erDiagram``` block for the whole model
+ *  (entities + identity.reference relationships) — NO per-entity prose. This is
+ *  the single neutral ER-diagram builder; both `renderMermaidModel()` (the
+ *  standalone model.md body) AND the neutral docs OVERVIEW page (`README.md`,
+ *  emitted by the Tier-2 `meta docs` engine) consume it, so there is exactly
+ *  ONE place ER topology is computed — no duplicate graph logic (ADR-0020).
+ *
+ *  Abstract entities are excluded — they have no physical table to put in a
+ *  diagram (matches migrate-ts/expected-schema.ts's same filter). */
+export function renderMermaidErBlock(root: MetaRoot): string {
   const entities = root
     .objects()
     .filter((o) => o.isEntity() && !o.isAbstract);
   const parts: string[] = [];
-
-  parts.push("# Data Model");
-  parts.push("");
   parts.push("```mermaid");
   parts.push("erDiagram");
   for (const line of renderRelationships(entities)) parts.push(`    ${line}`);
@@ -27,6 +35,22 @@ export function renderMermaidModel(root: MetaRoot): string {
     for (const line of renderEntityBlock(entity)) parts.push(`    ${line}`);
   }
   parts.push("```");
+  return parts.join("\n");
+}
+
+/** Render a docs/model.md body: Mermaid erDiagram + per-entity prose. Abstract
+ *  entities are excluded — they have no physical table to put in a diagram
+ *  (matches migrate-ts/expected-schema.ts's same filter). Reuses the shared
+ *  `renderMermaidErBlock()` for the diagram so the ER logic is never duplicated. */
+export function renderMermaidModel(root: MetaRoot): string {
+  const entities = root
+    .objects()
+    .filter((o) => o.isEntity() && !o.isAbstract);
+  const parts: string[] = [];
+
+  parts.push("# Data Model");
+  parts.push("");
+  parts.push(renderMermaidErBlock(root));
   parts.push("");
 
   for (const entity of entities) {
@@ -37,6 +61,150 @@ export function renderMermaidModel(root: MetaRoot): string {
   return parts.join("\n");
 }
 
+/** Render a Mermaid flowchart for ONE focal entity and its direct neighbors
+ *  (1-hop). Three node kinds are surfaced and styled distinctly:
+ *
+ *    - **focal**       — the entity this page is about (deeper blue)
+ *    - **same**        — entity in the focal's own package (blue)
+ *    - **external**    — entity in a different package (dashed gray)
+ *    - **vo**          — value object referenced via `field.object` (rounded
+ *                        purple) — composition rather than FK
+ *
+ *  Every node has a Mermaid `click <node> "./<node>.md"` directive, so the
+ *  rendered SVG is a true navigation surface — click any neighbor to jump to
+ *  its page. Edges are labeled with the field name that connects them.
+ *
+ *  This replaces the previous erDiagram-based renderer: Mermaid 10's erDiagram
+ *  has near-zero styling and no click support, while flowchart supports both.
+ *  The crow's-foot one-to-many notation is dropped — for a 1-hop context
+ *  diagram, "what kind of node is this" matters more than ER cardinality.
+ *
+ *  Returns `undefined` when the focal entity has no neighbors at all, so a
+ *  template can `{{#mini}}…{{/mini}}` and skip the section cleanly. Abstract
+ *  entities are excluded as neighbors (no physical rows). */
+export function renderEntityNeighborhoodErBlock(
+  focal: MetaObject,
+  root: MetaRoot,
+): string | undefined {
+  if (focal.isAbstract) return undefined;
+
+  // Resolve neighbor kind so the flowchart can color/shape it accordingly.
+  // Same-package = focal's effective package; differing or unknown = external.
+  // Value object = object.value subtype. Aborts return classify→undefined.
+  //
+  // `node.package` is the OWN attr only — entities that take their package
+  // from the file-default (`metadata.root: { package: ... }`) leave it
+  // undefined. Use `fileDefaultPackage` as the fallback so cross-file
+  // boundary detection works in the common case where adopters set the
+  // package once at the root, not on every entity. Mirrors the same
+  // resolution rule docs-paths.ts uses for page placement.
+  const byName = new Map<string, MetaObject>();
+  for (const obj of root.objects()) byName.set(obj.name, obj);
+  const effectivePkg = (n: MetaObject) => n.package ?? n.fileDefaultPackage;
+  const focalPackage = effectivePkg(focal);
+
+  const sameDomain = new Set<string>();
+  const external   = new Set<string>();
+  const valueObjs  = new Set<string>();
+
+  type NeighborKind = "same" | "external" | "vo";
+  function classify(name: string): NeighborKind | undefined {
+    if (name === focal.name) return "same";   // self-reference (parent-id etc.)
+    const target = byName.get(name);
+    if (!target) return undefined;
+    if (target.subType === OBJECT_SUBTYPE_VALUE) {
+      valueObjs.add(name);
+      return "vo";
+    }
+    if (target.isAbstract) return undefined;
+    if (effectivePkg(target) === focalPackage) {
+      sameDomain.add(name);
+      return "same";
+    }
+    external.add(name);
+    return "external";
+  }
+
+  const edges: Array<{ from: string; to: string; label: string }> = [];
+
+  // Outgoing FK — focal references other entities.
+  for (const ref of focal.referenceIdentities()) {
+    const target = ref.targetEntity;
+    const field = ref.fields[0];
+    if (typeof target !== "string" || typeof field !== "string") continue;
+    const targetName = target.split("::").pop()!;
+    if (classify(targetName) === undefined) continue;
+    edges.push({ from: focal.name, to: targetName, label: field });
+  }
+
+  // Incoming FK — entities that reference the focal.
+  for (const other of root.objects().filter(o => o.isEntity() && !o.isAbstract)) {
+    if (other.name === focal.name) continue;
+    for (const ref of other.referenceIdentities()) {
+      const target = ref.targetEntity;
+      if (typeof target !== "string") continue;
+      if (target.split("::").pop() !== focal.name) continue;
+      const field = ref.fields[0];
+      if (typeof field !== "string") continue;
+      if (classify(other.name) === undefined) continue;
+      edges.push({ from: other.name, to: focal.name, label: field });
+    }
+  }
+
+  // Value-object composition — `field.object @objectRef ContactInfo` etc.
+  // These aren't FKs (no row-level identity); they're embedded composition.
+  // Surfaced because adopters care: "what's inside this entity's `jsonb`
+  // column?" Click-through to the VO docs answers that.
+  for (const field of focal.fields()) {
+    if (field.subType !== FIELD_SUBTYPE_OBJECT) continue;
+    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    if (typeof ref !== "string" || ref.length === 0) continue;
+    const targetName = ref.split("::").pop()!;
+    if (classify(targetName) === undefined) continue;
+    edges.push({ from: focal.name, to: targetName, label: field.name });
+  }
+
+  if (edges.length === 0) return undefined;
+
+  // Build the flowchart. Nodes first (so all are declared before edges),
+  // then edges, then click directives, then classDefs + class assignments.
+  const allNodes = new Set<string>([focal.name, ...sameDomain, ...external, ...valueObjs]);
+  const parts: string[] = ["```mermaid", "flowchart TB"];
+
+  for (const name of allNodes) {
+    if (valueObjs.has(name)) {
+      // Stadium (rounded-rect) shape signals composition / embedded value.
+      parts.push(`    ${name}(["${name}"])`);
+    } else {
+      // Sharp rectangle for entities.
+      parts.push(`    ${name}["${name}"]`);
+    }
+  }
+  for (const { from, to, label } of edges) {
+    parts.push(`    ${from} -->|"${label}"| ${to}`);
+  }
+  // Click directives — link every node (focal + neighbors) to its docs page.
+  // Flat-layout assumption: `./<Name>.md` lives next to the focal's page.
+  // Package-layout adopters can override the template; the data plumbing
+  // is identical either way.
+  for (const name of allNodes) {
+    parts.push(`    click ${name} "./${name}.md"`);
+  }
+  // Visual styling: 4 node kinds, 4 classes. Color choices are deliberately
+  // muted so the diagram reads as documentation, not infographic art.
+  parts.push("    classDef focal    fill:#dbeafe,stroke:#1e40af,stroke-width:2px,color:#1e293b;");
+  parts.push("    classDef same     fill:#eff6ff,stroke:#3b82f6,color:#1e293b;");
+  parts.push("    classDef external fill:#f3f4f6,stroke:#9ca3af,stroke-dasharray:4 3,color:#374151;");
+  parts.push("    classDef vo       fill:#faf5ff,stroke:#9333ea,color:#1e293b;");
+  parts.push(`    class ${focal.name} focal;`);
+  const sameOthers = [...sameDomain].filter(n => n !== focal.name);
+  if (sameOthers.length > 0) parts.push(`    class ${sameOthers.join(",")} same;`);
+  if (external.size > 0)     parts.push(`    class ${[...external].join(",")} external;`);
+  if (valueObjs.size > 0)    parts.push(`    class ${[...valueObjs].join(",")} vo;`);
+  parts.push("```");
+  return parts.join("\n");
+}
+
 function renderRelationships(entities: MetaObject[]): string[] {
   const lines: string[] = [];
   for (const entity of entities) {

package/src/templates/output-parser.ts

@@ -2,11 +2,12 @@
 //
 // Per-template renderer for template.output codegen. Walks the @payloadRef's
 // value-object into a Zod schema and emits a dual-API parser (parse + safeParse)
-// alongside the schema. The emitted file is self-contained: it derives a
-// local data type via `z.infer<typeof Schema>` and exports it as
-// `<TemplateName>Data`. Consumers wiring `promptRender()` get a structurally
-// identical payload-VO interface in `prompts.ts`; either type can be used
-// interchangeably with parse results.
+// alongside the schema, plus (for json/xml outputs) a single tolerant
+// loader-delegating `extractLenient<Name>WithLoader(root, text)` that delegates to
+// the metadata-driven runtime extract. The emitted file derives a local data type
+// via `z.infer<typeof Schema>` and exports it as `<TemplateName>Data`. Consumers
+// wiring `promptRender()` get a structurally identical payload-VO interface in
+// `prompts.ts`; either type can be used interchangeably with parse results.
 
 import {
   type MetaData,
@@ -18,12 +19,8 @@ import {
   FIELD_ATTR_OBJECT_REF,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
-import {
-  schemaLiteral,
-  mirrorInitializer,
-} from "./extract-schema-emitter.js";
-import { extractMapHelpersUsed } from "./fr010-field-mapping.js";
 import {
   nestedMirrorInterfaces,
   nestedMappers,
@@ -46,7 +43,9 @@ const SCALAR_ZOD: Record<string, string> = {
 };
 
 function findObject(root: MetaData, name: string): MetaData | undefined {
-  return root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  // FR-032 — @payloadRef is FQN 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 findTemplate(root: MetaData, name: string): MetaData | undefined {
@@ -166,96 +165,52 @@ export function ${safeParseName}(
 
   // ---- FR-010 tolerant extract block (json/xml only) ----
   const extractedName = `${templateName}Extracted`;
-  const extractLenientFnName = `extractLenient${templateName}`;
-  const tryExtractLenientName = `tryExtractLenient${templateName}`;
   const extractLenientWithName = `extractLenient${templateName}WithLoader`;
-  const schemaConstName = `${templateName}ExtractSchema`;
   const payloadFqnConst = `${templateName.toUpperCase()}_PAYLOAD_NAME`;
   const formatEnum = format.toLowerCase() === "xml" ? "Format.XML" : "Format.JSON";
-  const schemaLit = schemaLiteral(vo, format, payloadRef);
-  const initializer = mirrorInitializer(vo);
-  const mapHelpers = extractMapHelpersUsed(vo);
 
-  // The nullable mirror is shared by BOTH extract paths. Use the nested-aware emitter so the
-  // payload mirror's nested-object / array-of-object components are typed (not `unknown`), and
-  // so a mirror interface is emitted for every reachable nested value-object. The payload mirror
-  // keeps the canonical `<Template>Extracted` name (instead of `<PayloadVO>Extracted`) so the
-  // existing self-contained extract<Name>() initializer continues to satisfy it.
+  // The nullable mirror is the return shape of the delegating extract. Use the nested-aware
+  // emitter so the payload mirror's nested-object / array-of-object components are typed (not
+  // `unknown`), and so a mirror interface is emitted for every reachable nested value-object.
+  // The payload mirror keeps the canonical `<Template>Extracted` name.
   const mirrorDecls = nestedMirrorInterfaces(vo, root, extractedName);
-  const payloadHasNested = hasNested(vo, root);
-
-  // Render-package imports the extract block needs. Only pull in the names the emitted
-  // source actually references, so the file has no unused imports (tsc noUnusedLocals-safe).
-  const renderImports = ["extract", "extractSchema", "Format"];
-  if (schemaLit.includes("scalar(")) renderImports.push("scalar");
-  if (schemaLit.includes("enumField(")) renderImports.push("enumField");
-  if (schemaLit.includes("FieldKind.")) renderImports.push("FieldKind");
-  renderImports.push("type ExtractSchema", "type ExtractOptions", "type ExtractionResult");
-  renderImports.push(...mapHelpers);
-
-  const selfContained = `/** Baked extract descriptor for the ${templateName} output. */
-const ${schemaConstName}: ExtractSchema = ${schemaLit};
-
-${mirrorDecls}
-
-/**
- * Self-contained tolerant best-effort extraction of a dirty LLM response; never throws.
- * Returns a nullable mirror (\`${extractedName}\`) with fields null where lost/malformed,
- * plus the per-field extraction report. Does NOT populate nested-object / array-of-object
- * components (those stay null — the historical FR-010 gap). For full nested extraction, use
- * \`${extractLenientWithName}(root, text)\`, which delegates to the runtime extract.
- */
-export function ${extractLenientFnName}(
-  text: string,
-  opts?: ExtractOptions,
-): ExtractionResult<${extractedName}> {
-  const outcome = extract(text, ${schemaConstName}, opts);
-  const d = outcome.data;
-  const data: ${extractedName} = ${initializer};
-  return { data, report: outcome.report };
-}
 
-/**
- * Extraction as a bool gate: \`true\` when the response was non-empty and no required
- * field was lost. On success, \`result\` carries the extracted mirror + report.
- */
-export function ${tryExtractLenientName}(
-  text: string,
-): { ok: boolean; result: ExtractionResult<${extractedName}> } {
-  const result = ${extractLenientFnName}(text);
-  const ok = !result.report.isEmpty() && !result.report.hasLostRequired();
-  return { ok, result };
-}
-`;
+  // Render-package imports the (single, loader-delegating) extract block needs. Kept minimal so
+  // the file has no unused imports (tsc noUnusedLocals-safe).
+  const renderImports = ["Format", "type ExtractOptions", "type ExtractionResult"];
 
-  // ---- Runtime-delegating extract (closes the nested gap) ----
+  // ---- Runtime-delegating extract (the single metadata-driven extract path) ----
   // Resolves this payload's MetaObject from a loaded MetaRoot by its baked simple name and
   // delegates to extractObject() in @metaobjectsdev/runtime-ts, which assembles the FULL nested
-  // object graph reflection-free. The assembled ValueObject graph is then mapped into the typed
-  // nullable mirror graph by the generated from<VO>Extracted mappers. Codegen-wrapping-runtime
-  // (a generated DAO calling the dynamic-metadata runtime) — mirrors the Java/Kotlin pilots.
+  // object graph reflection-free by reading the live metadata directly. The assembled ValueObject
+  // graph is then mapped into the typed nullable mirror graph by the generated from<VO>Extracted
+  // mappers. Codegen-wrapping-runtime (a generated DAO calling the dynamic-metadata runtime).
   //
   // The baked PAYLOAD_NAME is the resolved payload VO's SIMPLE name (root.findObject matches on
   // the object's `name`, not its FQN). The root mapper is named for the TEMPLATE (so it returns
   // the canonically-named `<Template>Extracted` mirror); nested mappers use their VO names.
   const payloadName = vo.name;
   const rootMapper = rootMapperName(templateName);
+  void hasNested;
   const delegating = `
 /** Payload value-object name this parser extracts — resolved against a loaded MetaRoot at runtime. */
 export const ${payloadFqnConst} = ${JSON.stringify(payloadName)};
 
+${mirrorDecls}
+
 ${nestedMappers(vo, root, rootMapper, extractedName)}
 
 ${delegateHelpers(usedHelpers(vo, root))}
 
 /**
- * Runtime-delegating tolerant extraction; never throws. Unlike \`${extractLenientFnName}(text)\`, this FULLY
- * populates nested-object and array-of-object components by delegating to the metadata-driven
- * runtime \`extractObject\` (which assembles the whole graph reflection-free via the Phase A object
- * model), then maps the assembled graph into the typed \`${extractedName}\` mirror.
+ * Runtime-delegating tolerant best-effort extraction; never throws. FULLY populates
+ * nested-object and array-of-object components by delegating to the metadata-driven runtime
+ * \`extractObject\` (which assembles the whole graph reflection-free via the Phase A object
+ * model, reading the live metadata directly), then maps the assembled graph into the typed
+ * \`${extractedName}\` mirror.
  *
  * @param root a loaded MetaRoot (e.g. \`(await new MetaDataLoader().load(...)).root\`) that declares
- *             the \`${payloadRef}\` value-object.
+ *             the \`${payloadName}\` value-object.
  */
 export function ${extractLenientWithName}(
   root: MetaRoot,
@@ -272,9 +227,6 @@ export function ${extractLenientWithName}(
 `;
 
   // The delegating overload needs runtime-ts (extractObject) + the MetaRoot type from metadata.
-  // It is always emitted (the gap-closing path), regardless of whether THIS payload has nested
-  // fields — a flat payload still benefits from the loader-driven path and keeps the API uniform.
-  void payloadHasNested;
   const metadataImport = `import type { MetaRoot } from "@metaobjectsdev/metadata";\n`;
   const runtimeImport = `import { extractObject } from "@metaobjectsdev/runtime-ts";\n`;
 
@@ -285,7 +237,6 @@ export function ${extractLenientWithName}(
     runtimeImport +
     `\n` +
     `${strictBody}\n` +
-    `${selfContained}\n` +
     `${delegating}`
   );
 }

package/src/templates/output-prompt.ts

@@ -17,11 +17,12 @@ import {
   TEMPLATE_SUBTYPE_OUTPUT,
   TEMPLATE_ATTR_PAYLOAD_REF,
   TEMPLATE_ATTR_FORMAT,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import { specLiteral } from "./output-format-spec-emitter.js";
 
 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 {

package/src/templates/queries-file.ts

@@ -1,8 +1,12 @@
 // Queries file composer — composes all CRUD function renderers (from queries.ts) into
 // a complete <Entity>.queries.ts file with @generated header and correct imports.
 
-import { code, joinCode, type Code } from "ts-poet";
-import { MetaObject } from "@metaobjectsdev/metadata";
+import { code, joinCode, imp, type Code } from "ts-poet";
+import {
+  MetaObject,
+  OBJECT_ATTR_DISCRIMINATOR,
+  OBJECT_ATTR_DISCRIMINATOR_VALUE,
+} from "@metaobjectsdev/metadata";
 import { type RenderContext } from "../render-context.js";
 import { entityModuleSpecifier } from "../import-path.js";
 import {
@@ -11,11 +15,21 @@ import {
   renderCreateFn,
   renderUpdateFn,
   renderDeleteByIdFn,
+  getPkInfo,
 } from "./queries.js";
-import { variableNameFromEntity } from "../naming.js";
+import { variableNameFromEntity, pluralize } from "../naming.js";
 import { GENERATED_HEADER } from "../constants.js";
+import { isTphDiscriminatorBase, tphConcreteSubtypes } from "./tph-discriminator.js";
 
 export function renderQueriesFile(obj: MetaObject, ctx: RenderContext): string {
+  // FR-017 Tier 2 — a TPH discriminator base gets a polymorphic queries file:
+  // base reads dispatch through parse<Base>, and per-subtype CRUD targets the
+  // single base table scoped to the discriminator value. (Subtype entities are
+  // filtered out of the queries generator entirely — their CRUD lives here.)
+  if (isTphDiscriminatorBase(obj, ctx.loadedRoot)) {
+    return renderTphQueriesFile(obj, ctx);
+  }
+
   const entityName = obj.name;
   // Import the entity's own file. Same target → relative "./Entity"; cross
   // target → importBase-qualified package path.
@@ -68,3 +82,118 @@ import { ${varName}, type ${entityName}, ${entityName}InsertSchema } from ${JSON
     `// Customize via ${entityName}.extra.ts in this directory (additional queries, custom logic).\n`;
   return header + body;
 }
+
+/**
+ * FR-017 Tier 2 — the polymorphic + per-subtype queries file for a TPH base.
+ *
+ * Base reads (`find<Base>ById`, `list<BasePlural>`) project every row through
+ * `parse<Base>` so they return the discriminated union. There is intentionally
+ * NO `create<Base>` / `update<Base>` — you cannot instantiate an abstract base.
+ *
+ * Each concrete subtype gets list / findById (filtered to the discriminator
+ * value, parsed with `<Sub>Schema`) plus create / updateById / deleteById, all
+ * against the single base table. Creates inject the discriminator value;
+ * updates strip it (a row's subtype is immutable).
+ */
+function renderTphQueriesFile(base: MetaObject, ctx: RenderContext): string {
+  const baseName = base.name;
+  const tableVar = variableNameFromEntity(baseName);
+  const discField = base.ownAttr(OBJECT_ATTR_DISCRIMINATOR) as string;
+  const { fieldName: pkField, tsType: pkType } = getPkInfo(base, ctx);
+
+  const baseFileSpec = entityModuleSpecifier(
+    ctx.selfTarget, ctx.entityModuleTarget, base.package, baseName, ctx.extStyle,
+  );
+  const tableSym = imp(`${tableVar}@${baseFileSpec}`);
+  const baseTypeSym = imp(`t:${baseName}@${baseFileSpec}`);
+  const parseSym = imp(`parse${baseName}@${baseFileSpec}`);
+  const eqSym = imp("eq@drizzle-orm");
+  const andSym = imp("and@drizzle-orm");
+
+  const dbTypeImport =
+    ctx.dialect === "postgres"
+      ? `import type { NodePgDatabase } from "drizzle-orm/node-postgres";`
+      : `import type { BaseSQLiteDatabase } from "drizzle-orm/sqlite-core";`;
+  const dbTypeAlias =
+    ctx.dialect === "postgres"
+      ? `type Db = NodePgDatabase<Record<string, never>>;`
+      : `type Db = BaseSQLiteDatabase<"async", Record<string, never>>;`;
+
+  // --- Polymorphic base reads ---
+  const polymorphic = code`
+export async function find${baseName}ById(db: Db, ${pkField}: ${pkType}): Promise<${baseTypeSym} | null> {
+  const [row] = await db.select().from(${tableSym}).where(${eqSym}(${tableSym}.${pkField}, ${pkField})).limit(1);
+  return row ? ${parseSym}(row) : null;
+}
+
+export async function list${pluralize(baseName)}(db: Db, opts?: { limit?: number; offset?: number }): Promise<${baseTypeSym}[]> {
+  let q = db.select().from(${tableSym}).$dynamic();
+  if (opts?.limit !== undefined) q = q.limit(opts.limit);
+  if (opts?.offset !== undefined) q = q.offset(opts.offset);
+  const rows = await q;
+  return rows.map((r) => ${parseSym}(r));
+}
+`;
+
+  // --- Per-subtype CRUD against the single base table ---
+  const subtypeSections: Code[] = [];
+  for (const sub of tphConcreteSubtypes(base, ctx.loadedRoot)) {
+    const value = sub.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE) as string;
+    const valueLit = JSON.stringify(value);
+    const subFileSpec = entityModuleSpecifier(
+      ctx.selfTarget, ctx.entityModuleTarget, sub.package, sub.name, ctx.extStyle,
+    );
+    const subTypeSym = imp(`t:${sub.name}@${subFileSpec}`);
+    const subSchemaSym = imp(`${sub.name}Schema@${subFileSpec}`);
+    const subInsertSym = imp(`${sub.name}InsertSchema@${subFileSpec}`);
+
+    subtypeSections.push(code`
+export async function list${pluralize(sub.name)}(db: Db, opts?: { limit?: number; offset?: number }): Promise<${subTypeSym}[]> {
+  let q = db.select().from(${tableSym}).where(${eqSym}(${tableSym}.${discField}, ${valueLit})).$dynamic();
+  if (opts?.limit !== undefined) q = q.limit(opts.limit);
+  if (opts?.offset !== undefined) q = q.offset(opts.offset);
+  const rows = await q;
+  return rows.map((r) => ${subSchemaSym}.parse(r));
+}
+
+export async function find${sub.name}ById(db: Db, ${pkField}: ${pkType}): Promise<${subTypeSym} | null> {
+  const [row] = await db.select().from(${tableSym})
+    .where(${andSym}(${eqSym}(${tableSym}.${pkField}, ${pkField}), ${eqSym}(${tableSym}.${discField}, ${valueLit}))).limit(1);
+  return row ? ${subSchemaSym}.parse(row) : null;
+}
+
+export async function create${sub.name}(db: Db, data: unknown): Promise<${subTypeSym}> {
+  const validated = ${subInsertSym}.parse(data);
+  const [row] = await db.insert(${tableSym}).values({ ...validated, ${discField}: ${valueLit} }).returning();
+  return ${subSchemaSym}.parse(row!);
+}
+
+export async function update${sub.name}ById(db: Db, ${pkField}: ${pkType}, data: unknown): Promise<${subTypeSym} | null> {
+  const validated = ${subInsertSym}.partial().parse(data) as Record<string, unknown>;
+  // The discriminator is immutable — a ${sub.name} can never become another subtype.
+  const { [${JSON.stringify(discField)}]: _disc, ...safe } = validated;
+  const [row] = await db.update(${tableSym}).set(safe)
+    .where(${andSym}(${eqSym}(${tableSym}.${pkField}, ${pkField}), ${eqSym}(${tableSym}.${discField}, ${valueLit}))).returning();
+  return row ? ${subSchemaSym}.parse(row) : null;
+}
+
+export async function delete${sub.name}ById(db: Db, ${pkField}: ${pkType}): Promise<boolean> {
+  const deleted = await db.delete(${tableSym})
+    .where(${andSym}(${eqSym}(${tableSym}.${pkField}, ${pkField}), ${eqSym}(${tableSym}.${discField}, ${valueLit}))).returning();
+  return deleted.length > 0;
+}
+`);
+  }
+
+  const literalImports = code`
+${dbTypeImport}
+${dbTypeAlias}
+`;
+
+  const body = joinCode([literalImports, polymorphic, ...subtypeSections], { on: "\n" }).toString();
+  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 (additional queries, custom logic).\n`;
+  return header + body;
+}

package/src/templates/queries.ts

@@ -5,10 +5,18 @@ import { code, imp, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import { IDENTITY_ATTR_FIELDS } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "../render-context.js";
-import { variableNameFromEntity, pluralize } from "../naming.js";
+import {
+  variableNameFromEntity,
+  pluralize,
+  findByIdFnName,
+  listFnName,
+  createFnName,
+  updateFnName,
+  deleteByIdFnName,
+} from "../naming.js";
 
 /** Get the PK field name and its TS type for a given entity. */
-function getPkInfo(entity: MetaObject, ctx: RenderContext): { fieldName: string; tsType: string } {
+export function getPkInfo(entity: MetaObject, ctx: RenderContext): { fieldName: string; tsType: string } {
   // Use primaryIdentity() to find the primary identity (may be inherited from extends:/super:).
   const primary = entity.primaryIdentity();
   const rawFields = primary?.ownAttr(IDENTITY_ATTR_FIELDS);
@@ -30,7 +38,7 @@ export function renderFindByIdFn(entity: MetaObject, ctx: RenderContext): Code {
   const entityName = entity.name;
   const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const { fieldName: pkField, tsType: pkType } = getPkInfo(entity, ctx);
-  const fnName = `find${entityName}ById`;
+  const fnName = findByIdFnName(entityName);
   const eqSym = imp("eq@drizzle-orm");
 
   return code`
@@ -46,7 +54,7 @@ export function renderListFn(entity: MetaObject, _ctx: RenderContext): Code {
   const entityName = entity.name;
   // Pluralize the PascalCase entity name, preserving capitalization
   // (e.g., "Category" -> "Categories", not "Categorys").
-  const fnName = `list${pluralize(entityName)}`;
+  const fnName = listFnName(entityName);
 
   return code`
 export async function ${fnName}(db: Db, opts?: { limit?: number; offset?: number }): Promise<${entityName}[]> {
@@ -62,7 +70,7 @@ export function renderCreateFn(entity: MetaObject, _ctx: RenderContext): Code {
   const varName = variableNameFromEntity(entity.name);
   const entityName = entity.name;
   const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
-  const fnName = `create${entityName}`;
+  const fnName = createFnName(entityName);
   const schemaName = `${entityName}InsertSchema`;
 
   return code`
@@ -79,7 +87,7 @@ export function renderUpdateFn(entity: MetaObject, ctx: RenderContext): Code {
   const entityName = entity.name;
   const singularVar = entityName.charAt(0).toLowerCase() + entityName.slice(1);
   const { fieldName: pkField, tsType: pkType } = getPkInfo(entity, ctx);
-  const fnName = `update${entityName}`;
+  const fnName = updateFnName(entityName);
   const schemaName = `${entityName}InsertSchema`;
   const eqSym = imp("eq@drizzle-orm");
 
@@ -96,7 +104,7 @@ export function renderDeleteByIdFn(entity: MetaObject, ctx: RenderContext): Code
   const varName = variableNameFromEntity(entity.name);
   const entityName = entity.name;
   const { fieldName: pkField, tsType: pkType } = getPkInfo(entity, ctx);
-  const fnName = `delete${entityName}ById`;
+  const fnName = deleteByIdFnName(entityName);
   const eqSym = imp("eq@drizzle-orm");
 
   return code`

package/src/templates/relations-block.ts

@@ -46,6 +46,23 @@ function renderRelationEntry(
   thisVarName: string,
   thisEntityPackage: string | undefined,
 ): Code {
+  // FR-018 M:N: the source navigates through the junction table, so the Drizzle
+  // many() targets the JUNCTION, not the target entity (the relational query API
+  // then hops junction → target via the junction's one() sides). The
+  // mountM2mRoute the routes generator emits performs the flattened two-stage
+  // traversal for the REST contract.
+  if (entry.cardinality === CARDINALITY_MANY && entry.junctionEntity !== undefined) {
+    const junctionSpec = crossEntitySpecifier(
+      ctx.outputLayout,
+      thisEntityPackage,
+      ctx.packageOf.get(entry.junctionEntity),
+      entry.junctionEntity,
+      ctx.extStyle,
+    );
+    const junctionVarSym = imp(`${variableNameFromEntity(entry.junctionEntity)}@${junctionSpec}`);
+    return code`  ${entry.name}: many(${junctionVarSym})`;
+  }
+
   // Use imp() for cross-entity references so ts-poet tracks and emits the import.
   const targetSpec = crossEntitySpecifier(
     ctx.outputLayout,