Deploy Sensorflow Studio

app_backend.py

@@ -1480,6 +1480,10 @@ app.include_router(bevfusion_router)
 from sensorflow.safety.api import router as safety_router
 app.include_router(safety_router)
 
+# Regression Root Cause Analysis workbench (staged offline-vs-shadow forensics).
+from sensorflow.rca.api import router as rca_router
+app.include_router(rca_router)
+
 # Mount static folder
 static_dir = Path(__file__).parent / "static"
 if static_dir.exists():

sensorflow/rca/__init__.py

@@ -0,0 +1,15 @@
+"""Regression Root Cause Analysis (RCA) investigation workbench.
+
+A skeptical, staged methodology for answering "offline says +5%, shadow says
+-2% -- which is real, and why?" without assuming either measurement is valid.
+
+Modules:
+    models      investigation entity, stage state machine, evidence records
+    scenario    synthetic offline+shadow dataset generator with planted causes
+    stats       Wilson CIs, PSI / JS / KS, cluster-aware effective sample size
+    diagnostics per-stage diagnostic computations (pure functions on data)
+    scoring     root-cause scoring board, decision tree, experiment ranking
+    report      final markdown + JSON report assembly
+    store       persistence under runs/rca/
+    api         FastAPI router mounted at /api/rca
+"""

sensorflow/rca/api.py

@@ -0,0 +1,253 @@
+"""FastAPI router for the RCA investigation workbench (prefix /api/rca)."""
+
+from __future__ import annotations
+
+import random
+from typing import Dict, Optional
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from sensorflow.rca import diagnostics as dg, report as report_mod, scoring, store
+from sensorflow.rca.models import (FINDING_STATUS, HYPOTHESIS_LABELS,
+                                   Investigation, ROOT_CAUSES, SEVERITIES,
+                                   STAGES, StageOrderError,
+                                   UnknownsNotAcknowledgedError, make_finding)
+from sensorflow.rca.scenario import CAUSE_EXPLANATIONS, generate_scenario
+
+router = APIRouter(prefix="/api/rca")
+
+# The full battery is deterministic per investigation (data is immutable), so
+# it is computed once and cached.
+_battery_cache: Dict[str, Dict] = {}
+
+
+def _inv_or_404(inv_id: str) -> Investigation:
+    inv = store.load_investigation(inv_id)
+    if inv is None:
+        raise HTTPException(404, f"Unknown investigation {inv_id}")
+    return inv
+
+
+def _bundle_or_404(inv_id: str):
+    bundle = store.load_bundle(inv_id)
+    if bundle is None:
+        raise HTTPException(404, f"No scenario data for investigation {inv_id}")
+    return bundle
+
+
+def _battery(inv_id: str) -> Dict:
+    if inv_id not in _battery_cache:
+        _battery_cache[inv_id] = dg.run_all(_bundle_or_404(inv_id))
+    return _battery_cache[inv_id]
+
+
+# ------------------------------------------------------------------- requests
+
+
+class CreateInvestigationRequest(BaseModel):
+    name: str = ""
+    baseline_model: str = "detr3d-a-v41"
+    candidate_model: str = "detr3d-b-v42"
+    # None + training_mode -> random hidden cause ("load demo investigation").
+    cause: Optional[str] = None
+    seed: Optional[int] = None
+    training_mode: bool = False
+
+
+class CompleteStageRequest(BaseModel):
+    acknowledge_unknowns: bool = False
+    note: str = ""
+
+
+class RecordFindingRequest(BaseModel):
+    stage: str
+    title: str
+    status: str = "MISMATCH"
+    severity: str = "WARN"
+    detail: str = ""
+    code: str = ""
+
+
+class AssessHypothesisRequest(BaseModel):
+    hypothesis: str
+    confidence: str = Field(pattern="^(HIGH|MEDIUM|LOW|UNKNOWN)$")
+    note: str = ""
+
+
+# ---------------------------------------------------------------- meta routes
+
+
+@router.get("/causes")
+def list_causes():
+    return {"causes": [{"id": c, "label": HYPOTHESIS_LABELS[c]}
+                       for c in ROOT_CAUSES]}
+
+
+@router.get("/stages")
+def list_stages():
+    return {"stages": STAGES}
+
+
+# -------------------------------------------------------------- investigations
+
+
+@router.post("/investigations")
+def create_investigation(req: CreateInvestigationRequest):
+    seed = req.seed if req.seed is not None else random.randint(1, 10_000_000)
+    if req.cause is not None:
+        if req.cause not in ROOT_CAUSES:
+            raise HTTPException(400, f"Unknown cause {req.cause!r}")
+        cause = req.cause
+    else:
+        cause = random.Random(seed).choice(ROOT_CAUSES)
+
+    bundle = generate_scenario(cause, seed=seed)
+    measured = bundle.meta["measured"]
+    claims = {
+        "metric": "object-level accuracy",
+        "offline_delta_pp": round(measured["offline_delta"] * 100, 2),
+        "shadow_delta_pp": round(measured["shadow_delta"] * 100, 2),
+        "offline_n": measured["offline_n"],
+        "shadow_scored_n": measured["shadow_scored_n"],
+    }
+    name = req.name or (f"{'Training drill' if req.training_mode else 'RCA'}: "
+                        f"{req.candidate_model} vs {req.baseline_model}")
+    inv = Investigation.new(name=name, baseline_model=req.baseline_model,
+                            candidate_model=req.candidate_model,
+                            scenario_cause=cause, seed=seed,
+                            training_mode=req.training_mode, claims=claims)
+    store.save_investigation(inv, bundle)
+    return inv.to_dict()
+
+
+@router.get("/investigations")
+def list_investigations():
+    return {"investigations": store.list_investigations()}
+
+
+@router.get("/investigations/{inv_id}")
+def get_investigation(inv_id: str):
+    return _inv_or_404(inv_id).to_dict()
+
+
+@router.post("/investigations/{inv_id}/reveal")
+def reveal(inv_id: str):
+    inv = _inv_or_404(inv_id)
+    inv.revealed = True
+    inv.log("revealed", "Planted root cause revealed")
+    store.save_investigation(inv)
+    return {"cause": inv.scenario_cause,
+            "explanation": CAUSE_EXPLANATIONS[inv.scenario_cause]}
+
+
+# --------------------------------------------------------------------- stages
+
+
+@router.post("/investigations/{inv_id}/stages/{index}/complete")
+def complete_stage(inv_id: str, index: int, req: CompleteStageRequest):
+    inv = _inv_or_404(inv_id)
+    try:
+        stage = inv.complete_stage(index,
+                                   acknowledge_unknowns=req.acknowledge_unknowns,
+                                   ack_note=req.note)
+    except StageOrderError as e:
+        raise HTTPException(409, str(e))
+    except UnknownsNotAcknowledgedError as e:
+        raise HTTPException(409, str(e))
+    except KeyError as e:
+        raise HTTPException(404, str(e))
+    store.save_investigation(inv)
+    return {"stage": stage.to_dict(), "investigation": inv.to_dict()}
+
+
+@router.post("/investigations/{inv_id}/stages/{index}/reopen")
+def reopen_stage(inv_id: str, index: int):
+    inv = _inv_or_404(inv_id)
+    if not 0 <= index < len(inv.stages):
+        raise HTTPException(404, f"No stage {index}")
+    stage = inv.reopen_stage(index)
+    store.save_investigation(inv)
+    return {"stage": stage.to_dict(), "investigation": inv.to_dict()}
+
+
+# ------------------------------------------------------------------- findings
+
+
+@router.post("/investigations/{inv_id}/findings")
+def record_finding(inv_id: str, req: RecordFindingRequest):
+    inv = _inv_or_404(inv_id)
+    stage_keys = [s["key"] for s in STAGES]
+    if req.stage not in stage_keys:
+        raise HTTPException(400, f"Unknown stage {req.stage!r}")
+    if req.status not in FINDING_STATUS:
+        raise HTTPException(400, f"status must be one of {FINDING_STATUS}")
+    if req.severity not in SEVERITIES:
+        raise HTTPException(400, f"severity must be one of {SEVERITIES}")
+    finding = make_finding(req.stage, req.code or f"HUMAN:{req.stage}",
+                           req.title, req.status, req.severity, req.detail,
+                           source="human")
+    inv.add_human_finding(finding)
+    store.save_investigation(inv)
+    return {"finding": finding.to_dict()}
+
+
+# ---------------------------------------------------------------- diagnostics
+
+
+@router.get("/investigations/{inv_id}/diagnostics/{stage_key}")
+def stage_diagnostics(inv_id: str, stage_key: str):
+    inv = _inv_or_404(inv_id)
+    if stage_key not in dg.STAGE_DIAGNOSTICS:
+        raise HTTPException(404, f"No diagnostic for stage {stage_key!r}")
+    data, findings = _battery(inv_id)[stage_key]
+    inv.upsert_auto_findings(stage_key, findings)
+    store.save_investigation(inv)
+    return {"stage": stage_key, "data": data,
+            "findings": [f.to_dict() for f in findings]}
+
+
+# ------------------------------------------------------- scoring and decision
+
+
+@router.get("/investigations/{inv_id}/scoreboard")
+def scoreboard(inv_id: str, recorded_only: bool = False):
+    inv = _inv_or_404(inv_id)
+    bundle = _bundle_or_404(inv_id)
+    if recorded_only:
+        return scoring.build_scoreboard(bundle, inv, recorded_only=True)
+    return scoring.build_scoreboard(bundle, inv, battery=_battery(inv_id))
+
+
+@router.post("/investigations/{inv_id}/scoreboard/assess")
+def assess_hypothesis(inv_id: str, req: AssessHypothesisRequest):
+    inv = _inv_or_404(inv_id)
+    if req.hypothesis not in ROOT_CAUSES:
+        raise HTTPException(400, f"Unknown hypothesis {req.hypothesis!r}")
+    inv.human_assessments[req.hypothesis] = {"confidence": req.confidence,
+                                             "note": req.note}
+    inv.log("human_assessment",
+            f"Human set {req.hypothesis} confidence to {req.confidence}",
+            {"note": req.note})
+    store.save_investigation(inv)
+    bundle = _bundle_or_404(inv_id)
+    return scoring.build_scoreboard(bundle, inv, battery=_battery(inv_id))
+
+
+@router.get("/investigations/{inv_id}/decision-tree")
+def decision_tree(inv_id: str):
+    bundle = _bundle_or_404(inv_id)
+    return scoring.evaluate_decision_tree(bundle, battery=_battery(inv_id))
+
+
+@router.get("/investigations/{inv_id}/experiments")
+def experiments(inv_id: str):
+    bundle = _bundle_or_404(inv_id)
+    return scoring.recommend_experiments(bundle, battery=_battery(inv_id))
+
+
+@router.get("/investigations/{inv_id}/report")
+def report(inv_id: str):
+    inv = _inv_or_404(inv_id)
+    bundle = _bundle_or_404(inv_id)
+    return report_mod.build_report(bundle, inv, battery=_battery(inv_id))

sensorflow/rca/diagnostics.py

