readme: two wire formats, one value surface #86

Merged

yuris merged 2 commits from bsatn-phase5-docs into main

2026-08-21 07:59:18 +00:00

yuris commented

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

Owner

Phase 5 of #9. Stacked on #85. One paragraph.

The wiki carries the rest: Protocol-Notes gained the frame envelope, the message map, the pinned capture answers and the byte/latency tables; Usage-Guide documents the option and the four divergences; API-Reference lists the new surface.

Verified: 10 passed, 0 failed; stylua --check stdb dev/test clean.

Phase 5 of #9. Stacked on #85. One paragraph. The wiki carries the rest: Protocol-Notes gained the frame envelope, the message map, the pinned capture answers and the byte/latency tables; Usage-Guide documents the option and the four divergences; API-Reference lists the new surface. **Verified:** 10 passed, 0 failed; `stylua --check stdb dev/test` clean.

yuris added 1 commit

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

readme: two wire formats, one value surface

ci / ci (pull_request) Successful in 1m27s

Details

4c5ed948f2

v1 JSON stays the default; connect({ protocol = "v2" }) is the only
route to event tables and separated reducer results. Rows decode to the
same Lua values either way.

yuris force-pushed bsatn-phase5-docs from 4c5ed948f2

ci / ci (pull_request) Successful in 1m27s

Details

to 0e6b65a037

ci / ci (pull_request) Successful in 1m29s

Details

2026-08-21 06:39:13 +00:00

Compare

yuris commented

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

Author

Owner

Review round: two factual errors in the prose, corrected

Both were statements a reader would have reasonably trusted and acted on.

What v2 separates was inverted. The paragraph had it backwards. Your own reducer result and
its transaction arrive in one frame; what v2 drops is the caller's reducer_call from
broadcasts to other clients. As written, it described roughly the opposite of the wire.
"The option changes nothing a consumer reads" is false. It changes at least five things, and a
consumer switching protocols on the strength of that sentence would have been surprised by every one
of them: ret_value (raw BSATN on v2), reducer_call (absent from broadcasts), one-off query rows,
on_out_of_energy (no OutOfEnergy outcome on v2 — it arrives as InternalError text), and
light (v1-only; the v2 schema has no light mode).

The published benchmark figures this PR documents were also corrected, in #9 and on the wiki:

Benchmark correction (applies to the numbers this stack published): the 10k apply-latency pair of
20.0ms / 10.5ms and its ratio of 0.53 were measured with the machine's load unrecorded. A re-run of the
same commit measured every native absolute 2-3x higher (v1 median 61.7ms, v2 44.6ms over 5 runs) at
loadavg 11.06 on 16 cores, with the harness flagging 47% spread on two sweeps, and put the ratio at
0.59-0.65, not 0.53. Direction holds, the value does not — #9 and the wiki now state the conditions
instead of the bare digits, and a clean re-measure is an open follow-up. The wire-byte tables are
unaffected and stand as published (v2 ~46% of v1 on row payloads, 31% on client frames): they are byte
counts, not timings.

The wiki's Bytes and latency section now states the machine, the sample size and the observed spread
alongside the figures, so a future reader can tell a real regression from a noisy box — the ambiguity
that caused this correction in the first place. The structural claims are kept and now stated as
structural, since they are load-independent and reproduced: the HTML5 pre bucket collapses from the
frame's largest share on v1 to a non-dominant one on v2, and the big-integer quoting bucket is
structurally absent on v2 — that scan exists only because JSON cannot carry a u128 exactly — now
enforced by a zero-ATTEMPTS assertion rather than merely observed to be zero.

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: two factual errors in the prose, corrected Both were statements a reader would have reasonably trusted and acted on. - **What v2 separates was inverted.** The paragraph had it backwards. Your **own** reducer result and its transaction arrive in **one** frame; what v2 drops is the **caller's `reducer_call` from broadcasts** to other clients. As written, it described roughly the opposite of the wire. - **"The option changes nothing a consumer reads" is false.** It changes at least five things, and a consumer switching protocols on the strength of that sentence would have been surprised by every one of them: `ret_value` (raw BSATN on v2), `reducer_call` (absent from broadcasts), one-off query rows, `on_out_of_energy` (no `OutOfEnergy` outcome on v2 — it arrives as `InternalError` text), and `light` (v1-only; the v2 schema has no light mode). The published benchmark figures this PR documents were also corrected, in #9 and on the wiki: **Benchmark correction** (applies to the numbers this stack published): the 10k apply-latency pair of 20.0ms / 10.5ms and its ratio of 0.53 were measured with the machine's load unrecorded. A re-run of the same commit measured every native absolute 2-3x higher (v1 median 61.7ms, v2 44.6ms over 5 runs) at `loadavg` 11.06 on 16 cores, with the harness flagging 47% spread on two sweeps, and put the ratio at **0.59-0.65, not 0.53**. Direction holds, the value does not — #9 and the wiki now state the conditions instead of the bare digits, and a clean re-measure is an open follow-up. The **wire-byte tables are unaffected** and stand as published (v2 ~46% of v1 on row payloads, 31% on client frames): they are byte counts, not timings. The wiki's *Bytes and latency* section now states the machine, the sample size and the observed spread alongside the figures, so a future reader can tell a real regression from a noisy box — the ambiguity that caused this correction in the first place. The structural claims are kept and now stated *as* structural, since they are load-independent and reproduced: the HTML5 `pre` bucket collapses from the frame's largest share on v1 to a non-dominant one on v2, and the big-integer quoting bucket is **structurally absent** on v2 — that scan exists only because JSON cannot carry a `u128` exactly — now enforced by a **zero-ATTEMPTS assertion** rather than merely observed to be zero. **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 force-pushed bsatn-phase5-docs from 0e6b65a037

ci / ci (pull_request) Successful in 1m29s

Details

to bcad829ee1

ci / ci (pull_request) Has been cancelled

Details

2026-08-21 07:56:24 +00:00

Compare

yuris changed target branch from bsatn-phase4-conformance to main

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

yuris force-pushed bsatn-phase5-docs from bcad829ee1

ci / ci (pull_request) Has been cancelled