Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.
TypeScript adhdagent-orchestrationai-agentscanvasclaude-codecodexcoding-agentsdeveloper-toolselectrongeminilinuxmacosmultiplexeropencodeparallel-agentsterminalterminal-emulatorterminal-multiplexertmuxworkspace-manager
fix(team): a delete beats a concurrent drag frame — causally, not by a tiebreak
enes9a52d24fc0f0
diff --git a/docs/team-presence.md b/docs/team-presence.mdindex f972d1669..3c73d2406 100644--- a/docs/team-presence.md+++ b/docs/team-presence.md@@ -658,26 +658,43 @@ concurrently with a peer's delete.**Does NOT converge — named, not hidden:**-- **Array order after a resurrection.** If a delete *loses* the order race, the client that issued it- removed the node and then re-appended it, so it can sit in a different **slot** in the array than- on a client that never removed it. Node set, positions, sizes and data all agree; only the array- order (which drives the sidebar listing) can differ, and the next load normalizes it.+- **Array order after a resurrection.** If a node is deleted and then legitimately re-created, the+ client that issued the delete removed it and re-appended it, so it can sit in a different **slot**+ in the array than on a client that never removed it. Node set, positions, sizes and data all agree;+ only the array order (which drives the sidebar listing) can differ, and the next load normalizes it.- **Intent, on a contended node.** Two people dragging the same node fight: the node lands whereverthe last-ordered frame put it. Two people typing a title get one title. That is last-write-wins,not a merge — by design (no CRDT).-- **A delete that loses to a concurrent edit — and the node comes back with a DEAD TERMINAL.** If A- deletes a node while B is mid-drag, and B's next frame is ordered after A's remove, the node- **survives on both canvases** — the last write wins, and it happened to be an upsert. But A's- `transport.destroy` had already run `tmux kill-session`, and nothing resurrects a killed session:- the node that comes back is a **shell around a dead terminal**. Its scrollback and its running- process are gone; the next time it is opened, `pty.create` starts a **fresh** session under the same- `nt-<nodeId>` (a cold start: scrollback replay finds nothing, an agent node re-launches its CLI).- The canvas is *consistent* everywhere (no split-brain save, which was the whole point) — the node- content is not. Deleting a node someone else is actively dragging is a race between two humans;- nodeterm resolves the canvas, it cannot un-kill a process. A "delete always wins" tiebreak would- trade this for the opposite hazard (a stale drag frame from a disconnected peer erasing a node that- was legitimately re-created), so v1 leaves the total order in charge and names the wart here.-- **Anything outside the node vocabulary** — edges, project lifecycle (see item 5 above).+- **Anything outside the node/edge vocabulary** — project lifecycle (see item 5 above).++### A delete beats a concurrent edit — CAUSALLY, not by a tiebreak (rule 4)++This used to be in the list above, as a named wart: A deletes a node while B is mid-drag, B's next+frame is ordered after A's remove, so the node **survived on every canvas** — but A's+`transport.destroy` had already run `tmux kill-session`, so what came back was a **shell around a+dead terminal**. Consistent, and nobody had asked for that node back.++The fix is not the "delete always wins" tiebreak this document previously rejected — that one buys+the opposite hazard, a stale drag frame from a disconnected peer erasing a node that was+legitimately re-created. The missing fact was **causality**, so every mutation now carries `seen`:+the highest `seq` its sender had applied when it cast. The rule is exact, with no timer:++> an upsert for a removed node is dropped **iff** `seen < the seq the remove was ordered at`.++B's drag frame was produced in ignorance of the delete and dies everywhere; a re-creation (⌘Z on+the delete, the node added again) necessarily carries `seen` at or past it and lands. Its mirror on+the receiving side: **a `remove` is never held off by rule 2's suppression** — rule 2 rests on "our+unacked mutation wins everywhere", which under rule 4 it no longer does, so suppressing the remove+would be the one way to disagree with our peers.++`seen` is client-supplied and it *decides* something, so the reflector **bounds** it+(`stampMutation`): it can never legitimately reach the order the mutation is being given, so it is+clamped there, and a non-integer/negative one is dropped. A mutation with **no** `seen` (an older+peer, the relay mirror) is judged exactly as before rule 4 existed — degrade, never break.++What this does **not** do: un-kill the process. If the delete wins, the terminal is gone, which is+what the human asked for. If the node is deliberately re-created later, it is still a fresh session+under the same `nt-<nodeId>` (a cold start).## Non-goals (v1)@@ -916,10 +933,10 @@ logged in, named, and on the **same project**.- **Weak identity** — anyone can claim any name.- **Concurrent typing garbles input** — accepted; the badge is the warning.- **Cross-user undo** — last-write-wins, no CRDT.-- **Per-node last-write-wins is a resolution, not an arbitration.** Clients always converge, but a- delete can lose to a concurrent drag frame (the node survives everywhere, with a dead session), and- two people dragging one node fight over it. Named in full under- [Concurrent-edit resolution](#concurrent-edit-resolution-what-converges-and-what-does-not).+- **Per-node last-write-wins is a resolution, not an arbitration.** Clients always converge, but two+ people dragging one node fight over it and the last-ordered frame decides. (A delete no longer+ loses that race — see rule 4 under+ [Concurrent-edit resolution](#concurrent-edit-resolution-what-converges-and-what-does-not).)- **A peer's edge (context link / note link) is deleted by your next save.** Edges are not synced butthey *are* persisted, in the same whole-file write. See item 5 of[What Stage 3 changed](#what-stage-3-changed-relative-to-this-spec).diff --git a/src/core/canvas-sync.convergence.test.ts b/src/core/canvas-sync.convergence.test.tsindex 466e3fa96..40ab29bf9 100644--- a/src/core/canvas-sync.convergence.test.ts+++ b/src/core/canvas-sync.convergence.test.ts@@ -167,12 +167,15 @@ class Client {// pending entry or casting. A refusal means nothing was cast — so nothing is pending (the// node stays open to its peers) and the publisher keeps the node in its baseline and// retries it on the next publish. Canvas also surfaces the refusal to the user.- if (!isCanvasMutation(m)) {+ // Stamp our causal position FIRST, so the guard judges the exact payload that is cast+ // (canvas-order rule 4 — `seen` is what lets a delete beat a concurrent drag frame).+ const stamped = this.order.stamp(m)+ if (!isCanvasMutation(stamped)) {this.refused++return false}- this.order.onLocal(m)- bus.cast(id, PROJECT, m)+ this.order.onLocal(stamped)+ bus.cast(id, PROJECT, stamped)return true},{ src }@@ -287,7 +290,12 @@ describe('canvas convergence (async bus)', () => {// The bug Stage 3 exists to kill, in its sharpest form: A deletes a node while B is dragging it.// Divergence here is not cosmetic — A's next whole-file workspace.save would write the node// straight back over B's canvas (or vice versa).- it('concurrent delete vs move of the same node converges (no split-brain save)', () => {+ //+ // RULE 4 also decides WHICH way it converges. Plain last-write-wins let B's next drag frame — a+ // frame produced in ignorance of the delete — win the order and keep the node ALIVE on every+ // canvas, as a shell around a tmux session A's `kill-session` had already killed. `seen` says B+ // had not yet applied the remove, so the frame is dropped everywhere and the delete stands.+ it('concurrent delete vs move of the same node converges — on DELETED', () => {a.edit([node('n1', 0), node('n2', 0)])bus.settle()@@ -295,14 +303,45 @@ describe('canvas convergence (async bus)', () => {b.edit(b.states.map((n) => (n.id === 'n1' ? node('n1', 50) : n))) // …while B drags itbus.settle()- // Whatever the total order decided, BOTH clients agree — that is the save-safety property.- // Here A's remove was ordered first, so B's later drag frame wins and the node survives on both- // (an honest last-write-wins outcome; see docs/team-presence.md). What can no longer happen is- // A holding the node while B does not — the split-brain that made A's save resurrect it on disk.+ expect(a.ids()).toEqual(b.ids()) // the save-safety property, unchanged+ expect(a.ids()).toEqual(['n2']) // …and the node nobody asked back stays gone+ expect(canon(a)).toEqual(canon(b))+ expect(a.persisted()).toEqual(b.persisted())+ })++ // The other half of rule 4, and the reason it is not a blunt "delete always wins": an upsert cast+ // AFTER the client applied the delete is a deliberate re-creation (⌘Z on the delete, or the node+ // being added again) and must land. Without the causal test, a bounded "delete wins" window would+ // silently eat it.+ it('a node re-created AFTER the delete landed is not eaten by the delete', () => {+ a.edit([node('n1', 0), node('n2', 0)])+ bus.settle()++ a.edit(a.states.filter((n) => n.id !== 'n1')) // A deletes n1+ bus.settle() // …and everyone has applied it+ b.edit([...b.states, node('n1', 7)]) // B adds it back, knowing it was deleted+ bus.settle()++ expect(a.ids()).toEqual(b.ids())+ expect(a.ids()).toContain('n1')+ expect(a.x('n1')).toBe(7)+ expect(a.persisted()).toEqual(b.persisted())+ })++ // A stale frame from a client whose socket was stalled must not resurrect the node either — this+ // is the "disconnected peer erases / revives what everyone else settled" hazard, and it is the one+ // a TIME-based delete-wins window would get wrong (the frame arrives long after any window).+ it('a very late drag frame from a stalled client cannot revive the deleted node', () => {+ a.edit([node('n1', 0), node('n2', 0)])+ bus.settle()++ b.edit(b.states.map((n) => (n.id === 'n1' ? node('n1', 50) : n))) // B's frame is cast…+ a.edit(a.states.filter((n) => n.id !== 'n1')) // …A deletes n1+ clock += 60_000 // …and B's cast sits on a stalled link for a minute+ bus.settle()+expect(a.ids()).toEqual(b.ids())- expect(a.ids()).toEqual(['n1', 'n2'])- expect(canon(a)).toEqual(canon(b)) // same node set, same values (A re-appended n1: see `canon`)- expect(a.x('n1')).toBe(50) // B's drag frame is the last write+ expect(a.ids()).toEqual(['n2'])})it('delete wins when it is the later write, and stays deleted on both', () => {diff --git a/src/core/canvas-sync.test.ts b/src/core/canvas-sync.test.tsindex 7c472109f..6ffbdcf60 100644--- a/src/core/canvas-sync.test.ts+++ b/src/core/canvas-sync.test.ts@@ -100,6 +100,28 @@ describe('stampMutation', () => {stampMutation({ op: 'remove', id: 'n1', src: 42 as unknown as string }, 1).src).toBeUndefined()})++ // `seen` (canvas-order rule 4) is the one client-supplied field that DECIDES something: an upsert+ // claiming to have seen a node's delete is applied over it. A forged one resurrects a node a+ // teammate deleted — on every canvas. It can never legitimately reach the order it is being given.+ it('passes an honest `seen` through untouched', () => {+ expect(stampMutation({ op: 'upsert', node: node('n1'), seen: 6 }, 9).seen).toBe(6)+ expect(stampMutation({ op: 'upsert', node: node('n1'), seen: 0 }, 1).seen).toBe(0)+ })++ it('clamps a forged `seen` to just below the order it is being given', () => {+ expect(stampMutation({ op: 'upsert', node: node('n1'), seen: 999_999 }, 9).seen).toBe(8)+ expect(stampMutation({ op: 'upsert', node: node('n1'), seen: 9 }, 9).seen).toBe(8)+ })++ it('drops a non-integer / negative `seen` — degrading to unstamped, never to outranking a delete', () => {+ for (const bad of [-1, 1.5, NaN, Infinity, '5', null]) {+ expect(+ stampMutation({ op: 'upsert', node: node('n1'), seen: bad as unknown as number }, 4).seen+ ).toBeUndefined()+ }+ expect(stampMutation({ op: 'upsert', node: node('n1') }, 4).seen).toBeUndefined()+ })})describe('isCanvasMutation', () => {diff --git a/src/core/canvas-sync.ts b/src/core/canvas-sync.tsindex 61b4d388c..445f8e492 100644--- a/src/core/canvas-sync.ts+++ b/src/core/canvas-sync.ts@@ -61,14 +61,27 @@ export function reflectTargets(all: ClientId[], _sender: ClientId): ClientId[] {}/**- * Stamp a client's mutation with its place in the total order, and BOUND the client-supplied `src`- * tag (it is echoed to every peer, and a client could otherwise plant a megabyte there — or forge+ * Stamp a client's mutation with its place in the total order, and BOUND the two client-supplied+ * fields it carries. Pure — exported for the test.+ *+ * `src` is echoed to every peer, and a client could otherwise plant a megabyte there — or forge* another client's tag, which would only ever make that client ignore an edit meant for it, but is- * still not something to reflect unchecked). Pure — exported for the test.+ * still not something to reflect unchecked.+ *+ * `seen` is the sender's causal position (canvas-order rule 4), and it is the one client-supplied+ * value that DECIDES something: an upsert claiming to have seen a node's delete is applied over it.+ * A forged one is therefore a way to resurrect a node a teammate deleted. It cannot legitimately+ * reach the order this mutation is being GIVEN (the sender can only have seen `seq`s already+ * assigned), so clamp it there — an honest client is never touched, and a liar buys itself nothing+ * beyond the moment it actually cast. A non-integer / negative value is dropped, which degrades to+ * "unstamped" (judged exactly as before rule 4 existed), never to a value that outranks a delete.*/export function stampMutation(m: CanvasMutation, seq: number): CanvasMutation {const stamped: CanvasMutation = { ...m, seq }if (!isRefId(stamped.src)) delete stamped.src+ const seen = stamped.seen+ if (typeof seen !== 'number' || !Number.isInteger(seen) || seen < 0) delete stamped.seen+ else if (seen >= seq) stamped.seen = seq - 1return stamped}diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsxindex e98a12127..bfcd037f5 100644--- a/src/renderer/canvas/Canvas.tsx+++ b/src/renderer/canvas/Canvas.tsx@@ -3646,6 +3646,11 @@ export function Canvas() {(m) => {const projectId = useProjects.getState().activeProjectIdif (!projectId) return false // no active canvas: nothing was cast — retry on the next publish+ // Stamp our causal position FIRST (canvas-order rule 4: what we had applied when we cast —+ // it is what lets a teammate's delete beat this frame instead of being resurrected by it),+ // so the size guard below judges the EXACT payload that goes on the wire. `stamp` is pure:+ // a refusal still records no pending entry.+ const stamped = order.stamp(m)// The reflector REFUSES an oversized / malformed mutation at ingest, silently: no peer ever// sees it and there is no negative ack. Ask the same predicate FIRST, so a refusal costs us// neither a pending entry (which would deafen this node to its peers for the whole TTL — a@@ -3653,20 +3658,20 @@ export function Canvas() {// resurrect their node) nor the retry (the publisher keeps the node in its baseline). The// only thing that can legitimately blow the cap is free text, i.e. a sticky's body — so say// so, instead of letting the note silently never sync.- if (!guard(m)) {+ if (!guard(stamped)) {setSyncNote('This note is too large to share with your teammates (over 250 KB). It stays on your ' +'canvas, but they will not see it until you shorten it.')return false}- order.onLocal(m)+ order.onLocal(stamped)// Cast to the ACTIVE session's core — a relay tab publishes to the relay HOST, not to B's// own local core (the bug this fixes). Byte-identical on a local tab (`activeSession.api`// IS `window.nodeTerminal`). `canvasSyncTarget` decides the GATE (hasPeers) at bind time;// the cast target is just the session's api, so reach it directly — no per-cast allocation// on this ~20 Hz path.- activeSession.api.canvas.mutate(projectId, m)+ activeSession.api.canvas.mutate(projectId, stamped)return true},// A hosted Viewer/Commenter publishes nothing: the host refuses canvas:mut for them (R5).diff --git a/src/shared/canvas-order.test.ts b/src/shared/canvas-order.test.tsindex e16dc2d2b..64db32e84 100644--- a/src/shared/canvas-order.test.ts+++ b/src/shared/canvas-order.test.ts@@ -172,6 +172,81 @@ describe('createCanvasOrder', () => {expect(o.accept(unstamped)).toBe(true)})+ // RULE 4 — a delete is not an edit, and `seq` alone cannot tell them apart. Before this, A's+ // delete losing the order race to B's next drag frame left the node ALIVE on every canvas as a+ // shell around a tmux session `kill-session` had already killed. `seen` (what the sender had+ // applied when it cast) separates "a stale frame" from "a deliberate re-creation".+ describe('rule 4 — a stale frame cannot resurrect a deleted node', () => {+ it('drops an upsert whose sender had not yet seen the delete', () => {+ const o = createCanvasOrder('me')+ expect(o.accept(rm('n1', 'a', 10))).toBe(true)+ // B's drag frame: ordered AFTER the remove, but produced when B knew only up to seq 9.+ expect(o.accept({ ...up('n1', 42, 'b', 11), seen: 9 })).toBe(false)+ })++ it('applies an upsert whose sender HAD seen the delete (a deliberate re-creation)', () => {+ const o = createCanvasOrder('me')+ expect(o.accept(rm('n1', 'a', 10))).toBe(true)+ // A's own ⌘Z, or anyone adding the node back: cast in full knowledge of the delete.+ expect(o.accept({ ...up('n1', 42, 'a', 11), seen: 10 })).toBe(true)+ // …and the node is alive again, so an ordinary later edit is not blocked by a dead entry.+ expect(o.accept({ ...up('n1', 43, 'b', 12), seen: 11 })).toBe(true)+ })++ it('does not judge an unstamped upsert (an older peer degrades, it does not break)', () => {+ const o = createCanvasOrder('me')+ expect(o.accept(rm('n1', 'a', 10))).toBe(true)+ expect(o.accept(up('n1', 42, 'b', 11))).toBe(true) // no `seen`: the pre-rule-4 verdict+ })++ // The mirror on the receiving side. Rule 2 rests on "our unacked mutation is later in the total+ // order, so it wins everywhere" — under rule 4 it does not, because every peer is about to drop+ // it as older than this delete. Suppressing the remove here is the one way to disagree with them.+ it('a remove is never held off by our own unacked drag (rule 2 does not apply to it)', () => {+ const o = createCanvasOrder('me')+ o.onLocal(o.stamp(up('n1', 1, 'me', 0))) // we are mid-drag, nothing acked yet+ expect(o.accept(up('n1', 5, 'peer', 7))).toBe(false) // a peer's EDIT still loses to ours+ expect(o.accept(rm('n1', 'peer', 8))).toBe(true) // …a peer's DELETE does not+ })++ // …and our own frames, echoed back after that delete, must not put the node back on OUR canvas+ // alone (every other client dropped them for being older than the remove).+ it('our own echo cannot resurrect a node a peer deleted mid-drag', () => {+ let t = 1000+ const o = createCanvasOrder('me', { now: () => t })+ o.onLocal(o.stamp(up('n1', 1, 'me', 0)))+ t += PENDING_TTL_MS + 1 // our ack is stuck; rule 3 would otherwise call the echo a repair+ expect(o.accept(rm('n1', 'peer', 20))).toBe(true)+ expect(o.accept({ ...up('n1', 1, 'me', 21), seen: 5 })).toBe(false)+ })++ it('stamps our casts with the highest seq we have processed, our own echo included', () => {+ const o = createCanvasOrder('me')+ expect(o.stamp(up('n1', 0, 'me', 0)).seen).toBe(0) // nothing applied yet+ o.accept(up('n2', 1, 'peer', 4))+ expect(o.stamp(up('n1', 0, 'me', 0)).seen).toBe(4)+ o.accept(up('n2', 2, 'me', 9)) // our own ack still advances our causal position+ expect(o.stamp(up('n1', 0, 'me', 0)).seen).toBe(9)+ o.accept(up('n2', 3, 'peer', 2)) // a straggler proves the order reached 2 — never lowers it+ expect(o.stamp(up('n1', 0, 'me', 0)).seen).toBe(9)+ })++ it('stamp is pure — it records no pending entry (a refused cast must cost nothing)', () => {+ const o = createCanvasOrder('me')+ o.stamp(up('n1', 1, 'me', 0)) // …the size guard then refuses it: onLocal is never called+ expect(o.accept(up('n1', 5, 'peer', 3))).toBe(true) // so the node is NOT deafened to peers+ })++ it('reset clears the removed set (a fresh core restarts its seq at 0)', () => {+ const o = createCanvasOrder('me')+ expect(o.accept(rm('n1', 'a', 10))).toBe(true)+ o.reset()+ // Same low seq the new core would hand out: without the clear, the old entry (10) would+ // outrank every new mutation and blackhole this node for the rest of the session.+ expect(o.accept({ ...up('n1', 1, 'b', 1), seen: 0 })).toBe(true)+ })+ })+it('reset forgets the order and the pending edits (project switch / reconnect)', () => {const o = createCanvasOrder('me')o.onLocal(up('n1', 1, 'me', 0))diff --git a/src/shared/canvas-order.ts b/src/shared/canvas-order.tsindex 9462f3686..3195c37a5 100644--- a/src/shared/canvas-order.ts+++ b/src/shared/canvas-order.ts@@ -36,10 +36,36 @@// this, a late ack left the client permanently on the losing value and its whole-file save// wrote those bytes over everyone else's canvas.//+// 4. A DELETE IS NOT AN EDIT, AND `seq` ALONE CANNOT TELL THEM APART. Rules 1-3 order mutations+// but say nothing about INTENT, and for one pair that gap was a real defect: A deletes a node+// while B is mid-drag, B's next frame is ordered after A's remove, so the upsert wins — the+// node SURVIVES on every canvas as a shell around a terminal `tmux kill-session` already+// killed. Consistent, and wrong: nobody asked for that node back.+//+// The missing fact is CAUSALITY. B's frame is not a decision to re-create the node; it was+// produced in ignorance of the delete. So every mutation carries `seen` — the highest `seq`+// its sender had applied when it cast — and the rule is exact, with no timer and no heuristic:+//+// an upsert for a removed node is DROPPED iff `seen < the seq the remove was ordered at`.+//+// A stale drag frame carries `seen` from before the remove and dies; a deliberate re-creation+// (⌘Z on the delete, a node re-added later) necessarily carries `seen` at or past it and is+// applied, which is what keeps this from becoming a blunt "delete always wins" — the tiebreak+// docs/team-presence.md rejected precisely because it would let one stale frame from a+// disconnected peer erase a node that was legitimately re-created.+//+// Its mirror on the receiving side: a `remove` is never held off by rule 2. Rule 2 rests on+// "our unacked mutation is later in the total order, so it wins everywhere" — and under this+// rule it no longer does, because every other client is about to drop it for the same reason+// we would be dropping the remove. Suppressing the remove here would be the one way to+// diverge from them.+//+// An UNSTAMPED mutation (no `seen`: an older peer, or a path with no reflector) is judged+// exactly as it was before this rule existed — applied. Degrade, never break.+//// Together those give: every client ends on the mutation with the highest `seq` for that node.-// Convergence, on any interleaving. What it deliberately does NOT give is intent preservation —-// two people dragging one node still fight, and a delete concurrent with an edit is decided by the-// total order, not by "delete wins" (see docs/team-presence.md, which states the resolution).+// Convergence, on any interleaving. What it deliberately does NOT give is intent preservation for+// two people dragging the SAME node — they still fight, and last-write-wins decides.//// Pure: no React, no DOM, no timers (the pending TTL below is a lazy clock read, not a timer).@@ -62,12 +88,32 @@ import type { CanvasMutation } from './types'*/export const PENDING_TTL_MS = 5000+/**+ * How many removed node ids stay judgeable (rule 4). An entry is dropped the moment the node is+ * legitimately re-created, so this only bounds nodes that were deleted and never came back — i.e.+ * a session's whole delete history. Far past any real canvas, and the eviction is a plain LRU:+ * losing the OLDEST entry degrades exactly to the pre-rule-4 behaviour for that node (a stale+ * upsert could resurrect it), never to something worse.+ */+export const REMOVED_MAX = 512+/** The node a mutation addresses. */export function mutationNodeId(m: CanvasMutation): string {return m.op === 'remove' ? m.id : m.node.id}export interface CanvasOrder {+ /**+ * Stamp a mutation we are ABOUT to cast with our causal position (`seen`) — rule 4.+ *+ * PURE, and separate from `onLocal` on purpose: the caller has to run the shared+ * `isCanvasMutation` size guard on the EXACT payload it will cast (a mutation the reflector+ * refuses is dropped silently, and one that recorded a pending entry would deafen that node to+ * its peers for a whole TTL). Stamping inside `onLocal` would mean guarding a payload a few+ * bytes smaller than the one that actually goes on the wire — the one difference that can put a+ * borderline mutation on the wrong side of the cap.+ */+ stamp(m: CanvasMutation): CanvasMutation/** Record a mutation WE are casting (it becomes pending until its echo comes back). */onLocal(m: CanvasMutation): void/**@@ -120,6 +166,44 @@ export function createCanvasOrder(* late ack is APPLIED rather than dropped, if the total order still says it wins.*/const superseded = new Set<string>()+ /**+ * RULE 4 — nodes a `remove` has taken off the canvas, and the `seq` that remove was ordered at.+ * An upsert whose sender had not yet applied that remove (`seen` below it) was produced in+ * ignorance of the delete and is dropped; anything at or past it is a deliberate re-creation and+ * is applied (which also clears the entry). Insertion-ordered, capped at REMOVED_MAX.+ */+ const removed = new Map<string, number>()+ /**+ * The highest `seq` we have applied or deliberately dropped, across ALL nodes — our causal+ * position in the total order, and what `stamp` puts on every mutation we cast. Global, not per+ * node: rule 4 compares a sender's knowledge of the ORDER against a remove's place in it, and+ * "what did this client know when it cast" has nothing to do with which node it addressed.+ */+ let lastSeq = 0++ const noteRemoved = (id: string, seq: number): void => {+ removed.delete(id) // re-insert so the Map's iteration order stays the LRU order+ removed.set(id, seq)+ while (removed.size > REMOVED_MAX) {+ const oldest = removed.keys().next().value as string | undefined+ if (oldest === undefined) break+ removed.delete(oldest)+ }+ }++ /**+ * Rule 4's verdict: is this upsert a stale frame from before the node was removed?+ *+ * An UNSTAMPED mutation (`seen` undefined — an older peer, the relay mirror, a test bus with no+ * reflector) is never blocked: we cannot judge its causality, and guessing "stale" would drop a+ * legitimate edit. Degrade to the pre-rule-4 behaviour rather than break.+ */+ const supersededByRemove = (m: CanvasMutation, id: string): boolean => {+ if (m.op !== 'upsert') return false+ const at = removed.get(id)+ if (at === undefined) return false+ return typeof m.seen === 'number' && m.seen < at+ }/** Is rule 2's suppression live for this node? Lapses on the TTL (the entry stays: see Pending). */const suppressing = (id: string): boolean => {@@ -134,6 +218,13 @@ export function createCanvasOrder(}return {+ stamp(m) {+ // `lastSeq` 0 = we have applied nothing from the reflector yet, which is also the value an+ // unstamped mutation would carry. Stamp it anyway: 0 is a truthful causal position (we know+ // about nothing), and it is what makes a first-frame drag lose to a delete that precedes it.+ return { ...m, seen: lastSeq }+ },+onLocal(m) {const id = mutationNodeId(m)const p = pending.get(id)@@ -157,13 +248,27 @@ export function createCanvasOrder(// `seq` 0 means an unstamped mutation (no reflector in the path) — never treat it as stale.const current = seq === 0 || seq > highestif (seq > highest) seen.set(id, seq)+ // Our causal position for the mutations WE cast next (rule 4). Advanced for EVERYTHING we+ // process — our own echo included, and a straggler too: both prove the order has reached at+ // least that far, and "what did this client know" says nothing about who sent it.+ if (seq > lastSeq) lastSeq = seq++ // Rule 4's bookkeeping, before any verdict below reads it. Only a CURRENT mutation may move+ // it: a straggler describes a state the total order has already left behind.+ const stale = supersededByRemove(m, id)+ if (current) {+ if (m.op === 'remove') noteRemoved(id, seq)+ else if (!stale) removed.delete(id) // a deliberate re-creation: this node is alive again+ }if (m.src && m.src === src) {const p = pending.get(id)// Rule 3: our optimistic value was overwritten by a peer while this cast was in flight (the// TTL had lapsed, so rule 2 no longer held it off). If this echo still wins the total order,// it is a REPAIR, not a rubber-band — apply it and land where every other client already is.- const repair = superseded.has(id) && current+ // Rule 4 forecloses that: a value the delete superseded lost on every OTHER client, so+ // replaying it here would resurrect — on this canvas alone — a node nobody else has.+ const repair = superseded.has(id) && current && !stale// Rule 1: otherwise our own echo is just an ack — consume it, apply nothing.if (p && --p.count <= 0) {pending.delete(id)@@ -174,9 +279,16 @@ export function createCanvasOrder(// A straggler: a mutation the total order has already superseded on this client (applied, or// deliberately dropped). Applying it would move the node BACKWARDS out of the total order.if (!current) return false+ // Rule 4: cast in ignorance of the delete — a stale frame, not a decision to bring the node+ // back. (A re-creation carries `seen` at or past the remove and never reaches here.)+ if (stale) return false// Rule 2: an edit of ours for this node is still in flight, so it is later in the total order// than this one and will win everywhere. Keep ours; the peers will land on it.- if (suppressing(id)) return false+ //+ // NEVER for a `remove`. Rule 2 rests on our unacked mutation winning everywhere, and under+ // rule 4 it does not: every other client is about to drop it for being older than this+ // delete. Holding the remove off here is the one way to end up disagreeing with them.+ if (m.op !== 'remove' && suppressing(id)) return false// Applying a peer's mutation over an unacked cast of ours (the TTL lapsed — `suppressing`// just said so, but the entry is still there): remember that our value is gone, so the late// ack can repair it (rule 3).@@ -188,6 +300,11 @@ export function createCanvasOrder(seen.clear()pending.clear()superseded.clear()+ // The core may have restarted at seq 0 — a `removed` entry stamped with the OLD counter would+ // then outrank every new mutation and blackhole that node, and a stale `lastSeq` would put a+ // causal position on our casts that the new order has not reached.+ removed.clear()+ lastSeq = 0}}}diff --git a/src/shared/types.ts b/src/shared/types.tsindex f8dfbdb9d..9f7c19cb1 100644--- a/src/shared/types.ts+++ b/src/shared/types.ts@@ -649,11 +649,17 @@ export interface CanvasState {* that echo is the ACK that tells the sender where its edit landed in the total order).* - `seq` is stamped by the reflector (src/core/canvas-sync.ts) and is the TOTAL ORDER. It is* server-authoritative: a client-supplied `seq` is overwritten at ingest, never trusted.- * The relay's host↔client mirror (src/main/remote) uses the same vocabulary and simply omits both.+ * - `seen` is the sender's CAUSAL stamp: the highest `seq` it had applied at the moment it cast.+ * It answers the one question `seq` alone cannot — "did this client already know about the+ * delete?" — which is what lets a delete beat a concurrent drag frame instead of being+ * resurrected by it (canvas-order's rule 4). Client-supplied, so the reflector BOUNDS it+ * (it can never legitimately reach the order it is being given); a mutation without it is+ * judged exactly as before, so an unstamped peer degrades rather than breaks.+ * The relay's host↔client mirror (src/main/remote) uses the same vocabulary and simply omits them.*/export type CanvasMutation =- | { op: 'upsert'; node: CanvasNodeState; src?: string; seq?: number }- | { op: 'remove'; id: string; src?: string; seq?: number }+ | { op: 'upsert'; node: CanvasNodeState; src?: string; seq?: number; seen?: number }+ | { op: 'remove'; id: string; src?: string; seq?: number; seen?: number }/** Canvas pan/zoom state. */export interface Viewport {