Claude/review work allocation f32 sl

.machine_readable/6a2/ECOSYSTEM.a2ml

@@ -10,17 +10,32 @@ last-updated = "2026-04-11"
 
 [project]
 name = "burble"
-purpose = ""  # TODO: describe project purpose
-role = ""  # TODO: describe project role  # e.g. ffi-infrastructure, cli-tool, library, service
+purpose = "Self-hostable voice-first communications platform with P2P Claude-to-Claude AI data channel"
+role = "service"
 
 [position-in-ecosystem]
-tier = "infrastructure"  # 1 | 2 | infrastructure
+tier = "1"
 
 [related-projects]
-# relationship types: sibling-standard, dependency, dependent, inspiration, potential-consumer
-# - { name = "language-bridges", relationship = "sibling-standard" }
-# - { name = "hypatia", relationship = "potential-consumer" }
+projects = [
+  { name = "VeriSimDB", relationship = "dependency", note = "Sole data store for users, tokens, room config, provenance" },
+  { name = "proven", relationship = "dependency", note = "Formally verified crypto, password, UUID, email, path safety bridge" },
+  { name = "standards/lol", relationship = "dependency", note = "Multilingual corpus for i18n support" },
+  { name = "IDApTIK", relationship = "dependent", note = "Asymmetric co-op game consuming Burble voice bridge (VoiceBridge, spatial audio)" },
+  { name = "PanLL", relationship = "dependent", note = "Panel workspace consuming BurbleEngine, PanelBus events, VoiceTag hooks" },
+  { name = "game-server-admin", relationship = "dependent", note = "Consumes burble plexus/nexus for multi-server voice coordination" },
+  { name = "gossamer", relationship = "sibling-standard", note = "Both use Zig FFI + Idris2 ABI pattern; gossamer provides webview runtime" },
+  { name = "typed-wasm", relationship = "potential-consumer", note = "Could type-check Burble's WASM SNIF modules against typed-wasm's level system" },
+  { name = "ephapax", relationship = "sibling-standard", note = "Client desktop shell (.eph files) uses Ephapax's dyadic type system" },
+  { name = "Avow", relationship = "dependency", note = "Consent attestation framework — trust chain for room join/leave" },
+  { name = "Vext", relationship = "dependency", note = "Hash chain + capability subsumption for extension sandboxing" },
+]
 
 [integration-points]
-# External systems this project connects to
-# - { system = "gitbot-fleet", direction = "outbound", protocol = "repository_dispatch" }
+points = [
+  { system = "signaling/relay.js", direction = "internal", protocol = "HTTP PUT/GET, ephemeral SDP, 60s TTL" },
+  { system = "burble-ai-bridge.js", direction = "internal", protocol = "HTTP REST + WebSocket, port 6474/6475" },
+  { system = "VeriSimDB", direction = "outbound", protocol = "HTTP REST + ClickHouse" },
+  { system = "gitbot-fleet", direction = "outbound", protocol = "repository_dispatch (CI)" },
+  { system = "hypatia", direction = "inbound", protocol = "Hypatia scan rules via .hypatia/ config" },
+]

.machine_readable/6a2/META.a2ml

@@ -9,14 +9,24 @@ version = "0.1.0"
 last-updated = "2026-04-11"
 
 [project-info]
-type = "library"  # TODO: update type (library|binary|service|website|monorepo)  # library | binary | monorepo | service | website
-languages = []             # e.g. ["rust", "zig", "idris2"]
+type = "service"
+languages = ["elixir", "zig", "idris2", "javascript", "rescript", "ephapax"]
+languages-target = ["elixir", "zig", "idris2", "javascript", "affinescript", "ephapax"]
 license = "PMPL-1.0-or-later"
 author = "Jonathan D.A. Jewell (hyperpolymath)"
 
 [architecture-decisions]
