feat(fr-035): present-key PATCH tristate — Python port

Green the cross-port `update-explicit-null-clears` gate on Python (both lanes).
Python's write path already clears a present null (raw-dict merge through
ObjectManager.update), so the only gap was the required-null rejection.

- codegen router_generator: emit a module-level `_REQUIRED_FIELDS` frozenset
  (sibling of the filter allowlist) and guard the generated update handler — an
  explicit null on a @required key → 400 {"error":"validation"} before the repo
  call; a present null on a non-required field falls through and clears the
  column; an omitted required field is untouched. The set is derived from ALL
  @required fields including field.object/jsonb columns (not just scalars), and
  the guard is emitted on BOTH the non-TPH handler and the TPH per-subtype
  handlers (union of base + subtype required fields).
- reference server (api_contract_server): the same required-null → 400 guard.
- A shared `_py_set_literal(names, frozen=)` helper collapses the set/frozenset
  literal builder (was copy-pasted for the sort allowlists); byte-identical
  output, so existing sort goldens are unchanged.

Validate-before-existence (guard runs before the repo/404 check) matches the TS
generated lane (Zod safeParse → 400 precedes the DB update → 404), so the two
ports agree on a required-null PATCH to a missing id.

Gate green both Python lanes; full api-contract 46/46, codegen 289 pass
(2 pre-existing unrelated staleness-nudge failures), TPH generated 5/5, ruff clean.

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/router_generator.py

@@ -39,6 +39,7 @@
 from metaobjects.apidocs.naming import snake_case as _snake_case
 from metaobjects.codegen.constants import generated_header
 from metaobjects.codegen.format import ruff_format
