Upload 20 files

Dockerfile

@@ -0,0 +1,36 @@
+FROM python:3.11-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    SWMM_WORKER_PYTHON=/opt/swmm-venv/bin/python \
+    SWMM_SESSION_ROOT=/tmp/swmm_sessions \
+    PYTHONFAULTHANDLER=1
+
+WORKDIR /app
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential gcc g++ \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY requirements.txt worker-requirements.txt /app/
+
+# Main server environment: MCP + FastAPI. OpenSWMM is intentionally absent.
+RUN python -m pip install --upgrade pip setuptools wheel \
+    && python -m pip install -r /app/requirements.txt
+
+# Native SWMM environment: used only by the one-shot crash-isolated worker.
+RUN python -m venv /opt/swmm-venv \
+    && /opt/swmm-venv/bin/python -m pip install --upgrade pip setuptools wheel \
+    && /opt/swmm-venv/bin/python -m pip install -r /app/worker-requirements.txt \
+    && /opt/swmm-venv/bin/python -c "from openswmm.engine import Solver; print('Isolated OpenSWMM worker verified')"
+
+COPY . /app
+
+RUN useradd --create-home --uid 1000 appuser \
+    && mkdir -p /tmp/swmm_sessions \
+    && chown -R appuser:appuser /app /opt/swmm-venv /tmp/swmm_sessions
+
+USER appuser
+EXPOSE 7860
+
+CMD ["python", "-X", "faulthandler", "-m", "uvicorn", "server:app", "--host", "0.0.0.0", "--port", "7860"]

agent.py

@@ -0,0 +1,229 @@
+"""Built-in agent: an LLM tool-use loop over the SWMM tool registry.
+
+For platforms that are not MCP clients (plain REST callers, n8n HTTP nodes,
+Custom GPT Actions, simple webhooks), this provides a single "ask the agent"
+endpoint. MCP-native clients (Claude Desktop/web, Gemini, LangChain,
+Flowise, Langflow) should normally drive the tools directly instead — their
+own model is the agent.
+
+Providers (two wire dialects, both via httpx, no SDK dependencies):
+  anthropic  -> Anthropic Messages API (ANTHROPIC_API_KEY)
+  openai     -> OpenAI chat completions (OPENAI_API_KEY)
+  gemini     -> Gemini OpenAI-compatible endpoint (GEMINI_API_KEY)
+  groq       -> Groq OpenAI-compatible endpoint (GROQ_API_KEY)
+  mistral    -> Mistral OpenAI-compatible endpoint (MISTRAL_API_KEY)
+  local      -> any OpenAI-compatible server (Ollama, LM Studio, vLLM) via
+                base_url; api_key optional
+
+Keys come from environment (HF Space secrets) or per-request overrides.
+Every response includes the full tool-call audit trail.
+"""
+from __future__ import annotations
+
+import inspect
+import json
+import os
+import time
+from typing import Any
+
+import httpx
+
+from tools import TOOL_REGISTRY
+
+MAX_STEPS = 8
+TOOL_RESULT_CHAR_LIMIT = 14000
+
+SYSTEM_PROMPT = """You are a stormwater modelling analysis agent operating deterministic SWMM tools.
+
+Rules of practice:
+- Work from tool results only; never invent numbers. If output is unavailable, say so — do not report zero.
+- Distinguish SCREENING results from CRITERIA: thresholds (e.g. Calgary 3.0/4.0 m/s velocity screens) require confirmation by the responsible engineer; say "screens above/below" not "fails/passes" unless a criterion is confirmed.
+- Typical workflow: upload_model -> run_simulation -> targeted result/screening tools. Reuse an existing session_id when the user provides one.
+- If the rpt_reconciliation verdict flags links, note that .rpt values are authoritative for those links.
+- State clearly that outputs are preliminary engineering screening, not a professional determination.
+Answer concisely with the key numbers and their provenance (which tool produced them)."""
+
+PROVIDER_PRESETS: dict[str, dict[str, str]] = {
+    "anthropic": {"dialect": "anthropic", "base_url": "https://api.anthropic.com",
+                  "env": "ANTHROPIC_API_KEY", "default_model": "claude-sonnet-4-5"},
+    "openai": {"dialect": "openai", "base_url": "https://api.openai.com/v1",
+               "env": "OPENAI_API_KEY", "default_model": "gpt-4o"},
+    "gemini": {"dialect": "openai", "base_url": "https://generativelanguage.googleapis.com/v1beta/openai",
+               "env": "GEMINI_API_KEY", "default_model": "gemini-2.0-flash"},
+    "groq": {"dialect": "openai", "base_url": "https://api.groq.com/openai/v1",
+             "env": "GROQ_API_KEY", "default_model": "llama-3.3-70b-versatile"},
+    "mistral": {"dialect": "openai", "base_url": "https://api.mistral.ai/v1",
+                "env": "MISTRAL_API_KEY", "default_model": "mistral-large-latest"},
+    "local": {"dialect": "openai", "base_url": os.environ.get("LOCAL_LLM_BASE_URL", "http://localhost:11434/v1"),
+              "env": "LOCAL_LLM_API_KEY", "default_model": os.environ.get("LOCAL_LLM_MODEL", "llama3.1")},
+}
+
+# Tools the agent may call. upload_model is included so callers can pass INP
+# content inline; generate_report excluded by default (large side effects)
+# unless allow_report=True.
+AGENT_TOOLS_DEFAULT = [
+    "upload_model", "run_simulation", "list_sessions", "get_node_results",
+    "get_link_results", "get_subcatchment_results", "get_timeseries",
+    "query_results", "get_table_catalog", "calgary_screening",
+    "preliminary_design_review", "get_reconciliation", "run_scenario",
+]
+
+_JSON_TYPES = {str: "string", int: "integer", float: "number", bool: "boolean",
+               dict: "object", list: "array"}
+
+
+def _tool_schemas(names: list[str]) -> list[dict[str, Any]]:
+    schemas = []
+    for name in names:
+        fn = TOOL_REGISTRY.get(name)
+        if fn is None:
+            continue
+        sig = inspect.signature(fn)
+        props, required = {}, []
+        for pname, param in sig.parameters.items():
+            ann = param.annotation
+            jtype = "string"
+            for py, js in _JSON_TYPES.items():
+                if ann is py:
+                    jtype = js
+                    break
+            if ann in (dict | str | None, dict | str):
+                jtype = "object"
+            props[pname] = {"type": jtype}
+            if param.default is inspect.Parameter.empty:
+                required.append(pname)
+        schemas.append({"name": name,
+                        "description": (fn.__doc__ or name).strip()[:900],
+                        "input_schema": {"type": "object", "properties": props, "required": required}})
+    return schemas
+
+
+def _execute(name: str, arguments: dict[str, Any]) -> str:
+    fn = TOOL_REGISTRY.get(name)
+    if fn is None:
+        return json.dumps({"error": f"unknown tool {name}"})
+    try:
+        result = fn(**(arguments or {}))
+        text = json.dumps(result, default=str)
+    except Exception as exc:  # deterministic error surface for the model
+        text = json.dumps({"error": f"{type(exc).__name__}: {exc}"})
+    if len(text) > TOOL_RESULT_CHAR_LIMIT:
+        text = text[:TOOL_RESULT_CHAR_LIMIT] + '... (truncated — request a smaller limit or use query_results)"}'
+    return text
+
+
+class LLMClient:
+    """Minimal two-dialect chat client. `transport` is injectable for tests."""
+
+    def __init__(self, provider: str, model: str | None = None, api_key: str | None = None,
+                 base_url: str | None = None, transport: Any | None = None):
+        preset = PROVIDER_PRESETS.get(provider)
+        if preset is None:
+            raise ValueError(f"Unknown provider '{provider}'. Choose from {sorted(PROVIDER_PRESETS)}.")
+        self.provider = provider
+        self.dialect = preset["dialect"]
+        self.base_url = (base_url or preset["base_url"]).rstrip("/")
+        self.model = model or preset["default_model"]
+        self.api_key = api_key or os.environ.get(preset["env"], "")
+        if not self.api_key and provider != "local":
+            raise ValueError(
+                f"No API key for provider '{provider}'. Set the {preset['env']} Space secret "
+                "or pass api_key in the request.")
+        self._transport = transport
+
+    def chat(self, messages: list[dict], tools: list[dict]) -> dict:
+        if self._transport is not None:
+            return self._transport(self, messages, tools)
+        if self.dialect == "anthropic":
+            return self._chat_anthropic(messages, tools)
+        return self._chat_openai(messages, tools)
+
+    def _chat_anthropic(self, messages: list[dict], tools: list[dict]) -> dict:
+        resp = httpx.post(
+            f"{self.base_url}/v1/messages",
+            headers={"x-api-key": self.api_key, "anthropic-version": "2023-06-01"},
+            json={"model": self.model, "max_tokens": 2000, "system": SYSTEM_PROMPT,
+                  "messages": messages, "tools": tools},
+            timeout=120.0)
+        resp.raise_for_status()
+        data = resp.json()
+        calls = [{"id": b["id"], "name": b["name"], "arguments": b["input"]}
+                 for b in data.get("content", []) if b.get("type") == "tool_use"]
+        text = "".join(b.get("text", "") for b in data.get("content", []) if b.get("type") == "text")
+        return {"text": text, "tool_calls": calls, "raw_content": data.get("content", []),
+                "stop": data.get("stop_reason")}
+
+    def _chat_openai(self, messages: list[dict], tools: list[dict]) -> dict:
+        oai_tools = [{"type": "function",
+                      "function": {"name": t["name"], "description": t["description"],
+                                   "parameters": t["input_schema"]}} for t in tools]
+        oai_messages = [{"role": "system", "content": SYSTEM_PROMPT}] + messages
+        headers = {"Content-Type": "application/json"}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        resp = httpx.post(f"{self.base_url}/chat/completions", headers=headers,
+                          json={"model": self.model, "messages": oai_messages,
+                                "tools": oai_tools or None}, timeout=120.0)
+        resp.raise_for_status()
+        msg = resp.json()["choices"][0]["message"]
+        calls = [{"id": c["id"], "name": c["function"]["name"],
+                  "arguments": json.loads(c["function"]["arguments"] or "{}")}
+                 for c in (msg.get("tool_calls") or [])]
+        return {"text": msg.get("content") or "", "tool_calls": calls,
+                "raw_message": msg, "stop": "tool_use" if calls else "end"}
+
+
+def run_agent(question: str, provider: str = "anthropic", model: str | None = None,
+              api_key: str | None = None, base_url: str | None = None,
+              session_id: str | None = None, inp_content: str | None = None,
+              allow_report: bool = False, max_steps: int = MAX_STEPS,
+              transport: Any | None = None) -> dict:
+    """Run the tool-use loop and return {answer, tool_trace, steps, provider}."""
+    client = LLMClient(provider, model, api_key, base_url, transport)
+    tool_names = list(AGENT_TOOLS_DEFAULT) + (["generate_report", "close_session"] if allow_report else [])
+    tools = _tool_schemas(tool_names)
+
+    user_text = question
+    if session_id:
+        user_text += f"\n\n(Existing session_id: {session_id})"
+    if inp_content:
+        user_text += "\n\nA SWMM .inp model is provided below — upload it first.\n<inp_file>\n" + inp_content[:400000] + "\n</inp_file>"
+
+    trace: list[dict[str, Any]] = []
+    if client.dialect == "anthropic":
+        messages: list[dict] = [{"role": "user", "content": user_text}]
+        for step in range(max_steps):
+            reply = client.chat(messages, tools)
+            if not reply["tool_calls"]:
+                return {"answer": reply["text"], "tool_trace": trace, "steps": step + 1,
+                        "provider": provider, "model": client.model}
+            messages.append({"role": "assistant", "content": reply["raw_content"]})
+            results_content = []
+            for call in reply["tool_calls"]:
+                t0 = time.time()
+                output = _execute(call["name"], call["arguments"])
+                trace.append({"tool": call["name"], "arguments": call["arguments"],
+                              "elapsed_s": round(time.time() - t0, 2),
+                              "result_preview": output[:400]})
+                results_content.append({"type": "tool_result", "tool_use_id": call["id"],
+                                        "content": output})
+            messages.append({"role": "user", "content": results_content})
+    else:
+        messages = [{"role": "user", "content": user_text}]
+        for step in range(max_steps):
+            reply = client.chat(messages, tools)
+            if not reply["tool_calls"]:
+                return {"answer": reply["text"], "tool_trace": trace, "steps": step + 1,
+                        "provider": provider, "model": client.model}
+            messages.append(reply["raw_message"])
+            for call in reply["tool_calls"]:
+                t0 = time.time()
+                output = _execute(call["name"], call["arguments"])
+                trace.append({"tool": call["name"], "arguments": call["arguments"],
+                              "elapsed_s": round(time.time() - t0, 2),
+                              "result_preview": output[:400]})
+                messages.append({"role": "tool", "tool_call_id": call["id"], "content": output})
+
+    return {"answer": "Agent reached the maximum number of steps without a final answer. "
+                      "Partial evidence is in tool_trace.",
+            "tool_trace": trace, "steps": max_steps, "provider": provider, "model": client.model}

ai_report_assistant.py

@@ -0,0 +1,205 @@
+"""Optional AI assistance for Calgary SWMR drafting and consistency review.
+
+This module is intentionally separate from the general model-analysis agent.
+The deterministic report engine remains the source of all engineering values,
+criteria statuses, checklist statuses, and permitted conclusions.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+import requests
+
+PROMPT_DIR = Path(__file__).resolve().parent / "prompts"
+
+PROVIDERS: dict[str, dict[str, Any]] = {
+    "Claude (Anthropic)": {
+        "models": ["claude-opus-4-5", "claude-sonnet-4-5", "claude-haiku-4-5"],
+        "format": "anthropic",
+        "url": "https://api.anthropic.com/v1/messages",
+    },
+    "GPT (OpenAI)": {
+        "models": ["gpt-4o", "gpt-4o-mini", "gpt-4-turbo"],
+        "format": "openai",
+        "url": "https://api.openai.com/v1/chat/completions",
+    },
+    "Gemini (Google)": {
+        "models": ["gemini-2.0-flash", "gemini-1.5-pro", "gemini-1.5-flash"],
+        "format": "gemini",
+        "url": "https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent",
+    },
+    "Groq (Free tier)": {
+        "models": ["llama-3.3-70b-versatile", "llama-3.1-8b-instant", "mixtral-8x7b-32768"],
+        "format": "openai",
+        "url": "https://api.groq.com/openai/v1/chat/completions",
+    },
+    "Mistral": {
+        "models": ["mistral-large-latest", "mistral-small-latest", "open-mistral-7b"],
+        "format": "openai",
+        "url": "https://api.mistral.ai/v1/chat/completions",
+    },
+}
+
+
+def load_prompt(name: str) -> str:
+    path = PROMPT_DIR / name
+    if not path.exists():
+        raise FileNotFoundError(f"Prompt file not found: {path}")
+    return path.read_text(encoding="utf-8").strip()
+
+
+DRAFT_SYSTEM_PROMPT = load_prompt("calgary_report_drafting_system.txt")
+REVIEW_SYSTEM_PROMPT = load_prompt("calgary_report_review_system.txt")
+
+
+def _call_provider(
+    provider_name: str,
+    api_key: str,
+    model: str,
+    messages: Sequence[Mapping[str, str]],
+    system_prompt: str,
+    max_tokens: int = 3200,
+    timeout: int = 90,
+) -> str:
+    if provider_name not in PROVIDERS:
+        raise ValueError(f"Unsupported provider: {provider_name}")
+    if not api_key.strip():
+        raise ValueError("An API key is required for optional AI assistance.")
+
+    provider = PROVIDERS[provider_name]
+    fmt = provider["format"]
+
+    if fmt == "anthropic":
+        response = requests.post(
+            provider["url"],
+            headers={
+                "Content-Type": "application/json",
+                "x-api-key": api_key,
+                "anthropic-version": "2023-06-01",
+            },
+            json={
+                "model": model,
+                "max_tokens": max_tokens,
+                "system": system_prompt,
+                "messages": list(messages),
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return response.json()["content"][0]["text"].strip()
+
+    if fmt == "openai":
+        response = requests.post(
+            provider["url"],
+            headers={
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {api_key}",
+            },
+            json={
+                "model": model,
+                "max_tokens": max_tokens,
+                "messages": [{"role": "system", "content": system_prompt}] + list(messages),
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return response.json()["choices"][0]["message"]["content"].strip()
+
+    if fmt == "gemini":
+        url = provider["url"].replace("{model}", model) + f"?key={api_key}"
+        contents = []
+        for message in messages:
+            role = "model" if message["role"] == "assistant" else "user"
+            contents.append({"role": role, "parts": [{"text": message["content"]}]})
+        response = requests.post(
+            url,
+            json={
+                "system_instruction": {"parts": [{"text": system_prompt}]},
+                "contents": contents,
+                "generationConfig": {"maxOutputTokens": max_tokens},
+            },
+            timeout=timeout,
+        )
+        response.raise_for_status()
+        return response.json()["candidates"][0]["content"]["parts"][0]["text"].strip()
+
+    raise ValueError(f"Provider format is not implemented: {fmt}")
+
+
+def _safe_json(data: Mapping[str, Any]) -> str:
+    return json.dumps(data, ensure_ascii=False, default=str, separators=(",", ":"))
+
+
+def draft_report_section(
+    *,
+    provider_name: str,
+    api_key: str,
+    model: str,
+    section: str,
+    report_context: Mapping[str, Any],
+    additional_instruction: str = "",
+) -> str:
+    """Draft narrative from deterministic report context only."""
+    request = f"""Prepare this Calgary SWMR draft component: {section}.
+
+Use only the VERIFIED_REPORT_CONTEXT JSON below. Follow every conclusion-control,
+checklist, storage, outfall, minor-system, major-system, and model-input/output rule
+in the system prompt. Preserve all values and units exactly.
+
+VERIFIED_REPORT_CONTEXT:
+{_safe_json(report_context)}
+
+ADDITIONAL_USER_INSTRUCTION:
+{additional_instruction.strip() or 'None'}
+
+Return report-ready prose with clear headings. Do not include a preamble about being an AI.
+"""
+    return _call_provider(
+        provider_name,
+        api_key,
+        model,
+        [{"role": "user", "content": request}],
+        DRAFT_SYSTEM_PROMPT,
+    )
+
+
+def review_report_narrative(
+    *,
+    provider_name: str,
+    api_key: str,
+    model: str,
+    narrative: str,
+    report_context: Mapping[str, Any],
+) -> str:
+    """Review narrative against deterministic facts without changing model results."""
+    request = f"""Review the DRAFT_NARRATIVE against VERIFIED_REPORT_CONTEXT.
+Identify unsupported claims, value or unit discrepancies, checklist omissions,
+misuse of criteria, overstatements, and contradictions. Then provide corrected
+replacement wording for each material issue.
+
+VERIFIED_REPORT_CONTEXT:
+{_safe_json(report_context)}
+
+DRAFT_NARRATIVE:
+{narrative}
+"""
+    return _call_provider(
+        provider_name,
+        api_key,
+        model,
+        [{"role": "user", "content": request}],
+        REVIEW_SYSTEM_PROMPT,
+    )
+
+
+def draft_multiple_report_sections(*, provider_name: str, api_key: str, model: str, sections: Sequence[str], report_context: Mapping[str, Any], additional_instruction: str = "") -> dict[str, str]:
+    """Generate independent section drafts so each can be reviewed and approved."""
+    drafts: dict[str, str] = {}
+    for section in sections:
+        drafts[section] = draft_report_section(
+            provider_name=provider_name, api_key=api_key, model=model, section=section,
+            report_context=report_context, additional_instruction=additional_instruction,
+        )
+    return drafts

calgary_rules.py

@@ -0,0 +1,302 @@
+"""Deterministic Calgary SWMR criteria helpers.
+
+The rules in this module are deliberately transparent and configurable. They are
+screening/default values, not a substitute for current City direction, an
+approved SMDP/MDP, or professional engineering judgement.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+import pandas as pd
+
+
+@dataclass
+class CalgaryCriteria:
+    profile_name: str = "City of Calgary SWMR"
+    source_manual: str = "City of Calgary Stormwater Management & Design Manual (2011)"
+    manual_status: str = "Historical baseline - verify current amendments"
+    minor_release_rate_lps_ha: float | None = None
+    trap_low_max_depth_m: float = 0.50
+    entrance_grade_margin_m: float = 0.30
+    pipe_advisory_velocity_mps: float = 3.0
+    pipe_critical_velocity_mps: float = 4.0
+    conduit_capacity_review_ratio: float = 0.80
+    conduit_capacity_warning_ratio: float = 0.95
+    continuity_review_pct: float = 0.50
+    continuity_warning_pct: float = 1.00
+    depth_velocity_curve: tuple[tuple[float, float], ...] = (
+        (0.5, 0.80), (1.0, 0.32), (2.0, 0.21), (3.0, 0.09)
+    )
+    special_link_limits: dict[str, float] = field(default_factory=dict)
+    storage_classification: dict[str, str] = field(default_factory=dict)
+    outfall_classification: dict[str, str] = field(default_factory=dict)
+
+
+def infer_design_event(rain_gages: list[str], fallback: str = "Model design event") -> tuple[str, str]:
+    names = [str(x) for x in rain_gages if str(x).strip()]
+    for name in names:
+        normalized = name.replace("_", " ").replace("-", " ")
+        duration = re.search(r"(\d+(?:\.\d+)?)\s*h", normalized, re.I)
+        return_period = re.search(r"(?:1\s*[:/]\s*)?(\d+)\s*y", normalized, re.I)
+        if duration and return_period:
+            return (
+                f"Calgary {duration.group(1)}-hour, 1:{return_period.group(1)}-year design storm",
+                f"Inferred from rain-gage name '{name}'; confirm before issue.",
+            )
+    return fallback, "Entered by user or retained from model metadata; confirm before issue."
+
+
+def permissible_overland_depth(velocity_mps: float, curve: tuple[tuple[float, float], ...]) -> float | None:
+    """Linearly interpolate the Alberta/Calgary street depth-velocity envelope."""
+    try:
+        v = float(velocity_mps)
+    except (TypeError, ValueError):
+        return None
+    pts = sorted((float(x), float(y)) for x, y in curve)
+    if not pts:
+        return None
+    if v <= pts[0][0]:
+        return pts[0][1]
+    if v > pts[-1][0]:
+        return pts[-1][1]
+    for (v1, d1), (v2, d2) in zip(pts[:-1], pts[1:]):
+        if v1 <= v <= v2:
+            f = (v - v1) / (v2 - v1)
+            return d1 + f * (d2 - d1)
+    return None
+
+
+def classify_overland(depth_m: float, velocity_mps: float, curve: tuple[tuple[float, float], ...]) -> tuple[str, float | None]:
+    allowed = permissible_overland_depth(velocity_mps, curve)
+    if allowed is None:
+        return "Review - criterion unavailable", None
+    d = float(depth_m or 0.0)
+    ratio = d / allowed if allowed > 0 else math.inf
+    if ratio <= 0.90:
+        return "Pass", allowed
+    if ratio <= 1.00:
+        return "Pass - near limit", allowed
+    return "Exceeds depth-velocity criterion", allowed
+
+
+def manning_full_capacity_circular(diameter: float, slope: float, n: float, unit_system: str) -> float | None:
+    """Full-flow Manning capacity for a circular conduit in model-native flow units.
+
+    SI result: m3/s. US customary result: cfs.
+    """
+    try:
+        d, s, rough = float(diameter), float(slope), float(n)
+    except (TypeError, ValueError):
+        return None
+    if d <= 0 or s <= 0 or rough <= 0:
+        return None
+    area = math.pi * d * d / 4.0
+    radius = d / 4.0
+    coefficient = 1.0 if unit_system.upper().startswith("SI") else 1.486
+    return coefficient / rough * area * radius ** (2.0 / 3.0) * math.sqrt(s)
+
+
+def build_minor_system_capacity_table(link_table: pd.DataFrame, unit_system: str, flow_unit: str, length_unit: str, criteria: CalgaryCriteria) -> pd.DataFrame:
+    if link_table is None or link_table.empty:
+        return pd.DataFrame()
+    df = link_table.copy()
+    if "Model Type" in df:
+        df = df[df["Model Type"].astype(str).str.lower().eq("conduit")]
+    if "Shape" in df:
+        df = df[df["Shape"].astype(str).str.upper().eq("CIRCULAR")]
+    diam_col = next((c for c in df.columns if c.startswith("Diameter / Geom1") or c.startswith("Diameter (")), None)
+    flow_col = next((c for c in df.columns if c.startswith("Peak Flow (")), None)
+    length_col = next((c for c in df.columns if c.startswith("Length (")), None)
+    if not all([diam_col, flow_col]):
+        return pd.DataFrame()
+    rows = []
+    for _, r in df.iterrows():
+        slope = pd.to_numeric(r.get("Slope (ft/ft)", r.get("Slope", math.nan)), errors="coerce")
+        # The model table may not include slope. Calculate from offsets/inverts only when explicitly available.
+        cap = manning_full_capacity_circular(r.get(diam_col), slope, r.get("Manning n"), unit_system) if pd.notna(slope) else None
+        peak = pd.to_numeric(r.get(flow_col), errors="coerce")
+        modelled_depth_ratio = pd.to_numeric(r.get("Depth Ratio"), errors="coerce")
+        capacity_ratio = float(peak / cap) if cap and pd.notna(peak) else math.nan
+        if pd.notna(capacity_ratio):
+            if capacity_ratio >= criteria.conduit_capacity_warning_ratio:
+                status = "Warning - limited calculated capacity"
+            elif capacity_ratio >= criteria.conduit_capacity_review_ratio:
+                status = "Review calculated capacity"
+            else:
+                status = "Pass calculated capacity screening"
+            capacity_basis = "Manning full-flow capacity"
+        elif pd.notna(modelled_depth_ratio):
+            if modelled_depth_ratio >= criteria.conduit_capacity_warning_ratio:
+                status = "Warning - high modelled depth ratio"
+            elif modelled_depth_ratio >= criteria.conduit_capacity_review_ratio:
+                status = "Review modelled depth ratio"
+            else:
+                status = "Below depth-ratio screening threshold"
+            capacity_basis = "Full-flow capacity not calculated"
+        else:
+            status = "Not assessed - missing capacity and depth ratio"
+            capacity_basis = "Insufficient data"
+        rows.append({
+            "Segment": r.get("Link ID"), "From": r.get("From Node"), "To": r.get("To Node"),
+            f"Diameter ({length_unit})": r.get(diam_col), f"Length ({length_unit})": r.get(length_col) if length_col else None,
+            "Manning n": r.get("Manning n"), f"Routed Flow ({flow_unit})": peak,
+            f"Full-Flow Capacity ({flow_unit})": cap,
+            "Calculated Capacity Ratio": capacity_ratio if pd.notna(capacity_ratio) else None,
+            "Modelled Depth Ratio": modelled_depth_ratio if pd.notna(modelled_depth_ratio) else None,
+            f"Spare Capacity ({flow_unit})": (cap - peak) if cap and pd.notna(peak) else None,
+            "Assessment Basis": capacity_basis,
+            "Status": status,
+        })
+    return pd.DataFrame(rows)
+
+
+def build_overland_compliance_table(overland: pd.DataFrame, criteria: CalgaryCriteria, flow_unit: str, length_unit: str, velocity_unit: str) -> pd.DataFrame:
+    if overland is None or overland.empty:
+        return pd.DataFrame()
+    flow_col = next((c for c in overland.columns if c.startswith("Peak Flow (")), None)
+    depth_col = next((c for c in overland.columns if c.startswith("Peak Depth (")), None)
+    vel_col = next((c for c in overland.columns if c.startswith("Peak Velocity (")), None)
+    rows = []
+    for _, r in overland.iterrows():
+        d = pd.to_numeric(r.get(depth_col), errors="coerce") if depth_col else math.nan
+        v = pd.to_numeric(r.get(vel_col), errors="coerce") if vel_col else math.nan
+        status, permitted = classify_overland(d, v, criteria.depth_velocity_curve) if pd.notna(d) and pd.notna(v) else ("Review - missing depth/velocity", None)
+        link_id = str(r.get("Link ID", ""))
+        special_limit = criteria.special_link_limits.get(link_id)
+        special_status = ""
+        if special_limit is not None and flow_col:
+            q = pd.to_numeric(r.get(flow_col), errors="coerce")
+            special_status = "Pass" if pd.notna(q) and q <= special_limit else "Exceeds project-specific flow limit"
+        rows.append({
+            "Segment": link_id, "From": r.get("From Node"), "To": r.get("To Node"),
+            f"Peak Flow ({flow_unit})": r.get(flow_col) if flow_col else None,
+            f"Peak Depth ({length_unit})": d, f"Peak Velocity ({velocity_unit})": v,
+            f"Permissible Depth ({length_unit})": permitted, "Depth-Velocity Status": status,
+            f"Special Flow Limit ({flow_unit})": special_limit, "Special Limit Status": special_status,
+            "Spill Active": "Yes" if ("spill" in link_id.lower() and pd.to_numeric(r.get(flow_col), errors="coerce") > 0) else "No",
+        })
+    return pd.DataFrame(rows)
+
+
+def apply_storage_classification(storage_table: pd.DataFrame, criteria: CalgaryCriteria, length_unit: str) -> pd.DataFrame:
+    if storage_table is None or storage_table.empty:
+        return pd.DataFrame()
+    df = storage_table.copy()
+    depth_col = next((c for c in df.columns if c.startswith("Time-Series Peak Depth") or c.startswith("Reported Peak Depth")), None)
+    max_col = next((c for c in df.columns if c.startswith("Maximum Depth")), None)
+    classes, statuses, margins = [], [], []
+    for _, r in df.iterrows():
+        sid = str(r.get("Storage ID", ""))
+        cls = criteria.storage_classification.get(sid)
+        if not cls:
+            s = sid.lower()
+            if "storage" in s:
+                cls = "Street trap low / surface storage"
+            elif s.startswith("cb"):
+                cls = "Catchbasin ponding storage"
+            elif s.startswith("sub"):
+                cls = "Private-site / routing storage"
+            else:
+                cls = "Unclassified storage"
+        peak = pd.to_numeric(r.get(depth_col), errors="coerce") if depth_col else math.nan
+        maxd = pd.to_numeric(r.get(max_col), errors="coerce") if max_col else math.nan
+        margin = maxd - peak if pd.notna(maxd) and pd.notna(peak) else math.nan
+        ratio = peak / maxd if pd.notna(maxd) and maxd > 0 and pd.notna(peak) else math.nan
+        if cls.startswith("Street trap"):
+            if pd.isna(peak): status = "Review - missing peak depth"
+            elif peak > criteria.trap_low_max_depth_m: status = "Exceeds trap-low depth criterion"
+            elif peak >= 0.95 * criteria.trap_low_max_depth_m: status = "Pass - limited margin"
+            else: status = "Pass"
+        else:
+            if pd.isna(ratio): status = "Review - unclassified or incomplete"
+            elif ratio >= 1.0: status = "Exceeded"
+            elif ratio >= 0.90: status = "Near capacity"
+            else: status = "Pass"
+        classes.append(cls); statuses.append(status); margins.append(margin)
+    df.insert(1, "Calgary Storage Classification", classes)
+    df[f"Remaining Depth Margin ({length_unit})"] = margins
+    df["Calgary Status"] = statuses
+    return df
+
+
+def criteria_register(criteria: CalgaryCriteria) -> pd.DataFrame:
+    rows = [
+        ("CAL-GEN-001", "Source manual", criteria.source_manual, criteria.manual_status, "Verify current City amendments"),
+        ("CAL-MIN-001", "Minor-system release rate", criteria.minor_release_rate_lps_ha, "Project-specific", "L/s/ha"),
+        ("CAL-MAJ-001", "Street depth-velocity envelope", json.dumps(criteria.depth_velocity_curve), "Calgary/Alberta reference curve", "m/s vs m"),
+        ("CAL-TRL-001", "Trap-low maximum ponding depth", criteria.trap_low_max_depth_m, "Configurable default", "m"),
+        ("CAL-TRL-002", "Entrance grade margin", criteria.entrance_grade_margin_m, "Configurable default", "m"),
+        ("CAL-MIN-002", "Conduit capacity review ratio", criteria.conduit_capacity_review_ratio, "Screening", "fraction"),
+        ("CAL-MIN-003", "Conduit capacity warning ratio", criteria.conduit_capacity_warning_ratio, "Screening", "fraction"),
+        ("CAL-QA-001", "Continuity review threshold", criteria.continuity_review_pct, "Screening", "%"),
+        ("CAL-QA-002", "Continuity warning threshold", criteria.continuity_warning_pct, "Screening", "%"),
+    ]
+    return pd.DataFrame(rows, columns=["Rule ID", "Criterion", "Value", "Rule Status", "Units / Note"])
+
+
+def build_llm_report_context(*, metadata: dict[str, Any], criteria: CalgaryCriteria, findings: list[str], tables: dict[str, pd.DataFrame]) -> dict[str, Any]:
+    compact_tables = {}
+    for name, df in tables.items():
+        if df is not None and not df.empty:
+            compact_tables[name] = df.head(30).where(pd.notna(df), None).to_dict(orient="records")
+    return {
+        "task": "Draft a City of Calgary stormwater management report narrative for professional review.",
+        "metadata": metadata,
+        "approved_criteria": asdict(criteria),
+        "deterministic_findings": findings,
+        "verified_tables": compact_tables,
+        "interpretation_controls": {
+            "minor_system_primary_metric": "modelled depth ratio unless a calculated full-flow capacity is present",
+            "full_flow_capacity_available": bool("minor_system" in compact_tables and any(r.get("Full-Flow Capacity (m³/s)") is not None or r.get("Full-Flow Capacity (cfs)") is not None for r in compact_tables.get("minor_system", []))),
+            "generic_storage_freeboard_screening_allowed": False,
+            "storm_name_verified": False,
+            "model_input_output_overall_status": next((r.get("Status") for r in compact_tables.get("swmr_checklist", []) if r.get("Item") == "SWMR-17"), "Not assessed"),
+            "allowed_conclusions": {"adequate": False, "compliant": False, "safe": False, "effective": False, "approved": False},
+        },
+        "preferred_wording": {
+            "minor_system": "Use 'modelled depth ratio' when full-flow capacity is unavailable.",
+            "storage": "Use 'remaining depth margin' for maximum ponding-depth criteria.",
+            "event": "State that the design-event name is inferred when not independently verified.",
+            "outfalls": "Report modelled flows and state that downstream capacity requires confirmation.",
+            "model_documentation": "Distinguish digital package completeness from report appendix, schematic, drawing reconciliation, and authenticated-file completeness.",
+        },
+        "constraints": [
+            "Do not change or recalculate numerical results.",
+            "Do not claim City approval or professional certification.",
+            "Identify inferred, project-specific, historical, and unverified criteria.",
+            "Use 'not provided' where project facts are missing.",
+            "Distinguish pass, warning, information gap, and professional judgement.",
+            "Do not use adequate, compliant, safe, effective, acceptable, or approved unless deterministic verified criteria authorize that wording.",
+            "Use the Calgary SWMR completeness register and state all missing or partial mandatory items.",
+            "Never call modelled depth ratio capacity used unless calculated full-flow capacity is present.",
+            "Do not apply generic junction freeboard screening to storage nodes.",
+        ],
+    }
+
+
+CALGARY_LLM_SYSTEM_PROMPT = """You are a Calgary stormwater report drafting assistant.
+Use only the verified structured data, deterministic findings, approved Project Criteria Register, and Calgary SWMR Completeness Register supplied by the application.
+Never calculate or modify hydraulic values. Never invent project facts. Never describe a screening threshold as a current City requirement unless its rule status is verified.
+
+ENGINEERING INTERPRETATION RULES
+1. Do not describe the model, system, infrastructure, design, or results as adequate, compliant, safe, effective, acceptable, or approved unless the deterministic compliance engine explicitly returns that conclusion for the applicable verified criterion.
+2. Do not apply generic junction freeboard or depth-ratio criteria to storage nodes. Use the Calgary storage classification, adopted maximum ponding depth, remaining depth margin, utilization, spill elevation, and Calgary status fields.
+3. For active spill links, report the modeled peak flow, depth, velocity, and deterministic depth-velocity screening result. Also require confirmation of grading continuity, route containment, public safety, erosion, downstream impacts, and receiving-system capacity.
+4. Do not state that outfalls manage flow effectively or have adequate receiving capacity. Report only modeled flow, depth, flooding, boundary type, and verified downstream criteria.
+5. When full-flow pipe capacity is unavailable, do not describe conduit depth ratio as full capacity utilization, spare capacity, or hydraulic capacity. Call it modeled depth ratio.
+6. Prioritize approved project-specific criteria, applicable MDP/SMDP/pond-report/prior-SWMR criteria, verified current City requirements, historical manual criteria, then user-defined screening thresholds.
+7. Clearly distinguish deterministic results, screening results, project-specific requirements, historical reference criteria, inferred information, missing information, and professional judgement.
+8. Do not invent project facts, capacities, material properties, downstream conditions, grading information, or compliance conclusions.
+9. Where criteria are missing or unverified, use wording such as 'requires confirmation', 'screening only', 'not established from the available data', or 'cannot be concluded from the model results alone'.
+10. The generated text is an engineering draft for professional review and must not be presented as final certification or municipal approval.
+
+CALGARY SWMR CHECKLIST RULES
+Use the completeness register when drafting. Do not omit a checklist subject merely because data are unavailable; state what is missing and what must be provided. For each material conclusion, identify supporting report tables, figures, model results, approved criteria, or source documents. Do not state that the SWMR is complete when mandatory items are Missing, Partially complete, or Require professional confirmation. Highlight unresolved issues, departures, missing project data, drawing gaps, and unverified downstream conditions in the executive summary and Outstanding Information and Actions section. Distinguish model-derived information from drawing-, survey-, project-, and professionally-confirmed information.
+
+Draft clear consultant-quality narrative for professional review. Do not certify compliance or approval.
+"""

