Add living project map documenting all modules and relationships

docs/map/ covers: models, scenarios, agents, validation, scoring
(planned), server, frontend, config, and tests. Updated after each
implementation session to serve as codebase memory.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/map/README.md

@@ -0,0 +1,115 @@
+# ReplicaLab Project Map
+
+> Living reference of every module, class, function, and relationship.
+> Updated after each implementation session.
+>
+> **Last updated:** 2026-03-07
+
+## Module Index
+
+| File | What it covers |
+|------|---------------|
+| [models.md](models.md) | Data contracts — actions, observations, protocol, reward, episode state |
+| [scenarios.md](scenarios.md) | Scenario generation — templates, constraints, resources, hidden specs |
+| [agents.md](agents.md) | Agent policies — scientist prompt/parse/retry, lab manager feasibility/suggest/compose |
+| [validation.md](validation.md) | Protocol validation — deterministic checks against scenario constraints |
+| [scoring.md](scoring.md) | Judge scoring — rigor, feasibility, fidelity (NOT YET IMPLEMENTED) |
+| [server.md](server.md) | FastAPI server — REST + WebSocket endpoints, stub environment |
+| [frontend.md](frontend.md) | React UI — dashboard, episode viewer, components |
+| [config.md](config.md) | Shared constants — rounds, budget, timeouts |
+| [tests.md](tests.md) | Test coverage — 87 tests across 6 files |
+
+## Dependency Graph
+
+```
+server/app.py
+ ├── replicalab.config
+ ├── replicalab.models
+ ├── replicalab.scenarios (generate_scenario, available_scenario_families)
+ └── replicalab.agents (check_feasibility, suggest_alternative, compose_lab_manager_response)
+
+replicalab/agents/scientist_policy.py
+ ├── replicalab.models (ScientistAction, ScientistObservation, Protocol, ConversationEntry)
+ └── replicalab.scenarios (NormalizedScenarioPack)
+
+replicalab/agents/lab_manager_policy.py
+ ├── replicalab.models (LabManagerAction, LabManagerActionType, Protocol)
+ ├── replicalab.scenarios (NormalizedScenarioPack)
+ └── replicalab.utils.validation (ValidationResult, validate_protocol)
+
+replicalab/scenarios/templates.py
+ ├── replicalab.config (MAX_BUDGET, MAX_ROUNDS)
+ ├── replicalab.models (ScientistObservation, LabManagerObservation)
+ ├── replicalab.scenarios.{math_reasoning, ml_benchmark, finance_trading}
+ └── replicalab.utils.seed (seed_rng)
+
+replicalab/utils/validation.py
+ ├── replicalab.models (Protocol)
+ └── replicalab.scenarios.templates (NormalizedScenarioPack)
+
+replicalab/scoring/           <-- NOT YET IMPLEMENTED
+ ├── replicalab.models (Protocol, RewardBreakdown)
+ ├── replicalab.scenarios (NormalizedScenarioPack, HiddenReferenceSpec)
+ └── replicalab.agents.lab_manager_policy (check_feasibility, FeasibilityCheckResult)
+```
+
+## File Tree (implemented only)
+
+```
+replicalab/
+ ├── __init__.py              (empty)
+ ├── config.py                (shared constants)
+ ├── models.py                (25 classes — all data contracts)
+ ├── agents/
+ │   ├── __init__.py          (re-exports from submodules)
+ │   ├── scientist_policy.py  (AGT 01-04: prompt, formatter, parser, retry, baseline)
+ │   └── lab_manager_policy.py(AGT 05-07: feasibility, suggest, compose)
+ ├── scenarios/
+ │   ├── __init__.py          (re-exports from templates)
+ │   ├── templates.py         (NormalizedScenarioPack, generate_scenario, apply_difficulty)
+ │   ├── math_reasoning.py    (2 cases: Cauchy-Schwarz, Jensen's inequality)
+ │   ├── ml_benchmark.py      (2 cases: AG News TinyBERT, CIFAR-10 ResNet-18)
+ │   └── finance_trading.py   (2 cases: SPY/QQQ mean-reversion, momentum futures)
+ ├── scoring/                 <-- EMPTY (JDG 01-03 not yet built)
+ │   └── .gitkeep
+ └── utils/
+     ├── seed.py              (deterministic RNG from SHA256)
+     └── validation.py        (MOD 05: protocol validation, 5 checks)
+
+server/
+ └── app.py                   (FastAPI + WebSocket + _StubEnv)
+
+frontend/
+ ├── package.json             (React 19, Three.js, Framer Motion, Recharts, Tailwind)
+ ├── src/
+ │   ├── App.tsx              (router: /, /episode, /episode/:id)
+ │   ├── types/index.ts       (TypeScript interfaces mirroring Python models)
+ │   ├── lib/
+ │   │   ├── api.ts           (REST + WebSocket client + mock data generators)
+ │   │   ├── audio.ts         (audio utilities)
+ │   │   └── utils.ts         (shared helpers)
+ │   ├── components/          (15 React components)
+ │   └── pages/               (DashboardPage, EpisodePage)
+ └── vite.config.ts
+
+tests/
+ ├── test_config.py           (3 tests)
+ ├── test_models.py           (15 tests)
+ ├── test_scenarios.py        (8 tests)
+ ├── test_validation.py       (13 tests)
+ ├── test_scientist_policy.py (18 tests)
+ └── test_lab_manager_policy.py(13 tests)
+```
+
+## Task Completion Status
+
+| Area | Done | Remaining | Key gaps |
+|------|------|-----------|----------|
+| Models (MOD) | MOD 01-05, 09, 11-12 | MOD 06 | Semantic validators for impossible plans |
+| Scenarios (SCN) | SCN 01-12 | SCN 13 | Booking/scheduling data model |
+| Agents (AGT) | AGT 01-07, 11 | AGT 08-10 | LLM-backed scientist, model selection |
+| Judge (JDG) | — | JDG 01-08 | Entire scoring engine |
+| Environment (ENV) | — | ENV 01-11 | Entire real environment |
+| Server (API) | API 01-04, 06 (partial) | API 05, 07-10 | Replay, auth, rate limiting |
+| Frontend (FND) | FND 01-10 | — | Complete |
+| Training (TRN) | — | TRN 01-18 | Entire RL pipeline |

docs/map/agents.md

