feat(cat-blink): v2 fountain-coded blink wire format + shared codec#252
Open
systemslibrarian wants to merge 1 commit into
Open
feat(cat-blink): v2 fountain-coded blink wire format + shared codec#252systemslibrarian wants to merge 1 commit into
systemslibrarian wants to merge 1 commit into
Conversation
First foundation piece of the blink-to-app roadmap (docs/CAT_MODE_BLINK_ROADMAP.md steps 1-2): a single versioned wire format that replaces the two incompatible legacy blink streams and adds erasure coding so a phone that misses blinks still reconstructs the message. - docs/CAT_BLINK_V2.md: bit-exact spec. Reuses the EXISTING fountain droplet layout (seed|count|indices|data) already spoken by the QR path, Rust core, and Python/mobile decoders — the blink and QR paths now share one FEC layer; only the transport framing differs. Per-droplet frame = SYNC(3) + version + k_blocks + block_size + original_length + droplet + CRC-16/CCITT, MSB-first bits, MEOW-LCG whitened. version byte + distinct SYNC keep legacy v1 videos decodable through the untouched cat_video.py path. - Shared reference codec: web_demo/static/cat-blink-v2.js (browser + Node) and meow_decoder/cat_blink_v2.py, kept bit-for-bit identical. - Tests (no device): JS round-trip + erasure tolerance (11/11, recovers through 40% frame loss), Python equivalent (5/5), and a committed JS-generated vector that Python decodes — proving the format is genuinely cross-language. - Caught by the cross-language vector: JS whitening LCG overflowed Number's 53-bit safe range on a plain multiply and desynced from Python; fixed with Math.imul (matching catWhitening.ts / cat_video.py). - CI: Python test in the Gate-1 file list; JS round-trip via the existing node-subprocess pytest harness (test_cat_js_runner.py); npm run test:blink-v2. Remaining roadmap (need the device / follow-up PRs): wire this codec into the HTML emitter and mobile sampler, re-wire the CatCapture route, camera hardening, the Gate 4b-style screenshot CI, and the hardware-matrix blink row. Co-Authored-By: Claude Fable 5 <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
1 participant
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.
First foundation piece of the blink→app roadmap (
docs/CAT_MODE_BLINK_ROADMAP.mdsteps 1-2). Approved direction: a fresh v2 format everywhere, versioned so old recorded blink videos still decode.What this is
A single versioned blink wire format replacing the two incompatible legacy streams (standalone-demo CatProtocol packets vs the cat_video.py/Flask 68-byte-header stream), plus a fountain-coding layer so a phone that misses blinks (glare/motion/slow frames) still reconstructs by watching the loop a bit longer — exactly like the QR path.
Key design: it reuses the existing fountain droplet layout (
seed|count|indices|data) already spoken by the QR path, Rust core, and Python/mobile decoders. The blink and QR paths now share one FEC layer; only the transport framing differs.Contents
docs/CAT_BLINK_V2.md— bit-exact spec (frame = SYNC + version + k/block_size/original_length + droplet + CRC-16, MSB-first, MEOW-LCG whitened).web_demo/static/cat-blink-v2.js(browser + Node) andmeow_decoder/cat_blink_v2.py, kept bit-for-bit identical.Bug the cross-language vector caught
The JS whitening LCG (
seed * 1103515245) overflowed Number's 53-bit safe range and desynced from Python's arbitrary-precision version. Fixed withMath.imul(matchingcatWhitening.ts/cat_video.py). Without the shared vector this would have silently shipped.Remaining roadmap (follow-up PRs; need the device)
Wire the codec into the HTML emitter + mobile sampler, re-wire the
CatCaptureroute, camera hardening, the Gate 4b-style screenshot CI harness, and the hardware-matrix blink row.🤖 Generated with Claude Code