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
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.tsnew file mode 100644index 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.tsnew file mode 100644index 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`)+ }+ }+ }+}