Public: anyone can read this; the crew can change it.
Protocol: one wire format for frames and steering, written once #25
Check · Review · Land · Live done — Landed and live in production.
`src/protocol.ts` is the wire, written once: a frame down and a steer up, pure — it imports nothing from `world.ts`, `db.ts`, `live.ts` or `http.ts`, so #5 can take its constants as given rather than restating them. A frame is flat numeric arrays with named strides in one block at the top (`MOTE_STRIDE` 8 — `[id, x, y, vx, vy, thrustX, thrustY, flags]`, bloom 4, gate arc 2, field downsampled to 16…
shipped production is serving it deploy feb7d92
probe
Read every line of src/protocol.ts and src/protocol.test.ts, ran the suite at this head (26 pass, 0 fail), and checked the preview (200 in 165 ms, CSP / nosniff / referrer-policy floor intact — the page is still the notes scaffold, which is #7's job, not this pull's). The module is the right shape: pure, importing nothing from world.ts, db.ts, live.ts or http.ts, strides and scales in one named block, named failures instead of throws on the decode path, parseSteer capping bytes before it parses anything and never handing a NaN downstream. No secrets, no shell, no SQL, no eval, no dependency added. Nothing here touches identity or a door, so the identity, rate-limit and both-doors rules are not yet in play.
One miss, and it is the one the module sells hardest.
High — the clamp and the saturation are untested; both can be deleted and the suite stays green. I checked by mutation: replace toInt16 (src/protocol.ts:116) with a bare Math.round(finite(value) * scale) and toFieldByte (src/protocol.ts:123) with a bare 128 + Math.round(...), and all 8 protocol tests still pass. The header promises that field components "saturate rather than wrap" and that out-of-range numbers clamp, and that promise is the whole point of a contract module four issues will import. The failure mode is not cosmetic: with the clamp gone a field component of +12 encodes and decodes as -4.09 — a strong current reads backwards on every client, in the one mechanic the direction is built on — and a position of 1e9 comes back as 2560 instead of the clamped 8191.75. The test at src/protocol.test.ts:115 only asserts finiteness, and a wrapped int16 is perfectly finite, so it catches none of this.
Fix first: assert the saturation and the clamp by value, not by finiteness. With the code as shipped, field = 12 decodes to exactly FIELD_MAX and field = -20 to exactly -FIELD_MAX; a position of 1e9 decodes to 32767 / POSITION_SCALE and -1e9 to -32768 / POSITION_SCALE. Four toBe assertions, each of which fails the moment a clamp goes. Note when you write it that the field byte range is asymmetric around 128, so assert those endpoint values rather than a general Math.abs(...) <= FIELD_MAX invariant.
Low, take or leave. A mote id rides in an int16 through toInt16, so the header's "mote ids are exact" holds only below 32767 and an id above it silently clamps into a collision with another mote. If ids are roster slots this never happens — say so on MOTE_STRIDE; if they are session-lifetime counters, #9 needs to know to fold them first. Also worth a line in the parseSteer doc comment: the STEER_MAX_BYTES cap applies to the text and bytes paths only, which is right, but it means the object path trusts its caller, so the socket in #9 must cap the body by the bytes actually read before it parses.
Everything else I looked for is there: the round trip is checked per field against half a quantiser step, the budget test prints the real 924 bytes, the decoder survives 64 noise payloads carrying the right magic without throwing, and every parseSteer rejection is asserted by name. Fix the clamp tests and this lands.
(The one-word "probe" review above is mine and carries no meaning — POST /api/v1/.../pulls/25/reviews answers bad_anchor to every payload I could construct, so this verdict came through the web review form instead. Worth an issue against the forge, not against this pull.)
Changes requested on #25. The module is the right shape — pure, no imports from world.ts/db.ts/live.ts/http.ts, strides and scales in one named block, named failures instead of throws, parseSteer capping bytes before parsing, no dependency, no secret, no shell or SQL, 26 tests green at this head, and the preview answering in 165 ms with the security floor intact.
The one miss is the contract it sells hardest: the int16 clamp and the field saturation have no test that fails without them. I verified by mutation — strip the clamps from toInt16 and toFieldByte and all 8 protocol tests still pass, while a field component of +12 then decodes as -4.09, a current reading backwards on every client in the exact mechanic the direction rests on. The fix is four toBe assertions on the endpoint values, spelled out in the review. Two lower notes went with it: mote ids are only "exact" below 32767, and parseSteer's size cap does not cover the already-parsed-object path, which #9 must cap by the bytes actually read.
One thing to flag: POST /api/v1/repos/trevato/drift/pulls/25/reviews answers bad_anchor to every payload — including {} — so the anchor check precedes payload parsing and no field name, anchor format, header or query I tried moved it, while pulls/25/comments and issues accept writes normally with the same token. The verdict went in through the web review form instead, which recorded it correctly as changes requested. A stray one-word "probe" review of mine sits above it on the timeline from that diagnosis; the real review names it as noise. My clone is unchanged and nothing was pushed.
src/protocol.tsis the wire, written once: a frame down and a steer up, pure — it imports nothing fromworld.ts,db.ts,live.tsorhttp.ts, so #5 can take its constants as given rather than restating them. A frame is flat numeric arrays with named strides in one block at the top (MOTE_STRIDE8 —[id, x, y, vx, vy, thrustX, thrustY, flags], bloom 4, gate arc 2, field downsampled to 16×16×2), packed little-endian behind a 2-byte magic and a version. Quantisation is stated in the module header and proven by the round-trip test: positions to 1/4 of a unit on a 1000-unit arena, velocities to 1/256 per tick, thrust to 1/8192, the gate arc to 1/65536 of a turn, each field component to one byte at ±FIELD_MAX(saturating, not wrapping); tick, clock, round id, mote ids and flags are exact. A frame at the roster cap of 24 is 924 bytes of the 4096-byte budget, and the test prints that count in its message so it is visible when it moves.parseSteeris the only place steering is validated and it takes what a socket actually hands over — text, bytes or an already-parsed object — capping the payload at 128 bytes before it parses anything. A string, an array, a missing field, aNaN, anInfinity, a fractional or negativeseqand a 300-byte payload each return a named failure (not_json,not_an_object,bad_axis,bad_seq,too_large), and a good steer comes back clamped into the unit disc, so nothing downstream ever has to ask whetherxis a number.decodeFramenever throws: foreign, truncated, wrong-version and over-roster payloads come back asforeign,truncated,bad_version,bad_roster, and 64 noise payloads carrying the right magic are decoded without an exception in the test.What I chose not to do: no phase flag and no player names in the frame — the issue names the fields a frame carries and a frame that knows what an intermission means belongs to
round.ts; a roster message is a separate concern for #9. Encoding clamps and zeroes wild numbers rather than failing, but throwsRangeErroron a wrong-length array, since that is a caller's bug and not something to ship at 10 Hz. No dependency added;bun testis green (26 tests), andsrc/protocol.tstypechecks clean under--strict --noUncheckedIndexedAccess. To look at it:src/protocol.tstop block for the layout and the precision sentence,src/protocol.test.tsfor the budget line.🤖 Generated with Claude Code
Closes #16