feat(python-codegen): generated FastAPI router stamps @autoset (ADR-0045, #203)

The generated Python router delegated raw DTOs to the consumer repository seam and
did no @autoset stamping — #203's Python stamping lives only in the ObjectManager
runtime, BELOW that seam. So an adopter who wires their own persistence into the
generated router got a deployed API that silently dropped the timestamp-stamping FR.

Per ADR-0045 (the generated API surface owns metamodel write semantics), the router
now stamps inline, ABOVE the repo seam, with no runtime dependency:
- create stamps onCreate + onUpdate from ONE captured base instant (a fresh row's
  createdAt == updatedAt), ignoring any caller-supplied value;
- update/patch bumps onUpdate on EVERY request (a server-inserted present key,
  compatible with the PATCH present-key tristate) and never rewrites onCreate;
- the now()-expression is keyed off the column temporal type (date/time/timestamp;
  @localTime → naive), mirroring ObjectManager._auto_set_stamp;
- byte-identical output for entities with no @autoset field (regression-pinned:
  render_router callers 26/26 green).

The ObjectManager keeps stamping for non-HTTP writes (defense-in-depth). TPH-router
@autoset stamping is a documented follow-up (not exercised by the corpus).

This is the Python leg of the ADR-0045 rollout (Kotlin leg: 46d8e54). The shared
api-contract @autoset gate follows; no scenario lands here, so no lane reds.

Refs #203, #229.

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

Author: dmealing

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

@@ -52,6 +52,7 @@
 from metaobjects.codegen.type_map import PyType, py_type_for
 from metaobjects.meta.core.field import field_constants as fc
 from metaobjects.meta.core.field.meta_field import MetaField
+from metaobjects.meta.persistence.db import db_constants as dbc
 from metaobjects.meta.core.identity.identity_constants import (
     IDENTITY_ATTR_FIELDS,
     IDENTITY_REFERENCE_ATTR_REFERENCES,
@@ -98,6 +99,60 @@ def _required_field_names(entity: MetaObject) -> list[str]:
     return [f.name for f in entity.fields() if is_required(f)]
 
 
+# --- #203 / ADR-0045: @autoSet stamping in the generated router (above the repo seam) ----------
+
+_AUTO_SET_TEMPORAL_SUBTYPES = (
+    fc.FIELD_SUBTYPE_DATE,
+    fc.FIELD_SUBTYPE_TIME,
+    fc.FIELD_SUBTYPE_TIMESTAMP,
+)
+
+
+def _auto_set_split(entity: MetaObject) -> tuple[list[MetaField], list[MetaField]]:
+    """The entity's ``@autoSet`` temporal fields split into ``(onCreate, onUpdate)``.
+
+    Reads the RESOLVING ``@autoSet`` (ADR-0039) so an inherited
+    ``BaseEntity.createdAt/updatedAt`` is honored; a non-temporal field is skipped.
+    Both lists are empty for an entity that declares none, keeping its router
+    byte-identical to the pre-#203 output."""
+    on_create: list[MetaField] = []
+    on_update: list[MetaField] = []
+    for f in entity.fields():
+        if f.sub_type not in _AUTO_SET_TEMPORAL_SUBTYPES:
+            continue
+        mode = f.get_meta_attr(fc.FIELD_ATTR_AUTO_SET)  # ADR-0039 resolving: may be inherited via extends
+        if mode == fc.AUTO_SET_ON_CREATE:
+            on_create.append(f)
+        elif mode == fc.AUTO_SET_ON_UPDATE:
+            on_update.append(f)
+    return on_create, on_update
+
+
+def _auto_set_stamp_expr(field: MetaField, base_var: str) -> str:
+    """The inline now()-expression for an ``@autoSet`` *field*, derived from one shared
+    tz-aware *base_var* datetime so every column stamped in one op is equal (a fresh
+    row's created == updated). Keyed off the COLUMN's temporal type: ``field.date`` →
+    ``.date()``; ``field.time`` → ``.time()``; ``field.timestamp`` → the tz-aware base
+    (``@localTime`` → a naive wall-clock value). Mirrors ObjectManager._auto_set_stamp."""
+    sub = field.sub_type
+    if sub == fc.FIELD_SUBTYPE_DATE:
+        return f"{base_var}.date()"
+    if sub == fc.FIELD_SUBTYPE_TIME:
+        return f"{base_var}.time()"
+    is_tz = field.get_meta_attr(dbc.FIELD_ATTR_LOCAL_TIME) is not True  # ADR-0039 resolving
+    return base_var if is_tz else f"{base_var}.replace(tzinfo=None)"
+
+
+def _auto_set_stamp_lines(fields: list[MetaField]) -> list[str]:
+    """Router-handler body lines stamping *fields* into ``dto`` from ONE captured base
+    instant (so all same-op columns are equal). Empty list for no fields."""
+    if not fields:
+        return []
+    lines = ["    _asnow = _dt.datetime.now(_dt.timezone.utc)"]
+    lines += [f'    dto["{f.name}"] = {_auto_set_stamp_expr(f, "_asnow")}' for f in fields]
+    return lines
+
+
 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()``."""
@@ -259,6 +314,8 @@ def _emit_route_handler(
         ops_const: str,
         model_name: str,
         patch_model: str,
+        create_autoset: list[str] = (),
+        update_autoset: list[str] = (),
     ) -> list[str]:
         """One CRUD route handler block, dispatched by *name*
         (``list`` / ``get`` / ``create`` / ``update`` / ``delete``). Override to
@@ -318,6 +375,11 @@ def _emit_route_handler(
                 f"        {model_name}(**dto)",
                 "    except ValidationError:",
                 '        return JSONResponse(status_code=400, content={"error": "validation"})',
+                # #203/ADR-0045: the generated router (the API surface) stamps @autoSet columns
+                # ABOVE the consumer repo seam — onCreate + onUpdate both stamped from one instant
+                # (a fresh row's createdAt == updatedAt), ignoring any caller-supplied value.
+                *(["    # #203/ADR-0045: stamp @autoSet columns (server-owned; caller ignored)."]
+                  + list(create_autoset) if create_autoset else []),
                 "    return repo.create(dto)",
             ]
         if name == "update":
@@ -341,6 +403,11 @@ def _emit_route_handler(
                 f"        {patch_model}(**dto)",
                 "    except ValidationError:",
                 '        return JSONResponse(status_code=400, content={"error": "validation"})',
+                # #203/ADR-0045: bump onUpdate @autoSet columns (server-owned) on EVERY patch,
+                # above the repo seam — a server-inserted present key (compatible with the PATCH
+                # present-key tristate); onCreate columns are never touched here.
+                *(["    # #203/ADR-0045: bump onUpdate @autoSet column(s) (server-owned)."]
+                  + list(update_autoset) if update_autoset else []),
                 f"    saved = repo.update({pk_param}, dto)",
                 "    if saved is None:",
                 '        return JSONResponse(status_code=404, content={"error": "not_found"})',
@@ -684,13 +751,25 @@ def render_router(
         # is a 400 — the update handler guards these before the repo call.
         required_set_body = _py_set_literal(_required_field_names(entity), frozen=True)
 
+        # #203/ADR-0045: @autoSet stamp lines for the create/update handlers (empty for a
+        # non-@autoSet entity → byte-identical output). insert stamps onCreate+onUpdate from one
+        # instant; a patch bumps onUpdate only (createdAt stays immutable).
+        _on_create_auto, _on_update_auto = _auto_set_split(entity)
+        create_autoset = _auto_set_stamp_lines(_on_create_auto + _on_update_auto)
+        update_autoset = _auto_set_stamp_lines(_on_update_auto)
+        has_autoset = bool(_on_create_auto or _on_update_auto)
+
         parts: list[str] = []
         parts.append(
             generated_header(short_name, _effective_fqn(entity)).rstrip() + "\n"
             + f'"""GENERATED — REST router for {short_name} entity. Implements the cross-port API contract."""\n'
         )
         parts.append("from __future__ import annotations")
         parts.append("")
+        if has_autoset:
+            # #203/ADR-0045: the router stamps @autoSet columns inline (no runtime dependency).
+            parts.append("import datetime as _dt")
+            parts.append("")
         for import_line in sorted(pk.imports):
             parts.append(import_line)
         if pk.imports:
@@ -762,6 +841,8 @@ def render_router(
             ops_const=ops_const,
             model_name=f"{short_name}Create",
             patch_model=f"{short_name}Patch",
+            create_autoset=create_autoset,
+            update_autoset=update_autoset,
         )
         for i, hname in enumerate(("list", "get", "create", "update", "delete")):
             if i > 0:

server/python/tests/codegen/test_router_autoset.py

@@ -0,0 +1,84 @@
+"""#203 / ADR-0045 — the generated FastAPI router (the deployed API surface) stamps
+``@autoSet`` timestamps ABOVE the consumer repository seam, so an adopter who wires
+their own persistence into the generated router still gets the shipped stamping
+semantics. (The ObjectManager keeps stamping for non-HTTP writes — defense-in-depth,
+not the wire-tier guarantee.) A non-``@autoSet`` entity's router stays byte-identical."""
+
+from __future__ import annotations
+
+import shutil
+import tempfile
+from pathlib import Path
+
+from metaobjects import MetaDataLoader
+from metaobjects.codegen.generators.m2m_codegen import build_object_index
+from metaobjects.codegen.generators.router_generator import render_router
+from metaobjects.meta.core.object.meta_object import MetaObject
+from metaobjects.shared.base_types import TYPE_OBJECT
+
+# Event declares both @autoSet policies on field.timestamp columns; Note declares none
+# (the byte-identical baseline).
+_AUTOSET_FIXTURE = """{
+  "metadata.root": { "package": "acme::events", "children": [
+    { "object.entity": { "name": "Event", "children": [
+        { "source.rdb":      { "@table": "events" } },
+        { "field.long":      { "name": "id" } },
+        { "field.string":    { "name": "name", "@required": true, "@maxLength": 120 } },
+        { "field.timestamp": { "name": "createdAt", "@autoSet": "onCreate" } },
+        { "field.timestamp": { "name": "updatedAt", "@autoSet": "onUpdate" } },
+        { "identity.primary": { "@fields": "id", "@generation": "increment" } }
+    ] } },
+    { "object.entity": { "name": "Note", "children": [
+        { "source.rdb":      { "@table": "notes" } },
+        { "field.long":      { "name": "id" } },
+        { "field.string":    { "name": "title", "@required": true, "@maxLength": 200 } },
+        { "identity.primary": { "@fields": "id", "@generation": "increment" } }
+    ] } }
+  ] }
+}"""
+
+
+def _load(fixture: str) -> dict[str, MetaObject]:
+    tmp = Path(tempfile.mkdtemp(prefix="router-autoset-"))
+    try:
+        (tmp / "meta.events.json").write_text(fixture)
+        result = MetaDataLoader.from_directory(str(tmp))
+        assert not result.errors, [f"{e.code}: {e.message}" for e in result.errors]
+        return {
+            c.name: c
+            for c in result.root.children()
+            if c.type == TYPE_OBJECT and isinstance(c, MetaObject)
+        }
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+
+
+_ENTITIES = _load(_AUTOSET_FIXTURE)
+_INDEX = build_object_index(list(_ENTITIES.values()))
+
+
+def test_router_create_stamps_both_autoset_columns_from_one_instant() -> None:
+    src = render_router(_ENTITIES["Event"], _INDEX)
+    assert src is not None
+    assert "import datetime as _dt" in src
+    # ONE captured base instant, assigned to BOTH columns → a fresh row's createdAt == updatedAt.
+    assert "_asnow = _dt.datetime.now(_dt.timezone.utc)" in src
+    assert 'dto["createdAt"] = _asnow' in src
+    assert 'dto["updatedAt"] = _asnow' in src
+
+
+def test_router_update_bumps_only_onupdate() -> None:
+    src = render_router(_ENTITIES["Event"], _INDEX)
+    assert src is not None
+    update_body = src.split("def update_")[1].split("def delete_")[0]
+    # the update handler bumps updatedAt; createdAt is never stamped on update (immutable).
+    assert 'dto["updatedAt"] = _asnow' in update_body
+    assert 'dto["createdAt"]' not in update_body
+
+
+def test_non_autoset_router_is_byte_identical() -> None:
+    src = render_router(_ENTITIES["Note"], _INDEX)
+    assert src is not None
+    assert "import datetime as _dt" not in src
+    assert "_asnow" not in src
+    assert "_dt.datetime.now" not in src