calgary_rules.yaml

@@ -0,0 +1,22 @@
+profile: City of Calgary SWMR
+source_manual:
+  title: City of Calgary Stormwater Management & Design Manual
+  edition: 2011
+  status: historical_baseline_verify_current_amendments
+criteria:
+  trap_low_max_depth_m: 0.50
+  entrance_grade_margin_m: 0.30
+  conduit_capacity_review_ratio: 0.80
+  conduit_capacity_warning_ratio: 0.95
+  pipe_advisory_velocity_mps: 3.0
+  pipe_critical_velocity_mps: 4.0
+  continuity_review_pct: 0.50
+  continuity_warning_pct: 1.00
+  depth_velocity_curve:
+    - [0.5, 0.80]
+    - [1.0, 0.32]
+    - [2.0, 0.21]
+    - [3.0, 0.09]
+notes:
+  - Project-specific SMDP, MDP, pond report, City direction, and current amendments take precedence.
+  - Values marked as screening criteria are not automatic compliance limits.

model_pipeline.py

@@ -0,0 +1,319 @@
+"""Headless SWMM model pipeline: INP parsing and result-summary builders.
+
+Extracted verbatim from the SWMM6 GIS Tool (Rev 23.2) Streamlit app so the
+same deterministic logic serves the MCP/REST server without a Streamlit
+dependency. Includes the Rev 23.2 fix resolving IRREGULAR-section full depth
+from [TRANSECTS] GR data.
+"""
+from __future__ import annotations
+
+import pandas as pd
+import numpy as np
+
+def parse_inp_sections(inp_path):
+    sections = {}
+    current = None
+    with open(inp_path, encoding="utf-8", errors="ignore") as f:
+        for line in f:
+            line = line.strip()
+            if not line or line.startswith(";"):
+                continue
+            if line.startswith("["):
+                try:
+                    current = line[1:line.index("]")]
+                    sections[current] = []
+                except ValueError:
+                    pass
+            elif current is not None:
+                sections[current].append(line.split())
+    return sections
+
+def parse_node_types(sections):
+    types = {}
+    for sname, ntype in [("JUNCTIONS", "junction"), ("OUTFALLS", "outfall"),
+                          ("STORAGE", "storage"), ("DIVIDERS", "divider")]:
+        for row in sections.get(sname, []):
+            if row:
+                types[row[0]] = ntype
+    return types
+
+def parse_link_topology(sections):
+    """Return {link_id: (from_node, to_node, type)} dict."""
+    topo = {}
+    for sname, ltype in [("CONDUITS", "conduit"), ("PUMPS", "pump"),
+                          ("ORIFICES", "orifice"), ("WEIRS", "weir"), ("OUTLETS", "outlet")]:
+        for row in sections.get(sname, []):
+            if len(row) >= 3:
+                topo[row[0]] = (row[1], row[2], ltype)
+    return topo
+
+def parse_conduit_geometry(sections):
+    """Return {conduit_id: {length, roughness, xsect_params}} dict."""
+    geom = {}
+    for row in sections.get("CONDUITS", []):
+        if len(row) >= 6:
+            try:
+                geom[row[0]] = {"length": float(row[3]), "roughness": float(row[4])}
+            except ValueError:
+                pass
+    # Full depth of IRREGULAR sections comes from the referenced transect's
+    # GR rows (max station elevation - min station elevation), matching the
+    # engine's Cross Section Summary "Full Depth". Previously float() failed
+    # on the transect NAME in geom1 and the depth silently defaulted to
+    # 1.0 m downstream, distorting depth ratios for street/overland links.
+    transect_full_depth = {}
+    current_transect = None
+    for row in sections.get("TRANSECTS", []):
+        tag = str(row[0]).upper()
+        if tag == "X1" and len(row) >= 2:
+            current_transect = row[1]
+            transect_full_depth.setdefault(current_transect, [])
+        elif tag == "GR" and current_transect is not None:
+            # GR rows are (elev, station) pairs.
+            for i in range(1, len(row) - 1, 2):
+                try:
+                    transect_full_depth[current_transect].append(float(row[i]))
+                except ValueError:
+                    pass
+    transect_full_depth = {
+        name: (max(elevs) - min(elevs)) for name, elevs in transect_full_depth.items() if elevs
+    }
+    for row in sections.get("XSECTIONS", []):
+        if len(row) >= 3 and row[0] in geom:
+            geom[row[0]]["shape"] = row[1]
+            if str(row[1]).upper() == "IRREGULAR":
+                geom[row[0]]["transect"] = row[2]
+                full = transect_full_depth.get(row[2])
+                if full and full > 0:
+                    geom[row[0]]["diameter"] = full
+            else:
+                try:
+                    geom[row[0]]["diameter"] = float(row[2])
+                except (ValueError, IndexError):
+                    pass
+    return geom
+
+def parse_subcatchment_attrs(sections):
+    attrs = {}
+    for row in sections.get("SUBCATCHMENTS", []):
+        if len(row) >= 6:
+            try:
+                attrs[row[0]] = {
+                    "gage": row[1],
+                    "outlet": row[2],
+                    "area": float(row[3]),
+                    "pct_imp": float(row[4]),
+                    "width": float(row[5]) if len(row) > 5 else 0.0,
+                    "slope": float(row[6]) if len(row) > 6 else 0.0,
+                }
+            except (ValueError, IndexError):
+                pass
+    return attrs
+
+def parse_gis(sections):
+    """Extract node coords, link vertices, sub polygons from INP."""
+    dims = get_map_dimensions(sections)
+
+    # Node coordinates
+    raw_coords = {}
+    for row in sections.get("COORDINATES", []):
+        if len(row) >= 3:
+            try:
+                raw_coords[row[0]] = (float(row[1]), float(row[2]))
+            except ValueError:
+                pass
+
+    node_coords = normalize_coords(raw_coords, dims)
+
+    # Link vertices
+    raw_verts = {}
+    for row in sections.get("VERTICES", []):
+        if len(row) >= 3:
+            try:
+                raw_verts.setdefault(row[0], []).append((float(row[1]), float(row[2])))
+            except ValueError:
+                pass
+
+    # Normalize vertices using same scale
+    if raw_coords and dims:
+        xmin, ymin, xmax, ymax = dims
+        cx = (xmin + xmax) / 2
+        cy = (ymin + ymax) / 2
+        rx = max(xmax - xmin, 1e-9)
+        ry = max(ymax - ymin, 1e-9)
+        scale = 0.005 / max(rx, ry)
+    elif raw_coords:
+        xs = [v[0] for v in raw_coords.values()]
+        ys = [v[1] for v in raw_coords.values()]
+        cx = (min(xs) + max(xs)) / 2
+        cy = (min(ys) + max(ys)) / 2
+        scale = 0.005 / max(max(xs) - min(xs), max(ys) - min(ys), 1e-9)
+    else:
+        cx, cy, scale = 0, 0, 1
+
+    link_vertices = {}
+    for lid, verts in raw_verts.items():
+        link_vertices[lid] = [((x - cx) * scale, (y - cy) * scale) for x, y in verts]
+
+    # Subcatchment polygons
+    raw_polys = {}
+    for row in sections.get("Polygons", []):
+        if len(row) >= 3:
+            try:
+                raw_polys.setdefault(row[0], []).append((float(row[1]), float(row[2])))
+            except ValueError:
+                pass
+
+    sub_polygons = {}
+    for sid, pts in raw_polys.items():
+        sub_polygons[sid] = [((x - cx) * scale, (y - cy) * scale) for x, y in pts]
+
+    return node_coords, link_vertices, sub_polygons
+
+def build_node_summary(node_ts, node_types, flood_thresh, depth_ratio_thresh):
+    rows = []
+    for nid, d in node_ts.items():
+        depths = d.get("depth", [0])
+        floods = d.get("flooding", [0])
+        inflows = d.get("inflow", [0])
+        invert = d.get("invert_elevation", 0)
+        full_d = d.get("full_depth", 1) or 1
+
+        pk_depth = max(depths) if depths else 0
+        pk_flood = max(floods) if floods else 0
+        pk_inflow = max(inflows) if inflows else 0
+        depth_ratio = pk_depth / full_d
+
+        if pk_flood > flood_thresh:
+            status = "🚨 Flooded"
+        elif depth_ratio > depth_ratio_thresh:
+            status = "⚠️ Near Capacity"
+        else:
+            status = "✅ OK"
+
+        rows.append({
+            "Node ID": nid,
+            "Type": node_types.get(nid, "junction"),
+            "Invert (m)": round(invert, 3),
+            "Full Depth (m)": round(full_d, 3),
+            "Peak Depth (m)": round(pk_depth, 4),
+            "Depth Ratio": round(depth_ratio, 3),
+            "Peak Flooding (m³/s)": round(pk_flood, 6),
+            "Peak Inflow (m³/s)": round(pk_inflow, 6),
+            "Status": status,
+        })
+    return pd.DataFrame(rows)
+
+def build_link_summary(link_ts, link_topo, conduit_geom, depth_ratio_thresh, vel_thresh):
+    rows = []
+    for lid, d in link_ts.items():
+        flows = d.get("flow", [0])
+        depths = d.get("depth", [0])
+        velocities = d.get("velocity", [0])
+        topo = link_topo.get(lid, ("?", "?", "conduit"))
+        geom = conduit_geom.get(lid, {})
+
+        pk_flow = max(flows) if flows else 0
+        pk_depth = max(depths) if depths else 0
+        pk_velocity = max((abs(v) for v in velocities), default=0)
+        diam = geom.get("diameter", 1) or 1
+        length = geom.get("length", 0)
+        depth_ratio = pk_depth / diam
+
+        if depth_ratio >= 1.0:
+            status = "Pressurised"
+        elif depth_ratio > depth_ratio_thresh:
+            status = "Surcharging"
+        elif pk_velocity > vel_thresh:
+            status = "High Velocity"
+        elif depth_ratio > 0.5:
+            status = "Filling"
+        else:
+            status = "Free-flow"
+
+        rows.append({
+            "Link ID": lid,
+            "Type": topo[2],
+            "From Node": topo[0],
+            "To Node": topo[1],
+            "Length (m)": round(length, 1),
+            "Diameter (m)": round(diam, 3),
+            "Peak Flow (m³/s)": round(pk_flow, 6),
+            "Peak Depth (m)": round(pk_depth, 4),
+            "Depth Ratio": round(depth_ratio, 3),
+            "Peak Velocity (m/s)": round(pk_velocity, 3),
+            "Status": status,
+        })
+    return pd.DataFrame(rows)
+
+def build_sub_summary(sub_ts, sub_attrs, times=None, flow_units="CMS"):
+    """Build subcatchment summary with time-integrated runoff volume.
+
+    Values remain in the SWMM model unit system. The legacy internal column name
+    ``Total Runoff (m³)`` is retained for database compatibility, but its value is
+    flow integrated over time in the native flow-volume basis (e.g., ft³ for CFS,
+    m³ for CMS, litres for LPS). The report engine assigns the correct label.
+    """
+    rows = []
+    flow_units = str(flow_units or "CMS").upper()
+
+    def _integrate(values, timestamps):
+        if not values:
+            return 0.0
+        if timestamps and len(timestamps) == len(values) and len(values) > 1:
+            total = 0.0
+            for i in range(1, len(values)):
+                try:
+                    dt = (timestamps[i] - timestamps[i - 1]).total_seconds()
+                except Exception:
+                    dt = 0.0
+                if dt > 0:
+                    total += 0.5 * (float(values[i - 1]) + float(values[i])) * dt
+            return total
+        return float(sum(values))
+
+    def _rain_depth(values, timestamps):
+        # Rainfall is an intensity (in/hr for US, mm/hr for SI).
+        return _integrate(values, timestamps) / 3600.0
+
+    for sid, d in sub_ts.items():
+        runoffs = d.get("runoff", [0])
+        rainfalls = d.get("rainfall", [0])
+        attrs = sub_attrs.get(sid, {})
+        area = d.get("area", attrs.get("area", 0))
+        pct_imp = d.get("pct_imp", attrs.get("pct_imp", 0))
+
+        pk_runoff = max(runoffs) if runoffs else 0
+        pk_rainfall = max(rainfalls) if rainfalls else 0
+        integrated_flow_seconds = _integrate(runoffs, times)
+        total_rain_depth = _rain_depth(rainfalls, times)
+
+        # Convert integrated native flow to the native report volume basis.
+        if flow_units == "CFS":
+            total_runoff_vol = integrated_flow_seconds  # ft³
+            runoff_depth = (total_runoff_vol / (area * 43560.0) * 12.0) if area > 0 else 0.0
+        elif flow_units == "CMS":
+            total_runoff_vol = integrated_flow_seconds  # m³
+            runoff_depth = (total_runoff_vol / (area * 10000.0) * 1000.0) if area > 0 else 0.0
+        elif flow_units == "LPS":
+            total_runoff_vol = integrated_flow_seconds  # litres
+            runoff_depth = ((total_runoff_vol / 1000.0) / (area * 10000.0) * 1000.0) if area > 0 else 0.0
+        else:
+            total_runoff_vol = integrated_flow_seconds
+            runoff_depth = 0.0
+
+        rc = (runoff_depth / total_rain_depth) if total_rain_depth > 0 else 0.0
+
+        rows.append({
+            "Sub ID": sid,
+            "Area (ha)": round(area, 3),
+            "% Impervious": round(pct_imp, 1),
+            "Connected To": attrs.get("outlet", "?"),
+            "Peak Runoff (m³/s)": round(pk_runoff, 6),
+            "Total Runoff (m³)": round(total_runoff_vol, 3),
+            "Peak Rainfall (mm/h)": round(pk_rainfall, 4),
+            "Total Rainfall Depth": round(total_rain_depth, 4),
+            "Runoff Depth": round(runoff_depth, 4),
+            "Runoff Coefficient": round(rc, 3),
+        })
+    return pd.DataFrame(rows)

preliminary_design_assistant.py