@@ -0,0 +1,287 @@
+# Agents Map — `replicalab/agents/`
+
+> Deterministic policy helpers for Scientist and Lab Manager agents.
+> No LLM calls in this module — the LLM backend is injected via `GenerateFn`.
+>
+> **Tasks implemented:** AGT 01-07, 11
+
+## Exports — `__init__.py`
+
+```python
+# From lab_manager_policy
+AlternativeSuggestion, FeasibilityCheckResult, SuggestionChange
+check_feasibility, compose_lab_manager_response, suggest_alternative
+
+# From scientist_policy
+RetryMetadata, ScientistCallResult, ScientistOutputParseError
+build_baseline_scientist_action, build_scientist_system_prompt
+call_scientist_with_retry, format_scientist_observation, parse_scientist_output
+```
+
+---
+
+## Scientist Policy — `scientist_policy.py`
+
+### Pipeline Flow
+
+```
+scenario → build_scientist_system_prompt() → system_prompt
+                                                    ↓
+observation → format_scientist_observation() → user_message
+                                                    ↓
+              call_scientist_with_retry(generate_fn, system_prompt, obs)
+                   ↓ calls generate_fn(messages)
+                   ↓ calls parse_scientist_output(raw_text)
+                   ↓ on failure: _build_correction_prompt(error)
+                   ↓ retries up to max_retries times
+                   → ScientistCallResult(action, metadata)
+```
+
+### Public Functions
+
+#### `build_scientist_system_prompt(scenario) -> str` — AGT 01
+Builds a domain-neutral system prompt from a `NormalizedScenarioPack`.
+
+**Sections rendered (in order):**
+1. Role statement ("You are the Scientist agent in ReplicaLab")
+2. Job description (negotiate strongest feasible plan)
+3. Domain ID
+4. Task summary
+5. Success criteria (bulleted)
+6. Constraints (with hard/soft labels, quantities, comparators)
+7. Available resources (with availability status)
+8. Allowed substitutions (original → alternative with conditions)
+9. Output contract (exactly one JSON, no extra keys)
+10. Allowed action_type values
+11. Action-specific field requirements
+
+#### `format_scientist_observation(obs: ScientistObservation) -> str` — AGT 02
+Converts a per-turn observation into the user message string.
+
+**Sections (fixed order, tested):**
+1. Round status: `"Round {n} of {max}"`
+2. Paper summary: title, hypothesis, method, key finding, goal
+3. Conversation history or "No conversation history yet"
+4. Current protocol or "No protocol has been proposed yet"
+5. ScientistAction schema reminder (field list, action_type values)
+6. Closing instruction: "Respond with exactly one JSON object"
+
+#### `parse_scientist_output(raw_text: str) -> ScientistAction` — MOD 09
+Strict parser from raw model text into validated `ScientistAction`.
+
+**Accepts:**
+- Plain JSON objects
+- `\`\`\`json` fenced blocks
+- Prose containing one JSON object
+
+**Error codes:**
+| Code | Meaning |
+|------|---------|
+| `no_json` | No JSON object found in output |
+| `invalid_json` | JSON syntax error (trailing comma, etc.) |
+| `invalid_action` | Valid JSON but fails ScientistAction validation |
+
+#### `call_scientist_with_retry(generate_fn, system_prompt, observation, max_retries=2) -> ScientistCallResult` — AGT 03
+Retry loop with error-specific correction prompts.
+
+**Behavior:**
+1. Builds messages: `[system, user]`
+2. Calls `generate_fn(messages)` → raw text
+3. Calls `parse_scientist_output(raw_text)`
+4. On success: returns `ScientistCallResult(action, metadata)`
+5. On failure: appends `[assistant(bad_output), user(correction)]` to messages, retries
+6. After `max_retries` failures: raises last `ScientistOutputParseError`
+
+**Correction prompts (`_build_correction_prompt`):**
+- `no_json`: "Your previous response did not contain a JSON object..."
+- `invalid_json`: "Your previous response contained malformed JSON: {error}..."
+- `invalid_action`: "...failed ScientistAction validation: {detail}. Fix the validation error..."
+
+#### `build_baseline_scientist_action(observation) -> ScientistAction` — AGT 04
+Deterministic non-LLM action for smoke tests. No API calls.
+
+**Decision tree:**
+1. If protocol exists AND at max rounds → `accept`
+2. If protocol exists AND latest lab_manager feedback indicates blocker → `revise_protocol` (halve sample, reduce duration)
+3. If protocol exists AND no blocker → `accept`
+4. If no protocol → `propose_protocol` (domain-inferred defaults)
+
+**Domain inference (`_infer_domain`):**
+- Checks paper fields for ML hints (benchmark, dataset, gpu, bert...) → `machine_learning`
+- Checks for finance hints (backtest, sharpe, trading...) → `finance_trading`
+- Default → `mathematics`
+
+**Blocker detection (`_feedback_indicates_blocker`):**
+- Returns `False` if action_type is `accept` or `report_feasibility`
+- Otherwise checks message for blocker hints: booked, unavailable, exceeds, tight, budget, cost, etc.
+
+### Classes
+
+#### `ScientistOutputParseError(ValueError)`
+| Attribute | Type | Purpose |
+|-----------|------|---------|
+| `code` | `Literal["no_json", "invalid_json", "invalid_action"]` | Machine-readable error type |
+| `message` | `str` | Human-readable detail |
+| `raw_text` | `str` | Original model output |
+| `parsed_payload` | `dict \| None` | Decoded JSON if parsing succeeded |
+
+#### `RetryMetadata(BaseModel)` — `extra="forbid"`
+| Field | Type | Purpose |
+|-------|------|---------|
+| `attempt_count` | `int` | Total attempts (1 = success on first try) |
+| `retry_count` | `int` | `attempt_count - 1` |
+| `last_error_code` | `str \| None` | Error code from last failure |
+| `last_error_message` | `str \| None` | Error message from last failure |
+
+#### `ScientistCallResult(BaseModel)` — `extra="forbid"`
+| Field | Type |
+|-------|------|
+| `action` | `ScientistAction` |
+| `metadata` | `RetryMetadata` |
+
+### Type Aliases
+
+```python
+GenerateFn = Callable[[list[dict[str, str]]], str]
+```
+
+### Constants
+
+```python
+_ML_HINTS = ("benchmark", "dataset", "accuracy", "tokenizer", "train", "gpu", ...)
+_FINANCE_HINTS = ("backtest", "drawdown", "sharpe", "trading", "slippage", ...)
+_BLOCKER_HINTS = ("booked", "unavailable", "exceeds", "tight", "budget", "cost", ...)
+```
+
+---
+
+## Lab Manager Policy — `lab_manager_policy.py`
+
+### Pipeline Flow
+
+```
+protocol + scenario → check_feasibility()
+                           ↓
+                    FeasibilityCheckResult (7 dimensions)
+                           ↓
+              suggest_alternative(protocol, check, scenario)
+                           ↓
+              AlternativeSuggestion | None
+                           ↓
+              compose_lab_manager_response(check, suggestion)
+                           ↓
+                    LabManagerAction (typed, with explanation)
+```
+
+### Public Functions
+
+#### `check_feasibility(protocol, scenario) -> FeasibilityCheckResult` — AGT 05
+Runs 7 deterministic dimension checks. No LLM calls.
+
+**Checks performed:**
+| Dimension | Function | What it checks |
+|-----------|----------|---------------|
+| `protocol` | `_build_protocol_check` | Wraps `validate_protocol()` from MOD 05 |
+| `budget` | `_check_budget` | `_estimate_protocol_cost()` vs `budget_remaining` |
+| `equipment` | `_check_equipment` | Items available/booked, finds substitutions |
+| `reagents` | `_check_reagents` | Items in-stock/out-of-stock, finds substitutions |
+| `schedule` | `_check_schedule` | `duration_days` vs `time_limit_days` |
+| `staff` | `_check_staff` | `_estimate_staff_load()` vs `staff_count` |
+| `policy` | `_check_policy` | Safety restrictions (e.g., offline-only execution) |
+
+**Cost estimation (`_estimate_protocol_cost`):**
+```
+base = sample_size * 10
++ duration_days * 50
++ len(controls) * 25
++ len(required_equipment) * 100
++ len(required_reagents) * 75
+```
+
+**Staff estimation (`_estimate_staff_load`):**
+```
+base = 1
++ (1 if sample_size > 20)
++ (1 if len(controls) > 2)
++ (1 if duration_days > 5)
++ (1 if len(required_equipment) > 2)
+```
+
+#### `suggest_alternative(protocol, check_result, scenario) -> AlternativeSuggestion | None` — AGT 06
+Deterministic revision engine. Returns `None` if already feasible.
+
+**Fix order (deterministic):**
+1. Equipment substitutions — replace booked items with alternatives
+2. Reagent substitutions — replace out-of-stock items with alternatives
+3. Duration clamp — reduce to `time_limit_days` if over
+4. Sample size reduction — iterative halving until budget fits (max 10 iterations)
+
+**Post-fix recheck:** runs `check_feasibility()` on revised protocol.
+**Returns:** revised protocol, list of changes, remaining failures, pre/post checks.
+
+#### `compose_lab_manager_response(check_result, suggestion=None, explanation_renderer=None) -> LabManagerAction` — AGT 07
+Converts grounded results into a typed `LabManagerAction`.
+
+**Action type selection (`_select_lab_manager_action_type`):**
+| Condition | Action |
+|-----------|--------|
+| All 7 dimensions pass | `ACCEPT` |
+| Suggestion exists AND improved AND only non-lab failures remain | `SUGGEST_ALTERNATIVE` |
+| Lab constraints fail AND no suggestion | `REJECT` |
+| Only policy/protocol fail (not lab constraints) | `REPORT_FEASIBILITY` |
+| Suggestion exists but didn't improve | `REJECT` |
+
+**Lab constraints = budget, equipment, reagents, schedule, staff (not protocol, not policy).**
+
+### Classes
+
+#### `DimensionCheck(BaseModel)` — `extra="forbid"`
+| Field | Type | Default |
+|-------|------|---------|
+| `ok` | `bool` | `True` |
+| `reasons` | `list[str]` | `[]` |
+
+#### `FeasibilityCheckResult(BaseModel)` — `extra="forbid"`
+| Field | Type |
+|-------|------|
+| `protocol` | `DimensionCheck` |
+| `budget` | `DimensionCheck` |
+| `equipment` | `DimensionCheck` |
+| `reagents` | `DimensionCheck` |
+| `schedule` | `DimensionCheck` |
+| `staff` | `DimensionCheck` |
+| `policy` | `DimensionCheck` |
+| `estimated_cost` | `float` |
+| `required_staff` | `int` |
+| `substitution_options` | `dict[str, list[str]]` |
+| `validation_result` | `ValidationResult` |
+
+**Computed properties:** `protocol_ok`, `budget_ok`, `equipment_ok`, `reagents_ok`, `schedule_ok`, `staff_ok`, `feasible`, `summary`
+
+#### `SuggestionChange(BaseModel)` — `extra="forbid"`
+| Field | Type | Purpose |
+|-------|------|---------|
+| `field` | `str` | Which protocol field was changed |
+| `original` | `str` | Original value (stringified) |
+| `revised` | `str` | New value (stringified) |
+| `reason` | `str` | Why it was changed |
+| `tradeoff` | `str` | What is lost |
+
+#### `AlternativeSuggestion(BaseModel)` — `extra="forbid"`
+| Field | Type |
+|-------|------|
+| `revised_protocol` | `Protocol` |
+| `applied_changes` | `list[SuggestionChange]` |
+| `remaining_failures` | `list[str]` |
+| `improved` | `bool` |
+| `pre_check` | `FeasibilityCheckResult` |
+| `post_check` | `FeasibilityCheckResult` |
+
+### Type Aliases
+
+```python
+ExplanationRenderer = Callable[
+    [LabManagerActionType, FeasibilityCheckResult, Optional[AlternativeSuggestion]],
+    str,
+]
+```