-# ADR format: status = proposed | accepted | deprecated | superseded | rejected
-# - { id = "ADR-001", title = "Use Zig for FFI", status = "accepted", date = "2026-02-14" }
+decisions = [
+  { id = "ADR-001", title = "Elixir/Phoenix for control plane — OTP fault isolation", status = "accepted", date = "2025-12-01" },
+  { id = "ADR-002", title = "Zig for FFI coprocessor — SIMD audio + zero-cost C ABI", status = "accepted", date = "2025-12-15" },
+  { id = "ADR-003", title = "Idris2 for ABI proofs — dependent types prove correctness", status = "accepted", date = "2026-01-10" },
+  { id = "ADR-004", title = "WebRTC for media — browser-native, E2EE Insertable Streams", status = "accepted", date = "2026-01-20" },
+  { id = "ADR-005", title = "P2P mode first-class — zero-server voice + AI data channel", status = "accepted", date = "2026-02-01" },
+  { id = "ADR-006", title = "V-lang banned estate-wide — replaced by Zig FFI", status = "accepted", date = "2026-04-10" },
+  { id = "ADR-007", title = "ReScript → AffineScript client migration", status = "accepted", date = "2026-04-16" },
+  { id = "ADR-008", title = "Server-side Opus not implemented — SFU-opaque E2EE model", status = "accepted", date = "2026-04-16" },
+  { id = "ADR-009", title = "P2P AI bridge is primary Claude-to-Claude channel (not server-side Burble.LLM)", status = "accepted", date = "2026-04-16" },
+]
 
 [development-practices]
 build-tool = "just"
@@ -50,4 +60,6 @@ drift-risk-example = "single exception broadening into policy violation (e.g. Re
 effects-evidence = "benchmark execution/results and maintainer status dialogue/review"
 
 [design-rationale]
-# Key design decisions and their reasoning
+sfu-not-mcu = "Server forwards encrypted RTP opaquely (SFU), never decodes audio (MCU). This preserves E2EE: clients Opus-encode in the browser; server cannot eavesdrop. Trade-off: no server-side mixing, transcoding, or recording of decoded audio."
+p2p-first = "P2P mode (copy-paste signaling or relay at signaling/relay.js on port 6476) requires zero infrastructure. Server mode adds rooms, permissions, presence, recording — but P2P is the floor, not the ceiling."
+ai-bridge-architecture = "Claude-to-Claude messages travel: curl POST /send → Deno bridge (:6474 HTTP) → bridge WS (:6475) → p2p-voice.html → WebRTC DataChannel → remote page → remote bridge WS → remote bridge queue → remote curl GET /recv. This keeps the AI channel inside the same encrypted WebRTC session as voice."

.machine_readable/6a2/NEUROSYM.a2ml

@@ -14,10 +14,17 @@ scan-depth = "standard"  # quick | standard | deep
 report-format = "logtalk"
 
 [symbolic-rules]
-# Custom symbolic rules for this project
-# - { name = "no-unsafe-ffi", pattern = "believe_me|unsafeCoerce", severity = "critical" }
+rules = [
+  { name = "no-believe-me", pattern = "believe_me", severity = "critical", scope = "*.idr" },
+  { name = "no-assert-total", pattern = "assert_total", severity = "critical", scope = "*.idr" },
+  { name = "no-v-lang-files", pattern = "\\.v$", severity = "critical", scope = "**", note = "V-lang banned 2026-04-16" },
+  { name = "no-new-rescript", pattern = "\\.res$|\\.resi$", severity = "warning", scope = "**", note = "ReScript migration to AffineScript in progress; new .res files banned" },
+  { name = "no-opus-pretence", pattern = "opus_encode|opus_decode", severity = "warning", scope = "*.ex", note = "Backend.audio_encode is PCM framing, not Opus. Use opus_transcode/4 explicitly." },
+  { name = "stub-nif-returns-error", pattern = "simulated response", severity = "critical", scope = "*.ex", note = "Burble.LLM.process_query must not return simulated strings in production" },
+  { name = "no-system-time-outside-ptp", pattern = "System\\.system_time", severity = "warning", scope = "*.ex", note = "Should go through Burble.Timing.PTP.now/0 for clock-source awareness" },
+  { name = "tflite-model-path-validated", pattern = "nif_neural_init_model", severity = "warning", scope = "*.ex", note = "Model path not validated; model file not in priv/" },
+]
 
 [neural-config]
-# Neural pattern detection settings
-# confidence-threshold = 0.85
-# model = "hypatia-v2"
+confidence-threshold = 0.85
+model = "hypatia-v2"

.machine_readable/6a2/PLAYBOOK.a2ml

@@ -9,27 +9,49 @@ version = "0.1.0"
 last-updated = "2026-04-11"
 
 [deployment]
-# method = "gitops"  # gitops | manual | ci-triggered
-# target = "container"  # container | binary | library | wasm
+method = "manual"
+target = "container"
+container-runtime = "podman"
+container-base = "Chainguard"
+compose-file = "containers/compose.toml"
+notes = "P2P mode needs no deployment — just open p2p-voice.html + run bridge. Server mode uses `just up` (podman-compose) or `just server` (dev)."
+
+[p2p-quickstart]
+steps = [
+  "1. deno run --allow-net --allow-env client/web/burble-ai-bridge.js &",
+  "2. Open client/web/p2p-voice.html in browser",
+  "3. Exchange room codes or use signaling relay (just relay on port 6476)",
+  "4. Verify green 'bridge online' dot in AI Channel card",
+  "5. Test: curl http://localhost:6474/status",
+]
 
 [incident-response]
