@adhd/apigen-python-env 0.2.1 → 0.2.3

package/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.2.3 (2026-08-07)
+
+
+### 🩹 Fixes
+
+- **apigen-cli:** restore 2768 files mass-deleted by 0117eb22 (BUG-APIGEN-052)
+
+- **apigen-python:** parent-death watchdog so Python hosts cannot outlive their spawning process (BUG-APIGEN-053)
+
+
+### ❤️  Thank You
+
+- parity-harness-self-test
+- pseudosky
+
+## 0.2.2 (2026-07-30)
+
+
+### 🩹 Fixes
+
+- **nx-build:** release-atomicity test coverage + CPU-guard flakiness + cache-input gap
+
+- **apigen-python-env:** dist copy-plugin hardening alongside cache-input fix
+
+
+### ❤️  Thank You
+
+- pseudosky
+
 ## 0.2.1 (2026-07-27)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhd/apigen-python-env",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "main": "./index.js",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -12,7 +12,7 @@
     "provisioning"
   ],
   "dependencies": {
-    "@adhd/apigen-core-client": "^0.2.1"
+    "@adhd/apigen-core-client": "^0.3.0"
   },
   "publishConfig": {
     "access": "public"

package/python/apigen_python/flask_server.py

@@ -73,6 +73,7 @@ import json
 import sys
 import threading
 import urllib.parse
+from concurrent.futures import ThreadPoolExecutor
 from datetime import datetime
 from decimal import Decimal
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
@@ -92,6 +93,7 @@ if str(_THIS_DIR) not in sys.path:
     sys.path.insert(0, str(_THIS_DIR))
 
 from apigen_python.errors import ApiError, HTTP_STATUS  # noqa: E402
+from apigen_python.parent_watchdog import start_parent_death_watchdog  # noqa: E402
 from apigen_python.runtime import HostRequest, Runtime  # noqa: E402
 from apigen_python.validator import validate, ValidationError  # noqa: E402
 
@@ -278,7 +280,7 @@ class _RouteEntry:
 class _ServerState:
     """Immutable server configuration shared across all request threads."""
 
-    __slots__ = ("namespace", "runtime", "operations", "route_map")
+    __slots__ = ("namespace", "runtime", "operations", "route_map", "route_map_by_op_id")
 
     def __init__(
         self,
@@ -299,6 +301,12 @@ class _ServerState:
         # composition artifact; the Python runtime receives bare params), so
         # no separate schema map is needed alongside this.
         self.route_map: dict[str, _RouteEntry] = {}
+        # (batch-rollout F8) op id -> _RouteEntry, built from the SAME loop
+        # that builds route_map above. `_dispatch_batch` resolves a batch
+        # request's `operation` field (an operation ID, not a URL path) to
+        # its real, dispatchable route entry through this index — `route_map`
+        # alone (keyed by URL path) cannot serve that lookup.
+        self.route_map_by_op_id: dict[str, _RouteEntry] = {}
         for op in operations:
             entry = routes.get(op["id"])
             if entry is None:
@@ -308,7 +316,256 @@ class _ServerState:
                     f"cover every operation extract_module() (phase 1) "
                     f"produced, 1:1."
                 )
-            self.route_map[entry["route"]] = _RouteEntry(op=op, verb=entry["verb"])
+            route_entry = _RouteEntry(op=op, verb=entry["verb"])
+            self.route_map[entry["route"]] = route_entry
+            self.route_map_by_op_id[op["id"]] = route_entry
+
+
+# ---------------------------------------------------------------------------
+# Batch/bulk fan-out (`_batch/<kind>`) — BATCH_0.0.1.md §5, this host's own
+# executor implementation, ported from the design at
+# tmp/apigen-batch-python-design.md (§2.2, corrected per §3.5's architect-
+# review findings F2-F5). This is the Python-idiom equivalent of the TS
+# `invokeBatch` (`apigen-engine-runtime/src/lib/batch.ts`), never a call into
+# it — the target op is dispatched locally, the same way every other route on
+# this server already dispatches, N times, with concurrency/mode/onItemError
+# control.
+# ---------------------------------------------------------------------------
+
+# (F7) Hard cap on requested concurrency — a literal port of the TS
+# constant's VALUE (intentionally duplicated per-host rather than unified
+# into one cross-language source of truth; there is no cross-language
+# constant-sharing mechanism in this repo today — see
+# `apigen-engine-runtime/src/lib/batch.ts:35`'s
+# `export const BATCH_MAX_CONCURRENCY = 32;`).
+BATCH_MAX_CONCURRENCY = 32
+
+# Mirrors `apigen-engine-runtime/src/lib/batch.ts`'s
+# `BATCH_DEFAULT_CONCURRENCY = 4` — the fan-out width used when the request
+# doesn't specify one.
+BATCH_DEFAULT_CONCURRENCY = 4
+
+
+def _not_attempted_reason(mode: str) -> dict[str, Any]:
+    """The per-item rejection reason for an item never attempted because an
+    earlier item aborted the whole batch (F5): a REAL
+    ``ApiError('internal', ...).to_json()``, never a hand-rolled dict with an
+    invented ``'cancelled'`` code that exists in neither ``errors.py``'s
+    taxonomy nor ``apigen-base-errors`` — mirrors TS `invokeBatch`'s own
+    `notAttempted()` mapping (`apigen-engine-runtime/src/lib/batch.ts`)."""
+    if mode == "chained":
+        message = (
+            "batch aborted (mode=chained) — an earlier item failed and this "
+            "item was never attempted"
+        )
+    else:
+        message = (
+            "batch aborted (onItemError=abort) — an earlier item failed and "
+            "this item was never attempted"
+        )
+    return ApiError("internal", message).to_json()
+
+
+def _run_batch_item(
+    state: _ServerState,
+    entry: _RouteEntry,
+    index: int,
+    item: Any,
+    envelope: dict[str, Any],
+) -> dict[str, Any]:
+    """Dispatch ONE batch item through the SAME validate -> decode logical
+    types -> invoke -> encode result pipeline `_ApigenHandler._dispatch`
+    already performs for a real single-op request (F4 — logical-type
+    parity). Never a bypass of `_decode_params`/`pre_validated=True`/
+    `_encode_result`; the only difference from `_dispatch` is that a failure
+    here becomes a per-item `BatchItemResult` instead of an HTTP response.
+    """
+    input_schema: dict[str, Any] = entry.op.get("input", {})
+    try:
+        data = item if isinstance(item, dict) else {}
+
+        # SPEC §6: validate BEFORE dispatch, exactly like the single-op path.
+        if input_schema:
+            try:
+                validate(input_schema, data)
+            except ValidationError as exc:
+                raise ApiError(
+                    "invalid_argument", f"input validation failed: {exc}"
+                ) from exc
+
+        # Schema-driven logical-type decode (Decimal, datetime, ...) — F4.
+        decoded_data = _decode_params(data, input_schema)
+
+        host_req = HostRequest(
+            operation=entry.op,
+            data=decoded_data,
+            envelope=envelope,
+            transport="http",
+            pre_validated=True,
+        )
+        value = state.runtime.invoke_sync(host_req)
+        return {"index": index, "status": "fulfilled", "value": _encode_result(value)}
+    except ApiError as exc:
+        return {"index": index, "status": "rejected", "reason": exc.to_json()}
+    except Exception as exc:  # noqa: BLE001 - must never leak a bare traceback over the wire
+        return {
+            "index": index,
+            "status": "rejected",
+            "reason": ApiError("internal", f"dispatch error: {exc}").to_json(),
+        }
+
+
+def _resolve_batch_concurrency(mode: str, requested: Any, item_count: int) -> int:
+    """Mirror `apigen-engine-runtime/src/lib/batch.ts`'s `resolveConcurrency`:
+    `serial`/`chained` are always width-1 (never reach this — callers only
+    invoke this for `mode == 'parallel'`), a bad/missing request falls back
+    to `BATCH_DEFAULT_CONCURRENCY`, and the result is always clamped to
+    `[1, BATCH_MAX_CONCURRENCY]` and never exceeds the item count (so
+    `ThreadPoolExecutor` is never constructed with `max_workers=0`).
+    """
+    if requested is None or not isinstance(requested, (int, float)) or requested < 1:
+        n = BATCH_DEFAULT_CONCURRENCY
+    else:
+        n = int(requested)
+    n = min(n, BATCH_MAX_CONCURRENCY)
+    return max(1, min(n, max(item_count, 1)))
+
+
+def _dispatch_batch(
+    state: _ServerState, body: dict[str, Any], envelope: dict[str, Any]
+) -> list[dict[str, Any]]:
+    """Fan out `body['items']` to the real operation `body['operation']` —
+    the Python host's OWN executor against BATCH_0.0.1.md §5's wire contract
+    (LEFT column only; this function is never a call into the TS
+    `invokeBatch`). Implements the architect-reviewed design's binding fixes
+    (`tmp/apigen-batch-python-design.md` §3.5):
+
+    - F2: `mode` branching — `parallel` uses a bounded `ThreadPoolExecutor`;
+      `serial`/`chained` use a plain sequential loop; `chained` additionally
+      stops on the first failure regardless of `onItemError`.
+    - F3: `itemTimeoutMs` is rejected upfront (whole-batch `invalid_argument`)
+      — `Runtime.invoke_sync` has no timeout kwarg / cancellation hook, so no
+      partial/best-effort cancellation is offered under the same field name
+      TS uses for real `AbortSignal`-based cancellation.
+    - F4: every item goes through `_run_batch_item`'s real
+      validate/decode/invoke/encode pipeline (logical-type parity with the
+      single-op path); the nested-batch guard checks the `_batch/` ID
+      PREFIX, never `op["kind"] == "batch"` (impossible — `kind` is always
+      the real grouped kind, e.g. `'action'`/`'query'`).
+    - F5: every rejected result's `reason` is a real `ApiError(...).to_json()`
+      using an existing `errors.py` taxonomy code.
+
+    Raises:
+        ApiError: for whole-request-level rejections (bad `operation`,
+            unsupported `itemTimeoutMs`, malformed `items`/`mode`/
+            `onItemError`/`concurrency`) — the caller maps this to a real
+            HTTP 4xx via `_send_error`, the SAME mechanism every other route
+            on this server already uses.
+    """
+    # F3 — reject the WHOLE batch upfront; never a silently-weaker
+    # wait-only guarantee under the same field name TS uses for real
+    # cancellation.
+    if body.get("itemTimeoutMs") is not None:
+        raise ApiError(
+            "invalid_argument",
+            "itemTimeoutMs is not supported by the Python host",
+        )
+
+    target_op_id = body.get("operation")
+    if not isinstance(target_op_id, str) or not target_op_id:
+        raise ApiError(
+            "invalid_argument",
+            '"operation" must be a non-empty string naming the target operation id',
+        )
+    # F4 — the nested-batch guard checks the ID PREFIX (`syntheticOp` always
+    # names batch mounts this way), NOT `op["kind"] == "batch"` (impossible:
+    # `kind` on a real target op is always its real grouped kind, never the
+    # literal string 'batch').
+    if target_op_id.startswith("_batch/"):
+        raise ApiError(
+            "invalid_argument",
+            f"not a real batchable operation: {target_op_id!r} is itself a "
+            "batch mount",
+        )
+    entry = state.route_map_by_op_id.get(target_op_id)
+    if entry is None:
+        raise ApiError(
+            "invalid_argument",
+            f"not a real batchable operation: {target_op_id!r} is not one "
+            "of this server's operations",
+        )
+
+    items = body.get("items")
+    if not isinstance(items, list):
+        raise ApiError("invalid_argument", '"items" must be an array')
+
+    mode = body.get("mode", "parallel")
+    if mode not in ("parallel", "serial", "chained"):
+        raise ApiError(
+            "invalid_argument",
+            '"mode" must be one of "parallel" | "serial" | "chained"',
+        )
+    on_item_error = body.get("onItemError", "continue")
+    if on_item_error not in ("continue", "abort"):
+        raise ApiError(
+            "invalid_argument",
+            '"onItemError" must be one of "continue" | "abort"',
+        )
+    requested_concurrency = body.get("concurrency")
+    if requested_concurrency is not None and not isinstance(requested_concurrency, (int, float)):
+        raise ApiError("invalid_argument", '"concurrency" must be a number')
+
+    results: list[dict[str, Any] | None] = [None] * len(items)
+
+    # F2 — serial/chained: a plain sequential loop, no thread pool at all
+    # (strictly simpler than the parallel path below).
+    if mode in ("serial", "chained"):
+        stop = False
+        for i, item in enumerate(items):
+            if stop:
+                results[i] = {
+                    "index": i,
+                    "status": "rejected",
+                    "reason": _not_attempted_reason(mode),
+                }
+                continue
+            result = _run_batch_item(state, entry, i, item, envelope)
+            results[i] = result
+            if result["status"] == "rejected" and (mode == "chained" or on_item_error == "abort"):
+                stop = True
+        return results  # type: ignore[return-value]
+
+    # F2 — parallel: bounded ThreadPoolExecutor, the idiomatic sync-Python
+    # equivalent of TS's worker-pool scheduler (runtime.invoke is NOT used —
+    # introducing asyncio into this synchronous BaseHTTPRequestHandler server
+    # is out of scope; see the design doc's "Concurrency primitive" note).
+    concurrency = _resolve_batch_concurrency(mode, requested_concurrency, len(items))
+    aborted = threading.Event()
+
+    def run_one(i: int, item: Any) -> None:
+        if aborted.is_set():
+            results[i] = {
+                "index": i,
+                "status": "rejected",
+                "reason": _not_attempted_reason(mode),
+            }
+            return
+        result = _run_batch_item(state, entry, i, item, envelope)
+        results[i] = result
+        if result["status"] == "rejected" and on_item_error == "abort":
+            # Stop starting NEW items once one fails — cannot un-submit
+            # already-running thread-pool work, identical in spirit to TS's
+            # `onItemError:'abort'` behavior (in-flight items are allowed to
+            # finish; they are not force-cancelled).
+            aborted.set()
+
+    if items:
+        with ThreadPoolExecutor(max_workers=concurrency) as pool:
+            futures = [pool.submit(run_one, i, item) for i, item in enumerate(items)]
+            for f in futures:
+                f.result()  # propagate any genuinely unexpected exception loudly
+
+    return results  # type: ignore[return-value]
 
 
 # ---------------------------------------------------------------------------
@@ -372,6 +629,46 @@ class _ApigenHandler(BaseHTTPRequestHandler):
 
         self._dispatch(op, data, envelope_from_headers=True)
 
+    # ------------------------------------------------------------------
+    # Route: POST <route> for a synthetic `_batch/<kind>` mount
+    # (BATCH_0.0.1.md §5 — see `_dispatch_batch`'s own doc comment).
+    # ------------------------------------------------------------------
+
+    def _handle_batch_post(self, op: dict[str, Any]) -> None:
+        content_length = int(self.headers.get("Content-Length", "0") or "0")
+        body_bytes = self.rfile.read(content_length) if content_length > 0 else b"{}"
+        try:
+            body = json.loads(body_bytes or b"{}")
+        except json.JSONDecodeError as exc:
+            self._send_error(400, "invalid_argument", f"JSON parse error: {exc}")
+            return
+
+        if not isinstance(body, dict):
+            self._send_error(400, "invalid_argument", "request body must be a JSON object")
+            return
+
+        state: _ServerState = self.server.state  # type: ignore[attr-defined]
+
+        # §9.1 envelope from headers, extracted once and shared across every
+        # item — mirrors the TS `invokeBatch` call site, which also threads
+        # ONE shared `call.envelope` across every fanned-out item (never a
+        # per-item envelope).
+        headers_lc = {k.lower(): v for k, v in self.headers.items()}
+        envelope = _extract_envelope(op.get("input", {}), headers_lc)
+
+        try:
+            results = _dispatch_batch(state, body, envelope)
+        except ApiError as exc:
+            status = HTTP_STATUS.get(exc.code, 500)
+            self._send_error(status, exc.code, exc.message)
+            return
+        except Exception as exc:
+            self._send_error(500, "internal", f"batch dispatch error: {exc}")
+            return
+
+        body_out = _json_dumps(results).encode()
+        self._send_json(200, body_out)
+
     # ------------------------------------------------------------------
     # Dispatch (shared between GET/POST paths)
     # ------------------------------------------------------------------
@@ -480,7 +777,15 @@ class _ApigenHandler(BaseHTTPRequestHandler):
         state: _ServerState = self.server.state  # type: ignore[attr-defined]
         entry = state.route_map.get(path_only)
         if entry is not None:
-            self._handle_post(entry.op)
+            # (batch-rollout) A synthetic `_batch/<kind>` mount's op id is
+            # the authoritative marker (`syntheticOp` always names batch
+            # mounts this way — F4) — never `entry.op.get("kind")`, which on
+            # a batch mount is its real grouped kind (e.g. 'action'), not the
+            # literal string 'batch'.
+            if entry.op.get("id", "").startswith("_batch/"):
+                self._handle_batch_post(entry.op)
+            else:
+                self._handle_post(entry.op)
             return
 
         self._send_error(404, "not_found", f"no route for POST {path_only}")
@@ -642,6 +947,10 @@ class ApigenFlaskServer:
         self.start()
         # §13.1 readiness signal — TS launcher polls for this line on stdout
         print(json.dumps({"ready": True, "port": self._port}), flush=True)
+        # BUG-APIGEN-053: self-terminate if the TS parent process dies
+        # outright (SIGKILL/OOM-kill/crash) without ever sending a signal —
+        # see apigen_python.parent_watchdog's module docstring.
+        start_parent_death_watchdog()
         try:
             # Block main thread while the daemon thread serves
             if self._thread is not None:

package/python/apigen_python/grpc_server.py

@@ -119,6 +119,7 @@ if str(_THIS_DIR) not in sys.path:
     sys.path.insert(0, str(_THIS_DIR))
 
 from apigen_python.errors import ApiError, GRPC_CODE  # noqa: E402
+from apigen_python.parent_watchdog import start_parent_death_watchdog  # noqa: E402
 from apigen_python.runtime import HostRequest, Runtime  # noqa: E402
 from apigen_python.validator import validate, ValidationError  # noqa: E402
 
@@ -842,6 +843,11 @@ class ApigenGrpcServer:
         _signal.signal(_signal.SIGTERM, _sig_handler)
         _signal.signal(_signal.SIGINT, _sig_handler)
 
+        # BUG-APIGEN-053: self-terminate if the TS parent process dies
+        # outright (SIGKILL/OOM-kill/crash) without ever sending a signal —
+        # see apigen_python.parent_watchdog's module docstring.
+        start_parent_death_watchdog()
+
         try:
             stop_event.wait()
         except KeyboardInterrupt:

package/python/apigen_python/parent_watchdog.py

@@ -0,0 +1,79 @@
+"""Parent-death watchdog (BUG-APIGEN-053).
+
+Both of apigen_python's long-running servers (flask_server.py, grpc_server.py)
+are spawned by a TS parent (apigen-plugin-py-flask/-py-grpc's `run()`) with
+stdio `['pipe', 'pipe', 'pipe']`. The only teardown path either plugin wires
+is `input.signal`'s 'abort' handler, which sends SIGTERM to the child -- but
+that requires the TS parent process to still be alive to fire it. When the
+parent instead dies outright (SIGKILL, OOM-kill, CI job cancellation, an
+uncaught crash before its abort handler runs), no signal is ever sent,
+`serve_forever()`'s wait/join call never wakes up, and the process reparents
+to launchd (ppid=1), holding its listening socket forever -- this is
+BUG-APIGEN-053's exact, measured failure mode (132 orphaned processes / 137
+listening sockets, ~23h old).
+
+Neither Python's default SIGTERM disposition (fires only when someone SENDS
+SIGTERM) nor a PR_SET_PDEATHSIG-style mechanism (Linux-only; unavailable on
+macOS, where this failure was measured) closes this gap. The portable fix:
+the child's stdin is a pipe whose write end is owned by the parent process.
+The OS closes that write end the INSTANT the parent dies, for ANY reason,
+including SIGKILL -- no cooperation from the dying parent required. A
+background thread blocked reading stdin sees EOF at exactly that moment.
+"""
+from __future__ import annotations
+
+import os
+import threading
+from typing import Callable, Optional
+
+
+def start_parent_death_watchdog(
+    on_parent_death: Optional[Callable[[], None]] = None,
+) -> threading.Thread:
+    """Starts a daemon thread blocked reading stdin (fd 0) via a raw
+    `os.read()` -- see the in-loop comment for why not `sys.stdin`. On EOF
+    (the parent's write end of the stdin pipe closed -- i.e. the parent
+    died, for ANY reason including SIGKILL), calls `on_parent_death`.
+
+    Default `on_parent_death` is `os._exit(0)` -- an immediate hard process
+    exit. That is deliberate and safe here: there is no client left to serve
+    a graceful response to (the process that spawned this server is gone),
+    and the OS reclaims the listening socket on process exit regardless of
+    whether `Server.stop()`/`shutdown()` ran first.
+
+    Returns the started (daemon=True) Thread so a caller/test can join it.
+    """
+    callback = on_parent_death or (lambda: os._exit(0))
+
+    def _watch() -> None:
+        try:
+            while True:
+                # Deliberately `os.read(0, ...)` (a raw fd read via the
+                # syscall wrapper), NOT `sys.stdin.buffer.read(...)`: the
+                # buffered form takes CPython's internal BufferedReader lock
+                # for the duration of the blocking read. `grpc_server.py`
+                # handles SIGTERM/SIGINT gracefully (its own handler sets an
+                # Event and `_main()` returns normally, reaching an ORDERLY
+                # `Py_Finalize()`) -- and finalization tries to flush/close
+                # `sys.stdin`, which cannot acquire that same lock while this
+                # daemon thread still holds it, producing a real, reproduced
+                # `Fatal Python error: _enter_buffered_busy: could not
+                # acquire lock ... at interpreter shutdown` on every single
+                # graceful teardown. A raw `os.read()` never touches that
+                # lock, so it can be safely abandoned mid-call when the
+                # interpreter exits either gracefully or via `os._exit()`.
+                chunk = os.read(0, 4096)
+                if not chunk:
+                    break
+        except OSError:
+            # stdin fd already closed/invalid (e.g. a harness that doesn't
+            # wire a pipe, or redirects fd 0 elsewhere) -- nothing to watch;
+            # exit the thread quietly.
+            return
+        callback()
+
+    thread = threading.Thread(
+        target=_watch, name="apigen-parent-death-watchdog", daemon=True
+    )
+    thread.start()
+    return thread

package/python/run_tests.py

@@ -25,6 +25,7 @@ import importlib.util
 import inspect
 import json
 import os
+import shutil
 import subprocess
 import sys
 import tempfile
@@ -916,6 +917,44 @@ def run_echo_roundtrip(results: _Results) -> None:
 # Never sleep-as-proof: all waits are bounded polls.
 # ---------------------------------------------------------------------------
 
+def _build_flask_plan(
+    fixture_module: Path,
+    namespace: str,
+    ops: list[dict[str, Any]] | None = None,
+    extra_operations: list[dict[str, Any]] | None = None,
+    extra_routes: dict[str, dict[str, str]] | None = None,
+) -> tuple[Path, Path]:
+    """Build a real `--plan-file` for `flask_server.py` from a real
+    `extract_module()` pass — `flask_server.py` has required `--plan-file`
+    since the apigen-serve-core py-flask-serve-split (it no longer
+    self-extracts or re-derives route/verb; see its module docstring).
+
+    Routes use the flat `/{namespace}/{fnName}` shape this file's own
+    `_post`/`_get` test helpers already assume — this suite tests
+    `flask_server.py`'s OWN dispatch/validation/logical-type/batch behavior
+    given a correct plan, not route derivation itself (the real
+    `project()`-derived kebab-route shape is independently proven
+    byte-for-byte by `apigen-plugin-py-flask`'s own TS test suite,
+    BUG-APIGEN-OPENAPI-ROUTE-PATH-MISMATCH-001).
+
+    Returns:
+        `(plan_path, tmpdir)` — caller removes `tmpdir` (best-effort) once
+        the spawned server is done with it.
+    """
+    if ops is None:
+        ops = extract_module(str(fixture_module), namespace)
+    routes: dict[str, dict[str, str]] = {}
+    for op in ops:
+        fn_name = op["path"][-1]["raw"]
+        routes[op["id"]] = {"route": f"/{namespace}/{fn_name}", "verb": "POST"}
+    all_ops = list(ops) + list(extra_operations or [])
+    routes.update(extra_routes or {})
+    tmpdir = Path(tempfile.mkdtemp(prefix="apigen-py-flask-runtests-plan-"))
+    plan_path = tmpdir / "plan.json"
+    plan_path.write_text(json.dumps({"operations": all_ops, "routes": routes}))
+    return plan_path, tmpdir
+
+
 def run_flask_server_tests(results: _Results) -> None:
     """Run live HTTP tests against a real flask_server subprocess."""
     import signal
@@ -930,7 +969,7 @@ def run_flask_server_tests(results: _Results) -> None:
     # SCRIPT_DIR.parent = packages/apigen
     fixture_module = (
         SCRIPT_DIR.parent /   # packages/apigen
-        "plugins" / "py-flask" / "src" / "test" / "fixtures" / "test_api.py"
+        "apigen-plugin-py-flask" / "src" / "test" / "fixtures" / "test_api.py"
     )
     if not fixture_module.exists():
         results.fail(
@@ -943,6 +982,37 @@ def run_flask_server_tests(results: _Results) -> None:
     namespace = "testapi"
     base_url = f"http://127.0.0.1:{port}"
 
+    # (batch-rollout) Every fixture op below (`echo_str`/`double_decimal`/...)
+    # is `kind='action'` (see extractor.py: every callable export → 'action'),
+    # so they group under ONE synthetic `_batch/action` mount — mirrors what
+    # `buildBatchMountedOperations` (apigen-core-client/src/lib/batch.ts)
+    # would produce TS-side for this same fixture module, hand-built here
+    # since this suite has no Node/TS runtime available to call it for real.
+    real_ops = extract_module(str(fixture_module), namespace)
+    batch_op_id = "_batch/action"
+    batch_op: dict[str, Any] = {
+        "id": batch_op_id,
+        "host": "python",
+        "namespace": {"raw": namespace, "words": [namespace]},
+        "path": [{"raw": "batch", "words": ["batch"]}, {"raw": "action", "words": ["action"]}],
+        "kind": "action",
+        "async": False,
+        "streaming": False,
+        "safe": False,
+        "input": {"type": "object"},
+        "output": {},
+        "envelope": {},
+        "typeText": None,
+        "operationIds": [op["id"] for op in real_ops],
+    }
+    plan_path, plan_tmpdir = _build_flask_plan(
+        fixture_module,
+        namespace,
+        ops=real_ops,
+        extra_operations=[batch_op],
+        extra_routes={batch_op_id: {"route": f"/{namespace}/_batch/action", "verb": "POST"}},
+    )
+
     # Spawn the server subprocess.
     proc = subprocess.Popen(
         [
@@ -950,6 +1020,7 @@ def run_flask_server_tests(results: _Results) -> None:
             "--module", str(fixture_module),
             "--namespace", namespace,
             "--port", str(port),
+            "--plan-file", str(plan_path),
         ],
         cwd=str(SCRIPT_DIR),
         env={**os.environ, "PYTHONPATH": str(SCRIPT_DIR)},
@@ -971,6 +1042,7 @@ def run_flask_server_tests(results: _Results) -> None:
 
     if not ready:
         proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
         results.fail("flask.startup", "Server did not become ready within 10 s")
         return
 
@@ -1119,12 +1191,219 @@ def run_flask_server_tests(results: _Results) -> None:
         else:
             results.fail("flask.envelope.ctx", f"expected session in response, got {env_status} {env_body!r}")
 
+        # ------------------------------------------------------------------
+        # Batch/bulk fan-out — BATCH_0.0.1.md §5 (batch-rollout, py-flask)
+        # ------------------------------------------------------------------
+        batch_url = f"{base_url}/{namespace}/_batch/action"
+
+        def _post_batch(payload: dict[str, Any]) -> tuple[int, Any]:
+            req = urllib.request.Request(
+                batch_url,
+                data=json.dumps(payload).encode(),
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            try:
+                with urllib.request.urlopen(req, timeout=10) as resp:
+                    return resp.status, json.loads(resp.read())
+            except urllib.error.HTTPError as e:
+                return e.code, json.loads(e.read())
+
+        # Test: parallel fan-out, 3 items (2 valid echo_str + 1 that fails
+        # input validation) — proves per-item partial-failure with
+        # onItemError='continue' (the default) using the REAL ApiError
+        # reason shape.
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/echo-str",
+            "items": [{"msg": "one"}, {"msg": 123}, {"msg": "two"}],
+        })
+        if (
+            status == 200
+            and isinstance(body, list)
+            and len(body) == 3
+            and body[0] == {"index": 0, "status": "fulfilled", "value": "one"}
+            and body[1]["status"] == "rejected"
+            and body[1]["reason"].get("code") == "invalid_argument"
+            and body[2] == {"index": 2, "status": "fulfilled", "value": "two"}
+        ):
+            results.ok("flask.batch.parallel.partial_failure")
+        else:
+            results.fail(
+                "flask.batch.parallel.partial_failure",
+                f"expected [fulfilled,rejected(invalid_argument),fulfilled], got {status} {body!r}",
+            )
+
+        # Test: Decimal logical-type parity through the batch path (F4) —
+        # same decoded-Decimal-then-encoded-string round-trip as the
+        # single-op `double_decimal` test above.
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/double-decimal",
+            "items": [{"amount": "123.456"}, {"amount": "0.1"}],
+        })
+        if (
+            status == 200
+            and isinstance(body, list)
+            and len(body) == 2
+            and body[0] == {"index": 0, "status": "fulfilled", "value": "246.912"}
+            and body[1] == {"index": 1, "status": "fulfilled", "value": "0.2"}
+            and isinstance(body[1]["value"], str)
+        ):
+            results.ok("flask.batch.logical_type.decimal_parity")
+        else:
+            results.fail(
+                "flask.batch.logical_type.decimal_parity",
+                f"expected decimal-string parity with single-op path, got {status} {body!r}",
+            )
+
+        # Test: mode='serial' actually runs sequentially, in declared order,
+        # all fulfilled (no failures to react to).
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/echo-str",
+            "items": [{"msg": "a"}, {"msg": "b"}, {"msg": "c"}],
+            "mode": "serial",
+        })
+        if status == 200 and body == [
+            {"index": 0, "status": "fulfilled", "value": "a"},
+            {"index": 1, "status": "fulfilled", "value": "b"},
+            {"index": 2, "status": "fulfilled", "value": "c"},
+        ]:
+            results.ok("flask.batch.serial.order")
+        else:
+            results.fail("flask.batch.serial.order", f"expected in-order fulfilled triple, got {status} {body!r}")
+
+        # Test: mode='chained' stops immediately on the first failure —
+        # every remaining item is marked not-attempted regardless of
+        # onItemError (which defaults to 'continue' here, deliberately, to
+        # prove 'chained' overrides it).
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/echo-str",
+            "items": [{"msg": 999}, {"msg": "never-runs"}, {"msg": "never-runs-2"}],
+            "mode": "chained",
+        })
+        if (
+            status == 200
+            and isinstance(body, list)
+            and len(body) == 3
+            and body[0]["status"] == "rejected"
+            and body[0]["reason"].get("code") == "invalid_argument"
+            and body[1]["status"] == "rejected"
+            and body[1]["reason"].get("code") == "internal"
+            and "never attempted" in body[1]["reason"].get("message", "").lower()
+            and body[2]["status"] == "rejected"
+            and body[2]["reason"].get("code") == "internal"
+        ):
+            results.ok("flask.batch.chained.stops_on_first_failure")
+        else:
+            results.fail(
+                "flask.batch.chained.stops_on_first_failure",
+                f"expected item0 rejected + items1/2 not-attempted, got {status} {body!r}",
+            )
+
+        # NEGATIVE CONTROL for the chained test above: with mode='parallel'
+        # (the default) and onItemError='continue' (the default), the SAME
+        # failing-first-item batch must NOT abort the remaining items — if
+        # it did, this would go RED, proving the 'chained' assertion above
+        # has teeth (it is actually 'chained'-specific behavior, not just
+        # "the server always stops on first failure").
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/echo-str",
+            "items": [{"msg": 999}, {"msg": "still-runs"}, {"msg": "still-runs-2"}],
+        })
+        if (
+            status == 200
+            and isinstance(body, list)
+            and len(body) == 3
+            and body[0]["status"] == "rejected"
+            and body[1] == {"index": 1, "status": "fulfilled", "value": "still-runs"}
+            and body[2] == {"index": 2, "status": "fulfilled", "value": "still-runs-2"}
+        ):
+            results.ok("flask.batch.chained.negative_control_default_continues")
+        else:
+            results.fail(
+                "flask.batch.chained.negative_control_default_continues",
+                f"default mode must NOT stop on first failure, got {status} {body!r}",
+            )
+
+        # Test: onItemError='abort' under mode='parallel' with concurrency=1
+        # (forces strict submission-order execution through the single
+        # ThreadPoolExecutor worker) — the first item fails, so items 1/2
+        # must never actually run (not-attempted), deterministically (no
+        # timing/sleep dependency: with exactly one worker thread pulling
+        # from the pool's FIFO queue, item 0 always completes — and sets the
+        # abort flag — strictly before item 1 is dequeued).
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/echo-str",
+            "items": [{"msg": 999}, {"msg": "should-not-run"}, {"msg": "should-not-run-2"}],
+            "concurrency": 1,
+            "onItemError": "abort",
+        })
+        if (
+            status == 200
+            and isinstance(body, list)
+            and len(body) == 3
+            and body[0]["status"] == "rejected"
+            and body[0]["reason"].get("code") == "invalid_argument"
+            and body[1]["status"] == "rejected"
+            and body[1]["reason"].get("code") == "internal"
+            and "abort" in body[1]["reason"].get("message", "").lower()
+            and body[2]["status"] == "rejected"
+        ):
+            results.ok("flask.batch.parallel.on_item_error_abort")
+        else:
+            results.fail(
+                "flask.batch.parallel.on_item_error_abort",
+                f"expected item0 rejected + items1/2 not-attempted (abort), got {status} {body!r}",
+            )
+
+        # Test: itemTimeoutMs is rejected upfront (F3) — the WHOLE batch
+        # request 400s with invalid_argument, before any item is dispatched.
+        status, body = _post_batch({
+            "operation": f"{namespace}/test-api/echo-str",
+            "items": [{"msg": "x"}],
+            "itemTimeoutMs": 1000,
+        })
+        if status == 400 and body.get("code") == "invalid_argument":
+            results.ok("flask.batch.item_timeout_ms.rejected")
+        else:
+            results.fail(
+                "flask.batch.item_timeout_ms.rejected",
+                f"expected 400 invalid_argument for itemTimeoutMs, got {status} {body!r}",
+            )
+
+        # Test: targeting a nested `_batch/*` mount is rejected (F4's
+        # ID-prefix guard) — never silently accepted as a real op.
+        status, body = _post_batch({
+            "operation": batch_op_id,
+            "items": [{}],
+        })
+        if status == 400 and body.get("code") == "invalid_argument":
+            results.ok("flask.batch.nested_batch_target.rejected")
+        else:
+            results.fail(
+                "flask.batch.nested_batch_target.rejected",
+                f"expected 400 invalid_argument for nested batch target, got {status} {body!r}",
+            )
+
+        # Test: targeting an operation id that doesn't exist at all.
+        status, body = _post_batch({
+            "operation": f"{namespace}/does-not-exist",
+            "items": [{}],
+        })
+        if status == 400 and body.get("code") == "invalid_argument":
+            results.ok("flask.batch.unknown_operation.rejected")
+        else:
+            results.fail(
+                "flask.batch.unknown_operation.rejected",
+                f"expected 400 invalid_argument for unknown operation, got {status} {body!r}",
+            )
+
     finally:
         proc.kill()
         try:
             proc.wait(timeout=3)
         except subprocess.TimeoutExpired:
             proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
 
 
 # ---------------------------------------------------------------------------