@@ -0,0 +1,370 @@
+"""Rev23 preliminary design review and controlled-correction workflow.
+
+Deterministic code identifies traceable model findings and applies only
+engineer-approved edits. The LLM explains and prioritises findings; it does not
+silently alter the model or determine municipal compliance.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime
+from typing import Any, Mapping, Sequence
+import hashlib
+import json
+import re
+
+import pandas as pd
+
+from ai_report_assistant import PROVIDERS, _call_provider, load_prompt
+from scenario_manager import _split_sections, _join_sections, _data_tokens, _replace_tokens, _set_option
+
+REVIEW_SYSTEM_PROMPT = load_prompt("preliminary_design_review_system.txt")
+
+
+@dataclass
+class DesignFinding:
+    finding_id: str
+    category: str
+    severity: str
+    finding_type: str
+    object_type: str = "MODEL"
+    object_id: str = "MODEL"
+    rule_id: str = ""
+    criterion_status: str = "Screening"
+    deterministic_basis: str = ""
+    recommended_action: str = ""
+    proposed_parameter: str = ""
+    proposed_value: Any = None
+    units: str = ""
+    engineer_decision: str = "Defer"
+    resolution_status: str = "Open"
+    reviewer_comment: str = ""
+    ai_explanation: str = ""
+
+
+def _rows(sections: Mapping[str, Sequence[str]], name: str) -> list[list[str]]:
+    out: list[list[str]] = []
+    for line in sections.get(name, []):
+        parsed = _data_tokens(line)
+        if parsed:
+            out.append(parsed[0])
+    return out
+
+
+def _ids(sections: Mapping[str, Sequence[str]], names: Sequence[str]) -> set[str]:
+    values: set[str] = set()
+    for name in names:
+        values.update(row[0] for row in _rows(sections, name) if row)
+    return values
+
+
+def _first_numeric(row: Mapping[str, Any], aliases: Sequence[str]) -> float | None:
+    """Return the first explicitly available numeric value without converting missing data to zero."""
+    for key in aliases:
+        if key not in row:
+            continue
+        value = row.get(key)
+        if value is None or value == "":
+            continue
+        parsed = pd.to_numeric(pd.Series([value]), errors="coerce").iloc[0]
+        if pd.notna(parsed):
+            return float(parsed)
+    return None
+
+
+def _records(df: pd.DataFrame | None, limit: int = 500) -> list[dict[str, Any]]:
+    if df is None or df.empty:
+        return []
+    clean = df.head(limit).copy()
+    clean = clean.where(pd.notna(clean), None)
+    return clean.to_dict(orient="records")
+
+
+def build_deterministic_findings(
+    *,
+    inp_text: str,
+    node_summary: pd.DataFrame | None = None,
+    link_summary: pd.DataFrame | None = None,
+    sub_summary: pd.DataFrame | None = None,
+    metadata: Mapping[str, Any] | None = None,
+    simulation_completed: bool = False,
+    output_results_available: bool = False,
+    flood_threshold: float = 0.0,
+    depth_ratio_threshold: float = 0.85,
+    velocity_threshold: float = 3.0,
+) -> list[dict[str, Any]]:
+    """Create a conservative, traceable preliminary-review register."""
+    _, sections = _split_sections(inp_text)
+    findings: list[DesignFinding] = []
+    counter = 1
+
+    def add(category: str, severity: str, finding_type: str, basis: str, action: str,
+            object_type: str = "MODEL", object_id: str = "MODEL", rule_id: str = "",
+            proposed_parameter: str = "", proposed_value: Any = None, units: str = "",
+            criterion_status: str = "Screening") -> None:
+        nonlocal counter
+        findings.append(DesignFinding(
+            finding_id=f"PDA-{counter:03d}", category=category, severity=severity,
+            finding_type=finding_type, object_type=object_type, object_id=str(object_id),
+            rule_id=rule_id, criterion_status=criterion_status,
+            deterministic_basis=basis, recommended_action=action,
+            proposed_parameter=proposed_parameter, proposed_value=proposed_value, units=units,
+        ))
+        counter += 1
+
+    # Completeness and topology.
+    node_ids = _ids(sections, ["JUNCTIONS", "STORAGE", "OUTFALLS", "DIVIDERS"])
+    link_rows = []
+    for sec in ["CONDUITS", "PUMPS", "ORIFICES", "WEIRS", "OUTLETS"]:
+        for row in _rows(sections, sec):
+            if len(row) >= 3:
+                link_rows.append((sec, row[0], row[1], row[2]))
+    referenced_nodes = {x for _, _, a, b in link_rows for x in (a, b)}
+    # SWMM matches object IDs case-insensitively, so an endpoint that
+    # differs from a defined node only by letter case still routes in the
+    # engine. Treat exact-case misses with a case-insensitive fallback:
+    # genuine misses stay Critical; case-only mismatches are a Medium
+    # naming-consistency finding (they break exact-match post-processing
+    # and GIS joins even though the simulation runs).
+    node_ids_casefold = {str(n).casefold(): n for n in node_ids}
+    for nid in sorted(referenced_nodes - node_ids):
+        matched = node_ids_casefold.get(str(nid).casefold())
+        if matched is not None:
+            add("Topology", "Medium", "ID case inconsistency",
+                f"Link endpoint '{nid}' matches defined node '{matched}' only when letter case is ignored. "
+                "SWMM resolves the connection, but exact-match tools (GIS joins, scripts, result queries) will not.",
+                f"Rename the link endpoint or the node so both use '{matched}' consistently.", "NODE", nid)
+        else:
+            add("Topology", "Critical", "Invalid reference", f"Node '{nid}' is referenced by a link but is not defined.",
+                "Define the node or correct the link endpoint before design use.", "NODE", nid)
+
+    connected = referenced_nodes
+    for nid in sorted(node_ids - connected):
+        # Outfalls/storage-only models can legitimately have simple topology, so advisory.
+        add("Topology", "Advisory", "Connectivity review", f"Node '{nid}' is not referenced by a hydraulic link.",
+            "Confirm whether the node is intentionally isolated or the model connection is incomplete.", "NODE", nid)
+
+    sub_rows = _rows(sections, "SUBCATCHMENTS")
+    sub_names = {r[0] for r in sub_rows}
+    sub_names_casefold = {str(s).casefold(): s for s in sub_names}
+    for row in sub_rows:
+        if len(row) >= 3 and row[2] not in node_ids and row[2] not in sub_names:
+            outlet = str(row[2])
+            matched = node_ids_casefold.get(outlet.casefold()) or sub_names_casefold.get(outlet.casefold())
+            if matched is not None:
+                add("Hydrology", "Medium", "ID case inconsistency",
+                    f"Subcatchment '{row[0]}' outlet '{outlet}' matches defined object '{matched}' only when letter case is ignored. "
+                    "SWMM resolves the routing, but exact-match tools will not.",
+                    f"Rename the outlet reference or the object so both use '{matched}' consistently.", "SUBCATCHMENT", row[0])
+            else:
+                add("Hydrology", "Critical", "Invalid outlet", f"Subcatchment '{row[0]}' routes to undefined outlet '{outlet}'.",
+                    "Correct the outlet reference.", "SUBCATCHMENT", row[0])
+        if len(row) >= 7:
+            try:
+                area, imperv, width, slope = float(row[3]), float(row[4]), float(row[5]), float(row[6])
+                if area <= 0:
+                    add("Hydrology", "High", "Input review", f"Area is {area}.", "Enter a positive drainage area.", "SUBCATCHMENT", row[0], proposed_parameter="area")
+                if imperv < 0 or imperv > 100:
+                    add("Hydrology", "Critical", "Input range", f"Imperviousness is {imperv}%.", "Set imperviousness within 0–100%.", "SUBCATCHMENT", row[0], proposed_parameter="imperviousness", units="%")
+                elif imperv >= 95:
+                    add("Hydrology", "Moderate", "Sensitivity review", f"Imperviousness is {imperv}%.", "Confirm land-use basis and test sensitivity.", "SUBCATCHMENT", row[0])
+                if width <= 0:
+                    add("Hydrology", "High", "Input review", f"Width is {width}.", "Enter and document a representative subcatchment width.", "SUBCATCHMENT", row[0], proposed_parameter="width")
+                if slope <= 0:
+                    add("Hydrology", "High", "Input review", f"Slope is {slope}%.", "Confirm grading and enter a positive slope.", "SUBCATCHMENT", row[0], proposed_parameter="slope", units="%")
+            except Exception:
+                pass
+
+    # Options and rainfall.
+    options = {r[0].upper(): r[1] for r in _rows(sections, "OPTIONS") if len(r) >= 2}
+    if "FLOW_UNITS" not in options:
+        add("Simulation setup", "High", "Missing option", "FLOW_UNITS is not explicitly defined.", "Define and verify the model unit system.")
+    report_step = options.get("REPORT_STEP", "")
+    wet_step = options.get("WET_STEP", "")
+    if not report_step:
+        add("Simulation setup", "Moderate", "Missing option", "REPORT_STEP is not explicitly defined.", "Set a reporting timestep appropriate for the event and control response.", proposed_parameter="REPORT_STEP")
+    if not wet_step:
+        add("Simulation setup", "Moderate", "Missing option", "WET_STEP is not explicitly defined.", "Set and document the wet-weather timestep.", proposed_parameter="WET_STEP")
+    rain_gages = _rows(sections, "RAINGAGES")
+    time_series = _rows(sections, "TIMESERIES")
+    if not rain_gages:
+        add("Rainfall", "Critical", "Missing rainfall", "No [RAINGAGES] records were identified.", "Add and verify the applicable design rainfall.")
+    if rain_gages and not time_series:
+        add("Rainfall", "High", "Rainfall source review", "Rain gages exist but no internal [TIMESERIES] records were identified.", "Confirm external rainfall files and package them with the model.")
+
+    # Deterministic result screening. Result-based findings are permitted only
+    # when a successful simulation and parsed output tables are explicitly available.
+    results_ready = bool(simulation_completed and output_results_available)
+    if results_ready and node_summary is not None and not node_summary.empty:
+        for _, r in node_summary.iterrows():
+            row = r.to_dict()
+            nid = str(row.get("Node ID", row.get("ID", "")))
+            flooding = _first_numeric(row, ["Peak Flooding (m³/s)", "Peak Flooding", "Max Flooding", "Maximum Flooding"] )
+            if flooding is not None and flooding > flood_threshold:
+                add("Hydraulics", "Critical", "Flooding", f"Peak model flooding is {flooding:.6g}.", "Review HGL, rim elevation, downstream boundary, and design alternatives.", "NODE", nid, "CAL-HYD-FLOOD", units=str(metadata.get("flow_units", "") if metadata else ""))
+
+    if results_ready and link_summary is not None and not link_summary.empty:
+        for _, r in link_summary.iterrows():
+            row = r.to_dict()
+            lid = str(row.get("Link ID", row.get("ID", "")))
+            vel = _first_numeric(row, ["Peak Velocity (m/s)", "Max Velocity", "Maximum Velocity", "Velocity"] )
+            ratio = _first_numeric(row, ["Depth Ratio", "Max/Full Depth", "Maximum Depth Ratio"] )
+            if vel is not None and vel > velocity_threshold:
+                add("Hydraulics", "High", "Velocity screening", f"Maximum modelled velocity is {vel:.4g}, above the configured {velocity_threshold:g} screening value.", "Confirm pipe/channel material, erosion protection, energy dissipation, and applicable criterion.", "LINK", lid, "CAL-HYD-VEL", units="model units")
+            if ratio is not None and ratio >= depth_ratio_threshold:
+                add("Hydraulics", "High", "Depth-ratio screening", f"Maximum modelled depth ratio is {ratio:.4g}, at or above the configured {depth_ratio_threshold:g} screening value.", "Review capacity, HGL, surcharge duration, and downstream boundary conditions.", "LINK", lid, "CAL-HYD-DEPTH")
+
+    if results_ready and sub_summary is not None and not sub_summary.empty:
+        zero_runoff_tolerance = 1e-9
+        for _, r in sub_summary.iterrows():
+            row = r.to_dict()
+            sid = str(row.get("Sub ID", row.get("Subcatchment", row.get("ID", ""))))
+            runoff = _first_numeric(row, ["Peak Runoff (m³/s)", "Peak Runoff", "Peak Runoff (cfs)", "Peak Runoff (L/s)"] )
+            if runoff is not None and abs(runoff) <= zero_runoff_tolerance:
+                add("Hydrology", "Moderate", "Zero runoff", "Peak runoff is explicitly reported as zero for the completed simulation.", "Confirm rainfall assignment, infiltration, routing, and subcatchment activation.", "SUBCATCHMENT", sid)
+
+    # Missing design criteria are never silently replaced by generic standards.
+    add("Criteria", "High", "Missing project criterion", "Project-specific allowable release rate is not established by the model alone.", "Enter the approved release criterion and source before evaluating outlet compliance.", rule_id="CAL-MIN-001", criterion_status="Not established")
+    if _rows(sections, "STORAGE"):
+        add("Storage", "High", "Missing project criterion", "Approved pond/storage HWL, freeboard, emergency spill elevation, and classification are not established by the model alone.", "Enter the approved storage criteria and source before concluding performance.", rule_id="CAL-POND-001", criterion_status="Not established")
+
+    return [asdict(x) for x in findings]
+
+
+def findings_dataframe(findings: Sequence[Mapping[str, Any]]) -> pd.DataFrame:
+    columns = [f.name for f in DesignFinding.__dataclass_fields__.values()]
+    df = pd.DataFrame(list(findings))
+    for col in columns:
+        if col not in df.columns:
+            df[col] = ""
+    return df[columns]
+
+
+def build_review_context(
+    *,
+    inp_name: str,
+    inp_text: str,
+    findings: Sequence[Mapping[str, Any]],
+    metadata: Mapping[str, Any],
+    criteria: Mapping[str, Any] | None = None,
+    node_summary: pd.DataFrame | None = None,
+    link_summary: pd.DataFrame | None = None,
+    sub_summary: pd.DataFrame | None = None,
+    simulation_completed: bool = False,
+    output_results_available: bool = False,
+    review_mode: str = "Input and simulation-output review",
+) -> dict[str, Any]:
+    _, sections = _split_sections(inp_text)
+    output_ready = bool(simulation_completed and output_results_available)
+    return {
+        "review_mode": review_mode,
+        "availability": {
+            "model_input_available": bool(inp_text),
+            "simulation_completed": bool(simulation_completed),
+            "output_results_available": bool(output_results_available),
+            "result_based_review_authorized": output_ready,
+        },
+        "model": {
+            "name": inp_name,
+            "sha256": hashlib.sha256(inp_text.encode("utf-8")).hexdigest(),
+            "section_counts": {k: len(_rows(sections, k)) for k in sections},
+        },
+        "metadata": dict(metadata or {}),
+        "criteria": dict(criteria or {}),
+        "simulation_results": {
+            "node_summary": _records(node_summary) if output_ready else [],
+            "link_summary": _records(link_summary) if output_ready else [],
+            "subcatchment_summary": _records(sub_summary) if output_ready else [],
+        },
+        "result_table_counts": {
+            "nodes": 0 if node_summary is None else int(len(node_summary)),
+            "links": 0 if link_summary is None else int(len(link_summary)),
+            "subcatchments": 0 if sub_summary is None else int(len(sub_summary)),
+        },
+        "deterministic_findings": list(findings),
+        "allowed_ai_actions": ["explain", "prioritise", "identify missing information", "propose review steps", "propose structured edits for engineer approval"],
+        "prohibited_ai_actions": ["claim compliance", "silently modify the model", "invent criteria", "certify design", "approve a preferred design", "convert missing values to zero"],
+    }
+
+
+def ai_review_findings(*, provider_name: str, api_key: str, model: str, review_context: Mapping[str, Any], user_request: str = "") -> str:
+    request = f"""Review the preliminary SWMM model using only the deterministic context below.
+Prioritise issues, explain likely engineering implications, identify missing criteria,
+and propose conservative next actions. Do not recalculate results or claim compliance.
+
+USER_REQUEST:
+{user_request or 'Provide a complete preliminary design review.'}
+
+DETERMINISTIC_CONTEXT:
+{json.dumps(review_context, ensure_ascii=False, default=str)}
+
+Return concise professional Markdown with these headings:
+1. Review summary
+2. Priority findings
+3. Modelling corrections for engineer consideration
+4. Design-criteria confirmations required
+5. Recommended path to scenario analysis
+"""
+    return _call_provider(provider_name, api_key, model, [{"role": "user", "content": request}], REVIEW_SYSTEM_PROMPT, max_tokens=3600)
+
+
+def apply_approved_changes(inp_text: str, findings: Sequence[Mapping[str, Any]], edited_values: Mapping[str, Any] | None = None) -> tuple[str, list[dict[str, Any]]]:
+    """Apply a deliberately limited set of approved, structured edits."""
+    preamble, sections = _split_sections(inp_text)
+    log: list[dict[str, Any]] = []
+    edited_values = dict(edited_values or {})
+
+    def update_named(section: str, object_id: str, token_index: int, value: Any, finding_id: str, parameter: str):
+        lines = sections.get(section, [])
+        changed = False
+        old = None
+        new_lines = []
+        for line in lines:
+            parsed = _data_tokens(line)
+            if parsed and parsed[0][0].casefold() == object_id.casefold() and len(parsed[0]) > token_index:
+                tokens, comment = parsed
+                old = tokens[token_index]
+                tokens[token_index] = str(value)
+                line = _replace_tokens(line, tokens, comment)
+                changed = True
+            new_lines.append(line)
+        sections[section] = new_lines
+        log.append({"finding_id": finding_id, "object_id": object_id, "parameter": parameter, "old_value": old, "new_value": value, "applied": changed})
+
+    for f in findings:
+        if str(f.get("engineer_decision", "")).lower() != "accept":
+            continue
+        fid = str(f.get("finding_id", ""))
+        parameter = str(f.get("proposed_parameter", ""))
+        value = edited_values.get(fid, f.get("proposed_value"))
+        oid = str(f.get("object_id", ""))
+        otype = str(f.get("object_type", "")).upper()
+        if value in (None, "") or not parameter:
+            log.append({"finding_id": fid, "object_id": oid, "parameter": parameter, "applied": False, "note": "No structured value supplied; retained as an accepted review action only."})
+            continue
+        if otype == "SUBCATCHMENT":
+            idx = {"area": 3, "imperviousness": 4, "width": 5, "slope": 6}.get(parameter)
+            if idx is not None:
+                update_named("SUBCATCHMENTS", oid, idx, value, fid, parameter)
+                continue
+        if otype == "MODEL" and parameter.upper() in {"REPORT_STEP", "WET_STEP", "ROUTING_STEP", "END_DATE", "END_TIME"}:
+            sections["OPTIONS"] = _set_option(sections.get("OPTIONS", []), parameter.upper(), str(value))
+            log.append({"finding_id": fid, "object_id": "MODEL", "parameter": parameter.upper(), "new_value": value, "applied": True})
+            continue
+        log.append({"finding_id": fid, "object_id": oid, "parameter": parameter, "new_value": value, "applied": False, "note": "Parameter is not yet supported by the controlled correction engine."})
+    return _join_sections(preamble, sections), log
+
+
+def review_manifest(*, original_name: str, reviewed_name: str, original_text: str, reviewed_text: str, findings: Sequence[Mapping[str, Any]], change_log: Sequence[Mapping[str, Any]], status: str) -> dict[str, Any]:
+    return {
+        "workflow": "Rev23 Preliminary Design Assistant",
+        "created_at": datetime.now().isoformat(timespec="seconds"),
+        "original_model": original_name,
+        "reviewed_model": reviewed_name,
+        "original_sha256": hashlib.sha256(original_text.encode("utf-8")).hexdigest(),
+        "reviewed_sha256": hashlib.sha256(reviewed_text.encode("utf-8")).hexdigest(),
+        "review_status": status,
+        "finding_counts": pd.Series([f.get("severity", "") for f in findings]).value_counts().to_dict() if findings else {},
+        "decision_counts": pd.Series([f.get("engineer_decision", "") for f in findings]).value_counts().to_dict() if findings else {},
+        "change_log": list(change_log),
+    }

report_engine.py

@@ -0,0 +1,1417 @@
+"""Municipal stormwater report generator for the SWMM6 GIS Space.
+
+Creates an editable DOCX report and a ZIP package of supporting CSV/JSON data
+from the deterministic simulation results already held in Streamlit session state.
+"""
+from __future__ import annotations
+
+import io
+import json
+import re
+import sqlite3
+import tempfile
+import zipfile
+from dataclasses import dataclass, asdict
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Mapping
+
+import pandas as pd
+from docx import Document
+from docx.enum.section import WD_ORIENT, WD_SECTION
+from docx.enum.text import WD_ALIGN_PARAGRAPH
+from docx.enum.table import WD_CELL_VERTICAL_ALIGNMENT, WD_TABLE_ALIGNMENT
+from docx.shared import Inches, Pt, RGBColor
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+
+from calgary_rules import (
+    CalgaryCriteria, apply_storage_classification, build_llm_report_context,
+    build_minor_system_capacity_table, build_overland_compliance_table,
+    criteria_register, infer_design_event,
+)
+
+
+@dataclass
+class ReportCriteria:
+    node_depth_ratio: float = 0.80
+    minimum_freeboard: float = 0.50
+    conduit_depth_ratio: float = 0.80
+    velocity_threshold: float = 4.00
+    continuity_review: float = 0.50
+    continuity_warning: float = 1.00
+    suppress_empty_sections: bool = True
+    major_link_ids: tuple[str, ...] = ()
+    area_classification: dict[str, str] | None = None
+    calgary_enabled: bool = True
+    minor_release_rate_lps_ha: float | None = None
+    trap_low_max_depth_m: float = 0.50
+    entrance_grade_margin_m: float = 0.30
+    conduit_capacity_warning_ratio: float = 0.95
+    special_link_limits: dict[str, float] | None = None
+    storage_classification: dict[str, str] | None = None
+    outfall_classification: dict[str, str] | None = None
+    checklist_overrides: dict[str, str] | None = None
+    drawing_inventory: tuple[str, ...] = ()
+    applicable_reports: tuple[str, ...] = ()
+
+
+@dataclass
+class ReportMetadata:
+    project_name: str = "SWMM Project"
+    client: str = "Not provided"
+    consultant: str = "Not provided"
+    consultant_file_no: str = "Not provided"
+    subdivision_no: str = "Not provided"
+    outline_plan_no: str = "Not provided"
+    development_permit_no: str = "Not provided"
+    design_storm: str = "Model design event"
+    prepared_by: str = "Not provided"
+    checked_by: str = "Not provided"
+    report_date: str = ""
+    municipality: str = "City of Calgary-style"
+    contact_name: str = "Not provided"
+    contact_email: str = "Not provided"
+    legal_description: str = "Not provided"
+    submission_status: str = "Preliminary"
+    construction_drawing_no: str = "Not provided"
+    development_agreement_no: str = "Not provided"
+
+    def __post_init__(self) -> None:
+        if not self.report_date:
+            self.report_date = datetime.now().strftime("%B %d, %Y")
+
+
+def _safe_name(value: str) -> str:
+    value = re.sub(r"[^A-Za-z0-9._-]+", "_", str(value).strip())
+    return value.strip("_") or "SWMM_Project"
+
+
+def _set_cell_text(cell, value: Any, bold: bool = False, size: float = 8.0) -> None:
+    cell.text = ""
+    cell.vertical_alignment = WD_CELL_VERTICAL_ALIGNMENT.CENTER
+    p = cell.paragraphs[0]
+    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    p.paragraph_format.space_after = Pt(0)
+    run = p.add_run("" if value is None else str(value))
+    run.bold = bold
+    run.font.size = Pt(size)
+    run.font.name = "Arial"
+
+
+def _repeat_table_header(row) -> None:
+    tr_pr = row._tr.get_or_add_trPr()
+    tbl_header = OxmlElement("w:tblHeader")
+    tbl_header.set(qn("w:val"), "true")
+    tr_pr.append(tbl_header)
+
+
+def _set_cell_shading(cell, fill: str = "D9EAD3") -> None:
+    tc_pr = cell._tc.get_or_add_tcPr()
+    shd = tc_pr.find(qn("w:shd"))
+    if shd is None:
+        shd = OxmlElement("w:shd")
+        tc_pr.append(shd)
+    shd.set(qn("w:fill"), fill)
+
+
+def _set_landscape(section) -> None:
+    section.orientation = WD_ORIENT.LANDSCAPE
+    section.page_width, section.page_height = section.page_height, section.page_width
+    section.top_margin = Inches(0.45)
+    section.bottom_margin = Inches(0.45)
+    section.left_margin = Inches(0.45)
+    section.right_margin = Inches(0.45)
+
+
+def _format_value(value: Any) -> str:
+    if value is None or (isinstance(value, float) and pd.isna(value)):
+        return ""
+    if isinstance(value, float):
+        if abs(value) >= 1000:
+            return f"{value:,.2f}"
+        if abs(value) >= 10:
+            return f"{value:,.3f}".rstrip("0").rstrip(".")
+        return f"{value:,.4f}".rstrip("0").rstrip(".")
+    return str(value)
+
+
+def _add_df_table(
+    doc: Document,
+    title: str,
+    df: pd.DataFrame,
+    max_rows: int = 250,
+    *,
+    font_size: float = 7.4,
+    landscape: bool = False,
+) -> None:
+    if landscape:
+        section = doc.add_section(WD_SECTION.NEW_PAGE)
+        _set_landscape(section)
+    doc.add_heading(title, level=3)
+    if df is None or df.empty:
+        doc.add_paragraph("No applicable model records were identified.")
+        return
+
+    shown = df.head(max_rows).copy()
+    table = doc.add_table(rows=1, cols=len(shown.columns))
+    table.style = "Table Grid"
+    table.alignment = WD_TABLE_ALIGNMENT.CENTER
+    table.autofit = True
+    _repeat_table_header(table.rows[0])
+    for i, col in enumerate(shown.columns):
+        _set_cell_text(table.rows[0].cells[i], col, bold=True, size=max(6.3, font_size - 0.2))
+        _set_cell_shading(table.rows[0].cells[i])
+    for _, row in shown.iterrows():
+        cells = table.add_row().cells
+        for i, col in enumerate(shown.columns):
+            _set_cell_text(cells[i], _format_value(row[col]), size=font_size)
+    if len(df) > max_rows:
+        doc.add_paragraph(f"Table truncated in the report at {max_rows:,} rows. Complete data are included in the ZIP package.")
+
+
+@dataclass(frozen=True)
+class UnitContext:
+    flow_units: str
+    system: str
+    flow: str
+    length: str
+    area: str
+    velocity: str
+    rainfall: str
+    storage: str
+
+
+def _unit_context(flow_units: str) -> UnitContext:
+    u = str(flow_units or "").upper()
+    if u in {"CFS", "GPM", "MGD", "IMGD", "AFD"}:
+        flow = {"CFS": "cfs", "GPM": "gpm", "MGD": "MGD", "IMGD": "IMGD", "AFD": "ac-ft/day"}.get(u, u)
+        return UnitContext(u, "US Customary", flow, "ft", "ac", "ft/s", "in/hr", "ft³")
+    flow = {"CMS": "m³/s", "LPS": "L/s", "MLD": "ML/day"}.get(u, u or "model units")
+    return UnitContext(u or "UNKNOWN", "SI", flow, "m", "ha", "m/s", "mm/hr", "m³")
+
+
+def _rename_native_columns(df: pd.DataFrame, units: UnitContext) -> pd.DataFrame:
+    if df is None:
+        return pd.DataFrame()
+    out = df.copy()
+    replacements = {
+        "Area (ha)": f"Area ({units.area})",
+        "Width (m)": f"Width ({units.length})",
+        "Length (m)": f"Length ({units.length})",
+        "Diameter (m)": f"Diameter ({units.length})",
+        "Geom1 (m)": f"Geom1 ({units.length})",
+        "Inlet Offset (m)": f"Inlet Offset ({units.length})",
+        "Outlet Offset (m)": f"Outlet Offset ({units.length})",
+        "Invert (m)": f"Invert ({units.length})",
+        "Full Depth (m)": f"Full Depth ({units.length})",
+        "Peak Depth (m)": f"Peak Depth ({units.length})",
+        "Maximum HGL (m)": f"Maximum HGL ({units.length})",
+        "Ground/Rim (m)": f"Ground/Rim ({units.length})",
+        "Freeboard (m)": f"Freeboard ({units.length})",
+        "Peak Flow (m³/s)": f"Peak Flow ({units.flow})",
+        "Peak Runoff (m³/s)": f"Peak Runoff ({units.flow})",
+        "Peak Flooding (m³/s)": f"Peak Flooding ({units.flow})",
+        "Peak Inflow (m³/s)": f"Peak Inflow ({units.flow})",
+        "Peak Velocity (m/s)": f"Peak Velocity ({units.velocity})",
+        "Peak Rainfall (mm/h)": f"Peak Rainfall ({units.rainfall})",
+    }
+    if units.flow_units == "CFS":
+        replacements["Total Runoff (m³)"] = "Runoff Volume (ft³)"
+        replacements["Total Rainfall Depth"] = "Total Rainfall (in)"
+        replacements["Runoff Depth"] = "Runoff Depth (in)"
+    elif units.flow_units == "CMS":
+        replacements["Total Runoff (m³)"] = "Runoff Volume (m³)"
+        replacements["Total Rainfall Depth"] = "Total Rainfall (mm)"
+        replacements["Runoff Depth"] = "Runoff Depth (mm)"
+    elif units.flow_units == "LPS":
+        replacements["Total Runoff (m³)"] = "Runoff Volume (L)"
+        replacements["Total Rainfall Depth"] = "Total Rainfall (mm)"
+        replacements["Runoff Depth"] = "Runoff Depth (mm)"
+    else:
+        replacements["Total Runoff (m³)"] = f"Integrated Runoff ({units.flow}-s)"
+    return out.rename(columns={k: v for k, v in replacements.items() if k in out.columns})
+
+def _inp_options(sections: dict[str, list[list[str]]]) -> dict[str, str]:
+    result: dict[str, str] = {}
+    for row in sections.get("OPTIONS", []):
+        if len(row) >= 2:
+            result[row[0].upper()] = " ".join(row[1:])
+    return result
+
+
+def _subcatchment_model_table(sections: dict[str, list[list[str]]], sub_summary: pd.DataFrame) -> pd.DataFrame:
+    attrs: dict[str, dict[str, Any]] = {}
+    for row in sections.get("SUBCATCHMENTS", []):
+        if len(row) >= 7:
+            try:
+                attrs[row[0]] = {
+                    "Rain Gage": row[1], "Outlet": row[2], "Area (ha)": float(row[3]),
+                    "Impervious (%)": float(row[4]), "Width (m)": float(row[5]), "Slope (%)": float(row[6]),
+                }
+            except ValueError:
+                continue
+    for row in sections.get("SUBAREAS", []):
+        if len(row) >= 7 and row[0] in attrs:
+            try:
+                attrs[row[0]].update({
+                    "n Imperv.": float(row[1]), "n Perv.": float(row[2]),
+                    "Dstore Imperv.": float(row[3]), "Dstore Perv.": float(row[4]),
+                    "Zero Imperv. (%)": float(row[5]), "Routing": row[6],
+                })
+            except ValueError:
+                pass
+    model_df = pd.DataFrame([{"Sub ID": sid, **vals} for sid, vals in attrs.items()])
+    if model_df.empty:
+        return sub_summary.copy()
+    if sub_summary is not None and not sub_summary.empty:
+        # Model input values are authoritative for shared fields; avoid duplicate area/impervious columns.
+        result_df = sub_summary.drop(columns=[c for c in ["Area (ha)", "% Impervious"] if c in sub_summary.columns], errors="ignore")
+        return model_df.merge(result_df, on="Sub ID", how="left")
+    return model_df
+
+
+def _link_model_table(sections: dict[str, list[list[str]]], link_summary: pd.DataFrame) -> pd.DataFrame:
+    records: dict[str, dict[str, Any]] = {}
+    for section, link_type in (("CONDUITS", "conduit"), ("PUMPS", "pump"), ("ORIFICES", "orifice"), ("WEIRS", "weir"), ("OUTLETS", "outlet")):
+        for row in sections.get(section, []):
+            if len(row) < 3:
+                continue
+            rec = {"Link ID": row[0], "Model Type": link_type, "From Node": row[1], "To Node": row[2]}
+            if section == "CONDUITS" and len(row) >= 9:
+                try:
+                    rec.update({
+                        "Length (m)": float(row[3]), "Manning n": float(row[4]),
+                        "Inlet Offset (m)": float(row[5]), "Outlet Offset (m)": float(row[6]),
+                        "Initial Flow": float(row[7]), "Maximum Flow": float(row[8]),
+                    })
+                except ValueError:
+                    pass
+            records[row[0]] = rec
+    for row in sections.get("XSECTIONS", []):
+        if len(row) >= 3 and row[0] in records:
+            records[row[0]]["Shape"] = row[1]
+            try:
+                records[row[0]]["Geom1 (m)"] = float(row[2])
+                if len(row) > 3: records[row[0]]["Geom2"] = float(row[3])
+                if len(row) > 4: records[row[0]]["Geom3"] = float(row[4])
+                if len(row) > 5: records[row[0]]["Geom4"] = float(row[5])
+                if len(row) > 6: records[row[0]]["Barrels"] = int(float(row[6]))
+            except ValueError:
+                pass
+    model_df = pd.DataFrame(records.values())
+    if model_df.empty:
+        return link_summary.copy()
+    if link_summary is not None and not link_summary.empty:
+        drop_overlap = [c for c in ["From Node", "To Node", "Length (m)"] if c in link_summary.columns]
+        result_df = link_summary.drop(columns=drop_overlap, errors="ignore")
+        return model_df.merge(result_df, on="Link ID", how="left")
+    return model_df
+
+
+def _node_hgl_table(node_summary: pd.DataFrame) -> pd.DataFrame:
+    if node_summary is None or node_summary.empty:
+        return pd.DataFrame()
+    df = node_summary.copy()
+    df["Maximum HGL (m)"] = df.get("Invert (m)", 0) + df.get("Peak Depth (m)", 0)
+    df["Ground/Rim (m)"] = df.get("Invert (m)", 0) + df.get("Full Depth (m)", 0)
+    df["Freeboard (m)"] = df["Ground/Rim (m)"] - df["Maximum HGL (m)"]
+    cols = ["Node ID", "Type", "Invert (m)", "Ground/Rim (m)", "Maximum HGL (m)", "Peak Depth (m)", "Freeboard (m)", "Peak Flooding (m³/s)", "Status"]
+    return df[[c for c in cols if c in df.columns]]
+
+
+
+def _parse_time_seconds(value: str | None) -> float:
+    """Parse SWMM HH:MM:SS or numeric-second time values."""
+    if value is None:
+        return 0.0
+    text = str(value).strip()
+    if not text:
+        return 0.0
+    try:
+        return float(text)
+    except ValueError:
+        pass
+    parts = text.split(":")
+    try:
+        nums = [float(x) for x in parts]
+    except ValueError:
+        return 0.0
+    if len(nums) == 3:
+        return nums[0] * 3600.0 + nums[1] * 60.0 + nums[2]
+    if len(nums) == 2:
+        return nums[0] * 60.0 + nums[1]
+    return 0.0
+
+
+def _enhance_subcatchment_results(df: pd.DataFrame, units: UnitContext, report_step_s: float) -> pd.DataFrame:
+    """Add defensible event coefficients and integrated runoff volumes in native units."""
+    if df is None or df.empty:
+        return pd.DataFrame()
+    out = df.copy()
+    out = out.loc[:, ~out.columns.duplicated()].copy()
+    area_col = next((c for c in out.columns if c.startswith("Area (")), None)
+    q_col = next((c for c in out.columns if c.startswith("Peak Runoff (")), None)
+    rain_col = next((c for c in out.columns if c.startswith("Peak Rainfall (")), None)
+    sum_col = next((c for c in out.columns if c.startswith("Runoff Sum (")), None)
+
+    if area_col and q_col and rain_col:
+        area = pd.to_numeric(out[area_col], errors="coerce")
+        q = pd.to_numeric(out[q_col], errors="coerce")
+        intensity = pd.to_numeric(out[rain_col], errors="coerce")
+        denom = pd.Series(float("nan"), index=out.index)
+        if units.flow_units == "CFS":
+            denom = 1.008 * intensity * area  # Q(cfs)=1.008*C*i(in/hr)*A(ac)
+        elif units.flow_units == "CMS":
+            denom = 0.0027777778 * intensity * area  # Q(m3/s)=0.0027778*C*i(mm/hr)*A(ha)
+        elif units.flow_units == "LPS":
+            denom = 2.7777778 * intensity * area  # Q(L/s)=2.7778*C*i(mm/hr)*A(ha)
+        coeff = q / denom.where(denom > 0)
+        out["Peak-Flow Runoff Coefficient"] = coeff.where((coeff >= 0) & (coeff <= 1.5))
+        out.drop(columns=["Runoff Coefficient"], errors="ignore", inplace=True)
+
+    if sum_col and report_step_s > 0:
+        runoff_sum = pd.to_numeric(out[sum_col], errors="coerce").fillna(0.0)
+        if units.flow_units == "CFS":
+            volume_ft3 = runoff_sum * report_step_s
+            out["Runoff Volume (ft³)"] = volume_ft3
+            out["Runoff Volume (ac-ft)"] = volume_ft3 / 43560.0
+            out["Runoff Volume (MG)"] = volume_ft3 * 7.48051948 / 1_000_000.0
+            if area_col:
+                area = pd.to_numeric(out[area_col], errors="coerce")
+                out["Runoff Depth (in)"] = (volume_ft3 / (area * 43560.0)) * 12.0
+        elif units.flow_units == "CMS":
+            volume_m3 = runoff_sum * report_step_s
+            out["Runoff Volume (m³)"] = volume_m3
+            if area_col:
+                area = pd.to_numeric(out[area_col], errors="coerce")
+                out["Runoff Depth (mm)"] = volume_m3 / (area * 10.0)
+        elif units.flow_units == "LPS":
+            volume_m3 = runoff_sum * report_step_s / 1000.0
+            out["Runoff Volume (m³)"] = volume_m3
+            if area_col:
+                area = pd.to_numeric(out[area_col], errors="coerce")
+                out["Runoff Depth (mm)"] = volume_m3 / (area * 10.0)
+        elif units.flow_units in {"GPM", "MGD", "IMGD", "MLD", "AFD"}:
+            out[f"Integrated Runoff ({units.flow}-s)"] = runoff_sum * report_step_s
+        out.drop(columns=[sum_col], errors="ignore", inplace=True)
+
+    # Add convenient secondary volume units when the application already supplied an integrated native volume.
+    if units.flow_units == "CFS" and "Runoff Volume (ft³)" in out.columns:
+        volume_ft3 = pd.to_numeric(out["Runoff Volume (ft³)"], errors="coerce")
+        out["Runoff Volume (ac-ft)"] = volume_ft3 / 43560.0
+        out["Runoff Volume (MG)"] = volume_ft3 * 7.48051948 / 1_000_000.0
+    elif units.flow_units == "LPS" and "Runoff Volume (L)" in out.columns:
+        out["Runoff Volume (m³)"] = pd.to_numeric(out["Runoff Volume (L)"], errors="coerce") / 1000.0
+    return out
+
+
+def _populate_outfall_flows(node_df: pd.DataFrame, link_df: pd.DataFrame, units: UnitContext) -> pd.DataFrame:
+    """Populate outfall peak inflow from incoming links when node output is absent or zero."""
+    if node_df is None or node_df.empty:
+        return pd.DataFrame()
+    out = node_df.copy()
+    inflow_col = f"Peak Inflow ({units.flow})"
+    flow_col = f"Peak Flow ({units.flow})"
+    if inflow_col not in out.columns:
+        out[inflow_col] = 0.0
+    if link_df is None or link_df.empty or "To Node" not in link_df or flow_col not in link_df:
+        return out
+    incoming = link_df.groupby("To Node")[flow_col].max()
+    mask = out.get("Type", "").astype(str).str.lower().eq("outfall")
+    for idx in out.index[mask]:
+        node_id = out.at[idx, "Node ID"]
+        current = pd.to_numeric(pd.Series([out.at[idx, inflow_col]]), errors="coerce").iloc[0]
+        fallback = incoming.get(node_id)
+        if (pd.isna(current) or float(current) <= 0.0) and fallback is not None and not pd.isna(fallback):
+            out.at[idx, inflow_col] = float(fallback)
+    return out
+
+
+def _split_link_appendix(link_table: pd.DataFrame, units: UnitContext) -> tuple[pd.DataFrame, pd.DataFrame, pd.DataFrame]:
+    geom_cols = ["Link ID", "From Node", "To Node", "Model Type", "Shape", f"Length ({units.length})",
+                 f"Geom1 ({units.length})", "Geom2", "Geom3", "Geom4", "Barrels"]
+    params_cols = ["Link ID", "Manning n", f"Inlet Offset ({units.length})", f"Outlet Offset ({units.length})",
+                   "Initial Flow", "Maximum Flow"]
+    results_cols = ["Link ID", f"Peak Flow ({units.flow})", f"Peak Depth ({units.length})", "Depth Ratio",
+                    f"Peak Velocity ({units.velocity})", "Status"]
+    return tuple(link_table[[c for c in cols if c in link_table.columns]].copy() for cols in (geom_cols, params_cols, results_cols))
+
+
+def _split_subcatchment_appendix(sub_table: pd.DataFrame, units: UnitContext) -> tuple[pd.DataFrame, pd.DataFrame]:
+    model_cols = ["Sub ID", "Rain Gage", "Outlet", f"Area ({units.area})", "Impervious (%)", f"Width ({units.length})",
+                  "Slope (%)", "n Imperv.", "n Perv.", "Dstore Imperv.", "Dstore Perv.", "Zero Imperv. (%)", "Routing", "Connected To"]
+    result_cols = ["Sub ID", f"Peak Runoff ({units.flow})", "Peak-Flow Runoff Coefficient",
+                   f"Peak Rainfall ({units.rainfall})", "Runoff Volume (ft³)", "Runoff Volume (ac-ft)",
+                   "Runoff Volume (MG)", "Runoff Volume (m³)", "Runoff Depth (in)", "Runoff Depth (mm)"]
+    return (sub_table[[c for c in model_cols if c in sub_table.columns]].copy(),
+            sub_table[[c for c in result_cols if c in sub_table.columns]].copy())
+
+
+
+def _read_sqlite_tables(result_db_bytes: bytes | None, table_names: list[str]) -> dict[str, pd.DataFrame]:
+    """Read selected result tables from the in-memory SQLite export package."""
+    if not result_db_bytes:
+        return {}
+    tables: dict[str, pd.DataFrame] = {}
+    tmp_name = None
+    try:
+        with tempfile.NamedTemporaryFile(suffix=".sqlite", delete=False) as tmp:
+            tmp.write(result_db_bytes)
+            tmp_name = tmp.name
+        with sqlite3.connect(tmp_name) as con:
+            available = {r[0] for r in con.execute("SELECT name FROM sqlite_master WHERE type='table'")}
+            for name in table_names:
+                if name in available:
+                    tables[name] = pd.read_sql_query(f'SELECT * FROM "{name}"', con)
+    except Exception:
+        return tables
+    finally:
+        if tmp_name:
+            try:
+                Path(tmp_name).unlink(missing_ok=True)
+            except Exception:
+                pass
+    return tables
+
+
+def _control_table(sections: dict[str, list[list[str]]], link_table: pd.DataFrame, units: UnitContext) -> pd.DataFrame:
+    """Create a control-specific schedule for orifices, weirs and outlets."""
+    peak_col = f"Peak Flow ({units.flow})"
+    peak_lookup = {}
+    if link_table is not None and not link_table.empty and peak_col in link_table.columns:
+        peak_lookup = link_table.set_index("Link ID")[peak_col].to_dict()
+    rows: list[dict[str, Any]] = []
+    for row in sections.get("ORIFICES", []):
+        if len(row) >= 6:
+            rows.append({
+                "Control ID": row[0], "Control Type": "Orifice", "From Node": row[1], "To Node": row[2],
+                "Subtype": row[3], f"Offset ({units.length})": _num(row[4]), "Discharge Coefficient": _num(row[5]),
+                "Flap Gate": row[6] if len(row) > 6 else "", "Opening/Closing Time": _num(row[7]) if len(row) > 7 else None,
+                peak_col: peak_lookup.get(row[0]),
+            })
+    for row in sections.get("WEIRS", []):
+        if len(row) >= 6:
+            rows.append({
+                "Control ID": row[0], "Control Type": "Weir", "From Node": row[1], "To Node": row[2],
+                "Subtype": row[3], f"Crest Height ({units.length})": _num(row[4]), "Discharge Coefficient": _num(row[5]),
+                "Flap Gate": row[6] if len(row) > 6 else "", "End Contractions": _num(row[7]) if len(row) > 7 else None,
+                "End Coefficient": _num(row[8]) if len(row) > 8 else None, "Surcharge Allowed": row[9] if len(row) > 9 else "",
+                peak_col: peak_lookup.get(row[0]),
+            })
+    for row in sections.get("OUTLETS", []):
+        if len(row) >= 6:
+            rows.append({
+                "Control ID": row[0], "Control Type": "Outlet", "From Node": row[1], "To Node": row[2],
+                f"Offset ({units.length})": _num(row[3]), "Rating Type": row[4], "Rating Curve/Parameters": " ".join(row[5:]),
+                peak_col: peak_lookup.get(row[0]),
+            })
+    return pd.DataFrame(rows)
+
+
+def _num(value: Any) -> float | None:
+    try:
+        return float(value)
+    except Exception:
+        return None
+
+
+def _control_reconciliation(control_df: pd.DataFrame, link_table: pd.DataFrame, units: UnitContext) -> pd.DataFrame:
+    """Compare parallel control peaks with the downstream conveyance peak as a screening check."""
+    peak_col = f"Peak Flow ({units.flow})"
+    if control_df is None or control_df.empty or link_table is None or link_table.empty or peak_col not in link_table.columns:
+        return pd.DataFrame()
+    rows = []
+    for to_node, grp in control_df.groupby("To Node", dropna=False):
+        control_sum = pd.to_numeric(grp[peak_col], errors="coerce").fillna(0).sum()
+        downstream = link_table[(link_table.get("From Node") == to_node) & (link_table.get("Model Type", link_table.get("Type", "")).astype(str).str.lower() == "conduit")]
+        downstream_peak = pd.to_numeric(downstream[peak_col], errors="coerce").max() if not downstream.empty else float("nan")
+        diff = downstream_peak - control_sum if pd.notna(downstream_peak) else float("nan")
+        pct = abs(diff) / max(abs(downstream_peak), 1e-12) * 100 if pd.notna(diff) else float("nan")
+        rows.append({
+            "Receiving Node": to_node, "Controls": ", ".join(grp["Control ID"].astype(str)),
+            f"Sum of Control Peaks ({units.flow})": control_sum,
+            "Downstream Link": ", ".join(downstream["Link ID"].astype(str)) if not downstream.empty else "Not identified",
+            f"Downstream Peak ({units.flow})": downstream_peak,
+            f"Difference ({units.flow})": diff, "Difference (%)": pct,
+            "Check": "Consistent" if pd.notna(pct) and pct <= 2.0 else "Review timing / routing",
+        })
+    return pd.DataFrame(rows)
+
+
+def _storage_table(sections: dict[str, list[list[str]]], node_report: pd.DataFrame, db_tables: dict[str, pd.DataFrame], units: UnitContext) -> pd.DataFrame:
+    """Create storage-specific input/result table using node time series when available."""
+    node_ts = db_tables.get("node_timeseries", pd.DataFrame())
+    node_lookup = node_report.set_index("Node ID").to_dict("index") if node_report is not None and not node_report.empty else {}
+    rows = []
+    for r in sections.get("STORAGE", []):
+        if len(r) < 5:
+            continue
+        sid = r[0]; invert = _num(r[1]); max_depth = _num(r[2]); init_depth = _num(r[3]); shape = r[4]
+        rec: dict[str, Any] = {"Storage ID": sid, f"Invert ({units.length})": invert, f"Maximum Depth ({units.length})": max_depth,
+                               f"Initial Depth ({units.length})": init_depth, "Shape/Curve": shape,
+                               "Shape Parameters": " ".join(r[5:])}
+        nrec = node_lookup.get(sid, {})
+        rec[f"Reported Peak Depth ({units.length})"] = nrec.get(f"Peak Depth ({units.length})")
+        rec[f"Maximum HGL ({units.length})"] = nrec.get(f"Invert ({units.length})", invert) + (nrec.get(f"Peak Depth ({units.length})") or 0) if invert is not None else None
+        if not node_ts.empty and "node_id" in node_ts.columns:
+            g = node_ts[node_ts["node_id"].astype(str) == sid].copy()
+            if not g.empty:
+                for src, label in (("depth", f"Time-Series Peak Depth ({units.length})"), ("volume", f"Maximum Stored Volume ({units.storage})"),
+                                   ("inflow", f"Peak Inflow ({units.flow})"), ("outflow", f"Peak Outflow ({units.flow})")):
+                    if src in g:
+                        rec[label] = pd.to_numeric(g[src], errors="coerce").max()
+                if "volume" in g and "timestamp" in g:
+                    vals = pd.to_numeric(g["volume"], errors="coerce")
+                    if vals.notna().any(): rec["Time of Maximum Storage"] = g.loc[vals.idxmax(), "timestamp"]
+        peak_depth = rec.get(f"Time-Series Peak Depth ({units.length})", rec.get(f"Reported Peak Depth ({units.length})"))
+        rec["Depth Utilization (%)"] = 100 * float(peak_depth) / float(max_depth) if peak_depth is not None and max_depth and max_depth > 0 else None
+        rec["Status"] = "Review zero storage response" if (peak_depth is not None and float(peak_depth) == 0 and (rec.get(f"Peak Outflow ({units.flow})") or 0) > 0) else "OK"
+        rows.append(rec)
+    return pd.DataFrame(rows)
+
+
+def _area_classification(sub_table: pd.DataFrame, units: UnitContext, overrides: dict[str, str] | None = None) -> pd.DataFrame:
+    """Separate likely proposed, pre-development and external/comparison catchments by naming convention."""
+    if sub_table is None or sub_table.empty:
+        return pd.DataFrame()
+    area_col = f"Area ({units.area})"
+    if area_col not in sub_table:
+        return pd.DataFrame()
+    overrides = {str(k): str(v) for k, v in (overrides or {}).items()}
+    def classify(name: str) -> str:
+        if str(name) in overrides:
+            return overrides[str(name)]
+        n = str(name).lower().replace("_", " ")
+        if any(k in n for k in ("predevelop", "pre develop", "pre-development", "existing", "predev")):
+            return "Pre-development / comparison"
+        if any(k in n for k in ("external", "offsite", "off-site", "upstream")):
+            return "External area"
+        return "Proposed / modelled development"
+    d = sub_table[["Sub ID", area_col]].copy(); d["Area Category"] = d["Sub ID"].map(classify)
+    return d.groupby("Area Category", as_index=False)[area_col].sum()
+
+
+def _critical_elements(node_df: pd.DataFrame, link_df: pd.DataFrame, units: UnitContext, criteria: ReportCriteria) -> tuple[pd.DataFrame, pd.DataFrame]:
+    node_rows = []
+    if node_df is not None and not node_df.empty:
+        for _, r in node_df.iterrows():
+            node_type = str(r.get("Type", "")).lower()
+            # Storage facilities use Calgary storage-classification criteria and are
+            # intentionally excluded from generic junction freeboard screening.
+            if node_type in {"outfall", "storage"}:
+                continue
+            ratio = pd.to_numeric(pd.Series([r.get("Depth Ratio")]), errors="coerce").iloc[0]
+            free = pd.to_numeric(pd.Series([r.get(f"Freeboard ({units.length})")]), errors="coerce").iloc[0]
+            flooding = pd.to_numeric(pd.Series([r.get(f"Peak Flooding ({units.flow})")]), errors="coerce").fillna(0).iloc[0]
+            issues = []
+            if pd.notna(ratio) and ratio >= criteria.node_depth_ratio:
+                issues.append(f"depth ratio ≥ {criteria.node_depth_ratio:.2f}")
+            if pd.notna(free) and free <= criteria.minimum_freeboard:
+                issues.append(f"freeboard ≤ {criteria.minimum_freeboard:g} {units.length}")
+            if flooding > 0:
+                issues.append("flooding reported")
+            if issues:
+                node_rows.append({"Node ID": r.get("Node ID"), "Type": r.get("Type"), "Depth Ratio": ratio,
+                                  f"Freeboard ({units.length})": free, f"Peak Flooding ({units.flow})": flooding,
+                                  "Review Issue": "; ".join(issues)})
+    link_rows = []
+    if link_df is not None and not link_df.empty:
+        vel_col = f"Peak Velocity ({units.velocity})"
+        for _, r in link_df.iterrows():
+            if str(r.get("Type", r.get("Model Type", ""))).lower() not in ("conduit", ""):
+                continue
+            ratio = pd.to_numeric(pd.Series([r.get("Depth Ratio")]), errors="coerce").iloc[0]
+            vel = pd.to_numeric(pd.Series([r.get(vel_col)]), errors="coerce").iloc[0]
+            issues = []
+            if pd.notna(vel) and vel >= criteria.velocity_threshold:
+                issues.append(f"velocity ≥ {criteria.velocity_threshold:g} {units.velocity}")
+            if pd.notna(ratio) and ratio >= criteria.conduit_depth_ratio:
+                issues.append(f"depth ratio ≥ {criteria.conduit_depth_ratio:.2f}")
+            if issues:
+                link_rows.append({"Link ID": r.get("Link ID"), "From Node": r.get("From Node"), "To Node": r.get("To Node"),
+                                  f"Peak Flow ({units.flow})": r.get(f"Peak Flow ({units.flow})"), vel_col: vel,
+                                  "Depth Ratio": ratio, "Review Issue": "; ".join(issues)})
+    return pd.DataFrame(node_rows), pd.DataFrame(link_rows)
+
+def _summary_findings(node_df: pd.DataFrame, link_df: pd.DataFrame, sub_df: pd.DataFrame, metadata: dict[str, Any], units: UnitContext, options: dict[str, str], criteria: ReportCriteria) -> list[str]:
+    findings: list[str] = []
+    for label, key in (("Runoff quantity continuity error", "runoff_error"), ("Flow-routing continuity error", "flow_error"), ("Water-quality continuity error", "quality_error")):
+        val = metadata.get(key)
+        if val is not None:
+            try:
+                v = float(val); findings.append(f"{label}: {v:.3f}%.")
+                if key == "flow_error" and abs(v) > criteria.continuity_warning:
+                    findings.append(f"⚠️ Flow-routing continuity error exceeds the {criteria.continuity_warning:g}% warning threshold and should be reviewed.")
+                elif key == "flow_error" and abs(v) > criteria.continuity_review:
+                    findings.append(f"Flow-routing continuity error exceeds the {criteria.continuity_review:g}% review threshold.")
+            except Exception: findings.append(f"{label}: {val}.")
+    if node_df is not None and not node_df.empty:
+        flooded_col = next((c for c in node_df.columns if c.startswith('Peak Flooding (')), None)
+        flooded = int((pd.to_numeric(node_df[flooded_col], errors='coerce').fillna(0) > 0).sum()) if flooded_col else 0
+        findings.append(f"Flooded nodes identified: {flooded}.")
+        junction_nodes = node_df[node_df.get('Type', '').astype(str).str.lower().isin(['junction', 'divider'])].copy()
+        if 'Depth Ratio' in junction_nodes and not junction_nodes.empty:
+            ratios = pd.to_numeric(junction_nodes['Depth Ratio'], errors='coerce')
+            if ratios.notna().any():
+                i = ratios.idxmax(); findings.append(f"Maximum junction depth ratio: {ratios.loc[i]:.3f} at {junction_nodes.loc[i, 'Node ID']}.")
+                free_col = f"Freeboard ({units.length})"
+                if ratios.loc[i] >= criteria.node_depth_ratio and free_col in junction_nodes:
+                    findings.append(f"{junction_nodes.loc[i, 'Node ID']} has {_format_value(junction_nodes.loc[i, free_col])} {units.length} of modelled rim clearance and should be reviewed.")
+        storage_nodes = node_df[node_df.get('Type', '').astype(str).str.lower().eq('storage')].copy()
+        if 'Depth Ratio' in storage_nodes and not storage_nodes.empty:
+            ratios = pd.to_numeric(storage_nodes['Depth Ratio'], errors='coerce')
+            if ratios.notna().any():
+                i = ratios.idxmax(); findings.append(f"Maximum storage depth utilization ratio: {ratios.loc[i]:.3f} at {storage_nodes.loc[i, 'Node ID']}; assess using the applicable storage classification and ponding-depth criterion.")
+    conduits = link_df.copy() if link_df is not None else pd.DataFrame()
+    if not conduits.empty and 'Type' in conduits:
+        conduits = conduits[conduits['Type'].astype(str).str.lower().eq('conduit')]
+    if not conduits.empty:
+        if "Depth Ratio" in conduits:
+            ratios = pd.to_numeric(conduits["Depth Ratio"], errors="coerce")
+            if ratios.notna().any():
+                i=ratios.idxmax(); findings.append(f"Maximum conduit depth ratio: {ratios.loc[i]:.3f} at {conduits.loc[i, 'Link ID']}.")
+        vcol=f"Peak Velocity ({units.velocity})"
+        if vcol in conduits:
+            vals=pd.to_numeric(conduits[vcol], errors='coerce')
+            if vals.notna().any():
+                i=vals.idxmax(); findings.append(f"Maximum conduit velocity: {vals.loc[i]:.3f} {units.velocity} at {conduits.loc[i, 'Link ID']}.")
+    if sub_df is not None and not sub_df.empty:
+        acol=next((c for c in sub_df.columns if c.startswith('Area (')), None)
+        if acol: findings.append(f"Total model-database subcatchment area: {pd.to_numeric(sub_df[acol], errors='coerce').sum():.3f} {units.area}.")
+    routing = options.get("FLOW_ROUTING", "").upper()
+    if routing == "KINWAVE":
+        findings.append("⚠️ Kinematic-wave routing does not fully represent backwater, pressurization, reverse flow, or complex surcharge interactions; HGL and surcharge conclusions should be interpreted accordingly.")
+    warnings = metadata.get("warnings") or []
+    if warnings: findings.append(f"Simulation warnings recorded: {len(warnings)}. Review the attached metadata and model report.")
+    return findings
+
+
+def _event_summary(sub_df: pd.DataFrame, metadata: dict[str, Any], options: dict[str, str], units: UnitContext) -> pd.DataFrame:
+    rain_total_col = next((c for c in sub_df.columns if c.startswith("Total Rainfall (")), None) if sub_df is not None else None
+    rain_peak_col = next((c for c in sub_df.columns if c.startswith("Peak Rainfall (")), None) if sub_df is not None else None
+    total_rain = pd.to_numeric(sub_df[rain_total_col], errors="coerce").max() if rain_total_col and not sub_df.empty else None
+    peak_rain = pd.to_numeric(sub_df[rain_peak_col], errors="coerce").max() if rain_peak_col and not sub_df.empty else None
+    start = metadata.get("start_time")
+    end = metadata.get("end_time")
+    duration = ""
+    try:
+        duration = str(pd.Timestamp(end) - pd.Timestamp(start)) if start and end else ""
+    except Exception:
+        pass
+    rows = [
+        {"Parameter": "Design event", "Value": metadata.get("design_storm", "Model design event")},
+        {"Parameter": "Simulation start", "Value": start or "Not identified"},
+        {"Parameter": "Simulation end", "Value": end or "Not identified"},
+        {"Parameter": "Simulation duration", "Value": duration or "Not identified"},
+        {"Parameter": "Rainfall / wet-weather timestep", "Value": options.get("WET_STEP", options.get("REPORT_STEP", "Not identified"))},
+        {"Parameter": "Reporting timestep", "Value": options.get("REPORT_STEP", "Not identified")},
+    ]
+    if total_rain is not None and pd.notna(total_rain): rows.append({"Parameter": "Total event precipitation", "Value": f"{_format_value(total_rain)} {'in' if units.system == 'US Customary' else 'mm'}"})
+    if peak_rain is not None and pd.notna(peak_rain):
+        wet_step = str(options.get("WET_STEP", options.get("REPORT_STEP", "")))
+        label = "Maximum rainfall-interval intensity"
+        if wet_step in {"0:05", "00:05", "0:05:00", "00:05:00", "5 min", "5 minutes"}:
+            label = "Maximum 5-minute rainfall intensity"
+        rows.append({"Parameter": label, "Value": f"{_format_value(peak_rain)} {units.rainfall}"})
+    return pd.DataFrame(rows)
+
+
+def _executive_summary(findings: list[str], critical_nodes: pd.DataFrame, critical_links: pd.DataFrame, units: UnitContext, criteria: ReportCriteria) -> list[str]:
+    lines = ["The simulation completed and the principal model results were screened using the project criteria listed in this report."]
+    if critical_nodes.empty:
+        lines.append(f"No junctions or dividers met the generic node screening criteria (depth ratio ≥ {criteria.node_depth_ratio:.2f}, rim clearance ≤ {criteria.minimum_freeboard:g} {units.length}, or flooding greater than zero). Storage facilities are assessed separately using their Calgary storage classification.")
+    else:
+        lines.append(f"{len(critical_nodes)} junction/divider node(s) met the generic node screening criteria; storage facilities are assessed separately using their Calgary storage classification.")
+    if critical_links.empty:
+        lines.append(f"No conduits met the critical-link screening criteria (depth ratio ≥ {criteria.conduit_depth_ratio:.2f} or velocity ≥ {criteria.velocity_threshold:g} {units.velocity}).")
+    else:
+        lines.append(f"{len(critical_links)} conduit(s) met the critical-link screening criteria, primarily due to velocity or depth utilization.")
+    warning_lines = [x for x in findings if "⚠️" in x]
+    if warning_lines:
+        lines.append("At least one numerical or modelling limitation requires review before the report is relied upon for design conclusions.")
+    return lines
+
+
+def _provided(value: Any) -> bool:
+    return bool(str(value or "").strip()) and str(value).strip().lower() not in {"not provided", "n/a", "none", "unknown"}
+
+def _build_swmr_checklist(metadata: ReportMetadata, criteria: ReportCriteria, *, has_model: bool, has_results: bool, has_storage: bool, has_controls: bool, has_overland: bool, has_outfalls: bool, has_conduits: bool) -> pd.DataFrame:
+    drawings = {x.strip().lower() for x in criteria.drawing_inventory}
+    reports = list(criteria.applicable_reports)
+    rows = []
+    def add(i, req, status, evidence, action, category):
+        override=(criteria.checklist_overrides or {}).get(i)
+        rows.append({"Item":i,"Category":category,"Requirement":req,"Status":override or status,"Report Evidence":evidence,"Outstanding Action":action})
+    admin_ok=all(_provided(x) for x in [metadata.project_name, metadata.client, metadata.consultant, metadata.outline_plan_no, metadata.prepared_by])
+    add("SWMR-01","Project, developer, consultant, planning and professional information", "Complete" if admin_ok else "Partially complete", "Cover page", "Complete missing administrative and professional fields", "Administration")
+    add("SWMR-02","Cover letter, circulation status, unresolved matters and departures", "Partially complete", "Outstanding Information and Actions", "Prepare signed cover letter and identify unresolved matters", "Administration")
+    add("SWMR-03","Applicable MDP/SMDP, pond report, prior SWMR and downstream reports", "Complete" if reports else "Missing", "Applicable Reports Register" if reports else "—", "Upload or list applicable drainage documents", "Criteria")
+    add("SWMR-04","Study area, legal description, adjacent lands, external drainage and location figure", "Partially complete" if _provided(metadata.legal_description) else "Missing", "Section 2 / model area table", "Add legal description, site location, external drainage and study-area figure", "Site")
+    add("SWMR-05","Design objectives and verified project criteria", "Partially complete", "Project Criteria Register", "Confirm current City amendments and project-specific criteria", "Criteria")
+    add("SWMR-06","Model methodology, software, routing, infiltration, storm, timesteps and continuity", "Complete" if has_model and has_results else "Missing", "Section 3 and design-event table", "Provide model/results" if not has_results else "Professional confirmation", "Methodology")
+    add("SWMR-07","Subcatchment boundaries, areas, imperviousness, widths, slopes and outlets", "Complete" if has_model else "Missing", "Catchment tables", "Confirm against drainage drawings", "Hydrology")
+    if has_conduits:
+        add("SWMR-08","Minor-system routed flows, cumulative design flows, pipe capacities and spare capacity", "Partially complete" if has_results else "Missing", "Minor-system tables", "Verify release rate and full-flow capacities", "Minor System")
+        add("SWMR-09","HGL, surcharge, rim clearance, downstream HWL and backwater assessment", "Partially complete" if has_results else "Missing", "Node HGL table", "Confirm downstream HWL and prepare profiles where required", "Minor System")
+    else:
+        add("SWMR-08","Minor-system routed flows, cumulative design flows, pipe capacities and spare capacity", "Not applicable", "No conduits identified in uploaded model", "Confirm whether a separate minor-system model is within the report scope", "Minor System")
+        add("SWMR-09","HGL, surcharge, rim clearance, downstream HWL and backwater assessment", "Requires professional confirmation", "Storage/outfall HGL table; no conduit network identified", "Confirm whether a separate minor-system model and downstream HWL assessment are required", "Minor System")
+    add("SWMR-10","Catchbasin, inlet, ICD and outlet rating information", "Complete" if has_controls else "Not applicable / missing", "Hydraulic controls table" if has_controls else "—", "Confirm inlet types, rating curves and drawing locations", "Minor System")
+    add("SWMR-11","Critical overland flows, depths, velocities, spill routes and escape routes", "Partially complete" if has_overland else "Requires drawing review", "Major-system depth-velocity table" if has_overland else "No overland route identified in model", "Confirm overland route, grading, containment, escape routes and safety on drawings", "Major System")
+    add("SWMR-12","Trap-low and storage volume, depth, spill, entrance grade and restrictive covenant information", "Partially complete" if has_storage else "Not applicable", "Storage assessment" if has_storage else "—", "Add spill elevations, building grades and covenant requirements", "Storage")
+    add("SWMR-13","Minor and major boundary inflows/outflows and supporting source", "Partially complete" if has_outfalls else "Missing", "Boundary outflow tables" if has_outfalls else "—", "Confirm downstream capacity and external inflows", "Boundary Conditions")
+    add("SWMR-14","Private-site permissible discharge and on-site storage requirements", "Missing", "—", "Provide applicable release rates and private-site storage criteria", "Private Sites")
+    add("SWMR-15","Water-quality treatment, BMPs, downstream treatment and source controls", "Missing", "—", "Document water-quality strategy and downstream treatment", "Water Quality")
+    required_drawings={"site location","study area","catchment plan","model schematic","overland drainage","storm drainage"}
+    found=len(required_drawings & drawings)
+    add("SWMR-16","Required figures and drawings", "Complete" if found==len(required_drawings) else ("Partially complete" if found else "Missing"), f"{found}/{len(required_drawings)} core drawings recorded", "Add missing site, catchment, schematic, overland and storm-drainage drawings", "Drawings")
+    add("SWMR-17","Model input/output files, formatted listings, model schematic, drawing reconciliation and auditable digital package", "Partially complete" if has_model and has_results else "Missing", "Digital model package and structured appendices", "Add fixed-width input/output listings, model schematic, drawing-to-model cross-reference, revision metadata and final authenticated files", "Appendices")
+    return pd.DataFrame(rows)
+
+def _readiness_scores(checklist: pd.DataFrame) -> pd.DataFrame:
+    weights={"Complete":1.0,"Partially complete":0.5,"Requires professional confirmation":0.5,"Requires drawing review":0.5,"Not applicable":1.0,"Not applicable / missing":0.5,"Missing":0.0}
+    cats={"Model data completeness":["Methodology","Hydrology","Appendices"],"Hydraulic-result completeness":["Minor System","Major System","Storage","Boundary Conditions"],"Project information":["Administration","Site"],"Drawing completeness":["Drawings"],"Criteria verification":["Criteria","Private Sites","Water Quality"]}
+    rows=[]
+    for name,groups in cats.items():
+        d=checklist[checklist["Category"].isin(groups)]
+        score=100*sum(weights.get(str(x),0.25) for x in d["Status"])/max(len(d),1)
+        rows.append({"Readiness Dimension":name,"Score (%)":round(score,1)})
+    rows.append({"Readiness Dimension":"SWMR draft readiness","Score (%)":round(sum(r["Score (%)"] for r in rows)/len(rows),1)})
+    return pd.DataFrame(rows)
+
+def _add_narrative_block(doc: Document, narrative_sections: Mapping[str, str] | None, key: str) -> bool:
+    """Insert an approved narrative block while preserving simple paragraph/list structure."""
+    if not narrative_sections:
+        return False
+    text = str(narrative_sections.get(key, "") or "").strip()
+    if not text:
+        return False
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line:
+            continue
+        # Section headings are controlled by the deterministic report template.
+        if line.startswith("#"):
+            continue
+        if line.startswith(("- ", "* ")):
+            doc.add_paragraph(line[2:].strip(), style="List Bullet")
+        elif re.match(r"^\d+[.)]\s+", line):
+            doc.add_paragraph(re.sub(r"^\d+[.)]\s+", "", line), style="List Number")
+        else:
+            doc.add_paragraph(line)
+    return True
+
+
+
+def _scenario_inp_sections(record: Mapping[str, Any]) -> dict[str, list[list[str]]]:
+    raw = (record.get("files", {}) or {}).get("inp", b"")
+    if isinstance(raw, bytes):
+        text = raw.decode("utf-8", errors="ignore")
+    else:
+        text = str(raw or "")
+    sections: dict[str, list[list[str]]] = {}
+    current = None
+    for original in text.splitlines():
+        line = original.strip()
+        if line.startswith("[") and line.endswith("]"):
+            current = line[1:-1].strip().upper()
+            sections.setdefault(current, [])
+            continue
+        if not current or not line or line.startswith(";"):
+            continue
+        data = line.split(";", 1)[0].strip()
+        if data:
+            sections[current].append(data.split())
+    return sections
+
+def _series_peak(values: Mapping[str, Any], key: str, absolute: bool = False) -> float:
+    seq = values.get(key, []) or []
+    nums=[]
+    for v in seq:
+        try:
+            x=float(v); nums.append(abs(x) if absolute else x)
+        except (TypeError, ValueError):
+            pass
+    return max(nums, default=0.0)
+
+def _safe_float(value: Any) -> float | None:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def _peak_time(values: Mapping[str, Any], key: str, times: list[Any]) -> str:
+    seq = values.get(key, []) or []
+    if not seq:
+        return "Not available"
+    numeric=[]
+    for i, value in enumerate(seq):
+        try:
+            numeric.append((float(value), i))
+        except (TypeError, ValueError):
+            continue
+    if not numeric:
+        return "Not available"
+    _, idx=max(numeric, key=lambda x: x[0])
+    if idx < len(times):
+        return str(times[idx])
+    return str(idx)
+
+
+def _event_short_label(row: Mapping[str, Any]) -> str:
+    role=str(row.get("Model Role", "Scenario") or "Scenario")
+    storm=str(row.get("Storm", "Model event") or "Model event")
+    low=storm.lower().replace("_", " ")
+    match=re.search(r"(?:^|\D)(\d+)\s*(?:y|yr|year)", low)
+    if not match:
+        match=re.search(r"(\d+)y", low.replace(" ", ""))
+    event=f"{match.group(1)}-Year" if match else storm
+    prefix="Base" if role.lower()=="base" else "Scenario"
+    return f"{prefix} – {event}"
+
+
+def _scenario_detail_tables(record: Mapping[str, Any], units: UnitContext) -> dict[str, pd.DataFrame]:
+    results = record.get("results", {}) or {}
+    definition = record.get("definition", {}) or {}
+    summary = record.get("summary", {}) or {}
+    sections = _scenario_inp_sections(record)
+    storage_rows_inp = {r[0]: r for r in sections.get("STORAGE", []) if r}
+    storage_ids = set(storage_rows_inp)
+    outfall_ids = {r[0] for r in sections.get("OUTFALLS", []) if r}
+    conduit_ids = {r[0] for r in sections.get("CONDUITS", []) if r}
+    outlet_ids = {r[0] for r in sections.get("OUTLETS", []) if r}
+    node_ts = results.get("node_ts", {}) or {}
+    link_ts = results.get("link_ts", {}) or {}
+    sub_ts = results.get("sub_ts", {}) or {}
+    times = list(results.get("times", []) or [])
+
+    overview = pd.DataFrame([{
+        "Scenario": definition.get("scenario_name", summary.get("Scenario Name", "Scenario")),
+        "Source Model": summary.get("Source Model", (record.get("manifest", {}) or {}).get("base_model_name", "Not identified")),
+        "Rainfall Event": (definition.get("storm", {}) or {}).get("name", summary.get("Storm", "Model rainfall")),
+        "Storm Status": summary.get("Storm Status", (definition.get("storm", {}) or {}).get("source_status", "Not verified")),
+        "Runoff Error (%)": summary.get("Runoff Error (%)"),
+        "Flow Error (%)": summary.get("Flow Error (%)"),
+        f"Peak Subcatchment Runoff ({units.flow})": summary.get("Peak Subcatchment Runoff"),
+        f"Peak Link/Control Flow ({units.flow})": summary.get("Peak Link Flow"),
+        f"Maximum Node Inflow ({units.flow})": summary.get("Maximum Node Inflow"),
+        f"Maximum Node Flooding ({units.flow})": summary.get("Maximum Node Flooding"),
+        "Maximum Conduit Velocity": (summary.get("Maximum Link Velocity") if conduit_ids else "Not applicable — no conduits in model"),
+        "Maximum Conduit Depth Ratio": (summary.get("Maximum Modelled Depth Ratio") if conduit_ids else "Not applicable — no conduits in model"),
+    }])
+
+    sub_rows=[]
+    for sid, vals in sub_ts.items():
+        sub_rows.append({"Subcatchment": sid, f"Peak Runoff ({units.flow})": _series_peak(vals,"runoff"), f"Peak Rainfall ({units.rainfall})": _series_peak(vals,"rainfall")})
+
+    storage_rows=[]
+    for nid in sorted(storage_ids):
+        vals=node_ts.get(nid,{})
+        inp=storage_rows_inp.get(nid, [])
+        invert=_safe_float(inp[1]) if len(inp)>1 else None
+        max_depth=_safe_float(inp[2]) if len(inp)>2 else None
+        peak_depth=_series_peak(vals,"depth")
+        peak_head=_series_peak(vals,"head")
+        if not peak_head and invert is not None:
+            peak_head=invert+peak_depth
+        peak_volume=_series_peak(vals,"volume")
+        remaining=(max_depth-peak_depth) if max_depth is not None else None
+        utilization=(100.0*peak_depth/max_depth) if max_depth and max_depth>0 else None
+        storage_rows.append({
+            "Storage ID":nid,
+            f"Peak Depth ({units.length})":peak_depth,
+            f"Maximum HGL ({units.length})":peak_head,
+            f"Maximum Stored Volume ({units.storage})":peak_volume,
+            f"Peak Inflow ({units.flow})":_series_peak(vals,"inflow"),
+            f"Peak Outflow ({units.flow})":_series_peak(vals,"outflow"),
+            f"Peak Flooding ({units.flow})":_series_peak(vals,"flooding"),
+            "Time of Peak Storage":_peak_time(vals,"volume",times),
+            "Depth Utilization (%)":utilization,
+            f"Remaining Depth Margin ({units.length})":remaining,
+        })
+
+    outfall_rows=[]
+    for nid in sorted(outfall_ids):
+        vals=node_ts.get(nid,{})
+        outfall_rows.append({"Outfall ID":nid, f"Peak Depth ({units.length})":_series_peak(vals,"depth"), f"Peak Inflow ({units.flow})":_series_peak(vals,"inflow"), f"Peak Flooding ({units.flow})":_series_peak(vals,"flooding")})
+    control_rows=[]
+    for lid in sorted(outlet_ids):
+        vals=link_ts.get(lid,{})
+        control_rows.append({"Control ID":lid, f"Peak Flow ({units.flow})":_series_peak(vals,"flow",True), f"Peak Depth ({units.length})":_series_peak(vals,"depth"), "Time of Peak Flow":_peak_time(vals,"flow",times)})
+    conduit_rows=[]
+    for lid in sorted(conduit_ids):
+        vals=link_ts.get(lid,{})
+        diameter=float(vals.get("diameter",0) or 0)
+        depth=_series_peak(vals,"depth")
+        conduit_rows.append({"Conduit ID":lid, f"Peak Flow ({units.flow})":_series_peak(vals,"flow",True), f"Peak Velocity ({units.velocity})":_series_peak(vals,"velocity",True), "Modelled Depth Ratio": depth/diameter if diameter>0 else None})
+    return {"overview":overview,"subcatchments":pd.DataFrame(sub_rows),"storage":pd.DataFrame(storage_rows),"outfalls":pd.DataFrame(outfall_rows),"controls":pd.DataFrame(control_rows),"conduits":pd.DataFrame(conduit_rows)}
+
+def _compact_scenario_comparison(df: pd.DataFrame) -> pd.DataFrame:
+    if df is None or df.empty:
+        return pd.DataFrame()
+    out=df.copy()
+    out.insert(0, "Display Scenario", [_event_short_label(row) for _, row in out.iterrows()])
+    wanted=["Display Scenario","Source Model","Storm","Storm Status","Simulation Status","Runoff Error (%)","Flow Error (%)","Peak Subcatchment Runoff","Maximum Storage Depth","Maximum Storage Volume","Peak Link Flow","Maximum Node Inflow","Maximum Node Flooding","Hydraulic Difference"]
+    return out[[c for c in wanted if c in out.columns]].copy()
+
+def generate_report_package(
+    *,
+    metadata: ReportMetadata,
+    inp_sections: dict[str, list[list[str]]],
+    node_summary: pd.DataFrame,
+    link_summary: pd.DataFrame,
+    sub_summary: pd.DataFrame,
+    simulation_metadata: dict[str, Any],
+    result_db_bytes: bytes | None = None,
+    criteria: ReportCriteria | None = None,
+    narrative_sections: Mapping[str, str] | None = None,
+    scenario_comparison: pd.DataFrame | None = None,
+    scenario_analysis: str | None = None,
+    scenario_records: list[Mapping[str, Any]] | None = None,
+    scenario_reporting_mode: str = "Base report with scenario comparison",
+    preliminary_review_artifacts: Mapping[str, Any] | None = None,
+) -> dict[str, bytes | str]:
+    """Generate editable Word report and ZIP package entirely in memory."""
+    criteria = criteria or ReportCriteria()
+    options = _inp_options(inp_sections)
+    units = _unit_context(options.get("FLOW_UNITS", ""))
+    sub_table = _subcatchment_model_table(inp_sections, sub_summary)
+    link_table = _link_model_table(inp_sections, link_summary)
+    hgl_table = _node_hgl_table(node_summary)
+
+    # The simulation arrays are retained in the model's native unit system.
+    # Rename report headers to match that system; do not convert values.
+    sub_table = _rename_native_columns(sub_table, units)
+    link_table = _rename_native_columns(link_table, units)
+    hgl_table = _rename_native_columns(hgl_table, units)
+    sub_table = sub_table.loc[:, ~sub_table.columns.duplicated()].copy()
+    link_table = link_table.loc[:, ~link_table.columns.duplicated()].copy()
+    hgl_table = hgl_table.loc[:, ~hgl_table.columns.duplicated()].copy()
+    node_report = _rename_native_columns(node_summary, units)
+    link_report = _rename_native_columns(link_summary, units)
+    sub_report = _rename_native_columns(sub_summary, units)
+
+    report_step_s = _parse_time_seconds(options.get("REPORT_STEP"))
+    sub_report = _enhance_subcatchment_results(sub_report, units, report_step_s)
+    sub_table = _enhance_subcatchment_results(sub_table, units, report_step_s)
+    node_report = _populate_outfall_flows(node_report, link_report, units)
+    db_tables = _read_sqlite_tables(result_db_bytes, ["node_timeseries", "link_timeseries"])
+    control_table = _control_table(inp_sections, link_table, units)
+    control_recon = _control_reconciliation(control_table, link_table, units)
+    storage_table = _storage_table(inp_sections, node_report, db_tables, units)
+    if not storage_table.empty and not control_table.empty:
+        peak_col = f"Peak Flow ({units.flow})"
+        for idx in storage_table.index:
+            sid = storage_table.at[idx, "Storage ID"]
+            outgoing_peak = pd.to_numeric(control_table.loc[control_table["From Node"].astype(str) == str(sid), peak_col], errors="coerce").fillna(0).sum() if peak_col in control_table else 0.0
+            depth_col = next((c for c in storage_table.columns if c.startswith("Time-Series Peak Depth (")), None)
+            peak_depth = storage_table.at[idx, depth_col] if depth_col else storage_table.at[idx, f"Reported Peak Depth ({units.length})"]
+            if outgoing_peak > 0 and (pd.isna(peak_depth) or float(peak_depth) <= 0):
+                storage_table.at[idx, "Status"] = "Review: control flow occurs but storage depth is zero"
+    area_table = _area_classification(sub_table, units, criteria.area_classification)
+    critical_nodes, critical_links = _critical_elements(_rename_native_columns(_node_hgl_table(node_report), units), link_report, units, criteria)
+
+    calgary = CalgaryCriteria(
+        minor_release_rate_lps_ha=criteria.minor_release_rate_lps_ha,
+        trap_low_max_depth_m=criteria.trap_low_max_depth_m,
+        entrance_grade_margin_m=criteria.entrance_grade_margin_m,
+        pipe_critical_velocity_mps=criteria.velocity_threshold if units.system == "SI" else 4.0,
+        conduit_capacity_review_ratio=criteria.conduit_depth_ratio,
+        conduit_capacity_warning_ratio=criteria.conduit_capacity_warning_ratio,
+        continuity_review_pct=criteria.continuity_review,
+        continuity_warning_pct=criteria.continuity_warning,
+        special_link_limits=criteria.special_link_limits or {},
+        storage_classification=criteria.storage_classification or {},
+        outfall_classification=criteria.outfall_classification or {},
+    )
+    rain_gages = [r[1] for r in inp_sections.get("SUBCATCHMENTS", []) if len(r) > 1]
+    inferred_event, inferred_event_note = infer_design_event(rain_gages, metadata.design_storm)
+    if metadata.design_storm.strip().lower() in {"model design event", "not provided", ""}:
+        metadata.design_storm = inferred_event
+    criteria_table = criteria_register(calgary)
+    # Calgary-specific calculations use SI design rules. In US models, tables remain available but are flagged for review.
+    minor_capacity = build_minor_system_capacity_table(link_table, units.system, units.flow, units.length, calgary)
+    # Checklist applicability is based on actual model element types, not on
+    # whether the generic link table happens to contain outlet controls.
+    _conduit_rows = inp_sections.get("CONDUITS", []) or []
+    _xsection_rows = {str(r[0]): str(r[1]).upper() for r in (inp_sections.get("XSECTIONS", []) or []) if len(r) > 1}
+    _open_shapes = {"TRAPEZOIDAL", "RECT_OPEN", "TRIANGULAR", "IRREGULAR", "STREET"}
+    _has_overland = any(str(r[0]) in _xsection_rows and _xsection_rows[str(r[0])] in _open_shapes for r in _conduit_rows if r)
+    checklist_table = _build_swmr_checklist(
+        metadata,
+        criteria,
+        has_model=bool(inp_sections),
+        has_results=not node_report.empty,
+        has_storage=not storage_table.empty,
+        has_controls=not control_table.empty,
+        has_overland=_has_overland,
+        has_outfalls=bool((node_report.get("Type", pd.Series(dtype=str)).astype(str).str.lower()=="outfall").any()),
+        has_conduits=bool(_conduit_rows),
+    )
+    readiness_table = _readiness_scores(checklist_table)
+
+    doc = Document()
+    sec = doc.sections[0]
+    sec.top_margin = Inches(0.65)
+    sec.bottom_margin = Inches(0.65)
+    sec.left_margin = Inches(0.65)
+    sec.right_margin = Inches(0.65)
+
+    styles = doc.styles
+    styles["Normal"].font.name = "Arial"
+    styles["Normal"].font.size = Pt(9)
+    for sname in ("Title", "Heading 1", "Heading 2", "Heading 3"):
+        styles[sname].font.name = "Arial"
+        styles[sname].font.color.rgb = RGBColor(31, 78, 121)
+
+    title = doc.add_paragraph()
+    title.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    r = title.add_run("STORMWATER MANAGEMENT REPORT")
+    r.bold = True; r.font.size = Pt(20); r.font.color.rgb = RGBColor(31, 78, 121)
+    p = doc.add_paragraph(metadata.project_name)
+    p.alignment = WD_ALIGN_PARAGRAPH.CENTER
+    p.runs[0].bold = True; p.runs[0].font.size = Pt(16)
+
+    cover = doc.add_table(rows=0, cols=2); cover.style = "Table Grid"
+    for label, value in [
+        ("Subdivision (SB) #", metadata.subdivision_no), ("Outline Plan #", metadata.outline_plan_no),
+        ("Development Permit #", metadata.development_permit_no), ("Prepared for", metadata.client),
+        ("Prepared by", metadata.consultant), ("Consultant file number", metadata.consultant_file_no),
+        ("Responsible engineer", metadata.prepared_by), ("Checked by", metadata.checked_by),
+        ("Contact name", metadata.contact_name), ("Contact email", metadata.contact_email),
+        ("Legal description", metadata.legal_description), ("Circulation status", metadata.submission_status),
+        ("Construction drawing no.", metadata.construction_drawing_no), ("Development Agreement no.", metadata.development_agreement_no),
+        ("Report date", metadata.report_date), ("Reporting profile", metadata.municipality),
+    ]:
+        cells = cover.add_row().cells
+        _set_cell_text(cells[0], label, bold=True, size=9)
+        _set_cell_text(cells[1], value, size=9)
+
+    doc.add_page_break()
+    doc.add_heading("1.0 INTRODUCTION", level=1)
+    if not _add_narrative_block(doc, narrative_sections, "introduction"):
+        doc.add_paragraph(
+            f"This report summarizes the hydrologic and hydraulic analysis for {metadata.project_name}. "
+            "The document was generated from the deterministic EPA SWMM/OpenSWMM simulation results in the SWMM6 GIS Tool. "
+            "Project-specific planning, survey, geotechnical, environmental, drawing, and approval information must be verified by the responsible professional engineer."
+        )
+
+    doc.add_paragraph("Draft status: suitable for consultant/client discussion and structured engineering review. Human-in-the-loop completion, technical verification, drawing coordination, and professional authentication are required before municipal submission.")
+    doc.add_heading("1.1 Calgary SWMR Checklist Summary", level=2)
+    doc.add_paragraph("The completeness register tracks the principal Calgary SWMR checklist subjects. It is a draft-readiness tool, not a municipal compliance score.")
+    _add_df_table(doc, "Table 1A - Calgary SWMR Completeness Register", checklist_table, landscape=True, font_size=7.0)
+    _add_df_table(doc, "Table 1B - Draft Readiness Summary", readiness_table, font_size=8.0)
+    if criteria.applicable_reports:
+        doc.add_heading("1.2 Applicable Reports Register", level=2)
+        for item in criteria.applicable_reports: doc.add_paragraph(item, style="List Bullet")
+    _add_narrative_block(doc, narrative_sections, "applicable_criteria")
+
+    doc.add_heading("2.0 SITE DESCRIPTION AND DESIGN CRITERIA", level=1)
+    _add_narrative_block(doc, narrative_sections, "site_description")
+    native_area_col = f"Area ({units.area})"
+    total_area = float(sub_report[native_area_col].sum()) if not sub_report.empty and native_area_col in sub_report else 0.0
+    weighted_imp = 0.0
+    if not sub_report.empty and total_area > 0 and "% Impervious" in sub_report:
+        weighted_imp = float((sub_report[native_area_col] * sub_report["% Impervious"]).sum() / total_area)
+    doc.add_paragraph(
+        f"The model database contains {len(sub_summary) if sub_summary is not None else 0} subcatchments, "
+        f"{len(node_summary) if node_summary is not None else 0} nodes, and {len(link_summary) if link_summary is not None else 0} links. "
+        f"The combined model-database subcatchment area is {total_area:.3f} {units.area} and the area-weighted imperviousness is approximately {weighted_imp:.1f}%. "
+        "Pre-development/comparison and external catchments are listed separately below where identifiable from their names."
+    )
+    _add_df_table(doc, "Table 2A - Model Area Classification", area_table, font_size=8.2)
+    doc.add_heading("2.1 Design Objectives", level=2)
+    for text in [
+        "Confirm minor-system flows remain within selected hydraulic criteria.",
+        "Assess overland conveyance depth and velocity against the applicable municipal criteria.",
+        "Identify surcharge, flooding, instability, and continuity concerns.",
+        "Confirm boundary outflows and runoff volumes for the selected design event.",
+    ]:
+        doc.add_paragraph(text, style="List Bullet")
+
+    doc.add_heading("3.0 ANALYSIS METHODOLOGY AND DATA", level=1)
+    _add_narrative_block(doc, narrative_sections, "methodology")
+    doc.add_heading("3.1 Design Storm", level=2)
+    simulation_metadata = dict(simulation_metadata or {})
+    simulation_metadata["design_storm"] = metadata.design_storm
+    event_table = _event_summary(sub_report, simulation_metadata, options, units)
+    _add_df_table(doc, "Table 3A - Design Event Summary", event_table, font_size=8.2)
+    doc.add_paragraph(inferred_event_note)
+    if criteria.calgary_enabled:
+        _add_df_table(doc, "Table 3B - Calgary Project Criteria Register", criteria_table, landscape=True, font_size=7.5)
+    doc.add_heading("3.2 Computer Model", level=2)
+    doc.add_paragraph(
+        f"The analysis was completed using EPA SWMM/OpenSWMM. The report retains the model unit system ({units.system}; flow units {units.flow}). "
+        f"routing model: {options.get('FLOW_ROUTING', 'not identified')}; infiltration model: {options.get('INFILTRATION', 'not identified')}; "
+        f"reporting step: {options.get('REPORT_STEP', 'not identified')}; routing step: {options.get('ROUTING_STEP', 'not identified')}."
+    )
+    if options.get("FLOW_ROUTING", "").upper() == "KINWAVE":
+        doc.add_paragraph("Modelling limitation: kinematic-wave routing does not fully represent backwater, pressurization, reverse flow, or complex surcharge interactions. Dynamic-wave routing should be considered where these effects are material.")
+    doc.add_heading("3.3 Major-Minor System", level=2)
+    doc.add_paragraph("Open channels, swales, gutters, culverts, and closed conduits represented in the model were reviewed. Final major/minor classification must be confirmed against the approved drainage concept and drawings.")
+    if scenario_comparison is not None and not scenario_comparison.empty:
+        doc.add_heading("3.4 Preliminary Design Scenarios", level=2)
+        doc.add_paragraph(
+            "The scenario register summarizes preliminary model alternatives generated and simulated through the Rev22 workflow. "
+            "Scenario storm sources, parameter changes, and review status must be confirmed by the responsible engineer before design use."
+        )
+        doc.add_paragraph(f"Reporting mode: {scenario_reporting_mode}.")
+        compact_scenario = _compact_scenario_comparison(scenario_comparison)
+        _add_df_table(doc, "Table 3C - Preliminary Scenario Comparison", compact_scenario, landscape=True, font_size=7.2)
+        if scenario_analysis:
+            doc.add_heading("3.4.1 Scenario Comparison Analysis", level=3)
+            for paragraph in str(scenario_analysis).split("\n\n"):
+                if paragraph.strip():
+                    doc.add_paragraph(paragraph.strip())
+        if scenario_records and scenario_reporting_mode != "Base report with scenario comparison":
+            doc.add_heading("3.4.2 Event-Specific Deterministic Results", level=3)
+            doc.add_paragraph("Each selected model-event combination is presented as a separate deterministic dataset. Values shown as not applicable indicate that the corresponding model element type is absent.")
+            table_no = 1
+            for record in scenario_records:
+                definition = record.get("definition", {}) or {}
+                summary = record.get("summary", {}) or {}
+                label = _event_short_label(summary)
+                full_label = definition.get("scenario_name", f"Scenario {table_no}")
+                doc.add_heading(str(label), level=4)
+                doc.add_paragraph(f"Model-event dataset: {full_label}. Source model: {summary.get('Source Model', 'Not identified')}. Rainfall event: {summary.get('Storm', 'Not identified')}.")
+                detail = _scenario_detail_tables(record, units)
+                for key, title in [("overview","Event Summary"),("storage","Storage Results"),("controls","Outlet and Control Results"),("outfalls","Outfall Results"),("conduits","Conduit Results"),("subcatchments","Subcatchment Results")]:
+                    frame=detail[key]
+                    if frame is not None and not frame.empty:
+                        _add_df_table(doc, f"Table 3D-{table_no} - {label}: {title}", frame, landscape=len(frame.columns)>6, font_size=7.4)
+                        table_no += 1
+        doc.add_heading("3.5 Catchment Areas", level=2)
+    else:
+        doc.add_heading("3.4 Catchment Areas", level=2)
+    _add_narrative_block(doc, narrative_sections, "hydrology")
+    catchment_main_cols = [
+        "Sub ID", "Rain Gage", "Outlet", f"Area ({units.area})", "Impervious (%)",
+        f"Width ({units.length})", "Slope (%)", "n Imperv.", "n Perv.",
+        f"Peak Runoff ({units.flow})", f"Peak Rainfall ({units.rainfall})", "Peak-Flow Runoff Coefficient",
+    ]
+    _add_df_table(doc, "Table 4 - Catchment Parameters and Runoff Results", sub_table[[c for c in catchment_main_cols if c in sub_table.columns]], landscape=True)
+
+    doc.add_heading("4.0 RESULTS", level=1)
+    doc.add_heading("4.1 Major-System and Spill-Route Assessment", level=2)
+    _add_narrative_block(doc, narrative_sections, "major_system")
+    overland = link_table.copy()
+    if criteria.major_link_ids:
+        selected = {str(x).strip() for x in criteria.major_link_ids if str(x).strip()}
+        overland = overland[overland["Link ID"].astype(str).isin(selected)].copy()
+    else:
+        # Outlet/orifice/weir controls are not automatically classified as
+        # major-system overland routes. Only open conduit/street shapes are
+        # included unless the engineer explicitly supplies major_link_ids.
+        model_type = overland.get("Model Type", overland.get("Type", pd.Series("", index=overland.index))).astype(str).str.lower()
+        shape = overland.get("Shape", pd.Series("", index=overland.index)).fillna("").astype(str).str.upper()
+        overland = overland[model_type.eq("conduit") & shape.isin(["TRAPEZOIDAL", "RECT_OPEN", "TRIANGULAR", "IRREGULAR", "STREET"])].copy()
+    overland_cols = ["Link ID", "From Node", "To Node", "Shape", f"Peak Flow ({units.flow})", f"Peak Depth ({units.length})", f"Peak Velocity ({units.velocity})", "Depth Ratio", "Status"]
+    _add_df_table(doc, "Table 9 - Overland Flow Assessment", overland[[c for c in overland_cols if c in overland.columns]], landscape=True)
+    overland_compliance = build_overland_compliance_table(overland, calgary, units.flow, units.length, units.velocity) if units.system == "SI" else pd.DataFrame()
+    if not overland_compliance.empty:
+        _add_df_table(doc, "Table 9A - Calgary Major-System Depth-Velocity Screening", overland_compliance, landscape=True, font_size=7.2)
+
+    outfalls = node_report[node_report["Type"].astype(str).str.lower() == "outfall"].copy() if not node_report.empty and "Type" in node_report else pd.DataFrame()
+    if not outfalls.empty:
+        outfalls["Status"] = "Boundary condition"
+        outfalls["Depth Ratio"] = "N/A"
+    outfall_cols = ["Node ID", "Type", f"Invert ({units.length})", f"Peak Depth ({units.length})", f"Peak Inflow ({units.flow})", f"Peak Flooding ({units.flow})", "Status"]
+    _add_df_table(doc, "Table 10 - Major System Boundary Conditions - Outflows", outfalls[[c for c in outfall_cols if c in outfalls.columns]])
+
+    doc.add_heading("4.2 Minor-System Assessment", level=2)
+    _add_narrative_block(doc, narrative_sections, "minor_system")
+    if f"Diameter ({units.length})" in link_table.columns:
+        link_table = link_table.rename(columns={f"Diameter ({units.length})": f"Diameter / Geom1 ({units.length})"})
+    minor_cols = ["Link ID", "From Node", "To Node", "Shape", f"Length ({units.length})", f"Diameter / Geom1 ({units.length})", "Manning n", f"Peak Flow ({units.flow})", f"Peak Depth ({units.length})", "Depth Ratio", f"Peak Velocity ({units.velocity})", "Status"]
+    conduit_table = link_table[link_table.get("Model Type", link_table.get("Type", "")).astype(str).str.lower().eq("conduit")].copy()
+    _add_df_table(doc, "Table 12A - Conduit, Culvert, Swale and Gutter Analysis", conduit_table[[c for c in minor_cols if c in conduit_table.columns]], landscape=True)
+    if not minor_capacity.empty:
+        _add_df_table(doc, "Table 12A-1 - Calgary Minor-System Capacity Screening", minor_capacity, landscape=True, font_size=7.2)
+    doc.add_heading("4.3 Hydraulic Controls", level=2)
+    _add_narrative_block(doc, narrative_sections, "hydraulic_controls")
+    if not criteria.suppress_empty_sections or not control_table.empty:
+        _add_df_table(doc, "Table 12B - Hydraulic Controls", control_table, landscape=True, font_size=7.2)
+    if not criteria.suppress_empty_sections or not control_recon.empty:
+        _add_df_table(doc, "Table 12C - Hydraulic Control Flow Reconciliation", control_recon, landscape=True, font_size=7.2)
+    doc.add_heading("4.4 Storage and Trap-Low Assessment", level=2)
+    _add_narrative_block(doc, narrative_sections, "storage")
+    storage_calgary = apply_storage_classification(storage_table, calgary, units.length) if not storage_table.empty else pd.DataFrame()
+    if not criteria.suppress_empty_sections or not storage_calgary.empty:
+        _add_df_table(doc, "Table 13 - Storage Unit Performance", storage_calgary, landscape=True, font_size=7.0)
+    if criteria.suppress_empty_sections and control_table.empty and storage_table.empty:
+        doc.add_paragraph("The model does not contain hydraulic controls or storage units; related result tables are not applicable.")
+
+    doc.add_heading("4.5 HGL, Surcharge, and Flooding Assessment", level=2)
+    _add_narrative_block(doc, narrative_sections, "hgl_surcharge")
+    hgl_display = hgl_table.copy()
+    if not hgl_display.empty and "Type" in hgl_display:
+        mask = hgl_display["Type"].astype(str).str.lower().eq("outfall")
+        for c in [f"Ground/Rim ({units.length})", f"Freeboard ({units.length})"]:
+            if c in hgl_display:
+                hgl_display[c] = hgl_display[c].astype(object)
+                hgl_display.loc[mask, c] = "N/A"
+        if "Status" in hgl_display: hgl_display.loc[mask, "Status"] = "Boundary condition"
+    _add_df_table(doc, "Table 15 - Summary of Node HGL / Surcharge Conditions", hgl_display, landscape=True)
+    doc.add_heading("4.6 Outfalls and Boundary Conditions", level=2)
+    _add_narrative_block(doc, narrative_sections, "outfalls")
+    _add_df_table(doc, "Table 16 - Minor System Boundary Conditions - Outflows", outfalls[[c for c in outfall_cols if c in outfalls.columns]])
+    if narrative_sections and str(narrative_sections.get("private_sites", "")).strip():
+        doc.add_heading("4.7 Private-Site Discharge and Storage", level=2)
+        _add_narrative_block(doc, narrative_sections, "private_sites")
+    if narrative_sections and str(narrative_sections.get("water_quality", "")).strip():
+        doc.add_heading("4.8 Water Quality and BMPs", level=2)
+        _add_narrative_block(doc, narrative_sections, "water_quality")
+    if narrative_sections and str(narrative_sections.get("model_documentation", "")).strip():
+        doc.add_heading("4.9 Model Input/Output Documentation", level=2)
+        _add_narrative_block(doc, narrative_sections, "model_documentation")
+
+    doc.add_heading("5.0 SUMMARY OF FINDINGS, CONCLUSIONS, AND RECOMMENDATIONS", level=1)
+    findings = _summary_findings(node_report, link_report, sub_report, simulation_metadata, units, options, criteria)
+    doc.add_heading("5.1 Executive Summary", level=2)
+    if not _add_narrative_block(doc, narrative_sections, "executive_summary"):
+        for line in _executive_summary(findings, critical_nodes, critical_links, units, criteria):
+            doc.add_paragraph(line)
+    doc.add_heading("5.2 Detailed Findings", level=2)
+    for finding in findings:
+        doc.add_paragraph(finding, style="List Bullet")
+    doc.add_paragraph(
+        f"QA/QC screening criteria for junctions/dividers: depth ratio ≥ {criteria.node_depth_ratio:.2f}; rim clearance ≤ {criteria.minimum_freeboard:g} {units.length}; storage facilities are assessed separately by classification; "
+        f"conduit depth ratio ≥ {criteria.conduit_depth_ratio:.2f}; velocity ≥ {criteria.velocity_threshold:g} {units.velocity}; "
+        f"continuity review/warning thresholds = {criteria.continuity_review:g}%/{criteria.continuity_warning:g}%.",
+        style=None,
+    )
+    doc.add_paragraph(
+        "Peak-flow runoff coefficient is calculated from the Rational Method relationship and is a screening statistic; it is not necessarily equivalent to the volumetric event runoff coefficient.",
+        style=None,
+    )
+    if not criteria.suppress_empty_sections or not critical_nodes.empty:
+        _add_df_table(doc, "Table 17A - Critical Nodes Requiring Review", critical_nodes, font_size=8.0)
+    if not criteria.suppress_empty_sections or not critical_links.empty:
+        _add_df_table(doc, "Table 17B - Critical Conduits Requiring Review", critical_links, landscape=True, font_size=7.8)
+    doc.add_heading("5.3 Outstanding Information and Actions", level=2)
+    outstanding = checklist_table[~checklist_table["Status"].isin(["Complete", "Not applicable"])][["Item","Requirement","Status","Outstanding Action"]]
+    _add_df_table(doc, "Table 18 - Outstanding SWMR Information and Actions", outstanding, landscape=True, font_size=7.2)
+    _add_narrative_block(doc, narrative_sections, "outstanding_actions")
+    doc.add_heading("5.4 Conclusions and Recommendations", level=2)
+    _add_narrative_block(doc, narrative_sections, "conclusions")
+    doc.add_paragraph(
+        "This automatically generated report is a model-data population aid. It does not replace engineering judgment, "
+        "municipal criteria verification, design-drawing review, boundary-condition confirmation, or professional authentication."
+    )
+
+    doc.add_page_break()
+    doc.add_heading("APPENDIX A - MODEL DATA", level=1)
+    link_geom, link_params, link_results = _split_link_appendix(conduit_table, units)
+    _add_df_table(doc, "Table A-1 - Link Connectivity and Geometry", link_geom, landscape=True, font_size=7.0)
+    _add_df_table(doc, "Table A-2 - Link Hydraulic Parameters", link_params, landscape=True, font_size=7.2)
+    _add_df_table(doc, "Table A-3 - Link Simulation Results", link_results, landscape=True, font_size=7.2)
+    if not criteria.suppress_empty_sections or not control_table.empty:
+        _add_df_table(doc, "Table A-4 - Hydraulic Control Parameters and Results", control_table, landscape=True, font_size=7.0)
+    if not criteria.suppress_empty_sections or not storage_calgary.empty:
+        _add_df_table(doc, "Table A-5 - Storage Unit Parameters and Results", storage_calgary, landscape=True, font_size=6.8)
+    _add_df_table(doc, "Table A-6 - Node Model and Result Summary", hgl_display, landscape=True, font_size=7.0)
+
+    if criteria.calgary_enabled:
+        doc.add_heading("APPENDIX B - CALGARY QA/QC", level=1)
+        _add_df_table(doc, "Table B-1 - Project Criteria Register", criteria_table, landscape=True, font_size=7.2)
+        if not overland_compliance.empty:
+            _add_df_table(doc, "Table B-2 - Major-System Depth-Velocity Screening", overland_compliance, landscape=True, font_size=7.0)
+        if not minor_capacity.empty:
+            _add_df_table(doc, "Table B-3 - Minor-System Capacity Screening", minor_capacity, landscape=True, font_size=7.0)
+        _add_df_table(doc, "Table B-4 - Calgary SWMR Completeness Register", checklist_table, landscape=True, font_size=6.8)
+        _add_df_table(doc, "Table B-5 - Draft Readiness Summary", readiness_table, font_size=8.0)
+
+    doc.add_heading("APPENDIX C - SUBCATCHMENT DATA", level=1)
+    sub_model, sub_results = _split_subcatchment_appendix(sub_table, units)
+    _add_df_table(doc, "Table B-1 - Subcatchment Model Parameters", sub_model, landscape=True, font_size=7.0)
+    _add_df_table(doc, "Table B-2 - Subcatchment Simulation Results", sub_results, landscape=True, font_size=7.2)
+
+    llm_context = build_llm_report_context(
+        metadata=asdict(metadata), criteria=calgary, findings=findings,
+        tables={
+            "design_event": event_table, "criteria_register": criteria_table,
+            "minor_system": minor_capacity, "major_system": overland_compliance,
+            "storage": storage_calgary, "critical_nodes": critical_nodes,
+            "critical_conduits": critical_links, "outfalls": outfalls,
+            "swmr_checklist": checklist_table, "draft_readiness": readiness_table,
+            "scenario_comparison": scenario_comparison if scenario_comparison is not None else pd.DataFrame(),
+        },
+    )
+    docx_buffer = io.BytesIO(); doc.save(docx_buffer); docx_bytes = docx_buffer.getvalue()
+    base = _safe_name(metadata.project_name)
+
+    zip_buffer = io.BytesIO()
+    with zipfile.ZipFile(zip_buffer, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr(f"{base}_SWM_Report.docx", docx_bytes)
+        zf.writestr("tables/node_summary.csv", node_report.to_csv(index=False) if node_summary is not None else "")
+        zf.writestr("tables/link_summary.csv", link_report.to_csv(index=False) if link_summary is not None else "")
+        zf.writestr("tables/subcatchment_summary.csv", sub_report.to_csv(index=False) if sub_summary is not None else "")
+        zf.writestr("tables/catchment_model_results.csv", sub_table.to_csv(index=False))
+        zf.writestr("tables/link_model_results.csv", link_table.to_csv(index=False))
+        zf.writestr("tables/node_hgl_summary.csv", hgl_table.to_csv(index=False))
+        zf.writestr("tables/hydraulic_controls.csv", control_table.to_csv(index=False))
+        zf.writestr("tables/control_flow_reconciliation.csv", control_recon.to_csv(index=False))
+        zf.writestr("tables/storage_unit_performance.csv", storage_table.to_csv(index=False))
+        zf.writestr("tables/model_area_classification.csv", area_table.to_csv(index=False))
+        zf.writestr("tables/critical_nodes.csv", critical_nodes.to_csv(index=False))
+        zf.writestr("tables/critical_conduits.csv", critical_links.to_csv(index=False))
+        zf.writestr("tables/design_event_summary.csv", event_table.to_csv(index=False))
+        zf.writestr("tables/calgary_criteria_register.csv", criteria_table.to_csv(index=False))
+        zf.writestr("tables/calgary_minor_system_capacity.csv", minor_capacity.to_csv(index=False))
+        zf.writestr("tables/calgary_major_system_compliance.csv", overland_compliance.to_csv(index=False))
+        zf.writestr("tables/calgary_storage_assessment.csv", storage_calgary.to_csv(index=False))
+        zf.writestr("tables/calgary_swmr_completeness_register.csv", checklist_table.to_csv(index=False))
+        zf.writestr("tables/swmr_draft_readiness.csv", readiness_table.to_csv(index=False))
+        if scenario_comparison is not None and not scenario_comparison.empty:
+            zf.writestr("tables/preliminary_scenario_comparison.csv", scenario_comparison.to_csv(index=False))
+        if scenario_analysis:
+            zf.writestr("narratives/preliminary_scenario_comparison_analysis.txt", str(scenario_analysis))
+        if scenario_records:
+            for record in scenario_records:
+                sid = str((record.get("definition", {}) or {}).get("scenario_id", "scenario"))
+                if sid == "BASE_MODEL":
+                    continue
+                for key, frame in _scenario_detail_tables(record, units).items():
+                    if frame is not None and not frame.empty:
+                        zf.writestr(f"tables/scenarios/{sid}_{key}.csv", frame.to_csv(index=False))
+        zf.writestr("metadata/llm_report_context.json", json.dumps(llm_context, indent=2, default=str))
+        zf.writestr("metadata/approved_narrative_sections.json", json.dumps(dict(narrative_sections or {}), indent=2, ensure_ascii=False))
+        zf.writestr("metadata/project_metadata.json", json.dumps(asdict(metadata), indent=2))
+        zf.writestr("metadata/report_criteria.json", json.dumps(asdict(criteria), indent=2, default=str))
+        zf.writestr("metadata/simulation_metadata.json", json.dumps(simulation_metadata, indent=2, default=str))
+        zf.writestr("metadata/inp_sections.json", json.dumps(inp_sections, indent=2, default=str))
+        if preliminary_review_artifacts:
+            zf.writestr("preliminary_design/review_manifest.json", json.dumps(preliminary_review_artifacts.get("manifest", {}), indent=2, default=str))
+            findings_df = preliminary_review_artifacts.get("findings")
+            if isinstance(findings_df, pd.DataFrame):
+                zf.writestr("preliminary_design/findings_register.csv", findings_df.to_csv(index=False))
+            elif findings_df:
+                zf.writestr("preliminary_design/findings_register.json", json.dumps(findings_df, indent=2, default=str))
+            if preliminary_review_artifacts.get("ai_review"):
+                zf.writestr("preliminary_design/ai_review.md", str(preliminary_review_artifacts.get("ai_review")))
+            if preliminary_review_artifacts.get("reviewed_model"):
+                zf.writestr("preliminary_design/reviewed_scenario_base.inp", str(preliminary_review_artifacts.get("reviewed_model")))
+        if result_db_bytes:
+            zf.writestr("database/swmm_complete_results.sqlite", result_db_bytes)
+
+    return {
+        "docx": docx_bytes,
+        "zip": zip_buffer.getvalue(),
+        "docx_name": f"{base}_SWM_Report.docx",
+        "zip_name": f"{base}_SWM_Report_Package.zip",
+        "catchment_table": sub_table,
+        "link_table": link_table,
+        "hgl_table": hgl_table,
+        "control_table": control_table,
+        "storage_table": storage_calgary,
+        "area_table": area_table,
+        "calgary_criteria_table": criteria_table,
+        "calgary_minor_capacity": minor_capacity,
+        "calgary_overland_compliance": overland_compliance,
+        "swmr_checklist": checklist_table, "draft_readiness": readiness_table,
+        "llm_context": llm_context,
+        "narrative_sections": dict(narrative_sections or {}),
+        "scenario_comparison": scenario_comparison if scenario_comparison is not None else pd.DataFrame(),
+    }

requirements.txt

@@ -0,0 +1,9 @@
+# Server environment (OpenSWMM intentionally absent — worker venv only)
+mcp>=1.10,<2
+fastapi>=0.110
+uvicorn>=0.29
+httpx>=0.27
+pandas>=2.0
+numpy>=1.26
+python-docx>=1.1
+PyYAML>=6.0

results_db.py

@@ -0,0 +1,333 @@
+"""Complete SQLite store for SWMM model inputs, outputs, summaries and AI retrieval."""
+from __future__ import annotations
+
+import json
+import re
+import sqlite3
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+
+class ResultDatabase:
+    """File-backed SQLite database containing the complete model and simulation dataset.
+
+    The database is intentionally file-backed rather than ``:memory:`` so the user can
+    download it, inspect it in any SQLite client, and retain an auditable simulation
+    artefact. The LLM still receives only bounded query results.
+    """
+
+    def __init__(self, db_path: str | Path | None = None) -> None:
+        if db_path is None:
+            fd, name = tempfile.mkstemp(prefix="swmm_model_", suffix=".sqlite")
+            Path(name).unlink(missing_ok=True)
+            try:
+                import os
+                os.close(fd)
+            except OSError:
+                pass
+            self.path = Path(name)
+        else:
+            self.path = Path(db_path)
+        self.connection = sqlite3.connect(str(self.path), check_same_thread=False)
+        self.connection.execute("PRAGMA journal_mode=WAL")
+        self.connection.execute("PRAGMA synchronous=NORMAL")
+        self.connection.execute("PRAGMA foreign_keys=ON")
+
+    @staticmethod
+    def _safe_table_name(section: str) -> str:
+        clean = re.sub(r"[^a-zA-Z0-9_]+", "_", section.strip().lower()).strip("_")
+        return f"inp_{clean or 'unknown'}"
+
+    def _load_complete_input(self, inp_path: str | Path) -> None:
+        path = Path(inp_path)
+        text = path.read_text(encoding="utf-8", errors="replace")
+        line_rows: list[dict[str, Any]] = []
+        section_rows: dict[str, list[dict[str, Any]]] = {}
+        catalog: list[dict[str, Any]] = []
+        current_section = "PREAMBLE"
+        section_row_no = 0
+
+        for line_no, raw in enumerate(text.splitlines(), start=1):
+            stripped = raw.strip()
+            is_section = stripped.startswith("[") and "]" in stripped
+            if is_section:
+                current_section = stripped[1:stripped.index("]")].strip().upper()
+                section_row_no = 0
+            elif stripped and not stripped.startswith(";"):
+                section_row_no += 1
+
+            line_rows.append({
+                "line_no": line_no,
+                "section_name": current_section,
+                "section_row_no": section_row_no if not is_section else 0,
+                "raw_text": raw,
+                "stripped_text": stripped,
+                "is_blank": int(not stripped),
+                "is_comment": int(stripped.startswith(";")),
+                "is_section_header": int(is_section),
+            })
+
+            if stripped and not stripped.startswith(";") and not is_section:
+                # Keep both the exact raw line and all whitespace-delimited values.
+                tokens = stripped.split()
+                row = {
+                    "row_no": section_row_no,
+                    "source_line_no": line_no,
+                    "raw_text": raw,
+                }
+                for i, token in enumerate(tokens, start=1):
+                    row[f"value_{i}"] = token
+                section_rows.setdefault(current_section, []).append(row)
+
+        pd.DataFrame(line_rows).to_sql(
+            "model_input_lines", self.connection, if_exists="replace", index=False
+        )
+        pd.DataFrame([{
+            "file_name": path.name,
+            "absolute_path_at_run": str(path),
+            "byte_size": path.stat().st_size,
+            "line_count": len(line_rows),
+            "full_text": text,
+        }]).to_sql("model_input_file", self.connection, if_exists="replace", index=False)
+
+        for section, rows in section_rows.items():
+            table = self._safe_table_name(section)
+            pd.DataFrame(rows).to_sql(table, self.connection, if_exists="replace", index=False)
+            catalog.append({
+                "section_name": section,
+                "table_name": table,
+                "row_count": len(rows),
+                "max_values_per_row": max(
+                    (sum(1 for k in r if k.startswith("value_")) for r in rows), default=0
+                ),
+            })
+
+        pd.DataFrame(catalog).to_sql(
+            "model_input_section_catalog", self.connection, if_exists="replace", index=False
+        )
+
+    @staticmethod
+    def _time_strings(times: list[Any]) -> list[str]:
+        return [t.isoformat(sep=" ") if hasattr(t, "isoformat") else str(t) for t in times]
+
+    def _load_complete_outputs(self, results: dict[str, Any]) -> None:
+        times = results.get("times", [])
+        time_strings = self._time_strings(times)
+
+        node_rows: list[dict[str, Any]] = []
+        for node_id, data in results.get("node_ts", {}).items():
+            n = max((len(data.get(k, [])) for k in (
+                "depth", "flooding", "inflow", "head", "outflow", "volume"
+            )), default=0)
+            for i in range(n):
+                node_rows.append({
+                    "time_index": i,
+                    "timestamp": time_strings[i] if i < len(time_strings) else str(i),
+                    "node_id": node_id,
+                    "depth": data.get("depth", [None] * n)[i],
+                    "flooding": data.get("flooding", [None] * n)[i],
+                    "inflow": data.get("inflow", [None] * n)[i],
+                    "head": data.get("head", [None] * n)[i],
+                    "outflow": data.get("outflow", [None] * n)[i],
+                    "volume": data.get("volume", [None] * n)[i],
+                })
+        pd.DataFrame(node_rows, columns=[
+            "time_index", "timestamp", "node_id", "depth", "flooding",
+            "inflow", "head", "outflow", "volume"
+        ]).to_sql("node_timeseries", self.connection, if_exists="replace", index=False, chunksize=5000)
+
+        node_static = [{
+            "node_id": node_id,
+            "invert_elevation": data.get("invert_elevation"),
+            "full_depth": data.get("full_depth"),
+        } for node_id, data in results.get("node_ts", {}).items()]
+        pd.DataFrame(node_static, columns=["node_id", "invert_elevation", "full_depth"]).to_sql(
+            "node_output_metadata", self.connection, if_exists="replace", index=False
+        )
+
+        link_rows: list[dict[str, Any]] = []
+        for link_id, data in results.get("link_ts", {}).items():
+            n = max((len(data.get(k, [])) for k in (
+                "flow", "depth", "velocity", "volume", "capacity"
+            )), default=0)
+            for i in range(n):
+                link_rows.append({
+                    "time_index": i,
+                    "timestamp": time_strings[i] if i < len(time_strings) else str(i),
+                    "link_id": link_id,
+                    "flow": data.get("flow", [None] * n)[i],
+                    "depth": data.get("depth", [None] * n)[i],
+                    "velocity": data.get("velocity", [None] * n)[i],
+                    "volume": data.get("volume", [None] * n)[i],
+                    "capacity": data.get("capacity", [None] * n)[i],
+                })
+        pd.DataFrame(link_rows, columns=[
+            "time_index", "timestamp", "link_id", "flow", "depth",
+            "velocity", "volume", "capacity"
+        ]).to_sql("link_timeseries", self.connection, if_exists="replace", index=False, chunksize=5000)
+
+        link_static = [{
+            "link_id": link_id,
+            "length": data.get("length"),
+            "roughness": data.get("roughness"),
+            "diameter": data.get("diameter"),
+        } for link_id, data in results.get("link_ts", {}).items()]
+        pd.DataFrame(link_static, columns=["link_id", "length", "roughness", "diameter"]).to_sql(
+            "link_output_metadata", self.connection, if_exists="replace", index=False
+        )
+
+        sub_rows: list[dict[str, Any]] = []
+        for sub_id, data in results.get("sub_ts", {}).items():
+            n = max((len(data.get(k, [])) for k in ("runoff", "rainfall", "infil")), default=0)
+            for i in range(n):
+                sub_rows.append({
+                    "time_index": i,
+                    "timestamp": time_strings[i] if i < len(time_strings) else str(i),
+                    "subcatchment_id": sub_id,
+                    "runoff": data.get("runoff", [None] * n)[i],
+                    "rainfall": data.get("rainfall", [None] * n)[i],
+                    "infiltration": data.get("infil", [None] * n)[i],
+                })
+        pd.DataFrame(sub_rows, columns=[
+            "time_index", "timestamp", "subcatchment_id", "runoff", "rainfall", "infiltration"
+        ]).to_sql("subcatchment_timeseries", self.connection, if_exists="replace", index=False, chunksize=5000)
+
+        metadata = results.get("metadata", {})
+        meta_rows = []
+        warnings = metadata.get("warnings", []) or []
+        for key, value in metadata.items():
+            if key == "warnings":
+                continue
+            if isinstance(value, (dict, list, tuple)):
+                value = json.dumps(value, default=str)
+            elif hasattr(value, "isoformat"):
+                value = value.isoformat()
+            meta_rows.append({"key": key, "value": value})
+        pd.DataFrame(meta_rows, columns=["key", "value"]).to_sql(
+            "simulation_metadata", self.connection, if_exists="replace", index=False
+        )
+        pd.DataFrame(warnings, columns=["code", "message"]).to_sql(
+            "simulation_warnings", self.connection, if_exists="replace", index=False
+        )
+
+        # Indexes materially reduce retrieval cost for large models.
+        self.connection.executescript("""
+        CREATE INDEX IF NOT EXISTS idx_node_ts_id_time ON node_timeseries(node_id, time_index);
+        CREATE INDEX IF NOT EXISTS idx_node_ts_flood ON node_timeseries(flooding DESC);
+        CREATE INDEX IF NOT EXISTS idx_link_ts_id_time ON link_timeseries(link_id, time_index);
+        CREATE INDEX IF NOT EXISTS idx_link_ts_capacity ON link_timeseries(capacity DESC);
+        CREATE INDEX IF NOT EXISTS idx_sub_ts_id_time ON subcatchment_timeseries(subcatchment_id, time_index);
+        CREATE INDEX IF NOT EXISTS idx_input_section ON model_input_lines(section_name, section_row_no);
+        """)
+
+    def load(
+        self,
+        node_summary: pd.DataFrame,
+        link_summary: pd.DataFrame,
+        sub_summary: pd.DataFrame,
+        *,
+        inp_path: str | Path,
+        results: dict[str, Any],
+    ) -> None:
+        node_summary.to_sql("node_summary", self.connection, if_exists="replace", index=False)
+        link_summary.to_sql("link_summary", self.connection, if_exists="replace", index=False)
+        sub_summary.to_sql("subcatchment_summary", self.connection, if_exists="replace", index=False)
+        self._load_complete_input(inp_path)
+        self._load_complete_outputs(results)
+        self.connection.commit()
+
+    def table_catalog(self) -> pd.DataFrame:
+        return pd.read_sql_query("""
+            SELECT name AS table_name
+            FROM sqlite_master
+            WHERE type='table' AND name NOT LIKE 'sqlite_%'
+            ORDER BY name
+        """, self.connection)
+
+    def export_bytes(self) -> bytes:
+        self.connection.commit()
+        # Checkpoint WAL so the downloaded main file is self-contained.
+        try:
+            self.connection.execute("PRAGMA wal_checkpoint(FULL)")
+        except sqlite3.DatabaseError:
+            pass
+        return self.path.read_bytes()
+
+    @staticmethod
+    def _quoted(value: str) -> str:
+        return value.replace("'", "''")
+
+    def engineering_context(self, question: str, limit: int = 20) -> str:
+        """Return compact SQL-derived context while retaining the full database locally."""
+        q = question.lower()
+        parts: list[str] = []
+
+        # Asset IDs in the question are used to retrieve exact time series.
+        ids = re.findall(r"\b[A-Za-z][A-Za-z0-9_.:-]*\b", question)
+        known_noise = {"which", "what", "when", "where", "show", "compare", "node", "nodes",
+                       "link", "links", "pipe", "pipes", "conduit", "flow", "depth", "runoff",
+                       "the", "and", "for", "from", "with", "during", "model"}
+        ids = [x for x in ids if x.lower() not in known_noise][:8]
+
+        if any(k in q for k in ("input", "roughness", "diameter", "length", "invert", "elevation",
+                                "option", "rain gage", "timeseries", "control", "weir", "orifice",
+                                "pump", "storage", "infiltration", "subarea")):
+            section_terms = {
+                "roughness": "CONDUITS", "diameter": "XSECTIONS", "length": "CONDUITS",
+                "invert": "JUNCTIONS", "elevation": "JUNCTIONS", "control": "CONTROLS",
+                "pump": "PUMPS", "weir": "WEIRS", "orifice": "ORIFICES",
+                "storage": "STORAGE", "infiltration": "INFILTRATION", "subarea": "SUBAREAS",
+                "rain": "RAINGAGES", "option": "OPTIONS",
+            }
+            selected = {v for k, v in section_terms.items() if k in q}
+            if not selected:
+                selected = {"OPTIONS", "JUNCTIONS", "CONDUITS", "XSECTIONS", "SUBCATCHMENTS"}
+            names = ",".join(f"'{self._quoted(s)}'" for s in selected)
+            sql = f"""SELECT section_name, section_row_no, raw_text
+                      FROM model_input_lines
+                      WHERE section_name IN ({names}) AND is_comment=0 AND is_blank=0
+                      LIMIT {int(limit * 2)}"""
+            parts.append("MODEL INPUT\n" + pd.read_sql_query(sql, self.connection).to_csv(index=False))
+
+        if any(k in q for k in ("flood", "node", "manhole", "head", "inflow", "outflow")):
+            parts.append("NODE SUMMARY\n" + pd.read_sql_query(
+                f'''SELECT * FROM node_summary ORDER BY "Peak Flooding (m³/s)" DESC, "Depth Ratio" DESC LIMIT {int(limit)}''',
+                self.connection).to_csv(index=False))
+            for asset_id in ids:
+                df = pd.read_sql_query(
+                    """SELECT * FROM node_timeseries WHERE lower(node_id)=lower(?)
+                       ORDER BY time_index LIMIT ?""", self.connection, params=(asset_id, int(limit * 3)))
+                if not df.empty:
+                    parts.append(f"NODE TIMESERIES {asset_id}\n" + df.to_csv(index=False))
+
+        if any(k in q for k in ("conduit", "pipe", "link", "surcharge", "velocity", "capacity", "flow")):
+            parts.append("LINK SUMMARY\n" + pd.read_sql_query(
+                f'''SELECT * FROM link_summary ORDER BY "Depth Ratio" DESC, "Peak Flow (m³/s)" DESC LIMIT {int(limit)}''',
+                self.connection).to_csv(index=False))
+            for asset_id in ids:
+                df = pd.read_sql_query(
+                    """SELECT * FROM link_timeseries WHERE lower(link_id)=lower(?)
+                       ORDER BY time_index LIMIT ?""", self.connection, params=(asset_id, int(limit * 3)))
+                if not df.empty:
+                    parts.append(f"LINK TIMESERIES {asset_id}\n" + df.to_csv(index=False))
+
+        if any(k in q for k in ("subcatch", "runoff", "rain", "catchment", "hydrology", "infiltration")):
+            parts.append("SUBCATCHMENT SUMMARY\n" + pd.read_sql_query(
+                f'''SELECT * FROM subcatchment_summary ORDER BY "Peak Runoff (m³/s)" DESC LIMIT {int(limit)}''',
+                self.connection).to_csv(index=False))
+            for asset_id in ids:
+                df = pd.read_sql_query(
+                    """SELECT * FROM subcatchment_timeseries WHERE lower(subcatchment_id)=lower(?)
+                       ORDER BY time_index LIMIT ?""", self.connection, params=(asset_id, int(limit * 3)))
+                if not df.empty:
+                    parts.append(f"SUBCATCHMENT TIMESERIES {asset_id}\n" + df.to_csv(index=False))
+
+        if not parts:
+            for table in ("simulation_metadata", "node_summary", "link_summary", "subcatchment_summary"):
+                parts.append(table.upper() + "\n" + pd.read_sql_query(
+                    f"SELECT * FROM {table} LIMIT 10", self.connection).to_csv(index=False))
+
+        return "\n".join(parts)

rpt_reconciliation.py

@@ -0,0 +1,464 @@
+"""Deterministic reconciliation of app-extracted results against the SWMM .rpt file.
+
+Rationale
+---------
+The application builds its result tables (and therefore the Calgary velocity
+screening and the Table 9A depth-velocity assessment) from time series read
+through the OpenSWMM Python API inside the isolated worker. The engine's own
+``.rpt`` file independently reports per-timestep maxima in its Link Flow
+Summary and Node Depth Summary. On the Kincora Phase 2 reference model these
+two sources were found to disagree: pipe peak velocities differed by 5-12%,
+and peak velocities in irregular-transect (street) channels were understated
+by up to a factor of six in the API-derived tables, while the ``.rpt`` values
+matched the original consultant's SWMM 5.0.022 run almost exactly.
+
+This module parses the ``.rpt`` summaries and produces an auditable
+reconciliation table plus findings-register entries compatible with the
+Preliminary Design Assistant. It performs no simulation and calls no LLM.
+
+Notes and limitations
+---------------------
+* RPT object names are truncated to 20 characters by the engine. Where a
+  worker ID is longer than 20 characters, matching falls back to the
+  truncated prefix; ambiguous prefixes are reported as ``Unmatched`` rather
+  than guessed.
+* Only CONDUIT and CHANNEL rows carry velocity; OUTLET/DUMMY/PUMP/ORIFICE/
+  WEIR rows are reconciled on peak flow only.
+* The ``.rpt`` is treated as the authoritative cross-check because it is the
+  engine's own per-timestep statistic. A discrepancy does not by itself say
+  which value is "true"; it says the two extraction paths disagree and the
+  responsible engineer must not rely on the affected screening rows until
+  the cause is resolved.
+"""
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping, Sequence
+
+import pandas as pd
+
+_RPT_NAME_WIDTH = 20
+_VELOCITY_TYPES = {"CONDUIT", "CHANNEL"}
+_FLOW_ONLY_TYPES = {"OUTLET", "DUMMY", "PUMP", "ORIFICE", "WEIR"}
+
+
+@dataclass
+class ReconciliationTolerances:
+    """Screening tolerances for worker-vs-RPT deltas.
+
+    Values are relative unless stated. Absolute floors avoid flagging noise
+    on near-zero quantities (e.g. a 0.002 vs 0.004 m/s trickle).
+    """
+
+    velocity_review_pct: float = 5.0
+    velocity_discrepancy_pct: float = 15.0
+    velocity_abs_floor: float = 0.05          # m/s or ft/s
+    flow_review_pct: float = 2.0
+    flow_discrepancy_pct: float = 10.0
+    flow_abs_floor: float = 0.005             # model flow units
+    depth_review_pct: float = 5.0
+    depth_discrepancy_pct: float = 15.0
+    depth_abs_floor: float = 0.01             # m or ft
+    continuity_abs_review: float = 0.05       # absolute percentage points
+
+
+# ---------------------------------------------------------------------------
+# RPT parsing
+# ---------------------------------------------------------------------------
+
+def _section_lines(text: str, header: str) -> list[str]:
+    """Return the body lines of a starred RPT section, or an empty list."""
+    pattern = re.compile(
+        r"^\s*" + re.escape(header) + r"\s*$", re.MULTILINE)
+    match = pattern.search(text)
+    if not match:
+        return []
+    lines = text[match.end():].splitlines()
+    # The data table starts after the LAST dashed rule that precedes the
+    # first data row: title banner (****), blank, dashed rule, column
+    # headers, dashed rule, data rows, blank line.
+    last_rule = -1
+    for i, line in enumerate(lines):
+        stripped = line.strip()
+        if stripped and set(stripped) <= {"-"}:
+            last_rule = i
+            continue
+        if last_rule >= 0 and stripped and not stripped.startswith("*"):
+            # Column-header lines sit between the two rules; a line after a
+            # rule that is followed by another rule is a header, so only
+            # accept this as the data start if no further rule intervenes
+            # before the next blank line.
+            remainder = lines[i:]
+            if any(set(l.strip()) <= {"-"} and l.strip() for l in remainder[:4]):
+                continue  # still inside the header block
+            body: list[str] = []
+            for data_line in remainder:
+                if not data_line.strip():
+                    break
+                if data_line.strip().startswith("*"):
+                    break
+                body.append(data_line.rstrip("\n"))
+            return body
+    return []
+
+
+def _row_tokens(line: str) -> tuple[str, list[str]]:
+    """Split an RPT summary row into (object name, remaining tokens).
+
+    The name field is fixed-width (20 chars) and may itself contain no
+    spaces in SWMM inputs, but is sliced positionally to be safe.
+    """
+    name = line[:2 + _RPT_NAME_WIDTH].strip()
+    rest = line[2 + _RPT_NAME_WIDTH:].split()
+    return name, rest
+
+
+def _to_float(token: str) -> float | None:
+    try:
+        value = float(token)
+    except (TypeError, ValueError):
+        return None
+    return value if math.isfinite(value) else None
+
+
+def parse_link_flow_summary(rpt_path: str | Path) -> pd.DataFrame:
+    """Parse the Link Flow Summary into a DataFrame.
+
+    Columns: ``Link ID``, ``RPT Type``, ``RPT Peak |Flow|``,
+    ``RPT Time of Max``, ``RPT Peak |Velocity|``, ``RPT Max/Full Flow``,
+    ``RPT Max/Full Depth``. Velocity columns are NaN for flow-only types.
+    """
+    text = Path(rpt_path).read_text(encoding="utf-8", errors="replace")
+    rows: list[dict[str, Any]] = []
+    for line in _section_lines(text, "Link Flow Summary"):
+        name, tokens = _row_tokens(line)
+        if not name or len(tokens) < 2:
+            continue
+        rtype = tokens[0].upper()
+        record: dict[str, Any] = {
+            "Link ID": name, "RPT Type": rtype,
+            "RPT Peak |Flow|": _to_float(tokens[1]),
+            "RPT Time of Max": None, "RPT Peak |Velocity|": None,
+            "RPT Max/Full Flow": None, "RPT Max/Full Depth": None,
+        }
+        if len(tokens) >= 4:
+            record["RPT Time of Max"] = f"{tokens[2]} {tokens[3]}"
+        if rtype in _VELOCITY_TYPES and len(tokens) >= 7:
+            record["RPT Peak |Velocity|"] = _to_float(tokens[4])
+            record["RPT Max/Full Flow"] = _to_float(tokens[5])
+            record["RPT Max/Full Depth"] = _to_float(tokens[6])
+        rows.append(record)
+    return pd.DataFrame(rows)
+
+
+def parse_node_depth_summary(rpt_path: str | Path) -> pd.DataFrame:
+    """Parse the Node Depth Summary into a DataFrame."""
+    text = Path(rpt_path).read_text(encoding="utf-8", errors="replace")
+    rows: list[dict[str, Any]] = []
+    for line in _section_lines(text, "Node Depth Summary"):
+        name, tokens = _row_tokens(line)
+        if not name or len(tokens) < 4:
+            continue
+        rows.append({
+            "Node ID": name, "RPT Type": tokens[0].upper(),
+            "RPT Avg Depth": _to_float(tokens[1]),
+            "RPT Max Depth": _to_float(tokens[2]),
+            "RPT Max HGL": _to_float(tokens[3]),
+        })
+    return pd.DataFrame(rows)
+
+
+def parse_continuity_errors(rpt_path: str | Path) -> dict[str, float | None]:
+    """Return runoff and flow-routing continuity errors in PERCENT.
+
+    The first ``Continuity Error (%)`` line in the RPT belongs to the runoff
+    quantity block and the second to flow routing, matching the engine's
+    output order.
+    """
+    text = Path(rpt_path).read_text(encoding="utf-8", errors="replace")
+    values = [
+        _to_float(m.group(1))
+        for m in re.finditer(r"Continuity Error \(%\) \.+\s+(-?[\d.]+)", text)
+    ]
+    return {
+        "runoff_error_pct": values[0] if len(values) > 0 else None,
+        "flow_error_pct": values[1] if len(values) > 1 else None,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Reconciliation
+# ---------------------------------------------------------------------------
+
+def _match_rpt_row(object_id: str, rpt: pd.DataFrame, id_col: str) -> pd.Series | None:
+    exact = rpt[rpt[id_col].astype(str) == str(object_id)]
+    if len(exact) == 1:
+        return exact.iloc[0]
+    prefix = str(object_id)[:_RPT_NAME_WIDTH]
+    by_prefix = rpt[rpt[id_col].astype(str) == prefix]
+    if len(by_prefix) == 1:
+        return by_prefix.iloc[0]
+    return None
+
+
+def _classify(worker: float | None, reference: float | None,
+              review_pct: float, discrepancy_pct: float,
+              abs_floor: float) -> tuple[str, float | None]:
+    """Return (status, delta_pct). Deltas below the absolute floor pass."""
+    if worker is None or reference is None:
+        return "Unavailable", None
+    if abs(worker - reference) <= abs_floor:
+        return "OK", 0.0 if reference == 0 else round(
+            100.0 * (worker - reference) / abs(reference), 2)
+    if reference == 0:
+        return "Discrepancy", None
+    delta = 100.0 * (worker - reference) / abs(reference)
+    if abs(delta) <= review_pct:
+        return "OK", round(delta, 2)
+    if abs(delta) <= discrepancy_pct:
+        return "Review", round(delta, 2)
+    return "Discrepancy", round(delta, 2)
+
+
+def reconcile_links(
+    link_summary: pd.DataFrame,
+    rpt_path: str | Path,
+    tolerances: ReconciliationTolerances | None = None,
+) -> pd.DataFrame:
+    """Reconcile the app's link table against the RPT Link Flow Summary.
+
+    ``link_summary`` must contain ``Link ID`` plus any of the recognised
+    worker columns (``Peak Flow (...)``, ``Peak Velocity (...)``,
+    ``Depth Ratio``). Unrecognised columns are ignored so unit-suffix
+    variations (m³/s vs cfs, m/s vs ft/s) are handled transparently.
+    """
+    tol = tolerances or ReconciliationTolerances()
+    if link_summary is None or link_summary.empty:
+        return pd.DataFrame()
+    rpt = parse_link_flow_summary(rpt_path)
+    if rpt.empty:
+        return pd.DataFrame()
+
+    flow_col = next((c for c in link_summary.columns if c.startswith("Peak Flow (")), None)
+    vel_col = next((c for c in link_summary.columns if c.startswith("Peak Velocity (")), None)
+    depth_ratio_col = "Depth Ratio" if "Depth Ratio" in link_summary.columns else None
+
+    rows: list[dict[str, Any]] = []
+    for _, record in link_summary.iterrows():
+        link_id = str(record["Link ID"])
+        matched = _match_rpt_row(link_id, rpt, "Link ID")
+        if matched is None:
+            rows.append({"Link ID": link_id, "RPT Type": None,
+                         "Overall Status": "Unmatched"})
+            continue
+        entry: dict[str, Any] = {"Link ID": link_id, "RPT Type": matched["RPT Type"]}
+        statuses: list[str] = []
+
+        worker_flow = _to_float(record.get(flow_col)) if flow_col else None
+        entry["Worker Peak Flow"] = worker_flow
+        entry["RPT Peak Flow"] = matched["RPT Peak |Flow|"]
+        status, delta = _classify(worker_flow, matched["RPT Peak |Flow|"],
+                                  tol.flow_review_pct, tol.flow_discrepancy_pct,
+                                  tol.flow_abs_floor)
+        entry["Flow Delta (%)"], entry["Flow Status"] = delta, status
+        statuses.append(status)
+
+        if matched["RPT Type"] in _VELOCITY_TYPES:
+            worker_vel = _to_float(record.get(vel_col)) if vel_col else None
+            entry["Worker Peak Velocity"] = worker_vel
+            entry["RPT Peak Velocity"] = matched["RPT Peak |Velocity|"]
+            status, delta = _classify(worker_vel, matched["RPT Peak |Velocity|"],
+                                      tol.velocity_review_pct,
+                                      tol.velocity_discrepancy_pct,
+                                      tol.velocity_abs_floor)
+            entry["Velocity Delta (%)"], entry["Velocity Status"] = delta, status
+            statuses.append(status)
+
+            if depth_ratio_col is not None:
+                worker_ratio = _to_float(record.get(depth_ratio_col))
+                entry["Worker Depth Ratio"] = worker_ratio
+                entry["RPT Max/Full Depth"] = matched["RPT Max/Full Depth"]
+                status, delta = _classify(worker_ratio, matched["RPT Max/Full Depth"],
+                                          tol.depth_review_pct,
+                                          tol.depth_discrepancy_pct,
+                                          tol.depth_abs_floor)
+                entry["Depth Ratio Delta (%)"], entry["Depth Ratio Status"] = delta, status
+                statuses.append(status)
+
+        order = {"Discrepancy": 3, "Unmatched": 3, "Review": 2, "Unavailable": 1, "OK": 0}
+        entry["Overall Status"] = max(statuses, key=lambda s: order.get(s, 0)) if statuses else "Unavailable"
+        rows.append(entry)
+    return pd.DataFrame(rows)
+
+
+def reconcile_nodes(
+    node_summary: pd.DataFrame,
+    rpt_path: str | Path,
+    tolerances: ReconciliationTolerances | None = None,
+) -> pd.DataFrame:
+    """Reconcile app node peak depths against the RPT Node Depth Summary."""
+    tol = tolerances or ReconciliationTolerances()
+    if node_summary is None or node_summary.empty:
+        return pd.DataFrame()
+    rpt = parse_node_depth_summary(rpt_path)
+    if rpt.empty:
+        return pd.DataFrame()
+    depth_col = next((c for c in node_summary.columns if c.startswith("Peak Depth (")), None)
+    if depth_col is None:
+        return pd.DataFrame()
+    rows: list[dict[str, Any]] = []
+    for _, record in node_summary.iterrows():
+        node_id = str(record["Node ID"])
+        matched = _match_rpt_row(node_id, rpt, "Node ID")
+        if matched is None:
+            rows.append({"Node ID": node_id, "Overall Status": "Unmatched"})
+            continue
+        worker_depth = _to_float(record.get(depth_col))
+        status, delta = _classify(worker_depth, matched["RPT Max Depth"],
+                                  tol.depth_review_pct, tol.depth_discrepancy_pct,
+                                  tol.depth_abs_floor)
+        rows.append({
+            "Node ID": node_id, "RPT Type": matched["RPT Type"],
+            "Worker Peak Depth": worker_depth,
+            "RPT Max Depth": matched["RPT Max Depth"],
+            "Depth Delta (%)": delta, "Overall Status": status,
+        })
+    return pd.DataFrame(rows)
+
+
+def reconcile_continuity(
+    simulation_metadata: Mapping[str, Any],
+    rpt_path: str | Path,
+    tolerances: ReconciliationTolerances | None = None,
+) -> pd.DataFrame:
+    """Reconcile worker continuity errors against the RPT, in percent.
+
+    Detects the fraction-vs-percent inconsistency: if the worker value is
+    approximately the RPT value divided by 100, the row is marked
+    ``Unit inconsistency (fraction vs percent)`` rather than a numeric
+    discrepancy, since the underlying simulation agrees.
+    """
+    tol = tolerances or ReconciliationTolerances()
+    rpt_values = parse_continuity_errors(rpt_path)
+    pairs = [
+        ("Runoff continuity", simulation_metadata.get("runoff_error"),
+         rpt_values["runoff_error_pct"]),
+        ("Flow routing continuity", simulation_metadata.get("flow_error"),
+         rpt_values["flow_error_pct"]),
+    ]
+    rows: list[dict[str, Any]] = []
+    for label, worker, reference in pairs:
+        worker_f, ref_f = _to_float(worker), _to_float(reference)
+        if worker_f is None or ref_f is None:
+            status = "Unavailable"
+        elif abs(worker_f - ref_f) <= tol.continuity_abs_review:
+            status = "OK"
+        elif abs(worker_f * 100.0 - ref_f) <= tol.continuity_abs_review:
+            status = "Unit inconsistency (fraction vs percent)"
+        else:
+            status = "Discrepancy"
+        rows.append({"Quantity": label, "Worker Value": worker_f,
+                     "RPT Value (%)": ref_f, "Status": status})
+    return pd.DataFrame(rows)
+
+
+# ---------------------------------------------------------------------------
+# Findings-register integration
+# ---------------------------------------------------------------------------
+
+def reconciliation_findings(
+    link_recon: pd.DataFrame,
+    node_recon: pd.DataFrame | None = None,
+    continuity_recon: pd.DataFrame | None = None,
+    start_index: int = 1,
+) -> list[dict[str, Any]]:
+    """Convert reconciliation discrepancies into PDA-style finding dicts.
+
+    Only ``Review``, ``Discrepancy``, ``Unmatched`` and unit-inconsistency
+    rows generate findings. Severity: Discrepancy/Unmatched -> High,
+    Review -> Medium. These findings carry no proposed model edit; the
+    recommended action is to resolve the extraction path before relying on
+    the affected screening tables.
+    """
+    findings: list[dict[str, Any]] = []
+    counter = start_index
+
+    def add(severity: str, object_type: str, object_id: str, basis: str) -> None:
+        nonlocal counter
+        findings.append({
+            "finding_id": f"RPT-{counter:03d}",
+            "category": "Result reconciliation",
+            "severity": severity,
+            "finding_type": "Worker/RPT disagreement",
+            "object_type": object_type,
+            "object_id": object_id,
+            "rule_id": "QA-RECON-001",
+            "criterion_status": "Deterministic cross-check",
+            "deterministic_basis": basis,
+            "recommended_action": (
+                "Do not rely on the affected screening rows until the API "
+                "extraction and the engine report file agree. Verify units, "
+                "extraction property, and sampling of the worker time series."
+            ),
+            "engineer_decision": "Defer",
+            "resolution_status": "Open",
+        })
+        counter += 1
+
+    if link_recon is not None and not link_recon.empty:
+        for _, row in link_recon.iterrows():
+            status = row.get("Overall Status")
+            if status in {"OK", "Unavailable", None}:
+                continue
+            severity = "High" if status in {"Discrepancy", "Unmatched"} else "Medium"
+            parts = []
+            for label, w, r, d in [
+                ("velocity", row.get("Worker Peak Velocity"), row.get("RPT Peak Velocity"), row.get("Velocity Delta (%)")),
+                ("flow", row.get("Worker Peak Flow"), row.get("RPT Peak Flow"), row.get("Flow Delta (%)")),
+                ("depth ratio", row.get("Worker Depth Ratio"), row.get("RPT Max/Full Depth"), row.get("Depth Ratio Delta (%)")),
+            ]:
+                if d is not None and not (isinstance(d, float) and math.isnan(d)) and abs(d) > 5.0:
+                    parts.append(f"peak {label} worker={w} vs rpt={r} ({d:+.1f}%)")
+            basis = (f"Link '{row['Link ID']}': " + "; ".join(parts)) if parts else (
+                f"Link '{row['Link ID']}': status {status}.")
+            add(severity, "LINK", str(row["Link ID"]), basis)
+
+    if node_recon is not None and not node_recon.empty:
+        for _, row in node_recon.iterrows():
+            if row.get("Overall Status") in {"Review", "Discrepancy", "Unmatched"}:
+                severity = "Medium" if row["Overall Status"] == "Review" else "High"
+                add(severity, "NODE", str(row["Node ID"]),
+                    f"Node '{row['Node ID']}': peak depth worker="
+                    f"{row.get('Worker Peak Depth')} vs rpt={row.get('RPT Max Depth')}"
+                    f" ({row.get('Depth Delta (%)')}%).")
+
+    if continuity_recon is not None and not continuity_recon.empty:
+        for _, row in continuity_recon.iterrows():
+            if row["Status"] not in {"OK", "Unavailable"}:
+                add("Medium", "MODEL", "MODEL",
+                    f"{row['Quantity']}: worker={row['Worker Value']} vs "
+                    f"rpt={row['RPT Value (%)']}%. {row['Status']}.")
+    return findings
+
+
+def reconciliation_summary(link_recon: pd.DataFrame) -> dict[str, Any]:
+    """Compact machine-readable summary for the report package metadata."""
+    if link_recon is None or link_recon.empty:
+        return {"links_checked": 0, "ok": 0, "review": 0,
+                "discrepancy": 0, "unmatched": 0, "verdict": "Not performed"}
+    counts = link_recon["Overall Status"].value_counts().to_dict()
+    discrepancies = counts.get("Discrepancy", 0) + counts.get("Unmatched", 0)
+    verdict = ("Pass - worker tables agree with engine report" if discrepancies == 0
+               and counts.get("Review", 0) == 0 else
+               "Review required - worker tables disagree with engine report")
+    return {
+        "links_checked": int(len(link_recon)),
+        "ok": int(counts.get("OK", 0)),
+        "review": int(counts.get("Review", 0)),
+        "discrepancy": int(counts.get("Discrepancy", 0)),
+        "unmatched": int(counts.get("Unmatched", 0)),
+        "verdict": verdict,
+    }

scenario_manager.py

@@ -0,0 +1,600 @@
+"""Preliminary SWMM scenario generation, execution, and comparison.
+
+Rev22.1 intentionally treats generated storms and parameter changes as preliminary
+engineering scenarios.  It does not represent generated rainfall as an approved
+City of Calgary design storm unless the user supplies and verifies the source.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from datetime import datetime, timedelta
+from io import BytesIO
+from pathlib import Path
+from typing import Any, Iterable
+import csv
+import hashlib
+import json
+import math
+import re
+import tempfile
+import zipfile
+
+import pandas as pd
+
+from swmm_core import run_swmm
+
+
+@dataclass
+class StormDefinition:
+    mode: str = "existing_model"
+    name: str = "Existing model rainfall"
+    return_period: str = "Model-defined"
+    duration_minutes: int = 60
+    interval_minutes: int = 5
+    total_depth_mm: float | None = None
+    peak_position: float = 0.40
+    source_status: str = "Existing model input"
+    source_reference: str = ""
+    selected_timeseries: str = ""
+
+
+@dataclass
+class ScenarioChange:
+    object_type: str
+    object_id: str
+    parameter: str
+    old_value: Any = None
+    new_value: Any = None
+    status: str = "requested"
+    note: str = ""
+
+
+@dataclass
+class ScenarioDefinition:
+    scenario_id: str
+    scenario_name: str
+    description: str = ""
+    storm: StormDefinition = field(default_factory=StormDefinition)
+    imperviousness_overrides: dict[str, float] = field(default_factory=dict)
+    conduit_diameter_overrides: dict[str, float] = field(default_factory=dict)
+    conduit_roughness_overrides: dict[str, float] = field(default_factory=dict)
+    storage_depth_overrides: dict[str, float] = field(default_factory=dict)
+    simulation_hours: float | None = None
+    review_status: str = "Preliminary"
+    created_at: str = field(default_factory=lambda: datetime.now().isoformat(timespec="seconds"))
+
+
+def safe_scenario_id(value: str) -> str:
+    cleaned = re.sub(r"[^A-Za-z0-9_-]+", "_", value.strip()).strip("_")
+    return cleaned[:64] or "scenario"
+
+
+def _split_sections(text: str) -> tuple[list[str], dict[str, list[str]]]:
+    preamble: list[str] = []
+    sections: dict[str, list[str]] = {}
+    current: str | None = None
+    for raw in text.splitlines():
+        m = re.match(r"^\s*\[([^]]+)\]\s*$", raw)
+        if m:
+            current = m.group(1).upper()
+            sections.setdefault(current, [])
+        elif current is None:
+            preamble.append(raw)
+        else:
+            sections[current].append(raw)
+    return preamble, sections
+
+
+def _join_sections(preamble: list[str], sections: dict[str, list[str]]) -> str:
+    out = list(preamble)
+    if out and out[-1].strip():
+        out.append("")
+    for name, lines in sections.items():
+        out.append(f"[{name}]")
+        out.extend(lines)
+        out.append("")
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _data_tokens(line: str) -> tuple[list[str], str] | None:
+    body, sep, comment = line.partition(";")
+    if not body.strip() or body.lstrip().startswith(";"):
+        return None
+    return body.split(), (sep + comment if sep else "")
+
+
+def _replace_tokens(line: str, tokens: list[str], comment: str) -> str:
+    return "  ".join(str(x) for x in tokens) + ((" " + comment) if comment else "")
+
+
+def _update_named_row(lines: list[str], object_id: str, token_index: int, new_value: Any) -> tuple[list[str], Any, bool]:
+    updated: list[str] = []
+    old = None
+    changed = False
+    for line in lines:
+        parsed = _data_tokens(line)
+        if parsed and parsed[0] and parsed[0][0].casefold() == object_id.casefold():
+            tokens, comment = parsed
+            if len(tokens) > token_index:
+                old = tokens[token_index]
+                tokens[token_index] = f"{new_value:g}" if isinstance(new_value, float) else str(new_value)
+                line = _replace_tokens(line, tokens, comment)
+                changed = True
+        updated.append(line)
+    return updated, old, changed
+
+
+def _set_option(lines: list[str], key: str, value: str) -> list[str]:
+    result: list[str] = []
+    found = False
+    for line in lines:
+        parsed = _data_tokens(line)
+        if parsed and parsed[0][0].upper() == key.upper():
+            tokens, comment = parsed
+            tokens = [key, value]
+            line = _replace_tokens(line, tokens, comment)
+            found = True
+        result.append(line)
+    if not found:
+        result.append(f"{key:<20} {value}")
+    return result
+
+
+def chicago_style_incremental_depths(total_depth_mm: float, duration_minutes: int, interval_minutes: int, peak_position: float = 0.4) -> list[float]:
+    """Create a preliminary, mass-conserving Chicago-style alternating-block storm.
+
+    This is deliberately labelled preliminary. It is useful for scenario workflow
+    testing, but it is not a replacement for a verified municipal IDF-based storm.
+    """
+    n = max(1, int(math.ceil(duration_minutes / interval_minutes)))
+    # Smooth synthetic intensity pattern with a sharp peak and positive tails.
+    ranks = list(range(1, n + 1))
+    weights = [1.0 / (r ** 0.72) for r in ranks]
+    scale = total_depth_mm / sum(weights)
+    blocks = [w * scale for w in weights]
+    peak_idx = min(n - 1, max(0, round((n - 1) * peak_position)))
+    order = [peak_idx]
+    offset = 1
+    while len(order) < n:
+        right = peak_idx + offset
+        left = peak_idx - offset
+        if right < n:
+            order.append(right)
+        if left >= 0 and len(order) < n:
+            order.append(left)
+        offset += 1
+    result = [0.0] * n
+    for block, idx in zip(sorted(blocks, reverse=True), order):
+        result[idx] = block
+    # exact conservation after floating-point arithmetic
+    result[-1] += total_depth_mm - sum(result)
+    return result
+
+
+def _inject_preliminary_storm(sections: dict[str, list[str]], storm: StormDefinition, scenario_id: str) -> None:
+    if storm.total_depth_mm is None:
+        raise ValueError("Total storm depth is required for a generated preliminary storm.")
+    interval = max(1, int(storm.interval_minutes))
+    duration = max(interval, int(storm.duration_minutes))
+    series_id = f"SCN_{safe_scenario_id(scenario_id)}_RAIN"
+    depths = chicago_style_incremental_depths(float(storm.total_depth_mm), duration, interval, float(storm.peak_position))
+
+    # Replace/add the time series. Values are interval rainfall depths; the gage is VOLUME.
+    ts_lines = [ln for ln in sections.get("TIMESERIES", []) if not (_data_tokens(ln) and _data_tokens(ln)[0][0].casefold() == series_id.casefold())]
+    start = datetime(2000, 1, 1, 0, 0)
+    ts_lines.append(f"; Preliminary scenario storm: {storm.name}; source status: {storm.source_status}")
+    for i, depth in enumerate(depths):
+        t = start + timedelta(minutes=i * interval)
+        ts_lines.append(f"{series_id:<24} {t.strftime('%m/%d/%Y')} {t.strftime('%H:%M')} {depth:.6f}")
+    sections["TIMESERIES"] = ts_lines
+
+    # Point all model rain gages to the generated series while retaining their IDs.
+    rg_lines: list[str] = []
+    for line in sections.get("RAINGAGES", []):
+        parsed = _data_tokens(line)
+        if parsed:
+            tokens, comment = parsed
+            if len(tokens) >= 1:
+                gage_id = tokens[0]
+                tokens = [gage_id, "VOLUME", f"0:{interval:02d}", "1.0", "TIMESERIES", series_id]
+                line = _replace_tokens(line, tokens, comment)
+        rg_lines.append(line)
+    sections["RAINGAGES"] = rg_lines
+
+
+
+def extract_rainfall_event_catalog(text: str) -> list[dict[str, str]]:
+    """Return rainfall time-series available inside an INP model.
+
+    SWMM models often retain several design-event series (for example 1:5 and
+    1:100) while only one series is referenced by the active rain gage.
+    """
+    _, sections = _split_sections(text)
+    active = set()
+    gages = {}
+    for line in sections.get("RAINGAGES", []):
+        parsed = _data_tokens(line)
+        if not parsed:
+            continue
+        tokens, _ = parsed
+        if len(tokens) >= 6 and tokens[4].upper() == "TIMESERIES":
+            gages[tokens[0]] = tokens[5]
+            active.add(tokens[5].casefold())
+    ids=[]
+    seen=set()
+    for line in sections.get("TIMESERIES", []):
+        parsed=_data_tokens(line)
+        if not parsed:
+            continue
+        tokens,_=parsed
+        if not tokens:
+            continue
+        sid=tokens[0]
+        if sid.casefold() in seen:
+            continue
+        seen.add(sid.casefold())
+        ids.append({"event_id":sid,"active":"Yes" if sid.casefold() in active else "No","used_by":", ".join(k for k,v in gages.items() if v.casefold()==sid.casefold())})
+    return ids
+
+
+def _select_existing_timeseries(sections: dict[str, list[str]], series_id: str) -> None:
+    """Point every TIMESERIES-based rain gage to an existing model series."""
+    available={x["event_id"].casefold():x["event_id"] for x in extract_rainfall_event_catalog(_join_sections([], sections))}
+    if series_id.casefold() not in available:
+        raise ValueError(f"Rainfall time series {series_id!r} was not found in the selected model.")
+    canonical=available[series_id.casefold()]
+    new=[]
+    changed=0
+    for line in sections.get("RAINGAGES", []):
+        parsed=_data_tokens(line)
+        if parsed:
+            tokens,comment=parsed
+            if len(tokens)>=6 and tokens[4].upper()=="TIMESERIES":
+                tokens[5]=canonical
+                line=_replace_tokens(line,tokens,comment)
+                changed+=1
+        new.append(line)
+    if changed==0:
+        raise ValueError("The selected model has no TIMESERIES-based rain gage to assign.")
+    sections["RAINGAGES"]=new
+
+def build_scenario_inp(base_inp: str | Path, scenario: ScenarioDefinition, output_path: str | Path) -> dict[str, Any]:
+    base = Path(base_inp)
+    text = base.read_text(encoding="utf-8", errors="ignore")
+    preamble, sections = _split_sections(text)
+    change_log: list[ScenarioChange] = []
+
+    if scenario.storm.mode == "generated_preliminary":
+        _inject_preliminary_storm(sections, scenario.storm, scenario.scenario_id)
+        change_log.append(ScenarioChange("storm", scenario.storm.name, "rainfall_series", None, scenario.storm.total_depth_mm, "applied", scenario.storm.source_status))
+    elif scenario.storm.mode == "existing_timeseries" and scenario.storm.selected_timeseries:
+        _select_existing_timeseries(sections, scenario.storm.selected_timeseries)
+        change_log.append(ScenarioChange("storm", scenario.storm.selected_timeseries, "active_timeseries", None, scenario.storm.selected_timeseries, "applied", "Existing series selected from model"))
+
+    if scenario.simulation_hours and scenario.simulation_hours > 0:
+        start = datetime(2000, 1, 1, 0, 0)
+        end = start + timedelta(hours=float(scenario.simulation_hours))
+        opts = sections.setdefault("OPTIONS", [])
+        for key, val in [
+            ("START_DATE", start.strftime("%m/%d/%Y")),
+            ("START_TIME", start.strftime("%H:%M:%S")),
+            ("REPORT_START_DATE", start.strftime("%m/%d/%Y")),
+            ("REPORT_START_TIME", start.strftime("%H:%M:%S")),
+            ("END_DATE", end.strftime("%m/%d/%Y")),
+            ("END_TIME", end.strftime("%H:%M:%S")),
+        ]:
+            opts = _set_option(opts, key, val)
+        sections["OPTIONS"] = opts
+
+    # SWMM [SUBCATCHMENTS]: Name RainGage Outlet Area %Imperv Width %Slope ...
+    for oid, value in scenario.imperviousness_overrides.items():
+        lines, old, ok = _update_named_row(sections.get("SUBCATCHMENTS", []), oid, 4, float(value))
+        sections["SUBCATCHMENTS"] = lines
+        change_log.append(ScenarioChange("subcatchment", oid, "imperviousness_percent", old, value, "applied" if ok else "not_found"))
+
+    # SWMM [XSECTIONS]: Link Shape Geom1 ... ; circular Geom1 is diameter.
+    for oid, value in scenario.conduit_diameter_overrides.items():
+        lines, old, ok = _update_named_row(sections.get("XSECTIONS", []), oid, 2, float(value))
+        sections["XSECTIONS"] = lines
+        change_log.append(ScenarioChange("link", oid, "diameter_or_geom1", old, value, "applied" if ok else "not_found"))
+
+    # SWMM [CONDUITS]: Name From To Length Roughness ...
+    for oid, value in scenario.conduit_roughness_overrides.items():
+        lines, old, ok = _update_named_row(sections.get("CONDUITS", []), oid, 4, float(value))
+        sections["CONDUITS"] = lines
+        change_log.append(ScenarioChange("conduit", oid, "manning_n", old, value, "applied" if ok else "not_found"))
+
+    # SWMM [STORAGE]: Name Elev MaxDepth InitDepth Shape ...
+    for oid, value in scenario.storage_depth_overrides.items():
+        lines, old, ok = _update_named_row(sections.get("STORAGE", []), oid, 2, float(value))
+        sections["STORAGE"] = lines
+        change_log.append(ScenarioChange("storage", oid, "maximum_depth", old, value, "applied" if ok else "not_found"))
+
+    output = Path(output_path)
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(_join_sections(preamble, sections), encoding="utf-8")
+    return {
+        "scenario": asdict(scenario),
+        "changes": [asdict(x) for x in change_log],
+        "input_sha256": hashlib.sha256(output.read_bytes()).hexdigest(),
+        "output_path": str(output),
+    }
+
+
+def summarize_scenario_results(results: dict[str, Any], scenario: ScenarioDefinition) -> dict[str, Any]:
+    node_ts = results.get("node_ts", {}) or {}
+    link_ts = results.get("link_ts", {}) or {}
+    sub_ts = results.get("sub_ts", {}) or {}
+    meta = results.get("metadata", {}) or {}
+
+    max_flood = max((max(v.get("flooding", []) or [0.0]) for v in node_ts.values()), default=0.0)
+    total_peak_inflow = max((max(v.get("inflow", []) or [0.0]) for v in node_ts.values()), default=0.0)
+    max_velocity = 0.0
+    max_velocity_link = ""
+    max_depth_ratio = 0.0
+    max_depth_ratio_link = ""
+    peak_link_flow = 0.0
+    for lid, values in link_ts.items():
+        vel = max((abs(float(x)) for x in values.get("velocity", []) or [0.0]), default=0.0)
+        if vel > max_velocity:
+            max_velocity, max_velocity_link = vel, lid
+        depth = max((float(x) for x in values.get("depth", []) or [0.0]), default=0.0)
+        diameter = float(values.get("diameter", 0.0) or 0.0)
+        ratio = depth / diameter if diameter > 0 else 0.0
+        if ratio > max_depth_ratio:
+            max_depth_ratio, max_depth_ratio_link = ratio, lid
+        peak_link_flow = max(peak_link_flow, max((abs(float(x)) for x in values.get("flow", []) or [0.0]), default=0.0))
+    peak_runoff = max((max(v.get("runoff", []) or [0.0]) for v in sub_ts.values()), default=0.0)
+    return {
+        "Scenario ID": scenario.scenario_id,
+        "Scenario Name": scenario.scenario_name,
+        "Storm": scenario.storm.name,
+        "Storm Status": scenario.storm.source_status,
+        "Simulation Status": "Completed",
+        "Runoff Error (%)": float(meta.get("runoff_error", 0.0) or 0.0),
+        "Flow Error (%)": float(meta.get("flow_error", 0.0) or 0.0),
+        "Peak Subcatchment Runoff": peak_runoff,
+        "Peak Link Flow": peak_link_flow,
+        "Maximum Link Velocity": max_velocity,
+        "Velocity Link": max_velocity_link,
+        "Maximum Modelled Depth Ratio": max_depth_ratio,
+        "Depth-Ratio Link": max_depth_ratio_link,
+        "Maximum Node Flooding": max_flood,
+        "Maximum Node Inflow": total_peak_inflow,
+        "Review Status": scenario.review_status,
+        "Model Role": "Scenario",
+    }
+
+
+def run_scenario(base_inp: str | Path, scenario: ScenarioDefinition, work_dir: str | Path | None = None) -> dict[str, Any]:
+    root = Path(work_dir) if work_dir else Path(tempfile.mkdtemp(prefix="swmm_scenario_"))
+    root.mkdir(parents=True, exist_ok=True)
+    sid = safe_scenario_id(scenario.scenario_id)
+    inp = root / f"{sid}.inp"
+    manifest = build_scenario_inp(base_inp, scenario, inp)
+    rpt = root / f"{sid}.rpt"
+    out = root / f"{sid}.out"
+    results = run_swmm(inp, rpt, out)
+    # Attach final-input geometry to result records so scenario depth-ratio
+    # summaries are computed from the scenario model rather than shown as zero.
+    final_sections = {}
+    try:
+        _, final_sections = _split_sections(inp.read_text(encoding="utf-8", errors="ignore"))
+        diameters = {}
+        for line in final_sections.get("XSECTIONS", []):
+            parsed = _data_tokens(line)
+            if parsed:
+                tokens, _ = parsed
+                if len(tokens) >= 3:
+                    try:
+                        diameters[tokens[0]] = float(tokens[2])
+                    except ValueError:
+                        pass
+        for lid, values in (results.get("link_ts", {}) or {}).items():
+            if lid in diameters:
+                values["diameter"] = diameters[lid]
+    except Exception:
+        pass
+    summary = summarize_scenario_results(results, scenario)
+    summary["Conduit Count"] = len(final_sections.get("CONDUITS", []) or [])
+    storage_ids = [(_data_tokens(line)[0][0] if _data_tokens(line) else "") for line in (final_sections.get("STORAGE", []) or [])]
+    storage_ids = [x for x in storage_ids if x]
+    storage_depth = 0.0
+    storage_volume = 0.0
+    storage_node = ""
+    for node_id in storage_ids:
+        values = (results.get("node_ts", {}) or {}).get(node_id, {})
+        depth = max((float(x) for x in values.get("depth", []) or [0.0]), default=0.0)
+        volume = max((float(x) for x in values.get("volume", []) or [0.0]), default=0.0)
+        if depth > storage_depth:
+            storage_depth, storage_node = depth, node_id
+        storage_volume = max(storage_volume, volume)
+    summary["Maximum Storage Depth"] = storage_depth if storage_ids else None
+    summary["Maximum Storage Volume"] = storage_volume if storage_ids else None
+    summary["Controlling Storage Node"] = storage_node if storage_ids else ""
+    manifest.update({
+        "report_path": str(rpt),
+        "output_path": str(out),
+        "report_sha256": hashlib.sha256(rpt.read_bytes()).hexdigest() if rpt.exists() else None,
+        "summary": summary,
+    })
+    return {"definition": asdict(scenario), "manifest": manifest, "results": results, "summary": summary, "files": {"inp": inp.read_bytes(), "rpt": rpt.read_bytes() if rpt.exists() else b"", "out": out.read_bytes() if out.exists() else b""}}
+
+
+
+def base_model_record(results: dict[str, Any], *, scenario_name: str = "Base Model", review_status: str = "Reference model", source_name: str = "Base Model") -> dict[str, Any]:
+    """Create a comparison record for the currently simulated base model."""
+    definition = ScenarioDefinition(
+        scenario_id="BASE_MODEL",
+        scenario_name=scenario_name,
+        description="Current uploaded and simulated reference model.",
+        storm=StormDefinition(
+            mode="existing_model",
+            name="Existing model rainfall",
+            return_period="Model-defined",
+            source_status="Base model input",
+        ),
+        review_status=review_status,
+    )
+    summary = summarize_scenario_results(results or {}, definition)
+    summary["Model Role"] = "Base"
+    summary["Source Model"] = source_name
+    summary["Input Changed"] = "Reference"
+    summary["Input SHA256 (short)"] = ""
+    summary["Conduit Count"] = sum(1 for values in ((results or {}).get("link_ts", {}) or {}).values() if float(values.get("diameter", 0) or 0) > 0)
+    return {
+        "definition": asdict(definition),
+        "manifest": {"summary": summary, "model_role": "Base", "source": "Current uploaded model"},
+        "results": results or {},
+        "summary": summary,
+        "files": {},
+    }
+
+
+def comparison_with_base(base_results: dict[str, Any] | None, records: Iterable[dict[str, Any]], *, base_name: str = "Base Model") -> pd.DataFrame:
+    """Return one comparison table containing the base model and scenario records."""
+    combined: list[dict[str, Any]] = []
+    if base_results:
+        combined.append(base_model_record(base_results, scenario_name=base_name, source_name=base_name))
+    combined.extend(list(records))
+    df = comparison_dataframe(combined)
+    if not df.empty and "Model Role" not in df.columns:
+        df.insert(0, "Model Role", ["Base" if str(v) == "BASE_MODEL" else "Scenario" for v in df.get("Scenario ID", [])])
+    elif not df.empty:
+        df["Model Role"] = df["Model Role"].fillna("Scenario")
+    if not df.empty:
+        base_rows = df[df["Scenario ID"].astype(str) == "BASE_MODEL"]
+        if not base_rows.empty:
+            b = base_rows.iloc[0]
+            metric_cols = ["Peak Subcatchment Runoff", "Peak Link Flow", "Maximum Link Velocity", "Maximum Modelled Depth Ratio", "Maximum Node Flooding", "Maximum Node Inflow"]
+            flags = []
+            for _, row in df.iterrows():
+                if str(row.get("Scenario ID")) == "BASE_MODEL":
+                    flags.append("Reference")
+                    continue
+                changed = False
+                for col in metric_cols:
+                    try:
+                        if abs(float(row.get(col, 0) or 0) - float(b.get(col, 0) or 0)) > 1e-8:
+                            changed = True
+                            break
+                    except Exception:
+                        pass
+                flags.append("Different" if changed else "No summary-level difference")
+            df["Hydraulic Difference"] = flags
+    return df
+
+
+def deterministic_comparison_analysis(comparison: pd.DataFrame) -> str:
+    """Create a conservative, deterministic scenario-comparison narrative."""
+    if comparison is None or comparison.empty:
+        return "No scenario comparison data are available."
+    df = comparison.copy()
+    base = df[df["Scenario ID"].astype(str) == "BASE_MODEL"]
+    if base.empty:
+        base = df.iloc[[0]]
+    b = base.iloc[0]
+    metrics = [
+        ("Peak Subcatchment Runoff", "peak subcatchment runoff"),
+        ("Peak Link Flow", "peak link flow"),
+        ("Maximum Link Velocity", "maximum link velocity"),
+        ("Maximum Modelled Depth Ratio", "maximum modelled depth ratio"),
+        ("Maximum Node Flooding", "maximum node flooding"),
+        ("Maximum Node Inflow", "maximum node inflow"),
+        ("Maximum Storage Depth", "maximum storage depth"),
+        ("Maximum Storage Volume", "maximum storage volume"),
+    ]
+    lines = [
+        "The comparison uses the current uploaded model as the reference case. Differences are calculated from deterministic simulation summaries and are intended for preliminary engineering review.",
+        "",
+    ]
+    # Guard: if every base metric is zero while at least one scenario is
+    # non-zero, the base record almost certainly did not carry usable
+    # results (e.g. it was built from an empty or malformed results dict).
+    # Deltas quoted against a zeroed base are misleading, so say so
+    # explicitly instead of presenting "+X relative to base" as fact.
+    def _metric_value(record, col):
+        try:
+            return abs(float(record.get(col, 0) or 0))
+        except Exception:
+            return 0.0
+    base_all_zero = all(_metric_value(b, col) <= 1e-12 for col, _ in metrics)
+    any_scenario_nonzero = any(
+        _metric_value(row, col) > 1e-12
+        for _, row in df[df["Scenario ID"].astype(str) != str(b.get("Scenario ID", "BASE_MODEL"))].iterrows()
+        for col, _ in metrics
+    )
+    if base_all_zero and any_scenario_nonzero:
+        lines.insert(0, (
+            "CAUTION: All reference-case metrics are zero while scenario results are non-zero. "
+            "The base record does not appear to contain usable simulation results; differences below "
+            "are NOT valid deltas against the uploaded model. Re-simulate or rebuild the base record "
+            "before relying on this comparison."
+        ))
+        lines.insert(1, "")
+    scenarios = df[df["Scenario ID"].astype(str) != str(b.get("Scenario ID", "BASE_MODEL"))]
+    if scenarios.empty:
+        lines.append("No alternative scenario has been completed.")
+        return "\n".join(lines)
+    for _, row in scenarios.iterrows():
+        sid = row.get("Scenario ID", "Scenario")
+        name = row.get("Scenario Name", sid)
+        lines.append(f"{name} ({sid}):")
+        changes=[]
+        no_conduits = int(row.get("Conduit Count", 0) or 0) == 0
+        for col,label in metrics:
+            if no_conduits and col in {"Maximum Link Velocity", "Maximum Modelled Depth Ratio"}:
+                changes.append(f"- {label}: Not applicable — no conduits in model")
+                continue
+            try:
+                bv=float(b.get(col,0) or 0); sv=float(row.get(col,0) or 0)
+            except Exception:
+                continue
+            delta=sv-bv
+            if abs(bv)>1e-12:
+                pct=100*delta/abs(bv)
+                changes.append(f"- {label}: {sv:.4g} ({delta:+.4g}; {pct:+.1f}% relative to base)")
+            else:
+                changes.append(f"- {label}: {sv:.4g} ({delta:+.4g} relative to base)")
+        lines.extend(changes)
+        if str(row.get("Hydraulic Difference", "")) == "No summary-level difference":
+            lines.append("- No difference was detected in the reported summary metrics. Check the input-change status and detailed time series before treating this as a distinct hydraulic alternative.")
+        if str(row.get("Input Changed", "")) == "No":
+            lines.append("- The final scenario input is identical to the base-model input; identical results are expected.")
+        if float(row.get("Maximum Node Flooding",0) or 0)>0:
+            lines.append("- Modelled node flooding is present and requires review.")
+        if abs(float(row.get("Runoff Error (%)",0) or 0))>1 or abs(float(row.get("Flow Error (%)",0) or 0))>1:
+            lines.append("- Numerical continuity exceeds 1% for at least one reported balance and requires review.")
+        lines.append("")
+    lines.append("The comparison does not establish design adequacy or compliance. The responsible engineer must review model changes, storm sources, controlling elements, physical feasibility, and applicable project criteria.")
+    return "\n".join(lines).strip()
+
+def comparison_dataframe(records: Iterable[dict[str, Any]]) -> pd.DataFrame:
+    rows = [r.get("summary", {}) for r in records]
+    return pd.DataFrame(rows)
+
+
+def build_scenario_package(records: Iterable[dict[str, Any]]) -> bytes:
+    records = list(records)
+    buffer = BytesIO()
+    with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_DEFLATED) as zf:
+        comparison = comparison_dataframe(records)
+        zf.writestr("scenario_comparison.csv", comparison.to_csv(index=False))
+        manifest = []
+        for rec in records:
+            sid = safe_scenario_id(rec.get("definition", {}).get("scenario_id", "scenario"))
+            base = f"scenarios/{sid}"
+            editable_clone = rec.get("files", {}).get("editable_clone", b"")
+            if editable_clone:
+                zf.writestr(f"{base}/{sid}_editable_clone_source.inp", editable_clone)
+            zf.writestr(f"{base}/{sid}.inp", rec.get("files", {}).get("inp", b""))
+            zf.writestr(f"{base}/{sid}.rpt", rec.get("files", {}).get("rpt", b""))
+            out_bytes = rec.get("files", {}).get("out", b"")
+            if out_bytes:
+                zf.writestr(f"{base}/{sid}.out", out_bytes)
+            zf.writestr(f"{base}/scenario_definition.json", json.dumps(rec.get("definition", {}), indent=2, default=str))
+            zf.writestr(f"{base}/scenario_manifest.json", json.dumps(rec.get("manifest", {}), indent=2, default=str))
+            manifest.append(rec.get("manifest", {}))
+        zf.writestr("scenario_register.json", json.dumps(manifest, indent=2, default=str))
+        zf.writestr("README.txt", "Rev22.1 preliminary scenario package. Editable clone source files are preserved separately from final scenario input files. Generated storms and parameter changes require professional verification before design use or municipal submission.\n")
+    return buffer.getvalue()