-# 1. Check .machine_readable/STATE.a2ml for current status
-# 2. Review recent commits and CI results
-# 3. Run `just validate` to check compliance
-# 4. Run `just security` to audit for vulnerabilities
+steps = [
+  "1. Check .machine_readable/6a2/STATE.a2ml for current status + known blockers",
+  "2. Review recent commits and CI results (git log -10, gh run list)",
+  "3. Run `just test` (Elixir + Zig tests)",
+  "4. Run `just scan` (panic-attacker static analysis)",
+  "5. For AI bridge issues: check browser console for [Burble AI] errors",
+  "6. For audio issues: check server logs for [PTP] [MediaEngine] [Pipeline] prefixes",
+]
 
 [release-process]
-# 1. Update version in STATE.a2ml, META.a2ml, Justfile
-# 2. Run `just release-preflight` (validate + quality + security + maint-hard-pass)
-# 3. Optional local permission hardening: `just perms-snapshot && just perms-lock`
-# 4. Tag and push
-# 5. Restore local permissions if needed: `just perms-restore`
-# 6. Run `just container-push` if applicable
+steps = [
+  "1. Update version in STATE.a2ml, META.a2ml, Justfile",
+  "2. Run `just test` — all green",
+  "3. Run `deno test --allow-net --allow-env --allow-run client/web/tests/` — AI bridge tests green",
+  "4. Run `just scan` — panic-attacker clean",
+  "5. Update CHANGELOG.md",
+  "6. Tag: git tag -a v<version> -m 'Release <version>'",
+  "7. Push: git push origin main --tags",
+  "8. Container: `just container-build && just container-push` if applicable",
+]
 
 [maintenance-operations]
-# Baseline audit:
-#   just maint-audit
-# Hard release gate:
-#   just maint-hard-pass
-# Permission audit:
-#   just perms-audit
+operations = [
+  { name = "full-test", command = "just test", frequency = "every commit" },
+  { name = "ai-bridge-test", command = "deno test --allow-net --allow-env --allow-run client/web/tests/", frequency = "every commit touching client/web/" },
+  { name = "static-scan", command = "just scan", frequency = "pre-release" },
+  { name = "proof-check", command = "cd src && idris2 --check ABI.idr", frequency = "when src/Burble/ABI/*.idr changes" },
+  { name = "zig-ffi-test", command = "just test-ffi", frequency = "when ffi/zig/ changes" },
+]

.machine_readable/6a2/STATE.a2ml

@@ -5,32 +5,67 @@
 
 [metadata]
 project = "burble"
-version = "1.1.0"
-last-updated = "2026-04-12"
+version = "1.1.0-pre"
+last-updated = "2026-04-16"
 status = "active"
 
 [project-context]
 name = "burble"
 purpose = "Modern, self-hostable, voice-first communications platform. Mumble successor."
-completion-percentage = 85
+completion-percentage = 72
 
 [position]
-phase = "maintenance"
-maturity = "production"
+phase = "hardening"
+maturity = "pre-production"
+rationale = "Foundations + SFU solid. LLM service, PTP hardware read, Avow attestation, Opus server NIF are stubs contradicting earlier 'done' claims. Migration in progress: V-lang removed, ReScript -> AffineScript pending."
 
 [route-to-mvp]
 milestones = [
   { name = "v0.1.0 to v0.4.0 — Foundation & Transport", completion = 100 },
   { name = "v1.0.0 — Stable Release", completion = 100 },
-  { name = "v1.1.0 — High Rigor & Resilience", completion = 80 }
+  { name = "Phase 0 — Scrub baseline (V-lang removed, docs honest)", completion = 100, date = "2026-04-16" },
+  { name = "Phase 1 — Audio dependable (Opus honest, jitter sync, comfort noise, REMB, Avow chain)", completion = 0 },
+  { name = "Phase 2 — P2P AI channel dependable (burble-ai-bridge fixes, round-trip tests, docs) — CRITICAL PATH for family/pair-programming use case", completion = 30 },
+  { name = "Phase 2b — server-side Burble.LLM (provider, circuit breaker, fixed parse_frame, NimblePool wired) — SECONDARY, not required for family use case", completion = 0 },
+  { name = "Phase 3 — RTSP + signaling + text + AffineScript client start", completion = 0 },
+  { name = "Phase 4 — PTP hardware clock via Zig NIF, phc2sys supervisor, multi-node align", completion = 0 },
+  { name = "Phase 5 — ReScript -> AffineScript completion", completion = 0 }
 ]
 
