Air-gap optical transport (BRC-141): convergence plan for PiWalletSV PW1, Vault Manager CHUNK, and legacy bsvpayf2

[sirdeggen]

Context

PR #404 introduces @bsv/air-gap, the reference implementation of the experimental BRC-141 optical air-gap wire protocol (v1): a payload-agnostic, fountain-coded, one-directional screen-to-camera transport with a versioned header, 8-byte session identity, and shared conformance vectors under conformance/vectors/transport/.

The review on PR #404 asked for a linked design/tracking item covering coordination with the adjacent systems that currently ship their own incompatible optical framings:

• PiWalletSV PR #1 — versioned gzip+CBOR envelopes with stateSync, stateReceipt, state revision/hash, proposal IDs, and Atomic BEEF over its indexed PW1 transport
• Vault Manager — its own CHUNK transport plus an Atomic-BEEF/coin-state and audit model
• bsv-browser fountain.ts (bsvpayf2:) — the algorithm ancestor of @bsv/air-gap; its coding contained a JavaScript float-precision seed bug and a mis-sampled degree distribution that BRC-141 v1 deliberately corrects rather than reproduces, so there is no bit-level compatibility

Agreed convergence boundary

• BRC-141 / @bsv/air-gap owns the shared, versioned optical transport — bytes in, parts out, camera reads in, verified bytes out. It stays strictly payload-agnostic.
• A separate common wallet-state envelope (to be specified) owns capabilities, network/wallet identity, Atomic BEEF, state revision/hash, proposal/idempotency, and receipt/replay semantics. That envelope rides inside BRC-141 payloads.
• Existing PW1, CHUNK, and bsvpayf2 get explicit adapters/migration paths, not silent multi-format decoding in the shared decoder: the BRC-141 decoder accepts BRC-141 v1 parts only.

Work items

• Draft the common wallet-state envelope spec (owner: adjacent-project maintainers + ts-stack), referencing PiWalletSV PR chore(deps): bump pnpm/action-setup from 3 to 6 #1 envelope semantics as the starting inventory
• PiWalletSV: adapter/migration path from PW1 framing to BRC-141 parts carrying the common envelope
• Vault Manager: adapter/migration path from CHUNK
• bsv-browser: replace the bsvpayf2: fountain with @bsv/air-gap (no wire compatibility to preserve — the legacy coding is not reproduced by design)
• Land at least one independent second implementation (different language or codebase) passing conformance/vectors/transport/air-gap-optical.json
• Only after the above: consider promoting BRC-141 and @bsv/air-gap docs from experimental toward stable

References

• Wire spec: specs/transport/air-gap-optical.md (ts-stack) / BRC-141
• Conformance corpus: conformance/vectors/transport/air-gap-optical.json
• Review thread: PR feat(air-gap): add @bsv/air-gap one-directional optical transport v0.1.1 (wire v1, BRC-141) #404