fix(#213): emit the entity read-view's replica view (isWriteThrough → one emitter)

#213 hole 2 (the missing-view half): a write-through entity (FR-024 §7 — a writable
table source PLUS a non-primary read-only view source + derived origin.* fields) never
got its replica view emitted. `isWriteThrough` was defined, exported, and tested but
had ZERO call sites; buildProjectionViews walked isProjection only, so migrate never
generated or owned the view — reads had nowhere to resolve the derived columns from.

Now the entity is a second host for the ONE canonical view emitter ("one emitter, two
hosts"):
- extract-view-spec: a write-through entity IS its own base (isWriteThrough → base =
  the entity), and buildSelectSpec exposes its EFFECTIVE field set (o.* incl.
  extends-inherited fields) — stored fields project from the base alias, derived
  (origin.*) fields from the joins. A plain projection keeps its declared-own-set
  exposure + extends-anchored base, unchanged.
- build-projection-views: a second walk over isWriteThrough entities feeds them through
  a shared emitViewFor() tail (the projection loop now uses it too — no duplication).
  Only a plain `view` read source synthesizes DDL (matview/proc/tableFunction stay
  hand-managed, same as projections). isProjection and isWriteThrough are mutually
  exclusive, so the walks never overlap.

Together with the write-side exclusions (6a58732), a `SELECT o.*, extra` legacy view
now models cleanly as an entity read-view: writes → the table (no derived columns),
reads → the emitted view. The #206 docs on-ramp becomes drivable.

Verified: new view-emission test (view produced; SELECT = o.* stored fields from the
base + the derived join column; derived col never projects from o.*); codegen-ts 962
pass; typecheck exit 0; canonical schema.postgres.sql drift gate byte-identical (its
view is a projection, not write-through — no overlap).

Follow-up verification (before any release): a migrate round-trip PG/SQLite gate for a
write-through entity (emit → apply → introspect → re-diff EMPTY) + a
persistence-conformance write-through fixture — the emitter is already round-trip-gated
for projections, but the entity host wants its own gate. Known limitation: a flattened
field.object on a write-through entity is not yet handled in the entity-host SELECT
(scalars + derived joins are). The cross-port §7 codegen-half (other ports' ORM/DTO
derived-field exclusions + read routing + the entity read TYPE) remains a separate
coordinated issue.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NGQ7oSuNcjhsMHWwZzhBwr

Author: dmealing

server/typescript/packages/codegen-ts/src/projection/build-projection-views.ts

@@ -21,7 +21,7 @@ import {
   resolveTableName,
   resolveTableSchema,
 } from "@metaobjectsdev/metadata";
-import { isProjection } from "./projection-detector.js";
+import { isProjection, isWriteThrough } from "./projection-detector.js";
 import { extractViewSpec } from "./extract-view-spec.js";
 import { emitViewDdl } from "./view-ddl-emit.js";
 import type { JoinNode, ViewSpec } from "./view-spec.js";
@@ -119,24 +119,54 @@ export function buildProjectionViews(
     );
     if (readOnlySource?.effectiveKind !== SOURCE_KIND_VIEW) continue;
     if (!viewIsDerived(projection)) continue;
-    const spec = extractViewSpec(projection, root, { columnNamingStrategy });
-    const baseTableName = joinTables[spec.joinTree.baseEntity];
-    if (!baseTableName) continue; // unresolved base — skip (loader/codegen surface the error elsewhere)
-    const body = emitViewDdl(spec, { dialect, baseTableName, joinTables, bodyOnly: true });
-    const schema = resolveTableSchema(projection);
-    const dependsOn = collectDependsOn(spec, baseTableName, joinTables);
-    const columns = collectViewColumns(spec, baseTableName, joinTables);
-    out.push({
-      name: spec.viewName,
-      sql: body,
-      dependsOn,
-      columns,
-      ...(schema !== undefined ? { schema } : {}),
-    });
+    emitViewFor(projection, root, joinTables, dialect, columnNamingStrategy, out);
+  }
+
+  // #213 hole 2 — a write-through ENTITY (FR-024 §7 read-view: a writable table
+  // source PLUS a non-primary read-only view source, with derived origin.* fields)
+  // hosts its OWN view. Emit it through the SAME canonical emitter — "one emitter,
+  // two hosts". `isWriteThrough` had zero call sites, so this replica view was never
+  // generated or owned by migrate. Unlike a projection there is no extends anchor
+  // and no viewIsDerived gate: the entity IS the base (extractViewSpec detects the
+  // write-through host), and it always has a derived view to emit. Only a plain
+  // `view` read source synthesizes CREATE VIEW DDL — a matview/proc/tableFunction
+  // read source is hand-managed, exactly as for projections above.
+  for (const entity of root.objects().filter(isWriteThrough)) {
+    const readOnlySource = entity.ownChildren().find(
+      (c): c is MetaSource => c instanceof MetaSource && c.isReadOnly(),
+    );
+    if (readOnlySource?.effectiveKind !== SOURCE_KIND_VIEW) continue;
+    emitViewFor(entity, root, joinTables, dialect, columnNamingStrategy, out);
   }
   return out;
 }
 