docs/map/config.md

@@ -0,0 +1,61 @@
+# Config Map — `replicalab/config.py`
+
+> Shared constants used across the entire project.
+
+## Constants
+
+| Constant | Value | Used by |
+|----------|-------|---------|
+| `DEFAULT_SCENARIO_TEMPLATE` | `"math_reasoning"` | server (reset defaults) |
+| `DEFAULT_DIFFICULTY` | `"easy"` | server (reset defaults) |
+| `MAX_ROUNDS` | `6` | scenarios (observation.max_rounds), server |
+| `MAX_BUDGET` | `5000.0` | scenarios (budget_total base) |
+| `TIMEOUT_SECONDS` | `300` | server (session TTL base) |
+| `ROUND_TIME_LIMIT_SECONDS` | `300` | server (per-round timeout) |
+| `SESSION_TTL_SECONDS` | `300` (= TIMEOUT_SECONDS) | server (session cleanup) |
+| `WS_IDLE_TIMEOUT_SECONDS` | `300` (= TIMEOUT_SECONDS) | server (WebSocket idle) |
+| `STUB_ACCEPT_REWARD` | `5.0` | server (_StubEnv reward on accept) |
+| `API_HOST` | `"0.0.0.0"` | server (uvicorn bind) |
+| `API_PORT` | `7860` | server (uvicorn port) |
+
+## Who Imports This
+
+| Consumer | Constants used |
+|----------|---------------|
+| `scenarios/templates.py` | `MAX_BUDGET`, `MAX_ROUNDS` |
+| `server/app.py` | `API_HOST`, `API_PORT`, `DEFAULT_SCENARIO_TEMPLATE`, `DEFAULT_DIFFICULTY`, `MAX_ROUNDS`, `ROUND_TIME_LIMIT_SECONDS`, `SESSION_TTL_SECONDS`, `STUB_ACCEPT_REWARD`, `WS_IDLE_TIMEOUT_SECONDS` |
+| `tests/test_config.py` | All constants (validation tests) |
+
+## Project Config — `pyproject.toml`
+
+| Key | Value |
+|-----|-------|
+| Name | `replicalab` |
+| Version | `0.1.0` |
+| Python | `>=3.10` |
+| License | MIT |
+
+### Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| `pydantic` | `>=2.7,<3.0` | Data validation |
+| `fastapi` | `>=0.115,<1.0` | REST API framework |
+| `uvicorn[standard]` | `>=0.34,<1.0` | ASGI server |
+| `websockets` | `>=15.0,<17.0` | WebSocket support |
+| `openenv-core[core]` | `>=0.2.1,<0.3.0` | Environment base (not yet used) |
+
+### Dev Dependencies
+| Package | Purpose |
+|---------|---------|
+| `pytest` | Testing |
+| `pytest-cov` | Coverage |
+| `pytest-asyncio` | Async test support |
+| `httpx` | HTTP client for API tests |
+| `ruff` | Linting |
+| `mypy` | Type checking |
+
+### Entry Point
+```
+[project.scripts]
+server = "server.app:main"
+```

docs/map/frontend.md

@@ -0,0 +1,141 @@
+# Frontend Map — `frontend/`
+
+> React 19 + TypeScript + Vite UI for ReplicaLab.
+>
+> **Tasks implemented:** FND 01-10
+
+## Stack
+
+| Technology | Version | Purpose |
+|------------|---------|---------|
+| React | 19.2.0 | UI framework |
+| React Router | 7.13.1 | Client-side routing |
+| Three.js | 0.183.2 | 3D molecule scene |
+| @react-three/fiber | 9.5.0 | React Three.js bindings |
+| @react-three/drei | 10.7.7 | Three.js helpers |
+| Framer Motion | 12.35.1 | Animations |
+| @xyflow/react | 12.10.1 | Flow diagrams |
+| Recharts | 3.8.0 | Charts and graphs |
+| Tailwind CSS | 4.2.1 | Utility-first styling |
+| Lucide React | 0.577.0 | Icons |
+
+## Routes — `App.tsx`
+
+| Path | Component | Purpose |
+|------|-----------|---------|
+| `/` | `DashboardPage` | Training overview, scenario selection |
+| `/episode` | `EpisodePage` | Live episode viewer (new episode) |
+| `/episode/:episodeId` | `EpisodePage` | Replay of completed episode |
+
+## Pages
+
+### `DashboardPage.tsx`
+- Scenario selection (family + difficulty)
+- Training metrics display
+- Episode history list
+- Start new episode button
+
+### `EpisodePage.tsx`
+- Live negotiation between Scientist and Lab Manager
+- Protocol display and evolution
+- Score breakdown when episode completes
+- Replay controls for completed episodes
+
+## Components (15 files)
+
+### Negotiation & Protocol
+| Component | Purpose |
+|-----------|---------|
+| `NegotiationLog.tsx` | Scrollable conversation between agents |
+| `ProtocolPanel.tsx` | Current protocol details display |
+| `PaperPanel.tsx` | Paper summary (title, hypothesis, method, finding) |
+| `LabInventory.tsx` | Equipment and reagent availability |
+| `Controls.tsx` | User controls (start, step, auto-play) |
+
+### Visualization
+| Component | Purpose |
+|-----------|---------|
+| `ScorePanel.tsx` | Rigor/feasibility/fidelity score bars |
+| `JudgeAuditPanel.tsx` | Judge reasoning and audit trail |
+| `TrainingResults.tsx` | Training metrics charts |
+| `ReplayViewer.tsx` | Step-through replay of completed episodes |
+
+### 3D & Animation
+| Component | Purpose |
+|-----------|---------|
+| `CharacterStage.tsx` | 3D stage for agent characters |
+| `CharacterAvatar.tsx` | Individual agent avatar |
+| `AnimatedCharacter.tsx` | Character with animations |
+| `MoleculeScene.tsx` | 3D molecule visualization |
+| `TiltCard.tsx` | Tilt-on-hover card component |
+
+### Layout
+| Component | Purpose |
+|-----------|---------|
+| `Header.tsx` | Top navigation bar |
+
+## API Client — `lib/api.ts`
+
+### REST Functions
+| Function | Method | Endpoint |
+|----------|--------|----------|
+| `healthCheck()` | GET | `/health` |
+| `getScenarios()` | GET | `/scenarios` |
+| `resetEpisode(params)` | POST | `/reset` |
+| `stepEpisode(action)` | POST | `/step` |
+| `getReplay(episodeId)` | GET | `/replay/{episodeId}` |
+
+### WebSocket
+| Function | Purpose |
+|----------|---------|
+| `createWebSocket(onMessage, onOpen, onClose, onError)` | Connect to `/ws` |
+| `sendWsMessage(ws, msg)` | Send typed message |
+
+### Mock Data (for offline development)
+| Function | Returns |
+|----------|---------|
+| `createMockConversation()` | `NegotiationMessage[]` |
+| `createMockScores()` | `ScoreBreakdown` |
+| `createMockEpisodeState(done)` | `EpisodeState` |
+| `createMockProtocol()` | `Protocol` |
+| `createMockJudgeAudit()` | `JudgeAudit` |
+
+## TypeScript Types — `types/index.ts`
+
+Mirrors Python models:
+
+| TS Interface | Python Model |
+|-------------|--------------|
+| `ScientistAction` | `ScientistAction` |
+| `LabManagerAction` | `LabManagerAction` |
+| `Protocol` | `Protocol` |
+| `EpisodeState` | `EpisodeState` |
+| `StepResult` | `StepResult` |
+| `ScoreBreakdown` | `RewardBreakdown` |
+| `FeasibilityReport` | `FeasibilityCheckResult` (partial) |
+| `JudgeAudit` | `StepInfo.judge_notes` + `verdict` |
+| `NegotiationMessage` | `ConversationEntry` |
+
+Additional frontend-only types:
+- `TrainingMetrics` — loss, reward curves
+- `TrainingComparison` — baseline vs trained model
+- `PaperSummary` — paper details for display
+- `LabConstraints` — lab resource summary
+- `SuggestedChange` — protocol revision display
+
+## Utility Files
+
+### `lib/utils.ts`
+Shared helpers (class merging, formatting, etc.)
+
+### `lib/audio.ts`
+Audio feedback utilities for UI interactions.
+
+## Assets
+
+```
+frontend/public/characters/
+    judge.png           (~1.2 MB)
+    lab-manager.png     (~900 KB)
+    scientist.png       (~900 KB)
+```