@@ -0,0 +1,1029 @@
+"""Per-stage diagnostic computations.
+
+Every function takes a ScenarioBundle and returns (data, findings):
+    data      JSON-serializable payload for the UI table/visualization
+    findings  list of Finding records (auto evidence)
+
+Nothing here is invented: every number is computed from the investigation's
+offline/shadow unit data or its recorded configs.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import date
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.rca import stats as st
+from sensorflow.rca.models import Finding, make_finding
+from sensorflow.rca.scenario import FEATURES, SEGMENT_DIMS, ScenarioBundle
+
+LARGE_N_CAVEAT = (
+    "With thousands of units almost any difference is 'statistically "
+    "significant'; act on the practical-effect magnitude (PSI / JS labels), "
+    "not the p-value.")
+
+CONF_BANDS = ((0.0, 0.35), (0.35, 0.50), (0.50, 0.70), (0.70, 1.01))
+
+
+def _scored(bundle: ScenarioBundle) -> pd.DataFrame:
+    sh = bundle.shadow
+    return sh[sh["sampled"]]
+
+
+def _delta_pp(df: pd.DataFrame) -> float:
+    if len(df) == 0:
+        return 0.0
+    return float((df["b_correct"].mean() - df["a_correct"].mean()) * 100)
+
+
+def _parse_window(win: str) -> Optional[Tuple[date, date]]:
+    ds = re.findall(r"(\d{4})-(\d{2})-(\d{2})", win or "")
+    if len(ds) < 2:
+        return None
+    return (date(*map(int, ds[0])), date(*map(int, ds[1])))
+
+
+# ================================================== stage 0: comparison validity
+
+# (field, label, criticality-on-mismatch, expected-to-differ)
+_CV_FIELDS = [
+    ("metric_definition", "Metric definition", "CRITICAL", False),
+    ("aggregation", "Aggregation", "WARN", False),
+    ("eval_window", "Evaluation window", "WARN", True),
+    ("population_source", "Population source", "WARN", True),
+    ("confidence_threshold", "Confidence threshold", "CRITICAL", False),
+    ("quantization", "Numeric precision / quantization", "CRITICAL", False),
+    ("runtime_version", "Runtime version", "WARN", False),
+    ("nms_iou", "NMS IoU", "WARN", False),
+    ("feature_pipeline_version", "Feature pipeline version", "CRITICAL", False),
+    ("label_policy_version", "Labeling policy", "CRITICAL", False),
+    ("label_maturity_policy", "Label maturity policy", "WARN", True),
+    ("sampling_policy", "Sampling policy", "WARN", True),
+]
+
+
+def comparison_validity(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    off_cfg = bundle.meta["offline_config"]
+    sh_cfg = bundle.meta["shadow_config"]
+    rows: List[Dict] = []
+    findings: List[Finding] = []
+    stage = "comparison_validity"
+
+    for field, label, crit, expected_diff in _CV_FIELDS:
+        ov, sv = off_cfg.get(field), sh_cfg.get(field)
+        if ov is None or sv is None:
+            status = "unknown"
+            findings.append(make_finding(
+                stage, f"CV_UNKNOWN:{field}", f"{label} is unrecorded",
+                "UNKNOWN", crit,
+                f"Offline={ov!r}, shadow={sv!r}. You cannot certify the two "
+                f"numbers are comparable while {label.lower()} is unknown."))
+        elif ov == sv:
+            status = "comparable"
+        elif expected_diff:
+            status = "expected_difference"
+        else:
+            status = "mismatch"
+            findings.append(make_finding(
+                stage, f"CV_MISMATCH:{field}", f"{label} differs",
+                "MISMATCH", crit,
+                f"Offline={ov!r} vs shadow={sv!r}. The two measurements are "
+                "not measuring the same thing along this dimension.",
+                data={"offline": ov, "shadow": sv}))
+        rows.append({"field": field, "label": label, "offline": ov,
+                     "shadow": sv, "status": status,
+                     "criticality": crit})
+
+    # Window staleness: a large gap between offline eval window and the live
+    # shadow window is itself a validity hazard (world may have moved).
+    ow, sw = _parse_window(off_cfg.get("eval_window", "")), \
+        _parse_window(sh_cfg.get("eval_window", ""))
+    if ow and sw:
+        gap_days = (sw[0] - ow[1]).days
+        if gap_days > 45:
+            findings.append(make_finding(
+                stage, "CV_WINDOW_STALE", "Offline eval window is stale",
+                "MISMATCH", "WARN",
+                f"Offline window ends {ow[1].isoformat()}, shadow starts "
+                f"{sw[0].isoformat()} ({gap_days} days later). Data drift in "
+                "the gap can make both numbers correct on their own windows."))
+        rows.append({"field": "window_gap_days", "label": "Window gap (days)",
+                     "offline": ow[1].isoformat(), "shadow": sw[0].isoformat(),
+                     "status": "mismatch" if gap_days > 45 else "comparable",
+                     "criticality": "WARN", "gap_days": gap_days})
+
+    if not any(f.status != "PASS" for f in findings):
+        findings.append(make_finding(
+            stage, "CV_COMPARABLE", "No blocking comparability mismatch",
+            "PASS", "INFO",
+            "All recorded dimensions are comparable or expected differences."))
+
+    data = {"rows": rows,
+            "explainer": ("Dimension-by-dimension check that '+5% offline' and "
+                          "'-2% shadow' are even commensurable claims. Any "
+                          "mismatch row is a candidate explanation that must "
+                          "be ruled out before believing either number.")}
+    return data, findings
+
+
+# ======================================================= stage 1: offline audit
+
+
+def offline_audit(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "offline_audit"
+    findings: List[Finding] = []
+    off = bundle.offline
+    repro = bundle.meta["reproducibility"]
+    model_b = bundle.meta["model_b"]
+
+    orig = float(repro["original_offline_metric_delta"])
+    rerun = float(repro["rerun_metric_delta"])
+    diff = abs(rerun - orig)
+    reproduces = diff < 0.005
+    if reproduces:
+        findings.append(make_finding(
+            stage, "OA_REPRO_OK", "Offline result reproduces", "PASS", "INFO",
+            f"Re-run delta {rerun*100:+.2f}pp vs original {orig*100:+.2f}pp."))
+    else:
+        findings.append(make_finding(
+            stage, "OA_REPRO_FAIL", "Offline result does NOT reproduce",
+            "MISMATCH", "CRITICAL",
+            f"Re-running the baseline evaluation gives {rerun*100:+.2f}pp vs "
+            f"the claimed {orig*100:+.2f}pp (|diff| {diff*100:.2f}pp). An "
+            "irreproducible +5% is not evidence of anything."))
+    if repro["pins_present"]:
+        findings.append(make_finding(
+            stage, "OA_PINS_OK", "Version pins recorded", "PASS", "INFO",
+            repro["environment_lock"]))
+    else:
+        findings.append(make_finding(
+            stage, "OA_PINS_MISSING", "Version pins missing", "UNKNOWN", "WARN",
+            f"Environment: {repro['environment_lock']}. Cannot certify the "
+            "offline run's exact code/data state."))
+
+    # Leakage scan: near-duplicate flags + entity overlap with B's train set.
+    dup_mask = off["dup_similarity"] > 0.90
+    n_dup = int(dup_mask.sum())
+    train_ids = set(model_b.get("train_entity_ids", []))
+    overlap_entities = sorted(set(off["entity_id"]) & train_ids)
+    dup_frac = n_dup / max(1, len(off))
+    dup_delta = _delta_pp(off[dup_mask]) if n_dup else 0.0
+    clean_delta = _delta_pp(off[~dup_mask])
+    if n_dup > 0 or overlap_entities:
+        findings.append(make_finding(
+            stage, "OA_LEAKAGE_DUPLICATES", "Train/eval leakage detected",
+            "MISMATCH", "CRITICAL",
+            f"{n_dup} eval units ({dup_frac:.1%}) are near-duplicates "
+            f"(similarity>0.90) of candidate training data; "
+            f"{len(overlap_entities)} eval entities appear in B's training "
+            f"set. Delta on leaked units: {dup_delta:+.1f}pp vs "
+            f"{clean_delta:+.1f}pp on clean units.",
+            data={"n_duplicates": n_dup, "dup_fraction": dup_frac,
+                  "overlap_entity_count": len(overlap_entities),
+                  "dup_delta_pp": dup_delta, "clean_delta_pp": clean_delta}))
+    else:
+        findings.append(make_finding(
+            stage, "OA_LEAKAGE_CLEAN", "No leakage detected", "PASS", "INFO",
+            "No near-duplicates of candidate training data in the eval set; "
+            "no entity overlap with B's training entities."))
+
+    # Temporal leakage: eval window must start after B's training window ends.
+    eval_win = _parse_window(bundle.meta["offline_config"].get("eval_window", ""))
+    train_end = model_b.get("train_window", "").split("..")[-1].strip()
+    temporal_ok = True
+    if eval_win and re.match(r"\d{4}-\d{2}", train_end):
+        y, m = map(int, train_end.split("-")[:2])
+        temporal_ok = eval_win[0] >= date(y, m, 1)
+    findings.append(make_finding(
+        stage, "OA_TEMPORAL_OK" if temporal_ok else "OA_TEMPORAL_LEAK",
+        "Temporal split check", "PASS" if temporal_ok else "MISMATCH",
+        "INFO" if temporal_ok else "CRITICAL",
+        f"Eval window vs B train window ({model_b.get('train_window')})."))
+
+    split = model_b.get("split_strategy", "unknown")
+    if split == "row_level":
+        findings.append(make_finding(
+            stage, "OA_SPLIT_ROW_LEVEL", "Row-level split (correlated entities)",
+            "MISMATCH", "WARN",
+            "Train/eval split was row-level, so frames from the same drive "
+            "segment can straddle the boundary; correlated near-duplicates "
+            "inflate offline scores."))
+    else:
+        findings.append(make_finding(
+            stage, "OA_SPLIT_ENTITY_LEVEL", "Entity-level split", "PASS", "INFO",
+            "Split respects drive-segment boundaries."))
+
+    data = {
+        "reproducibility": {"original_delta_pp": orig * 100,
+                            "rerun_delta_pp": rerun * 100,
+                            "abs_diff_pp": diff * 100,
+                            "reproduces": reproduces,
+                            "pins_present": bool(repro["pins_present"]),
+                            "environment_lock": repro["environment_lock"]},
+        "leakage": {"n_duplicates": n_dup, "dup_fraction": dup_frac,
+                    "overlap_entity_count": len(overlap_entities),
+                    "overlap_examples": overlap_entities[:8],
+                    "dup_delta_pp": dup_delta, "clean_delta_pp": clean_delta,
+                    "offline_n": int(len(off))},
+        "split": {"strategy": split,
+                  "n_entities": int(off["entity_id"].nunique()),
+                  "mean_units_per_entity": float(len(off) / max(1, off["entity_id"].nunique()))},
+        "temporal": {"ok": temporal_ok,
+                     "b_train_window": model_b.get("train_window")},
+        "explainer": ("Audits the +5%% claim itself: does it reproduce, is the "
+                      "environment pinned, and is the eval set contaminated by "
+                      "the candidate's training data?"),
+    }
+    return data, findings
+
+
+# ================================================ stage 2: population validation
+
+
+def population_validation(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "population_validation"
+    findings: List[Finding] = []
+    off, sh = bundle.offline, bundle.shadow
+    scored = _scored(bundle)
+    traffic = bundle.meta["traffic"]
+
+    dim_tables = {}
+    for dim in SEGMENT_DIMS:
+        o = off[dim].value_counts(normalize=True)
+        s = scored[dim].value_counts(normalize=True)
+        cats = sorted(set(o.index) | set(s.index))
+        dim_tables[dim] = [{"value": c,
+                            "offline_share": float(o.get(c, 0.0)),
+                            "shadow_share": float(s.get(c, 0.0))}
+                           for c in cats]
+
+    overlap = len(set(off["entity_id"]) & set(sh["entity_id"]))
+    if len(scored) < 1000:
+        findings.append(make_finding(
+            stage, "POP_VOLUME_LOW", "Shadow scored volume is small",
+            "UNKNOWN", "CRITICAL",
+            f"Only {len(scored)} scored shadow units "
+            f"({sh['entity_id'].nunique()} drive segments). Aggregate deltas "
+            "at this volume are dominated by sampling noise; treat -2% as a "
+            "hypothesis, not a measurement."))
+    if len(off) < 1000:
+        findings.append(make_finding(
+            stage, "POP_SMALL_OFFLINE", "Offline eval set is small",
+            "UNKNOWN", "WARN",
+            f"Offline eval has only {len(off)} units."))
+    if len(scored) >= 1000 and len(off) >= 1000:
+        findings.append(make_finding(
+            stage, "POP_VOLUME_OK", "Volumes adequate", "PASS", "INFO",
+            f"Offline n={len(off)}, shadow scored n={len(scored)} "
+            f"(of {traffic['eligible_count']} eligible)."))
+
+    data = {
+        "volumes": {"offline_n": int(len(off)),
+                    "shadow_eligible_n": int(traffic["eligible_count"]),
+                    "shadow_scored_n": int(len(scored)),
+                    "sampling_rate": traffic["sampling_rate"],
+                    "offline_entities": int(off["entity_id"].nunique()),
+                    "shadow_entities": int(sh["entity_id"].nunique()),
+                    "entity_overlap": overlap},
+        "dimensions": dim_tables,
+        "explainer": ("Confirms both evaluations have enough volume to say "
+                      "anything, and shows the raw population composition "
+                      "side-by-side before any shift statistics."),
+    }
+    return data, findings
+
+
+# ================================================= stage 3: distribution shift
+
+
+def distribution_shift(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "distribution_shift"
+    findings: List[Finding] = []
+    off, scored = bundle.offline, _scored(bundle)
+    volume_ok = min(len(off), len(scored)) >= 800
+
+    seg_rows, feat_rows = [], []
+    seg_psis = {}
+    for dim in SEGMENT_DIMS:
+        psi = st.psi_categorical(off[dim], scored[dim])
+        js = st.js_divergence_categorical(off[dim], scored[dim])
+        chi, p = st.chi2_test(off[dim], scored[dim])
+        seg_psis[dim] = psi
+        seg_rows.append({"dimension": dim, "kind": "segment", "psi": psi,
+                         "js": js, "test": "chi2", "stat": chi, "p_value": p,
+                         "magnitude": st.shift_magnitude_label(psi)})
+
+    for feat in FEATURES:
+        a = off[feat].dropna().to_numpy()
+        b = scored[feat].dropna().to_numpy()
+        psi = st.psi_continuous(a, b)
+        js = st.js_divergence_continuous(a, b)
+        ks, p = st.ks_test(a, b)
+        feat_rows.append({"dimension": feat, "kind": "feature", "psi": psi,
+                          "js": js, "test": "ks", "stat": ks, "p_value": p,
+                          "magnitude": st.shift_magnitude_label(psi),
+                          "offline_mean": float(np.mean(a)),
+                          "shadow_mean": float(np.mean(b))})
+
+    if not volume_ok:
+        findings.append(make_finding(
+            stage, "DS_VOLUME_TOO_SMALL",
+            "Too little data to assess distribution shift",
+            "UNKNOWN", "WARN",
+            f"Only {len(off)} offline / {len(scored)} scored shadow units. "
+            "PSI estimates are upward-biased at this volume; shift can be "
+            "neither confirmed nor excluded."))
+        data = {"segments": seg_rows, "features": feat_rows,
+                "caveat": LARGE_N_CAVEAT, "volume_ok": False,
+                "explainer": ("Per-dimension PSI + Jensen-Shannon + KS/"
+                              "chi-square with BOTH significance and practical "
+                              "magnitude.")}
+        return data, findings
+
+    high_segs = [d for d, v in seg_psis.items() if v >= 0.25]
+    for dim in high_segs:
+        findings.append(make_finding(
+            stage, f"DS_SHIFT_HIGH:{dim}", f"Large population shift on {dim}",
+            "MISMATCH", "CRITICAL" if seg_psis[dim] >= 0.5 else "WARN",
+            f"PSI={seg_psis[dim]:.2f} ({st.shift_magnitude_label(seg_psis[dim])}). "
+            "Offline and shadow are scoring materially different populations; "
+            "aggregate deltas are not directly comparable. " + LARGE_N_CAVEAT,
+            data={"psi": seg_psis[dim]}))
+
+    if not high_segs and all(v < 0.10 for v in seg_psis.values()):
+        findings.append(make_finding(
+            stage, "DS_SHIFT_LOW", "Population mix is stable", "PASS", "INFO",
+            f"All segment-dimension PSIs < 0.10 "
+            f"({', '.join(f'{d}={v:.03f}' for d, v in seg_psis.items())})."))
+
+    # A single feature shifting hugely while the population mix is stable is
+    # the signature of a pipeline artifact, not a population change.
+    if all(v < 0.10 for v in seg_psis.values()):
+        for row in feat_rows:
+            if row["psi"] >= 0.5:
+                findings.append(make_finding(
+                    stage, f"DS_FEATURE_ONLY_SHIFT:{row['dimension']}",
+                    f"Isolated shift in {row['dimension']} despite stable mix",
+                    "MISMATCH", "WARN",
+                    f"{row['dimension']} PSI={row['psi']:.2f} while all segment "
+                    "mixes are stable -- consistent with a feature-pipeline "
+                    "artifact rather than a real-world change. Check feature "
+                    "parity (stage 7).",
+                    data={"psi": row["psi"],
+                          "offline_mean": row["offline_mean"],
+                          "shadow_mean": row["shadow_mean"]}))
+
+    data = {"segments": seg_rows, "features": feat_rows,
+            "caveat": LARGE_N_CAVEAT, "volume_ok": True,
+            "explainer": ("Per-dimension PSI + Jensen-Shannon + KS/chi-square "
+                          "with BOTH significance and practical magnitude. "
+                          "Large shift means the -2% may be measured on a "
+                          "different world than the +5%.")}
+    return data, findings
+
+
+# ============================================ stage 4: conditional performance
+
+
+def conditional_performance(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "conditional_performance"
+    findings: List[Finding] = []
+    off, scored = bundle.offline, _scored(bundle)
+
+    rows = []
+    agg_off, agg_sh = _delta_pp(off), _delta_pp(scored)
+    total_neg_contrib = 0.0
+    contribs: List[Tuple[str, float]] = []
+    consistent_volume = 0
+    neg_volume = 0
+
+    for (scene, tod), o_seg in off.groupby(["scene", "time_of_day"]):
+        s_seg = scored[(scored["scene"] == scene) & (scored["time_of_day"] == tod)]
+        od, sd = _delta_pp(o_seg), _delta_pp(s_seg)
+        off_share = len(o_seg) / len(off)
+        sh_share = len(s_seg) / max(1, len(scored))
+        seg_name = f"{scene}/{tod}"
+        low_vol = len(s_seg) < 60 or len(o_seg) < 60
+        if low_vol:
+            interp = "low_volume"
+        elif od > 0.5 and sd > 0.5:
+            interp = "consistent_improvement"
+        elif od < -0.5 and sd < -0.5:
+            interp = "consistent_regression"
+        elif od > 0.5 and sd < -0.5:
+            interp = "sign_flip"
+        else:
+            interp = "flat"
+        rows.append({"segment": seg_name, "scene": scene, "time_of_day": tod,
+                     "offline_delta_pp": od, "shadow_delta_pp": sd,
+                     "offline_n": int(len(o_seg)), "shadow_n": int(len(s_seg)),
+                     "offline_share": off_share, "shadow_share": sh_share,
+                     "shift_ratio": sh_share / max(1e-9, off_share),
+                     "interpretation": interp})
+        if not low_vol:
+            if np.sign(od) == np.sign(sd) and abs(od) > 0.5 and abs(sd) > 0.5:
+                consistent_volume += len(s_seg)
+            if sd < 0:
+                neg_volume += len(s_seg)
+                contrib = sh_share * sd
+                total_neg_contrib += contrib
+                contribs.append((seg_name, contrib))
+
+    rows.sort(key=lambda r: r["shadow_delta_pp"])
+    consistency = consistent_volume / max(1, len(scored))
+
+    # Simpson's requires the mix to have actually moved: within-segment sign
+    # agreement plus an aggregate flip is only a mix artifact if the segment
+    # composition differs between the two evaluations.
+    mix_psi = max(st.psi_categorical(off["scene"], scored["scene"]),
+                  st.psi_categorical(off["time_of_day"], scored["time_of_day"]))
+    simpsons = (agg_off > 0.5 and agg_sh < -0.5 and consistency >= 0.55
+                and mix_psi >= 0.25)
+    if simpsons:
+        findings.append(make_finding(
+            stage, "CP_SIMPSONS_DETECTED",
+            "Simpson's paradox: aggregate flip explained by mix",
+            "MISMATCH", "CRITICAL",
+            f"Aggregate offline {agg_off:+.1f}pp vs shadow {agg_sh:+.1f}pp, "
+            f"yet within-segment deltas agree in sign on {consistency:.0%} of "
+            "scored volume. The sign flip comes from WHERE the traffic is, "
+            "not from the model changing behavior.",
+            data={"consistency": consistency, "agg_offline_pp": agg_off,
+                  "agg_shadow_pp": agg_sh}))
+    elif contribs:
+        contribs.sort(key=lambda c: c[1])
+        # Concentration is checked at segment level and along each single
+        # dimension (all-highway regression should register even when split
+        # across highway/day, highway/dusk, highway/night).
+        grouped: Dict[str, float] = {}
+        for seg_name, contrib in contribs:
+            scene, tod = seg_name.split("/")
+            grouped[seg_name] = grouped.get(seg_name, 0.0) + contrib
+            grouped[f"scene={scene}"] = grouped.get(f"scene={scene}", 0.0) + contrib
+            grouped[f"time={tod}"] = grouped.get(f"time={tod}", 0.0) + contrib
+        top_seg, top_contrib = min(grouped.items(), key=lambda kv: kv[1])
+        top_share = top_contrib / total_neg_contrib if total_neg_contrib < 0 else 0.0
+        if top_share >= 0.55:
+            findings.append(make_finding(
+                stage, f"CP_SEGMENT_CONCENTRATED:{top_seg}",
+                f"Shadow regression concentrated in {top_seg}",
+                "MISMATCH", "WARN",
+                f"{top_share:.0%} of the total shadow regression comes from "
+                f"{top_seg}. A concentrated regression points at something "
+                "that segment depends on (a feature, a sensor mode), not a "
+                "global model change.",
+                data={"segment": top_seg, "share_of_regression": top_share}))
+        elif neg_volume / max(1, len(scored)) >= 0.6:
+            findings.append(make_finding(
+                stage, "CP_UNIFORM_REGRESSION",
+                "Shadow regression is broad-based",
+                "MISMATCH", "WARN",
+                f"{neg_volume / max(1, len(scored)):.0%} of scored volume sits "
+                "in segments with negative shadow delta and no single segment "
+                "dominates -- consistent with a genuine model-level change.",
+                data={"negative_volume_share": neg_volume / max(1, len(scored))}))
+
+    if not findings:
+        findings.append(make_finding(
+            stage, "CP_NO_PATTERN", "No dominant conditional pattern",
+            "PASS", "INFO",
+            "Per-segment deltas show no Simpson flip, concentration, or "
+            "uniform regression above thresholds."))
+
+    data = {"rows": rows, "aggregate": {"offline_delta_pp": agg_off,
+                                        "shadow_delta_pp": agg_sh,
+                                        "sign_consistency": consistency},
+            "explainer": ("Segment x (offline delta, shadow delta, volume, "
+                          "shift) matrix. This is where Simpson's paradox "
+                          "becomes visible: per-segment agreement with an "
+                          "aggregate sign flip means the mix, not the model.")}
+    return data, findings
+
+
+# ================================================ stage 5: paired comparison
+
+
+def paired_comparison(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "paired_comparison"
+    findings: List[Finding] = []
+    scored = _scored(bundle)
+    off = bundle.offline
+
+    def matrix(df: pd.DataFrame) -> Dict:
+        a, b = df["a_correct"] == 1, df["b_correct"] == 1
+        return {"both_correct": int((a & b).sum()),
+                "regressions": int((a & ~b).sum()),
+                "improvements": int((~a & b).sum()),
+                "both_wrong": int((~a & ~b).sum()),
+                "n": int(len(df)),
+                "net_pp": _delta_pp(df)}
+
+    overall = matrix(scored)
+    offline_overall = matrix(off)
+
+    by_segment = []
+    for (scene, tod), g in scored.groupby(["scene", "time_of_day"]):
+        m = matrix(g)
+        m["segment"] = f"{scene}/{tod}"
+        by_segment.append(m)
+    by_class = []
+    for cls, g in scored.groupby("object_class"):
+        m = matrix(g)
+        m["segment"] = cls
+        by_class.append(m)
+
+    by_band = []
+    conf_col = "b_conf_serving" if "b_conf_serving" in scored.columns else "b_conf"
+    total_reg = max(1, overall["regressions"])
+    band_reg_share = {}
+    for lo, hi in CONF_BANDS:
+        g = scored[(scored[conf_col] >= lo) & (scored[conf_col] < hi)]
+        m = matrix(g)
+        m["segment"] = f"[{lo:.2f}, {hi:.2f})"
+        m["unit_share"] = len(g) / max(1, len(scored))
+        m["regression_share"] = m["regressions"] / total_reg
+        m["lift"] = (m["regression_share"] / m["unit_share"]
+                     if m["unit_share"] > 0 else 0.0)
+        band_reg_share[(lo, hi)] = m
+        by_band.append(m)
+
+    focus = band_reg_share.get((0.35, 0.50))
+    if focus and focus["lift"] >= 1.5 and focus["regression_share"] >= 0.30:
+        findings.append(make_finding(
+            stage, "PC_CONF_BAND_CONCENTRATION",
+            "Regressions concentrated in the 0.35-0.50 confidence band",
+            "MISMATCH", "CRITICAL",
+            f"{focus['regression_share']:.0%} of A-correct->B-incorrect "
+            f"transitions sit in the [0.35, 0.50) serving-confidence band, "
+            f"{focus['lift']:.1f}x its traffic share. That band is exactly "
+            "where a serving-threshold difference would delete detections.",
+            data={"lift": focus["lift"],
+                  "regression_share": focus["regression_share"]}))
+
+    if overall["regressions"] > overall["improvements"] * 1.15:
+        findings.append(make_finding(
+            stage, "PC_NET_REGRESSION", "Net regression transitions in shadow",
+            "MISMATCH", "WARN",
+            f"{overall['regressions']} regression transitions vs "
+            f"{overall['improvements']} improvements on identical units "
+            f"(net {overall['net_pp']:+.1f}pp).",
+            data={"regressions": overall["regressions"],
+                  "improvements": overall["improvements"]}))
+    else:
+        findings.append(make_finding(
+            stage, "PC_BALANCED", "Transitions roughly balanced", "PASS", "INFO",
+            f"{overall['regressions']} regressions vs "
+            f"{overall['improvements']} improvements."))
+
+    data = {"shadow": overall, "offline": offline_overall,
+            "by_segment": by_segment, "by_class": by_class, "by_band": by_band,
+            "conf_col": conf_col,
+            "explainer": ("Error-transition matrix on the SAME units: "
+                          "A-correct->B-incorrect (regressions) vs "
+                          "A-incorrect->B-correct (improvements), sliced by "
+                          "segment, class, and serving-confidence band.")}
+    return data, findings
+
+
+# ============================================== stage 6: statistical significance
+
+
+def _seqeval_snapshot(scored: pd.DataFrame, margin: float) -> Optional[Dict]:
+    """Complementary anytime-valid evidence from sensorflow.seqeval, if the
+    package is available. The fixed-n cluster-robust CI stays the verdict
+    driver for this stage (one batch, one pre-committed look); the sequential
+    snapshot answers the different question 'could we have stopped early /
+    keep monitoring without alpha-spending'."""
+    try:
+        from sensorflow.seqeval import units as sq_units
+        from sensorflow.seqeval.sequential import PairedSequentialTest
+    except Exception:
+        return None
+    d = (scored["b_correct"] - scored["a_correct"]).to_numpy().astype(float)
+    means, _sizes = sq_units.cluster_units(d, scored["entity_id"].to_numpy())
+    order = np.random.default_rng(0).permutation(len(means))
+    test = PairedSequentialTest(delta=margin, alpha=0.05)
+    test.update_clusters(means[order])
+    test.record_objects(scored["a_correct"].to_numpy().astype(bool),
+                        scored["b_correct"].to_numpy().astype(bool))
+    test.evaluate()
+    snap = test.snapshot()
+    snap["note"] = (
+        "Anytime-valid empirical-Bernstein confidence sequence "
+        "(sensorflow.seqeval). Wider than the fixed-n CI by design: it stays "
+        "valid under continuous monitoring and optional stopping.")
+    return snap
+
+
+def statistical_significance(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "statistical_significance"
+    findings: List[Finding] = []
+    scored = _scored(bundle)
+    off = bundle.offline
+    margin = float(bundle.meta.get("practical_margin_pp", 1.0)) / 100.0
+
+    seq_snap = _seqeval_snapshot(scored, margin)
+    engine = "local+seqeval" if seq_snap is not None else "local"
+    sh_res = st.paired_delta_cluster(scored)
+    off_res = st.paired_delta_cluster(off)
+    outcome = st.three_way_outcome(sh_res["delta"], sh_res["ci_low"],
+                                   sh_res["ci_high"], margin)
+
+    wilson = {}
+    for name, df, col in (("offline_a", off, "a_correct"),
+                          ("offline_b", off, "b_correct"),
+                          ("shadow_a", scored, "a_correct"),
+                          ("shadow_b", scored, "b_correct")):
+        lo, hi = st.wilson_ci(int(df[col].sum()), len(df))
+        wilson[name] = {"rate": float(df[col].mean()), "ci_low": lo, "ci_high": hi,
+                        "n": int(len(df))}
+
+    if outcome == "significant_regression":
+        findings.append(make_finding(
+            stage, "SS_SIGNIFICANT_REGRESSION",
+            "Shadow regression is significant beyond the practical margin",
+            "MISMATCH", "CRITICAL",
+            f"Paired delta {sh_res['delta']*100:+.2f}pp, 95% CI "
+            f"[{sh_res['ci_low']*100:+.2f}, {sh_res['ci_high']*100:+.2f}]pp, "
+            f"entirely below the -{margin*100:.1f}pp practical margin "
+            f"(cluster-aware, effective n={sh_res['effective_n']}).",
+            data=sh_res))
+    elif outcome == "no_significant_difference":
+        findings.append(make_finding(
+            stage, "SS_NO_SIG_DIFF",
+            "No practically-important difference detectable",
+            "PASS", "INFO",
+            f"95% CI [{sh_res['ci_low']*100:+.2f}, {sh_res['ci_high']*100:+.2f}]pp "
+            f"excludes a regression beyond -{margin*100:.1f}pp.",
+            data=sh_res))
+    else:
+        findings.append(make_finding(
+            stage, "SS_INSUFFICIENT_EVIDENCE",
+            "Insufficient evidence to call the shadow delta",
+            "UNKNOWN", "CRITICAL",
+            f"Paired delta {sh_res['delta']*100:+.2f}pp with 95% CI "
+            f"[{sh_res['ci_low']*100:+.2f}, {sh_res['ci_high']*100:+.2f}]pp "
+            f"spans the practical margin. Effective n is only "
+            f"{sh_res['effective_n']} (design effect "
+            f"{sh_res['design_effect']:.1f} from {sh_res['n_clusters']} "
+            "clusters). Neither 'regression' nor 'fine' is supported.",
+            data=sh_res))
+
+    if sh_res["effective_n"] < 800:
+        findings.append(make_finding(
+            stage, "SS_LOW_ESS", "Low effective sample size", "UNKNOWN", "WARN",
+            f"Cluster correlation shrinks {sh_res['n']} units to an effective "
+            f"n of {sh_res['effective_n']}.",
+            data={"effective_n": sh_res["effective_n"],
+                  "design_effect": sh_res["design_effect"]}))
+
+    data = {"engine": engine,
+            "engine_note": ("Verdict: fixed-n cluster-robust paired CI (valid "
+                            "for this single pre-committed look). "
+                            + ("Complementary anytime-valid confidence "
+                               "sequence from sensorflow.seqeval attached."
+                               if seq_snap is not None else
+                               "sensorflow.seqeval not importable; local "
+                               "Wilson/paired implementation only.")),
+            "practical_margin_pp": margin * 100,
+            "shadow_paired": sh_res, "offline_paired": off_res,
+            "outcome": outcome, "wilson": wilson,
+            "seqeval": seq_snap,
+            "explainer": ("Paired B-A delta with cluster-aware effective "
+                          "sample size and a minimum practically-important "
+                          "regression margin. Three-way verdict: significant "
+                          "regression / no significant difference / "
+                          "insufficient evidence.")}
+    return data, findings
+
+
+# ==================================================== stage 7: feature parity
+
+
+def feature_parity(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "feature_parity"
+    findings: List[Finding] = []
+    off, scored = bundle.offline, _scored(bundle)
+
+    rows = []
+    for feat in FEATURES:
+        a, b = off[feat], scored[feat]
+        a_clean, b_clean = a.dropna(), b.dropna()
+        pooled_sd = float(np.sqrt((a_clean.std() ** 2 + b_clean.std() ** 2) / 2))
+        smd = abs(float(b_clean.mean() - a_clean.mean())) / max(pooled_sd, 1e-9)
+
+        # Within-segment SMD controls for population mix: a real-world shift
+        # moves the mix, a pipeline skew moves the values inside segments too.
+        seg_smds, seg_ws = [], []
+        for (scene, tod), g_off in off.groupby(["scene", "time_of_day"]):
+            g_sh = scored[(scored["scene"] == scene)
+                          & (scored["time_of_day"] == tod)]
+            if len(g_sh) < 40 or len(g_off) < 40:
+                continue
+            ac, bc = g_off[feat].dropna(), g_sh[feat].dropna()
+            sd = float(np.sqrt((ac.std() ** 2 + bc.std() ** 2) / 2))
+            seg_smds.append(abs(float(bc.mean() - ac.mean())) / max(sd, 1e-9))
+            seg_ws.append(len(g_sh))
+        within_smd = (float(np.average(seg_smds, weights=seg_ws))
+                      if seg_smds else smd)
+
+        q_off = a_clean.quantile([0.05, 0.5, 0.95])
+        q_sh = b_clean.quantile([0.05, 0.5, 0.95])
+        median_ratio = float(q_sh[0.5] / q_off[0.5]) if q_off[0.5] else float("nan")
+        miss_off = float(a.isna().mean())
+        miss_sh = float(b.isna().mean())
+        skew = within_smd >= 1.0
+        rows.append({"feature": feat,
+                     "offline_mean": float(a_clean.mean()),
+                     "shadow_mean": float(b_clean.mean()),
+                     "offline_p5": float(q_off[0.05]), "offline_p50": float(q_off[0.5]),
+                     "offline_p95": float(q_off[0.95]),
+                     "shadow_p5": float(q_sh[0.05]), "shadow_p50": float(q_sh[0.5]),
+                     "shadow_p95": float(q_sh[0.95]),
+                     "smd": smd, "within_segment_smd": within_smd,
+                     "median_ratio": median_ratio,
+                     "offline_missing": miss_off, "shadow_missing": miss_sh,
+                     "missing_delta": miss_sh - miss_off,
+                     "skew_flag": bool(skew)})
+
+    rows.sort(key=lambda r: r["within_segment_smd"], reverse=True)
+    for r in rows:
+        if r["skew_flag"]:
+            findings.append(make_finding(
+                stage, f"FP_FEATURE_SKEW:{r['feature']}",
+                f"Training-serving skew on {r['feature']}",
+                "MISMATCH", "CRITICAL",
+                f"{r['feature']}: shadow mean {r['shadow_mean']:.2f} vs offline "
+                f"{r['offline_mean']:.2f} (median ratio {r['median_ratio']:.2f}, "
+                f"within-segment SMD {r['within_segment_smd']:.2f}). The value "
+                "distribution differs INSIDE matched segments, so this is a "
+                "pipeline difference (unit/normalization), not a population "
+                "change.",
+                data={"feature": r["feature"],
+                      "median_ratio": r["median_ratio"],
+                      "within_segment_smd": r["within_segment_smd"]}))
+        elif abs(r["missing_delta"]) > 0.02:
+            findings.append(make_finding(
+                stage, f"FP_MISSINGNESS_DELTA:{r['feature']}",
+                f"Missingness differs on {r['feature']}", "MISMATCH", "WARN",
+                f"Missing offline {r['offline_missing']:.1%} vs shadow "
+                f"{r['shadow_missing']:.1%}."))
+    if not any(f.status == "MISMATCH" and f.severity == "CRITICAL"
+               for f in findings):
+        findings.append(make_finding(
+            stage, "FP_CLEAN", "No training-serving feature skew", "PASS", "INFO",
+            "All features have within-segment SMD < 1.0 and stable "
+            "missingness."))
+
+    data = {"rows": rows,
+            "explainer": ("Per-feature offline vs shadow deltas ranked by "
+                          "WITHIN-SEGMENT standardized mean difference -- the "
+                          "statistic that separates 'the world changed' from "
+                          "'the pipeline computes this feature differently "
+                          "online'.")}
+    return data, findings
+
+
+# ==================================================== stage 8: serving parity
+
+_SERVING_FIELDS = [
+    ("confidence_threshold", "Confidence threshold", "CRITICAL"),
+    ("quantization", "Quantization / precision", "CRITICAL"),
+    ("runtime_version", "Runtime version", "WARN"),
+    ("nms_iou", "NMS IoU threshold", "WARN"),
+    ("feature_pipeline_version", "Feature pipeline version", "CRITICAL"),
+]
+
+
+def serving_parity(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "serving_parity"
+    findings: List[Finding] = []
+    off_cfg, sh_cfg = bundle.meta["offline_config"], bundle.meta["shadow_config"]
+
+    rows = []
+    for field, label, crit in _SERVING_FIELDS:
+        ov, sv = off_cfg.get(field), sh_cfg.get(field)
+        if ov is None or sv is None:
+            status = "unknown"
+            findings.append(make_finding(
+                stage, f"SP_UNKNOWN:{field}", f"{label} unrecorded in shadow",
+                "UNKNOWN", crit,
+                f"Offline={ov!r}, shadow={sv!r}. Serving parity cannot be "
+                "certified while this artifact/config is unrecorded."))
+        elif ov != sv:
+            status = "mismatch"
+            findings.append(make_finding(
+                stage, f"SP_CONFIG_DIFF:{field}", f"{label} differs in serving",
+                "MISMATCH", crit,
+                f"Offline={ov!r} vs shadow={sv!r}. The shadow stack is not "
+                "running the model the offline harness evaluated.",
+                data={"offline": ov, "shadow": sv}))
+        else:
+            status = "match"
+        rows.append({"field": field, "label": label, "offline": ov,
+                     "shadow": sv, "status": status, "criticality": crit})
+
+    if not findings:
+        findings.append(make_finding(
+            stage, "SP_CLEAN", "Serving config at parity", "PASS", "INFO",
+            "All recorded serving artifacts/configs match the offline harness."))
+
+    data = {"rows": rows,
+            "explainer": ("Artifact/config diff between the offline harness "
+                          "and the shadow serving stack: threshold, precision "
+                          "mode, runtime, NMS, feature pipeline.")}
+    return data, findings
+
+
+# ================================================== stage 9: shadow traffic
+
+
+def shadow_traffic(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "shadow_traffic"
+    findings: List[Finding] = []
+    sh = bundle.shadow
+    scored = _scored(bundle)
+    unsampled = sh[~sh["sampled"]]
+    traffic = dict(bundle.meta["traffic"])
+
+    diff_psi = st.psi_continuous(sh["difficulty"].to_numpy(),
+                                 scored["difficulty"].to_numpy())
+    conf_psi = st.psi_continuous(sh["a_conf"].to_numpy(),
+                                 scored["a_conf"].to_numpy())
+    seg_psi = st.psi_categorical(sh["time_of_day"], scored["time_of_day"])
+    sampled_delta = _delta_pp(scored)
+    eligible_delta = _delta_pp(sh)
+    unsampled_delta = _delta_pp(unsampled)
+    gap = abs(sampled_delta - unsampled_delta)
+
+    drop_rate = (traffic["dropped_count"] + traffic["fallback_count"]
+                 + traffic["timeout_count"]) / max(1, traffic["eligible_count"])
+
+    if diff_psi >= 0.1 or conf_psi >= 0.1 or (gap >= 4.0 and diff_psi >= 0.03):
+        findings.append(make_finding(
+            stage, "ST_SELECTION_BIAS", "Shadow sample is selection-biased",
+            "MISMATCH", "CRITICAL",
+            f"Scored sample differs from the eligible stream: difficulty "
+            f"PSI={diff_psi:.2f}, confidence PSI={conf_psi:.2f}. Sampled delta "
+            f"{sampled_delta:+.1f}pp vs unsampled {unsampled_delta:+.1f}pp "
+            f"(eligible stream {eligible_delta:+.1f}pp). The -2% is a "
+            "statement about the sampler, not the traffic.",
+            data={"difficulty_psi": diff_psi, "conf_psi": conf_psi,
+                  "sampled_delta_pp": sampled_delta,
+                  "unsampled_delta_pp": unsampled_delta,
+                  "eligible_delta_pp": eligible_delta,
+                  "sampler": traffic.get("sampler")}))
+    else:
+        findings.append(make_finding(
+            stage, "ST_SAMPLE_FAIR", "Scored sample matches eligible stream",
+            "PASS", "INFO",
+            f"Difficulty PSI={diff_psi:.3f}, confidence PSI={conf_psi:.3f}, "
+            f"sampled vs unsampled delta gap {gap:.1f}pp."))
+
+    if drop_rate > 0.05:
+        findings.append(make_finding(
+            stage, "ST_DROPS_HIGH", "High dropped/fallback/timeout rate",
+            "MISMATCH", "WARN",
+            f"{drop_rate:.1%} of eligible traffic was dropped, timed out, or "
+            "ran the fallback stack -- those frames never enter the shadow "
+            "metric.",
+            data={"drop_rate": drop_rate}))
+
+    data = {"traffic": traffic,
+            "selection": {"difficulty_psi": diff_psi, "conf_psi": conf_psi,
+                          "segment_psi": seg_psi,
+                          "sampled_delta_pp": sampled_delta,
+                          "unsampled_delta_pp": unsampled_delta,
+                          "eligible_delta_pp": eligible_delta,
+                          "gap_pp": gap, "drop_rate": drop_rate},
+            "explainer": ("Audit of what the shadow sampler actually scored: "
+                          "sampling rate, eligibility filters, drops, and "
+                          "whether the scored sample statistically matches "
+                          "the eligible stream.")}
+    return data, findings
+
+
+# ================================================ stage 10: label integrity
+
+
+def label_integrity(bundle: ScenarioBundle) -> Tuple[Dict, List[Finding]]:
+    stage = "label_integrity"
+    findings: List[Finding] = []
+    scored = _scored(bundle)
+    maturity_h = float(bundle.meta.get("label_maturity_hours", 72.0))
+    off_cfg, sh_cfg = bundle.meta["offline_config"], bundle.meta["shadow_config"]
+
+    prov = scored["label_is_provisional"] == True  # noqa: E712 (CSV round-trip)
+    prov_frac = float(prov.mean())
+    mature = scored[~prov]
+    provisional = scored[prov]
+    mature_delta = _delta_pp(mature)
+    prov_delta = _delta_pp(provisional)
+
+    ages = scored["label_age_hours"]
+    hist_edges = [0, 24, 48, 72, 120, 240, 480]
+    hist = []
+    for lo, hi in zip(hist_edges[:-1], hist_edges[1:]):
+        hist.append({"bucket": f"{lo}-{hi}h",
+                     "count": int(((ages >= lo) & (ages < hi)).sum())})
+    hist.append({"bucket": f">{hist_edges[-1]}h",
+                 "count": int((ages >= hist_edges[-1]).sum())})
+
+    by_quartile = []
+    q = pd.qcut(scored["difficulty"], 4, labels=["q1", "q2", "q3", "q4"],
+                duplicates="drop")
+    for label, g in scored.groupby(q, observed=False):
+        gp = g[g["label_is_provisional"] == True]  # noqa: E712
+        by_quartile.append({
+            "quartile": str(label),
+            "provisional_frac": float((g["label_is_provisional"] == True).mean()),
+            "delta_pp": _delta_pp(g),
+            "provisional_delta_pp": _delta_pp(gp) if len(gp) >= 30 else None,
+            "n": int(len(g))})
+
+    policy_diff = off_cfg.get("label_policy_version") != sh_cfg.get("label_policy_version")
+
+    if prov_frac > 0.2:
+        findings.append(make_finding(
+            stage, "LI_PROVISIONAL_HIGH", "Large provisional-label fraction",
+            "MISMATCH", "WARN",
+            f"{prov_frac:.0%} of scored shadow units are graded against "
+            f"provisional labels younger than {maturity_h:.0f}h.",
+            data={"provisional_fraction": prov_frac}))
+    if prov_frac > 0.1 and len(mature) > 200 and (mature_delta - prov_delta) > 4.0:
+        findings.append(make_finding(
+            stage, "LI_MATURE_DIVERGES",
+            "Verdict flips on mature labels",
+            "MISMATCH", "CRITICAL",
+            f"On mature labels the paired delta is {mature_delta:+.1f}pp; on "
+            f"provisional labels it is {prov_delta:+.1f}pp. The -2% is a "
+            "property of the provisional labels, not of the model.",
+            data={"mature_delta_pp": mature_delta,
+                  "provisional_delta_pp": prov_delta}))
+    if len(by_quartile) == 4:
+        q1, q4 = by_quartile[0], by_quartile[-1]
+        if (q1["provisional_delta_pp"] is not None
+                and q4["provisional_delta_pp"] is not None
+                and (q1["provisional_delta_pp"] - q4["provisional_delta_pp"]) > 6.0):
+            findings.append(make_finding(
+                stage, "LI_DIFFICULTY_CORRELATED",
+                "Provisional-label penalty concentrates on hard cases",
+                "MISMATCH", "WARN",
+                f"Provisional-subset delta falls from "
+                f"{q1['provisional_delta_pp']:+.1f}pp (easiest quartile) to "
+                f"{q4['provisional_delta_pp']:+.1f}pp (hardest) -- the classic "
+                "signature of pseudo-labels that are wrong on hard cases."))
+    if policy_diff:
+        findings.append(make_finding(
+            stage, "LI_POLICY_DIFF", "Labeling policy version differs",
+            "MISMATCH", "WARN",
+            f"Offline: {off_cfg.get('label_policy_version')!r} vs shadow: "
+            f"{sh_cfg.get('label_policy_version')!r}."))
+    if not findings:
+        findings.append(make_finding(
+            stage, "LI_CLEAN", "Labels look trustworthy", "PASS", "INFO",
+            f"Provisional fraction {prov_frac:.1%}; mature-label delta "
+            f"({mature_delta:+.1f}pp) consistent with the overall shadow "
+            "verdict; same labeling policy."))
+
+    data = {"provisional_fraction": prov_frac,
+            "maturity_hours": maturity_h,
+            "age_histogram": hist,
+            "mature_delta_pp": mature_delta,
+            "provisional_delta_pp": prov_delta,
+            "mature_n": int(len(mature)), "provisional_n": int(len(provisional)),
+            "by_difficulty_quartile": by_quartile,
+            "policy": {"offline": off_cfg.get("label_policy_version"),
+                       "shadow": sh_cfg.get("label_policy_version"),
+                       "differs": bool(policy_diff)},
+            "explainer": ("Are shadow 'ground truth' labels actually ground "
+                          "truth? Label age distribution, provisional "
+                          "fraction, difficulty correlation, and the "
+                          "mature-vs-provisional verdict split.")}
+    return data, findings
+
+
+# ------------------------------------------------------------------ registry
+
+STAGE_DIAGNOSTICS = {
+    "comparison_validity": comparison_validity,
+    "offline_audit": offline_audit,
+    "population_validation": population_validation,
+    "distribution_shift": distribution_shift,
+    "conditional_performance": conditional_performance,
+    "paired_comparison": paired_comparison,
+    "statistical_significance": statistical_significance,
+    "feature_parity": feature_parity,
+    "serving_parity": serving_parity,
+    "shadow_traffic": shadow_traffic,
+    "label_integrity": label_integrity,
+}
+
+
+def run_all(bundle: ScenarioBundle) -> Dict[str, Tuple[Dict, List[Finding]]]:
+    """Run the full diagnostic battery (used by scoring, reports, tests)."""
+    return {key: fn(bundle) for key, fn in STAGE_DIAGNOSTICS.items()}

sensorflow/rca/models.py

@@ -0,0 +1,296 @@
+"""Core RCA entities: stages, findings, and the Investigation state machine."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import asdict, dataclass, field
+from typing import Dict, List, Optional
+
+# --------------------------------------------------------------------- stages
+
+STAGES: List[Dict] = [
+    {"index": 0, "key": "comparison_validity", "title": "Comparison Validity",
+     "question": "Are the offline and shadow numbers even measuring the same thing?"},
+    {"index": 1, "key": "offline_audit", "title": "Offline Audit",
+     "question": "Can the offline +5% be reproduced, and is the eval set leak-free?"},
+    {"index": 2, "key": "population_validation", "title": "Population Validation",
+     "question": "Do the two evaluations see comparable populations and volumes?"},
+    {"index": 3, "key": "distribution_shift", "title": "Distribution Shift",
+     "question": "How different are the offline and shadow data distributions?"},
+    {"index": 4, "key": "conditional_performance", "title": "Conditional Performance",
+     "question": "Where (which segments) does the delta live in each environment?"},
+    {"index": 5, "key": "paired_comparison", "title": "Paired Model Comparison",
+     "question": "On the same units, which predictions flipped between A and B?"},
+    {"index": 6, "key": "statistical_significance", "title": "Statistical Significance",
+     "question": "Is the shadow regression distinguishable from noise, cluster-aware?"},
+    {"index": 7, "key": "feature_parity", "title": "Feature Parity",
+     "question": "Do the models see the same feature values online as offline?"},
+    {"index": 8, "key": "serving_parity", "title": "Serving Parity",
+     "question": "Is the serving configuration identical to the offline harness?"},
+    {"index": 9, "key": "shadow_traffic", "title": "Shadow Traffic Audit",
+     "question": "Is shadow traffic a fair sample, or biased by selection/drops?"},
+    {"index": 10, "key": "label_integrity", "title": "Label / Ground-Truth Integrity",
+     "question": "Are shadow labels mature, unbiased, and on the same policy?"},
+    {"index": 11, "key": "root_cause_scoring", "title": "Root Cause Scoring + Decision",
+     "question": "Which hypotheses does the accumulated evidence support?"},
+    {"index": 12, "key": "recommendations_report", "title": "Experiments + Report",
+     "question": "What is the minimum additional evidence needed, and the verdict?"},
+]
+
+STAGE_KEYS = [s["key"] for s in STAGES]
+
+STAGE_STATUS = ("pending", "in_progress", "complete", "complete_with_unknowns")
+
+# ---------------------------------------------------------------- root causes
+
+ROOT_CAUSES = (
+    "TRUE_MODEL_REGRESSION",
+    "DISTRIBUTION_SHIFT",
+    "FEATURE_SKEW",
+    "SERVING_MISMATCH",
+    "LABEL_LATENCY",
+    "SAMPLING_BIAS",
+    "STATISTICAL_NOISE",
+    "OFFLINE_CONTAMINATION",
+)
+
+HYPOTHESIS_LABELS: Dict[str, str] = {
+    "TRUE_MODEL_REGRESSION": "Candidate genuinely regresses on production data",
+    "DISTRIBUTION_SHIFT": "Production population differs from the offline eval set",
+    "FEATURE_SKEW": "Online/offline feature pipeline mismatch (training-serving skew)",
+    "SERVING_MISMATCH": "Shadow serving config differs (threshold / quantization / runtime)",
+    "LABEL_LATENCY": "Shadow labels immature / provisional and biased",
+    "SAMPLING_BIAS": "Shadow traffic selection is not a fair sample",
+    "STATISTICAL_NOISE": "Deltas are within noise; effective sample too small",
+    "OFFLINE_CONTAMINATION": "Offline +5% inflated by train/eval leakage",
+}
+
+FINDING_STATUS = ("PASS", "MISMATCH", "UNKNOWN")
+SEVERITIES = ("INFO", "WARN", "CRITICAL")
+
+
+# ------------------------------------------------------------------- findings
+
+
+@dataclass
+class Finding:
+    """One structured evidence record produced by a stage."""
+
+    id: str
+    stage: str                 # stage key
+    code: str                  # stable machine code, e.g. FP_FEATURE_SKEW:obj_distance_m
+    title: str
+    status: str                # PASS / MISMATCH / UNKNOWN
+    severity: str              # INFO / WARN / CRITICAL
+    detail: str = ""
+    source: str = "auto"       # auto / human
+    created_at: float = field(default_factory=time.time)
+    data: Dict = field(default_factory=dict)
+
+    def to_dict(self) -> Dict:
+        return asdict(self)
+
+
+def make_finding(stage: str, code: str, title: str, status: str, severity: str,
+                 detail: str = "", data: Optional[Dict] = None,
+                 source: str = "auto") -> Finding:
+    assert status in FINDING_STATUS, status
+    assert severity in SEVERITIES, severity
+    return Finding(id=f"fnd-{uuid.uuid4().hex[:10]}", stage=stage, code=code,
+                   title=title, status=status, severity=severity, detail=detail,
+                   data=data or {}, source=source)
+
+
+# --------------------------------------------------------------- investigation
+
+
+class StageOrderError(Exception):
+    """Raised when the enforced stage ordering is violated."""
+
+
+class UnknownsNotAcknowledgedError(Exception):
+    """Raised when completing a stage with critical UNKNOWNs without an ack."""
+
+
+@dataclass
+class StageState:
+    index: int
+    key: str
+    title: str
+    status: str = "pending"
+    completed_at: Optional[float] = None
+    acknowledged_unknowns: bool = False
+    ack_note: str = ""
+    skip_acknowledged: bool = False
+
+    def to_dict(self) -> Dict:
+        return asdict(self)
+
+
+@dataclass
+class Investigation:
+    id: str
+    name: str
+    baseline_model: str
+    candidate_model: str
+    scenario_cause: str            # the planted truth (hidden in training mode)
+    seed: int
+    training_mode: bool = False
+    revealed: bool = False
+    created_at: float = field(default_factory=time.time)
+    claims: Dict = field(default_factory=dict)
+    stages: List[StageState] = field(default_factory=list)
+    findings: List[Finding] = field(default_factory=list)
+    # human overrides on the scoring board: {hypothesis: {confidence, note}}
+    human_assessments: Dict[str, Dict] = field(default_factory=dict)
+    events: List[Dict] = field(default_factory=list)
+
+    # ----------------------------------------------------------- construction
+
+    @classmethod
+    def new(cls, name: str, baseline_model: str, candidate_model: str,
+            scenario_cause: str, seed: int, training_mode: bool = False,
+            claims: Optional[Dict] = None) -> "Investigation":
+        inv = cls(
+            id=f"inv-{uuid.uuid4().hex[:8]}",
+            name=name,
+            baseline_model=baseline_model,
+            candidate_model=candidate_model,
+            scenario_cause=scenario_cause,
+            seed=seed,
+            training_mode=training_mode,
+            claims=claims or {},
+            stages=[StageState(index=s["index"], key=s["key"], title=s["title"])
+                    for s in STAGES],
+        )
+        inv.stages[0].status = "in_progress"
+        inv.log("created", f"Investigation created ({name})")
+        return inv
+
+    # ---------------------------------------------------------------- helpers
+
+    def log(self, kind: str, message: str, data: Optional[Dict] = None) -> None:
+        self.events.append({"ts": time.time(), "kind": kind, "message": message,
+                            "data": data or {}})
+
+    def stage_by_key(self, key: str) -> StageState:
+        for st in self.stages:
+            if st.key == key:
+                return st
+        raise KeyError(f"Unknown stage {key}")
+
+    def findings_for(self, stage_key: str) -> List[Finding]:
+        return [f for f in self.findings if f.stage == stage_key]
+
+    def critical_unknowns(self, stage_key: str) -> List[Finding]:
+        return [f for f in self.findings_for(stage_key)
+                if f.status == "UNKNOWN" and f.severity == "CRITICAL"]
+
+    def upsert_auto_findings(self, stage_key: str, findings: List[Finding]) -> None:
+        """Replace prior auto findings for a stage (recorded human ones kept)."""
+        self.findings = [f for f in self.findings
+                         if not (f.stage == stage_key and f.source == "auto")]
+        self.findings.extend(findings)
+
+    def add_human_finding(self, finding: Finding) -> None:
+        self.findings.append(finding)
+        self.log("finding_recorded", f"Human finding recorded on {finding.stage}",
+                 {"code": finding.code})
+
+    # ------------------------------------------------------------ state machine
+
+    def complete_stage(self, index: int, acknowledge_unknowns: bool = False,
+                       ack_note: str = "") -> StageState:
+        """Complete a stage. Ordering is enforced: every earlier stage must be
+        complete (possibly with acknowledged unknowns). Critical UNKNOWN
+        findings block completion unless explicitly acknowledged, and the
+        acknowledgment is recorded on the stage and in the event log."""
+        if not 0 <= index < len(self.stages):
+            raise KeyError(f"No stage {index}")
+        stage = self.stages[index]
+        for earlier in self.stages[:index]:
+            if earlier.status not in ("complete", "complete_with_unknowns"):
+                raise StageOrderError(
+                    f"Stage {index} ({stage.title}) cannot complete before stage "
+                    f"{earlier.index} ({earlier.title}) is complete. The methodology "
+                    "is ordered on purpose: early plausible explanations do not "
+                    "excuse skipping measurement-validity checks.")
+
+        unknowns = self.critical_unknowns(stage.key)
+        if unknowns and not acknowledge_unknowns:
+            raise UnknownsNotAcknowledgedError(
+                f"Stage {stage.title} has {len(unknowns)} critical UNKNOWN "
+                "finding(s). Resolve them or explicitly acknowledge proceeding "
+                "with unknowns.")
+
+        if unknowns:
+            stage.status = "complete_with_unknowns"
+            stage.acknowledged_unknowns = True
+            stage.ack_note = ack_note or "proceeding with unknowns"
+            self.log("unknowns_acknowledged",
+                     f"Proceeding with {len(unknowns)} unknown(s) on {stage.title}",
+                     {"codes": [f.code for f in unknowns], "note": stage.ack_note})
+        else:
+            stage.status = "complete"
+        stage.completed_at = time.time()
+
+        nxt = index + 1
+        if nxt < len(self.stages) and self.stages[nxt].status == "pending":
+            self.stages[nxt].status = "in_progress"
+        self.log("stage_completed", f"Stage {stage.title} -> {stage.status}")
+        return stage
+
+    def reopen_stage(self, index: int) -> StageState:
+        stage = self.stages[index]
+        stage.status = "in_progress"
+        stage.completed_at = None
+        self.log("stage_reopened", f"Stage {stage.title} reopened")
+        return stage
+
+    # ------------------------------------------------------------- serialization
+
+    def to_dict(self, include_cause: bool = False) -> Dict:
+        d = {
+            "id": self.id,
+            "name": self.name,
+            "baseline_model": self.baseline_model,
+            "candidate_model": self.candidate_model,
+            "seed": self.seed,
+            "training_mode": self.training_mode,
+            "revealed": self.revealed,
+            "created_at": self.created_at,
+            "claims": self.claims,
+            "stages": [s.to_dict() for s in self.stages],
+            "findings": [f.to_dict() for f in self.findings],
+            "human_assessments": self.human_assessments,
+            "events": self.events[-200:],
+        }
+        # The planted cause is only exposed for non-training investigations or
+        # once the user reveals it.
+        if include_cause or (not self.training_mode) or self.revealed:
+            d["scenario_cause"] = self.scenario_cause
+        return d
+
+    def to_json_dict(self) -> Dict:
+        """Full-fidelity dict for persistence (always includes the cause)."""
+        d = self.to_dict(include_cause=True)
+        d["events"] = self.events
+        return d
+
+    @classmethod
+    def from_json_dict(cls, d: Dict) -> "Investigation":
+        inv = cls(
+            id=d["id"], name=d["name"], baseline_model=d["baseline_model"],
+            candidate_model=d["candidate_model"],
+            scenario_cause=d["scenario_cause"], seed=d["seed"],
+            training_mode=d.get("training_mode", False),
+            revealed=d.get("revealed", False),
+            created_at=d.get("created_at", time.time()),
+            claims=d.get("claims", {}),
+            stages=[StageState(**s) for s in d.get("stages", [])],
+            findings=[Finding(**f) for f in d.get("findings", [])],
+            human_assessments=d.get("human_assessments", {}),
+            events=d.get("events", []),
+        )
+        return inv

sensorflow/rca/report.py

@@ -0,0 +1,237 @@
+"""Final investigation report: markdown + JSON assembly."""
+
+from __future__ import annotations
+
+import time
+from typing import Dict, List, Optional
+
+from sensorflow.rca import diagnostics as dg, scoring
+from sensorflow.rca.models import (HYPOTHESIS_LABELS, Investigation, STAGES)
+from sensorflow.rca.scenario import ScenarioBundle
+
+_REMEDIATION: Dict[str, Dict[str, List[str]]] = {
+    "TRUE_MODEL_REGRESSION": {
+        "containment": ["Halt the rollout / keep B out of the serving path",
+                        "Pin A as the serving model; keep B in shadow only"],
+        "short_term": ["Slice the regression by segment and error type to "
+                       "find what B lost",
+                       "Fine-tune B on recent-window data covering the "
+                       "regressing segments"],
+        "long_term": ["Add a recent-window eval set to the offline gate",
+                      "Automate freshness checks on eval data before any "
+                      "launch decision"],
+    },
+    "DISTRIBUTION_SHIFT": {
+        "containment": ["Do not treat either aggregate as a launch signal; "
+                        "gate on segment-level deltas"],
+        "short_term": ["Reweight offline eval to the production mix and "
+                       "re-decide", "Target B's night/urban weakness with "
+                       "focused training data"],
+        "long_term": ["Continuously monitor production mix vs eval mix (PSI "
+                      "alerting)", "Stratified launch gates per segment"],
+    },
+    "FEATURE_SKEW": {
+        "containment": ["Freeze the rollout; the online model is consuming "
+                        "corrupted features"],
+        "short_term": ["Fix the unit/normalization difference in the online "
+                       "feature pipeline; add a unit test on the skewed "
+                       "feature", "Re-run shadow after the fix"],
+        "long_term": ["Continuous training-serving feature parity monitoring "
+                      "with per-feature SMD alerts",
+                      "Version-pin and log feature pipeline versions in both "
+                      "environments"],
+    },
+    "SERVING_MISMATCH": {
+        "containment": ["Align shadow serving config (threshold, precision) "
+                        "with the evaluated artifact before reading any "
+                        "shadow number"],
+        "short_term": ["Re-run shadow with the offline config; if the gap "
+                       "closes, ship config alignment",
+                       "Calibrate B's confidence to the serving threshold"],
+        "long_term": ["Config parity checks in CI between eval harness and "
+                      "serving stack", "One artifact, one config: promote the "
+                      "exact evaluated bundle"],
+    },
+    "LABEL_LATENCY": {
+        "containment": ["Suspend shadow-based verdicts until labels mature"],
+        "short_term": ["Re-grade the frozen cohort post-maturity",
+                       "Exclude provisional labels from headline metrics"],
+        "long_term": ["Separate provisional and mature metrics in dashboards",
+                      "Track label-age distribution as a first-class metric"],
+    },
+    "SAMPLING_BIAS": {
+        "containment": ["Stop reading the triage-sampled stream as an "
+                        "unbiased estimate"],
+        "short_term": ["Add a parallel uniform sample for measurement",
+                       "Reweight existing sample by inclusion probability "
+                       "(if logged)"],
+        "long_term": ["Log inclusion probabilities for every sampled unit",
+                      "Keep measurement sampling separate from triage "
+                      "sampling"],
+    },
+    "STATISTICAL_NOISE": {
+        "containment": ["Make no launch decision on current evidence; both "
+                        "+5% and -2% are within noise"],
+        "short_term": ["Extend collection to the pre-computed effective-n "
+                       "target", "Use paired, cluster-aware tests only"],
+        "long_term": ["Pre-register power calculations before shadow "
+                      "experiments", "Adopt anytime-valid sequential tests "
+                      "(seqeval) to allow early stopping without p-hacking"],
+    },
+    "OFFLINE_CONTAMINATION": {
+        "containment": ["Retract the +5% claim; do not use the current "
+                        "offline set for any decision"],
+        "short_term": ["Rebuild the eval set with entity-level dedup against "
+                       "B's training data; re-run both models",
+                       "Pin versions and record environment locks"],
+        "long_term": ["Automated leakage scans in the eval-set build "
+                      "pipeline", "Entity-level splitting enforced by "
+                      "tooling, not convention"],
+    },
+    "NO_PRACTICAL_REGRESSION": {
+        "containment": ["No containment needed"],
+        "short_term": ["Proceed with a guarded rollout with segment-level "
+                       "monitoring"],
+        "long_term": ["Tighten practical-margin definitions per surface"],
+    },
+}
+
+_STAGE_HEADLINE = {
+    "comparison_validity": "Are the two numbers commensurable?",
+    "offline_audit": "Is the +5% real and reproducible?",
+    "population_validation": "Enough volume, comparable populations?",
+    "distribution_shift": "Did the world move between the two evals?",
+    "conditional_performance": "Where does the delta live?",
+    "paired_comparison": "Which units actually flipped?",
+    "statistical_significance": "Is -2% distinguishable from noise?",
+    "feature_parity": "Same features online and offline?",
+    "serving_parity": "Same config online and offline?",
+    "shadow_traffic": "Is the scored sample fair?",
+    "label_integrity": "Is shadow ground truth actually true?",
+}
+
+
+def build_report(bundle: ScenarioBundle, inv: Investigation,
+                 battery: Optional[Dict] = None) -> Dict:
+    battery = battery or dg.run_all(bundle)
+    scoreboard = scoring.build_scoreboard(bundle, inv, battery=battery)
+    tree = scoring.evaluate_decision_tree(bundle, battery=battery)
+    experiments = scoring.recommend_experiments(bundle, scoreboard, battery)
+
+    top = scoreboard["rows"][0]
+    conclusion = tree["conclusion"]
+    remediation = _REMEDIATION.get(conclusion or top["hypothesis"],
+                                   _REMEDIATION[top["hypothesis"]])
+
+    stage_summaries = []
+    for key, (data, findings) in battery.items():
+        mism = [f for f in findings if f.status == "MISMATCH"]
+        unk = [f for f in findings if f.status == "UNKNOWN"]
+        stage_summaries.append({
+            "stage": key,
+            "headline": _STAGE_HEADLINE.get(key, key),
+            "mismatches": [f.title for f in mism],
+            "unknowns": [f.title for f in unk],
+            "n_pass": sum(1 for f in findings if f.status == "PASS"),
+            "verdict": ("mismatch" if mism else
+                        "unknown" if unk else "clean"),
+        })
+
+    acked = [e for e in inv.events if e["kind"] == "unknowns_acknowledged"]
+
+    payload = {
+        "investigation_id": inv.id,
+        "name": inv.name,
+        "generated_at": time.time(),
+        "models": {"baseline": inv.baseline_model,
+                   "candidate": inv.candidate_model},
+        "claims": inv.claims,
+        "executive_finding": {
+            "conclusion": conclusion,
+            "conclusion_kind": tree["conclusion_kind"],
+            "top_hypothesis": top["hypothesis"],
+            "label": HYPOTHESIS_LABELS.get(top["hypothesis"], top["hypothesis"]),
+            "confidence": top["auto_confidence"],
+            "score": top["score"],
+            "score_gap_to_runner_up": scoreboard["score_gap"],
+        },
+        "stage_summaries": stage_summaries,
+        "hypothesis_ranking": [
+            {"rank": r["rank"], "hypothesis": r["hypothesis"],
+             "score": r["score"], "confidence": r["auto_confidence"],
+             "human_confidence": r["human_confidence"],
+             "evidence_for": len(r["evidence_for"]),
+             "evidence_against": len(r["evidence_against"])}
+            for r in scoreboard["rows"]],
+        "decision_path": tree["path"],
+        "minimum_additional_evidence": experiments["minimum_additional_evidence"],
+        "recommended_experiments": experiments["experiments"],
+        "remediation": remediation,
+        "acknowledged_unknowns": acked,
+        "human_findings": [f.to_dict() for f in inv.findings
+                           if f.source == "human"],
+    }
+    payload["markdown"] = _to_markdown(payload, inv)
+    return payload
+
+
+def _to_markdown(p: Dict, inv: Investigation) -> str:
+    ef = p["executive_finding"]
+    lines = [
+        f"# RCA Report — {p['name']}",
+        "",
+        f"**Baseline:** `{p['models']['baseline']}`   "
+        f"**Candidate:** `{p['models']['candidate']}`",
+        "",
+        f"**Claims under investigation:** offline "
+        f"{p['claims'].get('offline_delta_pp', '+5')}pp vs shadow "
+        f"{p['claims'].get('shadow_delta_pp', '-2')}pp "
+        f"({p['claims'].get('metric', 'accuracy')})",
+        "",
+        "## Executive finding",
+        "",
+        f"**{ef['conclusion'] or ef['top_hypothesis']}** — "
+        f"{ef['label']} (confidence: **{ef['confidence']}**, score "
+        f"{ef['score']}, gap to runner-up {ef['score_gap_to_runner_up']}).",
+        "",
+        "## Hypothesis ranking",
+        "",
+        "| # | Hypothesis | Score | Confidence | For | Against |",
+        "|---|-----------|-------|------------|-----|---------|",
+    ]
+    for r in p["hypothesis_ranking"]:
+        hc = f" (human: {r['human_confidence']})" if r["human_confidence"] else ""
+        lines.append(f"| {r['rank']} | {r['hypothesis']} | {r['score']} | "
+                     f"{r['confidence']}{hc} | {r['evidence_for']} | "
+                     f"{r['evidence_against']} |")
+
+    lines += ["", "## Stage summaries", ""]
+    for s in p["stage_summaries"]:
+        badge = {"mismatch": "MISMATCH", "unknown": "UNKNOWN",
+                 "clean": "clean"}[s["verdict"]]
+        lines.append(f"- **{s['stage']}** ({s['headline']}) — {badge}")
+        for m in s["mismatches"]:
+            lines.append(f"    - ⚠ {m}")
+        for u in s["unknowns"]:
+            lines.append(f"    - ? {u}")
+
+    if p["acknowledged_unknowns"]:
+        lines += ["", "## Acknowledged unknowns", ""]
+        for e in p["acknowledged_unknowns"]:
+            lines.append(f"- {e['message']} — note: "
+                         f"{e['data'].get('note', '')}")
+
+    lines += ["", "## Minimum additional evidence", "",
+              p["minimum_additional_evidence"], "",
+              "## Recommended experiments", ""]
+    for d in p["recommended_experiments"]:
+        lines.append(f"{d['rank']}. **{d['design']}** (cost: {d['cost']}, "
+                     f"gain {d['information_gain']}) — {d['description']}")
+
+    lines += ["", "## Remediation", "", "**Containment (now):**"]
+    lines += [f"- {x}" for x in p["remediation"]["containment"]]
+    lines += ["", "**Short term:**"]
+    lines += [f"- {x}" for x in p["remediation"]["short_term"]]
+    lines += ["", "**Long term:**"]
+    lines += [f"- {x}" for x in p["remediation"]["long_term"]]
+    return "\n".join(lines)

sensorflow/rca/scenario.py

@@ -0,0 +1,550 @@
+"""Synthetic investigation scenario generator.
+
+Produces a coherent offline + shadow dataset pair for models A (baseline) and
+B (candidate) with a PLANTED root cause. The aggregate story is always the
+same -- offline says B is ~+5pp better, shadow says B is ~-2pp worse -- but
+the unit-level data carries the planted cause's downstream signatures, so the
+diagnostic battery (not the generator) is what identifies the cause.
+
+All randomness flows from a single seed (numpy default_rng), so scenarios are
+deterministic and test-reproducible.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.rca.models import ROOT_CAUSES
+
+SEGMENT_DIMS = ("scene", "time_of_day", "object_class")
+SCENES = ("urban", "highway", "suburban")
+TIMES = ("day", "dusk", "night")
+CLASSES = ("vehicle", "pedestrian", "cyclist")
+
+FEATURES = ("obj_distance_m", "ego_speed_mps", "occlusion_ratio",
+            "points_in_box", "track_age_s", "ambient_lux")
+
+OFFLINE_MIX = {
+    "scene": {"urban": 0.45, "highway": 0.30, "suburban": 0.25},
+    "time_of_day": {"day": 0.62, "dusk": 0.24, "night": 0.14},
+    "object_class": {"vehicle": 0.60, "pedestrian": 0.25, "cyclist": 0.15},
+}
+
+# Shadow mix drifts slightly from offline for every cause (production is never
+# identical); DISTRIBUTION_SHIFT replaces this with a heavy night/urban tilt.
+SHADOW_MIX_DEFAULT = {
+    "scene": {"urban": 0.48, "highway": 0.28, "suburban": 0.24},
+    "time_of_day": {"day": 0.58, "dusk": 0.25, "night": 0.17},
+    "object_class": {"vehicle": 0.58, "pedestrian": 0.26, "cyclist": 0.16},
+}
+
+SHADOW_MIX_SHIFTED = {
+    "scene": {"urban": 0.58, "highway": 0.18, "suburban": 0.24},
+    "time_of_day": {"day": 0.28, "dusk": 0.22, "night": 0.50},
+    "object_class": {"vehicle": 0.52, "pedestrian": 0.30, "cyclist": 0.18},
+}
+
+LABEL_MATURITY_HOURS = 72.0
+
+CAUSE_EXPLANATIONS: Dict[str, str] = {
+    "TRUE_MODEL_REGRESSION":
+        "B genuinely regresses on current production data (concept drift since "
+        "the offline eval window). The offline +5% is real for June data, but "
+        "stale. Signature: uniform within-segment shadow regression, all parity "
+        "checks clean, significance stage confirms a practical regression.",
+    "DISTRIBUTION_SHIFT":
+        "Production traffic is night/urban heavy while the offline set is "
+        "day-dominated. B is better in daytime segments and worse at night IN "
+        "BOTH environments -- a Simpson's paradox: the aggregate sign flips "
+        "purely from the population mix.",
+    "FEATURE_SKEW":
+        "The online feature pipeline emits obj_distance_m in feet (x3.281) "
+        "while offline uses meters. B depends on that feature more than A, so "
+        "shadow degrades B most where distance matters (highway). Signature: "
+        "one feature tops the parity report with a huge within-segment delta.",
+    "SERVING_MISMATCH":
+        "Shadow serving applies confidence threshold 0.50 + int8 quantization "
+        "vs the offline harness's 0.35/fp32. B's (recalibrated, lower) "
+        "confidences fall into the suppressed band far more often. Signature: "
+        "config diff + regression transitions concentrated in the 0.35-0.50 "
+        "confidence band.",
+    "LABEL_LATENCY":
+        "40% of shadow labels are provisional pseudo-labels from the incumbent "
+        "auto-labeler (which mirrors A) and are wrong mostly on hard cases. A "
+        "gets credit for matching wrong labels; B is penalized for disagreeing. "
+        "Signature: mature-label subset shows B ahead; provisional fraction is "
+        "difficulty-correlated.",
+    "SAMPLING_BIAS":
+        "The shadow sampler oversamples hard, low-confidence traffic (triage-"
+        "driven selection). B is slightly weaker only on very hard cases. The "
+        "full eligible stream agrees with offline (+); the sampled subset "
+        "flips negative. Signature: sampled-vs-eligible distribution mismatch "
+        "in the traffic audit.",
+    "STATISTICAL_NOISE":
+        "True delta is ~0 in both environments. Small n plus cluster-"
+        "correlated drive segments make the effective sample tiny, so +5%/-2% "
+        "are both within noise. Signature: overlapping CIs, low effective n, "
+        "significance stage returns insufficient evidence.",
+    "OFFLINE_CONTAMINATION":
+        "A quarter of the offline eval set are near-duplicates of B's training "
+        "data (row-level split leak), inflating B's offline score. Signature: "
+        "leakage scan fires, baseline re-run fails to reproduce, version pins "
+        "missing; shadow shows no reliable regression.",
+}
+
+
+@dataclass
+class ScenarioBundle:
+    cause: str
+    seed: int
+    offline: pd.DataFrame
+    shadow: pd.DataFrame
+    meta: Dict
+
+
+# ------------------------------------------------------------------ helpers
+
+
+def _sigmoid(x: np.ndarray) -> np.ndarray:
+    return 1.0 / (1.0 + np.exp(-x))
+
+
+def _pick(rng: np.random.Generator, table: Dict[str, float], n: int) -> np.ndarray:
+    keys = list(table.keys())
+    probs = np.array([table[k] for k in keys], dtype=float)
+    probs = probs / probs.sum()
+    return rng.choice(keys, size=n, p=probs)
+
+
+def _sample_units(rng: np.random.Generator, n: int, mix: Dict, cluster_size: int,
+                  entity_prefix: str) -> pd.DataFrame:
+    """Sample units grouped into drive-segment entities. Scene and time of day
+    are entity-level (a drive segment is one place, one time); object class is
+    unit-level."""
+    n_entities = max(2, int(np.ceil(n / cluster_size)))
+    ent_scene = _pick(rng, mix["scene"], n_entities)
+    ent_time = _pick(rng, mix["time_of_day"], n_entities)
+    ent_ids = np.array([f"{entity_prefix}-{i:05d}" for i in range(n_entities)])
+
+    idx = rng.integers(0, n_entities, size=n)
+    scene = ent_scene[idx]
+    time_of_day = ent_time[idx]
+    entity_id = ent_ids[idx]
+    object_class = _pick(rng, mix["object_class"], n)
+
+    dist_mu = np.where(scene == "urban", np.log(18.0),
+                       np.where(scene == "highway", np.log(45.0), np.log(28.0)))
+    obj_distance = np.exp(rng.normal(dist_mu, 0.45))
+
+    speed_mu = np.where(scene == "urban", 9.0,
+                        np.where(scene == "highway", 27.0, 14.0))
+    ego_speed = np.clip(rng.normal(speed_mu, 3.5), 0.0, None)
+
+    occ_a = np.where(scene == "urban", 2.5, np.where(scene == "highway", 1.5, 2.0))
+    occ_b = np.where(scene == "urban", 3.5, np.where(scene == "highway", 6.0, 5.0))
+    occlusion = rng.beta(occ_a, occ_b)
+
+    points = np.exp(rng.normal(6.8 - 1.1 * np.log(obj_distance / 20.0), 0.5))
+    track_age = rng.exponential(4.0, size=n)
+
+    lux_mu = np.where(time_of_day == "day", 10.3,
+                      np.where(time_of_day == "dusk", 7.5, 3.6))
+    lux_sd = np.where(time_of_day == "day", 0.3,
+                      np.where(time_of_day == "dusk", 0.4, 0.5))
+    ambient_lux = np.exp(rng.normal(lux_mu, lux_sd))
+
+    difficulty = np.clip(
+        rng.beta(2.2, 3.2, size=n)
+        + 0.20 * (time_of_day == "night")
+        + 0.12 * occlusion
+        + 0.08 * (obj_distance > 40.0)
+        - 0.10, 0.0, 1.0)
+
+    return pd.DataFrame({
+        "entity_id": entity_id,
+        "scene": scene,
+        "time_of_day": time_of_day,
+        "object_class": object_class,
+        "obj_distance_m": obj_distance,
+        "ego_speed_mps": ego_speed,
+        "occlusion_ratio": occlusion,
+        "points_in_box": points,
+        "track_age_s": track_age,
+        "ambient_lux": ambient_lux,
+        "difficulty": difficulty,
+    })
+
+
+def _segment_adj(df: pd.DataFrame) -> np.ndarray:
+    """Shared (model-A) segment difficulty adjustments on the logit scale."""
+    adj = np.zeros(len(df))
+    adj += np.where(df["time_of_day"] == "night", -0.50,
+                    np.where(df["time_of_day"] == "dusk", -0.15, 0.0))
+    adj += np.where(df["object_class"] == "pedestrian", -0.30,
+                    np.where(df["object_class"] == "cyclist", -0.45, 0.0))
+    adj += np.where(df["scene"] == "urban", -0.15,
+                    np.where(df["scene"] == "highway", 0.05, 0.0))
+    return adj
+
+
+def _cluster_effects(rng: np.random.Generator, entities: pd.Series,
+                     sigma_shared: float, sigma_b: float) -> Tuple[np.ndarray, np.ndarray]:
+    uniq = entities.unique()
+    shared = dict(zip(uniq, rng.normal(0.0, sigma_shared, size=len(uniq))))
+    b_only = dict(zip(uniq, rng.normal(0.0, sigma_b, size=len(uniq))))
+    return (entities.map(shared).to_numpy(), entities.map(b_only).to_numpy())
+
+
+def _draw_correctness(rng: np.random.Generator, df: pd.DataFrame,
+                      b_edge: np.ndarray, sigma_shared: float = 0.4,
+                      sigma_b_cluster: float = 0.15) -> pd.DataFrame:
+    shared_eff, b_cluster = _cluster_effects(rng, df["entity_id"],
+                                             sigma_shared, sigma_b_cluster)
+    logit_a = 1.9 - 3.0 * df["difficulty"].to_numpy() + _segment_adj(df) + shared_eff
+    logit_b = logit_a + b_edge + b_cluster
+    p_a, p_b = _sigmoid(logit_a), _sigmoid(logit_b)
+    df = df.copy()
+    df["a_correct"] = (rng.random(len(df)) < p_a).astype(int)
+    df["b_correct"] = (rng.random(len(df)) < p_b).astype(int)
+    df["a_conf"] = np.clip(p_a + rng.normal(0, 0.07, len(df)), 0.02, 0.99)
+    df["b_conf"] = np.clip(p_b + rng.normal(0, 0.07, len(df)), 0.02, 0.99)
+    return df
+
+
+def _calibrate(df: pd.DataFrame, target_delta: float, rng: np.random.Generator,
+               flip_mask: Optional[pd.Series] = None,
+               metric_mask: Optional[pd.Series] = None,
+               col_a: str = "a_correct", col_b: str = "b_correct") -> pd.DataFrame:
+    """Flip a minimal number of candidate-model outcomes so the measured
+    aggregate delta lands on target. Flips are allocated proportionally across
+    scene x time_of_day strata so planted per-segment structure survives."""
+    df = df.copy()
+    if metric_mask is None:
+        metric_mask = pd.Series(True, index=df.index)
+    if flip_mask is None:
+        flip_mask = pd.Series(True, index=df.index)
+
+    m = df[metric_mask]
+    n_metric = len(m)
+    if n_metric == 0:
+        return df
+    cur = m[col_b].mean() - m[col_a].mean()
+    need = target_delta - cur
+    k = int(round(abs(need) * n_metric))
+    if k == 0:
+        return df
+
+    want_value = 1 if need > 0 else 0
+    cand = df[flip_mask & metric_mask & (df[col_b] != want_value)]
+    if len(cand) == 0:
+        cand = df[metric_mask & (df[col_b] != want_value)]
+    k = min(k, len(cand))
+
+    strata = cand.groupby(["scene", "time_of_day"]).indices
+    chosen: List[int] = []
+    total = len(cand)
+    for _, idx in strata.items():
+        take = int(round(k * len(idx) / total))
+        take = min(take, len(idx))
+        if take > 0:
+            sel = rng.choice(idx, size=take, replace=False)
+            chosen.extend(cand.index[sel])
+    # Round-off top-up.
+    remaining = k - len(chosen)
+    if remaining > 0:
+        pool = cand.index.difference(pd.Index(chosen))
+        if len(pool) > 0:
+            extra = rng.choice(pool.to_numpy(), size=min(remaining, len(pool)),
+                               replace=False)
+            chosen.extend(extra.tolist())
+    df.loc[chosen, col_b] = want_value
+    return df
+
+
+# --------------------------------------------------------------- meta builder
+
+
+def _base_configs() -> Tuple[Dict, Dict]:
+    offline = {
+        "metric_definition": "object-level accuracy (IoU>=0.5 match, class-aware)",
+        "aggregation": "micro-average over objects",
+        "eval_window": "2026-06-01 .. 2026-06-30",
+        "population_source": "curated holdout eval set (holdout-2026Q2)",
+        "confidence_threshold": 0.35,
+        "quantization": "fp32",
+        "runtime_version": "trt-9.2.1",
+        "nms_iou": 0.50,
+        "feature_pipeline_version": "fp-2.4.1",
+        "label_policy_version": "human-audited-v3",
+        "label_maturity_policy": "labels frozen post-audit",
+        "sampling_policy": "full eval set, no sampling",
+    }
+    shadow = dict(offline)
+    shadow.update({
+        "eval_window": "2026-08-01 .. 2026-08-10 (live)",
+        "population_source": "live shadow traffic",
+        "sampling_policy": "uniform 60% shadow sampler",
+        "label_maturity_policy": "mixed: audited after 72h maturity",
+    })
+    return offline, shadow
+
+
+def _traffic_meta(rng: np.random.Generator, eligible: int, sampled: int,
+                  biased: bool) -> Dict:
+    if biased:
+        return {
+            "eligible_count": eligible,
+            "sampled_count": sampled,
+            "sampling_rate": round(sampled / eligible, 4),
+            "dropped_count": int(eligible * 0.041),
+            "timeout_count": int(eligible * 0.018),
+            "fallback_count": int(eligible * 0.062),
+            "eligibility_filters": [
+                "exclude frames with fallback stack engaged",
+                "triage-priority sampler v2 (uplifts low-confidence / "
+                "disagreement traffic)",
+            ],
+            "sampler": "engaged-triage-sampler-v2",
+        }
+    return {
+        "eligible_count": eligible,
+        "sampled_count": sampled,
+        "sampling_rate": round(sampled / eligible, 4),
+        "dropped_count": int(eligible * 0.012),
+        "timeout_count": int(eligible * 0.006),
+        "fallback_count": int(eligible * 0.009),
+        "eligibility_filters": ["exclude frames with fallback stack engaged"],
+        "sampler": "uniform-shadow-sampler-v1",
+    }
+
+
+# ------------------------------------------------------------------ generator
+
+
+def generate_scenario(cause: str, seed: int = 7) -> ScenarioBundle:
+    if cause not in ROOT_CAUSES:
+        raise ValueError(f"Unknown root cause {cause!r}; expected one of {ROOT_CAUSES}")
+    rng = np.random.default_rng(seed)
+
+    n_off, off_cluster = 3000, 8
+    n_sh, sh_cluster = 6000, 10
+    sampled_rate = 0.6
+    sigma_b_cluster = 0.15
+    shadow_mix = SHADOW_MIX_DEFAULT
+    off_target, sh_target = 0.05, -0.02
+
+    if cause == "STATISTICAL_NOISE":
+        n_off, off_cluster = 500, 25
+        n_sh, sh_cluster = 420, 20
+        sampled_rate = 1.0
+        sigma_b_cluster = 0.60
+    elif cause == "TRUE_MODEL_REGRESSION":
+        n_sh = 20000
+        sh_target = -0.023
+    elif cause == "DISTRIBUTION_SHIFT":
+        shadow_mix = SHADOW_MIX_SHIFTED
+    elif cause == "OFFLINE_CONTAMINATION":
+        sh_target = -0.010
+
+    off = _sample_units(rng, n_off, OFFLINE_MIX, off_cluster, "off-seg")
+    sh = _sample_units(rng, n_sh, shadow_mix, sh_cluster, "sh-seg")
+
+    # ---------------------------------------------------------- B's true edge
+    def zeros(df):
+        return np.zeros(len(df))
+
+    b_edge_off, b_edge_sh = zeros(off), zeros(sh)
+    if cause == "TRUE_MODEL_REGRESSION":
+        b_edge_off = np.full(n_off, 0.35)
+        b_edge_sh = np.full(n_sh, -0.18)      # concept drift hits B uniformly
+    elif cause == "DISTRIBUTION_SHIFT":
+        def mix_edge(df):
+            return np.where(df["time_of_day"] == "day", 0.60,
+                            np.where(df["time_of_day"] == "dusk", 0.10, -0.55))
+        b_edge_off, b_edge_sh = mix_edge(off), mix_edge(sh)
+    elif cause == "FEATURE_SKEW":
+        b_edge_off = np.full(n_off, 0.35)
+        w = np.where(sh["scene"] == "highway", 1.0,
+                     np.where(sh["scene"] == "suburban", 0.5, 0.2))
+        # Skewed distance feature degrades both models online, B far more.
+        b_edge_sh = 0.35 - 1.25 * w
+    elif cause == "SERVING_MISMATCH":
+        b_edge_off = np.full(n_off, 0.35)
+        b_edge_sh = np.full(n_sh, 0.35)       # B is genuinely better...
+    elif cause == "LABEL_LATENCY":
+        b_edge_off = np.full(n_off, 0.35)
+        b_edge_sh = np.full(n_sh, 0.32)
+    elif cause == "SAMPLING_BIAS":
+        # B slightly weaker only on very hard cases, in BOTH environments.
+        b_edge_off = 0.55 - 1.1 * off["difficulty"].to_numpy()
+        b_edge_sh = 0.55 - 1.1 * sh["difficulty"].to_numpy()
+    elif cause == "STATISTICAL_NOISE":
+        pass                                   # true delta ~ 0 everywhere
+    elif cause == "OFFLINE_CONTAMINATION":
+        b_edge_off = np.full(n_off, 0.02)
+        b_edge_sh = np.full(n_sh, -0.05)
+
+    off = _draw_correctness(rng, off, b_edge_off, sigma_b_cluster=sigma_b_cluster)
+    sh = _draw_correctness(rng, sh, b_edge_sh, sigma_b_cluster=sigma_b_cluster)
+
+    # -------------------------------------------------- offline contamination
+    off["is_near_duplicate"] = False
+    off["dup_similarity"] = 0.0
+    train_entity_ids: List[str] = []
+    if cause == "OFFLINE_CONTAMINATION":
+        entities = off["entity_id"].unique()
+        n_dup_ent = int(len(entities) * 0.25)
+        dup_entities = set(rng.choice(entities, size=n_dup_ent, replace=False))
+        dup_mask = off["entity_id"].isin(dup_entities)
+        off.loc[dup_mask, "is_near_duplicate"] = True
+        off.loc[dup_mask, "dup_similarity"] = rng.uniform(0.93, 0.999, dup_mask.sum())
+        # B memorized these rows during training.
+        mem = dup_mask & (rng.random(n_off) < 0.985)
+        off.loc[mem, "b_correct"] = 1
+        off.loc[dup_mask, "b_conf"] = np.clip(
+            off.loc[dup_mask, "b_conf"] + 0.15, 0.02, 0.995)
+        train_entity_ids = sorted(dup_entities)
+
+    # ------------------------------------------------------ shadow mechanisms
+    sh["a_correct_true"] = sh["a_correct"]
+    sh["b_correct_true"] = sh["b_correct"]
+    sh["a_conf_serving"] = sh["a_conf"]
+    sh["b_conf_serving"] = sh["b_conf"]
+
+    if cause == "FEATURE_SKEW":
+        # Online pipeline logs/consumes distance in feet.
+        sh["obj_distance_m"] = sh["obj_distance_m"] * 3.281
+
+    if cause == "SERVING_MISMATCH":
+        # int8 quantization nudges confidences down slightly (B more).
+        sh["a_conf_serving"] = np.clip(sh["a_conf"] - 0.01, 0.02, 0.99)
+        sh["b_conf_serving"] = np.clip(sh["b_conf"] - 0.05, 0.02, 0.99)
+        band = (sh["b_conf_serving"] >= 0.35) & (sh["b_conf_serving"] < 0.50)
+        suppressed = band & (rng.random(n_sh) < 0.9)
+        sh.loc[suppressed, "b_correct"] = 0
+
+    sh["label_is_provisional"] = False
+    sh["label_age_hours"] = rng.uniform(80.0, 400.0, n_sh)
+    if cause == "LABEL_LATENCY":
+        prov = rng.random(n_sh) < 0.40
+        sh["label_is_provisional"] = prov
+        sh.loc[prov, "label_age_hours"] = rng.uniform(1.0, 60.0, prov.sum())
+        diff = sh["difficulty"].to_numpy()
+        pseudo_wrong = prov & (rng.random(n_sh) < np.clip(0.65 * diff, 0, 0.9))
+        # Wrong pseudo-labels mirror the incumbent (A-like) auto-labeler:
+        # A "matches" the wrong label often; B rarely does.
+        a_match = pseudo_wrong & (rng.random(n_sh) < 0.75)
+        b_match = pseudo_wrong & (rng.random(n_sh) < 0.12)
+        sh.loc[pseudo_wrong, "a_correct"] = 0
+        sh.loc[pseudo_wrong & a_match, "a_correct"] = 1
+        sh.loc[pseudo_wrong, "b_correct"] = 0
+        sh.loc[pseudo_wrong & b_match, "b_correct"] = 1
+
+    # ---------------------------------------------------------- shadow sampling
+    if cause == "SAMPLING_BIAS":
+        disagree = (sh["a_correct_true"] != sh["b_correct_true"]).to_numpy()
+        w = 0.12 + 0.55 * disagree + 0.55 * sh["difficulty"].to_numpy() \
+            + 0.25 * (sh["a_conf"].to_numpy() < 0.5)
+        p_sample = np.clip(w, 0.02, 0.98)
+        sh["sampled"] = rng.random(n_sh) < p_sample
+    else:
+        sh["sampled"] = rng.random(n_sh) < sampled_rate
+
+    # ------------------------------------------------------------- calibration
+    off_flip_mask = off["is_near_duplicate"] if cause == "OFFLINE_CONTAMINATION" else None
+    off = _calibrate(off, off_target, rng, flip_mask=off_flip_mask)
+
+    if cause == "SERVING_MISMATCH":
+        flip = (sh["b_conf_serving"] >= 0.33) & (sh["b_conf_serving"] < 0.52)
+    elif cause == "LABEL_LATENCY":
+        flip = sh["label_is_provisional"]
+    else:
+        flip = None
+    if cause == "SAMPLING_BIAS":
+        # Only the triage-tilted sample regresses; the unsampled remainder of
+        # the eligible stream agrees with offline (B ahead).
+        sh = _calibrate(sh, sh_target, rng, metric_mask=sh["sampled"])
+        sh = _calibrate(sh, 0.06, rng, metric_mask=~sh["sampled"])
+    else:
+        # Calibrate the full stream, then a small touch-up on the scored
+        # sample, so sampled vs unsampled stay consistent (no spurious
+        # selection-bias signature).
+        sh = _calibrate(sh, sh_target, rng, flip_mask=flip)
+        sh = _calibrate(sh, sh_target, rng, flip_mask=flip,
+                        metric_mask=sh["sampled"])
+
+    # Light feature missingness (parity report exercises missingness deltas).
+    for col, frac_off, frac_sh in (("points_in_box", 0.004, 0.009),
+                                   ("track_age_s", 0.002, 0.004)):
+        off.loc[off.sample(frac=frac_off, random_state=seed).index, col] = np.nan
+        sh.loc[sh.sample(frac=frac_sh, random_state=seed + 1).index, col] = np.nan
+
+    off.insert(0, "unit_id", [f"off-{i:06d}" for i in range(len(off))])
+    sh.insert(0, "unit_id", [f"sh-{i:06d}" for i in range(len(sh))])
+
+    # ------------------------------------------------------------------- meta
+    off_cfg, sh_cfg = _base_configs()
+    if cause == "SERVING_MISMATCH":
+        sh_cfg["confidence_threshold"] = 0.50
+        sh_cfg["quantization"] = "int8"
+        sh_cfg["runtime_version"] = "trt-9.3.0"
+    if cause == "FEATURE_SKEW":
+        sh_cfg["feature_pipeline_version"] = None   # nobody recorded it
+    if cause == "LABEL_LATENCY":
+        sh_cfg["label_policy_version"] = "auto-provisional-v1 (mixed)"
+        sh_cfg["label_maturity_policy"] = "provisional pseudo-labels until 72h audit"
+    if cause == "SAMPLING_BIAS":
+        sh_cfg["sampling_policy"] = "engaged-triage-sampler-v2 (priority traffic)"
+    if cause == "TRUE_MODEL_REGRESSION":
+        off_cfg["eval_window"] = "2026-05-20 .. 2026-06-10 (8 weeks stale)"
+
+    repro_ok = cause != "OFFLINE_CONTAMINATION"
+    sampled_count = int(sh["sampled"].sum())
+
+    measured_off = float(off["b_correct"].mean() - off["a_correct"].mean())
+    m = sh[sh["sampled"]]
+    measured_sh = float(m["b_correct"].mean() - m["a_correct"].mean())
+
+    meta = {
+        "cause": cause,
+        "seed": seed,
+        "offline_config": off_cfg,
+        "shadow_config": sh_cfg,
+        "model_a": {
+            "version": "detr3d-a-v41",
+            "train_window": "2025-11 .. 2026-04",
+            "train_entity_ids": [],
+            "split_strategy": "entity_level",
+        },
+        "model_b": {
+            "version": "detr3d-b-v42",
+            "train_window": "2025-12 .. 2026-05",
+            "train_entity_ids": train_entity_ids,
+            "split_strategy": ("row_level" if cause == "OFFLINE_CONTAMINATION"
+                               else "entity_level"),
+        },
+        "reproducibility": {
+            "original_offline_metric_delta": measured_off,
+            "rerun_metric_delta": (measured_off + (0.001 if repro_ok else -0.031)),
+            "pins_present": repro_ok,
+            "environment_lock": ("conda-lock + image digest recorded" if repro_ok
+                                 else "requirements.txt without pins; image tag "
+                                      "'latest'"),
+        },
+        "traffic": _traffic_meta(rng, n_sh, sampled_count,
+                                 biased=(cause == "SAMPLING_BIAS")),
+        "label_maturity_hours": LABEL_MATURITY_HOURS,
+        "practical_margin_pp": 1.0,
+        "measured": {
+            "offline_delta": measured_off,
+            "shadow_delta": measured_sh,
+            "offline_n": len(off),
+            "shadow_scored_n": int(m.shape[0]),
+        },
+        "explanation": CAUSE_EXPLANATIONS[cause],
+    }
+    return ScenarioBundle(cause=cause, seed=seed, offline=off, shadow=sh, meta=meta)

sensorflow/rca/scoring.py

@@ -0,0 +1,407 @@
+"""Root-cause scoring board, decision-tree evaluation, and experiment ranking.
+
+The scoreboard is rule-based and auditable: each of the 8 hypotheses has an
+explicit list of finding codes that count for/against it, with weights. Every
+score is traceable to the stage findings that produced it (evidence links),
+and the user can overlay their own confidence assessment without erasing the
+auto one.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple
+
+from sensorflow.rca import diagnostics as dg
+from sensorflow.rca.models import (Finding, HYPOTHESIS_LABELS, Investigation,
+                                   ROOT_CAUSES)
+from sensorflow.rca.scenario import ScenarioBundle
+
+# (code_prefix, weight). A finding matches a rule when its code starts with
+# the prefix, so FP_FEATURE_SKEW matches FP_FEATURE_SKEW:obj_distance_m.
+_RULES: Dict[str, Dict[str, List[Tuple[str, float]]]] = {
+    "OFFLINE_CONTAMINATION": {
+        "for": [("OA_LEAKAGE_DUPLICATES", 3.0), ("OA_REPRO_FAIL", 2.5),
+                ("OA_SPLIT_ROW_LEVEL", 1.5), ("OA_PINS_MISSING", 1.0),
+                ("OA_TEMPORAL_LEAK", 2.0)],
+        "against": [("OA_LEAKAGE_CLEAN", 2.5), ("OA_REPRO_OK", 1.5),
+                    ("OA_SPLIT_ENTITY_LEVEL", 0.5)],
+    },
+    "DISTRIBUTION_SHIFT": {
+        "for": [("DS_SHIFT_HIGH", 2.5), ("CP_SIMPSONS_DETECTED", 3.0)],
+        "against": [("DS_SHIFT_LOW", 2.5), ("DS_VOLUME_TOO_SMALL", 0.5),
+                    ("CP_NO_PATTERN", 0.5)],
+    },
+    "FEATURE_SKEW": {
+        "for": [("FP_FEATURE_SKEW", 3.5), ("DS_FEATURE_ONLY_SHIFT", 1.5),
+                ("SP_UNKNOWN:feature_pipeline_version", 1.0),
+                ("CV_UNKNOWN:feature_pipeline_version", 0.5),
+                ("CP_SEGMENT_CONCENTRATED", 0.75)],
+        "against": [("FP_CLEAN", 3.0)],
+    },
+    "SERVING_MISMATCH": {
+        "for": [("SP_CONFIG_DIFF", 2.0), ("PC_CONF_BAND_CONCENTRATION", 2.5),
+                ("CV_MISMATCH:confidence_threshold", 0.5),
+                ("CV_MISMATCH:quantization", 0.5)],
+        "against": [("SP_CLEAN", 3.0)],
+    },
+    "LABEL_LATENCY": {
+        "for": [("LI_MATURE_DIVERGES", 3.0), ("LI_PROVISIONAL_HIGH", 1.5),
+                ("LI_DIFFICULTY_CORRELATED", 1.5), ("LI_POLICY_DIFF", 1.0),
+                ("CV_MISMATCH:label_policy_version", 0.5)],
+        "against": [("LI_CLEAN", 3.0)],
+    },
+    "SAMPLING_BIAS": {
+        "for": [("ST_SELECTION_BIAS", 3.5), ("ST_DROPS_HIGH", 1.0)],
+        "against": [("ST_SAMPLE_FAIR", 3.0)],
+    },
+    "STATISTICAL_NOISE": {
+        "for": [("SS_INSUFFICIENT_EVIDENCE", 2.0), ("SS_LOW_ESS", 2.0),
+                ("POP_VOLUME_LOW", 1.5), ("POP_SMALL_OFFLINE", 1.0),
+                ("DS_VOLUME_TOO_SMALL", 0.5)],
+        "against": [("SS_SIGNIFICANT_REGRESSION", 3.0), ("SS_NO_SIG_DIFF", 1.0),
+                    ("POP_VOLUME_OK", 1.5)],
+    },
+    "TRUE_MODEL_REGRESSION": {
+        "for": [("SS_SIGNIFICANT_REGRESSION", 2.5), ("CP_UNIFORM_REGRESSION", 1.5),
+                ("CV_WINDOW_STALE", 0.75),
+                # Clean bill of health on every artifact channel is itself
+                # evidence that the regression is real.
+                ("OA_LEAKAGE_CLEAN", 0.6), ("FP_CLEAN", 0.6), ("SP_CLEAN", 0.6),
+                ("ST_SAMPLE_FAIR", 0.6), ("LI_CLEAN", 0.6), ("DS_SHIFT_LOW", 0.6)],
+        "against": [("OA_LEAKAGE_DUPLICATES", 2.0), ("OA_REPRO_FAIL", 1.5),
+                    ("FP_FEATURE_SKEW", 2.0), ("SP_CONFIG_DIFF", 1.5),
+                    ("ST_SELECTION_BIAS", 2.0), ("LI_MATURE_DIVERGES", 2.0),
+                    ("CP_SIMPSONS_DETECTED", 2.0), ("DS_SHIFT_HIGH", 1.5),
+                    ("SS_INSUFFICIENT_EVIDENCE", 1.5),
+                    ("PC_CONF_BAND_CONCENTRATION", 1.0)],
+    },
+}
+
+_NEXT_TEST: Dict[str, str] = {
+    "TRUE_MODEL_REGRESSION":
+        "Split the shadow window into halves and check the paired delta is "
+        "stable; re-run the offline eval on freshly-labeled recent data "
+        "(same model, different data).",
+    "DISTRIBUTION_SHIFT":
+        "Reweight the scored shadow units to the offline segment mix and "
+        "recompute the paired delta -- if it turns positive, the mix is the "
+        "whole story.",
+    "FEATURE_SKEW":
+        "Replay ~500 shadow frames through the offline feature pipeline and "
+        "diff feature values unit-by-unit (same data, different pipeline); "
+        "start with the top-ranked parity feature.",
+    "SERVING_MISMATCH":
+        "Score the offline eval set through the shadow serving stack (same "
+        "data, different pipeline) with configs pinned one at a time "
+        "(threshold first, then quantization).",
+    "LABEL_LATENCY":
+        "Freeze the cohort and re-grade after labels mature past the audit "
+        "threshold; compare against the provisional-label verdict.",
+    "SAMPLING_BIAS":
+        "Score a uniform random sample of the eligible stream (bypass the "
+        "triage sampler) and compare the paired delta.",
+    "STATISTICAL_NOISE":
+        "Extend shadow collection until the cluster-aware CI half-width is "
+        "below the practical margin; pre-register the stopping rule "
+        "(anytime-valid sequential test).",
+    "OFFLINE_CONTAMINATION":
+        "Dedup the offline eval set against B's training data at entity "
+        "level, pin versions, and re-run the offline comparison.",
+}
+
+
+def _confidence(score: float, matched: int) -> str:
+    """UNKNOWN = no evidence touches this hypothesis yet. Otherwise the score
+    maps to confidence THAT THIS IS THE CAUSE (negative = evidence against)."""
+    if matched == 0:
+        return "UNKNOWN"
+    if score >= 5.0:
+        return "HIGH"
+    if score >= 2.5:
+        return "MEDIUM"
+    return "LOW"
+
+
+def build_scoreboard(bundle: ScenarioBundle,
+                     inv: Optional[Investigation] = None,
+                     battery: Optional[Dict] = None,
+                     recorded_only: bool = False) -> Dict:
+    """Score all 8 hypotheses from the full diagnostic battery plus any
+    human-recorded findings; overlay human assessments if present.
+
+    With recorded_only=True, only findings already recorded on the
+    investigation are scored (auto findings accrue as the engineer works
+    through the stages) -- used for the evolving working-hypothesis banner so
+    the board never leaks conclusions from stages not yet visited."""
+    if recorded_only and inv is not None:
+        findings: List[Finding] = list(inv.findings)
+    else:
+        battery = battery or dg.run_all(bundle)
+        findings = [f for _, (_, fs) in battery.items() for f in fs]
+        if inv is not None:
+            findings = findings + [f for f in inv.findings if f.source == "human"]
+
+    rows = []
+    for hyp in ROOT_CAUSES:
+        rules = _RULES[hyp]
+        ev_for, ev_against = [], []
+        score = 0.0
+        for f in findings:
+            for prefix, w in rules["for"]:
+                if f.code.startswith(prefix):
+                    score += w
+                    ev_for.append({"code": f.code, "stage": f.stage,
+                                   "title": f.title, "weight": w,
+                                   "severity": f.severity, "status": f.status,
+                                   "finding_id": f.id})
+                    break
+            else:
+                for prefix, w in rules["against"]:
+                    if f.code.startswith(prefix):
+                        score -= w
+                        ev_against.append({"code": f.code, "stage": f.stage,
+                                           "title": f.title, "weight": w,
+                                           "severity": f.severity,
+                                           "status": f.status,
+                                           "finding_id": f.id})
+                        break
+        matched = len(ev_for) + len(ev_against)
+        auto_conf = _confidence(score, matched)
+        human = (inv.human_assessments.get(hyp) if inv is not None else None) or {}
+        rows.append({
+            "hypothesis": hyp,
+            "label": HYPOTHESIS_LABELS[hyp],
+            "score": round(score, 2),
+            "evidence_for": ev_for,
+            "evidence_against": ev_against,
+            "auto_confidence": auto_conf,
+            "human_confidence": human.get("confidence"),
+            "human_note": human.get("note", ""),
+            "next_discriminating_test": _NEXT_TEST[hyp],
+        })
+
+    rows.sort(key=lambda r: r["score"], reverse=True)
+    for i, r in enumerate(rows):
+        r["rank"] = i + 1
+
+    top = rows[0]
+    runner = rows[1] if len(rows) > 1 else None
+    # Skeptical semantics: a hypothesis leaves the working set only when the
+    # net recorded evidence is AGAINST it -- weak or absent evidence keeps it
+    # in play (never a premature single conclusion).
+    working_set = [r["hypothesis"] for r in rows
+                   if r["score"] >= -0.5 or r["auto_confidence"] == "UNKNOWN"]
+    return {
+        "rows": rows,
+        "top_hypothesis": top["hypothesis"],
+        "top_confidence": top["auto_confidence"],
+        "score_gap": round(top["score"] - (runner["score"] if runner else 0.0), 2),
+        "working_hypothesis_set": working_set or [top["hypothesis"]],
+        "explainer": ("Rule-based, auditable scoring: every point traces to a "
+                      "stage finding. Human overrides are recorded next to -- "
+                      "never instead of -- the automatic assessment."),
+    }
+
+
+# ------------------------------------------------------------- decision tree
+
+
+def _has(findings: List[Finding], prefix: str) -> Optional[Finding]:
+    for f in findings:
+        if f.code.startswith(prefix):
+            return f
+    return None
+
+
+def evaluate_decision_tree(bundle: ScenarioBundle,
+                           battery: Optional[Dict] = None) -> Dict:
+    """Walk the measurement-validity -> distribution -> parity -> significance
+    causal chain with this investigation's actual findings at each node."""
+    battery = battery or dg.run_all(bundle)
+    findings = [f for _, (_, fs) in battery.items() for f in fs]
+
+    def node(nid, question, yes_when_absent, bad_prefixes, unknown_prefixes,
+             conclusion_if_no, next_id):
+        bad = [p for p in bad_prefixes if _has(findings, p)]
+        unk = [p for p in unknown_prefixes if _has(findings, p)]
+        if bad:
+            answer = "no"
+        elif unk:
+            answer = "unknown"
+        else:
+            answer = "yes" if yes_when_absent else "unknown"
+        basis = [f.code for f in findings
+                 if any(f.code.startswith(p) for p in
+                        list(bad_prefixes) + list(unknown_prefixes))]
+        return {"id": nid, "question": question, "answer": answer,
+                "basis": basis, "conclusion_if_no": conclusion_if_no,
+                "next": next_id}
+
+    nodes = [
+        node("offline_trustworthy",
+             "Is the offline +5% measurement itself trustworthy "
+             "(reproducible, leak-free)?", True,
+             ["OA_LEAKAGE_DUPLICATES", "OA_REPRO_FAIL", "OA_TEMPORAL_LEAK"],
+             ["OA_PINS_MISSING"],
+             "OFFLINE_CONTAMINATION", "labels_trustworthy"),
+        node("labels_trustworthy",
+             "Are shadow ground-truth labels mature and unbiased?", True,
+             ["LI_MATURE_DIVERGES"],
+             ["LI_PROVISIONAL_HIGH"],
+             "LABEL_LATENCY", "sample_representative"),
+        node("sample_representative",
+             "Is the scored shadow sample representative of eligible "
+             "traffic?", True,
+             ["ST_SELECTION_BIAS"], [],
+             "SAMPLING_BIAS", "same_population"),
+        node("same_population",
+             "Do offline and shadow score comparable populations?", True,
+             ["DS_SHIFT_HIGH", "CP_SIMPSONS_DETECTED"],
+             ["DS_VOLUME_TOO_SMALL"],
+             "DISTRIBUTION_SHIFT", "feature_parity"),
+        node("feature_parity",
+             "Do the models see the same feature values online as offline?",
+             True,
+             ["FP_FEATURE_SKEW"],
+             ["SP_UNKNOWN:feature_pipeline_version"],
+             "FEATURE_SKEW", "serving_parity"),
+        node("serving_parity",
+             "Is the serving configuration at parity with the offline "
+             "harness?", True,
+             ["SP_CONFIG_DIFF"],
+             ["SP_UNKNOWN"],
+             "SERVING_MISMATCH", "significant"),
+    ]
+
+    sig = _has(findings, "SS_SIGNIFICANT_REGRESSION")
+    insuff = _has(findings, "SS_INSUFFICIENT_EVIDENCE")
+    nodes.append({
+        "id": "significant",
+        "question": ("With all artifact channels checked, is the shadow "
+                     "regression significant beyond the practical margin?"),
+        "answer": "yes" if sig else ("unknown" if insuff else "no"),
+        "basis": [f.code for f in findings if f.code.startswith("SS_")],
+        "conclusion_if_no": None,
+        "next": None,
+    })
+
+    # Walk the live path.
+    path: List[str] = []
+    conclusion = None
+    conclusion_kind = "root_cause"
+    for n in nodes:
+        path.append(n["id"])
+        if n["id"] == "significant":
+            if n["answer"] == "yes":
+                conclusion = "TRUE_MODEL_REGRESSION"
+            elif n["answer"] == "unknown":
+                conclusion = "STATISTICAL_NOISE"
+                conclusion_kind = "insufficient_evidence"
+            else:
+                conclusion = "NO_PRACTICAL_REGRESSION"
+                conclusion_kind = "no_regression"
+            break
+        if n["answer"] == "no":
+            conclusion = n["conclusion_if_no"]
+            break
+        # 'unknown' proceeds but is recorded on the node; the stage state
+        # machine is what forces the acknowledgment.
+
+    return {"nodes": nodes, "path": path, "conclusion": conclusion,
+            "conclusion_kind": conclusion_kind,
+            "explainer": ("The causal chain rendered with this "
+                          "investigation's actual answers. A 'no' anywhere "
+                          "upstream invalidates naive readings of every "
+                          "number downstream.")}
+
+
+# ---------------------------------------------------------------- experiments
+
+
+def recommend_experiments(bundle: ScenarioBundle,
+                          scoreboard: Optional[Dict] = None,
+                          battery: Optional[Dict] = None) -> Dict:
+    battery = battery or dg.run_all(bundle)
+    scoreboard = scoreboard or build_scoreboard(bundle, battery=battery)
+    rows = scoreboard["rows"]
+    by_hyp = {r["hypothesis"]: r for r in rows}
+    top, runner = rows[0], rows[1]
+
+    sig_data = battery["statistical_significance"][0]
+    eff_n = sig_data["shadow_paired"]["effective_n"]
+    margin = sig_data["practical_margin_pp"]
+    se = sig_data["shadow_paired"]["se"]
+    # n needed for the CI half-width to fit inside the practical margin.
+    needed_n = int(eff_n * (1.96 * se / max(1e-9, margin / 100.0)) ** 2) + 1
+
+    fp_rows = battery["feature_parity"][0]["rows"]
+    top_feature = fp_rows[0]["feature"] if fp_rows else "top-ranked feature"
+
+    designs = [
+        {"id": "same_data_diff_pipeline",
+         "design": "Same data, different pipeline",
+         "description": (f"Replay ~500 scored shadow frames through the "
+                         f"offline feature + serving pipeline and diff both "
+                         f"feature values (start with {top_feature}) and "
+                         "model outputs unit-by-unit."),
+         "discriminates": ["FEATURE_SKEW", "SERVING_MISMATCH"],
+         "cost": "low", "expected_days": 1},
+        {"id": "same_model_diff_data",
+         "design": "Same model, different data",
+         "description": ("Re-run the offline evaluation on a fresh, "
+                         "entity-deduped, recent-window eval set (and "
+                         "reweighted to the shadow segment mix)."),
+         "discriminates": ["OFFLINE_CONTAMINATION", "DISTRIBUTION_SHIFT",
+                           "TRUE_MODEL_REGRESSION"],
+         "cost": "medium", "expected_days": 2},
+        {"id": "uniform_shadow_sample",
+         "design": "Same traffic, different sampler",
+         "description": ("Score a uniform random sample of eligible shadow "
+                         "traffic, bypassing eligibility filters and the "
+                         "triage sampler."),
+         "discriminates": ["SAMPLING_BIAS"],
+         "cost": "low", "expected_days": 1},
+        {"id": "mature_label_regrade",
+         "design": "Same units, different labels",
+         "description": ("Freeze the scored cohort and re-grade once all "
+                         "labels pass the maturity threshold; compare "
+                         "verdicts."),
+         "discriminates": ["LABEL_LATENCY"],
+         "cost": "medium", "expected_days": 4},
+        {"id": "extend_collection",
+         "design": "More data, pre-registered stop",
+         "description": (f"Extend shadow collection to ~{needed_n:,} "
+                         f"effective units so the CI half-width fits inside "
+                         f"the {margin:.1f}pp practical margin; use an "
+                         "anytime-valid sequential test."),
+         "discriminates": ["STATISTICAL_NOISE", "TRUE_MODEL_REGRESSION"],
+         "cost": "medium", "expected_days": 5},
+    ]
+
+    # Information gain proxy: how much unresolved probability mass the
+    # experiment can move (sum of positive scores it discriminates among,
+    # with the top-2 gap counted double), divided by cost.
+    cost_w = {"low": 1.0, "medium": 2.0, "high": 4.0}
+    for d in designs:
+        mass = sum(max(0.0, by_hyp[h]["score"]) for h in d["discriminates"])
+        bonus = 3.0 if (top["hypothesis"] in d["discriminates"]
+                        or runner["hypothesis"] in d["discriminates"]) else 0.0
+        d["information_gain"] = round(mass + bonus, 2)
+        d["priority"] = round((mass + bonus) / cost_w[d["cost"]], 2)
+    designs.sort(key=lambda d: d["priority"], reverse=True)
+    for i, d in enumerate(designs):
+        d["rank"] = i + 1
+
+    minimum = (
+        f"Current leader: {top['hypothesis']} "
+        f"({top['auto_confidence']}, score {top['score']}) vs runner-up "
+        f"{runner['hypothesis']} (score {runner['score']}). The minimum "
+        f"additional evidence to conclude is: {designs[0]['description']} "
+        f"If that comes back clean, fall back to: {designs[1]['description']}")
+
+    return {"experiments": designs, "minimum_additional_evidence": minimum,
+            "power": {"effective_n": eff_n, "needed_effective_n": needed_n,
+                      "practical_margin_pp": margin},
+            "explainer": ("Counterfactual designs instantiated with this "
+                          "investigation's specifics, ranked by information "
+                          "gain per unit cost.")}

sensorflow/rca/stats.py

@@ -0,0 +1,193 @@
+"""Statistical primitives for the RCA diagnostics.
+
+Local implementations of Wilson CIs and cluster-aware paired deltas. When the
+sequential-testing package (sensorflow.seqeval: anytime-valid confidence
+sequences + paired evaluation) lands, the significance stage should prefer it;
+see diagnostics.significance_engine().
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional, Sequence, Tuple
+
+import numpy as np
+import pandas as pd
+from scipy import stats as sps
+
+Z95 = 1.959963984540054
+
+
+def wilson_ci(successes: int, n: int, z: float = Z95) -> Tuple[float, float]:
+    """Wilson score interval for a binomial proportion."""
+    if n == 0:
+        return (0.0, 1.0)
+    p = successes / n
+    denom = 1 + z * z / n
+    center = (p + z * z / (2 * n)) / denom
+    half = z * math.sqrt(p * (1 - p) / n + z * z / (4 * n * n)) / denom
+    return (max(0.0, center - half), min(1.0, center + half))
+
+
+# ------------------------------------------------------------- divergence
+
+
+def _hist_probs(a: np.ndarray, b: np.ndarray, bins: int = 10,
+                eps: float = 1e-4) -> Tuple[np.ndarray, np.ndarray]:
+    """Common-bin probability vectors for two continuous samples."""
+    lo = min(np.min(a), np.min(b))
+    hi = max(np.max(a), np.max(b))
+    if hi <= lo:
+        hi = lo + 1e-9
+    edges = np.linspace(lo, hi, bins + 1)
+    pa, _ = np.histogram(a, bins=edges)
+    pb, _ = np.histogram(b, bins=edges)
+    pa = pa / max(1, pa.sum())
+    pb = pb / max(1, pb.sum())
+    return pa + eps, pb + eps
+
+
+def psi_continuous(expected: np.ndarray, actual: np.ndarray, bins: int = 10) -> float:
+    pa, pb = _hist_probs(np.asarray(expected, float), np.asarray(actual, float), bins)
+    pa, pb = pa / pa.sum(), pb / pb.sum()
+    return float(np.sum((pb - pa) * np.log(pb / pa)))
+
+
+def psi_categorical(expected: Sequence, actual: Sequence, eps: float = 1e-4) -> float:
+    cats = sorted(set(expected) | set(actual))
+    e = pd.Series(list(expected)).value_counts(normalize=True)
+    a = pd.Series(list(actual)).value_counts(normalize=True)
+    pe = np.array([e.get(c, 0.0) + eps for c in cats])
+    pa = np.array([a.get(c, 0.0) + eps for c in cats])
+    pe, pa = pe / pe.sum(), pa / pa.sum()
+    return float(np.sum((pa - pe) * np.log(pa / pe)))
+
+
+def js_divergence_continuous(a: np.ndarray, b: np.ndarray, bins: int = 10) -> float:
+    pa, pb = _hist_probs(np.asarray(a, float), np.asarray(b, float), bins)
+    pa, pb = pa / pa.sum(), pb / pb.sum()
+    m = 0.5 * (pa + pb)
+    return float(0.5 * np.sum(pa * np.log(pa / m)) + 0.5 * np.sum(pb * np.log(pb / m)))
+
+
+def js_divergence_categorical(a: Sequence, b: Sequence, eps: float = 1e-4) -> float:
+    cats = sorted(set(a) | set(b))
+    sa = pd.Series(list(a)).value_counts(normalize=True)
+    sb = pd.Series(list(b)).value_counts(normalize=True)
+    pa = np.array([sa.get(c, 0.0) + eps for c in cats])
+    pb = np.array([sb.get(c, 0.0) + eps for c in cats])
+    pa, pb = pa / pa.sum(), pb / pb.sum()
+    m = 0.5 * (pa + pb)
+    return float(0.5 * np.sum(pa * np.log(pa / m)) + 0.5 * np.sum(pb * np.log(pb / m)))
+
+
+def ks_test(a: np.ndarray, b: np.ndarray) -> Tuple[float, float]:
+    res = sps.ks_2samp(a, b)
+    return float(res.statistic), float(res.pvalue)
+
+
+def chi2_test(a: Sequence, b: Sequence) -> Tuple[float, float]:
+    cats = sorted(set(a) | set(b))
+    ca = pd.Series(list(a)).value_counts()
+    cb = pd.Series(list(b)).value_counts()
+    table = np.array([[ca.get(c, 0) for c in cats], [cb.get(c, 0) for c in cats]])
+    table = table[:, table.sum(axis=0) > 0]
+    if table.shape[1] < 2:
+        return 0.0, 1.0
+    stat, p, _, _ = sps.chi2_contingency(table)
+    return float(stat), float(p)
+
+
+def shift_magnitude_label(psi: float) -> str:
+    """Practical-effect label for a PSI value (independent of p-values)."""
+    if psi < 0.02:
+        return "negligible"
+    if psi < 0.1:
+        return "small"
+    if psi < 0.25:
+        return "moderate"
+    return "large"
+
+
+# ---------------------------------------------------- cluster-aware paired delta
+
+
+def paired_delta_cluster(df: pd.DataFrame, col_a: str = "a_correct",
+                         col_b: str = "b_correct",
+                         cluster_col: str = "entity_id") -> Dict:
+    """Paired B-A delta with a cluster-robust CI and effective sample size.
+
+    The per-unit paired differences d_i = b_i - a_i are aggregated per cluster
+    (drive segment); the SE of the overall delta uses between-cluster variance
+    of cluster sums (standard cluster-robust estimator for a mean). The
+    effective sample size is n / design_effect with DE = 1 + (m_bar - 1) * ICC.
+    """
+    d = (df[col_b].astype(float) - df[col_a].astype(float)).to_numpy()
+    n = len(d)
+    if n == 0:
+        return {"n": 0, "delta": 0.0, "ci_low": 0.0, "ci_high": 0.0,
+                "effective_n": 0, "icc": 0.0, "design_effect": 1.0, "se": 0.0}
+    delta = float(d.mean())
+
+    groups = df.groupby(cluster_col).indices
+    cluster_sums = np.array([d[idx].sum() for idx in groups.values()])
+    cluster_sizes = np.array([len(idx) for idx in groups.values()])
+    g = len(cluster_sums)
+    if g > 1:
+        # Cluster-robust variance of the mean of d.
+        resid = cluster_sums - cluster_sizes * delta
+        var = float(np.sum(resid ** 2)) * g / (g - 1) / (n ** 2)
+        se = math.sqrt(max(var, 1e-12))
+    else:
+        se = float(d.std(ddof=1) / math.sqrt(n)) if n > 1 else 0.0
+
+    icc = _icc(d, df[cluster_col].to_numpy())
+    m_bar = float(cluster_sizes.mean()) if g else 1.0
+    design_effect = max(1.0, 1.0 + (m_bar - 1.0) * max(0.0, icc))
+    eff_n = int(n / design_effect)
+
+    return {
+        "n": int(n),
+        "n_clusters": int(g),
+        "delta": delta,
+        "se": se,
+        "ci_low": delta - Z95 * se,
+        "ci_high": delta + Z95 * se,
+        "icc": icc,
+        "design_effect": design_effect,
+        "effective_n": eff_n,
+    }
+
+
+def _icc(values: np.ndarray, clusters: np.ndarray) -> float:
+    """One-way ANOVA intraclass correlation estimate."""
+    dfr = pd.DataFrame({"v": values, "c": clusters})
+    grp = dfr.groupby("c")["v"]
+    k = grp.ngroups
+    n = len(dfr)
+    if k < 2 or n <= k:
+        return 0.0
+    grand = dfr["v"].mean()
+    m_i = grp.mean()
+    n_i = grp.size()
+    ss_between = float((n_i * (m_i - grand) ** 2).sum())
+    ss_within = float(((dfr["v"] - grp.transform("mean")) ** 2).sum())
+    ms_between = ss_between / (k - 1)
+    ms_within = ss_within / max(1, n - k)
+    n_bar = n / k
+    denom = ms_between + (n_bar - 1) * ms_within
+    if denom <= 0:
+        return 0.0
+    return float(max(0.0, (ms_between - ms_within) / denom))
+
+
+def three_way_outcome(delta: float, ci_low: float, ci_high: float,
+                      practical_margin: float) -> str:
+    """Classify a paired delta CI against a minimum practically-important
+    regression margin (expressed as a positive fraction, e.g. 0.01 = 1pp)."""
+    if ci_high < -practical_margin:
+        return "significant_regression"
+    if ci_low > -practical_margin:
+        # The CI excludes a practically-important regression entirely.
+        return "no_significant_difference"
+    return "insufficient_evidence"

sensorflow/rca/store.py

@@ -0,0 +1,115 @@
+"""Persistence for RCA investigations under runs/rca/.
+
+Layout:
+    runs/rca/<investigation_id>/investigation.json
+    runs/rca/<investigation_id>/offline.csv
+    runs/rca/<investigation_id>/shadow.csv
+    runs/rca/<investigation_id>/meta.json
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import pandas as pd
+
+from sensorflow.rca.models import Investigation
+from sensorflow.rca.scenario import ScenarioBundle
+
+_DEFAULT_ROOT = "runs/rca"
+_root = Path(_DEFAULT_ROOT)
+_lock = threading.Lock()
+_cache: Dict[str, Investigation] = {}
+_data_cache: Dict[str, ScenarioBundle] = {}
+
+
+def set_rca_root(path: str) -> None:
+    """Point the store somewhere else (tests use a tmp dir)."""
+    global _root
+    _root = Path(path)
+    reset_rca_store()
+
+
+def reset_rca_store() -> None:
+    _cache.clear()
+    _data_cache.clear()
+
+
+def _inv_dir(inv_id: str) -> Path:
+    return _root / inv_id
+
+
+def save_investigation(inv: Investigation,
+                       bundle: Optional[ScenarioBundle] = None) -> None:
+    with _lock:
+        d = _inv_dir(inv.id)
+        d.mkdir(parents=True, exist_ok=True)
+        (d / "investigation.json").write_text(
+            json.dumps(inv.to_json_dict(), indent=1))
+        if bundle is not None:
+            bundle.offline.to_csv(d / "offline.csv", index=False)
+            bundle.shadow.to_csv(d / "shadow.csv", index=False)
+            (d / "meta.json").write_text(json.dumps(bundle.meta, indent=1))
+            _data_cache[inv.id] = bundle
+        _cache[inv.id] = inv
+
+
+def load_investigation(inv_id: str) -> Optional[Investigation]:
+    if inv_id in _cache:
+        return _cache[inv_id]
+    f = _inv_dir(inv_id) / "investigation.json"
+    if not f.exists():
+        return None
+    inv = Investigation.from_json_dict(json.loads(f.read_text()))
+    _cache[inv_id] = inv
+    return inv
+
+
+def load_bundle(inv_id: str) -> Optional[ScenarioBundle]:
+    if inv_id in _data_cache:
+        return _data_cache[inv_id]
+    d = _inv_dir(inv_id)
+    if not (d / "meta.json").exists():
+        return None
+    meta = json.loads((d / "meta.json").read_text())
+    offline = pd.read_csv(d / "offline.csv")
+    shadow = pd.read_csv(d / "shadow.csv")
+    bundle = ScenarioBundle(cause=meta["cause"], seed=meta["seed"],
+                            offline=offline, shadow=shadow, meta=meta)
+    _data_cache[inv_id] = bundle
+    return bundle
+
+
+def list_investigations() -> List[Dict]:
+    out: List[Dict] = []
+    if not _root.exists():
+        return out
+    for d in sorted(_root.iterdir()):
+        f = d / "investigation.json"
+        if not f.is_file():
+            continue
+        inv = load_investigation(d.name)
+        if inv is None:
+            continue
+        done = sum(1 for s in inv.stages
+                   if s.status in ("complete", "complete_with_unknowns"))
+        summary = {
+            "id": inv.id,
+            "name": inv.name,
+            "baseline_model": inv.baseline_model,
+            "candidate_model": inv.candidate_model,
+            "training_mode": inv.training_mode,
+            "revealed": inv.revealed,
+            "created_at": inv.created_at,
+            "claims": inv.claims,
+            "stages_complete": done,
+            "stages_total": len(inv.stages),
+        }
+        if not inv.training_mode or inv.revealed:
+            summary["scenario_cause"] = inv.scenario_cause
+        out.append(summary)
+    out.sort(key=lambda r: r["created_at"], reverse=True)
+    return out

src/App.tsx

@@ -18,6 +18,7 @@ import {
   Radar,
   ShieldCheck,
   TrendingDown,
+  Microscope,
   Filter,
   UserCheck,
   Rocket,
@@ -46,6 +47,7 @@ import PipelineArchitecturePage from './pages/PipelineArchitecturePage';
 import SSAMSafetyDashboard from './pages/SSAMSafetyDashboard';
 import LegacyStudioPage from './pages/LegacyStudioPage';
 import CommandCenterPage from './pages/CommandCenterPage';
+import RootCauseLabPage from './pages/rca/RootCauseLabPage';
 import PageIntro from './components/help/PageIntro';
 import HelpMenu from './components/help/HelpMenu';
 
@@ -65,6 +67,7 @@ const PLATFORM_NAV: NavItem[] = [
   { id: 'rare-events', label: 'Rare Events', icon: <Radar size={18} /> },
   { id: 'quality', label: 'Quality Engine', icon: <ShieldCheck size={18} /> },
   { id: 'regression', label: 'Regression', icon: <TrendingDown size={18} /> },
+  { id: 'rca', label: 'Root Cause Lab', icon: <Microscope size={18} /> },
   { id: 'triage', label: 'Triage', icon: <Filter size={18} /> },
   { id: 'review', label: 'Human Review', icon: <UserCheck size={18} /> },
   { id: 'training', label: 'Training', icon: <Rocket size={18} /> },
@@ -87,6 +90,7 @@ const PAGE_TITLES: Record<PageId, string> = {
   'rare-events': 'Rare Event Detection',
   quality: 'Quality Engine',
   regression: 'Regression Tracking',
+  rca: 'Root Cause Lab',
   triage: 'Automated Triage',
   review: 'Human Review (HITL)',
   training: 'Training Flywheel',
@@ -291,6 +295,7 @@ export default function App() {
               {page === 'rare-events' ? <RareEventDashboard /> : null}
               {page === 'quality' ? <QualityEnginePage /> : null}
               {page === 'regression' ? <RegressionPage /> : null}
+              {page === 'rca' ? <RootCauseLabPage /> : null}
               {page === 'triage' ? <TriagePage /> : null}
               {page === 'review' ? <HumanReviewPage /> : null}
               {page === 'training' ? <TrainingPage /> : null}

src/components/help/HelpMenu.tsx

@@ -175,6 +175,7 @@ const PAGE_ORDER: PageId[] = [
   'rare-events',
   'quality',
   'regression',
+  'rca',
   'triage',
   'review',
   'training',
@@ -194,6 +195,7 @@ const PAGE_NAMES: Record<PageId, string> = {
   'rare-events': 'Rare Events',
   quality: 'Quality Engine',
   regression: 'Regression',
+  rca: 'Root Cause Lab',
   triage: 'Triage',
   review: 'Human Review',
   training: 'Training',

src/components/rca/ReportView.tsx

@@ -0,0 +1,189 @@
+/** Stage 12: recommended experiments, minimum-additional-evidence answer,
+ * rendered final report with remediation tiers, JSON/markdown export, and the
+ * training-mode reveal. */
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Chip from '@mui/material/Chip';
+import Collapse from '@mui/material/Collapse';
+import Typography from '@mui/material/Typography';
+import { Download, Eye, FileJson } from 'lucide-react';
+import type { Experiments, Investigation, RcaReport, RevealResponse } from '../../types/rca';
+import { BORDER, CONFIDENCE_COLORS, Explainer, SectionCard, StatusPill, tableSx } from './common';
+
+function download(filename: string, text: string, mime: string) {
+  const blob = new Blob([text], { type: mime });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+}
+
+const COST_COLORS: Record<string, string> = { low: '#66bb6a', medium: '#ffb74d', high: '#ef5350' };
+
+export function ExperimentsView({ exp }: { exp: Experiments }) {
+  return (
+    <>
+      <Explainer text={exp.explainer} />
+      <SectionCard title="Minimum additional evidence required">
+        <Typography variant="body2" sx={{ fontSize: 12.5, color: '#e3eaf0' }}>
+          {exp.minimum_additional_evidence}
+        </Typography>
+        <Box sx={{ display: 'flex', gap: 3, mt: 1 }}>
+          <Typography variant="caption" sx={{ color: '#8a949e' }}>
+            Current effective n: <b>{exp.power.effective_n.toLocaleString()}</b>
+          </Typography>
+          <Typography variant="caption" sx={{ color: '#8a949e' }}>
+            Needed for the {exp.power.practical_margin_pp.toFixed(1)}pp margin:{' '}
+            <b>{exp.power.needed_effective_n.toLocaleString()}</b>
+          </Typography>
+        </Box>
+      </SectionCard>
+      <SectionCard title="Recommended experiments — ranked by information gain / cost">
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr>
+              <th>#</th><th>Design</th><th>Instantiated for this investigation</th>
+              <th>Discriminates</th><th>Cost</th><th>Gain</th><th>Priority</th>
+            </tr>
+          </thead>
+          <tbody>
+            {exp.experiments.map((d) => (
+              <tr key={d.id}>
+                <td style={{ fontWeight: 800 }}>{d.rank}</td>
+                <td style={{ fontWeight: 700, whiteSpace: 'nowrap' }}>{d.design}</td>
+                <td><Typography variant="caption" sx={{ color: '#cfd8e0' }}>{d.description}</Typography></td>
+                <td>
+                  {d.discriminates.map((h) => (
+                    <Chip key={h} size="small" label={h} sx={{ height: 17, fontSize: 9.5, mr: 0.25, mb: 0.25, bgcolor: '#232a31' }} />
+                  ))}
+                </td>
+                <td>
+                  <Chip size="small" label={`${d.cost} · ~${d.expected_days}d`} sx={{
+                    height: 18, fontSize: 10, fontWeight: 700,
+                    bgcolor: `${COST_COLORS[d.cost]}22`, color: COST_COLORS[d.cost],
+                  }} />
+                </td>
+                <td style={{ fontFamily: 'monospace' }}>{d.information_gain.toFixed(1)}</td>
+                <td style={{ fontFamily: 'monospace', fontWeight: 800 }}>{d.priority.toFixed(1)}</td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}
+
+export function ReportView({ report, inv, reveal, onReveal }: {
+  report: RcaReport;
+  inv: Investigation;
+  reveal: RevealResponse | null;
+  onReveal: () => void;
+}) {
+  const [showMd, setShowMd] = useState(false);
+  const ef = report.executive_finding;
+  const confColor = CONFIDENCE_COLORS[ef.confidence];
+  return (
+    <>
+      <SectionCard
+        title="Executive finding"
+        action={
+          <Box sx={{ display: 'flex', gap: 1 }}>
+            <Button size="small" startIcon={<FileJson size={14} />} onClick={() => download(`${report.investigation_id}-report.json`, JSON.stringify(report, null, 2), 'application/json')}>
+              Export JSON
+            </Button>
+            <Button size="small" startIcon={<Download size={14} />} onClick={() => download(`${report.investigation_id}-report.md`, report.markdown, 'text/markdown')}>
+              Export MD
+            </Button>
+          </Box>
+        }
+      >
+        <Typography variant="h6" sx={{ fontWeight: 800, fontSize: 17 }}>
+          {ef.conclusion ?? ef.top_hypothesis}
+          <Chip size="small" label={`confidence: ${ef.confidence}`} sx={{ ml: 1.5, fontWeight: 800, bgcolor: `${confColor}22`, color: confColor, border: `1px solid ${confColor}55` }} />
+        </Typography>
+        <Typography variant="body2" sx={{ color: '#aab4be', mt: 0.5 }}>
+          {ef.label} — score {ef.score} (gap to runner-up {ef.score_gap_to_runner_up}). Claims under
+          investigation: offline {report.claims.offline_delta_pp >= 0 ? '+' : ''}{report.claims.offline_delta_pp}pp vs shadow{' '}
+          {report.claims.shadow_delta_pp}pp on {report.claims.metric}.
+        </Typography>
+      </SectionCard>
+
+      <SectionCard title="Per-stage summary">
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr><th>Stage</th><th>Question</th><th>Verdict</th><th>Mismatches / unknowns</th></tr>
+          </thead>
+          <tbody>
+            {report.stage_summaries.map((s) => (
+              <tr key={s.stage}>
+                <td style={{ fontWeight: 600, whiteSpace: 'nowrap' }}>{s.stage}</td>
+                <td><Typography variant="caption" sx={{ color: '#8a949e' }}>{s.headline}</Typography></td>
+                <td><StatusPill status={s.verdict === 'clean' ? 'PASS' : s.verdict === 'mismatch' ? 'MISMATCH' : 'UNKNOWN'} /></td>
+                <td>
+                  <Typography variant="caption">
+                    {[...s.mismatches, ...s.unknowns].join('; ') || '—'}
+                  </Typography>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+
+      <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 2 }}>
+        {(['containment', 'short_term', 'long_term'] as const).map((tier) => (
+          <SectionCard key={tier} title={tier === 'containment' ? 'Containment (now)' : tier === 'short_term' ? 'Short term' : 'Long term'}>
+            {report.remediation[tier].map((x) => (
+              <Typography key={x} variant="body2" sx={{ fontSize: 12, py: 0.25, color: '#cfd8e0' }}>
+                • {x}
+              </Typography>
+            ))}
+          </SectionCard>
+        ))}
+      </Box>
+
+      {report.acknowledged_unknowns.length ? (
+        <SectionCard title="Unknowns explicitly acknowledged during this investigation">
+          {report.acknowledged_unknowns.map((e, i) => (
+            <Typography key={i} variant="caption" sx={{ display: 'block', color: '#ffb74d' }}>
+              ⚠ {e.message} — note: {String((e.data as any)?.note ?? '')}
+            </Typography>
+          ))}
+        </SectionCard>
+      ) : null}
+
+      <SectionCard
+        title="Raw markdown"
+        action={<Button size="small" onClick={() => setShowMd((s) => !s)}>{showMd ? 'hide' : 'show'}</Button>}
+      >
+        <Collapse in={showMd}>
+          <Box component="pre" sx={{ fontSize: 11, fontFamily: 'monospace', whiteSpace: 'pre-wrap', color: '#aab4be', m: 0, maxHeight: 420, overflowY: 'auto' }}>
+            {report.markdown}
+          </Box>
+        </Collapse>
+      </SectionCard>
+
+      {inv.training_mode ? (
+        <SectionCard title="Training mode — the answer key">
+          {reveal ? (
+            <Box sx={{ p: 1.25, borderRadius: 1, border: `1px solid ${BORDER}`, bgcolor: '#0d1116' }}>
+              <Typography variant="body2" sx={{ fontWeight: 800, color: reveal.cause === ef.top_hypothesis ? '#66bb6a' : '#ef5350' }}>
+                Planted cause: {reveal.cause}{' '}
+                {reveal.cause === ef.top_hypothesis ? '— your board got it right ✓' : `— your board's top pick was ${ef.top_hypothesis} ✗`}
+              </Typography>
+              <Typography variant="caption" sx={{ color: '#aab4be' }}>{reveal.explanation}</Typography>
+            </Box>
+          ) : (
+            <Button variant="outlined" size="small" startIcon={<Eye size={14} />} onClick={onReveal}>
+              Reveal the planted root cause
+            </Button>
+          )}
+        </SectionCard>
+      ) : null}
+    </>
+  );
+}

src/components/rca/StageRail.tsx

@@ -0,0 +1,119 @@
+/** Guided left rail: the 13 ordered stages with status and enforced locking.
+ * A stage is viewable only when every earlier stage is complete (or complete
+ * with acknowledged unknowns) — plausible early explanations don't unlock
+ * later stages; finishing the methodology does. */
+import Box from '@mui/material/Box';
+import LinearProgress from '@mui/material/LinearProgress';
+import List from '@mui/material/List';
+import ListItemButton from '@mui/material/ListItemButton';
+import Tooltip from '@mui/material/Tooltip';
+import Typography from '@mui/material/Typography';
+import { CheckCircle2, CircleDot, Lock, TriangleAlert } from 'lucide-react';
+import type { StageState } from '../../types/rca';
+import { ACCENT, BG_PANEL, BORDER } from './common';
+
+export function firstIncompleteIndex(stages: StageState[]): number {
+  for (const s of stages) {
+    if (s.status !== 'complete' && s.status !== 'complete_with_unknowns') return s.index;
+  }
+  return stages.length;
+}
+
+export default function StageRail({ stages, selected, onSelect }: {
+  stages: StageState[];
+  selected: number;
+  onSelect: (index: number) => void;
+}) {
+  const frontier = firstIncompleteIndex(stages);
+  const done = stages.filter(
+    (s) => s.status === 'complete' || s.status === 'complete_with_unknowns'
+  ).length;
+
+  return (
+    <Box
+      sx={{
+        width: 250,
+        flexShrink: 0,
+        borderRight: `1px solid ${BORDER}`,
+        bgcolor: BG_PANEL,
+        overflowY: 'auto',
+      }}
+    >
+      <Box sx={{ px: 1.5, pt: 1.25, pb: 0.75 }}>
+        <Typography variant="caption" sx={{ color: '#8a949e', fontWeight: 700, letterSpacing: 0.8 }}>
+          METHODOLOGY · {done}/{stages.length}
+        </Typography>
+        <LinearProgress
+          variant="determinate"
+          value={(done / stages.length) * 100}
+          sx={{ mt: 0.5, height: 5, borderRadius: 2, bgcolor: '#0d1116' }}
+        />
+      </Box>
+      <List dense sx={{ py: 0 }}>
+        {stages.map((s) => {
+          const locked = s.index > frontier;
+          const isSel = s.index === selected;
+          const icon =
+            s.status === 'complete' ? (
+              <CheckCircle2 size={15} color="#66bb6a" />
+            ) : s.status === 'complete_with_unknowns' ? (
+              <TriangleAlert size={15} color="#ffb74d" />
+            ) : locked ? (
+              <Lock size={14} color="#5c666f" />
+            ) : (
+              <CircleDot size={15} color={ACCENT} />
+            );
+          const body = (
+            <ListItemButton
+              key={s.key}
+              dense
+              disabled={locked}
+              selected={isSel}
+              onClick={() => onSelect(s.index)}
+              sx={{
+                py: 0.5,
+                px: 1.25,
+                gap: 1,
+                '&.Mui-selected': { bgcolor: 'rgba(79,195,247,0.12)' },
+              }}
+            >
+              <Box sx={{ width: 18, display: 'flex', justifyContent: 'center', flexShrink: 0 }}>{icon}</Box>
+              <Box sx={{ minWidth: 0 }}>
+                <Typography
+                  variant="body2"
+                  sx={{
+                    fontSize: 12.5,
+                    fontWeight: isSel ? 700 : 500,
+                    color: locked ? '#5c666f' : isSel ? ACCENT : '#cfd8e0',
+                    whiteSpace: 'nowrap',
+                    overflow: 'hidden',
+                    textOverflow: 'ellipsis',
+                  }}
+                >
+                  {s.index}. {s.title}
+                </Typography>
+                {s.status === 'complete_with_unknowns' ? (
+                  <Typography variant="caption" sx={{ color: '#ffb74d', fontSize: 10 }}>
+                    proceeded with unknowns
+                  </Typography>
+                ) : null}
+              </Box>
+            </ListItemButton>
+          );
+          return locked ? (
+            <Tooltip
+              key={s.key}
+              title="Locked: complete the earlier stages first. The methodology is ordered on purpose — an early plausible explanation is not a license to skip measurement-validity checks."
+              placement="right"
+              arrow
+            >
+              <span>{body}</span>
+            </Tooltip>
+          ) : (
+            body
+          );
+        })}
+      </List>
+    </Box>
+  );
+}

src/components/rca/boardViews.tsx

@@ -0,0 +1,228 @@
+/** Stage 11 views: the 8-hypothesis Root Cause Board (auto + human
+ * assessments, evidence links that jump to stage findings) and the decision
+ * tree with the live path highlighted. */
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Chip from '@mui/material/Chip';
+import IconButton from '@mui/material/IconButton';
+import MenuItem from '@mui/material/MenuItem';
+import Select from '@mui/material/Select';
+import TextField from '@mui/material/TextField';
+import Tooltip from '@mui/material/Tooltip';
+import Typography from '@mui/material/Typography';
+import { ChevronDown, ChevronRight, Link2 } from 'lucide-react';
+import type { Confidence, DecisionTree, EvidenceLink, RootCause, Scoreboard } from '../../types/rca';
+import { BORDER, CONFIDENCE_COLORS, Explainer, SectionCard, SEVERITY_COLORS, tableSx } from './common';
+
+function ConfidenceChip({ c }: { c: Confidence | null }) {
+  if (!c) return <Typography variant="caption" sx={{ color: '#5c666f' }}>—</Typography>;
+  return (
+    <Chip size="small" label={c} sx={{
+      height: 18, fontSize: 10, fontWeight: 800,
+      bgcolor: `${CONFIDENCE_COLORS[c]}22`, color: CONFIDENCE_COLORS[c],
+      border: `1px solid ${CONFIDENCE_COLORS[c]}55`,
+    }} />
+  );
+}
+
+function EvidenceList({ items, sign, onJump }: {
+  items: EvidenceLink[];
+  sign: '+' | '−';
+  onJump: (stage: string) => void;
+}) {
+  if (!items.length) return <Typography variant="caption" sx={{ color: '#5c666f' }}>none</Typography>;
+  return (
+    <Box>
+      {items.map((e) => (
+        <Box key={`${e.code}-${e.finding_id}`} sx={{ display: 'flex', alignItems: 'center', gap: 0.5, py: 0.15 }}>
+          <Typography variant="caption" sx={{ fontFamily: 'monospace', color: sign === '+' ? '#a5d6a7' : '#ef9a9a', minWidth: 34 }}>
+            {sign}{e.weight.toFixed(1)}
+          </Typography>
+          <Tooltip title={`[${e.code}] from stage "${e.stage}" — click to open that stage`} arrow>
+            <Chip
+              size="small"
+              icon={<Link2 size={11} />}
+              label={e.title}
+              onClick={() => onJump(e.stage)}
+              sx={{
+                height: 19, fontSize: 10.5, maxWidth: 340,
+                bgcolor: '#232a31',
+                color: e.severity === 'CRITICAL' ? SEVERITY_COLORS.CRITICAL : '#cfd8e0',
+                '.MuiChip-icon': { color: '#8a949e', ml: 0.5 },
+              }}
+            />
+          </Tooltip>
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+export function ScoreBoardView({ board, onJumpToStage, onAssess }: {
+  board: Scoreboard;
+  onJumpToStage: (stageKey: string) => void;
+  onAssess: (hypothesis: RootCause, confidence: Confidence, note: string) => void;
+}) {
+  const [open, setOpen] = useState<Record<string, boolean>>({ [board.rows[0]?.hypothesis]: true });
+  const [notes, setNotes] = useState<Record<string, string>>({});
+  return (
+    <>
+      <Explainer text={board.explainer} />
+      <SectionCard title="Root Cause Board — 8 hypotheses, scored from the evidence">
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr>
+              <th /><th>#</th><th>Hypothesis</th><th>Score</th>
+              <th>Auto confidence</th><th>Your assessment</th><th>Next discriminating test</th>
+            </tr>
+          </thead>
+          <tbody>
+            {board.rows.map((r) => (
+              <>
+                <tr key={r.hypothesis} style={r.rank === 1 ? { background: '#4fc3f70d' } : undefined}>
+                  <td>
+                    <IconButton size="small" onClick={() => setOpen((o) => ({ ...o, [r.hypothesis]: !o[r.hypothesis] }))}>
+                      {open[r.hypothesis] ? <ChevronDown size={14} /> : <ChevronRight size={14} />}
+                    </IconButton>
+                  </td>
+                  <td style={{ fontWeight: 800 }}>{r.rank}</td>
+                  <td>
+                    <Typography variant="body2" sx={{ fontWeight: r.rank === 1 ? 800 : 600, fontSize: 12.5 }}>
+                      {r.hypothesis}
+                    </Typography>
+                    <Typography variant="caption" sx={{ color: '#8a949e' }}>{r.label}</Typography>
+                  </td>
+                  <td style={{ fontFamily: 'monospace', fontWeight: 700, color: r.score > 0 ? '#a5d6a7' : '#8a949e' }}>
+                    {r.score.toFixed(1)}
+                  </td>
+                  <td><ConfidenceChip c={r.auto_confidence} /></td>
+                  <td>
+                    <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+                      <Select
+                        size="small"
+                        value={r.human_confidence ?? ''}
+                        displayEmpty
+                        onChange={(e) => onAssess(r.hypothesis, e.target.value as Confidence, notes[r.hypothesis] ?? r.human_note)}
+                        sx={{ fontSize: 11, height: 26, minWidth: 104, '.MuiSelect-select': { py: 0.25 } }}
+                      >
+                        <MenuItem value="" disabled><em>set…</em></MenuItem>
+                        {(['HIGH', 'MEDIUM', 'LOW', 'UNKNOWN'] as Confidence[]).map((c) => (
+                          <MenuItem key={c} value={c} sx={{ fontSize: 12 }}>{c}</MenuItem>
+                        ))}
+                      </Select>
+                      {r.human_confidence ? <ConfidenceChip c={r.human_confidence} /> : null}
+                    </Box>
+                  </td>
+                  <td>
+                    <Typography variant="caption" sx={{ color: '#aab4be', display: 'block', maxWidth: 320 }}>
+                      {r.next_discriminating_test}
+                    </Typography>
+                  </td>
+                </tr>
+                {open[r.hypothesis] ? (
+                  <tr key={`${r.hypothesis}-detail`}>
+                    <td />
+                    <td colSpan={6}>
+                      <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr 1fr', gap: 2, py: 0.5 }}>
+                        <Box>
+                          <Typography variant="caption" sx={{ fontWeight: 800, color: '#a5d6a7' }}>EVIDENCE FOR</Typography>
+                          <EvidenceList items={r.evidence_for} sign="+" onJump={onJumpToStage} />
+                        </Box>
+                        <Box>
+                          <Typography variant="caption" sx={{ fontWeight: 800, color: '#ef9a9a' }}>EVIDENCE AGAINST</Typography>
+                          <EvidenceList items={r.evidence_against} sign="−" onJump={onJumpToStage} />
+                        </Box>
+                        <Box>
+                          <Typography variant="caption" sx={{ fontWeight: 800, color: '#8a949e' }}>YOUR NOTE</Typography>
+                          <TextField
+                            size="small"
+                            fullWidth
+                            multiline
+                            minRows={2}
+                            placeholder="Why do you agree/disagree with the auto assessment?"
+                            defaultValue={r.human_note}
+                            onChange={(e) => setNotes((n) => ({ ...n, [r.hypothesis]: e.target.value }))}
+                            onBlur={(e) => {
+                              if (r.human_confidence && e.target.value !== r.human_note) {
+                                onAssess(r.hypothesis, r.human_confidence, e.target.value);
+                              }
+                            }}
+                            sx={{ '.MuiInputBase-input': { fontSize: 11.5 } }}
+                          />
+                        </Box>
+                      </Box>
+                    </td>
+                  </tr>
+                ) : null}
+              </>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}
+
+// --------------------------------------------------------------- decision tree
+
+const ANSWER_COLORS = { yes: '#66bb6a', no: '#ef5350', unknown: '#ffb74d' };
+
+export function DecisionTreeView({ tree }: { tree: DecisionTree }) {
+  const onPath = new Set(tree.path);
+  const terminal = tree.path[tree.path.length - 1];
+  return (
+    <>
+      <Explainer text={tree.explainer} />
+      <SectionCard title="Decision chain: measurement validity → distribution → parity → significance">
+        <Box sx={{ display: 'flex', flexDirection: 'column' }}>
+          {tree.nodes.map((n, i) => {
+            const active = onPath.has(n.id);
+            const isTerminal = n.id === terminal;
+            const stoppedHere = isTerminal && (n.answer === 'no' || n.id === 'significant');
+            return (
+              <Box key={n.id} sx={{ display: 'flex', gap: 1.5, opacity: active ? 1 : 0.42 }}>
+                <Box sx={{ display: 'flex', flexDirection: 'column', alignItems: 'center', width: 22 }}>
+                  <Box sx={{
+                    width: 14, height: 14, borderRadius: '50%', mt: 0.75, flexShrink: 0,
+                    bgcolor: ANSWER_COLORS[n.answer],
+                    boxShadow: active ? `0 0 8px ${ANSWER_COLORS[n.answer]}88` : 'none',
+                  }} />
+                  {i < tree.nodes.length - 1 ? (
+                    <Box sx={{ width: 2, flex: 1, minHeight: 26, bgcolor: active && !stoppedHere ? '#4fc3f7' : BORDER }} />
+                  ) : null}
+                </Box>
+                <Box sx={{ pb: 2, minWidth: 0 }}>
+                  <Typography variant="body2" sx={{ fontWeight: active ? 700 : 500, fontSize: 12.5 }}>
+                    {n.question}
+                  </Typography>
+                  <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.75, flexWrap: 'wrap', mt: 0.25 }}>
+                    <Chip size="small" label={n.answer.toUpperCase()} sx={{
+                      height: 18, fontSize: 10, fontWeight: 800,
+                      bgcolor: `${ANSWER_COLORS[n.answer]}22`, color: ANSWER_COLORS[n.answer],
+                    }} />
+                    {n.basis.map((b) => (
+                      <Typography key={b} variant="caption" sx={{ fontFamily: 'monospace', color: '#8a949e', fontSize: 10 }}>
+                        {b}
+                      </Typography>
+                    ))}
+                    {n.answer === 'no' && n.conclusion_if_no && active ? (
+                      <Chip size="small" label={`→ ${n.conclusion_if_no}`} sx={{ height: 18, fontSize: 10, fontWeight: 800, bgcolor: '#ef535022', color: '#ef9a9a' }} />
+                    ) : null}
+                  </Box>
+                </Box>
+              </Box>
+            );
+          })}
+        </Box>
+        <Box sx={{ mt: 1, p: 1.25, borderRadius: 1, border: `1px solid ${BORDER}`, bgcolor: '#0d1116' }}>
+          <Typography variant="caption" sx={{ color: '#8a949e', fontWeight: 700 }}>CHAIN CONCLUSION</Typography>
+          <Typography variant="body2" sx={{ fontWeight: 800, color: tree.conclusion_kind === 'insufficient_evidence' ? '#ffb74d' : '#4fc3f7' }}>
+            {tree.conclusion_kind === 'insufficient_evidence'
+              ? `INSUFFICIENT EVIDENCE (leaning ${tree.conclusion})`
+              : tree.conclusion ?? '—'}
+          </Typography>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}

src/components/rca/chartViews.tsx

@@ -0,0 +1,441 @@
+/** Visualization-heavy stage views: distribution shift, conditional
+ * performance heatmap (Simpson's paradox surface), paired transition matrix,
+ * significance CI plot, feature parity ranked deltas. */
+import Box from '@mui/material/Box';
+import Chip from '@mui/material/Chip';
+import Tooltip from '@mui/material/Tooltip';
+import Typography from '@mui/material/Typography';
+import {
+  BORDER,
+  DeltaBar,
+  Explainer,
+  KV,
+  PsiBadge,
+  SectionCard,
+  StatusPill,
+  tableSx,
+} from './common';
+
+// ------------------------------------------------ stage 3: distribution shift
+
+export function ShiftView({ data }: { data: any }) {
+  if (data.volume_ok === false) {
+    return (
+      <>
+        <Explainer text={data.explainer} />
+        <SectionCard title="Distribution shift">
+          <Typography variant="body2" sx={{ color: '#ffb74d' }}>
+            Too little data to assess shift: PSI estimates are upward-biased at
+            this volume, so shift can be neither confirmed nor excluded. This
+            is itself a finding — record it and proceed with the unknown
+            acknowledged.
+          </Typography>
+        </SectionCard>
+      </>
+    );
+  }
+  const renderRows = (rows: any[]) => (
+    <Box component="table" sx={tableSx}>
+      <thead>
+        <tr>
+          <th>Dimension</th>
+          <th>PSI (practical effect)</th>
+          <th>JS div</th>
+          <th>Test</th>
+          <th>p-value (see caveat)</th>
+          <th>Means (off → sh)</th>
+        </tr>
+      </thead>
+      <tbody>
+        {rows.map((r: any) => (
+          <tr key={r.dimension}>
+            <td style={{ fontWeight: 600 }}>{r.dimension}</td>
+            <td><PsiBadge psi={r.psi} /></td>
+            <td style={{ fontFamily: 'monospace' }}>{r.js.toFixed(3)}</td>
+            <td style={{ fontFamily: 'monospace' }}>{r.test}={r.stat.toFixed(2)}</td>
+            <td style={{ fontFamily: 'monospace', color: r.p_value < 0.05 ? '#ffb74d' : '#8a949e' }}>
+              {r.p_value < 0.001 ? '<0.001' : r.p_value.toFixed(3)}
+            </td>
+            <td style={{ fontFamily: 'monospace', fontSize: 11 }}>
+              {r.offline_mean !== undefined
+                ? `${r.offline_mean.toFixed(1)} → ${r.shadow_mean.toFixed(1)}`
+                : '—'}
+            </td>
+          </tr>
+        ))}
+      </tbody>
+    </Box>
+  );
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard title="Population mix (segment dimensions)">
+        {renderRows(data.segments)}
+      </SectionCard>
+      <SectionCard title="Feature distributions" subtitle="An isolated large shift in ONE feature while segment mixes stay stable points at a pipeline artifact, not a population change — cross-check with Feature Parity (stage 7).">
+        {renderRows(data.features)}
+      </SectionCard>
+      <Typography variant="caption" sx={{ color: '#ffb74d' }}>
+        ⚠ {data.caveat}
+      </Typography>
+    </>
+  );
+}
+
+// ------------------------------------------ stage 4: conditional performance
+
+function heatColor(v: number, cap = 12): string {
+  const t = Math.max(-1, Math.min(1, v / cap));
+  if (t >= 0) {
+    const a = Math.round(40 + t * 150);
+    return `rgba(102, 187, 106, ${a / 255})`;
+  }
+  const a = Math.round(40 + -t * 170);
+  return `rgba(239, 83, 80, ${a / 255})`;
+}
+
+export function ConditionalHeatmapView({ data }: { data: any }) {
+  const rows: any[] = data.rows;
+  const scenes = Array.from(new Set(rows.map((r) => r.scene))).sort();
+  const times = Array.from(new Set(rows.map((r) => r.time_of_day))).sort();
+  const cell = (scene: string, tod: string) => rows.find((r) => r.scene === scene && r.time_of_day === tod);
+
+  const grid = (which: 'offline_delta_pp' | 'shadow_delta_pp', title: string) => (
+    <Box>
+      <Typography variant="caption" sx={{ fontWeight: 800, color: '#aab4be', display: 'block', mb: 0.5 }}>
+        {title}
+      </Typography>
+      <Box component="table" sx={{ borderCollapse: 'collapse' }}>
+        <thead>
+          <tr>
+            <th />
+            {times.map((t) => (
+              <Box component="th" key={t} sx={{ fontSize: 11, color: '#8a949e', px: 1, pb: 0.5 }}>{t}</Box>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {scenes.map((s) => (
+            <tr key={s}>
+              <Box component="td" sx={{ fontSize: 11, color: '#8a949e', pr: 1, textAlign: 'right' }}>{s}</Box>
+              {times.map((t) => {
+                const c = cell(s, t);
+                const v = c ? c[which] : 0;
+                return (
+                  <td key={t}>
+                    <Tooltip
+                      arrow
+                      title={c ? `${s}/${t}: offline ${c.offline_delta_pp.toFixed(1)}pp · shadow ${c.shadow_delta_pp.toFixed(1)}pp · n=${c.shadow_n} · ${c.interpretation}` : ''}
+                    >
+                      <Box
+                        sx={{
+                          width: 86,
+                          height: 40,
+                          m: 0.25,
+                          borderRadius: 1,
+                          display: 'flex',
+                          alignItems: 'center',
+                          justifyContent: 'center',
+                          bgcolor: heatColor(v),
+                          border: c?.interpretation === 'sign_flip' ? '2px dashed #ffb74d' : `1px solid ${BORDER}`,
+                          fontFamily: 'monospace',
+                          fontSize: 12,
+                          fontWeight: 700,
+                        }}
+                      >
+                        {v >= 0 ? '+' : ''}{v.toFixed(1)}
+                      </Box>
+                    </Tooltip>
+                  </td>
+                );
+              })}
+            </tr>
+          ))}
+        </tbody>
+      </Box>
+    </Box>
+  );
+
+  const agg = data.aggregate;
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard
+        title="Segment performance heatmap (B − A, pp)"
+        subtitle="Dashed amber border = sign flip between environments. If per-segment colors AGREE while the aggregates disagree, the mix — not the model — flipped the sign (Simpson's paradox)."
+      >
+        <Box sx={{ display: 'flex', gap: 5, flexWrap: 'wrap' }}>
+          {grid('offline_delta_pp', `OFFLINE (aggregate ${agg.offline_delta_pp >= 0 ? '+' : ''}${agg.offline_delta_pp.toFixed(1)}pp)`)}
+          {grid('shadow_delta_pp', `SHADOW (aggregate ${agg.shadow_delta_pp >= 0 ? '+' : ''}${agg.shadow_delta_pp.toFixed(1)}pp)`)}
+        </Box>
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1 }}>
+          Within-segment sign consistency: {(agg.sign_consistency * 100).toFixed(0)}% of scored volume.
+        </Typography>
+      </SectionCard>
+      <SectionCard title="Segment detail">
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr>
+              <th>Segment</th><th>Offline Δ</th><th>Shadow Δ</th><th>Vol (off/sh)</th><th>Shift ×</th><th>Interpretation</th>
+            </tr>
+          </thead>
+          <tbody>
+            {rows.map((r) => (
+              <tr key={r.segment}>
+                <td style={{ fontWeight: 600 }}>{r.segment}</td>
+                <td><DeltaBar value={r.offline_delta_pp} max={18} width={100} /></td>
+                <td><DeltaBar value={r.shadow_delta_pp} max={18} width={100} /></td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11 }}>{r.offline_n}/{r.shadow_n}</td>
+                <td style={{ fontFamily: 'monospace' }}>{r.shift_ratio.toFixed(2)}</td>
+                <td>
+                  <Chip size="small" label={r.interpretation} sx={{
+                    height: 18, fontSize: 10,
+                    bgcolor: r.interpretation === 'sign_flip' ? '#ffb74d22' : '#232a31',
+                    color: r.interpretation === 'sign_flip' ? '#ffb74d' : '#aab4be',
+                  }} />
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}
+
+// ------------------------------------------------ stage 5: paired comparison
+
+function TransitionMatrix({ m, title }: { m: any; title: string }) {
+  const cellSx = (bg: string, color: string) => ({
+    width: 130, height: 62, borderRadius: 1, m: 0.25, p: 1,
+    bgcolor: bg, border: `1px solid ${BORDER}`,
+    display: 'flex', flexDirection: 'column', justifyContent: 'center', color,
+  });
+  return (
+    <Box>
+      <Typography variant="caption" sx={{ fontWeight: 800, color: '#aab4be' }}>{title} (n={m.n.toLocaleString()})</Typography>
+      <Box sx={{ display: 'grid', gridTemplateColumns: 'auto auto auto', alignItems: 'center', mt: 0.5 }}>
+        <Box />
+        <Typography variant="caption" sx={{ textAlign: 'center', color: '#8a949e' }}>B correct</Typography>
+        <Typography variant="caption" sx={{ textAlign: 'center', color: '#8a949e' }}>B incorrect</Typography>
+        <Typography variant="caption" sx={{ color: '#8a949e', pr: 0.5 }}>A correct</Typography>
+        <Box sx={cellSx('#20302144', '#a5d6a7')}>
+          <Typography variant="caption">both correct</Typography>
+          <Typography sx={{ fontFamily: 'monospace', fontWeight: 800 }}>{m.both_correct.toLocaleString()}</Typography>
+        </Box>
+        <Box sx={cellSx('#ef535022', '#ef9a9a')}>
+          <Typography variant="caption" sx={{ fontWeight: 700 }}>REGRESSIONS ↓</Typography>
+          <Typography sx={{ fontFamily: 'monospace', fontWeight: 800 }}>{m.regressions.toLocaleString()}</Typography>
+        </Box>
+        <Typography variant="caption" sx={{ color: '#8a949e', pr: 0.5 }}>A incorrect</Typography>
+        <Box sx={cellSx('#66bb6a22', '#a5d6a7')}>
+          <Typography variant="caption" sx={{ fontWeight: 700 }}>improvements ↑</Typography>
+          <Typography sx={{ fontFamily: 'monospace', fontWeight: 800 }}>{m.improvements.toLocaleString()}</Typography>
+        </Box>
+        <Box sx={cellSx('#232a3155', '#90a4ae')}>
+          <Typography variant="caption">both wrong</Typography>
+          <Typography sx={{ fontFamily: 'monospace', fontWeight: 800 }}>{m.both_wrong.toLocaleString()}</Typography>
+        </Box>
+      </Box>
+      <Typography variant="caption" sx={{ color: '#8a949e' }}>net {m.net_pp >= 0 ? '+' : ''}{m.net_pp.toFixed(1)}pp</Typography>
+    </Box>
+  );
+}
+
+export function PairedTransitionView({ data }: { data: any }) {
+  const drill = (rows: any[], label: string) => (
+    <SectionCard title={`Transitions by ${label}`}>
+      <Box component="table" sx={tableSx}>
+        <thead>
+          <tr>
+            <th>{label}</th><th>Regressions (A✓→B✗)</th><th>Improvements (A✗→B✓)</th>
+            {rows[0]?.lift !== undefined ? <th>Unit share</th> : null}
+            {rows[0]?.lift !== undefined ? <th>Regression lift</th> : null}
+            <th>Net</th>
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((r) => (
+            <tr key={r.segment}>
+              <td style={{ fontWeight: 600, fontFamily: r.segment.startsWith('[') ? 'monospace' : undefined }}>{r.segment}</td>
+              <td style={{ fontFamily: 'monospace', color: '#ef9a9a' }}>{r.regressions}</td>
+              <td style={{ fontFamily: 'monospace', color: '#a5d6a7' }}>{r.improvements}</td>
+              {r.lift !== undefined ? <td style={{ fontFamily: 'monospace' }}>{(r.unit_share * 100).toFixed(0)}%</td> : null}
+              {r.lift !== undefined ? (
+                <td>
+                  <Chip size="small" label={`${r.lift.toFixed(1)}×`} sx={{
+                    height: 18, fontSize: 10, fontWeight: 700,
+                    bgcolor: r.lift >= 1.5 ? '#ef535022' : '#232a31',
+                    color: r.lift >= 1.5 ? '#ef5350' : '#aab4be',
+                  }} />
+                </td>
+              ) : null}
+              <td><DeltaBar value={r.net_pp} max={15} width={90} /></td>
+            </tr>
+          ))}
+        </tbody>
+      </Box>
+    </SectionCard>
+  );
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard title="Error-transition matrix — same units, both models">
+        <Box sx={{ display: 'flex', gap: 6, flexWrap: 'wrap' }}>
+          <TransitionMatrix m={data.shadow} title="SHADOW (scored sample)" />
+          <TransitionMatrix m={data.offline} title="OFFLINE (eval set)" />
+        </Box>
+      </SectionCard>
+      {drill(data.by_band, `serving-confidence band (${data.conf_col})`)}
+      {drill(data.by_segment, 'segment')}
+      {drill(data.by_class, 'object class')}
+    </>
+  );
+}
+
+// ---------------------------------------------------- stage 6: significance
+
+function CiPlot({ res, marginPp }: { res: any; marginPp: number }) {
+  // Scale: pp values mapped onto an SVG x-axis.
+  const w = 560; const h = 90;
+  const lo = Math.min(res.ci_low * 100, -marginPp) - 1.2;
+  const hi = Math.max(res.ci_high * 100, marginPp) + 1.2;
+  const x = (v: number) => ((v - lo) / (hi - lo)) * (w - 40) + 20;
+  const y = 38;
+  return (
+    <svg width={w} height={h}>
+      {/* practical-regression zone */}
+      <rect x={20} y={y - 16} width={x(-marginPp) - 20} height={32} fill="#ef5350" opacity={0.10} />
+      <line x1={x(-marginPp)} y1={y - 22} x2={x(-marginPp)} y2={y + 22} stroke="#ef5350" strokeDasharray="4 3" />
+      <text x={x(-marginPp)} y={y - 26} fill="#ef9a9a" fontSize={10} textAnchor="middle">
+        −{marginPp.toFixed(1)}pp practical margin
+      </text>
+      <line x1={x(0)} y1={y - 22} x2={x(0)} y2={y + 22} stroke="#5c666f" />
+      <text x={x(0)} y={y + 34} fill="#8a949e" fontSize={10} textAnchor="middle">0</text>
+      {/* CI */}
+      <line x1={x(res.ci_low * 100)} y1={y} x2={x(res.ci_high * 100)} y2={y} stroke="#4fc3f7" strokeWidth={4} strokeLinecap="round" />
+      <circle cx={x(res.delta * 100)} cy={y} r={5.5} fill="#4fc3f7" />
+      <text x={x(res.delta * 100)} y={y + 20} fill="#4fc3f7" fontSize={11} textAnchor="middle" fontFamily="monospace">
+        {res.delta * 100 >= 0 ? '+' : ''}{(res.delta * 100).toFixed(2)}pp
+      </text>
+      <text x={x(res.ci_low * 100)} y={y - 10} fill="#8a949e" fontSize={10} textAnchor="middle" fontFamily="monospace">
+        {(res.ci_low * 100).toFixed(2)}
+      </text>
+      <text x={x(res.ci_high * 100)} y={y - 10} fill="#8a949e" fontSize={10} textAnchor="middle" fontFamily="monospace">
+        {(res.ci_high * 100).toFixed(2)}
+      </text>
+    </svg>
+  );
+}
+
+const OUTCOME_LABEL: Record<string, { label: string; color: string }> = {
+  significant_regression: { label: 'SIGNIFICANT REGRESSION', color: '#ef5350' },
+  no_significant_difference: { label: 'NO SIGNIFICANT DIFFERENCE', color: '#66bb6a' },
+  insufficient_evidence: { label: 'INSUFFICIENT EVIDENCE', color: '#ffb74d' },
+};
+
+export function SignificanceView({ data }: { data: any }) {
+  const o = OUTCOME_LABEL[data.outcome];
+  const sp = data.shadow_paired;
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard
+        title="Paired shadow delta vs practical-significance margin"
+        action={<Chip size="small" label={o.label} sx={{ fontWeight: 800, bgcolor: `${o.color}22`, color: o.color, border: `1px solid ${o.color}66` }} />}
+      >
+        <CiPlot res={sp} marginPp={data.practical_margin_pp} />
+        <Box sx={{ display: 'flex', gap: 4, flexWrap: 'wrap', mt: 1 }}>
+          <KV k="Units / clusters" v={`${sp.n.toLocaleString()} / ${sp.n_clusters.toLocaleString()}`} />
+          <KV k="ICC (paired diffs)" v={sp.icc.toFixed(3)} />
+          <KV k="Design effect" v={sp.design_effect.toFixed(2)} />
+          <KV k="Effective n" v={sp.effective_n.toLocaleString()} />
+        </Box>
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 0.5 }}>
+          Engine: {data.engine} — {data.engine_note}
+        </Typography>
+      </SectionCard>
+      {data.seqeval ? (
+        <SectionCard title="Anytime-valid complement (sensorflow.seqeval)">
+          <Box sx={{ display: 'flex', gap: 4, flexWrap: 'wrap' }}>
+            <KV k="Sequential decision" v={<StatusPill status={data.seqeval.decision === 'REGRESSION' ? 'MISMATCH' : data.seqeval.decision === 'PASS' ? 'PASS' : 'UNKNOWN'} />} />
+            <KV k="Confidence sequence" v={`[${(data.seqeval.delta_ci[0] * 100).toFixed(2)}, ${(data.seqeval.delta_ci[1] * 100).toFixed(2)}]pp`} />
+            <KV k="e-value (regression)" v={data.seqeval.e_regression} />
+            <KV k="P(regression | data)" v={data.seqeval.bayes_p_regression ?? '—'} />
+          </Box>
+          <Typography variant="caption" sx={{ color: '#8a949e' }}>{data.seqeval.note}</Typography>
+        </SectionCard>
+      ) : null}
+      <SectionCard title="Per-model accuracy (Wilson 95% CI)">
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr><th>Measurement</th><th>Rate</th><th>95% CI</th><th>n</th></tr>
+          </thead>
+          <tbody>
+            {Object.entries(data.wilson as Record<string, any>).map(([k, v]) => (
+              <tr key={k}>
+                <td style={{ fontWeight: 600 }}>{k.replace('_', ' · model ')}</td>
+                <td style={{ fontFamily: 'monospace' }}>{(v.rate * 100).toFixed(2)}%</td>
+                <td style={{ fontFamily: 'monospace' }}>[{(v.ci_low * 100).toFixed(2)}, {(v.ci_high * 100).toFixed(2)}]</td>
+                <td style={{ fontFamily: 'monospace' }}>{v.n.toLocaleString()}</td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}
+
+// --------------------------------------------------- stage 7: feature parity
+
+export function FeatureParityView({ data }: { data: any }) {
+  const maxSmd = Math.max(...data.rows.map((r: any) => r.within_segment_smd), 1);
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard
+        title="Feature parity — ranked by within-segment SMD"
+        subtitle="Within-segment standardized mean difference controls for population mix: a value that still differs INSIDE matched segments is a pipeline difference, not a world change."
+      >
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr>
+              <th>Feature</th><th>Within-segment SMD</th><th>Raw SMD</th>
+              <th>Mean (off → sh)</th><th>Median ratio</th><th>Missing (off / sh)</th><th>Verdict</th>
+            </tr>
+          </thead>
+          <tbody>
+            {data.rows.map((r: any) => (
+              <tr key={r.feature} style={r.skew_flag ? { background: '#ef535011' } : undefined}>
+                <td style={{ fontWeight: 700 }}>{r.feature}</td>
+                <td>
+                  <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.75 }}>
+                    <Box sx={{ width: 130, height: 9, bgcolor: '#0d1116', borderRadius: 1, border: `1px solid ${BORDER}` }}>
+                      <Box sx={{
+                        width: `${Math.min(100, (r.within_segment_smd / maxSmd) * 100)}%`,
+                        height: '100%',
+                        bgcolor: r.skew_flag ? '#ef5350' : '#4fc3f7',
+                        borderRadius: 1,
+                      }} />
+                    </Box>
+                    <Typography variant="caption" sx={{ fontFamily: 'monospace' }}>{r.within_segment_smd.toFixed(2)}</Typography>
+                  </Box>
+                </td>
+                <td style={{ fontFamily: 'monospace' }}>{r.smd.toFixed(2)}</td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11 }}>{r.offline_mean.toFixed(1)} → {r.shadow_mean.toFixed(1)}</td>
+                <td style={{ fontFamily: 'monospace', fontWeight: r.skew_flag ? 800 : 400, color: r.skew_flag ? '#ef5350' : undefined }}>
+                  ×{r.median_ratio.toFixed(2)}
+                </td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11 }}>
+                  {(r.offline_missing * 100).toFixed(1)}% / {(r.shadow_missing * 100).toFixed(1)}%
+                </td>
+                <td><StatusPill status={r.skew_flag ? 'MISMATCH' : 'PASS'} /></td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}

src/components/rca/common.tsx

@@ -0,0 +1,242 @@
+/** Shared visual language for the RCA workbench (dark theme, chip-heavy). */
+import { type ReactNode } from 'react';
+import Box from '@mui/material/Box';
+import Chip from '@mui/material/Chip';
+import Paper from '@mui/material/Paper';
+import Tooltip from '@mui/material/Tooltip';
+import Typography from '@mui/material/Typography';
+import type { Confidence, Finding, FindingStatus, Severity } from '../../types/rca';
+
+export const ACCENT = '#4fc3f7';
+export const BG_PANEL = '#12171d';
+export const BORDER = '#232a31';
+
+export const STATUS_COLORS: Record<FindingStatus, string> = {
+  PASS: '#66bb6a',
+  MISMATCH: '#ef5350',
+  UNKNOWN: '#ffb74d',
+};
+
+export const SEVERITY_COLORS: Record<Severity, string> = {
+  INFO: '#78909c',
+  WARN: '#ffb74d',
+  CRITICAL: '#ef5350',
+};
+
+export const CONFIDENCE_COLORS: Record<Confidence, string> = {
+  HIGH: '#66bb6a',
+  MEDIUM: '#4fc3f7',
+  LOW: '#90a4ae',
+  UNKNOWN: '#ffb74d',
+};
+
+export function SectionCard({ title, subtitle, children, action }: {
+  title: string;
+  subtitle?: string;
+  action?: ReactNode;
+  children: ReactNode;
+}) {
+  return (
+    <Paper variant="outlined" sx={{ p: 1.75, bgcolor: BG_PANEL, borderColor: BORDER, mb: 2 }}>
+      <Box sx={{ display: 'flex', alignItems: 'flex-start', mb: subtitle ? 0.25 : 1 }}>
+        <Typography variant="subtitle2" sx={{ fontWeight: 800, flex: 1, fontSize: 13.5 }}>
+          {title}
+        </Typography>
+        {action}
+      </Box>
+      {subtitle ? (
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1.25 }}>
+          {subtitle}
+        </Typography>
+      ) : null}
+      {children}
+    </Paper>
+  );
+}
+
+export function StatusPill({ status }: { status: string }) {
+  const norm = status.toUpperCase() as FindingStatus;
+  const map: Record<string, { c: string; label: string }> = {
+    PASS: { c: STATUS_COLORS.PASS, label: 'PASS' },
+    MISMATCH: { c: STATUS_COLORS.MISMATCH, label: 'MISMATCH' },
+    UNKNOWN: { c: STATUS_COLORS.UNKNOWN, label: 'UNKNOWN' },
+    COMPARABLE: { c: STATUS_COLORS.PASS, label: 'comparable' },
+    MATCH: { c: STATUS_COLORS.PASS, label: 'match' },
+    EXPECTED_DIFFERENCE: { c: '#78909c', label: 'expected diff' },
+  };
+  const m = map[norm] ?? map[status.toUpperCase().replace(/ /g, '_')] ?? {
+    c: SEVERITY_COLORS.WARN,
+    label: status,
+  };
+  return (
+    <Chip
+      size="small"
+      label={m.label}
+      sx={{ height: 18, fontSize: 10, fontWeight: 700, bgcolor: `${m.c}22`, color: m.c, border: `1px solid ${m.c}55` }}
+    />
+  );
+}
+
+export function FindingChip({ finding, onClick }: { finding: Finding; onClick?: () => void }) {
+  const c = STATUS_COLORS[finding.status];
+  const sev = SEVERITY_COLORS[finding.severity];
+  return (
+    <Tooltip
+      title={
+        <Box sx={{ maxWidth: 380 }}>
+          <Typography variant="caption" sx={{ fontWeight: 700, display: 'block' }}>
+            [{finding.code}] {finding.title}
+          </Typography>
+          <Typography variant="caption">{finding.detail}</Typography>
+        </Box>
+      }
+      arrow
+    >
+      <Chip
+        size="small"
+        onClick={onClick}
+        label={
+          <span>
+            <b style={{ color: c }}>{finding.status}</b>
+            {finding.severity !== 'INFO' ? (
+              <b style={{ color: sev }}>{` · ${finding.severity}`}</b>
+            ) : null}
+            {` · ${finding.title}`}
+            {finding.source === 'human' ? ' · 👤' : ''}
+          </span>
+        }
+        sx={{
+          height: 22,
+          fontSize: 11,
+          bgcolor: `${c}14`,
+          border: `1px solid ${c}44`,
+          mr: 0.5,
+          mb: 0.5,
+          '.MuiChip-label': { px: 1 },
+        }}
+      />
+    </Tooltip>
+  );
+}
+
+export function FindingChips({ findings, onClick }: {
+  findings: Finding[];
+  onClick?: (f: Finding) => void;
+}) {
+  if (!findings.length) return null;
+  return (
+    <Box sx={{ display: 'flex', flexWrap: 'wrap', mt: 0.5 }}>
+      {findings.map((f) => (
+        <FindingChip key={f.id} finding={f} onClick={onClick ? () => onClick(f) : undefined} />
+      ))}
+    </Box>
+  );
+}
+
+export function Explainer({ text }: { text: string }) {
+  return (
+    <Box sx={{ borderLeft: `3px solid ${ACCENT}55`, pl: 1.25, py: 0.25, mb: 1.5 }}>
+      <Typography variant="caption" sx={{ color: '#aab4be' }}>
+        {text}
+      </Typography>
+    </Box>
+  );
+}
+
+/** Horizontal signed delta bar centered at zero (pp values). */
+export function DeltaBar({ value, max, width = 140 }: { value: number; max: number; width?: number }) {
+  const half = width / 2;
+  const frac = Math.min(1, Math.abs(value) / Math.max(1e-9, max));
+  const w = Math.max(1.5, frac * half);
+  const color = value >= 0 ? '#66bb6a' : '#ef5350';
+  return (
+    <Box sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.75 }}>
+      <svg width={width} height={14}>
+        <line x1={half} y1={0} x2={half} y2={14} stroke={BORDER} strokeWidth={1} />
+        <rect
+          x={value >= 0 ? half : half - w}
+          y={2.5}
+          width={w}
+          height={9}
+          rx={2}
+          fill={color}
+          opacity={0.85}
+        />
+      </svg>
+      <Typography
+        variant="caption"
+        sx={{ fontFamily: 'monospace', color, minWidth: 52, textAlign: 'right' }}
+      >
+        {value >= 0 ? '+' : ''}
+        {value.toFixed(1)}pp
+      </Typography>
+    </Box>
+  );
+}
+
+/** Simple 0..1 proportion bar for mix comparisons. */
+export function ShareBar({ value, color = ACCENT, width = 90 }: {
+  value: number;
+  color?: string;
+  width?: number;
+}) {
+  return (
+    <Box sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.5 }}>
+      <Box sx={{ width, height: 8, bgcolor: '#0d1116', borderRadius: 1, overflow: 'hidden', border: `1px solid ${BORDER}` }}>
+        <Box sx={{ width: `${Math.min(100, value * 100)}%`, height: '100%', bgcolor: color }} />
+      </Box>
+      <Typography variant="caption" sx={{ fontFamily: 'monospace', color: '#8a949e', minWidth: 40 }}>
+        {(value * 100).toFixed(1)}%
+      </Typography>
+    </Box>
+  );
+}
+
+export function PsiBadge({ psi }: { psi: number }) {
+  const mag = psi < 0.02 ? 'negligible' : psi < 0.1 ? 'small' : psi < 0.25 ? 'moderate' : 'large';
+  const color = mag === 'large' ? '#ef5350' : mag === 'moderate' ? '#ffb74d' : mag === 'small' ? '#4fc3f7' : '#78909c';
+  return (
+    <Tooltip title="Population Stability Index: practical shift magnitude, independent of p-values (<0.02 negligible, <0.1 small, <0.25 moderate, ≥0.25 large)" arrow>
+      <Chip
+        size="small"
+        label={`PSI ${psi.toFixed(2)} · ${mag}`}
+        sx={{ height: 18, fontSize: 10, fontWeight: 700, bgcolor: `${color}22`, color, border: `1px solid ${color}55` }}
+      />
+    </Tooltip>
+  );
+}
+
+export function KV({ k, v }: { k: string; v: ReactNode }) {
+  return (
+    <Box sx={{ display: 'flex', gap: 1, py: 0.2 }}>
+      <Typography variant="caption" sx={{ color: '#8a949e', minWidth: 190 }}>
+        {k}
+      </Typography>
+      <Typography variant="caption" component="div" sx={{ fontFamily: 'monospace' }}>
+        {v}
+      </Typography>
+    </Box>
+  );
+}
+
+export const tableSx = {
+  width: '100%',
+  borderCollapse: 'collapse' as const,
+  fontSize: 12,
+  '& th': {
+    textAlign: 'left' as const,
+    color: '#8a949e',
+    fontWeight: 700,
+    borderBottom: `1px solid ${BORDER}`,
+    px: 1,
+    py: 0.6,
+    fontSize: 11,
+    whiteSpace: 'nowrap' as const,
+  },
+  '& td': {
+    borderBottom: `1px solid ${BORDER}55`,
+    px: 1,
+    py: 0.55,
+    verticalAlign: 'middle' as const,
+  },
+};

src/components/rca/dialogs.tsx

@@ -0,0 +1,94 @@
+/** Dialogs: record a human finding; acknowledge unknowns to complete a stage. */
+import { useState } from 'react';
+import Button from '@mui/material/Button';
+import Dialog from '@mui/material/Dialog';
+import DialogActions from '@mui/material/DialogActions';
+import DialogContent from '@mui/material/DialogContent';
+import DialogTitle from '@mui/material/DialogTitle';
+import MenuItem from '@mui/material/MenuItem';
+import TextField from '@mui/material/TextField';
+import Typography from '@mui/material/Typography';
+import type { FindingStatus, Severity } from '../../types/rca';
+
+export function RecordFindingDialog({ open, stageTitle, onClose, onSubmit }: {
+  open: boolean;
+  stageTitle: string;
+  onClose: () => void;
+  onSubmit: (f: { title: string; status: FindingStatus; severity: Severity; detail: string }) => void;
+}) {
+  const [title, setTitle] = useState('');
+  const [status, setStatus] = useState<FindingStatus>('MISMATCH');
+  const [severity, setSeverity] = useState<Severity>('WARN');
+  const [detail, setDetail] = useState('');
+  const reset = () => { setTitle(''); setStatus('MISMATCH'); setSeverity('WARN'); setDetail(''); };
+  return (
+    <Dialog open={open} onClose={onClose} maxWidth="sm" fullWidth>
+      <DialogTitle sx={{ fontSize: 15, fontWeight: 800 }}>Record finding — {stageTitle}</DialogTitle>
+      <DialogContent sx={{ display: 'flex', flexDirection: 'column', gap: 1.5, pt: '8px !important' }}>
+        <TextField
+          label="Finding" size="small" fullWidth autoFocus value={title}
+          onChange={(e) => setTitle(e.target.value)}
+          placeholder="e.g. Confirmed with infra team: feature pipeline fp-2.5 deployed online only"
+        />
+        <TextField select label="Status" size="small" value={status} onChange={(e) => setStatus(e.target.value as FindingStatus)}>
+          {(['PASS', 'MISMATCH', 'UNKNOWN'] as FindingStatus[]).map((s) => <MenuItem key={s} value={s}>{s}</MenuItem>)}
+        </TextField>
+        <TextField select label="Severity" size="small" value={severity} onChange={(e) => setSeverity(e.target.value as Severity)}>
+          {(['INFO', 'WARN', 'CRITICAL'] as Severity[]).map((s) => <MenuItem key={s} value={s}>{s}</MenuItem>)}
+        </TextField>
+        <TextField
+          label="Detail / evidence" size="small" fullWidth multiline minRows={2} value={detail}
+          onChange={(e) => setDetail(e.target.value)}
+        />
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose}>Cancel</Button>
+        <Button
+          variant="contained" disabled={!title.trim()}
+          onClick={() => { onSubmit({ title: title.trim(), status, severity, detail }); reset(); }}
+        >
+          Record
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+
+export function AcknowledgeUnknownsDialog({ open, stageTitle, unknownTitles, onClose, onAcknowledge }: {
+  open: boolean;
+  stageTitle: string;
+  unknownTitles: string[];
+  onClose: () => void;
+  onAcknowledge: (note: string) => void;
+}) {
+  const [note, setNote] = useState('');
+  return (
+    <Dialog open={open} onClose={onClose} maxWidth="sm" fullWidth>
+      <DialogTitle sx={{ fontSize: 15, fontWeight: 800, color: '#ffb74d' }}>
+        Proceed with unknowns? — {stageTitle}
+      </DialogTitle>
+      <DialogContent sx={{ pt: '4px !important' }}>
+        <Typography variant="body2" sx={{ mb: 1 }}>
+          This stage has critical UNKNOWN findings. Completing it without resolving them
+          will be permanently recorded on the investigation ("proceeding with unknowns")
+          and will appear in the final report.
+        </Typography>
+        {unknownTitles.map((t) => (
+          <Typography key={t} variant="caption" sx={{ display: 'block', color: '#ffb74d' }}>
+            ? {t}
+          </Typography>
+        ))}
+        <TextField
+          label="Why is it acceptable to proceed? (recorded)" size="small" fullWidth multiline minRows={2}
+          sx={{ mt: 1.5 }} value={note} onChange={(e) => setNote(e.target.value)}
+        />
+      </DialogContent>
+      <DialogActions>
+        <Button onClick={onClose}>Go back and resolve</Button>
+        <Button color="warning" variant="contained" disabled={!note.trim()} onClick={() => { onAcknowledge(note.trim()); setNote(''); }}>
+          Acknowledge and proceed
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}

src/components/rca/stageViews.tsx

@@ -0,0 +1,278 @@
+/** Table-style stage views: comparison validity, offline audit, population,
+ * serving parity, shadow traffic, label integrity. Each receives the
+ * diagnostics payload for its stage. */
+import Box from '@mui/material/Box';
+import Chip from '@mui/material/Chip';
+import Typography from '@mui/material/Typography';
+import {
+  DeltaBar,
+  Explainer,
+  KV,
+  PsiBadge,
+  SectionCard,
+  ShareBar,
+  StatusPill,
+  tableSx,
+} from './common';
+
+const num = (v: unknown, digits = 2): string =>
+  typeof v === 'number' ? v.toFixed(digits) : String(v ?? '—');
+
+// ------------------------------------------------ stage 0: comparison validity
+
+export function ComparisonValidityView({ data }: { data: any }) {
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard
+        title="Comparison-validity matrix"
+        subtitle="Offline harness vs shadow serving, dimension by dimension. Mismatch rows are candidate explanations that must be ruled out before believing either headline number."
+      >
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr>
+              <th>Dimension</th>
+              <th>Offline</th>
+              <th>Shadow</th>
+              <th>Verdict</th>
+              <th>If mismatched</th>
+            </tr>
+          </thead>
+          <tbody>
+            {data.rows.map((r: any) => (
+              <tr key={r.field}>
+                <td style={{ fontWeight: 600 }}>{r.label}</td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11.5 }}>{String(r.offline ?? 'unrecorded')}</td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11.5 }}>{String(r.shadow ?? 'unrecorded')}</td>
+                <td><StatusPill status={r.status} /></td>
+                <td>
+                  <Typography variant="caption" sx={{ color: r.criticality === 'CRITICAL' ? '#ef5350' : '#8a949e' }}>
+                    {r.criticality}
+                  </Typography>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}
+
+// ---------------------------------------------------- stage 1: offline audit
+
+export function OfflineAuditView({ data }: { data: any }) {
+  const r = data.reproducibility;
+  const l = data.leakage;
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 2 }}>
+        <SectionCard title="Reproducibility fingerprint">
+          <KV k="Claimed offline delta" v={`${num(r.original_delta_pp)}pp`} />
+          <KV k="Re-run delta" v={`${num(r.rerun_delta_pp)}pp`} />
+          <KV k="|difference|" v={`${num(r.abs_diff_pp)}pp`} />
+          <KV k="Reproduces (<0.5pp)" v={<StatusPill status={r.reproduces ? 'PASS' : 'MISMATCH'} />} />
+          <KV k="Version pins present" v={<StatusPill status={r.pins_present ? 'PASS' : 'UNKNOWN'} />} />
+          <KV k="Environment lock" v={r.environment_lock} />
+        </SectionCard>
+        <SectionCard title="Leakage scan (train ∩ eval)">
+          <KV k="Near-duplicate eval units" v={`${l.n_duplicates} (${(l.dup_fraction * 100).toFixed(1)}% of ${l.offline_n})`} />
+          <KV k="Entities also in B's train set" v={l.overlap_entity_count} />
+          <KV k="Delta on leaked units" v={<DeltaBar value={l.dup_delta_pp} max={25} />} />
+          <KV k="Delta on clean units" v={<DeltaBar value={l.clean_delta_pp} max={25} />} />
+          {l.overlap_examples?.length ? (
+            <KV k="Examples" v={l.overlap_examples.join(', ')} />
+          ) : null}
+        </SectionCard>
+        <SectionCard title="Split-boundary analysis">
+          <KV k="Split strategy" v={<StatusPill status={data.split.strategy === 'entity_level' ? 'PASS' : 'MISMATCH'} />} />
+          <KV k="Strategy" v={data.split.strategy} />
+          <KV k="Eval entities" v={data.split.n_entities} />
+          <KV k="Mean units / entity" v={num(data.split.mean_units_per_entity, 1)} />
+        </SectionCard>
+        <SectionCard title="Temporal leakage">
+          <KV k="Eval window after B train end" v={<StatusPill status={data.temporal.ok ? 'PASS' : 'MISMATCH'} />} />
+          <KV k="B train window" v={data.temporal.b_train_window} />
+        </SectionCard>
+      </Box>
+    </>
+  );
+}
+
+// ---------------------------------------------- stage 2: population validation
+
+export function PopulationView({ data }: { data: any }) {
+  const v = data.volumes;
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard title="Volumes">
+        <Box sx={{ display: 'flex', gap: 4, flexWrap: 'wrap' }}>
+          <KV k="Offline eval units" v={v.offline_n.toLocaleString()} />
+          <KV k="Shadow eligible" v={v.shadow_eligible_n.toLocaleString()} />
+          <KV k="Shadow scored" v={v.shadow_scored_n.toLocaleString()} />
+          <KV k="Sampling rate" v={`${(v.sampling_rate * 100).toFixed(1)}%`} />
+          <KV k="Entities (off / sh)" v={`${v.offline_entities} / ${v.shadow_entities}`} />
+          <KV k="Entity overlap" v={v.entity_overlap} />
+        </Box>
+      </SectionCard>
+      {Object.entries(data.dimensions as Record<string, any[]>).map(([dim, rows]) => (
+        <SectionCard key={dim} title={`Composition: ${dim}`}>
+          <Box component="table" sx={tableSx}>
+            <thead>
+              <tr><th>Value</th><th>Offline share</th><th>Shadow share</th></tr>
+            </thead>
+            <tbody>
+              {rows.map((r: any) => (
+                <tr key={r.value}>
+                  <td style={{ fontWeight: 600 }}>{r.value}</td>
+                  <td><ShareBar value={r.offline_share} color="#78909c" /></td>
+                  <td><ShareBar value={r.shadow_share} /></td>
+                </tr>
+              ))}
+            </tbody>
+          </Box>
+        </SectionCard>
+      ))}
+    </>
+  );
+}
+
+// ----------------------------------------------------- stage 8: serving parity
+
+export function ServingParityView({ data }: { data: any }) {
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <SectionCard
+        title="Serving artifact / config diff"
+        subtitle="The exact stack difference between what was evaluated offline and what shadow actually runs."
+      >
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr><th>Artifact / config</th><th>Offline harness</th><th>Shadow serving</th><th>Verdict</th><th>Criticality</th></tr>
+          </thead>
+          <tbody>
+            {data.rows.map((r: any) => (
+              <tr key={r.field}>
+                <td style={{ fontWeight: 600 }}>{r.label}</td>
+                <td style={{ fontFamily: 'monospace' }}>{String(r.offline ?? 'unrecorded')}</td>
+                <td style={{ fontFamily: 'monospace' }}>{String(r.shadow ?? 'unrecorded')}</td>
+                <td><StatusPill status={r.status} /></td>
+                <td>
+                  <Typography variant="caption" sx={{ color: r.criticality === 'CRITICAL' ? '#ef5350' : '#8a949e' }}>
+                    {r.criticality}
+                  </Typography>
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      </SectionCard>
+    </>
+  );
+}
+
+// ----------------------------------------------------- stage 9: shadow traffic
+
+export function TrafficAuditView({ data }: { data: any }) {
+  const t = data.traffic;
+  const s = data.selection;
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 2 }}>
+        <SectionCard title="Traffic accounting">
+          <KV k="Eligible units" v={t.eligible_count.toLocaleString()} />
+          <KV k="Sampled / scored" v={`${t.sampled_count.toLocaleString()} (${(t.sampling_rate * 100).toFixed(1)}%)`} />
+          <KV k="Dropped" v={t.dropped_count.toLocaleString()} />
+          <KV k="Timeouts" v={t.timeout_count.toLocaleString()} />
+          <KV k="Fallback engaged" v={t.fallback_count.toLocaleString()} />
+          <KV k="Sampler" v={t.sampler} />
+          <Box sx={{ mt: 0.5 }}>
+            {t.eligibility_filters.map((f: string) => (
+              <Chip key={f} size="small" label={f} sx={{ mr: 0.5, mb: 0.5, height: 20, fontSize: 10.5, bgcolor: '#232a31' }} />
+            ))}
+          </Box>
+        </SectionCard>
+        <SectionCard
+          title="Selection-bias indicators"
+          subtitle="Does the scored sample statistically match the eligible stream it claims to represent?"
+        >
+          <KV k="Difficulty shift (sampled vs eligible)" v={<PsiBadge psi={s.difficulty_psi} />} />
+          <KV k="Confidence shift" v={<PsiBadge psi={s.conf_psi} />} />
+          <KV k="Segment mix shift" v={<PsiBadge psi={s.segment_psi} />} />
+          <KV k="Δ on scored sample" v={<DeltaBar value={s.sampled_delta_pp} max={8} />} />
+          <KV k="Δ on unsampled remainder" v={<DeltaBar value={s.unsampled_delta_pp} max={8} />} />
+          <KV k="Δ on full eligible stream" v={<DeltaBar value={s.eligible_delta_pp} max={8} />} />
+          <KV k="Dropped+fallback+timeout rate" v={`${(s.drop_rate * 100).toFixed(1)}%`} />
+        </SectionCard>
+      </Box>
+    </>
+  );
+}
+
+// --------------------------------------------------- stage 10: label integrity
+
+export function LabelIntegrityView({ data }: { data: any }) {
+  const maxCount = Math.max(...data.age_histogram.map((h: any) => h.count), 1);
+  return (
+    <>
+      <Explainer text={data.explainer} />
+      <Box sx={{ display: 'grid', gridTemplateColumns: '1fr 1fr', gap: 2 }}>
+        <SectionCard title="Label age distribution" subtitle={`Maturity threshold: ${data.maturity_hours}h (audited labels).`}>
+          {data.age_histogram.map((h: any) => (
+            <Box key={h.bucket} sx={{ display: 'flex', alignItems: 'center', gap: 1, py: 0.2 }}>
+              <Typography variant="caption" sx={{ minWidth: 70, color: '#8a949e', fontFamily: 'monospace' }}>
+                {h.bucket}
+              </Typography>
+              <Box sx={{ flex: 1, height: 10, bgcolor: '#0d1116', borderRadius: 1 }}>
+                <Box sx={{ width: `${(h.count / maxCount) * 100}%`, height: '100%', bgcolor: '#4fc3f7', borderRadius: 1 }} />
+              </Box>
+              <Typography variant="caption" sx={{ fontFamily: 'monospace', minWidth: 44, textAlign: 'right' }}>
+                {h.count}
+              </Typography>
+            </Box>
+          ))}
+          <Box sx={{ mt: 1 }}>
+            <KV k="Provisional fraction" v={`${(data.provisional_fraction * 100).toFixed(1)}%`} />
+            <KV k="Labeling policy (off / sh)" v={`${data.policy.offline} / ${data.policy.shadow}`} />
+            <KV k="Policy differs" v={<StatusPill status={data.policy.differs ? 'MISMATCH' : 'PASS'} />} />
+          </Box>
+        </SectionCard>
+        <SectionCard
+          title="Verdict by label maturity"
+          subtitle="If the conclusion flips between mature and provisional labels, the -2% is a property of the labels, not the model."
+        >
+          <KV k={`Mature labels (n=${data.mature_n})`} v={<DeltaBar value={data.mature_delta_pp} max={10} />} />
+          <KV k={`Provisional labels (n=${data.provisional_n})`} v={<DeltaBar value={data.provisional_delta_pp} max={10} />} />
+          <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1.5, mb: 0.5, fontWeight: 700 }}>
+            BY DIFFICULTY QUARTILE
+          </Typography>
+          <Box component="table" sx={tableSx}>
+            <thead>
+              <tr><th>Quartile</th><th>Provisional %</th><th>Δ (all)</th><th>Δ (provisional)</th></tr>
+            </thead>
+            <tbody>
+              {data.by_difficulty_quartile.map((q: any) => (
+                <tr key={q.quartile}>
+                  <td style={{ fontWeight: 600 }}>{q.quartile}</td>
+                  <td>{(q.provisional_frac * 100).toFixed(0)}%</td>
+                  <td><DeltaBar value={q.delta_pp} max={15} width={90} /></td>
+                  <td>
+                    {q.provisional_delta_pp == null ? (
+                      <Typography variant="caption" sx={{ color: '#5c666f' }}>n too small</Typography>
+                    ) : (
+                      <DeltaBar value={q.provisional_delta_pp} max={15} width={90} />
+                    )}
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </Box>
+        </SectionCard>
+      </Box>
+    </>
+  );
+}

src/content/glossary.ts

@@ -619,6 +619,41 @@ export const GLOSSARY: Record<string, GlossaryEntry> = {
     detail: 'Keyed by a hash of (run, filters, group-by, metrics). Hit rate shown in the header; identical dashboard queries return in ~0.1 ms.',
     caveat: 'Invalidated when a run publishes new artifacts.',
   },
+
+  // ------------------------------------------------- root cause analysis (RCA)
+  psi: {
+    term: 'PSI (Population Stability Index)',
+    category: 'Aggregation & scale',
+    short: 'Practical magnitude of a distribution change between two populations.',
+    detail: 'Sum over bins of (actual% − expected%) × ln(actual%/expected%). Rule of thumb: <0.02 negligible, <0.1 small, <0.25 moderate, ≥0.25 large. Used in the Root Cause Lab to compare offline vs shadow populations independently of p-values.',
+    caveat: 'At large n almost any change is statistically significant; PSI answers "does it matter", not "is it detectable".',
+  },
+  effective_sample_size: {
+    term: 'Effective sample size',
+    category: 'Human grading & sampling',
+    short: 'The number of independent observations your correlated data is actually worth.',
+    detail: 'Rows from the same entity (scene/track) are correlated; n_eff = n / design-effect where the design effect grows with cluster size and intra-cluster correlation. Confidence intervals in the Root Cause Lab use n_eff, not raw row counts.',
+    caveat: 'Using raw n on clustered evaluation data makes CIs look several times narrower than they really are.',
+  },
+  simpsons_paradox: {
+    term: "Simpson's paradox",
+    category: 'Aggregation & scale',
+    short: 'Aggregate trend reverses the trend present in every segment.',
+    detail: 'If a model improves within every segment but the population mix shifts toward segments where it is weaker, the aggregate can show a regression that no segment shows. The conditional-performance heatmap in the Root Cause Lab surfaces this: consistent per-segment deltas + a mix shift.',
+  },
+  training_serving_skew: {
+    term: 'Training–serving skew',
+    category: 'Operations',
+    short: 'A feature is computed differently offline than in production serving.',
+    detail: 'Unit changes, normalization differences or missing upstream signals make the serving-time feature distribution diverge from the offline one; the model then sees inputs unlike its training data. Detected in the feature-parity stage as a large standardized mean difference concentrated in specific features.',
+    caveat: 'Diagnose within segments: an aggregate feature delta can also be an honest population shift.',
+  },
+  shadow_evaluation: {
+    term: 'Shadow evaluation',
+    category: 'Operations',
+    short: 'Running a candidate model on live traffic without acting on its output.',
+    detail: 'The candidate scores real production inputs in parallel with the incumbent; outcomes are compared post-hoc. Sensitive to sampling bias, serving-config differences and provisional labels — which is why the Root Cause Lab audits the shadow pipeline before trusting its number.',
+  },
 };
 
 export type GlossaryKey = keyof typeof GLOSSARY;

src/content/pageHelp.ts

@@ -179,6 +179,18 @@ export const PAGE_HELP: Record<PageId, PageHelpEntry> = {
     actions: 'Navigate to any stage\u2019s page; use it as the mental model for the rest of the app.',
     dataFlow: 'This page is the map, not a stage: it visualizes the flows the other pages implement.',
   },
+  rca: {
+    subtitle:
+      'Guided forensic workbench for evaluation discrepancies: when offline says +5% and shadow production says −2%, walk a 13-stage skeptical methodology to find out which number is real — and why.',
+    purpose:
+      'A metric disagreement has at least eight competing explanations (true regression, distribution shift, feature skew, serving mismatch, label latency, sampling bias, noise, offline contamination). Jumping to the plausible one is how bad models ship and good models die. This lab enforces the full measurement-validity → distribution → parity → significance chain before any conclusion is allowed.',
+    reading:
+      'The left rail is the methodology: stages unlock strictly in order, and a stage with critical UNKNOWN findings can only be completed by explicitly acknowledging them (recorded forever). The banner keeps the current working-hypothesis set visible — never a single premature conclusion. Each stage screen shows its diagnostic (validity matrix, PSI-badged shift comparisons, the segment heatmap that surfaces Simpson\u2019s paradox, the 2\u00d72 error-transition matrix, the CI-vs-practical-margin plot, ranked feature-parity deltas). Stage 11 is the Root Cause Board: 8 hypotheses scored purely from recorded findings with evidence links back to their stage.',
+    actions:
+      'Create an investigation (choose a scenario, or a demo with a hidden planted cause for training). Work each stage: review diagnostics, record your own findings, complete or acknowledge-and-proceed. Adjust hypothesis confidences on the board with notes, then export the final report (JSON/markdown) with remediation tiers and the minimum-additional-evidence answer.',
+    dataFlow:
+      'Investigations generate a paired offline + shadow evaluation dataset (persisted under runs/rca/). Every diagnostic is computed from that data — nothing is invented — and every board score traces to a recorded finding. Reports feed promotion decisions and the recommended follow-up experiments.',
+  },
   ssam: {
     subtitle:
       'Surrogate-safety analysis of real intersections: conflicts ranked by TTC / PET / severity on an interactive map — the safety context the label platform feeds.',

src/context/LabelEvalContext.tsx

@@ -16,6 +16,7 @@ export type PageId =
   | 'evaluation'
   | 'audit'
   | 'pipeline'
+  | 'rca'
   | 'ssam'
   | 'legacy';
 
@@ -34,6 +35,7 @@ export const ALL_PAGE_IDS: PageId[] = [
   'evaluation',
   'audit',
   'pipeline',
+  'rca',
   'ssam',
   'legacy',
 ];

src/pages/rca/RootCauseLabPage.tsx

@@ -0,0 +1,441 @@
+/** Root Cause Lab — a guided, skeptical workbench for "offline says +5%,
+ * shadow says −2%": 13 enforced stages from comparison validity through
+ * root-cause scoring to recommended experiments. */
+import { type ComponentType, useCallback, useEffect, useMemo, useState } from 'react';
+import Alert from '@mui/material/Alert';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Chip from '@mui/material/Chip';
+import CircularProgress from '@mui/material/CircularProgress';
+import MenuItem from '@mui/material/MenuItem';
+import Paper from '@mui/material/Paper';
+import TextField from '@mui/material/TextField';
+import Typography from '@mui/material/Typography';
+import { ArrowLeft, CheckCheck, FlaskConical, Plus, StickyNote } from 'lucide-react';
+import * as api from '../../services/rca';
+import type {
+  Confidence,
+  DecisionTree,
+  DiagnosticsResponse,
+  Experiments,
+  Investigation,
+  InvestigationSummary,
+  RcaReport,
+  RevealResponse,
+  RootCause,
+  Scoreboard,
+} from '../../types/rca';
+import {
+  BG_PANEL,
+  BORDER,
+  Explainer,
+  FindingChips,
+  SectionCard,
+  tableSx,
+} from '../../components/rca/common';
+import StageRail, { firstIncompleteIndex } from '../../components/rca/StageRail';
+import {
+  ComparisonValidityView,
+  LabelIntegrityView,
+  OfflineAuditView,
+  PopulationView,
+  ServingParityView,
+  TrafficAuditView,
+} from '../../components/rca/stageViews';
+import {
+  ConditionalHeatmapView,
+  FeatureParityView,
+  PairedTransitionView,
+  ShiftView,
+  SignificanceView,
+} from '../../components/rca/chartViews';
+import { DecisionTreeView, ScoreBoardView } from '../../components/rca/boardViews';
+import { ExperimentsView, ReportView } from '../../components/rca/ReportView';
+import { AcknowledgeUnknownsDialog, RecordFindingDialog } from '../../components/rca/dialogs';
+
+const STAGE_VIEWS: Record<string, ComponentType<{ data: any }>> = {
+  comparison_validity: ComparisonValidityView,
+  offline_audit: OfflineAuditView,
+  population_validation: PopulationView,
+  distribution_shift: ShiftView,
+  conditional_performance: ConditionalHeatmapView,
+  paired_comparison: PairedTransitionView,
+  statistical_significance: SignificanceView,
+  feature_parity: FeatureParityView,
+  serving_parity: ServingParityView,
+  shadow_traffic: TrafficAuditView,
+  label_integrity: LabelIntegrityView,
+};
+
+// ----------------------------------------------------------- creation panel
+
+function CreatePanel({ onCreated }: { onCreated: (inv: Investigation) => void }) {
+  const [causes, setCauses] = useState<{ id: RootCause; label: string }[]>([]);
+  const [baseline, setBaseline] = useState('detr3d-a-v41');
+  const [candidate, setCandidate] = useState('detr3d-b-v42');
+  const [cause, setCause] = useState<string>('DEMO');
+  const [seed, setSeed] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [err, setErr] = useState('');
+
+  useEffect(() => {
+    api.getCauses().then((r) => setCauses(r.causes)).catch(() => undefined);
+  }, []);
+
+  const create = async () => {
+    setBusy(true);
+    setErr('');
+    try {
+      const inv = await api.createInvestigation({
+        baseline_model: baseline,
+        candidate_model: candidate,
+        cause: cause === 'DEMO' ? null : (cause as RootCause),
+        seed: seed ? Number(seed) : null,
+        training_mode: cause === 'DEMO',
+      });
+      onCreated(inv);
+    } catch (e) {
+      setErr(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <SectionCard
+      title="New investigation"
+      subtitle="Generates a full offline + shadow evaluation pair with a planted root cause. In demo mode the cause is hidden — work the methodology, then reveal the answer at the end."
+    >
+      <Box sx={{ display: 'flex', gap: 1.5, flexWrap: 'wrap', alignItems: 'center' }}>
+        <TextField label="Baseline model (A)" size="small" value={baseline} onChange={(e) => setBaseline(e.target.value)} sx={{ width: 180 }} />
+        <TextField label="Candidate model (B)" size="small" value={candidate} onChange={(e) => setCandidate(e.target.value)} sx={{ width: 180 }} />
+        <TextField select label="Scenario" size="small" value={cause} onChange={(e) => setCause(e.target.value)} sx={{ width: 320 }}>
+          <MenuItem value="DEMO">
+            <em>Demo investigation — hidden random root cause (training mode)</em>
+          </MenuItem>
+          {causes.map((c) => (
+            <MenuItem key={c.id} value={c.id}>{c.id} — {c.label}</MenuItem>
+          ))}
+        </TextField>
+        <TextField label="Seed (optional)" size="small" value={seed} onChange={(e) => setSeed(e.target.value.replace(/\D/g, ''))} sx={{ width: 130 }} />
+        <Button variant="contained" size="small" startIcon={busy ? <CircularProgress size={14} /> : <Plus size={15} />} disabled={busy} onClick={create}>
+          Create
+        </Button>
+      </Box>
+      {err ? <Alert severity="error" sx={{ mt: 1 }}>{err}</Alert> : null}
+    </SectionCard>
+  );
+}
+
+// -------------------------------------------------------- investigation list
+
+function InvestigationList({ onOpen }: { onOpen: (id: string) => void }) {
+  const [rows, setRows] = useState<InvestigationSummary[]>([]);
+  useEffect(() => {
+    api.listInvestigations().then((r) => setRows(r.investigations)).catch(() => undefined);
+  }, []);
+  return (
+    <SectionCard title="Investigations">
+      {rows.length === 0 ? (
+        <Typography variant="caption" sx={{ color: '#8a949e' }}>
+          None yet — create one above.
+        </Typography>
+      ) : (
+        <Box component="table" sx={tableSx}>
+          <thead>
+            <tr><th>Name</th><th>Models</th><th>Claims</th><th>Progress</th><th>Mode</th><th /></tr>
+          </thead>
+          <tbody>
+            {rows.map((r) => (
+              <tr key={r.id}>
+                <td style={{ fontWeight: 600 }}>{r.name}</td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11 }}>{r.candidate_model} vs {r.baseline_model}</td>
+                <td style={{ fontFamily: 'monospace', fontSize: 11 }}>
+                  <span style={{ color: '#a5d6a7' }}>+{r.claims.offline_delta_pp}pp off</span>{' / '}
+                  <span style={{ color: '#ef9a9a' }}>{r.claims.shadow_delta_pp}pp sh</span>
+                </td>
+                <td>{r.stages_complete}/{r.stages_total} stages</td>
+                <td>
+                  {r.training_mode ? (
+                    <Chip size="small" label={r.revealed ? `revealed: ${r.scenario_cause}` : 'training (hidden cause)'} sx={{ height: 18, fontSize: 10, bgcolor: '#232a31' }} />
+                  ) : (
+                    <Chip size="small" label={r.scenario_cause} sx={{ height: 18, fontSize: 10, bgcolor: '#232a31' }} />
+                  )}
+                </td>
+                <td><Button size="small" onClick={() => onOpen(r.id)}>Open</Button></td>
+              </tr>
+            ))}
+          </tbody>
+        </Box>
+      )}
+    </SectionCard>
+  );
+}
+
+// ----------------------------------------------------------- hypothesis banner
+
+function HypothesisBanner({ inv, workingSet }: { inv: Investigation; workingSet: RootCause[] }) {
+  return (
+    <Paper variant="outlined" sx={{ px: 1.5, py: 0.75, mb: 1.5, bgcolor: BG_PANEL, borderColor: BORDER, display: 'flex', alignItems: 'center', gap: 1.5, flexWrap: 'wrap' }}>
+      <Typography variant="caption" sx={{ fontWeight: 800, color: '#8a949e', letterSpacing: 0.6 }}>
+        CLAIMS
+      </Typography>
+      <Chip size="small" label={`offline +${inv.claims.offline_delta_pp}pp (n=${inv.claims.offline_n.toLocaleString()})`} sx={{ height: 20, fontSize: 11, bgcolor: '#66bb6a22', color: '#a5d6a7', fontFamily: 'monospace' }} />
+      <Chip size="small" label={`shadow ${inv.claims.shadow_delta_pp}pp (n=${inv.claims.shadow_scored_n.toLocaleString()})`} sx={{ height: 20, fontSize: 11, bgcolor: '#ef535022', color: '#ef9a9a', fontFamily: 'monospace' }} />
+      <Box sx={{ width: 1, height: 20, bgcolor: BORDER }} />
+      <Typography variant="caption" sx={{ fontWeight: 800, color: '#8a949e', letterSpacing: 0.6 }}>
+        WORKING HYPOTHESES ({workingSet.length})
+      </Typography>
+      {workingSet.map((h) => (
+        <Chip key={h} size="small" label={h} sx={{ height: 20, fontSize: 10, bgcolor: '#232a31', color: '#cfd8e0' }} />
+      ))}
+      <Typography variant="caption" sx={{ color: '#5c666f', ml: 'auto' }}>
+        narrowed by recorded evidence only — never a premature single conclusion
+      </Typography>
+    </Paper>
+  );
+}
+
+// -------------------------------------------------------- investigation view
+
+function InvestigationWorkspace({ invId, onBack }: { invId: string; onBack: () => void }) {
+  const [inv, setInv] = useState<Investigation | null>(null);
+  const [stageIdx, setStageIdx] = useState(0);
+  const [diag, setDiag] = useState<Record<string, DiagnosticsResponse>>({});
+  const [workingSet, setWorkingSet] = useState<RootCause[]>([]);
+  const [board, setBoard] = useState<Scoreboard | null>(null);
+  const [tree, setTree] = useState<DecisionTree | null>(null);
+  const [experiments, setExperiments] = useState<Experiments | null>(null);
+  const [report, setReport] = useState<RcaReport | null>(null);
+  const [reveal, setReveal] = useState<RevealResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState('');
+  const [findingOpen, setFindingOpen] = useState(false);
+  const [ackOpen, setAckOpen] = useState(false);
+
+  const stage = inv?.stages[stageIdx];
+  const stageKey = stage?.key ?? '';
+
+  const refreshWorkingSet = useCallback((id: string) => {
+    api.getScoreboard(id, true)
+      .then((b) => setWorkingSet(b.working_hypothesis_set))
+      .catch(() => undefined);
+  }, []);
+
+  const load = useCallback(async () => {
+    const got = await api.getInvestigation(invId);
+    setInv(got);
+    setStageIdx((cur) => Math.min(cur, firstIncompleteIndex(got.stages)));
+    refreshWorkingSet(invId);
+    return got;
+  }, [invId, refreshWorkingSet]);
+
+  useEffect(() => {
+    load().catch((e) => setError(String(e)));
+  }, [load]);
+
+  // Load whatever the selected stage needs.
+  useEffect(() => {
+    if (!inv || !stage) return;
+    setError('');
+    if (STAGE_VIEWS[stage.key] && !diag[stage.key]) {
+      setLoading(true);
+      api.getDiagnostics(inv.id, stage.key)
+        .then((d) => {
+          setDiag((m) => ({ ...m, [stage.key]: d }));
+          refreshWorkingSet(inv.id);
+        })
+        .catch((e) => setError(e instanceof Error ? e.message : String(e)))
+        .finally(() => setLoading(false));
+    }
+    if (stage.key === 'root_cause_scoring' && (!board || !tree)) {
+      setLoading(true);
+      Promise.all([api.getScoreboard(inv.id), api.getDecisionTree(inv.id)])
+        .then(([b, t]) => { setBoard(b); setTree(t); })
+        .catch((e) => setError(e instanceof Error ? e.message : String(e)))
+        .finally(() => setLoading(false));
+    }
+    if (stage.key === 'recommendations_report' && (!experiments || !report)) {
+      setLoading(true);
+      Promise.all([api.getExperiments(inv.id), api.getReport(inv.id)])
+        .then(([x, r]) => { setExperiments(x); setReport(r); })
+        .catch((e) => setError(e instanceof Error ? e.message : String(e)))
+        .finally(() => setLoading(false));
+    }
+  }, [inv, stage, diag, board, tree, experiments, report, refreshWorkingSet]);
+
+  const complete = async (ack = false, note = '') => {
+    if (!inv || !stage) return;
+    try {
+      const res = await api.completeStage(inv.id, stage.index, {
+        acknowledge_unknowns: ack,
+        note,
+      });
+      setInv(res.investigation);
+      setAckOpen(false);
+      if (stage.index + 1 < res.investigation.stages.length) setStageIdx(stage.index + 1);
+      refreshWorkingSet(inv.id);
+    } catch (e) {
+      const err = e as Error & { status?: number };
+      if (err.status === 409 && /UNKNOWN/i.test(err.message)) {
+        setAckOpen(true);
+      } else {
+        setError(err.message);
+      }
+    }
+  };
+
+  const submitFinding = async (f: { title: string; status: any; severity: any; detail: string }) => {
+    if (!inv || !stage) return;
+    await api.recordFinding(inv.id, { stage: stage.key, ...f });
+    setFindingOpen(false);
+    await load();
+    // Board scores include human findings — invalidate cached views.
+    setBoard(null);
+    setReport(null);
+  };
+
+  const assess = async (hypothesis: RootCause, confidence: Confidence, note: string) => {
+    if (!inv) return;
+    const b = await api.assessHypothesis(inv.id, { hypothesis, confidence, note });
+    setBoard(b);
+    setReport(null);
+  };
+
+  const doReveal = async () => {
+    if (!inv) return;
+    const r = await api.revealCause(inv.id);
+    setReveal(r);
+    await load();
+  };
+
+  const jumpToStage = useCallback((sk: string) => {
+    if (!inv) return;
+    const target = inv.stages.find((s) => s.key === sk);
+    if (target && target.index <= firstIncompleteIndex(inv.stages)) setStageIdx(target.index);
+  }, [inv]);
+
+  const stageFindings = useMemo(
+    () => (inv && stage ? inv.findings.filter((f) => f.stage === stage.key) : []),
+    [inv, stage]
+  );
+  const unknownTitles = stageFindings
+    .filter((f) => f.status === 'UNKNOWN' && f.severity === 'CRITICAL')
+    .map((f) => f.title);
+
+  if (!inv || !stage) {
+    return error ? <Alert severity="error">{error}</Alert> : <CircularProgress size={22} sx={{ m: 3 }} />;
+  }
+
+  const isDone = stage.status === 'complete' || stage.status === 'complete_with_unknowns';
+  const View = STAGE_VIEWS[stage.key];
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', height: '100%', minHeight: 0 }}>
+      <Box sx={{ display: 'flex', alignItems: 'center', gap: 1, mb: 1 }}>
+        <Button size="small" startIcon={<ArrowLeft size={14} />} onClick={onBack}>
+          All investigations
+        </Button>
+        <Typography variant="subtitle2" sx={{ fontWeight: 800 }}>{inv.name}</Typography>
+        <Typography variant="caption" sx={{ fontFamily: 'monospace', color: '#8a949e' }}>
+          {inv.candidate_model} vs {inv.baseline_model} · seed {inv.seed}
+        </Typography>
+        {inv.training_mode ? (
+          <Chip size="small" icon={<FlaskConical size={12} />} label="training mode" sx={{ height: 20, fontSize: 10, bgcolor: '#232a31' }} />
+        ) : null}
+      </Box>
+      <HypothesisBanner inv={inv} workingSet={workingSet} />
+      <Box sx={{ display: 'flex', flex: 1, minHeight: 0, border: `1px solid ${BORDER}`, borderRadius: 1, overflow: 'hidden' }}>
+        <StageRail stages={inv.stages} selected={stageIdx} onSelect={setStageIdx} />
+        <Box sx={{ flex: 1, minWidth: 0, overflowY: 'auto', p: 2 }}>
+          <Box sx={{ display: 'flex', alignItems: 'flex-start', gap: 1, mb: 0.75 }}>
+            <Box sx={{ flex: 1 }}>
+              <Typography variant="h6" sx={{ fontWeight: 800, fontSize: 16 }}>
+                Stage {stage.index}: {stage.title}
+              </Typography>
+            </Box>
+            {STAGE_VIEWS[stage.key] || stage.key === 'root_cause_scoring' ? (
+              <Button size="small" variant="outlined" startIcon={<StickyNote size={13} />} onClick={() => setFindingOpen(true)}>
+                Record finding
+              </Button>
+            ) : null}
+            {!isDone ? (
+              <Button size="small" variant="contained" startIcon={<CheckCheck size={14} />} onClick={() => complete()}>
+                Mark stage complete
+              </Button>
+            ) : (
+              <Chip size="small" label={stage.status === 'complete' ? 'complete' : 'complete with unknowns'} sx={{
+                height: 24, fontWeight: 700, fontSize: 11,
+                bgcolor: stage.status === 'complete' ? '#66bb6a22' : '#ffb74d22',
+                color: stage.status === 'complete' ? '#66bb6a' : '#ffb74d',
+              }} />
+            )}
+          </Box>
+          {stageFindings.length ? (
+            <Box sx={{ mb: 1 }}>
+              <FindingChips findings={stageFindings} />
+            </Box>
+          ) : null}
+          {error ? <Alert severity="error" sx={{ mb: 1 }}>{error}</Alert> : null}
+          {loading ? <CircularProgress size={20} sx={{ my: 2 }} /> : null}
+
+          {View && diag[stage.key] ? <View data={diag[stage.key].data} /> : null}
+
+          {stage.key === 'root_cause_scoring' && board && tree ? (
+            <>
+              <ScoreBoardView board={board} onJumpToStage={jumpToStage} onAssess={assess} />
+              <DecisionTreeView tree={tree} />
+            </>
+          ) : null}
+
+          {stage.key === 'recommendations_report' && experiments && report ? (
+            <>
+              <ExperimentsView exp={experiments} />
+              <ReportView report={report} inv={inv} reveal={reveal} onReveal={doReveal} />
+            </>
+          ) : null}
+
+          {stage.key === 'root_cause_scoring' && !board && !loading ? (
+            <Explainer text="Scoring runs once stages 0–10 are complete; every point on the board traces back to a recorded stage finding." />
+          ) : null}
+        </Box>
+      </Box>
+
+      <RecordFindingDialog
+        open={findingOpen}
+        stageTitle={stage.title}
+        onClose={() => setFindingOpen(false)}
+        onSubmit={submitFinding}
+      />
+      <AcknowledgeUnknownsDialog
+        open={ackOpen}
+        stageTitle={stage.title}
+        unknownTitles={unknownTitles}
+        onClose={() => setAckOpen(false)}
+        onAcknowledge={(note) => complete(true, note)}
+      />
+    </Box>
+  );
+}
+
+// -------------------------------------------------------------------- page
+
+export default function RootCauseLabPage() {
+  const [activeId, setActiveId] = useState<string | null>(null);
+  const [refreshKey, setRefreshKey] = useState(0);
+
+  if (activeId) {
+    return (
+      <Box sx={{ height: 'calc(100vh - 170px)', minHeight: 480 }}>
+        <InvestigationWorkspace invId={activeId} onBack={() => { setActiveId(null); setRefreshKey((k) => k + 1); }} />
+      </Box>
+    );
+  }
+  return (
+    <Box key={refreshKey}>
+      <Explainer text="Offline evaluation says the candidate is +5% better; shadow production says −2% worse. This lab refuses to assume either number is real: it walks a 13-stage skeptical methodology — comparison validity, offline audit, population, shift, conditional performance, paired transitions, significance, feature/serving parity, traffic, labels — before scoring 8 root-cause hypotheses against the evidence." />
+      <CreatePanel onCreated={(inv) => setActiveId(inv.id)} />
+      <InvestigationList onOpen={setActiveId} />
+    </Box>
+  );
+}

src/services/rca.ts

@@ -0,0 +1,126 @@
+/**
+ * Typed fetch wrappers for the Regression RCA workbench API (/api/rca).
+ * Mirrors the style of services/megaeval.ts.
+ */
+import type {
+  Confidence,
+  DecisionTree,
+  DiagnosticsResponse,
+  Experiments,
+  Finding,
+  FindingStatus,
+  Investigation,
+  InvestigationSummary,
+  RcaReport,
+  RevealResponse,
+  RootCause,
+  Scoreboard,
+  Severity,
+  StageMeta,
+  StageState,
+} from '../types/rca';
+
+async function handle<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    let detail = '';
+    try {
+      const body = await res.json();
+      detail = typeof body?.detail === 'string' ? body.detail : JSON.stringify(body);
+    } catch {
+      detail = await res.text().catch(() => '');
+    }
+    const err = new Error(detail || res.statusText) as Error & { status?: number };
+    err.status = res.status;
+    throw err;
+  }
+  return res.json() as Promise<T>;
+}
+
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+
+const get = <T,>(url: string): Promise<T> => fetch(url).then((r) => handle<T>(r));
+const post = <T,>(url: string, body?: unknown): Promise<T> =>
+  fetch(url, {
+    method: 'POST',
+    headers: JSON_HEADERS,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  }).then((r) => handle<T>(r));
+
+export const getCauses = () =>
+  get<{ causes: { id: RootCause; label: string }[] }>('/api/rca/causes');
+
+export const getStages = () => get<{ stages: StageMeta[] }>('/api/rca/stages');
+
+export const createInvestigation = (body: {
+  name?: string;
+  baseline_model?: string;
+  candidate_model?: string;
+  cause?: RootCause | null;
+  seed?: number | null;
+  training_mode?: boolean;
+}) => post<Investigation>('/api/rca/investigations', body);
+
+export const listInvestigations = () =>
+  get<{ investigations: InvestigationSummary[] }>('/api/rca/investigations');
+
+export const getInvestigation = (id: string) =>
+  get<Investigation>(`/api/rca/investigations/${encodeURIComponent(id)}`);
+
+export const completeStage = (id: string, index: number, body: {
+  acknowledge_unknowns?: boolean;
+  note?: string;
+}) =>
+  post<{ stage: StageState; investigation: Investigation }>(
+    `/api/rca/investigations/${encodeURIComponent(id)}/stages/${index}/complete`,
+    body
+  );
+
+export const reopenStage = (id: string, index: number) =>
+  post<{ stage: StageState; investigation: Investigation }>(
+    `/api/rca/investigations/${encodeURIComponent(id)}/stages/${index}/reopen`
+  );
+
+export const recordFinding = (id: string, body: {
+  stage: string;
+  title: string;
+  status: FindingStatus;
+  severity: Severity;
+  detail?: string;
+  code?: string;
+}) =>
+  post<{ finding: Finding }>(
+    `/api/rca/investigations/${encodeURIComponent(id)}/findings`,
+    body
+  );
+
+export const getDiagnostics = (id: string, stageKey: string) =>
+  get<DiagnosticsResponse>(
+    `/api/rca/investigations/${encodeURIComponent(id)}/diagnostics/${encodeURIComponent(stageKey)}`
+  );
+
+export const getScoreboard = (id: string, recordedOnly = false) =>
+  get<Scoreboard>(
+    `/api/rca/investigations/${encodeURIComponent(id)}/scoreboard${recordedOnly ? '?recorded_only=true' : ''}`
+  );
+
+export const assessHypothesis = (id: string, body: {
+  hypothesis: RootCause;
+  confidence: Confidence;
+  note?: string;
+}) =>
+  post<Scoreboard>(
+    `/api/rca/investigations/${encodeURIComponent(id)}/scoreboard/assess`,
+    body
+  );
+
+export const getDecisionTree = (id: string) =>
+  get<DecisionTree>(`/api/rca/investigations/${encodeURIComponent(id)}/decision-tree`);
+
+export const getExperiments = (id: string) =>
+  get<Experiments>(`/api/rca/investigations/${encodeURIComponent(id)}/experiments`);
+
+export const getReport = (id: string) =>
+  get<RcaReport>(`/api/rca/investigations/${encodeURIComponent(id)}/report`);
+
+export const revealCause = (id: string) =>
+  post<RevealResponse>(`/api/rca/investigations/${encodeURIComponent(id)}/reveal`);

src/types/rca.ts

@@ -0,0 +1,210 @@
+/** Types for the Regression RCA workbench (/api/rca). */
+
+export type RootCause =
+  | 'TRUE_MODEL_REGRESSION'
+  | 'DISTRIBUTION_SHIFT'
+  | 'FEATURE_SKEW'
+  | 'SERVING_MISMATCH'
+  | 'LABEL_LATENCY'
+  | 'SAMPLING_BIAS'
+  | 'STATISTICAL_NOISE'
+  | 'OFFLINE_CONTAMINATION';
+
+export type FindingStatus = 'PASS' | 'MISMATCH' | 'UNKNOWN';
+export type Severity = 'INFO' | 'WARN' | 'CRITICAL';
+export type StageStatus =
+  | 'pending'
+  | 'in_progress'
+  | 'complete'
+  | 'complete_with_unknowns';
+export type Confidence = 'HIGH' | 'MEDIUM' | 'LOW' | 'UNKNOWN';
+
+export interface StageMeta {
+  index: number;
+  key: string;
+  title: string;
+  question: string;
+}
+
+export interface StageState {
+  index: number;
+  key: string;
+  title: string;
+  status: StageStatus;
+  completed_at: number | null;
+  acknowledged_unknowns: boolean;
+  ack_note: string;
+  skip_acknowledged: boolean;
+}
+
+export interface Finding {
+  id: string;
+  stage: string;
+  code: string;
+  title: string;
+  status: FindingStatus;
+  severity: Severity;
+  detail: string;
+  source: 'auto' | 'human';
+  created_at: number;
+  data: Record<string, unknown>;
+}
+
+export interface InvestigationClaims {
+  metric: string;
+  offline_delta_pp: number;
+  shadow_delta_pp: number;
+  offline_n: number;
+  shadow_scored_n: number;
+}
+
+export interface Investigation {
+  id: string;
+  name: string;
+  baseline_model: string;
+  candidate_model: string;
+  seed: number;
+  training_mode: boolean;
+  revealed: boolean;
+  created_at: number;
+  claims: InvestigationClaims;
+  stages: StageState[];
+  findings: Finding[];
+  human_assessments: Record<string, { confidence: Confidence; note: string }>;
+  events: { ts: number; kind: string; message: string; data: Record<string, unknown> }[];
+  scenario_cause?: RootCause;
+}
+
+export interface InvestigationSummary {
+  id: string;
+  name: string;
+  baseline_model: string;
+  candidate_model: string;
+  training_mode: boolean;
+  revealed: boolean;
+  created_at: number;
+  claims: InvestigationClaims;
+  stages_complete: number;
+  stages_total: number;
+  scenario_cause?: RootCause;
+}
+
+export interface DiagnosticsResponse {
+  stage: string;
+  data: Record<string, any>;
+  findings: Finding[];
+}
+
+export interface EvidenceLink {
+  code: string;
+  stage: string;
+  title: string;
+  weight: number;
+  severity: Severity;
+  status: FindingStatus;
+  finding_id: string;
+}
+
+export interface ScoreboardRow {
+  hypothesis: RootCause;
+  label: string;
+  score: number;
+  rank: number;
+  evidence_for: EvidenceLink[];
+  evidence_against: EvidenceLink[];
+  auto_confidence: Confidence;
+  human_confidence: Confidence | null;
+  human_note: string;
+  next_discriminating_test: string;
+}
+
+export interface Scoreboard {
+  rows: ScoreboardRow[];
+  top_hypothesis: RootCause;
+  top_confidence: Confidence;
+  score_gap: number;
+  working_hypothesis_set: RootCause[];
+  explainer: string;
+}
+
+export interface DecisionNode {
+  id: string;
+  question: string;
+  answer: 'yes' | 'no' | 'unknown';
+  basis: string[];
+  conclusion_if_no: string | null;
+  next: string | null;
+}
+
+export interface DecisionTree {
+  nodes: DecisionNode[];
+  path: string[];
+  conclusion: string | null;
+  conclusion_kind: 'root_cause' | 'insufficient_evidence' | 'no_regression';
+  explainer: string;
+}
+
+export interface ExperimentDesign {
+  id: string;
+  design: string;
+  description: string;
+  discriminates: RootCause[];
+  cost: 'low' | 'medium' | 'high';
+  expected_days: number;
+  information_gain: number;
+  priority: number;
+  rank: number;
+}
+
+export interface Experiments {
+  experiments: ExperimentDesign[];
+  minimum_additional_evidence: string;
+  power: { effective_n: number; needed_effective_n: number; practical_margin_pp: number };
+  explainer: string;
+}
+
+export interface RcaReport {
+  investigation_id: string;
+  name: string;
+  generated_at: number;
+  models: { baseline: string; candidate: string };
+  claims: InvestigationClaims;
+  executive_finding: {
+    conclusion: string | null;
+    conclusion_kind: string;
+    top_hypothesis: RootCause;
+    label: string;
+    confidence: Confidence;
+    score: number;
+    score_gap_to_runner_up: number;
+  };
+  stage_summaries: {
+    stage: string;
+    headline: string;
+    mismatches: string[];
+    unknowns: string[];
+    n_pass: number;
+    verdict: 'mismatch' | 'unknown' | 'clean';
+  }[];
+  hypothesis_ranking: {
+    rank: number;
+    hypothesis: RootCause;
+    score: number;
+    confidence: Confidence;
+    human_confidence: Confidence | null;
+    evidence_for: number;
+    evidence_against: number;
+  }[];
+  decision_path: string[];
+  minimum_additional_evidence: string;
+  recommended_experiments: ExperimentDesign[];
+  remediation: { containment: string[]; short_term: string[]; long_term: string[] };
+  acknowledged_unknowns: { ts: number; kind: string; message: string; data: Record<string, unknown> }[];
+  human_findings: Finding[];
+  markdown: string;
+}
+
+export interface RevealResponse {
+  cause: RootCause;
+  explanation: string;
+}