@metaobjectsdev/codegen-ts 0.9.0 → 0.11.0-rc.1

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, ctx) : 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] : []),
-    renderInsertSchemaOnly(obj),
+    ...(tphReadSchema !== null ? [tphReadSchema] : []),
+    renderInsertSchemaOnly(obj, ctx),
+    ...(tphConstants !== null ? [tphConstants] : []),
+    ...(tphFilterAllowlist !== null ? [tphFilterAllowlist] : []),
+    ...(tphSortAllowlist !== null ? [tphSortAllowlist] : []),
+    ...(tphFilterType !== null ? [tphFilterType] : []),
   ];
   const body = joinCode(sections, { on: "\n" }).toString();
   const header =

package/src/templates/zod-validators.ts

@@ -10,7 +10,7 @@
 // downstream (e.g. to LLM tool_use input_schema) lost the nested object shape.
 
 import { code, joinCode, imp, type Code } from "ts-poet";
-import { MetaObject, MetaField } from "@metaobjectsdev/metadata";
+import { MetaObject, MetaField, stripPackage } from "@metaobjectsdev/metadata";
 import {
   FIELD_SUBTYPE_STRING, FIELD_SUBTYPE_INT, FIELD_SUBTYPE_LONG, FIELD_SUBTYPE_CURRENCY,
   FIELD_SUBTYPE_BOOLEAN, FIELD_SUBTYPE_DOUBLE, FIELD_SUBTYPE_FLOAT,
@@ -24,18 +24,92 @@ import {
   AUTO_SET_ON_CREATE, AUTO_SET_ON_UPDATE,
   VALIDATOR_ATTR_MAX, VALIDATOR_ATTR_MIN, VALIDATOR_ATTR_PATTERN,
   GENERATION_INCREMENT, GENERATION_UUID,
+  OBJECT_ATTR_DISCRIMINATOR, OBJECT_ATTR_DISCRIMINATOR_VALUE,
 } from "@metaobjectsdev/metadata";
 import { enumValues, zodEnumExpr } from "../enum-meta.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { sharedEnumForField } from "../enum-shared.js";
+import { sharedEnumImportSpecifier } from "../enum-import.js";
+import { sharedEnumZodConstName } from "./enums-file.js";
+import type { RenderContext } from "../render-context.js";
+import { valueObjectModuleSpecifier } from "../import-path.js";
+
+/**
+ * FR-017 Tier 1 — when this object is a TPH subtype (@discriminatorValue set
+ * and an ancestor carries @discriminator), return the discriminator-field-name
+ * → pinned-literal-value pair. Subtypes emit `<field>: z.literal("<value>")`
+ * instead of the inherited field's normal type expression. Returns undefined
+ * when the object is not a TPH subtype.
+ */
+export function tphDiscriminatorPin(obj: MetaObject): { fieldName: string; value: string } | undefined {
+  const value = obj.ownAttr(OBJECT_ATTR_DISCRIMINATOR_VALUE);
+  if (typeof value !== "string" || value === "") return undefined;
+
+  // Walk the extends chain to find the root carrying @discriminator.
+  let cursor = obj.superResolved;
+  while (cursor !== undefined) {
+    const fieldName = cursor.ownAttr(OBJECT_ATTR_DISCRIMINATOR);
+    if (typeof fieldName === "string" && fieldName !== "") {
+      return { fieldName, value };
+    }
+    cursor = cursor.superResolved;
+  }
+  return undefined;
+}
+
+/** True when this object is a TPH subtype — it declares @discriminatorValue
+ *  and an ancestor carries @discriminator. */
+export function isTphSubtype(obj: MetaObject): boolean {
+  return tphDiscriminatorPin(obj) !== undefined;
+}
+
+/**
+ * FR-017 Tier 2 — the per-subtype FULL read schema `<Sub>Schema`. Unlike the
+ * insert schema, this includes every effective field (PK included) so a raw DB
+ * row parses through it. The discriminator field is pinned to its literal value
+ * (`type: z.literal("Bridge")`) so the schema rejects a row of another subtype.
+ *
+ * This is the schema parse<Base>(row) dispatches to (see tph-discriminator.ts).
+ * Non-required columns are `.nullable()`-tolerant: a nullable TPH column read
+ * back from the DB arrives as `null`, not `undefined`, so the read schema must
+ * accept null (the insert schema, by contrast, makes them `.optional()`).
+ */
+export function renderTphSubtypeReadSchema(obj: MetaObject, ctx?: RenderContext): Code {
+  const z = imp("z@zod");
+  const tphPin = tphDiscriminatorPin(obj);
+
+  const fieldLines: Code[] = [];
+  for (const child of obj.fields()) {
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      fieldLines.push(code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`);
+      continue;
+    }
+    const expr = zodFieldExpr(child, obj, ctx);
+    // zodFieldExpr already appends `.optional()` for non-required fields; add
+    // `.nullable()` on top so a NULL column value (the TPH default for any
+    // subtype-only column) parses cleanly.
+    fieldLines.push(
+      fieldWillBeOptional(child) ? code`  ${child.name}: ${expr}.nullable()` : code`  ${child.name}: ${expr}`,
+    );
+  }
+
+  const docs = renderDocsFor(obj);
+  const docsPrefix = docs ? `${docs}\n` : "";
+  return code`
+${docsPrefix}export const ${obj.name}Schema = ${z}.object({
+${joinCode(fieldLines, { on: ",\n" })}
+});
+`;
+}
 
 /** Auto-generated PK field names that should be omitted from InsertSchema. */
 function autoGenPkFieldNames(obj: MetaObject): Set<string> {
   const out = new Set<string>();
   const primary = obj.primaryIdentity();
   if (primary) {
-    const generation = primary.ownAttr(IDENTITY_ATTR_GENERATION);
+    const generation = primary.attr(IDENTITY_ATTR_GENERATION);
     if (generation === GENERATION_INCREMENT || generation === GENERATION_UUID) {
-      const fields = primary.ownAttr(IDENTITY_ATTR_FIELDS);
+      const fields = primary.attr(IDENTITY_ATTR_FIELDS);
       const fieldsList = Array.isArray(fields) ? fields : (typeof fields === "string" ? [fields] : []);
       for (const f of fieldsList) out.add(String(f));
     }
@@ -52,9 +126,10 @@ function autoGenPkFieldNames(obj: MetaObject): Set<string> {
  * so consumer imports don't churn. A future polish PR could add a `<Name>Schema`
  * alias for clarity.
  */
-export function renderInsertSchemaOnly(obj: MetaObject): Code {
+export function renderInsertSchemaOnly(obj: MetaObject, ctx?: RenderContext): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
   for (const child of obj.fields()) {
@@ -62,16 +137,24 @@ export function renderInsertSchemaOnly(obj: MetaObject): Code {
     // FR-013: @readOnly fields are populated by DB / replication / external
     // owner; the application has no path to write them. Exclude from the
     // create-shape schema entirely.
-    if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
 
-    const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
+    // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
+      );
+      continue;
+    }
+
+    const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
 
     if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
       insertFieldLines.push(
         code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
       );
     } else {
-      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child)}`);
+      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child, obj, ctx)}`);
     }
   }
 
@@ -86,9 +169,90 @@ ${joinCode(insertFieldLines, { on: ",\n" })}
 `;
 }
 
