@metaobjectsdev/codegen-ts 0.16.0 → 0.17.0

package/src/projection/view-ddl-emit.ts

@@ -1,4 +1,6 @@
-import type { JoinNode, ViewSpec, ViewFilterClause } from "./view-spec.js";
+import type {
+  JoinNode, ViewSpec, ViewFilterClause, ViewExprNode, ViewOrderKey, SelectColumn,
+} from "./view-spec.js";
 
 // Quote an identifier only when it isn't a plain lowercase snake identifier —
 // exactly postgres's own rule. This keeps snake_case output unquoted (the common
@@ -52,36 +54,158 @@ function renderFilterCond(clause: ViewFilterClause, dialect: EmitOptions["dialec
     const joined = clause.clauses.map((c) => renderFilterCond(c, dialect)).join(clause.kind === "and" ? " AND " : " OR ");
     return `(${joined})`;
   }
-  const ref = quoteRef(clause.ref);
-  if (clause.op === "isNull") return clause.value === false ? `${ref} IS NOT NULL` : `${ref} IS NULL`;
+  // The left-hand side is a bare `alias.column` for a `cmp`, or a parenthesized
+  // inlined computed expression for #207's `exprCmp` (a projection @filter ref to
+  // an origin.computed field). The op handling below is identical for both.
+  const lhs = clause.kind === "exprCmp" ? `(${renderExpr(clause.expr, dialect)})` : quoteRef(clause.ref);
+  if (clause.op === "isNull") return clause.value === false ? `${lhs} IS NOT NULL` : `${lhs} IS NULL`;
   if (clause.op === "in") {
     const vals = (Array.isArray(clause.value) ? clause.value : [clause.value]).map((v) => sqlLiteral(v, dialect));
-    return `${ref} IN (${vals.join(", ")})`;
+    return `${lhs} IN (${vals.join(", ")})`;
   }
   const op = FILTER_OP_SQL[clause.op];
-  if (!op) throw new Error(`view-ddl-emit: unsupported aggregate filter operator "${clause.op}".`);
-  return `${ref} ${op} ${sqlLiteral(clause.value, dialect)}`;
+  if (!op) throw new Error(`view-ddl-emit: unsupported filter operator "${clause.op}".`);
+  return `${lhs} ${op} ${sqlLiteral(clause.value, dialect)}`;
 }
 
