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.

feat(core): canvas authority, the single writer of shared projects' content

review753b6140c315
diff --git a/src/core/canvas-authority.test.ts b/src/core/canvas-authority.test.ts
new file mode 100644
index 000000000..3dd5fdc37
--- /dev/null
+++ b/src/core/canvas-authority.test.ts
@@ -0,0 +1,538 @@
+// The Server Edition canvas authority: the one writer of a shared project's content. Every case
+// drives it through its deps only — a manual clock for the flush timers, in-memory maps for the
+// store's read and write, and a publish that can echo back through `onReflected` the way the real
+// reflector does (sanitized, stamped with the next `seq`, synchronously) — and asserts the state
+// that reached the "disk" or came back from an overlay, never the module's internals.
+import { describe, it, expect } from 'vitest'
+import { applyCanvasOp, type CanvasContent } from '../shared/canvas-content'
+import { isCanvasMutation, MUTATION_MAX_BYTES, sanitizeCanvasMutation } from '../shared/canvas-mutations'
+import { defaultKanbanFor } from '../shared/kanban-default-board'
+import type { CanvasMutation, CanvasNodeState, Project, ProjectKanban, Workspace } from '../shared/types'
+import { createCanvasAuthority, type CanvasAuthority, type CanvasAuthorityDeps } from './canvas-authority'
+import type { ContentAuthorityHooks } from './workspace-store'
+
+const node = (id: string, over: Partial<CanvasNodeState> = {}): CanvasNodeState => ({
+ id, kind: 'terminal', position: { x: 0, y: 0 }, size: { width: 100, height: 100 },
+ title: id, color: '#fff', group: null, ...over
+})
+const at = (id: string, x: number, over: Partial<CanvasNodeState> = {}): CanvasNodeState =>
+ node(id, { position: { x, y: 0 }, ...over })
+const content = (nodes: CanvasNodeState[], over: Partial<CanvasContent> = {}): CanvasContent =>
+ ({ nodes, bridges: [], ropes: [], ...over })
+const project = (over: Partial<Project> = {}): Project => ({
+ id: 'P', name: 'foo', color: '#7aa2f7', viewport: { x: 0, y: 0, zoom: 1 }, nodes: [node('a')], ...over
+})
+const ws = (...projects: Project[]): Workspace => ({ version: 2, activeProjectId: projects[0]?.id ?? '', projects })
+const ids = (nodes: Array<{ id: string }>): string[] => nodes.map((n) => n.id)
+const clone = <T>(v: T): T => JSON.parse(JSON.stringify(v)) as T
+const shellOf = (n: CanvasNodeState | undefined): string | undefined => (n as { shell?: string } | undefined)?.shell
+const byId = (nodes: CanvasNodeState[], id: string): CanvasNodeState | undefined => nodes.find((n) => n.id === id)
+
+/** Let every pending promise chain (the fake store's async read/write) run to completion. */
+async function settle(): Promise<void> {
+ for (let i = 0; i < 4; i++) await new Promise<void>((r) => setImmediate(r))
+}
+
+/** A manual clock: `setTimer`/`clearTimer` for the authority, `advanceTo` fires due timers in
+ * order and lets each one's async work finish before the next. */
+function manualClock() {
+ let now = 0
+ let nextId = 1
+ const timers = new Map<number, { at: number; fn: () => void }>()
+ return {
+ get now() {
+ return now
+ },
+ pending: () => timers.size,
+ setTimer: (fn: () => void, ms: number): unknown => {
+ const id = nextId++
+ timers.set(id, { at: now + ms, fn })
+ return id
+ },
+ clearTimer: (t: unknown): void => {
+ timers.delete(t as number)
+ },
+ async advanceTo(t: number): Promise<void> {
+ for (;;) {
+ await settle()
+ let best: [number, { at: number; fn: () => void }] | null = null
+ for (const entry of timers) {
+ if (entry[1].at > t) continue
+ if (!best || entry[1].at < best[1].at || (entry[1].at === best[1].at && entry[0] < best[0])) best = entry
+ }
+ if (!best) break
+ timers.delete(best[0])
+ now = best[1].at
+ best[1].fn()
+ }
+ now = t
+ await settle()
+ },
+ advance(ms: number): Promise<void> {
+ return this.advanceTo(now + ms)
+ }
+ }
+}
+
+interface HarnessOpts {
+ shared?: string[]
+ disk?: Record<string, CanvasContent>
+ /** Answers for successive writes; true once exhausted. */
+ writeResults?: boolean[]
+ /** Echo every published op back through onReflected, as the real reflector listener does. */
+ echo?: boolean
+}
+
+function harness(opts: HarnessOpts = {}) {
+ const clock = manualClock()
+ const shared = new Set(opts.shared ?? ['P'])
+ const disk = new Map<string, CanvasContent>(
+ Object.entries(opts.disk ?? { P: content([node('a')]) }).map(([k, v]) => [k, clone(v)])
+ )
+ const writes: Array<{ id: string; at: number; content: CanvasContent }> = []
+ const published: Array<{ id: string; m: CanvasMutation }> = []
+ const logs: string[] = []
+ const reads: string[] = []
+ const results = [...(opts.writeResults ?? [])]
+ let seq = 0
+ let authority!: CanvasAuthority
+ const deps: CanvasAuthorityDeps = {
+ sharedProjectIds: () => shared,
+ readContent: async (id) => {
+ reads.push(id)
+ const v = disk.get(id)
+ return v ? clone(v) : null
+ },
+ writeContent: async (id, c) => {
+ writes.push({ id, at: clock.now, content: clone(c) })
+ const ok = results.length ? (results.shift() as boolean) : true
+ if (ok) disk.set(id, clone(c))
+ return ok
+ },
+ publish: (id, m) => {
+ published.push({ id, m })
+ if (!opts.echo) return
+ // What publishCanvasMutation does before the reflected listener sees it: refuse what the
+ // wire refuses, sanitize, stamp the next seq of the ONE counter.
+ if (!isCanvasMutation(m)) return
+ const clean = sanitizeCanvasMutation(m)
+ if (clean) authority.onReflected(id, { ...clean, seq: ++seq })
+ },
+ setTimer: clock.setTimer,
+ clearTimer: clock.clearTimer,
+ log: (msg) => logs.push(msg)
+ }
+ authority = createCanvasAuthority(deps)
+ /** A client's cast as the reflector hands it on: stamped with the next seq. */
+ const cast = (m: CanvasMutation, id = 'P'): void => authority.onReflected(id, { ...m, seq: ++seq } as CanvasMutation)
+ return { authority, clock, shared, disk, writes, published, logs, reads, cast, nextSeq: () => ++seq }
+}
+
+describe('canvas authority — governing', () => {
+ it('1. an op for a project that is not shared changes nothing and schedules no write', async () => {
+ const h = harness({ shared: [] })
+ h.cast({ op: 'upsert', node: node('b') })
+ await h.clock.advance(60_000)
+ expect(h.reads).toEqual([])
+ expect(h.writes).toEqual([])
+ expect(h.clock.pending()).toBe(0)
+ const p = project({ nodes: [node('zzz')] })
+ const out = await h.authority.overlaySave(ws(p))
+ expect(out.projects[0]).toBe(p)
+ expect(h.authority.governs('P')).toBe(false)
+ })
+
+ it('2. adopts lazily on the first op: reads the content once, applies the op, writes once', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ h.cast({ op: 'upsert', node: node('b') })
+ await h.clock.advance(1000)
+ expect(h.reads).toEqual(['P'])
+ expect(h.writes).toHaveLength(1)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'b'])
+ })
+
+ it('3. coalesces a burst: 60 upserts of one node in 900 ms, then quiet → one write, last position', async () => {
+ // Disk holds a at -1, so the very first upsert (x=0) is already a change.
+ const h = harness({ disk: { P: content([at('a', -1)]) } })
+ for (let i = 0; i < 60; i++) {
+ await h.clock.advanceTo(i * 15)
+ h.cast({ op: 'upsert', node: at('a', i) })
+ }
+ await h.clock.advance(5000)
+ expect(h.writes).toHaveLength(1)
+ expect(h.writes[0].at).toBe(59 * 15 + 1000)
+ expect(byId(h.writes[0].content.nodes, 'a')?.position.x).toBe(59)
+ })
+
+ it('4. a stream that never goes quiet is still written by the max wait, and again after it ends', async () => {
+ // Disk holds a at -1, so the max-wait window opens on the very first op (t=0).
+ const h = harness({ disk: { P: content([at('a', -1)]) } })
+ for (let t = 0; t <= 7000; t += 500) {
+ await h.clock.advanceTo(t)
+ h.cast({ op: 'upsert', node: at('a', t) })
+ }
+ await h.clock.advance(10_000)
+ expect(h.writes.map((w) => w.at)).toEqual([5000, 8000])
+ expect(h.writes[0].at).toBeLessThan(7000)
+ expect(byId(h.writes[1].content.nodes, 'a')?.position.x).toBe(7000)
+ })
+
+ it('5. applies ops in the total order, including rule 4 (a stale frame cannot resurrect a delete)', async () => {
+ const h = harness({ disk: { P: content([at('a', 1), at('b', 1)]) } })
+ h.authority.onReflected('P', { op: 'remove', id: 'a', seq: 5 })
+ h.authority.onReflected('P', { op: 'upsert', node: at('a', 42), seq: 6, seen: 3 })
+ // …and a straggler below what the order has already seen for b is dropped.
+ h.authority.onReflected('P', { op: 'upsert', node: at('b', 10), seq: 8 })
+ h.authority.onReflected('P', { op: 'upsert', node: at('b', 7), seq: 7 })
+ await h.clock.advance(1000)
+ expect(h.writes).toHaveLength(1)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['b'])
+ expect(byId(h.writes[0].content.nodes, 'b')?.position.x).toBe(10)
+ })
+
+ it('5b. an op carrying any src tag is judged like every other op (none is taken for its own echo)', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ h.authority.onReflected('P', { op: 'upsert', node: node('b'), src: 'canvas-authority', seq: 1 })
+ h.authority.onReflected('P', { op: 'upsert', node: node('c'), src: '', seq: 2 })
+ await h.clock.advance(1000)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'b', 'c'])
+ })
+
+ it('15. a shared project whose content cannot be read stays governed, drops its ops and logs once', async () => {
+ const h = harness({ shared: ['proj-unknown'], disk: {} })
+ h.cast({ op: 'upsert', node: node('b') }, 'proj-unknown')
+ await settle()
+ h.cast({ op: 'upsert', node: node('c') }, 'proj-unknown')
+ await h.clock.advance(10_000)
+ expect(h.writes).toEqual([])
+ expect(h.logs).toHaveLength(1)
+ expect(h.logs[0]).toContain('proj-unknown')
+ expect(h.authority.governs('proj-unknown')).toBe(true)
+ expect(h.authority.governedIds()).toEqual(['proj-unknown'])
+ expect(h.authority.adoptedIds()).toEqual([])
+ })
+})
+
+describe('canvas authority — save and load overlays', () => {
+ it('6. a stale save cannot revert content, and still carries everything else', async () => {
+ const h = harness({ disk: { P: content([at('a', 0)]) } })
+ h.cast({ op: 'upsert', node: at('a', 10) })
+ await settle()
+ const out = await h.authority.overlaySave(ws(project({ name: 'Renamed', nodes: [at('a', 0)] })))
+ expect(out.projects[0].name).toBe('Renamed')
+ expect(out.projects[0].nodes).toHaveLength(1)
+ expect(byId(out.projects[0].nodes, 'a')?.position.x).toBe(10)
+ })
+
+ it('6b. an empty edge list adds no key the save lacked, and keeps the one it carried', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ const out = await h.authority.overlaySave(ws(project()))
+ expect('bridges' in out.projects[0]).toBe(false)
+ expect('ropes' in out.projects[0]).toBe(false)
+ const out2 = await h.authority.overlaySave(ws(project({ bridges: [{ id: 'stale', source: 'a', target: 'a' }], ropes: [] })))
+ expect(out2.projects[0].bridges).toEqual([])
+ expect(out2.projects[0].ropes).toEqual([])
+ })
+
+ it('7. carries this machine\'s exec fields from the save onto the overlay; the state keeps none', async () => {
+ const h = harness({ disk: { P: content([at('a', 0)]) } })
+ const out = await h.authority.overlaySave(ws(project({ nodes: [at('a', 0, { shell: '/bin/zsh' })] })))
+ expect(shellOf(byId(out.projects[0].nodes, 'a'))).toBe('/bin/zsh')
+ h.cast({ op: 'upsert', node: node('b') })
+ await h.clock.advance(1000)
+ expect(h.writes).toHaveLength(1)
+ expect(shellOf(byId(h.writes[0].content.nodes, 'a'))).toBeUndefined()
+ })
+
+ it('8. the board is field-level: items from the authority, github from the save', async () => {
+ const c1 = { id: 'c1', title: 'One', color: '#fff' }
+ const c9 = { id: 'c9', title: 'Nine', color: '#000' }
+ const diskBoard = { columns: [c1], assignments: [], github: { repository: 'disk/x', columnMappings: [] } } as ProjectKanban
+ const h = harness({ disk: { P: content([node('a')], { kanban: diskBoard }) } })
+ const saved = { columns: [c9], assignments: [], github: { repository: 'a/b', columnMappings: [] } } as ProjectKanban
+ const out = await h.authority.overlaySave(ws(project({ kanban: saved })))
+ expect(out.projects[0].kanban).toEqual({
+ columns: [c1], assignments: [], github: { repository: 'a/b', columnMappings: [] }
+ })
+ })
+
+ it('8b. with no board of its own, the save\'s github rides on the project\'s lazy default board', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ const github = { repository: 'a/b', columnMappings: [] }
+ const saved = { columns: [{ id: 'c9', title: 'Nine', color: '#000' }], assignments: [], github } as ProjectKanban
+ const out = await h.authority.overlaySave(ws(project({ kanban: saved })))
+ expect(out.projects[0].kanban).toEqual({ ...defaultKanbanFor('P'), github })
+ // …and with neither a board nor a config, the save's board items do not survive.
+ const out2 = await h.authority.overlaySave(ws(project({ kanban: { columns: [], assignments: [] } })))
+ expect(out2.projects[0].kanban).toBeUndefined()
+ expect('kanban' in out2.projects[0]).toBe(false)
+ })
+
+ it('9. a node too large to travel as an op is adopted from the save and written', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ const big = node('big', { kind: 'sticky', text: 'x'.repeat(MUTATION_MAX_BYTES + 10) })
+ expect(isCanvasMutation({ op: 'upsert', node: big })).toBe(false)
+ const out = await h.authority.overlaySave(ws(project({ nodes: [node('a'), big] })))
+ expect(ids(out.projects[0].nodes)).toEqual(['a', 'big'])
+ expect(byId(out.projects[0].nodes, 'big')?.text).toBe(big.text)
+ await h.clock.advance(1000)
+ expect(h.writes).toHaveLength(1)
+ expect(byId(h.writes[0].content.nodes, 'big')?.text).toBe(big.text)
+ })
+
+ it('9b. two identical saves of an unchanged big node write once, and the state keeps no exec', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ const big = node('big', { kind: 'sticky', text: 'y'.repeat(MUTATION_MAX_BYTES + 10), shell: '/bin/zsh' })
+ const out = await h.authority.overlaySave(ws(project({ nodes: [node('a'), clone(big)] })))
+ expect(shellOf(byId(out.projects[0].nodes, 'big'))).toBe('/bin/zsh') // carried onto the overlay
+ await h.clock.advance(1000)
+ await h.authority.overlaySave(ws(project({ nodes: [node('a'), clone(big)] })))
+ await h.clock.advance(10_000)
+ expect(h.writes).toHaveLength(1)
+ expect(shellOf(byId(h.writes[0].content.nodes, 'big'))).toBeUndefined()
+ })
+
+ it('10. a load is overlaid with the unflushed state', async () => {
+ const h = harness({ disk: { P: content([at('a', 0)]) } })
+ h.cast({ op: 'upsert', node: at('a', 10) })
+ await settle()
+ expect(h.writes).toEqual([])
+ const out = await h.authority.overlayLoad(ws(project({ nodes: [at('a', 0)] })))
+ expect(byId(out.projects[0].nodes, 'a')?.position.x).toBe(10)
+ })
+
+ it('an unavailable placeholder, a relay tab and an SSH project are never overlaid, and never seed the state', async () => {
+ const h = harness({ disk: { P: content([node('a'), node('b')]) } })
+ const placeholder = project({ nodes: [], unavailable: true })
+ const loaded = await h.authority.overlayLoad(ws(placeholder))
+ expect(loaded.projects[0]).toBe(placeholder)
+ const relay = project({ nodes: [], remote: true })
+ expect((await h.authority.overlaySave(ws(relay))).projects[0]).toBe(relay)
+ const ssh = project({ nodes: [], ssh: { server: { host: 'h' }, remoteCwd: '~' } as unknown as Project['ssh'] })
+ expect((await h.authority.overlayLoad(ws(ssh))).projects[0]).toBe(ssh)
+ h.cast({ op: 'upsert', node: node('c') })
+ await h.clock.advance(1000)
+ expect(h.reads).toEqual(['P'])
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'b', 'c'])
+ })
+
+ it('satisfies the store\'s ContentAuthorityHooks', () => {
+ const hooks: ContentAuthorityHooks = harness().authority
+ expect(typeof hooks.overlaySave).toBe('function')
+ })
+})
+
+describe('canvas authority — outside edits', () => {
+ it('11. adopts the outside edit, re-applies unflushed ops on top, publishes the difference, writes once', async () => {
+ const h = harness({ disk: { P: content([node('a'), node('b')]) } })
+ h.cast({ op: 'upsert', node: node('c') })
+ await settle()
+ expect(h.writes).toEqual([])
+ await h.authority.adoptOutsideEdit(project({ nodes: [node('a'), node('d')] }))
+ const ops = h.published.map((p) => p.m)
+ expect(ops).toEqual([{ op: 'upsert', node: node('d') }, { op: 'remove', id: 'b' }])
+ // The ops turn every client's old state into the new one.
+ let replica = content([node('a'), node('b'), node('c')])
+ for (const m of ops) replica = applyCanvasOp(replica, m, 'P')
+ expect(ids(replica.nodes).sort()).toEqual(['a', 'c', 'd'])
+ await h.clock.advance(10_000)
+ expect(h.writes).toHaveLength(1)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'd', 'c'])
+ })
+
+ it('11b. an outside edit alone (nothing unflushed) publishes its difference and writes nothing', async () => {
+ const h = harness({ disk: { P: content([node('a'), node('b')]) } })
+ await h.authority.overlayLoad(ws(project({ nodes: [node('a'), node('b')] })))
+ await h.authority.adoptOutsideEdit(project({ nodes: [node('a'), node('d')] }))
+ expect(h.published.map((p) => p.m.op)).toEqual(['upsert', 'remove'])
+ await h.clock.advance(10_000)
+ expect(h.writes).toEqual([])
+ })
+
+ it('11c. the echo of its own published diff is a no-op, and the order still judges later ops', async () => {
+ const h = harness({ disk: { P: content([node('a'), node('b')]) }, echo: true })
+ await h.authority.overlayLoad(ws(project({ nodes: [node('a'), node('b')] })))
+ const extra = { id: 'kx', title: 'Extra', color: '#fff' }
+ const board: ProjectKanban = {
+ columns: [...defaultKanbanFor('P').columns, extra],
+ assignments: [{ nodeId: 'a', columnId: 'kx' }]
+ }
+ const edited = project({
+ nodes: [node('a'), at('d', 5)],
+ bridges: [{ id: 'e1', source: 'a', target: 'd' }],
+ kanban: board
+ })
+ await h.authority.adoptOutsideEdit(edited)
+ const ops = h.published.map((p) => p.m)
+ expect(ops.map((m) => m.op)).toEqual(['upsert', 'edge-upsert', 'kb-column', 'kb-column-order', 'kb-card', 'remove'])
+ // Bare ops: valid on the wire, and nothing that would make the order take their echo for an ack.
+ for (const m of ops) {
+ expect(isCanvasMutation(m)).toBe(true)
+ expect(m.src).toBeUndefined()
+ expect(m.seq).toBeUndefined()
+ }
+ await h.clock.advance(10_000)
+ expect(h.writes).toEqual([]) // the echoes changed nothing, so nothing is dirty
+ // A later op for the same node applies…
+ h.cast({ op: 'upsert', node: at('d', 50) })
+ // …and a straggler ordered before the echo does not.
+ h.authority.onReflected('P', { op: 'upsert', node: at('d', 99), seq: 1 })
+ await h.clock.advance(10_000)
+ expect(h.writes).toHaveLength(1)
+ expect(byId(h.writes[0].content.nodes, 'd')?.position.x).toBe(50)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'd'])
+ expect(h.writes[0].content.bridges).toEqual([{ id: 'e1', source: 'a', target: 'd' }])
+ expect(h.writes[0].content.kanban?.assignments).toEqual([{ nodeId: 'a', columnId: 'kx' }])
+ })
+
+ it('11d. an unavailable or relay project is never adopted as an outside edit', async () => {
+ const h = harness({ disk: { P: content([node('a'), node('b')]) } })
+ await h.authority.overlayLoad(ws(project({ nodes: [node('a'), node('b')] })))
+ await h.authority.adoptOutsideEdit(project({ nodes: [], unavailable: true }))
+ await h.authority.adoptOutsideEdit(project({ nodes: [], remote: true }))
+ expect(h.published).toEqual([])
+ h.cast({ op: 'upsert', node: node('c') })
+ await h.clock.advance(1000)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'b', 'c'])
+ })
+
+ it('11e. a project shared after boot is adopted at share time, so an outside edit has a baseline', async () => {
+ const h = harness({ shared: [], disk: { P: content([node('a'), node('b')]) } })
+ h.shared.add('P')
+ h.authority.sharedChanged()
+ await settle()
+ expect(h.reads).toEqual(['P'])
+ expect(h.authority.adoptedIds()).toEqual(['P'])
+ // The store records the re-read before it hands the project over, so from here a read answers
+ // the NEW content — a baseline taken now would see no difference at all.
+ h.disk.set('P', content([node('a')]))
+ await h.authority.adoptOutsideEdit(project({ nodes: [node('a')] }))
+ expect(h.published.map((p) => p.m)).toEqual([{ op: 'remove', id: 'b' }])
+ })
+})
+
+describe('canvas authority — exec stays out of the state (R9)', () => {
+ it('a read that carries this machine\'s shell is stripped: never written, and a sanitized echo is a no-op', async () => {
+ const h = harness({ disk: { P: content([node('a', { shell: '/bin/zsh' })]) } })
+ h.cast({ op: 'upsert', node: node('b') })
+ await h.clock.advance(1000)
+ expect(h.writes).toHaveLength(1)
+ expect(shellOf(byId(h.writes[0].content.nodes, 'a'))).toBeUndefined()
+ h.cast({ op: 'upsert', node: node('a') }) // what the reflector sends for a: sanitized
+ await h.clock.advance(10_000)
+ expect(h.writes).toHaveLength(1)
+ })
+
+ it('a load seed that carries a shell is stripped, while the load result keeps it', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ const out = await h.authority.overlayLoad(ws(project({ nodes: [node('a', { shell: '/bin/zsh' })] })))
+ expect(shellOf(byId(out.projects[0].nodes, 'a'))).toBe('/bin/zsh')
+ h.cast({ op: 'upsert', node: node('b') })
+ await h.clock.advance(1000)
+ expect(h.reads).toEqual([])
+ expect(shellOf(byId(h.writes[0].content.nodes, 'a'))).toBeUndefined()
+ })
+
+ it('an outside edit that carries a shell publishes no spurious change for that node', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ await h.authority.overlayLoad(ws(project({ nodes: [node('a')] })))
+ await h.authority.adoptOutsideEdit(project({ nodes: [node('a', { shell: '/bin/zsh' })] }))
+ expect(h.published).toEqual([])
+ await h.clock.advance(10_000)
+ expect(h.writes).toEqual([])
+ })
+})
+
+describe('canvas authority — flushing and lifecycle', () => {
+ it('12. a failed write keeps the state (and its unflushed ops) and retries on the backoff schedule', async () => {
+ const h = harness({ disk: { P: content([node('a')]) }, writeResults: [false, false, true] })
+ h.cast({ op: 'upsert', node: node('b') })
+ await h.clock.advanceTo(2500) // write 1 at 1000 fails, write 2 at 2000 fails
+ expect(h.writes.map((w) => w.at)).toEqual([1000, 2000])
+ // An outside edit between failures: the ops never written must survive it.
+ h.disk.set('P', content([node('a'), node('x')]))
+ await h.authority.adoptOutsideEdit(project({ nodes: [node('a'), node('x')] }))
+ // An op during the backoff does not arm the quiet timer: the retry owns the next attempt, so a
+ // failing disk is not written once per quiet period (it would be at 3600 here).
+ await h.clock.advanceTo(2600)
+ h.cast({ op: 'upsert', node: node('c') })
+ await h.clock.advance(60_000)
+ expect(h.writes.map((w) => w.at)).toEqual([1000, 2000, 4000])
+ expect(ids(h.writes[2].content.nodes)).toEqual(['a', 'x', 'b', 'c'])
+ expect(h.logs).toHaveLength(2) // one per failed write
+ })
+
+ it('13. unsharing flushes the pending state once, then releases the project', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ h.cast({ op: 'upsert', node: node('b') })
+ await settle()
+ h.shared.delete('P')
+ h.authority.sharedChanged()
+ await settle()
+ expect(h.writes).toHaveLength(1)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'b'])
+ expect(h.authority.governs('P')).toBe(false)
+ expect(h.authority.governedIds()).toEqual([])
+ expect(h.authority.adoptedIds()).toEqual([])
+ h.cast({ op: 'upsert', node: node('c') })
+ await h.clock.advance(60_000)
+ expect(h.writes).toHaveLength(1)
+ expect(h.reads).toEqual(['P'])
+ })
+
+ it('13b. governedIds lists every shared project, adopted or not; adoptedIds only the adopted ones', async () => {
+ const h = harness({ shared: ['P', 'Q'], disk: { P: content([node('a')]), Q: content([node('q')]) } })
+ h.cast({ op: 'upsert', node: node('b') })
+ await settle()
+ expect([...h.authority.governedIds()].sort()).toEqual(['P', 'Q'])
+ expect(h.authority.adoptedIds()).toEqual(['P'])
+ expect(h.authority.governs('Q')).toBe(true)
+ })
+
+ it('13c. an unshared project whose write fails keeps retrying, and is released once it lands', async () => {
+ const h = harness({ disk: { P: content([node('a')]) }, writeResults: [false] })
+ h.cast({ op: 'upsert', node: node('b') })
+ await settle()
+ h.shared.delete('P')
+ h.authority.sharedChanged()
+ await settle()
+ expect(h.writes).toHaveLength(1)
+ await h.clock.advance(1000) // the retry
+ expect(h.writes).toHaveLength(2)
+ expect(ids(h.writes[1].content.nodes)).toEqual(['a', 'b'])
+ // Released: sharing it again starts from a fresh read, not from the old state.
+ h.disk.set('P', content([node('z')]))
+ h.shared.add('P')
+ h.cast({ op: 'upsert', node: node('c') })
+ await h.clock.advance(1000)
+ expect(h.reads).toEqual(['P', 'P'])
+ expect(ids(h.writes[2].content.nodes)).toEqual(['z', 'c'])
+ })
+
+ it('14. stop() resolves after the pending write; ops after it are ignored', async () => {
+ const h = harness({ disk: { P: content([node('a')]) } })
+ h.cast({ op: 'upsert', node: node('b') })
+ await settle()
+ await h.authority.stop()
+ expect(h.writes).toHaveLength(1)
+ expect(ids(h.writes[0].content.nodes)).toEqual(['a', 'b'])
+ expect(h.authority.governs('P')).toBe(false)
+ expect(h.authority.governedIds()).toEqual([])
+ h.cast({ op: 'upsert', node: node('c') })
+ await h.clock.advance(60_000)
+ expect(h.writes).toHaveLength(1)
+ expect(h.clock.pending()).toBe(0)
+ })
+
+ it('flushAll writes every dirty project now, without waiting for the quiet period', async () => {
+ const h = harness({ shared: ['P', 'Q'], disk: { P: content([node('a')]), Q: content([node('q')]) } })
+ h.cast({ op: 'upsert', node: node('b') })
+ h.cast({ op: 'upsert', node: node('r') }, 'Q')
+ await h.authority.flushAll()
+ expect(h.writes.map((w) => [w.id, ids(w.content.nodes)]).sort()).toEqual([
+ ['P', ['a', 'b']],
+ ['Q', ['q', 'r']]
+ ])
+ expect(h.writes.every((w) => w.at === 0)).toBe(true)
+ })
+})
diff --git a/src/core/canvas-authority.ts b/src/core/canvas-authority.ts
new file mode 100644
index 000000000..3de8d8cff
--- /dev/null
+++ b/src/core/canvas-authority.ts
@@ -0,0 +1,440 @@
+// The Server Edition canvas authority: for every project shared with a hosted team, the ONE writer
+// of its content (nodes, bridges, ropes and board items). Clients send ops, never content. This
+// module applies those ops in the reflector's total order through the same reducer every client
+// uses, overlays its state onto whole-workspace saves and loads (so a stale copy can never write
+// content back), adopts outside edits by publishing the difference as ops, and flushes through the
+// store's atomic content write. No electron and no ws: the Server Edition shell wires it
+// (docs/hosted-team-relay.md).
+//
+// What its state is, precisely: the fold of the total order over the content it adopted, plus the
+// two non-op inputs it accepts (an outside edit, and a node too large to ever travel as an op).
+// Four rules keep that honest:
+//
+// 1. ITS STATE CARRIES NO EXEC FIELDS. `shell` and `ssh.extraArgs` are machine-local
+// (@shared/node-exec): every op is sanitized before it is reflected, but a store read re-applies
+// this machine's values, so content entering from anywhere but an op is stripped on the way in
+// (`governedContent`). Unstripped state would differ from every sanitized echo and publish
+// spurious diffs. Exec reaches a save or a load only through `carryLocalNodeExec`, from the
+// copy the save or load itself carried.
+//
+// 2. ITS OWN PUBLISHED OPS ARE ORDINARY OPS. The diff an outside edit publishes goes out bare (no
+// `src`, no `seen`), is stamped by the reflector and comes back through `onReflected` like any
+// client's cast. It is applied, and it changes nothing, because the content is already there.
+// Treating it as "our own echo" instead would diverge from the clients the moment an older op
+// landed between the publish and the echo: the clients end on the published value (it has the
+// higher seq), and an authority that dropped its echo would keep the older one.
+//
+// 3. ONLY A WRITE THAT LANDED RETIRES AN OP. `unflushed` holds every op applied since the last
+// successful write, and a failed write keeps them all. They are re-applied on top of an outside
+// edit, because disk has the edit and not them.
+//
+// 4. A FAILED READ GOVERNS NOTHING. A shared project whose content cannot be read keeps `governs`
+// true (the clients must keep publishing), drops its ops, and says so once.
+
+import { applyCanvasOp, contentOf, diffContent, type CanvasContent } from '../shared/canvas-content'
+import { isCanvasMutation } from '../shared/canvas-mutations'
+import { createCanvasOrder } from '../shared/canvas-order'
+import { defaultKanbanFor } from '../shared/kanban-default-board'
+import { carryLocalNodeExec, stripSharedNodeExec } from '../shared/node-exec'
+import type { BridgeLink, CanvasMutation, CanvasNodeState, Project, ProjectKanban, Workspace } from '../shared/types'
+
+export interface CanvasAuthorityDeps {
+ /** The projects shared with the hosted team right now. Read on every call, never cached. */
+ sharedProjectIds(): ReadonlySet<string>
+ /** A project's content as the store knows it (null = unknown, SSH, or unreadable). Must not queue
+ * behind a save: the save overlay calls it from inside one. */
+ readContent(projectId: string): Promise<CanvasContent | null>
+ /** Write a project's content atomically. false = nothing was written. */
+ writeContent(projectId: string, content: CanvasContent): Promise<boolean>
+ /** Cast one op to every client (the reflector stamps its seq and echoes it back here). */
+ publish(projectId: string, m: CanvasMutation): void
+ /** Quiet period before a flush. Default 1000. */
+ quietMs?: number
+ /** Longest a dirty project waits for a flush while ops keep arriving. Default 5000. */
+ maxWaitMs?: number
+ /** Backoff before retry number `attempt` (0-based). Default min(30000, 1000 * 2 ** attempt). */
+ retryMs?: (attempt: number) => number
+ setTimer?: (fn: () => void, ms: number) => unknown
+ clearTimer?: (t: unknown) => void
+ log?: (msg: string) => void
+}
+
+export interface CanvasAuthority {
+ /** Is this project's content written by the authority? Shared and not stopped; true before the
+ * project is first adopted, and true even when its content cannot be read. */
+ governs(projectId: string): boolean
+ /** Every project `governs` answers true for, adopted or not (a client needs this before first
+ * contact, to know it must publish). */
+ governedIds(): string[]
+ /** The governed projects whose content the authority holds right now. */
+ adoptedIds(): string[]
+ /** One op, as the reflector stamped it, in the reflector's order. */
+ onReflected(projectId: string, m: CanvasMutation): void
+ /** Governed projects' content fields replaced by the authority's (the store's save hook). */
+ overlaySave(ws: Workspace): Promise<Workspace>
+ /** Governed projects' content fields replaced by the authority's (the store's load hook). */
+ overlayLoad(ws: Workspace): Promise<Workspace>
+ /** A project re-read after an outside edit (a git pull, a hand edit). */
+ adoptOutsideEdit(project: Project): Promise<void>
+ /** The shared set changed: flush and release what left it, adopt what joined it. */
+ sharedChanged(): void
+ /** Write every dirty project now. */
+ flushAll(): Promise<void>
+ /** Stop governing, after writing what is pending. Later ops are ignored. */
+ stop(): Promise<void>
+}
+
+interface Governed {
+ content: CanvasContent
+ /** Ops applied since the last successful write, re-applied on top of an outside edit. */
+ unflushed: CanvasMutation[]
+ /** The content differs from what is on disk. What `flush` keys on, not `unflushed.length`. */
+ dirty: boolean
+ quietTimer: unknown
+ maxTimer: unknown
+ retryTimer: unknown
+ attempt: number
+ flushing: Promise<void> | null
+}
+
+/**
+ * The order's own tag. EMPTY on purpose: the reflector strips every `src` that is not a ref id
+ * (`stampMutation`), and `accept` compares with `m.src && m.src === src`, so no reflected op,
+ * honest or forged, is ever taken for this authority's own echo (rule 2 in the header). It never
+ * calls `onLocal`, so for it the order is exactly "highest seq wins per key" plus rule 4's causal
+ * delete, the same verdicts every client reaches.
+ */
+const AUTHORITY_ORDER_TAG = ''
+
+/** Content entering the state from anything but an op, with the exec fields stripped (rule 1). */
+function governedContent(c: Pick<Project, 'nodes' | 'bridges' | 'ropes' | 'kanban'>): CanvasContent {
+ const x = contentOf(c)
+ return { ...x, nodes: stripSharedNodeExec(x.nodes) }
+}
+
+/** A node that can never travel as an op: the same verdict the reflector and the publisher reach. */
+const tooLargeToSync = (node: CanvasNodeState): boolean => !isCanvasMutation({ op: 'upsert', node })
+
+/** A project an overlay may rewrite. A relay tab is another machine's project, an unavailable
+ * placeholder's empty node list is not content, and an SSH project's file lives on another host
+ * (the store neither reads nor writes its content). */
+const overlayable = (p: Project): boolean => !p.remote && !p.unavailable && !p.ssh
+
+const isObject = (v: unknown): v is CanvasNodeState => !!v && typeof v === 'object'
+
+/** An edge list for an overlaid project: the authority's, except that an EMPTY list adds no key the
+ * incoming project lacked. The store's content write applies the same rule, for the same reason: a
+ * `"bridges": []` in a file nobody drew a link in is a diff nobody made. */
+const edgeList = (mine: BridgeLink[], theirs: BridgeLink[] | undefined): BridgeLink[] | undefined =>
+ mine.length || theirs !== undefined ? mine : undefined
+
+/** The board configuration a save or load carries: the two keys outside the op vocabulary. */
+function boardConfig(b: ProjectKanban | undefined): Pick<ProjectKanban, 'github' | 'pullLinks'> | undefined {
+ if (!b || typeof b !== 'object') return undefined
+ const out: Pick<ProjectKanban, 'github' | 'pullLinks'> = {}
+ if (b.github !== undefined) out.github = b.github
+ if (b.pullLinks !== undefined) out.pullLinks = b.pullLinks
+ return out.github !== undefined || out.pullLinks !== undefined ? out : undefined
+}
+
+/**
+ * Field-level board overlay: the ITEMS (columns, cards, meta, labels, views) from the authority,
+ * `github` and `pullLinks` from the incoming project, which owns them. With no board of its own,
+ * the incoming configuration rides on the project's lazy default board; with neither, no board.
+ */
+function overlayKanban(
+ projectId: string,
+ incoming: ProjectKanban | undefined,
+ mine: ProjectKanban | undefined
+): ProjectKanban | undefined {
+ const config = boardConfig(incoming)
+ if (!mine && !config) return undefined
+ const { github: _g, pullLinks: _p, ...items } = mine ?? defaultKanbanFor(projectId)
+ return { ...items, ...config }
+}
+
+function setOrDelete<K extends 'bridges' | 'ropes' | 'kanban'>(p: Project, key: K, value: Project[K] | undefined): void {
+ if (value === undefined) delete p[key]
+ else p[key] = value
+}
+
+export function createCanvasAuthority(deps: CanvasAuthorityDeps): CanvasAuthority {
+ const quietMs = deps.quietMs ?? 1000
+ const maxWaitMs = deps.maxWaitMs ?? 5000
+ const retryMs = deps.retryMs ?? ((attempt: number) => Math.min(30_000, 1000 * 2 ** attempt))
+ const setTimer = deps.setTimer ?? ((fn: () => void, ms: number): unknown => setTimeout(fn, ms))
+ const clearTimer = deps.clearTimer ?? ((t: unknown) => clearTimeout(t as ReturnType<typeof setTimeout>))
+ const log = deps.log ?? ((msg: string) => console.warn(`[canvas-authority] ${msg}`))
+
+ const order = createCanvasOrder(AUTHORITY_ORDER_TAG)
+ const governed = new Map<string, Governed>()
+ /** Adoptions waiting on `readContent`. Seeded adoptions (a load) are synchronous and never here. */
+ const adopting = new Map<string, Promise<Governed | null>>()
+ /** Ops the order accepted for a project whose adoption has not finished, in order. */
+ const queued = new Map<string, CanvasMutation[]>()
+ /** Projects whose unreadable content was already reported (rule 4 says so once). */
+ const warned = new Set<string>()
+ let stopped = false
+
+ const isShared = (id: string): boolean => deps.sharedProjectIds().has(id)
+ const governs = (id: string): boolean => !stopped && isShared(id)
+
+ function clearTimers(g: Governed): void {
+ for (const t of [g.quietTimer, g.maxTimer, g.retryTimer]) if (t) clearTimer(t)
+ g.quietTimer = g.maxTimer = g.retryTimer = null
+ }
+
+ /** Arm the flush timers. While a retry is pending, the backoff owns the next attempt: a burst of
+ * ops must not turn a failing disk into one write per quiet period. */
+ function schedule(id: string, g: Governed): void {
+ if (stopped || g.retryTimer) return
+ if (g.quietTimer) clearTimer(g.quietTimer)
+ g.quietTimer = setTimer(() => {
+ g.quietTimer = null
+ void flush(id)
+ }, quietMs)
+ if (!g.maxTimer) {
+ g.maxTimer = setTimer(() => {
+ g.maxTimer = null
+ void flush(id)
+ }, maxWaitMs)
+ }
+ }
+
+ function markDirty(id: string, g: Governed): void {
+ g.dirty = true
+ schedule(id, g)
+ }
+
+ /** Apply one op. Nothing changes, and nothing is marked dirty, when the reducer answers the SAME
+ * object: a duplicate, an echo of the authority's own diff, an unchanged big node from a save. */
+ function applyTo(id: string, g: Governed, m: CanvasMutation): void {
+ const next = applyCanvasOp(g.content, m, id)
+ if (next === g.content) return
+ g.content = next
+ g.unflushed.push(m)
+ markDirty(id, g)
+ }
+
+ /** Stop holding a project that left the shared set, once nothing it holds is still unwritten. */
+ function release(id: string, g: Governed): void {
+ if (isShared(id) || g.dirty || g.flushing || governed.get(id) !== g) return
+ clearTimers(g)
+ governed.delete(id)
+ }
+
+ function install(id: string, content: CanvasContent | null): Governed | null {
+ const pending = queued.get(id) ?? []
+ queued.delete(id)
+ // Unshared while the read was in flight: its ops were accepted while it was shared, but the
+ // clients' whole-workspace saves carry them again now that nothing governs the project.
+ if (!isShared(id)) return null
+ if (!content) {
+ if (!warned.has(id)) {
+ warned.add(id)
+ log(`project ${id} is shared, but its content could not be read; its canvas edits are not written until it can be`)
+ }
+ return null
+ }
+ warned.delete(id)
+ const g: Governed = {
+ content: governedContent(content),
+ unflushed: [],
+ dirty: false,
+ quietTimer: null,
+ maxTimer: null,
+ retryTimer: null,
+ attempt: 0,
+ flushing: null
+ }
+ governed.set(id, g)
+ for (const m of pending) applyTo(id, g, m)
+ return g
+ }
+
+ /** The governed state of a project, adopting it on first contact. `seed` (a load result) IS the
+ * disk state, so it adopts without a second read. */
+ function adopt(id: string, seed?: CanvasContent): Promise<Governed | null> {
+ const have = governed.get(id)
+ if (have) return Promise.resolve(have)
+ const inflight = adopting.get(id)
+ if (inflight) return inflight
+ if (seed) return Promise.resolve(install(id, seed))
+ // `.then` starts the read on a later tick, so the entry is in `adopting` before it can settle.
+ const run = Promise.resolve()
+ .then(() => deps.readContent(id))
+ .catch((): CanvasContent | null => null)
+ .then((content) => {
+ adopting.delete(id)
+ return install(id, content)
+ })
+ adopting.set(id, run)
+ return run
+ }
+
+ async function write(id: string, content: CanvasContent): Promise<boolean> {
+ try {
+ return (await deps.writeContent(id, content)) === true
+ } catch {
+ return false
+ }
+ }
+
+ function flush(id: string): Promise<void> {
+ const g = governed.get(id)
+ if (!g) return Promise.resolve()
+ if (g.flushing) return g.flushing
+ if (!g.dirty) {
+ release(id, g)
+ return Promise.resolve()
+ }
+ clearTimers(g)
+ const snapshot = g.content
+ const written = g.unflushed.length
+ g.dirty = false
+ const run = write(id, snapshot).then((ok) => {
+ g.flushing = null
+ if (ok) {
+ g.unflushed.splice(0, written)
+ g.attempt = 0
+ // Anything applied while the write was in flight is still owed.
+ if (g.dirty) schedule(id, g)
+ else release(id, g)
+ return
+ }
+ // Rule 3: keep the content and every unflushed op, and try again later.
+ g.dirty = true
+ clearTimers(g)
+ const wait = retryMs(g.attempt++)
+ log(`writing project ${id} failed; its content is kept and the write is retried in ${wait} ms`)
+ if (!stopped) {
+ g.retryTimer = setTimer(() => {
+ g.retryTimer = null
+ void flush(id)
+ }, wait)
+ }
+ })
+ g.flushing = run
+ return run
+ }
+
+ /** Wait for a write in flight, then write whatever is still dirty (a pending retry included). */
+ async function drain(id: string): Promise<void> {
+ const inflight = governed.get(id)?.flushing
+ if (inflight) await inflight
+ if (governed.get(id)?.dirty) await flush(id)
+ }
+
+ function overlayProject(p: Project, g: Governed, mode: 'save' | 'load'): Project {
+ const theirs = Array.isArray(p.nodes) ? p.nodes.filter(isObject) : []
+ if (mode === 'save') {
+ // The one node a save may contribute: one that can never travel as an op. It enters as a
+ // synthetic upsert, so the reducer strips its exec fields (rule 1), an unchanged copy is a
+ // no-op (two saves of one big sticky write once), and an outside edit re-applies it.
+ for (const n of theirs) if (tooLargeToSync(n)) applyTo(p.id, g, { op: 'upsert', node: n })
+ }
+ // This machine's exec fields live on the incoming copy (and in the index's localExec); carry
+ // them onto the authority's nodes, or the save would drop them from the index.
+ const incoming = new Map(theirs.map((n) => [n.id, n]))
+ const nodes = g.content.nodes.map((n) => {
+ const local = incoming.get(n.id)
+ return local ? carryLocalNodeExec(local, n) : n
+ })
+ const out: Project = { ...p, nodes }
+ setOrDelete(out, 'bridges', edgeList(g.content.bridges, p.bridges))
+ setOrDelete(out, 'ropes', edgeList(g.content.ropes, p.ropes))
+ setOrDelete(out, 'kanban', overlayKanban(p.id, p.kanban, g.content.kanban))
+ return out
+ }
+
+ return {
+ governs,
+
+ governedIds: () => (stopped ? [] : [...deps.sharedProjectIds()]),
+
+ adoptedIds: () => [...governed.keys()].filter(governs),
+
+ onReflected(id: string, m: CanvasMutation): void {
+ if (!governs(id)) return
+ // Every op of a governed project is judged in order, adopted or not, so the verdicts stay
+ // the clients' verdicts. Board ops are keyed per project.
+ if (!order.accept(m, id)) return
+ const g = governed.get(id)
+ if (g) {
+ applyTo(id, g, m)
+ return
+ }
+ const pending = queued.get(id)
+ if (pending) pending.push(m)
+ else queued.set(id, [m])
+ void adopt(id)
+ },
+
+ async overlaySave(ws: Workspace): Promise<Workspace> {
+ const projects = await Promise.all(
+ ws.projects.map(async (p) => {
+ if (!overlayable(p) || !governs(p.id)) return p
+ // Never seeded from a save: the save may be the stale copy this exists to overrule.
+ const g = await adopt(p.id)
+ return g ? overlayProject(p, g, 'save') : p
+ })
+ )
+ return { ...ws, projects }
+ },
+
+ async overlayLoad(ws: Workspace): Promise<Workspace> {
+ const projects = await Promise.all(
+ ws.projects.map(async (p) => {
+ if (!overlayable(p) || !governs(p.id)) return p
+ const g = await adopt(p.id, contentOf(p))
+ return g ? overlayProject(p, g, 'load') : p
+ })
+ )
+ return { ...ws, projects }
+ },
+
+ async adoptOutsideEdit(project: Project): Promise<void> {
+ if (!overlayable(project) || !governs(project.id)) return
+ const g = await adopt(project.id)
+ if (!g || !governs(project.id) || governed.get(project.id) !== g) return
+ const before = g.content
+ // ADOPT the edit, then re-apply what disk does not have yet on top of it (rule 3).
+ let after = governedContent(project)
+ for (const m of g.unflushed) after = applyCanvasOp(after, m, project.id)
+ // The state moves BEFORE the diff is published: the reflector echoes each op back through
+ // `onReflected` synchronously, and there it must find the content already in place.
+ g.content = after
+ for (const m of diffContent(before, after, project.id)) deps.publish(project.id, m)
+ // Disk already has the edit. It is owed a write only if our unflushed ops must go over it.
+ if (g.unflushed.length) markDirty(project.id, g)
+ },
+
+ sharedChanged(): void {
+ if (stopped) return
+ const shared = deps.sharedProjectIds()
+ // What left: write what is pending, then let go (`flush` releases once nothing is owed).
+ for (const id of [...governed.keys()]) if (!shared.has(id)) void flush(id)
+ // What joined: adopt now, so an outside edit that lands before any op still has a baseline to
+ // diff against. The store records its re-read of an edited file before it hands the project
+ // over, so a baseline read after the edit would see no difference at all.
+ for (const id of shared) if (!governed.has(id)) void adopt(id)
+ },
+
+ async flushAll(): Promise<void> {
+ await Promise.all([...adopting.values()])
+ await Promise.all([...governed.keys()].map((id) => drain(id)))
+ },
+
+ async stop(): Promise<void> {
+ if (stopped) return
+ stopped = true
+ // An adoption already reading installs its queued ops; they are written below.
+ await Promise.all([...adopting.values()])
+ await Promise.all([...governed.keys()].map((id) => drain(id)))
+ for (const [id, g] of governed) {
+ clearTimers(g)
+ if (g.dirty) log(`project ${id}: its latest canvas edits could not be written before stopping`)
+ }
+ }
+ }
+}