-export function renderZodValidators(obj: MetaObject): Code {
+/** One documented field in an Insert/Update schema's accepted shape. */
+export interface SchemaFieldShape {
+  /** The field name (the schema property key). */
+  name: string;
+  /** Whether the property is optional in the schema (`.optional()` / omitted-OK). */
+  optional: boolean;
+  /** For the @discriminator field on a TPH subtype's InsertSchema: the pinned
+   *  literal value (`z.literal("Bridge")`). Undefined otherwise. */
+  pinnedLiteral?: string;
+  /** True for @autoSet timestamp fields the schema fills server-side
+   *  (`z.string().optional().transform(...)`). */
+  autoSet?: boolean;
+}
+
+/**
+ * The field SET (name + optionality) the `<Name>InsertSchema` accepts — derived
+ * by the SAME iteration + skip rules `renderInsertSchemaOnly` /
+ * `renderZodValidators` use to EMIT that schema, so a documented create-payload
+ * shape can never drift from the real schema:
+ *   • auto-generated PK fields are omitted (caller doesn't provide them);
+ *   • @readOnly fields are omitted (DB / replication owns the write path);
+ *   • a TPH subtype's @discriminator field is a pinned `z.literal(value)`;
+ *   • @autoSet fields are present but optional (server fills them);
+ *   • every other field's optionality is `fieldWillBeOptional` (not required, or
+ *     carries a @default).
+ */
+export function insertSchemaFields(obj: MetaObject): SchemaFieldShape[] {
+  const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
+  const out: SchemaFieldShape[] = [];
+  for (const child of obj.fields()) {
+    if (autoGenPkFields.has(child.name)) continue;
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      out.push({ name: child.name, optional: false, pinnedLiteral: tphPin.value });
+      continue;
+    }
+    const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
+    if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
+      out.push({ name: child.name, optional: true, autoSet: true });
+    } else {
+      out.push({ name: child.name, optional: fieldWillBeOptional(child) });
+    }
+  }
+  return out;
+}
+
+/**
+ * The field SET the `<Name>UpdateSchema` accepts — same iteration + skip rules
+ * as `insertSchemaFields`, but mirroring the UpdateSchema branch of
+ * `renderZodValidators`:
+ *   • a TPH subtype's @discriminator field is OMITTED (clients can't change subtype);
+ *   • @autoSet onCreate fields are OMITTED (creation timestamps are immutable);
+ *   • @autoSet onUpdate fields are present + optional (server fills them);
+ *   • every other field is optional (PATCH semantics).
+ */
+export function updateSchemaFields(obj: MetaObject): SchemaFieldShape[] {
+  const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
+  const out: SchemaFieldShape[] = [];
+  for (const child of obj.fields()) {
+    if (autoGenPkFields.has(child.name)) continue;
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+    // TPH subtype discriminator: omitted from the update schema entirely.
+    if (tphPin !== undefined && child.name === tphPin.fieldName) continue;
+    const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
+    if (autoSet === AUTO_SET_ON_CREATE) {
+      // Omitted: creation timestamps cannot change after creation.
+      continue;
+    }
+    if (autoSet === AUTO_SET_ON_UPDATE) {
+      out.push({ name: child.name, optional: true, autoSet: true });
+      continue;
+    }
+    // All non-autoSet fields are optional in the update schema (PATCH semantics).
+    out.push({ name: child.name, optional: true });
+  }
+  return out;
+}
+
+export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code {
   const z = imp("z@zod");
   const autoGenPkFields = autoGenPkFieldNames(obj);
+  const tphPin = tphDiscriminatorPin(obj);
 
   const insertFieldLines: Code[] = [];
   const updateFieldLines: Code[] = [];
@@ -98,9 +262,20 @@ export function renderZodValidators(obj: MetaObject): Code {
     // The DB / trigger / replication owns the write path; the app must not
     // pass these values in POST/PATCH bodies (routesFile enforces the same
     // contract at the boundary with a 400 response).
-    if (child.ownAttr(FIELD_ATTR_READ_ONLY) === true) continue;
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+
+    // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
+    // The discriminator is implicit on subtype rows (controlled by URL / insert
+    // path) — the app never writes it via the body and never updates it.
+    // Insert: pinned literal. Update: omitted entirely (clients can't change subtype).
+    if (tphPin !== undefined && child.name === tphPin.fieldName) {
+      insertFieldLines.push(
+        code`  ${child.name}: z.literal(${JSON.stringify(tphPin.value)})`,
+      );
+      continue;
+    }
 
-    const autoSet = child.ownAttr(FIELD_ATTR_AUTO_SET);
+    const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
 
     // Insert schema: @autoSet fields use transform (always override client input).
     if (autoSet === AUTO_SET_ON_CREATE || autoSet === AUTO_SET_ON_UPDATE) {
@@ -108,7 +283,7 @@ export function renderZodValidators(obj: MetaObject): Code {
         code`  ${child.name}: z.string().optional().transform(() => new Date().toISOString())`,
       );
     } else {
-      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child)}`);
+      insertFieldLines.push(code`  ${child.name}: ${zodFieldExpr(child, obj, ctx)}`);
     }
 
     // Update schema: @autoSet onCreate → omit entirely; onUpdate → transform
@@ -122,7 +297,7 @@ export function renderZodValidators(obj: MetaObject): Code {
       // All non-autoSet fields are optional in the update schema (PATCH semantics).
       // zodFieldExpr already appends .optional() when the field is non-required
       // OR has a default; only append once more when it didn't.
-      const baseExpr = zodFieldExpr(child);
+      const baseExpr = zodFieldExpr(child, obj, ctx);
       updateFieldLines.push(
         fieldWillBeOptional(child) ? code`  ${child.name}: ${baseExpr}` : code`  ${child.name}: ${baseExpr}.optional()`,
       );
@@ -146,15 +321,24 @@ ${joinCode(updateFieldLines, { on: ",\n" })}
 `;
 }
 
