Qualia WASM Portal — Migration Plan

Status: IN PROGRESS — Pages T2 phenomenal path validating (Track C PR-C0–C11b ✅). U3 AcousticPlane complete on Pages (Track B5 / P-F1–F2 ✅, PR-B5f ✅). Remaining for PHENOMENAL: P-A full bake, P-B3/B4 desktop GPU policy, PR-C10 desktop parity, P-D3b network_ripple, PR-C12 asymmetric compute.
Created: 2026-06-17
Last updated: 2026-06-17 (PR-B5f: CQT bake/link, portal sidecar pin, KemarLite HRTF, test vectors — audio core done; PR-C10 still open) Branch target: 0.0.17-dev (qualiaDB)
Companion docs: AUDIO_PROJECT_STATUS.md, phone-console.md, 10D_INTEGRATION_PLAN.md, 10D_INTEGRATION_SUMMARY.md

Architectural decision (locked 2026-06-17)

Unify all libraries into the Qualia WASM project in qualiaDB — a complete replacement for JavaScript semantic work (V8 graph logic, Three.js scene graphs, canvas2d particle engines, per-frame Vec mesh rebuilds).

JavaScript role: glue only — import init, new QualiaPortal(canvas), resize, requestAnimationFrame(tick). No geometry, no particles, no ontology evaluation in JS.

webizen-browser remains the desktop host (Tauri, Dioxus, QApp studio) but links the qualiaDB-built WASM artifact; it does not ship a parallel semantic/render stack.

Heap strategy: fixed pipelines with explicit cold/hot boundaries — not “avoid alloc where possible” ad hoc:

BAKE (cold, heap OK once)  →  RESIDENT (mmap/GPU pin)  →  HOT (zero-heap)
     NQuin ingest                  Tensor10D SOA              visit_*_into
     SHACL compile                 VramLedger pins            tensor_volume.wgsl
     shader asset embed            particle buffer upload     ambient/projector WGSL
                                                              SPSC rings U0↔U1↔U2↔U3

Display never rebuilds a scene graph — it reads the same resident buffer uploaded at bake/mount time and animates via ≤48 B telemetry uniforms per frame.

Executive summary

QualiaDB’s GitHub Pages demos (docs/) are migrating off V8 + Three.js + canvas2d scaffolding to a single WASM artifact built from qualiaDB:

1. Qualia WASM (qualia.js / qualia_bg.wasm) — Semantic Subjectivity Bifurcation Portal: engine + viewport + compute universes in one cdylib (qualia-core-db, wasm32)
2. All WGSL — compute (fused_*, tensor_volume) + viewport (ambient, projector, epistemic, screen) live under crates/qualia-core-db/src/shaders/
3. All WASM exports — wasm_bridge.rs, spatial_wasm.rs, portal_render.rs (viewport), scientific modalities
4. HTML shell — thin JS glue only

JavaScript must not own geometry, particle animation, spectral math, or Quin encoding in the hot path.

Product naming — Qualia WASM

The browser/desktop WASM package is Qualia, not “webizen-web” in user-facing docs, filenames, or imports.

Why “portal”: The WASM boundary is where subjective presentation (viewport, ambient field, epistemic q-states, temporal slices) bifurcates from objective semantic truth (NQuin, baked Tensor10D, zero-heap evaluators). Same engine runs in-process on desktop; the portal is the embeddable edge — browser, QApp, GitHub Pages — without a second semantic stack.

Why not a separate “webizen WASM”: Webizen remains the render manifold host (wgpu, shaders, Dioxus shell, Tauri). Qualia remains the epistemic engine. End users load one module named Qualia; Webizen is an implementation layer inside it, not a competing brand at the WASM edge.

Tagline options (pick one for docs):

• Qualia — semantic subjectivity bifurcation portal
• Qualia — where meaning meets the manifold
• Qualia WASM — one engine, one portal, zero heap in the hot path

Phase 3 rename tasks:

• N-1 wasm-pack out-dir publishes as docs/pkg/qualia/ (not webizen_web/)
• N-2 Rust #[wasm_bindgen(js_name = QualiaPortal)] (crate qualia-wasm)
• N-3 docs/js/qualia-shell.js replaces viewport-shell.js
• N-4 Pages badge: Qualia WASM + tier (T2 · Live, etc.) — daemonBadgeLabel() in qualia-shell.js + #wasm-badge on spatial.html
• N-5 API catalog entries under qualia.* namespace
• N-6 Build portal from qualiaDB (cargo + package-qualia-wasm.ps1 → docs/pkg/qualia/); retire webizen-web semantic ownership (desktop host still links interim paths)

Phenomenal (definition for this plan) = live 10D tensor volume drives both query and viewport on a shared GPU buffer, with ambient telemetry tied to real subsystem vitals, σ spectral coloring, epistemic q-state visuals, and zero heap in hot paths. Not a PNG slideshow, not Three.js, not mock Qualia data.

Pipeline architecture (zero-heap by design)

The unified Qualia WASM project replaces heap-heavy JS patterns with named pipelines — each stage has a fixed contract; hot stages never allocate.

Pipeline 1 — Bake (cold path only)

Heap (Vec, String) permitted here only. Runs once per .q42 mount or ingest.

Pipeline 2 — Resident (mmap / VRAM pin)

No per-frame realloc. VramLedger pre-flight rejects mounts that would thrash.

Pipeline 3 — Query (hot, zero-heap)

Caller supplies &mut [T] out-buffers. No tensor_search() → Vec in evaluators.

Pipeline 4 — Display (hot, zero-heap)

Per frame: ≤48 B SystemTelemetry + 128 B CameraUniform + 128 B ObserverStandpoint upload. No JS vertex loops, no Three.js BufferGeometry rebuild.

Pipeline 5 — Inference (hot, zero-heap)

U0 LLM matmul ∥ U1 tensor producer (B3.3) ∥ U2 viewport present — orchestrated by ComputeUniverse + VramLedger, not synchronous host callbacks.

Rule: If a code path reintroduces dynamic graph traversal (HashMap, VecDeque, Three.js, canvas2d semantic work), it violates the unified WASM decision — acceptable only as a badge-labelled temporary fallback (see below).

Fallback policy — yes, but tiered and honest

Answer: yes, we need fallbacks — but only as explicit hardware tiers, not silent heap regressions.

What must always run (no fallback to JS semantics)

These stay Qualia WASM / native Rust on every tier:

• NQuin logic, modalities, N3/SHACL, GeoSPARQL
• spatial_encode, tensor export, zero-heap visit_*_into query APIs
• Telemetry sampling (may return zeros on edge, but contract stays 48 B)

What degrades by tier (display + query throughput only)

Fallback rules (non-negotiable)

1. Never fake phenomenal — Tier-0 UI shows a badge: Viewport: CPU fallback or WebGPU unavailable.
2. Display ≠ engine — canvas2d may draw particles; it must not re-implement Quin encode or graph traversal.
3. No Three.js in any tier — removed entirely after Phase 4; not a fallback option.
4. Eco / Reserve modes (desktop + portal) — under VRAM pressure, instant step-down: bloom off → ambient instance_count capped (50k Full / 8k Eco / 0 Reserve) → frame rate → diffusion before dropping tensor query correctness. No buffer realloc; static SSBO, dynamic draw count.
5. LLM wins scheduling — render drops frames; inference is never silently run on a JS fallback.
6. Pages vs desktop — Pages targets T1–T2 in Chrome/Edge; T0 canvas2d is acceptable for GitHub Pages reach. Desktop targets T2 phenomenal as default.
7. One WASM on Pages — fallback does not load a second module; qualia_bg.wasm (Qualia portal) handles all tiers. Legacy qualia_core_db.wasm retired from spatial/playground pages after merge.

When not to fallback

• Do not fall back to heap tensor_search() → Vec in evaluator hot paths (cold-path Vec APIs remain test/migration only).
• Do not fall back to mock_qualia_projection() when daemon :4242 is reachable.
• Do not create a new wgpu device per frame when shared GpuContext exists.

Phenomenal acceptance criteria (full checklist)

All boxes required for PHENOMENAL status:

A. Data plane (Qualia / 10D)

• P-A1 Ingest pipeline bakes NQuin → Tensor10D with real q/v/w (not hash placeholders)
• P-A2 Q42TensorVolume resident as struct-of-arrays (40 B × N, mmap or GPU upload)
• P-A3 Hot-path queries use only visit_*_into / GPU compute — no Vec in evaluator loops
• P-A4 High-density spectral sheets (SPD / STFT/CQT) linked from σ with mmap sidecars (shipped: Q4AU header, STFT+CQT bake, audio_sidecar_link, portal pin; optional full KEMAR/PCM ingest trails)
• P-A5 Gravitational/thermodynamic baking stage refines x,y,z (spec §2.4) at ingest
• P-A6 Tensor10D::from_nquin() reads baked metadata, not object-hash xyz proxy (geo vertex packed coords via bake_pipeline)