@@ -1338,7 +1617,7 @@ def run_cli_decimal_live_tests(results: _Results) -> None:
     # Locate the decimal_api fixture module.
     fixture_module = (
         SCRIPT_DIR.parent /           # packages/apigen
-        "plugins" / "py-flask" / "src" / "test" / "fixtures" / "decimal_api.py"
+        "apigen-plugin-py-flask" / "src" / "test" / "fixtures" / "decimal_api.py"
     )
     if not fixture_module.exists():
         results.fail(
@@ -1351,6 +1630,8 @@ def run_cli_decimal_live_tests(results: _Results) -> None:
     namespace = "decapi"
     base_url = f"http://127.0.0.1:{port}"
 
+    plan_path, plan_tmpdir = _build_flask_plan(fixture_module, namespace)
+
     # Spawn the flask_server directly (not through the CLI, to keep this test
     # self-contained within run_tests.py) but using PYTHONPATH=SCRIPT_DIR so
     # the environment matches the CLI-spawned environment exactly.
@@ -1360,6 +1641,7 @@ def run_cli_decimal_live_tests(results: _Results) -> None:
             "--module", str(fixture_module),
             "--namespace", namespace,
             "--port", str(port),
+            "--plan-file", str(plan_path),
         ],
         cwd=str(SCRIPT_DIR),
         env={**os.environ, "PYTHONPATH": str(SCRIPT_DIR)},
