# STOOP Lab v0

Decisions with rejected alternatives (runtime version pin, stills vs. video, the
lazy-load payload split, why the recorded-fallback GIF is fetched only on failure):
`docs/adr/ADR-0006-lab-v0-browser-runtime.md`.

`site/lab/index.html` — peregrine's real FP32 detector vs. its own INT8 quantization
(the nanostoop path), running side by side in the visitor's browser via ONNX Runtime
Web, on a bundled deterministic clip. Self-contained: no CDN, no external requests,
every dependency vendored under `vendor/`.

This is the **v0 slice** of TZ §3 Phase 3's protective spec. It is real and working —
not a mockup — but it is deliberately narrower than the Phase 3 spec's full scope. This
file is the honest accounting of both halves: what v0 actually does, verified, and what
v1 still owes.

## What works today (v0, verified 2026-08-20)

- **Real FP32 vs. real INT8, live, in-browser.** ONNX Runtime Web 1.18.0 (wasm EP)
  runs `peregrine-fp32.onnx` (peregrine's committed `models/best.onnx`, byte-identical,
  sha256-verified) and `peregrine-int8.onnx` (statically quantized by
  `scripts/quantize_lab_int8.py`, calibrated on 40 real frames from peregrine's own
  200-image calibration set) against the same input tensor, per frame.
- **Nanostoop's zeroing-bug lesson, actually applied, not just cited.** Static
  quantization at defaults silently zeroes every class score on this graph (its final
  `Concat` node forces the box branch and the class-score branch onto one shared
  int8 scale — see `nanostoop/nanostoop.py`'s `quantize_to_int8` docstring and
  `scripts/quantize_lab_int8.py`'s own docstring, which credits it). The fix
  (`op_types_to_quantize=["Conv"]`) is applied, and `tests/test_lab_page.py::
  test_lab_int8_model_used_the_zeroing_bug_fix` reads the quantizer's own provenance
  manifest to make sure a future edit can't silently drop it.
- **Accuracy-divergence only, latency from the matrix.** Per TZ §14.2: ORT-Web's
  WebGPU EP has incomplete INT8 coverage, so an in-tab FP32-vs-INT8 speed race is
  structurally invalid. This page never renders a browser-measured millisecond as a
  performance number — the "Latency" panel embeds real rows, verbatim, from
  `artifacts/matrix/target-matrix-2026-08-19.html`, each carrying its own hardware
  label and RECORDED badge.
- **Live agreement %, lost/gained boxes, mean IoU drift** — per-frame and pooled
  across a full 90-frame run. Decode/NMS/match logic (`lab-core.mjs`) is a direct port
  of `nanostoop.py`'s `decode`/`match_detections` and `scripts/fragility_derisk.py`'s
  `decode_yolov8`/`_class_aware_nms` — same constants (conf=0.25, NMS IoU=0.45, match
  IoU=0.50), not reinvented.
- **Default path is the bundled 90-frame clip**, not a webcam (TZ §3-Phase3-1):
  real, sequential warehouse stills (`IMG_0265_mp4`, frames 0–89, CC BY 4.0), resized
  and re-encoded — see `assets/clip/manifest.json` for full disclosure. Webcam is an
  explicit upgrade button (`getUserMedia`), gracefully declines with a visible message
  if denied or unavailable (tested: `NotAllowedError`/`NotSupportedError` both handled).
- **JPEG-quality degradation slider**, severity 0–5, the exact quality ladder from
  `src/stoop/degrade/params.py` (`90, 75, 60, 40, 25`), applied via canvas re-encode to
  the source frame **before** letterbox/preprocess, identically to both panels.
- **Fallback: WASM-only + hard styled failure screen.** If `ort.InferenceSession.create`
  throws for any reason (verified by blocking the model request in a real Playwright
  run), the page hides the live UI and shows a styled "your browser can't run this"
  screen with a real Playwright-recorded GIF of a working run — never an empty panel.
  The GIF (`assets/recorded-fallback.gif`, 2.8 MB) is fetched lazily, only on that
  failure path, so a normal successful visit never pays for its bytes.
- **Device strip** (LIVE badge): execution provider, WebGPU presence (detected via
  `navigator.gpu`, labeled "not used, v0" — see below), wasm thread count, wasm SIMD
  flag, user agent — all read from the actual running session, this tab, this load.
- **Gate Lab — the TZ's stated central interaction, built.** A device-budget slider tied to REAL
  measured numbers (`assets/gate-data.json`, copied verbatim from `artifacts/trt/`,
  `artifacts/coreml/`, and `artifacts/fragility/derisk-2026-08-19-nms070.json`'s clean condition) —
  drag the latency budget below the selected device's RECORDED p95 (or the quality budget below the
  clean-condition INT8 mAP50:95 drop) and the verdict flips **PASS → REFUSED**, naming the exact
  failed budget, the device, and an evidence link, mirroring
  `peregrine/src/peregrine/gates.py`'s `evaluate_release_gates()` semantics by hand (`lab-core.mjs`'s
  `evaluateLatencyGate`/`evaluateQualityGate`/`evaluateGateVerdict`). Lives **outside** `#lab-live` —
  it has no ONNX Runtime dependency, so it still renders on the `#lab-fallback` path.