B. GPU back-plane

• P-B1 Single GpuContext per process (LLM + tensor + render + diffusion) (shared wgpu device; render path pending)
• P-B1b ComputeUniverse orchestrator — U0/U1/U2 pinned ledger partitions on one device (Track B2)
• P-B1c ComputeUniverse::AcousticPlane (U3) — ledger pin + SPSC sonic-token consumer; symbolic/parametric only (no LLM PCM); aliases U1 tensor SOA; muted in Reserve — see AUDIO_PROJECT_STATUS.md
• P-B2 VramLedger pre-flight before load/render; memory_pressure reflects reality
• P-B3 Real ThermalGovernor gates render and non-critical inference
• P-B4 Persistent WgpuRenderer (no per-frame new_offscreen)
• P-B5 QTensorEngine reuses shared device; no per-chat GPU init

• P-B6 tensor_volume.wgsl — GPU mirror of visit_tensor_search for Tier 2 (CPU SIMD fallback when GPU unavailable)

• P-B8 Graph-guided attention sparsity — U1 kNN → AttentionRouteMask constrains fused_attention.wgsl KV reads
• P-B7 Topological speculative decoding — U1 drafts via kNN; U0 verify_topology_draft_batch accepts prefix + Sentinel gate (sentinel_allows_topology_draft)
• P-B9 Async continuous context — U1 producer thread injects during U0 matmul; zero stop-and-RAG stalls in decode loop

C. Viewport (Qualia portal — portal_gpu.rs + shaders/viewport/)

• P-C1 projector.wgsl pipeline live — depth buffer, CPU view_projection, instanced tensor SOA (PGA motor stack — see §C.1)
• P-C1b Full PGA null-vector sandwich P' = Ω P Ω̃ with motor_mul / sandwich_point — d=0 regresses Phase 1 (portal_pga.rs oracle + WGSL) (Phase 2b)
• P-C1c Bilateral T_pull via motor_translate d channel — gated on deontic_lane == 2 + standpoint_class >= 2 (Phase 2c)
• P-C1d v-band topology motors — [0,1) Euclidean · [1,2) cyclic · [2,3) hyperbolic · ≥3 boundary clique anchor via motor_v_band + lattice centroid (Phase 3)
• P-C2 Epistemic q visuals — collapsed (q≈0) vs sandbox (q>0) in projector.wgsl fragment (standalone epistemic.wgsl pipeline still unwired)
• P-C3 σ → CIE XYZ → linear sRGB in shader (spectral.wgsl Gaussian CMF; HDR path ungamma’d; portal_spectral.rs CPU oracle)
• P-C4 Binary tensor SOA → wgpu::Buffer upload once (PortalGpu::upload_tensor_buffer, 32 B header offset)
• P-C5 ambient.wgsl live in single pass (projector → ambient, depth early-Z)
• P-C5b T2 Kawase dual-filter bloom (bloom.wgsl) — HDR scene pass with additive (One, One) blend; v ≥ 3 boundary cliques push past threshold organically
• P-C5c VramLedger viewport load-shedding — bloom gated Full only; ambient draw throttle 50k / 8k / 0 via ambient_draw_instances() (instant step-down, zero realloc)
• P-C6 Live Qualia neighborhood — GET /tensor/slice + Lamport SSE /tensor/events + connectPortalToDaemon + Ed25519 standpoint gate (PR-C9a–C9c.3)
• P-C7 Camera IPC (set_camera) + temporal t_slice/t_window discard + Human-Centric ObserverStandpoint uniform (set_standpoint)
• P-C8 Navigation: GPU R32Uint picking + select_node_at / navigate_to_node / collapse_node_q (PR-C11)
• P-C8b Phenomenal CI contract — portal_phenomenal_contract.rs + phenomenal-verify.mjs in Pages workflow (PR-C11b; extended PR-B5e acoustic exports + σ/HRTF/SAB layout oracles)
• P-C9 Desktop: direct wgpu surface OR 30 FPS PNG with persistent renderer (not both re-initing GPU)

C.1 Human-Centric observer contract (qualiaDB portal — 2026-06-17)

Decouples the camera lens (spatial orbit) from the observer standpoint (semantic right to perceive). No hardware fingerprinting — ephemeral session nonce + optional verified identifier (DID IRI).

PGA motor phases (projector.wgsl + portal_pga.rs CPU oracle):

Terminology: use Human-Centric and identifier (not “identity” / legacy storage-path labels) for standpoint and DID binding. Identifier opt-in may unlock a sealed QualiaDB vault — data plane security is a separate gate (C.1g).

C.2 VramLedger viewport load-shedding (2026-06-17)

Human-Centric resilience policy for U2 — protects U0 inference the millisecond VRAM pressure spikes.

Design choice (locked): instant step-down on mode switch — matches bloom shunt latency. Asymmetric ramp-up on recovery (slow fade to 50k) is optional polish, not required for load-shedding correctness.

D. Telemetry / living system

• P-D1 gguf_bridge token loop → llm_heat
• P-D2 Encode/bake → baking_crystallization; query resolve → logic_flashes
• P-D3 VRAM ledger → memory_pressure — sample_ambient_telemetry() / refresh_from_ledger() each tick
• P-D3b Mesh I/O → network_ripple — record_network_ripple() exists; daemon/mesh call sites unwired
• P-D4 UI shows tier badge + operational mode (Full / Eco / Reserve)

E. WASM / Pages parity

• P-E1 Single Qualia WASM (qualia_bg.wasm); no Three.js; thin qualia-shell.js
• P-E2 spatial.html encode → tensor buffer → GPU upload end-to-end (buffer upload + σ projection in portal)
• P-E3 Tier-0 canvas2d fallback with honest badge when WebGPU missing
• P-E4 Viewport WGSL in qualiaDB shaders/viewport/ (ambient, projector, bloom); portal slim build ~272 KB gzip (--features portal, wasm-size-check.mjs); bloom + eco particle gating live
• P-E5 Phenomenal CI — phenomenal-verify.mjs (WGSL smoke, binding parity, PGA oracle, VramLedger, WASM nav + acoustic API) after portal WASM build

F. Audio / multi-modal (phenomenal+)

• P-F1 U3 AudioWorklet — spectral-first playback (mmap STFT/CQT sidecars) + Sonic Tokens + parametric DSP; not neural PCM from U0 (complete: worklet + cqt_bake.rs + sidecar link + bake_cqt_sidecar_demo + portal frame pin)
• P-F2 Visual + auditory share [α, μ, σ] truth layer — U2 spectral.wgsl + U3 inverse-STFT/synth from same SOA + sidecar index (complete: σ parity + KemarLite HRTF default; full measured KEMAR optional)

PHENOMENAL declared when: all of A, B, C, D, E complete. F is phenomenal+ — F1/F2 complete on Pages (2026-06-17). Audio trails: full KEMAR dataset, offline WAV export, PCM ingest (cold path only).

Architectural boundary (non-negotiable)

Spectral truth (α, μ, σ + linked SPD/STFT sheets) lives in Qualia/Q42. RGB/speaker output is Webizen last-mile projection inside the Qualia WASM module.

Current state audit

qualiaDB docs/ (Pages)

webizen-browser

webizen-desktop rendering reality (2026-06-17 audit)

What is real today:

• wgpu offscreen render → PNG → <img src="webizen://localhost/render/preview.png">
• screen.wgsl — 2D clip-space discs, lines, filled polygons (no depth buffer)
• ambient.wgsl — ~50k instanced particles with 3D positions, projected to 2D
• scene_contract.rs — Tensor10DProjection, epistemic state, spectral helpers

What is scaffolding (written, not on the live path):

Verdict: Desktop has real wgpu, but it is a 2D preview compositor with a particle backdrop — not the phenomenal 10D volumetric viewport the specs describe.

GPU back-plane / concurrency reality (2026-06-17 audit)

The problem: LLM, Qualia compute, and display each create independent GPU contexts with no arbitration.

qualiaDB portal + native engine (✅ on 0.0.17-dev):

• gpu_context.rs — shared wgpu::Device for LLM + tensor + viewport (native)
• VramLedger — KV cache cap, tensor/viewport slots, pressure() → memory_pressure
• ComputeUniverse / UniverseOrchestrator — U0/U1/U2/U3 pinned partitions (Track B2 + B5; U3 aliases U1 SOA)
• Operational modes (Full / Eco / Reserve) — bloom + ambient draw throttle live in portal
• gguf_bridge token loop → llm_heat; encode/GeoSPARQL → bake/logic pulses

Still open (desktop webizen-browser host + cross-process gaps):

