Claude/review work allocation f32 sl#10
Merged
Merged
Conversation
…cate Relay.res
Prerequisite cleanup for the audio-first phased plan
(see STATE.a2ml [route-to-mvp]). Every change in this commit is either
a deletion of already-broken/duplicate/orphan files, a doc
realignment to match actual code, or a test-assertion flip toward
safety behaviour that the source code already provides.
Removed
api/v/ V-lang REST client (language banned estate-wide)
api/zig/ broken merge-conflict-ridden half-migration
duplicate of ffi/zig/ (8 ======= markers in burble.zig,
Zig 0.13 API in build.zig — did not compile)
signaling/Relay.res ReScript duplicate of authoritative relay.js
alloyiser.toml orphaned Alloy spec pointing at deleted api/v/burble.v
generated/alloyiser/ generated output of the above
(15 files, -4,314 LOC)
Contractile + manifest updates
.machine_readable/MUST.contractile
project-invariants populated (previously a *REMINDER placeholder):
- ban new .v files (V-lang)
- ban new .res/.resi files (ReScript)
- no api/ directory — FFI lives at ffi/zig/
- single signaling relay (signaling/relay.js)
- stub NIFs must return {:error, :not_implemented}
- Burble.LLM.process_query must not return simulated strings in prod
- STATE.a2ml test count must match reality within ±5
- ROADMAP.adoc completion claims must match STATE.a2ml
0-AI-MANIFEST.a2ml
abstract + invariants reflect Zig-FFI / AffineScript-target reality;
old `rescript-web-client = "NOT TypeScript"` invariant replaced with
`affinescript-client` (migration-in-progress) and explicit `no-v-lang`.
.machine_readable/6a2/STATE.a2ml
completion-percentage 85 → 72 with rationale (LLM, PTP HW,
Avow attestation, Opus server NIF are stubs contradicting earlier
"done" claims). Added [migration] section tracking V-removal (done)
and ReScript-removal (pending Phase 3/5). Added phased roadmap
(Phase 0 complete; Phases 1–5 enumerated) and honest
[blockers-and-issues] listing doc/reality drift.
BURBLE-PROOF-STATUS.md
collapsed from 315 lines to ~40 — removed stale "Compilation
Needs Attention / module name mismatches" section (src/ABI.idr
compiles). Points at PROOF-NEEDS.md + STATE.a2ml and honestly
flags the runtime-enforcement gaps (Avow stub, no LLM.idr,
no Timing.idr).
TOPOLOGY.md
module-map rewritten: removed api/ and signaling/Relay.res;
annotated which subtrees are stubs vs production; noted client/
web/lib migration target. Added explicit "Removed 2026-04-16"
block at the bottom.
Tests
server/test/burble/e2e/signaling_test.exs
RoomChannel catch-all handle_in + handle_info for
:participant_joined/:left landed 2026-04-09 (commit 167d46d),
but the test suite still had two @tag :known_gap tests asserting
the OLD crash behaviour. Flipped them to safety-contract
regression guards: 6 tests in a new "Channel safety contract"
describe block verify structured-error replies, no EXIT signals,
and channel liveness after malformed input. Removed the stale
"Known channel gaps" comment block at top of file.
Build / test verification
not run in this session — no toolchain (just/mix/zig) available in
the execution sandbox. All edits are syntactically conservative:
doc/a2ml/scheme text, test-assertion flips, and git rm of files
already dead. Please run `just test` locally to confirm.
Refs Phase 0 of the review plan in STATE.a2ml [route-to-mvp].
https://claude.ai/code/session_01VqoQXyDhJfFUGepiKr6P8H
…, not transcoding
Phase 1 item 1 of the audio-first plan.
The Backend behaviour's audio_encode/4 + audio_decode/3 docstrings claimed
Opus encode/decode. The actual implementation is a length-prefixed i16 LE
frame packer — no compression, bitrate parameter ignored. Burble is an
E2EE-opaque SFU (clients Opus-encode in the browser's WebRTC stack; the
server forwards ciphertext without decoding), so server-side real Opus
was never going to happen in this layer. But the mislabelling meant
callers who asked for real Opus got a silent round-trip of raw PCM
instead of a loud failure.
Changes in this commit make the contract honest and enforceable:
Backend behaviour (server/lib/burble/coprocessor/backend.ex)
- audio_encode/4 docstring rewritten: 'Pack raw PCM samples into a
length-prefixed binary frame. THIS IS NOT OPUS ENCODING.' Explains
the SFU-opaque rationale and that bitrate is ignored.
- audio_decode/3 docstring rewritten to match.
- Kernel-domain comment updated: 'Audio — PCM frame pack/unpack (NOT
Opus transcoding)'.
- New callback opus_transcode/4 — explicit entry point for real Opus.
All backends return {:error, :not_implemented}. Callers wanting real
Opus must either use the browser's WebRTC Opus encoder or request
libopus integration (deferred — STATE.a2ml [migration]).
- New callback opus_available?/0 — always false until libopus is linked.
Backend implementations
- ElixirBackend: opus_transcode returns :not_implemented; audio_encode
inline comment clarifies it's framing, not compression.
- ZigBackend: opus_transcode returns :not_implemented.
- SmartBackend: delegates opus_transcode to the underlying backend.
- SNIFBackend: delegates to ZigBackend.
Zig kernel (ffi/zig/src/coprocessor/audio.zig)
- File header comment expanded: 'PCM frame pack/unpack — NOT Opus
compression. Real Opus transcoding requires linking libopus and is
deferred'. Cross-references STATE.a2ml [migration] + the
opus_transcode/4 callback.
Regression test (server/test/burble/coprocessor/opus_contract_test.exs)
- Six tests pinning the contract:
* opus_transcode returns :not_implemented on all 3 backends
* opus_available? is false on all 3 backends
* audio_encode -> audio_decode round-trips raw PCM within i16
quantisation error (proves no lossy Opus is running)
* bitrate parameter is provably ignored (low/high-bitrate frames
are byte-identical)
* frame format is stable (1-byte channels + 4-byte LE len + i16 LE
PCM body)
STATE.a2ml
- Moved the 'nif_audio_encode/decode are not real Opus (misleadingly
named)' entry from [blockers-and-issues] to [resolved-2026-04-16].
Build / test verification: not run in this sandbox (no mix/zig).
Please run `just test` locally.
Refs Phase 1 item 1 in STATE.a2ml [route-to-mvp]. Next: decide on
client-side noise gate strategy (Phase 1 item 7) before committing it.
https://claude.ai/code/session_01VqoQXyDhJfFUGepiKr6P8H
hyperpolymath
added a commit
that referenced
this pull request
May 13, 2026
Closes tasks #6, #10, #14, #17 from ADR-0003 roadmap. Scripts (all idempotent, all DRY_RUN-aware, all gated on CF_API_TOKEN): * scripts/cf-ddns.sh — Cloudflare A-record DDNS for bolt.<zone>. Detects public IPv4 across 4 providers with fallback, sets proxied:false so UDP/7373 bypasses CF's HTTP proxy. Cron + systemd timer examples in the companion doc. * scripts/cf-worker-deploy.sh — provisions the Burble signaling relay Worker on Cloudflare. Creates ROOMS KV namespace if missing, uploads signaling/worker.js as a module Worker with KV binding, enables the workers.dev subdomain route. No wrangler dependency. Docs: * docs/developer/bolt-ddns.adoc — one-liner usage, cron entry, systemd timer alternative, IP detection providers, IPv6 future note. Reproducible env (estate-wide policy — guix primary, nix fallback): * guix.scm — replaced template placeholders with real Burble package definition. Inputs: erlang + elixir + zig + rust + openssl + curl + jq. Build phase invokes zig build -Doptimize=ReleaseFast then mix release. Source filter excludes _build/, deps/, zig-cache/, node_modules/, .git/. Zig toolchain (out-of-band, recorded for completeness): * Zig 0.15.2 installed at ~/.local/share/zig-x86_64-linux-0.15.2/ with symlink at ~/.local/bin/zig — matches FFI build.zig's targeted version. Per ada-spark memory, ~/.local/bin is wired in ~/.profile. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Changes
RSR Quality Checklist
Required
just testor equivalent)just fmtor equivalent)unsafeblocks without// SAFETY:commentsbelieve_me,unsafeCoerce,Obj.magic,Admitted,sorry).envfiles includedAs Applicable
.machine_readable/STATE.a2mlupdated (if project state changed).machine_readable/ECOSYSTEM.a2mlupdated (if integrations changed).machine_readable/META.a2mlupdated (if architectural decisions changed)TOPOLOGY.mdupdated (if architecture changed)CHANGELOGor release notes updatedsrc/interface/abi/andsrc/interface/ffi/consistent)Testing
Screenshots