@@ -28,8 +28,38 @@ edit (two registered `description` strings) and was ruled a hold, as 1.0.4's was
   also stop saying the `verify` checks run in every port: the vocabulary loads and
   validates in all five, and the checks run in the Node `meta` CLI.
 
+### Added
+
+- **Codegen-compile conformance (TypeScript lane).** A new gate generates from the shared
+  cross-port corpus (`fixtures/persistence-conformance/canonical/meta.fitness.json` — 16
+  entities, 2 view-backed projections, two M:N through-junctions, a 4-entity TPH hierarchy,
+  jsonb storage, `isArray`, currency, decimal, and an `AllTypes` entity carrying every
+  persistable field subtype) and compiles every emitted module with the real TS compiler, on
+  both dialects. The existing corpora gate BEHAVIOR; none of them asked whether the emitted
+  code builds, which is why four separate "generated code does not compile" defects shipped
+  in 1.0.4 with every gate green. It found three more on its first run — all three are fixed
+  below. Peer lanes for the other ports are still to come; a port without this gate keeps
+  exactly the bug class it closes.
+
 ### Fixed
 
+- **A TPH subtype's declared type and its read schema disagreed, so `parse<Base>()` did not
+  compile.** The generated `<Sub>` interface and the `<Sub>Schema` the polymorphic
+  dispatcher parses through were emitted by two rules that answered the same question
+  differently. The schema made the PRIMARY KEY `.nullable()` — it is the shared base table's
+  key and is present on every row — while the interface did not admit `null` for a
+  subtype-only column, which genuinely is NULL on a sibling's row. Either way the value
+  `parse<Base>()` returns was not assignable to the base union (`TS2322`). Both emitters now
+  route through one predicate, `isTphReadNullTolerant`. **Generated output changes**: a TPH
+  subtype's interface widens its null-tolerant fields to `| null`, and its read schema stops
+  widening the PK.
+- **`@dbColumnType: jsonb` emitted a SQLite column that did not match its own type.** The
+  open-JSON-bag escape hatch types the field `unknown` in Zod and TS, because the value
+  round-trips as a PARSED JSON value on every dialect. On SQLite the attribute fell through
+  to a plain `text()` column typed `string`, so the generated queries did not compile — and
+  had they compiled, the value would have come back as a JSON-encoded string. It now emits
+  `text(..., { mode: "json" })`, the same idiomatic form `field.object` and `field.map`
+  already take on that dialect. Postgres is unchanged. **Generated output changes** on SQLite.
 - **A view-backed read model carrying an int-backed `field.enum` generated a module that did
   not compile.** A `@intValueMap` enum persists as an integer column, and the entity table
   emits a module-local Drizzle `customType` codec to encode and decode it. The view path
 
@@ -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:
 
@@ -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
 