docs/map/models.md

@@ -0,0 +1,219 @@
+# Models Map — `replicalab/models.py`
+
+> All Pydantic data contracts. Frozen with `extra="forbid"` unless noted.
+>
+> **Tasks implemented:** MOD 01, 02, 03, 04, 09, 11, 12
+
+## Enums
+
+### `ScientistActionType(str, Enum)`
+| Value | Meaning |
+|-------|---------|
+| `propose_protocol` | First protocol submission |
+| `revise_protocol` | Modify existing protocol |
+| `request_info` | Ask lab manager a question |
+| `accept` | Agree to current protocol |
+
+### `LabManagerActionType(str, Enum)`
+| Value | Meaning |
+|-------|---------|
+| `report_feasibility` | Report on feasibility without suggestions |
+| `suggest_alternative` | Propose revised protocol |
+| `reject` | Reject protocol outright |
+| `accept` | Approve protocol |
+
+## Action Models
+
+### `ScientistAction(BaseModel)` — `extra="forbid"`
+MOD 01 + MOD 09. Strict contract for scientist output.
+
+| Field | Type | Constraint | Notes |
+|-------|------|-----------|-------|
+| `action_type` | `ScientistActionType` | required | |
+| `sample_size` | `int` | `ge=0` | Must be `>=1` for propose/revise |
+| `controls` | `list[str]` | normalized | |
+| `technique` | `str` | stripped | Required for propose/revise |
+| `duration_days` | `int` | `ge=0` | |
+| `required_equipment` | `list[str]` | normalized | |
+| `required_reagents` | `list[str]` | normalized | |
+| `questions` | `list[str]` | normalized | Required non-empty for request_info |
+| `rationale` | `str` | stripped | Required for propose/revise |
+
+**Validation rules:**
+- `propose_protocol` / `revise_protocol`: sample_size >= 1, technique required, rationale required, questions must be empty
+- `request_info`: questions non-empty, no protocol payload fields
+- `accept`: no questions, no protocol payload fields
+
+### `LabManagerAction(BaseModel)` — `extra="forbid"`
+MOD 02. Strict contract with feasible-flag consistency.
+
+| Field | Type | Constraint | Notes |
+|-------|------|-----------|-------|
+| `action_type` | `LabManagerActionType` | required | |
+| `feasible` | `bool` | required | Must equal AND of all constraint flags |
+| `budget_ok` | `bool` | required | |
+| `equipment_ok` | `bool` | required | |
+| `reagents_ok` | `bool` | required | |
+| `schedule_ok` | `bool` | required | |
+| `staff_ok` | `bool` | required | |
+| `suggested_technique` | `str` | stripped | Only for suggest_alternative |
+| `suggested_sample_size` | `int` | `ge=0` | Only for suggest_alternative |
+| `suggested_controls` | `list[str]` | normalized | Only for suggest_alternative |
+| `explanation` | `str` | required non-empty | |
+
+**Validation rules:**
+- `feasible` must equal `all(budget_ok, equipment_ok, reagents_ok, schedule_ok, staff_ok)`
+- `accept` requires `feasible=True`
+- `reject` requires `feasible=False`
+- `suggest_alternative` requires `feasible=False` + at least one suggestion field
+- Suggestion fields forbidden for non-suggest_alternative actions
+
+## Observation Models
+
+### `ConversationEntry(BaseModel)` — `extra="forbid"`
+| Field | Type | Notes |
+|-------|------|-------|
+| `role` | `Literal["scientist", "lab_manager", "system"]` | |
+| `message` | `str` | Required non-empty |
+| `round_number` | `int` | `ge=0` |
+| `action_type` | `Optional[str]` | Null or non-empty |
+
+### `Protocol(BaseModel)` — `extra="forbid"`
+Shared protocol payload used in observations and actions.
+
+| Field | Type | Notes |
+|-------|------|-------|
+| `sample_size` | `int` | `ge=0` |
+| `controls` | `list[str]` | normalized |
+| `technique` | `str` | required non-empty |
+| `duration_days` | `int` | `ge=0` |
+| `required_equipment` | `list[str]` | normalized |
+| `required_reagents` | `list[str]` | normalized |
+| `rationale` | `str` | required non-empty |
+
+### `ScientistObservation(BaseModel)` — `extra="forbid"`
+| Field | Type |
+|-------|------|
+| `paper_title` | `str` |
+| `paper_hypothesis` | `str` |
+| `paper_method` | `str` |
+| `paper_key_finding` | `str` |
+| `experiment_goal` | `str` |
+| `conversation_history` | `list[ConversationEntry]` |
+| `current_protocol` | `Optional[Protocol]` |
+| `round_number` | `int` (ge=0) |
+| `max_rounds` | `int` (ge=0) |
+
+### `LabManagerObservation(BaseModel)` — `extra="forbid"`
+| Field | Type |
+|-------|------|
+| `budget_total` | `float` (ge=0) |
+| `budget_remaining` | `float` (ge=0) |
+| `equipment_available` | `list[str]` |
+| `equipment_booked` | `list[str]` |
+| `reagents_in_stock` | `list[str]` |
+| `reagents_out_of_stock` | `list[str]` |
+| `staff_count` | `int` (ge=0) |
+| `time_limit_days` | `int` (ge=0) |
+| `safety_restrictions` | `list[str]` |
+| `conversation_history` | `list[ConversationEntry]` |
+| `current_protocol` | `Optional[Protocol]` |
+| `round_number` | `int` (ge=0) |
+| `max_rounds` | `int` (ge=0) |
+
+### `Observation(BaseModel)` — `extra="forbid"`
+Combined wrapper. Each role receives its own view.
+
+| Field | Type |
+|-------|------|
+| `scientist` | `Optional[ScientistObservation]` |
+| `lab_manager` | `Optional[LabManagerObservation]` |
+
+## Reward & Step Models
+
+### `RewardBreakdown(BaseModel)` — default `extra="forbid"`
+MOD 11. Component scores from judge rubric engine.
+
+| Field | Type | Default | Range |
+|-------|------|---------|-------|
+| `rigor` | `float` | 0.0 | [0, 1] |
+| `feasibility` | `float` | 0.0 | [0, 1] |
+| `fidelity` | `float` | 0.0 | [0, 1] |
+| `efficiency_bonus` | `float` | 0.0 | unbounded |
+| `communication_bonus` | `float` | 0.0 | unbounded |
+| `penalties` | `dict[str, float]` | {} | unbounded |
+
+### `StepInfo(BaseModel)` — `extra="allow"`
+MOD 11. Extensible metadata returned with each step.
+
+| Field | Type | Default |
+|-------|------|---------|
+| `agreement_reached` | `bool` | False |
+| `error` | `Optional[str]` | None |
+| `reward_breakdown` | `Optional[RewardBreakdown]` | None |
+| `judge_notes` | `Optional[str]` | None |
+| `verdict` | `Optional[str]` | None |
+
+### `StepResult(BaseModel)`
+| Field | Type | Default |
+|-------|------|---------|
+| `observation` | `Optional[Observation]` | None |
+| `reward` | `float` | 0.0 |
+| `done` | `bool` | False |
+| `info` | `StepInfo` | StepInfo() |
+
+## Episode Models
+
+### `EpisodeState(BaseModel)` — MOD 04
+Full internal state for debugging and replay.
+
+| Field | Type | Default |
+|-------|------|---------|
+| `seed` | `int` | 0 |
+| `scenario_template` | `str` | "" |
+| `difficulty` | `str` | "easy" |
+| `paper_title` | `str` | "" |
+| `paper_hypothesis` | `str` | "" |
+| `paper_method` | `str` | "" |
+| `paper_key_finding` | `str` | "" |
+| `experiment_goal` | `str` | "" |
+| `lab_budget_total` | `float` | 0.0 |
+| `lab_budget_remaining` | `float` | 0.0 |
+| `lab_equipment` | `list[str]` | [] |
+| `lab_reagents` | `list[str]` | [] |
+| `lab_staff_count` | `int` | 0 |
+| `lab_time_limit_days` | `int` | 0 |
+| `current_protocol` | `Optional[Protocol]` | None |
+| `conversation_history` | `list[ConversationEntry]` | [] |
+| `round_number` | `int` | 0 |
+| `max_rounds` | `int` | 0 |
+| `done` | `bool` | False |
+| `agreement_reached` | `bool` | False |
+| `reward` | `float` | 0.0 |
+| `rigor_score` | `float` | 0.0 |
+| `feasibility_score` | `float` | 0.0 |
+| `fidelity_score` | `float` | 0.0 |
+
+### `EpisodeLog(BaseModel)` — MOD 04
+Completed episode record for logging, replay, evaluation.
+
+| Field | Type | Default |
+|-------|------|---------|
+| `episode_id` | `str` | "" |
+| `seed` | `int` | 0 |
+| `scenario_template` | `str` | "" |
+| `difficulty` | `str` | "easy" |
+| `final_state` | `Optional[EpisodeState]` | None |
+| `transcript` | `list[ConversationEntry]` | [] |
+| `reward_breakdown` | `Optional[RewardBreakdown]` | None |
+| `total_reward` | `float` | 0.0 |
+| `rounds_used` | `int` | 0 |
+| `agreement_reached` | `bool` | False |
+| `judge_notes` | `str` | "" |
+| `verdict` | `str` | "" |
+
+## Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `_normalize_string_list(value)` | Strip whitespace, reject empty strings |

