ADR 0023: Rust/WASM Atlas Layout Worker
ADR 0023: Rust/WASM Atlas Layout Worker
Status: accepted
Date: 2026-05-11
Context
The atlas view needs deterministic layout, spatial indexing, hit-test acceleration, label placement, collision handling, path tracing over loaded projection data, and visible-subgraph filtering.
These tasks are performance-sensitive and algorithmic, but the full catalog universe is large enough that ordinary student laptops should not be treated as the primary compute tier.
They are also not academic truth.
The user prefers starting with Rust/WASM for the atlas compute boundary because the project should not grow around fragile ad hoc browser computation. ADR 0026 further clarifies that this is a bounded client-side interaction tool, not a mandate to run dense universe, Advisory, or closure computation in the browser.
MDN documents WebAssembly as a code format that can run in web browsers.
MDN documents Web Workers as a way to run scripts in background threads without interfering with the user interface.
The wasm-bindgen guide documents Rust and JavaScript interoperability, including generated TypeScript bindings.
Primary references:
Decision
The first atlas implementation will require a Rust/WASM worker for layout and spatial compute on small active graph slices, fallback graph slices, and interaction-local jobs.
The worker will be named RustWasmLayoutWorker in documentation contracts.
Rendering remains in TypeScript and Three.js for v1.
The worker must not evaluate academic requirements.
The worker must not read raw catalog/index artifacts.
The worker must not call backend APIs directly.
The worker consumes compact projection inputs derived from backend graph view responses.
The worker returns positions, clusters, visibility masks, picking indices, label candidates, and layout metrics.
When backend or index-build graph projections include valid deterministic layout hints, the worker must prefer those hints over recomputing catalog-wide coordinates locally.
For broad universal Canva views, the worker should behave more like a verifier, adapter, or small adjustment layer than a full layout engine.
The worker must support deterministic seeds for reproducible layout.
The worker must expose explicit initialization, job, cancellation, error, and termination behavior.
Consequences
Layout algorithms can be written in a systems language with explicit data structures.
The browser main thread can stay responsive during heavy layout work.
The frontend codebase must include a Rust/WASM build path.
The data exchange boundary must be intentionally compact.
The implementation must test both the TypeScript wrapper and the Rust layout kernel.
The worker is a performance component, not a second source of academic meaning.
Alternatives Considered
Start with TypeScript-only layout
This would reduce the initial toolchain.
It would also defer the exact boundary the user wants to make explicit now.
The project accepts the extra setup because the atlas is central to the product.
Use Rust/WASM for rendering too
This could eventually be valuable.
It is not required for v1 and would make the first UI implementation harder.
The v1 split keeps rendering in the web ecosystem while moving deterministic layout compute to Rust/WASM.
Run every layout interaction on the Go backend
This would simplify browser packaging and protect weak laptops from heavy computation.
It would make local interaction network-dependent and could mix per-frame view geometry with backend academic services.
It is rejected for per-interaction camera, hover, selection, and small active-subgraph layout.
ADR 0026 narrows this rejection: backend or index-build layout hints are acceptable and preferred for dense catalog-wide projection artifacts, as long as they remain visual projections and not academic truth.
Verification
The atlas specs must define a worker protocol.
The worker protocol must distinguish layout failures from academic unknowns.
Tests must prove that identical inputs and seeds produce identical layout outputs within the chosen numeric tolerance.
Tests must prove that worker failure falls back to a usable 2D/list view or a degraded non-WASM layout only if explicitly marked as degraded.