From 10bd37c666666ca9a60483d55b127b5cf292eafe Mon Sep 17 00:00:00 2001 From: hyperpolymath <6759885+hyperpolymath@users.noreply.github.com> Date: Tue, 19 May 2026 13:43:01 +0100 Subject: [PATCH] docs(crg): add orienting READMEs to core subtree roots (#50) CRG-AUDIT-2026-04-18 immediate blocker #4 ("raise README orientation coverage in server/, client/, ffi/, tests/") + the 5/11 top-level subtree gap. Adds orienting READMEs (house style, grounded in actual contents, not stubs): server/ client/ ffi/ tests/ signaling/ scripts/ server/lib/burble/bolt/ server/lib/burble/verification/ Each cross-references the relevant ADRs and Earn-the-Core issues so the honest-status posture (ADR-0007) is consistent code-near, not just in the README. Advances #50 (CI test-pass evidence remains, depends on #39). Co-Authored-By: Claude Opus 4.7 (1M context) --- client/README.adoc | 24 +++++++++++++++++ ffi/README.adoc | 22 +++++++++++++++ scripts/README.adoc | 29 ++++++++++++++++++++ server/README.adoc | 31 ++++++++++++++++++++++ server/lib/burble/bolt/README.adoc | 24 +++++++++++++++++ server/lib/burble/verification/README.adoc | 25 +++++++++++++++++ signaling/README.adoc | 21 +++++++++++++++ tests/README.adoc | 25 +++++++++++++++++ 8 files changed, 201 insertions(+) create mode 100644 client/README.adoc create mode 100644 ffi/README.adoc create mode 100644 scripts/README.adoc create mode 100644 server/README.adoc create mode 100644 server/lib/burble/bolt/README.adoc create mode 100644 server/lib/burble/verification/README.adoc create mode 100644 signaling/README.adoc create mode 100644 tests/README.adoc diff --git a/client/README.adoc b/client/README.adoc new file mode 100644 index 0000000..b1d5cce --- /dev/null +++ b/client/README.adoc @@ -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. diff --git a/ffi/README.adoc b/ffi/README.adoc new file mode 100644 index 0000000..edf5b00 --- /dev/null +++ b/ffi/README.adoc @@ -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). diff --git a/scripts/README.adoc b/scripts/README.adoc new file mode 100644 index 0000000..a8f41d7 --- /dev/null +++ b/scripts/README.adoc @@ -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. diff --git a/server/README.adoc b/server/README.adoc new file mode 100644 index 0000000..40958b9 --- /dev/null +++ b/server/README.adoc @@ -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). diff --git a/server/lib/burble/bolt/README.adoc b/server/lib/burble/bolt/README.adoc new file mode 100644 index 0000000..3223c7d --- /dev/null +++ b/server/lib/burble/bolt/README.adoc @@ -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. diff --git a/server/lib/burble/verification/README.adoc b/server/lib/burble/verification/README.adoc new file mode 100644 index 0000000..0f0308d --- /dev/null +++ b/server/lib/burble/verification/README.adoc @@ -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). diff --git a/signaling/README.adoc b/signaling/README.adoc new file mode 100644 index 0000000..a8fb248 --- /dev/null +++ b/signaling/README.adoc @@ -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). diff --git a/tests/README.adoc b/tests/README.adoc new file mode 100644 index 0000000..62c6a73 --- /dev/null +++ b/tests/README.adoc @@ -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.