Upload folder using huggingface_hub

README.md

@@ -1,10 +1,91 @@
 ---
 title: Flashback
-emoji: 📚
-colorFrom: pink
-colorTo: red
+emoji: 🔦
+colorFrom: indigo
+colorTo: gray
 sdk: static
+app_file: index.html
 pinned: false
+license: apache-2.0
+short_description: Find the step your training run broke on, from 452 B/step
+tags:
+  - machine-learning
+  - distributed-training
+  - checkpointing
+  - observability
+  - debugging
+  - anomaly-detection
+  - pytorch
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Flashback — find the step your training run broke on
+
+**Finding the step a training run broke on should cost kilobytes, not terabytes.**
+
+A large run fails. Somewhere in the last 40,000 steps a learning rate spiked, a bit
+flipped, a shard of the dataloader started serving garbage. Today you answer *"when did
+this start?"* by squinting at a loss curve and reloading whichever checkpoint happens to be
+nearest — so your answer is quantised to the checkpoint interval, and only exists at all if
+the loss actually moved.
+
+Flashback keeps a **452-byte sketch of every single step** — 128 internal statistics that
+usually move long before the loss does — and bisects that index with **zero state
+reconstructions**.
+
+## What this Space is
+
+The telemetry here is **real**: recorded from actual training runs of a small Transformer
+in which a specific fault was injected at a specific step, with the ground truth written
+down before any detector looked at the data. The page reimplements
+[`flashback.bisect`](https://github.com/NagaYu/flashback/blob/main/flashback/bisect.py) in
+JavaScript so it can run for free as a static Space, and **checks itself against the answers
+Python computed for the same data** — the verification badge at the bottom of the page says
+whether the port currently agrees.
+
+Pick a fault, then compare the two charts. For the bit-flip scenario the loss curve never
+crosses its own anomaly threshold at any point in the run; the sketch crosses it on the
+exact step.
+
+## Measured results
+
+12 runs across 6 fault types, ground truth recorded before any detector runs:
+
+| condition | mean error | exact hits | never detected |
+|---|---:|---:|---:|
+| (A) full checkpoint every 100 steps + loss curve | 20.0 | 0/12 | 4 |
+| (B) full checkpoint every step + loss curve (ideal) | 0.5 | 4/12 | 4 |
+| **(C) Flashback sketch + bisect** | **0.0** | **12/12** | **0** |
+
+## Add it to your own run
+
+```python
+from flashback.integrations import FlashbackCallback
+
+trainer = Trainer(..., callbacks=[FlashbackCallback("runs/my-run")])
+```
+
+```bash
+flashback bisect my-run --metric grad_norm
+```
+
+## Links
+
+- **Code**: <https://github.com/NagaYu/flashback>
+- **Dataset**: <https://huggingface.co/datasets/NagaYu/flashback-forensics>
+- **Detector model**: <https://huggingface.co/NagaYu/flashback-first-bad-step>
+
+## What this demo is honest about
+
+- The detector needs a **healthy stretch** to calibrate against. A run broken from step 0
+  has no baseline and will not be localised.
+- It detects **regime changes**, so a fault that ramps in smoothly over hundreds of steps
+  has no single correct answer. The `data poisoning` scenario here is off by ~36 steps at
+  this model size, and the page shows that rather than hiding it.
+- **No bitwise determinism is claimed.** This is a statistical detector over recorded
+  statistics.
+- The demo model is tiny (0.13M parameters, 600 steps) so the page stays a few megabytes.
+  The mechanism is size-independent; the repository's benchmark runs the same experiments up
+  to ~30M parameters.
+- A full Gradio version of this demo — which additionally generates fresh runs on demand —
+  is in the repository as `app.py`. Hugging Face requires a PRO subscription to host Gradio
+  Spaces, so the free public demo is this static one.

data/index.json

@@ -0,0 +1,183 @@
+{
+ "scenarios": [
+  {
+   "key": "bit_flip",
+   "title": "bit flip (silent data corruption)",
+   "blurb": "One flipped exponent bit in one gradient element. Adam normalises the update away, so the loss curve usually never reacts at all.",
+   "truth": 372,
+   "bytes": 609898
+  },
+  {
+   "key": "lr_spike_loud",
+   "title": "learning-rate spike (loud)",
+   "blurb": "The easy case, included on purpose: the loss spikes, so watching the curve works here too.",
+   "truth": 372,
+   "bytes": 610213
+  },
+  {
+   "key": "lr_spike_subtle",
+   "title": "learning-rate drift (subtle)",
+   "blurb": "A sustained 4x learning rate. The loss degrades gradually, so 'when did it start?' is genuinely hard by eye.",
+   "truth": 372,
+   "bytes": 608000
+  },
+  {
+   "key": "overflow",
+   "title": "fp8-range overflow",
+   "blurb": "Gradients pushed outside an emulated fp8 range produce Inf, which propagates into the optimizer state.",
+   "truth": 372,
+   "bytes": 461278
+  },
+  {
+   "key": "data_poison",
+   "title": "data poisoning (12% of each batch)",
+   "blurb": "A small contamination, inside the loss curve's own noise band.",
+   "truth": 372,
+   "bytes": 607198
+  },
+  {
+   "key": "clean",
+   "title": "healthy run (no fault)",
+   "blurb": "A control. A good detector must report nothing here.",
+   "truth": null,
+   "bytes": 609191
+  }
+ ],
+ "n_metrics": 124,
+ "metrics": [
+  "loss",
+  "grad_norm",
+  "update_norm",
+  "param_norm",
+  "grad_max_abs",
+  "update_max_abs",
+  "param_max_abs",
+  "nonfinite_grad",
+  "nonfinite_param",
+  "sign_flip_rate",
+  "cos_grad_prev",
+  "update_param_ratio",
+  "grad_mean",
+  "grad_var",
+  "grad_absmean",
+  "grad_norm_tensor_max",
+  "grad_norm_tensor_min",
+  "grad_rms",
+  "loss_delta",
+  "update_norm_tensor_max",
+  "group:all:mean",
+  "group:all:var",
+  "group:all:max_abs",
+  "group:all:grad_l2",
+  "group:all:update_l2",
+  "group:all:sign_flip",
+  "group:all:nonfinite",
+  "group:all:upd_param_ratio",
+  "group:embed:mean",
+  "group:embed:var",
+  "group:embed:max_abs",
+  "group:embed:grad_l2",
+  "group:embed:update_l2",
+  "group:embed:sign_flip",
+  "group:embed:nonfinite",
+  "group:embed:upd_param_ratio",
+  "group:attn_qkv:mean",
+  "group:attn_qkv:var",
+  "group:attn_qkv:max_abs",
+  "group:attn_qkv:grad_l2",
+  "group:attn_qkv:update_l2",
+  "group:attn_qkv:sign_flip",
+  "group:attn_qkv:nonfinite",
+  "group:attn_qkv:upd_param_ratio",
+  "group:attn_out:mean",
+  "group:attn_out:var",
+  "group:attn_out:max_abs",
+  "group:attn_out:grad_l2",
+  "group:attn_out:update_l2",
+  "group:attn_out:sign_flip",
+  "group:attn_out:nonfinite",
+  "group:attn_out:upd_param_ratio",
+  "group:mlp_in:mean",
+  "group:mlp_in:var",
+  "group:mlp_in:max_abs",
+  "group:mlp_in:grad_l2",
+  "group:mlp_in:update_l2",
+  "group:mlp_in:sign_flip",
+  "group:mlp_in:nonfinite",
+  "group:mlp_in:upd_param_ratio",
+  "group:mlp_out:mean",
+  "group:mlp_out:var",
+  "group:mlp_out:max_abs",
+  "group:mlp_out:grad_l2",
+  "group:mlp_out:update_l2",
+  "group:mlp_out:sign_flip",
+  "group:mlp_out:nonfinite",
+  "group:mlp_out:upd_param_ratio",
+  "group:norm:mean",
+  "group:norm:var",
+  "group:norm:max_abs",
+  "group:norm:grad_l2",
+  "group:norm:update_l2",
+  "group:norm:sign_flip",
+  "group:norm:nonfinite",
+  "group:norm:upd_param_ratio",
+  "group:head:mean",
+  "group:head:var",
+  "group:head:max_abs",
+  "group:head:grad_l2",
+  "group:head:update_l2",
+  "group:head:sign_flip",
+  "group:head:nonfinite",
+  "group:head:upd_param_ratio",
+  "hist_grad:0",
+  "hist_grad:1",
+  "hist_grad:2",
+  "hist_grad:3",
+  "hist_grad:4",
+  "hist_grad:5",
+  "hist_grad:6",
+  "hist_grad:7",
+  "hist_grad:8",
+  "hist_grad:9",
+  "hist_grad:10",
+  "hist_grad:11",
+  "hist_grad:12",
+  "hist_grad:13",
+  "hist_grad:14",
+  "hist_grad:15",
+  "hist_update:0",
+  "hist_update:1",
+  "hist_update:2",
+  "hist_update:3",
+  "hist_update:4",
+  "hist_update:5",
+  "hist_update:6",
+  "hist_update:7",
+  "hist_update:8",
+  "hist_update:9",
+  "hist_update:10",
+  "hist_update:11",
+  "hist_update:12",
+  "hist_update:13",
+  "hist_update:14",
+  "hist_update:15",
+  "qnorm:0",
+  "qnorm:1",
+  "qnorm:2",
+  "qnorm:3",
+  "qnorm:4",
+  "qnorm:5",
+  "qnorm:6",
+  "qnorm:7"
+ ],
+ "bytes_per_step": 452,
+ "win": 32,
+ "preset": "nano",
+ "steps": 600,
+ "exclude": [
+  "lr",
+  "step_wall_ms",
+  "batch_id_mean",
+  "batch_uniq_frac"
+ ]
+}

detector.js

@@ -0,0 +1,224 @@
+/* A faithful JavaScript port of flashback/bisect.py.
+ *
+ * Hugging Face hosts static Spaces free for everyone but charges for Gradio
+ * ones, so the public demo runs the detector in the browser.  A port is only
+ * worth anything if it agrees with the original, so every function below
+ * mirrors a named Python function, and index.html checks the results against
+ * the answers Python computed for the same data (shipped in data/*.json).
+ *
+ * Python's numeric conventions that matter here:
+ *   - np.nanmedian ignores non-finite entries in a window
+ *   - np.percentile uses linear interpolation
+ *   - non-finite metric values mean "bad" and score +Infinity
+ */
+
+export const MAD_TO_SIGMA = 1.4826;
+export const HARD_SIGNALS = new Set([
+  "nonfinite_grad", "nonfinite_param", "group:all:nonfinite",
+]);
+
+function median(sorted) {
+  const n = sorted.length;
+  if (n === 0) return NaN;
+  const m = n >> 1;
+  return n % 2 ? sorted[m] : 0.5 * (sorted[m - 1] + sorted[m]);
+}
+
+function medianOf(values) {
+  const f = [];
+  for (const v of values) if (Number.isFinite(v)) f.push(v);
+  f.sort((a, b) => a - b);
+  return median(f);
+}
+
+/** numpy.percentile(a, q) with the default 'linear' method. */
+function percentile(sortedAsc, q) {
+  const n = sortedAsc.length;
+  if (n === 0) return NaN;
+  const pos = (q / 100) * (n - 1);
+  const lo = Math.floor(pos), hi = Math.ceil(pos);
+  if (lo === hi) return sortedAsc[lo];
+  return sortedAsc[lo] + (sortedAsc[hi] - sortedAsc[lo]) * (pos - lo);
+}
+
+/** Port of flashback.bisect.prepare_series. */
+export function prepareSeries(x, mode = "diff") {
+  const n = x.length;
+  if (mode === "level" || n < 3) return Float64Array.from(x);
+  let work = Float64Array.from(x);
+  let allPositive = true, any = false, mn = Infinity, mx = -Infinity;
+  for (const v of x) {
+    if (!Number.isFinite(v)) continue;
+    any = true;
+    if (v <= 0) allPositive = false;
+    if (v < mn) mn = v;
+    if (v > mx) mx = v;
+  }
+  if (any && allPositive) {
+    const span = mx / Math.max(mn, 1e-300);
+    if (span > 100) for (let i = 0; i < n; i++) work[i] = Math.log(Math.max(work[i], 1e-300));
+  }
+  const d = new Float64Array(n);
+  for (let i = 1; i < n; i++) d[i] = work[i] - work[i - 1];
+  // A step whose *original* value is non-finite stays non-finite, so the
+  // hard-signal and nonfinite_is_bad paths still see it.
+  for (let i = 0; i < n; i++) if (!Number.isFinite(x[i])) d[i] = Infinity;
+  return d;
+}
+
+/** Port of flashback.bisect.rolling_z. Returns {z, ok}. */
+export function rollingZ(series, win = 64, gap = 1,
+                         relFloor = 1e-3, globalFloorFrac = 1e-2, absFloor = 1e-12) {
+  const n = series.length;
+  const z = new Float64Array(n);
+  const ok = new Uint8Array(n);
+  if (n < win + gap + 2) return { z, ok };
+
+  let gmax = 0;
+  for (const v of series) if (Number.isFinite(v)) gmax = Math.max(gmax, Math.abs(v));
+  const floor = Math.max(gmax * globalFloorFrac, absFloor);
+
+  for (let i = win + gap; i < n; i++) {
+    const start = i - gap - win;
+    const w = [];
+    for (let j = start; j < start + win; j++) if (Number.isFinite(series[j])) w.push(series[j]);
+    let center = 0, scale = 0;
+    if (w.length) {
+      w.sort((a, b) => a - b);
+      center = median(w);
+      const dev = w.map((v) => Math.abs(v - center)).sort((a, b) => a - b);
+      scale = median(dev) * MAD_TO_SIGMA;
+    }
+    if (!Number.isFinite(center)) center = 0;
+    if (!Number.isFinite(scale)) scale = 0;
+    scale = Math.max(scale, Math.max(Math.abs(center) * relFloor, floor));
+    const x = series[i];
+    let zi = Number.isFinite(x) ? (x - center) / scale : Infinity;
+    if (Number.isNaN(zi)) zi = 0;
+    z[i] = zi;
+    ok[i] = 1;
+  }
+  return { z, ok };
+}
+
+/** Port of flashback.bisect.calibrate (healthy_upto is unused by the demo). */
+export function calibrate(z, ok, kCal = 12.0, kMin = 8.0) {
+  const a = [];
+  for (let i = 0; i < z.length; i++) {
+    if (!ok[i]) continue;
+    const v = Math.abs(z[i]);
+    if (Number.isFinite(v)) a.push(v);
+  }
+  if (a.length < 8) return { threshold: Infinity, usable: false };
+  a.sort((x, y) => x - y);
+  const med = median(a);
+  const dev = a.map((v) => Math.abs(v - med)).sort((x, y) => x - y);
+  let sc = median(dev) * MAD_TO_SIGMA;
+  if (!(sc > 0)) sc = (percentile(a, 90) - med) || 1.0;
+  return { threshold: Math.max(kMin, med + kCal * sc), usable: true, median: med, scale: sc };
+}
+
+/** Port of flashback.bisect.detect_on_series (two_sided, min_run=1). */
+export function detectOnSeries(raw, steps, spec, opts = {}) {
+  const { win = 32, gap = 1, mode = "diff", kCal = 12.0, kMin = 8.0 } = opts;
+  const n = raw.length;
+
+  if (HARD_SIGNALS.has(spec)) {
+    for (let i = 0; i < n; i++) {
+      if ((Number.isFinite(raw[i]) && raw[i] > 0) || !Number.isFinite(raw[i])) {
+        return { detected: true, index: i, step: steps[i], z: Infinity, threshold: 0, spec };
+      }
+    }
+    return { detected: false, spec, threshold: 0 };
+  }
+
+  const w = Math.max(8, Math.min(win, Math.max(8, Math.floor(n / 4))));
+  const { z, ok } = rollingZ(prepareSeries(raw, mode), w, gap);
+  const prof = calibrate(z, ok, kCal, kMin);
+  if (!prof.usable) return { detected: false, spec, threshold: prof.threshold };
+  for (let i = 0; i < n; i++) {
+    if (!ok[i]) continue;
+    const zz = Math.abs(z[i]);
+    if (zz > prof.threshold || !Number.isFinite(raw[i])) {
+      return { detected: true, index: i, step: steps[i],
+               z: Number.isFinite(raw[i]) ? zz : Infinity,
+               threshold: prof.threshold, spec };
+    }
+  }
+  return { detected: false, spec, threshold: prof.threshold };
+}
+
+/** |z| series for plotting, matching what detectOnSeries scores. */
+export function zSeries(raw, spec, opts = {}) {
+  const { win = 32, gap = 1, mode = "diff" } = opts;
+  const n = raw.length;
+  if (HARD_SIGNALS.has(spec)) {
+    const z = new Float64Array(n), ok = new Uint8Array(n);
+    for (let i = 0; i < n; i++) {
+      ok[i] = 1;
+      z[i] = ((Number.isFinite(raw[i]) && raw[i] > 0) || !Number.isFinite(raw[i])) ? Infinity : 0;
+    }
+    return { z, ok, threshold: 0 };
+  }
+  const w = Math.max(8, Math.min(win, Math.max(8, Math.floor(n / 4))));
+  const { z, ok } = rollingZ(prepareSeries(raw, mode), w, gap);
+  const az = new Float64Array(n);
+  for (let i = 0; i < n; i++) az[i] = Number.isFinite(raw[i]) ? Math.abs(z[i]) : Infinity;
+  const prof = calibrate(z, ok, opts.kCal ?? 12.0, opts.kMin ?? 8.0);
+  return { z: az, ok, threshold: prof.threshold };
+}
+
+/**
+ * Port of flashback.bisect.bisect_first_bad(metric="auto", strategy="scan").
+ * Returns the earliest step at which `minVotes` metrics agree within
+ * `voteWindow`, falling back to the earliest single detection unless
+ * `requireConsensus`.
+ */
+export function bisectFirstBad(table, steps, specs, opts = {}) {
+  const { minVotes = 3, voteWindow = 4, requireConsensus = false } = opts;
+  const dets = [];
+  for (const spec of specs) {
+    const s = table[spec];
+    if (!s) continue;
+    const d = detectOnSeries(s, steps, spec, opts);
+    if (d.detected) dets.push(d);
+  }
+  const indexReads = steps.length * specs.length;
+  if (!dets.length) {
+    return { step: null, votes: 0, metric: "auto", indexReads, stateProbes: 0,
+             candidates: [], note: "no metric crossed threshold" };
+  }
+  dets.sort((a, b) => (a.index - b.index) || (b.z - a.z));
+  const idxs = dets.map((d) => d.index);
+  for (const d of dets) {
+    const votes = idxs.filter((i) => i >= d.index && i <= d.index + voteWindow).length;
+    if (votes >= minVotes) {
+      return { step: d.step, index: d.index, metric: d.spec, z: d.z,
+               threshold: d.threshold, votes, indexReads, stateProbes: 0,
+               candidates: dets, note: "" };
+    }
+  }
+  const note = `no ${minVotes}-metric consensus; reporting earliest single detection`;
+  if (requireConsensus) {
+    return { step: null, votes: 0, metric: "auto", indexReads, stateProbes: 0,
+             candidates: dets, note: note + " (suppressed: require consensus)" };
+  }
+  const b = dets[0];
+  return { step: b.step, index: b.index, metric: b.spec, z: b.z, threshold: b.threshold,
+           votes: 1, indexReads, stateProbes: 0, candidates: dets, note };
+}
+
+/**
+ * The `git bisect` predicate: has anything gone wrong at or *before* this step?
+ * Only the cumulative form is monotone -- "is THIS step bad?" is false again
+ * one step after a transient fault, and a binary search on it walks off the end
+ * of the run.
+ */
+export function prefixBad(zs, i) {
+  let worst = 0;
+  for (let j = 0; j <= i && j < zs.z.length; j++) {
+    if (!zs.ok[j]) continue;
+    if (zs.z[j] > worst) worst = zs.z[j];
+  }
+  return { bad: worst > zs.threshold, z: worst };
+}

index.html

@@ -1,19 +1,525 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Flashback — find the step your training run broke on</title>
+<style>
+  :root {
+    --bg: #ffffff; --fg: #1a1a1a; --muted: #666; --line: #e3e3e6;
+    --card: #fafafa; --accent: #1f77b4; --loss: #c0392b; --ok: #2ca02c;
+    --warn: #e08a1e; --mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root { --bg:#0f1115; --fg:#e8e8ea; --muted:#9aa0a6; --line:#2a2d34;
+            --card:#161920; --accent:#5aa9e6; --loss:#ff6b5a; --ok:#5ec26a; }
+  }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--fg);
+         font: 15px/1.6 -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; }
+  .wrap { max-width: 1100px; margin: 0 auto; padding: 28px 20px 80px; }
+  h1 { font-size: 30px; margin: 0 0 6px; letter-spacing: -0.02em; }
+  h2 { font-size: 19px; margin: 34px 0 10px; letter-spacing: -0.01em; }
+  h3 { font-size: 15px; margin: 20px 0 8px; }
+  .lede { color: var(--muted); font-size: 16px; margin: 0 0 4px; }
+  a { color: var(--accent); }
+  .card { background: var(--card); border: 1px solid var(--line);
+          border-radius: 10px; padding: 16px 18px; }
+  .row { display: flex; flex-wrap: wrap; gap: 10px; }
+  button, select, input[type=number] {
+    font: inherit; color: var(--fg); background: var(--bg);
+    border: 1px solid var(--line); border-radius: 7px; padding: 7px 12px; cursor: pointer; }
+  button:hover { border-color: var(--accent); }
+  button.sel { background: var(--accent); color: #fff; border-color: var(--accent); }
+  button.primary { background: var(--accent); color:#fff; border-color: var(--accent);
+                   font-weight: 600; }
+  label { font-size: 13px; color: var(--muted); display: flex; flex-direction: column;
+          gap: 4px; }
+  table { border-collapse: collapse; width: 100%; font-size: 13.5px; }
+  th, td { text-align: left; padding: 6px 10px; border-bottom: 1px solid var(--line); }
+  th { color: var(--muted); font-weight: 600; }
+  td.num, th.num { text-align: right; font-variant-numeric: tabular-nums; }
+  code, .mono { font-family: var(--mono); font-size: 12.5px; }
+  .pill { display:inline-block; padding: 2px 9px; border-radius: 999px; font-size: 12px;
+          font-weight: 600; }
+  .pill.ok { background: rgba(44,160,44,.15); color: var(--ok); }
+  .pill.bad { background: rgba(192,57,43,.15); color: var(--loss); }
+  .pill.warn { background: rgba(224,138,30,.15); color: var(--warn); }
+  .grid2 { display: grid; grid-template-columns: 1fr 1fr; gap: 16px; }
+  @media (max-width: 820px) { .grid2 { grid-template-columns: 1fr; } }
+  .kv { display: grid; grid-template-columns: auto 1fr; gap: 4px 14px; font-size: 14px; }
+  .kv dt { color: var(--muted); }
+  .kv dd { margin: 0; font-variant-numeric: tabular-nums; }
+  .muted { color: var(--muted); }
+  .small { font-size: 13px; }
+  svg { width: 100%; height: auto; display: block; }
+  .axis { stroke: var(--line); stroke-width: 1; }
+  .tick { fill: var(--muted); font-size: 10px; }
+  .scroll { overflow-x: auto; }
+  footer { margin-top: 48px; padding-top: 18px; border-top: 1px solid var(--line);
+           color: var(--muted); font-size: 13.5px; }
+</style>
+</head>
+<body>
+<div class="wrap">
+
+  <h1>Flashback</h1>
+  <p class="lede">Find the step a training run broke on, from
+     <strong>452 bytes per step</strong>.</p>
+  <p class="small muted" style="max-width:78ch">
+    The top chart is what you would see on your dashboard. The bottom chart is what a
+    452-byte-per-step sketch saw at the same steps. Everything below is computed in your
+    browser from <em>recorded telemetry of real training runs with real injected faults</em>
+    — the ground truth was written down before any detector looked at the data.
+  </p>
+
+  <div id="scenarios" class="row" style="margin:18px 0 14px"></div>
+  <p id="blurb" class="small muted" style="margin:0 0 16px"></p>
+
+  <div class="card">
+    <div class="row" style="align-items:flex-end">
+      <label>metric
+        <select id="metric"><option value="auto">auto — test all of them</option></select>
+      </label>
+      <label>baseline window
+        <input id="win" type="number" min="8" max="128" step="4" value="32" style="width:92px">
+      </label>
+      <label>metrics required to agree
+        <input id="votes" type="number" min="1" max="12" value="3" style="width:92px">
+      </label>
+      <label>vote window
+        <input id="vwin" type="number" min="0" max="20" value="4" style="width:92px">
+      </label>
+      <label>mode
+        <select id="mode">
+          <option value="diff">diff — regime change</option>
+          <option value="level">level — excursion</option>
+        </select>
+      </label>
+      <label style="flex-direction:row;align-items:center;gap:7px">
+        <input id="strict" type="checkbox"> report nothing without consensus
+      </label>
+      <button id="run" class="primary">Run bisect</button>
+    </div>
+  </div>
+
+  <div id="result" class="card" style="margin-top:14px"></div>
+
+  <h2>What the loss curve shows</h2>
+  <div id="lossChart"></div>
+
+  <h2>What the sketch shows at the same steps</h2>
+  <div id="zChart"></div>
+  <p class="small muted" id="zlegend"></p>
+
+  <h2>Earliest detection, by metric</h2>
+  <p id="metricsNote" class="small muted" style="margin:0 0 10px;max-width:78ch"></p>
+  <div class="scroll"><table id="metrics"><tbody></tbody></table></div>
+
+  <h2>Bisect by hand</h2>
+  <p class="small muted" style="max-width:78ch">
+    Each probe asks the <code>git bisect</code> question —
+    <strong>has anything gone wrong at or before this step?</strong> — and halves the
+    bracket. That phrasing matters: <em>“is <strong>this step</strong> bad?”</em> is not
+    monotone (a flipped bit is bad at exactly one step), so a binary search on it walks off
+    the end of the run. <em>“has it gone bad <strong>yet</strong>?”</em> is monotone — and it
+    is also the question you can afford to ask expensively, since in the deterministic replay
+    mode each answer costs one state reconstruction.
+  </p>
+  <div class="card">
+    <div class="row" style="align-items:flex-end">
+      <label>metric to probe
+        <select id="mmetric" style="max-width:280px"></select>
+      </label>
+      <label>probe this step
+        <input id="mstep" type="number" value="0" style="width:110px">
+      </label>
+      <button id="mprobe" class="primary">Probe</button>
+      <button id="mreset">Start over</button>
+    </div>
+    <div id="manual" style="margin-top:14px"></div>
+  </div>
+
+  <footer>
+    <p><strong>What this demo is honest about.</strong>
+    The detector needs a healthy stretch to calibrate against — a run broken from step 0 has
+    no baseline. It detects <em>regime changes</em>, so a fault that ramps in over hundreds of
+    steps has no single correct answer. No bitwise determinism is claimed anywhere: this is a
+    statistical detector over recorded statistics. The demo model is tiny
+    (<span id="fparams"></span>) so the page stays small; the mechanism is size-independent
+    and the repository's benchmark runs the same experiments up to ~30M parameters.</p>
+    <p>
+      <a href="https://github.com/NagaYu/flashback">Code on GitHub</a> ·
+      <a href="https://huggingface.co/datasets/NagaYu/flashback-forensics">Dataset</a> ·
+      <a href="https://huggingface.co/NagaYu/flashback-first-bad-step">Detector model</a>
+      · Apache-2.0
+    </p>
+    <p id="parity" class="small"></p>
+  </footer>
+</div>
+
+<script type="module">
+import { detectOnSeries, zSeries, bisectFirstBad, prefixBad, HARD_SIGNALS }
+  from "./detector.js";
+
+const $ = (id) => document.getElementById(id);
+const state = { index: null, data: null, key: null, manual: null };
+
+const fmt = (v) => (v === null || v === undefined) ? "—"
+  : (!Number.isFinite(v) ? "∞" : (Math.abs(v) >= 1000 ? v.toExponential(2)
+     : (Number.isInteger(v) ? String(v) : v.toFixed(2))));
+
+/* JSON has no Inf/NaN, so the exporter writes null for every non-finite value. */
+const revive = (arr) => Float64Array.from(arr, (v) => (v === null ? NaN : v));
+
+async function boot() {
+  state.index = await (await fetch("data/index.json")).json();
+  const bar = $("scenarios");
+  state.index.scenarios.forEach((s, i) => {
+    const b = document.createElement("button");
+    b.textContent = s.title;
+    b.onclick = () => select(s.key);
+    b.dataset.key = s.key;
+    bar.appendChild(b);
+    if (i === 0) b.classList.add("sel");
+  });
+  const msel = $("metric"), mm = $("mmetric");
+  for (const spec of state.index.metrics) {
+    msel.appendChild(new Option(spec, spec));
+    mm.appendChild(new Option(spec, spec));
+  }
+  mm.value = "grad_norm";
+  $("run").onclick = render;
+  $("mprobe").onclick = manualProbe;
+  $("mreset").onclick = manualReset;
+  for (const id of ["metric", "win", "votes", "vwin", "mode", "strict"]) {
+    $(id).onchange = render;
+  }
+  $("mmetric").onchange = manualReset;
+  await select(state.index.scenarios[0].key);
+}
+
+async function select(key) {
+  document.querySelectorAll("#scenarios button")
+    .forEach((b) => b.classList.toggle("sel", b.dataset.key === key));
+  const raw = await (await fetch(`data/${key}.json`)).json();
+  raw.metricsF = {};
+  for (const [k, v] of Object.entries(raw.metrics)) raw.metricsF[k] = revive(v);
+  state.data = raw;
+  state.key = key;
+  $("blurb").textContent = raw.blurb;
+  $("fparams").textContent =
+    `${raw.preset}, ${(raw.param_count / 1e6).toFixed(2)}M parameters, ${raw.n_steps} steps`;
+  $("win").value = raw.win;
+  render();
+  manualReset();
+}
+
+function opts() {
+  return {
+    win: +$("win").value, gap: 1, mode: $("mode").value,
+    minVotes: +$("votes").value, voteWindow: +$("vwin").value,
+    requireConsensus: $("strict").checked,
+  };
+}
+
+function render() {
+  const d = state.data;
+  if (!d) return;
+  const o = opts();
+  const steps = d.steps;
+  const chosen = $("metric").value;
+  const specs = chosen === "auto" ? state.index.metrics : [chosen];
+  const res = bisectFirstBad(d.metricsF, steps, specs, o);
+  const loss = detectOnSeries(d.metricsF["loss"], steps, "loss", o);
+
+  const err = (v) => (d.truth === null || v === null || v === undefined)
+    ? "" : ` <span class="muted">(error <strong>${Math.abs(v - d.truth)}</strong> steps)</span>`;
+  const truthTxt = d.truth === null
+    ? '<span class="pill ok">none — this run is healthy</span>' : `<strong>${d.truth}</strong>`;
+  // A single metric crossing its threshold is not a finding.  Say so next to
+  // the number, not only in a footnote -- on the healthy control run this is
+  // the difference between "no fault" and an apparent false positive.
+  const weak = res.step !== null && res.votes < o.minVotes;
+  const fbTxt = res.step === null
+    ? '<span class="pill bad">no detection</span>'
+    : (weak
+        ? `<span class="muted" style="font-size:16px">${res.step}</span>
+           <span class="pill warn">low confidence — only ${res.votes} of
+           ${o.minVotes} required metrics agree</span>`
+        : `<strong style="font-size:18px">${res.step}</strong>` + err(res.step));
+  const lossTxt = loss.detected
+    ? `<strong>${loss.step}</strong>` + err(loss.step)
+    : '<span class="pill bad">never detected</span>';
+
+  $("result").innerHTML = `
+    <dl class="kv">
+      <dt>ground truth</dt><dd>${truthTxt}</dd>
+      <dt>Flashback bisect</dt><dd>${fbTxt}</dd>
+      <dt>loss curve alone</dt><dd>${lossTxt}</dd>
+      <dt>metric that fired first</dt>
+      <dd><code>${res.metric}</code> — z = ${fmt(res.z)}, threshold ${fmt(res.threshold)}</dd>
+      <dt>metrics that agree</dt>
+      <dd>${res.votes} of ${state.index.metrics.length} recorded
+        ${weak ? '<span class="muted">— below the ' + o.minVotes +
+                 ' required, so this is not a finding</span>' : ""}</dd>
+      <dt>cost</dt><dd>${res.indexReads.toLocaleString()} index reads,
+        <strong>${res.stateProbes} state reconstructions</strong></dd>
+      <dt>sketch size</dt><dd>${d.bytes_per_step} B/step
+        (${(d.total_bytes / 1024).toFixed(0)} KiB for the whole run)</dd>
+    </dl>
+    ${res.note ? `<p class="small muted" style="margin:10px 0 0">▸ ${res.note}</p>` : ""}`;
+
+  drawLoss(d, steps, res.step, loss.detected ? loss.step : null);
+
+  // Plot the metrics that voted for the ANSWER, strongest first -- not the
+  // globally earliest detections.  Across 124 correlated statistics a couple
+  // will always twitch early; charting those instead of the ones that actually
+  // localise the fault would make the picture argue against itself.
+  const inWindow = res.index === undefined ? []
+    : res.candidates.filter((c) => c.index >= res.index && c.index <= res.index + o.voteWindow);
+  const ranked = (inWindow.length ? inWindow : res.candidates)
+    .slice()
+    .sort((a, b) => (b.z === a.z ? 0 : (b.z > a.z ? 1 : -1)));
+  const picks = [];
+  for (const c of ranked) {
+    if (!picks.includes(c.spec)) picks.push(c.spec);
+    if (picks.length >= 4) break;
+  }
+  for (const f of ["grad_norm", "grad_max_abs", "update_max_abs", "sign_flip_rate"]) {
+    if (picks.length < 4 && !picks.includes(f)) picks.push(f);
+  }
+  drawZ(d, steps, picks, res.step, o);
+
+  const rows = [];
+  const seen = new Set();
+  const votedFor = new Set(inWindow.map((c) => c.spec));
+  for (const c of res.candidates) {
+    if (seen.has(c.spec)) continue;
+    seen.add(c.spec);
+    const tag = votedFor.has(c.spec)
+      ? '<span class="pill ok">voted</span>'
+      : '<span class="pill warn">isolated</span>';
+    rows.push(`<tr><td class="num">${c.step}</td><td class="num">${fmt(c.z)}</td>
+               <td>${tag}</td><td><code>${c.spec}</code></td></tr>`);
+    if (rows.length >= 14) break;
+  }
+  $("metrics").innerHTML =
+    `<thead><tr><th class="num">step</th><th class="num">z</th><th></th>
+      <th>metric</th></tr></thead>
+     <tbody>${rows.join("") || '<tr><td colspan="4" class="muted">nothing crossed its threshold</td></tr>'}</tbody>`;
+  $("metricsNote").innerHTML = votedFor.size
+    ? `<strong>${votedFor.size}</strong> metrics fired within ${o.voteWindow} steps of each
+       other and carried the answer (<span class="pill ok">voted</span>).
+       The <span class="pill warn">isolated</span> ones fired earlier but alone — across
+       ${state.index.metrics.length} correlated statistics a few always will, which is
+       exactly why a single loud metric is not allowed to decide.`
+    : "No metric reached consensus with any other.";
+
+  checkParity(res, loss);
+}
+
+/* --- charts ------------------------------------------------------------- */
+function chart(w, h, pad) {
+  return { w, h, pad, parts: [] };
+}
+function axes(c, xmin, xmax, ymin, ymax, ylog, ylabel) {
+  const { w, h, pad } = c;
+  c.x = (v) => pad.l + (v - xmin) / (xmax - xmin || 1) * (w - pad.l - pad.r);
+  const ly = (v) => ylog ? Math.log10(Math.max(v, ymin)) : v;
+  const a = ly(ymin), b = ly(ymax);
+  c.y = (v) => h - pad.b - (ly(v) - a) / ((b - a) || 1) * (h - pad.t - pad.b);
+  c.parts.push(`<line class="axis" x1="${pad.l}" y1="${h - pad.b}" x2="${w - pad.r}"
+                 y2="${h - pad.b}"/>`);
+  for (let k = 0; k <= 4; k++) {
+    const xv = xmin + (xmax - xmin) * k / 4;
+    c.parts.push(`<text class="tick" x="${c.x(xv)}" y="${h - pad.b + 14}"
+                   text-anchor="middle">${Math.round(xv)}</text>`);
+  }
+  const ticks = ylog
+    ? Array.from({ length: Math.min(7, Math.max(2, Math.ceil(b) - Math.floor(a) + 1)) },
+                 (_, i) => Math.pow(10, Math.floor(a) + i)).filter((v) => v <= ymax * 1.001)
+    : [ymin, (ymin + ymax) / 2, ymax];
+  for (const t of ticks) {
+    c.parts.push(`<line class="axis" x1="${pad.l}" y1="${c.y(t)}" x2="${w - pad.r}"
+                   y2="${c.y(t)}" stroke-opacity="0.35"/>`);
+    c.parts.push(`<text class="tick" x="${pad.l - 6}" y="${c.y(t) + 3}"
+                   text-anchor="end">${t >= 1000 || (t > 0 && t < 0.01)
+                     ? t.toExponential(0) : (+t.toPrecision(3))}</text>`);
+  }
+  if (ylabel) {
+    c.parts.push(`<text class="tick" x="12" y="${h / 2}" text-anchor="middle"
+                   transform="rotate(-90 12 ${h / 2})">${ylabel}</text>`);
+  }
+}
+function line(c, xs, ys, color, width = 1.1) {
+  let d = "", pen = false;
+  for (let i = 0; i < xs.length; i++) {
+    const v = ys[i];
+    if (!Number.isFinite(v) || v === null) { pen = false; continue; }
+    const X = c.x(xs[i]).toFixed(1), Y = c.y(v).toFixed(1);
+    d += (pen ? "L" : "M") + X + " " + Y + " ";
+    pen = true;
+  }
+  c.parts.push(`<path d="${d}" fill="none" stroke="${color}" stroke-width="${width}"/>`);
+}
+function vline(c, x, color, dash) {
+  if (x === null || x === undefined) return;
+  c.parts.push(`<line x1="${c.x(x)}" y1="${c.pad.t}" x2="${c.x(x)}"
+    y2="${c.h - c.pad.b}" stroke="${color}" stroke-width="2"
+    ${dash ? `stroke-dasharray="${dash}"` : ""} opacity="0.9"/>`);
+}
+function svg(c) {
+  return `<svg viewBox="0 0 ${c.w} ${c.h}" preserveAspectRatio="xMidYMid meet">
+          ${c.parts.join("")}</svg>`;
+}
+
+function drawLoss(d, steps, fb, lossStep) {
+  const ys = d.metricsF["loss"];
+  let lo = Infinity, hi = -Infinity;
+  for (const v of ys) if (Number.isFinite(v) && v > 0) { lo = Math.min(lo, v); hi = Math.max(hi, v); }
+  const c = chart(1000, 250, { l: 58, r: 16, t: 12, b: 26 });
+  axes(c, steps[0], steps[steps.length - 1], lo * 0.95, hi * 1.05, true, "loss (log)");
+  vline(c, d.truth, "var(--fg)", "7 5");
+  vline(c, lossStep, "var(--loss)", "2 4");
+  vline(c, fb, "var(--accent)");
+  line(c, steps, ys, "var(--loss)", 1.1);
+  $("lossChart").innerHTML = svg(c) + `<p class="small muted" style="margin:6px 0 0">
+    <span style="color:var(--fg)">▎</span> ground truth
+    &nbsp; <span style="color:var(--loss)">▎</span> where the loss curve notices
+    &nbsp; <span style="color:var(--accent)">▎</span> Flashback</p>`;
+}
+
+function drawZ(d, steps, picks, fb, o) {
+  const colors = ["var(--accent)", "#2ca02c", "#9467bd", "#17becf"];
+  const c = chart(1000, 300, { l: 58, r: 16, t: 12, b: 26 });
+  let hi = 10, thr = null;
+  const series = [];
+  picks.forEach((spec, i) => {
+    const raw = d.metricsF[spec];
+    if (!raw) return;
+    const zs = zSeries(raw, spec, o);
+    const plot = new Float64Array(zs.z.length);
+    for (let j = 0; j < zs.z.length; j++) {
+      plot[j] = zs.ok[j] ? (Number.isFinite(zs.z[j]) ? Math.max(zs.z[j], 1e-3) : 1e7) : NaN;
+      if (Number.isFinite(plot[j])) hi = Math.max(hi, plot[j]);
+    }
+    if (thr === null && Number.isFinite(zs.threshold)) thr = zs.threshold;
+    const det = detectOnSeries(raw, steps, spec, o);
+    series.push({ spec, plot, color: colors[i % colors.length], det });
+  });
+  axes(c, steps[0], steps[steps.length - 1], 1e-3, hi * 3, true, "robust z (log)");
+  if (thr !== null) {
+    c.parts.push(`<line class="axis" x1="${c.pad.l}" y1="${c.y(thr)}"
+      x2="${c.w - c.pad.r}" y2="${c.y(thr)}" stroke="var(--muted)" stroke-width="1.2"
+      stroke-dasharray="6 4"/>`);
+  }
+  vline(c, d.truth, "var(--fg)", "7 5");
+  for (const s of series) line(c, steps, s.plot, s.color, 1.0);
+  for (const s of series) {
+    if (!s.det.detected) continue;
+    const yv = Number.isFinite(s.det.z) ? Math.max(s.det.z, 1e-3) : 1e7;
+    c.parts.push(`<circle cx="${c.x(s.det.step)}" cy="${c.y(yv)}" r="5"
+      fill="${s.color}" stroke="var(--bg)" stroke-width="1.5"/>`);
+  }
+  $("zChart").innerHTML = svg(c);
+  $("zlegend").innerHTML = series.map((s) =>
+    `<span style="color:${s.color}">▎</span> <code>${s.spec}</code>` +
+    (s.det.detected ? ` → fires at <strong>${s.det.step}</strong>` : " (no detection)")
+  ).join(" &nbsp;&nbsp; ") +
+  (thr !== null ? ` &nbsp;&nbsp; <span class="muted">— — calibrated threshold ${fmt(thr)}</span>` : "");
+}
+
+/* --- manual bisect ------------------------------------------------------ */
+function manualReset() {
+  const d = state.data;
+  if (!d) return;
+  const spec = $("mmetric").value;
+  state.manual = { lo: 0, hi: d.n_steps - 1, probes: 0, log: [], spec,
+                   zs: zSeries(d.metricsF[spec], spec, opts()) };
+  $("mstep").value = Math.floor((state.manual.lo + state.manual.hi) / 2);
+  drawManual();
+}
+
+function manualProbe() {
+  const m = state.manual, d = state.data;
+  if (!m) return;
+  const i = Math.max(0, Math.min(d.n_steps - 1, +$("mstep").value));
+  const { bad, z } = prefixBad(m.zs, i);
+  m.probes++;
+  m.log.push({ i, bad, z });
+  if (bad) m.hi = i; else m.lo = Math.min(i + 1, m.hi);
+  $("mstep").value = Math.floor((m.lo + m.hi) / 2);
+  drawManual();
+}
+
+function drawManual() {
+  const m = state.manual, d = state.data;
+  const width = m.hi - m.lo + 1;
+  const ideal = Math.ceil(Math.log2(Math.max(2, d.n_steps)));
+  let html = `<dl class="kv">
+    <dt>bracket</dt><dd>steps <code>${m.lo} … ${m.hi}</code> (${width} wide)</dd>
+    <dt>probes used</dt><dd>${m.probes}
+      <span class="muted">— a binary search over ${d.n_steps} steps needs about ${ideal}</span></dd>`;
+  if (d.truth !== null) {
+    const inside = m.lo <= d.truth && d.truth <= m.hi;
+    html += `<dt>ground truth</dt><dd>${d.truth} ${inside
+      ? '<span class="pill ok">inside the bracket</span>'
+      : '<span class="pill warn">outside — a probe answered differently</span>'}</dd>`;
+  }
+  html += "</dl>";
+  if (width <= 1) {
+    const e = d.truth === null ? "" :
+      ` &nbsp; error <strong>${Math.abs(m.lo - d.truth)}</strong> steps`;
+    html += `<p style="margin:12px 0 0"><span class="pill ok">converged</span>
+             first bad step = <strong style="font-size:17px">${m.lo}</strong>${e}</p>`;
+  }
+  if (m.log.length) {
+    html += `<div class="scroll" style="margin-top:12px"><table>
+      <thead><tr><th class="num">probe</th><th class="num">step</th><th>verdict</th>
+      <th class="num">worst z so far</th></tr></thead><tbody>` +
+      m.log.map((r, k) => `<tr><td class="num">${k + 1}</td><td class="num">${r.i}</td>
+        <td>${r.bad ? '<span class="pill bad">BAD</span>' : '<span class="pill ok">ok</span>'}</td>
+        <td class="num">${fmt(r.z)}</td></tr>`).join("") + "</tbody></table></div>";
+  }
+  $("manual").innerHTML = html;
+}
+
+/* --- self-check against the Python reference ---------------------------- */
+function checkParity(res, loss) {
+  const d = state.data;
+  const o = opts();
+  const isDefault = o.win === d.win && o.mode === "diff" && o.minVotes === 3 &&
+                    o.voteWindow === 4 && !o.requireConsensus &&
+                    $("metric").value === "auto";
+  if (!isDefault) {
+    $("parity").innerHTML = `<span class="pill warn">settings changed</span>
+      Computed in-browser. The reference check below only applies at the default settings.`;
+    return;
+  }
+  const ref = d.reference;
+  const agreeStep = ref.consensus.step === res.step;
+  const agreeLoss = (ref.loss_only.step ?? null) === (loss.detected ? loss.step : null);
+  let mismatches = 0, checked = 0;
+  for (const [spec, r] of Object.entries(ref.per_metric)) {
+    const got = detectOnSeries(d.metricsF[spec], d.steps, spec, o);
+    checked++;
+    if (!got.detected || got.step !== r.step) mismatches++;
+  }
+  const ok = agreeStep && agreeLoss && mismatches === 0;
+  $("parity").innerHTML = ok
+    ? `<span class="pill ok">verified</span> This page's JavaScript detector reproduces
+       <code>flashback.bisect</code> exactly on this run: same consensus step
+       (${fmt(ref.consensus.step)}), same loss-curve verdict, and the same first-firing step
+       for all ${checked} metrics that fire. The Python answers are shipped in
+       <code>data/${d.key}.json</code> and checked on every render.`
+    : `<span class="pill bad">mismatch</span> The in-browser port disagrees with Python on
+       this run (${mismatches}/${checked} metrics differ${agreeStep ? "" : ", consensus step differs"}).
+       Trust <code>flashback.bisect</code>, not this page, and please
+       <a href="https://github.com/NagaYu/flashback/issues">file an issue</a>.`;
+}
+
+boot();
+</script>
+</body>
 </html>