@@ -15,6 +15,7 @@
     build_object_index,
     resolve_m2m_descriptors,
 )
+from metaobjects.codegen.generators.tph_plan import tph_subtype_binding
 
 
 def _is_int(value: object) -> bool:
@@ -199,6 +200,21 @@ def render_entity_model(
             imports.add(f"from .{base_class} import {base_class}")
 
         lines, uses_field = self._emit_field_lines(entity, imports, object_index)
+
+        # FR-017 TPH: a concrete subtype pins the inherited discriminator field to its
+        # own value (Literal) so the Pydantic model rejects a foreign-subtype tag —
+        # the type-layer parity with the TS `z.literal` / C# discriminator pin. (Python's
+        # runtime is dict-based, so the base's discriminated-UNION alias is intentionally
+        # deferred: it isn't consumed by the generated routes/ObjectManager and would
+        # force a base↔subtype circular import for an unused artifact.)
+        binding = tph_subtype_binding(entity)
+        if binding is not None:
+            disc_field, disc_value = binding
+            lines = [
+                f'    {disc_field}: Literal["{disc_value}"] = "{disc_value}"',
+                *lines,
+            ]
+            imports.add("from typing import Literal")
         body = lines if lines else ["    pass"]
 
         # Import only the pydantic names actually referenced.
 
@@ -35,6 +35,8 @@
 from metaobjects.codegen.constants import generated_header
 from metaobjects.codegen.format import ruff_format
 from metaobjects.codegen.generator import EmittedFile, GenContext, Generator, per_entity
+from metaobjects.codegen.generators.m2m_codegen import build_object_index
+from metaobjects.codegen.generators.tph_plan import tph_plan_for
 from metaobjects.codegen.instance_artifacts import emits_instance_artifacts
 from metaobjects.meta.core.field import field_constants as fc
 from metaobjects.meta.core.field.meta_field import MetaField
@@ -176,22 +178,34 @@ def _ops_for_field(self, field: MetaField) -> tuple[str, ...]:
         return ops_for_subtype_ordered(field.sub_type)
 
     def _compute_filterable_ops(
-        self, entity: MetaObject
+        self, entity: MetaObject, object_index: dict[str, MetaObject] | None = None
     ) -> dict[str, tuple[str, ...]]:
         """Build the ``{field_name: op_tuple}`` map for ``entity`` (own + inherited
         effective fields). Only fields with ``@filterable: true`` are included;
         object fields and fields whose ``_ops_for_field`` yields no operators are
-        skipped. Preserves declaration order so the emitted source is deterministic."""
+        skipped. Preserves declaration order so the emitted source is deterministic.
+
+        FR-017 TPH: when ``entity`` is a discriminator base (``object_index`` given),
+        the union also folds in each subtype's own filterable fields, so the single
+        table's per-subtype routes (and the polymorphic base) can filter on a
+        subtype-only column. Non-TPH entities are unaffected."""
         out: dict[str, tuple[str, ...]] = {}
-        for f in entity.fields():
-            if f.sub_type == fc.FIELD_SUBTYPE_OBJECT:
-                continue
-            if not _is_filterable(f):
-                continue
+
+        def add(f: MetaField) -> None:
+            if f.sub_type == fc.FIELD_SUBTYPE_OBJECT or f.name in out or not _is_filterable(f):
+                return
             ops = self._ops_for_field(f)
-            if not ops:
-                continue
-            out[f.name] = ops
+            if ops:
+                out[f.name] = ops
+
+        for f in entity.fields():
+            add(f)
+        if object_index is not None:
+            plan = tph_plan_for(entity, object_index)
+            if plan is not None:
+                for st in plan.subtypes:
+                    for f in st.entity.own_fields():
+                        add(f)
         return out
 
     def _emit_constants(
@@ -220,13 +234,18 @@ def _emit_constants(
             lines.append("}")
         return lines
 
-    def render_filter_allowlist(self, entity: MetaObject) -> str | None:
+    def render_filter_allowlist(
+        self, entity: MetaObject, object_index: dict[str, MetaObject] | None = None
+    ) -> str | None:
         """Render the filter allowlist module for ``entity`` (or ``None`` to skip).
 
         Returns ``None`` for entities without a ``source.rdb`` child and for
         read-only kinds (``view`` / ``materializedView`` / ``storedProc`` /
         ``tableFunction``) — these match the router generator's "no router"
         gate, so emitting an allowlist would be pure noise.
+
+        ``object_index`` (optional) lets a TPH discriminator base fold in its
+        subtypes' filterable fields (see :meth:`_compute_filterable_ops`).
         """
         if not emits_instance_artifacts(entity):
             return None
@@ -241,7 +260,7 @@ def render_filter_allowlist(self, entity: MetaObject) -> str | None:
         fields_const = f"{upper}_FILTER_FIELDS"
         ops_const = f"{upper}_FILTER_OPS_BY_FIELD"
 
-        ops_by_field = self._compute_filterable_ops(entity)
+        ops_by_field = self._compute_filterable_ops(entity, object_index)
 
         parts: list[str] = []
         parts.append(
@@ -257,8 +276,10 @@ def render_filter_allowlist(self, entity: MetaObject) -> str | None:
         return "\n".join(parts)
 
     def generate(self, ctx: GenContext) -> list[EmittedFile]:
+        index = build_object_index(ctx.entities)
+
         def emit(entity: MetaObject, _c: GenContext) -> list[EmittedFile]:
-            source = self.render_filter_allowlist(entity)
+            source = self.render_filter_allowlist(entity, index)
             if source is None:
                 return []
             snake = _snake_case(entity.name)
@@ -272,10 +293,12 @@ def emit(entity: MetaObject, _c: GenContext) -> list[EmittedFile]:
         return per_entity(emit)(ctx)
 
 
-def render_filter_allowlist(entity: MetaObject) -> str | None:
+def render_filter_allowlist(
+    entity: MetaObject, object_index: dict[str, MetaObject] | None = None
+) -> str | None:
     """Module-level back-compat wrapper. Delegates to a default
     :class:`FilterAllowlistGenerator`. Subclass it to customize."""
-    return FilterAllowlistGenerator().render_filter_allowlist(entity)
+    return FilterAllowlistGenerator().render_filter_allowlist(entity, object_index)
 
 
 def filter_allowlist_generator() -> Generator:
 
@@ -395,7 +395,7 @@ def list_sig(fn: str, route: str) -> list[str]:
         for st in plan.subtypes:
             seg = st.route_segment
             val = st.value
-            sfx = _snake_case(st.entity.name)
+            sfx = st.route_segment  # handler-name suffix = URL segment (e.g. "bridge"), matches the route
             parts.extend(list_sig(f"list_{plural}_{sfx}", f"/{seg}"))
             parts.extend(self._emit_tph_list_body(f'"{val}"', fields_const, ops_const))
             parts.append("")
 
@@ -58,6 +58,23 @@ def _discriminator_root(obj: MetaObject) -> MetaObject | None:
     return None
 
 
+def tph_subtype_binding(obj: MetaObject) -> tuple[str, str] | None:
+    """For a concrete TPH subtype, return ``(discriminator_field, discriminator_value)``
+    — the field NAME inherited from the ``@discriminator`` base + this subtype's own
+    ``@discriminatorValue``. ``None`` when *obj* is not a subtype. Used by the entity
+    generator to pin the inherited discriminator field to a ``Literal`` on the subtype."""
+    value = obj.attr(OBJECT_ATTR_DISCRIMINATOR_VALUE)  # own attr
+    if not isinstance(value, str) or not value:
+        return None
+    root = _discriminator_root(obj)
+    if root is None or root is obj:
+        return None
+    field = root.attr(OBJECT_ATTR_DISCRIMINATOR)
+    if not isinstance(field, str) or not field:
+        return None
+    return (field, value)
+
+
 def is_tph_subtype(obj: MetaObject) -> bool:
     """True when *obj* is a concrete TPH subtype: it declares ``@discriminatorValue``
     and (transitively) extends a ``@discriminator``-bearing base. Such an entity emits
 
@@ -264,7 +264,12 @@ def create(self, entity_name: str, data: dict[str, Any]) -> dict[str, Any]:
         return {col_to_field.get(k, k): v for k, v in row.items()}
 
     def update(
-        self, entity_name: str, id_value: Any, data: dict[str, Any]
+        self,
+        entity_name: str,
+        id_value: Any,
+        data: dict[str, Any],
+        *,
+        if_missing: str = "ignore",
     ) -> dict[str, Any] | None:
         """UPDATE a row by primary key through the runtime write path.
 
@@ -273,18 +278,23 @@ def update(
         as a dict, currency as integer minor units). Each value is run through the
         SAME write codec the INSERT path uses (``_coerce_write_value``) so the
         PATCH path cannot silently skip the type coercion INSERT applies — the
-        per-port hazard the ``update-delete-all-types`` corpus gates. Returns the
-        updated row (mapped to metadata field names) via ``RETURNING``, or
-        ``None`` when no row matched the PK.
+        per-port hazard the ``update-delete-all-types`` corpus gates.
+
+        Returns the updated row (mapped to metadata field names) via ``RETURNING``.
+        When no row matched the (TPH-scoped) PK, behavior follows *if_missing*
+        (mirrors the TS ``WriteOpts.ifMissing``): ``"ignore"`` (default) → ``None``
+        so a REST route renders 404; ``"throw"`` → raise so the persistence DSL's
+        ``expect-error`` op is satisfied. The discriminator is immutable, so a TPH
+        subtype's patch strips it and the by-id write is scoped to the subtype (a
+        cross-subtype id matches no row → the same not-found path).
         """
         entity = self._require_entity(entity_name)
         table = self._table_name(entity)
         pk_field = self._primary_pk_field(entity)
         pk_col = _column_of(entity.find_field(pk_field))
 
-        # FR-017 TPH: the discriminator is immutable — a subtype can't be retyped,
-        # so it is stripped from the patch. Reads/writes are subtype-scoped (a row
-        # of a different subtype is invisible → a cross-subtype update matches no row).
+        # FR-017 TPH: the discriminator is immutable — strip it from the patch; the
+        # by-id write is subtype-scoped (a row of a different subtype is invisible).
         tph = tph_subtype_of(entity)
         if tph is not None and tph.field in data:
             data = {k: v for k, v in data.items() if k != tph.field}
@@ -300,8 +310,9 @@ def update(
             set_cols.append(_column_of(f))
             params.append(_coerce_write_value(f, raw))
         if not set_cols:
-            # No columns to set → just read the row back by PK (no-op update).
-            return self.find_by_id(entity_name, id_value)
+            # 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()}
@@ -318,14 +329,7 @@ def update(
         result = self._driver.update_returning(sql, tuple(params))
         if result is None:
             self.last_column_oids = {}
-            if tph is not None:
-                # A subtype-scoped update that matched no row is a cross-subtype
-                # (or absent) write — the runtime rejects it (expect-error contract),
-                # mirroring the per-subtype route's 404. Non-TPH keeps None semantics.
-                raise KeyError(
-                    f"update('{entity_name}'): no {tph.value} row with {pk_field}={id_value!r}"
-                )
-            return None
+            return self._on_missing_update(entity_name, pk_field, id_value, if_missing)
         # Surface the RETURNING column OIDs (mapped to metadata field names) so the
         # serialization boundary applies the same SQL-type wire rules as a read —
         # a BIGINT / currency column comes back as a numeric string. Mirrors the
@@ -336,6 +340,18 @@ def update(
         row = result.rows[0]
         return {col_to_field.get(k, k): v for k, v in row.items()}
 
+    @staticmethod
+    def _on_missing_update(
+        entity_name: str, pk_field: str, id_value: Any, if_missing: str
+    ) -> None:
+        """No (TPH-scoped) row matched an update: ``"throw"`` raises (the persistence
+        ``expect-error`` contract), ``"ignore"`` returns ``None`` (REST route → 404)."""
+        if if_missing == "throw":
+            raise KeyError(
+                f"update('{entity_name}'): no row with {pk_field}={id_value!r} in scope"
+            )
+        return None
+
     def delete(self, entity_name: str, id_value: Any) -> bool:
         """DELETE a row by primary key through the runtime write path.