+[migration]
+v-lang = { status = "complete", date = "2026-04-16", removed = ["api/v/burble.v", "api/v/server.v", "api/zig/ (broken duplicate)", "alloyiser.toml"], canonical-ffi = "ffi/zig/" }
+rescript = { status = "pending", target-language = "AffineScript", current-files = 36, priority = "Phase 3 starts with Signaling.res + TextChat.res; Phase 5 finishes" }
+signaling-relay = { status = "consolidated", canonical = "signaling/relay.js", removed = ["signaling/Relay.res"] }
+
 [blockers-and-issues]
+doc-reality-drift = [
+  "ROADMAP.adoc claims LLM Service DONE — is a stub (provider missing, parse_frame broken)",
+  "ROADMAP.adoc claims Formal Proofs DONE — Avow attestation is data-type-only, no dependent-type enforcement",
+  "README.adoc PTP claim sub-microsecond assumes hardware — code falls back to system clock without NIF"
+]
+resolved-2026-04-16 = [
+  "Opus naming/contract drift: Backend.audio_encode/4 + audio_decode/3 docstrings rewritten to state explicitly that they are PCM frame pack/unpack, NOT Opus. Added explicit Backend.opus_transcode/4 callback returning {:error, :not_implemented} on every backend (ElixirBackend, ZigBackend, SmartBackend, SNIFBackend). Added opus_available?/0 callback (always false). Pinned by opus_contract_test.exs."
+]
 
 [critical-next-actions]