- **Loupe v0 — failure gallery, built.** 6 of the 24 stratified overlays from the golden-v1 collapse
  investigation (`artifacts/golden/golden-v1-collapse-investigation-2026-08-20.md`), re-encoded to
  WebP (`site/lab/assets/loupe/`, ~248KB total vs. ~5.3MB at source), captions copied verbatim from
  that investigation's own visual audit, RECORDED badge.
- **"Copy my numbers", built.** Visitor's device strip + this frame's agreement numbers + the current
  Gate Lab config, as a markdown table to the clipboard (falls back to a selected `<textarea>` if
  `navigator.clipboard` is blocked — verified via a real headless run) and packed into the URL
  fragment (`#lab=frame:severity:device:latencyBudget:qualityBudget`), restored on load so a shared
  link reproduces the exact state.
- **Three-lane test coverage**, matching the slice spec's own requirement:
  1. `tests/test_lab_page.py` — `html.parser`-based structural checks (balanced tags,
     every local asset reference resolves on disk, no external request, family
     truth-badges present) + the real payload-budget arithmetic (below).
  2. `node --check` on both hand-written JS modules (same file, parametrized).
  3. `tests/test_lab_divergence.mjs` — an exec-stub against **real captured data**:
     `tests/fixtures/lab_raw_output_frame0.json` is the actual raw `(1,6,8400)` output
     of the actual vendored ONNX Runtime Web running the actual shipped FP32/INT8
     models against a real letterboxed clip frame, captured via Playwright. Decoding
     it through `lab-core.mjs` reproduces the exact numbers the live page shows for
     that frame (100% agreement, 0 lost, 0 gained, mean IoU drift 0.0384) — the two
     independently-run paths agree, not just each pass its own assertions.

## Payload — measured, not estimated (2026-08-20)

| Path | Bytes | MB |
|---|---:|---:|
| `peregrine-fp32.onnx` (eager) | 12,266,037 | 12.27 |
| ONNX Runtime Web 1.18.0, plain wasm build (`ort.wasm.min.js` + `ort-wasm.wasm`, eager) | 9,901,016 | 9.90 |
| Bundled clip, 90 frames + manifest (eager) | 2,349,732 | 2.35 |
| `index.html` + `lab-core.mjs` + `lab-app.js` + `matrix-latency.json` + `gate-data.json` (eager) | 70,325 | 0.07 |
| **Eager default-path total** | **24,587,110** | **24.59** |
| `peregrine-int8.onnx` + manifest (**lazy** — fetched only when a visitor requests a comparison) | 3,463,825 | 3.46 |
| `assets/loupe/*.webp` + manifest (**lazy** — native `loading="lazy"`, below the fold) | 237,684 | 0.24 |
| **Grand total if a visitor loads everything** | **28,288,619** | **28.29** |
| `assets/recorded-fallback.gif` (fetched **only** on an actual ORT-init failure) | 2,824,650 | 2.82 |

`tests/test_lab_page.py::test_lab_eager_payload_is_under_25mb` asserts the eager total
against the 25MB budget from real on-disk file sizes (not an estimate) and prints the
lazy/grand-total numbers alongside it.

**Read literally**, TZ §3-Phase3-1's "Суммарный payload < 25MB — проверь, lazy-load
INT8-лейна" is satisfied: the eager path is under budget by ~440KB, and the INT8 lane
is lazy-loaded specifically so it doesn't have to be — which is exactly what "lazy-load
the INT8 lane" as the stated mitigation implies. The **grand total across both lanes**
is honestly ~28MB, not ~25MB, if a visitor actually clicks through to a comparison.
Closing that gap for real (not by hiding it) is a v1 TODO below.

### Why ONNX Runtime Web 1.18.0, plain wasm, not something smaller or newer

- **Version pin, not carelessness**: 1.10.0's smaller `ort-wasm.wasm` (6.77 MB vs.
  1.18.0's 9.76 MB — would have saved ~3MB of the eager budget) was tried first and
  **failed to load the 12MB FP32 model** — `InferenceSession.create` threw a raw
  Emscripten-style abort (`32268480`, not an `Error` object), reproduced twice. 1.18.0
  loads and runs both models correctly (verified: real detections, non-zero class
  scores, matches the exec-stub fixture exactly). Newer builds (1.27+) consolidate to
  one universal wasm binary that's larger still (13.48 MB) and requires a JSEP variant
  for WebGPU that's 20–27 MB by itself — both worse for this budget. 1.18.0 is the
  smallest version verified to actually work, not the newest or the smallest in the
  abstract.
- **Plain wasm build, not SIMD/threaded**: SIMD+threaded wasm needs COOP/COEP
  cross-origin-isolation response headers to unlock `SharedArrayBuffer` — a real
  server-config dependency this "self-contained, works from a plain static host"
  slice deliberately avoids. The cost is speed, which this page doesn't claim anyway
  (see the latency-panel rationale above).

