Deploy Sensorflow Studio

.gitignore

@@ -64,6 +64,7 @@ temp/
 
 # Generated runtime/test artifacts
 runs/labeleval/
+runs/megaeval/
 runs/pipeline/frame_test/
 runs/pipeline/qg_test/
 runs/pipeline/roundtrip/

ARCHITECTURE.md

@@ -0,0 +1,78 @@
+# Sensorflow Studio — Aggregate-First Evaluation Architecture (megaeval)
+
+The `sensorflow/megaeval/` layer replaces the "evaluation-record browser" model
+(annotation as the primary unit) with an **aggregate-first, risk-first,
+cohort-first, drill-down-on-demand** design.
+
+## Mental model → code
+
+| Concept | Meaning | Module / storage |
+| --- | --- | --- |
+| Dataset | immutable source population | `population.py` → `runs/megaeval/populations/{pop}/part-*.npz` |
+| Evaluation Run | model+config being evaluated (async job, first-class) | `runs.py` → `runs/megaeval/runs/{run}/run.json` |
+| Population | all objects evaluated in a run | headline row of the metric cube |
+| Cohort | slice by class/weather/lighting/road/scenario/sensor/distance/speed/occlusion | cube cells + `POST /api/evaluations/query` |
+| Container | scene/frame/segment holding related objects | `containers.npz` aggregate table |
+| Annotation | individual object — forensic view only | per-object `objects-part-*.npz`, loaded one partition at a time |
+
+## Data flow
+
+```
+generate population (vectorized numpy, partitioned npz)
+        │
+create run (queued) ──► worker pool (4 threads) processes partitions:
+        │                 model simulation → PARTIAL sufficient statistics
+        │                 (n, tp, fp, fn, sum_iou, conf sums, histograms …)
+        │                 grouped by the 9 cube dimensions, per partition
+        ▼
+reduce (concat + groupby-sum) ──► materialize METRIC CUBE (cube.npz)
+        │                          + error index, container table, sketches,
+        │                          container embeddings
+        ▼
+publish ──► queries served by QueryRouter: cache → cube → (rare) record scan
+```
+
+Aggregation **never** scans raw records at query time; queries like
+"pedestrian recall at night in rain for model v42" are cube lookups.
+
+## Single-node stand-ins for distributed infrastructure
+
+This repo runs on one laptop; the seams are shaped so each piece maps to the
+production-scale equivalent:
+
+| Here (single node) | Production analogue |
+| --- | --- |
+| npz column partitions (`part-0000.npz…`, hash-partitioned by container) | Parquet files in an Iceberg/Delta table, partitioned by scene |
+| `ThreadPoolExecutor` workers over partitions | Spark executors / Flink task slots |
+| partial stats per partition + `reduce_partials` | map-side combine + shuffle reduce |
+| `QueryRouter` (cache → cube → scan) with latency+source reporting | OLAP engine (Druid/Pinot/ClickHouse) over the lakehouse |
+| `QueryCache` keyed by hash(dataset+model+filters+group_by+metrics) | result cache / materialized views |
+| in-process SSE progress events | job-status topic (Kafka) + progress service |
+| numpy cosine similarity over container embeddings | vector DB (hybrid retrieval) |
+
+## Honesty rules encoded in the API
+
+- Cube counts and derived ratios are **exact** (`meta.exact = true`).
+- Percentiles/distributions come from fixed-bin quantile histograms;
+  cardinalities from HyperLogLog — always labeled approximate.
+- Precision/recall from human review are **sampling estimates with 95% CIs**
+  (stratified risk-weighted design: Wilson per stratum, weighted normal-approx
+  combination), reported with n reviewed / frame size / method.
+- Every query response reports `source` (cache/cube/scan), `cache_hit`,
+  and `latency_ms` so aggregate-first behavior is observable in the UI.
+- Evaluation runs are reproducible: lineage (dataset, model+checkpoint, label
+  version, evaluator code version, metric version, thresholds, sampling config,
+  seed, hardware) is stored on the run and derives the deterministic seed.
+
+## Performance SLOs (measured locally, 320k-object population, 67k cube cells)
+
+| Query | SLO | Measured |
+| --- | --- | --- |
+| aggregate dashboard (group by class) | < 2 s | ~75 ms |
+| filtered cohort query | < 3 s | ~350 ms first / sub-ms cached |
+| cached query | < 100 ms | ~0.1 ms |
+| object investigation (one container, forensic) | < 1 s | ~50–200 ms |
+
+The legacy `sensorflow/evaluation/` layer (label-evaluation pipeline, triage,
+HITL, training flywheel) remains unchanged; megaeval integrates with its
+regression tracker and alerting rather than duplicating them.

app_backend.py

@@ -1463,6 +1463,10 @@ def get_mitl_queue(sequence_id: str = "seq_001"):
 from sensorflow.evaluation.api import router as labeleval_router
 app.include_router(labeleval_router)
 
+# Aggregate-first mega-scale evaluation layer (metric cube, async runs, query API).
+from sensorflow.megaeval.api import router as megaeval_router
+app.include_router(megaeval_router)
+
 # Mount static folder
 static_dir = Path(__file__).parent / "static"
 if static_dir.exists():

sensorflow/evaluation/api.py

@@ -564,6 +564,18 @@ def copilot_explain_evidence(req: CopilotRequest):
 # ------------------------------------------------------------------ SSE stream
 
 
+def _megaeval_status() -> Dict:
+    try:
+        from sensorflow.megaeval.runs import get_mega_store
+        mstore = get_mega_store()
+        active = [r.progress_dict() for r in mstore.runs.values()
+                  if r.status in ("queued", "running", "reducing", "materializing")]
+        return {"active_runs": active, "cache": mstore.router.cache.stats(),
+                "total_runs": len(mstore.runs)}
+    except Exception:
+        return {"active_runs": [], "cache": None, "total_runs": 0}
+
+
 @router.get("/events/stream")
 async def events_stream(ticks: int = 600):
     async def gen():
@@ -573,6 +585,7 @@ async def events_stream(ticks: int = 600):
                 "pipeline": _pipeline_state(),
                 "training": _active_training_job(),
                 "alerts_count": len(get_store().all("alerts")),
+                "megaeval": _megaeval_status(),
             }
             yield f"data: {json.dumps(payload)}\n\n"
             await asyncio.sleep(1.0)

sensorflow/megaeval/__init__.py

@@ -0,0 +1,16 @@
+"""megaeval — aggregate-first, risk-first evaluation layer for mega-scale populations.
+
+Mental model (maps 1:1 to modules):
+
+    Dataset (immutable population)   -> population.py   (partitioned npz storage)
+    Evaluation Run (first-class job) -> runs.py         (async workers -> partial stats -> reduce)
+    Population / Cohort              -> cube.py         (metric cube + query router + cache)
+    Container                        -> runs.py         (container-level aggregate table)
+    Annotation (forensic drill-down) -> runs.py         (per-object partitions, loaded on demand)
+
+Single-node stand-ins for distributed infra (see ARCHITECTURE.md):
+    npz partitions      ~ Parquet files in an Iceberg table
+    worker thread pool  ~ Spark executors / Flink task slots
+    partial-stats+reduce~ map-side combine + shuffle reduce
+    QueryRouter         ~ OLAP engine (Druid/Pinot) in front of the lakehouse
+"""

sensorflow/megaeval/analysis.py

@@ -0,0 +1,314 @@
+"""Cross-run analysis: model-vs-model comparison, distribution shift, the "why"
+layer, and hybrid similarity search.
+
+All computations run on cubes and the error index — never on raw records.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.megaeval import cube as cube_mod
+from sensorflow.megaeval import population as pop_mod
+from sensorflow.megaeval.population import DIMENSIONS, DIM_NAMES
+from sensorflow.megaeval.runs import ERROR_TYPES, EvaluationRun, MegaStore, run_dir
+
+# ------------------------------------------------------------------ model vs model
+
+DEFAULT_PROMOTION_POLICY = {
+    "max_recall_drop": 0.010,
+    "max_precision_drop": 0.015,
+    "max_safety_recall_drop": 0.005,
+    "max_cohort_recall_drop": 0.050,
+    "min_cohort_support": 200,
+    "cohort_dims": ["road_type", "lighting", "class"],
+}
+
+_HEADLINE_METRICS = ["precision", "recall", "f1", "mean_iou", "safety_recall", "anomaly_rate"]
+
+
+def compare_runs(store: MegaStore, candidate: EvaluationRun, baseline: EvaluationRun,
+                 policy: Optional[Dict] = None) -> Dict:
+    policy = {**DEFAULT_PROMOTION_POLICY, **(policy or {})}
+    cand_art, base_art = store.artifacts(candidate.run_id), store.artifacts(baseline.run_id)
+    cand_cube, base_cube = cand_art["cube"], base_art["cube"]
+
+    headline = []
+    for m in _HEADLINE_METRICS:
+        c, b = candidate.headline.get(m), baseline.headline.get(m)
+        if c is None or b is None:
+            continue
+        headline.append({"metric": m, "baseline": round(b, 4), "candidate": round(c, 4),
+                         "delta": round(c - b, 4)})
+
+    per_class = []
+    for cls in DIMENSIONS["class"]:
+        c, b = candidate.per_class.get(cls), baseline.per_class.get(cls)
+        if not c or not b:
+            continue
+        per_class.append({
+            "class": cls, "n": c.get("n"),
+            "recall_baseline": b.get("recall"), "recall_candidate": c.get("recall"),
+            "recall_delta": round((c.get("recall") or 0) - (b.get("recall") or 0), 4),
+            "precision_baseline": b.get("precision"), "precision_candidate": c.get("precision"),
+            "precision_delta": round((c.get("precision") or 0) - (b.get("precision") or 0), 4),
+        })
+
+    dims = policy["cohort_dims"]
+    cand_rows, _ = cube_mod.aggregate(cand_cube, None, dims, ["n", "recall", "precision"], 2000)
+    base_rows, _ = cube_mod.aggregate(base_cube, None, dims, ["n", "recall", "precision"], 2000)
+    base_map = {tuple(r[d] for d in dims): r for r in base_rows}
+    cohorts = []
+    for r in cand_rows:
+        key = tuple(r[d] for d in dims)
+        b = base_map.get(key)
+        if not b or r["n"] < policy["min_cohort_support"]:
+            continue
+        if r.get("recall") is None or b.get("recall") is None:
+            continue
+        cohorts.append({
+            "cohort": "/".join(key), **{d: r[d] for d in dims}, "n": r["n"],
+            "recall_baseline": b["recall"], "recall_candidate": r["recall"],
+            "recall_delta": round(r["recall"] - b["recall"], 4),
+        })
+    cohorts.sort(key=lambda x: x["recall_delta"])
+    regressions = [c for c in cohorts if c["recall_delta"] < -policy["max_cohort_recall_drop"]]
+
+    blockers: List[str] = []
+    hd = {h["metric"]: h["delta"] for h in headline}
+    if hd.get("recall", 0) < -policy["max_recall_drop"]:
+        blockers.append(f"headline recall dropped {hd['recall']:+.4f} "
+                        f"(policy allows -{policy['max_recall_drop']})")
+    if hd.get("precision", 0) < -policy["max_precision_drop"]:
+        blockers.append(f"headline precision dropped {hd['precision']:+.4f}")
+    if hd.get("safety_recall", 0) < -policy["max_safety_recall_drop"]:
+        blockers.append(f"safety recall dropped {hd['safety_recall']:+.4f} "
+                        f"(policy allows -{policy['max_safety_recall_drop']})")
+    for c in regressions[:5]:
+        blockers.append(
+            f"REGRESSION: {c['cohort']} recall "
+            f"{c['recall_baseline']*100:.1f}% -> {c['recall_candidate']*100:.1f}% "
+            f"(Δ {c['recall_delta']*100:+.1f})")
+
+    # integrate with the existing regression tracker so the Regression page shows it
+    try:
+        from sensorflow.evaluation import regression as legacy_regression
+        from sensorflow.evaluation.records import get_store as get_legacy_store
+        legacy_regression.compare_runs(
+            get_legacy_store(),
+            current_metrics={"precision": candidate.headline.get("precision"),
+                             "recall": candidate.headline.get("recall"),
+                             "safety_critical_recall": candidate.headline.get("safety_recall"),
+                             "mean_iou_3d": candidate.headline.get("mean_iou")},
+            model_version=candidate.model_version,
+            dataset_version=candidate.population_id,
+            run_id=candidate.run_id,
+            baseline_metrics={"precision": baseline.headline.get("precision"),
+                              "recall": baseline.headline.get("recall"),
+                              "safety_critical_recall": baseline.headline.get("safety_recall"),
+                              "mean_iou_3d": baseline.headline.get("mean_iou")},
+            baseline_version=baseline.model_version,
+            affected_classes=[c["class"] for c in per_class if c["recall_delta"] < -0.03],
+            affected_scenarios=sorted({c.get("road_type", "") for c in regressions[:5] if c}),
+        )
+    except Exception:
+        pass
+
+    return {
+        "candidate": {"run_id": candidate.run_id, "model_version": candidate.model_version},
+        "baseline": {"run_id": baseline.run_id, "model_version": baseline.model_version},
+        "headline_deltas": headline,
+        "per_class": per_class,
+        "worst_cohorts": cohorts[:15],
+        "regressions": regressions[:10],
+        "policy": policy,
+        "recommendation": "DO_NOT_PROMOTE" if blockers else "PROMOTE",
+        "blockers": blockers,
+    }
+
+
+# ------------------------------------------------------------------ distribution shift
+
+
+def distribution_shift(store: MegaStore, run: EvaluationRun,
+                       min_eval_count: int = 300, rel_threshold: float = 0.35) -> Dict:
+    cache_path = os.path.join(run_dir(run.run_id), "shift.json")
+    if os.path.exists(cache_path):
+        with open(cache_path) as f:
+            return json.load(f)
+
+    meta = pop_mod.load_meta(run.population_id)
+    cube_df = store.artifacts(run.run_id)["cube"]
+    overall_rows, _ = cube_mod.aggregate(cube_df, None, None, ["recall"], 1)
+    overall_recall = overall_rows[0].get("recall")
+
+    shifts = []
+    for row in meta.get("train_mix", []):
+        train, evals = row["train_share"], row["eval_share"]
+        if train <= 0 or row["eval_count"] < min_eval_count:
+            continue
+        rel = (evals - train) / train
+        if abs(rel) < rel_threshold:
+            continue
+        filt = {"class": [row["class"]], "weather": [row["weather"]],
+                "lighting": [row["lighting"]]}
+        crows, _ = cube_mod.aggregate(cube_df, filt, None, ["n", "recall", "precision"], 1)
+        c = crows[0] if crows else {}
+        shifts.append({
+            "cohort": f"{row['class']}/{row['weather']}/{row['lighting']}",
+            "class": row["class"], "weather": row["weather"], "lighting": row["lighting"],
+            "train_share": round(train, 5), "eval_share": round(evals, 5),
+            "relative_change": round(rel, 4),
+            "eval_count": row["eval_count"],
+            "cohort_recall": c.get("recall"),
+            "overall_recall": overall_recall,
+            "recall_gap": (round(c["recall"] - overall_recall, 4)
+                           if c.get("recall") is not None and overall_recall is not None else None),
+        })
+    shifts.sort(key=lambda s: abs(s["relative_change"]) * (1 + abs(s.get("recall_gap") or 0) * 5),
+                reverse=True)
+
+    # surface the worst shifts as alerts in the existing alerting system (once per run)
+    try:
+        from sensorflow.evaluation.records import Alert, get_store as get_legacy_store, new_id
+        legacy = get_legacy_store()
+        for s in shifts[:3]:
+            if s.get("recall_gap") is not None and s["recall_gap"] < -0.03:
+                legacy.put("alerts", Alert(
+                    alert_id=new_id("alert"), kind="distribution_shift",
+                    severity="critical" if s["recall_gap"] < -0.08 else "warning",
+                    message=(f"Distribution shift {s['cohort']}: train {s['train_share']*100:.1f}% "
+                             f"-> eval {s['eval_share']*100:.1f}% "
+                             f"(rel {s['relative_change']*100:+.0f}%), cohort recall "
+                             f"{(s['cohort_recall'] or 0)*100:.1f}% vs overall "
+                             f"{(s['overall_recall'] or 0)*100:.1f}%"),
+                    evidence_page="command", evidence_id=run.run_id))
+        legacy.save()
+    except Exception:
+        pass
+
+    result = {"run_id": run.run_id, "shifts": shifts[:20],
+              "method": "train mix vs eval mix over (class, weather, lighting); "
+                        "relative share change with cube recall impact",
+              "thresholds": {"min_eval_count": min_eval_count, "rel_threshold": rel_threshold}}
+    with open(cache_path, "w") as f:
+        json.dump(result, f)
+    return result
+
+
+# ------------------------------------------------------------------ the "why" layer
+
+
+_FACTOR_ORDER = ["occlusion", "low_illumination", "long_range", "sensor_disagreement", "other"]
+
+
+def why(store: MegaStore, run: EvaluationRun, filters: Optional[Dict] = None,
+        metric: str = "recall") -> Dict:
+    """Decompose the failure population of a filtered slice by primary factor."""
+    art = store.artifacts(run.run_id)
+    errors = art.get("errors")
+    cube_df = art["cube"]
+    if errors is None or not len(errors):
+        return {"factors": [], "top_cohorts": [], "failure_count": 0}
+
+    mask = np.ones(len(errors), dtype=bool)
+    fail_types = [ERROR_TYPES.index(t) for t in ("FN", "FP", "LOCALIZATION")]
+    if metric == "recall":
+        fail_types = [ERROR_TYPES.index("FN"), ERROR_TYPES.index("LOCALIZATION")]
+    elif metric == "precision":
+        fail_types = [ERROR_TYPES.index("FP"), ERROR_TYPES.index("LOCALIZATION")]
+    mask &= errors["error_type"].isin(fail_types).to_numpy()
+    for dim, values in (filters or {}).items():
+        if dim not in DIM_NAMES:
+            continue
+        vocab = DIMENSIONS[dim]
+        codes = [vocab.index(v) for v in (values if isinstance(values, list) else [values])
+                 if v in vocab]
+        mask &= errors[dim].isin(codes).to_numpy()
+    sub = errors[mask]
+    total = len(sub)
+    if total == 0:
+        return {"factors": [], "top_cohorts": [], "failure_count": 0}
+
+    occl = sub["occlusion"].to_numpy() >= 1
+    night = sub["lighting"].to_numpy() == 1
+    far = sub["distance_band"].to_numpy() >= 2
+    sensor = sub["sensor_disagree"].to_numpy().astype(bool)
+    factor = np.full(total, 4, dtype=np.int8)  # other
+    factor[sensor] = 3
+    factor[far] = 2
+    factor[night] = 1
+    factor[occl] = 0  # priority: occlusion > low light > range > sensor > other
+    counts = np.bincount(factor, minlength=5)
+    factors = [{"factor": _FACTOR_ORDER[i], "count": int(counts[i]),
+                "share": round(float(counts[i]) / total, 4)}
+               for i in range(5) if counts[i] > 0]
+    factors.sort(key=lambda x: -x["count"])
+
+    rows, _ = cube_mod.aggregate(cube_df, filters, ["class", "lighting", "weather"],
+                                 ["n", metric, "fn", "fp"], 2000)
+    rows = [r for r in rows if r["n"] >= 150 and r.get(metric) is not None]
+    rows.sort(key=lambda r: r[metric])
+    top = [{"cohort": f"{r['class']}/{r['lighting']}/{r['weather']}",
+            "n": r["n"], metric: r[metric], "fn": r.get("fn"), "fp": r.get("fp")}
+           for r in rows[:8]]
+
+    return {"metric": metric, "filters": filters or {}, "failure_count": int(total),
+            "factors": factors, "top_cohorts": top,
+            "method": "primary-factor attribution over the error index "
+                      "(priority: occlusion > low illumination > long range > "
+                      "sensor disagreement > other)"}
+
+
+# ------------------------------------------------------------------ hybrid similarity
+
+
+def similar_containers(store: MegaStore, run: EvaluationRun, container_id: int,
+                       filters: Optional[Dict] = None, k: int = 12) -> Dict:
+    art = store.artifacts(run.run_id)
+    ids, emb = art["emb_ids"], art["emb"]
+    containers = art["containers"].set_index("container_id")
+    pos = np.where(ids == container_id)[0]
+    if pos.size == 0:
+        raise KeyError(f"Unknown container {container_id}")
+    q = emb[pos[0]]
+    sims = emb @ q
+
+    mask = np.ones(ids.shape[0], dtype=bool)
+    for dim, values in (filters or {}).items():
+        if dim not in pop_mod.CONTAINER_DIMS:
+            continue
+        vocab = DIMENSIONS[dim]
+        codes = [vocab.index(v) for v in (values if isinstance(values, list) else [values])
+                 if v in vocab]
+        col = containers.loc[ids, dim].to_numpy()
+        mask &= np.isin(col, codes)
+    mask[pos[0]] = False
+    sims = np.where(mask, sims, -np.inf)
+
+    kk = min(k, int(mask.sum()))
+    if kk <= 0:
+        return {"query_container": container_id, "results": []}
+    top = np.argpartition(-sims, kk - 1)[:kk]
+    top = top[np.argsort(-sims[top])]
+    results = []
+    for i in top.tolist():
+        cid = int(ids[i])
+        row = containers.loc[cid]
+        results.append({
+            "container_id": cid,
+            "similarity": round(float(sims[i]), 4),
+            **{dim: DIMENSIONS[dim][int(row[dim])] for dim in pop_mod.CONTAINER_DIMS},
+            "n_objects": int(row["n_objects"]),
+            "fn": int(row["fn"]), "fp": int(row["fp"]),
+            "anomalies": int(row["anomalies"]),
+            "risk_score": round(float(row["risk_score"]), 4),
+        })
+    return {"query_container": container_id,
+            "retrieval": "cosine over 32-d structural embeddings + structured filters",
+            "results": results}

sensorflow/megaeval/api.py

@@ -0,0 +1,387 @@
+"""FastAPI router for the aggregate-first mega-scale evaluation layer."""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel, Field
+
+from sensorflow.megaeval import analysis, errors as errors_mod, population as pop_mod
+from sensorflow.megaeval import sampling
+from sensorflow.megaeval.cube import SKETCH_METRICS
+from sensorflow.megaeval.population import DIMENSIONS
+from sensorflow.megaeval.runs import CONTAINER_STATUS, EvaluationRun, get_mega_store
+
+router = APIRouter(prefix="/api")
+
+
+def _run_or_404(run_id: str) -> EvaluationRun:
+    run = get_mega_store().runs.get(run_id)
+    if run is None:
+        raise HTTPException(404, f"Unknown evaluation run {run_id}")
+    return run
+
+
+def _published_or_409(run_id: str) -> EvaluationRun:
+    run = _run_or_404(run_id)
+    if run.status != "published":
+        raise HTTPException(409, f"Run {run_id} is {run.status}; results are available "
+                                 "once it is published")
+    return run
+
+
+# ------------------------------------------------------------------ requests
+
+
+class GeneratePopulationRequest(BaseModel):
+    name: str = "mega-perception"
+    num_objects: int = Field(320_000, ge=1_000, le=1_200_000)
+    seed: int = 42
+
+
+class CreateRunRequest(BaseModel):
+    population_id: str
+    model_version: str = "model-v42"
+    overrides: Dict = Field(default_factory=dict)
+    worker_delay_s: float = Field(0.5, ge=0.0, le=5.0)
+    workers: int = Field(4, ge=1, le=8)
+    seed: Optional[int] = None
+    label_version: str = "labels-v1"
+
+
+class EvaluationQueryRequest(BaseModel):
+    evaluation_id: str
+    filters: Dict[str, List[str]] = Field(default_factory=dict)
+    metrics: List[str] = Field(default_factory=list)
+    group_by: List[str] = Field(default_factory=list)
+    limit: int = Field(200, ge=1, le=2000)
+
+
+class ErrorSearchRequest(BaseModel):
+    run_id: str
+    error_types: List[str] = Field(default_factory=list)
+    filters: Dict[str, List[str]] = Field(default_factory=dict)
+    confidence_max: Optional[float] = None
+    confidence_min: Optional[float] = None
+    risk_min: Optional[float] = None
+    severity_min: Optional[float] = None
+    safety_only: bool = False
+    limit_containers: int = Field(25, ge=1, le=100)
+
+
+class CompareRequest(BaseModel):
+    candidate_run_id: str
+    baseline_run_id: str
+    policy: Dict = Field(default_factory=dict)
+
+
+class WhyRequest(BaseModel):
+    run_id: str
+    filters: Dict[str, List[str]] = Field(default_factory=dict)
+    metric: str = "recall"
+
+
+class SimilarityRequest(BaseModel):
+    run_id: str
+    container_id: int
+    filters: Dict[str, List[str]] = Field(default_factory=dict)
+    k: int = Field(12, ge=1, le=50)
+
+
+class ReviewPlanRequest(BaseModel):
+    target_n: Optional[int] = Field(None, ge=100, le=20_000)
+
+
+# ------------------------------------------------------------------ populations
+
+
+@router.post("/megaeval/population/generate")
+def generate_population(req: GeneratePopulationRequest):
+    meta = pop_mod.generate_population(name=req.name, num_objects=req.num_objects,
+                                       seed=req.seed)
+    return meta
+
+
+@router.get("/megaeval/populations")
+def list_populations():
+    return {"populations": pop_mod.list_populations()}
+
+
+@router.get("/megaeval/dimensions")
+def dimensions():
+    return {"dimensions": DIMENSIONS}
+
+
+# ------------------------------------------------------------------ runs (async jobs)
+
+
+@router.post("/megaeval/runs")
+def create_run(req: CreateRunRequest):
+    store = get_mega_store()
+    try:
+        run = store.create_run(population_id=req.population_id,
+                               model_version=req.model_version,
+                               overrides=req.overrides,
+                               seed=req.seed,
+                               worker_delay_s=req.worker_delay_s,
+                               workers=req.workers,
+                               label_version=req.label_version)
+    except KeyError as e:
+        raise HTTPException(404, str(e))
+    store.start_async(run)
+    return run.to_dict()
+
+
+@router.get("/megaeval/runs")
+def list_runs():
+    store = get_mega_store()
+    runs = sorted(store.runs.values(), key=lambda r: r.created_at, reverse=True)
+    return {"runs": [r.to_dict() for r in runs]}
+
+
+@router.get("/megaeval/runs/{run_id}")
+def get_run(run_id: str):
+    return _run_or_404(run_id).to_dict()
+
+
+@router.get("/megaeval/status")
+def megaeval_status():
+    store = get_mega_store()
+    active = [r.progress_dict() for r in store.runs.values()
+              if r.status in ("queued", "running", "reducing", "materializing")]
+    return {"active_runs": active, "cache": store.router.cache.stats(),
+            "total_runs": len(store.runs)}
+
+
+# ------------------------------------------------------------------ THE query API
+
+
+@router.post("/evaluations/query")
+def evaluations_query(req: EvaluationQueryRequest):
+    """Aggregate-first query endpoint. Routed: cache -> cube -> record scan."""
+    store = get_mega_store()
+    run = _published_or_409(req.evaluation_id)
+    art = store.artifacts(run.run_id)
+
+    def scan_fn(filters, group_by, metrics, limit):
+        return store.scan_records(run, filters, group_by, metrics, limit)
+
+    return store.router.query(run, art["cube"], art.get("sketches", {}),
+                              req.filters, req.metrics, req.group_by,
+                              req.limit, scan_fn=scan_fn)
+
+
+@router.get("/megaeval/cache")
+def cache_stats():
+    return get_mega_store().router.cache.stats()
+
+
+# ------------------------------------------------------------------ quality funnel
+
+
+@router.get("/megaeval/runs/{run_id}/funnel")
+def quality_funnel(run_id: str):
+    store = get_mega_store()
+    run = _published_or_409(run_id)
+    art = store.artifacts(run_id)
+    errs = art.get("errors")
+    review = art.get("review") or {}
+    n_err = int(len(errs)) if errs is not None else 0
+    n_high = int((errs["risk_score"] >= 0.6).sum()) if errs is not None and len(errs) else 0
+    results = (review.get("results") or {})
+    prec = results.get("precision") or {}
+    stages = [
+        {"stage": "Objects Evaluated", "count": int(run.objects_total)},
+        {"stage": "Containers", "count": int(run.headline.get("containers", 0))},
+        {"stage": "Potential Errors", "count": n_err},
+        {"stage": "High-Confidence Errors", "count": n_high},
+        {"stage": "Review Sample", "count": int((review.get("funnel") or {}).get("statistically_selected", 0))},
+        {"stage": "Human Verified", "count": int((review.get("funnel") or {}).get("reviewed", 0))},
+    ]
+    base = stages[0]["count"] or 1
+    for s in stages:
+        s["pct_of_population"] = round(s["count"] / base * 100, 3)
+    return {"stages": stages,
+            "estimated_precision": ({"estimate": prec.get("estimate"),
+                                     "ci_low": prec.get("ci_low"),
+                                     "ci_high": prec.get("ci_high"),
+                                     "n_reviewed": prec.get("n_reviewed")}
+                                    if prec else None)}
+
+
+# ------------------------------------------------------------------ containers
+
+
+_SORT_PRESETS = {
+    "worst_recall": ("recall", True),
+    "worst_precision": ("precision", True),
+    "worst_iou": ("mean_iou", True),
+    "most_anomalies": ("anomalies", False),
+    "least_verified": ("reviewed", True),
+    "highest_risk": ("risk_score", False),
+}
+
+
+@router.get("/megaeval/runs/{run_id}/containers")
+def containers(run_id: str, sort: str = "highest_risk", limit: int = 50, offset: int = 0):
+    store = get_mega_store()
+    _published_or_409(run_id)
+    art = store.artifacts(run_id)
+    df = art["containers"].copy()
+    tp, fp, fn = df["tp"], df["fp"], df["fn"]
+    with np.errstate(divide="ignore", invalid="ignore"):
+        df["recall"] = np.where((tp + fn) > 0, tp / (tp + fn), np.nan)
+        df["precision"] = np.where((tp + fp) > 0, tp / (tp + fp), np.nan)
+        df["mean_iou"] = np.where(tp > 0, df["sum_iou"] / tp, np.nan)
+    metric, ascending = _SORT_PRESETS.get(sort, _SORT_PRESETS["highest_risk"])
+    df = df.sort_values(metric, ascending=ascending, na_position="last")
+    total = len(df)
+    page = df.iloc[offset:offset + max(1, min(limit, 500))]
+    rows = []
+    for _, r in page.iterrows():
+        rows.append({
+            "container_id": int(r["container_id"]),
+            **{dim: DIMENSIONS[dim][int(r[dim])] for dim in pop_mod.CONTAINER_DIMS},
+            "n_objects": int(r["n_objects"]),
+            "tp": int(r["tp"]), "fp": int(r["fp"]), "fn": int(r["fn"]),
+            "anomalies": int(r["anomalies"]),
+            "reviewed": int(r["reviewed"]), "verified": int(r["verified"]),
+            "recall": None if np.isnan(r["recall"]) else round(float(r["recall"]), 4),
+            "precision": None if np.isnan(r["precision"]) else round(float(r["precision"]), 4),
+            "mean_iou": None if np.isnan(r["mean_iou"]) else round(float(r["mean_iou"]), 4),
+            "risk_score": round(float(r["risk_score"]), 4),
+            "status": CONTAINER_STATUS[int(r["status"])],
+        })
+    return {"total": total, "sort": sort, "rows": rows}
+
+
+@router.get("/megaeval/runs/{run_id}/containers/{container_id}/objects")
+def container_objects(run_id: str, container_id: int):
+    store = get_mega_store()
+    run = _published_or_409(run_id)
+    try:
+        rows = store.container_objects(run, container_id)
+    except FileNotFoundError:
+        raise HTTPException(404, f"No forensic data for container {container_id}")
+    if not rows:
+        raise HTTPException(404, f"Unknown container {container_id}")
+    return {"container_id": container_id, "objects": rows}
+
+
+# ------------------------------------------------------------------ error index
+
+
+@router.post("/megaeval/errors/search")
+def error_search(req: ErrorSearchRequest):
+    store = get_mega_store()
+    _published_or_409(req.run_id)
+    art = store.artifacts(req.run_id)
+    return errors_mod.search_errors(
+        art.get("errors"), art.get("containers"),
+        error_types=req.error_types or None, filters=req.filters or None,
+        confidence_max=req.confidence_max, confidence_min=req.confidence_min,
+        risk_min=req.risk_min, severity_min=req.severity_min,
+        safety_only=req.safety_only, limit_containers=req.limit_containers)
+
+
+# ------------------------------------------------------------------ compare / shift / why / similarity
+
+
+@router.post("/megaeval/compare")
+def compare(req: CompareRequest):
+    store = get_mega_store()
+    cand = _published_or_409(req.candidate_run_id)
+    base = _published_or_409(req.baseline_run_id)
+    return analysis.compare_runs(store, cand, base, req.policy or None)
+
+
+@router.get("/megaeval/runs/{run_id}/shift")
+def shift(run_id: str):
+    return analysis.distribution_shift(get_mega_store(), _published_or_409(run_id))
+
+
+@router.post("/megaeval/why")
+def why(req: WhyRequest):
+    return analysis.why(get_mega_store(), _published_or_409(req.run_id),
+                        req.filters or None, req.metric)
+
+
+@router.post("/megaeval/similarity")
+def similarity(req: SimilarityRequest):
+    try:
+        return analysis.similar_containers(get_mega_store(), _published_or_409(req.run_id),
+                                           req.container_id, req.filters or None, req.k)
+    except KeyError as e:
+        raise HTTPException(404, str(e))
+
+
+# ------------------------------------------------------------------ review sampling
+
+
+@router.get("/megaeval/runs/{run_id}/review")
+def review_state(run_id: str):
+    store = get_mega_store()
+    _published_or_409(run_id)
+    art = store.artifacts(run_id)
+    review = art.get("review")
+    if review is None:
+        return {"run_id": run_id, "planned": False, "executed": False}
+    slim = {k: v for k, v in review.items() if k != "plans"}
+    slim["planned"] = True
+    slim["strata"] = {name: plan["strata"] for name, plan in review["plans"].items()}
+    return slim
+
+
+@router.post("/megaeval/runs/{run_id}/review/plan")
+def review_plan(run_id: str, req: ReviewPlanRequest):
+    store = get_mega_store()
+    run = _published_or_409(run_id)
+    review = sampling.build_review_plan(store, run, target_n=req.target_n)
+    slim = {k: v for k, v in review.items() if k != "plans"}
+    slim["planned"] = True
+    slim["strata"] = {name: plan["strata"] for name, plan in review["plans"].items()}
+    return slim
+
+
+@router.post("/megaeval/runs/{run_id}/review/execute")
+def review_execute(run_id: str):
+    store = get_mega_store()
+    run = _published_or_409(run_id)
+    art = store.artifacts(run_id)
+    if art.get("review") is None:
+        sampling.build_review_plan(store, run)
+    review = sampling.execute_reviews(store, run)
+    slim = {k: v for k, v in review.items() if k != "plans"}
+    slim["planned"] = True
+    slim["strata"] = {name: plan["strata"] for name, plan in review["plans"].items()}
+    return slim
+
+
+# ------------------------------------------------------------------ distributions (sketches)
+
+
+@router.get("/megaeval/runs/{run_id}/distributions")
+def distributions(run_id: str):
+    store = get_mega_store()
+    run = _published_or_409(run_id)
+    art = store.artifacts(run_id)
+    sk = art.get("sketches", {})
+    out = {"run_id": run_id, "exact": False,
+           "note": "distributions are sketch-based (fixed-bin quantile histograms); "
+                   "counts in the cube are exact"}
+    for name in ("confidence", "iou"):
+        hist = sk.get(name)
+        if hist is None:
+            continue
+        out[name] = {
+            "bins": hist.bins, "lo": hist.lo, "hi": hist.hi,
+            "counts": hist.counts.tolist(),
+            "percentiles": {q: round(hist.percentile(float(q)), 4)
+                            for q in ("10", "25", "50", "75", "90", "99")},
+        }
+    out["containers_hll_estimate"] = sk.get("container_hll_estimate")
+    out["containers_exact"] = run.headline.get("containers")
+    out["available_sketch_metrics"] = SKETCH_METRICS
+    return out

sensorflow/megaeval/cube.py

@@ -0,0 +1,270 @@
+"""Metric cube: partial sufficient statistics -> reduce -> aggregate queries.
+
+The cube is the heart of aggregate-first evaluation. During a run, each worker
+computes *partial* additive statistics per partition, grouped by the 9 cube
+dimensions. Reducing = concatenating partials and summing per cell (map-side
+combine + shuffle reduce in Spark terms). Queries NEVER scan raw records unless
+they ask for something outside the cube (then the router honestly reports
+source="scan").
+
+Cell key: class x weather x lighting x road_type x scenario x sensor x
+          distance_band x speed_band x occlusion         (per evaluation run)
+Cell stats (all additive): n, tp, fp, fn, loc_err, anomalies, sum_iou,
+          sum_conf, sum_conf2, safety_n, safety_tp, reviewed, verified
+Derived on demand: precision, recall, f1, mean_iou, anomaly_rate,
+          conf_mean, conf_std, safety_recall, review_coverage, verified_rate
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import threading
+import time
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.megaeval.population import DIMENSIONS, DIM_NAMES
+
+STAT_COLS = ["n", "tp", "fp", "fn", "loc_err", "anomalies", "sum_iou",
+             "sum_conf", "sum_conf2", "safety_n", "safety_tp", "reviewed", "verified"]
+
+DERIVED_METRICS = ["precision", "recall", "f1", "mean_iou", "anomaly_rate",
+                   "conf_mean", "conf_std", "safety_recall", "review_coverage",
+                   "verified_rate", "error_rate"]
+COUNT_METRICS = ["n", "tp", "fp", "fn", "loc_err", "anomalies", "reviewed", "verified",
+                 "safety_n", "safety_tp"]
+SKETCH_METRICS = ["confidence_p50", "confidence_p10", "confidence_p90",
+                  "iou_p50", "iou_p10", "iou_p90"]
+ALL_METRICS = COUNT_METRICS + DERIVED_METRICS + SKETCH_METRICS
+
+
+# ------------------------------------------------------------------ partial stats
+
+
+def partial_stats(rows: pd.DataFrame) -> pd.DataFrame:
+    """Group one partition's contribution rows by the 9 dims and sum stat columns.
+
+    `rows` must contain DIM_NAMES code columns plus STAT_COLS contribution columns
+    (e.g. a TP object contributes n=1, tp=1, sum_iou=iou; an FP row contributes
+    n=0, fp=1, sum_conf=conf).
+    """
+    return rows.groupby(DIM_NAMES, as_index=False, observed=True, sort=False)[STAT_COLS].sum()
+
+
+def reduce_partials(partials: List[pd.DataFrame]) -> pd.DataFrame:
+    """Reduce partial stats into the final cube (concat + groupby-sum)."""
+    if not partials:
+        return pd.DataFrame(columns=DIM_NAMES + STAT_COLS)
+    return (pd.concat(partials, ignore_index=True)
+            .groupby(DIM_NAMES, as_index=False, observed=True, sort=False)[STAT_COLS]
+            .sum())
+
+
+def derive_metrics(agg: pd.DataFrame) -> pd.DataFrame:
+    """Attach derived ratio metrics to an aggregated (already summed) frame."""
+    out = agg.copy()
+    tp, fp, fn = out["tp"], out["fp"], out["fn"]
+    pp = tp + fp
+    with np.errstate(divide="ignore", invalid="ignore"):
+        out["precision"] = np.where(pp > 0, tp / pp, np.nan)
+        out["recall"] = np.where((tp + fn) > 0, tp / (tp + fn), np.nan)
+        p, r = out["precision"], out["recall"]
+        out["f1"] = np.where((p + r) > 0, 2 * p * r / (p + r), np.nan)
+        out["mean_iou"] = np.where(tp > 0, out["sum_iou"] / tp, np.nan)
+        out["anomaly_rate"] = np.where(out["n"] > 0, out["anomalies"] / out["n"], np.nan)
+        out["conf_mean"] = np.where(pp > 0, out["sum_conf"] / pp, np.nan)
+        var = np.where(pp > 1,
+                       (out["sum_conf2"] - out["sum_conf"] ** 2 / pp.replace(0, 1)) / (pp - 1).replace(0, 1),
+                       np.nan)
+        out["conf_std"] = np.sqrt(np.clip(var, 0, None))
+        out["safety_recall"] = np.where(out["safety_n"] > 0, out["safety_tp"] / out["safety_n"], np.nan)
+        out["review_coverage"] = np.where(out["n"] > 0, out["reviewed"] / out["n"], np.nan)
+        out["verified_rate"] = np.where(out["reviewed"] > 0, out["verified"] / out["reviewed"], np.nan)
+        out["error_rate"] = np.where(out["n"] > 0, (fn + fp + out["loc_err"]) / out["n"], np.nan)
+    return out
+
+
+# ------------------------------------------------------------------ persistence
+
+
+def save_cube(path: str, cube: pd.DataFrame) -> None:
+    np.savez_compressed(path, **{c: cube[c].to_numpy() for c in cube.columns})
+
+
+def load_cube(path: str) -> pd.DataFrame:
+    with np.load(path) as z:
+        return pd.DataFrame({k: z[k] for k in z.files})
+
+
+# ------------------------------------------------------------------ query router
+
+
+class QueryCache:
+    """Evaluation cache: key = hash(dataset+model+filters+group_by+metrics)."""
+
+    def __init__(self, max_entries: int = 512):
+        self._data: Dict[str, Dict] = {}
+        self._lock = threading.Lock()
+        self.max_entries = max_entries
+        self.hits = 0
+        self.misses = 0
+
+    @staticmethod
+    def key(dataset_version: str, model_version: str, filters: Dict,
+            group_by: List[str], metrics: List[str]) -> str:
+        blob = json.dumps({
+            "d": dataset_version, "m": model_version,
+            "f": {k: sorted(v) for k, v in sorted((filters or {}).items())},
+            "g": list(group_by or []), "x": sorted(metrics or []),
+        }, sort_keys=True)
+        return hashlib.sha256(blob.encode()).hexdigest()[:24]
+
+    def get(self, key: str) -> Optional[Dict]:
+        with self._lock:
+            hit = self._data.get(key)
+            if hit is not None:
+                self.hits += 1
+            else:
+                self.misses += 1
+            return hit
+
+    def put(self, key: str, value: Dict) -> None:
+        with self._lock:
+            if len(self._data) >= self.max_entries:
+                self._data.pop(next(iter(self._data)))
+            self._data[key] = value
+
+    def invalidate(self) -> None:
+        with self._lock:
+            self._data.clear()
+
+    def stats(self) -> Dict:
+        with self._lock:
+            total = self.hits + self.misses
+            return {"entries": len(self._data), "hits": self.hits, "misses": self.misses,
+                    "hit_rate": round(self.hits / total, 4) if total else None}
+
+
+def _codes_for(dim: str, values: List[str]) -> List[int]:
+    vocab = DIMENSIONS[dim]
+    out = []
+    for v in values:
+        if v in vocab:
+            out.append(vocab.index(v))
+    return out
+
+
+def apply_filters(cube: pd.DataFrame, filters: Optional[Dict[str, List[str]]]) -> pd.DataFrame:
+    if not filters:
+        return cube
+    mask = np.ones(len(cube), dtype=bool)
+    for dim, values in filters.items():
+        if dim not in DIM_NAMES:
+            continue
+        codes = _codes_for(dim, values if isinstance(values, list) else [values])
+        mask &= cube[dim].isin(codes).to_numpy()
+    return cube[mask]
+
+
+def aggregate(cube: pd.DataFrame, filters: Optional[Dict], group_by: Optional[List[str]],
+              metrics: Optional[List[str]], limit: int = 200) -> Tuple[List[Dict], int]:
+    """Aggregate-lookup path: filter cells, group, sum, derive. Never touches records."""
+    sub = apply_filters(cube, filters)
+    group_by = [g for g in (group_by or []) if g in DIM_NAMES]
+    metrics = [m for m in (metrics or []) if m in ALL_METRICS and m not in SKETCH_METRICS] \
+        or ["n", "precision", "recall", "f1", "mean_iou", "anomaly_rate"]
+
+    if group_by:
+        agg = sub.groupby(group_by, as_index=False, observed=True, sort=False)[STAT_COLS].sum()
+    else:
+        sums = sub[STAT_COLS].sum()
+        agg = pd.DataFrame([sums])
+    agg = derive_metrics(agg)
+
+    cell_count = len(sub)
+    sort_metric = next((m for m in metrics if m in agg.columns), None)
+    if group_by and sort_metric:
+        agg = agg.sort_values("n", ascending=False)
+    agg = agg.head(max(1, min(limit, 2000)))
+
+    rows: List[Dict] = []
+    for _, r in agg.iterrows():
+        row: Dict = {}
+        for g in group_by:
+            row[g] = DIMENSIONS[g][int(r[g])]
+        row["n"] = int(r["n"])
+        for m in metrics:
+            if m == "n":
+                continue
+            v = r.get(m)
+            if v is None or (isinstance(v, float) and np.isnan(v)):
+                row[m] = None
+            elif m in COUNT_METRICS:
+                row[m] = int(v)
+            else:
+                row[m] = round(float(v), 6)
+        rows.append(row)
+    return rows, cell_count
+
+
+class QueryRouter:
+    """Routes a query: cache -> cube aggregate -> (only if unavoidable) record scan.
+
+    This is the OLAP-engine seam: callers never know how data is stored.
+    """
+
+    def __init__(self):
+        self.cache = QueryCache()
+
+    def query(self, run: "object", cube: pd.DataFrame, sketches: Dict,
+              filters: Optional[Dict], metrics: Optional[List[str]],
+              group_by: Optional[List[str]], limit: int = 200,
+              scan_fn=None) -> Dict:
+        t0 = time.perf_counter()
+        metrics = metrics or []
+        key = QueryCache.key(run.population_id, run.model_version,
+                             filters or {}, group_by or [], metrics)
+        cached = self.cache.get(key)
+        if cached is not None:
+            return {**cached,
+                    "meta": {**cached["meta"], "cache_hit": True, "source": "cache",
+                             "latency_ms": round((time.perf_counter() - t0) * 1000, 3)}}
+
+        sketch_wanted = [m for m in metrics if m in SKETCH_METRICS]
+        needs_scan = any(g not in DIM_NAMES for g in (group_by or []))
+
+        if needs_scan and scan_fn is not None:
+            rows, cell_count = scan_fn(filters, group_by, metrics, limit)
+            source, exact = "scan", True
+        else:
+            rows, cell_count = aggregate(cube, filters, group_by, metrics, limit)
+            source, exact = "cube", True
+            if sketch_wanted and not group_by and not filters:
+                # population-level percentile questions answered from sketches
+                for m in sketch_wanted:
+                    metric_name, q = m.rsplit("_p", 1)
+                    hist = sketches.get(metric_name)
+                    if hist is not None and rows:
+                        rows[0][m] = round(float(hist.percentile(float(q))), 6)
+                exact = False  # percentiles are approximate
+            elif sketch_wanted:
+                exact = True  # sketch metrics ignored on grouped/filtered queries
+
+        latency = round((time.perf_counter() - t0) * 1000, 3)
+        result = {
+            "rows": rows,
+            "meta": {
+                "source": source,
+                "cache_hit": False,
+                "latency_ms": latency,
+                "cells_touched": cell_count,
+                "exact": exact,
+                "approximate_fields": sketch_wanted if not exact else [],
+            },
+        }
+        self.cache.put(key, result)
+        return result