-actions = [
-  "Implement circuit breakers and health checks for cascading failure prevention.",
-  "Set up automated backups for VeriSimDB state."
+phase-2-p2p-ai-bridge = [
+  "DONE 2026-04-16: Opus honest-demotion (commit 179fa34)",
+  "DONE 2026-04-16: AI bridge receive-leg bug fix (dead setupAIChannelWithBridge replaced with inline forwarding in setupAIChannel)",
+  "DONE 2026-04-16: Bridge heartbeat + robust wsClient assign + env-var port",
+  "DONE 2026-04-16: Bridge UI status indicator (green/amber/grey dot)",
+  "DONE 2026-04-16: Deno round-trip test (POST /send on A -> GET /recv on B)",
+  "DONE 2026-04-16: CLAUDE.md troubleshooting section",
+  "NEXT: multi-message ordering test (bursts of 100 messages each way, no drops)",
+  "NEXT: reconnect-resume test (drop bridge WS mid-session, verify queue not lost)",
+  "NEXT: documentation for the Claude-to-Claude protocol patterns (task/result/chat shapes)"
+]
+phase-1-audio = [
+  "DONE 2026-04-16: Opus honest contract (opus_transcode returns :not_implemented)",
+  "NEXT: Validate TFLite neural model or gate behind feature flag",
+  "NEXT: Wire RTP-timestamp jitter sync across peers (precursor to PTP phase)",
+  "NEXT: Server-side comfort noise injection on RX silence",
+  "NEXT: REMB bitrate adaptation feedback loop",
+  "NEXT: Replace Avow stub with hash-chain audit log + non-circularity property test"
 ]
 
 [maintenance-status]
@@ -43,10 +78,17 @@ open-failures = 0
 [session-history]
 # 2026-04-03: Binary Idris2 build artifacts removed from repository. Gitignore updated
 #             to prevent future binary artifact commits.
+# 2026-04-09: RoomChannel catch-all handle_in + handle_info for :participant_joined/:left
+#             added (commit 167d46d) — closes gaps previously documented in TEST-NEEDS.md.
 # 2026-04-12: P0 believe_me sweep — MediaPipeline.idr resampleFrame converted from
 #             anonymous `believe_me frame` placeholder to named `postulate resampleFrame`
 #             with documented Zig FFI migration path to `%foreign "C:burble_resample,libburblemedia"`.
 #             Commit bf0eef3 pushed to GitHub.
+# 2026-04-16: Phase 0 scrub-baseline — deleted api/v/ (V-lang client), api/zig/ (broken
+#             merge-conflicted duplicate), signaling/Relay.res (duplicate of relay.js),
+#             alloyiser.toml (orphaned V-lang spec). Updated MUST.contractile with V/ReScript
+#             bans. Flipped @known_gap tests in signaling_test.exs (the gaps are fixed).
+#             Collapsed BURBLE-PROOF-STATUS.md. Demoted completion % to honest 72.
 
 [crg]
 grade = "C"

.machine_readable/INTENT.contractile

@@ -35,38 +35,41 @@
 
   ; === Purpose (what this repo IS) ===
   (purpose
-    "{{ONE_PARAGRAPH_PURPOSE}}"
+    "Burble is a self-hostable, privacy-first voice communications platform. It delivers sub-10ms latency WebRTC audio with an Elixir/Phoenix control plane, Zig SIMD coprocessor NIFs, and a P2P mode that requires no server at all. The AI data channel lets two Claude Code instances exchange structured JSON over the same encrypted WebRTC link used for voice, enabling pair-programming across machines."
   )
 
   ; === Anti-Purpose (what this repo is NOT — prevents scope creep) ===
   (anti-purpose
-    "{{ONE_PARAGRAPH_ANTI_PURPOSE}}"
-    ; Examples:
-    ; "This is NOT a general-purpose database — it solves one specific problem."
-    ; "This is NOT a framework — it is a library with a focused API."
-    ; "This does NOT handle authentication — that is delegated to [other repo]."
+    "Burble is NOT a general-purpose messaging platform, NOT a video conferencing tool, NOT a Discord/Slack clone. It does NOT handle text-first chat as a primary concern (text is an adjunct to voice). It does NOT require accounts, telemetry, or centralised infrastructure in P2P mode. It is NOT only for able-bodied users with modern hardware — accessibility is a structural requirement (see ADJUST.contractile)."
   )
 
   ; === Key Architectural Decisions That Must Not Be Reversed ===
   (architectural-invariants
-    ; *REMINDER: List the foundational decisions*
-    ; ("Idris2 for ABI definitions — dependent types prove interface correctness")
-    ; ("Zig for FFI — zero-cost C ABI compatibility")
-    ; ("Elixir for supervision — OTP fault tolerance")
+    ("Elixir/Phoenix for the control plane — OTP supervision, fault isolation, hot code upgrade")
+    ("Zig for the FFI coprocessor — zero-cost C ABI, SIMD audio, no runtime GC")
+    ("Idris2 for ABI proofs — dependent types prove interface correctness at compile time")
+    ("WebRTC for media transport — browser-compatible, E2EE via Insertable Streams")
+    ("P2P mode as first-class — must work with zero server infrastructure")
+    ("AffineScript for the web client (migration from ReScript in progress) — resource-aware type safety")
+    ("No V-lang anywhere — removed 2026-04-16, replaced by Zig FFI")
+    ("No TypeScript, no Python, no Go, no npm — Deno for JS runtime")
   )
 
   ; === Sensitive Areas (if in doubt, ask) ===
   (ask-before-touching
-    ; *REMINDER: List areas where LLMs should check before modifying*
-    ; "src/abi/ — formal proofs, changes require re-verification"
-    ; "ffi/zig/ — C ABI boundary, changes affect all language bindings"
-    ; ".machine_readable/ — checkpoint files, format is specified"
+    "src/Burble/ABI/ — formal proofs; changes require re-verification"
+    "ffi/zig/src/coprocessor/ — C ABI boundary; changes affect all language bindings"
+    "client/web/burble-ai-bridge.js — P2P Claude-to-Claude channel; the family-use critical path"
+    "client/web/p2p-voice.html — WebRTC signaling + AI channel setup; hard to test without two browsers"
+    ".machine_readable/ — checkpoint files; format is specified by the 6a2 standard"
+    "server/lib/burble/media/ — SFU media engine; changes affect all connected peers"
+    "server/lib/burble/timing/ptp.ex — IEEE 1588 PTP; incorrect changes cause audible artefacts"
   )
 
   ; === Ecosystem Position ===
   (ecosystem
-    (belongs-to "{{MONOREPO_OR_STANDALONE}}")
-    (depends-on ("{{DEP1}}" "{{DEP2}}"))
-    (depended-on-by ("{{CONSUMER1}}" "{{CONSUMER2}}"))
+    (belongs-to "standalone (hyperpolymath estate)")
+    (depends-on ("VeriSimDB" "proven" "Avow" "Vext" "standards/lol"))
+    (depended-on-by ("IDApTIK (voice bridge)" "PanLL (voice engine)" "game-server-admin (plexus/nexus)"))
   )
 )