server.py

@@ -0,0 +1,231 @@
+"""SWMM Analysis MCP Server — dual-surface deployment for Hugging Face Spaces.
+
+Surfaces
+--------
+1. MCP (Streamable HTTP) at /mcp
+   For MCP-native clients: Claude Desktop & claude.ai custom connectors,
+   Gemini CLI/clients, ChatGPT connectors, LangChain MCP adapters, n8n MCP
+   Client node, Flowise/Langflow MCP tools, Codex CLI. Stateless HTTP +
+   JSON responses for maximum client compatibility; DNS-rebinding
+   protection disabled (required behind the HF Spaces proxy).
+
+2. REST/OpenAPI at /api/*  (schema at /openapi.json)
+   Every registry tool as POST /api/tool/{name}; used by Custom GPT
+   Actions, n8n HTTP Request nodes, plain webhooks, and anything that
+   speaks OpenAPI rather than MCP.
+
+3. Built-in agent at POST /api/agent (also MCP tool `agent_analyze`)
+   A multi-provider LLM tool-loop over the same registry, for callers that
+   want one natural-language endpoint (see agent.py).
+
+4. GET /files/{session_id}/{filename} — generated report downloads.
+
+Both surfaces dispatch to the same registry in tools.py, so behaviour is
+identical on every platform.
+"""
+from __future__ import annotations
+
+import contextlib
+import inspect
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from fastapi import Body, FastAPI, HTTPException
+from fastapi.responses import FileResponse, HTMLResponse, JSONResponse
+
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+
+import agent as agent_module
+from sessions import SESSION_ROOT, STORE
+from tools import TOOL_REGISTRY
+
+SERVER_NAME = "swmm-analysis"
+SERVER_VERSION = "1.0.0 (engine Rev 23.2)"
+
+# ---------------------------------------------------------------------------
+# MCP surface
+# ---------------------------------------------------------------------------
+# Known HF-Spaces deployment fixes, learned the hard way on prior servers:
+#   1. TransportSecuritySettings(enable_dns_rebinding_protection=False):
+#      the Spaces proxy rewrites Host headers and rebinding protection
+#      rejects every request without this.
+#   2. The MCP session manager lifespan MUST be wired into the outer FastAPI
+#      app (dropping it silently breaks streamable HTTP after startup).
+#   3. README.md needs its YAML front-matter header or the Space won't build.
+mcp = FastMCP(
+    SERVER_NAME,
+    instructions=(
+        "Deterministic EPA-SWMM stormwater analysis: upload a .inp model, run the "
+        "crash-isolated simulation, then query results, Calgary-style screening, "
+        "QA/QC findings, engine-report reconciliation, controlled scenarios, and "
+        "SWMR draft reports. Typical flow: upload_model -> run_simulation -> "
+        "analysis tools with the returned session_id. All outputs are preliminary "
+        "engineering screening, not professional determinations."
+    ),
+    stateless_http=True,
+    json_response=True,
+    transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False),
+)
+
+for _name, _fn in TOOL_REGISTRY.items():
+    mcp.tool()(_fn)
+
+
+@mcp.tool()
+def agent_analyze(question: str, provider: str = "anthropic", model: str = "",
+                  session_id: str = "", api_key: str = "", base_url: str = "") -> dict:
+    """Ask the built-in agent a natural-language question; it plans and runs the
+    SWMM tools itself and returns an answer plus a full tool audit trail.
+    Providers: anthropic, openai, gemini, groq, mistral, local (keys via Space
+    secrets or api_key argument). MCP clients normally drive tools directly —
+    use this when you want server-side orchestration."""
+    return agent_module.run_agent(
+        question=question, provider=provider, model=model or None,
+        api_key=api_key or None, base_url=base_url or None,
+        session_id=session_id or None)
+
+
+mcp_app = mcp.streamable_http_app()
+
+# ---------------------------------------------------------------------------
+# FastAPI app with the MCP lifespan wired in (fix #2)
+# ---------------------------------------------------------------------------
+
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with contextlib.AsyncExitStack() as stack:
+        await stack.enter_async_context(mcp.session_manager.run())
+        yield
+
+
+app = FastAPI(
+    title="SWMM Analysis MCP Server",
+    version=SERVER_VERSION,
+    description="Dual-surface (MCP + REST) EPA-SWMM analysis server with a built-in multi-provider agent. "
+                "MCP endpoint: /mcp. Engine: OpenSWMM in a crash-isolated worker, Calgary screening, "
+                "deterministic QA/QC, .rpt reconciliation, scenarios, SWMR reporting.",
+    lifespan=lifespan,
+)
+
+
+# ---------------------------------------------------------------------------
+# REST surface — one endpoint per tool, plus a generic dispatcher
+# ---------------------------------------------------------------------------
+
+def _tool_meta(name: str, fn) -> dict:
+    sig = inspect.signature(fn)
+    return {
+        "name": name,
+        "description": (fn.__doc__ or "").strip(),
+        "parameters": {
+            p: {"required": prm.default is inspect.Parameter.empty,
+                "default": None if prm.default is inspect.Parameter.empty else prm.default}
+            for p, prm in sig.parameters.items()
+        },
+        "rest": f"POST /api/tool/{name}",
+    }
+
+
+@app.get("/api/tools")
+def rest_list_tools() -> dict:
+    """List all tools with parameter metadata (machine-readable)."""
+    return {"server": SERVER_NAME, "version": SERVER_VERSION,
+            "tools": [_tool_meta(n, f) for n, f in TOOL_REGISTRY.items()]}
+
+
+@app.post("/api/tool/{tool_name}")
+def rest_call_tool(tool_name: str, payload: dict = Body(default={})) -> JSONResponse:
+    """Invoke any registry tool. Body = the tool's keyword arguments as JSON."""
+    fn = TOOL_REGISTRY.get(tool_name)
+    if fn is None:
+        raise HTTPException(404, f"Unknown tool '{tool_name}'. See /api/tools.")
+    try:
+        result = fn(**(payload or {}))
+    except (KeyError, ValueError, TypeError) as exc:
+        raise HTTPException(400, str(exc))
+    except Exception as exc:
+        raise HTTPException(500, f"{type(exc).__name__}: {exc}")
+    return JSONResponse(json.loads(json.dumps(result, default=str)))
+
+
+@app.post("/api/agent")
+def rest_agent(payload: dict = Body(...)) -> JSONResponse:
+    """Built-in agent endpoint.
+
+    Body: {"question": str, "provider": "anthropic|openai|gemini|groq|mistral|local",
+           "model": str?, "api_key": str?, "base_url": str?, "session_id": str?,
+           "inp_content": str?, "allow_report": bool?}
+    """
+    question = payload.get("question", "").strip()
+    if not question:
+        raise HTTPException(400, "'question' is required.")
+    try:
+        result = agent_module.run_agent(
+            question=question,
+            provider=payload.get("provider", "anthropic"),
+            model=payload.get("model") or None,
+            api_key=payload.get("api_key") or None,
+            base_url=payload.get("base_url") or None,
+            session_id=payload.get("session_id") or None,
+            inp_content=payload.get("inp_content") or None,
+            allow_report=bool(payload.get("allow_report", False)),
+        )
+    except ValueError as exc:
+        raise HTTPException(400, str(exc))
+    except Exception as exc:
+        raise HTTPException(502, f"Agent/provider error: {type(exc).__name__}: {exc}")
+    return JSONResponse(json.loads(json.dumps(result, default=str)))
+
+
+@app.get("/files/{session_id}/{filename}")
+def serve_file(session_id: str, filename: str) -> FileResponse:
+    """Download generated report artifacts."""
+    safe_session = Path(session_id).name
+    safe_file = Path(filename).name
+    path = (SESSION_ROOT / safe_session / "outputs" / safe_file).resolve()
+    if not str(path).startswith(str(SESSION_ROOT.resolve())) or not path.exists():
+        raise HTTPException(404, "File not found (sessions expire; regenerate the report).")
+    return FileResponse(path, filename=safe_file)
+
+
+@app.get("/health")
+def health() -> dict:
+    return {"status": "ok", "server": SERVER_NAME, "version": SERVER_VERSION,
+            "tools": len(TOOL_REGISTRY) + 1, "sessions": len(STORE.list()),
+            "mcp_endpoint": "/mcp", "openapi": "/openapi.json"}
+
+
+@app.get("/", response_class=HTMLResponse)
+def index() -> str:
+    tool_rows = "".join(
+        f"<tr><td><code>{n}</code></td><td>{(f.__doc__ or '').strip().splitlines()[0]}</td></tr>"
+        for n, f in TOOL_REGISTRY.items())
+    return f"""<!doctype html><html><head><title>SWMM Analysis MCP Server</title>
+<style>body{{font-family:system-ui;max-width:900px;margin:2rem auto;padding:0 1rem;color:#222}}
+code{{background:#f2f2f2;padding:1px 5px;border-radius:4px}}table{{border-collapse:collapse;width:100%}}
+td,th{{border:1px solid #ddd;padding:6px 10px;text-align:left;font-size:14px}}h1{{color:#0a4d8c}}</style></head>
+<body><h1>🌧️ SWMM Analysis MCP Server</h1>
+<p>Deterministic EPA-SWMM stormwater analysis (engine Rev 23.2) with dual MCP + REST surfaces
+and a built-in multi-provider agent. All results are preliminary engineering screening.</p>
+<ul>
+<li><b>MCP endpoint (Streamable HTTP):</b> <code>&lt;this-space-url&gt;/mcp</code></li>
+<li><b>REST:</b> <code>POST /api/tool/{{name}}</code> — catalog at <a href="/api/tools">/api/tools</a>,
+schema at <a href="/openapi.json">/openapi.json</a></li>
+<li><b>Agent:</b> <code>POST /api/agent</code> (anthropic · openai · gemini · groq · mistral · local)</li>
+<li><b>Health:</b> <a href="/health">/health</a></li>
+</ul>
+<h3>Tools ({len(TOOL_REGISTRY) + 1})</h3><table><tr><th>Tool</th><th>Purpose</th></tr>{tool_rows}
+<tr><td><code>agent_analyze</code></td><td>Server-side agent loop over all tools (MCP + REST).</td></tr></table>
+<p>Typical flow: <code>upload_model</code> → <code>run_simulation</code> → analysis tools with the returned
+<code>session_id</code>. See the README for per-platform connection instructions.</p></body></html>"""
+
+
+# Mount MCP last so explicit routes take priority.
+app.mount("/", mcp_app)
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "7860")))