sensorflow/megaeval/errors.py

@@ -0,0 +1,106 @@
+"""Error index: fast multi-criteria search over evaluation errors.
+
+The index is a columnar table (one row per error) built during the run:
+    error_id, object_id, container_id, error_type, severity, confidence,
+    risk_score, safety_critical, sensor_disagree, + the 9 cube dimensions.
+
+Searches return the *worst-N containers* (aggregated), never raw record dumps —
+this backs the Investigation UI. Individual exemplar errors are capped.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.megaeval.population import DIMENSIONS, DIM_NAMES
+from sensorflow.megaeval.runs import ERROR_TYPES
+
+
+def search_errors(
+    errors: pd.DataFrame,
+    containers: pd.DataFrame,
+    error_types: Optional[List[str]] = None,
+    filters: Optional[Dict[str, List[str]]] = None,
+    confidence_max: Optional[float] = None,
+    confidence_min: Optional[float] = None,
+    risk_min: Optional[float] = None,
+    severity_min: Optional[float] = None,
+    safety_only: bool = False,
+    limit_containers: int = 25,
+    limit_examples: int = 50,
+) -> Dict:
+    if errors is None or not len(errors):
+        return {"matched_errors": 0, "worst_containers": [], "examples": [],
+                "by_type": {}}
+    mask = np.ones(len(errors), dtype=bool)
+    if error_types:
+        codes = [ERROR_TYPES.index(t) for t in error_types if t in ERROR_TYPES]
+        mask &= errors["error_type"].isin(codes).to_numpy()
+    for dim, values in (filters or {}).items():
+        if dim not in DIM_NAMES:
+            continue
+        vocab = DIMENSIONS[dim]
+        codes = [vocab.index(v) for v in (values if isinstance(values, list) else [values])
+                 if v in vocab]
+        mask &= errors[dim].isin(codes).to_numpy()
+    if confidence_max is not None:
+        mask &= errors["confidence"].to_numpy() <= confidence_max
+    if confidence_min is not None:
+        mask &= errors["confidence"].to_numpy() >= confidence_min
+    if risk_min is not None:
+        mask &= errors["risk_score"].to_numpy() >= risk_min
+    if severity_min is not None:
+        mask &= errors["severity"].to_numpy() >= severity_min
+    if safety_only:
+        mask &= errors["safety_critical"].to_numpy().astype(bool)
+
+    sub = errors[mask]
+    by_type = {ERROR_TYPES[int(c)]: int(n)
+               for c, n in sub["error_type"].value_counts().items()}
+
+    # aggregate to worst containers: rank by count x mean risk
+    grp = sub.groupby("container_id", as_index=False).agg(
+        error_count=("error_id", "size"), mean_risk=("risk_score", "mean"),
+        max_severity=("severity", "max"), safety_hits=("safety_critical", "sum"))
+    grp["rank_score"] = grp["error_count"] * grp["mean_risk"]
+    grp = grp.sort_values("rank_score", ascending=False).head(limit_containers)
+    cmeta = containers.set_index("container_id") if containers is not None else None
+    worst = []
+    for _, r in grp.iterrows():
+        cid = int(r["container_id"])
+        item = {"container_id": cid, "error_count": int(r["error_count"]),
+                "mean_risk": round(float(r["mean_risk"]), 4),
+                "max_severity": round(float(r["max_severity"]), 4),
+                "safety_hits": int(r["safety_hits"])}
+        if cmeta is not None and cid in cmeta.index:
+            row = cmeta.loc[cid]
+            for dim in ("weather", "lighting", "road_type", "scenario"):
+                item[dim] = DIMENSIONS[dim][int(row[dim])]
+            item["n_objects"] = int(row["n_objects"])
+            item["risk_score"] = round(float(row["risk_score"]), 4)
+        worst.append(item)
+
+    ex = sub.sort_values("risk_score", ascending=False).head(limit_examples)
+    examples = []
+    for _, r in ex.iterrows():
+        examples.append({
+            "error_id": int(r["error_id"]),
+            "annotation_id": (f"obj-{int(r['object_id'])}" if r["object_id"] >= 0
+                              else f"fp-{int(r['error_id'])}"),
+            "container_id": int(r["container_id"]),
+            "error_type": ERROR_TYPES[int(r["error_type"])],
+            "class": DIMENSIONS["class"][int(r["class"])],
+            "severity": round(float(r["severity"]), 4),
+            "confidence": round(float(r["confidence"]), 4),
+            "risk_score": round(float(r["risk_score"]), 4),
+            "safety_critical": bool(r["safety_critical"]),
+            "scenario": DIMENSIONS["scenario"][int(r["scenario"])],
+            "lighting": DIMENSIONS["lighting"][int(r["lighting"])],
+            "weather": DIMENSIONS["weather"][int(r["weather"])],
+        })
+
+    return {"matched_errors": int(len(sub)), "by_type": by_type,
+            "worst_containers": worst, "examples": examples}

sensorflow/megaeval/population.py

@@ -0,0 +1,281 @@
+"""Immutable synthetic populations, generated vectorized and stored partitioned.
+
+Storage layout (single-node stand-in for an Iceberg/parquet lakehouse — no parquet
+engine is installed in this venv, so partitions are compressed npz column files):
+
+    runs/megaeval/populations/{pop_id}/
+        meta.json          dataset card: dims vocab, counts (exact), train mix, lineage
+        part-0000.npz ...  column arrays partitioned by container_id % NUM_PARTITIONS
+
+Every object row carries:
+  - 9 low-cardinality dimension codes (the cube dimensions)
+  - a model-independent `difficulty` in [0,1] (occlusion/distance/lighting/weather/size)
+  - `safety_critical` flag (VRUs in high-risk scenarios)
+
+The "training mix" is a deliberately shifted joint distribution over
+(class, weather, lighting) used by shift detection: training saw less
+night/rain/fog than this evaluation population.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import threading
+import uuid
+from datetime import datetime, timezone
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+
+MEGA_ROOT = os.path.join("runs", "megaeval")
+NUM_PARTITIONS = 32
+
+DIMENSIONS: Dict[str, List[str]] = {
+    "class": ["vehicle", "pedestrian", "cyclist", "motorcycle", "truck", "bus"],
+    "weather": ["clear", "rain", "fog", "snow"],
+    "lighting": ["day", "night", "dusk"],
+    "road_type": ["highway", "urban", "rural", "intersection"],
+    "scenario": ["nominal", "near_miss", "occlusion_heavy", "night_glare",
+                 "extreme_ttc", "sensor_degraded"],
+    "sensor": ["lidar", "camera", "fused"],
+    "distance_band": ["0-20m", "20-50m", "50-100m", "100m+"],
+    "speed_band": ["stationary", "slow", "medium", "fast"],
+    "occlusion": ["none", "partial", "heavy"],
+}
+DIM_NAMES = list(DIMENSIONS.keys())
+CONTAINER_DIMS = ["weather", "lighting", "road_type", "scenario"]
+OBJECT_DIMS = ["class", "sensor", "distance_band", "speed_band", "occlusion"]
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def pop_dir(pop_id: str) -> str:
+    return os.path.join(MEGA_ROOT, "populations", pop_id)
+
+
+def set_mega_root(path: str) -> None:
+    """Test hook: relocate all megaeval storage (and clear partition caches)."""
+    global MEGA_ROOT
+    MEGA_ROOT = str(path)
+    with _CACHE_LOCK:
+        _PART_CACHE.clear()
+
+
+# ------------------------------------------------------------------ generation
+
+
+def _sample_container_dims(rng: np.random.Generator, n: int) -> Dict[str, np.ndarray]:
+    """Correlated container-level context (weather/lighting/road/scenario)."""
+    weather = rng.choice(4, size=n, p=[0.62, 0.20, 0.11, 0.07]).astype(np.int8)
+    lighting = rng.choice(3, size=n, p=[0.60, 0.28, 0.12]).astype(np.int8)
+    road = rng.choice(4, size=n, p=[0.30, 0.38, 0.14, 0.18]).astype(np.int8)
+    scenario = rng.choice(6, size=n, p=[0.66, 0.09, 0.09, 0.06, 0.05, 0.05]).astype(np.int8)
+    # correlations: night_glare scenario forces night; fog/snow raise sensor_degraded odds
+    scenario_names = DIMENSIONS["scenario"]
+    lighting[scenario == scenario_names.index("night_glare")] = 1  # night
+    bad_wx = (weather >= 2)
+    flip = bad_wx & (rng.random(n) < 0.18)
+    scenario[flip] = scenario_names.index("sensor_degraded")
+    return {"weather": weather, "lighting": lighting, "road_type": road, "scenario": scenario}
+
+
+_CLASS_MIX_BY_ROAD = np.array([
+    # vehicle, pedestrian, cyclist, motorcycle, truck, bus
+    [0.62, 0.02, 0.01, 0.05, 0.24, 0.06],   # highway
+    [0.44, 0.26, 0.12, 0.06, 0.07, 0.05],   # urban
+    [0.55, 0.08, 0.06, 0.08, 0.18, 0.05],   # rural
+    [0.40, 0.30, 0.14, 0.05, 0.06, 0.05],   # intersection
+])
+
+_SPEED_MIX_BY_ROAD = np.array([
+    [0.02, 0.08, 0.35, 0.55],   # highway
+    [0.22, 0.44, 0.28, 0.06],   # urban
+    [0.10, 0.30, 0.40, 0.20],   # rural
+    [0.30, 0.45, 0.20, 0.05],   # intersection
+])
+
+
+def _object_difficulty(codes: Dict[str, np.ndarray], rng: np.random.Generator) -> np.ndarray:
+    """Model-independent difficulty in [0,1] — the physical hardness of each object."""
+    n = codes["class"].shape[0]
+    d = np.full(n, 0.12, dtype=np.float32)
+    d += np.array([0.00, 0.14, 0.12, 0.10, 0.02, 0.02], dtype=np.float32)[codes["class"]]
+    d += np.array([0.00, 0.08, 0.12, 0.10], dtype=np.float32)[codes["weather"]]
+    d += np.array([0.00, 0.12, 0.05], dtype=np.float32)[codes["lighting"]]
+    d += np.array([0.00, 0.10, 0.24], dtype=np.float32)[codes["occlusion"]]
+    d += np.array([0.00, 0.05, 0.14, 0.26], dtype=np.float32)[codes["distance_band"]]
+    d += np.array([0.00, 0.04, 0.08, 0.06, 0.07, 0.12], dtype=np.float32)[codes["scenario"]]
+    d += rng.normal(0.0, 0.05, size=n).astype(np.float32)
+    return np.clip(d, 0.01, 0.99)
+
+
+def generate_population(
+    name: str = "mega-perception",
+    num_objects: int = 320_000,
+    seed: int = 42,
+    avg_objects_per_container: float = 12.0,
+) -> Dict:
+    """Generate + persist a partitioned population. Vectorized; ~seconds for 320k."""
+    rng = np.random.default_rng(seed)
+    num_containers = max(64, int(num_objects / avg_objects_per_container))
+
+    cdims = _sample_container_dims(rng, num_containers)
+    per_container = np.clip(rng.poisson(avg_objects_per_container, size=num_containers),
+                            3, 48).astype(np.int64)
+    total = int(per_container.sum())
+    container_id = np.repeat(np.arange(num_containers, dtype=np.int64), per_container)
+
+    codes: Dict[str, np.ndarray] = {k: cdims[k][container_id] for k in CONTAINER_DIMS}
+
+    road_obj = codes["road_type"].astype(np.int64)
+    u = rng.random(total)
+    cls_cdf = np.cumsum(_CLASS_MIX_BY_ROAD, axis=1)[road_obj]
+    codes["class"] = (u[:, None] > cls_cdf).sum(axis=1).astype(np.int8)
+    u2 = rng.random(total)
+    spd_cdf = np.cumsum(_SPEED_MIX_BY_ROAD, axis=1)[road_obj]
+    codes["speed_band"] = (u2[:, None] > spd_cdf).sum(axis=1).astype(np.int8)
+    codes["sensor"] = rng.choice(3, size=total, p=[0.38, 0.22, 0.40]).astype(np.int8)
+    codes["distance_band"] = rng.choice(4, size=total, p=[0.24, 0.40, 0.25, 0.11]).astype(np.int8)
+
+    occ_p = np.tile(np.array([0.62, 0.28, 0.10]), (total, 1))
+    heavy_scene = codes["scenario"] == DIMENSIONS["scenario"].index("occlusion_heavy")
+    occ_p[heavy_scene] = [0.20, 0.42, 0.38]
+    occ_cdf = np.cumsum(occ_p, axis=1)
+    codes["occlusion"] = (rng.random(total)[:, None] > occ_cdf).sum(axis=1).astype(np.int8)
+
+    difficulty = _object_difficulty(codes, rng)
+    vru = np.isin(codes["class"], [1, 2, 3])
+    risky_scene = np.isin(codes["scenario"], [1, 4])  # near_miss, extreme_ttc
+    near = codes["distance_band"] <= 1
+    safety_critical = (vru & (risky_scene | (near & (rng.random(total) < 0.15)))).astype(np.uint8)
+
+    object_id = np.arange(total, dtype=np.int64)
+    pop_id = f"pop-{uuid.uuid4().hex[:10]}"
+    d = pop_dir(pop_id)
+    os.makedirs(d, exist_ok=True)
+
+    part_of = (container_id % NUM_PARTITIONS).astype(np.int64)
+    order = np.argsort(part_of, kind="stable")
+    part_sorted = part_of[order]
+    bounds = np.searchsorted(part_sorted, np.arange(NUM_PARTITIONS + 1))
+    partition_meta = []
+    for p in range(NUM_PARTITIONS):
+        sl = order[bounds[p]:bounds[p + 1]]
+        cols = {k: codes[k][sl] for k in DIM_NAMES}
+        cols["object_id"] = object_id[sl]
+        cols["container_id"] = container_id[sl]
+        cols["difficulty"] = difficulty[sl]
+        cols["safety_critical"] = safety_critical[sl]
+        np.savez_compressed(os.path.join(d, f"part-{p:04d}.npz"), **cols)
+        partition_meta.append({"partition": p, "rows": int(sl.size)})
+
+    # exact per-dimension counts (dataset card)
+    dim_counts = {
+        k: {DIMENSIONS[k][i]: int(c) for i, c in enumerate(np.bincount(codes[k], minlength=len(DIMENSIONS[k])))}
+        for k in DIM_NAMES
+    }
+
+    train_mix = _training_mix(codes, rng)
+
+    meta = {
+        "population_id": pop_id,
+        "name": name,
+        "created_at": _now(),
+        "seed": seed,
+        "num_objects": total,
+        "num_containers": num_containers,
+        "num_partitions": NUM_PARTITIONS,
+        "avg_objects_per_container": round(total / num_containers, 2),
+        "dimensions": DIMENSIONS,
+        "dim_counts": dim_counts,
+        "partitions": partition_meta,
+        "safety_critical_count": int(safety_critical.sum()),
+        "train_mix": train_mix,
+    }
+    with open(os.path.join(d, "meta.json"), "w") as f:
+        json.dump(meta, f)
+    return meta
+
+
+def _training_mix(codes: Dict[str, np.ndarray], rng: np.random.Generator) -> List[Dict]:
+    """Joint (class, weather, lighting) proportions the *training* set had.
+
+    Derived from the eval mix with deliberate, deterministic under-representation of
+    hard conditions (night, rain/fog/snow, VRU at night) so shift detection has
+    honest signal: shift = eval share vs train share of the same cohort.
+    """
+    n = codes["class"].shape[0]
+    key = (codes["class"].astype(np.int64) * 100
+           + codes["weather"].astype(np.int64) * 10
+           + codes["lighting"].astype(np.int64))
+    uniq, counts = np.unique(key, return_counts=True)
+    eval_share = counts / n
+
+    cls, wx, lt = uniq // 100, (uniq // 10) % 10, uniq % 10
+    factor = np.ones(uniq.shape)
+    factor[lt == 1] *= 0.55                       # trained on less night
+    factor[wx >= 1] *= 0.70                       # less rain/fog/snow
+    factor[(np.isin(cls, [1, 2])) & (lt == 1)] *= 0.75  # far fewer night VRUs
+    train_share = eval_share * factor
+    train_share = train_share / train_share.sum()
+
+    out = []
+    for i in range(uniq.size):
+        out.append({
+            "class": DIMENSIONS["class"][int(cls[i])],
+            "weather": DIMENSIONS["weather"][int(wx[i])],
+            "lighting": DIMENSIONS["lighting"][int(lt[i])],
+            "train_share": float(train_share[i]),
+            "eval_share": float(eval_share[i]),
+            "eval_count": int(counts[i]),
+        })
+    return out
+
+
+# ------------------------------------------------------------------ loading
+
+
+_PART_CACHE: Dict[Tuple[str, int], Dict[str, np.ndarray]] = {}
+_CACHE_LOCK = threading.Lock()
+
+
+def load_meta(pop_id: str) -> Optional[Dict]:
+    path = os.path.join(pop_dir(pop_id), "meta.json")
+    if not os.path.exists(path):
+        return None
+    with open(path) as f:
+        return json.load(f)
+
+
+def list_populations() -> List[Dict]:
+    base = os.path.join(MEGA_ROOT, "populations")
+    if not os.path.isdir(base):
+        return []
+    metas = []
+    for pid in sorted(os.listdir(base)):
+        m = load_meta(pid)
+        if m:
+            metas.append(m)
+    return metas
+
+
+def load_partition(pop_id: str, partition: int) -> Dict[str, np.ndarray]:
+    key = (pop_id, partition)
+    with _CACHE_LOCK:
+        if key in _PART_CACHE:
+            return _PART_CACHE[key]
+    path = os.path.join(pop_dir(pop_id), f"part-{partition:04d}.npz")
+    with np.load(path) as z:
+        cols = {k: z[k] for k in z.files}
+    with _CACHE_LOCK:
+        if len(_PART_CACHE) > 96:  # bounded partition cache
+            _PART_CACHE.clear()
+        _PART_CACHE[key] = cols
+    return cols
+
+
+def partition_of_container(container_id: int) -> int:
+    return int(container_id) % NUM_PARTITIONS

sensorflow/megaeval/runs.py