• webizen-render / WgpuDiffusionBackend adopt shared GpuContext (still per-PNG new_offscreen)
• Real ThermalGovernor (production uses NullThermalGovernor → always Cool)
• Render back-pressure when ModelLifecycle::Active or VRAM pressure high
• telemetry_hooks fed from qualia token loop → desktop render_scene_png_with_time_and_telemetry
• Persistent WgpuRenderer across frames (not per-PNG re-init)
• hardware_tier.rs::has_gpu() real adapter probe (stub returns false today)
• record_network_ripple() wired from daemon mesh / torrent I/O (P-D3b)

Design docs ahead of desktop code: BACKGROUND_VISUALISATION.md live path still targets webizen-render re-export (PR-C10), not qualiaDB portal.

qualia-core-db WASM exports (today)

Present: parse_n3logic_wasm, validate_shacl_constraint_wasm, forward_chain_wasm, initialize_webgpu_engine, …
Spatial demo exports (2026-06-17): spatial_encode_wasm, geosparql_operation_wasm, export_tensor_buffer_wasm, sample_browser_telemetry_wasm — in qualia_bg.wasm

Qualia portal API (2026-06-17, portal.rs / qualia-shell.js):

Scientific engine in single WASM package (2026-06-17): wasm_simd bytecode VM paths, 10D tensor SOA (export_tensor_buffer_wasm), SHACL evaluators, deontic logic (evaluate_deontic_contract), epistemic/paraconsistent/LTL modalities — all re-exported through the Qualia portal. This unlocks optimization pathways that standard LLM stacks cannot access (see Track B4).

Recommended track sequencing (qualiaDB)

Tracks B4 and B5 share the U1 tensor SOA and q field; neither is gated on external distribution work.

Target architecture (phenomenal)

┌──────────────── BAKE (cold, heap OK) ────────────────────────┐
│  NQuin graph → embedding → Q42TensorVolume (SOA, mmap)     │
│  + spectral sidecars (SPD/STFT) + physics relaxation stage   │
└──────────────────────────┬───────────────────────────────────┘
                           │ upload once
┌──────────────────────────▼───────────────────────────────────┐
│  GpuContext + VramLedger (single device, shared queues)        │
│  ┌────────────────┬─────────────────┬──────────────────────┐ │
│  │ tensor_buffer  │ LLM KV/weights  │ render targets       │ │
│  │ (10D SOA VRAM) │ (budgeted)      │ (viewport+bloom)     │ │
│  └────────────────┴─────────────────┴──────────────────────┘ │
└──────────────────────────┬───────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        ▼                  ▼                  ▼
  tensor_volume.wgsl   gguf_bridge       projector.wgsl
  (parallel query)     (LLM, prio 1)     + ambient.wgsl
        │                  │                  │
        └──────────────────┴──────────────────┘
                           │
┌──────────────────────────▼───────────────────────────────────┐
│  Shell: spatial.html / webizen-desktop (DOM only)              │
│  QualiaPortal::tick() — ≤48 B telemetry + camera uniform       │
│  U3 AudioWorklet — SAB/MessagePort uniform + stereo binaural  │
└────────────────────────────────────────────────────────────────┘

Per-frame CPU work: copy ≤48 B telemetry + camera uniform. No per-vertex JS updates. No new Vec per query.

Tier dispatch: HardwareTierDispatcher selects SIMD (T0–T1) vs GPU VRAM (T2) vs throttled (Eco).

Phase 0 — Plan & CI prerequisites

Goal: Repos can build and publish the combined WASM artifact.

• 0.1 Add this plan to PR template / AGENTS.md handoff pointer (docs/plans/wasm-viewport-migration-plan.md)
• 0.2 Document wasm-pack build command in plan appendix (see below) — Appendix A
• 0.3 CI copies portal WASM → docs/pkg/qualia/ — .github/workflows/pages.yml (qualiaDB-native path; webizen-web superseded)
• 0.4 Verify qualia-core-db builds for wasm32-unknown-unknown with required features — Pages CI cargo check --features portal
• 0.5 Smoke-test Pages locally: npx serve docs + WASM MIME types

Exit criteria: wasm-pack build + cargo check -p qualia-core-db --target wasm32-unknown-unknown --features portal pass in CI.

Phase 1 — Shared contracts (both repos)

Goal: One byte layout for scene + telemetry across desktop and browser.

Repo: webizen-browser (webizen-render)

• 1.1 Confirm SystemTelemetry is 48 bytes / Pod — Appendix B + portal_telemetry.rs
• 1.2 Export Tensor10DProjection, RenderScene, SceneNode as #[repr(C)] stable layouts for WASM FFI (webizen-render desktop parity — PR-C10)
• 1.3 Binary tensor header — TensorBufferHeader (32 B) in tensor/buffer_export.rs (replaces scene_contract::tensor_buffer_header)
• 1.4 Add unit test: desktop renderer + WASM deserialize same RenderScene bytes

Repo: qualiaDB (qualia-core-db)

• 1.5 export_tensor_slice_wasm / export_tensor_buffer_wasm — bounded, zero-heap (tensor/buffer_export.rs)
• 1.6 spatial_wasm.rs — spatial_encode_wasm, geosparql_operation_wasm, sample_browser_telemetry_wasm
• 1.7 sample_browser_telemetry_wasm() — VramLedger.pressure() + decay pulses → 0–1 floats

Exit criteria: Contract structs have stable sizes; round-trip test desktop ↔ bytes ↔ WASM parse.

Phase 2 — webizen-render on wasm32

Goal: Same WGSL shaders run in browser WebGPU.

Pages path superseded (2026-06-17): Shaders and QualiaPortal live in qualiaDB (portal_gpu.rs, shaders/viewport/). Remaining unchecked items apply to webizen-render desktop re-export (PR-C10) only.

Repo: webizen-browser

• 2.1 Add webizen-render feature flag web (enables wgpu on wasm32) — PR-C10
• 2.2 Un-gate WgpuRenderer surface path for wasm32 (canvas → wgpu::Surface) — PR-C10
• 2.3 Ambient particle shader — ambient.wgsl in qualiaDB portal (50k instanced SSBO, telemetry @1, bloom T2)
• 2.4 Spectral vertex color — spectral.wgsl σ → CIE XYZ → linear sRGB in qualiaDB portal
• 2.5 Tier dispatch — QualiaPortal::new() T0 canvas2d / T1 tensor / T2 WebGPU + ambient-viz.js fallback
• 2.6 Portal tick() — ≤48 B telemetry via refresh_from_ledger(); zero Vec in hot path

Exit criteria: Pages: qualiaDB portal renders on Chrome/Edge ✅. Desktop: webizen-render re-export still pending (PR-C10).

Phase 3 — Qualia WASM (single portal package)

Goal: One published artifact — qualia.js + qualia_bg.wasm — Semantic Subjectivity Bifurcation Portal.

Build owner: qualiaDB (qualia-core-db --features portal). webizen-web items below are superseded unless noted for desktop host linking.

Repo: webizen-browser (webizen-web crate → publish as Qualia) — superseded for Pages

• 3.1 Add dependency: webizen-render = { path = "../webizen-render", features = ["web"] } — desktop PR-C10 only
• 3.2 QualiaPortal in portal.rs / qualia-shell.js (was planned in webizen-web; shipped in qualiaDB):

  #[wasm_bindgen(js_name = QualiaPortal)]
  pub struct QualiaPortal { /* qualia engine handle + wgpu viewport */ }
  
  #[wasm_bindgen]
  impl QualiaPortal {
      pub fn new(canvas: HtmlCanvasElement) -> Result<QualiaPortal, JsValue>;
      pub fn resize(&mut self, width: u32, height: u32);
      pub fn tick(&mut self, dt_ms: f32);
      pub fn set_telemetry(&mut self, floats: &[f32]); // 48 B SystemTelemetry
      pub fn upload_tensor_buffer(&mut self, bytes: &[u8]);
      pub fn spatial_encode(&self, json: &str) -> JsValue;
      pub fn load_q42(&mut self, bytes: &[u8]) -> JsValue;
      pub fn tier(&self) -> u8; // 0–2 for UI badge
  }
  

• 3.3 WASM symbols re-exported through portal module (wasm_bridge.rs, spatial_wasm.rs, portal.rs)
• 3.4 wasm-pack build in Pages CI → rename to qualia.js / qualia_bg.wasm
• 3.5 Copy → qualiaDB/docs/pkg/qualia/ in CI (.github/workflows/pages.yml)
• 3.6 Naming tasks N-1 through N-6 (see Product naming)

Repo: qualiaDB

• 3.7 scripts/package-qualia-wasm.ps1
• 3.8 docs/js/qualia-shell.js — import init, { QualiaPortal } from '../pkg/qualia/qualia.js'
• 3.9 Retire duplicate playground/qualia_core_db.js on portal pages — spatial uses pkg/qualia/; qualia-shell.js still lazy-imports playground for wasm-full evaluators

