fix(#213): exclude derived fields from the entity write table + write codecs

#213 hole 1 (the silent-corruption half): an FR-024 §7 entity read-view's derived
(origin-bearing) field leaked onto the entity's WRITE table. `buildExpectedSchema`
built a column for every field with no origin check, so a join-derived passthrough
became a spurious column on the write table — and collided with a hand-written
`SELECT o.*, extra` view's alias (PG duplicate-output-column). The same unfiltered
`fields()` iteration also declared the column in the generated Drizzle table def and
accepted it in the Insert/Update Zod schemas.

A derived field is read-only and lives only on the read (view) side (ADR-0028), so
it must be excluded from every write-side artifact, in lockstep, or generated
runtime addresses a column migrate no longer creates.

- metadata: new `MetaField.isDerived()` (own origin child — origin never inherits,
  ADR-0029), the shared SSOT for "this field is derived".
- migrate-ts `expected-schema.ts`: skip derived fields in the write-table column
  loop AND the TPH subtype fold.
- codegen-ts `drizzle-schema.ts`: skip derived fields in the table column loop + the
  TPH fold.
- codegen-ts `zod-validators.ts`: derived ⇒ read-only, excluded from the Insert /
  Update / preserving schemas (same treatment as @readonly, all four field loops).

This is #213's schema/write half (TS-owned, ADR-0015). The READ half — emitting the
replica view (hole 2, `isWriteThrough` → buildProjectionViews) and routing reads to
it + the entity's read TYPE — follows; the cross-port codegen exclusions (other
ports' ORM/DTO generators) are a separate coordinated issue.

Verified: metadata 2179 pass (incl. isDerived), migrate-ts 341 (new write-table
exclusion test), codegen-ts 959 (new Drizzle + Zod exclusion test); typecheck exit 0.
No existing golden changed (no fixture had a write-through entity with derived fields).

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/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(

server/typescript/packages/codegen-ts/src/templates/zod-validators.ts

@@ -175,7 +175,9 @@ export function renderInsertSchemaOnly(obj: MetaObject, ctx?: RenderContext): Co
     // FR-013: @readOnly fields are populated by DB / replication / external
     // owner; the application has no path to write them. Exclude from the
     // create-shape schema entirely.
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+    // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
+    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
 
     // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
     if (tphPin !== undefined && child.name === tphPin.fieldName) {
@@ -239,7 +241,9 @@ export function insertSchemaFields(obj: MetaObject): SchemaFieldShape[] {
   const out: SchemaFieldShape[] = [];
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+    // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
+    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
     if (tphPin !== undefined && child.name === tphPin.fieldName) {
       out.push({ name: child.name, optional: false, pinnedLiteral: tphPin.value });
       continue;
@@ -269,7 +273,9 @@ export function updateSchemaFields(obj: MetaObject): SchemaFieldShape[] {
   const out: SchemaFieldShape[] = [];
   for (const child of obj.fields()) {
     if (autoGenPkFields.has(child.name)) continue;
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+    // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
+    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
     // TPH subtype discriminator: omitted from the update schema entirely.
     if (tphPin !== undefined && child.name === tphPin.fieldName) continue;
     const autoSet = child.attr(FIELD_ATTR_AUTO_SET);
@@ -306,7 +312,9 @@ export function renderZodValidators(obj: MetaObject, ctx?: RenderContext): Code
     // The DB / trigger / replication owns the write path; the app must not
     // pass these values in POST/PATCH bodies (routesFile enforces the same
     // contract at the boundary with a 400 response).
-    if (child.attr(FIELD_ATTR_READ_ONLY) === true) continue;
+    // #213 — a derived (origin-bearing) field is read-only (FR-024 §7 / ADR-0028):
+    // excluded from the Insert/Update/preserving schemas, exactly like @readOnly.
+    if (child.attr(FIELD_ATTR_READ_ONLY) === true || child.isDerived()) continue;
 
     // FR-017 Tier 1: TPH subtype pins its discriminator field to z.literal(...).
     // The discriminator is implicit on subtype rows (controlled by URL / insert

server/typescript/packages/codegen-ts/test/templates/issue-213-write-side-derived-exclusion.test.ts

@@ -0,0 +1,64 @@
+// #213 — the write-side codegen must exclude a derived (origin-bearing) field, in
+// lockstep with migrate-ts dropping it from the write-table DDL: otherwise the
+// generated Drizzle table declares a column, and the Insert/Update Zod schemas
+// accept a field, that no longer exists on the physical write table.
+
+import { describe, test, expect } from "bun:test";
+import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
+import { renderDrizzleSchema } from "../../src/templates/drizzle-schema.js";
+import { renderZodValidators } from "../../src/templates/zod-validators.js";
+import { makeRenderContext } from "../../src/render-context.js";
+import { buildPkMap } from "../../src/pk-resolver.js";
+import { buildRelationMap } from "../../src/relation-resolver.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" } },
+          { "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([]);
+  const order = root.objects().find((o) => o.name === "Order")!;
+  const ctx = makeRenderContext({
+    dialect: "postgres", loadedRoot: root, outDir: "/x", dbImport: "~/db",
+    pkMap: buildPkMap(root), relationMap: buildRelationMap(root),
+  });
+  return { order, ctx };
+}
+
+describe("#213 — write-side codegen excludes derived fields", () => {
+  test("Drizzle table def omits the derived customerName column", async () => {
+    const { order, ctx } = await loadWriteThroughOrder();
+    const out = renderDrizzleSchema(order, ctx).toString();
+    expect(out).toContain("customerId");        // stored FK stays
+    expect(out).not.toContain("customerName");  // derived join column excluded
+  });
+
+  test("Insert + Update Zod schemas omit the derived customerName field", async () => {
+    const { order, ctx } = await loadWriteThroughOrder();
+    const out = renderZodValidators(order, ctx).toString();
+    expect(out).toContain("OrderInsertSchema");
+    expect(out).toContain("customerId");
+    expect(out).not.toContain("customerName");
+  });
+});

server/typescript/packages/metadata/src/core/field/meta-field.ts

@@ -16,7 +16,7 @@ import {
   DATA_TYPE_OBJECT,
 } from "../../data-type.js";
 import { convertToDataType } from "../../data-converter.js";
-import { TYPE_VALIDATOR, TYPE_VIEW, SUBTYPE_BASE } from "../../shared/base-types.js";
+import { TYPE_VALIDATOR, TYPE_VIEW, TYPE_ORIGIN, SUBTYPE_BASE } from "../../shared/base-types.js";
 import {
   FIELD_SUBTYPE_STRING,
   FIELD_SUBTYPE_INT,
@@ -196,6 +196,18 @@ export class MetaField extends MetaData implements DataTypeAware {
     );
   }
 
+  /**
+   * True when this field carries an `origin.*` child (passthrough / aggregate /
+   * computed / first): its value is DERIVED from other data, not stored in the
+   * object's own writable table. A derived field is read-only wherever it lives
+   * (ADR-0028) — excluded from the write-table DDL, the ORM table def, and the
+   * Insert/Update codecs; it exists only on the read (view) side. `origin.*` never
+   * inherits (ADR-0029), so the check is own-only (category 4). */
+  isDerived(): boolean {
+    // ADR-0039 own (category 4): origin.* never inherits (ADR-0029) — own by policy.
+    return this.ownChildren().some((c) => c.type === TYPE_ORIGIN);
+  }
+
   /** The typed supertype field if `extends:` resolved, else undefined. */
   resolveSuper(): MetaField | undefined {
     return this.superData as MetaField | undefined;

server/typescript/packages/metadata/test/field-is-derived.test.ts

@@ -0,0 +1,46 @@
+// #213 — MetaField.isDerived(): true when a field carries an origin.* child (its
+// value is derived, not stored in the object's own writable table). Drives the
+// write-side exclusions (migrate table DDL, ORM table def, Insert/Update codecs).
+
+import { describe, test, expect } from "bun:test";
+import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
+
+async function loadOrder() {
+  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" } },
+          { "field.long": { name: "id" } },
+          { "field.long": { name: "customerId", "@required": true } },
+          // Derived field — a joined passthrough (has an origin child).
+          { "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.objects().find((o) => o.name === "Order")!;
+}
+
+describe("MetaField.isDerived", () => {
+  test("true for an origin-bearing field, false for stored fields", async () => {
+    const order = await loadOrder();
+    expect(order.findField("customerName")!.isDerived()).toBe(true);
+    expect(order.findField("id")!.isDerived()).toBe(false);
+    expect(order.findField("customerId")!.isDerived()).toBe(false);
+  });
+});

server/typescript/packages/migrate-ts/src/expected-schema.ts

@@ -1,4 +1,4 @@
-import type { ColumnNamingStrategy, MetaData, MetaObject, MetaRoot, MetaValidator } from "@metaobjectsdev/metadata";
+import type { ColumnNamingStrategy, MetaData, MetaField, MetaObject, MetaRoot, MetaValidator } from "@metaobjectsdev/metadata";
 import {
   VALIDATOR_SUBTYPE_NUMERIC, VALIDATOR_SUBTYPE_LENGTH, VALIDATOR_SUBTYPE_REGEX,
   VALIDATOR_SUBTYPE_COMPARISON, VALIDATOR_SUBTYPE_REQUIRED_WHEN,
@@ -375,6 +375,12 @@ function buildTable(
 
   const columns: ColumnDescriptor[] = [];
   for (const field of entity.fields()) {
+    // #213 — a derived (origin-bearing) field is read-only and lives only on the
+    // read (view) side (FR-024 §7 / ADR-0028); it is NOT a physical column on the
+    // entity's write table. Excluding it here stops the leak that put a joined
+    // passthrough onto the write table (and collided with a hand-written
+    // `SELECT o.*, extra` view's alias).
+    if (field.isDerived()) continue;
     const isPk = pkJsNames.includes(field.name);
     if (
       field.subType === FIELD_SUBTYPE_OBJECT &&
@@ -401,6 +407,8 @@ function buildTable(
       // fields (inherited base fields are already emitted on the base table).
       for (const field of sub.ownChildren()) {
         if (field.type !== TYPE_FIELD) continue;
+        // #213 — a TPH subtype's derived field is read-only too; never a column.
+        if ((field as MetaField).isDerived()) continue;
         const col = buildColumn(field, false, undefined, strategy);
         if (existing.has(col.name)) continue;
         col.nullable = true; // subtype-only columns are always nullable in TPH

server/typescript/packages/migrate-ts/test/issue-213-derived-field-exclusion.test.ts

@@ -0,0 +1,53 @@
+// #213 — FR-024 §7 entity read-view: a derived (origin-bearing) field must NOT
+// become a column on the entity's WRITE table. Before the fix, buildExpectedSchema
+// built a column for every field, so a joined-passthrough field leaked onto the
+// write table (and collided with a hand-written `SELECT o.*, extra` view's alias).
+
+import { describe, test, expect } from "bun:test";
+import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
+import { buildExpectedSchema } from "../src/expected-schema.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" } },
+        ] } },
+        // Entity read-view (FR-024 §7): writable table + non-primary read view +
+        // a derived join column.
+        { "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 — derived fields excluded from the write table DDL", () => {
+  test("the orders table carries id + customer_id but NOT the derived customer_name", async () => {
+    const snap = buildExpectedSchema(await loadWriteThroughOrder(), { dialect: "postgres" });
+    const orders = snap.tables.find((t) => t.name === "orders")!;
+    expect(orders).toBeDefined();
+    const cols = orders.columns.map((c) => c.name);
+    expect(cols).toContain("id");
+    expect(cols).toContain("customer_id");
+    // The derived join column must NOT be a physical column on the write table.
+    expect(cols).not.toContain("customer_name");
+  });
+});