@@ -0,0 +1,704 @@
+"""Evaluation runs: first-class async jobs producing cubes, error indexes and sketches.
+
+Lifecycle:  create -> queued -> running (workers over partitions, partial stats)
+            -> reducing -> materializing -> published   (or failed)
+
+Each worker processes one population partition (Spark-executor stand-in):
+  1. vectorized model simulation (deterministic given lineage seed)
+  2. partial sufficient statistics grouped by the 9 cube dims
+  3. per-object outputs persisted for forensic drill-down / honest scan fallback
+  4. error rows + sketch updates + container partial aggregates
+
+Reduce = concat partials + groupby-sum (cube.reduce_partials).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import platform
+import threading
+import time
+import uuid
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.megaeval import cube as cube_mod
+from sensorflow.megaeval import population as pop_mod
+from sensorflow.megaeval.population import DIMENSIONS, DIM_NAMES
+from sensorflow.megaeval.sketches import HyperLogLog, QuantileHistogram, Reservoir
+
+ERROR_TYPES = ["FN", "FP", "LOCALIZATION", "ANOMALY", "LOW_CONF"]
+CONTAINER_STATUS = ["ok", "warn", "critical"]
+IOU_MATCH_THRESHOLD = 0.5
+EVALUATOR_CODE_VERSION = "megaeval-1.0.0"
+METRIC_VERSION = "metrics-1.0"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def run_dir(run_id: str) -> str:
+    return os.path.join(pop_mod.MEGA_ROOT, "runs", run_id)
+
+
+# ------------------------------------------------------------------ model profiles
+
+
+def model_params(model_version: str, overrides: Optional[Dict] = None) -> Dict:
+    """Deterministic model skill profile derived from the version string.
+
+    Overrides let tests/demos inject regressions (e.g. worse night detection).
+    """
+    h = int(hashlib.sha256(model_version.encode()).hexdigest()[:8], 16)
+    r = np.random.default_rng(h)
+    params = {
+        "base_detect": 0.972 + float(r.uniform(-0.01, 0.015)),
+        "difficulty_weight": 0.18,
+        "night_penalty": 0.030 + float(r.uniform(0, 0.02)),
+        "rain_penalty": 0.020 + float(r.uniform(0, 0.015)),
+        "occlusion_penalty": 0.050,
+        "vru_penalty": 0.020 + float(r.uniform(0, 0.015)),
+        "far_penalty": 0.045,
+        "iou_base": 0.875 + float(r.uniform(-0.01, 0.015)),
+        "iou_difficulty": 0.28,
+        "fp_per_container": 0.30 + float(r.uniform(0, 0.08)),
+        "anomaly_base": 0.018,
+        "low_conf_threshold": 0.45,
+    }
+    params.update(overrides or {})
+    return params
+
+
+# ------------------------------------------------------------------ run entity
+
+
+class EvaluationRun:
+    def __init__(self, population_id: str, model_version: str,
+                 overrides: Optional[Dict] = None, seed: Optional[int] = None,
+                 worker_delay_s: float = 0.0, workers: int = 4,
+                 label_version: str = "labels-v1",
+                 threshold_config: Optional[Dict] = None,
+                 sampling_config: Optional[Dict] = None):
+        self.run_id = f"eval-{uuid.uuid4().hex[:10]}"
+        self.population_id = population_id
+        self.model_version = model_version
+        self.overrides = overrides or {}
+        self.seed = seed if seed is not None else int(
+            hashlib.sha256(f"{population_id}|{model_version}|{label_version}".encode()
+                           ).hexdigest()[:8], 16)
+        self.worker_delay_s = worker_delay_s
+        self.workers = workers
+        self.status = "created"
+        self.error: Optional[str] = None
+        self.created_at = _now()
+        self.started_at: Optional[str] = None
+        self.published_at: Optional[str] = None
+        self.partitions_total = 0
+        self.partitions_done = 0
+        self.objects_total = 0
+        self.objects_processed = 0
+        self.throughput_objs_per_s = 0.0
+        self.eta_s: Optional[float] = None
+        self.headline: Dict = {}
+        self.per_class: Dict = {}
+        self.lineage = {
+            "evaluation_id": self.run_id,
+            "dataset_version": population_id,
+            "model_version": model_version,
+            "model_checkpoint": f"ckpt-{hashlib.sha256(model_version.encode()).hexdigest()[:10]}",
+            "label_version": label_version,
+            "evaluator_code_version": EVALUATOR_CODE_VERSION,
+            "metric_version": METRIC_VERSION,
+            "threshold_config": {"iou_match": IOU_MATCH_THRESHOLD,
+                                 **(threshold_config or {})},
+            "sampling_config": sampling_config or {"method": "stratified_risk_weighted",
+                                                   "target_n": 1500},
+            "seed": self.seed,
+            "hardware": f"{platform.machine()}/{platform.system()} single-node",
+            "timestamp": self.created_at,
+        }
+
+    def progress_dict(self) -> Dict:
+        pct = (self.partitions_done / self.partitions_total * 100) if self.partitions_total else 0.0
+        return {
+            "run_id": self.run_id,
+            "population_id": self.population_id,
+            "model_version": self.model_version,
+            "status": self.status,
+            "percent": round(pct, 2),
+            "partitions_done": self.partitions_done,
+            "partitions_total": self.partitions_total,
+            "objects_processed": int(self.objects_processed),
+            "objects_total": int(self.objects_total),
+            "workers": self.workers,
+            "throughput_objs_per_s": round(self.throughput_objs_per_s, 1),
+            "eta_s": round(self.eta_s, 1) if self.eta_s is not None else None,
+            "error": self.error,
+        }
+
+    def to_dict(self) -> Dict:
+        return {
+            **self.progress_dict(),
+            "created_at": self.created_at,
+            "started_at": self.started_at,
+            "published_at": self.published_at,
+            "lineage": self.lineage,
+            "headline": self.headline,
+            "per_class": self.per_class,
+            "overrides": self.overrides,
+        }
+
+
+# ------------------------------------------------------------------ partition evaluation
+
+
+def evaluate_partition(pop_id: str, partition: int, params: Dict, seed: int) -> Dict:
+    """Simulate the model on one partition; return partials + per-object outputs.
+
+    Fully vectorized and deterministic for (lineage seed, partition).
+    """
+    cols = pop_mod.load_partition(pop_id, partition)
+    n = cols["object_id"].shape[0]
+    rng = np.random.default_rng((seed * 1_000_003 + partition) % (2**63))
+
+    difficulty = cols["difficulty"].astype(np.float64)
+    p_det = params["base_detect"] - difficulty * params["difficulty_weight"]
+    p_det -= params["night_penalty"] * (cols["lighting"] == 1)
+    p_det -= params["rain_penalty"] * (cols["weather"] >= 1)
+    p_det -= params["occlusion_penalty"] * (cols["occlusion"] == 2)
+    p_det -= params["vru_penalty"] * np.isin(cols["class"], [1, 2, 3])
+    p_det -= params["far_penalty"] * (cols["distance_band"] == 3)
+    p_det = np.clip(p_det, 0.02, 0.995)
+    detected = rng.random(n) < p_det
+
+    iou = np.zeros(n, dtype=np.float64)
+    iou[detected] = np.clip(
+        rng.normal(params["iou_base"] - difficulty[detected] * params["iou_difficulty"], 0.07),
+        0.02, 0.985)
+    tp = detected & (iou >= IOU_MATCH_THRESHOLD)
+    loc = detected & ~tp
+
+    conf = np.zeros(n, dtype=np.float64)
+    conf[detected] = np.clip(
+        0.55 * iou[detected] + 0.25 * (1 - difficulty[detected])
+        + rng.normal(0.05, 0.08, size=int(detected.sum())), 0.01, 0.999)
+
+    anomaly_p = params["anomaly_base"] * (1 + 2.0 * difficulty
+                                          + 0.8 * (cols["scenario"] >= 4))
+    anomaly = rng.random(n) < anomaly_p
+    sensor_disagree = rng.random(n) < (0.04 + 0.25 * (cols["scenario"] == 5))
+
+    safety = cols["safety_critical"].astype(bool)
+
+    # ---- spurious FPs per container
+    uniq_containers, first_idx = np.unique(cols["container_id"], return_index=True)
+    ncont = uniq_containers.size
+    wx_c = cols["weather"][first_idx]
+    lt_c = cols["lighting"][first_idx]
+    lam = params["fp_per_container"] * (1 + 0.5 * (wx_c >= 1) + 0.6 * (lt_c == 1))
+    fp_counts = rng.poisson(lam)
+    total_fp = int(fp_counts.sum())
+    fp_container = np.repeat(uniq_containers, fp_counts)
+    fp_src = np.repeat(first_idx, fp_counts)
+    fp_cols = {k: cols[k][fp_src] for k in pop_mod.CONTAINER_DIMS}
+    fp_cols["class"] = rng.choice(6, size=total_fp,
+                                  p=[0.42, 0.18, 0.10, 0.08, 0.14, 0.08]).astype(np.int8)
+    fp_cols["sensor"] = rng.choice(3, size=total_fp).astype(np.int8)
+    fp_cols["distance_band"] = rng.choice(4, size=total_fp, p=[0.15, 0.35, 0.30, 0.20]).astype(np.int8)
+    fp_cols["speed_band"] = rng.choice(4, size=total_fp).astype(np.int8)
+    fp_cols["occlusion"] = rng.choice(3, size=total_fp, p=[0.5, 0.3, 0.2]).astype(np.int8)
+    fp_conf = np.clip(rng.beta(2.0, 4.5, size=total_fp) + 0.05, 0.01, 0.99)
+
+    # ---- contribution rows -> partial stats
+    gt = pd.DataFrame({k: cols[k] for k in DIM_NAMES})
+    gt["n"] = 1
+    gt["tp"] = tp.astype(np.int64)
+    gt["fp"] = loc.astype(np.int64)          # badly localized box counts as FP too
+    gt["fn"] = (~tp).astype(np.int64)
+    gt["loc_err"] = loc.astype(np.int64)
+    gt["anomalies"] = anomaly.astype(np.int64)
+    gt["sum_iou"] = np.where(tp, iou, 0.0)
+    gt["sum_conf"] = np.where(detected, conf, 0.0)
+    gt["sum_conf2"] = np.where(detected, conf**2, 0.0)
+    gt["safety_n"] = safety.astype(np.int64)
+    gt["safety_tp"] = (safety & tp).astype(np.int64)
+    gt["reviewed"] = 0
+    gt["verified"] = 0
+
+    fpf = pd.DataFrame({k: fp_cols[k] for k in DIM_NAMES})
+    fpf["n"] = 0
+    fpf["tp"] = 0
+    fpf["fp"] = 1
+    fpf["fn"] = 0
+    fpf["loc_err"] = 0
+    fpf["anomalies"] = 0
+    fpf["sum_iou"] = 0.0
+    fpf["sum_conf"] = fp_conf
+    fpf["sum_conf2"] = fp_conf**2
+    fpf["safety_n"] = 0
+    fpf["safety_tp"] = 0
+    fpf["reviewed"] = 0
+    fpf["verified"] = 0
+
+    partial = cube_mod.partial_stats(pd.concat([gt, fpf], ignore_index=True))
+
+    # ---- error rows (error index)
+    err_frames = []
+    fn_mask = ~detected
+    for etype, mask, sev_base in (("FN", fn_mask, 0.75), ("LOCALIZATION", loc, 0.55)):
+        idx = np.where(mask)[0]
+        if idx.size == 0:
+            continue
+        code = ERROR_TYPES.index(etype)
+        err_frames.append(pd.DataFrame({
+            "object_id": cols["object_id"][idx],
+            "container_id": cols["container_id"][idx],
+            "error_type": np.full(idx.size, code, dtype=np.int8),
+            "severity": np.clip(sev_base + 0.25 * safety[idx] + 0.15 * difficulty[idx], 0, 1),
+            "confidence": conf[idx],
+            "safety_critical": safety[idx].astype(np.uint8),
+            "sensor_disagree": sensor_disagree[idx].astype(np.uint8),
+            **{k: cols[k][idx] for k in DIM_NAMES},
+        }))
+    an_idx = np.where(anomaly & tp)[0]
+    if an_idx.size:
+        err_frames.append(pd.DataFrame({
+            "object_id": cols["object_id"][an_idx],
+            "container_id": cols["container_id"][an_idx],
+            "error_type": np.full(an_idx.size, ERROR_TYPES.index("ANOMALY"), dtype=np.int8),
+            "severity": np.clip(0.4 + 0.3 * difficulty[an_idx], 0, 1),
+            "confidence": conf[an_idx],
+            "safety_critical": safety[an_idx].astype(np.uint8),
+            "sensor_disagree": sensor_disagree[an_idx].astype(np.uint8),
+            **{k: cols[k][an_idx] for k in DIM_NAMES},
+        }))
+    lc_idx = np.where(tp & (conf < params["low_conf_threshold"]))[0]
+    if lc_idx.size:
+        err_frames.append(pd.DataFrame({
+            "object_id": cols["object_id"][lc_idx],
+            "container_id": cols["container_id"][lc_idx],
+            "error_type": np.full(lc_idx.size, ERROR_TYPES.index("LOW_CONF"), dtype=np.int8),
+            "severity": np.clip(0.3 + 0.2 * difficulty[lc_idx], 0, 1),
+            "confidence": conf[lc_idx],
+            "safety_critical": safety[lc_idx].astype(np.uint8),
+            "sensor_disagree": sensor_disagree[lc_idx].astype(np.uint8),
+            **{k: cols[k][lc_idx] for k in DIM_NAMES},
+        }))
+    if total_fp:
+        err_frames.append(pd.DataFrame({
+            "object_id": np.full(total_fp, -1, dtype=np.int64),
+            "container_id": fp_container,
+            "error_type": np.full(total_fp, ERROR_TYPES.index("FP"), dtype=np.int8),
+            "severity": np.clip(0.45 + 0.4 * fp_conf, 0, 1),
+            "confidence": fp_conf,
+            "safety_critical": np.zeros(total_fp, dtype=np.uint8),
+            "sensor_disagree": (rng.random(total_fp) < 0.08).astype(np.uint8),
+            **{k: fp_cols[k] for k in DIM_NAMES},
+        }))
+    errors = (pd.concat(err_frames, ignore_index=True) if err_frames
+              else pd.DataFrame())
+
+    # ---- container partial aggregates
+    cdf = pd.DataFrame({
+        "container_id": cols["container_id"],
+        **{k: cols[k] for k in pop_mod.CONTAINER_DIMS},
+        "n_objects": 1,
+        "tp": tp.astype(np.int64),
+        "fp": loc.astype(np.int64),
+        "fn": (~tp).astype(np.int64),
+        "anomalies": anomaly.astype(np.int64),
+        "sum_iou": np.where(tp, iou, 0.0),
+        "safety_n": safety.astype(np.int64),
+    })
+    containers = cdf.groupby(["container_id"] + pop_mod.CONTAINER_DIMS,
+                             as_index=False, observed=True).sum()
+    if total_fp:
+        fp_per = pd.Series(fp_container).value_counts()
+        containers["fp"] = containers["fp"] + containers["container_id"].map(fp_per).fillna(0).astype(np.int64)
+
+    # ---- sketches (per partition, merged at reduce)
+    conf_hist = QuantileHistogram(0, 1, 64)
+    conf_hist.add(np.concatenate([conf[detected], fp_conf]))
+    iou_hist = QuantileHistogram(0, 1, 64)
+    iou_hist.add(iou[tp])
+    hll = HyperLogLog(12)
+    hll.add_ids(uniq_containers)
+    reservoir = Reservoir(k=100, seed=partition)
+    if len(errors):
+        reservoir.add_ids(errors["object_id"].to_numpy()[errors["object_id"].to_numpy() >= 0][:2000])
+
+    # ---- per-object outputs (forensic view + scan fallback + brute-force tests)
+    obj_out = {
+        "object_id": cols["object_id"],
+        "container_id": cols["container_id"],
+        "detected": detected.astype(np.uint8),
+        "tp": tp.astype(np.uint8),
+        "iou": iou.astype(np.float32),
+        "confidence": conf.astype(np.float32),
+        "anomaly": anomaly.astype(np.uint8),
+        "sensor_disagree": sensor_disagree.astype(np.uint8),
+    }
+    fp_out = {
+        "container_id": fp_container,
+        "confidence": fp_conf.astype(np.float32),
+        **{k: fp_cols[k] for k in DIM_NAMES},
+    }
+
+    return {"partial": partial, "errors": errors, "containers": containers,
+            "conf_hist": conf_hist, "iou_hist": iou_hist, "hll": hll,
+            "reservoir": reservoir, "objects": obj_out, "fps": fp_out,
+            "rows": n}
+
+
+# ------------------------------------------------------------------ store
+
+
+class MegaStore:
+    """Registry of populations + runs, with lazily-loaded run artifacts."""
+
+    def __init__(self):
+        self.lock = threading.RLock()
+        self.runs: Dict[str, EvaluationRun] = {}
+        self._artifacts: Dict[str, Dict] = {}
+        self.router = cube_mod.QueryRouter()
+        self._load_persisted_runs()
+
+    def _load_persisted_runs(self) -> None:
+        base = os.path.join(pop_mod.MEGA_ROOT, "runs")
+        if not os.path.isdir(base):
+            return
+        for rid in sorted(os.listdir(base)):
+            meta_path = os.path.join(base, rid, "run.json")
+            if not os.path.exists(meta_path):
+                continue
+            try:
+                with open(meta_path) as f:
+                    d = json.load(f)
+                run = EvaluationRun.__new__(EvaluationRun)
+                run.__dict__.update(d["state"])
+                self.runs[run.run_id] = run
+            except Exception:
+                continue
+
+    def save_run(self, run: EvaluationRun) -> None:
+        d = run_dir(run.run_id)
+        os.makedirs(d, exist_ok=True)
+        state = {k: v for k, v in run.__dict__.items() if not k.startswith("_")}
+        with open(os.path.join(d, "run.json"), "w") as f:
+            json.dump({"state": state}, f)
+
+    # ---- artifacts
+
+    def artifacts(self, run_id: str) -> Dict:
+        with self.lock:
+            if run_id in self._artifacts:
+                return self._artifacts[run_id]
+        d = run_dir(run_id)
+        art: Dict = {}
+        cube_path = os.path.join(d, "cube.npz")
+        if os.path.exists(cube_path):
+            art["cube"] = cube_mod.load_cube(cube_path)
+        err_path = os.path.join(d, "errors.npz")
+        if os.path.exists(err_path):
+            with np.load(err_path) as z:
+                art["errors"] = pd.DataFrame({k: z[k] for k in z.files})
+        cont_path = os.path.join(d, "containers.npz")
+        if os.path.exists(cont_path):
+            with np.load(cont_path) as z:
+                art["containers"] = pd.DataFrame({k: z[k] for k in z.files})
+        emb_path = os.path.join(d, "embeddings.npz")
+        if os.path.exists(emb_path):
+            with np.load(emb_path) as z:
+                art["emb_ids"] = z["container_id"]
+                art["emb"] = z["emb"]
+        sk_path = os.path.join(d, "sketches.npz")
+        if os.path.exists(sk_path):
+            with np.load(sk_path) as z:
+                art["sketches"] = {
+                    "confidence": QuantileHistogram.from_arrays(0, 1, z["conf_hist"]),
+                    "iou": QuantileHistogram.from_arrays(0, 1, z["iou_hist"]),
+                    "container_hll_estimate": float(z["hll_estimate"]),
+                    "exemplar_ids": z["exemplars"].tolist(),
+                }
+        rev_path = os.path.join(d, "review.json")
+        if os.path.exists(rev_path):
+            with open(rev_path) as f:
+                art["review"] = json.load(f)
+        with self.lock:
+            if len(self._artifacts) > 6:
+                self._artifacts.pop(next(iter(self._artifacts)))
+            self._artifacts[run_id] = art
+        return art
+
+    def invalidate_artifacts(self, run_id: str) -> None:
+        with self.lock:
+            self._artifacts.pop(run_id, None)
+        self.router.cache.invalidate()
+
+    # ---- lifecycle
+
+    def create_run(self, **kwargs) -> EvaluationRun:
+        run = EvaluationRun(**kwargs)
+        meta = pop_mod.load_meta(run.population_id)
+        if meta is None:
+            raise KeyError(f"Unknown population {run.population_id}")
+        run.partitions_total = meta["num_partitions"]
+        run.objects_total = meta["num_objects"]
+        run.status = "queued"
+        with self.lock:
+            self.runs[run.run_id] = run
+        self.save_run(run)
+        return run
+
+    def start_async(self, run: EvaluationRun) -> None:
+        t = threading.Thread(target=self._execute, args=(run,), daemon=True)
+        t.start()
+
+    def execute_sync(self, run: EvaluationRun) -> None:
+        self._execute(run)
+
+    def _execute(self, run: EvaluationRun) -> None:
+        try:
+            run.status = "running"
+            run.started_at = _now()
+            t_start = time.perf_counter()
+            params = model_params(run.model_version, run.overrides)
+            d = run_dir(run.run_id)
+            os.makedirs(d, exist_ok=True)
+
+            partials: List[pd.DataFrame] = []
+            error_frames: List[pd.DataFrame] = []
+            container_frames: List[pd.DataFrame] = []
+            conf_hist = QuantileHistogram(0, 1, 64)
+            iou_hist = QuantileHistogram(0, 1, 64)
+            hll = HyperLogLog(12)
+            reservoir = Reservoir(k=200, seed=run.seed)
+            agg_lock = threading.Lock()
+
+            def work(p: int) -> None:
+                res = evaluate_partition(run.population_id, p, params, run.seed)
+                if run.worker_delay_s:
+                    time.sleep(run.worker_delay_s)  # simulated distributed I/O latency
+                # uncompressed npz: these are hot-path worker writes (few MB total)
+                np.savez(os.path.join(d, f"objects-part-{p:04d}.npz"), **res["objects"])
+                np.savez(os.path.join(d, f"fp-part-{p:04d}.npz"), **res["fps"])
+                nonlocal conf_hist, iou_hist, hll, reservoir
+                with agg_lock:
+                    partials.append(res["partial"])
+                    if len(res["errors"]):
+                        error_frames.append(res["errors"])
+                    container_frames.append(res["containers"])
+                    conf_hist = conf_hist.merge(res["conf_hist"])
+                    iou_hist = iou_hist.merge(res["iou_hist"])
+                    hll = hll.merge(res["hll"])
+                    reservoir = reservoir.merge(res["reservoir"])
+                    run.partitions_done += 1
+                    run.objects_processed += res["rows"]
+                    elapsed = time.perf_counter() - t_start
+                    run.throughput_objs_per_s = run.objects_processed / max(elapsed, 1e-6)
+                    remaining = run.objects_total - run.objects_processed
+                    run.eta_s = remaining / max(run.throughput_objs_per_s, 1e-6)
+
+            with ThreadPoolExecutor(max_workers=run.workers) as ex:
+                list(ex.map(work, range(run.partitions_total)))
+
+            run.status = "reducing"
+            cube_df = cube_mod.reduce_partials(partials)
+
+            run.status = "materializing"
+            cube_mod.save_cube(os.path.join(d, "cube.npz"), cube_df)
+
+            errors = (pd.concat(error_frames, ignore_index=True)
+                      if error_frames else pd.DataFrame())
+            if len(errors):
+                errors = errors.reset_index(drop=True)
+                errors["error_id"] = np.arange(len(errors), dtype=np.int64)
+                risk = (errors["severity"] * 0.5
+                        + errors["safety_critical"] * 0.3
+                        + (1 - errors["confidence"]) * 0.15
+                        + errors["sensor_disagree"] * 0.05)
+                errors["risk_score"] = np.clip(risk, 0, 1)
+                np.savez_compressed(os.path.join(d, "errors.npz"),
+                                    **{c: errors[c].to_numpy() for c in errors.columns})
+
+            containers = (pd.concat(container_frames, ignore_index=True)
+                          .groupby(["container_id"] + pop_mod.CONTAINER_DIMS,
+                                   as_index=False, observed=True).sum())
+            containers["reviewed"] = 0
+            containers["verified"] = 0
+            err_share = (containers["fn"] + containers["fp"]) / containers["n_objects"].clip(lower=1)
+            containers["risk_score"] = np.clip(
+                0.55 * err_share + 0.25 * (containers["anomalies"] / containers["n_objects"].clip(lower=1))
+                + 0.20 * (containers["safety_n"] > 0), 0, 1).round(4)
+            containers["status"] = np.select(
+                [containers["risk_score"] >= 0.45, containers["risk_score"] >= 0.2],
+                [2, 1], default=0).astype(np.int8)
+            np.savez_compressed(os.path.join(d, "containers.npz"),
+                                **{c: containers[c].to_numpy() for c in containers.columns})
+
+            self._build_embeddings(d, containers)
+
+            np.savez_compressed(os.path.join(d, "sketches.npz"),
+                                conf_hist=conf_hist.counts, iou_hist=iou_hist.counts,
+                                hll_estimate=np.array(hll.estimate()),
+                                exemplars=np.array(reservoir.items, dtype=np.int64))
+
+            headline_rows, _ = cube_mod.aggregate(
+                cube_df, None, None,
+                ["n", "tp", "fp", "fn", "loc_err", "anomalies", "precision", "recall", "f1",
+                 "mean_iou", "anomaly_rate", "safety_recall", "conf_mean", "error_rate"], 1)
+            run.headline = headline_rows[0]
+            run.headline["containers"] = int(containers.shape[0])
+            run.headline["containers_hll_estimate"] = round(hll.estimate(), 1)
+
+            per_class_rows, _ = cube_mod.aggregate(
+                cube_df, None, ["class"],
+                ["n", "precision", "recall", "f1", "mean_iou", "safety_recall", "anomaly_rate"], 50)
+            run.per_class = {r["class"]: r for r in per_class_rows}
+
+            run.status = "published"
+            run.published_at = _now()
+            run.eta_s = 0.0
+            self.save_run(run)
+            self.invalidate_artifacts(run.run_id)
+        except Exception as e:  # pragma: no cover - defensive
+            run.status = "failed"
+            run.error = str(e)
+            self.save_run(run)
+
+    @staticmethod
+    def _build_embeddings(d: str, containers: pd.DataFrame) -> None:
+        """32-d container embeddings: structural features + seeded random projection."""
+        feats = []
+        nobj = containers["n_objects"].clip(lower=1).to_numpy(dtype=np.float64)
+        for col in ("tp", "fp", "fn", "anomalies", "safety_n"):
+            feats.append(containers[col].to_numpy(dtype=np.float64) / nobj)
+        feats.append(containers["sum_iou"].to_numpy(dtype=np.float64)
+                     / containers["tp"].clip(lower=1).to_numpy(dtype=np.float64))
+        feats.append(np.log1p(nobj) / 4.0)
+        feats.append(containers["risk_score"].to_numpy(dtype=np.float64))
+        for dim in pop_mod.CONTAINER_DIMS:
+            k = len(DIMENSIONS[dim])
+            onehot = np.eye(k)[containers[dim].to_numpy(dtype=np.int64)]
+            feats.extend(onehot.T)
+        X = np.vstack(feats).T  # (n, ~25)
+        rng = np.random.default_rng(1234)
+        proj = rng.normal(size=(X.shape[1], 32)) / np.sqrt(X.shape[1])
+        emb = X @ proj
+        emb = emb / np.clip(np.linalg.norm(emb, axis=1, keepdims=True), 1e-9, None)
+        np.savez_compressed(os.path.join(d, "embeddings.npz"),
+                            container_id=containers["container_id"].to_numpy(),
+                            emb=emb.astype(np.float32))
+
+    # ---- forensic drill-down (deepest level; loads exactly one partition)
+
+    def container_objects(self, run: EvaluationRun, container_id: int) -> List[Dict]:
+        p = pop_mod.partition_of_container(container_id)
+        pop_cols = pop_mod.load_partition(run.population_id, p)
+        d = run_dir(run.run_id)
+        with np.load(os.path.join(d, f"objects-part-{p:04d}.npz")) as z:
+            out_cols = {k: z[k] for k in z.files}
+        mask = pop_cols["container_id"] == container_id
+        idx = np.where(mask)[0]
+        rows = []
+        for i in idx.tolist():
+            det = bool(out_cols["detected"][i])
+            tp = bool(out_cols["tp"][i])
+            rows.append({
+                "annotation_id": f"obj-{int(pop_cols['object_id'][i])}",
+                "container_id": int(container_id),
+                **{k: DIMENSIONS[k][int(pop_cols[k][i])] for k in DIM_NAMES},
+                "safety_critical": bool(pop_cols["safety_critical"][i]),
+                "difficulty": round(float(pop_cols["difficulty"][i]), 4),
+                "detected": det,
+                "outcome": "TP" if tp else ("LOCALIZATION" if det else "FN"),
+                "iou": round(float(out_cols["iou"][i]), 4) if det else None,
+                "confidence": round(float(out_cols["confidence"][i]), 4) if det else None,
+                "anomaly": bool(out_cols["anomaly"][i]),
+                "sensor_disagree": bool(out_cols["sensor_disagree"][i]),
+            })
+        with np.load(os.path.join(d, f"fp-part-{p:04d}.npz")) as z:
+            fp_cols = {k: z[k] for k in z.files}
+        fp_mask = fp_cols["container_id"] == container_id
+        for j in np.where(fp_mask)[0].tolist():
+            rows.append({
+                "annotation_id": f"fp-{run.run_id[-4:]}-{p}-{j}",
+                "container_id": int(container_id),
+                **{k: DIMENSIONS[k][int(fp_cols[k][j])] for k in DIM_NAMES},
+                "safety_critical": False,
+                "difficulty": None,
+                "detected": True,
+                "outcome": "FP",
+                "iou": 0.0,
+                "confidence": round(float(fp_cols["confidence"][j]), 4),
+                "anomaly": False,
+                "sensor_disagree": False,
+            })
+        return rows
+
+    # ---- honest record-scan fallback for the query router
+
+    def scan_records(self, run: EvaluationRun, filters: Optional[Dict],
+                     group_by: Optional[List[str]], metrics: Optional[List[str]],
+                     limit: int) -> tuple:
+        frames = []
+        d = run_dir(run.run_id)
+        for p in range(run.partitions_total):
+            pop_cols = pop_mod.load_partition(run.population_id, p)
+            with np.load(os.path.join(d, f"objects-part-{p:04d}.npz")) as z:
+                df = pd.DataFrame({
+                    **{k: pop_cols[k] for k in DIM_NAMES},
+                    "container_id": pop_cols["container_id"],
+                    "tp": z["tp"].astype(np.int64),
+                    "fn": (1 - z["tp"]).astype(np.int64),
+                    "fp": (z["detected"] & ~z["tp"].astype(bool)).astype(np.int64),
+                    "anomalies": z["anomaly"].astype(np.int64),
+                    "iou": z["iou"],
+                })
+            frames.append(df)
+        full = pd.concat(frames, ignore_index=True)
+        full = cube_mod.apply_filters(full, filters)
+        gb = [g for g in (group_by or []) if g in list(full.columns)]
+        if not gb:
+            gb = ["container_id"]
+        agg = full.groupby(gb, as_index=False, observed=True).agg(
+            n=("tp", "size"), tp=("tp", "sum"), fp=("fp", "sum"), fn=("fn", "sum"),
+            anomalies=("anomalies", "sum"), mean_iou=("iou", "mean"))
+        agg["recall"] = agg["tp"] / (agg["tp"] + agg["fn"]).clip(lower=1)
+        agg = agg.sort_values("n", ascending=False).head(limit)
+        rows = []
+        for _, r in agg.iterrows():
+            row = {}
+            for g in gb:
+                row[g] = DIMENSIONS[g][int(r[g])] if g in DIM_NAMES else int(r[g])
+            row.update({"n": int(r["n"]), "tp": int(r["tp"]), "fp": int(r["fp"]),
+                        "fn": int(r["fn"]), "anomalies": int(r["anomalies"]),
+                        "mean_iou": round(float(r["mean_iou"]), 6),
+                        "recall": round(float(r["recall"]), 6)})
+            rows.append(row)
+        return rows, len(full)
+
+
+_STORE: Optional[MegaStore] = None
+_STORE_LOCK = threading.Lock()
+
+
+def get_mega_store() -> MegaStore:
+    global _STORE
+    with _STORE_LOCK:
+        if _STORE is None:
+            _STORE = MegaStore()
+        return _STORE
+
+
+def reset_mega_store() -> None:
+    global _STORE
+    with _STORE_LOCK:
+        _STORE = None

sensorflow/megaeval/sampling.py

@@ -0,0 +1,261 @@
+"""Human review as statistical sampling.
+
+Instead of a flat "review N labels" queue, review effort is a designed sample:
+
+  population -> containers -> suspicious containers -> candidate pool
+             -> stratified risk-weighted selection -> reviews -> CIs
+
+Two estimands, each with its own sampling frame:
+  - precision: frame = predicted positives, strata = confidence tier x safety
+  - recall:    frame = ground-truth objects,  strata = model outcome x safety
+
+Risk weighting happens through *allocation* (risky strata get more samples);
+estimates stay honest because strata are combined with their true population
+weights (classic stratified estimator):
+
+    p_hat = sum_h W_h * p_hat_h
+    SE    = sqrt( sum_h W_h^2 * p_hat_h (1 - p_hat_h) / n_h )     (normal approx)
+
+Per-stratum intervals use Wilson. Simulated reviewers agree with ground truth
+with 98.5% fidelity (the synthetic stand-in for human accuracy).
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+from typing import Dict, List, Optional, Tuple
+
+import numpy as np
+import pandas as pd
+
+from sensorflow.megaeval import population as pop_mod
+from sensorflow.megaeval.population import DIM_NAMES
+from sensorflow.megaeval.runs import EvaluationRun, MegaStore, run_dir
+
+HUMAN_FIDELITY = 0.985
+Z95 = 1.959964
+
+
+def wilson_interval(k: 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 = k / n
+    denom = 1 + z**2 / n
+    center = (p + z**2 / (2 * n)) / denom
+    margin = z * math.sqrt(p * (1 - p) / n + z**2 / (4 * n**2)) / denom
+    return (max(0.0, center - margin), min(1.0, center + margin))
+
+
+def _load_unit_frames(store: MegaStore, run: EvaluationRun) -> Tuple[pd.DataFrame, pd.DataFrame]:
+    """One batch scan (NOT on the query path) to build the two sampling frames."""
+    d = run_dir(run.run_id)
+    gt_frames, pp_frames = [], []
+    for p in range(run.partitions_total):
+        pop_cols = pop_mod.load_partition(run.population_id, p)
+        with np.load(os.path.join(d, f"objects-part-{p:04d}.npz")) as z:
+            detected = z["detected"].astype(bool)
+            tp = z["tp"].astype(bool)
+            conf = z["confidence"]
+        base = pd.DataFrame({
+            "unit_id": pop_cols["object_id"],
+            "container_id": pop_cols["container_id"],
+            **{k: pop_cols[k] for k in DIM_NAMES},
+            "safety": pop_cols["safety_critical"].astype(bool),
+            "detected": detected, "tp": tp, "confidence": conf,
+        })
+        gt_frames.append(base)
+        pp = base[detected].copy()
+        pp["correct"] = pp["tp"]
+        pp_frames.append(pp)
+        with np.load(os.path.join(d, f"fp-part-{p:04d}.npz")) as z:
+            if z["container_id"].size:
+                fpdf = pd.DataFrame({
+                    "unit_id": -np.arange(1, z["container_id"].size + 1) - p * 10_000_000,
+                    "container_id": z["container_id"],
+                    **{k: z[k] for k in DIM_NAMES},
+                    "safety": False, "detected": True, "tp": False,
+                    "confidence": z["confidence"], "correct": False,
+                })
+                pp_frames.append(fpdf)
+    return pd.concat(gt_frames, ignore_index=True), pd.concat(pp_frames, ignore_index=True)
+
+
+def _stratify_precision(pp: pd.DataFrame) -> pd.Series:
+    tier = np.select([pp["confidence"] < 0.45, pp["confidence"] < 0.75], [0, 1], default=2)
+    return pd.Series(tier * 2 + pp["safety"].astype(int).to_numpy(), index=pp.index)
+
+
+def _stratify_recall(gt: pd.DataFrame) -> pd.Series:
+    return pd.Series((~gt["detected"]).astype(int).to_numpy() * 2
+                     + gt["safety"].astype(int).to_numpy(), index=gt.index)
+
+
+_PRECISION_STRATA = {0: "low_conf", 1: "low_conf_safety", 2: "mid_conf", 3: "mid_conf_safety",
+                     4: "high_conf", 5: "high_conf_safety"}
+_RECALL_STRATA = {0: "detected", 1: "detected_safety", 2: "missed", 3: "missed_safety"}
+# risk-weighted allocation multipliers (riskier strata get proportionally more reviews)
+_PRECISION_RISK_W = {0: 3.0, 1: 4.0, 2: 1.5, 3: 2.5, 4: 1.0, 5: 2.0}
+_RECALL_RISK_W = {0: 1.0, 1: 2.0, 2: 3.0, 3: 5.0}
+
+
+def _allocate(counts: Dict[int, int], risk_w: Dict[int, float], total_n: int) -> Dict[int, int]:
+    weights = {h: counts[h] * risk_w.get(h, 1.0) for h in counts}
+    wsum = sum(weights.values()) or 1.0
+    alloc = {}
+    for h, c in counts.items():
+        n_h = int(round(total_n * weights[h] / wsum))
+        alloc[h] = max(1, min(n_h, c)) if c > 0 else 0
+    return alloc
+
+
+def build_review_plan(store: MegaStore, run: EvaluationRun,
+                      target_n: Optional[int] = None, seed: int = 99) -> Dict:
+    """Build the sampling funnel + stratified selection. Persists review.json."""
+    target_n = target_n or run.lineage["sampling_config"].get("target_n", 1500)
+    rng = np.random.default_rng(seed + run.seed)
+    gt, pp = _load_unit_frames(store, run)
+    art = store.artifacts(run.run_id)
+    containers = art["containers"]
+    errors = art.get("errors", pd.DataFrame())
+
+    suspicious = int((containers["risk_score"] >= 0.2).sum())
+    candidates = int(len(errors)) if len(errors) else 0
+
+    plans = {}
+    for name, frame, strat_fn, labels, risk_w in (
+            ("precision", pp, _stratify_precision, _PRECISION_STRATA, _PRECISION_RISK_W),
+            ("recall", gt, _stratify_recall, _RECALL_STRATA, _RECALL_RISK_W)):
+        strata = strat_fn(frame)
+        counts = strata.value_counts().to_dict()
+        alloc = _allocate(counts, risk_w, target_n // 2)
+        selected = {}
+        for h, n_h in alloc.items():
+            if n_h <= 0:
+                continue
+            idx = frame.index[strata == h].to_numpy()
+            chosen = rng.choice(idx, size=min(n_h, idx.size), replace=False)
+            selected[str(h)] = frame.loc[chosen, "unit_id"].astype(np.int64).tolist()
+        plans[name] = {
+            "frame_size": int(len(frame)),
+            "strata": {str(h): {"label": labels[h], "N": int(counts.get(h, 0)),
+                                "allocated": int(alloc.get(h, 0))}
+                       for h in labels},
+            "selected_ids": selected,
+        }
+
+    selected_total = sum(len(v) for p in plans.values() for v in p["selected_ids"].values())
+    review = {
+        "run_id": run.run_id,
+        "method": "stratified risk-weighted sampling; Wilson per-stratum, "
+                  "stratified normal-approx combined CI",
+        "target_n": target_n,
+        "funnel": {
+            "population_objects": int(run.objects_total),
+            "containers": int(len(containers)),
+            "suspicious_containers": suspicious,
+            "candidate_pool": candidates,
+            "statistically_selected": int(selected_total),
+            "reviewed": 0,
+        },
+        "plans": plans,
+        "executed": False,
+        "results": None,
+    }
+    with open(os.path.join(run_dir(run.run_id), "review.json"), "w") as f:
+        json.dump(review, f)
+    store.invalidate_artifacts(run.run_id)
+    return review
+
+
+def execute_reviews(store: MegaStore, run: EvaluationRun, seed: int = 7) -> Dict:
+    """Simulate human review of the selected sample; compute CIs; update the cube."""
+    d = run_dir(run.run_id)
+    with open(os.path.join(d, "review.json")) as f:
+        review = json.load(f)
+    rng = np.random.default_rng(seed + run.seed)
+    gt, pp = _load_unit_frames(store, run)
+    gt_idx = gt.set_index("unit_id")
+    pp_idx = pp.set_index("unit_id")
+
+    results = {}
+    reviewed_units = []  # (dims..., verified) for cube update — recall-frame units only
+    total_reviewed = 0
+    for name, frame_idx, truth_col in (("precision", pp_idx, "correct"),
+                                       ("recall", gt_idx, "tp")):
+        plan = review["plans"][name]
+        strata_out = []
+        p_hat_comb, var_comb = 0.0, 0.0
+        frame_N = plan["frame_size"]
+        n_total = 0
+        for h, sinfo in plan["strata"].items():
+            ids = plan["selected_ids"].get(h, [])
+            if not ids:
+                continue
+            units = frame_idx.loc[[i for i in ids if i in frame_idx.index]]
+            if isinstance(units, pd.Series):
+                units = units.to_frame().T
+            truth = units[truth_col].astype(bool).to_numpy()
+            agrees = rng.random(truth.size) < HUMAN_FIDELITY
+            verdict = np.where(agrees, truth, ~truth)
+            k, n_h = int(verdict.sum()), int(verdict.size)
+            W_h = sinfo["N"] / frame_N
+            p_h = k / n_h if n_h else 0.0
+            lo, hi = wilson_interval(k, n_h)
+            strata_out.append({"stratum": sinfo["label"], "N": sinfo["N"], "n": n_h,
+                               "correct": k, "p": round(p_h, 4),
+                               "wilson_ci": [round(lo, 4), round(hi, 4)],
+                               "weight": round(W_h, 4)})
+            p_hat_comb += W_h * p_h
+            var_comb += (W_h**2) * p_h * (1 - p_h) / max(n_h, 1)
+            n_total += n_h
+            total_reviewed += n_h
+            if name == "recall":
+                sub = units.copy()
+                sub["verified"] = verdict
+                reviewed_units.append(sub)
+        se = math.sqrt(var_comb)
+        results[name] = {
+            "estimate": round(p_hat_comb, 4),
+            "ci_low": round(max(0.0, p_hat_comb - Z95 * se), 4),
+            "ci_high": round(min(1.0, p_hat_comb + Z95 * se), 4),
+            "n_reviewed": n_total,
+            "frame_size": frame_N,
+            "method": review["method"],
+            "strata": strata_out,
+        }
+
+    # ---- fold reviews back into the cube + container table (reviewed/verified counters)
+    if reviewed_units:
+        ru = pd.concat(reviewed_units)
+        ru = ru.reset_index(drop=True)
+        upd = ru.groupby(DIM_NAMES, as_index=False, observed=True).agg(
+            add_reviewed=("verified", "size"), add_verified=("verified", "sum"))
+        from sensorflow.megaeval import cube as cube_mod
+        cube_path = os.path.join(d, "cube.npz")
+        cube_df = cube_mod.load_cube(cube_path)
+        merged = cube_df.merge(upd, on=DIM_NAMES, how="left")
+        merged["reviewed"] = merged["reviewed"] + merged["add_reviewed"].fillna(0).astype(np.int64)
+        merged["verified"] = merged["verified"] + merged["add_verified"].fillna(0).astype(np.int64)
+        cube_mod.save_cube(cube_path, merged.drop(columns=["add_reviewed", "add_verified"]))
+
+        cupd = ru.groupby("container_id", as_index=False).agg(
+            add_reviewed=("verified", "size"), add_verified=("verified", "sum"))
+        cont_path = os.path.join(d, "containers.npz")
+        with np.load(cont_path) as z:
+            cont = pd.DataFrame({k: z[k] for k in z.files})
+        cont = cont.merge(cupd, on="container_id", how="left")
+        cont["reviewed"] = cont["reviewed"] + cont["add_reviewed"].fillna(0).astype(np.int64)
+        cont["verified"] = cont["verified"] + cont["add_verified"].fillna(0).astype(np.int64)
+        cont = cont.drop(columns=["add_reviewed", "add_verified"])
+        np.savez_compressed(cont_path, **{c: cont[c].to_numpy() for c in cont.columns})
+
+    review["executed"] = True
+    review["funnel"]["reviewed"] = total_reviewed
+    review["results"] = results
+    with open(os.path.join(d, "review.json"), "w") as f:
+        json.dump(review, f)
+    store.invalidate_artifacts(run.run_id)
+    return review

sensorflow/megaeval/sketches.py

@@ -0,0 +1,173 @@
+"""Lightweight approximate data structures for population statistics.
+
+All numpy-based, mergeable (so they can be maintained per partition and reduced),
+and each clearly reports whether an answer is exact or approximate.
+
+- QuantileHistogram: fixed-bin histogram over a known range; percentile queries by
+  linear interpolation inside the winning bin. Stand-in for a t-digest.
+- HyperLogLog: classic HLL with 2^p registers and numpy vectorized updates.
+- Reservoir: uniform reservoir sample of exemplar ids (Algorithm R, vectorized-ish).
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional
+
+import numpy as np
+
+# ---------------------------------------------------------------- hashing
+
+_SPLITMIX_1 = np.uint64(0x9E3779B97F4A7C15)
+_SPLITMIX_2 = np.uint64(0xBF58476D1CE4E5B9)
+_SPLITMIX_3 = np.uint64(0x94D049BB133111EB)
+
+
+def _hash64(values: np.ndarray) -> np.ndarray:
+    """Deterministic 64-bit mix (splitmix64) of integer identifiers."""
+    with np.errstate(over="ignore"):
+        z = values.astype(np.uint64) + _SPLITMIX_1
+        z = (z ^ (z >> np.uint64(30))) * _SPLITMIX_2
+        z = (z ^ (z >> np.uint64(27))) * _SPLITMIX_3
+        return z ^ (z >> np.uint64(31))
+
+
+# ---------------------------------------------------------------- quantile histogram
+
+
+class QuantileHistogram:
+    """Fixed-bin histogram over [lo, hi]; approximate percentiles via interpolation.
+
+    Mergeable: histograms with identical bin config add counts element-wise.
+    """
+
+    def __init__(self, lo: float = 0.0, hi: float = 1.0, bins: int = 64,
+                 counts: Optional[np.ndarray] = None):
+        self.lo, self.hi, self.bins = float(lo), float(hi), int(bins)
+        self.counts = counts if counts is not None else np.zeros(bins, dtype=np.int64)
+
+    def add(self, values: np.ndarray) -> None:
+        if values.size == 0:
+            return
+        clipped = np.clip(values, self.lo, self.hi)
+        idx = np.minimum(
+            ((clipped - self.lo) / (self.hi - self.lo) * self.bins).astype(np.int64),
+            self.bins - 1)
+        self.counts += np.bincount(idx, minlength=self.bins)
+
+    def merge(self, other: "QuantileHistogram") -> "QuantileHistogram":
+        assert (self.lo, self.hi, self.bins) == (other.lo, other.hi, other.bins)
+        return QuantileHistogram(self.lo, self.hi, self.bins, self.counts + other.counts)
+
+    @property
+    def total(self) -> int:
+        return int(self.counts.sum())
+
+    def percentile(self, q: float) -> Optional[float]:
+        """Approximate q-th percentile (q in [0, 100])."""
+        total = self.total
+        if total == 0:
+            return None
+        target = total * (q / 100.0)
+        cum = np.cumsum(self.counts)
+        bin_idx = int(np.searchsorted(cum, target, side="left"))
+        bin_idx = min(bin_idx, self.bins - 1)
+        prev_cum = cum[bin_idx - 1] if bin_idx > 0 else 0
+        in_bin = self.counts[bin_idx]
+        frac = 0.5 if in_bin == 0 else float(np.clip((target - prev_cum) / in_bin, 0.0, 1.0))
+        width = (self.hi - self.lo) / self.bins
+        return self.lo + (bin_idx + frac) * width
+
+    def to_dict(self) -> Dict:
+        return {"lo": self.lo, "hi": self.hi, "bins": self.bins,
+                "counts": self.counts.tolist(), "exact": False}
+
+    @staticmethod
+    def from_arrays(lo: float, hi: float, counts: np.ndarray) -> "QuantileHistogram":
+        return QuantileHistogram(lo, hi, len(counts), counts.astype(np.int64))
+
+
+# ---------------------------------------------------------------- HyperLogLog
+
+
+class HyperLogLog:
+    """HLL cardinality estimator with 2^p registers (approximate).
+
+    Mergeable: element-wise max of registers.
+    """
+
+    def __init__(self, p: int = 12, registers: Optional[np.ndarray] = None):
+        self.p = int(p)
+        self.m = 1 << self.p
+        self.registers = registers if registers is not None else np.zeros(self.m, dtype=np.uint8)
+
+    def add_ids(self, ids: np.ndarray) -> None:
+        if ids.size == 0:
+            return
+        h = _hash64(np.asarray(ids))
+        reg_idx = (h >> np.uint64(64 - self.p)).astype(np.int64)
+        rest = (h << np.uint64(self.p)) | np.uint64((1 << self.p) - 1)
+        # rank = leading zeros of the remaining bits + 1
+        ranks = np.zeros(ids.shape, dtype=np.uint8)
+        remaining = rest.copy()
+        # 64-bit leading-zero count via float log2 is unsafe; loop over 64 bits max via vector ops
+        lz = np.full(ids.shape, 64, dtype=np.int64)
+        nonzero = remaining != 0
+        # bit_length via log2 on uint64 split into hi/lo 32-bit halves (exact for ints < 2^53 per half)
+        hi = (remaining >> np.uint64(32)).astype(np.float64)
+        lo = (remaining & np.uint64(0xFFFFFFFF)).astype(np.float64)
+        bl = np.zeros(ids.shape, dtype=np.int64)
+        hi_nz = hi > 0
+        bl[hi_nz] = 32 + np.floor(np.log2(hi[hi_nz])).astype(np.int64) + 1
+        lo_only = (~hi_nz) & (lo > 0)
+        bl[lo_only] = np.floor(np.log2(lo[lo_only])).astype(np.int64) + 1
+        lz[nonzero] = 64 - bl[nonzero]
+        ranks = np.minimum(lz + 1, 64 - self.p + 1).astype(np.uint8)
+        np.maximum.at(self.registers, reg_idx, ranks)
+
+    def merge(self, other: "HyperLogLog") -> "HyperLogLog":
+        assert self.p == other.p
+        return HyperLogLog(self.p, np.maximum(self.registers, other.registers))
+
+    def estimate(self) -> float:
+        m = float(self.m)
+        alpha = 0.7213 / (1.0 + 1.079 / m)
+        inv_sum = np.sum(np.exp2(-self.registers.astype(np.float64)))
+        raw = alpha * m * m / inv_sum
+        zeros = int(np.sum(self.registers == 0))
+        if raw <= 2.5 * m and zeros > 0:  # small-range correction
+            return m * np.log(m / zeros)
+        return float(raw)
+
+
+# ---------------------------------------------------------------- reservoir sample
+
+
+class Reservoir:
+    """Uniform reservoir sample of ids (exemplars for drill-down)."""
+
+    def __init__(self, k: int = 200, seed: int = 0):
+        self.k = int(k)
+        self.rng = np.random.default_rng(seed)
+        self.items: List[int] = []
+        self.seen = 0
+
+    def add_ids(self, ids: np.ndarray) -> None:
+        for v in np.asarray(ids).tolist():
+            self.seen += 1
+            if len(self.items) < self.k:
+                self.items.append(int(v))
+            else:
+                j = int(self.rng.integers(0, self.seen))
+                if j < self.k:
+                    self.items[j] = int(v)
+
+    def merge(self, other: "Reservoir") -> "Reservoir":
+        merged = Reservoir(self.k, seed=self.seen + other.seen + 1)
+        pool = self.items + other.items
+        merged.seen = self.seen + other.seen
+        if len(pool) <= self.k:
+            merged.items = pool
+        else:
+            idx = merged.rng.choice(len(pool), size=self.k, replace=False)
+            merged.items = [pool[i] for i in idx]
+        return merged

src/App.tsx

@@ -11,6 +11,7 @@ import ListSubheader from '@mui/material/ListSubheader';
 import Toolbar from '@mui/material/Toolbar';
 import Typography from '@mui/material/Typography';
 import {
+  Gauge,
   LayoutDashboard,
   Database,
   Tag,
@@ -44,6 +45,7 @@ import AuditPage from './pages/AuditPage';
 import PipelineArchitecturePage from './pages/PipelineArchitecturePage';
 import SSAMSafetyDashboard from './pages/SSAMSafetyDashboard';
 import LegacyStudioPage from './pages/LegacyStudioPage';
+import CommandCenterPage from './pages/CommandCenterPage';
 
 const DRAWER_WIDTH = 230;
 
@@ -54,6 +56,7 @@ interface NavItem {
 }
 
 const PLATFORM_NAV: NavItem[] = [
+  { id: 'command', label: 'Command Center', icon: <Gauge size={18} /> },
   { id: 'overview', label: 'Overview', icon: <LayoutDashboard size={18} /> },
   { id: 'datasets', label: 'Datasets', icon: <Database size={18} /> },
   { id: 'label-generation', label: 'Label Generation', icon: <Tag size={18} /> },
@@ -75,6 +78,7 @@ const LEGACY_NAV: NavItem[] = [
 ];
 
 const PAGE_TITLES: Record<PageId, string> = {
+  command: 'Evaluation Command Center',
   overview: 'Overview',
   datasets: 'Datasets',
   'label-generation': 'Label Generation',
@@ -95,7 +99,7 @@ const PAGE_TITLES: Record<PageId, string> = {
 function parseHash(): { page: PageId; entityId: string | null } {
   const raw = window.location.hash.replace(/^#\/?/, '');
   const [pageRaw, entityRaw] = raw.split('/');
-  const page = (ALL_PAGE_IDS as string[]).includes(pageRaw ?? '') ? (pageRaw as PageId) : 'overview';
+  const page = (ALL_PAGE_IDS as string[]).includes(pageRaw ?? '') ? (pageRaw as PageId) : 'command';
   return { page, entityId: entityRaw ? decodeURIComponent(entityRaw) : null };
 }
 
@@ -268,6 +272,7 @@ export default function App() {
               <Typography variant="h5" sx={{ fontWeight: 800, mb: 2 }}>
                 {PAGE_TITLES[page]}
               </Typography>
+              {page === 'command' ? <CommandCenterPage /> : null}
               {page === 'overview' ? <OverviewPage /> : null}
               {page === 'datasets' ? <DatasetsPage /> : null}
               {page === 'label-generation' ? <LabelGenerationPage /> : null}

src/components/megaeval/CohortTab.tsx

@@ -0,0 +1,266 @@
+/**
+ * Cohort explorer: pick a dimension tab, click a cohort value to drill —
+ * the value becomes a filter breadcrumb (e.g. Pedestrian → Night → Occluded)
+ * and the next level groups by the newly selected dimension. Every node shows
+ * cube metrics via POST /api/evaluations/query. "Why?" runs the factor
+ * decomposition for the current filter set.
+ */
+import { useMemo, useState } from 'react';
+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 Tab from '@mui/material/Tab';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import Tabs from '@mui/material/Tabs';
+import Typography from '@mui/material/Typography';
+import { HelpCircle, ChevronRight } from 'lucide-react';
+import type { DimName, WhyResponse } from '../../types/megaeval';
+import { DIM_NAMES } from '../../types/megaeval';
+import { fmtCompact, queryEvaluations, whyAnalysis } from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { ErrorNote, HBar, LoadingBox, SectionCard, fmtNum, fmtPct } from '../labeleval/shared';
+import { PctBarCell, QueryBadge, rowNum, rowStr } from './shared';
+
+interface Crumb {
+  dim: DimName;
+  value: string;
+}
+
+function crumbsToFilters(crumbs: Crumb[]): Partial<Record<DimName, string[]>> {
+  const filters: Partial<Record<DimName, string[]>> = {};
+  for (const c of crumbs) {
+    filters[c.dim] = [...(filters[c.dim] ?? []), c.value];
+  }
+  return filters;
+}
+
+function WhyPanel({ why }: { why: WhyResponse }) {
+  const maxCohortN = Math.max(1, ...why.top_cohorts.map((c) => c.n));
+  return (
+    <SectionCard
+      title={`Why is ${why.metric} degraded here?`}
+      sx={{ flex: '1 1 340px', borderColor: '#4a3b12' }}
+    >
+      <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1 }}>
+        {fmtCompact(why.failure_count)} failures decomposed · {why.method}
+      </Typography>
+      {why.factors.map((f) => (
+        <HBar
+          key={f.factor}
+          label={f.factor.replace(/_/g, ' ')}
+          value={f.share <= 1 ? f.share * 100 : f.share}
+          max={100}
+          color="#ffd54f"
+          valueLabel={`${fmtPct(f.share)} (${fmtCompact(f.count)})`}
+        />
+      ))}
+      {why.top_cohorts.length ? (
+        <>
+          <Typography variant="caption" sx={{ color: '#aab4be', display: 'block', mt: 1.5, mb: 0.5 }}>
+            Top affected cohorts
+          </Typography>
+          {why.top_cohorts.map((c) => (
+            <HBar
+              key={c.cohort}
+              label={c.cohort}
+              value={c.n}
+              max={maxCohortN}
+              color="#ef5350"
+              valueLabel={`n=${fmtCompact(c.n)}${c.fn !== undefined && c.fn !== null ? ` · fn=${fmtCompact(c.fn)}` : ''}${
+                c.fp !== undefined && c.fp !== null ? ` · fp=${fmtCompact(c.fp)}` : ''
+              }`}
+            />
+          ))}
+        </>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+export default function CohortTab({ runId, refreshKey }: { runId: string; refreshKey: number }) {
+  const [crumbs, setCrumbs] = useState<Crumb[]>([]);
+  const [dim, setDim] = useState<DimName>('class');
+  const [why, setWhy] = useState<WhyResponse | null>(null);
+  const [whyBusy, setWhyBusy] = useState(false);
+  const [whyError, setWhyError] = useState<string | null>(null);
+
+  const filters = useMemo(() => crumbsToFilters(crumbs), [crumbs]);
+  const filtersKey = JSON.stringify(filters);
+
+  const query = usePoll(
+    () =>
+      queryEvaluations({
+        evaluation_id: runId,
+        filters,
+        group_by: [dim],
+        metrics: ['n', 'recall', 'precision', 'mean_iou', 'anomaly_rate'],
+      }),
+    null,
+    [runId, refreshKey, dim, filtersKey]
+  );
+
+  const usedDims = new Set(crumbs.map((c) => c.dim));
+
+  const drillInto = (value: string) => {
+    const next = [...crumbs, { dim, value }];
+    setCrumbs(next);
+    setWhy(null);
+    // Auto-advance the group-by dimension to the next unused one.
+    const nextUsed = new Set(next.map((c) => c.dim));
+    const nextDim = DIM_NAMES.find((d) => !nextUsed.has(d));
+    if (nextDim) setDim(nextDim);
+  };
+
+  const removeCrumb = (idx: number) => {
+    setCrumbs((prev) => prev.filter((_, i) => i !== idx));
+    setWhy(null);
+  };
+
+  const runWhy = async () => {
+    setWhyBusy(true);
+    setWhyError(null);
+    try {
+      setWhy(await whyAnalysis({ run_id: runId, filters, metric: 'recall' }));
+    } catch (err) {
+      setWhyError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setWhyBusy(false);
+    }
+  };
+
+  const rows = useMemo(
+    () =>
+      query.data
+        ? // usePoll keeps the previous response while a new query is in flight;
+          // drop rows that don't carry the currently-selected dimension so stale
+          // groupings never render (and never collide on duplicate row keys).
+          query.data.rows
+            .filter((r) => typeof r[dim] === 'string')
+            .sort((a, b) => b.n - a.n)
+        : [],
+    [query.data, dim]
+  );
+
+  return (
+    <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+      <SectionCard
+        title="Cohort explorer"
+        action={
+          <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+            <QueryBadge meta={query.data?.meta} />
+            <Button
+              size="small"
+              variant="outlined"
+              color="warning"
+              startIcon={whyBusy ? <CircularProgress size={14} color="inherit" /> : <HelpCircle size={14} />}
+              disabled={crumbs.length === 0 || whyBusy}
+              onClick={() => void runWhy()}
+            >
+              Why?
+            </Button>
+          </Box>
+        }
+        sx={{ flex: '2 1 560px' }}
+      >
+        {/* Filter breadcrumb */}
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5, flexWrap: 'wrap', mb: 1 }}>
+          <Chip
+            size="small"
+            label="All objects"
+            onClick={() => {
+              setCrumbs([]);
+              setWhy(null);
+            }}
+            sx={{ height: 22, bgcolor: crumbs.length ? '#232a31' : '#12303f', color: '#81d4fa', fontWeight: 700 }}
+          />
+          {crumbs.map((c, i) => (
+            <Box key={`${c.dim}-${c.value}-${i}`} sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+              <ChevronRight size={13} color="#8a949e" />
+              <Chip
+                size="small"
+                label={`${c.dim}: ${c.value}`}
+                onDelete={() => removeCrumb(i)}
+                sx={{ height: 22, bgcolor: '#12303f', color: '#81d4fa', fontFamily: 'monospace', fontSize: 11 }}
+              />
+            </Box>
+          ))}
+        </Box>
+
+        {/* Dimension tabs */}
+        <Tabs
+          value={dim}
+          onChange={(_, v: DimName) => setDim(v)}
+          variant="scrollable"
+          scrollButtons="auto"
+          sx={{ minHeight: 32, mb: 1, '& .MuiTab-root': { minHeight: 32, py: 0.5, fontSize: 12 } }}
+        >
+          {DIM_NAMES.map((d) => (
+            <Tab key={d} label={d.replace(/_/g, ' ')} value={d} disabled={usedDims.has(d)} />
+          ))}
+        </Tabs>
+
+        {query.error ? <ErrorNote error={query.error} /> : null}
+        {query.loading && !query.data ? <LoadingBox /> : null}
+        {query.data ? (
+          <Table size="small">
+            <TableHead>
+              <TableRow>
+                <TableCell>{dim.replace(/_/g, ' ')}</TableCell>
+                <TableCell align="right">n</TableCell>
+                <TableCell>Recall</TableCell>
+                <TableCell>Precision</TableCell>
+                <TableCell align="right">Mean IoU</TableCell>
+                <TableCell align="right">Anomaly rate</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {rows.map((row, i) => {
+                const value = rowStr(row, dim);
+                return (
+                  <TableRow
+                    key={`${value}-${i}`}
+                    hover
+                    onClick={() => drillInto(value)}
+                    sx={{ cursor: 'pointer' }}
+                  >
+                    <TableCell sx={{ fontWeight: 600, color: '#4fc3f7' }}>{value}</TableCell>
+                    <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                      {fmtCompact(row.n)}
+                    </TableCell>
+                    <TableCell>
+                      <PctBarCell value={rowNum(row, 'recall')} color="#66bb6a" />
+                    </TableCell>
+                    <TableCell>
+                      <PctBarCell value={rowNum(row, 'precision')} color="#4fc3f7" />
+                    </TableCell>
+                    <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                      {fmtNum(rowNum(row, 'mean_iou'), 3)}
+                    </TableCell>
+                    <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                      {fmtPct(rowNum(row, 'anomaly_rate'))}
+                    </TableCell>
+                  </TableRow>
+                );
+              })}
+            </TableBody>
+          </Table>
+        ) : null}
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1 }}>
+          Click a row to drill into that cohort; the next level groups by the selected dimension tab.
+        </Typography>
+      </SectionCard>
+
+      {whyError ? (
+        <Box sx={{ flex: '1 1 340px' }}>
+          <ErrorNote error={whyError} />
+        </Box>
+      ) : null}
+      {why ? <WhyPanel why={why} /> : null}
+    </Box>
+  );
+}

src/components/megaeval/CompareTab.tsx

@@ -0,0 +1,221 @@
+/**
+ * Model-vs-model comparison: candidate (selected run) against the baseline
+ * chosen in the header. Headline deltas, per-class deltas, top regressions,
+ * and the PROMOTE / DO_NOT_PROMOTE recommendation with blockers.
+ */
+import Alert from '@mui/material/Alert';
+import AlertTitle from '@mui/material/AlertTitle';
+import Box from '@mui/material/Box';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import Typography from '@mui/material/Typography';
+import { compareRuns, fmtCompact } from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { ErrorNote, LoadingBox, SectionCard, fmtPct } from '../labeleval/shared';
+import { DeltaText } from './shared';
+
+/** Metrics where a positive delta is a regression rather than an improvement. */
+const LOWER_IS_BETTER = new Set(['anomaly_rate', 'error_rate', 'fp', 'fn', 'loc_err', 'anomalies']);
+
+function fmtMetricValue(v: number): string {
+  // Rates arrive as fractions; counts as integers > 1.
+  return Math.abs(v) <= 1 ? fmtPct(v) : fmtCompact(v);
+}
+
+export default function CompareTab({
+  runId,
+  baselineRunId,
+  refreshKey,
+}: {
+  runId: string;
+  baselineRunId: string | null;
+  refreshKey: number;
+}) {
+  const cmp = usePoll(
+    () =>
+      baselineRunId
+        ? compareRuns({ candidate_run_id: runId, baseline_run_id: baselineRunId })
+        : Promise.resolve(null),
+    null,
+    [runId, baselineRunId, refreshKey]
+  );
+
+  if (!baselineRunId) {
+    return (
+      <Alert severity="info" variant="outlined">
+        Select a <strong>baseline run</strong> in the header to compare the current candidate against it.
+      </Alert>
+    );
+  }
+  if (cmp.error) return <ErrorNote error={cmp.error} />;
+  if (cmp.loading && !cmp.data) return <LoadingBox label="Comparing runs…" />;
+  const data = cmp.data;
+  if (!data) return null;
+
+  const promote = data.recommendation === 'PROMOTE';
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <Alert severity={promote ? 'success' : 'error'} variant="filled" sx={{ fontWeight: 700 }}>
+        <AlertTitle sx={{ fontWeight: 800 }}>
+          {promote ? 'PROMOTE' : 'DO NOT PROMOTE'} — {data.candidate.model_version} vs baseline{' '}
+          {data.baseline.model_version}
+        </AlertTitle>
+        {data.blockers.length ? (
+          <Box component="ul" sx={{ m: 0, pl: 2.5 }}>
+            {data.blockers.map((b, i) => (
+              <li key={i}>
+                <Typography variant="body2">{b}</Typography>
+              </li>
+            ))}
+          </Box>
+        ) : (
+          <Typography variant="body2">No blockers under the current promotion policy.</Typography>
+        )}
+      </Alert>
+
+      <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+        <SectionCard title="Headline deltas" sx={{ flex: '1 1 380px' }}>
+          <Table size="small">
+            <TableHead>
+              <TableRow>
+                <TableCell>Metric</TableCell>
+                <TableCell align="right">Baseline</TableCell>
+                <TableCell align="right">Candidate</TableCell>
+                <TableCell align="right">Δ</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {data.headline_deltas.map((d) => (
+                <TableRow key={d.metric} hover>
+                  <TableCell sx={{ fontFamily: 'monospace' }}>{d.metric}</TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtMetricValue(d.baseline)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtMetricValue(d.candidate)}
+                  </TableCell>
+                  <TableCell align="right">
+                    <DeltaText
+                      delta={d.delta}
+                      higherIsBetter={!LOWER_IS_BETTER.has(d.metric)}
+                      asPct={Math.abs(d.baseline) <= 1 && Math.abs(d.candidate) <= 1}
+                    />
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </SectionCard>
+
+        <SectionCard title="Per-class deltas" sx={{ flex: '1 1 480px' }}>
+          <Table size="small">
+            <TableHead>
+              <TableRow>
+                <TableCell>Class</TableCell>
+                <TableCell align="right">n</TableCell>
+                <TableCell align="right">Recall</TableCell>
+                <TableCell align="right">Δ recall</TableCell>
+                <TableCell align="right">Precision</TableCell>
+                <TableCell align="right">Δ precision</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {data.per_class.map((c) => (
+                <TableRow key={c.class} hover>
+                  <TableCell sx={{ fontWeight: 600 }}>{c.class}</TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtCompact(c.n)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(c.recall_baseline)} → {fmtPct(c.recall_candidate)}
+                  </TableCell>
+                  <TableCell align="right">
+                    <DeltaText delta={c.recall_delta} />
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(c.precision_baseline)} → {fmtPct(c.precision_candidate)}
+                  </TableCell>
+                  <TableCell align="right">
+                    <DeltaText delta={c.precision_delta} />
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </SectionCard>
+      </Box>
+
+      <SectionCard title={`Top regressions (${data.regressions.length})`}>
+        {data.regressions.length === 0 ? (
+          <Typography variant="body2" sx={{ color: '#8a949e' }}>
+            No cohort regressions detected against the baseline.
+          </Typography>
+        ) : (
+          <Box sx={{ display: 'flex', flexDirection: 'column', gap: 0.75 }}>
+            {data.regressions.map((r) => (
+              <Box
+                key={r.cohort}
+                sx={{
+                  p: 1,
+                  border: '1px solid #5c1a1a',
+                  bgcolor: '#2a1214',
+                  borderRadius: 1,
+                  display: 'flex',
+                  alignItems: 'center',
+                  gap: 1,
+                  flexWrap: 'wrap',
+                }}
+              >
+                <Typography variant="body2" sx={{ fontWeight: 700, color: '#ef9a9a' }}>
+                  🚨 REGRESSION:
+                </Typography>
+                <Typography variant="body2" sx={{ fontFamily: 'monospace' }}>
+                  {r.cohort} recall {fmtPct(r.recall_baseline)} → {fmtPct(r.recall_candidate)} (Δ{' '}
+                  <DeltaText delta={r.recall_delta} />)
+                </Typography>
+                <Typography variant="caption" sx={{ color: '#8a949e', ml: 'auto', fontFamily: 'monospace' }}>
+                  n={fmtCompact(r.n)}
+                </Typography>
+              </Box>
+            ))}
+          </Box>
+        )}
+      </SectionCard>
+
+      {data.worst_cohorts.length ? (
+        <SectionCard title="Worst cohorts (candidate)">
+          <Table size="small">
+            <TableHead>
+              <TableRow>
+                <TableCell>Cohort</TableCell>
+                <TableCell align="right">n</TableCell>
+                <TableCell align="right">Recall (baseline → candidate)</TableCell>
+                <TableCell align="right">Δ</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {data.worst_cohorts.map((c) => (
+                <TableRow key={c.cohort} hover>
+                  <TableCell sx={{ fontFamily: 'monospace' }}>{c.cohort}</TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtCompact(c.n)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(c.recall_baseline)} → {fmtPct(c.recall_candidate)}
+                  </TableCell>
+                  <TableCell align="right">
+                    <DeltaText delta={c.recall_delta} />
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </SectionCard>
+      ) : null}
+    </Box>
+  );
+}

src/components/megaeval/ContainersTab.tsx

@@ -0,0 +1,321 @@
+/**
+ * Container explorer ("Quality by Container"): sortable container table with
+ * risk presets. Drilling into a container opens the forensic object table —
+ * intentionally the deepest level of the app — plus nearest-neighbor
+ * "similar containers" retrieval for casting a wider net.
+ */
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import CircularProgress from '@mui/material/CircularProgress';
+import MenuItem from '@mui/material/MenuItem';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import TextField from '@mui/material/TextField';
+import Typography from '@mui/material/Typography';
+import { ArrowLeft, Search, ShieldAlert } from 'lucide-react';
+import type { ContainerSortPreset, SimilarityResponse } from '../../types/megaeval';
+import {
+  findSimilarContainers,
+  fmtCompact,
+  getContainerObjects,
+  getRunContainers,
+} from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { ErrorNote, LoadingBox, SectionCard, fmtNum, fmtPct } from '../labeleval/shared';
+import { ContainerStatusIcon, DimChips, OutcomeChip } from './shared';
+
+const SORT_PRESETS: Array<{ value: ContainerSortPreset; label: string }> = [
+  { value: 'highest_risk', label: 'Highest risk' },
+  { value: 'worst_recall', label: 'Worst recall' },
+  { value: 'worst_precision', label: 'Worst precision' },
+  { value: 'worst_iou', label: 'Worst IoU' },
+  { value: 'most_anomalies', label: 'Most anomalies' },
+  { value: 'least_verified', label: 'Least verified' },
+];
+
+// ---------------------------------------------------------------- forensic view
+
+function ForensicView({
+  runId,
+  containerId,
+  onBack,
+  onDrill,
+}: {
+  runId: string;
+  containerId: number;
+  onBack: () => void;
+  onDrill: (cid: number) => void;
+}) {
+  const objects = usePoll(() => getContainerObjects(runId, containerId), null, [runId, containerId]);
+  const [similar, setSimilar] = useState<SimilarityResponse | null>(null);
+  const [simBusy, setSimBusy] = useState(false);
+  const [simError, setSimError] = useState<string | null>(null);
+
+  const findSimilar = async () => {
+    setSimBusy(true);
+    setSimError(null);
+    try {
+      setSimilar(await findSimilarContainers({ run_id: runId, container_id: containerId, k: 10 }));
+    } catch (err) {
+      setSimError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setSimBusy(false);
+    }
+  };
+
+  return (
+    <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+      <SectionCard
+        title={
+          <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+            <Button size="small" startIcon={<ArrowLeft size={14} />} onClick={onBack}>
+              Containers
+            </Button>
+            <span>Forensic object table · container #{containerId}</span>
+          </Box>
+        }
+        action={
+          <Button
+            size="small"
+            variant="outlined"
+            startIcon={simBusy ? <CircularProgress size={14} color="inherit" /> : <Search size={14} />}
+            disabled={simBusy}
+            onClick={() => void findSimilar()}
+          >
+            Find similar containers
+          </Button>
+        }
+        sx={{ flex: '2 1 620px' }}
+      >
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1 }}>
+          Deepest drill-down level: individual annotations, loaded on demand for this container only.
+        </Typography>
+        {objects.error ? <ErrorNote error={objects.error} /> : null}
+        {objects.loading && !objects.data ? <LoadingBox /> : null}
+        {objects.data ? (
+          <Box sx={{ maxHeight: 460, overflowY: 'auto' }}>
+            <Table size="small" stickyHeader>
+              <TableHead>
+                <TableRow>
+                  <TableCell>Outcome</TableCell>
+                  <TableCell>Class</TableCell>
+                  <TableCell align="right">IoU</TableCell>
+                  <TableCell align="right">Conf</TableCell>
+                  <TableCell align="center">Anomaly</TableCell>
+                  <TableCell>Dims</TableCell>
+                </TableRow>
+              </TableHead>
+              <TableBody>
+                {objects.data.objects.map((o) => (
+                  <TableRow key={o.annotation_id} hover>
+                    <TableCell>
+                      <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+                        <OutcomeChip outcome={o.outcome} />
+                        {o.safety_critical ? <ShieldAlert size={14} color="#ef5350" /> : null}
+                      </Box>
+                    </TableCell>
+                    <TableCell sx={{ fontWeight: 600 }}>{o.class}</TableCell>
+                    <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                      {fmtNum(o.iou, 3)}
+                    </TableCell>
+                    <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                      {fmtNum(o.confidence, 2)}
+                    </TableCell>
+                    <TableCell align="center">
+                      {o.anomaly ? (
+                        <Typography component="span" sx={{ color: '#ec407a', fontSize: 13 }}>
+                          ●
+                        </Typography>
+                      ) : (
+                        <Typography component="span" sx={{ color: '#37474f', fontSize: 13 }}>
+                          ○
+                        </Typography>
+                      )}
+                    </TableCell>
+                    <TableCell>
+                      <DimChips
+                        values={[
+                          o.weather,
+                          o.lighting,
+                          o.scenario,
+                          o.sensor,
+                          o.distance_band,
+                          o.occlusion,
+                          o.sensor_disagree ? 'sensor-disagree' : undefined,
+                        ]}
+                      />
+                    </TableCell>
+                  </TableRow>
+                ))}
+              </TableBody>
+            </Table>
+          </Box>
+        ) : null}
+      </SectionCard>
+
+      {simError ? (
+        <Box sx={{ flex: '1 1 340px' }}>
+          <ErrorNote error={simError} />
+        </Box>
+      ) : null}
+      {similar ? (
+        <SectionCard
+          title={`Similar containers${similar.retrieval ? ` · ${similar.retrieval}` : ''}`}
+          sx={{ flex: '1 1 380px' }}
+        >
+          <Table size="small">
+            <TableHead>
+              <TableRow>
+                <TableCell>Container</TableCell>
+                <TableCell align="right">Similarity</TableCell>
+                <TableCell>Context</TableCell>
+                <TableCell align="right">FN/FP</TableCell>
+                <TableCell align="right">Risk</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {similar.results.map((s) => (
+                <TableRow key={s.container_id} hover onClick={() => onDrill(s.container_id)} sx={{ cursor: 'pointer' }}>
+                  <TableCell sx={{ fontFamily: 'monospace', color: '#4fc3f7' }}>#{s.container_id}</TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(s.similarity)}
+                  </TableCell>
+                  <TableCell>
+                    <DimChips values={[s.scenario, s.lighting, s.weather]} />
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {s.fn}/{s.fp}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtNum(s.risk_score, 2)}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </SectionCard>
+      ) : null}
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------- containers table
+
+export default function ContainersTab({
+  runId,
+  refreshKey,
+  drillContainerId,
+  onDrill,
+}: {
+  runId: string;
+  refreshKey: number;
+  drillContainerId: number | null;
+  onDrill: (cid: number | null) => void;
+}) {
+  const [sort, setSort] = useState<ContainerSortPreset>('highest_risk');
+  const containers = usePoll(() => getRunContainers(runId, sort, 50), null, [runId, sort, refreshKey]);
+
+  if (drillContainerId !== null) {
+    return (
+      <ForensicView
+        runId={runId}
+        containerId={drillContainerId}
+        onBack={() => onDrill(null)}
+        onDrill={(cid) => onDrill(cid)}
+      />
+    );
+  }
+
+  return (
+    <SectionCard
+      title="Quality by container"
+      action={
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+          {containers.data ? (
+            <Typography variant="caption" sx={{ color: '#8a949e' }}>
+              {fmtCompact(containers.data.total)} containers (exact) · showing top {containers.data.rows.length}
+            </Typography>
+          ) : null}
+          <TextField
+            select
+            size="small"
+            label="Sort"
+            value={sort}
+            onChange={(e) => setSort(e.target.value as ContainerSortPreset)}
+            sx={{ minWidth: 180 }}
+          >
+            {SORT_PRESETS.map((p) => (
+              <MenuItem key={p.value} value={p.value}>
+                {p.label}
+              </MenuItem>
+            ))}
+          </TextField>
+        </Box>
+      }
+    >
+      {containers.error ? <ErrorNote error={containers.error} /> : null}
+      {containers.loading && !containers.data ? <LoadingBox /> : null}
+      {containers.data ? (
+        <Box sx={{ maxHeight: 520, overflowY: 'auto' }}>
+          <Table size="small" stickyHeader>
+            <TableHead>
+              <TableRow>
+                <TableCell />
+                <TableCell>Container</TableCell>
+                <TableCell>Context</TableCell>
+                <TableCell align="right">Objects</TableCell>
+                <TableCell align="right">Verified</TableCell>
+                <TableCell align="right">Precision</TableCell>
+                <TableCell align="right">Recall</TableCell>
+                <TableCell align="right">Mean IoU</TableCell>
+                <TableCell align="right">Anomalies</TableCell>
+                <TableCell align="right">Risk</TableCell>
+              </TableRow>
+            </TableHead>
+            <TableBody>
+              {containers.data.rows.map((c) => (
+                <TableRow key={c.container_id} hover onClick={() => onDrill(c.container_id)} sx={{ cursor: 'pointer' }}>
+                  <TableCell sx={{ width: 30 }}>
+                    <ContainerStatusIcon status={c.status} />
+                  </TableCell>
+                  <TableCell sx={{ fontFamily: 'monospace', color: '#4fc3f7' }}>#{c.container_id}</TableCell>
+                  <TableCell>
+                    <DimChips values={[c.scenario, c.lighting, c.weather, c.road_type]} />
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtCompact(c.n_objects)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {c.verified}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(c.precision)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(c.recall)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtNum(c.mean_iou, 3)}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace', color: c.anomalies > 0 ? '#ec407a' : undefined }}>
+                    {c.anomalies}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtNum(c.risk_score, 2)}
+                  </TableCell>
+                </TableRow>
+              ))}
+            </TableBody>
+          </Table>
+        </Box>
+      ) : null}
+      <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1 }}>
+        Click a container to open its forensic object table (deepest drill-down).
+      </Typography>
+    </SectionCard>
+  );
+}

src/components/megaeval/HeaderBar.tsx

@@ -0,0 +1,335 @@
+/**
+ * Command Center header: population + run + baseline selectors, run status,
+ * cache stats chip, and the two entry-point actions (generate population,
+ * launch evaluation run). The action buttons are exported so the page-level
+ * empty state can reuse them front and center.
+ */
+import { 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 Dialog from '@mui/material/Dialog';
+import DialogActions from '@mui/material/DialogActions';
+import DialogContent from '@mui/material/DialogContent';
+import DialogTitle from '@mui/material/DialogTitle';
+import FormControlLabel from '@mui/material/FormControlLabel';
+import MenuItem from '@mui/material/MenuItem';
+import Switch from '@mui/material/Switch';
+import TextField from '@mui/material/TextField';
+import Tooltip from '@mui/material/Tooltip';
+import Typography from '@mui/material/Typography';
+import { Database, FlaskConical } from 'lucide-react';
+import type { CacheStats, EvaluationRunInfo, PopulationMeta } from '../../types/megaeval';
+import { createRun, fmtCompact, generatePopulation } from '../../services/megaeval';
+import { fmtPct } from '../labeleval/shared';
+import { RunStatusChip } from './shared';
+
+// ---------------------------------------------------------------- action buttons
+
+export function GeneratePopulationButton({
+  onGenerated,
+  variant = 'outlined',
+  size = 'small',
+}: {
+  onGenerated: (pop: PopulationMeta) => void;
+  variant?: 'outlined' | 'contained';
+  size?: 'small' | 'medium' | 'large';
+}) {
+  const [open, setOpen] = useState(false);
+  const [numObjects, setNumObjects] = useState('320000');
+  const [name, setName] = useState('');
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const submit = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const parsed = Number(numObjects);
+      const pop = await generatePopulation({
+        ...(name.trim() ? { name: name.trim() } : {}),
+        num_objects: Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : 320000,
+      });
+      setOpen(false);
+      onGenerated(pop);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <Button variant={variant} size={size} startIcon={<Database size={16} />} onClick={() => setOpen(true)}>
+        Generate population
+      </Button>
+      <Dialog open={open} onClose={() => (busy ? undefined : setOpen(false))} maxWidth="xs" fullWidth>
+        <DialogTitle>Generate evaluation population</DialogTitle>
+        <DialogContent sx={{ display: 'flex', flexDirection: 'column', gap: 2, pt: '12px !important' }}>
+          {error ? (
+            <Alert severity="error" variant="outlined">
+              {error}
+            </Alert>
+          ) : null}
+          <TextField
+            label="Name (optional)"
+            size="small"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            placeholder="e.g. q3-highway-mix"
+          />
+          <TextField
+            label="Objects"
+            size="small"
+            type="number"
+            value={numObjects}
+            onChange={(e) => setNumObjects(e.target.value)}
+            helperText="1K – 1.2M synthetic annotated objects (default 320K)"
+          />
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={() => setOpen(false)} disabled={busy}>
+            Cancel
+          </Button>
+          <Button
+            variant="contained"
+            onClick={() => void submit()}
+            disabled={busy}
+            startIcon={busy ? <CircularProgress size={16} color="inherit" /> : <Database size={16} />}
+          >
+            {busy ? 'Generating…' : 'Generate'}
+          </Button>
+        </DialogActions>
+      </Dialog>
+    </>
+  );
+}
+
+export function NewRunButton({
+  populationId,
+  onCreated,
+  variant = 'contained',
+  size = 'small',
+}: {
+  populationId: string | null;
+  onCreated: (run: EvaluationRunInfo) => void;
+  variant?: 'outlined' | 'contained';
+  size?: 'small' | 'medium' | 'large';
+}) {
+  const [open, setOpen] = useState(false);
+  const [modelVersion, setModelVersion] = useState('perception-v2.1');
+  const [injectRegression, setInjectRegression] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const submit = async () => {
+    if (!populationId) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const run = await createRun({
+        population_id: populationId,
+        model_version: modelVersion.trim() || 'perception-v2.1',
+        ...(injectRegression ? { overrides: { night_penalty: 0.3, vru_penalty: 0.1 } } : {}),
+      });
+      setOpen(false);
+      onCreated(run);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <>
+      <Tooltip title={populationId ? '' : 'Generate a population first'}>
+        <span>
+          <Button
+            variant={variant}
+            size={size}
+            startIcon={<FlaskConical size={16} />}
+            disabled={!populationId}
+            onClick={() => setOpen(true)}
+          >
+            New evaluation run
+          </Button>
+        </span>
+      </Tooltip>
+      <Dialog open={open} onClose={() => (busy ? undefined : setOpen(false))} maxWidth="xs" fullWidth>
+        <DialogTitle>Launch evaluation run</DialogTitle>
+        <DialogContent sx={{ display: 'flex', flexDirection: 'column', gap: 2, pt: '12px !important' }}>
+          {error ? (
+            <Alert severity="error" variant="outlined">
+              {error}
+            </Alert>
+          ) : null}
+          <TextField
+            label="Model version"
+            size="small"
+            value={modelVersion}
+            onChange={(e) => setModelVersion(e.target.value)}
+          />
+          <FormControlLabel
+            control={
+              <Switch checked={injectRegression} onChange={(e) => setInjectRegression(e.target.checked)} />
+            }
+            label={
+              <Box>
+                <Typography variant="body2">Inject regression (demo)</Typography>
+                <Typography variant="caption" sx={{ color: '#8a949e' }}>
+                  Applies overrides night_penalty=0.30, vru_penalty=0.10
+                </Typography>
+              </Box>
+            }
+          />
+          <Typography variant="caption" sx={{ color: '#8a949e' }}>
+            Runs are asynchronous: the run is queued, evaluated across distributed workers, then published.
+          </Typography>
+        </DialogContent>
+        <DialogActions>
+          <Button onClick={() => setOpen(false)} disabled={busy}>
+            Cancel
+          </Button>
+          <Button
+            variant="contained"
+            onClick={() => void submit()}
+            disabled={busy || !populationId}
+            startIcon={busy ? <CircularProgress size={16} color="inherit" /> : <FlaskConical size={16} />}
+          >
+            {busy ? 'Queueing…' : 'Launch run'}
+          </Button>
+        </DialogActions>
+      </Dialog>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------- header bar
+
+export default function HeaderBar({
+  populations,
+  populationId,
+  onPopulationChange,
+  runs,
+  runId,
+  onRunChange,
+  baselineRunId,
+  onBaselineChange,
+  selectedRun,
+  cache,
+  onGenerated,
+  onRunCreated,
+}: {
+  populations: PopulationMeta[];
+  populationId: string | null;
+  onPopulationChange: (id: string) => void;
+  runs: EvaluationRunInfo[];
+  runId: string | null;
+  onRunChange: (id: string) => void;
+  baselineRunId: string | null;
+  onBaselineChange: (id: string | null) => void;
+  selectedRun: EvaluationRunInfo | null;
+  cache: CacheStats | null;
+  onGenerated: (pop: PopulationMeta) => void;
+  onRunCreated: (run: EvaluationRunInfo) => void;
+}) {
+  const sortedRuns = useMemo(
+    () => [...runs].sort((a, b) => (b.created_at ?? '').localeCompare(a.created_at ?? '')),
+    [runs]
+  );
+  const publishedRuns = useMemo(() => sortedRuns.filter((r) => r.status === 'published'), [sortedRuns]);
+
+  const runLabel = (r: EvaluationRunInfo) =>
+    `${r.model_version} · ${r.run_id.slice(0, 8)}${r.status === 'published' ? '' : ` (${r.status})`}`;
+
+  return (
+    <Box
+      sx={{
+        display: 'flex',
+        alignItems: 'center',
+        gap: 1.25,
+        flexWrap: 'wrap',
+        p: 1.5,
+        bgcolor: '#161b21',
+        border: '1px solid #232a31',
+        borderRadius: 1,
+      }}
+    >
+      <TextField
+        select
+        size="small"
+        label="Population"
+        value={populationId ?? ''}
+        onChange={(e) => onPopulationChange(e.target.value)}
+        sx={{ minWidth: 220 }}
+        disabled={populations.length === 0}
+      >
+        {populations.map((p) => (
+          <MenuItem key={p.population_id} value={p.population_id}>
+            {p.name} · {fmtCompact(p.num_objects)} objects
+          </MenuItem>
+        ))}
+      </TextField>
+
+      <TextField
+        select
+        size="small"
+        label="Evaluation run"
+        value={runId && sortedRuns.some((r) => r.run_id === runId) ? runId : ''}
+        onChange={(e) => onRunChange(e.target.value)}
+        sx={{ minWidth: 240 }}
+        disabled={sortedRuns.length === 0}
+      >
+        {sortedRuns.map((r) => (
+          <MenuItem key={r.run_id} value={r.run_id}>
+            {runLabel(r)}
+          </MenuItem>
+        ))}
+      </TextField>
+
+      <TextField
+        select
+        size="small"
+        label="Baseline (compare)"
+        value={
+          baselineRunId && publishedRuns.some((r) => r.run_id === baselineRunId) ? baselineRunId : ''
+        }
+        onChange={(e) => onBaselineChange(e.target.value === '' ? null : e.target.value)}
+        sx={{ minWidth: 220 }}
+        disabled={publishedRuns.length === 0}
+      >
+        <MenuItem value="">
+          <em>None</em>
+        </MenuItem>
+        {publishedRuns
+          .filter((r) => r.run_id !== runId)
+          .map((r) => (
+            <MenuItem key={r.run_id} value={r.run_id}>
+              {runLabel(r)}
+            </MenuItem>
+          ))}
+      </TextField>
+
+      {selectedRun ? <RunStatusChip status={selectedRun.status} /> : null}
+
+      <Box sx={{ flex: 1 }} />
+
+      {cache ? (
+        <Tooltip title={`Aggregate cache: ${cache.hits} hits / ${cache.misses} misses`}>
+          <Chip
+            size="small"
+            label={`cache ${cache.entries} · hit ${cache.hit_rate === null ? '—' : fmtPct(cache.hit_rate)}`}
+            sx={{ height: 20, fontSize: 10.5, fontFamily: 'monospace', bgcolor: '#232a31', color: '#aab4be' }}
+          />
+        </Tooltip>
+      ) : null}
+
+      <GeneratePopulationButton onGenerated={onGenerated} />
+      <NewRunButton populationId={populationId} onCreated={onRunCreated} />
+    </Box>
+  );
+}

src/components/megaeval/HeroRow.tsx

@@ -0,0 +1,117 @@
+/**
+ * Hero aggregates for a published run: population-scale counts followed by the
+ * headline quality metrics. Precision/recall are annotated with sampling-verified
+ * confidence intervals when review results exist.
+ */
+import Box from '@mui/material/Box';
+import Chip from '@mui/material/Chip';
+import type { EvaluationRunInfo, MetricEstimate, ReviewState } from '../../types/megaeval';
+import { fmtCompact, queryEvaluations } from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { MetricCard, fmtNum, fmtPct } from '../labeleval/shared';
+import { QueryBadge, rowNum } from './shared';
+
+function ciSub(est: MetricEstimate | undefined): string | null {
+  if (!est) return null;
+  return `95% CI ${fmtPct(est.ci_low)}–${fmtPct(est.ci_high)}, n=${est.n_reviewed.toLocaleString()} reviewed`;
+}
+
+const VERIFIED_CHIP = (
+  <Chip
+    size="small"
+    label="sampling-verified"
+    sx={{ height: 16, fontSize: 9, fontWeight: 700, bgcolor: '#12303f', color: '#81d4fa', ml: 0.5 }}
+  />
+);
+
+export default function HeroRow({
+  run,
+  review,
+  refreshKey,
+}: {
+  run: EvaluationRunInfo;
+  review: ReviewState | null;
+  refreshKey: number;
+}) {
+  const h = run.headline;
+  // Reviewed / verified totals come from the aggregate query API (also shows provenance).
+  const totals = usePoll(
+    () =>
+      queryEvaluations({
+        evaluation_id: run.run_id,
+        metrics: ['n', 'reviewed', 'verified', 'review_coverage'],
+      }),
+    null,
+    [run.run_id, refreshKey]
+  );
+  const totalsRow = totals.data?.rows[0];
+  const reviewed = totalsRow ? rowNum(totalsRow, 'reviewed') : null;
+  const verified = totalsRow ? rowNum(totalsRow, 'verified') : null;
+
+  const results = review?.results ?? null;
+  const precisionCi = ciSub(results?.precision);
+  const recallCi = ciSub(results?.recall);
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1.5 }}>
+      <Box sx={{ display: 'flex', gap: 1.5, flexWrap: 'wrap' }}>
+        <MetricCard label="Objects evaluated" value={fmtCompact(h.n)} sub="exact (cube)" />
+        <MetricCard
+          label="Containers"
+          value={fmtCompact(h.containers)}
+          sub={h.containers_hll_estimate !== undefined ? `HLL est ${fmtCompact(h.containers_hll_estimate)} (approx)` : 'exact'}
+        />
+        <MetricCard
+          label="Reviewed"
+          value={fmtCompact(reviewed)}
+          sub={
+            <Box component="span" sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.5 }}>
+              <span>human reviews</span>
+              <QueryBadge meta={totals.data?.meta} />
+            </Box>
+          }
+          accent="#42a5f5"
+        />
+        <MetricCard label="Verified" value={fmtCompact(verified)} accent="#66bb6a" sub="human-verified" />
+      </Box>
+      <Box sx={{ display: 'flex', gap: 1.5, flexWrap: 'wrap' }}>
+        <MetricCard
+          label="Precision"
+          value={fmtPct(h.precision)}
+          sub={
+            precisionCi ? (
+              <Box component="span" sx={{ display: 'inline-flex', alignItems: 'center', flexWrap: 'wrap' }}>
+                <span>
+                  {fmtPct(results?.precision.estimate)} ({precisionCi})
+                </span>
+                {VERIFIED_CHIP}
+              </Box>
+            ) : (
+              'point estimate'
+            )
+          }
+        />
+        <MetricCard
+          label="Recall"
+          value={fmtPct(h.recall)}
+          sub={
+            recallCi ? (
+              <Box component="span" sx={{ display: 'inline-flex', alignItems: 'center', flexWrap: 'wrap' }}>
+                <span>
+                  {fmtPct(results?.recall.estimate)} ({recallCi})
+                </span>
+                {VERIFIED_CHIP}
+              </Box>
+            ) : (
+              'point estimate'
+            )
+          }
+        />
+        <MetricCard label="F1" value={fmtPct(h.f1)} />
+        <MetricCard label="Mean IoU" value={fmtNum(h.mean_iou, 3)} />
+        <MetricCard label="Anomaly rate" value={fmtPct(h.anomaly_rate)} accent="#ffa726" />
+        <MetricCard label="Safety recall" value={fmtPct(h.safety_recall)} accent="#ef5350" />
+      </Box>
+    </Box>
+  );
+}

src/components/megaeval/InvestigationTab.tsx

@@ -0,0 +1,266 @@
+/**
+ * Investigation panel: multi-criteria error search against the inverted error
+ * index. Results stay aggregate-first (counts, by-type shares, worst
+ * containers) — clicking a container jumps to the forensic drill-down.
+ */
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import Checkbox from '@mui/material/Checkbox';
+import Chip from '@mui/material/Chip';
+import CircularProgress from '@mui/material/CircularProgress';
+import FormControlLabel from '@mui/material/FormControlLabel';
+import MenuItem from '@mui/material/MenuItem';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import TextField from '@mui/material/TextField';
+import Typography from '@mui/material/Typography';
+import { SearchCode, ShieldAlert } from 'lucide-react';
+import type { DimName, ErrorSearchResponse, ErrorType } from '../../types/megaeval';
+import { fmtCompact, getDimensions, searchErrors } from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { ErrorNote, MetricCard, SectionCard, fmtNum } from '../labeleval/shared';
+import { DimChips, ERROR_TYPE_COLORS, OutcomeChip } from './shared';
+
+const ALL_ERROR_TYPES: ErrorType[] = ['FN', 'FP', 'LOCALIZATION', 'ANOMALY', 'LOW_CONF'];
+
+function MultiSelect({
+  label,
+  options,
+  value,
+  onChange,
+  minWidth = 170,
+}: {
+  label: string;
+  options: string[];
+  value: string[];
+  onChange: (v: string[]) => void;
+  minWidth?: number;
+}) {
+  return (
+    <TextField
+      select
+      size="small"
+      label={label}
+      value={value}
+      onChange={(e) => {
+        const v = e.target.value as unknown;
+        onChange(typeof v === 'string' ? v.split(',').filter(Boolean) : (v as string[]));
+      }}
+      SelectProps={{ multiple: true }}
+      sx={{ minWidth }}
+    >
+      {options.map((o) => (
+        <MenuItem key={o} value={o}>
+          {o}
+        </MenuItem>
+      ))}
+    </TextField>
+  );
+}
+
+export default function InvestigationTab({
+  runId,
+  onOpenContainer,
+}: {
+  runId: string;
+  onOpenContainer: (cid: number) => void;
+}) {
+  const dims = usePoll(getDimensions, null, []);
+  const dimOptions = (d: DimName): string[] => dims.data?.dimensions[d] ?? [];
+
+  const [errorTypes, setErrorTypes] = useState<string[]>([]);
+  const [classes, setClasses] = useState<string[]>([]);
+  const [lightings, setLightings] = useState<string[]>([]);
+  const [weathers, setWeathers] = useState<string[]>([]);
+  const [confMax, setConfMax] = useState('');
+  const [riskMin, setRiskMin] = useState('');
+  const [safetyOnly, setSafetyOnly] = useState(false);
+
+  const [result, setResult] = useState<ErrorSearchResponse | null>(null);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const runSearch = async () => {
+    setBusy(true);
+    setError(null);
+    try {
+      const filters: Partial<Record<DimName, string[]>> = {};
+      if (classes.length) filters.class = classes;
+      if (lightings.length) filters.lighting = lightings;
+      if (weathers.length) filters.weather = weathers;
+      const confParsed = Number(confMax);
+      const riskParsed = Number(riskMin);
+      setResult(
+        await searchErrors({
+          run_id: runId,
+          ...(errorTypes.length ? { error_types: errorTypes as ErrorType[] } : {}),
+          ...(Object.keys(filters).length ? { filters } : {}),
+          ...(confMax.trim() !== '' && Number.isFinite(confParsed) ? { confidence_max: confParsed } : {}),
+          ...(riskMin.trim() !== '' && Number.isFinite(riskParsed) ? { risk_min: riskParsed } : {}),
+          ...(safetyOnly ? { safety_only: true } : {}),
+          limit_containers: 20,
+        })
+      );
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <SectionCard title="Error search">
+        <Box sx={{ display: 'flex', gap: 1.25, flexWrap: 'wrap', alignItems: 'center' }}>
+          <MultiSelect label="Error types" options={ALL_ERROR_TYPES} value={errorTypes} onChange={setErrorTypes} />
+          <MultiSelect label="Class" options={dimOptions('class')} value={classes} onChange={setClasses} />
+          <MultiSelect label="Lighting" options={dimOptions('lighting')} value={lightings} onChange={setLightings} />
+          <MultiSelect label="Weather" options={dimOptions('weather')} value={weathers} onChange={setWeathers} />
+          <TextField
+            size="small"
+            label="Max confidence"
+            type="number"
+            value={confMax}
+            onChange={(e) => setConfMax(e.target.value)}
+            sx={{ width: 130 }}
+            inputProps={{ step: 0.05, min: 0, max: 1 }}
+          />
+          <TextField
+            size="small"
+            label="Min risk"
+            type="number"
+            value={riskMin}
+            onChange={(e) => setRiskMin(e.target.value)}
+            sx={{ width: 110 }}
+            inputProps={{ step: 0.1, min: 0 }}
+          />
+          <FormControlLabel
+            control={<Checkbox size="small" checked={safetyOnly} onChange={(e) => setSafetyOnly(e.target.checked)} />}
+            label={<Typography variant="body2">Safety-critical only</Typography>}
+          />
+          <Button
+            variant="contained"
+            size="small"
+            startIcon={busy ? <CircularProgress size={14} color="inherit" /> : <SearchCode size={15} />}
+            disabled={busy}
+            onClick={() => void runSearch()}
+          >
+            Search errors
+          </Button>
+        </Box>
+        {error ? <ErrorNote error={error} /> : null}
+      </SectionCard>
+
+      {result ? (
+        <>
+          <Box sx={{ display: 'flex', gap: 1.5, flexWrap: 'wrap', alignItems: 'center' }}>
+            <MetricCard label="Matched errors" value={fmtCompact(result.matched_errors)} accent="#ef5350" />
+            <Box sx={{ display: 'flex', gap: 0.75, flexWrap: 'wrap', alignItems: 'center' }}>
+              {ALL_ERROR_TYPES.filter((t) => (result.by_type[t] ?? 0) > 0).map((t) => (
+                <Chip
+                  key={t}
+                  size="small"
+                  label={`${t}: ${fmtCompact(result.by_type[t] ?? 0)}`}
+                  sx={{
+                    fontFamily: 'monospace',
+                    fontWeight: 700,
+                    bgcolor: '#232a31',
+                    color: ERROR_TYPE_COLORS[t],
+                  }}
+                />
+              ))}
+            </Box>
+          </Box>
+
+          <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+            <SectionCard title={`Worst containers (${result.worst_containers.length})`} sx={{ flex: '1 1 480px' }}>
+              <Table size="small">
+                <TableHead>
+                  <TableRow>
+                    <TableCell>Container</TableCell>
+                    <TableCell>Context</TableCell>
+                    <TableCell align="right">Errors</TableCell>
+                    <TableCell align="right">Mean risk</TableCell>
+                    <TableCell align="right">Max severity</TableCell>
+                    <TableCell align="right">Safety hits</TableCell>
+                  </TableRow>
+                </TableHead>
+                <TableBody>
+                  {result.worst_containers.map((c) => (
+                    <TableRow
+                      key={c.container_id}
+                      hover
+                      onClick={() => onOpenContainer(c.container_id)}
+                      sx={{ cursor: 'pointer' }}
+                    >
+                      <TableCell sx={{ fontFamily: 'monospace', color: '#4fc3f7' }}>#{c.container_id}</TableCell>
+                      <TableCell>
+                        <DimChips values={[c.scenario, c.lighting, c.weather]} />
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                        {c.error_count}
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                        {fmtNum(c.mean_risk, 2)}
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                        {fmtNum(c.max_severity, 2)}
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace', color: c.safety_hits > 0 ? '#ef5350' : undefined }}>
+                        {c.safety_hits}
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+              <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1 }}>
+                Click a container to open its forensic object table.
+              </Typography>
+            </SectionCard>
+
+            <SectionCard title={`Top examples (${result.examples.length})`} sx={{ flex: '1 1 420px' }}>
+              <Box sx={{ maxHeight: 420, overflowY: 'auto', display: 'flex', flexDirection: 'column', gap: 0.75 }}>
+                {result.examples.map((ex) => (
+                  <Box
+                    key={ex.error_id}
+                    sx={{
+                      display: 'flex',
+                      alignItems: 'center',
+                      gap: 1,
+                      p: 0.75,
+                      border: '1px solid #232a31',
+                      borderRadius: 1,
+                      cursor: 'pointer',
+                      '&:hover': { bgcolor: '#1b222a' },
+                    }}
+                    onClick={() => onOpenContainer(ex.container_id)}
+                  >
+                    <OutcomeChip outcome={ex.error_type} />
+                    {ex.safety_critical ? <ShieldAlert size={14} color="#ef5350" /> : null}
+                    <Typography variant="body2" sx={{ fontWeight: 600 }}>
+                      {ex.class}
+                    </Typography>
+                    <DimChips values={[ex.scenario, ex.lighting, ex.weather]} />
+                    <Box sx={{ flex: 1 }} />
+                    <Typography variant="caption" sx={{ fontFamily: 'monospace', color: '#8a949e' }}>
+                      sev {fmtNum(ex.severity, 2)} · conf {fmtNum(ex.confidence, 2)} · risk {fmtNum(ex.risk_score, 2)} · #
+                      {ex.container_id}
+                    </Typography>
+                  </Box>
+                ))}
+              </Box>
+            </SectionCard>
+          </Box>
+        </>
+      ) : (
+        <Typography variant="body2" sx={{ color: '#8a949e' }}>
+          Define criteria and search the error index — results are served from the inverted index, not a scan.
+        </Typography>
+      )}
+    </Box>
+  );
+}

src/components/megaeval/LineageCard.tsx

@@ -0,0 +1,100 @@
+/**
+ * Collapsible reproducibility card: every version pin that produced this
+ * evaluation run (dataset, model, labels, evaluator code, metric definitions,
+ * thresholds, sampling config, seed, hardware).
+ */
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Collapse from '@mui/material/Collapse';
+import IconButton from '@mui/material/IconButton';
+import Typography from '@mui/material/Typography';
+import { ChevronDown, ChevronUp } from 'lucide-react';
+import type { RunLineage } from '../../types/megaeval';
+import { SectionCard } from '../labeleval/shared';
+
+function Field({ label, value }: { label: string; value: string | number }) {
+  return (
+    <Box sx={{ minWidth: 220, flex: '1 1 220px' }}>
+      <Typography variant="caption" sx={{ color: '#8a949e', textTransform: 'uppercase', fontSize: 9.5 }}>
+        {label}
+      </Typography>
+      <Typography variant="body2" sx={{ fontFamily: 'monospace', wordBreak: 'break-all' }}>
+        {value}
+      </Typography>
+    </Box>
+  );
+}
+
+export default function LineageCard({ lineage }: { lineage: RunLineage }) {
+  const [open, setOpen] = useState(true);
+  return (
+    <SectionCard
+      title="Run lineage & reproducibility"
+      action={
+        <IconButton size="small" onClick={() => setOpen((o) => !o)}>
+          {open ? <ChevronUp size={16} /> : <ChevronDown size={16} />}
+        </IconButton>
+      }
+    >
+      <Collapse in={open}>
+        <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', mb: 2 }}>
+          <Field label="Evaluation ID" value={lineage.evaluation_id} />
+          <Field label="Dataset version" value={lineage.dataset_version} />
+          <Field label="Model version" value={lineage.model_version} />
+          <Field label="Model checkpoint" value={lineage.model_checkpoint} />
+          <Field label="Label version" value={lineage.label_version} />
+          <Field label="Evaluator code version" value={lineage.evaluator_code_version} />
+          <Field label="Metric version" value={lineage.metric_version} />
+          <Field label="Seed" value={lineage.seed} />
+          <Field label="Hardware" value={lineage.hardware} />
+          <Field label="Timestamp" value={new Date(lineage.timestamp).toLocaleString()} />
+        </Box>
+        <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap' }}>
+          <Box sx={{ flex: '1 1 320px' }}>
+            <Typography variant="caption" sx={{ color: '#8a949e', textTransform: 'uppercase', fontSize: 9.5 }}>
+              Threshold config
+            </Typography>
+            <Box
+              component="pre"
+              sx={{
+                m: 0,
+                p: 1,
+                bgcolor: '#12171d',
+                border: '1px solid #232a31',
+                borderRadius: 1,
+                fontSize: 11.5,
+                fontFamily: 'monospace',
+                overflowX: 'auto',
+              }}
+            >
+              {JSON.stringify(lineage.threshold_config, null, 2)}
+            </Box>
+          </Box>
+          <Box sx={{ flex: '1 1 320px' }}>
+            <Typography variant="caption" sx={{ color: '#8a949e', textTransform: 'uppercase', fontSize: 9.5 }}>
+              Sampling config
+            </Typography>
+            <Box
+              component="pre"
+              sx={{
+                m: 0,
+                p: 1,
+                bgcolor: '#12171d',
+                border: '1px solid #232a31',
+                borderRadius: 1,
+                fontSize: 11.5,
+                fontFamily: 'monospace',
+                overflowX: 'auto',
+              }}
+            >
+              {JSON.stringify(lineage.sampling_config, null, 2)}
+            </Box>
+          </Box>
+        </Box>
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1.5 }}>
+          Identical inputs + seed reproduce this evaluation bit-for-bit.
+        </Typography>
+      </Collapse>
+    </SectionCard>
+  );
+}

src/components/megaeval/QualityTab.tsx

@@ -0,0 +1,358 @@
+/**
+ * Quality tab: per-class quality bars, error-type distribution, the quality
+ * funnel, cross-run quality trend, and sketch-based distributions.
+ * Every aggregate-query panel surfaces its provenance badge.
+ */
+import { useMemo } from 'react';
+import Box from '@mui/material/Box';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import Typography from '@mui/material/Typography';
+import type { ErrorType, EvaluationRunInfo } from '../../types/megaeval';
+import {
+  fmtCompact,
+  getRunDistributions,
+  getRunFunnel,
+  queryEvaluations,
+  searchErrors,
+} from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { ErrorNote, HBar, LoadingBox, SectionCard, fmtNum, fmtPct } from '../labeleval/shared';
+import {
+  ERROR_TYPE_COLORS,
+  ExactnessTag,
+  HistogramSparkline,
+  PctBarCell,
+  QueryBadge,
+  rowNum,
+  rowStr,
+} from './shared';
+
+// ---------------------------------------------------------------- per-class quality
+
+function QualityByClass({ runId, refreshKey }: { runId: string; refreshKey: number }) {
+  const q = usePoll(
+    () =>
+      queryEvaluations({
+        evaluation_id: runId,
+        group_by: ['class'],
+        metrics: ['n', 'precision', 'recall', 'f1', 'mean_iou'],
+      }),
+    null,
+    [runId, refreshKey]
+  );
+  return (
+    <SectionCard title="Quality by class" action={<QueryBadge meta={q.data?.meta} />} sx={{ flex: '1 1 460px' }}>
+      {q.error ? <ErrorNote error={q.error} /> : null}
+      {q.loading && !q.data ? <LoadingBox /> : null}
+      {q.data ? (
+        <Table size="small">
+          <TableHead>
+            <TableRow>
+              <TableCell>Class</TableCell>
+              <TableCell align="right">n</TableCell>
+              <TableCell>Recall</TableCell>
+              <TableCell>Precision</TableCell>
+              <TableCell align="right">F1</TableCell>
+              <TableCell align="right">Mean IoU</TableCell>
+            </TableRow>
+          </TableHead>
+          <TableBody>
+            {[...q.data.rows]
+              .sort((a, b) => b.n - a.n)
+              .map((row) => (
+                <TableRow key={rowStr(row, 'class')} hover>
+                  <TableCell sx={{ fontWeight: 600 }}>{rowStr(row, 'class')}</TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtCompact(row.n)}
+                  </TableCell>
+                  <TableCell>
+                    <PctBarCell value={rowNum(row, 'recall')} color="#66bb6a" />
+                  </TableCell>
+                  <TableCell>
+                    <PctBarCell value={rowNum(row, 'precision')} color="#4fc3f7" />
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtPct(rowNum(row, 'f1'))}
+                  </TableCell>
+                  <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                    {fmtNum(rowNum(row, 'mean_iou'), 3)}
+                  </TableCell>
+                </TableRow>
+              ))}
+          </TableBody>
+        </Table>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+// ---------------------------------------------------------------- error distribution
+
+const ERROR_TYPE_ORDER: ErrorType[] = ['FN', 'FP', 'LOCALIZATION', 'ANOMALY', 'LOW_CONF'];
+
+function ErrorDistribution({ runId, refreshKey }: { runId: string; refreshKey: number }) {
+  const res = usePoll(() => searchErrors({ run_id: runId }), null, [runId, refreshKey]);
+  const byType = res.data?.by_type ?? {};
+  const total = ERROR_TYPE_ORDER.reduce((acc, t) => acc + (byType[t] ?? 0), 0);
+  const max = Math.max(1, ...ERROR_TYPE_ORDER.map((t) => byType[t] ?? 0));
+  return (
+    <SectionCard title="Error distribution" sx={{ flex: '1 1 320px' }}>
+      {res.error ? <ErrorNote error={res.error} /> : null}
+      {res.loading && !res.data ? <LoadingBox /> : null}
+      {res.data ? (
+        <>
+          <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1 }}>
+            {fmtCompact(res.data.matched_errors)} potential errors indexed (exact)
+          </Typography>
+          {ERROR_TYPE_ORDER.map((t) => {
+            const count = byType[t] ?? 0;
+            return (
+              <HBar
+                key={t}
+                label={t}
+                value={count}
+                max={max}
+                color={ERROR_TYPE_COLORS[t]}
+                valueLabel={`${fmtCompact(count)} (${total > 0 ? fmtPct(count / total) : '—'})`}
+              />
+            );
+          })}
+        </>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+// ---------------------------------------------------------------- quality funnel
+
+function QualityFunnel({ runId, refreshKey }: { runId: string; refreshKey: number }) {
+  const funnel = usePoll(() => getRunFunnel(runId), null, [runId, refreshKey]);
+  const stages = funnel.data?.stages ?? [];
+  const max = stages.length ? Math.max(...stages.map((s) => s.count)) : 1;
+  const est = funnel.data?.estimated_precision ?? null;
+  return (
+    <SectionCard title="Quality funnel" sx={{ flex: '1 1 420px' }}>
+      {funnel.error ? <ErrorNote error={funnel.error} /> : null}
+      {funnel.loading && !funnel.data ? <LoadingBox /> : null}
+      {funnel.data ? (
+        <>
+          {stages.map((s) => (
+            <HBar
+              key={s.stage}
+              label={s.stage}
+              value={s.count}
+              max={max}
+              color="#4fc3f7"
+              valueLabel={`${fmtCompact(s.count)} (${fmtPct(s.pct_of_population)})`}
+            />
+          ))}
+          {est && est.estimate !== null ? (
+            <Typography variant="body2" sx={{ mt: 1.5, color: '#a5d6a7' }}>
+              Estimated precision {fmtPct(est.estimate)}
+              {est.ci_low !== null && est.ci_high !== null
+                ? ` (95% CI ${fmtPct(est.ci_low)}–${fmtPct(est.ci_high)}${
+                    est.n_reviewed !== null ? `, n=${est.n_reviewed.toLocaleString()} reviewed` : ''
+                  })`
+                : ''}
+            </Typography>
+          ) : null}
+        </>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+// ---------------------------------------------------------------- quality trend
+
+const TREND_SERIES: Array<{ key: 'precision' | 'recall' | 'safety_recall'; label: string; color: string }> = [
+  { key: 'precision', label: 'precision', color: '#4fc3f7' },
+  { key: 'recall', label: 'recall', color: '#66bb6a' },
+  { key: 'safety_recall', label: 'safety recall', color: '#ffa726' },
+];
+
+function QualityTrend({ runs }: { runs: EvaluationRunInfo[] }) {
+  const published = useMemo(
+    () =>
+      runs
+        .filter((r) => r.status === 'published')
+        .sort((a, b) => (a.created_at ?? '').localeCompare(b.created_at ?? '')),
+    [runs]
+  );
+
+  const width = 520;
+  const height = 150;
+  const padL = 40;
+  const padB = 30;
+  const padT = 10;
+
+  const values = published.flatMap((r) =>
+    TREND_SERIES.map((s) => r.headline[s.key]).filter((v): v is number => v !== null && v !== undefined)
+  );
+  const lo = values.length ? Math.max(0, Math.min(...values) - 0.05) : 0;
+  const hi = values.length ? Math.min(1, Math.max(...values) + 0.02) : 1;
+  const xFor = (i: number) =>
+    padL + (published.length <= 1 ? (width - padL) / 2 : (i / (published.length - 1)) * (width - padL - 10));
+  const yFor = (v: number) => padT + (1 - (v - lo) / Math.max(1e-9, hi - lo)) * (height - padT - padB);
+
+  return (
+    <SectionCard title="Quality trend across published runs" sx={{ flex: '1 1 460px' }}>
+      {published.length < 2 ? (
+        <Typography variant="body2" sx={{ color: '#8a949e' }}>
+          {published.length === 0
+            ? 'No published runs yet.'
+            : 'Only one published run — launch another run to see the trend.'}
+        </Typography>
+      ) : null}
+      {published.length >= 1 ? (
+        <>
+          <svg width={width} height={height}>
+            {[lo, (lo + hi) / 2, hi].map((v, i) => (
+              <g key={i}>
+                <line x1={padL} x2={width - 5} y1={yFor(v)} y2={yFor(v)} stroke="#232a31" />
+                <text x={2} y={yFor(v) + 3} fontSize={9} fill="#8a949e" fontFamily="monospace">
+                  {fmtPct(v)}
+                </text>
+              </g>
+            ))}
+            {TREND_SERIES.map((s) => {
+              const pts = published
+                .map((r, i) => ({ v: r.headline[s.key], i }))
+                .filter((p): p is { v: number; i: number } => p.v !== null && p.v !== undefined);
+              if (!pts.length) return null;
+              return (
+                <g key={s.key}>
+                  <polyline
+                    fill="none"
+                    stroke={s.color}
+                    strokeWidth={2}
+                    points={pts.map((p) => `${xFor(p.i)},${yFor(p.v)}`).join(' ')}
+                  />
+                  {pts.map((p) => (
+                    <circle key={p.i} cx={xFor(p.i)} cy={yFor(p.v)} r={3} fill={s.color} />
+                  ))}
+                </g>
+              );
+            })}
+            {published.map((r, i) => (
+              <text
+                key={r.run_id}
+                x={xFor(i)}
+                y={height - 6}
+                fontSize={9}
+                fill="#aab4be"
+                textAnchor="middle"
+                fontFamily="monospace"
+              >
+                {r.model_version.length > 14 ? `${r.model_version.slice(0, 13)}…` : r.model_version}
+              </text>
+            ))}
+          </svg>
+          <Box sx={{ display: 'flex', gap: 2 }}>
+            {TREND_SERIES.map((s) => (
+              <Box key={s.key} sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+                <Box sx={{ width: 10, height: 3, bgcolor: s.color, borderRadius: 1 }} />
+                <Typography variant="caption" sx={{ color: '#aab4be' }}>
+                  {s.label}
+                </Typography>
+              </Box>
+            ))}
+          </Box>
+        </>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+// ---------------------------------------------------------------- distributions (sketches)
+
+function DistributionsCard({ runId, refreshKey }: { runId: string; refreshKey: number }) {
+  const dist = usePoll(() => getRunDistributions(runId), null, [runId, refreshKey]);
+  const d = dist.data;
+  return (
+    <SectionCard
+      title={
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+          <span>Distributions</span>
+          <ExactnessTag approx />
+        </Box>
+      }
+      sx={{ flex: '1 1 320px' }}
+    >
+      {dist.error ? <ErrorNote error={dist.error} /> : null}
+      {dist.loading && !d ? <LoadingBox /> : null}
+      {d ? (
+        <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1.5 }}>
+          {d.confidence ? (
+            <Box>
+              <Typography variant="caption" sx={{ color: '#aab4be' }}>
+                Confidence — approximate (sketch)
+              </Typography>
+              <HistogramSparkline sketch={d.confidence} color="#4fc3f7" />
+            </Box>
+          ) : null}
+          {d.iou ? (
+            <Box>
+              <Typography variant="caption" sx={{ color: '#aab4be' }}>
+                IoU — approximate (sketch)
+              </Typography>
+              <HistogramSparkline sketch={d.iou} color="#66bb6a" />
+            </Box>
+          ) : null}
+          <Box sx={{ display: 'flex', gap: 3, alignItems: 'center' }}>
+            <Box>
+              <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+                <Typography variant="caption" sx={{ color: '#8a949e' }}>
+                  Containers (HLL)
+                </Typography>
+                <ExactnessTag approx />
+              </Box>
+              <Typography variant="body2" sx={{ fontFamily: 'monospace', fontWeight: 700 }}>
+                {d.containers_hll_estimate === null ? '—' : fmtCompact(d.containers_hll_estimate)}
+              </Typography>
+            </Box>
+            <Box>
+              <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.5 }}>
+                <Typography variant="caption" sx={{ color: '#8a949e' }}>
+                  Containers (exact)
+                </Typography>
+                <ExactnessTag approx={false} />
+              </Box>
+              <Typography variant="body2" sx={{ fontFamily: 'monospace', fontWeight: 700 }}>
+                {d.containers_exact === null ? '—' : fmtCompact(d.containers_exact)}
+              </Typography>
+            </Box>
+          </Box>
+          <Typography variant="caption" sx={{ color: '#8a949e' }}>
+            {d.note}
+          </Typography>
+        </Box>
+      ) : null}
+    </SectionCard>
+  );
+}
+
+// ---------------------------------------------------------------- tab
+
+export default function QualityTab({
+  runId,
+  runs,
+  refreshKey,
+}: {
+  runId: string;
+  runs: EvaluationRunInfo[];
+  refreshKey: number;
+}) {
+  return (
+    <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+      <QualityByClass runId={runId} refreshKey={refreshKey} />
+      <ErrorDistribution runId={runId} refreshKey={refreshKey} />
+      <QualityFunnel runId={runId} refreshKey={refreshKey} />
+      <QualityTrend runs={runs} />
+      <DistributionsCard runId={runId} refreshKey={refreshKey} />
+    </Box>
+  );
+}

src/components/megaeval/ReviewTab.tsx

@@ -0,0 +1,205 @@
+/**
+ * Review sampling panel: statistically grounded human review. Build a
+ * stratified sampling plan, execute (simulated) reviews, then read precision
+ * and recall estimates with Wilson confidence intervals per stratum.
+ */
+import { useState } from 'react';
+import Box from '@mui/material/Box';
+import Button from '@mui/material/Button';
+import CircularProgress from '@mui/material/CircularProgress';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import Typography from '@mui/material/Typography';
+import { ClipboardList, UserCheck } from 'lucide-react';
+import type { MetricEstimate, ReviewState, SamplingFunnel, StratumPlan } from '../../types/megaeval';
+import { executeReview, fmtCompact, planReview } from '../../services/megaeval';
+import { ErrorNote, HBar, SectionCard, fmtPct } from '../labeleval/shared';
+
+const FUNNEL_STAGES: Array<{ key: keyof SamplingFunnel; label: string }> = [
+  { key: 'population_objects', label: 'Population objects' },
+  { key: 'containers', label: 'Containers' },
+  { key: 'suspicious_containers', label: 'Suspicious containers' },
+  { key: 'candidate_pool', label: 'Candidate pool' },
+  { key: 'statistically_selected', label: 'Statistically selected' },
+  { key: 'reviewed', label: 'Reviewed' },
+];
+
+function EstimateCard({ label, est }: { label: string; est: MetricEstimate }) {
+  return (
+    <SectionCard title={`${label} estimate`} sx={{ flex: '1 1 420px' }}>
+      <Typography variant="h5" sx={{ fontWeight: 800, color: '#a5d6a7' }}>
+        {fmtPct(est.estimate)}
+        <Typography component="span" variant="body2" sx={{ color: '#8a949e', ml: 1 }}>
+          95% CI {fmtPct(est.ci_low)}–{fmtPct(est.ci_high)} · n={est.n_reviewed.toLocaleString()} reviewed · frame{' '}
+          {fmtCompact(est.frame_size)}
+        </Typography>
+      </Typography>
+      <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1 }}>
+        {est.method}
+      </Typography>
+      <Table size="small">
+        <TableHead>
+          <TableRow>
+            <TableCell>Stratum</TableCell>
+            <TableCell align="right">N</TableCell>
+            <TableCell align="right">n</TableCell>
+            <TableCell align="right">p</TableCell>
+            <TableCell align="right">Wilson 95% CI</TableCell>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {est.strata.map((s) => (
+            <TableRow key={s.stratum} hover>
+              <TableCell sx={{ fontFamily: 'monospace', fontSize: 12 }}>{s.stratum}</TableCell>
+              <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                {fmtCompact(s.N)}
+              </TableCell>
+              <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                {s.n.toLocaleString()}
+              </TableCell>
+              <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                {fmtPct(s.p)}
+              </TableCell>
+              <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                {fmtPct(s.wilson_ci[0])}–{fmtPct(s.wilson_ci[1])}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </SectionCard>
+  );
+}
+
+function PlanTable({ title, strata }: { title: string; strata: Record<string, StratumPlan> }) {
+  const entries = Object.entries(strata);
+  return (
+    <SectionCard title={title} sx={{ flex: '1 1 340px' }}>
+      <Table size="small">
+        <TableHead>
+          <TableRow>
+            <TableCell>Stratum</TableCell>
+            <TableCell align="right">N</TableCell>
+            <TableCell align="right">Allocated</TableCell>
+          </TableRow>
+        </TableHead>
+        <TableBody>
+          {entries.map(([key, plan]) => (
+            <TableRow key={key} hover>
+              <TableCell sx={{ fontFamily: 'monospace', fontSize: 12 }}>{plan.label || key}</TableCell>
+              <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                {fmtCompact(plan.N)}
+              </TableCell>
+              <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                {plan.allocated.toLocaleString()}
+              </TableCell>
+            </TableRow>
+          ))}
+        </TableBody>
+      </Table>
+    </SectionCard>
+  );
+}
+
+export default function ReviewTab({
+  runId,
+  review,
+  onReview,
+}: {
+  runId: string;
+  review: ReviewState | null;
+  onReview: (r: ReviewState) => void;
+}) {
+  const [busy, setBusy] = useState<'plan' | 'execute' | null>(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const act = async (kind: 'plan' | 'execute') => {
+    setBusy(kind);
+    setError(null);
+    try {
+      onReview(kind === 'plan' ? await planReview(runId) : await executeReview(runId));
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const funnel = review?.funnel;
+  const max = funnel ? Math.max(1, funnel.population_objects) : 1;
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      <SectionCard
+        title="Statistical review sampling"
+        action={
+          <Box sx={{ display: 'flex', gap: 1 }}>
+            <Button
+              size="small"
+              variant="outlined"
+              startIcon={busy === 'plan' ? <CircularProgress size={14} color="inherit" /> : <ClipboardList size={14} />}
+              disabled={busy !== null}
+              onClick={() => void act('plan')}
+            >
+              Build sampling plan
+            </Button>
+            <Button
+              size="small"
+              variant="contained"
+              startIcon={busy === 'execute' ? <CircularProgress size={14} color="inherit" /> : <UserCheck size={14} />}
+              disabled={busy !== null || !review?.planned}
+              onClick={() => void act('execute')}
+            >
+              Execute reviews (simulated)
+            </Button>
+          </Box>
+        }
+      >
+        {error ? <ErrorNote error={error} /> : null}
+        {!review || !review.planned ? (
+          <Typography variant="body2" sx={{ color: '#8a949e' }}>
+            No sampling plan yet. Reviewing everything at this scale is impossible — build a stratified plan to
+            estimate precision and recall from a small, statistically selected sample.
+          </Typography>
+        ) : (
+          <>
+            <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1 }}>
+              {review.method ?? 'stratified sampling'}
+              {review.target_n !== undefined ? ` · target n=${review.target_n.toLocaleString()}` : ''}
+              {review.executed ? ' · executed' : ' · planned, not executed'}
+            </Typography>
+            {funnel
+              ? FUNNEL_STAGES.map((s) => (
+                  <HBar
+                    key={s.key}
+                    label={s.label}
+                    value={funnel[s.key]}
+                    max={max}
+                    color={s.key === 'reviewed' ? '#66bb6a' : '#4fc3f7'}
+                    valueLabel={`${fmtCompact(funnel[s.key])} (${fmtPct(funnel[s.key] / max)})`}
+                  />
+                ))
+              : null}
+          </>
+        )}
+      </SectionCard>
+
+      {review?.planned && !review.executed && review.strata ? (
+        <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+          <PlanTable title="Precision strata plan" strata={review.strata.precision} />
+          <PlanTable title="Recall strata plan" strata={review.strata.recall} />
+        </Box>
+      ) : null}
+
+      {review?.results ? (
+        <Box sx={{ display: 'flex', gap: 2, flexWrap: 'wrap', alignItems: 'flex-start' }}>
+          <EstimateCard label="Precision" est={review.results.precision} />
+          <EstimateCard label="Recall" est={review.results.recall} />
+        </Box>
+      ) : null}
+    </Box>
+  );
+}

src/components/megaeval/RunProgressCard.tsx

@@ -0,0 +1,63 @@
+/**
+ * Live progress card for an in-flight (non-published) evaluation run.
+ * Fed by the SSE stream when available, otherwise by 1.5s polling.
+ */
+import Box from '@mui/material/Box';
+import LinearProgress from '@mui/material/LinearProgress';
+import Typography from '@mui/material/Typography';
+import type { RunProgress } from '../../types/megaeval';
+import { fmtCompact } from '../../services/megaeval';
+import { SectionCard } from '../labeleval/shared';
+import { CompactStat, RunStatusChip } from './shared';
+
+function fmtEta(s: number | null): string {
+  if (s === null || Number.isNaN(s)) return '—';
+  if (s < 60) return `${Math.max(0, Math.round(s))}s`;
+  return `${Math.floor(s / 60)}m ${Math.round(s % 60)}s`;
+}
+
+export default function RunProgressCard({ progress }: { progress: RunProgress }) {
+  // Tolerate either 0..1 or 0..100 percent encodings from the backend.
+  const pct = Math.max(0, Math.min(100, progress.percent <= 1 ? progress.percent * 100 : progress.percent));
+  return (
+    <SectionCard
+      title={
+        <Box sx={{ display: 'flex', alignItems: 'center', gap: 1 }}>
+          <span>
+            Evaluation run {progress.run_id.slice(0, 8)} · {progress.model_version}
+          </span>
+          <RunStatusChip status={progress.status} />
+        </Box>
+      }
+    >
+      <LinearProgress
+        variant="determinate"
+        value={pct}
+        sx={{ height: 10, borderRadius: 1, mb: 1.5, bgcolor: '#232a31' }}
+      />
+      <Box sx={{ display: 'flex', gap: 3, flexWrap: 'wrap' }}>
+        <CompactStat label="Progress" value={`${pct.toFixed(1)}%`} />
+        <CompactStat
+          label="Objects"
+          value={`${fmtCompact(progress.objects_processed)} / ${fmtCompact(progress.objects_total)}`}
+        />
+        <CompactStat
+          label="Partitions"
+          value={`${progress.partitions_done} / ${progress.partitions_total}`}
+        />
+        <CompactStat label="Workers" value={progress.workers} />
+        <CompactStat label="Throughput" value={`${fmtCompact(progress.throughput_objs_per_s)} objs/s`} />
+        <CompactStat label="ETA" value={fmtEta(progress.eta_s)} />
+      </Box>
+      {progress.error ? (
+        <Typography variant="body2" sx={{ color: '#ef5350', mt: 1.5, fontFamily: 'monospace' }}>
+          {progress.error}
+        </Typography>
+      ) : (
+        <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mt: 1.5 }}>
+          Map partitions across workers → reduce partial aggregates → materialize cube &amp; indexes → publish.
+        </Typography>
+      )}
+    </SectionCard>
+  );
+}

src/components/megaeval/ShiftTab.tsx

@@ -0,0 +1,96 @@
+/**
+ * Distribution shift panel: cohorts whose share of the evaluation population
+ * diverges from the training mix, annotated with the recall gap so a shift
+ * that also hurts quality stands out.
+ */
+import Box from '@mui/material/Box';
+import Table from '@mui/material/Table';
+import TableBody from '@mui/material/TableBody';
+import TableCell from '@mui/material/TableCell';
+import TableHead from '@mui/material/TableHead';
+import TableRow from '@mui/material/TableRow';
+import Typography from '@mui/material/Typography';
+import { fmtCompact, getRunShift } from '../../services/megaeval';
+import { usePoll } from '../../services/labeleval';
+import { ErrorNote, LoadingBox, SectionCard, fmtPct } from '../labeleval/shared';
+
+function gapColor(gap: number | null): string | undefined {
+  if (gap === null) return undefined;
+  const g = Math.abs(gap);
+  if (g >= 0.1) return '#ef5350';
+  if (g >= 0.05) return '#ffa726';
+  return undefined;
+}
+
+export default function ShiftTab({ runId, refreshKey }: { runId: string; refreshKey: number }) {
+  const shift = usePoll(() => getRunShift(runId), null, [runId, refreshKey]);
+  const data = shift.data;
+
+  return (
+    <SectionCard title="Distribution shift (train mix vs evaluation population)">
+      {shift.error ? <ErrorNote error={shift.error} /> : null}
+      {shift.loading && !data ? <LoadingBox /> : null}
+      {data ? (
+        <>
+          <Typography variant="caption" sx={{ color: '#8a949e', display: 'block', mb: 1 }}>
+            {data.method} · thresholds: min eval count {fmtCompact(data.thresholds.min_eval_count)}, relative change ≥{' '}
+            {fmtPct(data.thresholds.rel_threshold)}
+          </Typography>
+          {data.shifts.length === 0 ? (
+            <Typography variant="body2" sx={{ color: '#8a949e' }}>
+              No significant distribution shifts detected.
+            </Typography>
+          ) : (
+            <Table size="small">
+              <TableHead>
+                <TableRow>
+                  <TableCell>Cohort</TableCell>
+                  <TableCell align="right">Train → eval share</TableCell>
+                  <TableCell align="right">Relative change</TableCell>
+                  <TableCell align="right">Eval count</TableCell>
+                  <TableCell align="right">Cohort recall vs overall</TableCell>
+                  <TableCell align="right">Recall gap</TableCell>
+                </TableRow>
+              </TableHead>
+              <TableBody>
+                {data.shifts.map((s) => {
+                  const color = gapColor(s.recall_gap);
+                  return (
+                    <TableRow key={s.cohort} hover sx={color === '#ef5350' ? { bgcolor: '#2a1214' } : undefined}>
+                      <TableCell sx={{ fontFamily: 'monospace', fontWeight: 600 }}>{s.cohort}</TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                        {fmtPct(s.train_share)} → {fmtPct(s.eval_share)}
+                      </TableCell>
+                      <TableCell
+                        align="right"
+                        sx={{ fontFamily: 'monospace', color: s.relative_change > 0 ? '#ffa726' : '#4fc3f7' }}
+                      >
+                        {s.relative_change > 0 ? '+' : ''}
+                        {Math.round(s.relative_change * 100)}%
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                        {fmtCompact(s.eval_count)}
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace' }}>
+                        {fmtPct(s.cohort_recall)} vs {fmtPct(s.overall_recall)}
+                      </TableCell>
+                      <TableCell align="right" sx={{ fontFamily: 'monospace', fontWeight: 700, color }}>
+                        {s.recall_gap === null ? '—' : `${(s.recall_gap * 100).toFixed(1)} pts`}
+                      </TableCell>
+                    </TableRow>
+                  );
+                })}
+              </TableBody>
+            </Table>
+          )}
+          <Box sx={{ mt: 1 }}>
+            <Typography variant="caption" sx={{ color: '#8a949e' }}>
+              Highlighted rows are cohorts that are over-represented vs training <em>and</em> underperforming on
+              recall — prime candidates for targeted data collection.
+            </Typography>
+          </Box>
+        </>
+      ) : null}
+    </SectionCard>
+  );
+}

src/components/megaeval/shared.tsx

@@ -0,0 +1,304 @@
+/**
+ * Shared UI helpers for the Evaluation Command Center (megaeval).
+ * Complements components/labeleval/shared.tsx with aggregate-first idioms:
+ * query provenance badges, exact/approx honesty tags, delta coloring,
+ * outcome chips and sketch histogram sparklines.
+ */
+import type { ReactNode } from 'react';
+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 { CheckCircle2, AlertTriangle, OctagonAlert } from 'lucide-react';
+import type { ErrorType, HistogramSketch, QueryMeta, QueryRow } from '../../types/megaeval';
+import { fmtCompact } from '../../services/megaeval';
+import { fmtPct } from '../labeleval/shared';
+
+// ---------------------------------------------------------------- query provenance
+
+const SOURCE_COLORS: Record<QueryMeta['source'], { bg: string; fg: string }> = {
+  cache: { bg: '#1b5e20', fg: '#a5d6a7' },
+  cube: { bg: '#0d47a1', fg: '#90caf9' },
+  scan: { bg: '#e65100', fg: '#ffe0b2' },
+};
+
+function fmtLatency(ms: number): string {
+  if (ms < 1) return `${ms.toFixed(1)}ms`;
+  if (ms < 100) return `${ms.toFixed(1)}ms`;
+  return `${Math.round(ms)}ms`;
+}
+
+/** "cube · 74ms" / "cache · 0.1ms" provenance badge for POST /api/evaluations/query panels. */
+export function QueryBadge({ meta }: { meta: QueryMeta | null | undefined }) {
+  if (!meta) return null;
+  const colors = SOURCE_COLORS[meta.source] ?? SOURCE_COLORS.cube;
+  const label = `${meta.source} · ${fmtLatency(meta.latency_ms)}`;
+  return (
+    <Tooltip
+      title={`source=${meta.source} · cache_hit=${meta.cache_hit ? 'yes' : 'no'} · cells=${meta.cells_touched}${
+        meta.exact ? ' · exact' : ` · approx (${meta.approximate_fields.join(', ') || 'sketch'})`
+      }`}
+    >
+      <Chip
+        size="small"
+        label={meta.cache_hit ? `${label} ✓` : label}
+        sx={{
+          height: 18,
+          fontSize: 10,
+          fontFamily: 'monospace',
+          fontWeight: 700,
+          bgcolor: colors.bg,
+          color: colors.fg,
+        }}
+      />
+    </Tooltip>
+  );
+}
+
+/** Exact vs sketch-derived honesty tag. */
+export function ExactnessTag({ approx, sx }: { approx: boolean; sx?: object }) {
+  return (
+    <Chip
+      size="small"
+      label={approx ? 'approx' : 'exact'}
+      sx={{
+        height: 16,
+        fontSize: 9.5,
+        fontFamily: 'monospace',
+        bgcolor: approx ? '#4a3b12' : '#12303f',
+        color: approx ? '#ffd54f' : '#81d4fa',
+        ...sx,
+      }}
+    />
+  );
+}
+
+// ---------------------------------------------------------------- query row helpers
+
+/** Reads a numeric metric out of a QueryRow (values arrive as string | number | null). */
+export function rowNum(row: QueryRow, key: string): number | null {
+  const v = row[key];
+  if (v === null || v === undefined) return null;
+  const n = typeof v === 'number' ? v : Number(v);
+  return Number.isNaN(n) ? null : n;
+}
+
+export function rowStr(row: QueryRow, key: string): string {
+  const v = row[key];
+  return v === null || v === undefined ? '—' : String(v);
+}
+
+// ---------------------------------------------------------------- inline percent bar
+
+/** Compact percentage cell with an inline bar, for dense aggregate tables. */
+export function PctBarCell({
+  value,
+  color = '#4fc3f7',
+  width = 84,
+}: {
+  value: number | null | undefined;
+  color?: string;
+  width?: number;
+}) {
+  if (value === null || value === undefined || Number.isNaN(value)) {
+    return (
+      <Typography variant="caption" sx={{ color: '#8a949e', fontFamily: 'monospace' }}>
+        —
+      </Typography>
+    );
+  }
+  const frac = Math.max(0, Math.min(1, value <= 1 ? value : value / 100));
+  return (
+    <Box sx={{ display: 'inline-flex', alignItems: 'center', gap: 0.75 }}>
+      <Box sx={{ width, height: 6, bgcolor: '#232a31', borderRadius: 1, overflow: 'hidden' }}>
+        <Box sx={{ height: '100%', width: `${frac * 100}%`, bgcolor: color, borderRadius: 1 }} />
+      </Box>
+      <Typography variant="caption" sx={{ fontFamily: 'monospace', color: '#e6e9ec', minWidth: 44 }}>
+        {fmtPct(value)}
+      </Typography>
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------- outcome / error type chips
+
+export const OUTCOME_COLORS: Record<string, { bg: string; fg: string }> = {
+  TP: { bg: '#1b5e20', fg: '#a5d6a7' },
+  FN: { bg: '#b71c1c', fg: '#ffcdd2' },
+  FP: { bg: '#e65100', fg: '#ffe0b2' },
+  LOCALIZATION: { bg: '#4a148c', fg: '#ce93d8' },
+  ANOMALY: { bg: '#880e4f', fg: '#f48fb1' },
+  LOW_CONF: { bg: '#f9a825', fg: '#212121' },
+};
+
+export function OutcomeChip({ outcome }: { outcome: string }) {
+  const colors = OUTCOME_COLORS[outcome] ?? { bg: '#37474f', fg: '#cfd8dc' };
+  return (
+    <Chip
+      size="small"
+      label={outcome}
+      sx={{ height: 18, fontSize: 10, fontWeight: 700, fontFamily: 'monospace', bgcolor: colors.bg, color: colors.fg }}
+    />
+  );
+}
+
+export const ERROR_TYPE_COLORS: Record<ErrorType, string> = {
+  FN: '#ef5350',
+  FP: '#ffa726',
+  LOCALIZATION: '#ab47bc',
+  ANOMALY: '#ec407a',
+  LOW_CONF: '#ffee58',
+};
+
+// ---------------------------------------------------------------- run status
+
+const RUN_STATUS_COLORS: Record<string, { bg: string; fg: string }> = {
+  created: { bg: '#37474f', fg: '#cfd8dc' },
+  queued: { bg: '#37474f', fg: '#cfd8dc' },
+  running: { bg: '#0d47a1', fg: '#90caf9' },
+  reducing: { bg: '#4a148c', fg: '#ce93d8' },
+  materializing: { bg: '#004d40', fg: '#80cbc4' },
+  published: { bg: '#1b5e20', fg: '#a5d6a7' },
+  failed: { bg: '#b71c1c', fg: '#ffcdd2' },
+};
+
+export function RunStatusChip({ status }: { status: string }) {
+  const colors = RUN_STATUS_COLORS[status] ?? { bg: '#37474f', fg: '#cfd8dc' };
+  return (
+    <Chip
+      size="small"
+      label={status.toUpperCase()}
+      sx={{ height: 20, fontSize: 10, fontWeight: 700, letterSpacing: 0.5, bgcolor: colors.bg, color: colors.fg }}
+    />
+  );
+}
+
+// ---------------------------------------------------------------- container status
+
+export function ContainerStatusIcon({ status }: { status: 'ok' | 'warn' | 'critical' }) {
+  if (status === 'critical') return <OctagonAlert size={15} color="#ef5350" />;
+  if (status === 'warn') return <AlertTriangle size={15} color="#ffa726" />;
+  return <CheckCircle2 size={15} color="#66bb6a" />;
+}
+
+// ---------------------------------------------------------------- deltas
+
+/** Colored delta text. Set higherIsBetter=false for metrics like anomaly_rate / error_rate / fp. */
+export function DeltaText({
+  delta,
+  higherIsBetter = true,
+  asPct = true,
+}: {
+  delta: number;
+  higherIsBetter?: boolean;
+  asPct?: boolean;
+}) {
+  const good = higherIsBetter ? delta >= 0 : delta <= 0;
+  const neutral = Math.abs(delta) < 1e-9;
+  const magnitude = asPct ? (Math.abs(delta) * 100).toFixed(1) : Math.abs(delta).toFixed(3);
+  const sign = delta > 0 ? '+' : delta < 0 ? '−' : '±';
+  const text = `${sign}${magnitude}`;
+  return (
+    <Typography
+      component="span"
+      variant="caption"
+      sx={{
+        fontFamily: 'monospace',
+        fontWeight: 700,
+        color: neutral ? '#8a949e' : good ? '#66bb6a' : '#ef5350',
+      }}
+    >
+      {text}
+    </Typography>
+  );
+}
+
+// ---------------------------------------------------------------- dimension chips
+
+export function DimChips({ values, sx }: { values: (string | undefined)[]; sx?: object }) {
+  return (
+    <Box sx={{ display: 'inline-flex', gap: 0.5, flexWrap: 'wrap', ...sx }}>
+      {values
+        .filter((v): v is string => Boolean(v))
+        .map((v, i) => (
+          <Chip
+            key={`${v}-${i}`}
+            size="small"
+            label={v}
+            sx={{ height: 18, fontSize: 10, bgcolor: '#232a31', color: '#aab4be' }}
+          />
+        ))}
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------- histogram sparkline (sketch)
+
+/** SVG histogram sparkline with p10 / p50 / p90 markers. Sketch-derived — always labeled approx. */
+export function HistogramSparkline({
+  sketch,
+  color = '#4fc3f7',
+  width = 260,
+  height = 56,
+}: {
+  sketch: HistogramSketch;
+  color?: string;
+  width?: number;
+  height?: number;
+}) {
+  const maxCount = Math.max(1, ...sketch.counts);
+  const barW = width / Math.max(1, sketch.counts.length);
+  const span = sketch.hi - sketch.lo || 1;
+  const xFor = (v: number) => ((v - sketch.lo) / span) * width;
+  const markers: Array<{ key: string; v: number }> = ['p10', 'p50', 'p90']
+    .filter((k) => sketch.percentiles[k] !== undefined)
+    .map((k) => ({ key: k, v: sketch.percentiles[k] }));
+  return (
+    <Box>
+      <svg width={width} height={height + 14}>
+        {sketch.counts.map((c, i) => {
+          const h = (c / maxCount) * height;
+          return (
+            <rect
+              key={i}
+              x={i * barW + 0.5}
+              y={height - h}
+              width={Math.max(1, barW - 1)}
+              height={Math.max(0.5, h)}
+              fill={color}
+              opacity={0.75}
+            />
+          );
+        })}
+        {markers.map((m) => (
+          <g key={m.key}>
+            <line x1={xFor(m.v)} x2={xFor(m.v)} y1={0} y2={height} stroke="#ffd54f" strokeDasharray="2,2" />
+            <text x={xFor(m.v)} y={height + 11} fontSize={9} fill="#ffd54f" textAnchor="middle" fontFamily="monospace">
+              {m.key} {m.v.toFixed(2)}
+            </text>
+          </g>
+        ))}
+      </svg>
+    </Box>
+  );
+}
+
+// ---------------------------------------------------------------- misc
+
+export function CompactStat({ label, value }: { label: string; value: ReactNode }) {
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', minWidth: 90 }}>
+      <Typography variant="caption" sx={{ color: '#8a949e', textTransform: 'uppercase', fontSize: 9.5 }}>
+        {label}
+      </Typography>
+      <Typography variant="body2" sx={{ fontFamily: 'monospace', fontWeight: 700 }}>
+        {value}
+      </Typography>
+    </Box>
+  );
+}
+
+export function compactWithExact(n: number | null | undefined): string {
+  if (n === null || n === undefined) return '—';
+  return `${fmtCompact(n)} (${Math.round(n).toLocaleString()})`;
+}

src/context/LabelEvalContext.tsx

@@ -2,6 +2,7 @@ import { createContext, useContext } from 'react';
 import type { StreamEvent } from '../types/labeleval';
 
 export type PageId =
+  | 'command'
   | 'overview'
   | 'datasets'
   | 'label-generation'
@@ -19,6 +20,7 @@ export type PageId =
   | 'legacy';
 
 export const ALL_PAGE_IDS: PageId[] = [
+  'command',
   'overview',
   'datasets',
   'label-generation',

src/pages/CommandCenterPage.tsx

@@ -0,0 +1,325 @@
+/**
+ * Evaluation Command Center — the aggregate-first landing page.
+ *
+ * Mental model surfaced in the UI:
+ *   Dataset (population) → Evaluation Run → Population → Cohort → Container → Annotation
+ * Aggregates come first; individual annotations are the deepest drill-down.
+ *
+ * Runs are async: launched runs are queued, progress streams over SSE
+ * (stream.megaeval.active_runs) with a 1.5s polling fallback on GET /runs/{id},
+ * and the page auto-refreshes when the run publishes.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import Alert from '@mui/material/Alert';
+import Box from '@mui/material/Box';
+import Tab from '@mui/material/Tab';
+import Tabs from '@mui/material/Tabs';
+import Typography from '@mui/material/Typography';
+import type { EvaluationRunInfo, ReviewState, RunStatus } from '../types/megaeval';
+import {
+  getCacheStats,
+  getPopulations,
+  getRun,
+  getRunReview,
+  getRuns,
+} from '../services/megaeval';
+import { usePoll } from '../services/labeleval';
+import { useLabelEval } from '../context/LabelEvalContext';
+import { EmptyState, ErrorNote, LoadingBox, SectionCard } from '../components/labeleval/shared';
+import HeaderBar, {
+  GeneratePopulationButton,
+  NewRunButton,
+} from '../components/megaeval/HeaderBar';
+import RunProgressCard from '../components/megaeval/RunProgressCard';
+import HeroRow from '../components/megaeval/HeroRow';
+import QualityTab from '../components/megaeval/QualityTab';
+import CohortTab from '../components/megaeval/CohortTab';
+import ContainersTab from '../components/megaeval/ContainersTab';
+import InvestigationTab from '../components/megaeval/InvestigationTab';
+import CompareTab from '../components/megaeval/CompareTab';
+import ReviewTab from '../components/megaeval/ReviewTab';
+import ShiftTab from '../components/megaeval/ShiftTab';
+import LineageCard from '../components/megaeval/LineageCard';
+
+const ACTIVE_STATUSES: RunStatus[] = ['created', 'queued', 'running', 'reducing', 'materializing'];
+
+type TabId =
+  | 'quality'
+  | 'cohorts'
+  | 'containers'
+  | 'investigation'
+  | 'compare'
+  | 'review'
+  | 'shift'
+  | 'lineage';
+
+export default function CommandCenterPage() {
+  const { stream, entityId, navigate } = useLabelEval();
+
+  const populationsPoll = usePoll(getPopulations, 15000);
+  const runsPoll = usePoll(getRuns, 8000);
+  const cachePoll = usePoll(getCacheStats, 10000);
+
+  const populations = useMemo(() => {
+    const list = populationsPoll.data?.populations ?? [];
+    return [...list].sort((a, b) => (b.created_at ?? '').localeCompare(a.created_at ?? ''));
+  }, [populationsPoll.data]);
+  const runs = useMemo(() => runsPoll.data?.runs ?? [], [runsPoll.data]);
+
+  const [populationId, setPopulationId] = useState<string | null>(null);
+  const [runId, setRunId] = useState<string | null>(entityId);
+  const [baselineRunId, setBaselineRunId] = useState<string | null>(null);
+  const [tab, setTab] = useState<TabId>('quality');
+  const [drillContainerId, setDrillContainerId] = useState<number | null>(null);
+  const [publishTick, setPublishTick] = useState(0);
+  const [review, setReview] = useState<ReviewState | null>(null);
+  const [selectedRun, setSelectedRun] = useState<EvaluationRunInfo | null>(null);
+  const [runError, setRunError] = useState<string | null>(null);
+
+  // Explicit selection persists the run in the URL hash (#/command/<run_id>).
+  const selectRun = useCallback(
+    (id: string) => {
+      setRunId(id);
+      setDrillContainerId(null);
+      navigate('command', id);
+    },
+    [navigate]
+  );
+
+  // Follow hash changes (back/forward navigation, deep links).
+  useEffect(() => {
+    if (entityId && entityId !== runId) {
+      setRunId(entityId);
+      setDrillContainerId(null);
+    }
+  }, [entityId]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  // Default selections once data arrives.
+  useEffect(() => {
+    if (!populationId && populations.length) setPopulationId(populations[0].population_id);
+  }, [populations, populationId]);
+
+  useEffect(() => {
+    if (!runId && runs.length) {
+      const byCreated = [...runs].sort((a, b) => (b.created_at ?? '').localeCompare(a.created_at ?? ''));
+      const pick = byCreated.find((r) => r.status === 'published') ?? byCreated[0];
+      if (pick) setRunId(pick.run_id);
+    }
+  }, [runs, runId]);
+
+  // Selected run detail: 1.5s polling while the run is in flight (SSE-independent fallback).
+  useEffect(() => {
+    setSelectedRun(null);
+    setRunError(null);
+    if (!runId) return;
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const load = async () => {
+      try {
+        const info = await getRun(runId);
+        if (cancelled) return;
+        setSelectedRun(info);
+        setRunError(null);
+        if (info.status !== 'published' && info.status !== 'failed') timer = setTimeout(() => void load(), 1500);
+      } catch (err) {
+        if (cancelled) return;
+        setRunError(err instanceof Error ? err.message : String(err));
+        timer = setTimeout(() => void load(), 3000);
+      }
+    };
+    void load();
+    return () => {
+      cancelled = true;
+      if (timer) clearTimeout(timer);
+    };
+  }, [runId]);
+
+  // Auto-refresh all panels when the selected run publishes.
+  const prevStatusRef = useRef<RunStatus | null>(null);
+  const runsRefresh = runsPoll.refresh;
+  useEffect(() => {
+    const status = selectedRun?.status ?? null;
+    if (status === 'published' && prevStatusRef.current && prevStatusRef.current !== 'published') {
+      setPublishTick((t) => t + 1);
+      runsRefresh();
+    }
+    prevStatusRef.current = status;
+  }, [selectedRun?.status, runsRefresh]);
+
+  const published = selectedRun?.status === 'published';
+
+  // Review state (shared by the hero CI annotations and the Review tab).
+  useEffect(() => {
+    setReview(null);
+    if (!runId || !published) return;
+    let cancelled = false;
+    getRunReview(runId)
+      .then((r) => {
+        if (!cancelled) setReview(r);
+      })
+      .catch(() => undefined);
+    return () => {
+      cancelled = true;
+    };
+  }, [runId, published, publishTick]);
+
+  const megaStatus = stream?.megaeval ?? null;
+  const cache = megaStatus?.cache ?? cachePoll.data ?? null;
+
+  // Prefer SSE progress for the selected run when it is fresher than the poll.
+  const streamProgress = megaStatus?.active_runs.find((r) => r.run_id === runId) ?? null;
+  const selectedInFlight =
+    selectedRun && ACTIVE_STATUSES.includes(selectedRun.status) ? streamProgress ?? selectedRun : null;
+  const otherActiveRuns = (megaStatus?.active_runs ?? []).filter((r) => r.run_id !== runId);
+
+  const openContainer = useCallback((cid: number) => {
+    setDrillContainerId(cid);
+    setTab('containers');
+  }, []);
+
+  const initialLoading =
+    populationsPoll.loading && !populationsPoll.data && runsPoll.loading && !runsPoll.data;
+  const noPopulation = populationsPoll.data !== null && populations.length === 0;
+  const noRuns = !noPopulation && runsPoll.data !== null && runs.length === 0;
+
+  const onPopulationGenerated = useCallback(
+    (pop: { population_id: string }) => {
+      populationsPoll.refresh();
+      setPopulationId(pop.population_id);
+    },
+    [populationsPoll]
+  );
+
+  const onRunCreated = useCallback(
+    (run: EvaluationRunInfo) => {
+      runsRefresh();
+      selectRun(run.run_id);
+    },
+    [runsRefresh, selectRun]
+  );
+
+  if (initialLoading) return <LoadingBox label="Loading command center…" />;
+
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 2 }}>
+      {populationsPoll.error && !populationsPoll.data ? <ErrorNote error={populationsPoll.error} /> : null}
+
+      <HeaderBar
+        populations={populations}
+        populationId={populationId}
+        onPopulationChange={setPopulationId}
+        runs={runs}
+        runId={runId}
+        onRunChange={selectRun}
+        baselineRunId={baselineRunId}
+        onBaselineChange={setBaselineRunId}
+        selectedRun={selectedRun}
+        cache={cache}
+        onGenerated={onPopulationGenerated}
+        onRunCreated={onRunCreated}
+      />
+
+      <Typography variant="caption" sx={{ color: '#8a949e', mt: -1 }}>
+        Dataset (population) → Evaluation run → Population → Cohort → Container → Annotation — aggregates first,
+        individual annotations only at the deepest drill-down.
+      </Typography>
+
+      {/* Empty states: nothing generated / no runs yet */}
+      {noPopulation ? (
+        <SectionCard title="Welcome to the Evaluation Command Center">
+          <EmptyState
+            title="No evaluation population yet"
+            message="Generate a synthetic mega-scale population (hundreds of thousands of annotated objects across weather, lighting, scenario and sensor cohorts), then launch an evaluation run against it."
+            action={
+              <Box sx={{ display: 'flex', gap: 1.5, justifyContent: 'center' }}>
+                <GeneratePopulationButton variant="contained" size="large" onGenerated={onPopulationGenerated} />
+              </Box>
+            }
+          />
+        </SectionCard>
+      ) : null}
+
+      {noRuns ? (
+        <SectionCard title="Population ready — no evaluation runs yet">
+          <EmptyState
+            title="Launch your first evaluation run"
+            message="An evaluation run scores every object in the population against a model version, then materializes the aggregate cube, error index and sketches that power this page."
+            action={
+              <Box sx={{ display: 'flex', gap: 1.5, justifyContent: 'center' }}>
+                <NewRunButton variant="contained" size="large" populationId={populationId} onCreated={onRunCreated} />
+                <GeneratePopulationButton variant="outlined" size="large" onGenerated={onPopulationGenerated} />
+              </Box>
+            }
+          />
+        </SectionCard>
+      ) : null}
+
+      {runError && !selectedRun ? <ErrorNote error={runError} /> : null}
+
+      {/* Live progress for the selected run + any other active runs */}
+      {selectedInFlight ? <RunProgressCard progress={selectedInFlight} /> : null}
+      {otherActiveRuns.map((r) => (
+        <RunProgressCard key={r.run_id} progress={r} />
+      ))}
+
+      {selectedRun?.status === 'failed' ? (
+        <Alert severity="error" variant="outlined">
+          Run {selectedRun.run_id.slice(0, 8)} failed{selectedRun.error ? `: ${selectedRun.error}` : '.'} Launch a new
+          evaluation run from the header.
+        </Alert>
+      ) : null}
+
+      {/* Hero aggregates + tab sections (published runs only) */}
+      {published && selectedRun ? (
+        <>
+          <HeroRow run={selectedRun} review={review} refreshKey={publishTick} />
+
+          <Tabs
+            value={tab}
+            onChange={(_, v: TabId) => setTab(v)}
+            variant="scrollable"
+            scrollButtons="auto"
+            sx={{
+              minHeight: 36,
+              borderBottom: '1px solid #232a31',
+              '& .MuiTab-root': { minHeight: 36, py: 0.5 },
+            }}
+          >
+            <Tab label="Quality" value="quality" />
+            <Tab label="Cohorts" value="cohorts" />
+            <Tab label="Containers" value="containers" />
+            <Tab label="Investigation" value="investigation" />
+            <Tab label="Compare" value="compare" />
+            <Tab label="Review" value="review" />
+            <Tab label="Shift" value="shift" />
+            <Tab label="Lineage" value="lineage" />
+          </Tabs>
+
+          {tab === 'quality' ? (
+            <QualityTab runId={selectedRun.run_id} runs={runs} refreshKey={publishTick} />
+          ) : null}
+          {tab === 'cohorts' ? <CohortTab runId={selectedRun.run_id} refreshKey={publishTick} /> : null}
+          {tab === 'containers' ? (
+            <ContainersTab
+              runId={selectedRun.run_id}
+              refreshKey={publishTick}
+              drillContainerId={drillContainerId}
+              onDrill={setDrillContainerId}
+            />
+          ) : null}
+          {tab === 'investigation' ? (
+            <InvestigationTab runId={selectedRun.run_id} onOpenContainer={openContainer} />
+          ) : null}
+          {tab === 'compare' ? (
+            <CompareTab runId={selectedRun.run_id} baselineRunId={baselineRunId} refreshKey={publishTick} />
+          ) : null}
+          {tab === 'review' ? (
+            <ReviewTab runId={selectedRun.run_id} review={review} onReview={setReview} />
+          ) : null}
+          {tab === 'shift' ? <ShiftTab runId={selectedRun.run_id} refreshKey={publishTick} /> : null}
+          {tab === 'lineage' ? <LineageCard lineage={selectedRun.lineage} /> : null}
+        </>
+      ) : null}
+    </Box>
+  );
+}

src/services/labeleval.ts

@@ -34,6 +34,8 @@ import type {
   TrainRequest,
   TrainResponse,
 } from '../types/labeleval';
+import type { MegaevalStatus } from '../types/megaeval';
+import { getMegaevalStatus } from './megaeval';
 
 async function handle<T>(res: Response): Promise<T> {
   if (!res.ok) {
@@ -232,12 +234,19 @@ export function useStream(): StreamEvent | null {
           } catch {
             /* keep previous alert count */
           }
+          let megaeval: MegaevalStatus | undefined;
+          try {
+            megaeval = await getMegaevalStatus();
+          } catch {
+            /* megaeval layer unavailable — leave the field absent */
+          }
           if (!disposed) {
             setEvent({
               ts: new Date().toISOString(),
               pipeline,
               training: null,
               alerts_count: lastAlerts,
+              ...(megaeval ? { megaeval } : {}),
             });
           }
         } catch {

src/services/megaeval.ts

@@ -0,0 +1,152 @@
+/**
+ * Typed fetch wrappers for the aggregate-first mega-scale evaluation API
+ * ("megaeval"). Mirrors the style of services/labeleval.ts.
+ *
+ * Async run semantics: POST /runs returns immediately with status "queued";
+ * results endpoints return HTTP 409 until the run is "published".
+ */
+import type {
+  CacheStats,
+  CompareRequest,
+  CompareResponse,
+  ContainerObjectsResponse,
+  ContainerSortPreset,
+  ContainersResponse,
+  CreateRunRequest,
+  DimName,
+  DistributionsResponse,
+  ErrorSearchRequest,
+  ErrorSearchResponse,
+  EvaluationQueryRequest,
+  EvaluationQueryResponse,
+  EvaluationRunInfo,
+  GeneratePopulationRequest,
+  MegaevalStatus,
+  PopulationMeta,
+  QualityFunnelResponse,
+  ReviewState,
+  ShiftResponse,
+  SimilarityRequest,
+  SimilarityResponse,
+  WhyRequest,
+  WhyResponse,
+} from '../types/megaeval';
+
+async function handle<T>(res: Response): Promise<T> {
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`API ${res.status}: ${body || res.statusText}`);
+  }
+  return res.json() as Promise<T>;
+}
+
+const JSON_HEADERS = { 'Content-Type': 'application/json' };
+
+function get<T>(url: string): Promise<T> {
+  return fetch(url).then((res) => handle<T>(res));
+}
+
+function post<T>(url: string, body?: unknown): Promise<T> {
+  return fetch(url, {
+    method: 'POST',
+    headers: JSON_HEADERS,
+    body: body === undefined ? undefined : JSON.stringify(body),
+  }).then((res) => handle<T>(res));
+}
+
+// ---------------------------------------------------------------- populations
+
+export const generatePopulation = (body: GeneratePopulationRequest) =>
+  post<PopulationMeta>('/api/megaeval/population/generate', body);
+
+export const getPopulations = () =>
+  get<{ populations: PopulationMeta[] }>('/api/megaeval/populations');
+
+export const getDimensions = () =>
+  get<{ dimensions: Record<DimName, string[]> }>('/api/megaeval/dimensions');
+
+// ---------------------------------------------------------------- runs
+
+export const createRun = (body: CreateRunRequest) =>
+  post<EvaluationRunInfo>('/api/megaeval/runs', body);
+
+export const getRuns = () => get<{ runs: EvaluationRunInfo[] }>('/api/megaeval/runs');
+
+export const getRun = (runId: string) =>
+  get<EvaluationRunInfo>(`/api/megaeval/runs/${encodeURIComponent(runId)}`);
+
+export const getMegaevalStatus = () => get<MegaevalStatus>('/api/megaeval/status');
+
+// ---------------------------------------------------------------- query / cache
+
+export const queryEvaluations = (body: EvaluationQueryRequest) =>
+  post<EvaluationQueryResponse>('/api/evaluations/query', body);
+
+export const getCacheStats = () => get<CacheStats>('/api/megaeval/cache');
+
+// ---------------------------------------------------------------- run results
+
+export const getRunFunnel = (runId: string) =>
+  get<QualityFunnelResponse>(`/api/megaeval/runs/${encodeURIComponent(runId)}/funnel`);
+
+export const getRunContainers = (
+  runId: string,
+  sort: ContainerSortPreset = 'highest_risk',
+  limit = 50,
+  offset = 0
+) =>
+  get<ContainersResponse>(
+    `/api/megaeval/runs/${encodeURIComponent(runId)}/containers?sort=${encodeURIComponent(
+      sort
+    )}&limit=${limit}&offset=${offset}`
+  );
+
+export const getContainerObjects = (runId: string, containerId: number) =>
+  get<ContainerObjectsResponse>(
+    `/api/megaeval/runs/${encodeURIComponent(runId)}/containers/${containerId}/objects`
+  );
+
+export const searchErrors = (body: ErrorSearchRequest) =>
+  post<ErrorSearchResponse>('/api/megaeval/errors/search', body);
+
+export const compareRuns = (body: CompareRequest) =>
+  post<CompareResponse>('/api/megaeval/compare', body);
+
+export const getRunShift = (runId: string) =>
+  get<ShiftResponse>(`/api/megaeval/runs/${encodeURIComponent(runId)}/shift`);
+
+export const whyAnalysis = (body: WhyRequest) => post<WhyResponse>('/api/megaeval/why', body);
+
+export const findSimilarContainers = (body: SimilarityRequest) =>
+  post<SimilarityResponse>('/api/megaeval/similarity', body);
+
+// ---------------------------------------------------------------- review sampling
+
+export const getRunReview = (runId: string) =>
+  get<ReviewState>(`/api/megaeval/runs/${encodeURIComponent(runId)}/review`);
+
+export const planReview = (runId: string, targetN?: number) =>
+  post<ReviewState>(
+    `/api/megaeval/runs/${encodeURIComponent(runId)}/review/plan`,
+    targetN !== undefined ? { target_n: targetN } : {}
+  );
+
+export const executeReview = (runId: string) =>
+  post<ReviewState>(`/api/megaeval/runs/${encodeURIComponent(runId)}/review/execute`);
+
+// ---------------------------------------------------------------- distributions
+
+export const getRunDistributions = (runId: string) =>
+  get<DistributionsResponse>(`/api/megaeval/runs/${encodeURIComponent(runId)}/distributions`);
+
+// ---------------------------------------------------------------- formatting
+
+/** Compact count formatting for large aggregates: 950 -> "950", 214_700 -> "214.7K", 1_300_000 -> "1.3M". */
+export function fmtCompact(n: number | null | undefined): string {
+  if (n === null || n === undefined || Number.isNaN(n)) return '—';
+  const abs = Math.abs(n);
+  if (abs >= 1e9) return `${(n / 1e9).toFixed(1)}B`;
+  if (abs >= 1e6) return `${(n / 1e6).toFixed(1)}M`;
+  if (abs >= 1e3) return `${(n / 1e3).toFixed(1)}K`;
+  return Math.round(n).toLocaleString();
+}

src/types/labeleval.ts

@@ -4,6 +4,8 @@
  * Keep field names snake_case to match the JSON wire format exactly.
  */
 
+import type { MegaevalStatus } from './megaeval';
+
 // ---------------------------------------------------------------- enums
 
 export type GroundTruthType =
@@ -586,4 +588,6 @@ export interface StreamEvent {
   pipeline: PipelineStateResponse;
   training: TrainingJobStatus | null;
   alerts_count: number;
+  /** Mega-scale evaluation layer status; absent on older backends and in the polling fallback. */
+  megaeval?: MegaevalStatus;
 }

src/types/megaeval.ts

@@ -0,0 +1,536 @@
+/**
+ * API contract for the aggregate-first mega-scale evaluation layer (megaeval).
+ *
+ * Mental model: Dataset (population) -> Evaluation Run -> Population -> Cohort
+ *               -> Container -> Annotation (deepest, forensic drill-down only).
+ *
+ * Endpoints (all JSON):
+ *   POST /api/megaeval/population/generate     GeneratePopulationRequest -> PopulationMeta
+ *   GET  /api/megaeval/populations             -> { populations: PopulationMeta[] }
+ *   GET  /api/megaeval/dimensions              -> { dimensions: Record<DimName, string[]> }
+ *   POST /api/megaeval/runs                    CreateRunRequest -> EvaluationRunInfo (async job!)
+ *   GET  /api/megaeval/runs                    -> { runs: EvaluationRunInfo[] }
+ *   GET  /api/megaeval/runs/{run_id}           -> EvaluationRunInfo
+ *   GET  /api/megaeval/status                  -> MegaevalStatus (also inside SSE stream)
+ *   POST /api/evaluations/query                EvaluationQueryRequest -> EvaluationQueryResponse
+ *   GET  /api/megaeval/cache                   -> CacheStats
+ *   GET  /api/megaeval/runs/{id}/funnel        -> QualityFunnelResponse
+ *   GET  /api/megaeval/runs/{id}/containers?sort=&limit=&offset= -> ContainersResponse
+ *   GET  /api/megaeval/runs/{id}/containers/{cid}/objects -> ContainerObjectsResponse
+ *   POST /api/megaeval/errors/search           ErrorSearchRequest -> ErrorSearchResponse
+ *   POST /api/megaeval/compare                 CompareRequest -> CompareResponse
+ *   GET  /api/megaeval/runs/{id}/shift         -> ShiftResponse
+ *   POST /api/megaeval/why                     WhyRequest -> WhyResponse
+ *   POST /api/megaeval/similarity              SimilarityRequest -> SimilarityResponse
+ *   GET  /api/megaeval/runs/{id}/review        -> ReviewState
+ *   POST /api/megaeval/runs/{id}/review/plan   { target_n?: number } -> ReviewState
+ *   POST /api/megaeval/runs/{id}/review/execute -> ReviewState
+ *   GET  /api/megaeval/runs/{id}/distributions -> DistributionsResponse
+ *
+ * Notes:
+ * - Runs are async: POST /runs returns immediately with status "queued"; poll
+ *   GET /runs/{id} or use the SSE stream's `megaeval.active_runs` for progress.
+ * - Results endpoints return HTTP 409 until the run is "published".
+ * - Query responses carry meta.source ("cache"|"cube"|"scan"), meta.cache_hit and
+ *   meta.latency_ms — the UI should surface these as badges.
+ * - meta.exact=false means sketch-derived (approximate) numbers are included.
+ */
+
+export type DimName =
+  | 'class' | 'weather' | 'lighting' | 'road_type' | 'scenario'
+  | 'sensor' | 'distance_band' | 'speed_band' | 'occlusion';
+
+export const DIM_NAMES: DimName[] = [
+  'class', 'weather', 'lighting', 'road_type', 'scenario',
+  'sensor', 'distance_band', 'speed_band', 'occlusion',
+];
+
+export type RunStatus =
+  | 'created' | 'queued' | 'running' | 'reducing' | 'materializing'
+  | 'published' | 'failed';
+
+// ---------------------------------------------------------------- populations
+
+export interface GeneratePopulationRequest {
+  name?: string;
+  num_objects?: number; // 1_000 .. 1_200_000, default 320_000
+  seed?: number;
+}
+
+export interface TrainMixRow {
+  class: string;
+  weather: string;
+  lighting: string;
+  train_share: number;
+  eval_share: number;
+  eval_count: number;
+}
+
+export interface PopulationMeta {
+  population_id: string;
+  name: string;
+  created_at: string;
+  seed: number;
+  num_objects: number;
+  num_containers: number;
+  num_partitions: number;
+  avg_objects_per_container: number;
+  dimensions: Record<DimName, string[]>;
+  dim_counts: Record<DimName, Record<string, number>>;
+  safety_critical_count: number;
+  train_mix: TrainMixRow[];
+}
+
+// ---------------------------------------------------------------- runs
+
+export interface CreateRunRequest {
+  population_id: string;
+  model_version: string;
+  overrides?: Record<string, number>; // e.g. { night_penalty: 0.3 } to demo a regression
+  worker_delay_s?: number;            // simulated distributed I/O per partition (default 0.5)
+  workers?: number;                   // default 4
+  seed?: number | null;
+  label_version?: string;
+}
+
+export interface RunProgress {
+  run_id: string;
+  population_id: string;
+  model_version: string;
+  status: RunStatus;
+  percent: number;
+  partitions_done: number;
+  partitions_total: number;
+  objects_processed: number;
+  objects_total: number;
+  workers: number;
+  throughput_objs_per_s: number;
+  eta_s: number | null;
+  error: string | null;
+}
+
+export interface RunLineage {
+  evaluation_id: string;
+  dataset_version: string;
+  model_version: string;
+  model_checkpoint: string;
+  label_version: string;
+  evaluator_code_version: string;
+  metric_version: string;
+  threshold_config: Record<string, number>;
+  sampling_config: Record<string, unknown>;
+  seed: number;
+  hardware: string;
+  timestamp: string;
+}
+
+export interface RunHeadline {
+  n: number;
+  tp?: number;
+  fp?: number;
+  fn?: number;
+  loc_err?: number;
+  anomalies?: number;
+  precision?: number | null;
+  recall?: number | null;
+  f1?: number | null;
+  mean_iou?: number | null;
+  anomaly_rate?: number | null;
+  safety_recall?: number | null;
+  conf_mean?: number | null;
+  error_rate?: number | null;
+  containers?: number;
+  containers_hll_estimate?: number;
+}
+
+export interface EvaluationRunInfo extends RunProgress {
+  created_at: string;
+  started_at: string | null;
+  published_at: string | null;
+  lineage: RunLineage;
+  headline: RunHeadline;                       // {} until published
+  per_class: Record<string, QueryRow>;         // {} until published
+  overrides: Record<string, number>;
+}
+
+export interface CacheStats {
+  entries: number;
+  hits: number;
+  misses: number;
+  hit_rate: number | null;
+}
+
+export interface MegaevalStatus {
+  active_runs: RunProgress[];
+  cache: CacheStats | null;
+  total_runs: number;
+}
+
+// ---------------------------------------------------------------- query API
+
+export type MetricName =
+  | 'n' | 'tp' | 'fp' | 'fn' | 'loc_err' | 'anomalies' | 'reviewed' | 'verified'
+  | 'safety_n' | 'safety_tp'
+  | 'precision' | 'recall' | 'f1' | 'mean_iou' | 'anomaly_rate'
+  | 'conf_mean' | 'conf_std' | 'safety_recall' | 'review_coverage'
+  | 'verified_rate' | 'error_rate'
+  | 'confidence_p50' | 'confidence_p10' | 'confidence_p90'
+  | 'iou_p50' | 'iou_p10' | 'iou_p90';
+
+export interface EvaluationQueryRequest {
+  evaluation_id: string;                    // run_id
+  filters?: Partial<Record<DimName, string[]>>;
+  metrics?: MetricName[];
+  group_by?: DimName[];
+  limit?: number;
+}
+
+/** One aggregate row: group_by dims as strings + requested metrics. n always present. */
+export type QueryRow = { n: number } & Record<string, string | number | null>;
+
+export interface QueryMeta {
+  source: 'cache' | 'cube' | 'scan';
+  cache_hit: boolean;
+  latency_ms: number;
+  cells_touched: number;
+  exact: boolean;
+  approximate_fields: string[];
+}
+
+export interface EvaluationQueryResponse {
+  rows: QueryRow[];
+  meta: QueryMeta;
+}
+
+// ---------------------------------------------------------------- funnel
+
+export interface FunnelStage {
+  stage: string;
+  count: number;
+  pct_of_population: number;
+}
+
+export interface QualityFunnelResponse {
+  stages: FunnelStage[];
+  estimated_precision: {
+    estimate: number | null;
+    ci_low: number | null;
+    ci_high: number | null;
+    n_reviewed: number | null;
+  } | null;
+}
+
+// ---------------------------------------------------------------- containers
+
+export type ContainerSortPreset =
+  | 'worst_recall' | 'worst_precision' | 'worst_iou'
+  | 'most_anomalies' | 'least_verified' | 'highest_risk';
+
+export interface ContainerRow {
+  container_id: number;
+  weather: string;
+  lighting: string;
+  road_type: string;
+  scenario: string;
+  n_objects: number;
+  tp: number;
+  fp: number;
+  fn: number;
+  anomalies: number;
+  reviewed: number;
+  verified: number;
+  recall: number | null;
+  precision: number | null;
+  mean_iou: number | null;
+  risk_score: number;
+  status: 'ok' | 'warn' | 'critical';
+}
+
+export interface ContainersResponse {
+  total: number;
+  sort: string;
+  rows: ContainerRow[];
+}
+
+/** Forensic object row — the deepest drill-down (old annotation-table level). */
+export interface ContainerObject {
+  annotation_id: string;
+  container_id: number;
+  class: string;
+  weather: string;
+  lighting: string;
+  road_type: string;
+  scenario: string;
+  sensor: string;
+  distance_band: string;
+  speed_band: string;
+  occlusion: string;
+  safety_critical: boolean;
+  difficulty: number | null;
+  detected: boolean;
+  outcome: 'TP' | 'FN' | 'FP' | 'LOCALIZATION';
+  iou: number | null;
+  confidence: number | null;
+  anomaly: boolean;
+  sensor_disagree: boolean;
+}
+
+export interface ContainerObjectsResponse {
+  container_id: number;
+  objects: ContainerObject[];
+}
+
+// ---------------------------------------------------------------- error index
+
+export type ErrorType = 'FN' | 'FP' | 'LOCALIZATION' | 'ANOMALY' | 'LOW_CONF';
+
+export interface ErrorSearchRequest {
+  run_id: string;
+  error_types?: ErrorType[];
+  filters?: Partial<Record<DimName, string[]>>;
+  confidence_max?: number | null;
+  confidence_min?: number | null;
+  risk_min?: number | null;
+  severity_min?: number | null;
+  safety_only?: boolean;
+  limit_containers?: number;
+}
+
+export interface WorstContainer {
+  container_id: number;
+  error_count: number;
+  mean_risk: number;
+  max_severity: number;
+  safety_hits: number;
+  weather?: string;
+  lighting?: string;
+  road_type?: string;
+  scenario?: string;
+  n_objects?: number;
+  risk_score?: number;
+}
+
+export interface ErrorExample {
+  error_id: number;
+  annotation_id: string;
+  container_id: number;
+  error_type: ErrorType;
+  class: string;
+  severity: number;
+  confidence: number;
+  risk_score: number;
+  safety_critical: boolean;
+  scenario: string;
+  lighting: string;
+  weather: string;
+}
+
+export interface ErrorSearchResponse {
+  matched_errors: number;
+  by_type: Partial<Record<ErrorType, number>>;
+  worst_containers: WorstContainer[];
+  examples: ErrorExample[];
+}
+
+// ---------------------------------------------------------------- compare
+
+export interface HeadlineDelta {
+  metric: string;
+  baseline: number;
+  candidate: number;
+  delta: number;
+}
+
+export interface PerClassDelta {
+  class: string;
+  n: number | null;
+  recall_baseline: number | null;
+  recall_candidate: number | null;
+  recall_delta: number;
+  precision_baseline: number | null;
+  precision_candidate: number | null;
+  precision_delta: number;
+}
+
+export interface CohortDelta {
+  cohort: string; // e.g. "highway/night/cyclist"
+  road_type?: string;
+  lighting?: string;
+  class?: string;
+  n: number;
+  recall_baseline: number;
+  recall_candidate: number;
+  recall_delta: number;
+}
+
+export interface CompareRequest {
+  candidate_run_id: string;
+  baseline_run_id: string;
+  policy?: Record<string, unknown>;
+}
+
+export interface CompareResponse {
+  candidate: { run_id: string; model_version: string };
+  baseline: { run_id: string; model_version: string };
+  headline_deltas: HeadlineDelta[];
+  per_class: PerClassDelta[];
+  worst_cohorts: CohortDelta[];
+  regressions: CohortDelta[];
+  policy: Record<string, unknown>;
+  recommendation: 'PROMOTE' | 'DO_NOT_PROMOTE';
+  blockers: string[];
+}
+
+// ---------------------------------------------------------------- review sampling
+
+export interface StratumResult {
+  stratum: string;
+  N: number;
+  n: number;
+  correct: number;
+  p: number;
+  wilson_ci: [number, number];
+  weight: number;
+}
+
+export interface MetricEstimate {
+  estimate: number;
+  ci_low: number;
+  ci_high: number;
+  n_reviewed: number;
+  frame_size: number;
+  method: string;
+  strata: StratumResult[];
+}
+
+export interface SamplingFunnel {
+  population_objects: number;
+  containers: number;
+  suspicious_containers: number;
+  candidate_pool: number;
+  statistically_selected: number;
+  reviewed: number;
+}
+
+export interface StratumPlan {
+  label: string;
+  N: number;
+  allocated: number;
+}
+
+export interface ReviewState {
+  run_id: string;
+  planned: boolean;
+  executed: boolean;
+  method?: string;
+  target_n?: number;
+  funnel?: SamplingFunnel;
+  strata?: {
+    precision: Record<string, StratumPlan>;
+    recall: Record<string, StratumPlan>;
+  };
+  results?: {
+    precision: MetricEstimate;
+    recall: MetricEstimate;
+  } | null;
+}
+
+// ---------------------------------------------------------------- shift / why / similarity
+
+export interface ShiftRow {
+  cohort: string;
+  class: string;
+  weather: string;
+  lighting: string;
+  train_share: number;
+  eval_share: number;
+  relative_change: number; // e.g. +0.90 == +90%
+  eval_count: number;
+  cohort_recall: number | null;
+  overall_recall: number | null;
+  recall_gap: number | null;
+}
+
+export interface ShiftResponse {
+  run_id: string;
+  shifts: ShiftRow[];
+  method: string;
+  thresholds: { min_eval_count: number; rel_threshold: number };
+}
+
+export interface WhyRequest {
+  run_id: string;
+  filters?: Partial<Record<DimName, string[]>>;
+  metric?: 'recall' | 'precision';
+}
+
+export interface WhyFactor {
+  factor: 'occlusion' | 'low_illumination' | 'long_range' | 'sensor_disagreement' | 'other';
+  count: number;
+  share: number;
+}
+
+export interface WhyCohort {
+  cohort: string;
+  n: number;
+  fn?: number | null;
+  fp?: number | null;
+  [metric: string]: string | number | null | undefined;
+}
+
+export interface WhyResponse {
+  metric: string;
+  filters: Partial<Record<DimName, string[]>>;
+  failure_count: number;
+  factors: WhyFactor[];
+  top_cohorts: WhyCohort[];
+  method: string;
+}
+
+export interface SimilarityRequest {
+  run_id: string;
+  container_id: number;
+  filters?: Partial<Record<DimName, string[]>>;
+  k?: number;
+}
+
+export interface SimilarContainer {
+  container_id: number;
+  similarity: number;
+  weather: string;
+  lighting: string;
+  road_type: string;
+  scenario: string;
+  n_objects: number;
+  fn: number;
+  fp: number;
+  anomalies: number;
+  risk_score: number;
+}
+
+export interface SimilarityResponse {
+  query_container: number;
+  retrieval?: string;
+  results: SimilarContainer[];
+}
+
+// ---------------------------------------------------------------- distributions
+
+export interface HistogramSketch {
+  bins: number;
+  lo: number;
+  hi: number;
+  counts: number[];
+  percentiles: Record<string, number>;
+}
+
+export interface DistributionsResponse {
+  run_id: string;
+  exact: false;
+  note: string;
+  confidence?: HistogramSketch;
+  iou?: HistogramSketch;
+  containers_hll_estimate: number | null;
+  containers_exact: number | null;
+  available_sketch_metrics: string[];
+}

tests/test_megaeval/conftest.py

@@ -0,0 +1,36 @@
+"""Shared fixtures: an isolated megaeval root with a small population and two
+published runs (a good candidate and a deliberately regressed one)."""
+
+from __future__ import annotations
+
+import pytest
+
+from sensorflow.megaeval import population as pop_mod
+from sensorflow.megaeval.runs import get_mega_store, reset_mega_store
+
+
+@pytest.fixture(scope="session")
+def mega_env(tmp_path_factory):
+    root = tmp_path_factory.mktemp("megaeval")
+    pop_mod.set_mega_root(str(root))
+    reset_mega_store()
+    meta = pop_mod.generate_population("test-pop", num_objects=8_000, seed=17)
+    store = get_mega_store()
+
+    good = store.create_run(population_id=meta["population_id"],
+                            model_version="model-v41", worker_delay_s=0.0)
+    store.execute_sync(good)
+    assert good.status == "published", good.error
+
+    bad = store.create_run(population_id=meta["population_id"],
+                           model_version="model-v42-regressed",
+                           overrides={"night_penalty": 0.35, "vru_penalty": 0.12},
+                           worker_delay_s=0.0)
+    store.execute_sync(bad)
+    assert bad.status == "published", bad.error
+
+    yield {"root": root, "meta": meta, "store": store, "good": good, "bad": bad}
+
+    # restore defaults for any later suites
+    pop_mod.set_mega_root("runs/megaeval")
+    reset_mega_store()

tests/test_megaeval/test_analysis.py

@@ -0,0 +1,76 @@
+"""Model-vs-model comparison, distribution shift, why-layer, similarity."""
+
+from __future__ import annotations
+
+from sensorflow.megaeval import analysis
+
+
+def test_compare_detects_injected_regression(mega_env):
+    store = mega_env["store"]
+    cmp = analysis.compare_runs(store, mega_env["bad"], mega_env["good"])
+    assert cmp["recommendation"] == "DO_NOT_PROMOTE"
+    assert cmp["blockers"]
+    hd = {h["metric"]: h["delta"] for h in cmp["headline_deltas"]}
+    assert hd["recall"] < 0
+    assert hd["safety_recall"] < 0
+    # injected night+VRU penalty must surface night cohorts among worst regressions
+    assert any("night" in c["cohort"] for c in cmp["worst_cohorts"][:8])
+    assert any("REGRESSION" in b for b in cmp["blockers"])
+
+
+def test_compare_promotes_equivalent_model(mega_env):
+    store, meta = mega_env["store"], mega_env["meta"]
+    good = mega_env["good"]
+    twin = store.create_run(population_id=meta["population_id"],
+                            model_version=good.model_version, worker_delay_s=0.0)
+    store.execute_sync(twin)
+    cmp = analysis.compare_runs(store, twin, good)
+    assert cmp["recommendation"] == "PROMOTE"
+    assert cmp["blockers"] == []
+
+
+def test_compare_writes_legacy_regression_result(mega_env):
+    from sensorflow.evaluation.records import get_store as legacy_store
+    analysis.compare_runs(mega_env["store"], mega_env["bad"], mega_env["good"])
+    results = legacy_store().all("regressions")
+    ours = [r for r in results if r.model_version == mega_env["bad"].model_version]
+    assert ours and ours[-1].regression_detected
+
+
+def test_distribution_shift_flags_underrepresented_cohorts(mega_env):
+    sh = analysis.distribution_shift(mega_env["store"], mega_env["good"])
+    assert sh["shifts"], "training mix was deliberately shifted; must be detected"
+    top = sh["shifts"][0]
+    assert abs(top["relative_change"]) >= 0.35
+    assert top["eval_count"] >= 300
+    # the train mix under-represents night/bad weather, so eval share must be higher
+    assert any(s["relative_change"] > 0 and s["lighting"] == "night" for s in sh["shifts"])
+
+
+def test_why_decomposition_sums_to_one(mega_env):
+    w = analysis.why(mega_env["store"], mega_env["good"],
+                     {"class": ["pedestrian"]}, "recall")
+    assert w["failure_count"] > 0
+    total_share = sum(f["share"] for f in w["factors"])
+    assert abs(total_share - 1.0) < 0.01
+    assert sum(f["count"] for f in w["factors"]) == w["failure_count"]
+    names = {f["factor"] for f in w["factors"]}
+    assert names <= {"occlusion", "low_illumination", "long_range",
+                     "sensor_disagreement", "other"}
+    assert w["top_cohorts"], "must list affected cohorts with metric values"
+    assert all("recall" in c for c in w["top_cohorts"])
+
+
+def test_similarity_hybrid_search(mega_env):
+    store, run = mega_env["store"], mega_env["good"]
+    containers = store.artifacts(run.run_id)["containers"]
+    risky = containers.sort_values("risk_score", ascending=False).iloc[0]
+    cid = int(risky["container_id"])
+    res = analysis.similar_containers(store, run, cid, k=8)
+    assert len(res["results"]) == 8
+    sims = [r["similarity"] for r in res["results"]]
+    assert sims == sorted(sims, reverse=True)
+    assert all(r["container_id"] != cid for r in res["results"])
+    # hybrid: structured filter restricts results
+    filt = analysis.similar_containers(store, run, cid, filters={"lighting": ["night"]}, k=8)
+    assert all(r["lighting"] == "night" for r in filt["results"])

tests/test_megaeval/test_api_lifecycle.py

@@ -0,0 +1,190 @@
+"""Async run lifecycle, the query API (cache behavior + routing), 409 gating,
+containers/forensic drill-down, review endpoints and performance SLOs —
+all through the real HTTP API."""
+
+from __future__ import annotations
+
+import time
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+@pytest.fixture(scope="module")
+def client(mega_env):
+    from app_backend import app
+    with TestClient(app) as c:
+        yield c
+
+
+@pytest.fixture(scope="module")
+def api_run(client, mega_env):
+    """Create a fresh run via the API and wait for the async lifecycle to publish."""
+    pop_id = mega_env["meta"]["population_id"]
+    res = client.post("/api/megaeval/runs",
+                      json={"population_id": pop_id, "model_version": "model-api",
+                            "worker_delay_s": 0.05, "workers": 4})
+    assert res.status_code == 200
+    run = res.json()
+    assert run["status"] in ("queued", "running")
+
+    seen_statuses = {run["status"]}
+    deadline = time.time() + 60
+    while time.time() < deadline:
+        r = client.get(f"/api/megaeval/runs/{run['run_id']}").json()
+        seen_statuses.add(r["status"])
+        if r["status"] in ("published", "failed"):
+            break
+        time.sleep(0.2)
+    assert r["status"] == "published", r.get("error")
+    return {"run": r, "seen_statuses": seen_statuses}
+
+
+def test_async_lifecycle_and_progress(api_run):
+    r = api_run["run"]
+    assert api_run["seen_statuses"] & {"queued", "running", "reducing", "materializing"}
+    assert r["percent"] == 100.0
+    assert r["objects_processed"] == r["objects_total"] > 0
+    assert r["throughput_objs_per_s"] > 0
+    assert r["headline"]["n"] == r["objects_total"]
+    lin = r["lineage"]
+    for field in ("evaluation_id", "dataset_version", "model_version", "model_checkpoint",
+                  "label_version", "evaluator_code_version", "metric_version",
+                  "threshold_config", "sampling_config", "seed", "hardware", "timestamp"):
+        assert field in lin
+
+
+def test_results_blocked_until_published(client, mega_env):
+    pop_id = mega_env["meta"]["population_id"]
+    res = client.post("/api/megaeval/runs",
+                      json={"population_id": pop_id, "model_version": "model-slow",
+                            "worker_delay_s": 0.4, "workers": 2})
+    run_id = res.json()["run_id"]
+    blocked = client.get(f"/api/megaeval/runs/{run_id}/funnel")
+    assert blocked.status_code == 409
+    deadline = time.time() + 90
+    while time.time() < deadline:
+        if client.get(f"/api/megaeval/runs/{run_id}").json()["status"] == "published":
+            break
+        time.sleep(0.3)
+    assert client.get(f"/api/megaeval/runs/{run_id}/funnel").status_code == 200
+
+
+def test_query_api_cache_and_latency_slos(client, api_run):
+    run_id = api_run["run"]["run_id"]
+    body = {"evaluation_id": run_id,
+            "filters": {"class": ["pedestrian"], "lighting": ["night"]},
+            "metrics": ["n", "recall", "precision", "mean_iou"],
+            "group_by": []}
+    r1 = client.post("/api/evaluations/query", json=body).json()
+    assert r1["meta"]["source"] == "cube"
+    assert r1["meta"]["cache_hit"] is False
+    assert r1["meta"]["exact"] is True
+    assert r1["rows"][0]["n"] > 0
+    assert r1["meta"]["latency_ms"] < 3000  # filtered cohort query SLO
+
+    r2 = client.post("/api/evaluations/query", json=body).json()
+    assert r2["meta"]["cache_hit"] is True
+    assert r2["meta"]["source"] == "cache"
+    assert r2["meta"]["latency_ms"] < 100   # cached query SLO
+    assert r2["rows"] == r1["rows"]
+
+    dash = client.post("/api/evaluations/query",
+                       json={"evaluation_id": run_id, "group_by": ["class"],
+                             "metrics": ["n", "precision", "recall", "f1"]}).json()
+    assert dash["meta"]["latency_ms"] < 2000  # aggregate dashboard SLO
+    assert len(dash["rows"]) == 6
+
+    stats = client.get("/api/megaeval/cache").json()
+    assert stats["hits"] >= 1
+
+
+def test_query_sketch_metrics_marked_approximate(client, api_run):
+    run_id = api_run["run"]["run_id"]
+    res = client.post("/api/evaluations/query",
+                      json={"evaluation_id": run_id,
+                            "metrics": ["n", "recall", "confidence_p50", "iou_p90"]}).json()
+    assert res["meta"]["exact"] is False
+    assert set(res["meta"]["approximate_fields"]) == {"confidence_p50", "iou_p90"}
+    assert 0 <= res["rows"][0]["confidence_p50"] <= 1
+
+
+def test_containers_sort_presets_and_forensic_drilldown(client, api_run):
+    run_id = api_run["run"]["run_id"]
+    worst = client.get(f"/api/megaeval/runs/{run_id}/containers",
+                       params={"sort": "worst_recall", "limit": 20}).json()
+    assert worst["total"] > 0 and len(worst["rows"]) == 20
+    recalls = [r["recall"] for r in worst["rows"] if r["recall"] is not None]
+    assert recalls == sorted(recalls)
+
+    risky = client.get(f"/api/megaeval/runs/{run_id}/containers",
+                       params={"sort": "highest_risk", "limit": 5}).json()["rows"]
+    risks = [r["risk_score"] for r in risky]
+    assert risks == sorted(risks, reverse=True)
+    assert risky[0]["status"] in ("ok", "warn", "critical")
+
+    t0 = time.perf_counter()
+    objs = client.get(
+        f"/api/megaeval/runs/{run_id}/containers/{risky[0]['container_id']}/objects").json()
+    elapsed_ms = (time.perf_counter() - t0) * 1000
+    assert elapsed_ms < 1000  # object investigation SLO
+    assert objs["objects"], "forensic drill-down must return annotation-level rows"
+    outcomes = {o["outcome"] for o in objs["objects"]}
+    assert outcomes <= {"TP", "FN", "FP", "LOCALIZATION"}
+    gt_objs = [o for o in objs["objects"] if o["outcome"] != "FP"]
+    assert len(gt_objs) == risky[0]["n_objects"]
+
+
+def test_review_endpoints_full_cycle(client, api_run):
+    run_id = api_run["run"]["run_id"]
+    state = client.get(f"/api/megaeval/runs/{run_id}/review").json()
+    assert state["planned"] is False
+
+    plan = client.post(f"/api/megaeval/runs/{run_id}/review/plan",
+                       json={"target_n": 600}).json()
+    assert plan["planned"] and not plan["executed"]
+    assert plan["funnel"]["statistically_selected"] > 0
+
+    done = client.post(f"/api/megaeval/runs/{run_id}/review/execute").json()
+    assert done["executed"]
+    res = done["results"]
+    for metric in ("precision", "recall"):
+        est = res[metric]
+        assert est["ci_low"] < est["estimate"] < est["ci_high"]
+
+    funnel = client.get(f"/api/megaeval/runs/{run_id}/funnel").json()
+    stages = {s["stage"]: s["count"] for s in funnel["stages"]}
+    assert stages["Human Verified"] == done["funnel"]["reviewed"]
+    assert funnel["estimated_precision"]["estimate"] is not None
+
+
+def test_error_search_compare_shift_why_similarity_endpoints(client, api_run, mega_env):
+    run_id = api_run["run"]["run_id"]
+    es = client.post("/api/megaeval/errors/search",
+                     json={"run_id": run_id, "error_types": ["FN"],
+                           "filters": {"class": ["pedestrian"]},
+                           "risk_min": 0.5}).json()
+    assert es["matched_errors"] > 0 and es["worst_containers"]
+
+    cmp = client.post("/api/megaeval/compare",
+                      json={"candidate_run_id": mega_env["bad"].run_id,
+                            "baseline_run_id": run_id}).json()
+    assert cmp["recommendation"] == "DO_NOT_PROMOTE"
+
+    sh = client.get(f"/api/megaeval/runs/{run_id}/shift").json()
+    assert sh["shifts"]
+
+    why = client.post("/api/megaeval/why",
+                      json={"run_id": run_id, "filters": {"lighting": ["night"]},
+                            "metric": "recall"}).json()
+    assert why["failure_count"] > 0 and why["factors"]
+
+    cid = es["worst_containers"][0]["container_id"]
+    sim = client.post("/api/megaeval/similarity",
+                      json={"run_id": run_id, "container_id": cid, "k": 5}).json()
+    assert len(sim["results"]) == 5
+
+    dist = client.get(f"/api/megaeval/runs/{run_id}/distributions").json()
+    assert dist["exact"] is False
+    assert "confidence" in dist and "50" in dist["confidence"]["percentiles"]
+    assert dist["containers_exact"] > 0

tests/test_megaeval/test_cube.py

@@ -0,0 +1,109 @@
+"""Cube correctness: cube aggregates must EXACTLY match brute-force computation
+over the raw per-object records, and re-running with the same lineage must be
+bit-identical (deterministic seeds)."""
+
+from __future__ import annotations
+
+import os
+
+import numpy as np
+import pandas as pd
+import pytest
+
+from sensorflow.megaeval import cube as cube_mod
+from sensorflow.megaeval import population as pop_mod
+from sensorflow.megaeval.population import DIM_NAMES, DIMENSIONS
+from sensorflow.megaeval.runs import run_dir
+
+
+def _brute_force(env, group_dims):
+    """Recompute tp/fp/fn/n per group directly from raw per-object outputs."""
+    run = env["good"]
+    frames = []
+    d = run_dir(run.run_id)
+    for p in range(run.partitions_total):
+        pop_cols = pop_mod.load_partition(run.population_id, p)
+        with np.load(os.path.join(d, f"objects-part-{p:04d}.npz")) as z:
+            df = pd.DataFrame({
+                **{k: pop_cols[k] for k in DIM_NAMES},
+                "tp": z["tp"].astype(np.int64),
+                "detected": z["detected"].astype(bool),
+            })
+        df["fn"] = 1 - df["tp"]
+        df["fp"] = (df["detected"] & (df["tp"] == 0)).astype(np.int64)
+        df["n"] = 1
+        frames.append(df[group_dims + ["n", "tp", "fp", "fn"]])
+        with np.load(os.path.join(d, f"fp-part-{p:04d}.npz")) as z:
+            if z["container_id"].size:
+                fpdf = pd.DataFrame({k: z[k] for k in DIM_NAMES})
+                fpdf["n"] = 0
+                fpdf["tp"] = 0
+                fpdf["fp"] = 1
+                fpdf["fn"] = 0
+                frames.append(fpdf[group_dims + ["n", "tp", "fp", "fn"]])
+    full = pd.concat(frames, ignore_index=True)
+    return full.groupby(group_dims, as_index=False).sum()
+
+
+@pytest.mark.parametrize("group_dims", [["class"], ["class", "lighting"], ["scenario"]])
+def test_cube_matches_brute_force_exactly(mega_env, group_dims):
+    run = mega_env["good"]
+    cube = mega_env["store"].artifacts(run.run_id)["cube"]
+    rows, _ = cube_mod.aggregate(cube, None, group_dims,
+                                 ["n", "tp", "fp", "fn", "precision", "recall"], 2000)
+    brute = _brute_force(mega_env, group_dims)
+    assert len(rows) == len(brute)
+    for _, b in brute.iterrows():
+        key = {d: DIMENSIONS[d][int(b[d])] for d in group_dims}
+        match = [r for r in rows if all(r[d] == key[d] for d in group_dims)]
+        assert len(match) == 1, f"missing cube row for {key}"
+        r = match[0]
+        assert r["n"] == int(b["n"])
+        assert r["tp"] == int(b["tp"])
+        assert r["fp"] == int(b["fp"])
+        assert r["fn"] == int(b["fn"])
+        # derived ratios match brute force (API rounds ratios to 6 decimals)
+        if b["tp"] + b["fp"] > 0:
+            assert r["precision"] == pytest.approx(b["tp"] / (b["tp"] + b["fp"]), abs=1e-6)
+        if b["tp"] + b["fn"] > 0:
+            assert r["recall"] == pytest.approx(b["tp"] / (b["tp"] + b["fn"]), abs=1e-6)
+
+
+def test_rollup_consistency(mega_env):
+    """Any grouped rollup must sum to the global totals (no double counting)."""
+    run = mega_env["good"]
+    cube = mega_env["store"].artifacts(run.run_id)["cube"]
+    total_rows, _ = cube_mod.aggregate(cube, None, None, ["n", "tp", "fp", "fn"], 1)
+    total = total_rows[0]
+    for dim in ("class", "weather", "occlusion", "distance_band"):
+        rows, _ = cube_mod.aggregate(cube, None, [dim], ["n", "tp", "fp", "fn"], 2000)
+        for stat in ("n", "tp", "fp", "fn"):
+            assert sum(r[stat] for r in rows) == total[stat], f"{dim}/{stat} rollup mismatch"
+
+
+def test_filtered_aggregate_equals_manual_subset(mega_env):
+    run = mega_env["good"]
+    cube = mega_env["store"].artifacts(run.run_id)["cube"]
+    filt = {"class": ["pedestrian"], "lighting": ["night"]}
+    rows, _ = cube_mod.aggregate(cube, filt, None, ["n", "tp", "fn", "recall"], 1)
+    sub = cube[(cube["class"] == DIMENSIONS["class"].index("pedestrian"))
+               & (cube["lighting"] == DIMENSIONS["lighting"].index("night"))]
+    assert rows[0]["n"] == int(sub["n"].sum())
+    assert rows[0]["tp"] == int(sub["tp"].sum())
+    assert rows[0]["recall"] == pytest.approx(sub["tp"].sum() / max(sub["tp"].sum() + sub["fn"].sum(), 1), abs=1e-6)
+
+
+def test_reproducible_run_same_lineage(mega_env):
+    """Same population + model_version (same derived seed) -> identical cube."""
+    store, meta = mega_env["store"], mega_env["meta"]
+    r1 = store.create_run(population_id=meta["population_id"],
+                          model_version="model-repro", worker_delay_s=0.0)
+    store.execute_sync(r1)
+    r2 = store.create_run(population_id=meta["population_id"],
+                          model_version="model-repro", worker_delay_s=0.0)
+    store.execute_sync(r2)
+    assert r1.seed == r2.seed
+    c1 = mega_env["store"].artifacts(r1.run_id)["cube"].sort_values(DIM_NAMES).reset_index(drop=True)
+    c2 = mega_env["store"].artifacts(r2.run_id)["cube"].sort_values(DIM_NAMES).reset_index(drop=True)
+    pd.testing.assert_frame_equal(c1, c2)
+    assert r1.headline == {**r2.headline}

tests/test_megaeval/test_error_index.py

@@ -0,0 +1,64 @@
+"""Error index: multi-criteria search correctness and worst-container ranking."""
+
+from __future__ import annotations
+
+import numpy as np
+
+from sensorflow.megaeval import errors as errors_mod
+from sensorflow.megaeval.population import DIMENSIONS
+from sensorflow.megaeval.runs import ERROR_TYPES
+
+
+def test_multi_criteria_search_matches_brute_filter(mega_env):
+    store, run = mega_env["store"], mega_env["good"]
+    art = store.artifacts(run.run_id)
+    errs, containers = art["errors"], art["containers"]
+
+    res = errors_mod.search_errors(
+        errs, containers, error_types=["FN"],
+        filters={"class": ["pedestrian"], "lighting": ["night"]},
+        confidence_max=0.4, risk_min=0.5)
+
+    mask = ((errs["error_type"] == ERROR_TYPES.index("FN"))
+            & (errs["class"] == DIMENSIONS["class"].index("pedestrian"))
+            & (errs["lighting"] == DIMENSIONS["lighting"].index("night"))
+            & (errs["confidence"] <= 0.4)
+            & (errs["risk_score"] >= 0.5))
+    assert res["matched_errors"] == int(mask.sum())
+    assert res["matched_errors"] > 0
+
+    for ex in res["examples"]:
+        assert ex["error_type"] == "FN"
+        assert ex["class"] == "pedestrian"
+        assert ex["lighting"] == "night"
+        assert ex["confidence"] <= 0.4
+        assert ex["risk_score"] >= 0.5
+
+
+def test_worst_containers_ranked_and_capped(mega_env):
+    store, run = mega_env["store"], mega_env["good"]
+    art = store.artifacts(run.run_id)
+    res = errors_mod.search_errors(art["errors"], art["containers"],
+                                   error_types=["FN", "FP"], limit_containers=10)
+    worst = res["worst_containers"]
+    assert 0 < len(worst) <= 10
+    scores = [w["error_count"] * w["mean_risk"] for w in worst]
+    assert scores == sorted(scores, reverse=True)
+    # returns aggregated containers with context dims, not raw record dumps
+    assert "weather" in worst[0] and "n_objects" in worst[0]
+
+
+def test_safety_only_filter(mega_env):
+    store, run = mega_env["store"], mega_env["good"]
+    art = store.artifacts(run.run_id)
+    res = errors_mod.search_errors(art["errors"], art["containers"],
+                                   error_types=["FN"], safety_only=True)
+    assert res["matched_errors"] > 0
+    assert all(ex["safety_critical"] for ex in res["examples"])
+
+
+def test_by_type_totals_are_consistent(mega_env):
+    store, run = mega_env["store"], mega_env["good"]
+    art = store.artifacts(run.run_id)
+    res = errors_mod.search_errors(art["errors"], art["containers"])
+    assert sum(res["by_type"].values()) == res["matched_errors"] == len(art["errors"])

tests/test_megaeval/test_sampling.py

@@ -0,0 +1,64 @@
+"""Review sampling: funnel structure, CI correctness (must cover the true
+population metric), and cube review-counter updates."""
+
+from __future__ import annotations
+
+import pytest
+
+from sensorflow.megaeval import cube as cube_mod
+from sensorflow.megaeval import sampling
+
+
+@pytest.fixture(scope="module")
+def reviewed(mega_env):
+    store, run = mega_env["store"], mega_env["good"]
+    plan = sampling.build_review_plan(store, run, target_n=1200)
+    result = sampling.execute_reviews(store, run)
+    return {"plan": plan, "result": result, "run": run, "store": store}
+
+
+def test_sampling_funnel_shape(reviewed):
+    f = reviewed["result"]["funnel"]
+    assert f["population_objects"] > f["containers"] > 0
+    assert f["suspicious_containers"] <= f["containers"]
+    # per-stratum rounding can overshoot by at most one unit per stratum (10 strata)
+    assert f["statistically_selected"] <= reviewed["result"]["target_n"] + 10
+    assert f["reviewed"] == f["statistically_selected"]
+
+
+def test_stratified_ci_covers_true_metrics(reviewed):
+    run = reviewed["run"]
+    res = reviewed["result"]["results"]
+    slack = 0.02  # human-fidelity noise (98.5%) can bias estimates slightly
+    for metric in ("precision", "recall"):
+        true = run.headline[metric]
+        est = res[metric]
+        assert est["ci_low"] < est["estimate"] < est["ci_high"]
+        assert est["ci_low"] - slack <= true <= est["ci_high"] + slack, (
+            f"{metric}: true {true} outside CI [{est['ci_low']}, {est['ci_high']}]")
+        assert abs(est["estimate"] - true) < 0.06
+        assert (est["ci_high"] - est["ci_low"]) < 0.25
+        assert est["n_reviewed"] > 0
+        assert "stratified" in est["method"]
+
+
+def test_strata_are_risk_weighted(reviewed):
+    """Missed/safety strata must be oversampled relative to their share."""
+    rec = reviewed["result"]["results"]["recall"]
+    by_label = {s["stratum"]: s for s in rec["strata"]}
+    detected = by_label.get("detected")
+    missed = by_label.get("missed")
+    assert detected and missed
+    assert (missed["n"] / max(missed["N"], 1)) > (detected["n"] / max(detected["N"], 1))
+
+
+def test_cube_review_counters_updated(reviewed):
+    store, run = reviewed["store"], reviewed["run"]
+    cube = store.artifacts(run.run_id)["cube"]
+    rows, _ = cube_mod.aggregate(cube, None, None, ["n", "reviewed", "verified"], 1)
+    total = rows[0]
+    assert total["reviewed"] > 0
+    assert 0 < total["verified"] <= total["reviewed"]
+    # containers table too
+    containers = store.artifacts(run.run_id)["containers"]
+    assert int(containers["reviewed"].sum()) == total["reviewed"]

tests/test_megaeval/test_sketches.py

@@ -0,0 +1,70 @@
+"""Sketch accuracy: quantile histograms, HyperLogLog, reservoir, Wilson CIs."""
+
+from __future__ import annotations
+
+import numpy as np
+import pytest
+
+from sensorflow.megaeval.sketches import HyperLogLog, QuantileHistogram, Reservoir
+from sensorflow.megaeval.sampling import wilson_interval
+
+
+def test_quantile_histogram_percentiles_close_to_exact():
+    rng = np.random.default_rng(3)
+    data = np.clip(rng.beta(5, 2, size=50_000), 0, 1)
+    h = QuantileHistogram(0, 1, 64)
+    h.add(data)
+    bin_width = 1 / 64
+    for q in (10, 25, 50, 75, 90, 99):
+        approx = h.percentile(q)
+        exact = float(np.percentile(data, q))
+        assert abs(approx - exact) <= bin_width + 1e-9, f"p{q}: {approx} vs {exact}"
+
+
+def test_quantile_histogram_merge_equals_combined():
+    rng = np.random.default_rng(4)
+    a, b = rng.random(10_000), rng.random(10_000)
+    ha, hb, hc = QuantileHistogram(), QuantileHistogram(), QuantileHistogram()
+    ha.add(a)
+    hb.add(b)
+    hc.add(np.concatenate([a, b]))
+    merged = ha.merge(hb)
+    assert np.array_equal(merged.counts, hc.counts)
+
+
+def test_hll_estimate_within_five_percent():
+    hll = HyperLogLog(12)
+    n = 20_000
+    hll.add_ids(np.arange(n, dtype=np.int64))
+    est = hll.estimate()
+    assert abs(est - n) / n < 0.05, est
+
+
+def test_hll_merge_is_union():
+    h1, h2 = HyperLogLog(12), HyperLogLog(12)
+    h1.add_ids(np.arange(0, 8_000, dtype=np.int64))
+    h2.add_ids(np.arange(4_000, 12_000, dtype=np.int64))
+    merged = h1.merge(h2)
+    est = merged.estimate()
+    assert abs(est - 12_000) / 12_000 < 0.06, est
+
+
+def test_reservoir_bounded_and_uniformish():
+    r = Reservoir(k=100, seed=1)
+    r.add_ids(np.arange(10_000))
+    assert len(r.items) == 100
+    assert r.seen == 10_000
+    # sampled ids should span the range, not just the head
+    assert max(r.items) > 5_000 and min(r.items) < 5_000
+
+
+def test_wilson_interval_known_value():
+    lo, hi = wilson_interval(8, 10)
+    assert lo == pytest.approx(0.490, abs=0.01)
+    assert hi == pytest.approx(0.943, abs=0.01)
+    lo0, hi0 = wilson_interval(0, 0)
+    assert (lo0, hi0) == (0.0, 1.0)
+    # Wilson upper bound at p=1 is mathematically < 1 (that's the point of Wilson)
+    lo1, hi1 = wilson_interval(50, 50)
+    assert 0.9 < lo1 < hi1 <= 1.0
+    assert hi1 == pytest.approx(0.9928, abs=0.01)