sessions.py

@@ -0,0 +1,98 @@
+"""Session store for the SWMM MCP server.
+
+Each uploaded model gets a session with its own working directory under
+/tmp/swmm_sessions. Sessions expire after SESSION_TTL_HOURS (default 6) and
+are swept lazily on access. State is process-local: the HF Space runs a
+single uvicorn worker, matching the stateful-session conclusion from the
+WNTR MCP architecture work (one backend, session-ID state).
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import threading
+import time
+import uuid
+from pathlib import Path
+from typing import Any
+
+SESSION_ROOT = Path(os.environ.get("SWMM_SESSION_ROOT", "/tmp/swmm_sessions"))
+SESSION_TTL_S = float(os.environ.get("SESSION_TTL_HOURS", "6")) * 3600.0
+MAX_SESSIONS = int(os.environ.get("MAX_SESSIONS", "40"))
+
+
+class Session:
+    def __init__(self, session_id: str, workdir: Path):
+        self.id = session_id
+        self.workdir = workdir
+        self.created = time.time()
+        self.touched = time.time()
+        self.data: dict[str, Any] = {}
+
+    def touch(self) -> None:
+        self.touched = time.time()
+
+
+class SessionStore:
+    def __init__(self) -> None:
+        self._sessions: dict[str, Session] = {}
+        self._lock = threading.Lock()
+        SESSION_ROOT.mkdir(parents=True, exist_ok=True)
+
+    def create(self) -> Session:
+        with self._lock:
+            self._sweep_locked()
+            if len(self._sessions) >= MAX_SESSIONS:
+                oldest = min(self._sessions.values(), key=lambda s: s.touched)
+                self._drop_locked(oldest.id)
+            sid = uuid.uuid4().hex[:12]
+            workdir = SESSION_ROOT / sid
+            workdir.mkdir(parents=True, exist_ok=True)
+            session = Session(sid, workdir)
+            self._sessions[sid] = session
+            return session
+
+    def get(self, session_id: str) -> Session:
+        with self._lock:
+            self._sweep_locked()
+            session = self._sessions.get(str(session_id))
+            if session is None:
+                raise KeyError(
+                    f"Unknown or expired session '{session_id}'. Call upload_model first "
+                    f"(sessions expire after {SESSION_TTL_S/3600:.0f} h of inactivity)."
+                )
+            session.touch()
+            return session
+
+    def list(self) -> list[dict[str, Any]]:
+        with self._lock:
+            self._sweep_locked()
+            return [
+                {
+                    "session_id": s.id,
+                    "model": s.data.get("filename"),
+                    "simulated": bool(s.data.get("results")),
+                    "age_minutes": round((time.time() - s.created) / 60.0, 1),
+                }
+                for s in self._sessions.values()
+            ]
+
+    def drop(self, session_id: str) -> bool:
+        with self._lock:
+            return self._drop_locked(str(session_id))
+
+    # -- internal --
+    def _drop_locked(self, session_id: str) -> bool:
+        session = self._sessions.pop(session_id, None)
+        if session is None:
+            return False
+        shutil.rmtree(session.workdir, ignore_errors=True)
+        return True
+
+    def _sweep_locked(self) -> None:
+        now = time.time()
+        for sid in [s for s, v in self._sessions.items() if now - v.touched > SESSION_TTL_S]:
+            self._drop_locked(sid)
+
+
+STORE = SessionStore()

smoke_test.py

@@ -0,0 +1,46 @@
+"""Deployment smoke test. Run against a live server:
+    python smoke_test.py http://127.0.0.1:7860  (or the Space URL)
+Verifies: health, REST tool call, full MCP workflow, regression pin (>=26/27
+links reconciled on Kincora), report download, agent 400-without-key.
+Requires a local Kincora_Phase_2.inp or any valid .inp passed as argv[2].
+"""
+import asyncio, json, sys
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+
+BASE = sys.argv[1].rstrip("/") if len(sys.argv) > 1 else "http://127.0.0.1:7860"
+INP = sys.argv[2] if len(sys.argv) > 2 else "Kincora_Phase_2.inp"
+
+async def main():
+    h = httpx.get(f"{BASE}/health", timeout=30).json()
+    assert h["status"] == "ok", h
+    print("health:", h["server"], h["version"], "| tools", h["tools"])
+    r = httpx.post(f"{BASE}/api/tool/list_sessions", json={}, timeout=30)
+    assert r.status_code == 200
+    print("REST surface: OK")
+    inp = open(INP, encoding="utf-8", errors="replace").read()
+    async with streamablehttp_client(f"{BASE}/mcp") as (read, write, _):
+        async with ClientSession(read, write) as s:
+            await s.initialize()
+            tools = await s.list_tools()
+            assert len(tools.tools) >= 16
+            up = json.loads((await s.call_tool("upload_model",
+                {"inp_content": inp, "filename": INP})).content[0].text)
+            sid = up["session_id"]
+            run = json.loads((await s.call_tool("run_simulation", {"session_id": sid})).content[0].text)
+            recon = run["rpt_reconciliation"]
+            print(f"MCP workflow: session {sid} | recon {recon.get('ok')}/{recon.get('links_checked')}")
+            if "Kincora" in INP:
+                assert recon.get("ok", 0) >= 26, "REGRESSION PIN FAILED"
+            rep = json.loads((await s.call_tool("generate_report",
+                {"session_id": sid, "project_name": "Smoke Test"})).content[0].text)
+            dl = httpx.get(f"{BASE}{rep['files']['docx']}", timeout=60)
+            assert dl.status_code == 200 and len(dl.content) > 30000
+            print("report + download: OK", len(dl.content), "bytes")
+            await s.call_tool("close_session", {"session_id": sid})
+    r = httpx.post(f"{BASE}/api/agent", json={"question": "x", "provider": "anthropic"}, timeout=30)
+    print("agent (no key expected 400 unless secret set):", r.status_code)
+    print("\nSMOKE TEST: PASS")
+
+asyncio.run(main())

sql_agent.py

@@ -0,0 +1,390 @@
+"""Safe provider-agnostic SQL retrieval agent for the complete SWMM SQLite store.
+
+The language model produces a constrained JSON retrieval plan. This module validates
+that plan and executes read-only SELECT statements only. No model-generated SQL is
+executed directly.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+import sqlite3
+from dataclasses import dataclass
+from typing import Any
+
+import pandas as pd
+
+
+_ALLOWED_FILTER_OPS = {
+    "eq": "=", "ne": "!=", "gt": ">", "gte": ">=", "lt": "<", "lte": "<=",
+    "like": "LIKE", "in": "IN", "between": "BETWEEN",
+    "is_null": "IS NULL", "not_null": "IS NOT NULL",
+}
+_ALLOWED_AGGS = {"MAX", "MIN", "AVG", "SUM", "COUNT"}
+_MAX_ACTIONS = 6
+_MAX_ROWS_PER_ACTION = 120
+_MAX_CONTEXT_CHARS = 45_000
+
+
+@dataclass
+class RetrievalResult:
+    context: str
+    audit: list[dict[str, Any]]
+    plan: dict[str, Any]
+
+
+class SafeSQLAgent:
+    """Validate and execute bounded, read-only retrieval plans against a ResultDatabase."""
+
+    def __init__(self, result_db: Any) -> None:
+        self.db = result_db
+        self.conn: sqlite3.Connection = result_db.connection
+        self._tables = self._read_tables()
+        self._columns = {table: self._read_columns(table) for table in self._tables}
+
+    @staticmethod
+    def _quote_identifier(name: str) -> str:
+        return '"' + name.replace('"', '""') + '"'
+
+    def _read_tables(self) -> list[str]:
+        rows = self.conn.execute(
+            "SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%' ORDER BY name"
+        ).fetchall()
+        return [str(r[0]) for r in rows]
+
+    def _read_columns(self, table: str) -> list[str]:
+        if table not in self._tables:
+            return []
+        rows = self.conn.execute(f"PRAGMA table_info({self._quote_identifier(table)})").fetchall()
+        return [str(r[1]) for r in rows]
+
+    def _row_count(self, table: str) -> int:
+        try:
+            return int(self.conn.execute(
+                f"SELECT COUNT(*) FROM {self._quote_identifier(table)}"
+            ).fetchone()[0])
+        except Exception:
+            return 0
+
+    @staticmethod
+    def _tokens(text: str) -> set[str]:
+        return {t.lower() for t in re.findall(r"[A-Za-z0-9_:.\-]+", text) if len(t) > 1}
+
+    def schema_context(self, question: str, max_tables: int = 16) -> str:
+        """Return a compact, question-ranked schema catalogue for the planning call."""
+        q_tokens = self._tokens(question)
+        synonyms = {
+            "node": {"node", "junction", "outfall", "storage", "manhole", "flood", "head", "depth"},
+            "link": {"link", "conduit", "pipe", "pump", "weir", "orifice", "outlet", "flow", "velocity", "capacity"},
+            "subcatchment": {"subcatchment", "catchment", "runoff", "rainfall", "infiltration", "hydrology"},
+            "input": {"input", "option", "roughness", "diameter", "length", "invert", "curve", "pattern", "control"},
+            "timeseries": {"time", "timeseries", "duration", "when", "peak", "first", "last", "hour"},
+        }
+        expanded = set(q_tokens)
+        for _, words in synonyms.items():
+            if q_tokens & words:
+                expanded |= words
+
+        always = {
+            "simulation_metadata", "simulation_warnings", "node_summary", "link_summary",
+            "subcatchment_summary", "model_input_section_catalog",
+        }
+        scored: list[tuple[float, str]] = []
+        for table in self._tables:
+            hay = self._tokens(table + " " + " ".join(self._columns[table]))
+            score = float(len(expanded & hay) * 5)
+            for token in expanded:
+                if token in table.lower():
+                    score += 3
+                score += sum(1 for c in self._columns[table] if token in c.lower()) * 0.5
+            if table in always:
+                score += 4
+            if table.endswith("_timeseries") and (expanded & synonyms["timeseries"]):
+                score += 5
+            if table.startswith("inp_") and (expanded & synonyms["input"]):
+                score += 5
+            scored.append((score, table))
+
+        selected = [t for _, t in sorted(scored, reverse=True)[:max_tables]]
+        for table in always:
+            if table in self._tables and table not in selected:
+                selected.append(table)
+        selected = selected[:max_tables]
+
+        lines = ["AVAILABLE SQLITE TABLES (question-ranked):"]
+        for table in selected:
+            cols = self._columns[table]
+            count = self._row_count(table)
+            lines.append(f"- {table} ({count} rows): {', '.join(cols)}")
+        lines.append(
+            "The complete database may contain additional inp_<section> tables. "
+            "Use model_input_lines to search exact source text when a section is not listed."
+        )
+        return "\n".join(lines)
+
+    def planner_system_prompt(self, schema_context: str) -> str:
+        return f"""You are a retrieval planner for an EPA SWMM SQLite database.
+Return ONLY valid JSON. Do not answer the engineering question.
+Create the smallest read-only retrieval plan that supplies enough evidence for a later engineering answer.
+Never emit SQL. Use only the operations and fields below.
+
+{schema_context}
+
+JSON format:
+{{
+  "reasoning_summary": "brief retrieval rationale",
+  "actions": [
+    {{
+      "operation": "select",
+      "table": "table_name",
+      "columns": ["column1", "column2"],
+      "filters": [{{"column":"column1","op":"eq|ne|gt|gte|lt|lte|like|in|between|is_null|not_null","value": "value or list"}}],
+      "order_by": [{{"column":"column1","direction":"asc|desc"}}],
+      "limit": 40,
+      "label": "descriptive result label"
+    }},
+    {{
+      "operation": "aggregate",
+      "table": "table_name",
+      "group_by": ["optional_column"],
+      "metrics": [{{"function":"MAX|MIN|AVG|SUM|COUNT","column":"column_or_*","alias":"metric_name"}}],
+      "filters": [],
+      "order_by": [{{"column":"metric_alias_or_group_column","direction":"desc"}}],
+      "limit": 40,
+      "label": "descriptive result label"
+    }},
+    {{
+      "operation": "search_input",
+      "term": "text to find in raw SWMM input lines",
+      "section": "optional SWMM section name without brackets",
+      "limit": 40,
+      "label": "descriptive result label"
+    }},
+    {{
+      "operation": "describe_table",
+      "table": "table_name",
+      "label": "table structure"
+    }}
+  ]
+}}
+
+Rules:
+- Maximum 6 actions and normally 1-4 actions.
+- Use exact asset IDs appearing in the user's question as equality filters.
+- Prefer summary/aggregate retrieval for broad questions and detailed time-series only for named assets or explicit temporal questions.
+- For first/last/peak questions, use ordering and a small limit or an aggregate.
+- Retrieve model inputs from inp_* tables or model_input_lines.
+- Never request full tables. Keep each limit at or below 120.
+- Use engineering evidence from both input and output tables when the question asks for diagnosis or recommendations.
+"""
+
+    @staticmethod
+    def parse_plan(text: str) -> dict[str, Any]:
+        cleaned = text.strip()
+        cleaned = re.sub(r"^```(?:json)?\s*", "", cleaned, flags=re.IGNORECASE)
+        cleaned = re.sub(r"\s*```$", "", cleaned)
+        start, end = cleaned.find("{"), cleaned.rfind("}")
+        if start >= 0 and end > start:
+            cleaned = cleaned[start:end + 1]
+        plan = json.loads(cleaned)
+        if not isinstance(plan, dict):
+            raise ValueError("Planner response must be a JSON object")
+        actions = plan.get("actions", [])
+        if not isinstance(actions, list):
+            raise ValueError("Planner actions must be a list")
+        plan["actions"] = actions[:_MAX_ACTIONS]
+        return plan
+
+    def _validate_table(self, table: str) -> str:
+        if table not in self._tables:
+            raise ValueError(f"Unknown table: {table}")
+        return table
+
+    def _validate_column(self, table: str, column: str, *, allow_star: bool = False) -> str:
+        if allow_star and column == "*":
+            return column
+        if column not in self._columns[table]:
+            raise ValueError(f"Unknown column {column!r} in {table}")
+        return column
+
+    def _build_filters(self, table: str, filters: Any) -> tuple[str, list[Any]]:
+        if not filters:
+            return "", []
+        clauses: list[str] = []
+        params: list[Any] = []
+        for item in list(filters)[:12]:
+            if not isinstance(item, dict):
+                continue
+            col = self._validate_column(table, str(item.get("column", "")))
+            op_key = str(item.get("op", "eq")).lower()
+            if op_key not in _ALLOWED_FILTER_OPS:
+                raise ValueError(f"Unsupported filter operation: {op_key}")
+            sql_op = _ALLOWED_FILTER_OPS[op_key]
+            qcol = self._quote_identifier(col)
+            value = item.get("value")
+            if op_key in {"is_null", "not_null"}:
+                clauses.append(f"{qcol} {sql_op}")
+            elif op_key == "in":
+                values = value if isinstance(value, list) else [value]
+                values = values[:50]
+                if not values:
+                    clauses.append("1=0")
+                else:
+                    clauses.append(f"{qcol} IN ({','.join('?' for _ in values)})")
+                    params.extend(values)
+            elif op_key == "between":
+                values = value if isinstance(value, list) else []
+                if len(values) != 2:
+                    raise ValueError("between requires exactly two values")
+                clauses.append(f"{qcol} BETWEEN ? AND ?")
+                params.extend(values)
+            else:
+                clauses.append(f"{qcol} {sql_op} ?")
+                params.append(value)
+        return (" WHERE " + " AND ".join(clauses)) if clauses else "", params
+
+    def _build_order(self, table: str, order_by: Any, aliases: set[str] | None = None) -> str:
+        if not order_by:
+            return ""
+        aliases = aliases or set()
+        parts: list[str] = []
+        for item in list(order_by)[:4]:
+            if not isinstance(item, dict):
+                continue
+            col = str(item.get("column", ""))
+            if col not in aliases:
+                self._validate_column(table, col)
+            direction = "DESC" if str(item.get("direction", "asc")).lower() == "desc" else "ASC"
+            parts.append(f"{self._quote_identifier(col)} {direction}")
+        return " ORDER BY " + ", ".join(parts) if parts else ""
+
+    @staticmethod
+    def _clean_frame(df: pd.DataFrame) -> pd.DataFrame:
+        out = df.copy()
+        for col in out.columns:
+            out[col] = out[col].map(
+                lambda v: None if isinstance(v, float) and (math.isnan(v) or math.isinf(v)) else v
+            )
+        return out
+
+    def _execute_select(self, action: dict[str, Any]) -> tuple[pd.DataFrame, str]:
+        table = self._validate_table(str(action.get("table", "")))
+        requested = action.get("columns") or self._columns[table]
+        columns = [self._validate_column(table, str(c)) for c in requested]
+        columns = columns[:24]
+        where_sql, params = self._build_filters(table, action.get("filters"))
+        order_sql = self._build_order(table, action.get("order_by"))
+        limit = min(max(int(action.get("limit", 40)), 1), _MAX_ROWS_PER_ACTION)
+        sql = (
+            "SELECT " + ", ".join(self._quote_identifier(c) for c in columns) +
+            f" FROM {self._quote_identifier(table)}" + where_sql + order_sql + " LIMIT ?"
+        )
+        df = pd.read_sql_query(sql, self.conn, params=(*params, limit))
+        return self._clean_frame(df), sql
+
+    def _execute_aggregate(self, action: dict[str, Any]) -> tuple[pd.DataFrame, str]:
+        table = self._validate_table(str(action.get("table", "")))
+        group_by = [self._validate_column(table, str(c)) for c in (action.get("group_by") or [])][:6]
+        metric_exprs: list[str] = []
+        aliases: set[str] = set()
+        for metric in (action.get("metrics") or [])[:12]:
+            if not isinstance(metric, dict):
+                continue
+            fn = str(metric.get("function", "")).upper()
+            if fn not in _ALLOWED_AGGS:
+                raise ValueError(f"Unsupported aggregate: {fn}")
+            col = str(metric.get("column", "*"))
+            self._validate_column(table, col, allow_star=(fn == "COUNT"))
+            alias = re.sub(r"[^A-Za-z0-9_]+", "_", str(metric.get("alias") or f"{fn.lower()}_{col}"))
+            aliases.add(alias)
+            expr_col = "*" if col == "*" else self._quote_identifier(col)
+            metric_exprs.append(f"{fn}({expr_col}) AS {self._quote_identifier(alias)}")
+        if not metric_exprs:
+            metric_exprs = ['COUNT(*) AS "row_count"']
+            aliases.add("row_count")
+        select_parts = [self._quote_identifier(c) for c in group_by] + metric_exprs
+        where_sql, params = self._build_filters(table, action.get("filters"))
+        group_sql = " GROUP BY " + ", ".join(self._quote_identifier(c) for c in group_by) if group_by else ""
+        order_sql = self._build_order(table, action.get("order_by"), aliases=aliases)
+        limit = min(max(int(action.get("limit", 40)), 1), _MAX_ROWS_PER_ACTION)
+        sql = (
+            "SELECT " + ", ".join(select_parts) + f" FROM {self._quote_identifier(table)}" +
+            where_sql + group_sql + order_sql + " LIMIT ?"
+        )
+        df = pd.read_sql_query(sql, self.conn, params=(*params, limit))
+        return self._clean_frame(df), sql
+
+    def _execute_search_input(self, action: dict[str, Any]) -> tuple[pd.DataFrame, str]:
+        term = str(action.get("term", "")).strip()
+        if not term:
+            raise ValueError("search_input requires a term")
+        section = str(action.get("section", "")).strip().upper()
+        limit = min(max(int(action.get("limit", 40)), 1), _MAX_ROWS_PER_ACTION)
+        sql = (
+            "SELECT line_no, section_name, section_row_no, raw_text FROM model_input_lines "
+            "WHERE lower(raw_text) LIKE lower(?)"
+        )
+        params: list[Any] = [f"%{term}%"]
+        if section:
+            sql += " AND upper(section_name)=?"
+            params.append(section)
+        sql += " ORDER BY line_no LIMIT ?"
+        params.append(limit)
+        df = pd.read_sql_query(sql, self.conn, params=params)
+        return self._clean_frame(df), sql
+
+    def _execute_describe(self, action: dict[str, Any]) -> tuple[pd.DataFrame, str]:
+        table = self._validate_table(str(action.get("table", "")))
+        rows = self.conn.execute(f"PRAGMA table_info({self._quote_identifier(table)})").fetchall()
+        df = pd.DataFrame(rows, columns=["cid", "name", "type", "notnull", "default_value", "primary_key"])
+        df["row_count"] = self._row_count(table)
+        return df, f"PRAGMA table_info({table})"
+
+    def execute_plan(self, plan: dict[str, Any]) -> RetrievalResult:
+        contexts: list[str] = []
+        audit: list[dict[str, Any]] = []
+        used_chars = 0
+        for index, action in enumerate(plan.get("actions", [])[:_MAX_ACTIONS], start=1):
+            if not isinstance(action, dict):
+                continue
+            operation = str(action.get("operation", "select")).lower()
+            label = str(action.get("label") or f"Retrieval {index}")
+            try:
+                if operation == "select":
+                    df, sql = self._execute_select(action)
+                elif operation == "aggregate":
+                    df, sql = self._execute_aggregate(action)
+                elif operation == "search_input":
+                    df, sql = self._execute_search_input(action)
+                elif operation == "describe_table":
+                    df, sql = self._execute_describe(action)
+                else:
+                    raise ValueError(f"Unsupported operation: {operation}")
+                csv_text = df.to_csv(index=False)
+                block = f"=== {label} ===\n{csv_text}"
+                remaining = _MAX_CONTEXT_CHARS - used_chars
+                if remaining <= 0:
+                    break
+                if len(block) > remaining:
+                    block = block[:remaining] + "\n[retrieval context truncated]"
+                contexts.append(block)
+                used_chars += len(block)
+                audit.append({
+                    "action": index,
+                    "label": label,
+                    "operation": operation,
+                    "table": action.get("table", "model_input_lines" if operation == "search_input" else ""),
+                    "rows_returned": int(len(df)),
+                    "status": "ok",
+                })
+            except Exception as exc:
+                audit.append({
+                    "action": index,
+                    "label": label,
+                    "operation": operation,
+                    "table": action.get("table", ""),
+                    "rows_returned": 0,
+                    "status": f"error: {exc}",
+                })
+        return RetrievalResult(context="\n\n".join(contexts), audit=audit, plan=plan)

