feat(#214): entity read-view codegen READ half — Python port

Fan the FR-024 §7 read-half (TS reference b4eee45) out to the Python port. It
splits into a codegen half and a runtime half (schema stays TS-owned, ADR-0015).

Shared metadata predicates (SSOT, mirror Java/Kotlin/C#):
- MetaField.is_derived() — the field carries an origin.* child (own-only; matched
  by type string so the core field module needs no persistence-layer import).
- MetaObject.is_write_through() — owns BOTH a writable-kind and a read-only-kind
  source.rdb (role-agnostic own-source classification — a replica view carries
  @ROLE:replica, so no primary-role accessor).

Codegen:
- entity_model.py: <Name>Create and <Name>Patch EXCLUDE derived fields (view-
  computed, not client input); the read model still carries them.
- router_generator.py + filter_allowlist_generator.py: a write-through entity is
  writable, so both its CRUD router AND the filter allowlist its router imports are
  emitted — via an order-independent gate (else a view-source-first write-through
  router imports a never-generated allowlist module → FastAPI startup crash).

Runtime (ObjectManager — the analogue of the TS queries-file):
- reads (find_many / find_by_id / count) route to the replica VIEW (carrying the
  derived columns) for a write-through entity, else the entity's own source.
- writes (create / update) target the table with derived fields excluded from BOTH
  the INSERT/UPDATE column set (a read-modify-write round-trip POSTing back the read
  model must not try to write a view-computed column) AND the RETURNING set (the
  table has no such column), then RE-READ the row through the view by PK so the
  returned dict carries the derived fields (read-your-writes). delete is unchanged.
- vanilla entities and projections are byte-identical (they have no derived fields /
  are not write-through).

Gated by test_write_through.py (read model carries derived, Create/Patch exclude
it, router + filter-allowlist emitted regardless of source order) and
test_object_manager_write_through.py (a fake driver asserts reads→view,
writes→table with derived excluded from INSERT/UPDATE + RETURNING, and the by-PK
view re-read). A high-effort review caught the filter-allowlist gate coupling and
the write-column-set derived leak (both fixed above).

Single-PK is the documented ObjectManager scope; a row-scoped replica view that
does not surface a just-written row falls back to the table row (its derived fields
absent) — an accepted edge for the 1:1-replica common case.

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

Author: dmealing

server/python/src/metaobjects/codegen/generators/entity_model.py

@@ -496,6 +496,8 @@ def _emit_create_lines(
                 continue  # FR-036 #2 — a server-generated PK is never in the create body
             if f.attrs().get(fc.FIELD_ATTR_READ_ONLY) is True:
                 continue  # FR-013 — a read-only column is DB/owner-written, not create input
+            if f.is_derived():
+                continue  # FR-024 §7 (#214) — a derived (origin.*) field is view-computed, not create input
             line, used = _create_field_line(f, imports, cfg)
             uses_field = uses_field or used
             lines.append(line)
@@ -529,6 +531,8 @@ def _emit_patch_lines(
         for f in entity.fields():
             if f.name in pk_fields:
                 continue  # FR-036 #4 — the PK is route-authoritative, never patched
+            if f.is_derived():
+                continue  # FR-024 §7 (#214) — a derived (origin.*) field is view-computed, never patched
             line, used = _patch_field_line(f, imports, cfg)
             uses_field = uses_field or used
             lines.append(line)

server/python/src/metaobjects/codegen/generators/filter_allowlist_generator.py

@@ -250,7 +250,12 @@ def render_filter_allowlist(
         src = _primary_source_rdb(entity)
         if src is None:
             return None
-        if src.effective_kind() != SOURCE_KIND_TABLE:
+        # FR-024 §7 (#214): a write-through entity read-view is writable and its generated
+        # router imports this allowlist — so it MUST be emitted for write-through regardless of
+        # source declaration order (matching the router gate; else a view-source-first
+        # write-through router imports a never-generated module and FastAPI startup crashes). A
+        # projection (read-only source only) is not write-through, so it still skips.
+        if not entity.is_write_through() and src.effective_kind() != SOURCE_KIND_TABLE:
             return None
 
         short_name = entity.name

server/python/src/metaobjects/codegen/generators/router_generator.py

@@ -645,7 +645,12 @@ def render_router(
         src = _primary_source_rdb(entity)
         if src is None:
             return None
-        if src.effective_kind() != SOURCE_KIND_TABLE:
+        # FR-024 §7 (#214): a write-through entity read-view is writable (owns a table
+        # source) and MUST emit its CRUD router regardless of source declaration order —
+        # the first-source gate below would wrongly skip a view-source-first write-through
+        # entity. Reads route to the replica view in the ObjectManager (not here). A
+        # projection (read-only source only) is not write-through, so it still skips.
+        if not entity.is_write_through() and src.effective_kind() != SOURCE_KIND_TABLE:
             return None
 
         # FR-017 TPH: a discriminator base emits a polymorphic collection at the base

server/python/src/metaobjects/meta/core/field/meta_field.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 from ....datatype import DataType
+from ....shared.base_types import TYPE_ORIGIN
 from ...meta_data import MetaData
 from . import field_constants as fc
 
@@ -53,6 +54,20 @@ def object_ref(self) -> str | None:
         v = self.get_meta_attr(fc.FIELD_ATTR_OBJECT_REF)
         return str(v) if v is not None else None
 
+    def is_derived(self) -> bool:
+        """Whether this field is DERIVED — it carries an ``origin.*`` child
+        (``passthrough`` / ``aggregate`` / …), so its value is computed from a read
+        source (a view join or aggregate), not stored on the writable table.
+
+        Derived ⇒ read-only wherever the field lives (ADR-0028): excluded from the
+        write table + create/update inputs, carried only on the read shape (FR-024 §7,
+        #214). Mirrors the TS/Java ``MetaField.isDerived()``.
+
+        OWN-only (ADR-0029/0039): an ``origin.*`` never inherits via ``extends``, so
+        this reads own children (matched by ``type`` so no ``MetaOrigin`` import is
+        needed — the core field module must not depend on the persistence layer)."""
+        return any(c.type == TYPE_ORIGIN for c in self.own_children())
+
     def get_value(self, obj: object, name: str | None = None) -> object:
         """Read this field's value from a backing object.
 

server/python/src/metaobjects/meta/core/object/meta_object.py

@@ -1,6 +1,7 @@
 """MetaObject — typed accessors over children + runtime instantiation."""
 from __future__ import annotations
 
+from ....shared.base_types import TYPE_SOURCE
 from ...meta_data import MetaData
 from ..field.meta_field import MetaField
 from .object_class_registry import (
@@ -32,6 +33,27 @@ def get_meta_field(self, name: str) -> MetaField | None:
         """Alias for find_field — Java/TS parity (``getMetaField``)."""
         return self.find_field(name)
 
+    def is_write_through(self) -> bool:
+        """Whether this object is a WRITE-THROUGH entity read-view (FR-024 §7, #214) —
+        it owns BOTH a writable-kind ``source.rdb`` (a ``@kind: table``) AND a
+        read-only-kind ``source.rdb`` (a ``@kind: view`` / …). Writes route to the
+        table; reads route to the (derived-field-carrying) view.
+
+        OWN-only + role-agnostic (mirrors the TS/Java ``isWriteThrough``): classified by
+        the source ``@kind`` of this object's OWN ``source.*`` children — a replica view
+        carries ``@role: replica``, so this must NOT go through a primary-role accessor.
+        Duck-typed on ``type == TYPE_SOURCE`` + ``is_read_only()`` so the core object
+        module needs no persistence-layer import."""
+        has_writable = has_read_only = False
+        for c in self.own_children():
+            if c.type != TYPE_SOURCE:
+                continue
+            if c.is_read_only():
+                has_read_only = True
+            else:
+                has_writable = True
+        return has_writable and has_read_only
+
     def new_instance(self, registry: ObjectClassRegistry | None = None) -> object:
         """Instantiate a backing object for this MetaObject (Java/TS parity:
         ``newInstance``). Resolution order:

server/python/src/metaobjects/runtime/object_manager.py

@@ -273,14 +273,22 @@ def _insert_row(
                 raise ValueError(
                     f"create('{entity_name}'): no field '{field_name}' in metadata"
                 )
+            # #214: a DERIVED (origin.*) field has no column on the write table — it is
+            # view-computed. A read-modify-write round-trip (a client POSTs back the read
+            # model, which carries derived fields) must not try to INSERT it; drop it here.
+            if f.is_derived():
+                continue
             insert_cols.append(_column_of(f))
             params.append(_coerce_write_value(f, raw))
 
-        # Always RETURNING the full physical column set so the inserted row —
-        # including any server-generated PK / default — comes back, then map
-        # columns → metadata field names for cross-port row-shape parity.
-        all_cols = [_column_of(f) for f in entity.fields()]
-        col_to_field = {_column_of(f): f.name for f in entity.fields()}
+        # RETURNING the physical column set so the inserted row — including any
+        # server-generated PK / default — comes back, then map columns → metadata field
+        # names for cross-port row-shape parity. #214: a DERIVED (origin.*) field has no
+        # column on the write table (it is computed by the replica view), so it is
+        # excluded from RETURNING; the write-through re-read below fetches it via the view.
+        returning_fields = [f for f in entity.fields() if not f.is_derived()]
+        all_cols = [_column_of(f) for f in returning_fields]
+        col_to_field = {_column_of(f): f.name for f in returning_fields}
 
         if insert_cols:
             col_list = ", ".join(_q(c) for c in insert_cols)
@@ -302,7 +310,15 @@ def _insert_row(
             col_to_field.get(c, c): oid for c, oid in result.column_oids.items()
         }
         row = result.rows[0]
-        return {col_to_field.get(k, k): v for k, v in row.items()}
+        mapped = {col_to_field.get(k, k): v for k, v in row.items()}
+        # #214: a write-through entity's INSERT RETURNING covers only the table (non-derived)
+        # columns; re-read the persisted row through the replica VIEW by PK so the returned row
+        # carries the derived origin.* fields (read-your-writes). find_by_id routes to the view.
+        if entity.is_write_through():
+            reread = self.find_by_id(entity_name, mapped[self._primary_pk_field(entity)])
+            if reread is not None:
+                return reread
+        return mapped
 
     def update(
         self,
@@ -366,15 +382,24 @@ def update(
                 raise ValueError(
                     f"update('{entity_name}'): no field '{field_name}' in metadata"
                 )
+            # #214: a DERIVED (origin.*) field has no column on the write table (view-computed).
+            # A read-modify-write round-trip PATCHing back the whole read model must not try to
+            # UPDATE it; drop it from the SET list.
+            if f.is_derived():
+                continue
             set_cols.append(_column_of(f))
             params.append(_coerce_write_value(f, raw))
         if not set_cols:
             # No columns to set → just read the (scoped) row back by PK (no-op update).
             row = self.find_by_id(entity_name, id_value)
             return self._on_missing_update(entity_name, pk_field, id_value, if_missing) if row is None else row
 
-        all_cols = [_column_of(f) for f in entity.fields()]
-        col_to_field = {_column_of(f): f.name for f in entity.fields()}
+        # #214: exclude DERIVED (origin.*) fields from RETURNING — they have no column on
+        # the write table (computed by the replica view); the write-through re-read below
+        # fetches them via the view.
+        returning_fields = [f for f in entity.fields() if not f.is_derived()]
+        all_cols = [_column_of(f) for f in returning_fields]
+        col_to_field = {_column_of(f): f.name for f in returning_fields}
         assignments = ", ".join(f"{_q(c)} = %s" for c in set_cols)
         params.append(_coerce_write_value(entity.find_field(pk_field), id_value))
         where = f"{_q(pk_col)} = %s"
@@ -397,7 +422,14 @@ def update(
             col_to_field.get(c, c): oid for c, oid in result.column_oids.items()
         }
         row = result.rows[0]
-        return {col_to_field.get(k, k): v for k, v in row.items()}
+        mapped = {col_to_field.get(k, k): v for k, v in row.items()}
+        # #214: re-read the updated row through the replica VIEW by PK so the returned row
+        # carries the derived origin.* fields (write targeted the table, which lacks them).
+        if entity.is_write_through():
+            reread = self.find_by_id(entity_name, id_value)
+            if reread is not None:
+                return reread
+        return mapped
 
     @staticmethod
     def _on_missing_update(
@@ -442,7 +474,10 @@ def find_many(
         offset: int | None = None,
     ) -> list[dict[str, Any]]:
         entity = self._require_entity(entity_name)
-        table = self._table_name(entity)
+        # #214: reads route to the replica VIEW for a write-through entity (carrying the
+        # derived origin.* columns), else the entity's own primary source. All effective
+        # fields (incl. derived) are selected — the view exposes them.
+        table = self._read_source_name(entity)
         cols = [_column_of(f) for f in entity.fields()]
         sql = f'SELECT {", ".join(_q(c) for c in cols)} FROM {_q(table)}'
         params: list[Any] = []
@@ -480,7 +515,9 @@ def find_many(
 
     def count(self, entity_name: str, filter: Filter | None = None) -> int:
         entity = self._require_entity(entity_name)
-        table = self._table_name(entity)
+        # #214: count reads through the same source as find_many (the replica view for a
+        # write-through entity — a 1:1 replica, so the count is unchanged).
+        table = self._read_source_name(entity)
         sql = f"SELECT COUNT(*) FROM {_q(table)}"
         params: list[Any] = []
         filter = self._scope_filter(filter, tph_subtype_of(entity))  # FR-017 TPH subtype scope
@@ -591,6 +628,23 @@ def _table_name(self, entity: MetaObject) -> str:
                     return pn
         return entity.name
 
+    def _read_source_name(self, entity: MetaObject) -> str:
+        """The physical relation READS run against. FR-024 §7 (#214): a write-through
+        entity read-view reads through its read-only REPLICA VIEW (which carries the
+        derived ``origin.*`` columns), while writes still target the table
+        (:meth:`_table_name`). Every other object reads its own primary source (=
+        ``_table_name``), so vanilla/projection behavior is unchanged.
+
+        OWN + role-agnostic: the replica view carries ``@role: replica``, so it is found
+        by read-only kind among the entity's own sources, not a primary-role accessor."""
+        if entity.is_write_through():
+            for c in entity.own_children():
+                if isinstance(c, MetaSource) and c.is_read_only():
+                    pn = c.physical_name()
+                    if pn:
+                        return pn
+        return self._table_name(entity)
+
     @staticmethod
     def _scope_filter(filter: Filter | None, tph: TphSubtype | None) -> Filter | None:
         """AND the TPH discriminator predicate into a filter (subtype-scoped reads).

server/python/tests/codegen/test_write_through.py

@@ -0,0 +1,112 @@
+"""FR-024 §7 (#214) — write-through entity read-view codegen (Python port).
+
+A write-through entity declares BOTH a writable ``source.rdb`` (@kind:table) and a
+read-only replica ``source.rdb`` (@role:replica @kind:view) plus DERIVED fields (a
+field carrying an ``origin.*`` child). The codegen contract mirrors the TS reference
+(``b4eee456``): the read model ``<Name>`` carries the derived field, while the write
+models ``<Name>Create`` / ``<Name>Patch`` EXCLUDE it (it is view-computed, not client
+input). The router IS emitted (a write-through entity is writable), regardless of
+source declaration order.
+
+Canonical fixture: Customer + write-through Order (replica view ``v_order_with_customer``,
+derived ``customerName`` passthrough from ``Customer.name`` via the ``customer`` join).
+"""
+from __future__ import annotations
+
+import json
+
+import metaobjects.core_types  # noqa: F401  — side-effect: registers attr classes
+from metaobjects import load_string
+from metaobjects.codegen.generators.entity_model import render_entity_model
+from metaobjects.codegen.generators.filter_allowlist_generator import render_filter_allowlist
+from metaobjects.codegen.generators.router_generator import render_router
+from metaobjects.meta.core.object.meta_object import MetaObject
+
+# Table source declared FIRST.
+_META = {
+    "metadata.root": {
+        "package": "acme::sales",
+        "children": [
+            {
+                "object.entity": {
+                    "name": "Customer",
+                    "children": [
+                        {"source.rdb": {"@table": "customers"}},
+                        {"field.long": {"name": "id"}},
+                        {"field.string": {"name": "name", "@required": True}},
+                        {"identity.primary": {"name": "pk", "@fields": ["id"], "@generation": "increment"}},
+                    ],
+                }
+            },
+            {
+                "object.entity": {
+                    "name": "Order",
+                    "children": [
+                        {"source.rdb": {"@role": "primary", "@table": "orders"}},
+                        {"source.rdb": {"@role": "replica", "@kind": "view", "@view": "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"], "@generation": "increment"}},
+                        {"identity.reference": {"name": "ref_customer", "@fields": ["customerId"], "@references": "Customer"}},
+                    ],
+                }
+            },
+        ],
+    }
+}
+
+# Same, but with the replica VIEW source declared BEFORE the table — guards that
+# write-through detection / router emission is source-order-independent.
+_META_VIEW_FIRST = json.loads(json.dumps(_META))
+_order = _META_VIEW_FIRST["metadata.root"]["children"][1]["object.entity"]["children"]
+_order[0], _order[1] = _order[1], _order[0]  # swap the two source.rdb declarations
+
+
+def _order_obj(meta: dict) -> MetaObject:
+    root = load_string(json.dumps(meta)).root
+    return next(c for c in root.own_children()
+                if isinstance(c, MetaObject) and c.name == "Order")
+
+
+def test_read_model_carries_derived_write_models_exclude_it() -> None:
+    order = _order_obj(_META)
+    assert order.is_write_through()
+
+    # render_entity_model emits the whole module: the read model `Order` plus the
+    # write shapes `OrderCreate` / `OrderPatch`. EXEC it (a syntax/name/import defect
+    # fails here), then introspect each Pydantic model's field set.
+    src = render_entity_model(order)
+    ns: dict[str, object] = {}
+    exec(compile(src, "<Order model>", "exec"), ns)  # noqa: S102
+
+    read_fields = set(ns["Order"].model_fields)
+    create_fields = set(ns["OrderCreate"].model_fields)
+    patch_fields = set(ns["OrderPatch"].model_fields)
+
+    # the read model carries the derived field; the write shapes EXCLUDE it.
+    assert "customerName" in read_fields
+    assert "customerName" not in create_fields
+    assert "customerName" not in patch_fields
+    # the stored writable field is present everywhere.
+    assert "customerId" in read_fields
+    assert "customerId" in create_fields
+    assert "customerId" in patch_fields
+
+
+def test_write_through_router_is_emitted_regardless_of_source_order() -> None:
+    # A write-through entity is writable → it gets a CRUD router (a read-only
+    # projection returns None). Order-independent: the view-first fixture too.
+    assert render_router(_order_obj(_META)) is not None
+    assert render_router(_order_obj(_META_VIEW_FIRST)) is not None
+    assert _order_obj(_META_VIEW_FIRST).is_write_through()
+
+
+def test_write_through_filter_allowlist_is_emitted_with_the_router() -> None:
+    # The generated router imports the entity's filter allowlist, so the allowlist
+    # generator MUST emit for a write-through entity too — regardless of source order,
+    # else a view-first router imports a never-generated module (FastAPI startup crash).
+    assert render_filter_allowlist(_order_obj(_META)) is not None
+    assert render_filter_allowlist(_order_obj(_META_VIEW_FIRST)) is not None