Deepen InferScale simulation research workflow

README.md

@@ -1,6 +1,5 @@
 ---
 title: InferScale-Sim
-emoji: 📈
 colorFrom: indigo
 colorTo: blue
 sdk: static
@@ -10,97 +9,118 @@ license: mit
 short_description: Interactive LLM serving simulator and SLO planner
 ---
 
-# InferScale-Sim v0.3.0
+# InferScale-Sim
 
-**Interactive LLM serving simulator and SLO-aware design laboratory - written in Python and executed entirely in the browser.**
+**Interactive LLM serving-systems laboratory written in Python and executed entirely in the browser.**
 
-InferScale-Sim explores a systems question:
+InferScale-Sim studies a systems question:
 
-> How do workload shape, batching, scheduling, KV-cache pressure, reusable prefixes, and prefill/decode disaggregation change tail latency and sustainable LLM-serving capacity?
+> How do workload shape, batching, scheduling, KV-cache pressure, reusable prefixes, topology, and resource allocation change tail latency, goodput, and sustainable serving capacity?
 
-The public Hugging Face Space uses **no server CPU, no GPU, no API key, and no paid inference provider**. Hugging Face serves static files; Pyodide executes the same Python package used by the local test suite inside a Web Worker on the visitor's ordinary CPU.
+The public Hugging Face Space uses **no server CPU, no GPU, no API key, and no inference provider**. Hugging Face serves static files; Pyodide executes the same Python package used by the local test suite inside a Web Worker on the visitor's ordinary CPU.
 
 > [!IMPORTANT]
-> v0.3 ships with **analytical reference latency profiles**, not measured GPU calibration data. It is designed for systems behavior, what-if studies, and comparative exploration. Absolute milliseconds must not be presented as empirical L4/A10G/A100 benchmark results.
+> InferScale-Sim ships with **analytical reference latency profiles**, not measured GPU calibration data. Queueing, scheduling, cache, transfer, SLO, and design-space behavior is simulated live. Absolute L4/A10G/A100 milliseconds must not be presented as empirical hardware benchmarks.
 
 ## Why simulation?
 
-Exhaustively testing serving configurations on real GPU clusters is expensive. **Vidur** reported finding a LLaMA2-70B deployment configuration in roughly one CPU-hour while estimating that deployment-based exploration would require about **42,000 GPU-hours (~$218K)**. Its evaluated latency predictions were within 9% error.
+Exhaustive serving-system exploration is expensive. Microsoft's **Vidur** reported finding a LLaMA2-70B deployment configuration in roughly one CPU-hour while estimating that deployment-based exploration would require about **42,000 GPU-hours (~$218K)**; the paper reports inference-latency prediction error below 9% in its evaluated settings.
 
-That research direction has continued. **Revati (2026)** explores GPU-free time-warp emulation of real serving control paths; **LLMServingSim 2.0 (2026)** models heterogeneous and disaggregated serving; **Frontier (May 2026)** models P/D disaggregation, communication, runtime optimizations, stateful workloads, and SLA-dependent Pareto exploration; and **HeteroPanacea (Aug 2026)** studies heterogeneous specialization across prefill/decode/attention/FFN serving stages.
+The research direction has continued rapidly. Recent work includes GPU-free serving emulation, heterogeneous and disaggregated simulation, stateful/agentic workloads, open-loop load replay, and SLA-aware design-space exploration. InferScale-Sim is deliberately smaller: dependency-light, inspectable Python intended to expose the reasoning behind serving-system trade-offs rather than hide them behind a production runtime.
 
-InferScale-Sim is deliberately smaller: a dependency-light, inspectable Python implementation intended to make the core serving trade-offs interactive and understandable.
+## What is simulated
 
-## v0.3 capabilities
+### Workloads
 
-### Workload and serving loop
-
-- deterministic constant, Poisson, and bursty arrival processes
+- deterministic constant, Poisson, and bursty **open-loop** arrivals
 - log-normal prompt/output-length distributions
+- exact **CSV/JSON trace replay** using supplied arrival times and token lengths
+- shared seeds for controlled A/B experiments
+
+Generated load is open-loop: arrivals are scheduled independently of response completion so queueing delay remains visible under overload. Trace replay accepts:
+
+```text
+arrival_time,prompt_tokens,output_tokens
+0.000,512,64
+0.137,233,41
+0.284,1024,128
+```
+
+### Serving loop
+
 - static batching baseline
 - continuous batching with FCFS
 - shortest-job-first scheduling
 - least-slack/SLO-aware scheduling
 - chunked prefill
 - paged KV-cache accounting and VRAM admission control
-- analytical roofline-style prefill/decode latency proxy
+- controlled exact-prefix reuse
+- colocated or prefill/decode-disaggregated topology
+- independent P/D worker counts and accelerator profiles
+- explicit serialized KV-transfer model
 - FP16 / INT8 / INT4 weight-footprint scenarios
 
-### Metrics and SLOs
+### Metrics
 
-- TTFT, TPOT, E2E and queue-latency percentiles
+- TTFT, TPOT, E2E, and queue-latency percentiles
 - request and output-token throughput
-- **goodput**: completed requests that satisfy both configured SLOs per simulated second
-- component TTFT/E2E SLO attainment
-- virtual resource utilization
-- peak KV usage
-- heuristic bottleneck diagnosis with explicit simulator provenance
-
-### Prefix reuse - new in v0.3
-
-v0.3 adds a controlled shared-prefix scenario:
+- **goodput**: SLO-compliant completed requests per simulated second
+- TTFT/E2E SLO attainment
+- peak KV usage and virtual utilization
+- prefix-cache hit rate / saved prefill work
+- P/D transfer latency / transfer volume / role utilization
+- heuristic bottleneck diagnoses with explicit simulator provenance
 
-- configurable shared-prefix length
-- configurable request reuse fraction
-- deterministic cache-hit assignment independent of the generated workload trace
-- cached prefill tokens skipped on a hit
-- one persistent shared KV allocation instead of per-request duplication
-- cache-hit rate and saved-prefill-token telemetry
+## Interactive experiments
 
-This is intentionally **not** a complete RadixAttention implementation. It isolates the compute/memory effect of exact reusable prefixes while keeping the simulator small enough to inspect.
+### Serving Lab
 
-### Prefill/decode disaggregation - new in v0.3
+Run one workload through a colocated or P/D system and inspect request-level behavior, queue/KV timelines, latency distributions, prefix reuse, and bottleneck diagnostics.
 
-The simulator now supports a separate P/D topology with:
+### Scheduler Arena
 
-- independent prefill/decode accelerator profiles
-- configurable prefill and decode worker counts
-- independent role utilization
-- continuous decode admission between iterations
-- explicit KV transfer after prefill
-- serialized analytical interconnect model
-- configurable interconnect GB/s and base transfer latency
-- p95 KV-transfer latency, total transfer volume, and link utilization
-- P/D-specific bottleneck diagnoses such as prefill-pool, decode-pool, and transfer pressure
+Run every colocated scheduler against the **same deterministic workload** and compare goodput, SLO attainment, tail latency, KV pressure, and unfinished work.
 
-### Interactive tools
+### Capacity Planner
 
-**Serving Lab** - run one colocated or P/D scenario and inspect live metrics, timelines, cache behavior, and diagnostics.
+Perform repeated SLO-constrained binary search for the highest sustainable offered rate. A rate passes only if **every repetition** meets the requested SLO attainment and drains all generated requests. The search exposes mean attainment, worst repetition, target, and min/max range.
 
-**Scheduler Arena** - run every colocated scheduler against the identical deterministic workload.
+### Modern Serving Lab
 
-**Capacity Planner** - robust binary search for the highest request rate where **every repetition** satisfies the target and drains. The trace exposes mean SLO attainment, worst repetition, target, and min/max range.
-
-**Modern Serving Lab** - compare four controlled variants on one workload:
+Compare the same workload across:
 
 1. colocated
 2. colocated + prefix reuse
 3. P/D disaggregated
 4. P/D disaggregated + prefix reuse
 
-**Design Explorer** - runs a bounded live sweep over scheduler, batch size, prefix caching, and P/D worker splits, then reports two non-dominated frontiers: **raw goodput vs p95 TTFT** and **goodput per accelerator vs p95 TTFT**. The second view makes the resource cost of multi-worker P/D layouts explicit.
+Raw goodput and goodput-per-accelerator are reported separately so extra simulated hardware is not treated as free.
+
+### Design Explorer
 
-All charts can be expanded and exported as meaningfully named PNG files. Result tables support clipboard copy and CSV export.
+Run a bounded live sweep across scheduler, batch size, prefix caching, and P/D worker splits. InferScale reports two non-dominated frontiers:
+
+- **performance:** maximize goodput while minimizing p95 TTFT
+- **efficiency:** maximize goodput per accelerator while minimizing p95 TTFT
+
+### Research Studies
+
+This is the statistical/research layer rather than another configuration dashboard.
+
+**Paired Monte Carlo A/B studies** currently support:
+
+- prefix reuse off vs on
+- colocated vs P/D topology
+- continuous FCFS vs chunked prefill
+- continuous FCFS vs least-slack/SLO-aware scheduling
+
+Baseline and treatment use **common random numbers**: each repetition gets the same seed and therefore the same generated workload. InferScale reports paired mean deltas, relative effects, treatment win rate, and a **95% bootstrap interval over paired deltas**.
+
+**Model-uncertainty stress testing** then perturbs analytical prefill, decode, and transfer timing scales jointly for both alternatives. The purpose is not to assign a probability distribution to real GPUs; it asks a narrower scientific question:
+
+> Does the qualitative conclusion survive plausible multiplicative error in the analytical reference profile?
+
+This makes profile uncertainty visible rather than allowing one uncalibrated proxy to silently determine the winner.
 
 ## Architecture
 
@@ -109,34 +129,82 @@ All charts can be expanded and exported as meaningfully named PNG files. Result
                                   |
                                   | serves files only
                                   v
-+----------------------------------------------------------------+
-| Browser                                                        |
-|                                                                |
-| UI / Chart.js                  Pyodide Web Worker               |
-|       |                                |                        |
-|       +------------------------------->|                        |
-|                                        v                        |
-|                              Python inferscale package          |
-|                                        |                        |
-|       +--------------------------------+-------------------+    |
-|       |                    |                 |             |    |
-|   workload             schedulers         KV cache     profiles |
-|       |                    |                 |             |    |
-|       +--------------------+-----------------+-------------+    |
-|                                        |                        |
-|                   +--------------------+------------------+     |
-|                   |                                       |     |
-|            colocated simulator                   P/D simulator  |
-|                                                   |             |
-|                                      prefill -> transfer -> decode|
-|                   |                                       |     |
-|                   +--------------------+------------------+     |
-|                                        v                        |
-|                            metrics / SLO / search                |
-+----------------------------------------------------------------+
++------------------------------------------------------------------+
+| Browser                                                          |
+|                                                                  |
+| UI / Chart.js                    Pyodide Web Worker               |
+|       |                                  |                        |
+|       +--------------------------------->|                        |
+|                                          v                        |
+|                               Python inferscale package           |
+|                                          |                        |
+|       +------------------+---------------+------------------+     |
+|       |                  |               |                  |     |
+|   workloads          schedulers       KV/cache          profiles  |
+|       |                  |               |                  |     |
+|       +------------------+---------------+------------------+     |
+|                                          |                        |
+|                  +-----------------------+------------------+     |
+|                  |                                          |     |
+|          colocated simulator                       P/D simulator  |
+|                                                      |           |
+|                                         prefill -> transfer -> decode
+|                  |                                          |     |
+|                  +-----------------------+------------------+     |
+|                                          v                        |
+|                         metrics / search / research                |
++------------------------------------------------------------------+
+```
+
+The discrete-event engine never sleeps for simulated compute time. If the analytical model predicts a 40 ms operation, virtual time advances by 0.040 seconds immediately.
+
+## Core modeling choices
+
+### Goodput
+
+```text
+goodput = requests satisfying TTFT and E2E SLOs / simulated makespan
+```
+
+Raw throughput can reward overload; goodput penalizes requests that complete too late to satisfy the configured objective.
+
+### KV-cache model
+
+Per-token KV bytes are approximated as:
+
+```text
+2 x layers x KV heads x head dimension x 2 bytes
+```
+
+for K and V with FP16 KV state. Paged allocation rounds live request state to configurable token blocks. With prefix reuse enabled, the shared prefix is represented once as persistent KV state and request allocations contain only the uncached suffix plus generated tokens.
+
+### P/D transfer model
+
+After prefill, newly computed prompt KV crosses a serialized reference link:
+
+```text
+transfer_time = base_latency + KV_bytes / interconnect_bandwidth
+```
+
+The link is intentionally simple and explicit. It does not claim to reproduce NCCL, NIXL, RDMA, PCIe, or NVLink behavior.
+
+### Analytical latency model
+
+`AnalyticalLatencyModel` uses model architecture, accelerator peak FP16 compute, memory bandwidth, quantization footprint, batch/context shape, and conservative efficiency factors in a roofline-style proxy. Prefill and decode are modeled separately.
+
+The research stress test can multiplicatively perturb prefill/decode/transfer timing to expose conclusions that are sensitive to analytical-model error.
+
+## Empirical validation hook
+
+The public project does **not** ship invented "measured" GPU results. Instead, the repository includes an explicit validation path for future real measurements:
+
+```bash
+python scripts/validate_measurements.py my_measured_cases.json --output validation_report.json
 ```
 
-The discrete-event engine never sleeps for simulated compute time. A predicted 40 ms decode step advances virtual time by 0.040 seconds immediately.
+Each validation case provides a normal simulator configuration plus externally measured metrics such as p95 TTFT, p95 E2E, or goodput. InferScale reports prediction error, MAPE, median APE, and per-case residuals.
+
+`examples/validation_cases.schema.json` is a schema/template only; its zero values are clearly marked placeholders and are not benchmark data.
 
 ## Run locally
 
@@ -158,13 +226,13 @@ Run one simulation:
 python scripts/run_simulation.py
 ```
 
-Serve the browser app:
+Serve the browser application:
 
 ```bash
 python -m http.server 8000
 ```
 
-Open `http://localhost:8000`. The first page load downloads Pyodide and Chart.js from the CDN; simulation runs then execute locally in the worker.
+Open `http://localhost:8000`. The initial page load downloads Pyodide and Chart.js; simulations then run inside the local browser worker.
 
 ## Deploy to Hugging Face
 
@@ -185,55 +253,19 @@ pytest -q
 python scripts/release_check.py
 ```
 
-`sync_web_python.py` mirrors the canonical `src/inferscale/` package into `py/inferscale/`, which the Pyodide worker imports. CI fails if the mirror is stale.
-
-## Core modeling choices
-
-### Goodput
-
-```text
-goodput = requests satisfying TTFT and E2E SLOs / simulated makespan
-```
-
-Raw throughput can reward overload. Goodput penalizes requests that finish too late to be useful.
-
-### KV-cache model
-
-Per-token KV bytes are approximated as:
-
-```text
-2 x layers x KV heads x head dimension x 2 bytes
-```
-
-for K and V with FP16 KV state. Paged allocation rounds live per-request state to configurable token blocks.
-
-With prefix reuse enabled, the shared prefix is represented once as persistent KV state and request allocations contain only the uncached suffix plus generated tokens.
-
-### P/D transfer model
-
-After prefill, newly computed prompt KV is moved to the decode pool through a serialized reference link:
-
-```text
-transfer_time = base_latency + KV_bytes / interconnect_bandwidth
-```
-
-The link is intentionally simple and explicit. It does not claim to reproduce NCCL, NIXL, RDMA, PCIe, or NVLink behavior.
-
-### Latency-profile honesty
-
-`AnalyticalLatencyModel` estimates operation duration from model architecture, accelerator peak FP16 compute, memory bandwidth, quantization footprint, context length, and conservative efficiency factors. It is an analytical proxy.
-
-A future empirical interpolator can replace that backend without rewriting workload generation, scheduling, KV logic, P/D orchestration, or metrics.
+`sync_web_python.py` mirrors the canonical `src/inferscale/` package into `py/inferscale/`. CI fails if the browser mirror is stale.
 
 ## Research lineage
 
-- **Vidur: A Large-Scale Simulation Framework for LLM Inference** (MLSys 2024) - profiling + simulation + deployment search. https://arxiv.org/abs/2405.05465
-- **SGLang: Efficient Execution of Structured Language Model Programs** (NeurIPS 2024) - RadixAttention motivates exact shared-prefix reuse. https://arxiv.org/abs/2312.07104
+- **Vidur: A Large-Scale Simulation Framework for LLM Inference** (MLSys 2024) - predictive profiling, simulation, and deployment search. https://arxiv.org/abs/2405.05465
+- **SGLang: Efficient Execution of Structured Language Model Programs** (NeurIPS 2024) - RadixAttention motivates reusable-prefix experiments. https://arxiv.org/abs/2312.07104
 - **TokenSim** (2025) - extensible scheduling and memory-management simulation. https://arxiv.org/abs/2503.08415
-- **Revati: Transparent GPU-Free Time-Warp Emulation for LLM Serving** (2026) - real control logic with virtualized GPU time. https://arxiv.org/abs/2601.00397
+- **Revati** (2026) - GPU-free time-warp emulation of serving control logic. https://arxiv.org/abs/2601.00397
 - **LLMServingSim 2.0** (2026) - heterogeneous/disaggregated infrastructure and runtime interactions. https://arxiv.org/abs/2602.23036
-- **Frontier: Towards Comprehensive and Accurate LLM Inference Simulation** (2026) - P/D and Attention-FFN disaggregation, runtime optimizations, stateful workloads, and Pareto exploration. https://arxiv.org/abs/2605.21312
-- **When Does Disaggregation Pay? / HeteroPanacea** (Aug 2026) - heterogeneous P/D/attention/FFN specialization and cross-stack design exploration. https://arxiv.org/abs/2608.03741
+- **Frontier** (May 2026) - P/D and Attention-FFN disaggregation, runtime optimizations, stateful workloads, and Pareto exploration. https://arxiv.org/abs/2605.21312
+- **AgentServeSim** (June 2026) - hardware-aware simulation for multi-turn agent serving, tool gaps, routing, and KV residency. https://arxiv.org/abs/2606.09613
+- **Vanguard / Load Testing for Machine Learning Model Serving Systems at Scale** (June 2026) - trace replay, reproducibility analysis, bootstrap intervals, and open-loop generation to avoid coordinated omission. https://arxiv.org/abs/2606.22013
+- **When Does Disaggregation Pay? / HeteroPanacea** (August 2026) - heterogeneous stage specialization and cross-stack disaggregated design exploration. https://arxiv.org/abs/2608.03741
 
 See `docs/research.md`, `docs/methodology.md`, and `docs/validation.md` for scope and limitations.
 
@@ -241,24 +273,25 @@ See `docs/research.md`, `docs/methodology.md`, and `docs/validation.md` for scop
 
 ```text
 .
-|-- src/inferscale/          canonical Python simulator
+|-- src/inferscale/          canonical Python simulator + research utilities
 |-- py/inferscale/           generated browser mirror
 |-- tests/                   deterministic unit tests
-|-- scripts/                 local runner + release tooling
-|-- docs/                    architecture / methodology / research notes
+|-- scripts/                 runner, validation, release tooling
+|-- examples/                workload / validation schemas
+|-- docs/                    architecture, methodology, research notes
 |-- index.html               HF Static Space entry point
-|-- app.js                   UI + charts + export tooling
+|-- app.js                   UI, studies, charts, export tooling
 |-- worker.mjs               Pyodide Web Worker bridge
 `-- styles.css
 ```
 
-## Roadmap
+## Scope / next research directions
 
-v0.3 deliberately stops short of pretending to be a production-runtime emulator. Strong next steps would be:
+The project intentionally stops short of claiming production-runtime fidelity without calibration. High-value next steps include:
 
-- empirical latency-profile import and held-out calibration report
-- multi-turn / agentic session traces
-- speculative decoding
+- measured operation-profile import and held-out calibration
+- stateful multi-turn / agentic sessions with tool gaps and KV residency
+- speculative decoding and acceptance-rate sensitivity
 - multi-replica routing and tenant fairness
 - richer prefix-tree eviction/scheduling
 - attention/FFN disaggregation

app.js

@@ -8,6 +8,9 @@ let lastArenaRows = [];
 let lastCapacityTrace = [];
 let lastTopologyRows = [];
 let lastDesignRows = [];
