@metaobjectsdev/codegen-ts 1.0.5-rc.2 → 1.0.5-rc.4

package/src/relation-resolver.ts

@@ -18,6 +18,8 @@ import {
   stripPackage,
 } from "@metaobjectsdev/metadata";
 import { variableNameFromEntity } from "./naming.js";
+import { hasWritableRdbSource } from "./source-detect.js";
+import { tphStorageObject } from "./templates/zod-validators.js";
 import { isProjection } from "./projection/projection-detector.js";
 
 export interface RelationEntry {
@@ -55,8 +57,16 @@ export type RelationMap = Map<string, RelationEntry[]>;
 /**
  * Walk all entities, collect relationship children, and also register inverse
  * many() sides on the target entity.
+ *
+ * `onWarn`, when supplied, receives one line per M:N relationship whose junction FKs
+ * could not be derived: the entry is skipped (a route that mounts nothing is an
+ * ABSENCE, not an error), and the warning is the only thing that says so. The runner
+ * passes its warnings channel; callers without one keep the silent skip.
  */
-export function buildRelationMap(root: MetaRoot): RelationMap {
+export function buildRelationMap(
+  root: MetaRoot,
+  onWarn?: (msg: string) => void,
+): RelationMap {
   const result: RelationMap = new Map();
 
   const ensure = (name: string): RelationEntry[] => {
@@ -64,12 +74,71 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
     return result.get(name)!;
   };
 
+  // Files a CARDINALITY-ONE entry under the entity whose module renders the
+  // relations() block. A TPH subtype has no module of its own — it is folded into
+  // the discriminator base's single table, and the block renders on the BASE's.
+  // So an entry must be filed under the entity that actually renders it, or it is
+  // silently never emitted. `tphStorageName` is the seam for exactly this (its own
+  // doc says "for the name-keyed relation map"); the TARGET side of relations-block
+  // already resolves through it — only the SOURCE side was keyed raw.
+  //
+  // Because `obj.relationships()` RESOLVES, a base-declared relationship is reached
+  // again through every subtype and would now land on the same key repeatedly, so an
+  // entry structurally identical to one already filed is skipped. A name that collides
+  // with a DIFFERENT shape is a real conflict the base's single block cannot express:
+  // it is reported through `onWarn` rather than silently overwritten, because a
+  // navigation that quietly resolves to another subtype's target is the worse failure.
+  // True when a module renders a relations() block for this storage object — the
+  // question the map's contract asks, not either cause of its answer. Both
+  // non-abstractness and a writable source.rdb are required: the entity file
+  // routes an object failing EITHER to renderValueObjectFile, which emits no
+  // block. The oracle's tableBackedObjects walk makes the same exclusion. Filing
+  // an entry without it would only document, in `meta docs`/api-model, a
+  // `<Entity>Relations` export that no module emits.
+  const rendersRelationsBlock = (storing: MetaObject): boolean =>
+    !storing.isAbstract && hasWritableRdbSource(storing);
+
+  const push = (obj: MetaObject, entry: RelationEntry): void => {
+    const storing = tphStorageObject(obj);
+    if (!rendersRelationsBlock(storing)) return;
+    const key = storing.name;
+    const entries = ensure(key);
+    const clash = entries.find((e) => e.name === entry.name);
+    if (clash !== undefined) {
+      const same =
+        clash.cardinality === entry.cardinality &&
+        clash.targetEntity === entry.targetEntity &&
+        clash.fkField === entry.fkField;
+      if (!same) {
+        onWarn?.(
+          `relationship "${entry.name}" on entity "${obj.name}" gets no relations() entry: ` +
+            `"${key}" already carries a different "${entry.name}" ` +
+            `(-> ${clash.targetEntity} via ${clash.fkField}), and a single-table hierarchy ` +
+            `renders ONE relations() block on the base, which cannot hold both. ` +
+            `Rename one of them.`,
+        );
+      }
+      return;
+    }
+    entries.push(entry);
+  };
+
   for (const obj of root.objects()) {
     // Projections (source.dbView) are view-backed; they never emit a relations()
     // block, and their inherited belongs-to relationships would otherwise register
     // a spurious inverse-many on the target entity.
     if (isProjection(obj)) continue;
 
+    // An ABSTRACT level's own declarations do not file. Its FK column reaches the
+    // base's single table only through a CONCRETE @discriminatorValue descendant
+    // (collectTphSubtypeFields folds effective fields per concrete subtype), and
+    // that descendant's RESOLVING relationships() walk reaches this same
+    // relationship and files the identical entry — the dedupe collapses the
+    // copies. With no concrete descendant there is no folded column and no rows to
+    // navigate, so absence is the honest output: an entry would make the base's
+    // relations() block name a column the table does not have.
+    if (obj.isAbstract) continue;
+
     for (const child of obj.relationships()) {
       // ADR-0039: resolving — a relationship may inherit @cardinality via extends.
       const cardinality = child.attr(RELATIONSHIP_ATTR_CARDINALITY) as string | undefined;
@@ -79,7 +148,12 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       // many(junction) navigation on the source.
       // ADR-0039: resolving — @through may be inherited via extends.
       if (cardinality === CARDINALITY_MANY && child.attr(RELATIONSHIP_ATTR_THROUGH) !== undefined) {
-        const m2m = buildM2mEntry(obj, child as MetaRelationship, root);
+        const m2m = buildM2mEntry(obj, child as MetaRelationship, root, onWarn);
+        // NOT re-keyed to the storage base: the ROUTES tier reads this map to mount
+        // an M:N under EACH concrete subtype's segment, so it needs the per-subtype
+        // entries. Collapsing them onto the base key silently reduces four mounts to
+        // one. Only the cardinality-one path below is re-keyed, because that is the
+        // one the relations() block renders on the base's module.
         if (m2m) ensure(obj.name).push(m2m);
         continue;
       }
@@ -106,7 +180,7 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       const fkField = matching.fields[0];
       if (!fkField) continue;
 
-      ensure(obj.name).push({
+      push(obj, {
         name: child.name,
         cardinality: "one",
         targetEntity,
@@ -131,7 +205,6 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
   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];
@@ -143,7 +216,7 @@ export function buildRelationMap(root: MetaRoot): RelationMap {
       const refName = ref.name && ref.name.length > 0
         ? ref.name
         : variableNameFromEntity(targetEntity);
-      entries.push({
+      push(junction, {
         name: refName,
         cardinality: "one",
         targetEntity,
@@ -174,12 +247,16 @@ function collectJunctionNames(root: MetaRoot): Set<string> {
  * 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.
+ * fails, reporting the derivation's own reason through `onWarn` when supplied —
+ * the loader's rules never check subject pairing, so a model can load clean and
+ * still carry a junction this pass cannot pair (e.g. one whose identity.reference
+ * names a concrete subtype of the declaring entity).
  */
 function buildM2mEntry(
   source: MetaObject,
   rel: MetaRelationship,
   root: MetaRoot,
+  onWarn?: (msg: string) => void,
 ): RelationEntry | null {
   // ADR-0039: resolving — @objectRef/@through may be inherited via extends.
   const targetRaw = rel.attr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
@@ -188,7 +265,13 @@ function buildM2mEntry(
   let fields;
   try {
     fields = deriveM2MFields(rel, source, root);
-  } catch {
+  } catch (err) {
+    onWarn?.(
+      `M:N relationship "${rel.name}" on entity "${source.name}" gets no traversal route: its ` +
+        `@through junction "${stripPackage(throughRaw)}" could not be paired — ` +
+        `${err instanceof Error ? err.message : String(err)}. The model loads, so the run ` +
+        `continues, but the endpoint is absent (a 404).`,
+    );
     return null;
   }
   return {

package/src/runner.ts

@@ -486,7 +486,7 @@ export async function runGen(opts: RunGenOpts): Promise<RunGenResult> {
 
   // 3. Build shared render state once.
   const pkMap = buildPkMap(root);
-  const relationMap = buildRelationMap(root);
+  const relationMap = buildRelationMap(root, (m) => warnings.push(m));
   // ADR-0044/#228 — the ENTITY-tier collision domain is the run's EMITTED
   // `object.value` SET (NOT any per-payload closure): value-object module
   // filenames + `packageOf` are per-run/global, so the emitted-name map is built

package/src/templates/entity-ui-descriptor.ts

@@ -53,7 +53,6 @@ import {
 import { inferViewKind, currencyMetaFor, labelFor, humanize, valueObjectFor } from "./field-meta.js";
 import { VIEW_CONTEXT_FORM } from "../view-context.js";
 import { enumValues } from "../enum-meta.js";
-import { isProjection } from "../projection/projection-detector.js";
 // `restPath` lives HERE rather than in api-surface.ts, which is where it used to sit and
 // which now re-exports it. The descriptor is what emits `$path`, so the composition has to
 // be reachable from this module; importing it back from `api-surface.js` would be a cycle,
@@ -116,30 +115,24 @@ export interface EntityUiDescriptor {
  * An object's OWN pluralized resource path — the one derivation of that spelling, and the
  * input {@link restPath} composes an address from. It is NOT `$path` on its own.
  *
- * A projection is KEBAB-cased and an entity is SNAKE-cased, and that split is not a
- * style choice: both spellings are already mounted. `renderProjectionDecl` emits
- * `$path: "/order-summaries"` and `renderEntityConstants` emits `$path:
- * "/order_summaries"`, and `routes-file.ts` mounts whichever const belongs to the object
- * — so an address computed without the split is wrong for every multi-word projection.
- * It used to live in a second function inside `projection-decl.ts`, which is exactly how
- * `agent/ui.md` and `api/AGENT-API.md` both came to print `/order_summaries` for a
- * projection served at `/order-summaries`.
+ * ONE rule for entities and projections alike: snake_case the name, then pluralize.
+ * A projection used to be KEBAB-cased here while an entity was SNAKE-cased, composed in
+ * the opposite ORDER, and that split was grandfathered rather than designed — the only
+ * reason recorded for it was that the projection const had always emitted it. It is
+ * collapsed, so `OrderSummary` is `/order_summaries` whichever it is. That renamed every
+ * multi-word projection's collection URL; see CHANGELOG.
  *
  *   "Subscriber"     → "/subscribers"
  *   "WorkoutEvent"   → "/workout_events"
- *   "ProgramSummary" → "/program-summaries"   (projection)
+ *   "ProgramSummary" → "/program_summaries"   (projection — same rule)
  *
  * A TPH SUBTYPE is not addressed by this path — it is mounted under its base — so this is
  * an INPUT to {@link restPath}, not the answer. `$path` carries `restPath`; call this only
  * when you specifically want an object's own pluralized name, never to build an address.
  */
 export function resourcePath(entity: MetaData): string {
-  // The two compositions differ in ORDER as well as separator, and both are load-bearing:
-  // pluralize-then-snake is what the projection const has always emitted, snake-then-
-  // pluralize is what the entity const has. Neither may be "tidied" into the other.
-  return isProjection(entity)
-    ? `/${toSnakeCase(pluralize(entity.name)).replace(/_/g, "-")}`
-    : `/${pluralize(toSnakeCase(entity.name))}`;
+  // One rule, every object kind and every port: snake_case, then pluralize.
+  return `/${pluralize(toSnakeCase(entity.name))}`;
 }
 
 /**

package/src/templates/routes-file.ts

@@ -167,9 +167,7 @@ export async function ${handlerName}(fastify: ${FastifyInstanceSym}) {
   // FK columns were derived from the junction's identity.reference children (the
   // SSOT) by the relation-resolver pre-pass; here we resolve them to physical
   // column names for the Drizzle two-stage join.
-  const m2mEntries = (ctx.relationMap.get(entityName) ?? []).filter(
-    (e): e is RelationEntry & { junctionEntity: string } => e.junctionEntity !== undefined,
-  );
+  const m2mEntries = m2mEntriesOf(ctx, entityName);
   // Two fastify-scope variants: under an apiPrefix the mounts live inside the
   // register-block (`instance`); otherwise they bind directly to `fastify`.
   const m2mMountsPrefixed = renderM2mMounts(m2mEntries, entity, ctx, "instance");
@@ -242,6 +240,21 @@ ${m2mMountsFlat}}
   return header + literalImports.toString() + body.toString();
 }
 
+/**
+ * The M:N navigation entries of `name` — the ONE rule for which relationships get a
+ * traversal mount. The vanilla entity path and the TPH path both go through it, so
+ * they cannot drift apart: a rule change moves every mount at once, and the
+ * independent oracle's route rule stays checkable against both emit paths alike.
+ */
+function m2mEntriesOf(
+  ctx: RenderContext,
+  name: string,
+): Array<RelationEntry & { junctionEntity: string }> {
+  return (ctx.relationMap.get(name) ?? []).filter(
+    (e): e is RelationEntry & { junctionEntity: string } => e.junctionEntity !== undefined,
+  );
+}
+
 /**
  * Render the M:N traversal mounts for an entity as a single Code fragment to
  * interpolate INTO the handler-body code template (so the junction/target table
@@ -255,13 +268,38 @@ function renderM2mMounts(
   source: MetaObject,
   ctx: RenderContext,
   fastifyVar: string,
+  tphSource?: TphM2mSource,
 ): Code | string {
   if (entries.length === 0) return "";
-  const mounts = entries.map((e) => renderM2mMount(e, source, ctx, fastifyVar));
+  const mounts = entries.map((e) => renderM2mMount(e, source, ctx, fastifyVar, tphSource));
   return code`${joinCode(mounts, { on: "\n", trim: false })}
 `;
 }
 
+/**
+ * Where a TPH M:N mount hangs, and how it proves the source id is really ITS subtype's.
+ *
+ * Only `renderTphRoutesFile` supplies this, and only for a relationship declared ON a
+ * subtype. The path gains that subtype's segment, and `sourceDiscriminator` gets the
+ * check that makes the segment mean something: the junction FK points at the shared base
+ * table, so without it a sibling subtype's id reaches the same junction rows and the
+ * segment in the URL is decorative. A relationship declared on the BASE passes nothing
+ * here — every row of the table is a legitimate source — so its mount is byte-identical
+ * to a vanilla entity's.
+ */
+interface TphM2mSource {
+  /** Appended to the base entity's `$path`, e.g. `"/bridge"`. */
+  pathSuffix: string;
+  /** The base table const this subtype's rows live in. */
+  table: Code | string;
+  /** Physical PK column of the base table. */
+  pkColumn: Code;
+  /** Physical discriminator column of the base table. */
+  discriminatorColumn: Code;
+  /** This subtype's `@discriminatorValue`. */
+  value: string;
+}
+
 /**
  * Render one M:N traversal mount. The junction + target Drizzle table consts are
  * imported from their sibling entity files (imp() lets ts-poet track + emit the
@@ -274,6 +312,7 @@ function renderM2mMount(
   source: MetaObject,
   ctx: RenderContext,
   fastifyVar: string,
+  tphSource?: TphM2mSource,
 ): Code {
   // `source` never changes across this function, so its effective package is computed
   // once and reused below (both crossEntitySpecifier calls, and the three
@@ -329,9 +368,20 @@ function renderM2mMount(
     targetDiscriminator: { column: ${resolveJunctionColumn(target, pin.fieldName, ctx, sourcePkg)}, value: ${JSON.stringify(pin.value)} },`
     : "";
 
+  // A subtype-declared M:N hangs under the subtype's segment; everything else hangs at
+  // the source entity's own path. `$path` is read from the BASE const either way — a TPH
+  // subtype's module exports no entity const of its own.
+  const pathExpr: Code = tphSource === undefined
+    ? code`${source.name}.$path`
+    : code`${source.name}.$path + ${JSON.stringify(tphSource.pathSuffix)}`;
+  const sourceDiscriminatorLine: Code | string = tphSource === undefined
+    ? ""
+    : code`
+    sourceDiscriminator: { table: ${tphSource.table}, pkColumn: ${tphSource.pkColumn}, column: ${tphSource.discriminatorColumn}, value: ${JSON.stringify(tphSource.value)} },`;
+
   return code`  ${mountM2mRouteSym}({
     fastify: ${fastifyVar},
-    path: ${source.name}.$path,
+    path: ${pathExpr},
     relationName: ${JSON.stringify(entry.name)},
     db,
     junctionTable: ${junctionVarSym},
@@ -339,7 +389,7 @@ function renderM2mMount(
     sourceColumn: ${sourceColumn},
     targetColumn: ${targetColumn},
     targetPkColumn: ${targetPkColumn},
-    symmetric: ${entry.symmetric ? "true" : "false"},${discriminatorLine}
+    symmetric: ${entry.symmetric ? "true" : "false"},${discriminatorLine}${sourceDiscriminatorLine}
   });`;
 }
 
@@ -440,7 +490,20 @@ function renderTphRoutesFile(
       dialect: ${dialectLit},${polymorphicExposeLine}
     });`;
 
-  const subtypeMounts: Code[] = plan.subtypes.map(({ entity: sub, value, routeSegment: segment }) => {
+  // FR-018 x FR-017 — M:N traversal inside a TPH hierarchy. This file never consulted
+  // the relation map at all, so BOTH sides vanished from the generated API: a
+  // relationship declared on the base (every row of the table is a legitimate source)
+  // and one declared on a subtype (only that subtype's rows are). Neither is a compile
+  // error — a route that is never mounted is an absence — which is why the codegen
+  // compile gate stayed green while the endpoint 404'd.
+  //
+  // The physical columns stage 0 needs, resolved once against the base's own table.
+  const basePkField = ctx.pkMap.get(baseName)?.fieldName ?? "id";
+  const basePkColumn = resolveJunctionColumn(base, basePkField, ctx, basePkg);
+  const baseDiscColumn = resolveJunctionColumn(base, discField, ctx, basePkg);
+  const baseM2mMounts = renderM2mMounts(m2mEntriesOf(ctx, baseName), base, ctx, fastifyRef);
+
+  const subtypeMounts: Code[] = plan.subtypes.flatMap(({ entity: sub, value, routeSegment: segment }) => {
     const subFileSpec = entityModuleSpecifier(
       ctx.selfTarget, ctx.entityModuleTarget, effectivePackage(sub), sub.name, ctx.extStyle,
     );
@@ -457,7 +520,7 @@ function renderTphRoutesFile(
     // (discriminator excluded — it's pinned by this path).
     const subFilterSym = imp(`${sub.name}FilterAllowlist@${subFileSpec}`);
     const subSortSym = imp(`${sub.name}SortAllowlist@${subFileSpec}`);
-    return code`
+    const crud = code`
     ${mountCrudRoutesSym}({
       fastify: ${fastifyRef},
       path: ${baseConstSym}.$path + ${JSON.stringify("/" + segment)},
@@ -470,9 +533,32 @@ function renderTphRoutesFile(
       dialect: ${dialectLit},
       discriminator: { column: ${JSON.stringify(discField)}, value: ${JSON.stringify(value)} },${exposeLine(expose, "      ")}
     });`;
+    // This subtype's own M:N navigations, mounted beneath its segment and gated on the
+    // discriminator so a sibling's id yields [] instead of the sibling's relations.
+    //
+    // Every relationship this subtype RESOLVES, inherited ones included — not just the
+    // ones it declares. A subtype resource is a resource: `/auths/bridge/1` carries the
+    // same sub-resources as any other, so it carries the base's relationships too, and
+    // an abstract mid level's relationship has nowhere else to be served at all.
+    //
+    // The base mounts its own set separately, at its own path. The overlap is deliberate
+    // and not redundant: `/auths/1/tags` accepts any row of the table, while
+    // `/auths/bridge/1/tags` answers [] for a Copay id — the segment is a type
+    // assertion, which is exactly what sourceDiscriminator enforces below.
+    const subM2m = renderM2mMounts(m2mEntriesOf(ctx, sub.name), base, ctx, fastifyRef, {
+      pathSuffix: "/" + segment,
+      table: code`${tableSym}`,
+      pkColumn: basePkColumn,
+      discriminatorColumn: baseDiscColumn,
+      value,
+    });
+    return subM2m === "" ? [crud] : [crud, subM2m as Code];
   });
 
-  const mounts = joinCode([polymorphic, ...subtypeMounts], { on: "\n" });
+  const mounts = joinCode(
+    [polymorphic, ...(baseM2mMounts === "" ? [] : [baseM2mMounts as Code]), ...subtypeMounts],
+    { on: "\n" },
+  );
   // The base path is read-only by construction (TPH_POLYMORPHIC_VERBS), but the
   // per-subtype mounts below it are full CRUD — so `expose` does narrow this file.
   const tphAuthJsDoc = authSeamJsDoc({ framework: "fastify", handlerName, narrowable: true });

package/src/templates/zod-validators.ts

@@ -148,26 +148,46 @@ export function hasAutoSetFields(obj: MetaObject): boolean {
   return false;
 }
 
+/** Is this field's column one the TPH BASE declares, rather than a subtype-only one?
+ *
+ *  Resolving (ADR-0039) and compared by name against `base.fields()` — exactly the set
+ *  `collectTphSubtypeFields` treats as "already emitted" when it folds the subtype
+ *  columns into the base table, so the two answers cannot drift apart. A field declared
+ *  on an abstract level BETWEEN the base and the subtype is subtype-only: the base's own
+ *  field set does not carry it, and neither does the base's `.notNull()`. */
+function isTphBaseOwnField(obj: MetaObject, field: MetaField): boolean {
+  const base = tphDiscriminatorBase(obj);
+  if (base === undefined) return false;
+  return base.fields().some((f) => f.name === field.name);
+}
+
 /**
  * Is this field NULL-tolerant in a TPH subtype's READ shape?
  *
- * A TPH subtype shares one physical table with its siblings, so a column only one
- * subtype declares is NULL on every other subtype's row, and a non-`@required` column
- * of this subtype's own is NULL when unset. Either way the value read back is `null`,
- * not `undefined`. The PRIMARY KEY is the exception — it is the shared base table's
- * key and is present on every row.
+ * Answered from the PHYSICAL column, because that is the only thing a read can return.
+ * A TPH subtype shares one table with its siblings, so a column only some subtypes
+ * declare is NULL on every other subtype's row and `drizzle-schema.ts` drops its
+ * `.notNull()` whatever `@required` says (its `forceNullable` fold). A column the base
+ * itself declares carries `.notNull()` precisely when the field is required. The PRIMARY
+ * KEY is the shared base table's key and is present on every row.
+ *
+ * `@default` is deliberately NOT consulted, and that is the fix rather than an omission.
+ * A default decides whether an INSERT may leave the value out; it says nothing about what
+ * a READ can see. Asking `fieldWillBeOptional` here widened a `NOT NULL DEFAULT` column to
+ * `| null` and — through the `.optional()` that same predicate mirrors — to `| undefined`,
+ * which the declared interface did not admit: `parse<Base>()` returned a value not
+ * assignable to the base union and the generated module failed to compile (TS2322).
  *
  * ONE predicate, because TWO emitters answer this question about the same field: the
  * Zod read schema (`renderTphSubtypeReadSchema`) and the declared TS type
- * (`renderValueObjectInterface`). They answered it differently, so the value
- * `parse<Base>()` returns was not assignable to the base union and the generated
- * module did not compile (TS2322). A second answer to one question is the defect;
+ * (`renderValueObjectInterface`). A second answer to one question is the defect;
  * keeping the two call sites pointed here is the fix.
  */
 export function isTphReadNullTolerant(obj: MetaObject, field: MetaField): boolean {
   if (!isTphSubtype(obj)) return false;
-  if (!fieldWillBeOptional(field)) return false;
-  return !primaryIdentityFieldNames(obj).includes(field.name);
+  if (primaryIdentityFieldNames(obj).includes(field.name)) return false;
+  if (!isTphBaseOwnField(obj, field)) return true;
+  return !isRequired(field);
 }
 
 /**
@@ -191,10 +211,16 @@ export function renderTphSubtypeReadSchema(obj: MetaObject, ctx?: RenderContext)
       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 parses cleanly. The declared
-    // interface widens the SAME fields — see isTphReadNullTolerant.
+    // forceRequired: a row selected from the table carries every column as a KEY —
+    // a nullable one arrives as `null`, never absent — so nothing with a COLUMN in a
+    // read shape is `.optional()`. Letting zodFieldExpr append it made the inferred
+    // type `T | undefined` while the declared interface said `T`, and the two
+    // disagreed. A derived (origin-bearing) field is the one member of obj.fields()
+    // with no column — drizzle-schema.ts emits none, and the TPH queries path selects
+    // the bare base table — so its key is genuinely absent from every parsed row and
+    // it alone keeps `.optional()`, matching the interface's `?: T | null`.
+    // Null-tolerance is added below, from the column, by isTphReadNullTolerant.
+    const expr = zodFieldExpr(child, obj, ctx, !child.isDerived());
     fieldLines.push(
       isTphReadNullTolerant(obj, child)
         ? code`  ${child.name}: ${expr}.nullable()`
@@ -606,8 +632,9 @@ function zodFieldExpr(
   field: MetaField,
   owner?: MetaObject,
   ctx?: RenderContext,
-  /** Suppress the trailing `.optional()` — see assignedPkFieldNames. Set ONLY
-   *  by the insert-shape emitters; the update/read shapes must stay optional. */
+  /** Suppress the trailing `.optional()`. Set by the insert-shape emitters for an
+   *  assigned PK (see assignedPkFieldNames) and by the TPH read shape, where every
+   *  column is a present key. The UPDATE shape must stay optional (PATCH semantics). */
   forceRequired = false,
 ): Code {
   // `@dbColumnType: jsonb` on a scalar (legal only on field.string) is the