@metaobjectsdev/codegen-ts 1.0.4-rc.1 → 1.0.5-rc.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metaobjectsdev/codegen-ts",
-  "version": "1.0.4-rc.1",
+  "version": "1.0.5-rc.1",
   "description": "TypeScript codegen engine for MetaObjects — emits Drizzle, Zod, and Fastify artifacts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -111,8 +111,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@metaobjectsdev/metadata": "1.0.4-rc.1",
-    "@metaobjectsdev/render": "1.0.4-rc.1",
+    "@metaobjectsdev/metadata": "1.0.5-rc.1",
+    "@metaobjectsdev/render": "1.0.5-rc.1",
     "@biomejs/js-api": "^0.7.0",
     "@biomejs/wasm-nodejs": "^1.9.4",
     "@toon-format/toon": "^2.3.0",
@@ -124,9 +124,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^1.9.0",
-    "@metaobjectsdev/codegen-ts-react": "1.0.4-rc.1",
-    "@metaobjectsdev/migrate-ts": "1.0.4-rc.1",
-    "@metaobjectsdev/runtime-ts": "1.0.4-rc.1",
+    "@metaobjectsdev/codegen-ts-react": "1.0.5-rc.1",
+    "@metaobjectsdev/migrate-ts": "1.0.5-rc.1",
+    "@metaobjectsdev/runtime-ts": "1.0.5-rc.1",
     "bun-types": "latest",
     "drizzle-orm": "^0.38.0",
     "hono": "^4.6.0",

package/src/column-mapper.ts

