Sync Engine — Flow Atlas

Structured canvas edits are absolute-value writes (move, resize, recolor) where "last writer wins per field, in server commit order" is the behavior we actually want. A CRDT's merge semantics buy nothing there, and the current Yjs path gave us silent divergence classes, a 673 ms load stall on big canvases, and no server-side source of truth to reason about. Text keeps Yjs because character-level concurrent editing is exactly what CRDTs are for.

No. The design went through five review revisions (an adversarial audit, three review/grill rounds, a code-grounded verification pass). Every open question was ruled and recorded as binding decisions R1–R35 in spike/hld/decision-record.md. Deliberate gaps are tracked in named-not-built.md with explicit triggers for when to build them.

The unit a cursor and counter attach to. v1 has two live tiers: canvas:{id} (objects) and workspace:{id} (assets only — R32). An org tier is type-admitted but not opened in v1. Each scope has its own gap-free server counter and its own client cursor.

The payload is extremely repetitive (uuids, enums, bbox tuples) so brotli crushes ~1 MB to ~250 KB — a sub-100 ms transfer. Paging increases total bytes (per-request overhead, N round-trips). The real historical stall was never the fetch: it was constructing the WASM R-tree synchronously on the main thread (the 673 ms class). That's fixed client-side by chunking the insert across idle/rAF frames, viewport first. Camera-ordered server paging exists as a deferral (#6) if first-paint still misses on the 7k-artboard canvas.

Two guards. Live SSE + /since run during the fill, so the delete arrives as a normal envelope. And because a delete can arrive for a row the tab hasn't loaded yet, the engine materializes a tombstone entry in base (R28) so a stale in-flight hydrate of that row loses the per-row syncId comparison and can't resurrect a ghost.

No. assetRef.storage on the row is render-authoritative — the renderer builds the CDN URL straight from it. The asset record (name, status, provenance) syncs in parallel through the workspace collection, entirely off the paint path.

That's a named bet with a measured gate, not a hope: benchmark gate C fails the design if the pool exceeds ~150 MB V8 heap at 22k items on a low-end phone, and gate D fails it if any frame exceeds 16.6 ms during skeleton construction. The fallbacks are pre-chosen: app-level LRU eviction (#5) and camera-ordered paging (#6). No number, no debate.