docs/map/scenarios.md

@@ -0,0 +1,153 @@
+# Scenarios Map — `replicalab/scenarios/`
+
+> Normalized scenario generation across 3 domains with seeded determinism.
+>
+> **Tasks implemented:** SCN 01-12
+
+## Entry Point
+
+### `generate_scenario(seed, template, difficulty) -> NormalizedScenarioPack`
+Located in `templates.py`. The main public API.
+
+**Flow:**
+1. `seed_rng(seed)` → deterministic `random.Random` instance
+2. `load_template(template)` → picks the template builder function
+3. `builder(rng)` → raw draft dict (randomly selects one of 2 cases per domain)
+4. `apply_difficulty(draft, difficulty, rng)` → scales budget, time, staff, resources
+5. `_build_pack(seed, template, draft)` → constructs `NormalizedScenarioPack`
+
+### `available_scenario_families() -> list[dict]`
+Returns `[{"family": name, "difficulties": ["easy", "medium", "hard"]}]` for each template.
+
+## Core Data Classes (all in `templates.py`)
+
+### `NormalizedScenarioPack(BaseModel)` — `extra="forbid"`
+The complete scenario definition. Every downstream consumer uses this.
+
+| Field | Type | Source |
+|-------|------|--------|
+| `scenario_id` | `str` | `"{template}_{seed}"` |
+| `template` | `TemplateName` | input param |
+| `domain_id` | `str` | from template case |
+| `difficulty` | `Difficulty` | input param |
+| `seed` | `int` | input param |
+| `task_summary` | `str` | from template case |
+| `success_criteria` | `list[str]` | from template case |
+| `constraints` | `list[ScenarioConstraint]` | from template + difficulty scaling |
+| `resources` | `list[ScenarioResource]` | from template + difficulty scaling |
+| `allowed_substitutions` | `list[AllowedSubstitution]` | from template case |
+| `hidden_reference_spec` | `HiddenReferenceSpec` | from template case |
+| `scientist_observation` | `ScientistObservation` | built from case fields |
+| `lab_manager_observation` | `LabManagerObservation` | built from case fields |
+
+### `ScenarioConstraint(BaseModel)`
+| Field | Type | Example |
+|-------|------|---------|
+| `key` | `str` | `"gpu_hours"` |
+| `label` | `str` | `"Maximum GPU budget"` |
+| `quantity` | `float \| int \| None` | `8` |
+| `unit` | `str \| None` | `"gpu_hours"` |
+| `comparator` | `Literal["<=", ">=", "="]` | `"<="` |
+| `hard` | `bool` | `True` |
+| `details` | `str` | `"The full run must fit within eight GPU-hours."` |
+
+### `ScenarioResource(BaseModel)`
+| Field | Type | Example |
+|-------|------|---------|
+| `key` | `str` | `"gpu_node"` |
+| `label` | `str` | `"A100 GPU node"` |
+| `quantity` | `float \| int \| None` | `1` |
+| `unit` | `str \| None` | `"node"` |
+| `available` | `bool` | `True` |
+| `category` | `str` | `"compute"` |
+| `details` | `str` | `"Reserved for one benchmark run at a time."` |
+
+### `AllowedSubstitution(BaseModel)`
+| Field | Type | Example |
+|-------|------|---------|
+| `original` | `str` | `"A100 GPU node"` |
+| `alternative` | `str` | `"V100 GPU node"` |
+| `condition` | `str` | `"Use if A100 is booked."` |
+| `tradeoff` | `str` | `"V100 is slower; extend training by ~30%."` |
+
+### `HiddenReferenceSpec(BaseModel)`
+Ground truth the judge uses to score fidelity. The scientist never sees this.
+
+| Field | Type | Example |
+|-------|------|---------|
+| `summary` | `str` | `"A valid plan keeps the published split..."` |
+| `required_elements` | `list[str]` | `["published data split", "held-out accuracy evaluation"]` |
+| `flexible_elements` | `list[str]` | `["batch size", "learning-rate schedule"]` |
+| `target_metric` | `str` | `"held_out_accuracy"` |
+| `target_value` | `str` | `"within one point of the reported baseline"` |
+
+## Template Builders
+
+Each returns a raw `dict[str, Any]` with one randomly selected case.
+
+### `build_math_reasoning_template(rng)` — `math_reasoning.py`
+- **Domain:** `mathematics`
+- **Case A:** Cauchy-Schwarz inequality — structured proof verification
+- **Case B:** Jensen's inequality — convexity-based proof
+- **Equipment:** Structured proof notebook, Automated proof checker
+- **Reagents:** Graduate reviewer, Reference textbook
+- **Substitutions:** Graduate reviewer → self-check rubric
+
+### `build_ml_benchmark_template(rng)` — `ml_benchmark.py`
+- **Domain:** `machine_learning`
+- **Case A:** AG News TinyBERT — text classification replication
+- **Case B:** CIFAR-10 ResNet-18 — image classification replication
+- **Equipment:** A100 GPU node, Dataset mirror, Experiment tracker
+- **Reagents:** Pre-trained checkpoint, Evaluation harness
+- **Substitutions:** A100 → V100 (slower), full dataset → stratified sample
+
+### `build_finance_trading_template(rng)` — `finance_trading.py`
+- **Domain:** `finance_trading`
+- **Case A:** SPY/QQQ mean-reversion — pairs trading backtest
+- **Case B:** Momentum futures — trend-following strategy
+- **Equipment:** Backtest engine, Historical daily bar dataset
+- **Reagents:** Risk reviewer, Compliance packet
+- **Substitutions:** Daily bars → weekly bars, risk reviewer → automated risk check
+- **Safety restrictions:** offline-only execution policy
+
+## Difficulty Scaling — `apply_difficulty(draft, difficulty, rng)`
+
+| Parameter | Easy | Medium | Hard |
+|-----------|------|--------|------|
+| `budget_total` | ×1.15 | ×0.95 | ×0.80 |
+| `time_limit_days` | unchanged | −1 day | −1 day |
+| `staff_count` | unchanged | unchanged | −1 person |
+| Resources tightened | 0 | 1 | 2 |
+| Conflict constraint | no | yes (1) | yes (1) |
+
+**`_tighten_one_resource`**: picks a random resource, sets `available=False`.
+**`_append_conflict_constraint`**: adds a soft constraint noting resource conflict.
+
+## Utility — `replicalab/utils/seed.py`
+
+| Function | Purpose |
+|----------|---------|
+| `get_deterministic_seed(seed, namespace)` | SHA256-based child seed derivation |
+| `seed_rng(seed, namespace)` | Returns `random.Random(derived_seed)` |
+
+## Type Aliases
+
+```python
+Difficulty = Literal["easy", "medium", "hard"]
+TemplateName = Literal["math_reasoning", "ml_benchmark", "finance_trading"]
+TemplateBuilder = Callable[[Any], dict[str, Any]]
+```
+
+## Constants
+
+```python
+GOLDEN_SCENARIO_SPECS_PATH = Path("tests/fixtures/golden_scenarios.json")
+```
+
+## Who Consumes This
+
+- **`validation.py`** — reads constraints, resources, substitutions, hidden_reference_spec
+- **`lab_manager_policy.py`** — reads lab_manager_observation, substitutions, constraints
+- **`scientist_policy.py`** — reads scenario pack for system prompt generation
+- **`server/app.py`** — calls `generate_scenario()` on reset, stores pack for lab manager
+- **`scoring/`** (future) — will read hidden_reference_spec for fidelity scoring

