@@ -0,0 +1,59 @@
+# `api-contract-conformance/write-through/` — #214 write-through read-your-writes
+
+Cross-port REST contract for a **write-through entity** (FR-024 §7 / #214): an
+`object.entity` that declares BOTH a writable primary table
+(`source.rdb @role:primary @table:orders`) AND a read-only replica view
+(`source.rdb @role:replica @kind:view @table:v_order_with_customer`), plus a
+derived `customerName` field carrying `origin.passthrough @from Customer.name @via
+Order.customer`.
+
+The contract the deployed HTTP artifact must honour:
+
+- **Writes target the table.** `POST /api/orders` inserts into `orders`; the
+  derived `customerName` is not a table column (it is excluded from the write
+  schema per #213).
+- **Reads route through the replica view.** `POST` (create's re-read), `GET
+  /api/orders/:id`, and `GET /api/orders` all SELECT from
+  `v_order_with_customer`, so the response carries the derived `customerName`
+  joined from `Customer` — **read-your-writes returns the derived field**.
+
+## The bug this gates
+
+The #214 read-half shipped in the query layer + the replica view, but the
+generated REST **routes** were initially left mounting vanilla table CRUD, so a
+write-through entity's `GET`/`POST` responses OMITTED `customerName`. Fixed by
+routing the generated routes' reads through the view (`readView` on
+`mountCrudRoutes` in TS; the EF `.ToView` read-model / Exposed `OrderView` re-read
+in C# / Kotlin). This corpus is the deployed-artifact regression gate.
+
+## Files
+
+```
+write-through/
+├── README.md              # this file
+├── meta.json              # Customer + write-through Order (table + replica view + derived customerName)
+├── seed.json              # 2 customers + 1 pre-seeded order (id 100 → customer 2 "Globex")
+└── scenarios/
+    ├── create-returns-derived-field.yaml   # POST → 201 body carries the derived customerName
+    └── get-reads-through-view.yaml          # GET seeded order → body carries the derived customerName
+```
+
+`seed.json` seeds the base tables directly (the derived `customerName` is never
+seeded — it is produced by the view join on read).
+
+## Lane coverage — TS / C# / Kotlin (accepted design)
+
+This subcorpus runs on the three ports whose **generated artifact itself** re-reads
+through the replica view over HTTP: **TS** (`mountCrudRoutes` `readView`), **C#**
+(EF read-model view DbSet + `.ToView`), **Kotlin** (inline Exposed `OrderView`
+re-read). The generated-lane harness for each hand-creates the SQL view
+(`v_order_with_customer`) so the `.existing()` view binding resolves.
+
+**Java and Python are intentionally excluded.** Their generated controller/router
+delegates read-your-writes to the runtime (Python `ObjectManager`) or to the
+consumer persistence seam (Java), which the api-contract in-memory-repo lane
+bypasses — so a write-through gate there would test a hand-written seam repo faking
+the Customer join, not the port's generated re-read. The runtime read-routing for
+those ports is gated elsewhere (Python `test_object_manager_write_through`); a
+cross-port persistence-conformance roundtrip is a separate deferred follow-up (see
+`spec/roadmap.md` #214).
@@ -0,0 +1,30 @@
+{
+  "metadata.root": {
+    "package": "acme::orders",
+    "children": [
+      { "object.entity": {
+        "name": "Customer",
+        "children": [
+          { "source.rdb":       { "@table": "customers" } },
+          { "field.long":       { "name": "id" } },
+          { "field.string":     { "name": "name", "@required": true, "@maxLength": 80 } },
+          { "identity.primary": { "name": "id", "@fields": "id", "@generation": "increment" } }
+        ]
+      }},
+      { "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": "id", "@fields": "id", "@generation": "increment" } },
+          { "identity.reference": { "name": "fkCustomer", "@fields": "customerId", "@references": "Customer" } }
+        ]
+      }}
+    ]
+  }
+}
@@ -0,0 +1,21 @@
+name: create-returns-derived-field
+description: >
+  #214 read-your-writes over HTTP. POST /api/orders writes ONLY the base table
+  (orders — the derived customerName is not a table column, per #213), then the
+  generated route RE-READS the new row through the replica view
+  v_order_with_customer by PK, so the 201 response body carries the derived
+  customerName joined from Customer. This is the deployed-artifact proof that a
+  write-through entity's create returns the derived field (the bug: the routes
+  used to read the table and omit it).
+requests:
+  - id: r1
+    method: POST
+    path: /api/orders
+    body:
+      customerId: 1
+    expect:
+      status: 201
+      body:
+        hasId: true
+        row:
+          customerName: "Acme"
@@ -0,0 +1,16 @@
+name: get-reads-through-view
+description: >
+  #214 read path over HTTP. GET /api/orders/:id reads the write-through entity
+  THROUGH the replica view v_order_with_customer, so the response carries the
+  derived customerName joined from Customer — for a seeded order (id 100 →
+  customer 2 "Globex") that was written table-only. Proves the generated get
+  route routes reads through the view, not the base table.
+requests:
+  - id: r1
+    method: GET
+    path: /api/orders/100
+    expect:
+      status: 200
+      body:
+        row:
+          customerName: "Globex"
@@ -0,0 +1,9 @@
+{
+  "customers": [
+    { "id": 1, "name": "Acme" },
+    { "id": 2, "name": "Globex" }
+  ],
+  "orders": [
+    { "id": 100, "customerId": 2 }
+  ]
+}
@@ -0,0 +1,125 @@
+// api-contract-write-through-generated-server.ts — boots the GENERATED Order
+// routes (the deployed artifact) over HTTP and drives them against the #214
+// write-through corpus.
+//
+// Mirrors api-contract-m2m-generated-server.ts, but the model is a WRITE-THROUGH
+// entity: Order has a writable `orders` table AND a read-only replica view
+// `v_order_with_customer` carrying the derived `customerName` (origin.passthrough
+// from Customer.name). It:
+//   1. runs the real codegen (runGen) over the write-through meta into a temp dir,
+//      emitting Order's Drizzle table + the `.existing()` replica VIEW binding +
+//      Order.routes.ts — which (post-fix) mounts mountCrudRoutes with `readView`;
+//   2. provisions the `customers` + `orders` tables AND the `v_order_with_customer`
+//      SQL view the generated `.existing()` binding reads through;
+//   3. imports the EMITTED Order.routes.ts unmodified and mounts it.
+//
+// This proves the GENERATED write-through routes — the deployed artifact, not a
+// re-implementation — return the derived field on read-your-writes over HTTP.
+
+import Fastify, { type FastifyInstance } from "fastify";
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { runGen, defineConfig } from "@metaobjectsdev/codegen-ts";
+import { entityFile, routesFile } from "@metaobjectsdev/codegen-ts/generators";
+import pg from "pg";
+import { executeSql } from "./postgres-sql.ts";
+import { loadMetadataFile } from "./load-metadata.ts";
+
+export interface WriteThroughSeed {
+  customers: Array<{ id: number; name: string }>;
+  orders: Array<{ id: number; customerId: number }>;
+}
+
+export interface GeneratedWriteThroughServerHandle {
+  baseUrl: string;
+  applySeed(seed: WriteThroughSeed): Promise<void>;
+  close(): Promise<void>;
+}
+
+export async function startGeneratedWriteThroughServer(
+  connectionUri: string,
+  metaPath: string,
+): Promise<GeneratedWriteThroughServerHandle> {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const genTmpRoot = join(here, "..", ".gen-tmp");
+  mkdirSync(genTmpRoot, { recursive: true });
+  const tmp = mkdtempSync(join(genTmpRoot, "api-contract-write-through-"));
+
+  // 1. Emit the real artifacts for the write-through model.
+  const root = await loadMetadataFile(metaPath);
+  const lr = await runGen({
+    config: defineConfig({
+      outDir: tmp,
+      extStyle: "none",
+      dbImport: "./db",
+      dialect: "postgres",
+      apiPrefix: "/api",
+      generators: [entityFile(), routesFile()],
+    }),
+    metadata: root,
+  });
+  if (lr.warnings.length > 0) {
+    throw new Error(`codegen produced warnings: ${lr.warnings.join("; ")}`);
+  }
+
+  // 2. db module the emitted routes import (`import { db } from "./db"`).
+  const bigintTypesImport = pathToFileURL(join(here, "pg-bigint-number-types.ts")).href;
+  const dbModule = `
+import { drizzle } from "drizzle-orm/node-postgres";
+import pg from "pg";
+import { bigintAsNumberTypes } from ${JSON.stringify(bigintTypesImport)};
+export const pool = new pg.Pool({ connectionString: ${JSON.stringify(connectionUri)}, types: bigintAsNumberTypes });
+export const db = drizzle(pool);
+`;
+  writeFileSync(join(tmp, "db.ts"), dbModule, "utf8");
+
+  // 3. Provision the base tables (snake_case, matching the EMITTED Drizzle table)
+  //    AND the replica VIEW the generated `.existing()` binding reads through. The
+  //    view columns (id / customer_id / customer_name) match orderView's physical
+  //    column names, so a read routed through it carries the derived customerName.
+  await executeSql(connectionUri, `
+    CREATE TABLE IF NOT EXISTS "customers" ("id" bigserial PRIMARY KEY, "name" varchar(80) NOT NULL);
+    CREATE TABLE IF NOT EXISTS "orders" ("id" bigserial PRIMARY KEY, "customer_id" bigint NOT NULL);
+    CREATE OR REPLACE VIEW "v_order_with_customer" AS
+      SELECT o."id" AS "id", o."customer_id" AS "customer_id", c."name" AS "customer_name"
+      FROM "orders" o JOIN "customers" c ON o."customer_id" = c."id";
+  `);
+
+  // 4. Import the EMITTED Order route file unmodified and mount it.
+  const orderRoutes = (await import(pathToFileURL(join(tmp, "Order.routes.ts")).href)) as {
+    orderRoutes: (f: FastifyInstance) => Promise<void>;
+  };
+  const dbMod = (await import(pathToFileURL(join(tmp, "db.ts")).href)) as { pool: pg.Pool };
+
+  const fastify = Fastify();
+  await fastify.register(orderRoutes.orderRoutes);
+  await fastify.ready();
+  const baseUrl = await fastify.listen({ host: "127.0.0.1", port: 0 });
+
+  return {
+    baseUrl,
+    applySeed: async (seed: WriteThroughSeed) => {
+      await seedWriteThrough(connectionUri, seed);
+    },
+    close: async () => {
+      await fastify.close();
+      await dbMod.pool.end();
+      rmSync(tmp, { recursive: true, force: true });
+    },
+  };
+}
+
+/** Truncate + insert the write-through corpus seed (base tables only — the
+ *  derived customerName is produced by the view join on read). */
+export async function seedWriteThrough(connectionUri: string, seed: WriteThroughSeed): Promise<void> {
+  await executeSql(connectionUri, `TRUNCATE TABLE "customers","orders" RESTART IDENTITY CASCADE;`);
+  for (const c of seed.customers)
+    await executeSql(connectionUri, `INSERT INTO "customers" ("id","name") VALUES (${c.id}, ${str(c.name)})`);
+  for (const o of seed.orders)
+    await executeSql(connectionUri, `INSERT INTO "orders" ("id","customer_id") VALUES (${o.id}, ${o.customerId})`);
+}
+
+function str(v: string): string {
+  return `'${v.replace(/'/g, "''")}'`;
+}
@@ -34,5 +34,9 @@ export const API_CONTRACT_TPH_SCENARIOS_DIR = resolve(API_CONTRACT_TPH_DIR, "sce
 export const API_CONTRACT_JSONB_DIR = resolve(API_CONTRACT_DIR, "jsonb");
 export const API_CONTRACT_JSONB_SCENARIOS_DIR = resolve(API_CONTRACT_JSONB_DIR, "scenarios");
 
+// #214 write-through read-your-writes subcorpus.
+export const API_CONTRACT_WRITE_THROUGH_DIR = resolve(API_CONTRACT_DIR, "write-through");
+export const API_CONTRACT_WRITE_THROUGH_SCENARIOS_DIR = resolve(API_CONTRACT_WRITE_THROUGH_DIR, "scenarios");
+
 // fixtures/validation-conformance/ — cross-port generated input-validation corpus.
 export const VALIDATION_DIR = resolve(repoRoot, "fixtures", "validation-conformance");
@@ -0,0 +1,69 @@
+// #214 write-through read-your-writes api-contract conformance (GENERATED lane).
+//
+// Drives the fixtures/api-contract-conformance/write-through/ scenarios over HTTP
+// against the GENERATED Order routes (the deployed artifact) — the emitted
+// Order.routes.ts booted unmodified against a real Postgres testcontainer with the
+// replica view v_order_with_customer present. This proves the deployed REST surface
+// returns the derived customerName on read-your-writes (POST create's re-read + GET
+// through the view) — the regression gate for the write-through-routes fix.
+//
+// Generated lane only: a hand-rolled reference server would re-implement the view
+// join by hand and prove nothing about the emitted artifact (the thing that was
+// broken). One Postgres testcontainer per scenario (full isolation).
+
+import { describe, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+  API_CONTRACT_WRITE_THROUGH_DIR,
+  API_CONTRACT_WRITE_THROUGH_SCENARIOS_DIR,
+} from "../src/paths.ts";
+import { loadScenarios, assertResponse, type ApiScenario } from "../src/api-contract-scenario.ts";
+import { startPostgres } from "../src/postgres-container.ts";
+import {
+  startGeneratedWriteThroughServer,
+  type GeneratedWriteThroughServerHandle,
+  type WriteThroughSeed,
+} from "../src/api-contract-write-through-generated-server.ts";
+
+const SEED = JSON.parse(
+  readFileSync(join(API_CONTRACT_WRITE_THROUGH_DIR, "seed.json"), "utf8"),
+) as WriteThroughSeed;
+const META_PATH = join(API_CONTRACT_WRITE_THROUGH_DIR, "meta.json");
+
+describe("api contract write-through (#214) — GENERATED routes lane", () => {
+  for (const scenario of loadScenarios(API_CONTRACT_WRITE_THROUGH_SCENARIOS_DIR)) {
+    test(scenario.name, async () => {
+      const pg = await startPostgres();
+      let server: GeneratedWriteThroughServerHandle | null = null;
+      try {
+        server = await startGeneratedWriteThroughServer(pg.connectionUri, META_PATH);
+        await server.applySeed(SEED);
+        await runScenario(scenario, server);
+      } finally {
+        if (server) await server.close();
+        await pg.stop();
+      }
+    }, { timeout: 60_000 });
+  }
+});
+
+async function runScenario(
+  scenario: ApiScenario,
+  server: GeneratedWriteThroughServerHandle,
+): Promise<void> {
+  for (const req of scenario.requests) {
+    const init: RequestInit = { method: req.method };
+    if (req.body !== undefined) {
+      init.body = JSON.stringify(req.body);
+      init.headers = { "content-type": "application/json" };
+    }
+    const res = await fetch(server.baseUrl + req.path, init);
+    const bodyText = await res.text();
+    let body: unknown = null;
+    if (bodyText.length > 0) {
+      try { body = JSON.parse(bodyText); } catch { body = bodyText; }
+    }
+    assertResponse(scenario.name, req, res.status, body);
+  }
+}