nativegate 0.1.0__py3-none-any.whl

nativegate/generators/python_pkg_gen.py

@@ -0,0 +1,1164 @@
+"""Generated Python package + FastAPI service layer (design.md sections 10, 12)."""
+
+from __future__ import annotations
+
+import dataclasses
+
+from ..ir import (
+    FunctionDef,
+    ModuleIR,
+    Parameter,
+    python_identifier,
+    size_pairings as _size_pairings,
+)
+from . import mcp_gen
+from .error_gen import ERROR_HANDLER_IMPORTS, generate_error_handler
+
+
+def _py(name: str) -> str:
+    """The Python spelling of a native name (B4).
+
+    Only the *Python* identifier changes. The HTTP route and the attribute
+    looked up on the native extension keep the original spelling, so escaping
+    a name never moves the wire contract or breaks the symbol lookup.
+    """
+    return python_identifier(name)
+
+
+def _attr(target: str, native_name: str) -> str:
+    """`target.native_name`, falling back to getattr for a Python keyword.
+
+    `native.lambda` is a SyntaxError even though the pybind11/f2py attribute is
+    genuinely called `lambda`, so the *access* has to be spelled differently
+    while still naming the original attribute.
+    """
+    if _py(native_name) == native_name:
+        return f"{target}.{native_name}"
+    return f'getattr({target}, "{native_name}")'
+
+
+class _EndpointNames:
+    """Unique (route, function name) pairs for the endpoints of one router (A5).
+
+    C++ overloads share a name, so two `viscosity` overloads previously emitted
+    two `def viscosity(...)` and two `@router.post("/viscosity")` in one module:
+    the second def shadowed the first and FastAPI dispatched the first route, so
+    one overload was unreachable with no warning.
+
+    Chosen fix: keep one endpoint per overload and disambiguate the later ones
+    with a numeric suffix (`/viscosity_2`, `def viscosity_2`). Merging the
+    overloads into a single endpoint with optional parameters was the
+    alternative, but it cannot express two overloads that differ only in
+    argument *type*, and it would silently pick an overload at request time
+    based on which fields happened to be present — every overload stays
+    individually addressable this way instead.
+    """
+
+    def __init__(self, service_name: str = "") -> None:
+        # `_unexposed` is taken by the generated introspection route, so a
+        # native symbol of that name gets the suffix instead of shadowing it.
+        self._used: set[str] = {"_unexposed"}
+        self._service = service_name
+        # Issued operationIds, and the route each was issued for: the id is a
+        # lossy function of the route (see operation_id), so uniqueness has to
+        # be tracked rather than derived, and a repeat call for the same route
+        # must return the same id rather than allocating a new suffix.
+        self._used_operation_ids: set[str] = set()
+        self._operation_ids: dict[str, str] = {}
+
+    def take(self, native_name: str) -> tuple[str, str]:
+        """Return (route path segment, Python function base name)."""
+        base = _py(native_name)
+        route, name = native_name, base
+        counter = 1
+        while name in self._used:
+            counter += 1
+            route, name = f"{native_name}_{counter}", f"{base}_{counter}"
+        self._used.add(name)
+        return route, name
+
+    def operation_id(self, route: str) -> str:
+        """The OpenAPI operationId for a route, qualified by service name.
+
+        Two separate constraints shape this, both measured rather than assumed.
+
+        **Uniqueness.** OperationIds must be unique across an OpenAPI
+        *document*, and the same router is served by two documents: the
+        service's own app, and a gateway that mounts several services at once.
+        Unqualified ids collide in the gateway — certainly on `_unexposed`,
+        which every service has, and on any symbol name two services happen to
+        share. FastAPI answers a duplicate with a warning and an OpenAPI
+        document that client generators and FastMCP both mis-handle, so the id
+        carries the service name. It is also the MCP tool name, where the
+        prefix earns its keep a second time: `pvt_solution_gor` tells the model
+        which service it is calling, which a bare `solution_gor` does not.
+
+        **No double underscores.** FastMCP TRUNCATES a tool name at `__` and
+        strips leading underscores: measured against fastmcp 3.4.7,
+        `svc__unexposed` becomes the tool `svc`, and `svc_a__b` becomes
+        `svc_a`. So `<service>_` + `_unexposed` would name the introspection
+        tool after the service itself, and any two native symbols differing
+        only after a `__` would collapse onto one tool name — silently making
+        one of them uncallable. Underscore runs are therefore collapsed before
+        the id is issued, and the result is de-duplicated with a numeric
+        suffix so collapsing can never merge two distinct routes.
+        """
+        if route in self._operation_ids:
+            return self._operation_ids[route]
+        base = f"{self._service}_{route}" if self._service else route
+        # Collapse runs of underscores and trim the ends: what survives here is
+        # exactly what FastMCP will use, so the id and the tool name agree.
+        candidate = "_".join(part for part in base.split("_") if part) or "endpoint"
+        unique, counter = candidate, 1
+        while unique in self._used_operation_ids:
+            counter += 1
+            unique = f"{candidate}_{counter}"
+        self._used_operation_ids.add(unique)
+        self._operation_ids[route] = unique
+        return unique
+
+
+def _route(route: str, names: "_EndpointNames") -> str:
+    """A POST decorator carrying an explicit `operation_id` (generators/mcp_gen.py).
+
+    The operation_id is the service name plus the NATIVE symbol name — the
+    route's own spelling, not the escaped Python one, so it matches the rest of
+    the wire contract. See _EndpointNames.operation_id for why it is qualified.
+
+    It is not cosmetic. FastMCP names each generated MCP tool after the route's
+    operationId, and FastAPI's default is `<function>_<path>_<method>`: without
+    this, `solution_gor` reaches the model as
+    `solution_gor_endpoint_solution_gor_post`. It also gives the OpenAPI schema
+    stable operation ids, which is what client generators key off.
+    """
+    return f'@router.post("/{route}", operation_id="{names.operation_id(route)}")'
+
+
+# A docstring body we are willing to paste into a `"""..."""` literal as-is.
+#
+# Deliberately strict, because the text on the other side comes from a native
+# source file nobody vetted: a `"""` closes the literal early and turns the
+# rest of a C++ comment into executable Python, and a trailing backslash
+# escapes the closing quotes so the literal swallows the code after it. Both
+# are ordinary things to find in a real header (`\` ends a line in a macro, and
+# Doxygen examples quote Python), so this is a real injection channel and not a
+# hypothetical one. Anything failing this test is emitted via repr() instead.
+_DOCSTRING_CONTROL = ("\r", "\x00")
+
+
+def _breaks_a_docstring(text: str) -> bool:
+    """True when `text` cannot be pasted between triple double-quotes as-is.
+
+    Precise rather than merely conservative, because the fallback is a
+    single-line repr() and a 20-line Fortran header rendered that way is
+    genuinely hard to read in a file people debug even though they may not
+    edit it.
+
+    What actually breaks the literal, and nothing else:
+
+      * `\"\"\"` anywhere — closes it early, and what follows becomes code;
+      * a TRAILING `\"` — it abuts the closing quotes to make four, ending the
+        literal one character early and opening another string. A quote
+        anywhere else is harmless: `\"pressure\"` mid-prose is ordinary text to
+        Python, and rejecting it cost readability for nothing;
+      * any backslash — `\\N{`, a truncated `\\x`, or a trailing one escaping
+        the closing quotes. Real sources are full of `\\param` and `C:\\logs\\`;
+      * NUL and carriage return, less breakage than a way to make generated
+        files render and diff badly.
+    """
+    return (
+        '"""' in text
+        or text.endswith('"')
+        or "\\" in text
+        or any(c in text for c in _DOCSTRING_CONTROL)
+    )
+
+
+def _docstring_literal(text: str) -> str:
+    """`text` as a Python string literal that is safe to use as a docstring.
+
+    Two shapes, chosen per text rather than one compromise:
+
+    * the common case — plain prose — becomes a readable `\"\"\"...\"\"\"` block,
+      because generated code nobody may hand-edit should still be legible to
+      whoever has to debug it;
+    * anything `_breaks_a_docstring` rejects becomes `repr(text)`, a
+      single-line literal Python itself guarantees is correctly escaped. It is
+      uglier, and that is the right trade: the alternative is hand-rolled
+      escaping of adversarial input, which is how a generator starts emitting
+      code that does not parse — or worse, parses.
+    """
+    if _breaks_a_docstring(text):
+        return repr(text)
+    return f'"""{text}"""'
+
+
+def _docstring(summary: str, doc: str | None = None) -> list[str]:
+    """The endpoint's docstring: the native source's own words, then ours.
+
+    FastAPI publishes this as the route's OpenAPI `description`, which is what
+    FastMCP hands the model as the MCP tool description (generators/mcp_gen.py).
+    With no docstring FastMCP falls back to a title-cased function name
+    ("Solution Gor Endpoint"), which tells the model nothing about the routine —
+    so how well a model calls native code depends directly on this text.
+
+    `doc` is the documentation the parser recovered from the declaration itself
+    (ROADMAP 3.4): a Doxygen block over a C++ prototype, the comment header on a
+    Fortran subroutine. It is used VERBATIM. nativegate does not paraphrase it,
+    because a plausible-sounding paraphrase of a numerical routine's contract is
+    worse than no description at all, and legacy headers do carry stale
+    comments — passing them through unchanged at least keeps the staleness
+    attributable to the source.
+
+    `summary` is nativegate's own one-line statement of what the endpoint does,
+    and is always emitted. It survives even when `doc` is present because the
+    native comment rarely says which symbol it belongs to, and the model needs
+    that to reason about a call it is about to make.
+    """
+    if not doc or not doc.strip():
+        return [f"    {_docstring_literal(summary)}"]
+
+    # Indented to sit inside the endpoint function. The native text is
+    # re-indented line by line rather than pasted as one blob, so a multi-line
+    # comment does not emit a docstring whose continuation lines sit at column
+    # zero — that parses, but it reads as though the function body ended.
+    body = "\n".join(
+        f"    {line}".rstrip() for line in f"{doc.strip()}\n\n{summary}".splitlines()
+    ).strip()
+    literal = _docstring_literal(body)
+    if literal.startswith('"""'):
+        # Closing quotes on their own line, PEP 257's shape for a multi-line
+        # docstring, and the reason the body was re-indented above.
+        return [f'    """{body}', '    """'] if "\n" in body else [f"    {literal}"]
+    return [f"    {literal}"]
+
+
+def _native_module_symbol(module: ModuleIR) -> str:
+    # cpp compiles one pybind11 extension named "<module>_cpp" (section 7);
+    # f2py names the extension after the Fortran module directly (section 8).
+    return f"{module.name}_cpp" if module.language == "cpp" else module.name
+
+
+def generate_init_py(module: ModuleIR) -> str:
+    module_symbol = _native_module_symbol(module)
+    # Structs are re-exported alongside classes: a method returning one is
+    # useless if the caller can't name the type to annotate or construct it.
+    names = (
+        [struct.name for struct in module.structs]
+        + [cls.name for cls in module.classes]
+        + [fn.name for fn in module.functions]
+    )
+    # __all__ lists the names this package actually binds, which are the escaped
+    # Python spellings — `__all__ = ["lambda"]` would name something unimportable.
+    all_list = ", ".join(f'"{_py(n)}"' for n in names)
+
+    if module.language == "fortran" and any(fn.fortran_module for fn in module.functions):
+        # Routines declared inside `module X ... end module X` come back from
+        # f2py as attributes of a nested `<module_symbol>.<X>` fortran object,
+        # not top-level names — re-export them so callers still get the flat
+        # `from physics import calculate_pressure` design.md promises.
+        #
+        # Resolved per routine, not per service: a modern F90 facade over
+        # fixed-form F77 decks has module-scoped and top-level routines in the
+        # same build, and that is the normal shape of a migration in progress.
+        # The attribute path uses the name f2py actually created (lower case,
+        # original spelling); only the local binding is escaped for Python.
+        rebindings = "\n".join(
+            f"{_py(fn.name)} = "
+            + (
+                _attr(
+                    _attr("_native", fn.fortran_module),
+                    (fn.cpp_name or fn.name).lower(),
+                )
+                if fn.fortran_module
+                else _attr("_native", (fn.cpp_name or fn.name).lower())
+            )
+            for fn in module.functions
+        )
+        return (
+            "# Generated by nativegate. Do not edit by hand — re-run `ngate generate`.\n"
+            f"from ._native import {module_symbol} as _native\n\n"
+            f"{rebindings}\n\n"
+            f"__all__ = [{all_list}]\n"
+        )
+
+    if module.language == "fortran":
+        # Fortran is case-insensitive and f2py always emits lowercase symbols,
+        # but legacy sources (and therefore nativegate.yaml) spell routines in
+        # upper case. Alias so `PVTINI` in config keeps working while the
+        # import targets the symbol that actually exists.
+        native_names = {name: name.lower() for name in names}
+    else:
+        native_names = {name: name for name in names}
+
+    # A native symbol whose own spelling is a Python keyword cannot appear in an
+    # import statement at all (`from m import lambda as lambda_` is a
+    # SyntaxError), so it is fetched by getattr from the module object instead.
+    importable = [
+        (native, _py(name))
+        for name, native in native_names.items()
+        if _py(native) == native
+    ]
+    by_getattr = [
+        (native, _py(name))
+        for name, native in native_names.items()
+        if _py(native) != native
+    ]
+
+    lines = ["# Generated by nativegate. Do not edit by hand — re-run `ngate generate`."]
+    if not names:
+        # `from ._native.svc import` with nothing after it is a SyntaxError.
+        # The CLI already refuses an empty module, but a generator must not be
+        # able to emit an unparsable file for any IR it is handed.
+        lines.append("# Nothing exposed — check `expose:` in nativegate.yaml.")
+    elif by_getattr:
+        lines.append(f"from ._native import {module_symbol} as _native")
+        if importable:
+            imports = ", ".join(
+                f"{native} as {alias}" if native != alias else native
+                for native, alias in importable
+            )
+            lines.append(f"from ._native.{module_symbol} import {imports}")
+        for native, alias in by_getattr:
+            lines.append(f'{alias} = getattr(_native, "{native}")')
+    else:
+        imports = ", ".join(
+            f"{native} as {alias}" if native != alias else native
+            for native, alias in importable
+        )
+        lines.append(f"from ._native.{module_symbol} import {imports}")
+
+    lines.append("")
+    lines.append(f"__all__ = [{all_list}]")
+    return "\n".join(lines) + "\n"
+
+
+# --- serialising native calls (COMMON-block safety) ----------------------
+
+# Why this exists, in the generated file itself: a maintainer who deletes the
+# lock to "fix throughput" reintroduces silently wrong numbers, so the reason
+# has to travel with the code and not only with the docs.
+NATIVE_LOCK_COMMENT = [
+    "# Every native call below is serialised through this one process-wide lock.",
+    "#",
+    "# Fortran COMMON blocks are process-global storage, not per-call state. A",
+    "# routine like PVTINI writes COMMON /FLUID/ and a later call to PVTRS,",
+    "# PVTBO or PVTVIS reads it back — the header's own contract is \"CALL",
+    "# PVTSET(P) THEN USE THE COMMON\". FastAPI runs synchronous `def` endpoints",
+    "# in a threadpool, so without this lock two requests configuring different",
+    "# fluids interleave their writes and reads in the SAME COMMON block and",
+    "# each caller gets numbers computed from the other caller's fluid. Nothing",
+    "# raises, nothing logs; the answers are just wrong.",
+    "#",
+    "# Per-request objects cannot fix this the way they fix a stateful C++ class:",
+    "# COMMON is reachable from every instance because it belongs to the process.",
+    "#",
+    "# DO NOT REMOVE THIS TO IMPROVE THROUGHPUT. It caps native execution at one",
+    "# concurrent call per process on purpose. The supported ways to go faster are",
+    "# more processes, or an API reshaped so a configure+read pair is one call.",
+    "#",
+    "# RLock, not Lock: if one generated endpoint is ever changed to call another,",
+    "# a plain Lock would deadlock the request against itself.",
+]
+
+
+# --- input bounds (ROADMAP 2.3) -----------------------------------------
+
+# The placeholder extent. `ir.Parameter` records *that* an argument is an array
+# but not how long it may be — real extents need the fparser2 front end (1.4).
+# Until then every generated array endpoint shares one cap, overridable per
+# deployment through the environment without regenerating.
+DEFAULT_MAX_ARRAY_ITEMS = 65536
+
+ARRAY_CAP_COMMENT = [
+    "# Maximum number of elements accepted in any array argument of any endpoint.",
+    "#",
+    "# PLACEHOLDER. nativegate does not yet know the real extent of a native array",
+    "# argument — the IR records that a parameter IS an array, not how long the",
+    "# routine expects it to be. Recovering the declared extent needs the fparser2",
+    "# front end (ROADMAP 1.4); until then one configurable cap stands in for all",
+    "# of them, so an unbounded request body cannot exhaust this worker's memory.",
+    "# Pydantic rejects an oversized list during request validation, so the caller",
+    "# gets a 422 and the array is never materialised for the native call.",
+    "#",
+    "# Raise it for a service with genuinely large inputs; do not remove it.",
+    f'MAX_ARRAY_ITEMS = int(os.environ.get("NATIVEGATE_MAX_ARRAY_ITEMS", "{DEFAULT_MAX_ARRAY_ITEMS}"))',
+]
+
+
+# Integer-name shapes that unambiguously describe an array `x`: n, nx, n_x,
+# num_x, len_x, size_x, count_x, x_n, x_len, x_size, x_count. Anything else is
+# not paired — a wrong pairing rejects valid calls, which is worse than the
+# status quo for that routine.
+def _size_guard_lines(pairings: list[tuple[str, str]]) -> list[str]:
+    """Reject a size/array mismatch before the value reaches native code."""
+    lines: list[str] = []
+    for int_name, array_name in pairings:
+        lines.append(f"    if {int_name} != len({array_name}):")
+        lines.append("        raise HTTPException(")
+        lines.append("            status_code=422,")
+        lines.append(
+            f'            detail=f"{int_name} ({{{int_name}}}) must equal '
+            f'len({array_name}) ({{len({array_name})}}): the native routine '
+            f'uses {int_name} as the extent of {array_name} and would index '
+            'past the end of the buffer.",'
+        )
+        lines.append("        )")
+    return lines
+
+
+def _array_annotation(inner: str) -> str:
+    return f"Annotated[list[{inner}], Field(max_length=MAX_ARRAY_ITEMS)]"
+
+
+def _serialised(body_lines: list[str]) -> list[str]:
+    """Indent `body_lines` under `with _NATIVE_LOCK:`.
+
+    Only the native call itself belongs inside the lock. Argument marshalling
+    and JSON shaping touch no COMMON storage, and holding the lock across them
+    would lengthen the critical section for no correctness gain.
+    """
+    return ["    with _NATIVE_LOCK:"] + [f"    {line}" for line in body_lines]
+
+
+def _endpoint_for_function(
+    fn: FunctionDef,
+    call_expr: str,
+    names: "_EndpointNames | None" = None,
+    serialise: bool = False,
+) -> list[str]:
+    """One FastAPI endpoint for one native routine.
+
+    Intent decides both halves of the signature. f2py drops `intent(out)`
+    arguments from the call and returns them instead, so an endpoint that
+    still accepted them would pass too many arguments; and `intent(in,out)`
+    arguments are both passed and returned. Getting this wrong is how a
+    Fortran routine's results end up discarded — the call succeeds and the
+    answer goes nowhere.
+    """
+    names = names or _EndpointNames()
+    route, py_name = names.take(fn.name)
+
+    # Every parameter that becomes a Python identifier is escaped first (B4);
+    # the call into the native routine is positional, so the values still land
+    # on the right arguments.
+    parameters = [_renamed(p, _py(p.name)) for p in fn.parameters]
+    # intent(out) is supplied by Fortran, not by the caller.
+    inputs = [p for p in parameters if p.intent != "out"]
+    outputs = [p for p in parameters if p.intent != "in"]
+
+    array_inputs = [p for p in inputs if p.is_array]
+    scalar_inputs = [p for p in inputs if not p.is_array]
+
+    sig_parts = [f"{p.name}: {p.type}" for p in scalar_inputs] + [
+        f"{p.name}: {_array_annotation(p.type)}" for p in array_inputs
+    ]
+    # The endpoint function shares fn.name with the imported native symbol
+    # (see call_expr's alias in generate_service_py) — using fn.name here as
+    # well would shadow the import and turn every call into infinite self-recursion.
+    lines = [_route(route, names), f"def {py_name}_endpoint({', '.join(sig_parts)}):"]
+    call_args = [p.name for p in inputs]
+
+    kind = "subroutine" if fn.is_subroutine else "routine"
+    body_lines = _docstring(f"Call the native {kind} `{fn.name}`.", fn.doc)
+
+    # Checked against the *list* the request supplied, before it is turned into
+    # a numpy buffer and before the native call.
+    body_lines += _size_guard_lines(_size_pairings(inputs))
+    for p in array_inputs:
+        body_lines.append(f"    {p.name} = np.array({p.name}, dtype=np.float64)")
+
+    call = f"{call_expr}({', '.join(call_args)})"
+
+    def _as_json(param) -> str:
+        if param.is_array:
+            return f"{param.name}.tolist()"
+        if param.type == "str":
+            # f2py hands CHARACTER outputs back as BYTES, blank-padded to the
+            # declared length. Bytes are not JSON, and the padding is Fortran
+            # bookkeeping, not data.
+            return f"_n2p_text({param.name})"
+        return param.name
+
+    # The call is kept separate from the return so it — and only it — can be
+    # wrapped in the COMMON-block lock below.
+    if fn.is_subroutine:
+        if not outputs:
+            call_lines = [f"    {call}"]
+            return_line = '    return {"ok": True}'
+        elif len(outputs) == 1:
+            call_lines = [f"    {outputs[0].name} = {call}"]
+            return_line = f'    return {{"{outputs[0].name}": {_as_json(outputs[0])}}}'
+        else:
+            targets = ", ".join(p.name for p in outputs)
+            call_lines = [f"    {targets} = {call}"]
+            result_expr = ", ".join(f'"{p.name}": {_as_json(p)}' for p in outputs)
+            return_line = f"    return {{{result_expr}}}"
+    elif outputs:
+        # A FUNCTION with output arguments: f2py returns the result first,
+        # then each output argument, in declaration order.
+        targets = ", ".join(["result"] + [p.name for p in outputs])
+        call_lines = [f"    {targets} = {call}"]
+        result_expr = ", ".join(
+            ['"result": result'] + [f'"{p.name}": {_as_json(p)}' for p in outputs]
+        )
+        return_line = f"    return {{{result_expr}}}"
+    elif serialise:
+        # Inlining the call into the return would put JSON shaping inside the
+        # lock, so the result is named first.
+        call_lines = [f"    result = {call}"]
+        return_line = '    return {"result": result}'
+    else:
+        call_lines = []
+        return_line = f'    return {{"result": {call}}}'
+
+    if serialise and call_lines:
+        call_lines = _serialised(call_lines)
+    body_lines.extend(call_lines)
+    body_lines.append(return_line)
+
+    return [lines[0], lines[1], *body_lines, ""]
+
+
+def generate_router_py(module: ModuleIR, service_name: str) -> str:
+    """The endpoints as a mountable APIRouter, deliberately WITHOUT a prefix.
+
+    Keeping the prefix out of the router is what lets one generated service
+    serve two deployment topologies from identical code: standalone (its own
+    image, its own FastAPI app, paths at `/circle_area`) and composed (many
+    services mounted into one gateway app under `/demo/circle_area`). The
+    mounting side chooses the prefix — see generators/gateway_gen.py.
+
+    Three rules here exist because breaking them produced services that
+    *imported* wrongly rather than failing a build:
+
+    * an instance is created **inside** each endpoint, not at module scope.
+      A module-scope `sim = Simulator()` is one shared mutable object for
+      every concurrent request, and for a class with no default constructor
+      it is a TypeError at import — the service never starts;
+    * a struct crossing the boundary is converted through a Pydantic model.
+      Returning the pybind11 object gets a 500 from the JSON encoder at
+      request time, with the class bound perfectly well underneath;
+    * a signature nativegate cannot serialise (a bound *class* as a parameter
+      or return) gets no endpoint and a comment saying why, because FastAPI
+      raises on an unknown annotation when the router is registered — again,
+      at import.
+    """
+    structs = {struct.name: struct for struct in module.structs}
+    class_names = {cls.name for cls in module.classes}
+
+    # Does any endpoint accept an array from the request? Includes class
+    # constructor and method arguments, not only free functions.
+    endpoint_params = [p for fn in module.functions for p in fn.parameters]
+    for cls in module.classes:
+        for ctor in cls.constructors:
+            endpoint_params.extend(ctor)
+        for method in cls.methods:
+            endpoint_params.extend(method.parameters)
+    needs_bounds = any(p.is_array for p in endpoint_params)
+
+    # Fortran only. A C++ service already builds a fresh instance per request
+    # (see below), and a C++ free function has no equivalent of COMMON unless
+    # it uses file-scope statics — which the parser cannot see, so a lock there
+    # would be a guess that costs every C++ service its concurrency.
+    serialise = module.language == "fortran"
+
+    # The endpoints are built first so the header can import exactly what they
+    # turned out to need — the size guards are emitted only where a pairing is
+    # unambiguous, and an unused `HTTPException` import (or a missing one) would
+    # otherwise depend on re-deriving that decision a second time.
+    endpoint_lines: list[str] = []
+    # One registry for the whole file: a class method and a free function can
+    # collide just as two overloads of one method can (A5).
+    names = _EndpointNames(service_name)
+
+    for cls in module.classes:
+        endpoint_lines.extend(
+            _endpoints_for_class(cls, structs, class_names, names, serialise=serialise)
+        )
+
+    for fn in module.functions:
+        if module.language == "cpp":
+            endpoint_lines.extend(
+                _endpoint_for_cpp_function(fn, structs, class_names, names)
+            )
+        else:
+            endpoint_lines.extend(
+                _endpoint_for_function(fn, _py(fn.name), names, serialise=serialise)
+            )
+
+    needs_http_exception = any("HTTPException(" in line for line in endpoint_lines)
+    # Derived from what was actually EMITTED, not from the IR. Only the Fortran
+    # path marshals arrays through numpy (f2py wants a contiguous buffer);
+    # pybind11 takes a plain list and converts it to std::vector itself. Keying
+    # this off `p.is_array` instead put `import numpy` in every C++ router the
+    # moment std::vector became bindable — and numpy is not a declared
+    # dependency of a C++ service, so the router would fail at import inside
+    # the container while passing every test on a dev machine that has numpy.
+    needs_numpy = any("np." in line for line in endpoint_lines)
+    needs_text_helper = any("_n2p_text(" in line for line in endpoint_lines)
+
+    lines = [
+        "# Generated by nativegate. Do not edit by hand — re-run `ngate generate`.",
+    ]
+    if needs_bounds:
+        lines.append("import os")
+    if serialise:
+        lines.append("import threading")
+    if needs_bounds:
+        lines.append("from typing import Annotated")
+    if needs_numpy:
+        lines.append("import numpy as np")
+    lines.append(
+        "from fastapi import APIRouter, HTTPException"
+        if needs_http_exception
+        else "from fastapi import APIRouter"
+    )
+    pydantic_names = (["BaseModel"] if structs else []) + (
+        ["Field"] if needs_bounds else []
+    )
+    if pydantic_names:
+        lines.append(f"from pydantic import {', '.join(pydantic_names)}")
+    lines.append("")
+
+    # The package re-exports every symbol under its escaped Python name (B4),
+    # so that is what the router imports.
+    imported_names = [
+        _py(name)
+        for name in (
+            [struct.name for struct in module.structs]
+            + [cls.name for cls in module.classes]
+            + [fn.name for fn in module.functions]
+        )
+    ]
+    if imported_names:
+        lines.append(f"from . import {', '.join(imported_names)}")
+    lines.append("")
+
+    if needs_bounds:
+        lines.extend(ARRAY_CAP_COMMENT)
+        lines.append("")
+
+    if needs_text_helper:
+        lines.extend(
+            [
+                "def _n2p_text(value) -> str:",
+                '    """A CHARACTER output as a Python str.',
+                "",
+                "    f2py returns bytes, blank-padded to the declared length —",
+                "    Fortran bookkeeping, not data. Latin-1 because it cannot",
+                "    fail: every byte maps, so a deck that stuffed binary into",
+                "    a CHARACTER still round-trips instead of raising mid-request.",
+                '    """',
+                "    if isinstance(value, (bytes, bytearray)):",
+                '        return value.decode("latin-1").rstrip()',
+                "    return str(value).rstrip()",
+                "",
+                "",
+            ]
+        )
+
+    lines.extend(_struct_models(module, structs))
+
+    if serialise:
+        lines.extend(NATIVE_LOCK_COMMENT)
+        lines.append("_NATIVE_LOCK = threading.RLock()")
+        lines.append("")
+
+    lines.append(f'router = APIRouter(tags=["{service_name}"])')
+    lines.append("")
+
+    lines.extend(_unexposed_route(module, names))
+
+    lines.extend(endpoint_lines)
+
+    return "\n".join(lines).rstrip() + "\n"
+
+
+# --- what the parser refused to bind (ROADMAP 2.4) ----------------------
+
+
+def _unexposed_route(module: ModuleIR, names: "_EndpointNames") -> list[str]:
+    """`GET /_unexposed` — every symbol the parser recognised and refused.
+
+    `ModuleIR.skipped` is how nativegate promises never to mis-bind silently,
+    but until now it only survived as comments in a file inside a container.
+    Serving it makes the refusals part of the running service's contract: a
+    caller who cannot find an endpoint can ask why it is missing.
+
+    The route exists even when nothing was skipped, and returns `{}`. That is
+    the point — an empty mapping means "this build refused nothing", while a
+    404 means "this service was generated before nativegate could tell you".
+    """
+    # Duplicate names are merged rather than silently overwritten: two reasons
+    # for one overloaded symbol are both true and both worth reporting.
+    merged: dict[str, str] = {}
+    for entry in module.skipped:
+        if entry.name in merged:
+            merged[entry.name] = f"{merged[entry.name]}; {entry.reason}"
+        else:
+            merged[entry.name] = entry.reason
+
+    lines = [
+        "# Symbols this build recognised and refused to bind, with the reason.",
+        "#",
+        "# Refusal is nativegate's safety mechanism (a non-const char* output buffer",
+        "# has no length; a pointer return has no ownership; a derived-type Fortran",
+        "# result has no mapping), so the refusals are part of this service's",
+        "# contract and not an implementation detail. An EMPTY mapping means this",
+        "# build refused nothing; a 404 on this route means the service predates",
+        "# the feature and cannot tell you either way.",
+        "_UNEXPOSED: dict[str, str] = {",
+    ]
+    for name, reason in merged.items():
+        lines.append(f"    {name!r}: {reason!r},")
+    lines.append("}")
+    lines.append("")
+    lines.append(
+        '@router.get("/_unexposed", tags=["introspection"], '
+        f'operation_id="{names.operation_id("_unexposed")}")'
+    )
+    # Deliberately NOT `def _unexposed`: the router imports every bound symbol
+    # into this module namespace, so a native routine called `_unexposed` and
+    # the route handler would be the same name and one would silently shadow
+    # the other — the endpoint for that routine would then return this mapping.
+    lines.append("def _nativegate_unexposed() -> dict[str, str]:")
+    lines.append('    """Symbols the parser recognised but refused to bind, and why."""')
+    lines.append("    return _UNEXPOSED")
+    lines.append("")
+    return lines
+
+
+# --- structs over HTTP ---------------------------------------------------
+
+
+def _model_name(struct_name: str) -> str:
+    return f"{_py(struct_name)}Model"
+
+
+def _struct_models(module: ModuleIR, structs: dict) -> list[str]:
+    """A Pydantic model, a parser and a serialiser for each bound struct.
+
+    pybind11 hands Python a real C++ object; FastAPI needs something it can
+    encode. The conversions are explicit rather than a generic `__dict__`
+    walk so a field the IR never bound cannot silently appear in an API
+    response.
+    """
+    lines: list[str] = []
+    for struct in module.structs:
+        lines.append(f"class {_model_name(struct.name)}(BaseModel):")
+        if not struct.fields:
+            lines.append("    pass")
+        for field in struct.fields:
+            # A field whose native name is a Python keyword is escaped on both
+            # sides of the boundary — the model attribute AND the JSON key — so
+            # a request body round-trips through the response unchanged. The
+            # native member is still reached under its original spelling below.
+            lines.append(f"    {_py(field.name)}: {_annotation(field, structs)}")
+        lines.append("")
+        lines.append("")
+
+    for struct in module.structs:
+        # native -> JSON
+        lines.append(f"def _from_{_py(struct.name)}(native) -> dict:")
+        if not struct.fields:
+            lines.append("    return {}")
+        else:
+            items = ", ".join(
+                f'"{_py(f.name)}": {_field_to_json(f, structs)}' for f in struct.fields
+            )
+            lines.append(f"    return {{{items}}}")
+        lines.append("")
+        lines.append("")
+
+        # JSON -> native
+        lines.append(f"def _to_{_py(struct.name)}(model: {_model_name(struct.name)}):")
+        lines.append(f"    native = {_py(struct.name)}()")
+        for field in struct.fields:
+            value = _field_to_native(field, structs)
+            if _py(field.name) == field.name:
+                lines.append(f"    native.{field.name} = {value}")
+            else:
+                lines.append(f'    setattr(native, "{field.name}", {value})')
+        lines.append("    return native")
+        lines.append("")
+        lines.append("")
+
+    return lines
+
+
+def _annotation(param, structs: dict, bounded: bool = False) -> str:
+    """The Python type annotation FastAPI should see for one parameter/field.
+
+    `bounded` is set for endpoint *parameters*, where an array arriving from an
+    untrusted request body carries the MAX_ARRAY_ITEMS cap. Struct model fields
+    are left plain: they are reached through a parameter that already carries
+    the cap on the outer list.
+    """
+    base = _model_name(param.type) if param.type in structs else param.type
+    if not param.is_array:
+        return base
+    return _array_annotation(base) if bounded else f"list[{base}]"
+
+
+def _field_to_json(field, structs: dict) -> str:
+    access = _attr("native", field.name)
+    if field.type in structs:
+        return (
+            f"[_from_{_py(field.type)}(v) for v in {access}]"
+            if field.is_array
+            else f"_from_{_py(field.type)}({access})"
+        )
+    return f"list({access})" if field.is_array else access
+
+
+def _field_to_native(field, structs: dict) -> str:
+    access = f"model.{_py(field.name)}"
+    if field.type in structs:
+        return (
+            f"[_to_{_py(field.type)}(v) for v in {access}]"
+            if field.is_array
+            else f"_to_{_py(field.type)}({access})"
+        )
+    return access
+
+
+def _unserialisable(params, returns: str, structs: dict, class_names: set) -> str | None:
+    """Why this signature cannot be exposed over HTTP, or None if it can.
+
+    A bound class is a live C++ object: there is no JSON that constructs one
+    and none that represents one. It stays available in the Python package —
+    only the HTTP endpoint is impossible.
+    """
+    for param in params:
+        if param.type in class_names and param.type not in structs:
+            return f"parameter '{param.name}' is a bound class ({param.type})"
+    if returns in class_names and returns not in structs:
+        return f"it returns a bound class ({returns})"
+    return None
+
+
+def _call_arguments(params, structs: dict) -> list[str]:
+    return [
+        f"_to_{_py(p.type)}({p.name})"
+        if p.type in structs and not p.is_array
+        else p.name
+        for p in params
+    ]
+
+
+def _wrap_result(expression: str, returns: str, structs: dict) -> str:
+    if returns in structs:
+        return f"_from_{_py(returns)}({expression})"
+    return expression
+
+
+# --- class endpoints -----------------------------------------------------
+
+
+def _constructor_parameters(cls) -> list | None:
+    """The constructor arguments an endpoint must accept, or None if the class
+    cannot be constructed from a request at all.
+
+    A default constructor needs nothing. Otherwise the shortest public
+    constructor is used — it asks the caller for the least, and every
+    constructor of a class builds the same type.
+    """
+    if cls.has_default_constructor:
+        return []
+    if not cls.constructors:
+        return None
+    return min(cls.constructors, key=len)
+
+
+def _endpoints_for_class(
+    cls,
+    structs: dict,
+    class_names: set,
+    names: "_EndpointNames | None" = None,
+    serialise: bool = False,
+) -> list[str]:
+    names = names or _EndpointNames()
+    lines: list[str] = []
+    ctor_params = _constructor_parameters(cls)
+
+    if ctor_params is None and any(not m.is_static for m in cls.methods):
+        lines.append(
+            f"# {cls.name}: no public constructor callable from Python "
+            "(abstract, or all constructors are non-public), so its instance "
+            "methods have no endpoint. It is still exported by the package and "
+            "usable as a base class."
+        )
+        lines.append("")
+
+    for method in cls.methods:
+        if method.is_static:
+            needed_ctor = []
+        elif ctor_params is None:
+            continue
+        else:
+            needed_ctor = ctor_params
+
+        reason = _unserialisable(
+            [*needed_ctor, *method.parameters], method.returns, structs, class_names
+        )
+        if reason is not None:
+            lines.append(f"# {cls.name}.{method.name}: no endpoint — {reason}.")
+            lines.append("")
+            continue
+
+        # A constructor argument sharing a name with a method argument would
+        # be one parameter in the signature and the wrong value in one of the
+        # two calls, so the constructor's copy is renamed. Every name is also
+        # escaped against Python's keywords (B4).
+        method_params = [_renamed(p, _py(p.name)) for p in method.parameters]
+        # Same treatment buffer arguments get on free functions: the length is
+        # read off the array the caller sent, so it is not asked over HTTP,
+        # and a buffer the native code writes through comes back in the
+        # response — the array it wrote into does not outlive the request.
+        buffers = [p for p in method_params if getattr(p, "length_param", None)]
+        length_names = {p.length_param for p in buffers}
+        method_params = [p for p in method_params if p.name not in length_names]
+        mutable_buffers = [p for p in buffers if getattr(p, "is_mutable_buffer", False)]
+        method_names = {p.name for p in method_params}
+        ctor_names = [
+            f"{_py(p.name)}_init" if _py(p.name) in method_names else _py(p.name)
+            for p in needed_ctor
+        ]
+
+        signature = [
+            f"{name}: {_annotation(p, structs, bounded=True)}"
+            for name, p in zip(ctor_names, needed_ctor)
+        ] + [
+            f"{p.name}: {_annotation(p, structs, bounded=True)}" for p in method_params
+        ]
+
+        ctor_args = _call_arguments(
+            [_renamed(p, name) for name, p in zip(ctor_names, needed_ctor)], structs
+        )
+        call_args = _call_arguments(method_params, structs)
+
+        route, py_name = names.take(method.name)
+        lines.append(_route(route, names))
+        lines.append(f"def {py_name}({', '.join(signature)}):")
+        if method.is_static:
+            summary = f"Call the static method `{cls.name}::{method.name}`."
+        else:
+            # Worth stating: the instance is per-request, so an LLM cannot
+            # treat two calls as operating on the same object.
+            summary = (
+                f"Construct a `{cls.name}` and call its `{method.name}` method. "
+                "The instance does not outlive this request."
+            )
+        lines.extend(_docstring(summary))
+        guard = _size_guard_lines(
+            _size_pairings(
+                [_renamed(p, name) for name, p in zip(ctor_names, needed_ctor)]
+                + method_params
+            )
+        )
+        lines.extend(guard)
+        body: list[str] = []
+        for buf in buffers:
+            body.append(
+                f"    {buf.name} = np.array({buf.name}, dtype=np.{_BUFFER_DTYPE[buf.type]})"
+            )
+        if method.is_static:
+            call = f"{_attr(_py(cls.name), method.name)}({', '.join(call_args)})"
+        else:
+            # Per request, not per process: a native class with internal state
+            # shared across concurrent requests is a correctness bug, and a
+            # simulation object is stateful by definition.
+            body.append(f"    instance = {_py(cls.name)}({', '.join(ctor_args)})")
+            call = f"{_attr('instance', method.name)}({', '.join(call_args)})"
+        if mutable_buffers:
+            written = ", ".join(
+                f'"{p.name}": {p.name}.tolist()' for p in mutable_buffers
+            )
+            if method.returns == "None":
+                body.append(f"    {call}")
+                lines.extend(_serialised(body) if serialise else body)
+                lines.append(f"    return {{{written}}}")
+            else:
+                body.append(f"    result = {call}")
+                lines.extend(_serialised(body) if serialise else body)
+                lines.append(
+                    f'    return {{"result": '
+                    f'{_wrap_result("result", method.returns, structs)}, {written}}}'
+                )
+        elif method.returns == "None":
+            body.append(f"    {call}")
+            lines.extend(_serialised(body) if serialise else body)
+            lines.append('    return {"ok": True}')
+        elif serialise:
+            body.append(f"    result = {call}")
+            lines.extend(_serialised(body))
+            lines.append(f'    return {{"result": {_wrap_result("result", method.returns, structs)}}}')
+        else:
+            lines.extend(body)
+            lines.append(
+                f'    return {{"result": {_wrap_result(call, method.returns, structs)}}}'
+            )
+        lines.append("")
+
+    return lines
+
+
+def _renamed(param, name: str):
+    """Copy of a Parameter under a different endpoint-level name."""
+    if not isinstance(param, Parameter):  # pragma: no cover - defensive
+        return Parameter(
+            name=name, type=param.type, is_array=param.is_array, intent=param.intent
+        )
+    return dataclasses.replace(param, name=name)
+
+
+# numpy dtype for a buffer parameter, matching what pybind_gen's lambda
+# demands. A mutable buffer of the wrong dtype is REFUSED by the binding
+# rather than converted, so these two tables have to agree.
+_BUFFER_DTYPE = {"float": "float64", "int": "intc", "bool": "bool_"}
+
+
+def _endpoint_for_cpp_function(
+    fn, structs: dict, class_names: set, names: "_EndpointNames | None" = None
+) -> list[str]:
+    names = names or _EndpointNames()
+    reason = _unserialisable(fn.parameters, fn.returns, structs, class_names)
+    if reason is not None:
+        return [f"# {fn.name}: no endpoint — {reason}.", ""]
+
+    parameters = [_renamed(p, _py(p.name)) for p in fn.parameters]
+
+    # A `T*` bound as a buffer takes its length from the array itself, so the
+    # length argument is not part of the binding's signature and must not be
+    # asked of an HTTP caller either.
+    buffers = [p for p in parameters if getattr(p, "length_param", None)]
+    length_names = {p.length_param for p in buffers}
+    exposed = [p for p in parameters if p.name not in length_names]
+    mutable_buffers = [p for p in buffers if getattr(p, "is_mutable_buffer", False)]
+
+    signature = ", ".join(
+        f"{p.name}: {_annotation(p, structs, bounded=True)}" for p in exposed
+    )
+    call_args = [p.name for p in exposed]
+    call = f"{_py(fn.name)}({', '.join(call_args)})"
+
+    # extern "C" scalars passed by reference: non-const ones are OUTPUTS, and
+    # the binding returns their final values f2py-style — result first, then
+    # each output in declaration order, a bare value when there is only one.
+    # The endpoint unpacks that shape so an output like an error code reaches
+    # the caller instead of dying with the lambda's locals.
+    scalar_outputs = [
+        p.name
+        for p in exposed
+        if getattr(p, "is_scalar_ref", False) and p.intent != "in"
+    ]
+
+    route, py_name = names.take(fn.name)
+    lines = [_route(route, names), f"def {py_name}_endpoint({signature}):"]
+    lines.extend(_docstring(f"Call the native function `{fn.name}`.", fn.doc))
+    if not buffers:
+        lines.extend(_size_guard_lines(_size_pairings(parameters)))
+
+    # The binding wants a real ndarray, and for a mutable buffer specifically a
+    # writable one of the exact dtype — it refuses to convert, because a
+    # converted array is a temporary whose writes are discarded. JSON gives us
+    # a list, so the array is built here with the dtype the binding demands.
+    for buf in buffers:
+        lines.append(
+            f"    {buf.name} = np.array({buf.name}, dtype=np.{_BUFFER_DTYPE[buf.type]})"
+        )
+
+    if scalar_outputs:
+        named = ", ".join(f'"{n}": {n}' for n in scalar_outputs)
+        if fn.returns == "None" and len(scalar_outputs) == 1:
+            lines.append(f"    {scalar_outputs[0]} = {call}")
+            lines.append(f"    return {{{named}}}")
+        elif fn.returns == "None":
+            lines.append(f"    {', '.join(scalar_outputs)} = {call}")
+            lines.append(f"    return {{{named}}}")
+        else:
+            lines.append(f"    result, {', '.join(scalar_outputs)} = {call}")
+            lines.append(f'    return {{"result": result, {named}}}')
+        lines.append("")
+        return lines
+
+    if not mutable_buffers:
+        # Inline, exactly as before: naming an intermediate would churn every
+        # generated router for the benefit of the few that write back.
+        if fn.returns == "None":
+            lines.append(f"    {call}")
+            lines.append('    return {"ok": True}')
+        else:
+            lines.append(
+                f'    return {{"result": {_wrap_result(call, fn.returns, structs)}}}'
+            )
+        lines.append("")
+        return lines
+
+    if fn.returns == "None":
+        lines.append(f"    {call}")
+    else:
+        lines.append(f"    result = {_wrap_result(call, fn.returns, structs)}")
+
+    if mutable_buffers:
+        # Whatever the native call wrote goes back to the caller. Without this
+        # the endpoint would run, return 200, and silently discard the entire
+        # point of an in-place routine — the HTTP-layer version of the
+        # std::vector& trap this codebase refuses at the binding layer.
+        written = ", ".join(f'"{p.name}": {p.name}.tolist()' for p in mutable_buffers)
+        if fn.returns == "None":
+            lines.append(f"    return {{{written}}}")
+        else:
+            lines.append(f'    return {{"result": result, {written}}}')
+    elif fn.returns == "None":
+        lines.append('    return {"ok": True}')
+    else:
+        lines.append('    return {"result": result}')
+    lines.append("")
+    return lines
+
+
+def generate_service_py(service_name: str) -> str:
+    """Standalone app: this service alone, in its own container.
+
+    Thin by design — all the endpoints live in router.py so the exact same
+    code can instead be mounted into a shared gateway.
+
+    The error handler is emitted here AND in the gateway app, from the same
+    generator, because it attaches to an app rather than to a router — see
+    generators/error_gen.py.
+    """
+    error_imports = "\n".join(ERROR_HANDLER_IMPORTS)
+    return f'''# Generated by nativegate. Do not edit by hand — re-run `ngate generate`.
+{error_imports}
+from fastapi import FastAPI, Request
+
+from .middleware import install_middleware, readiness
+from .router import router
+{mcp_gen.MCP_APP_IMPORT}
+
+# `lifespan=` is not optional: FastMCP's streamable-HTTP session manager starts
+# in mcp_app's lifespan, and mounting the app without adopting it fails every
+# tool call at runtime with "task group was not initialized" — at request time,
+# not at startup. See generators/mcp_gen.py.
+app = FastAPI(title="{service_name}", lifespan=mcp_app.lifespan)
+app.include_router(router)
+
+# Auth, rate limiting, body-size limits, request ids and access logging. Called
+# here AND in the gateway app: middleware attaches to an app, and a router
+# mounted into a gateway runs under the gateway's app.
+install_middleware(app, "{service_name}")
+readiness(app, "{service_name}")
+{mcp_gen.mcp_mount_lines()}
+
+
+@app.get("/healthz", tags=["health"])
+def healthz():
+    """Liveness: the process is up and the native extension imported.
+
+    Deliberately NOT readiness — see /readyz. A liveness probe that fails
+    during startup gets the container killed and restarted forever.
+    """
+    return {{"status": "ok", "service": "{service_name}"}}
+{generate_error_handler(service_name)}'''