@metaobjectsdev/codegen-ts 0.9.0 → 0.10.0

package/src/projection/extract-view-spec.ts

@@ -1,5 +1,6 @@
 import {
   TYPE_FIELD,
+  TYPE_IDENTITY,
   TYPE_ORIGIN,
   TYPE_RELATIONSHIP,
   MetaSource,
@@ -79,26 +80,55 @@ export function projectionViewName(
   return viewName(projection, { columnNamingStrategy });
 }
 
+/**
+ * FR-024 (ADR-0029): the entity NAMED by a node's dotted extends ref — the
+ * owner part of `<owner>.<child>...` resolved as an object. Mirrors the
+ * loader's `_refNamedOwner`: the ref names the anchor, never the physical
+ * declaring ancestor of an inherited child.
+ */
+function refNamedOwner(node: MetaData, root: MetaRoot): MetaObject | undefined {
+  const ref = (node as { superRef?: string }).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 root.findObject(tail.slice(0, dot)) ?? undefined;
+}
+
 function baseEntityFor(
   projection: MetaObject,
   root: MetaRoot,
 ): MetaObject {
-  // v1: base entity is the resolved super (set via `extends:` in metadata).
-  const superModel = projection.superResolved;
-  const superName = superModel?.name ?? projection.superRef;
-  if (!superName) {
-    throw new Error(
-      `Projection ${projection.name}: missing extends — projections must extend a writable entity in v1.`,
-    );
+  // FR-024 base-anchor rules (mirror the loader's _deriveBaseEntity):
+  // 1) the extends-bound identity anchors the base entity;
+  // 2) else the single distinct entity targeted by extends-bound fields.
+  // The pre-FR-024 object-level `extends:` firehose is removed (B4b cutover).
+  //
+  // COUPLING NOTE: this intentionally derives the anchor ONLY from the ref's
+  // named owner (refNamedOwner), NOT the loader's `superResolved.parent`
+  // fallback for a non-dotted identity extends. That fallback is unreachable
+  // here because the loader gate (validate-identity-passthrough →
+  // ERR_PROJECTION_IDENTITY_NOT_EXTENDED) rejects any projection whose identity
+  // is not dotted-extends-bound before codegen runs. If that loader gate is
+  // ever loosened, this function must grow the same fallback.
+  for (const identity of projection
+    .ownChildren()
+    .filter((c) => c.type === TYPE_IDENTITY)) {
+    const named = refNamedOwner(identity, root);
+    if (named !== undefined) return named;
   }
-  const base =
-    superModel instanceof MetaObject ? superModel : root.findObject(superName);
-  if (!base) {
-    throw new Error(
-      `Projection ${projection.name}: extends "${superName}" does not resolve to any entity.`,
-    );
+  const targets = new Set<MetaObject>();
+  for (const f of projection.ownChildren().filter((c) => c.type === TYPE_FIELD)) {
+    const named = refNamedOwner(f, root);
+    if (named !== undefined && named !== projection) targets.add(named);
   }
-  return base;
+  if (targets.size === 1) return [...targets][0]!;
+  throw new Error(
+    `Projection ${projection.name}: cannot derive the base entity — declare an ` +
+      `extends-bound identity (identity.primary { name, extends: "<Entity>.<identity>" }) ` +
+      `to anchor the base (FR-024).`,
+  );
 }
 
 function sourceColumnNameFor(
@@ -270,22 +300,11 @@ function buildSelectSpec(
 ): SelectSpec {
   const columns: SelectColumn[] = [];
 
-  // Inherited fields from extends parent — emit as passthrough on baseAlias.
-  // Skip fields that the projection has overridden with an explicit origin.
-  // fields() is effective-by-default, so multi-level inheritance (base → BaseEntity) works.
-  for (const baseField of base.fields()) {
-    const overridden = projection.ownChildren().find(
-      (c) => c.type === TYPE_FIELD && c.name === baseField.name,
-    );
-    if (overridden) continue;
-    columns.push({
-      kind: "passthrough",
-      fieldName: baseField.name,
-      dbColAlias: sourceColumnNameFor(baseField, ctx),
-      sourceAlias: joinTree.baseAlias,
-      sourceColumn: sourceColumnNameFor(baseField, ctx),
-    });
-  }
+  // FR-024 (ADR-0028): the projection's DECLARED field set IS the exposure —
+  // the inclusive list, fail-closed by construction. The pre-FR-024 loop that
+  // emitted every base-entity field as an implicit passthrough (the firehose)
+  // is removed with the B4b cutover: base columns are declared explicitly as
+  // extends-bound fields (`{ field.int: { name: id, extends: "Program.id" } }`).
 
   // Fields explicitly declared on the projection.
   for (const field of projection.ownChildren()) {

package/src/relation-resolver.ts

@@ -5,11 +5,14 @@
 //
 // Reads identity.reference declarations to determine the physical reference side.
 
-import type { MetaRoot } from "@metaobjectsdev/metadata";
+import type { MetaRoot, MetaObject, MetaRelationship } from "@metaobjectsdev/metadata";
 import {
   RELATIONSHIP_ATTR_CARDINALITY,
   RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_THROUGH,
   CARDINALITY_ONE,
+  CARDINALITY_MANY,
+  deriveM2MFields,
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { variableNameFromEntity } from "./naming.js";
@@ -26,6 +29,22 @@ export interface RelationEntry {
   fkField?: string;
   /** For cardinality 'one': the target entity's PK field (e.g., "id") */
   targetPkField?: string;
+  /**
+   * FR-018 M:N navigation fields. Present only for a many-to-many navigation (a
+   * `@cardinality: "many"` relationship that declares `@through`). The Drizzle
+   * relations() block emits `many(<junction>)` for these; the routes file emits
+   * a `mountM2mRoute(...)` traversal. The junction FK fields are DERIVED from the
+   * junction entity's two `identity.reference` children (the SSOT), never
+   * restated on the relationship.
+   */
+  /** The junction/through entity name (e.g., "PostTag"). M:N entries only. */
+  junctionEntity?: string;
+  /** Junction FK field holding the source-side key (logical field name, e.g. "postId"). M:N only. */
+  sourceJoinField?: string;
+  /** Junction FK field holding the target-side key (logical field name, e.g. "tagId"). M:N only. */
+  targetJoinField?: string;
+  /** Undirected self-join: union both junction FK columns at read time. M:N only. */
+  symmetric?: boolean;
 }
 
 /** Map from entity name → list of relations for that entity's relations() block */
@@ -51,6 +70,16 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
 
     for (const child of obj.relationships()) {
       const cardinality = child.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
+
+      // FR-018 M:N: `@cardinality: "many"` + `@through` — derive the junction FK
+      // columns from the junction's identity.reference children and register a
+      // many(junction) navigation on the source.
+      if (cardinality === CARDINALITY_MANY && child.ownAttr(RELATIONSHIP_ATTR_THROUGH) !== undefined) {
+        const m2m = buildM2mEntry(obj, child as MetaRelationship, root);
+        if (m2m) ensure(obj.name).push(m2m);
+        continue;
+      }
+
       if (cardinality !== CARDINALITY_ONE) continue;
 
       const targetEntityRaw = child.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
@@ -83,5 +112,78 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
     }
   }
 
+  // FR-018: junction entities reached via @through need their two belongs-to
+  // one() sides so the through-table is navigable in the Drizzle relational
+  // query API (db.query.posts.findMany({ with: { tags: { with: { tag: true }}}})).
+  // A junction is any entity named by some M:N relationship's @through.
+  for (const junctionName of collectJunctionNames(root)) {
+    const junction = root.findObject(junctionName);
+    if (!junction) continue;
+    const entries = ensure(junctionName);
+    for (const ref of junction.referenceIdentities()) {
+      const targetRaw = ref.targetEntity;
+      const fkField = ref.fields[0];
+      if (!targetRaw || !fkField) continue;
+      const targetEntity = stripPackage(targetRaw);
+      // The relation member is named after the target entity (camel singular);
+      // multiple references to the same entity (self-join junction) are
+      // disambiguated by the FK field name.
+      const refName = ref.name && ref.name.length > 0
+        ? ref.name
+        : variableNameFromEntity(targetEntity);
+      entries.push({
+        name: refName,
+        cardinality: "one",
+        targetEntity,
+        fkField,
+        targetPkField: "id",
+      });
+    }
+  }
+
   return result;
 }
+
+/** Names of all entities that are the `@through` junction of some M:N relationship. */
+function collectJunctionNames(root: MetaRoot): Set<string> {
+  const names = new Set<string>();
+  for (const obj of root.objects()) {
+    for (const rel of obj.relationships()) {
+      if (rel.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
+      const through = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+      if (through) names.add(stripPackage(through));
+    }
+  }
+  return names;
+}
+
+/**
+ * Build the source-side M:N navigation entry: derive the junction FK fields from
+ * the junction's two identity.reference children (the SSOT), handling hetero /
+ * directed-self-join / symmetric. Returns null (skips the entry) if derivation
+ * fails — the loader validation pass surfaces the actionable error separately.
+ */
+function buildM2mEntry(
+  source: MetaObject,
+  rel: MetaRelationship,
+  root: MetaRoot,
+): RelationEntry | null {
+  const targetRaw = rel.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+  const throughRaw = rel.ownAttr(RELATIONSHIP_ATTR_THROUGH) as string | undefined;
+  if (!targetRaw || !throughRaw) return null;
+  let fields;
+  try {
+    fields = deriveM2MFields(rel, source, root);
+  } catch {
+    return null;
+  }
+  return {
+    name: rel.name,
+    cardinality: "many",
+    targetEntity: stripPackage(targetRaw),
+    junctionEntity: stripPackage(throughRaw),
+    sourceJoinField: fields.sourceField,
+    targetJoinField: fields.targetField,
+    symmetric: rel.symmetric,
+  };
+}

package/src/render-context.ts

@@ -52,6 +52,10 @@ export interface RenderContext {
   relationMap: RelationMap;
   /** Entity name → its metadata package (undefined if the entity has no package). Built once per run. */
   packageOf: Map<string, string | undefined>;
+  /** FR-019: module specifier to import externally-PROVIDED shared enums from
+   *  (`@provided: true` declarations). Undefined when unset — referencing a
+   *  provided enum without it is a codegen-time error. */
+  providedEnumModule?: string;
 }
 
 /** Optional shape — `extStyle`, `omImport`, `columnNamingStrategy`, `apiPrefix`, `outputLayout`, and `packageOf` default if omitted. `packageOf` defaults to an empty Map (correct for flat layout; `runGen` always provides the real map). */

package/src/render-engine/embedded-templates.generated.ts

@@ -0,0 +1,14 @@
+// @generated from templates/*/*.mustache — DO NOT EDIT.
+// Regenerate: bun run scripts/generate-embedded-templates.ts (or scripts/sync-doc-templates.sh).
+//
+// Embedded framework doc templates so they resolve inside the
+// `bun build --compile` standalone `meta` binary, where the on-disk
+// `templates/` directory is unavailable. Keys are provider resolve refs
+// (path under templates/ minus the .mustache suffix).
+export const EMBEDDED_FRAMEWORK_TEMPLATES: Record<string, string> = {
+  "api/agent-api.md": "{{{generatedMarker}}}\n\n# {{title}}\n\nGenerated API reference for {{project}}; call these exactly as written. {{importNote}}\n{{#hasSetup}}\n\n## Setup\n{{#setup}}\n- `{{handle}}` — {{{note}}} `{{{snippetInline}}}`\n{{/setup}}\n{{/hasSetup}}\n{{#units}}\n\n## {{node}}\n{{#groups}}\n\n`{{importHeader}}`\n{{#symbols}}\n- `{{signature}}` — {{usage}}{{#throwsMarker}} {{throwsMarker}}{{/throwsMarker}}\n{{/symbols}}\n{{/groups}}\n{{#example}}\n\nExample:\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/units}}\n",
+  "api/entity-api.md": "{{{generatedMarker}}}\n\n# {{node}} API\n{{#modelPageHref}}\n\n**Model / metadata:** [{{node}}]({{modelPageHref}})\n{{/modelPageHref}}\n\n> Import paths are relative to your generated-output directory.\n{{#hasSetup}}\n\n## Setup\n\nObtain the runtime handles the calls below need:\n{{#setup}}\n\n- `{{handle}}` — {{{note}}}\n\n```ts\n{{{snippet}}}\n```\n{{/setup}}\n{{/hasSetup}}\n{{#unitExample}}\n\n## Example\n\n```ts\n{{{unitExample}}}\n```\n{{/unitExample}}\n{{#sections}}\n\n## {{heading}}\n{{#symbols}}\n\n### `{{signature}}`\n\n{{usage}}\n\n```ts\n{{importLine}}\n```\n{{#hasFields}}\n\n{{fieldsCaption}}:\n\n| Field | Type | Required | Notes |\n|---|---|---|---|\n{{#fieldRows}}\n| `{{field}}` | `{{{type}}}` | {{required}} | {{notes}} |\n{{/fieldRows}}\n{{/hasFields}}\n{{#mountNote}}\n\nMount: {{{mountNote}}}\n{{/mountNote}}\n{{#throws}}\n\nThrows: {{throws}}\n{{/throws}}\n{{#example}}\n\n```ts\n{{{example}}}\n```\n{{/example}}\n{{/symbols}}\n{{/sections}}\n",
+  "api/index.md": "{{{generatedMarker}}}\n\n# {{title}}\n\n{{intro}}\n{{#hasEntities}}\n\n## Entities\n\n{{#entities}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/entities}}\n{{/hasEntities}}\n{{#hasTemplates}}\n\n## Templates\n\n{{#templates}}\n- [{{node}}]({{href}}) — {{summary}} ({{symbolCount}} symbol{{^one}}s{{/one}})\n{{/templates}}\n{{/hasTemplates}}\n",
+  "docs/entity-page.md": "{{{generatedMarker}}}\n\n# {{entity.name}}\n{{#summaryLead}}\n\n{{{.}}}\n{{/summaryLead}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n{{#apiRefs.0}}\n\n**API reference:** {{/apiRefs.0}}{{#apiRefs}}[{{label}}]({{href}}){{^last}} · {{/last}}{{/apiRefs}}{{#apiRefs.0}}\n{{/apiRefs.0}}\n\n{{{preambleHeader}}}\n{{#hasIdentities}}\n\n## Identity\n\n{{#identities}}\n- {{{bullet}}}\n{{/identities}}\n{{/hasIdentities}}\n{{#hasNeighborhoodEr}}\n\n## In context\n\n{{{neighborhoodErBlock}}}\n{{/hasNeighborhoodEr}}\n{{#fields.hasFields}}\n\n## Fields\n\n| Field | Type | Required | Column | Rules |\n|---|---|---|---|---|\n{{#fields.rows}}\n| {{{fieldCell}}} | {{{typeCell}}} | {{requiredCell}} | {{{storageCell}}} | {{{rulesCell}}} |\n{{/fields.rows}}\n{{/fields.hasFields}}\n{{#fieldDetails.hasDetails}}\n\n## Field details\n\n{{#fieldDetails.rows}}\n{{{block}}}\n\n{{/fieldDetails.rows}}\n{{/fieldDetails.hasDetails}}\n{{#hasRelationships}}\n\n## Relationships\n\n{{#relationships}}\n- {{{bullet}}}\n{{/relationships}}\n{{/hasRelationships}}\n{{#hasUsedBy}}\n\n## Used by\n\n{{#usedBy}}\n- {{{bullet}}}\n{{/usedBy}}\n{{/hasUsedBy}}\n",
+  "docs/template-page.md": "{{{generatedMarker}}}\n\n# {{name}}\n{{#descriptionQuote}}\n\n{{{.}}}\n{{/descriptionQuote}}\n\n**Kind:** {{kind}}\n\n## Output\n{{^isEmail}}\n\n- Format: `{{format}}`\n{{/isEmail}}\n{{#isEmail}}\n\nMultipart email — rendered as the following parts:\n\n| Part | Source | Format | Escaping |\n|---|---|---|---|\n{{#parts}}\n| {{label}} | `{{ref}}` | `{{format}}` | {{#escaped}}escaped{{/escaped}}{{^escaped}}raw{{/escaped}} |\n{{/parts}}\n{{/isEmail}}\n\n## Input\n\n- Payload: [`{{payload.name}}`]({{payload.link}})\n{{#hasRequiredTags}}\n- Required fields:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Render contract\n\n- Every field referenced by the template is validated against the payload at generation time; an unknown field fails generation.\n{{#maxChars}}\n- Maximum length: {{.}} characters (rendering longer output fails).\n{{/maxChars}}\n{{#hasRequiredTags}}\n- Required tags must be present:{{#requiredTags}} `{{.}}`{{/requiredTags}}\n{{/hasRequiredTags}}\n\n## Source\n\n{{#sourceRefs}}\n- `{{.}}`\n{{/sourceRefs}}\n{{#templateSourceSection}}\n\n{{{.}}}\n{{/templateSourceSection}}\n\n## Capability\n\n{{capability}}\n",
+};

package/src/render-engine/framework-provider.ts

@@ -16,6 +16,7 @@ import type { Provider } from "@metaobjectsdev/render";
 import { existsSync, readFileSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { EMBEDDED_FRAMEWORK_TEMPLATES } from "./embedded-templates.generated.js";
 
 /** Canonical shipped template — used to verify a candidate framework
  *  templates directory actually contains our defaults. Without this check a
@@ -31,8 +32,11 @@ const CANONICAL_TEMPLATE_REL = "docs/entity-page.md.mustache";
  *
  *  Returns `undefined` when no on-disk templates dir can be found — e.g. inside
  *  the `bun build --compile` standalone binary, whose `import.meta.url` is a
- *  `/$bunfs/root` virtual path with no real `package.json` alongside it. The
- *  embedded-template fallback (see `FileSystemProvider`) covers that case. */
+ *  `/$bunfs/root` virtual path with no real `package.json` alongside it. In that
+ *  case `FrameworkTemplatesProvider.resolve` falls back to the bundled
+ *  `EMBEDDED_FRAMEWORK_TEMPLATES` (embedded-templates.generated.ts), a plain
+ *  string module generated from the canonical templates/docs/*.mustache and
+ *  compiled into the binary. */
 function findFrameworkTemplatesDir(start: string): string | undefined {
   let dir = start;
   while (true) {
@@ -81,23 +85,33 @@ export class FileSystemProvider implements Provider {
 }
 
 /** The framework defaults provider — resolves refs against codegen-ts's own
- *  on-disk `templates/` directory.
+ *  on-disk `templates/` directory, falling back to the bundled
+ *  `EMBEDDED_FRAMEWORK_TEMPLATES` when no on-disk dir exists.
  *
  *  Resolution is lazy: the directory is located on first `resolve()`, not at
  *  module import. This keeps merely importing this module side-effect-free,
  *  which matters for the `bun build --compile` standalone `meta` binary — its
  *  `import.meta.url` is a `/$bunfs/root` virtual path with no on-disk
- *  `templates/` dir, so eager resolution at import time used to throw before
- *  any command (even `--help` or the schema ops `migrate`/`verify --db`) could
- *  run. Now non-codegen commands import cleanly; only the codegen doc path
- *  (which the standalone binary doesn't target) needs the on-disk dir. */
+ *  `templates/` dir.
+ *
+ *  ON-DISK FIRST, then embedded: the source/install layout (and adopter
+ *  overrides chained ahead of this provider via `projectProvider`) always wins,
+ *  so local edits to the shipped package `templates/` still take effect. Only
+ *  when the on-disk dir is unresolved (the compiled binary) — or a ref the dir
+ *  doesn't contain — do we consult the embedded map, which is generated from
+ *  the same canonical templates and compiled into the binary. Unknown refs are
+ *  `undefined` in the map, which is the correct miss. */
 class FrameworkTemplatesProvider implements Provider {
   resolve(ref: string): string | undefined {
+    // On-disk first: dev/install layout, plus shipped-package edits.
     const dir = frameworkTemplatesDir();
-    if (dir === undefined) return undefined;
-    const path = join(dir, `${ref}.mustache`);
-    if (!existsSync(path)) return undefined;
-    return readFileSync(path, "utf-8");
+    if (dir !== undefined) {
+      const path = join(dir, `${ref}.mustache`);
+      if (existsSync(path)) return readFileSync(path, "utf-8");
+    }
+    // Embedded fallback: the binary case (no on-disk dir) or a ref the on-disk
+    // dir doesn't carry. `undefined` for unknown refs is the correct miss.
+    return EMBEDDED_FRAMEWORK_TEMPLATES[ref];
   }
 }
 

package/src/runner.ts

@@ -20,6 +20,10 @@ import {
  *  from untrusted sources (e.g. MCP). Mirrors the guard in legacy generate.ts. */
 const VALID_ENTITY_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 
+/** ADR-0025: doc generators whose single door is `meta docs`. If a `meta gen`
+ *  config still lists one (by its stable `name`), the runner warns + skips it. */
+const DEPRECATED_DOC_GENERATORS = new Set(["docs-file", "api-docs"]);
+
 export interface RunGenOpts {
   config: MetaobjectsGenConfig;
   metadata: MetaData;
@@ -143,9 +147,24 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
     root.objects().map((o) => [o.name, o.package]),
   );
 
+  // Auto-detect: is the OPT-IN Hono routes generator in the active suite? If so,
+  // surface it on every generator's ctx.config so api-docs documents the Hono
+  // CRUD surface it actually emits (rather than silently omitting it).
+  const includeHonoRoutes = config.generators.some((g) => g.emitsHonoRoutes === true);
+
   // 4. Run each generator with a per-target render context; collect with full path.
   const emitted: { fullPath: string; content: string; generatedBy: string }[] = [];
   for (const generator of config.generators) {
+    // ADR-0025: `meta docs` is the single docs door. A `meta gen` config that
+    // still lists a deprecated doc generator is warned + skipped, not run — the
+    // generator stays as `meta docs`'s internal engine.
+    if (DEPRECATED_DOC_GENERATORS.has(generator.name)) {
+      warnings.push(
+        `[${generator.name}] docs are produced by 'meta docs' (ADR-0025); ` +
+        `remove ${generator.name === "api-docs" ? "apiDocsFile()" : "docsFile()"} from generators. Skipped.`,
+      );
+      continue;
+    }
     const selfTarget = targetOf(generator);
     const renderContext = makeRenderContext({
       dialect: config.dialect,
@@ -162,6 +181,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
       packageOf,
       selfTarget,
       entityModuleTarget,
+      ...(config.providedEnumModule !== undefined && { providedEnumModule: config.providedEnumModule }),
     });
     const ctx: GenContext = {
       entities: safeEntities,
@@ -173,6 +193,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
         dbImport: selfTarget.dbImport,
         dialect: config.dialect,
         outputLayout: selfTarget.outputLayout,
+        includeHonoRoutes,
       },
       renderContext,
       ...(projectRoot !== undefined && { projectRoot }),

package/src/templates/docs-file.ts

@@ -22,15 +22,11 @@ export interface DocsRenderOpts {
   dialect: Dialect;
   columnNamingStrategy?: ColumnNamingStrategy;
   loadedRoot: MetaRoot;
-  /** Names of generators present in the pipeline — drives the "Generated code"
-   *  section. Always includes "entity-file" implicitly. Recognized names:
-   *  "queries-file", "routes-file", "routes-file-hono". */
-  generatorNames?: ReadonlySet<string>;
 }
 
 /** Backward-compatible entry point: builds the EntityDocData payload and
- *  renders it via the framework template. Byte-identical to the hand-coded
- *  rc.11 output (gated by `docs-file-conformance.test.ts`). */
+ *  renders it via the framework template. Output is gated by
+ *  `docs-file-conformance.test.ts`. */
 export function renderDocsFile(entity: MetaObject, opts: DocsRenderOpts): string {
   const data = buildEntityDocData(entity, {
     dialect: opts.dialect,
@@ -38,9 +34,6 @@ export function renderDocsFile(entity: MetaObject, opts: DocsRenderOpts): string
       ? { columnNamingStrategy: opts.columnNamingStrategy }
       : {}),
     loadedRoot: opts.loadedRoot,
-    ...(opts.generatorNames !== undefined
-      ? { generatorNames: opts.generatorNames }
-      : {}),
   });
   return render({
     ref: "docs/entity-page.md",

package/src/templates/drizzle-schema.ts

@@ -16,6 +16,7 @@ import { mapColumnType, type ColumnSpec } from "../column-mapper.js";
 import { tableNameFromEntity, variableNameFromEntity, columnNameFromField } from "../naming.js";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { collectTphSubtypeFields } from "./tph-discriminator.js";
 
 /**
  * Render the Drizzle table definition for one entity, including:
@@ -83,6 +84,29 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
     }
   }
 
+  // FR-017 Tier 2 — TPH single-table inheritance. When this entity is a
+  // discriminator base, fold every concrete subtype's own columns into this
+  // one table. Subtype-only columns are ALWAYS nullable (a row of any other
+  // subtype stores NULL there) and never carry a DB default (a default would
+  // stamp onto other-subtype inserts), regardless of the field's @required.
+  // Subtype entities emit no table of their own (the value-object path).
+  for (const child of collectTphSubtypeFields(obj, ctx.loadedRoot)) {
+    const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy);
+    const fieldDocs = renderDocsFor(child);
+    const columnLine = renderColumn(
+      spec, child, ctx, false, undefined, fkMap.get(child.name), isComposite, false, obj.package, true,
+    );
+    columnLines.push(fieldDocs ? code`  ${fieldDocs}\n${columnLine}` : columnLine);
+    // Enum CHECK constraints stay valid under TPH: `NULL IN (...)` is NULL
+    // (not false), so other-subtype rows with NULL pass the check.
+    if (spec.checkConstraint !== undefined) {
+      checkConstraints.push({
+        name: `chk_${tableName}_${spec.dbName}`,
+        expr: spec.checkConstraint,
+      });
+    }
+  }
+
   // Build all table callback entries
   const callbackEntries: Code[] = [];
 
@@ -212,6 +236,9 @@ function renderColumn(
   isComposite: boolean,
   isUnique: boolean = false,
   entityPackage: string | undefined = undefined,
+  // FR-017 Tier 2 — TPH subtype-only column: force nullable (drop .notNull())
+  // and suppress any DB default (other-subtype rows must stay NULL here).
+  forceNullable: boolean = false,
 ): Code {
   const fnSym = imp(`${spec.fnName}@${spec.importModule}`);
 
@@ -261,6 +288,9 @@ function renderColumn(
     if (isPk && !isComposite && (m === ".notNull()" || m === ".unique()")) continue;
     // Avoid double-emitting .unique() if it was already appended above.
     if (isUnique && m === ".unique()") continue;
+    // TPH subtype-only column: never .notNull() / .unique() — rows of other
+    // subtypes store NULL, so neither constraint can hold across the table.
+    if (forceNullable && (m === ".notNull()" || m === ".unique()")) continue;
     modifiersStr += m;
   }
 
@@ -268,7 +298,7 @@ function renderColumn(
   // the `sql` import via imp(); a raw `.default(sql`...`)` would leave `sql`
   // unresolved in the generated file.
   let sqlDefaultSegment: Code | null = null;
-  if (spec.defaultExpr !== undefined && !isPk) {
+  if (spec.defaultExpr !== undefined && !isPk && !forceNullable) {
     if (spec.defaultExpr.kind === "now") {
       if (ctx.dialect === "sqlite") {
         const sqlSym = imp("sql@drizzle-orm");

package/src/templates/entity-constants.ts

@@ -67,7 +67,7 @@ function humanize(s: string): string {
  *   "Subscriber" → "/subscribers"
  *   "WorkoutEvent" → "/workout_events"
  */
-function resourcePath(entity: MetaData): string {
+export function resourcePath(entity: MetaData): string {
   const overrideAttr = entity.ownAttr("routePath");
   if (typeof overrideAttr === "string" && overrideAttr.length > 0) {
     return overrideAttr.startsWith("/") ? overrideAttr : `/${overrideAttr}`;

package/src/templates/entity-file.ts

@@ -15,6 +15,7 @@ import { renderZodValidators } from "./zod-validators.js";
 import { renderEntityConstants } from "./entity-constants.js";
 import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.js";
 import { renderFilterType } from "./filter-type.js";
+import { renderTphDiscriminatorUnion, isTphDiscriminatorBase } from "./tph-discriminator.js";
 import { GENERATED_HEADER } from "../constants.js";
 import { isProjection } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
@@ -53,7 +54,7 @@ export function renderEntityFile(
   // it. The entity-file generator suppresses this entirely when
   // emitAbstractShapes is off; here we only guarantee "shape, never table".
   if (isAbstract(entity)) {
-    return renderValueObjectFile(entity);
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 
   // --- Projection path (read-only: view-backed entity with no table source) ---
@@ -72,19 +73,29 @@ export function renderEntityFile(
   // the shape (LLM tool_use input_schema, REST body parsing) use the Zod
   // schema; consumers that need the type use the interface.
   if (!hasWritableRdbSource(entity)) {
-    return renderValueObjectFile(entity);
+    return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
 
   // --- Vanilla / write-through entity path ---
-  const enumAliases = renderEnumTypeAliases(entity);
+  const enumAliases = renderEnumTypeAliases(entity, ctx);
+  // FR-017 Tier 1: when this entity carries @discriminator AND has concrete
+  // subtypes, append the discriminated-union type alias, type guards, and
+  // the parse<Base>(row) dispatcher. Returns null otherwise (no subtypes, or
+  // not a discriminator-bearing entity); the section is suppressed cleanly.
+  const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
+  // FR-017: when a discriminator base also has a union block, the union owns the
+  // bare `<Base>` type — so the inferred Drizzle row type is emitted as
+  // `<Base>Row` to avoid a duplicate `export type <Base>`.
+  const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
-    renderInferredTypes(entity),
+    renderInferredTypes(entity, tphBase),
     ...(enumAliases !== null ? [enumAliases] : []),
-    renderZodValidators(entity),
+    renderZodValidators(entity, ctx),
     renderEntityConstants(entity, ctx.apiPrefix),
     ...(allowlists ? [renderFilterAllowlist(entity), renderSortAllowlist(entity)] : []),
     renderFilterType(entity),
+    ...(tphBlock !== null ? [tphBlock] : []),
   ];
 
   // Render ts-poet body first (ts-poet hoists imp()-tracked imports to the top),

package/src/templates/enums-file.ts

@@ -0,0 +1,50 @@
+// FR-019 — shared enums module.
+//
+// Emits, ONCE per run, the materialized (non-@provided) shared enum types that
+// at least one concrete entity field references via `extends` of a root-level
+// abstract `field.enum`. Each enum yields:
+//   • `export type <E> = "A" | "B";`   — the cross-port type identity
+//   • `export const <E>Enum = z.enum(["A","B"]);` — the shared Zod validator
+//
+// Consuming entity files import these instead of redeclaring the union inline.
+// @provided enums are NEVER materialized here (they live in hand-written code,
+// imported from the configured providedEnumModule).
+
+import { code, imp, joinCode, type Code } from "ts-poet";
+import type { MetaRoot } from "@metaobjectsdev/metadata";
+import { GENERATED_HEADER } from "../constants.js";
+import { materializedSharedEnums, type SharedEnum } from "../enum-shared.js";
+import { enumUnionString } from "./inferred-types.js";
+
+/** Basename (no extension) of the shared-enums module emitted at the entity-module target root. */
+export const SHARED_ENUMS_BASENAME = "enums";
+
+/** The exported Zod-constant name for a shared enum (`<E>Enum`). */
+export function sharedEnumZodConstName(enumName: string): string {
+  return `${enumName}Enum`;
+}
+
+/** One enum's two declarations (type alias + shared z.enum const). */
+function renderOneSharedEnum(e: SharedEnum): Code {
+  const z = imp("z@zod");
+  const members = e.values.map((v) => JSON.stringify(v)).join(", ");
+  return code`
+export type ${e.name} = ${enumUnionString(e.values)};
+export const ${sharedEnumZodConstName(e.name)} = ${z}.enum([${members}]);
+`;
+}
+
+/**
+ * The full shared-enums module body, or null when the model has no materialized
+ * shared enums (so the generator emits no file at all).
+ */
+export function renderSharedEnumsFile(root: MetaRoot): string | null {
+  const enums = materializedSharedEnums(root);
+  if (enums.length === 0) return null;
+
+  const body = joinCode(enums.map(renderOneSharedEnum), { on: "\n" }).toString();
+  const header =
+    `// ${GENERATED_HEADER} — DO NOT EDIT.\n` +
+    `// Shared enum types (FR-019): one declaration per reused package-level enum.\n`;
+  return header + body;
+}

package/src/templates/extract-delegate-emitter.ts

@@ -1,11 +1,9 @@
 // server/typescript/packages/codegen-ts/src/templates/extract-delegate-emitter.ts
 //
-// FR-010 Plan 2.1 (nested codegen gap) — the runtime-DELEGATING extract emitter.
+// FR-010 — the runtime-DELEGATING extract emitter (the single metadata-driven extract path).
 //
-// The self-contained extract<Name>(text) path (extract-schema-emitter + the baked
-// ExtractSchema) covers scalars / enums / scalar-arrays but leaves nested-object and
-// array-of-object components NULL — the historical FR-010 codegen gap. This module emits
-// the additive delegating overload that CLOSES that gap by wrapping the runtime extract:
+// This module emits the loader-delegating extract entry point that reads the live metadata
+// directly and populates nested-object and array-of-object components in full:
 //
 //   extract<Name>(root: MetaRoot, text, opts?) -> ExtractionResult<<Name>Extracted>
 //
@@ -29,11 +27,12 @@ import {
   FIELD_SUBTYPE_ENUM,
   FIELD_ATTR_OBJECT_REF,
   PACKAGE_SEPARATOR,
+  refMatchesObject,
 } from "@metaobjectsdev/metadata";
 import { fields, isArray, scalarKind, jsonStringLiteral } from "./fr010-field-mapping.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));
 }
 
 /** The @objectRef target VO for a nested-object field, or undefined when unresolvable. */