swmm_core.py

@@ -0,0 +1,106 @@
+"""Crash-isolated deterministic OpenSWMM simulation core.
+
+The OpenSWMM engine is a native extension.  It is never loaded into the
+long-lived Streamlit process.  Each simulation runs in a short-lived worker
+process and returns only serialisable Python data.
+"""
+from __future__ import annotations
+
+import os
+import pickle
+import subprocess
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+
+class SwmmWorkerError(RuntimeError):
+    """Raised when the isolated OpenSWMM worker cannot complete."""
+
+
+
+def run_swmm(
+    inp_path: str | Path,
+    rpt_path: str | Path | None = None,
+    out_path: str | Path | None = None,
+    timeout_s: int = 900,
+) -> dict[str, Any]:
+    """Run OpenSWMM in an isolated subprocess.
+
+    Isolation prevents a native OpenSWMM segmentation fault from terminating
+    Streamlit.  The worker deliberately uses ``os._exit`` after serialising its
+    result so native-library finalisers cannot crash the parent application.
+    """
+    inp = Path(inp_path).resolve()
+    if not inp.is_file():
+        raise FileNotFoundError(f"SWMM input file not found: {inp}")
+
+    rpt = Path(rpt_path).resolve() if rpt_path else inp.with_suffix(".rpt")
+    out = Path(out_path).resolve() if out_path else inp.with_suffix(".out")
+    worker = Path(__file__).with_name("swmm_worker.py")
+    if not worker.is_file():
+        raise FileNotFoundError(f"OpenSWMM worker not found: {worker}")
+
+    fd, result_name = tempfile.mkstemp(prefix="swmm_result_", suffix=".pkl")
+    os.close(fd)
+    result_file = Path(result_name)
+
+    worker_python = os.environ.get("SWMM_WORKER_PYTHON", "/opt/swmm-venv/bin/python")
+    if not Path(worker_python).is_file():
+        raise FileNotFoundError(
+            f"Isolated OpenSWMM interpreter not found: {worker_python}"
+        )
+
+    cmd = [
+        worker_python,
+        "-u",
+        str(worker),
+        "--inp", str(inp),
+        "--rpt", str(rpt),
+        "--out", str(out),
+        "--result", str(result_file),
+    ]
+
+    try:
+        completed = subprocess.run(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            timeout=timeout_s,
+            check=False,
+            env={**os.environ, "PYTHONUNBUFFERED": "1"},
+        )
+
+        payload = None
+        if result_file.exists() and result_file.stat().st_size:
+            with result_file.open("rb") as f:
+                payload = pickle.load(f)
+
+        if isinstance(payload, dict) and payload.get("ok"):
+            results = payload["results"]
+            results.setdefault("metadata", {})["worker_stdout"] = completed.stdout[-4000:]
+            results["metadata"]["worker_stderr"] = completed.stderr[-4000:]
+            results["metadata"]["worker_exit_code"] = completed.returncode
+            return results
+
+        detail = ""
+        if isinstance(payload, dict):
+            detail = payload.get("error", "")
+        if not detail:
+            detail = completed.stderr.strip() or completed.stdout.strip()
+        if completed.returncode in (-11, 139):
+            detail = (
+                "The OpenSWMM worker encountered a native segmentation fault. "
+                "The Streamlit process remained protected. " + detail
+            ).strip()
+        raise SwmmWorkerError(
+            f"OpenSWMM worker failed with exit code {completed.returncode}. {detail}".strip()
+        )
+    except subprocess.TimeoutExpired as exc:
+        raise SwmmWorkerError(
+            f"OpenSWMM simulation exceeded the {timeout_s}-second timeout."
+        ) from exc
+    finally:
+        result_file.unlink(missing_ok=True)

