basen/base128: name the varint continuation-bit layout - #1612

Implements fjs/basen/base128/todo/continuation-bit-layout.md (deleted here).

The problem

encode and decode in fjs/basen/base128/module.f.mjs are exact inverses, but each spelled the varint layout with its own literals and nothing tied them together:

• encode: uint & 0x7fn, 0x80n | item, uint >>= 7n
• decode: (result << 7n) | (byte & 0x7fn), if (byte < 0x80n)

Three separate facts — payload width, payload mask, continuation flag — appear twice each, in two different notations. A reader has to match 0x7f on one side against 0x7f on the other and confirm by hand that 0x80 is the bit just above the 7-bit payload.

The change

Name the layout once and route both halves through it:

const payloadBits = 7n
const payloadMask = mask(payloadBits)
const continuationFlag = 1n << payloadBits

Deviation from the TODO

The TODO proposed literal constants (payloadMask = 0x7fn, continuationFlag = 0x80n). I derived them from payloadBits instead, via mask from types/bigint and a shift. That makes the relationship between the three structural rather than a coincidence of literals that still has to be checked by eye — which is the whole point of the TODO. Verified the derivations evaluate as expected: mask(7n) === 0x7fn, 1n << 7n === 0x80n.

One further change beyond a pure rename: decode's if (byte < 0x80n) became if ((byte & continuationFlag) === 0n). These are equivalent because pop8 = popFront(8n) yields exactly 8 bits, so byte < 0x80n and "bit 7 clear" are the same test. The mask form is what makes the two halves visibly agree.

I also added a short comment on encode's result === empty ? 0n : continuationFlag, since "the first byte built is the last one emitted" is the non-obvious part of that line.

Verification

• npx tsc — clean.
• node fjs/module.mjs test — 2914 pass, 0 fail.
• npm run cov — 100.00% lines / branches / functions, all files.
• Differential against main: 741 values — every 1n << k minus one, 1n << k, and 1n << k plus one for k in 0..80, plus 500 pseudo-random 96-bit values — recording encoded length, encoded bits, decoded value and remainder length for each, plus 4 cases decoding a vector with a trailing byte to check the remainder is handed back. Both sides ran to completion (745 rows of real hex data on each) and the outputs are byte-identical.

The differential harness itself failed to load on its first run (it imported a concat that bit_vec does not export at top level — it lives under msb). Worth stating because a harness that crashes identically on both sides compares two identical stack traces and reports a false match; here it was a hard SyntaxError at import, so it could not have silently passed. Fixed, then re-run; the numbers above are from the working version.

Changelog

• basen/base128: the varint continuation-bit layout is named once and shared
  by encode and decode instead of being spelled with literals in each

No public API change — the three constants are module-private, and encode/decode keep their signatures and behavior.

Generated by Claude Code