Docs correctness pass + property-based tests

[jackyzha0]

Why

A correctness pass over the docs, then property-based tests for the invariants
PROTOCOL.md claims. The docs pass found a set of examples that don't work; the
tests found three real codec bugs and one flaky test.

Four separable commits — happy to split into separate PRs if you'd rather.

What changed

docs: correct README and PROTOCOL — every README TypeScript snippet is now
typechecked against the real source. Things that would fail for someone copying
them: @replit/river/testUtil (the export is ./test-util), comparing against
the string 'CANCEL_CODE' (the value is 'CANCEL'), MockClientTransport (not
exported), handler(ctx, ...args) (handlers take one object), rejecting a
handshake by returning false (you return a fatal code), and a dead link to
__tests__/fixtures/. PROTOCOL.md had drifted: a syntactically broken error
payload, v0/v1 listed as accepted, connectionStatus events that don't
exist, a state diagram missing SessionBackingOff, and a heartbeat section
describing the mechanism #395 replaced. Also documents backpressure,
ctx.deferCleanup, middleware, and ServiceSchema.scaffold.

fix(transport): break require cycles — three modules value-imported across
a cycle, so importing the transport before the router left Transport undefined
and transport/server.ts died with "Class extends value undefined". All three
only needed types or a deep import. Also fixes isStreamOpen/isStreamClose,
which were exported inside an export type { ... } block and so unusable as
values.

test: property tests with hegel — 45 properties, ~7s, catalog in
__tests__/properties/README.md. Covers codec round-trips, stream ordering and
half-close, and delivery under generated fault schedules.

chore: skip .claude worktrees — it holds scratch git worktrees, stale
checkouts of this repo, so npx vitest run was collecting and failing old copies
of these tests and npm run format flagged files in them. CI unaffected.

Codec bugs: two fixed, one not

Fixed — NaiveJsonCodec marker collisions. The codec encodes a Uint8Array
as { $t: <base64> } and a bigint as { $b: <digits> }, which puts those
markers in the same namespace as application data. A payload containing $t
decoded as binary (silent corruption); a payload containing { $b: <non-numeric> }
made fromBuffer throw, and a decode failure tears the connection down — so
ordinary application data could drop a connection on the default codec.

Both are fixed by escaping: a key that could be mistaken for a marker gains an
extra $ on the way out and loses it on the way back in. Marker decoding is now
shape-checked too, rather than just testing whether the key is present. Cost is
~1.6% on a message with no marker keys — the replacer already visits every
property, so this only adds a per-object key scan.

Compatibility: an unescaped { $t: <base64> } from an older peer still decodes
as binary, so nothing that worked before changes. Payloads that were already
broken behave differently against an old peer, hence the minor.

Verified by widening the property generators — $t/$b are now generated
freely and A1 passes across all three codecs.

Not fixed — __proto__ in BinaryCodec/ProtoCodec. They encode the key
and then refuse to decode it. msgpack's check is hardcoded ahead of
mapKeyConverter and it exposes no per-key encode hook, so the only fix is a
second full traversal of every payload on encode — in the codec chosen for
throughput, to defend a key that doesn't appear in real payloads. Left pinned as
a documented limitation.

Perf

Measured with npx vitest bench.

	before	after
adapter decode + validate (server)	143,933 hz	563,915 hz (3.9x)
NaiveJsonCodec encode, 64KB binary	882 µs	75 µs (12x)
NaiveJsonCodec decode, 64KB binary	1378 µs	70 µs (20x)
BinaryCodec encode / decode	—	7% / 5%

Schema validation dominated the receive path: Value.Check re-walks the schema
on every inbound message at 5.18 µs, against ~1.8 µs for the entire
BinaryCodec decode. A compiled validator does it in 0.0055 µs.

Compiling uses new Function, which a strict CSP blocks, so only the server
compiles — the client may be a browser, and it keeps the interpreted path. The
seam is clean: NoConnection is the client entrypoint, WaitingForHandshake
and WaitingForHandshakeToConnected are the server's. Falls back if compiling
throws anyway.

The base64 win is Node's Buffer (browsers get a chunked btoa fallback).
Worth noting BinaryCodec is still ~7x faster on encode and ~76x on decode for
that payload — base64-in-JSON is the wrong tool for binary, as the README says.

The benchmark was measuring fake time

The global setup installs fake timers, which fake performance.now — what
tinybench measures with. Every sample in bandwidth.bench.ts landed on either
0.0000 or exactly 20.0000 ms. The numbers were wrong in magnitude, not just
noisy: rpc reads 12,770 hz on the real clock against 8,112 hz on the
fake one. Fixed, plus benchmark.exclude for .claude (separate from
test.exclude, so vitest bench was running stale worktree copies).

Adds codec.bench.ts so the wins above stay visible and regressions surface.

Known flake — now reproducible

Under CPU load the suite fails this, and only this:

transport connection edge cases ('ws' transport, 'naive'|'binary' codec)
  > messages should not be resent when client reconnects to a different
    instance of the server
AssertionError: expected "spy" to be called 2 times, but got 1 times

Not a timeout — it fails at ~540ms, under the 1s ceiling. It's the shared
waitFor budget in testUtil/fixtures/cleanup.ts: 500ms, while that test
restarts a real WebSocket server and redials it, and retry backoff alone can
take ~350ms before any socket or handshake work.

I had a commit raising that budget and pulled it back out because the evidence
was thin. It's since reproduced 2/6 runs under deliberate load with an
identical signature every time, plus a 7-failure run right after the
benchmarks saturated the machine. That's a good deal firmer than the 1/12 I had
before.

Still not in this PR — say the word and I'll add it back (budget to 2s,
testTimeout to 5s so chained waits can use it).

Versioning

• Breaking protocol change
• Breaking ts/js API change

engines.node moves from >=16 to >=20.11.0. Not a code break, but it will
warn for consumers on older Node. >=16 was already inaccurate — nanoid@5 needs
^18 || >=20 and @msgpack/msgpack@3 needs >=18; 20.11 is hegel's floor.

🤖 Generated with Claude Code

[wiz-a44d115bc1]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	1
Software Management Findings	-
Total	1

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

[masad-frost]

property-based-based testing