swmm_worker.py

@@ -0,0 +1,207 @@
+"""One-shot OpenSWMM worker.  Do not import this module from Streamlit."""
+from __future__ import annotations
+
+import argparse
+import os
+import pickle
+import traceback
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+def _as_float_list(values: Any) -> list[float]:
+    return np.asarray(values, dtype=float).copy().tolist()
+
+
+def _enum_name(value: Any) -> str:
+    return getattr(value, "name", str(value))
+
+
+def _safe_float(getter, default: float = 0.0) -> float:
+    try:
+        return float(getter())
+    except Exception:
+        return default
+
+
+def simulate(inp_path: str, rpt_path: str, out_path: str) -> dict[str, Any]:
+    from openswmm.engine import Solver
+
+    node_ts: dict[str, dict[str, Any]] = {}
+    link_ts: dict[str, dict[str, Any]] = {}
+    sub_ts: dict[str, dict[str, Any]] = {}
+    times: list[Any] = []
+    warnings: list[dict[str, Any]] = []
+
+    with Solver(inp_path, rpt_path, out_path) as solver:
+        solver.set_warning_callback(
+            lambda code, message: warnings.append(
+                {"code": int(code), "message": str(message)}
+            )
+        )
+
+        nodes = solver.nodes
+        links = solver.links
+        subs = solver.subcatchments
+
+        node_ids = [str(nodes.get_id(i)) for i in range(len(nodes))]
+        link_ids = [str(links.get_id(i)) for i in range(len(links))]
+        sub_ids = [str(subs.get_id(i)) for i in range(len(subs))]
+
+        for node in nodes:
+            node_ts[str(node.id)] = {
+                "depth": [], "flooding": [], "inflow": [], "head": [],
+                "outflow": [], "volume": [],
+                "invert_elevation": float(node.invert_elev),
+                "full_depth": float(node.max_depth),
+            }
+
+        for link in links:
+            geom1 = 0.0
+            try:
+                geom1 = float(link.xsect.geom1)
+            except Exception:
+                try:
+                    geom1 = float(link.xsect.geometry[0])
+                except Exception:
+                    pass
+            link_ts[str(link.id)] = {
+                "flow": [], "depth": [], "velocity": [], "volume": [],
+                "capacity": [], "length": float(link.length),
+                "roughness": float(link.roughness), "diameter": geom1,
+            }
+
+        for sub in subs:
+            sub_ts[str(sub.id)] = {"runoff": [], "rainfall": [], "infil": []}
+
+        for _elapsed in solver.steps():
+            times.append(solver.current_datetime)
+
+            node_values = {
+                "depth": _as_float_list(nodes.depths),
+                "flooding": _as_float_list(nodes.overflows),
+                "inflow": _as_float_list(nodes.inflows),
+                "head": _as_float_list(nodes.heads),
+                "outflow": _as_float_list(nodes.outflows),
+                "volume": _as_float_list(nodes.volumes),
+            }
+            for i, node_id in enumerate(node_ids):
+                for key, values in node_values.items():
+                    node_ts[node_id][key].append(values[i])
+
+            link_values = {
+                "flow": _as_float_list(links.flows),
+                "depth": _as_float_list(links.depths),
+                "velocity": _as_float_list(links.velocities),
+                "volume": _as_float_list(links.volumes),
+                "capacity": _as_float_list(links.capacities),
+            }
+            for i, link_id in enumerate(link_ids):
+                for key, values in link_values.items():
+                    link_ts[link_id][key].append(values[i])
+
+            if sub_ids:
+                sub_values = {
+                    "runoff": _as_float_list(subs.runoffs),
+                    "rainfall": _as_float_list(subs.rainfalls),
+                    "infil": _as_float_list(subs.infils),
+                }
+                for i, sub_id in enumerate(sub_ids):
+                    for key, values in sub_values.items():
+                        sub_ts[sub_id][key].append(values[i])
+
+        # Recompute link velocity as |flow| / (volume / length).
+        # Rationale: the bulk `links.velocities` API array was found to
+        # disagree with the engine's own .rpt Link Flow Summary (5-12% on
+        # circular pipes; understated up to ~6x on IRREGULAR transect
+        # channels), while |Q|*L/volume reproduces the .rpt values to ~1%
+        # for both pipes and channels (validated against a SWMM 5.0.022
+        # reference run of the same model). The raw API series is kept as
+        # "velocity_api" for auditability. Zero-length links (OUTLET/DUMMY)
+        # carry no meaningful velocity and are reported as zero.
+        for link_id in link_ids:
+            ts = link_ts[link_id]
+            length = float(ts.get("length", 0.0) or 0.0)
+            flows = ts["flow"]
+            volumes = ts["volume"]
+            ts["velocity_api"] = ts["velocity"]
+            if length > 0.0:
+                derived = []
+                for q, vol in zip(flows, volumes):
+                    if vol > 1e-9:
+                        v = abs(q) * length / vol
+                        derived.append(v if np.isfinite(v) else 0.0)
+                    else:
+                        derived.append(0.0)
+                ts["velocity"] = derived
+            else:
+                ts["velocity"] = [0.0] * len(flows)
+
+        mb = solver.mass_balance
+        diag = mb.routing_diagnostics
+        metadata = {
+            "flow_units": _enum_name(solver.flow_units),
+            "system_units": str(solver.unit_system),
+            # OpenSWMM returns continuity errors as fractions; the .rpt and
+            # every downstream consumer (UI banner, report thresholds,
+            # calgary_rules continuity_*_pct) express them in PERCENT.
+            # Convert at the source so a -1.93% error reads as -1.93, not
+            # -0.0193 (which silently defeated the 0.5/1.0% thresholds).
+            "runoff_error": float(mb.runoff_continuity_error) * 100.0,
+            "flow_error": float(mb.routing_continuity_error) * 100.0,
+            "quality_error": _safe_float(lambda: mb.quality_continuity_error) * 100.0,
+            "start_time": solver.start_datetime,
+            "end_time": solver.end_datetime,
+            "routing_steps": int(diag.n_steps),
+            "not_converged_steps": int(diag.n_steps_not_converged),
+            "pct_not_converged": float(diag.pct_not_converged),
+            "avg_routing_step_s": float(diag.avg_time_step),
+            "warnings": warnings,
+            "report_path": rpt_path,
+            "output_path": out_path,
+        }
+
+    return {
+        "node_ts": node_ts,
+        "link_ts": link_ts,
+        "sub_ts": sub_ts,
+        "times": times,
+        "metadata": metadata,
+    }
+
+
+def write_payload(path: Path, payload: dict[str, Any]) -> None:
+    temp = path.with_suffix(path.suffix + ".tmp")
+    with temp.open("wb") as f:
+        pickle.dump(payload, f, protocol=pickle.HIGHEST_PROTOCOL)
+        f.flush()
+        os.fsync(f.fileno())
+    os.replace(temp, path)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--inp", required=True)
+    parser.add_argument("--rpt", required=True)
+    parser.add_argument("--out", required=True)
+    parser.add_argument("--result", required=True)
+    args = parser.parse_args()
+    result_path = Path(args.result)
+
+    try:
+        results = simulate(args.inp, args.rpt, args.out)
+        write_payload(result_path, {"ok": True, "results": results})
+        # Bypass Python/native-extension finalisers.  This is intentional.
+        os._exit(0)
+    except BaseException as exc:
+        write_payload(result_path, {
+            "ok": False,
+            "error": f"{type(exc).__name__}: {exc}\n{traceback.format_exc()}",
+        })
+        os._exit(1)
+
+
+if __name__ == "__main__":
+    main()