+/** Extract + emit one host's (projection or write-through entity) view body and
+ *  push it onto `out`. The single tail shared by both walks in buildProjectionViews. */
+function emitViewFor(
+  host: MetaObject,
+  root: MetaRoot,
+  joinTables: Record<string, string>,
+  dialect: "postgres" | "sqlite",
+  columnNamingStrategy: ColumnNamingStrategy,
+  out: ExpectedView[],
+): void {
+  const spec = extractViewSpec(host, root, { columnNamingStrategy });
+  const baseTableName = joinTables[spec.joinTree.baseEntity];
+  if (!baseTableName) return; // unresolved base — skip (loader/codegen surface the error elsewhere)
+  const body = emitViewDdl(spec, { dialect, baseTableName, joinTables, bodyOnly: true });
+  const schema = resolveTableSchema(host);
+  const dependsOn = collectDependsOn(spec, baseTableName, joinTables);
+  const columns = collectViewColumns(spec, baseTableName, joinTables);
+  out.push({
+    name: spec.viewName,
+    sql: body,
+    dependsOn,
+    columns,
+    ...(schema !== undefined ? { schema } : {}),
+  });
+}
+
 /**
  * The SELECT list as PHYSICAL (table, column) pairs, in emitted order.
  *

server/typescript/packages/codegen-ts/src/projection/extract-view-spec.ts

@@ -44,11 +44,14 @@ import {
   stripPackage,
   type AggregateFunction,
 } from "@metaobjectsdev/metadata";
-import { type MetaData, type MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
+import { type MetaData, type MetaField, type MetaRoot, MetaObject } from "@metaobjectsdev/metadata";
 import {
   columnNameFromField,
   viewNameFromProjection,
 } from "../naming.js";
+// #213 — a write-through ENTITY (FR-024 §7 read-view) hosts its own view; the base
+// is the entity itself, not an extends-anchored projection.
+import { isWriteThrough } from "./projection-detector.js";
 // #209 — the SAME NOT-NULL predicate that drives a column's `.notNull()` decides
 // whether a belongs-to join is INNER (required FK) vs LEFT OUTER (nullable FK).
 import { isRequired } from "../column-mapper.js";
@@ -625,12 +628,17 @@ function buildSelectSpec(
   // is removed with the B4b cutover: base columns are declared explicitly as
   // extends-bound fields (`{ field.int: { name: id, extends: "Program.id" } }`).
 
-  // Fields explicitly declared on the projection.
-  // ADR-0039: own — the projection's DECLARED field set IS the exposure
-  // (FR-024/ADR-0028); iterate own fields + each field's own origin. origin.*
-  // NEVER inherits (ADR-0029), so the origin attr reads below are own (category 4).
-  for (const field of projection.ownChildren()) {
-    if (field.type !== TYPE_FIELD) continue;
+  // #213 — an entity read-view HOST (base === projection, FR-024 §7) exposes its
+  // EFFECTIVE field set: the `o.*` includes fields inherited via extends (a
+  // BaseEntity id/createdAt). A plain projection exposes only its DECLARED (own)
+  // 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);
+  for (const field of declaredFields) {
     const origin = field.ownChildren().find((c) => c.type === TYPE_ORIGIN);
     const dbCol = sourceColumnNameFor(field, ctx);
 
@@ -863,7 +871,10 @@ export function extractViewSpec(
   root: MetaRoot,
   ctx: ExtractContext,
 ): ViewSpec {
-  const base = baseEntityFor(projection, root);
+  // #213 — a write-through entity (FR-024 §7) IS its own base: stored fields SELECT
+  // from the base alias (o.*), derived (origin.*) fields from the joins. A plain
+  // projection anchors its base via an extends binding (baseEntityFor).
+  const base = isWriteThrough(projection) ? projection : baseEntityFor(projection, root);
   const usedAliases = new Set<string>();
   const baseAlias = shortAliasFor(base.name, usedAliases);
   const joinTree = buildJoinTree(projection, base, root, usedAliases, baseAlias, ctx);

server/typescript/packages/codegen-ts/test/projection/issue-213-entity-read-view-emit.test.ts

@@ -0,0 +1,66 @@
+// #213 hole 2 — the FR-024 §7 entity read-view's replica-view DDL must be EMITTED.
+// `isWriteThrough` had zero call sites; buildProjectionViews walked isProjection only,
+// so a write-through entity's view was never generated/owned. Now it is: base = the
+// entity itself, its stored fields SELECT from the base alias (o.*), its derived
+// (origin.*) fields SELECT from the join — "one emitter, two hosts".
+
+import { describe, test, expect } from "bun:test";
+import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
+import { buildProjectionViews } from "../../src/projection/build-projection-views.js";
+
+async function loadWriteThroughOrder() {
+  const json = JSON.stringify({
+    "metadata.root": {
+      package: "acme",
+      children: [
+        { "object.entity": { name: "Customer", children: [
+          { "source.rdb": { "@table": "customers" } },
+          { "field.long": { name: "id" } },
+          { "field.string": { name: "name" } },
+          { "identity.primary": { name: "pk", "@fields": "id" } },
+        ] } },
+        { "object.entity": { name: "Order", children: [
+          { "source.rdb": { "@role": "primary", "@table": "orders" } },
+          { "source.rdb": { "@role": "replica", "@kind": "view", "@table": "v_order_with_customer" } },
+          { "field.long": { name: "id" } },
+          { "field.long": { name: "customerId", "@required": true } },
+          { "field.string": { name: "customerName", children: [
+            { "origin.passthrough": { "@from": "Customer.name", "@via": "Order.customer" } } ] } },
+          { "relationship.association": { name: "customer", "@objectRef": "Customer", "@cardinality": "one" } },
+          { "identity.primary": { name: "pk", "@fields": "id" } },
+          { "identity.reference": { name: "ref_customer", "@fields": "customerId", "@references": "Customer" } },
+        ] } },
+      ],
+    },
+  });
+  const { root, errors } = await new MetaDataLoader().load([new InMemoryStringSource(json)]);
+  expect(errors).toEqual([]);
+  return root;
+}
+
+describe("#213 — write-through entity emits its replica view", () => {
+  test("a view named after the read source is produced", async () => {
+    const views = buildProjectionViews(await loadWriteThroughOrder(), { dialect: "postgres", columnNamingStrategy: "snake_case" });
+    const v = views.find((x) => x.name === "v_order_with_customer");
+    expect(v).toBeDefined();
+  });
+
+  test("the SELECT is o.* (stored fields from the base) + the derived join column", async () => {
+    const views = buildProjectionViews(await loadWriteThroughOrder(), { dialect: "postgres", columnNamingStrategy: "snake_case" });
+    const sql = views.find((x) => x.name === "v_order_with_customer")!.sql;
+    expect(sql).toContain("FROM orders");
+    // stored fields project from the base alias
+    expect(sql).toMatch(/\bid AS id\b/);
+    expect(sql).toMatch(/customer_id AS customer_id/);
+    // the derived extra projects from the joined customers table
+    expect(sql).toContain("name AS customer_name");
+    expect(sql).toContain("JOIN customers");
+  });
+
+  test("the derived column does NOT project from the base (it is the joined value)", async () => {
+    const views = buildProjectionViews(await loadWriteThroughOrder(), { dialect: "postgres", columnNamingStrategy: "snake_case" });
+    const sql = views.find((x) => x.name === "v_order_with_customer")!.sql;
+    // customer_name comes from the join alias, never `o.customer_name`.
+    expect(sql).not.toMatch(/o\.customer_name/);
+  });
+});