WebGPU compute rewrite: design map + verified reference oracle + GPU spike - #11

Ground-up rewrite of Gump — the 3D face-lattice automaton — with iteration computed on the GPU and rendered/interacted in the browser. Produced by charting the foggy design work as a wayfinder decision map and resolving it. This PR is the spec + a proven compute spike, not the finished app (per the session's chosen destination).

What's here

web/reference/ — the correctness oracle

• A faithful port of dev/gump/environment.pde in world coordinates (ground truth), plus the packed per-orientation sublattice representation the GPU uses.
• Proven bit-for-bit equivalent across N=8…50 (node web/reference/verify.mjs), with a pinned golden trajectory and the N=50 cube reproducing the README's grow→sustain signature.
• Decoding the neighborhood from source caught a wrong assumption from research: the 4 coplanar neighbors are diagonal (±2,±2), not axis-aligned.

web/src/ — the WebGPU spike

• The exact rule (born {4,5} / survive {3,4,5}, 12 neighbors, toroidal) as a WGSL compute kernel, ping-ponged on the GPU.
• Compute decoupled from render via a steps-per-frame slider, with a live iterations/sec readout (the target metric).
• GPU stat reduction (population, per-orientation counts, orientation-balance variance) read back asynchronously; live population-over-time Canvas2D chart.
• Instanced oriented-quad render with an orientation ↔ heat color toggle; orbit camera.
• "Verify vs oracle" button: runs the GPU and compares state to the JS reference cell-for-cell, in-browser.

web/SPEC.md — build-ready spec consolidating every resolved decision (compute API = WebGPU, storage-buffer sublattice encoding, decoupling loop, render path, coloring, stats, symmetry metric, seed-centric interaction, controls, stack).

Resolved design decisions (the map)

WebGPU compute (primary) · N a runtime slider · seed-centric, no freehand editing · three excellent readouts: population-over-time, cell-age/heat coloring, orientation-balance variance.

Verification

node web/reference/verify.mjs             # faithful port ⇄ packed GPU representation (bit-exact)
node web/reference/verify-wgsl-table.mjs  # WGSL neighbor table ⇄ verified reference (36/36)

Correctness chain: faithful environment.pde port == packed JS == WGSL table, with execution-level proof available in-browser via the Verify button.

Run

cd web && python3 -m http.server 8000   # open http://localhost:8000/ in a WebGPU browser

Notes

• The original Processing project under dev/ is untouched; the rewrite lives beside it in web/.
• The GPU compute/render/stat kernels are written and cross-checked against the verified oracle, but WebGPU can't execute in the headless CI environment — the in-browser Verify button is the execution-level proof on a real GPU.

🤖 Generated with Claude Code

https://claude.ai/code/session_01445YRo7RS6hGSuNyBUbaxH

Generated by Claude Code