tools.py

@@ -0,0 +1,404 @@
+"""SWMM analysis tool registry.
+
+Every capability is a plain typed function registered in TOOL_REGISTRY.
+The MCP surface, the REST surface, and the internal agent all dispatch to
+these same functions, so behaviour is identical regardless of platform.
+
+Epistemics: all screening results are deterministic and distinguish
+"screening" from "criterion"; nothing here is a professional engineering
+determination. Outputs are bounded (row/point limits) so they remain usable
+as LLM tool results.
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import json
+import math
+from pathlib import Path
+from typing import Any, Callable
+
+import pandas as pd
+
+import model_pipeline as mp
+import rpt_reconciliation as rr
+from calgary_rules import (
+    CalgaryCriteria,
+    apply_storage_classification,
+    criteria_register,
+    infer_design_event,
+)
+from preliminary_design_assistant import build_deterministic_findings, findings_dataframe
+from results_db import ResultDatabase
+from sessions import STORE
+from sql_agent import SafeSQLAgent
+from swmm_core import run_swmm
+
+MAX_ROWS = 60
+MAX_TS_POINTS = 200
+
+
+def _df_records(df: pd.DataFrame | None, limit: int = MAX_ROWS) -> dict[str, Any]:
+    if df is None or df.empty:
+        return {"rows": [], "row_count": 0, "truncated": False}
+    clean = df.replace({float("nan"): None})
+    return {
+        "rows": json.loads(clean.head(limit).to_json(orient="records")),
+        "row_count": int(len(df)),
+        "truncated": bool(len(df) > limit),
+    }
+
+
+def _require_results(session) -> None:
+    if not session.data.get("results"):
+        raise ValueError(f"Session '{session.id}' has no simulation results yet. Call run_simulation first.")
+
+
+# ---------------------------------------------------------------------------
+# Model lifecycle
+# ---------------------------------------------------------------------------
+
+def upload_model(inp_content: str, filename: str = "model.inp") -> dict:
+    """Upload an EPA SWMM .inp model (raw text or base64) and create a session.
+
+    Returns a session_id used by every other tool, plus element counts.
+    """
+    text = inp_content
+    if "[" not in inp_content[:2000]:  # likely base64
+        try:
+            text = base64.b64decode(inp_content, validate=True).decode("utf-8", errors="replace")
+        except (binascii.Error, ValueError):
+            pass
+    if "[OPTIONS]" not in text.upper() and "[JUNCTIONS]" not in text.upper():
+        raise ValueError("Content does not look like a SWMM .inp file (no [OPTIONS]/[JUNCTIONS] section).")
+    session = STORE.create()
+    safe_name = Path(filename).name or "model.inp"
+    if not safe_name.lower().endswith(".inp"):
+        safe_name += ".inp"
+    inp_path = session.workdir / safe_name
+    inp_path.write_text(text, encoding="utf-8")
+    sections = mp.parse_inp_sections(str(inp_path))
+    session.data.update({"filename": safe_name, "inp_path": str(inp_path), "sections": sections})
+    counts = {name: len(rows) for name, rows in sections.items()
+              if name in ("JUNCTIONS", "OUTFALLS", "STORAGE", "CONDUITS", "PUMPS", "WEIRS",
+                          "ORIFICES", "OUTLETS", "SUBCATCHMENTS", "RAINGAGES", "TIMESERIES")}
+    gages = [row[0] for row in sections.get("RAINGAGES", []) if row]
+    return {
+        "session_id": session.id,
+        "filename": safe_name,
+        "element_counts": counts,
+        "rain_gages": gages,
+        "design_event_inference": infer_design_event(gages) if gages else None,
+        "next_step": "Call run_simulation with this session_id.",
+    }
+
+
+def run_simulation(session_id: str) -> dict:
+    """Run the model in the crash-isolated OpenSWMM worker and build summaries.
+
+    Also runs the deterministic worker-vs-.rpt reconciliation cross-check.
+    """
+    session = STORE.get(session_id)
+    inp_path = session.data.get("inp_path")
+    if not inp_path:
+        raise ValueError("Session has no uploaded model.")
+    results = run_swmm(inp_path)
+    md = results["metadata"]
+    sections = session.data["sections"]
+    node_df = mp.build_node_summary(results["node_ts"], mp.parse_node_types(sections), 0.001, 0.9)
+    link_df = mp.build_link_summary(results["link_ts"], mp.parse_link_topology(sections),
+                                    mp.parse_conduit_geometry(sections), 0.9, 3.0)
+    sub_df = mp.build_sub_summary(results["sub_ts"], mp.parse_subcatchment_attrs(sections),
+                                  results.get("times"), md.get("flow_units", "CMS"))
+    db = ResultDatabase(str(session.workdir / "results.sqlite"))
+    db.load(node_df, link_df, sub_df, inp_path=inp_path, results=results)
+
+    recon = {"verdict": "Not performed"}
+    recon_links = recon_nodes = recon_cont = None
+    rpt_path = md.get("report_path")
+    if rpt_path and Path(str(rpt_path)).exists():
+        recon_links = rr.reconcile_links(link_df, rpt_path)
+        recon_nodes = rr.reconcile_nodes(node_df, rpt_path)
+        recon_cont = rr.reconcile_continuity(md, rpt_path)
+        recon = rr.reconciliation_summary(recon_links)
+
+    session.data.update({
+        "results": results, "node_df": node_df, "link_df": link_df, "sub_df": sub_df,
+        "db": db, "recon_links": recon_links, "recon_nodes": recon_nodes,
+        "recon_continuity": recon_cont, "recon_summary": recon,
+    })
+    flooded_col = next((c for c in node_df.columns if c.startswith("Peak Flooding (")), None)
+    flooded = int((pd.to_numeric(node_df[flooded_col], errors="coerce").fillna(0) > 0.001).sum()) if flooded_col else 0
+    return {
+        "session_id": session.id,
+        "simulation": "completed",
+        "flow_units": md.get("flow_units"),
+        "runoff_continuity_error_pct": round(float(md.get("runoff_error", 0.0)), 3),
+        "flow_continuity_error_pct": round(float(md.get("flow_error", 0.0)), 3),
+        "warnings": (results.get("warnings") or md.get("warnings") or [])[:10],
+        "flooded_nodes": flooded,
+        "rpt_reconciliation": recon,
+        "note": "Values are model results, not engineering determinations.",
+    }
+
+
+def list_sessions() -> dict:
+    """List active sessions (id, model filename, simulated flag, age)."""
+    return {"sessions": STORE.list()}
+
+
+def close_session(session_id: str) -> dict:
+    """Delete a session and its working files."""
+    return {"session_id": session_id, "deleted": STORE.drop(session_id)}
+
+
+# ---------------------------------------------------------------------------
+# Results
+# ---------------------------------------------------------------------------
+
+def get_node_results(session_id: str, node_type: str = "", sort_by: str = "Depth Ratio",
+                     limit: int = 20) -> dict:
+    """Node result summary. Optional node_type filter (junction/storage/outfall);
+    sorted descending by sort_by column (default Depth Ratio)."""
+    session = STORE.get(session_id)
+    _require_results(session)
+    df = session.data["node_df"]
+    if node_type:
+        df = df[df["Type"].astype(str).str.lower() == node_type.lower()]
+    if sort_by in df.columns:
+        df = df.sort_values(sort_by, ascending=False)
+    return _df_records(df, min(int(limit), MAX_ROWS))
+
+
+def get_link_results(session_id: str, sort_by: str = "Peak Velocity (m/s)", limit: int = 20) -> dict:
+    """Link result summary sorted descending by sort_by (default peak velocity)."""
+    session = STORE.get(session_id)
+    _require_results(session)
+    df = session.data["link_df"]
+    if sort_by in df.columns:
+        df = df.sort_values(sort_by, ascending=False)
+    return _df_records(df, min(int(limit), MAX_ROWS))
+
+
+def get_subcatchment_results(session_id: str, limit: int = 30) -> dict:
+    """Subcatchment runoff summary."""
+    session = STORE.get(session_id)
+    _require_results(session)
+    return _df_records(session.data["sub_df"], min(int(limit), MAX_ROWS))
+
+
+def get_timeseries(session_id: str, object_type: str, object_id: str, variable: str) -> dict:
+    """Bounded time series for one object.
+
+    object_type: node|link|subcatchment. Variables — node: depth, flooding,
+    inflow, head, outflow, volume; link: flow, depth, velocity, volume,
+    capacity; subcatchment: runoff, rainfall, infil. Series longer than 200
+    points are decimated evenly (peaks preserved via max-in-bucket).
+    """
+    session = STORE.get(session_id)
+    _require_results(session)
+    results = session.data["results"]
+    key = {"node": "node_ts", "link": "link_ts", "subcatchment": "sub_ts"}.get(object_type.lower())
+    if key is None:
+        raise ValueError("object_type must be node, link, or subcatchment")
+    store = results[key]
+    if object_id not in store:
+        raise ValueError(f"Unknown {object_type} '{object_id}'. Known: {sorted(store)[:25]}")
+    series = store[object_id].get(variable)
+    if not isinstance(series, list):
+        available = [k for k, v in store[object_id].items() if isinstance(v, list)]
+        raise ValueError(f"Unknown variable '{variable}'. Available: {available}")
+    times = results.get("times", [])
+    n = len(series)
+    if n > MAX_TS_POINTS:
+        bucket = math.ceil(n / MAX_TS_POINTS)
+        points = []
+        for i in range(0, n, bucket):
+            chunk = series[i:i + bucket]
+            j = i + max(range(len(chunk)), key=lambda k: abs(chunk[k]))
+            points.append({"t": str(times[j]) if j < len(times) else j, "v": round(float(series[j]), 6)})
+    else:
+        points = [{"t": str(times[i]) if i < len(times) else i, "v": round(float(v), 6)}
+                  for i, v in enumerate(series)]
+    return {"object_id": object_id, "variable": variable, "n_source_points": n,
+            "decimated": n > MAX_TS_POINTS, "peak": round(float(max(series, key=abs, default=0.0)), 6),
+            "points": points}
+
+
+def query_results(session_id: str, plan: dict | str) -> dict:
+    """Execute a validated JSON retrieval plan against the bounded result DB.
+
+    Plan format: {"actions":[{"type":"select"|"aggregate","table":...,
+    "columns":[...], "filters":[{"column","op","value"}], "order_by":[...],
+    "limit":N, "aggregations":[{"agg","column"}]}]}. Use get_table_catalog
+    for table/column names. Read-only; invalid plans degrade gracefully.
+    """
+    session = STORE.get(session_id)
+    _require_results(session)
+    if isinstance(plan, str):
+        plan = json.loads(plan)
+    agent = SafeSQLAgent(session.data["db"])
+    result = agent.execute_plan(plan)
+    return {"context": result.context[:12000]}
+
+
+def get_table_catalog(session_id: str) -> dict:
+    """List queryable tables (results + complete tokenized INP) for query_results."""
+    session = STORE.get(session_id)
+    _require_results(session)
+    return _df_records(session.data["db"].table_catalog(), 60)
+
+
+# ---------------------------------------------------------------------------
+# Screening and review
+# ---------------------------------------------------------------------------
+
+def calgary_screening(session_id: str) -> dict:
+    """Screen results against City-of-Calgary-style criteria.
+
+    Velocity screen (3.0 m/s advisory / 4.0 m/s critical), storage
+    classification (trap-low vs pond heuristics), and the criteria register.
+    SCREENING ONLY — thresholds must be confirmed by the responsible engineer.
+    """
+    session = STORE.get(session_id)
+    _require_results(session)
+    crit = CalgaryCriteria()
+    link_df = session.data["link_df"]
+    node_df = session.data["node_df"]
+    vel_col = next((c for c in link_df.columns if c.startswith("Peak Velocity")), None)
+    lv = link_df[["Link ID", vel_col, "Depth Ratio"]].copy()
+    lv["Screen"] = lv[vel_col].apply(
+        lambda v: "CRITICAL > 4.0" if v > 4.0 else ("Advisory > 3.0" if v > 3.0 else "OK"))
+    flagged = lv[lv["Screen"] != "OK"].sort_values(vel_col, ascending=False)
+    storage = node_df[node_df["Type"].astype(str).str.lower() == "storage"].copy()
+    storage_class = apply_storage_classification(storage, crit, "m") if not storage.empty else pd.DataFrame()
+    return {
+        "velocity_screen_flagged": _df_records(flagged, 30),
+        "storage_classification": _df_records(storage_class, 30),
+        "criteria_register": _df_records(criteria_register(crit), 40),
+        "status": "Screening only — criteria applicability requires engineer confirmation.",
+    }
+
+
+def preliminary_design_review(session_id: str) -> dict:
+    """Deterministic QA/QC findings register (topology, hydrology, screening)
+    merged with the worker-vs-.rpt reconciliation findings (RPT-###)."""
+    session = STORE.get(session_id)
+    _require_results(session)
+    inp_text = Path(session.data["inp_path"]).read_text(encoding="utf-8", errors="replace")
+    findings = build_deterministic_findings(
+        inp_text=inp_text, node_summary=session.data["node_df"],
+        link_summary=session.data["link_df"], sub_summary=session.data["sub_df"],
+        metadata=session.data["results"]["metadata"],
+        simulation_completed=True, output_results_available=True)
+    recon_findings = rr.reconciliation_findings(
+        session.data.get("recon_links"), session.data.get("recon_nodes"),
+        session.data.get("recon_continuity"))
+    all_findings = list(findings) + list(recon_findings)
+    session.data["findings"] = all_findings
+    return {"findings": _df_records(findings_dataframe(all_findings), 60),
+            "rpt_reconciliation": session.data.get("recon_summary", {})}
+
+
+def get_reconciliation(session_id: str) -> dict:
+    """Worker-vs-.rpt reconciliation detail: flagged links and continuity check.
+    For flagged links, .rpt values are authoritative for screening."""
+    session = STORE.get(session_id)
+    _require_results(session)
+    lr = session.data.get("recon_links")
+    flagged = lr[lr["Overall Status"] != "OK"] if lr is not None and not lr.empty else pd.DataFrame()
+    return {"summary": session.data.get("recon_summary", {}),
+            "flagged_links": _df_records(flagged, 40),
+            "continuity": _df_records(session.data.get("recon_continuity"), 5)}
+
+
+# ---------------------------------------------------------------------------
+# Scenarios and reporting
+# ---------------------------------------------------------------------------
+
+def run_scenario(session_id: str, scenario_name: str,
+                 conduit_diameter_overrides: dict | str | None = None,
+                 rainfall_multiplier: float | None = None) -> dict:
+    """Clone the base model, apply controlled changes, re-simulate, compare.
+
+    conduit_diameter_overrides: {"link_id": new_diameter_m}. The base model is
+    never mutated; comparisons quote deterministic summary deltas.
+    """
+    import scenario_manager as sm
+    session = STORE.get(session_id)
+    _require_results(session)
+    if isinstance(conduit_diameter_overrides, str) and conduit_diameter_overrides:
+        conduit_diameter_overrides = json.loads(conduit_diameter_overrides)
+    kwargs: dict[str, Any] = {}
+    if conduit_diameter_overrides:
+        kwargs["conduit_diameter_overrides"] = {str(k): float(v) for k, v in conduit_diameter_overrides.items()}
+    if rainfall_multiplier is not None:
+        kwargs["rainfall_multiplier"] = float(rainfall_multiplier)
+    scen_id = f"scn_{len(session.data.setdefault('scenarios', [])) + 1}"
+    definition = sm.ScenarioDefinition(scenario_id=scen_id, scenario_name=scenario_name, **kwargs)
+    record = sm.run_scenario(session.data["inp_path"], definition,
+                             work_dir=str(session.workdir / "scenarios"))
+    base_record = sm.base_model_record(session.data["results"])
+    session.data["scenarios"].append(record)
+    comparison = sm.comparison_with_base(base_record, session.data["scenarios"])
+    narrative = sm.deterministic_comparison_analysis(comparison)
+    session.data["scenario_comparison"] = comparison
+    keep = [c for c in comparison.columns if comparison[c].dtype != object or c in
+            ("Scenario ID", "Scenario Name", "Simulation Status", "Velocity Link")]
+    return {"scenario_id": scen_id, "comparison": _df_records(comparison[keep], 20),
+            "deterministic_analysis": narrative[:6000]}
+
+
+def generate_report(session_id: str, project_name: str, client: str = "",
+                    consultant: str = "", prepared_by: str = "",
+                    outline_plan_no: str = "") -> dict:
+    """Generate the Calgary-style SWMR draft package (docx + audit zip).
+
+    Returns download paths served by this Space at /files/{session_id}/{name}.
+    The draft-readiness score honestly reflects missing project information.
+    """
+    from report_engine import ReportMetadata, generate_report_package
+    session = STORE.get(session_id)
+    _require_results(session)
+    meta = ReportMetadata(project_name=project_name, client=client, consultant=consultant,
+                          prepared_by=prepared_by, outline_plan_no=outline_plan_no)
+    findings = session.data.get("findings") or []
+    pkg = generate_report_package(
+        metadata=meta, inp_sections=session.data["sections"],
+        node_summary=session.data["node_df"], link_summary=session.data["link_df"],
+        sub_summary=session.data["sub_df"],
+        simulation_metadata=session.data["results"]["metadata"],
+        result_db_bytes=session.data["db"].export_bytes(),
+        preliminary_review_artifacts={
+            "findings": findings, "status": "Preliminary",
+            "manifest": {"rpt_reconciliation": session.data.get("recon_summary", {})},
+        } if findings else None)
+    outputs = session.workdir / "outputs"
+    outputs.mkdir(exist_ok=True)
+    files = {}
+    for key, blob in pkg.items():
+        if isinstance(blob, (bytes, bytearray)):
+            name = pkg.get(f"{key}_name") if isinstance(pkg.get(f"{key}_name"), str) else f"{key}.bin"
+            if key == "docx":
+                name = f"{project_name.replace(' ', '_')}_SWMR_Draft.docx"
+            elif key == "zip":
+                name = f"{project_name.replace(' ', '_')}_SWMR_Package.zip"
+            (outputs / name).write_bytes(blob)
+            files[key] = f"/files/{session.id}/{name}"
+    return {"files": files, "size_bytes": {k: len(v) for k, v in pkg.items() if isinstance(v, (bytes, bytearray))},
+            "note": "Draft for engineering review — not an issued document."}
+
+
+# ---------------------------------------------------------------------------
+# Registry
+# ---------------------------------------------------------------------------
+
+TOOL_REGISTRY: dict[str, Callable[..., dict]] = {
+    fn.__name__: fn for fn in [
+        upload_model, run_simulation, list_sessions, close_session,
+        get_node_results, get_link_results, get_subcatchment_results,
+        get_timeseries, query_results, get_table_catalog,
+        calgary_screening, preliminary_design_review, get_reconciliation,
+        run_scenario, generate_report,
+    ]
+}

worker-requirements.txt

@@ -0,0 +1,2 @@
+numpy==1.26.4
+openswmm==6.0.0a2