+from metaobjects.codegen.fr010_field_mapping import is_required
 from metaobjects.codegen.generator import EmittedFile, GenContext, Generator, per_entity
 from metaobjects.codegen.generators.m2m_codegen import (
     M2mDescriptor,
@@ -89,6 +90,24 @@ def _scalar_fields(entity: MetaObject) -> list[MetaField]:
     return [f for f in entity.fields() if f.sub_type != fc.FIELD_SUBTYPE_OBJECT]
 
 
+def _required_field_names(entity: MetaObject) -> list[str]:
+    """Every @required field name — scalar AND object/jsonb (unlike
+    _scalar_fields, which drops object fields for the sort allowlist). FR-035
+    PATCH-2 guards present-null on any of these, and a @required jsonb column can
+    be nulled just like a scalar one."""
+    return [f.name for f in entity.fields() if is_required(f)]
+
+
+def _py_set_literal(names: list[str], *, frozen: bool = False) -> str:
+    """A Python set/frozenset literal from field names, matching the generated
+    allowlist idiom (one quoted name per line). Empty → ``frozenset()`` / ``set()``."""
+    empty = "frozenset()" if frozen else "set()"
+    if not names:
+        return empty
+    body = "{\n" + "".join(f'    "{name}",\n' for name in names) + "}"
+    return f"frozenset({body})" if frozen else body
+
+
 def _pk_py_type(entity: MetaObject) -> PyType:
     """The Python type of the entity's primary-key path/id parameter, derived
     from the PK field's declared subtype via ``type_map.py_type_for`` — the same
@@ -300,6 +319,12 @@ def _emit_route_handler(
                 "    dto: dict[str, Any],",
                 f"    repo: Annotated[{repo_class}, Depends(get_repository)],",
                 ") -> Any:",
+                "    # FR-035 PATCH-2: an explicit null on a @required field is a 400 —",
+                "    # a present null on a NON-required field falls through and clears it,",
+                "    # and an OMITTED required field is untouched (never a 400).",
+                "    for _k in _REQUIRED_FIELDS:",
+                "        if _k in dto and dto[_k] is None:",
+                '            return JSONResponse(status_code=400, content={"error": "validation"})',
                 f"    saved = repo.update({pk_param}, dto)",
                 "    if saved is None:",
                 '        return JSONResponse(status_code=404, content={"error": "not_found"})',
@@ -385,9 +410,18 @@ def _render_tph_router(self, entity: MetaObject, plan: TphPlan) -> str:
                 if f.name not in seen:
                     seen.add(f.name)
                     sort_fields.append(f.name)
-        sort_set_body = "set()" if not sort_fields else (
-            "{\n" + "".join(f'    "{name}",\n' for name in sort_fields) + "}"
-        )
+        sort_set_body = _py_set_literal(sort_fields)
+        # FR-035 PATCH-2: @required fields across the base AND every subtype — an
+        # explicit null on any of these is a 400 (the per-subtype update handlers
+        # guard against it before the repo call). Union, stable order.
+        required_names: list[str] = _required_field_names(entity)
+        req_seen = set(required_names)
+        for st in plan.subtypes:
+            for name in _required_field_names(st.entity):
+                if name not in req_seen:
+                    req_seen.add(name)
+                    required_names.append(name)
+        required_set_body = _py_set_literal(required_names, frozen=True)
 
         h = generated_header(short_name, _effective_fqn(entity)).rstrip()
         parts: list[str] = []
@@ -427,6 +461,9 @@ def _render_tph_router(self, entity: MetaObject, plan: TphPlan) -> str:
         parts.append(f"_SORT_ALLOWLIST: set[str] = {sort_set_body}")
         parts.append("")
         parts.append("")
+        parts.append(f"_REQUIRED_FIELDS: frozenset[str] = {required_set_body}")
+        parts.append("")
+        parts.append("")
         parts.append("def _parse_sort(raw: str) -> _SortClause | None:")
         parts.append('    """Parse `field:asc|desc`; return None for malformed / disallowed input."""')
         parts.append('    parts = raw.split(":", 1)')
@@ -511,6 +548,10 @@ def list_sig(fn: str, route: str) -> list[str]:
             parts.append("    dto: dict[str, Any],")
             parts.append(f"    repo: Annotated[{repo_class}, Depends(get_repository)],")
             parts.append(") -> Any:")
+            parts.append("    # FR-035 PATCH-2: an explicit null on a @required field is a 400.")
+            parts.append("    for _k in _REQUIRED_FIELDS:")
+            parts.append("        if _k in dto and dto[_k] is None:")
+            parts.append('            return JSONResponse(status_code=400, content={"error": "validation"})')
             parts.append(f'    saved = repo.update("{val}", {pk_param}, dto)')
             parts.append("    if saved is None:")
             parts.append('        return JSONResponse(status_code=404, content={"error": "not_found"})')
@@ -600,9 +641,10 @@ def render_router(
         ops_const = f"{upper}_FILTER_OPS_BY_FIELD"
         allowlist_module = f"{snake}_filter_allowlist"
 
-        sort_set_body = "set()" if not sort_fields else (
-            "{\n" + "".join(f'    "{name}",\n' for name in sort_fields) + "}"
-        )
+        sort_set_body = _py_set_literal(sort_fields)
+        # FR-035 PATCH-2: an explicit null on a @required field (scalar or jsonb)
+        # is a 400 — the update handler guards these before the repo call.
+        required_set_body = _py_set_literal(_required_field_names(entity), frozen=True)
 
         parts: list[str] = []
         parts.append(
@@ -642,6 +684,9 @@ def render_router(
         parts.append(f"_SORT_ALLOWLIST: set[str] = {sort_set_body}")
         parts.append("")
         parts.append("")
+        parts.append(f"_REQUIRED_FIELDS: frozenset[str] = {required_set_body}")
+        parts.append("")
+        parts.append("")
         parts.append('def _parse_sort(raw: str) -> _SortClause | None:')
         parts.append('    """Parse `field:asc|desc`; return None for malformed / disallowed input."""')
         parts.append('    parts = raw.split(":", 1)')

server/python/tests/integration/api_contract_server.py

@@ -418,6 +418,12 @@ def create_author(dto: dict[str, Any]) -> Any:
     @app.patch("/api/authors/{author_id}")
     @app.put("/api/authors/{author_id}")
     def update_author(author_id: int, dto: dict[str, Any]) -> Any:
+        # FR-035 PATCH-2: an explicit null on a @required field (name / createdAt,
+        # per meta.json) is a 400 — a present null on the nullable bio clears it,
+        # and an omitted required field is simply untouched (never a 400).
+        for _k in ("name", "createdAt"):
+            if _k in dto and dto[_k] is None:
+                return JSONResponse(status_code=400, content={"error": "validation"})
         saved = repo.update(author_id, dto)
         if saved is None:
             return JSONResponse(status_code=404, content={"error": "not_found"})