docs/map/scoring.md

@@ -0,0 +1,57 @@
+# Scoring Map — `replicalab/scoring/`
+
+> Judge scoring engine for protocol evaluation.
+>
+> **Status:** NOT YET IMPLEMENTED
+> **Tasks remaining:** JDG 01-08
+
+## Planned Architecture
+
+```
+replicalab/scoring/
+    __init__.py          # exports: score_rigor, score_feasibility, score_fidelity, compute_reward
+    rigor.py             # JDG 01 — protocol structural quality
+    feasibility.py       # JDG 02 — resource feasibility (wraps AGT 05)
+    fidelity.py          # JDG 03 — adherence to hidden reference spec
+```
+
+## Planned Functions
+
+### `score_rigor(protocol, scenario) -> float` — JDG 01
+Score range: [0.0, 1.0]
+Measures: structural completeness, success criteria coverage, required element coverage.
+
+### `score_feasibility(protocol, scenario, check_result=None) -> float` — JDG 02
+Score range: [0.0, 1.0]
+Measures: whether the lab can execute the protocol (budget, equipment, reagents, schedule, staff, policy).
+Reuses `check_feasibility()` from AGT 05. Adds partial credit (continuous signal vs binary pass/fail).
+
+### `score_fidelity(protocol, scenario) -> float` — JDG 03
+Score range: [0.0, 1.0]
+Measures: how closely the protocol matches `hidden_reference_spec`.
+Substitution-aware — allowed substitutions get partial credit.
+
+### `compute_reward(protocol, scenario, check_result=None) -> RewardBreakdown` — JDG 04/05
+Combines rigor + feasibility + fidelity into `RewardBreakdown`.
+Applies efficiency bonus, communication bonus, and penalties.
+
+## Data Consumed
+
+| Source | Used by | For what |
+|--------|---------|----------|
+| `Protocol` (models.py) | All scorers | The final agreed protocol |
+| `NormalizedScenarioPack` (scenarios) | All scorers | Constraints, resources, success criteria |
+| `HiddenReferenceSpec` (scenarios) | JDG 01, JDG 03 | Required/flexible elements, target metric |
+| `FeasibilityCheckResult` (agents) | JDG 02 | 7 dimension checks |
+| `AllowedSubstitution` (scenarios) | JDG 03 | Partial credit for substitutions |
+| `RewardBreakdown` (models.py) | JDG 04/05 | Output container |
+
+## Data Produced
+
+`RewardBreakdown` populates:
+- `rigor: float` — from JDG 01
+- `feasibility: float` — from JDG 02
+- `fidelity: float` — from JDG 03
+- `efficiency_bonus: float` — from JDG 04 (rounds used / max rounds)
+- `communication_bonus: float` — from JDG 05 (negotiation quality)
+- `penalties: dict[str, float]` — from JDG 06-08 (policy violations, etc.)

docs/map/server.md

@@ -0,0 +1,128 @@
+# Server Map — `server/app.py`
+
+> FastAPI backend with REST + WebSocket endpoints and stub environment.
+>
+> **Tasks implemented:** API 01-04, 06 (partial)
+
+## Environment
+
+### `_StubEnv`
+Minimal environment stub used until the real `ReplicaLabEnv` is implemented (ENV 01-11).
+
+**State:**
+| Attribute | Type | Purpose |
+|-----------|------|---------|
+| `_state` | `EpisodeState` | Full episode state |
+| `_episode_id` | `str` | UUID for this episode |
+| `_scenario_pack` | `NormalizedScenarioPack \| None` | Stored for lab manager pipeline |
+| `_logs` | `list[ConversationEntry]` | Conversation transcript |
+
+**Methods:**
+
+| Method | Returns | Behavior |
+|--------|---------|----------|
+| `reset(seed, scenario, difficulty)` | `Observation` | Generates scenario, builds initial observations |
+| `step(action: ScientistAction)` | `StepResult` | Processes scientist action, runs lab manager pipeline |
+| `state()` | `EpisodeState` | Returns current state snapshot |
+| `episode_id()` | `str` | Returns episode UUID |
+| `close()` | `None` | No-op |
+
+**Lab Manager Integration (AGT 07):**
+The `_lab_manager_action()` method runs the full deterministic pipeline:
+1. `check_feasibility(protocol, scenario_pack)` → `FeasibilityCheckResult`
+2. `suggest_alternative(protocol, check_result, scenario_pack)` → `AlternativeSuggestion | None`
+3. `compose_lab_manager_response(check_result, suggestion)` → `LabManagerAction`
+
+**Termination logic:**
+- Episode ends (`done=True`) when `agreement_reached=True` (both agents accept)
+- `agreement_reached` when lab manager action_type is `accept` (2-round stub logic)
+- On termination: reward = `STUB_ACCEPT_REWARD` (5.0)
+
+### `_make_env() -> _StubEnv`
+Factory that tries to import `ReplicaLabEnv` from `replicalab.env`, falls back to `_StubEnv`.
+
+## REST Endpoints
+
+### `GET /health`
+Returns `{"status": "ok"}`.
+
+### `POST /reset`
+**Request:** `ResetRequest`
+| Field | Type | Default |
+|-------|------|---------|
+| `seed` | `int \| None` | `None` (random) |
+| `scenario` | `str` | `DEFAULT_SCENARIO_TEMPLATE` |
+| `difficulty` | `str` | `DEFAULT_DIFFICULTY` |
+| `session_id` | `str \| None` | `None` (auto-generated) |
+
+**Response:** `ResetResponse`
+| Field | Type |
+|-------|------|
+| `session_id` | `str` |
+| `episode_id` | `str` |
+| `observation` | `Observation` |
+
+### `POST /step`
+**Request:** `StepRequest`
+| Field | Type |
+|-------|------|
+| `session_id` | `str` |
+| `action` | `ScientistAction` |
+
+**Response:** `StepResult` (observation, reward, done, info)
+
+When `done=True`, the episode log is stored in `_replay_store`.
+
+### `GET /scenarios`
+Returns `available_scenario_families()` — list of families with difficulties.
+
+### `GET /replay/{episode_id}`
+Returns `EpisodeLog` for a completed episode, or 404 if not found.
+
+## WebSocket Endpoint
+
+### `WS /ws`
+Bidirectional session with JSON messages.
+
+**Client → Server messages:**
+| Type | Payload | Behavior |
+|------|---------|----------|
+| `reset` | `{seed, scenario, difficulty}` | Creates env, returns initial state |
+| `step` | `{action: ScientistAction}` | Steps env, returns result |
+| `ping` | — | Returns `{"type": "pong"}` |
+
+**Server → Client messages:**
+| Type | Payload |
+|------|---------|
+| `state` | `{observation, episode_id}` |
+| `step_result` | `StepResult.info.model_dump()` |
+| `pong` | `{}` |
+| `error` | `{message}` |
+
+## Session Management
+
+| Store | Type | Purpose |
+|-------|------|---------|
+| `_sessions` | `dict[str, dict]` | Active REST sessions (env + last_active) |
+| `_replay_store` | `dict[str, EpisodeLog]` | Completed episode logs |
+
+**Cleanup:** Background task runs every 60s, removes sessions older than `SESSION_TTL_SECONDS` (300s).
+
+## Helper Functions
+
+| Function | Purpose |
+|----------|---------|
+| `_reward_breakdown_from_state(state)` | Extract RewardBreakdown from EpisodeState scores |
+| `_build_episode_log(episode_id, state)` | Build EpisodeLog from final state |
+| `_touch(session_id)` | Update last_active timestamp |
+| `_cleanup_stale_sessions()` | Remove expired sessions |
+
+## Dependencies
+
+```python
+from replicalab.agents import check_feasibility, compose_lab_manager_response, suggest_alternative
+from replicalab.config import API_HOST, API_PORT, DEFAULT_DIFFICULTY, ...
+from replicalab.models import (ConversationEntry, EpisodeLog, EpisodeState, LabManagerAction,
+                                Observation, Protocol, RewardBreakdown, ScientistAction, StepInfo, StepResult, ...)
+from replicalab.scenarios import NormalizedScenarioPack, available_scenario_families, generate_scenario
+```

