# 018 - Gibberlink ## User Story As the operator, I want the radio to send agent messages as real ggwave data sound, as a mode of its own and as the fallback where speech cannot play, so that a machine can decode every message and its sender from the audio while I hear which agent transmits. ## Decisions (operator-confirmed 2026-11-17; do not re-litigate) 1. **Real ggwave**: ggwave 0.4.0 from npm (MIT, the only JavaScript build, 2022-07-05), vendored under `orchestrator/vendor/ggwave/` with its sha256 pinned, the MIT text of the upstream repository at v0.4.0 beside it (the npm tarball ships none) and a `kvb-check-legal` pass (order 2026-11-14). Rejected: a sound imitation (not decodable), the Python package (source only, a C++ toolchain at install), a rebuild from source with emscripten (toolchain cost; revisit when a newer protocol is needed). 2. **Isolated encoder**: ggwave.js needs `new Function` (embind) and WebAssembly, so it runs in a worker or a sandboxed iframe with its own CSP (`'unsafe-eval' 'wasm-unsafe-eval'`, no network, no DOM); the page posts protocol and text and plays the samples it gets back. The hub page CSP gains only the encoder's source, never `'unsafe-eval'`. The e2e in Chromium and Firefox decided (2026-11-17): a sandboxed iframe whose response also sets `sandbox allow-scripts`, so the server keeps it in an opaque origin however it loads. Rejected: `'unsafe-eval'` on the hub page, which signs with the passkey; encoding in a node subprocess of the hub (node becomes a hub runtime dependency). 3. **Mode**: Gibberlink joins Auto, Quiet, Silence and Morse. Every message sends whole as frames; MAYDAY, PAN-PAN and Sécurité speak their procedure word first, as in Quiet and Silence. Stop cuts at once, a mode change cuts and replans, and a row of a higher class cuts a running row, which sends again whole after it (as Morse, 004 decision 1). Rejected: frames only, like Morse (a MAYDAY would sound like any other chirp). 4. **Frames**: ggwave carries at most 140 bytes per transmission, so a message splits into self-identifying frames like packet radio: frame 1 is the sender's full session key, `1/m` and text, frames 2 to m its first 8 characters, `n/m` and text, each at most 140 UTF-8 bytes and never split inside a character. The session key is the row's `source`, the key the hub resolves for the sender; the text leaves out the hub's message mark. 5. **One sound per agent**: from the speaker slot that already gives voice and Morse pitch, each agent gets one of the four audible protocols the vendored ggwave decodes (Normal, Fast, Fastest, DT Fastest) and one of five stereo positions, 20 distinct sounds; they repeat beyond that. No pitch shift, as ggwave decoders listen on fixed bands. Ultrasound and custom protocols stay out. Amended 2026-11-17 on evidence: DT Normal and DT Fast of ggwave 0.4.0 fail to decode at most lengths from 5 bytes up, even on a perfect digital channel, while the four decode at every length from 1 to 140. Rejected: all six audible protocols (two undecodable); a rebuild from current upstream (decision 1); the MT protocols of the order (not in 0.4.0). 6. **Fallback**: where the burst plays today (Auto with the CPU gate closed, Quiet), a selector in the radio gear picks what plays for the rest of the message: Gibberlink frames (default), Morse keying or the hiss, today's burst. The pick is kept per browser in the radio set beside mode and squelch. Rejected: a hub setting for every browser. 7. **Volume**: frames play at the row's tone volume times the squelch, as burst and Morse do. 8. **Timing**: implemented after 015 to 017 are committed. ## Approach ```mermaid flowchart TD subgraph P["🧭 0 · Preparation"] P1["📋 Write requirement"] --> P2{"✅ Operator approves?"} P2 -- "✏️ corrections" --> P1 end P2 -- "🤖 yes, after 015 to 017" --> A1 subgraph A["📦 A · Vendor and frames"] A1["⚖️ Vendor ggwave 0.4.0, licence, legal check"] --> A2["✂️ Frames, protocol and pan per speaker"] A2 --> A3{"🧪 Unit green?"} A3 -- "🔴 no: fix" --> A2 end A3 -- "🟢 yes" --> B1 subgraph B["🔒 B · Isolated encoder"] B1["🧱 Worker or sandboxed iframe with its own CSP"] --> B2{"🧪 Decode round trip green?"} B2 -- "🔴 no: fix" --> B1 end B2 -- "🟢 yes" --> C1 subgraph C["📻 C · Radio"] C1["🎛️ Mode, fallback selector, playback, cuts"] --> C2{"🧪 E2E green?"} C2 -- "🔴 no: fix" --> C1 C2 -- "🟢 yes" --> CF{"💬 Operator feedback on screenshots and sound?"} CF -- "✏️ changes" --> C1 end CF -- "👍 fits" --> D1["🏁 Review, commit with operator OK, hand-over"] ``` ## Acceptance Criteria ### Vendor and Licence - [ ] `orchestrator/vendor/ggwave/ggwave.js` equals the file of the npm tarball `ggwave-0.4.0.tgz` (integrity `sha512-+sKq0aIEVJ7zHj4Vw+Sj/RPa91xp76ihaG5gsOKZ8ojM5+uUu3NFzAspozwBx/zeaThxP5VeIkA2bbsfWpUd2g==`), its sha256 pinned in `tests/test_hub_artifacts.py`. - [ ] `orchestrator/vendor/ggwave/LICENSE` holds the MIT text of the upstream repository at v0.4.0, the README names ggwave 0.4.0 beside the other vendored libraries, and `kvb-check-legal` reports no blocker. ### Encoder - [ ] The hub page's `Content-Security-Policy` holds no `'unsafe-eval'`; the encoder's own response carries `'unsafe-eval' 'wasm-unsafe-eval'` and `connect-src 'none'`. - [ ] For each of the four protocols, samples from the encoder decode back to the frame text with the same vendored ggwave.js. ### Frames and Sound - [ ] A 300-byte message from a 36-character session key splits into frames of at most 140 UTF-8 bytes; frame 1 starts with the full key and ` 1/m `, every later frame with the first 8 characters and ` n/m `; the frame texts joined give the message without the hub's mark. - [ ] A message with `ä`, `€` and an emoji at a frame edge splits between characters, never inside one. - [ ] Every speaker gets one stable protocol of the four and one stable stereo position from its speaker slot; four speakers in four distinct protocol slots get four distinct protocols. ### Radio - [ ] The mode row offers Gibberlink beside Auto, Quiet, Silence and Morse; in Gibberlink `RadioSet.plan` gives MAYDAY, PAN-PAN and Sécurité their procedure word, then the frames of the whole message, and every other class the frames only. - [ ] In Auto with the gate closed and in Quiet, `plan` gives the fallback after the word: Gibberlink frames by default, Morse keying or the burst when picked; the pick survives a reload in this browser and never appears in the hub settings. - [ ] Stop ends the frames at once; a MAYDAY arriving during a post's frames cuts them, and the post sends again whole after the MAYDAY. - [ ] Frames play at the row's tone volume times the squelch; squelch 0 plays none. ### Tests - [ ] Unit: frames (byte budget, headers, characters, joined text), protocol and pan per speaker slot, `plan` per mode and fallback, radio set validation of the fallback pick. - [ ] Integration: node decodes the encoder's samples for all four protocols back to the frame text; the hub serves the encoder files with their own CSP and the page CSP without `'unsafe-eval'`. - [ ] E2E: Chromium and Firefox at 1920, 1366 and 390: the Gibberlink mode button, the fallback selector in the gear, a posted message whose captured frames decode to the message, no CSP violation on the hub page; screenshots for the checkpoint.