diff --git a/docs/requirements/018-gibberlink.md b/docs/requirements/018-gibberlink.md new file mode 100644 index 0000000..fc821ff --- /dev/null +++ b/docs/requirements/018-gibberlink.md @@ -0,0 +1,148 @@ +# 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. diff --git a/docs/requirements/README.md b/docs/requirements/README.md index 287e0b2..77d0f91 100644 --- a/docs/requirements/README.md +++ b/docs/requirements/README.md @@ -21,3 +21,4 @@ skill defines the format. - [015 - Time Range in the Rates Panel](015-rates-time-range.md) - [016 - Agents Controls in the View Row](016-agents-controls-row.md) - [017 - Legend Toggle](017-legend-toggle.md) +- [018 - Gibberlink](018-gibberlink.md)