A flat viewport-intersection scan over the skeleton bboxes — in-view ids to the head of the queue, the rest in document order. The queue only orders, never drops: everything eventually loads. A pan mid-fill re-sorts only the remaining queue. No priority-queue or second R-tree structure — a 7k-bbox scan is sub-millisecond (#9 if that ever janks).

The skeleton is durable in IDB. Freshness is covered by checksum + /since; completeness by the resumed background fill. Re-fetching the tree would buy nothing the /since delta doesn't already deliver.

Two distinct failures, two distinct answers. A missing row (partial data) → a coalesced by-id batch fetch, business as usual. A missing cursor (Safari's 7-day rule and quota eviction are origin-wide, so this is the real signature) → cold bootstrap for that scope, because there's no baseline for /since to diff against. Never a full re-bootstrap for one missing row.

Pending creates would make the local row count legitimately differ from the server's — the comparison would false-positive and cold-reload a user who's just holding offline work. R9 gates it; and per R30 the skipped tick isn't wasted — it drains the outbox instead, which also clears the reason the checksum couldn't run. A stuck entry can't suppress the drift canary forever.

A 60 fps drag would be a write storm for state nobody needs durably — the intent is only real at release. Remote users still see the motion live because the transform rides the awareness channel (same as today's throttled preview, minus the 100 ms structured write that's being deleted). Durable state changes once, at commit.

Nothing bad. The command sits in the outbox until the tab's base cursor passes the receipt's syncId. Any re-POST (this tab or another) hits the receipt keyed (scope, actorId, commandId) and gets the stored response back — the command can never apply twice (§10.3).

Only that command's overlay is dropped. Because rollback is "remove the overlay" rather than "write old values back", a teammate's concurrent same-field edit — which lives in base — shows through instead of being clobbered. The matching undo entry is removed atomically, so undo can never replay a rejected command (phantom-free).

One. The move, the section's new frame, and every sibling's re-anchor travel as a single atomic command (distinct ids, so R3 holds), which is what makes undo restore the whole arrangement at once. Known pre-existing issue: two clients auto-fitting the same section concurrently can LWW-interleave — today's Yjs has the identical bug; the engine neither adds nor fixes it.

Only the editing client (single-writer): it awaits the font load, measures, and commits {text, width, height} as one atomic update. Everyone else reads w/h from the row and never measures — this kills the cross-client measure war between machines with different fonts. A client missing the font may see overflow; accepted.

No. The renderer reads effective = base ⊕ pending ⊕ gesture and your gesture is the top layer, so base changing underneath is invisible until you let go. The recompute is synchronous with the base write (materialize-on-write), so there's not even a one-frame flash.

The gesture overlay was memory-only, so it vanishes — uncommitted work is supposed to vanish. The teammate's x=700 is already in base and the cursor already advanced past it, so nothing is lost and nothing needs re-pulling. Crash-safety falls out of the layering; there's no recovery code for this case.

Suppression creates a hole — a change you've seen but not applied — and then needs four mechanisms to manage it (held cursor, replay buffer, watermark semantics, a drift-check exception). Landing everything means there's never a hole: masking falls out of the existing layer stack and LWW settles the winner. It's also exactly what Yjs today and Linear do, so behavior doesn't change for users.

A sequence's nextval() is non-transactional: command 502 can commit before 501, a client reads to 502, advances its cursor, and 501 is never pulled — silent loss. The counter row's lock is held to commit, so a higher syncId literally cannot become visible before a lower one; a client that has read to N has provably seen everything ≤ N. Gap-freedom is a free bonus (rollback un-increments; a sequence burns the number).

Both miss the receipt lookup, both proceed, and the second one's journal INSERT hits the UNIQUE constraint on (scope, actor_id, command_id) — it catches, re-reads, and returns the first one's stored response. The receipt lookup is the fast path; the UNIQUE is the backstop.

All row work applies in sorted id order (R15), so two commands touching the same rows always lock them in the same sequence. Combined with counter-first, the deadlock rate should be zero by construction — the benchmark suite verifies it rather than tolerating a retry budget. Any residual serialization abort retries server-side and is never surfaced as a client reject.

No — only the moved node (R12). The descendant path rewrite is a server-internal concern for its own ltree queries; the FE holds no paths and derives the subtree from its parentId reverse index, so nothing else needs to re-sync. Stamping descendants would desync FE/BE per-row syncIds and false-positive any future row-hash checksum.

No — there's exactly one audited internal path: a system actor with a synthetic commandId, one counter allocation and one journal envelope per debounced flush. The §10.2 trigger makes bypassing structurally impossible: nothing can write canvas_objects without advancing sync_id.

Either the tab missed a delta (freshness — maxSyncId axis) or holds the wrong row set (completeness — rowCount axis). Both are self-healing: /since first, cold reload if it persists. Crucially every heal also logs to Sentry — the checksum is the canary that tells us whether any divergence class survives in production, so escalating to a per-row hash (#7) is a data-driven decision, not a guess.

That trap is designed out: anything that advances a cursor (/since and /checksum) reads the primary, because the SSE bump fires from the primary and a lagged replica would tell the client "you're caught up" about data it hasn't seen — divergence SSE would never re-signal. Only the heavy bootstrap snapshot may use a replica; the anchor /since pass self-heals its staleness (W15).

The cursor is trusted — /since pulls from it. What's not trusted is the gap: any bump published while the stream was down is gone (SSE has no replay), so the only safe move is to always pull on open. It's cheap when nothing changed (empty response) and correct when everything did.

Bump-only keeps push strictly latency-optional — losing an event can delay you, never diverge you, because /since is the single ordered source. Inline payloads (with gap-checking and pull-repair) are specced as a purely additive deferral (#22), triggered only if measured remote-edit latency is actually felt.

Two-week-old ops replayed as fresh last-writer-wins would silently overwrite everything your teammates did since — stale work masquerading as new intent. Conditional apply (only if the captured preconditions still hold) is specced as a deferral, but the honest default is: drop, tell the user, log it. And the gate is the client's own clock compared against itself, so clock skew can't lock anyone out.

Reconcile re-creates placements for finished slots that have no local row and no tombstone. Tombstones purge at 7 days — beyond that, the record that you deliberately deleted a placement is gone, so reconcile would resurrect work you undid. Aligning the reconcile window with the tombstone window makes that impossible; older tasks are simply settled.

No. Everything that reached the server is in the rows; the cold bootstrap re-downloads it. Only the never-sent outbox tail is affected, and only past 48 hours.

Whichever tab hits one of the four triggers next — or the next session's first tab at instance start. The outbox is durable and commandId-keyed, POSTs are receipt-idempotent, so anyone can safely drain everything. No one needs to know the origin tab died; there is deliberately no liveness detection.

Because holding a Web Lock is not proof of life — a suspended iOS tab keeps its locks while draining nothing, starving the queue — and a held or queued lock blocks bfcache in Chrome. Worse, the outbox has no ownership column, so "drain only your own" was never even definable across sessions. Locks added failure modes and solved nothing receipts didn't already solve.

Yes — redundant, never incorrect, and only when a user actually opens N tabs. The leader (one tab owns the network, others follow over a broadcast bus) is fully designed and parked as deferral #15; it bolts on additively by gating SSE/base-writes on isLeader. It gets built when the measured N-connection cost bites, not before.

Because the cursor means "what my pool has applied." If tab A pulls 501–510 and advances a shared cursor, tab B — which never applied them — would skip that range and render stale forever, invisibly to the checksum. Per-tab in-memory cursors make that impossible; the shared IDB value is only a starting seed, advanced with max().

The undo's update lands on a tombstoned row and is an accepted no-op (R1) — delete wins, and crucially the rest of your multi-object undo command still applies. If instead your undo is undoing a delete, the full-row create on the tombstoned id revives it (R2) — that's intentional forward-LWW, the same spirit as "undo can deliberately win a collision."

No. The undo command carries only the fields the original command touched. A teammate's edit to a different field merges untouched; a teammate's edit to the same field is deliberately overridden — that's the chosen model (no rebase, no operational transforms), and it's recorded as such.

No — it's per-tab, in-memory UX state, trimmed at a max stack size, gone on reload. Persisting it is a named deferral with a trigger ("users demand undo-after-reload"), not an oversight.

The task finishes server-side regardless. When you return (within 7 days), the client fetches the task's durable state and materializes a placement for every finished slot you don't have — reading state, not replaying missed stream events, so a lost chunk can't drop a placement. The reconcile waits until your canvas scope's /since is current, so it never races a delete that was about to arrive.

They see placements as your creates commit and sync — not the in-flight progress (that's on your personal generation stream). Accepted cost, recorded: generation is a personal action; a shared live preview is a named deferral if product ever wants it.

A slot that finishes after your undo-delete may briefly reappear via reconcile, and you delete it again — bounded, rare, self-correcting (and its tombstone then blocks any further resurrection). Auto-clearing that late placement is a named deferral, triggered only if it measurably confuses users.

Downtime removes the split-brain writer race entirely: no old client writing Yjs while a new client writes rows. The dangerous residue isn't the happy path — it's a backgrounded mobile tab that wakes after cutover still running the old build. That's what the protocol-capability handshake exists for: it hard-blocks and force-reloads pre-cutover clients at connect, because a soft "please update" banner provably isn't enough.

Nothing — text was never leaving Yjs. Only the bounded read-only summary is projected onto the row; the docId link and the subdocs are untouched. The riders are infra: per-edit content flush + Redis AOF/no-evict so "undelete restores exact text" actually holds, and a reap cron for purged docs' subdocs.

Yes, and it was verified rather than assumed: the canvas_objects table and its bbox read APIs have zero production callers today (the table is only the debounced Yjs shadow this cutover replaces). Under the relative-geometry model those world-envelope columns would be permanently stale anyway — a container move changes the whole subtree's world positions with zero row writes. Server-side spatial queries, if ever needed, are parked deferrals (#6, #19) with the local geometry retained to build on.