DaisyChain-Infer: project files + guide

Layer-sharded peer-to-peer inference. Each device downloads only its own
layers from the Hub via safetensors byte ranges, so no device holds the
whole model -- this pools memory, which DaisyChain-Train explicitly cannot.

Loads any Llama-style or GPT-2-style .safetensors repo. Verified INT8 units,
WGSL kernels and their exact gates carried over from DaisyChain-Web unchanged.
47 checks: bit-exact split equivalence (both families, with mutation checks),
wire protocol refusals, ring routing, safetensors/dtype/BPE loader.

GUIDE.md

@@ -0,0 +1,197 @@
+# ❄ DaisyChain-Infer — run one model across your devices
+
+Part of **DaisyChain** → https://huggingface.co/DaisyChainAI
+
+Point it at a **Hugging Face model**, open the page on two or more devices, and
+each one takes a slice of the model's layers. A token is produced by passing
+the hidden state around the ring, peer-to-peer over WebRTC. Every multiply runs
+through the same **verified INT8 units** as the rest of DaisyChain — WebGPU
+where available, the identical math on CPU where not.
+
+**This runs locally.** It is a project you clone and start on your own
+machines; there is no hosted deployment, and it is not a Space.
+
+```bash
+npm install
+npm start            # http://localhost:8788
+```
+
+Built from [DaisyChain-Train](https://huggingface.co/DaisyChainAI/DaisyChain-Train)
+and [DaisyChain-Web](https://huggingface.co/spaces/Quazim0t0/DaisyChain-Web) —
+the verified units, the WGSL kernels and their exact gates, and the WebRTC mesh
+are carried over unchanged.
+
+---
+
+## What is actually new here
+
+DaisyChain-Train is explicit about its limit: it **pools compute, not memory**.
+Every node holds a full replica, so a model bigger than one machine cannot be
+trained, and chaining five laptops does not give you one big machine.
+
+Inference is where that limit can be lifted, because a forward pass is a chain:
+layer `l` needs layer `l-1`'s **output**, never its **weights**.
+
+And because safetensors gives every tensor an exact byte range, **each device
+downloads only its own layers, straight from the Hub**. No device — not even
+the one driving the run — ever holds the whole model.
+
+|  | DaisyChain-Train | DaisyChain-Infer |
+|---|---|---|
+| What is split | the **batch** | the **model** |
+| What crosses the wire | gradients (whole-model sized, every step) | hidden states (`T×hidden` floats, per hop) |
+| Every device holds | the entire model | its own layers only |
+| Pools | compute | **memory** |
+| More devices means | more throughput | a **bigger model fits** |
+
+Running SmolLM-135M across three devices, each one downloads and holds
+135–243 MB of a 513 MB model. The activation moving between them is tens of KB.
+That asymmetry is why this works.
+
+## The ring
+
+```
+        ┌──────────────── hidden state (T×hidden f32) ─────────────┐
+        ▼                                                          │
+   ┌─────────┐        ┌─────────┐        ┌─────────┐               │
+   │ stage 0 │───────▶│ stage 1 │───────▶│ stage 2 │───────────────┘
+   │  HEAD   │        │ layers  │        │ layers  │
+   │ embed   │        │ 10–19   │        │ 20–29   │
+   │ layers  │        └─────────┘        └─────────┘
+   │  0–9    │
+   │ lm_head │◀── the returning state becomes the next token
+   └─────────┘
+```
+
+It is a **ring, not a line**, and weight tying forces that. When `lm_head` is
+tied to the embedding table — as it is in most small models — the largest
+tensor is needed at *both* ends: to embed the prompt and to produce the logits.
+Copying it to the last stage would hand back most of the memory just pooled, so
+the last stage returns its hidden state to the head, which owns the embedding
+**once** and does both ends.
+
+A consequence worth stating plainly: a middle stage receives layer weights
+only. It never gets the embedding table, so **it never sees the vocabulary** —
+it passes floats it cannot interpret.
+
+## Models it can run
+
+Any Hugging Face repo with `.safetensors` weights whose architecture is:
+
+- **Llama-style** — Llama, Mistral, Qwen2/2.5, SmolLM, TinyLlama
+  (RMSNorm, RoPE, grouped-query attention, SwiGLU)
+- **GPT-2-style** — LayerNorm with bias, learned positions, fused QKV, GELU
+
+Verified working end to end: `HuggingFaceTB/SmolLM-135M`,
+`openai-community/gpt2`, `Qwen/Qwen2.5-0.5B`.
+
+Anything else is **refused by name**, not approximated. Treating an unknown
+architecture as a known one produces fluent, confident, wrong output, which is
+the failure this project spends its verification budget making impossible. The
+same applies to tokenizers: byte-level BPE is implemented, and a
+SentencePiece/Unigram repo is rejected rather than tokenized approximately.
+
+Practical ceiling: weights are held as f32, so budget ~4 bytes per parameter
+across the group, and remember the head also carries the embedding table.
+
+## The token
+
+Gated or private models need a Hugging Face token. You are asked for one
+**once**, when a request actually fails for want of it — not up front.
+
+It is held in memory for that tab and nowhere else: **not** localStorage, not
+sessionStorage, not a cookie, not the URL, never written to the log, and
+**never sent to another device**. Each device is asked for its own, because
+each device fetches its own layers. Reloading the tab forgets it, and there is
+a *Forget token* button.
+
+## Verification
+
+The trainer's stack carries over unchanged: exact init gates on every kernel on
+every boot, the continuous random-cell audit at live shapes, and the
+cross-device kernel probe.
+
+But a pipeline moves the risk somewhere those instruments cannot reach:
+
+> In data-parallel **training**, every peer computes the same thing, so a
+> device with broken arithmetic shows up as a diverging replica. In a
+> **pipeline**, each stage computes something *different* and nobody else
+> repeats it. There is no replica to compare against. A wrong middle stage
+> produces a fluent, confident, wrong answer, and no consistency check
+> anywhere in the system would notice.
+
+Four things close that:
+
+1. **The kernel probe**, which matters more here than in the trainer — the same
+   seeded GEMM on every device, so it stays comparable even when the real work
+   is not. A stage whose probe disagrees is flagged before it is given layers.
+2. **Activation integrity hashes** on every hop, plus the model fingerprint, so
+   a stage still holding a slice of a *different* model refuses the hop instead
+   of silently mixing two models.
+3. **Structural validation** of every assignment — a plan that does not cover
+   each layer exactly once is refused, because it would still generate fluent
+   text with a layer missing.
+4. **The differential check** (tick *Verify*). The driving device re-runs the
+   identical prompt with every layer locally and compares token ids. It is the
+   only instrument that can show a distributed answer is *right* rather than
+   merely self-consistent.
+
+```bash
+npm test        # pipeline equivalence + wire protocol + loader
+```
+
+`test_pipeline.js` asserts that splitting changes **no bit**, for *both*
+architecture families, across several uneven splits including a head that keeps
+no layers. Two cases are mutation checks — a stage that silently drops a layer,
+and stages applied out of order — both of which *must* fail the comparison.
+Without those, a test where both sides call the same code proves nothing.
+
+This was also confirmed against a real model: SmolLM-135M's 30 layers split
+`[10,10,10]`, `[1,14,15]`, `[0,15,15]` and `[5,5,5,5,5,5]` all produced token
+sequences identical to the single-device run.
+
+`test_loader.js` builds safetensors files and reads them back, checks BF16/F16
+widening is exact (including subnormals and signed zero), and round-trips the
+BPE tokenizer. `test_wire.js` round-trips the protocol and refuses the
+malformed messages that would otherwise produce plausible wrong answers — a
+plan with a gap, a crafted repo id, a one-ulp flip deep in an activation, a
+`-0` flipped to `+0`.
+
+### One bug, and what it cost to find
+
+The first live two-device run stalled. The head is both stage 0 *and* the
+ring's terminus, so an activation addressed to index 0 meant "start the lap"
+outbound and "the lap is finished" inbound. The head read the return leg as its
+own turn, re-ran its own layers, forwarded again, and the lap never closed.
+
+Every number was correct. Every message round-tripped. **Neither test suite
+could see it** — the pipeline test calls the stages in order itself, and the
+codec test only checks bytes. The defect lived in the *route*, precisely the
+category DaisyChain-Web's own self-corpus writeup identified as needing
+different instruments rather than better oracles. The fix gave the return leg
+its own address, and the routing decision moved out of the event handler into a
+pure function so `walkLap` in `test_wire.js` can walk a lap and assert it
+visits each stage once and terminates. That test fails against the old
+behaviour; it was checked.
+
+## Honest limits
+
+- **Latency, not bandwidth, is the cost.** Every token pays one round trip per
+  stage. More stages buy capacity, not speed — expect tokens/sec to *fall* as
+  you add devices.
+- **No KV cache.** Every token re-runs the whole window, which is also what
+  keeps the split bit-comparable against an unsplit run. Context length is the
+  dominant per-token cost.
+- **f32 in memory.** Weights are widened from F16/BF16 on load, so a stage
+  costs 4 bytes per parameter it holds.
+- **The head is a single point of failure**, and a stage that drops stalls the
+  ring; press Generate again to re-plan around whoever is still connected.
+- **No authentication of activations.** A malicious stage that runs correct
+  math but returns a crafted activation is not caught by any of this — the
+  verification proves the *computation* is right on every honest device. Peers
+  see each other's IPs, and the head sees your prompt. Run rings with people
+  you trust.
+
+---
+
+**License:** MIT · **Author:** Dean Byrne (Quazim0t0) · **Org:** DaisyChainAI

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dean Byrne (Quazim0t0) / DaisyChainAI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,247 @@
+---
+license: mit
+tags:
+  - distributed-inference
+  - pipeline-parallel
+  - webgpu
+  - webrtc
+  - int8
+  - old-hardware
+---
+
+# ❄ DaisyChain-Infer — run one model across several devices
+
+**Part of DaisyChain on 🤗 Hugging Face → https://huggingface.co/DaisyChainAI**
+**Live Space:** https://huggingface.co/spaces/Quazim0t0/DaisyChain-Infer
+
+---
+
+> **In plain terms:** point it at a Hugging Face model, open the page on two or
+> more devices, and each one holds only a **slice of the model's layers**. A
+> token is produced by passing the hidden state around the ring, peer-to-peer.
+> The group can run a model that **no single device could hold**.
+> Before you rely on it, read [Honest limits](#honest-limits).
+
+This repo is the **project and the guide**. Clone it and run it on your own
+machines:
+
+```bash
+npm install
+npm start            # http://localhost:8788
+npm test             # 47 checks: pipeline equivalence, wire protocol, loader
+```
+
+Full walkthrough: **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** ·
+Internals: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** ·
+The guide as one page: **[GUIDE.md](GUIDE.md)**
+
+---
+
+## What this adds to DaisyChain
+
+DaisyChain-Train is explicit about its limit: it **pools compute, not memory**.
+Every node holds a full replica, so a model bigger than one machine cannot be
+trained, and chaining five laptops does not give you one big machine.
+
+Inference is where that limit can be lifted, because a forward pass is a chain:
+layer `l` needs layer `l-1`'s **output**, never its **weights**. So the layers
+live on different machines and the activation travels instead.
+
+And because safetensors gives every tensor an exact byte range, **each device
+fetches only its own layers straight from the Hub**. No device — not even the
+one driving the run — ever holds the whole model. That is what makes the pooling
+real rather than a redistribution of something one machine already had to load.
+
+|  | DaisyChain-Train | DaisyChain-Infer |
+|---|---|---|
+| What is split | the **batch** | the **model** |
+| What crosses the wire | gradients (whole-model sized, every step) | hidden states (`T×hidden` floats, per hop) |
+| Every device holds | the entire model | its own layers only |
+| Pools | compute | **memory** |
+| More devices means | more throughput | a **bigger model fits** |
+
+Running SmolLM-135M across three devices, each downloads and holds 135–243 MB
+of a 513 MB model, and the activation moving between them is tens of KB. That
+asymmetry is why this works.
+
+## The ring
+
+```
+        ┌──────────────── hidden state (T×hidden f32) ─────────────┐
+        ▼                                                          │
+   ┌─────────┐        ┌─────────┐        ┌─────────┐               │
+   │ stage 0 │───────▶│ stage 1 │───────▶│ stage 2 │───────────────┘
+   │  HEAD   │        │ layers  │        │ layers  │
+   │ embed   │        │ 10–19   │        │ 20–29   │
+   │ layers  │        └─────────┘        └─────────┘
+   │  0–9    │
+   │ lm_head │◀── the returning state becomes the next token
+   └─────────┘
+```
+
+It is a **ring, not a line**, and weight tying forces that. When `lm_head` is
+tied to the embedding table — as it is in most small models — the largest tensor
+is needed at *both* ends: to embed the prompt and to produce the logits. Copying
+it to the last stage would hand back most of the memory just pooled, so the last
+stage returns its hidden state to the head, which owns the embedding **once**.
+
+A consequence worth stating plainly: a middle stage receives layer weights only.
+It never gets the embedding table, so **it never sees the vocabulary** — it
+passes floats it cannot interpret.
+
+## Models it can run
+
+Any Hugging Face repo with `.safetensors` weights whose architecture is:
+
+- **Llama-style** — Llama, Mistral, Qwen2/2.5, SmolLM, TinyLlama
+  (RMSNorm, RoPE, grouped-query attention, SwiGLU)
+- **GPT-2-style** — LayerNorm with bias, learned positions, fused QKV, GELU
+
+Verified end to end: `HuggingFaceTB/SmolLM-135M`, `openai-community/gpt2`,
+`Qwen/Qwen2.5-0.5B`.
+
+Anything else is **refused by name**, not approximated. Treating an unknown
+architecture as a known one produces fluent, confident, wrong output — the
+failure this project spends its verification budget making impossible. The same
+applies to tokenizers: byte-level BPE is implemented, and a SentencePiece or
+WordPiece repo is rejected rather than tokenized approximately.
+
+Two details that are silent when wrong, and so are decided by evidence rather
+than assumption:
+
+- **Weight layout.** `torch.nn.Linear` stores `(out, in)`; GPT-2's `Conv1D`
+  stores `(in, out)`, which is already the `k×n` the GEMM wants. A wrong
+  transpose does not throw.
+- **Bias presence.** Qwen2.5 ships q/k/v biases and SmolLM does not, and neither
+  says so in `config.json`. Bias is decided by what the weight file contains.
+
+## Credentials
+
+Public models need nothing. For gated or private ones, the **local** build asks
+for a read token once, when a request actually fails for want of it — held in
+memory for that tab only, never written to storage, never logged, never put in a
+URL, and **never sent to another device** (each device authenticates itself,
+because each fetches its own layers).
+
+The hosted Space instead offers **Sign in with Hugging Face** and has no
+paste-a-token box at all, because typing a personal access token into a page you
+do not control is a bad habit even when the code is honest.
+
+## Verification
+
+The trainer's stack carries over unchanged: exact init gates on every kernel on
+every boot, the continuous random-cell audit at live shapes, and the cross-device
+kernel probe.
+
+But a pipeline moves the risk somewhere those instruments cannot reach:
+
+> In data-parallel **training**, every peer computes the same thing, so a device
+> with broken arithmetic shows up as a diverging replica. In a **pipeline**, each
+> stage computes something *different* and nobody else repeats it. There is no
+> replica to compare against. A wrong middle stage produces a fluent, confident,
+> wrong answer, and no consistency check anywhere in the system would notice.
+
+Four things close that:
+
+1. **The kernel probe**, which matters more here than in the trainer — the same
+   seeded GEMM on every device, so it stays comparable even when the real work is
+   not. A stage whose probe disagrees is flagged before it is given layers.
+2. **Activation integrity hashes** on every hop, plus the model fingerprint, so a
+   stage still holding a slice of a *different* model refuses the hop instead of
+   silently mixing two models.
+3. **Structural validation** of every assignment — a plan that does not cover
+   each layer exactly once is refused, because it would still generate fluent
+   text with a layer missing.
+4. **The differential check** — the head re-running the identical prompt with
+   every layer locally and comparing token ids. The only instrument that can show
+   a distributed answer is *right* rather than merely self-consistent.
+
+`test_pipeline.js` asserts that splitting changes **no bit**, for both
+architecture families, across several uneven splits including a head that keeps
+no layers. Two cases are mutation checks — a stage that silently drops a layer,
+and stages applied out of order — both of which *must* fail the comparison.
+Without those, a test where both sides call the same code proves nothing.
+
+Confirmed on a real model too: SmolLM-135M's 30 layers split `[10,10,10]`,
+`[1,14,15]`, `[0,15,15]` and `[5,5,5,5,5,5]` all produced token sequences
+identical to the single-device run.
+
+`test_loader.js` builds safetensors files and reads them back, checks BF16/F16
+widening is exact (including subnormals and signed zero), and round-trips the BPE
+tokenizer. `test_wire.js` round-trips the protocol and refuses the malformed
+messages that would otherwise produce plausible wrong answers — a plan with a
+gap, a crafted repo id, a one-ulp flip deep in an activation, a `-0` flipped to
+`+0`.
+
+### One bug, and what it cost to find
+
+The first live two-device run stalled. The head is both stage 0 *and* the ring's
+terminus, so an activation addressed to index 0 meant "start the lap" outbound
+and "the lap is finished" inbound. The head read the return leg as its own turn,
+re-ran its own layers, forwarded again, and the lap never closed.
+
+Every number was correct. Every message round-tripped. **Neither test suite could
+see it** — the pipeline test calls the stages in order itself, and the codec test
+only checks bytes. The defect lived in the *route*, precisely the category
+DaisyChain-Web's own self-corpus writeup identified as needing different
+instruments rather than better oracles. The fix gave the return leg its own
+address, and the routing decision moved out of the event handler into a pure
+function so `walkLap` in `test_wire.js` can walk a lap and assert it visits each
+stage once and terminates. That test fails against the old behaviour; it was
+checked.
+
+## Layout
+
+```
+server.js                 signaling + static host + OAuth code exchange
+public/safetensors.js     header parsing, exact BF16/F16 widening, range coalescing
+public/hf.js              Hub client: range reads, gated repos, token redaction
+public/arch.js            config.json -> normalized spec; per-family tensor names
+public/tokenizer.js       byte-level BPE from the repo's own tokenizer.json
+public/shard.js           the plan, per-stage tensor sets, weight-layout handling
+public/infer.js           forward pass: embed / runLayers / readout
+public/wire.js            binary protocol + routing, as pure functions
+public/app.js             WebRTC mesh, assignments, credentials, token loop
+public/verified_core.js   the verified INT8 units      (unchanged from DaisyChain-Web)
+public/webgpu.js          WGSL kernels + exact gates   (unchanged)
+public/*.bin              the units as lookup tables   (unchanged)
+test_pipeline.js          split vs unsplit, bit-exact, both families
+test_wire.js              protocol round-trips, refusals, ring routing
+test_loader.js            safetensors, dtype widening, BPE
+docs/                     GETTING_STARTED, ARCHITECTURE
+```
+
+## Honest limits
+
+- **Latency, not bandwidth, is the cost.** Every token pays one round trip per
+  stage. More stages buy capacity, not speed — expect tokens/sec to *fall* as you
+  add devices.
+- **No KV cache.** Every token re-runs the whole window, which is also what keeps
+  the split bit-comparable against an unsplit run.
+- **f32 in memory.** Weights are widened from F16/BF16 on load, so a stage costs
+  4 bytes per parameter it holds.
+- **The head is a single point of failure**, and a stage that drops stalls the
+  ring; press Generate again to re-plan around whoever is still connected.
+- **No authentication of activations.** A malicious stage that runs correct math
+  but returns a crafted activation is not caught by any of this. Peers see each
+  other's IPs, and the head sees your prompt. Ring with people you trust.
+- **Proof of concept**, not a hardened service.
+
+---
+
+**License:** MIT · **Author:** Dean Byrne (Quazim0t0) · **Org:** DaisyChainAI
+
+Built on [DaisyChain-Train](https://huggingface.co/DaisyChainAI/DaisyChain-Train)
+and [DaisyChain-Web](https://huggingface.co/spaces/Quazim0t0/DaisyChain-Web).
+
+## Citation
+
+```bibtex
+@misc{byrne2026daisychaininfer,
+  title        = {DaisyChain-Infer: Layer-Sharded Peer-to-Peer Inference in the Browser},
+  author       = {Byrne, Dean (Quazim0t0)},
+  year         = {2026},
+  howpublished = {\url{https://huggingface.co/DaisyChainAI/DaisyChain-Infer}},
+  note         = {Run one model across several devices; pools memory, not just compute}
+}
+```

docs/ARCHITECTURE.md

@@ -0,0 +1,160 @@
+# Architecture
+
+How a page load becomes one stage of a model, and how a token gets produced by
+several machines that each hold only part of it.
+
+## The pieces
+
+| File | Role |
+|---|---|
+| `server.js` | WebSocket **signaling** + static hosting. Never sees a weight, an activation, a prompt, or a token. |
+| `public/safetensors.js` | header parsing, dtype widening, byte-range coalescing. |
+| `public/hf.js` | the Hub client — range reads, gated-repo handling, token redaction. |
+| `public/arch.js` | `config.json` -> a normalized spec, and the tensor names to fetch. |
+| `public/tokenizer.js` | byte-level BPE, read from the repo's own `tokenizer.json`. |
+| `public/shard.js` | the **plan**, per-stage tensor sets, and weight-layout handling. |
+| `public/infer.js` | the forward pass, split into `embed` / `runLayers` / `readout`. |
+| `public/wire.js` | the binary protocol and the routing decisions, as pure functions. |
+| `public/app.js` | the WebRTC mesh, assignments, the token prompt, and the token loop. |
+| `public/verified_core.js` | the **verified INT8 units** — unchanged from DaisyChain-Web. |
+| `public/webgpu.js` | the WGSL kernels and their **exact init gates** — unchanged. |
+| `public/*.bin` | the units as lookup tables — unchanged. |
+
+The last three being unchanged is deliberate. The arithmetic is copied, not
+reimplemented, which is what makes the split checkable against the unsplit path
+with `!==` instead of a tolerance.
+
+## Reading a model without downloading it
+
+A safetensors file is `[u64 headerLen][JSON header][tensor bytes]`, and the
+header gives every tensor's exact byte range. So loading a model here means
+fetching `config.json`, the tokenizer, and the weight *headers* — a few tens of
+KB regardless of whether the model is 100 MB or 100 GB. After that, every
+tensor's location is known and nothing else has been transferred.
+
+`arch.js` turns the config into a normalized spec:
+
+```
+family, layers, hidden, heads, kvHeads, headDim, inter, vocab, maxPos,
+norm ('rms'|'ln'), normEps, act ('silu'|'gelu'), gated, rope, ropeTheta,
+tie, qkvFused, bias, weightLayout ('in_out'|'out_in')
+```
+
+Everything downstream works off that spec and never asks which family a model
+came from. Unknown architectures are refused by name — silently treating one
+block shape as another produces confident nonsense.
+
+Two details that are silent when wrong, and so are decided by evidence rather
+than assumption:
+
+- **Weight layout.** `torch.nn.Linear` stores `(out, in)`; GPT-2's `Conv1D`
+  stores `(in, out)`, which is already the `k x n` the GEMM wants. A wrong
+  transpose does not throw. The layout comes from the spec and is applied once,
+  at load.
+- **Bias presence.** Qwen2.5 ships q/k/v biases and SmolLM does not, and
+  neither says so in `config.json`. Bias is therefore decided by what the
+  weight file actually contains, not by a config flag.
+
+## The plan
+
+Whoever loads the model is the **head**: it owns the embedding table and so
+does both ends of the pass. It orders devices itself-first, then by peer id,
+and apportions blocks by **measured** capacity — each device times a real GEMM
+through its own live kernel and reports GEMMs/sec, the same self-calibrating
+idea as `cluster.py`'s `capacity_score`, except what is being balanced is
+layers per device rather than batch per device.
+
+Apportionment is largest-remainder, so it is a pure function of the capacity
+report: every device derives the same plan from the same inputs, and the plan
+never has to be trusted, only compared. A device that ends up with zero blocks
+is dropped from the ring unless it is the head — an empty hop is pure latency.
+
+`unpackAssign` refuses any plan whose stages do not cover every layer exactly
+once, and any plan whose stage 0 is not the head. A gap there would not throw
+at runtime; it would generate fluent text with a layer missing. The repo id is
+validated too — it is interpolated into a Hub URL, so a peer must not be able
+to point this device at an arbitrary path.
+
+## Fetching a slice
+
+Each device receives an assignment (model id, revision, spec, plan, its own
+layer range) and then fetches **its own tensors itself**, with its own
+credentials. Weights never travel between peers, which means:
+
+- no device needs to hold the whole model, not even the head;
+- a token is never sent over the wire — each device is prompted separately;
+- adjacent byte ranges are coalesced, so a stage costs roughly one request
+  rather than nine per layer.
+
+## One token
+
+1. The **head** embeds the last `T` tokens (plus learned positions, for GPT-2)
+   and runs its own layers.
+2. It sends the hidden state to stage 1. Each stage runs its layers and passes
+   the result on.
+3. The **last** stage sends the state back to the head, addressed `RETURN`.
+4. The head applies the final norm and `lm_head` — for the last position only,
+   which at a 150k-token vocabulary turns the largest GEMM in the model into a
+   single row — picks a token, and starts the next lap.
+
+The head is both stage 0 and the terminus, so the return leg has its own
+address rather than a stage index. Reading it as "stage 0, your turn" was a
+real bug: the head re-ran its own layers and the lap never closed.
+
+## The wire
+
+All messages are binary. Sentinels continue DaisyChain-Web's numbering (it uses
+−2…−8) so a client pointed at the wrong server sees an unknown tag rather than
+a valid-looking message of the wrong kind.
+
+| Sentinel | Message |
+|---|---|
+| `-5` | fragment — large messages chunked at 48 KB |
+| `-20` | hello: measured capacity, kernel probe hash, backend |
+| `-21` | assignment — model id + your layer range (**no weights**) |
+| `-22` | ready — this stage has fetched and loaded its layers |
+| `-23` | activation hop |
+| `-24` | token emitted (so every device can watch the output) |
+| `-25` | run finished |
+
+Activation format:
+`[i32 ACT][i32 seq][i32 tokenIdx][i32 nextIndex][u32 actHash][u32 modelHash][f32 hidden]`
+
+The two hashes answer different questions. `actHash` asks whether the payload
+arrived intact. `modelHash` asks whether this activation belongs to the model I
+hold a slice of — not hypothetical, since reloading the head with a different
+model leaves stages out there still holding the old one. It is derived from the
+repo id, revision and tensor index rather than the weights, because no device
+reads all of them.
+
+## Backends
+
+Unchanged from DaisyChain-Web: DP4A hardware int8 dot → LUT compute shader →
+CPU mirror, each **exact-gated at init** and demoted on any mismatch. The CPU
+mirror is not an approximation — it produces the same bits, which is what lets
+a phone on CPU and a desktop on WebGPU sit in the same ring.
+
+Attention runs per head through the same verified block GEMM, because real
+models have head geometries (grouped-query, non-uniform head dims) that the
+trainer's fused uniform-head kernels do not cover. Every product still goes
+through the units.
+
+There is no plain-float path. If the units fail to load, the device does not
+compute.
+
+## What the pipeline changes about verification
+
+In data-parallel training every peer computes the same thing, so broken
+arithmetic surfaces as a diverging replica. In a pipeline each stage computes
+something different and nobody repeats it — there is no replica to compare
+against, and a wrong middle stage yields a confident wrong answer.
+
+What still works: the **kernel probe** (same seeded GEMM everywhere, so it is
+comparable even when the real work is not), the init gates, and the live-shape
+audit — all of which run per device regardless of what that device is computing.
+
+What is new: activation hashes, the model fingerprint on every hop, and the
+**differential check** — the head fetching the whole model and re-running the
+prompt locally, then comparing token ids. It is the only instrument that can
+prove a distributed answer right rather than merely self-consistent, and it is
+offered rather than assumed because it needs a model one device can hold.

docs/GETTING_STARTED.md

@@ -0,0 +1,152 @@
+# Getting started with DaisyChain-Infer
+
+This is a local project. There is no hosted version — you clone it and run it
+on your own machines.
+
+## Run the server
+
+```bash
+npm install
+npm start            # http://localhost:8788
+```
+
+Open it in two tabs to try the ring on one machine, or on two devices to try it
+for real.
+
+> **HTTPS matters.** WebGPU and cross-device WebRTC need a *secure context*:
+> `localhost` or HTTPS. Plain `http://192.168.x.x` from another device will not
+> get WebGPU and may not connect at all. For real multi-device runs on your own
+> network, put it behind a tunnel (`cloudflared`, `ngrok`) or a local TLS
+> reverse proxy.
+
+## Pick a model
+
+Type any Hugging Face repo id — `owner/name` — and press **Load**.
+
+Works with `.safetensors` repos whose architecture is:
+
+- **Llama-style**: Llama, Mistral, Qwen2/2.5, SmolLM, TinyLlama
+- **GPT-2-style**: GPT-2 and close relatives
+
+Good ones to start with:
+
+| Repo | Size | Notes |
+|---|---|---|
+| `HuggingFaceTB/SmolLM-135M` | 513 MB f32 | 30 layers — splits nicely |
+| `openai-community/gpt2` | 523 MB f32 | the GPT-2 path |
+| `Qwen/Qwen2.5-0.5B` | 942 MB f32 | GQA 14/2, and it ships QKV biases |
+
+Loading reads only `config.json`, `tokenizer.json` and the weight **headers** —
+a few tens of KB, whatever the model's size. No weights move until you press
+Generate, and then each device fetches only its own layers.
+
+Weights are held as **f32**, so budget ~4 bytes per parameter across the group.
+The ring plan shows exactly how many MB each device will download and hold.
+
+An unsupported architecture or tokenizer is refused with a message naming what
+it found. That is deliberate: approximating one would produce fluent, confident,
+wrong text.
+
+## Gated or private models
+
+You are asked for a Hugging Face token **once**, and only when a request
+actually fails for want of one. Create a **read** token at
+huggingface.co/settings/tokens.
+
+The token is held in memory for that tab and nowhere else — not localStorage,
+not sessionStorage, not a cookie, not the URL, never logged, and **never sent
+to another device**. Each device is prompted for its own, because each device
+downloads its own layers. Reloading the tab forgets it, and *Forget token*
+clears it immediately.
+
+For a gated model, accept its licence on the model page first — a token alone
+will not get past a licence you have not accepted.
+
+## Rooms
+
+Devices on one network group automatically (by public IP, Snapdrop-style). To
+include devices on other networks, everyone opens:
+
+```
+https://<host>/?room=MY-SECRET-CODE
+```
+
+The first person in is the **host** and approves each device individually.
+
+## Run it
+
+1. Wait until the devices see each other in the peer list.
+2. On **one** device, load the model. That device becomes the **head**: it
+   holds the embedding table, embeds your prompt, and turns the returning
+   hidden state back into words.
+3. Check the **ring plan** — who holds which layers, and how much each will
+   download.
+4. Type a prompt and press **Generate**. Each device fetches its layers (this
+   takes a moment the first time), reports ready, and the ring starts.
+
+| Setting | Default | What it does |
+|---|---|---|
+| Tokens | 60 | how many to generate |
+| Context length | 64 | window size; the main cost per token (there is no KV cache) |
+| Temperature ÷100 | 0 | 0 = greedy, deterministic and therefore checkable |
+| Seed | 1234 | drives sampling above temperature 0, so runs stay reproducible |
+| Verify | off | afterwards, re-run with every layer here and compare |
+
+Every device shows the token stream as it arrives — including ones holding a
+few layers and no vocabulary.
+
+## Reading the numbers
+
+- **tokens/sec** — the whole ring's rate. Expect it to *fall* as you add
+  stages: each one adds a round trip per token. More stages buy capacity, not
+  speed.
+- **ring hops** — stages × tokens.
+- **kernel probe** (in the log) — the same number on every honest device,
+  whatever its backend. A peer reporting a different one is computing different
+  arithmetic, and the log says so.
+- **my slice** — which layers this device holds and how much memory they take.
+
+## Verify
+
+Tick **Verify** before generating. Afterwards the head downloads the whole
+model and re-runs the identical prompt locally, then compares token ids:
+
+```
+VERIFIED: the distributed run and the single-device run produced identical token ids.
+```
+
+In a pipeline nothing recomputes anything, so this is the only check that can
+show a distributed answer is *right* rather than merely self-consistent. It
+needs a model one device can hold, which is why it is optional.
+
+Without a browser:
+
+```bash
+npm test
+```
+
+## When it goes wrong
+
+- **"the ring stalled at token N"** — a stage went quiet. Press Generate again
+  to re-plan around whoever is still connected.
+- **"unsupported architecture"** — the model is not Llama-style or
+  GPT-2-style.
+- **"tokenizer type … is not supported"** — the repo uses SentencePiece or
+  WordPiece; only byte-level BPE is implemented.
+- **401 / 403** — the model needs a token, or the token lacks access. For
+  gated repos, accept the licence on the model page first.
+- **"the server ignored the byte range"** — the whole file came back instead of
+  a slice; refused rather than accepted, since that defeats the point.
+- **"REFUSED activation … belongs to model X"** — a stage still holds a slice
+  of a previous model. Reload that device.
+- **"⚠ … disagrees with this device's kernel probe"** — that device's
+  arithmetic differs from yours. Do not give it layers.
+- **out of memory** — the stage's slice does not fit. Add devices, or pick a
+  smaller model; the plan shows the per-device cost before you start.
+
+## More
+
+- [ARCHITECTURE.md](ARCHITECTURE.md) — the ring, the plan, the wire protocol.
+- The parent projects:
+  [DaisyChain-Train](https://huggingface.co/DaisyChainAI/DaisyChain-Train) ·
+  [DaisyChain-Web](https://huggingface.co/spaces/Quazim0t0/DaisyChain-Web)

package.json

@@ -0,0 +1,16 @@
+{
+  "name": "daisychain-infer",
+  "version": "1.0.0",
+  "description": "Run one Hugging Face model across several devices — layer-sharded pipeline inference in the browser, peer-to-peer over WebRTC, computed through verified INT8 units. Runs locally.",
+  "private": true,
+  "main": "server.js",
+  "scripts": {
+    "start": "node server.js",
+    "test": "node test_pipeline.js && node test_wire.js && node test_loader.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "license": "MIT",
+  "author": "Dean Byrne (Quazim0t0)"
+}

public/app.js

@@ -0,0 +1,770 @@
+// DaisyChain-Infer client: connect P2P, take a slice of a model straight from
+// the Hub, and run one token loop around the ring.
+//
+// The mesh (signaling, WebRTC, fragmentation, rooms, reconnect) is
+// DaisyChain-Web's, because those are the parts already proven against real
+// phones and real NATs. Everything from "the model" down is new.
+"use strict";
+
+const STUN = [
+  { urls: "stun:stun.l.google.com:19302" },
+  { urls: "turn:openrelay.metered.ca:80", username: "openrelayproject", credential: "openrelayproject" },
+  { urls: "turn:openrelay.metered.ca:443", username: "openrelayproject", credential: "openrelayproject" },
+  { urls: "turns:openrelay.metered.ca:443?transport=tcp", username: "openrelayproject", credential: "openrelayproject" },
+];
+let rtcConfig = { iceServers: STUN };
+
+const ui = {};
+for (const id of ["status", "backend", "me", "peers", "log", "requests", "roomInfo", "roomCode",
+                  "copyLink", "model", "tokenizer", "plan", "myShard", "prompt", "genBtn",
+                  "stopBtn", "out", "tps", "tokcount", "hops", "temp", "vtemp", "ntok", "vntok",
+                  "seed", "verify", "verifyRow", "ringState", "repo", "revision", "loadRepo",
+                  "modelState", "ctxLen", "vctxLen", "tokenState", "clearToken",
+                  "tokModal", "tokInput", "tokOk", "tokCancel", "tokWhy",
+                  "tokPasteRow", "tokSignIn", "tokSignInBtn",
+                  "lobby", "createRoom", "joinRoom", "joinCode"])
+  ui[id] = document.getElementById(id);
+
+function log(m) { ui.log.textContent = `${new Date().toLocaleTimeString()}  ${redact(m)}\n` + ui.log.textContent; }
+function setStatus(s) { ui.status.textContent = s; }
+
+// ---- the token --------------------------------------------------------------
+// Held in a closure variable and nowhere else. Not localStorage, not
+// sessionStorage, not a cookie, not the URL, not the log, and never on the
+// wire — each device authenticates itself, so a peer never needs anyone
+// else's credentials. Reloading the page is meant to lose it.
+let hfToken = null, tokenSource = "";
+let oauthAvailable = false;
+function redact(s) { return hfToken ? String(s).split(hfToken).join("hf_***") : String(s); }
+function haveToken() { return !!hfToken; }
+function setToken(t, source) {
+  hfToken = t || null;
+  tokenSource = t ? (source || "entered") : "";
+  ui.tokenState.textContent = hfToken
+    ? `${tokenSource} · held in memory for this tab only`
+    : (oauthAvailable ? "not signed in" : "none");
+  ui.clearToken.style.display = hfToken ? "" : "none";
+}
+function clearToken() { setToken(null); log("token cleared from memory"); }
+
+// A hosted deployment hands the OAuth token back in the URL *fragment*, which
+// browsers never send to a server. Take it, then strip it from the address bar
+// and from history immediately — a credential sitting in a visible URL is one
+// screenshot away from being shared.
+function adoptTokenFromFragment() {
+  if (!location.hash || location.hash.length < 2) return;
+  const h = new URLSearchParams(location.hash.slice(1));
+  const t = h.get("hf"), err = h.get("oauth_error");
+  if (t || err) history.replaceState(null, "", location.pathname + location.search);
+  if (err) { log(`sign-in failed: ${err}`); return; }
+  if (t) { setToken(t, "signed in with Hugging Face"); log("signed in with Hugging Face — token held in memory for this tab only"); }
+}
+
+// One-time prompt. Resolves to a token string, or null if the user declines.
+// Deliberately a modal rather than a stored setting: the moment a credential
+// becomes ambient, it becomes something you forget you granted.
+// Where OAuth is available — a deployment the user does not control — the
+// paste box is not offered at all. Asking someone to type a personal access
+// token into a page served by a third party is a bad pattern even when the
+// code is honest, because the user cannot verify that it is. Signing in hands
+// over a scoped, expiring token instead, and it is the only path shown there.
+let tokenPrompt = null;
+function requestToken(why) {
+  if (tokenPrompt) return tokenPrompt;
+  ui.tokWhy.textContent = why || "This model needs a Hugging Face token to download.";
+  ui.tokPasteRow.style.display = oauthAvailable ? "none" : "";
+  ui.tokSignIn.style.display = oauthAvailable ? "" : "none";
+  ui.tokOk.style.display = oauthAvailable ? "none" : "";      // nothing to submit
+  ui.tokInput.value = "";
+  ui.tokModal.style.display = "flex";
+  if (!oauthAvailable) ui.tokInput.focus();
+  tokenPrompt = new Promise((resolve) => {
+    const done = (val) => {
+      ui.tokModal.style.display = "none";
+      ui.tokInput.value = "";                    // do not leave it in the DOM
+      ui.tokOk.onclick = null; ui.tokCancel.onclick = null;
+      ui.tokInput.onkeydown = null; ui.tokSignInBtn.onclick = null;
+      tokenPrompt = null;
+      resolve(val);
+    };
+    ui.tokSignInBtn.onclick = () => {
+      // full-page redirect: we come back with the token in the fragment
+      log("redirecting to Hugging Face to sign in…");
+      location.href = "auth/login";
+    };
+    ui.tokOk.onclick = () => {
+      const v = ui.tokInput.value.trim();
+      if (!v) return done(null);
+      setToken(v, "entered by hand");
+      log("token accepted — kept in memory for this tab only, never sent to peers");
+      done(v);
+    };
+    ui.tokCancel.onclick = () => { log("token request declined"); done(null); };
+    ui.tokInput.onkeydown = (e) => { if (e.key === "Enter") ui.tokOk.onclick(); if (e.key === "Escape") ui.tokCancel.onclick(); };
+  });
+  return tokenPrompt;
+}
+
+// Run an HF call, and if it fails for want of credentials ask once, then retry.
+async function withAuth(fn, what) {
+  try { return await fn(hfToken); }
+  catch (e) {
+    if (e && e.kind === "auth") {
+      const gated = e.status === 403 ? " It is gated or private" : "";
+      const t = await requestToken(oauthAvailable
+        ? `${what} needs Hugging Face access.${gated}${gated ? " — for a gated model, accept its licence on the model page first." : ""}`
+        : `${what} needs a Hugging Face token.${gated}. Create a READ token at huggingface.co/settings/tokens.`);
+      if (!t) throw new Error(`${what}: cancelled — no token provided`);
+      return fn(t);
+    }
+    throw e;
+  }
+}
+
+// ---- identity ---------------------------------------------------------------
+const ADJ = ["Frosted", "Silver", "Pale", "Winter", "Hollow", "Quiet", "Drifting", "Little",
+             "Glacier", "Misty", "Northern", "Still", "Brave", "Snowlit", "Amber"];
+const NOUN = ["Fox", "Hare", "Owl", "Elk", "Marten", "Sparrow", "Otter", "Deer",
+              "Ptarmigan", "Pine", "Birch", "Wren", "Fawn", "Moth", "Lynx"];
+const deviceName = ADJ[Math.floor(Math.random() * ADJ.length)] + " " +
+                   NOUN[Math.floor(Math.random() * NOUN.length)];
+
+let myId = null, compute = null, ws = null, L = null, wasDenied = false;
+const pcs = new Map(), chans = new Map(), names = new Map();
+const caps = new Map();
+
+// ---- model state ------------------------------------------------------------
+let repoInfo = null;      // {repo, revision, spec, tensors, fingerprint} — head only
+let spec = null, plan = null, myStage = null, stageObj = null;
+let tok = null;           // tokenizer, loaded from the same repo
+let modelHash = 0;
+let running = false, abortRun = false;
+let probeHash = 0, auditFailure = null;
+const readyStages = new Set();
+
+function nmeOf(id) { return names.get(id) || id; }
+function room() { return new URLSearchParams(location.search).get("room"); }
+function updatePeers() {
+  if (!names.size) { ui.peers.textContent = "(none yet — you can still run solo)"; return; }
+  ui.peers.textContent = [...names.entries()]
+    .map(([id, n]) => `${n} ${chans.has(id) ? "✓" : "(connecting…)"}`).join(", ");
+}
+function ctxLen() { return +ui.ctxLen.value; }
+
+// ---- signaling + WebRTC -----------------------------------------------------
+function connectSignaling() {
+  const proto = location.protocol === "https:" ? "wss" : "ws";
+  const params = new URLSearchParams();
+  params.set("name", deviceName);
+  if (room()) params.set("room", room());
+  ws = new WebSocket(`${proto}://${location.host}/?${params}`);
+  ws.onopen = () => setStatus(room() ? `connected — private room "${room()}"` : "connected — grouping with devices on your network");
+  ws.onclose = () => {
+    if (wasDenied) return;
+    setStatus("signaling disconnected — reconnecting…");
+    setTimeout(connectSignaling, 3000);
+  };
+  ws.onmessage = async (ev) => {
+    const msg = JSON.parse(ev.data);
+    if (msg.type === "welcome") {
+      myId = msg.id;
+      if (msg.room) log(`group: ${msg.room.startsWith("net:") ? "your network" : "private room " + msg.room.replace("room:", "")}`);
+      if (msg.host) { log("you host this room — joiners wait for your approval"); setStatus(`hosting private room "${room()}"`); }
+      else if (room()) setStatus(`accepted into private room "${room()}"`);
+      for (const p of msg.peers) { names.set(p.id, p.name); if (!chans.has(p.id)) initiatePeer(p.id); }
+      updatePeers();
+    } else if (msg.type === "waiting") {
+      setStatus("knocking — waiting for the room's host to let you in…");
+    } else if (msg.type === "denied") {
+      wasDenied = true; setStatus("the host declined your request to join"); log("join request declined by the host");
+    } else if (msg.type === "host") {
+      log("the host left — you are now the host of this room"); setStatus(`hosting private room "${room()}"`);
+    } else if (msg.type === "join-request") {
+      addJoinRequest(msg.id, msg.name);
+    } else if (msg.type === "peer-joined") {
+      names.set(msg.id, msg.name); updatePeers(); log(`${msg.name} joined`);
+    } else if (msg.type === "peer-left") {
+      log(`${nmeOf(msg.id)} left`); cleanupPeer(msg.id); names.delete(msg.id); caps.delete(msg.id); updatePeers(); renderPlan();
+    } else if (msg.type === "signal") {
+      await onSignal(msg.from, msg.data);
+    } else if (msg.type === "ping") {
+      ws.send(JSON.stringify({ type: "pong" }));
+    } else if (msg.type === "relay") {
+      onWire(msg.from, bufFromB64(msg.data));
+    }
+  };
+}
+function signal(to, data) { ws.send(JSON.stringify({ type: "signal", to, data })); }
+
+function addJoinRequest(id, name) {
+  const row = document.createElement("div");
+  row.className = "joinrow";
+  const who = document.createElement("span");
+  who.textContent = `❄ ${name} wants to join`;     // textContent: names come off the wire
+  const btn = (label, allow) => {
+    const b = document.createElement("button");
+    b.textContent = label;
+    b.className = allow ? "small" : "small danger";
+    b.onclick = () => {
+      ws.send(JSON.stringify({ type: "admit", id, allow }));
+      row.remove();
+      log(allow ? `you let ${name} in` : `you declined ${name}`);
+    };
+    return b;
+  };
+  row.append(who, btn("Accept", true), btn("Deny", false));
+  ui.requests.appendChild(row);
+}
+
+function newPC(peerId) {
+  const pc = new RTCPeerConnection(rtcConfig);
+  pc.onicecandidate = (e) => { if (e.candidate) signal(peerId, { candidate: e.candidate }); };
+  pc.onconnectionstatechange = () => {
+    if (pc.connectionState === "failed") { cleanupPeer(peerId); scheduleReconnect(peerId); }
+    if (pc.connectionState === "disconnected")
+      setTimeout(() => {
+        if (pcs.get(peerId) === pc && pc.connectionState === "disconnected") {
+          log(`${nmeOf(peerId)} connection did not recover — redialing`);
+          cleanupPeer(peerId); scheduleReconnect(peerId);
+        }
+      }, 4000);
+  };
+  pcs.set(peerId, pc);
+  return pc;
+}
+function b64FromBuf(buf) {
+  const u = new Uint8Array(buf); let s = "";
+  for (let i = 0; i < u.length; i += 0x8000) s += String.fromCharCode(...u.subarray(i, i + 0x8000));
+  return btoa(s);
+}
+function bufFromB64(s) { return Uint8Array.from(atob(s), c => c.charCodeAt(0)).buffer; }
+function makeRelayChannel(peerId) {
+  return {
+    isRelay: true,
+    get readyState() { return ws && ws.readyState === 1 && names.has(peerId) ? "open" : "closed"; },
+    get bufferedAmount() { return ws ? ws.bufferedAmount : 0; },
+    send(buf) { ws.send(JSON.stringify({ type: "relay", to: peerId, data: b64FromBuf(buf) })); },
+    close() { chans.delete(peerId); },
+  };
+}
+const reconnectTimers = new Map();
+function scheduleReconnect(peerId, attempt = 0) {
+  if (!names.has(peerId) || chans.has(peerId) || reconnectTimers.has(peerId)) return;
+  if (attempt >= 5) {
+    if (names.has(peerId)) {
+      log(`no direct WebRTC path to ${nmeOf(peerId)} after 5 attempts — relaying activations through the server instead`);
+      chans.set(peerId, makeRelayChannel(peerId));
+      updatePeers(); wake();
+    }
+    return;
+  }
+  const delay = 1500 * Math.pow(2, attempt);
+  reconnectTimers.set(peerId, setTimeout(() => {
+    reconnectTimers.delete(peerId);
+    if (!names.has(peerId) || chans.has(peerId)) return;
+    if (+myId.slice(1) > +peerId.slice(1)) {
+      log(`reconnecting to ${nmeOf(peerId)} (attempt ${attempt + 1})…`);
+      cleanupPeer(peerId); initiatePeer(peerId);
+    }
+    setTimeout(() => scheduleReconnect(peerId, attempt + 1), 6000);
+  }, delay));
+}
+function initiatePeer(peerId) {
+  const pc = newPC(peerId);
+  setupChannel(peerId, pc.createDataChannel("daisy"));
+  pc.createOffer().then(o => pc.setLocalDescription(o)).then(() => signal(peerId, { sdp: pc.localDescription }));
+}
+const pendingCand = new Map();
+async function onSignal(from, data) {
+  let pc = pcs.get(from);
+  if (data.sdp) {
+    if (!pc) { pc = newPC(from); pc.ondatachannel = (e) => setupChannel(from, e.channel); }
+    await pc.setRemoteDescription(data.sdp);
+    for (const c of pendingCand.get(from) || []) try { await pc.addIceCandidate(c); } catch (e) {}
+    pendingCand.delete(from);
+    if (data.sdp.type === "offer") {
+      const ans = await pc.createAnswer(); await pc.setLocalDescription(ans);
+      signal(from, { sdp: pc.localDescription });
+    }
+  } else if (data.candidate) {
+    if (pc && pc.remoteDescription) { try { await pc.addIceCandidate(data.candidate); } catch (e) {} }
+    else { if (!pendingCand.has(from)) pendingCand.set(from, []); pendingCand.get(from).push(data.candidate); }
+  }
+}
+function setupChannel(peerId, dc) {
+  dc.binaryType = "arraybuffer";
+  dc.onopen = () => { chans.set(peerId, dc); updatePeers(); log(`connected to ${nmeOf(peerId)}`); sendHello(peerId); };
+  dc.onclose = () => { chans.delete(peerId); updatePeers(); wake(); scheduleReconnect(peerId); };
+  dc.onmessage = (e) => onWire(peerId, e.data);
+}
+function cleanupPeer(id) {
+  const pc = pcs.get(id); if (pc) pc.close();
+  pcs.delete(id); chans.delete(id); pendingCand.delete(id);
+  for (const k of fragIn.keys()) if (k.startsWith(id + ":")) fragIn.delete(k);
+  wake();
+}
+
+// ---- fragmentation ----------------------------------------------------------
+const FRAG_SENTINEL = Wire.FRAG, FRAG_CHUNK = 48 * 1024, DC_MAXBUF = 4 * 1024 * 1024;
+let fragSeq = 1;
+const fragIn = new Map();
+function dcDrain(dc) {
+  return new Promise((res) => {
+    if (dc.bufferedAmount <= DC_MAXBUF || dc.readyState !== "open") return res();
+    const t = setInterval(() => {
+      if (dc.bufferedAmount <= DC_MAXBUF || dc.readyState !== "open") { clearInterval(t); res(); }
+    }, 50);
+  });
+}
+async function dcSend(dc, buf) {
+  if (buf.byteLength <= FRAG_CHUNK) {
+    await dcDrain(dc);
+    if (dc.readyState === "open") dc.send(buf);
+    return;
+  }
+  const id = fragSeq++, src = new Uint8Array(buf);
+  const total = Math.ceil(src.length / FRAG_CHUNK);
+  for (let s = 0; s < total; s++) {
+    await dcDrain(dc);
+    if (dc.readyState !== "open") return;
+    const part = src.subarray(s * FRAG_CHUNK, Math.min((s + 1) * FRAG_CHUNK, src.length));
+    const msg = new ArrayBuffer(16 + part.length);
+    new Int32Array(msg, 0, 4).set([FRAG_SENTINEL, id, s, total]);
+    new Uint8Array(msg, 16).set(part);
+    dc.send(msg);
+  }
+}
+function onFragment(peerId, buf) {
+  const [, id, seq, total] = new Int32Array(buf, 0, 4);
+  const key = peerId + ":" + id;
+  let st = fragIn.get(key);
+  if (!st) { st = { id, parts: [], got: 0, total }; fragIn.set(key, st); }
+  st.parts[seq] = new Uint8Array(buf, 16).slice(0);
+  st.got++;
+  if (st.got < st.total) return null;
+  fragIn.delete(key);
+  let len = 0; for (const p of st.parts) len += p.length;
+  const out = new Uint8Array(len);
+  let off = 0; for (const p of st.parts) { out.set(p, off); off += p.length; }
+  return out.buffer;
+}
+function sendTo(peerId, buf) {
+  const dc = chans.get(peerId);
+  if (!dc || dc.readyState !== "open") return Promise.resolve(false);
+  return dcSend(dc, buf).then(() => true);
+}
+function broadcast(buf) {
+  return Promise.all([...chans.values()].filter(dc => dc.readyState === "open").map(dc => dcSend(dc, buf)));
+}
+
+// ---- hello / capability -----------------------------------------------------
+function sendHello(peerId) {
+  return sendTo(peerId, Wire.packHello(myCapacity, probeHash, compute ? compute.backend : "?"));
+}
+function onHello(peerId, buf) {
+  let h;
+  try { h = Wire.unpackHello(buf); } catch (e) { log(`bad hello from ${nmeOf(peerId)}: ${e.message}`); return; }
+  caps.set(peerId, { capacity: h.capacity, backend: h.backend, probe: h.probeHash });
+  // The kernel probe matters MORE in a pipeline than in the trainer. There,
+  // every peer computes the same thing, so bad arithmetic shows up as a
+  // diverging replica. Here each stage computes something different and nobody
+  // repeats it — a broken middle stage would corrupt every token invisibly.
+  // The probe is the one value that stays comparable when the work is not.
+  if (probeHash && h.probeHash && h.probeHash !== probeHash)
+    log(`⚠ ${nmeOf(peerId)} disagrees with this device's kernel probe (${h.probeHash} vs ${probeHash}). ` +
+        `Their arithmetic differs from ours — do not put them in the ring.`);
+  renderPlan();
+}
+
+// ---- capacity ---------------------------------------------------------------
+let myCapacity = 1;
+async function measureCapacity() {
+  const m = 32, k = 64, n = 64;
+  const X = new Float32Array(m * k), W = new Float32Array(k * n);
+  for (let i = 0; i < X.length; i++) X[i] = Math.sin(i) * 0.5;
+  for (let i = 0; i < W.length; i++) W[i] = Math.cos(i) * 0.5;
+  await Verified.vgemmBlock(X, W, { m, k, n, batch: 1 }, L, compute.bgemm, null);
+  const t0 = performance.now();
+  let it = 0;
+  while (performance.now() - t0 < 300) { await Verified.vgemmBlock(X, W, { m, k, n, batch: 1 }, L, compute.bgemm, null); it++; }
+  myCapacity = it / ((performance.now() - t0) / 1000);
+  return myCapacity;
+}
+
+// ---- loading a model from the Hub -------------------------------------------
+// Only the header and config are read here: a few tens of KB, regardless of how
+// large the model is. Weights are fetched per stage, later, by each device.
+async function loadRepo() {
+  const repo = ui.repo.value.trim();
+  const revision = (ui.revision.value.trim() || "main");
+  if (!/^[\w.-]+\/[\w.-]+$/.test(repo)) { log(`"${repo}" is not a valid repo id (expected owner/name)`); return; }
+  ui.loadRepo.disabled = true;
+  ui.modelState.textContent = "reading config…";
+  try {
+    const cfg = await withAuth((t) => HF.getJSON(repo, "config.json", revision, t), `${repo}/config.json`);
+    const s = Arch.fromConfig(cfg);
+    ui.modelState.textContent = "reading tokenizer…";
+    const tokJson = await withAuth((t) => HF.getJSON(repo, "tokenizer.json", revision, t), `${repo}/tokenizer.json`);
+    tok = Tokenizer.build(tokJson);
+    ui.tokenizer.textContent = tok.name;
+    ui.modelState.textContent = "reading weight index…";
+    const { tensors } = await withAuth((t) => HF.readIndex(repo, revision, t, (m) => { ui.modelState.textContent = m; }),
+                                       `${repo} weights`);
+    const fingerprint = Shard.modelFingerprint(repo, revision, tensors);
+    repoInfo = { repo, revision, spec: s, tensors, fingerprint };
+    spec = s; modelHash = fingerprint;
+    const totalMB = [...tensors.values()].reduce((a, t) => a + t.elems * 4, 0) / 1048576;
+    ui.model.textContent =
+      `${repo} · ${s.family}-style · ${s.layers} layers · hidden ${s.hidden} · ` +
+      `heads ${s.heads}${s.kvHeads !== s.heads ? "/" + s.kvHeads + " kv" : ""} · vocab ${s.vocab}`;
+    ui.modelState.textContent = `${totalMB.toFixed(0)} MB in f32 · fingerprint ${fingerprint.toString(16)}`;
+    log(`model ready: ${repo}@${revision} — ${s.layers} layers, ${totalMB.toFixed(0)} MB total in f32. ` +
+        `Nothing has been downloaded yet beyond headers; each device will fetch only its own layers.`);
+    if (s.maxPos < ctxLen()) log(`⚠ this model's max position is ${s.maxPos} — lower the context length`);
+    ui.genBtn.disabled = false;
+    ui.verifyRow.style.display = "";
+    renderPlan();
+  } catch (e) {
+    ui.modelState.textContent = "failed";
+    log(`could not load ${repo}: ${redact(e.message)}`);
+  }
+  ui.loadRepo.disabled = false;
+}
+
+function buildPlan() {
+  if (!repoInfo) return null;
+  const list = [{ id: myId, capacity: myCapacity, backend: compute.backend }];
+  for (const id of [...chans.keys()].sort((a, b) => +a.slice(1) - +b.slice(1))) {
+    const c = caps.get(id);
+    if (c) list.push({ id, capacity: c.capacity, backend: c.backend });
+  }
+  return Shard.planStages(repoInfo.spec, list);
+}
+function renderPlan() {
+  if (!plan) {
+    const known = 1 + [...chans.keys()].filter(id => caps.has(id)).length;
+    ui.plan.textContent = repoInfo ? `${known} device(s) ready — press Generate to shard and run`
+                                   : "load a model to see how it would be split";
+    return;
+  }
+  ui.plan.textContent = plan.map(s => {
+    const who = s.id === myId ? "me" : nmeOf(s.id);
+    const part = s.hi > s.lo ? `layers ${s.lo}–${s.hi - 1}` : "—";
+    let mb = "";
+    if (repoInfo) mb = " · " + (Shard.stageBytes(repoInfo.spec, repoInfo.tensors, s, Arch) / 1048576).toFixed(0) + " MB";
+    return `${s.index}. ${who}${s.head ? " (head: embed + lm_head)" : ""} · ${part}${mb}` +
+           (readyStages.has(s.index) ? " ✓" : "");
+  }).join("\n");
+}
+
+// Fetch this device's own layers. This is the only place weight bytes move,
+// and they move from the Hub to here — never from a peer.
+async function loadMyStage(assign, st) {
+  const s = assign.spec;
+  ui.myShard.textContent = "reading index…";
+  const { tensors } = await withAuth((t) => HF.readIndex(assign.repo, assign.revision, t), `${assign.repo} weights`);
+  const want = Arch.tensorsFor(s, tensors, st).map(n => tensors.get(n));
+  const mb = want.reduce((a, t) => a + t.elems * 4, 0) / 1048576;
+  log(`fetching my slice from the Hub: ${want.length} tensors, ${mb.toFixed(0)} MB ` +
+      `(the other ${s.layers - (st.hi - st.lo)} layers are never downloaded here)`);
+  const got = await withAuth((t) => HF.fetchTensors(assign.repo, assign.revision, t, want,
+                                                    (p) => { ui.myShard.textContent = `downloading ${p}`; }),
+                             `${assign.repo} weights`);
+  const w = Shard.stageWeights(s, st, got, Arch);
+  stageObj = Infer.makeStage(s, st, w, kernelCtx(), assign.ctx || ctxLen());
+  spec = s;
+  ui.myShard.textContent = `${st.head ? "head + " : ""}layers ${st.lo}–${st.hi - 1} · ${mb.toFixed(0)} MB resident`;
+  return stageObj;
+}
+
+async function onAssign(peerId, buf) {
+  if (running) { log(`ignored an assignment from ${nmeOf(peerId)} mid-run`); return; }
+  let a;
+  try { a = Wire.unpackAssign(buf); } catch (e) { log(`REFUSED assignment from ${nmeOf(peerId)}: ${e.message}`); return; }
+  plan = a.plan; spec = a.spec; modelHash = a.fingerprint;
+  myStage = plan[a.mine];
+  log(`assigned by ${nmeOf(peerId)}: ${a.repo}@${a.revision}, layers ${myStage.lo}–${myStage.hi - 1} ` +
+      `of ${a.spec.layers} (stage ${a.mine} of ${plan.length})`);
+  renderPlan();
+  try {
+    // tokenizer only matters on the head, but loading it is cheap and lets a
+    // middle stage show the token stream
+    if (!tok) {
+      try { tok = Tokenizer.build(await withAuth((t) => HF.getJSON(a.repo, "tokenizer.json", a.revision, t), "tokenizer")); }
+      catch (e) { log(`(no tokenizer here: ${redact(e.message)} — this stage will show ids, not text)`); }
+    }
+    await loadMyStage(a, myStage);
+    await sendTo(peerId, Wire.packReady(a.mine, true, "loaded"));
+    log(`ready — holding layers ${myStage.lo}–${myStage.hi - 1}. The rest of the model is not on this device.`);
+    setStatus("in the ring — waiting for work");
+  } catch (e) {
+    await sendTo(peerId, Wire.packReady(a.mine, false, redact(e.message)));
+    log(`could not take my slice: ${redact(e.message)}`);
+  }
+}
+function onReady(peerId, buf) {
+  const r = Wire.unpackReady(buf);
+  if (r.ok) { readyStages.add(r.stageIndex); log(`${nmeOf(peerId)} is ready (stage ${r.stageIndex})`); }
+  else log(`${nmeOf(peerId)} could not load stage ${r.stageIndex}: ${r.note}`);
+  renderPlan(); wake();
+}
+
+// ---- the ring ---------------------------------------------------------------
+// One token = one lap. The head embeds the window and hands the hidden state
+// to stage 1; each stage runs its own layers and hands the result on; the last
+// stage returns it to the head, which turns it into a token.
+//
+// The payload is T x hidden floats — tens of KB. The weights it stands in for
+// are hundreds of megabytes. That asymmetry is the whole reason this works,
+// and it makes a run latency-bound rather than bandwidth-bound.
+let runSeq = 0;
+const waiters = new Set();
+function wake() { for (const w of waiters) w(); }
+function waitFor(pred, timeoutMs) {
+  return new Promise((resolve) => {
+    const t0 = Date.now();
+    let timer = null;
+    const check = () => {
+      const ok = pred();
+      if (ok || Date.now() - t0 > timeoutMs) { waiters.delete(check); clearInterval(timer); resolve(!!ok); }
+    };
+    waiters.add(check);
+    timer = setInterval(check, 200);
+    check();
+  });
+}
+const actIn = new Map();
+
+function packAct(seq, tokenIdx, nextIndex, hidden) {
+  return Wire.packAct(seq, tokenIdx, nextIndex, hidden, Shard.hashF32, modelHash);
+}
+async function onAct(peerId, buf) {
+  let a;
+  try { a = Wire.unpackAct(buf, Shard.hashF32); }
+  catch (e) { log(`activation from ${nmeOf(peerId)} rejected: ${e.message}`); return; }
+  const { seq, tokenIdx, nextIndex, modelHash: mh, hidden } = a;
+  if (mh !== modelHash) {
+    log(`REFUSED activation from ${nmeOf(peerId)}: it belongs to model ${mh.toString(16)}, this device ` +
+        `holds a slice of ${modelHash.toString(16)}. Mixing two models would produce confident nonsense.`);
+    return;
+  }
+  const me = plan && plan.find(s => s.id === myId);
+  const kind = Wire.classifyAct(nextIndex, me ? me.index : -99);
+  if (kind === "return") { actIn.set(`${seq}:${tokenIdx}`, hidden); wake(); return; }
+  if (kind === "other" || !me || !stageObj) return;
+  const t0 = performance.now();
+  let x;
+  try { x = await Infer.runLayers(stageObj, hidden); }
+  catch (e) { log(`stage failed: ${redact(e.message)}`); return; }
+  if (auditFailure) { log("KERNEL AUDIT FAILED mid-hop — refusing to pass on a value I cannot vouch for"); return; }
+  const hop = Wire.routeAfter(plan, me.index);
+  ui.ringState.textContent = `layers ${me.lo}–${me.hi - 1} in ${(performance.now() - t0).toFixed(0)} ms → ` +
+                             `${hop.to === myId ? "me" : nmeOf(hop.to)}${hop.isReturn ? " (return)" : ""}`;
+  await sendTo(hop.to, packAct(seq, tokenIdx, hop.address, x));
+}
+
+async function generate() {
+  if (running) return;
+  if (!repoInfo) { log("load a model first — the device that loads it drives the ring"); return; }
+  if (!tok) { log("no tokenizer loaded"); return; }
+  running = true; abortRun = false; auditFailure = null;
+  ui.genBtn.disabled = true; ui.stopBtn.disabled = false;
+  readyStages.clear();
+  try {
+    const T = Math.min(ctxLen(), repoInfo.spec.maxPos);
+    plan = buildPlan(); modelHash = repoInfo.fingerprint; spec = repoInfo.spec;
+    renderPlan();
+    if (plan.length > 1) {
+      log(`plan: ${spec.layers} layers over ${plan.length} device(s) — ` +
+          plan.map(s => `${s.id === myId ? "me" : nmeOf(s.id)}:${s.hi - s.lo}`).join(", "));
+      for (let i = 1; i < plan.length; i++)
+        await sendTo(plan[i].id, Wire.packAssign({
+          repo: repoInfo.repo, revision: repoInfo.revision, spec, plan,
+          mine: i, fingerprint: repoInfo.fingerprint, ctx: T,
+        }));
+      log("waiting for every stage to fetch its layers…");
+      const ok = await waitFor(() => readyStages.size >= plan.length - 1, 600000);
+      if (!ok) { log("not every stage reported ready — generating anyway will stall, so stopping here."); throw new Error("stages not ready"); }
+    } else {
+      log(`solo run — this device will hold all ${spec.layers} layers`);
+    }
+    myStage = plan[0];
+    ui.myShard.textContent = "loading my slice…";
+    await loadMyStage({ repo: repoInfo.repo, revision: repoInfo.revision, spec, ctx: T }, myStage);
+
+    const seq = ++runSeq;
+    const nTok = +ui.ntok.value, temp = +ui.temp.value / 100;
+    const opts = { temperature: temp, topK: 40, rng: Infer.mulberry32(+ui.seed.value | 0) };
+    let ids = [...Tokenizer.encode(tok, ui.prompt.value || "The")];
+    if (!ids.length) ids = [0];
+    const promptLen = ids.length;
+    ui.out.textContent = ui.prompt.value;
+    const tStart = performance.now();
+    let hops = 0;
+
+    for (let n = 0; n < nTok && !abortRun; n++) {
+      const win = new Int32Array(T);
+      const tail = ids.slice(-T);
+      for (let i = 0; i < tail.length; i++) win[T - tail.length + i] = tail[i];
+      let x = Infer.embed(stageObj, win);
+      x = await Infer.runLayers(stageObj, x);
+      if (auditFailure) { log(`KERNEL AUDIT FAILED: ${auditFailure} — stopping`); break; }
+      if (plan.length > 1) {
+        await sendTo(plan[1].id, packAct(seq, n, plan[1].index, x));
+        hops += plan.length;
+        const key = `${seq}:${n}`;
+        const ok = await waitFor(() => actIn.has(key), 60000);
+        if (!ok) { log(`the ring stalled at token ${n + 1}: no activation came back. Press Generate again to re-plan.`); break; }
+        x = actIn.get(key); actIn.delete(key);
+      }
+      const id = Infer.pickToken(await Infer.readout(stageObj, x), opts);
+      ids.push(id);
+      ui.out.textContent = Tokenizer.decode(tok, ids);
+      ui.tokcount.textContent = String(n + 1);
+      ui.hops.textContent = String(hops);
+      ui.tps.textContent = ((n + 1) / ((performance.now() - tStart) / 1000)).toFixed(2);
+      broadcast(Wire.packToken(seq, id, ids.length));
+      await new Promise(r => setTimeout(r, 0));
+    }
+    // The differential check. In a pipeline nothing recomputes anything, so
+    // this is the only instrument that can show a distributed answer is RIGHT
+    // rather than merely self-consistent. It costs a full local run, which is
+    // only possible when this device can hold the whole model — so it is
+    // offered, not assumed.
+    if (ui.verify.checked && !abortRun && plan.length > 1) {
+      log("verifying: fetching the whole model here and re-running the same prompt…");
+      const all = { id: myId, index: 0, lo: 0, hi: spec.layers, head: true };
+      const solo = await loadMyStage({ repo: repoInfo.repo, revision: repoInfo.revision, spec, ctx: T }, all);
+      const ref = await Infer.generateLocal([solo], Tokenizer.encode(tok, ui.prompt.value || "The"), nTok,
+                                            { temperature: temp, topK: 40, rng: Infer.mulberry32(+ui.seed.value | 0) });
+      const same = ref.length === ids.length && ref.every((v, i) => v === ids[i]);
+      log(same ? "VERIFIED: the distributed run and the single-device run produced identical token ids."
+               : `MISMATCH: the ring and this device disagree. Distributed "${Tokenizer.decode(tok, ids).slice(0, 60)}" ` +
+                 `vs local "${Tokenizer.decode(tok, ref).slice(0, 60)}". Check the log for probe warnings.`);
+    }
+    if (!abortRun) log(`done — ${ids.length - promptLen} token(s) in ${((performance.now() - tStart) / 1000).toFixed(1)} s ` +
+                       `over ${plan.length} stage(s)`);
+    broadcast(Wire.packDone(seq));
+  } catch (e) {
+    log(`run failed: ${redact(e.message)}`);
+    console.error(e);
+  }
+  running = false;
+  ui.genBtn.disabled = false; ui.stopBtn.disabled = true;
+  ui.ringState.textContent = "idle";
+}
+
+function onToken(peerId, buf) {
+  const { id } = Wire.unpackToken(buf);
+  if (tok) ui.out.textContent += Tokenizer.decode(tok, [id]);
+  else ui.out.textContent += ` ${id}`;
+  ui.tokcount.textContent = String(+(ui.tokcount.textContent || 0) + 1);
+}
+
+function onWire(peerId, buf) {
+  const tag = Wire.tagOf(buf);
+  if (tag === Wire.FRAG) { const whole = onFragment(peerId, buf); if (whole) onWire(peerId, whole); return; }
+  if (tag === Wire.HELLO) return onHello(peerId, buf);
+  if (tag === Wire.ASSIGN) return void onAssign(peerId, buf);
+  if (tag === Wire.READY) return onReady(peerId, buf);
+  if (tag === Wire.ACT) return void onAct(peerId, buf);
+  if (tag === Wire.TOKEN) return onToken(peerId, buf);
+  if (tag === Wire.DONE) { ui.ringState.textContent = "idle"; return; }
+}
+
+// ---- kernels ----------------------------------------------------------------
+const gemmAudit = {
+  cells: 12,
+  due: () => true,
+  fail: (msg) => { if (!auditFailure) { auditFailure = msg; log(`KERNEL AUDIT FAILED: ${msg}`); } },
+};
+function kernelCtx() {
+  return { L, bgemm: compute.bgemm || null, att: compute.att || null,
+           mlp: compute.mlp || null, audit: gemmAudit };
+}
+
+// ---- boot -------------------------------------------------------------------
+(async function () {
+  try {
+    const mode = await (await fetch("mode")).json();
+    if (mode.rtc) rtcConfig = mode.rtc;
+    oauthAvailable = !!mode.oauth;
+    // Room-first deployments (the hosted Space sets DAISY_FORCE_ROOMS): there
+    // is no LAN auto-grouping between strangers. Two people behind the same
+    // CGNAT or on the same campus network share a public IP, and without this
+    // they would be dropped into one ring together — able to see each other's
+    // addresses and each other's activations. So a visitor with no room code
+    // chooses: create their own room, or join one by code.
+    if (mode.forceRooms && !room()) {
+      for (const c of document.querySelectorAll(".card")) if (c !== ui.lobby) c.style.display = "none";
+      ui.lobby.style.display = "";
+      ui.createRoom.onclick = () => {
+        const code = (ADJ[Math.floor(Math.random() * ADJ.length)] + "-" +
+                      NOUN[Math.floor(Math.random() * NOUN.length)] + "-" +
+                      (100 + Math.floor(Math.random() * 900))).toLowerCase();
+        location.href = "?room=" + code;
+      };
+      const join = () => {
+        const code = ui.joinCode.value.trim().toLowerCase();
+        if (code) location.href = "?room=" + encodeURIComponent(code);
+      };
+      ui.joinRoom.onclick = join;
+      ui.joinCode.onkeydown = (e) => { if (e.key === "Enter") join(); };
+      return;                                    // wait for the choice
+    }
+  } catch (e) {}                                 // no /mode: local defaults
+  adoptTokenFromFragment();                      // returning from an OAuth sign-in
+
+  // Same rule as the trainer: the verified units are mandatory. No float path.
+  try {
+    L = await Compute.loadLUTs();
+    if (!(L.mul instanceof Int16Array) || L.mul.length !== 65536) throw new Error("mul8 LUT malformed");
+    if (L.mul[((7 & 0xFF) * 256) + (-3 & 0xFF)] !== -21) throw new Error("mul8 LUT self-test failed (7 × -3 ≠ -21)");
+    compute = await Compute.initCompute(L);
+  } catch (e) {
+    setStatus("NEURAL UNITS UNAVAILABLE — inference disabled");
+    ui.backend.textContent = "unavailable";
+    log(`FATAL: verified neural units failed to load (${e.message}). This build only computes through the units.`);
+    return;
+  }
+  ui.backend.textContent = `${compute.backend.toUpperCase()} — ${compute.label}`;
+  probeHash = await Compute.kernelProbe(compute, L);
+  log(`kernel probe: ${probeHash} — every honest device gets this same number, on any backend`);
+
+  await measureCapacity();
+  log(`measured capacity: ${myCapacity.toFixed(0)} verified GEMMs/sec — this decides how many layers this device takes`);
+
+  ui.me.textContent = deviceName;
+  if (!hfToken) setToken(null);                  // keep a token adopted from the fragment
+  if (oauthAvailable) log("this deployment uses Hugging Face sign-in for gated models — no token is ever typed into this page");
+  for (const [el, out] of [[ui.temp, ui.vtemp], [ui.ntok, ui.vntok], [ui.ctxLen, ui.vctxLen]])
+    el.oninput = () => out.textContent = el.value;
+  ui.temp.oninput(); ui.ntok.oninput(); ui.ctxLen.oninput();
+
+  if (room()) {
+    ui.roomInfo.style.display = "";
+    ui.roomCode.textContent = room();
+    ui.copyLink.onclick = async () => {
+      try { await navigator.clipboard.writeText(location.href); ui.copyLink.textContent = "Copied!"; }
+      catch { ui.copyLink.textContent = location.href; }
+      setTimeout(() => ui.copyLink.textContent = "Copy invite link", 2000);
+    };
+  }
+  ui.loadRepo.onclick = loadRepo;
+  ui.repo.onkeydown = (e) => { if (e.key === "Enter") loadRepo(); };
+  ui.clearToken.onclick = clearToken;
+  ui.genBtn.onclick = generate;
+  ui.stopBtn.onclick = () => { abortRun = true; log("stopping after the current token"); };
+
+  updatePeers(); renderPlan();
+  connectSignaling();
+  document.addEventListener("visibilitychange", () => {
+    if (!document.hidden && (!ws || ws.readyState > 1)) { log("page woke — reconnecting"); connectSignaling(); }
+  });
+  if (navigator.connection && navigator.connection.addEventListener)
+    navigator.connection.addEventListener("change", () => {
+      if (!ws || ws.readyState > 1) { log("network changed — reconnecting"); connectSignaling(); }
+    });
+  setStatus("ready — load a model to drive, or wait to be given a slice");
+  log(`ready — this device is "${deviceName}", computing through verified units on ${compute.backend.toUpperCase()}`);
+})();

public/arch.js

@@ -0,0 +1,153 @@
+// config.json -> a normalized model spec, and the tensor names to fetch.
+//
+// "Load any model off HuggingFace" is not a file-format problem, it is an
+// architecture problem: the weights are easy to read, but a Llama block and a
+// GPT-2 block are different computations. This file is where that difference
+// is confined. Everything downstream — sharding, the ring, the kernels —
+// works off the normalized spec and never asks what family a model came from.
+//
+// Supported families, and what each one needs from the forward pass:
+//
+//   llama / mistral / qwen2 / smollm / tinyllama   RMSNorm, RoPE, GQA, SwiGLU
+//   gpt2 / gpt2-style                              LayerNorm+bias, learned
+//                                                  positions, fused QKV, GELU
+//
+// Anything else is refused BY NAME with a clear message. Silently treating an
+// unknown architecture as a known one would produce fluent, confident, wrong
+// output — the exact failure this project spends its verification budget on
+// making impossible.
+(function (root) {
+  "use strict";
+
+  const LLAMA_LIKE = new Set(["llama", "mistral", "qwen2", "qwen3", "smollm", "tinyllama", "olmo", "phi3"]);
+  const GPT2_LIKE = new Set(["gpt2", "gpt_neo"]);
+
+  function pick(cfg, keys, dflt) {
+    for (const k of keys) if (cfg[k] != null) return cfg[k];
+    return dflt;
+  }
+
+  function fromConfig(cfg) {
+    const type = String(cfg.model_type || "").toLowerCase();
+    const family = LLAMA_LIKE.has(type) ? "llama" : GPT2_LIKE.has(type) ? "gpt2" : null;
+    if (!family)
+      throw new Error(`unsupported architecture "${cfg.model_type || "unknown"}". ` +
+        `This build implements Llama-style (RMSNorm/RoPE/GQA/SwiGLU) and GPT-2-style blocks. ` +
+        `Running a different block shape through these kernels would produce confident nonsense, so it is refused.`);
+
+    const hidden = pick(cfg, ["hidden_size", "n_embd"], 0);
+    const layers = pick(cfg, ["num_hidden_layers", "n_layer"], 0);
+    const heads = pick(cfg, ["num_attention_heads", "n_head"], 0);
+    const vocab = pick(cfg, ["vocab_size"], 0);
+    if (!hidden || !layers || !heads || !vocab)
+      throw new Error("config.json is missing hidden_size / num_hidden_layers / num_attention_heads / vocab_size");
+
+    const kvHeads = family === "llama" ? pick(cfg, ["num_key_value_heads"], heads) : heads;
+    const headDim = pick(cfg, ["head_dim"], Math.floor(hidden / heads));
+    if (heads * headDim !== hidden && family === "gpt2")
+      throw new Error(`head geometry does not divide the hidden size (${heads} heads x ${headDim} != ${hidden})`);
+
+    const spec = {
+      family, modelType: type, hidden, layers, heads, kvHeads, headDim, vocab,
+      inter: pick(cfg, ["intermediate_size", "n_inner"], family === "gpt2" ? 4 * hidden : 4 * hidden),
+      maxPos: pick(cfg, ["max_position_embeddings", "n_positions", "n_ctx"], 2048),
+      normEps: pick(cfg, ["rms_norm_eps", "layer_norm_epsilon", "layer_norm_eps"], 1e-5),
+      norm: family === "llama" ? "rms" : "ln",
+      act: family === "llama" ? "silu" : "gelu",
+      gated: family === "llama",                 // SwiGLU has a gate branch; GELU MLP does not
+      rope: family === "llama",
+      ropeTheta: pick(cfg, ["rope_theta"], 10000),
+      tie: pick(cfg, ["tie_word_embeddings"], family === "gpt2"),
+      qkvFused: family === "gpt2",               // GPT-2 packs q,k,v in one c_attn
+      bias: family === "gpt2",                   // Llama-likes are bias-free
+      // GPT-2's Conv1D stores (in, out) — already the k x n our GEMM wants.
+      // torch.nn.Linear stores (out, in) and must be transposed at load.
+      weightLayout: family === "gpt2" ? "in_out" : "out_in",
+    };
+    if (spec.gated && !cfg.intermediate_size)
+      throw new Error("a gated MLP needs intermediate_size in config.json");
+    if (spec.kvHeads && spec.heads % spec.kvHeads !== 0)
+      throw new Error(`num_attention_heads (${spec.heads}) is not a multiple of num_key_value_heads (${spec.kvHeads})`);
+    return spec;
+  }
+
+  // ---- tensor names -----------------------------------------------------------
+  // Returned as { role: name }. Roles are what the forward pass asks for, so a
+  // new family only has to be named here, never plumbed through.
+  function layerTensors(spec, i) {
+    if (spec.family === "llama") {
+      const p = `model.layers.${i}.`;
+      // The q/k/v biases are listed but OPTIONAL, and that is not a detail:
+      // Qwen2.5 ships them while SmolLM does not, and neither says so in
+      // config.json (`attention_bias` is simply absent from Qwen's). Trusting
+      // the config would silently drop three bias vectors per layer — a model
+      // that still generates fluent text, just not the right text. So bias is
+      // decided by what the weight file actually contains.
+      return {
+        nrm1: p + "input_layernorm.weight",
+        nrm2: p + "post_attention_layernorm.weight",
+        Wq: p + "self_attn.q_proj.weight", bq: p + "self_attn.q_proj.bias",
+        Wk: p + "self_attn.k_proj.weight", bk: p + "self_attn.k_proj.bias",
+        Wv: p + "self_attn.v_proj.weight", bv: p + "self_attn.v_proj.bias",
+        Wo: p + "self_attn.o_proj.weight", bo: p + "self_attn.o_proj.bias",
+        Wgate: p + "mlp.gate_proj.weight", Wup: p + "mlp.up_proj.weight", Wdown: p + "mlp.down_proj.weight",
+      };
+    }
+    const p = `h.${i}.`;                          // gpt2 (also seen as transformer.h.N)
+    return {
+      nrm1: p + "ln_1.weight", nrm1b: p + "ln_1.bias",
+      nrm2: p + "ln_2.weight", nrm2b: p + "ln_2.bias",
+      Wqkv: p + "attn.c_attn.weight", bqkv: p + "attn.c_attn.bias",
+      Wo: p + "attn.c_proj.weight", bo: p + "attn.c_proj.bias",
+      Wfc: p + "mlp.c_fc.weight", bfc: p + "mlp.c_fc.bias",
+      Wdown: p + "mlp.c_proj.weight", bdown: p + "mlp.c_proj.bias",
+    };
+  }
+  function headTensors(spec) {
+    if (spec.family === "llama")
+      return { emb: "model.embed_tokens.weight", nrmF: "model.norm.weight",
+               lmHead: spec.tie ? null : "lm_head.weight" };
+    return { emb: "wte.weight", pos: "wpe.weight",
+             nrmF: "ln_f.weight", nrmFb: "ln_f.bias",
+             lmHead: spec.tie ? null : "lm_head.weight" };
+  }
+
+  // Repos differ on whether GPT-2 tensors carry a "transformer." prefix, and
+  // some Llama exports drop "model.". Rather than guessing, resolve each name
+  // against the tensors the file actually contains.
+  function resolver(available) {
+    const has = (n) => available.has(n);
+    return function resolve(name, optional) {
+      if (name == null) return null;
+      if (has(name)) return name;
+      for (const alt of ["transformer." + name, name.replace(/^model\./, ""), "model." + name,
+                         name.replace(/^transformer\./, "")])
+        if (has(alt)) return alt;
+      if (optional) return null;
+      throw new Error(`the weights do not contain "${name}" — this repo's layout is not one this build recognises`);
+    };
+  }
+
+  // Every tensor one stage needs: its layers, plus the head's pieces if it is
+  // the head. This is the list that becomes byte ranges.
+  function tensorsFor(spec, available, st) {
+    const resolve = resolver(available);
+    const want = [];
+    const add = (n, opt) => { const r = resolve(n, opt); if (r) want.push(r); };
+    if (st.head) {
+      const h = headTensors(spec);
+      add(h.emb); add(h.pos, true); add(h.nrmF, true); add(h.nrmFb, true); add(h.lmHead, true);
+    }
+    for (let l = st.lo; l < st.hi; l++) {
+      const t = layerTensors(spec, l);
+      // bias roles (b*) are optional everywhere: present in the file or not
+      // applied at all. Weight roles (W*, nrm*) are required.
+      for (const [role, n] of Object.entries(t)) add(n, /^b/.test(role));
+    }
+    return want;
+  }
+
+  const api = { fromConfig, layerTensors, headTensors, tensorsFor, resolver, LLAMA_LIKE, GPT2_LIKE };
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.Arch = api;
+})(typeof self !== "undefined" ? self : this);

public/hf.js

@@ -0,0 +1,155 @@
+// Hugging Face Hub client — fetch only the bytes this device needs.
+//
+// Two rules shape this file.
+//
+// 1. NOTHING is downloaded whole. config.json and the tokenizer are small and
+//    fetched normally; the weights are read with HTTP range requests against
+//    the byte offsets in the safetensors header. A device that owns four
+//    layers transfers four layers.
+//
+// 2. The token is asked for ONCE, held in memory, and never written anywhere.
+//    Not localStorage, not sessionStorage, not a cookie, not a URL, not the
+//    log, and above all never onto the wire — peers each authenticate
+//    themselves. A page reload is meant to lose it. See requestToken() in
+//    app.js for the prompt; this file only ever receives it as an argument.
+(function (root) {
+  "use strict";
+
+  let ST;                                  // Safetensors — resolved per environment at the end
+  const HUB = "https://huggingface.co";
+
+  // A token that reaches a log or a peer is a leaked credential, so anything
+  // that formats an error goes through here first. Cheap, and it means a
+  // careless template literal cannot undo rule 2.
+  function redact(s, token) {
+    if (!token) return s;
+    return String(s).split(token).join("hf_***");
+  }
+
+  function headers(token, extra) {
+    const h = Object.assign({}, extra || {});
+    if (token) h["Authorization"] = "Bearer " + token;
+    return h;
+  }
+
+  function fileUrl(repo, file, revision) {
+    return `${HUB}/${repo}/resolve/${encodeURIComponent(revision || "main")}/${file}`;
+  }
+
+  // Turn the Hub's status codes into something a person can act on. 401/403 on
+  // a public-looking repo almost always means "gated, accept the licence" or
+  // "private, needs a token", and those need different actions from the user,
+  // so they are not collapsed into one message.
+  class HFError extends Error {
+    constructor(msg, kind, status) { super(msg); this.kind = kind; this.status = status; }
+  }
+  function statusError(res, repo, file, hasToken) {
+    const where = `${repo}/${file}`;
+    if (res.status === 401)
+      return new HFError(hasToken
+        ? `${where}: the token was rejected (401). Check it is a valid READ token and has not been revoked.`
+        : `${where} needs authentication (401).`, "auth", 401);
+    if (res.status === 403)
+      return new HFError(hasToken
+        ? `${where}: this token does not have access (403). If the model is gated, accept its licence on the model page first.`
+        : `${where} is gated or private (403).`, "auth", 403);
+    if (res.status === 404)
+      return new HFError(`${where} not found (404). Check the repo id, and that this model ships .safetensors weights.`, "missing", 404);
+    return new HFError(`${where}: HTTP ${res.status}`, "http", res.status);
+  }
+
+  async function getJSON(repo, file, revision, token) {
+    const res = await fetch(fileUrl(repo, file, revision), { headers: headers(token) });
+    if (!res.ok) throw statusError(res, repo, file, !!token);
+    try { return await res.json(); }
+    catch (e) { throw new HFError(`${repo}/${file} is not valid JSON`, "parse", res.status); }
+  }
+
+  // Range read. The Hub redirects to a CDN that honours Range and answers 206;
+  // a 200 here means the whole file came back, which for a multi-hundred-MB
+  // weights file is exactly the outcome this project exists to avoid — so it
+  // is treated as an error rather than silently accepted.
+  async function getRange(repo, file, revision, token, start, end) {
+    const res = await fetch(fileUrl(repo, file, revision), {
+      headers: headers(token, { Range: `bytes=${start}-${end - 1}` }),
+    });
+    if (res.status === 200)
+      throw new HFError(`${repo}/${file}: the server ignored the byte range and returned the whole file — refusing it.`, "norange", 200);
+    if (!res.ok && res.status !== 206) throw statusError(res, repo, file, !!token);
+    return res.arrayBuffer();
+  }
+
+  // ---- what a repo contains ---------------------------------------------------
+  // Sharded repos carry model.safetensors.index.json mapping tensor -> shard.
+  // Single-file repos just have model.safetensors. Try the index first: its
+  // absence is the normal case and a 404 is cheap.
+  async function listWeightFiles(repo, revision, token) {
+    try {
+      const idx = await getJSON(repo, "model.safetensors.index.json", revision, token);
+      const files = [...new Set(Object.values(idx.weight_map || {}))];
+      if (!files.length) throw new HFError("weight index lists no shards", "parse", 200);
+      return { files, weightMap: idx.weight_map };
+    } catch (e) {
+      if (e.kind === "auth") throw e;                 // don't mask a token problem
+      return { files: ["model.safetensors"], weightMap: null };
+    }
+  }
+
+  // Read just the header of each weight shard: two requests per shard, a few
+  // tens of KB, and afterwards we know every tensor's exact byte range without
+  // having touched a single weight.
+  async function readIndex(repo, revision, token, onProgress) {
+    const { files } = await listWeightFiles(repo, revision, token);
+    const tensors = new Map();
+    for (const f of files) {
+      if (onProgress) onProgress(`reading ${f} header…`);
+      const head = await getRange(repo, f, revision, token, 0, 8);
+      const dv = new DataView(head);
+      const lo = dv.getUint32(0, true), hi = dv.getUint32(4, true);
+      if (hi !== 0) throw new HFError(`${f}: implausible header length — not a safetensors file`, "parse", 200);
+      const full = await getRange(repo, f, revision, token, 0, 8 + lo);
+      const parsed = ST.parseHeader(full);
+      for (const [name, t] of parsed.tensors) tensors.set(name, Object.assign({ file: f }, t));
+    }
+    return { files, tensors };
+  }
+
+  // Fetch a specific set of tensors as f32, coalescing adjacent byte ranges.
+  // This is the only function that moves real weight data.
+  async function fetchTensors(repo, revision, token, tensors, onProgress) {
+    const out = new Map();
+    const byFile = new Map();
+    for (const t of tensors) {
+      if (!byFile.has(t.file)) byFile.set(t.file, []);
+      byFile.get(t.file).push(t);
+    }
+    let done = 0;
+    const total = tensors.reduce((a, t) => a + t.bytes, 0);
+    for (const [file, list] of byFile) {
+      for (const run of ST.coalesce(list)) {
+        const buf = await getRange(repo, file, revision, token, run.start, run.end);
+        for (const t of run.tensors) {
+          const off = t.start - run.start;
+          out.set(t.name, ST.toF32(t.dtype, new Uint8Array(buf, off, t.bytes)));
+          done += t.bytes;
+          if (onProgress) onProgress(`${(done / 1048576).toFixed(1)} / ${(total / 1048576).toFixed(1)} MB`);
+        }
+      }
+    }
+    return out;
+  }
+
+  // A cheap probe so the UI can ask for a token only when one is actually
+  // needed, instead of demanding credentials up front for public models.
+  async function needsAuth(repo, revision) {
+    try {
+      const res = await fetch(fileUrl(repo, "config.json", revision), { method: "HEAD" });
+      return res.status === 401 || res.status === 403;
+    } catch (e) { return false; }
+  }
+
+  const api = { HUB, HFError, fileUrl, getJSON, getRange, listWeightFiles, readIndex,
+                fetchTensors, needsAuth, redact };
+  if (typeof module !== "undefined" && module.exports) { ST = require("./safetensors.js"); module.exports = api; }
+  else { ST = root.Safetensors; root.HF = api; }
+})(typeof self !== "undefined" ? self : this);

public/index.html

@@ -0,0 +1,252 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>DaisyChain-Infer — run one model across your devices</title>
+<style>
+  /* Winter palette: pale snow-light, deep glacier dark. Blues and slates
+     throughout, with a cold cyan accent that stays legible on both. */
+  :root {
+    --page-bg: #eef3f8;
+    --page-tint: #dce6f0;
+    --card-bg: #f9fbfd;
+    --card-border: rgba(90, 122, 154, 0.28);
+    --text: #16232e;
+    --text-soft: #55708a;
+    --accent: #2f6f96;
+    --accent-deep: #1d4b6b;
+    --panel-bg: linear-gradient(135deg, #24455e 0%, #14283a 100%);
+    --panel-num: #eaf4fb;
+    --panel-label: #8fb4cd;
+    --btn: linear-gradient(135deg, #35789e 0%, #1d4b6b 100%);
+    --btn-hover: linear-gradient(135deg, #4189af 0%, #255a7f 100%);
+    --danger: #9a3d3d;
+    --warn: #a2472f;
+    --track: rgba(90, 122, 154, 0.20);
+    --shadow: 0 2px 12px rgba(30, 60, 90, 0.10);
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --page-bg: #0c141d;
+      --page-tint: #101c27;
+      --card-bg: #14212d;
+      --card-border: rgba(140, 180, 210, 0.22);
+      --text: #dce9f3;
+      --text-soft: #8faec7;
+      --accent: #6fb5da;
+      --accent-deep: #9fd0e8;
+      --panel-bg: linear-gradient(135deg, #16303f 0%, #0a1620 100%);
+      --panel-num: #e6f3fb;
+      --panel-label: #7ea9c4;
+      --btn: linear-gradient(135deg, #2c6688 0%, #17394f 100%);
+      --btn-hover: linear-gradient(135deg, #37789d 0%, #1e4a66 100%);
+      --danger: #b3554f;
+      --warn: #e0a07f;
+      --track: rgba(140, 180, 210, 0.18);
+      --shadow: 0 2px 14px rgba(0, 0, 0, 0.35);
+    }
+  }
+  * { box-sizing: border-box; }
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+         max-width: 760px; margin: 0 auto; padding: 24px 18px 48px; line-height: 1.5;
+         background: linear-gradient(180deg, var(--page-tint) 0%, var(--page-bg) 340px);
+         color: var(--text); }
+  h1 { margin: 0 0 2px; font-size: 1.7rem; letter-spacing: .2px; }
+  .sub { color: var(--text-soft); margin: 0 0 18px; font-size: .92rem; }
+  .sub code, code { background: rgba(47, 111, 150, .12); padding: 1px 5px; border-radius: 4px;
+                    font-family: 'Cascadia Code', 'Courier New', monospace; font-size: .9em; }
+  .card { background: var(--card-bg); border: 1px solid var(--card-border); border-radius: 12px;
+          padding: 14px 16px; margin: 12px 0; box-shadow: var(--shadow); }
+  .lbl { color: var(--text-soft); font-size: 11px; font-weight: 800; letter-spacing: 1.5px;
+         text-transform: uppercase; margin-bottom: 8px; }
+  .row { display: flex; justify-content: space-between; gap: 12px; padding: 3px 0; font-size: .95rem; }
+  .k { color: var(--text-soft); } .v { font-weight: 700; text-align: right; word-break: break-word; }
+  .device { font-family: 'Cascadia Code', 'Courier New', monospace; font-size: 1.5rem; font-weight: 700;
+            color: var(--accent-deep); }
+  .panel { background: var(--panel-bg); border-radius: 10px; padding: 12px 16px; text-align: center; flex: 1; }
+  .panel .num { font-family: 'Cascadia Code', 'Courier New', monospace; font-size: 1.7rem;
+                font-weight: 700; color: var(--panel-num); }
+  .panel .cl { color: var(--panel-label); font-size: 10px; text-transform: uppercase; letter-spacing: 1.2px; }
+  button { background: var(--btn); color: #eef6fb; border: 0; border-radius: 8px; padding: 11px 24px;
+           font-weight: 700; font-size: .98rem; letter-spacing: .3px; cursor: pointer;
+           box-shadow: 0 2px 8px rgba(20, 45, 70, 0.22); transition: .15s; }
+  button:hover:not(:disabled) { background: var(--btn-hover); }
+  button:disabled { background: #7d8f9e; opacity: .5; cursor: not-allowed; box-shadow: none; }
+  button.small { padding: 6px 14px; font-size: .85rem; }
+  button.danger { background: var(--danger); }
+  pre { background: rgba(20, 45, 70, 0.05); border-radius: 8px; padding: 10px; max-height: 180px; overflow: auto;
+        font-size: .78rem; color: var(--text-soft); white-space: pre-wrap; margin: 0;
+        font-family: 'Cascadia Code', 'Courier New', monospace; }
+  @media (prefers-color-scheme: dark) { pre { background: rgba(0, 0, 0, 0.28); } }
+  .note { color: var(--text-soft); font-size: .82rem; }
+  .note b { color: var(--warn); }
+  .slbl { display: flex; justify-content: space-between; font-size: .92rem; margin: 10px 0 4px; font-weight: 600; }
+  .sval { font-family: 'Cascadia Code', 'Courier New', monospace; color: var(--accent); font-weight: 700; }
+  input[type=range] { width: 100%; accent-color: var(--accent); }
+  input[type=text], input[type=number], input[type=password] {
+        padding: 10px 12px; border-radius: 8px; border: 1px solid var(--card-border);
+        background: rgba(255,255,255,.55); color: inherit;
+        font-family: 'Cascadia Code', 'Courier New', monospace; font-size: .92rem; }
+  @media (prefers-color-scheme: dark) {
+    input[type=text], input[type=number], input[type=password] { background: rgba(0,0,0,.25); }
+  }
+  input:focus { outline: 2px solid var(--accent); outline-offset: 1px; }
+  #out { background: rgba(20, 45, 70, 0.05); border-radius: 8px; padding: 12px; min-height: 96px;
+         max-height: 340px; overflow: auto; white-space: pre-wrap; word-break: break-word;
+         font-family: 'Cascadia Code', 'Courier New', monospace; font-size: .9rem; color: var(--text); }
+  @media (prefers-color-scheme: dark) { #out { background: rgba(0, 0, 0, 0.28); } }
+  .joinrow { display: flex; gap: 8px; align-items: center; justify-content: space-between;
+             margin-top: 10px; flex-wrap: wrap; }
+  .modal { position: fixed; inset: 0; background: rgba(8, 18, 28, .62); backdrop-filter: blur(3px);
+           display: none; align-items: center; justify-content: center; padding: 20px; z-index: 50; }
+  .modal .box { background: var(--card-bg); border: 1px solid var(--card-border); border-radius: 12px;
+                padding: 20px; max-width: 460px; width: 100%; box-shadow: 0 10px 40px rgba(0,0,0,.35); }
+  .modal h3 { margin: 0 0 8px; font-size: 1.1rem; }
+  .modal input { width: 100%; margin: 12px 0 6px; }
+  .modal .acts { display: flex; gap: 8px; justify-content: flex-end; margin-top: 12px; }
+</style>
+</head>
+<body>
+  <h1>❄ DaisyChain-Infer</h1>
+  <p class="sub">Run <b>one model across several devices</b>. Each device downloads and holds only its <b>own layers</b> — straight from Hugging Face, never from a peer — and passes the hidden state around the ring over WebRTC. The group can run a model that no single device could hold. Every multiply goes through the verified INT8 units. Runs locally: <code>npm start</code>.</p>
+
+  <!-- Shown only when the deployment sets DAISY_FORCE_ROOMS (the hosted Space).
+       Without it, visitors with no room code are grouped by public IP — which
+       on a public URL would put strangers behind the same CGNAT in one ring. -->
+  <div class="card" id="lobby" style="display:none;text-align:center">
+    <div class="lbl">❄ Get started</div>
+    <p class="note" style="margin:0 0 12px">Create a room and invite your own devices, or join a room someone shared with you. Rings are private by invitation — you approve every device that joins.</p>
+    <button id="createRoom">Create a room</button>
+    <div style="display:flex;gap:8px;justify-content:center;margin-top:12px;flex-wrap:wrap">
+      <input type="text" id="joinCode" placeholder="room code" spellcheck="false">
+      <button id="joinRoom" style="padding:10px 18px">Join</button>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="lbl">❄ This device</div>
+    <div class="device" id="me">—</div>
+    <div class="row" style="margin-top:8px"><span class="k">Status</span><span class="v" id="status">starting…</span></div>
+    <div class="row"><span class="k">Compute</span><span class="v" id="backend">detecting…</span></div>
+    <div class="row"><span class="k">My slice</span><span class="v" id="myShard">none yet</span></div>
+    <div class="row"><span class="k">HF token</span><span class="v" id="tokenState">none</span></div>
+    <div style="text-align:right"><button id="clearToken" class="small danger" style="display:none">Forget token</button></div>
+  </div>
+
+  <div class="card">
+    <div class="lbl">🜂 Devices in your group</div>
+    <div class="row"><span class="v" id="peers" style="text-align:left">(none yet)</span></div>
+    <div id="roomInfo" style="display:none;margin-top:8px">
+      <div class="row"><span class="k">Room</span><span class="v" id="roomCode"></span></div>
+      <div style="text-align:center;margin-top:6px"><button id="copyLink" class="small">Copy invite link</button></div>
+      <p class="note" style="margin:.5rem 0 0;text-align:center">Open the link on your other devices — you approve each one before it joins.</p>
+    </div>
+    <div id="requests"></div>
+  </div>
+
+  <div class="card">
+    <div class="lbl">🗻 Model</div>
+    <div style="display:flex;gap:8px;flex-wrap:wrap">
+      <input type="text" id="repo" value="HuggingFaceTB/SmolLM-135M" spellcheck="false"
+             placeholder="owner/name" style="flex:2;min-width:200px">
+      <input type="text" id="revision" value="main" spellcheck="false" placeholder="revision" style="flex:0 0 90px">
+      <button id="loadRepo">Load</button>
+    </div>
+    <div class="row" style="margin-top:10px"><span class="v" id="model" style="text-align:left">no model loaded</span></div>
+    <div class="row"><span class="k">Status</span><span class="v" id="modelState">—</span></div>
+    <div class="row"><span class="k">Tokenizer</span><span class="v" id="tokenizer">—</span></div>
+    <p class="note" style="margin:.6rem 0 0">Any Hugging Face repo with <code>.safetensors</code> weights whose architecture is <b>Llama-style</b> (Llama, Mistral, Qwen2, SmolLM, TinyLlama) or <b>GPT-2-style</b>. Loading reads only <code>config.json</code>, the tokenizer, and the weight <i>headers</i> — a few tens of KB, whatever the model's size. Gated or private repos will ask for a token, once.</p>
+  </div>
+
+  <div class="card">
+    <div class="lbl">⛓ Ring plan</div>
+    <pre id="plan" style="max-height:140px">load a model to see how it would be split</pre>
+    <p class="note" style="margin:.5rem 0 0">Layers are apportioned by <b>measured</b> speed — each device times a real GEMM through its own kernel. The MB figure is what that device will actually download and hold.</p>
+  </div>
+
+  <div class="card">
+    <div class="lbl">🎚 Generation</div>
+    <label class="slbl">Tokens <span class="sval" id="vntok">60</span></label>
+    <input type="range" id="ntok" min="10" max="400" step="10" value="60">
+    <label class="slbl">Context length <span class="sval" id="vctxLen">64</span></label>
+    <input type="range" id="ctxLen" min="16" max="512" step="16" value="64">
+    <p class="note" style="margin:.3rem 0 .6rem">There is no KV cache — every token re-runs the whole window, so context length is the main cost per token.</p>
+    <label class="slbl">Temperature ÷100 <span class="sval" id="vtemp">0</span></label>
+    <input type="range" id="temp" min="0" max="150" step="5" value="0">
+    <p class="note" style="margin:.3rem 0 .6rem">0 = greedy, which is deterministic and therefore checkable. Above 0, sampling follows the seed so runs stay reproducible.</p>
+    <label class="slbl">Seed</label>
+    <input type="number" id="seed" value="1234" style="width:140px">
+    <div class="row" id="verifyRow" style="display:none;margin-top:10px">
+      <label class="note" style="display:flex;gap:8px;align-items:center;cursor:pointer">
+        <input type="checkbox" id="verify"> Verify afterwards against a single-device run
+        <span>(downloads the whole model here — only sensible for small ones)</span>
+      </label>
+    </div>
+  </div>
+
+  <div class="card">
+    <div class="lbl">✎ Prompt</div>
+    <div style="display:flex;gap:8px;flex-wrap:wrap">
+      <input type="text" id="prompt" value="The quick brown fox" spellcheck="false" style="flex:1;min-width:180px">
+      <button id="genBtn" disabled>Generate</button>
+      <button id="stopBtn" disabled class="danger">Stop</button>
+    </div>
+    <div id="out" style="margin-top:10px"></div>
+    <div style="display:flex;gap:8px;margin-top:10px">
+      <div class="panel"><div class="num" id="tps">—</div><div class="cl">tokens / sec</div></div>
+      <div class="panel"><div class="num" id="tokcount">0</div><div class="cl">tokens</div></div>
+      <div class="panel"><div class="num" id="hops">0</div><div class="cl">ring hops</div></div>
+    </div>
+    <div class="row" style="margin-top:8px"><span class="k">Ring</span><span class="v" id="ringState">idle</span></div>
+  </div>
+
+  <div class="card">
+    <div class="lbl">❋ Log</div>
+    <pre id="log"></pre>
+  </div>
+
+  <p class="note">Needs a secure context (localhost or HTTPS) for WebGPU and cross-device WebRTC. No WebGPU? The identical verified INT8 units run on CPU — slower, but a CPU device and a GPU device produce the same bits, so they can share a ring. There is no plain-float path.</p>
+  <p class="note"><b>Heads up:</b> peers connect directly, so devices in your ring can see each other's IP address. A middle stage never receives the embedding table or the vocabulary, but it does see the hidden states passing through — and the head sees your prompt and output. Run rings with devices and people you trust. Proof of concept, not a hardened service.</p>
+
+  <!-- One-time credential prompt, shown only when a request actually fails for
+       want of one. Never stored: not localStorage, not sessionStorage, not a
+       cookie, and never sent to a peer — each device authenticates itself.
+       Reloading the tab forgets it.
+
+       On a hosted deployment the paste box is hidden entirely and only
+       "Sign in with Hugging Face" is offered: typing a personal access token
+       into a page you do not control is a bad habit even when the code is
+       honest, because you cannot verify that it is. -->
+  <div class="modal" id="tokModal">
+    <div class="box">
+      <h3>❄ Hugging Face access</h3>
+      <p class="note" id="tokWhy">This model needs a token to download.</p>
+      <div id="tokSignIn" style="display:none;margin:14px 0 6px">
+        <button id="tokSignInBtn" style="width:100%">Sign in with Hugging Face</button>
+        <p class="note" style="margin:.6rem 0 0">You are redirected to huggingface.co and back. This page receives a <b>scoped, expiring</b> token — read access to repositories, nothing else — held in memory for this tab only. No token is ever typed into this page, and none is sent to other devices.</p>
+      </div>
+      <div id="tokPasteRow">
+        <input type="password" id="tokInput" placeholder="hf_…" spellcheck="false" autocomplete="off">
+        <p class="note" style="margin:0">Kept <b>in memory for this tab only</b>: never written to disk or storage, never put in a URL, never logged, and never sent to other devices — each device is asked for its own. Create a <b>read</b> token at huggingface.co/settings/tokens.</p>
+      </div>
+      <div class="acts">
+        <button id="tokCancel" class="small danger">Cancel</button>
+        <button id="tokOk" class="small">Use token</button>
+      </div>
+    </div>
+  </div>
+
+  <script src="traincore.js"></script>
+  <script src="verified_core.js"></script>
+  <script src="safetensors.js"></script>
+  <script src="hf.js"></script>
+  <script src="arch.js"></script>
+  <script src="tokenizer.js"></script>
+  <script src="shard.js"></script>
+  <script src="wire.js"></script>
+  <script src="infer.js"></script>
+  <script src="webgpu.js"></script>
+  <script src="app.js"></script>
+</body>
+</html>

public/infer.js

@@ -0,0 +1,268 @@
+// Forward-only transformer, split at layer boundaries, for real HF models.
+//
+// Every matrix product goes through the verified INT8 units — the same
+// block-scaled quantize -> exact LUT/DP4A multiply -> exact int32 accumulate ->
+// pinned f32 epilogue as the rest of DaisyChain. Nothing here computes in
+// plain float except the elementwise parts that have no matmul in them
+// (norms, softmax, RoPE, the activation), exactly as the trainer does it.
+//
+// The pass is cut into three callable pieces so they can run on different
+// machines:
+//
+//   embed(ids)        head stage: token (+ learned position) embedding
+//   runLayers(x)      any stage:  its own contiguous layers
+//   readout(x)        head stage: final norm + lm_head -> logits
+//
+// Architecture differences live in the spec (see arch.js), never in branches
+// scattered through the maths: `spec.norm`, `spec.gated`, `spec.rope`,
+// `spec.kvHeads`. A Llama block and a GPT-2 block take the same path here.
+(function (root) {
+  "use strict";
+
+  let TC, V, SH;
+
+  // ---- norms ------------------------------------------------------------------
+  // RMSNorm (Llama): x * w / sqrt(mean(x^2) + eps) — no mean subtraction.
+  // LayerNorm (GPT-2): (x - mu) / sigma * w + b.
+  // Both are elementwise after a row reduction, so there is no matmul to send
+  // through the units, and both run in f64-accumulated JS — which IEEE requires
+  // to be exactly rounded, so every device agrees.
+  function rmsNorm(x, rows, C, w, eps) {
+    const y = new Float32Array(rows * C);
+    for (let r = 0; r < rows; r++) {
+      let s = 0;
+      for (let j = 0; j < C; j++) { const v = x[r * C + j]; s += v * v; }
+      const inv = 1 / Math.sqrt(s / C + eps);
+      for (let j = 0; j < C; j++) y[r * C + j] = x[r * C + j] * inv * w[j];
+    }
+    return y;
+  }
+  function layerNorm(x, rows, C, w, b, eps) {
+    const y = new Float32Array(rows * C);
+    for (let r = 0; r < rows; r++) {
+      let mu = 0;
+      for (let j = 0; j < C; j++) mu += x[r * C + j];
+      mu /= C;
+      let v = 0;
+      for (let j = 0; j < C; j++) { const d = x[r * C + j] - mu; v += d * d; }
+      const inv = 1 / Math.sqrt(v / C + eps);
+      for (let j = 0; j < C; j++) y[r * C + j] = (x[r * C + j] - mu) * inv * w[j] + (b ? b[j] : 0);
+    }
+    return y;
+  }
+  function norm(spec, x, rows, C, w, b) {
+    return spec.norm === "rms" ? rmsNorm(x, rows, C, w, spec.normEps)
+                               : layerNorm(x, rows, C, w, b, spec.normEps);
+  }
+
+  // ---- activations ------------------------------------------------------------
+  const silu = (v) => v / (1 + Math.exp(-v));
+  // tanh-approximate GELU: what GPT-2 was trained with, so it is the correct
+  // function here rather than an approximation of the erf form.
+  function gelu(v) {
+    return 0.5 * v * (1 + Math.tanh(0.7978845608028654 * (v + 0.044715 * v * v * v)));
+  }
+
+  // ---- RoPE -------------------------------------------------------------------
+  // Rotary embeddings applied per head, in the half-split layout HF uses:
+  // dims [0, hd/2) pair with [hd/2, hd). Positions are absolute, and because
+  // there is no KV cache every token re-runs the whole window, so position i
+  // is simply the row index.
+  function ropeTables(hd, theta, maxT) {
+    const half = hd >> 1;
+    const cos = new Float32Array(maxT * half), sin = new Float32Array(maxT * half);
+    for (let p = 0; p < maxT; p++)
+      for (let i = 0; i < half; i++) {
+        const f = p / Math.pow(theta, (2 * i) / hd);
+        cos[p * half + i] = Math.cos(f);
+        sin[p * half + i] = Math.sin(f);
+      }
+    return { cos, sin, half };
+  }
+  // x is rows x (nHeads*hd), rows = T; rotate each head in place.
+  function applyRope(x, T, nHeads, hd, rope, posOffset) {
+    const half = rope.half, stride = nHeads * hd;
+    for (let t = 0; t < T; t++) {
+      const p = (posOffset || 0) + t;
+      for (let h = 0; h < nHeads; h++) {
+        const o = t * stride + h * hd;
+        for (let i = 0; i < half; i++) {
+          const c = rope.cos[p * half + i], s = rope.sin[p * half + i];
+          const a = x[o + i], b = x[o + half + i];
+          x[o + i] = a * c - b * s;
+          x[o + half + i] = b * c + a * s;
+        }
+      }
+    }
+  }
+
+  // ---- verified matmul --------------------------------------------------------
+  // X is m x k, W is k x n (row-major). Weights are stored k x n at load time
+  // (see loadStage), so nothing is transposed per call.
+  async function vmm(X, W, m, k, n, ctx, bias) {
+    const out = await V.vgemmBlock(X, W, { m, k, n, batch: 1 }, ctx.L, ctx.bgemm, ctx.audit);
+    if (bias) for (let i = 0; i < m; i++) for (let j = 0; j < n; j++) out[i * n + j] += bias[j];
+    return out;
+  }
+
+  // ---- one layer --------------------------------------------------------------
+  async function layerForward(S, x, ly) {
+    const { spec, ctx } = S, C = spec.hidden, T = S.T;
+    const hd = spec.headDim, nH = spec.heads, nKV = spec.kvHeads;
+    const qDim = nH * hd, kvDim = nKV * hd;
+
+    // ---- attention
+    const h1 = norm(spec, x, T, C, ly.nrm1, ly.nrm1b);
+    let q, k, v;
+    if (spec.qkvFused) {
+      // GPT-2 packs q,k,v into one (C x 3C) projection — one GEMM, then split.
+      const qkv = await vmm(h1, ly.Wqkv, T, C, 3 * C, ctx, ly.bqkv);
+      q = new Float32Array(T * C); k = new Float32Array(T * C); v = new Float32Array(T * C);
+      for (let t = 0; t < T; t++) {
+        q.set(qkv.subarray(t * 3 * C, t * 3 * C + C), t * C);
+        k.set(qkv.subarray(t * 3 * C + C, t * 3 * C + 2 * C), t * C);
+        v.set(qkv.subarray(t * 3 * C + 2 * C, t * 3 * C + 3 * C), t * C);
+      }
+    } else {
+      [q, k, v] = await Promise.all([
+        vmm(h1, ly.Wq, T, C, qDim, ctx, ly.bq),
+        vmm(h1, ly.Wk, T, C, kvDim, ctx, ly.bk),
+        vmm(h1, ly.Wv, T, C, kvDim, ctx, ly.bv),
+      ]);
+    }
+    if (spec.rope) { applyRope(q, T, nH, hd, S.rope, 0); applyRope(k, T, nKV, hd, S.rope, 0); }
+
+    // Grouped-query attention: several query heads share one kv head. Rather
+    // than materialising repeated kv (memory this project does not have to
+    // spare), the head index is mapped when reading.
+    const group = nH / nKV;
+    const scale = 1 / Math.sqrt(hd);
+    const ctxOut = new Float32Array(T * qDim);
+    // Scores and context are the two attention GEMMs. They are small per head
+    // (T x hd and T x T), and the fused kernels in webgpu.js expect the
+    // trainer's uniform-head layout, so at general head geometry they are run
+    // through the same verified block GEMM per head — every product still goes
+    // through the units, and the CPU mirror and GPU kernel agree bit-for-bit.
+    for (let h = 0; h < nH; h++) {
+      const kvh = Math.floor(h / group);
+      const qh = new Float32Array(T * hd), kh = new Float32Array(T * hd), vh = new Float32Array(T * hd);
+      for (let t = 0; t < T; t++) {
+        qh.set(q.subarray(t * qDim + h * hd, t * qDim + h * hd + hd), t * hd);
+        kh.set(k.subarray(t * kvDim + kvh * hd, t * kvDim + kvh * hd + hd), t * hd);
+        vh.set(v.subarray(t * kvDim + kvh * hd, t * kvDim + kvh * hd + hd), t * hd);
+      }
+      const khT = TC.transpose(kh, T, hd);                       // hd x T
+      const scores = await V.vgemmBlock(qh, khT, { m: T, k: hd, n: T, batch: 1 }, ctx.L, ctx.bgemm, ctx.audit);
+      const a = new Float32Array(T * T);                          // causal softmax
+      for (let i = 0; i < T; i++) {
+        let mx = -Infinity;
+        for (let j = 0; j <= i; j++) mx = Math.max(mx, scores[i * T + j] * scale);
+        let z = 0;
+        for (let j = 0; j <= i; j++) { const e = Math.exp(scores[i * T + j] * scale - mx); a[i * T + j] = e; z += e; }
+        for (let j = 0; j <= i; j++) a[i * T + j] /= z;
+      }
+      const oh = await V.vgemmBlock(a, vh, { m: T, k: T, n: hd, batch: 1 }, ctx.L, ctx.bgemm, ctx.audit);
+      for (let t = 0; t < T; t++) ctxOut.set(oh.subarray(t * hd, t * hd + hd), t * qDim + h * hd);
+    }
+    const attn = await vmm(ctxOut, ly.Wo, T, qDim, C, ctx, ly.bo);
+    const x2 = new Float32Array(T * C);
+    for (let i = 0; i < x2.length; i++) x2[i] = x[i] + attn[i];
+
+    // ---- MLP
+    const h2 = norm(spec, x2, T, C, ly.nrm2, ly.nrm2b);
+    let hid;
+    if (spec.gated) {
+      // SwiGLU: down(silu(gate(x)) * up(x))
+      const [g, u] = await Promise.all([
+        vmm(h2, ly.Wgate, T, C, spec.inter, ctx, null),
+        vmm(h2, ly.Wup, T, C, spec.inter, ctx, null),
+      ]);
+      hid = g;
+      for (let i = 0; i < hid.length; i++) hid[i] = silu(hid[i]) * u[i];
+    } else {
+      hid = await vmm(h2, ly.Wfc, T, C, spec.inter, ctx, ly.bfc);
+      for (let i = 0; i < hid.length; i++) hid[i] = gelu(hid[i]);
+    }
+    const down = await vmm(hid, ly.Wdown, T, spec.inter, C, ctx, ly.bdown);
+    const out = new Float32Array(T * C);
+    for (let i = 0; i < out.length; i++) out[i] = x2[i] + down[i];
+    return out;
+  }
+
+  // ---- stage ------------------------------------------------------------------
+  function makeStage(spec, st, w, ctx, T) {
+    const S = { spec, st, w, ctx, T: T || Math.min(spec.maxPos, 128) };
+    if (spec.rope) S.rope = ropeTables(spec.headDim, spec.ropeTheta, S.T + 1);
+    return S;
+  }
+
+  function embed(S, ids) {
+    const { spec } = S, C = spec.hidden, T = S.T;
+    const x = new Float32Array(T * C);
+    for (let i = 0; i < T; i++) {
+      const id = ids[i];
+      for (let j = 0; j < C; j++) x[i * C + j] = S.w.emb[id * C + j];
+    }
+    if (S.w.pos)                                    // GPT-2 learned positions
+      for (let i = 0; i < T; i++)
+        for (let j = 0; j < C; j++) x[i * C + j] += S.w.pos[i * C + j];
+    return x;
+  }
+
+  async function runLayers(S, x) {
+    for (const ly of S.w.layers) x = await layerForward(S, x, ly);
+    return x;
+  }
+
+  // Only the last position's logits are needed to pick the next token, and at
+  // a 150k-token vocabulary that turns the largest GEMM in the model into a
+  // single row — the biggest single saving in the ring.
+  async function readout(S, x) {
+    const { spec, ctx } = S, C = spec.hidden, T = S.T;
+    const y = norm(spec, x, T, C, S.w.nrmF, S.w.nrmFb);
+    const last = y.subarray((T - 1) * C, T * C);
+    return vmm(last, S.w.lmHead, 1, C, spec.vocab, ctx, null);
+  }
+
+  // ---- sampling ---------------------------------------------------------------
+  function mulberry32(a) { return function () { a |= 0; a = a + 0x6D2B79F5 | 0; let t = Math.imul(a ^ a >>> 15, 1 | a); t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t; return ((t ^ t >>> 14) >>> 0) / 4294967296; }; }
+  function pickToken(logits, opts) {
+    const o = opts || {}, temp = o.temperature ?? 0, vocab = logits.length;
+    if (!temp) {
+      let best = 0, bv = -Infinity;
+      for (let j = 0; j < vocab; j++) if (logits[j] > bv) { bv = logits[j]; best = j; }
+      return best;
+    }
+    const k = Math.min(o.topK || 40, vocab);
+    const idx = Array.from({ length: vocab }, (_, i) => i).sort((a, b) => logits[b] - logits[a]).slice(0, k);
+    let mx = -Infinity;
+    for (const i of idx) mx = Math.max(mx, logits[i] / temp);
+    let z = 0;
+    const p = idx.map(i => { const e = Math.exp(logits[i] / temp - mx); z += e; return e; });
+    let r = (o.rng || Math.random)() * z;
+    for (let i = 0; i < idx.length; i++) { r -= p[i]; if (r <= 0) return idx[i]; }
+    return idx[idx.length - 1];
+  }
+
+  // ---- single-device reference ------------------------------------------------
+  async function generateLocal(stages, ids, nTokens, opts) {
+    const head = stages[0], T = head.T;
+    const out = [...ids];
+    for (let n = 0; n < nTokens; n++) {
+      const win = new Int32Array(T);
+      const tail = out.slice(-T);
+      for (let i = 0; i < tail.length; i++) win[T - tail.length + i] = tail[i];
+      let x = embed(head, win);
+      for (const S of stages) x = await runLayers(S, x);
+      out.push(pickToken(await readout(head, x), opts));
+    }
+    return out;
+  }
+
+  const api = { makeStage, embed, runLayers, readout, pickToken, generateLocal,
+                rmsNorm, layerNorm, norm, ropeTables, applyRope, silu, gelu, mulberry32 };
+  if (typeof module !== "undefined" && module.exports) {
+    TC = require("./traincore.js"); V = require("./verified_core.js"); SH = require("./shard.js");
+    module.exports = api;
+  } else { TC = root.TrainCore; V = root.Verified; SH = root.Shard; root.Infer = api; }
+})(typeof self !== "undefined" ? self : this);

public/luts_meta.json

@@ -0,0 +1 @@
+{"mul": [256, 256], "requant": 65536, "relu": 256, "shift": 8}

public/mul_lut.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5cecff7e22049d0083ad9ee36dcf0695222c61621bacfd5a401c7b133abe892d
+size 131072

public/relu_lut.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2acb03ba7520467636273208563f8e733494748f4aa5ac2dba89d9560050da79
+size 256

public/requant_lut.bin

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:173444ecfa293433329a333289983a665c481d913e9fd1c2778b55380ca4dd31
+size 65536

public/safetensors.js

@@ -0,0 +1,128 @@
+// safetensors, read a piece at a time.
+//
+// The format is what makes this project's memory pooling honest. A file is:
+//
+//   [u64 headerLen][JSON header][ tensor bytes, back to back ]
+//
+// and the header gives every tensor's exact byte range. So a device does not
+// need the model — it needs its own layers, and it can ask the CDN for exactly
+// those bytes. Nothing else is ever downloaded, decoded, or held.
+//
+// That is the difference between "we split the model across devices" and
+// "one device downloads the model and hands out pieces". Only the first one
+// actually lets a group run something none of them could hold.
+(function (root) {
+  "use strict";
+
+  // ---- dtype decoding ---------------------------------------------------------
+  // Everything becomes f32, because that is what the verified units quantize
+  // from. F16 and BF16 are the common storage formats and both widen exactly —
+  // no rounding, no device-dependent behaviour, so a CPU device and a GPU
+  // device still agree bit-for-bit after loading.
+  const BYTES = { F64: 8, F32: 4, F16: 2, BF16: 2, I64: 8, I32: 4, I16: 2, I8: 1, U8: 1, BOOL: 1 };
+
+  // BF16 is the top 16 bits of an f32 — widening is a shift, exactly.
+  function bf16ToF32(u16, out) {
+    const u32 = new Uint32Array(out.buffer, out.byteOffset, out.length);
+    for (let i = 0; i < u16.length; i++) u32[i] = u16[i] << 16;
+    return out;
+  }
+  // F16 -> F32 by hand rather than via Float16Array, which is not everywhere
+  // yet. Subnormals and inf/nan are handled explicitly; every f16 has an exact
+  // f32 representation, so this is a widening, not a conversion.
+  function f16ToF32(u16, out) {
+    for (let i = 0; i < u16.length; i++) {
+      const h = u16[i], s = (h & 0x8000) >> 15, e = (h & 0x7C00) >> 10, f = h & 0x03FF;
+      let v;
+      if (e === 0) v = f === 0 ? 0 : Math.pow(2, -14) * (f / 1024);
+      else if (e === 0x1F) v = f === 0 ? Infinity : NaN;
+      else v = Math.pow(2, e - 15) * (1 + f / 1024);
+      out[i] = s ? -v : v;
+    }
+    return out;
+  }
+
+  function toF32(dtype, bytes) {
+    const n = bytes.byteLength / BYTES[dtype];
+    if (dtype === "F32") {
+      // may be unaligned inside a range response — copy rather than view
+      const out = new Float32Array(n);
+      new Uint8Array(out.buffer).set(bytes);
+      return out;
+    }
+    const out = new Float32Array(n);
+    if (dtype === "F16" || dtype === "BF16") {
+      const u16 = new Uint16Array(n);
+      new Uint8Array(u16.buffer).set(bytes);
+      return dtype === "BF16" ? bf16ToF32(u16, out) : f16ToF32(u16, out);
+    }
+    if (dtype === "F64") {
+      const f64 = new Float64Array(n);
+      new Uint8Array(f64.buffer).set(bytes);
+      for (let i = 0; i < n; i++) out[i] = f64[i];
+      return out;
+    }
+    throw new Error(`unsupported tensor dtype ${dtype} — weights must be F32, F16, BF16 or F64`);
+  }
+
+  // ---- header ----------------------------------------------------------------
+  // The first 8 bytes are a u64 length. It is read as two u32s because a JS
+  // number cannot hold a u64 — but a header that genuinely needed the high word
+  // would be gigabytes, so a nonzero high word means the file is not what it
+  // claims and is refused rather than truncated into something plausible.
+  function parseHeader(buf) {
+    const dv = new DataView(buf);
+    const lo = dv.getUint32(0, true), hi = dv.getUint32(4, true);
+    if (hi !== 0) throw new Error("safetensors header length is implausibly large — not a safetensors file");
+    if (lo <= 0 || lo > buf.byteLength - 8) throw new Error("safetensors header is truncated");
+    let json;
+    try { json = JSON.parse(new TextDecoder().decode(new Uint8Array(buf, 8, lo))); }
+    catch (e) { throw new Error("safetensors header is not valid JSON — not a safetensors file"); }
+    const dataStart = 8 + lo;
+    const tensors = new Map();
+    for (const [name, t] of Object.entries(json)) {
+      if (name === "__metadata__") continue;
+      if (!t || !t.dtype || !Array.isArray(t.shape) || !Array.isArray(t.data_offsets))
+        throw new Error(`safetensors header entry "${name}" is malformed`);
+      const [s, e] = t.data_offsets;
+      const elems = t.shape.reduce((a, b) => a * b, 1);
+      const want = elems * (BYTES[t.dtype] || 0);
+      if (BYTES[t.dtype] && e - s !== want)
+        throw new Error(`tensor "${name}": header claims ${e - s} bytes for a ${t.shape.join("x")} ${t.dtype} (expected ${want})`);
+      tensors.set(name, { name, dtype: t.dtype, shape: t.shape, elems,
+                          start: dataStart + s, end: dataStart + e, bytes: e - s });
+    }
+    return { tensors, dataStart, metadata: json.__metadata__ || {} };
+  }
+
+  // How much a set of tensors will cost to hold, before fetching any of it.
+  // Reported in the UI so a device can see whether its slice fits BEFORE it
+  // spends the bandwidth finding out.
+  function f32Bytes(tensors) {
+    let n = 0;
+    for (const t of tensors) n += t.elems * 4;
+    return n;
+  }
+
+  // ---- coalescing -------------------------------------------------------------
+  // A stage's tensors are contiguous in the file far more often than not
+  // (safetensors writes them in the order they were registered, which follows
+  // layer order). Merging adjacent ranges turns ~9 requests per layer into
+  // roughly one per stage. Gaps below `slack` are downloaded and discarded
+  // because one extra request costs more than a few unused kilobytes.
+  function coalesce(tensors, slack) {
+    const gap = slack == null ? 1 << 20 : slack;
+    const sorted = [...tensors].sort((a, b) => a.start - b.start);
+    const runs = [];
+    for (const t of sorted) {
+      const last = runs[runs.length - 1];
+      if (last && t.start - last.end <= gap) { last.end = Math.max(last.end, t.end); last.tensors.push(t); }
+      else runs.push({ start: t.start, end: t.end, tensors: [t] });
+    }
+    return runs;
+  }
+
+  const api = { BYTES, parseHeader, toF32, coalesce, f32Bytes, f16ToF32, bf16ToF32 };
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.Safetensors = api;
+})(typeof self !== "undefined" ? self : this);

public/shard.js

@@ -0,0 +1,155 @@
+// Model sharding — the piece DaisyChain-Train does not have.
+//
+// DaisyChain-Train pools COMPUTE: every node holds a full replica, so a model
+// bigger than one machine cannot be trained. Inference is where that limit can
+// be lifted, because a forward pass is a chain: layer l needs layer l-1's
+// OUTPUT, never its WEIGHTS. So the layers live on different machines and the
+// activation travels instead.
+//
+// And because safetensors gives every tensor an exact byte range, each device
+// fetches only its own layers straight from the Hub. No device — not even the
+// head — ever holds the whole model. That is what makes the pooling real
+// rather than a redistribution of something one machine already had to load.
+//
+// The ring shape is forced by weight tying. When lm_head is tied to the
+// embedding table, the largest tensor in the model is needed at BOTH ends: to
+// embed the prompt and to produce the logits. Copying it to the last stage
+// would hand back most of the memory just pooled, so the last stage returns
+// its hidden state to the head, which owns the embedding once and does both
+// ends of the pass.
+(function (root) {
+  "use strict";
+
+  // ---- the plan ---------------------------------------------------------------
+  // Stage 0 is the HEAD: embeddings, final norm, lm_head. Every stage may also
+  // own a contiguous run of layers, apportioned by MEASURED capacity — the
+  // same self-calibrating idea as cluster.py's capacity_score, except what is
+  // balanced is layers per device rather than batch per device.
+  //
+  // Largest-remainder apportionment, so the plan is a pure function of the
+  // capacity report: every device derives the same plan from the same inputs
+  // and the plan never has to be trusted, only compared.
+  function planStages(spec, caps) {
+    const n = caps.length;
+    if (n < 1) throw new Error("no devices to plan across");
+    const total = caps.reduce((a, d) => a + Math.max(1e-6, d.capacity), 0);
+    const exact = caps.map(d => spec.layers * Math.max(1e-6, d.capacity) / total);
+    const floor = exact.map(Math.floor);
+    let left = spec.layers - floor.reduce((a, b) => a + b, 0);
+    const order = exact.map((e, i) => [e - floor[i], i]).sort((a, b) => b[0] - a[0] || a[1] - b[1]);
+    for (let i = 0; i < order.length && left > 0; i++, left--) floor[order[i][1]]++;
+    const stages = [];
+    let lo = 0;
+    for (let i = 0; i < n; i++) {
+      const hi = lo + floor[i];
+      stages.push({ id: caps[i].id, index: i, lo, hi, head: i === 0,
+                    backend: caps[i].backend, capacity: caps[i].capacity });
+      lo = hi;
+    }
+    // A device with no layers is only worth a hop if it is the head, which has
+    // real work (embed + unembed). Anyone else empty is dropped.
+    return stages.filter(s => s.head || s.hi > s.lo).map((s, i) => ({ ...s, index: i }));
+  }
+
+  // What a stage will cost to hold, computed from the file's own header BEFORE
+  // any weight bytes move — so a device can see whether its slice fits before
+  // spending the bandwidth finding out.
+  function stageBytes(spec, available, st, ArchMod) {
+    const names = ArchMod.tensorsFor(spec, available, st);
+    let n = 0;
+    for (const name of names) n += available.get(name).elems * 4;   // f32 in memory
+    return n;
+  }
+
+  // ---- arranging fetched tensors into what the forward pass wants -------------
+  // Two shape conventions have to be reconciled here, and getting it wrong is
+  // silent: torch.nn.Linear stores weights (out, in) while the GEMM wants
+  // (in, out), whereas GPT-2's Conv1D already stores (in, out). A wrong
+  // transpose does not throw — it produces a model that generates confident
+  // nonsense — so the layout comes from the spec and is applied once, at load.
+  function toKN(w, outDim, inDim, layout) {
+    if (layout === "in_out") return w;                    // already k x n
+    const out = new Float32Array(w.length);
+    for (let o = 0; o < outDim; o++)
+      for (let i = 0; i < inDim; i++) out[i * outDim + o] = w[o * inDim + i];
+    return out;
+  }
+
+  function stageWeights(spec, st, got, ArchMod) {
+    const resolve = ArchMod.resolver(new Map([...got.keys()].map(k => [k, true])));
+    const pick = (name, opt) => { const r = resolve(name, opt); return r ? got.get(r) : null; };
+    const C = spec.hidden, L = spec.weightLayout;
+    const w = { layers: [] };
+
+    if (st.head) {
+      const h = ArchMod.headTensors(spec);
+      w.emb = pick(h.emb);                                // (vocab, C) — used as a lookup, not a GEMM
+      w.pos = pick(h.pos, true);
+      w.nrmF = pick(h.nrmF, true);
+      w.nrmFb = pick(h.nrmFb, true);
+      // lm_head as k x n = (C, vocab). When tied, that is embᵀ.
+      const lm = pick(h.lmHead, true);
+      w.lmHead = lm ? toKN(lm, spec.vocab, C, L) : transposeEmb(w.emb, spec.vocab, C);
+      if (!w.nrmF) w.nrmF = new Float32Array(C).fill(1);  // a model without a final norm weight
+    }
+
+    const qDim = spec.heads * spec.headDim, kvDim = spec.kvHeads * spec.headDim;
+    for (let l = st.lo; l < st.hi; l++) {
+      const t = ArchMod.layerTensors(spec, l);
+      const ly = { nrm1: pick(t.nrm1), nrm1b: pick(t.nrm1b, true),
+                   nrm2: pick(t.nrm2), nrm2b: pick(t.nrm2b, true) };
+      if (spec.qkvFused) {
+        ly.Wqkv = toKN(pick(t.Wqkv), 3 * C, C, L);
+        ly.bqkv = pick(t.bqkv, true);
+      } else {
+        ly.Wq = toKN(pick(t.Wq), qDim, C, L); ly.bq = pick(t.bq, true);
+        ly.Wk = toKN(pick(t.Wk), kvDim, C, L); ly.bk = pick(t.bk, true);
+        ly.Wv = toKN(pick(t.Wv), kvDim, C, L); ly.bv = pick(t.bv, true);
+      }
+      ly.Wo = toKN(pick(t.Wo), C, qDim, L); ly.bo = pick(t.bo, true);
+      if (spec.gated) {
+        ly.Wgate = toKN(pick(t.Wgate), spec.inter, C, L);
+        ly.Wup = toKN(pick(t.Wup), spec.inter, C, L);
+      } else {
+        ly.Wfc = toKN(pick(t.Wfc), spec.inter, C, L); ly.bfc = pick(t.bfc, true);
+      }
+      ly.Wdown = toKN(pick(t.Wdown), C, spec.inter, L); ly.bdown = pick(t.bdown, true);
+      w.layers.push(ly);
+    }
+    return w;
+  }
+  function transposeEmb(emb, vocab, C) {
+    const out = new Float32Array(emb.length);
+    for (let v = 0; v < vocab; v++)
+      for (let c = 0; c < C; c++) out[c * vocab + v] = emb[v * C + c];
+    return out;
+  }
+
+  // ---- hashes -----------------------------------------------------------------
+  // FNV-1a over raw bytes, identical to the function DaisyChain-Web hashes
+  // replicas with, so hashes stay comparable across the projects.
+  function fnv1a(bytes) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < bytes.length; i++) { h ^= bytes[i]; h = Math.imul(h, 0x01000193); }
+    return h >>> 0;
+  }
+  function hashF32(a) { return fnv1a(new Uint8Array(a.buffer, a.byteOffset, a.byteLength)); }
+
+  // The model fingerprint every stage repeats in its status. Derived from the
+  // repo id, revision and the tensor index — NOT from the weights, because no
+  // device reads all of them. It answers "are we all running the same model?",
+  // which is the question that matters when stages hold disjoint pieces.
+  function modelFingerprint(repo, revision, tensors) {
+    const parts = [repo, revision || "main"];
+    for (const name of [...tensors.keys()].sort()) {
+      const t = tensors.get(name);
+      parts.push(`${name}:${t.dtype}:${t.shape.join("x")}:${t.start}:${t.end}`);
+    }
+    return fnv1a(new TextEncoder().encode(parts.join("|")));
+  }
+
+  const api = { planStages, stageBytes, stageWeights, toKN, transposeEmb,
+                fnv1a, hashF32, modelFingerprint };
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.Shard = api;
+})(typeof self !== "undefined" ? self : this);

public/traincore.js

@@ -0,0 +1,99 @@
+// Shared training math — pure JS. Used as the WebGPU fallback in the browser,
+// and unit-tested directly in Node. Model: linear regression Y = X @ W (MSE).
+// The GEMMs here are exactly what the WebGPU compute shader replaces.
+(function (root) {
+  "use strict";
+
+  // C(m×n) = A(m×k) @ B(k×n), all Float32Array row-major
+  function matmul(A, B, m, k, n) {
+    const C = new Float32Array(m * n);
+    for (let i = 0; i < m; i++) {
+      for (let p = 0; p < k; p++) {
+        const a = A[i * k + p];
+        if (a === 0) continue;
+        const bo = p * n, co = i * n;
+        for (let j = 0; j < n; j++) C[co + j] += a * B[bo + j];
+      }
+    }
+    return C;
+  }
+
+  function transpose(A, rows, cols) {
+    const T = new Float32Array(rows * cols);
+    for (let i = 0; i < rows; i++)
+      for (let j = 0; j < cols; j++) T[j * rows + i] = A[i * cols + j];
+    return T;
+  }
+
+  // Forward + loss + gradient for one shard.
+  //   X: n×din,  W: din×dout,  y: n×dout
+  //   gradW = (2/n) * Xᵀ @ (X@W - y)   (din×dout)
+  // matmulFn lets the browser swap in the WebGPU GEMM (same signature as matmul).
+  function forwardLossGrad(X, y, W, n, din, dout, matmulFn) {
+    const mm = matmulFn || matmul;
+    const pred = mm(X, W, n, din, dout);          // n×dout   (GEMM)
+    const resid = new Float32Array(n * dout);
+    let loss = 0;
+    for (let i = 0; i < n * dout; i++) {
+      const r = pred[i] - y[i];
+      resid[i] = r; loss += r * r;
+    }
+    loss /= (n * dout);
+    const Xt = transpose(X, n, din);              // din×n
+    const g = mm(Xt, resid, din, n, dout);        // din×dout (GEMM)
+    const scale = 2 / n;
+    for (let i = 0; i < g.length; i++) g[i] *= scale;
+    return { pred, loss, gradW: g };
+  }
+
+  function applyGrad(W, gradAvg, lr) {
+    for (let i = 0; i < W.length; i++) W[i] -= lr * gradAvg[i];
+  }
+
+  // average a list of gradient Float32Arrays (equal weight)
+  // ORDER MATTERS: float addition is not associative, so every replica MUST
+  // pass the gradients in the same order (the leader's roster order) or their
+  // averages differ in the last bits and the weights fork. Never self-first.
+  function averageGrads(grads) {
+    const out = new Float32Array(grads[0].length);
+    for (const g of grads) for (let i = 0; i < g.length; i++) out[i] += g[i];
+    for (let i = 0; i < out.length; i++) out[i] /= grads.length;
+    return out;
+  }
+
+  // DaisyAdam — Adam with bias correction, applied to the cluster-averaged
+  // gradient. State is a pure function of the gradient sequence, so every peer
+  // that averages the same gradients keeps bit-identical moments: no optimizer
+  // state ever crosses the wire. Momentum also smooths the noisy STE gradients
+  // coming out of the verified INT8 units.
+  function makeAdam(dim, opts) {
+    const o = opts || {};
+    const lr = o.lr ?? 0.02, b1 = o.beta1 ?? 0.9, b2 = o.beta2 ?? 0.999, eps = o.eps ?? 1e-8;
+    const m = new Float32Array(dim), v = new Float32Array(dim);
+    let t = 0;
+    return {
+      name: `adam(lr=${lr})`,
+      // returns the update u; caller does W[i] -= u[i]
+      step(g) {
+        t++;
+        const c1 = 1 - Math.pow(b1, t), c2 = 1 - Math.pow(b2, t);
+        const u = new Float32Array(dim);
+        for (let i = 0; i < dim; i++) {
+          m[i] = b1 * m[i] + (1 - b1) * g[i];
+          v[i] = b2 * v[i] + (1 - b2) * g[i] * g[i];
+          u[i] = lr * (m[i] / c1) / (Math.sqrt(v[i] / c2) + eps);
+        }
+        return u;
+      },
+      // snapshot/restore the moments — this is what lets a device that joins
+      // mid-run become bit-identical with the group (weights alone are not
+      // enough; Adam's m/v/t must match too)
+      getState() { return { m: Float32Array.from(m), v: Float32Array.from(v), t }; },
+      setState(s) { m.set(s.m); v.set(s.v); t = s.t; },
+    };
+  }
+
+  const api = { matmul, transpose, forwardLossGrad, applyGrad, averageGrads, makeAdam };
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.TrainCore = api;
+})(typeof self !== "undefined" ? self : this);

public/verified_core.js

@@ -0,0 +1,496 @@
+// Verified INT8 compute — the emulated GPU logic, in the browser.
+// A layer's forward runs THROUGH the units: quantize -> LUT multiply -> requant
+// -> optional ReLU -> dequant. Backward is a straight-through estimator (the
+// integer path has no gradient), so ordinary float weights still learn.
+// Same units as the Python/Docker DaisyChain; here they're lookup tables.
+(function (root) {
+  "use strict";
+
+  let TC;   // TrainCore (matmul/transpose) — resolved per environment at the end
+
+  function quantize(X) {
+    let mx = 0; for (let i = 0; i < X.length; i++) { const a = Math.abs(X[i]); if (a > mx) mx = a; }
+    const scale = Math.max(mx / 127, 1e-8);
+    const q = new Int8Array(X.length);
+    for (let i = 0; i < X.length; i++) { let v = Math.round(X[i] / scale); q[i] = v < -128 ? -128 : v > 127 ? 127 : v; }
+    return { q, scale };
+  }
+
+  // int8 matmul via the verified multiply LUT: acc(m×n) = sum_k mulLUT[Xq,Wq]
+  function lutMatmulJS(Xq, Wq, m, k, n, L) {
+    const C = new Int32Array(m * n), mul = L.mul;
+    for (let i = 0; i < m; i++) {
+      for (let p = 0; p < k; p++) {
+        const au = (Xq[i * k + p] & 0xFF) * 256, wo = p * n, co = i * n;
+        for (let j = 0; j < n; j++) C[co + j] += mul[au + (Wq[wo + j] & 0xFF)];
+      }
+    }
+    return C;
+  }
+
+  // ---- 3xINT8 fast-accurate GEMM --------------------------------------------
+  // The CUTLASS example-27 "3xTF32" scheme, ported to the verified units:
+  // split each float into a coarse int8 part plus an int8-quantized residual,
+  // run three EXACT LUT GEMMs (hi·hi, hi·lo, lo·hi), drop the negligible
+  // lo·lo, and recombine. Same big/small decomposition NVIDIA uses to recover
+  // near-fp32 accuracy from TF32 tensor cores — here it recovers ~14-bit
+  // accuracy from the 8-bit units, at 3× the unit ops. Every product still
+  // goes through the verified mul8 LUT.
+  function quantize2(X) {
+    const hi = quantize(X);
+    const r = new Float32Array(X.length);
+    for (let i = 0; i < X.length; i++) r[i] = X[i] - hi.q[i] * hi.scale;
+    const lo = quantize(r);
+    return { hi, lo };
+  }
+  function combine3(hh, hl, lh, x, w, len) {
+    const out = new Float32Array(len);
+    const shh = x.hi.scale * w.hi.scale, shl = x.hi.scale * w.lo.scale, slh = x.lo.scale * w.hi.scale;
+    for (let i = 0; i < len; i++) out[i] = hh[i] * shh + hl[i] * shl + lh[i] * slh;
+    return out;
+  }
+  function lutMatmul3JS(Xf, Wf, m, k, n, L) {          // sync, CPU LUT path
+    const x = quantize2(Xf), w = quantize2(Wf);
+    return combine3(lutMatmulJS(x.hi.q, w.hi.q, m, k, n, L),
+                    lutMatmulJS(x.hi.q, w.lo.q, m, k, n, L),
+                    lutMatmulJS(x.lo.q, w.hi.q, m, k, n, L), x, w, m * n);
+  }
+  async function lutMatmul3(Xf, Wf, m, k, n, L, matmulInt8) {  // any backend
+    const x = quantize2(Xf), w = quantize2(Wf);
+    const mm = matmulInt8 || lutMatmulJS;
+    const [hh, hl, lh] = await Promise.all([
+      mm(x.hi.q, w.hi.q, m, k, n, L),
+      mm(x.hi.q, w.lo.q, m, k, n, L),
+      mm(x.lo.q, w.hi.q, m, k, n, L),
+    ]);
+    return combine3(hh, hl, lh, x, w, m * n);
+  }
+
+  // ---- block-scaled verified GEMM (CUTLASS ex. 67/81 blockwise scaling) ------
+  // Per-ROW scales for the activations and per-COLUMN scales for the weights:
+  // the integer math through the mul8 LUT is completely unchanged — only the
+  // dequant uses rs[row]·cs[col] instead of one tensor-wide product, so a single
+  // outlier no longer crushes the quantization resolution of every other
+  // row/column. One LUT pass at this granularity beats the per-tensor 3-pass.
+  function quantizeRows(X, rows, cols) {
+    const q = new Int8Array(rows * cols), s = new Float32Array(rows);
+    for (let r = 0; r < rows; r++) {
+      let mx = 0;
+      for (let c = 0; c < cols; c++) { const a = Math.abs(X[r * cols + c]); if (a > mx) mx = a; }
+      const sc = Math.max(mx / 127, 1e-8); s[r] = sc;
+      for (let c = 0; c < cols; c++) {
+        const v = Math.round(X[r * cols + c] / sc);
+        q[r * cols + c] = v < -128 ? -128 : v > 127 ? 127 : v;
+      }
+    }
+    return { q, s };
+  }
+  function quantizeCols(W, rows, cols) {
+    const q = new Int8Array(rows * cols), s = new Float32Array(cols);
+    for (let c = 0; c < cols; c++) {
+      let mx = 0;
+      for (let r = 0; r < rows; r++) { const a = Math.abs(W[r * cols + c]); if (a > mx) mx = a; }
+      s[c] = Math.max(mx / 127, 1e-8);
+    }
+    for (let r = 0; r < rows; r++)
+      for (let c = 0; c < cols; c++) {
+        const v = Math.round(W[r * cols + c] / s[c]);
+        q[r * cols + c] = v < -128 ? -128 : v > 127 ? 127 : v;
+      }
+    return { q, s };
+  }
+
+  // ---- B2B MLP chain (CUTLASS ex. 13 two-GEMM fusion + ex. 23 epilogue
+  // reduction), respecced for cross-device exactness ---------------------------
+  // The MLP is the one back-to-back GEMM pair with no layernorm/softmax between
+  // (ReLU is already fused in the epilogue), so the intermediate h1 can be
+  // quantized ON the GPU and fed straight to the second GEMM. Two rules make
+  // that fleet-safe:
+  //   1. The per-row |max| (ex. 23) uses only comparisons — exact on any
+  //      hardware, order-independent — and comes back to JS as ~1KB.
+  //   2. Scale DERIVATION (two divisions) stays in JS f64, which IEEE requires
+  //      to be exactly rounded and is therefore identical on every device.
+  //      WGSL division is only 2.5 ULP — a fork waiting to happen — but WGSL
+  //      multiply/add are correctly rounded and floor/clamp are exact. So the
+  //      quantize step is respecced from  round(x / scale)  to
+  //      floor(f32(x * invScale) + 0.5)  — floor(x+0.5) IS Math.round's tie
+  //      rule — and the fround-stepped mirror below is bit-identical to the
+  //      GPU kernel, which is exact-gated against it at init.
+  // NOTE this changes which int8 a value on a rounding boundary lands on
+  // (≤1 step) vs quantizeRows, so old and new builds cannot co-train — the
+  // divergence guard stops such mixed groups by design.
+  function rowAbsMax(X, rows, cols) {
+    const mx = new Float32Array(rows);
+    for (let r = 0; r < rows; r++) {
+      let m = 0;
+      for (let c = 0; c < cols; c++) { const a = Math.abs(X[r * cols + c]); if (a > m) m = a; }
+      mx[r] = m;
+    }
+    return mx;
+  }
+  function scalesFromAbsMax(mx) {                // f64 divisions: exactly rounded, device-identical
+    const scale = new Float32Array(mx.length), inv = new Float32Array(mx.length);
+    for (let i = 0; i < mx.length; i++) {
+      scale[i] = Math.max(mx[i] / 127, 1e-8);
+      inv[i] = 1 / scale[i];                     // recip of the STORED f32 scale
+    }
+    return { scale, inv };
+  }
+  function quantizeRowsInv(X, rows, cols, inv) { // bit-exact mirror of the GPU quantize kernel
+    const q = new Int8Array(rows * cols);
+    for (let r = 0; r < rows; r++) {
+      const iv = inv[r];
+      for (let c = 0; c < cols; c++) {
+        const n = Math.floor(f32(f32(X[r * cols + c] * iv) + 0.5));
+        q[r * cols + c] = n < -128 ? -128 : n > 127 ? 127 : n;
+      }
+    }
+    return q;
+  }
+  // the chained MLP: X @ W1 -> ReLU (fused) -> absmax -> quantize -> @ W2.
+  //   d = { m, k, h, n };  gpuMlp (from webgpu.js) runs both GEMMs + the
+  // on-GPU quantize with one tiny absmax readback between; without it the CPU
+  // mirror chain runs — SAME math, so mixed GPU/CPU fleets stay bit-identical.
+  async function vmlpBlock(Xf, W1f, W2f, d, L, gpuMlp, audit) {
+    const x = quantizeRows(Xf, d.m, d.k);
+    const w1 = quantizeCols(W1f, d.k, d.h);
+    const w2 = quantizeCols(W2f, d.h, d.n);
+    if (gpuMlp) {
+      const r = await gpuMlp(x.q, w1.q, w2.q, x.s, w1.s, w2.s, d);
+      if (audit && audit.due()) {
+        // audit BOTH live GEMMs: gemm1 against the units directly; gemm2 by
+        // reconstructing its exact operand through the proven quantize mirror
+        const bad1 = auditTile(x.q, w1.q, x.s, w1.s, { m: d.m, k: d.k, n: d.h, relu: true }, r.h1, L, audit.cells);
+        if (bad1) { audit.fail("mlp gemm1: " + bad1); return r; }
+        const sc = scalesFromAbsMax(rowAbsMax(r.h1, d.m, d.h));
+        const hq = quantizeRowsInv(r.h1, d.m, d.h, sc.inv);
+        const bad2 = auditTile(hq, w2.q, sc.scale, w2.s, { m: d.m, k: d.h, n: d.n }, r.out, L, audit.cells);
+        if (bad2) audit.fail("mlp gemm2: " + bad2);
+      }
+      return r;
+    }
+    const h1 = bgemmJS(x.q, w1.q, x.s, w1.s, { m: d.m, k: d.k, n: d.h, batch: 1, relu: true }, L);
+    const sc = scalesFromAbsMax(rowAbsMax(h1, d.m, d.h));
+    const hq = quantizeRowsInv(h1, d.m, d.h, sc.inv);
+    const out = bgemmJS(hq, w2.q, sc.scale, w2.s, { m: d.m, k: d.h, n: d.n, batch: 1 }, L);
+    return { h1, out };
+  }
+
+  // ---- epilogue mirror -------------------------------------------------------
+  // BIT-EXACT mirror of the WGSL epilogue `f32(s) * a * b`. WGSL rounds to f32
+  // after the int->float conversion and after EACH multiply; plain JS would do
+  // the whole chain in f64 and round once, which differs in the last ulp. That
+  // last-ulp gap is what used to force a tolerance into the kernel gates —
+  // mirroring the rounding exactly is what lets the gates compare with `!==`.
+  const f32 = Math.fround;
+  function epi(s, a, b) { return f32(f32(f32(s) * a) * b); }
+
+  // f32 equality at the BIT level: `!==` says -0 === 0, but replicas are
+  // compared by hashing raw bytes, so an audit that can't see the sign of zero
+  // could pass a device that later forks the fleet. (Real ISAs have non-IEEE
+  // modes that flush -0 to +0 — e.g. RDNA2 output modifiers / legacy muls.)
+  const _fb = new Float32Array(1), _ub = new Uint32Array(_fb.buffer);
+  function bitDiff(a, b) { _fb[0] = a; const u = _ub[0]; _fb[0] = b; return u !== _ub[0]; }
+
+  // CPU mirror of the fused GPU kernel: batched int8 GEMM through the LUT with
+  // the epilogue (block dequant + optional ReLU) applied before returning —
+  // exactly what the WGSL kernel does on-device. d.acc=true returns the raw
+  // int32 accumulator instead (the exact oracle the fused kernel normally hides).
+  function bgemmJS(Xq, Wq, rs, cs, d, L) {
+    const { m, k, n } = d, batch = d.batch || 1, relu = !!d.relu, mul = L.mul;
+    const raw = !!d.acc;
+    const out = raw ? new Int32Array(batch * m * n) : new Float32Array(batch * m * n);
+    const acc = new Int32Array(n);
+    for (let bz = 0; bz < batch; bz++) {
+      const xo = bz * m * k, wo = bz * k * n, oo = bz * m * n, co = bz * n;
+      for (let i = 0; i < m; i++) {
+        acc.fill(0);
+        const xrow = xo + i * k;
+        for (let p = 0; p < k; p++) {
+          const au = (Xq[xrow + p] & 0xFF) * 256, wrow = wo + p * n;
+          for (let j = 0; j < n; j++) acc[j] += mul[au + (Wq[wrow + j] & 0xFF)];
+        }
+        const orow = oo + i * n;
+        if (raw) { for (let j = 0; j < n; j++) out[orow + j] = acc[j]; continue; }
+        const rscale = rs[bz * m + i];
+        for (let j = 0; j < n; j++) {
+          const v = epi(acc[j], rscale, cs[co + j]);
+          out[orow + j] = relu && v < 0 ? 0 : v;
+        }
+      }
+    }
+    return out;
+  }
+
+  // Recompute a handful of RANDOM output cells of a live GEMM through the LUT
+  // mirror and compare against what the kernel produced. Sampling cells instead
+  // of whole matrices makes this cheap enough to run continuously, at the real
+  // shapes training uses — not once at boot on toy inputs.
+  // STRATIFIED sampling. Uniformly random cells are the wrong instrument for
+  // the bugs that actually occur here: a bounds-guard off-by-one or a pack-tail
+  // padding bug lives on the LAST row/column, and uniform sampling finds that
+  // with probability ~1/n per cell — at the 16512-wide logits GEMM, never. So
+  // the first cells are the structurally dangerous ones (corners, last row,
+  // last column, last batch) chosen deterministically, and the remainder are
+  // random interior cells that catch diffuse bugs. Same principle as poisoning
+  // the buffer pool: construct the dangerous case, don't wait to land on it.
+  function auditTile(Xq, Wq, rs, cs, d, got, L, nCells) {
+    const { m, k, n } = d, batch = d.batch || 1, relu = !!d.relu, mul = L.mul;
+    const N = nCells || 8;
+    const edges = [[0, m - 1, n - 1], [0, 0, n - 1], [0, m - 1, 0], [0, 0, 0],
+                   [batch - 1, m - 1, n - 1], [batch - 1, 0, 0]];
+    for (let t = 0; t < N; t++) {
+      let bz, i, j;
+      if (t < edges.length) { bz = edges[t][0]; i = edges[t][1]; j = edges[t][2]; }
+      else { bz = (Math.random() * batch) | 0; i = (Math.random() * m) | 0; j = (Math.random() * n) | 0; }
+      let acc = 0;
+      const xrow = bz * m * k + i * k, wo = bz * k * n;
+      for (let p = 0; p < k; p++) acc += mul[(Xq[xrow + p] & 0xFF) * 256 + (Wq[wo + p * n + j] & 0xFF)];
+      let v = epi(acc, rs[bz * m + i], cs[bz * n + j]);
+      if (relu && v < 0) v = 0;
+      const idx = (bz * m + i) * n + j;
+      if (bitDiff(got[idx], v))
+        return `GEMM audit failed at [b${bz},${i},${j}] shape ${m}x${k}x${n}: kernel ${Object.is(got[idx], -0) ? "-0" : got[idx]} vs units ${Object.is(v, -0) ? "-0" : v}`;
+    }
+    return null;
+  }
+
+  // ---- exact mirror of the split-K f32 GEMM ----------------------------------
+  // The f32 backward GEMM was the last kernel gated by a TOLERANCE (allclose at
+  // 1e-3) — and this project's own gate mutation test shows allclose waving
+  // through real bugs. The reason was real though: split-K accumulates in a
+  // different ORDER than a naive reference, so bit-equality against the naive
+  // one is impossible. The fix is the same as the epilogue mirror: reproduce
+  // the kernel's order exactly, then compare with `!==`.
+  //   partials: for z in 0..S-1, sum p in [z*ks, min(k,(z+1)*ks)) in order
+  //   reduce:   sum the S partials in ascending z
+  // `fma` selects the rounding schedule for `s + a*b`: WGSL PERMITS a compiler
+  // to contract that into a fused multiply-add (one rounding) instead of two.
+  // Which one the device does is a fact about the device, so the gate tries
+  // both and reports which matches rather than assuming.
+  function fgemmMirror(A, Bm, d, fma) {
+    const { m, k, n } = d, transA = !!d.transA;
+    const S = k > 4096 ? Math.min(16, Math.ceil(k / 2048)) : 1;
+    const ks = Math.ceil(k / S);
+    const out = new Float32Array(m * n);
+    for (let row = 0; row < m; row++)
+      for (let col = 0; col < n; col++) {
+        let acc = 0;                                    // reduce pass, ascending z
+        for (let z = 0; z < S; z++) {
+          const p0 = z * ks, p1 = Math.min(k, p0 + ks);
+          let s = 0;                                    // one partial, in order
+          for (let p = p0; p < p1; p++) {
+            const a = transA ? A[p * m + row] : A[row * k + p];
+            s = fma ? f32(s + a * Bm[p * n + col])      // single rounding
+                    : f32(s + f32(a * Bm[p * n + col]));
+          }
+          acc = f32(acc + s);
+        }
+        out[row * n + col] = acc;
+      }
+    return out;
+  }
+
+  // ---- live audits for the fused attention kernels ---------------------------
+  // The attention kernels had exact INIT gates but nothing at live shapes —
+  // the exact gap the GEMM audit exists to close, left open on the kernels with
+  // the trickiest indexing (head-strided gather, scatter write-back). These
+  // recompute individual output cells from the units, stratified like
+  // auditTile: last/first token pair, last head, last channel first, then
+  // random. Cost is hd (or T) multiply-adds per cell.
+  function auditAttScores(qq, kq, qs, ks, d, got, L, nCells) {
+    const { B, T, heads, hd } = d, C = heads * hd, mul = L.mul, raw = !!d.acc;
+    const N = nCells || 8;
+    const edges = [[B - 1, heads - 1, T - 1, T - 1], [0, 0, 0, 0],
+                   [0, heads - 1, T - 1, 0], [B - 1, 0, 0, T - 1]];
+    for (let t = 0; t < N; t++) {
+      let bi, h, ti, tj;
+      if (t < edges.length) { bi = edges[t][0]; h = edges[t][1]; ti = edges[t][2]; tj = edges[t][3]; }
+      else { bi = (Math.random() * B) | 0; h = (Math.random() * heads) | 0;
+             ti = (Math.random() * T) | 0; tj = (Math.random() * T) | 0; }
+      const bz = bi * heads + h;
+      const qo = (bi * T + ti) * C + h * hd, ko = (bi * T + tj) * C + h * hd;
+      let acc = 0;
+      for (let p = 0; p < hd; p++) acc += mul[(qq[qo + p] & 0xFF) * 256 + (kq[ko + p] & 0xFF)];
+      const v = raw ? acc : epi(acc, qs[(bi * T + ti) * heads + h], ks[(bi * T + tj) * heads + h]);
+      const idx = (bz * T + ti) * T + tj;
+      if (raw ? got[idx] !== v : bitDiff(got[idx], v))
+        return `att.scores audit failed at [b${bi},h${h},${ti},${tj}] B${B}T${T}H${heads}d${hd}: kernel ${got[idx]} vs units ${v}`;
+    }
+    return null;
+  }
+  function auditAttCtx(aq, vq, as, vs, d, got, L, nCells) {
+    const { B, T, heads, hd } = d, C = heads * hd, mul = L.mul, raw = !!d.acc;
+    const N = nCells || 8;
+    const edges = [[B - 1, heads - 1, T - 1, hd - 1], [0, 0, 0, 0],
+                   [0, heads - 1, T - 1, 0], [B - 1, 0, 0, hd - 1]];
+    for (let t = 0; t < N; t++) {
+      let bi, h, ti, j;
+      if (t < edges.length) { bi = edges[t][0]; h = edges[t][1]; ti = edges[t][2]; j = edges[t][3]; }
+      else { bi = (Math.random() * B) | 0; h = (Math.random() * heads) | 0;
+             ti = (Math.random() * T) | 0; j = (Math.random() * hd) | 0; }
+      const bz = bi * heads + h, ao = (bz * T + ti) * T;
+      let acc = 0;
+      for (let tj = 0; tj < T; tj++)
+        acc += mul[(aq[ao + tj] & 0xFF) * 256 + (vq[(bi * T + tj) * C + h * hd + j] & 0xFF)];
+      const v = raw ? acc : epi(acc, as[bz * T + ti], vs[(bi * heads + h) * hd + j]);
+      const idx = (bi * T + ti) * C + h * hd + j;
+      if (raw ? got[idx] !== v : bitDiff(got[idx], v))
+        return `att.ctx audit failed at [b${bi},h${h},${ti},${j}] B${B}T${T}H${heads}d${hd}: kernel ${got[idx]} vs units ${v}`;
+    }
+    return null;
+  }
+
+  // block-scaled verified GEMM, float in → float out.
+  //   d = { m, k, n, batch=1, relu=false }; X is (batch·m)×k, W is batch×(k×n)
+  // gpuBgemm (from webgpu.js) runs the batched kernel with the fused epilogue;
+  // without it the CPU LUT mirror runs. Every product goes through the units.
+  async function vgemmBlock(Xf, Wf, d, L, gpuBgemm, audit) {
+    const { m, k, n } = d, batch = d.batch || 1;
+    const x = quantizeRows(Xf, batch * m, k);
+    let wq, ws;
+    if (batch === 1) {
+      const w = quantizeCols(Wf, k, n); wq = w.q; ws = w.s;
+    } else {
+      wq = new Int8Array(batch * k * n); ws = new Float32Array(batch * n);
+      for (let bz = 0; bz < batch; bz++) {
+        const w = quantizeCols(Wf.subarray(bz * k * n, (bz + 1) * k * n), k, n);
+        wq.set(w.q, bz * k * n); ws.set(w.s, bz * n);
+      }
+    }
+    if (gpuBgemm) {
+      const out = await gpuBgemm(x.q, wq, x.s, ws, d);
+      // continuous re-verification at LIVE shapes: the boot gate only ever saw
+      // toy inputs, so sample a few real cells against the units as we go
+      if (audit && audit.due()) {
+        const bad = auditTile(x.q, wq, x.s, ws, d, out, L, audit.cells);
+        if (bad) audit.fail(bad);
+      }
+      return out;
+    }
+    return bgemmJS(x.q, wq, x.s, ws, d, L);
+  }
+
+  // ---- gather-fused attention through the units (CUTLASS ex. 36/52) ----------
+  // The kernels read q/k/v/ctx directly in their natural BT×C layout with
+  // head-strided indexing — no JS gather copies, no kᵀ transpose, and the
+  // context write scatters straight back into BT×C. Quantization stays
+  // block-scaled: q/k/a per (token,head) row, v per (head,channel) column.
+  // The (BT·heads)×hd row view of q/k IS the contiguous buffer, so
+  // quantizeRows(q, BT·heads, hd) gives per-(token,head) scales for free.
+  function quantizeHeadCols(v, B, T, heads, hd) {   // per (batch,head,channel) column
+    const C = heads * hd;
+    const q = new Int8Array(B * T * C), s = new Float32Array(B * heads * hd);
+    for (let bi = 0; bi < B; bi++)
+      for (let h = 0; h < heads; h++)
+        for (let j = 0; j < hd; j++) {
+          let mx = 0;
+          for (let ti = 0; ti < T; ti++) {
+            const a = Math.abs(v[(bi * T + ti) * C + h * hd + j]);
+            if (a > mx) mx = a;
+          }
+          const sc = Math.max(mx / 127, 1e-8);
+          s[(bi * heads + h) * hd + j] = sc;
+          for (let ti = 0; ti < T; ti++) {
+            const idx = (bi * T + ti) * C + h * hd + j;
+            const w = Math.round(v[idx] / sc);
+            q[idx] = w < -128 ? -128 : w > 127 ? 127 : w;
+          }
+        }
+    return { q, s };
+  }
+  // scores S[bz,ti,tj] = q_row(bi,ti,h) · k_row(bi,tj,h), every product via the LUT
+  // d.acc=true returns the raw int32 accumulator (exact oracle for the kernel gate)
+  function attScoresJS(qq, kq, qs, ks, d, L) {
+    const { B, T, heads, hd } = d, C = heads * hd, mul = L.mul, raw = !!d.acc;
+    const out = raw ? new Int32Array(B * heads * T * T) : new Float32Array(B * heads * T * T);
+    for (let bi = 0; bi < B; bi++) for (let h = 0; h < heads; h++) {
+      const bz = bi * heads + h;
+      for (let ti = 0; ti < T; ti++) {
+        const qo = (bi * T + ti) * C + h * hd, rscale = qs[(bi * T + ti) * heads + h];
+        for (let tj = 0; tj < T; tj++) {
+          const ko = (bi * T + tj) * C + h * hd;
+          let acc = 0;
+          for (let p = 0; p < hd; p++) acc += mul[(qq[qo + p] & 0xFF) * 256 + (kq[ko + p] & 0xFF)];
+          out[(bz * T + ti) * T + tj] = raw ? acc : epi(acc, rscale, ks[(bi * T + tj) * heads + h]);
+        }
+      }
+    }
+    return out;
+  }
+  // ctx[(bi,ti),(h,j)] = Σ_tj a[bz,ti,tj]·v[(bi,tj),(h,j)] — scatter fused into BT×C
+  function attCtxJS(aq, vq, as, vs, d, L) {
+    const { B, T, heads, hd } = d, C = heads * hd, mul = L.mul, raw = !!d.acc;
+    const out = raw ? new Int32Array(B * T * C) : new Float32Array(B * T * C);
+    for (let bi = 0; bi < B; bi++) for (let h = 0; h < heads; h++) {
+      const bz = bi * heads + h;
+      for (let ti = 0; ti < T; ti++) {
+        const ao = (bz * T + ti) * T, rscale = as[bz * T + ti];
+        for (let j = 0; j < hd; j++) {
+          let acc = 0;
+          for (let tj = 0; tj < T; tj++)
+            acc += mul[(aq[ao + tj] & 0xFF) * 256 + (vq[(bi * T + tj) * C + h * hd + j] & 0xFF)];
+          out[(bi * T + ti) * C + h * hd + j] = raw ? acc : epi(acc, rscale, vs[(bi * heads + h) * hd + j]);
+        }
+      }
+    }
+    return out;
+  }
+
+  // one verified layer forward; returns float out (+ cache for STE backward).
+  // Every product goes through the verified INT8 multiply (mul8 LUT) with exact
+  // int32 accumulation — i.e. an emulated INT8 tensor-core GEMM — then dequant.
+  async function linearFwd(X, W, m, k, n, L, useRelu, matmulInt8) {
+    const xq = quantize(X), wq = quantize(W);
+    const acc = await (matmulInt8 || lutMatmulJS)(xq.q, wq.q, m, k, n, L);  // verified multiply
+    const dq = xq.scale * wq.scale;
+    const out = new Float32Array(m * n);
+    const mask = useRelu ? new Uint8Array(m * n) : null;
+    for (let i = 0; i < m * n; i++) {
+      let v = acc[i] * dq;
+      if (useRelu) { if (v > 0) mask[i] = 1; else v = 0; }
+      out[i] = v;
+    }
+    return { out, mask };
+  }
+
+  // 2-layer MLP: X→H (relu) →dout. Forward through verified units, MSE loss.
+  async function forward(X, y, W1, W2, D, L, matmulInt8) {
+    const { n, din, h, dout } = D;
+    const l1 = await linearFwd(X, W1, n, din, h, L, true, matmulInt8);
+    const l2 = await linearFwd(l1.out, W2, n, h, dout, L, false, matmulInt8);
+    const resid = new Float32Array(n * dout); let loss = 0;
+    for (let i = 0; i < resid.length; i++) { const r = l2.out[i] - y[i]; resid[i] = r; loss += r * r; }
+    loss /= resid.length;
+    return { loss, resid, z1: l1.out, mask1: l1.mask };
+  }
+
+  // STE backward (verified matmul treated as float X@W). Returns flat [gW1, gW2].
+  function backward(X, W1, W2, fwd, D) {
+    const { n, din, h, dout } = D;
+    const { resid, z1, mask1 } = fwd;
+    const s = 2 / n;
+    const dout_ = new Float32Array(resid.length);
+    for (let i = 0; i < resid.length; i++) dout_[i] = resid[i] * s;
+    const mm = TC.matmul, tr = TC.transpose;
+    const gW2 = mm(tr(z1, n, h), dout_, h, n, dout);          // z1ᵀ @ dout
+    const dz1 = mm(dout_, tr(W2, h, dout), n, dout, h);        // dout @ W2ᵀ
+    for (let i = 0; i < dz1.length; i++) if (!mask1[i]) dz1[i] = 0;  // relu grad
+    const gW1 = mm(tr(X, n, din), dz1, din, n, h);            // Xᵀ @ dz1
+    const g = new Float32Array(gW1.length + gW2.length);
+    g.set(gW1, 0); g.set(gW2, gW1.length);
+    return g;
+  }
+
+  function splitApply(W1, W2, gAvg, lr) {
+    for (let i = 0; i < W1.length; i++) W1[i] -= lr * gAvg[i];
+    for (let j = 0; j < W2.length; j++) W2[j] -= lr * gAvg[W1.length + j];
+  }
+
+  const api = { quantize, quantize2, quantizeRows, quantizeCols, quantizeHeadCols, lutMatmulJS, lutMatmul3JS, lutMatmul3,
+                bgemmJS, vgemmBlock, auditTile, epi, attScoresJS, attCtxJS, linearFwd, forward, backward, splitApply,
+                rowAbsMax, scalesFromAbsMax, quantizeRowsInv, vmlpBlock, bitDiff,
+                auditAttScores, auditAttCtx, fgemmMirror };
+  if (typeof module !== "undefined" && module.exports) { TC = require("./traincore.js"); module.exports = api; }
+  else { TC = root.TrainCore; root.Verified = api; }
+})(typeof self !== "undefined" ? self : this);

public/webgpu.js

@@ -0,0 +1,996 @@
+// WebGPU INT8 matmul via the verified multiply LUT — the emulated GPU logic
+// running on the browser's GPU. Automatic CPU fallback (same LUT) for machines
+// without WebGPU (e.g. old PCs via Supermium). initCompute() returns
+//   { backend, label, matmulInt8(Xq, Wq, m, k, n, L) -> Int32Array }
+// matching Verified.lutMatmulJS, so the trainer is device-blind.
+//
+// High-throughput path: when the browser exposes WGSL's
+// packed_4x8_integer_dot_product feature, we use dot4I8Packed — it compiles to
+// the GPU's DP4A/INT8 dot-product hardware (the same units tensor-core INT8
+// paths are built on): 4 exact int8 MACs per instruction, int32 accumulation,
+// and 4× less memory traffic from packing. Because int8×int8→int32 is exact,
+// it is bit-identical to the verified mul8 LUT — and we PROVE that at init by
+// cross-checking random matmuls against the LUT before trusting it. If the
+// hardware ever disagrees with the units, we fall back to the LUT shader.
+(function (root) {
+  "use strict";
+
+  const WGSL_LUT = `
+    @group(0) @binding(0) var<storage, read> Xq  : array<i32>;   // int8 byte per elem
+    @group(0) @binding(1) var<storage, read> Wq  : array<i32>;
+    @group(0) @binding(2) var<storage, read> lut : array<i32>;   // 65536 signed products
+    @group(0) @binding(3) var<storage, read_write> C : array<i32>;
+    @group(0) @binding(4) var<uniform> dims : vec3<u32>;         // m, k, n
+    @compute @workgroup_size(8, 8)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let m = dims.x; let k = dims.y; let n = dims.z;
+      let row = gid.x; let col = gid.y;
+      if (row >= m || col >= n) { return; }
+      var s : i32 = 0;
+      for (var p = 0u; p < k; p = p + 1u) {
+        let au = u32(Xq[row * k + p] & 255);
+        let bu = u32(Wq[p * n + col] & 255);
+        s = s + lut[au * 256u + bu];
+      }
+      C[row * n + col] = s;
+    }`;
+
+  // ---- B2B MLP chain kernels (CUTLASS ex. 13 + 23) ---------------------------
+  // ROWMAX: per-row |max| of a GEMM's f32 output, fused into the same command
+  // encoder (ex. 23 epilogue reduction). Non-negative f32 bit patterns order
+  // like u32, so atomicMax on bitcast(abs(v)) computes an EXACT max, in any
+  // execution order, on any hardware — nothing here can round.
+  const WGSL_ROWMAX = `
+    @group(0) @binding(0) var<storage, read> O : array<f32>;
+    @group(0) @binding(1) var<storage, read_write> MX : array<atomic<u32>>;
+    @group(0) @binding(2) var<uniform> dims : vec4<u32>;         // m, n, _, _
+    @compute @workgroup_size(8, 8, 1)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let m = dims.x; let n = dims.y;
+      let row = gid.x; let col = gid.y;
+      if (row >= m || col >= n) { return; }
+      atomicMax(&MX[row], bitcast<u32>(abs(O[row * n + col])));
+    }`;
+  // QUANT: h1 (f32, still on the GPU) -> int8 by MULTIPLY with a JS-computed
+  // inverse scale. floor(f32(x*inv)+0.5) uses only ops WGSL guarantees exact
+  // or correctly rounded (mul, add, floor, clamp) — division is 2.5 ULP and
+  // never runs on the GPU. Bit-identical to Verified.quantizeRowsInv, and
+  // exact-gated against it at init. pack=true emits 4 bytes per u32 for the
+  // DP4A kernel; pack=false emits one i32 per element for the LUT kernel.
+  const WGSL_QUANT = (pack) => `
+    @group(0) @binding(0) var<storage, read> H : array<f32>;
+    @group(0) @binding(1) var<storage, read> inv : array<f32>;   // per row
+    @group(0) @binding(2) var<storage, read_write> Q : array<${pack ? "u32" : "i32"}>;
+    @group(0) @binding(3) var<uniform> dims : vec4<u32>;         // m, k, kw, _
+    @compute @workgroup_size(64)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let m = dims.x; let k = dims.y; let kw = dims.z;
+      let idx = gid.x;
+      ${pack ? `
+      if (idx >= m * kw) { return; }
+      let row = idx / kw;
+      var acc : u32 = 0u;
+      for (var b = 0u; b < 4u; b = b + 1u) {
+        let c = (idx % kw) * 4u + b;
+        var q : i32 = 0;
+        if (c < k) {
+          let v = clamp(floor(H[row * k + c] * inv[row] + 0.5), -128.0, 127.0);
+          q = i32(v);
+        }
+        acc = acc | ((u32(q) & 255u) << (8u * b));
+      }
+      Q[idx] = acc;` : `
+      if (idx >= m * k) { return; }
+      let row = idx / k;
+      let v = clamp(floor(H[idx] * inv[row] + 0.5), -128.0, 127.0);
+      Q[idx] = i32(v);`}
+    }`;
+
+  // NOTE: the un-batched DP4A matmul that used to live here was removed. It was
+  // the only kernel with an exact gate, but the transformer stopped calling it
+  // when the block-scaled path landed — so it sat here passing its own gate
+  // while verifying nothing that ran. A gate on a kernel nobody calls is worse
+  // than no gate: it reads like coverage. The batched kernels below are the
+  // ones training uses, and they now carry that exact gate instead.
+
+  // Batched block-scaled GEMM with a FUSED EPILOGUE (CUTLASS ex. 05/24 + 12):
+  // grid z = batch index, so ALL attention heads run in ONE dispatch, and the
+  // epilogue (block dequant rs·cs + optional ReLU) happens before the data
+  // leaves the GPU — f32 out, no int32 readback, no second pass in JS.
+  // Each kernel is emitted in two variants from ONE source string: the live one
+  // (fused epilogue, f32 out) and a `verify` one that writes the raw int32
+  // accumulator instead. The indexing — the part that actually goes wrong — is
+  // textually identical, so gating the verify variant genuinely gates the live
+  // kernel, and the comparison is EXACT (int8xint8->int32 has no rounding to
+  // hide in) instead of an allclose that whole bug classes walk through.
+  const OUT_DECL = (v, b) => `@group(0) @binding(${b}) var<storage, read_write> O : array<${v ? "i32" : "f32"}>;`;
+
+  const WGSL_BG_LUT = (verify) => `
+    @group(0) @binding(0) var<storage, read> Xq  : array<i32>;   // int8 byte per elem
+    @group(0) @binding(1) var<storage, read> Wq  : array<i32>;
+    @group(0) @binding(2) var<storage, read> lut : array<i32>;
+    @group(0) @binding(3) var<storage, read> rs  : array<f32>;   // per (batch,row)
+    @group(0) @binding(4) var<storage, read> cs  : array<f32>;   // per (batch,col)
+    ${OUT_DECL(verify, 5)}
+    @group(0) @binding(6) var<uniform> dims : vec4<u32>;         // m, k, n, flags(1=relu)
+    @compute @workgroup_size(8, 8, 1)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let m = dims.x; let k = dims.y; let n = dims.z;
+      let row = gid.x; let col = gid.y; let bz = gid.z;
+      if (row >= m || col >= n) { return; }
+      var s : i32 = 0;
+      let xo = (bz * m + row) * k;
+      let wo = bz * k * n + col;
+      for (var p = 0u; p < k; p = p + 1u) {
+        let au = u32(Xq[xo + p] & 255);
+        let bu = u32(Wq[wo + p * n] & 255);
+        s = s + lut[au * 256u + bu];
+      }
+      ${verify ? `O[(bz * m + row) * n + col] = s;` : `
+      var v = f32(s) * rs[bz * m + row] * cs[bz * n + col];
+      if ((dims.w & 1u) == 1u && v < 0.0) { v = 0.0; }
+      O[(bz * m + row) * n + col] = v;`}
+    }`;
+
+  // same fused/batched kernel on the DP4A hardware path (Wᵀ packed per batch)
+  const WGSL_BG_DP4 = (verify) => `
+    @group(0) @binding(0) var<storage, read> Xp : array<u32>;
+    @group(0) @binding(1) var<storage, read> Wp : array<u32>;    // per-batch Wᵀ, packed
+    @group(0) @binding(2) var<storage, read> rs : array<f32>;
+    @group(0) @binding(3) var<storage, read> cs : array<f32>;
+    ${OUT_DECL(verify, 4)}
+    @group(0) @binding(5) var<uniform> dims : vec4<u32>;         // m, kw, n, flags
+    @compute @workgroup_size(8, 8, 1)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let m = dims.x; let kw = dims.y; let n = dims.z;
+      let row = gid.x; let col = gid.y; let bz = gid.z;
+      if (row >= m || col >= n) { return; }
+      var s : i32 = 0;
+      let xo = (bz * m + row) * kw;
+      let wo = (bz * n + col) * kw;
+      for (var p = 0u; p < kw; p = p + 1u) {
+        s = s + dot4I8Packed(Xp[xo + p], Wp[wo + p]);
+      }
+      ${verify ? `O[(bz * m + row) * n + col] = s;` : `
+      var v = f32(s) * rs[bz * m + row] * cs[bz * n + col];
+      if ((dims.w & 1u) == 1u && v < 0.0) { v = 0.0; }
+      O[(bz * m + row) * n + col] = v;`}
+    }`;
+
+  // Gather-fused attention (CUTLASS ex. 36/52): kernels index q/k/v directly in
+  // their BT×C layout (head-strided) — no gather copies, no kᵀ transpose — and
+  // the ctx kernel scatters straight back into BT×C. int8×int8→i32 is exact, so
+  // these are bit-identical to the LUT mirrors (proved at init before use).
+  const WGSL_ATT_SCORES = (verify) => `
+    @group(0) @binding(0) var<storage, read> Q : array<i32>;     // int8 per elem, BT×C
+    @group(0) @binding(1) var<storage, read> K : array<i32>;
+    @group(0) @binding(2) var<storage, read> qs : array<f32>;    // per (token,head)
+    @group(0) @binding(3) var<storage, read> ks : array<f32>;
+    ${OUT_DECL(verify, 4)}
+    @group(0) @binding(5) var<uniform> dims : vec4<u32>;         // T, heads, hd, _
+    @compute @workgroup_size(8, 8, 1)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let T = dims.x; let heads = dims.y; let hd = dims.z;
+      let ti = gid.x; let tj = gid.y; let bz = gid.z;
+      if (ti >= T || tj >= T) { return; }
+      let bi = bz / heads; let h = bz % heads;
+      let C = heads * hd;
+      let qo = (bi * T + ti) * C + h * hd;
+      let ko = (bi * T + tj) * C + h * hd;
+      var s : i32 = 0;
+      for (var p = 0u; p < hd; p = p + 1u) { s = s + Q[qo + p] * K[ko + p]; }
+      ${verify ? `O[(bz * T + ti) * T + tj] = s;`
+               : `O[(bz * T + ti) * T + tj] = f32(s) * qs[(bi * T + ti) * heads + h] * ks[(bi * T + tj) * heads + h];`}
+    }`;
+  const WGSL_ATT_CTX = (verify) => `
+    @group(0) @binding(0) var<storage, read> A : array<i32>;     // int8, BH×T×T
+    @group(0) @binding(1) var<storage, read> V : array<i32>;     // int8, BT×C
+    @group(0) @binding(2) var<storage, read> as_ : array<f32>;   // per (bz,row)
+    @group(0) @binding(3) var<storage, read> vs : array<f32>;    // per (batch,head,chan)
+    ${OUT_DECL(verify, 4)}                                       // BT×C (scatter fused)
+    @group(0) @binding(5) var<uniform> dims : vec4<u32>;         // T, heads, hd, _
+    @compute @workgroup_size(8, 8, 1)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let T = dims.x; let heads = dims.y; let hd = dims.z;
+      let ti = gid.x; let j = gid.y; let bz = gid.z;
+      if (ti >= T || j >= hd) { return; }
+      let bi = bz / heads; let h = bz % heads;
+      let C = heads * hd;
+      let ao = (bz * T + ti) * T;
+      var s : i32 = 0;
+      for (var tj = 0u; tj < T; tj = tj + 1u) { s = s + A[ao + tj] * V[(bi * T + tj) * C + h * hd + j]; }
+      ${verify ? `O[(bi * T + ti) * C + h * hd + j] = s;`
+               : `O[(bi * T + ti) * C + h * hd + j] = f32(s) * as_[bz * T + ti] * vs[(bi * heads + h) * hd + j];`}
+    }`;
+
+  // Split-K f32 GEMM (CUTLASS ex. 06) for the STE BACKWARD only — the backward
+  // was always float (the integer path has no gradient); this just moves that
+  // exact float math off the JS thread. Split-K matters for dlnf: M=256, N=32,
+  // K=16512 — 8k outputs with a huge inner loop would idle the GPU, so slices
+  // of K run on separate workgroups and a second tiny pass reduces partials.
+  const WGSL_FGEMM = `
+    @group(0) @binding(0) var<storage, read> A : array<f32>;
+    @group(0) @binding(1) var<storage, read> Bm : array<f32>;
+    @group(0) @binding(2) var<storage, read_write> P : array<f32>;   // S partials
+    @group(0) @binding(3) var<uniform> dims : vec4<u32>;             // m, k, n, flags(bit0=transA, rest=S)
+    @compute @workgroup_size(8, 8, 1)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let m = dims.x; let k = dims.y; let n = dims.z;
+      let transA = (dims.w & 1u) == 1u;
+      let S = dims.w >> 1u;
+      let row = gid.x; let col = gid.y; let z = gid.z;
+      if (row >= m || col >= n) { return; }
+      let ks = (k + S - 1u) / S;
+      let p0 = z * ks;
+      let p1 = min(k, p0 + ks);
+      var s : f32 = 0.0;
+      for (var p = p0; p < p1; p = p + 1u) {
+        let a = select(A[row * k + p], A[p * m + row], transA);
+        s = s + a * Bm[p * n + col];
+      }
+      P[(z * m + row) * n + col] = s;
+    }`;
+  const WGSL_FREDUCE = `
+    @group(0) @binding(0) var<storage, read> P : array<f32>;
+    @group(0) @binding(1) var<storage, read_write> O : array<f32>;
+    @group(0) @binding(2) var<uniform> dims : vec4<u32>;             // mn, S, _, _
+    @compute @workgroup_size(64)
+    fn main(@builtin(global_invocation_id) gid : vec3<u32>) {
+      let mn = dims.x; let S = dims.y;
+      let i = gid.x;
+      if (i >= mn) { return; }
+      var s : f32 = 0.0;
+      for (var z = 0u; z < S; z = z + 1u) { s = s + P[z * mn + i]; }
+      O[i] = s;
+    }`;
+
+  async function loadLUTs(base) {
+    base = base || "";
+    const [mulB, reqB, reluB, meta] = await Promise.all([
+      fetch(base + "mul_lut.bin").then(r => r.arrayBuffer()),
+      fetch(base + "requant_lut.bin").then(r => r.arrayBuffer()),
+      fetch(base + "relu_lut.bin").then(r => r.arrayBuffer()),
+      fetch(base + "luts_meta.json").then(r => r.json()),
+    ]);
+    return { mul: new Int16Array(mulB), requant: new Int8Array(reqB),
+             relu: new Int8Array(reluB), shift: meta.shift };
+  }
+
+  // pack a row-major int8 matrix (rows×cols) into u32 words of 4 bytes along
+  // cols, zero-padded to kw words per row (zeros contribute 0 to the dot)
+  function packRows(Q, rows, cols, kw) {
+    const out = new Uint32Array(rows * kw);
+    const bytes = new Uint8Array(out.buffer);
+    for (let r = 0; r < rows; r++)
+      for (let c = 0; c < cols; c++) bytes[(r * kw * 4) + c] = Q[r * cols + c] & 0xFF;
+    return out;
+  }
+  function transposeI8(Q, rows, cols) {
+    const out = new Int8Array(rows * cols);
+    for (let r = 0; r < rows; r++) for (let c = 0; c < cols; c++) out[c * rows + r] = Q[r * cols + c];
+    return out;
+  }
+
+  // f32 gate equality AT THE BIT LEVEL. JS `!==` says -0 === 0, but the fleet
+  // compares devices by hashing raw bit patterns (FNV over the byte buffer), so
+  // a kernel that flushes -0 to +0 — real hardware has instructions that do
+  // exactly this (RDNA2 output modifiers and DX9-legacy multiplies are
+  // documented as "not IEEE compatible: -0 is flushed to +0") — would pass a
+  // `!==` gate and still fork the weights at the sync guard. The gates must
+  // compare the same thing the hash sees: the bits.
+  const _fb = new Float32Array(1), _ub = new Uint32Array(_fb.buffer);
+  function bitDiff(a, b) { _fb[0] = a; const u = _ub[0]; _fb[0] = b; return u !== _ub[0]; }
+
+  async function initCompute(L) {
+    const cpu = { backend: "cpu", label: "CPU (JS)",
+                  matmulInt8: (Xq, Wq, m, k, n, LL) => root.Verified.lutMatmulJS(Xq, Wq, m, k, n, LL) };
+    if (!(root.navigator && navigator.gpu)) return cpu;
+    try {
+      const adapter = await navigator.gpu.requestAdapter();
+      if (!adapter) return cpu;
+      const device = await adapter.requestDevice();
+      const info = adapter.info || {};
+      const gpuName = info.description || info.vendor || "WebGPU";
+
+      // LUT pipeline (always built — the fallback and the verification oracle)
+      const lutModule = device.createShaderModule({ code: WGSL_LUT });
+      const lutPipe = device.createComputePipeline({ layout: "auto", compute: { module: lutModule, entryPoint: "main" } });
+      const lut32 = new Int32Array(L.mul);   // widen int16 -> int32
+      const lutBuf = device.createBuffer({ size: lut32.byteLength, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST });
+      device.queue.writeBuffer(lutBuf, 0, lut32);
+      const mkPipe = (code) => device.createComputePipeline({ layout: "auto",
+        compute: { module: device.createShaderModule({ code }), entryPoint: "main" } });
+      // The verify variant doesn't reference the scale buffers, so `layout:auto`
+      // would strip those bindings and the bind group would silently mismatch.
+      // An EXPLICIT layout keeps both variants binding-compatible — which is the
+      // point: they must differ only in the final write, nothing else.
+      const mkLayout = (spec) => device.createBindGroupLayout({
+        entries: spec.map((t, i) => ({ binding: i, visibility: GPUShaderStage.COMPUTE,
+          buffer: { type: t === "u" ? "uniform" : t === "rw" ? "storage" : "read-only-storage" } })) });
+      const mkPipeL = (code, layout) => device.createComputePipeline({
+        layout: device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+        compute: { module: device.createShaderModule({ code }), entryPoint: "main" } });
+      const bgLutLayout = mkLayout(["r", "r", "r", "r", "r", "rw", "u"]);
+      const bgDp4Layout = mkLayout(["r", "r", "r", "r", "rw", "u"]);
+      const attLayout = mkLayout(["r", "r", "r", "r", "rw", "u"]);
+      const rowmaxLayout = mkLayout(["r", "rw", "u"]);
+      const quantLayout = mkLayout(["r", "r", "rw", "u"]);
+      const rowmaxPipe = mkPipeL(WGSL_ROWMAX, rowmaxLayout);
+      const quantI32Pipe = mkPipeL(WGSL_QUANT(false), quantLayout);
+      const quantPackPipe = mkPipeL(WGSL_QUANT(true), quantLayout);
+      // live + verify variants, compiled from the same source (see WGSL_* above)
+      const bgLutPipe = mkPipeL(WGSL_BG_LUT(false), bgLutLayout), bgLutVPipe = mkPipeL(WGSL_BG_LUT(true), bgLutLayout);
+      const scoresPipe = mkPipeL(WGSL_ATT_SCORES(false), attLayout), scoresVPipe = mkPipeL(WGSL_ATT_SCORES(true), attLayout);
+      const ctxPipe = mkPipeL(WGSL_ATT_CTX(false), attLayout), ctxVPipe = mkPipeL(WGSL_ATT_CTX(true), attLayout);
+
+      // gather-fused attention kernels. The gate runs the VERIFY variant of the
+      // same source and compares the int32 accumulator with `!==` — exact, no
+      // tolerance — then checks the fused epilogue against a bit-exact JS mirror
+      // of the WGSL rounding. Swept over several shapes, incl. odd/ragged ones,
+      // because head-strided addressing is where these kernels can go wrong.
+      let att = { scores: (qq, kq, qs, ks, d) => gpuAttScores(device, d.acc ? scoresVPipe : scoresPipe, qq, kq, qs, ks, d),
+                  ctx: (aq, vq, as, vs, d) => gpuAttCtx(device, d.acc ? ctxVPipe : ctxPipe, aq, vq, as, vs, d) };
+      try {
+        for (const d0 of [{ B: 2, T: 8, heads: 2, hd: 8 }, { B: 1, T: 32, heads: 2, hd: 16 },
+                          { B: 3, T: 7, heads: 3, hd: 5 }, { B: 2, T: 33, heads: 4, hd: 8 }]) {
+          const nQ = d0.B * d0.T * d0.heads * d0.hd;
+          const qq = new Int8Array(nQ), kq = new Int8Array(nQ), vq = new Int8Array(nQ);
+          for (let i = 0; i < nQ; i++) { qq[i] = (Math.random() * 256 - 128) | 0; kq[i] = (Math.random() * 256 - 128) | 0; vq[i] = (Math.random() * 256 - 128) | 0; }
+          const qs = Float32Array.from({ length: d0.B * d0.T * d0.heads }, () => Math.random() + 0.5);
+          const ks = Float32Array.from({ length: d0.B * d0.T * d0.heads }, () => Math.random() + 0.5);
+          const aq = new Int8Array(d0.B * d0.heads * d0.T * d0.T);
+          for (let i = 0; i < aq.length; i++) aq[i] = (Math.random() * 127) | 0;
+          const as = Float32Array.from({ length: d0.B * d0.heads * d0.T }, () => Math.random() + 0.5);
+          const vs = Float32Array.from({ length: d0.B * d0.heads * d0.hd }, () => Math.random() + 0.5);
+          const dv = { ...d0, acc: true };
+          const [accS, accC, hwS, hwC] = await Promise.all([
+            att.scores(qq, kq, qs, ks, dv), att.ctx(aq, vq, as, vs, dv),
+            att.scores(qq, kq, qs, ks, d0), att.ctx(aq, vq, as, vs, d0)]);
+          const refAccS = root.Verified.attScoresJS(qq, kq, qs, ks, dv, L);
+          const refAccC = root.Verified.attCtxJS(aq, vq, as, vs, dv, L);
+          for (let i = 0; i < refAccS.length; i++) if (accS[i] !== refAccS[i]) throw new Error(`scores accumulator mismatch @${i} shape ${JSON.stringify(d0)}`);
+          for (let i = 0; i < refAccC.length; i++) if (accC[i] !== refAccC[i]) throw new Error(`ctx accumulator mismatch @${i} shape ${JSON.stringify(d0)}`);
+          const refS = root.Verified.attScoresJS(qq, kq, qs, ks, d0, L);
+          const refC = root.Verified.attCtxJS(aq, vq, as, vs, d0, L);
+          for (let i = 0; i < refS.length; i++) if (bitDiff(hwS[i], refS[i])) throw new Error(`scores epilogue mismatch @${i}`);
+          for (let i = 0; i < refC.length; i++) if (bitDiff(hwC[i], refC[i])) throw new Error(`ctx epilogue mismatch @${i}`);
+        }
+      } catch (e) {
+        console.warn("fused attention kernels failed verification — using CPU LUT mirrors:", e.message);
+        att = null;
+      }
+
+      // split-K f32 GEMM for the STE backward (self-tested vs JS float matmul)
+      const fPipes = { gemm: mkPipe(WGSL_FGEMM), reduce: mkPipe(WGSL_FREDUCE) };
+      let fgemm = (A, Bm, d) => gpuFgemm(device, fPipes, A, Bm, d);
+      let fgemm2 = (A, B1, d1, B2, d2) => gpuFgemm2(device, fPipes, A, B1, d1, B2, d2);
+      let fgemmFma = false;                     // set by the gate below
+      try {
+        const m0 = 7, k0 = 4500, n0 = 5;                      // k big enough to exercise split-K
+        const A = Float32Array.from({ length: m0 * k0 }, () => Math.random() - 0.5);
+        const Bm = Float32Array.from({ length: k0 * n0 }, () => Math.random() - 0.5);
+        // EXACT gate, replacing an allclose. The mirror reproduces split-K's
+        // partition and accumulation order, so bit-equality is achievable and
+        // is the honest bar. WGSL may contract `s + a*b` into an FMA, so try
+        // both rounding schedules and record which the device implements —
+        // if NEITHER matches, the f32 backward is not bit-reproducible here
+        // and must not run, because its gradients set the weights the whole
+        // fleet is hashed against.
+        const dG = { m: m0, k: k0, n: n0 };
+        const hw = await fgemm(A, Bm, dG);
+        const mStep = root.Verified.fgemmMirror(A, Bm, dG, false);
+        const mFma = root.Verified.fgemmMirror(A, Bm, dG, true);
+        let okStep = true, okFma = true;
+        for (let i = 0; i < hw.length; i++) {
+          if (bitDiff(hw[i], mStep[i])) okStep = false;
+          if (bitDiff(hw[i], mFma[i])) okFma = false;
+          if (!okStep && !okFma) break;
+        }
+        if (!okStep && !okFma) throw new Error("fgemm matches neither rounding schedule — not bit-reproducible");
+        fgemmFma = !okStep;                     // remember what this device does
+        console.info(`split-K f32 GEMM is bit-exact (${okStep ? "two-rounding" : "fused"} multiply-add schedule)`);
+        // The shared-operand pair must equal the two calls it replaces, EXACTLY:
+        // same buffer, same shader, same arithmetic, so bit-level equality is
+        // the honest bar (not a tolerance). Both index patterns of A are
+        // exercised — transA on one leg, plain on the other, the live shapes.
+        const kT = 300, mT = 9, nT = 6;                       // A is mT x kT, used both ways
+        const A2 = Float32Array.from({ length: mT * kT }, () => Math.random() - 0.5);
+        const Bt = Float32Array.from({ length: mT * nT }, () => Math.random() - 0.5);
+        const Bn = Float32Array.from({ length: kT * nT }, () => Math.random() - 0.5);
+        const dT = { m: kT, k: mT, n: nT, transA: true }, dN = { m: mT, k: kT, n: nT };
+        const [f1, f2] = await fgemm2(A2, Bt, dT, Bn, dN);
+        const [r1, r2] = [await fgemm(A2, Bt, dT), await fgemm(A2, Bn, dN)];
+        for (let i = 0; i < r1.length; i++) if (bitDiff(f1[i], r1[i])) throw new Error("fgemm2 transA leg differs");
+        for (let i = 0; i < r2.length; i++) if (bitDiff(f2[i], r2[i])) throw new Error("fgemm2 plain leg differs");
+      } catch (e) {
+        console.warn("split-K f32 GEMM failed verification — backward stays in JS:", e.message);
+        fgemm = null; fgemm2 = null;
+      }
+
+      // Shared exact gate for a bgemm implementation. Sweeps shapes (including
+      // ragged ones and a k long enough to matter), compares the int32
+      // accumulator from the verify variant with `!==`, then compares the fused
+      // f32 epilogue against the bit-exact JS mirror. Returns null if clean.
+      async function gateBgemm(bgFn) {
+        for (const d0 of [{ m: 5, k: 9, n: 6, batch: 3, relu: true },
+                          { m: 32, k: 64, n: 32, batch: 1, relu: false },
+                          { m: 7, k: 253, n: 5, batch: 2, relu: true },
+                          { m: 1, k: 4, n: 1, batch: 1, relu: false },
+                          { m: 17, k: 33, n: 9, batch: 1, relu: true }]) {
+          const Xq = new Int8Array(d0.batch * d0.m * d0.k), Wq = new Int8Array(d0.batch * d0.k * d0.n);
+          for (let i = 0; i < Xq.length; i++) Xq[i] = (Math.random() * 256 - 128) | 0;
+          for (let i = 0; i < Wq.length; i++) Wq[i] = (Math.random() * 256 - 128) | 0;
+          const rs = Float32Array.from({ length: d0.batch * d0.m }, () => Math.random() + 0.5);
+          const cs = Float32Array.from({ length: d0.batch * d0.n }, () => Math.random() + 0.5);
+          const shape = `${d0.m}x${d0.k}x${d0.n}b${d0.batch}`;
+          const accHw = await bgFn(Xq, Wq, rs, cs, { ...d0, acc: true });
+          const accRef = root.Verified.bgemmJS(Xq, Wq, rs, cs, { ...d0, acc: true }, L);
+          for (let i = 0; i < accRef.length; i++)
+            if (accHw[i] !== accRef[i]) return `accumulator mismatch @${i} (${shape}): ${accHw[i]} vs ${accRef[i]}`;
+          const hw = await bgFn(Xq, Wq, rs, cs, d0);
+          const ref = root.Verified.bgemmJS(Xq, Wq, rs, cs, d0, L);
+          for (let i = 0; i < ref.length; i++)
+            if (bitDiff(hw[i], ref[i])) return `epilogue mismatch @${i} (${shape}): ${hw[i]} vs ${ref[i]}`;
+        }
+        return null;
+      }
+
+      // Poison the pool with large-magnitude residue at the gate's own shapes,
+      // so a re-gate runs on RECYCLED (non-zero) buffers. See the dirty-buffer
+      // gate note below the MLP gate for why this matters.
+      async function poisonBgemm(bgFn) {
+        for (const d0 of [{ m: 5, k: 9, n: 6, batch: 3, relu: true },
+                          { m: 32, k: 64, n: 32, batch: 1, relu: false },
+                          { m: 7, k: 253, n: 5, batch: 2, relu: true },
+                          { m: 1, k: 4, n: 1, batch: 1, relu: false },
+                          { m: 17, k: 33, n: 9, batch: 1, relu: true }]) {
+          const Xq = new Int8Array(d0.batch * d0.m * d0.k).fill(127);
+          const Wq = new Int8Array(d0.batch * d0.k * d0.n).fill(127);
+          const rs = new Float32Array(d0.batch * d0.m).fill(1e4);
+          const cs = new Float32Array(d0.batch * d0.n).fill(1e4);
+          await bgFn(Xq, Wq, rs, cs, d0);
+          await bgFn(Xq, Wq, rs, cs, { ...d0, acc: true });
+        }
+      }
+      const gateBgemmDirty = async (bgFn) => { await poisonBgemm(bgFn); return gateBgemm(bgFn); };
+
+      const bgLut = (Xq, Wq, rs, cs, d) => gpuBgemmLUT(device, d.acc ? bgLutVPipe : bgLutPipe, lutBuf, Xq, Wq, rs, cs, d);
+      // the LUT bgemm is the fallback AND the oracle's shader twin — gate it too
+      const lutBad = (await gateBgemm(bgLut)) || (await gateBgemmDirty(bgLut));
+      if (lutBad) { console.warn("LUT bgemm shader failed verification — CPU mirrors only:", lutBad); return cpu; }
+
+      // B2B MLP chain gate (CUTLASS ex. 13+23): run the WHOLE chain — gemm1 +
+      // ReLU + on-GPU rowmax + on-GPU quantize + gemm2 — against the pure-JS
+      // mirror chain, exact `!==` on both h1 and the final output. Sweeps
+      // ragged shapes; h not a multiple of 4 exercises the pack-tail padding.
+      const MLP_SHAPES = [{ m: 6, k: 8, h: 12, n: 5 }, { m: 5, k: 16, h: 6, n: 3 },
+                          { m: 17, k: 33, h: 10, n: 9 }, { m: 32, k: 64, h: 128, n: 32 }];
+      async function gateMlp(mlpFn, sweepOnly) {
+        for (const d0 of MLP_SHAPES) {
+          const rnd = (len) => Float32Array.from({ length: len }, () => Math.random() * 2 - 1);
+          const Xf = rnd(d0.m * d0.k), W1 = rnd(d0.k * d0.h), W2 = rnd(d0.h * d0.n);
+          const hw = await root.Verified.vmlpBlock(Xf, W1, W2, d0, L, mlpFn, null);
+          const ref = await root.Verified.vmlpBlock(Xf, W1, W2, d0, L, null, null);
+          const shape = `${d0.m}x${d0.k}x${d0.h}x${d0.n}`;
+          for (let i = 0; i < ref.h1.length; i++)
+            if (bitDiff(hw.h1[i], ref.h1[i])) return `h1 mismatch @${i} (${shape}): ${hw.h1[i]} vs ${ref.h1[i]}`;
+          for (let i = 0; i < ref.out.length; i++)
+            if (bitDiff(hw.out[i], ref.out[i])) return `out mismatch @${i} (${shape}): ${hw.out[i]} vs ${ref.out[i]}`;
+        }
+        if (sweepOnly) return null;      // dirty re-gate: sweep is the point, skip the respec hunt
+        // DISCRIMINATING case: the sweep above passes vacuously if no value
+        // lands on a rounding boundary — the old round(x/scale) spec would
+        // pass it too. So hunt (in fast JS) for an input where the two specs
+        // actually disagree, then check the GPU sides with the RESPEC. This
+        // gates the gate: a pass must be something the old spec would fail.
+        const V = root.Verified;
+        const d1 = { m: 16, k: 32, h: 64, n: 16 };
+        const rnd1 = (len) => Float32Array.from({ length: len }, () => Math.random() * 4 - 2);
+        for (let t = 0; t < 800; t++) {
+          const Xf = rnd1(d1.m * d1.k), W1 = rnd1(d1.k * d1.h), W2 = rnd1(d1.h * d1.n);
+          const x = V.quantizeRows(Xf, d1.m, d1.k), w1 = V.quantizeCols(W1, d1.k, d1.h);
+          const h1 = V.bgemmJS(x.q, w1.q, x.s, w1.s, { m: d1.m, k: d1.k, n: d1.h, batch: 1, relu: true }, L);
+          const sc = V.scalesFromAbsMax(V.rowAbsMax(h1, d1.m, d1.h));
+          const qNew = V.quantizeRowsInv(h1, d1.m, d1.h, sc.inv);
+          const qOld = V.quantizeRows(h1, d1.m, d1.h).q;
+          let boundary = false;
+          for (let i = 0; i < qNew.length; i++) if (qNew[i] !== qOld[i]) { boundary = true; break; }
+          if (!boundary) continue;
+          const w2 = V.quantizeCols(W2, d1.h, d1.n);
+          const gpu = await mlpFn(x.q, w1.q, w2.q, x.s, w1.s, w2.s, d1);
+          const refNew = V.bgemmJS(qNew, w2.q, sc.scale, w2.s, { m: d1.m, k: d1.h, n: d1.n, batch: 1 }, L);
+          const refOld = V.bgemmJS(qOld, w2.q, sc.scale, w2.s, { m: d1.m, k: d1.h, n: d1.n, batch: 1 }, L);
+          let eqNew = true, eqOld = true;
+          for (let i = 0; i < refNew.length; i++) { if (bitDiff(gpu.out[i], refNew[i])) eqNew = false; if (bitDiff(gpu.out[i], refOld[i])) eqOld = false; }
+          if (!eqNew) return "discriminating boundary case: GPU chain does not match the respec mirror";
+          if (eqOld) return "discriminating boundary case: GPU chain matches the OLD quantize spec";
+          return null;                                    // proven: respec, not merely gate-compatible
+        }
+        console.warn("B2B gate: no rounding-boundary input found in 800 trials — respec discrimination unproven this boot (sweep still exact)");
+        return null;
+      }
+      // FMA-contraction note for the quantize kernel: WGSL permits a compiler
+      // to contract `H*inv + 0.5` into a hardware FMA (e.g. RDNA2 V_FMA_F32 —
+      // ONE rounding instead of two). This CANNOT change the quantized int8:
+      // adding 0.5 is exact except at binade crossings, and there the
+      // double-rounding anomaly only moves the value within the same integer
+      // cell (the RNE tie parity resolves both schedules to the same side of
+      // the integer), so floor() sees no difference. Verified empirically in
+      // test_b2b.js: 48M draws targeted at binade edges, 1.9M last-ulp
+      // fused-vs-stepped differences, ZERO floor-visible. The `+0.5` respec is
+      // contraction-immune by construction — `round(x/scale)` was not.
+      // ---- DIRTY-BUFFER GATE ----------------------------------------------
+      // A pooled buffer is NOT zero-initialized, so any kernel that assumes
+      // zeros (the rowmax atomicMax accumulator does) is right on step one and
+      // wrong on step two. That is a STATE bug: no single call is wrong, the
+      // sequence is — the family an oracle cannot reach.
+      //
+      // MEASURED, and it corrected the assumption that motivated this code:
+      // the existing sweep ALREADY catches it. Deleting the clearBuffer and
+      // re-running showed the plain gate failing at the SECOND shape, because
+      // the sweep's own shapes recycle each other's buffers (same power-of-2
+      // bucket) and an uncleared max only grows. So the suite was never
+      // blind — it had incidental dirty coverage nobody designed.
+      //
+      // Incidental is the problem. It relies on the sweep having >= 2 shapes,
+      // on them colliding in one bucket, and on the residue exceeding the real
+      // value. Change the shape list and the coverage silently evaporates.
+      // The poison below makes it deliberate: run first at 1e4 magnitude so
+      // the residue dominates ANY value the gate can produce, release it, then
+      // sweep again. Detection stops depending on ordering luck and covers the
+      // first shape too. Cheap by design — the re-gate skips the 800-trial
+      // respec hunt, which has nothing to do with buffer state.
+      async function poisonPool(mlpFn) {
+        // same shapes as the gate => same pool buckets => the gate's next
+        // acquisition is exactly one of these poisoned buffers (free list is LIFO)
+        const big = (len) => Float32Array.from({ length: len }, () => (Math.random() * 2 - 1) * 1e4);
+        for (const d0 of MLP_SHAPES)
+          await root.Verified.vmlpBlock(big(d0.m * d0.k), big(d0.k * d0.h), big(d0.h * d0.n), d0, L, mlpFn, null);
+      }
+      async function gateMlpDirty(mlpFn) {
+        await poisonPool(mlpFn);
+        return gateMlp(mlpFn, true);    // sweep only, on recycled non-zero buffers
+      }
+
+      const lutMlpEnv = { dp4: false, gemm: bgLutPipe, rowmax: rowmaxPipe, quant: quantI32Pipe, lutBuf };
+      let mlpLut = (xq, w1q, w2q, xs, w1s, w2s, d) => gpuMlpChain(device, lutMlpEnv, xq, w1q, w2q, xs, w1s, w2s, d);
+      const mlpLutBad = (await gateMlp(mlpLut)) || (await gateMlpDirty(mlpLut));
+      if (mlpLutBad) { console.warn("B2B MLP chain (LUT) failed verification — MLP stays on the CPU mirror chain:", mlpLutBad); mlpLut = null; }
+
+      const viaLUT = { backend: "webgpu", label: `${gpuName} (LUT shader · exact-gated)`,
+                       matmulInt8: (Xq, Wq, m, k, n) => gpuMatmulLUT(device, lutPipe, lutBuf, Xq, Wq, m, k, n),
+                       bgemm: bgLut, att, fgemm, fgemm2, mlp: mlpLut };
+
+      // DP4A pipeline — only if the WGSL feature exists AND its batched kernel
+      // reproduces the verified units exactly across the shape sweep
+      if (!(navigator.gpu.wgslLanguageFeatures && navigator.gpu.wgslLanguageFeatures.has("packed_4x8_integer_dot_product")))
+        return viaLUT;
+      const bgDp4Pipe = mkPipeL(WGSL_BG_DP4(false), bgDp4Layout), bgDp4VPipe = mkPipeL(WGSL_BG_DP4(true), bgDp4Layout);
+      const bg = (Xq, Wq, rs, cs, d) => gpuBgemmDP4(device, d.acc ? bgDp4VPipe : bgDp4Pipe, Xq, Wq, rs, cs, d);
+      const dp4Bad = (await gateBgemm(bg)) || (await gateBgemmDirty(bg));
+      if (dp4Bad) {
+        console.warn("batched DP4A disagreed with the verified units — using LUT bgemm:", dp4Bad);
+        return viaLUT;
+      }
+      const dp4MlpEnv = { dp4: true, gemm: bgDp4Pipe, rowmax: rowmaxPipe, quant: quantPackPipe };
+      let mlpDp4 = (xq, w1q, w2q, xs, w1s, w2s, d) => gpuMlpChain(device, dp4MlpEnv, xq, w1q, w2q, xs, w1s, w2s, d);
+      const mlpDp4Bad = (await gateMlp(mlpDp4)) || (await gateMlpDirty(mlpDp4));
+      if (mlpDp4Bad) { console.warn("B2B MLP chain (DP4A) failed verification — using the LUT chain:", mlpDp4Bad); mlpDp4 = mlpLut; }
+
+      // Both backends are exact-gated bit-identical, so which one runs is a
+      // free choice — and an init race that timed them was tried and REMOVED.
+      // Measured on this NVIDIA part they tie on the shipped float path (DP4A's
+      // JS packing cancels its dot-throughput win at these sizes), so the race
+      // bought nothing, cost ~40 ms of init, and made the backend vary between
+      // page loads — which silently invalidated three separate A/B benchmarks
+      // before it was noticed. A knob that changes what you are measuring is
+      // worse than a fixed choice. DP4A ships: it wins the int8-backward mode
+      // by ~12% and ties elsewhere.
+      return { backend: "webgpu", label: `${gpuName} (DP4A int8 dot · exact-gated vs units)`,
+               bgemm: bg, att, fgemm, fgemm2, mlp: mlpDp4 };
+    } catch (e) { console.warn("WebGPU init failed, CPU fallback:", e); return cpu; }
+  }
+
+  // shared dispatch/readback plumbing
+  async function runPass(device, pipeline, entries, m, n) {
+    const bytesC = m * n * 4;
+    const bufC = mk(device, bytesC, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    const bind = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0),
+      entries: entries(bufC) });
+    const enc = device.createCommandEncoder();
+    const pass = enc.beginComputePass();
+    pass.setPipeline(pipeline); pass.setBindGroup(0, bind);
+    pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(n / 8)); pass.end();
+    const read = mk(device, bytesC, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+    enc.copyBufferToBuffer(bufC, 0, read, 0, bytesC);
+    device.queue.submit([enc.finish()]);
+    await read.mapAsync(GPUMapMode.READ);
+    const out = new Int32Array(read.getMappedRange(0, bytesC).slice(0));   // pooled: map only the logical range
+    read.unmap();
+    return { out, bufC, read };
+  }
+
+  async function gpuMatmulLUT(device, pipeline, lutBuf, Xq, Wq, m, k, n) {
+    const X32 = Int32Array.from(Xq), W32 = Int32Array.from(Wq);   // byte -> i32
+    const bufX = up(device, X32, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufW = up(device, W32, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufD = up(device, new Uint32Array([m, k, n, 0]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const r = await runPass(device, pipeline, (bufC) => [
+      { binding: 0, resource: { buffer: bufX } }, { binding: 1, resource: { buffer: bufW } },
+      { binding: 2, resource: { buffer: lutBuf } }, { binding: 3, resource: { buffer: bufC } },
+      { binding: 4, resource: { buffer: bufD } } ], m, n);
+    release(device, [bufX, bufW, bufD, r.bufC, r.read]);
+    return r.out;
+  }
+
+  // attention kernels: int8 (widened i32) in, f32 out, strided head indexing
+  async function gpuAttScores(device, pipeline, qq, kq, qs, ks, d) {
+    const { B, T, heads } = d;
+    const bufQ = up(device, Int32Array.from(qq), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufK = up(device, Int32Array.from(kq), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufQs = up(device, qs, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufKs = up(device, ks, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufD = up(device, new Uint32Array([d.T, d.heads, d.hd, 0]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const r = await runBgPass(device, pipeline, (bufO) => [
+      { binding: 0, resource: { buffer: bufQ } }, { binding: 1, resource: { buffer: bufK } },
+      { binding: 2, resource: { buffer: bufQs } }, { binding: 3, resource: { buffer: bufKs } },
+      { binding: 4, resource: { buffer: bufO } }, { binding: 5, resource: { buffer: bufD } } ], T, T, B * heads, d.acc);
+    release(device, [bufQ, bufK, bufQs, bufKs, bufD, r.bufO, r.read]);
+    return r.out;
+  }
+  async function gpuAttCtx(device, pipeline, aq, vq, as, vs, d) {
+    const { B, T, heads, hd } = d;
+    const bufA = up(device, Int32Array.from(aq), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufV = up(device, Int32Array.from(vq), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufAs = up(device, as, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufVs = up(device, vs, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufD = up(device, new Uint32Array([T, heads, hd, 0]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const r = await runBgPass(device, pipeline, (bufO) => [
+      { binding: 0, resource: { buffer: bufA } }, { binding: 1, resource: { buffer: bufV } },
+      { binding: 2, resource: { buffer: bufAs } }, { binding: 3, resource: { buffer: bufVs } },
+      { binding: 4, resource: { buffer: bufO } }, { binding: 5, resource: { buffer: bufD } } ], T, hd, B * heads, d.acc);
+    release(device, [bufA, bufV, bufAs, bufVs, bufD, r.bufO, r.read]);
+    return r.out;
+  }
+
+  // split-K f32 GEMM (backward): partial pass + reduce pass
+  async function gpuFgemm(device, pipes, A, Bm, d) {
+    const { m, k, n } = d, transA = d.transA ? 1 : 0;
+    const S = k > 4096 ? Math.min(16, Math.ceil(k / 2048)) : 1;
+    const bufA = up(device, A, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufB = up(device, Bm, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufP = mk(device, S * m * n * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    const bufD1 = up(device, new Uint32Array([m, k, n, transA | (S << 1)]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const bufO = mk(device, m * n * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    const bufD2 = up(device, new Uint32Array([m * n, S, 0, 0]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const enc = device.createCommandEncoder();
+    let pass = enc.beginComputePass();
+    pass.setPipeline(pipes.gemm);
+    pass.setBindGroup(0, device.createBindGroup({ layout: pipes.gemm.getBindGroupLayout(0), entries: [
+      { binding: 0, resource: { buffer: bufA } }, { binding: 1, resource: { buffer: bufB } },
+      { binding: 2, resource: { buffer: bufP } }, { binding: 3, resource: { buffer: bufD1 } } ] }));
+    pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(n / 8), S); pass.end();
+    pass = enc.beginComputePass();
+    pass.setPipeline(pipes.reduce);
+    pass.setBindGroup(0, device.createBindGroup({ layout: pipes.reduce.getBindGroupLayout(0), entries: [
+      { binding: 0, resource: { buffer: bufP } }, { binding: 1, resource: { buffer: bufO } },
+      { binding: 2, resource: { buffer: bufD2 } } ] }));
+    pass.dispatchWorkgroups(Math.ceil(m * n / 64)); pass.end();
+    const read = mk(device, m * n * 4, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+    enc.copyBufferToBuffer(bufO, 0, read, 0, m * n * 4);
+    device.queue.submit([enc.finish()]);
+    await read.mapAsync(GPUMapMode.READ);
+    const out = new Float32Array(read.getMappedRange(0, m * n * 4).slice(0));   // pooled: logical range only
+    read.unmap();
+    release(device, [bufA, bufB, bufP, bufD1, bufO, bufD2, read]);
+    return out;
+  }
+
+  // SHARED-OPERAND fused f32 GEMM pair. The two embedding-gradient GEMMs both
+  // consume dlogits (BT x vocab). With the 16512-token vocab that operand is
+  // ~17 MB, and running them as two independent calls uploaded it TWICE and
+  // paid two submits and two map round trips — profiling put the pair at 55%
+  // of the whole step. Here A goes up ONCE, both GEMM+reduce chains ride one
+  // command encoder, one submit covers both, and the two readbacks are mapped
+  // concurrently. The shader reads A as either A[row*k+p] or A[p*m+row]
+  // (transA), so ONE flat buffer serves both index patterns — nothing about
+  // the arithmetic changes, which is why the gradients stay bit-identical.
+  async function gpuFgemm2(device, pipes, A, B1, d1, B2, d2) {
+    const SU = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+    const UU = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST;
+    const bufA = up(device, A, SU);                       // the shared 17 MB operand: ONE upload
+    const enc = device.createCommandEncoder();
+    const legs = [];
+    for (const [Bm, d] of [[B1, d1], [B2, d2]]) {
+      const { m, k, n } = d, transA = d.transA ? 1 : 0;
+      const S = k > 4096 ? Math.min(16, Math.ceil(k / 2048)) : 1;
+      const bufB = up(device, Bm, SU);
+      const bufP = mk(device, S * m * n * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+      const bufD1 = up(device, new Uint32Array([m, k, n, transA | (S << 1)]), UU);
+      const bufO = mk(device, m * n * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+      const bufD2 = up(device, new Uint32Array([m * n, S, 0, 0]), UU);
+      let pass = enc.beginComputePass();
+      pass.setPipeline(pipes.gemm);
+      pass.setBindGroup(0, device.createBindGroup({ layout: pipes.gemm.getBindGroupLayout(0), entries: [
+        { binding: 0, resource: { buffer: bufA } }, { binding: 1, resource: { buffer: bufB } },
+        { binding: 2, resource: { buffer: bufP } }, { binding: 3, resource: { buffer: bufD1 } } ] }));
+      pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(n / 8), S); pass.end();
+      pass = enc.beginComputePass();
+      pass.setPipeline(pipes.reduce);
+      pass.setBindGroup(0, device.createBindGroup({ layout: pipes.reduce.getBindGroupLayout(0), entries: [
+        { binding: 0, resource: { buffer: bufP } }, { binding: 1, resource: { buffer: bufO } },
+        { binding: 2, resource: { buffer: bufD2 } } ] }));
+      pass.dispatchWorkgroups(Math.ceil(m * n / 64)); pass.end();
+      const bytes = m * n * 4;
+      const read = mk(device, bytes, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+      enc.copyBufferToBuffer(bufO, 0, read, 0, bytes);
+      legs.push({ read, bytes, bufs: [bufB, bufP, bufD1, bufO, bufD2] });
+    }
+    device.queue.submit([enc.finish()]);                  // ONE submit for both GEMMs
+    await Promise.all(legs.map((l) => l.read.mapAsync(GPUMapMode.READ)));
+    const outs = legs.map((l) => {
+      const o = new Float32Array(l.read.getMappedRange(0, l.bytes).slice(0));
+      l.read.unmap();
+      return o;
+    });
+    release(device, [bufA, ...legs.flatMap((l) => [...l.bufs, l.read])]);
+    return outs;
+  }
+
+  // fused batched dispatch: f32 out, epilogue done on-device (raw=true reads the
+  // verify variant's int32 accumulator instead)
+  async function runBgPass(device, pipeline, entries, m, n, batch, raw) {
+    const bytesO = batch * m * n * 4;
+    const bufO = mk(device, bytesO, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    const bind = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: entries(bufO) });
+    const enc = device.createCommandEncoder();
+    const pass = enc.beginComputePass();
+    pass.setPipeline(pipeline); pass.setBindGroup(0, bind);
+    pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(n / 8), batch); pass.end();
+    const read = mk(device, bytesO, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+    enc.copyBufferToBuffer(bufO, 0, read, 0, bytesO);
+    device.queue.submit([enc.finish()]);
+    await read.mapAsync(GPUMapMode.READ);
+    const buf = read.getMappedRange(0, bytesO).slice(0);   // pooled: logical range only
+    const out = raw ? new Int32Array(buf) : new Float32Array(buf);
+    read.unmap();
+    return { out, bufO, read };
+  }
+
+  async function gpuBgemmLUT(device, pipeline, lutBuf, Xq, Wq, rs, cs, d) {
+    const { m, k, n } = d, batch = d.batch || 1, flags = d.relu ? 1 : 0;
+    const bufX = up(device, Int32Array.from(Xq), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufW = up(device, Int32Array.from(Wq), GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufR = up(device, rs, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufS = up(device, cs, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufD = up(device, new Uint32Array([m, k, n, flags]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const r = await runBgPass(device, pipeline, (bufO) => [
+      { binding: 0, resource: { buffer: bufX } }, { binding: 1, resource: { buffer: bufW } },
+      { binding: 2, resource: { buffer: lutBuf } }, { binding: 3, resource: { buffer: bufR } },
+      { binding: 4, resource: { buffer: bufS } }, { binding: 5, resource: { buffer: bufO } },
+      { binding: 6, resource: { buffer: bufD } } ], m, n, batch, d.acc);
+    release(device, [bufX, bufW, bufR, bufS, bufD, r.bufO, r.read]);
+    return r.out;
+  }
+
+  async function gpuBgemmDP4(device, pipeline, Xq, Wq, rs, cs, d) {
+    const { m, k, n } = d, batch = d.batch || 1, flags = d.relu ? 1 : 0;
+    const kw = Math.ceil(k / 4);
+    const Xp = packRows(Xq, batch * m, k, kw);            // rows are (batch·m)
+    const Wp = new Uint32Array(batch * n * kw);           // per-batch Wᵀ, packed
+    for (let bz = 0; bz < batch; bz++) {
+      const wt = transposeI8(Wq.subarray(bz * k * n, (bz + 1) * k * n), k, n);
+      Wp.set(packRows(wt, n, k, kw), bz * n * kw);
+    }
+    const bufX = up(device, Xp, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufW = up(device, Wp, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufR = up(device, rs, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufS = up(device, cs, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST);
+    const bufD = up(device, new Uint32Array([m, kw, n, flags]), GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST);
+    const r = await runBgPass(device, pipeline, (bufO) => [
+      { binding: 0, resource: { buffer: bufX } }, { binding: 1, resource: { buffer: bufW } },
+      { binding: 2, resource: { buffer: bufR } }, { binding: 3, resource: { buffer: bufS } },
+      { binding: 4, resource: { buffer: bufO } }, { binding: 5, resource: { buffer: bufD } } ], m, n, batch, d.acc);
+    release(device, [bufX, bufW, bufR, bufS, bufD, r.bufO, r.read]);
+    return r.out;
+  }
+
+  // B2B MLP chain: gemm1 (ReLU fused) + rowmax in one encoder, a 4·m-byte
+  // absmax readback, then quantize + gemm2 in a second encoder. h1 comes back
+  // because the STE backward needs it, but it never goes UP again — gemm2's
+  // left operand is produced and consumed entirely on the GPU.
+  async function gpuMlpChain(device, env, xq, w1q, w2q, xs, w1s, w2s, d) {
+    const { m, k, h, n } = d, dp4 = !!env.dp4;
+    const SU = GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST;
+    let bufX, bufW1, bufW2, kw1, hw;
+    if (dp4) {
+      kw1 = Math.ceil(k / 4); hw = Math.ceil(h / 4);
+      bufX = up(device, packRows(xq, m, k, kw1), SU);
+      bufW1 = up(device, packRows(transposeI8(w1q, k, h), h, k, kw1), SU);
+      bufW2 = up(device, packRows(transposeI8(w2q, h, n), n, h, hw), SU);
+    } else {
+      kw1 = k; hw = h;
+      bufX = up(device, Int32Array.from(xq), SU);
+      bufW1 = up(device, Int32Array.from(w1q), SU);
+      bufW2 = up(device, Int32Array.from(w2q), SU);
+    }
+    const bufRs = up(device, xs, SU), bufCs1 = up(device, w1s, SU), bufCs2 = up(device, w2s, SU);
+    const bufH = mk(device, m * h * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    // rowmax accumulates with atomicMax and NEEDS zeros. A fresh buffer was
+    // zero-initialized; a POOLED buffer is not — cleared in the encoder below.
+    const bufMX = mk(device, m * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST);
+    const UU = GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST;
+    const bufD1 = up(device, new Uint32Array([m, kw1, h, 1]), UU);       // flags=1: fused ReLU
+    const bufDM = up(device, new Uint32Array([m, h, 0, 0]), UU);
+    const gemmBind = (bufA, bufB, bufR, bufC, bufO, bufD) => device.createBindGroup({
+      layout: env.gemm.getBindGroupLayout(0),
+      entries: (dp4 ? [bufA, bufB, bufR, bufC, bufO, bufD]
+                    : [bufA, bufB, env.lutBuf, bufR, bufC, bufO, bufD])
+        .map((b, i) => ({ binding: i, resource: { buffer: b } })) });
+    const enc1 = device.createCommandEncoder();
+    enc1.clearBuffer(bufMX, 0, m * 4);            // pooled buffer: zero the atomicMax accumulator
+    let pass = enc1.beginComputePass();
+    pass.setPipeline(env.gemm);
+    pass.setBindGroup(0, gemmBind(bufX, bufW1, bufRs, bufCs1, bufH, bufD1));
+    pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(h / 8), 1); pass.end();
+    pass = enc1.beginComputePass();
+    pass.setPipeline(env.rowmax);
+    pass.setBindGroup(0, device.createBindGroup({ layout: env.rowmax.getBindGroupLayout(0), entries: [
+      { binding: 0, resource: { buffer: bufH } }, { binding: 1, resource: { buffer: bufMX } },
+      { binding: 2, resource: { buffer: bufDM } } ] }));
+    pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(h / 8), 1); pass.end();
+    const readH = mk(device, m * h * 4, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+    const readM = mk(device, m * 4, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+    enc1.copyBufferToBuffer(bufH, 0, readH, 0, m * h * 4);
+    enc1.copyBufferToBuffer(bufMX, 0, readM, 0, m * 4);
+    device.queue.submit([enc1.finish()]);
+    await Promise.all([readH.mapAsync(GPUMapMode.READ), readM.mapAsync(GPUMapMode.READ)]);
+    const h1 = new Float32Array(readH.getMappedRange(0, m * h * 4).slice(0)); readH.unmap();
+    // the atomicMax'ed u32 bit patterns ARE the f32 |max| values
+    const mx = new Float32Array(readM.getMappedRange(0, m * 4).slice(0)); readM.unmap();
+    // scale derivation in JS f64 — exactly rounded, identical on every device
+    // (WGSL division is 2.5 ULP, which is why it never runs on the GPU)
+    const sc = root.Verified.scalesFromAbsMax(mx);
+    const bufInv = up(device, sc.inv, SU), bufHs = up(device, sc.scale, SU);
+    const bufQ = mk(device, m * hw * 4, GPUBufferUsage.STORAGE);
+    const bufDQ = up(device, new Uint32Array([m, h, hw, 0]), UU);
+    const bufD2 = up(device, new Uint32Array([m, hw, n, 0]), UU);
+    const bufO = mk(device, m * n * 4, GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC);
+    const enc2 = device.createCommandEncoder();
+    pass = enc2.beginComputePass();
+    pass.setPipeline(env.quant);
+    pass.setBindGroup(0, device.createBindGroup({ layout: env.quant.getBindGroupLayout(0), entries: [
+      { binding: 0, resource: { buffer: bufH } }, { binding: 1, resource: { buffer: bufInv } },
+      { binding: 2, resource: { buffer: bufQ } }, { binding: 3, resource: { buffer: bufDQ } } ] }));
+    pass.dispatchWorkgroups(Math.ceil((m * (dp4 ? hw : h)) / 64)); pass.end();
+    pass = enc2.beginComputePass();
+    pass.setPipeline(env.gemm);
+    pass.setBindGroup(0, gemmBind(bufQ, bufW2, bufHs, bufCs2, bufO, bufD2));
+    pass.dispatchWorkgroups(Math.ceil(m / 8), Math.ceil(n / 8), 1); pass.end();
+    const readO = mk(device, m * n * 4, GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ);
+    enc2.copyBufferToBuffer(bufO, 0, readO, 0, m * n * 4);
+    device.queue.submit([enc2.finish()]);
+    await readO.mapAsync(GPUMapMode.READ);
+    const out = new Float32Array(readO.getMappedRange(0, m * n * 4).slice(0)); readO.unmap();
+    release(device, [bufX, bufW1, bufW2, bufRs, bufCs1, bufCs2, bufH, bufMX, bufD1, bufDM,
+     bufInv, bufHs, bufQ, bufDQ, bufD2, bufO, readH, readM, readO]);
+    return { h1, out };
+  }
+
+  // ---- buffer pool ------------------------------------------------------------
+  // Every dispatch used to create and destroy its buffers — ~19 create/destroy
+  // pairs per MLP chain call, per layer, per step. Creation cost is pure driver
+  // overhead, and at these GEMM sizes it is a large share of the step. The pool
+  // recycles buffers by (usage, size-bucket): same bytes uploaded, same regions
+  // read, ZERO math change — the kernels only ever index inside the logical
+  // dims, so the stale tail of a bucketed buffer is never read. The one
+  // exception is a buffer a kernel expects ZEROED (the rowmax accumulator):
+  // pooled buffers are NOT fresh, so that one is cleared explicitly in the
+  // encoder (see gpuMlpChain). Correctness is enforced where it always was:
+  // the exact init gates, the live audit, and the per-step probe hash all run
+  // through these pooled paths.
+  const _pools = new WeakMap();                     // device -> Map(key -> free list)
+  function _poolOf(device) {
+    let p = _pools.get(device);
+    if (!p) { p = new Map(); _pools.set(device, p); }
+    return p;
+  }
+  function mk(device, size, usage) {
+    let cap = 256; while (cap < size) cap *= 2;
+    const key = usage + ":" + cap;
+    const list = _poolOf(device).get(key);
+    if (list && list.length) return list.pop();
+    const b = device.createBuffer({ size: cap, usage });
+    b._poolKey = key;
+    return b;
+  }
+  function up(device, arr, usage) {
+    const b = mk(device, Math.max(16, arr.byteLength), usage);
+    device.queue.writeBuffer(b, 0, arr);
+    return b;
+  }
+  function release(device, bufs) {
+    const p = _poolOf(device);
+    for (const b of bufs) {
+      if (!b || !b._poolKey) { if (b) b.destroy(); continue; }
+      let list = p.get(b._poolKey);
+      if (!list) { list = []; p.set(b._poolKey, list); }
+      if (list.length < 64) list.push(b); else b.destroy();
+    }
+  }
+
+  // ---- canonical kernel probe -------------------------------------------------
+  // The weight hash CANNOT catch a device whose kernel is wrong: weights only
+  // depend on the gradient bytes everyone receives, so a fleet averaging one
+  // device's bad gradient stays bit-identical and perfectly happy. This is the
+  // check that can. Every device runs the SAME seeded int8 GEMM through its own
+  // live kernel (verify variant -> raw int32 accumulator, exact on every
+  // backend — GPU DP4A, GPU LUT, CPU mirror alike) and hashes the result. Same
+  // input + correct kernels => same hash, regardless of hardware. A device that
+  // disagrees is computing different arithmetic than the rest of the fleet.
+  const PROBE = { m: 24, k: 96, n: 24, batch: 2 };
+  function probeInputs() {
+    let seed = 0x5EED;                       // fixed: identical on every device
+    const rnd = () => { seed = (Math.imul(seed, 1103515245) + 12345) & 0x7fffffff; return seed / 0x7fffffff; };
+    const { m, k, n, batch } = PROBE;
+    const Xq = new Int8Array(batch * m * k), Wq = new Int8Array(batch * k * n);
+    for (let i = 0; i < Xq.length; i++) Xq[i] = Math.round(rnd() * 254 - 127);
+    for (let i = 0; i < Wq.length; i++) Wq[i] = Math.round(rnd() * 254 - 127);
+    const rs = Float32Array.from({ length: batch * m }, () => 1);
+    const cs = Float32Array.from({ length: batch * n }, () => 1);
+    return { Xq, Wq, rs, cs, d: { ...PROBE, acc: true } };
+  }
+  // ---- transcendental probe ---------------------------------------------------
+  // The kernel probe covers int8 GEMM arithmetic. It does NOT cover the JS
+  // transcendentals, and ECMA-262 does not require Math.exp/log/cos/sin to be
+  // correctly rounded — it calls them "implementation-approximated", so V8,
+  // SpiderMonkey and JSC are all permitted to return different bits.
+  //
+  // One use of them can fork a fleet: weight INIT. Peers build their own
+  // starting weights from a shared seed rather than broadcasting them
+  // (Box-Muller, so Math.log/cos/sin), and one ulp of engine disagreement
+  // means peers begin from different models. The per-step uses (softmax, loss)
+  // cannot fork anything — every peer averages the same received gradient
+  // BYTES, so a differently-rounded local gradient is still a gradient the
+  // whole group then agrees on.
+  //
+  // This hashes the exact f64 bits of those four functions over a fixed grid,
+  // so a browser whose math library differs is IDENTIFIED instead of showing
+  // up later as an unexplained weight-hash mismatch. Cost: microseconds, once.
+  // Detection, not correction — pinning the algorithms would be a fleet-wide
+  // numerics change, and is only worth doing if this ever reports a mismatch.
+  function mathProbe() {
+    const buf = new ArrayBuffer(8), dv = new DataView(buf);
+    let h = 0x811c9dc5;
+    const eat = (x) => {
+      dv.setFloat64(0, x);
+      for (let i = 0; i < 8; i++) { h ^= dv.getUint8(i); h = Math.imul(h, 0x01000193); }
+    };
+    for (let i = 1; i <= 400; i++) {
+      const u = i / 401;                     // (0,1): the Box-Muller domain
+      eat(Math.log(u));
+      eat(Math.cos(2 * Math.PI * u));
+      eat(Math.sin(2 * Math.PI * u));
+      eat(Math.sqrt(-2 * Math.log(u)));      // the exact composite randn uses
+      eat(Math.exp(-u * 12));                // the softmax domain
+    }
+    return h >>> 0;
+  }
+
+  async function kernelProbe(compute, L) {
+    const { Xq, Wq, rs, cs, d } = probeInputs();
+    const out = compute && compute.bgemm
+      ? await compute.bgemm(Xq, Wq, rs, cs, d)
+      : root.Verified.bgemmJS(Xq, Wq, rs, cs, d, L);
+    let h = 0x811c9dc5;                      // FNV-1a over the exact int32 results
+    const b = new Uint8Array(out.buffer, out.byteOffset, out.byteLength);
+    for (let i = 0; i < b.length; i++) { h ^= b[i]; h = Math.imul(h, 0x01000193); }
+    // fold in the transcendental hash: same question ("is your arithmetic the
+    // same as mine?"), same broadcast slot, no wire-format change
+    const mh = mathProbe();
+    for (let i = 0; i < 4; i++) { h ^= (mh >>> (i * 8)) & 0xFF; h = Math.imul(h, 0x01000193); }
+    return h >>> 0;
+  }
+
+  root.Compute = { initCompute, loadLUTs, kernelProbe, mathProbe };
+})(self);

public/wire.js

@@ -0,0 +1,171 @@
+// The wire protocol, as pure functions.
+//
+// Kept out of app.js on purpose: a codec that only exists inside a browser
+// event handler cannot be tested, and the failures this protocol can have are
+// precisely the ones that are invisible at runtime. A misread offset does not
+// throw — it yields a plausible number, and a plausible number in an
+// activation is a slightly wrong sentence nobody can attribute to anything.
+// So the codec lives here and test_wire.js round-trips it.
+//
+// Sentinels continue DaisyChain-Web's numbering (it uses -2..-8), so a client
+// pointed at the wrong server sees an unknown tag rather than a valid-looking
+// message of the wrong kind.
+(function (root) {
+  "use strict";
+
+  const FRAG = -5,      // fragment of a large message (shared with DaisyChain-Web)
+        HELLO = -20,    // capability report
+        ASSIGN = -21,   // model identity + which layers you own (no weights)
+        READY = -22,    // a stage has fetched its layers and is in the ring
+        ACT = -23,      // hidden state moving to the next stage
+        TOKEN = -24,    // a token was emitted
+        DONE = -25;     // run finished
+
+  // The address of the head's return leg. Not a stage index: the head is both
+  // stage 0 and the terminus, so "next = 0" is ambiguous — outbound it means
+  // "stage 0, run your blocks", inbound it means "the lap is done". They need
+  // distinct addresses or the head re-runs its own blocks and the lap never
+  // closes. Negative, so it can never collide with a real stage index.
+  const RETURN = -1;
+
+  const enc = new TextEncoder(), dec = new TextDecoder();
+
+  function tagOf(buf) { return new Int32Array(buf, 0, 1)[0]; }
+
+  // ---- hello -----------------------------------------------------------------
+  function packHello(capacity, probeHash, backend) {
+    const nb = enc.encode(String(backend || "?").slice(0, 32));
+    const buf = new ArrayBuffer(16 + nb.length);
+    new Int32Array(buf, 0, 1)[0] = HELLO;
+    new Float32Array(buf, 4, 1)[0] = capacity;
+    new Uint32Array(buf, 8, 1)[0] = probeHash >>> 0;
+    new Int32Array(buf, 12, 1)[0] = nb.length;
+    new Uint8Array(buf, 16).set(nb);
+    return buf;
+  }
+  function unpackHello(buf) {
+    const n = new Int32Array(buf, 12, 1)[0];
+    if (n < 0 || 16 + n > buf.byteLength) throw new Error("hello: bad backend length");
+    return { capacity: new Float32Array(buf, 4, 1)[0],
+             probeHash: new Uint32Array(buf, 8, 1)[0],
+             backend: dec.decode(new Uint8Array(buf, 16, n)) };
+  }
+
+  // ---- assignment -------------------------------------------------------------
+  // Weights do NOT travel between peers. The head sends each device the model's
+  // identity and which layers it owns; the device then fetches exactly those
+  // tensors from the Hub itself, with its own credentials. So this message is
+  // small, and a token never crosses the wire.
+  //
+  //   [i32 ASSIGN][utf8 JSON]
+  //
+  // JSON rather than packed ints because the payload is a model spec whose
+  // fields differ by architecture. It is validated on arrival — a malformed
+  // assignment must fail here, not three layers deep in a GEMM.
+  function packAssign(a) {
+    const bytes = enc.encode(JSON.stringify(a));
+    const buf = new ArrayBuffer(4 + bytes.length);
+    new Int32Array(buf, 0, 1)[0] = ASSIGN;
+    new Uint8Array(buf, 4).set(bytes);
+    return buf;
+  }
+  function unpackAssign(buf) {
+    let a;
+    try { a = JSON.parse(dec.decode(new Uint8Array(buf, 4))); }
+    catch (e) { throw new Error("assignment: payload is not valid JSON"); }
+    if (!a || typeof a.repo !== "string" || !a.repo)
+      throw new Error("assignment: no repo id");
+    if (!/^[\w.-]+\/[\w.-]+$/.test(a.repo))
+      throw new Error(`assignment: "${a.repo}" is not a valid repo id`);
+    if (!a.spec || !a.spec.layers || !a.spec.hidden)
+      throw new Error("assignment: incomplete model spec");
+    if (!Array.isArray(a.plan) || !a.plan.length)
+      throw new Error("assignment: no plan");
+    // A plan that does not cover every layer exactly once still generates
+    // fluent text — with a layer missing. It has to be refused at the door.
+    let cover = 0;
+    for (const s of a.plan) {
+      if (typeof s.lo !== "number" || typeof s.hi !== "number" || s.hi < s.lo || s.lo < 0 || s.hi > a.spec.layers)
+        throw new Error("assignment: stage range out of bounds");
+      cover += s.hi - s.lo;
+    }
+    if (cover !== a.spec.layers)
+      throw new Error(`assignment: stages cover ${cover} of ${a.spec.layers} layers`);
+    if (!a.plan[0].head) throw new Error("assignment: stage 0 must be the head");
+    if (typeof a.mine !== "number" || a.mine < 0 || a.mine >= a.plan.length)
+      throw new Error("assignment: no valid stage index for this device");
+    return a;
+  }
+
+  // ---- activation ------------------------------------------------------------
+  // [i32 ACT, seq, tokenIdx, nextIndex][u32 actHash, modelHash][f32 hidden]
+  // actHash is an integrity check on the payload; modelHash answers a different
+  // question — whether this activation belongs to the model I hold a slice of.
+  // Two rings running at once on one device is not hypothetical: reload the
+  // head with a different checkpoint and the old stages are still out there.
+  function packAct(seq, tokenIdx, nextIndex, hidden, hashF32, modelHash) {
+    const buf = new ArrayBuffer(24 + hidden.byteLength);
+    new Int32Array(buf, 0, 4).set([ACT, seq, tokenIdx, nextIndex]);
+    new Uint32Array(buf, 16, 2).set([hashF32(hidden) >>> 0, modelHash >>> 0]);
+    new Float32Array(buf, 24).set(hidden);
+    return buf;
+  }
+  function unpackAct(buf, hashF32) {
+    if (buf.byteLength < 24) throw new Error("act: truncated header");
+    const iv = new Int32Array(buf, 0, 4);
+    const [actHash, modelHash] = new Uint32Array(buf, 16, 2);
+    const hidden = new Float32Array(buf.slice(24));
+    if (hashF32 && (hashF32(hidden) >>> 0) !== actHash) throw new Error("act: payload failed its integrity hash");
+    return { seq: iv[1], tokenIdx: iv[2], nextIndex: iv[3], actHash, modelHash, hidden };
+  }
+
+  // ---- routing ---------------------------------------------------------------
+  // Where an activation goes after this stage, and how to read one that arrives.
+  // These are two lines each and they live here, as pure functions, only
+  // because getting them wrong is invisible everywhere else: the math is
+  // correct, the bytes are correct, and the lap simply never closes. Neither a
+  // numeric oracle nor a codec round-trip can see that — it is a property of
+  // the ROUTE, so it needs something that can walk one.
+  function routeAfter(plan, myIndex) {
+    const isLast = myIndex === plan.length - 1;
+    const next = isLast ? plan[0] : plan[myIndex + 1];
+    return { to: next.id, address: isLast ? RETURN : next.index, isReturn: isLast };
+  }
+  function classifyAct(nextIndex, myIndex) {
+    if (nextIndex === RETURN) return "return";     // the lap is finished
+    if (nextIndex === myIndex) return "mine";      // run my blocks, pass it on
+    return "other";                                // not addressed to me
+  }
+
+  // ---- token / done ----------------------------------------------------------
+  function packToken(seq, id, total) {
+    const buf = new ArrayBuffer(16);
+    new Int32Array(buf).set([TOKEN, seq, id, total]);
+    return buf;
+  }
+  function unpackToken(buf) {
+    const iv = new Int32Array(buf, 0, 4);
+    return { seq: iv[1], id: iv[2], total: iv[3] };
+  }
+  function packDone(seq) { return new Int32Array([DONE, seq]).buffer; }
+
+  // ---- ready ------------------------------------------------------------------
+  function packReady(stageIndex, ok, note) {
+    const bytes = enc.encode(JSON.stringify({ stageIndex, ok: !!ok, note: String(note || "").slice(0, 300) }));
+    const buf = new ArrayBuffer(4 + bytes.length);
+    new Int32Array(buf, 0, 1)[0] = READY;
+    new Uint8Array(buf, 4).set(bytes);
+    return buf;
+  }
+  function unpackReady(buf) {
+    try { return JSON.parse(dec.decode(new Uint8Array(buf, 4))); }
+    catch (e) { throw new Error("ready: payload is not valid JSON"); }
+  }
+
+  const api = { FRAG, HELLO, ASSIGN, READY, ACT, TOKEN, DONE, RETURN, tagOf,
+                packHello, unpackHello, packAssign, unpackAssign, packReady, unpackReady,
+                packAct, unpackAct, packToken, unpackToken, packDone,
+                routeAfter, classifyAct };
+  if (typeof module !== "undefined" && module.exports) module.exports = api;
+  else root.Wire = api;
+})(typeof self !== "undefined" ? self : this);

server.js

@@ -0,0 +1,257 @@
+// DaisyChain-Infer signaling + static host.
+//
+// Deliberately tiny. What it does NOT do is the point: it introduces peers and
+// relays WebRTC handshakes, and never sees a weight, an activation, a prompt,
+// or a generated token. Those move directly between the devices in the ring,
+// and weights come from the Hugging Face CDN straight to each browser.
+//
+// The one exception is the OAuth code exchange below, which by construction
+// has to handle an access token for a few milliseconds. That is called out
+// rather than glossed: see the comment on /auth/callback.
+//
+// Only dependency: `ws`.  Run:  npm install && npm start
+const http = require("http");
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+const { WebSocketServer } = require("ws");
+
+// ---- rooms -------------------------------------------------------------------
+// Snapdrop-style grouping: same public IP -> same room, so devices on your own
+// network find each other with no code. ?room=CODE crosses networks, gated by
+// host approval.
+function clientIP(req) {
+  const xff = req.headers["x-forwarded-for"];
+  if (xff) return xff.split(",")[0].trim();
+  return (req.socket.remoteAddress || "unknown").replace(/^::ffff:/, "");
+}
+function roomFor(req) {
+  const u = new URL(req.url, "http://x");
+  const code = u.searchParams.get("room");
+  if (code) return "room:" + code;
+  const h = crypto.createHash("sha256").update(clientIP(req)).digest("hex").slice(0, 10);
+  return "net:" + h;
+}
+
+const PORT = process.env.PORT || 8788;
+const PUB = path.join(__dirname, "public");
+const TYPES = { ".html": "text/html", ".js": "text/javascript",
+                ".css": "text/css", ".json": "application/json" };
+
+// ---- OAuth (hosted deployments) ----------------------------------------------
+// On a Hugging Face Space with `hf_oauth: true`, these are injected by the
+// platform. When they are absent — a local run — OAuth is simply off and the
+// page falls back to asking for a token directly, which is safe there because
+// the page is served from the user's own machine.
+const OA = {
+  clientId: process.env.OAUTH_CLIENT_ID,
+  clientSecret: process.env.OAUTH_CLIENT_SECRET,
+  scopes: process.env.OAUTH_SCOPES || "read-repos",
+  provider: (process.env.OPENID_PROVIDER_URL || "https://huggingface.co").replace(/\/$/, ""),
+  spaceHost: process.env.SPACE_HOST || "",
+};
+const oauthOn = !!(OA.clientId && OA.clientSecret);
+
+// One-time `state` values, so a callback cannot be replayed or forged. Short
+// TTL, and consumed on use.
+const states = new Map();                 // state -> expiry ms
+function newState() {
+  const s = crypto.randomBytes(24).toString("base64url");
+  states.set(s, Date.now() + 10 * 60 * 1000);
+  return s;
+}
+function takeState(s) {
+  const exp = states.get(s);
+  if (exp === undefined) return false;
+  states.delete(s);                       // single use
+  return exp > Date.now();
+}
+setInterval(() => {
+  const now = Date.now();
+  for (const [s, exp] of states) if (exp <= now) states.delete(s);
+}, 60000);
+
+function redirectUri(req) {
+  const host = OA.spaceHost || req.headers.host;
+  const proto = OA.spaceHost || /^(localhost|127\.|\[::1\])/.test(host || "") === false ? "https" : "http";
+  return `${proto}://${host}/auth/callback`;
+}
+
+function oauthLogin(req, res) {
+  const state = newState();
+  const u = new URL(OA.provider + "/oauth/authorize");
+  u.searchParams.set("client_id", OA.clientId);
+  u.searchParams.set("redirect_uri", redirectUri(req));
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("scope", OA.scopes);
+  u.searchParams.set("state", state);
+  res.writeHead(302, { Location: u.toString() });
+  res.end();
+}
+
+// The token exchange needs the client secret, so it MUST happen here rather
+// than in the browser — which means this server briefly holds an access token.
+// It is never written to disk, never logged, and never kept: it is handed to
+// the browser in the URL *fragment*, which browsers do not send to servers and
+// which the page strips from history immediately on arrival. That is the
+// smallest exposure the OAuth flow allows; it is not zero, and the Space's
+// README says so.
+async function oauthCallback(req, res, url) {
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  const err = url.searchParams.get("error");
+  const bail = (msg) => {
+    res.writeHead(302, { Location: "/#oauth_error=" + encodeURIComponent(msg) });
+    res.end();
+  };
+  if (err) return bail(err);
+  if (!code || !state) return bail("missing code or state");
+  if (!takeState(state)) return bail("state was not recognised — start the sign-in again");
+  try {
+    const body = new URLSearchParams({
+      grant_type: "authorization_code",
+      code,
+      redirect_uri: redirectUri(req),
+      client_id: OA.clientId,
+      client_secret: OA.clientSecret,
+    });
+    const r = await fetch(OA.provider + "/oauth/token", {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+      body,
+    });
+    if (!r.ok) return bail(`token exchange failed (HTTP ${r.status})`);
+    const j = await r.json();
+    if (!j.access_token) return bail("no access token in the response");
+    res.writeHead(302, { Location: "/#hf=" + encodeURIComponent(j.access_token) });
+    res.end();
+  } catch (e) {
+    bail("token exchange error");                 // deliberately not e.message
+  }
+}
+
+// keepalive: proxies close idle WebSockets, and a ring can sit idle between
+// prompts far longer than a training run ever does
+setInterval(() => {
+  for (const room of rooms.values())
+    for (const [, v] of room.peers) {
+      if (v.ws.isAlive === false) { v.ws.terminate(); continue; }
+      v.ws.isAlive = false;
+      send(v.ws, { type: "ping" });
+    }
+}, 30000);
+
+const server = http.createServer((req, res) => {
+  const url = new URL(req.url, "http://x");
+  let p = decodeURIComponent(url.pathname);
+
+  if (p === "/mode") {
+    let rtc = null;
+    try { if (process.env.DAISY_RTC_CONFIG) rtc = JSON.parse(process.env.DAISY_RTC_CONFIG); } catch (e) {}
+    res.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
+    return res.end(JSON.stringify({
+      // DAISY_FORCE_ROOMS=1 (set on the hosted Space): no LAN auto-grouping, so
+      // strangers who happen to share a public IP — same CGNAT, same campus,
+      // same office — are never put in one ring. Each visitor makes their own
+      // room and invites devices by link.
+      forceRooms: !!process.env.DAISY_FORCE_ROOMS,
+      // When OAuth is available the page does not offer a paste-a-token box at
+      // all: on a deployment the user does not control, signing in is the only
+      // credential path offered.
+      oauth: oauthOn,
+      rtc,
+    }));
+  }
+  if (p === "/auth/login" || p === "/oauth/login") {
+    if (!oauthOn) { res.writeHead(404); return res.end("oauth is not configured"); }
+    return oauthLogin(req, res);
+  }
+  // HF registers /auth/callback for Spaces; the alias costs nothing and saves a
+  // broken deploy if the platform ever hands back the other spelling.
+  if (p === "/auth/callback" || p === "/oauth/callback") {
+    if (!oauthOn) { res.writeHead(404); return res.end("oauth is not configured"); }
+    return void oauthCallback(req, res, url);
+  }
+
+  if (p === "/") p = "/index.html";
+  const file = path.join(PUB, path.normalize(p));
+  if (!file.startsWith(PUB)) { res.writeHead(403); return res.end(); }
+  fs.readFile(file, (err, data) => {
+    if (err) { res.writeHead(404); return res.end("not found"); }
+    res.writeHead(200, { "Content-Type": TYPES[path.extname(file)] || "application/octet-stream" });
+    res.end(data);
+  });
+});
+
+const wss = new WebSocketServer({ server });
+const rooms = new Map();
+let nextId = 1;
+function send(ws, obj) { if (ws.readyState === 1) ws.send(JSON.stringify(obj)); }
+
+wss.on("connection", (ws, req) => {
+  const roomId = roomFor(req);
+  const name = (new URL(req.url, "http://x").searchParams.get("name") || "").slice(0, 40) || ("p" + nextId);
+  const id = "p" + (nextId++);
+  ws.peerId = id; ws.roomId = roomId;
+  if (!rooms.has(roomId)) rooms.set(roomId, { peers: new Map(), host: null, pending: new Map() });
+  const room = rooms.get(roomId);
+  const isPrivate = roomId.startsWith("room:");
+
+  function admit(pid, peer) {
+    const roster = [...room.peers.entries()].map(([qid, v]) => ({ id: qid, name: v.name }));
+    send(peer.ws, { type: "welcome", id: pid, room: roomId, peers: roster, host: room.host === pid });
+    for (const [, v] of room.peers) send(v.ws, { type: "peer-joined", id: pid, name: peer.name });
+    room.peers.set(pid, peer);
+  }
+
+  if (isPrivate && room.peers.size === 0) room.host = id;
+  if (isPrivate && room.host !== id) {
+    room.pending.set(id, { ws, name });
+    send(ws, { type: "waiting" });
+    const h = room.peers.get(room.host);
+    if (h) send(h.ws, { type: "join-request", id, name });
+  } else {
+    admit(id, { ws, name });
+  }
+
+  ws.on("message", (buf) => {
+    let msg; try { msg = JSON.parse(buf); } catch { return; }
+    if (msg.type === "signal" && msg.to && room.peers.has(id)) {
+      const target = room.peers.get(msg.to);
+      if (target) send(target.ws, { type: "signal", from: id, data: msg.data });
+    } else if (msg.type === "pong") {
+      ws.isAlive = true;
+    } else if (msg.type === "relay" && msg.to && room.peers.has(id)) {
+      // last-resort path when two devices cannot form a direct WebRTC route.
+      // Note this DOES put activations through the server — the UI says so.
+      const target = room.peers.get(msg.to);
+      if (target) send(target.ws, { type: "relay", from: id, data: msg.data });
+    } else if (msg.type === "admit" && id === room.host) {
+      const p = room.pending.get(msg.id);
+      if (!p) return;
+      room.pending.delete(msg.id);
+      if (msg.allow) admit(msg.id, p);
+      else { send(p.ws, { type: "denied" }); p.ws.close(); }
+    }
+  });
+
+  ws.on("close", () => {
+    room.pending.delete(id);
+    if (room.peers.delete(id))
+      for (const [, v] of room.peers) send(v.ws, { type: "peer-left", id });
+    if (room.host === id) {
+      room.host = room.peers.keys().next().value ?? null;
+      const h = room.peers.get(room.host);
+      if (h) {
+        send(h.ws, { type: "host" });
+        for (const [pid, p] of room.pending) send(h.ws, { type: "join-request", id: pid, name: p.name });
+      }
+    }
+    if (room.peers.size === 0 && room.pending.size === 0) rooms.delete(roomId);
+  });
+});
+
+server.listen(PORT, () =>
+  console.log(`DaisyChain-Infer on http://localhost:${PORT}` +
+              (oauthOn ? " (HF OAuth enabled)" : "") +
+              (process.env.DAISY_FORCE_ROOMS ? " (rooms forced)" : "")));

test_loader.js

@@ -0,0 +1,179 @@
+// The loader: safetensors parsing, dtype widening, range coalescing, and BPE.
+//
+// This is the layer where "load any model off HuggingFace" is either true or
+// quietly false. Every failure here is silent by nature — a misread offset
+// gives plausible floats, a wrong dtype gives plausible floats, a
+// half-implemented tokenizer gives plausible text. So the checks are exact,
+// and several are built by CONSTRUCTING a file and reading it back rather than
+// by trusting a fixture.
+//
+//   node test_loader.js
+const assert = require("assert");
+const ST = require("./public/safetensors.js");
+const Tok = require("./public/tokenizer.js");
+const Arch = require("./public/arch.js");
+
+let failed = 0;
+function t(name, fn) {
+  try { fn(); console.log(`  ok    ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+console.log("\nDaisyChain-Infer — loader\n");
+
+// Build a real safetensors buffer so the parser is tested against the format,
+// not against our own idea of it.
+function buildFile(entries) {
+  let offset = 0;
+  const header = {};
+  const chunks = [];
+  for (const [name, dtype, shape, bytes] of entries) {
+    header[name] = { dtype, shape, data_offsets: [offset, offset + bytes.length] };
+    chunks.push(bytes);
+    offset += bytes.length;
+  }
+  const hj = Buffer.from(JSON.stringify(header), "utf8");
+  const out = Buffer.alloc(8 + hj.length + offset);
+  out.writeUInt32LE(hj.length, 0); out.writeUInt32LE(0, 4);
+  hj.copy(out, 8);
+  let o = 8 + hj.length;
+  for (const c of chunks) { Buffer.from(c).copy(out, o); o += c.length; }
+  return out.buffer.slice(out.byteOffset, out.byteOffset + out.length);
+}
+
+t("parses a header and locates every tensor", () => {
+  const a = Buffer.from(new Float32Array([1, 2, 3, 4]).buffer);
+  const b = Buffer.from(new Float32Array([5, 6]).buffer);
+  const buf = buildFile([["w.a", "F32", [2, 2], a], ["w.b", "F32", [2], b]]);
+  const { tensors } = ST.parseHeader(buf);
+  assert.strictEqual(tensors.size, 2);
+  const ta = tensors.get("w.a");
+  assert.deepStrictEqual(ta.shape, [2, 2]);
+  assert.strictEqual(ta.elems, 4);
+  assert.deepStrictEqual([...ST.toF32("F32", new Uint8Array(buf, ta.start, ta.bytes))], [1, 2, 3, 4]);
+  const tb = tensors.get("w.b");
+  assert.deepStrictEqual([...ST.toF32("F32", new Uint8Array(buf, tb.start, tb.bytes))], [5, 6]);
+});
+
+// A shape that disagrees with the byte range means every subsequent tensor
+// would be read at the wrong offset — plausible floats all the way down.
+t("a header whose shape contradicts its byte range is refused", () => {
+  const a = Buffer.from(new Float32Array([1, 2, 3, 4]).buffer);
+  const buf = buildFile([["w", "F32", [9, 9], a]]);
+  assert.throws(() => ST.parseHeader(buf), /expected/);
+});
+
+t("junk in place of a header is refused, not guessed at", () => {
+  const junk = Buffer.alloc(64); junk.writeUInt32LE(16, 0);
+  assert.throws(() => ST.parseHeader(junk.buffer.slice(0, 64)), /not valid JSON|not a safetensors/);
+  const big = Buffer.alloc(16); big.writeUInt32LE(0, 0); big.writeUInt32LE(7, 4);
+  assert.throws(() => ST.parseHeader(big.buffer.slice(0, 16)), /implausibly large/);
+});
+
+// BF16 is the top 16 bits of an f32, so widening must be EXACT — not close.
+t("BF16 widens exactly (it is the high half of an f32)", () => {
+  const vals = [1, -1, 0.5, -0.5, 2, 100, -0.0078125, 0];
+  const u16 = new Uint16Array(vals.length);
+  const f = new Float32Array(1), u = new Uint32Array(f.buffer);
+  for (let i = 0; i < vals.length; i++) { f[0] = vals[i]; u16[i] = u[0] >>> 16; }
+  const out = ST.bf16ToF32(u16, new Float32Array(vals.length));
+  for (let i = 0; i < vals.length; i++)
+    assert.strictEqual(out[i], vals[i], `bf16 round-trip changed ${vals[i]} to ${out[i]}`);
+});
+
+t("F16 widens exactly, including subnormals and signed zero", () => {
+  // every f16 has an exact f32 value, so this is a widening with no error
+  const cases = [[0x3C00, 1], [0xBC00, -1], [0x3800, 0.5], [0x0000, 0], [0x8000, -0],
+                 [0x0001, Math.pow(2, -24)], [0x7BFF, 65504]];
+  const u16 = Uint16Array.from(cases.map(c => c[0]));
+  const out = ST.f16ToF32(u16, new Float32Array(cases.length));
+  cases.forEach(([, want], i) =>
+    assert.ok(Object.is(out[i], want), `f16 ${i}: got ${out[i]}, want ${want}`));
+});
+
+// Coalescing is a bandwidth optimisation, and a wrong one would hand a tensor
+// the wrong bytes. It must merge only what is genuinely adjacent, and the
+// per-tensor offsets must still land correctly inside a merged run.
+t("range coalescing merges neighbours and keeps offsets correct", () => {
+  const mk = (start, end) => ({ start, end, bytes: end - start, elems: (end - start) / 4, dtype: "F32", name: `t${start}` });
+  const runs = ST.coalesce([mk(0, 100), mk(100, 200), mk(10_000_000, 10_000_100)], 1024);
+  assert.strictEqual(runs.length, 2, "adjacent ranges were not merged, or a distant one was");
+  assert.deepStrictEqual([runs[0].start, runs[0].end], [0, 200]);
+  assert.strictEqual(runs[0].tensors.length, 2);
+  assert.deepStrictEqual([runs[1].start, runs[1].end], [10_000_000, 10_000_100]);
+  // a tensor's data must be recoverable from its offset within the merged run
+  const t2 = runs[0].tensors[1];
+  assert.strictEqual(t2.start - runs[0].start, 100);
+});
+
+t("stage byte cost is computed from the header alone", () => {
+  const spec = Arch.fromConfig({ model_type: "llama", hidden_size: 64, num_hidden_layers: 4,
+    num_attention_heads: 4, num_key_value_heads: 4, intermediate_size: 128, vocab_size: 100 });
+  const names = new Map();
+  const add = (n, elems) => names.set(n, { name: n, elems, bytes: elems * 2, dtype: "BF16", shape: [elems] });
+  const h = Arch.headTensors(spec);
+  add(h.emb, 100 * 64); add(h.nrmF, 64);
+  for (let l = 0; l < 4; l++) {
+    const lt = Arch.layerTensors(spec, l);
+    add(lt.nrm1, 64); add(lt.nrm2, 64);
+    add(lt.Wq, 64 * 64); add(lt.Wk, 64 * 64); add(lt.Wv, 64 * 64); add(lt.Wo, 64 * 64);
+    add(lt.Wgate, 128 * 64); add(lt.Wup, 128 * 64); add(lt.Wdown, 64 * 128);
+  }
+  const Shard = require("./public/shard.js");
+  const mid = Shard.stageBytes(spec, names, { lo: 1, hi: 2, head: false }, Arch);
+  const head = Shard.stageBytes(spec, names, { lo: 0, hi: 1, head: true }, Arch);
+  assert.strictEqual(mid, (4 * 64 * 64 + 3 * 128 * 64 + 2 * 64) * 4, "middle stage cost is wrong");
+  assert.ok(head > mid, "the head must cost more — it holds the embedding table");
+});
+
+// ---- tokenizer --------------------------------------------------------------
+// A tiny byte-level BPE built by hand, so encode/decode are checked against a
+// known merge table rather than against themselves.
+const TOKJSON = (() => {
+  const vocab = {};
+  let id = 0;
+  // single byte-level characters for the printable ASCII we use
+  for (const ch of "ĠabcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ.,!") vocab[ch] = id++;
+  vocab["ab"] = id++; vocab["abc"] = id++; vocab["Ġth"] = id++; vocab["Ġthe"] = id++;
+  const merges = ["a b", "ab c", "Ġ t h", "Ġth e"].map(m => m.replace(/^(\S+) (\S+)$/, "$1 $2"));
+  return { model: { type: "BPE", vocab, merges: ["a b", "ab c", "Ġt h", "Ġth e"] },
+           added_tokens: [{ id: id++, content: "<|end|>" }] };
+})();
+
+t("byte-level BPE round-trips text exactly", () => {
+  const tk = Tok.build(TOKJSON);
+  for (const s of ["abc", "abc abc", "the", " the", "hello world", "a,b!c."]) {
+    const ids = Tok.encode(tk, s);
+    assert.strictEqual(Tok.decode(tk, ids), s, `"${s}" did not round-trip (got "${Tok.decode(tk, ids)}")`);
+  }
+});
+
+t("BPE actually applies its merges", () => {
+  const tk = Tok.build(TOKJSON);
+  // "abc" must become the single merged token, not three characters
+  assert.deepStrictEqual([...Tok.encode(tk, "abc")], [tk.vocab["abc"]], "merges were not applied");
+  assert.deepStrictEqual([...Tok.encode(tk, "ab")], [tk.vocab["ab"]]);
+});
+
+t("added/special tokens stay whole and are hidden on decode", () => {
+  const tk = Tok.build(TOKJSON);
+  const ids = [...Tok.encode(tk, "abc<|end|>abc")];
+  assert.ok(ids.includes(tk.added.get("<|end|>")), "the special token was split up");
+  assert.strictEqual(Tok.decode(tk, ids), "abcabc", "special tokens should not appear in output text");
+  assert.ok(Tok.decode(tk, ids, true).includes("<|end|>"), "keepSpecial should show them");
+});
+
+t("a non-BPE tokenizer is refused rather than approximated", () => {
+  assert.throws(() => Tok.build({ model: { type: "Unigram", vocab: {} } }), /not supported/);
+  assert.throws(() => Tok.build({ model: { type: "WordPiece", vocab: {} } }), /not supported/);
+});
+
+t("the byte table covers all 256 bytes and is a bijection", () => {
+  const { b2u, u2b } = Tok.byteTables();
+  assert.strictEqual(b2u.size, 256, "byte->unicode table is incomplete");
+  assert.strictEqual(u2b.size, 256, "unicode->byte table is incomplete");
+  for (let b = 0; b < 256; b++) assert.strictEqual(u2b.get(b2u.get(b)), b, `byte ${b} does not round-trip`);
+});
+
+console.log(failed ? `\n${failed} failure(s)\n` : "\nall loader checks passed\n");
+process.exit(failed ? 1 : 0);

test_pipeline.js

@@ -0,0 +1,193 @@
+// The central claim of this project, as a test that runs.
+//
+// Splitting a model across machines is only safe if the split changes nothing.
+// That is checkable here in a way it usually is not, because the pieces are
+// deterministic: run a prompt with every layer on one "device", then again
+// with the layers handed out across N simulated stages passing hidden states
+// between them, and compare.
+//
+// The comparison is EXACT — bit patterns, not a tolerance. A correct split is
+// not merely close to the unsplit result, it is identical, because the ring
+// never re-derives anything; it only moves f32 arrays. A tolerance here would
+// hide exactly the bugs worth finding: dropping one layer out of twelve moves
+// the logits far less than you would guess, and still reads as fluent text.
+//
+//   node test_pipeline.js
+const assert = require("assert");
+const Shard = require("./public/shard.js");
+const Infer = require("./public/infer.js");
+const Arch = require("./public/arch.js");
+
+// The LUT is exactly a*b for int8 — what the verified mul8 unit is proven to
+// reproduce. Rebuilding it here keeps the test fixture-free without weakening
+// it, since the unit's whole claim is that it equals this.
+const L = (() => {
+  const mul = new Int16Array(65536);
+  for (let a = 0; a < 256; a++)
+    for (let b = 0; b < 256; b++) mul[a * 256 + b] = (a > 127 ? a - 256 : a) * (b > 127 ? b - 256 : b);
+  return { mul };
+})();
+const ctx = () => ({ L, bgemm: null, att: null, mlp: null, audit: null });   // CPU mirror
+
+function mulberry32(a) { return function () { a |= 0; a = a + 0x6D2B79F5 | 0; let t = Math.imul(a ^ a >>> 15, 1 | a); t = t + Math.imul(t ^ t >>> 7, 61 | t) ^ t; return ((t ^ t >>> 14) >>> 0) / 4294967296; }; }
+function rnd(n, seed, scale) {
+  const r = mulberry32(seed), o = new Float32Array(n);
+  for (let i = 0; i < n; i++) o[i] = (r() * 2 - 1) * (scale || 1);
+  return o;
+}
+
+// Build a weights map keyed exactly as the real repos key them, so the test
+// exercises the same name resolution and layout handling the loader uses.
+function makeWeights(spec) {
+  const got = new Map();
+  const C = spec.hidden, qDim = spec.heads * spec.headDim, kvDim = spec.kvHeads * spec.headDim;
+  let seed = 7;
+  const put = (n, len, scale) => got.set(n, rnd(len, seed++, scale ?? 0.08));
+  const h = Arch.headTensors(spec);
+  put(h.emb, spec.vocab * C, 0.05);
+  if (h.pos) put(h.pos, spec.maxPos * C, 0.02);
+  put(h.nrmF, C, 1);
+  got.set(h.nrmF, new Float32Array(C).fill(1));
+  if (spec.norm === "ln") got.set(h.nrmFb, new Float32Array(C));
+  if (!spec.tie) put(h.lmHead, spec.vocab * C, 0.05);
+  for (let l = 0; l < spec.layers; l++) {
+    const t = Arch.layerTensors(spec, l);
+    got.set(t.nrm1, new Float32Array(C).fill(1));
+    got.set(t.nrm2, new Float32Array(C).fill(1));
+    if (spec.norm === "ln") { got.set(t.nrm1b, new Float32Array(C)); got.set(t.nrm2b, new Float32Array(C)); }
+    if (spec.qkvFused) { put(t.Wqkv, C * 3 * C); got.set(t.bqkv, new Float32Array(3 * C)); }
+    else { put(t.Wq, qDim * C); put(t.Wk, kvDim * C); put(t.Wv, kvDim * C); }
+    put(t.Wo, C * qDim);
+    if (spec.qkvFused) got.set(t.bo, new Float32Array(C));
+    if (spec.gated) { put(t.Wgate, spec.inter * C); put(t.Wup, spec.inter * C); }
+    else { put(t.Wfc, spec.inter * C); got.set(t.bfc, new Float32Array(spec.inter)); }
+    put(t.Wdown, C * spec.inter);
+    if (!spec.gated) got.set(t.bdown, new Float32Array(C));
+  }
+  return got;
+}
+
+function stagesFor(spec, got, splits, T) {
+  const plan = [];
+  let lo = 0;
+  splits.forEach((n, i) => { plan.push({ id: "p" + i, index: i, lo, hi: lo + n, head: i === 0 }); lo += n; });
+  assert.strictEqual(lo, spec.layers, "splits must cover every layer exactly once");
+  return plan.map(st => Infer.makeStage(spec, st, Shard.stageWeights(spec, st, got, Arch), ctx(), T));
+}
+
+async function ringGenerate(spec, stages, ids, nTok, T) {
+  const head = stages[0];
+  const out = [...ids];
+  for (let n = 0; n < nTok; n++) {
+    const win = new Int32Array(T);
+    const tail = out.slice(-T);
+    for (let i = 0; i < tail.length; i++) win[T - tail.length + i] = tail[i];
+    let x = Infer.embed(head, win);
+    for (const S of stages) x = await Infer.runLayers(S, x);       // the "hop"
+    out.push(Infer.pickToken(await Infer.readout(head, x), { temperature: 0 }));
+  }
+  return out;
+}
+
+function bitsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const ua = new Uint32Array(a.buffer, a.byteOffset, a.length);
+  const ub = new Uint32Array(b.buffer, b.byteOffset, b.length);
+  for (let i = 0; i < ua.length; i++) if (ua[i] !== ub[i]) return false;
+  return true;
+}
+
+// Two architectures, because the whole point of arch.js is that the ring does
+// not care which one it is running. Llama-style exercises RMSNorm/RoPE/GQA/
+// SwiGLU; GPT-2-style exercises LayerNorm+bias, fused QKV and GELU.
+const LLAMA = Arch.fromConfig({
+  model_type: "llama", hidden_size: 64, num_hidden_layers: 6, num_attention_heads: 4,
+  num_key_value_heads: 2, intermediate_size: 128, vocab_size: 128,
+  max_position_embeddings: 64, rms_norm_eps: 1e-5, tie_word_embeddings: true,
+});
+const GPT2 = Arch.fromConfig({
+  model_type: "gpt2", n_embd: 64, n_layer: 6, n_head: 4, vocab_size: 128,
+  n_positions: 64, n_inner: 128, layer_norm_epsilon: 1e-5,
+});
+
+(async function () {
+  let failed = 0;
+  const t = (name, fn) => fn().then(
+    () => console.log(`  ok    ${name}`),
+    (e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+
+  console.log("\nDaisyChain-Infer — pipeline equivalence\n");
+
+  const T = 16, PROMPT = [5, 11, 42, 7];
+
+  for (const [label, spec] of [["llama-style", LLAMA], ["gpt2-style", GPT2]]) {
+    console.log(`  ${label}: ${spec.layers} layers, hidden ${spec.hidden}, ` +
+                `heads ${spec.heads}/${spec.kvHeads}, ${spec.gated ? "SwiGLU" : "GELU"}, ` +
+                `${spec.norm.toUpperCase()}, rope=${spec.rope}`);
+    const got = makeWeights(spec);
+    const ref = await ringGenerate(spec, stagesFor(spec, got, [spec.layers], T), PROMPT, 8, T);
+
+    await t(`${label}: a stage boundary changes no bit of the hidden state`, async () => {
+      const whole = stagesFor(spec, got, [spec.layers], T);
+      const split = stagesFor(spec, got, [2, 2, 2], T);
+      const win = new Int32Array(T);
+      for (let i = 0; i < PROMPT.length; i++) win[T - PROMPT.length + i] = PROMPT[i];
+      const a = await Infer.runLayers(whole[0], Infer.embed(whole[0], win));
+      let b = Infer.embed(split[0], win);
+      for (const S of split) b = await Infer.runLayers(S, b);
+      assert.ok(bitsEqual(a, b), "hidden states diverged across the split");
+    });
+
+    for (const splits of [[3, 3], [1, 2, 3], [0, 3, 3], [2, 1, 1, 1, 1], [1, 1, 1, 1, 1, 1]]) {
+      await t(`${label}: generation is identical when split ${JSON.stringify(splits)}`, async () => {
+        const out = await ringGenerate(spec, stagesFor(spec, got, splits, T), PROMPT, 8, T);
+        assert.deepStrictEqual(out, ref, `split ${splits} produced different tokens`);
+      });
+    }
+
+    // Mutation checks. Without these, a test where both sides call the same
+    // code proves nothing at all.
+    await t(`${label}: a stage that silently skips a layer IS caught`, async () => {
+      const stages = stagesFor(spec, got, [2, 2, 2], T);
+      stages[1].w.layers.pop();
+      const out = await ringGenerate(spec, stages, PROMPT, 8, T);
+      assert.notDeepStrictEqual(out, ref, "dropping a whole layer changed nothing — the check is blind");
+    });
+    await t(`${label}: stages applied out of order ARE caught`, async () => {
+      const stages = stagesFor(spec, got, [2, 2, 2], T);
+      const out = await ringGenerate(spec, [stages[0], stages[2], stages[1]], PROMPT, 8, T);
+      assert.notDeepStrictEqual(out, ref, "layer order did not matter — the check is blind");
+    });
+  }
+
+  // A wrong transpose does not throw; it yields a model that generates
+  // confident nonsense. So the layout conversion gets its own check.
+  await t("weight layout conversion is a real transpose, and in_out is a no-op", async () => {
+    const w = Float32Array.from([1, 2, 3, 4, 5, 6]);           // (out=2, in=3)
+    const kn = Shard.toKN(w, 2, 3, "out_in");
+    assert.deepStrictEqual([...kn], [1, 4, 2, 5, 3, 6], "out_in did not transpose to k x n");
+    assert.strictEqual(Shard.toKN(w, 2, 3, "in_out"), w, "in_out must pass through untouched");
+  });
+
+  await t("architecture detection maps real configs, and refuses unknown ones", async () => {
+    assert.strictEqual(Arch.fromConfig({ model_type: "qwen2", hidden_size: 896, num_hidden_layers: 24,
+      num_attention_heads: 14, num_key_value_heads: 2, intermediate_size: 4864, vocab_size: 151936 }).family, "llama");
+    assert.strictEqual(Arch.fromConfig({ model_type: "gpt2", n_embd: 768, n_layer: 12,
+      n_head: 12, vocab_size: 50257 }).family, "gpt2");
+    assert.throws(() => Arch.fromConfig({ model_type: "mamba", hidden_size: 8, num_hidden_layers: 1,
+      num_attention_heads: 1, vocab_size: 8 }), /unsupported architecture/);
+    assert.throws(() => Arch.fromConfig({ model_type: "llama" }), /missing/);
+  });
+
+  await t("planning is deterministic and capacity-weighted", async () => {
+    const caps = [{ id: "p1", capacity: 100 }, { id: "p2", capacity: 300 }, { id: "p3", capacity: 200 }];
+    const a = Shard.planStages(LLAMA, caps), b = Shard.planStages(LLAMA, caps);
+    assert.deepStrictEqual(a, b, "planning is not deterministic");
+    assert.strictEqual(a.reduce((s, x) => s + (x.hi - x.lo), 0), LLAMA.layers, "plan does not cover every layer");
+    assert.ok(a[1].hi - a[1].lo > a[0].hi - a[0].lo, "the faster device did not get more layers");
+    assert.ok(a[0].head, "stage 0 must be the head");
+  });
+
+  console.log(failed ? `\n${failed} failure(s)\n` : "\nall pipeline checks passed\n");
+  process.exit(failed ? 1 : 0);
+})();

test_wire.js

@@ -0,0 +1,209 @@
+// Protocol round-trips, and the malformed messages the protocol must refuse.
+//
+// The reason this file exists separately from test_pipeline.js: the pipeline
+// test proves the MATH survives being split. It cannot see a protocol bug,
+// because it never encodes anything — it hands Float32Arrays between stages
+// directly. Every real failure of a distributed system lives in the gap those
+// two tests leave for each other, which is exactly what DaisyChain-Web's own
+// self-corpus writeup concluded after a stalled roster gradient turned out to
+// be a protocol bug that no data oracle could fire on.
+//
+//   node test_wire.js
+const assert = require("assert");
+const Wire = require("./public/wire.js");
+const Shard = require("./public/shard.js");
+
+const SPEC = { family: "llama", layers: 6, hidden: 64, heads: 4, kvHeads: 2, vocab: 128 };
+const PLAN = [{ id: "p1", index: 0, lo: 0, hi: 2, head: true },
+              { id: "p7", index: 1, lo: 2, hi: 4, head: false },
+              { id: "p3", index: 2, lo: 4, hi: 6, head: false }];
+function assign(over) { return Object.assign({ repo: "owner/model", revision: "main", spec: SPEC, plan: PLAN, mine: 1, fingerprint: 123 }, over || {}); }
+
+function bitsEqual(a, b) {
+  if (a.length !== b.length) return false;
+  const ua = new Uint32Array(a.buffer, a.byteOffset, a.length);
+  const ub = new Uint32Array(b.buffer, b.byteOffset, b.length);
+  for (let i = 0; i < ua.length; i++) if (ua[i] !== ub[i]) return false;
+  return true;
+}
+
+let failed = 0;
+function t(name, fn) {
+  try { fn(); console.log(`  ok    ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+console.log("\nDaisyChain-Infer — wire protocol\n");
+
+t("hello round-trips, including the backend string", () => {
+  const b = Wire.packHello(1234.5, 0xDEADBEEF, "webgpu");
+  assert.strictEqual(Wire.tagOf(b), Wire.HELLO);
+  const h = Wire.unpackHello(b);
+  assert.strictEqual(Math.fround(1234.5), h.capacity);
+  assert.strictEqual(h.probeHash, 0xDEADBEEF);
+  assert.strictEqual(h.backend, "webgpu");
+});
+
+t("assignment round-trips the model identity and the plan", () => {
+  const a = Wire.unpackAssign(Wire.packAssign(assign()));
+  assert.strictEqual(a.repo, "owner/model");
+  assert.strictEqual(a.revision, "main");
+  assert.strictEqual(a.mine, 1);
+  assert.strictEqual(a.spec.layers, 6);
+  assert.deepStrictEqual(a.plan.map(s2 => [s2.lo, s2.hi]), [[0, 2], [2, 4], [4, 6]]);
+});
+
+// An assignment carries no weights by design — each device fetches its own
+// layers from the Hub. This asserts the message stays small no matter how big
+// the model is, which is what keeps a token off the wire and a peer from ever
+// shipping weights to another peer.
+t("an assignment carries no weight data", () => {
+  const buf = Wire.packAssign(assign({ spec: Object.assign({}, SPEC, { hidden: 4096, layers: 80, vocab: 128000 }) }));
+  assert.ok(buf.byteLength < 2048, `assignment is ${buf.byteLength} bytes — it must never carry weights`);
+});
+
+// The failure this rejects produces a plausible answer rather than an error:
+// a plan missing a layer still generates fluent text.
+t("a plan that does not cover every layer is refused", () => {
+  const gap = [{ id: "p1", lo: 0, hi: 2, head: true }, { id: "p2", lo: 3, hi: 6, head: false }];
+  assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ plan: gap }))), /cover 5 of 6/);
+  const over = [{ id: "p1", lo: 0, hi: 4, head: true }, { id: "p2", lo: 2, hi: 6, head: false }];
+  assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ plan: over }))), /cover 8 of 6/);
+  const oob = [{ id: "p1", lo: 0, hi: 9, head: true }];
+  assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ plan: oob }))), /out of bounds/);
+});
+
+t("an assignment whose stage 0 is not the head is refused", () => {
+  const bad = [{ id: "p1", lo: 0, hi: 3, head: false }, { id: "p2", lo: 3, hi: 6, head: true }];
+  assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ plan: bad }))), /stage 0 must be the head/);
+});
+
+// A repo id is interpolated straight into a Hub URL, so it is validated rather
+// than trusted: a peer should not be able to point this device at an arbitrary
+// path by sending a crafted assignment.
+t("a malformed repo id is refused", () => {
+  for (const repo of ["", "nope", "../../etc/passwd", "owner/name/extra", "owner/na me"])
+    assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ repo }))), /repo id/, `accepted "${repo}"`);
+});
+
+t("an assignment with no valid stage index for this device is refused", () => {
+  assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ mine: 9 }))), /stage index/);
+  assert.throws(() => Wire.unpackAssign(Wire.packAssign(assign({ mine: -1 }))), /stage index/);
+});
+
+t("ready round-trips", () => {
+  const r = Wire.unpackReady(Wire.packReady(2, true, "loaded"));
+  assert.strictEqual(r.stageIndex, 2);
+  assert.strictEqual(r.ok, true);
+  const bad = Wire.unpackReady(Wire.packReady(1, false, "out of memory"));
+  assert.strictEqual(bad.ok, false);
+  assert.strictEqual(bad.note, "out of memory");
+});
+
+t("activation round-trips and carries both hashes", () => {
+  const hidden = new Float32Array(16 * 32);
+  for (let i = 0; i < hidden.length; i++) hidden[i] = Math.cos(i) * 0.5;
+  const buf = Wire.packAct(7, 3, 2, hidden, Shard.hashF32, 0x5150);
+  const a = Wire.unpackAct(buf, Shard.hashF32);
+  assert.strictEqual(a.seq, 7);
+  assert.strictEqual(a.tokenIdx, 3);
+  assert.strictEqual(a.nextIndex, 2);
+  assert.strictEqual(a.modelHash, 0x5150);
+  assert.ok(bitsEqual(a.hidden, hidden), "hidden state changed on the wire");
+});
+
+// Corruption in an activation is the quietest failure in the whole system:
+// the next stage happily consumes any float array of the right length.
+t("a corrupted activation is caught by its hash", () => {
+  const hidden = new Float32Array(64).fill(1.5);
+  const buf = Wire.packAct(1, 0, 1, hidden, Shard.hashF32, 9);
+  new Float32Array(buf, 24)[10] = 1.5000001;              // one ulp, deep in the payload
+  assert.throws(() => Wire.unpackAct(buf, Shard.hashF32), /integrity hash/);
+});
+
+t("-0 in an activation survives, and is distinguished from +0", () => {
+  // The parent project learned this the hard way: `!==` says -0 === 0, but the
+  // hash sees the bits. An activation carrying -0 must arrive as -0, and a
+  // flip to +0 must not slip past the integrity check.
+  const hidden = new Float32Array(8);
+  hidden[3] = -0;
+  const buf = Wire.packAct(1, 0, 1, hidden, Shard.hashF32, 9);
+  const a = Wire.unpackAct(buf, Shard.hashF32);
+  assert.ok(Object.is(a.hidden[3], -0), "-0 did not survive the wire");
+  new Float32Array(buf, 24)[3] = 0;
+  assert.throws(() => Wire.unpackAct(buf, Shard.hashF32), /integrity hash/);
+});
+
+t("token and done round-trip", () => {
+  const tk = Wire.unpackToken(Wire.packToken(4, 1337, 42));
+  assert.deepStrictEqual([tk.seq, tk.id, tk.total], [4, 1337, 42]);
+  assert.strictEqual(Wire.tagOf(Wire.packDone(9)), Wire.DONE);
+});
+
+// ---- routing ---------------------------------------------------------------
+// These exist because of a real bug, and they are the shape of test that would
+// have caught it. The head is both stage 0 and the ring's terminus, so the
+// returning activation was addressed to index 0 and every stage read that as
+// "stage 0, run your blocks" — the head re-ran its own layers and forwarded
+// again, and the lap never closed. Every number involved was correct. Every
+// message round-tripped. The pipeline test could not see it because it calls
+// the stages in order itself, and the codec test could not see it because the
+// bytes were fine. The defect was in the ROUTE, so the check has to walk one.
+function walkLap(plan) {
+  // Simulate one lap: start at stage 0, follow routeAfter/classifyAct, and
+  // record who runs. Returns the sequence of stage indices that computed.
+  const ran = [];
+  let addr = 0, guard = 0;
+  for (;;) {
+    if (++guard > 100) throw new Error("lap did not terminate — the ring is cycling");
+    let actor = null;
+    for (const s of plan) if (Wire.classifyAct(addr, s.index) === "mine") {
+      if (actor !== null) throw new Error(`two stages both claim address ${addr}`);
+      actor = s.index;
+    }
+    if (actor === null) {
+      if (Wire.classifyAct(addr, 0) !== "return") throw new Error(`address ${addr} is claimed by nobody`);
+      return ran;                                   // lap closed at the head
+    }
+    ran.push(actor);
+    addr = Wire.routeAfter(plan, actor).address;
+  }
+}
+
+t("a lap visits every stage exactly once and terminates at the head", () => {
+  for (const n of [1, 2, 3, 5, 8]) {
+    const plan = Array.from({ length: n }, (_, i) => ({ id: "p" + i, index: i, lo: i, hi: i + 1, head: i === 0 }));
+    assert.deepStrictEqual(walkLap(plan), plan.map(s => s.index),
+      `a ${n}-stage ring did not visit each stage exactly once in order`);
+  }
+});
+
+t("the return leg is addressed differently from stage 0", () => {
+  const plan = [{ id: "p0", index: 0 }, { id: "p1", index: 1 }];
+  const last = Wire.routeAfter(plan, 1);
+  assert.strictEqual(last.to, "p0", "the last stage must hand back to the head");
+  assert.ok(last.isReturn, "the last hop must be flagged as the return leg");
+  assert.notStrictEqual(last.address, 0,
+    "the return leg is addressed as stage 0 — the head will re-run its own blocks and the lap will never close");
+  assert.strictEqual(Wire.classifyAct(last.address, 0), "return");
+  assert.strictEqual(Wire.classifyAct(0, 0), "mine");     // outbound, same number, different meaning
+});
+
+t("a single-stage ring returns to itself immediately", () => {
+  const solo = [{ id: "p0", index: 0 }];
+  const hop = Wire.routeAfter(solo, 0);
+  assert.ok(hop.isReturn && hop.to === "p0");
+  assert.deepStrictEqual(walkLap(solo), [0]);
+});
+
+t("every sentinel is distinct and cannot collide with a step number", () => {
+  const tags = [Wire.FRAG, Wire.HELLO, Wire.ASSIGN, Wire.READY, Wire.ACT, Wire.TOKEN, Wire.DONE];
+  assert.strictEqual(new Set(tags).size, tags.length, "two sentinels share a value");
+  for (const t2 of tags) assert.ok(t2 < 0, `sentinel ${t2} is not negative — it could be mistaken for data`);
+  // DaisyChain-Web uses -2..-8; ours start at -20 so a misdirected client sees
+  // an unknown tag rather than a valid message of the wrong kind.
+  for (const t2 of tags) assert.ok(t2 === Wire.FRAG || t2 <= -20, `sentinel ${t2} overlaps DaisyChain-Web's range`);
+});
+
+console.log(failed ? `\n${failed} failure(s)\n` : "\nall wire checks passed\n");
+process.exit(failed ? 1 : 0);