@@ -468,6 +468,19 @@ export function mapColumnType(
       // SQLite has no native array type; serialize as JSON in a text column.
       fnName = "text";
       fnOptions = { mode: "json" };
+    } else if (field.attr(FIELD_ATTR_DB_COLUMN_TYPE) === DB_COLUMN_TYPE_JSONB) {
+      // `@dbColumnType: jsonb` — the open JSON bag. SQLite has no native jsonb, but
+      // the attribute is not merely physical here: the wire contract says the value
+      // round-trips as a PARSED JSON value on every dialect (the api-contract jsonb
+      // corpus: "POST a JSON object, read it back as an object — never a
+      // JSON-encoded string"), and the generated Zod/TS type is `unknown` for that
+      // reason. Falling through to a plain `text()` gave that column a `string` type
+      // while the entity type stayed `unknown`, so the generated queries did not
+      // compile — and had they compiled, the value would have come back as a string.
+      // text(..., { mode: "json" }) is the same idiomatic form field.object and
+      // field.map already take on this dialect, and it keeps both halves agreeing.
+      fnName = "text";
+      fnOptions = { mode: "json" };
     } else {
       switch (subType) {
         case FIELD_SUBTYPE_BOOLEAN:

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

@@ -570,6 +570,50 @@ function sourceColumnNameFor(
   return columnNameFromField(entityField.name, ctx.columnNamingStrategy);
 }
 
+/**
+ * The BASE table's column an extends-bound passthrough field SELECTS.
+ *
+ * A projection field may RENAME what it exposes
+ * (`{ field.string: { name: bookingRef, extends: "Shipment.reference" } }`). The view's
+ * OUTPUT alias is the projection field's own; the column it reads from the base table is
+ * the extends TARGET's. Deriving both from the projection field emits
+ * `SELECT s.booking_ref` against a table whose column is `reference` — SQL that SQLite
+ * accepts at CREATE VIEW and only fails at the first SELECT, and that Postgres rejects
+ * outright at migrate time.
+ *
+ * Caller contract: this is for a PLAIN projection only. A read-view HOST (`base ===
+ * projection`) reads its own table, so its passthrough source is always the field's own
+ * column and there is no rename to resolve — and a host field may legally `extends` a
+ * SIBLING field of the same entity for shape reuse, which this would otherwise read as a
+ * rename and silently serve the sibling's data under this field's name.
+ *
+ * Only a DOTTED extends naming the BASE entity redirects the source column:
+ *
+ *   - `extends: "Shipment.reference"` — binds a base column; the target's column wins.
+ *   - `extends: "Code24"` (bare, a package-level abstract) — SHAPE REUSE, not a binding.
+ *     `refNamedOwner` returns undefined, so the field's own name stays the source.
+ *   - `extends: "Other.foo"` — names an entity that is not the base. The caller emits this
+ *     column against `joinTree.baseAlias`, so borrowing another entity's column name would
+ *     be a second wrong answer; keep the field's own.
+ *
+ * The alias is not always the projection's spelling: `sourceColumnNameFor` reads `@column`
+ * with the RESOLVING accessor, so a renaming field whose base carries an explicit `@column`
+ * inherits it and both sides land on that physical name. The rename then holds on the TS /
+ * wire tier only. That is pre-existing and self-consistent — the Drizzle view decl binds
+ * the same column — but it is not a promise this function makes.
+ */
+function baseColumnNameFor(
+  field: MetaField,
+  base: MetaObject,
+  root: MetaRoot,
+  ctx: ExtractContext,
+): string {
+  const target = field.superData;
+  if (target === undefined) return sourceColumnNameFor(field, ctx);
+  if (refNamedOwner(field, root) !== base) return sourceColumnNameFor(field, ctx);
+  return sourceColumnNameFor(target, ctx);
+}
+
 /**
  * Physical column for a join FK/PK field — resolves @column + naming strategy the
  * same way passthrough columns do (EFFECTIVE fields, so inherited PKs resolve).
@@ -976,22 +1020,27 @@ function buildSelectSpec(
   // fields — the declared set IS the exposure (FR-024/ADR-0028). Either way, each
   // field's own origin decides passthrough-from-base vs derived-from-join. origin.*
   // NEVER inherits (ADR-0029), so the origin reads below are own (category 4).
-  const declaredFields: MetaField[] =
-    base === projection
-      ? base.fields()
-      : projection.ownChildren().filter((c): c is MetaField => c.type === TYPE_FIELD);
+  // A read-view HOST reads its OWN table (base === projection), so every passthrough
+  // sources from the field's own column; a plain projection reads the base's, which an
+  // extends-bound field may rename. The flag decides both the field set and the source.
+  const isReadViewHost = base === projection;
+  const declaredFields: MetaField[] = isReadViewHost
+    ? base.fields()
+    : projection.ownChildren().filter((c): c is MetaField => c.type === TYPE_FIELD);
   for (const field of declaredFields) {
     const origin = field.ownChildren().find((c) => c.type === TYPE_ORIGIN);
     const dbCol = sourceColumnNameFor(field, ctx);
 
     if (!origin) {
-      // Declared on projection but no origin — passthrough from base table.
+      // Declared on projection but no origin — passthrough from base table. The alias is
+      // this field's own column; the SOURCE is the extends target's, which differs
+      // whenever the projection renames the base field.
       columns.push({
         kind: "passthrough",
         fieldName: field.name,
         dbColAlias: dbCol,
         sourceAlias: joinTree.baseAlias,
-        sourceColumn: dbCol,
+        sourceColumn: isReadViewHost ? dbCol : baseColumnNameFor(field, base, root, ctx),
       });
       continue;
     }

package/src/templates/drizzle-schema.ts

@@ -22,6 +22,7 @@ import {
   namesRef, physicalNameExpr, sourceSchemaExpr, indexNameExpr, columnExpr,
 } from "../names.js";
 import { resolveTableSchema } from "@metaobjectsdev/metadata";
+import { renderEnumIntCustomType } from "./enum-int-codec.js";
 import { renderRelationsBlock } from "./relations-block.js";
 import { renderDocsFor } from "./jsdoc.js";
 import { collectTphSubtypeFields } from "./tph-discriminator.js";
@@ -35,7 +36,18 @@ import { effectivePackage } from "../docs-paths.js";
  * Returns a Code object so ts-poet can deduplicate imports when this composes
  * with the rest of the entity file. Biome formatting runs after composition.
  */
-export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
+export function renderDrizzleSchema(
+  obj: MetaObject,
+  ctx: RenderContext,
+  /**
+   * OUT param: the int-backed-enum codec const names this table DECLARES. A caller that
+   * emits another artifact referencing the same codecs into the SAME module — entity-file's
+   * write-through replica view — passes a set here and hands it to that emitter, which then
+   * references the consts instead of re-declaring them. A duplicate module-scope `const` is
+   * a JS parse error, so the module would not even load.
+   */
+  declaredEnumIntCodecs?: Set<string>,
+): Code {
   const dialect = ctx.dialect;
   const tableFn = dialect === "sqlite" ? "sqliteTable" : "pgTable";
   const importModule = dialect === "sqlite" ? "drizzle-orm/sqlite-core" : "drizzle-orm/pg-core";
@@ -381,57 +393,15 @@ ${joinCode(columnLines, { on: ",\n", trim: false })}
   const enumIntBlocks = [...enumIntTypes.values()]
     .sort((a, b) => a.fnConstName.localeCompare(b.fnConstName))
     .map((t) => renderEnumIntCustomType(t, importModule));
+  if (declaredEnumIntCodecs !== undefined) {
+    for (const name of enumIntTypes.keys()) declaredEnumIntCodecs.add(name);
+  }
 
   const blocks: Code[] = [...enumIntBlocks, tableBlock];
   if (relationsBlock !== null) blocks.push(relationsBlock);
   return blocks.length === 1 ? blocks[0]! : joinCode(blocks, { on: "\n" });
 }
 
-/**
- * Render an int-backed `field.enum`'s Drizzle `customType` helper plus its two
- * lookup maps.
- *
- * The codec lives HERE, in the column definition, so nothing downstream needs to
- * know about it: `db.insert().values()` encodes on bind, a selected row decodes on
- * read, and a filter comparison encodes because Drizzle binds through the column
- * type. That is why this shape was chosen over a Zod write-transform plus a
- * generated read-decode — TS's generated queries return raw Drizzle rows and have
- * no decode seam, so the query-layer approach meant inventing one and wrapping
- * every generated read. It is also the direct analogue of what the other four
- * ports already do (EF Core `HasConversion`, OMDB `JdbcFieldCodec`, Exposed
- * `customEnumeration`, Python `ObjectManager` coercion).
- *
- * `fromDriver` throws on an unmapped integer rather than returning undefined: a
- * value outside the map means the DB holds data the model says is impossible
- * (a hand-written INSERT, or a member removed without a migration), and silently
- * yielding `undefined` for a non-nullable field would surface far from the cause.
- */
-function renderEnumIntCustomType(t: EnumIntCustomType, importModule: string): Code {
-  const customTypeSym = imp(`customType@${importModule}`);
-  const union = t.members.map((m) => JSON.stringify(m)).join(" | ");
-  const toEntries = t.members
-    .map((m) => `${JSON.stringify(m)}: ${t.intByMember[m]}`)
-    .join(", ");
-  const fromEntries = t.members
-    .map((m) => `${t.intByMember[m]}: ${JSON.stringify(m)}`)
-    .join(", ");
-  return code`
-const ${t.toIntConstName} = { ${toEntries} } as const satisfies Record<${union}, number>;
-const ${t.fromIntConstName}: Record<number, ${union}> = { ${fromEntries} };
-const ${t.fnConstName} = ${customTypeSym}<{ data: ${union}; driverData: number }>({
-  dataType: () => ${JSON.stringify(t.dataType)},
-  toDriver: (value) => ${t.toIntConstName}[value],
-  fromDriver: (value) => {
-    const member = ${t.fromIntConstName}[value];
-    if (member === undefined) {
-      throw new Error(\`unmapped ${t.fnConstName} value: \${value}\`);
-    }
-    return member;
-  },
-});
-`;
-}
-
 interface FkInfo {
   targetVarName: string;    // e.g., "users"
   targetEntityName: string; // e.g., "User" — used for the import path

package/src/templates/entity-file.ts

@@ -136,6 +136,12 @@ export function renderEntityFile(
   // compile error). A base+write-through combo keeps the TPH polymorphic read path (reads
   // the base table); routing its reads through a replica view is a documented non-goal.
   const writeThrough = isWriteThrough(entity) && !tphBase;
+  // Rendered BEFORE the replica view below, for two reasons that both matter: the table
+  // DECLARES the int-backed-enum codecs (a `const` the view's declaration would duplicate,
+  // and a duplicate module-scope const is a parse error), and those consts must precede the
+  // view's use of them in the emitted file or the view hits a TDZ ReferenceError at import.
+  const declaredEnumIntCodecs = new Set<string>();
+  const schemaBlock = renderDrizzleSchema(entity, ctx, declaredEnumIntCodecs);
   const viewSections: Code[] = [];
   if (writeThrough) {
     const camel = entity.name.charAt(0).toLowerCase() + entity.name.slice(1);
@@ -168,6 +174,8 @@ export function renderEntityFile(
       // is passed separately below and stays a literal — the artifact holds the primary
       // (table) source's name, not this one.
       names: entityNames,
+      // The table above already declared these; the view references them by name.
+      declaredEnumIntCodecs,
       // The replica view's OWN @schema, from the same source node projectionViewName picks
       // — never the entity's, which is the WRITE TABLE's and would qualify this view with a
       // schema that belongs to something else. A view and the table it replicates need not
@@ -206,7 +214,7 @@ ${docsPrefix}export type ${entity.name} = ${z}.infer<typeof ${entity.name}Schema
   const constantsNames = namesRef(entity, ctx);
 
   const sections: Code[] = [
-    renderDrizzleSchema(entity, ctx),
+    schemaBlock,
     ...viewSections,
     renderInferredTypes(entity, tphBase, ctx, writeThrough /* skipRow — read type is the view schema */),
     ...(enumAliases !== null ? [enumAliases] : []),

package/src/templates/enum-int-codec.ts

@@ -0,0 +1,67 @@
+/**
+ * The int-backed `field.enum` codec emitter, shared by the two artifacts that can
+ * reference one: the entity's Drizzle table (`drizzle-schema.ts`) and any view-backed
+ * read model (`view-decl.ts` — a projection or an entity read-view).
+ *
+ * It lives in its own module because the codec is a MODULE-LOCAL const in whatever file
+ * declares the column, so every emitter that can produce such a column must be able to
+ * declare it too. While only the table template owned it, the view template emitted the
+ * call site and let the const name fall through to `imp(fnName@drizzle-orm/*-core)` —
+ * importing a member that package does not export, which `meta gen` reported as success
+ * and only `tsc` caught.
+ *
+ * The invariant this module exists to protect: the codec is declared ONCE PER MODULE, and
+ * it must precede every use. A write-through entity puts its table and its replica view in
+ * one file and both reference the same consts, so `entity-file.ts` renders the table first,
+ * collects the names it declared, and hands them to the view — which then references them
+ * instead of re-declaring. Two module-scope `const`s of one name is a JS parse error, and a
+ * declaration emitted after its use is a TDZ ReferenceError at import: both are worse than
+ * the missing-codec bug, because neither lets the module load at all.
+ */
+import { code, imp, type Code } from "ts-poet";
+import type { EnumIntCustomType } from "../column-mapper.js";
+
+/**
+ * Render an int-backed `field.enum`'s Drizzle `customType` helper plus its two
+ * lookup maps.
+ *
+ * The codec lives HERE, in the column definition, so nothing downstream needs to
+ * know about it: `db.insert().values()` encodes on bind, a selected row decodes on
+ * read, and a filter comparison encodes because Drizzle binds through the column
+ * type. That is why this shape was chosen over a Zod write-transform plus a
+ * generated read-decode — TS's generated queries return raw Drizzle rows and have
+ * no decode seam, so the query-layer approach meant inventing one and wrapping
+ * every generated read. It is also the direct analogue of what the other four
+ * ports already do (EF Core `HasConversion`, OMDB `JdbcFieldCodec`, Exposed
+ * `customEnumeration`, Python `ObjectManager` coercion).
+ *
+ * `fromDriver` throws on an unmapped integer rather than returning undefined: a
+ * value outside the map means the DB holds data the model says is impossible
+ * (a hand-written INSERT, or a member removed without a migration), and silently
+ * yielding `undefined` for a non-nullable field would surface far from the cause.
+ */
+export function renderEnumIntCustomType(t: EnumIntCustomType, importModule: string): Code {
+  const customTypeSym = imp(`customType@${importModule}`);
+  const union = t.members.map((m) => JSON.stringify(m)).join(" | ");
+  const toEntries = t.members
+    .map((m) => `${JSON.stringify(m)}: ${t.intByMember[m]}`)
+    .join(", ");
+  const fromEntries = t.members
+    .map((m) => `${t.intByMember[m]}: ${JSON.stringify(m)}`)
+    .join(", ");
+  return code`
+const ${t.toIntConstName} = { ${toEntries} } as const satisfies Record<${union}, number>;
+const ${t.fromIntConstName}: Record<number, ${union}> = { ${fromEntries} };
+const ${t.fnConstName} = ${customTypeSym}<{ data: ${union}; driverData: number }>({
+  dataType: () => ${JSON.stringify(t.dataType)},
+  toDriver: (value) => ${t.toIntConstName}[value],
+  fromDriver: (value) => {
+    const member = ${t.fromIntConstName}[value];
+    if (member === undefined) {
+      throw new Error(\`unmapped ${t.fnConstName} value: \${value}\`);
+    }
+    return member;
+  },
+});
+`;
+}

package/src/templates/inferred-types.ts

@@ -39,6 +39,7 @@ import { stripPackage } from "@metaobjectsdev/metadata";
 import { enumValues } from "../enum-meta.js";
 import { sharedEnumZodConstName } from "./enums-file.js";
 import { renderDocsFor } from "./jsdoc.js";
+import { isTphReadNullTolerant } from "./zod-validators.js";
 import { sharedEnumForField } from "../enum-shared.js";
 import { sharedEnumImportSpecifier, providedEnumImportSpecifier } from "../enum-import.js";
 import { fieldDeclaringPackage, type RenderContext } from "../render-context.js";
@@ -387,7 +388,12 @@ export function renderValueObjectInterface(entity: MetaObject, ctx?: RenderConte
     const required = field.attr(FIELD_ATTR_REQUIRED) === true;
     const optional = required ? "" : "?";
     const tsType = valueObjectFieldType(entity, field, ctx);
-    lines.push(code`  ${field.name}${optional}: ${tsType};`);
+    // A TPH subtype's read schema accepts `null` for a column that is NULL on a
+    // sibling subtype's row; the declared type has to admit the same values, or
+    // `parse<Base>()` returns something this interface rejects. One predicate
+    // answers it for both emitters (ADR-style single source, see its docblock).
+    const nullable = isTphReadNullTolerant(entity, field) ? " | null" : "";
+    lines.push(code`  ${field.name}${optional}: ${tsType}${nullable};`);
   }
 
   // joinCode with "\n" interpolates each Code segment on its own line and

package/src/templates/view-decl.ts

@@ -12,7 +12,8 @@ import {
   type MetaField, FIELD_SUBTYPE_OBJECT, FIELD_ATTR_OBJECT_REF,
 } from "@metaobjectsdev/metadata";
 import type { ColumnNamingStrategy } from "../metaobjects-config.js";
-import { mapColumnType } from "../column-mapper.js";
+import { mapColumnType, type EnumIntCustomType } from "../column-mapper.js";
+import { renderEnumIntCustomType } from "./enum-int-codec.js";
 import { zodTypeFor } from "./field-meta.js";
 import { columnExpr, type ObjectNames } from "../names.js";
 
@@ -21,6 +22,14 @@ export interface ViewDeclOpts {
   readonly columnNamingStrategy: ColumnNamingStrategy;
   /** Drives the timestamp column TS type (Date vs string) in the view declaration. */
   readonly timestampMode: "date" | "string";
+  /**
+   * Int-backed-enum codec const names ALREADY declared in the module this view lands in.
+   * A write-through entity's table and its replica view share one file, and both reference
+   * the same codecs — so the view references these by name and declares only what the table
+   * did not (a derived field's codec, which the write table omits). Absent = the view owns
+   * every codec it needs, which is the projection case.
+   */
+  readonly declaredEnumIntCodecs?: ReadonlySet<string>;
   /**
    * ADR-0044/#228 — resolve a `field.object` / `field.map`'s `@objectRef` to the
    * value object's EMITTED name (bare when unique in the run, package-qualified on
@@ -72,10 +81,26 @@ export interface ViewDeclOpts {
  * so `db.select().from(<view>)` is typed. Honors `@dbColumnType`; `.existing()`
  * views carry type + physical name only (no PK/default/notNull DDL modifiers).
  */
-function viewColumnLine(f: MetaField, opts: ViewDeclOpts): Code {
+function viewColumnLine(
+  f: MetaField,
+  opts: ViewDeclOpts,
+  /** Codecs this view needs, collected for the caller to DECLARE — see below. */
+  enumIntTypes: Map<string, EnumIntCustomType>,
+): Code {
   const { dialect, columnNamingStrategy, timestampMode } = opts;
   const spec = mapColumnType(f, dialect, columnNamingStrategy, timestampMode);
-  const colSym = imp(`${spec.fnName}@${spec.importModule}`);
+  // An int-backed field.enum's column function is a LOCAL generated const (the
+  // customType helper the caller emits into this same file), so it must not be
+  // imported from drizzle-orm/*-core like a built-in column type would be. Same
+  // rule the table template applies in `renderColumn`; a view reads the very same
+  // integer column and needs the very same decode on the way out.
+  if (spec.enumIntCustomType !== undefined) {
+    enumIntTypes.set(spec.enumIntCustomType.fnConstName, spec.enumIntCustomType);
+  }
+  const colSym =
+    spec.enumIntCustomType !== undefined
+      ? spec.enumIntCustomType.fnConstName
+      : imp(`${spec.fnName}@${spec.importModule}`);
   const optsArg =
     spec.fnOptions && Object.keys(spec.fnOptions).length > 0
       ? `, ${JSON.stringify(spec.fnOptions)}`
@@ -137,7 +162,8 @@ export function renderExistingViewDecl(
   const viewFn = opts.dialect === "postgres" ? "pgView" : "sqliteView";
   const viewModule = opts.dialect === "postgres" ? "drizzle-orm/pg-core" : "drizzle-orm/sqlite-core";
   const viewSym = imp(`${viewFn}@${viewModule}`);
-  const viewColumnLines = fields.map((f) => viewColumnLine(f, opts));
+  const enumIntTypes = new Map<string, EnumIntCustomType>();
+  const viewColumnLines = fields.map((f) => viewColumnLine(f, opts, enumIntTypes));
   const viewNameExpr = typeof viewName === "string" ? code`${JSON.stringify(viewName)}` : viewName;
 
   // @schema — a view lands in a schema exactly as a table does, and migrate qualifies the
@@ -153,7 +179,16 @@ export function renderExistingViewDecl(
   const viewCall: Code = viewSchemaExpr === undefined
     ? code`${viewSym}`
     : code`${imp(`pgSchema@${viewModule}`)}(${viewSchemaExpr}).view`;
-  return code`
+  // Int-backed enum codecs are declared BEFORE the view that references them, sorted
+  // by const name so output is deterministic regardless of field order — the same
+  // contract the table template holds.
+  const alreadyDeclared = opts.declaredEnumIntCodecs;
+  const enumIntBlocks = [...enumIntTypes.values()]
+    .filter((t) => alreadyDeclared === undefined || !alreadyDeclared.has(t.fnConstName))
+    .sort((a, b) => a.fnConstName.localeCompare(b.fnConstName))
+    .map((t) => renderEnumIntCustomType(t, viewModule));
+
+  const viewBlock = code`
 // View declaration — Drizzle uses this for typed SELECT queries.
 // The SQL view is created/managed by migrate-ts; .existing() tells Drizzle
 // not to attempt DDL for this declaration.
@@ -161,6 +196,9 @@ export const ${viewVar} = ${viewCall}(${viewNameExpr}, {
 ${joinCode(viewColumnLines, { on: ",\n" })}
 }).existing();
 `;
+  return enumIntBlocks.length === 0
+    ? viewBlock
+    : joinCode([...enumIntBlocks, viewBlock], { on: "\n" });
 }
 
 /**

package/src/templates/zod-validators.ts

@@ -126,6 +126,28 @@ export function hasAutoSetFields(obj: MetaObject): boolean {
   return false;
 }
 
+/**
+ * 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.
+ *
+ * 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;
+ * 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);
+}
+
 /**
  * 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
@@ -149,10 +171,12 @@ export function renderTphSubtypeReadSchema(obj: MetaObject, ctx?: RenderContext)
     }
     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.
+    // `.nullable()` on top so a NULL column value parses cleanly. The declared
+    // interface widens the SAME fields — see isTphReadNullTolerant.
     fieldLines.push(
-      fieldWillBeOptional(child) ? code`  ${child.name}: ${expr}.nullable()` : code`  ${child.name}: ${expr}`,
+      isTphReadNullTolerant(obj, child)
+        ? code`  ${child.name}: ${expr}.nullable()`
+        : code`  ${child.name}: ${expr}`,
     );
   }