Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
46122cc
Pin drowse 6.1.3 and Ledger 0.1.5; the structured hook program carrie…
a9lim Nov 12, 2026
9333e07
Release tools read native 6.1 lens manifests and manifold folders, wh…
a9lim Nov 12, 2026
bc69ee9
The browser fit writes typed frames like drowse 6.1: Mahalanobis-orth…
a9lim Nov 12, 2026
0b86ea7
Steering lowers through typed frames: Mahalanobis Gram-Schmidt on wri…
a9lim Nov 12, 2026
0b85451
Merge parity-6.1/ns: typed steering, gains 8 and 2, raised lens atoms
a9lim Nov 12, 2026
7289e74
Archives read and write drowse 6.1's tolerant formats: readers requir…
a9lim Nov 12, 2026
ddf5466
Merge parity-6.1/nf: typed fit, tolerant formats
a9lim Nov 12, 2026
67f276f
Core-pack profiles stop stamping share_metric (drowse 6.1 has none); …
a9lim Nov 12, 2026
d977550
Hook ABI v6: affine groups and curves take read rows beside their wri…
a9lim Nov 12, 2026
96e0b61
browser-units-goldens gives its recorded pushes a read row, the dual …
a9lim Nov 12, 2026
f555bb6
Merge parity-6.1/k: hook ABI v6 (read rows in the kernels), bridge .50
a9lim Nov 12, 2026
7365d46
Prune the browser goldens drowse 6.1 deleted: golden-only tests and t…
a9lim Nov 12, 2026
43f7c4b
Merge parity-6.1/w1: the drowse browser goldens and the tests that re…
a9lim Nov 12, 2026
3db09a4
The fitting-worker e2e sends the covariance job its read rows (the fi…
a9lim Nov 12, 2026
d56fa03
Adopt the v6 runtime lock (nine hook ABI v6 libraries, their core-pub…
a9lim Nov 12, 2026
39e7672
Returning users upgrade cleanly across a runtime rebuild: a model ins…
a9lim Nov 12, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ webui/dist-local/
browser-runtime/.v3-compile.*/
browser-runtime/.local-build/
browser-runtime/vendor/*.tgz
!browser-runtime/vendor/drowse-web-llm-0.2.84-drowse.49.tgz
!browser-runtime/vendor/drowse-web-llm-0.2.84-drowse.50.tgz

# Virtual environments
.venv/
Expand Down
13 changes: 7 additions & 6 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,14 @@ alias for them.
A change that only touches shared code belongs in drowse, with its tests there.
Site tests that read shared files exist to check how the hosted shell uses them.

## Parity goldens
## Parity

`drowse/tests/fixtures/browser/*` are the Python reference outputs the browser
runtime replays (`browser-core-pack`, `structured-hook-parity`, the Rust
topology tests, `verify-mlc-hook.py`). drowse's own tests pin them against the
engine; regenerate them there, then bump the pin and update the runtime here.
Browser-only fixtures stay in `browser-runtime/fixtures/`.
There are no parity goldens. The browser runtime matches the engine by reading
the pinned drowse source; when a change moves numerics, check it once against the
pinned Python engine on a tiny model, in scratch, and commit nothing from that
comparison. Tests here check invariants and quiet-regression risks. Small input
data a test needs may live in `browser-runtime/fixtures/` or beside the code that
imports it; recorded engine outputs may not.

## Release

Expand Down
6 changes: 3 additions & 3 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,10 +50,10 @@ syntax, including projections, ablations, manifold positions, phase windows,
probe gates, SAE selectors, and J-lens selectors. Python and TypeScript consume
the same accept/reject fixture. Parsing does not imply execution support: each
expression is reduced to an explicit hook-feature requirement set before GPU
program compilation. The hook ABI v5 library profiles (`standard-v4` with unit
sites, `standard-v4-residual` without) implement structured affine and curved
program compilation. The hook ABI v6 library profiles (`standard-v5` with unit
sites, `standard-v5-residual` without) implement structured affine and curved
programs, exact geometry reads, precomputed SAE steering/readout, and exact
full-vocabulary J-lens steering/readout; `standard-v4` adds the neuron and head
full-vocabulary J-lens steering/readout; `standard-v5` adds the neuron and head
unit sites (`browser-runtime/HOOK_ABI.md`). The worker
still validates the library feature manifest, runtime identity, model profile,
and required instrument packs before every program is installed; unsupported
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ the browser.

| Path | What it holds |
| --- | --- |
| `drowse/` | Submodule pinned to [stdlogits/drowse](https://github.com/stdlogits/drowse): the shared dashboard source (`drowse/webui/src`), the Python reference implementation, and the parity goldens (`drowse/tests/fixtures/browser`) the browser runtime replays. |
| `drowse/` | Submodule pinned to [stdlogits/drowse](https://github.com/stdlogits/drowse): the shared dashboard source (`drowse/webui/src`) and the Python reference implementation the browser runtime follows. |
| `webui/` | The hosted shell (`hosted/`), site-only UI and runtime (`src/`), static assets (`public-hosted/`), build, release, and test scripts (`scripts/`), Playwright specs (`e2e/`), and the `/api/contact` Worker (`contact-worker/`). |
| `browser-runtime/` | The WebGPU runtime: WebLLM/MLC forks and compiler, the Rust/WASM fitting kernel, runtime and distribution locks, and release inputs. |
| `tests/` | Python tests for the browser-runtime build and validation tools. |
Expand Down
130 changes: 70 additions & 60 deletions browser-runtime/HOOK_ABI.md

Large diffs are not rendered by default.

78 changes: 31 additions & 47 deletions browser-runtime/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,12 @@ The hosted application must not infer with stock WebLLM. Production loading is
enabled only when `runtime-lock.json` has `status: "verified"` and the exact
package, overlay, toolchain, model, and compiled-library closure is pinned.

The runtime lock is hook ABI v5 (`runtime-lock.json` schema 2): `drowse-web-runtime-v2`,
`block-sites-v5`, `exact-readout-v2`, each model's capacity profile by architecture
(`standard-v4` for Gemma 3 and Qwen3, with the `blockSpec` its library's schema-4 descriptor
attests; `standard-v4-residual` for GPT-2, Pythia and Qwen3.5 base, with the `unitRefusal` its
unit calls answer), the WebLLM archive `0.2.84-drowse.49`, the fork manifest, compiler recipe
and LLVM identities. It stays `feasibility-required` until every v5 library's converted revision,
The runtime lock is hook ABI v6 (`runtime-lock.json` schema 2): `drowse-web-runtime-v3`,
`block-sites-v6`, `exact-readout-v2`, each model's capacity profile by architecture
(`standard-v5` for Gemma 3 and Qwen3, with the `blockSpec` its library's schema-4 descriptor
attests; `standard-v5-residual` for GPT-2, Pythia and Qwen3.5 base, with the `unitRefusal` its
unit calls answer), the WebLLM archive `0.2.84-drowse.50`, the fork manifest, compiler recipe
and LLVM identities. It stays `feasibility-required` until every v6 library's converted revision,
converted-manifest digest and library digest are filled (`prepare-hosted-candidate-lock.mjs`,
below); `check-runtime-lock.mjs` lists what is still pending. Exact converted-model
revisions, compiled libraries, package archive, overlay closure, runtime ABI, hook ABI,
Expand All @@ -18,10 +18,9 @@ contains only immutable packages that match those identities.

The browser core-pack compiler produces the required neutral whitener and seed
manifold pack for each release model. Every steering expression lowers to one
drowse-structured-v4 program (native's `synthesize_subspace` lowering, which
needs the neutral whitener); it shares Python goldens for Mahalanobis
normalization, mean-normalized per-layer share, and uncapped affine gain, and
lowers independent push/ablation groups, prior-step gates, response phases,
drowse-structured-v5 program (native's `synthesize_subspace` lowering, which
needs the neutral whitener); it follows native's Mahalanobis normalization,
mean-normalized per-layer share and uncapped affine gain, and lowers independent push/ablation groups, prior-step gates, response phases,
SAE and R-lens programs, box/custom/sphere curved manifolds, in-block unit
ablation, and exact geometry reads.
Curved steering retains its separate safety cap. Every published pack passes the
Expand All @@ -34,15 +33,15 @@ response/prompt/count/thinking phases, prior-step scalar gates, and up to four
curved terms per layer. Curves may use bounded, unbounded, periodic, or spherical
domains and may have up to four intrinsic dimensions. Curved steering can itself
be phase-gated or controlled by a prior SAE, R-lens probability, scalar affine
probe, or exact geometry channel from the preceding token. Every hook ABI v5 library
(`HOOK_ABI.md` is the contract) runs `drowse-structured-v4`: four independently gated affine
probe, or exact geometry channel from the preceding token. Every hook ABI v6 library
(`HOOK_ABI.md` is the contract) runs `drowse-structured-v5`: four independently gated affine
groups, rank eight, eight scalar probes, four curves, thirty-two nodes per curve, four intrinsic
dimensions and eight embedded dimensions, eight geometry probes, whitener rank 96,
thirty-three candidates per probe, a 41-float output record per layer and geometry probe, and
`exact-readout-v2` (lens reads at both sites, top-k ≤ 256, the S footprint, unit static-read
primitives). A `standard-v4` library adds the in-block unit sites (neuron and head mean-ablation,
primitives). A `standard-v5` library adds the in-block unit sites (neuron and head mean-ablation,
unit taps, the replay for token anatomy, unit activity and attention patterns, static unit
reads); a `standard-v4-residual` library attests their absence and answers unit calls with the
reads); a `standard-v5-residual` library attests their absence and answers unit calls with the
lock's refusal.

The v3 geometry path produces domain coordinates, subspace fraction,
Expand Down Expand Up @@ -195,7 +194,7 @@ npm run publish:hosted:pack -- MODEL_ID core|sae|jlens|slens|units PACK_DIR

The production-q4 comparator checks the unsteered residuals of every layer and
position against the dequantized Transformers model, then the steered read on
hook ABI v5 (capture schema 4): one drowse-structured-v4 program with linear
hook ABI v6 (capture schema 4): one drowse-structured-v5 program with linear
probes on a fixed orthonormal sketch at every layer (the first direction the
push of a rank-1 affine group at the middle layer), measured at every captured
position with and without the group (`measurePreparedPositions`). Probe error
Expand All @@ -206,13 +205,7 @@ control probes to reproduce the projection of the plain capture, rejects any
pre-enabled-layer delta between the control and steered probes, and compares
the steering delta's direction in the sketch.

`webui/scripts/browser-core-build.mjs` runs the core builder (the unchanged
`hosted-whitener.worker.ts`), the plain and measured captures and the
injection-arithmetic oracle on B4's tiny v5 fixture libraries:
`node scripts/browser-core-build.mjs --webllm WEB_LLM.js --fixtures DIR
--arch qwen3|gemma3 --quantization q0f32|q4f32_1 --work SCRATCH`.

Capture schema 5 adds B1 §4.3's production measures for a units (`standard-v4`) library and
Capture schema 5 adds B1 §4.3's production measures for a units (`standard-v5`) library and
refuses them for a residual one (`q4_unit_parity.py`). Its `capture.json` carries
`units: {block: {d_ff, n_heads, head_dim}, sites_sha256, static_reads}`:

Expand All @@ -230,7 +223,7 @@ refuses them for a residual one (`q4_unit_parity.py`). Its `capture.json` carrie
scales come from the units pack and divide both sides alike).

The repository lock carries every value a compile does not produce; each library-bound field
stays null until a hook ABI v5 library fills it. `prepare-hosted-candidate-lock.mjs` fills one
stays null until a hook ABI v6 library fills it. `prepare-hosted-candidate-lock.mjs` fills one
model from its assembled publish directory and chains models into one candidate lock:

```bash
Expand Down Expand Up @@ -402,9 +395,7 @@ so a rebind takes seconds.
and the neutral pass every statistic averages over, with the digest of its rows (the
write norms' whitener, and the core pack's, are built from them). `build_hosted_packs.py`
refuses a layer without `neurons.write_norms`. Rank-3 tensors are stored
`[prod(shape[:-1]), shape[-1]]` with their logical shapes recorded. On the ABI v5 tiny
fixture every shipped units tensor equals the `unit-artifacts` golden on both
architectures (`tests/test_hosted_packs.py`).
`[prod(shape[:-1]), shape[-1]]` with their logical shapes recorded.
- **core statistics**: `core/neutral-statistics.*` (unit statistics, `out` and `mid`
means, stacked over layers) and `core/neutral-rows.safetensors` (the neutral pass's
rows, a build input that does not ship), added to the core pack by the whitener
Expand Down Expand Up @@ -459,8 +450,8 @@ npm run test:browser-runtime:full -- \
--output /tmp/drowse-real-browser-e2e.json
```

The packs follow the library's profile, as the catalog admits them: a `standard-v4` model
runs with its R (`--jlens-directory`), S and units packs, a `standard-v4-residual` one with no
The packs follow the library's profile, as the catalog admits them: a `standard-v5` model
runs with its R (`--jlens-directory`), S and units packs, a `standard-v5-residual` one with no
S or units pack (an R pack is optional); SAE is optional on both. The harness stages every
pack file and hands the runtime what the app's worker does: the install files, and each
on-demand lens or units layer through `fetchFile` on its first read. `--runtime-lock CANDIDATE`
Expand All @@ -475,11 +466,11 @@ post-block capture, exact forced-token replay and compact cross-token scoring,
an alternate-token fork, flat steering gated independently by geometry and, with their packs,
R-lens probability and SAE activation signals, R-lens and SAE steering/readout,
a small spectral fit backed by the OPFS activation spool, nearest-node role
selection and named-role generation, curved steering, then on `standard-v4` the units
selection and named-role generation, curved steering, then on `standard-v5` the units
check (a token-anatomy replay of the first generated token; a mean-ablation of its largest
contributor that moves that token's logprob by at least 1e-4; a static read of a contributing
neuron; a generation with a unit tap and an `slens/` S readout, both finite) or on
`standard-v4-residual` the refusal check (six unit members answer 422 with the lock's
`standard-v5-residual` the refusal check (six unit members answer 422 with the lock's
`unitRefusal`, the unit catalog answers unbound, a unit ablation and a unit probe refuse, and
the bridge's unit surface answers `UNIT_SITES_UNAVAILABLE`), streamed stop, unload/reload,
and a final reload from reopened OPFS files while all HTTP(S) fetches are blocked. It fails
Expand Down Expand Up @@ -534,21 +525,17 @@ SKIP_LOADING_MLCLLM_SO=1 \
PYTHONPATH=/path/to/tvm/python:/path/to/mlc-llm/python \
/path/to/venv/bin/python browser-runtime/forks/verify-mlc-hook.py \
--mlc-repository /path/to/mlc-llm \
--tvm-repository /path/to/tvm [--units-fixtures FIXTURES]
--tvm-repository /path/to/tvm
```

Without `--units-fixtures` it checks the Qwen3, Llama and Gemma 3 graph exports and runs the
structured, geometry, curved and exact-readout goldens through a compiled C TVM VM. With it, it
runs drowse's units, replay and read goldens (`drowse/tests/fixtures/browser/*`) over the four
fixture libraries `forks/build-units-fixtures.py` makes from drowse's checkpoints (Qwen3 and
Gemma 3 at q0f32 and q4f32_1). `webui/scripts/browser-units-goldens.mjs` runs the same goldens
through the vendored WebLLM bridge on WebGPU. Neither proves a production library, q4 parity or
a physical device; those are the per-library records below.
It checks the Qwen3, Llama and Gemma 3 graph exports and runs hand-built structured, geometry,
curved and exact-readout cases through a compiled C TVM VM. It does not prove a production
library, q4 parity or a physical device; those are the per-library checks below.

For the WebGPU compile gate, source exact Emscripten 3.1.56, rebuild both support runtimes
against the pinned TVM checkout (`make -C mlc-llm/web`, `TVM_HOME=… make -C tvm/web`), and
compile each architecture fixture with `forks/compile-tiny-webgpu.py --architecture
qwen3|llama|gemma3_text` (or `--model-config` for a units fixture). The compiler requires a new
qwen3|llama|gemma3_text`. The compiler requires a new
output path, validates the WebAssembly with the matching Binaryen tool, and requires the v5
export set for its architecture (`overlay_checks.py`: `REQUIRED_FUNCTIONS`, plus
`UNIT_FUNCTIONS` on Qwen3 and Gemma 3, none on Llama) and the shader checks.
Expand Down Expand Up @@ -578,18 +565,15 @@ authorizes catalog downloads.
Each browser runtime generation reads its catalog at its own path of
`stdlogits/drowse-web-catalog` (`webui/scripts/hosted-catalog-location.mjs`): runtime v1
builds read the root `catalog.json` (sequences up to 10), runtime v2 builds (hook ABI v5)
`v2/catalog.json` and `v2/catalog.sig.json` (from 11), which the lock names and
`check-runtime-lock.mjs` requires. Publishing a catalog for the new runtime therefore never
`v2/catalog.json` (11), runtime v3 builds (hook ABI v6) `v3/catalog.json` and
`v3/catalog.sig.json` (from 12), which the lock names and `check-runtime-lock.mjs` requires. Publishing a catalog for the new runtime therefore never
changes what the deployed site reads, and builds of the previous runtime keep working until
the new one is deployed.

## Release

1. Compile the libraries with the overlay (`compiler/README.md`) and assemble each
(`assemble:hosted:model`). When the overlay, the bridge or the drowse goldens change, run the
fixture goldens: `browser-runtime/record-cvm-goldens.py` on the C TVM VM and
`webui/scripts/browser-units-goldens.mjs --report` on WebGPU (run it with
`--webllm node_modules/@drowse/web-llm/lib/index.js`). They are checks, not records.
(`assemble:hosted:model`).
2. Fill a candidate lock from the assembled directories (`prepare:hosted:candidate-lock`, one model
at a time with `--base`), rebind the packs and build each core pack against it.
3. Publish each model's files and core pack (`publish:hosted:model`, `publish:hosted:pack ... core`),
Expand Down Expand Up @@ -620,8 +604,8 @@ accepts an Ed25519 PKCS#8 PEM key path and signs the exact `catalog.json` bytes.
The publisher writes to the directory the lock's URLs name and verifies the catalog published
there against the lock's keys before it advances the sequence. The first catalog at a new
directory has nothing there to advance, so the publisher verifies the previous directory's
catalog instead (the one deployed builds still read) and requires a greater sequence: catalog 11
at `v2/` must verify the root's catalog 10 and exceed it. A new directory whose predecessor has
catalog instead (the one deployed builds still read) and requires a greater sequence: catalog 12
at `v3/` must verify `v2/`'s catalog 11 and exceed it. A new directory whose predecessor has
nothing published is refused; only the root may start without one. `./deploy.sh`
checks the signed catalog at the lock's URL before every upload (`preflight-hosted-distribution.mjs`),
so a build never ships pointing at an unpublished path. A rotation that cannot sign with the outgoing
Expand Down
5 changes: 2 additions & 3 deletions browser-runtime/build_hosted_packs.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@
The packs bind the runtime identity they are built for (``--runtime-identity``,
written by ``webui/scripts/hosted-runtime-identity.mjs``) and, for units, the
identities of the lens packs and statistics they average over. Lens shards are
the native files byte for byte, so a pack shard's digest is the native manifest's.
the native files byte for byte; the pack manifest records each shard's digest
(native lens manifests no longer carry one).
Output goes to a staging directory; ``build-hosted-packs.sh`` assembles and
validates it. Nothing is published from here.
"""
Expand Down Expand Up @@ -288,8 +289,6 @@ def build_lens_pack(
name = f"{site}.layer-{layer}.safetensors"
shutil.copyfile(source, pack / name)
digest = sha256_file(pack / name)
if digest != native["tensor_sha256"][str(layer)]:
raise PackBuildError(f"{source} does not match its manifest digest")
files[str(layer)] = name
digests[str(layer)] = digest
sites[site] = {"layers": layers, "tensor_files": files, "tensor_sha256": digests}
Expand Down
Loading
Loading