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
// Convergence: two clients, interleaved local edits, one ordering reflector → identical node sets.
//
// No CRDT: per-node last-write-wins IN THE REFLECTOR'S TOTAL ORDER is the whole contract. That
// property is what makes persistence safe — whichever client calls workspace.save writes the same
// bytes, so a peer's delete can never be written back to disk by someone whose canvas still held
// the node, and two people dragging one node cannot leave it at two different places forever.
//
// THE BUS IS ASYNCHRONOUS, deliberately. The first version of this suite delivered each mutation
// into the peer inside the sender's own cast() call, so two edits could never be in flight at once
// — which is the ONLY condition under which last-write-wins can diverge. It therefore "passed" a
// design that diverged permanently on the very first concurrent drag. A synchronous bus cannot
// catch this class of bug. Here, casts and deliveries are QUEUED (FIFO per link, exactly as IPC and
// a WebSocket deliver), so a test can hold several edits in flight and choose the interleaving.
//
// Everything else runs against the REAL pieces: the real reflector (initCanvasSync — `seq` stamping
// + fan-out to every client, sender included), the real publisher (createCanvasPublisher: diff,
// `src` stamping, adopt loop guard, ephemeral filter), the real ordering state (createCanvasOrder)
// and the real apply vocabulary (applyCanvasMutation). Only the transport is simulated.
import { describe, it, expect, beforeEach, afterEach } from 'vitest'
import { initPlatform, resetPlatformForTests, type CorePlatform } from './platform'
import { makeFakeUserDataDir } from './platform-fake'
import { initCanvasSync, MUTATION_MAX_BYTES, setReflectedListener } from './canvas-sync'
import { createCanvasAuthority } from './canvas-authority'
import {
applyCanvasMutation,
applyEdgeMutationToScene,
isCanvasMutation,
type CanvasScene
} from '../shared/canvas-mutations'
import {
createCanvasOrder,
createReconnectWatch,
isRemoveOp,
mutationKey,
PENDING_TTL_MS
} from '../shared/canvas-order'
import { createCanvasPublisher, publishableScene, shouldPublishCanvas } from '../shared/canvas-publish'
import { applyCanvasOp, type CanvasContent } from '../shared/canvas-content'
import { defaultKanbanFor } from '../shared/kanban-default-board'
import { applyKanbanOp, diffKanbanOps, isKanbanOp, sanitizeKanbanOp } from '../shared/kanban-ops'
import { IPC } from '../shared/ipc'
import type { BridgeLink, CanvasMutation, CanvasNodeState, ProjectKanban } from '../shared/types'
const node = (id: string, x: number, title = 't', color = '#fff'): CanvasNodeState =>
({
id,
kind: 'terminal',
title,
color,
group: null,
position: { x, y: 0 },
size: { width: 10, height: 10 }
}) as CanvasNodeState
/** A sticky whose body someone pasted a document into: its serialized form is over
* MUTATION_MAX_BYTES, so the reflector REFUSES it at ingest — silently, with no negative ack. */
const fat = (id: string): CanvasNodeState =>
({
...node(id, 0),
kind: 'sticky',
data: { text: 'x'.repeat(MUTATION_MAX_BYTES) }
}) as CanvasNodeState
const PROJECT = 'p1'
/**
* The transport, ASYNC. Two FIFO queues — the two orderings a real deployment guarantees:
* - `casts`: client → reflector. The order the reflector pops them in IS the total order.
* - `inbox[clientId]`: reflector → that client. Per-connection FIFO (IPC and WS both give this,
* and canvas-order's rule 2 depends on it).
* Nothing moves until the test says so, so several clients can hold edits in flight at once.
*/
class Bus {
private readonly senderListeners = new Map<string, (senderId: number, ...args: any[]) => void>()
private readonly casts: Array<{ sender: number; projectId: string; m: CanvasMutation }> = []
private readonly inbox = new Map<number, Array<{ projectId: string; m: CanvasMutation }>>()
readonly deliver = new Map<number, (projectId: string, m: CanvasMutation) => void>()
clients: number[] = []
/** Total casts made BY clients (publisher → reflector). One per real local edit; never more. */
castCount = 0
/** Clients whose INBOX is stalled — their socket is backed up (Stage 2 tolerates an 8 MB pty
* backlog on the very same socket), so their acks and their peers' mutations arrive late.
* Their casts still reach the reflector: only the return path is blocked. */
private readonly stalled = new Set<number>()
platform: CorePlatform = {
// Never a fixed literal: a predictable '/tmp/...' registered through initPlatform is the
// js/insecure-temporary-file shape (see canvas-sync.test.ts). Under the run root, removed with it.
userDataDir: makeFakeUserDataDir(),
appVersion: '0.0.0-test',
isPackaged: false,
handle: () => {},
on: () => {},
handleWithSender: () => {},
onWithSender: (ch, fn) => void this.senderListeners.set(ch, fn),
clientIds: () => this.clients,
sendTo: (to, channel, ...args) => {
if (channel !== IPC.canvasMut) return
const q = this.inbox.get(to) ?? []
q.push({ projectId: args[0] as string, m: args[1] as CanvasMutation })
this.inbox.set(to, q)
},
broadcast: () => {},
openExternal: async () => {}
}
/** A client casts: the mutation is QUEUED, not reflected. It reaches the reflector on settle(). */
cast(senderId: number, projectId: string, m: CanvasMutation): void {
this.castCount++
this.casts.push({ sender: senderId, projectId, m })
}
/** Pop one cast into the reflector — this is where a mutation gets its place in the total order. */
private stepCast(): boolean {
const c = this.casts.shift()
if (!c) return false
this.senderListeners.get(IPC.canvasMut)?.(c.sender, c.projectId, c.m)
return true
}
/** Stall / unstall one client's inbox (a backed-up socket). */
stall(id: number): void {
this.stalled.add(id)
}
unstall(id: number): void {
this.stalled.delete(id)
}
/** Pop one queued delivery into its addressed client (FIFO within that client's inbox). */
private stepDelivery(): boolean {
for (const id of this.clients) {
if (this.stalled.has(id)) continue
const q = this.inbox.get(id)
if (!q?.length) continue
const d = q.shift() as { projectId: string; m: CanvasMutation }
this.deliver.get(id)?.(d.projectId, d.m)
return true
}
return false
}
/** Run the network to quiescence: every queued cast reflected, every delivery delivered. */
settle(): void {
for (let i = 0; i < 10_000; i++) {
if (this.stepCast()) continue
if (this.stepDelivery()) continue
return
}
throw new Error('bus did not settle — mutation loop?')
}
}
/** A simulated client: its own node list, publisher and ordering state, wired by ClientId.
* Mirrors the two Canvas effects — publish the diff of the settled snapshot; on an incoming
* mutation ask the ordering state whether to apply it, then adopt (never re-publish) the result. */
class Client {
states: CanvasNodeState[] = []
/** The two PERSISTED edge lists, alongside the nodes — they ride the same whole-file save, so
* they are part of what has to converge (see the edge tests at the bottom). */
bridges: BridgeLink[] = []
ropes: BridgeLink[] = []
/** Ephemeral cards (subagent / loop) this client renders — derived locally, never published. */
ephemeral = new Set<string>()
/** The project's board. Absent = the deterministic lazy default, exactly as a project whose file
* has no `kanban` block — so it is part of what converges, like the edge lists. */
board: ProjectKanban | undefined = undefined
/** Every mutation this client CAST, in order (after its own gates) — what a test reads to prove a
* rule held on the SENDING side, e.g. that a prune removal never left this client. */
readonly cast: CanvasMutation[] = []
/** Mutations APPLIED from the wire (an own echo, or one the order supersedes, is not applied). */
applied = 0
/** Local mutations the publisher tried to cast and this client refused (oversized / malformed). */
refused = 0
private readonly order: ReturnType<typeof createCanvasOrder>
private readonly pub: ReturnType<typeof createCanvasPublisher>
private readonly src: string
/** Mirrors Canvas's presence subscription: reset the order state only on a GENUINE reconnect. */
private readonly reconnected = createReconnectWatch(null)
constructor(
readonly id: number,
private readonly bus: Bus,
/** Canvas's publish gate. Absent = always publish (every other test here has a peer attached). */
gate?: () => boolean
) {
// Built here, not as field initializers: a field initializer runs BEFORE the parameter
// properties are assigned, so `this.id` would still be undefined and both clients would stamp
// the same `src` — every peer mutation would then look like their own echo.
const src = `src-${id}`
this.src = src
// A FAKE clock: the pending TTL is the one time-dependent rule in canvas-order, and the tests
// below need to cross it deliberately (`clock += ...`) rather than by sleeping.
this.order = createCanvasOrder(src, { now: () => clock })
// Mirrors Canvas: the node/edge publisher and the board publisher cast through ONE send
// (`castFor`), so both families are stamped, gated and recorded by the same order.
this.pub = createCanvasPublisher((m) => this.send(m), { src, ...(gate ? { shouldPublish: gate } : {}) })
bus.deliver.set(id, (projectId, m) => {
if (projectId !== PROJECT) return
// Mirrors Canvas: our own remove coming back RELEASES a re-creation the gate held — cast it now,
// after this mutation is handled (a repaired remove is applied first), or it waits for an edit.
const key = mutationKey(m, projectId)
const held = this.order.hasPendingRemove(key)
const apply = this.order.accept(m, projectId)
const released = held && !this.order.hasPendingRemove(key)
if (apply && isKanbanOp(m)) {
// Mirrors Canvas: a board op lands in the projects STORE through the one reducer — never
// through the board funnel, whose publish hook would cast it again — and touches no node.
this.applied++
this.board = applyCanvasOp(this.content(), m, PROJECT).kanban
} else if (apply) {
this.applied++
this.states = applyCanvasMutation(this.states, m)
// One id is one edge across both lists — what Canvas and the projects store apply.
const edges = applyEdgeMutationToScene({ bridges: this.bridges, ropes: this.ropes }, m)
this.bridges = edges.bridges
this.ropes = edges.ropes
this.pub.adopt(this.publishable()) // loop guard — never re-publish someone else's change
}
if (released && this.pub.hasOwed()) this.pub.publish(this.publishable())
})
}
/** THE ONE CAST — Canvas's `castFor`, for the one project this harness has: stamp `src` + `seen`,
* the re-creation gate, the reflector's own predicate, then record it as pending and cast. */
private send(m: CanvasMutation): boolean {
// Mirrors Canvas: ask the SAME predicate the reflector's ingest asks, BEFORE recording a
// 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.
// 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, src: this.src })
// The re-creation gate, as Canvas has it: a re-creation of a key whose remove of ours is
// still unacked would carry a `seen` below that remove — held (owed) until the echo lands.
// The project rides every key the order builds (ruling R4: a board's order ops are
// per-project singletons) — the same PROJECT the cast goes out on.
if (!isRemoveOp(stamped) && this.order.hasPendingRemove(mutationKey(stamped, PROJECT))) return false
if (!isCanvasMutation(stamped)) {
this.refused++
return false
}
this.order.onLocal(stamped, PROJECT)
this.cast.push(stamped)
this.bus.cast(this.id, PROJECT, stamped)
return true
}
private content(): CanvasContent {
return { nodes: this.states, bridges: this.bridges, ropes: this.ropes, ...(this.board ? { kanban: this.board } : {}) }
}
private publishable(): CanvasScene {
return publishableScene(
{ nodes: this.states, bridges: this.bridges, ropes: this.ropes },
this.ephemeral
)
}
/** A local edit: take the new node list, then publish the diff (what the Canvas effect does). */
edit(next: CanvasNodeState[]): void {
this.states = next
this.pub.publish(this.publishable())
}
/** A local EDGE edit — drawing or deleting a context link / rope. Same effect, same publisher:
* the Canvas publish effect has the edge arrays in its deps for exactly this. */
editEdges(next: { bridges?: BridgeLink[]; ropes?: BridgeLink[] }): void {
if (next.bridges) this.bridges = next.bridges
if (next.ropes) this.ropes = next.ropes
this.pub.publish(this.publishable())
}
/** A local BOARD edit — what `useProjects.setProjectKanban` + the kanban publisher do
* (renderer/canvas/kanban-sync.ts): diff the board item by item against this client's OWN nodes
* (a card whose node is not live here is pruned locally and its removal is never cast), cast the
* clean form of each op through the same send, and keep that clean form locally when the board
* held something else (ruling R2: the reflector repairs what it relays and our own echo is only
* an ack, so an unrepaired local value would be ours alone, for good). */
editBoard(next: ProjectKanban): void {
const prev = this.board
this.board = next
const live = new Set(this.states.map((n) => n.id))
for (const op of diffKanbanOps(prev, next, PROJECT, live)) {
const clean = sanitizeKanbanOp(op)
if (!clean) continue
if (this.send(clean) && stableJson(clean) !== stableJson(op))
this.board = applyCanvasOp(this.content(), clean, PROJECT).kanban
}
}
/** Our presence clientId resolved (or changed). What Canvas's presence subscription does: the
* ordering state is forgotten ONLY when a NEW clientId replaces an OLD one — a fresh connection
* to a core whose `seq` may have restarted at 0. The first `null → myId` hello is not that. */
presence(id: string | null): void {
if (this.reconnected(id)) this.order.reset()
}
/** Adopt the freshly loaded canvas as the publisher baseline without publishing it — what Canvas
* does while `loadingRef` is set (a project load is not an edit). */
pubAdopt(): void {
this.pub.adopt(this.publishable())
}
/** The node set that would be written by this client's workspace.save (ephemeral cards excluded,
* as flowToNodeStates already excludes them). */
persisted(): CanvasScene {
return this.publishable()
}
ids(): string[] {
return this.states.map((n) => n.id).sort()
}
x(id: string): number | undefined {
return this.states.find((n) => n.id === id)?.position.x
}
}
/**
* The convergence contract, canonically: the same NODE SET, and the same VALUE for every node.
*
* Array ORDER is deliberately NOT part of it. When a delete loses the order race, the client that
* issued it removed the node and then re-appended it (applyCanvasMutation appends an upsert of an
* absent node), so its array can end up carrying that node in a different SLOT than a client that
* never removed it. Array order drives only the sidebar listing — positions, sizes, data and the
* node set all agree, so either client's save writes a canvas the other agrees with. Documented as
* such in docs/team-presence.md; use this helper wherever a resurrection can happen.
*/
/** JSON with sorted keys — "the same op" as the kanban publisher judges it (key order is not a change). */
function stableJson(v: unknown): string {
return JSON.stringify(v, (_k, val: unknown) =>
val && typeof val === 'object' && !Array.isArray(val)
? Object.fromEntries(Object.keys(val).sort().map((k) => [k, (val as Record<string, unknown>)[k]]))
: val
)
}
const canon = (c: Client): CanvasNodeState[] =>
[...c.persisted().nodes].sort((x, y) => x.id.localeCompare(y.id))
let bus: Bus
let a: Client
let b: Client
/** The clients' shared fake clock (ms), read by every canvas-order pending TTL. */
let clock = 0
function boot(): void {
clock = 1_000
bus = new Bus()
initPlatform(bus.platform)
initCanvasSync()
a = new Client(1, bus)
b = new Client(2, bus)
bus.clients = [1, 2]
}
beforeEach(boot)
afterEach(() => resetPlatformForTests())
describe('canvas convergence (async bus)', () => {
// THE case a synchronous bus cannot express: both clients edit the SAME node before either has
// heard from the other. Two people dragging one node cross like this on every single frame.
it('concurrent move of the same node converges (both land on the ordered winner)', () => {
a.edit([node('n1', 0)])
bus.settle()
// In flight at the same time: A drags n1 to 200, B drags the same node to 100.
a.edit([node('n1', 200)])
b.edit([node('n1', 100)])
bus.settle()
expect(a.states).toEqual(b.states)
expect(a.x('n1')).toBe(b.x('n1'))
// The reflector popped A's cast first, so B's is the LATER write in the total order — B wins,
// on both canvases. (Before the ordering fix: A showed 200 and B showed 100, forever.)
expect(a.x('n1')).toBe(100)
expect(a.persisted()).toEqual(b.persisted())
})
it('converges whichever way the reflector orders the two concurrent writes', () => {
b.edit([node('n1', 100)]) // B's cast is queued first this time
a.edit([node('n1', 200)])
bus.settle()
expect(a.states).toEqual(b.states)
expect(a.x('n1')).toBe(200) // A's cast was popped last → A wins, on both
})
// 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).
//
// 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()
a.edit(a.states.filter((n) => n.id !== 'n1')) // A deletes n1…
b.edit(b.states.map((n) => (n.id === 'n1' ? node('n1', 50) : n))) // …while B drags it
bus.settle()
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())
})
// ── Edges ──────────────────────────────────────────────────────────────────────────────────────
// The sharpest data-loss shape this stage had left open, and it was WORSE than a cosmetic gap:
// edges were not in the mutation vocabulary but they ARE in the whole-file save, so an edge you
// drew never reached your teammate — and their next save, of a canvas that never had it, deleted
// it for everyone. (Same in reverse.)
describe('edges converge like nodes', () => {
it("a link A draws reaches B — and B's save no longer deletes it", () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
a.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'n2' }] })
bus.settle()
expect(b.bridges).toEqual([{ id: 'b1', source: 'n1', target: 'n2' }])
// THE assertion: B's whole-file save now writes A's edge, instead of erasing it.
expect(b.persisted().bridges).toEqual(a.persisted().bridges)
// …and an unrelated edit by B does not lose it either (the publisher's baseline carries it).
b.edit([...b.states, node('n3', 0)])
bus.settle()
expect(b.persisted().bridges).toEqual(a.persisted().bridges)
})
it('a deleted link stays deleted on both', () => {
a.edit([node('n1', 0), node('n2', 0)])
a.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'n2' }] })
bus.settle()
b.editEdges({ bridges: [] })
bus.settle()
expect(a.bridges).toEqual([])
expect(a.persisted()).toEqual(b.persisted())
})
it('bridges and ropes are two lists, and a mutation only touches its own kind', () => {
a.edit([node('n1', 0), node('n2', 0)])
a.editEdges({ ropes: [{ id: 'ctrl-1', source: 'n1', target: 'n2' }] })
bus.settle()
expect(b.ropes).toEqual([{ id: 'ctrl-1', source: 'n1', target: 'n2' }])
expect(b.bridges).toEqual([])
})
it('a peer edge is applied once and re-published NEVER (the adopt loop guard covers edges)', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
const before = bus.castCount
a.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'n2' }] })
bus.settle()
expect(bus.castCount - before).toBe(1) // one local edit, one cast, no counter-cast from B
})
// Both edges survive on both clients. Compared as a SET, not as an array: each client appended
// the peer's edge to its own, so the two arrays hold the same edges in different SLOTS — the
// same array-order caveat docs/team-presence.md already names for nodes, and it matters even
// less here (edges are rendered as a set; nothing lists them in order).
it('two clients drawing edges at the same time keep BOTH', () => {
a.edit([node('n1', 0), node('n2', 0), node('n3', 0)])
bus.settle()
a.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'n2' }] })
b.editEdges({ bridges: [{ id: 'b2', source: 'n2', target: 'n3' }] })
bus.settle()
const byId = (es: BridgeLink[]) => [...es].sort((x, y) => x.id.localeCompare(y.id))
expect(byId(a.persisted().bridges)).toEqual(byId(b.persisted().bridges))
expect(a.bridges.map((e) => e.id).sort()).toEqual(['b1', 'b2'])
})
// Rule 4 is keyed on `mutationKey`, so it covers an edge exactly as it covers a node: a client
// re-pointing an edge in ignorance of its delete must not bring it back.
it('a stale edge frame cannot resurrect a deleted edge', () => {
a.edit([node('n1', 0), node('n2', 0)])
a.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'n2' }] })
bus.settle()
b.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'n1' }] }) // B re-points it…
a.editEdges({ bridges: [] }) // …while A deletes it
bus.settle()
expect(a.bridges).toEqual([])
expect(b.bridges).toEqual([])
})
// An edge whose endpoint is an ephemeral card (a subagent / loop node) must not go on the wire
// for the same reason the card itself must not: the peer derives that node independently.
it('an edge to an ephemeral card is never published', () => {
a.ephemeral.add('sub-1')
a.edit([node('n1', 0), node('sub-1', 0)])
bus.settle()
const before = bus.castCount
a.editEdges({ bridges: [{ id: 'b1', source: 'n1', target: 'sub-1' }] })
bus.settle()
expect(bus.castCount - before).toBe(0)
expect(b.bridges).toEqual([])
})
})
// THE RE-CREATION GATE (port map §6.5). Our own remove enters `seen` only when its echo comes back,
// so a re-creation of the same id cast before that — a link deleted and redrawn, a node deleted and
// ⌘Z'd, inside one round trip — carries a `seen` below the remove, and every PEER drops it as a
// stale frame (rule 4) while we keep showing it. Held back until the echo lands, then cast, it
// carries the remove in its `seen` and is a re-creation everywhere.
describe('a re-creation waits for our own pending remove of the same id', () => {
const bridge = { id: 'bridge-n1-n2', source: 'n1', target: 'n2' }
const byId = (es: BridgeLink[]) => [...es].sort((x, y) => x.id.localeCompare(y.id))
it('a link deleted and redrawn before our echo returns reaches the peer', () => {
a.edit([node('n1', 0), node('n2', 0)])
a.editEdges({ bridges: [bridge] })
bus.settle()
bus.stall(a.id) // our socket is backed up: our acks are late
a.editEdges({ bridges: [] }) // A removes the link…
a.editEdges({ bridges: [bridge] }) // …and draws it again before the remove's echo is back
bus.unstall(a.id)
bus.settle()
expect(canon(a)).toEqual(canon(b))
expect(byId(a.persisted().bridges)).toEqual(byId(b.persisted().bridges))
expect(a.bridges).toEqual([bridge])
expect(b.bridges).toEqual([bridge]) // was: [] — B dropped the redraw as a stale frame
})
// The echo is rarely the only thing in flight: a teammate's op for ANOTHER node is ordered first
// and adopted while the redraw is still held. The adopt must not take the held link into the
// baseline, or the release finds nothing to cast.
it('…even when a teammate’s op is adopted while the redraw is held', () => {
a.edit([node('n1', 0), node('n2', 0), node('n3', 0)])
a.editEdges({ bridges: [bridge] })
bus.settle()
bus.stall(a.id)
b.edit(b.states.map((n) => (n.id === 'n3' ? node('n3', 30) : n))) // B's move is ordered first
a.editEdges({ bridges: [] })
a.editEdges({ bridges: [bridge] })
bus.unstall(a.id)
bus.settle()
expect(a.x('n3')).toBe(30)
expect(b.bridges).toEqual([bridge])
expect(a.persisted()).toEqual(b.persisted())
})
it('a node deleted and ⌘Z’d before our echo returns comes back on the peer too', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
bus.stall(a.id)
const before = a.states
a.edit(a.states.filter((n) => n.id !== 'n1')) // delete…
a.edit(before) // …undo
bus.unstall(a.id)
bus.settle()
expect(b.ids()).toEqual(['n1', 'n2']) // was: ['n2'] — B dropped the undo as a stale frame
expect(canon(a)).toEqual(canon(b))
})
it('the release casts the held re-creation once, and nothing after it', () => {
a.edit([node('n1', 0), node('n2', 0)])
a.editEdges({ bridges: [bridge] })
bus.settle()
bus.stall(a.id)
a.editEdges({ bridges: [] })
a.editEdges({ bridges: [bridge] })
const beforeRelease = bus.castCount
bus.unstall(a.id)
bus.settle()
expect(bus.castCount - beforeRelease).toBe(1) // the held redraw, cast on the echo
const settled = bus.castCount
a.edit([...a.states]) // an unrelated publish
bus.settle()
expect(bus.castCount - settled).toBe(0)
})
})
// 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(['n2'])
})
it('delete wins when it is the later write, and stays deleted on both', () => {
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 move is cast first…
a.edit(a.states.filter((n) => n.id !== 'n1')) // …A's delete is ordered after it
bus.settle()
expect(a.ids()).toEqual(['n2'])
expect(b.ids()).toEqual(['n2'])
expect(a.persisted()).toEqual(b.persisted())
})
// A drag is a STREAM of concurrent writes: 20 Hz of frames from each side, all in flight at once.
it('two clients dragging the same node for many frames still converge', () => {
a.edit([node('n1', 0)])
bus.settle()
for (let i = 1; i <= 20; i++) {
a.edit([node('n1', i * 10)])
b.edit([node('n1', 1000 - i * 10)])
if (i % 3 === 0) bus.settle() // …with the network catching up only sometimes
}
bus.settle()
expect(a.states).toEqual(b.states)
expect(a.persisted()).toEqual(b.persisted())
})
it('interleaved mutations from two clients leave identical node sets', () => {
a.edit([node('n1', 0)]) // A adds n1
bus.settle()
b.edit([...b.states, node('n2', 0)]) // B adds n2
bus.settle()
a.edit(a.states.map((n) => (n.id === 'n1' ? node('n1', 40) : n))) // A drags n1
b.edit(b.states.map((n) => (n.id === 'n2' ? node('n2', 0, 'B') : n))) // B renames n2
bus.settle()
a.edit(a.states.filter((n) => n.id !== 'n2')) // A deletes B's node
bus.settle()
expect(a.ids()).toEqual(b.ids())
expect(a.ids()).toEqual(['n1'])
expect(a.states).toEqual(b.states)
expect(a.x('n1')).toBe(40)
// The whole point: whichever client saves, it writes the same bytes.
expect(a.persisted()).toEqual(b.persisted())
})
it('converges under every interleaving AND every settle point of the same edit set', () => {
// Six edits, replayed in different orders AND with the network settling at different points —
// `settleEvery: 6` means all six are cast before a single one is delivered, i.e. maximum
// concurrency. Both clients must land on one node set every time.
const orders = [
[0, 1, 2, 3, 4, 5],
[5, 4, 3, 2, 1, 0],
[0, 3, 1, 4, 2, 5],
[2, 0, 5, 1, 3, 4],
[4, 2, 0, 3, 5, 1]
]
for (const order of orders) {
for (const settleEvery of [1, 2, 6]) {
resetPlatformForTests()
boot()
const edits: Array<() => void> = [
() => a.edit([...a.states.filter((n) => n.id !== 'n1'), node('n1', 10)]),
() => b.edit([...b.states.filter((n) => n.id !== 'n2'), node('n2', 20)]),
() => a.edit(a.states.map((n) => (n.id === 'n2' ? node('n2', 99) : n))),
() => b.edit(b.states.map((n) => (n.id === 'n1' ? node('n1', 10, 'renamed') : n))),
() => a.edit([...a.states.filter((n) => n.id !== 'n3'), node('n3', 30)]),
() => b.edit(b.states.filter((n) => n.id !== 'n3'))
]
let n = 0
for (const i of order) {
edits[i]()
if (++n % settleEvery === 0) bus.settle()
}
bus.settle()
const tag = `order ${order.join('')} settle/${settleEvery}`
// `canon`, not raw array equality: this set contains a delete that can lose the order race,
// and the client that issued it re-appends the node in a different slot (see `canon`).
expect(a.ids(), tag).toEqual(b.ids())
expect(canon(a), tag).toEqual(canon(b))
}
}
})
it('three clients editing the same node concurrently converge on one value', () => {
const c = new Client(3, bus)
bus.clients = [1, 2, 3]
a.edit([node('n1', 0)])
bus.settle()
a.edit([node('n1', 1)])
b.edit([node('n1', 2)])
c.edit([node('n1', 3)])
bus.settle()
expect(a.states).toEqual(b.states)
expect(b.states).toEqual(c.states)
expect(a.x('n1')).toBe(3) // C's cast was ordered last
})
it('last write wins on a concurrent edit to the same node (no CRDT, no merge, no duplicate)', () => {
a.edit([node('n1', 0)])
a.edit([node('n1', 10)])
b.edit(b.states.map((n) => (n.id === 'n1' ? node('n1', 20) : n)))
bus.settle()
expect(a.states).toEqual(b.states)
expect(a.states).toHaveLength(1) // one node, not two — upsert replaces by id
})
it('no infinite loop: an applied mutation is never re-published', () => {
a.edit([node('n1', 0)])
bus.settle()
expect(b.applied).toBe(1)
expect(a.applied).toBe(0) // A's own echo is an ACK, not an edit — applied optimistically already
expect(bus.castCount).toBe(1) // one local edit → exactly one cast; B did not re-emit it
b.edit(b.states.map((n) => (n.id === 'n1' ? node('n1', 5) : n)))
bus.settle()
expect(a.applied).toBe(1)
expect(b.applied).toBe(1) // B did not apply its own echo, and A did not re-emit it
expect(bus.castCount).toBe(2) // still one cast per local edit — the adopt() guard holds
expect(a.states).toEqual(b.states)
})
it('a burst of peer mutations still produces no counter-cast (3 clients, bulk delete)', () => {
const c = new Client(3, bus)
bus.clients = [1, 2, 3]
a.edit([node('n1', 0), node('n2', 0), node('n3', 0)])
bus.settle()
expect(bus.castCount).toBe(3) // three upserts, from A only
a.edit([]) // bulk delete — three removes in one tick
bus.settle()
expect(bus.castCount).toBe(6) // three removes, from A only: B and C reflected nothing back
expect(b.states).toEqual([])
expect(c.states).toEqual([])
expect(b.applied + c.applied).toBe(12) // 6 mutations × 2 peers each
})
it('ephemeral subagent / loop cards are never published', () => {
a.ephemeral.add('subagent-abc')
a.edit([node('n1', 0), node('subagent-abc', 5), node('loop-n1', 9)])
bus.settle()
expect(a.ids()).toEqual(['loop-n1', 'n1', 'subagent-abc']) // A still renders its own cards
expect(b.ids()).toEqual(['n1']) // …and the peer got only the real node
expect(b.applied).toBe(1)
// Moving an ephemeral card emits nothing at all (it is not in the published baseline).
const casts = bus.castCount
a.edit(a.states.map((n) => (n.id === 'subagent-abc' ? node('subagent-abc', 77) : n)))
bus.settle()
expect(bus.castCount).toBe(casts)
expect(b.ids()).toEqual(['n1'])
// …and the real nodes still converge.
expect(a.persisted()).toEqual(b.persisted())
})
it('a third client that joins late converges with the other two', () => {
a.edit([node('n1', 0)])
a.edit([...a.states, node('n2', 0)])
a.edit(a.states.filter((n) => n.id !== 'n1')) // n1 deleted before C ever connects
bus.settle()
const c = new Client(3, bus)
bus.clients = [1, 2, 3]
c.states = [...a.states] // a fresh client loads the canvas from disk/store on mount
c.pubAdopt() // …and adopts it as the baseline, without republishing it
expect(bus.castCount).toBe(3) // the join itself cast nothing
a.edit(a.states.map((n) => (n.id === 'n2' ? node('n2', 7) : n)))
b.edit([...b.states, node('n4', 1)])
c.edit(c.states.map((n) => (n.id === 'n2' ? node('n2', 7, 'from C') : n)))
bus.settle()
expect(c.states).toEqual(a.states)
expect(b.states).toEqual(a.states)
expect(a.ids()).toEqual(['n2', 'n4'])
expect(a.persisted()).toEqual(c.persisted())
})
// A LATE ACK. Rule 1 (never re-apply our own echo) is only sound while our optimistic value is
// still on our canvas. Once rule 2's suppression lapses on the TTL and a peer's OLDER mutation
// overwrites it, our echo is the only thing that can restore the value that won everywhere else —
// and rule 1 used to throw it away. Realistic trigger: our socket is backed up with pty output
// (Stage 2 tolerates an 8 MB backlog on that same socket), so our ack takes longer than the TTL.
it('a peer edit applied after the TTL is repaired by our own late ack (no permanent split-brain)', () => {
a.edit([node('n1', 0)])
bus.settle()
bus.stall(a.id) // A's socket backs up: nothing reaches A, but its casts still leave.
b.edit([node('n1', 50)]) // B's edit is cast (and ordered) FIRST…
a.edit([node('n1', 100)]) // …A's is ordered AFTER it, so A's value wins on every other client.
bus.settle()
expect(b.x('n1')).toBe(100) // …and it does: B (and every other client) shows A's 100.
clock += PENDING_TTL_MS + 1 // A's pending entry expires while its inbox is still stalled.
bus.unstall(a.id)
bus.settle() // A now receives B's older mutation, then its OWN echo.
// A must not be left holding the value that lost the total order — its next whole-file
// workspace.save would write those losing bytes over everyone else's canvas.
expect(a.x('n1')).toBe(100)
expect(a.x('n1')).toBe(b.x('n1'))
expect(a.persisted()).toEqual(b.persisted())
})
// THE FIRST HELLO IS NOT A RECONNECT. Canvas resets the ordering state whenever its presence
// clientId changes — including the very first `null → myId`, which lands a few ms after mount.
// A peer's mutation can arrive before that (it is proof of a peer, so we publish), which means one
// of OUR casts can already be in flight when the reset fires. The reset drops `pending` — so the
// peer's mutation is no longer suppressed, and our own echo is no longer recognizable as the
// repair of a value that already won everywhere else. It was dropped, and this client stayed on
// the LOSING value forever (its whole-file save then wrote those bytes over everyone's canvas):
// the permanent split-brain the ordering state exists to prevent, reopened by a lifecycle event.
it('our first presence hello does not lose a cast in flight (the late echo still repairs)', () => {
a.edit([node('n1', 0)])
bus.settle()
b.edit([node('n1', 50)]) // B's edit is cast (and ordered) first…
a.edit([node('n1', 100)]) // …ours is ordered AFTER it, so 100 wins on every other client.
a.presence('cl-a') // …and NOW our own presence hello resolves, with that cast still unacked.
bus.settle()
expect(b.x('n1')).toBe(100) // B lands on the ordered winner…
expect(a.x('n1')).toBe(100) // …and so must we (was: 50 — our echo was thrown away).
expect(a.persisted()).toEqual(b.persisted()) // whoever saves writes the same bytes
})
// …but a GENUINE reconnect must still reset. The core restarting puts its `seq` counter back at 0
// while our `seen` map still holds the old (high) values — every mutation that follows would look
// like a straggler and be silently dropped, and this client would drift away from its peers with
// no way back. (Here: a new clientId, and a peer mutation stamped with a LOW seq from the restarted
// reflector.)
it('a genuine reconnect forgets the stale seq floor (a restarted core starts at seq 1 again)', () => {
a.presence('cl-a')
a.edit([node('n1', 0)])
b.edit([node('n1', 1)])
b.edit([node('n1', 2)])
bus.settle()
expect(a.x('n1')).toBe(2) // a few mutations in: A's `seen` floor for n1 is now high
a.presence('cl-a2') // the core restarted → new connection, new clientId, `seq` back at 0
// The restarted reflector stamps from 1 again. Without the reset this is a straggler and is
// dropped — A would sit on the old value for the rest of the session.
bus.deliver.get(a.id)?.(PROJECT, { op: 'upsert', node: node('n1', 9), src: 'src-2', seq: 1 })
expect(a.x('n1')).toBe(9)
})
// …and a reconnect to the SAME core must not throw away our causal position. The reset fires on
// any new clientId, and the core's `seq` carries on; a first cast stamped `seen: 0` — ⌘Z on a node
// deleted before the drop — is a stale frame to every peer holding the tombstone, and our own echo
// of it is no repair. A persistent split, until the next edit of that node.
it('a re-creation after a same-core reconnect reaches the peer (reset keeps our `seen`)', () => {
a.presence('cl-a')
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
const before = a.states
a.edit(a.states.filter((n) => n.id !== 'n1')) // A deletes n1…
bus.settle() // …and everyone has applied it
a.presence('cl-a2') // the socket dropped and came back: new clientId, same core, `seq` goes on
a.edit(before) // ⌘Z
bus.settle()
expect(b.ids()).toEqual(['n1', 'n2']) // was: ['n2'] — dropped as a stale frame
expect(canon(a)).toEqual(canon(b))
})
// A REFUSED CAST. The reflector drops a malformed / oversized mutation at ingest (silently — there
// is no negative ack). If the publisher has already advanced its baseline it never retries, and if
// the ordering state has already recorded a pending entry the node goes DEAF to its peers for the
// whole TTL. A peer's `remove` landing in that window was dropped and never recovered → the next
// save resurrected the node they deleted. Trigger: a sticky whose body a user pasted a document
// into (sticky text is unbounded in the UI) is over MUTATION_MAX_BYTES.
it('an oversized node the reflector refuses does not deafen it to a peer delete', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
a.edit([fat('n1'), node('n2', 0)]) // A pastes a document into n1 → the cast is refused at ingest
b.edit(b.states.filter((n) => n.id !== 'n1')) // …and B deletes n1 in the same window
bus.settle()
expect(a.ids()).toEqual(b.ids()) // was: A ['n1','n2'] vs B ['n2'] — forever
expect(a.ids()).toEqual(['n2'])
expect(a.persisted()).toEqual(b.persisted())
})
it('a refused cast is retried on the next publish (once the node is within the size limit)', () => {
a.edit([node('n1', 0)])
bus.settle()
a.edit([fat('n1')]) // refused: never reaches B
bus.settle()
expect(b.x('n1')).toBe(0) // B still shows the last mutation that WAS reflected
a.edit([node('n1', 7)]) // the user trims the sticky → the edit is within the limit again
bus.settle()
expect(b.x('n1')).toBe(7)
expect(a.persisted()).toEqual(b.persisted())
})
it('a refused cast does not block the OTHER nodes in the same snapshot', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
a.edit([fat('n1'), node('n2', 42)]) // one refused upsert, one legitimate one
bus.settle()
expect(b.x('n2')).toBe(42)
})
it('a peer delete is not resurrected by the surviving client (the save-safety property)', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
b.edit(b.states.filter((n) => n.id !== 'n1')) // B deletes n1
bus.settle()
// A's canvas — the one that would be written by ITS next whole-file workspace.save — no longer
// carries n1. Before Stage 3, A's save would have written the deleted node straight back.
expect(a.persisted().nodes.map((n) => n.id)).toEqual(['n2'])
expect(a.persisted()).toEqual(b.persisted())
// And A's subsequent edit does not reintroduce it either.
a.edit(a.states.map((n) => (n.id === 'n2' ? node('n2', 3) : n)))
bus.settle()
expect(b.ids()).toEqual(['n2'])
})
})
// ---- boards (kanban) ----
// The board is canvas content too: `.nodeterm/project.json` carries it beside the nodes, so a peer's
// next whole-file save writes whatever board THAT peer holds. Item-level ops ride the same bus, the
// same reflector `seq` and the same order as nodes, under their own `k:` keys (@shared/kanban-ops).
describe('boards converge like nodes (kanban ops)', () => {
const COLS = defaultKanbanFor(PROJECT).columns
const TODO = COLS[0].id
const DOING = COLS[1].id
const DONE = COLS[2].id
/** `board` with `nodeId` filed into `columnId` — a person's drag, as the board computes it. */
const file = (board: ProjectKanban | undefined, nodeId: string, columnId: string): ProjectKanban =>
applyKanbanOp(board, { op: 'kb-card', assignment: { nodeId, columnId } }, PROJECT)
/** What the board UI does to every commit (renderer lib/kanban `pruneAssignments`): drop the cards
* and meta of nodes this client does not hold. A LOCAL, lazy cleanup — never an edit. */
const prune = (board: ProjectKanban, live: string[]): ProjectKanban => ({
...board,
assignments: board.assignments.filter((a) => live.includes(a.nodeId)),
...(board.meta ? { meta: board.meta.filter((m) => live.includes(m.nodeId)) } : {})
})
/** The column a card SHOWS in: its assignment's column when that column exists, else null — the
* virtual Ungrouped column, which holds unassigned AND dangling cards alike. */
const where = (c: Client, nodeId: string): string | null => {
const board = c.board ?? defaultKanbanFor(PROJECT)
const a = board.assignments.find((x) => x.nodeId === nodeId)
return a && board.columns.some((col) => col.id === a.columnId) ? a.columnId : null
}
/** The board as a person sees it: the columns in order, and each column's cards in order. */
const shown = (c: Client) => {
const board = c.board ?? defaultKanbanFor(PROJECT)
return board.columns.map((col) => ({
id: col.id,
title: col.title,
cards: board.assignments.filter((a) => a.columnId === col.id).map((a) => a.nodeId)
}))
}
const kbCast = (c: Client, op: string) => c.cast.filter((m) => m.op === op)
it('1. A and B each move a DIFFERENT card at the same time → both moves land on both', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
a.editBoard(file(file(undefined, 'n1', TODO), 'n2', TODO))
bus.settle()
expect(b.board).toEqual(a.board)
expect(b.cast).toEqual([]) // B applied A's board ops and cast nothing back (never re-published)
// Neither hears the other before it commits: both inboxes stalled, both casts in flight.
bus.stall(1)
bus.stall(2)
a.editBoard(file(a.board, 'n1', DOING))
b.editBoard(file(b.board, 'n2', DONE))
bus.settle()
bus.unstall(1)
bus.unstall(2)
bus.settle()
for (const c of [a, b]) {
expect(where(c, 'n1')).toBe(DOING)
expect(where(c, 'n2')).toBe(DONE)
}
expect(shown(a)).toEqual(shown(b))
})
it('2. A and B move the SAME card concurrently → both end on the higher-seq column', () => {
a.edit([node('n1', 0)])
bus.settle()
a.editBoard(file(undefined, 'n1', TODO))
bus.settle()
a.editBoard(file(a.board, 'n1', DOING)) // cast first → the lower seq
b.editBoard(file(b.board, 'n1', DONE)) // cast second → the higher seq, wins everywhere
bus.settle()
expect(where(a, 'n1')).toBe(DONE)
expect(where(b, 'n1')).toBe(DONE)
expect(shown(a)).toEqual(shown(b))
// …and the other way round.
b.editBoard(file(b.board, 'n1', TODO))
a.editBoard(file(a.board, 'n1', DOING))
bus.settle()
expect(where(a, 'n1')).toBe(DOING)
expect(where(b, 'n1')).toBe(DOING)
})
it('3. a first-ever board edit made by both at once → three columns on both (deterministic ids)', () => {
a.edit([node('n1', 0), node('n2', 0)])
bus.settle()
expect(a.board).toBeUndefined()
expect(b.board).toBeUndefined()
a.editBoard(file(undefined, 'n1', TODO))
b.editBoard(file(undefined, 'n2', DOING))
bus.settle()
for (const c of [a, b]) {
expect(c.board?.columns.map((col) => col.id)).toEqual(COLS.map((col) => col.id))
expect(where(c, 'n1')).toBe(TODO)
expect(where(c, 'n2')).toBe(DOING)
}
// The lazy default is the same board on both, so materializing it casts no column at all — a
// random id per client would have cast three columns each and left six on every board.
expect([...kbCast(a, 'kb-column'), ...kbCast(b, 'kb-column'), ...kbCast(a, 'kb-column-order'), ...kbCast(b, 'kb-column-order')]).toEqual([])
expect(shown(a)).toEqual(shown(b))
})
it('4. B commits a board edit while A’s card for a new node is still in flight → no kb-card-remove, the card placed on both', () => {
a.edit([node('m', 0)])
bus.settle()
a.editBoard(file(undefined, 'm', TODO))
bus.settle()
// A creates n and files its card (the node op leaves first, as the spec's batch order has it);
// neither has reached B.
bus.stall(2)
a.edit([...a.states, node('n', 0)])
a.editBoard(file(a.board, 'n', DOING))
// B, meanwhile, moves m — and prunes, as every board commit does, against its OWN nodes.
b.editBoard(prune(file(b.board, 'm', DONE), b.ids()))
expect(kbCast(b, 'kb-card-remove')).toEqual([])
bus.settle()
bus.unstall(2)
bus.settle()
for (const c of [a, b]) {
expect(where(c, 'n')).toBe(DOING)
expect(where(c, 'm')).toBe(DONE)
}
expect(shown(a)).toEqual(shown(b))
})
// The same rule on the arrival order the live canvas produces: a board write is published the
// moment the store funnel runs, a new node only after React renders it — so a peer can hold the
// CARD of a node it has not received yet. Its commit prunes that card locally (the board UI prunes
// every commit), and the removal is never cast: every replica that did not prune keeps the card.
// The pruning client's own copy is the local, lazy cleanup spec amendment 6 accepts.
it('4b. a card that arrives before its node survives a peer that prunes it (the removal is never cast)', () => {
const c = new Client(3, bus)
bus.clients = [1, 2, 3]
a.edit([node('m', 0)])
bus.settle()
a.editBoard(file(undefined, 'm', TODO))
bus.settle()
a.editBoard(file(a.board, 'n', DOING)) // the card, before the node op has left A
bus.settle()
expect(b.board?.assignments.some((x) => x.nodeId === 'n')).toBe(true) // B holds it, without n
bus.stall(2)
a.edit([...a.states, node('n', 0)]) // the node op, held in B's inbox
b.editBoard(prune(file(b.board, 'm', DONE), b.ids()))
expect(kbCast(b, 'kb-card-remove')).toEqual([]) // the prune stayed local
bus.settle()
bus.unstall(2)
bus.settle()
expect(where(a, 'n')).toBe(DOING)
expect(where(c, 'n')).toBe(DOING)
for (const x of [a, b, c]) expect(where(x, 'm')).toBe(DONE)
})
it('5. A deletes a column while B moves a card into it → the column is gone, the card Ungrouped on both', () => {
for (const bFirst of [false, true]) {
boot()
a.edit([node('n', 0)])
bus.settle()
a.editBoard(file(undefined, 'n', TODO))
bus.settle()
const drop = (board: ProjectKanban): ProjectKanban => ({
...board,
columns: board.columns.filter((col) => col.id !== DONE),
assignments: board.assignments.filter((x) => x.columnId !== DONE)
})
const tag = bFirst ? 'B ordered first' : 'A ordered first'
if (bFirst) b.editBoard(file(b.board, 'n', DONE)) // B had not seen the delete
a.editBoard(drop(a.board!))
if (!bFirst) b.editBoard(file(b.board, 'n', DONE))
bus.settle()
for (const x of [a, b]) {
expect(x.board?.columns.map((col) => col.id), tag).toEqual([TODO, DOING])
expect(where(x, 'n'), tag).toBeNull()
}
expect(shown(a), tag).toEqual(shown(b))
}
})
// Ruling R2: the reflector relays the REPAIRED op and the sender drops its own echo as an ack, so
// the sender must hold the repaired value too — or its board shows a name no peer has.
it('6. an over-long label name lands cut on every board, the sender’s included', () => {
a.editBoard({ ...defaultKanbanFor(PROJECT), labels: [{ id: 'lab-1', name: 'x'.repeat(90), color: 'red' }] })
bus.settle()
expect(a.board?.labels).toEqual([{ id: 'lab-1', name: 'x'.repeat(60), color: 'red' }])
expect(b.board?.labels).toEqual(a.board?.labels)
expect(a.cast.filter((m) => m.op === 'kb-label')).toHaveLength(1) // repaired locally, not re-cast
})
})
// A browser alone on a project the hosted team shares (docs/hosted-team-relay.md). The canvas
// authority is the one writer of that project's content and writes ONLY what it hears as ops, so a
// solo client that kept the old solo gate (publish only with a peer) would edit a canvas that is
// never saved: its whole-workspace save is overlaid with the authority's content.
describe('a solo client on a governed project (the canvas authority)', () => {
afterEach(() => setReflectedListener(null))
const soloWithAuthority = (gate: () => boolean) => {
bus = new Bus()
initPlatform(bus.platform)
initCanvasSync()
const solo = new Client(1, bus, gate)
bus.clients = [1]
const writes: CanvasContent[] = []
const authority = createCanvasAuthority({
sharedProjectIds: () => new Set([PROJECT]),
readContent: async () => ({ nodes: [], bridges: [], ropes: [] }),
writeContent: async (_id, c) => {
writes.push(c)
return true
},
publish: () => {},
setTimer: () => null,
clearTimer: () => {},
log: () => {}
})
setReflectedListener((id, m) => authority.onReflected(id, m))
return { solo, writes, authority }
}
it('with the project governed, the solo edit reaches the authority and is written', async () => {
const { solo, writes, authority } = soloWithAuthority(() => shouldPublishCanvas(false, new Set([PROJECT]), PROJECT))
solo.edit([node('n1', 42)])
solo.editEdges({ bridges: [{ id: 'e1', source: 'n1', target: 'n1' }] })
bus.settle()
await authority.flushAll()
expect(writes).toHaveLength(1)
expect(writes[0].nodes.map((n) => [n.id, n.position.x])).toEqual([['n1', 42]])
expect(writes[0].bridges.map((e) => e.id)).toEqual(['e1'])
await authority.stop()
})
it('with the pre-authority gate (a peer only), nothing is cast and nothing is written', async () => {
const { solo, writes, authority } = soloWithAuthority(() => shouldPublishCanvas(false, new Set<string>(), PROJECT))
solo.edit([node('n1', 42)])
bus.settle()
await authority.flushAll()
expect(bus.castCount).toBe(0)
expect(writes).toEqual([])
await authority.stop()
})
})