-function zodFieldExpr(field: MetaField): Code {
+function zodFieldExpr(field: MetaField, owner?: MetaObject, ctx?: RenderContext): Code {
   // FIELD_SUBTYPE_OBJECT: emit z.array(<Ref>InsertSchema) / <Ref>InsertSchema
   // via an imp() so ts-poet hoists the cross-module import. Without this the
   // field used to collapse to z.string() / z.array(z.string()) and downstream
   // JSON Schema (e.g. LLM tool_use input_schema) lost the nested object shape.
   if (field.subType === FIELD_SUBTYPE_OBJECT) {
-    const ref = field.ownAttr(FIELD_ATTR_OBJECT_REF);
+    const ref = field.attr(FIELD_ATTR_OBJECT_REF);
     if (typeof ref === "string" && ref.length > 0) {
-      const refImp = imp(`${ref}InsertSchema@./${ref}.js`);
+      // @objectRef may be authored fully-qualified or bare — the referenced
+      // <Ref>InsertSchema is named by the BARE short name. The import MODULE is
+      // resolved via the shared layout/package/extStyle-aware helper (the SAME
+      // one the field's TS type + Drizzle .$type<> use) so all three agree.
+      // Without owner/ctx (bare unit-test calls) fall back to the flat same-dir.
+      const refBase = stripPackage(ref);
+      const moduleSpec = (ctx && owner)
+        ? valueObjectModuleSpecifier(refBase, ctx.packageOf, owner.package, ctx.outputLayout, ctx.extStyle)
+        : `./${refBase}.js`;
+      const refImp = imp(`${refBase}InsertSchema@${moduleSpec}`);
       let base: Code = code`${refImp}`;
       if (field.isArray) base = code`z.array(${base})`;
       return appendValidatorChain(base, field);
@@ -187,7 +371,27 @@ function zodFieldExpr(field: MetaField): Code {
       break;
     case FIELD_SUBTYPE_ENUM: {
       const values = enumValues(field);
-      baseStr = values !== undefined ? zodEnumExpr(values) : "z.string()";
+      if (values === undefined) {
+        baseStr = "z.string()";
+        break;
+      }
+      // FR-019: a field extending a MATERIALIZED root-level abstract enum uses the
+      // shared `<E>Enum` Zod const (imported from ./enums) instead of inlining
+      // z.enum([...]). A @provided enum keeps inline z.enum([...]) — validation
+      // stays metaobjects-owned (the @values SSOT); only the TS type is external.
+      // Inline enums (and bare-ctx unit-test calls) keep inlining as before.
+      if (ctx !== undefined) {
+        const shared = sharedEnumForField(field);
+        if (shared !== undefined && !shared.provided) {
+          const constName = sharedEnumZodConstName(shared.name);
+          const spec = sharedEnumImportSpecifier(ctx, owner?.package);
+          const sharedConst = imp(`${constName}@${spec}`);
+          let base: Code = code`${sharedConst}`;
+          if (field.isArray) base = code`z.array(${base})`;
+          return appendValidatorChain(base, field);
+        }
+      }
+      baseStr = zodEnumExpr(values);
       break;
     }
     case FIELD_SUBTYPE_STRING:
@@ -204,11 +408,11 @@ function zodFieldExpr(field: MetaField): Code {
 /** Mirrors the optional-or-not decision inside appendValidatorChain so the update-schema
  *  caller can avoid stacking a second `.optional()` onto an already-optional expression. */
 function fieldWillBeOptional(field: MetaField): boolean {
-  let isRequired = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
+  let isRequired = field.attr(FIELD_ATTR_REQUIRED) === true;
   for (const child of field.validators()) {
     if (child.subType === VALIDATOR_SUBTYPE_REQUIRED) isRequired = true;
   }
-  const hasDefault = field.ownAttr(FIELD_ATTR_DEFAULT) !== undefined;
+  const hasDefault = field.attr(FIELD_ATTR_DEFAULT) !== undefined;
   return !isRequired || hasDefault;
 }
 
@@ -226,8 +430,8 @@ const NUMERIC_FIELD_SUBTYPES = new Set<string>([
  *  - array (any element)    → .min/.max = element count     (validator.array)
  */
 function appendValidatorChain(base: Code, field: MetaField): Code {
-  let isRequired = field.ownAttr(FIELD_ATTR_REQUIRED) === true;
-  let maxLen: number | undefined = field.ownAttr(FIELD_ATTR_MAX_LENGTH) as number | undefined;
+  let isRequired = field.attr(FIELD_ATTR_REQUIRED) === true;
+  let maxLen: number | undefined = field.attr(FIELD_ATTR_MAX_LENGTH) as number | undefined;
   let minLen: number | undefined;
   let pattern: string | undefined;
   let numMin: number | undefined;
@@ -278,7 +482,7 @@ function appendValidatorChain(base: Code, field: MetaField): Code {
   // Fields with DB-level defaults are optional in the InsertSchema: the caller
   // can omit them and the DB will fill in. Otherwise required-with-default
   // would force callers to repeat the default at every call site.
-  const hasDefault = field.ownAttr(FIELD_ATTR_DEFAULT) !== undefined;
+  const hasDefault = field.attr(FIELD_ATTR_DEFAULT) !== undefined;
   if (!isRequired || hasDefault) chain = code`${chain}.optional()`;
   return chain;
 }

package/templates/api/agent-api.md.mustache

@@ -0,0 +1,30 @@
+{{{generatedMarker}}}
+
+# {{title}}
+
+Generated API reference for {{project}}; call these exactly as written. {{importNote}}
+{{#hasSetup}}
+
+## Setup
+{{#setup}}
+- `{{handle}}` — {{{note}}} `{{{snippetInline}}}`
+{{/setup}}
+{{/hasSetup}}
+{{#units}}
+
+## {{node}}
+{{#groups}}
+
+`{{importHeader}}`
+{{#symbols}}
+- `{{signature}}` — {{usage}}{{#throwsMarker}} {{throwsMarker}}{{/throwsMarker}}
+{{/symbols}}
+{{/groups}}
+{{#example}}
+
+Example:
+```ts
+{{{example}}}
+```
+{{/example}}
+{{/units}}