Skip to content

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.

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.md
index 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 wherever
the 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 but
they *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.ts
index 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 it
bus.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.ts
index 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.ts
index 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 - 1
return stamped
}
diff --git a/src/renderer/canvas/Canvas.tsx b/src/renderer/canvas/Canvas.tsx
index 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().activeProjectId
if (!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.ts
index 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.ts
index 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 > highest
if (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.ts
index 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 {