Upload folder using huggingface_hub (part 2)

environment/training-source/source-snapshot/Cargo.toml

@@ -0,0 +1,74 @@
+[package]
+name = "dinovision"
+version = "0.1.0"
+edition = "2024"
+
+[workspace]
+members = ["android", "android-xr"]
+
+[dependencies]
+# Pinned to the exact blade-graphics revision meganeura depends on. Both
+# crates must resolve to the *same* blade-graphics so the
+# `Arc<blade_graphics::Context>` we create for rendering is the same type
+# meganeura's `SessionConfig::gpu` accepts. Bump both together.
+blade-graphics = { version = "0.8.4", git = "https://github.com/kvark/blade", rev = "ba0fb5a6f2b5462c3e5796f8ce06b3b3d580adac" }
+meganeura = { version = "0.2", default-features = false }
+bytemuck = { version = "1", features = ["derive"] }
+blade-macros = "0.3"
+half = "2"
+log = "0.4"
+
+# Desktop screen capture. Optional so the Android crate never sees it —
+# it drags in a windowing stack that has no business on a headset.
+xcap = { version = "0.9", optional = true }
+
+[dev-dependencies]
+env_logger = "0.11"
+image = { version = "0.25", default-features = false, features = ["png", "jpeg"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+sha2 = "0.10"
+
+# The viewer's windowing, kept off Android: winit drags in android-activity,
+# which then fails to build for aarch64-linux-android when no backend
+# feature is selected — and it has no business there anyway, since the
+# on-device benchmark is a plain native binary and the XR app has its own
+# activity.
+[target.'cfg(not(target_os = "android"))'.dev-dependencies]
+winit = "0.30"
+
+[features]
+default = []
+# Desktop-only: lets the tools fetch weights straight from the Hub. The
+# on-device crate never enables it.
+hub = ["meganeura/hub"]
+# Live screen capture as a `source::FrameSource`.
+capture = ["dep:xcap"]
+
+# Tools live in examples/ rather than src/bin/ so they can use
+# dev-dependencies, matching meganeura's own layout.
+[[example]]
+name = "bench"
+path = "examples/bench.rs"
+
+[[example]]
+name = "verify"
+path = "examples/verify.rs"
+
+# Local checkout: the Android build fix (hf-hub behind a feature,
+# tokenizers moved to dev-dependencies) is not upstream yet.
+[patch.crates-io]
+meganeura = { path = "../meganeura" }
+
+[[example]]
+name = "preview"
+path = "examples/preview.rs"
+
+[[example]]
+name = "viewer"
+path = "examples/viewer.rs"
+required-features = ["capture"]
+
+[[example]]
+name = "train_decoder"
+path = "examples/train_decoder.rs"

environment/training-source/source-snapshot/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dzmitry Malyshau
+
+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.

environment/training-source/source-snapshot/README.md

@@ -0,0 +1,363 @@
+# dinovision
+
+DINOv3 inference on Meta Quest, using [Blade](https://github.com/kvark/blade)
+for graphics and [Meganeura](https://github.com/kvark/meganeura) for the
+network. The camera image is encoded to DINOv3 patch features and those
+features are turned back into something viewable, so the wearer sees the
+world through a DINO roundtrip.
+
+Status: **the full stereo passthrough roundtrip is implemented.** The corrected
+encoder and Meganeura-trained decoder pass host validation; fresh Quest
+correctness and timing runs are tracked in `REPORT.md`. No historical device
+number in Git history is paper evidence unless that report explicitly admits
+it into the frozen artifact.
+
+**Meganeura does both halves.** The encoder is Meganeura inference; the
+decoder was *trained* in Meganeura too — its autodiff builds the backward
+pass (47 forward nodes → 122 with backward), its Adam runs the updates, and
+`session.step()` does forward, backward, and optimizer in one GPU
+submission. PyTorch is not used to train or export the decoder; it appears
+only in the independent Hugging Face numerical-reference check.
+
+The test-pattern fallback remains available when camera permission or hardware
+is absent, but it is not evidence for the passthrough result.
+
+## Layout
+
+| Path | What |
+|---|---|
+| `src/dinov3.rs` | The encoder as a meganeura graph, plus config and RoPE tables |
+| `src/preprocess.rs` | Image → patch tensor, in the order the folded patch-embedding matmul needs |
+| `src/weights.rs` | Binding a HuggingFace checkpoint to graph parameters |
+| `src/pca.rs` | Features → RGB: on-device PCA fit, folded into the graph as one matmul |
+| `src/inference.rs` | The worker thread that owns the session and publishes feature grids |
+| `src/render.rs` | Full-screen view of the coloured grid |
+| `src/source.rs` | Where frames come from: test pattern, screen capture, and the seam the Quest camera slots into |
+| `src/bench.rs` | Throughput measurement, shared by desktop and device |
+| `examples/viewer.rs` | Live windowed viewer over screen capture |
+| `examples/preview.rs` | Runs the whole pipeline on desktop and writes a PNG |
+| `examples/bench.rs` | Desktop benchmark runner |
+| `examples/verify.rs` | Numerics comparison against the HuggingFace reference |
+| `android/` | The headless benchmark APK |
+| `android-xr/` | The XR application |
+| `tools/dump_reference.py` | Produces the reference dump `verify` consumes |
+
+## Running
+
+**Live, in a window, no headset needed.** Screen capture through the same
+pipeline the headset runs:
+
+```sh
+cargo run --release --features capture --example viewer -- [model.safetensors] [monitor]
+```
+
+`R` refits the colour basis (worth doing after pointing it at something
+new), `Esc` quits. The window title reports display and inference rates.
+
+This is the demo, and it is also how the passthrough-camera work gets
+de-risked: capture loop, downscale, and asynchronous-frame structure are all
+identical, so the Quest camera becomes one more `source::FrameSource` with
+nothing around it changing.
+
+Run the whole pipeline on desktop and look at the result — inference
+worker, PCA fit, colour projection, everything but OpenXR:
+
+```sh
+cargo run --release --example preview -- preview.png [model.safetensors]
+```
+
+Without a checkpoint it uses synthetic weights. The colours are then
+meaningless, but the *structure* is not: a ViT with random weights still
+preserves patch identity, so the scene's layout must still show through. If
+it comes out scrambled, patch extraction or token ordering is broken.
+
+Desktop benchmark:
+
+```sh
+cargo run --release --example bench -- 20
+```
+
+Weights. Accept Meta's DINOv3 License on the canonical gated repository, then
+download the exact upstream checkpoint:
+
+```sh
+hf download facebook/dinov3-vits16-pretrain-lvd1689m model.safetensors \
+  --local-dir ref/
+```
+
+The paper artifact records SHA-256
+`4610ad75edef83e75afdebf162d148dc628045ea6cbb83d67d4708c709c4f91d`.
+
+Semantic check — that the features actually separate content:
+
+```sh
+DINOVISION_WEIGHTS=model.safetensors cargo test --release --test semantics -- --nocapture
+```
+
+On a scene of four flat regions, every same-material patch pair must score
+closer than every different-material pair (measured: worst within 0.984,
+best across 0.959). This catches more than a numerical diff would: a
+transposed projection, a mis-paired RoPE half, or a patch flattening in the
+wrong channel order all leave magnitudes healthy while collapsing that
+margin — and it needs no torch on the machine.
+
+A strict numerical comparison against HuggingFace is also available, if you
+have `torch`/`transformers`:
+
+```sh
+python tools/dump_reference.py --out ref/
+cargo run --release --example verify -- ref/
+```
+
+On device. Needs `cargo-apk`, the `aarch64-linux-android` target, and
+`ANDROID_HOME` / `ANDROID_NDK_HOME` set.
+
+**Benchmarking: skip the APK.** Vulkan compute works from a plain adb shell
+binary — no activity, no window, no compositor, and the headset does not
+even need to be awake. This is much faster to iterate on than an APK, and it
+measures compute without the window system anywhere near it:
+
+```sh
+cargo build --release --target aarch64-linux-android --example bench
+adb shell mkdir -p /data/local/tmp/dinovision
+adb push target/aarch64-linux-android/release/examples/bench /data/local/tmp/dinovision/
+adb shell "cd /data/local/tmp/dinovision && chmod 755 bench && RUST_LOG=info ./bench 5"
+```
+
+(On Git Bash, prefix with `MSYS_NO_PATHCONV=1` or `/data/...` gets rewritten
+to `C:/data/...`.)
+
+The `android/` benchmark APK exists but is the wrong shape for Horizon OS —
+see the note below.
+
+The XR application:
+
+```sh
+# Optional: real weights, and a writable directory for the plan cache.
+adb shell mkdir -p /data/local/tmp/dinovision
+adb push ref/model.safetensors /data/local/tmp/dinovision/
+
+cargo apk run --manifest-path android-xr/Cargo.toml --release --no-logcat
+adb logcat -v time | grep -E "dinovision|RustStdoutStderr"
+```
+
+It falls back to synthetic weights if the checkpoint is absent, and logs
+render and inference rates separately every five seconds.
+
+**The headset must be worn**, and awake is not enough. `adb shell am start`
+silently caches the launch instead of running it:
+
+```text
+Launch is blocked because: a Reprojected OS dialog is currently showing
+```
+
+That message is misleading. Check what is actually on top:
+
+```sh
+adb shell dumpsys activity activities | grep topResumedActivity
+```
+
+`com.oculus.os.vrlockscreen/.SensorLockActivity` means the proximity sensor
+has locked the headset because nobody is wearing it. `mWakefulness=Awake`
+does not help, `wm dismiss-keyguard` does nothing, and there is no adb-side
+override — only putting the headset on clears it. With `mWakefulness=Asleep`
+the OpenXR session additionally never reaches `READY`.
+
+Two Horizon OS behaviours worth knowing, both learned the hard way:
+
+* A plain 2D activity that never creates a surface — a headless compute
+  benchmark, say — is killed by the volumetric window manager with
+  `Timeout while requesting window placement`. Use the native binary above
+  instead.
+* Without a hand-tracking declaration, launches are blocked behind
+  `LaunchCheckControllerRequiredDialogActivity` when no controllers are on.
+  `android-xr/Cargo.toml` declares `oculus.software.handtracking` as
+  optional to avoid it.
+
+## Architecture notes
+
+### One shared GPU context
+
+The renderer and the network run on a **single**
+`blade_graphics::Context`, created by `dinovision::init_context` and handed
+to meganeura through `SessionConfig::gpu`. No external-memory interop is
+involved: `Session::input_buffer` returns a `BufferPiece` that a render pass
+can write to directly, and both sides share one device and queue.
+
+This is why the root `Cargo.toml` pins the *exact* blade-graphics revision
+meganeura depends on. Two resolved copies of the crate would make the
+`Arc<Context>` types incompatible, and the error would be a confusing type
+mismatch rather than anything about versions. **Bump both together.**
+
+### Threading, and the constraint that shapes it
+
+The renderer runs free at the headset's refresh rate, always drawing the
+most recent completed grid; inference runs on a worker thread and lands
+whenever it lands. The display loop never waits synchronously for a model
+result.
+
+`blade_graphics::Context` is `Send + Sync`, so an `Arc<Context>` can be
+shared. `meganeura::Session` is **not** `Send`, so the worker receives the
+context and builds its session *in place* rather than being handed one.
+`tests/threading.rs` pins this down.
+
+The reason is narrower than it first appears, and fixable: the only
+non-`Send` field anywhere in the chain is `ScratchBuffer::mapped`, a raw
+pointer into a persistently mapped allocation. `Buffer` carries the same
+kind of pointer and has `unsafe impl Send`/`Sync` already. Command buffers
+are not thread-affine in Vulkan — the spec asks only that a command pool be
+externally synchronized, which `&mut CommandEncoder` guarantees. A one-line
+`unsafe impl Send for ScratchBuffer` in blade makes `Session` `Send`
+(verified); the branch `command-encoder-send` carries it. The worker does
+not need it, so it is not pulled in here.
+
+Threading decouples CPU orchestration, not GPU occupancy: both threads submit
+to the same Vulkan queue, so a long compute submission can still delay a
+render submission behind it. The audited live-worn sweep measures that
+co-tenancy effect with each eye counted separately; pre-audit rates are not
+retained here.
+
+The fix is now in meganeura: `Session::set_submission_chunks` spreads the
+plan over several submissions so the renderer can interleave. The app
+defaults to 12, roughly one per transformer layer.
+
+That boundary needs no extra synchronization, which is the whole risk of
+the change and worth stating explicitly: blade closes every command buffer
+with a conservative global memory barrier, opens each new one assuming an
+unknown prior producer, and a Vulkan pipeline barrier's scopes cover
+commands submitted to the same queue *before and after* it — not merely
+those in one command buffer. `meganeura/tests/submission_chunks.rs` checks
+a deep dependent chain over several steps and requires chunked output to
+match the single-submission result **exactly**, at 2, 3, 5, and 16 chunks.
+The isolated benchmark reports the throughput cost beside the live sweep.
+
+### The roundtrip
+
+`src/decoder.rs` reconstructs RGB from patch features — the thing the
+project is named for. A plain convolutional upsampler, four ×2 stages from
+`[384, 14, 14]` to `[3, 224, 224]`, about 1.3M parameters and ~0.9 GMAC, so
+roughly a fifth of the encoder. No skip connections and nothing clever on
+purpose: the question is what the *features* carry, and a decoder with its
+own path to the input would answer a different one.
+
+```sh
+cargo run --release --example train_decoder -- \
+  <dataset-dir-or-manifest> <model.safetensors> \
+  [steps] [images] [layers] [size] [seed] [output-dir]
+cargo run --release --features capture --example viewer -- model.safetensors decoder.bin
+```
+
+**The training is Meganeura's own**, which is half the point of the
+exercise: `train::build` with `Mode::Training` runs the autodiff that turns
+47 forward nodes into a 122-node forward-plus-backward graph, `set_adam`
+drives the optimizer, and each `session.step()` is forward, backward, and
+parameter update in one submission. The same runtime that serves the model
+on a headset trained the model on a desktop.
+
+Training precomputes features once per image rather than re-encoding every
+step — the encoder is frozen, so running it in the loop would cost ~30× the
+decoder's forward pass for no gradient — and caches targets as u8, because
+as f32 they are 900 KB an image and a few thousand no longer fit in RAM.
+
+Expect softness. 14×14×384 is only about 2× the raw pixel count, and DINOv3
+features are trained for semantic invariance, which means colour and texture
+detail are discarded *by design*. Layout and dominant colour come back well;
+fine detail does not. That is the result, not a defect in the decoder.
+
+### Features to pixels
+
+The first display mode is the classic DINO visualization: project patch
+features onto their top three principal components and read those off as
+RGB. No trained decoder, one `[hidden, 3]` matmul, and semantically
+meaningful — patches of the same object land on the same colour.
+
+The basis is fitted **on device** from a captured frame rather than shipped
+as an asset, because feature statistics depend on what the camera is looking
+at. It is folded into the graph as a parameter, so the per-frame readback is
+`tokens × 3` floats (~3 KB) instead of `tokens × 384` (~300 KB), and
+refitting is a `set_parameter` call rather than a graph rebuild.
+
+One case worth knowing about: when a component carries almost no variance —
+a blank wall — normalizing it to full range would amplify numerical noise
+into a psychedelic channel. Such components are mapped to flat mid-grey
+instead.
+
+### Why the graph is hand-built
+
+`meganeura::load_onnx` recognizes `Add`, `Gemm`, `MatMul`, and `Relu` — not
+close to enough for a ViT. Every op DINOv3 needs already exists in the IR,
+so `src/dinov3.rs` transcribes
+`transformers/models/dinov3_vit/modeling_dinov3_vit.py` directly, following
+the pattern of meganeura's own `src/models/`.
+
+### The three things that make DINOv3 not a plain ViT
+
+1. **No learned position embedding.** Position enters only as 2D axial RoPE
+   on Q and K inside every layer. The `pos_embed_rescale` in the config is
+   applied under `if self.training` in the reference, so inference ignores
+   it.
+2. **Prefix tokens.** A CLS token and 4 register tokens precede the patch
+   tokens, and RoPE deliberately skips them. Rather than split the token
+   dimension in the graph, the RoPE tables carry `(cos, sin) = (1, 0)` on
+   prefix rows, making the rotation an identity there.
+3. **LayerScale.** Each residual branch is scaled by a learned hidden-channel
+   vector. Meganeura's broadcast operator is NCHW-flat, so the token-major
+   matrix is transposed to hidden-major layout before `mul_per_channel` and
+   transposed back afterward. Exact-shape tests pin this convention.
+
+Two conventions differ from the checkpoint and are fixed up in
+`src/weights.rs`: `nn.Linear` stores `[out, in]` where meganeura's `matmul`
+wants `[in, out]`, and the patch embedding is a 4D conv weight that gets
+flattened and transposed. The checkpoint's `k_proj` genuinely has no bias
+(`key_bias: false`).
+
+Patch flattening order is **channel-major** (`c * patch_size² + ky *
+patch_size + kx`) because that is how PyTorch's `[out, 3, k, k]` conv weight
+flattens. Getting it wrong still runs and produces confident nonsense, so
+`src/preprocess.rs` pins it with tests.
+
+## Evidence status
+
+The original exploratory measurements are intentionally removed from this
+README. An audit found that the encoder misapplied LayerScale after the first
+token; the old decoder weights, reconstruction scores, and device timings are
+therefore invalid. The corrected 1-, 3-, and 12-layer graphs pass an
+independent Transformers comparison under predeclared numerical thresholds.
+
+See [REPORT.md](REPORT.md) for the paper-facing case study,
+[experiments/AUDIT.md](experiments/AUDIT.md) for rejected evidence, and
+[experiments/README.md](experiments/README.md) for the frozen protocol. Only
+machine-readable results produced after the LayerScale correction are
+admissible.
+
+## Local dependency revisions
+
+The workspace uses the sibling `../meganeura` checkout. Its Android branch
+makes host-only Hub/tokenizer dependencies optional, adds Android
+cross-compilation support, and exposes chunked plan submission so Blade
+rendering can interleave with inference on a shared Vulkan queue. Artifact
+metadata records both that checkout's full revision and the Blade revision
+actually resolved by Cargo; the neighboring Blade working tree is not assumed
+to be the selected dependency.
+
+These revisions must be frozen as clean commits before a paper artifact cites
+them. Until then, `tools/collect_artifact_metadata.ps1` stores the dirty-tree
+patch and hashes every tracked or untracked, non-ignored source file.
+
+## Android toolchain
+
+The camera path requires Android API 34 symbols and NDK r27. Paper builds set
+both `ANDROID_NDK_ROOT` and the Android target linker to
+`27.0.12077973`; NDK r23 is insufficient for the vendor-tag camera API.
+
+## Remaining paper run
+
+1. Complete three corrected decoder initializations on the frozen Imagenette
+   manifest and aggregate all 3,925 validation images per seed.
+2. Compare one fixed public frame across the RTX host and Quest before
+   admitting device timing.
+3. Run the isolated multi-process benchmark and live-worn chunk sweep with raw
+   samples and device-state snapshots.
+4. Freeze source revisions and publish the corrected decoder artifacts and
+   audit records without the gated encoder, Imagenette images, or private
+   headset captures.

environment/training-source/source-snapshot/REPORT.md

@@ -0,0 +1,228 @@
+# DinoVision: host training and Android XR deployment with Meganeura
+
+## Merge recommendation
+
+**Status: not yet ready to merge into the Meganeura paper.** The experiment
+now has a defensible claim and an audited protocol, and the corrected DINOv3
+encoder agrees with an independent Transformers implementation. Corrected
+decoder replicates and fresh Quest measurements are still in progress. No
+historical quality or device-performance number from the previous version of
+this report should be cited.
+
+The experiment is best used as a deployment case study, complementary to a
+matched framework benchmark:
+
+> Meganeura trains an image decoder through its graph autodiff and Adam path
+> on an NVIDIA host, then compiles the decoder's forward path, joined to a
+> frozen DINOv3 encoder, through the same graph compiler and Vulkan runtime in
+> an Android XR application sharing Blade's graphics context and queue.
+
+This demonstrates a useful span of the stack: transformer inference,
+convolutional decoder training, parameter serialization, Android
+cross-compilation, and compute/graphics co-tenancy. It does not establish
+performance portability relative to PyTorch, capture-to-photon latency,
+zero-copy camera integration, or a general image-generation result.
+
+## 1. System boundary
+
+DinoVision converts each passthrough frame to a 224 by 224 RGB image, runs the
+first three layers of DINOv3 ViT-S/16, decodes the 14 by 14 patch-feature grid
+back to RGB, and displays the reconstruction in both eyes.
+
+| Component | Training host | Android XR device |
+|---|---|---|
+| DINOv3 encoder | Frozen; run once per corpus image to cache features | Joined to the decoder in one inference graph |
+| RGB decoder | Meganeura training graph, batch 8, autodiff and Adam | Same decoder builder and parameters, forward only, batch 1 |
+| Compiler/runtime | Meganeura graph compiler and Vulkan runtime | Meganeura graph compiler and Vulkan runtime |
+| GPU integration | Dedicated compute context | Blade graphics context and Vulkan queue shared with rendering |
+
+The wording “same graph” would be too strong. Training caches frozen encoder
+features and optimizes a decoder-only batch graph. Deployment builds a
+batch-one joined encoder/decoder graph. The decoder construction, learned
+parameters, IR operators, compiler, and runtime are shared across the two
+paths.
+
+The frozen encoder is the gated
+`facebook/dinov3-vits16-pretrain-lvd1689m` checkpoint (SHA-256
+`4610ad75edef83e75afdebf162d148dc628045ea6cbb83d67d4708c709c4f91d`).
+At 224 pixels it produces 196 patch tokens plus one CLS and four register
+tokens, each 384-dimensional. Only patch tokens enter the decoder.
+
+The decoder has 2,012,547 trainable parameters. Four stages successively
+upsample 14 to 28, 56, 112, and 224 pixels while reducing channels from 384
+through 256, 128, 64, and 32. Each stage uses a 3 by 3 convolution, group
+normalization, SiLU, and 2x upsampling; the first two stages include a second
+blend convolution. A final 3 by 3 convolution and sigmoid produce RGB. Its
+forward pass is 1.142 GMAC at 224 pixels.
+
+## 2. Correctness gate
+
+The first audit run found that the previous application was not executing the
+intended transformer. DinoVision passed a `[tokens, hidden]` matrix to
+Meganeura's NCHW-flat `mul_per_channel` operator as if it broadcast over the
+trailing hidden dimension. Consequently, only the first token received the
+intended learned LayerScale update; residual branches for later tokens were
+effectively suppressed. Visually plausible reconstructions and a semantic
+smoke test did not expose this error.
+
+The corrected graph transposes each residual branch to `[hidden, tokens]`,
+flattens it for the NCHW operator, applies the learned hidden-coordinate gain
+with all tokens as the spatial extent, reshapes, and transposes back. Exact
+shape tests compare both attention and this LayerScale path against CPU
+implementations.
+
+An independent reference run uses Torch 2.13.0+cpu and Transformers 5.14.1.
+Both implementations consume the same normalized f32 pixel tensor and exact
+checkpoint. The acceptance thresholds were relative output L2 at most 0.01,
+CLS cosine above 0.999, and every patch-token cosine above 0.999.
+
+| Encoder depth | Relative L2 | CLS cosine | Worst patch cosine | Result |
+|---:|---:|---:|---:|---|
+| 1 layer | 0.000781 | 1.000000 | 0.999990 | pass |
+| 3 layers (deployed) | 0.001403 | 1.000000 | 0.999995 | pass |
+| 12 layers | 0.002253 | 0.999997 | 0.999996 | pass |
+
+At the first layer, embeddings, LayerNorm, Q/K/V projections, and RoPE match
+to the displayed six decimal places. The attention output differs by 0.005852
+relative L2; learned LayerScale reduces the attention-residual difference to
+0.000566. The final three-layer error is comfortably inside the declared
+threshold.
+
+All decoder weights and device measurements produced before this correction
+are invalid. They are excluded rather than “corrected” by reinterpretation.
+
+## 3. Host training and held-out reconstruction
+
+The corrected experiment uses the public Imagenette-320 archive. Its archive
+SHA-256 is
+`569b4497c98db6dd29f335d1f109cf315fe127053cedf69010d047f0188e158c`.
+An immutable manifest records every image path, byte count, SHA-256, source,
+split, and leakage group; its SHA-256 is
+`2071f89b2a7b077d7729641fc858e1225d057d11a797d16198c0d195d989bb89`.
+The upstream train/validation boundary is preserved.
+
+Each run trains on the same class-interleaved prefix of 2,500 training images,
+exactly 250 from each of Imagenette's ten classes, for 12,000 batch-8 updates.
+The objective is mean absolute error. Adam uses
+beta1 0.9, beta2 0.999, epsilon 1e-8, and a learning rate that decays linearly
+from 0.002 to 0.0001 over the first 95% of updates, then remains at 0.0001.
+Seeds 0, 1, and 2 independently control initialization and data order. The
+selected deployment artifact is seed 0 by prior rule, not the best validation
+seed.
+
+Every photograph is center-cropped to its largest square and resized to 224
+by 224 with a Catmull-Rom filter; there is no stochastic augmentation. The
+encoder input uses ImageNet RGB mean `[0.485, 0.456, 0.406]` and standard
+deviation `[0.229, 0.224, 0.225]`. The decoder target is the same resized RGB8
+image mapped to `[0,1]`, so preprocessing cannot create a train/evaluation
+resolution mismatch.
+
+Evaluation verifies every input hash and processes all 3,925 held-out
+validation images. It retains per-image MSE, MAE, PSNR, and RGB SSIM. RGB SSIM
+uses an 11 by 11 Gaussian window with sigma 1.5 over the valid region. Global
+PSNR is computed from aggregate squared error; seed dispersion is reported
+across independently initialized decoders.
+
+**Corrected results are pending.** The former 20.94 dB claim was the mean PSNR
+of six training images selected for a diagnostic strip and is not a
+generalization result. Pre-fix held-out runs are also invalid because their
+encoder was wrong.
+
+Training wall times are retained diagnostically but excluded from performance
+claims: the host clock and interactive workload were not controlled. The
+experiment demonstrates functional host training, not competitive training
+throughput.
+
+## 4. Device experiment
+
+The deployment graph contains the corrected three-layer encoder, patch-token
+to NCHW rearrangement, and decoder. Intermediate features remain on the GPU
+inside this graph. The application creates one inference worker per eye; each
+worker owns its Meganeura session. The render loop never waits for inference
+and drops submissions while a worker is busy instead of queuing stale camera
+frames.
+
+Both inference workers and Blade rendering submit to one Vulkan queue. The
+Meganeura branch adds `Session::set_submission_chunks(n)`, allowing a long
+plan to be split so rendering can interleave between compute submissions.
+This is the main systems question for the live experiment: chunking trades
+some isolated throughput for queue fairness under graphics co-tenancy.
+
+Fresh device results must satisfy two separate protocols:
+
+1. **Isolated native benchmark.** At least five untimed warmups, 20 retained
+   synchronized samples, median/IQR/min/max/raw samples, and three fresh
+   processes in one declared headset state.
+2. **Live-worn XR sweep.** `submission_chunks = 1, 2, 4, 8, 12, 16` at a fixed
+   inference interval, retaining every application JSON window, each eye's
+   update rate, render-submission rate, worker wall latency, thermal/power
+   snapshots, display configuration, and runtime toggles.
+
+The host and Quest must also execute one fixed public RGB frame with identical
+weights. Preprocessed patches, full encoder output, spatial decoder input, and
+reconstruction are compared by relative L2, maximum absolute error, and
+cosine similarity before any device timing is admitted.
+
+**Corrected Quest correctness and timing results are pending.** Historical
+figures such as 125 ms, 12.5 Hz, the claimed 45% elementwise share, f16
+conclusions, and the 224-to-240 comparison must not appear in the paper unless
+they are reproduced under the audited protocol on the corrected graph.
+
+## 5. What the case study can support
+
+If the pending runs pass, DinoVision provides evidence for the following
+Meganeura properties:
+
+- The graph IR expresses a ViT with patch projection, learned prefix tokens,
+  axial RoPE, multi-head attention, LayerNorm, GELU MLPs, LayerScale, and
+  residual connections, as well as a convolutional upsampling decoder.
+- The training stack differentiates and optimizes the decoder with Adam on an
+  NVIDIA Vulkan device; no decoder is trained or imported through PyTorch.
+- The same decoder definition and serialized parameters execute through the
+  inference compiler/runtime on an Android Adreno device.
+- Meganeura sessions can share Blade's Vulkan context and queue inside a live
+  OpenXR application, and chunked plan submission exposes a runtime mechanism
+  for compute/graphics co-tenancy.
+- The runtime cross-compiles without pulling host-only Hub/tokenizer
+  dependencies into Android.
+
+The strongest evidence is breadth and integration, not peak speed. This is an
+application-level complement to controlled kernel or framework comparisons.
+
+## 6. Limitations
+
+- No matched PyTorch-on-Android baseline is included. The experiment does not
+  estimate speedup over another framework.
+- Decoder quality is measured on held-out photographs. Until independent
+  headset capture sessions are grouped and held out, no quantitative
+  camera-domain quality claim is supported.
+- DINOv3 is trained for semantic invariance, not invertibility. Reconstruction
+  quality is a probe of retained information, not a measure of DINOv3's
+  intended task quality.
+- Camera conversion, CPU patchification, GPU upload, output readback,
+  smoothing, and renderer upload are not zero-copy. Worker wall time is not
+  capture-to-photon latency.
+- Stereo comfort and perceived stability are single-user observations unless
+  instrumented or evaluated with multiple participants.
+- The source revisions are not citable until DinoVision changes are committed
+  and the Meganeura Android branch is frozen or merged. The Blade checkout in
+  the neighboring repository is not necessarily the revision selected by
+  Cargo; artifact metadata records the resolved dependency instead.
+
+## 7. Artifact and licensing
+
+`experiments/README.md` defines the complete protocol and
+`experiments/AUDIT.md` records rejected evidence. Machine-readable training,
+quality, correctness, benchmark, and environment records are generated by the
+tools in `tools/`; summaries are derived from those records rather than
+manually transcribed.
+
+The public Hugging Face repository will contain corrected decoder weights,
+replicate metadata, held-out metrics, the public dataset manifest, and the
+fixed correctness frame. It will not duplicate Meta's gated DINOv3 checkpoint,
+Imagenette images, or private headset captures.
+
+DinoVision source code is MIT-licensed. The encoder is governed by Meta's
+DINOv3 License. Decoder weights are treated conservatively as DINOv3-derived:
+their distribution includes that agreement and a prominent “Built with
+DINOv3” notice, and the Meganeura paper must acknowledge DINOv3.

environment/training-source/source-snapshot/android-xr/src/lib.rs

@@ -0,0 +1,898 @@
+//! The DinoVision XR application.
+//!
+//! Renders the DINO feature view to both eyes at the headset's refresh
+//! rate, while inference runs on a worker thread at whatever rate it can
+//! manage. The renderer never waits for the encoder: it draws the most
+//! recent completed grid, so a 40 ms inference does not become a 40 ms
+//! frame.
+//!
+//! ```text
+//! cargo apk run --manifest-path android-xr/Cargo.toml --release --no-logcat
+//! adb logcat -v time | grep -E "dinovision|RustStdoutStderr"
+//! ```
+//!
+//! Frames come from the passthrough camera when it opens, and from
+//! `dinovision::source::TestPattern` when it does not — a missing runtime
+//! permission or an older Horizon OS should degrade to something visible
+//! rather than a black screen. The camera needs a grant that the manifest
+//! alone does not provide:
+//!
+//! ```text
+//! adb shell pm grant rust.dinovision_xr horizonos.permission.HEADSET_CAMERA
+//! ```
+
+#![cfg(target_os = "android")]
+
+use std::sync::Arc;
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant, SystemTime, UNIX_EPOCH};
+
+use blade_graphics as gpu;
+use dinovision::dinov3::Config;
+use dinovision::inference::{self, Weights, Worker};
+use dinovision::render::GridView;
+use dinovision::source::{FrameSource, TestPattern};
+use log::{info, warn};
+use openxr as xr;
+
+const VIEW_TYPE: xr::ViewConfigurationType = xr::ViewConfigurationType::PRIMARY_STEREO;
+const MAX_EYES: usize = 2;
+
+/// Where the app looks for weights pushed by `adb push`.
+///
+/// Bundling 43 MB of f16 weights as an asset is the eventual answer; for
+/// bring-up, a path outside the APK avoids a rebuild per weight change.
+const WEIGHTS_PATH: &str = "/data/local/tmp/dinovision/model.safetensors";
+
+/// Trained RGB decoder. When present the app shows a real reconstruction
+/// instead of the PCA colouring — the roundtrip the project is for.
+const DECODER_PATH: &str = "/data/local/tmp/dinovision/decoder.bin";
+
+/// Encoder depth used with the decoder.
+///
+/// Measured: against a 3-layer encoder the decoder reconstructs at 20.94 dB
+/// versus 19.82 dB against the full 12, and the encoder runs 3.69× faster
+/// (37.9 ms against 139.7 ms on this device). The deep layers build semantic
+/// invariance by discarding colour and texture, which is exactly what a
+/// reconstruction needs back. The decoder weights are trained for this depth
+/// and are not valid at any other.
+const RECONSTRUCTION_LAYERS: usize = 3;
+
+const CAPTURE_SIZE: (i32, i32) = (1280, 960);
+
+/// Show the camera frame directly instead of the DINO roundtrip, for
+/// checking geometry independently of the model:
+///
+/// ```text
+/// adb shell touch /data/local/tmp/dinovision/raw_camera
+/// ```
+const RAW_CAMERA_PATH: &str = "/data/local/tmp/dinovision/raw_camera";
+
+/// Dump camera frames to disk for retraining, one raw RGB file each:
+///
+/// ```text
+/// adb shell "echo room-a-01 > /data/local/tmp/dinovision/capture"
+/// # …wear the headset and look around…
+/// adb pull /sdcard/Android/data/rust.dinovision_xr/files/captures/room-a-01
+/// ```
+///
+/// The decoder has only ever been trained on clean, well-lit colour
+/// photographs, while these cameras produce noisy, wide-angle, nearly
+/// monochrome frames. That mismatch is the most likely single cause of poor
+/// reconstruction on the headset, and no amount of architecture work
+/// addresses it — the model has to see the distribution it will be used on.
+/// The flag is read from `/data/local/tmp` — apps may read there — but the
+/// frames go to the app's own external directory. SELinux forbids an
+/// `untrusted_app` writing to `shell_data_file` no matter how permissive
+/// the mode bits look:
+///
+/// ```text
+/// avc: denied { write } … tcontext=u:object_r:shell_data_file
+/// ```
+const CAPTURE_FLAG_PATH: &str = "/data/local/tmp/dinovision/capture";
+const CAPTURE_DIR_BASE: &str = "/sdcard/Android/data/rust.dinovision_xr/files/captures";
+
+fn capture_directory() -> Option<String> {
+    if !std::path::Path::new(CAPTURE_FLAG_PATH).exists() {
+        return None;
+    }
+    let requested = std::fs::read_to_string(CAPTURE_FLAG_PATH).unwrap_or_default();
+    let requested = requested.trim();
+    let session = if requested.is_empty() {
+        format!(
+            "session-{}",
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap_or_default()
+                .as_secs()
+        )
+    } else if requested
+        .chars()
+        .all(|c| c.is_ascii_alphanumeric() || matches!(c, '-' | '_'))
+    {
+        requested.to_string()
+    } else {
+        warn!("invalid capture session {requested:?}; use only ASCII letters, digits, '-' and '_'");
+        return None;
+    };
+    let directory = format!("{CAPTURE_DIR_BASE}/{session}");
+    if std::fs::read_dir(&directory)
+        .ok()
+        .and_then(|mut entries| entries.next())
+        .is_some()
+    {
+        warn!("capture session directory is not empty; refusing to overwrite {directory}");
+        return None;
+    }
+    match std::fs::create_dir_all(&directory) {
+        Ok(()) => {
+            info!("capturing session {session:?} to {directory}");
+            Some(directory)
+        }
+        Err(error) => {
+            warn!("could not create capture session directory {directory}: {error}");
+            None
+        }
+    }
+}
+
+/// Frames to keep, and how many to skip between them.
+///
+/// Consecutive frames of a barely-moving head are near-duplicates and teach
+/// almost nothing, so sampling sparsely buys far more variety per byte. At
+/// 224² RGB a frame is 150 KB, so this caps the dump around 225 MB.
+const CAPTURE_LIMIT: usize = 1500;
+const CAPTURE_STRIDE: u64 = 8;
+
+/// Run one camera and one roundtrip, shown to both eyes:
+///
+/// ```text
+/// adb shell touch /data/local/tmp/dinovision/mono
+/// ```
+///
+/// Halves the work, since encoder and decoder both run once instead of
+/// twice, and roughly doubles the update rate. The cost is that the right
+/// eye sees the world from the left camera's position, so there is no
+/// stereo depth — worth it when the question is latency rather than
+/// whether the roundtrip fuses.
+const MONO_PATH: &str = "/data/local/tmp/dinovision/mono";
+
+/// How far each new result moves the displayed image. 1.0 shows the raw
+/// result and flickers; lower is steadier but lags. At ~12 Hz inference,
+/// 0.35 settles within a few frames while killing most of the jitter.
+const SMOOTHING: f32 = 0.35;
+
+/// Optional override for the camera image's vertical half-angle, in
+/// degrees.
+///
+/// Unset — the normal case — the image simply spans each eye's field of
+/// view, which is what passthrough itself does with these cameras. Only
+/// worth setting if the camera turns out to see meaningfully more or less
+/// than the display shows:
+///
+/// ```text
+/// adb shell "echo 40 > /data/local/tmp/dinovision/camera_half_fov_deg"
+/// ```
+///
+/// The full frame is resampled rather than cropped, so the horizontal
+/// extent follows from the sensor aspect: for a rectilinear lens the
+/// tangents scale with the sensor dimensions, giving
+/// `tan(hfov/2) = (w/h) · tan(vfov/2)`.
+const HALF_FOV_PATH: &str = "/data/local/tmp/dinovision/camera_half_fov_deg";
+
+fn read_half_fov() -> Option<f32> {
+    let deg = std::fs::read_to_string(HALF_FOV_PATH)
+        .ok()
+        .and_then(|s| s.trim().parse::<f32>().ok())?;
+    info!("camera half-FOV override: {deg} deg");
+    Some(deg.to_radians())
+}
+
+/// Minimum gap between inference submissions, in milliseconds, read from a
+/// pushed file so it can be changed without rebuilding:
+///
+/// ```text
+/// adb shell "echo 300 > /data/local/tmp/dinovision/inference_interval_ms"
+/// ```
+///
+/// Inference and rendering share one Vulkan queue, so a long compute
+/// submission delays the frame queued behind it. Left unthrottled the
+/// worker resubmits the instant it finishes, so the GPU is never free and
+/// the render loop is dragged down to the encoder's cadence. Raising this
+/// trades feature-update rate for frame rate. A very large value disables
+/// inference entirely, which is how the renderer's standalone cost is
+/// measured.
+const INTERVAL_PATH: &str = "/data/local/tmp/dinovision/inference_interval_ms";
+
+/// How many submissions the encoder is split across, same override
+/// mechanism as the interval.
+const CHUNKS_PATH: &str = "/data/local/tmp/dinovision/submission_chunks";
+
+/// One chunk per transformer layer, roughly. At ~135 ms for the whole
+/// encoder that is ~11 ms of queue occupancy at a time, which fits inside a
+/// 90 Hz frame budget instead of blowing through eleven of them.
+const DEFAULT_CHUNKS: usize = 12;
+
+fn read_chunks() -> usize {
+    let n = std::fs::read_to_string(CHUNKS_PATH)
+        .ok()
+        .and_then(|s| s.trim().parse::<usize>().ok())
+        .unwrap_or(DEFAULT_CHUNKS);
+    info!("submission chunks: {n}");
+    n
+}
+
+/// Measured on a Quest 3S at 224², where the encoder takes ~135 ms:
+///
+/// | interval | render | inference |
+/// |---------:|-------:|----------:|
+/// |      off |  90 Hz |         — |
+/// |   500 ms |  67 Hz |    2.0 Hz |
+/// |   250 ms |  27 Hz |    3.7 Hz |
+/// |        0 |  15 Hz |    7.6 Hz |
+///
+/// Render rate tracks `(1 - duty cycle) × 90 Hz` fairly closely, which is
+/// the whole story: throttling does not avoid the stall, it just chooses
+/// how often to pay it. 500 ms keeps rendering comfortable, and the view
+/// is nearly static anyway.
+const DEFAULT_INTERVAL_MS: u64 = 500;
+
+fn read_interval() -> Duration {
+    let ms = std::fs::read_to_string(INTERVAL_PATH)
+        .ok()
+        .and_then(|s| s.trim().parse::<u64>().ok())
+        .unwrap_or(DEFAULT_INTERVAL_MS);
+    info!("inference interval: {ms} ms");
+    Duration::from_millis(ms)
+}
+
+/// One eye's chain: its own camera, its own encode, its own image.
+///
+/// Kept entirely separate per eye because the experiment is whether the
+/// roundtrip survives stereo fusion. Sharing anything — one camera shown
+/// twice, or one encode reused — would answer a different and easier
+/// question.
+struct EyePipeline {
+    source: Box<dyn FrameSource>,
+    worker: Worker,
+    view: GridView,
+    /// Exponentially smoothed image, damping per-frame feature jitter.
+    smoothed: Vec<f32>,
+    last_shown: u64,
+    last_submit: Instant,
+    eye: dinovision::camera::Eye,
+    /// Head orientation when the in-flight frame was captured, and when
+    /// the frame currently on screen was. The difference between the
+    /// latter and the live pose is what keeps the image world-locked.
+    pending_orientation: Option<[f32; 4]>,
+    shown_orientation: Option<[f32; 4]>,
+}
+
+struct App {
+    surface: gpu::XrSurface,
+    /// One per eye when both cameras open, otherwise a single shared chain
+    /// drawn to both.
+    eyes: Vec<EyePipeline>,
+    config: Config,
+    frames: u64,
+    last_report: Instant,
+    /// Completed results per eye pipeline in the current reporting window.
+    /// Keeping these separate avoids calling two asynchronous eye updates a
+    /// single "inference Hz" figure.
+    inference_counts: Vec<u64>,
+    /// Wall latency for every completed worker result in the current window.
+    inference_latencies_ms: Vec<Vec<f64>>,
+    /// Minimum gap between inference submissions. See [`INTERVAL_PATH`].
+    interval: Duration,
+    submission_chunks: usize,
+    camera_active: bool,
+    /// Bypass inference and show the camera frame. See [`RAW_CAMERA_PATH`].
+    raw_camera: bool,
+    raw_scratch: Vec<f32>,
+    /// Tangent of the image half-angle, per axis. See [`HALF_FOV_PATH`].
+    camera_half_tan: Option<[f32; 2]>,
+    logged_fov: bool,
+    /// Frames written so far, and the counter that strides between them.
+    captured: usize,
+    capture_tick: u64,
+    capturing: bool,
+    capture_dir: Option<String>,
+    /// Head orientation from the previous frame. Used when submitting, so
+    /// it is one frame stale — around 10 ms against the 100 ms the
+    /// inference itself takes, which is the lag that actually matters.
+    last_head: Option<[f32; 4]>,
+}
+
+impl App {
+    fn new(context: &Arc<gpu::Context>, config: Config) -> Self {
+        let surface = context
+            .create_xr_surface()
+            .expect("unable to create XR surface");
+
+        // A trained decoder turns this into the actual roundtrip, at a
+        // shallower and much cheaper encoder depth.
+        let decoder_path = std::path::PathBuf::from(DECODER_PATH);
+        let (config, display, view_grid) = if decoder_path.exists() {
+            info!("reconstructing with {}", decoder_path.display());
+            let config = config.with_layers(RECONSTRUCTION_LAYERS);
+            let grid = config.image_size;
+            (
+                config,
+                inference::Display::Reconstruction(decoder_path),
+                grid,
+            )
+        } else {
+            let grid = config.grid();
+            (config, inference::Display::PcaColour, grid)
+        };
+        // Raw camera frames are full resolution regardless of what the
+        // model would have produced.
+        let raw_camera = std::path::Path::new(RAW_CAMERA_PATH).exists();
+        if raw_camera {
+            info!("raw camera mode — inference bypassed");
+        }
+        let view_grid = if raw_camera {
+            config.image_size
+        } else {
+            view_grid
+        };
+
+        // Real weights if they have been pushed, synthetic otherwise, so
+        // the render path can be brought up before the checkpoint is on
+        // the device.
+        let weights_path = std::path::PathBuf::from(WEIGHTS_PATH);
+        let have_weights = weights_path.exists();
+        if have_weights {
+            info!("using weights from {}", weights_path.display());
+        } else {
+            warn!(
+                "no weights at {WEIGHTS_PATH} — running synthetic; \
+                 adb push the checkpoint there for real features"
+            );
+        }
+
+        // One chain per eye if both cameras open. Two encodes cost twice the
+        // GPU, which is the price of the question being asked: whether a
+        // reconstructed world still fuses into a single stereo percept. A
+        // single camera shown to both eyes cannot answer it — that is
+        // monocular, and would look flat and offset no matter how good the
+        // reconstruction is.
+        let chunks = read_chunks();
+        let mono = std::path::Path::new(MONO_PATH).exists();
+        if mono {
+            info!("monocular: one camera and one roundtrip for both eyes");
+        }
+        let wanted: &[dinovision::camera::Eye] = if mono {
+            &[dinovision::camera::Eye::Left]
+        } else {
+            &[
+                dinovision::camera::Eye::Left,
+                dinovision::camera::Eye::Right,
+            ]
+        };
+        let mut sources: Vec<(dinovision::camera::Eye, Box<dyn FrameSource>)> = Vec::new();
+        for &eye in wanted {
+            match dinovision::camera::PassthroughCamera::new(config.image_size, eye, CAPTURE_SIZE) {
+                Ok(camera) => {
+                    info!("{eye:?} camera open");
+                    sources.push((eye, Box::new(camera)));
+                }
+                Err(e) => warn!("{eye:?} camera unavailable: {e}"),
+            }
+        }
+        if sources.is_empty() {
+            warn!(
+                "no camera opened; falling back to the test pattern. Grant it with: \
+                 adb shell pm grant rust.dinovision_xr horizonos.permission.HEADSET_CAMERA"
+            );
+            sources.push((
+                dinovision::camera::Eye::Left,
+                Box::new(TestPattern::new(config.image_size)),
+            ));
+        }
+
+        let eyes: Vec<EyePipeline> = sources
+            .into_iter()
+            .map(|(eye, source)| EyePipeline {
+                source,
+                // No plan cache: two sessions would race on the same file.
+                worker: inference::spawn(
+                    Arc::clone(context),
+                    config.clone(),
+                    if have_weights {
+                        Weights::SafeTensors(weights_path.clone())
+                    } else {
+                        Weights::Synthetic
+                    },
+                    None,
+                    chunks,
+                    display.clone(),
+                ),
+                view: GridView::new(context, surface.format(), view_grid),
+                smoothed: Vec::new(),
+                last_shown: 0,
+                last_submit: Instant::now(),
+                eye,
+                pending_orientation: None,
+                shown_orientation: None,
+            })
+            .collect();
+        info!(
+            "{} eye pipeline(s) — {}",
+            eyes.len(),
+            if eyes.len() > 1 {
+                "stereo"
+            } else {
+                "monocular"
+            }
+        );
+        let eye_count = eyes.len();
+        let interval = read_interval();
+
+        let capture_dir = capture_directory();
+        Self {
+            surface,
+            eyes,
+            config,
+            frames: 0,
+            last_report: Instant::now(),
+            inference_counts: vec![0; eye_count],
+            inference_latencies_ms: vec![Vec::new(); eye_count],
+            interval,
+            submission_chunks: chunks,
+            camera_active: true,
+            raw_camera,
+            raw_scratch: Vec::new(),
+            last_head: None,
+            captured: 0,
+            capture_tick: 0,
+            capturing: capture_dir.is_some(),
+            capture_dir,
+            camera_half_tan: read_half_fov().map(|v| {
+                let t = v.tan();
+                let aspect = CAPTURE_SIZE.0 as f32 / CAPTURE_SIZE.1 as f32;
+                [t * aspect, t]
+            }),
+            logged_fov: false,
+        }
+    }
+
+    /// Acquire or release the camera as focus comes and goes.
+    ///
+    /// Android hands the camera to the foreground app and takes it back
+    /// otherwise; holding it while backgrounded is what produced
+    /// `ACameraDevice` error 3. Releasing on the way out also means the
+    /// headset camera stops streaming to an app the wearer has navigated
+    /// away from, which is the behaviour anyone would expect of it.
+    fn set_camera_active(&mut self, active: bool) {
+        if active == self.camera_active {
+            return;
+        }
+        self.camera_active = active;
+        let size = self.config.image_size;
+        for pipeline in &mut self.eyes {
+            if active {
+                match dinovision::camera::PassthroughCamera::new(size, pipeline.eye, CAPTURE_SIZE) {
+                    Ok(camera) => {
+                        info!("{:?} camera reacquired on focus", pipeline.eye);
+                        pipeline.source = Box::new(camera);
+                    }
+                    Err(e) => warn!("could not reacquire the {:?} camera: {e}", pipeline.eye),
+                }
+            } else {
+                // Dropping the camera closes the device and stops the stream.
+                info!("releasing the {:?} camera on focus loss", pipeline.eye);
+                pipeline.source = Box::new(TestPattern::new(size));
+            }
+        }
+    }
+
+    fn render(&mut self, context: &gpu::Context, encoder: &mut gpu::CommandEncoder) {
+        let interval = self.interval;
+        let raw = self.raw_camera;
+        let config = self.config.clone();
+        let head = self.last_head;
+
+        // Snapshot frames for retraining, from the first eye only — the two
+        // cameras see nearly the same scene, so the second would mostly
+        // duplicate the first.
+        if self.capturing && self.captured < CAPTURE_LIMIT {
+            self.capture_tick += 1;
+            if self.capture_tick.is_multiple_of(CAPTURE_STRIDE)
+                && let Some(pipeline) = self.eyes.first_mut()
+                && let Some(rgb) = pipeline.source.next_frame()
+            {
+                let path = format!(
+                    "{}/{:05}.rgb",
+                    self.capture_dir.as_deref().expect("capture directory"),
+                    self.captured
+                );
+                match std::fs::write(&path, rgb) {
+                    Ok(()) => {
+                        self.captured += 1;
+                        if self.captured.is_multiple_of(100) {
+                            info!("captured {} / {CAPTURE_LIMIT} frames", self.captured);
+                        }
+                    }
+                    Err(e) => {
+                        warn!("capture failed ({e}); stopping");
+                        self.capturing = false;
+                    }
+                }
+            }
+        }
+        for (pipeline_index, pipeline) in self.eyes.iter_mut().enumerate() {
+            if raw {
+                // Straight to the display, no model in the way, for judging
+                // geometry and render submission rate separately from the
+                // network. Keep this before worker submission: "raw" must
+                // not leave hidden inference contending for the same queue.
+                if let Some(rgb) = pipeline.source.next_frame() {
+                    self.raw_scratch.clear();
+                    self.raw_scratch
+                        .extend(rgb.iter().map(|&b| b as f32 / 255.0));
+                    pipeline.view.upload(context, &self.raw_scratch);
+                }
+                continue;
+            }
+
+            // Keep each worker fed. They report not-ready while busy, and
+            // frames offered meanwhile are dropped rather than queued — a
+            // queued frame would be stale by the time it ran.
+            if pipeline.worker.is_ready()
+                && pipeline.last_submit.elapsed() >= interval
+                && let Some(rgb) = pipeline.source.next_frame()
+            {
+                let patches = dinovision::preprocess::patches_from_rgb8(rgb, &config);
+                if pipeline.worker.submit(patches) {
+                    pipeline.last_submit = Instant::now();
+                    // Remember where the head was pointing, so the result
+                    // can be put back in the world where it was seen.
+                    pipeline.pending_orientation = head;
+                }
+            }
+
+            let generation = pipeline.worker.generation();
+            if generation != pipeline.last_shown
+                && let Some(grid) = pipeline.worker.latest()
+            {
+                // Blend towards the new frame rather than snapping to it.
+                // DINO features are sensitive enough that sensor noise and
+                // auto-exposure make individual patches jump between
+                // consecutive frames, which reads as constant flickering
+                // even with the head still.
+                let new = grid.patch_rgb();
+                if pipeline.smoothed.len() != new.len() {
+                    pipeline.smoothed = new.to_vec();
+                } else {
+                    for (s, &n) in pipeline.smoothed.iter_mut().zip(new) {
+                        *s += (n - *s) * SMOOTHING;
+                    }
+                }
+                pipeline.view.upload(context, &pipeline.smoothed);
+                pipeline.last_shown = generation;
+                pipeline.shown_orientation = pipeline.pending_orientation;
+                self.inference_counts[pipeline_index] += 1;
+                self.inference_latencies_ms[pipeline_index].push(grid.latency_ms);
+            }
+        }
+
+        let Some(frame) = self.surface.acquire_frame(context) else {
+            return;
+        };
+
+        encoder.start();
+        encoder.init_texture(frame.texture());
+
+        let eyes = frame.xr_view_count().min(MAX_EYES as u32);
+        for eye in 0..eyes {
+            // Each eye's frustum is asymmetric and differs from the other's,
+            // so the overlay has to be placed per eye. Skipping this is what
+            // made the two views refuse to fuse.
+            let xr_view = frame.xr_view(eye);
+            let fov = [
+                xr_view.fov.angle_left,
+                xr_view.fov.angle_right,
+                xr_view.fov.angle_up,
+                xr_view.fov.angle_down,
+            ];
+            if !self.logged_fov {
+                info!(
+                    "eye {eye} frustum: L {:.1} R {:.1} U {:.1} D {:.1} deg \
+                     (axis offset x {:.2} y {:.2})",
+                    fov[0].to_degrees(),
+                    fov[1].to_degrees(),
+                    fov[2].to_degrees(),
+                    fov[3].to_degrees(),
+                    -(fov[1].tan() + fov[0].tan()) / (fov[1].tan() - fov[0].tan()),
+                    -(fov[2].tan() + fov[3].tan()) / (fov[2].tan() - fov[3].tan()),
+                );
+                if eye + 1 == eyes {
+                    self.logged_fov = true;
+                }
+            }
+            let now = xr_view.pose.orientation;
+            if eye == 0 {
+                self.last_head = Some(now);
+            }
+
+            // With two cameras each eye shows its own; with one, both show
+            // the same and the view is monocular.
+            let index = (eye as usize).min(self.eyes.len() - 1);
+
+            // Put the image back where the head was pointing when the
+            // camera saw it, so it holds still in the world while the view
+            // sweeps across it. Without this the picture is glued to the
+            // screen and drags a tenth of a second behind every turn.
+            let centre = self.eyes[index]
+                .shown_orientation
+                .and_then(|then| dinovision::render::reprojection_offset(then, now))
+                .unwrap_or([0.0, 0.0]);
+            self.eyes[index].view.set_transform(
+                context,
+                eye as usize,
+                // Same size as filling the buffer, but recentred on each
+                // eye's own axis. Still a 2D scale and offset; nothing is
+                // projected.
+                //
+                // The recentring is not optional, and this device says so
+                // with numbers. Its frusta are asymmetric and mirrored —
+                // left eye L -49.0 R +45.0, right eye L -45.0 R +49.0 — so
+                // an image filling the buffer has its centre at -2.0 deg in
+                // the left eye and +2.0 deg in the right. That is 4 deg of
+                // *divergence*, pulling the eyes apart, against a fusion
+                // limit of roughly 1 deg. It reads exactly as "the object
+                // is further left in my left eye" and it cannot converge.
+                match self.camera_half_tan {
+                    Some(half_tan) => dinovision::render::EyeTransform::for_eye(fov, half_tan),
+                    None => dinovision::render::EyeTransform::filling_at(fov, centre),
+                },
+            );
+
+            let mut pass = encoder.render(
+                "eye",
+                gpu::RenderTargetSet {
+                    colors: &[gpu::RenderTarget {
+                        view: frame.xr_texture_view(eye),
+                        // The view covers every pixel, so clearing would only
+                        // be wasted bandwidth on a tiler.
+                        init_op: gpu::InitOp::Clear(gpu::TextureColor::OpaqueBlack),
+                        finish_op: gpu::FinishOp::Store,
+                    }],
+                    depth_stencil: None,
+                },
+            );
+            self.eyes[index].view.draw(&mut pass, eye as usize);
+        }
+
+        encoder.present(frame);
+        let _sync_point = context.submit(encoder);
+        self.frames += 1;
+
+        if self.last_report.elapsed() >= Duration::from_secs(5) {
+            let secs = self.last_report.elapsed().as_secs_f64();
+            let render_hz = self.frames as f64 / secs;
+            let per_eye_hz: Vec<f64> = self
+                .inference_counts
+                .iter()
+                .map(|&count| count as f64 / secs)
+                .collect();
+            // This is the lower eye update rate, not a synchronization claim:
+            // the two cameras and workers are currently independent.
+            let min_eye_hz = per_eye_hz.iter().copied().fold(f64::INFINITY, f64::min);
+            let latencies: Vec<Option<f64>> = self
+                .eyes
+                .iter()
+                .map(|eye| eye.worker.latest().map(|grid| grid.latency_ms))
+                .collect();
+            info!(
+                "render {:.1} Hz | per-eye updates {:?} Hz | min-eye {:.1} Hz | worker latency {:?} ms",
+                render_hz, per_eye_hz, min_eye_hz, latencies,
+            );
+            let counts_json = self
+                .inference_counts
+                .iter()
+                .map(u64::to_string)
+                .collect::<Vec<_>>()
+                .join(",");
+            let rates_json = per_eye_hz
+                .iter()
+                .map(|value| format!("{value:.6}"))
+                .collect::<Vec<_>>()
+                .join(",");
+            let latency_json = latencies
+                .iter()
+                .map(|value| value.map_or_else(|| "null".into(), |v| format!("{v:.6}")))
+                .collect::<Vec<_>>()
+                .join(",");
+            let latency_samples_json = self
+                .inference_latencies_ms
+                .iter()
+                .map(|samples| {
+                    format!(
+                        "[{}]",
+                        samples
+                            .iter()
+                            .map(|value| format!("{value:.6}"))
+                            .collect::<Vec<_>>()
+                            .join(",")
+                    )
+                })
+                .collect::<Vec<_>>()
+                .join(",");
+            info!(
+                "DINOVISION_APP_JSON {{\"schema_version\":1,\"kind\":\"dinovision_app_window\",\
+                 \"window_seconds\":{secs:.6},\"render_frames\":{},\"render_hz\":{render_hz:.6},\
+                 \"per_eye_update_counts\":[{counts_json}],\"per_eye_update_hz\":[{rates_json}],\
+                 \"min_eye_update_hz\":{min_eye_hz:.6},\"worker_latest_latency_ms\":[{latency_json}],\
+                 \"worker_latency_samples_ms\":[{latency_samples_json}],\"submission_chunks\":{},\
+                 \"inference_interval_ms\":{},\"raw_camera\":{}}}",
+                self.frames,
+                self.submission_chunks,
+                self.interval.as_millis(),
+                self.raw_camera,
+            );
+            self.frames = 0;
+            self.inference_counts.fill(0);
+            self.inference_latencies_ms.iter_mut().for_each(Vec::clear);
+            self.last_report = Instant::now();
+        }
+    }
+
+    fn destroy(mut self, context: &gpu::Context) {
+        // Drop the workers first: each holds an `Arc<Context>` and must
+        // finish any in-flight submission before the surface goes away.
+        for pipeline in self.eyes.drain(..) {
+            drop(pipeline.worker);
+            pipeline.view.destroy(context);
+        }
+        context.destroy_xr_surface(&mut self.surface);
+    }
+}
+
+fn spawn_event_pump() -> Arc<AtomicBool> {
+    let should_exit = Arc::new(AtomicBool::new(false));
+    let flag = Arc::clone(&should_exit);
+    std::thread::spawn(move || {
+        while let Some(event) = ndk_glue::poll_events() {
+            if matches!(event, ndk_glue::Event::Destroy) {
+                flag.store(true, Ordering::Relaxed);
+                break;
+            }
+        }
+    });
+    should_exit
+}
+
+#[ndk_glue::main]
+pub fn main() {
+    android_logger::init_once(
+        android_logger::Config::default()
+            .with_max_level(log::LevelFilter::Info)
+            .with_tag("dinovision"),
+    );
+    std::panic::set_hook(Box::new(|info| log::error!("panic: {info}")));
+    info!("=== dinovision starting ===");
+
+    let entry = unsafe { xr::Entry::load().expect("no OpenXR loader") };
+    entry.initialize_android_loader().unwrap();
+
+    let available = entry.enumerate_extensions().unwrap();
+    assert!(
+        available.khr_vulkan_enable2,
+        "runtime lacks XR_KHR_vulkan_enable2"
+    );
+    let mut extensions = xr::ExtensionSet::default();
+    extensions.khr_vulkan_enable2 = true;
+    extensions.khr_android_create_instance = true;
+
+    let xr_instance = entry
+        .create_instance(
+            &xr::ApplicationInfo {
+                application_name: "DinoVision",
+                application_version: 0,
+                engine_name: "Blade",
+                engine_version: 0,
+                api_version: xr::Version::new(1, 0, 0),
+            },
+            &extensions,
+            &[],
+        )
+        .unwrap();
+    let system = xr_instance
+        .system(xr::FormFactor::HEAD_MOUNTED_DISPLAY)
+        .unwrap();
+
+    // One context, shared by the renderer and by meganeura. This is the
+    // whole reason the crate pins meganeura's blade revision.
+    let context = Arc::new(unsafe {
+        gpu::Context::init(gpu::ContextDesc {
+            xr: Some(gpu::XrDesc {
+                instance: xr_instance.clone(),
+                system_id: system,
+            }),
+            ..Default::default()
+        })
+        .expect("failed to initialize GPU context")
+    });
+    let info = context.device_information();
+    info!("GPU: {} ({})", info.device_name, info.driver_name);
+
+    // 224, measured. Desktop suggested 256 was nearly free (+15% time for
+    // +30% tokens) because it was dispatch-bound there. On the Adreno it is
+    // compute-bound, and 256 costs +51% — 85 ms versus 130 ms — for one
+    // extra row and column of features. Not worth it.
+    let config = Config::vits16().at_resolution(224);
+
+    let mut encoder = context.create_command_encoder(gpu::CommandEncoderDesc {
+        name: "dinovision",
+        buffer_count: 2,
+        manual_barriers: false,
+    });
+
+    let mut app: Option<App> = None;
+    let should_exit = spawn_event_pump();
+    let mut events = xr::EventDataBuffer::new();
+
+    'main: loop {
+        if should_exit.load(Ordering::Relaxed) {
+            break 'main;
+        }
+
+        while let Some(event) = xr_instance.poll_event(&mut events).unwrap() {
+            use xr::Event::*;
+            match event {
+                SessionStateChanged(e) => {
+                    info!("XR session state: {:?}", e.state());
+                    match e.state() {
+                        xr::SessionState::READY => {
+                            if app.is_none() {
+                                app = Some(App::new(&context, config.clone()));
+                            }
+                            context.xr_session().unwrap().begin(VIEW_TYPE).unwrap();
+                        }
+                        xr::SessionState::STOPPING => {
+                            context.xr_session().unwrap().end().unwrap();
+                            if let Some(app) = app.take() {
+                                app.destroy(&context);
+                            }
+                        }
+                        // Release the camera the moment we stop being the
+                        // focused app. Android revokes it from background
+                        // apps anyway — that is what error code 3 was — and
+                        // holding it is both rude to whatever wants it next
+                        // and a privacy question, since a headset camera
+                        // should not keep streaming to an app the wearer has
+                        // navigated away from.
+                        xr::SessionState::VISIBLE | xr::SessionState::SYNCHRONIZED => {
+                            if let Some(app) = app.as_mut() {
+                                app.set_camera_active(false);
+                            }
+                        }
+                        xr::SessionState::FOCUSED => {
+                            if let Some(app) = app.as_mut() {
+                                app.set_camera_active(true);
+                            }
+                        }
+                        xr::SessionState::EXITING | xr::SessionState::LOSS_PENDING => break 'main,
+                        _ => {}
+                    }
+                }
+                InstanceLossPending(_) => break 'main,
+                _ => {}
+            }
+        }
+
+        match &mut app {
+            Some(app) => app.render(&context, &mut encoder),
+            // Not in session yet; idle rather than spin.
+            None => std::thread::sleep(Duration::from_millis(50)),
+        }
+    }
+
+    if let Some(app) = app.take() {
+        app.destroy(&context);
+    }
+    context.destroy_command_encoder(&mut encoder);
+    info!("=== dinovision stopped ===");
+}

environment/training-source/source-snapshot/examples/bench.rs

@@ -0,0 +1,44 @@
+//! Desktop benchmark runner.
+//!
+//! The same [`dinovision::bench`] code runs on the Quest through the
+//! `android` crate; running it here first gives a reference point from a
+//! GPU that *does* have cooperative matrix, which makes the Adreno numbers
+//! interpretable rather than just small.
+//!
+//! ```text
+//! cargo run --release --example bench -- [iters]
+//! DINOVISION_BENCH=shapes cargo run --release --example bench -- [iters]
+//! ```
+//!
+//! With `DINOVISION_BENCH=shapes`, runs only the matmul shape sweep — the diagnostic for
+//! what the register-tiled kernel is short of. It takes a couple of minutes
+//! instead of the full suite's twenty, which matters when the target is a
+//! headset on a flaky wireless adb link.
+
+fn main() {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    let iters = std::env::args()
+        .nth(1)
+        .and_then(|s| s.parse().ok())
+        .unwrap_or(20);
+    // Selected by environment, not by argument: `std::env::args()` does not
+    // survive the trip to an adb shell on Horizon OS, and silently running
+    // the wrong benchmark is worse than an ugly interface. `RUST_LOG`
+    // already proves the environment arrives intact.
+    let shapes_only = std::env::var("DINOVISION_BENCH").as_deref() == Ok("shapes");
+
+    let gpu = dinovision::init_context(None).expect("failed to initialize GPU context");
+    let results = if shapes_only {
+        dinovision::bench::describe_device(&gpu);
+        dinovision::bench::matmul_shapes(gpu, iters)
+    } else {
+        dinovision::bench::run_all(gpu, iters)
+    };
+
+    println!("\n{:-<80}", "");
+    for t in &results {
+        println!("{t}");
+        println!("DINOVISION_BENCH_JSON {}", t.json_line());
+    }
+}

environment/training-source/source-snapshot/examples/common/mod.rs

@@ -0,0 +1,310 @@
+//! Dataset handling shared by the decoder trainer and evaluator.
+
+#![allow(dead_code)] // Each example uses a different subset of these helpers.
+
+use std::collections::HashMap;
+use std::io::Read;
+use std::path::{Path, PathBuf};
+
+use serde::{Deserialize, Serialize};
+use sha2::{Digest, Sha256};
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct DatasetManifest {
+    pub schema_version: u32,
+    pub name: String,
+    /// Relative to the manifest file unless absolute. May be overridden by
+    /// `DINOVISION_DATA_ROOT` on another machine.
+    pub root: PathBuf,
+    pub images: Vec<ManifestImage>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ManifestImage {
+    pub path: PathBuf,
+    pub split: String,
+    pub source: String,
+    /// Capture session, photo collection, or other leakage boundary. A group
+    /// must occur in exactly one split.
+    pub group: String,
+    pub sha256: String,
+    pub bytes: u64,
+}
+
+pub struct LoadedManifest {
+    pub manifest: DatasetManifest,
+    pub root: PathBuf,
+}
+
+pub fn load_manifest(path: &Path) -> Result<LoadedManifest, Box<dyn std::error::Error>> {
+    let bytes = std::fs::read(path)?;
+    let manifest: DatasetManifest = serde_json::from_slice(&bytes)?;
+    if manifest.schema_version != 1 {
+        return Err(format!(
+            "{} uses unsupported manifest schema {}",
+            path.display(),
+            manifest.schema_version
+        )
+        .into());
+    }
+    let root = match std::env::var_os("DINOVISION_DATA_ROOT") {
+        Some(value) => PathBuf::from(value),
+        None if manifest.root.is_absolute() => manifest.root.clone(),
+        None => path
+            .parent()
+            .unwrap_or_else(|| Path::new("."))
+            .join(&manifest.root),
+    };
+
+    validate_manifest(&manifest)?;
+    Ok(LoadedManifest { manifest, root })
+}
+
+fn validate_manifest(manifest: &DatasetManifest) -> Result<(), Box<dyn std::error::Error>> {
+    if manifest.images.is_empty() {
+        return Err("dataset manifest contains no images".into());
+    }
+
+    let mut group_splits: HashMap<(&str, &str), &str> = HashMap::new();
+    let mut hashes: HashMap<&str, (&str, &Path)> = HashMap::new();
+    let mut paths: HashMap<&Path, &str> = HashMap::new();
+    for image in &manifest.images {
+        if image.split.is_empty()
+            || image.source.is_empty()
+            || image.group.is_empty()
+            || image.sha256.len() != 64
+        {
+            return Err(format!("invalid manifest entry for {}", image.path.display()).into());
+        }
+        let key = (image.source.as_str(), image.group.as_str());
+        if let Some(old) = group_splits.insert(key, image.split.as_str())
+            && old != image.split
+        {
+            return Err(format!(
+                "group {}/{} leaks across splits {old:?} and {:?}",
+                image.source, image.group, image.split
+            )
+            .into());
+        }
+        if let Some(old_split) = paths.insert(&image.path, image.split.as_str()) {
+            return Err(format!(
+                "path {} is listed more than once ({old_split} and {})",
+                image.path.display(),
+                image.split
+            )
+            .into());
+        }
+        if let Some((old_split, old_path)) =
+            hashes.insert(image.sha256.as_str(), (image.split.as_str(), &image.path))
+        {
+            return Err(format!(
+                "identical files occur more than once: {} ({old_split}) and {} ({})",
+                old_path.display(),
+                image.path.display(),
+                image.split
+            )
+            .into());
+        }
+    }
+    Ok(())
+}
+
+pub fn images_for_split(
+    path: &Path,
+    split: &str,
+    limit: usize,
+) -> Result<Vec<(PathBuf, ManifestImage)>, Box<dyn std::error::Error>> {
+    let loaded = load_manifest(path)?;
+    let mut result = Vec::new();
+    for image in loaded
+        .manifest
+        .images
+        .into_iter()
+        .filter(|image| image.split == split)
+        .take(limit)
+    {
+        result.push((loaded.root.join(&image.path), image));
+    }
+    if result.is_empty() {
+        return Err(format!("manifest has no images in split {split:?}").into());
+    }
+    Ok(result)
+}
+
+/// Collect image paths, round-robin across subdirectories.
+pub fn find_images(root: &Path, limit: usize) -> Vec<PathBuf> {
+    let mut groups: Vec<Vec<PathBuf>> = Vec::new();
+    let mut stack = vec![root.to_path_buf()];
+    while let Some(dir) = stack.pop() {
+        let Ok(entries) = std::fs::read_dir(&dir) else {
+            continue;
+        };
+        let mut here = Vec::new();
+        let mut items: Vec<_> = entries.filter_map(|e| e.ok()).map(|e| e.path()).collect();
+        items.sort();
+        for path in items {
+            if path.is_dir() {
+                stack.push(path);
+            } else if matches!(
+                path.extension().and_then(|e| e.to_str()),
+                Some("JPEG" | "jpeg" | "jpg" | "png" | "rgb")
+            ) {
+                here.push(path);
+            }
+        }
+        if !here.is_empty() {
+            groups.push(here);
+        }
+    }
+    groups.sort();
+
+    let mut out = Vec::new();
+    let deepest = groups.iter().map(|g| g.len()).max().unwrap_or(0);
+    'outer: for i in 0..deepest {
+        for group in &groups {
+            if let Some(path) = group.get(i) {
+                out.push(path.clone());
+                if out.len() >= limit {
+                    break 'outer;
+                }
+            }
+        }
+    }
+    out
+}
+
+/// Load a photograph or a raw headset capture as interleaved RGB8.
+pub fn load_frame(path: &Path, size: u32) -> Option<Vec<u8>> {
+    if path.extension().and_then(|e| e.to_str()) == Some("rgb") {
+        let bytes = std::fs::read(path).ok()?;
+        let expected = (size * size * 3) as usize;
+        if bytes.len() != expected {
+            log::warn!(
+                "{}: {} bytes, expected {expected} — captured at a different resolution?",
+                path.display(),
+                bytes.len()
+            );
+            return None;
+        }
+        return Some(bytes);
+    }
+    load_rgb(path, size)
+}
+
+fn load_rgb(path: &Path, size: u32) -> Option<Vec<u8>> {
+    let img = image::open(path).ok()?.to_rgb8();
+    let (w, h) = (img.width(), img.height());
+    let side = w.min(h);
+    let cropped = image::imageops::crop_imm(&img, (w - side) / 2, (h - side) / 2, side, side);
+    let resized = image::imageops::resize(
+        &cropped.to_image(),
+        size,
+        size,
+        image::imageops::FilterType::CatmullRom,
+    );
+    Some(resized.into_raw())
+}
+
+pub fn sha256(path: &Path) -> Result<String, std::io::Error> {
+    let mut file = std::fs::File::open(path)?;
+    let mut hasher = Sha256::new();
+    let mut buffer = vec![0u8; 1024 * 1024];
+    loop {
+        let n = file.read(&mut buffer)?;
+        if n == 0 {
+            break;
+        }
+        hasher.update(&buffer[..n]);
+    }
+    Ok(format!("{:x}", hasher.finalize()))
+}
+
+pub fn verify_image(path: &Path, image: &ManifestImage) -> Result<(), Box<dyn std::error::Error>> {
+    let metadata = std::fs::metadata(path)?;
+    if metadata.len() != image.bytes {
+        return Err(format!(
+            "{} is {} bytes; manifest records {}",
+            path.display(),
+            metadata.len(),
+            image.bytes
+        )
+        .into());
+    }
+    let digest = sha256(path)?;
+    if digest != image.sha256 {
+        return Err(format!(
+            "{} has SHA-256 {digest}; manifest records {}",
+            path.display(),
+            image.sha256
+        )
+        .into());
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn image(path: &str, split: &str, group: &str, hash: char) -> ManifestImage {
+        ManifestImage {
+            path: PathBuf::from(path),
+            split: split.to_string(),
+            source: "camera".to_string(),
+            group: group.to_string(),
+            sha256: std::iter::repeat_n(hash, 64).collect(),
+            bytes: 1,
+        }
+    }
+
+    fn manifest(images: Vec<ManifestImage>) -> DatasetManifest {
+        DatasetManifest {
+            schema_version: 1,
+            name: "test".to_string(),
+            root: PathBuf::from("."),
+            images,
+        }
+    }
+
+    #[test]
+    fn independent_groups_and_splits_are_valid() {
+        validate_manifest(&manifest(vec![
+            image("a.rgb", "train", "session-a", 'a'),
+            image("b.rgb", "test", "session-b", 'b'),
+        ]))
+        .unwrap();
+    }
+
+    #[test]
+    fn group_cannot_cross_a_split() {
+        let error = validate_manifest(&manifest(vec![
+            image("a.rgb", "train", "session-a", 'a'),
+            image("b.rgb", "test", "session-a", 'b'),
+        ]))
+        .unwrap_err()
+        .to_string();
+        assert!(error.contains("leaks across splits"), "{error}");
+    }
+
+    #[test]
+    fn duplicate_content_is_rejected_even_within_one_split() {
+        let error = validate_manifest(&manifest(vec![
+            image("a.rgb", "train", "session-a", 'a'),
+            image("b.rgb", "train", "session-a", 'a'),
+        ]))
+        .unwrap_err()
+        .to_string();
+        assert!(error.contains("identical files"), "{error}");
+    }
+
+    #[test]
+    fn duplicate_path_is_rejected() {
+        let error = validate_manifest(&manifest(vec![
+            image("a.rgb", "train", "session-a", 'a'),
+            image("a.rgb", "train", "session-a", 'b'),
+        ]))
+        .unwrap_err()
+        .to_string();
+        assert!(error.contains("listed more than once"), "{error}");
+    }
+}

environment/training-source/source-snapshot/examples/evaluate_decoder.rs

@@ -0,0 +1,559 @@
+//! Evaluate a trained decoder on an immutable held-out dataset manifest.
+//!
+//! Unlike `train_decoder`, this program never updates parameters and never
+//! samples from the training cache. It verifies every input hash and writes
+//! per-image metrics so aggregate claims can be regenerated from raw data.
+//!
+//! ```text
+//! cargo run --release --example evaluate_decoder -- \
+//!   --manifest experiments/dataset.json \
+//!   --model model.safetensors --decoder decoder.bin \
+//!   --split test --layers 3 --output artifacts/quality.json
+//! ```
+
+use std::path::{Path, PathBuf};
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+use dinovision::decoder;
+use dinovision::dinov3::Config;
+use meganeura::train::{Mode, SessionConfig};
+use serde::Serialize;
+
+mod common;
+
+#[derive(Debug)]
+struct Args {
+    manifest: PathBuf,
+    model: PathBuf,
+    decoder: PathBuf,
+    split: String,
+    layers: usize,
+    size: usize,
+    limit: usize,
+    output: PathBuf,
+    samples: usize,
+}
+
+fn require_value(args: &mut impl Iterator<Item = String>, flag: &str) -> Result<String, String> {
+    args.next()
+        .ok_or_else(|| format!("{flag} requires a value"))
+}
+
+impl Args {
+    fn parse() -> Result<Self, String> {
+        let mut manifest = None;
+        let mut model = None;
+        let mut decoder = None;
+        let mut split = "test".to_string();
+        let mut layers = 3usize;
+        let mut size = 224usize;
+        let mut limit = usize::MAX;
+        let mut output = PathBuf::from("artifacts/quality.json");
+        let mut samples = 12usize;
+
+        let mut args = std::env::args().skip(1);
+        while let Some(flag) = args.next() {
+            match flag.as_str() {
+                "--manifest" => manifest = Some(PathBuf::from(require_value(&mut args, &flag)?)),
+                "--model" => model = Some(PathBuf::from(require_value(&mut args, &flag)?)),
+                "--decoder" => decoder = Some(PathBuf::from(require_value(&mut args, &flag)?)),
+                "--split" => split = require_value(&mut args, &flag)?,
+                "--layers" => {
+                    layers = require_value(&mut args, &flag)?
+                        .parse()
+                        .map_err(|_| "invalid --layers")?
+                }
+                "--size" => {
+                    size = require_value(&mut args, &flag)?
+                        .parse()
+                        .map_err(|_| "invalid --size")?
+                }
+                "--limit" => {
+                    limit = require_value(&mut args, &flag)?
+                        .parse()
+                        .map_err(|_| "invalid --limit")?
+                }
+                "--output" => output = PathBuf::from(require_value(&mut args, &flag)?),
+                "--samples" => {
+                    samples = require_value(&mut args, &flag)?
+                        .parse()
+                        .map_err(|_| "invalid --samples")?
+                }
+                "-h" | "--help" => {
+                    return Err(
+                        "usage: evaluate_decoder --manifest FILE --model FILE --decoder FILE \
+                         [--split test] [--layers 3] [--size 224] [--limit N] \
+                         [--output FILE] [--samples N]"
+                            .to_string(),
+                    );
+                }
+                _ => return Err(format!("unknown argument {flag:?}")),
+            }
+        }
+
+        Ok(Self {
+            manifest: manifest.ok_or("--manifest is required")?,
+            model: model.ok_or("--model is required")?,
+            decoder: decoder.ok_or("--decoder is required")?,
+            split,
+            layers,
+            size,
+            limit,
+            output,
+            samples,
+        })
+    }
+}
+
+#[derive(Serialize)]
+struct PerImage {
+    path: String,
+    source: String,
+    group: String,
+    sha256: String,
+    pixels: usize,
+    mse: f64,
+    mae: f64,
+    psnr_db: f64,
+    ssim: f64,
+}
+
+#[derive(Serialize)]
+struct Distribution {
+    mean: f64,
+    median: f64,
+    p25: f64,
+    p75: f64,
+    min: f64,
+    max: f64,
+}
+
+#[derive(Serialize)]
+struct Summary {
+    count: usize,
+    global_psnr_db: f64,
+    psnr_db: Distribution,
+    ssim: Distribution,
+    mae: Distribution,
+}
+
+#[derive(Serialize)]
+struct Evaluation {
+    schema_version: u32,
+    created_unix_seconds: u64,
+    dataset_name: String,
+    manifest: String,
+    manifest_sha256: String,
+    split: String,
+    image_size: usize,
+    encoder_layers: usize,
+    model: String,
+    model_sha256: String,
+    decoder: String,
+    decoder_sha256: String,
+    elapsed_seconds: f64,
+    summary: Summary,
+    images: Vec<PerImage>,
+}
+
+fn distribution(values: impl IntoIterator<Item = f64>) -> Distribution {
+    let mut values: Vec<f64> = values.into_iter().collect();
+    values.sort_by(f64::total_cmp);
+    let n = values.len();
+    assert!(n > 0);
+    let quantile = |q: f64| {
+        let at = q * (n - 1) as f64;
+        let lo = at.floor() as usize;
+        let hi = at.ceil() as usize;
+        values[lo] + (values[hi] - values[lo]) * (at - lo as f64)
+    };
+    Distribution {
+        mean: values.iter().sum::<f64>() / n as f64,
+        median: quantile(0.5),
+        p25: quantile(0.25),
+        p75: quantile(0.75),
+        min: values[0],
+        max: values[n - 1],
+    }
+}
+
+fn target_chw(rgb: &[u8], size: usize) -> Vec<f32> {
+    let pixels = size * size;
+    let mut target = vec![0.0f32; 3 * pixels];
+    for c in 0..3 {
+        for p in 0..pixels {
+            target[c * pixels + p] = rgb[p * 3 + c] as f32 / 255.0;
+        }
+    }
+    target
+}
+
+fn metrics(recon: &[f32], target: &[f32], size: usize) -> (f64, f64, f64, f64) {
+    let mut squared = 0.0f64;
+    let mut absolute = 0.0f64;
+    for (&a, &b) in recon.iter().zip(target) {
+        let d = (a - b) as f64;
+        squared += d * d;
+        absolute += d.abs();
+    }
+    let mse = squared / recon.len() as f64;
+    let mae = absolute / recon.len() as f64;
+    let psnr = 10.0 * (1.0 / mse).log10();
+    (mse, mae, psnr, ssim_rgb(recon, target, size))
+}
+
+/// RGB SSIM with the conventional 11x11 Gaussian window (sigma 1.5),
+/// computed independently per channel over the valid image region.
+fn ssim_rgb(a: &[f32], b: &[f32], size: usize) -> f64 {
+    const RADIUS: usize = 5;
+    const SIGMA: f64 = 1.5;
+    const C1: f64 = 0.01 * 0.01;
+    const C2: f64 = 0.03 * 0.03;
+    assert!(size > 2 * RADIUS);
+    let mut kernel = [0.0f64; 2 * RADIUS + 1];
+    let mut kernel_sum = 0.0;
+    for (index, weight) in kernel.iter_mut().enumerate() {
+        let x = index as isize - RADIUS as isize;
+        *weight = (-(x * x) as f64 / (2.0 * SIGMA * SIGMA)).exp();
+        kernel_sum += *weight;
+    }
+    for w in &mut kernel {
+        *w /= kernel_sum;
+    }
+
+    let plane = size * size;
+    let valid = size - 2 * RADIUS;
+    let mut total = 0.0;
+    let mut count = 0usize;
+    for c in 0..3 {
+        // Five Gaussian-filtered moments, stored together to reuse both the
+        // input reads and kernel coefficients. The separable implementation
+        // is mathematically equivalent to the 11x11 2-D Gaussian window.
+        let mut horizontal = vec![[0.0f64; 5]; size * valid];
+        for y in 0..size {
+            for x in 0..valid {
+                let mut moments = [0.0f64; 5];
+                for (kx, &weight) in kernel.iter().enumerate() {
+                    let index = c * plane + y * size + x + kx;
+                    let va = a[index] as f64;
+                    let vb = b[index] as f64;
+                    moments[0] += weight * va;
+                    moments[1] += weight * vb;
+                    moments[2] += weight * va * va;
+                    moments[3] += weight * vb * vb;
+                    moments[4] += weight * va * vb;
+                }
+                horizontal[y * valid + x] = moments;
+            }
+        }
+        for y in 0..valid {
+            for x in 0..valid {
+                let mut moments = [0.0f64; 5];
+                for (ky, &weight) in kernel.iter().enumerate() {
+                    for i in 0..5 {
+                        moments[i] += weight * horizontal[(y + ky) * valid + x][i];
+                    }
+                }
+                let [mean_a, mean_b, aa, bb, ab] = moments;
+                let var_a = (aa - mean_a * mean_a).max(0.0);
+                let var_b = (bb - mean_b * mean_b).max(0.0);
+                let covariance = ab - mean_a * mean_b;
+                total += ((2.0 * mean_a * mean_b + C1) * (2.0 * covariance + C2))
+                    / ((mean_a * mean_a + mean_b * mean_b + C1) * (var_a + var_b + C2));
+                count += 1;
+            }
+        }
+    }
+    total / count as f64
+}
+
+fn save_sample(
+    path: &Path,
+    rgb: &[u8],
+    patches: &[f32],
+    encoder_output: &[f32],
+    features: &[f32],
+    recon: &[f32],
+    size: usize,
+) {
+    let mut image = image::RgbImage::new((2 * size) as u32, size as u32);
+    let pixels = size * size;
+    for y in 0..size {
+        for x in 0..size {
+            let p = y * size + x;
+            image.put_pixel(
+                x as u32,
+                y as u32,
+                image::Rgb([rgb[p * 3], rgb[p * 3 + 1], rgb[p * 3 + 2]]),
+            );
+            let value = |c: usize| (recon[c * pixels + p].clamp(0.0, 1.0) * 255.0) as u8;
+            image.put_pixel(
+                (size + x) as u32,
+                y as u32,
+                image::Rgb([value(0), value(1), value(2)]),
+            );
+        }
+    }
+    image.save(path).expect("write reconstruction sample");
+    let stem = path
+        .file_stem()
+        .expect("sample path has a stem")
+        .to_string_lossy();
+    let parent = path.parent().unwrap_or_else(|| Path::new("."));
+    std::fs::write(
+        parent.join(format!("{stem}-patches.f32")),
+        bytemuck::cast_slice(patches),
+    )
+    .expect("write preprocessed patches");
+    std::fs::write(
+        parent.join(format!("{stem}-encoder.f32")),
+        bytemuck::cast_slice(encoder_output),
+    )
+    .expect("write raw encoder output");
+    std::fs::write(
+        parent.join(format!("{stem}-features.f32")),
+        bytemuck::cast_slice(features),
+    )
+    .expect("write raw encoder features");
+    std::fs::write(
+        parent.join(format!("{stem}-reconstruction.f32")),
+        bytemuck::cast_slice(recon),
+    )
+    .expect("write raw reconstruction sample");
+}
+
+fn main() -> Result<(), Box<dyn std::error::Error>> {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+    let args = Args::parse().map_err(|e| format!("{e}"))?;
+    let loaded = common::load_manifest(&args.manifest)?;
+    let dataset_name = loaded.manifest.name.clone();
+    let entries = common::images_for_split(&args.manifest, &args.split, args.limit)?;
+    log::info!(
+        "evaluating {} images from split {:?}",
+        entries.len(),
+        args.split
+    );
+
+    let config = Config::vits16()
+        .at_resolution(args.size)
+        .with_layers(args.layers);
+    let gpu = dinovision::init_context(None).expect("GPU context");
+    let (mut encoder, _) = dinovision::bench::build_encoder_session(gpu.clone(), &config, None);
+    let model = meganeura::data::safetensors::SafeTensorsModel::load(args.model.clone())?;
+    dinovision::weights::load_encoder(&mut encoder, &model, &config)?;
+
+    let feat_len = config.hidden_size * config.num_patches();
+    let img_len = 3 * config.image_size * config.image_size;
+    let mut graph = meganeura::Graph::new();
+    let features = graph.input("feat", &[feat_len]);
+    let reconstruction = decoder::build_decoder(&mut graph, &config, features, 1);
+    graph.set_outputs(vec![reconstruction]);
+    let (mut decoder_session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    decoder::load_parameters(&mut decoder_session, &graph, &args.decoder)?;
+
+    let sample_dir = args
+        .output
+        .parent()
+        .unwrap_or_else(|| Path::new("."))
+        .join("quality_samples");
+    if args.samples > 0 {
+        std::fs::create_dir_all(&sample_dir)?;
+    }
+    if let Some(parent) = args.output.parent()
+        && !parent.as_os_str().is_empty()
+    {
+        std::fs::create_dir_all(parent)?;
+    }
+
+    let start = Instant::now();
+    let total_entries = entries.len();
+    let mut encoder_out = vec![0.0f32; config.num_tokens() * config.hidden_size];
+    let mut recon = vec![0.0f32; img_len];
+    let mut results = Vec::new();
+    let mut total_squared_error = 0.0f64;
+    let mut total_values = 0usize;
+
+    for (index, (path, entry)) in entries.into_iter().enumerate() {
+        common::verify_image(&path, &entry)?;
+        let rgb = common::load_frame(&path, config.image_size as u32)
+            .ok_or_else(|| format!("failed to load {}", path.display()))?;
+        let target = target_chw(&rgb, config.image_size);
+        let patches = dinovision::preprocess::patches_from_rgb8(&rgb, &config);
+        encoder.set_input("patches", &patches);
+        encoder.step();
+        encoder.wait();
+        encoder.read_output_by_index(0, &mut encoder_out);
+        let features = decoder::patch_features_to_nchw(&encoder_out, &config);
+
+        decoder_session.set_input("feat", &features);
+        decoder_session.step();
+        decoder_session.wait();
+        decoder_session.read_output_by_index(0, &mut recon);
+
+        let (mse, mae, psnr_db, ssim) = metrics(&recon, &target, config.image_size);
+        total_squared_error += mse * recon.len() as f64;
+        total_values += recon.len();
+        results.push(PerImage {
+            path: entry.path.to_string_lossy().replace('\\', "/"),
+            source: entry.source,
+            group: entry.group,
+            sha256: entry.sha256,
+            pixels: config.image_size * config.image_size,
+            mse,
+            mae,
+            psnr_db,
+            ssim,
+        });
+
+        if index < args.samples {
+            save_sample(
+                &sample_dir.join(format!("{index:04}.png")),
+                &rgb,
+                &patches,
+                &encoder_out,
+                &features,
+                &recon,
+                config.image_size,
+            );
+        }
+        log::info!(
+            "{}/{}  PSNR {:.2} dB  SSIM {:.4}  {}",
+            index + 1,
+            total_entries,
+            psnr_db,
+            ssim,
+            path.display()
+        );
+    }
+
+    let global_mse = total_squared_error / total_values as f64;
+    let summary = Summary {
+        count: results.len(),
+        global_psnr_db: 10.0 * (1.0 / global_mse).log10(),
+        psnr_db: distribution(results.iter().map(|x| x.psnr_db)),
+        ssim: distribution(results.iter().map(|x| x.ssim)),
+        mae: distribution(results.iter().map(|x| x.mae)),
+    };
+    let evaluation = Evaluation {
+        schema_version: 1,
+        created_unix_seconds: SystemTime::now().duration_since(UNIX_EPOCH)?.as_secs(),
+        dataset_name,
+        manifest: args.manifest.to_string_lossy().replace('\\', "/"),
+        manifest_sha256: common::sha256(&args.manifest)?,
+        split: args.split,
+        image_size: config.image_size,
+        encoder_layers: config.num_hidden_layers,
+        model: args.model.to_string_lossy().replace('\\', "/"),
+        model_sha256: common::sha256(&args.model)?,
+        decoder: args.decoder.to_string_lossy().replace('\\', "/"),
+        decoder_sha256: common::sha256(&args.decoder)?,
+        elapsed_seconds: start.elapsed().as_secs_f64(),
+        summary,
+        images: results,
+    };
+    std::fs::write(&args.output, serde_json::to_vec_pretty(&evaluation)?)?;
+    println!(
+        "wrote {}: {} images, global PSNR {:.2} dB, median SSIM {:.4}",
+        args.output.display(),
+        evaluation.summary.count,
+        evaluation.summary.global_psnr_db,
+        evaluation.summary.ssim.median
+    );
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn reference_ssim(a: &[f32], b: &[f32], size: usize) -> f64 {
+        const RADIUS: isize = 5;
+        const SIGMA: f64 = 1.5;
+        const C1: f64 = 0.01 * 0.01;
+        const C2: f64 = 0.03 * 0.03;
+        let mut kernel = Vec::new();
+        let mut sum = 0.0;
+        for y in -RADIUS..=RADIUS {
+            for x in -RADIUS..=RADIUS {
+                let weight = (-((x * x + y * y) as f64) / (2.0 * SIGMA * SIGMA)).exp();
+                kernel.push(weight);
+                sum += weight;
+            }
+        }
+        kernel.iter_mut().for_each(|weight| *weight /= sum);
+
+        let plane = size * size;
+        let mut total = 0.0;
+        let mut count = 0;
+        for c in 0..3 {
+            for y in RADIUS as usize..size - RADIUS as usize {
+                for x in RADIUS as usize..size - RADIUS as usize {
+                    let mut moments = [0.0f64; 5];
+                    let mut wi = 0;
+                    for ky in -RADIUS..=RADIUS {
+                        for kx in -RADIUS..=RADIUS {
+                            let index = c * plane
+                                + (y as isize + ky) as usize * size
+                                + (x as isize + kx) as usize;
+                            let va = a[index] as f64;
+                            let vb = b[index] as f64;
+                            let weight = kernel[wi];
+                            moments[0] += weight * va;
+                            moments[1] += weight * vb;
+                            moments[2] += weight * va * va;
+                            moments[3] += weight * vb * vb;
+                            moments[4] += weight * va * vb;
+                            wi += 1;
+                        }
+                    }
+                    let [mean_a, mean_b, aa, bb, ab] = moments;
+                    let var_a = (aa - mean_a * mean_a).max(0.0);
+                    let var_b = (bb - mean_b * mean_b).max(0.0);
+                    let covariance = ab - mean_a * mean_b;
+                    total += ((2.0 * mean_a * mean_b + C1) * (2.0 * covariance + C2))
+                        / ((mean_a * mean_a + mean_b * mean_b + C1) * (var_a + var_b + C2));
+                    count += 1;
+                }
+            }
+        }
+        total / count as f64
+    }
+
+    #[test]
+    fn identical_images_have_unit_ssim() {
+        let size = 16;
+        let image: Vec<f32> = (0..3 * size * size)
+            .map(|i| (i % 251) as f32 / 250.0)
+            .collect();
+        assert!((ssim_rgb(&image, &image, size) - 1.0).abs() < 1e-10);
+    }
+
+    #[test]
+    fn separable_ssim_matches_direct_window() {
+        let size = 16;
+        let a: Vec<f32> = (0..3 * size * size)
+            .map(|i| ((i * 37 + 11) % 251) as f32 / 250.0)
+            .collect();
+        let b: Vec<f32> = (0..3 * size * size)
+            .map(|i| ((i * 19 + 7) % 241) as f32 / 240.0)
+            .collect();
+        let expected = reference_ssim(&a, &b, size);
+        let actual = ssim_rgb(&a, &b, size);
+        assert!((actual - expected).abs() < 1e-12, "{actual} vs {expected}");
+    }
+
+    #[test]
+    fn distribution_interpolates_quartiles() {
+        let d = distribution([1.0, 2.0, 3.0, 4.0]);
+        assert_eq!(d.median, 2.5);
+        assert_eq!(d.p25, 1.75);
+        assert_eq!(d.p75, 3.25);
+    }
+}

environment/training-source/source-snapshot/examples/preview.rs

@@ -0,0 +1,138 @@
+//! Run the full pipeline on desktop and write the result as an image.
+//!
+//! Exercises exactly what the headset does — inference worker, PCA fit,
+//! colour projection — minus OpenXR, and writes a side-by-side PPM so the
+//! output can actually be looked at. Rendering a feature view you cannot
+//! see is a poor way to find out it is wrong.
+//!
+//! ```text
+//! cargo run --release --example preview -- [out.ppm] [model.safetensors]
+//! ```
+//!
+//! Without a checkpoint it runs on synthetic weights: the pipeline is
+//! exercised end to end, but the colours mean nothing. With real weights,
+//! regions that belong to the same object should share a colour.
+
+use std::path::PathBuf;
+use std::time::{Duration, Instant};
+
+use dinovision::dinov3::Config;
+use dinovision::inference::{self, Weights};
+use dinovision::pca::COMPONENTS;
+use dinovision::source::{FrameSource, TestPattern};
+
+/// Nearest-neighbour upscale of the feature grid, so each patch reads as a
+/// solid block. Bilinear would look prettier and hide the true resolution.
+fn upscale(grid_rgb: &[f32], grid: usize, out: usize) -> Vec<u8> {
+    let mut px = vec![0u8; out * out * 3];
+    for y in 0..out {
+        let gy = (y * grid) / out;
+        for x in 0..out {
+            let gx = (x * grid) / out;
+            let src = (gy * grid + gx) * COMPONENTS;
+            let dst = (y * out + x) * 3;
+            for c in 0..3 {
+                px[dst + c] = (grid_rgb[src + c].clamp(0.0, 1.0) * 255.0) as u8;
+            }
+        }
+    }
+    px
+}
+
+/// Source on the left, feature view on the right.
+fn write_side_by_side(path: &PathBuf, left: &[u8], right: &[u8], size: usize) {
+    let mut joined = vec![0u8; size * size * 6];
+    for y in 0..size {
+        let src = y * size * 3;
+        let dst = y * size * 6;
+        joined[dst..dst + size * 3].copy_from_slice(&left[src..src + size * 3]);
+        joined[dst + size * 3..dst + size * 6].copy_from_slice(&right[src..src + size * 3]);
+    }
+    image::RgbImage::from_raw(size as u32 * 2, size as u32, joined)
+        .expect("image dimensions do not match buffer")
+        .save(path)
+        .expect("failed to write image");
+}
+
+fn main() {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    let mut args = std::env::args().skip(1);
+    let out_path = PathBuf::from(args.next().unwrap_or_else(|| "preview.png".into()));
+    let weights = match args.next().map(PathBuf::from) {
+        Some(p) if p.exists() => {
+            log::info!("using weights from {}", p.display());
+            Weights::SafeTensors(p)
+        }
+        Some(p) => panic!("{} does not exist", p.display()),
+        None => Weights::Synthetic,
+    };
+
+    let config = Config::vits16().at_resolution(256);
+    let gpu = dinovision::init_context(None).expect("failed to initialize GPU context");
+    let worker = inference::spawn(gpu, config.clone(), weights, None, 1, dinovision::inference::Display::PcaColour);
+
+    // `DINOVISION_SOURCE=screen` grabs the desktop instead of the synthetic
+    // scene, which is the quickest way to see the colouring against real
+    // imagery without opening a window.
+    let mut source: Box<dyn FrameSource> = match std::env::var("DINOVISION_SOURCE").as_deref() {
+        #[cfg(feature = "capture")]
+        Ok("screen") => match dinovision::source::ScreenCapture::new(config.image_size, 0) {
+            Ok(s) => Box::new(s),
+            Err(e) => panic!("screen capture unavailable: {e}"),
+        },
+        #[cfg(not(feature = "capture"))]
+        Ok("screen") => panic!("rebuild with --features capture for screen capture"),
+        _ => Box::new(TestPattern::new(config.image_size)),
+    };
+    let mut last_frame: Vec<u8> = Vec::new();
+
+    // Let the session build, then run a few frames so the PCA basis is
+    // refitted from real features rather than the placeholder.
+    let deadline = Instant::now() + Duration::from_secs(180);
+    let mut completed = 0;
+    while completed < 5 && Instant::now() < deadline {
+        if worker.is_ready() {
+            let rgb = source.next_frame().unwrap();
+            last_frame = rgb.to_vec();
+            let patches = dinovision::preprocess::patches_from_rgb8(rgb, &config);
+            worker.submit(patches);
+        }
+        std::thread::sleep(Duration::from_millis(20));
+        completed = worker.generation();
+    }
+
+    let grid = worker
+        .latest()
+        .expect("inference produced no result before the deadline");
+    log::info!(
+        "{} completed encodes, last took {:.1} ms ({}x{} grid)",
+        completed,
+        grid.latency_ms,
+        grid.grid,
+        grid.grid
+    );
+
+    let size = config.image_size;
+    let features = upscale(grid.patch_rgb(), grid.grid, size);
+    write_side_by_side(&out_path, &last_frame, &features, size);
+
+    // A view that is one flat colour means the projection collapsed, which
+    // is easy to miss by eye in a small image.
+    let spread = {
+        let mut lo = [255u8; 3];
+        let mut hi = [0u8; 3];
+        for px in features.chunks_exact(3) {
+            for c in 0..3 {
+                lo[c] = lo[c].min(px[c]);
+                hi[c] = hi[c].max(px[c]);
+            }
+        }
+        (0..3).map(|c| hi[c] as i32 - lo[c] as i32).max().unwrap()
+    };
+    println!("wrote {} (source | features)", out_path.display());
+    println!("colour spread: {spread}/255");
+    if spread < 16 {
+        println!("WARNING: the feature view is nearly flat — projection may have collapsed");
+    }
+}

environment/training-source/source-snapshot/examples/train_decoder.rs

@@ -0,0 +1,436 @@
+//! Train the DINOv3 feature → RGB decoder, using meganeura for both halves.
+//!
+//! ```text
+//! cargo run --release --example train_decoder -- \
+//!   <dataset-dir-or-manifest> <model.safetensors> \
+//!   [steps] [images] [layers] [size] [seed] [output-dir]
+//! ```
+//!
+//! Two phases. First every image is encoded once and its features cached in
+//! memory, because the encoder is frozen and running it inside the training
+//! loop would cost ~30× the decoder's own forward pass for no gradient.
+//! Then the decoder trains on those pairs with Adam.
+//!
+//! Writes `decoder.bin` — raw f32, parameters in graph declaration order —
+//! next to the working directory, plus a PNG strip of reconstructions so
+//! the result can be judged by eye rather than by loss alone.
+
+use std::path::{Path, PathBuf};
+use std::time::{Instant, SystemTime, UNIX_EPOCH};
+
+use dinovision::decoder;
+use dinovision::dinov3::Config;
+use meganeura::graph::Op;
+use meganeura::train::{Mode, SessionConfig};
+use meganeura::{Graph, Session};
+use serde::Serialize;
+
+mod common;
+
+const BATCH: usize = 8;
+
+fn random_u64(state: &mut u64) -> u64 {
+    *state ^= *state >> 12;
+    *state ^= *state << 25;
+    *state ^= *state >> 27;
+    state.wrapping_mul(0x2545_F491_4F6C_DD1D)
+}
+
+fn seeded_state(base: u64, seed: u64) -> u64 {
+    let state = base ^ seed;
+    if state == 0 {
+        0xA076_1D64_78BD_642F
+    } else {
+        state
+    }
+}
+
+fn shuffle(order: &mut [usize], state: &mut u64) {
+    for i in (1..order.len()).rev() {
+        order.swap(i, random_u64(state) as usize % (i + 1));
+    }
+}
+
+/// Deterministic small init. Kaiming-ish: scaled by fan-in so activations
+/// neither vanish nor explode through four stages.
+fn init_parameters(session: &mut Session, graph: &Graph, seed: u64) {
+    let mut state = seeded_state(0x9E37_79B9_7F4A_7C15, seed);
+    let mut next = move || ((random_u64(&mut state) >> 40) as f32 / (1u32 << 24) as f32) - 0.5;
+    for node in graph.nodes() {
+        let Op::Parameter { name } = &node.op else {
+            continue;
+        };
+        let n = node.ty.num_elements();
+        let shape = &node.ty.shape;
+        let data: Vec<f32> = if name.ends_with("norm.weight") {
+            vec![1.0; n]
+        } else if name.ends_with(".bias") {
+            vec![0.0; n]
+        } else {
+            // shape is [out, in, kh, kw]; fan_in = in * kh * kw.
+            let fan_in: usize = shape.iter().skip(1).product::<usize>().max(1);
+            let scale = (2.0 / fan_in as f32).sqrt() * 2.0;
+            (0..n).map(|_| next() * scale).collect()
+        };
+        session.set_parameter(name, &data);
+    }
+}
+
+#[derive(Serialize)]
+struct TrainingRecord {
+    schema_version: u32,
+    completed_unix_seconds: u64,
+    dataset: String,
+    dataset_manifest_sha256: Option<String>,
+    requested_images: usize,
+    training_images: usize,
+    model: String,
+    model_sha256: String,
+    initialization: String,
+    initialization_sha256: Option<String>,
+    seed: u64,
+    image_size: usize,
+    encoder_layers: usize,
+    batch_size: usize,
+    steps: usize,
+    data_order: &'static str,
+    objective: &'static str,
+    optimizer: &'static str,
+    initial_learning_rate: f32,
+    final_learning_rate: f32,
+    decoder_parameters: usize,
+    encoding_seconds: f64,
+    training_seconds: f64,
+    final_l1: f32,
+    decoder: String,
+    decoder_sha256: String,
+    diagnostic_samples: String,
+}
+
+fn portable_path(path: &Path) -> String {
+    path.to_string_lossy().replace('\\', "/")
+}
+
+fn save_parameters(session: &Session, graph: &Graph, path: &Path) -> std::io::Result<()> {
+    let mut bytes = Vec::new();
+    for node in graph.nodes() {
+        let Op::Parameter { name } = &node.op else {
+            continue;
+        };
+        let mut buf = vec![0.0f32; node.ty.num_elements()];
+        session.read_param(name, &mut buf);
+        bytes.extend_from_slice(bytemuck::cast_slice(&buf));
+    }
+    std::fs::write(path, bytes)
+}
+
+fn main() {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    let mut args = std::env::args().skip(1);
+    let image_dir = PathBuf::from(args.next().expect(
+        "usage: train_decoder <dataset-dir-or-manifest> <model.safetensors> \
+         [steps] [images] [layers] [size] [seed] [output-dir]",
+    ));
+    let weights = PathBuf::from(args.next().expect("need the DINOv3 checkpoint"));
+    let steps: usize = args.next().and_then(|s| s.parse().ok()).unwrap_or(3000);
+    let max_images: usize = args.next().and_then(|s| s.parse().ok()).unwrap_or(2500);
+    // Truncating the encoder is the cheapest way to speed it up on a
+    // headset, and the later layers are where colour gets discarded, so a
+    // shallower encoder may reconstruct better as well as faster.
+    let layers: usize = args.next().and_then(|s| s.parse().ok()).unwrap_or(12);
+    let size: usize = args.next().and_then(|s| s.parse().ok()).unwrap_or(224);
+    let seed: u64 = args.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+    let output_dir = args
+        .next()
+        .map(PathBuf::from)
+        .unwrap_or_else(|| PathBuf::from("."));
+    assert!(steps > 0, "steps must be positive");
+    std::fs::create_dir_all(&output_dir).expect("create output directory");
+
+    let config = Config::vits16().at_resolution(size).with_layers(layers);
+    let gpu = dinovision::init_context(None).expect("GPU context");
+
+    // ---- Phase 1: encode the dataset once ----
+    let paths = if image_dir.extension().and_then(|e| e.to_str()) == Some("json") {
+        common::images_for_split(&image_dir, "train", max_images)
+            .unwrap_or_else(|e| panic!("{}: {e}", image_dir.display()))
+            .into_iter()
+            .map(|(path, image)| {
+                common::verify_image(&path, &image)
+                    .unwrap_or_else(|e| panic!("dataset verification failed: {e}"));
+                path
+            })
+            .collect()
+    } else {
+        common::find_images(&image_dir, max_images)
+    };
+    assert!(!paths.is_empty(), "no images under {}", image_dir.display());
+    log::info!("encoding {} images", paths.len());
+
+    let (mut encoder, _) = dinovision::bench::build_encoder_session(gpu.clone(), &config, None);
+    let model = meganeura::data::safetensors::SafeTensorsModel::load(weights.clone())
+        .expect("read weights");
+    dinovision::weights::load_encoder(&mut encoder, &model, &config).expect("bind weights");
+
+    let feat_len = config.hidden_size * config.num_patches();
+    let img_len = 3 * config.image_size * config.image_size;
+    let mut features: Vec<f32> = Vec::with_capacity(paths.len() * feat_len);
+    // Targets stay u8 and are widened per batch. As f32 the cache would be
+    // 900 KB an image, and a few thousand images then no longer fit in RAM.
+    let mut targets: Vec<u8> = Vec::with_capacity(paths.len() * img_len);
+
+    let start = Instant::now();
+    let mut kept = 0usize;
+    let mut scratch = vec![0.0f32; config.num_tokens() * config.hidden_size];
+    for (i, path) in paths.iter().enumerate() {
+        let Some(rgb) = common::load_frame(path, config.image_size as u32) else {
+            continue;
+        };
+        let patches = dinovision::preprocess::patches_from_rgb8(&rgb, &config);
+        encoder.set_input("patches", &patches);
+        encoder.step();
+        encoder.wait();
+        encoder.read_output_by_index(0, &mut scratch);
+
+        features.extend_from_slice(&decoder::patch_features_to_nchw(&scratch, &config));
+        // Target is plain CHW in [0, 1] — the decoder predicts pixels, not
+        // ImageNet-normalized values.
+        let size = config.image_size;
+        for c in 0..3 {
+            for p in 0..size * size {
+                targets.push(rgb[p * 3 + c]);
+            }
+        }
+        kept += 1;
+        if i % 500 == 0 {
+            log::info!(
+                "  {i}/{} ({:.0}s)",
+                paths.len(),
+                start.elapsed().as_secs_f64()
+            );
+        }
+    }
+    drop(encoder);
+    assert!(kept > 0, "none of the selected images could be decoded");
+    let encoding_seconds = start.elapsed().as_secs_f64();
+    log::info!(
+        "encoded {kept} images in {:.0}s ({:.0} MB cached)",
+        encoding_seconds,
+        (features.len() * 4 + targets.len()) as f64 / 1e6
+    );
+
+    // ---- Phase 2: train the decoder ----
+    let mut g = Graph::new();
+    let feat_in = g.input("feat", &[BATCH * feat_len]);
+    let recon = decoder::build_decoder(&mut g, &config, feat_in, BATCH);
+    let target_in = g.input("target", &[BATCH * img_len]);
+    // L1 rather than MSE. Squared error optimises the conditional mean, so
+    // wherever a feature is ambiguous the decoder hedges by averaging every
+    // possibility, which is blur by construction. L1 optimises the median
+    // and commits to one answer, usually looking markedly sharper at the
+    // same PSNR.
+    let loss = g.l1_loss(recon, target_in);
+    g.set_outputs(vec![loss, recon]);
+
+    let (mut session, _) = meganeura::train::build(
+        &g,
+        SessionConfig {
+            mode: Mode::Training,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    // `DINOVISION_INIT=decoder.bin` continues from existing weights instead
+    // of starting over. Necessary when adapting to a few hundred captured
+    // frames: 2M parameters trained from scratch on that much data would
+    // simply memorise it, where fine-tuning shifts an already-general
+    // decoder onto the new distribution.
+    let (initialization, initialization_sha256) = match std::env::var("DINOVISION_INIT") {
+        Ok(path) => {
+            let path = PathBuf::from(path);
+            decoder::load_parameters(&mut session, &g, &path)
+                .unwrap_or_else(|e| panic!("could not load {}: {e}", path.display()));
+            log::info!("fine-tuning from {}", path.display());
+            let digest = common::sha256(&path).expect("hash initial decoder");
+            (portable_path(&path), Some(digest))
+        }
+        Err(_) => {
+            init_parameters(&mut session, &g, seed);
+            ("random".to_string(), None)
+        }
+    };
+    session.set_adam(2e-3, 0.9, 0.999, 1e-8);
+    log::info!(
+        "training {} decoder parameters for {steps} steps, batch {BATCH}, encoder depth {layers}, \
+         resolution {size}, seed {seed}",
+        decoder::parameter_count(&config)
+    );
+
+    let mut feat_batch = vec![0.0f32; BATCH * feat_len];
+    let mut target_batch = vec![0.0f32; BATCH * img_len];
+    let mut order: Vec<usize> = (0..kept).collect();
+    let mut shuffle_state = seeded_state(0xD1B5_4A32_D192_ED03, seed);
+    shuffle(&mut order, &mut shuffle_state);
+    let mut cursor = 0usize;
+    let train_start = Instant::now();
+    let mut final_l1 = f32::NAN;
+    let mut final_learning_rate = 2e-3;
+
+    for step in 0..steps {
+        for b in 0..BATCH {
+            if cursor == kept {
+                shuffle(&mut order, &mut shuffle_state);
+                cursor = 0;
+            }
+            let idx = order[cursor];
+            cursor += 1;
+            feat_batch[b * feat_len..(b + 1) * feat_len]
+                .copy_from_slice(&features[idx * feat_len..(idx + 1) * feat_len]);
+            for (dst, &src) in target_batch[b * img_len..(b + 1) * img_len]
+                .iter_mut()
+                .zip(&targets[idx * img_len..(idx + 1) * img_len])
+            {
+                *dst = src as f32 / 255.0;
+            }
+        }
+        session.set_input("feat", &feat_batch);
+        session.set_input("target", &target_batch);
+        // Linear decay: the last stretch matters for sharpness, and a
+        // constant rate leaves the reconstruction visibly noisier.
+        let progress = step as f32 / steps as f32;
+        final_learning_rate = 2e-3 * (1.0 - progress).max(0.05);
+        session.set_adam(final_learning_rate, 0.9, 0.999, 1e-8);
+        session.step();
+        session.wait();
+
+        if step % 100 == 0 || step == steps - 1 {
+            final_l1 = session.read_loss();
+            log::info!(
+                "step {step:>5}  L1 {final_l1:.5}  ({:.0}s)",
+                train_start.elapsed().as_secs_f64()
+            );
+        }
+    }
+    let training_seconds = train_start.elapsed().as_secs_f64();
+
+    let decoder_path = output_dir.join("decoder.bin");
+    save_parameters(&session, &g, &decoder_path).expect("write decoder.bin");
+    log::info!("wrote {}", decoder_path.display());
+
+    // ---- Sample strip: original above, reconstruction below ----
+    let size = config.image_size;
+    for b in 0..BATCH {
+        let idx = b % kept;
+        feat_batch[b * feat_len..(b + 1) * feat_len]
+            .copy_from_slice(&features[idx * feat_len..(idx + 1) * feat_len]);
+        for (dst, &src) in target_batch[b * img_len..(b + 1) * img_len]
+            .iter_mut()
+            .zip(&targets[idx * img_len..(idx + 1) * img_len])
+        {
+            *dst = src as f32 / 255.0;
+        }
+    }
+    session.set_input("feat", &feat_batch);
+    session.step();
+    session.wait();
+    let mut recon_out = vec![0.0f32; BATCH * img_len];
+    session.read_output_by_index(1, &mut recon_out);
+
+    let cols = 6.min(BATCH);
+    let mut strip = image::RgbImage::new((cols * size) as u32, (2 * size) as u32);
+    let mut total_psnr = 0.0;
+    for b in 0..cols {
+        let t = &target_batch[b * img_len..(b + 1) * img_len];
+        let r = &recon_out[b * img_len..(b + 1) * img_len];
+        total_psnr += decoder::psnr(r, t);
+        for y in 0..size {
+            for x in 0..size {
+                let at = |src: &[f32], c: usize| {
+                    (src[c * size * size + y * size + x].clamp(0.0, 1.0) * 255.0) as u8
+                };
+                strip.put_pixel(
+                    (b * size + x) as u32,
+                    y as u32,
+                    image::Rgb([at(t, 0), at(t, 1), at(t, 2)]),
+                );
+                strip.put_pixel(
+                    (b * size + x) as u32,
+                    (size + y) as u32,
+                    image::Rgb([at(r, 0), at(r, 1), at(r, 2)]),
+                );
+            }
+        }
+    }
+    let samples_path = output_dir.join("decoder_samples.png");
+    strip.save(&samples_path).expect("write samples");
+    let manifest_sha256 = (image_dir.extension().and_then(|e| e.to_str()) == Some("json"))
+        .then(|| common::sha256(&image_dir).expect("hash dataset manifest"));
+    let record = TrainingRecord {
+        schema_version: 1,
+        completed_unix_seconds: SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .expect("system time before Unix epoch")
+            .as_secs(),
+        dataset: portable_path(&image_dir),
+        dataset_manifest_sha256: manifest_sha256,
+        requested_images: max_images,
+        training_images: kept,
+        model: portable_path(&weights),
+        model_sha256: common::sha256(&weights).expect("hash encoder model"),
+        initialization,
+        initialization_sha256,
+        seed,
+        image_size: config.image_size,
+        encoder_layers: config.num_hidden_layers,
+        batch_size: BATCH,
+        steps,
+        data_order: "seeded Fisher-Yates; reshuffled after every complete pass",
+        objective: "mean absolute error (L1)",
+        optimizer: "Adam(beta1=0.9,beta2=0.999,epsilon=1e-8), linear learning-rate decay",
+        initial_learning_rate: 2e-3,
+        final_learning_rate,
+        decoder_parameters: decoder::parameter_count(&config),
+        encoding_seconds,
+        training_seconds,
+        final_l1,
+        decoder: portable_path(&decoder_path),
+        decoder_sha256: common::sha256(&decoder_path).expect("hash trained decoder"),
+        diagnostic_samples: portable_path(&samples_path),
+    };
+    let record_path = output_dir.join("training.json");
+    std::fs::write(
+        &record_path,
+        serde_json::to_vec_pretty(&record).expect("serialize training record"),
+    )
+    .expect("write training record");
+    println!(
+        "wrote {} and {}\nin-sample diagnostic mean PSNR {:.2} dB",
+        samples_path.display(),
+        record_path.display(),
+        total_psnr / cols as f32
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn shuffle_is_seeded_and_preserves_every_index() {
+        let run = |seed| {
+            let mut order: Vec<usize> = (0..100).collect();
+            let mut state = seeded_state(0xD1B5_4A32_D192_ED03, seed);
+            shuffle(&mut order, &mut state);
+            order
+        };
+        let a = run(7);
+        let b = run(7);
+        let c = run(8);
+        assert_eq!(a, b);
+        assert_ne!(a, c);
+        let mut sorted = a;
+        sorted.sort_unstable();
+        assert_eq!(sorted, (0..100).collect::<Vec<_>>());
+    }
+}

environment/training-source/source-snapshot/examples/verify.rs

@@ -0,0 +1,638 @@
+//! Compare our encoder against the HuggingFace reference, on desktop.
+//!
+//! ViT numerics are unforgiving: a transposed weight, a wrong RoPE pairing,
+//! or a misordered patch flattening all produce output that looks
+//! statistically reasonable and is completely wrong. This has to pass
+//! before anything is deployed, because diagnosing it through logcat is
+//! miserable.
+//!
+//! Inputs come from `tools/dump_reference.py`, which writes the *already
+//! preprocessed* pixel tensor alongside the expected features. Taking the
+//! pixel tensor verbatim keeps image resizing out of the comparison, so a
+//! failure here is a failure in the graph.
+//!
+//! ```text
+//! python tools/dump_reference.py --out ref/
+//! cargo run --release --bin verify -- ref/ [model.safetensors]
+//! ```
+
+use std::path::{Path, PathBuf};
+
+use dinovision::dinov3::Config;
+use meganeura::Graph;
+use meganeura::train::{Mode, SessionConfig};
+use serde::{Deserialize, Serialize};
+
+mod common;
+
+#[derive(Serialize)]
+struct Verification {
+    schema_version: u32,
+    model_sha256: String,
+    pixel_values_sha256: String,
+    reference_features_sha256: String,
+    meganeura_features_sha256: String,
+    elements: usize,
+    relative_l2: f64,
+    max_absolute_error: f32,
+    worst_absolute_token: usize,
+    cls_cosine: f32,
+    worst_patch_cosine: f32,
+    thresholds: Thresholds,
+    passed: bool,
+}
+
+#[derive(Deserialize)]
+struct ReferenceMetadata {
+    image_size: usize,
+    encoder_layers: usize,
+}
+
+#[derive(Serialize)]
+struct Thresholds {
+    max_relative_l2: f64,
+    min_cls_cosine: f32,
+    min_patch_cosine: f32,
+}
+
+fn read_f32(path: &Path) -> Vec<f32> {
+    let bytes = std::fs::read(path).unwrap_or_else(|e| panic!("{}: {e}", path.display()));
+    assert_eq!(
+        bytes.len() % 4,
+        0,
+        "{} is not a whole number of f32 values",
+        path.display()
+    );
+    bytes
+        .chunks_exact(4)
+        .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
+        .collect()
+}
+
+fn embedding_forward(
+    gpu: std::sync::Arc<blade_graphics::Context>,
+    config: &Config,
+    model: &meganeura::data::safetensors::SafeTensorsModel,
+    patches: &[f32],
+) -> Vec<f32> {
+    let hidden = config.hidden_size;
+    let prefix = config.num_prefix_tokens();
+    let mut graph = Graph::new();
+    let input = graph.input("patches", &[config.num_patches(), config.patch_dim()]);
+    let weight = graph.parameter(
+        "embeddings.patch_embeddings.weight",
+        &[config.patch_dim(), hidden],
+    );
+    let bias = graph.parameter("embeddings.patch_embeddings.bias", &[hidden]);
+    let patch_embeddings = graph.matmul(input, weight);
+    let patch_embeddings = graph.bias_add(patch_embeddings, bias);
+    let prefix_tokens = graph.parameter("prefix_tokens", &[prefix, hidden]);
+    let output = graph.concat(
+        prefix_tokens,
+        patch_embeddings,
+        1,
+        (prefix * hidden) as u32,
+        (config.num_patches() * hidden) as u32,
+        1,
+    );
+    let output = graph.reshape(output, &[config.num_tokens(), hidden]);
+    graph.set_outputs(vec![output]);
+
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    let convolution = model
+        .tensor_f32_auto("embeddings.patch_embeddings.weight")
+        .expect("load patch embedding weight");
+    session.set_parameter(
+        "embeddings.patch_embeddings.weight",
+        &dinovision::preprocess::conv_weight_to_matmul(&convolution, hidden, config.patch_dim()),
+    );
+    session.set_parameter(
+        "embeddings.patch_embeddings.bias",
+        &model
+            .tensor_f32_auto("embeddings.patch_embeddings.bias")
+            .expect("load patch embedding bias"),
+    );
+    let mut prefix_data = model
+        .tensor_f32_auto("embeddings.cls_token")
+        .expect("load CLS token");
+    prefix_data.extend(
+        model
+            .tensor_f32_auto("embeddings.register_tokens")
+            .expect("load register tokens"),
+    );
+    session.set_parameter("prefix_tokens", &prefix_data);
+    session.set_input("patches", patches);
+    session.step();
+    session.wait();
+    session.read_output(config.num_tokens() * hidden)
+}
+
+fn first_projections(
+    gpu: std::sync::Arc<blade_graphics::Context>,
+    config: &Config,
+    model: &meganeura::data::safetensors::SafeTensorsModel,
+    embeddings: &[f32],
+) -> [Vec<f32>; 4] {
+    let hidden = config.hidden_size;
+    let mut graph = Graph::new();
+    let input = graph.input("embeddings", &[config.num_tokens(), hidden]);
+    let norm_weight = graph.parameter("layer.0.norm1.weight", &[hidden]);
+    let norm_bias = graph.parameter("layer.0.norm1.bias", &[hidden]);
+    let normalized = graph.layer_norm(input, norm_weight, norm_bias, config.layer_norm_eps);
+    let mut projections = Vec::new();
+    for (name, has_bias) in [("q_proj", true), ("k_proj", false), ("v_proj", true)] {
+        let weight = graph.parameter(
+            &format!("layer.0.attention.{name}.weight"),
+            &[hidden, hidden],
+        );
+        let projected = graph.matmul(normalized, weight);
+        let projected = if has_bias {
+            let bias = graph.parameter(&format!("layer.0.attention.{name}.bias"), &[hidden]);
+            graph.bias_add(projected, bias)
+        } else {
+            projected
+        };
+        projections.push(projected);
+    }
+    graph.set_outputs(vec![
+        normalized,
+        projections[0],
+        projections[1],
+        projections[2],
+    ]);
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    let prefix = if model
+        .tensor_info()
+        .contains_key("model.layer.0.norm1.weight")
+    {
+        "model."
+    } else {
+        ""
+    };
+    for part in ["weight", "bias"] {
+        session.set_parameter(
+            &format!("layer.0.norm1.{part}"),
+            &model
+                .tensor_f32_auto(&format!("{prefix}layer.0.norm1.{part}"))
+                .expect("load first norm"),
+        );
+    }
+    for (name, has_bias) in [("q_proj", true), ("k_proj", false), ("v_proj", true)] {
+        session.set_parameter(
+            &format!("layer.0.attention.{name}.weight"),
+            &model
+                .tensor_f32_auto_transposed(&format!("{prefix}layer.0.attention.{name}.weight"))
+                .expect("load first projection"),
+        );
+        if has_bias {
+            session.set_parameter(
+                &format!("layer.0.attention.{name}.bias"),
+                &model
+                    .tensor_f32_auto(&format!("{prefix}layer.0.attention.{name}.bias"))
+                    .expect("load first projection bias"),
+            );
+        }
+    }
+    session.set_input("embeddings", embeddings);
+    session.step();
+    session.wait();
+    std::array::from_fn(|index| {
+        let mut output = vec![0.0; config.num_tokens() * hidden];
+        session.read_output_by_index(index, &mut output);
+        output
+    })
+}
+
+fn first_attention(
+    gpu: std::sync::Arc<blade_graphics::Context>,
+    config: &Config,
+    q: &[f32],
+    k: &[f32],
+    v: &[f32],
+) -> [Vec<f32>; 3] {
+    let tokens = config.num_tokens();
+    let heads = config.num_attention_heads;
+    let head_dim = config.head_dim();
+    let hidden = config.hidden_size;
+    let mut graph = Graph::new();
+    let q_node = graph.input("q", &[tokens, hidden]);
+    let k_node = graph.input("k", &[tokens, hidden]);
+    let v_node = graph.input("v", &[tokens, hidden]);
+    let (cos_data, sin_data) = dinovision::dinov3::rope_tables(config);
+    let cos = graph.constant(cos_data, &[tokens, hidden]);
+    let sin = graph.constant(sin_data, &[tokens, hidden]);
+    let apply_rope = |graph: &mut Graph, input| {
+        let blocks = tokens as u32 * heads;
+        let half = head_dim / 2;
+        let first = graph.split_a(input, blocks, half, half, 1);
+        let second = graph.split_b(input, blocks, half, half, 1);
+        let negative_second = graph.neg(second);
+        let rotated = graph.concat(negative_second, first, blocks, half, half, 1);
+        let rotated = graph.reshape(rotated, &[tokens, hidden]);
+        let straight = graph.mul(input, cos);
+        let crossed = graph.mul(rotated, sin);
+        graph.add(straight, crossed)
+    };
+    let q_rope = apply_rope(&mut graph, q_node);
+    let k_rope = apply_rope(&mut graph, k_node);
+    let attention = graph.full_attention(q_rope, k_rope, v_node, heads, heads, head_dim);
+    graph.set_outputs(vec![q_rope, k_rope, attention]);
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    session.set_input("q", q);
+    session.set_input("k", k);
+    session.set_input("v", v);
+    session.step();
+    session.wait();
+    std::array::from_fn(|index| {
+        let mut output = vec![0.0; tokens * hidden];
+        session.read_output_by_index(index, &mut output);
+        output
+    })
+}
+
+fn first_remainder(
+    gpu: std::sync::Arc<blade_graphics::Context>,
+    config: &Config,
+    model: &meganeura::data::safetensors::SafeTensorsModel,
+    embeddings: &[f32],
+    attention: &[f32],
+) -> Vec<Vec<f32>> {
+    let tokens = config.num_tokens();
+    let hidden = config.hidden_size;
+    let intermediate = config.intermediate_size;
+    let mut graph = Graph::new();
+    let embeddings_node = graph.input("embeddings", &[tokens, hidden]);
+    let attention_node = graph.input("attention", &[tokens, hidden]);
+    let output_weight = graph.parameter("layer.0.attention.o_proj.weight", &[hidden, hidden]);
+    let output_bias = graph.parameter("layer.0.attention.o_proj.bias", &[hidden]);
+    let attention_projected = graph.matmul(attention_node, output_weight);
+    let attention_projected = graph.bias_add(attention_projected, output_bias);
+    let scale1 = graph.parameter("layer.0.layer_scale1.lambda1", &[hidden]);
+    let transposed = graph.transpose(attention_projected);
+    let flat = graph.reshape(transposed, &[hidden * tokens]);
+    let scaled = graph.mul_per_channel(flat, scale1, hidden as u32, tokens as u32);
+    let scaled = graph.reshape(scaled, &[hidden, tokens]);
+    let attention_scaled = graph.transpose(scaled);
+    let residual = graph.add(embeddings_node, attention_scaled);
+
+    let norm2_weight = graph.parameter("layer.0.norm2.weight", &[hidden]);
+    let norm2_bias = graph.parameter("layer.0.norm2.bias", &[hidden]);
+    let norm2 = graph.layer_norm(residual, norm2_weight, norm2_bias, config.layer_norm_eps);
+    let up_weight = graph.parameter("layer.0.mlp.up_proj.weight", &[hidden, intermediate]);
+    let up_bias = graph.parameter("layer.0.mlp.up_proj.bias", &[intermediate]);
+    let mlp_up = graph.matmul(norm2, up_weight);
+    let mlp_up = graph.bias_add(mlp_up, up_bias);
+    let mlp_activated = graph.gelu(mlp_up);
+    let down_weight = graph.parameter("layer.0.mlp.down_proj.weight", &[intermediate, hidden]);
+    let down_bias = graph.parameter("layer.0.mlp.down_proj.bias", &[hidden]);
+    let mlp_down = graph.matmul(mlp_activated, down_weight);
+    let mlp_down = graph.bias_add(mlp_down, down_bias);
+    let scale2 = graph.parameter("layer.0.layer_scale2.lambda1", &[hidden]);
+    let transposed = graph.transpose(mlp_down);
+    let flat = graph.reshape(transposed, &[hidden * tokens]);
+    let scaled = graph.mul_per_channel(flat, scale2, hidden as u32, tokens as u32);
+    let scaled = graph.reshape(scaled, &[hidden, tokens]);
+    let mlp_scaled = graph.transpose(scaled);
+    let layer_output = graph.add(residual, mlp_scaled);
+    let final_weight = graph.parameter("norm.weight", &[hidden]);
+    let final_bias = graph.parameter("norm.bias", &[hidden]);
+    let final_norm = graph.layer_norm(
+        layer_output,
+        final_weight,
+        final_bias,
+        config.layer_norm_eps,
+    );
+    graph.set_outputs(vec![
+        attention_projected,
+        attention_scaled,
+        residual,
+        norm2,
+        mlp_up,
+        mlp_activated,
+        mlp_down,
+        mlp_scaled,
+        layer_output,
+        final_norm,
+    ]);
+
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    let prefix = if model
+        .tensor_info()
+        .contains_key("model.layer.0.norm1.weight")
+    {
+        "model."
+    } else {
+        ""
+    };
+    for name in [
+        "attention.o_proj.weight",
+        "mlp.up_proj.weight",
+        "mlp.down_proj.weight",
+    ] {
+        session.set_parameter(
+            &format!("layer.0.{name}"),
+            &model
+                .tensor_f32_auto_transposed(&format!("{prefix}layer.0.{name}"))
+                .expect("load first-layer matrix"),
+        );
+    }
+    for name in [
+        "attention.o_proj.bias",
+        "layer_scale1.lambda1",
+        "norm2.weight",
+        "norm2.bias",
+        "mlp.up_proj.bias",
+        "mlp.down_proj.bias",
+        "layer_scale2.lambda1",
+    ] {
+        session.set_parameter(
+            &format!("layer.0.{name}"),
+            &model
+                .tensor_f32_auto(&format!("{prefix}layer.0.{name}"))
+                .expect("load first-layer vector"),
+        );
+    }
+    for part in ["weight", "bias"] {
+        session.set_parameter(
+            &format!("norm.{part}"),
+            &model
+                .tensor_f32_auto(&format!("norm.{part}"))
+                .expect("load final norm"),
+        );
+    }
+    session.set_input("embeddings", embeddings);
+    session.set_input("attention", attention);
+    session.step();
+    session.wait();
+    [
+        hidden,
+        hidden,
+        hidden,
+        hidden,
+        intermediate,
+        intermediate,
+        hidden,
+        hidden,
+        hidden,
+        hidden,
+    ]
+    .into_iter()
+    .enumerate()
+    .map(|(index, width)| {
+        let mut output = vec![0.0; tokens * width];
+        session.read_output_by_index(index, &mut output);
+        output
+    })
+    .collect()
+}
+
+fn relative_l2(actual: &[f32], expected: &[f32]) -> f64 {
+    let squared_error: f64 = actual
+        .iter()
+        .zip(expected)
+        .map(|(a, b)| (*a as f64 - *b as f64).powi(2))
+        .sum();
+    let squared_reference: f64 = expected.iter().map(|x| (*x as f64).powi(2)).sum();
+    squared_error.sqrt() / squared_reference.sqrt().max(f64::MIN_POSITIVE)
+}
+
+fn main() {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    let mut args = std::env::args().skip(1);
+    let ref_dir = PathBuf::from(
+        args.next()
+            .expect("usage: verify <reference-dir> [model.safetensors]"),
+    );
+    let weights_path = args
+        .next()
+        .map(PathBuf::from)
+        .unwrap_or_else(|| ref_dir.join("model.safetensors"));
+
+    let pixels = read_f32(&ref_dir.join("pixel_values.bin"));
+    let expected = read_f32(&ref_dir.join("features.bin"));
+    let reference: ReferenceMetadata = serde_json::from_slice(
+        &std::fs::read(ref_dir.join("reference.json")).expect("read reference.json"),
+    )
+    .expect("parse reference.json");
+
+    // Infer the resolution from the pixel tensor rather than assuming it,
+    // so the reference script can dump any supported size.
+    let side = ((pixels.len() / 3) as f64).sqrt() as usize;
+    assert_eq!(
+        3 * side * side,
+        pixels.len(),
+        "pixel tensor is not 3 x N x N"
+    );
+    assert_eq!(
+        side, reference.image_size,
+        "pixel tensor resolution disagrees with reference.json"
+    );
+    let config = Config::vits16()
+        .at_resolution(side)
+        .with_layers(reference.encoder_layers);
+    log::info!(
+        "reference: {side}x{side} -> {}x{} grid, {} tokens",
+        config.grid(),
+        config.grid(),
+        config.num_tokens()
+    );
+    assert_eq!(
+        expected.len(),
+        config.num_tokens() * config.hidden_size,
+        "expected features should be [{}, {}]",
+        config.num_tokens(),
+        config.hidden_size
+    );
+
+    let gpu = dinovision::init_context(None).expect("failed to initialize GPU context");
+
+    let model = meganeura::data::safetensors::SafeTensorsModel::load(weights_path.clone())
+        .unwrap_or_else(|e| panic!("{}: {e}", weights_path.display()));
+    let patches = dinovision::preprocess::patches_from_pixels_chw(&pixels, &config);
+    let expected_embeddings = read_f32(&ref_dir.join("embeddings.bin"));
+    let actual_embeddings = embedding_forward(gpu.clone(), &config, &model, &patches);
+    println!(
+        "embedding relative L2 : {:.6}",
+        relative_l2(&actual_embeddings, &expected_embeddings)
+    );
+    let actual_first = first_projections(gpu.clone(), &config, &model, &actual_embeddings);
+    for (label, actual, file) in [
+        ("first norm1", &actual_first[0], "first-norm1.bin"),
+        ("first Q", &actual_first[1], "first-q.bin"),
+        ("first K", &actual_first[2], "first-k.bin"),
+        ("first V", &actual_first[3], "first-v.bin"),
+    ] {
+        println!(
+            "{label:<18}: {:.6}",
+            relative_l2(actual, &read_f32(&ref_dir.join(file)))
+        );
+    }
+    let actual_attention = first_attention(
+        gpu.clone(),
+        &config,
+        &actual_first[1],
+        &actual_first[2],
+        &actual_first[3],
+    );
+    for (label, actual, file) in [
+        ("first Q RoPE", &actual_attention[0], "first-q-rope.bin"),
+        ("first K RoPE", &actual_attention[1], "first-k-rope.bin"),
+        (
+            "first attention",
+            &actual_attention[2],
+            "first-attention.bin",
+        ),
+    ] {
+        println!(
+            "{label:<18}: {:.6}",
+            relative_l2(actual, &read_f32(&ref_dir.join(file)))
+        );
+    }
+    let actual_remainder = first_remainder(
+        gpu.clone(),
+        &config,
+        &model,
+        &actual_embeddings,
+        &actual_attention[2],
+    );
+    for (index, (label, file)) in [
+        ("attention projected", "first-attention-projected.bin"),
+        ("attention scaled", "first-attention-scaled.bin"),
+        ("attention residual", "first-residual.bin"),
+        ("first norm2", "first-norm2.bin"),
+        ("first MLP up", "first-mlp-up.bin"),
+        ("first MLP GELU", "first-mlp-activated.bin"),
+        ("first MLP down", "first-mlp-down.bin"),
+        ("first MLP scaled", "first-mlp-scaled.bin"),
+        ("first output", "first-output.bin"),
+        ("first final norm", "first-final-norm.bin"),
+    ]
+    .into_iter()
+    .enumerate()
+    {
+        println!(
+            "{label:<20}: {:.6}",
+            relative_l2(&actual_remainder[index], &read_f32(&ref_dir.join(file)))
+        );
+    }
+
+    let (mut session, _) = dinovision::bench::build_encoder_session(gpu, &config, None);
+    dinovision::weights::load_encoder(&mut session, &model, &config).expect("load weights");
+
+    session.set_input("patches", &patches);
+    session.step();
+    session.wait();
+
+    let got = session.read_output(config.num_tokens() * config.hidden_size);
+
+    // Report both absolute error and cosine similarity per token group.
+    // Cosine matters more for what we do downstream: PCA colouring and a
+    // decoder both care about feature *direction*, and a uniform scale
+    // error would still look right while indicating a real bug.
+    let mut worst_abs = 0.0f32;
+    let mut worst_token = 0usize;
+    let mut squared_error = 0.0f64;
+    let mut squared_reference = 0.0f64;
+    for t in 0..config.num_tokens() {
+        for d in 0..config.hidden_size {
+            let i = t * config.hidden_size + d;
+            let difference = got[i] - expected[i];
+            let e = difference.abs();
+            squared_error += (difference as f64).powi(2);
+            squared_reference += (expected[i] as f64).powi(2);
+            if e > worst_abs {
+                worst_abs = e;
+                worst_token = t;
+            }
+        }
+    }
+    let relative_l2 = squared_error.sqrt() / squared_reference.sqrt().max(f64::MIN_POSITIVE);
+
+    let cosine = |a: &[f32], b: &[f32]| -> f32 {
+        let dot: f32 = a.iter().zip(b).map(|(x, y)| x * y).sum();
+        let na: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
+        let nb: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
+        dot / (na * nb).max(f32::MIN_POSITIVE)
+    };
+
+    let h = config.hidden_size;
+    let cls_cos = cosine(&got[0..h], &expected[0..h]);
+    let mut worst_patch_cos = 1.0f32;
+    for t in config.num_prefix_tokens()..config.num_tokens() {
+        let c = cosine(&got[t * h..(t + 1) * h], &expected[t * h..(t + 1) * h]);
+        worst_patch_cos = worst_patch_cos.min(c);
+    }
+
+    println!("relative L2           : {relative_l2:.6}");
+    println!("max |ours - reference| : {worst_abs:.5} (worst at token {worst_token})");
+    println!("CLS cosine             : {cls_cos:.6}");
+    println!("worst patch cosine     : {worst_patch_cos:.6}");
+
+    // f32 GPU accumulation in a different order than PyTorch's will not
+    // reproduce bit-for-bit; 0.999 cosine across every patch is the real
+    // signal that the architecture is right.
+    let thresholds = Thresholds {
+        max_relative_l2: 0.01,
+        min_cls_cosine: 0.999,
+        min_patch_cosine: 0.999,
+    };
+    let ok = relative_l2 <= thresholds.max_relative_l2
+        && worst_patch_cos > thresholds.min_patch_cosine
+        && cls_cos > thresholds.min_cls_cosine;
+    let got_path = ref_dir.join("meganeura_features.bin");
+    std::fs::write(&got_path, bytemuck::cast_slice(&got)).expect("write Meganeura features");
+    let verification = Verification {
+        schema_version: 1,
+        model_sha256: common::sha256(&weights_path).expect("hash model"),
+        pixel_values_sha256: common::sha256(&ref_dir.join("pixel_values.bin")).expect("hash input"),
+        reference_features_sha256: common::sha256(&ref_dir.join("features.bin"))
+            .expect("hash reference"),
+        meganeura_features_sha256: common::sha256(&got_path).expect("hash Meganeura output"),
+        elements: got.len(),
+        relative_l2,
+        max_absolute_error: worst_abs,
+        worst_absolute_token: worst_token,
+        cls_cosine: cls_cos,
+        worst_patch_cosine: worst_patch_cos,
+        thresholds,
+        passed: ok,
+    };
+    std::fs::write(
+        ref_dir.join("verification.json"),
+        serde_json::to_vec_pretty(&verification).expect("serialize verification"),
+    )
+    .expect("write verification record");
+    println!("\n{}", if ok { "PASS" } else { "FAIL" });
+    if !ok {
+        std::process::exit(1);
+    }
+}

environment/training-source/source-snapshot/examples/viewer.rs

@@ -0,0 +1,288 @@
+//! Live DINO feature view in a desktop window.
+//!
+//! The same pipeline the headset runs — capture, encode, PCA colour,
+//! display — pointed at a monitor instead of a passthrough camera. Two
+//! reasons it exists:
+//!
+//! * It is the demo you can actually show someone. Point it at a video, a
+//!   photo, a game, and watch objects resolve into stable colour regions.
+//! * It de-risks the Quest camera. The capture loop, the downscale, and the
+//!   "new frame arrives asynchronously while the window redraws" structure
+//!   are all the same; the passthrough camera becomes another
+//!   `FrameSource` and nothing around it changes.
+//!
+//! ```text
+//! cargo run --release --features capture --example viewer -- [model.safetensors] [monitor]
+//! ```
+//!
+//! Without a checkpoint it runs on synthetic weights, which still shows the
+//! scene's structure but colours it arbitrarily.
+
+use std::sync::Arc;
+use std::time::{Duration, Instant};
+
+use blade_graphics as gpu;
+use dinovision::dinov3::Config;
+use dinovision::inference::{self, Weights, Worker};
+use dinovision::render::GridView;
+use dinovision::source::FrameSource;
+
+fn surface_config(size: winit::dpi::PhysicalSize<u32>) -> gpu::SurfaceConfig {
+    gpu::SurfaceConfig {
+        size: gpu::Extent {
+            width: size.width.max(1),
+            height: size.height.max(1),
+            depth: 1,
+        },
+        usage: gpu::TextureUsage::TARGET,
+        display_sync: gpu::DisplaySync::Recent,
+        ..Default::default()
+    }
+}
+
+struct Viewer {
+    context: Arc<gpu::Context>,
+    surface: gpu::Surface,
+    encoder: gpu::CommandEncoder,
+    view: GridView,
+    worker: Worker,
+    source: Box<dyn FrameSource>,
+    config: Config,
+    last_shown: u64,
+    frames: u64,
+    encodes: u64,
+    last_report: Instant,
+    window: winit::window::Window,
+}
+
+impl Viewer {
+    fn redraw(&mut self) {
+        // Feed the encoder whenever it is free. Unlike the headset there is
+        // no compositor to starve here, so it runs flat out.
+        if self.worker.is_ready()
+            && let Some(rgb) = self.source.next_frame()
+        {
+            let patches = dinovision::preprocess::patches_from_rgb8(rgb, &self.config);
+            self.worker.submit(patches);
+        }
+
+        let generation = self.worker.generation();
+        if generation != self.last_shown
+            && let Some(grid) = self.worker.latest()
+        {
+            self.view.upload(&self.context, grid.patch_rgb());
+            self.last_shown = generation;
+            self.encodes += 1;
+        }
+
+        let frame = self.surface.acquire_frame();
+        self.encoder.start();
+        self.encoder.init_texture(frame.texture());
+        {
+            let mut pass = self.encoder.render("view", gpu::RenderTargetSet {
+                colors: &[gpu::RenderTarget {
+                    view: frame.texture_view(),
+                    init_op: gpu::InitOp::DontCare,
+                    finish_op: gpu::FinishOp::Store,
+                }],
+                depth_stencil: None,
+            });
+            self.view.draw(&mut pass, 0);
+        }
+        self.encoder.present(frame);
+        let _sp = self.context.submit(&mut self.encoder);
+
+        self.frames += 1;
+        if self.last_report.elapsed() >= Duration::from_secs(3) {
+            let secs = self.last_report.elapsed().as_secs_f64();
+            let latency = self
+                .worker
+                .latest()
+                .map(|g| g.latency_ms)
+                .unwrap_or(f64::NAN);
+            self.window.set_title(&format!(
+                "dinovision — {:.0} fps display, {:.1} Hz inference ({:.0} ms)",
+                self.frames as f64 / secs,
+                self.encodes as f64 / secs,
+                latency
+            ));
+            self.frames = 0;
+            self.encodes = 0;
+            self.last_report = Instant::now();
+        }
+    }
+}
+
+#[derive(Default)]
+struct App {
+    viewer: Option<Viewer>,
+    weights: Option<std::path::PathBuf>,
+    decoder: Option<std::path::PathBuf>,
+    monitor: usize,
+}
+
+impl winit::application::ApplicationHandler for App {
+    fn resumed(&mut self, event_loop: &winit::event_loop::ActiveEventLoop) {
+        if self.viewer.is_some() {
+            return;
+        }
+        let window = event_loop
+            .create_window(
+                winit::window::Window::default_attributes()
+                    .with_title("dinovision — starting…")
+                    .with_inner_size(winit::dpi::LogicalSize::new(720, 720)),
+            )
+            .expect("failed to create window");
+
+        let context = Arc::new(unsafe {
+            gpu::Context::init(gpu::ContextDesc {
+                presentation: true,
+                validation: false,
+                ..Default::default()
+            })
+            .expect("failed to initialize GPU context")
+        });
+
+        let surface = context
+            .create_surface_configured(&window, surface_config(window.inner_size()))
+            .expect("failed to create surface");
+
+        let config = Config::vits16().at_resolution(224);
+        // A reconstruction fills the whole image, so the display grid is the
+        // image size; PCA colouring only has one value per patch.
+        let display = match self.decoder.clone() {
+            Some(path) => {
+                log::info!("decoder: {}", path.display());
+                inference::Display::Reconstruction(path)
+            }
+            None => inference::Display::PcaColour,
+        };
+        let view_grid = match &display {
+            inference::Display::Reconstruction(_) => config.image_size,
+            inference::Display::PcaColour => config.grid(),
+        };
+        let view = GridView::new(&context, surface.info().format, view_grid);
+
+        let weights = match self.weights.clone() {
+            Some(p) => {
+                log::info!("weights: {}", p.display());
+                Weights::SafeTensors(p)
+            }
+            None => {
+                log::warn!("no checkpoint given — synthetic weights, colours are arbitrary");
+                Weights::Synthetic
+            }
+        };
+        // One submission: nothing else is competing for this GPU, so the
+        // chunking that matters on a headset would only cost overhead.
+        let worker = inference::spawn(Arc::clone(&context), config.clone(), weights, None, 1, display);
+
+        let source: Box<dyn FrameSource> = match dinovision::source::ScreenCapture::new(
+            config.image_size,
+            self.monitor,
+        ) {
+            Ok(s) => Box::new(s),
+            Err(e) => {
+                log::warn!("screen capture unavailable ({e}); falling back to the test pattern");
+                Box::new(dinovision::source::TestPattern::new(config.image_size))
+            }
+        };
+
+        let encoder = context.create_command_encoder(gpu::CommandEncoderDesc {
+            name: "viewer",
+            buffer_count: 2,
+            manual_barriers: false,
+        });
+
+        self.viewer = Some(Viewer {
+            context,
+            surface,
+            encoder,
+            view,
+            worker,
+            source,
+            config,
+            last_shown: 0,
+            frames: 0,
+            encodes: 0,
+            last_report: Instant::now(),
+            window,
+        });
+    }
+
+    fn about_to_wait(&mut self, _event_loop: &winit::event_loop::ActiveEventLoop) {
+        if let Some(v) = &self.viewer {
+            v.window.request_redraw();
+        }
+    }
+
+    fn window_event(
+        &mut self,
+        event_loop: &winit::event_loop::ActiveEventLoop,
+        _id: winit::window::WindowId,
+        event: winit::event::WindowEvent,
+    ) {
+        let Some(viewer) = self.viewer.as_mut() else {
+            return;
+        };
+        match event {
+            winit::event::WindowEvent::CloseRequested => event_loop.exit(),
+            winit::event::WindowEvent::KeyboardInput {
+                event:
+                    winit::event::KeyEvent {
+                        physical_key: winit::keyboard::PhysicalKey::Code(code),
+                        state: winit::event::ElementState::Pressed,
+                        ..
+                    },
+                ..
+            } => match code {
+                winit::keyboard::KeyCode::Escape => event_loop.exit(),
+                // Refit the colour basis on demand: point the capture at
+                // something new and the old principal components will be a
+                // poor fit for it.
+                winit::keyboard::KeyCode::KeyR => {
+                    log::info!("refitting colour basis");
+                    viewer.worker.request_refit();
+                }
+                _ => {}
+            },
+            winit::event::WindowEvent::Resized(size) => {
+                viewer
+                    .context
+                    .reconfigure_surface(&mut viewer.surface, surface_config(size));
+            }
+            winit::event::WindowEvent::RedrawRequested => viewer.redraw(),
+            _ => {}
+        }
+    }
+}
+
+fn main() {
+    env_logger::Builder::from_env(env_logger::Env::default().default_filter_or("info")).init();
+
+    let mut args = std::env::args().skip(1);
+    let weights = args.next().map(std::path::PathBuf::from).filter(|p| {
+        let ok = p.exists();
+        if !ok {
+            log::warn!("{} does not exist; using synthetic weights", p.display());
+        }
+        ok
+    });
+    // A decoder file switches the view from PCA colour to a real RGB
+    // reconstruction.
+    let decoder = args.next().map(std::path::PathBuf::from).filter(|p| p.exists());
+    let monitor = args.next().and_then(|s| s.parse().ok()).unwrap_or(0);
+
+    println!("R refits the colour basis · Esc quits");
+
+    let event_loop = winit::event_loop::EventLoop::new().expect("failed to create event loop");
+    event_loop.set_control_flow(winit::event_loop::ControlFlow::Poll);
+    event_loop
+        .run_app(&mut App {
+            viewer: None,
+            weights,
+            decoder,
+            monitor,
+        })
+        .expect("event loop failed");
+}

environment/training-source/source-snapshot/experiments/AUDIT.md

@@ -0,0 +1,74 @@
+# Audit record for the Meganeura case study
+
+Date: 2026-08-01 (America/Los_Angeles)
+
+## Decision
+
+The original `REPORT.md` is not admissible as paper evidence. It is a useful
+engineering narrative, but several headline results were either evaluated on
+training examples, measured with a biased timing protocol, or produced by an
+incorrect DINOv3 graph. The case study can become paper material after the
+corrected decoder training and Quest measurements in `experiments/README.md`
+are complete.
+
+The defensible case-study claim is deliberately narrow:
+
+> A decoder graph is trained through Meganeura autodiff and Adam on the host,
+> then its forward path is joined to a frozen DINOv3 encoder and compiled by
+> the same Meganeura graph compiler/runtime for Vulkan inference in an Android
+> XR application sharing Blade's graphics context and queue.
+
+Training caches frozen encoder features and executes a batched decoder-only
+graph. Deployment executes a batch-one joined encoder/decoder graph. They
+share decoder construction, parameters, IR operations, compiler, and runtime;
+they are not literally the same complete graph.
+
+## Findings that invalidate historical numbers
+
+| Historical evidence | Audit finding | Disposition |
+|---|---|---|
+| Decoder PSNR in `REPORT.md` | The trainer reconstructed the first six cached training images and averaged their PSNR. There was no held-out split, per-image record, or seed replication. | Replaced by an upstream-defined Imagenette validation split, all 3,925 images, per-image PSNR/SSIM/MAE, exact hashes, and three initializations. |
+| Isolated device timings | The benchmark used one untimed warmup and reported the minimum retained sample as throughput. Clock ramp and process-to-process state were not controlled. | Rerun with at least five warmups, 20 retained samples, median/IQR/raw samples, and three fresh processes in a declared headset state. |
+| DINOv3 encoder correctness | The app passed `[tokens, hidden]` data to Meganeura's NCHW-flat `mul_per_channel` as if it broadcast over the trailing dimension. Only the first token received the intended LayerScale update; later token residual branches were effectively suppressed. | Fixed by transposing to `[hidden, tokens]`, flattening for the NCHW operator, applying the hidden gain with `spatial=tokens`, reshaping, and transposing back. All old decoders and device timings are invalid. |
+| Live XR “inference Hz” | Two asynchronous eye completions were combined into one count, and the raw-camera toggle still submitted hidden inference. | App records each eye independently and true raw-camera mode bypasses the model. |
+| 240-pixel, f16, and operation-share conclusions | These were microbenchmark observations or extrapolations, not matched end-to-end experiments or a deployed-graph profile. | Exclude causal or “closed” claims unless the matched experiments are run. |
+
+The invalid pre-fix decoder runs are preserved locally under
+`C:\tmp\dinovision-runs`; they must not be uploaded or cited. The corrected
+matrix uses a separate root so no artifact can be mistaken for a valid run.
+
+## Independent encoder validation after the fix
+
+The reference is `facebook/dinov3-vits16-pretrain-lvd1689m`, executed in
+Torch 2.13.0+cpu and Transformers 5.14.1 from the same deterministic normalized
+pixel tensor and exact checkpoint. Meganeura uses f32 scalar matmul on the RTX
+3050 for this comparison. Thresholds were declared before the corrected run:
+relative L2 at most 0.01, CLS cosine above 0.999, and every patch-token cosine
+above 0.999.
+
+| Depth | Relative L2 | CLS cosine | Worst patch cosine | Result |
+|---:|---:|---:|---:|---|
+| 1 layer | 0.000781 | 1.000000 | 0.999990 | pass |
+| 3 layers (deployed) | 0.001403 | 1.000000 | 0.999995 | pass |
+| 12 layers (upstream depth) | 0.002253 | 0.999997 | 0.999996 | pass |
+
+At the first layer, embeddings, LayerNorm, Q/K/V projections, and RoPE agree
+to the displayed six decimal places. Attention differs by 0.005852 relative
+L2; after learned LayerScale the residual differs by 0.000566. Exact-shape
+tests independently compare Meganeura attention and the corrected trailing
+LayerScale broadcast against CPU implementations.
+
+## Evidence still required
+
+- Three corrected decoder initializations and full held-out photo metrics.
+- A public decoder artifact whose metadata binds it to the corrected source,
+  DINO checkpoint hash, dataset-manifest hash, depth, resolution, and seed.
+- Host/Quest equality on preprocessed patches, encoder features, spatial
+  decoder input, and reconstruction for one fixed public frame.
+- Fresh isolated Quest timings and live-worn XR chunk sweep from the corrected
+  graph, with raw samples and state snapshots.
+- Clean, immutable DinoVision and Meganeura revisions. The current worktree is
+  a development freeze candidate, not yet a citable revision.
+
+Until those items are complete, the correct paper status is **promising but
+not merge-ready**.

environment/training-source/source-snapshot/experiments/README.md

@@ -0,0 +1,163 @@
+# DinoVision paper artifact protocol
+
+This experiment is a deployment case study for Meganeura, not an additional
+cell in the paper's matched Meganeura/PyTorch performance-portability matrix.
+Its claim is narrower and complementary:
+
+> One Meganeura graph definition trains an RGB decoder through autodiff on an
+> RTX GPU and deploys its forward path, joined to a DINOv3 encoder, through the
+> same compiler and Vulkan runtime on an Adreno-based Android XR device. The
+> application shares Blade's graphics context and queue with inference.
+
+The artifact must distinguish that demonstrated claim from hypotheses about
+decoder quality, f16 arithmetic, zero-copy integration, or camera perception.
+
+## Frozen revisions and assets
+
+Every run directory contains:
+
+- clean full Git revisions for DinoVision, Meganeura, and the Blade revision
+  selected by Cargo;
+- `Cargo.lock`, `cargo tree`, Rust/NDK/ADB versions, GPU/driver, Horizon build,
+  refresh configuration, thermal state, and all runtime toggle values;
+- SHA-256 hashes for the upstream DINO checkpoint and each decoder;
+- the immutable dataset manifest and the exact command line;
+- raw timing or per-image records, followed by separately generated summary
+  tables and figures.
+
+The canonical DINO checkpoint remains an upstream dependency rather than being
+duplicated. Meta's DINOv3 License permits redistribution only under that
+agreement and requires a copy of it, a prominent “Built with DINOv3” notice,
+and acknowledgment in resulting research. The artifact links to the gated
+canonical model and preserves its hash. Decoder weights are treated
+conservatively as DINOv3-derived: their model repository carries the DINOv3
+agreement and notice rather than presenting the weights as unconditionally
+MIT-licensed. The DinoVision source remains MIT. Generated decoder weights are
+published with their architecture, depth, resolution, dataset-manifest hash,
+and training metadata.
+
+## Dataset validity
+
+Generate `dataset.json` with `tools/make_dataset_manifest.py`. A `group` is a
+leakage boundary: one headset capture session, room/lighting traversal, or
+photo collection. A group may occur in exactly one of `train`, `validation`,
+and `test`. Identical file hashes may not cross splits.
+
+The paper-quality dataset should contain at least:
+
+- an Imagenette/photo training source;
+- multiple independent headset capture sessions for training;
+- held-out capture sessions from different trajectories and lighting for
+  validation and test;
+- a separately reported held-out photo split, so domain adaptation is not
+  hidden inside one aggregate.
+
+Sequential camera frames must never be randomly divided across splits.
+Create each capture group under its own immutable session name by writing that
+name into the device's `capture` flag before launching the app, for example
+`echo room-a-01 > /data/local/tmp/dinovision/capture`. The app refuses to
+overwrite a non-empty session directory.
+
+## Reconstruction evaluation
+
+Use `examples/evaluate_decoder.rs`. It verifies all input hashes and emits
+per-image MSE, MAE, PSNR, and RGB SSIM, plus global PSNR and distributions.
+The sample PNGs place the target on the left and reconstruction on the right;
+the same directory retains raw preprocessed patches, the full encoder output,
+the spatial decoder input, and decoder output for numerical cross-device
+comparison.
+
+The deployment artifact repeats its selected `3 layers @ 224` cell with three
+decoder initializations. If the report retains comparative depth or resolution
+claims, extend that into this matched matrix, again with three seeds per cell:
+
+| Encoder | Resolution | Decoder | Purpose |
+|---|---:|---|---|
+| 12 layers | 224 | early two-stage blend | official final representation |
+| 3 layers | 224 | early two-stage blend | deployed latency choice |
+| 3 layers | 240 | retargeted and retrained | test the tail-waste hypothesis end to end |
+
+If the report retains claims about L1, constant learning rate, or the number of
+blend stages, those become matched ablations under the same manifests and
+seeds. Otherwise they are described as implementation choices, not findings.
+
+Example:
+
+```powershell
+python tools/make_dataset_manifest.py `
+  --root C:\Data\dinovision `
+  --output experiments\dataset.json `
+  --entry train photo imagenette-train imagenette\train `
+  --entry train capture room-a captures\room-a `
+  --entry test capture room-b captures\room-b
+
+cargo run --release --example evaluate_decoder -- `
+  --manifest experiments\dataset.json `
+  --model model.safetensors --decoder decoder.bin `
+  --split test --layers 3 --output artifacts\quality-3l-224.json
+```
+
+Training uses a deterministic, seed-controlled shuffle and writes its decoder,
+diagnostic strip, and `training.json` into the requested output directory:
+
+```powershell
+cargo run --release --example train_decoder -- `
+  experiments\dataset.json model.safetensors `
+  12000 2500 3 224 0 artifacts\train-3l-224-seed0
+```
+
+## Timing validity
+
+Isolated native benchmarks and live-XR co-tenancy are separate experiments.
+
+For isolated kernel/encoder timings:
+
+- use five or more untimed warmups and at least 20 retained synchronized
+  samples;
+- report median, IQR, minimum, maximum, and every raw sample;
+- stabilize the headset in one power/display state before the matrix;
+- randomize or bracket variants rather than relying on monotonic clock ramp;
+- repeat the matrix in at least three fresh processes.
+
+For the XR application, retain every `DINOVISION_APP_JSON` record and report:
+
+- application render-submission rate;
+- each eye's independent update rate and the lower of the two rates;
+- per-worker wall latency, explicitly not capture-to-photon latency;
+- mono/stereo, chunk count, inference interval, display refresh, and duration.
+
+Sweep `submission_chunks = 1, 2, 4, 8, 12, 16` at a fixed interval in the
+predeclared order `4, 16, 1, 12, 2, 8`, rather than coupling chunk count to
+startup or thermal drift. Report both isolated throughput cost and live
+render/update tradeoff. Run long enough to expose sustained thermal behavior.
+App submission rate must not be called compositor or display rate.
+
+## Correctness
+
+Before performance or quality results are admitted:
+
+1. run the Hugging Face reference comparison and retain its tensors/output;
+2. run the same fixed raw image and weights through `evaluate_decoder` on RTX
+   and Adreno, retaining `*-patches.f32`, `*-encoder.f32`, `*-features.f32`,
+   and `*-reconstruction.f32`;
+3. report relative output L2, maximum absolute error, and per-token cosine;
+4. confirm decoder output agreement across the two devices;
+5. run `cargo test --workspace --all-targets`, with the real-weight semantic
+   test enabled rather than silently skipped.
+
+Use `tools/compare_f32.py` for each host/device tensor pair. It records both
+input hashes, relative L2, cosine similarity, mean/max absolute error, and the
+explicit pass thresholds rather than relying on a console-only comparison.
+
+## Interpretation rules
+
+- A microbenchmark may explain a hypothesis, but only a profile of the
+  deployed graph may assign wall time to an operation class.
+- f16 weight storage says nothing conclusive about unimplemented f16
+  arithmetic.
+- The 240-pixel encoder result is not an end-to-end result until its decoder,
+  preprocessing, readback, and rendering path are included.
+- Direct GPU output is future work until output lifetime, EMA, layout, and
+  synchronization are implemented and measured.
+- Stereo fusion, comfort, camera rate, and capture-to-photon claims require
+  timestamps/calibration or are labeled single-user observations.

environment/training-source/source-snapshot/huggingface/DINOv3-LICENSE.md

@@ -0,0 +1,66 @@
+# DINOv3 License
+
+*Last Updated: August 19, 2025*
+
+**“Agreement”** means the terms and conditions for use, reproduction, distribution and modification of the DINO Materials set forth herein.
+
+**“DINO Materials”** means, collectively, Documentation and the models, software and algorithms, including machine-learning model code, trained model weights, inference-enabling code, training-enabling code, fine-tuning enabling code, and other elements of the foregoing distributed by Meta and made available under this Agreement.
+
+**“Documentation”** means the specifications, manuals and documentation accompanying
+DINO Materials distributed by Meta.
+
+**“Licensee”** or **“you”** means you, or your employer or any other person or entity (if you are entering into this Agreement on such person or entity’s behalf), of the age required under applicable laws, rules or regulations to provide legal consent and that has legal authority to bind your employer or such other person or entity if you are entering in this Agreement on their behalf.
+
+**“Meta”** or **“we”** means Meta Platforms Ireland Limited (if you are located in or, if you are an entity, your principal place of business is in the EEA or Switzerland) or Meta Platforms, Inc. (if you are located outside of the EEA or Switzerland).
+
+**“Sanctions”** means any economic or trade sanctions or restrictions administered or enforced by the United States (including the Office of Foreign Assets Control of the U.S. Department of the Treasury (“OFAC”), the U.S. Department of State and the U.S. Department of Commerce), the United Nations, the European Union, or the United Kingdom.
+
+**“Trade Controls”** means any of the following: Sanctions and applicable export and import controls.
+
+By clicking “I Accept” below or by using or distributing any portion or element of the DINO Materials, you agree to be bound by this Agreement.
+
+## 1. License Rights and Redistribution.
+
+a. <ins>Grant of Rights</ins>. You are granted a non-exclusive, worldwide, non-transferable and royalty-free limited license under Meta’s intellectual property or other rights owned by Meta embodied in the DINO Materials to use, reproduce, distribute, copy, create derivative works of, and make modifications to the DINO Materials.
+
+b. <ins>Redistribution and Use</ins>.
+
+i. Distribution of DINO Materials, and any derivative works thereof, are subject to the terms of this Agreement. If you distribute or make the DINO Materials, or any derivative works thereof, available to a third party, you may only do so under the terms of this Agreement and you shall provide a copy of this Agreement with any such DINO Materials.
+
+ii.  If you submit for publication the results of research you perform on, using, or otherwise in connection with DINO Materials, you must acknowledge the use of DINO Materials in your publication.
+
+iii. Your use of the DINO Materials must comply with applicable laws and regulations, including Trade Control Laws and applicable privacy and data protection laws.
+
+iv. Your use of the DINO Materials will not involve or encourage others to reverse engineer, decompile or discover the underlying components of the DINO Materials.
+
+v. You are not the target of Trade Controls and your use of DINO Materials must comply with Trade Controls. You agree not to use, or permit others to use, DINO Materials for any activities subject to the International Traffic in Arms Regulations (ITAR) or end uses prohibited by Trade Controls, including those related to military or warfare purposes, nuclear industries or applications, espionage, or the development or use of guns or illegal weapons.
+
+## 2. User Support.
+
+Your use of the DINO Materials is done at your own discretion; Meta does not process any information nor provide any service in relation to such use.  Meta is under no obligation to provide any support services for the DINO Materials. Any support provided is “as is”, “with all faults”, and without warranty of any kind.
+
+## 3. Disclaimer of Warranty.
+
+UNLESS REQUIRED BY APPLICABLE LAW, THE DINO MATERIALS AND ANY OUTPUT AND RESULTS THEREFROM ARE PROVIDED ON AN “AS IS” BASIS, WITHOUT WARRANTIES OF ANY KIND, AND META DISCLAIMS ALL WARRANTIES OF ANY KIND, BOTH EXPRESS AND IMPLIED, INCLUDING, WITHOUT LIMITATION, ANY WARRANTIES OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. YOU ARE SOLELY RESPONSIBLE FOR DETERMINING THE APPROPRIATENESS OF USING OR REDISTRIBUTING THE DINO MATERIALS AND ASSUME ANY RISKS ASSOCIATED WITH YOUR USE OF THE DINO MATERIALS AND ANY OUTPUT AND RESULTS.
+
+## 4. Limitation of Liability.
+
+IN NO EVENT WILL META OR ITS AFFILIATES BE LIABLE UNDER ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, TORT, NEGLIGENCE, PRODUCTS LIABILITY, OR OTHERWISE, ARISING OUT OF THIS AGREEMENT, FOR ANY LOST PROFITS OR ANY DIRECT OR INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL, EXEMPLARY OR PUNITIVE DAMAGES, EVEN IF META OR ITS AFFILIATES HAVE BEEN ADVISED OF THE POSSIBILITY OF ANY OF THE FOREGOING.
+
+## 5. Intellectual Property.
+
+a. Subject to Meta’s ownership of DINO Materials and derivatives made by or for Meta, with respect to any derivative works and modifications of the DINO Materials that are made by you, as between you and Meta, you are and will be the owner of such derivative works and modifications.
+
+b. If you institute litigation or other proceedings against Meta or any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the DINO Materials, outputs or results, or any portion of any of the foregoing, constitutes infringement of intellectual property or other rights owned or licensable by you, then any licenses granted to you under this Agreement shall terminate as of the date such litigation or claim is filed or instituted. You will indemnify and hold harmless Meta from and against any claim by any third party arising out of or related to your use or distribution of the DINO Materials.
+
+## 6. Term and Termination.
+
+The term of this Agreement will commence upon your acceptance of this Agreement or access to the DINO Materials and will continue in full force and effect until terminated in accordance with the terms and conditions herein. Meta may terminate this Agreement if you are in breach of any term or condition of this Agreement. Upon termination of this Agreement, you shall delete and cease use of the DINO Materials. Sections 3, 4 and 7 shall survive the termination of this Agreement.
+
+## 7. Governing Law and Jurisdiction.
+
+This Agreement will be governed and construed under the laws of the State of California without regard to choice of law principles, and the UN Convention on Contracts for the International Sale of Goods does not apply to this Agreement. The courts of California shall have exclusive jurisdiction of any dispute arising out of this Agreement.
+
+## 8. Modifications and Amendments.
+
+Meta may modify this Agreement from time to time; provided that they are similar in spirit to the current version of the Agreement, but may differ in detail to address new problems or concerns. All such changes will be effective immediately. Your continued use of the DINO Materials after any modification to this Agreement constitutes your agreement to such modification. Except as provided in this Agreement, no modification or addition to any provision of this Agreement will be binding unless it is in writing and signed by an authorized representative of both you and Meta.

environment/training-source/source-snapshot/huggingface/NOTICE.md

@@ -0,0 +1,17 @@
+# Built with DINOv3
+
+The DinoVision decoder weights were trained from features produced by Meta's
+DINOv3 ViT-S/16 checkpoint. The encoder checkpoint is not redistributed in
+this artifact. Obtain it from the canonical gated repository and comply with
+the DINOv3 License included as `DINOv3-LICENSE.md`.
+
+DinoVision source code is MIT-licensed. The learned decoder weights are
+treated conservatively as DINOv3-derived and distributed under the DINOv3
+agreement.
+
+`DINOv3-LICENSE.md` is the upstream DINOv3 repository's agreement (SHA-256
+`25d122eb8f5b880fd23c736fb6ea8018ee45c12237e00b8a86d14c653904999e`).
+Meta may amend the agreement; consult the
+[current official terms](https://ai.meta.com/resources/models-and-libraries/dinov3-license/)
+as well. The live terms require the prominent notice above in addition to a
+copy of the agreement and acknowledgment in research publications.

environment/training-source/source-snapshot/huggingface/README.md

@@ -0,0 +1,131 @@
+---
+license: other
+license_name: DINOv3 License
+license_link: https://ai.meta.com/resources/models-and-libraries/dinov3-license/
+library_name: meganeura
+pipeline_tag: image-to-image
+base_model: facebook/dinov3-vits16-pretrain-lvd1689m
+tags:
+- dinov3
+- meganeura
+- vulkan
+- android
+- image-reconstruction
+---
+
+# DinoVision decoder
+
+> **Built with DINOv3**
+
+This repository contains the RGB decoder weights and audited records for the
+DinoVision Meganeura case study. The decoder is trained on the host with
+Meganeura autodiff and Adam, then joined to a frozen three-layer DINOv3
+ViT-S/16 encoder for Vulkan inference on Android XR.
+
+The artifact is not a standalone Hugging Face image-to-image pipeline. Use it
+with [DinoVision](https://github.com/kvark/dinovision) and
+[Meganeura](https://github.com/kvark/meganeura).
+
+## Required base model
+
+The Meta encoder checkpoint is deliberately not duplicated here. Obtain the
+gated
+[`facebook/dinov3-vits16-pretrain-lvd1689m`](https://huggingface.co/facebook/dinov3-vits16-pretrain-lvd1689m)
+checkpoint after accepting its terms.
+
+| Item | Value |
+|---|---|
+| Encoder checkpoint SHA-256 | `4610ad75edef83e75afdebf162d148dc628045ea6cbb83d67d4708c709c4f91d` |
+| Encoder depth | first 3 of 12 layers |
+| Input | normalized RGB, 224 by 224 |
+| Encoder patch grid | 14 by 14, 384 channels |
+| Decoder parameters | 2,012,547 |
+| Decoder output | RGB, 224 by 224, sigmoid range |
+
+## Selected artifact
+
+Seed 0 is selected by a rule fixed before validation; it is not selected as
+the best of the three runs.
+
+<!-- CORRECTED_RESULTS_START -->
+
+Corrected three-seed quality results will be inserted here after the frozen
+matrix completes. No pre-audit decoder is published.
+
+<!-- CORRECTED_RESULTS_END -->
+
+`decoder.bin` is the runtime format: little-endian f32 parameters in
+Meganeura graph-declaration order. `decoder.safetensors` contains the same
+values as 26 named tensors and records the encoder depth, resolution, seed,
+base-model hash, and dataset-manifest hash. The SafeTensors conversion checks
+every tensor for exact round-trip equality.
+
+## Training and evaluation
+
+Each replicate uses 2,500 class-interleaved Imagenette training images (250
+from each of ten classes),
+12,000 batch-8 updates, mean absolute error, and Adam with a linearly decayed
+learning rate from 0.002 to 0.0001 over the first 95% of updates and a 0.0001
+floor thereafter. Seeds independently control parameter initialization and
+data order.
+
+Evaluation processes all 3,925 images in the upstream Imagenette validation
+split. Every file is verified against an immutable manifest. The artifact
+retains per-image MSE, MAE, PSNR, and RGB SSIM (11 by 11 Gaussian window,
+sigma 1.5), plus aggregate distributions. Training wall time is excluded as a
+performance result because the interactive host was not controlled.
+
+The previous DinoVision graph misapplied DINOv3 LayerScale and is invalid.
+The corrected three-layer Meganeura encoder was compared with an independent
+Torch 2.13.0+cpu / Transformers 5.14.1 execution of the canonical checkpoint:
+
+| Depth | Relative L2 | CLS cosine | Worst patch cosine |
+|---:|---:|---:|---:|
+| 3 layers | 0.001403 | 1.000000 | 0.999995 |
+| 12 layers | 0.002253 | 0.999997 | 0.999996 |
+
+## File layout
+
+- `decoder.bin`, `decoder.safetensors`, `training.json`: selected seed 0.
+- `replicates/`: all seeded decoder weights and immutable training records.
+- `quality/`: per-image held-out records and generated aggregate summaries.
+- `manifests/`: public dataset and correctness manifests.
+- `correctness/`: independent-implementation and host/device numerical checks.
+- `benchmarks/`: raw and summarized corrected Quest measurements, when present.
+- `environment/`: source/revision, dependency, toolchain, and device metadata.
+
+Target/reconstruction PNGs from Imagenette are not redistributed. Private
+headset captures are also excluded. The fixed synthetic correctness frame is
+public and is included with its hash.
+
+## Intended use and limitations
+
+These weights support research reproduction of a systems case study. They are
+not intended for photographic restoration, surveillance, identity inference,
+medical use, or safety-critical perception. Reconstruction quality is
+evaluated on held-out photographs, not independent headset capture sessions.
+Worker latency is not capture-to-photon latency, and the artifact does not
+claim a PyTorch-on-Android speedup.
+
+## License and acknowledgment
+
+The DinoVision source code is MIT-licensed. These learned weights are treated
+conservatively as DINOv3-derived and distributed under the included
+`DINOv3-LICENSE.md`. Use of the required base model and these artifacts is
+subject to that agreement. Research using this artifact must acknowledge
+DINOv3; see the canonical model card for the official citation. The included
+agreement is preserved byte-for-byte from the upstream DINOv3 repository; the
+[live Meta terms](https://ai.meta.com/resources/models-and-libraries/dinov3-license/)
+should also be consulted because they may be amended.
+
+```bibtex
+@misc{simeoni2025dinov3,
+  title         = {{DINOv3}},
+  author        = {Sim{\'e}oni, Oriane and Vo, Huy V. and Seitzer, Maximilian and others},
+  year          = {2025},
+  eprint        = {2508.10104},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.CV},
+  url           = {https://arxiv.org/abs/2508.10104}
+}
+```

environment/training-source/source-snapshot/src/bench.rs

@@ -0,0 +1,472 @@
+//! Throughput measurement, shared by the desktop and on-device entry
+//! points.
+//!
+//! The question this exists to answer: the Adreno in a Quest 3 is not
+//! expected to expose `VK_KHR_cooperative_matrix`, so meganeura will fall
+//! back to its register-tiled scalar matmul. Whether the encoder then
+//! lands at 20 ms or 200 ms per frame decides the input resolution, the
+//! inference rate, and whether the render loop has to be decoupled from
+//! inference (it almost certainly does).
+//!
+//! Everything here reports achieved GFLOP/s next to the theoretical MAC
+//! count, so a number that looks fast can be checked against what the
+//! device could possibly do.
+
+use std::sync::Arc;
+use std::time::Instant;
+
+use meganeura::graph::Op;
+use meganeura::train::{Mode, SessionConfig};
+use meganeura::{Graph, Session};
+
+use crate::dinov3::Config;
+
+/// One timing result.
+#[derive(Debug, Clone)]
+pub struct Timing {
+    pub label: String,
+    /// Minimum retained sample. Useful diagnostically, but not the primary
+    /// result: selecting the minimum biases comparisons on a noisy device.
+    pub best_ms: f64,
+    pub mean_ms: f64,
+    pub median_ms: f64,
+    pub p25_ms: f64,
+    pub p75_ms: f64,
+    pub max_ms: f64,
+    /// Every retained synchronized wall-time observation.
+    pub samples_ms: Vec<f64>,
+    /// Multiply-accumulates per iteration, for the GFLOP/s figure.
+    pub macs: u64,
+}
+
+impl Timing {
+    /// Median achieved GFLOP/s, counting a multiply-accumulate as two
+    /// operations.
+    pub fn gflops(&self) -> f64 {
+        (self.macs as f64 * 2.0) / (self.median_ms / 1000.0) / 1e9
+    }
+
+    /// One self-contained JSON record suitable for retaining from logcat.
+    pub fn json_line(&self) -> String {
+        let label = self.label.replace('\\', "\\\\").replace('"', "\\\"");
+        let samples = self
+            .samples_ms
+            .iter()
+            .map(|v| format!("{v:.6}"))
+            .collect::<Vec<_>>()
+            .join(",");
+        format!(
+            "{{\"schema_version\":1,\"kind\":\"dinovision_benchmark\",\
+             \"label\":\"{label}\",\"macs\":{},\"median_ms\":{:.6},\
+             \"p25_ms\":{:.6},\"p75_ms\":{:.6},\"min_ms\":{:.6},\
+             \"max_ms\":{:.6},\"mean_ms\":{:.6},\"samples_ms\":[{samples}]}}",
+            self.macs,
+            self.median_ms,
+            self.p25_ms,
+            self.p75_ms,
+            self.best_ms,
+            self.max_ms,
+            self.mean_ms,
+        )
+    }
+}
+
+impl std::fmt::Display for Timing {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(
+            f,
+            "{:<28} median {:>8.2} ms  IQR [{:>7.2}, {:>7.2}]  min/max [{:>7.2}, {:>7.2}]  {:>7.1} GFLOP/s",
+            self.label,
+            self.median_ms,
+            self.p25_ms,
+            self.p75_ms,
+            self.best_ms,
+            self.max_ms,
+            self.gflops()
+        )
+    }
+}
+
+/// Log the device identity and whether cooperative matrix is usable.
+///
+/// This is the single most important line of the whole benchmark: it
+/// determines which matmul kernel every subsequent number came from.
+pub fn describe_device(gpu: &blade_graphics::Context) {
+    let info = gpu.device_information();
+    log::info!("device       : {}", info.device_name);
+    log::info!("driver       : {} {}", info.driver_name, info.driver_info);
+
+    let caps = meganeura::runtime::auto_tune(gpu, 0).coop_caps;
+    if caps.f16_tile == 0 && caps.f32_tile == 0 {
+        log::warn!("coop matrix  : NOT AVAILABLE — expect the register-tiled scalar matmul");
+    } else {
+        log::info!(
+            "coop matrix  : available (f32 tile {}, f16 tile {})",
+            caps.f32_tile,
+            caps.f16_tile
+        );
+    }
+}
+
+/// Fill every parameter with small deterministic pseudo-random values.
+///
+/// Timing is not sensitive to weight *values*, but leaving parameters at
+/// zero would make every activation zero, and a benchmark whose data is
+/// entirely one value invites doubt about data-dependent fast paths.
+/// Cheap insurance.
+pub fn fill_parameters(session: &mut Session, graph: &Graph) {
+    let mut state = 0x2545_F491_4F6C_DD1Du64;
+    let mut scratch = Vec::new();
+    for node in graph.nodes() {
+        let Op::Parameter { name } = &node.op else {
+            continue;
+        };
+        scratch.clear();
+        scratch.reserve(node.ty.num_elements());
+        for _ in 0..node.ty.num_elements() {
+            // xorshift64*, inlined to avoid a dependency.
+            state ^= state >> 12;
+            state ^= state << 25;
+            state ^= state >> 27;
+            let bits = state.wrapping_mul(0x2545_F491_4F6C_DD1D) >> 40;
+            scratch.push((bits as f32 / (1u32 << 24) as f32 - 0.5) * 0.05);
+        }
+        session.set_parameter(name, &scratch);
+    }
+}
+
+pub(crate) fn time_session(session: &mut Session, label: &str, macs: u64, iters: usize) -> Timing {
+    // Five is the paper protocol's minimum. The environment override exists
+    // for diagnostic sweeps, and is recorded alongside the raw samples by
+    // the calling artifact script.
+    let warmups = std::env::var("DINOVISION_WARMUPS")
+        .ok()
+        .and_then(|s| s.parse::<usize>().ok())
+        .unwrap_or(5);
+    for _ in 0..warmups {
+        session.step();
+        session.wait();
+    }
+
+    let mut samples_ms = Vec::with_capacity(iters.max(1));
+    for _ in 0..iters.max(1) {
+        let start = Instant::now();
+        session.step();
+        session.wait();
+        samples_ms.push(start.elapsed().as_secs_f64() * 1000.0);
+    }
+
+    let mut sorted = samples_ms.clone();
+    sorted.sort_by(f64::total_cmp);
+    let quantile = |q: f64| {
+        let at = q * (sorted.len() - 1) as f64;
+        let lo = at.floor() as usize;
+        let hi = at.ceil() as usize;
+        sorted[lo] + (sorted[hi] - sorted[lo]) * (at - lo as f64)
+    };
+    Timing {
+        label: label.to_string(),
+        best_ms: sorted[0],
+        mean_ms: samples_ms.iter().sum::<f64>() / samples_ms.len() as f64,
+        median_ms: quantile(0.5),
+        p25_ms: quantile(0.25),
+        p75_ms: quantile(0.75),
+        max_ms: sorted[sorted.len() - 1],
+        samples_ms,
+        macs,
+    }
+}
+
+/// Time a bare `[m, k] @ [k, n]` matmul.
+///
+/// Run at the shapes the encoder actually uses, so the result is an upper
+/// bound on what the encoder could reach rather than a peak-throughput
+/// number from an unrepresentatively large matrix.
+pub fn matmul_throughput(
+    gpu: Arc<blade_graphics::Context>,
+    m: usize,
+    k: usize,
+    n: usize,
+    iters: usize,
+) -> Timing {
+    let mut g = Graph::new();
+    let a = g.input("a", &[m, k]);
+    let b = g.parameter("b", &[k, n]);
+    let y = g.matmul(a, b);
+    g.set_outputs(vec![y]);
+
+    let (mut session, _) = meganeura::train::build(
+        &g,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    fill_parameters(&mut session, &g);
+    session.set_input("a", &vec![0.01f32; m * k]);
+
+    time_session(
+        &mut session,
+        &format!("matmul {m}x{k}x{n}"),
+        (m * k * n) as u64,
+        iters,
+    )
+}
+
+/// Sweep matmul shapes to find what the kernel is actually short of.
+///
+/// The encoder runs at ~67 GFLOP/s on device and an isolated matmul at its
+/// own shapes reaches ~120, but the same register-tiled kernel only reaches
+/// ~12% of peak on a desktop GPU too. An inefficiency that follows the
+/// kernel across two unrelated architectures is not an ALU-rate problem,
+/// which is what would have made f16 arithmetic worth writing. So measure
+/// the three things that could be costing the rest, each isolated:
+///
+/// * **Tail waste.** `m` is 201 — 196 patches, CLS, 4 registers — against
+///   `BM = 64`, so the last tile row is 9/64 useful and 21% of every
+///   dispatch is padding. Padding `m` to 256 does 27% more arithmetic; if
+///   the wall time does not move, we were paying for it already.
+/// * **Occupancy.** Tiles are 64×64 with `KTILE = 32`, so a workgroup holds
+///   16.4 KB of shared memory and few stay resident. Widening `n` at fixed
+///   cost per workgroup raises the workgroup count; if throughput climbs
+///   with it, the device is starved rather than saturated. This is also the
+///   one thing f16 would genuinely fix, by halving the LDS footprint.
+/// * **Prologue cost.** `k = 384` is 12 k-tiles, so the per-tile load and
+///   double barrier amortize over very few iterations. Deepening `k` at the
+///   same output size isolates that.
+///
+/// The large square shapes at the end give the kernel's ceiling with every
+/// one of those effects removed, which is the number f16 arithmetic would
+/// have to improve on to be worth the work.
+pub fn matmul_shapes(gpu: Arc<blade_graphics::Context>, iters: usize) -> Vec<Timing> {
+    let mut results = Vec::new();
+    for (m, k, n, note) in [
+        (201, 384, 1536, "encoder MLP up, as it runs"),
+        (256, 384, 1536, "m padded to a whole tile: +27% MACs"),
+        (201, 384, 384, "24 workgroups"),
+        (201, 384, 1536, "96 workgroups"),
+        (201, 384, 6144, "384 workgroups"),
+        (201, 1536, 1536, "4x the k-tiles per workgroup"),
+        (512, 512, 512, "square, no tail"),
+        (1024, 1024, 1024, "square, no tail"),
+        (2048, 2048, 2048, "square, kernel ceiling"),
+    ] {
+        let t = matmul_throughput(gpu.clone(), m, k, n, iters);
+        log::info!("{t}   ({note})");
+        results.push(t);
+    }
+
+    // Cash in the tail waste. Every token-major matmul has `m = tokens`, and
+    // 201 tokens occupy four 64-row tiles — 256 rows, of which 55 are
+    // padding we already pay for. A 240² input gives a 15×15 grid, so 225
+    // patches plus 5 prefix tokens is 230 rows: still four tiles, still the
+    // same dispatch, but 15% more spatial resolution reaching the decoder.
+    //
+    // Not entirely free — attention scores are O(tokens²) and they are ~8%
+    // of the layer — so measure it rather than assert it.
+    // 224 twice, bracketing 240. The Adreno's first measurement in a session
+    // runs at less than half the rate of its fifth — clocks ramp — so a
+    // straight A-then-B comparison credits B for the warm-up. If both 224s
+    // agree, the ramp is done and the middle number means something.
+    for size in [224, 240, 224] {
+        let c = Config::vits16().at_resolution(size).with_layers(3);
+        let mut t = encoder_forward(gpu.clone(), &c, iters);
+        t.label = format!("dinov3 @{size} 3L");
+        log::info!(
+            "{t}   (grid {}x{}, {} tokens)",
+            c.grid(),
+            c.grid(),
+            c.num_tokens()
+        );
+        results.push(t);
+    }
+    results
+}
+
+/// Build an encoder session on the shared context.
+///
+/// Weights are left to the caller: [`crate::weights::load_encoder`] for
+/// real features, [`fill_parameters`] for pure timing.
+pub fn build_encoder_session(
+    gpu: Arc<blade_graphics::Context>,
+    config: &Config,
+    cache: Option<&std::path::Path>,
+) -> (Session, Graph) {
+    let mut g = Graph::new();
+    let out = crate::dinov3::build_encoder(&mut g, config);
+    g.set_outputs(vec![out]);
+
+    let build_start = Instant::now();
+    let (session, _) = meganeura::train::build(
+        &g,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            cache,
+            ..Default::default()
+        },
+    );
+    // Worth reporting separately: on a mobile CPU, graph optimization plus
+    // WGSL-to-SPIR-V for every kernel is slow enough to matter at startup,
+    // and it is exactly what the plan cache is meant to remove.
+    log::info!(
+        "session build: {:.1} s (cache {})",
+        build_start.elapsed().as_secs_f64(),
+        if cache.is_some() { "on" } else { "off" }
+    );
+    (session, g)
+}
+
+/// Time a full DINOv3 forward pass with synthetic weights.
+pub fn encoder_forward(gpu: Arc<blade_graphics::Context>, config: &Config, iters: usize) -> Timing {
+    let (mut session, g) = build_encoder_session(gpu, config, None);
+    fill_parameters(&mut session, &g);
+    session.set_input(
+        "patches",
+        &vec![0.1f32; config.num_patches() * config.patch_dim()],
+    );
+
+    time_session(
+        &mut session,
+        &format!("dinov3 vits16 @{}", config.image_size),
+        config.forward_macs(),
+        iters,
+    )
+}
+
+/// Time the deployed joined encoder-to-RGB graph, including decoder and all
+/// graph-internal layout transformations. Camera conversion, CPU patchifying,
+/// output readback, and rendering are outside this isolated measurement.
+pub fn roundtrip_forward(
+    gpu: Arc<blade_graphics::Context>,
+    config: &Config,
+    submission_chunks: usize,
+    iters: usize,
+) -> Timing {
+    let mut graph = Graph::new();
+    let encoder_output = crate::dinov3::build_encoder(&mut graph, config);
+    let reconstruction = crate::decoder::attach_to_encoder(&mut graph, config, encoder_output);
+    graph.set_outputs(vec![reconstruction]);
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    session.set_submission_chunks(submission_chunks);
+    fill_parameters(&mut session, &graph);
+    session.set_input(
+        "patches",
+        &vec![0.1f32; config.num_patches() * config.patch_dim()],
+    );
+    time_session(
+        &mut session,
+        &format!(
+            "roundtrip @{} {}L x{}",
+            config.image_size, config.num_hidden_layers, submission_chunks
+        ),
+        config.forward_macs() + crate::decoder::forward_macs(config),
+        iters,
+    )
+}
+
+/// The full benchmark: device identity, matmul throughput at the shapes
+/// the encoder uses, then the encoder itself across candidate input
+/// resolutions.
+pub fn run_all(gpu: Arc<blade_graphics::Context>, iters: usize) -> Vec<Timing> {
+    describe_device(&gpu);
+
+    let base = Config::vits16();
+    let tokens = base.num_tokens();
+    let hidden = base.hidden_size;
+    let mut results = Vec::new();
+
+    // The three matmul shapes that dominate a ViT-S forward pass.
+    for (m, k, n) in [
+        (tokens, hidden, hidden),                 // Q/K/V/output projection
+        (tokens, hidden, base.intermediate_size), // MLP up
+        (tokens, base.intermediate_size, hidden), // MLP down
+    ] {
+        let t = matmul_throughput(gpu.clone(), m, k, n, iters);
+        log::info!("{t}");
+        results.push(t);
+    }
+
+    // 224 is the reference resolution (14×14 features); 256 buys a 16×16
+    // grid for ~30% more work. Anything larger is unlikely to fit a
+    // real-time budget, which is what these numbers will confirm or deny.
+    for size in [224, 256] {
+        let config = base.clone().at_resolution(size);
+        let t = encoder_forward(gpu.clone(), &config, iters);
+        log::info!(
+            "{t}   (grid {}x{}, {} tokens)",
+            config.grid(),
+            config.grid(),
+            config.num_tokens()
+        );
+        results.push(t);
+    }
+
+    // ViT-S/16 is the smallest DINOv3 there is, so cheaper means fewer
+    // layers or fewer tokens rather than a smaller model. Measure both
+    // knobs, since which one to spend is a quality judgement that wants
+    // real numbers under it.
+    for layers in [6, 3] {
+        let c = base.clone().at_resolution(224).with_layers(layers);
+        let mut t = encoder_forward(gpu.clone(), &c, iters);
+        t.label = format!("dinov3 @224 {layers}L");
+        log::info!("{t}   ({layers} of 12 layers)");
+        results.push(t);
+    }
+    for size in [160, 128] {
+        let c = base.clone().at_resolution(size);
+        let mut t = encoder_forward(gpu.clone(), &c, iters);
+        t.label = format!("dinov3 vits16 @{size}");
+        log::info!("{t}   (grid {}x{})", c.grid(), c.grid());
+        results.push(t);
+    }
+
+    // The actual reconstruction workload is a joined three-layer encoder and
+    // decoder. Keep isolated chunk costs beside the live-XR sweep so queue
+    // fairness is not presented without its throughput price.
+    let reconstruction = base.clone().at_resolution(224).with_layers(3);
+    for chunks in [1, 4, 12] {
+        let t = roundtrip_forward(gpu.clone(), &reconstruction, chunks, iters);
+        log::info!("{t}   (joined encoder + decoder, {chunks} submission chunks)");
+        results.push(t);
+    }
+
+    // f16 weight storage halves weight traffic. Whether that shows up
+    // depends on whether the device is short of bandwidth or of ALU, which
+    // is exactly the thing worth measuring rather than reasoning about.
+    let f16 = base.clone().at_resolution(224).with_f16_weights(true);
+    let mut t = encoder_forward(gpu.clone(), &f16, iters);
+    t.label = "dinov3 vits16 @224 f16w".to_string();
+    log::info!("{t}   (f16 weight storage, f32 arithmetic)");
+    results.push(t);
+
+    // Chunked submission should cost a little throughput — several submits
+    // instead of one — in exchange for letting a co-tenant interleave. This
+    // measures the price when nothing else is on the queue.
+    let chunked = base.clone().at_resolution(224);
+    let (mut session, g) = build_encoder_session(gpu, &chunked, None);
+    session.set_submission_chunks(12);
+    fill_parameters(&mut session, &g);
+    session.set_input(
+        "patches",
+        &vec![0.1f32; chunked.num_patches() * chunked.patch_dim()],
+    );
+    let t = time_session(
+        &mut session,
+        "dinov3 vits16 @224 x12",
+        chunked.forward_macs(),
+        iters,
+    );
+    log::info!("{t}   (12 submissions instead of 1)");
+    results.push(t);
+
+    results
+}

environment/training-source/source-snapshot/src/camera.rs

@@ -0,0 +1,731 @@
+//! Quest passthrough camera, through the Camera2 NDK.
+//!
+//! Meta exposes the forward-facing cameras on Quest 3 and 3S as ordinary
+//! Camera2 devices, distinguished from the avatar cameras by vendor tags.
+//! Their own documentation covers the Kotlin path; this is the native one,
+//! because everything else here is Rust and bouncing frames through JNI to
+//! get them back into a Vulkan pipeline would be absurd.
+//!
+//! Requirements, all of which fail silently if missed:
+//!
+//! * `horizonos.permission.HEADSET_CAMERA` **granted at runtime**. Declaring
+//!   it is not enough. For a POC:
+//!   `adb shell pm grant rust.dinovision_xr horizonos.permission.HEADSET_CAMERA`
+//! * minSdk 34 and NDK r27 for the API-34 sysroot. Note that Horizon OS
+//!   v205 does *not* export `ACameraManager_getTagFromName`, so Meta's
+//!   vendor tags cannot be resolved by name; cameras are identified by
+//!   lens facing and supported formats instead.
+//! * Passthrough enabled on the device.
+//!
+//! The camera delivers 1280×960 YUV420 at 60 Hz. The encoder wants a
+//! 224×224 RGB square, so [`FrameSource::next_frame`] centre-crops,
+//! box-downscales, and converts in one pass over the destination.
+
+#![cfg(target_os = "android")]
+
+use std::ffi::{c_char, c_int, c_void};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::time::{Duration, Instant};
+
+use crate::source::FrameSource;
+
+/// How long to wait between reopen attempts. The camera stays disabled for
+/// as long as the headset is off, so retrying hard would just spin.
+const REOPEN_INTERVAL: Duration = Duration::from_secs(1);
+
+// --- Opaque handles -------------------------------------------------------
+
+#[repr(C)]
+struct ACameraManager(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACameraDevice(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACameraMetadata(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACameraCaptureSession(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACaptureRequest(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACameraOutputTarget(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACaptureSessionOutput(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ACaptureSessionOutputContainer(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct AImageReader(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct AImage(#[allow(dead_code)] [u8; 0]);
+#[repr(C)]
+struct ANativeWindow(#[allow(dead_code)] [u8; 0]);
+
+#[repr(C)]
+struct ACameraIdList {
+    num_cameras: c_int,
+    camera_ids: *mut *const c_char,
+}
+
+#[repr(C)]
+struct ACameraMetadataConstEntry {
+    tag: u32,
+    kind: u8,
+    count: u32,
+    data: *const u8,
+}
+
+#[repr(C)]
+struct ACameraDeviceStateCallbacks {
+    context: *mut c_void,
+    on_disconnected: extern "C" fn(*mut c_void, *mut ACameraDevice),
+    on_error: extern "C" fn(*mut c_void, *mut ACameraDevice, c_int),
+}
+
+#[repr(C)]
+struct ACameraCaptureSessionStateCallbacks {
+    context: *mut c_void,
+    on_closed: extern "C" fn(*mut c_void, *mut ACameraCaptureSession),
+    on_ready: extern "C" fn(*mut c_void, *mut ACameraCaptureSession),
+    on_active: extern "C" fn(*mut c_void, *mut ACameraCaptureSession),
+}
+
+const AIMAGE_FORMAT_YUV_420_888: c_int = 0x23;
+const TEMPLATE_PREVIEW: c_int = 1;
+const ACAMERA_OK: c_int = 0;
+const AMEDIA_OK: c_int = 0;
+
+/// Standard metadata tags, section ordinal `<< 16` plus index.
+///
+/// Meta's vendor tags would be nicer, but resolving a vendor tag by name
+/// needs `ACameraManager_getTagFromName`, and Horizon OS v205 does not
+/// export it — linking against it stops the whole library from loading
+/// with `UnsatisfiedLinkError`. Standard tags are all that is portable
+/// here, so the passthrough cameras get identified by what they can do
+/// rather than by what they are called.
+const ACAMERA_LENS_FACING: u32 = (8 << 16) + 5;
+const ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS: u32 = (13 << 16) + 10;
+
+/// The passthrough cameras look outward at the world, so they report
+/// `LENS_FACING_BACK`. The Quest also exposes a front-facing camera —
+/// the avatar one — which advertises the same resolutions but is
+/// separately restricted and denies `openCamera` outright.
+const LENS_FACING_BACK: u8 = 1;
+
+/// Camera2 error codes, so a failure says something rather than showing a
+/// bare negative number.
+fn camera_error(code: c_int) -> &'static str {
+    match code {
+        -10001 => "invalid parameter",
+        -10002 => "camera disconnected",
+        -10003 => "not enough memory",
+        -10004 => "metadata not found",
+        -10005 => "camera device error",
+        -10006 => "camera service error",
+        -10007 => "session closed",
+        -10008 => "invalid operation",
+        -10009 => "stream configure failed",
+        -10010 => "camera in use",
+        -10011 => "max cameras in use",
+        -10012 => "camera disabled",
+        -10013 => "permission denied",
+        -10014 => "unsupported operation",
+        _ => "unknown",
+    }
+}
+
+#[link(name = "camera2ndk")]
+unsafe extern "C" {
+    fn ACameraManager_create() -> *mut ACameraManager;
+    fn ACameraManager_delete(m: *mut ACameraManager);
+    fn ACameraManager_getCameraIdList(m: *mut ACameraManager, out: *mut *mut ACameraIdList) -> c_int;
+    fn ACameraManager_deleteCameraIdList(l: *mut ACameraIdList);
+    fn ACameraManager_getCameraCharacteristics(
+        m: *mut ACameraManager,
+        id: *const c_char,
+        out: *mut *mut ACameraMetadata,
+    ) -> c_int;
+    fn ACameraManager_openCamera(
+        m: *mut ACameraManager,
+        id: *const c_char,
+        cb: *mut ACameraDeviceStateCallbacks,
+        out: *mut *mut ACameraDevice,
+    ) -> c_int;
+    fn ACameraMetadata_getConstEntry(
+        md: *const ACameraMetadata,
+        tag: u32,
+        entry: *mut ACameraMetadataConstEntry,
+    ) -> c_int;
+    fn ACameraMetadata_free(md: *mut ACameraMetadata);
+    fn ACameraDevice_close(d: *mut ACameraDevice) -> c_int;
+    fn ACameraDevice_createCaptureRequest(
+        d: *mut ACameraDevice,
+        template: c_int,
+        out: *mut *mut ACaptureRequest,
+    ) -> c_int;
+    fn ACameraDevice_createCaptureSession(
+        d: *mut ACameraDevice,
+        outputs: *const ACaptureSessionOutputContainer,
+        cb: *const ACameraCaptureSessionStateCallbacks,
+        session: *mut *mut ACameraCaptureSession,
+    ) -> c_int;
+    fn ACaptureSessionOutputContainer_create(
+        out: *mut *mut ACaptureSessionOutputContainer,
+    ) -> c_int;
+    fn ACaptureSessionOutputContainer_add(
+        c: *mut ACaptureSessionOutputContainer,
+        o: *const ACaptureSessionOutput,
+    ) -> c_int;
+    fn ACaptureSessionOutputContainer_free(c: *mut ACaptureSessionOutputContainer);
+    fn ACaptureSessionOutput_create(
+        w: *mut ANativeWindow,
+        out: *mut *mut ACaptureSessionOutput,
+    ) -> c_int;
+    fn ACaptureSessionOutput_free(o: *mut ACaptureSessionOutput);
+    fn ACameraOutputTarget_create(w: *mut ANativeWindow, out: *mut *mut ACameraOutputTarget)
+    -> c_int;
+    fn ACameraOutputTarget_free(t: *mut ACameraOutputTarget);
+    fn ACaptureRequest_addTarget(r: *mut ACaptureRequest, t: *const ACameraOutputTarget) -> c_int;
+    fn ACaptureRequest_free(r: *mut ACaptureRequest);
+    fn ACameraCaptureSession_setRepeatingRequest(
+        s: *mut ACameraCaptureSession,
+        cb: *mut c_void,
+        num: c_int,
+        requests: *mut *mut ACaptureRequest,
+        seq: *mut c_int,
+    ) -> c_int;
+    fn ACameraCaptureSession_close(s: *mut ACameraCaptureSession);
+}
+
+#[link(name = "mediandk")]
+unsafe extern "C" {
+    fn AImageReader_new(
+        width: c_int,
+        height: c_int,
+        format: c_int,
+        max_images: c_int,
+        out: *mut *mut AImageReader,
+    ) -> c_int;
+    fn AImageReader_delete(r: *mut AImageReader);
+    fn AImageReader_getWindow(r: *mut AImageReader, out: *mut *mut ANativeWindow) -> c_int;
+    fn AImageReader_acquireLatestImage(r: *mut AImageReader, out: *mut *mut AImage) -> c_int;
+    fn AImage_delete(i: *mut AImage);
+    fn AImage_getWidth(i: *const AImage, out: *mut i32) -> c_int;
+    fn AImage_getHeight(i: *const AImage, out: *mut i32) -> c_int;
+    fn AImage_getPlaneRowStride(i: *const AImage, plane: c_int, out: *mut i32) -> c_int;
+    fn AImage_getPlanePixelStride(i: *const AImage, plane: c_int, out: *mut i32) -> c_int;
+    fn AImage_getPlaneData(
+        i: *const AImage,
+        plane: c_int,
+        data: *mut *mut u8,
+        len: *mut c_int,
+    ) -> c_int;
+}
+
+/// Set from the device callbacks, cleared when the camera is reopened.
+///
+/// A process-global rather than a per-camera flag because the callbacks
+/// take a raw context pointer and this app only ever opens one camera;
+/// threading an `Arc` through the FFI to support a second would be
+/// ceremony for a case that does not exist.
+static DEVICE_ERROR: AtomicBool = AtomicBool::new(false);
+
+extern "C" fn on_disconnected(_ctx: *mut c_void, _d: *mut ACameraDevice) {
+    log::warn!("camera disconnected");
+    DEVICE_ERROR.store(true, Ordering::Release);
+}
+
+extern "C" fn on_error(_ctx: *mut c_void, _d: *mut ACameraDevice, err: c_int) {
+    // Code 3 is ERROR_CAMERA_DISABLED, which Horizon OS raises whenever the
+    // headset comes off. It is routine rather than exceptional here, so the
+    // camera reopens instead of the view freezing on its last frame.
+    log::warn!(
+        "camera device error {err}{}",
+        if err == 3 { " (disabled — headset removed?)" } else { "" }
+    );
+    DEVICE_ERROR.store(true, Ordering::Release);
+}
+extern "C" fn on_session(_ctx: *mut c_void, _s: *mut ACameraCaptureSession) {}
+
+/// Which of the two forward-facing cameras to read.
+#[derive(Clone, Copy, Debug)]
+pub enum Eye {
+    Left,
+    Right,
+}
+
+impl Eye {
+    fn position(self) -> u8 {
+        match self {
+            Eye::Left => 0,
+            Eye::Right => 1,
+        }
+    }
+}
+
+/// A live passthrough camera delivering square RGB frames.
+pub struct PassthroughCamera {
+    manager: *mut ACameraManager,
+    device: *mut ACameraDevice,
+    session: *mut ACameraCaptureSession,
+    request: *mut ACaptureRequest,
+    target: *mut ACameraOutputTarget,
+    output: *mut ACaptureSessionOutput,
+    container: *mut ACaptureSessionOutputContainer,
+    reader: *mut AImageReader,
+    size: usize,
+    buf: Vec<u8>,
+    have_frame: bool,
+    /// Kept so the camera can be reopened after the device errors.
+    eye: Eye,
+    capture: (i32, i32),
+    last_reopen: Instant,
+}
+
+// The handles are only touched from the thread that owns the struct; the
+// NDK does not pin them to a thread.
+unsafe impl Send for PassthroughCamera {}
+
+impl PassthroughCamera {
+    /// Open the passthrough camera for one eye at `size × size` output.
+    ///
+    /// `capture` is the sensor resolution to request — 1280×960 is what the
+    /// Quest 3/3S offer.
+    pub fn new(size: usize, eye: Eye, capture: (i32, i32)) -> Result<Self, String> {
+        unsafe {
+            let manager = ACameraManager_create();
+            if manager.is_null() {
+                return Err("ACameraManager_create returned null".into());
+            }
+
+            let mut list: *mut ACameraIdList = std::ptr::null_mut();
+            if ACameraManager_getCameraIdList(manager, &mut list) != ACAMERA_OK || list.is_null() {
+                ACameraManager_delete(manager);
+                return Err("could not enumerate cameras — is HEADSET_CAMERA granted?".into());
+            }
+            let ids = std::slice::from_raw_parts((*list).camera_ids, (*list).num_cameras as usize);
+            log::info!("{} cameras visible", ids.len());
+
+            let candidates = Self::candidates(manager, ids, eye, capture);
+            if candidates.is_empty() {
+                ACameraManager_deleteCameraIdList(list);
+                ACameraManager_delete(manager);
+                return Err("no outward-facing camera offers the requested format".into());
+            }
+
+            // --- Reader and its surface ---
+            let mut reader: *mut AImageReader = std::ptr::null_mut();
+            if AImageReader_new(
+                capture.0,
+                capture.1,
+                AIMAGE_FORMAT_YUV_420_888,
+                // A small queue: we always take the newest frame and drop
+                // the rest, so depth only adds latency.
+                4,
+                &mut reader,
+            ) != AMEDIA_OK
+            {
+                ACameraManager_deleteCameraIdList(list);
+                ACameraManager_delete(manager);
+                return Err("AImageReader_new failed".into());
+            }
+            let mut window: *mut ANativeWindow = std::ptr::null_mut();
+            AImageReader_getWindow(reader, &mut window);
+
+            // --- Open the device ---
+            let mut callbacks = ACameraDeviceStateCallbacks {
+                context: std::ptr::null_mut(),
+                on_disconnected,
+                on_error,
+            };
+            // Try each candidate in preference order. Which camera id maps
+            // to which physical sensor is not documented, and some are
+            // restricted in ways that only surface at open time, so trying
+            // beats predicting.
+            let mut device: *mut ACameraDevice = std::ptr::null_mut();
+            let mut last = ACAMERA_OK;
+            for &id in &candidates {
+                let status = ACameraManager_openCamera(manager, id, &mut callbacks, &mut device);
+                if status == ACAMERA_OK && !device.is_null() {
+                    log::info!("opened camera {:?}", std::ffi::CStr::from_ptr(id));
+                    break;
+                }
+                log::warn!(
+                    "camera {:?} would not open: {} ({status})",
+                    std::ffi::CStr::from_ptr(id),
+                    camera_error(status)
+                );
+                last = status;
+                device = std::ptr::null_mut();
+            }
+            ACameraManager_deleteCameraIdList(list);
+            if device.is_null() {
+                AImageReader_delete(reader);
+                ACameraManager_delete(manager);
+                return Err(format!(
+                    "no camera would open; last error {} ({last}){}",
+                    camera_error(last),
+                    if last == -10013 {
+                        " — HEADSET_CAMERA is a runtime permission and must be \
+                         granted, and passthrough must be enabled"
+                    } else {
+                        ""
+                    }
+                ));
+            }
+
+            // --- Session and repeating request ---
+            let mut container: *mut ACaptureSessionOutputContainer = std::ptr::null_mut();
+            ACaptureSessionOutputContainer_create(&mut container);
+            let mut output: *mut ACaptureSessionOutput = std::ptr::null_mut();
+            ACaptureSessionOutput_create(window, &mut output);
+            ACaptureSessionOutputContainer_add(container, output);
+
+            let session_cb = ACameraCaptureSessionStateCallbacks {
+                context: std::ptr::null_mut(),
+                on_closed: on_session,
+                on_ready: on_session,
+                on_active: on_session,
+            };
+            let mut session: *mut ACameraCaptureSession = std::ptr::null_mut();
+            if ACameraDevice_createCaptureSession(device, container, &session_cb, &mut session)
+                != ACAMERA_OK
+            {
+                return Err("createCaptureSession failed".into());
+            }
+
+            let mut request: *mut ACaptureRequest = std::ptr::null_mut();
+            ACameraDevice_createCaptureRequest(device, TEMPLATE_PREVIEW, &mut request);
+            let mut target: *mut ACameraOutputTarget = std::ptr::null_mut();
+            ACameraOutputTarget_create(window, &mut target);
+            ACaptureRequest_addTarget(request, target);
+
+            let mut requests = [request];
+            if ACameraCaptureSession_setRepeatingRequest(
+                session,
+                std::ptr::null_mut(),
+                1,
+                requests.as_mut_ptr(),
+                std::ptr::null_mut(),
+            ) != ACAMERA_OK
+            {
+                return Err("setRepeatingRequest failed".into());
+            }
+
+            log::info!(
+                "passthrough camera streaming {}x{} -> {size}x{size}",
+                capture.0,
+                capture.1
+            );
+            Ok(Self {
+                manager,
+                device,
+                session,
+                request,
+                target,
+                output,
+                container,
+                reader,
+                size,
+                // Mid-grey until the first frame lands, so a stalled camera
+                // is visibly "no data" rather than black.
+                buf: vec![128; size * size * 3],
+                have_frame: false,
+                eye,
+                capture,
+                last_reopen: Instant::now(),
+            })
+        }
+    }
+
+    /// Find the passthrough camera for the requested eye.
+    ///
+    /// Meta identifies these with vendor tags, but resolving a vendor tag
+    /// needs `ACameraManager_getTagFromName`, which Horizon OS v205 does not
+    /// export — and merely *linking* it prevents the library from loading at
+    /// all. So the cameras are identified by capability instead: the
+    /// passthrough pair are the ones offering the requested YUV420 size.
+    /// Among those, the list order is left then right, matching how Meta
+    /// numbers them.
+    unsafe fn candidates(
+        manager: *mut ACameraManager,
+        ids: &[*const c_char],
+        eye: Eye,
+        capture: (i32, i32),
+    ) -> Vec<*const c_char> {
+        unsafe {
+            let mut matching = Vec::new();
+            for &id in ids {
+                let mut md: *mut ACameraMetadata = std::ptr::null_mut();
+                if ACameraManager_getCameraCharacteristics(manager, id, &mut md) != ACAMERA_OK {
+                    continue;
+                }
+
+                let mut entry = ACameraMetadataConstEntry {
+                    tag: 0,
+                    kind: 0,
+                    count: 0,
+                    data: std::ptr::null(),
+                };
+                let facing = (ACameraMetadata_getConstEntry(md, ACAMERA_LENS_FACING, &mut entry)
+                    == ACAMERA_OK
+                    && entry.count > 0)
+                    .then(|| *entry.data);
+
+                let mut supported = false;
+                let mut entry = ACameraMetadataConstEntry {
+                    tag: 0,
+                    kind: 0,
+                    count: 0,
+                    data: std::ptr::null(),
+                };
+                if ACameraMetadata_getConstEntry(
+                    md,
+                    ACAMERA_SCALER_AVAILABLE_STREAM_CONFIGURATIONS,
+                    &mut entry,
+                ) == ACAMERA_OK
+                    && !entry.data.is_null()
+                {
+                    // int32[n * 4]: format, width, height, is-input.
+                    let values =
+                        std::slice::from_raw_parts(entry.data as *const i32, entry.count as usize);
+                    supported = values.chunks_exact(4).any(|c| {
+                        c[0] == AIMAGE_FORMAT_YUV_420_888
+                            && c[1] == capture.0
+                            && c[2] == capture.1
+                            && c[3] == 0
+                    });
+                }
+                ACameraMetadata_free(md);
+
+                log::info!(
+                    "camera {:?}: facing={facing:?} offers {}x{} YUV420: {supported}",
+                    std::ffi::CStr::from_ptr(id),
+                    capture.0,
+                    capture.1
+                );
+                if supported {
+                    matching.push((id, facing));
+                }
+            }
+
+            // Outward-facing first, and within that the requested eye
+            // first — but keep the rest as fallbacks, since the mapping
+            // from camera id to physical sensor is undocumented.
+            let (mut outward, inward): (Vec<_>, Vec<_>) = matching
+                .into_iter()
+                .partition(|&(_, facing)| facing == Some(LENS_FACING_BACK));
+
+            let wanted = eye.position() as usize;
+            if wanted < outward.len() {
+                outward.swap(0, wanted);
+            }
+            let ordered: Vec<*const c_char> = outward
+                .into_iter()
+                .chain(inward)
+                .map(|(id, _)| id)
+                .collect();
+
+            if ordered.is_empty() {
+                log::warn!(
+                    "no camera advertises {}x{} YUV420; trying all of them",
+                    capture.0,
+                    capture.1
+                );
+                return ids.to_vec();
+            }
+            ordered
+        }
+    }
+
+    /// Pull the newest frame, converting YUV420 to a square RGB crop.
+    fn pump(&mut self) -> bool {
+        unsafe {
+            let mut image: *mut AImage = std::ptr::null_mut();
+            if AImageReader_acquireLatestImage(self.reader, &mut image) != AMEDIA_OK
+                || image.is_null()
+            {
+                return false;
+            }
+
+            let (mut w, mut h) = (0i32, 0i32);
+            AImage_getWidth(image, &mut w);
+            AImage_getHeight(image, &mut h);
+
+            let plane = |index: c_int| -> Option<(*mut u8, usize, usize)> {
+                let (mut data, mut len) = (std::ptr::null_mut(), 0);
+                if AImage_getPlaneData(image, index, &mut data, &mut len) != AMEDIA_OK {
+                    return None;
+                }
+                let (mut row, mut pixel) = (0i32, 0i32);
+                AImage_getPlaneRowStride(image, index, &mut row);
+                AImage_getPlanePixelStride(image, index, &mut pixel);
+                Some((data, row as usize, pixel.max(1) as usize))
+            };
+
+            let (Some((y_data, y_row, _)), Some((u_data, u_row, u_pix)), Some((v_data, v_row, v_pix))) =
+                (plane(0), plane(1), plane(2))
+            else {
+                AImage_delete(image);
+                return false;
+            };
+
+            yuv420_to_square_rgb(
+                YuvPlanes {
+                    y: y_data,
+                    y_row,
+                    u: u_data,
+                    u_row,
+                    u_pix,
+                    v: v_data,
+                    v_row,
+                    v_pix,
+                },
+                w as usize,
+                h as usize,
+                self.size,
+                &mut self.buf,
+            );
+            AImage_delete(image);
+            self.have_frame = true;
+            true
+        }
+    }
+}
+
+impl Drop for PassthroughCamera {
+    fn drop(&mut self) {
+        unsafe {
+            if !self.session.is_null() {
+                ACameraCaptureSession_close(self.session);
+            }
+            if !self.request.is_null() {
+                ACaptureRequest_free(self.request);
+            }
+            if !self.target.is_null() {
+                ACameraOutputTarget_free(self.target);
+            }
+            if !self.container.is_null() {
+                ACaptureSessionOutputContainer_free(self.container);
+            }
+            if !self.output.is_null() {
+                ACaptureSessionOutput_free(self.output);
+            }
+            if !self.device.is_null() {
+                ACameraDevice_close(self.device);
+            }
+            if !self.reader.is_null() {
+                AImageReader_delete(self.reader);
+            }
+            if !self.manager.is_null() {
+                ACameraManager_delete(self.manager);
+            }
+        }
+    }
+}
+
+impl FrameSource for PassthroughCamera {
+    fn size(&self) -> usize {
+        self.size
+    }
+
+    fn next_frame(&mut self) -> Option<&[u8]> {
+        // Taking the headset off disables the camera, which is a normal
+        // thing to do rather than a fatal one. Reopen instead of freezing
+        // on the last frame forever.
+        if DEVICE_ERROR.load(Ordering::Acquire)
+            && self.last_reopen.elapsed() >= REOPEN_INTERVAL
+        {
+            self.last_reopen = Instant::now();
+            match Self::new(self.size, self.eye, self.capture) {
+                Ok(mut fresh) => {
+                    // Carry the last good frame across so the view does not
+                    // flash grey on every reopen.
+                    std::mem::swap(&mut fresh.buf, &mut self.buf);
+                    fresh.have_frame = self.have_frame;
+                    DEVICE_ERROR.store(false, Ordering::Release);
+                    // Dropping the old value closes the previous handles.
+                    *self = fresh;
+                    log::info!("camera reopened");
+                }
+                Err(e) => log::warn!("camera reopen failed: {e}"),
+            }
+        }
+
+        // A frame may not have arrived since the last call; showing the
+        // previous one beats stalling the pipeline.
+        self.pump();
+        self.have_frame.then_some(&self.buf[..])
+    }
+}
+
+struct YuvPlanes {
+    y: *mut u8,
+    y_row: usize,
+    u: *mut u8,
+    u_row: usize,
+    u_pix: usize,
+    v: *mut u8,
+    v_row: usize,
+    v_pix: usize,
+}
+
+/// Resample the *whole* YUV420 frame into a square RGB buffer.
+///
+/// Deliberately not a centre crop. The encoder needs a square, but cropping
+/// 1280×960 to 960×960 throws away a quarter of the horizontal field of
+/// view, and the point of this app is to show what the camera saw. Squashing
+/// the full frame instead keeps all of it; the aspect is restored at display
+/// time by drawing the quad at the camera's real 4:3 shape, so nothing ends
+/// up stretched on screen. DINO sees a horizontally compressed image, which
+/// costs a little feature quality and is a far better trade than losing the
+/// periphery.
+///
+/// Box-averages luma over each destination pixel's source footprint —
+/// point-sampling 960 down to 224 aliases badly enough to change what the
+/// patch embedding sees. Chroma is sampled at the centre, which is
+/// imperceptible after a 4× reduction and halves the work.
+///
+/// # Safety
+///
+/// The plane pointers must be valid for the given strides and dimensions.
+unsafe fn yuv420_to_square_rgb(
+    p: YuvPlanes,
+    width: usize,
+    height: usize,
+    size: usize,
+    out: &mut [u8],
+) {
+    for oy in 0..size {
+        let sy0 = oy * height / size;
+        let sy1 = ((oy + 1) * height / size).max(sy0 + 1).min(height);
+        for ox in 0..size {
+            let sx0 = ox * width / size;
+            let sx1 = ((ox + 1) * width / size).max(sx0 + 1).min(width);
+
+            let mut acc = 0u32;
+            let mut n = 0u32;
+            for sy in sy0..sy1 {
+                let row = unsafe { p.y.add(sy * p.y_row) };
+                for sx in sx0..sx1 {
+                    acc += unsafe { *row.add(sx) } as u32;
+                    n += 1;
+                }
+            }
+            let luma = (acc / n.max(1)) as f32;
+
+            // Chroma planes are half resolution in both axes.
+            let cx = ((sx0 + sx1) / 2) / 2;
+            let cy = ((sy0 + sy1) / 2) / 2;
+            let u = unsafe { *p.u.add(cy * p.u_row + cx * p.u_pix) } as f32 - 128.0;
+            let v = unsafe { *p.v.add(cy * p.v_row + cx * p.v_pix) } as f32 - 128.0;
+
+            // BT.601, which is what Camera2 delivers.
+            let r = luma + 1.402 * v;
+            let g = luma - 0.344_136 * u - 0.714_136 * v;
+            let b = luma + 1.772 * u;
+
+            let o = (oy * size + ox) * 3;
+            out[o] = r.clamp(0.0, 255.0) as u8;
+            out[o + 1] = g.clamp(0.0, 255.0) as u8;
+            out[o + 2] = b.clamp(0.0, 255.0) as u8;
+        }
+    }
+}

environment/training-source/source-snapshot/src/decoder.rs

@@ -0,0 +1,385 @@
+//! Reconstructing RGB from DINOv3 patch features.
+//!
+//! This is the roundtrip the project is named for: encode an image to
+//! features, decode those features back to pixels, and look at what
+//! survived.
+//!
+//! # What to expect
+//!
+//! At 224² the encoder produces a 14×14 grid of 384-dimensional features —
+//! about 75k numbers standing in for a 150k-value image. That alone would
+//! permit a decent reconstruction, but DINOv3 features are trained for
+//! *semantic invariance*: two views of the same object should land in the
+//! same place regardless of colour, lighting, or fine texture, which means
+//! precisely that information is discarded on purpose. So the reconstruction
+//! recovers layout and dominant colour well and fine detail poorly. That is
+//! the interesting result, not a defect in the decoder.
+//!
+//! # Shape
+//!
+//! A plain convolutional upsampler, four stages of ×2 from 14 to 224:
+//!
+//! ```text
+//! [384, 14, 14] → 256@28 → 128@56 → 64@112 → 32@224 → 3@224
+//! ```
+//!
+//! 2.01M parameters and about 1.14 GMAC per image. The early two stages use
+//! a second convolution to blend patch seams; the later stages do not.
+//!
+//! No skip connections and nothing fancy: the point is to measure what the
+//! features carry, and a decoder with its own access to the input would
+//! confuse that question entirely.
+
+use meganeura::{Graph, NodeId};
+
+use crate::dinov3::Config;
+
+/// Channel widths after each upsampling stage, from the feature grid up.
+pub const STAGES: [usize; 4] = [256, 128, 64, 32];
+/// How many of the early stages get a second convolution. Seams originate
+/// at the patch grid, so blending earns its cost at low resolution and
+/// mostly smooths detail away at high resolution.
+pub const BLEND_STAGES: usize = 2;
+/// Channels per group in the group norms.
+const GROUP_SIZE: usize = 16;
+const EPS: f32 = 1e-5;
+
+/// Total parameter count, for reporting and for sizing a weights file.
+pub fn parameter_count(config: &Config) -> usize {
+    let mut total = 0;
+    let mut in_c = config.hidden_size;
+    for (i, &out_c) in STAGES.iter().enumerate() {
+        total += out_c * in_c * 9 + out_c + out_c * 2;
+        if i < BLEND_STAGES {
+            total += out_c * out_c * 9 + out_c + out_c * 2;
+        }
+        in_c = out_c;
+    }
+    total += 3 * in_c * 9 + 3; // final projection to RGB
+    total
+}
+
+/// Multiply-accumulates in the decoder's convolution kernels at batch one.
+/// Bias, normalization, activations, and upsampling are intentionally not
+/// folded into this number; timing still includes every operation.
+pub fn forward_macs(config: &Config) -> u64 {
+    let mut total = 0u64;
+    let mut in_c = config.hidden_size;
+    let mut hw = config.grid();
+    for (i, &out_c) in STAGES.iter().enumerate() {
+        total += (out_c * in_c * 9 * hw * hw) as u64;
+        if i < BLEND_STAGES {
+            total += (out_c * out_c * 9 * hw * hw) as u64;
+        }
+        hw *= 2;
+        in_c = out_c;
+    }
+    total + (3 * in_c * 9 * hw * hw) as u64
+}
+
+/// One `conv3x3 → bias → group-norm → SiLU` block at a fixed resolution.
+fn block(
+    g: &mut Graph,
+    x: NodeId,
+    name: &str,
+    batch: usize,
+    in_c: usize,
+    out_c: usize,
+    hw: usize,
+) -> NodeId {
+    let kernel = g.parameter(&format!("{name}.weight"), &[out_c, in_c, 3, 3]);
+    let x = g.conv2d(
+        x,
+        kernel,
+        batch as u32,
+        in_c as u32,
+        hw as u32,
+        hw as u32,
+        out_c as u32,
+        3,
+        3,
+        1,
+        1,
+    );
+    let bias = g.parameter(&format!("{name}.bias"), &[out_c]);
+    let x = g.add_per_channel(x, bias, out_c as u32, (hw * hw) as u32);
+
+    let gn_w = g.parameter(&format!("{name}.norm.weight"), &[out_c]);
+    let gn_b = g.parameter(&format!("{name}.norm.bias"), &[out_c]);
+    let x = g.group_norm(
+        x,
+        gn_w,
+        gn_b,
+        batch as u32,
+        out_c as u32,
+        (hw * hw) as u32,
+        (out_c / GROUP_SIZE) as u32,
+        EPS,
+    );
+    g.silu(x)
+}
+
+/// Build the decoder over an existing feature node.
+///
+/// `features` must be `[batch, hidden, grid, grid]` flattened NCHW — patch
+/// tokens only, transposed out of the encoder's token-major layout. See
+/// [`patch_features_to_nchw`].
+///
+/// Returns `[batch, 3, image_size, image_size]` in `[0, 1]`.
+pub fn build_decoder(g: &mut Graph, config: &Config, features: NodeId, batch: usize) -> NodeId {
+    let mut x = features;
+    let mut in_c = config.hidden_size;
+    let mut hw = config.grid();
+
+    for (i, &out_c) in STAGES.iter().enumerate() {
+        x = block(g, x, &format!("dec.{i}"), batch, in_c, out_c, hw);
+        // A second convolution, but only where it pays for itself.
+        //
+        // The seams come from the input being piecewise constant — one
+        // feature vector per 16×16 patch — so hiding them needs a receptive
+        // field wide enough to mix across cells, and one 3×3 per scale
+        // reaches only a single neighbour. Doing that at *every* scale
+        // removed the tiling but doubled the decoder, and the decoder is
+        // ~40% of the frame on device.
+        //
+        // Each stage halves the channels and doubles the resolution, so all
+        // four second convolutions cost the same. The early ones are where
+        // patch boundaries actually live; by 56² and beyond the grid has
+        // already been blended and the extra pass mostly smooths detail
+        // away. Keeping the first two buys the seam repair for half the
+        // price.
+        if i < BLEND_STAGES {
+            x = block(g, x, &format!("dec.{i}b"), batch, out_c, out_c, hw);
+        }
+        x = g.upsample_2x(x, batch as u32, out_c as u32, hw as u32, hw as u32);
+        hw *= 2;
+        in_c = out_c;
+    }
+    assert_eq!(
+        hw, config.image_size,
+        "stage count does not reach the image resolution"
+    );
+
+    let kernel = g.parameter("dec.out.weight", &[3, in_c, 3, 3]);
+    let x = g.conv2d(
+        x,
+        kernel,
+        batch as u32,
+        in_c as u32,
+        hw as u32,
+        hw as u32,
+        3,
+        3,
+        3,
+        1,
+        1,
+    );
+    let bias = g.parameter("dec.out.bias", &[3]);
+    let x = g.add_per_channel(x, bias, 3, (hw * hw) as u32);
+    // Sigmoid rather than a clamp: pixels live in [0, 1] and a hard clamp
+    // has zero gradient outside the range, which strands any channel that
+    // starts saturated.
+    g.sigmoid(x)
+}
+
+/// Attach the decoder directly to a live encoder output.
+///
+/// Does in the graph what [`patch_features_to_nchw`] does on the CPU: drop
+/// the prefix tokens and transpose from the encoder's token-major layout to
+/// the channel-major one convolution needs. Batch 1 only — that is what
+/// inference runs.
+pub fn attach_to_encoder(g: &mut Graph, config: &Config, encoder_out: NodeId) -> NodeId {
+    let hidden = config.hidden_size;
+    let patches = config.num_patches();
+    let prefix = config.num_prefix_tokens();
+
+    // Slice off CLS and the register tokens. They carry global rather than
+    // spatial information and have no place on a feature map.
+    let patch_tokens = g.split_b(
+        encoder_out,
+        1,
+        (prefix * hidden) as u32,
+        (patches * hidden) as u32,
+        1,
+    );
+    let patch_tokens = g.reshape(patch_tokens, &[patches, hidden]);
+    let planes = g.transpose(patch_tokens);
+    let planes = g.reshape(planes, &[hidden * patches]);
+    build_decoder(g, config, planes, 1)
+}
+
+/// Load parameters written by `examples/train_decoder.rs`.
+///
+/// The file is raw f32 in graph declaration order, so it is only valid for
+/// the graph shape that produced it; a length mismatch means the decoder
+/// architecture changed and the weights are stale.
+pub fn load_parameters(
+    session: &mut meganeura::Session,
+    graph: &Graph,
+    path: &std::path::Path,
+) -> Result<(), Box<dyn std::error::Error>> {
+    let bytes = std::fs::read(path)?;
+    let values: Vec<f32> = bytes
+        .chunks_exact(4)
+        .map(|c| f32::from_le_bytes([c[0], c[1], c[2], c[3]]))
+        .collect();
+
+    let mut offset = 0;
+    let mut loaded = 0;
+    for node in graph.nodes() {
+        let meganeura::graph::Op::Parameter { name } = &node.op else {
+            continue;
+        };
+        // Only decoder parameters live in this file; the encoder's come
+        // from the checkpoint.
+        if !name.starts_with("dec.") {
+            continue;
+        }
+        let n = node.ty.num_elements();
+        if offset + n > values.len() {
+            return Err(format!(
+                "{} is too short: needed {} values by parameter '{name}', have {}",
+                path.display(),
+                offset + n,
+                values.len()
+            )
+            .into());
+        }
+        session.set_parameter(name, &values[offset..offset + n]);
+        offset += n;
+        loaded += 1;
+    }
+    if offset != values.len() {
+        return Err(format!(
+            "{} has {} values but the graph consumed {offset}; the decoder \
+             architecture and the weights disagree",
+            path.display(),
+            values.len()
+        )
+        .into());
+    }
+    log::info!("loaded {loaded} decoder parameters from {}", path.display());
+    Ok(())
+}
+
+/// Rearrange the encoder's `[tokens, hidden]` output into the `[hidden,
+/// grid, grid]` NCHW block the decoder consumes, dropping the CLS and
+/// register tokens.
+///
+/// The encoder is token-major (each row one token); convolution wants
+/// channel-major. Done on the CPU here because it happens once per image
+/// during dataset preparation; the live path folds it into the graph.
+pub fn patch_features_to_nchw(features: &[f32], config: &Config) -> Vec<f32> {
+    let hidden = config.hidden_size;
+    let patches = config.num_patches();
+    let skip = config.num_prefix_tokens();
+    assert_eq!(features.len(), config.num_tokens() * hidden);
+
+    let mut out = vec![0.0f32; hidden * patches];
+    for p in 0..patches {
+        let src = (skip + p) * hidden;
+        for c in 0..hidden {
+            out[c * patches + p] = features[src + c];
+        }
+    }
+    out
+}
+
+/// Peak signal-to-noise ratio in dB between two `[0, 1]` images.
+///
+/// The number to quote for reconstruction quality. Roughly: below 15 dB is
+/// unrecognizable, 20 dB is a recognizable blur, 30 dB is visually close.
+pub fn psnr(a: &[f32], b: &[f32]) -> f32 {
+    assert_eq!(a.len(), b.len());
+    let mse: f64 = a
+        .iter()
+        .zip(b)
+        .map(|(x, y)| {
+            let d = (x - y) as f64;
+            d * d
+        })
+        .sum::<f64>()
+        / a.len() as f64;
+    if mse <= f64::EPSILON {
+        return f32::INFINITY;
+    }
+    (10.0 * (1.0 / mse).log10()) as f32
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn stages_reach_the_image_resolution() {
+        let c = Config::vits16();
+        assert_eq!(c.grid() * 2usize.pow(STAGES.len() as u32), c.image_size);
+    }
+
+    #[test]
+    fn every_stage_divides_into_groups() {
+        for &c in &STAGES {
+            assert_eq!(c % GROUP_SIZE, 0, "{c} channels do not group evenly");
+        }
+    }
+
+    #[test]
+    fn parameter_count_is_modest() {
+        let n = parameter_count(&Config::vits16());
+        assert!(
+            (1_000_000..4_000_000).contains(&n),
+            "unexpected decoder size: {n}"
+        );
+    }
+
+    #[test]
+    fn forward_macs_match_the_deployed_decoder() {
+        let c = Config::vits16().at_resolution(224).with_layers(3);
+        assert_eq!(forward_macs(&c), 1_141_604_352);
+    }
+
+    #[test]
+    fn graph_builds_with_the_right_output_shape() {
+        let c = Config::vits16();
+        let mut g = Graph::new();
+        let feat = g.input("feat", &[c.hidden_size * c.num_patches()]);
+        let out = build_decoder(&mut g, &c, feat, 1);
+        assert_eq!(
+            g.node(out).ty.num_elements(),
+            3 * c.image_size * c.image_size
+        );
+    }
+
+    /// The NCHW rearrangement must move each token's channel `c` to plane
+    /// `c` at the token's grid position, and must skip the prefix tokens.
+    #[test]
+    fn nchw_rearrangement_is_a_transpose_past_the_prefix() {
+        let c = Config::vits16();
+        let h = c.hidden_size;
+        // Encode each value as token*1000 + channel so the mapping is
+        // checkable by arithmetic.
+        let features: Vec<f32> = (0..c.num_tokens() * h)
+            .map(|i| ((i / h) * 1000 + (i % h)) as f32)
+            .collect();
+        let nchw = patch_features_to_nchw(&features, &c);
+        assert_eq!(nchw.len(), h * c.num_patches());
+
+        for &(p, ch) in &[(0usize, 0usize), (37, 5), (195, 383)] {
+            let token = c.num_prefix_tokens() + p;
+            assert_eq!(
+                nchw[ch * c.num_patches() + p],
+                (token * 1000 + ch) as f32,
+                "patch {p} channel {ch} came from the wrong token"
+            );
+        }
+    }
+
+    #[test]
+    fn psnr_behaves() {
+        let a = vec![0.5f32; 100];
+        assert!(psnr(&a, &a).is_infinite(), "identical images are lossless");
+        // A uniform 0.1 error is MSE 0.01, i.e. 20 dB.
+        let b: Vec<f32> = a.iter().map(|v| v + 0.1).collect();
+        assert!((psnr(&a, &b) - 20.0).abs() < 0.1);
+    }
+}

environment/training-source/source-snapshot/src/dinov3.rs

@@ -0,0 +1,532 @@
+//! DINOv3 ViT encoder, expressed directly in meganeura's graph IR.
+//!
+//! Built by hand rather than imported: `meganeura::load_onnx` currently
+//! recognizes only `Add`, `Gemm`, `MatMul`, and `Relu`, which is nowhere
+//! near enough for a ViT. Every op this needs already exists in the IR,
+//! so the graph is a faithful transcription of
+//! `transformers/models/dinov3_vit/modeling_dinov3_vit.py`.
+//!
+//! Three things distinguish DINOv3 from a garden-variety ViT, and each is
+//! handled below:
+//!
+//! 1. **No learned position embedding.** Position enters only as 2D axial
+//!    RoPE applied to Q and K inside every layer.
+//! 2. **Prefix tokens.** A CLS token and `num_register_tokens` register
+//!    tokens are prepended to the patch tokens, and RoPE deliberately
+//!    skips them.
+//! 3. **LayerScale.** Each residual branch is scaled by a learned
+//!    per-channel vector before being added back.
+
+use meganeura::{Graph, NodeId};
+
+/// Architecture hyperparameters, mirroring HuggingFace's `DINOv3ViTConfig`.
+#[derive(Debug, Clone)]
+pub struct Config {
+    pub hidden_size: usize,
+    pub num_hidden_layers: usize,
+    pub num_attention_heads: u32,
+    pub intermediate_size: usize,
+    pub num_register_tokens: usize,
+    pub patch_size: usize,
+    /// Side length in pixels of the (square) input the graph is compiled
+    /// for. RoPE lets the real model take any size, but a meganeura graph
+    /// has static shapes, so one session serves one resolution.
+    pub image_size: usize,
+    pub layer_norm_eps: f32,
+    pub rope_theta: f32,
+    /// `false` selects the plain GELU MLP; DINOv3 only gates on ViT-L and
+    /// larger. Gated MLPs are not implemented here yet.
+    pub use_gated_mlp: bool,
+    /// Store the projection weights as f16, halving weight traffic from
+    /// 86 MB to 43 MB per forward pass.
+    ///
+    /// Storage only — meganeura's generated matmul reads `array<f16>` and
+    /// converts to f32 for the arithmetic, so this buys bandwidth, not ALU
+    /// rate. Whether that helps depends on which of the two the device is
+    /// short of; measure with `examples/bench` rather than assuming.
+    ///
+    /// Norms, biases, and LayerScale stay f32: they are a rounding error in
+    /// size and the most precision-sensitive parts of the network.
+    pub f16_weights: bool,
+}
+
+impl Config {
+    /// `facebook/dinov3-vits16-pretrain-lvd1689m` — 21M parameters.
+    pub fn vits16() -> Self {
+        Self {
+            hidden_size: 384,
+            num_hidden_layers: 12,
+            num_attention_heads: 6,
+            intermediate_size: 1536,
+            num_register_tokens: 4,
+            patch_size: 16,
+            image_size: 224,
+            layer_norm_eps: 1e-5,
+            rope_theta: 100.0,
+            use_gated_mlp: false,
+            f16_weights: false,
+        }
+    }
+
+    /// Enable f16 weight storage. See [`Config::f16_weights`].
+    pub fn with_f16_weights(mut self, enabled: bool) -> Self {
+        self.f16_weights = enabled;
+        self
+    }
+
+    /// Keep only the first `n` transformer layers.
+    ///
+    /// ViT-S/16 is already the smallest DINOv3 — the family only goes up
+    /// from here — so truncation is the way to get a cheaper encoder. Layers
+    /// are uniform in cost and dominate the frame, so this is very close to
+    /// a linear speedup: 6 of 12 layers runs about twice as fast.
+    ///
+    /// For RGB reconstruction it is not a trade at all. Measured: the same
+    /// decoder trained against 3 layers reaches 20.94 dB where 12 layers
+    /// gives 19.82 dB — better *and* 3.69× faster. The later layers are
+    /// where DINO's semantic invariance is built, which is exactly where
+    /// colour and texture get discarded, so for putting pixels back the deep
+    /// layers were destroying information the decoder needed.
+    ///
+    /// It does cut the other way for PCA colouring, which wants the
+    /// semantics the deep layers add. Depth is a per-display-mode choice.
+    ///
+    /// The decoder must be retrained for whichever depth is chosen; features
+    /// from layer 6 are not features from layer 12.
+    pub fn with_layers(mut self, n: usize) -> Self {
+        assert!(n <= 12, "DINOv3 ViT-S/16 has 12 layers, not {n}");
+        self.num_hidden_layers = n;
+        self
+    }
+
+    /// Same weights, different input resolution. The patch grid scales
+    /// with it, so cost grows quadratically — 224 gives a 14×14 grid at
+    /// ~4.6 GMAC, 448 gives 28×28 at ~4× that.
+    pub fn at_resolution(mut self, image_size: usize) -> Self {
+        assert_eq!(
+            image_size % self.patch_size,
+            0,
+            "image_size {image_size} is not a multiple of patch_size {}",
+            self.patch_size
+        );
+        self.image_size = image_size;
+        self
+    }
+
+    pub fn head_dim(&self) -> u32 {
+        self.hidden_size as u32 / self.num_attention_heads
+    }
+
+    /// Patches along one side of the image — the feature grid resolution.
+    pub fn grid(&self) -> usize {
+        self.image_size / self.patch_size
+    }
+
+    pub fn num_patches(&self) -> usize {
+        self.grid() * self.grid()
+    }
+
+    /// CLS + register tokens, which sit ahead of the patch tokens.
+    pub fn num_prefix_tokens(&self) -> usize {
+        1 + self.num_register_tokens
+    }
+
+    pub fn num_tokens(&self) -> usize {
+        self.num_prefix_tokens() + self.num_patches()
+    }
+
+    /// Length of one flattened patch: `3 * patch_size²`.
+    pub fn patch_dim(&self) -> usize {
+        3 * self.patch_size * self.patch_size
+    }
+
+    /// Multiply-accumulate count for one forward pass, for sanity-checking
+    /// measured throughput against achievable device throughput.
+    pub fn forward_macs(&self) -> u64 {
+        let t = self.num_tokens() as u64;
+        let d = self.hidden_size as u64;
+        let ff = self.intermediate_size as u64;
+        let per_layer =
+            // Q, K, V, and output projections
+            4 * t * d * d
+            // scores and the value-weighted sum
+            + 2 * t * t * d
+            // MLP up and down
+            + 2 * t * d * ff;
+        self.num_hidden_layers as u64 * per_layer + t * self.patch_dim() as u64 * d
+    }
+}
+
+/// Precomputed 2D axial RoPE tables, each `[num_tokens, hidden_size]`.
+///
+/// Two deviations from a literal transcription, both deliberate:
+///
+/// * Prefix rows are `(cos, sin) = (1, 0)`, making the rotation an
+///   identity there. DINOv3 skips RoPE on CLS and register tokens by
+///   slicing the token dimension; encoding it as data instead keeps the
+///   graph free of token-dimension splits.
+/// * The per-head table is replicated across all heads, so the tables
+///   multiply Q and K elementwise with no per-head indexing.
+///
+/// The coordinate jitter/shift/rescale in the reference is training-only
+/// (`if self.training`), so `pos_embed_rescale` is correctly ignored here.
+pub fn rope_tables(config: &Config) -> (Vec<f32>, Vec<f32>) {
+    let head_dim = config.head_dim() as usize;
+    // inv_freq has head_dim/4 entries: half the rotated pairs go to the
+    // y axis and half to x.
+    let quarter = head_dim / 4;
+    let half = head_dim / 2;
+    let heads = config.num_attention_heads as usize;
+    let hidden = config.hidden_size;
+    let grid = config.grid();
+
+    // inv_freq = 1 / theta^linspace(0, 1, head_dim/4)
+    let inv_freq: Vec<f32> = (0..quarter)
+        .map(|i| 1.0 / config.rope_theta.powf(i as f32 * 4.0 / head_dim as f32))
+        .collect();
+
+    let mut cos = vec![0.0f32; config.num_tokens() * hidden];
+    let mut sin = vec![0.0f32; config.num_tokens() * hidden];
+
+    // Identity rotation over the prefix tokens.
+    for t in 0..config.num_prefix_tokens() {
+        for c in 0..hidden {
+            cos[t * hidden + c] = 1.0;
+            sin[t * hidden + c] = 0.0;
+        }
+    }
+
+    let mut angles = vec![0.0f32; half];
+    for py in 0..grid {
+        for px in 0..grid {
+            // Patch-center coordinates normalized to [-1, +1]. The
+            // reference stacks them (y, x), and that order decides which
+            // half of the rotated pairs encodes which axis.
+            let y = 2.0 * ((py as f32 + 0.5) / grid as f32) - 1.0;
+            let x = 2.0 * ((px as f32 + 0.5) / grid as f32) - 1.0;
+            for i in 0..quarter {
+                angles[i] = std::f32::consts::TAU * y * inv_freq[i];
+                angles[quarter + i] = std::f32::consts::TAU * x * inv_freq[i];
+            }
+
+            let t = config.num_prefix_tokens() + py * grid + px;
+            let row = t * hidden;
+            for h in 0..heads {
+                for d in 0..head_dim {
+                    // `angles.tile(2)`: the upper half repeats the lower,
+                    // which is what pairs dimension d with d + head_dim/2
+                    // under `rotate_half`.
+                    let a = angles[d % half];
+                    cos[row + h * head_dim + d] = a.cos();
+                    sin[row + h * head_dim + d] = a.sin();
+                }
+            }
+        }
+    }
+
+    (cos, sin)
+}
+
+/// `x * cos + rotate_half(x) * sin`, where
+/// `rotate_half([x1, x2]) = [-x2, x1]` splits each head's `head_dim` in
+/// two.
+///
+/// Q and K arrive from `matmul` as `[tokens, heads * head_dim]`, and
+/// meganeura's attention reads head `h` of token `t` at
+/// `t * heads * head_dim + h * head_dim` — head-major, so each head's
+/// slice is contiguous. That lets the split treat the tensor as
+/// `tokens * heads` independent blocks of `head_dim`, with no transpose.
+fn apply_rope(
+    g: &mut Graph,
+    x: NodeId,
+    cos: NodeId,
+    sin: NodeId,
+    tokens: usize,
+    heads: u32,
+    head_dim: u32,
+) -> NodeId {
+    let hidden = (heads * head_dim) as usize;
+    let blocks = tokens as u32 * heads;
+    let half = head_dim / 2;
+
+    let x1 = g.split_a(x, blocks, half, half, 1);
+    let x2 = g.split_b(x, blocks, half, half, 1);
+    let neg_x2 = g.neg(x2);
+    let rotated = g.concat(neg_x2, x1, blocks, half, half, 1);
+    let rotated = g.reshape(rotated, &[tokens, hidden]);
+
+    let straight = g.mul(x, cos);
+    let crossed = g.mul(rotated, sin);
+    g.add(straight, crossed)
+}
+
+/// Apply a learned gain to the trailing hidden dimension of a
+/// `[tokens, hidden]` matrix.
+///
+/// Meganeura's `mul_per_channel` follows NCHW layout and indexes its gate as
+/// `linear_index / spatial`; using it directly with `spatial = 1` would read
+/// beyond the hidden-sized gate after the first token. Transposing to
+/// `[hidden, tokens]` makes each hidden coordinate an NCHW channel, with all
+/// tokens as its spatial extent, and therefore gives the LayerScale broadcast
+/// used by the reference implementation.
+fn layer_scale(g: &mut Graph, x: NodeId, gain: NodeId, tokens: usize, hidden: usize) -> NodeId {
+    let hidden_by_tokens = g.transpose(x);
+    // `mul_per_channel` is an NCHW-flat operator. Keeping the two-dimensional
+    // transpose shape would make its compiler interpret only the first axis
+    // as the element count.
+    let flat = g.reshape(hidden_by_tokens, &[hidden * tokens]);
+    let scaled = g.mul_per_channel(flat, gain, hidden as u32, tokens as u32);
+    let scaled = g.reshape(scaled, &[hidden, tokens]);
+    g.transpose(scaled)
+}
+
+/// Build the encoder and return the final `[num_tokens, hidden_size]`
+/// feature node.
+///
+/// Declares one input, `"patches"`, of shape `[num_patches, patch_dim]` —
+/// see [`crate::preprocess`] for the layout it expects. Parameter names
+/// match the HuggingFace checkpoint so [`crate::weights`] can bind them
+/// directly.
+///
+/// Row 0 of the output is the CLS token, rows `1..=num_register_tokens`
+/// are the registers, and the patch features follow in row-major grid
+/// order.
+pub fn build_encoder(g: &mut Graph, config: &Config) -> NodeId {
+    assert!(
+        !config.use_gated_mlp,
+        "gated MLP (ViT-L and larger) is not implemented"
+    );
+
+    let hidden = config.hidden_size;
+    let eps = config.layer_norm_eps;
+    let heads = config.num_attention_heads;
+    let head_dim = config.head_dim();
+    let tokens = config.num_tokens();
+    let prefix = config.num_prefix_tokens();
+
+    // Projection weights, in whichever storage the config asks for. Only
+    // the large 2D matrices participate; everything else stays f32.
+    let weight = |g: &mut Graph, name: &str, shape: &[usize]| {
+        if config.f16_weights {
+            g.parameter_f16(name, shape)
+        } else {
+            g.parameter(name, shape)
+        }
+    };
+
+    // --- Patch embedding ---
+    //
+    // The reference applies a Conv2d with kernel == stride == patch_size,
+    // which is exactly a per-patch linear map. Feeding pre-flattened
+    // patches turns it into a single matmul and keeps the (cheap,
+    // memory-bound) patch extraction outside the graph, where a render
+    // pass can do it straight from the camera texture later.
+    let patches = g.input("patches", &[config.num_patches(), config.patch_dim()]);
+    let patch_w = g.parameter(
+        "embeddings.patch_embeddings.weight",
+        &[config.patch_dim(), hidden],
+    );
+    let patch_b = g.parameter("embeddings.patch_embeddings.bias", &[hidden]);
+    let patch_embeds = g.matmul(patches, patch_w);
+    let patch_embeds = g.bias_add(patch_embeds, patch_b);
+
+    // --- Prepend CLS + register tokens ---
+    //
+    // One `[prefix, hidden]` parameter rather than separate cls_token and
+    // register_tokens nodes: the loader concatenates them, which costs one
+    // memcpy offline and saves a concat per forward pass.
+    let prefix_tokens = g.parameter("prefix_tokens", &[prefix, hidden]);
+    let mut x = g.concat(
+        prefix_tokens,
+        patch_embeds,
+        1,
+        (prefix * hidden) as u32,
+        (config.num_patches() * hidden) as u32,
+        1,
+    );
+    x = g.reshape(x, &[tokens, hidden]);
+
+    // RoPE tables are the same for every layer and for both Q and K, so
+    // they become two constant buffers shared by all 24 uses.
+    let (cos_data, sin_data) = rope_tables(config);
+    let cos = g.constant(cos_data, &[tokens, hidden]);
+    let sin = g.constant(sin_data, &[tokens, hidden]);
+
+    for i in 0..config.num_hidden_layers {
+        let p = format!("layer.{i}");
+
+        // --- Attention block ---
+        let n1_w = g.parameter(&format!("{p}.norm1.weight"), &[hidden]);
+        let n1_b = g.parameter(&format!("{p}.norm1.bias"), &[hidden]);
+        let h = g.layer_norm(x, n1_w, n1_b, eps);
+
+        let wq = weight(
+            g,
+            &format!("{p}.attention.q_proj.weight"),
+            &[hidden, hidden],
+        );
+        let bq = g.parameter(&format!("{p}.attention.q_proj.bias"), &[hidden]);
+        let wk = weight(
+            g,
+            &format!("{p}.attention.k_proj.weight"),
+            &[hidden, hidden],
+        );
+        let wv = weight(
+            g,
+            &format!("{p}.attention.v_proj.weight"),
+            &[hidden, hidden],
+        );
+        let bv = g.parameter(&format!("{p}.attention.v_proj.bias"), &[hidden]);
+
+        let q = g.matmul(h, wq);
+        let q = g.bias_add(q, bq);
+        // `key_bias: false` in the config — K genuinely has no bias.
+        let k = g.matmul(h, wk);
+        let v = g.matmul(h, wv);
+        let v = g.bias_add(v, bv);
+
+        let q = apply_rope(g, q, cos, sin, tokens, heads, head_dim);
+        let k = apply_rope(g, k, cos, sin, tokens, heads, head_dim);
+
+        // Non-causal: every token attends to every other. meganeura
+        // scales by head_dim^-0.5 internally, matching the reference.
+        let attn = g.full_attention(q, k, v, heads, heads, head_dim);
+
+        let wo = weight(
+            g,
+            &format!("{p}.attention.o_proj.weight"),
+            &[hidden, hidden],
+        );
+        let bo = g.parameter(&format!("{p}.attention.o_proj.bias"), &[hidden]);
+        let attn = g.matmul(attn, wo);
+        let attn = g.bias_add(attn, bo);
+
+        // LayerScale: learned gain over the trailing hidden dimension.
+        let ls1 = g.parameter(&format!("{p}.layer_scale1.lambda1"), &[hidden]);
+        let attn = layer_scale(g, attn, ls1, tokens, hidden);
+        x = g.add(x, attn);
+
+        // --- MLP block ---
+        let n2_w = g.parameter(&format!("{p}.norm2.weight"), &[hidden]);
+        let n2_b = g.parameter(&format!("{p}.norm2.bias"), &[hidden]);
+        let h = g.layer_norm(x, n2_w, n2_b, eps);
+
+        let up_w = weight(
+            g,
+            &format!("{p}.mlp.up_proj.weight"),
+            &[hidden, config.intermediate_size],
+        );
+        let up_b = g.parameter(
+            &format!("{p}.mlp.up_proj.bias"),
+            &[config.intermediate_size],
+        );
+        let down_w = weight(
+            g,
+            &format!("{p}.mlp.down_proj.weight"),
+            &[config.intermediate_size, hidden],
+        );
+        let down_b = g.parameter(&format!("{p}.mlp.down_proj.bias"), &[hidden]);
+
+        let m = g.matmul(h, up_w);
+        let m = g.bias_add(m, up_b);
+        let m = g.gelu(m);
+        let m = g.matmul(m, down_w);
+        let m = g.bias_add(m, down_b);
+
+        let ls2 = g.parameter(&format!("{p}.layer_scale2.lambda1"), &[hidden]);
+        let m = layer_scale(g, m, ls2, tokens, hidden);
+        x = g.add(x, m);
+    }
+
+    let n_w = g.parameter("norm.weight", &[hidden]);
+    let n_b = g.parameter("norm.bias", &[hidden]);
+    g.layer_norm(x, n_w, n_b, eps)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn vits16_shapes() {
+        let c = Config::vits16();
+        assert_eq!(c.grid(), 14);
+        assert_eq!(c.num_patches(), 196);
+        assert_eq!(c.num_prefix_tokens(), 5);
+        assert_eq!(c.num_tokens(), 201);
+        assert_eq!(c.head_dim(), 64);
+        assert_eq!(c.patch_dim(), 768);
+    }
+
+    #[test]
+    fn forward_macs_in_expected_ballpark() {
+        // ViT-S/16 at 224² is quoted at roughly 4.6 GMAC.
+        let macs = Config::vits16().forward_macs();
+        assert!(
+            (4.0e9..5.5e9).contains(&(macs as f64)),
+            "unexpected MAC count {macs}"
+        );
+    }
+
+    #[test]
+    fn rope_prefix_rows_are_identity() {
+        let c = Config::vits16();
+        let (cos, sin) = rope_tables(&c);
+        assert_eq!(cos.len(), c.num_tokens() * c.hidden_size);
+        for t in 0..c.num_prefix_tokens() {
+            for d in 0..c.hidden_size {
+                assert_eq!(cos[t * c.hidden_size + d], 1.0);
+                assert_eq!(sin[t * c.hidden_size + d], 0.0);
+            }
+        }
+    }
+
+    #[test]
+    fn rope_replicates_across_heads_and_tiles_halves() {
+        let c = Config::vits16();
+        let (cos, sin) = rope_tables(&c);
+        let hd = c.head_dim() as usize;
+        let half = hd / 2;
+        // Pick a patch token well away from the grid origin.
+        let row = (c.num_prefix_tokens() + 100) * c.hidden_size;
+        for d in 0..hd {
+            // Every head sees the same angle...
+            for h in 1..c.num_attention_heads as usize {
+                assert_eq!(cos[row + d], cos[row + h * hd + d]);
+                assert_eq!(sin[row + d], sin[row + h * hd + d]);
+            }
+            // ...and the upper half of each head repeats the lower half,
+            // which is what makes rotate_half pair d with d + half.
+            if d < half {
+                assert_eq!(cos[row + d], cos[row + d + half]);
+                assert_eq!(sin[row + d], sin[row + d + half]);
+            }
+        }
+    }
+
+    #[test]
+    fn rope_center_of_grid_is_near_zero_angle() {
+        // A 14×14 grid has no patch exactly at the center, but the two
+        // straddling it must have opposite-signed angles.
+        let c = Config::vits16();
+        let (_, sin) = rope_tables(&c);
+        let grid = c.grid();
+        let hidden = c.hidden_size;
+        let lo = (c.num_prefix_tokens() + (grid / 2 - 1) * grid + grid / 2 - 1) * hidden;
+        let hi = (c.num_prefix_tokens() + (grid / 2) * grid + grid / 2) * hidden;
+        assert!(
+            sin[lo] < 0.0 && sin[hi] > 0.0,
+            "expected opposite signs straddling the grid center, got {} and {}",
+            sin[lo],
+            sin[hi]
+        );
+    }
+
+    #[test]
+    fn graph_builds_and_declares_expected_slots() {
+        let c = Config::vits16();
+        let mut g = Graph::new();
+        let out = build_encoder(&mut g, &c);
+        assert_eq!(g.node(out).ty.shape, vec![c.num_tokens(), c.hidden_size]);
+    }
+}

environment/training-source/source-snapshot/src/inference.rs

@@ -0,0 +1,370 @@
+//! The inference worker: a thread that owns the meganeura session and
+//! publishes coloured feature grids for the renderer to display.
+//!
+//! # Why a thread at all
+//!
+//! The encoder is expected to take 40–60 ms on a Quest 3 while the
+//! compositor wants a frame every 13.9 ms. Running inference inline would
+//! put the render loop on the encoder's cadence, which is uncomfortable at
+//! best. Instead the renderer runs free, always drawing the most recent
+//! completed result, and inference lands whenever it lands.
+//!
+//! # Why the worker builds its own session
+//!
+//! `meganeura::Session` is not `Send` — it owns a `CommandEncoder` holding
+//! raw Vulkan handles. It cannot be constructed here and moved. What *is*
+//! shareable is `Arc<blade_graphics::Context>`, so the worker receives the
+//! context and builds the session in place. See `tests/threading.rs`.
+//!
+//! # The caveat this design cannot fix
+//!
+//! Both threads submit to the same Vulkan queue, which blade guards with a
+//! mutex. A long compute submission can still delay the render submission
+//! queued behind it — threading decouples *CPU* orchestration, not GPU
+//! occupancy. Whether that shows up as dropped frames is exactly what the
+//! on-device numbers will reveal; if it does, the fix is splitting the plan
+//! across frames, which needs meganeura to grow partial execution
+//! (`step()` currently submits every dispatch in one go).
+
+use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
+use std::sync::{Arc, Mutex, mpsc};
+use std::time::Instant;
+
+use crate::dinov3::Config;
+use crate::pca::{self, Basis};
+
+/// A completed inference result: a square RGB image, either the coarse
+/// feature colouring or a full reconstruction.
+#[derive(Debug, Clone)]
+pub struct FeatureGrid {
+    /// Row-major RGB. For [`Display::PcaColour`] this is `[tokens, 3]`
+    /// including the prefix tokens; for [`Display::Reconstruction`] it is
+    /// already `[grid * grid, 3]` with no prefix.
+    pub colors: Vec<f32>,
+    /// Side length of the displayable square: the patch grid for PCA
+    /// colouring, the image size for a reconstruction.
+    pub grid: usize,
+    pub prefix_tokens: usize,
+    /// Encoder wall time, for the on-screen/logged rate readout.
+    pub latency_ms: f64,
+}
+
+impl FeatureGrid {
+    /// The displayable `grid × grid × 3` image, with any prefix tokens
+    /// dropped.
+    pub fn patch_rgb(&self) -> &[f32] {
+        &self.colors[self.prefix_tokens * pca::COMPONENTS..]
+    }
+}
+
+/// What the encoder's output is turned into for display.
+#[derive(Clone, Debug)]
+pub enum Display {
+    /// Project patch features onto their top three principal components and
+    /// read those off as RGB. No training, one `[hidden, 3]` matmul, and a
+    /// `grid × grid` result. Shows what the features *distinguish*.
+    PcaColour,
+    /// Reconstruct RGB through the trained decoder — the actual roundtrip.
+    /// Produces a full `image_size × image_size` picture, so the readback
+    /// per frame is ~600 KB rather than ~3 KB. Shows what the features
+    /// *retain*.
+    Reconstruction(std::path::PathBuf),
+}
+
+/// What the worker is told to do next.
+enum Command {
+    /// Encode this image. `[num_patches, patch_dim]`, from
+    /// [`crate::preprocess`].
+    Submit(Vec<f32>),
+    /// Refit the PCA basis from the next frame's features.
+    Refit,
+    Stop,
+}
+
+/// Handle to a running worker.
+pub struct Worker {
+    tx: mpsc::Sender<Command>,
+    latest: Arc<Mutex<Option<FeatureGrid>>>,
+    generation: Arc<AtomicU64>,
+    ready: Arc<AtomicBool>,
+    handle: Option<std::thread::JoinHandle<()>>,
+}
+
+impl Worker {
+    /// Queue a frame for encoding.
+    ///
+    /// Returns `false` if the worker is busy or gone. Dropping frames is
+    /// the correct behaviour: the camera produces 60 Hz and the encoder
+    /// cannot keep up, so anything queued would be stale by the time it ran.
+    pub fn submit(&self, patches: Vec<f32>) -> bool {
+        if !self.ready.load(Ordering::Acquire) {
+            return false;
+        }
+        self.ready.store(false, Ordering::Release);
+        self.tx.send(Command::Submit(patches)).is_ok()
+    }
+
+    /// Ask for the colour basis to be refitted from the next frame.
+    pub fn request_refit(&self) {
+        let _ = self.tx.send(Command::Refit);
+    }
+
+    /// The most recent completed result, if any.
+    pub fn latest(&self) -> Option<FeatureGrid> {
+        self.latest.lock().ok().and_then(|g| g.clone())
+    }
+
+    /// Monotonic count of completed encodes, so the renderer can tell a
+    /// fresh result from a repeat without comparing pixel data.
+    pub fn generation(&self) -> u64 {
+        self.generation.load(Ordering::Acquire)
+    }
+
+    /// True when the worker is idle and would accept a frame.
+    pub fn is_ready(&self) -> bool {
+        self.ready.load(Ordering::Acquire)
+    }
+}
+
+impl Drop for Worker {
+    fn drop(&mut self) {
+        let _ = self.tx.send(Command::Stop);
+        if let Some(handle) = self.handle.take() {
+            let _ = handle.join();
+        }
+    }
+}
+
+/// How the worker should obtain its weights.
+pub enum Weights {
+    /// Load a checkpoint from disk. On device this is a path the app has
+    /// pushed or unpacked from its assets.
+    SafeTensors(std::path::PathBuf),
+    /// Deterministic synthetic weights. Produces meaningless features, but
+    /// exercises the entire pipeline end to end — useful for bringing the
+    /// render path up before the real checkpoint is on the device.
+    Synthetic,
+}
+
+/// Start the worker.
+///
+/// Returns immediately; the session is built on the worker thread, which
+/// takes a few seconds on a mobile CPU. [`Worker::is_ready`] reports false
+/// until it is done, and [`Worker::latest`] yields `None`.
+pub fn spawn(
+    gpu: Arc<blade_graphics::Context>,
+    config: Config,
+    weights: Weights,
+    plan_cache: Option<std::path::PathBuf>,
+    submission_chunks: usize,
+    display: Display,
+) -> Worker {
+    let (tx, rx) = mpsc::channel();
+    let latest = Arc::new(Mutex::new(None));
+    let generation = Arc::new(AtomicU64::new(0));
+    let ready = Arc::new(AtomicBool::new(false));
+
+    let handle = {
+        let latest = Arc::clone(&latest);
+        let generation = Arc::clone(&generation);
+        let ready = Arc::clone(&ready);
+        std::thread::Builder::new()
+            .name("dinovision-inference".into())
+            .spawn(move || {
+                worker_main(
+                    gpu,
+                    config,
+                    weights,
+                    plan_cache,
+                    submission_chunks,
+                    display,
+                    rx,
+                    latest,
+                    generation,
+                    ready,
+                );
+            })
+            .expect("failed to spawn inference thread")
+    };
+
+    Worker {
+        tx,
+        latest,
+        generation,
+        ready,
+        handle: Some(handle),
+    }
+}
+
+#[allow(clippy::too_many_arguments)]
+fn worker_main(
+    gpu: Arc<blade_graphics::Context>,
+    config: Config,
+    weights: Weights,
+    plan_cache: Option<std::path::PathBuf>,
+    submission_chunks: usize,
+    display: Display,
+    rx: mpsc::Receiver<Command>,
+    latest: Arc<Mutex<Option<FeatureGrid>>>,
+    generation: Arc<AtomicU64>,
+    ready: Arc<AtomicBool>,
+) {
+    // For PCA colouring both the colours and the features are outputs:
+    // colours every frame (3 KB), features only when refitting the basis
+    // (300 KB), which is why they are separate. A reconstruction needs
+    // neither — the decoder consumes the features inside the graph.
+    let reconstructing = matches!(display, Display::Reconstruction(_));
+    let mut g = meganeura::Graph::new();
+    let features = crate::dinov3::build_encoder(&mut g, &config);
+    if reconstructing {
+        let rgb = crate::decoder::attach_to_encoder(&mut g, &config, features);
+        g.set_outputs(vec![rgb]);
+    } else {
+        let colors = pca::add_projection(&mut g, features, config.hidden_size);
+        g.set_outputs(vec![colors, features]);
+    }
+
+    let build_start = Instant::now();
+    let (mut session, _) = meganeura::train::build(&g, meganeura::train::SessionConfig {
+        mode: meganeura::train::Mode::Inference,
+        gpu: Some(gpu),
+        cache: plan_cache.as_deref(),
+        ..Default::default()
+    });
+    log::info!(
+        "inference session ready in {:.1} s",
+        build_start.elapsed().as_secs_f64()
+    );
+
+    // Hand the queue back periodically so the renderer can get a frame in.
+    // One long submission is faster in isolation but starves everything
+    // else sharing the device.
+    session.set_submission_chunks(submission_chunks);
+
+    match weights {
+        Weights::SafeTensors(path) => {
+            match meganeura::data::safetensors::SafeTensorsModel::load(path.clone()) {
+                Ok(model) => {
+                    if let Err(e) = crate::weights::load_encoder(&mut session, &model, &config) {
+                        log::error!("failed to bind weights from {}: {e}", path.display());
+                        return;
+                    }
+                }
+                Err(e) => {
+                    log::error!("failed to read {}: {e}", path.display());
+                    return;
+                }
+            }
+        }
+        Weights::Synthetic => {
+            log::warn!("running with synthetic weights — features are meaningless");
+            crate::bench::fill_parameters(&mut session, &g);
+        }
+    }
+
+    let tokens = config.num_tokens();
+    let mut basis = Basis::placeholder(config.hidden_size);
+    let mut refit_pending = false;
+    let mut colors_out;
+    let mut features_out = vec![0.0f32; tokens * config.hidden_size];
+    // Reconstruction reads a planar [3, H, W] image; the renderer wants it
+    // interleaved, so keep a staging buffer for the transpose.
+    let mut planar = Vec::new();
+
+    match &display {
+        Display::PcaColour => {
+            // Start with a placeholder basis so the first frame displays
+            // something, then refit from real features as soon as one lands.
+            refit_pending = true;
+            apply_basis(&mut session, &basis);
+            colors_out = vec![0.0f32; tokens * pca::COMPONENTS];
+        }
+        Display::Reconstruction(path) => {
+            if let Err(e) = crate::decoder::load_parameters(&mut session, &g, path) {
+                log::error!("failed to load the decoder: {e}");
+                return;
+            }
+            let pixels = config.image_size * config.image_size;
+            planar = vec![0.0f32; 3 * pixels];
+            colors_out = vec![0.0f32; pixels * 3];
+        }
+    }
+
+    ready.store(true, Ordering::Release);
+
+    while let Ok(cmd) = rx.recv() {
+        let patches = match cmd {
+            Command::Submit(p) => p,
+            Command::Refit => {
+                refit_pending = true;
+                continue;
+            }
+            Command::Stop => break,
+        };
+
+        let start = Instant::now();
+        session.set_input("patches", &patches);
+        session.step();
+        session.wait();
+
+        if reconstructing {
+            session.read_output_by_index(0, &mut planar);
+            // [3, H, W] → [H * W, 3].
+            let pixels = config.image_size * config.image_size;
+            for p in 0..pixels {
+                for c in 0..3 {
+                    colors_out[p * 3 + c] = planar[c * pixels + p];
+                }
+            }
+        } else {
+            session.read_output_by_index(0, &mut colors_out);
+        }
+
+        if refit_pending {
+            // Refitting needs the full feature matrix, so this frame pays
+            // for the larger readback. It happens once at startup and then
+            // only on request.
+            session.read_output_by_index(1, &mut features_out);
+            basis = Basis::fit(
+                &features_out,
+                tokens,
+                config.hidden_size,
+                config.num_prefix_tokens(),
+            );
+            apply_basis(&mut session, &basis);
+            refit_pending = false;
+            log::info!("refitted colour basis from live features");
+            // The colours just read were produced by the old basis; redo
+            // the projection on the CPU so this frame is not displayed with
+            // a stale palette.
+            colors_out = basis.project(&features_out, tokens);
+        }
+
+        let grid = FeatureGrid {
+            colors: colors_out.clone(),
+            grid: if reconstructing {
+                config.image_size
+            } else {
+                config.grid()
+            },
+            prefix_tokens: if reconstructing {
+                0
+            } else {
+                config.num_prefix_tokens()
+            },
+            latency_ms: start.elapsed().as_secs_f64() * 1000.0,
+        };
+        if let Ok(mut slot) = latest.lock() {
+            *slot = Some(grid);
+        }
+        generation.fetch_add(1, Ordering::Release);
+        ready.store(true, Ordering::Release);
+    }
+
+    log::info!("inference worker stopped");
+}
+
+fn apply_basis(session: &mut meganeura::Session, basis: &Basis) {
+    session.set_parameter("pca.weight", &basis.weight_matrix());
+    session.set_parameter("pca.bias", &basis.bias_vector());
+}

environment/training-source/source-snapshot/src/lib.rs

@@ -0,0 +1,70 @@
+//! DINOv3 inference on Meta Quest, via Blade for graphics and Meganeura
+//! for the network.
+//!
+//! The camera image is encoded to DINOv3 patch features and those features
+//! are turned back into something viewable, so the user sees the world
+//! through a DINO roundtrip.
+//!
+//! # Layout
+//!
+//! * [`dinov3`] — the encoder as a meganeura graph, plus its config.
+//! * [`preprocess`] — image to patch tensor, with the flattening order the
+//!   folded patch-embedding matmul requires.
+//! * [`weights`] — binding a HuggingFace checkpoint to graph parameters.
+//! * [`bench`] — throughput measurement, shared by the desktop and
+//!   on-device entry points.
+//!
+//! # Sharing one GPU context
+//!
+//! The renderer and the network run on a *single*
+//! `blade_graphics::Context`, created here and handed to meganeura through
+//! `SessionConfig::gpu`. That is why this crate pins the same
+//! blade-graphics revision meganeura does — two copies of the crate would
+//! make the `Arc<Context>` types incompatible. It also means no
+//! external-memory interop is needed: `Session::input_buffer` hands back a
+//! `BufferPiece` a render pass can write to directly.
+
+pub mod bench;
+#[cfg(target_os = "android")]
+pub mod camera;
+pub mod decoder;
+pub mod dinov3;
+pub mod inference;
+pub mod pca;
+pub mod preprocess;
+pub mod render;
+pub mod source;
+pub mod weights;
+
+use std::sync::Arc;
+
+/// Create the GPU context that both the renderer and inference will share.
+///
+/// `xr` stays `None` for headless compute (the benchmark); the XR path
+/// fills in an `XrDesc` and everything downstream is unchanged.
+pub fn init_context(
+    xr: Option<blade_graphics::XrDesc>,
+) -> Result<Arc<blade_graphics::Context>, blade_graphics::NotSupportedError> {
+    let context = unsafe {
+        blade_graphics::Context::init(blade_graphics::ContextDesc {
+            presentation: false,
+            xr,
+            ray_tracing: false,
+            // Validation layers are not present on a retail Quest, and
+            // they cost real time where we can least afford it.
+            validation: cfg!(debug_assertions) && !cfg!(target_os = "android"),
+            timing: false,
+            capture: false,
+            overlay: false,
+            device_id: None,
+        })
+    }?;
+    let info = context.device_information();
+    log::info!(
+        "GPU: {} ({}), driver {}",
+        info.device_name,
+        info.driver_name,
+        info.driver_info
+    );
+    Ok(Arc::new(context))
+}

environment/training-source/source-snapshot/src/pca.rs

@@ -0,0 +1,401 @@
+//! Turning 384-dimensional patch features into something a person can see.
+//!
+//! The first display mode is the classic DINO visualization: project patch
+//! features onto their top three principal components and read those off as
+//! RGB. It needs no trained decoder, costs one `[hidden, 3]` matmul, and is
+//! semantically meaningful — patches of the same object land on the same
+//! colour, which is precisely what the features encode.
+//!
+//! The basis is fitted **on device** from a captured frame rather than
+//! shipped as an asset. Feature statistics depend on what the camera is
+//! actually looking at, and a basis fitted on ImageNet-ish photos would
+//! waste most of its dynamic range on a living room wall.
+//!
+//! Fitting uses power iteration with deflation. For three components out of
+//! a few hundred tokens that is a handful of milliseconds on the CPU, and
+//! it avoids pulling in a linear-algebra dependency for one job.
+
+use meganeura::{Graph, NodeId};
+
+/// Number of principal components, one per colour channel.
+pub const COMPONENTS: usize = 3;
+
+/// A fitted projection from feature space to RGB.
+#[derive(Debug, Clone)]
+pub struct Basis {
+    /// Feature-space mean, subtracted before projection.
+    pub mean: Vec<f32>,
+    /// Row-major `[COMPONENTS, dim]` — the top principal directions.
+    pub components: Vec<f32>,
+    /// Per-component scale mapping projections into roughly `[0, 1]`.
+    pub scale: [f32; COMPONENTS],
+    /// Per-component offset, applied after scaling.
+    pub offset: [f32; COMPONENTS],
+    pub dim: usize,
+}
+
+impl Basis {
+    /// An identity-ish basis to display before the first fit completes:
+    /// three arbitrary orthogonal axes. Produces a picture, just not a
+    /// well-conditioned one.
+    pub fn placeholder(dim: usize) -> Self {
+        let mut components = vec![0.0; COMPONENTS * dim];
+        for c in 0..COMPONENTS {
+            components[c * dim + c] = 1.0;
+        }
+        Self {
+            mean: vec![0.0; dim],
+            components,
+            scale: [1.0; COMPONENTS],
+            offset: [0.5; COMPONENTS],
+            dim,
+        }
+    }
+
+    /// Fit from a `[tokens, dim]` feature matrix.
+    ///
+    /// `skip` drops the leading prefix tokens: CLS and register tokens are
+    /// not patches, they carry global rather than spatial information, and
+    /// including them skews the components away from what is being
+    /// displayed.
+    pub fn fit(features: &[f32], tokens: usize, dim: usize, skip: usize) -> Self {
+        assert_eq!(features.len(), tokens * dim, "feature matrix shape mismatch");
+        assert!(skip < tokens, "nothing left after skipping {skip} tokens");
+        let rows = tokens - skip;
+        let data = &features[skip * dim..];
+
+        // Centre.
+        let mut mean = vec![0.0f32; dim];
+        for r in 0..rows {
+            for d in 0..dim {
+                mean[d] += data[r * dim + d];
+            }
+        }
+        for m in &mut mean {
+            *m /= rows as f32;
+        }
+        let mut centred: Vec<f32> = (0..rows * dim)
+            .map(|i| data[i] - mean[i % dim])
+            .collect();
+
+        let mut components = vec![0.0f32; COMPONENTS * dim];
+        let mut projected = vec![0.0f32; COMPONENTS * rows];
+
+        for c in 0..COMPONENTS {
+            // Deterministic, non-degenerate start vector. A constant vector
+            // would be orthogonal to components that sum to zero, so vary it.
+            let mut v: Vec<f32> = (0..dim)
+                .map(|d| ((d * 2654435761usize) % 1024) as f32 / 1024.0 - 0.5)
+                .collect();
+            normalize(&mut v);
+
+            let mut scores = vec![0.0f32; rows];
+            for _ in 0..48 {
+                // scores = X v ; v' = Xᵀ scores  — power iteration on XᵀX
+                // without ever forming the dim×dim covariance matrix.
+                for r in 0..rows {
+                    let row = &centred[r * dim..(r + 1) * dim];
+                    scores[r] = row.iter().zip(&v).map(|(a, b)| a * b).sum();
+                }
+                let mut next = vec![0.0f32; dim];
+                for r in 0..rows {
+                    let s = scores[r];
+                    let row = &centred[r * dim..(r + 1) * dim];
+                    for d in 0..dim {
+                        next[d] += s * row[d];
+                    }
+                }
+                if normalize(&mut next) < 1e-12 {
+                    break;
+                }
+                v = next;
+            }
+
+            // Final scores, then deflate so the next iteration finds the
+            // next-strongest direction.
+            for r in 0..rows {
+                let row = &centred[r * dim..(r + 1) * dim];
+                let s: f32 = row.iter().zip(&v).map(|(a, b)| a * b).sum();
+                scores[r] = s;
+                projected[c * rows + r] = s;
+            }
+            for r in 0..rows {
+                let s = scores[r];
+                for d in 0..dim {
+                    centred[r * dim + d] -= s * v[d];
+                }
+            }
+            components[c * dim..(c + 1) * dim].copy_from_slice(&v);
+        }
+
+        // Map each component to [0, 1] using a robust range rather than
+        // min/max: a single outlier patch would otherwise flatten the whole
+        // image into a narrow band of colour.
+        let mut lo = [0.0f32; COMPONENTS];
+        let mut span = [0.0f32; COMPONENTS];
+        for c in 0..COMPONENTS {
+            let mut col: Vec<f32> = projected[c * rows..(c + 1) * rows].to_vec();
+            col.sort_by(|a, b| a.partial_cmp(b).unwrap_or(std::cmp::Ordering::Equal));
+            lo[c] = col[(rows as f32 * 0.02) as usize];
+            let hi = col[((rows as f32 * 0.98) as usize).min(rows - 1)];
+            span[c] = hi - lo[c];
+        }
+
+        // A component carrying almost no variance relative to the leading
+        // one carries no visual information, and normalizing it to full
+        // range would amplify numerical noise into a psychedelic channel.
+        // This is not a contrived case: it is what a blank wall looks like.
+        // Map such a channel to flat mid-grey instead.
+        let dominant = span.iter().copied().fold(0.0f32, f32::max);
+        let floor = dominant * 1e-3;
+        let mut scale = [0.0f32; COMPONENTS];
+        let mut offset = [0.5f32; COMPONENTS];
+        for c in 0..COMPONENTS {
+            if span[c] > floor && span[c] > f32::MIN_POSITIVE {
+                scale[c] = 1.0 / span[c];
+                offset[c] = -lo[c] / span[c];
+            }
+        }
+
+        Self {
+            mean,
+            components,
+            scale,
+            offset,
+            dim,
+        }
+    }
+
+    /// The `[dim, COMPONENTS]` matrix the graph's projection matmul wants,
+    /// with the per-component scale folded in.
+    pub fn weight_matrix(&self) -> Vec<f32> {
+        let mut w = vec![0.0f32; self.dim * COMPONENTS];
+        for c in 0..COMPONENTS {
+            for d in 0..self.dim {
+                w[d * COMPONENTS + c] = self.components[c * self.dim + d] * self.scale[c];
+            }
+        }
+        w
+    }
+
+    /// The matching bias.
+    ///
+    /// `(x - mean) @ W * scale + offset` folds into `x @ (W * scale) + b`
+    /// with `b = offset - (mean @ W) * scale`, saving a subtraction pass
+    /// over every token.
+    pub fn bias_vector(&self) -> Vec<f32> {
+        let mut b = [0.0f32; COMPONENTS];
+        for c in 0..COMPONENTS {
+            let dot: f32 = (0..self.dim)
+                .map(|d| self.mean[d] * self.components[c * self.dim + d])
+                .sum();
+            b[c] = self.offset[c] - dot * self.scale[c];
+        }
+        b.to_vec()
+    }
+
+    /// CPU-side projection, for tests and for previewing a fit without a
+    /// GPU roundtrip.
+    pub fn project(&self, features: &[f32], tokens: usize) -> Vec<f32> {
+        let w = self.weight_matrix();
+        let b = self.bias_vector();
+        let mut out = vec![0.0f32; tokens * COMPONENTS];
+        for t in 0..tokens {
+            for c in 0..COMPONENTS {
+                let mut acc = b[c];
+                for d in 0..self.dim {
+                    acc += features[t * self.dim + d] * w[d * COMPONENTS + c];
+                }
+                out[t * COMPONENTS + c] = acc;
+            }
+        }
+        out
+    }
+}
+
+fn normalize(v: &mut [f32]) -> f32 {
+    let norm = v.iter().map(|x| x * x).sum::<f32>().sqrt();
+    if norm > 1e-12 {
+        for x in v.iter_mut() {
+            *x /= norm;
+        }
+    }
+    norm
+}
+
+/// Append the colour projection to an encoder output.
+///
+/// Declares `pca.weight` and `pca.bias` as parameters, so refitting the
+/// basis is a `set_parameter` call rather than a graph rebuild.
+///
+/// Returns the `[tokens, COMPONENTS]` colour node. Folding this into the
+/// graph rather than projecting on the CPU keeps the per-frame readback at
+/// `tokens * 3` floats instead of `tokens * 384` — about 3 KB rather than
+/// 300 KB, which matters on a bus shared with the compositor.
+pub fn add_projection(g: &mut Graph, features: NodeId, hidden: usize) -> NodeId {
+    let w = g.parameter("pca.weight", &[hidden, COMPONENTS]);
+    let b = g.parameter("pca.bias", &[COMPONENTS]);
+    let projected = g.matmul(features, w);
+    g.bias_add(projected, b)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Features lying on a known plane must be recovered by the top two
+    /// components, with the projection spreading across the output range.
+    #[test]
+    fn recovers_a_planted_subspace() {
+        let dim = 32;
+        let tokens = 200;
+        let mut features = vec![0.0f32; tokens * dim];
+        for t in 0..tokens {
+            let a = (t as f32 / tokens as f32) * 2.0 - 1.0;
+            let b = ((t * 7 % tokens) as f32 / tokens as f32) * 2.0 - 1.0;
+            for d in 0..dim {
+                // Two strong directions plus a much weaker third.
+                features[t * dim + d] = if d == 3 {
+                    5.0 * a
+                } else if d == 11 {
+                    4.0 * b
+                } else {
+                    0.01 * ((d as f32) * 0.1 + a)
+                };
+            }
+        }
+
+        let basis = Basis::fit(&features, tokens, dim, 0);
+        // The first two components should be dominated by dims 3 and 11.
+        let c0 = &basis.components[0..dim];
+        let c1 = &basis.components[dim..2 * dim];
+        let strongest = |c: &[f32]| {
+            c.iter()
+                .enumerate()
+                .max_by(|a, b| a.1.abs().partial_cmp(&b.1.abs()).unwrap())
+                .unwrap()
+                .0
+        };
+        let (s0, s1) = (strongest(c0), strongest(c1));
+        assert!(
+            (s0 == 3 && s1 == 11) || (s0 == 11 && s1 == 3),
+            "expected components along dims 3 and 11, got {s0} and {s1}"
+        );
+    }
+
+    #[test]
+    fn components_are_orthonormal() {
+        let dim = 24;
+        let tokens = 90;
+        let features: Vec<f32> = (0..tokens * dim)
+            .map(|i| ((i * 37 % 101) as f32 / 101.0 - 0.5) * (1.0 + (i % 5) as f32))
+            .collect();
+        let basis = Basis::fit(&features, tokens, dim, 0);
+
+        for a in 0..COMPONENTS {
+            let va = &basis.components[a * dim..(a + 1) * dim];
+            let norm: f32 = va.iter().map(|x| x * x).sum::<f32>().sqrt();
+            assert!((norm - 1.0).abs() < 1e-3, "component {a} norm {norm}");
+            for b in (a + 1)..COMPONENTS {
+                let vb = &basis.components[b * dim..(b + 1) * dim];
+                let dot: f32 = va.iter().zip(vb).map(|(x, y)| x * y).sum();
+                assert!(dot.abs() < 1e-2, "components {a},{b} not orthogonal: {dot}");
+            }
+        }
+    }
+
+    /// The folded weight/bias form must agree with an explicit
+    /// centre-project-scale-offset, since the graph only sees the folded one.
+    #[test]
+    fn folded_weights_match_explicit_form() {
+        let dim = 16;
+        let tokens = 60;
+        let features: Vec<f32> = (0..tokens * dim)
+            .map(|i| ((i * 13 % 97) as f32 / 97.0 - 0.5) * 3.0)
+            .collect();
+        let basis = Basis::fit(&features, tokens, dim, 0);
+        let folded = basis.project(&features, tokens);
+
+        for t in 0..tokens {
+            for c in 0..COMPONENTS {
+                let explicit: f32 = (0..dim)
+                    .map(|d| {
+                        (features[t * dim + d] - basis.mean[d]) * basis.components[c * dim + d]
+                    })
+                    .sum::<f32>()
+                    * basis.scale[c]
+                    + basis.offset[c];
+                let got = folded[t * COMPONENTS + c];
+                assert!(
+                    (got - explicit).abs() < 1e-3,
+                    "token {t} component {c}: folded {got} vs explicit {explicit}"
+                );
+            }
+        }
+    }
+
+    /// The robust range should put the bulk of patches inside [0, 1],
+    /// otherwise the display is either washed out or clipped.
+    #[test]
+    fn projection_spans_the_display_range() {
+        let dim = 48;
+        let tokens = 300;
+        let features: Vec<f32> = (0..tokens * dim)
+            .map(|i| {
+                let t = (i / dim) as f32;
+                let d = (i % dim) as f32;
+                (t * 0.017 + d * 0.31).sin() * 2.0
+            })
+            .collect();
+        let basis = Basis::fit(&features, tokens, dim, 0);
+        let out = basis.project(&features, tokens);
+
+        for c in 0..COMPONENTS {
+            let vals: Vec<f32> = (0..tokens).map(|t| out[t * COMPONENTS + c]).collect();
+            let inside = vals.iter().filter(|v| (0.0..=1.0).contains(*v)).count();
+            let frac = inside as f32 / tokens as f32;
+            assert!(frac > 0.9, "component {c}: only {:.0}% inside [0,1]", frac * 100.0);
+        }
+    }
+
+    /// A near-featureless scene — a blank wall — must not be amplified into
+    /// a noise field. Degenerate components go flat grey instead.
+    #[test]
+    fn degenerate_components_stay_neutral() {
+        let dim = 32;
+        let tokens = 120;
+        // Rank-1 data: only the first component carries any variance.
+        let mut features = vec![0.0f32; tokens * dim];
+        for t in 0..tokens {
+            let a = t as f32 / tokens as f32;
+            for d in 0..dim {
+                features[t * dim + d] = a * (d as f32 * 0.05).cos();
+            }
+        }
+
+        let basis = Basis::fit(&features, tokens, dim, 0);
+        let out = basis.project(&features, tokens);
+        assert!(out.iter().all(|v| v.is_finite()), "projection produced non-finite values");
+
+        // Components 1 and 2 have no signal; every token should sit at the
+        // neutral value rather than spanning the range.
+        for c in 1..COMPONENTS {
+            let vals: Vec<f32> = (0..tokens).map(|t| out[t * COMPONENTS + c]).collect();
+            let lo = vals.iter().copied().fold(f32::INFINITY, f32::min);
+            let hi = vals.iter().copied().fold(f32::NEG_INFINITY, f32::max);
+            assert!(
+                (hi - lo) < 1e-3 && (lo - 0.5).abs() < 1e-3,
+                "component {c} should be flat mid-grey, spans [{lo}, {hi}]"
+            );
+        }
+    }
+
+    #[test]
+    fn placeholder_is_usable_before_the_first_fit() {
+        let basis = Basis::placeholder(384);
+        let features = vec![0.25f32; 8 * 384];
+        let out = basis.project(&features, 8);
+        assert_eq!(out.len(), 8 * COMPONENTS);
+        assert!(out.iter().all(|v| v.is_finite()));
+    }
+}

environment/training-source/source-snapshot/src/preprocess.rs

@@ -0,0 +1,191 @@
+//! Turning an image into the `"patches"` tensor the encoder graph wants.
+//!
+//! The graph folds DINOv3's patch-embedding Conv2d into a single matmul,
+//! which means the flattening order here has to agree exactly with the
+//! order the convolution weight was flattened in. PyTorch stores that
+//! weight as `[out_channels, in_channels, kh, kw]`, so within one patch
+//! the element order is **channel-major**:
+//!
+//! ```text
+//! index = c * patch_size² + ky * patch_size + kx
+//! ```
+//!
+//! Get this wrong and the model still runs, producing confident nonsense
+//! — so it is pinned down by tests below.
+
+use crate::dinov3::Config;
+
+/// ImageNet statistics from the model's `preprocessor_config.json`.
+pub const IMAGE_MEAN: [f32; 3] = [0.485, 0.456, 0.406];
+pub const IMAGE_STD: [f32; 3] = [0.229, 0.224, 0.225];
+
+/// Flatten an already-normalized CHW pixel tensor into patches.
+///
+/// `pixels` is `[3, image_size, image_size]`, matching what HuggingFace's
+/// image processor hands to the model as `pixel_values`. Taking this form
+/// directly is what lets the desktop verifier feed the exact same tensor
+/// as the reference implementation, keeping resize and normalization
+/// differences out of a numerics comparison.
+///
+/// Returns `[num_patches, patch_dim]` in row-major grid order.
+pub fn patches_from_pixels_chw(pixels: &[f32], config: &Config) -> Vec<f32> {
+    let size = config.image_size;
+    let ps = config.patch_size;
+    let grid = config.grid();
+    assert_eq!(
+        pixels.len(),
+        3 * size * size,
+        "expected a [3, {size}, {size}] pixel tensor, got {} values",
+        pixels.len()
+    );
+
+    let plane = size * size;
+    let patch_area = ps * ps;
+    let mut out = vec![0.0f32; config.num_patches() * config.patch_dim()];
+
+    for gy in 0..grid {
+        for gx in 0..grid {
+            let patch = (gy * grid + gx) * config.patch_dim();
+            for c in 0..3 {
+                for ky in 0..ps {
+                    let src_row = c * plane + (gy * ps + ky) * size + gx * ps;
+                    let dst_row = patch + c * patch_area + ky * ps;
+                    out[dst_row..dst_row + ps].copy_from_slice(&pixels[src_row..src_row + ps]);
+                }
+            }
+        }
+    }
+
+    out
+}
+
+/// Flatten interleaved 8-bit RGB into patches, rescaling to `[0, 1]` and
+/// applying the ImageNet normalization on the way.
+///
+/// `rgb` is `[image_size, image_size, 3]` — the layout image decoders and
+/// camera conversions naturally produce. No resizing happens here; the
+/// caller supplies an image already at `config.image_size`.
+pub fn patches_from_rgb8(rgb: &[u8], config: &Config) -> Vec<f32> {
+    let size = config.image_size;
+    let ps = config.patch_size;
+    let grid = config.grid();
+    assert_eq!(
+        rgb.len(),
+        3 * size * size,
+        "expected a [{size}, {size}, 3] RGB image, got {} bytes",
+        rgb.len()
+    );
+
+    let patch_area = ps * ps;
+    let mut out = vec![0.0f32; config.num_patches() * config.patch_dim()];
+
+    for gy in 0..grid {
+        for gx in 0..grid {
+            let patch = (gy * grid + gx) * config.patch_dim();
+            for ky in 0..ps {
+                let y = gy * ps + ky;
+                for kx in 0..ps {
+                    let x = gx * ps + kx;
+                    let src = (y * size + x) * 3;
+                    for c in 0..3 {
+                        let v = rgb[src + c] as f32 / 255.0;
+                        out[patch + c * patch_area + ky * ps + kx] =
+                            (v - IMAGE_MEAN[c]) / IMAGE_STD[c];
+                    }
+                }
+            }
+        }
+    }
+
+    out
+}
+
+/// Reshape a `[out, 3, patch, patch]` Conv2d weight into the
+/// `[patch_dim, out]` matrix the graph's patch-embedding matmul expects.
+///
+/// The source is already contiguous in channel-major order per output
+/// channel, so this is purely a transpose of a `[out, patch_dim]` view.
+pub fn conv_weight_to_matmul(weight: &[f32], out_channels: usize, patch_dim: usize) -> Vec<f32> {
+    assert_eq!(
+        weight.len(),
+        out_channels * patch_dim,
+        "conv weight has {} values, expected {out_channels} * {patch_dim}",
+        weight.len()
+    );
+    let mut m = vec![0.0f32; patch_dim * out_channels];
+    for o in 0..out_channels {
+        for i in 0..patch_dim {
+            m[i * out_channels + o] = weight[o * patch_dim + i];
+        }
+    }
+    m
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn chw_patch_layout_is_channel_major() {
+        let c = Config::vits16();
+        // Encode each pixel's identity as its flat CHW index so the
+        // mapping is checkable by arithmetic.
+        let size = c.image_size;
+        let pixels: Vec<f32> = (0..3 * size * size).map(|i| i as f32).collect();
+        let patches = patches_from_pixels_chw(&pixels, &c);
+
+        let ps = c.patch_size;
+        let plane = size * size;
+        // Patch (gy=3, gx=5), channel 2, offset (ky=7, kx=11).
+        let (gy, gx, ch, ky, kx) = (3, 5, 2, 7, 11);
+        let got = patches[(gy * c.grid() + gx) * c.patch_dim() + ch * ps * ps + ky * ps + kx];
+        let want = (ch * plane + (gy * ps + ky) * size + gx * ps + kx) as f32;
+        assert_eq!(got, want);
+    }
+
+    #[test]
+    fn rgb8_and_chw_paths_agree() {
+        let c = Config::vits16();
+        let size = c.image_size;
+        // Build an arbitrary but reproducible RGB image, then the
+        // equivalent normalized CHW tensor, and check both flatteners
+        // land on the same patch tensor.
+        let rgb: Vec<u8> = (0..3 * size * size).map(|i| (i % 251) as u8).collect();
+        let mut chw = vec![0.0f32; 3 * size * size];
+        for y in 0..size {
+            for x in 0..size {
+                for ch in 0..3 {
+                    let v = rgb[(y * size + x) * 3 + ch] as f32 / 255.0;
+                    chw[ch * size * size + y * size + x] = (v - IMAGE_MEAN[ch]) / IMAGE_STD[ch];
+                }
+            }
+        }
+
+        let from_rgb = patches_from_rgb8(&rgb, &c);
+        let from_chw = patches_from_pixels_chw(&chw, &c);
+        assert_eq!(from_rgb.len(), from_chw.len());
+        let worst = from_rgb
+            .iter()
+            .zip(&from_chw)
+            .map(|(a, b)| (a - b).abs())
+            .fold(0.0f32, f32::max);
+        assert!(worst < 1e-6, "paths disagree by {worst}");
+    }
+
+    #[test]
+    fn normalization_maps_midgray_near_zero() {
+        let c = Config::vits16();
+        // 0.485*255 ≈ 124 is the red-channel mean, so red lands near 0.
+        let rgb = vec![124u8; 3 * c.image_size * c.image_size];
+        let patches = patches_from_rgb8(&rgb, &c);
+        assert!(patches[0].abs() < 0.02, "red channel not centred: {}", patches[0]);
+    }
+
+    #[test]
+    fn conv_weight_transpose_roundtrip() {
+        // [out=2, patch_dim=3] stored row-major becomes [3, 2].
+        let w = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0];
+        let m = conv_weight_to_matmul(&w, 2, 3);
+        assert_eq!(m, vec![1.0, 4.0, 2.0, 5.0, 3.0, 6.0]);
+    }
+}

environment/training-source/source-snapshot/src/render.rs

@@ -0,0 +1,324 @@
+//! Drawing the coloured feature grid to an eye buffer.
+//!
+//! Deliberately tiny: a full-screen triangle and a `grid x grid x 3` float
+//! buffer. The renderer runs at the headset's refresh rate regardless of
+//! how slowly inference produces new grids, so the expensive part of the
+//! frame is never on the display path.
+
+use blade_graphics as gpu;
+
+use crate::pca::COMPONENTS;
+
+/// Maximum eyes we allocate parameter slots for.
+pub const MAX_EYES: usize = 2;
+
+#[repr(C)]
+#[derive(Clone, Copy, bytemuck::Pod, bytemuck::Zeroable)]
+struct Params {
+    scale: [f32; 2],
+    offset: [f32; 2],
+    grid: u32,
+    pad: [u32; 3],
+}
+
+/// Where a flat overlay lands in one eye's clip space.
+///
+/// Purely 2D. The only thing an eye's frustum contributes to a head-locked
+/// image is where its axis sits and how wide the image should be — a scale
+/// and an offset — so that is all this carries.
+#[derive(Clone, Copy, Debug)]
+pub struct EyeTransform {
+    pub scale: [f32; 2],
+    pub offset: [f32; 2],
+}
+
+impl EyeTransform {
+    /// Fills the eye buffer exactly. Right for a flat window, wrong for a
+    /// headset, where it stretches the image over the whole field of view
+    /// and ignores the frustum's asymmetry.
+    pub const FULLSCREEN: Self = Self {
+        scale: [1.0, 1.0],
+        offset: [0.0, 0.0],
+    };
+
+    /// Fill an eye's field of view, centred on a given direction rather
+    /// than on the eye's axis.
+    ///
+    /// `centre_tan` is where the image's middle should sit, in tangent
+    /// units: `(x/-z, y/-z)` of the target direction expressed in the eye's
+    /// space. Zero is straight ahead and reproduces [`filling`].
+    ///
+    /// This is how the image gets to stay put while the head moves. The
+    /// content is as old as the last completed inference — a tenth of a
+    /// second here — so labelling it with the current head pose tells the
+    /// compositor to compensate for nothing, and it slides around with the
+    /// head. Feeding the direction the camera was *pointing when the frame
+    /// was captured* moves the image opposite to head motion, which is what
+    /// world-locked looks like.
+    pub fn filling_at(fov: [f32; 4], centre_tan: [f32; 2]) -> Self {
+        let [left, right, up, down] = fov;
+        let (tan_l, tan_r) = (left.tan(), right.tan());
+        let (tan_u, tan_d) = (up.tan(), down.tan());
+        let (span_x, span_y) = (tan_r - tan_l, tan_u - tan_d);
+        Self {
+            // Same size as filling the buffer.
+            scale: [1.0, 1.0],
+            offset: [
+                (2.0 * centre_tan[0] - (tan_r + tan_l)) / span_x,
+                (2.0 * centre_tan[1] - (tan_u + tan_d)) / span_y,
+            ],
+        }
+    }
+
+    /// Fill an eye's field of view, recentred on its axis.
+    ///
+    /// The right default for passthrough parity: the system's own
+    /// passthrough maps these cameras across your whole view, so matching it
+    /// means spanning the frustum rather than inventing an angular size.
+    ///
+    /// Note this is *not* the same as filling the eye buffer. Headset frusta
+    /// are asymmetric and mirror between the eyes, so an image painted
+    /// edge-to-edge has its centre at a different angle in each eye, and the
+    /// two will not fuse. Spanning the frustum symmetrically about the axis
+    /// is what makes them agree.
+    pub fn filling(fov: [f32; 4]) -> Self {
+        let [left, right, up, down] = fov;
+        let half_tan = [
+            (right.tan() - left.tan()) * 0.5,
+            (up.tan() - down.tan()) * 0.5,
+        ];
+        Self::for_eye(fov, half_tan)
+    }
+
+    /// Place an image into an eye whose frustum is `[left, right, up, down]`
+    /// radians, as OpenXR reports it.
+    ///
+    /// `half_tan` is the tangent of the image's half-angle on each axis.
+    /// Separate axes matter: the camera frame is squashed into a square for
+    /// the encoder, and giving x and y their true angular extents here is
+    /// what unsquashes it, so the view keeps the camera's full field
+    /// without looking stretched.
+    ///
+    /// A ray at angle θ from the view axis lands at clip
+    /// `(2·tanθ − (tanR + tanL)) / (tanR − tanL)`, so the quad's ±1 edges
+    /// map to a scale of `2·half_tan / (tanR − tanL)` about an offset of
+    /// `−(tanR + tanL) / (tanR − tanL)`.
+    ///
+    /// Headset frusta are asymmetric and differ between eyes, which is why
+    /// the offset is not zero and not shared: dropping it is what leaves the
+    /// two views unfusable.
+    pub fn for_eye(fov: [f32; 4], half_tan: [f32; 2]) -> Self {
+        let [left, right, up, down] = fov;
+        let (tan_l, tan_r) = (left.tan(), right.tan());
+        let (tan_u, tan_d) = (up.tan(), down.tan());
+        let (span_x, span_y) = (tan_r - tan_l, tan_u - tan_d);
+        Self {
+            scale: [
+                2.0 * half_tan[0] / span_x,
+                2.0 * half_tan[1] / span_y,
+            ],
+            offset: [-(tan_r + tan_l) / span_x, -(tan_u + tan_d) / span_y],
+        }
+    }
+}
+
+#[derive(blade_macros::ShaderData)]
+struct ViewData {
+    params: gpu::BufferPiece,
+    cells: gpu::BufferPiece,
+}
+
+/// Renders the latest feature grid full-screen.
+pub struct GridView {
+    pipeline: gpu::RenderPipeline,
+    params_buf: gpu::Buffer,
+    cells_buf: gpu::Buffer,
+    grid: usize,
+}
+
+impl GridView {
+    /// `color_format` must match the eye buffer being rendered into —
+    /// on an XR surface, `XrSurface::format()`.
+    pub fn new(context: &gpu::Context, color_format: gpu::TextureFormat, grid: usize) -> Self {
+        let shader = context.create_shader(gpu::ShaderDesc {
+            source: include_str!("shaders/grid_view.wgsl"),
+            naga_module: None,
+        });
+        let data_layout = <ViewData as gpu::ShaderData>::layout();
+        let pipeline = context.create_render_pipeline(gpu::RenderPipelineDesc {
+            name: "grid-view",
+            data_layouts: &[&data_layout],
+            vertex: shader.at("vs_main"),
+            vertex_fetches: &[],
+            primitive: gpu::PrimitiveState::default(),
+            // The view covers every pixel, so there is nothing to depth-test
+            // against and no depth buffer to allocate.
+            depth_stencil: None,
+            fragment: Some(shader.at("fs_main")),
+            color_targets: &[gpu::ColorTargetState::from(color_format)],
+            multisample_state: gpu::MultisampleState::default(),
+        });
+
+        // One slot per eye: the projection differs between them, and both
+        // are in flight within a single frame's submission.
+        let params_buf = context.create_buffer(gpu::BufferDesc {
+            name: "grid-view-params",
+            size: (std::mem::size_of::<Params>() * MAX_EYES) as u64,
+            memory: gpu::Memory::Shared,
+        });
+        let cells_buf = context.create_buffer(gpu::BufferDesc {
+            name: "grid-view-cells",
+            size: (grid * grid * COMPONENTS * std::mem::size_of::<f32>()) as u64,
+            memory: gpu::Memory::Shared,
+        });
+
+        let mut view = Self {
+            pipeline,
+            params_buf,
+            cells_buf,
+            grid,
+        };
+        // Full-screen until the caller supplies per-eye transforms, which
+        // is right for a window and wrong for a headset.
+        for eye in 0..MAX_EYES {
+            view.set_transform(context, eye, EyeTransform::FULLSCREEN);
+        }
+        // A mid-grey field, so a failure to ever produce a result looks
+        // like "no data" rather than like a working black-and-nothing view.
+        view.upload(context, &vec![0.5; grid * grid * COMPONENTS]);
+        view
+    }
+
+    /// Replace the displayed grid. `rgb` is `[grid * grid, 3]`, row-major.
+    pub fn upload(&mut self, context: &gpu::Context, rgb: &[f32]) {
+        let expected = self.grid * self.grid * COMPONENTS;
+        debug_assert_eq!(rgb.len(), expected, "grid payload is the wrong size");
+        let n = rgb.len().min(expected);
+        unsafe {
+            std::ptr::copy_nonoverlapping(rgb.as_ptr(), self.cells_buf.data() as *mut f32, n);
+        }
+        context.sync_buffer(self.cells_buf);
+    }
+
+    /// Set where the overlay lands in one eye.
+    pub fn set_transform(&mut self, context: &gpu::Context, eye: usize, t: EyeTransform) {
+        debug_assert!(eye < MAX_EYES);
+        unsafe {
+            let slot = (self.params_buf.data() as *mut Params).add(eye);
+            *slot = Params {
+                scale: t.scale,
+                offset: t.offset,
+                grid: self.grid as u32,
+                pad: [0; 3],
+            };
+        }
+        context.sync_buffer(self.params_buf);
+    }
+
+    /// Draw into an already-started render pass, using `eye`'s transform.
+    pub fn draw(&self, pass: &mut gpu::RenderCommandEncoder, eye: usize) {
+        let offset = (eye.min(MAX_EYES - 1) * std::mem::size_of::<Params>()) as u64;
+        let mut encoder = pass.with(&self.pipeline);
+        encoder.bind(
+            0,
+            &ViewData {
+                params: self.params_buf.at(offset),
+                cells: self.cells_buf.into(),
+            },
+        );
+        encoder.draw(0, 6, 0, 1);
+    }
+
+    pub fn destroy(mut self, context: &gpu::Context) {
+        context.destroy_buffer(self.cells_buf);
+        context.destroy_buffer(self.params_buf);
+        context.destroy_render_pipeline(&mut self.pipeline);
+    }
+}
+
+/// Rotate a vector by a quaternion `[x, y, z, w]`.
+fn rotate(q: [f32; 4], v: [f32; 3]) -> [f32; 3] {
+    let (qx, qy, qz, qw) = (q[0], q[1], q[2], q[3]);
+    // t = 2 * (q_vec × v); v' = v + qw * t + q_vec × t
+    let tx = 2.0 * (qy * v[2] - qz * v[1]);
+    let ty = 2.0 * (qz * v[0] - qx * v[2]);
+    let tz = 2.0 * (qx * v[1] - qy * v[0]);
+    [
+        v[0] + qw * tx + qy * tz - qz * ty,
+        v[1] + qw * ty + qz * tx - qx * tz,
+        v[2] + qw * tz + qx * ty - qy * tx,
+    ]
+}
+
+/// Where a direction that was straight ahead under `then` appears under
+/// `now`, in tangent units suitable for [`EyeTransform::filling_at`].
+///
+/// Both quaternions are `[x, y, z, w]` in the same reference space. The
+/// result is the image's centre after the head has moved, so a rotation to
+/// the right pushes the content left — the image staying put in the world
+/// while the view sweeps across it.
+///
+/// Returns `None` when the old direction has swung behind the viewer, where
+/// a tangent-plane shift stops meaning anything.
+pub fn reprojection_offset(then: [f32; 4], now: [f32; 4]) -> Option<[f32; 2]> {
+    // Forward under the capture pose, brought into the current eye's space
+    // by the inverse of the current pose.
+    let forward = rotate(then, [0.0, 0.0, -1.0]);
+    let inverse_now = [-now[0], -now[1], -now[2], now[3]];
+    let v = rotate(inverse_now, forward);
+    if v[2] >= -1e-3 {
+        return None;
+    }
+    Some([v[0] / -v[2], v[1] / -v[2]])
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    /// Straight ahead stays straight ahead when the head has not moved.
+    #[test]
+    fn no_motion_means_no_shift() {
+        let identity = [0.0, 0.0, 0.0, 1.0];
+        let offset = reprojection_offset(identity, identity).unwrap();
+        assert!(offset[0].abs() < 1e-6 && offset[1].abs() < 1e-6);
+    }
+
+    /// Turning the head right must push the content left, so the image
+    /// appears to stay where it was in the world.
+    #[test]
+    fn turning_right_pushes_content_left() {
+        let identity = [0.0, 0.0, 0.0, 1.0];
+        // +15 degrees about Y is a leftward yaw in a right-handed system
+        // looking down -Z, so -15 turns the view to the right.
+        let half = (-15.0f32).to_radians() * 0.5;
+        let turned_right = [0.0, half.sin(), 0.0, half.cos()];
+        let offset = reprojection_offset(identity, turned_right).unwrap();
+        assert!(
+            offset[0] < -0.1,
+            "expected the image to move left, got {offset:?}"
+        );
+        // The magnitude should be tan(15 deg) = 0.268.
+        assert!((offset[0] + 15.0f32.to_radians().tan()).abs() < 1e-3);
+        assert!(offset[1].abs() < 1e-6, "yaw should not shift vertically");
+    }
+
+    /// Looking up must push the content down.
+    #[test]
+    fn looking_up_pushes_content_down() {
+        let identity = [0.0, 0.0, 0.0, 1.0];
+        let half = 10.0f32.to_radians() * 0.5;
+        let looked_up = [half.sin(), 0.0, 0.0, half.cos()];
+        let offset = reprojection_offset(identity, looked_up).unwrap();
+        assert!(offset[1] < -0.1, "expected downward shift, got {offset:?}");
+        assert!(offset[0].abs() < 1e-6);
+    }
+
+    /// A view swung right round has nothing sensible to show.
+    #[test]
+    fn facing_away_has_no_offset() {
+        let identity = [0.0, 0.0, 0.0, 1.0];
+        let behind = [0.0, 1.0, 0.0, 0.0];
+        assert!(reprojection_offset(identity, behind).is_none());
+    }
+}

environment/training-source/source-snapshot/src/shaders/grid_view.wgsl

@@ -0,0 +1,73 @@
+// The feature grid, drawn as a head-locked 2D overlay.
+//
+// A quad in clip space with a per-eye scale and offset. No 3D: the content
+// is flat and pinned to the head, so nothing here needs a view or a
+// projection matrix.
+//
+// The per-eye transform is not optional decoration, though. A headset's
+// frusta are asymmetric — the view axis is not at the centre of the eye
+// buffer, and the two eyes differ — so painting identical pixels into both
+// buffers puts the same content at different apparent angles and the views
+// refuse to fuse. `offset` recentres on each eye's view axis; `scale` sizes
+// the image to the angle the camera actually saw, instead of stretching it
+// across the whole display and looking zoomed.
+
+struct Params {
+    scale: vec2<f32>,
+    offset: vec2<f32>,
+    grid: u32,
+    pad0: u32,
+    pad1: u32,
+    pad2: u32,
+};
+var<storage, read> params: Params;
+var<storage, read> cells: array<f32>;
+
+struct VsOut {
+    @builtin(position) position: vec4<f32>,
+    @location(0) uv: vec2<f32>,
+};
+
+@vertex
+fn vs_main(@builtin(vertex_index) vi: u32) -> VsOut {
+    // Two triangles over the unit square.
+    var xs = array<f32, 6>(-1.0, 1.0, -1.0, -1.0, 1.0, 1.0);
+    var ys = array<f32, 6>(-1.0, -1.0, 1.0, 1.0, -1.0, 1.0);
+    let x = xs[vi];
+    let y = ys[vi];
+
+    var out: VsOut;
+    out.position = vec4<f32>(
+        x * params.scale.x + params.offset.x,
+        y * params.scale.y + params.offset.y,
+        0.0,
+        1.0,
+    );
+    // Blade uses a negative-height viewport, so clip +y is the top of the
+    // framebuffer. Row 0 of the grid is the top of the image, so v runs
+    // opposite to y.
+    out.uv = vec2<f32>(x * 0.5 + 0.5, 0.5 - y * 0.5);
+    return out;
+}
+
+fn cell(ix: i32, iy: i32) -> vec3<f32> {
+    let g = i32(params.grid);
+    let x = clamp(ix, 0, g - 1);
+    let y = clamp(iy, 0, g - 1);
+    let base = u32((y * g + x) * 3);
+    return vec3<f32>(cells[base], cells[base + 1u], cells[base + 2u]);
+}
+
+@fragment
+fn fs_main(in: VsOut) -> @location(0) vec4<f32> {
+    let p = in.uv * f32(params.grid) - 0.5;
+    let corner = floor(p);
+    let frac = p - corner;
+    let ix = i32(corner.x);
+    let iy = i32(corner.y);
+
+    let top = mix(cell(ix, iy), cell(ix + 1, iy), frac.x);
+    let bottom = mix(cell(ix, iy + 1), cell(ix + 1, iy + 1), frac.x);
+    let rgb = clamp(mix(top, bottom, frac.y), vec3<f32>(0.0), vec3<f32>(1.0));
+    return vec4<f32>(rgb, 1.0);
+}

environment/training-source/source-snapshot/src/source.rs

@@ -0,0 +1,289 @@
+//! Where frames come from.
+//!
+//! The passthrough camera is not wired up yet, so this exists mainly as the
+//! seam it will slot into: the XR loop pulls from a [`FrameSource`] and does
+//! not care whether the pixels came from a camera or were made up.
+//!
+//! Until then [`TestPattern`] provides something with real spatial
+//! structure. That matters more than it sounds — a flat or noisy image
+//! makes every patch feature statistically identical, so the PCA colouring
+//! would look plausible while proving nothing. A scene with distinct
+//! regions shows immediately whether features are tracking content.
+
+/// A source of square RGB8 frames at the encoder's input resolution.
+pub trait FrameSource {
+    /// Side length in pixels; must match `Config::image_size`.
+    fn size(&self) -> usize;
+
+    /// The next frame as interleaved RGB8, `[size, size, 3]`, or `None`
+    /// when nothing new is available.
+    fn next_frame(&mut self) -> Option<&[u8]>;
+}
+
+/// A moving synthetic scene: coloured discs drifting over a gradient, with
+/// a checkerboard patch for high-frequency contrast.
+///
+/// Deliberately built from a few large, distinctly-coloured regions, since
+/// that is what DINO features separate well and therefore what makes the
+/// PCA view legible while bringing the pipeline up.
+pub struct TestPattern {
+    size: usize,
+    buf: Vec<u8>,
+    frame: u32,
+}
+
+impl TestPattern {
+    pub fn new(size: usize) -> Self {
+        Self {
+            size,
+            buf: vec![0; size * size * 3],
+            frame: 0,
+        }
+    }
+
+    fn render(&mut self) {
+        let size = self.size;
+        let t = self.frame as f32 * 0.02;
+        // Three discs on circular paths, each a saturated primary so the
+        // top principal components have something unambiguous to separate.
+        let discs = [
+            (0.30 + 0.18 * t.cos(), 0.30 + 0.18 * t.sin(), 0.16, [230u8, 60, 50]),
+            (0.70 + 0.15 * (t * 0.7 + 2.0).cos(), 0.35 + 0.15 * (t * 0.7).sin(), 0.13, [60, 200, 90]),
+            (0.50 + 0.20 * (t * 0.5 + 4.0).sin(), 0.72 + 0.10 * (t * 0.9).cos(), 0.15, [70, 110, 235]),
+        ];
+
+        for y in 0..size {
+            let v = y as f32 / size as f32;
+            for x in 0..size {
+                let u = x as f32 / size as f32;
+
+                // Background: a slow vertical gradient.
+                let mut rgb = [
+                    (40.0 + 60.0 * v) as u8,
+                    (50.0 + 40.0 * (1.0 - v)) as u8,
+                    (70.0 + 50.0 * v) as u8,
+                ];
+
+                // A checkerboard corner, for a region whose texture differs
+                // from everything else without its colour doing so.
+                if u > 0.72 && v > 0.72 {
+                    let cell = ((x / 8) + (y / 8)) % 2;
+                    let shade = if cell == 0 { 200 } else { 90 };
+                    rgb = [shade, shade, shade];
+                }
+
+                for &(cx, cy, r, color) in &discs {
+                    let dx = u - cx;
+                    let dy = v - cy;
+                    if dx * dx + dy * dy < r * r {
+                        rgb = color;
+                    }
+                }
+
+                let i = (y * size + x) * 3;
+                self.buf[i] = rgb[0];
+                self.buf[i + 1] = rgb[1];
+                self.buf[i + 2] = rgb[2];
+            }
+        }
+    }
+}
+
+impl FrameSource for TestPattern {
+    fn size(&self) -> usize {
+        self.size
+    }
+
+    fn next_frame(&mut self) -> Option<&[u8]> {
+        self.render();
+        self.frame = self.frame.wrapping_add(1);
+        Some(&self.buf)
+    }
+}
+
+/// Centre-crop an interleaved RGBA image to a square and resample it down
+/// to `size`, dropping alpha.
+///
+/// Box-averaging rather than nearest: a patch embedding sees 16×16 pixels,
+/// and point-sampling a 2560-wide screen down to 224 would alias hard
+/// enough to change what the features encode. Cheap here — it runs once per
+/// captured frame, not per patch.
+pub fn square_downscale_rgba(rgba: &[u8], width: usize, height: usize, size: usize) -> Vec<u8> {
+    let side = width.min(height);
+    let x0 = (width - side) / 2;
+    let y0 = (height - side) / 2;
+
+    let mut out = vec![0u8; size * size * 3];
+    for oy in 0..size {
+        let sy0 = y0 + oy * side / size;
+        let sy1 = (y0 + (oy + 1) * side / size).max(sy0 + 1);
+        for ox in 0..size {
+            let sx0 = x0 + ox * side / size;
+            let sx1 = (x0 + (ox + 1) * side / size).max(sx0 + 1);
+
+            let mut acc = [0u32; 3];
+            let mut n = 0u32;
+            for sy in sy0..sy1.min(height) {
+                for sx in sx0..sx1.min(width) {
+                    let i = (sy * width + sx) * 4;
+                    acc[0] += rgba[i] as u32;
+                    acc[1] += rgba[i + 1] as u32;
+                    acc[2] += rgba[i + 2] as u32;
+                    n += 1;
+                }
+            }
+            let n = n.max(1);
+            let o = (oy * size + ox) * 3;
+            for c in 0..3 {
+                out[o + c] = (acc[c] / n) as u8;
+            }
+        }
+    }
+    out
+}
+
+/// Live screen capture.
+///
+/// Exists mostly so the whole pipeline can be developed and demonstrated
+/// without a headset: it is the same `FrameSource` contract the Quest
+/// passthrough camera will implement, so the capture loop, colour handling,
+/// and downscale are all exercised here first.
+#[cfg(feature = "capture")]
+pub struct ScreenCapture {
+    monitor: xcap::Monitor,
+    size: usize,
+    buf: Vec<u8>,
+}
+
+#[cfg(feature = "capture")]
+impl ScreenCapture {
+    /// Capture the monitor at `index`, or the primary one if out of range.
+    pub fn new(size: usize, index: usize) -> Result<Self, Box<dyn std::error::Error>> {
+        let monitors = xcap::Monitor::all()?;
+        if monitors.is_empty() {
+            return Err("no monitors found".into());
+        }
+        for (i, m) in monitors.iter().enumerate() {
+            log::info!(
+                "monitor {i}: {}x{}{}",
+                m.width().unwrap_or(0),
+                m.height().unwrap_or(0),
+                if i == index { " (selected)" } else { "" }
+            );
+        }
+        let monitor = monitors
+            .into_iter()
+            .nth(index)
+            .ok_or("monitor index out of range")?;
+        Ok(Self {
+            monitor,
+            size,
+            buf: vec![128; size * size * 3],
+        })
+    }
+}
+
+#[cfg(feature = "capture")]
+impl FrameSource for ScreenCapture {
+    fn size(&self) -> usize {
+        self.size
+    }
+
+    fn next_frame(&mut self) -> Option<&[u8]> {
+        // A dropped frame is not worth failing over — the previous one is
+        // still displayable, and capture hiccups when windows change.
+        match self.monitor.capture_image() {
+            Ok(image) => {
+                let (w, h) = (image.width() as usize, image.height() as usize);
+                self.buf = square_downscale_rgba(&image.into_raw(), w, h, self.size);
+                Some(&self.buf)
+            }
+            Err(e) => {
+                log::warn!("screen capture failed: {e}");
+                None
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn downscale_centre_crops_and_averages() {
+        // A 40×20 image: left half red, right half blue. The centre crop is
+        // the middle 20×20, which straddles the boundary evenly.
+        let (w, h) = (40usize, 20usize);
+        let mut rgba = vec![0u8; w * h * 4];
+        for y in 0..h {
+            for x in 0..w {
+                let i = (y * w + x) * 4;
+                let c = if x < w / 2 { [255, 0, 0] } else { [0, 0, 255] };
+                rgba[i..i + 3].copy_from_slice(&c);
+                rgba[i + 3] = 255;
+            }
+        }
+
+        let out = square_downscale_rgba(&rgba, w, h, 4);
+        assert_eq!(out.len(), 4 * 4 * 3);
+        // Left column should be red, right column blue.
+        let px = |x: usize, y: usize| {
+            let i = (y * 4 + x) * 3;
+            [out[i], out[i + 1], out[i + 2]]
+        };
+        assert_eq!(px(0, 0), [255, 0, 0], "left edge should be red");
+        assert_eq!(px(3, 0), [0, 0, 255], "right edge should be blue");
+    }
+
+    #[test]
+    fn downscale_averages_rather_than_point_samples() {
+        // Alternating single-pixel columns must average to grey, not pick
+        // one extreme. Point sampling would give 0 or 255.
+        let (w, h) = (64usize, 64usize);
+        let mut rgba = vec![255u8; w * h * 4];
+        for y in 0..h {
+            for x in 0..w {
+                let v = if x % 2 == 0 { 0 } else { 255 };
+                let i = (y * w + x) * 4;
+                rgba[i..i + 3].copy_from_slice(&[v, v, v]);
+            }
+        }
+        let out = square_downscale_rgba(&rgba, w, h, 8);
+        for px in out.chunks_exact(3) {
+            assert!(
+                (100..=155).contains(&px[0]),
+                "expected mid-grey from averaging, got {}",
+                px[0]
+            );
+        }
+    }
+
+    #[test]
+    fn test_pattern_has_spatial_structure() {
+        let mut src = TestPattern::new(224);
+        let frame = src.next_frame().unwrap().to_vec();
+        assert_eq!(frame.len(), 224 * 224 * 3);
+
+        // A uniform image would make the whole exercise meaningless, so
+        // check there is real variation to encode.
+        let mean = frame.iter().map(|&b| b as f64).sum::<f64>() / frame.len() as f64;
+        let var = frame
+            .iter()
+            .map(|&b| (b as f64 - mean).powi(2))
+            .sum::<f64>()
+            / frame.len() as f64;
+        assert!(var > 400.0, "test pattern is too flat: variance {var:.1}");
+    }
+
+    #[test]
+    fn test_pattern_animates() {
+        let mut src = TestPattern::new(64);
+        let a = src.next_frame().unwrap().to_vec();
+        for _ in 0..20 {
+            src.next_frame();
+        }
+        let b = src.next_frame().unwrap().to_vec();
+        assert_ne!(a, b, "frames are identical; the scene is not moving");
+    }
+}

environment/training-source/source-snapshot/src/weights.rs

@@ -0,0 +1,172 @@
+//! Binding a HuggingFace DINOv3 checkpoint to the encoder graph's
+//! parameters.
+//!
+//! Three shape conventions differ between the checkpoint and the graph,
+//! and all three are handled here rather than in the graph:
+//!
+//! * `nn.Linear` stores `[out_features, in_features]`; meganeura's
+//!   `matmul` wants `[in, out]`. Every projection is transposed.
+//! * The patch embedding is a 4D `[out, 3, k, k]` conv weight; it is
+//!   flattened to `[out, patch_dim]` and transposed.
+//! * `cls_token` and `register_tokens` are separate parameters; the graph
+//!   declares one `prefix_tokens` matrix, assembled here.
+
+use meganeura::Session;
+use meganeura::data::safetensors::SafeTensorsModel;
+
+use crate::dinov3::Config;
+use crate::preprocess::conv_weight_to_matmul;
+
+type Error = Box<dyn std::error::Error>;
+
+/// Checkpoints appear both with and without a `model.` prefix on the
+/// encoder layers, depending on whether they were saved from
+/// `DINOv3ViTModel` or from the bare backbone. Resolve whichever this one
+/// uses once, up front, instead of guessing per tensor.
+fn layer_prefix(model: &SafeTensorsModel) -> Result<&'static str, Error> {
+    let info = model.tensor_info();
+    for candidate in ["layer.", "model.layer."] {
+        if info.keys().any(|k| k.starts_with(candidate)) {
+            return Ok(candidate);
+        }
+    }
+    Err(format!(
+        "no encoder layers found; checkpoint has {} tensors, e.g. {:?}",
+        info.len(),
+        info.keys().take(5).collect::<Vec<_>>()
+    )
+    .into())
+}
+
+/// Read a tensor under an optional `model.` prefix.
+fn embedding_tensor(model: &SafeTensorsModel, name: &str) -> Result<Vec<f32>, Error> {
+    if model.tensor_info().contains_key(name) {
+        model.tensor_f32_auto(name)
+    } else {
+        model.tensor_f32_auto(&format!("model.{name}"))
+    }
+}
+
+/// Upload every parameter the encoder graph declares.
+///
+/// Fails loudly on a missing or mis-shaped tensor: a silently skipped
+/// weight would leave a zero buffer and produce plausible-looking
+/// garbage.
+pub fn load_encoder(
+    session: &mut Session,
+    model: &SafeTensorsModel,
+    config: &Config,
+) -> Result<(), Error> {
+    let hidden = config.hidden_size;
+    let prefix = layer_prefix(model)?;
+    log::info!("checkpoint layer prefix: {prefix:?}");
+
+    // --- Patch embedding: [out, 3, k, k] -> [patch_dim, out] ---
+    let conv = embedding_tensor(model, "embeddings.patch_embeddings.weight")?;
+    let expected = hidden * config.patch_dim();
+    if conv.len() != expected {
+        return Err(format!(
+            "patch embedding has {} values, expected {expected} \
+             (is the checkpoint's patch_size or hidden_size different?)",
+            conv.len()
+        )
+        .into());
+    }
+    session.set_parameter(
+        "embeddings.patch_embeddings.weight",
+        &conv_weight_to_matmul(&conv, hidden, config.patch_dim()),
+    );
+    session.set_parameter(
+        "embeddings.patch_embeddings.bias",
+        &embedding_tensor(model, "embeddings.patch_embeddings.bias")?,
+    );
+
+    // --- Prefix tokens: CLS first, then the registers ---
+    //
+    // Order matters and is not arbitrary: the reference builds the
+    // sequence as cat([cls, registers, patches]), and RoPE identifies
+    // prefix tokens purely by their position at the front.
+    let cls = embedding_tensor(model, "embeddings.cls_token")?;
+    let registers = embedding_tensor(model, "embeddings.register_tokens")?;
+    if cls.len() != hidden {
+        return Err(format!("cls_token has {} values, expected {hidden}", cls.len()).into());
+    }
+    if registers.len() != config.num_register_tokens * hidden {
+        return Err(format!(
+            "register_tokens has {} values, expected {} * {hidden}",
+            registers.len(),
+            config.num_register_tokens
+        )
+        .into());
+    }
+    let mut prefix_tokens = Vec::with_capacity(config.num_prefix_tokens() * hidden);
+    prefix_tokens.extend_from_slice(&cls);
+    prefix_tokens.extend_from_slice(&registers);
+    session.set_parameter("prefix_tokens", &prefix_tokens);
+
+    // --- Encoder layers ---
+    for i in 0..config.num_hidden_layers {
+        let src = format!("{prefix}{i}");
+        let dst = format!("layer.{i}");
+
+        for norm in ["norm1", "norm2"] {
+            for part in ["weight", "bias"] {
+                session.set_parameter(
+                    &format!("{dst}.{norm}.{part}"),
+                    &model.tensor_f32_auto(&format!("{src}.{norm}.{part}"))?,
+                );
+            }
+        }
+
+        // K has no bias — `key_bias: false` in the config.
+        for (proj, has_bias) in [
+            ("q_proj", true),
+            ("k_proj", false),
+            ("v_proj", true),
+            ("o_proj", true),
+        ] {
+            session.set_parameter(
+                &format!("{dst}.attention.{proj}.weight"),
+                &model.tensor_f32_auto_transposed(&format!("{src}.attention.{proj}.weight"))?,
+            );
+            if has_bias {
+                session.set_parameter(
+                    &format!("{dst}.attention.{proj}.bias"),
+                    &model.tensor_f32_auto(&format!("{src}.attention.{proj}.bias"))?,
+                );
+            }
+        }
+
+        for proj in ["up_proj", "down_proj"] {
+            session.set_parameter(
+                &format!("{dst}.mlp.{proj}.weight"),
+                &model.tensor_f32_auto_transposed(&format!("{src}.mlp.{proj}.weight"))?,
+            );
+            session.set_parameter(
+                &format!("{dst}.mlp.{proj}.bias"),
+                &model.tensor_f32_auto(&format!("{src}.mlp.{proj}.bias"))?,
+            );
+        }
+
+        for ls in ["layer_scale1", "layer_scale2"] {
+            session.set_parameter(
+                &format!("{dst}.{ls}.lambda1"),
+                &model.tensor_f32_auto(&format!("{src}.{ls}.lambda1"))?,
+            );
+        }
+    }
+
+    // --- Final norm ---
+    for part in ["weight", "bias"] {
+        session.set_parameter(
+            &format!("norm.{part}"),
+            &embedding_tensor(model, &format!("norm.{part}"))?,
+        );
+    }
+
+    log::info!(
+        "loaded DINOv3 weights: {} layers, hidden {hidden}",
+        config.num_hidden_layers
+    );
+    Ok(())
+}

environment/training-source/source-snapshot/tests/dinov3_ops.rs

@@ -0,0 +1,142 @@
+//! Numerical checks at the exact tensor shapes used by DINOv3.
+
+use meganeura::Graph;
+use meganeura::train::{Mode, SessionConfig};
+
+#[test]
+fn full_attention_matches_cpu_at_dinov3_shape() {
+    let sequence = 201usize;
+    let heads = 6usize;
+    let head_dim = 64usize;
+    let hidden = heads * head_dim;
+
+    let mut graph = Graph::new();
+    let q_node = graph.input("q", &[sequence, hidden]);
+    let k_node = graph.input("k", &[sequence, hidden]);
+    let v_node = graph.input("v", &[sequence, hidden]);
+    let output = graph.full_attention(
+        q_node,
+        k_node,
+        v_node,
+        heads as u32,
+        heads as u32,
+        head_dim as u32,
+    );
+    graph.set_outputs(vec![output]);
+
+    let q: Vec<f32> = (0..sequence * hidden)
+        .map(|i| (i as f32 * 0.013).sin() * 0.2)
+        .collect();
+    let k: Vec<f32> = (0..sequence * hidden)
+        .map(|i| (i as f32 * 0.017 + 0.3).cos() * 0.2)
+        .collect();
+    let v: Vec<f32> = (0..sequence * hidden)
+        .map(|i| (i as f32 * 0.019 - 0.2).sin() * 0.2)
+        .collect();
+
+    let mut expected = vec![0.0f32; sequence * hidden];
+    let scale = 1.0 / (head_dim as f32).sqrt();
+    for query in 0..sequence {
+        for head in 0..heads {
+            let offset = head * head_dim;
+            let mut scores = vec![0.0f32; sequence];
+            for key in 0..sequence {
+                scores[key] = (0..head_dim)
+                    .map(|dimension| {
+                        q[query * hidden + offset + dimension]
+                            * k[key * hidden + offset + dimension]
+                    })
+                    .sum::<f32>()
+                    * scale;
+            }
+            let maximum = scores.iter().copied().fold(f32::NEG_INFINITY, f32::max);
+            let denominator: f32 = scores.iter().map(|score| (*score - maximum).exp()).sum();
+            for dimension in 0..head_dim {
+                expected[query * hidden + offset + dimension] = scores
+                    .iter()
+                    .enumerate()
+                    .map(|(key, score)| {
+                        (*score - maximum).exp() * v[key * hidden + offset + dimension]
+                    })
+                    .sum::<f32>()
+                    / denominator;
+            }
+        }
+    }
+
+    let gpu = dinovision::init_context(None).expect("GPU context");
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    session.set_input("q", &q);
+    session.set_input("k", &k);
+    session.set_input("v", &v);
+    session.step();
+    session.wait();
+    let actual = session.read_output(expected.len());
+    let maximum_error = actual
+        .iter()
+        .zip(&expected)
+        .map(|(a, b)| (a - b).abs())
+        .fold(0.0f32, f32::max);
+    assert!(
+        maximum_error < 2e-4,
+        "full attention differs by {maximum_error} at DINOv3 shape"
+    );
+}
+
+#[test]
+fn trailing_layer_scale_matches_cpu_at_dinov3_shape() {
+    let tokens = 201usize;
+    let hidden = 384usize;
+    let mut graph = Graph::new();
+    let input = graph.input("input", &[tokens, hidden]);
+    let gain = graph.input("gain", &[hidden]);
+    let transposed = graph.transpose(input);
+    let flat = graph.reshape(transposed, &[hidden * tokens]);
+    let scaled = graph.mul_per_channel(flat, gain, hidden as u32, tokens as u32);
+    let scaled = graph.reshape(scaled, &[hidden, tokens]);
+    let output = graph.transpose(scaled);
+    graph.set_outputs(vec![output]);
+
+    let values: Vec<f32> = (0..tokens * hidden)
+        .map(|index| (index as f32 * 0.017).sin())
+        .collect();
+    let gains: Vec<f32> = (0..hidden)
+        .map(|index| 0.1 + index as f32 / hidden as f32)
+        .collect();
+    let expected: Vec<f32> = values
+        .iter()
+        .enumerate()
+        .map(|(index, value)| value * gains[index % hidden])
+        .collect();
+
+    let gpu = dinovision::init_context(None).expect("GPU context");
+    let (mut session, _) = meganeura::train::build(
+        &graph,
+        SessionConfig {
+            mode: Mode::Inference,
+            gpu: Some(gpu),
+            ..Default::default()
+        },
+    );
+    session.set_input("input", &values);
+    session.set_input("gain", &gains);
+    session.step();
+    session.wait();
+    let actual = session.read_output(expected.len());
+    let maximum_error = actual
+        .iter()
+        .zip(&expected)
+        .map(|(a, b)| (a - b).abs())
+        .fold(0.0f32, f32::max);
+    assert!(
+        maximum_error < 1e-5,
+        "trailing LayerScale differs by {maximum_error}"
+    );
+}

environment/training-source/source-snapshot/tests/semantics.rs

@@ -0,0 +1,133 @@
+//! Do the features actually mean anything?
+//!
+//! The point of DINO features is that patches of the same thing land near
+//! each other in feature space regardless of position, and patches of
+//! different things do not. That property is what the PCA colouring
+//! displays and what any downstream use would rely on, and it is
+//! surprisingly sensitive to exactly the mistakes that are easy to make
+//! here: a transposed projection, a mis-paired RoPE half, or a patch
+//! flattening in the wrong channel order all leave the magnitudes looking
+//! healthy while destroying the structure.
+//!
+//! So rather than compare against a reference dump — which would need
+//! torch on the machine — this checks the property directly, using a scene
+//! with known regions.
+//!
+//! Requires the checkpoint. Set `DINOVISION_WEIGHTS` to a
+//! `model.safetensors`; without it the test reports itself skipped, since
+//! failing for a missing asset would be noise.
+
+use dinovision::dinov3::Config;
+
+/// Cosine similarity, the metric DINO features are usually compared under.
+fn cosine(a: &[f32], b: &[f32]) -> f32 {
+    let dot: f32 = a.iter().zip(b).map(|(x, y)| x * y).sum();
+    let na: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
+    let nb: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();
+    dot / (na * nb).max(f32::MIN_POSITIVE)
+}
+
+/// A scene with four unambiguous regions, drawn as flat colour blocks so
+/// the expected grouping is not a matter of opinion. Quadrants, at 224²:
+/// top-left red, top-right green, bottom-left blue, bottom-right a fine
+/// checkerboard (same mean colour as the background, different texture).
+fn quadrant_scene(size: usize) -> Vec<u8> {
+    let mut rgb = vec![0u8; size * size * 3];
+    let half = size / 2;
+    for y in 0..size {
+        for x in 0..size {
+            let px = match (x < half, y < half) {
+                (true, true) => [200, 40, 40],
+                (false, true) => [40, 180, 60],
+                (true, false) => [50, 70, 210],
+                (false, false) => {
+                    let on = ((x / 4) + (y / 4)) % 2 == 0;
+                    if on { [230, 230, 230] } else { [30, 30, 30] }
+                }
+            };
+            let i = (y * size + x) * 3;
+            rgb[i..i + 3].copy_from_slice(&px);
+        }
+    }
+    rgb
+}
+
+/// Index of the patch at grid position (gx, gy), skipping prefix tokens.
+fn patch(features: &[f32], config: &Config, gx: usize, gy: usize) -> Vec<f32> {
+    let t = config.num_prefix_tokens() + gy * config.grid() + gx;
+    let h = config.hidden_size;
+    features[t * h..(t + 1) * h].to_vec()
+}
+
+#[test]
+fn features_group_by_content_not_position() {
+    let Ok(weights) = std::env::var("DINOVISION_WEIGHTS") else {
+        eprintln!("skipped: set DINOVISION_WEIGHTS to a model.safetensors to run this");
+        return;
+    };
+    let weights = std::path::PathBuf::from(weights);
+    if !weights.exists() {
+        eprintln!("skipped: {} does not exist", weights.display());
+        return;
+    }
+
+    let config = Config::vits16().at_resolution(224);
+    let gpu = dinovision::init_context(None).expect("GPU context");
+    let (mut session, _) = dinovision::bench::build_encoder_session(gpu, &config, None);
+    let model = meganeura::data::safetensors::SafeTensorsModel::load(weights).expect("read weights");
+    dinovision::weights::load_encoder(&mut session, &model, &config).expect("bind weights");
+
+    let rgb = quadrant_scene(config.image_size);
+    let patches = dinovision::preprocess::patches_from_rgb8(&rgb, &config);
+    session.set_input("patches", &patches);
+    session.step();
+    session.wait();
+    let features = session.read_output(config.num_tokens() * config.hidden_size);
+    assert!(
+        features.iter().all(|v| v.is_finite()),
+        "features contain non-finite values"
+    );
+
+    // Sample two well-separated patches inside each quadrant, staying away
+    // from the boundaries where receptive fields mix regions.
+    let g = config.grid();
+    let q = g / 4;
+    let regions = [
+        ("red", [(q, q), (q + 1, q + 1)]),
+        ("green", [(g - q - 1, q), (g - q - 2, q + 1)]),
+        ("blue", [(q, g - q - 1), (q + 1, g - q - 2)]),
+        ("checker", [(g - q - 1, g - q - 1), (g - q - 2, g - q - 2)]),
+    ];
+
+    // Within a region, two patches of the same material should be close.
+    let mut worst_within = 1.0f32;
+    for (name, pts) in &regions {
+        let a = patch(&features, &config, pts[0].0, pts[0].1);
+        let b = patch(&features, &config, pts[1].0, pts[1].1);
+        let c = cosine(&a, &b);
+        eprintln!("within {name:>8}: {c:.3}");
+        worst_within = worst_within.min(c);
+    }
+
+    // Across regions, patches of different material should be further apart
+    // than any same-material pair.
+    let mut best_across = -1.0f32;
+    for i in 0..regions.len() {
+        for j in (i + 1)..regions.len() {
+            let a = patch(&features, &config, regions[i].1[0].0, regions[i].1[0].1);
+            let b = patch(&features, &config, regions[j].1[0].0, regions[j].1[0].1);
+            let c = cosine(&a, &b);
+            eprintln!("across {:>8}/{:<8}: {c:.3}", regions[i].0, regions[j].0);
+            best_across = best_across.max(c);
+        }
+    }
+
+    eprintln!("worst within-region {worst_within:.3}, best across-region {best_across:.3}");
+    assert!(
+        worst_within > best_across,
+        "features do not separate content: the least similar same-region pair \
+         ({worst_within:.3}) scored below the most similar different-region pair \
+         ({best_across:.3}). A scrambled patch order or transposed projection \
+         looks exactly like this."
+    );
+}

environment/training-source/source-snapshot/tests/threading.rs

@@ -0,0 +1,29 @@
+//! Compile-time constraints that dictate how inference is threaded.
+//!
+//! `blade_graphics::Context` is `Send + Sync` — it guards its queue,
+//! memory manager, and XR session state behind mutexes — so an
+//! `Arc<Context>` can be shared with a worker thread.
+//!
+//! `meganeura::Session` is **not** `Send`: it owns a
+//! `blade_graphics::CommandEncoder`. The single offending field is
+//! `ScratchBuffer::mapped`, a raw pointer into a persistently mapped
+//! allocation — everything else is Vulkan handles, which are fine. (Rust has
+//! no stable way to *assert* a negative, hence a comment not a test.)
+//!
+//! That is why [`dinovision::inference`] hands the worker an
+//! `Arc<Context>` and has it construct the session in place. A one-line
+//! `unsafe impl Send for ScratchBuffer` in blade lifts the constraint —
+//! verified, and on the `command-encoder-send` branch there.
+
+fn assert_send<T: Send>() {}
+fn assert_sync<T: Sync>() {}
+
+#[test]
+fn context_can_be_shared_across_threads() {
+    assert_send::<blade_graphics::Context>();
+    assert_sync::<blade_graphics::Context>();
+    // Buffer handles carry explicit `unsafe impl Send/Sync`, so GPU-side
+    // results can be published to the render thread by handle.
+    assert_send::<blade_graphics::Buffer>();
+    assert_sync::<blade_graphics::Buffer>();
+}

environment/training-source/source-snapshot/tools/build_android_artifacts.ps1

@@ -0,0 +1,121 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir,
+    [string]$AndroidSdk,
+    [string]$NdkRoot
+)
+
+$ErrorActionPreference = 'Stop'
+$repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+if (-not $AndroidSdk) {
+    if (-not $env:LOCALAPPDATA) { throw 'pass -AndroidSdk when LOCALAPPDATA is unavailable' }
+    $AndroidSdk = Join-Path $env:LOCALAPPDATA 'Android\Sdk'
+}
+$sdk = (Resolve-Path $AndroidSdk).Path
+if (-not $NdkRoot) { $NdkRoot = Join-Path $sdk 'ndk\27.0.12077973' }
+$ndk = (Resolve-Path $NdkRoot).Path
+$clang = Join-Path $ndk 'toolchains\llvm\prebuilt\windows-x86_64\bin\aarch64-linux-android34-clang.cmd'
+$ar = Join-Path $ndk 'toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-ar.exe'
+foreach ($tool in @($clang, $ar)) {
+    if (-not (Test-Path -LiteralPath $tool -PathType Leaf)) { throw "missing NDK tool: $tool" }
+}
+$sourceProperties = Get-Content -Raw -LiteralPath (Join-Path $ndk 'source.properties')
+if ($sourceProperties -notmatch '(?m)^Pkg\.Revision\s*=\s*27\.') {
+    throw "DinoVision's API-34 camera build requires NDK r27; got $sourceProperties"
+}
+
+$destination = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $destination) {
+    if (@(Get-ChildItem -LiteralPath $destination -Force).Count -ne 0) {
+        throw "Refusing to merge Android build output into non-empty directory: $destination"
+    }
+} else {
+    New-Item -ItemType Directory -Path $destination | Out-Null
+}
+
+$env:ANDROID_HOME = $sdk
+$env:ANDROID_SDK_ROOT = $sdk
+$env:ANDROID_NDK_ROOT = $ndk
+$env:ANDROID_NDK_HOME = $ndk
+$env:CARGO_TARGET_AARCH64_LINUX_ANDROID_LINKER = $clang
+$env:CC_aarch64_linux_android = $clang
+$env:AR_aarch64_linux_android = $ar
+$cargo = (Get-Command cargo).Source
+
+function Run-Cargo([string[]]$Arguments, [string]$Name) {
+    $process = Start-Process `
+        -FilePath $cargo `
+        -ArgumentList $Arguments `
+        -NoNewWindow `
+        -Wait `
+        -PassThru `
+        -RedirectStandardOutput (Join-Path $destination "$Name.stdout.log") `
+        -RedirectStandardError (Join-Path $destination "$Name.stderr.log")
+    if ($process.ExitCode -ne 0) {
+        throw "$Name failed with code $($process.ExitCode)"
+    }
+}
+
+Push-Location $repo
+try {
+    Run-Cargo @(
+        'build', '--locked', '--release', '--target', 'aarch64-linux-android',
+        '--example', 'bench', '--example', 'evaluate_decoder'
+    ) 'native-build'
+    Run-Cargo @('apk', 'build', '--release', '--package', 'dinovision-xr') 'apk-build'
+} finally {
+    Pop-Location
+}
+
+$built = [ordered]@{
+    'bench' = Join-Path $repo 'target\aarch64-linux-android\release\examples\bench'
+    'evaluate_decoder' = Join-Path $repo 'target\aarch64-linux-android\release\examples\evaluate_decoder'
+    'dinovision_xr.apk' = Join-Path $repo 'target\release\apk\dinovision_xr.apk'
+}
+$artifacts = @()
+foreach ($entry in $built.GetEnumerator()) {
+    if (-not (Test-Path -LiteralPath $entry.Value -PathType Leaf)) {
+        throw "expected Android artifact is missing: $($entry.Value)"
+    }
+    $target = Join-Path $destination $entry.Key
+    Copy-Item -LiteralPath $entry.Value -Destination $target
+    $artifacts += [ordered]@{
+        name = $entry.Key
+        bytes = (Get-Item -LiteralPath $target).Length
+        sha256 = (Get-FileHash -LiteralPath $target -Algorithm SHA256).Hash.ToLowerInvariant()
+    }
+}
+
+$buildTools = Get-ChildItem -LiteralPath (Join-Path $sdk 'build-tools') -Directory |
+    Sort-Object { [version]$_.Name } -Descending |
+    Select-Object -First 1
+$aapt = Join-Path $buildTools.FullName 'aapt.exe'
+if (-not (Test-Path -LiteralPath $aapt -PathType Leaf)) { throw 'aapt.exe was not found' }
+& $aapt dump badging (Join-Path $destination 'dinovision_xr.apk') |
+    Set-Content -LiteralPath (Join-Path $destination 'apk-badging.txt') -Encoding utf8
+if ($LASTEXITCODE -ne 0) { throw 'could not inspect the XR APK manifest' }
+$badging = Get-Content -Raw -LiteralPath (Join-Path $destination 'apk-badging.txt')
+if ($badging -notmatch "package: name='rust\.dinovision_xr'" -or
+    $badging -notmatch "launchable-activity: name='android\.app\.NativeActivity'") {
+    throw 'XR APK package/activity does not match the device harness defaults'
+}
+
+$cargoApk = (Get-Command cargo-apk).Source
+$record = [ordered]@{
+    schema_version = 1
+    completed_utc = [DateTime]::UtcNow.ToString('o')
+    target = 'aarch64-linux-android'
+    android_api = 34
+    android_sdk = $sdk
+    ndk = $ndk
+    ndk_source_properties = $sourceProperties.Trim()
+    rustc = (& rustc --version --verbose) -join "`n"
+    cargo = (& $cargo --version --verbose) -join "`n"
+    cargo_apk_sha256 = (Get-FileHash -LiteralPath $cargoApk -Algorithm SHA256).Hash.ToLowerInvariant()
+    package = 'rust.dinovision_xr'
+    activity = 'android.app.NativeActivity'
+    artifacts = $artifacts
+}
+$record | ConvertTo-Json -Depth 6 |
+    Set-Content -LiteralPath (Join-Path $destination 'android-build.json') -Encoding utf8
+Write-Output "wrote checked Android artifacts to $destination"

environment/training-source/source-snapshot/tools/collect_artifact_metadata.ps1

@@ -0,0 +1,156 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir,
+    [string]$Model,
+    [string]$Decoder
+)
+
+$ErrorActionPreference = 'Stop'
+$git = 'C:\Portables\cmder\vendor\git-for-windows\cmd\git.exe'
+$root = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$meganeura = (Resolve-Path (Join-Path $root '..\meganeura')).Path
+$blade = (Resolve-Path (Join-Path $root '..\blade')).Path
+$adbCandidates = @()
+if ($env:LOCALAPPDATA) {
+    $adbCandidates += Join-Path $env:LOCALAPPDATA 'Android\Sdk\platform-tools\adb.exe'
+}
+if ($env:ANDROID_HOME) {
+    $adbCandidates += Join-Path $env:ANDROID_HOME 'platform-tools\adb.exe'
+}
+$adbCandidates = @($adbCandidates | Where-Object { Test-Path -LiteralPath $_ })
+$adb = if ($adbCandidates.Count -gt 0) { $adbCandidates[0] } else { $null }
+$out = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $out) {
+    if (@(Get-ChildItem -LiteralPath $out -Force).Count -ne 0) {
+        throw "Refusing to merge environment metadata into non-empty directory: $out"
+    }
+} else {
+    New-Item -ItemType Directory -Path $out | Out-Null
+}
+
+function Git-State([string]$repo) {
+    $revision = (& $git -C $repo rev-parse HEAD).Trim()
+    $branch = (& $git -C $repo branch --show-current).Trim()
+    $status = @(& $git -C $repo status --porcelain=v1)
+    [ordered]@{
+        path = $repo
+        revision = $revision
+        branch = $branch
+        clean = $status.Count -eq 0
+        status = $status
+    }
+}
+
+$cargoMetadata = (& cargo metadata --format-version 1 --locked | ConvertFrom-Json)
+$resolvedPackages = [ordered]@{}
+foreach ($name in @('meganeura', 'blade-graphics')) {
+    $package = @($cargoMetadata.packages | Where-Object { $_.name -eq $name })
+    $resolvedPackages[$name] = @(
+        $package | ForEach-Object {
+            [ordered]@{
+                version = $_.version
+                source = $_.source
+                manifest_path = $_.manifest_path
+            }
+        }
+    )
+}
+
+$metadata = [ordered]@{
+    schema_version = 1
+    collected_utc = [DateTime]::UtcNow.ToString('o')
+    dinovision = Git-State $root
+    meganeura = Git-State $meganeura
+    blade_checkout = Git-State $blade
+    resolved_packages = $resolvedPackages
+    rustc = (& rustc --version --verbose) -join "`n"
+    cargo = (& cargo --version --verbose) -join "`n"
+    os = [System.Environment]::OSVersion.VersionString
+    android_ndk_root = $env:ANDROID_NDK_ROOT
+    android_ndks = if ($env:ANDROID_HOME) {
+        @(
+            Get-ChildItem -LiteralPath (Join-Path $env:ANDROID_HOME 'ndk') -Directory -ErrorAction SilentlyContinue |
+                Select-Object -ExpandProperty Name
+        )
+    } else { @() }
+    nvidia_smi = if (Get-Command nvidia-smi -ErrorAction SilentlyContinue) {
+        (& nvidia-smi --query-gpu=name,driver_version --format=csv,noheader) -join "`n"
+    } else { $null }
+    adb = if ($adb) { (& $adb version) -join "`n" } else { $null }
+    model = $null
+    decoder = $null
+    quest_connected = $false
+}
+
+# A Git revision alone is not sufficient while the experiment is being
+# developed in a dirty tree. Preserve the exact tracked patch and hash every
+# tracked or untracked, non-ignored source file. The paper freeze should be a
+# clean commit; this fallback makes development runs auditable instead of
+# silently attributing them to HEAD.
+$workingPatch = Join-Path $out 'dinovision-working-tree.patch'
+& $git -C $root diff --binary --no-ext-diff --output=$workingPatch HEAD
+if ($LASTEXITCODE -ne 0) { throw 'could not preserve the DinoVision working-tree patch' }
+$sourceFiles = @(
+    & $git -C $root ls-files --cached --others --exclude-standard |
+        Where-Object { $_ -and (Test-Path -LiteralPath (Join-Path $root $_)) }
+)
+$metadata.dinovision['working_patch_sha256'] = (
+    Get-FileHash -LiteralPath $workingPatch -Algorithm SHA256
+).Hash.ToLowerInvariant()
+$metadata.dinovision['source_files'] = @(
+    $sourceFiles | ForEach-Object {
+        $path = Join-Path $root $_
+        [ordered]@{
+            path = $_.Replace('\', '/')
+            bytes = (Get-Item -LiteralPath $path).Length
+            sha256 = (Get-FileHash -LiteralPath $path -Algorithm SHA256).Hash.ToLowerInvariant()
+        }
+    }
+)
+$sourceSnapshot = Join-Path $out 'dinovision-source-snapshot'
+foreach ($relative in $sourceFiles) {
+    $source = Join-Path $root $relative
+    $target = Join-Path $sourceSnapshot $relative
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $target) | Out-Null
+    Copy-Item -LiteralPath $source -Destination $target
+}
+
+foreach ($asset in @(@('model', $Model), @('decoder', $Decoder))) {
+    if ($asset[1] -and (Test-Path -LiteralPath $asset[1])) {
+        $file = Get-Item -LiteralPath $asset[1]
+        $metadata[$asset[0]] = [ordered]@{
+            path = $file.FullName
+            bytes = $file.Length
+            sha256 = (Get-FileHash -Algorithm SHA256 -LiteralPath $file.FullName).Hash.ToLowerInvariant()
+        }
+    }
+}
+
+& cargo tree --locked | Set-Content -Encoding utf8 (Join-Path $out 'cargo-tree.txt')
+Copy-Item -LiteralPath (Join-Path $root 'Cargo.lock') -Destination (Join-Path $out 'Cargo.lock')
+
+$deviceLines = if ($adb) { @(& $adb devices) } else { @() }
+$connected = @($deviceLines | Select-Object -Skip 1 | Where-Object { $_ -match "`tdevice$" })
+if ($connected.Count -gt 0) {
+    $metadata.quest_connected = $true
+    & $adb shell getprop | Set-Content -Encoding utf8 (Join-Path $out 'quest-getprop.txt')
+    & $adb shell dumpsys thermalservice | Set-Content -Encoding utf8 (Join-Path $out 'quest-thermal.txt')
+    & $adb shell dumpsys battery | Set-Content -Encoding utf8 (Join-Path $out 'quest-battery.txt')
+    & $adb shell dumpsys power | Set-Content -Encoding utf8 (Join-Path $out 'quest-power.txt')
+    & $adb shell dumpsys SurfaceFlinger | Select-String -Pattern 'refresh|fps|Display' |
+        Set-Content -Encoding utf8 (Join-Path $out 'quest-display.txt')
+    $toggles = @(
+        'raw_camera', 'mono', 'camera_half_fov_deg',
+        'inference_interval_ms', 'submission_chunks', 'capture'
+    )
+    $toggleState = [ordered]@{}
+    foreach ($toggle in $toggles) {
+        $path = "/data/local/tmp/dinovision/$toggle"
+        $value = (& $adb shell "if [ -e '$path' ]; then cat '$path' 2>/dev/null || echo '<present>'; else echo '<absent>'; fi").Trim()
+        $toggleState[$toggle] = $value
+    }
+    $toggleState | ConvertTo-Json -Depth 4 | Set-Content -Encoding utf8 (Join-Path $out 'quest-runtime-toggles.json')
+}
+
+$metadata | ConvertTo-Json -Depth 8 | Set-Content -Encoding utf8 (Join-Path $out 'metadata.json')
+Write-Output "wrote metadata to $out"

environment/training-source/source-snapshot/tools/compare_f32.py

@@ -0,0 +1,170 @@
+#!/usr/bin/env python3
+"""Compare two raw little-endian f32 tensors and emit an auditable record."""
+
+from __future__ import annotations
+
+import argparse
+import array
+import hashlib
+import json
+import math
+import sys
+from pathlib import Path
+
+
+def read_tensor(path: Path) -> array.array[float]:
+    data = path.read_bytes()
+    if len(data) % 4:
+        raise SystemExit(f"{path} is not a whole number of f32 values")
+    values = array.array("f")
+    values.frombytes(data)
+    if sys.byteorder != "little":
+        values.byteswap()
+    return values
+
+
+def sha256(path: Path) -> str:
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("reference", type=Path)
+    parser.add_argument("candidate", type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--max-relative-l2", type=float)
+    parser.add_argument("--min-cosine", type=float)
+    parser.add_argument("--row-size", type=int)
+    parser.add_argument("--min-row-cosine", type=float)
+    args = parser.parse_args()
+    if args.min_row_cosine is not None and args.row_size is None:
+        raise SystemExit("--min-row-cosine requires --row-size")
+
+    reference = read_tensor(args.reference)
+    candidate = read_tensor(args.candidate)
+    if len(reference) != len(candidate):
+        raise SystemExit(
+            f"length mismatch: {args.reference} has {len(reference)}, "
+            f"{args.candidate} has {len(candidate)}"
+        )
+
+    squared_error = 0.0
+    squared_reference = 0.0
+    squared_candidate = 0.0
+    dot = 0.0
+    absolute_error = 0.0
+    max_absolute_error = -1.0
+    max_absolute_index = 0
+    for index, (expected, actual) in enumerate(zip(reference, candidate)):
+        difference = float(actual) - float(expected)
+        squared_error += difference * difference
+        squared_reference += float(expected) * float(expected)
+        squared_candidate += float(actual) * float(actual)
+        dot += float(expected) * float(actual)
+        absolute_error += abs(difference)
+        if abs(difference) > max_absolute_error:
+            max_absolute_error = abs(difference)
+            max_absolute_index = index
+
+    relative_l2 = math.sqrt(squared_error) / max(math.sqrt(squared_reference), sys.float_info.min)
+    cosine = dot / max(
+        math.sqrt(squared_reference) * math.sqrt(squared_candidate),
+        sys.float_info.min,
+    )
+    row_metrics = None
+    if args.row_size is not None:
+        if args.row_size <= 0 or len(reference) % args.row_size:
+            raise SystemExit("--row-size must be positive and divide the tensor length")
+        minimum_cosine = math.inf
+        minimum_cosine_row = 0
+        maximum_relative_l2 = -math.inf
+        maximum_relative_l2_row = 0
+        for row in range(len(reference) // args.row_size):
+            start = row * args.row_size
+            end = start + args.row_size
+            row_reference = reference[start:end]
+            row_candidate = candidate[start:end]
+            row_dot = sum(float(a) * float(b) for a, b in zip(row_reference, row_candidate))
+            row_reference_squared = sum(float(value) ** 2 for value in row_reference)
+            row_candidate_squared = sum(float(value) ** 2 for value in row_candidate)
+            row_error_squared = sum(
+                (float(actual) - float(expected)) ** 2
+                for expected, actual in zip(row_reference, row_candidate)
+            )
+            row_cosine = row_dot / max(
+                math.sqrt(row_reference_squared) * math.sqrt(row_candidate_squared),
+                sys.float_info.min,
+            )
+            row_relative_l2 = math.sqrt(row_error_squared) / max(
+                math.sqrt(row_reference_squared), sys.float_info.min
+            )
+            if row_cosine < minimum_cosine:
+                minimum_cosine = row_cosine
+                minimum_cosine_row = row
+            if row_relative_l2 > maximum_relative_l2:
+                maximum_relative_l2 = row_relative_l2
+                maximum_relative_l2_row = row
+        row_metrics = {
+            "row_size": args.row_size,
+            "rows": len(reference) // args.row_size,
+            "minimum_cosine": minimum_cosine,
+            "minimum_cosine_row": minimum_cosine_row,
+            "maximum_relative_l2": maximum_relative_l2,
+            "maximum_relative_l2_row": maximum_relative_l2_row,
+        }
+    checks = {
+        "max_relative_l2": (
+            None
+            if args.max_relative_l2 is None
+            else relative_l2 <= args.max_relative_l2
+        ),
+        "min_cosine": (
+            None if args.min_cosine is None else cosine >= args.min_cosine
+        ),
+        "min_row_cosine": (
+            None
+            if args.min_row_cosine is None
+            else row_metrics is not None
+            and row_metrics["minimum_cosine"] >= args.min_row_cosine
+        ),
+    }
+    passed = all(value is not False for value in checks.values())
+    record = {
+        "schema_version": 1,
+        "reference": str(args.reference).replace("\\", "/"),
+        "reference_sha256": sha256(args.reference),
+        "candidate": str(args.candidate).replace("\\", "/"),
+        "candidate_sha256": sha256(args.candidate),
+        "elements": len(reference),
+        "relative_l2": relative_l2,
+        "cosine": cosine,
+        "mean_absolute_error": absolute_error / len(reference),
+        "max_absolute_error": max_absolute_error,
+        "max_absolute_index": max_absolute_index,
+        "thresholds": {
+            "max_relative_l2": args.max_relative_l2,
+            "min_cosine": args.min_cosine,
+            "min_row_cosine": args.min_row_cosine,
+        },
+        "row_metrics": row_metrics,
+        "checks": checks,
+        "passed": passed,
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps(record, indent=2) + "\n", encoding="utf-8")
+    row_text = (
+        ""
+        if row_metrics is None
+        else f", minimum row cosine {row_metrics['minimum_cosine']:.9f}"
+    )
+    print(
+        f"relative L2 {relative_l2:.6g}, cosine {cosine:.9f}{row_text}, "
+        f"max abs {max_absolute_error:.6g} at {max_absolute_index}: "
+        f"{'PASS' if passed else 'FAIL'}"
+    )
+    if not passed:
+        raise SystemExit(1)
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/convert_decoder.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Convert DinoVision's runtime decoder.bin into named SafeTensors."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+import numpy as np
+from safetensors.numpy import load_file, save_file
+
+
+STAGES = (256, 128, 64, 32)
+BLEND_STAGES = 2
+
+
+def sha256(path: Path) -> str:
+    hasher = hashlib.sha256()
+    with path.open("rb") as source:
+        for chunk in iter(lambda: source.read(1024 * 1024), b""):
+            hasher.update(chunk)
+    return hasher.hexdigest()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--training", required=True, type=Path)
+    parser.add_argument("--input", type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+
+    training = json.loads(args.training.read_text(encoding="utf-8"))
+    source = args.input or args.training.parent / "decoder.bin"
+    source_hash = sha256(source)
+    if source_hash != training["decoder_sha256"]:
+        raise SystemExit(
+            f"{source} has SHA-256 {source_hash}; training record expects "
+            f"{training['decoder_sha256']}"
+        )
+
+    flat = np.fromfile(source, dtype="<f4")
+    offset = 0
+    tensors: dict[str, np.ndarray] = {}
+
+    def take(name: str, shape: tuple[int, ...]) -> None:
+        nonlocal offset
+        count = int(np.prod(shape))
+        end = offset + count
+        if end > len(flat):
+            raise SystemExit(f"{source} ends inside tensor {name}")
+        tensors[name] = flat[offset:end].reshape(shape).copy()
+        offset = end
+
+    def block(name: str, in_channels: int, out_channels: int) -> None:
+        take(f"{name}.weight", (out_channels, in_channels, 3, 3))
+        take(f"{name}.bias", (out_channels,))
+        take(f"{name}.norm.weight", (out_channels,))
+        take(f"{name}.norm.bias", (out_channels,))
+
+    in_channels = 384
+    for index, out_channels in enumerate(STAGES):
+        block(f"dec.{index}", in_channels, out_channels)
+        if index < BLEND_STAGES:
+            block(f"dec.{index}b", out_channels, out_channels)
+        in_channels = out_channels
+    take("dec.out.weight", (3, in_channels, 3, 3))
+    take("dec.out.bias", (3,))
+    if offset != len(flat):
+        raise SystemExit(f"{source} has {len(flat) - offset} trailing f32 values")
+
+    metadata = {
+        "format": "dinovision-decoder-v1",
+        "source_decoder_sha256": source_hash,
+        "model_sha256": training["model_sha256"],
+        "dataset_manifest_sha256": training["dataset_manifest_sha256"],
+        "encoder_layers": str(training["encoder_layers"]),
+        "image_size": str(training["image_size"]),
+        "seed": str(training["seed"]),
+        "objective": training["objective"],
+    }
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    save_file(tensors, args.output, metadata=metadata)
+    loaded = load_file(args.output)
+    for name, expected in tensors.items():
+        if name not in loaded or not np.array_equal(expected, loaded[name]):
+            raise SystemExit(f"SafeTensors roundtrip changed tensor {name}")
+    print(
+        f"wrote {args.output}: {len(tensors)} named tensors, "
+        f"SHA-256 {sha256(args.output)}"
+    )
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/dump_reference.py

@@ -0,0 +1,228 @@
+#!/usr/bin/env python3
+"""Dump a DINOv3 reference forward pass for `cargo run --example verify`.
+
+Writes three files into the output directory:
+
+  pixel_values.bin   f32 [3, S, S]      the preprocessed input tensor
+  features.bin       f32 [tokens, 384]  expected last_hidden_state
+  model.safetensors                     weights, in the graph's naming
+
+Dumping the *preprocessed* pixel tensor rather than an image is deliberate:
+it keeps resize and normalization differences out of the comparison, so a
+mismatch in `verify` is a mismatch in the graph, not in the resampling
+filter.
+
+Saving the state dict here rather than downloading it in Rust also means
+`verify` needs no Hub access and no license acceptance at run time.
+
+    pip install torch transformers safetensors pillow numpy
+    huggingface-cli login          # facebook/... is license-gated
+    python tools/dump_reference.py --out ref/
+
+The weights are gated. Accept the DINOv3 license on the canonical model page
+and authenticate with Hugging Face before running this script.
+"""
+
+import argparse
+import hashlib
+import json
+import pathlib
+
+import numpy as np
+import torch
+import transformers
+from safetensors.torch import save_file
+from transformers import AutoModel
+from transformers.models.dinov3_vit.modeling_dinov3_vit import (
+    apply_rotary_pos_emb,
+    eager_attention_forward,
+)
+
+DEFAULT_MODEL = "facebook/dinov3-vits16-pretrain-lvd1689m"
+IMAGE_MEAN = np.array([0.485, 0.456, 0.406], dtype=np.float32)
+IMAGE_STD = np.array([0.229, 0.224, 0.225], dtype=np.float32)
+
+
+def build_input(size: int, image: str | None) -> np.ndarray:
+    """Return a normalized f32 CHW tensor."""
+    if image is not None:
+        from PIL import Image
+
+        rgb = Image.open(image).convert("RGB").resize((size, size), Image.BILINEAR)
+        hwc = np.asarray(rgb, dtype=np.float32) / 255.0
+    else:
+        # A smooth, deterministic pattern. Smooth matters: white noise makes
+        # every patch statistically identical, which would hide a bug in the
+        # patch ordering or in the position encoding.
+        ys, xs = np.mgrid[0:size, 0:size].astype(np.float32)
+        u, v = xs / size, ys / size
+        hwc = np.stack(
+            [
+                0.5 + 0.5 * np.sin(6.0 * u + 2.0 * v),
+                0.5 + 0.5 * np.sin(4.0 * v - 3.0 * u * v),
+                0.5 + 0.5 * np.cos(5.0 * u * v + u),
+            ],
+            axis=-1,
+        ).astype(np.float32)
+
+    chw = ((hwc - IMAGE_MEAN) / IMAGE_STD).transpose(2, 0, 1)
+    return np.ascontiguousarray(chw, dtype=np.float32)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--out", default="ref", type=pathlib.Path)
+    ap.add_argument("--model", default=DEFAULT_MODEL)
+    ap.add_argument("--size", type=int, default=224)
+    ap.add_argument(
+        "--layers",
+        type=int,
+        default=12,
+        help="number of leading encoder layers to execute before the final norm",
+    )
+    ap.add_argument("--image", default=None, help="optional real photo instead of a test pattern")
+    args = ap.parse_args()
+
+    if args.size % 16:
+        raise SystemExit(f"--size {args.size} is not a multiple of the patch size (16)")
+
+    args.out.mkdir(parents=True, exist_ok=True)
+
+    model = AutoModel.from_pretrained(args.model, dtype=torch.float32).eval()
+    cfg = model.config
+    print(
+        f"{args.model}: {cfg.num_hidden_layers} layers, hidden {cfg.hidden_size}, "
+        f"{cfg.num_register_tokens} register tokens, gated_mlp={cfg.use_gated_mlp}"
+    )
+    if cfg.use_gated_mlp:
+        raise SystemExit("the Rust graph implements the plain MLP only (ViT-S/B)")
+    if not 0 <= args.layers <= cfg.num_hidden_layers:
+        raise SystemExit(
+            f"--layers must be in [0, {cfg.num_hidden_layers}], got {args.layers}"
+        )
+
+    chw = build_input(args.size, args.image)
+    pixels = torch.from_numpy(chw)[None]
+    with torch.no_grad():
+        hidden_states = model.embeddings(pixels)
+        embeddings = hidden_states[0].numpy().astype(np.float32)
+        position_embeddings = model.rope_embeddings(pixels)
+        first_layer = model.model.layer[0]
+        first_norm1 = first_layer.norm1(hidden_states)
+        first_q = first_layer.attention.q_proj(first_norm1)
+        first_k = first_layer.attention.k_proj(first_norm1)
+        first_v = first_layer.attention.v_proj(first_norm1)
+        tokens = first_q.shape[1]
+        heads = cfg.num_attention_heads
+        head_dim = cfg.hidden_size // heads
+        q_heads = first_q.view(1, tokens, heads, head_dim).transpose(1, 2)
+        k_heads = first_k.view(1, tokens, heads, head_dim).transpose(1, 2)
+        v_heads = first_v.view(1, tokens, heads, head_dim).transpose(1, 2)
+        q_rope, k_rope = apply_rotary_pos_emb(
+            q_heads, k_heads, *position_embeddings
+        )
+        first_attention, _ = eager_attention_forward(
+            first_layer.attention,
+            q_rope,
+            k_rope,
+            v_heads,
+            None,
+            scaling=first_layer.attention.scaling,
+        )
+        first_attention = first_attention.reshape(1, tokens, cfg.hidden_size)
+        first_attention_projected = first_layer.attention.o_proj(first_attention)
+        first_attention_scaled = first_layer.layer_scale1(
+            first_attention_projected
+        )
+        first_residual = hidden_states + first_attention_scaled
+        first_norm2 = first_layer.norm2(first_residual)
+        first_mlp_up = first_layer.mlp.up_proj(first_norm2)
+        first_mlp_activated = first_layer.mlp.act_fn(first_mlp_up)
+        first_mlp_down = first_layer.mlp.down_proj(first_mlp_activated)
+        first_mlp_scaled = first_layer.layer_scale2(first_mlp_down)
+        first_output = first_residual + first_mlp_scaled
+        first_final_norm = model.norm(first_output)
+        for layer in model.model.layer[: args.layers]:
+            hidden_states = layer(
+                hidden_states, position_embeddings=position_embeddings
+            )
+        features = model.norm(hidden_states)[0].numpy().astype(np.float32)
+
+    grid = args.size // cfg.patch_size
+    expected_tokens = 1 + cfg.num_register_tokens + grid * grid
+    assert features.shape == (expected_tokens, cfg.hidden_size), features.shape
+
+    (args.out / "pixel_values.bin").write_bytes(chw.tobytes())
+    (args.out / "embeddings.bin").write_bytes(
+        np.ascontiguousarray(embeddings).tobytes()
+    )
+    for name, tensor in {
+        "first-norm1.bin": first_norm1,
+        "first-q.bin": first_q,
+        "first-k.bin": first_k,
+        "first-v.bin": first_v,
+        "first-q-rope.bin": q_rope.transpose(1, 2).reshape(
+            1, tokens, cfg.hidden_size
+        ),
+        "first-k-rope.bin": k_rope.transpose(1, 2).reshape(
+            1, tokens, cfg.hidden_size
+        ),
+        "first-attention.bin": first_attention,
+        "first-attention-projected.bin": first_attention_projected,
+        "first-attention-scaled.bin": first_attention_scaled,
+        "first-residual.bin": first_residual,
+        "first-norm2.bin": first_norm2,
+        "first-mlp-up.bin": first_mlp_up,
+        "first-mlp-activated.bin": first_mlp_activated,
+        "first-mlp-down.bin": first_mlp_down,
+        "first-mlp-scaled.bin": first_mlp_scaled,
+        "first-output.bin": first_output,
+        "first-final-norm.bin": first_final_norm,
+    }.items():
+        (args.out / name).write_bytes(
+            np.ascontiguousarray(tensor[0].numpy().astype(np.float32)).tobytes()
+        )
+    (args.out / "features.bin").write_bytes(np.ascontiguousarray(features).tobytes())
+
+    # `save_file` rejects shared storage, which `state_dict()` can contain.
+    state = {k: v.contiguous().clone() for k, v in model.state_dict().items()}
+    save_file(state, str(args.out / "model.safetensors"))
+
+    def sha256(path: pathlib.Path) -> str:
+        return hashlib.sha256(path.read_bytes()).hexdigest()
+
+    local_model = pathlib.Path(args.model)
+    reference = {
+        "schema_version": 1,
+        "base_model": DEFAULT_MODEL if local_model.is_dir() else args.model,
+        "model_source": str(args.model),
+        "image_size": args.size,
+        "encoder_layers": args.layers,
+        "tokens": expected_tokens,
+        "hidden_size": cfg.hidden_size,
+        "torch_version": torch.__version__,
+        "transformers_version": transformers.__version__,
+        "numpy_version": np.__version__,
+        "pixel_values_sha256": sha256(args.out / "pixel_values.bin"),
+        "embeddings_sha256": sha256(args.out / "embeddings.bin"),
+        "features_sha256": sha256(args.out / "features.bin"),
+        "exported_model_sha256": sha256(args.out / "model.safetensors"),
+    }
+    if local_model.is_dir() and (local_model / "model.safetensors").is_file():
+        reference["source_model_sha256"] = sha256(
+            local_model / "model.safetensors"
+        )
+    (args.out / "reference.json").write_text(
+        json.dumps(reference, indent=2) + "\n", encoding="utf-8"
+    )
+
+    print(
+        f"wrote {args.out}/ — {args.layers} layers, {args.size}x{args.size}, "
+        f"{grid}x{grid} grid, {expected_tokens} tokens"
+    )
+    print(f"features: mean {features.mean():+.4f}  std {features.std():.4f}")
+    print(f"\nnow run:  cargo run --release --example verify -- {args.out}")
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/extract_json_records.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Extract prefixed JSON records from benchmark or logcat text files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--input", action="append", required=True, type=Path)
+    parser.add_argument("--marker", required=True)
+    parser.add_argument("--output", required=True, type=Path)
+    args = parser.parse_args()
+
+    records: list[dict[str, object]] = []
+    decoder = json.JSONDecoder()
+    for path in args.input:
+        for line_number, line in enumerate(
+            path.read_text(encoding="utf-8", errors="replace").splitlines(), start=1
+        ):
+            marker_at = line.find(args.marker)
+            if marker_at < 0:
+                continue
+            payload = line[marker_at + len(args.marker) :].strip()
+            try:
+                record, consumed = decoder.raw_decode(payload)
+            except json.JSONDecodeError as error:
+                raise SystemExit(f"{path}:{line_number}: malformed record: {error}") from error
+            if payload[consumed:].strip():
+                raise SystemExit(f"{path}:{line_number}: trailing text after JSON record")
+            if not isinstance(record, dict):
+                raise SystemExit(f"{path}:{line_number}: record is not a JSON object")
+            record["artifact_source"] = str(path).replace("\\", "/")
+            record["artifact_line"] = line_number
+            records.append(record)
+
+    if not records:
+        raise SystemExit(f"no {args.marker!r} records found")
+    output = {"schema_version": 1, "marker": args.marker, "records": records}
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_text(json.dumps(output, indent=2) + "\n", encoding="utf-8")
+    print(f"wrote {args.output}: {len(records)} records")
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/make_correctness_frame.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+"""Generate the deterministic RGB8 frame used for host/device parity."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--size", type=int, default=224)
+    args = parser.parse_args()
+    if args.size <= 1 or args.size % 16:
+        raise SystemExit("--size must be greater than one and divisible by 16")
+
+    pixels = bytearray()
+    center = (args.size - 1) / 2.0
+    radius_squared = (args.size * 0.28) ** 2
+    for y in range(args.size):
+        for x in range(args.size):
+            red = round(255 * x / (args.size - 1))
+            green = round(255 * y / (args.size - 1))
+            checker = 48 if ((x // 16) ^ (y // 16)) & 1 else 208
+            in_circle = (x - center) ** 2 + (y - center) ** 2 < radius_squared
+            blue = 255 - checker if in_circle else checker
+            pixels.extend((red, green, blue))
+
+    args.output.parent.mkdir(parents=True, exist_ok=True)
+    args.output.write_bytes(pixels)
+    digest = hashlib.sha256(pixels).hexdigest()
+    print(f"wrote {args.output}: {len(pixels)} bytes, SHA-256 {digest}")
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/make_dataset_manifest.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Build a deterministic, leakage-checked DinoVision dataset manifest.
+
+Each --entry supplies SPLIT SOURCE GROUP PATH. PATH is resolved below --root.
+All files in one capture session must share a GROUP, and a group may occur in
+only one split. Identical bytes are rejected when they cross a split boundary.
+Files from sibling directories are interleaved, so a limited training prefix
+does not consist entirely of the lexicographically first class.
+
+Example:
+  python tools/make_dataset_manifest.py \
+    --root data --output experiments/dataset.json \
+    --entry train photo imagenette-train imagenette/train \
+    --entry train capture room-a captures/room-a \
+    --entry test capture room-b captures/room-b
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+from pathlib import Path
+
+
+EXTENSIONS = {".jpeg", ".jpg", ".png", ".rgb"}
+
+
+def digest(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as f:
+        for chunk in iter(lambda: f.read(1024 * 1024), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def interleaved_images(directory: Path) -> list[Path]:
+    """Return a deterministic round-robin over leaf directories."""
+    groups: dict[Path, list[Path]] = {}
+    for path in directory.rglob("*"):
+        if path.is_file() and path.suffix.lower() in EXTENSIONS:
+            groups.setdefault(path.parent, []).append(path)
+    ordered_groups = [sorted(groups[parent]) for parent in sorted(groups)]
+    result: list[Path] = []
+    for index in range(max((len(group) for group in ordered_groups), default=0)):
+        result.extend(group[index] for group in ordered_groups if index < len(group))
+    return result
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--root", required=True, type=Path)
+    ap.add_argument("--output", required=True, type=Path)
+    ap.add_argument("--name", default="dinovision")
+    ap.add_argument(
+        "--entry",
+        nargs=4,
+        action="append",
+        metavar=("SPLIT", "SOURCE", "GROUP", "PATH"),
+        required=True,
+    )
+    ap.add_argument(
+        "--provenance",
+        nargs=3,
+        action="append",
+        default=[],
+        metavar=("NAME", "URL", "SHA256"),
+        help="record an immutable source archive without downloading it",
+    )
+    args = ap.parse_args()
+
+    root = args.root.resolve()
+    output = args.output.resolve()
+    for name, _, sha256 in args.provenance:
+        if len(sha256) != 64 or any(c not in "0123456789abcdef" for c in sha256.lower()):
+            raise SystemExit(f"provenance {name} has an invalid SHA-256: {sha256}")
+    images: list[dict[str, object]] = []
+    group_splits: dict[tuple[str, str], str] = {}
+    hash_entries: dict[str, dict[str, object]] = {}
+
+    for split, source, group, relative in sorted(args.entry):
+        key = (source, group)
+        previous = group_splits.setdefault(key, split)
+        if previous != split:
+            raise SystemExit(
+                f"group {source}/{group} occurs in both {previous} and {split}"
+            )
+
+        directory = (root / relative).resolve()
+        try:
+            directory.relative_to(root)
+        except ValueError:
+            raise SystemExit(f"entry escapes --root: {directory}") from None
+        if not directory.is_dir():
+            raise SystemExit(f"not a directory: {directory}")
+        paths = interleaved_images(directory)
+        if not paths:
+            raise SystemExit(f"no supported images below {directory}")
+
+        for path in paths:
+            sha = digest(path)
+            old = hash_entries.get(sha)
+            if old is not None:
+                raise SystemExit(
+                    "identical file occurs more than once: "
+                    f"{old['path']} ({old['split']}) and {path} ({split})"
+                )
+            item = {
+                "path": path.relative_to(root).as_posix(),
+                "split": split,
+                "source": source,
+                "group": group,
+                "sha256": sha,
+                "bytes": path.stat().st_size,
+            }
+            images.append(item)
+            hash_entries.setdefault(sha, item)
+
+    try:
+        stored_root = Path(os.path.relpath(root, output.parent)).as_posix()
+    except ValueError:
+        stored_root = str(root)
+    manifest = {
+        "schema_version": 1,
+        "name": args.name,
+        "root": stored_root,
+        "provenance": [
+            {"name": name, "url": url, "sha256": sha256}
+            for name, url, sha256 in args.provenance
+        ],
+        "images": images,
+    }
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(manifest, indent=2) + "\n", encoding="utf-8")
+
+    counts: dict[str, int] = {}
+    for image in images:
+        counts[image["split"]] = counts.get(image["split"], 0) + 1
+    print(f"wrote {output}: {len(images)} images, splits {counts}")
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/pull_quest_artifacts.ps1

@@ -0,0 +1,89 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir
+)
+
+$ErrorActionPreference = "Stop"
+
+$adbCandidates = @()
+if ($env:LOCALAPPDATA) {
+    $adbCandidates += Join-Path $env:LOCALAPPDATA "Android\Sdk\platform-tools\adb.exe"
+}
+if ($env:ANDROID_HOME) {
+    $adbCandidates += Join-Path $env:ANDROID_HOME "platform-tools\adb.exe"
+}
+$adbCandidates = @($adbCandidates | Where-Object { Test-Path -LiteralPath $_ })
+
+if ($adbCandidates.Count -eq 0) {
+    throw "adb.exe was not found under LOCALAPPDATA or ANDROID_HOME"
+}
+$adb = $adbCandidates[0]
+
+$devices = @(& $adb devices | Select-Object -Skip 1 | Where-Object { $_ -match "\tdevice$" })
+if ($devices.Count -ne 1) {
+    throw "Expected exactly one authorized device; found $($devices.Count). Check 'adb devices'."
+}
+
+$destination = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $destination) {
+    if (@(Get-ChildItem -LiteralPath $destination -Force).Count -ne 0) {
+        throw "Refusing to merge a recovery pull into non-empty directory: $destination"
+    }
+} else {
+    New-Item -ItemType Directory -Path $destination | Out-Null
+}
+
+$runtimeDir = Join-Path $destination "runtime"
+$captureDir = Join-Path $destination "captures"
+New-Item -ItemType Directory -Path $runtimeDir | Out-Null
+New-Item -ItemType Directory -Path $captureDir | Out-Null
+
+$runtimeRemote = "/data/local/tmp/dinovision"
+$capturesRemote = "/sdcard/Android/data/rust.dinovision_xr/files/captures"
+
+# adb pull is read-only on the headset. Pull the whole runtime directory first
+# so unknown historical files are preserved rather than guessed at by name.
+$runtimePresent = $false
+& $adb shell "test -d $runtimeRemote"
+if ($LASTEXITCODE -eq 0) {
+    $runtimePresent = $true
+    & $adb pull "$runtimeRemote/." $runtimeDir
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to pull $runtimeRemote"
+    }
+}
+
+$capturesPresent = $false
+& $adb shell "test -d $capturesRemote"
+if ($LASTEXITCODE -eq 0) {
+    $capturesPresent = $true
+    & $adb pull "$capturesRemote/." $captureDir
+    if ($LASTEXITCODE -ne 0) {
+        throw "Failed to pull $capturesRemote"
+    }
+}
+
+$metadata = [ordered]@{
+    schema_version = 1
+    pulled_utc = [DateTime]::UtcNow.ToString("o")
+    device = (& $adb get-serialno).Trim()
+    product = (& $adb shell getprop ro.product.name).Trim()
+    model = (& $adb shell getprop ro.product.model).Trim()
+    build_fingerprint = (& $adb shell getprop ro.build.fingerprint).Trim()
+    runtime_directory_present = $runtimePresent
+    capture_directory_present = $capturesPresent
+    files = @(
+        Get-ChildItem -LiteralPath $destination -File -Recurse | ForEach-Object {
+            [ordered]@{
+                path = [System.IO.Path]::GetRelativePath($destination, $_.FullName).Replace("\", "/")
+                bytes = $_.Length
+                sha256 = (Get-FileHash -LiteralPath $_.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
+            }
+        }
+    )
+}
+
+$manifestPath = Join-Path $destination "recovery_manifest.json"
+$metadata | ConvertTo-Json -Depth 5 | Set-Content -LiteralPath $manifestPath -Encoding utf8
+Write-Host "Recovered $($metadata.files.Count) files to $destination"
+Write-Host "Manifest: $manifestPath"

environment/training-source/source-snapshot/tools/run_cross_device_correctness.ps1

@@ -0,0 +1,160 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir,
+    [Parameter(Mandatory = $true)]
+    [string]$RecoveryManifest,
+    [Parameter(Mandatory = $true)]
+    [string]$Binary,
+    [Parameter(Mandatory = $true)]
+    [string]$CorrectnessRoot,
+    [Parameter(Mandatory = $true)]
+    [string]$HostSampleDir,
+    [Parameter(Mandatory = $true)]
+    [string]$Model,
+    [Parameter(Mandatory = $true)]
+    [string]$Decoder,
+    [int]$Layers = 3,
+    [int]$Size = 224
+)
+
+$ErrorActionPreference = 'Stop'
+$repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$binaryPath = (Resolve-Path $Binary).Path
+$rootPath = (Resolve-Path $CorrectnessRoot).Path
+$hostSamples = (Resolve-Path $HostSampleDir).Path
+$modelPath = (Resolve-Path $Model).Path
+$decoderPath = (Resolve-Path $Decoder).Path
+$recoveryPath = (Resolve-Path $RecoveryManifest).Path
+$manifestPath = (Resolve-Path (Join-Path $rootPath 'manifests\correctness-224.json')).Path
+$framePath = (Resolve-Path (Join-Path $rootPath 'input\frame.rgb')).Path
+$destination = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $destination) {
+    if (@(Get-ChildItem -LiteralPath $destination -Force).Count -ne 0) {
+        throw "Refusing to merge correctness output into non-empty directory: $destination"
+    }
+} else {
+    New-Item -ItemType Directory -Path $destination | Out-Null
+}
+
+$adbCandidates = @()
+if ($env:LOCALAPPDATA) {
+    $adbCandidates += Join-Path $env:LOCALAPPDATA 'Android\Sdk\platform-tools\adb.exe'
+}
+if ($env:ANDROID_HOME) {
+    $adbCandidates += Join-Path $env:ANDROID_HOME 'platform-tools\adb.exe'
+}
+$adbCandidates = @($adbCandidates | Where-Object { Test-Path -LiteralPath $_ })
+if ($adbCandidates.Count -eq 0) { throw 'adb.exe was not found' }
+$adb = $adbCandidates[0]
+$devices = @(& $adb devices | Select-Object -Skip 1 | Where-Object { $_ -match "`tdevice$" })
+if ($devices.Count -ne 1) { throw "Expected one authorized device; found $($devices.Count)" }
+$serial = (& $adb get-serialno).Trim()
+$recovery = Get-Content -Raw -LiteralPath $recoveryPath | ConvertFrom-Json
+if ($recovery.device -ne $serial) {
+    throw "Recovery manifest is for $($recovery.device), connected device is $serial"
+}
+
+function Hash([string]$Path) {
+    (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
+}
+
+$binaryHash = Hash $binaryPath
+$modelHash = Hash $modelPath
+$decoderHash = Hash $decoderPath
+$stamp = [DateTime]::UtcNow.ToString('yyyyMMddTHHmmssZ')
+$remoteRoot = "/data/local/tmp/dinovision-correctness/$stamp-$($decoderHash.Substring(0, 12))"
+foreach ($subdirectory in @('', '/manifests', '/input', '/output')) {
+    & $adb shell "mkdir -p '$remoteRoot$subdirectory'"
+    if ($LASTEXITCODE -ne 0) { throw "could not create $remoteRoot$subdirectory" }
+}
+
+$remoteFiles = [ordered]@{
+    "$remoteRoot/evaluate_decoder" = $binaryPath
+    "$remoteRoot/model.safetensors" = $modelPath
+    "$remoteRoot/decoder.bin" = $decoderPath
+    "$remoteRoot/manifests/correctness-224.json" = $manifestPath
+    "$remoteRoot/input/frame.rgb" = $framePath
+}
+foreach ($entry in $remoteFiles.GetEnumerator()) {
+    & $adb push $entry.Value $entry.Key | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw "could not push $($entry.Value)" }
+    $remoteHash = ((& $adb shell "sha256sum '$($entry.Key)'").Trim().Split(' ')[0])
+    if ((Hash $entry.Value) -ne $remoteHash) { throw "hash mismatch for $($entry.Key)" }
+}
+& $adb shell "chmod 755 '$remoteRoot/evaluate_decoder'"
+if ($LASTEXITCODE -ne 0) { throw 'could not mark evaluator executable' }
+
+& $adb shell dumpsys thermalservice | Set-Content -Encoding utf8 (Join-Path $destination 'before-thermal.txt')
+& $adb shell dumpsys battery | Set-Content -Encoding utf8 (Join-Path $destination 'before-battery.txt')
+& $adb shell dumpsys power | Set-Content -Encoding utf8 (Join-Path $destination 'before-power.txt')
+$command = "cd '$remoteRoot' && RUST_LOG=warn ./evaluate_decoder " +
+    "--manifest manifests/correctness-224.json --model model.safetensors " +
+    "--decoder decoder.bin --split test --layers $Layers --size $Size " +
+    "--output output/quality.json --samples 1"
+$oldErrorPreference = $ErrorActionPreference
+try {
+    $ErrorActionPreference = 'Continue'
+    & $adb shell $command `
+        1> (Join-Path $destination 'device.stdout.log') `
+        2> (Join-Path $destination 'device.stderr.log')
+    $exitCode = $LASTEXITCODE
+} finally {
+    $ErrorActionPreference = $oldErrorPreference
+}
+if ($exitCode -ne 0) { throw "device evaluator exited with code $exitCode" }
+
+$deviceOutput = Join-Path $destination 'device-output'
+New-Item -ItemType Directory -Path $deviceOutput | Out-Null
+& $adb pull "$remoteRoot/output/." $deviceOutput | Out-Null
+if ($LASTEXITCODE -ne 0) { throw 'could not pull device correctness output' }
+& $adb shell dumpsys thermalservice | Set-Content -Encoding utf8 (Join-Path $destination 'after-thermal.txt')
+& $adb shell dumpsys battery | Set-Content -Encoding utf8 (Join-Path $destination 'after-battery.txt')
+& $adb shell dumpsys power | Set-Content -Encoding utf8 (Join-Path $destination 'after-power.txt')
+
+$deviceSamples = Join-Path $deviceOutput 'quality_samples'
+$comparisons = Join-Path $destination 'comparisons'
+New-Item -ItemType Directory -Path $comparisons | Out-Null
+function Compare(
+    [string]$Name,
+    [double]$MaxRelativeL2,
+    [double]$MinCosine,
+    [int]$RowSize = 0,
+    [double]$MinRowCosine = 0.0
+) {
+    $arguments = @(
+        (Join-Path $hostSamples "0000-$Name.f32"),
+        (Join-Path $deviceSamples "0000-$Name.f32"),
+        '--output', (Join-Path $comparisons "$Name.json"),
+        '--max-relative-l2', "$MaxRelativeL2",
+        '--min-cosine', "$MinCosine"
+    )
+    if ($RowSize -gt 0) {
+        $arguments += @('--row-size', "$RowSize", '--min-row-cosine', "$MinRowCosine")
+    }
+    & python (Join-Path $repo 'tools\compare_f32.py') @arguments
+    if ($LASTEXITCODE -ne 0) { throw "$Name comparison failed" }
+}
+
+Compare 'patches' 0.0 0.999999999
+Compare 'encoder' 0.01 0.999 384 0.999
+Compare 'features' 0.01 0.999
+Compare 'reconstruction' 0.02 0.999
+
+$metadata = [ordered]@{
+    schema_version = 1
+    completed_utc = [DateTime]::UtcNow.ToString('o')
+    device_serial = $serial
+    device_model = (& $adb shell getprop ro.product.model).Trim()
+    build_fingerprint = (& $adb shell getprop ro.build.fingerprint).Trim()
+    remote_root = $remoteRoot
+    encoder_layers = $Layers
+    image_size = $Size
+    binary_sha256 = $binaryHash
+    model_sha256 = $modelHash
+    decoder_sha256 = $decoderHash
+    manifest_sha256 = Hash $manifestPath
+    frame_sha256 = Hash $framePath
+    recovery_manifest_sha256 = Hash $recoveryPath
+}
+$metadata | ConvertTo-Json -Depth 5 | Set-Content -Encoding utf8 (Join-Path $destination 'correctness-metadata.json')
+Write-Output "cross-device correctness passed; device files remain at $remoteRoot"

environment/training-source/source-snapshot/tools/run_decoder_matrix.ps1

@@ -0,0 +1,142 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$Manifest,
+    [Parameter(Mandatory = $true)]
+    [string]$Model,
+    [Parameter(Mandatory = $true)]
+    [string]$OutputRoot,
+    [string[]]$Seeds = @('0', '1', '2'),
+    [int]$Steps = 12000,
+    [int]$Images = 2500,
+    [int]$Layers = 3,
+    [int]$Size = 224,
+    [string]$EvaluationSplit = "validation"
+)
+
+$ErrorActionPreference = "Stop"
+$repo = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+$manifestPath = (Resolve-Path $Manifest).Path
+$modelPath = (Resolve-Path $Model).Path
+$manifestHash = (Get-FileHash -LiteralPath $manifestPath -Algorithm SHA256).Hash.ToLowerInvariant()
+$modelHash = (Get-FileHash -LiteralPath $modelPath -Algorithm SHA256).Hash.ToLowerInvariant()
+$outputPath = [System.IO.Path]::GetFullPath($OutputRoot)
+New-Item -ItemType Directory -Force -Path $outputPath | Out-Null
+$cargo = (Get-Command cargo).Source
+$seedValues = @(
+    $Seeds | ForEach-Object { $_ -split ',' } | ForEach-Object {
+        $value = 0L
+        if (-not [long]::TryParse($_.Trim(), [ref]$value) -or $value -lt 0) {
+            throw "invalid seed: $_"
+        }
+        $value
+    }
+)
+if ($seedValues.Count -eq 0 -or @($seedValues | Select-Object -Unique).Count -ne $seedValues.Count) {
+    throw 'provide at least one seed, without duplicates'
+}
+
+function Run-Cargo(
+    [string[]]$Arguments,
+    [string]$Stdout,
+    [string]$Stderr,
+    [string]$LogLevel
+) {
+    $env:RUST_LOG = $LogLevel
+    Push-Location $repo
+    $oldErrorPreference = $ErrorActionPreference
+    try {
+        # Windows PowerShell may wrap native stderr as ErrorRecord objects;
+        # Continue preserves the native exit code while the two streams are
+        # retained independently.
+        $ErrorActionPreference = "Continue"
+        & $cargo @Arguments 1> $Stdout 2> $Stderr
+        $exitCode = $LASTEXITCODE
+    } finally {
+        $ErrorActionPreference = $oldErrorPreference
+        Pop-Location
+    }
+    if ($exitCode -ne 0) {
+        throw "cargo exited with code $exitCode; see $Stdout and $Stderr"
+    }
+}
+
+foreach ($seed in $seedValues) {
+    $runDir = Join-Path $outputPath "${Layers}l${Size}-seed${seed}"
+    New-Item -ItemType Directory -Force -Path $runDir | Out-Null
+    $decoder = Join-Path $runDir "decoder.bin"
+    $training = Join-Path $runDir "training.json"
+    $quality = Join-Path $runDir "quality-imagenette-$EvaluationSplit.json"
+
+    if (-not ((Test-Path -LiteralPath $training) -and (Test-Path -LiteralPath $decoder))) {
+        Write-Output "training seed $seed at $(Get-Date -Format o)"
+        Run-Cargo `
+            -Arguments @(
+                "run", "--release", "--example", "train_decoder", "--",
+                $manifestPath, $modelPath, "$Steps", "$Images", "$Layers", "$Size", "$seed", $runDir
+            ) `
+            -Stdout (Join-Path $runDir "training.stdout.log") `
+            -Stderr (Join-Path $runDir "training.stderr.log") `
+            -LogLevel "info"
+    } else {
+        Write-Output "seed $seed training outputs already exist; preserving them"
+    }
+
+    $record = Get-Content -Raw -LiteralPath $training | ConvertFrom-Json
+    if (
+        $record.seed -ne $seed -or
+        $record.steps -ne $Steps -or
+        $record.requested_images -ne $Images -or
+        $record.encoder_layers -ne $Layers -or
+        $record.image_size -ne $Size -or
+        $record.dataset_manifest_sha256 -ne $manifestHash -or
+        $record.model_sha256 -ne $modelHash
+    ) {
+        throw "existing training record does not match requested cell: $training"
+    }
+
+    if (-not (Test-Path -LiteralPath $quality)) {
+        Write-Output "evaluating seed $seed at $(Get-Date -Format o)"
+        Run-Cargo `
+            -Arguments @(
+                "run", "--release", "--example", "evaluate_decoder", "--",
+                "--manifest", $manifestPath,
+                "--model", $modelPath,
+                "--decoder", $decoder,
+                "--split", $EvaluationSplit,
+                "--layers", "$Layers",
+                "--size", "$Size",
+                "--output", $quality,
+                "--samples", "12"
+            ) `
+            -Stdout (Join-Path $runDir "evaluation.stdout.log") `
+            -Stderr (Join-Path $runDir "evaluation.stderr.log") `
+            -LogLevel "warn"
+    } else {
+        Write-Output "seed $seed quality output already exists; preserving it"
+    }
+
+    $qualityRecord = Get-Content -Raw -LiteralPath $quality | ConvertFrom-Json
+    if (
+        $qualityRecord.split -ne $EvaluationSplit -or
+        $qualityRecord.encoder_layers -ne $Layers -or
+        $qualityRecord.image_size -ne $Size -or
+        $qualityRecord.manifest_sha256 -ne $manifestHash -or
+        $qualityRecord.model_sha256 -ne $modelHash -or
+        $qualityRecord.decoder_sha256 -ne $record.decoder_sha256
+    ) {
+        throw "quality record does not match its training cell: $quality"
+    }
+
+    $safeTensors = Join-Path $runDir "decoder.safetensors"
+    if (-not (Test-Path -LiteralPath $safeTensors)) {
+        & python (Join-Path $repo "tools\convert_decoder.py") `
+            --training $training `
+            --input $decoder `
+            --output $safeTensors
+        if ($LASTEXITCODE -ne 0) {
+            throw "decoder SafeTensors conversion failed for seed $seed"
+        }
+    }
+}
+
+Write-Output "decoder matrix complete at $(Get-Date -Format o)"

environment/training-source/source-snapshot/tools/run_quest_bench.ps1

@@ -0,0 +1,149 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir,
+    [Parameter(Mandatory = $true)]
+    [string]$RecoveryManifest,
+    [string]$Binary = "target\aarch64-linux-android\release\examples\bench",
+    [ValidateSet("live-worn", "awake-unworn")]
+    [string]$Condition = "live-worn",
+    [int]$Processes = 3,
+    [int]$Iterations = 20,
+    [ValidateSet("full", "shapes")]
+    [string]$Suite = "full"
+)
+
+$ErrorActionPreference = "Stop"
+if ($Processes -lt 3) { throw "paper protocol requires at least three processes" }
+if ($Iterations -lt 20) { throw "paper protocol requires at least 20 retained samples" }
+$repo = (Resolve-Path (Join-Path $PSScriptRoot "..")).Path
+$binaryPath = (Resolve-Path (Join-Path $repo $Binary)).Path
+$recoveryPath = (Resolve-Path $RecoveryManifest).Path
+$destination = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $destination) {
+    if (@(Get-ChildItem -LiteralPath $destination -Force).Count -ne 0) {
+        throw "Refusing to merge benchmark output into non-empty directory: $destination"
+    }
+} else {
+    New-Item -ItemType Directory -Path $destination | Out-Null
+}
+
+$adbCandidates = @()
+if ($env:LOCALAPPDATA) {
+    $adbCandidates += Join-Path $env:LOCALAPPDATA "Android\Sdk\platform-tools\adb.exe"
+}
+if ($env:ANDROID_HOME) {
+    $adbCandidates += Join-Path $env:ANDROID_HOME "platform-tools\adb.exe"
+}
+$adbCandidates = @($adbCandidates | Where-Object { Test-Path -LiteralPath $_ })
+if ($adbCandidates.Count -eq 0) {
+    throw "adb.exe was not found"
+}
+$adb = $adbCandidates[0]
+$devices = @(& $adb devices | Select-Object -Skip 1 | Where-Object { $_ -match "\tdevice$" })
+if ($devices.Count -ne 1) {
+    throw "Expected exactly one authorized device; found $($devices.Count)"
+}
+$serial = (& $adb get-serialno).Trim()
+$recovery = Get-Content -Raw -LiteralPath $recoveryPath | ConvertFrom-Json
+if ($recovery.device -ne $serial) {
+    throw "Recovery manifest is for $($recovery.device), connected device is $serial"
+}
+
+$binaryHash = (Get-FileHash -LiteralPath $binaryPath -Algorithm SHA256).Hash.ToLowerInvariant()
+$remoteDir = "/data/local/tmp/dinovision"
+$remoteBinary = "$remoteDir/bench-paper-$($binaryHash.Substring(0, 12))"
+& $adb shell "mkdir -p $remoteDir"
+if ($LASTEXITCODE -ne 0) { throw "could not create $remoteDir" }
+& $adb push $binaryPath $remoteBinary
+if ($LASTEXITCODE -ne 0) { throw "could not push benchmark binary" }
+& $adb shell "chmod 755 $remoteBinary"
+if ($LASTEXITCODE -ne 0) { throw "could not mark benchmark executable" }
+
+$remoteHash = (& $adb shell "sha256sum $remoteBinary").Trim().Split(" ")[0]
+if ($binaryHash -ne $remoteHash) {
+    throw "pushed binary hash mismatch: host $binaryHash, device $remoteHash"
+}
+
+$suiteEnvironment = if ($Suite -eq "shapes") { "DINOVISION_BENCH=shapes " } else { "" }
+$remoteName = [System.IO.Path]::GetFileName($remoteBinary)
+$command = "cd $remoteDir && RUST_LOG=info DINOVISION_WARMUPS=5 ${suiteEnvironment}./$remoteName $Iterations"
+
+function Capture-State([string]$Prefix) {
+    & $adb shell dumpsys thermalservice | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-thermal.txt")
+    & $adb shell dumpsys battery | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-battery.txt")
+    & $adb shell dumpsys power | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-power.txt")
+    & $adb shell dumpsys activity activities | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-activity.txt")
+    & $adb shell dumpsys SurfaceFlinger | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-surfaceflinger.txt")
+}
+
+function Assert-Condition([string]$When) {
+    $power = (& $adb shell dumpsys power) -join "`n"
+    if ($power -notmatch 'mWakefulness=Awake') {
+        throw "Headset is not awake $When; requested condition is $Condition"
+    }
+    if ($Condition -eq 'live-worn') {
+        $activity = (& $adb shell dumpsys activity activities) -join "`n"
+        if ($activity -match 'SensorLockActivity') {
+            throw "Headset is not being worn $When (SensorLockActivity is resumed)"
+        }
+    }
+}
+
+function Run-Process([string]$Name, [string]$RunCommand) {
+    Capture-State "$Name-before"
+    $process = Start-Process `
+        -FilePath $adb `
+        -ArgumentList @("shell", $RunCommand) `
+        -NoNewWindow `
+        -Wait `
+        -PassThru `
+        -RedirectStandardOutput (Join-Path $destination "$Name.stdout.log") `
+        -RedirectStandardError (Join-Path $destination "$Name.stderr.log")
+    Capture-State "$Name-after"
+    if ($process.ExitCode -ne 0) {
+        throw "device benchmark $Name exited with code $($process.ExitCode)"
+    }
+}
+
+# This process is retained as a stabilization diagnostic but excluded from
+# aggregate results. It prevents the first retained process from receiving
+# the entire device clock-ramp penalty.
+Assert-Condition "before stabilization"
+$warmupCommand = "cd $remoteDir && RUST_LOG=info DINOVISION_WARMUPS=5 ${suiteEnvironment}./$remoteName 5"
+Run-Process "stabilization" $warmupCommand
+for ($index = 0; $index -lt $Processes; $index++) {
+    Assert-Condition "before process $index"
+    Run-Process ("process-{0:d2}" -f $index) $command
+}
+Assert-Condition "after retained processes"
+
+$recordArguments = @(
+    (Join-Path $repo 'tools\extract_json_records.py'),
+    '--marker', 'DINOVISION_BENCH_JSON',
+    '--output', (Join-Path $destination 'benchmark-records.json')
+)
+for ($index = 0; $index -lt $Processes; $index++) {
+    $recordArguments += @('--input', (Join-Path $destination ("process-{0:d2}.stdout.log" -f $index)))
+}
+& python @recordArguments
+if ($LASTEXITCODE -ne 0) { throw 'could not extract benchmark JSON records' }
+
+$metadata = [ordered]@{
+    schema_version = 1
+    completed_utc = [DateTime]::UtcNow.ToString("o")
+    condition = $Condition
+    suite = $Suite
+    processes = $Processes
+    warmups_per_process = 5
+    retained_samples_per_workload = $Iterations
+    command = $command
+    binary = $binaryPath
+    binary_sha256 = $binaryHash
+    device_serial = $serial
+    device_model = (& $adb shell getprop ro.product.model).Trim()
+    build_fingerprint = (& $adb shell getprop ro.build.fingerprint).Trim()
+    recovery_manifest = $recoveryPath
+    recovery_manifest_sha256 = (Get-FileHash -LiteralPath $recoveryPath -Algorithm SHA256).Hash.ToLowerInvariant()
+}
+$metadata | ConvertTo-Json -Depth 4 | Set-Content -Encoding utf8 (Join-Path $destination "benchmark-metadata.json")
+Write-Output "wrote Quest benchmark artifacts to $destination"

environment/training-source/source-snapshot/tools/run_xr_sweep.ps1

@@ -0,0 +1,239 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir,
+    [Parameter(Mandatory = $true)]
+    [string]$RecoveryManifest,
+    [Parameter(Mandatory = $true)]
+    [string]$Apk,
+    [Parameter(Mandatory = $true)]
+    [string]$Model,
+    [Parameter(Mandatory = $true)]
+    [string]$Decoder,
+    # Fixed before device data: a deterministic permutation avoids making
+    # chunk count monotonic with startup/thermal drift. Summaries sort cells.
+    [int[]]$Chunks = @(4, 16, 1, 12, 2, 8),
+    [int]$InferenceIntervalMs = 0,
+    [int]$DurationSeconds = 90,
+    [string]$Package = 'rust.dinovision_xr',
+    [string]$Activity = 'android.app.NativeActivity'
+)
+
+$ErrorActionPreference = 'Stop'
+if ($DurationSeconds -lt 60) {
+    throw 'paper protocol requires at least 60 seconds per chunk setting'
+}
+if ($Chunks.Count -lt 2 -or @($Chunks | Where-Object { $_ -lt 1 }).Count -gt 0) {
+    throw 'provide at least two positive chunk settings'
+}
+if (@($Chunks | Select-Object -Unique).Count -ne $Chunks.Count) {
+    throw 'chunk settings must be unique because each setting owns one output cell'
+}
+
+$repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$apkPath = (Resolve-Path $Apk).Path
+$modelPath = (Resolve-Path $Model).Path
+$decoderPath = (Resolve-Path $Decoder).Path
+$recoveryPath = (Resolve-Path $RecoveryManifest).Path
+$destination = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $destination) {
+    if (@(Get-ChildItem -LiteralPath $destination -Force).Count -ne 0) {
+        throw "Refusing to merge XR output into non-empty directory: $destination"
+    }
+} else {
+    New-Item -ItemType Directory -Path $destination | Out-Null
+}
+
+$adbCandidates = @()
+if ($env:LOCALAPPDATA) {
+    $adbCandidates += Join-Path $env:LOCALAPPDATA 'Android\Sdk\platform-tools\adb.exe'
+}
+if ($env:ANDROID_HOME) {
+    $adbCandidates += Join-Path $env:ANDROID_HOME 'platform-tools\adb.exe'
+}
+$adbCandidates = @($adbCandidates | Where-Object { Test-Path -LiteralPath $_ })
+if ($adbCandidates.Count -eq 0) { throw 'adb.exe was not found' }
+$adb = $adbCandidates[0]
+$devices = @(& $adb devices | Select-Object -Skip 1 | Where-Object { $_ -match "`tdevice$" })
+if ($devices.Count -ne 1) { throw "Expected one authorized device; found $($devices.Count)" }
+$serial = (& $adb get-serialno).Trim()
+$recovery = Get-Content -Raw -LiteralPath $recoveryPath | ConvertFrom-Json
+if ($recovery.device -ne $serial) {
+    throw "Recovery manifest is for $($recovery.device), connected device is $serial"
+}
+
+$remoteDir = '/data/local/tmp/dinovision'
+$modelRemote = "$remoteDir/model.safetensors"
+$decoderRemote = "$remoteDir/decoder.bin"
+$toggleNames = @(
+    'raw_camera', 'mono', 'camera_half_fov_deg',
+    'inference_interval_ms', 'submission_chunks', 'capture'
+)
+
+function Shell-Quote([string]$Value) {
+    if ($Value.Contains("'")) { throw 'toggle values may not contain a single quote' }
+    return "'$Value'"
+}
+
+function Assert-LiveWorn([string]$When) {
+    $power = (& $adb shell dumpsys power) -join "`n"
+    if ($power -notmatch 'mWakefulness=Awake') {
+        throw "Headset is not awake $When"
+    }
+    $activityState = (& $adb shell dumpsys activity activities) -join "`n"
+    if ($activityState -match 'SensorLockActivity') {
+        throw "Headset is not being worn $When (SensorLockActivity is resumed)"
+    }
+}
+
+function Capture-State([string]$Prefix) {
+    & $adb shell dumpsys thermalservice | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-thermal.txt")
+    & $adb shell dumpsys battery | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-battery.txt")
+    & $adb shell dumpsys power | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-power.txt")
+    & $adb shell dumpsys activity activities | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-activity.txt")
+    & $adb shell dumpsys SurfaceFlinger | Set-Content -Encoding utf8 (Join-Path $destination "$Prefix-surfaceflinger.txt")
+}
+
+function Read-Toggle([string]$Name) {
+    $path = "$remoteDir/$Name"
+    $present = ((& $adb shell "if [ -e '$path' ]; then echo yes; else echo no; fi").Trim() -eq 'yes')
+    [ordered]@{
+        present = $present
+        value = if ($present) { ((& $adb shell "cat '$path' 2>/dev/null") -join "`n").TrimEnd() } else { $null }
+    }
+}
+
+function Write-Toggle([string]$Name, [string]$Value) {
+    $path = "$remoteDir/$Name"
+    $quoted = Shell-Quote $Value
+    & $adb shell "printf '%s' $quoted > '$path'"
+    if ($LASTEXITCODE -ne 0) { throw "could not write toggle $Name" }
+}
+
+function Remove-Toggle([string]$Name) {
+    & $adb shell "rm -f -- '$remoteDir/$Name'"
+    if ($LASTEXITCODE -ne 0) { throw "could not remove toggle $Name" }
+}
+
+function Remote-File-Present([string]$Path) {
+    return ((& $adb shell "if [ -f '$Path' ]; then echo yes; else echo no; fi").Trim() -eq 'yes')
+}
+
+& $adb shell "mkdir -p '$remoteDir'"
+if ($LASTEXITCODE -ne 0) { throw "could not create $remoteDir" }
+$originalToggles = [ordered]@{}
+foreach ($name in $toggleNames) { $originalToggles[$name] = Read-Toggle $name }
+$originalToggles | ConvertTo-Json -Depth 5 | Set-Content -Encoding utf8 (Join-Path $destination 'preexisting-toggles.json')
+
+$backupDir = Join-Path $destination 'preexisting-runtime'
+New-Item -ItemType Directory -Path $backupDir | Out-Null
+$hadModel = Remote-File-Present $modelRemote
+$hadDecoder = Remote-File-Present $decoderRemote
+if ($hadModel) { & $adb pull $modelRemote (Join-Path $backupDir 'model.safetensors') | Out-Null }
+if ($hadDecoder) { & $adb pull $decoderRemote (Join-Path $backupDir 'decoder.bin') | Out-Null }
+
+$completed = $false
+try {
+    Assert-LiveWorn 'before installation'
+    & $adb install -r $apkPath | Set-Content -Encoding utf8 (Join-Path $destination 'install.log')
+    if ($LASTEXITCODE -ne 0) { throw 'APK installation failed' }
+    & $adb shell pm grant $Package horizonos.permission.HEADSET_CAMERA
+    if ($LASTEXITCODE -ne 0) { throw 'HEADSET_CAMERA permission grant failed' }
+
+    & $adb push $modelPath $modelRemote | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw 'encoder push failed' }
+    & $adb push $decoderPath $decoderRemote | Out-Null
+    if ($LASTEXITCODE -ne 0) { throw 'decoder push failed' }
+    $modelHash = (Get-FileHash -LiteralPath $modelPath -Algorithm SHA256).Hash.ToLowerInvariant()
+    $decoderHash = (Get-FileHash -LiteralPath $decoderPath -Algorithm SHA256).Hash.ToLowerInvariant()
+    $remoteModelHash = ((& $adb shell "sha256sum '$modelRemote'").Trim().Split(' ')[0])
+    $remoteDecoderHash = ((& $adb shell "sha256sum '$decoderRemote'").Trim().Split(' ')[0])
+    if ($modelHash -ne $remoteModelHash -or $decoderHash -ne $remoteDecoderHash) {
+        throw 'pushed weight hash mismatch'
+    }
+
+    # Stereo corrected-model runs only. Capture is disabled so this protocol
+    # never writes private camera frames.
+    foreach ($name in @('raw_camera', 'mono', 'capture')) { Remove-Toggle $name }
+    Write-Toggle 'inference_interval_ms' "$InferenceIntervalMs"
+
+    foreach ($chunk in $Chunks) {
+        $name = "chunks-{0:d2}" -f $chunk
+        Write-Toggle 'submission_chunks' "$chunk"
+        Assert-LiveWorn "before $name"
+        Capture-State "$name-before"
+        & $adb shell am force-stop $Package
+        # logcat streams the existing ring buffer unless it is cleared. A stale
+        # DinoVision window from an earlier setting would otherwise be accepted
+        # as part of this cell and silently bias the aggregate.
+        & $adb logcat -c
+        if ($LASTEXITCODE -ne 0) { throw "could not clear logcat before $name" }
+        $stdout = Join-Path $destination "$name.logcat.log"
+        $stderr = Join-Path $destination "$name.logcat.stderr.log"
+        $logcat = Start-Process `
+            -FilePath $adb `
+            -ArgumentList @('logcat', '-v', 'epoch', 'dinovision:I', 'RustStdoutStderr:I', '*:S') `
+            -WindowStyle Hidden `
+            -PassThru `
+            -RedirectStandardOutput $stdout `
+            -RedirectStandardError $stderr
+        try {
+            Start-Sleep -Seconds 1
+            & $adb shell am start -W -a android.intent.action.MAIN -c com.oculus.intent.category.VR -n "$Package/$Activity" |
+                Set-Content -Encoding utf8 (Join-Path $destination "$name-launch.log")
+            if ($LASTEXITCODE -ne 0) { throw "could not launch $name" }
+            Start-Sleep -Seconds $DurationSeconds
+            & $adb shell am force-stop $Package
+            Start-Sleep -Seconds 2
+        } finally {
+            Stop-Process -Id $logcat.Id -Force -ErrorAction SilentlyContinue
+            $logcat.WaitForExit()
+        }
+        Capture-State "$name-after"
+        Assert-LiveWorn "after $name"
+        & python (Join-Path $repo 'tools\extract_json_records.py') `
+            --input $stdout `
+            --marker DINOVISION_APP_JSON `
+            --output (Join-Path $destination "$name-records.json")
+        if ($LASTEXITCODE -ne 0) { throw "no valid application records for $name" }
+    }
+
+    $metadata = [ordered]@{
+        schema_version = 1
+        completed_utc = [DateTime]::UtcNow.ToString('o')
+        condition = 'live-worn'
+        device_serial = $serial
+        device_model = (& $adb shell getprop ro.product.model).Trim()
+        build_fingerprint = (& $adb shell getprop ro.build.fingerprint).Trim()
+        package = $Package
+        activity = $Activity
+        chunks = $Chunks
+        order_policy = 'predeclared deterministic permutation before corrected device data'
+        inference_interval_ms = $InferenceIntervalMs
+        duration_seconds_per_setting = $DurationSeconds
+        apk_sha256 = (Get-FileHash -LiteralPath $apkPath -Algorithm SHA256).Hash.ToLowerInvariant()
+        model_sha256 = $modelHash
+        decoder_sha256 = $decoderHash
+        recovery_manifest = $recoveryPath
+        recovery_manifest_sha256 = (Get-FileHash -LiteralPath $recoveryPath -Algorithm SHA256).Hash.ToLowerInvariant()
+    }
+    $metadata | ConvertTo-Json -Depth 5 | Set-Content -Encoding utf8 (Join-Path $destination 'sweep-metadata.json')
+    $completed = $true
+} finally {
+    & $adb shell am force-stop $Package 2>$null
+    foreach ($name in $toggleNames) {
+        $state = $originalToggles[$name]
+        if ($state.present) { Write-Toggle $name ([string]$state.value) } else { Remove-Toggle $name }
+    }
+    if ($hadModel) {
+        & $adb push (Join-Path $backupDir 'model.safetensors') $modelRemote | Out-Null
+    } else {
+        & $adb shell "rm -f -- '$modelRemote'"
+    }
+    if ($hadDecoder) {
+        & $adb push (Join-Path $backupDir 'decoder.bin') $decoderRemote | Out-Null
+    } else {
+        & $adb shell "rm -f -- '$decoderRemote'"
+    }
+}
+
+if ($completed) { Write-Output "wrote live XR sweep to $destination" }

environment/training-source/source-snapshot/tools/stage_huggingface_artifact.ps1

@@ -0,0 +1,230 @@
+param(
+    [Parameter(Mandatory = $true)]
+    [string]$OutputDir,
+    [Parameter(Mandatory = $true)]
+    [string]$RunsRoot,
+    [Parameter(Mandatory = $true)]
+    [string]$DatasetManifest,
+    [Parameter(Mandatory = $true)]
+    [string]$CorrectnessRoot,
+    [Parameter(Mandatory = $true)]
+    [string[]]$ReferenceRoots,
+    [Parameter(Mandatory = $true)]
+    [string]$EnvironmentDir,
+    [string]$CrossDeviceDir,
+    [string]$BenchmarkDir,
+    [string]$XrDir,
+    [int[]]$Seeds = @(0, 1, 2),
+    [int]$SelectedSeed = 0,
+    [int]$Layers = 3,
+    [int]$Size = 224,
+    [string]$ExpectedDatasetManifestSha256 = '2071f89b2a7b077d7729641fc858e1225d057d11a797d16198c0d195d989bb89',
+    [string]$ExpectedCorrectnessManifestSha256 = '94b10d1640c3e09b3eecec8abea64ec0cdd128032ad60a0e31d246ac932b178f',
+    [string]$ExpectedCorrectnessFrameSha256 = 'b89c2000b8877bce4649610e490579eef1ada5b29867f7a773d88450549ad1a8'
+)
+
+$ErrorActionPreference = 'Stop'
+$repo = (Resolve-Path (Join-Path $PSScriptRoot '..')).Path
+$runs = (Resolve-Path $RunsRoot).Path
+$manifest = (Resolve-Path $DatasetManifest).Path
+$correctness = (Resolve-Path $CorrectnessRoot).Path
+$environment = (Resolve-Path $EnvironmentDir).Path
+$references = @($ReferenceRoots | ForEach-Object { (Resolve-Path $_).Path })
+
+function File-Hash([string]$Path) {
+    (Get-FileHash -LiteralPath $Path -Algorithm SHA256).Hash.ToLowerInvariant()
+}
+
+if ((File-Hash $manifest) -ne $ExpectedDatasetManifestSha256) {
+    throw 'dataset manifest is not the frozen Imagenette manifest'
+}
+$correctnessManifest = Join-Path $correctness 'manifests\correctness-224.json'
+$correctnessFrame = Join-Path $correctness 'input\frame.rgb'
+if ((File-Hash $correctnessManifest) -ne $ExpectedCorrectnessManifestSha256) {
+    throw 'correctness manifest is not the frozen public manifest'
+}
+if ((File-Hash $correctnessFrame) -ne $ExpectedCorrectnessFrameSha256) {
+    throw 'correctness frame is not the frozen synthetic public frame'
+}
+
+if ($Seeds.Count -lt 3 -or $Seeds -notcontains $SelectedSeed) {
+    throw 'publish at least three seeds and include the preselected seed'
+}
+$destination = [System.IO.Path]::GetFullPath($OutputDir)
+if (Test-Path -LiteralPath $destination) {
+    if (@(Get-ChildItem -LiteralPath $destination -Force).Count -ne 0) {
+        throw "Refusing to merge a publication into non-empty directory: $destination"
+    }
+} else {
+    New-Item -ItemType Directory -Path $destination | Out-Null
+}
+
+function Copy-PublicFile([string]$Source, [string]$RelativeDestination) {
+    if (-not (Test-Path -LiteralPath $Source -PathType Leaf)) {
+        throw "required publication input is missing: $Source"
+    }
+    $target = Join-Path $destination $RelativeDestination
+    $parent = Split-Path -Parent $target
+    New-Item -ItemType Directory -Force -Path $parent | Out-Null
+    Copy-Item -LiteralPath $Source -Destination $target
+}
+
+function Copy-DirectoryFiles(
+    [string]$Source,
+    [string]$RelativeDestination,
+    [string[]]$Patterns
+) {
+    foreach ($pattern in $Patterns) {
+        Get-ChildItem -LiteralPath $Source -File -Filter $pattern | ForEach-Object {
+            Copy-PublicFile $_.FullName (Join-Path $RelativeDestination $_.Name)
+        }
+    }
+}
+
+function Copy-PublicTree([string]$Source, [string]$RelativeDestination) {
+    if (-not (Test-Path -LiteralPath $Source -PathType Container)) {
+        throw "required publication directory is missing: $Source"
+    }
+    Get-ChildItem -LiteralPath $Source -Recurse -File | ForEach-Object {
+        $relative = [System.IO.Path]::GetRelativePath($Source, $_.FullName)
+        Copy-PublicFile $_.FullName (Join-Path $RelativeDestination $relative)
+    }
+}
+
+function Write-SanitizedJson(
+    [string]$Source,
+    [string]$RelativeDestination,
+    [string[]]$RemoveProperties
+) {
+    if (-not (Test-Path -LiteralPath $Source -PathType Leaf)) {
+        throw "required publication input is missing: $Source"
+    }
+    $record = Get-Content -Raw -LiteralPath $Source | ConvertFrom-Json
+    foreach ($property in $RemoveProperties) {
+        $record.PSObject.Properties.Remove($property)
+    }
+    $target = Join-Path $destination $RelativeDestination
+    New-Item -ItemType Directory -Force -Path (Split-Path -Parent $target) | Out-Null
+    $record | ConvertTo-Json -Depth 20 | Set-Content -LiteralPath $target -Encoding utf8
+}
+
+# Repository-owned documentation is the only recursively copied directory.
+# Every experimental artifact below is selected by exact filename or suffix;
+# in particular, no dataset image or private headset capture directory can be
+# reached through this script.
+Get-ChildItem -LiteralPath (Join-Path $repo 'huggingface') -File | ForEach-Object {
+    Copy-PublicFile $_.FullName $_.Name
+}
+
+$selectedDir = Join-Path $runs ("${Layers}l${Size}-seed${SelectedSeed}")
+foreach ($name in @('decoder.bin', 'decoder.safetensors', 'training.json')) {
+    Copy-PublicFile (Join-Path $selectedDir $name) $name
+}
+
+foreach ($seed in $Seeds) {
+    $runName = "${Layers}l${Size}-seed${seed}"
+    $runDir = Join-Path $runs $runName
+    foreach ($name in @(
+        'decoder.bin', 'decoder.safetensors', 'training.json',
+        'run-notes.json',
+        'training.stdout.log', 'training.stderr.log',
+        'evaluation.stdout.log', 'evaluation.stderr.log'
+    )) {
+        Copy-PublicFile (Join-Path $runDir $name) (Join-Path "replicates\$runName" $name)
+    }
+    Copy-PublicFile `
+        (Join-Path $runDir 'quality-imagenette-validation.json') `
+        (Join-Path 'quality' "$runName.json")
+}
+Copy-PublicFile (Join-Path $runs 'quality-summary.json') 'quality\summary.json'
+Copy-PublicFile (Join-Path $runs 'quality-summary.md') 'quality\summary.md'
+Copy-PublicFile (Join-Path $runs 'dataset-summary.json') 'manifests\dataset-summary.json'
+Copy-PublicFile (Join-Path $runs 'dataset-summary.md') 'manifests\dataset-summary.md'
+
+Copy-PublicFile $manifest 'manifests\imagenette2-320.json'
+Copy-PublicFile `
+    $correctnessManifest `
+    'manifests\correctness-224.json'
+Copy-PublicFile $correctnessFrame 'correctness\frame.rgb'
+
+foreach ($reference in $references) {
+    $name = Split-Path -Leaf $reference
+    # Reference tensors use .bin; the gated exported model has a distinct
+    # .safetensors suffix and is deliberately not selected.
+    Copy-DirectoryFiles $reference (Join-Path 'correctness\reference' $name) @('*.json', '*.bin')
+}
+
+Copy-DirectoryFiles $environment 'environment\training-source' @(
+    'metadata.json', 'Cargo.lock', 'cargo-tree.txt', 'dinovision-working-tree.patch'
+)
+Copy-PublicTree `
+    (Join-Path $environment 'dinovision-source-snapshot') `
+    'environment\training-source\source-snapshot'
+
+if ($CrossDeviceDir) {
+    $cross = (Resolve-Path $CrossDeviceDir).Path
+    Write-SanitizedJson `
+        (Join-Path $cross 'correctness-metadata.json') `
+        'correctness\host-quest\metadata.json' `
+        @('device_serial', 'remote_root', 'recovery_manifest_sha256')
+    Copy-DirectoryFiles (Join-Path $cross 'comparisons') 'correctness\host-quest\comparisons' @('*.json')
+    Copy-DirectoryFiles (Join-Path $cross 'device-output') 'correctness\host-quest\device-output' @('*.json')
+    Copy-DirectoryFiles `
+        (Join-Path $cross 'device-output\quality_samples') `
+        'correctness\host-quest\device-output\quality_samples' `
+        @('*.f32')
+}
+
+if ($BenchmarkDir) {
+    $bench = (Resolve-Path $BenchmarkDir).Path
+    Write-SanitizedJson `
+        (Join-Path $bench 'benchmark-metadata.json') `
+        'benchmarks\isolated\metadata.json' `
+        @('device_serial', 'binary', 'recovery_manifest', 'recovery_manifest_sha256')
+    foreach ($name in @('benchmark-records.json', 'benchmark-summary.json', 'benchmark-summary.md')) {
+        Copy-PublicFile (Join-Path $bench $name) (Join-Path 'benchmarks\isolated' $name)
+    }
+}
+
+if ($XrDir) {
+    $xr = (Resolve-Path $XrDir).Path
+    Write-SanitizedJson `
+        (Join-Path $xr 'sweep-metadata.json') `
+        'benchmarks\live-xr\metadata.json' `
+        @('device_serial', 'recovery_manifest', 'recovery_manifest_sha256')
+    Copy-DirectoryFiles $xr 'benchmarks\live-xr\records' @('chunks-*-records.json')
+    foreach ($name in @('xr-summary.json', 'xr-summary.md')) {
+        Copy-PublicFile (Join-Path $xr $name) (Join-Path 'benchmarks\live-xr' $name)
+    }
+}
+
+$files = @(
+    Get-ChildItem -LiteralPath $destination -Recurse -File |
+        Sort-Object FullName |
+        ForEach-Object {
+            [ordered]@{
+                path = [System.IO.Path]::GetRelativePath($destination, $_.FullName).Replace('\', '/')
+                bytes = $_.Length
+                sha256 = (Get-FileHash -LiteralPath $_.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
+            }
+        }
+)
+$encoderCheckpointSha256 = '4610ad75edef83e75afdebf162d148dc628045ea6cbb83d67d4708c709c4f91d'
+if (@($files | Where-Object { $_.sha256 -eq $encoderCheckpointSha256 }).Count -ne 0) {
+    throw 'the gated DINOv3 checkpoint must not be staged'
+}
+$imagePayloads = @($files | Where-Object { $_.path -match '\.(jpe?g|png)$' })
+if ($imagePayloads.Count -ne 0) {
+    throw "dataset or reconstruction images must not be staged: $($imagePayloads.path -join ', ')"
+}
+$manifestRecord = [ordered]@{
+    schema_version = 1
+    created_utc = [DateTime]::UtcNow.ToString('o')
+    selected_seed = $SelectedSeed
+    encoder_layers = $Layers
+    image_size = $Size
+    files = $files
+}
+$manifestRecord | ConvertTo-Json -Depth 6 |
+    Set-Content -LiteralPath (Join-Path $destination 'ARTIFACT_MANIFEST.json') -Encoding utf8
+Write-Output "staged $($files.Count) explicitly selected files in $destination"

environment/training-source/source-snapshot/tools/summarize_bench.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""Aggregate raw benchmark samples across fresh device processes."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import math
+import statistics
+from collections import defaultdict
+from pathlib import Path
+from typing import Iterable
+
+
+def distribution(values: Iterable[float]) -> dict[str, float]:
+    ordered = sorted(float(value) for value in values)
+    if not ordered:
+        raise SystemExit("cannot summarize an empty distribution")
+    if any(not math.isfinite(value) or value <= 0 for value in ordered):
+        raise SystemExit("timing samples must be finite and positive")
+
+    def quantile(q: float) -> float:
+        at = q * (len(ordered) - 1)
+        lower = int(at)
+        upper = min(lower + 1, len(ordered) - 1)
+        return ordered[lower] + (ordered[upper] - ordered[lower]) * (at - lower)
+
+    return {
+        "mean": statistics.fmean(ordered),
+        "median": quantile(0.5),
+        "p25": quantile(0.25),
+        "p75": quantile(0.75),
+        "min": ordered[0],
+        "max": ordered[-1],
+    }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--records", required=True, type=Path)
+    parser.add_argument("--metadata", required=True, type=Path)
+    parser.add_argument("--output-json", required=True, type=Path)
+    parser.add_argument("--output-markdown", required=True, type=Path)
+    args = parser.parse_args()
+
+    artifact = json.loads(args.records.read_text(encoding="utf-8-sig"))
+    metadata = json.loads(args.metadata.read_text(encoding="utf-8-sig"))
+    if int(metadata["processes"]) < 3:
+        raise SystemExit("paper protocol requires at least three processes")
+    expected_samples = int(metadata["retained_samples_per_workload"])
+    if expected_samples < 20:
+        raise SystemExit("paper protocol requires at least 20 samples per process")
+
+    grouped: dict[str, list[dict[str, object]]] = defaultdict(list)
+    for record in artifact.get("records", []):
+        if record.get("kind") != "dinovision_benchmark":
+            raise SystemExit("unexpected benchmark record kind")
+        samples = record.get("samples_ms", [])
+        if len(samples) != expected_samples:
+            raise SystemExit(
+                f"{record.get('label')} has {len(samples)} samples, expected {expected_samples}"
+            )
+        computed = distribution(float(value) for value in samples)
+        for field, key in (
+            ("median_ms", "median"),
+            ("p25_ms", "p25"),
+            ("p75_ms", "p75"),
+            ("min_ms", "min"),
+            ("max_ms", "max"),
+            ("mean_ms", "mean"),
+        ):
+            if not math.isclose(
+                float(record[field]), computed[key], rel_tol=0.0, abs_tol=1e-4
+            ):
+                raise SystemExit(
+                    f"{record.get('label')} has inconsistent {field}: "
+                    f"{record[field]} vs {computed[key]} from raw samples"
+                )
+        grouped[str(record["label"])].append(record)
+
+    workloads: list[dict[str, object]] = []
+    for label, records in sorted(grouped.items()):
+        if len(records) != int(metadata["processes"]):
+            raise SystemExit(
+                f"{label!r} occurs in {len(records)} processes, expected {metadata['processes']}"
+            )
+        sources = {str(record.get("artifact_source")) for record in records}
+        if len(sources) != len(records):
+            raise SystemExit(f"{label!r} does not have one record per distinct process log")
+        macs = {int(record["macs"]) for record in records}
+        if len(macs) != 1:
+            raise SystemExit(f"{label!r} has inconsistent MAC counts")
+        mac_count = next(iter(macs))
+        samples = [float(value) for record in records for value in record["samples_ms"]]
+        timings = distribution(samples)
+        process_medians = distribution(float(record["median_ms"]) for record in records)
+        median_ms = timings["median"]
+        workloads.append(
+            {
+                "label": label,
+                "macs": mac_count,
+                "processes": len(records),
+                "samples": len(samples),
+                "timing_ms": timings,
+                "process_median_ms": process_medians,
+                "median_gflops": (2.0 * mac_count) / (median_ms / 1000.0) / 1e9,
+            }
+        )
+
+    result = {
+        "schema_version": 1,
+        "benchmark_metadata": metadata,
+        "records_sha256": hashlib.sha256(args.records.read_bytes()).hexdigest(),
+        "workloads": workloads,
+    }
+    args.output_json.parent.mkdir(parents=True, exist_ok=True)
+    args.output_markdown.parent.mkdir(parents=True, exist_ok=True)
+    args.output_json.write_text(json.dumps(result, indent=2) + "\n", encoding="utf-8")
+
+    lines = [
+        "# Isolated Quest benchmark",
+        "",
+        f"Condition: `{metadata['condition']}`. Each workload has {metadata['processes']} processes x {expected_samples} retained samples after {metadata['warmups_per_process']} warmups/process.",
+        "",
+        "| Workload | Pooled median [IQR] (ms) | Process medians: median [min, max] (ms) | Pooled min-max (ms) | Median GFLOP/s |",
+        "|---|---:|---:|---:|---:|",
+    ]
+    for workload in workloads:
+        timing = workload["timing_ms"]
+        lines.append(
+            f"| {workload['label']} "
+            f"| {timing['median']:.2f} [{timing['p25']:.2f}, {timing['p75']:.2f}] "
+            f"| {workload['process_median_ms']['median']:.2f} "
+            f"[{workload['process_median_ms']['min']:.2f}, {workload['process_median_ms']['max']:.2f}] "
+            f"| {timing['min']:.2f}-{timing['max']:.2f} "
+            f"| {workload['median_gflops']:.1f} |"
+        )
+    args.output_markdown.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"wrote {args.output_json} and {args.output_markdown}")
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/summarize_dataset.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""Summarize an immutable dataset manifest and its selected training prefix."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from collections import Counter, defaultdict
+from pathlib import Path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--manifest", required=True, type=Path)
+    parser.add_argument("--training-prefix", type=int, default=2500)
+    parser.add_argument(
+        "--class-component",
+        type=int,
+        default=2,
+        help="zero-based path component containing a class ID",
+    )
+    parser.add_argument("--output-json", required=True, type=Path)
+    parser.add_argument("--output-markdown", required=True, type=Path)
+    args = parser.parse_args()
+    if args.training_prefix < 1 or args.class_component < 0:
+        raise SystemExit("prefix must be positive and class component non-negative")
+
+    manifest_bytes = args.manifest.read_bytes()
+    manifest = json.loads(manifest_bytes)
+    if manifest.get("schema_version") != 1 or not manifest.get("images"):
+        raise SystemExit("unsupported or empty dataset manifest")
+
+    split_counts: Counter[str] = Counter()
+    source_counts: dict[str, Counter[str]] = defaultdict(Counter)
+    group_splits: dict[tuple[str, str], str] = {}
+    hashes: set[str] = set()
+    paths: set[str] = set()
+    class_counts: dict[str, Counter[str]] = defaultdict(Counter)
+    train_entries: list[dict[str, object]] = []
+    for image in manifest["images"]:
+        split = str(image["split"])
+        source = str(image["source"])
+        group = str(image["group"])
+        path = str(image["path"])
+        digest = str(image["sha256"])
+        if path in paths or digest in hashes:
+            raise SystemExit(f"duplicate path or content in manifest: {path}")
+        paths.add(path)
+        hashes.add(digest)
+        key = (source, group)
+        previous = group_splits.setdefault(key, split)
+        if previous != split:
+            raise SystemExit(f"group {source}/{group} crosses {previous} and {split}")
+        parts = Path(path).parts
+        if len(parts) <= args.class_component:
+            raise SystemExit(f"{path} has no class component {args.class_component}")
+        class_id = parts[args.class_component]
+        split_counts[split] += 1
+        source_counts[split][source] += 1
+        class_counts[split][class_id] += 1
+        if split == "train":
+            train_entries.append(image)
+
+    if len(train_entries) < args.training_prefix:
+        raise SystemExit(
+            f"training split has {len(train_entries)} entries, fewer than prefix "
+            f"{args.training_prefix}"
+        )
+    prefix_classes = Counter(
+        Path(str(image["path"])).parts[args.class_component]
+        for image in train_entries[: args.training_prefix]
+    )
+    artifact = {
+        "schema_version": 1,
+        "dataset_name": manifest.get("name"),
+        "manifest_sha256": hashlib.sha256(manifest_bytes).hexdigest(),
+        "provenance": manifest.get("provenance", []),
+        "images": len(manifest["images"]),
+        "unique_content_hashes": len(hashes),
+        "groups": len(group_splits),
+        "split_counts": dict(sorted(split_counts.items())),
+        "source_counts_by_split": {
+            split: dict(sorted(counts.items()))
+            for split, counts in sorted(source_counts.items())
+        },
+        "class_counts_by_split": {
+            split: dict(sorted(counts.items()))
+            for split, counts in sorted(class_counts.items())
+        },
+        "selected_training_prefix": args.training_prefix,
+        "selected_training_prefix_class_counts": dict(sorted(prefix_classes.items())),
+    }
+    args.output_json.parent.mkdir(parents=True, exist_ok=True)
+    args.output_markdown.parent.mkdir(parents=True, exist_ok=True)
+    args.output_json.write_text(json.dumps(artifact, indent=2) + "\n", encoding="utf-8")
+
+    lines = [
+        "# Dataset summary",
+        "",
+        f"Manifest SHA-256: `{artifact['manifest_sha256']}`.",
+        "",
+        "| Split | Images | Classes | Sources |",
+        "|---|---:|---:|---|",
+    ]
+    for split, count in sorted(split_counts.items()):
+        lines.append(
+            f"| {split} | {count} | {len(class_counts[split])} "
+            f"| {', '.join(f'{source}: {n}' for source, n in sorted(source_counts[split].items()))} |"
+        )
+    lines.extend(
+        [
+            "",
+            f"The selected training prefix contains {args.training_prefix} images:",
+            "",
+            "| Class ID | Images |",
+            "|---|---:|",
+        ]
+    )
+    lines.extend(f"| {name} | {count} |" for name, count in sorted(prefix_classes.items()))
+    args.output_markdown.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"wrote {args.output_json} and {args.output_markdown}")
+
+
+if __name__ == "__main__":
+    main()

environment/training-source/source-snapshot/tools/summarize_quality.py

@@ -0,0 +1,202 @@
+#!/usr/bin/env python3
+"""Aggregate decoder training/evaluation JSON without manual transcription."""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import statistics
+from collections import defaultdict
+from pathlib import Path
+
+
+def mean_sd(values: list[float]) -> dict[str, float | None]:
+    if not values:
+        return {"mean": None, "sample_stddev": None}
+    return {
+        "mean": statistics.fmean(values),
+        "sample_stddev": statistics.stdev(values) if len(values) > 1 else None,
+    }
+
+
+def display(value: dict[str, float | None], digits: int) -> str:
+    mean = value["mean"]
+    stddev = value["sample_stddev"]
+    assert mean is not None
+    return (
+        f"{mean:.{digits}f}"
+        if stddev is None
+        else f"{mean:.{digits}f} ± {stddev:.{digits}f}"
+    )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--run-dir", action="append", required=True, type=Path)
+    parser.add_argument("--quality-name", default="quality-imagenette-validation.json")
+    parser.add_argument("--output-json", required=True, type=Path)
+    parser.add_argument("--output-markdown", required=True, type=Path)
+    parser.add_argument("--minimum-runs", type=int, default=3)
+    args = parser.parse_args()
+    if args.minimum_runs < 1:
+        raise SystemExit("--minimum-runs must be positive")
+
+    runs: list[dict[str, object]] = []
+    grouped: dict[tuple[object, ...], list[dict[str, object]]] = defaultdict(list)
+    for directory in args.run_dir:
+        training = json.loads((directory / "training.json").read_text(encoding="utf-8"))
+        quality = json.loads((directory / args.quality_name).read_text(encoding="utf-8"))
+        notes_path = directory / "run-notes.json"
+        notes = json.loads(notes_path.read_text(encoding="utf-8")) if notes_path.exists() else {}
+        checks = {
+            "decoder_hash": training["decoder_sha256"] == quality["decoder_sha256"],
+            "model_hash": training["model_sha256"] == quality["model_sha256"],
+            "manifest_hash": training["dataset_manifest_sha256"]
+            == quality["manifest_sha256"],
+            "layers": training["encoder_layers"] == quality["encoder_layers"],
+            "image_size": training["image_size"] == quality["image_size"],
+        }
+        if not all(checks.values()):
+            raise SystemExit(f"inconsistent run {directory}: {checks}")
+        run = {
+            "directory": str(directory).replace("\\", "/"),
+            "seed": training["seed"],
+            "encoder_layers": training["encoder_layers"],
+            "image_size": training["image_size"],
+            "training_images": training["training_images"],
+            "evaluation_images": quality["summary"]["count"],
+            "dataset": quality["dataset_name"],
+            "split": quality["split"],
+            "manifest_sha256": quality["manifest_sha256"],
+            "model_sha256": quality["model_sha256"],
+            "decoder_sha256": quality["decoder_sha256"],
+            "training_record_sha256": hashlib.sha256(
+                (directory / "training.json").read_bytes()
+            ).hexdigest(),
+            "quality_record_sha256": hashlib.sha256(
+                (directory / args.quality_name).read_bytes()
+            ).hexdigest(),
+            "training_seconds": training["training_seconds"],
+            # Interactive development runs are valid training/quality records,
+            # but their wall time is not a performance result.  Timing is
+            # admitted only when the run notes opt in after documenting a
+            # controlled host state; absence of notes must fail closed.
+            "training_timing_valid": notes.get("training_timing_valid", False),
+            "final_training_l1": training["final_l1"],
+            "global_psnr_db": quality["summary"]["global_psnr_db"],
+            "median_image_psnr_db": quality["summary"]["psnr_db"]["median"],
+            "median_image_ssim": quality["summary"]["ssim"]["median"],
+            "median_image_mae": quality["summary"]["mae"]["median"],
+        }
+        runs.append(run)
+        key = (
+            run["encoder_layers"],
+            run["image_size"],
+            run["dataset"],
+            run["split"],
+            run["manifest_sha256"],
+            run["model_sha256"],
+        )
+        grouped[key].append(run)
+
+    aggregates: list[dict[str, object]] = []
+    for (layers, size, dataset, split, manifest_sha, model_sha), cell_runs in sorted(
+        grouped.items()
+    ):
+        cell_runs.sort(key=lambda run: int(run["seed"]))
+        seeds = [int(run["seed"]) for run in cell_runs]
+        if len(cell_runs) < args.minimum_runs:
+            raise SystemExit(
+                f"{layers}L/{size}/{dataset}/{split} has {len(cell_runs)} runs; "
+                f"require at least {args.minimum_runs}"
+            )
+        if len(set(seeds)) != len(seeds):
+            raise SystemExit(f"duplicate seed in {layers}L/{size}/{dataset}/{split}: {seeds}")
+        training_counts = {int(run["training_images"]) for run in cell_runs}
+        evaluation_counts = {int(run["evaluation_images"]) for run in cell_runs}
+        if len(training_counts) != 1 or len(evaluation_counts) != 1:
+            raise SystemExit(
+                f"inconsistent sample counts in {layers}L/{size}/{dataset}/{split}"
+            )
+        valid_training_times = [
+            float(run["training_seconds"])
+            for run in cell_runs
+            if run["training_timing_valid"]
+        ]
+        aggregate = {
+            "encoder_layers": layers,
+            "image_size": size,
+            "dataset": dataset,
+            "split": split,
+            "manifest_sha256": manifest_sha,
+            "model_sha256": model_sha,
+            "seeds": seeds,
+            "runs": len(cell_runs),
+            "training_images_per_run": cell_runs[0]["training_images"],
+            "evaluation_images_per_run": cell_runs[0]["evaluation_images"],
+            "global_psnr_db": mean_sd(
+                [float(run["global_psnr_db"]) for run in cell_runs]
+            ),
+            "median_image_psnr_db": mean_sd(
+                [float(run["median_image_psnr_db"]) for run in cell_runs]
+            ),
+            "median_image_ssim": mean_sd(
+                [float(run["median_image_ssim"]) for run in cell_runs]
+            ),
+            "median_image_mae": mean_sd(
+                [float(run["median_image_mae"]) for run in cell_runs]
+            ),
+            "valid_training_timing_runs": len(valid_training_times),
+            "training_seconds": mean_sd(valid_training_times),
+        }
+        aggregates.append(aggregate)
+
+    artifact = {"schema_version": 1, "runs": runs, "aggregates": aggregates}
+    args.output_json.parent.mkdir(parents=True, exist_ok=True)
+    args.output_markdown.parent.mkdir(parents=True, exist_ok=True)
+    args.output_json.write_text(json.dumps(artifact, indent=2) + "\n", encoding="utf-8")
+
+    lines = [
+        "# Decoder quality summary",
+        "",
+        "Generated from immutable training and per-image evaluation JSON.",
+        "",
+        "| Encoder | Size | Seeds | Validation images/run | Global PSNR (dB) | Median-image PSNR (dB) | Median RGB SSIM | Median MAE |",
+        "|---:|---:|---:|---:|---:|---:|---:|---:|",
+    ]
+    for cell in aggregates:
+        lines.append(
+            f"| {cell['encoder_layers']}L | {cell['image_size']} | {cell['runs']} "
+            f"| {cell['evaluation_images_per_run']} "
+            f"| {display(cell['global_psnr_db'], 2)} "
+            f"| {display(cell['median_image_psnr_db'], 2)} "
+            f"| {display(cell['median_image_ssim'], 4)} "
+            f"| {display(cell['median_image_mae'], 4)} |"
+        )
+    lines.extend(
+        [
+            "",
+            "| Seed | Decoder SHA-256 | Training (s) | Final-batch train L1 | Global PSNR (dB) | Median RGB SSIM |",
+            "|---:|---|---:|---:|---:|---:|",
+        ]
+    )
+    for run in sorted(runs, key=lambda item: (item["encoder_layers"], item["image_size"], item["seed"])):
+        training_seconds = (
+            f"{float(run['training_seconds']):.1f}"
+            if run["training_timing_valid"]
+            else "excluded"
+        )
+        lines.append(
+            f"| {run['seed']} | `{run['decoder_sha256']}` "
+            f"| {training_seconds} "
+            f"| {float(run['final_training_l1']):.5f} "
+            f"| {float(run['global_psnr_db']):.2f} "
+            f"| {float(run['median_image_ssim']):.4f} |"
+        )
+    args.output_markdown.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"wrote {args.output_json} and {args.output_markdown}")
+
+
+if __name__ == "__main__":
+    main()