feat(codegen-python): reverse navigation via explicit FK finders (ADR-0038)

Implement the Python port of ADR-0038 / ADR-0036 Wave 4: generate reverse 1:N
navigation as explicit, typed FK query finders on the repository Protocol seam,
NOT lazy ORM collections — matching the TS reference and the cross-port contract.

For each FK an entity E holds (an identity.reference over an FK field referencing
T), E's repository Protocol now gains a finder pair, named by the FK FIELD
(snake_cased, single trailing `_id` dropped) so it is unique within E by
construction:

  find_<e_plural>_by_<fk_segment>(value)     → single,  WHERE fk = ?
  find_<e_plural>_by_<fk_segment>_in(values) → batched, WHERE fk IN (…) (anti-N+1)

Both return list[Any] (the E rows matching a given T id) — a plain, framework-free
single query the consumer implements, NOT a lazy relationship() (no open session,
no N+1). The same-pair case (GameSession with 3 FKs to Scene) yields 3 distinct
finders — find_game_sessions_by_current_scene /
…_by_last_opening_narrative_scene / …_by_transitioning_from_scene — no collision
and no naming attribute.

The Python port only ever emitted M:N navigation (no lazy reverse 1:N
collections), so there is nothing to remove; M:N traversal is unchanged.

- apidocs/naming.py: reverse_finder_fk_segment / reverse_finder_fn /
  reverse_finder_in_fn (the cross-port naming SSOT, idiomatic snake_case).
- router_generator.py: reverse_fks_for (derives FKs from identity.reference) +
  _emit_reverse_finders extension hook, wired into the repository Protocol; the
  existing _emit_repository_protocol override seam is left signature-stable.
- test_reverse_finders.py loads the shared fixtures/conformance/
  reverse-finders-same-pair corpus and asserts the 3 distinct GameSession finders
  + single/batched shapes + no lazy reverse collection.

Shared fixture + goldens untouched; registry-conformance unaffected (no new vocab).

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

Author: claude

server/python/src/metaobjects/apidocs/naming.py

@@ -39,6 +39,9 @@
     "output_prompt_fn",
     "output_parser_fn",
     "extractor_fn",
+    "reverse_finder_fk_segment",
+    "reverse_finder_fn",
+    "reverse_finder_in_fn",
 ]
 
 
@@ -121,3 +124,75 @@ def output_parser_fn(template_name: str) -> str:
 def extractor_fn(template_name: str) -> str:
     """``OrderSummary`` → ``extract_order_summary`` (the strict extractor fn)."""
     return f"extract_{snake_case(template_name)}"