## What's TODO for v1 (not silently deferred — tracked here)

In priority order, matching the TZ's own "v0 vs. v1" split (§3-Phase3, closing note):

1. ~~**Device-budget gate slider → REFUSED verdict.**~~ **Built** (see "What works today"
   above — Gate Lab). Two independent budgets (device p95 latency, INT8 mAP50:95 drop on the
   clean condition), both against RECORDED numbers, verdict computed LIVE. Remaining gap: the
   real gate engine (`stoop.core.gate`) is still a `make gate` TODO stub at day 0 — this section
   ports `peregrine/src/peregrine/gates.py`'s semantics by hand into JS, it does not call a
   shared engine, so the two could in principle drift if either is edited without the other.
2. **Full degradation rack** beyond JPEG quality: motion blur, exposure/low-light,
   downscale-upscale, frame drop/stutter, rolling shutter, sensor noise —
   `src/stoop/degrade/ops.py` already implements all of these server-side; porting
   each to a canvas/WebGL shader for identical browser-side application is the
   remaining work.
3. **Real WebGPU compute path.** v0 detects `navigator.gpu` and labels it
   ("detected, not used, v0") but always executes via wasm. Wiring the JSEP WebGPU
   backend is blocked on the payload budget above (20–27 MB for the JSEP wasm binary
   alone) — likely needs a second, separately-fetched bundle gated behind an explicit
   "try WebGPU" opt-in, not the default path, to keep the eager budget intact.
4. **Close the ~28MB grand-total gap for real**, once WebGPU work reshuffles what's
   eager vs. lazy anyway: candidates are brotli-precompressed vendor assets served
   with the right `Content-Encoding` (wasm binaries and ONNX float weights both
   compress meaningfully), a smaller FP32 export, or trimming the bundled clip further.
5. ~~**Loupe failure-gallery** and **"copy my numbers"**~~ **Built** (see "What works
   today" above). Loupe is a fixed set of 6 pre-selected overlays, not a live query over the
   full 24-image stratified set or the full 600-image golden-v1 eval — expanding the picker is
   tracked here, not silently out of scope.
6. **Full fallback chain**: TZ §3-Phase3-4 specifies WebGPU → WASM-SIMD-threads →
   bundled clip → recorded GIF → local offline copy as a *hard* requirement. v0 ships
   WASM-only (no SIMD/threads, see above) → bundled clip → recorded GIF. The
   SIMD-threads rung and the local-offline-copy rung are not built.
7. **Web Worker / chunked inference** so a full 90-frame run doesn't block the main
   thread between frames (v0 yields via `setTimeout(0)` between frames, which keeps
   the progress bar responsive but each individual `session.run()` call is still
   synchronous on the main thread).
8. **Bilingual (EN/UK)** — DESIGN.md requires EN/UK "from day one" for user-facing
   surfaces; v0 is EN-only. Tracked here as a known gap, not silently dropped.

## Regenerating the assets

```
python scripts/quantize_lab_int8.py   # rebuilds peregrine-int8.onnx + its manifest
python scripts/build_lab_clip.py      # rebuilds the 90-frame bundled clip + manifest
```

Both require `peregrine/` checked out as a sibling directory (read-only dependency,
same convention as `scripts/fragility_derisk.py` and `scripts/build_synthetic_clip.py`
— see `docs/adr/ADR-0000-base-decision.md`), the `eval` extra installed
(`pip install -e .[eval]` — pulls in `onnxruntime`, `opencv-python-headless`), **plus**
`pip install onnx` separately: `onnxruntime.quantization` needs the ONNX protobuf
library to load and rewrite the graph, exactly as `nanostoop/README.md` documents for
the identical dependency, and `pyproject.toml`'s `eval` extra does not (yet) list it —
tracked here rather than silently worked around.

## Regenerating the test fixture

`tests/fixtures/lab_raw_output_frame0.json` is real captured ONNX Runtime Web output,
not hand-written. To regenerate it: serve `site/lab/` over HTTP (e.g.
`python3 -m http.server 8935 --directory site/lab`), then drive a headless browser
(Playwright + Chromium) to letterbox `assets/clip/frame-0000.jpg` to 640×640 on a
canvas exactly as `lab-app.js`'s `letterboxToTensor` does, run both sessions, and dump
`Array.from(output.data)` for each to JSON alongside the letterbox geometry used. The
capture script itself is not checked into this repo (it is a one-off harness, not
product code) — this paragraph is the reproduce-it-by-hand record per the project's
"no un-reproducible number" discipline.

## Regenerating the recorded-fallback GIF

Captured via Playwright's `recordVideo` context option against a real interaction
sequence (compare → scrub → adjust severity), then converted with:

```
ffmpeg -ss 7 -t 13 -i recording.webm \
  -vf "fps=6,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=128[p];[s1][p]paletteuse=dither=bayer" \
  -loop 0 recorded-fallback.gif
```