feat(collab): the hub is the only writer while a room is live

[ssowonny]

TL;DR

• Every co-editor used to write the file themselves, 700 ms after their own last keystroke — N writers racing for one file. Every lost race parked someone's text as a "conflict copy" of the file against itself. Two rounds of client-side retry (fix(editor): a save refused for a stale base is retried, not parked #257, fix(editor): a save the file has already moved past is dropped, not parked #258) didn't stop it, because the race is between reading the base and the write arriving.
• Now nobody in a live room writes. The hub holds the document, sees every update, and writes once per pause (2 s idle / 10 s max — Hocuspocus's numbers).
• Co-editor save conflicts become structurally impossible, not retried. An If-Match refusal can now only mean someone outside the room wrote.
• Stacked on fix(collab): two files open in one browser no longer mix #259; retargets to main when that merges.
• Every gate verified in both directions on the final tree: 7/7 e2e, room-writer Go suite race-clean.

Why the previous fixes couldn't finish the job

#257 handled "ours ⊇ theirs" and #258 handled "theirs ⊇ ours" — both correct, both still racing. The window is between the client reading its base sha and its PUT arriving, and no care about when a peer's sha is adopted can close a window that's already open. Fixing the race meant removing the racers.

This was in the PRD as Stage 4 ("the client defers the write to the hub entirely… a periodic snapshot while a room is live"). I ticked those boxes and implemented only the local-edits half. This PR is the other half.

What the hub does now

crdt.Doc.OnUpdate (ygo already exposes it) arms a per-room timer: 2 s after the last change, never later than 10 s after the first. OnUpdate returns immediately — nothing on it may block or re-enter the doc — so it only arms the timer; the write runs on the timer's goroutine. Subscribing happens after seeding, so the bytes a room was built from are never mistaken for an edit to write back.

An outside writer is never silently overwritten. With one writer, a 409 can't be a co-editor — everyone in the room shares this document. It can only be an agent, the CLI, or a device. Their write stays the file; the room's version is parked beside it under the sync path's conflict name, attributed to the human who was editing; then the room rebases so it isn't refused for the same stale base forever. Nothing lost on either side. Folding the outside write into the live document is the better answer and is the hub's to give (it's the one place the splice could be made exactly once) — filed, not done.

What the client does now

Once the room reports live, it never arms its save timer again — including on destroy, where a parting write would be one more racer. dirty clears honestly: when the hub's write comes back through the change stream and merge() finds the file equal to the document. A client that never reaches live is solo and saves exactly as before.

Tests

Server (ycollab_writer_test.go), each seen to fail with its mechanism removed:

test	removed → fails
writes itself after a pause	watchRoom no-op
writes by the deadline while typing never pauses	watchRoom no-op
parks its version when someone outside wrote	no If-Match → "snapshot overwrote an outside write"
seeding a room is not a write	—
dropped room does not write	—

e2e — in a live room no client writes the file, and the file still updates: old client bundle fails with exactly "clients in a live room wrote the file themselves: A"; new one passes.

#257/#258's forced-409 tests were rightly broken by this — they failed on their own "409 was never delivered" guard, because a live-room client no longer saves. They now run in solo mode (routeWebSocket refuses the upgrade; the editor falls back after UNREACHABLE_MS), which is the case the retry was kept for. Both re-verified: with the retry removed, each still fails on the conflict copy it guards.

One rebase artefact worth knowing

The union merge of #258's spec and mine left #258's test body unclosed — its final expect ran straight into my test's header comment, so one function swallowed the other and the spec didn't parse. tsc never sees e2e/, so it passed the typecheck; Playwright caught it. Fixed in the second commit.

What this doesn't do

The room is single-instance state; two hub instances would hold two documents per file. That's Stage 11, still blocked as recorded in the PRD — nothing here moves the instance cap.

🤖 Generated with Claude Code