-function renderColumn(c: import("./view-spec.js").SelectColumn, dialect: EmitOptions["dialect"]): string {
-  const src = `${c.sourceAlias}.${quoteIfNeeded(c.sourceColumn)}`;
+/**
+ * Render resolved ordering keys, applying the #195 nulls-last pin (`NULLS LAST` in
+ * both directions — PG + SQLite ≥ 3.30). `alias` qualifies each key's column.
+ */
+function renderOrderKeys(keys: readonly ViewOrderKey[], alias: string): string {
+  return keys
+    .map((k) => `${alias}.${quoteIfNeeded(k.column)} ${k.dir.toUpperCase()} NULLS LAST`)
+    .join(", ");
+}
+
+/** Lower a resolved computed expression tree (#195 origin.computed) to a SQL scalar expression. */
+function renderExpr(node: ViewExprNode, dialect: EmitOptions["dialect"]): string {
+  switch (node.kind) {
+    case "col":
+      return quoteRef(node.ref);
+    case "lit":
+      return sqlLiteral(node.value, dialect);
+    case "cmp": {
+      const op = FILTER_OP_SQL[node.op];
+      if (!op) throw new Error(`view-ddl-emit: unsupported computed comparison operator "${node.op}".`);
+      return `${renderExpr(node.left, dialect)} ${op} ${renderExpr(node.right, dialect)}`;
+    }
+    case "nullTest":
+      return `${renderExpr(node.arg, dialect)} IS ${node.negated ? "NOT " : ""}NULL`;
+    case "not":
+      return `NOT (${renderExpr(node.arg, dialect)})`;
+    case "logic": {
+      const joiner = node.op === "and" ? " AND " : " OR ";
+      return `(${node.args.map((a) => renderExpr(a, dialect)).join(joiner)})`;
+    }
+    case "coalesce":
+      return `COALESCE(${node.args.map((a) => renderExpr(a, dialect)).join(", ")})`;
+  }
+}
+
+/**
+ * Lower an `origin.first` column (#195) to a correlated scalar subquery. The subquery
+ * keys on the OUTER base alias (`baseAlias`), so it composes with the view's GROUP BY
+ * (the base PK is always a grouped passthrough column). The child PK ascending is
+ * ALWAYS appended as the final tie-breaker so equal-order rows stay byte-deterministic.
+ */
+function renderFirst(
+  c: Extract<SelectColumn, { kind: "first" }>,
+  options: EmitOptions,
+  baseAlias: string,
+): string {
+  const childTable = options.joinTables[c.childEntity];
+  if (!childTable) {
+    throw new Error(`view-ddl-emit: no table name registered for origin.first child entity "${c.childEntity}".`);
+  }
+  const of = `${c.childAlias}.${quoteIfNeeded(c.sourceColumn)}`;
+  const fk = quoteIfNeeded(c.fkColumn);
+  const pk = quoteIfNeeded(c.pkColumn);
+  // Mirror renderJoin's ON clause, with the child in the subquery and the base outside.
+  //   referenceHolder "source" → FK on base:  child.pk = base.fk   (belongs-to)
+  //   referenceHolder "target" → FK on child: child.fk = base.pk   (has-many)
+  const correlation = c.referenceHolder === "source"
+    ? `${c.childAlias}.${pk} = ${baseAlias}.${fk}`
+    : `${c.childAlias}.${fk} = ${baseAlias}.${pk}`;
+  const filterClause = c.filter ? ` AND ${renderFilterCond(c.filter, options.dialect)}` : "";
+  // The @orderBy keys carry the nulls-last pin; the appended PK tie-breaker never does
+  // (a primary key is non-null, so NULLS LAST would be noise). Its ASC direction makes
+  // equal-order rows byte-deterministic.
+  const tieBreak = `${c.childAlias}.${quoteIfNeeded(c.childPkColumn)} ASC`;
+  const orderKeys = c.orderBy.length > 0
+    ? `${renderOrderKeys(c.orderBy, c.childAlias)}, ${tieBreak}`
+    : tieBreak;
+  return (
+    `(SELECT ${of} FROM ${quoteIfNeeded(childTable)} ${c.childAlias}` +
+    ` WHERE ${correlation}${filterClause} ORDER BY ${orderKeys} LIMIT 1) AS ${quoteIfNeeded(c.dbColAlias)}`
+  );
+}
+
+function renderColumn(c: SelectColumn, options: EmitOptions, baseAlias: string): string {
+  const dialect = options.dialect;
   const alias = quoteIfNeeded(c.dbColAlias);
+
   if (c.kind === "passthrough") {
-    return `${src} AS ${alias}`;
+    return `${c.sourceAlias}.${quoteIfNeeded(c.sourceColumn)} AS ${alias}`;
+  }
+
+  if (c.kind === "aggregate") {
+    const src = `${c.sourceAlias}.${quoteIfNeeded(c.sourceColumn)}`;
+    // aggregate — use DISTINCT for count() over joined PKs to avoid join inflation.
+    // A scoping @filter renders as postgres `FILTER (WHERE …)`; sqlite (no aggregate
+    // FILTER pre-3.30) uses the portable `CASE WHEN … END` argument form.
+    const cond = c.filter ? renderFilterCond(c.filter, dialect) : undefined;
+    if (c.agg === "count") {
+      if (cond && dialect === "sqlite") return `COUNT(DISTINCT CASE WHEN ${cond} THEN ${src} END) AS ${alias}`;
+      if (cond) return `COUNT(DISTINCT ${src}) FILTER (WHERE ${cond}) AS ${alias}`;
+      return `COUNT(DISTINCT ${src}) AS ${alias}`;
+    }
+    const fn = c.agg.toUpperCase();
+    if (cond && dialect === "sqlite") return `${fn}(CASE WHEN ${cond} THEN ${src} END) AS ${alias}`;
+    if (cond) return `${fn}(${src}) FILTER (WHERE ${cond}) AS ${alias}`;
+    return `${fn}(${src}) AS ${alias}`;
+  }
+
+  if (c.kind === "predicateAgg") {
+    // #195 any/all. The phantom-row guard (joined.pk IS NOT NULL) EXCLUDES null-extended
+    // LEFT-JOIN non-matches, so the empty-related-set pins hold: any=false / all=true.
+    const pred = renderFilterCond(c.pred, dialect);
+    const guard = `${c.sourceAlias}.${quoteIfNeeded(c.joinedPkColumn)} IS NOT NULL`;
+    if (dialect === "sqlite") {
+      // No boolean aggregates: MAX≡bool_or, MIN≡bool_and over 1/0. The outer CASE yields
+      // NULL (not 0) for phantom rows so MIN/MAX ignore them — the COALESCE default then
+      // supplies the empty-set pin (0 for any, 1 for all).
+      const fn = c.quant === "any" ? "MAX" : "MIN";
+      const empty = c.quant === "any" ? "0" : "1";
+      return `COALESCE(${fn}(CASE WHEN ${guard} THEN (CASE WHEN ${pred} THEN 1 ELSE 0 END) END), ${empty}) AS ${alias}`;
+    }
+    const fn = c.quant === "any" ? "bool_or" : "bool_and";
+    const empty = c.quant === "any" ? "FALSE" : "TRUE";
+    return `COALESCE(${fn}(${pred}) FILTER (WHERE ${guard}), ${empty}) AS ${alias}`;
   }
-  // aggregate — use DISTINCT for count() over joined PKs to avoid join inflation.
-  // A scoping @filter renders as postgres `FILTER (WHERE …)`; sqlite (no aggregate
-  // FILTER pre-3.30) uses the portable `CASE WHEN … END` argument form.
-  const cond = c.filter ? renderFilterCond(c.filter, dialect) : undefined;
-  if (c.agg === "count") {
-    if (cond && dialect === "sqlite") return `COUNT(DISTINCT CASE WHEN ${cond} THEN ${src} END) AS ${alias}`;
-    if (cond) return `COUNT(DISTINCT ${src}) FILTER (WHERE ${cond}) AS ${alias}`;
-    return `COUNT(DISTINCT ${src}) AS ${alias}`;
+
+  if (c.kind === "collectAgg") {
+    const src = `${c.sourceAlias}.${quoteIfNeeded(c.sourceColumn)}`;
+    const guard = `${c.sourceAlias}.${quoteIfNeeded(c.joinedPkColumn)} IS NOT NULL`;
+    const distinctKw = c.distinct ? "DISTINCT " : "";
+    // Element order: @distinct always orders by the value (PG's array_agg(DISTINCT x
+    // ORDER BY x) co-occurrence rule); otherwise an explicit @orderBy, else the
+    // value-ascending default (both for conformance byte-stability).
+    const orderClause = !c.distinct && c.orderBy.length > 0
+      ? `ORDER BY ${renderOrderKeys(c.orderBy, c.sourceAlias)}`
+      : `ORDER BY ${src} ASC`;
+    if (dialect === "sqlite") {
+      return `COALESCE(json_group_array(${distinctKw}${src} ${orderClause}) FILTER (WHERE ${guard}), json_array()) AS ${alias}`;
+    }
+    return `COALESCE(array_agg(${distinctKw}${src} ${orderClause}) FILTER (WHERE ${guard}), '{}') AS ${alias}`;
+  }
+
+  if (c.kind === "computed") {
+    return `${renderExpr(c.expr, dialect)} AS ${alias}`;
   }
-  const fn = c.agg.toUpperCase();
-  if (cond && dialect === "sqlite") return `${fn}(CASE WHEN ${cond} THEN ${src} END) AS ${alias}`;
-  if (cond) return `${fn}(${src}) FILTER (WHERE ${cond}) AS ${alias}`;
-  return `${fn}(${src}) AS ${alias}`;
+
+  // first — a correlated scalar subquery keyed on the base alias.
+  return renderFirst(c, options, baseAlias);
 }
 
 function renderJoin(
@@ -106,7 +230,10 @@ function renderJoin(
   const onClause = node.referenceHolder === "source"
     ? `${childAlias}.${pkCol} = ${parentAlias}.${fkCol}`
     : `${childAlias}.${fkCol} = ${parentAlias}.${pkCol}`;
-  let sql = `  LEFT OUTER JOIN ${quoteIfNeeded(table)} ${childAlias} ON ${onClause}`;
+  // #209 — join type derived from FK optionality (extract-view-spec): a required
+  // belongs-to FK → INNER (matches the hand-written INNER-join view); else LEFT OUTER.
+  const joinKw = node.joinType === "inner" ? "INNER JOIN" : "LEFT OUTER JOIN";
+  let sql = `  ${joinKw} ${quoteIfNeeded(table)} ${childAlias} ON ${onClause}`;
   for (const childJoin of node.children) {
     sql += "\n" + renderJoin(childJoin, childAlias, options);
   }
@@ -115,12 +242,19 @@ function renderJoin(
 
 export function emitViewDdl(spec: ViewSpec, options: EmitOptions): string {
   const cols = spec.selectSpec.columns
-    .map((c) => "    " + renderColumn(c, options.dialect))
+    .map((c) => "    " + renderColumn(c, options, spec.joinTree.baseAlias))
     .join(",\n");
   const fromClause = `  FROM ${quoteIfNeeded(options.baseTableName)} ${spec.joinTree.baseAlias}`;
   const joinsClause = spec.joinTree.joins
     .map((j) => renderJoin(j, spec.joinTree.baseAlias, options))
     .join("\n");
+  // #207 — a projection-level row @filter is an outer WHERE that scopes which base
+  // rows the view returns. It renders AFTER the joins and BEFORE any GROUP BY (it
+  // filters rows, not aggregate groups — a post-aggregate HAVING is a separate concern).
+  const whereClause =
+    spec.where !== undefined
+      ? `\n  WHERE ${renderFilterCond(spec.where, options.dialect)}`
+      : "";
   const groupByClause =
     spec.groupBy.length > 0
       ? `\n  GROUP BY ${spec.groupBy.map(quoteRef).join(", ")}`
@@ -128,7 +262,7 @@ export function emitViewDdl(spec: ViewSpec, options: EmitOptions): string {
 
   const body = `  SELECT
 ${cols}
-${fromClause}${joinsClause ? "\n" + joinsClause : ""}${groupByClause}`;
+${fromClause}${joinsClause ? "\n" + joinsClause : ""}${whereClause}${groupByClause}`;
 
   if (options.bodyOnly) return body;
   return `CREATE VIEW ${quoteIfNeeded(spec.viewName)} AS

package/src/projection/view-spec.ts

@@ -16,6 +16,12 @@ export interface JoinNode {
   readonly pkColumn: string;
   /** Which side of this hop physically holds the FK: the parent (source) or the child (target). */
   readonly referenceHolder: "source" | "target";
+  /** #209 — `inner` when this is a belongs-to hop whose FK is NOT NULL (required):
+   *  the join can neither drop nor NULL-fill a base row, so it is semantically INNER
+   *  and matches the hand-written INNER-join view it stands in for. `left` otherwise —
+   *  a nullable belongs-to FK, or ANY has-many (inverse-FK) hop, where a base row with
+   *  no match must survive (aggregates COALESCE to 0, not drop the row). */
+  readonly joinType: "inner" | "left";
   /** Child joins. */
   readonly children: readonly JoinNode[];
 }
@@ -31,15 +37,46 @@ export interface JoinTree {
 }
 
 /**
- * A resolved filter clause scoping an aggregate to a subset of related rows. Column
- * refs are already resolved to `alias.column` (naming-strategy applied), so the
- * emitter is a pure renderer. Mirrors the canonical attr.filter shape.
+ * A resolved filter clause. Column refs are already resolved to `alias.column`
+ * (naming-strategy applied), so the emitter is a pure renderer. Mirrors the
+ * canonical attr.filter shape. Used both for an aggregate's scoping `@filter`
+ * (which only ever produces `cmp`/`and`/`or`) and for #207's projection-level
+ * row `@filter` (which may additionally compare an inlined computed expression —
+ * the `exprCmp` node — when a filter ref names an `origin.computed` field).
  */
 export type ViewFilterClause =
   | { readonly kind: "cmp"; readonly ref: string; readonly op: string; readonly value: unknown }
+  // #207 — a comparison whose left-hand side is an inlined computed expression
+  // (a resolved `origin.computed` field referenced by a projection-level @filter),
+  // rather than a bare `alias.column`. Only the view-level WHERE resolver produces
+  // it; aggregate `@filter` resolution never does.
+  | { readonly kind: "exprCmp"; readonly expr: ViewExprNode; readonly op: string; readonly value: unknown }
   | { readonly kind: "and"; readonly clauses: readonly ViewFilterClause[] }
   | { readonly kind: "or"; readonly clauses: readonly ViewFilterClause[] };
 
+/** A scalar literal in a resolved computed expression (mirrors attr.expression's ExprLiteral). */
+export type ViewExprLiteral = string | number | boolean | null;
+
+/**
+ * A resolved node of an `origin.computed` expression (#195). Field refs are already
+ * lowered to a physical `alias.column` (base alias + naming strategy applied), so the
+ * emitter is a pure tree-walk. Mirrors the closed `attr.expression` node grammar.
+ */
+export type ViewExprNode =
+  | { readonly kind: "col"; readonly ref: string }                                       // resolved base column `alias.column`
+  | { readonly kind: "lit"; readonly value: ViewExprLiteral }                            // scalar literal
+  | { readonly kind: "cmp"; readonly op: string; readonly left: ViewExprNode; readonly right: ViewExprNode } // eq/ne/gt/gte/lt/lte
+  | { readonly kind: "nullTest"; readonly negated: boolean; readonly arg: ViewExprNode } // isNull / isNotNull
+  | { readonly kind: "not"; readonly arg: ViewExprNode }
+  | { readonly kind: "logic"; readonly op: "and" | "or"; readonly args: readonly ViewExprNode[] }
+  | { readonly kind: "coalesce"; readonly args: readonly ViewExprNode[] };
+
+/** A resolved ordering key: a physical column (naming-strategy applied) + direction. */
+export interface ViewOrderKey {
+  readonly column: string;
+  readonly dir: "asc" | "desc";
+}
+
 /** One column of the SELECT list. */
 export type SelectColumn =
   | {
@@ -58,6 +95,62 @@ export type SelectColumn =
       readonly sourceColumn: string;
       /** Optional scoping filter (origin.aggregate @filter) → SQL aggregate FILTER (WHERE …). */
       readonly filter?: ViewFilterClause;
+    }
+  | {
+      // #195 — origin.aggregate @agg:any|all — a predicate quantifier over the related
+      // row-set. Lowered to COALESCE(bool_or/bool_and(pred) FILTER (WHERE joined.pk IS
+      // NOT NULL), FALSE/TRUE) on PG; MAX/MIN(CASE …) on SQLite. Empty set → false (any)
+      // / true (all). Inflation-immune; never null.
+      readonly kind: "predicateAgg";
+      readonly fieldName: string;
+      readonly dbColAlias: string;
+      readonly quant: "any" | "all";
+      readonly sourceAlias: string;      // alias of the related (aggregated) entity
+      readonly joinedPkColumn: string;   // related entity's PK column — the LEFT-JOIN phantom guard
+      readonly pred: ViewFilterClause;   // the quantified predicate (origin.aggregate @filter — required)
+    }
+  | {
+      // #195 — origin.aggregate @agg:collect — array rollup of @of across the related set.
+      // Lowered to COALESCE(array_agg(<of> [DISTINCT] ORDER BY …) FILTER (WHERE joined.pk
+      // IS NOT NULL), '{}') on PG; json_group_array on SQLite. Empty set → []. Default
+      // element order = value ascending (byte-stability); @distinct dedupes.
+      readonly kind: "collectAgg";
+      readonly fieldName: string;
+      readonly dbColAlias: string;
+      readonly sourceAlias: string;
+      readonly sourceColumn: string;     // the @of column (collected value)
+      readonly joinedPkColumn: string;   // related entity's PK column — the LEFT-JOIN phantom guard
+      readonly distinct: boolean;
+      /** Element ordering over the @of entity's columns; empty ⇒ value-ascending default. */
+      readonly orderBy: readonly ViewOrderKey[];
+    }
+  | {
+      // #195 — origin.computed — a row-level value from the base entity's own fields via
+      // a structured @expr tree (no related rows). Lowered by a tree-walk to a SQL scalar
+      // expression over the base alias's columns.
+      readonly kind: "computed";
+      readonly fieldName: string;
+      readonly dbColAlias: string;
+      readonly expr: ViewExprNode;
+    }
+  | {
+      // #195 — origin.first — argmax-then-project: the single related row selected by
+      // @orderBy along @via, projecting @of. Lowered to a CORRELATED scalar subquery
+      // keyed on the base alias (coexists with the outer GROUP BY). Empty set → null.
+      readonly kind: "first";
+      readonly fieldName: string;
+      readonly dbColAlias: string;
+      readonly childEntity: string;      // entity name of the related rows (for table lookup)
+      readonly childAlias: string;       // FRESH subquery alias (never a JOIN-tree alias)
+      readonly sourceColumn: string;     // the @of column projected from the selected row
+      /** Correlation direction (mirrors JoinNode.referenceHolder). */
+      readonly referenceHolder: "source" | "target";
+      readonly fkColumn: string;         // FK column (resolved) for the base↔child correlation
+      readonly pkColumn: string;         // PK column (resolved) for the base↔child correlation
+      readonly childPkColumn: string;    // child's own PK column — the determinism tie-breaker
+      readonly orderBy: readonly ViewOrderKey[]; // row-selection ordering over the child entity
+      /** Optional scoping filter over the child entity (refs use `childAlias`). */
+      readonly filter?: ViewFilterClause;
     };
 
 export interface SelectSpec {
@@ -71,4 +164,12 @@ export interface ViewSpec {
   readonly selectSpec: SelectSpec;
   /** non-aggregate column SQL fragments to put in GROUP BY (empty if no aggregates). */
   readonly groupBy: readonly string[];
+  /**
+   * #207 — a projection-level row `@filter` (view-level WHERE): a resolved predicate
+   * over the projection's OWN fields (each ref already lowered to `alias.column`),
+   * rendered as an outer `WHERE` BEFORE any `GROUP BY` — it scopes which base rows the
+   * view returns (soft-delete / status / type views). Distinct from an aggregate's
+   * `@filter`, which scopes the rows a single aggregate spans. Undefined = no filter.
+   */
+  readonly where?: ViewFilterClause;
 }

package/src/reference/entity.ts

@@ -42,8 +42,11 @@ import {
   SHARED_ENUMS_BASENAME,
   // predicates + helpers:
   isProjection,
+  isWriteThrough,
   isAbstract,
   hasWritableRdbSource,
+  // engine composer — used for the delegated write-through variant:
+  renderEntityFile,
   // engine plumbing:
   formatTs,
   entityOutputPath,
@@ -79,8 +82,15 @@ function renderEntity(entity: MetaObject, ctx: RenderContext, opts?: RenderEntit
   if (!runtime || !hasWritableRdbSource(entity)) {
     return renderValueObjectFile(entity, ctx.apiPrefix, ctx);
   }
+  // #214 — a write-through entity read-view (writable table + a read-only replica view +
+  // derived origin.* fields) needs the hybrid file (table + `.existing()` view decl + a
+  // z.infer read type carrying the derived fields). Delegate to the engine composer rather
+  // than duplicate that branch here (mirrors the projection delegation above).
+  if (isWriteThrough(entity)) {
+    return renderEntityFile(entity, ctx, { allowlists });
+  }
 
-  // Write-through entity → the full Drizzle table file. Reorder/drop sections freely.
+  // Vanilla entity → the full Drizzle table file. Reorder/drop sections freely.
   const enumAliases = renderEnumTypeAliases(entity, ctx);
   const tphBlock = renderTphDiscriminatorUnion(entity, ctx.loadedRoot);
   const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);

package/src/reference/queries.ts

@@ -31,6 +31,7 @@ import {
   reverseFksFor,
   isTphDiscriminatorBase,
   isProjection,
+  isWriteThrough,
   isTphSubtype,
   renderQueriesFile, // engine composer — used for the delegated variants
   formatTs,
@@ -41,7 +42,9 @@ import {
 // --- composition (OWNED for the common case) ---
 function renderQueries(obj: MetaObject, ctx: RenderContext): string {
   // Advanced variants delegate to the engine (byte-identical). Own them by copying their source.
-  if (isTphDiscriminatorBase(obj, ctx.loadedRoot) || isProjection(obj)) {
+  // #214 — a write-through entity read-view (reads → replica view, writes → table) delegates
+  // too; owning it inline would duplicate the hybrid read/write routing.
+  if (isTphDiscriminatorBase(obj, ctx.loadedRoot) || isProjection(obj) || isWriteThrough(obj)) {
     return renderQueriesFile(obj, ctx);
   }
 

package/src/templates/drizzle-schema.ts

@@ -66,6 +66,11 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   // Collect CHECK constraints for enum columns; emitted as table-level check() callbacks.
   const checkConstraints: Array<{ name: string; expr: string }> = [];
   for (const child of obj.fields()) {
+    // #213 — a derived (origin-bearing) field is read-only, materialized on the
+    // read (view) side, NOT a column on the entity's write table (FR-024 §7).
+    // Emitting it here would declare a Drizzle column for a table column migrate
+    // no longer creates.
+    if (child.isDerived()) continue;
     const isPk = pkFieldNames.has(child.name);
     const isUnique = uniqueFieldNames.has(child.name) && !isPk;
     const fkInfo = fkMap.get(child.name);
@@ -90,6 +95,8 @@ export function renderDrizzleSchema(obj: MetaObject, ctx: RenderContext): Code {
   // stamp onto other-subtype inserts), regardless of the field's @required.
   // Subtype entities emit no table of their own (the value-object path).
   for (const child of collectTphSubtypeFields(obj, ctx.loadedRoot)) {
+    // #213 — a TPH subtype's derived field is read-only too; never a table column.
+    if (child.isDerived()) continue;
     const spec = mapColumnType(child, ctx.dialect, ctx.columnNamingStrategy, ctx.timestampMode);
     const fieldDocs = renderDocsFor(child);
     const columnLine = renderColumn(

package/src/templates/entity-file.ts

@@ -6,7 +6,7 @@
 //   !hasWritableRdbSource(entity)      → renderValueObjectFile (in-memory / transit shape: interface + Zod schema)
 //   vanilla / write-through entity     → Drizzle table path
 
-import { joinCode, type Code } from "ts-poet";
+import { code, imp, joinCode, type Code } from "ts-poet";
 import type { MetaObject } from "@metaobjectsdev/metadata";
 import type { RenderContext } from "../render-context.js";
 import { renderDrizzleSchema } from "./drizzle-schema.js";
@@ -17,8 +17,13 @@ import { renderFilterAllowlist, renderSortAllowlist } from "./filter-allowlist.j
 import { renderFilterType } from "./filter-type.js";
 import { renderTphDiscriminatorUnion, isTphDiscriminatorBase } from "./tph-discriminator.js";
 import { GENERATED_HEADER } from "../constants.js";
-import { isProjection } from "../projection/projection-detector.js";
+import { isProjection, isWriteThrough } from "../projection/projection-detector.js";
 import { renderProjectionDecl } from "./projection-decl.js";
+import { projectionViewName } from "../projection/extract-view-spec.js";
+import { renderExistingViewDecl, renderViewReadZodObject } from "./view-decl.js";
+import { renderDocsFor } from "./jsdoc.js";
+import { valueObjectModuleSpecifier } from "../import-path.js";
+import { stripPackage } from "@metaobjectsdev/metadata";
 import { hasWritableRdbSource } from "../source-detect.js";
 import { renderValueObjectFile } from "./value-object-file.js";
 import { isAbstract } from "../instance-artifacts.js";
@@ -108,9 +113,47 @@ export function renderEntityFile(
   // bare `<Base>` type — so the inferred Drizzle row type is emitted as
   // `<Base>Row` to avoid a duplicate `export type <Base>`.
   const tphBase = tphBlock !== null && isTphDiscriminatorBase(entity, ctx.loadedRoot);
+
+  // #214 — a write-through entity read-view (FR-024 §7): reads route to the replica
+  // VIEW, so the entity file additionally declares the `.existing()` view (carrying the
+  // derived fields the write table omits, #213) and a read schema `<Entity>Schema`
+  // whose `z.infer` IS the read type <Entity> (dialect-agnostic — a Drizzle view is not
+  // a Table, so InferSelectModel/`$inferSelect` don't uniformly apply; the Zod schema's
+  // nullability mirrors the view columns exactly like a projection). The write table +
+  // Insert/Update stay derived-free. `.existing()` is a runtime-target Drizzle binding,
+  // and this path only runs in a runtime target (contract-only/non-writable returned above).
+  // A TPH discriminator base owns `export type <Base>` via its discriminated-union block,
+  // so it must NOT also emit the view-schema read type (that would be a duplicate-identifier
+  // 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;
+  const viewSections: Code[] = [];
+  if (writeThrough) {
+    const camel = entity.name.charAt(0).toLowerCase() + entity.name.slice(1);
+    const fields = entity.fields();
+    const voModule = (refBase: string): string =>
+      valueObjectModuleSpecifier(stripPackage(refBase), ctx.packageOf, entity.package, ctx.outputLayout, ctx.extStyle);
+    const viewOpts = {
+      dialect: ctx.dialect, columnNamingStrategy: ctx.columnNamingStrategy, timestampMode: ctx.timestampMode, voModule,
+    };
+    const z = imp("z@zod");
+    const docs = renderDocsFor(entity);
+    const docsPrefix = docs ? `${docs}\n` : "";
+    viewSections.push(
+      renderExistingViewDecl(fields, projectionViewName(entity, ctx.columnNamingStrategy), `${camel}View`, viewOpts),
+      code`
+export const ${entity.name}Schema = ${renderViewReadZodObject(fields, viewOpts)};
+`,
+      code`
+${docsPrefix}export type ${entity.name} = ${z}.infer<typeof ${entity.name}Schema>;
+`,
+    );
+  }
+
   const sections: Code[] = [
     renderDrizzleSchema(entity, ctx),
-    renderInferredTypes(entity, tphBase, ctx),
+    ...viewSections,
+    renderInferredTypes(entity, tphBase, ctx, writeThrough /* skipRow — read type is the view schema */),
     ...(enumAliases !== null ? [enumAliases] : []),
     renderZodValidators(entity, ctx),
     renderEntityConstants(entity, ctx.apiPrefix),

package/src/templates/inferred-types.ts

@@ -51,7 +51,12 @@ import type { RenderContext } from "../render-context.js";
  * to avoid a duplicate `export type <Base>`. Insert/Update keep their names
  * (no collision); they describe the physical TPH table row shape.
  */
-export function renderInferredTypes(entity: MetaObject, tphBase = false, ctx?: RenderContext): Code {
+export function renderInferredTypes(
+  entity: MetaObject,
+  tphBase = false,
+  ctx?: RenderContext,
+  skipRow = false,
+): Code {
   // The inferred Row/Insert types reference the Drizzle table var, so they must
   // resolve to the SAME (possibly overridden) collection name the schema emits.
   // ctx is optional for bare unit-test calls — those fall back to the default
@@ -64,6 +69,18 @@ export function renderInferredTypes(entity: MetaObject, tphBase = false, ctx?: R
   const docs = renderDocsFor(entity);
   const docsPrefix = docs ? `${docs}\n` : "";
   const rowName = tphBase ? `${entity.name}Row` : entity.name;
+  // #214 — a write-through entity read-view routes READS to the replica view, so the
+  // read row type <Entity> is emitted from the VIEW's read schema (z.infer, carrying
+  // the derived fields) by the entity-file composer, NOT here. `skipRow` suppresses
+  // the table-inferred Row so there is no duplicate `export type <Entity>` (selectSym
+  // then goes unreferenced and ts-poet drops its import). Insert/Update always stay
+  // inferred from the write TABLE (derived-free, #213).
+  if (skipRow) {
+    return code`
+export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;
+export type ${entity.name}Update = Partial<${entity.name}Insert>;
+`;
+  }
   return code`
 ${docsPrefix}export type ${rowName} = ${selectSym}<typeof ${varName}>;
 export type ${entity.name}Insert = ${insertSym}<typeof ${varName}>;