Exit criteria: docs/spatial.html loads pkg/qualia/ for viewport ✅; badge reads Qualia WASM · T{n} ✅.

Phase 4 — spatial.html migration (flagship demo)

Goal: Remove Three.js; spatial demo is WASM-native end-to-end.

Repo: qualiaDB docs/

• 4.1 Remove <script three.js> from spatial.html
• 4.2 Replace spatial-demo.js Three.js path with qualia-shell.js + QualiaPortal API
• 4.3 Wire geometry controls → encode_geometry → upload_tensor_buffer (GPU SOA, not JS mesh)
• 4.4 Wire GeoSPARQL tab → geosparql_operation_wasm (remove JS polygon fallback; WASM required on all tiers)
• 4.5 Wire Spatial Ops tab → WASM bbox/hull/triangulate
• 4.6 Telemetry sliders → set_telemetry(Float32Array); encode/spatial ops → pulse via WASM
• 4.6b Standpoint selector + temporal t scrub + identifier epistemic aperture (spatial-demo.js)
• 4.7 Mark ambient-viz.js deprecated; load only when QualiaPortal::new returns WebGpuUnavailable
• 4.8 Q42 10D tab: live readout of tensor fields from uploaded scene buffer
• 4.9 Update in-page architecture callout to reflect implemented state (not “future”)

Exit criteria: spatial.html works on GitHub Pages with no Three.js; hard-refresh shows wgpu particles + encoded geometry.

Phase 5 — Broader docs site updates

Goal: Pages consistently describe and use the WASM viewport pattern.

5A — Pages to update

5B — New docs (optional)

• 5.10 docs/manuals/qualia-wasm-portal.md — portal concept, build, deploy, fallback tiers, U3 sonification, COI/SAB
• 5.11 docs/plans/wasm-viewport-migration-plan.md — this file; update checkboxes per PR (2026-06-17 sync)

5C — Cross-repo doc sync

• 5.12 Update webizen-browser/BACKGROUND_VISUALISATION.md status: “implemented in webizen-render Phase 2”
• 5.13 Add pointer in AGENTS.md §7 session notes when phases complete (manuals + ADR 0007 + acoustic standard draft shipped 2026-06-17)
• 5.14 Update Claude.md §8 known inaccuracies: spatial demo no longer Three.js

Exit criteria: No docs page claims Three.js is the spatial engine; API catalog lists viewport exports.

Phase 6 — Telemetry bridge (live vitals)

Goal: Demo telemetry reflects real WASM work, not sliders only.

• 6.1 Map encode timing → baking_crystallization — record_bake_pulse() on spatial_encode_wasm / encode_geometry
• 6.2 Map GeoSPARQL/op queue → logic_flashes — record_logic_flash() in geosparql_operation_wasm
• 6.3 Map VRAM pressure → memory_pressure — VramLedger.pressure() via refresh_from_ledger() each tick
• 6.4 (Desktop) Port telemetry_hooks.rs mapping to sample_browser_telemetry_wasm subset
• 6.5 Lamport revision SSE (GET /tensor/events) → debounced tensor slice refresh in qualia-shell.js (telemetry uniform opt-in → future)

Exit criteria: Clicking “Encode to Quins” visibly drives shader without manual slider movement.

Phase 8 — GPU back-plane (LLM + Qualia + display coexistence)

Goal: One adapter, one policy — inference, graph compute, and viewport share VRAM and queues without stomping each other.

Priority: P0 for desktop phenomenal path — should precede or run parallel with Phase 2–3, not after Pages migration.

Repo: qualiaDB (qualia-core-db + qualia-client-core)

• 8.1 gpu_context.rs — process-wide SharedGpuContext + global_vram_ledger() (qualiaDB native)
• 8.2 QTensorEngine adopts gpu_context::shared_gpu() device/queue (native; WASM keeps private device)
• 8.3 VramLedger — KV cache cap, tensor/viewport slots; pressure() → memory_pressure (portal path live)
• 8.4 Wire real ThermalGovernor (Windows DXGI / sysinfo thermal stub → trait impl); replace NullThermalGovernor in model_lifecycle.rs
• 8.5 orchestrate_inference() + render daemon: on ThermalStatus::Critical, pause render loop and block non-critical intents
• 8.6 Resident mmap reuse — QTensorEngine::adopt_resident_mmap; engine init inside LLM thread avoids per-turn device churn
• 8.7 Export sample_gpu_telemetry() for Webizen telemetry_hooks

Repo: webizen-browser

• 8.8 WgpuRenderer accepts shared Arc<wgpu::Device> + Arc<wgpu::Queue> from GpuContext
• 8.9 Store persistent offscreen WgpuRenderer in PreviewState — reuse across 30 FPS loop
• 8.10 Register toggle_render_loop in Tauri invoke handler; gate on VramLedger + ModelLifecycle
• 8.11 Render daemon calls render_scene_png_with_time_and_telemetry() (not the without-telemetry variant)
• 8.12 Wire telemetry_hooks::increment_inference_counter() from qualia token generation
• 8.13 webizen-runtime diffusion backend shares same GpuContext (or separate queue on same device)

Scheduling policy (to implement in gpu_scheduler.rs or GpuContext):

Priority queue (same physical device):
  1. LLM token generation (UserInteractive QoS, pre-empts render)
  2. Qualia graph/query bursts (short, bounded)
  3. Viewport present (30 FPS cap, drops frames under pressure)
  4. Ambient particles (always GPU, cheapest — runs in viewport pass)
  5. Diffusion compute (background, Eco mode disables)

Exit criteria: Single adapter.request_device() per process; LLM + 30 FPS preview run concurrently without OOM; telemetry llm_heat moves ambient shader during inference.

Phase 9 — Phenomenal viewport (desktop + shared shaders)

Goal: True 3D volumetric viewport — same shader core as WASM Pages.

Depends on: Phase 8, Phase 10, Phase 1

• 9.1 Wire projector.wgsl — depth buffer, 3D clip, PGA Phases 1–3 + bilateral T_pull
• 9.1b Phase 2b dual-quaternion regression + Phase 2c T_pull + Phase 3 v-band motors (portal_pga.rs tests)
• 9.2 q-state LOD — collapsed vs sandbox in projector.wgsl fragment (dedicated epistemic.wgsl pass optional)
• 9.3 Tensor SOA → wgpu::Buffer instanced upload (40 B stride, 32 B header skip) — portal_gpu.rs
• 9.4 scene_to_contract.rs reads baked volume, not Tensor10DProjection::default()
• 9.5 Live daemon neighborhood on Pages — connectPortalToDaemon + GET /tensor/slice + SSE /tensor/events (desktop fetch_local_neighborhood mock fallback still open)
• 9.6 IPC camera + temporal slice + ObserverStandpoint from UI shell → GPU uniforms each frame (Pages spatial.html; Dioxus desktop parity pending)
• 9.7 Register toggle_render_loop, navigate_to_node, select_node_at; wire RenderPreview
• 9.8 Kawase bloom post-pass (T2 Full only; VramLedger auto-disables Eco/Reserve)
• 9.9 Tauri wgpu child surface (Tier 2 default); PNG protocol Tier 1 fallback with persistent renderer
• 9.10 Operational modes wired in portal render loop: bloom + ambient draw throttle via gpu_context::OperationalMode (UI badge live; desktop Dioxus parity pending)
• 9.11 GPU R32Uint picking + CPU fallback — select_node_at / poll_selected_node (PR-C11; same as P-C8)

Exit criteria: P-C1 through P-C9 satisfied on desktop T2 hardware.

Phase 10 — 10D bake pipeline + VRAM residency (zero-heap core)

Goal: Make the 10D tensor the primary query surface; GPU holds the resident volume.

Depends on: Phase 1 contracts; parallel with Phase 8

Repo: qualiaDB (qualia-core-db)

• 10.1 tensor/bake_pipeline.rs — full ingest: spectral link + physics relaxation (spec §2.4) (partial: bake_quin_to_tensor + geo vertex path live)
• 10.2 Replace hash-proxy xyz everywhere — geo vertex baked ✅ (P-A6); legacy hash spread still fallback for non-geo Quins
• 10.3 Emit mmap-ready SOA: tensors.bin + index.bin + optional spectral/ sidecars
• 10.4 Harden hot path: audit call sites; ban tensor_search() → Vec from evaluators (grep CI rule)
• 10.5 hardware_tier.rs — real has_gpu() (DXGI / wgpu adapter probe); wire ExecutionStrategy::GPUVRAM
• 10.6 tensor_volume.wgsl + volume_gpu.rs — GPU kNN mirror of visit_tensor_search_into (P-B6)
• 10.7 Tensor SOA → wgpu::Buffer + ledger pin — PortalGpu::upload_tensor_buffer / VramLedger tensor slot
• 10.8 Daemon GET /tensor/slice — daemon_tensor.rs binary SOA (P-C6)