+
+
+# ---------------------------------------------------------------------------
+# ADR-0038 — reverse-relationship navigation as explicit FK finders.
+#
+# For each FK an entity ``E`` holds (an ``identity.reference`` over an FK field
+# referencing entity ``T``), ``E``'s repository surface gains a finder returning
+# the ``E`` rows matching a given ``T`` id — so ``T`` navigates to its referencing
+# ``E`` rows by calling the finder with a ``T`` id. Two variants: a single-value
+# finder and a batched (anti-N+1) ``…_in`` finder. Both are plain, framework-free
+# single queries (``WHERE <fk> = ?`` / ``WHERE <fk> IN (…)``) — NOT lazy ORM
+# collections (ADR-0038: lazy collections are impossible framework-free and are
+# the canonical N+1 anti-pattern).
+#
+# CANONICAL NAMING (the cross-port contract — idiomatic Python snake_case spelling
+# of the cross-port shape ``find<EPlural>By<FkField>`` / ``…In``):
+#
+#   find_<e_plural>_by_<fk_segment>(value)     → SELECT … FROM E WHERE <fk> = ?
+#   find_<e_plural>_by_<fk_segment>_in(values) → SELECT … FROM E WHERE <fk> IN (…)
+#
+# where:
+#   - <e_plural>   is the source entity name pluralized then snake_cased
+#     (``GameSession`` → ``game_sessions``).
+#   - <fk_segment> is the FK FIELD name (NOT the relationship/navigation name and
+#     NOT the raw column), snake_cased, with a single trailing ``_id`` dropped if
+#     present. The FK field name is unique within an entity, so the finder name is
+#     unique by construction — this dissolves the same-pair collision and removes
+#     any need for a naming attribute.
+#
+# SAME-PAIR EXAMPLE (``GameSession`` has THREE FKs to ``Scene``):
+#   FK field ``currentSceneId``               → find_game_sessions_by_current_scene
+#   FK field ``lastOpeningNarrativeSceneId``  → find_game_sessions_by_last_opening_narrative_scene
+#   FK field ``transitioningFromSceneId``     → find_game_sessions_by_transitioning_from_scene
+# Three distinct finders — no collision.
+# ---------------------------------------------------------------------------
+
+
+def _pluralize(name: str) -> str:
+    """Trivial cross-port pluralization (matches the TS ``pluralize`` /
+    ``MetaSource._pluralize``), applied to a PascalCase entity name BEFORE
+    snake-casing (``GameSession`` → ``GameSessions``)."""
+    if not name:
+        return name
+    lower = name.lower()
+    if lower.endswith(("s", "x", "z", "ch", "sh")):
+        return name + "es"
+    if len(name) >= 2 and lower[-1] == "y" and lower[-2] not in "aeiou":
+        return name[:-1] + "ies"
+    return name + "s"
+
+
+def reverse_finder_fk_segment(fk_field_name: str) -> str:
+    """Lower an FK field name to the ``<fk_segment>`` of a reverse finder name:
+    snake_case the field, then drop a single trailing ``_id`` if present.
+    E.g. ``currentSceneId`` → ``current_scene``, ``authorId`` → ``author``,
+    ``scene`` → ``scene``."""
+    snake = snake_case(fk_field_name)
+    # Drop a single trailing "_id" (but not a bare "id" — that would yield "").
+    if len(snake) > 3 and snake.endswith("_id"):
+        return snake[:-3]
+    return snake
+
+
+def reverse_finder_fn(source_entity_name: str, fk_field_name: str) -> str:
+    """Reverse single-value finder name: ``find_<e_plural>_by_<fk_segment>``."""
+    e_plural = snake_case(_pluralize(source_entity_name))
+    return f"find_{e_plural}_by_{reverse_finder_fk_segment(fk_field_name)}"
+
+
+def reverse_finder_in_fn(source_entity_name: str, fk_field_name: str) -> str:
+    """Reverse batched finder name: ``find_<e_plural>_by_<fk_segment>_in``."""
+    return f"{reverse_finder_fn(source_entity_name, fk_field_name)}_in"

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

