fix(wire): BLOB columns no longer corrupt to {} — normalize ArrayBuffer to Uint8Array in both codecs

[grrowl]

Fixes #27

Problem

workerd's SqlStorage returns BLOB column values as bare ArrayBuffer. @msgpack/msgpack only special-cases ArrayBuffer.isView, so a bare ArrayBuffer fell through to encodeMap and the client silently received {} — for cold snapshots and live deltas alike. The JSON debug codec had the same gap: classify() tagged Uint8Array (u8) but not ArrayBuffer, and JSON.stringify(ArrayBuffer) is {}.

Design decision (ADR-0017)

Normalize at emission rather than rejecting BLOB-affinity columns in assertSyncCompatible. Rejection is the tool for shapes that cannot be made safe; a BLOB can be, losslessly — it is bytes, Uint8Array is the codecs' existing byte type, and a client writing the Uint8Array back stores the same bytes. The wire now has exactly one byte type: clients always receive Uint8Array, never a bare ArrayBuffer. No warning added to assertSyncCompatible — after normalization there is nothing for an author to act on.

• Binary codec (wire/frame-codec.ts): msgpack ExtensionCodec entry (custom type 0), consulted before the encodeMap fallthrough; decodes to a copied Uint8Array (returning the subarray view would alias the wire buffer — caught in adversarial review).
• JSON debug codec (wire/codec.ts): classify() tags ArrayBuffer as u8; decode was already symmetric.

Out of scope: >2^53 INTEGER precision loss (#10, wontfix) — happens before the wire; cross-referenced in the ADR and pinned in the test.

Tests

• tests/row-shape.test.ts (new, end-to-end in workerd): BLOB written as new Uint8Array([1,2,3]).buffer arrives on the subscribed client as a Uint8Array with those bytes — snapshot and live delta — alongside the other row-shape guarantees (verbatim snake_case column names, JSON TEXT stays a string, INTEGER/REAL/NULL fidelity).
• tests/codec.test.ts / tests/frame-codec.test.ts: codec-level ArrayBuffer round-trip for both codecs, plus a no-aliasing assertion on the binary path.

Full suite: 44 files / 198 tests green; tsc --noEmit clean.

Adversarial review

codex exec (gpt-5.5) reviewed the diff: found one real bug — the ext decoder returned msgpack's subarray view into the decode buffer (mutable through the transport buffer; pins the whole frame allocation behind a small BLOB). Fixed with bytes.slice() and pinned by test. It verified no ext-type collision (timestamp is built-in -1) and that all emission paths route through the updated codecs.

🤖 Generated with Claude Code