docs/map/tests.md

@@ -0,0 +1,194 @@
+# Tests Map — `tests/`
+
+> 87 tests across 6 files. All passing.
+>
+> **Last verified:** 2026-03-07
+
+## Summary
+
+| File | Tests | What it covers |
+|------|-------|---------------|
+| `test_config.py` | 3 | Shared constants consistency |
+| `test_models.py` | 15 | All Pydantic model contracts |
+| `test_scenarios.py` | 8 | Scenario generation and determinism |
+| `test_validation.py` | 13 | Protocol validation checks |
+| `test_scientist_policy.py` | 18 | Parser, retry, formatter, baseline |
+| `test_lab_manager_policy.py` | 13 | Feasibility, suggestion, response |
+| **Total** | **87** | |
+
+## Missing Coverage (not yet implemented)
+
+| File (planned) | Would cover |
+|---------------|-------------|
+| `test_reward.py` | JDG 01-03 scoring functions |
+| `test_env.py` | ENV 01-11 real environment |
+| `test_server.py` | API endpoint integration tests |
+
+---
+
+## `test_config.py` (3 tests)
+
+| Test | What it verifies |
+|------|-----------------|
+| `test_reset_request_defaults_match_shared_config` | ResetRequest defaults match config constants |
+| `test_generated_scenarios_respect_shared_round_and_budget_caps` | Scenarios use MAX_ROUNDS and MAX_BUDGET |
+| `test_timeout_exports_share_the_same_default_value` | SESSION_TTL, WS_IDLE, ROUND_TIME all equal TIMEOUT |
+
+## `test_models.py` (15 tests)
+
+### ScientistAction (6 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_scientist_action_accepts_valid_protocol_payload` | propose_protocol with full fields passes |
+| `test_scientist_action_rejects_unknown_action_type` | Invalid enum value rejected |
+| `test_scientist_action_rejects_request_info_without_questions` | questions must be non-empty for request_info |
+| `test_scientist_action_rejects_protocol_payload_for_request_info` | No protocol fields with request_info |
+| `test_scientist_action_rejects_protocol_with_zero_sample_size` | sample_size >= 1 for protocol actions |
+| `test_scientist_action_rejects_extra_fields` | extra="forbid" enforcement |
+
+### LabManagerAction (4 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_lab_manager_action_accepts_valid_suggestion_payload` | suggest_alternative with all fields passes |
+| `test_lab_manager_action_rejects_feasible_flag_mismatch` | feasible must match constraint flags AND |
+| `test_lab_manager_action_rejects_missing_suggestion_fields` | suggest_alternative needs suggestion fields |
+| `test_lab_manager_action_rejects_suggestions_for_report_feasibility` | Suggestion fields forbidden for non-suggest |
+
+### Observation (2 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_observation_coerces_nested_dicts_to_typed_models` | Dict coercion to ConversationEntry/Protocol |
+| `test_observation_rejects_invalid_conversation_role` | Only scientist/lab_manager/system |
+| `test_observation_rejects_negative_budget` | budget_total ge=0 |
+
+### Episode Models — MOD 04 (3 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_episode_state_accepts_typed_protocol_and_history` | Protocol + ConversationEntry fields |
+| `test_episode_state_accepts_none_protocol` | Optional[Protocol] = None |
+| `test_episode_state_json_round_trip` | model_dump_json → model_validate_json |
+| `test_episode_log_accepts_typed_fields` | Typed transcript + reward_breakdown |
+| `test_episode_log_none_reward_breakdown` | Optional[RewardBreakdown] = None |
+| `test_episode_log_json_round_trip` | Serialization round-trip |
+| `test_episode_log_nested_state_preserves_typed_fields` | final_state nesting |
+| `test_step_result_with_typed_info` | StepInfo with RewardBreakdown |
+
+## `test_scenarios.py` (8 tests)
+
+| Test | What it verifies |
+|------|-----------------|
+| `test_generate_scenario_is_deterministic_for_same_seed` | Same seed → same output |
+| `test_generate_scenario_varies_across_seeded_cases` | Different seeds → different output |
+| `test_available_scenario_families_exposes_three_domain_families` | 3 families, each with 3 difficulties |
+| `test_hard_finance_scenario_exposes_unavailable_resource_and_safety_rules` | Hard mode tightens resources |
+| `test_difficulty_levels_mechanically_change_budget_and_constraints` | Easy > medium > hard budget |
+| `test_generated_scenarios_keep_unique_constraint_and_resource_keys` | No duplicate keys |
+| `test_golden_scenario_specs_exist_for_manual_prompt_checks` | Golden file exists |
+| `test_golden_scenarios_match_expected_title_and_domain` | Golden content matches |
+
+## `test_validation.py` (13 tests)
+
+| Test | What it verifies |
+|------|-----------------|
+| `test_valid_protocol_passes` | Well-formed protocol → valid=True |
+| `test_zero_sample_size_is_error` | sample_size < 1 → ERROR |
+| `test_zero_duration_is_error` | duration_days < 1 → ERROR |
+| `test_duration_exceeding_time_limit_is_error` | Over limit → ERROR |
+| `test_duration_within_limit_passes` | Under limit → pass |
+| `test_unknown_equipment_is_warning` | Unknown item → WARNING |
+| `test_booked_equipment_without_substitution_is_error` | Booked + no sub → ERROR |
+| `test_out_of_stock_reagent_without_substitution_is_error` | Out + no sub → ERROR |
+| `test_unknown_reagent_is_warning` | Unknown reagent → WARNING |
+| `test_required_element_warning_when_not_addressed` | Missing element → WARNING |
+| `test_no_controls_is_warning` | Empty controls → WARNING |
+| `test_validation_result_never_raises` | Always returns, never throws |
+| `test_validation_result_json_round_trip` | Serialization round-trip |
+
+## `test_scientist_policy.py` (18 tests)
+
+### Parser — MOD 09 (5 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_parse_scientist_output_accepts_plain_json` | Plain JSON parsing |
+| `test_parse_scientist_output_accepts_fenced_json_with_prose` | Fenced block extraction |
+| `test_parse_scientist_output_raises_explicit_error_when_json_is_missing` | no_json error code |
+| `test_parse_scientist_output_raises_explicit_error_when_json_is_invalid` | invalid_json error code |
+| `test_parse_scientist_output_raises_explicit_error_when_schema_is_invalid` | invalid_action error code |
+
+### System Prompt — AGT 01 (1 test)
+| Test | What it verifies |
+|------|-----------------|
+| `test_build_scientist_system_prompt_uses_normalized_scenario_data` | Contains role, task, criteria, action types |
+
+### Observation Formatter — AGT 02 (5 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_format_observation_empty_history_no_protocol` | Empty state formatting |
+| `test_format_observation_with_history_and_protocol` | Populated state formatting |
+| `test_format_observation_stable_section_order` | Section order is deterministic |
+| `test_format_observation_history_entry_without_action_type` | Null action_type handled |
+| `test_format_observation_from_generated_scenario` | Works with real scenario data |
+
+### Retry Loop — AGT 03 (7 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_retry_success_on_first_try` | No retry needed |
+| `test_retry_malformed_json_then_valid` | Recovers from bad JSON |
+| `test_retry_invalid_action_then_valid` | Recovers from schema error |
+| `test_retry_exhausted_raises_last_error` | Raises after max retries |
+| `test_retry_correction_message_includes_parser_error` | Correction prompt has error detail |
+| `test_retry_correction_for_invalid_action_includes_validation_detail` | Schema error in correction |
+| `test_retry_metadata_serializable` | RetryMetadata JSON round-trip |
+
+### Baseline Action — AGT 04 (4 tests — user-added)
+| Test | What it verifies |
+|------|-----------------|
+| `test_baseline_scientist_proposes_protocol_for_fresh_observation` | No protocol → propose |
+| `test_baseline_scientist_accepts_existing_protocol_without_blocker` | Accepted → accept |
+| `test_baseline_scientist_revises_when_latest_feedback_has_blocker` | Blocker → revise |
+| `test_baseline_scientist_finishes_stub_episode_without_crashing` | Full 2-round stub episode |
+
+## `test_lab_manager_policy.py` (13 tests)
+
+### Feasibility — AGT 05 (7 tests — user-added)
+| Test | What it verifies |
+|------|-----------------|
+| `test_check_feasibility_passes_for_viable_protocol` | All 7 dimensions pass |
+| `test_check_feasibility_flags_budget_overrun` | Over-budget detected |
+| `test_check_feasibility_flags_unavailable_resource_and_lists_substitution` | Out-of-stock + substitution |
+| `test_check_feasibility_flags_schedule_overrun` | Duration over limit |
+| `test_check_feasibility_flags_staff_overload` | Staff insufficient |
+| `test_check_feasibility_flags_policy_violation` | Policy violation detected |
+| `test_check_feasibility_is_deterministic` | Same inputs → same output |
+
+### Suggestion — AGT 06 (8 tests)
+| Test | What it verifies |
+|------|-----------------|
+| `test_suggest_alternative_returns_none_for_feasible_protocol` | Feasible → None |
+| `test_suggest_alternative_substitutes_equipment` | Equipment swap applied |
+| `test_suggest_alternative_substitutes_reagent` | Reagent swap applied |
+| `test_suggest_alternative_clamps_duration` | Duration reduced to limit |
+| `test_suggest_alternative_reduces_sample_size_for_budget` | Sample size halved for budget |
+| `test_suggest_alternative_is_deterministic` | Same inputs → same output |
+| `test_suggest_alternative_post_check_is_not_worse` | Post-fix has <= pre-fix failures |
+| `test_suggest_alternative_reports_remaining_failures` | Unfixable failures listed |
+
+### Response Composition — AGT 07 (5 tests — user-added)
+| Test | What it verifies |
+|------|-----------------|
+| `test_compose_lab_manager_response_accepts_feasible_protocol` | Feasible → ACCEPT |
+| `test_compose_lab_manager_response_suggests_alternative_when_revision_exists` | Has suggestion → SUGGEST |
+| `test_compose_lab_manager_response_rejects_when_no_revision_exists` | No fix → REJECT |
+| `test_compose_lab_manager_response_reports_non_lab_issues` | Policy-only → REPORT |
+| `test_compose_lab_manager_response_uses_custom_renderer_without_changing_verdict` | Custom renderer works |
+
+## Test Helpers
+
+### Shared fixtures in test files
+| Helper | File | Purpose |
+|--------|------|---------|
+| `_scenario(template, difficulty)` | test_lab_manager_policy | Generate scenario with seed=123 |
+| `_protocol_for_scenario(scenario, **overrides)` | test_lab_manager_policy | Build viable protocol from scenario |
+| `_base_observation(**overrides)` | test_scientist_policy | Build ScientistObservation with defaults |
+| `_make_system_prompt()` | test_scientist_policy | Build prompt from math_reasoning scenario |
+| `_VALID_REQUEST_INFO_JSON` | test_scientist_policy | Valid request_info JSON string |