@@ -1382,6 +1664,7 @@ def run_cli_decimal_live_tests(results: _Results) -> None:
     if not ready:
         stderr_out = proc.stderr.read().decode("utf-8", errors="replace") if proc.stderr else ""
         proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
         results.fail(
             "cli_decimal.startup",
             f"Server did not become ready within 10 s. stderr: {stderr_out[:500]}",
@@ -1557,6 +1840,7 @@ def run_cli_decimal_live_tests(results: _Results) -> None:
             proc.wait(timeout=3)
         except subprocess.TimeoutExpired:
             proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
 
 
 # ---------------------------------------------------------------------------
@@ -1585,7 +1869,7 @@ def run_future_annotations_tests(results: _Results) -> None:
 
     fixture_module = (
         SCRIPT_DIR.parent /        # packages/apigen
-        "plugins" / "py-flask" / "src" / "test" / "fixtures" / "future_annotations_api.py"
+        "apigen-plugin-py-flask" / "src" / "test" / "fixtures" / "future_annotations_api.py"
     )
     if not fixture_module.exists():
         results.fail(
@@ -1674,12 +1958,15 @@ def run_future_annotations_tests(results: _Results) -> None:
     namespace = "futureann"
     base_url = f"http://127.0.0.1:{port}"
 
+    plan_path, plan_tmpdir = _build_flask_plan(fixture_module, namespace, ops=ops)
+
     proc = subprocess.Popen(
         [
             sys.executable, "-m", "apigen_python.flask_server",
             "--module", str(fixture_module),
             "--namespace", namespace,
             "--port", str(port),
+            "--plan-file", str(plan_path),
         ],
         cwd=str(SCRIPT_DIR),
         env={**os.environ, "PYTHONPATH": str(SCRIPT_DIR)},
@@ -1702,6 +1989,7 @@ def run_future_annotations_tests(results: _Results) -> None:
     if not ready:
         stderr_out = proc.stderr.read().decode("utf-8", errors="replace") if proc.stderr else ""
         proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
         results.fail(
             "future_ann.startup",
             f"Server did not become ready within 10 s. stderr: {stderr_out[:500]}",
@@ -1782,6 +2070,7 @@ def run_future_annotations_tests(results: _Results) -> None:
             proc.wait(timeout=3)
         except subprocess.TimeoutExpired:
             proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
 
 
 # ---------------------------------------------------------------------------
@@ -1799,6 +2088,65 @@ def run_future_annotations_tests(results: _Results) -> None:
 #      NEGATIVE CONTROL: JSON number response would fail typeof=='string' check
 # ---------------------------------------------------------------------------
 
+def _grpc_snake(words: list[str]) -> str:
+    """Join tokenised Segment `words` into a snake_case identifier."""
+    return "_".join(words)
+
+
+def _grpc_pascal(words: list[str]) -> str:
+    """Join tokenised Segment `words` into a PascalCase identifier."""
+    return "".join(w.capitalize() for w in words)
+
+
+def _build_grpc_plan(
+    fixture_module: Path,
+    namespace: str,
+) -> tuple[Path, Path, str, str]:
+    """Build a real `--plan-file` for `grpc_server.py` from a real
+    `extract_module()` pass — `grpc_server.py` has required `--plan-file`
+    since the apigen-serve-core py-grpc-serve-split (it no longer
+    self-extracts or re-derives package/service/method; see its module
+    docstring).
+
+    Computes each op's `{package, service, method}` the SAME way the real
+    `@adhd/apigen-engine-naming` `project(op).grpc` does (grpc_server.py's
+    module docstring, mirrored from `naming.ts`):
+        package = dotted, snake_cased, all `[namespace, ...path]` segments
+                  but the last
+        service = Pascal-cased second-to-last segment (the "file" segment,
+                  falling back to the first segment when there is no
+                  second-to-last)
+        method  = Pascal-cased last segment (the "export" segment)
+
+    This suite tests `grpc_server.py`'s OWN dispatch/validation/logical-type
+    behavior given a correct plan, not naming derivation itself (the real
+    `project()`-derived package/service/method shape is independently
+    proven byte-for-byte by `apigen-plugin-py-grpc`'s own TS test suite,
+    `apigen-engine-naming/src/test/naming.spec.ts`).
+
+    Returns:
+        `(plan_path, tmpdir, package, service)` — caller removes `tmpdir`
+        (best-effort) once the spawned server is done with it; `package`
+        and `service` are returned so callers can build the expected
+        `<package>.<Service>/<Method>` gRPC target without recomputing it.
+    """
+    ops = extract_module(str(fixture_module), namespace)
+    grpc_map: dict[str, dict[str, str]] = {}
+    package = ""
+    service = ""
+    for op in ops:
+        all_segs = [op["namespace"]] + op["path"]
+        package = ".".join(_grpc_snake(seg["words"]) for seg in all_segs[:-1])
+        second_to_last = all_segs[-2] if len(all_segs) >= 2 else all_segs[0]
+        service = _grpc_pascal(second_to_last["words"])
+        method = _grpc_pascal(all_segs[-1]["words"])
+        grpc_map[op["id"]] = {"package": package, "service": service, "method": method}
+    tmpdir = Path(tempfile.mkdtemp(prefix="apigen-py-grpc-runtests-plan-"))
+    plan_path = tmpdir / "plan.json"
+    plan_path.write_text(json.dumps({"operations": ops, "grpc": grpc_map}))
+    return plan_path, tmpdir, package, service
+
+
 def run_grpc_server_tests(results: _Results) -> None:
     """Run live gRPC tests against a real grpc_server subprocess (using grpcurl)."""
     import re as _re
@@ -1821,7 +2169,7 @@ def run_grpc_server_tests(results: _Results) -> None:
     # Locate the gRPC fixture module
     fixture_module = (
         SCRIPT_DIR.parent /           # packages/apigen
-        "plugins" / "py-grpc" / "src" / "test" / "fixtures" / "grpc_api.py"
+        "apigen-plugin-py-grpc" / "src" / "test" / "fixtures" / "grpc_api.py"
     )
     if not fixture_module.exists():
         results.fail(
@@ -1836,12 +2184,22 @@ def run_grpc_server_tests(results: _Results) -> None:
     namespace = "pkg"
     addr = f"localhost:{port}"
 
+    plan_path, plan_tmpdir, grpc_package, grpc_service = _build_grpc_plan(
+        fixture_module, namespace,
+    )
+    # Full gRPC method target, e.g. "pkg.grpc_api.GrpcApi/AddDecimal" —
+    # computed from the SAME injected plan the server itself consumes (never
+    # a re-derived/hard-coded literal), so this suite can never drift from
+    # `grpc_server.py`'s actual `--plan-file` contract.
+    service_target = f"{grpc_package}.{grpc_service}"
+
     proc = subprocess.Popen(
         [
             sys.executable, "-m", "apigen_python.grpc_server",
             "--module", str(fixture_module),
             "--namespace", namespace,
             "--port", str(port),
+            "--plan-file", str(plan_path),
         ],
         cwd=str(SCRIPT_DIR),
         env={**os.environ, "PYTHONPATH": str(SCRIPT_DIR)},
@@ -1873,6 +2231,7 @@ def run_grpc_server_tests(results: _Results) -> None:
     if not ready:
         stderr_out = proc.stderr.read().decode("utf-8", errors="replace") if proc.stderr else ""
         proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
         results.fail(
             "grpc.startup",
             f"Server did not emit ready signal within 10 s. stderr: {stderr_out[:500]}",
@@ -1890,32 +2249,37 @@ def run_grpc_server_tests(results: _Results) -> None:
         return r.returncode, r.stdout.strip(), r.stderr.strip()
 
     def _call(method: str, data: dict[str, Any]) -> tuple[int, str, str]:
-        """Call /<namespace>.<Namespace>Service/<method> with typed data payload."""
-        return _grpcurl("-d", json.dumps(data), addr, f"{namespace}.PkgService/{method}")
+        """Call /<package>.<Service>/<Method> with typed data payload — target
+        computed from the SAME injected `--plan-file` the server consumes.
+        `method` is the fixture's raw snake_case function name (e.g.
+        "add_decimal"); it is Pascal-cased here to match the plan's
+        `grpc_map[...]["method"]` the server actually registered."""
+        method_pascal = _grpc_pascal(method.split("_"))
+        return _grpcurl("-d", json.dumps(data), addr, f"{service_target}/{method_pascal}")
 
     try:
         # ------------------------------------------------------------------
         # Test 1: grpcurl list → service visible via reflection
         # ------------------------------------------------------------------
         code, out, err = _grpcurl(addr, "list")
-        if code == 0 and f"{namespace}.PkgService" in out:
+        if code == 0 and service_target in out:
             results.ok("grpc.list.service_visible")
         else:
             results.fail(
                 "grpc.list.service_visible",
-                f"expected pkg.PkgService in list; exit={code} out={out!r} err={err[:200]!r}",
+                f"expected {service_target} in list; exit={code} out={out!r} err={err[:200]!r}",
             )
 
         # ------------------------------------------------------------------
         # Test 2: describe → methods present
         # ------------------------------------------------------------------
-        code, out, err = _grpcurl(addr, "describe", f"{namespace}.PkgService")
-        if code == 0 and "add_decimal" in out and "greet" in out:
+        code, out, err = _grpcurl(addr, "describe", service_target)
+        if code == 0 and "AddDecimal" in out and "Greet" in out:
             results.ok("grpc.describe.methods_present")
         else:
             results.fail(
                 "grpc.describe.methods_present",
-                f"expected add_decimal, greet in describe; exit={code} out={out[:300]!r}",
+                f"expected AddDecimal, Greet in describe; exit={code} out={out[:300]!r}",
             )
 
         # ------------------------------------------------------------------
@@ -2056,6 +2420,7 @@ def run_grpc_server_tests(results: _Results) -> None:
             proc.wait(timeout=3)
         except subprocess.TimeoutExpired:
             proc.kill()
+        shutil.rmtree(plan_tmpdir, ignore_errors=True)
 
 
 # ---------------------------------------------------------------------------