+let lastPairedStudy = null;
+let lastRobustStudy = null;
+let traceRequests = [];
 
 const COLORS = {
   blue: "#79a7ff",
@@ -29,7 +32,8 @@ worker.addEventListener("message", (event) => {
   if (data.type === "ready") {
     runtimePill.classList.add("ready");
     runtimeText.textContent = "Python runtime ready";
-    ["runBtn", "arenaBtn", "capacityBtn", "topologyBtn", "designBtn"].forEach((id) => { $(id).disabled = false; });
+    ["runBtn", "arenaBtn", "capacityBtn", "topologyBtn", "designBtn", "pairedStudyBtn", "robustStudyBtn"].forEach((id) => { $(id).disabled = false; });
+    syncConditionalControls();
     window.setTimeout(() => document.body.classList.add("runtime-ready"), 650);
     return;
   }
@@ -89,6 +93,7 @@ function configFromUI(overrides = {}) {
     slo_ttft_ms: num("sloTtft"),
     slo_e2e_ms: num("sloE2e"),
     slo_attainment_target: 0.99,
+    trace_requests: $("arrival").value === "trace" ? traceRequests : [],
     ...overrides,
   };
 }
@@ -161,10 +166,20 @@ function downloadJson(result) {
   a.click();
   URL.revokeObjectURL(url);
 }
+function downloadNamedJson(prefix, result) {
+  const blob = new Blob([JSON.stringify(result, null, 2)], { type: "application/json" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `${prefix}_${stamp()}.json`;
+  a.click();
+  URL.revokeObjectURL(url);
+}
 
 Chart.defaults.color = "#929dab";
 Chart.defaults.borderColor = COLORS.grid;
 Chart.defaults.font.family = getComputedStyle(document.body).fontFamily;
+Chart.defaults.font.size = 13;
 Chart.defaults.animation.duration = 160;
 
 function commonChartOptions() {
@@ -186,7 +201,6 @@ function pointLegend() {
   return {
     labels: {
       usePointStyle: true,
-      pointStyle: "circle",
       boxWidth: 8,
       boxHeight: 8,
       padding: 14,
@@ -334,6 +348,7 @@ function renderSimulation(result) {
 }
 
 $("runBtn").addEventListener("click", async () => {
+  if ($("arrival").value === "trace" && traceRequests.length === 0) { showToast("Load a trace file first"); return; }
   const button = $("runBtn");
   const state = $("runState");
   button.disabled = true;
@@ -373,7 +388,7 @@ function renderArena(rows) {
   $("arenaContent").classList.remove("hidden");
   $("arenaCopyBtn").disabled = false;
   $("arenaCsvBtn").disabled = false;
-  $("arenaRows").innerHTML = rows.map((r, index) => `<tr><td>${escapeHtml(schedulerLabel(r.scheduler))}${index === 0 ? '<span class="best-label">Best</span>' : ""}</td><td>${fmt(r.goodput_rps, 2)} req/s</td><td>${fmt(r.goodput_per_accelerator, 2)} req/s/GPU</td><td>${pct(r.slo_attainment)}</td><td>${fmt(r.p95_ttft_ms)} ms</td><td>${fmt(r.p95_e2e_ms)} ms</td><td>${pct(r.peak_kv_utilization)}</td><td>${fmt(r.unfinished, 0)}</td><td>${escapeHtml(r.bottleneck || "N/A")}</td></tr>`).join("");
+  $("arenaRows").innerHTML = rows.map((r, index) => `<tr><td>${escapeHtml(schedulerLabel(r.scheduler))}${index === 0 ? '<span class="best-label">Best</span>' : ""}</td><td>${fmt(r.goodput_rps, 2)} req/s</td><td>${pct(r.slo_attainment)}</td><td>${fmt(r.p95_ttft_ms)} ms</td><td>${fmt(r.p95_e2e_ms)} ms</td><td>${pct(r.peak_kv_utilization)}</td><td>${fmt(r.unfinished, 0)}</td><td>${escapeHtml(r.bottleneck || "N/A")}</td></tr>`).join("");
   destroyChart("arena");
   charts.arena = new Chart($("arenaChart"), {
     type: "bar",
@@ -441,6 +456,7 @@ function renderCapacity(result) {
   });
 }
 $("capacityBtn").addEventListener("click", async () => {
+  if ($("arrival").value === "trace") { showToast("Capacity search requires a rate-driven workload"); return; }
   const button = $("capacityBtn");
   const state = $("plannerState");
   button.disabled = true;
@@ -498,7 +514,7 @@ function renderTopology(rows) {
   $("topologyContent").classList.remove("hidden");
   $("topologyCopyBtn").disabled = false;
   $("topologyCsvBtn").disabled = false;
-  $("topologyRows").innerHTML = rows.map((r, index) => `<tr><td>${escapeHtml(scenarioLabel(r.scenario))}${index === 0 ? '<span class="best-label">Best</span>' : ""}</td><td>${fmt(r.accelerator_instances, 0)}</td><td>${fmt(r.goodput_rps, 2)} req/s</td><td>${fmt(r.goodput_per_accelerator, 2)} req/s/GPU</td><td>${pct(r.slo_attainment)}</td><td>${fmt(r.p95_ttft_ms)} ms</td><td>${fmt(r.p95_e2e_ms)} ms</td><td>${fmt(r.p95_transfer_ms, 2)} ms</td><td>${pct(r.prefix_hit_rate)}</td><td>${fmt(r.prefill_tokens_saved, 0)} tok</td><td>${escapeHtml(r.bottleneck || "N/A")}</td></tr>`).join("");
+  $("topologyRows").innerHTML = rows.map((r, index) => `<tr><td>${escapeHtml(scenarioLabel(r.scenario))}${index === 0 ? '<span class="best-label">Best</span>' : ""}</td><td>${fmt(r.accelerator_instances, 0)}</td><td>${fmt(r.goodput_rps, 2)} req/s</td><td>${pct(r.slo_attainment)}</td><td>${fmt(r.p95_ttft_ms)} ms</td><td>${fmt(r.p95_e2e_ms)} ms</td><td>${fmt(r.p95_transfer_ms, 2)} ms</td><td>${pct(r.prefix_hit_rate)}</td><td>${fmt(r.prefill_tokens_saved, 0)} tok</td><td>${escapeHtml(r.bottleneck || "N/A")}</td></tr>`).join("");
 
   const palette = [COLORS.blue, COLORS.green, COLORS.amber, COLORS.red];
   destroyChart("topology");
@@ -555,7 +571,7 @@ function renderDesign(result) {
     data: { datasets: [
       { label: "SLO pass", data: passPoints, backgroundColor: COLORS.green, borderColor: COLORS.green, pointRadius: 4 },
       { label: "SLO fail", data: failPoints, backgroundColor: COLORS.gray, borderColor: COLORS.gray, pointRadius: 4 },
-      { type: "line", label: "Performance frontier", data: frontier, borderColor: COLORS.blue, backgroundColor: COLORS.blue, pointBackgroundColor: COLORS.blue, pointRadius: 5, fill: false, tension: 0 },
+      { type: "line", label: "Performance frontier", pointStyle: "line", data: frontier, borderColor: COLORS.blue, backgroundColor: COLORS.blue, pointBackgroundColor: COLORS.blue, pointRadius: 5, fill: false, tension: 0 },
     ] },
     options: { ...commonChartOptions(), parsing: false, plugins: { legend: pointLegend() }, scales: { x: { title: { display: true, text: "p95 TTFT (ms)" }, beginAtZero: true }, y: { title: { display: true, text: "Goodput (req/s)" }, beginAtZero: true } } },
   });
@@ -569,7 +585,7 @@ function renderDesign(result) {
     data: { datasets: [
       { label: "SLO pass", data: efficiencyPass, backgroundColor: COLORS.green, borderColor: COLORS.green, pointRadius: 4 },
       { label: "SLO fail", data: efficiencyFail, backgroundColor: COLORS.gray, borderColor: COLORS.gray, pointRadius: 4 },
-      { type: "line", label: "Efficiency frontier", data: efficiencyFrontier, borderColor: COLORS.amber, backgroundColor: COLORS.amber, pointBackgroundColor: COLORS.amber, pointRadius: 5, fill: false, tension: 0 },
+      { type: "line", label: "Efficiency frontier", pointStyle: "line", data: efficiencyFrontier, borderColor: COLORS.amber, backgroundColor: COLORS.amber, pointBackgroundColor: COLORS.amber, pointRadius: 5, fill: false, tension: 0 },
     ] },
     options: { ...commonChartOptions(), parsing: false, plugins: { legend: pointLegend() }, scales: { x: { title: { display: true, text: "p95 TTFT (ms)" }, beginAtZero: true }, y: { title: { display: true, text: "Goodput / accelerator (req/s/GPU)" }, beginAtZero: true } } },
   });
@@ -586,6 +602,197 @@ const designHeaders = ["Candidate", "Perf Pareto", "Efficiency Pareto", "SLO pas
 $("designCopyBtn").addEventListener("click", () => copyText(tableText(designHeaders, designTableRows(lastDesignRows)), "Design table copied"));
 $("designCsvBtn").addEventListener("click", () => downloadCsv(`inferscale_design-space_${stamp()}.csv`, designHeaders, designTableRows(lastDesignRows)));
 
+function studyValue(metric, value) {
+  if (metric === "slo_attainment") return pct(value);
+  if (metric === "goodput_rps") return `${fmt(value, 3)} req/s`;
+  return `${fmt(value, 2)} ms`;
+}
+function studyDelta(metric, value) {
+  if (metric === "slo_attainment") return `${value >= 0 ? "+" : ""}${fmt(value * 100, 2)} pp`;
+  if (metric === "goodput_rps") return `${value >= 0 ? "+" : ""}${fmt(value, 3)} req/s`;
+  return `${value >= 0 ? "+" : ""}${fmt(value, 2)} ms`;
+}
+function pairedTableRows(result) {
+  return (result?.metrics || []).map((m) => [
+    m.label,
+    studyValue(m.metric, m.baseline_mean),
+    studyValue(m.metric, m.treatment_mean),
+    studyDelta(m.metric, m.delta_mean),
+    `${studyDelta(m.metric, m.delta_ci95_low)} to ${studyDelta(m.metric, m.delta_ci95_high)}`,
+    `${m.relative_change_pct >= 0 ? "+" : ""}${fmt(m.relative_change_pct, 2)}%`,
+    pct(m.treatment_win_rate),
+    m.ci_excludes_zero ? "YES" : "NO",
+  ]);
+}
+function renderPairedStudy(result) {
+  lastPairedStudy = result;
+  $("pairedEmpty").classList.add("hidden");
+  $("pairedContent").classList.remove("hidden");
+  ["pairedCopyBtn", "pairedCsvBtn", "pairedJsonBtn"].forEach((id) => { $(id).disabled = false; });
+  const state = $("pairedState");
+  state.textContent = `${result.repetitions} paired runs`;
+  state.className = "tag good";
+
+  let improvements = 0;
+  let regressions = 0;
+  for (const m of result.metrics) {
+    if (!m.ci_excludes_zero) continue;
+    const favorable = m.preferred_direction === "higher" ? m.delta_ci95_low > 0 : m.delta_ci95_high < 0;
+    favorable ? improvements++ : regressions++;
+  }
+  const conclusion = improvements && !regressions
+    ? `${improvements} metric${improvements === 1 ? "" : "s"} show a directional treatment improvement with a 95% bootstrap interval excluding zero.`
+    : regressions && !improvements
+      ? `${regressions} metric${regressions === 1 ? "" : "s"} show a directional treatment regression with a 95% bootstrap interval excluding zero.`
+      : improvements || regressions
+        ? "The treatment shows mixed statistically separated effects across metrics; inspect the latency/throughput trade-off rather than declaring one winner."
+        : "None of the paired metric intervals excludes zero; this workload does not support a stable directional conclusion at the chosen repetition count.";
+  $("pairedSummary").innerHTML = `<strong>${escapeHtml(result.baseline_label)} vs ${escapeHtml(result.treatment_label)}.</strong> ${result.repetitions} common-seed repetitions with ${result.bootstrap_samples} bootstrap resamples. ${escapeHtml(conclusion)}`;
+
+  $("pairedRows").innerHTML = result.metrics.map((m) => {
+    const favorable = m.preferred_direction === "higher" ? m.delta_ci95_low > 0 : m.delta_ci95_high < 0;
+    const separated = m.ci_excludes_zero;
+    return `<tr><td>${escapeHtml(m.label)}</td><td>${studyValue(m.metric, m.baseline_mean)}</td><td>${studyValue(m.metric, m.treatment_mean)}</td><td>${studyDelta(m.metric, m.delta_mean)}</td><td>${studyDelta(m.metric, m.delta_ci95_low)} to ${studyDelta(m.metric, m.delta_ci95_high)}</td><td>${m.relative_change_pct >= 0 ? "+" : ""}${fmt(m.relative_change_pct, 2)}%</td><td>${pct(m.treatment_win_rate)}</td><td class="${separated ? (favorable ? "pass" : "fail") : ""}">${separated ? "YES" : "NO"}</td></tr>`;
+  }).join("");
+
+  const effects = result.metrics.map((m) => m.relative_change_pct * (m.preferred_direction === "higher" ? 1 : -1));
+  destroyChart("paired");
+  charts.paired = new Chart($("pairedChart"), {
+    type: "bar",
+    data: { labels: result.metrics.map((m) => m.label), datasets: [{ label: "Relative improvement (%)", data: effects, backgroundColor: effects.map((v) => v >= 0 ? COLORS.green : COLORS.red) }] },
+    options: { ...commonChartOptions(), plugins: { legend: { display: false }, tooltip: { callbacks: { label: (ctx) => `${fmt(ctx.raw, 2)}% (positive = treatment better)` } } }, scales: { y: { title: { display: true, text: "Relative improvement (%)" } } } },
+  });
+}
+const pairedHeaders = ["Metric", "Baseline mean", "Treatment mean", "Mean delta", "95% bootstrap CI", "Relative change", "Treatment win rate", "CI excludes zero"];
+$("pairedStudyBtn").addEventListener("click", async () => {
+  const button = $("pairedStudyBtn");
+  button.disabled = true;
+  button.textContent = "Running paired study...";
+  $("pairedState").textContent = "Running...";
+  $("pairedState").className = "tag neutral";
+  try {
+    renderPairedStudy(await callPython("paired_study", {
+      config: configFromUI(), study: $("studyPreset").value,
+      repetitions: num("studyReps"), bootstrap_samples: num("studyBootstrap"),
+    }));
+  } catch (error) {
+    $("pairedState").textContent = "Error";
+    $("pairedState").className = "tag bad";
+    alert(`Paired study failed: ${error.message}`);
+  } finally {
+    button.disabled = false;
+    button.textContent = "Run paired study";
+  }
+});
+$("pairedCopyBtn").addEventListener("click", () => { if (lastPairedStudy) copyText(tableText(pairedHeaders, pairedTableRows(lastPairedStudy)), "Paired study copied"); });
+$("pairedCsvBtn").addEventListener("click", () => { if (lastPairedStudy) downloadCsv(`inferscale_paired-study_${slug(lastPairedStudy.study)}_${stamp()}.csv`, pairedHeaders, pairedTableRows(lastPairedStudy)); });
+$("pairedJsonBtn").addEventListener("click", () => { if (lastPairedStudy) downloadNamedJson(`inferscale_paired-study_${slug(lastPairedStudy.study)}`, lastPairedStudy); });
+
+function robustTableRows(result) {
+  return (result?.rows || []).map((r) => [
+    r.sample,
+    fmt(r.prefill_scale, 3), fmt(r.decode_scale, 3), fmt(r.transfer_scale, 3),
+    pct(r.baseline.slo_attainment), pct(r.treatment.slo_attainment),
+    studyDelta("goodput_rps", r.treatment.goodput_rps - r.baseline.goodput_rps),
+    studyDelta("p95_ttft_ms", r.treatment.p95_ttft_ms - r.baseline.p95_ttft_ms),
+    studyDelta("p95_e2e_ms", r.treatment.p95_e2e_ms - r.baseline.p95_e2e_ms),
+  ]);
+}
+function renderRobustStudy(result) {
+  lastRobustStudy = result;
+  $("robustEmpty").classList.add("hidden");
+  $("robustContent").classList.remove("hidden");
+  ["robustCopyBtn", "robustCsvBtn", "robustJsonBtn"].forEach((id) => { $(id).disabled = false; });
+  const s = result.summary;
+  $("rTtftWins").textContent = pct(s.treatment_ttft_win_fraction);
+  $("rGoodputWins").textContent = pct(s.treatment_goodput_win_fraction);
+  $("rTreatmentPass").textContent = pct(s.treatment_slo_pass_fraction);
+  $("rBaselinePass").textContent = pct(s.baseline_slo_pass_fraction);
+  $("robustState").textContent = `${result.samples} perturbations`;
+  $("robustState").className = "tag good";
+  const ttftStable = s.treatment_ttft_win_fraction >= .8 || s.treatment_ttft_win_fraction <= .2;
+  const goodputStable = s.treatment_goodput_win_fraction >= .8 || s.treatment_goodput_win_fraction <= .2;
+  const stability = ttftStable && goodputStable ? "The directional conclusion is comparatively stable across the tested perturbations." : "At least one conclusion changes frequently under profile perturbation; treat the apparent winner as calibration-sensitive.";
+  $("robustSummary").innerHTML = `<strong>${escapeHtml(result.baseline_label)} vs ${escapeHtml(result.treatment_label)}.</strong> ${result.samples} shared perturbations within +/-${fmt(result.uncertainty * 100, 0)}% of the analytical prefill/decode/transfer timing proxies. ${escapeHtml(stability)} This is sensitivity analysis, not a confidence interval over real GPUs.`;
+  $("robustRows").innerHTML = result.rows.map((r) => `<tr><td>${r.sample}</td><td>${fmt(r.prefill_scale, 3)}</td><td>${fmt(r.decode_scale, 3)}</td><td>${fmt(r.transfer_scale, 3)}</td><td>${pct(r.baseline.slo_attainment)}</td><td>${pct(r.treatment.slo_attainment)}</td><td>${studyDelta("goodput_rps", r.treatment.goodput_rps - r.baseline.goodput_rps)}</td><td>${studyDelta("p95_ttft_ms", r.treatment.p95_ttft_ms - r.baseline.p95_ttft_ms)}</td><td>${studyDelta("p95_e2e_ms", r.treatment.p95_e2e_ms - r.baseline.p95_e2e_ms)}</td></tr>`).join("");
+}
+const robustHeaders = ["Sample", "Prefill scale", "Decode scale", "Transfer scale", "Baseline SLO", "Treatment SLO", "Goodput delta", "TTFT delta", "E2E delta"];
+$("robustStudyBtn").addEventListener("click", async () => {
+  const button = $("robustStudyBtn");
+  button.disabled = true;
+  button.textContent = "Stress-testing...";
+  $("robustState").textContent = "Running...";
+  $("robustState").className = "tag neutral";
+  try {
+    renderRobustStudy(await callPython("robustness_study", {
+      config: configFromUI(), study: $("studyPreset").value,
+      samples: num("robustSamples"), uncertainty: num("robustUncertainty"),
+    }));
+  } catch (error) {
+    $("robustState").textContent = "Error";
+    $("robustState").className = "tag bad";
+    alert(`Robustness study failed: ${error.message}`);
+  } finally {
+    button.disabled = false;
+    button.textContent = "Stress-test conclusion";
+  }
+});
+$("robustCopyBtn").addEventListener("click", () => { if (lastRobustStudy) copyText(tableText(robustHeaders, robustTableRows(lastRobustStudy)), "Robustness table copied"); });
+$("robustCsvBtn").addEventListener("click", () => { if (lastRobustStudy) downloadCsv(`inferscale_robustness_${slug(lastRobustStudy.study)}_${stamp()}.csv`, robustHeaders, robustTableRows(lastRobustStudy)); });
+$("robustJsonBtn").addEventListener("click", () => { if (lastRobustStudy) downloadNamedJson(`inferscale_robustness_${slug(lastRobustStudy.study)}`, lastRobustStudy); });
+
+function normalizeTraceRows(rows) {
+  if (!Array.isArray(rows)) throw new Error("Trace JSON must be an array or contain a requests array");
+  if (rows.length > 10000) throw new Error("Trace replay is limited to 10,000 requests in the browser");
+  return rows.map((row, index) => {
+    const arrival = Number(row.arrival_time);
+    const prompt = Number(row.prompt_tokens);
+    const output = Number(row.output_tokens);
+    if (!Number.isFinite(arrival) || arrival < 0 || !Number.isFinite(prompt) || prompt < 1 || !Number.isFinite(output) || output < 1) {
+      throw new Error(`Invalid trace row ${index + 1}`);
+    }
+    return { arrival_time: arrival, prompt_tokens: Math.round(prompt), output_tokens: Math.round(output) };
+  });
+}
+function parseTraceCsv(text) {
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  if (lines.length < 2) throw new Error("CSV trace needs a header and at least one request");
+  const headers = lines[0].split(",").map((x) => x.trim());
+  const required = ["arrival_time", "prompt_tokens", "output_tokens"];
+  const idx = Object.fromEntries(required.map((name) => [name, headers.indexOf(name)]));
+  if (required.some((name) => idx[name] < 0)) throw new Error("CSV header must contain arrival_time,prompt_tokens,output_tokens");
+  return normalizeTraceRows(lines.slice(1).map((line) => {
+    const cells = line.split(",").map((x) => x.trim());
+    return { arrival_time: cells[idx.arrival_time], prompt_tokens: cells[idx.prompt_tokens], output_tokens: cells[idx.output_tokens] };
+  }));
+}
+async function loadTraceFile(file) {
+  const text = await file.text();
+  let rows;
+  if (file.name.toLowerCase().endsWith(".json")) {
+    const parsed = JSON.parse(text);
+    rows = normalizeTraceRows(Array.isArray(parsed) ? parsed : parsed.requests);
+  } else {
+    rows = parseTraceCsv(text);
+  }
+  rows.sort((a, b) => a.arrival_time - b.arrival_time);
+  traceRequests = rows;
+  const span = rows.length ? rows[rows.length - 1].arrival_time - rows[0].arrival_time : 0;
+  $("traceStatus").textContent = `${rows.length.toLocaleString()} requests loaded (${fmt(span, 2)} s span)`;
+  showToast("Trace loaded");
+}
+$("traceFile").addEventListener("change", async (event) => {
+  const file = event.target.files?.[0];
+  if (!file) return;
+  try { await loadTraceFile(file); }
+  catch (error) { traceRequests = []; $("traceStatus").textContent = "Trace rejected"; alert(`Trace load failed: ${error.message}`); }
+});
+$("traceClearBtn").addEventListener("click", () => {
+  traceRequests = [];
+  $("traceFile").value = "";
+  $("traceStatus").textContent = "No trace loaded";
+});
+
 function syncConditionalControls() {
   const pd = $("topology").value === "disaggregated_pd";
   $("pdControls").classList.toggle("hidden", !pd);
@@ -595,7 +802,12 @@ function syncConditionalControls() {
     showToast("Static FCFS switched to Continuous FCFS for P/D topology");
   }
   $("prefixControls").classList.toggle("hidden", !boolSelect("prefixCache"));
+  const trace = $("arrival").value === "trace";
   $("burstControls").classList.toggle("hidden", $("arrival").value !== "bursty");
+  $("traceControls").classList.toggle("hidden", !trace);
+  ["rate", "duration", "promptMean", "promptCv", "outputMean", "outputCv"].forEach((id) => { $(id).disabled = trace; });
+  $("capacityBtn").disabled = trace || !runtimePill.classList.contains("ready");
+  $("capacityBtn").title = trace ? "Capacity search is undefined for a fixed arrival trace" : "";
 }
 $("topology").addEventListener("change", syncConditionalControls);
 $("prefixCache").addEventListener("change", syncConditionalControls);

docs/architecture.md

@@ -1,18 +1,20 @@
 # Architecture
 
-InferScale-Sim separates **serving-system logic** from **latency estimation**.
+InferScale-Sim separates **serving-system logic**, **analytical latency estimation**, and **research methodology**.
 
 ## Main Python modules
 
-1. `workloads.py` creates deterministic workload traces and shared-prefix hit assignments.
+1. `workloads.py` creates deterministic synthetic workloads or exact trace-replay requests.
 2. `simulator.py` implements the colocated serving loop.
 3. `disaggregated.py` implements separate prefill/decode worker pools plus KV transfer.
 4. `kv_cache.py` handles memory/admission and shared-prefix allocation.
-5. `latency.py` predicts reference prefill/decode operation durations.
-6. `metrics.py` derives request-level TTFT, TPOT, E2E, queueing, throughput, and goodput.
+5. `latency.py` predicts reference prefill/decode operation durations and exposes sensitivity scales.
+6. `metrics.py` derives TTFT, TPOT, E2E, queueing, throughput, goodput, and SLO attainment.
 7. `diagnostics.py` converts simulated telemetry into explicit heuristic bottleneck labels.
-8. `optimizer.py` implements capacity search, scheduler comparison, topology/cache comparison, and the bounded Pareto sweep.
-9. `api.py` exposes JSON-like actions to both local Python and Pyodide.
+8. `optimizer.py` implements capacity search, scheduler comparison, topology/cache comparison, and Pareto sweeps.
+9. `research.py` implements paired common-seed A/B studies, bootstrap intervals, and analytical-model sensitivity analysis.
+10. `validation.py` compares predictions against externally supplied measured cases.
+11. `api.py` exposes JSON-like actions to local Python and Pyodide.
 
 ## Colocated path
 
@@ -32,11 +34,25 @@ arrival
   -> complete
 ```
 
-The P/D path is a genuine discrete-event loop: prefill workers, decode workers, and the transfer link can have overlapping virtual activity.
+The P/D path is a genuine discrete-event loop: prefill workers, decode workers, and the transfer link can overlap in virtual time.
+
+## Research path
+
+```text
+base configuration
+      |
+      +--> paired A/B study --> shared seeds --> paired deltas --> bootstrap CI
+      |
+      +--> sensitivity study --> shared latency perturbations --> ranking/SLO stability
+      |
+      `--> external measurements --> prediction residuals / MAPE
+```
+
+The simulator and statistical layer are separate on purpose: research conclusions are derived from repeated simulations rather than from one displayed run.
 
 ## Browser execution
 
-Canonical source lives in `src/inferscale`. `scripts/sync_web_python.py` mirrors it into `py/inferscale`. A module Web Worker loads Pyodide, writes those files into Pyodide's virtual filesystem, imports `inferscale.api`, and exchanges JSON messages with the UI.
+Canonical source lives in `src/inferscale`. `scripts/sync_web_python.py` mirrors it into `py/inferscale`. A module Web Worker loads Pyodide, writes those files into the virtual filesystem, imports `inferscale.api`, and exchanges JSON messages with the UI.
 
 The simulator therefore runs away from the browser main thread and uses the same Python implementation as the local tests.
 
@@ -49,4 +65,4 @@ The simulator therefore runs away from the browser main thread and uses the same
 - `model_weight_gb`
 - `kv_bytes_per_token()`
 
-without rewriting scheduling, cache, P/D orchestration, SLO metrics, or search tooling.
+without rewriting workload generation, scheduling, cache logic, P/D orchestration, SLO metrics, or research protocols.

docs/methodology.md

@@ -1,45 +1,49 @@
 # Methodology and limitations
 
-## What v0.3 simulates
+## What is simulated
 
 InferScale models request arrival, queueing, admission, prefill, autoregressive decode, dynamic batch membership, KV-cache memory, and request completion.
 
-For P/D disaggregation it additionally models independent prefill/decode worker pools and explicit prompt-KV transfer before decode admission.
-
-Metrics are computed from per-request virtual timestamps.
+For P/D disaggregation it additionally models independent prefill/decode worker pools and explicit prompt-KV transfer before decode admission. Metrics are computed from per-request virtual timestamps.
 
 ## Scheduler semantics
 
 - `static_fcfs`: admits one colocated batch and drains it before admitting new requests.
 - `continuous_fcfs`: admits FCFS work whenever decode slots become available.
 - `continuous_sjf`: prioritizes shorter estimated jobs at admission.
-- `continuous_slo`: uses a least-slack-style ordering based on E2E deadline and an analytical remaining-service estimate.
+- `continuous_slo`: uses least-slack-style ordering from the E2E deadline and an analytical remaining-service estimate.
 - `chunked_slo`: combines least-slack ordering with chunked prompt prefill.
 
-These are transparent approximations, not line-by-line reproductions of vLLM or SGLang.
-
-Static batching is intentionally excluded from the P/D comparison; if requested for P/D, the simulator warns and uses continuous semantics.
+These are transparent approximations, not line-by-line reproductions of vLLM or SGLang. Static batching is excluded from P/D comparisons; a requested static P/D run is converted to continuous semantics with an explicit warning.
 
 ## Workload semantics
 
-Poisson arrivals use exponentially distributed inter-arrival times. Constant arrivals are evenly spaced. Bursty arrivals alternate lower and higher rate periods.
+Poisson arrivals use exponentially distributed inter-arrival times. Constant arrivals are evenly spaced. Bursty arrivals alternate lower and higher rate periods. Prompt/output lengths use log-normal distributions parameterized by mean and coefficient of variation.
+
+All generated arrival modes are **open-loop**: arrival scheduling does not wait for prior responses to finish. This preserves queueing delay under overload instead of allowing client backpressure to hide tail latency.
+
+Exact trace replay accepts rows with:
+
+```text
+arrival_time, prompt_tokens, output_tokens
+```
 
-Prompt/output lengths are sampled from log-normal distributions parameterized by mean and coefficient of variation (CV).
+and preserves those values directly. Capacity search is intentionally disabled for exact traces because changing `request_rate_rps` would not change a fixed arrival sequence.
 
 ## Shared-prefix model
 
-v0.3 models one reusable exact prefix:
+The simulator models one reusable exact prefix:
 
-1. cache hits are assigned deterministically with a separate seeded RNG so enabling cache does **not** change the underlying arrival/prompt/output trace;
-2. a hit reduces prefill work by the configured reusable-prefix length, bounded by the request prompt;
-3. shared prefix KV consumes one persistent allocation per serving worker rather than being duplicated per request;
-4. decode still uses the full logical context length for attention-cost estimation.
+1. cache hits use a separate seeded RNG so enabling cache does not alter the arrival/prompt/output trace;
+2. a hit reduces prefill work by the reusable-prefix length, bounded by prompt length;
+3. shared prefix KV consumes one persistent allocation per serving worker instead of being duplicated per request;
+4. decode still uses the full logical context for attention-cost estimation.
 
-This isolates prefix reuse without implementing radix-tree lookup, eviction, or prefix-aware scheduling.
+This isolates exact prefix reuse without implementing radix-tree lookup, eviction, or cache-aware routing.
 
 ## P/D disaggregation
 
-P/D uses a global discrete-event queue with four main event classes:
+P/D uses a global event queue with four main event classes:
 
 ```text
 arrival
@@ -48,17 +52,17 @@ transfer_done
 decode_done
 ```
 
-Prefill workers batch queued requests independently. Completed prompt state is placed on a serialized transfer link. Decode workers admit transferred requests only between decode iterations, preserving continuous-batching semantics.
+Prefill workers batch queued requests independently. Completed prompt state enters a serialized transfer link. Decode workers admit transferred requests only between decode iterations, preserving continuous-batching semantics.
 
 The transfer model is:
 
 ```text
-base_latency + bytes / bandwidth
+(base_latency + bytes / bandwidth) x transfer_scale
 ```
 
 where transferred bytes correspond to newly computed prompt KV. With a cache hit, shared-prefix state is assumed resident in both role pools and only the uncached suffix is transferred.
 
-The model does not claim protocol-level fidelity to PCIe, NVLink, RDMA, NIXL, or NCCL.
+The model does not claim protocol-level fidelity to PCIe, NVLink, RDMA, NIXL, NCCL, or any particular production transport.
 
 ## Latency model
 
@@ -66,9 +70,11 @@ The default reference model is roofline-inspired:
 
 - dense transformer FLOPs scale with parameter count and processed tokens;
 - attention adds context-length-dependent work;
-- decode includes model-weight traffic and context-dependent KV reads;
+- decode includes weight traffic and context-dependent KV reads;
 - time is approximated from compute/memory costs plus a launch/scheduling proxy;
-- conservative efficiency factors keep accelerator peak specs from being treated as achieved throughput.
+- conservative efficiency factors prevent peak hardware specifications from being treated as achieved throughput.
+
+Prefill and decode expose multiplicative sensitivity scales. These default to 1.0 and are used only by research stress tests unless explicitly supplied.
 
 This creates useful qualitative dynamics but is **not empirically calibrated**.
 
@@ -89,25 +95,42 @@ Each offered rate is evaluated over deterministic seed offsets and is feasible o
 1. reaches the configured SLO-attainment target; and
 2. fully drains all generated requests.
 
-The result retains mean, worst, best, and standard-deviation evidence. A bounded binary search estimates the highest feasible rate and a recommended rate after user-selected headroom.
+The result retains mean, worst, best, and standard-deviation evidence. A bounded binary search estimates the highest feasible rate and a recommended load after user-selected headroom.
 
 ## Design-space explorer
 
-The browser-safe v0.3 sweep evaluates:
+The browser-safe sweep evaluates:
 
 - three colocated continuous schedulers over batch sizes 8/16/32;
-- one additional cached SLO-aware colocated point at the user's current batch size;
+- one cached SLO-aware colocated point at the current batch size;
 - optionally P/D worker splits 1P:1D, 1P:2D, and 2P:1D, each with cache off/on.
 
-A candidate is Pareto-optimal when no other candidate has both **at least as much goodput** and **no worse p95 TTFT**, with at least one strict improvement.
+A candidate is performance-Pareto-optimal when no other candidate has both at least as much goodput and no worse p95 TTFT, with at least one strict improvement. An independent efficiency frontier replaces raw goodput with goodput per accelerator.
+
+This is a bounded interactive design study, not exhaustive global optimization.
+
+## Paired A/B studies
+
+A paired study compares one controlled system change repeatedly. Baseline and treatment receive the same seed on every repetition. This is the common-random-numbers variance-reduction idea: both alternatives see the same sampled workload, so the paired delta is less contaminated by workload randomness.
+
+For each metric InferScale reports:
+
+- baseline and treatment means;
+- mean and median paired delta;
+- treatment win rate;
+- mean relative change;
+- 95% percentile-bootstrap interval over paired deltas.
+
+The bootstrap interval is an uncertainty summary for the simulated repeated experiment. It is not evidence that the analytical hardware profile itself is empirically correct.
 
-This is a bounded interactive study, not exhaustive global optimization.
+## Analytical-model sensitivity
 
-## Validation status
+The robustness study draws shared multiplicative prefill/decode/transfer scales inside a user-defined band and applies each draw to both alternatives. It reports how often the treatment wins TTFT/goodput/E2E and how often each alternative satisfies the SLO.
 
-v0.3 validates deterministic software invariants and expected qualitative behavior through tests. It does **not** provide held-out GPU calibration error. Empirical profile import/calibration remains a future extension rather than being fabricated for this release.
+The perturbation distribution is deliberately described as a **sensitivity analysis**, not a calibrated posterior over real hardware. Its purpose is to identify conclusions that reverse under modest model error.
 
+## Empirical validation
 
-## Resource-normalized design comparison
+`validation.py` accepts externally measured cases and compares them against simulator predictions. Supported observations include p95 TTFT, p95 E2E, goodput, request throughput, and SLO attainment. The report contains per-case residuals, MAPE, median APE, and maximum APE.
 
-P/D candidates can use more simulated accelerator instances than colocated candidates. v0.3 therefore reports both raw goodput and `goodput / accelerator`. The Design Explorer computes a separate Pareto frontier for each throughput objective against p95 TTFT. This avoids treating additional hardware as a free improvement and keeps raw performance distinct from resource efficiency.
+No measured benchmark values are bundled as truth with the project.

docs/research.md

@@ -1,67 +1,85 @@
 # Research context
 
-InferScale-Sim is a portfolio-scale implementation situated within the research line on replacing expensive deployment sweeps with modeling, simulation, or emulation.
+InferScale-Sim is a portfolio-scale implementation situated within the research line on replacing expensive deployment sweeps with modeling, simulation, emulation, and statistically careful load testing.
 
 ## Vidur (2024)
 
-Vidur combines experimental profiling, predictive models, and end-to-end inference simulation. Its paper reports under 9% inference-latency estimation error across the evaluated range and a configuration-search example where LLaMA2-70B exploration took about one CPU-hour versus an estimated 42K GPU-hours (~$218K) for deployment-based exploration.
+Vidur combines experimental profiling, predictive models, and end-to-end inference simulation. Its paper reports inference-latency estimates below 9% error in the evaluated range and a configuration-search example where LLaMA2-70B exploration took about one CPU-hour versus an estimated 42K GPU-hours (~$218K) for deployment-based exploration.
 
-InferScale inspiration: workload-aware configuration search, explicit performance-profile provenance, and separation between latency prediction and event simulation.
+InferScale inspiration: explicit performance-profile provenance, workload-aware search, and separation between latency prediction and event simulation.
 
 Source: https://arxiv.org/abs/2405.05465
 
 ## SGLang / RadixAttention (2024)
 
-SGLang introduced RadixAttention for automatic KV-cache reuse across shared prompt prefixes. A radix tree retains reusable prompt/generation state and combines prefix lookup with cache-aware scheduling and eviction.
-
-InferScale v0.3 does not implement a radix tree. It adds a deliberately smaller controlled shared-prefix abstraction so the effect of avoiding repeated prefill and duplicate KV allocation can be studied independently.
+SGLang introduced RadixAttention for automatic KV-cache reuse across shared prefixes. InferScale does not implement a radix tree; it uses a controlled exact-prefix abstraction so the compute and memory consequences can be isolated and paired against an identical workload.
 
 Source: https://arxiv.org/abs/2312.07104
 
 ## TokenSim (2025)
 
-TokenSim emphasizes extensible exploration of scheduling and memory-management choices and reports sub-1% error in its evaluated workloads.
+TokenSim emphasizes extensible scheduling and memory-management exploration.
 
-InferScale inspiration: modular scheduler/memory experiments.
+InferScale inspiration: modular scheduler/memory experiments rather than a single hard-coded serving policy.
 
 Source: https://arxiv.org/abs/2503.08415
 
 ## Revati (2026)
 
-Revati avoids reimplementing every evolving serving-system control decision: it executes real vLLM/SGLang control paths while virtualizing CUDA time. The paper reports less than 5% prediction error across its evaluated scenarios and 5-17x faster execution than real GPU serving runs.
+Revati executes real serving control paths while virtualizing GPU time, addressing a fidelity limitation of simulators that reimplement rapidly evolving runtime logic.
 
-InferScale lesson: pure simulation has a control-path fidelity ceiling. Our schedulers therefore document their semantics rather than claiming framework equivalence.
+InferScale lesson: scheduler semantics must be documented as explicit approximations rather than presented as framework equivalence.
 
 Source: https://arxiv.org/abs/2601.00397
 
 ## LLMServingSim 2.0 (2026)
 
-LLMServingSim 2.0 focuses on heterogeneous and disaggregated infrastructure and integrates batching, routing, offloading, memory, communication, and power into a unified runtime loop. The 2026 paper reports about 0.97% average error in its validation.
+LLMServingSim 2.0 models heterogeneous and disaggregated serving while integrating runtime decisions with batching, routing, memory, communication, and power. The paper reports 0.97% average error in its validation.
 
-InferScale v0.3 inspiration: role-specific resources and explicit data movement rather than assuming a monolithic replica.
+InferScale inspiration: role-specific resources and explicit data movement rather than a monolithic-replica abstraction.
 
 Source: https://arxiv.org/abs/2602.23036
 
 ## Frontier (May 2026)
 
-Frontier models co-location, Prefill-Decode Disaggregation, Attention-FFN Disaggregation, runtime optimizations such as speculative decoding, and stateful workloads. It reports average throughput error below 4% on its 16-H800 evaluation and explicitly supports SLA-dependent Pareto-frontier exploration.
+Frontier models co-location, Prefill-Decode Disaggregation, Attention-FFN Disaggregation, runtime optimizations such as speculative decoding, and stateful workloads. It reports average throughput error below 4% on its H800 evaluation and supports SLA-dependent Pareto exploration.
 
-InferScale v0.3 inspiration:
+InferScale inspiration:
 
-- separate prefill and decode worker pools;
+- separate prefill/decode workers;
 - communication/KV-transfer cost;
 - role-specific bottleneck telemetry;
-- an interactive bounded Pareto design-space study.
+- resource-aware Pareto design studies.
 
 Source: https://arxiv.org/abs/2605.21312
 
-## Scope boundary
+## AgentServeSim (June 2026)
+
+AgentServeSim extends serving simulation to multi-turn programs with tool-induced gaps, session-aware routing, cache locality, and KV residency. It reports reproducing real-system behavior within 6% across its evaluated metrics while executing on CPUs.
+
+InferScale uses this as a roadmap boundary: exact trace replay exists today, while session identity, tool gaps, and cross-turn residency are explicit future work rather than being approximated silently.
+
+Source: https://arxiv.org/abs/2606.09613
+
+## Vanguard / Load Testing for ML Serving Systems at Scale (June 2026)
 
-InferScale-Sim v0.3 is not intended to compete with these research systems on fidelity, hardware scale, or runtime compatibility. Its goal is an inspectable, dependency-light Python implementation with a zero-backend interactive interface for understanding the systems mechanisms that motivate them.
+Vanguard highlights two methodology points that directly influence InferScale:
 
+1. **open-loop replay** avoids coordinated omission by scheduling requests independently of response time;
+2. repeated load-test analysis benefits from reproducibility statistics and bootstrap confidence intervals.
 
-## HeteroPanacea / When Does Disaggregation Pay? (Aug 2026)
+InferScale's generated workloads are open-loop, trace replay preserves externally supplied arrivals, and Research Studies use repeated paired simulations with bootstrap intervals.
 
-**When Does Disaggregation Pay? Simulating Prefill--Decode--Attention--FFN Specialization for Agentic LLM Inference** pushes the simulator design space toward heterogeneous stage-specific hardware and automated cross-stack exploration. InferScale-Sim v0.3 does not model Attention--FFN disaggregation or custom NPUs, but its P/D topology already permits independent prefill and decode accelerator profiles and reports resource-normalized efficiency so heterogeneous layouts can be compared without treating extra accelerators as free.
+Source: https://arxiv.org/abs/2606.22013
+
+## HeteroPanacea / When Does Disaggregation Pay? (August 2026)
+
+HeteroPanacea pushes design exploration toward stage-specific heterogeneous hardware, quantization, parallelism, and Prefill/Decode/Attention/FFN disaggregation. The paper emphasizes that disaggregation gains are conditional on workload and hardware design rather than universally beneficial.
+
+InferScale's smaller P/D model already separates role hardware, worker counts, interconnect cost, and resource-normalized goodput. It does not model custom NPUs or Attention-FFN disaggregation.
+
+Source: https://arxiv.org/abs/2608.03741
+
+## Scope boundary
 
-- arXiv: https://arxiv.org/abs/2608.03741
+InferScale-Sim is not intended to compete with these research systems on fidelity, hardware scale, or runtime compatibility. Its aim is an inspectable Python implementation with a zero-backend interactive interface, explicit uncertainty, controlled experiments, and a path to external empirical validation.

docs/validation.md

@@ -1,13 +1,14 @@
-# v0.3 validation checklist
+# Validation checklist
 
-The release checks prevent software, deployment, and provenance mistakes; they do not pretend the analytical profile has measured-hardware fidelity.
+Release checks prevent software, deployment, and provenance mistakes; they do not pretend the analytical profile has measured-hardware fidelity.
 
-## Automated
+## Automated software checks
 
-- deterministic workload generation
-- constant/Poisson/bursty workload behavior
+- deterministic constant/Poisson/bursty workload generation
+- exact trace replay and trace validation
 - prefill latency monotonicity
 - quantization footprint ordering
+- latency sensitivity-scale behavior
 - colocated end-to-end completion
 - static vs continuous behavioral difference
 - component TTFT/E2E SLO accounting
@@ -15,11 +16,14 @@ The release checks prevent software, deployment, and provenance mistakes; they d
 - bottleneck-diagnosis provenance
 - prefix hits do not alter the underlying generated request trace
 - prefix reuse reduces modeled prefill work
-- P/D pipeline completion
-- non-zero P/D transfer telemetry
+- P/D pipeline completion and transfer telemetry
 - configurable P/D worker counts
 - four-scenario topology/cache comparison
-- bounded design-space sweep and Pareto marking
+- bounded design-space sweep and two Pareto objectives
+- paired common-seed research study
+- bootstrap paired-effect intervals
+- analytical-profile perturbation study
+- external-measurement validation report generation
 - ASCII-only public UI labels
 - chart export controls present
 - explicit planner worst-repetition and target columns
@@ -27,12 +31,34 @@ The release checks prevent software, deployment, and provenance mistakes; they d
 - Hugging Face `short_description` <= 60 characters
 - `sdk: static` metadata
 - canonical Python source equals browser mirror
-- every Python module is included by the worker
+- every browser Python module is included by the worker
 - provenance remains `analytical-reference`
 - JavaScript syntax parse
 - Python compilation
 
-## Not claimed in v0.3
+## Empirical validation protocol
+
+A future hardware run should be stored as external validation cases, not copied into analytical profiles without provenance. At minimum each case should record:
+
+- model / revision
+- serving topology and scheduler
+- accelerator / count
+- precision
+- workload arrival process or trace ID
+- prompt/output distribution or exact trace
+- SLO definition
+- p95 TTFT / p95 E2E / goodput
+- runtime/software versions
+
+Run:
+
+```bash
+python scripts/validate_measurements.py measured_cases.json --output validation_report.json
+```
+
+The report provides residuals and aggregate percentage errors. Calibration should be fit on a training subset and reported on held-out cases if empirical fitting is added later.
+
+## Not claimed
 
 - empirical L4/A10G/A100 latency accuracy
 - exact vLLM/SGLang scheduler equivalence
@@ -43,9 +69,4 @@ The release checks prevent software, deployment, and provenance mistakes; they d
 - Attention-FFN disaggregation
 - multi-turn/agentic session fidelity
 
-These remain explicit future extensions.
-
-
-## Design-space sanity checks
-
-The release suite verifies that the bounded design sweep returns at least one raw-performance Pareto point and at least one resource-efficiency Pareto point. P/D candidates also expose accelerator-instance counts so raw and normalized throughput can be interpreted separately.
+These are explicit scope boundaries, not hidden assumptions.

examples/trace.csv

@@ -0,0 +1,9 @@
+arrival_time,prompt_tokens,output_tokens
+0.000,512,64
+0.180,256,48
+0.410,768,96
+0.730,384,40
+1.020,1024,128
+1.360,192,32
+1.780,640,72
+2.140,320,56

examples/validation_cases.schema.json

@@ -0,0 +1,22 @@
+{
+  "cases": [
+    {
+      "name": "replace-with-a-real-measured-case",
+      "config": {
+        "model": "Qwen2.5-3B",
+        "accelerator": "L4",
+        "quantization": "int8",
+        "request_rate_rps": 4,
+        "duration_s": 30,
+        "prompt_tokens_mean": 512,
+        "output_tokens_mean": 64
+      },
+      "measured": {
+        "p95_ttft_ms": 0,
+        "p95_e2e_ms": 0,
+        "goodput_rps": 0
+      }
+    }
+  ],
+  "note": "Template only. Zero placeholders are not benchmark measurements and should be replaced before use."
+}

index.html

@@ -23,7 +23,7 @@
   <main class="shell">
     <section class="intro">
       <div class="intro-copy">
-        <div class="eyebrow">InferScale-Sim / v0.3.0</div>
+        <div class="eyebrow">InferScale-Sim</div>
         <h1>Explore serving policies, cache reuse, and P/D disaggregation without provisioning a GPU.</h1>
         <p>Generate workloads, compare schedulers, model KV pressure and prefix reuse, separate prefill from decode, and search the SLO-constrained design space. The simulator is Python running locally in a Pyodide Web Worker.</p>
       </div>
@@ -43,6 +43,7 @@
       <button class="tab" data-tab="planner">Capacity Planner</button>
       <button class="tab" data-tab="modern">Modern Serving</button>
       <button class="tab" data-tab="design">Design Explorer</button>
+      <button class="tab" data-tab="research">Research Studies</button>
       <button class="tab" data-tab="method">Methodology</button>
     </nav>
 
@@ -86,7 +87,7 @@
           <hr />
           <div class="section-kicker">Workload</div>
           <div class="field-grid two">
-            <label>Arrival process<select id="arrival"><option value="poisson">Poisson</option><option value="constant">Constant</option><option value="bursty">Bursty</option></select></label>
+            <label>Arrival process<select id="arrival"><option value="poisson">Poisson</option><option value="constant">Constant</option><option value="bursty">Bursty</option><option value="trace">Trace replay</option></select></label>
             <label>Request rate<input id="rate" type="number" min="0.1" step="0.1" value="4" /><span class="unit">req/s</span></label>
             <label>Duration<input id="duration" type="number" min="2" step="1" value="30" /><span class="unit">sim s</span></label>
             <label>Seed<input id="seed" type="number" step="1" value="7" /></label>
@@ -95,6 +96,12 @@
             <label>Burst multiplier<input id="burstMultiplier" type="number" min="1" step="0.25" value="3" /><span class="unit">x</span></label>
             <label>Burst period<input id="burstPeriod" type="number" min="0.5" step="0.5" value="10" /><span class="unit">s</span></label>
           </div>
+          <div id="traceControls" class="subcontrols hidden">
+            <div class="section-kicker">Exact trace replay</div>
+            <label class="file-label">Workload file<input id="traceFile" type="file" accept=".csv,.json,text/csv,application/json" /></label>
+            <div class="trace-row"><span id="traceStatus">No trace loaded</span><button id="traceClearBtn" class="mini-button" type="button">Clear</button></div>
+            <p class="control-help">CSV or JSON rows: arrival_time, prompt_tokens, output_tokens. Trace replay preserves exact arrivals and token lengths; the Capacity Planner is disabled because offered rate is fixed by the trace.</p>
+          </div>
           <div class="field-grid two">
             <label>Prompt mean<input id="promptMean" type="number" min="16" value="512" /><span class="unit">tokens</span></label>
             <label>Prompt CV<input id="promptCv" type="number" min="0" max="2" step="0.05" value="0.50" /></label>
@@ -165,7 +172,7 @@
     <section id="arena" class="tab-panel">
       <div class="panel wide-panel">
         <div class="panel-title-row arena-title-row">
-          <div><div class="section-kicker">Same workload - same seed</div><h2>Scheduler Arena</h2><p class="muted">Run every colocated v0.3 scheduler against the current Serving Lab workload and rank by SLO attainment, then goodput.</p></div>
+          <div><div class="section-kicker">Same workload - same seed</div><h2>Scheduler Arena</h2><p class="muted">Run every colocated scheduler against the current Serving Lab workload and rank by SLO attainment, then goodput.</p></div>
           <button id="arenaBtn" class="primary compact" disabled>Compare schedulers</button>
         </div>
         <div id="arenaEmpty" class="empty-state small"><h3>No comparison yet</h3><p>Your Serving Lab workload and model controls are reused automatically.</p></div>
@@ -261,13 +268,77 @@
       </div>
     </section>
 
+
+    <section id="research" class="tab-panel">
+      <div class="research-grid">
+        <aside class="panel research-controls">
+          <div class="panel-title-row"><h2>Research protocol</h2><span class="tag">Paired seeds</span></div>
+          <p class="muted">Test one systems hypothesis repeatedly on matched workloads, then stress the conclusion against analytical-profile uncertainty.</p>
+          <label>Hypothesis<select id="studyPreset">
+            <option value="prefix_cache">Prefix reuse: off vs on</option>
+            <option value="pd_vs_colocated">Topology: colocated vs P/D</option>
+            <option value="chunked_vs_fcfs">Scheduling: FCFS vs chunked prefill</option>
+            <option value="slo_vs_fcfs">Scheduling: FCFS vs least-slack</option>
+          </select></label>
+          <hr />
+          <div class="section-kicker">Paired Monte Carlo</div>
+          <div class="field-grid two">
+            <label>Repetitions<input id="studyReps" type="number" min="2" max="64" value="12" /></label>
+            <label>Bootstrap samples<input id="studyBootstrap" type="number" min="50" max="5000" step="50" value="500" /></label>
+          </div>
+          <button id="pairedStudyBtn" class="primary" disabled>Run paired study</button>
+          <hr />
+          <div class="section-kicker">Model uncertainty stress test</div>
+          <div class="field-grid two">
+            <label>Samples<input id="robustSamples" type="number" min="4" max="96" value="32" /></label>
+            <label>Latency uncertainty<input id="robustUncertainty" type="number" min="0" max="0.75" step="0.05" value="0.20" /><span class="unit">fraction</span></label>
+          </div>
+          <button id="robustStudyBtn" class="secondary research-secondary" disabled>Stress-test conclusion</button>
+        </aside>
+
+        <div class="research-results">
+          <section class="panel research-panel">
+            <div class="panel-title-row"><div><div class="section-kicker">Controlled A/B experiment</div><h2>Paired study</h2></div><span id="pairedState" class="tag neutral">Waiting</span></div>
+            <div id="pairedEmpty" class="empty-state small"><h3>No paired experiment yet</h3><p>Baseline and treatment use the same random seed on every repetition. The reported confidence interval is over paired deltas, not unrelated runs.</p></div>
+            <div id="pairedContent" class="hidden">
+              <div class="study-summary" id="pairedSummary"></div>
+              <div class="chart-card full" data-chart-card data-chart-name="paired-study-relative-effects">
+                <div class="chart-head"><div class="chart-title">Treatment effect by metric</div><div class="chart-actions"><button class="chart-download" type="button">Download PNG</button><button class="chart-expand" type="button">Expand</button></div></div>
+                <div class="chart-body research-chart"><canvas id="pairedChart"></canvas></div>
+              </div>
+              <div class="table-toolbar"><span>Paired effect estimates</span><div><button id="pairedCopyBtn" class="mini-button" disabled>Copy table</button><button id="pairedCsvBtn" class="mini-button" disabled>Download CSV</button><button id="pairedJsonBtn" class="mini-button" disabled>Download JSON</button></div></div>
+              <div class="table-wrap"><table><thead><tr><th>Metric</th><th>Baseline mean</th><th>Treatment mean</th><th>Mean delta</th><th>95% bootstrap CI</th><th>Relative change</th><th>Treatment win rate</th><th>CI excludes zero</th></tr></thead><tbody id="pairedRows"></tbody></table></div>
+            </div>
+          </section>
+
+          <section class="panel research-panel">
+            <div class="panel-title-row"><div><div class="section-kicker">Sensitivity analysis</div><h2>Conclusion robustness</h2></div><span id="robustState" class="tag neutral">Waiting</span></div>
+            <div id="robustEmpty" class="empty-state small"><h3>No stress test yet</h3><p>Shared multiplicative perturbations are applied to prefill, decode, and transfer latency proxies. This tests sensitivity to profile error; it is not a probability distribution over real hardware.</p></div>
+            <div id="robustContent" class="hidden">
+              <div class="metric-grid four">
+                <div class="metric"><span>TTFT wins</span><strong id="rTtftWins">N/A</strong></div>
+                <div class="metric"><span>Goodput wins</span><strong id="rGoodputWins">N/A</strong></div>
+                <div class="metric"><span>Treatment SLO pass</span><strong id="rTreatmentPass">N/A</strong></div>
+                <div class="metric"><span>Baseline SLO pass</span><strong id="rBaselinePass">N/A</strong></div>
+              </div>
+              <div class="study-summary" id="robustSummary"></div>
+              <div class="table-toolbar"><span>Perturbation summary</span><div><button id="robustCopyBtn" class="mini-button" disabled>Copy table</button><button id="robustCsvBtn" class="mini-button" disabled>Download CSV</button><button id="robustJsonBtn" class="mini-button" disabled>Download JSON</button></div></div>
+              <div class="table-wrap"><table><thead><tr><th>Sample</th><th>Prefill scale</th><th>Decode scale</th><th>Transfer scale</th><th>Baseline SLO</th><th>Treatment SLO</th><th>Goodput delta</th><th>TTFT delta</th><th>E2E delta</th></tr></thead><tbody id="robustRows"></tbody></table></div>
+            </div>
+          </section>
+        </div>
+      </div>
+    </section>
+
     <section id="method" class="tab-panel">
       <div class="method-grid">
         <article class="panel prose"><div class="section-kicker">Simulation core</div><h2>What is actually simulated?</h2><p>Requests are generated from deterministic workload distributions and advanced through virtual time. Colocated runs model admission, prefill, paged KV allocation, dynamic decode batches, and completion. P/D runs use separate prefill and decode worker pools plus an explicit serialized KV-transfer link.</p><div class="formula">request -> queue -> prefill -> [KV transfer] -> decode -> completion</div></article>
-        <article class="panel prose"><div class="section-kicker">Prefix reuse</div><h2>Cache without pretending to implement a radix tree</h2><p>v0.3 models a single shared prompt prefix with configurable length and reuse fraction. Cache hits avoid redundant prefill work and share one persistent KV allocation. It is deliberately a controlled what-if abstraction, not a claim to reproduce SGLang's full RadixAttention policy.</p></article>
+        <article class="panel prose"><div class="section-kicker">Prefix reuse</div><h2>Cache without pretending to implement a radix tree</h2><p>The simulator models a single shared prompt prefix with configurable length and reuse fraction. Cache hits avoid redundant prefill work and share one persistent KV allocation. It is deliberately a controlled what-if abstraction, not a claim to reproduce SGLang's full RadixAttention policy.</p></article>
         <article class="panel prose"><div class="section-kicker">P/D disaggregation</div><h2>Role-specific resources and transfer cost</h2><p>Prefill and decode have separate accelerator profiles and worker counts. Prompt KV state crosses a modeled interconnect before decode admission. The simulator reports role utilization, transfer latency, and transfer pressure so the benefit of isolation can be weighed against data-movement overhead.</p></article>
         <article class="panel prose"><div class="section-kicker">Design search</div><h2>Pareto, not one magic configuration</h2><p>The Design Explorer reports both a raw-performance frontier and a resource-normalized frontier using goodput per accelerator. That prevents a multi-GPU P/D layout from looking unconditionally better merely because it uses more simulated hardware.</p></article>
-        <article class="panel prose wide-method"><div class="section-kicker">Research lineage</div><h2>Why these features are in v0.3</h2><p>Vidur established the value of simulation for avoiding expensive deployment sweeps. Recent systems have pushed toward heterogeneous and disaggregated serving, communication-aware modeling, runtime optimizations, and SLA-dependent design-space exploration. InferScale-Sim remains intentionally smaller and inspectable.</p><div class="paper-grid"><div><strong>Vidur / 2024</strong><span>Predictive profiling, workload-aware serving simulation, configuration search.</span></div><div><strong>TokenSim / 2025</strong><span>Extensible scheduling and memory-management simulation.</span></div><div><strong>Revati / 2026</strong><span>GPU-free time-warp emulation of serving control logic.</span></div><div><strong>LLMServingSim 2.0 / 2026</strong><span>Heterogeneous and disaggregated infrastructure, memory and communication.</span></div><div><strong>Frontier / May 2026</strong><span>P/D disaggregation, runtime optimizations, stateful workloads, Pareto exploration.</span></div><div><strong>HeteroPanacea / Aug 2026</strong><span>Heterogeneous stage specialization motivates resource-aware P/D comparison.</span></div><div><strong>SGLang / RadixAttention</strong><span>Automatic shared-prefix KV reuse motivates the controlled cache scenario.</span></div></div></article>
+        <article class="panel prose"><div class="section-kicker">Trace methodology</div><h2>Generated load or exact replay</h2><p>Poisson, constant, and bursty workloads are open-loop: arrivals are scheduled independently of response completion, so queueing delay is not hidden by client backpressure. Exact CSV/JSON traces can be replayed with their original arrival times and token lengths.</p></article>
+        <article class="panel prose"><div class="section-kicker">Research protocol</div><h2>Paired conclusions, not one lucky seed</h2><p>Research Studies use common random numbers: baseline and treatment receive identical seeds, reducing workload variance in the paired difference. A bootstrap interval summarizes the repeated effect, while a separate sensitivity study perturbs analytical latency scales to reveal conclusions that depend too strongly on one reference profile.</p></article>
+        <article class="panel prose wide-method"><div class="section-kicker">Research lineage</div><h2>Research lineage and scope</h2><p>Vidur established the value of simulation for avoiding expensive deployment sweeps. Recent systems have pushed toward heterogeneous and disaggregated serving, communication-aware modeling, stateful workloads, trace replay, and SLA-dependent design-space exploration. InferScale-Sim remains intentionally smaller and inspectable, with paired experiments and sensitivity analysis built into the workflow.</p><div class="paper-grid"><div><strong>Vidur / 2024</strong><span>Predictive profiling, workload-aware serving simulation, configuration search.</span></div><div><strong>TokenSim / 2025</strong><span>Extensible scheduling and memory-management simulation.</span></div><div><strong>Revati / 2026</strong><span>GPU-free time-warp emulation of serving control logic.</span></div><div><strong>LLMServingSim 2.0 / 2026</strong><span>Heterogeneous and disaggregated infrastructure, memory and communication.</span></div><div><strong>Frontier / May 2026</strong><span>P/D disaggregation, runtime optimizations, stateful workloads, Pareto exploration.</span></div><div><strong>HeteroPanacea / Aug 2026</strong><span>Heterogeneous stage specialization motivates resource-aware P/D comparison.</span></div><div><strong>Vanguard / Jun 2026</strong><span>Open-loop replay avoids coordinated omission when studying latency under load.</span></div><div><strong>AgentServeSim / Jun 2026</strong><span>Stateful multi-turn serving motivates future session-aware workload modeling.</span></div><div><strong>SGLang / RadixAttention</strong><span>Automatic shared-prefix KV reuse motivates the controlled cache scenario.</span></div></div></article>
       </div>
     </section>
   </main>

py/inferscale/__init__.py

@@ -1,7 +1,9 @@
 from .api import execute, metadata
 from .models import SimulationConfig
 from .optimizer import capacity_search, compare_schedulers, compare_topologies, design_space_search
+from .research import paired_study, robustness_study
 from .simulator import run_simulation
+from .validation import validate_cases
 
 __all__ = [
     "SimulationConfig",
@@ -11,7 +13,12 @@ __all__ = [
     "design_space_search",
     "execute",
     "metadata",
+    "paired_study",
+    "robustness_study",
     "run_simulation",
+    "validate_cases",
 ]
 
-__version__ = "0.3.0"
+# Internal package metadata only; the public project intentionally avoids
+# release/version branding in the interface and documentation.
+__version__ = "0.4.0"

py/inferscale/api.py

@@ -2,16 +2,17 @@ from __future__ import annotations
 
 from .optimizer import capacity_search, compare_schedulers, compare_topologies, design_space_search
 from .profiles import ACCELERATORS, MODELS
+from .research import STUDIES, paired_study, robustness_study
 from .simulator import SCHEDULERS, run_simulation
 
 
 def metadata() -> dict:
     return {
-        "version": "0.3.0",
         "models": list(MODELS.keys()),
         "accelerators": list(ACCELERATORS.keys()),
         "schedulers": sorted(SCHEDULERS),
         "topologies": ["colocated", "disaggregated_pd"],
+        "research_studies": STUDIES,
         "profile_type": "analytical-reference",
     }
 
@@ -38,6 +39,22 @@ def execute(action: str, payload: dict) -> dict:
     if action == "design_space":
         config = payload.get("config", payload)
         return design_space_search(config, bool(payload.get("include_disaggregated", True)))
+    if action == "paired_study":
+        config = payload.get("config", payload)
+        return paired_study(
+            config,
+            study=str(payload.get("study", "prefix_cache")),
+            repetitions=int(payload.get("repetitions", 12)),
+            bootstrap_samples=int(payload.get("bootstrap_samples", 500)),
+        )
+    if action == "robustness_study":
+        config = payload.get("config", payload)
+        return robustness_study(
+            config,
+            study=str(payload.get("study", "pd_vs_colocated")),
+            samples=int(payload.get("samples", 32)),
+            uncertainty=float(payload.get("uncertainty", 0.20)),
+        )
     if action == "metadata":
         return metadata()
     raise ValueError(f"Unknown action: {action}")

py/inferscale/disaggregated.py

@@ -36,7 +36,7 @@ class DecodeWorker:
 class DisaggregatedSimulator:
     """Two-stage prefill/decode discrete-event simulator.
 
-    v0.3 models role-specific worker pools plus a serialized analytical KV-transfer
+    the current model models role-specific worker pools plus a serialized analytical KV-transfer
     link. It is intentionally a systems abstraction, not a distributed-runtime
     emulator: transport, compute and memory timings remain reference-model
     predictions and carry explicit provenance in every result.
@@ -52,8 +52,12 @@ class DisaggregatedSimulator:
         self.model = get_model(cfg.model)
         self.prefill_accelerator = get_accelerator(cfg.prefill_accelerator)
         self.decode_accelerator = get_accelerator(cfg.decode_accelerator)
-        self.prefill_latency = AnalyticalLatencyModel(self.model, self.prefill_accelerator, cfg.quantization)
-        self.decode_latency = AnalyticalLatencyModel(self.model, self.decode_accelerator, cfg.quantization)
+        self.prefill_latency = AnalyticalLatencyModel(
+            self.model, self.prefill_accelerator, cfg.quantization, cfg.prefill_time_scale, cfg.decode_time_scale
+        )
+        self.decode_latency = AnalyticalLatencyModel(
+            self.model, self.decode_accelerator, cfg.quantization, cfg.prefill_time_scale, cfg.decode_time_scale
+        )
 
         self.prefill_workers = [
             PrefillWorker(i, self.prefill_latency, KVCacheModel(self.prefill_latency, cfg))
@@ -168,7 +172,10 @@ class DisaggregatedSimulator:
         bytes_to_transfer = req.uncached_prompt_tokens * self.prefill_latency.kv_bytes_per_token()
         gb = bytes_to_transfer / 1e9
         start = max(self.now, self.transfer_busy_until)
-        duration = self.cfg.transfer_base_ms / 1000.0 + bytes_to_transfer / (self.cfg.interconnect_gbps * 1e9)
+        duration = (
+            self.cfg.transfer_base_ms / 1000.0
+            + bytes_to_transfer / (self.cfg.interconnect_gbps * 1e9)
+        ) * max(self.cfg.transfer_time_scale, 1e-6)
         end = start + duration
         self.transfer_busy_until = end
         self.transfer_busy_time_s += duration
@@ -275,7 +282,8 @@ class DisaggregatedSimulator:
             self.warnings.append("Disaggregated pipeline stalled before all requests completed.")
 
         self._record_timeline(force=True)
-        makespan = max(self.now, self.cfg.duration_s if self.requests else 0.0)
+        workload_horizon = 0.0 if self.cfg.arrival_process == "trace" else (self.cfg.duration_s if self.requests else 0.0)
+        makespan = max(self.now, workload_horizon)
         prefill_util = sum(w.busy_time_s for w in self.prefill_workers) / max(makespan * len(self.prefill_workers), 1e-9)
         decode_util = sum(w.busy_time_s for w in self.decode_workers) / max(makespan * len(self.decode_workers), 1e-9)
         transfer_util = self.transfer_busy_time_s / max(makespan, 1e-9)
@@ -336,8 +344,7 @@ class DisaggregatedSimulator:
         diagnostics = diagnose_run(summary, latency, resource, self.cfg)
         provenance = {
             "simulator": "InferScale-Sim",
-            "version": "0.3.0",
-            "latency_profile_type": "analytical-reference",
+                        "latency_profile_type": "analytical-reference",
             "profile_warning": "Reference profiles are analytical proxies, not measured hardware benchmarks.",
             "model_profile_source": self.model.source,
             "prefill_accelerator_profile_source": self.prefill_accelerator.source,

py/inferscale/latency.py

@@ -15,7 +15,14 @@ class AnalyticalLatencyModel:
     profiles are tagged `analytical-reference` throughout the app.
     """
 
-    def __init__(self, model: ModelProfile, accelerator: AcceleratorProfile, quantization: str = "fp16"):
+    def __init__(
+        self,
+        model: ModelProfile,
+        accelerator: AcceleratorProfile,
+        quantization: str = "fp16",
+        prefill_scale: float = 1.0,
+        decode_scale: float = 1.0,
+    ):
         if quantization not in QUANTIZATION_BYTES:
             raise ValueError(f"Unsupported quantization: {quantization}")
         self.model = model
@@ -23,13 +30,15 @@ class AnalyticalLatencyModel:
         self.quantization = quantization
         self.weight_bytes_per_param = QUANTIZATION_BYTES[quantization]
         self.compute_overhead = QUANTIZATION_COMPUTE_MULTIPLIER[quantization]
+        self.prefill_scale = max(float(prefill_scale), 1e-6)
+        self.decode_scale = max(float(decode_scale), 1e-6)
 
     @property
     def model_weight_gb(self) -> float:
         return self.model.params_b * self.weight_bytes_per_param
 
     def kv_bytes_per_token(self) -> float:
-        # K + V, all layers, KV heads only. KV state is assumed fp16 in v0.3.
+        # K + V, all layers, KV heads only. KV state is assumed fp16 in the current model.
         return (
             2
             * self.model.layers
@@ -74,7 +83,7 @@ class AnalyticalLatencyModel:
         )
         # Kernel launch / scheduling proxy prevents implausibly tiny times.
         launch = 0.0018 + 0.00008 * batch
-        return max(compute, memory * 0.28) + launch
+        return (max(compute, memory * 0.28) + launch) * self.prefill_scale
 
     def decode_step_seconds(self, context_lengths: list[int]) -> float:
         if not context_lengths:
@@ -103,4 +112,4 @@ class AnalyticalLatencyModel:
         )
 
         launch = 0.0012 + 0.000035 * batch + 0.00000003 * avg_context
-        return max(compute, memory) + launch
+        return (max(compute, memory) + launch) * self.decode_scale

py/inferscale/models.py

@@ -58,7 +58,19 @@ class SimulationConfig:
     burst_period_s: float = 10.0
     timeline_points: int = 300
 
-    # Prefix-cache scenario. v0.3 intentionally models one reusable shared
+    # Optional exact workload replay. Each row contains arrival_time,
+    # prompt_tokens, and output_tokens. The trace path is browser-safe because
+    # rows are supplied directly by the UI rather than read from local files.
+    trace_requests: list[dict[str, Any]] = field(default_factory=list)
+
+    # Sensitivity-analysis hooks. Public reference profiles default to 1.0;
+    # research studies perturb these factors to test whether conclusions survive
+    # plausible analytical-model error rather than treating one proxy as truth.
+    prefill_time_scale: float = 1.0
+    decode_time_scale: float = 1.0
+    transfer_time_scale: float = 1.0
+
+    # Prefix-cache scenario. the current model intentionally models one reusable shared
     # prefix rather than a full radix tree. Hits share one persistent KV entry.
     prefix_cache_enabled: bool = False
     shared_prefix_tokens: int = 256

py/inferscale/optimizer.py

@@ -53,6 +53,8 @@ def capacity_search(
     headroom: float = 0.20,
 ) -> dict:
     base = SimulationConfig.from_dict(config)
+    if base.arrival_process == "trace":
+        raise ValueError("Capacity search requires a rate-driven workload; trace replay has fixed arrival times.")
     low = max(0.01, min_rate)
     high = max(low * 1.01, max_rate)
     trace: list[dict] = []

py/inferscale/research.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import math
+import random
+from copy import deepcopy
+from statistics import mean, median
+
+from .models import SimulationConfig
+from .simulator import run_simulation
+
+
+STUDIES = {
+    "prefix_cache": {
+        "label": "Prefix reuse: off vs on",
+        "baseline": "Prefix reuse off",
+        "treatment": "Prefix reuse on",
+    },
+    "pd_vs_colocated": {
+        "label": "Topology: colocated vs P/D",
+        "baseline": "Colocated",
+        "treatment": "P/D disaggregated",
+    },
+    "chunked_vs_fcfs": {
+        "label": "Scheduling: FCFS vs chunked prefill",
+        "baseline": "Continuous FCFS",
+        "treatment": "Chunked prefill + SLO",
+    },
+    "slo_vs_fcfs": {
+        "label": "Scheduling: FCFS vs least-slack",
+        "baseline": "Continuous FCFS",
+        "treatment": "Continuous SLO",
+    },
+}
+
+METRICS = {
+    "goodput_rps": {"direction": 1, "label": "Goodput", "unit": "req/s"},
+    "p95_ttft_ms": {"direction": -1, "label": "p95 TTFT", "unit": "ms"},
+    "p95_e2e_ms": {"direction": -1, "label": "p95 E2E", "unit": "ms"},
+    "slo_attainment": {"direction": 1, "label": "SLO attainment", "unit": "fraction"},
+}
+
+
+def _study_configs(base: SimulationConfig, study: str) -> tuple[SimulationConfig, SimulationConfig]:
+    if study not in STUDIES:
+        raise ValueError(f"Unknown paired study: {study}")
+    a = deepcopy(base)
+    b = deepcopy(base)
+
+    if study == "prefix_cache":
+        a.prefix_cache_enabled = False
+        b.prefix_cache_enabled = True
+    elif study == "pd_vs_colocated":
+        a.topology = "colocated"
+        b.topology = "disaggregated_pd"
+        if b.scheduler == "static_fcfs":
+            b.scheduler = "continuous_fcfs"
+    elif study == "chunked_vs_fcfs":
+        a.topology = "colocated"
+        b.topology = "colocated"
+        a.scheduler = "continuous_fcfs"
+        b.scheduler = "chunked_slo"
+    elif study == "slo_vs_fcfs":
+        a.topology = "colocated"
+        b.topology = "colocated"
+        a.scheduler = "continuous_fcfs"
+        b.scheduler = "continuous_slo"
+    return a, b
+
+
+def _extract(result: dict) -> dict[str, float]:
+    return {
+        "goodput_rps": float(result["summary"]["goodput_rps"]),
+        "p95_ttft_ms": float(result["latency"]["ttft_ms"]["p95"]),
+        "p95_e2e_ms": float(result["latency"]["e2e_ms"]["p95"]),
+        "slo_attainment": float(result["summary"]["slo_attainment"]),
+    }
+
+
+def _percentile(values: list[float], q: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    if len(ordered) == 1:
+        return ordered[0]
+    pos = min(max(q, 0.0), 1.0) * (len(ordered) - 1)
+    lo = int(math.floor(pos))
+    hi = int(math.ceil(pos))
+    if lo == hi:
+        return ordered[lo]
+    frac = pos - lo
+    return ordered[lo] * (1.0 - frac) + ordered[hi] * frac
+
+
+def _bootstrap_ci(deltas: list[float], samples: int, seed: int) -> tuple[float, float]:
+    if not deltas:
+        return (0.0, 0.0)
+    rng = random.Random(seed)
+    n = len(deltas)
+    boot = []
+    for _ in range(max(samples, 50)):
+        boot.append(mean(deltas[rng.randrange(n)] for _ in range(n)))
+    return _percentile(boot, 0.025), _percentile(boot, 0.975)
+
+
+def paired_study(config: dict, study: str = "prefix_cache", repetitions: int = 12, bootstrap_samples: int = 500) -> dict:
+    """Run a paired Monte Carlo A/B study using common random numbers.
+
+    Baseline and treatment share the same seed on every repetition. This reduces
+    workload-noise variance and makes the delta attributable to the controlled
+    system change rather than to different synthetic request traces.
+    """
+    base = SimulationConfig.from_dict(config)
+    repetitions = max(2, min(int(repetitions), 64))
+    a_cfg, b_cfg = _study_configs(base, study)
+    pairs: list[dict] = []
+
+    for rep in range(repetitions):
+        seed = base.seed + rep * 1009
+        a_cfg.seed = seed
+        b_cfg.seed = seed
+        a_result = run_simulation(a_cfg.to_dict())
+        b_result = run_simulation(b_cfg.to_dict())
+        a_metrics = _extract(a_result)
+        b_metrics = _extract(b_result)
+        pairs.append({"rep": rep + 1, "seed": seed, "baseline": a_metrics, "treatment": b_metrics})
+
+    metrics = []
+    for key, meta in METRICS.items():
+        baseline = [row["baseline"][key] for row in pairs]
+        treatment = [row["treatment"][key] for row in pairs]
+        deltas = [b - a for a, b in zip(baseline, treatment, strict=True)]
+        relative = [((b - a) / abs(a) * 100.0) if abs(a) > 1e-12 else 0.0 for a, b in zip(baseline, treatment, strict=True)]
+        metric_seed = sum((idx + 1) * ord(ch) for idx, ch in enumerate(key))
+        ci_low, ci_high = _bootstrap_ci(deltas, bootstrap_samples, base.seed ^ metric_seed)
+        direction = int(meta["direction"])
+        wins = sum(1 for delta in deltas if delta * direction > 0)
+        ties = sum(1 for delta in deltas if abs(delta) <= 1e-12)
+        metrics.append(
+            {
+                "metric": key,
+                "label": meta["label"],
+                "unit": meta["unit"],
+                "baseline_mean": mean(baseline),
+                "treatment_mean": mean(treatment),
+                "delta_mean": mean(deltas),
+                "delta_median": median(deltas),
+                "delta_ci95_low": ci_low,
+                "delta_ci95_high": ci_high,
+                "relative_change_pct": mean(relative),
+                "treatment_win_rate": wins / repetitions,
+                "tie_rate": ties / repetitions,
+                "preferred_direction": "higher" if direction > 0 else "lower",
+                "ci_excludes_zero": ci_low > 0 or ci_high < 0,
+            }
+        )
+
+    return {
+        "study": study,
+        "label": STUDIES[study]["label"],
+        "baseline_label": STUDIES[study]["baseline"],
+        "treatment_label": STUDIES[study]["treatment"],
+        "repetitions": repetitions,
+        "bootstrap_samples": max(bootstrap_samples, 50),
+        "protocol": "paired-common-random-numbers",
+        "metrics": metrics,
+        "pairs": pairs,
+    }
+
+
+def robustness_study(
+    config: dict,
+    study: str = "pd_vs_colocated",
+    samples: int = 32,
+    uncertainty: float = 0.20,
+) -> dict:
+    """Stress-test an A/B conclusion under analytical latency uncertainty.
+
+    Each sample draws shared prefill/decode/transfer scale factors and applies
+    them to both alternatives. The goal is not a probability statement about
+    real hardware; it is a sensitivity analysis showing whether a conclusion is
+    fragile to plausible multiplicative error in the reference latency model.
+    """
+    base = SimulationConfig.from_dict(config)
+    samples = max(4, min(int(samples), 96))
+    uncertainty = min(max(float(uncertainty), 0.0), 0.75)
+    rng = random.Random(base.seed ^ 0x51514A)
+    rows = []
+
+    for idx in range(samples):
+        prefill_scale = rng.uniform(1.0 - uncertainty, 1.0 + uncertainty)
+        decode_scale = rng.uniform(1.0 - uncertainty, 1.0 + uncertainty)
+        transfer_scale = rng.uniform(1.0 - uncertainty, 1.0 + uncertainty)
+        a_cfg, b_cfg = _study_configs(base, study)
+        seed = base.seed + idx * 1009
+        for cfg in (a_cfg, b_cfg):
+            cfg.seed = seed
+            cfg.prefill_time_scale = prefill_scale
+            cfg.decode_time_scale = decode_scale
+            cfg.transfer_time_scale = transfer_scale
+        a = run_simulation(a_cfg.to_dict())
+        b = run_simulation(b_cfg.to_dict())
+        am = _extract(a)
+        bm = _extract(b)
+        rows.append(
+            {
+                "sample": idx + 1,
+                "prefill_scale": prefill_scale,
+                "decode_scale": decode_scale,
+                "transfer_scale": transfer_scale,
+                "baseline": am,
+                "treatment": bm,
+                "baseline_slo_pass": am["slo_attainment"] >= base.slo_attainment_target,
+                "treatment_slo_pass": bm["slo_attainment"] >= base.slo_attainment_target,
+            }
+        )
+
+    def win_fraction(metric: str, direction: int) -> float:
+        return mean(
+            1.0 if (row["treatment"][metric] - row["baseline"][metric]) * direction > 0 else 0.0
+            for row in rows
+        )
+
+    goodput_deltas = [row["treatment"]["goodput_rps"] - row["baseline"]["goodput_rps"] for row in rows]
+    ttft_deltas = [row["treatment"]["p95_ttft_ms"] - row["baseline"]["p95_ttft_ms"] for row in rows]
+    e2e_deltas = [row["treatment"]["p95_e2e_ms"] - row["baseline"]["p95_e2e_ms"] for row in rows]
+
+    return {
+        "study": study,
+        "label": STUDIES[study]["label"],
+        "baseline_label": STUDIES[study]["baseline"],
+        "treatment_label": STUDIES[study]["treatment"],
+        "samples": samples,
+        "uncertainty": uncertainty,
+        "method": "shared-multiplicative-latency-perturbation",
+        "summary": {
+            "treatment_goodput_win_fraction": win_fraction("goodput_rps", 1),
+            "treatment_ttft_win_fraction": win_fraction("p95_ttft_ms", -1),
+            "treatment_e2e_win_fraction": win_fraction("p95_e2e_ms", -1),
+            "baseline_slo_pass_fraction": mean(1.0 if row["baseline_slo_pass"] else 0.0 for row in rows),
+            "treatment_slo_pass_fraction": mean(1.0 if row["treatment_slo_pass"] else 0.0 for row in rows),
+            "median_goodput_delta": median(goodput_deltas),
+            "median_ttft_delta_ms": median(ttft_deltas),
+            "median_e2e_delta_ms": median(e2e_deltas),
+        },
+        "rows": rows,
+    }

py/inferscale/simulator.py

@@ -27,7 +27,9 @@ class Simulator:
         self.cfg = cfg
         self.model = get_model(cfg.model)
         self.accelerator = get_accelerator(cfg.accelerator)
-        self.latency = AnalyticalLatencyModel(self.model, self.accelerator, cfg.quantization)
+        self.latency = AnalyticalLatencyModel(
+            self.model, self.accelerator, cfg.quantization, cfg.prefill_time_scale, cfg.decode_time_scale
+        )
         self.kv = KVCacheModel(self.latency, cfg)
         self.requests = generate_workload(cfg)
         self.pending_idx = 0
@@ -271,7 +273,8 @@ class Simulator:
             self._run_continuous()
         self._record_timeline(force=True)
 
-        makespan = max(self.now, self.cfg.duration_s if self.requests else 0.0)
+        workload_horizon = 0.0 if self.cfg.arrival_process == "trace" else (self.cfg.duration_s if self.requests else 0.0)
+        makespan = max(self.now, workload_horizon)
         summary, latency = summarize(self.completed, self.cfg, makespan, self.busy_time)
         summary["requests_generated"] = len(self.requests)
         summary["requests_unfinished"] = len(self.requests) - len(self.completed)
@@ -308,8 +311,7 @@ class Simulator:
 
         provenance = {
             "simulator": "InferScale-Sim",
-            "version": "0.3.0",
-            "latency_profile_type": "analytical-reference",
+                        "latency_profile_type": "analytical-reference",
             "profile_warning": "Reference profiles are analytical proxies, not measured hardware benchmarks.",
             "model_profile_source": self.model.source,
             "accelerator_profile_source": self.accelerator.source,

py/inferscale/validation.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import math
+from statistics import mean, median
+from typing import Any
+
+from .simulator import run_simulation
+
+
+SUPPORTED_METRICS = {
+    "goodput_rps": ("summary", "goodput_rps"),
+    "request_throughput_rps": ("summary", "request_throughput_rps"),
+    "slo_attainment": ("summary", "slo_attainment"),
+    "p95_ttft_ms": ("latency", "ttft_ms", "p95"),
+    "p95_e2e_ms": ("latency", "e2e_ms", "p95"),
+}
+
+
+def _predicted(result: dict[str, Any], metric: str) -> float:
+    path = SUPPORTED_METRICS[metric]
+    value: Any = result
+    for key in path:
+        value = value[key]
+    return float(value)
+
+
+def validate_cases(cases: list[dict[str, Any]]) -> dict[str, Any]:
+    """Compare simulator predictions with externally measured serving cases.
+
+    Each case contains a normal SimulationConfig dictionary and a `measured`
+    mapping. No measured data ships as benchmark truth with InferScale; this
+    function is the explicit integration point for future empirical validation.
+    """
+    rows: list[dict[str, Any]] = []
+    absolute_percentage_errors: list[float] = []
+
+    for index, case in enumerate(cases):
+        if "config" not in case or "measured" not in case:
+            raise ValueError(f"Validation case {index} requires config and measured fields")
+        result = run_simulation(case["config"])
+        name = str(case.get("name", f"case-{index + 1}"))
+        for metric, measured_raw in case["measured"].items():
+            if metric not in SUPPORTED_METRICS:
+                raise ValueError(f"Unsupported validation metric: {metric}")
+            measured = float(measured_raw)
+            predicted = _predicted(result, metric)
+            error = predicted - measured
+            ape = abs(error) / abs(measured) * 100.0 if abs(measured) > 1e-12 else math.nan
+            if math.isfinite(ape):
+                absolute_percentage_errors.append(ape)
+            rows.append(
+                {
+                    "case": name,
+                    "metric": metric,
+                    "measured": measured,
+                    "predicted": predicted,
+                    "error": error,
+                    "absolute_error": abs(error),
+                    "absolute_percentage_error": ape,
+                }
+            )
+
+    return {
+        "case_count": len(cases),
+        "observation_count": len(rows),
+        "mape_pct": mean(absolute_percentage_errors) if absolute_percentage_errors else 0.0,
+        "median_ape_pct": median(absolute_percentage_errors) if absolute_percentage_errors else 0.0,
+        "max_ape_pct": max(absolute_percentage_errors, default=0.0),
+        "rows": rows,
+        "provenance": "external-measurements-vs-analytical-reference",
+    }

py/inferscale/workloads.py

@@ -37,6 +37,9 @@ def _arrival_times(cfg: SimulationConfig, rng: random.Random) -> list[float]:
                 arrivals.append(t)
         return arrivals
 
+    if cfg.arrival_process == "trace":
+        return []
+
     if cfg.arrival_process != "poisson":
         raise ValueError(f"Unknown arrival process: {cfg.arrival_process}")
 
@@ -47,17 +50,61 @@ def _arrival_times(cfg: SimulationConfig, rng: random.Random) -> list[float]:
     return arrivals
 
 
+def _cache_tokens(cfg: SimulationConfig, prompt: int, cache_rng: random.Random) -> int:
+    if not cfg.prefix_cache_enabled or cfg.shared_prefix_tokens <= 0 or cfg.prefix_reuse_fraction <= 0:
+        return 0
+    if cache_rng.random() >= min(max(cfg.prefix_reuse_fraction, 0.0), 1.0):
+        return 0
+    return min(cfg.shared_prefix_tokens, max(prompt - 1, 0))
+
+
+def _from_trace(cfg: SimulationConfig, cache_rng: random.Random) -> list[Request]:
+    rows: list[tuple[float, int, int]] = []
+    for idx, raw in enumerate(cfg.trace_requests):
+        try:
+            arrival = float(raw["arrival_time"])
+            prompt = int(raw["prompt_tokens"])
+            output = int(raw["output_tokens"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValueError(
+                f"Trace row {idx} must contain numeric arrival_time, prompt_tokens, and output_tokens"
+            ) from exc
+        if not math.isfinite(arrival) or arrival < 0:
+            raise ValueError(f"Trace row {idx} has invalid arrival_time")
+        if prompt < 1 or output < 1:
+            raise ValueError(f"Trace row {idx} token counts must be positive")
+        rows.append((arrival, prompt, output))
+
+    rows.sort(key=lambda row: row[0])
+    requests: list[Request] = []
+    for request_id, (arrival, prompt, output) in enumerate(rows):
+        cached = _cache_tokens(cfg, prompt, cache_rng)
+        requests.append(
+            Request(
+                request_id=request_id,
+                arrival_time=arrival,
+                prompt_tokens=prompt,
+                output_tokens=output,
+                deadline_time=arrival + cfg.slo_e2e_ms / 1000.0,
+                remaining_prefill=max(0, prompt - cached),
+                cached_prefix_tokens=cached,
+            )
+        )
+    return requests
+
+
 def generate_workload(cfg: SimulationConfig) -> list[Request]:
     rng = random.Random(cfg.seed)
     cache_rng = random.Random(cfg.seed ^ 0x5A17CACE)
+
+    if cfg.arrival_process == "trace":
+        return _from_trace(cfg, cache_rng)
+
     requests: list[Request] = []
     for idx, arrival in enumerate(_arrival_times(cfg, rng)):
         prompt = _sample_lognormal(cfg.prompt_tokens_mean, cfg.prompt_tokens_cv, rng)
         output = _sample_lognormal(cfg.output_tokens_mean, cfg.output_tokens_cv, rng)
-        cached = 0
-        if cfg.prefix_cache_enabled and cfg.shared_prefix_tokens > 0 and cfg.prefix_reuse_fraction > 0:
-            if cache_rng.random() < min(max(cfg.prefix_reuse_fraction, 0.0), 1.0):
-                cached = min(cfg.shared_prefix_tokens, max(prompt - 1, 0))
+        cached = _cache_tokens(cfg, prompt, cache_rng)
         requests.append(
             Request(
                 request_id=idx,

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "inferscale-sim"
-version = "0.3.0"
+version = "0.4.0"
 description = "Interactive LLM serving simulator and SLO capacity planner"
 readme = "README.md"
 requires-python = ">=3.10"

scripts/release_check.py

@@ -11,9 +11,12 @@ SRC = ROOT / "src"
 sys.path.insert(0, str(SRC))
 
 inferscale = importlib.import_module("inferscale")
-__version__ = inferscale.__version__
+internal_version = inferscale.__version__
 design_space_search = inferscale.design_space_search
+paired_study = inferscale.paired_study
+robustness_study = inferscale.robustness_study
 run_simulation = inferscale.run_simulation
+validate_cases = inferscale.validate_cases
 
 errors: list[str] = []
 
@@ -28,8 +31,17 @@ else:
 
 if "sdk: static" not in README:
     errors.append("README metadata must use sdk: static")
-if __version__ != "0.3.0":
-    errors.append(f"package version is {__version__}; expected 0.3.0")
+if internal_version != "0.4.0":
+    errors.append(f"internal package version is {internal_version}; expected 0.4.0")
+
+# Public-facing release/version branding is intentionally absent. Model names
+# such as Mistral-7B-v0.3 are allowed; project headings/badges are not.
+public_texts = [("README.md", README), ("index.html", (ROOT / "index.html").read_text())]
+for name, text in public_texts:
+    if re.search(r"InferScale(?:-Sim)?\s*/?\s*v\d", text, re.IGNORECASE):
+        errors.append(f"{name} contains public project version branding")
+if (ROOT / "CHANGELOG.md").exists():
+    errors.append("CHANGELOG.md should be omitted from the public portfolio release")
 
 src_files = sorted((ROOT / "src" / "inferscale").glob("*.py"))
 web_files = sorted((ROOT / "py" / "inferscale").glob("*.py"))
@@ -54,11 +66,21 @@ for ui_file in (ROOT / "index.html", ROOT / "app.js"):
 index = (ROOT / "index.html").read_text()
 app = (ROOT / "app.js").read_text()
 if "<footer" in index.lower():
-    errors.append("v0.3 UI should not include the old product-style footer")
+    errors.append("UI should not include a product-style footer")
 if "Download PNG" not in index or ".chart-download" not in app:
     errors.append("chart PNG export controls are missing")
 if "Worst repetition" not in index or "Target" not in index:
     errors.append("capacity evidence columns are missing")
+for expected in ["Trace replay", "Research Studies", "Run paired study", "Stress-test conclusion"]:
+    if expected not in index:
+        errors.append(f"UI is missing research/trace feature: {expected}")
+
+# Every $("id") lookup in app.js should resolve to a static DOM id.
+app_ids = set(re.findall(r'\$\("([A-Za-z0-9_-]+)"\)', app))
+html_ids = set(re.findall(r'id="([A-Za-z0-9_-]+)"', index))
+missing_ids = sorted(app_ids - html_ids)
+if missing_ids:
+    errors.append(f"app.js references missing DOM ids: {', '.join(missing_ids[:12])}")
 
 smoke_cfg = {
     "model": "Qwen2.5-3B",
@@ -77,11 +99,22 @@ try:
         errors.append("profile provenance guard is missing")
     if smoke["diagnostics"].get("provenance") != "heuristic-simulator-diagnosis":
         errors.append("diagnosis provenance missing")
-    if "prefix_cache_hit_rate" not in smoke["resource"]:
-        errors.append("prefix-cache telemetry missing")
 except Exception as exc:  # pragma: no cover
     errors.append(f"colocated smoke test raised: {exc}")
 
+try:
+    trace = run_simulation(smoke_cfg | {
+        "arrival_process": "trace",
+        "trace_requests": [
+            {"arrival_time": 0.0, "prompt_tokens": 64, "output_tokens": 4},
+            {"arrival_time": 0.2, "prompt_tokens": 96, "output_tokens": 6},
+        ],
+    })
+    if trace["summary"]["requests_generated"] != 2:
+        errors.append("trace replay smoke test did not preserve request count")
+except Exception as exc:  # pragma: no cover
+    errors.append(f"trace replay smoke test raised: {exc}")
+
 try:
     pd = run_simulation(smoke_cfg | {
         "topology": "disaggregated_pd",
@@ -90,8 +123,6 @@ try:
         "decode_accelerator": "L4",
         "interconnect_gbps": 50,
     })
-    if pd["provenance"].get("topology") != "disaggregated_pd":
-        errors.append("P/D provenance missing")
     if pd["resource"].get("p95_transfer_ms", 0) <= 0:
         errors.append("P/D transfer telemetry missing")
 except Exception as exc:  # pragma: no cover
@@ -109,6 +140,41 @@ try:
 except Exception as exc:  # pragma: no cover
     errors.append(f"design-space smoke test raised: {exc}")
 
+try:
+    paired = paired_study(
+        smoke_cfg | {"shared_prefix_tokens": 64, "prefix_reuse_fraction": 0.75},
+        study="prefix_cache",
+        repetitions=4,
+        bootstrap_samples=100,
+    )
+    if paired["protocol"] != "paired-common-random-numbers" or len(paired["metrics"]) != 4:
+        errors.append("paired research study smoke test is incomplete")
+except Exception as exc:  # pragma: no cover
+    errors.append(f"paired study smoke test raised: {exc}")
+
+try:
+    robust = robustness_study(
+        smoke_cfg | {"prefill_accelerator": "L4", "decode_accelerator": "L4"},
+        study="pd_vs_colocated",
+        samples=4,
+        uncertainty=0.10,
+    )
+    if robust["method"] != "shared-multiplicative-latency-perturbation" or len(robust["rows"]) != 4:
+        errors.append("robustness study smoke test is incomplete")
+except Exception as exc:  # pragma: no cover
+    errors.append(f"robustness study smoke test raised: {exc}")
+
+try:
+    validation = validate_cases([{
+        "name": "release-fixture",
+        "config": smoke_cfg,
+        "measured": {"p95_ttft_ms": 100.0, "goodput_rps": 0.8},
+    }])
+    if validation["observation_count"] != 2:
+        errors.append("external-measurement validation hook failed")
+except Exception as exc:  # pragma: no cover
+    errors.append(f"validation hook smoke test raised: {exc}")
+
 if errors:
     print("InferScale release check: FAIL")
     for error in errors:
@@ -116,13 +182,13 @@ if errors:
     raise SystemExit(1)
 
 print("InferScale release check: PASS")
-print(f"Version: {__version__}")
 print(f"HF short_description: {len(short)}/60 characters")
 print(f"Python modules mirrored: {len(src_files)}")
 print(f"Colocated smoke requests: {smoke['summary']['requests_completed']}")
+print(f"Trace replay requests: {trace['summary']['requests_generated']}")
 print(f"P/D transfer p95: {pd['resource']['p95_transfer_ms']:.3f} ms")
-print(
-    f"Design candidates: {design['candidate_count']} "
-    f"({design['pareto_count']} performance Pareto, {design['efficiency_pareto_count']} efficiency Pareto)"
-)
+print(f"Design candidates: {design['candidate_count']}")
+print(f"Paired-study metrics: {len(paired['metrics'])}")
+print(f"Robustness perturbations: {len(robust['rows'])}")
+print(f"Validation observations: {validation['observation_count']}")
 print(f"Profile provenance: {smoke['provenance']['latency_profile_type']}")

scripts/validate_measurements.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "src"))
+
+from inferscale.validation import validate_cases  # noqa: E402
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Validate InferScale predictions against external measured cases")
+    parser.add_argument("input", type=Path, help="JSON file containing a list of validation cases")
+    parser.add_argument("--output", type=Path, help="Optional JSON report path")
+    args = parser.parse_args()
+
+    payload = json.loads(args.input.read_text())
+    cases = payload if isinstance(payload, list) else payload.get("cases", [])
+    report = validate_cases(cases)
+    text = json.dumps(report, indent=2)
+    if args.output:
+        args.output.write_text(text + "\n")
+    print(text)
+
+
+if __name__ == "__main__":
+    main()

src/inferscale/__init__.py

@@ -1,7 +1,9 @@
 from .api import execute, metadata
 from .models import SimulationConfig
 from .optimizer import capacity_search, compare_schedulers, compare_topologies, design_space_search
+from .research import paired_study, robustness_study
 from .simulator import run_simulation
+from .validation import validate_cases
 
 __all__ = [
     "SimulationConfig",
@@ -11,7 +13,12 @@ __all__ = [
     "design_space_search",
     "execute",
     "metadata",
+    "paired_study",
+    "robustness_study",
     "run_simulation",
+    "validate_cases",
 ]
 
-__version__ = "0.3.0"
+# Internal package metadata only; the public project intentionally avoids
+# release/version branding in the interface and documentation.
+__version__ = "0.4.0"

src/inferscale/api.py

@@ -2,16 +2,17 @@ from __future__ import annotations
 
 from .optimizer import capacity_search, compare_schedulers, compare_topologies, design_space_search
 from .profiles import ACCELERATORS, MODELS
+from .research import STUDIES, paired_study, robustness_study
 from .simulator import SCHEDULERS, run_simulation
 
 
 def metadata() -> dict:
     return {
-        "version": "0.3.0",
         "models": list(MODELS.keys()),
         "accelerators": list(ACCELERATORS.keys()),
         "schedulers": sorted(SCHEDULERS),
         "topologies": ["colocated", "disaggregated_pd"],
+        "research_studies": STUDIES,
         "profile_type": "analytical-reference",
     }
 
@@ -38,6 +39,22 @@ def execute(action: str, payload: dict) -> dict:
     if action == "design_space":
         config = payload.get("config", payload)
         return design_space_search(config, bool(payload.get("include_disaggregated", True)))
+    if action == "paired_study":
+        config = payload.get("config", payload)
+        return paired_study(
+            config,
+            study=str(payload.get("study", "prefix_cache")),
+            repetitions=int(payload.get("repetitions", 12)),
+            bootstrap_samples=int(payload.get("bootstrap_samples", 500)),
+        )
+    if action == "robustness_study":
+        config = payload.get("config", payload)
+        return robustness_study(
+            config,
+            study=str(payload.get("study", "pd_vs_colocated")),
+            samples=int(payload.get("samples", 32)),
+            uncertainty=float(payload.get("uncertainty", 0.20)),
+        )
     if action == "metadata":
         return metadata()
     raise ValueError(f"Unknown action: {action}")

src/inferscale/disaggregated.py

@@ -36,7 +36,7 @@ class DecodeWorker:
 class DisaggregatedSimulator:
     """Two-stage prefill/decode discrete-event simulator.
 
-    v0.3 models role-specific worker pools plus a serialized analytical KV-transfer
+    the current model models role-specific worker pools plus a serialized analytical KV-transfer
     link. It is intentionally a systems abstraction, not a distributed-runtime
     emulator: transport, compute and memory timings remain reference-model
     predictions and carry explicit provenance in every result.
@@ -52,8 +52,12 @@ class DisaggregatedSimulator:
         self.model = get_model(cfg.model)
         self.prefill_accelerator = get_accelerator(cfg.prefill_accelerator)
         self.decode_accelerator = get_accelerator(cfg.decode_accelerator)
-        self.prefill_latency = AnalyticalLatencyModel(self.model, self.prefill_accelerator, cfg.quantization)
-        self.decode_latency = AnalyticalLatencyModel(self.model, self.decode_accelerator, cfg.quantization)
+        self.prefill_latency = AnalyticalLatencyModel(
+            self.model, self.prefill_accelerator, cfg.quantization, cfg.prefill_time_scale, cfg.decode_time_scale
+        )
+        self.decode_latency = AnalyticalLatencyModel(
+            self.model, self.decode_accelerator, cfg.quantization, cfg.prefill_time_scale, cfg.decode_time_scale
+        )
 
         self.prefill_workers = [
             PrefillWorker(i, self.prefill_latency, KVCacheModel(self.prefill_latency, cfg))
@@ -168,7 +172,10 @@ class DisaggregatedSimulator:
         bytes_to_transfer = req.uncached_prompt_tokens * self.prefill_latency.kv_bytes_per_token()
         gb = bytes_to_transfer / 1e9
         start = max(self.now, self.transfer_busy_until)
-        duration = self.cfg.transfer_base_ms / 1000.0 + bytes_to_transfer / (self.cfg.interconnect_gbps * 1e9)
+        duration = (
+            self.cfg.transfer_base_ms / 1000.0
+            + bytes_to_transfer / (self.cfg.interconnect_gbps * 1e9)
+        ) * max(self.cfg.transfer_time_scale, 1e-6)
         end = start + duration
         self.transfer_busy_until = end
         self.transfer_busy_time_s += duration
@@ -275,7 +282,8 @@ class DisaggregatedSimulator:
             self.warnings.append("Disaggregated pipeline stalled before all requests completed.")
 
         self._record_timeline(force=True)
-        makespan = max(self.now, self.cfg.duration_s if self.requests else 0.0)
+        workload_horizon = 0.0 if self.cfg.arrival_process == "trace" else (self.cfg.duration_s if self.requests else 0.0)
+        makespan = max(self.now, workload_horizon)
         prefill_util = sum(w.busy_time_s for w in self.prefill_workers) / max(makespan * len(self.prefill_workers), 1e-9)
         decode_util = sum(w.busy_time_s for w in self.decode_workers) / max(makespan * len(self.decode_workers), 1e-9)
         transfer_util = self.transfer_busy_time_s / max(makespan, 1e-9)
@@ -336,8 +344,7 @@ class DisaggregatedSimulator:
         diagnostics = diagnose_run(summary, latency, resource, self.cfg)
         provenance = {
             "simulator": "InferScale-Sim",
-            "version": "0.3.0",
-            "latency_profile_type": "analytical-reference",
+                        "latency_profile_type": "analytical-reference",
             "profile_warning": "Reference profiles are analytical proxies, not measured hardware benchmarks.",
             "model_profile_source": self.model.source,
             "prefill_accelerator_profile_source": self.prefill_accelerator.source,

src/inferscale/latency.py

@@ -15,7 +15,14 @@ class AnalyticalLatencyModel:
     profiles are tagged `analytical-reference` throughout the app.
     """
 
-    def __init__(self, model: ModelProfile, accelerator: AcceleratorProfile, quantization: str = "fp16"):
+    def __init__(
+        self,
+        model: ModelProfile,
+        accelerator: AcceleratorProfile,
+        quantization: str = "fp16",
+        prefill_scale: float = 1.0,
+        decode_scale: float = 1.0,
+    ):
         if quantization not in QUANTIZATION_BYTES:
             raise ValueError(f"Unsupported quantization: {quantization}")
         self.model = model
@@ -23,13 +30,15 @@ class AnalyticalLatencyModel:
         self.quantization = quantization
         self.weight_bytes_per_param = QUANTIZATION_BYTES[quantization]
         self.compute_overhead = QUANTIZATION_COMPUTE_MULTIPLIER[quantization]
+        self.prefill_scale = max(float(prefill_scale), 1e-6)
+        self.decode_scale = max(float(decode_scale), 1e-6)
 
     @property
     def model_weight_gb(self) -> float:
         return self.model.params_b * self.weight_bytes_per_param
 
     def kv_bytes_per_token(self) -> float:
-        # K + V, all layers, KV heads only. KV state is assumed fp16 in v0.3.
+        # K + V, all layers, KV heads only. KV state is assumed fp16 in the current model.
         return (
             2
             * self.model.layers
@@ -74,7 +83,7 @@ class AnalyticalLatencyModel:
         )
         # Kernel launch / scheduling proxy prevents implausibly tiny times.
         launch = 0.0018 + 0.00008 * batch
-        return max(compute, memory * 0.28) + launch
+        return (max(compute, memory * 0.28) + launch) * self.prefill_scale
 
     def decode_step_seconds(self, context_lengths: list[int]) -> float:
         if not context_lengths:
@@ -103,4 +112,4 @@ class AnalyticalLatencyModel:
         )
 
         launch = 0.0012 + 0.000035 * batch + 0.00000003 * avg_context
-        return max(compute, memory) + launch
+        return (max(compute, memory) + launch) * self.decode_scale

src/inferscale/models.py

@@ -58,7 +58,19 @@ class SimulationConfig:
     burst_period_s: float = 10.0
     timeline_points: int = 300
 
-    # Prefix-cache scenario. v0.3 intentionally models one reusable shared
+    # Optional exact workload replay. Each row contains arrival_time,
+    # prompt_tokens, and output_tokens. The trace path is browser-safe because
+    # rows are supplied directly by the UI rather than read from local files.
+    trace_requests: list[dict[str, Any]] = field(default_factory=list)
+
+    # Sensitivity-analysis hooks. Public reference profiles default to 1.0;
+    # research studies perturb these factors to test whether conclusions survive
+    # plausible analytical-model error rather than treating one proxy as truth.
+    prefill_time_scale: float = 1.0
+    decode_time_scale: float = 1.0
+    transfer_time_scale: float = 1.0
+
+    # Prefix-cache scenario. the current model intentionally models one reusable shared
     # prefix rather than a full radix tree. Hits share one persistent KV entry.
     prefix_cache_enabled: bool = False
     shared_prefix_tokens: int = 256

src/inferscale/optimizer.py

@@ -53,6 +53,8 @@ def capacity_search(
     headroom: float = 0.20,
 ) -> dict:
     base = SimulationConfig.from_dict(config)
+    if base.arrival_process == "trace":
+        raise ValueError("Capacity search requires a rate-driven workload; trace replay has fixed arrival times.")
     low = max(0.01, min_rate)
     high = max(low * 1.01, max_rate)
     trace: list[dict] = []

src/inferscale/research.py

@@ -0,0 +1,246 @@
+from __future__ import annotations
+
+import math
+import random
+from copy import deepcopy
+from statistics import mean, median
+
+from .models import SimulationConfig
+from .simulator import run_simulation
+
+
+STUDIES = {
+    "prefix_cache": {
+        "label": "Prefix reuse: off vs on",
+        "baseline": "Prefix reuse off",
+        "treatment": "Prefix reuse on",
+    },
+    "pd_vs_colocated": {
+        "label": "Topology: colocated vs P/D",
+        "baseline": "Colocated",
+        "treatment": "P/D disaggregated",
+    },
+    "chunked_vs_fcfs": {
+        "label": "Scheduling: FCFS vs chunked prefill",
+        "baseline": "Continuous FCFS",
+        "treatment": "Chunked prefill + SLO",
+    },
+    "slo_vs_fcfs": {
+        "label": "Scheduling: FCFS vs least-slack",
+        "baseline": "Continuous FCFS",
+        "treatment": "Continuous SLO",
+    },
+}
+
+METRICS = {
+    "goodput_rps": {"direction": 1, "label": "Goodput", "unit": "req/s"},
+    "p95_ttft_ms": {"direction": -1, "label": "p95 TTFT", "unit": "ms"},
+    "p95_e2e_ms": {"direction": -1, "label": "p95 E2E", "unit": "ms"},
+    "slo_attainment": {"direction": 1, "label": "SLO attainment", "unit": "fraction"},
+}
+
+
+def _study_configs(base: SimulationConfig, study: str) -> tuple[SimulationConfig, SimulationConfig]:
+    if study not in STUDIES:
+        raise ValueError(f"Unknown paired study: {study}")
+    a = deepcopy(base)
+    b = deepcopy(base)
+
+    if study == "prefix_cache":
+        a.prefix_cache_enabled = False
+        b.prefix_cache_enabled = True
+    elif study == "pd_vs_colocated":
+        a.topology = "colocated"
+        b.topology = "disaggregated_pd"
+        if b.scheduler == "static_fcfs":
+            b.scheduler = "continuous_fcfs"
+    elif study == "chunked_vs_fcfs":
+        a.topology = "colocated"
+        b.topology = "colocated"
+        a.scheduler = "continuous_fcfs"
+        b.scheduler = "chunked_slo"
+    elif study == "slo_vs_fcfs":
+        a.topology = "colocated"
+        b.topology = "colocated"
+        a.scheduler = "continuous_fcfs"
+        b.scheduler = "continuous_slo"
+    return a, b
+
+
+def _extract(result: dict) -> dict[str, float]:
+    return {
+        "goodput_rps": float(result["summary"]["goodput_rps"]),
+        "p95_ttft_ms": float(result["latency"]["ttft_ms"]["p95"]),
+        "p95_e2e_ms": float(result["latency"]["e2e_ms"]["p95"]),
+        "slo_attainment": float(result["summary"]["slo_attainment"]),
+    }
+
+
+def _percentile(values: list[float], q: float) -> float:
+    if not values:
+        return 0.0
+    ordered = sorted(values)
+    if len(ordered) == 1:
+        return ordered[0]
+    pos = min(max(q, 0.0), 1.0) * (len(ordered) - 1)
+    lo = int(math.floor(pos))
+    hi = int(math.ceil(pos))
+    if lo == hi:
+        return ordered[lo]
+    frac = pos - lo
+    return ordered[lo] * (1.0 - frac) + ordered[hi] * frac
+
+
+def _bootstrap_ci(deltas: list[float], samples: int, seed: int) -> tuple[float, float]:
+    if not deltas:
+        return (0.0, 0.0)
+    rng = random.Random(seed)
+    n = len(deltas)
+    boot = []
+    for _ in range(max(samples, 50)):
+        boot.append(mean(deltas[rng.randrange(n)] for _ in range(n)))
+    return _percentile(boot, 0.025), _percentile(boot, 0.975)
+
+
+def paired_study(config: dict, study: str = "prefix_cache", repetitions: int = 12, bootstrap_samples: int = 500) -> dict:
+    """Run a paired Monte Carlo A/B study using common random numbers.
+
+    Baseline and treatment share the same seed on every repetition. This reduces
+    workload-noise variance and makes the delta attributable to the controlled
+    system change rather than to different synthetic request traces.
+    """
+    base = SimulationConfig.from_dict(config)
+    repetitions = max(2, min(int(repetitions), 64))
+    a_cfg, b_cfg = _study_configs(base, study)
+    pairs: list[dict] = []
+
+    for rep in range(repetitions):
+        seed = base.seed + rep * 1009
+        a_cfg.seed = seed
+        b_cfg.seed = seed
+        a_result = run_simulation(a_cfg.to_dict())
+        b_result = run_simulation(b_cfg.to_dict())
+        a_metrics = _extract(a_result)
+        b_metrics = _extract(b_result)
+        pairs.append({"rep": rep + 1, "seed": seed, "baseline": a_metrics, "treatment": b_metrics})
+
+    metrics = []
+    for key, meta in METRICS.items():
+        baseline = [row["baseline"][key] for row in pairs]
+        treatment = [row["treatment"][key] for row in pairs]
+        deltas = [b - a for a, b in zip(baseline, treatment, strict=True)]
+        relative = [((b - a) / abs(a) * 100.0) if abs(a) > 1e-12 else 0.0 for a, b in zip(baseline, treatment, strict=True)]
+        metric_seed = sum((idx + 1) * ord(ch) for idx, ch in enumerate(key))
+        ci_low, ci_high = _bootstrap_ci(deltas, bootstrap_samples, base.seed ^ metric_seed)
+        direction = int(meta["direction"])
+        wins = sum(1 for delta in deltas if delta * direction > 0)
+        ties = sum(1 for delta in deltas if abs(delta) <= 1e-12)
+        metrics.append(
+            {
+                "metric": key,
+                "label": meta["label"],
+                "unit": meta["unit"],
+                "baseline_mean": mean(baseline),
+                "treatment_mean": mean(treatment),
+                "delta_mean": mean(deltas),
+                "delta_median": median(deltas),
+                "delta_ci95_low": ci_low,
+                "delta_ci95_high": ci_high,
+                "relative_change_pct": mean(relative),
+                "treatment_win_rate": wins / repetitions,
+                "tie_rate": ties / repetitions,
+                "preferred_direction": "higher" if direction > 0 else "lower",
+                "ci_excludes_zero": ci_low > 0 or ci_high < 0,
+            }
+        )
+
+    return {
+        "study": study,
+        "label": STUDIES[study]["label"],
+        "baseline_label": STUDIES[study]["baseline"],
+        "treatment_label": STUDIES[study]["treatment"],
+        "repetitions": repetitions,
+        "bootstrap_samples": max(bootstrap_samples, 50),
+        "protocol": "paired-common-random-numbers",
+        "metrics": metrics,
+        "pairs": pairs,
+    }
+
+
+def robustness_study(
+    config: dict,
+    study: str = "pd_vs_colocated",
+    samples: int = 32,
+    uncertainty: float = 0.20,
+) -> dict:
+    """Stress-test an A/B conclusion under analytical latency uncertainty.
+
+    Each sample draws shared prefill/decode/transfer scale factors and applies
+    them to both alternatives. The goal is not a probability statement about
+    real hardware; it is a sensitivity analysis showing whether a conclusion is
+    fragile to plausible multiplicative error in the reference latency model.
+    """
+    base = SimulationConfig.from_dict(config)
+    samples = max(4, min(int(samples), 96))
+    uncertainty = min(max(float(uncertainty), 0.0), 0.75)
+    rng = random.Random(base.seed ^ 0x51514A)
+    rows = []
+
+    for idx in range(samples):
+        prefill_scale = rng.uniform(1.0 - uncertainty, 1.0 + uncertainty)
+        decode_scale = rng.uniform(1.0 - uncertainty, 1.0 + uncertainty)
+        transfer_scale = rng.uniform(1.0 - uncertainty, 1.0 + uncertainty)
+        a_cfg, b_cfg = _study_configs(base, study)
+        seed = base.seed + idx * 1009
+        for cfg in (a_cfg, b_cfg):
+            cfg.seed = seed
+            cfg.prefill_time_scale = prefill_scale
+            cfg.decode_time_scale = decode_scale
+            cfg.transfer_time_scale = transfer_scale
+        a = run_simulation(a_cfg.to_dict())
+        b = run_simulation(b_cfg.to_dict())
+        am = _extract(a)
+        bm = _extract(b)
+        rows.append(
+            {
+                "sample": idx + 1,
+                "prefill_scale": prefill_scale,
+                "decode_scale": decode_scale,
+                "transfer_scale": transfer_scale,
+                "baseline": am,
+                "treatment": bm,
+                "baseline_slo_pass": am["slo_attainment"] >= base.slo_attainment_target,
+                "treatment_slo_pass": bm["slo_attainment"] >= base.slo_attainment_target,
+            }
+        )
+
+    def win_fraction(metric: str, direction: int) -> float:
+        return mean(
+            1.0 if (row["treatment"][metric] - row["baseline"][metric]) * direction > 0 else 0.0
+            for row in rows
+        )
+
+    goodput_deltas = [row["treatment"]["goodput_rps"] - row["baseline"]["goodput_rps"] for row in rows]
+    ttft_deltas = [row["treatment"]["p95_ttft_ms"] - row["baseline"]["p95_ttft_ms"] for row in rows]
+    e2e_deltas = [row["treatment"]["p95_e2e_ms"] - row["baseline"]["p95_e2e_ms"] for row in rows]
+
+    return {
+        "study": study,
+        "label": STUDIES[study]["label"],
+        "baseline_label": STUDIES[study]["baseline"],
+        "treatment_label": STUDIES[study]["treatment"],
+        "samples": samples,
+        "uncertainty": uncertainty,
+        "method": "shared-multiplicative-latency-perturbation",
+        "summary": {
+            "treatment_goodput_win_fraction": win_fraction("goodput_rps", 1),
+            "treatment_ttft_win_fraction": win_fraction("p95_ttft_ms", -1),
+            "treatment_e2e_win_fraction": win_fraction("p95_e2e_ms", -1),
+            "baseline_slo_pass_fraction": mean(1.0 if row["baseline_slo_pass"] else 0.0 for row in rows),
+            "treatment_slo_pass_fraction": mean(1.0 if row["treatment_slo_pass"] else 0.0 for row in rows),
+            "median_goodput_delta": median(goodput_deltas),
+            "median_ttft_delta_ms": median(ttft_deltas),
+            "median_e2e_delta_ms": median(e2e_deltas),
+        },
+        "rows": rows,
+    }

src/inferscale/simulator.py

@@ -27,7 +27,9 @@ class Simulator:
         self.cfg = cfg
         self.model = get_model(cfg.model)
         self.accelerator = get_accelerator(cfg.accelerator)
-        self.latency = AnalyticalLatencyModel(self.model, self.accelerator, cfg.quantization)
+        self.latency = AnalyticalLatencyModel(
+            self.model, self.accelerator, cfg.quantization, cfg.prefill_time_scale, cfg.decode_time_scale
+        )
         self.kv = KVCacheModel(self.latency, cfg)
         self.requests = generate_workload(cfg)
         self.pending_idx = 0
@@ -271,7 +273,8 @@ class Simulator:
             self._run_continuous()
         self._record_timeline(force=True)
 
-        makespan = max(self.now, self.cfg.duration_s if self.requests else 0.0)
+        workload_horizon = 0.0 if self.cfg.arrival_process == "trace" else (self.cfg.duration_s if self.requests else 0.0)
+        makespan = max(self.now, workload_horizon)
         summary, latency = summarize(self.completed, self.cfg, makespan, self.busy_time)
         summary["requests_generated"] = len(self.requests)
         summary["requests_unfinished"] = len(self.requests) - len(self.completed)
@@ -308,8 +311,7 @@ class Simulator:
 
         provenance = {
             "simulator": "InferScale-Sim",
-            "version": "0.3.0",
-            "latency_profile_type": "analytical-reference",
+                        "latency_profile_type": "analytical-reference",
             "profile_warning": "Reference profiles are analytical proxies, not measured hardware benchmarks.",
             "model_profile_source": self.model.source,
             "accelerator_profile_source": self.accelerator.source,

src/inferscale/validation.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import math
+from statistics import mean, median
+from typing import Any
+
+from .simulator import run_simulation
+
+
+SUPPORTED_METRICS = {
+    "goodput_rps": ("summary", "goodput_rps"),
+    "request_throughput_rps": ("summary", "request_throughput_rps"),
+    "slo_attainment": ("summary", "slo_attainment"),
+    "p95_ttft_ms": ("latency", "ttft_ms", "p95"),
+    "p95_e2e_ms": ("latency", "e2e_ms", "p95"),
+}
+
+
+def _predicted(result: dict[str, Any], metric: str) -> float:
+    path = SUPPORTED_METRICS[metric]
+    value: Any = result
+    for key in path:
+        value = value[key]
+    return float(value)
+
+
+def validate_cases(cases: list[dict[str, Any]]) -> dict[str, Any]:
+    """Compare simulator predictions with externally measured serving cases.
+
+    Each case contains a normal SimulationConfig dictionary and a `measured`
+    mapping. No measured data ships as benchmark truth with InferScale; this
+    function is the explicit integration point for future empirical validation.
+    """
+    rows: list[dict[str, Any]] = []
+    absolute_percentage_errors: list[float] = []
+
+    for index, case in enumerate(cases):
+        if "config" not in case or "measured" not in case:
+            raise ValueError(f"Validation case {index} requires config and measured fields")
+        result = run_simulation(case["config"])
+        name = str(case.get("name", f"case-{index + 1}"))
+        for metric, measured_raw in case["measured"].items():
+            if metric not in SUPPORTED_METRICS:
+                raise ValueError(f"Unsupported validation metric: {metric}")
+            measured = float(measured_raw)
+            predicted = _predicted(result, metric)
+            error = predicted - measured
+            ape = abs(error) / abs(measured) * 100.0 if abs(measured) > 1e-12 else math.nan
+            if math.isfinite(ape):
+                absolute_percentage_errors.append(ape)
+            rows.append(
+                {
+                    "case": name,
+                    "metric": metric,
+                    "measured": measured,
+                    "predicted": predicted,
+                    "error": error,
+                    "absolute_error": abs(error),
+                    "absolute_percentage_error": ape,
+                }
+            )
+
+    return {
+        "case_count": len(cases),
+        "observation_count": len(rows),
+        "mape_pct": mean(absolute_percentage_errors) if absolute_percentage_errors else 0.0,
+        "median_ape_pct": median(absolute_percentage_errors) if absolute_percentage_errors else 0.0,
+        "max_ape_pct": max(absolute_percentage_errors, default=0.0),
+        "rows": rows,
+        "provenance": "external-measurements-vs-analytical-reference",
+    }

src/inferscale/workloads.py

@@ -37,6 +37,9 @@ def _arrival_times(cfg: SimulationConfig, rng: random.Random) -> list[float]:
                 arrivals.append(t)
         return arrivals
 
+    if cfg.arrival_process == "trace":
+        return []
+
     if cfg.arrival_process != "poisson":
         raise ValueError(f"Unknown arrival process: {cfg.arrival_process}")
 
@@ -47,17 +50,61 @@ def _arrival_times(cfg: SimulationConfig, rng: random.Random) -> list[float]:
     return arrivals
 
 
+def _cache_tokens(cfg: SimulationConfig, prompt: int, cache_rng: random.Random) -> int:
+    if not cfg.prefix_cache_enabled or cfg.shared_prefix_tokens <= 0 or cfg.prefix_reuse_fraction <= 0:
+        return 0
+    if cache_rng.random() >= min(max(cfg.prefix_reuse_fraction, 0.0), 1.0):
+        return 0
+    return min(cfg.shared_prefix_tokens, max(prompt - 1, 0))
+
+
+def _from_trace(cfg: SimulationConfig, cache_rng: random.Random) -> list[Request]:
+    rows: list[tuple[float, int, int]] = []
+    for idx, raw in enumerate(cfg.trace_requests):
+        try:
+            arrival = float(raw["arrival_time"])
+            prompt = int(raw["prompt_tokens"])
+            output = int(raw["output_tokens"])
+        except (KeyError, TypeError, ValueError) as exc:
+            raise ValueError(
+                f"Trace row {idx} must contain numeric arrival_time, prompt_tokens, and output_tokens"
+            ) from exc
+        if not math.isfinite(arrival) or arrival < 0:
+            raise ValueError(f"Trace row {idx} has invalid arrival_time")
+        if prompt < 1 or output < 1:
+            raise ValueError(f"Trace row {idx} token counts must be positive")
+        rows.append((arrival, prompt, output))
+
+    rows.sort(key=lambda row: row[0])
+    requests: list[Request] = []
+    for request_id, (arrival, prompt, output) in enumerate(rows):
+        cached = _cache_tokens(cfg, prompt, cache_rng)
+        requests.append(
+            Request(
+                request_id=request_id,
+                arrival_time=arrival,
+                prompt_tokens=prompt,
+                output_tokens=output,
+                deadline_time=arrival + cfg.slo_e2e_ms / 1000.0,
+                remaining_prefill=max(0, prompt - cached),
+                cached_prefix_tokens=cached,
+            )
+        )
+    return requests
+
+
 def generate_workload(cfg: SimulationConfig) -> list[Request]:
     rng = random.Random(cfg.seed)
     cache_rng = random.Random(cfg.seed ^ 0x5A17CACE)
+
+    if cfg.arrival_process == "trace":
+        return _from_trace(cfg, cache_rng)
+
     requests: list[Request] = []
     for idx, arrival in enumerate(_arrival_times(cfg, rng)):
         prompt = _sample_lognormal(cfg.prompt_tokens_mean, cfg.prompt_tokens_cv, rng)
         output = _sample_lognormal(cfg.output_tokens_mean, cfg.output_tokens_cv, rng)
-        cached = 0
-        if cfg.prefix_cache_enabled and cfg.shared_prefix_tokens > 0 and cfg.prefix_reuse_fraction > 0:
-            if cache_rng.random() < min(max(cfg.prefix_reuse_fraction, 0.0), 1.0):
-                cached = min(cfg.shared_prefix_tokens, max(prompt - 1, 0))
+        cached = _cache_tokens(cfg, prompt, cache_rng)
         requests.append(
             Request(
                 request_id=idx,

styles.css

@@ -22,7 +22,7 @@ body {
   background: var(--bg);
   color: var(--text);
   font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
-  font-size: 14px;
+  font-size: 16px;
 }
 
 .topbar {
@@ -43,8 +43,8 @@ body.runtime-ready .topbar { transform: translateY(-58px); }
 body.runtime-ready .topbar:hover,
 body.runtime-ready .topbar:focus-within { transform: translateY(0); }
 .brand-wrap { display: flex; align-items: center; min-width: 0; }
-.brand { font-size: 14px; font-weight: 760; letter-spacing: -.01em; }
-.subtitle { margin-top: 2px; color: var(--faint); font-size: 10px; }
+.brand { font-size: 15px; font-weight: 760; letter-spacing: -.01em; }
+.subtitle { margin-top: 2px; color: var(--faint); font-size: 12px; }
 .runtime-pill {
   display: inline-flex;
   align-items: center;
@@ -54,7 +54,7 @@ body.runtime-ready .topbar:focus-within { transform: translateY(0); }
   background: var(--surface-2);
   border-radius: 4px;
   padding: 6px 9px;
-  font-size: 10px;
+  font-size: 11.5px;
   white-space: nowrap;
 }
 .runtime-pill .dot { width: 6px; height: 6px; border-radius: 50%; background: var(--amber); }
@@ -78,8 +78,8 @@ body.runtime-ready .shell { padding-top: 34px; }
 }
 .eyebrow, .section-kicker {
   color: var(--accent-2);
-  font-size: 9px;
-  line-height: 1.2;
+  font-size: 10.5px;
+  line-height: 1.25;
   text-transform: uppercase;
   letter-spacing: .1em;
   font-weight: 760;
@@ -93,17 +93,17 @@ body.runtime-ready .shell { padding-top: 34px; }
   letter-spacing: -.038em;
   font-weight: 720;
 }
-.intro p { max-width: 920px; margin: 0; color: var(--muted); font-size: 13px; line-height: 1.65; }
+.intro p { max-width: 920px; margin: 0; color: var(--muted); font-size: 14.5px; line-height: 1.65; }
 .project-facts { margin: 0; border-top: 1px solid var(--line); }
 .project-facts div { display: grid; grid-template-columns: 120px 1fr; gap: 14px; padding: 9px 0; border-bottom: 1px solid var(--line-soft); }
-.project-facts dt { color: var(--faint); font-size: 10px; }
-.project-facts dd { margin: 0; color: #bdc7d2; font-size: 11px; }
+.project-facts dt { color: var(--faint); font-size: 11.5px; }
+.project-facts dd { margin: 0; color: #bdc7d2; font-size: 12.5px; }
 .reference-note {
   border-left: 2px solid #6c6041;
   background: #11120f;
   color: #bcb5a5;
   padding: 10px 12px;
-  font-size: 11px;
+  font-size: 12.5px;
   line-height: 1.55;
 }
 
@@ -123,6 +123,7 @@ body.runtime-ready .shell { padding-top: 34px; }
   padding: 9px 11px;
   cursor: pointer;
   font-weight: 650;
+  font-size: 13px;
   white-space: nowrap;
 }
 .tab:hover { color: var(--text); }
@@ -130,13 +131,13 @@ body.runtime-ready .shell { padding-top: 34px; }
 .tab-panel { display: none; }
 .tab-panel.active { display: block; }
 
-.workspace { display: grid; grid-template-columns: 405px minmax(0, 1fr); gap: 14px; align-items: start; }
-.planner-grid { grid-template-columns: 360px minmax(0, 1fr); }
+.workspace { display: grid; grid-template-columns: 430px minmax(0, 1fr); gap: 14px; align-items: start; }
+.planner-grid { grid-template-columns: 390px minmax(0, 1fr); }
 .panel { background: var(--surface); border: 1px solid var(--line); border-radius: 6px; }
 .controls-panel { padding: 18px; position: sticky; top: 16px; }
 .result-panel, .wide-panel { padding: 20px; }
 .panel-title-row { display: flex; align-items: flex-start; justify-content: space-between; gap: 14px; margin-bottom: 16px; }
-.panel-title-row h2 { margin: 0; font-size: 17px; letter-spacing: -.02em; }
+.panel-title-row h2 { margin: 0; font-size: 19px; letter-spacing: -.02em; }
 .panel-title-row p { margin: 6px 0 0; }
 .tag {
   display: inline-flex;
@@ -146,26 +147,27 @@ body.runtime-ready .shell { padding-top: 34px; }
   color: var(--muted);
   border-radius: 4px;
   padding: 5px 7px;
-  font-size: 10px;
+  font-size: 11.5px;
   white-space: nowrap;
 }
 .tag.good { color: var(--good); border-color: #315e4a; }
 .tag.bad { color: var(--danger); border-color: #643943; }
 
-label { display: block; color: #b5bfcb; font-size: 11px; font-weight: 650; position: relative; }
+label { display: block; color: #b5bfcb; font-size: 12.5px; font-weight: 650; position: relative; }
 select, input[type="number"] {
   width: 100%;
   margin-top: 7px;
-  height: 37px;
+  height: 40px;
   border: 1px solid var(--line);
   background: #0a0f15;
   color: var(--text);
   border-radius: 4px;
   padding: 0 9px;
   outline: none;
+  font-size: 14px;
 }
 select:focus, input[type="number"]:focus { border-color: #5475a8; box-shadow: 0 0 0 2px rgba(84,117,168,.16); }
-.unit { position: absolute; right: 9px; bottom: 11px; color: #697687; font-size: 9px; pointer-events: none; }
+.unit { position: absolute; right: 9px; bottom: 12px; color: #697687; font-size: 10.5px; pointer-events: none; }
 .field-grid { display: grid; gap: 10px; margin-bottom: 10px; }
 .field-grid.two { grid-template-columns: 1fr 1fr; }
 .subcontrols { margin: 12px 0 4px; padding: 12px; border: 1px solid var(--line-soft); background: #0a0f15; }
@@ -175,7 +177,7 @@ hr { border: 0; border-top: 1px solid var(--line-soft); margin: 17px 0; }
 .hidden { display: none !important; }
 
 button.primary, button.secondary {
-  height: 40px;
+  height: 43px;
   border-radius: 4px;
   font-weight: 700;
   cursor: pointer;
@@ -192,37 +194,37 @@ button:disabled { opacity: .42; cursor: not-allowed; }
 .compact { width: auto !important; min-width: 178px; padding: 0 17px; margin-top: 0 !important; }
 .button-row { display: grid; grid-template-columns: 1fr 1fr; gap: 8px; margin-top: 8px; }
 .action-stack { display: flex; flex-direction: column; align-items: flex-end; gap: 8px; }
-.checkline { display: flex; align-items: center; gap: 7px; color: var(--muted); font-size: 10px; font-weight: 600; }
+.checkline { display: flex; align-items: center; gap: 7px; color: var(--muted); font-size: 12px; font-weight: 600; }
 .checkline input { accent-color: var(--accent); }
 
 .empty-state { min-height: 380px; display: grid; place-content: center; text-align: center; color: var(--muted); padding: 30px; }
 .empty-state.small { min-height: 240px; }
-.empty-state h3 { color: #ccd4de; margin: 0 0 6px; font-size: 15px; }
-.empty-state p { max-width: 560px; margin: 0; line-height: 1.55; font-size: 12px; }
+.empty-state h3 { color: #ccd4de; margin: 0 0 6px; font-size: 17px; }
+.empty-state p { max-width: 620px; margin: 0; line-height: 1.6; font-size: 13.5px; }
 .metric-grid { display: grid; grid-template-columns: repeat(6, 1fr); gap: 8px; margin-bottom: 12px; }
 .metric-grid.four { grid-template-columns: repeat(4, 1fr); }
 .metric { min-height: 82px; padding: 13px; border: 1px solid var(--line-soft); background: var(--surface-2); }
-.metric span { display: block; color: var(--muted); font-size: 10px; margin-bottom: 9px; }
-.metric strong { font-size: 18px; letter-spacing: -.025em; }
-.metric strong.metric-small { font-size: 13px; line-height: 1.35; }
+.metric span { display: block; color: var(--muted); font-size: 11.5px; margin-bottom: 9px; }
+.metric strong { font-size: 20px; letter-spacing: -.025em; }
+.metric strong.metric-small { font-size: 14.5px; line-height: 1.35; }
 .metric.emphasis { border-color: #486da4; background: #101824; }
 
 .diagnostic-card { margin-bottom: 12px; border: 1px solid var(--line); background: #0d131b; padding: 14px; }
 .diagnostic-head { display: flex; align-items: baseline; justify-content: space-between; gap: 16px; }
-.diagnostic-head span { color: var(--muted); font-size: 10px; text-transform: uppercase; letter-spacing: .06em; }
-.diagnostic-head strong { font-size: 14px; }
-.diagnostic-card p { margin: 8px 0 0; color: #b8c1cd; font-size: 12px; line-height: 1.55; }
+.diagnostic-head span { color: var(--muted); font-size: 11.5px; text-transform: uppercase; letter-spacing: .06em; }
+.diagnostic-head strong { font-size: 16px; }
+.diagnostic-card p { margin: 8px 0 0; color: #b8c1cd; font-size: 13.5px; line-height: 1.55; }
 .diagnostic-card .diagnostic-action { color: var(--muted); }
 .evidence-row { display: flex; flex-wrap: wrap; gap: 6px; margin-top: 10px; }
-.evidence-row span { border: 1px solid var(--line-soft); background: #090e14; padding: 4px 6px; color: #8390a0; font: 10px/1.2 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+.evidence-row span { border: 1px solid var(--line-soft); background: #090e14; padding: 5px 7px; color: #8390a0; font: 11px/1.25 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
 
 .chart-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 10px; }
 .chart-card { border: 1px solid var(--line); background: var(--surface-2); min-height: 300px; position: relative; }
 .chart-card.full { margin-top: 10px; }
 .chart-head { height: 42px; display: flex; align-items: center; justify-content: space-between; gap: 12px; padding: 0 12px; border-bottom: 1px solid var(--line-soft); }
-.chart-title { color: #c7d0db; font-size: 11px; font-weight: 700; }
+.chart-title { color: #c7d0db; font-size: 12.5px; font-weight: 700; }
 .chart-actions { display: flex; gap: 6px; }
-.chart-expand, .chart-download, .mini-button { border: 1px solid var(--line); background: #0a0f15; color: var(--muted); border-radius: 3px; cursor: pointer; height: 28px; padding: 0 9px; font-size: 10px; }
+.chart-expand, .chart-download, .mini-button { border: 1px solid var(--line); background: #0a0f15; color: var(--muted); border-radius: 3px; cursor: pointer; height: 31px; padding: 0 10px; font-size: 11.5px; }
 .chart-body { height: 260px; padding: 10px 12px 12px; }
 .chart-body.large { height: 350px; }
 .chart-card.chart-expanded { position: fixed; inset: 16px; z-index: 100; background: #0a0f15; border-color: #4c596b; box-shadow: 0 0 0 9999px rgba(0,0,0,.76); min-height: 0; margin: 0; }
@@ -230,35 +232,35 @@ button:disabled { opacity: .42; cursor: not-allowed; }
 body.chart-open { overflow: hidden; }
 canvas { width: 100% !important; height: 100% !important; max-height: none; }
 
-.warnings { margin-top: 10px; border-left: 3px solid #7b6840; padding: 9px 11px; background: #15140f; color: #c4bca9; font-size: 11px; line-height: 1.5; }
-.muted { color: var(--muted); font-size: 12px; line-height: 1.55; }
-.table-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-top: 14px; color: #aab4c1; font-size: 11px; }
+.warnings { margin-top: 10px; border-left: 3px solid #7b6840; padding: 10px 12px; background: #15140f; color: #c4bca9; font-size: 12.5px; line-height: 1.5; }
+.muted { color: var(--muted); font-size: 13.5px; line-height: 1.55; }
+.table-toolbar { display: flex; align-items: center; justify-content: space-between; gap: 12px; margin-top: 16px; color: #aab4c1; font-size: 12.5px; }
 .table-toolbar > div { display: flex; gap: 6px; }
 .table-wrap { overflow: auto; margin-top: 7px; border: 1px solid var(--line); }
-table { width: 100%; border-collapse: collapse; font-size: 12px; min-width: 900px; }
+table { width: 100%; border-collapse: collapse; font-size: 13.5px; min-width: 900px; }
 th, td { padding: 10px 11px; text-align: right; border-bottom: 1px solid var(--line-soft); white-space: nowrap; }
 th:first-child, td:first-child { text-align: left; }
-th { color: #7f8b9b; font-size: 9px; text-transform: uppercase; letter-spacing: .06em; background: #090e14; position: sticky; top: 0; }
+th { color: #8e9aab; font-size: 10.5px; text-transform: uppercase; letter-spacing: .06em; background: #090e14; position: sticky; top: 0; }
 td { color: #c7d0db; }
 tbody tr:last-child td { border-bottom: 0; }
 tbody tr:hover td { background: #111821; }
 .pass { color: var(--good); }
 .fail { color: var(--danger); }
-.best-label, .pareto-label { display: inline-block; margin-left: 7px; border: 1px solid #4a6386; color: #9ab8df; padding: 2px 5px; border-radius: 2px; font-size: 9px; text-transform: uppercase; }
-.planner-note { color: var(--muted); border-left: 2px solid #445a77; padding: 7px 9px; margin-bottom: 2px; font-size: 11px; line-height: 1.5; }
+.best-label, .pareto-label { display: inline-block; margin-left: 7px; border: 1px solid #4a6386; color: #9ab8df; padding: 2px 5px; border-radius: 2px; font-size: 10.5px; text-transform: uppercase; }
+.planner-note { color: var(--muted); border-left: 2px solid #445a77; padding: 9px 11px; margin-bottom: 2px; font-size: 12.5px; line-height: 1.5; }
 
 .method-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 12px; }
 .prose { padding: 22px; }
 .prose h2 { font-size: 20px; margin: 8px 0 11px; }
-.prose p { color: var(--muted); line-height: 1.7; font-size: 13px; }
+.prose p { color: var(--muted); line-height: 1.7; font-size: 14.5px; }
 .prose code { color: #a8bfe4; }
-.formula { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: #b7c3d2; padding: 10px; border: 1px solid var(--line); background: #0a0f15; font-size: 11px; }
+.formula { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; color: #b7c3d2; padding: 10px; border: 1px solid var(--line); background: #0a0f15; font-size: 12.5px; }
 .wide-method { grid-column: 1 / -1; }
 .paper-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 8px; margin-top: 18px; }
 .paper-grid > div { padding: 12px; border: 1px solid var(--line-soft); background: #0c1219; }
-.paper-grid strong { display: block; font-size: 11px; margin-bottom: 7px; }
-.paper-grid span { color: var(--muted); font-size: 10px; line-height: 1.55; display: block; }
-.toast { position: fixed; right: 20px; bottom: 20px; z-index: 130; background: #17202b; border: 1px solid #465467; color: #d5dce5; padding: 9px 12px; border-radius: 4px; font-size: 11px; opacity: 0; transform: translateY(8px); pointer-events: none; transition: .16s ease; }
+.paper-grid strong { display: block; font-size: 12.5px; margin-bottom: 7px; }
+.paper-grid span { color: var(--muted); font-size: 11.5px; line-height: 1.55; display: block; }
+.toast { position: fixed; right: 20px; bottom: 20px; z-index: 130; background: #17202b; border: 1px solid #465467; color: #d5dce5; padding: 9px 12px; border-radius: 4px; font-size: 12.5px; opacity: 0; transform: translateY(8px); pointer-events: none; transition: .16s ease; }
 .toast.show { opacity: 1; transform: translateY(0); }
 
 @media (max-width: 1100px) {
@@ -286,3 +288,27 @@ tbody tr:hover td { background: #111821; }
   .wide-method { grid-column: auto; }
   .chart-card.chart-expanded { inset: 6px; }
 }
+
+
+/* Research-oriented readability and trace controls */
+.tab { font-size: 13.5px; }
+button.primary, button.secondary { font-size: 13.5px; }
+input[type="file"] {
+  width: 100%; margin-top: 8px; color: #c4ccd7; font-size: 12.5px;
+  border: 1px solid var(--line); background: #090e14; padding: 9px; border-radius: 4px;
+}
+input[type="file"]::file-selector-button {
+  border: 1px solid #425168; background: #111925; color: #d4dbe4; padding: 7px 10px;
+  margin-right: 10px; border-radius: 3px; cursor: pointer;
+}
+.trace-row { display: flex; justify-content: space-between; align-items: center; gap: 10px; margin-top: 10px; color: #b8c1cc; font-size: 12.5px; }
+.control-help { margin: 10px 0 0; color: var(--muted); font-size: 12px; line-height: 1.55; }
+.research-grid { display: grid; grid-template-columns: 390px minmax(0, 1fr); gap: 14px; align-items: start; }
+.research-controls { padding: 20px; position: sticky; top: 16px; }
+.research-results { display: grid; gap: 14px; min-width: 0; }
+.research-panel { padding: 20px; }
+.research-secondary { width: 100%; margin-top: 10px; }
+.study-summary { border-left: 2px solid #516d92; background: #0a1017; padding: 11px 13px; color: #b9c3cf; font-size: 13px; line-height: 1.6; margin-bottom: 10px; }
+.study-summary strong { color: #e1e7ee; }
+.research-chart { height: 310px; }
+@media (max-width: 1100px) { .research-grid { grid-template-columns: 1fr; } .research-controls { position: static; } }

tests/test_research.py

@@ -0,0 +1,38 @@
+from inferscale import paired_study, robustness_study
+
+
+BASE = {
+    "model": "Qwen2.5-3B",
+    "accelerator": "L4",
+    "quantization": "int8",
+    "duration_s": 8,
+    "request_rate_rps": 2.5,
+    "prompt_tokens_mean": 256,
+    "output_tokens_mean": 32,
+    "shared_prefix_tokens": 128,
+    "prefix_reuse_fraction": 0.75,
+    "prefill_accelerator": "L4",
+    "decode_accelerator": "L4",
+}
+
+
+def test_paired_study_uses_common_seeds_and_returns_ci():
+    result = paired_study(BASE, "prefix_cache", repetitions=4, bootstrap_samples=100)
+    assert result["protocol"] == "paired-common-random-numbers"
+    assert len(result["pairs"]) == 4
+    assert all(row["seed"] == BASE.get("seed", 7) + idx * 1009 for idx, row in enumerate(result["pairs"]))
+    assert {row["metric"] for row in result["metrics"]} == {
+        "goodput_rps", "p95_ttft_ms", "p95_e2e_ms", "slo_attainment"
+    }
+    assert all("delta_ci95_low" in row for row in result["metrics"])
+
+
+def test_robustness_study_perturbs_reference_model():
+    result = robustness_study(BASE, "pd_vs_colocated", samples=6, uncertainty=0.15)
+    assert result["samples"] == 6
+    assert result["method"] == "shared-multiplicative-latency-perturbation"
+    assert len(result["rows"]) == 6
+    for row in result["rows"]:
+        assert 0.85 <= row["prefill_scale"] <= 1.15
+        assert 0.85 <= row["decode_scale"] <= 1.15
+        assert 0.85 <= row["transfer_scale"] <= 1.15

tests/test_trace_replay.py

@@ -0,0 +1,32 @@
+from inferscale import run_simulation
+
+
+def test_trace_replay_preserves_arrivals_and_lengths():
+    trace = [
+        {"arrival_time": 0.4, "prompt_tokens": 96, "output_tokens": 8},
+        {"arrival_time": 0.1, "prompt_tokens": 64, "output_tokens": 6},
+        {"arrival_time": 0.9, "prompt_tokens": 128, "output_tokens": 10},
+    ]
+    result = run_simulation({
+        "model": "Qwen2.5-3B",
+        "accelerator": "L4",
+        "quantization": "int8",
+        "arrival_process": "trace",
+        "trace_requests": trace,
+        "duration_s": 2,
+        "slo_ttft_ms": 5000,
+        "slo_e2e_ms": 10000,
+    })
+    rows = result["requests"]
+    assert result["summary"]["requests_generated"] == 3
+    assert [row["arrival_time"] for row in rows] == [0.1, 0.4, 0.9]
+    assert [row["prompt_tokens"] for row in rows] == [64, 96, 128]
+
+
+def test_trace_replay_rejects_bad_rows():
+    try:
+        run_simulation({"arrival_process": "trace", "trace_requests": [{"arrival_time": 0.0}]})
+    except ValueError as exc:
+        assert "Trace row" in str(exc)
+    else:
+        raise AssertionError("bad trace should fail")

tests/test_validation.py

@@ -0,0 +1,19 @@
+from inferscale.validation import validate_cases
+
+
+def test_validation_report_compares_external_metrics():
+    base = {
+        "model": "Qwen2.5-3B", "accelerator": "L4", "quantization": "int8",
+        "duration_s": 4, "request_rate_rps": 1, "prompt_tokens_mean": 128, "output_tokens_mean": 8,
+    }
+    # Values are deliberately arbitrary: this tests the validation machinery,
+    # not empirical accuracy of the analytical reference profile.
+    report = validate_cases([{
+        "name": "fixture",
+        "config": base,
+        "measured": {"p95_ttft_ms": 100.0, "goodput_rps": 0.8},
+    }])
+    assert report["case_count"] == 1
+    assert report["observation_count"] == 2
+    assert report["mape_pct"] >= 0
+    assert {row["metric"] for row in report["rows"]} == {"p95_ttft_ms", "goodput_rps"}

worker.mjs

@@ -11,7 +11,9 @@ const MODULES = [
   "models.py",
   "optimizer.py",
   "profiles.py",
+  "research.py",
   "simulator.py",
+  "validation.py",
   "workloads.py",
 ];