docs/map/validation.md

@@ -0,0 +1,99 @@
+# Validation Map — `replicalab/utils/validation.py`
+
+> Deterministic protocol validation against scenario constraints.
+> Pure functions — no LLM calls, no side effects.
+>
+> **Tasks implemented:** MOD 05
+
+## Public API
+
+### `validate_protocol(protocol: Protocol, scenario: NormalizedScenarioPack) -> ValidationResult`
+Main entry point. Never raises — always returns a `ValidationResult`.
+
+**Checks run (in order):**
+1. `_check_obvious_impossibilities` — sample_size < 1, no controls, duration < 1
+2. `_check_duration_vs_time_limit` — protocol days vs lab time_limit_days
+3. `_check_equipment_vocabulary` — items vs available/booked/substitutable
+4. `_check_reagent_vocabulary` — items vs in-stock/out-of-stock/substitutable
+5. `_check_required_element_coverage` — protocol text vs hidden_reference_spec.required_elements
+
+**Result:** `valid=True` only if zero ERROR-level issues.
+
+## Data Classes
+
+### `IssueSeverity(str, Enum)`
+| Value | Meaning |
+|-------|---------|
+| `error` | Hard failure — protocol cannot proceed |
+| `warning` | Advisory — protocol is suboptimal but possible |
+
+### `ValidationIssue(BaseModel)` — `extra="forbid"`
+| Field | Type | Example |
+|-------|------|---------|
+| `severity` | `IssueSeverity` | `ERROR` |
+| `category` | `str` | `"equipment"`, `"duration"`, `"sample_size"` |
+| `message` | `str` | `"Equipment 'X' is booked and has no substitution."` |
+
+### `ValidationResult(BaseModel)` — `extra="forbid"`
+| Field | Type |
+|-------|------|
+| `valid` | `bool` |
+| `issues` | `list[ValidationIssue]` |
+
+**Properties:**
+- `errors` → `list[ValidationIssue]` (severity=ERROR only)
+- `warnings` → `list[ValidationIssue]` (severity=WARNING only)
+
+## Check Details
+
+### `_check_obvious_impossibilities`
+| Condition | Severity | Category |
+|-----------|----------|----------|
+| `sample_size < 1` | ERROR | `sample_size` |
+| `controls` empty | WARNING | `controls` |
+| `duration_days < 1` | ERROR | `duration` |
+
+### `_check_duration_vs_time_limit`
+| Condition | Severity | Category |
+|-----------|----------|----------|
+| `duration_days > time_limit_days` | ERROR | `duration` |
+
+### `_check_equipment_vocabulary`
+| Condition | Severity | Category |
+|-----------|----------|----------|
+| Item available | — (pass) | — |
+| Item booked + has substitution | WARNING | `equipment` |
+| Item booked + no substitution | ERROR | `equipment` |
+| Item unknown (not in inventory) | WARNING | `equipment` |
+
+### `_check_reagent_vocabulary`
+| Condition | Severity | Category |
+|-----------|----------|----------|
+| Item in stock | — (pass) | — |
+| Item out of stock + has substitution | WARNING | `reagent` |
+| Item out of stock + no substitution | ERROR | `reagent` |
+| Item unknown (not in inventory) | WARNING | `reagent` |
+
+### `_check_required_element_coverage`
+Checks each `hidden_reference_spec.required_elements` against protocol text fields using token matching.
+
+**Protocol text searched:** technique, rationale, controls, equipment, reagents (joined, lowercased).
+**Token extraction:** `_element_tokens(element)` splits on spaces, keeps tokens with 3+ chars.
+**Match:** any token from element found in protocol text → covered.
+
+| Condition | Severity | Category |
+|-----------|----------|----------|
+| Element not addressed | WARNING | `required_element` |
+
+## Internal Helpers
+
+| Function | Purpose |
+|----------|---------|
+| `_normalize(label)` | Lowercase, strip, collapse whitespace |
+| `_element_tokens(element)` | Split element string into searchable tokens (3+ chars) |
+| `_substitution_alternatives(scenario)` | Set of normalized original items from `allowed_substitutions` |
+
+## Who Consumes This
+
+- **`lab_manager_policy.py`** — `check_feasibility()` calls `validate_protocol()` and wraps result in `protocol` DimensionCheck
+- **`scoring/`** (future) — JDG 01 rigor score will reuse `_element_tokens` for required element matching