bsatn: a pure-Lua BSATN primitive codec #82

Merged

yuris merged 1 commit from bsatn-phase1-codec into main

2026-08-21 07:57:12 +00:00

yuris commented

2026-08-21 05:46:13 +00:00

Owner

Phase 1 of #9. New module stdb/bsatn.lua plus its unit suite. Nothing else in the SDK requires it yet, so this lands inert.

Pure arithmetic rather than require("bit"): the unit-test host is plain Lua 5.1 with no bit module, and one implementation that runs both there and in Defold beats two that agree by inspection.

Value surface matches what protocol.lua already hands out: u64/i64 on a double (exact to 2^53, rounding above), 128-bit as exact decimal digit strings, 256-bit as minimal-width hex including the -0x8000… case.

Verified: lua dev/test/runner.lua on this branch alone: 9 passed, 0 failed. Float bit patterns were cross-checked against node's Buffer.writeDoubleLE, not against this codec. Two deliberate mutants were injected and both were killed by the suite.

Phase 1 of #9. New module `stdb/bsatn.lua` plus its unit suite. Nothing else in the SDK requires it yet, so this lands inert. Pure arithmetic rather than `require("bit")`: the unit-test host is plain Lua 5.1 with no `bit` module, and one implementation that runs both there and in Defold beats two that agree by inspection. Value surface matches what `protocol.lua` already hands out: u64/i64 on a double (exact to 2^53, rounding above), 128-bit as exact decimal digit strings, 256-bit as minimal-width hex including the `-0x8000…` case. **Verified:** `lua dev/test/runner.lua` on this branch alone: 9 passed, 0 failed. Float bit patterns were cross-checked against node's `Buffer.writeDoubleLE`, not against this codec. Two deliberate mutants were injected and both were killed by the suite.

yuris added 1 commit

2026-08-21 05:46:13 +00:00

bsatn: a pure-Lua BSATN primitive codec

ci / ci (pull_request) Successful in 1m28s

Details

conformance / conformance (pull_request) Successful in 2m46s

Details

5c0d494975

The v2 message schema is served only in BSATN, so speaking it at all
starts with a codec. Pure arithmetic rather than require("bit"): the
unit-test host is plain Lua 5.1 with no bit module, and one
implementation that runs in both places beats two that agree by
inspection.

u64/i64 land on a double, exact to 2^53 and rounding above, which is
the surface the v1 JSON path already documents. 128-bit values become
exact decimal digit strings and 256-bit ones minimal-width hex, both
matching what protocol.lua already hands out.

yuris referenced this pull request

2026-08-21 05:46:13 +00:00

protocol_v2: the v2 message schema over BSATN #83

yuris commented

2026-08-21 06:51:55 +00:00

Author

Owner

Review round: clean, merge as-is

Reviewed for codec correctness and for hostile input. No findings. Nothing in this PR was changed
as a result of the review.

What the review actually exercised, beyond reading:

200,000 random f32/f64 values round-tripped bit-exact through the writer and back through
the reader. This is the check that matters for a hand-rolled IEEE-754 codec built on math.ldexp
and 32-bit bit ops, and it covers the cases a spot-check misses: subnormals, signed zero, the
infinities, and NaN.
20,000 wide-integer values matched an independent renderer — the 128/256-bit decimal-digit and
hex paths checked against a second implementation rather than against themselves, so a shared bug
in the divmod-by-10 loop could not hide.

One note for the reader of this stack, so the diff is not confusing later: this PR's stdb/bsatn.lua
gained two things after it was reviewed, and they landed on #83's branch, not here — a bounded
Reader:len (the fix for the array-count amplification described on #83) and the wide-type writers
needed for wide reducer arguments. Review #83 for both.

Verification state at the stack tip (bsatn-phase5-docs): unit suite 11 passed, 0 failed;
all four conformance suites PASS end to end — v1 native, v2 native, v1 HTML5, v2 HTML5 — under the
new protocol-specific gates, whose negative controls were proven non-vacuous; stylua --check stdb dev/test
clean.

## Review round: clean, merge as-is Reviewed for codec correctness and for hostile input. **No findings.** Nothing in this PR was changed as a result of the review. What the review actually exercised, beyond reading: - **200,000 random `f32`/`f64` values round-tripped bit-exact** through the writer and back through the reader. This is the check that matters for a hand-rolled IEEE-754 codec built on `math.ldexp` and 32-bit bit ops, and it covers the cases a spot-check misses: subnormals, signed zero, the infinities, and NaN. - **20,000 wide-integer values matched an independent renderer** — the 128/256-bit decimal-digit and hex paths checked against a second implementation rather than against themselves, so a shared bug in the divmod-by-10 loop could not hide. One note for the reader of this stack, so the diff is not confusing later: this PR's `stdb/bsatn.lua` gained two things *after* it was reviewed, and they landed on **#83's branch**, not here — a bounded `Reader:len` (the fix for the array-count amplification described on #83) and the wide-type writers needed for wide reducer arguments. Review #83 for both. **Verification state at the stack tip** (`bsatn-phase5-docs`): unit suite **11 passed, 0 failed**; all **four conformance suites PASS** end to end — v1 native, v2 native, v1 HTML5, v2 HTML5 — under the new protocol-specific gates, whose negative controls were proven non-vacuous; `stylua --check stdb dev/test` clean.

yuris referenced this pull request

2026-08-21 06:51:55 +00:00

protocol_v2: the v2 message schema over BSATN #83

yuris merged commit cccfd7a315 into main

2026-08-21 07:57:12 +00:00

yuris deleted branch bsatn-phase1-codec

2026-08-21 07:57:12 +00:00

yuris referenced this pull request from a commit

2026-08-21 07:57:13 +00:00

bsatn: a pure-Lua BSATN primitive codec (#82)

yuris referenced this pull request

2026-08-21 08:00:30 +00:00