oficina / docs Public

Plan 1: the Rust core runs under wazero, wire-compatible with browser Yjs

A Rust y-crdt crate compiles to plain wasm32-unknown-unknown with a C ABI
and zero imports, runs under wazero inside a cgo-free Go binary with no
JavaScript host anywhere, and stays byte-compatible with browser yjs in
both directions including formatting. The branch was allowed to conclude
the architecture was wrong. It does not.

Seven tasks: the Rust crate; a Node fixture generator using real yjs; both
compatibility directions with the fixtures as a contract; the C ABI; the
Go wazero host; and .amadan/ci.d/10-gate. Plus the spec commits recording
what execution discovered.

What the design did not anticipate:

yrs calls std::str::from_utf8_unchecked on wire data (read.rs:137). A
mutation fuzz hit it on 0.4-5.1% of single-byte corruptions of our own
fixtures -- random bytes are harmless, which is why a naive garbage-input
test proves nothing. Not fixable from our layer; contained by the
per-document wasm instance, and still to file upstream. That makes the
sandbox load-bearing for security rather than only portability: inside
wasm the fault is a contained trap where a native build corrupts silently.

But the containment claim needed correcting, and the branch's own tests
said so: some corrupted updates are silently ACCEPTED, so downstream must
not assume document text is valid UTF-8.

And a 36-byte corrupted fixture ran apply for 163 real seconds and
returned the correct answer -- denial of service invisible to any
correctness test. The host now caps execution at 1s; the original 5s never
fired for the input it was added for.

This is falsification-grade, not production-grade, and says so. ABI v1 has
no state export, so trap recovery is capped log replay rather than
snapshot restore, and the 4096-update cap would make a longer-lived
document unloadable. Blocking before internal/core gets a real caller.

Every gate here started out checking something adjacent to its purpose and
was corrected: the zero-imports test passed by skipping, the trap test
passed against a host that never discarded, the containment fuzz checked
liveness while discarding the bytes it compared. A check that reports
success without checking is the most repeated finding of this work.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011F5CivVm4CmL9ByfSSAaXA