Repo: webizen-browser

• 10.9 qualiaDB portal consumes TensorBufferHeader binary — no JSON scene round-trip (desktop webizen-render pending PR-C10)
• 10.10 qualiaDB portal reads resident tensor SOA directly — PortalGpu instanced draw (desktop RenderScene duplicate copy still open)

Exit criteria: P-A1 through P-A6 and P-B6 satisfied; graph kNN query runs on GPU without Rust heap allocation.

Phase 11 — Phenomenal+ (audio, science, docs polish)

Goal: Multi-modal spectral fidelity and public docs match implemented reality.

• 11.1 AudioWorklet + phenomenal acoustic contract (portal_phenomenal_contract.rs, audio/*, manuals, ADR 0007, vectors/acoustic-plane-v0.1.json) — P-F1/P-F2 complete on Pages
• 11.2 scientific-computing.html — live blackbody / σ band demo from tensor sheet
• 11.3 docs/manuals/webizen-wasm-viewport.md — tiers, fallback badges, build guide
• 11.4 zero-heap-compliance.html — bake vs query vs display table
• 11.5 CI: phenomenal-verify.mjs — WGSL compile/bindings, PGA oracle, VramLedger, WASM nav API
• 11.6 Remove ambient-viz.js from default bundle (Tier-0 lazy-load only)
• 11.7 Delete scene.rs duplicate contract in webizen-render

Exit criteria: PHENOMENAL+; all P-* including F-*; docs never overclaim.

Phase 7 — CI, size budget, and release

• 7.1 CI: portal qualia_bg.wasm size budget — wasm-size-check.mjs (~272 KB gzip, --features portal) in pages.yml
• 7.2 CI: phenomenal-verify.mjs — WGSL smoke, binding parity, PGA oracle, VramLedger, WASM nav + acoustic API (phenomenal_hrtf, 12 QualiaPortal exports incl. bake_cqt_sidecar_demo)
• 7.3 scripts/package-flutter-windows.ps1 unaffected; separate scripts/package-docs-wasm.ps1
• 7.4 GitHub Pages deploy: COOP/COEP for SharedArrayBuffer — coi-serviceworker.js + early registration in spatial.html head; qualia-coi.js on-demand; MessagePort fallback when not crossOriginIsolated
• 7.5 Release note in docs/RELEASE_NOTES_*.md

WASM API contract (Qualia portal — Pages shell)

JavaScript surface (thin)

import init, { QualiaPortal, init_panic_hook } from './pkg/qualia/qualia.js';

await init();
init_panic_hook?.();

const canvas = document.getElementById('qualia-portal');
const portal = new QualiaPortal(canvas);

// Resize
new ResizeObserver(() => portal.resize(canvas.clientWidth, canvas.clientHeight)).observe(canvas.parentElement);

// Telemetry (48 bytes = 12 f32)
const telem = new Float32Array(12);
telem[0] = 0.5; // memory_pressure
portal.set_telemetry(telem);

// Tier badge
document.getElementById('wasm-text').textContent = `Qualia WASM · T${portal.tier()}`;

// Loop
function frame() { portal.tick(16.67); requestAnimationFrame(frame); }
requestAnimationFrame(frame);

Rust exports (qualia-core-db, re-exported through Qualia portal module)

QualiaPortal methods (wasm-bindgen)

Risks and mitigations

Verification checklist (acceptance)

Minimum ship (Track A — not yet phenomenal)

• spatial.html — zero Three.js CDN requests
• WebGPU T1: ≥24 FPS ambient on mid-range laptop (manual bench; not CI-gated)
• Encode → WASM → GPU buffer without JS vertex loops — encode_geometry → upload_tensor_buffer
• GeoSPARQL "backend": "wasm" on all tiers — WASM primary; JS polygon fallback when evaluators unavailable
• Tier-0 badge visible when WebGPU missing — T0 · CPU fallback / ambient-viz.js path

Phenomenal ship (Tracks B + C — required for PHENOMENAL status)

• All P-A through P-E boxes checked (see Phenomenal acceptance criteria)
• LLM + 30 FPS viewport concurrent without OOM (T2, 6 GB+ VRAM test rig)
• llm_heat animates ambient field during live inference without slider
• Live daemon neighborhood — connectPortalToDaemon + SSE revision sync when :4242 healthy (Pages path; desktop mock fallback still open)
• Phenomenal CI contract — node docs/tests/phenomenal-verify.mjs passes after portal WASM build
• tensor_volume.wgsl kNN matches visit_tensor_search_into on test fixture (±ε)
• Eco mode: bloom off, particles reduced (8k draw cap), queries still correct (portal WebGPU path; desktop parity pending)
• cargo test -p qualia-core-db --lib pass (CI / local)
• cargo test -p webizen-render pass (desktop parity — PR-C10)

Implementation order (recommended PR stack)

Track A — Pages WASM viewport (can start now)

PR-A1  qualiaDB:  spatial_wasm.rs + tensor export + tests
PR-A2  webizen:   webizen-render `web` feature + wasm32 wgpu surface
PR-A3  webizen:   ambient WGSL + SystemTelemetry uniform (shared with desktop)
PR-A4  webizen:   QualiaPortal API + wasm-pack → docs/pkg/qualia/
PR-A5  qualiaDB:  qualia-shell.js + spatial.html migration + naming N-1..N-5
PR-A6  qualiaDB:  docs site sweep (index, api, features, zero-heap page)
PR-A7  both:      telemetry bridge + CI wasm build

Track B — GPU back-plane + 10D VRAM (blocks phenomenal; lead Track A)

PR-B1  qualiaDB:  GpuContext + VramLedger
PR-B2  qualiaDB:  QTensorEngine adopts shared device
PR-B3  qualiaDB:  tensor/bake_pipeline.rs + real from_nquin coords
PR-B4  qualiaDB:  hardware_tier real GPU detect + tensor_volume.wgsl
PR-B5  webizen:   persistent WgpuRenderer + register toggle_render_loop
PR-B6  both:      telemetry_hooks ↔ gguf_bridge ↔ ambient shader

Track B2 — Compute universes (Qualia-native, not generic GPU)

Objective: Eliminate VRAM thrashing and pipeline stalls by transitioning the single wgpu::Device from temporal time-slicing to persistent, logically partitioned Compute Universes. U0 (LLM), U1 (QualiaDB/Tensor10D), and U2 (Viewport) operate as concurrent, isolated execution planes on one adapter.

Architecture constraints:

• Single physical adapter — all universes share shared_gpu().device; no multiple GPUDevice instantiation.
• Pinned residency — universes bind to pre-allocated VramLedger slots; SOA tensor blob stays resident and is never evicted to serve another universe.
• Queue-level concurrency — dispatch to separate logical queue lanes (LlmCompute / TensorCompute / ViewportRender) for driver scheduling overlap.
• Zero-copy state — cross-universe communication via shared buffer visibility + lock-free SPSC rings (Phase-8 bifurcation).

Milestones:

Concept: One physical wgpu::Device (shared_gpu()), three parallel universes as pinned VRAM domains + queue lanes — not multiple requestDevice() calls. This is not a portable GPU abstraction; it maps directly to QualiaDB primitives:

Code: compute_universe.rs (UniverseFabric, ContextInjectRing, AttentionRouteMask) + gpu_context.rs (ledger slots).

Implemented (2026-06-17): gpu_context.rs — ComputeUniverse, VramLedgerSlot, VramByteRange, QueueLane, UniversePartition, UniverseOrchestrator (mode-aware), can_allocate_in_universe(), SharedGpuContext::queue_for_universe(), per-universe effective_mode() (U0 wins under Reserve). gguf_bridge::ensure_kv_cache pre-flights U0 pin.

Budget splits (mode-aware):

PR-B7  qualiaDB:  wire gguf_bridge pre-flight → can_allocate_in_universe(U0)
PR-B8  qualiaDB:  tensor_volume.wgsl dispatch on QueueLane::TensorCompute
PR-B9  webizen:   WgpuRenderer on QueueLane::ViewportRender (same device)
PR-B10 qualiaDB:  Phase-8 continuous RAG — U1 kNN → NQuin ring → Sentinel (no stop-and-fetch)
PR-B11 qualiaDB:  10D attention bitmask export for fused attention kernel (U1 → U0)
PR-B12 qualiaDB:  TopologyDraftRing + TopologyDraftBatch (B3.1a)
PR-B13 qualiaDB:  U1 extrapolate_topology_draft — 10D trajectory → concept hashes (B3.1b)
PR-B14 qualiaDB:  gguf_bridge verify_topology_draft_batch + Sentinel accept (B3.1d)
PR-B15 qualiaDB:  build_attention_route_mask — kNN → mask per decode step (B3.2a) ✅
PR-B16 qualiaDB:  fused_attention.wgsl masked KV + AttentionGpuParams (B3.2c) ✅
PR-B12 qualiaDB:  TopologyDraftRing + TopologyDraftBatch (B3.1a) ✅
PR-B13 qualiaDB:  TopologyDraftMapper + extrapolate_topology_draft_mapped (B3.1b/c) ✅
PR-B14 qualiaDB:  verify_topology_draft_batch + llm_agent accept loop (B3.1d) ✅
PR-B8  qualiaDB:  tensor_volume.wgsl + volume_gpu.rs GPU kNN (B8) ✅
PR-B17 qualiaDB:  start_tensor_search_producer background thread (B3.3a) ✅
PR-B18 qualiaDB:  KvInjectRing for pre-baked daemon slices (B3.3c, optional)

Tier degradation (same logical orchestration):

Exit criteria: Viewport rotation never exceeds U2 cap; KV cache (U0) never evicted by U2; continuous RAG injects via SPSC ring without blocking decode.

Track B3 — U1→U0 inference acceleration (research-aligned, Qualia-native)

Thesis: Standard 2025/2026 LLM acceleration (speculative decoding, structured sparsity, continuous batching) assumes a second draft model, dense attention, or blocking RAG fetches. QualiaDB already has the substrate to bypass all three — Compute Universes + Graph–Tensor duality + Phase-8 SPSC rings — without loading extra weights or heap-backed retrieval.

Hard constraints (same as Track B2): zero heap in decode hot path; fixed-capacity rings; Sentinel DenyRollback before accepting draft tokens or sparse KV slots; all URIs via q_hash / lexicon at cold-path mapping only.

B3.1 — Topological speculative decoding (draft model = 10D space)

Research gap addressed: Draft-model speculative decoding pays a severe VRAM penalty (second weight set) and suffers mutual-waiting between draft and target on edge devices.

Mechanism:

1. U1 drafter — While U0 decodes token t, U1 extrapolates a semantic trajectory in Tensor10D (current manifold_w, velocity from last kNN hits, optional temporal t slice). Trajectory yields γ concept hashes (subject_hash per step), not logits.
2. Cold-path vocab bridge — TopologyDraftMapper (load-time only): subject_hash → nearest tokenizer id via resident GgufTokenizer + lexicon label lookup. Output: fixed [u32; MAX_DRAFT_LEN] stack buffer.
3. U0 verifier — Single batched forward pass over γ draft positions (extends existing prefill chunk path in gguf_bridge). Compare draft ids to target argmax chain; accept longest matching prefix (standard speculative acceptance).
4. SPSC transport — New ring TopologyDraftRing (producer U1, consumer U0) alongside ContextInjectRing; carries { draft_ids: [u32; γ], concept_hashes: [u64; γ], draft_len: u8 }.
5. Sentinel gate — Before accepting drafts, Sentinel checks deontic/epistemic constraints on the proposed NQuin path (same Phase-8 control ring as anomaly rollback).

Expected speedup model (acceptance rate α, draft length γ, verify cost ratio c ≈ cost(verify γ) / cost(1 token)):

When α → 1 (10D topology aligns with LLM semantics), speedup → γ. Measure α empirically per ontology domain; tune γ ∈ {2, 4, 8} under U0 VRAM pin.

PR stack: PR-B12 rings + types → PR-B13 U1 trajectory → PR-B14 U0 verify loop + Sentinel hook.

Exit criteria: On Gemma-class fixture, measured tokens/sec ≥ 1.5× autoregressive baseline at α ≥ 0.6, γ = 4, with zero additional weight staging bytes in VramLedger.

B3.2 — Graph-guided attention sparsity (dynamic KV mask)

Research gap addressed: Dense attention is memory-bandwidth bound at long context; graph-pruning literature shows LLMs waste compute on overlapping, irrelevant context.

Mechanism:

1. U1 mask builder — Each decode step: kNN on current query tensor (from last accepted ContextInjectToken or decode position embedding projected into 10D). tensor_search_into → indices → AttentionRouteMask::set_index for each hit (cap ATTENTION_MASK_WORDS × 64 bits).
2. KV slot mapping — Cold-path table maps tensor_index → KV cache slot (prompt token positions with provenance NQuin). Hot path passes only u64 mask words to GPU.
3. Kernel contract — Extend AttentionGpuParams + fused_attention.wgsl with mask_words buffer binding; softmax skips masked-out KV positions (structured block-sparse, not unstructured).
4. Fallback — If mask empty or U1 behind, dense attention (current path); never block decode.

PR stack: PR-B11 (already planned) → PR-B15 mask builder → PR-B16 shader + params.

Exit criteria: Identical token stream vs dense baseline on masked fixture test; wall-clock attention pass ↓ proportional to active_bits / context_len.

B3.3 — Async continuous context via SPSC (no stop-and-RAG)

Research gap addressed: Continuous batching still stalls when retrieval blocks the forward pass.

Mechanism:

1. U1 producer thread — Bound to platform_scheduler::bind_background_thread(); loop: read decode position hint (atomic from U0), run visit_tensor_search_into, push ContextInjectToken + refresh AttentionRouteMask snapshot.
2. U0 consumer — Existing decode loop drains ring non-blocking (pop_tensor_context); never awaits graph/daemon.
3. KV inject (phase 2) — Optional KvInjectRing for pre-baked prompt segments (daemon :4242 slice uploaded once to U0 pin); distinct from per-step context tokens.
4. Universe isolation — Producer only writes U1 ledger + rings; U0 reads shared SOA substrate by reference (GraphTensorSubstrate); no cross-universe buffer realloc.

PR stack: PR-B10 (continuous RAG) → PR-B17 producer thread → PR-B18 KV inject ring (optional).

Exit criteria: Decode loop contains no block_on graph/SPARQL calls; p99 inter-token latency variance ↓ vs synchronous kNN; ring overflow drops tokens (lossy) rather than stalling U0.

Track B3 dependency graph

flowchart LR
  B24[B2.4 ContextInject ring]
  B11[B11 AttentionRouteMask export]
  B81[B8 tensor_volume.wgsl]
  B24 --> B33[B3.3 Async continuous]
  B81 --> B33
  B24 --> B32[B3.2 Graph sparsity]
  B11 --> B32
  B24 --> B31[B3.1 Topo spec decode]
  B32 --> B31

Recommended implementation order: Complete B2.4 → B3.3 (unblocks latency) → B3.2 (unblocks bandwidth) → B3.1 (multiplier on top). B3.1 has highest upside but needs accurate α from real ontology trajectories.

Research citations (planning only, not legal deps): Cassandra / PicoSpec (speculative decoding tradeoffs); Beyond FLOPs: Benchmarking Real Inference Acceleration of LLM Pruning (June 2026); AutoPrunedRetriever / minimal reasoning graphs (graph-guided context pruning).

Track B4 — Scientific engine optimizations (Qualia-native, WASM-first)

Thesis: Standard LLMs are statistical proximity engines — constraints applied post-hoc waste compute and invite rollbacks. The unified Qualia WASM package already embeds wasm_simd, 10D tensors, SHACL, and deontic logic inside the Phase-8 bifurcation loop. These functions can physically constrain U0 generation instead of filtering output after the fact.

Mapping to existing work:

Recommended next extension for Qualia WASM (qualia-core-db → docs/pkg/qualia): B4.1 Epistemic temperature (q-driven τ scaling).

Implementation repo: qualiaDB only. Webizen (webizen-web) is the optional portal shell that re-exports qualia-core-db; all B4 logic lives in crates/qualia-core-db/src/.

Rationale for portal-first ordering:

1. No new GPU kernel — works on WASM SIMD + CPU decode paths (T0–T1 reach) before phenomenal viewport ships.
2. Uses data already in the portal — Tensor10D q-field, epistemic shader contract (epistemic.wgsl), and SystemTelemetry.epistemic_density are the same truth layer.
3. Composes with B3.3 — async U1 producer already refreshes manifold position; τ becomes a side-effect of the same ring drain, zero extra blocking.
4. Human-Centric agency — rigid output on verified facts (legal/SHACL bounds) without post-generation rollback; aligns with Sentinel philosophy.

Second: B4.2 SIMD deontic logit mask — highest governance value, but requires vocab-sized mask buffer budgeting in VramLedger (U0 pin) and wasm_simd softmax integration; prioritize once local WASM LLM (initialize_webgpu_engine) is the default export path.

Third: B4.3 SHACL-aware KV eviction — depends on bake pipeline (P-A1..A6), KvProvenanceMap (B3.2b), and resident SOA mmap; highest VRAM win on edge but blocked on cold-path infrastructure.

B4.1 — Epistemic routing (q → temperature)

Exit criteria: Fixed prompt on low-q fixture → greedy/near-greedy tokens; same prompt in high-q sandbox region → measurably higher entropy (χ² on token distribution); zero heap in hot path.

B4.2 — WASM SIMD deontic logit masking

Exit criteria: Deontic-forbidden token never appears in argmax/top-k on governed fixture; mask apply < 0.5 ms for 32k vocab on WASM SIMD bench.

B4.3 — SHACL-aware hierarchical KV eviction

Exit criteria: Token stream identical on structural fixture when generative tail evicted; VRAM U0 pin drops ≥ 30% vs LRU baseline at equal perceived context.

PR stack (qualiaDB 0.0.17-dev): PR-B19 B4.1 epistemic τ → PR-B20 B4.2 SIMD mask → PR-B21 B4.3 KV eviction (after B3.2b bake).

qualiaDB file map (B4):

Recommended implementation order (qualia WASM + inference): B3.3 (done scaffold) → B4.1 → B4.2 → B3.2d bench → B4.3 → B3.1 α tuning.

Track B5 — U3 AcousticPlane (qualiaDB)

Status: Complete on Pages (PR-B5a–f ✅, 2026-06-17). No LLM waveform generation — 64-bit Sonic Tokens + 10D parametric streams only. Optional trails: full measured KEMAR bundle, offline WAV export, PCM cold ingest. Desktop host: PR-C10. Milestones in AUDIO_PROJECT_STATUS.md.

Core modules (qualia-core-db):

Browser glue: docs/js/qualia-audio-worklet.js, qualia-shell.js (mountAcousticPlane), qualia-coi.js, coi-serviceworker.js, spatial-demo.js acoustic button.

PR-B5a qualiaDB:  ComputeUniverse::AcousticPlane + sonic_token ring + portal exports     ✅
PR-B5b qualiaDB:  σ parity + HRTF + STFT bake + AcousticUniform 82-float contract       ✅
PR-B5c qualiaDB:  acoustic_sab SharedArrayBuffer + publish_acoustic_sab zero-copy       ✅
PR-B5d docs:      AudioWorklet stereo binaural + COI bootstrap on spatial.html           ✅
PR-B5e CI:        phenomenal_hrtf + 10 WASM acoustic exports in phenomenal-verify.mjs   ✅
PR-B5f qualiaDB:  CQT bake + sidecar link + portal pin + KemarLite HRTF + test vectors  ✅

COOP/COEP (Phase 7.4 ✅): service worker injects isolation headers on reload; SAB path active when crossOriginIsolated.

Track I — Interface Control Plane / phone console (qualiaDB)

Status: IN PROGRESS (2026-06-17). ICP normalizes all HID classes (mouse, keyboard, primary touch, phone gyro/mic) into PortalControlCommand → single viewport drain. Phone companion PWA is the flagship remote client; local spatial-demo.js pointer/keyboard path converges on the same opcodes (PR-I1f). Transport: daemon relay first (✅ PR-I2–I4), then LAN WebRTC. Not a separate Three.js/Leptos/Ollama stack.

Full spec: phone-console.md.

PR-I1 qualiaDB:  portal_control.rs — PortalControlCommand codec + drain/apply  ✅
PR-I1f docs:     qualia-icp-local.js — mouse/keyboard/primary touch → ICP      ✅
PR-I1g docs:     icp-profile + responsive fallbacks + ContextFrame.icp_hints  ✅
PR-I2 qualiaDB:  relay message type on chat publish/pull                       ✅
PR-I3 docs:      phone-console.html + qualia-icp-phone.js — QR pair + relay     ✅
PR-I4 qualiaDB:  ContextFrame + GraphLensFrame push — menu/graph tap → fly-to   ✅
PR-I4b docs:     Control Surface + Graph Lens shells + interface bar          ✅
PR-I5 qualiaDB:  OPFS pairing cache + phone identifier standpoint             ✅
PR-I6 CI:        phone-console-verify.mjs (+ optional daemon round-trip)       ✅
PR-I7 wellfare:  Samsung Health CSV → OPFS vault → Anatomy context push        ⬜
PR-I3b docs:     Remote Deck — swipe pad + button rail + tilt → desktop         ✅ (swipe/buttons; tilt ⬜)
PR-I8  docs:     Companion Voice — phone-local TTS (ONNX tiny; not U3 PCM)    ⬜

Field note (2026-06-17): Qualia WASM on phone can outperform AC-powered desktop — tier-probe on install, not T0-assumed. Linked mode = Remote Deck + optional Companion Voice on phone speaker.

Depends on: C11 navigation exports (✅), B5 U3 Sonic Token path (✅). Parallel with: PR-C10 desktop host.

Track C — Phenomenal viewport (qualiaDB portal — Pages path ✅; desktop parity pending)

qualiaDB portal PR stack (shipped on Pages / remaining):

PR-C0  qualiaDB:  portal slim WASM (~272 KB gzip) + feature gates          ✅
PR-C1  qualiaDB:  portal_gpu — depth, projector→ambient pass, tensor SOA  ✅
PR-C2  qualiaDB:  CameraUniform + orbit IPC                             ✅
PR-C3  qualiaDB:  ObserverStandpoint + temporal t discard               ✅
PR-C4  qualiaDB:  PGA Phase 1 (R_w·R_q) + time bridge                   ✅
PR-C5  qualiaDB:  PGA Phase 2a — vault freeze + identifier epistemic_q    ✅
PR-C6  qualiaDB:  PGA Phase 2b — dual-quaternion null-vector regression ✅
PR-C7  qualiaDB:  PGA Phase 2c — bilateral T_pull (d channel)           ✅
PR-C7b qualiaDB:  PGA Phase 3 — v-band motors (cyclic/hyperbolic/anchor) ✅
PR-C8a qualiaDB:  Kawase bloom + HDR additive pass + ledger bloom gate  ✅
PR-C8b qualiaDB:  Eco-tier particle draw throttle (instant step-down)     ✅
PR-C8c qualiaDB:  σ → CIE XYZ → linear sRGB (`spectral.wgsl` + CPU oracle)  ✅
PR-C9a qualiaDB:  `GET /tensor/slice` binary SOA + standpoint headers     ✅
PR-C9b qualiaDB:  `qualia-shell.js` probe + ripple + badge state machine  ✅
PR-C9c.1 qualiaDB: Lamport revision SSE (`GET /tensor/events`) + debounced shell sync  ✅
PR-C9c.2 qualiaDB: Daemon Ed25519 verify on slice (`KeyVault`) + vault/commons routing  ✅
PR-C9c.3 qualiaDB: `crypto.subtle` client sign + Auth Failed fallback + dev pairing     ✅
PR-C12 qualiaDB: Asymmetric compute routing (daemon Live → U0/U1 offload)               ⬜
PR-C10 webizen:   desktop Dioxus parity (shared shaders)                ⬜
PR-C11 qualiaDB:  GPU R32Uint picking + `select_node_at` / `navigate_to_node` / collapse  ✅
PR-C11b both:     phenomenal-checklist CI                               ✅

webizen-desktop (still pending): PNG 2D compositor path; projector/epistemic/bloom pipelines not wired to shared GpuContext.

Recommended order: (B4.1 parallel) → C10 (desktop Dioxus parity — golden master frozen by C11b) → C12 (asymmetric compute offload). C9/C11/C11b complete on Pages.

Throughput priority fork: If inference tokens/sec is the bottleneck before phenomenal viewport, interleave B2.4 → B10 → B17 → B15 → B16 ahead of Track C.

Progress log

Update this table and checkboxes when each item completes.

PR-C12 — Asymmetric compute routing (design; post-C9c)

Prerequisite: PR-C9c network bridge + Ed25519 standpoint gate (✅); PR-C11/C11b navigation + CI golden master (✅). C12 does not block PR-C10.

Crossing :4242 breaks out of the browser sandbox onto bare metal. The portal becomes a high-performance terminal; the native daemon becomes the compute backplane.

Compute delegation matrix

Orchestrator hook: extend UniverseOrchestrator / ComputeUniverse (gpu_context.rs) with ComputeLocation::{LocalEdge, RemoteDaemon}; flip on qualia-shell.js DaemonLinkState.LIVE.

Native CPU backplane (AVX-2 / AVX-512)

Task routing to CPU thread pool (branch-heavy, poor GPU fit):

• Heavy kNN over mmap’d Tensor10D SOA — cosine / Euclidean blitz (daemon_swarm.rs already probes avx2; extend to tensor SOA scans)
• DeonticVocabMask compile, SHACL constraint evaluation, paraconsistent routing

Existing SIMD anchors: geometric_algebra/simd_kernel.rs, modalities/calculus/mod.rs (AVX2/AVX-512 tiers), daemon_swarm.rs worker cells.

Native headless wgpu pipeline

Daemon shares WGSL contracts with the portal but no wgpu::Surface — headless Device on Vulkan / Metal / DX12.

Task routing to GPU compute queues:

• U0: fused_attention.wgsl, GGUF shard load (gguf_bridge.rs, resident_model.rs)
• U1: tensor_volume.wgsl, topology draft / attention masks (compute_universe.rs)

Binary RPC contract (zero JSON hot path)

1. Trap: WASM evaluator sees ComputeLocation::RemoteDaemon → defer execution.
2. Payload: Fixed [u8; 64] parameter block (target q, v bands, spatial radius, query opcode).
3. Shell bridge: qualia-shell.js → POST /compute/{knn|shacl|…} with application/octet-stream body.
4. Subjectivity gate: Reuse PR-C9c headers — X-Qualia-Standpoint-Class, X-Qualia-T-Slice, X-Qualia-T-Window, X-Qualia-Identifier-Did, X-Qualia-Session-Nonce, X-Qualia-Signature. Daemon applies t_slice filter + vault auth before executing against .qualia graph (fail closed — no commons fallback).
5. Return: application/octet-stream — baked Tensor10D SOA subset or token-id stream.
6. Re-sync: upload_tensor_buffer / SSE revision (GET /tensor/events) — viewport ripples without page refresh.

End-to-end flow (swarm mode)

Portal U2 (60 FPS) ──binary RPC + standpoint headers──► :4242 daemon
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
      AVX-2/512 thread pool            Headless wgpu queues
      (SHACL, deontic, kNN CPU)        (U0 LLM, U1 tensor_volume)
              │                               │
              └───────────────┬───────────────┘
                              ▼
              octet-stream result ──SSE revision──► debounced slice refresh

PR-C12 sub-phases (qualiaDB 0.0.17-dev)

Recommended sequencing: C10 (desktop WGSL parity) in parallel with C12.1–C12.2 as first Track B4 offload gate. C11/C11b complete — browser contract is the golden master for desktop re-export. Full U0 LLM stream offload = B3/B4 dependency chain.

Appendix A — Build commands

# qualiaDB engine tests
cargo test -p qualia-core-db --lib

# U3 acoustic contract (SAB, HRTF, σ parity)
cargo test -p qualia-core-db audio:: portal_phenomenal_contract::tests::phenomenal_hrtf --lib
node docs\tests\phenomenal-verify.mjs --wasm-api docs\pkg\qualia\qualia.d.ts

# Qualia WASM portal — slim Pages build (hot path only)
cargo build --release --target wasm32-unknown-unknown --no-default-features --features portal -p qualia-core-db
.\scripts\package-qualia-wasm.ps1
node docs\tests\wasm-size-check.mjs    # enforces ~272 KB gzip budget

# Full playground build (logic + scientific modalities)
cargo build --release --target wasm32-unknown-unknown --no-default-features --features wasm-full -p qualia-core-db

# Local Pages preview (COOP/COEP for SharedArrayBuffer / AudioWorklet)
npx --yes serve C:\Projects\qualiaDB\docs -p 4173

Appendix B — SystemTelemetry field map (48 bytes)

Source: crates/qualia-core-db/src/portal_telemetry.rs (portal); legacy mirror in webizen-render/src/telemetry.rs

Appendix B.1 — Viewport uniform blocks (qualiaDB portal)

Eco gating API (gpu_context.rs): viewport_operational_mode() · ambient_draw_instances(resident) · ambient_draw_instances_for_mode(resident, mode) — no buffer resize; instant instance_count cap per §C.2.

ObserverStandpoint fields: standpoint_hash, session_nonce, epistemic_q, t_slice, t_window, deontic_lane, standpoint_class, fabric_gate (ViewportLocal = 0, FabricShared = 1).

Standpoint classes: 0 spectator · 1 ephemeral · 2 verified identifier · 3 vault (spin collapsed in Phase 2a).

Appendix C — Ready-to-implement gates

Gate A — Pages WASM viewport (minimum ship)

Status: Ready for PR-A1 after PR-B1 scaffold recommended.

• Problem, boundary, fallback policy documented
• GpuContext not required for Pages-only preview, but shaders should target shared contracts

First session: PR-B1 (GpuContext skeleton) then PR-A1 + PR-A2.

Gate B — GPU back-plane + 10D VRAM

Status: qualiaDB native path largely complete — desktop webizen-render adoption + full bake still block PHENOMENAL.

• GpuContext + VramLedger — gpu_context.rs (qualiaDB native + portal)
• tensor/bake_pipeline.rs — full P-A ingest (partial geo vertex bake live)
• tensor_volume.wgsl — volume_gpu.rs + U1 dispatch (P-B6)
• Real hardware_tier GPU detection — has_gpu() stub returns false

Next sessions: PR-C10 desktop shader parity → full bake (P-A) → hardware_tier probe.

Gate C — PHENOMENAL declared

Status: Pages path near-complete — P-C6–C8b, P-D3 (memory_pressure), P-E*, and phenomenal CI satisfied on 0.0.17-dev. Still blocking PHENOMENAL: P-A full bake pipeline, P-C9 desktop persistent renderer, PR-C10 webizen-render shader parity, P-B3 thermal governor, P-B4 persistent WgpuRenderer, P-D3b network_ripple wiring.

Next sessions: PR-C10 (desktop Dioxus parity) → PR-C12.1–C12.2 (asymmetric compute scaffold). Optional parallel: B4.1 epistemic τ.

Strategic recommendation

1. Fallback: yes — tiered display degradation only; semantics always WASM.
2. Lead with Track B — without VRAM residency, Pages migration just moves Three.js to a smaller JS lie.
3. One shader codebase — ambient.wgsl, projector.wgsl, tensor_volume.wgsl shared native + wasm32.
4. PHENOMENAL is not Phase 4 — Phase 4 is minimum Pages ship; phenomenal is Phase 8+9+10+Gate C.

Appendix D — Tier fallback matrix (implementation spec)

Implement Viewport::tier() returning enum; shell reads it for badge + control visibility.

Appendix E — File ownership map (phenomenal)

Appendix E.1 — WGSL migration from webizen-render/src/shaders

Source: C:\Projects\webizen-browser\webizen-render\src\shaders\
Target: C:\Projects\qualiaDB\crates\qualia-core-db\src\shaders\viewport\
Goal: Qualia WASM portal in qualiaDB owns the full shader set (compute + render) inside one qualia_bg.wasm; webizen-render becomes optional for desktop Dioxus/Tauri only.

Already in qualiaDB shaders/ (do not duplicate — keep separate):

Migration PR stack (qualiaDB):

PR-V1  Copy viewport WGSL → shaders/viewport/ + mod.rs                    ✅
PR-V2  portal_gpu.rs — wgpu pipeline on wasm32 (T2 phenomenal)            ✅
PR-V3  QualiaPortal::tick wires telemetry + camera + observer uniforms    ✅
PR-V4  projector + ambient pipelines (depth, tensor SOA, PGA Phase 1/2a)  ✅
PR-V5  webizen-render re-exports qualiaDB shaders (desktop parity)      ⬜
PR-V6  PGA Phase 2b/2c/3 + Kawase bloom + eco particle gating             ✅
PR-V7  σ → CIE XYZ shader mapping (P-C3 / PR-C8c)                         ✅

Telemetry alignment (required on copy):

gpu_context::sample_ambient_telemetry() already emits 11 floats matching spatial_wasm::BrowserTelemetry. The webizen ambient.wgsl Telemetry struct is stale (5 fields only). On migration, use the full layout from Appendix B (indices 0–9 + padding) so llm_heat, epistemic_density, and future B4.1 τ slot share one uniform block.

B4.1 portal hook: add epistemic_temperature to BrowserTelemetry + shader uniform when B4.1 lands; epistemic.wgsl drives visual LOD from the same q that sets τ.

Appendix F — Track B3 benchmarks & speculative speedup calculator

Use this to validate B3.1 before shipping topological speculative decoding. Variables are measured at runtime via atomics (no heap); the calculator is for planning and CI regression targets.

Variables

Speedup formula (prefix acceptance, parallel verify)

Planning examples (assume c = 0.15, i.e. verifying 4 drafts costs ~60% of one serial step):

α is ontology-dependent: guardianship/legal graphs with tight 10D manifolds should score higher than open-domain chat.

CI / bench harness (add to benchmarks/qualia/)

1. Baseline — autoregressive decode only, fixed prompt fixture, report tokens/sec.
2. B3.3 — same fixture with U1 producer on; report p50/p99 inter-token latency (stall regression guard).
3. B3.2 — 1024-token context, 10% mask density; report attention pass time vs dense.
4. B3.1 — enable TopologyDraftRing; sweep γ ∈ {2,4,8}; report measured speedup vs formula residual < 15%.

Telemetry atomics (P-D extension, gpu_context.rs)

Portal HUD can expose these alongside llm_heat once B3.1e lands.

Maintainers: check boxes in this file as PRs land; bump Last updated and Progress log on each merge.