docs(requirements): 018 Gibberlink radio mode and fallback
Requirement 018: real ggwave 0.4.0 vendored and pinned, an isolated encoder in a sandboxed iframe with its own CSP, Gibberlink as a radio mode and as the fallback where speech cannot play, self-identifying frames of at most 140 bytes, and one of four decodable protocols times five stereo positions per agent. Decision 5 records the evidence that narrowed the six audible protocols to four. 🎯 Fix: 96 % 💥 Break: 1 % 💸 Tokens: 100 % ⏱️ Velocity: 100 % 🛡️ Security: 100 % 🏆 Score: 95 🚦 Gate: ✅ 90/5, tokens and velocity <= 100, security 100 % Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
94bf0b418a
commit
cbaedb4fbb
2 files changed
+149
No files matched your search
@@ -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.
|
||||
@@ -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)
|
||||
Reference in new issue
Block a user