@@ -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}`,
     );
   }
 
 
@@ -0,0 +1,139 @@
+// CODEGEN-COMPILE CONFORMANCE (TypeScript lane)
+//
+// Generate from the SHARED cross-port corpus — fixtures/persistence-conformance/
+// canonical/meta.fitness.json — and compile every emitted module with the real TS
+// compiler. Zero diagnostics or the lane is red.
+//
+// WHY THIS EXISTS. Four defects shipped in 1.0.4 that every existing gate was blind to,
+// because each one produced output that PARSES and GENERATES cleanly and only fails when
+// somebody builds it:
+//
+//   - a view over an int-backed enum imported a codec drizzle does not export (TS);
+//   - a renamed projection field selected a column that does not exist (TS);
+//   - a DbContext named FK config through `nameof` on a member that is not there (C#);
+//   - an extract mapper did not compile for most scalar subtypes (Java).
+//
+// `meta gen` exits 0 in all four cases. The metamodel, render, persistence, api-contract
+// and registry corpora all stay green — they gate BEHAVIOR, and none of them asks whether
+// the emitted code builds. The adopter's build is the first thing that does, which makes
+// the adopter the gate. This closes that.
+//
+// WHY THE FITNESS CORPUS rather than a fixture of its own: it is already the shared
+// cross-port model (16 entities, 2 view-backed projections, 2 value objects, two M:N
+// through-junctions incl. a self-join, a 4-entity TPH hierarchy, jsonb storage, isArray,
+// field.currency, field.decimal, and an AllTypes entity carrying every persistable field
+// subtype incl. @intValueMap). A second kitchen sink would drift from the first, and the
+// coverage this gate has is exactly the coverage the other corpora already maintain.
+//
+// The peer lanes are the same test in each port. If one port drops out, that port keeps
+// precisely the bug class this exists to catch — so a skip here is never "just this lane".
+
+import { describe, test, expect } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import ts from "typescript";
+import { loadUris, type MetaRoot, type MetaObject } from "@metaobjectsdev/metadata";
+import { entityFile } from "../src/generators/entity-file.js";
+import { namesFile } from "../src/generators/names-file.js";
+import { queriesFile } from "../src/generators/queries-file.js";
+import { barrel } from "../src/generators/barrel.js";
+import { makeRenderContext } from "../src/render-context.js";
+import { buildPkMap } from "../src/pk-resolver.js";
+import { buildRelationMap } from "../src/relation-resolver.js";
+import type { GenContext } from "../src/generator.js";
+
+// test → codegen-ts → packages → typescript → server → repo root
+const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..", "..", "..", "..");
+const CORPUS = resolve(
+  REPO_ROOT,
+  "fixtures",
+  "persistence-conformance",
+  "canonical",
+  "meta.fitness.json",
+);
+
+async function loadCorpus(): Promise<MetaRoot> {
+  const result = await loadUris([pathToFileURL(CORPUS).href]);
+  if (result.errors.length > 0) {
+    throw new Error(
+      `${CORPUS} did not load cleanly:\n` +
+        result.errors.map((e) => `  ${(e as { code?: string }).code ?? "ERROR"}: ${e.message}`).join("\n"),
+    );
+  }
+  return result.root;
+}
+
+describe("codegen-compile conformance — the shared fitness corpus", () => {
+  for (const dialect of ["postgres", "sqlite"] as const) {
+    test(`${dialect}: every generated module compiles with zero diagnostics`, async () => {
+      const root = await loadCorpus();
+      const dir = mkdtempSync(join(import.meta.dir, `tmp-codegen-compile-${dialect}-`));
+      try {
+        const renderContext = makeRenderContext({
+          dialect,
+          loadedRoot: root,
+          outDir: dir,
+          dbImport: "~/db",
+          pkMap: buildPkMap(root),
+          relationMap: buildRelationMap(root),
+        });
+        // `matches` is composed from each generator's OWN filter, exactly as runner.ts
+        // does it (`matches: (e) => generator.filter?.(e) ?? true`). Hardcoding
+        // `() => true` here would run every generator over every object and report the
+        // generator's own deliberate exclusions — a value object has no table, a TPH
+        // subtype no standalone one — as if they were emit bugs. The gate has to run the
+        // generators the way the runner runs them or it measures the harness.
+        const genCtx = (generator: { filter?: (e: MetaObject) => boolean }): GenContext => ({
+          entities: root.objects(),
+          loadedRoot: root,
+          matches: (e) => generator.filter?.(e) ?? true,
+          projectRoot: dir,
+          config: { outDir: dir, extStyle: "none", dbImport: "~/db", dialect } as never,
+          renderContext,
+          warn: () => {},
+        });
+
+        // The model tier plus its consumers. `allowlists: false` keeps the program over
+        // drizzle + zod alone, so a diagnostic is about OUR emit and not a runtime-ts
+        // resolution problem; routes are excluded for the same reason C#'s compile test
+        // excludes them — the server framework's types would drown the signal.
+        const generators = [
+          entityFile({ allowlists: false }),
+          namesFile(),
+          queriesFile(),
+          barrel(),
+        ];
+        const files = (
+          await Promise.all(generators.map((g) => g.generate(genCtx(g))))
+        ).flat();
+        expect(files.length).toBeGreaterThan(0);
+        for (const f of files) writeFileSync(join(dir, f.path), f.content);
+
+        const program = ts.createProgram(
+          files.map((f) => join(dir, f.path)),
+          {
+            strict: true,
+            noEmit: true,
+            target: ts.ScriptTarget.ES2022,
+            module: ts.ModuleKind.ESNext,
+            moduleResolution: ts.ModuleResolutionKind.Bundler,
+            skipLibCheck: true,
+          },
+        );
+        const diagnostics = ts.getPreEmitDiagnostics(program).map((d) => {
+          const where =
+            d.file && d.start !== undefined
+              ? `${d.file.fileName.slice(dir.length + 1)}:${
+                  d.file.getLineAndCharacterOfPosition(d.start).line + 1
+                } `
+              : "";
+          return `${where}${ts.flattenDiagnosticMessageText(d.messageText, "\n")}`;
+        });
+        expect(diagnostics).toEqual([]);
+      } finally {
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+  }
+});