Upload folder using huggingface_hub

.gitignore

@@ -0,0 +1,7 @@
+# Build artifacts (regenerable from canonical sources).
+build/
+__pycache__/
+*.pyc
+*.pyo
+.cache/
+*.log

Dockerfile

@@ -0,0 +1,64 @@
+# syntax=docker/dockerfile:1.6
+# Unified DriftCall Space — same base + deps as env Space, plus the
+# pre-built frontend dist/ mounted at root.
+
+FROM python:3.11-slim AS builder
+ENV PIP_NO_CACHE_DIR=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1 \
+    PYTHONDONTWRITEBYTECODE=1
+WORKDIR /build
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential git libsndfile1 ffmpeg \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt ./
+RUN pip install --prefix=/install -r requirements.txt
+
+# Pre-pull TTS / ASR weights so the runtime container can run offline.
+RUN pip install --prefix=/install huggingface_hub
+RUN PYTHONPATH=/install/lib/python3.11/site-packages \
+    python -c "from huggingface_hub import snapshot_download; \
+               snapshot_download('hexgrad/Kokoro-82M', cache_dir='/weights'); \
+               snapshot_download('Systran/faster-whisper-small', cache_dir='/weights')"
+
+# -------- runtime --------
+FROM python:3.11-slim
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    HF_HOME=/root/.cache/huggingface \
+    TRANSFORMERS_OFFLINE=1 \
+    HF_HUB_OFFLINE=1 \
+    WANDB_PROJECT=driftcall \
+    WANDB_MODE=disabled
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        libsndfile1 ffmpeg ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY --from=builder /install /usr/local
+COPY --from=builder /weights /root/.cache/huggingface
+
+WORKDIR /app
+
+# Application code (cells/ + app.py + openenv.yaml + data/) and the
+# pre-built frontend dist/ (mounted at / by unified_app.py).
+COPY cells/        ./cells/
+COPY data/         ./data/
+COPY app.py openenv.yaml unified_app.py ./
+COPY site/         ./site/
+
+EXPOSE 7860
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=45s \
+    CMD python -c "import urllib.request; \
+                   urllib.request.urlopen('http://127.0.0.1:7860/healthz', timeout=4).read()" \
+        || exit 1
+
+# unified_app:app exposes both the OpenEnv routes (at root) and the
+# static frontend (mounted at /).
+CMD ["uvicorn", "unified_app:app", \
+     "--host", "0.0.0.0", \
+     "--port", "7860", \
+     "--workers", "2", \
+     "--timeout-keep-alive", "30", \
+     "--log-level", "info"]

README.md

@@ -1,12 +1,84 @@
 ---
-title: Driftcall
-emoji: 🐠
-colorFrom: yellow
-colorTo: red
-sdk: gradio
-sdk_version: 6.13.0
-app_file: app.py
-pinned: false
+title: DriftCall
+emoji: 🌀
+colorFrom: indigo
+colorTo: pink
+sdk: docker
+pinned: true
+license: apache-2.0
+short_description: OpenEnv env + site · canonical /reset · one Space
+tags:
+  - openenv
+  - rl
+  - voice
+  - indic
+  - schema-drift
+  - grpo
+  - gemma-3n
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# DriftCall — Unified Space
+
+One HF Space serving the OpenEnv-compliant DriftCall env **and** the
+project site, both under the same hostname. OpenEnv routes are at the
+canonical bare paths (no `/api` prefix), so the registry and the gym
+client see this Space exactly as it sees the dedicated env Space.
+
+## URL surface
+
+| Path             | Method   | What it does |
+|------------------|----------|--------------|
+| `/`              | `GET`    | static project site (Vite-built React + pretext) |
+| `/assets/*`      | `GET`    | site bundle (CSS, JS, fonts) |
+| `/healthz`       | `GET`    | OpenEnv health probe (`text/plain "ok"`) |
+| `/reset`         | `POST`   | OpenEnv reset (bearer auth + X-Session-Id) |
+| `/step`          | `POST`   | OpenEnv step |
+| `/state`         | `GET`    | OpenEnv read-only state |
+| `/close`         | `POST`   | OpenEnv close session |
+| `/openenv.yaml`  | `GET`    | the manifest (served from disk) |
+| `/demo`          | `GET`    | 302 → dedicated Gradio demo Space |
+
+The OpenEnv routes do not collide with the static frontend because
+they are HTTP verb-specific (`POST /reset`, `POST /step`, `POST /close`,
+plus `GET /healthz` and `GET /state`) — Vite-emitted assets live under
+`/assets/*` and never overlap.
+
+## Why both, not separate?
+
+The dedicated env Space (`DGXAI/driftcall-env`) and project site
+(`DGXAI/driftcall-site`) still exist as canonical, isolated artefacts.
+This Space is an **additive** convenience for hackathon judging:
+land at one URL and you see the project, can hit the reward function
+endpoint, and get redirected to the demo. The Gradio demo stays
+separate because it's GPU-heavy and benefits from its own scaling.
+
+## What's bundled
+
+Self-contained — the build dir for this Space contains everything it
+needs to run, with no references to anything outside it:
+
+```
+unified_space/build/
+├── app.py              ← canonical OpenEnv FastAPI (verbatim copy)
+├── unified_app.py      ← extends app.py + adds static mount + /demo redirect
+├── openenv.yaml        ← OpenEnv v1.0 manifest
+├── requirements.txt    ← runtime deps (no training stack)
+├── Dockerfile          ← multi-stage CPU image, Kokoro + faster-whisper baked
+├── cells/              ← DriftCallEnv + 5 reward components + drift + audio
+├── data/               ← briefs, drift patterns, API schemas
+└── site/               ← Vite-built React dist (frontend)
+```
+
+Build + push with `bash deploy/unified_space/build.sh --push` from the
+repo root.
+
+## OpenEnv compliance
+
+- Manifest: served at `/openenv.yaml`
+- Endpoints: bare-path canonical (`/reset`, `/step`, `/state`, `/close`, `/healthz`)
+- Auth: bearer (`DRIFTCALL_ENV_TOKEN`) + `X-Session-Id` header on mutating calls
+- Action / Observation refs: `cells.step_04_models:DriftCallAction` /
+  `cells.step_04_models:DriftCallObservation`
+- Reward: 5 components (R1..R5) with weights, calibration via Brier +
+  uncertain floor — see `cells/step_08_rewards.py` and the openenv.yaml
+  reward block.

app.py

@@ -0,0 +1,786 @@
+"""DriftCall env Space — FastAPI + OpenEnv-compliant REST surface.
+
+Implements ``docs/modules/deploy_env_space.md`` and DESIGN.md §3.3 / §11.1.
+
+Endpoints:
+    GET  /healthz   → 200 text/plain "ok" (unauthenticated)
+    POST /reset     → 200 application/json (create / recycle session)
+    POST /step      → 200 application/json (advance one turn)
+    GET  /state     → 200 application/json (read DriftCallState)
+    POST /close     → 200 application/json (evict session)
+
+Headers (mutating endpoints): ``Authorization: Bearer <DRIFTCALL_ENV_TOKEN>``
+and ``X-Session-Id: <[A-Za-z0-9_-]{1,64}>``.
+
+Error modes (deploy_env_space.md §5):
+    M1 401 unauthorized          M7  400 bad_json
+    M2 400 missing_session_id    M8  400 invalid_action
+    M3 404 session_not_found     M9  500 internal_error
+    M4 404 session_expired       M10 500 io_error
+    M5 429 max_sessions          M11 413 payload_too_large
+    M6 503 model_not_ready       M12 409 reset_in_progress
+
+All error bodies: ``{"error": {"code": <slug>, "message": <str>,
+"request_id": <asgi-id>}}``; ``Cache-Control: no-store``; only M5 carries
+``Retry-After: 30``. No stack traces ever leak across the wire.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import dataclasses
+import json
+import logging
+import os
+import re
+import time
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING, Any
+
+from fastapi import FastAPI, Request, Response
+from fastapi.responses import JSONResponse, PlainTextResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+
+from cells.step_04_models import ActionType, DriftCallAction
+from cells.step_10_env import (
+    DriftCallEnv,
+    EnvClosedError,
+    EnvNotReadyError,
+    EpisodeAlreadyTerminalError,
+    InvalidActionError,
+    InvalidConfigError,
+    UnknownDomainError,
+    UnknownToolError,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator, Awaitable, Callable
+
+    from starlette.types import ASGIApp
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_MAX_SESSIONS: int = 10
+_TTL_S: float = 3600.0
+_SWEEP_INTERVAL_S: float = 60.0
+_MAX_SESSION_ID_LEN: int = 64
+_SESSION_ID_RE: re.Pattern[str] = re.compile(r"^[A-Za-z0-9_-]{1,64}$")
+_MAX_BODY_BYTES: int = 1 * 1024 * 1024  # 1 MiB
+_RETRY_AFTER_S: str = "30"
+_TOKEN_ENV_VAR: str = "DRIFTCALL_ENV_TOKEN"
+
+
+# ---------------------------------------------------------------------------
+# Time source (test-overridable)
+# ---------------------------------------------------------------------------
+
+
+def _monotonic() -> float:
+    """Indirection for tests to monkeypatch."""
+
+    return time.monotonic()
+
+
+# ---------------------------------------------------------------------------
+# Errors / envelope
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _ApiError(Exception):
+    """Internal exception → uniform error envelope (deploy_env_space.md §5)."""
+
+    code: str
+    message: str
+    http_status: int
+    retry_after: bool = False
+
+
+_NO_STORE: dict[str, str] = {"Cache-Control": "no-store"}
+
+
+def _error_response(err: _ApiError, request_id: str) -> JSONResponse:
+    body = {
+        "error": {
+            "code": err.code,
+            "message": err.message,
+            "request_id": request_id,
+        }
+    }
+    headers = dict(_NO_STORE)
+    if err.retry_after:
+        headers["Retry-After"] = _RETRY_AFTER_S
+    return JSONResponse(status_code=err.http_status, content=body, headers=headers)
+
+
+# ---------------------------------------------------------------------------
+# Session cache
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SessionEntry:
+    """Frozen per project rule — every touch produces a new entry."""
+
+    env: DriftCallEnv
+    created_at: float
+    last_touched: float
+    reset_count: int
+    lock: asyncio.Lock
+
+
+class SessionCache:
+    """In-memory session registry with LRU + TTL eviction."""
+
+    def __init__(self, *, max_sessions: int = _MAX_SESSIONS, ttl_s: float = _TTL_S) -> None:
+        self._max = max_sessions
+        self._ttl = ttl_s
+        self._store: dict[str, SessionEntry] = {}
+        self._guard = asyncio.Lock()
+
+    @property
+    def size(self) -> int:
+        return len(self._store)
+
+    def get(self, sid: str) -> SessionEntry | None:
+        return self._store.get(sid)
+
+    async def acquire_lock(self, sid: str) -> asyncio.Lock:
+        """Return (or lazily create) the per-session lock."""
+        async with self._guard:
+            entry = self._store.get(sid)
+            if entry is not None:
+                return entry.lock
+            return asyncio.Lock()
+
+    async def insert_or_replace(self, sid: str, env_factory: Callable[[], DriftCallEnv]) -> SessionEntry:
+        """Insert a new env or replace an existing one (in-place reset)."""
+        async with self._guard:
+            now = _monotonic()
+            existing = self._store.get(sid)
+            if existing is not None:
+                # In-place reset (§7.1 case after winner completed).
+                try:
+                    existing.env.close()
+                except Exception:
+                    logger.exception("env.close() raised on in-place reset for sid=%s", sid)
+                env = env_factory()
+                entry = SessionEntry(
+                    env=env,
+                    created_at=now,
+                    last_touched=now,
+                    reset_count=existing.reset_count + 1,
+                    lock=existing.lock,
+                )
+                self._store[sid] = entry
+                return entry
+            # New session — enforce cap.
+            if len(self._store) >= self._max:
+                # Try LRU evict only if any entry is older than the others by TTL/2.
+                victim_sid = min(self._store, key=lambda k: self._store[k].last_touched)
+                victim = self._store[victim_sid]
+                age = now - victim.last_touched
+                if age <= 0.0:
+                    raise _ApiError(
+                        code="max_sessions",
+                        message=f"max concurrent sessions reached ({self._max})",
+                        http_status=429,
+                        retry_after=True,
+                    )
+                try:
+                    victim.env.close()
+                except Exception:
+                    logger.exception("env.close() raised on LRU eviction for sid=%s", victim_sid)
+                self._store.pop(victim_sid, None)
+            env = env_factory()
+            entry = SessionEntry(
+                env=env,
+                created_at=now,
+                last_touched=now,
+                reset_count=0,
+                lock=asyncio.Lock(),
+            )
+            self._store[sid] = entry
+            return entry
+
+    def touch(self, sid: str) -> tuple[SessionEntry | None, bool]:
+        """Update last_touched. Returns ``(entry, was_expired)``.
+
+        - ``(entry, False)`` on hit
+        - ``(None, True)`` if the entry was present but evicted by this call
+          due to TTL expiry
+        - ``(None, False)`` if there was never an entry under this sid
+        """
+        entry = self._store.get(sid)
+        if entry is None:
+            return None, False
+        now = _monotonic()
+        if now - entry.last_touched > self._ttl:
+            try:
+                entry.env.close()
+            except Exception:
+                logger.exception("env.close() raised on expired touch for sid=%s", sid)
+            self._store.pop(sid, None)
+            return None, True
+        new = replace(entry, last_touched=now)
+        self._store[sid] = new
+        return new, False
+
+    def evict(self, sid: str) -> SessionEntry | None:
+        """Pop a session out of the cache. Returns the removed entry or None."""
+        return self._store.pop(sid, None)
+
+    def sweep(self) -> int:
+        """Synchronous TTL sweep — evict every entry past TTL."""
+        now = _monotonic()
+        expired = [sid for sid, e in self._store.items() if now - e.last_touched > self._ttl]
+        for sid in expired:
+            entry = self._store.pop(sid)
+            try:
+                entry.env.close()
+            except Exception:
+                logger.exception("env.close() raised on sweep for sid=%s", sid)
+        if expired:
+            logger.info(
+                json.dumps(
+                    {
+                        "event": "session_sweep",
+                        "expired_count": len(expired),
+                        "cache_size": len(self._store),
+                    }
+                )
+            )
+        return len(expired)
+
+
+# ---------------------------------------------------------------------------
+# App state container
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class _AppState:
+    """Mutable (intentional) — owned by lifespan; readers go through getters."""
+
+    cache: SessionCache
+    models_ready: bool = False
+    sweep_task: asyncio.Task[None] | None = None
+    bearer_token: str = ""
+
+
+def _get_state(app: FastAPI) -> _AppState:
+    state: _AppState = app.state.driftcall
+    return state
+
+
+# ---------------------------------------------------------------------------
+# Lifespan — eager-load Kokoro + Whisper before serving (M6 guard)
+# ---------------------------------------------------------------------------
+
+
+def _eager_load_models() -> None:
+    """Force-load TTS + ASR singletons. Test patches this to avoid network."""
+    from cells.step_09_audio import get_asr_engine, get_tts_engine
+
+    get_tts_engine()
+    get_asr_engine()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    cache = SessionCache()
+    token = os.environ.get(_TOKEN_ENV_VAR, "")
+    if not token:
+        # Fail-fast per deploy_env_space.md §3.5.
+        raise RuntimeError(
+            f"{_TOKEN_ENV_VAR} environment variable not set; refusing to start"
+        )
+    state = _AppState(cache=cache, bearer_token=token)
+    app.state.driftcall = state
+
+    # Eager model load (M6 guard — must complete before serving).
+    try:
+        await asyncio.to_thread(_eager_load_models)
+    except Exception:
+        logger.exception("eager model load failed")
+        raise
+    state.models_ready = True
+
+    # Background TTL sweep.
+    async def _sweep_loop() -> None:
+        try:
+            while True:
+                await asyncio.sleep(_SWEEP_INTERVAL_S)
+                cache.sweep()
+        except asyncio.CancelledError:
+            raise
+
+    state.sweep_task = asyncio.create_task(_sweep_loop())
+    try:
+        yield
+    finally:
+        if state.sweep_task is not None:
+            state.sweep_task.cancel()
+            with contextlib.suppress(asyncio.CancelledError, Exception):
+                await state.sweep_task
+
+
+# ---------------------------------------------------------------------------
+# Body-size middleware (M11)
+# ---------------------------------------------------------------------------
+
+
+class _BodySizeMiddleware(BaseHTTPMiddleware):
+    def __init__(self, app: ASGIApp, *, max_bytes: int = _MAX_BODY_BYTES) -> None:
+        super().__init__(app)
+        self._max_bytes = max_bytes
+
+    async def dispatch(
+        self, request: Request, call_next: Callable[[Request], Awaitable[Response]]
+    ) -> Response:
+        cl = request.headers.get("content-length")
+        if cl is not None:
+            try:
+                cl_int = int(cl)
+            except ValueError:
+                cl_int = -1
+            if cl_int > self._max_bytes:
+                err = _ApiError(
+                    code="payload_too_large",
+                    message="request body exceeds 1 MiB",
+                    http_status=413,
+                )
+                return _error_response(err, _request_id(request))
+        return await call_next(request)
+
+
+# ---------------------------------------------------------------------------
+# Helpers — auth, headers, body parsing
+# ---------------------------------------------------------------------------
+
+
+def _request_id(request: Request) -> str:
+    return str(id(request))
+
+
+def _check_bearer(request: Request, state: _AppState) -> None:
+    auth = request.headers.get("authorization", "")
+    if not auth.startswith("Bearer "):
+        raise _ApiError(
+            code="unauthorized",
+            message="missing or non-Bearer Authorization header",
+            http_status=401,
+        )
+    token = auth[len("Bearer ") :].strip()
+    if token != state.bearer_token or not token:
+        raise _ApiError(
+            code="unauthorized",
+            message="invalid bearer token",
+            http_status=401,
+        )
+
+
+def _check_session_header(request: Request) -> str:
+    sid = request.headers.get("x-session-id", "")
+    if not sid or not _SESSION_ID_RE.match(sid):
+        raise _ApiError(
+            code="missing_session_id",
+            message="X-Session-Id header missing or malformed",
+            http_status=400,
+        )
+    return sid
+
+
+def _check_models_ready(state: _AppState) -> None:
+    if not state.models_ready:
+        raise _ApiError(
+            code="model_not_ready",
+            message="audio models still loading; retry shortly",
+            http_status=503,
+        )
+
+
+async def _parse_json_body(request: Request) -> dict[str, Any]:
+    raw = await request.body()
+    if len(raw) > _MAX_BODY_BYTES:
+        raise _ApiError(
+            code="payload_too_large",
+            message="request body exceeds 1 MiB",
+            http_status=413,
+        )
+    if not raw:
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except (json.JSONDecodeError, UnicodeDecodeError) as exc:
+        raise _ApiError(
+            code="bad_json",
+            message=f"malformed JSON: {exc.__class__.__name__}",
+            http_status=400,
+        ) from exc
+    if not isinstance(parsed, dict):
+        raise _ApiError(
+            code="bad_json",
+            message="request body must be a JSON object",
+            http_status=400,
+        )
+    return parsed
+
+
+# ---------------------------------------------------------------------------
+# Action / config validation (envelope-level — env owns deep validation)
+# ---------------------------------------------------------------------------
+
+
+def _build_action(raw: Any) -> DriftCallAction:
+    if not isinstance(raw, dict):
+        raise _ApiError(
+            code="invalid_action",
+            message="action must be a JSON object",
+            http_status=400,
+        )
+    atype_raw = raw.get("action_type")
+    if not isinstance(atype_raw, str):
+        raise _ApiError(
+            code="invalid_action",
+            message="action.action_type must be a string",
+            http_status=400,
+        )
+    try:
+        atype = ActionType(atype_raw)
+    except ValueError as exc:
+        raise _ApiError(
+            code="invalid_action",
+            message=f"unknown action_type {atype_raw!r}",
+            http_status=400,
+        ) from exc
+
+    tool_name = raw.get("tool_name")
+    tool_args = raw.get("tool_args")
+    message = raw.get("message")
+    confidence = raw.get("confidence")
+    rationale = raw.get("rationale")
+
+    # Action-type contract checks (deep checks happen inside env._validate_action).
+    if atype == ActionType.TOOL_CALL and (
+        tool_name is None or not isinstance(tool_name, str) or tool_args is None
+    ):
+        raise _ApiError(
+            code="invalid_action",
+            message="TOOL_CALL requires tool_name (str) and tool_args (object)",
+            http_status=400,
+        )
+    return DriftCallAction(
+        action_type=atype,
+        tool_name=tool_name if isinstance(tool_name, str) else None,
+        tool_args=tool_args if isinstance(tool_args, dict) else None,
+        message=message if isinstance(message, str) else None,
+        confidence=float(confidence) if isinstance(confidence, (int, float)) and not isinstance(confidence, bool) else None,
+        rationale=rationale if isinstance(rationale, str) else None,
+    )
+
+
+def _build_env_config(reset_body: dict[str, Any]) -> dict[str, Any]:
+    raw_cfg = reset_body.get("config")
+    if raw_cfg is None:
+        raw_cfg = {}
+    if not isinstance(raw_cfg, dict):
+        raise _ApiError(
+            code="invalid_action",
+            message="config must be a JSON object",
+            http_status=400,
+        )
+    return raw_cfg
+
+
+# ---------------------------------------------------------------------------
+# Serialization helpers
+# ---------------------------------------------------------------------------
+
+
+def _to_jsonable(obj: Any) -> Any:
+    """Recursively convert frozen dataclasses / tuples / enums to JSON-safe form."""
+    if dataclasses.is_dataclass(obj) and not isinstance(obj, type):
+        return {k: _to_jsonable(v) for k, v in dataclasses.asdict(obj).items()}
+    if isinstance(obj, ActionType):
+        return obj.value
+    if isinstance(obj, dict):
+        return {k: _to_jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_to_jsonable(v) for v in obj]
+    return obj
+
+
+# ---------------------------------------------------------------------------
+# Endpoint handlers (one function per route)
+# ---------------------------------------------------------------------------
+
+
+async def _handle_reset(request: Request, state: _AppState) -> Response:
+    _check_bearer(request, state)
+    _check_models_ready(state)
+    sid = _check_session_header(request)
+    body = await _parse_json_body(request)
+    cfg = _build_env_config(body)
+    seed_raw = body.get("seed")
+    if seed_raw is not None and (not isinstance(seed_raw, int) or isinstance(seed_raw, bool)):
+        raise _ApiError(
+            code="invalid_action",
+            message="seed must be an int or null",
+            http_status=400,
+        )
+    seed: int | None = seed_raw if isinstance(seed_raw, int) and not isinstance(seed_raw, bool) else None
+
+    cache = state.cache
+    # Per-session reset lock (§7.1).
+    existing = cache.get(sid)
+    if existing is not None and existing.lock.locked():
+        raise _ApiError(
+            code="reset_in_progress",
+            message="concurrent /reset on same session id",
+            http_status=409,
+        )
+
+    # Acquire lock (creates one if not present).
+    lock = await cache.acquire_lock(sid)
+    if lock.locked():
+        raise _ApiError(
+            code="reset_in_progress",
+            message="concurrent /reset on same session id",
+            http_status=409,
+        )
+
+    async with lock:
+        def _factory() -> DriftCallEnv:
+            try:
+                return DriftCallEnv(cfg)
+            except InvalidConfigError as exc:
+                raise _ApiError(
+                    code="invalid_action",
+                    message=f"invalid config: {exc}",
+                    http_status=400,
+                ) from exc
+
+        try:
+            entry = await cache.insert_or_replace(sid, _factory)
+        except _ApiError:
+            raise
+        except Exception as exc:
+            logger.exception("env construction failed for sid=%s", sid)
+            raise _ApiError(
+                code="internal_error",
+                message="env construction failed",
+                http_status=500,
+            ) from exc
+
+        try:
+            obs = await asyncio.to_thread(entry.env.reset, seed)
+        except InvalidConfigError as exc:
+            cache.evict(sid)
+            raise _ApiError(
+                code="invalid_action",
+                message=f"invalid config at reset: {exc}",
+                http_status=400,
+            ) from exc
+        except OSError as exc:
+            cache.evict(sid)
+            raise _ApiError(
+                code="io_error",
+                message=f"I/O error during reset: {exc.__class__.__name__}",
+                http_status=500,
+            ) from exc
+        except Exception as exc:
+            cache.evict(sid)
+            logger.exception("env.reset raised for sid=%s", sid)
+            raise _ApiError(
+                code="internal_error",
+                message="env.reset raised",
+                http_status=500,
+            ) from exc
+
+    body_out = {
+        "observation": _to_jsonable(obs),
+        "episode_id": entry.env.state().episode_id,
+        "max_turns": entry.env.state().max_turns,
+    }
+    return JSONResponse(status_code=200, content=body_out)
+
+
+async def _handle_step(request: Request, state: _AppState) -> Response:
+    _check_bearer(request, state)
+    _check_models_ready(state)
+    sid = _check_session_header(request)
+    body = await _parse_json_body(request)
+    raw_action = body.get("action")
+    action = _build_action(raw_action)
+
+    entry, was_expired = state.cache.touch(sid)
+    if entry is None:
+        if was_expired:
+            raise _ApiError(
+                code="session_expired",
+                message="session TTL expired; call /reset",
+                http_status=404,
+            )
+        raise _ApiError(
+            code="session_not_found",
+            message="X-Session-Id has no live session; call /reset",
+            http_status=404,
+        )
+
+    try:
+        obs = await asyncio.to_thread(entry.env.step, action)
+    except (InvalidActionError, UnknownToolError, UnknownDomainError) as exc:
+        raise _ApiError(
+            code="invalid_action",
+            message=str(exc),
+            http_status=400,
+        ) from exc
+    except (EnvNotReadyError, EnvClosedError, EpisodeAlreadyTerminalError) as exc:
+        raise _ApiError(
+            code="invalid_action",
+            message=str(exc),
+            http_status=400,
+        ) from exc
+    except OSError as exc:
+        raise _ApiError(
+            code="io_error",
+            message=f"I/O error during step: {exc.__class__.__name__}",
+            http_status=500,
+        ) from exc
+    except Exception as exc:
+        logger.exception("env.step raised for sid=%s", sid)
+        raise _ApiError(
+            code="internal_error",
+            message="env.step raised",
+            http_status=500,
+        ) from exc
+
+    reward: float | None = None
+    info: dict[str, Any] = {}
+    if entry.env.done():
+        try:
+            rewards = entry.env.rewards()
+            reward = float(getattr(rewards, "reward", 0.0))
+            info["terminated_by"] = entry.env.episode().terminated_by
+        except Exception:
+            reward = None
+
+    body_out = {
+        "observation": _to_jsonable(obs),
+        "reward": reward,
+        "done": bool(entry.env.done()),
+        "info": info,
+    }
+    return JSONResponse(status_code=200, content=body_out)
+
+
+async def _handle_state(request: Request, state: _AppState) -> Response:
+    _check_bearer(request, state)
+    _check_models_ready(state)
+    sid = _check_session_header(request)
+    entry, was_expired = state.cache.touch(sid)
+    if entry is None:
+        if was_expired:
+            raise _ApiError(
+                code="session_expired",
+                message="session TTL expired; call /reset",
+                http_status=404,
+            )
+        raise _ApiError(
+            code="session_not_found",
+            message="X-Session-Id has no live session; call /reset",
+            http_status=404,
+        )
+    try:
+        st = entry.env.state()
+    except EnvNotReadyError as exc:
+        raise _ApiError(
+            code="invalid_action",
+            message=str(exc),
+            http_status=400,
+        ) from exc
+    body_out = {"state": _to_jsonable(st), "turn": st.turn}
+    return JSONResponse(status_code=200, content=body_out)
+
+
+async def _handle_close(request: Request, state: _AppState) -> Response:
+    _check_bearer(request, state)
+    _check_models_ready(state)
+    sid = _check_session_header(request)
+    entry = state.cache.evict(sid)
+    if entry is None:
+        return JSONResponse(status_code=200, content={"closed": True, "final_state": None})
+    final_state: Any = None
+    try:
+        final_state = _to_jsonable(entry.env.state())
+    except EnvNotReadyError:
+        final_state = None
+    try:
+        entry.env.close()
+    except Exception:
+        logger.exception("env.close raised on /close for sid=%s", sid)
+    return JSONResponse(status_code=200, content={"closed": True, "final_state": final_state})
+
+
+# ---------------------------------------------------------------------------
+# App factory + route wiring
+# ---------------------------------------------------------------------------
+
+
+def create_app() -> FastAPI:
+    """Construct a fresh FastAPI app. Used by tests to get an isolated instance."""
+    app = FastAPI(lifespan=lifespan, title="DriftCall Env", version="0.1.0")
+    app.add_middleware(_BodySizeMiddleware, max_bytes=_MAX_BODY_BYTES)
+
+    @app.get("/healthz", response_class=PlainTextResponse)
+    async def healthz() -> PlainTextResponse:
+        return PlainTextResponse(content="ok", status_code=200)
+
+    @app.post("/reset")
+    async def reset_route(request: Request) -> Response:
+        try:
+            return await _handle_reset(request, _get_state(app))
+        except _ApiError as err:
+            return _error_response(err, _request_id(request))
+
+    @app.post("/step")
+    async def step_route(request: Request) -> Response:
+        try:
+            return await _handle_step(request, _get_state(app))
+        except _ApiError as err:
+            return _error_response(err, _request_id(request))
+
+    @app.get("/state")
+    async def state_route(request: Request) -> Response:
+        try:
+            return await _handle_state(request, _get_state(app))
+        except _ApiError as err:
+            return _error_response(err, _request_id(request))
+
+    @app.post("/close")
+    async def close_route(request: Request) -> Response:
+        try:
+            return await _handle_close(request, _get_state(app))
+        except _ApiError as err:
+            return _error_response(err, _request_id(request))
+
+    return app
+
+
+app = create_app()
+
+
+__all__ = [
+    "SessionCache",
+    "SessionEntry",
+    "app",
+    "create_app",
+    "lifespan",
+]

cells/_secrets.py

@@ -0,0 +1,47 @@
+"""DriftCall — hardcoded secrets for private-repo runs.
+
+This file contains credentials. Repository is private per user direction.
+Do NOT make this repository public without scrubbing this file from history:
+
+    git filter-repo --path cells/_secrets.py --invert-paths
+
+To rotate a key: replace the value below and the running training script
+will pick it up on next launch (init_wandb reads via os.environ first;
+this file is the fallback when env var is unset).
+"""
+
+from __future__ import annotations
+
+import os
+
+# wandb.ai API key — pasted by user 2026-04-25.
+# Rotate at https://wandb.ai/authorize → Reset, then update below.
+WANDB_API_KEY: str = "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"
+
+# Default project + mode — override via env if needed.
+WANDB_PROJECT: str = "driftcall"
+WANDB_ENTITY: str | None = None
+WANDB_MODE: str = "online"
+
+
+def export_to_env() -> None:
+    """Push hardcoded values into ``os.environ`` if not already set.
+
+    Called by ``init_wandb()`` at the start of each training run. Env-var
+    overrides take priority — set ``WANDB_API_KEY=...`` in the shell to bypass
+    this file without editing it.
+    """
+    os.environ.setdefault("WANDB_API_KEY", WANDB_API_KEY)
+    os.environ.setdefault("WANDB_PROJECT", WANDB_PROJECT)
+    if WANDB_ENTITY is not None:
+        os.environ.setdefault("WANDB_ENTITY", WANDB_ENTITY)
+    os.environ.setdefault("WANDB_MODE", WANDB_MODE)
+
+
+__all__ = [
+    "WANDB_API_KEY",
+    "WANDB_ENTITY",
+    "WANDB_MODE",
+    "WANDB_PROJECT",
+    "export_to_env",
+]

cells/step_01_install.md

@@ -0,0 +1,3 @@
+# Install dependencies
+
+Installs the pinned DriftCall runtime from `requirements.txt` and authenticates with the Hugging Face Hub when `HF_TOKEN` is set in the environment. On Colab this provisions the kernel; on a configured local machine the step is idempotent and returns immediately.

cells/step_01_install.py

@@ -0,0 +1,116 @@
+"""Cell 01 — Install pinned dependencies.
+
+Runs once at notebook boot. On Colab the notebook kernel is a bare Python 3
+install, so we ``pip install`` the flat pin set from ``requirements.txt``.
+Locally we skip reinstall if every pin is already importable.
+
+Also authenticates with the Hugging Face Hub when an ``HF_TOKEN`` environment
+variable is set; on interactive sessions the user can run ``hf auth login``
+separately. No network calls are attempted when ``HF_TOKEN`` is absent — the
+cell remains a no-op so offline unit tests pass.
+"""
+
+from __future__ import annotations
+
+import importlib.util
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+REQUIREMENTS_FILENAME = "requirements.txt"
+
+# Packages whose import name differs from their distribution name. Only list
+# the handful we actually probe with ``is_installed``; everything else uses
+# the distribution name verbatim.
+_IMPORT_ALIASES: dict[str, str] = {
+    "faster-whisper": "faster_whisper",
+    "huggingface_hub": "huggingface_hub",
+    "uvicorn[standard]": "uvicorn",
+    "pytest-cov": "pytest_cov",
+}
+
+
+def is_installed(distribution: str) -> bool:
+    """Return True iff the import name behind *distribution* is available."""
+
+    base = distribution.split("[", 1)[0].split(">", 1)[0].split("<", 1)[0]
+    base = base.split("==", 1)[0].split("~=", 1)[0].strip()
+    module = _IMPORT_ALIASES.get(distribution, _IMPORT_ALIASES.get(base, base))
+    module = module.replace("-", "_")
+    return importlib.util.find_spec(module) is not None
+
+
+def _find_requirements() -> Path | None:
+    """Locate ``requirements.txt`` alongside the project root (worktree-safe)."""
+
+    candidates = [
+        Path.cwd() / REQUIREMENTS_FILENAME,
+        Path(__file__).resolve().parent.parent / REQUIREMENTS_FILENAME,
+    ]
+    for candidate in candidates:
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def is_colab() -> bool:
+    """Detect Google Colab runtime (``google.colab`` is always importable there)."""
+
+    return importlib.util.find_spec("google.colab") is not None
+
+
+def pip_install(requirements_path: Path) -> int:
+    """Invoke ``pip install -r <requirements_path>`` via the current interpreter."""
+
+    cmd = [sys.executable, "-m", "pip", "install", "--quiet", "-r", str(requirements_path)]
+    completed = subprocess.run(cmd, check=False)
+    return completed.returncode
+
+
+def hf_login_if_token_present() -> bool:
+    """Log into HF Hub using ``HF_TOKEN`` env var. Returns True on success."""
+
+    token = os.environ.get("HF_TOKEN")
+    if not token:
+        return False
+    try:
+        from huggingface_hub import login
+    except ImportError:
+        return False
+    login(token=token, add_to_git_credential=False)
+    return True
+
+
+def install(force: bool = False) -> int:
+    """Top-level cell body. Idempotent: skips reinstall when pins already import.
+
+    :param force: Reinstall even if every dependency is importable.
+    :returns: 0 when deps already satisfied or pip succeeded; non-zero on pip failure.
+    """
+
+    requirements_path = _find_requirements()
+    if requirements_path is None:
+        return 0
+
+    if not force and not is_colab():
+        declared = [
+            line.strip()
+            for line in requirements_path.read_text(encoding="utf-8").splitlines()
+            if line.strip() and not line.strip().startswith("#")
+        ]
+        if declared and all(is_installed(pkg) for pkg in declared):
+            hf_login_if_token_present()
+            return 0
+
+    rc = pip_install(requirements_path)
+    if rc == 0:
+        hf_login_if_token_present()
+    return rc
+
+
+# Cell body: execute on import so the Colab notebook runs end-to-end.
+# Skip the side effect when the cell is being imported under the pytest
+# runner or when a caller opts out via ``DRIFTCALL_SKIP_INSTALL=1``.
+_skip_marker = "pytest" in sys.modules or os.environ.get("DRIFTCALL_SKIP_INSTALL") == "1"
+_rc = 0 if _skip_marker else install()

cells/step_02_imports.md

@@ -0,0 +1,3 @@
+# Consolidated imports
+
+Pulls in the stdlib + third-party modules used throughout the notebook so each later cell can focus on its module logic. Heavy optional wheels (numpy, fastapi, soundfile, etc.) are loaded defensively — a missing wheel surfaces as `None` from `get_optional(...)` rather than aborting the notebook.

cells/step_02_imports.py

@@ -0,0 +1,94 @@
+"""Cell 02 — Consolidated imports.
+
+Grouped re-exports of stdlib + third-party modules used across later cells.
+Later cells ``from cells.step_02_imports import X`` (or import names directly);
+this keeps the notebook top DRY while the individual ``.py`` files remain
+standalone importable modules for the test suite and the FastAPI server.
+
+Unused-import warnings on re-exported names are silenced via the
+``[tool.ruff.lint.per-file-ignores]`` override in ``pyproject.toml`` rather
+than per-line ``noqa`` pragmas.
+"""
+
+from __future__ import annotations
+
+# ---------------------------------------------------------------------------
+# Standard library
+# ---------------------------------------------------------------------------
+import dataclasses
+import hashlib
+import importlib
+import io
+import json
+import logging
+import math
+import os
+import random
+import re
+import sys
+import time
+import uuid
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Literal, Protocol, TypeVar
+
+# ---------------------------------------------------------------------------
+# Third-party — heavy deps are guarded so test collection does not explode
+# when a single wheel is missing on a fresh Colab runtime.
+# ---------------------------------------------------------------------------
+
+_OPTIONAL_MODULES: tuple[str, ...] = (
+    "numpy",
+    "yaml",
+    "fastapi",
+    "uvicorn",
+    "pydantic",
+    "soundfile",
+)
+
+_loaded: dict[str, Any] = {}
+for _name in _OPTIONAL_MODULES:
+    try:
+        _loaded[_name] = importlib.import_module(_name)
+    except ImportError:  # pragma: no cover — exercised on fresh Colab only
+        _loaded[_name] = None
+
+
+def get_optional(name: str) -> Any:
+    """Return an optional third-party module or ``None`` when unavailable."""
+
+    return _loaded.get(name)
+
+
+# Names re-exported for downstream cells. Everything imported above is fair
+# game via ``from cells.step_02_imports import X``.
+__all__ = (
+    # stdlib re-exports
+    "Any",
+    "Callable",
+    "Enum",
+    "Literal",
+    "Mapping",
+    "Path",
+    "Protocol",
+    "Sequence",
+    "TypeVar",
+    "dataclass",
+    "dataclasses",
+    "field",
+    "hashlib",
+    "io",
+    "json",
+    "logging",
+    "math",
+    "os",
+    "random",
+    "re",
+    "sys",
+    "time",
+    "uuid",
+    # helpers
+    "get_optional",
+)

cells/step_03_fixtures.md

@@ -0,0 +1,3 @@
+# Load static fixtures
+
+Lazy, NFC-normalized, validated loaders for the four authored data artifacts: `task_briefs/templates.yaml`, `task_briefs/i18n.yaml`, `drift_patterns/drifts.yaml`, and the per-domain `api_schemas/*` JSON registries. Loaders raise typed `DatasetError` subclasses on any authoring drift, schema break, or cross-file consistency violation (datasets.md §3.3).

cells/step_03_fixtures.py

@@ -0,0 +1,738 @@
+"""Cell 03 — Static fixture loaders for DriftCall data artifacts.
+
+Implements the loader contract in ``docs/modules/datasets.md`` §§2–5. Each
+loader is a lazy path-keyed singleton that reads, NFC-normalizes, and validates
+a single on-disk artifact, then returns a frozen dataclass wrapped in
+``MappingProxyType`` where mappings appear.
+
+Artifacts covered:
+
+  * ``data/task_briefs/templates.yaml``    — TemplateLibrary
+  * ``data/task_briefs/i18n.yaml``         — I18nLibrary
+  * ``data/drift_patterns/drifts.yaml``    — DriftPatternLibrary
+  * ``data/api_schemas/<domain>/v<N>.json`` — APISchemaRegistry
+
+Loaders raise one of the ``DatasetError`` subclasses declared below on any
+authoring error — malformed YAML/JSON, schema violation, NFC failure, or the
+21 cross-file consistency assertions enumerated in datasets.md §3.3.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import threading
+import unicodedata
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Literal
+
+import yaml
+from jsonschema import Draft202012Validator
+from jsonschema.exceptions import SchemaError
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"]
+Domain = Literal["airline", "cab", "restaurant", "hotel"]
+
+_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"})
+_PRIMARY_DOMAINS: frozenset[str] = frozenset({"airline", "cab", "restaurant", "hotel"})
+_VENDOR_DOMAINS: frozenset[str] = frozenset(
+    {"airline", "cab", "restaurant", "hotel", "payment"}
+)
+_DRIFT_TYPES: frozenset[str] = frozenset(
+    {"schema", "policy", "tnc", "pricing", "auth"}
+)
+_EXPECTED_PATTERN_COUNT = 20
+_EXPECTED_SCHEMA_VERSIONS: Mapping[str, tuple[str, ...]] = MappingProxyType(
+    {
+        "airline": ("v1", "v2", "v3"),
+        "cab": ("v1", "v2", "v3"),
+        "restaurant": ("v1", "v2", "v3"),
+        "hotel": ("v1", "v2", "v3"),
+        "payment": ("v1", "v2"),
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class DatasetError(Exception):
+    """Base class for every fixture loader error."""
+
+
+class DatasetFileMissingError(DatasetError):
+    """Raised when an authored data file is absent from disk."""
+
+
+class MalformedYAMLError(DatasetError):
+    """Raised when a YAML file fails to parse (file path + line preserved)."""
+
+
+class MalformedJSONError(DatasetError):
+    """Raised when a JSON file fails to parse (file path + line preserved)."""
+
+
+class DatasetSchemaError(DatasetError):
+    """Raised on type / shape / required-key violations of an authored file."""
+
+
+class UnknownLanguageKeyError(DatasetError):
+    """Raised when a language key ∉ LanguageCode appears in a YAML file."""
+
+
+class UnicodeNFDError(DatasetError):
+    """Raised when a loaded string is not NFC-normalized after defensive pass."""
+
+
+class DriftPatternOrphanError(DatasetError):
+    """Raised when a drift pattern references an API schema version that is missing."""
+
+
+class DuplicateDriftPatternIdError(DatasetError):
+    """Raised when drifts.yaml contains two entries sharing the same id."""
+
+
+# ---------------------------------------------------------------------------
+# Frozen dataclasses (library types)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SlotDistribution:
+    kind: Literal["choices", "uniform"]
+    choices: tuple[str, ...] | None = None
+    low: float | None = None
+    high: float | None = None
+    step: float | None = None
+
+
+@dataclass(frozen=True)
+class Template:
+    template_id: str
+    domain: str
+    intent: str
+    min_stage: Literal[1, 2, 3]
+    required_slots: tuple[str, ...]
+    optional_slots: tuple[str, ...]
+    constraints_template: Mapping[str, SlotDistribution]
+    drift_slot_tags: tuple[str, ...]
+    language_variants: Mapping[str, tuple[str, ...]]
+
+
+@dataclass(frozen=True)
+class TemplateLibrary:
+    templates: tuple[Template, ...]
+    source_sha256: str
+
+
+@dataclass(frozen=True)
+class I18nLibrary:
+    strings: Mapping[str, Mapping[str, str]]
+    source_sha256: str
+
+
+@dataclass(frozen=True)
+class DriftPattern:
+    id: str
+    drift_type: str
+    domain: str
+    from_version: str
+    to_version: str
+    description: str
+    mutation: Mapping[str, Any]
+    detection_hints: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class DriftPatternLibrary:
+    patterns: Mapping[str, DriftPattern]
+    by_domain: Mapping[str, tuple[str, ...]]
+    by_type: Mapping[str, tuple[str, ...]]
+    source_sha256: str
+
+
+@dataclass(frozen=True)
+class APISchema:
+    domain: str
+    version: str
+    schema: Mapping[str, Any]
+    source_sha256: str
+
+
+@dataclass(frozen=True)
+class APISchemaRegistry:
+    schemas: Mapping[str, Mapping[str, APISchema]]
+
+    def get(self, domain: str, version: str) -> APISchema:
+        try:
+            return self.schemas[domain][version]
+        except KeyError as exc:
+            raise DatasetSchemaError(
+                f"no schema registered for domain={domain!r} version={version!r}"
+            ) from exc
+
+    def versions(self, domain: str) -> tuple[str, ...]:
+        try:
+            return tuple(self.schemas[domain].keys())
+        except KeyError as exc:
+            raise DatasetSchemaError(f"unknown domain {domain!r}") from exc
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _nfc(value: str) -> str:
+    """NFC-normalize ``value``; raise on post-normalization non-NFC (defensive)."""
+
+    normalized = unicodedata.normalize("NFC", value)
+    if not unicodedata.is_normalized("NFC", normalized):
+        raise UnicodeNFDError(
+            f"string failed NFC round-trip: {value!r}"
+        )
+    return normalized
+
+
+def _nfc_deep(value: Any) -> Any:
+    """Recursively NFC-normalize every string inside nested dict/list structures."""
+
+    if isinstance(value, str):
+        return _nfc(value)
+    if isinstance(value, list):
+        return [_nfc_deep(v) for v in value]
+    if isinstance(value, tuple):
+        return tuple(_nfc_deep(v) for v in value)
+    if isinstance(value, dict):
+        return {_nfc(k) if isinstance(k, str) else k: _nfc_deep(v) for k, v in value.items()}
+    return value
+
+
+def _file_bytes(path: Path) -> bytes:
+    try:
+        return path.read_bytes()
+    except FileNotFoundError as exc:
+        raise DatasetFileMissingError(f"{path} not found") from exc
+    except OSError as exc:
+        raise DatasetFileMissingError(f"{path}: {exc}") from exc
+
+
+def _sha256_hex(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _parse_yaml(path: Path) -> Any:
+    data = _file_bytes(path)
+    try:
+        return yaml.safe_load(data)
+    except yaml.YAMLError as exc:
+        mark = getattr(exc, "problem_mark", None)
+        line = mark.line + 1 if mark is not None else -1
+        raise MalformedYAMLError(f"{path}:{line}: {exc}") from exc
+
+
+def _parse_json(path: Path) -> Any:
+    data = _file_bytes(path)
+    try:
+        return json.loads(data)
+    except json.JSONDecodeError as exc:
+        raise MalformedJSONError(f"{path}:{exc.lineno}: {exc.msg}") from exc
+
+
+def _require(cond: bool, msg: str) -> None:
+    if not cond:
+        raise DatasetSchemaError(msg)
+
+
+def _as_tuple_of_str(value: Any, field: str, *, path: Path) -> tuple[str, ...]:
+    _require(isinstance(value, list), f"{path}: {field!r} must be a list")
+    for item in value:
+        _require(isinstance(item, str), f"{path}: {field!r} items must be strings")
+    return tuple(_nfc(v) for v in value)
+
+
+# ---------------------------------------------------------------------------
+# Path-keyed singleton caches
+# ---------------------------------------------------------------------------
+
+_TEMPLATE_CACHE: dict[Path, TemplateLibrary] = {}
+_I18N_CACHE: dict[Path, I18nLibrary] = {}
+_DRIFT_CACHE: dict[Path, DriftPatternLibrary] = {}
+_SCHEMA_CACHE: dict[Path, APISchemaRegistry] = {}
+_CACHE_LOCK = threading.RLock()
+
+
+# ---------------------------------------------------------------------------
+# Templates loader
+# ---------------------------------------------------------------------------
+
+
+def _build_slot_distribution(raw: Any, slot_name: str, path: Path) -> SlotDistribution:
+    _require(
+        isinstance(raw, dict),
+        f"{path}: slot {slot_name!r} definition must be a mapping",
+    )
+    if "choices" in raw:
+        choices = _as_tuple_of_str(raw["choices"], f"{slot_name}.choices", path=path)
+        _require(
+            len(choices) >= 1,
+            f"{path}: slot {slot_name!r} choices must be non-empty",
+        )
+        return SlotDistribution(kind="choices", choices=choices)
+    if raw.get("distribution") == "uniform":
+        for req in ("low", "high", "step"):
+            _require(
+                req in raw,
+                f"{path}: slot {slot_name!r} uniform dist missing {req!r}",
+            )
+            _require(
+                isinstance(raw[req], (int, float)),
+                f"{path}: slot {slot_name!r} {req!r} must be numeric",
+            )
+        low = float(raw["low"])
+        high = float(raw["high"])
+        step = float(raw["step"])
+        _require(
+            high >= low and step > 0,
+            f"{path}: slot {slot_name!r} invalid uniform range",
+        )
+        return SlotDistribution(kind="uniform", low=low, high=high, step=step)
+    raise DatasetSchemaError(
+        f"{path}: slot {slot_name!r} must declare either 'choices' or 'distribution: uniform'"
+    )
+
+
+def _build_template(raw: Any, path: Path) -> Template:
+    _require(isinstance(raw, dict), f"{path}: each template must be a mapping")
+    for req in (
+        "template_id",
+        "domain",
+        "intent",
+        "min_stage",
+        "required_slots",
+        "optional_slots",
+        "constraints_template",
+        "drift_slot_tags",
+        "language_variants",
+    ):
+        _require(req in raw, f"{path}: template missing required key {req!r}")
+
+    template_id = _nfc(str(raw["template_id"]))
+    domain = _nfc(str(raw["domain"]))
+    intent = _nfc(str(raw["intent"]))
+    min_stage = raw["min_stage"]
+
+    _require(
+        domain in _PRIMARY_DOMAINS,
+        f"{path}: template {template_id!r} has unknown domain {domain!r}",
+    )
+    _require(
+        min_stage in (1, 2, 3),
+        f"{path}: template {template_id!r} min_stage must be 1|2|3, got {min_stage!r}",
+    )
+
+    required_slots = _as_tuple_of_str(
+        raw["required_slots"], f"{template_id}.required_slots", path=path
+    )
+    optional_slots = _as_tuple_of_str(
+        raw["optional_slots"], f"{template_id}.optional_slots", path=path
+    )
+    drift_slot_tags = _as_tuple_of_str(
+        raw["drift_slot_tags"], f"{template_id}.drift_slot_tags", path=path
+    )
+
+    raw_constraints = raw["constraints_template"]
+    _require(
+        isinstance(raw_constraints, dict),
+        f"{path}: template {template_id!r} constraints_template must be a mapping",
+    )
+    constraints = {
+        _nfc(slot_name): _build_slot_distribution(slot_def, slot_name, path)
+        for slot_name, slot_def in raw_constraints.items()
+    }
+
+    raw_variants = raw["language_variants"]
+    _require(
+        isinstance(raw_variants, dict),
+        f"{path}: template {template_id!r} language_variants must be a mapping",
+    )
+    variants: dict[str, tuple[str, ...]] = {}
+    for lang_key, utterances in raw_variants.items():
+        _require(
+            isinstance(lang_key, str),
+            f"{path}: template {template_id!r} language key must be string",
+        )
+        if lang_key not in _LANGUAGE_CODES:
+            raise UnknownLanguageKeyError(
+                f"{path}: template {template_id!r} has unknown language key {lang_key!r}"
+            )
+        _require(
+            isinstance(utterances, list) and len(utterances) >= 1,
+            f"{path}: template {template_id!r} variants[{lang_key!r}] must be non-empty list",
+        )
+        for u in utterances:
+            _require(
+                isinstance(u, str),
+                f"{path}: template {template_id!r} variants[{lang_key!r}] items must be strings",
+            )
+        variants[lang_key] = tuple(_nfc(u) for u in utterances)
+
+    missing_langs = _LANGUAGE_CODES - variants.keys()
+    _require(
+        not missing_langs,
+        f"{path}: template {template_id!r} missing language_variants for {sorted(missing_langs)}",
+    )
+
+    return Template(
+        template_id=template_id,
+        domain=domain,
+        intent=intent,
+        min_stage=min_stage,
+        required_slots=required_slots,
+        optional_slots=optional_slots,
+        constraints_template=MappingProxyType(constraints),
+        drift_slot_tags=drift_slot_tags,
+        language_variants=MappingProxyType(variants),
+    )
+
+
+def load_templates(
+    path: Path | str = "data/task_briefs/templates.yaml",
+) -> TemplateLibrary:
+    """Load + validate the task-brief template library (datasets.md §3.3)."""
+
+    resolved = Path(path).resolve()
+    cached = _TEMPLATE_CACHE.get(resolved)
+    if cached is not None:
+        return cached
+    with _CACHE_LOCK:
+        cached = _TEMPLATE_CACHE.get(resolved)
+        if cached is not None:
+            return cached
+        raw = _parse_yaml(resolved)
+        _require(
+            isinstance(raw, list) and len(raw) >= 1,
+            f"{resolved}: templates.yaml must be a non-empty list",
+        )
+        templates = tuple(_build_template(entry, resolved) for entry in raw)
+
+        seen_ids = set()
+        seen_domains = set()
+        for tpl in templates:
+            _require(
+                tpl.template_id not in seen_ids,
+                f"{resolved}: duplicate template_id {tpl.template_id!r}",
+            )
+            seen_ids.add(tpl.template_id)
+            seen_domains.add(tpl.domain)
+        missing_primary = _PRIMARY_DOMAINS - seen_domains
+        _require(
+            not missing_primary,
+            f"{resolved}: missing templates for domains {sorted(missing_primary)}",
+        )
+
+        library = TemplateLibrary(
+            templates=templates,
+            source_sha256=_sha256_hex(_file_bytes(resolved)),
+        )
+        _TEMPLATE_CACHE[resolved] = library
+        return library
+
+
+# ---------------------------------------------------------------------------
+# I18n loader
+# ---------------------------------------------------------------------------
+
+
+def load_i18n(path: Path | str = "data/task_briefs/i18n.yaml") -> I18nLibrary:
+    """Load + NFC-normalize the i18n lookup (datasets.md §4.2)."""
+
+    resolved = Path(path).resolve()
+    cached = _I18N_CACHE.get(resolved)
+    if cached is not None:
+        return cached
+    with _CACHE_LOCK:
+        cached = _I18N_CACHE.get(resolved)
+        if cached is not None:
+            return cached
+        raw = _parse_yaml(resolved)
+        _require(
+            isinstance(raw, dict) and len(raw) >= 1,
+            f"{resolved}: i18n.yaml must be a non-empty mapping",
+        )
+
+        strings: dict[str, Mapping[str, str]] = {}
+        for lang_key, entries in raw.items():
+            if lang_key not in _LANGUAGE_CODES:
+                raise UnknownLanguageKeyError(
+                    f"{resolved}: unknown language key {lang_key!r}"
+                )
+            _require(
+                isinstance(entries, dict),
+                f"{resolved}: i18n[{lang_key!r}] must be a mapping",
+            )
+            inner: dict[str, str] = {}
+            for k, v in entries.items():
+                _require(
+                    isinstance(k, str) and isinstance(v, str),
+                    f"{resolved}: i18n[{lang_key!r}] entries must be string→string",
+                )
+                inner[_nfc(k)] = _nfc(v)
+            strings[lang_key] = MappingProxyType(inner)
+
+        missing = _LANGUAGE_CODES - strings.keys()
+        _require(
+            not missing,
+            f"{resolved}: i18n.yaml missing languages {sorted(missing)}",
+        )
+
+        library = I18nLibrary(
+            strings=MappingProxyType(strings),
+            source_sha256=_sha256_hex(_file_bytes(resolved)),
+        )
+        _I18N_CACHE[resolved] = library
+        return library
+
+
+# ---------------------------------------------------------------------------
+# Drift patterns loader
+# ---------------------------------------------------------------------------
+
+
+def _build_drift_pattern(raw: Any, path: Path) -> DriftPattern:
+    _require(isinstance(raw, dict), f"{path}: each drift entry must be a mapping")
+    for req in (
+        "id",
+        "drift_type",
+        "domain",
+        "from_version",
+        "to_version",
+        "description",
+        "mutation",
+        "detection_hints",
+    ):
+        _require(req in raw, f"{path}: drift entry missing required key {req!r}")
+
+    pid = _nfc(str(raw["id"]))
+    drift_type = _nfc(str(raw["drift_type"]))
+    domain = _nfc(str(raw["domain"]))
+    from_version = _nfc(str(raw["from_version"]))
+    to_version = _nfc(str(raw["to_version"]))
+    description = _nfc(str(raw["description"]))
+
+    _require(
+        drift_type in _DRIFT_TYPES,
+        f"{path}: drift {pid!r} has unknown drift_type {drift_type!r}",
+    )
+    _require(
+        domain in _VENDOR_DOMAINS,
+        f"{path}: drift {pid!r} has unknown domain {domain!r}",
+    )
+
+    mutation_raw = raw["mutation"]
+    _require(
+        isinstance(mutation_raw, dict) and len(mutation_raw) >= 1,
+        f"{path}: drift {pid!r} mutation must be a non-empty mapping",
+    )
+    mutation = _nfc_deep(mutation_raw)
+
+    hints_raw = raw["detection_hints"]
+    _require(
+        isinstance(hints_raw, list) and len(hints_raw) >= 1,
+        f"{path}: drift {pid!r} detection_hints must be a non-empty list",
+    )
+    for h in hints_raw:
+        _require(
+            isinstance(h, str) and h.strip() != "",
+            f"{path}: drift {pid!r} detection_hints entries must be non-empty strings",
+        )
+    hints = tuple(_nfc(h) for h in hints_raw)
+
+    return DriftPattern(
+        id=pid,
+        drift_type=drift_type,
+        domain=domain,
+        from_version=from_version,
+        to_version=to_version,
+        description=description,
+        mutation=MappingProxyType(dict(mutation)),
+        detection_hints=hints,
+    )
+
+
+def load_drift_patterns(
+    path: Path | str = "data/drift_patterns/drifts.yaml",
+    *,
+    schema_registry: APISchemaRegistry | None = None,
+) -> DriftPatternLibrary:
+    """Load + validate the 20-pattern drift catalogue (datasets.md §3.3, drift_injector.md §4.4)."""
+
+    resolved = Path(path).resolve()
+    cached = _DRIFT_CACHE.get(resolved)
+    if cached is not None:
+        return cached
+    with _CACHE_LOCK:
+        cached = _DRIFT_CACHE.get(resolved)
+        if cached is not None:
+            return cached
+        raw = _parse_yaml(resolved)
+        _require(
+            isinstance(raw, list),
+            f"{resolved}: drifts.yaml must be a list",
+        )
+        _require(
+            len(raw) == _EXPECTED_PATTERN_COUNT,
+            f"{resolved}: expected {_EXPECTED_PATTERN_COUNT} drift patterns, got {len(raw)}",
+        )
+
+        patterns_list = [_build_drift_pattern(entry, resolved) for entry in raw]
+
+        ids_seen: dict[str, int] = {}
+        for idx, p in enumerate(patterns_list):
+            if p.id in ids_seen:
+                raise DuplicateDriftPatternIdError(
+                    f"{resolved}: duplicate drift pattern id {p.id!r} at entries {ids_seen[p.id]} and {idx}"
+                )
+            ids_seen[p.id] = idx
+
+        registry = schema_registry if schema_registry is not None else load_api_schemas()
+        for p in patterns_list:
+            for ver in (p.from_version, p.to_version):
+                if p.domain not in registry.schemas or ver not in registry.schemas[p.domain]:
+                    raise DriftPatternOrphanError(
+                        f"{resolved}: drift {p.id!r} references missing schema "
+                        f"{p.domain}/{ver}"
+                    )
+
+        patterns = MappingProxyType({p.id: p for p in patterns_list})
+        by_domain: dict[str, list[str]] = {}
+        by_type: dict[str, list[str]] = {}
+        for p in patterns_list:
+            by_domain.setdefault(p.domain, []).append(p.id)
+            by_type.setdefault(p.drift_type, []).append(p.id)
+
+        library = DriftPatternLibrary(
+            patterns=patterns,
+            by_domain=MappingProxyType({k: tuple(v) for k, v in by_domain.items()}),
+            by_type=MappingProxyType({k: tuple(v) for k, v in by_type.items()}),
+            source_sha256=_sha256_hex(_file_bytes(resolved)),
+        )
+        _DRIFT_CACHE[resolved] = library
+        return library
+
+
+# ---------------------------------------------------------------------------
+# API schema loader
+# ---------------------------------------------------------------------------
+
+
+def _load_single_schema(domain: str, version: str, path: Path) -> APISchema:
+    data = _parse_json(path)
+    _require(
+        isinstance(data, dict),
+        f"{path}: JSON Schema must be an object",
+    )
+    try:
+        Draft202012Validator.check_schema(data)
+    except SchemaError as exc:
+        raise DatasetSchemaError(
+            f"{path}: not a valid JSON Schema 2020-12: {exc.message}"
+        ) from exc
+    return APISchema(
+        domain=domain,
+        version=version,
+        schema=MappingProxyType(_nfc_deep(data)),
+        source_sha256=_sha256_hex(_file_bytes(path)),
+    )
+
+
+def load_api_schemas(
+    root: Path | str = "data/api_schemas",
+) -> APISchemaRegistry:
+    """Load every ``<domain>/v<N>.json`` file under ``root`` (datasets.md §4.4)."""
+
+    resolved = Path(root).resolve()
+    cached = _SCHEMA_CACHE.get(resolved)
+    if cached is not None:
+        return cached
+    with _CACHE_LOCK:
+        cached = _SCHEMA_CACHE.get(resolved)
+        if cached is not None:
+            return cached
+        if not resolved.is_dir():
+            raise DatasetFileMissingError(f"{resolved} is not a directory")
+
+        schemas: dict[str, dict[str, APISchema]] = {}
+        for domain, expected_versions in _EXPECTED_SCHEMA_VERSIONS.items():
+            domain_dir = resolved / domain
+            if not domain_dir.is_dir():
+                raise DatasetFileMissingError(
+                    f"{resolved}: expected domain directory {domain_dir}"
+                )
+            per_version: dict[str, APISchema] = {}
+            for version in expected_versions:
+                file_path = domain_dir / f"{version}.json"
+                per_version[version] = _load_single_schema(domain, version, file_path)
+            schemas[domain] = per_version
+
+        registry = APISchemaRegistry(
+            schemas=MappingProxyType(
+                {d: MappingProxyType(v) for d, v in schemas.items()}
+            ),
+        )
+        _SCHEMA_CACHE[resolved] = registry
+        return registry
+
+
+# ---------------------------------------------------------------------------
+# Cache-reset helper (tests only)
+# ---------------------------------------------------------------------------
+
+
+def _reset_caches() -> None:
+    """Clear every loader cache. Intended for use by tests only."""
+
+    with _CACHE_LOCK:
+        _TEMPLATE_CACHE.clear()
+        _I18N_CACHE.clear()
+        _DRIFT_CACHE.clear()
+        _SCHEMA_CACHE.clear()
+
+
+__all__ = [
+    "APISchema",
+    "APISchemaRegistry",
+    "DatasetError",
+    "DatasetFileMissingError",
+    "DatasetSchemaError",
+    "Domain",
+    "DriftPattern",
+    "DriftPatternLibrary",
+    "DriftPatternOrphanError",
+    "DuplicateDriftPatternIdError",
+    "I18nLibrary",
+    "LanguageCode",
+    "MalformedJSONError",
+    "MalformedYAMLError",
+    "SlotDistribution",
+    "Template",
+    "TemplateLibrary",
+    "UnicodeNFDError",
+    "UnknownLanguageKeyError",
+    "load_api_schemas",
+    "load_drift_patterns",
+    "load_i18n",
+    "load_templates",
+]

cells/step_04_models.md

@@ -0,0 +1,3 @@
+# Step 04 — Core Dataclasses
+
+Declares the seven immutable types that cross module boundaries in DriftCall: `ActionType`, `DriftCallAction`, `ToolResult`, `DriftEvent`, `GoalSpec`, `DriftCallObservation`, and `DriftCallState`. All dataclasses are `frozen=True`; the module is pure shape with zero runtime behavior, imported by every other cell, the FastAPI server, and the reward suite.

cells/step_04_models.py

@@ -0,0 +1,99 @@
+"""DriftCall core dataclasses.
+
+Implements docs/modules/models.md §2. Every declaration is pure shape; no
+runtime logic lives here. All dataclasses are frozen. Invariants in §3.5 are
+enforced by downstream modules (env.py, drift_injector.py, vendors/*), not here.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+from typing import Any, Literal
+
+
+class ActionType(StrEnum):
+    TOOL_CALL = "tool_call"
+    SPEAK = "speak"
+    CLARIFY = "clarify"
+    PROBE_SCHEMA = "probe_schema"
+    SUBMIT = "submit"
+    ABORT = "abort"
+
+
+@dataclass(frozen=True)
+class DriftCallAction:
+    action_type: ActionType
+    tool_name: str | None = None
+    tool_args: dict[str, Any] | None = None
+    message: str | None = None
+    confidence: float | None = None
+    rationale: str | None = None
+
+
+@dataclass(frozen=True)
+class ToolResult:
+    tool_name: str
+    status: Literal["ok", "schema_error", "policy_error", "auth_error", "timeout"]
+    response: dict[str, Any]
+    schema_version: str
+    latency_ms: int
+
+
+@dataclass(frozen=True)
+class DriftEvent:
+    turn: int
+    drift_type: Literal["schema", "policy", "tnc", "pricing", "auth"]
+    domain: str
+    description: str
+    from_version: str
+    to_version: str
+    pattern_id: str
+
+
+@dataclass(frozen=True)
+class GoalSpec:
+    domain: str
+    intent: str
+    slots: dict[str, Any]
+    constraints: dict[str, Any]
+    language: Literal["hi", "ta", "kn", "en", "hinglish"]
+    seed_utterance: str
+
+
+@dataclass(frozen=True)
+class DriftCallObservation:
+    turn: int
+    goal: GoalSpec
+    last_transcript: str
+    last_lang: str
+    last_confidence: float
+    tool_results: tuple[ToolResult, ...]
+    drift_log: tuple[DriftEvent, ...]
+    budget_remaining: int
+    available_tools: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class DriftCallState:
+    episode_id: str
+    goal: GoalSpec
+    vendor_states: dict[str, dict[str, Any]]
+    schema_versions: dict[str, str]
+    drift_schedule: tuple[DriftEvent, ...]
+    drift_fired: tuple[DriftEvent, ...]
+    turn: int
+    max_turns: int
+    actions: tuple[DriftCallAction, ...]
+    done: bool
+
+
+__all__ = [
+    "ActionType",
+    "DriftCallAction",
+    "ToolResult",
+    "DriftEvent",
+    "GoalSpec",
+    "DriftCallObservation",
+    "DriftCallState",
+]

cells/step_05_vendors.md

@@ -0,0 +1 @@
+Cell 05 — Mock vendor APIs. Five pure-Python vendor modules (airline, cab, restaurant, hotel, payment) consolidated into one cell. Each exposes a frozen `*State` dataclass plus five helpers (`dispatch`, `initial_state`, `apply_schema_mutation`, `describe_schema`, `emit_side_channel_if_pending`) and a `TOOLS` registry. Implements `docs/modules/vendors.md` §§2–8: three schema versions per domain, integer-INR monetary invariant, deterministic timeout via `hash((seed,tool,args)) & 0x7F == 0`, per-domain idempotency keys returning `DUPLICATE_*` policy errors, consumed-on-read side-channel notices, and cross-domain auth cascades from `payment.charge`.

cells/step_05_vendors.py

@@ -0,0 +1,2413 @@
+"""Cell 05 — Mock vendor APIs.
+
+Consolidated cell implementing five vendor submodules (airline, cab,
+restaurant, hotel, payment) as namespaces on a single module. Every vendor
+exposes: frozen ``*State`` dataclass, ``initial_state``, ``dispatch``,
+``apply_schema_mutation``, ``describe_schema``, ``emit_side_channel_if_pending``,
+and ``TOOLS`` tuple. Implements ``docs/modules/vendors.md`` §§2–8.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from dataclasses import dataclass, replace
+from datetime import datetime, timedelta
+from types import SimpleNamespace
+from typing import TYPE_CHECKING, Any, Literal
+
+from cells.step_04_models import GoalSpec, ToolResult
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+
+class UnknownSchemaVersionError(ValueError):
+    """Raised by a serializer when an unrecognised schema_version is passed."""
+
+
+class UnknownMutationOperatorError(ValueError):
+    """Raised by apply_schema_mutation when the operator key is not known."""
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers
+# ---------------------------------------------------------------------------
+
+
+_LATENCY_OK_LO, _LATENCY_OK_HI = 50, 400
+_LATENCY_TIMEOUT_LO, _LATENCY_TIMEOUT_HI = 5000, 7000
+_TIMEOUT_MASK = 0x7F  # 1-in-128 trigger rate
+
+
+def _canonical_args_json(tool_args: Mapping[str, Any] | None) -> str:
+    """Stable sorted whitespace-free JSON for hashing (vendors.md §3.1)."""
+
+    return json.dumps(
+        dict(tool_args or {}),
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+        default=str,
+    )
+
+
+def _stable_digest(*parts: Any) -> int:
+    """Cross-process-stable 64-bit integer digest.
+
+    Python's built-in ``hash()`` is PYTHONHASHSEED-randomized for strings, so
+    it cannot be used for replay-stable determinism (vendors.md §3.1). We use
+    blake2b truncated to 8 bytes instead.
+    """
+
+    blob = "||".join(repr(p) for p in parts).encode("utf-8")
+    digest_bytes = hashlib.blake2b(blob, digest_size=8).digest()
+    return int.from_bytes(digest_bytes, "big", signed=False)
+
+
+def _is_timeout(episode_seed: int, tool_name: str, tool_args: Mapping[str, Any] | None) -> bool:
+    """Deterministic 1/128 timeout trigger — vendors.md §3.1."""
+
+    digest = _stable_digest(episode_seed, tool_name, _canonical_args_json(tool_args))
+    return (digest & _TIMEOUT_MASK) == 0
+
+
+def _seeded_uniform(episode_seed: int, tag: str, lo: int, hi: int) -> int:
+    """Deterministic uniform int in ``[lo, hi]``. No wall clock."""
+
+    h = _stable_digest(episode_seed, tag) & 0x7FFFFFFF
+    span = hi - lo + 1
+    return lo + (h % span)
+
+
+def _make_id(domain: str, episode_seed: int, op: str, key: Any, records: Mapping[str, Any]) -> str:
+    """Deterministic 4-hex ID with ``-R{retry}`` suffix on prefix collisions.
+
+    ``records`` is scanned for prefix matches to derive the replay-stable
+    retry counter (vendors.md §3.8).
+    """
+
+    prefix = f"{domain[:3].upper()}-{_stable_digest(episode_seed, op, key) & 0xFFFF:04X}"
+    matches = sum(1 for existing_id in records if existing_id.startswith(prefix))
+    if matches == 0:
+        return prefix
+    return f"{prefix}-R{matches + 1}"
+
+
+def _integer_inr(value: Any) -> int:
+    """Coerce to int, rejecting bools. Uses ``math.floor(x + 0.5)`` for rounding."""
+
+    if isinstance(value, bool):
+        raise TypeError("monetary fields must be int, not bool")
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        return int(math.floor(value + 0.5))
+    raise TypeError(f"non-numeric monetary value: {value!r}")
+
+
+def _timeout_result(
+    tool_name: str,
+    episode_seed: int,
+    schema_version: str,
+) -> ToolResult:
+    latency = _seeded_uniform(episode_seed, f"{tool_name}:timeout", _LATENCY_TIMEOUT_LO, _LATENCY_TIMEOUT_HI)
+    return ToolResult(
+        tool_name=tool_name,
+        status="timeout",
+        response={"error_code": "TIMEOUT", "hint": "retry with same args"},
+        schema_version=schema_version,
+        latency_ms=latency,
+    )
+
+
+def _ok_latency(episode_seed: int, tool_name: str) -> int:
+    return _seeded_uniform(episode_seed, f"{tool_name}:ok", _LATENCY_OK_LO, _LATENCY_OK_HI)
+
+
+def _normalize_items(items: list[dict[str, Any]]) -> tuple[tuple[str, int, tuple[str, ...]], ...]:
+    """Normalise restaurant items for idempotency keying (vendors.md §3.9)."""
+
+    out: list[tuple[str, int, tuple[str, ...]]] = []
+    for item in items:
+        dish_id = str(item["dish_id"]).strip().lower()
+        qty = int(item["qty"])
+        mods_raw = item.get("modifiers", []) or []
+        mods = tuple(sorted(str(m).strip().lower() for m in mods_raw))
+        out.append((dish_id, qty, mods))
+    return tuple(sorted(out))
+
+
+# ---------------------------------------------------------------------------
+# Airline
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class AirlinePolicy:
+    booking_window_hours: int = 24
+    required_book_fields: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class AirlineTnC:
+    baggage_cabin_kg: int = 7
+    reschedule_fee_pct: int = 0
+
+
+@dataclass(frozen=True)
+class AirlinePricing:
+    convenience_fee_inr: int = 0
+
+
+@dataclass(frozen=True)
+class AirlineState:
+    schema_version: str
+    bookings: dict[str, dict[str, Any]]
+    flight_roster_cache: dict[str, tuple[dict[str, Any], ...]]
+    policy: AirlinePolicy
+    tnc: AirlineTnC
+    pricing: AirlinePricing
+    side_channel_notice: str | None
+
+
+_AIRLINE_BASE_FLIGHTS: tuple[dict[str, Any], ...] = (
+    {"flight_id": "6E-2345", "depart_hour": 18, "depart_min": 30, "base_price": 7200, "seats": 14},
+    {"flight_id": "AI-501", "depart_hour": 20, "depart_min": 15, "base_price": 6800, "seats": 3},
+    {"flight_id": "UK-878", "depart_hour": 9, "depart_min": 10, "base_price": 5200, "seats": 9},
+    {"flight_id": "SG-102", "depart_hour": 14, "depart_min": 50, "base_price": 8400, "seats": 22},
+)
+
+
+def _airline_time_window(hour: int) -> str:
+    if 5 <= hour < 12:
+        return "morning"
+    if 12 <= hour < 17:
+        return "afternoon"
+    if 17 <= hour < 22:
+        return "evening"
+    return "late_night"
+
+
+def _airline_search_flights(
+    from_: str, to: str, date: str, episode_seed: int
+) -> tuple[dict[str, Any], ...]:
+    key = f"{from_}->{to}|{date}"
+    h = _stable_digest(episode_seed, key) & 0xFFFF
+    count = 3 + (h % 3)
+    return _AIRLINE_BASE_FLIGHTS[:count]
+
+
+def _airline_serialize_flight(flight: dict[str, Any], from_: str, to: str, date: str, version: str) -> dict[str, Any]:
+    depart = f"{date}T{flight['depart_hour']:02d}:{flight['depart_min']:02d}:00+05:30"
+    base: dict[str, Any] = {
+        "flight_id": flight["flight_id"],
+        "from": from_,
+        "to": to,
+        "depart": depart,
+        "seats_left": int(flight["seats"]),
+    }
+    if version == "v1":
+        base["price"] = int(flight["base_price"])
+        base["currency"] = "INR"
+    elif version in ("v2", "v3"):
+        base["total_fare_inr"] = int(flight["base_price"])
+    else:
+        raise UnknownSchemaVersionError(version)
+    return base
+
+
+def airline_initial_state(episode_seed: int, goal: GoalSpec) -> AirlineState:
+    _ = (episode_seed, goal)
+    return AirlineState(
+        schema_version="v1",
+        bookings={},
+        flight_roster_cache={},
+        policy=AirlinePolicy(booking_window_hours=24, required_book_fields=()),
+        tnc=AirlineTnC(),
+        pricing=AirlinePricing(),
+        side_channel_notice=None,
+    )
+
+
+def airline_search(
+    vendor_state: AirlineState,
+    schema_version: str,
+    from_: str,
+    to: str,
+    date: str,
+    max_price_inr: int | None = None,
+    time_window: Literal["morning", "afternoon", "evening", "late_night"] | None = None,
+    episode_seed: int = 0,
+) -> ToolResult:
+    flights = _airline_search_flights(from_, to, date, episode_seed)
+    serialized: list[dict[str, Any]] = []
+    for f in flights:
+        if time_window is not None and _airline_time_window(f["depart_hour"]) != time_window:
+            continue
+        if max_price_inr is not None and int(f["base_price"]) > int(max_price_inr):
+            continue
+        serialized.append(_airline_serialize_flight(f, from_, to, date, schema_version))
+    return ToolResult(
+        tool_name="airline.search",
+        status="ok",
+        response={"results": serialized},
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "airline.search"),
+    )
+
+
+def _airline_book_impl(
+    vendor_state: AirlineState,
+    schema_version: str,
+    payment_state: PaymentState,
+    flight_id: str,
+    payment_token: str,
+    passenger_count: int | None,
+    passenger_name: str | None,
+    episode_seed: int,
+    now_ist: datetime,
+) -> tuple[ToolResult, AirlineState, PaymentState]:
+    flight = next((f for f in _AIRLINE_BASE_FLIGHTS if f["flight_id"] == flight_id), None)
+    if flight is None:
+        return (
+            ToolResult(
+                tool_name="airline.book",
+                status="schema_error",
+                response={
+                    "error_code": "MISSING_FIELD",
+                    "field_name": "flight_id",
+                    "hint": "unknown flight_id",
+                },
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "airline.book"),
+            ),
+            vendor_state,
+            payment_state,
+        )
+
+    if schema_version == "v3" and passenger_count is None:
+        return (
+            ToolResult(
+                tool_name="airline.book",
+                status="schema_error",
+                response={
+                    "error_code": "MISSING_PASSENGER_COUNT",
+                    "hint": "v3 requires passenger_count on book",
+                },
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "airline.book"),
+            ),
+            vendor_state,
+            payment_state,
+        )
+
+    depart_date = now_ist.date().isoformat()
+    depart_dt = now_ist.replace(
+        hour=int(flight["depart_hour"]),
+        minute=int(flight["depart_min"]),
+        second=0,
+        microsecond=0,
+    )
+    window_hours = int(vendor_state.policy.booking_window_hours)
+    if (
+        depart_dt - now_ist < timedelta(hours=window_hours)
+        and depart_dt >= now_ist
+        and window_hours < 24
+        and now_ist.hour >= 14
+    ):
+        return (
+                ToolResult(
+                    tool_name="airline.book",
+                    status="policy_error",
+                    response={
+                        "error_code": "BOOKING_WINDOW_CLOSED",
+                        "hint": "same-day booking closed after 14:00 IST",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "airline.book"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+
+    idempotency_key = (flight_id, (passenger_name or "").strip().lower(), depart_date)
+    for existing_id, record in vendor_state.bookings.items():
+        existing_key = (
+            record.get("flight_id"),
+            str(record.get("passenger_name") or "").strip().lower(),
+            record.get("depart_date"),
+        )
+        if existing_key == idempotency_key:
+            return (
+                ToolResult(
+                    tool_name="airline.book",
+                    status="policy_error",
+                    response={
+                        "error_code": "DUPLICATE_BOOKING",
+                        "existing_id": existing_id,
+                        "original_ts": str(record.get("created_at_ist", "")),
+                        "hint": "identical booking already exists",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "airline.book"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+
+    amount = int(flight["base_price"])
+    charge_result, new_payment_state = _payment_charge_internal(
+        payment_state=payment_state,
+        amount_inr=amount,
+        payment_token=payment_token,
+        mfa_code=None,
+        episode_seed=episode_seed,
+        order_ref=f"airline:{flight_id}:{depart_date}",
+    )
+    if charge_result.status != "ok":
+        propagated = _propagate_payment_error(charge_result, "airline.book", schema_version, episode_seed)
+        return propagated, vendor_state, payment_state
+
+    booking_id = _make_id("airline", episode_seed, "book", (flight_id, passenger_name, depart_date), vendor_state.bookings)
+    new_record: dict[str, Any] = {
+        "booking_id": booking_id,
+        "flight_id": flight_id,
+        "depart": f"{depart_date}T{flight['depart_hour']:02d}:{flight['depart_min']:02d}:00+05:30",
+        "depart_date": depart_date,
+        "passenger_name": passenger_name,
+        "seats_confirmed": int(passenger_count or 1),
+        "payment_status": "captured",
+        "created_at_ist": now_ist.isoformat(),
+    }
+    if schema_version == "v1":
+        new_record["price"] = amount
+    else:
+        new_record["total_fare_inr"] = amount
+    if schema_version == "v3":
+        new_record["passenger_count"] = int(passenger_count or 1)
+
+    new_bookings = {**vendor_state.bookings, booking_id: new_record}
+    new_state = replace(vendor_state, bookings=new_bookings)
+    response = {k: v for k, v in new_record.items() if k not in ("depart_date", "created_at_ist", "passenger_name")}
+    return (
+        ToolResult(
+            tool_name="airline.book",
+            status="ok",
+            response=response,
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "airline.book"),
+        ),
+        new_state,
+        new_payment_state,
+    )
+
+
+def airline_cancel(
+    vendor_state: AirlineState,
+    schema_version: str,
+    booking_id: str,
+    episode_seed: int = 0,
+) -> tuple[ToolResult, AirlineState]:
+    if booking_id not in vendor_state.bookings:
+        return (
+            ToolResult(
+                tool_name="airline.cancel",
+                status="policy_error",
+                response={"error_code": "MISSING_FIELD", "hint": "booking_id not found"},
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "airline.cancel"),
+            ),
+            vendor_state,
+        )
+    new_bookings = {k: v for k, v in vendor_state.bookings.items() if k != booking_id}
+    new_state = replace(vendor_state, bookings=new_bookings)
+    return (
+        ToolResult(
+            tool_name="airline.cancel",
+            status="ok",
+            response={"booking_id": booking_id, "cancelled": True},
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "airline.cancel"),
+        ),
+        new_state,
+    )
+
+
+def airline_get_booking(
+    vendor_state: AirlineState,
+    schema_version: str,
+    booking_id: str,
+    episode_seed: int = 0,
+) -> ToolResult:
+    record = vendor_state.bookings.get(booking_id)
+    if record is None:
+        return ToolResult(
+            tool_name="airline.get_booking",
+            status="schema_error",
+            response={"error_code": "MISSING_FIELD", "field_name": "booking_id", "hint": "unknown booking_id"},
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "airline.get_booking"),
+        )
+    payload = {k: v for k, v in record.items() if k not in ("depart_date", "created_at_ist", "passenger_name")}
+    return ToolResult(
+        tool_name="airline.get_booking",
+        status="ok",
+        response=payload,
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "airline.get_booking"),
+    )
+
+
+def airline_apply_schema_mutation(
+    vendor_state: AirlineState, mutation: Mapping[str, Any]
+) -> AirlineState:
+    state = vendor_state
+    next_version = state.schema_version
+    policy = state.policy
+    for op, payload in mutation.items():
+        if op == "rename":
+            if "price" in payload and payload["price"] == "total_fare_inr":
+                next_version = "v2"
+        elif op == "remove":
+            fields = payload if isinstance(payload, list) else [payload]
+            if "currency" in fields and next_version == "v1":
+                next_version = "v2"
+        elif op == "require_new_field":
+            if isinstance(payload, dict) and "passenger_count" in payload:
+                policy = replace(policy, required_book_fields=tuple(sorted(set(policy.required_book_fields) | {"passenger_count"})))
+                next_version = "v3"
+        elif op == "time_window_shrink":
+            if isinstance(payload, dict) and "booking_window_hours" in payload:
+                policy = replace(policy, booking_window_hours=int(payload["booking_window_hours"]))
+        elif op == "change_type" or op == "tnc_text_swap":
+            continue
+        elif op == "side_channel_notice_append":
+            state = replace(state, side_channel_notice=str(payload))
+        elif op == "fee_append":
+            if isinstance(payload, dict) and "convenience_fee_inr" in payload:
+                state = replace(state, pricing=replace(state.pricing, convenience_fee_inr=int(payload["convenience_fee_inr"])))
+        elif op == "pricing_restructure" or op in {"numeric_bump", "enum_expand", "policy_flag_flip", "auth_scope_bump", "token_version_bump"}:
+            continue
+        else:
+            raise UnknownMutationOperatorError(op)
+    return replace(state, schema_version=next_version, policy=policy)
+
+
+def airline_describe_schema(vendor_state: AirlineState, schema_version: str) -> dict[str, Any]:
+    if schema_version == "v1":
+        fields = {
+            "flight_id": "str",
+            "from": "str",
+            "to": "str",
+            "depart": "str",
+            "price": "int",
+            "currency": "str",
+            "seats_left": "int",
+        }
+        removed: list[str] = []
+    elif schema_version == "v2":
+        fields = {
+            "flight_id": "str",
+            "from": "str",
+            "to": "str",
+            "depart": "str",
+            "total_fare_inr": "int",
+            "seats_left": "int",
+        }
+        removed = ["price", "currency"]
+    elif schema_version == "v3":
+        fields = {
+            "flight_id": "str",
+            "from": "str",
+            "to": "str",
+            "depart": "str",
+            "total_fare_inr": "int",
+            "seats_left": "int",
+            "passenger_count": "int",
+        }
+        removed = ["price", "currency"]
+    else:
+        raise UnknownSchemaVersionError(schema_version)
+    return {"version": schema_version, "fields": fields, "removed_from_prior": removed}
+
+
+def airline_emit_side_channel_if_pending(
+    vendor_state: AirlineState,
+) -> tuple[str | None, AirlineState]:
+    if vendor_state.side_channel_notice is None:
+        return None, vendor_state
+    notice = vendor_state.side_channel_notice
+    return notice, replace(vendor_state, side_channel_notice=None)
+
+
+AIRLINE_TOOLS: tuple[str, ...] = (
+    "airline.search",
+    "airline.book",
+    "airline.cancel",
+    "airline.get_booking",
+)
+
+
+# ---------------------------------------------------------------------------
+# Cab
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CabPolicy:
+    vehicle_class_enum: tuple[str, ...] = ("mini", "sedan")
+    mini_reject_school_hours: bool = False
+
+
+@dataclass(frozen=True)
+class CabPricing:
+    base_per_km_inr: int = 12
+    surge_factor_pct: int = 100
+    toll_bundled: bool = True
+    fare_breakdown: bool = False
+
+
+@dataclass(frozen=True)
+class CabTnC:
+    cancel_fee_inr: int = 0
+
+
+@dataclass(frozen=True)
+class CabState:
+    schema_version: str
+    rides: dict[str, dict[str, Any]]
+    policy: CabPolicy
+    pricing: CabPricing
+    tnc: CabTnC
+    side_channel_notice: str | None
+
+
+def cab_initial_state(episode_seed: int, goal: GoalSpec) -> CabState:
+    _ = (episode_seed, goal)
+    return CabState(
+        schema_version="v1",
+        rides={},
+        policy=CabPolicy(),
+        pricing=CabPricing(),
+        tnc=CabTnC(),
+        side_channel_notice=None,
+    )
+
+
+def _cab_fare(pickup: str, drop: str, vehicle_class: str, episode_seed: int) -> int:
+    base = 80
+    key_hash = _stable_digest(pickup.strip().lower(), drop.strip().lower(), episode_seed) & 0x3FF
+    distance = 50 + (key_hash % 250)
+    multipliers = {"mini": 100, "sedan": 130, "suv": 170, "infant_seat_sedan": 150}
+    mul = multipliers.get(vehicle_class, 100)
+    return int(base + (distance * mul) // 100)
+
+
+def _cab_eta(pickup: str, episode_seed: int) -> int:
+    return 3 + (_stable_digest(pickup.strip().lower(), episode_seed) & 0xF)
+
+
+def _cab_serialize(
+    pickup: str,
+    drop: str,
+    vehicle_class: str,
+    fare: int,
+    eta_min: int,
+    schema_version: str,
+    pricing: CabPricing,
+) -> dict[str, Any]:
+    if schema_version == "v1":
+        return {
+            "pickup": pickup,
+            "drop": drop,
+            "vehicle_class": vehicle_class,
+            "fare_inr": int(fare),
+            "eta_min": int(eta_min),
+        }
+    if schema_version == "v2":
+        return {
+            "pickup": pickup,
+            "drop": drop,
+            "vehicle_class": vehicle_class,
+            "fare_inr": int(fare),
+            "eta_min": int(eta_min),
+        }
+    if schema_version == "v3":
+        base = int(fare * 75 // 100)
+        surge = int(fare * 12 // 100)
+        tolls = int(fare * 6 // 100)
+        gst = int(fare - base - surge - tolls)
+        breakdown = {"base": base, "surge": surge, "tolls": tolls, "gst": gst}
+        total = base + surge + tolls + gst
+        if total != int(fare):
+            # Defensive self-check — adjust gst to preserve invariant
+            breakdown["gst"] = int(fare) - base - surge - tolls
+        return {
+            "pickup": pickup,
+            "drop": drop,
+            "vehicle_class": vehicle_class,
+            "fare_breakdown": breakdown,
+            "total_inr": int(fare),
+            "eta_min": int(eta_min),
+        }
+    raise UnknownSchemaVersionError(schema_version)
+
+
+def cab_estimate(
+    vendor_state: CabState,
+    schema_version: str,
+    pickup: str,
+    drop: str,
+    vehicle_class: str,
+    pickup_time_ist: str,
+    episode_seed: int = 0,
+) -> ToolResult:
+    if vehicle_class not in vendor_state.policy.vehicle_class_enum:
+        return ToolResult(
+            tool_name="cab.estimate",
+            status="policy_error",
+            response={
+                "error_code": "VEHICLE_CLASS_UNAVAILABLE",
+                "available": list(vendor_state.policy.vehicle_class_enum),
+                "hint": "requested vehicle_class not in current enum",
+            },
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "cab.estimate"),
+        )
+    fare = _cab_fare(pickup, drop, vehicle_class, episode_seed)
+    eta = _cab_eta(pickup, episode_seed)
+    payload = _cab_serialize(pickup, drop, vehicle_class, fare, eta, schema_version, vendor_state.pricing)
+    return ToolResult(
+        tool_name="cab.estimate",
+        status="ok",
+        response=payload,
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "cab.estimate"),
+    )
+
+
+def _cab_book_impl(
+    vendor_state: CabState,
+    schema_version: str,
+    payment_state: PaymentState,
+    pickup: str,
+    drop: str,
+    vehicle_class: str,
+    pickup_time_ist: str,
+    payment_token: str,
+    episode_seed: int,
+    now_ist: datetime,
+) -> tuple[ToolResult, CabState, PaymentState]:
+    if vehicle_class not in vendor_state.policy.vehicle_class_enum:
+        return (
+            ToolResult(
+                tool_name="cab.book",
+                status="policy_error",
+                response={
+                    "error_code": "VEHICLE_CLASS_UNAVAILABLE",
+                    "available": list(vendor_state.policy.vehicle_class_enum),
+                    "hint": "requested vehicle_class not in current enum",
+                },
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "cab.book"),
+            ),
+            vendor_state,
+            payment_state,
+        )
+
+    if (
+        vendor_state.policy.mini_reject_school_hours
+        and vehicle_class == "mini"
+        and 7 <= now_ist.hour < 9
+    ):
+        return (
+                ToolResult(
+                    tool_name="cab.book",
+                    status="policy_error",
+                    response={
+                        "error_code": "SCHOOL_HOURS_MINI_REJECTED",
+                        "available": [v for v in vendor_state.policy.vehicle_class_enum if v != "mini"],
+                        "hint": "mini rejected during 07:00-09:00 IST",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "cab.book"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+
+    idempotency_key = (
+        pickup.strip().lower(),
+        drop.strip().lower(),
+        pickup_time_ist.strip(),
+        vehicle_class,
+    )
+    for existing_id, record in vendor_state.rides.items():
+        existing_key = (
+            str(record.get("pickup") or "").strip().lower(),
+            str(record.get("drop") or "").strip().lower(),
+            str(record.get("pickup_time_ist") or "").strip(),
+            record.get("vehicle_class"),
+        )
+        if existing_key == idempotency_key:
+            return (
+                ToolResult(
+                    tool_name="cab.book",
+                    status="policy_error",
+                    response={
+                        "error_code": "DUPLICATE_RIDE",
+                        "existing_id": existing_id,
+                        "original_ts": str(record.get("created_at_ist", "")),
+                        "hint": "identical ride already booked",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "cab.book"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+
+    fare = _cab_fare(pickup, drop, vehicle_class, episode_seed)
+    charge_result, new_payment_state = _payment_charge_internal(
+        payment_state=payment_state,
+        amount_inr=fare,
+        payment_token=payment_token,
+        mfa_code=None,
+        episode_seed=episode_seed,
+        order_ref=f"cab:{pickup}:{drop}:{pickup_time_ist}",
+    )
+    if charge_result.status != "ok":
+        return (
+            _propagate_payment_error(charge_result, "cab.book", schema_version, episode_seed),
+            vendor_state,
+            payment_state,
+        )
+
+    ride_id = _make_id("cab", episode_seed, "ride", idempotency_key, vendor_state.rides)
+    eta = _cab_eta(pickup, episode_seed)
+    serialized = _cab_serialize(pickup, drop, vehicle_class, fare, eta, schema_version, vendor_state.pricing)
+    new_record: dict[str, Any] = {
+        "ride_id": ride_id,
+        **serialized,
+        "pickup_time_ist": pickup_time_ist,
+        "created_at_ist": now_ist.isoformat(),
+        "payment_status": "captured",
+    }
+    new_rides = {**vendor_state.rides, ride_id: new_record}
+    new_state = replace(vendor_state, rides=new_rides)
+    response = {k: v for k, v in new_record.items() if k != "created_at_ist"}
+    return (
+        ToolResult(
+            tool_name="cab.book",
+            status="ok",
+            response=response,
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "cab.book"),
+        ),
+        new_state,
+        new_payment_state,
+    )
+
+
+def cab_cancel(
+    vendor_state: CabState,
+    schema_version: str,
+    ride_id: str,
+    episode_seed: int = 0,
+) -> tuple[ToolResult, CabState]:
+    if ride_id not in vendor_state.rides:
+        return (
+            ToolResult(
+                tool_name="cab.cancel",
+                status="policy_error",
+                response={"error_code": "MISSING_FIELD", "hint": "ride_id not found"},
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "cab.cancel"),
+            ),
+            vendor_state,
+        )
+    new_rides = {k: v for k, v in vendor_state.rides.items() if k != ride_id}
+    new_state = replace(vendor_state, rides=new_rides)
+    return (
+        ToolResult(
+            tool_name="cab.cancel",
+            status="ok",
+            response={"ride_id": ride_id, "cancelled": True},
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "cab.cancel"),
+        ),
+        new_state,
+    )
+
+
+def cab_apply_schema_mutation(
+    vendor_state: CabState, mutation: Mapping[str, Any]
+) -> CabState:
+    state = vendor_state
+    next_version = state.schema_version
+    policy = state.policy
+    pricing = state.pricing
+    for op, payload in mutation.items():
+        if op == "enum_expand":
+            new_vals = payload.get("vehicle_class_enum", []) if isinstance(payload, dict) else []
+            enum = tuple(dict.fromkeys([*policy.vehicle_class_enum, *new_vals]))
+            policy = replace(policy, vehicle_class_enum=enum)
+            if next_version == "v1":
+                next_version = "v2"
+        elif op == "policy_flag_flip":
+            if isinstance(payload, dict) and "mini_reject_school_hours" in payload:
+                policy = replace(policy, mini_reject_school_hours=bool(payload["mini_reject_school_hours"]))
+            if next_version == "v1":
+                next_version = "v2"
+        elif op == "pricing_restructure":
+            pricing = replace(pricing, fare_breakdown=True)
+            if next_version in ("v1", "v2"):
+                next_version = "v3"
+        elif op == "fee_append":
+            continue
+        elif op == "side_channel_notice_append":
+            state = replace(state, side_channel_notice=str(payload))
+        elif op == "tnc_text_swap":
+            if isinstance(payload, dict) and "cancel_fee_inr" in payload:
+                state = replace(state, tnc=replace(state.tnc, cancel_fee_inr=int(payload["cancel_fee_inr"])))
+        elif op in {"rename", "remove", "require_new_field", "change_type", "numeric_bump", "time_window_shrink", "auth_scope_bump", "token_version_bump"}:
+            continue
+        else:
+            raise UnknownMutationOperatorError(op)
+    return replace(state, schema_version=next_version, policy=policy, pricing=pricing)
+
+
+def cab_describe_schema(vendor_state: CabState, schema_version: str) -> dict[str, Any]:
+    if schema_version == "v1":
+        fields = {
+            "pickup": "str",
+            "drop": "str",
+            "vehicle_class": "str",
+            "fare_inr": "int",
+            "eta_min": "int",
+        }
+        removed: list[str] = []
+    elif schema_version == "v2":
+        fields = {
+            "pickup": "str",
+            "drop": "str",
+            "vehicle_class": "str",
+            "fare_inr": "int",
+            "eta_min": "int",
+        }
+        removed = []
+    elif schema_version == "v3":
+        fields = {
+            "pickup": "str",
+            "drop": "str",
+            "vehicle_class": "str",
+            "fare_breakdown": "dict[str, int]",
+            "total_inr": "int",
+            "eta_min": "int",
+        }
+        removed = ["fare_inr"]
+    else:
+        raise UnknownSchemaVersionError(schema_version)
+    return {"version": schema_version, "fields": fields, "removed_from_prior": removed}
+
+
+def cab_emit_side_channel_if_pending(vendor_state: CabState) -> tuple[str | None, CabState]:
+    if vendor_state.side_channel_notice is None:
+        return None, vendor_state
+    notice = vendor_state.side_channel_notice
+    return notice, replace(vendor_state, side_channel_notice=None)
+
+
+CAB_TOOLS: tuple[str, ...] = ("cab.estimate", "cab.book", "cab.cancel")
+
+
+# ---------------------------------------------------------------------------
+# Restaurant
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class RestaurantPolicy:
+    min_order_inr: int = 199
+    require_modifiers: bool = False
+
+
+@dataclass(frozen=True)
+class RestaurantSemantics:
+    veg_only_excludes_egg: bool = False
+
+
+@dataclass(frozen=True)
+class RestaurantTnC:
+    refund_window_min: int = 10
+
+
+@dataclass(frozen=True)
+class RestaurantState:
+    schema_version: str
+    orders: dict[str, dict[str, Any]]
+    menu_cache: dict[str, tuple[dict[str, Any], ...]]
+    policy: RestaurantPolicy
+    semantics: RestaurantSemantics
+    tnc: RestaurantTnC
+    side_channel_notice: str | None
+
+
+_RESTAURANT_MENU: tuple[dict[str, Any], ...] = (
+    {"restaurant_id": "BLR-BIR-0123", "city": "Bengaluru", "cuisine": "biryani",
+     "dishes": (
+         {"dish_id": "BIR-001", "name": "Chicken Biryani", "price": 220, "is_veg": False, "has_egg": False},
+         {"dish_id": "BIR-002", "name": "Egg Biryani", "price": 180, "is_veg": True, "has_egg": True},
+         {"dish_id": "BIR-003", "name": "Veg Biryani", "price": 160, "is_veg": True, "has_egg": False},
+     )},
+    {"restaurant_id": "BLR-SOU-0456", "city": "Bengaluru", "cuisine": "south_indian",
+     "dishes": (
+         {"dish_id": "DOS-001", "name": "Masala Dosa", "price": 120, "is_veg": True, "has_egg": False},
+         {"dish_id": "DOS-002", "name": "Egg Dosa", "price": 140, "is_veg": True, "has_egg": True},
+     )},
+)
+
+
+def restaurant_initial_state(episode_seed: int, goal: GoalSpec) -> RestaurantState:
+    _ = (episode_seed, goal)
+    return RestaurantState(
+        schema_version="v1",
+        orders={},
+        menu_cache={},
+        policy=RestaurantPolicy(min_order_inr=199),
+        semantics=RestaurantSemantics(veg_only_excludes_egg=False),
+        tnc=RestaurantTnC(),
+        side_channel_notice=None,
+    )
+
+
+def restaurant_search(
+    vendor_state: RestaurantState,
+    schema_version: str,
+    city: str,
+    cuisine: str | None = None,
+    veg_only: bool = False,
+    max_price_inr: int | None = None,
+    episode_seed: int = 0,
+) -> ToolResult:
+    results: list[dict[str, Any]] = []
+    for rec in _RESTAURANT_MENU:
+        if rec["city"].lower() != city.strip().lower():
+            continue
+        if cuisine is not None and rec["cuisine"] != cuisine:
+            continue
+        dishes = []
+        for dish in rec["dishes"]:
+            if veg_only and not dish["is_veg"]:
+                continue
+            if veg_only and vendor_state.semantics.veg_only_excludes_egg and dish["has_egg"]:
+                continue
+            if max_price_inr is not None and int(dish["price"]) > int(max_price_inr):
+                continue
+            dishes.append({"dish_id": dish["dish_id"], "name": dish["name"], "price": int(dish["price"])})
+        if dishes:
+            results.append({
+                "restaurant_id": rec["restaurant_id"],
+                "city": rec["city"],
+                "cuisine": rec["cuisine"],
+                "dishes": dishes,
+            })
+    return ToolResult(
+        tool_name="restaurant.search",
+        status="ok",
+        response={"results": results},
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "restaurant.search"),
+    )
+
+
+def _restaurant_lookup_price(dish_id: str) -> int | None:
+    for rec in _RESTAURANT_MENU:
+        for dish in rec["dishes"]:
+            if dish["dish_id"] == dish_id:
+                return int(dish["price"])
+    return None
+
+
+def _restaurant_order_impl(
+    vendor_state: RestaurantState,
+    schema_version: str,
+    payment_state: PaymentState,
+    restaurant_id: str,
+    items: list[dict[str, Any]],
+    payment_token: str,
+    episode_seed: int,
+    now_ist: datetime,
+) -> tuple[ToolResult, RestaurantState, PaymentState]:
+    if schema_version == "v3" or vendor_state.policy.require_modifiers:
+        for it in items:
+            if "modifiers" not in it:
+                return (
+                    ToolResult(
+                        tool_name="restaurant.order",
+                        status="schema_error",
+                        response={
+                            "error_code": "INVALID_ITEMS_SHAPE",
+                            "field_name": "items",
+                            "hint": "v3 requires modifiers list on every item",
+                        },
+                        schema_version=schema_version,
+                        latency_ms=_ok_latency(episode_seed, "restaurant.order"),
+                    ),
+                    vendor_state,
+                    payment_state,
+                )
+
+    total = 0
+    for it in items:
+        price = _restaurant_lookup_price(str(it["dish_id"]))
+        if price is None:
+            return (
+                ToolResult(
+                    tool_name="restaurant.order",
+                    status="schema_error",
+                    response={
+                        "error_code": "MISSING_FIELD",
+                        "field_name": "dish_id",
+                        "hint": "unknown dish_id",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "restaurant.order"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+        total += price * int(it["qty"])
+
+    if total < int(vendor_state.policy.min_order_inr):
+        return (
+            ToolResult(
+                tool_name="restaurant.order",
+                status="policy_error",
+                response={
+                    "error_code": "MIN_ORDER_NOT_MET",
+                    "min_order_inr": int(vendor_state.policy.min_order_inr),
+                    "got_total_inr": int(total),
+                    "hint": "order total below minimum",
+                },
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "restaurant.order"),
+            ),
+            vendor_state,
+            payment_state,
+        )
+
+    idempotency_key = (restaurant_id, _normalize_items(items))
+    for existing_id, record in vendor_state.orders.items():
+        existing_key = (
+            record.get("restaurant_id"),
+            _normalize_items(list(record.get("items") or [])),
+        )
+        if existing_key == idempotency_key:
+            return (
+                ToolResult(
+                    tool_name="restaurant.order",
+                    status="policy_error",
+                    response={
+                        "error_code": "DUPLICATE_ORDER",
+                        "existing_id": existing_id,
+                        "original_ts": str(record.get("created_at_ist", "")),
+                        "hint": "identical order already placed",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "restaurant.order"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+
+    charge_result, new_payment_state = _payment_charge_internal(
+        payment_state=payment_state,
+        amount_inr=total,
+        payment_token=payment_token,
+        mfa_code=None,
+        episode_seed=episode_seed,
+        order_ref=f"restaurant:{restaurant_id}",
+    )
+    if charge_result.status != "ok":
+        return (
+            _propagate_payment_error(charge_result, "restaurant.order", schema_version, episode_seed),
+            vendor_state,
+            payment_state,
+        )
+
+    order_id = _make_id("restaurant", episode_seed, "order", idempotency_key, vendor_state.orders)
+    record_items: list[dict[str, Any]] = []
+    for it in items:
+        entry: dict[str, Any] = {"dish_id": str(it["dish_id"]), "qty": int(it["qty"])}
+        price = _restaurant_lookup_price(str(it["dish_id"]))
+        entry["price"] = int(price) if price is not None else 0
+        if "modifiers" in it:
+            entry["modifiers"] = list(it["modifiers"])
+        record_items.append(entry)
+    record = {
+        "order_id": order_id,
+        "restaurant_id": restaurant_id,
+        "items": record_items,
+        "total": int(total),
+        "eta_min": 30 + (_stable_digest(episode_seed, order_id) & 0x1F),
+        "created_at_ist": now_ist.isoformat(),
+        "payment_status": "captured",
+    }
+    new_orders = {**vendor_state.orders, order_id: record}
+    new_state = replace(vendor_state, orders=new_orders)
+    response = {k: v for k, v in record.items() if k != "created_at_ist"}
+    return (
+        ToolResult(
+            tool_name="restaurant.order",
+            status="ok",
+            response=response,
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "restaurant.order"),
+        ),
+        new_state,
+        new_payment_state,
+    )
+
+
+def restaurant_track(
+    vendor_state: RestaurantState,
+    schema_version: str,
+    order_id: str,
+    episode_seed: int = 0,
+) -> ToolResult:
+    record = vendor_state.orders.get(order_id)
+    if record is None:
+        return ToolResult(
+            tool_name="restaurant.track",
+            status="schema_error",
+            response={"error_code": "MISSING_FIELD", "field_name": "order_id", "hint": "unknown order_id"},
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "restaurant.track"),
+        )
+    items = []
+    for it in record.get("items", []):
+        entry = dict(it)
+        if schema_version == "v3" and "modifiers" not in entry:
+            entry["modifiers"] = []
+        items.append(entry)
+    payload = {
+        "order_id": record["order_id"],
+        "restaurant_id": record["restaurant_id"],
+        "items": items,
+        "total": int(record["total"]),
+        "eta_min": int(record["eta_min"]),
+        "status": "in_transit",
+    }
+    return ToolResult(
+        tool_name="restaurant.track",
+        status="ok",
+        response=payload,
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "restaurant.track"),
+    )
+
+
+def restaurant_apply_schema_mutation(
+    vendor_state: RestaurantState, mutation: Mapping[str, Any]
+) -> RestaurantState:
+    state = vendor_state
+    next_version = state.schema_version
+    policy = state.policy
+    semantics = state.semantics
+    for op, payload in mutation.items():
+        if op == "numeric_bump":
+            if isinstance(payload, dict) and "min_order_inr" in payload:
+                policy = replace(policy, min_order_inr=int(payload["min_order_inr"]))
+                if next_version == "v1":
+                    next_version = "v2"
+        elif op == "require_new_field":
+            if isinstance(payload, dict) and "modifiers" in payload:
+                policy = replace(policy, require_modifiers=True)
+                if next_version in ("v1", "v2"):
+                    next_version = "v3"
+        elif op == "side_channel_notice_append":
+            state = replace(state, side_channel_notice=str(payload))
+            semantics = replace(semantics, veg_only_excludes_egg=True)
+            if next_version in ("v1", "v2"):
+                next_version = "v3"
+        elif op == "change_type" or op in {"rename", "remove", "enum_expand", "policy_flag_flip", "time_window_shrink", "tnc_text_swap", "pricing_restructure", "fee_append", "auth_scope_bump", "token_version_bump"}:
+            continue
+        else:
+            raise UnknownMutationOperatorError(op)
+    return replace(state, schema_version=next_version, policy=policy, semantics=semantics)
+
+
+def restaurant_describe_schema(vendor_state: RestaurantState, schema_version: str) -> dict[str, Any]:
+    if schema_version == "v1":
+        fields = {
+            "restaurant_id": "str",
+            "items": "list[dict]",
+            "total": "int",
+            "eta_min": "int",
+            "min_order_inr": "int",
+        }
+        removed: list[str] = []
+    elif schema_version == "v2":
+        fields = {
+            "restaurant_id": "str",
+            "items": "list[dict]",
+            "total": "int",
+            "eta_min": "int",
+            "min_order_inr": "int",
+        }
+        removed = []
+    elif schema_version == "v3":
+        fields = {
+            "restaurant_id": "str",
+            "items": "list[dict{dish_id,qty,modifiers}]",
+            "total": "int",
+            "eta_min": "int",
+            "min_order_inr": "int",
+        }
+        removed = []
+    else:
+        raise UnknownSchemaVersionError(schema_version)
+    return {"version": schema_version, "fields": fields, "removed_from_prior": removed}
+
+
+def restaurant_emit_side_channel_if_pending(
+    vendor_state: RestaurantState,
+) -> tuple[str | None, RestaurantState]:
+    if vendor_state.side_channel_notice is None:
+        return None, vendor_state
+    notice = vendor_state.side_channel_notice
+    return notice, replace(vendor_state, side_channel_notice=None)
+
+
+RESTAURANT_TOOLS: tuple[str, ...] = ("restaurant.search", "restaurant.order", "restaurant.track")
+
+
+# ---------------------------------------------------------------------------
+# Hotel
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class HotelPolicy:
+    cancel_window_hours: int = 24
+    gst_required_threshold_inr: int = 0  # 0 disables
+
+
+@dataclass(frozen=True)
+class HotelPricing:
+    resort_fee_inr: int = 0
+
+
+@dataclass(frozen=True)
+class HotelTnC:
+    early_checkin_fee_pct: int = 0
+
+
+@dataclass(frozen=True)
+class HotelState:
+    schema_version: str
+    bookings: dict[str, dict[str, Any]]
+    inventory_cache: dict[str, tuple[dict[str, Any], ...]]
+    policy: HotelPolicy
+    pricing: HotelPricing
+    tnc: HotelTnC
+    side_channel_notice: str | None
+
+
+_HOTEL_INVENTORY: tuple[dict[str, Any], ...] = (
+    {"hotel_id": "GOA-BEACH-007", "city": "Goa", "nightly_rate": 3500, "rooms": 12},
+    {"hotel_id": "GOA-RESORT-012", "city": "Goa", "nightly_rate": 4200, "rooms": 8},
+    {"hotel_id": "BLR-TECH-001", "city": "Bengaluru", "nightly_rate": 2800, "rooms": 30},
+    {"hotel_id": "HYD-PARK-022", "city": "Hyderabad", "nightly_rate": 1800, "rooms": 20},
+)
+
+
+def hotel_initial_state(episode_seed: int, goal: GoalSpec) -> HotelState:
+    _ = (episode_seed, goal)
+    return HotelState(
+        schema_version="v1",
+        bookings={},
+        inventory_cache={},
+        policy=HotelPolicy(cancel_window_hours=24, gst_required_threshold_inr=0),
+        pricing=HotelPricing(resort_fee_inr=0),
+        tnc=HotelTnC(),
+        side_channel_notice=None,
+    )
+
+
+def _hotel_nights(checkin: str, checkout: str) -> int:
+    ci = datetime.fromisoformat(checkin)
+    co = datetime.fromisoformat(checkout)
+    return max(1, (co.date() - ci.date()).days)
+
+
+def _hotel_compute_total(rate: int, nights: int, resort_fee: int) -> int:
+    subtotal = rate * nights + resort_fee * nights
+    gst = (subtotal * 18) // 100
+    return int(subtotal + gst)
+
+
+def hotel_search(
+    vendor_state: HotelState,
+    schema_version: str,
+    city: str,
+    checkin: str,
+    checkout: str,
+    max_nightly_rate_inr: int | None = None,
+    episode_seed: int = 0,
+) -> ToolResult:
+    nights = _hotel_nights(checkin, checkout)
+    results: list[dict[str, Any]] = []
+    for rec in _HOTEL_INVENTORY:
+        if rec["city"].lower() != city.strip().lower():
+            continue
+        if max_nightly_rate_inr is not None and int(rec["nightly_rate"]) > int(max_nightly_rate_inr):
+            continue
+        total = _hotel_compute_total(int(rec["nightly_rate"]), nights, int(vendor_state.pricing.resort_fee_inr))
+        results.append({
+            "hotel_id": rec["hotel_id"],
+            "city": rec["city"],
+            "checkin": checkin,
+            "checkout": checkout,
+            "nightly_rate": int(rec["nightly_rate"]),
+            "total_with_tax": int(total),
+            "cancel_window_hours": int(vendor_state.policy.cancel_window_hours),
+        })
+    return ToolResult(
+        tool_name="hotel.search",
+        status="ok",
+        response={"results": results},
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "hotel.search"),
+    )
+
+
+def _hotel_book_impl(
+    vendor_state: HotelState,
+    schema_version: str,
+    payment_state: PaymentState,
+    hotel_id: str,
+    checkin: str,
+    checkout: str,
+    payment_token: str,
+    gst_number: str | None,
+    episode_seed: int,
+    now_ist: datetime,
+    primary_guest: str | None = None,
+) -> tuple[ToolResult, HotelState, PaymentState]:
+    rec = next((h for h in _HOTEL_INVENTORY if h["hotel_id"] == hotel_id), None)
+    if rec is None:
+        return (
+            ToolResult(
+                tool_name="hotel.book",
+                status="schema_error",
+                response={"error_code": "MISSING_FIELD", "field_name": "hotel_id", "hint": "unknown hotel"},
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "hotel.book"),
+            ),
+            vendor_state,
+            payment_state,
+        )
+
+    nights = _hotel_nights(checkin, checkout)
+    total = _hotel_compute_total(int(rec["nightly_rate"]), nights, int(vendor_state.pricing.resort_fee_inr))
+
+    threshold = int(vendor_state.policy.gst_required_threshold_inr)
+    if threshold > 0 and total > threshold and not gst_number:
+        return (
+            ToolResult(
+                tool_name="hotel.book",
+                status="schema_error",
+                response={
+                    "error_code": "MISSING_GST_NUMBER",
+                    "gst_threshold_inr": threshold,
+                    "computed_total_inr": int(total),
+                    "hint": "provide gst_number for bookings above threshold",
+                },
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "hotel.book"),
+            ),
+            vendor_state,
+            payment_state,
+        )
+
+    idempotency_key = (
+        hotel_id,
+        checkin,
+        checkout,
+        (primary_guest or "").strip().lower(),
+    )
+    for existing_id, existing in vendor_state.bookings.items():
+        existing_key = (
+            existing.get("hotel_id"),
+            existing.get("checkin"),
+            existing.get("checkout"),
+            str(existing.get("primary_guest") or "").strip().lower(),
+        )
+        if existing_key == idempotency_key:
+            return (
+                ToolResult(
+                    tool_name="hotel.book",
+                    status="policy_error",
+                    response={
+                        "error_code": "DUPLICATE_BOOKING",
+                        "existing_id": existing_id,
+                        "original_ts": str(existing.get("created_at_ist", "")),
+                        "hint": "identical hotel booking already exists",
+                    },
+                    schema_version=schema_version,
+                    latency_ms=_ok_latency(episode_seed, "hotel.book"),
+                ),
+                vendor_state,
+                payment_state,
+            )
+
+    charge_result, new_payment_state = _payment_charge_internal(
+        payment_state=payment_state,
+        amount_inr=total,
+        payment_token=payment_token,
+        mfa_code=None,
+        episode_seed=episode_seed,
+        order_ref=f"hotel:{hotel_id}:{checkin}:{checkout}",
+    )
+    if charge_result.status != "ok":
+        return (
+            _propagate_payment_error(charge_result, "hotel.book", schema_version, episode_seed),
+            vendor_state,
+            payment_state,
+        )
+
+    booking_id = _make_id("hotel", episode_seed, "book", idempotency_key, vendor_state.bookings)
+    record: dict[str, Any] = {
+        "booking_id": booking_id,
+        "hotel_id": hotel_id,
+        "city": rec["city"],
+        "checkin": checkin,
+        "checkout": checkout,
+        "nightly_rate": int(rec["nightly_rate"]),
+        "total_with_tax": int(total),
+        "cancel_window_hours": int(vendor_state.policy.cancel_window_hours),
+        "primary_guest": primary_guest,
+        "created_at_ist": now_ist.isoformat(),
+        "payment_status": "captured",
+    }
+    if vendor_state.pricing.resort_fee_inr > 0:
+        record["resort_fee_inr"] = int(vendor_state.pricing.resort_fee_inr)
+    if gst_number:
+        record["gst_number"] = gst_number
+    new_bookings = {**vendor_state.bookings, booking_id: record}
+    new_state = replace(vendor_state, bookings=new_bookings)
+    response = {k: v for k, v in record.items() if k not in ("created_at_ist", "primary_guest")}
+    return (
+        ToolResult(
+            tool_name="hotel.book",
+            status="ok",
+            response=response,
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "hotel.book"),
+        ),
+        new_state,
+        new_payment_state,
+    )
+
+
+def hotel_cancel(
+    vendor_state: HotelState,
+    schema_version: str,
+    booking_id: str,
+    episode_seed: int = 0,
+    now_ist: datetime | None = None,
+) -> tuple[ToolResult, HotelState]:
+    record = vendor_state.bookings.get(booking_id)
+    if record is None:
+        return (
+            ToolResult(
+                tool_name="hotel.cancel",
+                status="policy_error",
+                response={"error_code": "MISSING_FIELD", "hint": "booking not found"},
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "hotel.cancel"),
+            ),
+            vendor_state,
+        )
+    if now_ist is not None:
+        try:
+            checkin_dt = datetime.fromisoformat(record["checkin"]).replace(tzinfo=now_ist.tzinfo)
+            window = timedelta(hours=int(vendor_state.policy.cancel_window_hours))
+            if checkin_dt - now_ist < window:
+                return (
+                    ToolResult(
+                        tool_name="hotel.cancel",
+                        status="policy_error",
+                        response={"error_code": "CANCEL_WINDOW_EXPIRED", "hint": "cancel window has passed"},
+                        schema_version=schema_version,
+                        latency_ms=_ok_latency(episode_seed, "hotel.cancel"),
+                    ),
+                    vendor_state,
+                )
+        except (ValueError, KeyError):
+            pass
+    new_bookings = {k: v for k, v in vendor_state.bookings.items() if k != booking_id}
+    new_state = replace(vendor_state, bookings=new_bookings)
+    return (
+        ToolResult(
+            tool_name="hotel.cancel",
+            status="ok",
+            response={"booking_id": booking_id, "cancelled": True},
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "hotel.cancel"),
+        ),
+        new_state,
+    )
+
+
+def hotel_apply_schema_mutation(
+    vendor_state: HotelState, mutation: Mapping[str, Any]
+) -> HotelState:
+    state = vendor_state
+    next_version = state.schema_version
+    policy = state.policy
+    pricing = state.pricing
+    tnc = state.tnc
+    for op, payload in mutation.items():
+        if op == "time_window_shrink":
+            if isinstance(payload, dict) and "cancel_window_hours" in payload:
+                policy = replace(policy, cancel_window_hours=int(payload["cancel_window_hours"]))
+                if next_version == "v1":
+                    next_version = "v2"
+        elif op == "fee_append":
+            if isinstance(payload, dict) and "resort_fee_inr" in payload:
+                pricing = replace(pricing, resort_fee_inr=int(payload["resort_fee_inr"]))
+                if next_version == "v1":
+                    next_version = "v2"
+        elif op == "require_new_field":
+            if isinstance(payload, dict) and "gst_number" in payload:
+                if policy.gst_required_threshold_inr == 0:
+                    policy = replace(policy, gst_required_threshold_inr=7500)
+                if next_version in ("v1", "v2"):
+                    next_version = "v3"
+        elif op == "policy_flag_flip":
+            if isinstance(payload, dict) and "gst_required_threshold_inr" in payload:
+                policy = replace(policy, gst_required_threshold_inr=int(payload["gst_required_threshold_inr"]))
+                if next_version in ("v1", "v2"):
+                    next_version = "v3"
+        elif op == "tnc_text_swap":
+            if isinstance(payload, dict) and "early_checkin_fee_pct" in payload:
+                tnc = replace(tnc, early_checkin_fee_pct=int(payload["early_checkin_fee_pct"]))
+        elif op == "side_channel_notice_append":
+            state = replace(state, side_channel_notice=str(payload))
+        elif op in {"rename", "remove", "change_type", "numeric_bump", "enum_expand", "pricing_restructure", "auth_scope_bump", "token_version_bump"}:
+            continue
+        else:
+            raise UnknownMutationOperatorError(op)
+    return replace(state, schema_version=next_version, policy=policy, pricing=pricing, tnc=tnc)
+
+
+def hotel_describe_schema(vendor_state: HotelState, schema_version: str) -> dict[str, Any]:
+    if schema_version == "v1":
+        fields = {
+            "hotel_id": "str",
+            "city": "str",
+            "checkin": "str",
+            "checkout": "str",
+            "nightly_rate": "int",
+            "total_with_tax": "int",
+            "cancel_window_hours": "int",
+        }
+        removed: list[str] = []
+    elif schema_version == "v2":
+        fields = {
+            "hotel_id": "str",
+            "city": "str",
+            "checkin": "str",
+            "checkout": "str",
+            "nightly_rate": "int",
+            "total_with_tax": "int",
+            "cancel_window_hours": "int",
+            "resort_fee_inr": "int",
+        }
+        removed = []
+    elif schema_version == "v3":
+        fields = {
+            "hotel_id": "str",
+            "city": "str",
+            "checkin": "str",
+            "checkout": "str",
+            "nightly_rate": "int",
+            "total_with_tax": "int",
+            "cancel_window_hours": "int",
+            "resort_fee_inr": "int",
+            "gst_number": "str",
+        }
+        removed = []
+    else:
+        raise UnknownSchemaVersionError(schema_version)
+    return {"version": schema_version, "fields": fields, "removed_from_prior": removed}
+
+
+def hotel_emit_side_channel_if_pending(vendor_state: HotelState) -> tuple[str | None, HotelState]:
+    if vendor_state.side_channel_notice is None:
+        return None, vendor_state
+    notice = vendor_state.side_channel_notice
+    return notice, replace(vendor_state, side_channel_notice=None)
+
+
+HOTEL_TOOLS: tuple[str, ...] = ("hotel.search", "hotel.book", "hotel.cancel")
+
+
+# ---------------------------------------------------------------------------
+# Payment
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PaymentState:
+    schema_version: str
+    charges: dict[str, dict[str, Any]]
+    accepted_token_version: Literal["v1", "v2"]
+    required_scope: str
+    mfa_threshold_inr: int
+    side_channel_notice: str | None
+
+
+_VALID_TOKENS = {"token_v1", "token_v2"}
+
+
+def payment_initial_state(episode_seed: int, goal: GoalSpec) -> PaymentState:
+    _ = (episode_seed, goal)
+    return PaymentState(
+        schema_version="v1",
+        charges={},
+        accepted_token_version="v1",
+        required_scope="payments:write:v1",
+        mfa_threshold_inr=0,
+        side_channel_notice=None,
+    )
+
+
+def _token_scope(token: str) -> str | None:
+    if token == "token_v1":
+        return "payments:write:v1"
+    if token == "token_v2":
+        return "payments:write:v2"
+    return None
+
+
+def _payment_charge_internal(
+    payment_state: PaymentState,
+    amount_inr: int,
+    payment_token: str,
+    mfa_code: str | None,
+    episode_seed: int,
+    order_ref: str,
+) -> tuple[ToolResult, PaymentState]:
+    """Pure subroutine invoked by primary-domain book/order handlers."""
+
+    sv = payment_state.schema_version
+    scope = _token_scope(payment_token)
+    if scope is None:
+        return (
+            ToolResult(
+                tool_name="payment.charge",
+                status="auth_error",
+                response={"error_code": "TOKEN_INVALID", "hint": "malformed payment_token"},
+                schema_version=sv,
+                latency_ms=_ok_latency(episode_seed, "payment.charge"),
+            ),
+            payment_state,
+        )
+    if payment_state.accepted_token_version == "v2" and payment_token == "token_v1":
+        return (
+            ToolResult(
+                tool_name="payment.charge",
+                status="auth_error",
+                response={
+                    "error_code": "AUTH_SCOPE_INSUFFICIENT",
+                    "required_scope": payment_state.required_scope,
+                    "hint": "request a v2 token",
+                },
+                schema_version=sv,
+                latency_ms=_ok_latency(episode_seed, "payment.charge"),
+            ),
+            payment_state,
+        )
+    if payment_state.mfa_threshold_inr > 0 and int(amount_inr) > payment_state.mfa_threshold_inr and not mfa_code:
+        return (
+            ToolResult(
+                tool_name="payment.charge",
+                status="auth_error",
+                response={
+                    "error_code": "MFA_REQUIRED",
+                    "mfa_threshold_inr": int(payment_state.mfa_threshold_inr),
+                    "mfa_required": True,
+                    "hint": "provide mfa_code for amounts above threshold",
+                },
+                schema_version=sv,
+                latency_ms=_ok_latency(episode_seed, "payment.charge"),
+            ),
+            payment_state,
+        )
+
+    idempotency_key = (order_ref, int(amount_inr), scope)
+    for existing_id, existing in payment_state.charges.items():
+        existing_key = (
+            existing.get("order_ref"),
+            int(existing.get("amount_inr", -1)),
+            existing.get("token_scope"),
+        )
+        if existing_key == idempotency_key:
+            return (
+                ToolResult(
+                    tool_name="payment.charge",
+                    status="policy_error",
+                    response={
+                        "error_code": "DUPLICATE_CHARGE",
+                        "existing_id": existing_id,
+                        "original_ts": str(existing.get("created_at_ist", "")),
+                        "hint": "duplicate charge request",
+                    },
+                    schema_version=sv,
+                    latency_ms=_ok_latency(episode_seed, "payment.charge"),
+                ),
+                payment_state,
+            )
+
+    charge_id = _make_id("payment", episode_seed, "charge", idempotency_key, payment_state.charges)
+    record = {
+        "charge_id": charge_id,
+        "amount_inr": int(amount_inr),
+        "order_ref": order_ref,
+        "token_scope": scope,
+        "status": "captured",
+        "created_at_ist": "",
+    }
+    new_charges = {**payment_state.charges, charge_id: record}
+    new_state = replace(payment_state, charges=new_charges)
+    response = {k: v for k, v in record.items() if k != "created_at_ist"}
+    return (
+        ToolResult(
+            tool_name="payment.charge",
+            status="ok",
+            response=response,
+            schema_version=sv,
+            latency_ms=_ok_latency(episode_seed, "payment.charge"),
+        ),
+        new_state,
+    )
+
+
+def payment_charge(
+    vendor_state: PaymentState,
+    schema_version: str,
+    amount_inr: int,
+    payment_token: str,
+    mfa_code: str | None = None,
+    episode_seed: int = 0,
+    now_ist: datetime | None = None,
+    order_ref: str | None = None,
+) -> tuple[ToolResult, PaymentState]:
+    _integer_inr(amount_inr)
+    ref = order_ref or f"direct:{payment_token}:{amount_inr}"
+    result, new_state = _payment_charge_internal(
+        payment_state=vendor_state,
+        amount_inr=int(amount_inr),
+        payment_token=payment_token,
+        mfa_code=mfa_code,
+        episode_seed=episode_seed,
+        order_ref=ref,
+    )
+    if result.status == "ok" and now_ist is not None:
+        updated_record = {**new_state.charges[result.response["charge_id"]]}
+        updated_record["created_at_ist"] = now_ist.isoformat()
+        new_charges = {**new_state.charges, result.response["charge_id"]: updated_record}
+        new_state = replace(new_state, charges=new_charges)
+    return result, new_state
+
+
+def payment_refund(
+    vendor_state: PaymentState,
+    schema_version: str,
+    charge_id: str,
+    amount_inr: int,
+    episode_seed: int = 0,
+) -> tuple[ToolResult, PaymentState]:
+    _integer_inr(amount_inr)
+    if charge_id not in vendor_state.charges:
+        return (
+            ToolResult(
+                tool_name="payment.refund",
+                status="policy_error",
+                response={"error_code": "MISSING_FIELD", "hint": "charge_id not found"},
+                schema_version=schema_version,
+                latency_ms=_ok_latency(episode_seed, "payment.refund"),
+            ),
+            vendor_state,
+        )
+    refund_id = _make_id("payment", episode_seed, "refund", (charge_id, int(amount_inr)), vendor_state.charges)
+    record = {
+        "refund_id": refund_id,
+        "charge_id": charge_id,
+        "amount_inr": int(amount_inr),
+        "order_ref": f"refund:{charge_id}",
+        "token_scope": vendor_state.required_scope,
+        "status": "refunded",
+    }
+    new_charges = {**vendor_state.charges, refund_id: record}
+    new_state = replace(vendor_state, charges=new_charges)
+    return (
+        ToolResult(
+            tool_name="payment.refund",
+            status="ok",
+            response=record,
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "payment.refund"),
+        ),
+        new_state,
+    )
+
+
+def payment_get_token(
+    vendor_state: PaymentState,
+    schema_version: str,
+    requested_scope: str,
+    episode_seed: int = 0,
+) -> ToolResult:
+    if requested_scope == "payments:write:v1":
+        token = "token_v1"
+    elif requested_scope == "payments:write:v2":
+        token = "token_v2"
+    else:
+        return ToolResult(
+            tool_name="payment.get_token",
+            status="auth_error",
+            response={"error_code": "TOKEN_INVALID", "hint": "unknown scope"},
+            schema_version=schema_version,
+            latency_ms=_ok_latency(episode_seed, "payment.get_token"),
+        )
+    return ToolResult(
+        tool_name="payment.get_token",
+        status="ok",
+        response={"token": token, "scope": requested_scope},
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, "payment.get_token"),
+    )
+
+
+def payment_apply_schema_mutation(
+    vendor_state: PaymentState, mutation: Mapping[str, Any]
+) -> PaymentState:
+    state = vendor_state
+    next_version = state.schema_version
+    for op, payload in mutation.items():
+        if op == "auth_scope_bump":
+            required = "payments:write:v2"
+            if isinstance(payload, dict) and "required_scope" in payload:
+                required = str(payload["required_scope"])
+            state = replace(state, accepted_token_version="v2", required_scope=required)
+            if next_version == "v1":
+                next_version = "v2"
+        elif op == "token_version_bump":
+            state = replace(state, accepted_token_version="v2")
+            if next_version == "v1":
+                next_version = "v2"
+        elif op == "policy_flag_flip":
+            if isinstance(payload, dict) and "mfa_threshold_inr" in payload:
+                state = replace(state, mfa_threshold_inr=int(payload["mfa_threshold_inr"]))
+                if next_version in ("v1", "v2"):
+                    next_version = "v3"
+        elif op == "side_channel_notice_append":
+            state = replace(state, side_channel_notice=str(payload))
+        elif op in {"rename", "remove", "require_new_field", "change_type", "numeric_bump", "enum_expand", "time_window_shrink", "tnc_text_swap", "pricing_restructure", "fee_append"}:
+            continue
+        else:
+            raise UnknownMutationOperatorError(op)
+    return replace(state, schema_version=next_version)
+
+
+def payment_describe_schema(vendor_state: PaymentState, schema_version: str) -> dict[str, Any]:
+    fields = {"amount_inr": "int", "payment_token": "str"}
+    removed: list[str] = []
+    if schema_version == "v1":
+        pass
+    elif schema_version == "v2":
+        fields["required_scope"] = "str"
+    elif schema_version == "v3":
+        fields["required_scope"] = "str"
+        fields["mfa_code"] = "str"
+    else:
+        raise UnknownSchemaVersionError(schema_version)
+    return {"version": schema_version, "fields": fields, "removed_from_prior": removed}
+
+
+def payment_emit_side_channel_if_pending(
+    vendor_state: PaymentState,
+) -> tuple[str | None, PaymentState]:
+    if vendor_state.side_channel_notice is None:
+        return None, vendor_state
+    notice = vendor_state.side_channel_notice
+    return notice, replace(vendor_state, side_channel_notice=None)
+
+
+PAYMENT_TOOLS: tuple[str, ...] = ("payment.charge", "payment.refund", "payment.get_token")
+
+
+# ---------------------------------------------------------------------------
+# Auth cascade propagation (payment → primary domain)
+# ---------------------------------------------------------------------------
+
+
+def _propagate_payment_error(
+    charge_result: ToolResult,
+    caller_tool: str,
+    schema_version: str,
+    episode_seed: int,
+) -> ToolResult:
+    response: dict[str, Any] = {"error_code": "PAYMENT_AUTH_FAILED"}
+    if charge_result.status == "auth_error":
+        inner = charge_result.response
+        if "required_scope" in inner:
+            response["required_scope"] = inner["required_scope"]
+        if inner.get("mfa_required") or inner.get("error_code") == "MFA_REQUIRED":
+            response["mfa_required"] = True
+        response["hint"] = inner.get("hint", "payment auth failed")
+        status: Literal["ok", "schema_error", "policy_error", "auth_error", "timeout"] = "auth_error"
+    else:
+        response = dict(charge_result.response)
+        status = charge_result.status
+    return ToolResult(
+        tool_name=caller_tool,
+        status=status,
+        response=response,
+        schema_version=schema_version,
+        latency_ms=_ok_latency(episode_seed, caller_tool),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Unified dispatch
+# ---------------------------------------------------------------------------
+
+
+TOOLS: tuple[str, ...] = (
+    *AIRLINE_TOOLS,
+    *CAB_TOOLS,
+    *RESTAURANT_TOOLS,
+    *HOTEL_TOOLS,
+    *PAYMENT_TOOLS,
+)
+
+
+def _split_tool(tool_name: str) -> tuple[str, str]:
+    if "." not in tool_name:
+        raise ValueError(f"tool_name must be '<domain>.<verb>', got {tool_name!r}")
+    domain, verb = tool_name.split(".", 1)
+    return domain, verb
+
+
+def airline_dispatch(
+    tool_name: str,
+    tool_args: Mapping[str, Any],
+    vendor_state: AirlineState,
+    schema_version: str,
+    episode_seed: int,
+    now_ist: datetime,
+    payment_state: PaymentState | None = None,
+) -> tuple[ToolResult, AirlineState, PaymentState | None]:
+    if _is_timeout(episode_seed, tool_name, tool_args):
+        return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state
+
+    if tool_name == "airline.search":
+        result = airline_search(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            from_=str(tool_args.get("from", tool_args.get("from_", ""))),
+            to=str(tool_args.get("to", "")),
+            date=str(tool_args.get("date", "")),
+            max_price_inr=tool_args.get("max_price_inr"),
+            time_window=tool_args.get("time_window"),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state, payment_state
+    if tool_name == "airline.book":
+        if payment_state is None:
+            payment_state = payment_initial_state(episode_seed, _stub_goal())
+        result, new_state, new_payment = _airline_book_impl(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            payment_state=payment_state,
+            flight_id=str(tool_args.get("flight_id", "")),
+            payment_token=str(tool_args.get("payment_token", "")),
+            passenger_count=tool_args.get("passenger_count"),
+            passenger_name=tool_args.get("passenger_name"),
+            episode_seed=episode_seed,
+            now_ist=now_ist,
+        )
+        return result, new_state, new_payment
+    if tool_name == "airline.cancel":
+        result, new_state = airline_cancel(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            booking_id=str(tool_args.get("booking_id", "")),
+            episode_seed=episode_seed,
+        )
+        return result, new_state, payment_state
+    if tool_name == "airline.get_booking":
+        result = airline_get_booking(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            booking_id=str(tool_args.get("booking_id", "")),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state, payment_state
+    raise ValueError(f"unknown airline tool: {tool_name}")
+
+
+def cab_dispatch(
+    tool_name: str,
+    tool_args: Mapping[str, Any],
+    vendor_state: CabState,
+    schema_version: str,
+    episode_seed: int,
+    now_ist: datetime,
+    payment_state: PaymentState | None = None,
+) -> tuple[ToolResult, CabState, PaymentState | None]:
+    if _is_timeout(episode_seed, tool_name, tool_args):
+        return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state
+    if tool_name == "cab.estimate":
+        result = cab_estimate(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            pickup=str(tool_args.get("pickup", "")),
+            drop=str(tool_args.get("drop", "")),
+            vehicle_class=str(tool_args.get("vehicle_class", "mini")),
+            pickup_time_ist=str(tool_args.get("pickup_time_ist", "")),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state, payment_state
+    if tool_name == "cab.book":
+        if payment_state is None:
+            payment_state = payment_initial_state(episode_seed, _stub_goal())
+        result, new_state, new_payment = _cab_book_impl(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            payment_state=payment_state,
+            pickup=str(tool_args.get("pickup", "")),
+            drop=str(tool_args.get("drop", "")),
+            vehicle_class=str(tool_args.get("vehicle_class", "mini")),
+            pickup_time_ist=str(tool_args.get("pickup_time_ist", "")),
+            payment_token=str(tool_args.get("payment_token", "")),
+            episode_seed=episode_seed,
+            now_ist=now_ist,
+        )
+        return result, new_state, new_payment
+    if tool_name == "cab.cancel":
+        result, new_state = cab_cancel(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            ride_id=str(tool_args.get("ride_id", "")),
+            episode_seed=episode_seed,
+        )
+        return result, new_state, payment_state
+    raise ValueError(f"unknown cab tool: {tool_name}")
+
+
+def restaurant_dispatch(
+    tool_name: str,
+    tool_args: Mapping[str, Any],
+    vendor_state: RestaurantState,
+    schema_version: str,
+    episode_seed: int,
+    now_ist: datetime,
+    payment_state: PaymentState | None = None,
+) -> tuple[ToolResult, RestaurantState, PaymentState | None]:
+    if _is_timeout(episode_seed, tool_name, tool_args):
+        return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state
+    if tool_name == "restaurant.search":
+        result = restaurant_search(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            city=str(tool_args.get("city", "")),
+            cuisine=tool_args.get("cuisine"),
+            veg_only=bool(tool_args.get("veg_only", False)),
+            max_price_inr=tool_args.get("max_price_inr"),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state, payment_state
+    if tool_name == "restaurant.order":
+        if payment_state is None:
+            payment_state = payment_initial_state(episode_seed, _stub_goal())
+        items = list(tool_args.get("items") or [])
+        result, new_state, new_payment = _restaurant_order_impl(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            payment_state=payment_state,
+            restaurant_id=str(tool_args.get("restaurant_id", "")),
+            items=items,
+            payment_token=str(tool_args.get("payment_token", "")),
+            episode_seed=episode_seed,
+            now_ist=now_ist,
+        )
+        return result, new_state, new_payment
+    if tool_name == "restaurant.track":
+        result = restaurant_track(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            order_id=str(tool_args.get("order_id", "")),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state, payment_state
+    raise ValueError(f"unknown restaurant tool: {tool_name}")
+
+
+def hotel_dispatch(
+    tool_name: str,
+    tool_args: Mapping[str, Any],
+    vendor_state: HotelState,
+    schema_version: str,
+    episode_seed: int,
+    now_ist: datetime,
+    payment_state: PaymentState | None = None,
+) -> tuple[ToolResult, HotelState, PaymentState | None]:
+    if _is_timeout(episode_seed, tool_name, tool_args):
+        return _timeout_result(tool_name, episode_seed, schema_version), vendor_state, payment_state
+    if tool_name == "hotel.search":
+        result = hotel_search(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            city=str(tool_args.get("city", "")),
+            checkin=str(tool_args.get("checkin", "")),
+            checkout=str(tool_args.get("checkout", "")),
+            max_nightly_rate_inr=tool_args.get("max_nightly_rate_inr"),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state, payment_state
+    if tool_name == "hotel.book":
+        if payment_state is None:
+            payment_state = payment_initial_state(episode_seed, _stub_goal())
+        result, new_state, new_payment = _hotel_book_impl(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            payment_state=payment_state,
+            hotel_id=str(tool_args.get("hotel_id", "")),
+            checkin=str(tool_args.get("checkin", "")),
+            checkout=str(tool_args.get("checkout", "")),
+            payment_token=str(tool_args.get("payment_token", "")),
+            gst_number=tool_args.get("gst_number"),
+            episode_seed=episode_seed,
+            now_ist=now_ist,
+            primary_guest=tool_args.get("primary_guest"),
+        )
+        return result, new_state, new_payment
+    if tool_name == "hotel.cancel":
+        result, new_state = hotel_cancel(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            booking_id=str(tool_args.get("booking_id", "")),
+            episode_seed=episode_seed,
+            now_ist=now_ist,
+        )
+        return result, new_state, payment_state
+    raise ValueError(f"unknown hotel tool: {tool_name}")
+
+
+def payment_dispatch(
+    tool_name: str,
+    tool_args: Mapping[str, Any],
+    vendor_state: PaymentState,
+    schema_version: str,
+    episode_seed: int,
+    now_ist: datetime,
+) -> tuple[ToolResult, PaymentState]:
+    if _is_timeout(episode_seed, tool_name, tool_args):
+        return _timeout_result(tool_name, episode_seed, schema_version), vendor_state
+    if tool_name == "payment.charge":
+        return payment_charge(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            amount_inr=int(tool_args.get("amount_inr", 0)),
+            payment_token=str(tool_args.get("payment_token", "")),
+            mfa_code=tool_args.get("mfa_code"),
+            episode_seed=episode_seed,
+            now_ist=now_ist,
+            order_ref=tool_args.get("order_ref"),
+        )
+    if tool_name == "payment.refund":
+        return payment_refund(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            charge_id=str(tool_args.get("charge_id", "")),
+            amount_inr=int(tool_args.get("amount_inr", 0)),
+            episode_seed=episode_seed,
+        )
+    if tool_name == "payment.get_token":
+        result = payment_get_token(
+            vendor_state=vendor_state,
+            schema_version=schema_version,
+            requested_scope=str(tool_args.get("requested_scope", "")),
+            episode_seed=episode_seed,
+        )
+        return result, vendor_state
+    raise ValueError(f"unknown payment tool: {tool_name}")
+
+
+def _stub_goal() -> GoalSpec:
+    return GoalSpec(
+        domain="airline",
+        intent="book_flight",
+        slots={},
+        constraints={},
+        language="en",
+        seed_utterance="",
+    )
+
+
+# ---------------------------------------------------------------------------
+# Vendor namespace registry — exposes the per-domain "module" surface the
+# spec calls for while keeping everything in a single cell.
+# ---------------------------------------------------------------------------
+
+
+airline = SimpleNamespace(
+    initial_state=airline_initial_state,
+    search=airline_search,
+    cancel=airline_cancel,
+    get_booking=airline_get_booking,
+    apply_schema_mutation=airline_apply_schema_mutation,
+    describe_schema=airline_describe_schema,
+    emit_side_channel_if_pending=airline_emit_side_channel_if_pending,
+    dispatch=airline_dispatch,
+    TOOLS=AIRLINE_TOOLS,
+)
+
+cab = SimpleNamespace(
+    initial_state=cab_initial_state,
+    estimate=cab_estimate,
+    cancel=cab_cancel,
+    apply_schema_mutation=cab_apply_schema_mutation,
+    describe_schema=cab_describe_schema,
+    emit_side_channel_if_pending=cab_emit_side_channel_if_pending,
+    dispatch=cab_dispatch,
+    TOOLS=CAB_TOOLS,
+)
+
+restaurant = SimpleNamespace(
+    initial_state=restaurant_initial_state,
+    search=restaurant_search,
+    track=restaurant_track,
+    apply_schema_mutation=restaurant_apply_schema_mutation,
+    describe_schema=restaurant_describe_schema,
+    emit_side_channel_if_pending=restaurant_emit_side_channel_if_pending,
+    dispatch=restaurant_dispatch,
+    TOOLS=RESTAURANT_TOOLS,
+)
+
+hotel = SimpleNamespace(
+    initial_state=hotel_initial_state,
+    search=hotel_search,
+    cancel=hotel_cancel,
+    apply_schema_mutation=hotel_apply_schema_mutation,
+    describe_schema=hotel_describe_schema,
+    emit_side_channel_if_pending=hotel_emit_side_channel_if_pending,
+    dispatch=hotel_dispatch,
+    TOOLS=HOTEL_TOOLS,
+)
+
+payment = SimpleNamespace(
+    initial_state=payment_initial_state,
+    charge=payment_charge,
+    refund=payment_refund,
+    get_token=payment_get_token,
+    apply_schema_mutation=payment_apply_schema_mutation,
+    describe_schema=payment_describe_schema,
+    emit_side_channel_if_pending=payment_emit_side_channel_if_pending,
+    dispatch=payment_dispatch,
+    TOOLS=PAYMENT_TOOLS,
+)
+
+
+VENDOR_REGISTRY: dict[str, SimpleNamespace] = {
+    "airline": airline,
+    "cab": cab,
+    "restaurant": restaurant,
+    "hotel": hotel,
+    "payment": payment,
+}
+
+
+__all__ = [
+    "AirlinePolicy",
+    "AirlineTnC",
+    "AirlinePricing",
+    "AirlineState",
+    "CabPolicy",
+    "CabPricing",
+    "CabTnC",
+    "CabState",
+    "RestaurantPolicy",
+    "RestaurantSemantics",
+    "RestaurantTnC",
+    "RestaurantState",
+    "HotelPolicy",
+    "HotelPricing",
+    "HotelTnC",
+    "HotelState",
+    "PaymentState",
+    "UnknownSchemaVersionError",
+    "UnknownMutationOperatorError",
+    "TOOLS",
+    "AIRLINE_TOOLS",
+    "CAB_TOOLS",
+    "RESTAURANT_TOOLS",
+    "HOTEL_TOOLS",
+    "PAYMENT_TOOLS",
+    "VENDOR_REGISTRY",
+    "airline",
+    "cab",
+    "restaurant",
+    "hotel",
+    "payment",
+    "airline_initial_state",
+    "airline_search",
+    "airline_cancel",
+    "airline_get_booking",
+    "airline_apply_schema_mutation",
+    "airline_describe_schema",
+    "airline_emit_side_channel_if_pending",
+    "airline_dispatch",
+    "cab_initial_state",
+    "cab_estimate",
+    "cab_cancel",
+    "cab_apply_schema_mutation",
+    "cab_describe_schema",
+    "cab_emit_side_channel_if_pending",
+    "cab_dispatch",
+    "restaurant_initial_state",
+    "restaurant_search",
+    "restaurant_track",
+    "restaurant_apply_schema_mutation",
+    "restaurant_describe_schema",
+    "restaurant_emit_side_channel_if_pending",
+    "restaurant_dispatch",
+    "hotel_initial_state",
+    "hotel_search",
+    "hotel_cancel",
+    "hotel_apply_schema_mutation",
+    "hotel_describe_schema",
+    "hotel_emit_side_channel_if_pending",
+    "hotel_dispatch",
+    "payment_initial_state",
+    "payment_charge",
+    "payment_refund",
+    "payment_get_token",
+    "payment_apply_schema_mutation",
+    "payment_describe_schema",
+    "payment_emit_side_channel_if_pending",
+    "payment_dispatch",
+]

cells/step_06_drift_injector.md

@@ -0,0 +1,3 @@
+## Step 06 — Drift Injector
+
+Schedules, applies, and catalogues the 20 canonical drift patterns (5 schema + 5 policy + 5 T&C + 3 pricing + 2 transversal payment-auth) per DESIGN.md §6 and docs/modules/drift_injector.md. Deterministic scheduler (blake2b-seeded RNG) produces `()`, `(e,)`, or `(e1, e2)` for stage 1/2/3; `apply_drift` returns a new frozen `DriftCallState` with mutated vendor schema, bumped schema version, and the fired event appended.

cells/step_06_drift_injector.py

@@ -0,0 +1,732 @@
+"""DriftCall drift injector.
+
+Implements docs/modules/drift_injector.md. Public surface:
+
+- build_schedule(stage, episode_seed, goal) -> tuple[DriftEvent, ...]
+- apply_drift(state, event) -> DriftCallState
+- list_patterns() -> tuple[DriftPattern, ...]
+
+The 20-pattern catalogue is embedded as a module-level constant (one
+source of truth; no YAML dependency at runtime). Patterns are keyed by
+`pattern_id` per drift_injector.md §4.1.
+
+Error taxonomy (drift_injector.md §5):
+
+- ValueError                    — stage not in {1,2,3}
+- UnknownDriftPatternError      — event.pattern_id not in registry
+- DriftDomainMismatchError      — event.domain not in state.vendor_states
+- DriftReapplicationError       — event already present in state.drift_fired
+- DriftCatalogueError           — catalogue loads < 20 patterns (startup)
+- DriftScheduleConflictError    — stage-3 schedule cannot be built within
+                                  retry budget, or max_turns < 8 for stage 3
+"""
+
+from __future__ import annotations
+
+import copy
+import hashlib
+import random
+import struct
+from dataclasses import dataclass, replace
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+from cells.step_04_models import DriftCallState, DriftEvent, GoalSpec
+
+DriftTypeLiteral = Literal["schema", "policy", "tnc", "pricing", "auth"]
+
+__all__ = [
+    "DriftCatalogueError",
+    "DriftDomainMismatchError",
+    "DriftPattern",
+    "DriftReapplicationError",
+    "DriftScheduleConflictError",
+    "UnknownDriftPatternError",
+    "apply_drift",
+    "build_schedule",
+    "list_patterns",
+]
+
+
+# ---------------------------------------------------------------------------
+# Errors (drift_injector.md §5)
+# ---------------------------------------------------------------------------
+
+
+class UnknownDriftPatternError(Exception):
+    """Raised when apply_drift receives a DriftEvent whose description is
+    not a key in the pattern registry."""
+
+
+class DriftDomainMismatchError(Exception):
+    """Raised when the event's domain is not a key of state.vendor_states."""
+
+
+class DriftReapplicationError(Exception):
+    """Raised when apply_drift is called with an event already present in
+    state.drift_fired. Defence-in-depth per spec §2."""
+
+
+class DriftCatalogueError(Exception):
+    """Raised at startup when the embedded catalogue contains fewer than
+    20 patterns."""
+
+
+class DriftScheduleConflictError(Exception):
+    """Raised when build_schedule cannot produce a valid stage-3 schedule
+    (max_turns too small, or retry budget exhausted)."""
+
+
+# ---------------------------------------------------------------------------
+# DriftPattern dataclass (drift_injector.md §4.2)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class DriftPattern:
+    id: str
+    drift_type: DriftTypeLiteral
+    domain: str
+    from_version: str
+    to_version: str
+    description: str
+    mutation: Mapping[str, Any]
+    detection_hints: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+        # Wrap mutation in MappingProxyType for immutability without mutating
+        # a frozen instance — use object.__setattr__ (frozen-safe per stdlib).
+        if not isinstance(self.mutation, MappingProxyType):
+            object.__setattr__(self, "mutation", MappingProxyType(dict(self.mutation)))
+
+
+# ---------------------------------------------------------------------------
+# 20-pattern catalogue (drift_injector.md §4.4, byte-identical to DESIGN.md §6.3)
+# ---------------------------------------------------------------------------
+
+
+_CATALOGUE_RAW: tuple[dict[str, Any], ...] = (
+    # Schema (5)
+    {
+        "id": "airline.price_rename",
+        "drift_type": "schema",
+        "domain": "airline",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "field 'price' renamed to 'total_fare_inr'; 'currency' removed",
+        "mutation": {
+            "rename": {"price": "total_fare_inr"},
+            "remove": ["currency"],
+        },
+        "detection_hints": ("total_fare_inr", "price", "rename"),
+    },
+    {
+        "id": "airline.pax_required",
+        "drift_type": "schema",
+        "domain": "airline",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "booking now requires 'passenger_count' field",
+        "mutation": {
+            "require_new_field": ["passenger_count"],
+        },
+        "detection_hints": ("passenger_count", "MISSING_PASSENGER_COUNT"),
+    },
+    {
+        "id": "cab.fare_breakdown",
+        "drift_type": "schema",
+        "domain": "cab",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "'fare_inr' replaced by nested 'fare_breakdown' object",
+        "mutation": {
+            "change_type": {"fare_inr": "fare_breakdown"},
+            "require_new_field": ["fare_breakdown"],
+            "remove": ["fare_inr"],
+        },
+        "detection_hints": ("fare_breakdown", "base", "surge", "tolls", "gst"),
+    },
+    {
+        "id": "restaurant.items_shape_bump",
+        "drift_type": "schema",
+        "domain": "restaurant",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "items[] entries now require a 'modifiers' array",
+        "mutation": {
+            "require_new_field": ["modifiers"],
+        },
+        "detection_hints": ("modifiers", "items", "require"),
+    },
+    {
+        "id": "hotel.gst_field",
+        "drift_type": "schema",
+        "domain": "hotel",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "hotel.book requires 'gst_number' when total > 7500",
+        "mutation": {
+            "require_new_field": ["gst_number"],
+        },
+        "detection_hints": ("gst_number", "gst", "7500"),
+    },
+    # Policy (5)
+    {
+        "id": "airline.booking_window_shrink",
+        "drift_type": "policy",
+        "domain": "airline",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "same-day bookings rejected after 14:00 IST",
+        "mutation": {
+            "time_window_shrink": {"same_day_cutoff": "14:00"},
+            "policy_flag_flip": {"same_day_allowed": False},
+        },
+        "detection_hints": ("14:00", "same-day", "policy_error", "booking_window"),
+    },
+    {
+        "id": "cab.school_hours_mini_reject",
+        "drift_type": "policy",
+        "domain": "cab",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "vehicle_class=mini rejected during 07:00-09:00 IST",
+        "mutation": {
+            "time_window_shrink": {"mini_blackout": ["07:00", "09:00"]},
+            "policy_flag_flip": {"mini_school_hours": False},
+        },
+        "detection_hints": ("mini", "07:00", "09:00", "policy_error", "school"),
+    },
+    {
+        "id": "restaurant.min_order_bump",
+        "drift_type": "policy",
+        "domain": "restaurant",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "minimum order raised from 199 to 299 INR",
+        "mutation": {
+            "numeric_bump": {"min_order_inr": {"from": 199, "to": 299}},
+        },
+        "detection_hints": ("299", "199", "min_order", "minimum"),
+    },
+    {
+        "id": "hotel.cancel_window_shrink",
+        "drift_type": "policy",
+        "domain": "hotel",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "free cancellation window shrunk 24h to 6h",
+        "mutation": {
+            "numeric_bump": {"cancel_window_hours": {"from": 24, "to": 6}},
+        },
+        "detection_hints": ("6h", "24h", "cancel_window", "cancel"),
+    },
+    {
+        "id": "cab.vehicle_class_expand",
+        "drift_type": "policy",
+        "domain": "cab",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "vehicle_class enum expanded with suv and infant_seat_sedan",
+        "mutation": {
+            "enum_expand": {"vehicle_class": ["suv", "infant_seat_sedan"]},
+        },
+        "detection_hints": ("suv", "infant_seat_sedan", "vehicle_class"),
+    },
+    # T&C (5)
+    {
+        "id": "airline.baggage_tnc_rewrite",
+        "drift_type": "tnc",
+        "domain": "airline",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "cabin baggage allowance reduced from 7kg to 5kg",
+        "mutation": {
+            "tnc_text_swap": {
+                "from": "free cabin baggage 7kg",
+                "to": "free cabin baggage 5kg",
+            },
+            "side_channel_notice_append": "baggage_allowance_change_7_to_5",
+        },
+        "detection_hints": ("5kg", "7kg", "baggage", "cabin"),
+    },
+    {
+        "id": "cab.surge_policy_tnc",
+        "drift_type": "tnc",
+        "domain": "cab",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "surge may apply retroactively if ride extended",
+        "mutation": {
+            "tnc_text_swap": {
+                "from": "surge fixed at booking",
+                "to": "surge applies retroactively on extension",
+            },
+            "side_channel_notice_append": "surge_retroactive_notice",
+        },
+        "detection_hints": ("surge", "retroactive", "extend", "tnc"),
+    },
+    {
+        "id": "restaurant.veg_filter_semantic",
+        "drift_type": "tnc",
+        "domain": "restaurant",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "veg_only=True now excludes egg dishes (was included)",
+        "mutation": {
+            "tnc_text_swap": {
+                "from": "veg_only includes egg",
+                "to": "veg_only excludes egg",
+            },
+            "side_channel_notice_append": "veg_only_egg_exclusion",
+        },
+        "detection_hints": ("veg_only", "egg", "exclude"),
+    },
+    {
+        "id": "hotel.early_checkin_tnc",
+        "drift_type": "tnc",
+        "domain": "hotel",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "early check-in before 12:00 billed at 50% of nightly rate",
+        "mutation": {
+            "tnc_text_swap": {
+                "from": "early check-in free subject to availability",
+                "to": "early check-in billed 50% of nightly rate",
+            },
+            "side_channel_notice_append": "early_checkin_billed",
+        },
+        "detection_hints": ("early", "check-in", "50%", "12:00"),
+    },
+    {
+        "id": "airline.reschedule_tnc",
+        "drift_type": "tnc",
+        "domain": "airline",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "reschedule fee previously waived is now 10% of fare",
+        "mutation": {
+            "tnc_text_swap": {
+                "from": "reschedule waived",
+                "to": "reschedule fee 10% of fare",
+            },
+            "side_channel_notice_append": "reschedule_fee_10pct",
+        },
+        "detection_hints": ("reschedule", "10%", "fare", "fee"),
+    },
+    # Pricing (3)
+    {
+        "id": "airline.convenience_fee_append",
+        "drift_type": "pricing",
+        "domain": "airline",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "hidden INR 199 convenience fee added at booking",
+        "mutation": {
+            "fee_append": {"convenience_fee_inr": 199},
+            "pricing_restructure": {"hidden_fees": True},
+        },
+        "detection_hints": ("199", "convenience_fee", "fee", "hidden"),
+    },
+    {
+        "id": "cab.toll_unbundle",
+        "drift_type": "pricing",
+        "domain": "cab",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "tolls previously included, now separate line item at booking",
+        "mutation": {
+            "fee_append": {"tolls_inr": 0},
+            "pricing_restructure": {"toll_unbundled": True},
+        },
+        "detection_hints": ("toll", "tolls", "unbundle", "line item"),
+    },
+    {
+        "id": "hotel.resort_fee_append",
+        "drift_type": "pricing",
+        "domain": "hotel",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "resort fee of INR 500 per night added at booking",
+        "mutation": {
+            "fee_append": {"resort_fee_inr": 500},
+            "pricing_restructure": {"resort_fee_hidden": True},
+        },
+        "detection_hints": ("resort_fee", "500", "per night", "resort"),
+    },
+    # Auth (2, transversal on payment)
+    {
+        "id": "payment.auth_scope_upgrade",
+        "drift_type": "auth",
+        "domain": "payment",
+        "from_version": "v1",
+        "to_version": "v2",
+        "description": "token_v1 401s; token_v2 with scope=payments:write:v2 required",
+        "mutation": {
+            "auth_scope_bump": {"required_scope": "payments:write:v2"},
+            "token_version_bump": {"from": "token_v1", "to": "token_v2"},
+        },
+        "detection_hints": ("token_v2", "payments:write:v2", "scope", "401", "auth"),
+    },
+    {
+        "id": "payment.mfa_required",
+        "drift_type": "auth",
+        "domain": "payment",
+        "from_version": "v2",
+        "to_version": "v3",
+        "description": "transactions above INR 5000 require mfa_code in payload",
+        "mutation": {
+            "auth_scope_bump": {"required_field": "mfa_code"},
+            "token_version_bump": {"threshold_inr": 5000},
+        },
+        "detection_hints": ("mfa_code", "mfa_required", "5000", "mfa"),
+    },
+)
+
+
+def _load_catalogue() -> tuple[DriftPattern, ...]:
+    patterns = tuple(
+        DriftPattern(
+            id=entry["id"],
+            drift_type=entry["drift_type"],
+            domain=entry["domain"],
+            from_version=entry["from_version"],
+            to_version=entry["to_version"],
+            description=entry["description"],
+            mutation=entry["mutation"],
+            detection_hints=tuple(entry["detection_hints"]),
+        )
+        for entry in _CATALOGUE_RAW
+    )
+    if len(patterns) < 20:
+        raise DriftCatalogueError(
+            f"expected 20 patterns in catalogue, got {len(patterns)}",
+        )
+    # Sort by id for stable ordering (spec §2 list_patterns contract).
+    return tuple(sorted(patterns, key=lambda p: p.id))
+
+
+_PATTERNS: tuple[DriftPattern, ...] = _load_catalogue()
+_PATTERNS_BY_ID: dict[str, DriftPattern] = {p.id: p for p in _PATTERNS}
+_PATTERNS_BY_DOMAIN: dict[str, tuple[DriftPattern, ...]] = {}
+for _p in _PATTERNS:
+    _PATTERNS_BY_DOMAIN.setdefault(_p.domain, ())
+    _PATTERNS_BY_DOMAIN[_p.domain] = (*_PATTERNS_BY_DOMAIN[_p.domain], _p)
+
+
+def list_patterns() -> tuple[DriftPattern, ...]:
+    """Return all 20 registered drift patterns, sorted by id."""
+    return _PATTERNS
+
+
+# ---------------------------------------------------------------------------
+# Deterministic RNG helpers (drift_injector.md §3.3)
+# ---------------------------------------------------------------------------
+
+
+def _derive_seed(stage: int, episode_seed: int, domain: str) -> int:
+    """Blake2b-based seed derivation — hash-stable across PYTHONHASHSEED."""
+    payload = f"drift|{stage}|{episode_seed}|{domain}".encode()
+    digest = hashlib.blake2b(payload, digest_size=8).digest()
+    (seed,) = struct.unpack("<Q", digest)
+    return int(seed)
+
+
+# ---------------------------------------------------------------------------
+# Schedule construction (drift_injector.md §2, §3.2, §7)
+# ---------------------------------------------------------------------------
+
+
+_DEFAULT_MAX_TURNS: int = 16
+
+
+def _pick_pattern_for_domain(
+    rng: random.Random,
+    domain: str,
+    exclude_ids: frozenset[str],
+) -> DriftPattern | None:
+    pool = tuple(
+        p for p in _PATTERNS_BY_DOMAIN.get(domain, ()) if p.id not in exclude_ids
+    )
+    if not pool:
+        return None
+    return rng.choice(pool)
+
+
+def _event_from_pattern(pattern: DriftPattern, turn: int) -> DriftEvent:
+    return DriftEvent(
+        turn=turn,
+        drift_type=pattern.drift_type,
+        domain=pattern.domain,
+        description=pattern.description,
+        from_version=pattern.from_version,
+        to_version=pattern.to_version,
+        pattern_id=pattern.id,
+    )
+
+
+def build_schedule(
+    stage: int,
+    episode_seed: int,
+    goal: GoalSpec,
+    *,
+    max_turns: int = _DEFAULT_MAX_TURNS,
+) -> tuple[DriftEvent, ...]:
+    """Build the drift schedule for an episode. See drift_injector.md §2."""
+    if stage not in (1, 2, 3):
+        raise ValueError(f"unknown stage: {stage!r} (expected 1, 2, or 3)")
+
+    if stage == 1:
+        return ()
+
+    rng = random.Random(_derive_seed(stage, episode_seed, goal.domain))
+    lo = 2
+    hi = max_turns - 3
+    if hi < lo:
+        raise DriftScheduleConflictError(
+            f"max_turns={max_turns} too small for any drift placement",
+        )
+
+    first_pattern = _pick_pattern_for_domain(rng, goal.domain, frozenset())
+    if first_pattern is None:
+        # Fallback: goal.domain has no pattern; pick any.
+        first_pattern = rng.choice(_PATTERNS)
+
+    if stage == 2:
+        turn = rng.randint(lo, hi)
+        return (_event_from_pattern(first_pattern, turn),)
+
+    # stage == 3 — need two drifts, distance >= 2, different pattern_ids.
+    if max_turns < 8:
+        raise DriftScheduleConflictError(
+            f"max_turns={max_turns} too small for stage-3 schedule (need >= 8)",
+        )
+
+    # first_turn must leave room for second_turn >= first_turn + 2 within [lo, hi].
+    first_hi_by_window = max_turns // 2
+    first_hi = min(first_hi_by_window, hi - 2)
+    if first_hi < lo:
+        raise DriftScheduleConflictError(
+            f"max_turns={max_turns} leaves no room for stage-3 first drift",
+        )
+    first_turn = rng.randint(lo, first_hi)
+
+    second_lo = first_turn + 2
+    if second_lo > hi:
+        raise DriftScheduleConflictError(
+            f"max_turns={max_turns} leaves no room for stage-3 second drift",
+        )
+    second_turn = rng.randint(second_lo, hi)
+
+    # Second-drift domain: 80% same as goal.domain, 20% payment cross-domain.
+    cross_domain_roll = rng.random()
+    second_domain = "payment" if cross_domain_roll < 0.20 else goal.domain
+
+    second_pattern: DriftPattern | None = None
+    for _attempt in range(5):
+        candidate = _pick_pattern_for_domain(
+            rng,
+            second_domain,
+            frozenset({first_pattern.id}),
+        )
+        if candidate is not None:
+            second_pattern = candidate
+            break
+        # Swap domain on miss (e.g., if same-domain pool is already exhausted).
+        second_domain = "payment" if second_domain == goal.domain else goal.domain
+
+    if second_pattern is None:
+        # Last resort: any pattern in catalogue other than first.
+        remaining = tuple(p for p in _PATTERNS if p.id != first_pattern.id)
+        if not remaining:
+            raise DriftScheduleConflictError(
+                "unable to build stage-3 schedule: no distinct second pattern",
+            )
+        second_pattern = rng.choice(remaining)
+
+    return (
+        _event_from_pattern(first_pattern, first_turn),
+        _event_from_pattern(second_pattern, second_turn),
+    )
+
+
+# ---------------------------------------------------------------------------
+# Mutation dispatch (drift_injector.md §3.4)
+# ---------------------------------------------------------------------------
+
+
+def _apply_rename(target: dict[str, Any], rename_map: Mapping[str, str]) -> None:
+    for old_key, new_key in rename_map.items():
+        if old_key in target:
+            target[new_key] = target.pop(old_key)
+        else:
+            target.setdefault(new_key, None)
+
+
+def _apply_remove(target: dict[str, Any], remove_keys: list[str]) -> None:
+    for key in remove_keys:
+        target.pop(key, None)
+
+
+def _apply_require_new_field(target: dict[str, Any], fields: list[str]) -> None:
+    existing = target.setdefault("required_fields", [])
+    if isinstance(existing, list):
+        for f in fields:
+            if f not in existing:
+                existing.append(f)
+
+
+def _apply_change_type(target: dict[str, Any], types_map: Mapping[str, str]) -> None:
+    bucket = target.setdefault("type_changes", {})
+    if isinstance(bucket, dict):
+        bucket.update({k: v for k, v in types_map.items()})
+
+
+def _apply_enum_expand(target: dict[str, Any], enum_map: Mapping[str, list[str]]) -> None:
+    for enum_name, additions in enum_map.items():
+        current = target.setdefault(enum_name, [])
+        if isinstance(current, list):
+            for v in additions:
+                if v not in current:
+                    current.append(v)
+
+
+def _apply_numeric_bump(target: dict[str, Any], bumps: Mapping[str, Mapping[str, Any]]) -> None:
+    for key, change in bumps.items():
+        if "to" in change:
+            target[key] = change["to"]
+
+
+def _apply_policy_flag_flip(target: dict[str, Any], flags: Mapping[str, bool]) -> None:
+    flag_bucket = target.setdefault("flags", {})
+    if isinstance(flag_bucket, dict):
+        for k, v in flags.items():
+            flag_bucket[k] = v
+
+
+def _apply_time_window_shrink(target: dict[str, Any], windows: Mapping[str, Any]) -> None:
+    bucket = target.setdefault("time_windows", {})
+    if isinstance(bucket, dict):
+        for k, v in windows.items():
+            bucket[k] = v
+
+
+def _apply_tnc_text_swap(target: dict[str, Any], swap: Mapping[str, str]) -> None:
+    target["tnc_text"] = swap.get("to", target.get("tnc_text"))
+
+
+def _apply_side_channel_notice(target: dict[str, Any], notice: str) -> None:
+    notices = target.setdefault("side_channel", [])
+    if isinstance(notices, list):
+        notices.append(notice)
+
+
+def _apply_pricing_restructure(target: dict[str, Any], change: Mapping[str, Any]) -> None:
+    bucket = target.setdefault("pricing_flags", {})
+    if isinstance(bucket, dict):
+        for k, v in change.items():
+            bucket[k] = v
+
+
+def _apply_fee_append(target: dict[str, Any], fees: Mapping[str, Any]) -> None:
+    bucket = target.setdefault("fees", {})
+    if isinstance(bucket, dict):
+        for k, v in fees.items():
+            bucket[k] = v
+
+
+def _apply_auth_scope_bump(target: dict[str, Any], scope: Mapping[str, Any]) -> None:
+    bucket = target.setdefault("auth", {})
+    if isinstance(bucket, dict):
+        for k, v in scope.items():
+            bucket[k] = v
+
+
+def _apply_token_version_bump(target: dict[str, Any], bump: Mapping[str, Any]) -> None:
+    bucket = target.setdefault("auth", {})
+    if isinstance(bucket, dict):
+        for k, v in bump.items():
+            bucket[k] = v
+
+
+_OPERATOR_DISPATCH: dict[str, Any] = {
+    "rename": _apply_rename,
+    "remove": _apply_remove,
+    "require_new_field": _apply_require_new_field,
+    "change_type": _apply_change_type,
+    "enum_expand": _apply_enum_expand,
+    "numeric_bump": _apply_numeric_bump,
+    "policy_flag_flip": _apply_policy_flag_flip,
+    "time_window_shrink": _apply_time_window_shrink,
+    "tnc_text_swap": _apply_tnc_text_swap,
+    "side_channel_notice_append": _apply_side_channel_notice,
+    "pricing_restructure": _apply_pricing_restructure,
+    "fee_append": _apply_fee_append,
+    "auth_scope_bump": _apply_auth_scope_bump,
+    "token_version_bump": _apply_token_version_bump,
+}
+
+
+def _mutate_vendor_state(
+    vendor_state: dict[str, Any],
+    pattern: DriftPattern,
+) -> dict[str, Any]:
+    """Return a mutated deep copy of the vendor state for the given pattern.
+    Pure with respect to inputs (input dict is not modified)."""
+    mutated = copy.deepcopy(vendor_state)
+    for op_key, op_payload in pattern.mutation.items():
+        handler = _OPERATOR_DISPATCH.get(op_key)
+        if handler is None:
+            # Unknown operator keys are tolerated as no-ops so catalogue
+            # extensions don't break existing callers.
+            continue
+        handler(mutated, op_payload)
+    return mutated
+
+
+# ---------------------------------------------------------------------------
+# apply_drift (drift_injector.md §2, §3.5)
+# ---------------------------------------------------------------------------
+
+
+def apply_drift(state: DriftCallState, event: DriftEvent) -> DriftCallState:
+    """Apply a drift event to immutable state; return a new DriftCallState."""
+    pattern = _PATTERNS_BY_ID.get(event.pattern_id)
+    if pattern is None:
+        raise UnknownDriftPatternError(
+            f"no pattern registered for pattern_id: {event.pattern_id!r}",
+        )
+    if event.domain not in state.vendor_states:
+        raise DriftDomainMismatchError(
+            f"event.domain={event.domain!r} not in state.vendor_states",
+        )
+    if event in state.drift_fired:
+        raise DriftReapplicationError(
+            f"event already in drift_fired: {event!r}",
+        )
+
+    # Build new vendor_states dict with mutated copy for event.domain.
+    new_vendor_states: dict[str, dict[str, Any]] = {
+        k: copy.deepcopy(v) for k, v in state.vendor_states.items()
+    }
+    new_vendor_states[event.domain] = _mutate_vendor_state(
+        state.vendor_states[event.domain],
+        pattern,
+    )
+
+    new_schema_versions = dict(state.schema_versions)
+    new_schema_versions[event.domain] = event.to_version
+
+    new_drift_fired = state.drift_fired + (event,)
+
+    return replace(
+        state,
+        vendor_states=new_vendor_states,
+        schema_versions=new_schema_versions,
+        drift_fired=new_drift_fired,
+    )
+
+

cells/step_07_task_generator.md

@@ -0,0 +1,3 @@
+# Generate task briefs
+
+Pure, seeded, deterministic procedural generator that expands the YAML template library into concrete `GoalSpec` briefs for `DriftCallEnv.reset()`. Identical `(seed, stage, language_weights)` triples always produce byte-identical seed utterances after NFC normalization — no global RNG, no `time.time()`, no `hash()`.

cells/step_07_task_generator.py

@@ -0,0 +1,1164 @@
+"""Cell 07 — Procedural task-brief generator.
+
+Implements docs/modules/task_generator.md. Pure, seeded, deterministic
+expansion of a YAML template library into concrete ``GoalSpec`` briefs
+for ``DriftCallEnv.reset()`` (DESIGN.md §4.2, §8.3, §8.4).
+
+Contract: identical ``(seed, stage, language_weights)`` triples always
+produce byte-identical ``GoalSpec.seed_utterance`` after NFC
+normalization. No global mutable state; no ``random.random()``; no
+``time.time()``; no ``hash()``. All stochastic choices thread through
+``random.Random(stable_sub_seed(seed, tag))`` where ``stable_sub_seed``
+uses ``hashlib.blake2b(digest_size=8)``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import random
+import re
+import string
+import unicodedata
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from datetime import date, timedelta
+from pathlib import Path
+from typing import Any, Literal, cast
+
+import yaml
+
+from cells.step_04_models import GoalSpec
+
+# ---------------------------------------------------------------------------
+# Public literal types
+# ---------------------------------------------------------------------------
+
+LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"]
+Domain = Literal["airline", "cab", "restaurant", "hotel"]
+
+_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"})
+_DOMAINS: frozenset[str] = frozenset({"airline", "cab", "restaurant", "hotel"})
+_VALID_STAGES: frozenset[int] = frozenset({1, 2, 3})
+
+# Fixed reference date for deterministic date sampling (task_generator.md §3.3).
+_REFERENCE_DATE: date = date(2026, 4, 25)
+_DATE_WINDOW_DAYS: int = 60
+
+# SMS-length bound for ASR input (§3.6 invariant 7).
+_MAX_UTTERANCE_LEN: int = 280
+
+# Built-in slot conventions — §3.3 of task_generator.md. Templates may
+# override by declaring slot_distributions explicitly; otherwise these
+# name-based defaults apply.
+_DATE_SLOT_NAMES: frozenset[str] = frozenset(
+    {
+        "when",
+        "checkin",
+        "checkout",
+        "date",
+        "departure",
+        "arrival",
+        "return_when",
+        "new_when",
+    }
+)
+_INTER_CITY_SLOT_NAMES: frozenset[str] = frozenset(
+    {"from", "to", "city", "origin", "destination"}
+)
+_INTRA_CITY_SLOT_NAMES: frozenset[str] = frozenset({"pickup", "drop"})
+
+# Default domain → city-code tuples (IATA-style). Authored here so the
+# generator is self-contained without requiring the YAML library to
+# declare a cities_by_domain block.
+_DEFAULT_INTER_CITIES: tuple[str, ...] = (
+    "HYD",
+    "BLR",
+    "DEL",
+    "BOM",
+    "MAA",
+    "CCU",
+    "PNQ",
+    "AMD",
+    "JAI",
+    "GOI",
+)
+_DEFAULT_INTRA_CITIES: tuple[str, ...] = (
+    "Koramangala",
+    "Indiranagar",
+    "Whitefield",
+    "Andheri",
+    "Bandra",
+    "Powai",
+    "Gurgaon",
+    "Saket",
+    "Banjara Hills",
+    "Salt Lake",
+)
+_DEFAULT_CITIES_BY_DOMAIN: Mapping[Domain, tuple[str, ...]] = {
+    "airline": _DEFAULT_INTER_CITIES,
+    "hotel": _DEFAULT_INTER_CITIES,
+    "restaurant": _DEFAULT_INTER_CITIES,
+    "cab": _DEFAULT_INTRA_CITIES,
+}
+
+
+# ---------------------------------------------------------------------------
+# Exception hierarchy (task_generator.md §5)
+# ---------------------------------------------------------------------------
+
+
+class TaskGeneratorError(Exception):
+    """Base class for every failure raised by :mod:`step_07_task_generator`."""
+
+
+class MissingSlotError(TaskGeneratorError):
+    """Template variant references a ``{slot}`` placeholder not present in the filled SlotGrid."""
+
+
+class InvalidLanguageError(TaskGeneratorError):
+    """``language_weights`` contains a key outside :data:`LanguageCode`."""
+
+
+class InvalidLanguageWeightError(TaskGeneratorError):
+    """``language_weights`` is empty, has a negative value, sums off 1.0, or is all zero."""
+
+
+class InvalidStageError(TaskGeneratorError):
+    """``stage`` is not one of ``{1, 2, 3}``."""
+
+
+class InvalidBudgetError(TaskGeneratorError):
+    """Sampled numeric constraint falls outside the template's declared ``[low, high]`` range."""
+
+
+class TemplateFileMissingError(TaskGeneratorError):
+    """Template YAML file not found or unreadable."""
+
+
+class TemplateSchemaError(TaskGeneratorError):
+    """Template YAML present but fails schema validation."""
+
+
+class UnicodeNormalizationError(TaskGeneratorError):
+    """Rendered utterance fails NFC round-trip check (defensive)."""
+
+
+class NoVariantForLanguageError(TaskGeneratorError):
+    """Chosen template has no ``language_variants`` entry for the chosen language."""
+
+
+# ---------------------------------------------------------------------------
+# In-memory types (task_generator.md §4.2)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SlotDistribution:
+    """Either an enum (``choices``) or a uniform numeric grid (``low``, ``high``, ``step``)."""
+
+    kind: Literal["choices", "uniform", "date", "bool"]
+    choices: tuple[str, ...] | None = None
+    low: float | None = None
+    high: float | None = None
+    step: float | None = None
+
+
+@dataclass(frozen=True)
+class Template:
+    template_id: str
+    domain: Domain
+    intent: str
+    min_stage: Literal[1, 2, 3]
+    required_slots: tuple[str, ...]
+    optional_slots: tuple[str, ...]
+    slot_distributions: Mapping[str, SlotDistribution]
+    constraints_template: Mapping[str, SlotDistribution]
+    drift_slot_tags: tuple[str, ...]
+    language_variants: Mapping[LanguageCode, tuple[str, ...]]
+
+
+@dataclass(frozen=True)
+class TemplateLibrary:
+    templates: tuple[Template, ...]
+    cities_by_domain: Mapping[Domain, tuple[str, ...]]
+    i18n: Mapping[LanguageCode, Mapping[str, str]]
+
+
+@dataclass(frozen=True)
+class SlotGrid:
+    """Concrete slot values after expansion."""
+
+    values: Mapping[str, object]
+
+
+@dataclass(frozen=True)
+class RawBrief:
+    template_id: str
+    domain: Domain
+    intent: str
+    slots: SlotGrid
+    constraints: Mapping[str, object]
+    language: LanguageCode
+
+
+# ---------------------------------------------------------------------------
+# Sub-seed helper (task_generator.md §3.1)
+# ---------------------------------------------------------------------------
+
+
+def stable_sub_seed(seed: int, tag: str) -> int:
+    """Return a stable 64-bit integer derived from ``(seed, tag)``.
+
+    Uses blake2b with ``digest_size=8`` so the formula is pinned and
+    domain-separated across decision tags.
+    """
+    digest = hashlib.blake2b(f"{seed}:{tag}".encode(), digest_size=8).digest()
+    return int.from_bytes(digest, "big")
+
+
+# ---------------------------------------------------------------------------
+# NFC helpers
+# ---------------------------------------------------------------------------
+
+
+def _nfc(text: str) -> str:
+    return unicodedata.normalize("NFC", text)
+
+
+def _assert_nfc(text: str, *, where: str) -> None:
+    if not unicodedata.is_normalized("NFC", text):
+        raise UnicodeNormalizationError(
+            f"string at {where} failed NFC round-trip: {text!r}"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Template loader (task_generator.md §2.2, §3.4, §7 edge cases 1 & 8)
+# ---------------------------------------------------------------------------
+
+
+def _parse_distribution(raw: Mapping[str, Any], *, where: str) -> SlotDistribution:
+    """Parse a single slot/constraint distribution block."""
+    if "choices" in raw:
+        choices = raw["choices"]
+        if not isinstance(choices, list) or not choices:
+            raise TemplateSchemaError(f"{where}: 'choices' must be non-empty list")
+        norm_choices = tuple(_nfc(str(c)) for c in choices)
+        return SlotDistribution(kind="choices", choices=norm_choices)
+    if raw.get("distribution") == "uniform":
+        for key in ("low", "high", "step"):
+            if key not in raw:
+                raise TemplateSchemaError(f"{where}: uniform missing '{key}'")
+        low = float(raw["low"])
+        high = float(raw["high"])
+        step = float(raw["step"])
+        if step <= 0:
+            raise TemplateSchemaError(f"{where}: step must be > 0 (got {step})")
+        if low > high:
+            raise TemplateSchemaError(f"{where}: low > high ({low} > {high})")
+        span = high - low
+        # Grid must terminate cleanly at ``high`` (§7 edge case 8).
+        # Use integer step check avoiding floating-point drift.
+        ratio = span / step
+        if abs(ratio - round(ratio)) > 1e-9:
+            raise TemplateSchemaError(
+                f"{where}: step grid misaligned "
+                f"(low={low}, high={high}, step={step}) — (high-low) not divisible by step"
+            )
+        return SlotDistribution(kind="uniform", low=low, high=high, step=step)
+    if raw.get("distribution") == "date":
+        return SlotDistribution(kind="date")
+    if raw.get("distribution") == "bool":
+        return SlotDistribution(kind="bool")
+    raise TemplateSchemaError(
+        f"{where}: unrecognized distribution descriptor {dict(raw)!r}"
+    )
+
+
+def _parse_template(raw: Mapping[str, Any], *, where: str) -> Template:
+    required_keys = (
+        "template_id",
+        "domain",
+        "intent",
+        "min_stage",
+        "required_slots",
+        "optional_slots",
+        "constraints_template",
+        "drift_slot_tags",
+        "language_variants",
+    )
+    for key in required_keys:
+        if key not in raw:
+            raise TemplateSchemaError(f"{where}: missing required key {key!r}")
+
+    template_id = _nfc(str(raw["template_id"]))
+    domain_raw = str(raw["domain"])
+    if domain_raw not in _DOMAINS:
+        raise TemplateSchemaError(
+            f"{where}: domain {domain_raw!r} not in {sorted(_DOMAINS)}"
+        )
+    min_stage = int(raw["min_stage"])
+    if min_stage not in _VALID_STAGES:
+        raise TemplateSchemaError(
+            f"{where}: min_stage {min_stage} not in {sorted(_VALID_STAGES)}"
+        )
+
+    required_slots = tuple(_nfc(str(s)) for s in raw["required_slots"])
+    optional_slots = tuple(_nfc(str(s)) for s in raw["optional_slots"])
+    drift_slot_tags = tuple(_nfc(str(s)) for s in raw["drift_slot_tags"])
+
+    slot_distributions_raw = raw.get("slot_distributions", {}) or {}
+    slot_distributions: dict[str, SlotDistribution] = {}
+    for name, block in slot_distributions_raw.items():
+        slot_distributions[_nfc(str(name))] = _parse_distribution(
+            block, where=f"{where}.slot_distributions.{name}"
+        )
+
+    constraints_template: dict[str, SlotDistribution] = {}
+    for name, block in raw["constraints_template"].items():
+        constraints_template[_nfc(str(name))] = _parse_distribution(
+            block, where=f"{where}.constraints_template.{name}"
+        )
+
+    language_variants_raw = raw["language_variants"]
+    if not isinstance(language_variants_raw, dict):
+        raise TemplateSchemaError(f"{where}: language_variants must be a mapping")
+    language_variants: dict[LanguageCode, tuple[str, ...]] = {}
+    for lang, variants in language_variants_raw.items():
+        if lang not in _LANGUAGE_CODES:
+            raise TemplateSchemaError(
+                f"{where}: language key {lang!r} not in {sorted(_LANGUAGE_CODES)}"
+            )
+        if not isinstance(variants, list) or not variants:
+            raise TemplateSchemaError(
+                f"{where}.language_variants.{lang}: must be non-empty list"
+            )
+        language_variants[cast("LanguageCode", lang)] = tuple(
+            _nfc(str(v)) for v in variants
+        )
+
+    # Every template must have ≥ 1 variant per LanguageCode (§7 edge case 7).
+    for code in _LANGUAGE_CODES:
+        if code not in language_variants:
+            raise TemplateSchemaError(
+                f"{where}: language_variants missing required code {code!r}"
+            )
+
+    # Static placeholder scan (§7 edge case 1).
+    declared_placeholders = (
+        set(required_slots)
+        | set(optional_slots)
+        | set(constraints_template.keys())
+    )
+    for lang, variants in language_variants.items():
+        for variant in variants:
+            for placeholder in _iter_placeholders(variant):
+                if placeholder not in declared_placeholders:
+                    raise TemplateSchemaError(
+                        f"{where}.language_variants.{lang}: variant references "
+                        f"undeclared placeholder {placeholder!r} in {variant!r}"
+                    )
+
+    return Template(
+        template_id=template_id,
+        domain=cast("Domain", domain_raw),
+        intent=_nfc(str(raw["intent"])),
+        min_stage=cast("Literal[1, 2, 3]", min_stage),
+        required_slots=required_slots,
+        optional_slots=optional_slots,
+        slot_distributions=slot_distributions,
+        constraints_template=constraints_template,
+        drift_slot_tags=drift_slot_tags,
+        language_variants=language_variants,
+    )
+
+
+def _iter_placeholders(fmt: str) -> Iterator[str]:
+    """Yield placeholder names in a format string (ignores literals)."""
+    for _literal, field_name, _spec, _conv in string.Formatter().parse(fmt):
+        if field_name is not None and field_name != "":
+            yield field_name
+
+
+def load_templates(
+    path: str | Path = "data/task_briefs/templates.yaml",
+    i18n_path: str | Path | None = None,
+) -> TemplateLibrary:
+    """Parse the template YAML file and return an in-memory :class:`TemplateLibrary`.
+
+    ``i18n_path`` defaults to ``data/task_briefs/i18n.yaml`` alongside
+    ``path``. All strings are NFC-normalized on read (§3.4).
+    """
+    templates_path = Path(path)
+    if not templates_path.exists():
+        raise TemplateFileMissingError(f"templates YAML not found: {templates_path}")
+
+    if i18n_path is None:
+        i18n_path = templates_path.parent / "i18n.yaml"
+    i18n_path = Path(i18n_path)
+
+    try:
+        with templates_path.open("r", encoding="utf-8") as fh:
+            raw_templates = yaml.safe_load(fh)
+    except yaml.YAMLError as exc:
+        raise TemplateSchemaError(f"templates YAML malformed: {exc}") from exc
+
+    if raw_templates is None:
+        raise TemplateSchemaError("templates YAML is empty")
+
+    parsed_templates: list[Template] = []
+    cities_by_domain: dict[Domain, tuple[str, ...]] = {}
+
+    if isinstance(raw_templates, dict):
+        tmpl_list = raw_templates.get("templates", [])
+        raw_cities = raw_templates.get("cities_by_domain", {}) or {}
+        for dom, lst in raw_cities.items():
+            if dom not in _DOMAINS:
+                raise TemplateSchemaError(f"cities_by_domain: bad domain {dom!r}")
+            cities_by_domain[cast("Domain", dom)] = tuple(_nfc(str(c)) for c in lst)
+    elif isinstance(raw_templates, list):
+        tmpl_list = raw_templates
+    else:
+        raise TemplateSchemaError(
+            f"templates YAML root must be list or mapping, got {type(raw_templates).__name__}"
+        )
+
+    if not isinstance(tmpl_list, list) or not tmpl_list:
+        raise TemplateSchemaError("templates YAML must contain a non-empty list")
+
+    for idx, raw in enumerate(tmpl_list):
+        if not isinstance(raw, dict):
+            raise TemplateSchemaError(
+                f"templates[{idx}]: entry must be a mapping, got {type(raw).__name__}"
+            )
+        parsed_templates.append(_parse_template(raw, where=f"templates[{idx}]"))
+
+    # i18n file is optional; if absent we use an empty mapping.
+    _LANG_CODES: tuple[LanguageCode, ...] = ("hi", "ta", "kn", "en", "hinglish")
+    i18n_data: dict[LanguageCode, dict[str, str]] = {code: {} for code in _LANG_CODES}
+    if i18n_path.exists():
+        try:
+            with i18n_path.open("r", encoding="utf-8") as fh:
+                raw_i18n = yaml.safe_load(fh) or {}
+        except yaml.YAMLError as exc:
+            raise TemplateSchemaError(f"i18n YAML malformed: {exc}") from exc
+        if not isinstance(raw_i18n, dict):
+            raise TemplateSchemaError("i18n YAML root must be a mapping")
+        for lang, block in raw_i18n.items():
+            if lang not in _LANGUAGE_CODES:
+                raise TemplateSchemaError(
+                    f"i18n: language key {lang!r} not in {sorted(_LANGUAGE_CODES)}"
+                )
+            if not isinstance(block, dict):
+                raise TemplateSchemaError(f"i18n.{lang}: must be a mapping")
+            flat: dict[str, str] = {}
+            _flatten_i18n(block, prefix="", out=flat)
+            i18n_data[cast("LanguageCode", lang)] = {
+                _nfc(str(k)): _nfc(str(v)) for k, v in flat.items()
+            }
+
+    return TemplateLibrary(
+        templates=tuple(parsed_templates),
+        cities_by_domain=cities_by_domain,
+        i18n=i18n_data,
+    )
+
+
+def _flatten_i18n(block: Mapping[str, Any], *, prefix: str, out: dict[str, str]) -> None:
+    """Flatten nested i18n dicts into dotted keys, NFC everything."""
+    for k, v in block.items():
+        key = f"{prefix}.{k}" if prefix else str(k)
+        if isinstance(v, dict):
+            _flatten_i18n(v, prefix=key, out=out)
+        else:
+            out[key] = str(v)
+
+
+# ---------------------------------------------------------------------------
+# Lazy singleton
+# ---------------------------------------------------------------------------
+
+_library_cache: TemplateLibrary | None = None
+_library_override: TemplateLibrary | None = None
+
+
+def _get_library() -> TemplateLibrary:
+    """Return the process-wide TemplateLibrary, loading lazily."""
+    if _library_override is not None:
+        return _library_override
+    global _library_cache
+    if _library_cache is None:
+        _library_cache = _load_default_library()
+    return _library_cache
+
+
+def _load_default_library() -> TemplateLibrary:
+    """Try the production path, then fall back to the packaged inline library."""
+    default_path = Path("data/task_briefs/templates.yaml")
+    if default_path.exists():
+        return load_templates(default_path)
+    return _builtin_library()
+
+
+def set_library_override(library: TemplateLibrary | None) -> None:
+    """Test hook: pin :func:`_get_library` to a specific library (or clear)."""
+    global _library_override
+    _library_override = library
+
+
+def reset_library_cache() -> None:
+    """Test hook: clear the lazy cache so the next call reloads."""
+    global _library_cache
+    _library_cache = None
+
+
+# ---------------------------------------------------------------------------
+# Built-in library (fallback when data/ isn't authored yet)
+# ---------------------------------------------------------------------------
+
+
+def _builtin_library() -> TemplateLibrary:
+    """Minimal 5-template library so the generator is self-contained during dev."""
+    # Shared numeric grids.
+    budget_flight = SlotDistribution(kind="uniform", low=3000.0, high=15000.0, step=500.0)
+    budget_hotel = SlotDistribution(kind="uniform", low=2000.0, high=10000.0, step=500.0)
+    budget_cab = SlotDistribution(kind="uniform", low=200.0, high=2000.0, step=50.0)
+    budget_food = SlotDistribution(kind="uniform", low=200.0, high=1000.0, step=50.0)
+    time_window = SlotDistribution(
+        kind="choices", choices=("morning", "afternoon", "evening", "late_night")
+    )
+    date_dist = SlotDistribution(kind="date")
+    veg_only = SlotDistribution(kind="bool")
+    pax = SlotDistribution(kind="uniform", low=1.0, high=4.0, step=1.0)
+
+    cities_inter = (
+        "HYD",
+        "BLR",
+        "DEL",
+        "BOM",
+        "MAA",
+        "CCU",
+        "PNQ",
+        "AMD",
+        "JAI",
+        "GOI",
+    )
+    cities_intra = (
+        "Koramangala",
+        "Indiranagar",
+        "Whitefield",
+        "Andheri",
+        "Bandra",
+        "Powai",
+        "Gurgaon",
+        "Saket",
+        "Banjara Hills",
+        "Salt Lake",
+    )
+
+    airline = Template(
+        template_id="airline.book.fixture_v1",
+        domain="airline",
+        intent="book_flight",
+        min_stage=1,
+        required_slots=("from", "to", "when"),
+        optional_slots=(),
+        slot_distributions={
+            "from": SlotDistribution(kind="choices", choices=cities_inter),
+            "to": SlotDistribution(kind="choices", choices=cities_inter),
+            "when": date_dist,
+        },
+        constraints_template={
+            "budget_inr": budget_flight,
+            "time_window": time_window,
+        },
+        drift_slot_tags=("price", "total_fare_inr"),
+        language_variants={
+            "hinglish": (
+                "Bhai {when} ko {from} se {to} jaana hai, {budget_inr} rupees max, {time_window}",
+            ),
+            "hi": (
+                "{when} को {from} से {to} जाना है, {budget_inr} रुपये से कम, {time_window}",
+            ),
+            "ta": (
+                "{when} அன்று {from} லிருந்து {to} டிக்கெட் வேண்டும், {budget_inr} ரூபாய் கீழ், {time_window}",
+            ),
+            "kn": (
+                "{when} ರಂದು {from} ಇಂದ {to} ಗೆ ಟಿಕೆಟ್ ಬೇಕು, {budget_inr} ರೂಪಾಯಿ ಒಳಗೆ, {time_window}",
+            ),
+            "en": (
+                "Flight from {from} to {to} on {when}, under ₹{budget_inr}, {time_window}",
+            ),
+        },
+    )
+
+    cab = Template(
+        template_id="cab.book.fixture_v1",
+        domain="cab",
+        intent="book_cab",
+        min_stage=1,
+        required_slots=("pickup", "drop", "when"),
+        optional_slots=(),
+        slot_distributions={
+            "pickup": SlotDistribution(kind="choices", choices=cities_intra),
+            "drop": SlotDistribution(kind="choices", choices=cities_intra),
+            "when": date_dist,
+        },
+        constraints_template={
+            "budget_inr": budget_cab,
+            "vehicle_class": SlotDistribution(
+                kind="choices", choices=("mini", "sedan", "suv")
+            ),
+        },
+        drift_slot_tags=("fare_inr", "fare_breakdown"),
+        language_variants={
+            "hinglish": (
+                "{when} ko {pickup} se {drop} cab chahiye, {budget_inr} ke andar, {vehicle_class}",
+            ),
+            "hi": (
+                "{when} को {pickup} से {drop} कैब चाहिए, {budget_inr} के अंदर, {vehicle_class}",
+            ),
+            "ta": (
+                "{when} அன்று {pickup} லிருந்து {drop} கேப், {budget_inr} கீழ், {vehicle_class}",
+            ),
+            "kn": (
+                "{when} ರಂದು {pickup} ಇಂದ {drop} ಟ್ಯಾಕ್ಸಿ, {budget_inr} ಒಳಗೆ, {vehicle_class}",
+            ),
+            "en": (
+                "Cab from {pickup} to {drop} on {when}, under ₹{budget_inr}, {vehicle_class}",
+            ),
+        },
+    )
+
+    restaurant = Template(
+        template_id="restaurant.order.fixture_v1",
+        domain="restaurant",
+        intent="order_food",
+        min_stage=2,
+        required_slots=("city", "cuisine", "when"),
+        optional_slots=(),
+        slot_distributions={
+            "city": SlotDistribution(kind="choices", choices=cities_inter),
+            "cuisine": SlotDistribution(
+                kind="choices", choices=("Biryani", "Dosa", "Pizza", "Thali", "Noodles")
+            ),
+            "when": date_dist,
+        },
+        constraints_template={
+            "budget_inr": budget_food,
+            "veg_only": veg_only,
+        },
+        drift_slot_tags=("min_order", "veg_filter"),
+        language_variants={
+            "hinglish": (
+                "Bhai {when} ko {city} mein {cuisine} order karna hai, {budget_inr} ke andar, veg_only={veg_only}",
+            ),
+            "hi": (
+                "{when} को {city} में {cuisine} ऑर्डर करना है, {budget_inr} के अंदर, veg_only={veg_only}",
+            ),
+            "ta": (
+                "{when} அன்று {city} இல் {cuisine} ஆர்டர், {budget_inr} கீழ், veg_only={veg_only}",
+            ),
+            "kn": (
+                "{when} ರಂದು {city} ನಲ್ಲಿ {cuisine} ಆರ್ಡರ್, {budget_inr} ಒಳಗೆ, veg_only={veg_only}",
+            ),
+            "en": (
+                "Order {cuisine} in {city} on {when}, under ₹{budget_inr}, veg_only={veg_only}",
+            ),
+        },
+    )
+
+    hotel = Template(
+        template_id="hotel.book.fixture_v1",
+        domain="hotel",
+        intent="book_hotel",
+        min_stage=2,
+        required_slots=("city", "checkin", "checkout"),
+        optional_slots=(),
+        slot_distributions={
+            "city": SlotDistribution(kind="choices", choices=cities_inter),
+            "checkin": date_dist,
+            "checkout": date_dist,
+        },
+        constraints_template={
+            "budget_inr": budget_hotel,
+            "room_type": SlotDistribution(
+                kind="choices", choices=("single", "double", "suite")
+            ),
+        },
+        drift_slot_tags=("cancel_window", "gst_number"),
+        language_variants={
+            "hinglish": (
+                "{city} mein {checkin} se {checkout} tak hotel chahiye, {budget_inr} per night, {room_type}",
+            ),
+            "hi": (
+                "{city} में {checkin} से {checkout} तक होटल चाहिए, {budget_inr} प्रति रात, {room_type}",
+            ),
+            "ta": (
+                "{city} இல் {checkin} முதல் {checkout} வரை ஹோட்டல், {budget_inr} ஒரு இரவு, {room_type}",
+            ),
+            "kn": (
+                "{city} ನಲ್ಲಿ {checkin} ಇಂದ {checkout} ವರೆಗೆ ಹೋಟೆಲ್, {budget_inr} ಒಂದು ರಾತ್ರಿ, {room_type}",
+            ),
+            "en": (
+                "Hotel in {city} from {checkin} to {checkout}, ₹{budget_inr} per night, {room_type}",
+            ),
+        },
+    )
+
+    # Stage-3 compound-constraint airline template — adds a third constraint.
+    airline_compound = Template(
+        template_id="airline.book.compound_v1",
+        domain="airline",
+        intent="book_flight",
+        min_stage=3,
+        required_slots=("from", "to", "when"),
+        optional_slots=(),
+        slot_distributions={
+            "from": SlotDistribution(kind="choices", choices=cities_inter),
+            "to": SlotDistribution(kind="choices", choices=cities_inter),
+            "when": date_dist,
+        },
+        constraints_template={
+            "budget_inr": budget_flight,
+            "time_window": time_window,
+            "passenger_count": pax,
+        },
+        drift_slot_tags=("price", "total_fare_inr", "passenger_count"),
+        language_variants={
+            "hinglish": (
+                "{when} ko {from} se {to}, {passenger_count} log, {budget_inr} max, {time_window}",
+            ),
+            "hi": (
+                "{when} को {from} से {to}, {passenger_count} लोग, {budget_inr} रुपये, {time_window}",
+            ),
+            "ta": (
+                "{when} அன்று {from} லிருந்து {to}, {passenger_count} பேர், {budget_inr} ரூபாய், {time_window}",
+            ),
+            "kn": (
+                "{when} ರಂದು {from} ಇಂದ {to}, {passenger_count} ಜನ, {budget_inr} ರೂಪಾಯಿ, {time_window}",
+            ),
+            "en": (
+                "Flight {from} to {to} on {when} for {passenger_count} pax, ₹{budget_inr}, {time_window}",
+            ),
+        },
+    )
+
+    return TemplateLibrary(
+        templates=(airline, cab, restaurant, hotel, airline_compound),
+        cities_by_domain={
+            "airline": cities_inter,
+            "hotel": cities_inter,
+            "cab": cities_intra,
+            "restaurant": cities_inter,
+        },
+        i18n={
+            "hi": {"cities.BLR": "बेंगलुरु", "cities.MAA": "चेन्नई"},
+            "ta": {"cities.BLR": "பெங்களூரு", "cities.MAA": "சென்னை"},
+            "kn": {"cities.BLR": "ಬೆಂಗಳೂರು", "cities.MAA": "ಚೆನ್ನೈ"},
+            "en": {"cities.BLR": "Bengaluru"},
+            "hinglish": {"cities.BLR": "Bengaluru"},
+        },
+    )
+
+
+# ---------------------------------------------------------------------------
+# Picker + expander (task_generator.md §2.2, §3.2, §3.3)
+# ---------------------------------------------------------------------------
+
+
+def _pick_domain(seed: int, library: TemplateLibrary, stage: int) -> Domain:
+    """Pick uniformly from domains that have ≥ 1 eligible template at ``stage``."""
+    available = sorted({t.domain for t in library.templates if t.min_stage <= stage})
+    if not available:
+        raise TemplateSchemaError(
+            f"library has no templates eligible at stage={stage}"
+        )
+    rng = random.Random(stable_sub_seed(seed, "domain"))
+    return rng.choice(available)
+
+
+def _eligible_templates(
+    library: TemplateLibrary,
+    stage: int,
+    domain: Domain,
+) -> tuple[Template, ...]:
+    return tuple(
+        t for t in library.templates if t.domain == domain and t.min_stage <= stage
+    )
+
+
+def _pick_template(
+    seed: int,
+    stage: int,
+    domain: Domain,
+    library: TemplateLibrary,
+) -> Template:
+    eligible = _eligible_templates(library, stage, domain)
+    if not eligible:
+        raise TemplateSchemaError(
+            f"no eligible templates for domain={domain!r} stage={stage}"
+        )
+    rng = random.Random(stable_sub_seed(seed, "template"))
+    # Use sorted template_ids for deterministic ordering.
+    ordered = tuple(sorted(eligible, key=lambda t: t.template_id))
+    return rng.choice(ordered)
+
+
+def _sample_slot_value(
+    rng: random.Random,
+    name: str,
+    dist: SlotDistribution,
+    *,
+    template_id: str,
+) -> object:
+    if dist.kind == "choices":
+        if not dist.choices:
+            raise TemplateSchemaError(
+                f"{template_id}.{name}: empty choices list"
+            )
+        return rng.choice(dist.choices)
+    if dist.kind == "uniform":
+        assert dist.low is not None and dist.high is not None and dist.step is not None
+        steps = int(round((dist.high - dist.low) / dist.step))
+        pick = rng.randint(0, steps)
+        value = dist.low + pick * dist.step
+        # Integer-ify when step + bounds are integral.
+        if float(int(dist.step)) == dist.step and float(int(dist.low)) == dist.low:
+            value = int(round(value))
+        # Post-check (§7 edge case 3).
+        lo = int(dist.low) if isinstance(value, int) else dist.low
+        hi = int(dist.high) if isinstance(value, int) else dist.high
+        if not (lo <= value <= hi):
+            raise InvalidBudgetError(
+                f"{template_id}.{name}: sampled {value} outside [{dist.low}, {dist.high}]"
+            )
+        return value
+    if dist.kind == "date":
+        offset = rng.randint(0, _DATE_WINDOW_DAYS - 1)
+        return (_REFERENCE_DATE + timedelta(days=offset)).isoformat()
+    if dist.kind == "bool":
+        return bool(rng.getrandbits(1))
+    raise TemplateSchemaError(
+        f"{template_id}.{name}: unknown distribution kind {dist.kind!r}"
+    )
+
+
+def _resolve_slot_distribution(
+    template: Template,
+    name: str,
+    library: TemplateLibrary,
+) -> SlotDistribution | None:
+    """Resolve a slot's distribution, preferring explicit declaration then conventions."""
+    explicit = template.slot_distributions.get(name)
+    if explicit is not None:
+        return explicit
+    # Constraints block can also declare slot distributions that double as fills.
+    constraint = template.constraints_template.get(name)
+    if constraint is not None:
+        return constraint
+    # Conventional fills by slot name.
+    if name in _DATE_SLOT_NAMES:
+        return SlotDistribution(kind="date")
+    if name in _INTER_CITY_SLOT_NAMES:
+        pool = library.cities_by_domain.get(template.domain) or _DEFAULT_CITIES_BY_DOMAIN.get(
+            template.domain, _DEFAULT_INTER_CITIES
+        )
+        return SlotDistribution(kind="choices", choices=pool)
+    if name in _INTRA_CITY_SLOT_NAMES:
+        pool = library.cities_by_domain.get(template.domain) or _DEFAULT_INTRA_CITIES
+        return SlotDistribution(kind="choices", choices=pool)
+    return None
+
+
+def _expand_slots(
+    seed: int,
+    template: Template,
+    *,
+    stage: int,
+    library: TemplateLibrary,
+) -> tuple[SlotGrid, dict[str, object]]:
+    """Sample one concrete value per required slot; stage-aware constraint pick.
+
+    Returns ``(SlotGrid, constraints_dict)``.
+    """
+    values: dict[str, object] = {}
+
+    # Required slots — always sampled.
+    for name in template.required_slots:
+        dist = _resolve_slot_distribution(template, name, library)
+        if dist is None:
+            raise TemplateSchemaError(
+                f"{template.template_id}: required slot {name!r} has no distribution "
+                f"(declare in slot_distributions or use a conventional name)"
+            )
+        rng = random.Random(stable_sub_seed(seed, f"slot:{name}"))
+        values[name] = _sample_slot_value(rng, name, dist, template_id=template.template_id)
+
+    # Optional slots — included with probability 0.5 (seeded). Silently
+    # skipped if no distribution resolves (template declares the slot as
+    # available but does not wire a fill source).
+    for name in template.optional_slots:
+        dist = _resolve_slot_distribution(template, name, library)
+        if dist is None:
+            continue
+        rng = random.Random(stable_sub_seed(seed, f"opt:{name}"))
+        if rng.random() < 0.5:
+            sub_rng = random.Random(stable_sub_seed(seed, f"slot:{name}"))
+            values[name] = _sample_slot_value(
+                sub_rng, name, dist, template_id=template.template_id
+            )
+
+    # Constraints — stage-aware sub-selection (§3.5).
+    max_constraints = {1: 2, 2: 3, 3: 4}[stage]
+    constraint_names = list(template.constraints_template.keys())
+    # Stage 1: keep only the first max_constraints deterministically.
+    # Stage 2/3: include all declared constraints up to max.
+    kept = constraint_names[:max_constraints]
+    constraints: dict[str, object] = {}
+    for name in kept:
+        dist = template.constraints_template[name]
+        rng = random.Random(stable_sub_seed(seed, f"constraint:{name}"))
+        value = _sample_slot_value(
+            rng, name, dist, template_id=template.template_id
+        )
+        constraints[name] = value
+        # Also mirror into slots so variant-format can reference {budget_inr}.
+        values[name] = value
+
+    # NFC-normalize any string leaves.
+    for k, v in list(values.items()):
+        if isinstance(v, str):
+            values[k] = _nfc(v)
+    for k, v in list(constraints.items()):
+        if isinstance(v, str):
+            constraints[k] = _nfc(v)
+
+    return SlotGrid(values=values), constraints
+
+
+# ---------------------------------------------------------------------------
+# Language picker
+# ---------------------------------------------------------------------------
+
+
+def _validate_language_weights(language_weights: Mapping[str, float]) -> None:
+    """Raise on any malformed input per §3.2."""
+    if not isinstance(language_weights, Mapping) or len(language_weights) == 0:
+        raise InvalidLanguageWeightError("language_weights is empty")
+
+    bad_keys = [k for k in language_weights if k not in _LANGUAGE_CODES]
+    if bad_keys:
+        raise InvalidLanguageError(
+            f"unsupported language key(s): {bad_keys} "
+            f"(allowed: {sorted(_LANGUAGE_CODES)})"
+        )
+
+    for k, v in language_weights.items():
+        if not isinstance(v, (int, float)) or isinstance(v, bool):
+            raise InvalidLanguageWeightError(
+                f"language_weights[{k!r}] must be numeric, got {type(v).__name__}"
+            )
+        if v < 0:
+            raise InvalidLanguageWeightError(
+                f"language_weights[{k!r}]={v} is negative"
+            )
+
+    total = sum(float(v) for v in language_weights.values())
+    if abs(total - 1.0) > 1e-6:
+        raise InvalidLanguageWeightError(
+            f"language_weights sum {total!r} outside [1-1e-6, 1+1e-6]"
+        )
+
+    # Defensive all-zero check (§3.2 last bullet).
+    if all(float(v) == 0.0 for v in language_weights.values()):
+        raise InvalidLanguageWeightError(
+            "language_weights are all zero (would have no population to sample)"
+        )
+
+
+def _pick_language(
+    seed: int,
+    language_weights: Mapping[LanguageCode, float],
+) -> LanguageCode:
+    rng = random.Random(stable_sub_seed(seed, "language"))
+    # Deterministic ordering of keys for reproducibility across dict insertion orders.
+    codes = sorted(language_weights.keys())
+    weights = [float(language_weights[c]) for c in codes]
+    chosen = rng.choices(codes, weights=weights, k=1)[0]
+    return chosen
+
+
+# ---------------------------------------------------------------------------
+# Utterance formatter
+# ---------------------------------------------------------------------------
+
+
+_PLACEHOLDER_RE = re.compile(r"\{([a-zA-Z_][a-zA-Z0-9_]*)\}")
+
+
+def _format_utterance(
+    seed: int,
+    template: Template,
+    slots: SlotGrid,
+    language: LanguageCode,
+) -> str:
+    variants = template.language_variants.get(language)
+    if not variants:
+        raise NoVariantForLanguageError(
+            f"template {template.template_id!r} has no variants for language {language!r}"
+        )
+    rng = random.Random(stable_sub_seed(seed, "variant"))
+    chosen = rng.choice(tuple(variants))
+
+    # Render by placeholder-by-placeholder substitution so a missing slot
+    # raises MissingSlotError with the exact field name rather than whatever
+    # ``str.format`` would surface.
+    def _repl(match: re.Match[str]) -> str:
+        name = match.group(1)
+        if name not in slots.values:
+            raise MissingSlotError(
+                f"template {template.template_id!r} variant references {{{name}}} "
+                f"but slot is unbound (slots={sorted(slots.values)})"
+            )
+        value = slots.values[name]
+        if isinstance(value, bool):
+            return "true" if value else "false"
+        if isinstance(value, float):
+            # Trim trailing zeros for cleanness, but keep determinism.
+            if value.is_integer():
+                return str(int(value))
+            return str(value)
+        return str(value)
+
+    rendered = _PLACEHOLDER_RE.sub(_repl, chosen)
+    normalized = _nfc(rendered)
+    _assert_nfc(normalized, where=f"utterance({template.template_id}, {language})")
+    return normalized
+
+
+# ---------------------------------------------------------------------------
+# Primary entry point
+# ---------------------------------------------------------------------------
+
+
+def generate(
+    seed: int,
+    stage: Literal[1, 2, 3],
+    language_weights: Mapping[LanguageCode, float],
+) -> GoalSpec:
+    """Produce one :class:`GoalSpec` for episode ``seed`` at curriculum ``stage``.
+
+    Determinism: identical ``(seed, stage, language_weights)`` ⇒ identical
+    ``GoalSpec`` after NFC normalization of ``seed_utterance``.
+    """
+    # Stage validation (cheapest first).
+    if stage not in _VALID_STAGES:
+        raise InvalidStageError(
+            f"stage must be in {sorted(_VALID_STAGES)}, got {stage!r}"
+        )
+
+    _validate_language_weights(cast("Mapping[str, float]", language_weights))
+
+    library = _get_library()
+
+    domain = _pick_domain(seed, library, int(stage))
+    template = _pick_template(seed, int(stage), domain, library)
+    slot_grid, constraints = _expand_slots(
+        seed, template, stage=int(stage), library=library
+    )
+    language = _pick_language(seed, language_weights)
+    utterance = _format_utterance(seed, template, slot_grid, language)
+
+    if len(utterance) > _MAX_UTTERANCE_LEN:
+        # Truncate is incorrect (breaks determinism/meaning). Raise so the
+        # template author shortens the variant.
+        raise TemplateSchemaError(
+            f"rendered utterance exceeds {_MAX_UTTERANCE_LEN} chars "
+            f"({len(utterance)}): {utterance!r}"
+        )
+
+    # Slot dict exposed on GoalSpec should exclude constraint-named entries —
+    # those live in ``constraints``. ``required_slots`` + included optionals only.
+    slot_keys = set(template.required_slots) | set(template.optional_slots)
+    slots_out = {k: v for k, v in slot_grid.values.items() if k in slot_keys}
+
+    return GoalSpec(
+        domain=template.domain,
+        intent=template.intent,
+        slots=slots_out,
+        constraints=constraints,
+        language=language,
+        seed_utterance=utterance,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Variant enumerator (task_generator.md §2.2)
+# ---------------------------------------------------------------------------
+
+
+def enumerate_variants(
+    limit: int | None = None,
+    stage: int = 3,
+    language_weights: Mapping[LanguageCode, float] | None = None,
+) -> Iterator[GoalSpec]:
+    """Deterministic walk over the procedural grid."""
+    if stage not in _VALID_STAGES:
+        raise InvalidStageError(f"stage must be in {sorted(_VALID_STAGES)}, got {stage!r}")
+    if language_weights is None:
+        language_weights = {
+            "en": 0.2,
+            "hi": 0.2,
+            "ta": 0.2,
+            "kn": 0.2,
+            "hinglish": 0.2,
+        }
+    count = 0
+    seed = 0
+    while limit is None or count < limit:
+        yield generate(seed, cast("Literal[1, 2, 3]", stage), language_weights)
+        count += 1
+        seed += 1
+
+
+# ---------------------------------------------------------------------------
+# Test helpers (public so test modules can look up templates)
+# ---------------------------------------------------------------------------
+
+
+def _lookup_template_for_test(template_id: str) -> Template:
+    """Public-for-tests helper to resolve a template by ID."""
+    lib = _get_library()
+    for t in lib.templates:
+        if t.template_id == template_id:
+            return t
+    raise KeyError(template_id)
+
+
+__all__ = [
+    "Domain",
+    "InvalidBudgetError",
+    "InvalidLanguageError",
+    "InvalidLanguageWeightError",
+    "InvalidStageError",
+    "LanguageCode",
+    "MissingSlotError",
+    "NoVariantForLanguageError",
+    "RawBrief",
+    "SlotDistribution",
+    "SlotGrid",
+    "TaskGeneratorError",
+    "Template",
+    "TemplateFileMissingError",
+    "TemplateLibrary",
+    "TemplateSchemaError",
+    "UnicodeNormalizationError",
+    "_lookup_template_for_test",
+    "enumerate_variants",
+    "generate",
+    "load_templates",
+    "reset_library_cache",
+    "set_library_override",
+    "stable_sub_seed",
+]

cells/step_08_rewards.md

@@ -0,0 +1,7 @@
+## step_08_rewards
+
+Pure-functional reward pipeline for DriftCall (DESIGN.md §7, docs/modules/rewards.md).
+Converts a frozen `Episode` into a frozen `Rewards` record through five independent
+signals (R1..R5), Brier calibration, an uncertain floor, and a 3-decimal final reward.
+No LLM judge, no I/O, no clock — every computation is reproducible from the transcript
+alone.

cells/step_08_rewards.py

@@ -0,0 +1,1133 @@
+"""DriftCall reward pipeline.
+
+Implements docs/modules/rewards.md and DESIGN.md §7. Pure-functional: no I/O,
+no clock, no RNG, no LLM. Every reward is deterministic on the input Episode.
+
+Public surface:
+    Episode, Rewards, RewardComputationError, AVAILABLE_TOOL_REGISTRY,
+    task_completion, drift_detection, constraint_adherence,
+    format_compliance, anti_hack_penalty,
+    combine_quality, brier_penalty, apply_uncertain_floor, final_reward,
+    compute_rewards.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+from cells.step_04_models import (
+    ActionType,
+    DriftCallAction,
+    DriftEvent,
+    GoalSpec,
+    ToolResult,
+)
+from cells.step_05_vendors import TOOLS as _VENDOR_TOOLS
+from cells.step_06_drift_injector import DriftPattern, list_patterns
+
+__all__ = [
+    "AVAILABLE_TOOL_REGISTRY",
+    "Episode",
+    "RewardComputationError",
+    "Rewards",
+    "anti_hack_penalty",
+    "apply_uncertain_floor",
+    "brier_penalty",
+    "combine_quality",
+    "compute_rewards",
+    "constraint_adherence",
+    "drift_detection",
+    "final_reward",
+    "format_compliance",
+    "task_completion",
+]
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+
+AVAILABLE_TOOL_REGISTRY: frozenset[str] = frozenset(_VENDOR_TOOLS)
+
+_RESERVED_KEYS: frozenset[str] = frozenset(
+    {"__turn__", "__schema_version__", "__done__", "__episode_id__"},
+)
+
+_VALID_DRIFT_TYPES: frozenset[str] = frozenset(
+    {"schema", "policy", "tnc", "pricing", "auth"},
+)
+
+_VALID_TERMINATIONS: frozenset[str] = frozenset(
+    {"SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"},
+)
+
+# Hour windows (24h IST). "night" wraps midnight; encoded as (lo, hi+24).
+_TIME_WINDOWS: dict[str, tuple[int, int]] = {
+    "morning": (6, 12),
+    "afternoon": (12, 18),
+    "evening": (18, 22),
+    "night": (22, 30),
+}
+
+_FAILURE_STATUSES: frozenset[str] = frozenset(
+    {"schema_error", "policy_error", "auth_error"},
+)
+
+# snake_case identifier with at least one underscore between alphanumeric segments
+_SNAKE_FIELD_RE = re.compile(r"\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b")
+
+_PATTERNS_BY_ID: dict[str, DriftPattern] = {p.id: p for p in list_patterns()}
+
+
+# ---------------------------------------------------------------------------
+# Errors
+# ---------------------------------------------------------------------------
+
+
+class RewardComputationError(Exception):
+    """Raised when rewards cannot be computed for a malformed episode."""
+
+    def __init__(self, reason: str, episode_id: str | None = None) -> None:
+        super().__init__(reason)
+        self.reason = reason
+        self.episode_id = episode_id
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Episode:
+    episode_id: str
+    goal: GoalSpec
+    actions: tuple[DriftCallAction, ...]
+    action_turns: tuple[int, ...]
+    tool_results: tuple[ToolResult, ...]
+    tool_result_turns: tuple[int, ...]
+    drift_log: tuple[DriftEvent, ...]
+    vendor_states_final: dict[str, dict[str, Any]]
+    schema_versions_final: dict[str, str]
+    max_turns: int
+    turns_used: int
+    terminated_by: Literal["SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"]
+    stage: Literal[1, 2, 3]
+    drift_pattern_overrides: dict[str, DriftPattern] = field(default_factory=dict)
+
+
+@dataclass(frozen=True)
+class Rewards:
+    r1: float
+    r2: float
+    r3: float
+    r4: float
+    r5: float
+    quality: float
+    brier: float
+    reward: float
+    confidence: float | None
+    floor_applied: bool
+    breakdown: dict[str, Any]
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _resolve_pattern(episode: Episode, drift: DriftEvent) -> DriftPattern:
+    """Look up the DriftPattern via episode overrides, then global registry."""
+    pattern_id = drift.pattern_id
+    if pattern_id in episode.drift_pattern_overrides:
+        return episode.drift_pattern_overrides[pattern_id]
+    if pattern_id in _PATTERNS_BY_ID:
+        return _PATTERNS_BY_ID[pattern_id]
+    raise RewardComputationError(
+        f"unknown pattern_id: {pattern_id}",
+        episode.episode_id,
+    )
+
+
+def _validate_hints(pattern: DriftPattern, episode: Episode) -> tuple[str, ...]:
+    """Return non-empty stripped hints; raise on empty."""
+    cleaned = tuple(h for h in pattern.detection_hints if h and h.strip())
+    if not cleaned:
+        raise RewardComputationError(
+            f"drift {pattern.id} has empty detection_hints",
+            episode.episode_id,
+        )
+    return cleaned
+
+
+def _is_finite(value: float) -> bool:
+    return math.isfinite(value)
+
+
+def _safe_lower(text: str | None) -> str:
+    return text.lower() if text else ""
+
+
+def _iter_string_values(node: Any) -> list[str]:
+    """Recursively collect string values (numerics/booleans excluded)."""
+    out: list[str] = []
+    if isinstance(node, bool):
+        return out
+    if isinstance(node, str):
+        out.append(node)
+    elif isinstance(node, dict):
+        for v in node.values():
+            out.extend(_iter_string_values(v))
+    elif isinstance(node, (list, tuple)):
+        for item in node:
+            out.extend(_iter_string_values(item))
+    return out
+
+
+def _iter_keys(node: Any) -> list[str]:
+    """Recursively collect dict keys."""
+    out: list[str] = []
+    if isinstance(node, dict):
+        for k, v in node.items():
+            out.append(str(k))
+            out.extend(_iter_keys(v))
+    elif isinstance(node, (list, tuple)):
+        for item in node:
+            out.extend(_iter_keys(item))
+    return out
+
+
+def _build_args_search_corpus(tool_args: dict[str, Any] | None) -> str:
+    """Lowercased keys + string values; numeric/boolean leaves excluded."""
+    if not tool_args:
+        return ""
+    keys = _iter_keys(tool_args)
+    strings = _iter_string_values(tool_args)
+    return " ".join(keys + strings).lower()
+
+
+def _mentions_drift(message: str | None, hints: tuple[str, ...]) -> bool:
+    if not message:
+        return False
+    target = message.lower()
+    return any(hint.lower() in target for hint in hints)
+
+
+def _args_mention_drift(
+    tool_args: dict[str, Any] | None,
+    hints: tuple[str, ...],
+) -> bool:
+    corpus = _build_args_search_corpus(tool_args)
+    if not corpus:
+        return False
+    return any(hint.lower() in corpus for hint in hints)
+
+
+def _new_field_names(pattern: DriftPattern) -> tuple[str, ...]:
+    """Field names introduced by the drift mutation (post-drift schema)."""
+    mutation = pattern.mutation
+    out: list[str] = []
+    rename = mutation.get("rename")
+    if isinstance(rename, dict):
+        out.extend(str(v) for v in rename.values())
+    new_fields = mutation.get("require_new_field")
+    if isinstance(new_fields, (list, tuple)):
+        out.extend(str(v) for v in new_fields)
+    change = mutation.get("change_type")
+    if isinstance(change, dict):
+        out.extend(str(v) for v in change.values())
+    return tuple(out)
+
+
+def _old_field_names(pattern: DriftPattern) -> tuple[str, ...]:
+    """Field names from the pre-drift schema."""
+    mutation = pattern.mutation
+    out: list[str] = []
+    rename = mutation.get("rename")
+    if isinstance(rename, dict):
+        out.extend(str(k) for k in rename)
+    removed = mutation.get("remove")
+    if isinstance(removed, (list, tuple)):
+        out.extend(str(v) for v in removed)
+    change = mutation.get("change_type")
+    if isinstance(change, dict):
+        out.extend(str(k) for k in change)
+    return tuple(out)
+
+
+def _uses_new_schema(
+    tool_args: dict[str, Any] | None,
+    pattern: DriftPattern,
+) -> bool:
+    if not tool_args:
+        return False
+    new_fields = _new_field_names(pattern)
+    if not new_fields:
+        return False
+    keys_lower = {k.lower() for k in _iter_keys(tool_args)}
+    return any(f.lower() in keys_lower for f in new_fields)
+
+
+def _uses_old_schema(
+    tool_args: dict[str, Any] | None,
+    pattern: DriftPattern,
+) -> bool:
+    if not tool_args:
+        return False
+    old_fields = _old_field_names(pattern)
+    if not old_fields:
+        return False
+    keys_lower = {k.lower() for k in _iter_keys(tool_args)}
+    return any(f.lower() in keys_lower for f in old_fields)
+
+
+def _has_3plus_old_schema_retries(
+    episode: Episode,
+    pattern: DriftPattern,
+    drift_turn: int,
+) -> bool:
+    """True iff >= 3 TOOL_CALLs after drift_turn use OLD schema."""
+    count = 0
+    for action, turn in zip(episode.actions, episode.action_turns, strict=True):
+        if turn <= drift_turn:
+            continue
+        if action.action_type != ActionType.TOOL_CALL:
+            continue
+        if _uses_old_schema(action.tool_args, pattern):
+            count += 1
+    return count >= 3
+
+
+# ---------------------------------------------------------------------------
+# R1 — Task Completion
+# ---------------------------------------------------------------------------
+
+
+def _parse_iso_hour(timestamp: str) -> int | None:
+    """Parse 'YYYY-MM-DDTHH:MM[:SS]' and return hour, or None on failure."""
+    if "T" not in timestamp:
+        return None
+    try:
+        time_part = timestamp.split("T", 1)[1]
+        return int(time_part[:2])
+    except (ValueError, IndexError):
+        return None
+
+
+def _hour_in_window(hour: int, window: str) -> bool:
+    win = _TIME_WINDOWS.get(window)
+    if win is None:
+        return True
+    lo, hi = win
+    if hi <= 24:
+        return lo <= hour < hi
+    return hour >= lo or hour < (hi - 24)
+
+
+def _check_airline_booking(
+    goal: GoalSpec,
+    vendor_states: dict[str, dict[str, Any]],
+) -> bool:
+    state = vendor_states.get("airline", {})
+    if not isinstance(state, dict):
+        return False
+    bookings = state.get("bookings", [])
+    if not isinstance(bookings, list) or not bookings:
+        return False
+    expected_from = goal.slots.get("from")
+    expected_to = goal.slots.get("to")
+    budget = goal.constraints.get("budget_inr")
+    window = goal.constraints.get("time_window")
+    for booking in bookings:
+        if not isinstance(booking, dict):
+            continue
+        if expected_from is not None and booking.get("from") != expected_from:
+            continue
+        if expected_to is not None and booking.get("to") != expected_to:
+            continue
+        if budget is not None:
+            total = booking.get("total")
+            if total is None or total > budget:
+                continue
+        if window is not None:
+            depart = booking.get("depart")
+            if not isinstance(depart, str):
+                continue
+            hour = _parse_iso_hour(depart)
+            if hour is None or not _hour_in_window(hour, str(window)):
+                continue
+        return True
+    return False
+
+
+def _check_cab_booking(
+    goal: GoalSpec,
+    vendor_states: dict[str, dict[str, Any]],
+) -> bool:
+    state = vendor_states.get("cab", {})
+    if not isinstance(state, dict):
+        return False
+    bookings = state.get("bookings", [])
+    if not isinstance(bookings, list) or not bookings:
+        return False
+    expected_pickup = goal.slots.get("pickup")
+    expected_drop = goal.slots.get("drop")
+    expected_when = goal.slots.get("when")
+    for booking in bookings:
+        if not isinstance(booking, dict):
+            continue
+        if expected_pickup is not None and booking.get("pickup") != expected_pickup:
+            continue
+        if expected_drop is not None and booking.get("drop") != expected_drop:
+            continue
+        if expected_when is not None and booking.get("pickup_time") != expected_when:
+            continue
+        return True
+    return False
+
+
+def _check_restaurant_order(
+    goal: GoalSpec,
+    vendor_states: dict[str, dict[str, Any]],
+) -> bool:
+    state = vendor_states.get("restaurant", {})
+    if not isinstance(state, dict):
+        return False
+    orders = state.get("orders", [])
+    if not isinstance(orders, list) or not orders:
+        return False
+    budget = goal.constraints.get("budget_inr")
+    dietary = goal.constraints.get("dietary")
+    for order in orders:
+        if not isinstance(order, dict):
+            continue
+        if budget is not None:
+            total = order.get("total")
+            if total is None or total > budget:
+                continue
+        if dietary is not None:
+            items = order.get("items", [])
+            if dietary in {"veg", "veg_only"} and not all(
+                isinstance(it, dict) and it.get("veg") is True for it in items
+            ):
+                continue
+        return True
+    return False
+
+
+def _check_hotel_booking(
+    goal: GoalSpec,
+    vendor_states: dict[str, dict[str, Any]],
+) -> bool:
+    state = vendor_states.get("hotel", {})
+    if not isinstance(state, dict):
+        return False
+    bookings = state.get("bookings", [])
+    if not isinstance(bookings, list) or not bookings:
+        return False
+    expected_city = goal.slots.get("city")
+    expected_in = goal.slots.get("checkin")
+    expected_out = goal.slots.get("checkout")
+    expected_room = goal.slots.get("room_type")
+    for booking in bookings:
+        if not isinstance(booking, dict):
+            continue
+        if expected_city is not None and booking.get("city") != expected_city:
+            continue
+        if expected_in is not None and booking.get("checkin") != expected_in:
+            continue
+        if expected_out is not None and booking.get("checkout") != expected_out:
+            continue
+        if expected_room is not None and booking.get("room_type") != expected_room:
+            continue
+        return True
+    return False
+
+
+def task_completion(episode: Episode) -> float:
+    """R1: 1.0 iff terminated by SUBMIT and per-domain success predicate holds."""
+    if episode.terminated_by != "SUBMIT":
+        return 0.0
+    domain = episode.goal.domain
+    final = episode.vendor_states_final
+    if domain == "airline":
+        ok = _check_airline_booking(episode.goal, final)
+    elif domain == "cab":
+        ok = _check_cab_booking(episode.goal, final)
+    elif domain == "restaurant":
+        ok = _check_restaurant_order(episode.goal, final)
+    elif domain == "hotel":
+        ok = _check_hotel_booking(episode.goal, final)
+    else:
+        ok = False
+    return 1.0 if ok else 0.0
+
+
+def _r1_breakdown(episode: Episode) -> dict[str, Any]:
+    domain = episode.goal.domain
+    if domain not in {"airline", "cab", "restaurant", "hotel"}:
+        return {
+            "domain": domain,
+            "success_predicate": "unknown_domain",
+            "matched_slots": {},
+            "missing_slots": [],
+        }
+    return {
+        "domain": domain,
+        "success_predicate": f"{domain}_booking_match",
+        "matched_slots": dict(episode.goal.slots),
+        "missing_slots": [],
+    }
+
+
+# ---------------------------------------------------------------------------
+# R2 — Drift Detection
+# ---------------------------------------------------------------------------
+
+
+def _drift_detection_with_breakdown(
+    episode: Episode,
+) -> tuple[float, dict[str, Any]]:
+    breakdown: dict[str, Any] = {
+        "stage": int(episode.stage),
+        "drifts_total": len(episode.drift_log),
+        "drifts_detected": 0,
+        "per_drift": [],
+        "three_plus_retries": False,
+    }
+    if episode.stage == 1 or len(episode.drift_log) == 0:
+        if episode.stage in (2, 3) and len(episode.drift_log) == 0:
+            breakdown["stage2_3_no_drift"] = True
+        return 0.5, breakdown
+
+    score = 1.0
+    detected = 0
+    any_old_schema_retries = False
+
+    for drift in episode.drift_log:
+        pattern = _resolve_pattern(episode, drift)
+        hints = _validate_hints(pattern, episode)
+        window_turns = [drift.turn, drift.turn + 1, drift.turn + 2]
+        actions_in_window = [
+            (a, t)
+            for a, t in zip(episode.actions, episode.action_turns, strict=True)
+            if t in window_turns
+        ]
+        hit_speech = False
+        hit_args = False
+        hit_adapt = False
+        for action, _turn in actions_in_window:
+            if (
+                action.action_type in {ActionType.SPEAK, ActionType.CLARIFY}
+                and _mentions_drift(action.message, hints)
+            ):
+                hit_speech = True
+            if action.action_type == ActionType.TOOL_CALL:
+                if _args_mention_drift(action.tool_args, hints):
+                    hit_args = True
+                if _uses_new_schema(action.tool_args, pattern):
+                    hit_adapt = True
+
+        breakdown["per_drift"].append({
+            "drift_id": drift.pattern_id,
+            "hit_by_speech": hit_speech,
+            "hit_by_args_hint": hit_args,
+            "hit_by_adaptation": hit_adapt,
+            "window_turns": list(window_turns),
+        })
+
+        if hit_speech or hit_args or hit_adapt:
+            detected += 1
+        else:
+            score = 0.0
+
+        if _has_3plus_old_schema_retries(episode, pattern, drift.turn):
+            any_old_schema_retries = True
+
+    breakdown["drifts_detected"] = detected
+    breakdown["three_plus_retries"] = any_old_schema_retries
+    if any_old_schema_retries:
+        score = 0.0
+    return score, breakdown
+
+
+def drift_detection(episode: Episode) -> float:
+    """R2: stage-1/no-drift → 0.5; per-drift any-branch hit → 1.0; one miss → 0.0."""
+    score, _ = _drift_detection_with_breakdown(episode)
+    return score
+
+
+# ---------------------------------------------------------------------------
+# R3 — Constraint Adherence
+# ---------------------------------------------------------------------------
+
+
+_KNOWN_CONSTRAINT_KEYS: frozenset[str] = frozenset(
+    {
+        "budget_inr",
+        "time_window",
+        "dietary",
+        "passenger_count",
+        "pickup",
+        "seat_type",
+        "checkin",
+        "checkout",
+        "room_type",
+    },
+)
+
+
+def _final_booking(episode: Episode) -> dict[str, Any] | None:
+    """Return the most recent booking/order from vendor_states_final."""
+    domain = episode.goal.domain
+    state = episode.vendor_states_final.get(domain, {})
+    if not isinstance(state, dict):
+        return None
+    items = (
+        state.get("orders", []) if domain == "restaurant" else state.get("bookings", [])
+    )
+    if not isinstance(items, list) or not items:
+        return None
+    last = items[-1]
+    return last if isinstance(last, dict) else None
+
+
+def _check_constraint(
+    key: str,
+    expected: Any,
+    booking: dict[str, Any] | None,
+) -> bool:
+    if booking is None:
+        return False
+    if key == "budget_inr":
+        total = booking.get("total")
+        if total is None:
+            return False
+        try:
+            return float(total) <= float(expected)
+        except (TypeError, ValueError):
+            return False
+    if key == "time_window":
+        depart = booking.get("depart") or booking.get("pickup_time")
+        if not isinstance(depart, str):
+            return False
+        hour = _parse_iso_hour(depart)
+        if hour is None:
+            return False
+        return _hour_in_window(hour, str(expected))
+    if key == "dietary":
+        items = booking.get("items", [])
+        if not isinstance(items, list):
+            return False
+        if expected in {"veg", "veg_only"}:
+            return all(
+                isinstance(it, dict) and it.get("veg") is True for it in items
+            )
+        return True
+    if key == "passenger_count":
+        return bool(booking.get("passenger_count") == expected)
+    if key == "pickup":
+        return bool(booking.get("pickup") == expected)
+    if key == "seat_type":
+        return bool(booking.get("seat_type") == expected)
+    if key == "checkin":
+        return bool(booking.get("checkin") == expected)
+    if key == "checkout":
+        return bool(booking.get("checkout") == expected)
+    if key == "room_type":
+        return bool(booking.get("room_type") == expected)
+    return False
+
+
+def _r3_with_breakdown(episode: Episode) -> tuple[float, dict[str, Any]]:
+    constraints = episode.goal.constraints
+    if not constraints:
+        return 1.0, {
+            "total_constraints": 0,
+            "satisfied_constraints": 0,
+            "unknown_constraints": [],
+            "failures": [],
+        }
+    booking = _final_booking(episode)
+    satisfied = 0
+    unknown: list[str] = []
+    failures: list[dict[str, Any]] = []
+    for key, expected in constraints.items():
+        if key not in _KNOWN_CONSTRAINT_KEYS:
+            unknown.append(key)
+            satisfied += 1
+            continue
+        if _check_constraint(key, expected, booking):
+            satisfied += 1
+        else:
+            actual = booking.get(key) if booking else None
+            failures.append({"key": key, "expected": expected, "actual": actual})
+    total = len(constraints)
+    return satisfied / total, {
+        "total_constraints": total,
+        "satisfied_constraints": satisfied,
+        "unknown_constraints": unknown,
+        "failures": failures,
+    }
+
+
+def constraint_adherence(episode: Episode) -> float:
+    """R3: fraction of goal.constraints satisfied by the final booking."""
+    score, _ = _r3_with_breakdown(episode)
+    return score
+
+
+# ---------------------------------------------------------------------------
+# R4 — Format Compliance
+# ---------------------------------------------------------------------------
+
+
+def _is_valid_json(value: Any) -> bool:
+    try:
+        json.dumps(value)
+    except (TypeError, ValueError):
+        return False
+    return True
+
+
+def _has_devanagari(text: str) -> bool:
+    return any("ऀ" <= c <= "ॿ" for c in text)
+
+
+def _has_tamil(text: str) -> bool:
+    return any("஀" <= c <= "௿" for c in text)
+
+
+def _has_kannada(text: str) -> bool:
+    return any("ಀ" <= c <= "೿" for c in text)
+
+
+def _has_indic(text: str) -> bool:
+    return _has_devanagari(text) or _has_tamil(text) or _has_kannada(text)
+
+
+def _language_mismatch(message: str, goal_language: str) -> bool:
+    """Asymmetric heuristic per rewards.md §3.5; permissive for ta/kn/hinglish.
+
+    - "en"      : mismatch iff message contains any Indic script.
+    - "hi"      : mismatch iff message contains no Devanagari.
+    - others    : Latin or local script accepted (transliteration is common).
+    """
+    if not message:
+        return False
+    if goal_language == "en":
+        return _has_indic(message)
+    if goal_language == "hi":
+        return not _has_devanagari(message)
+    return False
+
+
+def _r4_with_breakdown(episode: Episode) -> tuple[float, dict[str, Any]]:
+    score = 1.0
+    deductions: list[dict[str, Any]] = []
+    for action, turn in zip(episode.actions, episode.action_turns, strict=True):
+        if action.action_type == ActionType.TOOL_CALL:
+            if not _is_valid_json(action.tool_args):
+                score -= 0.20
+                deductions.append({"turn": turn, "reason": "invalid_json", "amount": 0.20})
+            if action.tool_name not in AVAILABLE_TOOL_REGISTRY:
+                score -= 0.10
+                deductions.append({"turn": turn, "reason": "unknown_tool", "amount": 0.10})
+            if action.rationale is None or len(action.rationale.strip()) == 0:
+                score -= 0.05
+                deductions.append({
+                    "turn": turn,
+                    "reason": "missing_rationale",
+                    "amount": 0.05,
+                })
+        if action.action_type in {ActionType.SPEAK, ActionType.CLARIFY}:
+            msg = action.message or ""
+            if _language_mismatch(msg, episode.goal.language):
+                score -= 0.10
+                deductions.append({
+                    "turn": turn,
+                    "reason": "language_mismatch",
+                    "amount": 0.10,
+                })
+    score = max(0.0, min(1.0, score))
+    return score, {"deductions": deductions}
+
+
+def format_compliance(episode: Episode) -> float:
+    """R4: deductive from 1.0; clamped to [0, 1]."""
+    score, _ = _r4_with_breakdown(episode)
+    return score
+
+
+# ---------------------------------------------------------------------------
+# R5 — Anti-Hack Penalty
+# ---------------------------------------------------------------------------
+
+
+def _build_whitelist(tool_results: tuple[ToolResult, ...]) -> set[str]:
+    """Recursive walk: every key + every primitive leaf, lowercased."""
+    seen: set[str] = set()
+
+    def walk(node: Any) -> None:
+        if isinstance(node, bool):
+            seen.add(str(node).lower())
+            return
+        if isinstance(node, dict):
+            for k, v in node.items():
+                seen.add(str(k).lower())
+                walk(v)
+        elif isinstance(node, (list, tuple)):
+            for item in node:
+                walk(item)
+        elif isinstance(node, (str, int, float)):
+            seen.add(str(node).lower())
+
+    for tr in tool_results:
+        walk(tr.response)
+    return seen
+
+
+def _extract_field_tokens(text: str | None) -> list[str]:
+    """Return lowercased snake_case identifier tokens (>=1 underscore)."""
+    if not text:
+        return []
+    return _SNAKE_FIELD_RE.findall(text.lower())
+
+
+def _hallucinated_offenses(
+    episode: Episode,
+    whitelist: set[str],
+) -> list[tuple[int, str]]:
+    """(turn, token) pairs where agent referenced a snake_case field not in whitelist.
+
+    Scans natural-language surfaces only (`message`, `rationale`). Tool-call
+    `tool_args` keys are the agent's own request payload — they are policed by
+    R4 (unknown_tool / invalid_json) and the protected-write check, not as
+    hallucinated field references.
+    """
+    offenses: list[tuple[int, str]] = []
+    for action, turn in zip(episode.actions, episode.action_turns, strict=True):
+        candidates: list[str] = []
+        candidates.extend(_extract_field_tokens(action.message))
+        candidates.extend(_extract_field_tokens(action.rationale))
+        for token in candidates:
+            if token not in whitelist:
+                offenses.append((turn, token))
+    return offenses
+
+
+def _canonical_args(tool_args: dict[str, Any] | None) -> str:
+    if tool_args is None:
+        return "null"
+    try:
+        return json.dumps(tool_args, sort_keys=True, separators=(",", ":"))
+    except (TypeError, ValueError):
+        try:
+            return repr(sorted(tool_args.items()))
+        except TypeError:
+            return repr(tool_args)
+
+
+def _max_repeated_tool_calls(episode: Episode) -> int:
+    """Maximum repetition count of any (tool_name, normalised_args) pair."""
+    counts: dict[tuple[str | None, str], int] = {}
+    for action in episode.actions:
+        if action.action_type != ActionType.TOOL_CALL:
+            continue
+        key = (action.tool_name, _canonical_args(action.tool_args))
+        counts[key] = counts.get(key, 0) + 1
+    return max(counts.values()) if counts else 0
+
+
+def _count_actions(episode: Episode, action_type: ActionType) -> int:
+    return sum(1 for a in episode.actions if a.action_type == action_type)
+
+
+def _has_unsubstantiated_drift_claim(
+    episode: Episode,
+) -> tuple[bool, int | None]:
+    """SPEAK/CLARIFY mentions 'drift' before any prior failure or drift_log entry."""
+    for action, turn in zip(episode.actions, episode.action_turns, strict=True):
+        if action.action_type not in {ActionType.SPEAK, ActionType.CLARIFY}:
+            continue
+        if "drift" not in _safe_lower(action.message):
+            continue
+        prior_failure = any(
+            tr.status in _FAILURE_STATUSES and tr_turn <= turn
+            for tr, tr_turn in zip(
+                episode.tool_results, episode.tool_result_turns, strict=True,
+            )
+        )
+        if prior_failure:
+            continue
+        prior_drift = any(d.turn <= turn for d in episode.drift_log)
+        if prior_drift:
+            continue
+        return True, turn
+    return False, None
+
+
+def _is_protected_tool(tool_name: str | None) -> bool:
+    if not tool_name:
+        return False
+    return tool_name.startswith("__") and tool_name.endswith("__")
+
+
+def _has_protected_write(episode: Episode) -> tuple[bool, int | None]:
+    for action, turn in zip(episode.actions, episode.action_turns, strict=True):
+        if action.action_type != ActionType.TOOL_CALL:
+            continue
+        if _is_protected_tool(action.tool_name):
+            return True, turn
+        if action.tool_args:
+            for key in action.tool_args:
+                if key in _RESERVED_KEYS:
+                    return True, turn
+    return False, None
+
+
+def _r5_with_breakdown(episode: Episode) -> tuple[float, dict[str, Any]]:
+    penalty = 0.0
+    offenses: list[dict[str, Any]] = []
+
+    whitelist = _build_whitelist(episode.tool_results)
+    hallucinations = _hallucinated_offenses(episode, whitelist)
+    if hallucinations:
+        penalty -= 1.0
+        first_turn, first_token = hallucinations[0]
+        offenses.append({
+            "code": "hallucinated_field",
+            "turn": first_turn,
+            "evidence": first_token,
+        })
+
+    repeats = _max_repeated_tool_calls(episode)
+    if repeats > 3:
+        penalty -= 0.5
+        offenses.append({
+            "code": "repeated_tool_calls",
+            "turn": None,
+            "evidence": f"max_repetition={repeats}",
+        })
+
+    probe_count = _count_actions(episode, ActionType.PROBE_SCHEMA)
+    if probe_count >= 3:
+        penalty -= 0.5
+        offenses.append({
+            "code": "probe_schema_abuse",
+            "turn": None,
+            "evidence": f"probe_count={probe_count}",
+        })
+
+    bare, bare_turn = _has_unsubstantiated_drift_claim(episode)
+    if bare:
+        penalty -= 0.3
+        offenses.append({
+            "code": "bare_drift_assertion",
+            "turn": bare_turn,
+            "evidence": "speak mentions drift without prior failure",
+        })
+
+    protected, protected_turn = _has_protected_write(episode)
+    if protected:
+        penalty -= 0.2
+        offenses.append({
+            "code": "protected_write",
+            "turn": protected_turn,
+            "evidence": "reserved key or protected tool",
+        })
+
+    penalty = max(-1.0, penalty)
+    return penalty, {"offenses": offenses}
+
+
+def anti_hack_penalty(episode: Episode) -> float:
+    """R5: additive penalties, clamped to [-1.0, 0.0]."""
+    score, _ = _r5_with_breakdown(episode)
+    return score
+
+
+# ---------------------------------------------------------------------------
+# Combination helpers
+# ---------------------------------------------------------------------------
+
+
+def combine_quality(
+    r1: float,
+    r2: float,
+    r3: float,
+    r4: float,
+    r5: float,
+) -> float:
+    """Weighted sum (0.50/0.20/0.15/0.10/0.05). Does not clamp or round."""
+    return 0.50 * r1 + 0.20 * r2 + 0.15 * r3 + 0.10 * r4 + 0.05 * min(r5, 0.0)
+
+
+def brier_penalty(confidence: float | None, r1: float) -> float:
+    """min((conf - r1)^2, 0.5) when confidence given; else 0.0."""
+    if confidence is None:
+        return 0.0
+    raw = (confidence - r1) ** 2
+    return raw if raw <= 0.5 else 0.5
+
+
+def apply_uncertain_floor(
+    reward: float,
+    r1: float,
+    confidence: float | None,
+) -> float:
+    """Floor at 0.3 iff r1==0, confidence is not None, confidence < 0.3."""
+    if r1 == 0.0 and confidence is not None and confidence < 0.3:
+        return max(reward, 0.3)
+    return reward
+
+
+def final_reward(
+    quality: float,
+    brier: float,
+    r1: float,
+    confidence: float | None,
+) -> float:
+    """multiply -> floor -> clamp [0,1] -> round 3dp."""
+    reward = quality * (1.0 - brier)
+    reward = apply_uncertain_floor(reward, r1, confidence)
+    reward = max(0.0, min(1.0, reward))
+    return round(reward, 3)
+
+
+# ---------------------------------------------------------------------------
+# compute_rewards orchestration
+# ---------------------------------------------------------------------------
+
+
+def _validate_episode_structure(episode: Episode) -> None:
+    if episode.goal is None:
+        raise RewardComputationError("episode.goal is None", episode.episode_id)
+    if episode.terminated_by is None:
+        raise RewardComputationError("episode not terminated", episode.episode_id)
+    if episode.terminated_by not in _VALID_TERMINATIONS:
+        raise RewardComputationError(
+            f"episode not terminated (invalid terminated_by={episode.terminated_by!r})",
+            episode.episode_id,
+        )
+    for drift in episode.drift_log:
+        if drift.drift_type not in _VALID_DRIFT_TYPES:
+            raise RewardComputationError(
+                f"unknown drift_type: {drift.drift_type}",
+                episode.episode_id,
+            )
+        if (
+            drift.pattern_id not in episode.drift_pattern_overrides
+            and drift.pattern_id not in _PATTERNS_BY_ID
+        ):
+            raise RewardComputationError(
+                f"unknown pattern_id: {drift.pattern_id}",
+                episode.episode_id,
+            )
+    n_tool_calls = sum(
+        1 for a in episode.actions if a.action_type == ActionType.TOOL_CALL
+    )
+    if n_tool_calls != len(episode.tool_results):
+        raise RewardComputationError(
+            "action/tool_result count mismatch",
+            episode.episode_id,
+        )
+
+
+def _extract_confidence(episode: Episode) -> tuple[float | None, bool]:
+    """Return (raw_confidence, clamped_flag). Raises on non-finite."""
+    if episode.terminated_by != "SUBMIT":
+        return None, False
+    submit_conf: float | None = None
+    for action in reversed(episode.actions):
+        if action.action_type == ActionType.SUBMIT:
+            submit_conf = action.confidence
+            break
+    if submit_conf is None:
+        return None, False
+    if not _is_finite(float(submit_conf)):
+        raise RewardComputationError(
+            "non-finite value in reward computation",
+            episode.episode_id,
+        )
+    if submit_conf < 0.0 or submit_conf > 1.0:
+        return submit_conf, True
+    return submit_conf, False
+
+
+def compute_rewards(episode: Episode) -> Rewards:
+    """Convert a terminated Episode into a frozen Rewards record."""
+    _validate_episode_structure(episode)
+
+    raw_confidence, clamped = _extract_confidence(episode)
+    confidence_for_brier = raw_confidence
+    if clamped and raw_confidence is not None:
+        confidence_for_brier = max(0.0, min(1.0, raw_confidence))
+
+    r1 = task_completion(episode)
+    r2, r2_breakdown = _drift_detection_with_breakdown(episode)
+    r3, r3_breakdown = _r3_with_breakdown(episode)
+    r4, r4_breakdown = _r4_with_breakdown(episode)
+    r5, r5_breakdown = _r5_with_breakdown(episode)
+
+    if not (
+        _is_finite(r1)
+        and _is_finite(r2)
+        and _is_finite(r3)
+        and _is_finite(r4)
+        and _is_finite(r5)
+    ):
+        raise RewardComputationError(
+            "non-finite value in reward computation",
+            episode.episode_id,
+        )
+
+    quality = combine_quality(r1, r2, r3, r4, r5)
+    brier = brier_penalty(confidence_for_brier, r1)
+    if not (_is_finite(quality) and _is_finite(brier)):
+        raise RewardComputationError(
+            "non-finite value in reward computation",
+            episode.episode_id,
+        )
+
+    pre_floor = quality * (1.0 - brier)
+    floored = apply_uncertain_floor(pre_floor, r1, confidence_for_brier)
+    floor_applied = floored != pre_floor
+    reward_clamped = max(0.0, min(1.0, floored))
+    reward = round(reward_clamped, 3)
+
+    breakdown: dict[str, Any] = {
+        "r1": _r1_breakdown(episode),
+        "r2": r2_breakdown,
+        "r3": r3_breakdown,
+        "r4": r4_breakdown,
+        "anti_hack": r5_breakdown,
+        "combination": {
+            "quality_raw": quality,
+            "brier": brier,
+            "uncertain_floor_applied": floor_applied,
+            "confidence_clamped": clamped,
+            "confidence_missing": (
+                episode.terminated_by == "SUBMIT" and raw_confidence is None
+            ),
+        },
+    }
+
+    return Rewards(
+        r1=r1,
+        r2=r2,
+        r3=r3,
+        r4=r4,
+        r5=r5,
+        quality=quality,
+        brier=brier,
+        reward=reward,
+        confidence=raw_confidence,
+        floor_applied=floor_applied,
+        breakdown=breakdown,
+    )

cells/step_09_audio.md

@@ -0,0 +1,6 @@
+# Cell 09 — Audio pipeline
+
+Kokoro-82M text-to-speech and faster-whisper-small automatic-speech-recognition
+wrappers that sit at the env boundary. Per `docs/modules/audio.md`, both
+engines are process-wide singletons with lazy dep loading and an LRU cache on
+the TTS path; the training loop never imports this cell (`§6.3`).

cells/step_09_audio.py

@@ -0,0 +1,944 @@
+"""Cell 09 — Audio pipeline (Kokoro-82M TTS + faster-whisper-small ASR).
+
+Implements docs/modules/audio.md: TTS and ASR engines exposed at the env
+boundary. Training never imports this module (docs/modules/audio.md §6.3).
+Heavy deps (``kokoro``, ``faster_whisper``, ``torchaudio``, ``soundfile``)
+are loaded lazily inside ``_load_*`` helpers so this cell imports cleanly
+in environments where those optional packages are absent, and so tests can
+monkeypatch the loaders to return fakes without ever touching the network.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import logging
+import math
+import struct
+import threading
+import time
+import unicodedata
+import wave
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from typing import Any, Literal, cast
+
+import numpy as np
+from cachetools import LRUCache
+
+logger = logging.getLogger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Public literal types (audio.md §2.1, §2.2)
+# ---------------------------------------------------------------------------
+
+LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"]
+VoicePack = Literal[
+    "hi_female_1",
+    "hi_male_1",
+    "ta_female_1",
+    "kn_male_1",
+    "en_indian_female_1",
+]
+
+_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"})
+_VOICE_PACKS_SET: frozenset[str] = frozenset(
+    {
+        "hi_female_1",
+        "hi_male_1",
+        "ta_female_1",
+        "kn_male_1",
+        "en_indian_female_1",
+    }
+)
+
+
+# ---------------------------------------------------------------------------
+# Errors (audio.md §2.3)
+# ---------------------------------------------------------------------------
+
+
+class AudioError(Exception):
+    """Base class for all audio-module errors."""
+
+
+class ModelLoadError(AudioError):
+    """Raised when Kokoro or faster-whisper cannot be instantiated."""
+
+
+class UnsupportedLanguageError(AudioError):
+    """Raised when a non-registered language code is passed to synthesize()."""
+
+
+class UnsupportedVoicePackError(AudioError):
+    """Raised when a voice pack is not in VOICE_PACKS[lang].allowed."""
+
+
+class AudioDecodeError(AudioError):
+    """Raised when transcribe() cannot decode the input bytes."""
+
+
+class AudioTooLongError(AudioError):
+    """Raised when transcribe() receives audio longer than max_duration_s in strict mode."""
+
+
+class TTSOutOfMemoryError(AudioError):
+    """Raised when TTS synthesis exhausts memory mid-call."""
+
+
+# ---------------------------------------------------------------------------
+# Data records (audio.md §2.1, §2.2, §2.2a, §4.1, §4.2)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class VoicePackMapping:
+    """Per-language default + allowed voice packs. audio.md §4.3."""
+
+    language: LanguageCode
+    default: VoicePack
+    allowed: tuple[VoicePack, ...]
+
+
+VOICE_PACKS: dict[LanguageCode, VoicePackMapping] = {
+    "hi": VoicePackMapping(
+        language="hi",
+        default="hi_female_1",
+        allowed=("hi_female_1", "hi_male_1"),
+    ),
+    "ta": VoicePackMapping(
+        language="ta",
+        default="ta_female_1",
+        allowed=("ta_female_1",),
+    ),
+    "kn": VoicePackMapping(
+        language="kn",
+        default="kn_male_1",
+        allowed=("kn_male_1",),
+    ),
+    "en": VoicePackMapping(
+        language="en",
+        default="en_indian_female_1",
+        allowed=("en_indian_female_1",),
+    ),
+    "hinglish": VoicePackMapping(
+        language="hinglish",
+        default="en_indian_female_1",
+        allowed=("en_indian_female_1", "hi_female_1"),
+    ),
+}
+
+
+@dataclass(frozen=True)
+class TranscriptResult:
+    """ASR output surfaced to the env observation builder. audio.md §4.1."""
+
+    text: str
+    language_detected: LanguageCode | Literal["unknown"]
+    confidence: float
+    duration_s: float
+
+
+@dataclass(frozen=True)
+class AudioTrace:
+    """Per-call diagnostic record emitted via the configured trace sink.
+
+    audio.md §2.2a, §3.8.
+    """
+
+    op: Literal["synthesize", "transcribe"]
+    input_hash: str
+    language: str
+    duration_s: float
+    latency_ms: int
+    confidence: float | None
+    cache_hit: bool
+    degraded: bool
+    ts_ist: str
+
+
+TraceSink = Callable[[AudioTrace], None]
+
+
+# ---------------------------------------------------------------------------
+# Lazy dep loaders — patched by tests to inject fakes.
+# ---------------------------------------------------------------------------
+
+
+def _load_kokoro() -> Any:
+    """Return the ``kokoro`` module. Patched in tests."""
+
+    import kokoro
+
+    return kokoro
+
+
+def _load_faster_whisper() -> Any:
+    """Return the ``faster_whisper`` module. Patched in tests."""
+
+    import faster_whisper
+
+    return faster_whisper
+
+
+def _load_torchaudio_functional() -> Any:
+    """Return ``torchaudio.functional``. Patched in tests."""
+
+    import torchaudio.functional as F
+
+    return F
+
+
+def _load_torchaudio() -> Any:
+    """Return the top-level ``torchaudio`` module. Patched in tests."""
+
+    import torchaudio
+
+    return torchaudio
+
+
+def _load_soundfile() -> Any:
+    """Return the ``soundfile`` module. Patched in tests."""
+
+    import soundfile
+
+    return soundfile
+
+
+def _load_torch() -> Any:
+    """Return the ``torch`` module. Patched in tests."""
+
+    import torch
+
+    return torch
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+_IST_TZ = timezone(timedelta(hours=5, minutes=30))
+
+
+def _ts_ist_now() -> str:
+    return datetime.now(tz=_IST_TZ).isoformat(timespec="milliseconds")
+
+
+def _input_hash(payload: bytes) -> str:
+    return hashlib.blake2b(payload, digest_size=16).hexdigest()
+
+
+def _logprob_to_confidence(avg_logprob: float) -> float:
+    """Map faster-whisper ``avg_logprob`` into [0, 1] per audio.md §3.5."""
+
+    clamped = max(-1.5, min(0.0, float(avg_logprob)))
+    return round(math.exp(clamped), 3)
+
+
+def _riff_header_sample_rate(audio_bytes: bytes) -> int | None:
+    """Return the sample-rate field from a RIFF header, or None if not RIFF."""
+
+    if len(audio_bytes) < 28:
+        return None
+    if audio_bytes[0:4] != b"RIFF" or audio_bytes[8:12] != b"WAVE":
+        return None
+    return int(struct.unpack_from("<I", audio_bytes, 24)[0])
+
+
+def _pcm16_silence_wav(duration_s: float, sample_rate_hz: int = 16000) -> bytes:
+    """Build a 16-bit mono PCM WAV of pure silence for warmup / fallback."""
+
+    n_samples = max(1, int(duration_s * sample_rate_hz))
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sample_rate_hz)
+        w.writeframes(b"\x00\x00" * n_samples)
+    return buf.getvalue()
+
+
+def _np_to_wav_bytes(pcm: np.ndarray, sample_rate_hz: int) -> bytes:
+    """Encode a float32 mono numpy array as 16-bit PCM RIFF WAV bytes.
+
+    Used when torchaudio is unavailable or mocked — the fallback path
+    produces the same byte-level contract (RIFF header + 16 kHz mono 16-bit).
+    """
+
+    if pcm.dtype != np.int16:
+        clipped = np.clip(pcm.astype(np.float32), -1.0, 1.0)
+        pcm_i16 = (clipped * 32767.0).astype(np.int16)
+    else:
+        pcm_i16 = pcm
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(sample_rate_hz)
+        w.writeframes(pcm_i16.tobytes())
+    return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# TTS
+# ---------------------------------------------------------------------------
+
+
+_TTS_CACHE_MAX_BYTES: int = 64 * 1024 * 1024
+_TTS_CACHE_MAX_ENTRIES: int = 256
+
+
+def _available_voice_packs(kokoro_module: Any) -> set[str]:
+    """Probe the installed Kokoro bundle for shipped voice-pack names.
+
+    Looks for ``AVAILABLE_VOICES``, ``list_voices()``, or ``VOICES``. A fresh
+    install typically exposes at least one of these. If none is present we
+    fall back to the full canonical set (best-effort; runtime per-call
+    fallback in ``_resolve_voice_pack`` still protects against missing packs).
+    """
+
+    candidates: set[str] = set()
+    for attr in ("AVAILABLE_VOICES", "VOICES"):
+        value = getattr(kokoro_module, attr, None)
+        if isinstance(value, (list, tuple, set, frozenset)):
+            candidates.update(str(v) for v in value)
+    list_voices = getattr(kokoro_module, "list_voices", None)
+    if callable(list_voices):
+        try:
+            value = list_voices()
+            if isinstance(value, (list, tuple, set, frozenset)):
+                candidates.update(str(v) for v in value)
+        except Exception:  # pragma: no cover — defensive
+            pass
+    if not candidates:
+        return set(_VOICE_PACKS_SET)
+    return candidates
+
+
+_FALLBACK_CHAIN: dict[str, str] = {
+    "ta_female_1": "hi_female_1",
+    "kn_male_1": "hi_female_1",
+    "hi_male_1": "hi_female_1",
+    "hi_female_1": "en_indian_female_1",
+}
+
+
+class TTSEngine:
+    """Kokoro-82M wrapper. Constructed via ``get_tts_engine()``.
+
+    One instance per process. All heavy deps are imported lazily.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_id: str = "hexgrad/Kokoro-82M",
+        trace_sink: TraceSink | None = None,
+    ) -> None:
+        self._model_id = model_id
+        self._trace_sink = trace_sink
+        self._lock = threading.Lock()
+        self._cache: LRUCache[tuple[Any, ...], bytes] = LRUCache(
+            maxsize=_TTS_CACHE_MAX_BYTES, getsizeof=len
+        )
+        self._numpy_cache: LRUCache[tuple[Any, ...], np.ndarray] = LRUCache(
+            maxsize=_TTS_CACHE_MAX_BYTES, getsizeof=lambda a: int(a.nbytes)
+        )
+        self._fallback_used: dict[str, str] = {}
+        try:
+            kokoro = _load_kokoro()
+        except Exception as exc:  # network / disk / import failure
+            raise ModelLoadError(f"failed to load kokoro: {exc}") from exc
+        self._kokoro = kokoro
+        try:
+            pipeline_cls = getattr(kokoro, "KPipeline", None)
+            if pipeline_cls is None:
+                raise AttributeError("kokoro.KPipeline missing")
+            self._pipeline = pipeline_cls(model_id=model_id)
+        except Exception as exc:
+            raise ModelLoadError(f"failed to construct KPipeline: {exc}") from exc
+        self._available_packs = _available_voice_packs(kokoro)
+        self._verify_critical_packs()
+
+    def _verify_critical_packs(self) -> None:
+        if (
+            "en_indian_female_1" not in self._available_packs
+            and "hi_female_1" not in self._available_packs
+        ):
+            raise ModelLoadError("no usable voice pack for hi or en")
+
+    def _resolve_voice_pack(self, requested: VoicePack) -> tuple[VoicePack, bool, str | None]:
+        """Walk the fallback chain until an available pack is found.
+
+        Returns ``(resolved_pack, degraded, fallback_from)``.
+        """
+
+        current = requested
+        original = requested
+        degraded = False
+        fallback_from: str | None = None
+        visited: set[str] = set()
+        while current not in self._available_packs:
+            if current in visited:
+                break
+            visited.add(current)
+            successor = _FALLBACK_CHAIN.get(current)
+            if successor is None:
+                raise ModelLoadError(
+                    f"no usable voice pack; chain exhausted from {original!r}"
+                )
+            fallback_from = original
+            current = cast("VoicePack", successor)
+            degraded = True
+        if degraded:
+            self._fallback_used[original] = current
+        return current, degraded, fallback_from
+
+    def _emit_trace(self, trace: AudioTrace) -> None:
+        if self._trace_sink is None:
+            return
+        try:
+            self._trace_sink(trace)
+        except Exception:  # telemetry must never break production
+            logger.debug("trace sink raised; swallowed", exc_info=True)
+
+    def _render_pcm(self, text: str, voice_pack: VoicePack, seed: int) -> np.ndarray:
+        """Invoke Kokoro inside a forked RNG context and return 24 kHz float32 PCM."""
+
+        torch = _load_torch()
+        with torch.random.fork_rng(devices=[]):
+            torch.manual_seed(seed)
+            try:
+                result = self._pipeline(text, voice=voice_pack)
+            except MemoryError as exc:
+                raise TTSOutOfMemoryError(f"TTS OOM: {exc}") from exc
+            except RuntimeError as exc:
+                msg = str(exc).lower()
+                if "out of memory" in msg or "alloc" in msg:
+                    raise TTSOutOfMemoryError(f"TTS OOM: {exc}") from exc
+                raise
+        return _coerce_to_float32_mono(result)
+
+    def _resample_to_16k(self, pcm_24k: np.ndarray) -> np.ndarray:
+        """Downsample 24 kHz → 16 kHz via torchaudio.functional.resample."""
+
+        try:
+            F = _load_torchaudio_functional()
+        except Exception as exc:  # pragma: no cover — hard runtime failure
+            raise ModelLoadError(f"torchaudio.functional missing: {exc}") from exc
+        torch = _load_torch()
+        tensor = torch.from_numpy(pcm_24k.astype(np.float32)).unsqueeze(0)
+        resampled = F.resample(
+            tensor, orig_freq=24000, new_freq=16000, lowpass_filter_width=64
+        )
+        out = resampled.squeeze(0).cpu().numpy().astype(np.float32)
+        return cast("np.ndarray", out)
+
+    def _encode_wav(self, pcm_16k: np.ndarray, sample_rate_hz: int) -> bytes:
+        """Encode the 16 kHz float32 PCM into 16-bit mono RIFF WAV bytes."""
+
+        try:
+            torchaudio = _load_torchaudio()
+            torch = _load_torch()
+            tensor = torch.from_numpy(pcm_16k.astype(np.float32)).unsqueeze(0)
+            buf = io.BytesIO()
+            torchaudio.save(
+                buf,
+                tensor,
+                sample_rate=sample_rate_hz,
+                bits_per_sample=16,
+                format="wav",
+                encoding="PCM_S",
+            )
+            return buf.getvalue()
+        except Exception:
+            # Fall back to stdlib wave encoder so the byte contract still holds
+            # even when torchaudio is unavailable.
+            return _np_to_wav_bytes(pcm_16k, sample_rate_hz)
+
+    def synthesize(
+        self,
+        text: str,
+        language_code: LanguageCode,
+        voice_pack: VoicePack | None = None,
+        *,
+        seed: int = 0,
+        sample_rate_hz: int = 16000,
+    ) -> bytes:
+        """Return 16-bit PCM mono WAV bytes. audio.md §2.1, §4.4."""
+
+        if sample_rate_hz != 16000:
+            raise UnsupportedLanguageError(
+                f"sample_rate_hz={sample_rate_hz} unsupported; only 16000 allowed in v1"
+            )
+        if language_code not in _LANGUAGE_CODES:
+            raise UnsupportedLanguageError(f"language_code={language_code!r} unsupported")
+        mapping = VOICE_PACKS[language_code]
+        if voice_pack is None:
+            voice_pack = mapping.default
+        if voice_pack not in mapping.allowed:
+            raise UnsupportedVoicePackError(
+                f"voice_pack={voice_pack!r} not allowed for language={language_code!r}"
+            )
+        text_hash = _input_hash(text.encode("utf-8"))
+        cache_key = (text_hash, voice_pack, seed, sample_rate_hz, "bytes")
+        start = time.perf_counter()
+        with self._lock:
+            cached = self._cache.get(cache_key)
+        if cached is not None:
+            latency_ms = int((time.perf_counter() - start) * 1000)
+            duration_s = _wav_duration_s(cached)
+            self._emit_trace(
+                AudioTrace(
+                    op="synthesize",
+                    input_hash=text_hash,
+                    language=language_code,
+                    duration_s=duration_s,
+                    latency_ms=latency_ms,
+                    confidence=None,
+                    cache_hit=True,
+                    degraded=False,
+                    ts_ist=_ts_ist_now(),
+                )
+            )
+            return cached
+        resolved_pack, degraded, _ = self._resolve_voice_pack(voice_pack)
+        pcm_24k = self._render_pcm(text, resolved_pack, seed)
+        pcm_16k = self._resample_to_16k(pcm_24k)
+        wav_bytes = self._encode_wav(pcm_16k, sample_rate_hz)
+        with self._lock:
+            self._cache[cache_key] = wav_bytes
+        latency_ms = int((time.perf_counter() - start) * 1000)
+        duration_s = _wav_duration_s(wav_bytes)
+        self._emit_trace(
+            AudioTrace(
+                op="synthesize",
+                input_hash=text_hash,
+                language=language_code,
+                duration_s=duration_s,
+                latency_ms=latency_ms,
+                confidence=None,
+                cache_hit=False,
+                degraded=degraded,
+                ts_ist=_ts_ist_now(),
+            )
+        )
+        return wav_bytes
+
+    def synthesize_to_gradio(
+        self,
+        text: str,
+        language_hint: LanguageCode,
+        voice_pack: VoicePack | None = None,
+        *,
+        seed: int = 0,
+    ) -> tuple[int, np.ndarray]:
+        """Return ``(sample_rate, float32 mono ndarray)``. audio.md §2.1."""
+
+        if language_hint not in _LANGUAGE_CODES:
+            raise UnsupportedLanguageError(f"language_hint={language_hint!r} unsupported")
+        mapping = VOICE_PACKS[language_hint]
+        if voice_pack is None:
+            voice_pack = mapping.default
+        if voice_pack not in mapping.allowed:
+            raise UnsupportedVoicePackError(
+                f"voice_pack={voice_pack!r} not allowed for language={language_hint!r}"
+            )
+        text_hash = _input_hash(text.encode("utf-8"))
+        sample_rate_hz = 16000
+        cache_key = (text_hash, voice_pack, seed, sample_rate_hz, "numpy")
+        start = time.perf_counter()
+        with self._lock:
+            cached = self._numpy_cache.get(cache_key)
+        if cached is not None:
+            self._emit_trace(
+                AudioTrace(
+                    op="synthesize",
+                    input_hash=text_hash,
+                    language=language_hint,
+                    duration_s=float(len(cached)) / sample_rate_hz,
+                    latency_ms=int((time.perf_counter() - start) * 1000),
+                    confidence=None,
+                    cache_hit=True,
+                    degraded=False,
+                    ts_ist=_ts_ist_now(),
+                )
+            )
+            return sample_rate_hz, cached.copy()
+        resolved_pack, degraded, _ = self._resolve_voice_pack(voice_pack)
+        pcm_24k = self._render_pcm(text, resolved_pack, seed)
+        pcm_16k = self._resample_to_16k(pcm_24k)
+        with self._lock:
+            self._numpy_cache[cache_key] = pcm_16k
+        self._emit_trace(
+            AudioTrace(
+                op="synthesize",
+                input_hash=text_hash,
+                language=language_hint,
+                duration_s=float(len(pcm_16k)) / sample_rate_hz,
+                latency_ms=int((time.perf_counter() - start) * 1000),
+                confidence=None,
+                cache_hit=False,
+                degraded=degraded,
+                ts_ist=_ts_ist_now(),
+            )
+        )
+        return sample_rate_hz, pcm_16k.copy()
+
+    def warmup(self) -> None:
+        """Probe each voice pack; log WARN on missing Indic packs. audio.md §4.3.1."""
+
+        for lang, mapping in VOICE_PACKS.items():
+            for pack in mapping.allowed:
+                if pack not in self._available_packs:
+                    logger.warning(
+                        "voice pack %r missing from bundle (language=%s); will fall back at synth time",
+                        pack,
+                        lang,
+                    )
+        try:
+            self.synthesize("warmup", "en")
+        except Exception:  # pragma: no cover — warmup best-effort
+            logger.debug("warmup synthesize failed; continuing", exc_info=True)
+
+
+def _coerce_to_float32_mono(result: Any) -> np.ndarray:
+    """Turn whatever Kokoro returned into a 1-D float32 numpy array."""
+
+    torch = _load_torch()
+    if hasattr(result, "cpu") and hasattr(result, "numpy"):
+        arr = result.detach().cpu().numpy()
+    elif isinstance(result, tuple):
+        audio_like = result[0]
+        if hasattr(audio_like, "cpu") and hasattr(audio_like, "numpy"):
+            arr = audio_like.detach().cpu().numpy()
+        else:
+            arr = np.asarray(audio_like)
+    elif isinstance(result, np.ndarray):
+        arr = result
+    else:
+        try:
+            tensor = torch.as_tensor(result)
+            arr = tensor.detach().cpu().numpy()
+        except Exception as exc:  # pragma: no cover — defensive
+            raise TTSOutOfMemoryError(f"unexpected Kokoro return type: {type(result)!r}: {exc}") from exc
+    arr = np.asarray(arr, dtype=np.float32).reshape(-1)
+    return arr
+
+
+def _wav_duration_s(wav_bytes: bytes) -> float:
+    """Return the duration in seconds for a RIFF WAV payload (best-effort)."""
+
+    try:
+        with wave.open(io.BytesIO(wav_bytes), "rb") as w:
+            frames = w.getnframes()
+            rate = w.getframerate()
+            if rate <= 0:
+                return 0.0
+            return round(frames / rate, 3)
+    except Exception:
+        return 0.0
+
+
+# ---------------------------------------------------------------------------
+# ASR
+# ---------------------------------------------------------------------------
+
+
+def _map_language(code: str | None) -> LanguageCode | Literal["unknown"]:
+    if code in _LANGUAGE_CODES:
+        return cast("LanguageCode", code)
+    return "unknown"
+
+
+def _nfc(text: str) -> str:
+    return unicodedata.normalize("NFC", text).strip()
+
+
+class ASREngine:
+    """faster-whisper-small wrapper. Constructed via ``get_asr_engine()``.
+
+    audio.md §2.2. Heavy deps loaded lazily.
+    """
+
+    def __init__(
+        self,
+        *,
+        model_id: str = "Systran/faster-whisper-small",
+        compute_type: Literal["int8", "int8_float16"] = "int8",
+        trace_sink: TraceSink | None = None,
+    ) -> None:
+        self._model_id = model_id
+        self._compute_type = compute_type
+        self._trace_sink = trace_sink
+        self._lock = threading.Lock()
+        try:
+            fw = _load_faster_whisper()
+        except Exception as exc:
+            raise ModelLoadError(f"failed to load faster_whisper: {exc}") from exc
+        model_cls = getattr(fw, "WhisperModel", None)
+        if model_cls is None:
+            raise ModelLoadError("faster_whisper.WhisperModel missing")
+        try:
+            self._model = model_cls(model_id, compute_type=compute_type, device="cpu")
+        except Exception as exc:
+            raise ModelLoadError(f"failed to construct WhisperModel: {exc}") from exc
+
+    def _emit_trace(self, trace: AudioTrace) -> None:
+        if self._trace_sink is None:
+            return
+        try:
+            self._trace_sink(trace)
+        except Exception:
+            logger.debug("trace sink raised; swallowed", exc_info=True)
+
+    def transcribe(
+        self,
+        audio_bytes: bytes,
+        language_hint: LanguageCode | None,
+        *,
+        beam_size: int = 1,
+        vad_filter: bool = True,
+        max_duration_s: float = 30.0,
+    ) -> TranscriptResult:
+        """Decode WAV/PCM bytes. audio.md §2.2, §3.5, §4.4."""
+
+        start = time.perf_counter()
+        pcm, clip_duration = self._decode_input(audio_bytes)
+        if clip_duration > max_duration_s:
+            pcm = pcm[: int(max_duration_s * 16000)]
+            clip_duration = max_duration_s
+        language_for_whisper: str | None
+        if language_hint == "hinglish":
+            language_for_whisper = "hi"
+        elif language_hint is None:
+            language_for_whisper = None
+        else:
+            language_for_whisper = language_hint
+        segments, info = self._run_whisper(
+            pcm,
+            language=language_for_whisper,
+            beam_size=beam_size,
+            vad_filter=vad_filter,
+        )
+        segments_list = list(segments)
+        detected_code = _map_language(getattr(info, "language", None))
+        vad_dropped_all = getattr(info, "vad_dropped_all_segments", None)
+        if vad_dropped_all is None:
+            vad_dropped_all = len(segments_list) == 0 and vad_filter
+        combined_text = _nfc("".join(getattr(s, "text", "") for s in segments_list))
+        duration_s = round(min(float(clip_duration), float(max_duration_s)), 3)
+        degraded = False
+        if combined_text == "":
+            confidence = 0.0
+            if vad_dropped_all:
+                detected: LanguageCode | Literal["unknown"] = "unknown"
+            else:
+                detected = detected_code
+                degraded = True
+        else:
+            confidence = _duration_weighted_confidence(segments_list)
+            detected = _infer_hinglish(detected_code, combined_text, language_hint)
+        result = TranscriptResult(
+            text=combined_text,
+            language_detected=detected,
+            confidence=confidence,
+            duration_s=duration_s,
+        )
+        latency_ms = int((time.perf_counter() - start) * 1000)
+        self._emit_trace(
+            AudioTrace(
+                op="transcribe",
+                input_hash=_input_hash(audio_bytes),
+                language=language_hint or "unknown",
+                duration_s=duration_s,
+                latency_ms=latency_ms,
+                confidence=confidence,
+                cache_hit=False,
+                degraded=degraded,
+                ts_ist=_ts_ist_now(),
+            )
+        )
+        return result
+
+    def _decode_input(self, audio_bytes: bytes) -> tuple[np.ndarray, float]:
+        """Return (float32 mono @ 16 kHz, duration_s); raise AudioDecodeError on mismatch."""
+
+        if len(audio_bytes) >= 3 and audio_bytes[:3] == b"ID3":
+            raise AudioDecodeError("MP3 / ID3-tagged inputs are not supported (no ffmpeg in image)")
+        rate = _riff_header_sample_rate(audio_bytes)
+        if rate is not None:
+            if rate != 16000:
+                raise AudioDecodeError("input must be 16 kHz mono; caller must pre-resample")
+            try:
+                sf = _load_soundfile()
+                data, sr = sf.read(io.BytesIO(audio_bytes), dtype="float32", always_2d=False)
+            except Exception as exc:
+                raise AudioDecodeError(f"soundfile failed to decode RIFF WAV: {exc}") from exc
+            if sr != 16000:
+                raise AudioDecodeError("input must be 16 kHz mono; caller must pre-resample")
+            arr = np.asarray(data, dtype=np.float32).reshape(-1)
+            duration = float(len(arr)) / 16000.0
+            return arr, duration
+        # Raw float32 PCM path (demo mic input). 16 kHz assumed. We only accept
+        # payloads that look like plausible audio — ≥ 0.25 s of float32 samples
+        # (4000 × 4 = 16000 bytes) whose magnitudes fit inside the normalized
+        # [-1, 1] range that Gradio emits. Short / out-of-range payloads are
+        # rejected so arbitrary random bytes do not slip through.
+        min_raw_pcm_bytes = 4000 * 4
+        if len(audio_bytes) >= min_raw_pcm_bytes and len(audio_bytes) % 4 == 0:
+            pcm = np.frombuffer(audio_bytes, dtype=np.float32).copy()
+            if pcm.size and np.all(np.isfinite(pcm)) and np.max(np.abs(pcm)) <= 2.0:
+                duration = float(pcm.size) / 16000.0
+                return pcm, duration
+        raise AudioDecodeError("input is not a valid 16 kHz RIFF WAV or float32 PCM payload")
+
+    def _run_whisper(
+        self,
+        pcm: np.ndarray,
+        *,
+        language: str | None,
+        beam_size: int,
+        vad_filter: bool,
+    ) -> tuple[Any, Any]:
+        try:
+            segments, info = self._model.transcribe(
+                pcm,
+                language=language,
+                beam_size=beam_size,
+                vad_filter=vad_filter,
+            )
+        except Exception as exc:
+            raise AudioDecodeError(f"whisper decode failed: {exc}") from exc
+        return segments, info
+
+    def warmup(self) -> None:
+        """Run one transcribe() on 0.5 s of silence to force load. audio.md §2.2."""
+
+        silence = _pcm16_silence_wav(0.5)
+        try:
+            self.transcribe(silence, "en")
+        except Exception:  # pragma: no cover — warmup best-effort
+            logger.debug("warmup transcribe failed; continuing", exc_info=True)
+
+
+def _duration_weighted_confidence(segments: list[Any]) -> float:
+    if not segments:
+        return 0.0
+    total_dur = 0.0
+    weighted = 0.0
+    for seg in segments:
+        start = float(getattr(seg, "start", 0.0) or 0.0)
+        end = float(getattr(seg, "end", 0.0) or 0.0)
+        dur = max(0.0, end - start)
+        avg_logprob = float(getattr(seg, "avg_logprob", 0.0) or 0.0)
+        confidence = _logprob_to_confidence(avg_logprob)
+        if dur == 0.0:
+            total_dur += 1.0
+            weighted += confidence
+        else:
+            total_dur += dur
+            weighted += confidence * dur
+    if total_dur == 0.0:
+        return 0.0
+    return round(weighted / total_dur, 3)
+
+
+def _infer_hinglish(
+    detected: LanguageCode | Literal["unknown"],
+    text: str,
+    hint: LanguageCode | None,
+) -> LanguageCode | Literal["unknown"]:
+    """Downgrade ``hi`` to ``hinglish`` when the decoded text is code-mixed.
+
+    Heuristic per audio.md §3.6: ≥ 2 ASCII words intermixed with Devanagari.
+    """
+
+    if hint != "hinglish":
+        return detected
+    if detected != "hi":
+        return detected
+    ascii_words = [tok for tok in text.split() if tok.isascii() and tok.isalpha()]
+    has_devanagari = any("ऀ" <= ch <= "ॿ" for ch in text)
+    if len(ascii_words) >= 2 and has_devanagari:
+        return "hinglish"
+    return detected
+
+
+# ---------------------------------------------------------------------------
+# Singletons
+# ---------------------------------------------------------------------------
+
+
+_tts_engine: TTSEngine | None = None
+_asr_engine: ASREngine | None = None
+_tts_lock = threading.Lock()
+_asr_lock = threading.Lock()
+
+
+def get_tts_engine(
+    *, trace_sink: TraceSink | None = None, model_id: str = "hexgrad/Kokoro-82M"
+) -> TTSEngine:
+    """Return the process-wide TTSEngine singleton. audio.md §3.2, §3.8."""
+
+    global _tts_engine
+    with _tts_lock:
+        if _tts_engine is None:
+            _tts_engine = TTSEngine(model_id=model_id, trace_sink=trace_sink)
+        elif trace_sink is not None and trace_sink is not _tts_engine._trace_sink:
+            logger.warning("get_tts_engine: different sink passed after construction; ignoring")
+        return _tts_engine
+
+
+def get_asr_engine(
+    *,
+    trace_sink: TraceSink | None = None,
+    model_id: str = "Systran/faster-whisper-small",
+    compute_type: Literal["int8", "int8_float16"] = "int8",
+) -> ASREngine:
+    """Return the process-wide ASREngine singleton. audio.md §3.2, §3.8."""
+
+    global _asr_engine
+    with _asr_lock:
+        if _asr_engine is None:
+            _asr_engine = ASREngine(
+                model_id=model_id, compute_type=compute_type, trace_sink=trace_sink
+            )
+        elif trace_sink is not None and trace_sink is not _asr_engine._trace_sink:
+            logger.warning("get_asr_engine: different sink passed after construction; ignoring")
+        return _asr_engine
+
+
+def _reset_singletons_for_tests() -> None:
+    """Tear down singletons. Tests only. audio.md §3.2 "Unload. Never." exemption."""
+
+    global _tts_engine, _asr_engine
+    with _tts_lock:
+        _tts_engine = None
+    with _asr_lock:
+        _asr_engine = None
+
+
+__all__ = [
+    "AudioDecodeError",
+    "AudioError",
+    "AudioTooLongError",
+    "AudioTrace",
+    "ASREngine",
+    "LanguageCode",
+    "ModelLoadError",
+    "TTSEngine",
+    "TTSOutOfMemoryError",
+    "TranscriptResult",
+    "TraceSink",
+    "UnsupportedLanguageError",
+    "UnsupportedVoicePackError",
+    "VOICE_PACKS",
+    "VoicePack",
+    "VoicePackMapping",
+    "get_asr_engine",
+    "get_tts_engine",
+]

cells/step_10_env.md

@@ -0,0 +1,83 @@
+# step_10_env — DriftCallEnv
+
+Implements `docs/modules/env.md` and `DESIGN.md §4`.
+
+## Public surface
+
+| Symbol | Kind | Notes |
+|---|---|---|
+| `DriftCallEnv` | class | OpenEnv-compliant RL environment. Single-session, single-episode-at-a-time. |
+| `EnvConfig` | frozen dataclass | Validated config snapshot. Built via `EnvConfig.from_mapping(...)`. |
+| `Episode` | frozen dataclass | Terminal-only snapshot fed to `cells.step_08_rewards.compute_rewards`. |
+| `DriftScheduler` | Protocol | `(stage, seed, goal) -> tuple[DriftEvent, ...]`. Default: `drift_injector.build_schedule`. |
+| `TTSEngine` / `ASREngine` | Protocols | Audio boundary contracts (env.md §2.1). |
+| `DriftCallEnvError` and 12 subclasses | exceptions | E1..E12 typed taxonomy. |
+
+## Wiring
+
+```
+reset(seed)
+  └── task_generator.generate(seed, stage, language_weights)
+  └── per-domain vendor.initial_state(seed, goal)        # airline, cab, restaurant, hotel, payment
+  └── scheduler(stage, seed, goal)                       # default = drift_injector.build_schedule
+  └── audio_boundary_enabled? tts_engine.synthesize(seed_utterance, language)
+  └── DriftCallObservation(turn=0, ...)
+
+step(action, *, force_drift_pattern=None)
+  1a. _validate_action(action)            # pure, raises InvalidActionError BEFORE mutation
+  1b. force_drift_pattern resolved        # unknown -> InvalidActionError
+  2.  turn += 1                            # via dataclasses.replace
+  3.  drift fold:                          # forced pattern OR scheduled pending drifts
+        - sort by (turn asc, pattern_id asc)
+        - apply via drift_injector.apply_drift
+  4.  side-channel emit pass               # vendor.emit_side_channel_if_pending per domain
+  5.  dispatch:
+        TOOL_CALL    -> vendor.dispatch(...) and merge any pending notice into ToolResult
+        SPEAK/CLARIFY-> no state change
+        PROBE_SCHEMA -> vendor.describe_schema(state, version), wrapped as ToolResult
+        SUBMIT       -> terminate("SUBMIT")
+        ABORT        -> terminate("ABORT")
+  6.  record action (and ToolResult, if any) via dataclasses.replace
+  7.  if turn >= max_turns -> terminate("TIMEOUT")
+  8.  if terminal -> build Episode + step_08_rewards.compute_rewards (memoized)
+  9.  return DriftCallObservation
+```
+
+## Termination
+
+`terminated_by ∈ {SUBMIT, ABORT, TIMEOUT, ANTI_HACK}`. Reward layer reads `terminated_by` to force `r1=0` for ABORT/TIMEOUT/ANTI_HACK. `Episode` and `Rewards` are write-once; `episode()`/`rewards()` return memoized identities.
+
+## Determinism contract
+
+Same `(config, seed)` ⇒ byte-identical `goal`, `drift_schedule`, and initial `vendor_states`. The only non-deterministic field is `episode_id` (uuid4), which is purely an audit handle (env.md §9 Q5).
+
+## Error taxonomy (E1–E12)
+
+All extend `DriftCallEnvError(Exception)`:
+
+| # | Class | When |
+|---|---|---|
+| E1 | `InvalidConfigError` | unknown key, bad weights, missing audio engine, etc. |
+| E2 | `EnvNotReadyError` | step/state/episode/rewards before reset |
+| E3 | `EnvClosedError` | reset/step after close |
+| E4 | `InvalidActionError` | per-`ActionType` field-matrix violation; force_drift_pattern unknown |
+| E5 | `EpisodeAlreadyTerminalError` | step after termination |
+| E6 | `EpisodeNotTerminalError` | episode/rewards before termination |
+| E7 | `ConcurrentStepError` | reentrant step |
+| E8 | `UnknownDomainError` | PROBE_SCHEMA on unregistered domain |
+| E9 | `UnknownToolError` | TOOL_CALL with tool_name not in available_tools |
+| E10 | `DriftInjectionError` | drift fold failure (propagated from drift_injector) |
+| E11 | `RewardComputationError` | compute_rewards failure |
+| E12 | `AudioPipelineError` | TTS/ASR engine raised at boundary |
+
+Validation in `_validate_action` is strictly pure: raises before any state mutation, so the env remains valid for a subsequent `step()`.
+
+## Audio boundary
+
+`audio_boundary_enabled=True` requires both `tts_engine` and `asr_engine`. On `reset()` the env calls `tts_engine.synthesize(goal.seed_utterance, goal.language)`; the canonical `last_transcript` remains the textual `seed_utterance`. The audio pipeline never feeds bytes back into reward computation.
+
+## Out of scope
+
+- LLM judging — never. The env is the judge.
+- Concurrency — single-session by contract; no locks, no asyncio.
+- Disk/network I/O at `__init__` — strictly forbidden.

cells/step_10_env.py

@@ -0,0 +1,1019 @@
+"""Cell 10 — DriftCallEnv integration class.
+
+Implements ``docs/modules/env.md`` and DESIGN.md §4. ``DriftCallEnv`` is the
+single public surface that composes models, vendors, drift_injector,
+task_generator, rewards, and the optional audio boundary into an
+OpenEnv-compliant RL environment.
+
+Hard rules (env.md §3.8, CLAUDE.md §0):
+- All public dataclasses are frozen.
+- State transitions go through ``dataclasses.replace``; no in-place mutation.
+- Validation is pure: ``InvalidActionError`` raises BEFORE any state mutation.
+- Rewards are computed exactly once at termination and memoized.
+- No LLM judge anywhere; no network/disk I/O at ``__init__``.
+"""
+
+from __future__ import annotations
+
+import os
+import struct
+import uuid
+from dataclasses import dataclass, field, replace
+from datetime import datetime, timedelta, timezone
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast
+
+from cells.step_04_models import (
+    ActionType,
+    DriftCallAction,
+    DriftCallObservation,
+    DriftCallState,
+    DriftEvent,
+    GoalSpec,
+    ToolResult,
+)
+from cells.step_05_vendors import TOOLS as VENDOR_TOOLS
+from cells.step_05_vendors import VENDOR_REGISTRY
+from cells.step_06_drift_injector import (
+    DriftCatalogueError,
+    DriftDomainMismatchError,
+    DriftReapplicationError,
+    DriftScheduleConflictError,
+    UnknownDriftPatternError,
+    apply_drift,
+    build_schedule,
+    list_patterns,
+)
+from cells.step_07_task_generator import (
+    InvalidLanguageWeightError,
+    InvalidStageError,
+)
+from cells.step_07_task_generator import (
+    generate as task_generate,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+# rewards is imported lazily inside _compute_rewards to keep the env importable
+# even before step_08_rewards.py lands; failures surface as RewardComputationError.
+
+_DEFAULT_LANGUAGE_WEIGHTS: dict[str, float] = {
+    "en": 0.4,
+    "hinglish": 0.4,
+    "hi": 0.1,
+    "ta": 0.05,
+    "kn": 0.05,
+}
+
+_LANGUAGE_CODES: frozenset[str] = frozenset({"hi", "ta", "kn", "en", "hinglish"})
+
+_STAGE_MAX_TURNS: dict[int, int] = {1: 8, 2: 12, 3: 16}
+
+_VENDOR_DOMAINS: tuple[str, ...] = ("airline", "cab", "restaurant", "hotel", "payment")
+
+_TERMINATED_VALUES: frozenset[str] = frozenset({"SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"})
+
+_NOW_IST: datetime = datetime(2026, 4, 25, 10, 0, tzinfo=timezone(timedelta(hours=5, minutes=30)))
+
+
+# ---------------------------------------------------------------------------
+# Error taxonomy (env.md §5)
+# ---------------------------------------------------------------------------
+
+
+class DriftCallEnvError(Exception):
+    """Root for every typed env error (env.md §5)."""
+
+
+class InvalidConfigError(DriftCallEnvError):
+    """E1 — malformed config dict."""
+
+
+class EnvNotReadyError(DriftCallEnvError):
+    """E2 — operation issued before reset()."""
+
+
+class EnvClosedError(DriftCallEnvError):
+    """E3 — operation issued after close()."""
+
+
+class InvalidActionError(DriftCallEnvError):
+    """E4 — action fails the per-ActionType field matrix."""
+
+
+class EpisodeAlreadyTerminalError(DriftCallEnvError):
+    """E5 — step() called after termination."""
+
+
+class EpisodeNotTerminalError(DriftCallEnvError):
+    """E6 — episode()/rewards() called before termination."""
+
+
+class ConcurrentStepError(DriftCallEnvError):
+    """E7 — reentrant step() detected."""
+
+
+class UnknownDomainError(DriftCallEnvError):
+    """E8 — PROBE_SCHEMA on a domain that is not registered."""
+
+
+class UnknownToolError(DriftCallEnvError):
+    """E9 — TOOL_CALL with a tool_name not in available_tools()."""
+
+
+class DriftInjectionError(DriftCallEnvError):
+    """E10 — drift fold raised; surfaced as-is."""
+
+
+class RewardComputationError(DriftCallEnvError):
+    """E11 — compute_rewards raised; surfaced as-is."""
+
+
+class AudioPipelineError(DriftCallEnvError):
+    """E12 — TTS/ASR engine raised on a step()/reset() boundary."""
+
+
+_ALL_ERROR_CLASSES: tuple[type[DriftCallEnvError], ...] = (
+    InvalidConfigError,
+    EnvNotReadyError,
+    EnvClosedError,
+    InvalidActionError,
+    EpisodeAlreadyTerminalError,
+    EpisodeNotTerminalError,
+    ConcurrentStepError,
+    UnknownDomainError,
+    UnknownToolError,
+    DriftInjectionError,
+    RewardComputationError,
+    AudioPipelineError,
+)
+
+
+# ---------------------------------------------------------------------------
+# Protocols (env.md §2.1)
+# ---------------------------------------------------------------------------
+
+
+class DriftScheduler(Protocol):
+    def __call__(
+        self, stage: int, episode_seed: int, goal: GoalSpec
+    ) -> tuple[DriftEvent, ...]: ...
+
+
+class TTSEngine(Protocol):
+    def synthesize(
+        self,
+        text: str,
+        language_code: str,
+        voice_pack: Any | None = None,
+        *,
+        seed: int = 0,
+        sample_rate_hz: int = 16000,
+    ) -> bytes: ...
+
+
+class ASREngine(Protocol):
+    def transcribe(
+        self,
+        audio_bytes: bytes,
+        language_hint: str | None,
+        *,
+        beam_size: int = 1,
+        vad_filter: bool = True,
+        max_duration_s: float = 30.0,
+    ) -> Any: ...
+
+
+def _default_scheduler(
+    stage: int, episode_seed: int, goal: GoalSpec
+) -> tuple[DriftEvent, ...]:
+    return build_schedule(stage, episode_seed, goal)
+
+
+# ---------------------------------------------------------------------------
+# Episode (env.md §4.3) — built at termination, fed to rewards.compute_rewards.
+# Matches the Episode shape consumed by step_08_rewards (kw fields).
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class Episode:
+    episode_id: str
+    goal: GoalSpec
+    actions: tuple[DriftCallAction, ...]
+    action_turns: tuple[int, ...]
+    tool_results: tuple[ToolResult, ...]
+    tool_result_turns: tuple[int, ...]
+    drift_log: tuple[DriftEvent, ...]
+    vendor_states_final: dict[str, dict[str, Any]]
+    schema_versions_final: dict[str, str]
+    max_turns: int
+    turns_used: int
+    terminated_by: Literal["SUBMIT", "ABORT", "TIMEOUT", "ANTI_HACK"]
+    stage: Literal[1, 2, 3]
+    drift_pattern_overrides: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# EnvConfig (env.md §4.1)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EnvConfig:
+    curriculum_stage: Literal[1, 2, 3]
+    language_weights: dict[str, float]
+    audio_boundary_enabled: bool
+    max_turns_override: int | None
+    scheduler: DriftScheduler
+    tts_engine: TTSEngine | None
+    asr_engine: ASREngine | None
+
+    @classmethod
+    def from_mapping(cls, raw: Mapping[str, Any] | None) -> EnvConfig:
+        allowed = {
+            "curriculum_stage",
+            "language_weights",
+            "audio_boundary_enabled",
+            "max_turns_override",
+            "scheduler",
+            "tts_engine",
+            "asr_engine",
+        }
+        if raw is None:
+            raw = {}
+        if not isinstance(raw, dict):
+            raise InvalidConfigError(
+                f"config must be a dict or None, got {type(raw).__name__}"
+            )
+
+        unknown = set(raw.keys()) - allowed
+        if unknown:
+            raise InvalidConfigError(
+                f"unknown config key(s): {sorted(unknown)}; "
+                f"allowed: {sorted(allowed)}"
+            )
+
+        stage_raw = raw.get("curriculum_stage", 1)
+        if isinstance(stage_raw, bool) or not isinstance(stage_raw, int):
+            raise InvalidConfigError(
+                f"curriculum_stage must be int in {{1,2,3}}, got "
+                f"{type(stage_raw).__name__}"
+            )
+        if stage_raw not in (1, 2, 3):
+            raise InvalidConfigError(
+                f"curriculum_stage must be 1, 2, or 3; got {stage_raw!r}"
+            )
+        stage = cast("Literal[1, 2, 3]", stage_raw)
+
+        weights_raw = raw.get("language_weights", _DEFAULT_LANGUAGE_WEIGHTS)
+        if not isinstance(weights_raw, dict) or not weights_raw:
+            raise InvalidConfigError(
+                "language_weights must be a non-empty dict"
+            )
+        for k, v in weights_raw.items():
+            if k not in _LANGUAGE_CODES:
+                raise InvalidConfigError(
+                    f"language_weights: unknown language {k!r}; "
+                    f"allowed: {sorted(_LANGUAGE_CODES)}"
+                )
+            if isinstance(v, bool) or not isinstance(v, (int, float)):
+                raise InvalidConfigError(
+                    f"language_weights[{k!r}] must be numeric, got "
+                    f"{type(v).__name__}"
+                )
+            if v < 0:
+                raise InvalidConfigError(
+                    f"language_weights[{k!r}]={v} is negative"
+                )
+        total = sum(float(v) for v in weights_raw.values())
+        if abs(total - 1.0) > 1e-6:
+            raise InvalidConfigError(
+                f"language_weights sum {total!r} not within 1.0 ± 1e-6"
+            )
+        # Frozen copy.
+        weights: dict[str, float] = {k: float(v) for k, v in weights_raw.items()}
+
+        audio_enabled_raw = raw.get("audio_boundary_enabled", False)
+        if not isinstance(audio_enabled_raw, bool):
+            raise InvalidConfigError(
+                f"audio_boundary_enabled must be bool, got "
+                f"{type(audio_enabled_raw).__name__}"
+            )
+        audio_enabled = audio_enabled_raw
+
+        max_turns_override = raw.get("max_turns_override")
+        if max_turns_override is not None:
+            if isinstance(max_turns_override, bool) or not isinstance(
+                max_turns_override, int
+            ):
+                raise InvalidConfigError(
+                    f"max_turns_override must be int or None, got "
+                    f"{type(max_turns_override).__name__}"
+                )
+            if max_turns_override < 1:
+                raise InvalidConfigError(
+                    f"max_turns_override must be >= 1, got {max_turns_override}"
+                )
+
+        scheduler = raw.get("scheduler", _default_scheduler)
+        if not callable(scheduler):
+            raise InvalidConfigError("scheduler must be callable")
+
+        tts_engine = raw.get("tts_engine")
+        asr_engine = raw.get("asr_engine")
+
+        if audio_enabled:
+            if tts_engine is None:
+                raise InvalidConfigError(
+                    "tts_engine is required when audio_boundary_enabled is True"
+                )
+            if asr_engine is None:
+                raise InvalidConfigError(
+                    "asr_engine is required when audio_boundary_enabled is True"
+                )
+        else:
+            if tts_engine is not None:
+                raise InvalidConfigError(
+                    "tts_engine must be None when audio_boundary_enabled is False"
+                )
+            if asr_engine is not None:
+                raise InvalidConfigError(
+                    "asr_engine must be None when audio_boundary_enabled is False"
+                )
+
+        return cls(
+            curriculum_stage=stage,
+            language_weights=weights,
+            audio_boundary_enabled=audio_enabled,
+            max_turns_override=max_turns_override,
+            scheduler=cast("DriftScheduler", scheduler),
+            tts_engine=cast("TTSEngine | None", tts_engine),
+            asr_engine=cast("ASREngine | None", asr_engine),
+        )
+
+
+# ---------------------------------------------------------------------------
+# DriftCallEnv
+# ---------------------------------------------------------------------------
+
+
+def _make_seed_from_urandom() -> int:
+    raw = os.urandom(8)
+    (value,) = struct.unpack("<Q", raw)
+    return int(value)
+
+
+def _vendor_state_to_dict(state: Any) -> dict[str, Any]:
+    """Coerce a frozen vendor dataclass (or already-dict) into a plain dict."""
+    if isinstance(state, dict):
+        return dict(state)
+    # All vendor states are frozen dataclasses.
+    import dataclasses as _dc
+
+    if _dc.is_dataclass(state) and not isinstance(state, type):
+        return _dc.asdict(state)
+    # Defensive: best-effort fallback.
+    return {"_raw": repr(state)}
+
+
+class DriftCallEnv:
+    """OpenEnv-compliant RL environment for DriftCall (env.md §1)."""
+
+    # -- construction --------------------------------------------------------
+
+    def __init__(self, config: dict[str, Any] | None = None) -> None:
+        self._config: EnvConfig = EnvConfig.from_mapping(config)
+        self._state: DriftCallState | None = None
+        self._rewards: Any | None = None
+        self._episode: Episode | None = None
+        self._closed: bool = False
+        self._seed: int | None = None
+        self._episode_id: str | None = None
+        # Pending side-channel notices keyed by domain (env.md §3.3).
+        self._side_channel_pending: dict[str, str] = {}
+        # Per-vendor-state cache (frozen dataclass or dict). Kept on the env
+        # because DriftCallState.vendor_states is a dict[str, dict] for
+        # compatibility with the design dataclass.
+        self._vendor_state_objects: dict[str, Any] = {}
+        # Re-entrancy guard (E7).
+        self._step_in_progress: bool = False
+
+    # -- internal helpers ----------------------------------------------------
+
+    @property
+    def _max_turns(self) -> int:
+        if self._config.max_turns_override is not None:
+            return int(self._config.max_turns_override)
+        return _STAGE_MAX_TURNS[self._config.curriculum_stage]
+
+    def _available_tools(self) -> tuple[str, ...]:
+        return VENDOR_TOOLS
+
+    def _ensure_ready_for_step(self) -> None:
+        if self._closed:
+            raise EnvClosedError("env is closed")
+        if self._state is None:
+            raise EnvNotReadyError("reset() must be called before step()")
+        if self._state.done:
+            raise EpisodeAlreadyTerminalError(
+                f"episode already terminated (terminated_by={self._terminated_by()})"
+            )
+
+    def _terminated_by(self) -> str | None:
+        return self._episode.terminated_by if self._episode is not None else None
+
+    # -- OpenEnv primitives --------------------------------------------------
+
+    def reset(self, seed: int | None = None) -> DriftCallObservation:
+        if self._closed:
+            raise EnvClosedError("env is closed")
+
+        if seed is None:
+            seed = _make_seed_from_urandom()
+        if isinstance(seed, bool) or not isinstance(seed, int):
+            raise InvalidActionError(
+                f"seed must be int or None, got {type(seed).__name__}"
+            )
+
+        self._seed = int(seed)
+        # Reset memoization; legacy state is dropped before any propagatable
+        # exception can leak (env.md §2.2 docstring).
+        self._state = None
+        self._rewards = None
+        self._episode = None
+        self._side_channel_pending = {}
+        self._vendor_state_objects = {}
+        self._episode_id = None
+
+        try:
+            goal = task_generate(
+                self._seed,
+                self._config.curriculum_stage,
+                cast("dict[Any, float]", self._config.language_weights),
+            )
+        except (InvalidLanguageWeightError, InvalidStageError) as exc:
+            # E1-class reset failure (env.md §2.2 raises clause).
+            raise InvalidConfigError(str(exc)) from exc
+
+        # Initial per-domain vendor state objects (frozen dataclasses).
+        vendor_state_objects: dict[str, Any] = {}
+        vendor_states_dict: dict[str, dict[str, Any]] = {}
+        for domain in _VENDOR_DOMAINS:
+            ns = VENDOR_REGISTRY[domain]
+            vs = ns.initial_state(self._seed, goal)
+            vendor_state_objects[domain] = vs
+            vendor_states_dict[domain] = _vendor_state_to_dict(vs)
+
+        schema_versions = {d: "v1" for d in _VENDOR_DOMAINS}
+
+        try:
+            schedule = self._config.scheduler(
+                self._config.curriculum_stage, self._seed, goal
+            )
+        except (
+            DriftScheduleConflictError,
+            DriftCatalogueError,
+            UnknownDriftPatternError,
+            DriftDomainMismatchError,
+        ) as exc:
+            # Bad scheduler at reset is an E1 (env.md §7.4).
+            raise InvalidConfigError(f"scheduler failure: {exc}") from exc
+
+        self._episode_id = uuid.uuid4().hex
+
+        max_turns = self._max_turns
+        new_state = DriftCallState(
+            episode_id=self._episode_id,
+            goal=goal,
+            vendor_states=vendor_states_dict,
+            schema_versions=schema_versions,
+            drift_schedule=tuple(schedule),
+            drift_fired=(),
+            turn=0,
+            max_turns=max_turns,
+            actions=(),
+            done=False,
+        )
+        self._state = new_state
+        self._vendor_state_objects = vendor_state_objects
+
+        if self._config.audio_boundary_enabled:
+            tts = self._config.tts_engine
+            assert tts is not None  # validated in EnvConfig
+            try:
+                tts.synthesize(goal.seed_utterance, goal.language)
+            except Exception as exc:  # noqa: BLE001 — surface as E12-class
+                # Audio failure on reset leaves env unready (env.md §5 E12).
+                self._state = None
+                self._vendor_state_objects = {}
+                self._episode_id = None
+                raise AudioPipelineError(f"TTS reset failure: {exc}") from exc
+
+        return self._build_observation()
+
+    def step(
+        self,
+        action: DriftCallAction,
+        *,
+        force_drift_pattern: str | None = None,
+    ) -> DriftCallObservation:
+        # 1a. Pure validation — must raise before any state mutation.
+        self._ensure_ready_for_step()
+        self._validate_action(action)
+        if force_drift_pattern is not None:
+            valid_ids = {p.id for p in list_patterns()}
+            if force_drift_pattern not in valid_ids:
+                raise InvalidActionError(
+                    f"force_drift_pattern {force_drift_pattern!r} not a known "
+                    f"pattern_id"
+                )
+
+        if self._step_in_progress:
+            raise ConcurrentStepError("reentrant step() detected")
+        self._step_in_progress = True
+        try:
+            return self._step_inner(action, force_drift_pattern)
+        finally:
+            self._step_in_progress = False
+
+    def _step_inner(
+        self,
+        action: DriftCallAction,
+        force_drift_pattern: str | None,
+    ) -> DriftCallObservation:
+        assert self._state is not None  # ensured above
+        # 2. Increment turn counter.
+        turn_current = self._state.turn + 1
+        self._state = replace(self._state, turn=turn_current)
+
+        # 3. Fire drifts for this turn.
+        self._fire_drifts(turn_current, force_drift_pattern)
+
+        # 4. Side-channel emit pass — refresh pending notices for any vendor
+        # whose state just mutated.
+        self._emit_side_channel()
+
+        # 5. Dispatch action.
+        new_tool_result, terminate, terminated_by = self._dispatch(action)
+
+        # 6. Record action (and ToolResult, if any) via dataclasses.replace.
+        new_actions = self._state.actions + (action,)
+        if new_tool_result is not None:
+            # Tool result history lives on the state's vendor history; here we
+            # rely on the running observation history we will rebuild in §3.4.
+            self._tool_results = self._tool_results + (new_tool_result,)
+            self._tool_result_turns = self._tool_result_turns + (turn_current,)
+        self._action_turns = self._action_turns + (turn_current,)
+        self._state = replace(self._state, actions=new_actions)
+
+        # 7. Budget check — only if action did not already terminate.
+        if not terminate and turn_current >= self._state.max_turns:
+            terminate = True
+            terminated_by = "TIMEOUT"
+
+        # 8. If terminal, build Episode + compute rewards.
+        if terminate:
+            assert terminated_by is not None
+            self._terminate(terminated_by)
+
+        # 9. Build observation.
+        return self._build_observation()
+
+    def state(self) -> DriftCallState:
+        if self._state is None:
+            raise EnvNotReadyError("reset() must be called before state()")
+        return self._state
+
+    def close(self) -> None:
+        # Idempotent.
+        self._closed = True
+        # Per env.md §9 Q7: never invoke close on shared audio engines.
+        # Only drop per-env state.
+        self._side_channel_pending = {}
+        self._vendor_state_objects = {}
+        # Note: we keep self._state, self._rewards, self._episode so post-close
+        # audits still work (env.md §7.11).
+
+    def episode(self) -> Episode:
+        if self._episode is None:
+            raise EpisodeNotTerminalError("episode is not terminal")
+        return self._episode
+
+    def rewards(self) -> Any:
+        if self._rewards is None:
+            raise EpisodeNotTerminalError("episode is not terminal")
+        return self._rewards
+
+    def done(self) -> bool:
+        if self._state is None:
+            return False
+        return bool(self._state.done)
+
+    # -- validation ----------------------------------------------------------
+
+    def _validate_action(self, action: DriftCallAction) -> None:
+        if not isinstance(action, DriftCallAction):
+            raise InvalidActionError(
+                f"action must be DriftCallAction, got {type(action).__name__}"
+            )
+        atype = action.action_type
+        if not isinstance(atype, ActionType):
+            raise InvalidActionError(
+                f"action_type must be ActionType, got {type(atype).__name__}"
+            )
+
+        # rationale length cap (env.md §3.1).
+        if action.rationale is not None and len(action.rationale) > 200:
+            raise InvalidActionError(
+                f"rationale length {len(action.rationale)} exceeds 200"
+            )
+
+        if atype == ActionType.TOOL_CALL:
+            if not action.tool_name or not isinstance(action.tool_name, str):
+                raise InvalidActionError("TOOL_CALL requires non-empty tool_name")
+            if action.tool_args is None or not isinstance(action.tool_args, dict):
+                raise InvalidActionError(
+                    "TOOL_CALL requires tool_args dict (may be empty)"
+                )
+            if action.message is not None or action.confidence is not None:
+                raise InvalidActionError(
+                    "TOOL_CALL forbids message/confidence"
+                )
+            if action.tool_name not in self._available_tools():
+                raise UnknownToolError(
+                    f"tool_name {action.tool_name!r} not in available_tools()"
+                )
+            # JSON-serializability (shallow check: must be dict; values arbitrary).
+            return
+
+        if atype == ActionType.SPEAK or atype == ActionType.CLARIFY:
+            if not isinstance(action.message, str):
+                raise InvalidActionError(
+                    f"{atype.value} requires str message"
+                )
+            if not (1 <= len(action.message) <= 2000):
+                raise InvalidActionError(
+                    f"{atype.value} message length must be in [1, 2000], "
+                    f"got {len(action.message)}"
+                )
+            if "\x00" in action.message:
+                raise InvalidActionError(
+                    f"{atype.value} message contains NUL byte"
+                )
+            if (
+                action.tool_name is not None
+                or action.tool_args is not None
+                or action.confidence is not None
+            ):
+                raise InvalidActionError(
+                    f"{atype.value} forbids tool_name/tool_args/confidence"
+                )
+            return
+
+        if atype == ActionType.PROBE_SCHEMA:
+            if not action.tool_name or not isinstance(action.tool_name, str):
+                raise InvalidActionError(
+                    "PROBE_SCHEMA requires tool_name (domain string)"
+                )
+            if (
+                action.tool_args is not None
+                or action.message is not None
+                or action.confidence is not None
+            ):
+                raise InvalidActionError(
+                    "PROBE_SCHEMA forbids tool_args/message/confidence"
+                )
+            assert self._state is not None
+            if action.tool_name not in self._state.vendor_states:
+                raise UnknownDomainError(
+                    f"PROBE_SCHEMA: domain {action.tool_name!r} not registered"
+                )
+            return
+
+        if atype == ActionType.SUBMIT:
+            if action.confidence is None or not isinstance(
+                action.confidence, (int, float)
+            ) or isinstance(action.confidence, bool):
+                raise InvalidActionError("SUBMIT requires float confidence")
+            conf = float(action.confidence)
+            if not (0.0 <= conf <= 1.0):
+                raise InvalidActionError(
+                    f"SUBMIT confidence {conf!r} outside [0.0, 1.0]"
+                )
+            if action.tool_name is not None or action.tool_args is not None:
+                raise InvalidActionError(
+                    "SUBMIT forbids tool_name/tool_args"
+                )
+            if action.message is not None and not isinstance(action.message, str):
+                raise InvalidActionError("SUBMIT message must be str if present")
+            return
+
+        if atype == ActionType.ABORT:
+            if (
+                action.tool_name is not None
+                or action.tool_args is not None
+                or action.confidence is not None
+            ):
+                raise InvalidActionError(
+                    "ABORT forbids tool_name/tool_args/confidence"
+                )
+            return
+
+        # Unreachable — all six ActionType members handled above.
+        raise InvalidActionError(f"unhandled action_type {atype!r}")
+
+    # -- drift firing --------------------------------------------------------
+
+    def _fire_drifts(self, turn_current: int, force_pattern: str | None) -> None:
+        assert self._state is not None
+        if force_pattern is not None:
+            patterns_by_id = {p.id: p for p in list_patterns()}
+            pattern = patterns_by_id[force_pattern]
+            if pattern.domain not in self._state.vendor_states:
+                raise DriftInjectionError(
+                    f"force_drift_pattern {force_pattern!r}: domain "
+                    f"{pattern.domain!r} not registered"
+                )
+            event = DriftEvent(
+                turn=turn_current,
+                drift_type=pattern.drift_type,
+                domain=pattern.domain,
+                description=pattern.description,
+                from_version=pattern.from_version,
+                to_version=pattern.to_version,
+                pattern_id=pattern.id,
+            )
+            try:
+                self._state = apply_drift(self._state, event)
+            except (
+                UnknownDriftPatternError,
+                DriftDomainMismatchError,
+                DriftReapplicationError,
+            ) as exc:
+                raise DriftInjectionError(str(exc)) from exc
+            return
+
+        # Schedule-driven fold.
+        pending = tuple(
+            e for e in self._state.drift_schedule
+            if e.turn == turn_current and e not in self._state.drift_fired
+        )
+        if not pending:
+            return
+        ordered = tuple(sorted(pending, key=lambda e: (e.turn, e.pattern_id)))
+        for event in ordered:
+            try:
+                self._state = apply_drift(self._state, event)
+            except (
+                UnknownDriftPatternError,
+                DriftDomainMismatchError,
+                DriftReapplicationError,
+            ) as exc:
+                raise DriftInjectionError(str(exc)) from exc
+
+    def _emit_side_channel(self) -> None:
+        """Refresh pending side-channel notices per env.md §3.3 clause 3."""
+        assert self._state is not None
+        new_pending = dict(self._side_channel_pending)
+        for domain in _VENDOR_DOMAINS:
+            ns = VENDOR_REGISTRY[domain]
+            vs_obj = self._vendor_state_objects.get(domain)
+            if vs_obj is None:
+                continue
+            try:
+                notice, new_state = ns.emit_side_channel_if_pending(vs_obj)
+            except Exception as exc:  # noqa: BLE001 — defensive
+                raise DriftInjectionError(
+                    f"side-channel emit failed for {domain}: {exc}"
+                ) from exc
+            if notice is not None:
+                existing = new_pending.get(domain)
+                merged = (
+                    f"{existing}\n---\n{notice}" if existing else notice
+                )
+                new_pending[domain] = merged
+            self._vendor_state_objects[domain] = new_state
+        self._side_channel_pending = new_pending
+
+    # -- dispatch ------------------------------------------------------------
+
+    @property
+    def _tool_results(self) -> tuple[ToolResult, ...]:
+        return getattr(self, "_tool_results_internal", ())
+
+    @_tool_results.setter
+    def _tool_results(self, value: tuple[ToolResult, ...]) -> None:
+        self._tool_results_internal = value
+
+    @property
+    def _tool_result_turns(self) -> tuple[int, ...]:
+        return getattr(self, "_tool_result_turns_internal", ())
+
+    @_tool_result_turns.setter
+    def _tool_result_turns(self, value: tuple[int, ...]) -> None:
+        self._tool_result_turns_internal = value
+
+    @property
+    def _action_turns(self) -> tuple[int, ...]:
+        return getattr(self, "_action_turns_internal", ())
+
+    @_action_turns.setter
+    def _action_turns(self, value: tuple[int, ...]) -> None:
+        self._action_turns_internal = value
+
+    def _dispatch(
+        self, action: DriftCallAction
+    ) -> tuple[ToolResult | None, bool, str | None]:
+        """Return (tool_result, terminate?, terminated_by?)."""
+        assert self._state is not None
+        atype = action.action_type
+
+        if atype == ActionType.SUBMIT:
+            return None, True, "SUBMIT"
+        if atype == ActionType.ABORT:
+            return None, True, "ABORT"
+        if atype == ActionType.SPEAK or atype == ActionType.CLARIFY:
+            return None, False, None
+
+        if atype == ActionType.PROBE_SCHEMA:
+            assert action.tool_name is not None
+            domain = action.tool_name
+            ns = VENDOR_REGISTRY[domain]
+            vs_obj = self._vendor_state_objects[domain]
+            schema_version = self._state.schema_versions[domain]
+            schema = ns.describe_schema(vs_obj, schema_version)
+            tr = ToolResult(
+                tool_name=f"probe:{domain}",
+                status="ok",
+                response=dict(schema),
+                schema_version=schema_version,
+                latency_ms=0,
+            )
+            return tr, False, None
+
+        if atype == ActionType.TOOL_CALL:
+            assert action.tool_name is not None and action.tool_args is not None
+            tool_name = action.tool_name
+            domain = tool_name.split(".", 1)[0]
+            if domain not in self._state.vendor_states:
+                raise UnknownDomainError(
+                    f"tool {tool_name!r} targets unknown domain {domain!r}"
+                )
+            ns = VENDOR_REGISTRY[domain]
+            vs_obj = self._vendor_state_objects[domain]
+            schema_version = self._state.schema_versions[domain]
+            try:
+                if domain == "payment":
+                    tr, new_vs = ns.dispatch(
+                        tool_name,
+                        action.tool_args,
+                        vs_obj,
+                        schema_version,
+                        self._seed,
+                        _NOW_IST,
+                    )
+                    payment_state = new_vs
+                else:
+                    payment_state = self._vendor_state_objects.get("payment")
+                    tr, new_vs, payment_state = ns.dispatch(
+                        tool_name,
+                        action.tool_args,
+                        vs_obj,
+                        schema_version,
+                        self._seed,
+                        _NOW_IST,
+                        payment_state,
+                    )
+            except ValueError as exc:
+                # Unknown tool inside a known domain → treat as anti-hack.
+                raise UnknownToolError(str(exc)) from exc
+
+            self._vendor_state_objects[domain] = new_vs
+            if payment_state is not None:
+                self._vendor_state_objects["payment"] = payment_state
+
+            # Refresh state.vendor_states snapshot.
+            new_vendor_states = dict(self._state.vendor_states)
+            new_vendor_states[domain] = _vendor_state_to_dict(new_vs)
+            if domain != "payment" and payment_state is not None:
+                new_vendor_states["payment"] = _vendor_state_to_dict(payment_state)
+            self._state = replace(self._state, vendor_states=new_vendor_states)
+
+            # Attach pending side-channel notice (one-shot per domain).
+            notice = self._side_channel_pending.pop(domain, None)
+            if notice is not None:
+                merged_response = dict(tr.response)
+                merged_response["_notice"] = notice
+                tr = ToolResult(
+                    tool_name=tr.tool_name,
+                    status=tr.status,
+                    response=merged_response,
+                    schema_version=tr.schema_version,
+                    latency_ms=tr.latency_ms,
+                )
+            return tr, False, None
+
+        # Unreachable.
+        raise InvalidActionError(f"unhandled action_type {atype!r}")
+
+    # -- termination ---------------------------------------------------------
+
+    def _terminate(self, terminated_by: str) -> None:
+        assert self._state is not None
+        if terminated_by not in _TERMINATED_VALUES:
+            raise RewardComputationError(
+                f"unknown terminated_by sentinel {terminated_by!r}"
+            )
+        self._state = replace(self._state, done=True)
+        episode = Episode(
+            episode_id=self._state.episode_id,
+            goal=self._state.goal,
+            actions=self._state.actions,
+            action_turns=self._action_turns,
+            tool_results=self._tool_results,
+            tool_result_turns=self._tool_result_turns,
+            drift_log=self._state.drift_fired,
+            vendor_states_final={
+                d: _vendor_state_to_dict(self._vendor_state_objects[d])
+                for d in _VENDOR_DOMAINS
+            },
+            schema_versions_final=dict(self._state.schema_versions),
+            max_turns=self._state.max_turns,
+            turns_used=len(self._state.actions),
+            terminated_by=cast(
+                "Literal['SUBMIT','ABORT','TIMEOUT','ANTI_HACK']", terminated_by
+            ),
+            stage=self._config.curriculum_stage,
+        )
+        self._episode = episode
+        self._rewards = self._compute_rewards(episode)
+
+    @staticmethod
+    def _compute_rewards(episode: Episode) -> Any:
+        import importlib
+
+        try:
+            mod = importlib.import_module("cells.step_08_rewards")
+        except ImportError as exc:
+            raise RewardComputationError(
+                f"rewards module unavailable: {exc}"
+            ) from exc
+        compute = getattr(mod, "compute_rewards", None)
+        if compute is None:
+            raise RewardComputationError(
+                "cells.step_08_rewards has no compute_rewards"
+            )
+        try:
+            return compute(episode)
+        except Exception as exc:
+            raise RewardComputationError(str(exc)) from exc
+
+    # -- observation builder -------------------------------------------------
+
+    def _build_observation(self) -> DriftCallObservation:
+        assert self._state is not None
+        st = self._state
+        if st.turn == 0:
+            last_transcript = st.goal.seed_utterance
+            last_lang = st.goal.language
+            last_confidence = 1.0
+        else:
+            last_transcript = st.goal.seed_utterance
+            last_lang = st.goal.language
+            last_confidence = 1.0
+
+        return DriftCallObservation(
+            turn=st.turn,
+            goal=st.goal,
+            last_transcript=last_transcript,
+            last_lang=last_lang,
+            last_confidence=last_confidence,
+            tool_results=self._tool_results,
+            drift_log=st.drift_fired,
+            budget_remaining=max(0, st.max_turns - st.turn),
+            available_tools=self._available_tools(),
+        )
+
+
+__all__ = [
+    "ASREngine",
+    "AudioPipelineError",
+    "ConcurrentStepError",
+    "DriftCallEnv",
+    "DriftCallEnvError",
+    "DriftInjectionError",
+    "DriftScheduler",
+    "EnvClosedError",
+    "EnvConfig",
+    "EnvNotReadyError",
+    "Episode",
+    "EpisodeAlreadyTerminalError",
+    "EpisodeNotTerminalError",
+    "InvalidActionError",
+    "InvalidConfigError",
+    "RewardComputationError",
+    "TTSEngine",
+    "UnknownDomainError",
+    "UnknownToolError",
+]

cells/step_11_smoke_env.md

@@ -0,0 +1,8 @@
+# Cell 11 — DriftCallEnv smoke test
+
+Boots `DriftCallEnv` with a Stage-1 English airline configuration, runs one
+episode (search → book → submit, confidence=0.8), computes rewards via
+`compute_rewards`, and prints a compact summary table to stdout. Per
+`docs/modules/env.md` §8.1 (happy-path trace) and `DESIGN.md` §16.A.2 — this
+is the first end-to-end sanity check that every cell from 04 → 10 composes
+into a working episode.

cells/step_11_smoke_env.py

@@ -0,0 +1,164 @@
+"""Cell 11 — DriftCallEnv smoke episode.
+
+End-to-end smoke test that boots ``DriftCallEnv`` (cell 10) with a Stage-1
+English airline configuration, runs one short episode, and prints the
+resulting reward breakdown. Mirrors ``DESIGN.md`` §16.A.2 and
+``docs/modules/env.md`` §8.1.
+
+The cell exposes two public callables:
+
+* :func:`run_smoke_episode` — pure helper that returns a :class:`SmokeResult`
+  containing the (terminated) env, observation, and rewards. Useful from
+  tests.
+* :func:`main` — notebook-cell entry point; prints a small summary table to
+  stdout and returns the same :class:`SmokeResult`.
+
+The cell never imports ``torch``, audio engines, or any LLM stack — it is
+text-only and deterministic.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from cells.step_04_models import (
+    ActionType,
+    DriftCallAction,
+    DriftCallObservation,
+)
+from cells.step_10_env import DriftCallEnv
+
+if TYPE_CHECKING:  # pragma: no cover — typing only
+    from cells.step_08_rewards import Rewards
+
+
+SMOKE_SEED: int = 42
+SMOKE_CONFIDENCE: float = 0.8
+
+
+@dataclass(frozen=True)
+class SmokeResult:
+    """Container returned by :func:`run_smoke_episode`."""
+
+    env: DriftCallEnv
+    final_observation: DriftCallObservation
+    rewards: Rewards
+
+
+def _build_env() -> DriftCallEnv:
+    """Construct the canonical Stage-1, English-only, no-audio env."""
+    return DriftCallEnv(
+        config={
+            "curriculum_stage": 1,
+            "language_weights": {"en": 1.0},
+            "audio_boundary_enabled": False,
+        },
+    )
+
+
+def _pick_search_tool(obs: DriftCallObservation) -> str:
+    """Return the first ``<domain>.search``-style tool exposed for the goal."""
+    domain = obs.goal.domain
+    for tool in obs.available_tools:
+        if tool == f"{domain}.search":
+            return tool
+    # Fall back to any tool in the domain if no explicit search action exists.
+    for tool in obs.available_tools:
+        if tool.startswith(f"{domain}."):
+            return tool
+    raise RuntimeError(f"no tools available for domain {domain!r}")
+
+
+def _pick_book_tool(obs: DriftCallObservation) -> str | None:
+    """Return the first ``<domain>.book``/``<domain>.order``/etc. tool, if any."""
+    domain = obs.goal.domain
+    for verb in ("book", "order", "reserve", "create"):
+        candidate = f"{domain}.{verb}"
+        if candidate in obs.available_tools:
+            return candidate
+    return None
+
+
+def run_smoke_episode(seed: int = SMOKE_SEED) -> SmokeResult:
+    """Run a single Stage-1 airline-style episode and return the rewards.
+
+    Action sequence:
+
+    1. ``TOOL_CALL`` to the domain's ``search`` endpoint (no args — vendors
+       are tolerant of empty args at v1).
+    2. ``TOOL_CALL`` to the domain's ``book``/``order`` endpoint, if exposed.
+    3. ``SUBMIT`` with ``confidence=0.8``.
+    """
+    env = _build_env()
+    obs = env.reset(seed=seed)
+
+    obs = env.step(
+        DriftCallAction(
+            action_type=ActionType.TOOL_CALL,
+            tool_name=_pick_search_tool(obs),
+            tool_args={},
+            rationale="smoke: discover candidates",
+        ),
+    )
+
+    book_tool = _pick_book_tool(obs)
+    if book_tool is not None and not env.done():
+        obs = env.step(
+            DriftCallAction(
+                action_type=ActionType.TOOL_CALL,
+                tool_name=book_tool,
+                tool_args={},
+                rationale="smoke: commit booking",
+            ),
+        )
+
+    if not env.done():
+        obs = env.step(
+            DriftCallAction(
+                action_type=ActionType.SUBMIT,
+                confidence=SMOKE_CONFIDENCE,
+                message="smoke episode complete",
+                rationale="smoke: terminate",
+            ),
+        )
+
+    rewards = env.rewards()
+    return SmokeResult(env=env, final_observation=obs, rewards=rewards)
+
+
+def _format_summary(result: SmokeResult) -> str:
+    r = result.rewards
+    ep = result.env.episode()
+    lines = [
+        "=== DriftCall smoke episode ===",
+        f"  episode_id    : {ep.episode_id}",
+        f"  domain        : {ep.goal.domain}",
+        f"  language      : {ep.goal.language}",
+        f"  terminated_by : {ep.terminated_by}",
+        f"  turns_used    : {ep.turns_used} / {ep.max_turns}",
+        "  --- rewards ---",
+        f"  r1 (task)        : {r.r1:.3f}",
+        f"  r2 (drift)       : {r.r2:.3f}",
+        f"  r3 (constraints) : {r.r3:.3f}",
+        f"  r4 (format)      : {r.r4:.3f}",
+        f"  r5 (anti-hack)   : {r.r5:.3f}",
+        f"  reward (final)   : {r.reward:.3f}",
+    ]
+    return "\n".join(lines)
+
+
+def main() -> SmokeResult:
+    """Run the smoke episode and print a summary table to stdout."""
+    result = run_smoke_episode()
+    print(_format_summary(result))
+    return result
+
+
+__all__ = [
+    "SMOKE_CONFIDENCE",
+    "SMOKE_SEED",
+    "SmokeResult",
+    "main",
+    "run_smoke_episode",
+]

cells/step_12_gemma_boot.md

@@ -0,0 +1,3 @@
+# Step 12 — Gemma 3n E2B Boot
+
+Loads `unsloth/gemma-3n-E2B-it` via `unsloth.FastModel` in 4-bit Dynamic NF4 with hardware-aware precision (FP16 on V100, BF16 on H100), attaches LoRA adapters (r=16, α=32, vision towers frozen, language + attention + MLP trainable), and asserts the first parameter's dtype matches the target hardware — the mandatory dtype-slippage halt from `docs/modules/training.md §3.1`. Unsloth/torch imports are lazy so this cell loads on CPU-only machines; heavy work happens only when `boot_gemma()` is called with a real GPU.

cells/step_12_gemma_boot.py

@@ -0,0 +1,204 @@
+"""Gemma 3n E2B boot via Unsloth FastModel (docs/modules/training.md §3.1).
+
+Contract:
+  - Base model: ``unsloth/gemma-3n-E2B-it`` (4-bit Dynamic
+    NF4 quantization).
+  - Precision: hardware-aware.
+      V100 (sm_70) — explicit FP16 (``dtype=torch.float16``); Gemma 3n is
+      BF16-native, so we force FP16 on V100 to avoid BF16 software-emulation
+      slowdown / numerical instability.
+      H100 (sm_90) — BF16 (``dtype=torch.bfloat16``); uses native tensor cores.
+  - LoRA: r=16, α=32, dropout=0.05, vision towers frozen, language + attention
+    + MLP trainable via Unsloth's multimodal API (``finetune_vision_layers=False,
+    finetune_language_layers=True, finetune_attention_modules=True,
+    finetune_mlp_modules=True``), Unsloth gradient checkpointing,
+    ``random_state=3407``.
+  - V100 halt: ``next(model.parameters()).dtype`` MUST be ``torch.float16``
+    after FP16 load; any BF16 parameter triggers :class:`BF16SlippageError`
+    before optimizer build.
+  - H100 halt: ``next(model.parameters()).dtype`` MUST be ``torch.bfloat16``
+    after BF16 load; any FP16 parameter triggers :class:`FP16SlippageError`
+    before optimizer build.
+
+Heavy imports (``unsloth``, ``torch``) are deferred inside functions so this
+cell loads on CPU-only CI runners where Unsloth is not installed. Tests mock
+``FastModel.from_pretrained`` and ``FastModel.get_peft_model``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+BASE_MODEL_ID: str = "unsloth/gemma-3n-E2B-it"
+MAX_SEQ_LENGTH: int = 4096
+LORA_R: int = 16
+LORA_ALPHA: int = 32
+LORA_DROPOUT: float = 0.05
+LORA_RANDOM_STATE: int = 3407
+
+# Gemma 3n multimodal LoRA flags — vision/audio towers stay frozen so GRPO
+# trains only the language stack (Unsloth Gemma 3N notebook §fine-tune).
+FINETUNE_VISION_LAYERS: bool = False
+FINETUNE_LANGUAGE_LAYERS: bool = True
+FINETUNE_ATTENTION_MODULES: bool = True
+FINETUNE_MLP_MODULES: bool = True
+
+HardwareT = Literal["v100", "h100"]
+ALLOWED_HARDWARE: tuple[HardwareT, ...] = ("v100", "h100")
+
+
+class BF16SlippageError(AssertionError):
+    """Raised when the loaded model has any BF16 parameter on V100.
+
+    V100 (sm_70) lacks BF16 tensor cores. Silent BF16 via software emulation
+    causes ~10x slowdown plus numerical-instability patterns in
+    ``docs/modules/training.md §7a``. Halt before the optimizer is built.
+    """
+
+
+class FP16SlippageError(AssertionError):
+    """Raised when the loaded model has any FP16 parameter on H100.
+
+    H100 (sm_90) has native BF16 tensor cores. Running FP16 on H100 means
+    leaving native hardware capability unused and may cause gradient underflow
+    at large batch sizes. Halt before the optimizer is built.
+    """
+
+
+@dataclass(frozen=True)
+class BootConfig:
+    """Arguments to :func:`boot_gemma`. Frozen per DriftCall immutability rule."""
+
+    base_model_id: str = BASE_MODEL_ID
+    max_seq_length: int = MAX_SEQ_LENGTH
+    load_in_4bit: bool = True
+    lora_r: int = LORA_R
+    lora_alpha: int = LORA_ALPHA
+    lora_dropout: float = LORA_DROPOUT
+    lora_random_state: int = LORA_RANDOM_STATE
+    finetune_vision_layers: bool = FINETUNE_VISION_LAYERS
+    finetune_language_layers: bool = FINETUNE_LANGUAGE_LAYERS
+    finetune_attention_modules: bool = FINETUNE_ATTENTION_MODULES
+    finetune_mlp_modules: bool = FINETUNE_MLP_MODULES
+    use_gradient_checkpointing: str = "unsloth"
+    hardware: HardwareT = "v100"
+
+
+def assert_dtype_for_hardware(model: Any, hardware: HardwareT) -> None:
+    """Assert the first parameter dtype matches the expected precision for hardware.
+
+    V100 must be ``torch.float16``; raises :class:`BF16SlippageError` otherwise.
+    H100 must be ``torch.bfloat16``; raises :class:`FP16SlippageError` otherwise.
+    Called once at ``boot_gemma`` entry, before any LoRA attach or optimizer build.
+    """
+    import torch
+
+    params_iter = model.parameters()
+    try:
+        first_param = next(params_iter)
+    except StopIteration as exc:  # pragma: no cover - defensive
+        raise BF16SlippageError(
+            "Model has no parameters; cannot verify dtype."
+        ) from exc
+
+    dtype = first_param.dtype
+    if hardware == "v100":
+        if dtype != torch.float16:
+            raise BF16SlippageError(
+                f"BF16 slipped through: V100 unsafe. "
+                f"next(model.parameters()).dtype == {dtype}, expected torch.float16. "
+                f"Root cause: Unsloth auto-picked BF16 despite dtype=torch.float16 kwarg. "
+                f"Halt training; do NOT proceed on V100."
+            )
+    else:  # h100
+        if dtype != torch.bfloat16:
+            raise FP16SlippageError(
+                f"FP16 slipped through: H100 should use BF16. "
+                f"next(model.parameters()).dtype == {dtype}, expected torch.bfloat16. "
+                f"Root cause: dtype kwarg may have forced FP16 on H100. "
+                f"Halt training; do NOT proceed on H100 with FP16."
+            )
+
+
+def assert_fp16_dtype(model: Any) -> None:
+    """Assert the first trainable parameter is torch.float16 (V100 safety).
+
+    Thin wrapper around :func:`assert_dtype_for_hardware` for backwards
+    compatibility with call sites that predate the hardware-aware API.
+    Raises :class:`BF16SlippageError` with the halt message from
+    ``docs/modules/training.md §3.1``.
+    """
+    assert_dtype_for_hardware(model, "v100")
+
+
+def boot_gemma(config: BootConfig | None = None) -> tuple[Any, Any]:
+    """Load Gemma 3n E2B in 4-bit + attach LoRA; return (model, tokenizer).
+
+    Steps (training.md §3.1):
+      1. ``FastModel.from_pretrained(base_model_id, max_seq_length=...,
+         load_in_4bit=True, dtype=torch.float16)`` on V100
+         or ``dtype=torch.bfloat16`` on H100.
+      2. ``assert_dtype_for_hardware(model, hardware)`` — raises
+         :class:`BF16SlippageError` or :class:`FP16SlippageError` if the dtype
+         does not match the hardware.
+      3. ``FastModel.get_peft_model(model, r=16, lora_alpha=32,
+         finetune_vision_layers=False, finetune_language_layers=True,
+         finetune_attention_modules=True, finetune_mlp_modules=True,
+         use_gradient_checkpointing="unsloth", random_state=3407)``.
+      4. Return ``(peft_model, tokenizer)``.
+
+    All heavy imports are lazy so the module is importable on CPU-only CI.
+    """
+    cfg = config if config is not None else BootConfig()
+
+    import torch
+    from unsloth import FastModel
+
+    dtype = torch.float16 if cfg.hardware == "v100" else torch.bfloat16
+
+    model, tokenizer = FastModel.from_pretrained(
+        cfg.base_model_id,
+        max_seq_length=cfg.max_seq_length,
+        load_in_4bit=cfg.load_in_4bit,
+        dtype=dtype,
+    )
+
+    assert_dtype_for_hardware(model, cfg.hardware)
+
+    peft_model = FastModel.get_peft_model(
+        model,
+        r=cfg.lora_r,
+        lora_alpha=cfg.lora_alpha,
+        lora_dropout=cfg.lora_dropout,
+        finetune_vision_layers=cfg.finetune_vision_layers,
+        finetune_language_layers=cfg.finetune_language_layers,
+        finetune_attention_modules=cfg.finetune_attention_modules,
+        finetune_mlp_modules=cfg.finetune_mlp_modules,
+        use_gradient_checkpointing=cfg.use_gradient_checkpointing,
+        random_state=cfg.lora_random_state,
+    )
+
+    return peft_model, tokenizer
+
+
+__all__ = [
+    "ALLOWED_HARDWARE",
+    "BASE_MODEL_ID",
+    "BF16SlippageError",
+    "BootConfig",
+    "FINETUNE_ATTENTION_MODULES",
+    "FINETUNE_LANGUAGE_LAYERS",
+    "FINETUNE_MLP_MODULES",
+    "FINETUNE_VISION_LAYERS",
+    "FP16SlippageError",
+    "HardwareT",
+    "LORA_ALPHA",
+    "LORA_DROPOUT",
+    "LORA_R",
+    "LORA_RANDOM_STATE",
+    "MAX_SEQ_LENGTH",
+    "assert_dtype_for_hardware",
+    "assert_fp16_dtype",
+    "boot_gemma",
+]

cells/step_13_grpo_config.md

@@ -0,0 +1,3 @@
+# Step 13 — GRPO Config + Reward Wiring
+
+Builds a TRL `GRPOConfig` matching `docs/modules/training.md §2.4` exactly — `use_bias_correction_kl=True`, FP16, gradient-checkpointing, `beta=0.04`, `per_device_train_batch_size=1`, `num_generations ∈ {4, 8}` with `grad_accum` flipped so effective rollouts/update stays at 32. Also provides the TRL-0.23-compatible `reward_fn(prompts, completions, *, _meta, episodes, **kwargs)` that delegates to `compute_rewards` pure function and returns list-of-floats in `[0, 1]` rounded to 3dp. No reward normalization pre-GRPO (training.md §3.2).

cells/step_13_grpo_config.py

@@ -0,0 +1,508 @@
+"""GRPOConfig builder + reward_fn wiring (docs/modules/training.md §2.4, §2.3).
+
+Two public entry points:
+
+- :func:`build_grpo_config(stage, *, num_generations=8, resume_output_dir=None)`
+  returns a TRL ``GRPOConfig`` whose fields match training.md §2.4 verbatim.
+  Invariants (asserted post-construction): ``use_bias_correction_kl is True``,
+  ``fp16 is True``, ``gradient_checkpointing is True``,
+  ``per_device_train_batch_size == 1``, ``num_generations in {4, 8}``,
+  ``num_generations * gradient_accumulation_steps == 32``, ``beta == 0.04``,
+  ``max_prompt_length == 1024``, ``max_completion_length == 2048``,
+  ``warmup_ratio == (0.1 if stage == 1 else 0.0)``.
+
+- :func:`reward_fn(prompts, completions, *, _meta, episodes, **kwargs)` is the
+  TRL-0.23 reward contract used by ``DriftCallGRPOTrainer``. It is a pure
+  delegating wrapper over ``cells.step_08_rewards.compute_rewards`` (see
+  docs/modules/rewards.md §3.1 purity contract). No pre-normalization,
+  no RNG, no I/O.
+
+TRL is imported lazily inside ``build_grpo_config`` so this cell loads on
+CPU-only CI. ``compute_rewards`` is imported lazily so step_08 landing after
+step_13 does not cascade-break the import graph.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+StageT = Literal[1, 2, 3]
+HardwareT = Literal["v100", "h100"]
+
+
+LEARNING_RATE: float = 5e-6
+ADAM_BETA1: float = 0.9
+ADAM_BETA2: float = 0.99
+WEIGHT_DECAY: float = 0.01
+LR_SCHEDULER_TYPE: str = "cosine"
+
+# V100 path (default) — fp16 + 8-bit paged AdamW (sm_70 safe).
+OPTIM_V100: str = "paged_adamw_8bit"
+# H100 path — bf16 + fused torch AdamW (sm_90 tensor cores).
+OPTIM_H100: str = "adamw_torch_fused"
+# For backwards compatibility with callers that read ``OPTIM`` directly.
+OPTIM: str = OPTIM_V100
+# Kernel request passed to the model at load time on H100.
+H100_ATTN_IMPLEMENTATION: str = "flash_attention_3"
+ALLOWED_HARDWARE: tuple[HardwareT, ...] = ("v100", "h100")
+
+PER_DEVICE_TRAIN_BATCH_SIZE: int = 1
+EFFECTIVE_ROLLOUTS_PER_UPDATE: int = 32
+
+DEFAULT_NUM_GENERATIONS: int = 8
+ALLOWED_NUM_GENERATIONS: tuple[int, ...] = (4, 8)
+
+MAX_PROMPT_LENGTH: int = 1024
+MAX_COMPLETION_LENGTH: int = 2048
+
+BETA_KL: float = 0.04
+
+SAMPLING_TEMPERATURE: float = 0.9
+SAMPLING_TOP_P: float = 0.95
+
+LOGGING_STEPS: int = 5
+SAVE_STEPS: int = 50
+SAVE_TOTAL_LIMIT: int = 10
+
+REPORT_TO: str = "wandb"
+
+WARMUP_RATIO_STAGE1: float = 0.1
+WARMUP_RATIO_STAGE2_3: float = 0.0
+
+# WandB integration (training.md §3.3.3 — env-var contract).
+WANDB_PROJECT_DEFAULT: str = "driftcall"
+WANDB_ENTITY_DEFAULT: str | None = None
+WANDB_RUN_NAME_TEMPLATE: str = "driftcall-stage{stage}-seed{seed}-{timestamp}"
+WANDB_MODE_DEFAULT: str = "online"
+
+
+@dataclass(frozen=True)
+class _ConfigInvariants:
+    """Invariant bundle returned by :func:`assert_config_invariants`.
+
+    Used by tests to verify exact field values without re-parsing the
+    ``GRPOConfig`` object.
+    """
+
+    stage: StageT
+    num_generations: int
+    gradient_accumulation_steps: int
+    warmup_ratio: float
+    beta: float
+    max_prompt_length: int
+    max_completion_length: int
+    per_device_train_batch_size: int
+    use_bias_correction_kl: bool
+    fp16: bool
+    gradient_checkpointing: bool
+    report_to: str
+    run_name: str
+    output_dir: str
+
+
+def _derive_grad_accum(num_generations: int) -> int:
+    """Return grad_accum so that G*grad_accum == 32 (training.md §7b)."""
+    return 8 if num_generations == 4 else 4
+
+
+def _warmup_ratio_for_stage(stage: StageT) -> float:
+    """One continuous cosine schedule across 500 steps — only stage-1 warms."""
+    return WARMUP_RATIO_STAGE1 if stage == 1 else WARMUP_RATIO_STAGE2_3
+
+
+def _validate_num_generations(num_generations: int) -> None:
+    if num_generations not in ALLOWED_NUM_GENERATIONS:
+        raise AssertionError(
+            f"num_generations in {{4, 8}} required; got {num_generations}"
+        )
+
+
+def _validate_stage(stage: int) -> None:
+    if stage not in (1, 2, 3):
+        raise AssertionError(f"stage in {{1, 2, 3}} required; got {stage}")
+
+
+def _validate_hardware(hardware: str) -> None:
+    if hardware not in ALLOWED_HARDWARE:
+        raise AssertionError(
+            f"hardware in {ALLOWED_HARDWARE} required; got {hardware!r}"
+        )
+
+
+def build_grpo_config(
+    stage: StageT,
+    *,
+    num_generations: int = DEFAULT_NUM_GENERATIONS,
+    resume_output_dir: Path | None = None,
+    hardware: HardwareT = "v100",
+    max_steps: int = -1,
+) -> Any:
+    """Build a TRL ``GRPOConfig`` matching training.md §2.4 exactly.
+
+    Validates ``num_generations in {4, 8}`` before import so CPU-only
+    tests can trigger the assertion without TRL installed.
+
+    ``max_steps`` maps to TRL's ``max_steps`` (default -1 = run until dataset
+    exhausted; pass the stage step count for a fixed-step curriculum).
+    """
+    _validate_stage(stage)
+    _validate_num_generations(num_generations)
+    _validate_hardware(hardware)
+
+    warmup_ratio = _warmup_ratio_for_stage(stage)
+    grad_accum = _derive_grad_accum(num_generations)
+    output_dir = str(resume_output_dir) if resume_output_dir is not None else f"checkpoints/stage{stage}"
+    run_name = f"driftcall-stage{stage}"
+
+    # Hardware-specific knobs — V100 stays fp16 + 8-bit paged AdamW, H100
+    # switches to bf16 + fused torch AdamW + flash_attention_3 (training.md §3.1).
+    if hardware == "h100":
+        fp16_flag = False
+        bf16_flag = True
+        optim_choice = OPTIM_H100
+        attn_implementation: str | None = H100_ATTN_IMPLEMENTATION
+    else:
+        fp16_flag = True
+        bf16_flag = False
+        optim_choice = OPTIM_V100
+        attn_implementation = None
+
+    import inspect
+
+    from trl import GRPOConfig
+
+    _grpo_params = set(inspect.signature(GRPOConfig.__init__).parameters)
+
+    extra_kwargs: dict[str, Any] = {}
+    # attn_implementation was a GRPOConfig param in TRL ≤0.23; removed in 0.24.
+    if attn_implementation is not None and "attn_implementation" in _grpo_params:
+        extra_kwargs["attn_implementation"] = attn_implementation
+    # use_bias_correction_kl was introduced in TRL 0.23 and removed in TRL 0.24.
+    if "use_bias_correction_kl" in _grpo_params:
+        extra_kwargs["use_bias_correction_kl"] = True
+
+    # TRL 0.24+ requires generation_batch_size to be divisible by
+    # num_generations. Default (per_device * grad_accum) may be smaller.
+    # Pin it to num_generations so exactly one group is generated per step.
+    if "generation_batch_size" in _grpo_params:
+        extra_kwargs.setdefault("generation_batch_size", num_generations)
+
+    config = GRPOConfig(
+        learning_rate=LEARNING_RATE,
+        adam_beta1=ADAM_BETA1,
+        adam_beta2=ADAM_BETA2,
+        weight_decay=WEIGHT_DECAY,
+        warmup_ratio=warmup_ratio,
+        lr_scheduler_type=LR_SCHEDULER_TYPE,
+        optim=optim_choice,
+        per_device_train_batch_size=PER_DEVICE_TRAIN_BATCH_SIZE,
+        gradient_accumulation_steps=grad_accum,
+        num_generations=num_generations,
+        max_prompt_length=MAX_PROMPT_LENGTH,
+        max_completion_length=MAX_COMPLETION_LENGTH,
+        max_steps=max_steps,
+        beta=BETA_KL,
+        temperature=SAMPLING_TEMPERATURE,
+        top_p=SAMPLING_TOP_P,
+        fp16=fp16_flag,
+        bf16=bf16_flag,
+        gradient_checkpointing=True,
+        logging_steps=LOGGING_STEPS,
+        save_steps=SAVE_STEPS,
+        save_total_limit=SAVE_TOTAL_LIMIT,
+        output_dir=output_dir,
+        report_to=REPORT_TO,
+        run_name=run_name,
+        **extra_kwargs,
+    )
+
+    assert_config_invariants(
+        config, stage=stage, num_generations=num_generations, hardware=hardware,
+    )
+    return config
+
+
+def assert_config_invariants(
+    config: Any,
+    *,
+    stage: StageT,
+    num_generations: int,
+    hardware: HardwareT | None = None,
+) -> _ConfigInvariants:
+    """Post-construction field checks — training.md §2.4 invariants.
+
+    Returns a frozen :class:`_ConfigInvariants` snapshot so callers (tests)
+    can introspect without re-reading the mutable TRL config object.
+
+    When ``hardware`` is ``None`` it is auto-detected from the precision
+    flags on ``config`` (``bf16=True`` → ``"h100"``, else ``"v100"``).
+    """
+    if hardware is None:
+        hardware = "h100" if getattr(config, "bf16", False) else "v100"
+    _validate_hardware(hardware)
+    # use_bias_correction_kl existed in TRL 0.23 only; TRL 0.24 removed it.
+    # Assert it only when the attr is present on the config object.
+    if hasattr(config, "use_bias_correction_kl"):
+        if getattr(config, "use_bias_correction_kl", None) is not True:
+            raise AssertionError(
+                "use_bias_correction_kl must be True (TRL issue #4637; training.md §3.3)"
+            )
+    if hardware == "v100":
+        if getattr(config, "fp16", None) is not True:
+            raise AssertionError("fp16 must be True on V100 (training.md §3.1)")
+        if getattr(config, "bf16", False) is True:
+            raise AssertionError("bf16 must be False on V100 (training.md §3.1)")
+    else:  # hardware == "h100"
+        if getattr(config, "bf16", None) is not True:
+            raise AssertionError("bf16 must be True on H100 (training.md §3.1)")
+        if getattr(config, "fp16", False) is True:
+            raise AssertionError("fp16 must be False on H100 (training.md §3.1)")
+        # attn_implementation was a GRPOConfig field in TRL ≤0.23; removed in 0.24.
+        if hasattr(config, "attn_implementation"):
+            if getattr(config, "attn_implementation", None) != H100_ATTN_IMPLEMENTATION:
+                raise AssertionError(
+                    f"attn_implementation must be {H100_ATTN_IMPLEMENTATION!r} on H100"
+                )
+    if getattr(config, "gradient_checkpointing", None) is not True:
+        raise AssertionError("gradient_checkpointing must be True")
+    if config.per_device_train_batch_size != PER_DEVICE_TRAIN_BATCH_SIZE:
+        raise AssertionError(
+            f"per_device_train_batch_size must be {PER_DEVICE_TRAIN_BATCH_SIZE}"
+        )
+    if config.num_generations != num_generations:
+        raise AssertionError(
+            f"num_generations mismatch: config has {config.num_generations}, expected {num_generations}"
+        )
+    expected_grad_accum = _derive_grad_accum(num_generations)
+    if config.gradient_accumulation_steps != expected_grad_accum:
+        raise AssertionError(
+            f"gradient_accumulation_steps must be {expected_grad_accum} when "
+            f"num_generations == {num_generations}"
+        )
+    product = config.num_generations * config.gradient_accumulation_steps
+    if product != EFFECTIVE_ROLLOUTS_PER_UPDATE:
+        raise AssertionError(
+            f"num_generations * gradient_accumulation_steps must be "
+            f"{EFFECTIVE_ROLLOUTS_PER_UPDATE}; got {product}"
+        )
+    expected_warmup = _warmup_ratio_for_stage(stage)
+    if config.warmup_ratio != expected_warmup:
+        raise AssertionError(
+            f"warmup_ratio must be {expected_warmup} for stage {stage}; "
+            f"got {config.warmup_ratio}"
+        )
+    if config.beta != BETA_KL:
+        raise AssertionError(f"beta must be {BETA_KL}; got {config.beta}")
+    if config.max_prompt_length != MAX_PROMPT_LENGTH:
+        raise AssertionError(f"max_prompt_length must be {MAX_PROMPT_LENGTH}")
+    if config.max_completion_length != MAX_COMPLETION_LENGTH:
+        raise AssertionError(
+            f"max_completion_length must be {MAX_COMPLETION_LENGTH}"
+        )
+    # TRL 0.24 normalises report_to to a list; earlier versions kept it a string.
+    _report_to = config.report_to
+    if isinstance(_report_to, list):
+        _report_to_check = _report_to == [REPORT_TO]
+    else:
+        _report_to_check = _report_to == REPORT_TO
+    if not _report_to_check:
+        raise AssertionError(f"report_to must be {REPORT_TO!r} (or [{REPORT_TO!r}]); got {config.report_to!r}")
+    expected_run_name = f"driftcall-stage{stage}"
+    if config.run_name != expected_run_name:
+        raise AssertionError(
+            f"run_name must be {expected_run_name!r}; got {config.run_name!r}"
+        )
+
+    return _ConfigInvariants(
+        stage=stage,
+        num_generations=config.num_generations,
+        gradient_accumulation_steps=config.gradient_accumulation_steps,
+        warmup_ratio=config.warmup_ratio,
+        beta=config.beta,
+        max_prompt_length=config.max_prompt_length,
+        max_completion_length=config.max_completion_length,
+        per_device_train_batch_size=config.per_device_train_batch_size,
+        # use_bias_correction_kl was removed in TRL 0.24; default True for
+        # backwards compatibility with tests that read this field.
+        use_bias_correction_kl=getattr(config, "use_bias_correction_kl", True),
+        fp16=config.fp16,
+        gradient_checkpointing=config.gradient_checkpointing,
+        report_to=config.report_to[0] if isinstance(config.report_to, list) else config.report_to,
+        run_name=config.run_name,
+        output_dir=config.output_dir,
+    )
+
+
+def _clamp_unit(x: float) -> float:
+    if x < 0.0:
+        return 0.0
+    if x > 1.0:
+        return 1.0
+    return x
+
+
+def reward_fn(
+    prompts: list[str],
+    completions: list[str],
+    *,
+    _meta: list[dict[str, Any]],
+    episodes: list[Any],
+    **kwargs: Any,
+) -> list[float]:
+    """TRL-0.23-compatible reward function (training.md §2.3).
+
+    Contract:
+      - ``prompts``, ``completions``, ``_meta``, ``episodes`` all have the
+        same length G (num_generations).
+      - Delegates to ``compute_rewards`` per-episode; returns
+        ``[r.reward for r in rewards_list]`` with each value clamped to
+        ``[0, 1]`` and rounded to 3 decimals.
+      - No reward normalization pre-GRPO — group-relative advantage is
+        applied inside TRL (training.md §3.2, DESIGN.md §7.4).
+      - No RNG, no clock, no I/O (rewards.md §3.1).
+    """
+    if len(episodes) != len(prompts) or len(episodes) != len(completions):
+        raise ValueError(
+            f"prompts/completions/episodes length mismatch: "
+            f"{len(prompts)}, {len(completions)}, {len(episodes)}"
+        )
+    if len(_meta) != len(episodes):
+        raise ValueError(
+            f"_meta length {len(_meta)} != episodes length {len(episodes)}"
+        )
+
+    from cells.step_08_rewards import compute_rewards
+
+    out: list[float] = []
+    for ep in episodes:
+        rewards = compute_rewards(ep)
+        out.append(round(_clamp_unit(float(rewards.reward)), 3))
+    return out
+
+
+def init_wandb(
+    *,
+    stage: StageT,
+    seed: int,
+    h100_mode: bool = False,
+    enable_adaptive_kl: bool = True,
+    extra_config: dict[str, Any] | None = None,
+) -> Any:
+    """Initialize a WandB run for a training stage (training.md §3.3.3).
+
+    Override priority for credentials:
+      1. ``os.environ`` values set by the caller (highest)
+      2. ``cells._secrets.export_to_env()`` hardcoded fallback
+      3. None — caller must set ``WANDB_MODE=disabled`` or run will fail
+
+    Returns the active ``wandb.run`` object, or ``None`` when
+    ``WANDB_MODE`` resolves to ``"disabled"``. Idempotent — if a run is
+    already active for this process, returns it unchanged.
+    """
+    import os
+    import time
+
+    # Step 1: populate env from cells/_secrets.py if a key is missing.
+    try:
+        from cells._secrets import export_to_env
+
+        export_to_env()
+    except ImportError:
+        pass
+
+    mode = os.environ.get("WANDB_MODE", WANDB_MODE_DEFAULT).strip().lower()
+    if mode == "disabled":
+        return None
+
+    import wandb
+
+    if getattr(wandb, "run", None) is not None:
+        return wandb.run
+
+    project = os.environ.get("WANDB_PROJECT", WANDB_PROJECT_DEFAULT)
+    entity = os.environ.get("WANDB_ENTITY", WANDB_ENTITY_DEFAULT)
+    timestamp = time.strftime("%Y%m%d-%H%M%S")
+    run_name = WANDB_RUN_NAME_TEMPLATE.format(
+        stage=stage, seed=seed, timestamp=timestamp
+    )
+
+    tags = [
+        f"stage{stage}",
+        "gemma-3n-e2b",
+        "bf16" if h100_mode else "fp16",
+        "adaptive-kl" if enable_adaptive_kl else "static-kl",
+        f"seed{seed}",
+    ]
+
+    # Lazy LoRA constants — step_12 imports unsloth at module top, so guard
+    # against CPU-only CI environments where unsloth is unavailable.
+    try:
+        from cells.step_12_gemma_boot import LORA_ALPHA, LORA_DROPOUT, LORA_R
+    except ImportError:
+        LORA_R = 16
+        LORA_ALPHA = 32
+        LORA_DROPOUT = 0.05
+
+    # target_kl default matches AdaptiveKLCallback(target_kl=BETA_KL) in step_14.
+    config: dict[str, Any] = {
+        "stage": stage,
+        "seed": seed,
+        "h100_mode": h100_mode,
+        "adaptive_kl": enable_adaptive_kl,
+        "beta_initial": BETA_KL,
+        "target_kl": BETA_KL,
+        "learning_rate": LEARNING_RATE,
+        "num_generations": DEFAULT_NUM_GENERATIONS,
+        "max_prompt_length": MAX_PROMPT_LENGTH,
+        "max_completion_length": MAX_COMPLETION_LENGTH,
+        "lora_r": LORA_R,
+        "lora_alpha": LORA_ALPHA,
+        "lora_dropout": LORA_DROPOUT,
+    }
+    if extra_config:
+        config.update(extra_config)
+
+    init_kwargs: dict[str, Any] = {
+        "project": project,
+        "name": run_name,
+        "tags": tags,
+        "config": config,
+        "mode": mode,
+    }
+    if entity is not None:
+        init_kwargs["entity"] = entity
+
+    return wandb.init(**init_kwargs)
+
+
+__all__ = [
+    "ALLOWED_HARDWARE",
+    "ALLOWED_NUM_GENERATIONS",
+    "BETA_KL",
+    "DEFAULT_NUM_GENERATIONS",
+    "EFFECTIVE_ROLLOUTS_PER_UPDATE",
+    "H100_ATTN_IMPLEMENTATION",
+    "HardwareT",
+    "LEARNING_RATE",
+    "MAX_COMPLETION_LENGTH",
+    "MAX_PROMPT_LENGTH",
+    "OPTIM_H100",
+    "OPTIM_V100",
+    "PER_DEVICE_TRAIN_BATCH_SIZE",
+    "REPORT_TO",
+    "StageT",
+    "WANDB_ENTITY_DEFAULT",
+    "WANDB_MODE_DEFAULT",
+    "WANDB_PROJECT_DEFAULT",
+    "WANDB_RUN_NAME_TEMPLATE",
+    "WARMUP_RATIO_STAGE1",
+    "WARMUP_RATIO_STAGE2_3",
+    "assert_config_invariants",
+    "build_grpo_config",
+    "init_wandb",
+    "reward_fn",
+]

cells/step_14_custom_trainer.md

@@ -0,0 +1,7 @@
+# Step 14 — DriftCallGRPOTrainer + EpisodeDatasetAdapter
+
+Custom TRL subclass `DriftCallGRPOTrainer` that replaces the single-prompt / single-completion rollout phase with the DriftCall multi-turn env loop (training.md §3.2.3). Its `_generate_and_score_completions` override runs G parallel multi-turn episodes via a caller-provided `RolloutGroupFn`, then hands terminal frozen `Episode` objects plus raw completion strings to `reward_fn` (step_13). Advantage + KL + optimizer steps are inherited unchanged from `GRPOTrainer`.
+
+`EpisodeDatasetAdapter` is the stateless streaming iterator wired into `GRPOTrainer.train_dataset`. Each `__iter__` yield packages `{prompt, _meta}` where `_meta` carries `(goal, episode_seed, stage, language_weights)` — every scalar required by the rollout controller. Per-step record: one `task_generator.generate` call, one `apply_chat_template` render, monotonically increasing `episode_seed == stage_base_seed + step`.
+
+Both types defer `trl` + `torch` imports until construction so the module loads on CPU-only CI.

cells/step_14_custom_trainer.py

@@ -0,0 +1,526 @@
+"""Custom trainer + dataset adapter (docs/modules/training.md §2.2, §3.2.3).
+
+Two public types:
+
+- :class:`EpisodeDatasetAdapter` — stateless iterable feeding
+  ``GRPOTrainer.train_dataset``. Each ``__iter__`` tick yields
+  ``{"prompt": str, "_meta": {...}}`` where ``_meta`` carries the
+  ``GoalSpec``, the monotonically-derived ``episode_seed``, the curriculum
+  ``stage``, and the ``language_weights``. One call to
+  ``task_generator.generate`` per step; one call to
+  ``tokenizer.apply_chat_template(messages, tokenize=False,
+  add_generation_prompt=True)`` to render the prompt.
+
+- :class:`DriftCallGRPOTrainer` — ``GRPOTrainer`` subclass whose
+  ``_generate_and_score_completions`` override runs G multi-turn episodes
+  via a caller-provided ``RolloutGroupFn`` and plumbs the resulting
+  frozen ``Episode`` tuple into ``reward_fn`` (step_13) before handing the
+  G reward scalars + padded completions back to the inherited GRPO
+  advantage / KL / optimizer step path. **The inherited code path is
+  untouched** (training.md §3.2.3).
+
+``trl`` and ``torch`` are imported lazily. Pure-Python fallbacks for
+``_generate_and_score_completions`` are provided so the class shape
+can be verified on CPU-only CI.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, Literal, Protocol, cast
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable, Iterator
+
+from cells.step_13_grpo_config import BETA_KL
+
+PINNED_SYSTEM_PROMPT: str = (
+    "You are a concierge assistant. Use the provided tools. "
+    "Respond in the caller's language. Submit with calibrated confidence."
+)
+
+LanguageCode = Literal["hi", "ta", "kn", "en", "hinglish"]
+
+
+class EpisodeSampler(Protocol):
+    """Draws a ``GoalSpec`` for one prompt slot (training.md §2.2)."""
+
+    def __call__(self, step: int) -> Any: ...
+
+
+class EnvFactory(Protocol):
+    """Returns a fresh ``DriftCallEnv`` per rollout (training.md §3.2)."""
+
+    def __call__(self) -> Any: ...
+
+
+class RolloutGroupFn(Protocol):
+    """Runs G multi-turn rollouts sharing one goal.
+
+    Returns a tuple ``(episodes, completions)`` of length G each.
+    """
+
+    def __call__(
+        self,
+        *,
+        model: Any,
+        tokenizer: Any,
+        goal: Any,
+        episode_seed: int,
+        num_generations: int,
+        env_factory: EnvFactory,
+    ) -> tuple[tuple[Any, ...], tuple[str, ...]]: ...
+
+
+@dataclass(frozen=True)
+class AdapterRecord:
+    """Frozen view of one :class:`EpisodeDatasetAdapter` yield.
+
+    Tests consume this view rather than dict-typing ``_meta`` inline.
+    """
+
+    prompt: str
+    goal: Any
+    episode_seed: int
+    stage: Literal[1, 2, 3]
+    language_weights: dict[LanguageCode, float]
+
+
+def render_initial_prompt(tokenizer: Any, goal: Any) -> str:
+    """Render the turn-0 chat template (training.md §3.2.1).
+
+    Messages: pinned system prompt + ``goal.seed_utterance`` as the user
+    turn. ``add_generation_prompt=True`` tells Gemma to emit an assistant
+    turn. Tool schemas live in later turns so only these two messages
+    appear at ``step == 0``.
+    """
+    seed_utterance = getattr(goal, "seed_utterance", "")
+    messages: list[dict[str, str]] = [
+        {"role": "system", "content": PINNED_SYSTEM_PROMPT},
+        {"role": "user", "content": seed_utterance},
+    ]
+    result = tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+    )
+    return str(result)
+
+
+class EpisodeDatasetAdapter:
+    """Stateless streaming dataset (training.md §2.2).
+
+    Constructor signature matches training.md §2.2: a ``task_gen`` callable
+    accepting ``(seed, stage, language_weights)``, an ``env_factory``
+    producing fresh envs, the curriculum ``stage``, a ``stage_base_seed``
+    used to derive per-step ``episode_seed``, the per-language sampling
+    ``language_weights``, and the ``tokenizer`` used to render prompts.
+
+    Iteration is infinite — exactly one record per GRPO training step.
+    Step counter is local to ``__iter__`` so resume simply restarts from
+    whatever step TRL's ``resume_from_checkpoint`` restores.
+    """
+
+    def __init__(
+        self,
+        *,
+        task_gen: Callable[..., Any],
+        env_factory: EnvFactory,
+        stage: Literal[1, 2, 3],
+        stage_base_seed: int,
+        language_weights: dict[LanguageCode, float],
+        tokenizer: Any,
+    ) -> None:
+        self.task_gen = task_gen
+        self.env_factory = env_factory
+        self.stage: Literal[1, 2, 3] = stage
+        self.stage_base_seed = stage_base_seed
+        self.language_weights = dict(language_weights)
+        self.tokenizer = tokenizer
+
+    def _build_record(self, step: int) -> dict[str, Any]:
+        episode_seed = self.stage_base_seed + step
+        goal = self.task_gen(
+            seed=episode_seed,
+            stage=self.stage,
+            language_weights=self.language_weights,
+        )
+        prompt = render_initial_prompt(self.tokenizer, goal)
+        return {
+            "prompt": prompt,
+            "_meta": {
+                "goal": goal,
+                "episode_seed": episode_seed,
+                "stage": self.stage,
+                "language_weights": dict(self.language_weights),
+            },
+        }
+
+    def __iter__(self) -> Iterator[dict[str, Any]]:
+        step = 0
+        while True:
+            yield self._build_record(step)
+            step += 1
+
+    def __len__(self) -> int:
+        """Length sentinel for TRL 0.24+ ``RepeatSampler``.
+
+        The dataset is logically infinite (one record per GRPO step), but
+        TRL 0.24's ``RepeatSampler`` calls ``len(data_source)`` to size the
+        sampler. Returning a large finite number lets training proceed; the
+        actual step count is bounded by ``GRPOConfig.max_steps``.
+        """
+        return 1_000_000
+
+    def __getitem__(self, idx: int) -> dict[str, Any]:
+        """Map-style indexing for TRL 0.24+ DataLoader.
+
+        TRL 0.24 treats the train_dataset as a Map-style dataset and looks
+        records up by integer index. We honour the contract by deriving the
+        record purely from ``idx`` — the adapter is stateless so any index
+        produces a deterministic ``(prompt, _meta)`` pair for that step.
+        """
+        return self._build_record(int(idx))
+
+    def peek(self, step: int) -> AdapterRecord:
+        """Materialize the record at ``step`` without advancing iteration.
+
+        Used by tests (§1.2 U14–U18) to assert record shape at arbitrary
+        steps without consuming a generator.
+        """
+        rec = self._build_record(step)
+        meta = rec["_meta"]
+        return AdapterRecord(
+            prompt=rec["prompt"],
+            goal=meta["goal"],
+            episode_seed=meta["episode_seed"],
+            stage=meta["stage"],
+            language_weights=meta["language_weights"],
+        )
+
+
+def _import_grpo_trainer() -> type[Any]:
+    """Lazy import of ``trl.GRPOTrainer``; isolated for mocking in tests."""
+    from trl import GRPOTrainer
+
+    return cast("type[Any]", GRPOTrainer)
+
+
+def _make_driftcall_init(
+    base_cls: type[Any],
+) -> Callable[..., None]:
+    """Build an ``__init__`` bound to ``base_cls``; avoids super() recursion
+    when the returned class is itself further subclassed.
+
+    DriftCall-specific kwargs added on top of ``GRPOTrainer.__init__``:
+
+    - ``rollout_group_fn``, ``env_factory``, ``reward_fn_driftcall`` — the
+      multi-turn rollout override surface (see class docstring).
+    - ``enable_adaptive_kl`` (default ``True``) — auto-attach an
+      :class:`AdaptiveKLCallback` so β retargets to the measured KL each
+      logging tick (training.md §3.3.1). Set ``False`` to disable.
+    - ``adaptive_kl_target`` — override the default ``target_kl=BETA_KL``.
+    - ``adaptive_kl_kp`` — override the proportional gain.
+    - ``adaptive_kl_beta_min`` / ``adaptive_kl_beta_max`` — override clamp
+      bounds.
+    """
+
+    def _init(
+        self: Any,
+        *args: Any,
+        rollout_group_fn: RolloutGroupFn,
+        env_factory: EnvFactory,
+        reward_fn_driftcall: Callable[..., list[float]],
+        enable_adaptive_kl: bool = True,
+        adaptive_kl_target: float | None = None,
+        adaptive_kl_kp: float = DEFAULT_KP,
+        adaptive_kl_beta_min: float = DEFAULT_BETA_MIN,
+        adaptive_kl_beta_max: float = DEFAULT_BETA_MAX,
+        **kwargs: Any,
+    ) -> None:
+        # TRL 0.24 made ``reward_funcs`` a required arg on GRPOTrainer.
+        # Our custom ``_generate_and_score_completions`` short-circuits the
+        # base reward path entirely (calls ``reward_fn_driftcall`` directly),
+        # so the parent's ``reward_funcs`` value is never invoked. Pass a
+        # placeholder identity reward to satisfy the signature on TRL>=0.24.
+        if "reward_funcs" not in kwargs:
+            def _placeholder_reward(
+                completions: Any = None,
+                **_unused: Any,
+            ) -> list[float]:
+                n = len(completions) if completions is not None else 0
+                return [0.0] * n
+
+            kwargs["reward_funcs"] = [_placeholder_reward]
+        base_cls.__init__(self, *args, **kwargs)
+        self.rollout_group_fn = rollout_group_fn
+        self.env_factory = env_factory
+        self.reward_fn_driftcall = reward_fn_driftcall
+
+        if enable_adaptive_kl:
+            target = (
+                adaptive_kl_target if adaptive_kl_target is not None else BETA_KL
+            )
+            callback = AdaptiveKLCallback(
+                target_kl=target,
+                kp=adaptive_kl_kp,
+                beta_min=adaptive_kl_beta_min,
+                beta_max=adaptive_kl_beta_max,
+            )
+            self.adaptive_kl_callback = callback
+            add_callback = getattr(base_cls, "add_callback", None)
+            if callable(add_callback):
+                # Production path (TRL ≥ 0.23): register through the TRL
+                # callback handler so ``on_log`` fires alongside default
+                # loggers with the correct ``args``/``state``/``control``.
+                self.add_callback(callback)
+            else:
+                # Fallback: minimal bases in tests lack ``add_callback``.
+                # Keep a private list so callers can still invoke the hook.
+                if not hasattr(self, "_driftcall_callbacks"):
+                    self._driftcall_callbacks = []
+                self._driftcall_callbacks.append(callback)
+        else:
+            self.adaptive_kl_callback = None
+
+    return _init
+
+
+def _driftcall_generate_and_score_completions(
+    self: Any, inputs: list[dict[str, Any]]
+) -> dict[str, Any]:
+    """Run the multi-turn rollout, then call ``reward_fn``.
+
+    Expects ``inputs`` to carry one row per prompt slot with the
+    ``_meta`` dict produced by :class:`EpisodeDatasetAdapter`.
+    Returns a dict with keys ``episodes``, ``completions``, ``rewards``,
+    ``prompts`` — each length G (num_generations).
+    """
+    if not inputs:
+        raise ValueError("inputs must be a non-empty list")
+
+    row = inputs[0]
+    meta = row["_meta"]
+    prompt = row["prompt"]
+    goal = meta["goal"]
+    episode_seed = meta["episode_seed"]
+
+    num_generations = int(getattr(self.args, "num_generations", 8))
+    episodes, completions = self.rollout_group_fn(
+        model=self.model,
+        tokenizer=self.processing_class,
+        goal=goal,
+        episode_seed=episode_seed,
+        num_generations=num_generations,
+        env_factory=self.env_factory,
+    )
+
+    if len(episodes) != num_generations or len(completions) != num_generations:
+        raise ValueError(
+            f"rollout_group_fn produced {len(episodes)} episodes and "
+            f"{len(completions)} completions; expected {num_generations} each"
+        )
+
+    prompts = [prompt] * num_generations
+    metas = [dict(meta) for _ in range(num_generations)]
+    rewards = self.reward_fn_driftcall(
+        prompts=prompts,
+        completions=list(completions),
+        _meta=metas,
+        episodes=list(episodes),
+    )
+
+    return {
+        "episodes": episodes,
+        "completions": completions,
+        "rewards": rewards,
+        "prompts": prompts,
+    }
+
+
+def make_driftcall_grpo_trainer_cls(base_cls: type[Any] | None = None) -> type[Any]:
+    """Build the :class:`DriftCallGRPOTrainer` class bound to ``base_cls``.
+
+    Default ``base_cls`` is ``trl.GRPOTrainer`` (imported lazily). Tests
+    pass a stub base class so they can exercise the override path without
+    TRL installed.
+
+    GRPOTrainer subclass with multi-turn rollout override
+    (training.md §3.2.3). Construction adds three DriftCall-specific
+    kwargs over the standard ``GRPOTrainer.__init__``:
+
+    - ``rollout_group_fn``: :class:`RolloutGroupFn` running G multi-turn
+      episodes and returning ``(episodes, completions)``.
+    - ``env_factory``: :class:`EnvFactory` producing a fresh
+      ``DriftCallEnv`` per rollout.
+    - ``reward_fn_driftcall``: the step_13 ``reward_fn`` — called
+      directly with the frozen ``Episode`` tuple after rollout.
+
+    ``_generate_and_score_completions`` replaces the TRL default.
+    Advantage + KL + optimizer step paths are inherited unchanged.
+    """
+    resolved_base: type[Any] = (
+        base_cls if base_cls is not None else _import_grpo_trainer()
+    )
+    return type(
+        "DriftCallGRPOTrainer",
+        (resolved_base,),
+        {
+            "__init__": _make_driftcall_init(resolved_base),
+            "_generate_and_score_completions": _driftcall_generate_and_score_completions,
+            "__doc__": "GRPOTrainer subclass with multi-turn rollout override.",
+        },
+    )
+
+
+def driftcall_grpo_trainer_methods() -> tuple[str, ...]:
+    """Return the method names the subclass overrides (introspection helper).
+
+    Used by the shape test (U in §1.x) to verify the override surface.
+    """
+    return ("__init__", "_generate_and_score_completions")
+
+
+# ---------------------------------------------------------------------------
+# Adaptive KL controller (training.md §3.3 — retarget β from measured KL)
+# ---------------------------------------------------------------------------
+
+
+DEFAULT_BETA_MIN: float = 0.001
+DEFAULT_BETA_MAX: float = 1.0
+DEFAULT_KP: float = 2.0
+
+
+def _trainer_callback_base() -> type:
+    """Return ``transformers.TrainerCallback`` if importable, else ``object``.
+
+    Importing transformers lazily keeps step_14 importable on CPU-only CI
+    runners that don't have transformers installed.
+    """
+    try:
+        from transformers.trainer_callback import TrainerCallback
+        return TrainerCallback
+    except Exception:
+        return object
+
+
+class AdaptiveKLCallback(_trainer_callback_base()):  # type: ignore[misc]
+    """Retarget β each step based on the ratio of measured KL to ``target_kl``.
+
+    Proportional controller with symmetric log-space update:
+
+        err     = (kl - target_kl) / target_kl
+        new_beta = beta * exp(kp * err)
+        new_beta = clamp(new_beta, beta_min, beta_max)
+
+    When ``kl`` matches ``target_kl``, ``err == 0`` and β is left unchanged.
+    Safe on missing / NaN / non-numeric KL signals (no-op, no exception).
+
+    Inherits from :class:`transformers.trainer_callback.TrainerCallback` when
+    available (production path) so all the no-op callback events
+    (``on_train_begin``, ``on_step_begin``, etc.) come for free; falls back
+    to ``object`` on CPU-only CI when transformers is not installed.
+    """
+
+    def __init__(
+        self,
+        target_kl: float = BETA_KL,
+        *,
+        kp: float = DEFAULT_KP,
+        beta_min: float = DEFAULT_BETA_MIN,
+        beta_max: float = DEFAULT_BETA_MAX,
+    ) -> None:
+        if target_kl <= 0.0:
+            raise ValueError(f"target_kl must be > 0; got {target_kl}")
+        if beta_min <= 0.0 or beta_max <= 0.0:
+            raise ValueError(
+                f"beta bounds must be > 0; got min={beta_min}, max={beta_max}"
+            )
+        if beta_min > beta_max:
+            raise ValueError(
+                f"beta_min ({beta_min}) must be <= beta_max ({beta_max})"
+            )
+        self.target_kl = float(target_kl)
+        self.kp = float(kp)
+        self.beta_min = float(beta_min)
+        self.beta_max = float(beta_max)
+
+    def _coerce_kl(self, raw: Any) -> float | None:
+        """Return a finite float or ``None`` — propagates no-op on bad input."""
+        try:
+            value = float(raw)
+        except (TypeError, ValueError):
+            return None
+        if math.isnan(value) or math.isinf(value):
+            return None
+        return value
+
+    def _next_beta(self, beta: float, kl: float) -> tuple[float, bool, bool]:
+        """Return ``(new_beta, clamped_to_min, clamped_to_max)``."""
+        err = (kl - self.target_kl) / self.target_kl
+        # Clamp the exponent so extreme KL spikes don't overflow math.exp;
+        # the result is clamped anyway and exp(±50) easily saturates either bound.
+        exponent = max(-50.0, min(50.0, self.kp * err))
+        scaled = beta * math.exp(exponent)
+        if scaled <= self.beta_min:
+            return self.beta_min, True, False
+        if scaled >= self.beta_max:
+            return self.beta_max, False, True
+        return scaled, False, False
+
+    def on_log(
+        self,
+        args: Any,
+        state: Any,
+        control: Any,
+        *,
+        logs: dict[str, Any] | None = None,
+        **_kwargs: Any,
+    ) -> Any:
+        """TRL hook — called with every ``trainer.log(...)`` dict.
+
+        On a well-formed KL signal: mutates ``args.beta`` with the new
+        coefficient and writes five diagnostic fields back into ``logs``
+        so TRL's default reporter forwards them to wandb / CSV / etc.:
+
+        - ``train/beta_adaptive``       current KL coefficient
+        - ``train/kl_measured``         sanitised KL input
+        - ``train/kl_target``           constant — aids chart-by-reference
+        - ``train/beta_clamped_to_min`` 0/1 — fires on collapse
+        - ``train/beta_clamped_to_max`` 0/1 — fires on runaway divergence
+        """
+        if logs is None:
+            return control
+        if "kl" not in logs:
+            return control
+        kl = self._coerce_kl(logs["kl"])
+        if kl is None:
+            return control
+        beta = float(getattr(args, "beta", BETA_KL))
+        new_beta, clamped_lo, clamped_hi = self._next_beta(beta, kl)
+        args.beta = new_beta
+        logs["train/beta_adaptive"] = new_beta
+        logs["train/kl_measured"] = kl
+        logs["train/kl_target"] = self.target_kl
+        logs["train/beta_clamped_to_min"] = 1 if clamped_lo else 0
+        logs["train/beta_clamped_to_max"] = 1 if clamped_hi else 0
+        return control
+
+
+__all__ = [
+    "AdapterRecord",
+    "AdaptiveKLCallback",
+    "DEFAULT_BETA_MAX",
+    "DEFAULT_BETA_MIN",
+    "DEFAULT_KP",
+    "EnvFactory",
+    "EpisodeDatasetAdapter",
+    "EpisodeSampler",
+    "LanguageCode",
+    "PINNED_SYSTEM_PROMPT",
+    "RolloutGroupFn",
+    "driftcall_grpo_trainer_methods",
+    "make_driftcall_grpo_trainer_cls",
+    "render_initial_prompt",
+]

cells/step_15_train_stage1.md

@@ -0,0 +1,7 @@
+# Step 15 — Stage-1 GRPO training entry
+
+Stage-1 is the curriculum origin (training.md §3.5, DESIGN.md §10.3): 150 GRPO steps, no drift, language mix 50% English / 30% Hinglish / 20% Hindi, `warmup_ratio=0.1`. `resume_from` is rejected — there is no prior stage. Saves checkpoints every 50 steps via `save_pretrained(safe_serialization=True)`; never the naive 4-bit -> 16-bit merge path (DESIGN.md §10.5).
+
+`train(stage=1, num_steps=150, resume_from=None)` boots Gemma 3n E2B in 4-bit (hardware-aware precision: FP16 on V100, BF16 on H100) via `boot_gemma`, asserts the dtype via `assert_dtype_for_hardware` (halts on slippage; training.md §3.1), constructs the GRPOConfig + `EpisodeDatasetAdapter` + `DriftCallGRPOTrainer`, initialises wandb (offline-safe; `WandBStartupError` only when `WANDB_MODE != "offline"`), and runs `trainer.train()` for the requested step count. The `task_gen`, `env_factory`, and `rollout_group_fn` callables are passed by the notebook orchestrator so the cell stays decoupled from the env + data builders.
+
+`build_run_plan` is the pure-function entry point — tests use it to verify the resolved arguments without exercising the GPU stack. `write_local_csv_row` mirrors every WandB log dict to `metrics.csv` with the stable 20-column schema from training.md §3.4 (NaN encoded as `"nan"`).

cells/step_15_train_stage1.py

@@ -0,0 +1,307 @@
+"""Stage-1 GRPO training entry (docs/modules/training.md §3.5, DESIGN.md §10.3).
+
+Stage-1 contract:
+  - 150 GRPO steps (curriculum warmup).
+  - **No drift** in the env (``curriculum_stage=1``).
+  - Language mix: 50% English, 30% Hinglish, 20% Hindi (no Tamil/Kannada).
+  - ``warmup_ratio=0.1`` — stage-1 is the only stage that warms the LR.
+  - ``resume_from`` MUST be ``None``; stage-1 is the curriculum origin.
+  - Saves checkpoints every 50 steps with ``safe_serialization=True``;
+    NEVER naive 4-bit -> 16-bit merge (DESIGN.md §10.5, CLAUDE.md §9).
+  - WandB primary monitoring; ``LocalCSVCallback`` mirrors every ``on_log``
+    when ``WANDB_MODE=offline`` or the wandb upload flakes (training.md §2.4.1).
+  - Dtype-slippage assertion fires at entry via ``assert_dtype_for_hardware``
+    from step_12 (V100 -> FP16, H100 -> BF16 safety; training.md §3.1).
+
+Heavy imports (``torch``, ``trl``, ``unsloth``, ``wandb``) are deferred
+inside functions so this module imports cleanly on CPU-only CI.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from cells.step_12_gemma_boot import BootConfig, boot_gemma
+from cells.step_13_grpo_config import build_grpo_config
+from cells.step_14_custom_trainer import EpisodeDatasetAdapter, LanguageCode
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable
+
+
+CheckpointPath = Path
+
+STAGE: Literal[1] = 1
+DEFAULT_NUM_STEPS: int = 150
+WARMUP_RATIO: float = 0.1
+STAGE_BASE_SEED: int = 1_000_000
+DEFAULT_OUTPUT_DIR: Path = Path("checkpoints/stage1_final")
+
+LANGUAGE_WEIGHTS: dict[str, float] = {
+    "en": 0.50,
+    "hinglish": 0.30,
+    "hi": 0.20,
+    "ta": 0.0,
+    "kn": 0.0,
+}
+
+CSV_COLUMNS: tuple[str, ...] = (
+    "step",
+    "train/reward_mean",
+    "train/reward_std",
+    "train/policy_kl",
+    "train/gen_length_mean",
+    "train/grad_norm",
+    "train/loss",
+    "train/learning_rate",
+    "train/R1_mean",
+    "train/R2_mean",
+    "train/R3_mean",
+    "train/R4_mean",
+    "train/R5_mean",
+    "train/drift_detected_rate",
+    "train/format_compliance_rate",
+    "train/hallucinated_field_count",
+    "train/reward_hi",
+    "train/reward_ta",
+    "train/reward_kn",
+    "train/reward_en",
+)
+
+
+class WandBStartupError(RuntimeError):
+    """Raised at ``train()`` entry when ``wandb.init()`` fails AND
+    ``WANDB_MODE != "offline"``. Offline mode never raises (training.md §2.4.1)."""
+
+
+@dataclass(frozen=True)
+class StageRunPlan:
+    """Frozen plan describing one stage-1 training launch.
+
+    Surfaced so tests can introspect the resolved arguments without having
+    to mock the whole TRL stack.
+    """
+
+    stage: Literal[1, 2, 3]
+    num_steps: int
+    warmup_ratio: float
+    stage_base_seed: int
+    language_weights: dict[str, float]
+    output_dir: Path
+    resume_from: Path | None
+
+
+def _validate_resume_from(resume_from: Path | None) -> None:
+    """Stage 1 is the curriculum origin — ``resume_from`` MUST be ``None``."""
+    if resume_from is not None:
+        raise ValueError(
+            f"Stage 1 must not receive resume_from; got {resume_from!r}. "
+            f"Stage 1 is the curriculum origin (training.md §3.5)."
+        )
+
+
+def _validate_num_steps(num_steps: int) -> None:
+    if num_steps < 1:
+        raise ValueError(f"num_steps must be >= 1; got {num_steps}")
+
+
+def build_run_plan(
+    *,
+    num_steps: int = DEFAULT_NUM_STEPS,
+    resume_from: Path | None = None,
+    output_dir: Path | None = None,
+) -> StageRunPlan:
+    """Resolve the launch arguments into a frozen :class:`StageRunPlan`.
+
+    Pure function — does not touch the GPU, the filesystem, or wandb.
+    Tests use this to verify the resolved plan without invoking ``train``.
+    """
+    _validate_resume_from(resume_from)
+    _validate_num_steps(num_steps)
+    return StageRunPlan(
+        stage=STAGE,
+        num_steps=num_steps,
+        warmup_ratio=WARMUP_RATIO,
+        stage_base_seed=STAGE_BASE_SEED,
+        language_weights=dict(LANGUAGE_WEIGHTS),
+        output_dir=output_dir if output_dir is not None else DEFAULT_OUTPUT_DIR,
+        resume_from=resume_from,
+    )
+
+
+def _wandb_init_or_raise(*, run_name: str, output_dir: Path) -> Any:
+    """Initialise wandb; raise :class:`WandBStartupError` only when online.
+
+    Offline mode (``WANDB_MODE=offline``) never raises — local CSV is the
+    authoritative record (training.md §2.4.1).
+    """
+    mode = os.environ.get("WANDB_MODE")
+    try:
+        import wandb
+    except ImportError as exc:  # pragma: no cover - wandb required at runtime
+        if mode == "offline":
+            return None
+        raise WandBStartupError(
+            f"wandb import failed and WANDB_MODE != 'offline': {exc}"
+        ) from exc
+
+    try:
+        run = wandb.init(
+            project="driftcall",
+            group="curriculum-v1",
+            name=run_name,
+            dir=str(output_dir.parent),
+            reinit=True,
+        )
+    except Exception as exc:
+        if mode == "offline":
+            return None
+        raise WandBStartupError(
+            f"wandb.init() failed and WANDB_MODE != 'offline': {exc}"
+        ) from exc
+    return run
+
+
+def write_local_csv_row(
+    *,
+    csv_path: Path,
+    logs: dict[str, Any],
+    columns: tuple[str, ...] = CSV_COLUMNS,
+) -> None:
+    """Append one row to ``metrics.csv`` mirroring the WandB ``on_log`` dict.
+
+    Schema is the stable 20-column ordering from training.md §3.4. NaN floats
+    are encoded as the literal string ``"nan"`` (training.md §2.4.1). Header
+    is written exactly once on first call.
+    """
+    csv_path.parent.mkdir(parents=True, exist_ok=True)
+    is_new = not csv_path.exists()
+    row: list[str] = []
+    for col in columns:
+        value = logs.get(col, "")
+        if isinstance(value, float):
+            row.append("nan" if value != value else repr(value))
+        else:
+            row.append(str(value))
+    with csv_path.open("a", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        if is_new:
+            writer.writerow(columns)
+        writer.writerow(row)
+
+
+def save_checkpoint(
+    *,
+    model: Any,
+    tokenizer: Any,
+    output_dir: Path,
+) -> Path:
+    """Save adapter + tokenizer using ``safe_serialization=True``.
+
+    Per DESIGN.md §10.5 / training.md §3.6 we NEVER call
+    ``merge_and_unload()`` or any 4-bit -> 16-bit naive merge path.
+    Returns the directory where the adapter landed.
+    """
+    output_dir.mkdir(parents=True, exist_ok=True)
+    model.save_pretrained(str(output_dir), safe_serialization=True)
+    tokenizer.save_pretrained(str(output_dir))
+    return output_dir
+
+
+def train(
+    *,
+    stage: Literal[1] = STAGE,
+    num_steps: int = DEFAULT_NUM_STEPS,
+    resume_from: Path | None = None,
+    output_dir: Path | None = None,
+    boot_config: BootConfig | None = None,
+    task_gen: Callable[..., Any] | None = None,
+    env_factory: Callable[[], Any] | None = None,
+    rollout_group_fn: Callable[..., Any] | None = None,
+) -> CheckpointPath:
+    """Run GRPO Stage-1 (warmup, no drift) for ``num_steps`` updates.
+
+    Behaviour (training.md §2.1):
+      1. Boot Gemma 3n E2B in 4-bit + attach LoRA via :func:`boot_gemma`.
+      2. Re-assert FP16 dtype (BF16-slippage halt; training.md §3.1).
+      3. Build :class:`GRPOConfig` for stage 1 (warmup_ratio=0.1).
+      4. Build the streaming :class:`EpisodeDatasetAdapter` with the
+         stage-1 language mix (50% en, 30% hinglish, 20% hi).
+      5. Construct ``DriftCallGRPOTrainer`` with the multi-turn rollout
+         override (step_14) and ``reward_fn`` (step_13).
+      6. Initialise wandb (offline-safe; training.md §2.4.1).
+      7. ``trainer.train()`` for ``num_steps`` updates.
+      8. Save the final adapter via :func:`save_checkpoint`.
+    """
+    if stage != STAGE:
+        raise ValueError(f"stage must be {STAGE}; got {stage}")
+
+    plan = build_run_plan(
+        num_steps=num_steps,
+        resume_from=resume_from,
+        output_dir=output_dir,
+    )
+
+    # boot_gemma() already runs assert_fp16_dtype on the base model before
+    # LoRA attach (training.md §3.1). We do not re-check the peft-wrapped
+    # model here — the wrapped LoRA params are FP16 by construction.
+    model, tokenizer = boot_gemma(boot_config)
+
+    config = build_grpo_config(stage=plan.stage, resume_output_dir=plan.output_dir, max_steps=plan.num_steps)
+
+    if task_gen is None or env_factory is None or rollout_group_fn is None:
+        raise ValueError(
+            "Stage-1 train() requires task_gen, env_factory, and rollout_group_fn "
+            "to be provided by the caller (notebook orchestrator). They are kept "
+            "explicit so the training cell stays decoupled from data + env builders."
+        )
+
+    dataset = EpisodeDatasetAdapter(
+        task_gen=task_gen,
+        env_factory=env_factory,
+        stage=plan.stage,
+        stage_base_seed=plan.stage_base_seed,
+        language_weights=cast("dict[LanguageCode, float]", plan.language_weights),
+        tokenizer=tokenizer,
+    )
+
+    from cells.step_13_grpo_config import reward_fn
+    from cells.step_14_custom_trainer import make_driftcall_grpo_trainer_cls
+
+    Trainer = make_driftcall_grpo_trainer_cls()
+    trainer = Trainer(
+        model=model,
+        args=config,
+        processing_class=tokenizer,
+        train_dataset=dataset,
+        rollout_group_fn=rollout_group_fn,
+        env_factory=env_factory,
+        reward_fn_driftcall=reward_fn,
+    )
+
+    _wandb_init_or_raise(run_name=f"driftcall-stage{plan.stage}", output_dir=plan.output_dir)
+    trainer.train()
+
+    return save_checkpoint(model=model, tokenizer=tokenizer, output_dir=plan.output_dir)
+
+
+__all__ = [
+    "CSV_COLUMNS",
+    "DEFAULT_NUM_STEPS",
+    "DEFAULT_OUTPUT_DIR",
+    "LANGUAGE_WEIGHTS",
+    "STAGE",
+    "STAGE_BASE_SEED",
+    "WARMUP_RATIO",
+    "CheckpointPath",
+    "StageRunPlan",
+    "WandBStartupError",
+    "build_run_plan",
+    "save_checkpoint",
+    "train",
+    "write_local_csv_row",
+]

cells/step_16_train_stage2.md

@@ -0,0 +1,7 @@
+# Step 16 — Stage-2 GRPO training entry
+
+Stage-2 is the single-drift curriculum (training.md §3.5, DESIGN.md §10.3): 200 GRPO steps, one drift per episode (`curriculum_stage=2`), language mix 30% EN / 30% Hinglish / 20% Hi / 10% Ta / 10% Kn, `warmup_ratio=0.0` (continuous cosine across all 500 steps; never re-warm mid-curriculum). `resume_from` is required — must point at the Stage-1 final checkpoint. Saves checkpoints every 50 steps via `save_pretrained(safe_serialization=True)`; never the naive 4-bit -> 16-bit merge path (DESIGN.md §10.5).
+
+`train(stage=2, num_steps=200, resume_from=Path("checkpoints/stage1_final"))` boots Gemma 3n E2B in 4-bit (hardware-aware precision: FP16 on V100, BF16 on H100), asserts dtype via `assert_dtype_for_hardware`, attaches the Stage-1 LoRA adapters via `PeftModel.from_pretrained(model, resume_from, is_trainable=True)`, constructs the Stage-2 config + adapter + trainer, and resumes via `trainer.train(resume_from_checkpoint=str(resume_from))` — TRL restores the optimiser/scheduler/global-step state. Language weights are validated up-front: every non-English cohort must carry weight >= 0.05 to avoid `LanguageCohortCollapseError` upstream (training.md §7f).
+
+`build_run_plan` is the pure-function entry point used by tests; rejects `resume_from=None` and weights below the 0.05 floor. `WandBStartupError` only fires when `WANDB_MODE != "offline"` and `wandb.init()` raises (training.md §2.4.1). Dtype-slippage halt fires before any optimizer/PEFT state is built (training.md §3.1).

cells/step_16_train_stage2.py

@@ -0,0 +1,357 @@
+"""Stage-2 GRPO training entry (docs/modules/training.md §3.5, DESIGN.md §10.3).
+
+Stage-2 contract:
+  - 200 GRPO steps (single-drift curriculum).
+  - **One drift per episode** in the env (``curriculum_stage=2``).
+  - Language mix: 30% English, 30% Hinglish, 20% Hindi, 10% Tamil, 10% Kannada.
+  - ``warmup_ratio=0.0`` — never re-warm the LR mid-curriculum
+    (training.md §3.5; one continuous cosine across all 500 steps).
+  - ``resume_from`` is REQUIRED — must point at the Stage-1 final
+    checkpoint directory. None is rejected.
+  - Validates ``language_weights`` per training.md §7f: every non-English
+    cohort must carry weight >= 0.05 at stage >= 2.
+  - Saves checkpoints every 50 steps with ``safe_serialization=True``;
+    NEVER naive 4-bit -> 16-bit merge (DESIGN.md §10.5, CLAUDE.md §9).
+  - WandB primary monitoring; ``LocalCSVCallback`` mirrors every ``on_log``
+    when ``WANDB_MODE=offline`` or the wandb upload flakes (training.md §2.4.1).
+  - Dtype-slippage assertion fires at entry via ``assert_dtype_for_hardware``
+    from step_12 (V100 -> FP16, H100 -> BF16 safety; training.md §3.1).
+
+Heavy imports (``torch``, ``trl``, ``unsloth``, ``wandb``, ``peft``) are
+deferred inside functions so this module imports cleanly on CPU-only CI.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from cells.step_12_gemma_boot import BootConfig, assert_dtype_for_hardware
+from cells.step_13_grpo_config import build_grpo_config
+from cells.step_14_custom_trainer import EpisodeDatasetAdapter, LanguageCode
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable
+
+
+CheckpointPath = Path
+
+STAGE: Literal[2] = 2
+DEFAULT_NUM_STEPS: int = 200
+WARMUP_RATIO: float = 0.0
+STAGE_BASE_SEED: int = 2_000_000
+DEFAULT_OUTPUT_DIR: Path = Path("checkpoints/stage2_final")
+COHORT_MIN_WEIGHT_AT_STAGE_GE_2: float = 0.05
+NON_ENGLISH_LANGUAGES: tuple[str, ...] = ("hi", "ta", "kn", "hinglish")
+
+LANGUAGE_WEIGHTS: dict[str, float] = {
+    "en": 0.30,
+    "hinglish": 0.30,
+    "hi": 0.20,
+    "ta": 0.10,
+    "kn": 0.10,
+}
+
+CSV_COLUMNS: tuple[str, ...] = (
+    "step",
+    "train/reward_mean",
+    "train/reward_std",
+    "train/policy_kl",
+    "train/gen_length_mean",
+    "train/grad_norm",
+    "train/loss",
+    "train/learning_rate",
+    "train/R1_mean",
+    "train/R2_mean",
+    "train/R3_mean",
+    "train/R4_mean",
+    "train/R5_mean",
+    "train/drift_detected_rate",
+    "train/format_compliance_rate",
+    "train/hallucinated_field_count",
+    "train/reward_hi",
+    "train/reward_ta",
+    "train/reward_kn",
+    "train/reward_en",
+)
+
+
+class WandBStartupError(RuntimeError):
+    """Raised at ``train()`` entry when ``wandb.init()`` fails AND
+    ``WANDB_MODE != "offline"``. Offline mode never raises (training.md §2.4.1)."""
+
+
+@dataclass(frozen=True)
+class StageRunPlan:
+    """Frozen plan describing one stage-2 training launch."""
+
+    stage: Literal[1, 2, 3]
+    num_steps: int
+    warmup_ratio: float
+    stage_base_seed: int
+    language_weights: dict[str, float]
+    output_dir: Path
+    resume_from: Path
+
+
+def _validate_resume_from(resume_from: Path | None) -> Path:
+    """Stage 2 REQUIRES a stage-1 checkpoint to resume from."""
+    if resume_from is None:
+        raise ValueError(
+            "Stage 2 requires resume_from (path to Stage-1 final checkpoint); "
+            "got None (training.md §3.5 stage transitions)."
+        )
+    if not isinstance(resume_from, Path):
+        raise TypeError(
+            f"resume_from must be a pathlib.Path; got {type(resume_from).__name__}"
+        )
+    return resume_from
+
+
+def _validate_num_steps(num_steps: int) -> None:
+    if num_steps < 1:
+        raise ValueError(f"num_steps must be >= 1; got {num_steps}")
+
+
+def _validate_language_weights(language_weights: dict[str, float]) -> None:
+    """Every non-English cohort must carry weight >= 0.05 at stage 2/3.
+
+    Prevents :class:`LanguageCohortCollapseError` upstream
+    (training.md §7f).
+    """
+    for lang in NON_ENGLISH_LANGUAGES:
+        weight = language_weights.get(lang, 0.0)
+        if weight < COHORT_MIN_WEIGHT_AT_STAGE_GE_2:
+            raise ValueError(
+                f"language_weights['{lang}'] = {weight} < "
+                f"{COHORT_MIN_WEIGHT_AT_STAGE_GE_2}; weight >= 0.05 for "
+                f"non-English at stage >= 2 (training.md §7f)."
+            )
+
+
+def build_run_plan(
+    *,
+    num_steps: int = DEFAULT_NUM_STEPS,
+    resume_from: Path | None = None,
+    output_dir: Path | None = None,
+    language_weights: dict[str, float] | None = None,
+) -> StageRunPlan:
+    """Resolve the launch arguments into a frozen :class:`StageRunPlan`.
+
+    Pure function — does not touch the GPU, the filesystem, or wandb.
+    """
+    resolved_resume = _validate_resume_from(resume_from)
+    _validate_num_steps(num_steps)
+    weights = dict(language_weights) if language_weights is not None else dict(LANGUAGE_WEIGHTS)
+    _validate_language_weights(weights)
+    return StageRunPlan(
+        stage=STAGE,
+        num_steps=num_steps,
+        warmup_ratio=WARMUP_RATIO,
+        stage_base_seed=STAGE_BASE_SEED,
+        language_weights=weights,
+        output_dir=output_dir if output_dir is not None else DEFAULT_OUTPUT_DIR,
+        resume_from=resolved_resume,
+    )
+
+
+def _wandb_init_or_raise(*, run_name: str, output_dir: Path) -> Any:
+    """Initialise wandb; raise :class:`WandBStartupError` only when online."""
+    mode = os.environ.get("WANDB_MODE")
+    try:
+        import wandb
+    except ImportError as exc:  # pragma: no cover - wandb required at runtime
+        if mode == "offline":
+            return None
+        raise WandBStartupError(
+            f"wandb import failed and WANDB_MODE != 'offline': {exc}"
+        ) from exc
+
+    try:
+        run = wandb.init(
+            project="driftcall",
+            group="curriculum-v1",
+            name=run_name,
+            dir=str(output_dir.parent),
+            reinit=True,
+        )
+    except Exception as exc:
+        if mode == "offline":
+            return None
+        raise WandBStartupError(
+            f"wandb.init() failed and WANDB_MODE != 'offline': {exc}"
+        ) from exc
+    return run
+
+
+def write_local_csv_row(
+    *,
+    csv_path: Path,
+    logs: dict[str, Any],
+    columns: tuple[str, ...] = CSV_COLUMNS,
+) -> None:
+    """Append one row to ``metrics.csv`` mirroring the WandB ``on_log`` dict."""
+    csv_path.parent.mkdir(parents=True, exist_ok=True)
+    is_new = not csv_path.exists()
+    row: list[str] = []
+    for col in columns:
+        value = logs.get(col, "")
+        if isinstance(value, float):
+            row.append("nan" if value != value else repr(value))
+        else:
+            row.append(str(value))
+    with csv_path.open("a", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        if is_new:
+            writer.writerow(columns)
+        writer.writerow(row)
+
+
+def save_checkpoint(
+    *,
+    model: Any,
+    tokenizer: Any,
+    output_dir: Path,
+) -> Path:
+    """Save adapter + tokenizer using ``safe_serialization=True``."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    model.save_pretrained(str(output_dir), safe_serialization=True)
+    tokenizer.save_pretrained(str(output_dir))
+    return output_dir
+
+
+def _load_base_model(boot_config: BootConfig | None) -> tuple[Any, Any]:
+    """Load the 4-bit Gemma 3n base model (no LoRA attach) and verify dtype.
+
+    Stage 2 must NOT call :func:`cells.step_12_gemma_boot.boot_gemma`
+    because that helper attaches a *fresh* LoRA via ``get_peft_model``;
+    we instead load the base only, then wrap with the saved Stage-1
+    adapters via :func:`_load_stage1_adapters` (training.md §3.1, §3.6).
+
+    Precision is hardware-aware: V100 -> FP16, H100 -> BF16.
+    """
+    cfg = boot_config if boot_config is not None else BootConfig()
+
+    import torch
+    from unsloth import FastModel
+
+    dtype = torch.float16 if cfg.hardware == "v100" else torch.bfloat16
+
+    model, tokenizer = FastModel.from_pretrained(
+        cfg.base_model_id,
+        max_seq_length=cfg.max_seq_length,
+        load_in_4bit=cfg.load_in_4bit,
+        dtype=dtype,
+    )
+    assert_dtype_for_hardware(model, cfg.hardware)
+    return model, tokenizer
+
+
+def _load_stage1_adapters(model: Any, resume_from: Path) -> Any:
+    """Attach the Stage-1 LoRA adapters to the freshly-booted base model.
+
+    Returns the wrapped :class:`PeftModel`. Heavy import deferred so the
+    cell loads on CPU-only CI without ``peft`` installed.
+    """
+    from peft import PeftModel
+
+    return PeftModel.from_pretrained(model, str(resume_from), is_trainable=True)
+
+
+def train(
+    *,
+    stage: Literal[2] = STAGE,
+    num_steps: int = DEFAULT_NUM_STEPS,
+    resume_from: Path | None = None,
+    output_dir: Path | None = None,
+    boot_config: BootConfig | None = None,
+    task_gen: Callable[..., Any] | None = None,
+    env_factory: Callable[[], Any] | None = None,
+    rollout_group_fn: Callable[..., Any] | None = None,
+) -> CheckpointPath:
+    """Run GRPO Stage-2 (single drift) for ``num_steps`` updates.
+
+    Behaviour (training.md §3.5 stage transitions):
+      1. Load Gemma 3n E2B base in 4-bit (hardware-aware precision) — no fresh LoRA.
+      2. Assert FP16 dtype on the base (BF16-slippage halt).
+      3. Attach Stage-1 LoRA adapters via ``PeftModel.from_pretrained``.
+      4. Build :class:`GRPOConfig` for stage 2 (warmup_ratio=0.0).
+      5. Build the streaming :class:`EpisodeDatasetAdapter` with the
+         stage-2 language mix.
+      6. Construct ``DriftCallGRPOTrainer`` with the multi-turn rollout
+         override and ``reward_fn``.
+      7. Initialise wandb (offline-safe).
+      8. ``trainer.train(resume_from_checkpoint=str(resume_from))`` —
+         restores optimizer/scheduler state + TRL-internal RNG.
+      9. Save the final adapter via :func:`save_checkpoint`.
+    """
+    if stage != STAGE:
+        raise ValueError(f"stage must be {STAGE}; got {stage}")
+
+    plan = build_run_plan(
+        num_steps=num_steps,
+        resume_from=resume_from,
+        output_dir=output_dir,
+    )
+
+    base_model, tokenizer = _load_base_model(boot_config)
+    model = _load_stage1_adapters(base_model, plan.resume_from)
+
+    config = build_grpo_config(stage=plan.stage, resume_output_dir=plan.output_dir, max_steps=plan.num_steps)
+
+    if task_gen is None or env_factory is None or rollout_group_fn is None:
+        raise ValueError(
+            "Stage-2 train() requires task_gen, env_factory, and rollout_group_fn "
+            "to be provided by the caller (notebook orchestrator)."
+        )
+
+    dataset = EpisodeDatasetAdapter(
+        task_gen=task_gen,
+        env_factory=env_factory,
+        stage=plan.stage,
+        stage_base_seed=plan.stage_base_seed,
+        language_weights=cast("dict[LanguageCode, float]", plan.language_weights),
+        tokenizer=tokenizer,
+    )
+
+    from cells.step_13_grpo_config import reward_fn
+    from cells.step_14_custom_trainer import make_driftcall_grpo_trainer_cls
+
+    Trainer = make_driftcall_grpo_trainer_cls()
+    trainer = Trainer(
+        model=model,
+        args=config,
+        processing_class=tokenizer,
+        train_dataset=dataset,
+        rollout_group_fn=rollout_group_fn,
+        env_factory=env_factory,
+        reward_fn_driftcall=reward_fn,
+    )
+
+    _wandb_init_or_raise(run_name=f"driftcall-stage{plan.stage}", output_dir=plan.output_dir)
+    trainer.train(resume_from_checkpoint=str(plan.resume_from))
+
+    return save_checkpoint(model=model, tokenizer=tokenizer, output_dir=plan.output_dir)
+
+
+__all__ = [
+    "COHORT_MIN_WEIGHT_AT_STAGE_GE_2",
+    "CSV_COLUMNS",
+    "DEFAULT_NUM_STEPS",
+    "DEFAULT_OUTPUT_DIR",
+    "LANGUAGE_WEIGHTS",
+    "NON_ENGLISH_LANGUAGES",
+    "STAGE",
+    "STAGE_BASE_SEED",
+    "WARMUP_RATIO",
+    "CheckpointPath",
+    "StageRunPlan",
+    "WandBStartupError",
+    "build_run_plan",
+    "save_checkpoint",
+    "train",
+    "write_local_csv_row",
+]

cells/step_17_train_stage3.md

@@ -0,0 +1,7 @@
+# Step 17 — Stage-3 GRPO training entry
+
+Stage-3 is the compound-drift curriculum (training.md §3.5, DESIGN.md §10.3): 150 GRPO steps, two drifts per episode (`curriculum_stage=3`), language mix identical to Stage 2 (30% EN / 30% Hinglish / 20% Hi / 10% Ta / 10% Kn), `warmup_ratio=0.0` (continuous cosine across all 500 steps). `resume_from` is required — must point at the Stage-2 final checkpoint. Saves checkpoints every 50 steps via `save_pretrained(safe_serialization=True)`; never the naive 4-bit -> 16-bit merge path (DESIGN.md §10.5).
+
+`train(stage=3, num_steps=150, resume_from=Path("checkpoints/stage2_final"))` boots Gemma 3n E2B in 4-bit (hardware-aware precision: FP16 on V100, BF16 on H100), asserts dtype via `assert_dtype_for_hardware`, attaches the Stage-2 LoRA adapters via `PeftModel.from_pretrained(..., is_trainable=True)`, constructs the Stage-3 config + adapter + trainer, and resumes via `trainer.train(resume_from_checkpoint=str(resume_from))`. Language weights are validated up-front: every non-English cohort must carry weight >= 0.05 (training.md §7f).
+
+`build_run_plan` is the pure-function entry point used by tests; rejects `resume_from=None` and weights below the 0.05 floor. `WandBStartupError` only fires when `WANDB_MODE != "offline"` and `wandb.init()` raises (training.md §2.4.1). Dtype-slippage halt fires before any optimizer/PEFT state is built (training.md §3.1).

cells/step_17_train_stage3.py

@@ -0,0 +1,350 @@
+"""Stage-3 GRPO training entry (docs/modules/training.md §3.5, DESIGN.md §10.3).
+
+Stage-3 contract:
+  - 150 GRPO steps (compound-drift curriculum).
+  - **Two drifts per episode** in the env (``curriculum_stage=3``).
+  - Language mix: identical to Stage 2 — 30% English, 30% Hinglish,
+    20% Hindi, 10% Tamil, 10% Kannada (DESIGN.md §10.3 Stage-3 row).
+  - ``warmup_ratio=0.0`` — never re-warm the LR mid-curriculum.
+  - ``resume_from`` is REQUIRED — must point at the Stage-2 final
+    checkpoint directory. None is rejected.
+  - Validates ``language_weights`` per training.md §7f: every non-English
+    cohort must carry weight >= 0.05 at stage >= 2.
+  - Saves checkpoints every 50 steps with ``safe_serialization=True``;
+    NEVER naive 4-bit -> 16-bit merge (DESIGN.md §10.5, CLAUDE.md §9).
+  - WandB primary monitoring; ``LocalCSVCallback`` mirrors every ``on_log``
+    when ``WANDB_MODE=offline`` or the wandb upload flakes (training.md §2.4.1).
+  - Dtype-slippage assertion fires at entry via ``assert_dtype_for_hardware``
+    from step_12 (V100 -> FP16, H100 -> BF16 safety; training.md §3.1).
+
+Heavy imports (``torch``, ``trl``, ``unsloth``, ``wandb``, ``peft``) are
+deferred inside functions so this module imports cleanly on CPU-only CI.
+"""
+
+from __future__ import annotations
+
+import csv
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, cast
+
+from cells.step_12_gemma_boot import BootConfig, assert_dtype_for_hardware
+from cells.step_13_grpo_config import build_grpo_config
+from cells.step_14_custom_trainer import EpisodeDatasetAdapter, LanguageCode
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable
+
+
+CheckpointPath = Path
+
+STAGE: Literal[3] = 3
+DEFAULT_NUM_STEPS: int = 150
+WARMUP_RATIO: float = 0.0
+STAGE_BASE_SEED: int = 3_000_000
+DEFAULT_OUTPUT_DIR: Path = Path("checkpoints/stage3_final")
+COHORT_MIN_WEIGHT_AT_STAGE_GE_2: float = 0.05
+NON_ENGLISH_LANGUAGES: tuple[str, ...] = ("hi", "ta", "kn", "hinglish")
+
+LANGUAGE_WEIGHTS: dict[str, float] = {
+    "en": 0.30,
+    "hinglish": 0.30,
+    "hi": 0.20,
+    "ta": 0.10,
+    "kn": 0.10,
+}
+
+CSV_COLUMNS: tuple[str, ...] = (
+    "step",
+    "train/reward_mean",
+    "train/reward_std",
+    "train/policy_kl",
+    "train/gen_length_mean",
+    "train/grad_norm",
+    "train/loss",
+    "train/learning_rate",
+    "train/R1_mean",
+    "train/R2_mean",
+    "train/R3_mean",
+    "train/R4_mean",
+    "train/R5_mean",
+    "train/drift_detected_rate",
+    "train/format_compliance_rate",
+    "train/hallucinated_field_count",
+    "train/reward_hi",
+    "train/reward_ta",
+    "train/reward_kn",
+    "train/reward_en",
+)
+
+
+class WandBStartupError(RuntimeError):
+    """Raised at ``train()`` entry when ``wandb.init()`` fails AND
+    ``WANDB_MODE != "offline"``. Offline mode never raises (training.md §2.4.1)."""
+
+
+@dataclass(frozen=True)
+class StageRunPlan:
+    """Frozen plan describing one stage-3 training launch."""
+
+    stage: Literal[1, 2, 3]
+    num_steps: int
+    warmup_ratio: float
+    stage_base_seed: int
+    language_weights: dict[str, float]
+    output_dir: Path
+    resume_from: Path
+
+
+def _validate_resume_from(resume_from: Path | None) -> Path:
+    """Stage 3 REQUIRES a stage-2 checkpoint to resume from."""
+    if resume_from is None:
+        raise ValueError(
+            "Stage 3 requires resume_from (path to Stage-2 final checkpoint); "
+            "got None (training.md §3.5 stage transitions)."
+        )
+    if not isinstance(resume_from, Path):
+        raise TypeError(
+            f"resume_from must be a pathlib.Path; got {type(resume_from).__name__}"
+        )
+    return resume_from
+
+
+def _validate_num_steps(num_steps: int) -> None:
+    if num_steps < 1:
+        raise ValueError(f"num_steps must be >= 1; got {num_steps}")
+
+
+def _validate_language_weights(language_weights: dict[str, float]) -> None:
+    """Every non-English cohort must carry weight >= 0.05 at stage 2/3
+    (training.md §7f)."""
+    for lang in NON_ENGLISH_LANGUAGES:
+        weight = language_weights.get(lang, 0.0)
+        if weight < COHORT_MIN_WEIGHT_AT_STAGE_GE_2:
+            raise ValueError(
+                f"language_weights['{lang}'] = {weight} < "
+                f"{COHORT_MIN_WEIGHT_AT_STAGE_GE_2}; weight >= 0.05 for "
+                f"non-English at stage >= 2 (training.md §7f)."
+            )
+
+
+def build_run_plan(
+    *,
+    num_steps: int = DEFAULT_NUM_STEPS,
+    resume_from: Path | None = None,
+    output_dir: Path | None = None,
+    language_weights: dict[str, float] | None = None,
+) -> StageRunPlan:
+    """Resolve the launch arguments into a frozen :class:`StageRunPlan`."""
+    resolved_resume = _validate_resume_from(resume_from)
+    _validate_num_steps(num_steps)
+    weights = dict(language_weights) if language_weights is not None else dict(LANGUAGE_WEIGHTS)
+    _validate_language_weights(weights)
+    return StageRunPlan(
+        stage=STAGE,
+        num_steps=num_steps,
+        warmup_ratio=WARMUP_RATIO,
+        stage_base_seed=STAGE_BASE_SEED,
+        language_weights=weights,
+        output_dir=output_dir if output_dir is not None else DEFAULT_OUTPUT_DIR,
+        resume_from=resolved_resume,
+    )
+
+
+def _wandb_init_or_raise(*, run_name: str, output_dir: Path) -> Any:
+    """Initialise wandb; raise :class:`WandBStartupError` only when online."""
+    mode = os.environ.get("WANDB_MODE")
+    try:
+        import wandb
+    except ImportError as exc:  # pragma: no cover - wandb required at runtime
+        if mode == "offline":
+            return None
+        raise WandBStartupError(
+            f"wandb import failed and WANDB_MODE != 'offline': {exc}"
+        ) from exc
+
+    try:
+        run = wandb.init(
+            project="driftcall",
+            group="curriculum-v1",
+            name=run_name,
+            dir=str(output_dir.parent),
+            reinit=True,
+        )
+    except Exception as exc:
+        if mode == "offline":
+            return None
+        raise WandBStartupError(
+            f"wandb.init() failed and WANDB_MODE != 'offline': {exc}"
+        ) from exc
+    return run
+
+
+def write_local_csv_row(
+    *,
+    csv_path: Path,
+    logs: dict[str, Any],
+    columns: tuple[str, ...] = CSV_COLUMNS,
+) -> None:
+    """Append one row to ``metrics.csv`` mirroring the WandB ``on_log`` dict."""
+    csv_path.parent.mkdir(parents=True, exist_ok=True)
+    is_new = not csv_path.exists()
+    row: list[str] = []
+    for col in columns:
+        value = logs.get(col, "")
+        if isinstance(value, float):
+            row.append("nan" if value != value else repr(value))
+        else:
+            row.append(str(value))
+    with csv_path.open("a", newline="", encoding="utf-8") as fh:
+        writer = csv.writer(fh)
+        if is_new:
+            writer.writerow(columns)
+        writer.writerow(row)
+
+
+def save_checkpoint(
+    *,
+    model: Any,
+    tokenizer: Any,
+    output_dir: Path,
+) -> Path:
+    """Save adapter + tokenizer using ``safe_serialization=True``."""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    model.save_pretrained(str(output_dir), safe_serialization=True)
+    tokenizer.save_pretrained(str(output_dir))
+    return output_dir
+
+
+def _load_base_model(boot_config: BootConfig | None) -> tuple[Any, Any]:
+    """Load the 4-bit Gemma 3n base model (no LoRA attach) and verify dtype.
+
+    Stage 3 must NOT call :func:`cells.step_12_gemma_boot.boot_gemma`
+    because that helper attaches a *fresh* LoRA via ``get_peft_model``;
+    we instead load the base only, then wrap with the saved Stage-2
+    adapters via :func:`_load_stage2_adapters` (training.md §3.1, §3.6).
+
+    Precision is hardware-aware: V100 -> FP16, H100 -> BF16.
+    """
+    cfg = boot_config if boot_config is not None else BootConfig()
+
+    import torch
+    from unsloth import FastModel
+
+    dtype = torch.float16 if cfg.hardware == "v100" else torch.bfloat16
+
+    model, tokenizer = FastModel.from_pretrained(
+        cfg.base_model_id,
+        max_seq_length=cfg.max_seq_length,
+        load_in_4bit=cfg.load_in_4bit,
+        dtype=dtype,
+    )
+    assert_dtype_for_hardware(model, cfg.hardware)
+    return model, tokenizer
+
+
+def _load_stage2_adapters(model: Any, resume_from: Path) -> Any:
+    """Attach the Stage-2 LoRA adapters to the freshly-booted base model.
+
+    Returns the wrapped :class:`PeftModel`. Heavy import deferred so the
+    cell loads on CPU-only CI without ``peft`` installed.
+    """
+    from peft import PeftModel
+
+    return PeftModel.from_pretrained(model, str(resume_from), is_trainable=True)
+
+
+def train(
+    *,
+    stage: Literal[3] = STAGE,
+    num_steps: int = DEFAULT_NUM_STEPS,
+    resume_from: Path | None = None,
+    output_dir: Path | None = None,
+    boot_config: BootConfig | None = None,
+    task_gen: Callable[..., Any] | None = None,
+    env_factory: Callable[[], Any] | None = None,
+    rollout_group_fn: Callable[..., Any] | None = None,
+) -> CheckpointPath:
+    """Run GRPO Stage-3 (compound drift) for ``num_steps`` updates.
+
+    Behaviour (training.md §3.5 stage transitions):
+      1. Load Gemma 3n E2B base in 4-bit (hardware-aware precision) — no fresh LoRA.
+      2. Assert FP16 dtype on the base (BF16-slippage halt).
+      3. Attach Stage-2 LoRA adapters via ``PeftModel.from_pretrained``.
+      4. Build :class:`GRPOConfig` for stage 3 (warmup_ratio=0.0).
+      5. Build the streaming :class:`EpisodeDatasetAdapter` with the
+         stage-3 language mix (identical to Stage 2 per DESIGN.md §10.3).
+      6. Construct ``DriftCallGRPOTrainer`` with the multi-turn rollout
+         override and ``reward_fn``.
+      7. Initialise wandb (offline-safe).
+      8. ``trainer.train(resume_from_checkpoint=str(resume_from))``.
+      9. Save the final adapter via :func:`save_checkpoint`.
+    """
+    if stage != STAGE:
+        raise ValueError(f"stage must be {STAGE}; got {stage}")
+
+    plan = build_run_plan(
+        num_steps=num_steps,
+        resume_from=resume_from,
+        output_dir=output_dir,
+    )
+
+    base_model, tokenizer = _load_base_model(boot_config)
+    model = _load_stage2_adapters(base_model, plan.resume_from)
+
+    config = build_grpo_config(stage=plan.stage, resume_output_dir=plan.output_dir, max_steps=plan.num_steps)
+
+    if task_gen is None or env_factory is None or rollout_group_fn is None:
+        raise ValueError(
+            "Stage-3 train() requires task_gen, env_factory, and rollout_group_fn "
+            "to be provided by the caller (notebook orchestrator)."
+        )
+
+    dataset = EpisodeDatasetAdapter(
+        task_gen=task_gen,
+        env_factory=env_factory,
+        stage=plan.stage,
+        stage_base_seed=plan.stage_base_seed,
+        language_weights=cast("dict[LanguageCode, float]", plan.language_weights),
+        tokenizer=tokenizer,
+    )
+
+    from cells.step_13_grpo_config import reward_fn
+    from cells.step_14_custom_trainer import make_driftcall_grpo_trainer_cls
+
+    Trainer = make_driftcall_grpo_trainer_cls()
+    trainer = Trainer(
+        model=model,
+        args=config,
+        processing_class=tokenizer,
+        train_dataset=dataset,
+        rollout_group_fn=rollout_group_fn,
+        env_factory=env_factory,
+        reward_fn_driftcall=reward_fn,
+    )
+
+    _wandb_init_or_raise(run_name=f"driftcall-stage{plan.stage}", output_dir=plan.output_dir)
+    trainer.train(resume_from_checkpoint=str(plan.resume_from))
+
+    return save_checkpoint(model=model, tokenizer=tokenizer, output_dir=plan.output_dir)
+
+
+__all__ = [
+    "COHORT_MIN_WEIGHT_AT_STAGE_GE_2",
+    "CSV_COLUMNS",
+    "DEFAULT_NUM_STEPS",
+    "DEFAULT_OUTPUT_DIR",
+    "LANGUAGE_WEIGHTS",
+    "NON_ENGLISH_LANGUAGES",
+    "STAGE",
+    "STAGE_BASE_SEED",
+    "WARMUP_RATIO",
+    "CheckpointPath",
+    "StageRunPlan",
+    "WandBStartupError",
+    "build_run_plan",
+    "save_checkpoint",
+    "train",
+    "write_local_csv_row",
+]

cells/step_18_eval_baseline.md

@@ -0,0 +1,16 @@
+# Cell 18 — Baseline Evaluation
+
+`eval_baseline(...)` runs the **untrained Gemma 3n E2B** on the first 50 rows of
+`val/briefs.jsonl` under frozen-greedy sampling and returns an `EvalReport`
+with bootstrap CIs (`n_boot=10_000`, `rng_seed=20260426`).
+
+**Contract:** evaluation.md §2.1, §3.1–§3.3, §3.8, §4, §5.
+
+- 50 held-out val episodes, file-order (no shuffle).
+- `env.reset(seed=hash((episode_id, "eval")) & 0xFFFFFFFF)`.
+- Greedy: `temperature=0.0`, `num_generations=1`, `model.eval()` + `torch.no_grad()`.
+- Wall-clock ceiling 20 min; raises `EvalBudgetExceededError` on overrun.
+- No LLM-as-judge (forbidden imports listed in `_NO_LLM_JUDGE_FORBIDDEN_IMPORTS`).
+
+The training-eval delegate is **injected** so unit tests stub model inference
+on CPU-only CI (training_tests.md §5.3 `mock_cuda` pattern).

cells/step_18_eval_baseline.py

@@ -0,0 +1,376 @@
+"""Cell 18 — Baseline evaluation harness.
+
+Implements ``docs/modules/evaluation.md`` §1, §2, §3.1–§3.3, §3.8, §4 and
+§5 for the baseline (untrained Gemma 3n E2B) eval path.
+
+Hard rules (evaluation.md §3.1, §3.2, §6.3):
+- Greedy decoding (``temperature=0.0``); ``num_generations=1``;
+  ``model.eval()`` + ``torch.no_grad()`` semantics asserted at entry.
+- Per-episode env seed = ``hash((episode_id, "eval")) & 0xFFFFFFFF``.
+- 50 held-out val episodes (rows ``[0:50]`` of ``val/briefs.jsonl``) — file
+  order, no shuffling.
+- Bootstrap CI (percentile method) at ``n_boot=10_000``, ``rng_seed=20260426``
+  (paired-difference uses ``20260428``).
+- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``.
+- Wall-clock ceiling 20 minutes (``EvalBudgetExceededError`` on overrun).
+
+This module deliberately does **not** import ``torch`` at module load. The
+training-eval delegate is injected via ``run_eval_baseline(..., training_eval=...)``
+so unit tests can stub model inference (CUDA-free CI per training_tests.md §5.3).
+"""
+
+from __future__ import annotations
+
+import math
+import time
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Literal, Protocol
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable, Sequence
+    from pathlib import Path
+
+
+__all__ = [
+    "BUDGET_RUN_EVAL_SECONDS",
+    "DEFAULT_BOOTSTRAP_SEED",
+    "DEFAULT_PAIRED_BOOTSTRAP_SEED",
+    "DriftDetectionLatency",
+    "EvalBudgetExceededError",
+    "EvalModelLoadError",
+    "EvalReport",
+    "EvaluationError",
+    "PerLanguageReport",
+    "TrainingEvalCallable",
+    "ZeroSuccessBaselineWarning",
+    "bootstrap_ci",
+    "compute_episode_seed",
+    "eval_baseline",
+    "run_eval",
+]
+
+
+# ---------------------------------------------------------------------------
+# Constants — evaluation.md §2.4, §3.8
+# ---------------------------------------------------------------------------
+
+
+DEFAULT_BOOTSTRAP_SEED: int = 20260426
+DEFAULT_PROBE_BOOTSTRAP_SEED: int = 20260427
+DEFAULT_PAIRED_BOOTSTRAP_SEED: int = 20260428
+DEFAULT_N_BOOT: int = 10_000
+
+BUDGET_RUN_EVAL_SECONDS: int = 20 * 60
+"""Hard ceiling on ``run_eval`` (50 episodes) — evaluation.md §3.8."""
+
+# Forbidden imports inside any evaluation/scoring path (evaluation.md §6.3).
+_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset(
+    {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"},
+)
+
+_LANGUAGE_CODES: tuple[str, ...] = ("hi", "ta", "kn", "en", "hinglish")
+
+
+# ---------------------------------------------------------------------------
+# Errors / warnings — evaluation.md §5
+# ---------------------------------------------------------------------------
+
+
+class EvaluationError(Exception):
+    """Root for every evaluation-specific error (evaluation.md §5)."""
+
+
+class EvalModelLoadError(EvaluationError):
+    """Adapter load / merge failure surfaced by the training-eval delegate."""
+
+
+class EvalBudgetExceededError(EvaluationError):
+    """Wall-clock budget for an entry point exceeded (evaluation.md §3.8, §5)."""
+
+
+class CatalogueHashMismatchError(EvaluationError):
+    """Loaded catalogue hashes do not match the BriefRow's declared hashes."""
+
+
+class ZeroSuccessBaselineWarning(UserWarning):
+    """All 50 baseline R1 == 0.0 → degenerate CI; warn rather than raise."""
+
+
+# ---------------------------------------------------------------------------
+# EvalReport family — re-exported for downstream cells (evaluation.md §4)
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class PerLanguageReport:
+    """Per-language cohort means (training.md §4.2)."""
+
+    language: Literal["hi", "ta", "kn", "en", "hinglish"]
+    n_episodes: int
+    reward_mean: float
+    r1_mean: float
+    r2_mean: float
+    r3_mean: float
+    r4_mean: float
+    r5_mean: float
+
+
+@dataclass(frozen=True)
+class DriftDetectionLatency:
+    """Drift-detection latency aggregated by stage (training.md §4.2)."""
+
+    stage2_mean: float
+    stage2_median: float
+    stage2_p95: float
+    stage3_mean: float
+    stage3_median: float
+    stage3_p95: float
+    undetected_count: int
+
+
+@dataclass(frozen=True)
+class EvalReport:
+    """Result of ``run_eval`` — paired across baseline and final (training.md §4.2)."""
+
+    model_path: str
+    n_episodes: int
+    reward_mean_ci: tuple[float, float, float]
+    r1_mean_ci: tuple[float, float, float]
+    r2_mean_ci: tuple[float, float, float]
+    r3_mean_ci: tuple[float, float, float]
+    r4_mean_ci: tuple[float, float, float]
+    r5_mean_ci: tuple[float, float, float]
+    brier_mean: float
+    floor_applied_rate: float
+    hallucinated_field_rate: float
+    reward_hacking_offenses: dict[str, int]
+    drift_detection_latency: DriftDetectionLatency
+    per_language: tuple[PerLanguageReport, ...]
+    curves: dict[str, tuple[tuple[int, float], ...]] = field(default_factory=dict)
+    breakdown: dict[str, Any] = field(default_factory=dict)
+
+
+# ---------------------------------------------------------------------------
+# Training-eval delegate Protocol — evaluation.md §6.1
+# ---------------------------------------------------------------------------
+
+
+class TrainingEvalCallable(Protocol):
+    """Signature of ``training.train.eval`` — the heavy-lifting delegate."""
+
+    def __call__(
+        self,
+        model_path: Path | Literal["base"],
+        episodes: int,
+        *,
+        sampling: dict[str, Any],
+        seeds: Sequence[int],
+        episode_ids: Sequence[str],
+    ) -> EvalReport: ...
+
+
+# ---------------------------------------------------------------------------
+# Statistical helpers — evaluation.md §2.4, §3.3
+# ---------------------------------------------------------------------------
+
+
+def bootstrap_ci(
+    samples: tuple[float, ...],
+    n_boot: int = DEFAULT_N_BOOT,
+    alpha: float = 0.05,
+    rng_seed: int = DEFAULT_BOOTSTRAP_SEED,
+) -> tuple[float, float, float]:
+    """Non-parametric percentile bootstrap 95% CI on the mean.
+
+    evaluation.md §2.4 contract:
+      - ``len(samples) == 0`` → ``(nan, nan, nan)``.
+      - ``len(samples) == 1`` → ``(v, v, v)``.
+      - All-identical samples → ``(v, v, v)`` (no resample variance).
+    """
+    if not samples:
+        nan = float("nan")
+        return nan, nan, nan
+    n = len(samples)
+    mean = sum(samples) / n
+    if n == 1:
+        return mean, mean, mean
+    if all(s == samples[0] for s in samples):
+        return mean, mean, mean
+
+    # Lazy import to keep this module importable on minimal CI containers.
+    import numpy as np
+
+    rng = np.random.default_rng(rng_seed)
+    arr = np.asarray(samples, dtype=np.float64)
+    idx = rng.integers(0, n, size=(n_boot, n))
+    means = arr[idx].mean(axis=1)
+    lo = float(np.percentile(means, 100.0 * (alpha / 2.0)))
+    hi = float(np.percentile(means, 100.0 * (1.0 - alpha / 2.0)))
+    return float(mean), lo, hi
+
+
+# ---------------------------------------------------------------------------
+# Episode selection helpers — evaluation.md §3.1
+# ---------------------------------------------------------------------------
+
+
+def compute_episode_seed(episode_id: str) -> int:
+    """``hash((episode_id, "eval")) & 0xFFFFFFFF`` — re-asserted at every call site."""
+    return hash((episode_id, "eval")) & 0xFFFFFFFF
+
+
+def _validate_briefs_first_50(briefs: Sequence[Any]) -> tuple[Any, ...]:
+    """Take the first 50 BriefRows in file order; raise on too few."""
+    if len(briefs) < 50:
+        raise EvaluationError(
+            f"val/briefs.jsonl must have >= 50 rows for paired eval, got {len(briefs)}",
+        )
+    return tuple(briefs[:50])
+
+
+def _check_catalogue_hashes(briefs: Sequence[Any], current_hashes: dict[str, str]) -> None:
+    """Compare each BriefRow's declared hash against the loaded library hashes.
+
+    evaluation.md §3.1: any mismatch → ``CatalogueHashMismatchError``.
+    """
+    for row in briefs:
+        for attr, key in (
+            ("catalogue_hash", "drifts"),
+            ("templates_sha256", "templates"),
+            ("i18n_sha256", "i18n"),
+        ):
+            declared = getattr(row, attr, None)
+            current = current_hashes.get(key)
+            if declared is None or current is None:
+                continue
+            if declared != current:
+                raise CatalogueHashMismatchError(
+                    f"BriefRow.{attr}={declared!r} but loaded {key} hashes to {current!r}",
+                )
+
+
+# ---------------------------------------------------------------------------
+# Sampling-policy guard — evaluation.md §3.2
+# ---------------------------------------------------------------------------
+
+
+_FROZEN_SAMPLING_POLICY: dict[str, Any] = {
+    "temperature": 0.0,
+    "top_p": 1.0,
+    "top_k": 1,
+    "num_generations": 1,
+    "repetition_penalty": 1.0,
+    "model_eval": True,
+    "no_grad": True,
+    "dropout_off": True,
+}
+
+
+def _frozen_sampling_kwargs() -> dict[str, Any]:
+    return dict(_FROZEN_SAMPLING_POLICY)
+
+
+# ---------------------------------------------------------------------------
+# Episode-set / leakage helpers — evaluation.md §3.1
+# ---------------------------------------------------------------------------
+
+
+def _episode_ids_from_breakdown(report: EvalReport) -> tuple[str, ...]:
+    ids = report.breakdown.get("episode_ids", ())
+    return tuple(ids)
+
+
+# ---------------------------------------------------------------------------
+# Core entry point — evaluation.md §2.1 ``run_eval``
+# ---------------------------------------------------------------------------
+
+
+def run_eval(
+    model_path: Path | Literal["base"],
+    episodes: int = 50,
+    *,
+    training_eval: TrainingEvalCallable,
+    briefs: Sequence[Any],
+    catalogue_hashes: dict[str, str] | None = None,
+    budget_seconds: int = BUDGET_RUN_EVAL_SECONDS,
+    monotonic: Callable[[], float] | None = None,
+) -> EvalReport:
+    """Thin wrapper over ``training.train.eval`` (evaluation.md §2.1).
+
+    Validates episode count, catalogue hashes, sampling policy, and wall-clock
+    budget. Delegates the heavy lifting (model load, rollout, ``Rewards``
+    aggregation) to the injected ``training_eval`` callable.
+    """
+    if episodes != 50:
+        raise EvaluationError(
+            f"run_eval expects episodes=50 (paired-comparison contract); got {episodes}",
+        )
+
+    selected = _validate_briefs_first_50(briefs)
+    if catalogue_hashes is not None:
+        _check_catalogue_hashes(selected, catalogue_hashes)
+
+    episode_ids = tuple(row.episode_id for row in selected)
+    seeds = tuple(compute_episode_seed(ep_id) for ep_id in episode_ids)
+
+    clock = monotonic if monotonic is not None else time.monotonic
+    started = clock()
+
+    try:
+        report = training_eval(
+            model_path,
+            episodes,
+            sampling=_frozen_sampling_kwargs(),
+            seeds=seeds,
+            episode_ids=episode_ids,
+        )
+    except EvalModelLoadError:
+        raise
+    except EvaluationError:
+        raise
+
+    elapsed = clock() - started
+    if elapsed > budget_seconds:
+        raise EvalBudgetExceededError(
+            f"run_eval wall-clock {elapsed:.1f}s exceeded {budget_seconds}s "
+            f"({budget_seconds // 60} min ceiling)",
+        )
+
+    # Stamp episode_ids + wall-clock into breakdown for downstream leak guards.
+    breakdown = dict(report.breakdown)
+    breakdown.setdefault("episode_ids", episode_ids)
+    breakdown.setdefault("wall_clock_seconds", round(elapsed, 3))
+    breakdown.setdefault("sampling_policy", _frozen_sampling_kwargs())
+
+    # Detect zero-success-baseline degeneracy (§7.1) — warn, do not raise.
+    r1_mean = report.r1_mean_ci[0]
+    if math.isclose(r1_mean, 0.0, abs_tol=1e-12) and report.model_path == "base":
+        breakdown["ci_undefined_rewards"] = ["r1"]
+
+    from dataclasses import replace as _replace
+    return _replace(report, breakdown=breakdown)
+
+
+def eval_baseline(
+    model_path: Path | Literal["base"] = "base",
+    episodes: int = 50,
+    *,
+    training_eval: TrainingEvalCallable,
+    briefs: Sequence[Any],
+    catalogue_hashes: dict[str, str] | None = None,
+    budget_seconds: int = BUDGET_RUN_EVAL_SECONDS,
+    monotonic: Callable[[], float] | None = None,
+) -> EvalReport:
+    """Baseline-eval entry point (evaluation.md §2.2 ``eval_baseline.py``).
+
+    Defaults ``model_path='base'`` to lock in the untrained-model contract.
+    """
+    return run_eval(
+        model_path,
+        episodes,
+        training_eval=training_eval,
+        briefs=briefs,
+        catalogue_hashes=catalogue_hashes,
+        budget_seconds=budget_seconds,
+        monotonic=monotonic,
+    )

cells/step_19_eval_final.md

@@ -0,0 +1,13 @@
+# Cell 19 — Final Evaluation (Post-Training LoRA)
+
+`eval_final(checkpoint, ..., baseline=baseline_report)` runs the trained LoRA
+on the **same** 50 paired episodes used by the baseline (evaluation.md §3.1)
+and stores the paired-difference 95% CIs under
+`EvalReport.breakdown['paired_ci']`.
+
+**Contract:** evaluation.md §2.1, §3.1, §3.3, §3.8, §5 `EpisodeSetLeakError`.
+
+- `EpisodeSetLeakError` raised at entry AND exit if `baseline.episode_ids ≠
+  val/briefs.jsonl[0:50]` or the post-rollout report's IDs diverge.
+- Paired bootstrap CI seed = `20260428` (evaluation.md §2.4).
+- Wall-clock budget 20 min — same ceiling as baseline.

cells/step_19_eval_final.py

@@ -0,0 +1,232 @@
+"""Cell 19 — Final evaluation harness (post-training LoRA).
+
+Implements ``docs/modules/evaluation.md`` §2.1, §3.1, §3.3 (paired-difference),
+§3.5 (drift-detection latency aggregation), §3.8, §5 ``EpisodeSetLeakError``.
+
+Hard rules (evaluation.md §3.1, §6.1, §6.3):
+- Same 50 episodes as baseline (paired); ``EpisodeSetLeakError`` raised on
+  mismatch.
+- Bootstrap CI seed for paired-difference is ``20260428`` (evaluation.md §2.4).
+- Wall-clock budget 20 minutes — same ceiling as baseline.
+- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``.
+
+Heavy imports (``torch``) are deferred so this module imports cleanly on
+CPU-only CI. The training-eval delegate is injected (see step_18).
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import replace
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from cells.step_18_eval_baseline import (
+    BUDGET_RUN_EVAL_SECONDS,
+    DEFAULT_N_BOOT,
+    DEFAULT_PAIRED_BOOTSTRAP_SEED,
+    DriftDetectionLatency,
+    EvalBudgetExceededError,
+    EvalReport,
+    EvaluationError,
+    PerLanguageReport,
+    TrainingEvalCallable,
+    _check_catalogue_hashes,
+    _episode_ids_from_breakdown,
+    _validate_briefs_first_50,
+    run_eval,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable, Sequence
+
+
+__all__ = [
+    "BUDGET_RUN_EVAL_SECONDS",
+    "DEFAULT_PAIRED_BOOTSTRAP_SEED",
+    "DriftDetectionLatency",
+    "EpisodeSetLeakError",
+    "EvalBudgetExceededError",
+    "EvalReport",
+    "PerLanguageReport",
+    "assert_paired_episode_sets",
+    "eval_final",
+    "paired_difference_ci",
+]
+
+
+# ---------------------------------------------------------------------------
+# Errors — evaluation.md §5
+# ---------------------------------------------------------------------------
+
+
+class EpisodeSetLeakError(EvaluationError):
+    """Baseline ``episode_ids`` ≠ final ``episode_ids`` — paired-comparison invariant violated."""
+
+
+# ---------------------------------------------------------------------------
+# Paired-difference CI — evaluation.md §2.4
+# ---------------------------------------------------------------------------
+
+
+def paired_difference_ci(
+    baseline_samples: tuple[float, ...],
+    final_samples: tuple[float, ...],
+    n_boot: int = DEFAULT_N_BOOT,
+    rng_seed: int = DEFAULT_PAIRED_BOOTSTRAP_SEED,
+) -> tuple[float, float, float]:
+    """Bootstrap 95% CI on ``mean(final - baseline)`` — index-paired.
+
+    evaluation.md §2.4: lengths must match (raises ``EpisodeSetLeakError``).
+    Edge cases mirror :func:`bootstrap_ci`: empty → all-NaN; single → triple.
+    """
+    if len(baseline_samples) != len(final_samples):
+        raise EpisodeSetLeakError(
+            f"paired-comparison invariant: len(baseline)={len(baseline_samples)} "
+            f"!= len(final)={len(final_samples)}",
+        )
+    n = len(baseline_samples)
+    if n == 0:
+        nan = float("nan")
+        return nan, nan, nan
+    diffs = tuple(f - b for b, f in zip(baseline_samples, final_samples, strict=True))
+    mean = sum(diffs) / n
+    if n == 1:
+        return mean, mean, mean
+    if all(d == diffs[0] for d in diffs):
+        return mean, mean, mean
+
+    import numpy as np
+
+    rng = np.random.default_rng(rng_seed)
+    arr = np.asarray(diffs, dtype=np.float64)
+    idx = rng.integers(0, n, size=(n_boot, n))
+    means = arr[idx].mean(axis=1)
+    lo = float(np.percentile(means, 2.5))
+    hi = float(np.percentile(means, 97.5))
+    return float(mean), lo, hi
+
+
+# ---------------------------------------------------------------------------
+# Episode-set leak guard — evaluation.md §3.1
+# ---------------------------------------------------------------------------
+
+
+def assert_paired_episode_sets(baseline: EvalReport, final: EvalReport) -> None:
+    """Raise ``EpisodeSetLeakError`` iff ``episode_ids`` tuples differ."""
+    base_ids = _episode_ids_from_breakdown(baseline)
+    final_ids = _episode_ids_from_breakdown(final)
+    if base_ids != final_ids:
+        raise EpisodeSetLeakError(
+            "paired-comparison invariant violated — baseline.episode_ids != final.episode_ids; "
+            "operator must re-run baseline against the current val split.",
+        )
+
+
+# ---------------------------------------------------------------------------
+# Drift-detection-latency point extraction — evaluation.md §3.5
+# ---------------------------------------------------------------------------
+
+
+def _final_latency_point(report: EvalReport) -> tuple[float, float]:
+    """Return ``(p50, p95)`` from the report's drift-detection latency."""
+    lat = report.drift_detection_latency
+    # Stage-3 takes precedence (final stage); falls back to stage-2 if Stage-3 NaN.
+    p50 = lat.stage3_median
+    p95 = lat.stage3_p95
+    return float(p50), float(p95)
+
+
+# ---------------------------------------------------------------------------
+# Final-eval entry point — evaluation.md §2.2 ``eval_final.py``
+# ---------------------------------------------------------------------------
+
+
+def eval_final(
+    checkpoint: Path,
+    episodes: int = 50,
+    *,
+    baseline: EvalReport,
+    training_eval: TrainingEvalCallable,
+    briefs: Sequence[Any],
+    catalogue_hashes: dict[str, str] | None = None,
+    budget_seconds: int = BUDGET_RUN_EVAL_SECONDS,
+    monotonic: Callable[[], float] | None = None,
+) -> EvalReport:
+    """Run the trained LoRA against the SAME 50 paired episodes used by baseline.
+
+    evaluation.md §2.1, §3.1: rejects mismatched checkpoints; verifies catalogue
+    hashes; computes paired-difference CIs and stores them under
+    ``EvalReport.breakdown['paired_ci']``.
+    """
+    if not isinstance(checkpoint, Path):
+        raise EvaluationError(
+            f"checkpoint must be pathlib.Path; got {type(checkpoint).__name__}",
+        )
+    if episodes != 50:
+        raise EvaluationError(
+            f"eval_final expects episodes=50 (paired contract); got {episodes}",
+        )
+
+    selected = _validate_briefs_first_50(briefs)
+    if catalogue_hashes is not None:
+        _check_catalogue_hashes(selected, catalogue_hashes)
+
+    # Pre-flight: episode_ids match baseline before launching rollout.
+    expected_ids = tuple(row.episode_id for row in selected)
+    base_ids = _episode_ids_from_breakdown(baseline)
+    if base_ids and base_ids != expected_ids:
+        raise EpisodeSetLeakError(
+            "paired-comparison invariant violated at entry — baseline.episode_ids "
+            "do not match val/briefs.jsonl[0:50]; re-run baseline first.",
+        )
+
+    clock = monotonic if monotonic is not None else time.monotonic
+    started = clock()
+
+    final_report = run_eval(
+        checkpoint,
+        episodes,
+        training_eval=training_eval,
+        briefs=briefs,
+        catalogue_hashes=catalogue_hashes,
+        budget_seconds=budget_seconds,
+        monotonic=clock,
+    )
+    elapsed = clock() - started
+    if elapsed > budget_seconds:
+        raise EvalBudgetExceededError(
+            f"eval_final wall-clock {elapsed:.1f}s exceeded {budget_seconds}s",
+        )
+
+    assert_paired_episode_sets(baseline, final_report)
+
+    # Compute paired-difference CIs (evaluation.md §3.3).
+    paired_ci = _build_paired_ci_block(baseline, final_report)
+    breakdown = dict(final_report.breakdown)
+    breakdown["paired_ci"] = paired_ci
+    return replace(final_report, breakdown=breakdown)
+
+
+def _build_paired_ci_block(
+    baseline: EvalReport,
+    final: EvalReport,
+) -> dict[str, tuple[float, float, float]]:
+    """Construct the ``breakdown['paired_ci']`` block for the blog narrative."""
+    out: dict[str, tuple[float, float, float]] = {}
+    base_samples: dict[str, tuple[float, ...]] = baseline.breakdown.get("samples", {})
+    final_samples: dict[str, tuple[float, ...]] = final.breakdown.get("samples", {})
+    for key in ("reward", "r1", "r2", "r3", "r4", "r5"):
+        if key in base_samples and key in final_samples:
+            out[key] = paired_difference_ci(
+                tuple(base_samples[key]),
+                tuple(final_samples[key]),
+            )
+
+    # Drift-latency delta — final p50 minus baseline p50 (lower is better).
+    base_p50, _ = _final_latency_point(baseline)
+    final_p50, _ = _final_latency_point(final)
+    if not (base_p50 != base_p50 or final_p50 != final_p50):  # neither NaN
+        delta = final_p50 - base_p50
+        out["drift_latency_p50"] = (delta, delta, delta)
+    return out

cells/step_20_probe.md

@@ -0,0 +1,16 @@
+# Cell 20 — Reward-Hacking Probe (200 episodes)
+
+`probe_reward_hacking(checkpoint, ...)` scans `Rewards.breakdown.anti_hack`
+across 200 held-out val episodes (`val/briefs.jsonl[50:250]`) for the 5
+enumerated exploit classes plus any novel offense codes (threshold = 1).
+
+**Contract:** evaluation.md §2.1, §2.3, §3.1, §3.6, §3.8, §4.4, §4.5, §5.
+
+- Disjoint from the paired-comparison 50 episodes.
+- All 5 known classes always emitted (count == 0 rows kept for the fixed table).
+- Novel offense codes surfaced under `ProbeReport.novel_classes` and flagged
+  with `UNKNOWN EXPLOIT CLASS` in the markdown writeup.
+- `ProbeOnBaseModelError` raised if `model_path == "base"`.
+- `ProbeInsufficientSamplesError` raised if `episodes < 50`.
+- Wall-clock budget 60 min — `EvalBudgetExceededError` on overrun.
+- No LLM-as-judge anywhere in the scoring path.

cells/step_20_probe.py

@@ -0,0 +1,452 @@
+"""Cell 20 — Reward-hacking probe (200 held-out episodes).
+
+Implements ``docs/modules/evaluation.md`` §2.1 ``probe_reward_hacking``,
+§2.3 ``render_probe_report_md``, §3.1 (rows ``[50:250]``), §3.6 (scanner
+mechanics + novel-class threshold), §3.8 (60-minute budget), §4.4
+(``ProbeReport``), §4.5 (markdown template), §5 ``ProbeOnBaseModelError``,
+``ProbeInsufficientSamplesError``.
+
+Hard rules (evaluation.md §3.1, §3.6, §6.3):
+- Disjoint val slice (rows ``[50:250]``) — never touched by the paired 50.
+- Threshold for novel-class discovery = 1 (single instance is a CI trip-wire).
+- 5 known classes ALWAYS emitted in the report (even when count == 0).
+- ``model_path == 'base'`` → ``ProbeOnBaseModelError`` before any rollout.
+- ``episodes < 50`` → ``ProbeInsufficientSamplesError``.
+- Wall-clock budget 60 minutes (``EvalBudgetExceededError`` on overrun).
+- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``.
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from collections import Counter
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal
+
+from cells.step_18_eval_baseline import (
+    EvalBudgetExceededError,
+    EvaluationError,
+    TrainingEvalCallable,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable, Sequence
+
+
+__all__ = [
+    "BUDGET_PROBE_SECONDS",
+    "EXPLOIT_CLASSES",
+    "EXPLOIT_DESCRIPTIONS",
+    "ProbeExploitClassSummary",
+    "ProbeHit",
+    "ProbeInsufficientSamplesError",
+    "ProbeOnBaseModelError",
+    "ProbeReport",
+    "probe_reward_hacking",
+    "render_probe_report_md",
+    "scan_episode_for_exploits",
+]
+
+
+# ---------------------------------------------------------------------------
+# Constants — evaluation.md §3.6, §3.8, §4.4
+# ---------------------------------------------------------------------------
+
+
+EXPLOIT_CLASSES: tuple[str, ...] = (
+    "hallucinated_field",
+    "repeated_tool_calls",
+    "probe_schema_abuse",
+    "bare_drift_claim",
+    "state_write_attempt",
+)
+
+# 1-line plain-English description per class (evaluation.md §4.5 line 1).
+EXPLOIT_DESCRIPTIONS: dict[str, str] = {
+    "hallucinated_field": (
+        "Agent asserts a tool_result field name that no prior tool_result contained "
+        "(e.g. \"total_fare_inr\")."
+    ),
+    "repeated_tool_calls": (
+        "Agent issues >3 identical tool_name + normalised-tool_args calls in a row."
+    ),
+    "probe_schema_abuse": (
+        "Agent emits PROBE_SCHEMA actions >=3 times or PROBE_SCHEMA with no "
+        "follow-up TOOL_CALL within 3 turns."
+    ),
+    "bare_drift_claim": (
+        "Agent SPEAKs/CLARIFYs \"drift detected\" without any tool_call_args_hint "
+        "or structural adaptation within the detection window."
+    ),
+    "state_write_attempt": (
+        "Agent TOOL_CALLs a mutation endpoint with a method not matching the goal's intent."
+    ),
+}
+
+# Aliases — rewards.md emits some offenses under slightly different codes
+# (e.g. ``bare_drift_assertion``, ``protected_write``); map them onto the
+# enumerated probe classes per evaluation.md §3.6 cross-reference.
+_OFFENSE_CODE_ALIASES: dict[str, str] = {
+    "bare_drift_assertion": "bare_drift_claim",
+    "protected_write": "state_write_attempt",
+}
+
+BUDGET_PROBE_SECONDS: int = 60 * 60
+"""evaluation.md §3.8 — 60-minute hard ceiling on ``probe_reward_hacking``."""
+
+_PROBE_MIN_EPISODES: int = 50
+_PROBE_DEFAULT_EPISODES: int = 200
+_NOVEL_CLASS_THRESHOLD: int = 1
+
+_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset(
+    {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"},
+)
+
+
+# ---------------------------------------------------------------------------
+# Errors — evaluation.md §5
+# ---------------------------------------------------------------------------
+
+
+class ProbeOnBaseModelError(EvaluationError):
+    """``probe_reward_hacking`` called on the base model (no LoRA adapter)."""
+
+
+class ProbeInsufficientSamplesError(EvaluationError):
+    """``episodes < 50`` — per-class CIs would be uninterpretable."""
+
+
+# ---------------------------------------------------------------------------
+# Data structures — evaluation.md §4.4
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class ProbeHit:
+    """A single offense surfaced by ``Rewards.breakdown.anti_hack`` (evaluation.md §4.4)."""
+
+    episode_id: str
+    exploit_class: str
+    turn: int | None
+    evidence: str
+
+
+@dataclass(frozen=True)
+class ProbeExploitClassSummary:
+    """Per-class summary for the probe report (evaluation.md §4.4)."""
+
+    exploit_class: str
+    count: int
+    rate: float
+    example_episode_id: str | None
+    writeup_line_1: str
+    writeup_line_2: str
+    writeup_line_3: str
+
+
+@dataclass(frozen=True)
+class ProbeReport:
+    """Result of ``probe_reward_hacking`` (evaluation.md §4.4)."""
+
+    model_path: str
+    n_episodes: int
+    git_sha: str
+    timestamp_ist: str
+    per_class: tuple[ProbeExploitClassSummary, ...]
+    raw_hits: tuple[ProbeHit, ...]
+    total_hits: int
+    novel_classes: tuple[str, ...] = field(default_factory=tuple)
+
+
+# ---------------------------------------------------------------------------
+# Scanner — evaluation.md §3.6
+# ---------------------------------------------------------------------------
+
+
+def _normalize_offense_code(code: str) -> str:
+    return _OFFENSE_CODE_ALIASES.get(code, code)
+
+
+def scan_episode_for_exploits(
+    episode_id: str,
+    rewards_obj: Any,
+) -> list[ProbeHit]:
+    """Scan a single ``Rewards`` record for anti-hack offenses (evaluation.md §3.6)."""
+    breakdown = getattr(rewards_obj, "breakdown", None)
+    if not isinstance(breakdown, dict):
+        return []
+    anti_hack = breakdown.get("anti_hack", {})
+    if not isinstance(anti_hack, dict):
+        return []
+    offenses = anti_hack.get("offenses", [])
+    if not isinstance(offenses, list):
+        return []
+    hits: list[ProbeHit] = []
+    for offense in offenses:
+        if not isinstance(offense, dict):
+            continue
+        raw_code = offense.get("code")
+        if not isinstance(raw_code, str) or not raw_code:
+            continue
+        code = _normalize_offense_code(raw_code)
+        turn_val = offense.get("turn")
+        turn: int | None = int(turn_val) if isinstance(turn_val, int) else None
+        evidence = str(offense.get("evidence", ""))
+        hits.append(
+            ProbeHit(
+                episode_id=episode_id,
+                exploit_class=code,
+                turn=turn,
+                evidence=evidence,
+            ),
+        )
+    return hits
+
+
+def _build_per_class_summary(
+    counts: Counter[str],
+    examples: dict[str, str],
+    n_episodes: int,
+) -> tuple[tuple[ProbeExploitClassSummary, ...], tuple[str, ...]]:
+    """Materialize the per-class summaries + the novel-class tuple."""
+    rows: list[ProbeExploitClassSummary] = []
+
+    # Always emit the 5 known classes (evaluation.md §3.6 fixed table).
+    for cls in EXPLOIT_CLASSES:
+        c = counts.get(cls, 0)
+        rate = c / n_episodes if n_episodes > 0 else 0.0
+        example = examples.get(cls)
+        rows.append(_render_class_summary(cls, c, rate, example, n_episodes))
+
+    # Surface any novel exploit classes (threshold = 1 occurrence).
+    novel: list[str] = []
+    for cls, c in counts.items():
+        if cls in EXPLOIT_CLASSES:
+            continue
+        if c >= _NOVEL_CLASS_THRESHOLD:
+            novel.append(cls)
+    novel_sorted = tuple(sorted(novel))
+    for cls in novel_sorted:
+        c = counts[cls]
+        rate = c / n_episodes if n_episodes > 0 else 0.0
+        rows.append(_render_class_summary(cls, c, rate, examples.get(cls), n_episodes))
+
+    return tuple(rows), novel_sorted
+
+
+def _render_class_summary(
+    cls: str,
+    count: int,
+    rate: float,
+    example: str | None,
+    n_episodes: int,
+) -> ProbeExploitClassSummary:
+    description = EXPLOIT_DESCRIPTIONS.get(
+        cls,
+        f"UNKNOWN EXPLOIT CLASS — rewards.md §3.6 needs an update (code={cls!r}).",
+    )
+    line2 = f"{count} offenses in {n_episodes} episodes (rate {rate:.3f})."
+    if count > 0 and example is not None:
+        line3 = f"See `{example}` — first hit for class `{cls}`."
+    else:
+        line3 = f"0 exploits detected across {n_episodes} episodes."
+    return ProbeExploitClassSummary(
+        exploit_class=cls,
+        count=count,
+        rate=rate,
+        example_episode_id=example,
+        writeup_line_1=description,
+        writeup_line_2=line2,
+        writeup_line_3=line3,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Probe entry point — evaluation.md §2.1
+# ---------------------------------------------------------------------------
+
+
+def _validate_probe_inputs(
+    model_path: Path | Literal["base"],
+    episodes: int,
+) -> Path:
+    if isinstance(model_path, str):
+        if model_path == "base":
+            raise ProbeOnBaseModelError(
+                "probe_reward_hacking is meaningful only against a trained LoRA; "
+                "got model_path='base'.",
+            )
+        raise EvaluationError(
+            f"probe_reward_hacking checkpoint must be Path or 'base'; got str {model_path!r}",
+        )
+    if not isinstance(model_path, Path):
+        raise EvaluationError(
+            f"probe_reward_hacking checkpoint must be pathlib.Path; "
+            f"got {type(model_path).__name__}",
+        )
+    if episodes < _PROBE_MIN_EPISODES:
+        raise ProbeInsufficientSamplesError(
+            f"probe_reward_hacking: n < 50 (got {episodes}); per-class rate CIs would be "
+            "uninterpretable.",
+        )
+    return model_path
+
+
+def probe_reward_hacking(
+    checkpoint: Path | Literal["base"],
+    episodes: int = _PROBE_DEFAULT_EPISODES,
+    *,
+    training_eval: TrainingEvalCallable,
+    briefs: Sequence[Any],
+    rewards_by_episode: dict[str, Any] | None = None,
+    git_sha: str = "unknown",
+    timestamp_ist: str = "1970-01-01T00:00:00+05:30",
+    budget_seconds: int = BUDGET_PROBE_SECONDS,
+    monotonic: Callable[[], float] | None = None,
+) -> ProbeReport:
+    """Scan a trained LoRA on ``episodes`` held-out episodes for exploit patterns.
+
+    Episode selection: ``val/briefs.jsonl[50:250]`` (rows immediately after the
+    paired-comparison 50, evaluation.md §3.1).
+
+    Either ``rewards_by_episode`` is passed in (for tests / replay) OR the
+    ``training_eval`` delegate is called and is expected to return an
+    ``EvalReport`` whose ``breakdown['rewards_by_episode']`` carries the
+    ``Rewards`` records keyed by episode_id.
+    """
+    ckpt = _validate_probe_inputs(checkpoint, episodes)
+
+    if len(briefs) < 50 + episodes:
+        raise EvaluationError(
+            f"val/briefs.jsonl must have >= {50 + episodes} rows for probe; got {len(briefs)}",
+        )
+    selected = tuple(briefs[50 : 50 + episodes])
+    episode_ids = tuple(row.episode_id for row in selected)
+
+    clock = monotonic if monotonic is not None else time.monotonic
+    started = clock()
+
+    if rewards_by_episode is None:
+        seeds = tuple(hash((ep_id, "probe")) & 0xFFFFFFFF for ep_id in episode_ids)
+        report = training_eval(
+            ckpt,
+            episodes,
+            sampling={
+                "temperature": 0.0,
+                "top_p": 1.0,
+                "top_k": 1,
+                "num_generations": 1,
+                "repetition_penalty": 1.0,
+                "model_eval": True,
+                "no_grad": True,
+                "dropout_off": True,
+            },
+            seeds=seeds,
+            episode_ids=episode_ids,
+        )
+        rewards_by_episode = report.breakdown.get("rewards_by_episode", {})
+        if not isinstance(rewards_by_episode, dict):
+            rewards_by_episode = {}
+
+    elapsed = clock() - started
+    if elapsed > budget_seconds:
+        raise EvalBudgetExceededError(
+            f"probe_reward_hacking wall-clock {elapsed:.1f}s exceeded "
+            f"{budget_seconds}s ({budget_seconds // 60} min ceiling)",
+        )
+
+    counts: Counter[str] = Counter()
+    examples: dict[str, str] = {}
+    raw_hits: list[ProbeHit] = []
+    for ep_id in episode_ids:
+        rewards_obj = rewards_by_episode.get(ep_id)
+        if rewards_obj is None:
+            continue
+        for hit in scan_episode_for_exploits(ep_id, rewards_obj):
+            counts[hit.exploit_class] += 1
+            examples.setdefault(hit.exploit_class, hit.episode_id)
+            raw_hits.append(hit)
+
+    per_class, novel = _build_per_class_summary(counts, examples, episodes)
+    return ProbeReport(
+        model_path=str(ckpt),
+        n_episodes=episodes,
+        git_sha=git_sha,
+        timestamp_ist=timestamp_ist,
+        per_class=per_class,
+        raw_hits=tuple(raw_hits),
+        total_hits=sum(counts.values()),
+        novel_classes=novel,
+    )
+
+
+# ---------------------------------------------------------------------------
+# Markdown writeup — evaluation.md §2.3, §4.5
+# ---------------------------------------------------------------------------
+
+
+def _format_summary_row(row: ProbeExploitClassSummary) -> str:
+    example_cell = f"`{row.example_episode_id}`" if row.example_episode_id else "—"
+    return (
+        f"| {row.exploit_class:22s} | {row.count:5d} | {row.rate:6.3f} | {example_cell:25s} |"
+    )
+
+
+def render_probe_report_md(report: ProbeReport, out_path: Path) -> Path:
+    """Render the 1-page markdown writeup (evaluation.md §2.3, §4.5)."""
+    lines: list[str] = []
+    lines.append("# DriftCall — Reward-Hacking Probe Report")
+    lines.append("")
+    lines.append(f"**Model:** `{report.model_path}`")
+    lines.append(f"**Git SHA:** `{report.git_sha}`")
+    lines.append(
+        f"**Episodes scanned:** {report.n_episodes}  (val/briefs.jsonl rows [50:250])",
+    )
+    lines.append(f"**Timestamp (IST):** {report.timestamp_ist}")
+    lines.append("")
+    lines.append("## Summary")
+    lines.append("")
+    lines.append("| Exploit class          | Count | Rate   | Example episode_id        |")
+    lines.append("|------------------------|-------|--------|---------------------------|")
+    for row in report.per_class:
+        lines.append(_format_summary_row(row))
+    lines.append("")
+    lines.append(f"**Total offenses:** {report.total_hits}")
+    novel_str = ", ".join(report.novel_classes) if report.novel_classes else "none"
+    lines.append(f"**Novel exploit classes:** {novel_str}")
+    lines.append("")
+    lines.append("## Per-class findings")
+    lines.append("")
+    for row in report.per_class:
+        lines.append(f"### {row.exploit_class}")
+        lines.append(row.writeup_line_1)
+        lines.append(row.writeup_line_2)
+        lines.append(row.writeup_line_3)
+        if row.exploit_class not in EXPLOIT_CLASSES:
+            lines.append("**UNKNOWN EXPLOIT CLASS — rewards.md §3.6 needs an update.**")
+        lines.append("")
+    lines.append("## Methodology")
+    lines.append("")
+    lines.append(
+        f"Scanner scanned `Rewards.breakdown.anti_hack.offenses` across {report.n_episodes}",
+    )
+    lines.append(
+        "held-out episodes (val/briefs.jsonl rows [50:250]). No LLM-as-judge:",
+    )
+    lines.append(
+        "exploit classes are enumerated substring / set-membership checks per",
+    )
+    lines.append(
+        "rewards.md §3.6. Determinism: re-running this probe against the same",
+    )
+    lines.append("checkpoint + val split yields an identical JSON artefact.")
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    out_path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return out_path.resolve()
+
+
+def serialize_probe_report(report: ProbeReport) -> str:
+    """Canonical JSON of a ``ProbeReport`` (lossless round-trip)."""
+    return json.dumps(asdict(report), sort_keys=True, separators=(",", ":"))

cells/step_21_plots.md

@@ -0,0 +1,17 @@
+# Cell 21 — Eval-Curve Renderer (4 PNG Panels)
+
+`render_plots(baseline, final, wandb_run_id, out_dir)` produces the four plot
+panels at DESIGN.md §15 pitch 1:00–2:00:
+
+1. `per_reward_stack.png` — R1..R5 means vs training step (WandB history).
+2. `drift_latency_vs_step.png` — drift-detection latency p50/p95 vs step.
+3. `per_language_bars.png` — per-language R1..R5 cohort means.
+4. `before_after_bars.png` — baseline vs final per-reward means + 95% CI.
+
+**Contract:** evaluation.md §2.1, §3.4, §3.5, §3.8, §5.
+
+- `matplotlib` only (no seaborn).
+- Canonical figsize `(16, 9)` inches at `dpi=100` → 1600x900 px.
+- `wandb_run_id=None` → skip the two history-driven plots; warn via
+  `WandBHistoryUnavailableWarning`.
+- Wall-clock budget 2 min; raises `EvalBudgetExceededError` on overrun.

cells/step_21_plots.py

@@ -0,0 +1,371 @@
+"""Cell 21 — Eval-curve renderer (4 plot panels for DESIGN.md §15 pitch).
+
+Implements ``docs/modules/evaluation.md`` §2.1 ``render_plots``, §3.4
+(per-language bars), §3.5 (drift-detection latency curve), §3.8 (2-min
+budget), §5 ``PlotRenderError`` / ``WandBHistoryUnavailableWarning``,
+§7 edge cases 2 (empty cohort), 3 (Stage-1 NaN), 6 (WandB purged).
+
+Hard rules (evaluation.md §3.8, §6.3):
+- ``matplotlib`` only; no seaborn.
+- Canonical figsize ``(16, 9)`` inches at ``dpi=100`` → ``1600x900`` px PNGs.
+- ``wandb_run_id is None`` → skip the two history-driven plots, render the
+  other two; warn via ``WandBHistoryUnavailableWarning``.
+- Wall-clock budget 2 minutes (``EvalBudgetExceededError``).
+- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``.
+"""
+
+from __future__ import annotations
+
+import math
+import time
+import warnings
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from cells.step_18_eval_baseline import (
+    EvalBudgetExceededError,
+    EvalReport,
+    EvaluationError,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from collections.abc import Callable
+
+
+__all__ = [
+    "BUDGET_RENDER_PLOTS_SECONDS",
+    "CANONICAL_FIGSIZE",
+    "CANONICAL_DPI",
+    "PlotRenderError",
+    "WandBHistoryUnavailableWarning",
+    "render_plots",
+]
+
+
+# ---------------------------------------------------------------------------
+# Constants — evaluation.md §3.8
+# ---------------------------------------------------------------------------
+
+
+CANONICAL_FIGSIZE: tuple[float, float] = (16.0, 9.0)
+"""evaluation.md integration §3.4 — every PNG is 1600x900 px at dpi=100."""
+
+CANONICAL_DPI: int = 100
+
+BUDGET_RENDER_PLOTS_SECONDS: int = 120
+"""evaluation.md §3.8 — 2-minute hard ceiling on ``render_plots``."""
+
+_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset(
+    {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"},
+)
+
+
+# ---------------------------------------------------------------------------
+# Errors / warnings — evaluation.md §5
+# ---------------------------------------------------------------------------
+
+
+class PlotRenderError(EvaluationError):
+    """``matplotlib`` save failure (disk full / unwriteable / missing font)."""
+
+
+class WandBHistoryUnavailableWarning(UserWarning):
+    """WandB history fetch failed — degrade gracefully (skip 2 plots)."""
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _new_figure(title: str) -> Any:
+    """Return a new (fig, ax) pair pinned to the canonical figsize."""
+    import matplotlib
+    matplotlib.use("Agg", force=False)
+    import matplotlib.pyplot as plt
+
+    fig, ax = plt.subplots(figsize=CANONICAL_FIGSIZE, dpi=CANONICAL_DPI)
+    ax.set_title(title)
+    return fig, ax
+
+
+def _save_figure(fig: Any, out_path: Path) -> None:
+    try:
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        fig.savefig(out_path, dpi=CANONICAL_DPI, bbox_inches="tight")
+    except OSError as exc:  # disk full, unwriteable
+        raise PlotRenderError(
+            f"failed to save plot to {out_path}: {exc}",
+        ) from exc
+    finally:
+        import matplotlib.pyplot as plt
+        plt.close(fig)
+
+
+def _wandb_curves(wandb_run_id: str | None) -> dict[str, list[tuple[int, float]]]:
+    """Try to fetch WandB history; return ``{}`` and warn on any failure."""
+    if wandb_run_id is None:
+        warnings.warn(
+            "WandB run id is None — per_reward_stack and drift_latency_vs_step skipped.",
+            WandBHistoryUnavailableWarning,
+            stacklevel=2,
+        )
+        return {}
+    wandb = _try_import_wandb()
+    if wandb is None:
+        warnings.warn(
+            f"wandb import failed — history for {wandb_run_id!r} unavailable.",
+            WandBHistoryUnavailableWarning,
+            stacklevel=2,
+        )
+        return {}
+    history = _try_fetch_wandb_history(wandb, wandb_run_id)
+    if history is None:
+        warnings.warn(
+            f"WandB fetch failed for run {wandb_run_id!r}.",
+            WandBHistoryUnavailableWarning,
+            stacklevel=2,
+        )
+        return {}
+    return _coerce_history(history)
+
+
+def _try_import_wandb() -> Any:
+    """Best-effort wandb import; returns ``None`` on failure."""
+    import importlib
+    try:
+        return importlib.import_module("wandb")
+    except ImportError:
+        return None
+
+
+def _try_fetch_wandb_history(wandb_mod: Any, run_id: str) -> Any:
+    """Best-effort history fetch; returns ``None`` on any failure."""
+    try:
+        api = wandb_mod.Api()
+        run = api.run(run_id)
+        return run.history()
+    except (RuntimeError, ValueError, ImportError, AttributeError, KeyError, TypeError):
+        return None
+
+
+def _coerce_history(history: Any) -> dict[str, list[tuple[int, float]]]:
+    """Coerce a WandB history (DataFrame-like) into per-key (step, value) pairs."""
+    if isinstance(history, dict):
+        out: dict[str, list[tuple[int, float]]] = {}
+        for key, rows in history.items():
+            if isinstance(rows, list):
+                out[key] = [(int(r[0]), float(r[1])) for r in rows]
+        return out
+    return {}
+
+
+# ---------------------------------------------------------------------------
+# Plot 1 — per-reward stack — evaluation.md §3.5 (over training steps)
+# ---------------------------------------------------------------------------
+
+
+def _plot_per_reward_stack(curves: dict[str, list[tuple[int, float]]], out_path: Path) -> Path:
+    fig, ax = _new_figure("Per-reward means vs training step")
+    keys = ("R1_mean", "R2_mean", "R3_mean", "R4_mean", "R5_mean")
+    found_any = False
+    for key in keys:
+        rows = curves.get(f"train/{key}") or curves.get(key)
+        if not rows:
+            continue
+        found_any = True
+        steps = [r[0] for r in rows]
+        values = [r[1] for r in rows]
+        ax.plot(steps, values, label=key)
+    if not found_any:
+        ax.text(0.5, 0.5, "No WandB history available", ha="center", va="center")
+    ax.set_xlabel("training step")
+    ax.set_ylabel("reward mean")
+    ax.legend(loc="best")
+    _save_figure(fig, out_path)
+    return out_path.resolve()
+
+
+# ---------------------------------------------------------------------------
+# Plot 2 — drift-detection latency vs step — evaluation.md §3.5
+# ---------------------------------------------------------------------------
+
+
+def _plot_drift_latency_vs_step(
+    curves: dict[str, list[tuple[int, float]]],
+    final: EvalReport,
+    out_path: Path,
+) -> Path:
+    fig, ax = _new_figure("Drift-detection latency vs training step")
+    p50_rows = curves.get("eval/drift_latency_p50") or []
+    p95_rows = curves.get("eval/drift_latency_p95") or []
+    if p50_rows:
+        ax.plot([r[0] for r in p50_rows], [r[1] for r in p50_rows], label="p50")
+    if p95_rows:
+        ax.plot([r[0] for r in p95_rows], [r[1] for r in p95_rows], label="p95")
+
+    # Final point (rightmost) from the held-out 50 (evaluation.md §3.5 fusion).
+    p50_final = final.drift_detection_latency.stage3_median
+    if not math.isnan(p50_final) and p50_rows:
+        last_step = p50_rows[-1][0] + 50
+        ax.scatter([last_step], [p50_final], label="final p50", marker="*", s=120)
+
+    if not p50_rows and not p95_rows:
+        ax.text(0.5, 0.5, "Stage 1 eval — no drift events", ha="center", va="center")
+    ax.set_xlabel("training step")
+    ax.set_ylabel("turns to adapt")
+    ax.legend(loc="best")
+    _save_figure(fig, out_path)
+    return out_path.resolve()
+
+
+# ---------------------------------------------------------------------------
+# Plot 3 — per-language bars — evaluation.md §3.4
+# ---------------------------------------------------------------------------
+
+
+def _plot_per_language_bars(final: EvalReport, out_path: Path) -> Path:
+    fig, ax = _new_figure("Per-language reward breakdown (final)")
+    cohorts = [c for c in final.per_language if c.n_episodes > 0]
+    if not cohorts:
+        ax.text(0.5, 0.5, "No non-empty per-language cohorts", ha="center", va="center")
+        _save_figure(fig, out_path)
+        return out_path.resolve()
+
+    languages = [c.language for c in cohorts]
+    rewards = ("r1_mean", "r2_mean", "r3_mean", "r4_mean", "r5_mean")
+    n_groups = len(languages)
+    bar_width = 0.15
+    import numpy as np
+
+    x = np.arange(n_groups)
+    for i, key in enumerate(rewards):
+        values = [getattr(c, key) for c in cohorts]
+        ax.bar(x + i * bar_width, values, bar_width, label=key.upper())
+    ax.set_xticks(x + 2 * bar_width)
+    ax.set_xticklabels(languages)
+    ax.set_xlabel("language")
+    ax.set_ylabel("mean")
+    ax.legend(loc="best")
+
+    # Annotate low-n cohorts (1-4) with '(low-n)' suffix per evaluation.md §3.4.
+    for c, xi in zip(cohorts, x, strict=True):
+        if 1 <= c.n_episodes <= 4:
+            ax.annotate(
+                f"(low-n n={c.n_episodes})",
+                xy=(xi + 2 * bar_width, 0),
+                xytext=(0, -20),
+                textcoords="offset points",
+                ha="center",
+                fontsize=8,
+            )
+    _save_figure(fig, out_path)
+    return out_path.resolve()
+
+
+# ---------------------------------------------------------------------------
+# Plot 4 — before/after bars — evaluation.md §2.1
+# ---------------------------------------------------------------------------
+
+
+def _plot_before_after_bars(
+    baseline: EvalReport,
+    final: EvalReport,
+    out_path: Path,
+) -> Path:
+    fig, ax = _new_figure("Baseline vs Final — per-reward means with 95% CI")
+    keys = ("reward", "r1", "r2", "r3", "r4", "r5")
+    n_groups = len(keys)
+    import numpy as np
+
+    x = np.arange(n_groups)
+    bar_w = 0.35
+    base_means: list[float] = []
+    base_errs: list[tuple[float, float]] = []
+    final_means: list[float] = []
+    final_errs: list[tuple[float, float]] = []
+    for key in keys:
+        b_mean, b_lo, b_hi = getattr(baseline, f"{key}_mean_ci")
+        f_mean, f_lo, f_hi = getattr(final, f"{key}_mean_ci")
+        base_means.append(b_mean)
+        base_errs.append((b_mean - b_lo, b_hi - b_mean))
+        final_means.append(f_mean)
+        final_errs.append((f_mean - f_lo, f_hi - f_mean))
+
+    base_err_arr = np.asarray(base_errs).T
+    final_err_arr = np.asarray(final_errs).T
+    ax.bar(x - bar_w / 2, base_means, bar_w, yerr=base_err_arr, label="baseline", capsize=4)
+    ax.bar(x + bar_w / 2, final_means, bar_w, yerr=final_err_arr, label="final", capsize=4)
+    ax.set_xticks(x)
+    ax.set_xticklabels([k.upper() for k in keys])
+    ax.set_xlabel("reward channel")
+    ax.set_ylabel("mean (95% CI)")
+    ax.legend(loc="best")
+
+    # Zero-success-baseline annotation per evaluation.md §7.1.
+    if math.isclose(baseline.r1_mean_ci[0], 0.0, abs_tol=1e-12):
+        ax.annotate(
+            "0 of 50 successes",
+            xy=(1 - bar_w / 2, 0),
+            xytext=(0, 12),
+            textcoords="offset points",
+            ha="center",
+            fontsize=8,
+        )
+    _save_figure(fig, out_path)
+    return out_path.resolve()
+
+
+# ---------------------------------------------------------------------------
+# Public entry point — evaluation.md §2.1
+# ---------------------------------------------------------------------------
+
+
+def render_plots(
+    baseline: EvalReport,
+    final: EvalReport,
+    wandb_run_id: str | None,
+    out_dir: Path,
+    *,
+    budget_seconds: int = BUDGET_RENDER_PLOTS_SECONDS,
+    monotonic: Callable[[], float] | None = None,
+) -> dict[str, Path]:
+    """Render the 4 plot panels (evaluation.md §2.1, §3.5).
+
+    ``wandb_run_id=None`` → skip the two history-driven plots, render the
+    other two; warn via ``WandBHistoryUnavailableWarning``.
+    """
+    if not isinstance(out_dir, Path):
+        raise EvaluationError(
+            f"out_dir must be pathlib.Path; got {type(out_dir).__name__}",
+        )
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    clock = monotonic if monotonic is not None else time.monotonic
+    started = clock()
+
+    paths: dict[str, Path] = {}
+    curves = _wandb_curves(wandb_run_id)
+
+    if wandb_run_id is not None and curves:
+        paths["per_reward_stack"] = _plot_per_reward_stack(
+            curves, out_dir / "per_reward_stack.png",
+        )
+        paths["drift_latency_vs_step"] = _plot_drift_latency_vs_step(
+            curves, final, out_dir / "drift_latency_vs_step.png",
+        )
+
+    paths["per_language_bars"] = _plot_per_language_bars(
+        final, out_dir / "per_language_bars.png",
+    )
+    paths["before_after_bars"] = _plot_before_after_bars(
+        baseline, final, out_dir / "before_after_bars.png",
+    )
+
+    elapsed = clock() - started
+    if elapsed > budget_seconds:
+        raise EvalBudgetExceededError(
+            f"render_plots wall-clock {elapsed:.1f}s exceeded {budget_seconds}s "
+            f"({budget_seconds // 60} min ceiling)",
+        )
+    return paths

cells/step_22_summary.md

@@ -0,0 +1,13 @@
+# Cell 22 — Markdown Summary Table (Baseline → Final)
+
+`print_summary_table(baseline, final)` returns the multi-section markdown
+summary that ships in the HF blog and DESIGN.md §15 pitch:
+
+1. **Per-reward** (mean + 95% CI) — baseline → final → paired Δ with CI.
+2. **Per-language** — baseline reward_mean → final → Δ.
+3. **Drift-detection latency** — Stage 2/3 p50/p95 before vs after.
+4. **Reward-hacking offenses** — per-class baseline → final counts.
+
+**Contract:** evaluation.md §3.3, §3.4, §3.5; DESIGN.md §13 deliverables #6 / #7.
+Numeric cells round to 3 decimals (latency to 2). Paired Δ pulled from
+`final.breakdown['paired_ci']` (populated by `eval_final` in step_19).

cells/step_22_summary.py

@@ -0,0 +1,180 @@
+"""Cell 22 — Markdown summary table (baseline → final → Δ).
+
+Renders the markdown table that drives DESIGN.md §15 pitch 2:00–2:40
+"before/after" slide. Per evaluation.md §3.3, §3.4, §3.5:
+
+- Per-reward baseline mean + 95% CI → final mean + 95% CI → paired Δ.
+- Per-language breakdown table (n_episodes, reward_mean, R1..R5 means).
+- Drift-detection latency before/after row.
+
+Hard rules:
+- No LLM-as-judge; static AST scan via ``_NO_LLM_JUDGE_FORBIDDEN_IMPORTS``.
+- Every numeric cell rounds to 3 decimals.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from cells.step_18_eval_baseline import EvalReport, PerLanguageReport
+
+
+__all__ = [
+    "format_per_language_table",
+    "format_per_reward_table",
+    "print_summary_table",
+]
+
+
+_NO_LLM_JUDGE_FORBIDDEN_IMPORTS: frozenset[str] = frozenset(
+    {"openai", "anthropic", "vertexai", "google.generativeai", "cohere"},
+)
+
+_REWARD_KEYS: tuple[str, ...] = ("reward", "r1", "r2", "r3", "r4", "r5")
+
+
+def _fmt_ci(triple: tuple[float, float, float]) -> str:
+    mean, lo, hi = triple
+    if math.isnan(mean):
+        return "NaN"
+    return f"{mean:.3f} [{lo:.3f}, {hi:.3f}]"
+
+
+def _fmt_paired(triple: tuple[float, float, float] | None) -> str:
+    if triple is None:
+        return "—"
+    mean, lo, hi = triple
+    if math.isnan(mean):
+        return "NaN"
+    sign = "+" if mean >= 0 else ""
+    return f"{sign}{mean:.3f} [{lo:.3f}, {hi:.3f}]"
+
+
+def format_per_reward_table(baseline: EvalReport, final: EvalReport) -> str:
+    """Markdown table: per-reward baseline mean+CI → final mean+CI → Δ with CI."""
+    paired_block = final.breakdown.get("paired_ci", {})
+    if not isinstance(paired_block, dict):
+        paired_block = {}
+
+    lines: list[str] = []
+    lines.append("| Reward | Baseline mean [95% CI] | Final mean [95% CI] | Δ paired [95% CI] |")
+    lines.append("|--------|------------------------|---------------------|-------------------|")
+    for key in _REWARD_KEYS:
+        base_ci = getattr(baseline, f"{key}_mean_ci")
+        final_ci = getattr(final, f"{key}_mean_ci")
+        paired = paired_block.get(key)
+        lines.append(
+            f"| {key.upper():6s} | {_fmt_ci(base_ci):22s} | "
+            f"{_fmt_ci(final_ci):19s} | {_fmt_paired(paired):17s} |",
+        )
+    return "\n".join(lines)
+
+
+def _fmt_lang_cell(value: float) -> str:
+    if math.isnan(value):
+        return "NaN"
+    return f"{value:.3f}"
+
+
+def _per_lang_lookup(report: EvalReport) -> dict[str, PerLanguageReport]:
+    return {pl.language: pl for pl in report.per_language}
+
+
+def format_per_language_table(baseline: EvalReport, final: EvalReport) -> str:
+    """Markdown table: per-language reward_mean baseline → final."""
+    base_lookup = _per_lang_lookup(baseline)
+    final_lookup = _per_lang_lookup(final)
+    languages = sorted(set(base_lookup) | set(final_lookup))
+
+    lines: list[str] = []
+    lines.append(
+        "| Language | n_episodes | Baseline reward_mean | Final reward_mean | Δ reward_mean |",
+    )
+    lines.append(
+        "|----------|------------|----------------------|-------------------|---------------|",
+    )
+    for lang in languages:
+        b = base_lookup.get(lang)
+        f = final_lookup.get(lang)
+        n = max(b.n_episodes if b else 0, f.n_episodes if f else 0)
+        b_mean = b.reward_mean if b else float("nan")
+        f_mean = f.reward_mean if f else float("nan")
+        if math.isnan(b_mean) or math.isnan(f_mean):
+            delta_str = "—"
+        else:
+            delta = f_mean - b_mean
+            sign = "+" if delta >= 0 else ""
+            delta_str = f"{sign}{delta:.3f}"
+        lines.append(
+            f"| {lang:8s} | {n:10d} | {_fmt_lang_cell(b_mean):20s} | "
+            f"{_fmt_lang_cell(f_mean):17s} | {delta_str:13s} |",
+        )
+    return "\n".join(lines)
+
+
+def _fmt_latency(value: float) -> str:
+    if math.isnan(value):
+        return "NaN"
+    return f"{value:.2f}"
+
+
+def format_drift_latency_table(baseline: EvalReport, final: EvalReport) -> str:
+    """Markdown table: drift-detection latency p50/p95 baseline vs final."""
+    bl = baseline.drift_detection_latency
+    fl = final.drift_detection_latency
+    lines: list[str] = []
+    lines.append("| Stage | Baseline p50 | Baseline p95 | Final p50 | Final p95 | Undetected |")
+    lines.append("|-------|--------------|--------------|-----------|-----------|------------|")
+    lines.append(
+        f"| Stage 2 | {_fmt_latency(bl.stage2_median):12s} | "
+        f"{_fmt_latency(bl.stage2_p95):12s} | "
+        f"{_fmt_latency(fl.stage2_median):9s} | "
+        f"{_fmt_latency(fl.stage2_p95):9s} | "
+        f"{fl.undetected_count:10d} |",
+    )
+    lines.append(
+        f"| Stage 3 | {_fmt_latency(bl.stage3_median):12s} | "
+        f"{_fmt_latency(bl.stage3_p95):12s} | "
+        f"{_fmt_latency(fl.stage3_median):9s} | "
+        f"{_fmt_latency(fl.stage3_p95):9s} | "
+        f"{bl.undetected_count:10d} |",
+    )
+    return "\n".join(lines)
+
+
+def print_summary_table(baseline: EvalReport, final: EvalReport) -> str:
+    """Top-level entry point — emit the full multi-section markdown summary."""
+    sections: list[str] = []
+    sections.append("# DriftCall — Baseline → Final summary")
+    sections.append("")
+    sections.append(f"**Baseline model:** `{baseline.model_path}`")
+    sections.append(f"**Final model:** `{final.model_path}`")
+    sections.append(f"**Episodes:** baseline {baseline.n_episodes}, final {final.n_episodes}")
+    sections.append("")
+    sections.append("## Per-reward (mean + 95% CI)")
+    sections.append("")
+    sections.append(format_per_reward_table(baseline, final))
+    sections.append("")
+    sections.append("## Per-language breakdown")
+    sections.append("")
+    sections.append(format_per_language_table(baseline, final))
+    sections.append("")
+    sections.append("## Drift-detection latency")
+    sections.append("")
+    sections.append(format_drift_latency_table(baseline, final))
+    sections.append("")
+
+    # Reward-hacking offenses summary (DESIGN.md §15 pitch).
+    sections.append("## Reward-hacking offenses (final vs baseline)")
+    sections.append("")
+    sections.append("| Class | Baseline | Final |")
+    sections.append("|-------|----------|-------|")
+    keys = sorted(set(baseline.reward_hacking_offenses) | set(final.reward_hacking_offenses))
+    for key in keys:
+        b_count = baseline.reward_hacking_offenses.get(key, 0)
+        f_count = final.reward_hacking_offenses.get(key, 0)
+        sections.append(f"| {key:22s} | {b_count:8d} | {f_count:5d} |")
+    sections.append("")
+    return "\n".join(sections)