hyperpolymath · hyperpolymath · May 19, 2026 · May 19, 2026
@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= client — end-user surfaces
+:toc: preamble
+
+== Purpose
+
+Everything a participant runs. The browser client is first-class
+("browser join, no downloads"); the rest wrap or embed it.
+
+== Contents
+
+`web/`:: First-class browser client (AffineScript + WebRTC APIs).
+Mid-migration ReScript→AffineScript; client test coverage is tracked in
+issue #48 (Earn-the-Core).
+`desktop/`:: Tauri 2 native wrapper around the web client for power users.
+`lib/`:: Embeddable `@burble/client` library (BurbleClient/Voice/Spatial/
+Signaling) — used by IDApTIK (in-game voice) and PanLL (workspace voice).
+`extension/`:: Browser extension for the Claude-to-Claude AI bridge.
+
+== Status
+
+The web client is half the core value proposition and currently the
+least-tested surface — see issue #48. Treat behaviour here as
+not-yet-CI-verified until that closes.
@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= ffi — foreign-function surface
+:toc: preamble
+
+== Purpose
+
+Native code bridged into the BEAM. The Zig SIMD coprocessor is the only
+FFI surface (the former V-lang layer was removed 2026-04-16; Zig is
+canonical).
+
+== Contents
+
+`zig/`:: SIMD audio/DSP/compression/neural NIFs compiled to
+`libburble_coprocessor.so`, loaded by `Burble.Coprocessor.ZigBackend`.
+Mirrors the Idris2 ABI proofs in `verification/`. See `ffi/zig/README.adoc`
+for the per-file breakdown and benchmarks.
+
+== Note
+
+WASM crash-isolation of these kernels (SNIF, `Burble.Coprocessor.SNIFBackend`)
+is an optional experimental path that degrades to this Zig backend when
+the `wasmex` NIF is absent (ADR-0007; PR #46).
@@ -0,0 +1,29 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= scripts — operational helpers
+:toc: preamble
+
+== Purpose
+
+Operator/maintainer scripts for deployment, Bolt reachability, and build
+prerequisites. None are required for `just deploy`; they support
+specific deployment topologies.
+
+== Contents
+
+*Bolt reachability:*
+`cf-bolt-dns.sh`, `cf-ddns.sh`, `cf-worker-deploy.sh`:: Cloudflare NAPTR/
+SRV + DDNS provisioning and worker deploy for public Bolt reach.
+`gen-bolt-cert.sh`:: Ed25519/P-256 self-signed cert for Bolt-over-QUIC
+(ADR-0004).
+`check-bolt-reachability.sh`:: Verify udp/7373 is reachable end-to-end.
+`mikrotik-bolt-nat.sh`:: Router dst-NAT rule for udp/7373.
+`wsl-bolt-udp-forward.ps1`:: Windows-host UDP forwarder for running the
+Bolt listener under WSL2 without mirrored networking (ADR-0005).
+
+*Build / deploy:*
+`ensure-msquic-version.sh`, `ensure-quicer-prereqs.sh`:: Guard the
+optional QUIC toolchain (msquic/quicer; experimental — ADR-0007).
+`docker-to-podman-image.sh`, `install-desktop.sh`, `smoke-check.sh`::
+Deploy/build utilities.
+
+`burble-launcher.sh.deprecated-2026-04-10`:: Retained, deprecated.
@@ -0,0 +1,31 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= server — Elixir/Phoenix control plane
+:toc: preamble
+
+== Purpose
+
+The OTP control plane: auth, sessions, rooms, presence, permissions,
+signaling, moderation, audit, the Bolt listener, the LLM service, and the
+WebRTC SFU orchestration. Everything runs under a supervision tree so a
+crashed room never takes the node down.
+
+== Contents
+
+`lib/burble/`:: Core application (Bolt, circuit breaker, groove, llm,
+presence, store, telemetry, topology, timing, chat, transport, media,
+verification). Each implementation subtree has its own README.
+`lib/burble_web/`:: Phoenix endpoint, router, channels, controllers, CDN.
+`config/`:: Compile- and runtime-config (`runtime.exs` reads env vars).
+`priv/`:: Static assets, the Zig NIF (`libburble_coprocessor.so`), certs.
+`rel/`:: Release definitions (`mix release` / Containerfile).
+`test/`:: ExUnit suite (222+ tests; property, e2e, contract, concurrency).
+`mix.exs` / `mix.lock`:: Deps. Optional NIFs (`quicer`, `wasmex`) are
+intentionally disabled — see ADR-0004/0007; runtime degrades gracefully.
+
+`_build/`, `deps/`, `erl_crash.dump` are build/runtime artefacts, not
+tracked.
+
+== Run
+
+`cd server && mix deps.get && mix phx.server` (see root `README.adoc` for
+the full prerequisite list and one-command container path).
@@ -0,0 +1,24 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= server/lib/burble/bolt — Bolt magic-packet subsystem
+:toc: preamble
+
+== Purpose
+
+Bolt is a network-layer "poke": a magic UDP/QUIC datagram to an address
+triggers an incoming-call notification if Burble is running there
+(Wake-on-LAN-inspired). See ADR-0003 (PAKE/SAS auth), ADR-0004 (QUIC
+dual-bind), ADR-0005 (WSL inbound), ADR-0006 (framing scope).
+
+== Key files
+
+`listener.ex`:: GenServer binding raw UDP on 7373 (+ udp/9 WoL-compat),
+and optionally QUIC on the same port when `quicer` + a cert are present.
+`Burble.Bolt.Listener` is the supervised entry point.
+`sender.ex`:: Outbound bolts. `:transport` (`:auto`/`:udp`/`:quic`) +
+`:try_quic`; UDP default keeps cold pokes cheap (ADR-0004).
+`quic.ex`:: All optional `quicer` interaction, guarded so absence yields
+`{:error, :quicer_not_available}` rather than raising (ADR-0004).
+`packet.ex`:: Wire format encode/decode. Fixed-offset record decoded by
+total BEAM binary matching (ADR-0006 — why proven-frame is N/A here).
+`notify.ex`:: Dispatches a decoded bolt to the incoming-call UX path.
+`naptr.ex`:: NAPTR/SRV discovery of a host's Bolt endpoint.
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= server/lib/burble/verification — attestation & integrity
+:toc: preamble
+
+== Purpose
+
+Runtime consent attestation and capability/integrity chains. These
+mirror Idris2 ABI proofs in `verification/` (repo root) and
+`src/Burble/ABI/`.
+
+== Key files
+
+`avow.ex`:: Consent attestation hash-chain (room join/leave). Enforces
+hash-chain linkage and data-type integrity at runtime. *Dependent-type
+enforcement is not yet wired* — the Idris2 proofs compile/type-check but
+runtime enforcement is roadmap (ADR-0008, Option C; PoC issue #55).
+`vext.ex`:: Capability hash chain + subsumption (extension sandboxing);
+backed by the `Vext.idr` proofs (capability transitivity).
+`vext_groove.ex`:: Vext integration with the Groove health/feedback mesh.
+
+== Honest status
+
+Safe-by-construction for current use cases; the proof→runtime
+enforcement bridge is the subject of ADR-0008. Do not describe this tree
+as "formally enforced" until #55 reports (per ADR-0007).
@@ -0,0 +1,21 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= signaling — WebRTC signaling relay
+:toc: preamble
+
+== Purpose
+
+The lightweight signaling path that brokers WebRTC SDP/ICE between peers
+before media flows directly (SFU or P2P mesh). Kept deliberately small —
+the heavy lifting is in the OTP control plane and the media plane.
+
+== Contents
+
+`relay.js`:: Canonical signaling relay. (The former `Relay.res` was
+removed when signaling was consolidated — see `STATE.a2ml [migration]`.)
+`worker.js`:: Cloudflare Worker deployment variant of the relay for
+edge-hosted signaling.
+
+== Related
+
+Server-side signaling tests: `server/test/.../signaling_test.exs`
+(19 + 6 safety-contract regression tests).
@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: PMPL-1.0-or-later
+= tests — repo-level test trees
+:toc: preamble
+
+== Purpose
+
+Cross-cutting tests that are not part of the Elixir server's own ExUnit
+suite. Most unit/property/e2e/contract tests live in `server/test/`;
+Deno client tests live in `client/web/tests/`.
+
+== Contents
+
+`aspect/`:: Aspect tests — security hardening, accessibility, and
+diagnostics cross-concerns.
+`fuzz/`:: Fuzzing harnesses.
+`test_room_namer.exs`:: Standalone room-namer check.
+
+== Coverage map
+
+- Server logic, property, e2e, contract, concurrency → `server/test/`
+- Zig coprocessor → `just test-ffi` (`ffi/zig`, `zig build test`)
+- P2P AI bridge (Deno) → `client/web/tests/`
+- Web client suite → tracked in issue #48 (currently absent)
+
+CRG grade and CI test-pass evidence are tracked in issue #50.