@@ -32,7 +32,10 @@
 """
 from __future__ import annotations
 
+from dataclasses import dataclass
+
 from metaobjects.apidocs.naming import plural_lowercase as _plural_lowercase
+from metaobjects.apidocs.naming import reverse_finder_fn, reverse_finder_in_fn
 from metaobjects.apidocs.naming import snake_case as _snake_case
 from metaobjects.codegen.constants import generated_header
 from metaobjects.codegen.format import ruff_format
@@ -46,10 +49,15 @@
 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
+from metaobjects.meta.core.identity.identity_constants import (
+    IDENTITY_ATTR_FIELDS,
+    IDENTITY_REFERENCE_ATTR_REFERENCES,
+    IDENTITY_SUBTYPE_REFERENCE,
+)
 from metaobjects.meta.core.object.meta_object import MetaObject
 from metaobjects.meta.persistence.source.meta_source import MetaSource
 from metaobjects.meta.persistence.source.source_constants import SOURCE_KIND_TABLE
-from metaobjects.shared.base_types import TYPE_SOURCE
+from metaobjects.shared.base_types import TYPE_IDENTITY, TYPE_SOURCE
 from metaobjects.shared.separators import PACKAGE_SEP
 
 
@@ -75,6 +83,43 @@ def _scalar_fields(entity: MetaObject) -> list[MetaField]:
     return [f for f in entity.fields() if f.sub_type != fc.FIELD_SUBTYPE_OBJECT]
 
 
+@dataclass(frozen=True)
+class ReverseFk:
+    """One FK an entity ``E`` holds (ADR-0038): the FK FIELD name on ``E`` and the
+    bare target entity (``T``) it references. Drives the reverse finder pair on
+    ``E``'s repository so ``T`` can navigate to its referencing ``E`` rows."""
+
+    fk_field: str
+    target_entity: str
+
+
+def reverse_fks_for(entity: MetaObject) -> list[ReverseFk]:
+    """The entity's OWN ``identity.reference`` FKs, in declaration order — the
+    cross-port-canonical source for the reverse-finder pair (mirrors the TS
+    ``reverseFksFor``). Each reference contributes one FK field + target entity;
+    malformed references (no ``@fields`` / no ``@references``) are skipped."""
+    out: list[ReverseFk] = []
+    for c in entity.own_children():
+        if c.type != TYPE_IDENTITY or c.sub_type != IDENTITY_SUBTYPE_REFERENCE:
+            continue
+        fields = c.attr(IDENTITY_ATTR_FIELDS)
+        fk_field: str | None = None
+        if isinstance(fields, (list, tuple)) and fields and isinstance(fields[0], str):
+            fk_field = fields[0]
+        elif isinstance(fields, str) and fields:
+            fk_field = fields.split(",")[0].strip() or None
+        references = c.attr(IDENTITY_REFERENCE_ATTR_REFERENCES)
+        target = (
+            references[references.rfind(PACKAGE_SEP) + len(PACKAGE_SEP):]
+            if isinstance(references, str) and PACKAGE_SEP in references
+            else references
+        )
+        if not fk_field or not isinstance(target, str) or not target:
+            continue
+        out.append(ReverseFk(fk_field=fk_field, target_entity=target))
+    return out
+
+
 class RouterGenerator:
     """``object.entity`` + ``source.rdb @kind="table"`` → one
     ``<entity_snake>_router.py`` per writable entity (FastAPI ``APIRouter``).
@@ -88,6 +133,8 @@ class RouterGenerator:
 
     * ``_emit_repository_protocol(repo_class, m2m)`` — the consumer-implemented
       ``Repository`` ``Protocol`` block (CRUD finders + M:N ``find_related_*``).
+    * ``_emit_reverse_finders(entity)`` — the ADR-0038 reverse-FK finder pair
+      (``find_<e_plural>_by_<fk_segment>`` + ``…_in``) appended to the ``Protocol``.
     * ``_emit_route_handler(name, ...)`` — the CRUD route handlers (list / get /
       create / update / delete), keyed by ``name``.
     * ``_emit_m2m_route(d, snake, pk_param, repo_class)`` — one M:N traversal route.
@@ -127,6 +174,28 @@ def _emit_repository_protocol(
             )
         return lines
 
+    def _emit_reverse_finders(self, entity: MetaObject) -> list[str]:
+        """ADR-0038 reverse-relationship finders for the repository ``Protocol`` — for
+        each FK this entity (``E``) holds (``identity.reference``), a single-value
+        ``find_<e_plural>_by_<fk_segment>`` + a batched (anti-N+1) ``…_in`` finder.
+
+        Each is a framework-free single query (``WHERE <fk> = ?`` / ``WHERE <fk> IN (…)``)
+        returning ``list[Any]`` (the ``E`` rows matching a given target id) — NOT a lazy
+        ORM collection (ADR-0038). The name derives from the FK FIELD (unique within the
+        entity), so same-pair FKs yield distinct finders with no collision. Returns
+        ``Protocol``-body lines (each already 4-space indented). Override to customize."""
+        lines: list[str] = []
+        entity_name = entity.name
+        for rfk in reverse_fks_for(entity):
+            single = reverse_finder_fn(entity_name, rfk.fk_field)
+            batched = reverse_finder_in_fn(entity_name, rfk.fk_field)
+            arg = _snake_case(rfk.fk_field)
+            lines.append(f"    def {single}(self, {arg}: Any) -> list[Any]: ...")
+            lines.append(
+                f"    def {batched}(self, {arg}_values: list[Any]) -> list[Any]: ..."
+            )
+        return lines
+
     def _emit_route_handler(
         self,
         name: str,
@@ -538,7 +607,9 @@ def render_router(
         parts.append("    return _SortClause(field=parts[0], direction=direction)")
         parts.append("")
         parts.append("")
-        parts.extend(self._emit_repository_protocol(repo_class, m2m))
+        proto_lines = self._emit_repository_protocol(repo_class, m2m)
+        proto_lines.extend(self._emit_reverse_finders(entity))
+        parts.extend(proto_lines)
         parts.append("")
         parts.append("")
         parts.append(f"def get_repository() -> {repo_class}:")