From c51a952a885ef015bca8bfab0618850201c2c95e Mon Sep 17 00:00:00 2001 From: Amp Date: Mon, 31 Aug 2026 09:44:23 +0000 Subject: [PATCH 01/24] feat(agent): add GraphDocument registry and activation seam Implements the ADR-0024 document/activation seam for the in-app agent: - DocumentId brand and target-keyed GraphDocument registry (workflow_id -> document_id mapping, duplicate/stale rejection) - pure document lifecycle reducer with derived persistence state, save tickets, and CAS close - activation coordinator with generation-raced activate/deactivate and ordered view-binding handoff - detached target session: staged unloaded-target frame queue with all-or-nothing commit, last-committed state-vector recovery, doc_reset lineage, gap/duplicate/overflow handling - target frame projection port: atomic clear+rebuild snapshot batch through GraphMutations - renderer-independent canonical document serializer - byte-identical save/reload integration tests across activation cycles, stamp/incarnation preservation, active-canvas isolation, reconnect/reset coverage - early-bound document identity in AgentPanelRoot scope resolution Amp-Thread-ID: https://ampcode.com/threads/T-01a05717-75a6-77a8-a59a-3ba204aa654c --- .../document/activationCoordinator.test.ts | 165 ++++++++ .../graph/document/activationCoordinator.ts | 89 +++++ .../document/detachedTargetSession.test.ts | 333 ++++++++++++++++ .../graph/document/detachedTargetSession.ts | 255 ++++++++++++ .../graph/document/documentLifecycle.test.ts | 143 +++++++ src/core/graph/document/documentLifecycle.ts | 74 ++++ src/core/graph/document/documentSerializer.ts | 59 +++ src/stores/graphDocumentStore.test.ts | 180 +++++++++ src/stores/graphDocumentStore.ts | 210 ++++++++++ src/types/documentId.ts | 18 + .../extensions/agent/AgentPanelRoot.vue | 29 +- ...tActivationPersistence.integration.test.ts | 364 ++++++++++++++++++ .../agent/crdt/targetFrameProjection.ts | 139 +++++++ 13 files changed, 2052 insertions(+), 6 deletions(-) create mode 100644 src/core/graph/document/activationCoordinator.test.ts create mode 100644 src/core/graph/document/activationCoordinator.ts create mode 100644 src/core/graph/document/detachedTargetSession.test.ts create mode 100644 src/core/graph/document/detachedTargetSession.ts create mode 100644 src/core/graph/document/documentLifecycle.test.ts create mode 100644 src/core/graph/document/documentLifecycle.ts create mode 100644 src/core/graph/document/documentSerializer.ts create mode 100644 src/stores/graphDocumentStore.test.ts create mode 100644 src/stores/graphDocumentStore.ts create mode 100644 src/types/documentId.ts create mode 100644 src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts create mode 100644 src/workbench/extensions/agent/crdt/targetFrameProjection.ts diff --git a/src/core/graph/document/activationCoordinator.test.ts b/src/core/graph/document/activationCoordinator.test.ts new file mode 100644 index 00000000000..94c9506be5c --- /dev/null +++ b/src/core/graph/document/activationCoordinator.test.ts @@ -0,0 +1,165 @@ +import { describe, expect, it } from 'vitest' + +import type { DocumentViewBinding } from '@/core/graph/document/activationCoordinator' +import { createActivationCoordinator } from '@/core/graph/document/activationCoordinator' +import type { DocumentId } from '@/types/documentId' +import { toDocumentId } from '@/types/documentId' + +function recordingBinding(log: string[], name: string): DocumentViewBinding { + return { + attach: (id: DocumentId) => log.push(`attach:${name}:${id}`), + detach: (id: DocumentId) => log.push(`detach:${name}:${id}`) + } +} + +function deferred(): { promise: Promise; resolve: () => void } { + let resolve!: () => void + const promise = new Promise((r) => { + resolve = r + }) + return { promise, resolve } +} + +describe('createActivationCoordinator', () => { + it('activates a loaded document and publishes it as active', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => true }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + + const outcome = await coordinator.activate(docA, recordingBinding(log, 'a')) + + expect(outcome).toEqual({ status: 'activated', documentId: docA }) + expect(coordinator.activeDocumentId()).toBe(docA) + expect(log).toEqual([`attach:a:${docA}`]) + }) + + it('rejects activation of a document that is not loaded', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => false }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + + const outcome = await coordinator.activate(docA, recordingBinding(log, 'a')) + + expect(outcome).toEqual({ + status: 'rejected', + documentId: docA, + reason: 'not-loaded' + }) + expect(coordinator.activeDocumentId()).toBeNull() + expect(log).toEqual([]) + }) + + it('rejects when hydration fails and leaves the previous binding intact', async () => { + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => + id === docB ? Promise.reject(new Error('boom')) : Promise.resolve() + }) + const log: string[] = [] + await coordinator.activate(docA, recordingBinding(log, 'a')) + + const outcome = await coordinator.activate(docB, recordingBinding(log, 'b')) + + expect(outcome).toEqual({ + status: 'rejected', + documentId: docB, + reason: 'hydration-failed' + }) + expect(coordinator.activeDocumentId()).toBe(docA) + expect(log).toEqual([`attach:a:${docA}`]) + }) + + it('performs an ordered detach-then-attach handoff between documents', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => true }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + + await coordinator.activate(docA, recordingBinding(log, 'a')) + await coordinator.activate(docB, recordingBinding(log, 'b')) + + expect(log).toEqual([ + `attach:a:${docA}`, + `detach:a:${docA}`, + `attach:b:${docB}` + ]) + expect(coordinator.activeDocumentId()).toBe(docB) + }) + + it('supersedes a slow activate when a newer activate wins the race', async () => { + const slowHydration = deferred() + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => (id === docA ? slowHydration.promise : Promise.resolve()) + }) + const log: string[] = [] + + const first = coordinator.activate(docA, recordingBinding(log, 'a')) + const second = await coordinator.activate(docB, recordingBinding(log, 'b')) + slowHydration.resolve() + const firstOutcome = await first + + expect(second).toEqual({ status: 'activated', documentId: docB }) + expect(firstOutcome).toEqual({ status: 'superseded', documentId: docA }) + expect(coordinator.activeDocumentId()).toBe(docB) + expect(log).toEqual([`attach:b:${docB}`]) + }) + + it('reports superseded when a stale request fails hydration after being overtaken', async () => { + const slowHydration = deferred() + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => + id === docA + ? slowHydration.promise.then(() => { + throw new Error('late failure') + }) + : Promise.resolve() + }) + const log: string[] = [] + + const first = coordinator.activate(docA, recordingBinding(log, 'a')) + await coordinator.activate(docB, recordingBinding(log, 'b')) + slowHydration.resolve() + + expect(await first).toEqual({ status: 'superseded', documentId: docA }) + expect(coordinator.activeDocumentId()).toBe(docB) + }) + + it('deactivate detaches the active document and cancels in-flight activation', async () => { + const slowHydration = deferred() + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + const coordinator = createActivationCoordinator({ + isLoaded: () => true, + hydrate: (id) => (id === docB ? slowHydration.promise : Promise.resolve()) + }) + const log: string[] = [] + await coordinator.activate(docA, recordingBinding(log, 'a')) + + const inFlight = coordinator.activate(docB, recordingBinding(log, 'b')) + expect(coordinator.deactivate(docA)).toBe(true) + slowHydration.resolve() + + expect(await inFlight).toEqual({ status: 'superseded', documentId: docB }) + expect(coordinator.activeDocumentId()).toBeNull() + expect(log).toEqual([`attach:a:${docA}`, `detach:a:${docA}`]) + }) + + it('deactivate of a non-active document is a no-op', async () => { + const coordinator = createActivationCoordinator({ isLoaded: () => true }) + const log: string[] = [] + const docA = toDocumentId('doc-a') + const docB = toDocumentId('doc-b') + await coordinator.activate(docA, recordingBinding(log, 'a')) + + expect(coordinator.deactivate(docB)).toBe(false) + expect(coordinator.activeDocumentId()).toBe(docA) + }) +}) diff --git a/src/core/graph/document/activationCoordinator.ts b/src/core/graph/document/activationCoordinator.ts new file mode 100644 index 00000000000..00f9bf23eff --- /dev/null +++ b/src/core/graph/document/activationCoordinator.ts @@ -0,0 +1,89 @@ +import type { DocumentId } from '@/types/documentId' + +/** + * View concerns attached by activation and detached by deactivation: the + * renderer/canvas binding, render-attached caches, viewport projection, and + * input/event hooks. Attach and detach must not touch semantic document + * state (ADR-0024: activation is presentation). + */ +export interface DocumentViewBinding { + attach(documentId: DocumentId): void + detach(documentId: DocumentId): void +} + +export type ActivationOutcome = + | { status: 'activated'; documentId: DocumentId } + /** A newer activate/deactivate request won the generation race. */ + | { status: 'superseded'; documentId: DocumentId } + | { + status: 'rejected' + documentId: DocumentId + reason: 'not-loaded' | 'hydration-failed' + } + +export interface ActivationCoordinatorDeps { + /** The registry's loaded check for the document being activated. */ + isLoaded(documentId: DocumentId): boolean + /** + * Hydrate and validate the document before the handoff. Runs without + * changing the current binding; a stale request discards this staged work. + */ + hydrate?(documentId: DocumentId): Promise +} + +/** + * Serializes document activation onto the active-canvas binding (ADR-0024). + * Requests carry a monotonic generation: a newer request cancels any older + * in-flight one, and a stale request may clean up its private staged work + * but can never detach, attach, or publish. The winning request performs one + * ordered handoff — detach the previous document's view hooks, attach the + * new document's, publish the new active binding — so a late `activate(A)` + * completion cannot overwrite a later `activate(B)`. + */ +export function createActivationCoordinator(deps: ActivationCoordinatorDeps) { + let generation = 0 + let active: { documentId: DocumentId; binding: DocumentViewBinding } | null = + null + + async function activate( + documentId: DocumentId, + binding: DocumentViewBinding + ): Promise { + const requestGeneration = ++generation + const stale = (): boolean => requestGeneration !== generation + try { + await deps.hydrate?.(documentId) + } catch { + return stale() + ? { status: 'superseded', documentId } + : { status: 'rejected', documentId, reason: 'hydration-failed' } + } + if (stale()) return { status: 'superseded', documentId } + if (!deps.isLoaded(documentId)) + return { status: 'rejected', documentId, reason: 'not-loaded' } + + if (active) active.binding.detach(active.documentId) + binding.attach(documentId) + active = { documentId, binding } + return { status: 'activated', documentId } + } + + /** + * Explicit inverse of {@link activate}. Detaches view concerns only; the + * document remains loaded and its domain stores, follower, queue, change + * tracking, and persistence continue to operate. + */ + function deactivate(documentId: DocumentId): boolean { + if (active?.documentId !== documentId) return false + generation++ + active.binding.detach(documentId) + active = null + return true + } + + function activeDocumentId(): DocumentId | null { + return active?.documentId ?? null + } + + return { activate, deactivate, activeDocumentId } +} diff --git a/src/core/graph/document/detachedTargetSession.test.ts b/src/core/graph/document/detachedTargetSession.test.ts new file mode 100644 index 00000000000..d3f3d2e0e38 --- /dev/null +++ b/src/core/graph/document/detachedTargetSession.test.ts @@ -0,0 +1,333 @@ +import { describe, expect, it } from 'vitest' +import * as Y from 'yjs' + +import type { + TargetFrame, + TargetFrameApplyPort +} from '@/core/graph/document/detachedTargetSession' +import { createDetachedTargetSession } from '@/core/graph/document/detachedTargetSession' + +const WORKFLOW_ID = 'wf-detached' + +/** + * A host document emitting ordered incremental update frames, mirroring the + * doc_update stream a live host produces. + */ +function createFrameSource(workflowId = WORKFLOW_ID) { + const host = new Y.Doc() + let seq = 0 + let lastVector = Y.encodeStateVector(host) + + function frame( + mutate: (doc: Y.Doc) => void, + stamps: Pick = {} + ): TargetFrame { + mutate(host) + const update = Y.encodeStateAsUpdate(host, lastVector) + lastVector = Y.encodeStateVector(host) + seq += 1 + return { workflowId, seq, update, ...stamps } + } + + function diffFrom(stateVector: Uint8Array, atSeq: number): TargetFrame { + return { + workflowId, + seq: atSeq, + update: Y.encodeStateAsUpdate(host, stateVector) + } + } + + return { host, frame, diffFrom } +} + +function setNode(doc: Y.Doc, id: string, fields: Record) { + const nodes = doc.getMap>('nodes') + const node = nodes.get(id) ?? new Y.Map() + if (!nodes.has(id)) nodes.set(id, node) + for (const [key, value] of Object.entries(fields)) node.set(key, value) +} + +function readNodes(update: Uint8Array): Record { + const doc = new Y.Doc() + Y.applyUpdate(doc, update) + const json = doc.getMap('nodes').toJSON() + doc.destroy() + return json +} + +const acceptAll: TargetFrameApplyPort = { apply: () => true } +const rejectAll: TargetFrameApplyPort = { apply: () => false } + +describe('createDetachedTargetSession', () => { + it('commits queued frames in order and reproduces the host state byte-exactly', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'a' }))) + session.enqueue(source.frame((doc) => setNode(doc, '2', { type: 'Sink' }))) + + const drained = session.drainAll(acceptAll) + + expect(drained).toEqual({ committed: 3, stoppedBy: { status: 'idle' } }) + expect(readNodes(session.encodeCommittedState())).toEqual( + source.host.getMap('nodes').toJSON() + ) + const snapshot = session.snapshot() + expect(snapshot.committedSeq).toBe(3) + expect(snapshot.revision).toBe(3) + expect(snapshot.lastCommitId).toBe(`${snapshot.lineage}:3`) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.needsResync).toBe(false) + }) + + it('offers the projection port the frame stamps verbatim and the staged doc with the frame folded in', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + const seen: { frame: TargetFrame; stagedNodes: Record }[] = + [] + const port: TargetFrameApplyPort = { + apply: (frame, stagedDoc) => { + seen.push({ frame, stagedNodes: stagedDoc.getMap('nodes').toJSON() }) + return true + } + } + + const frame = source.frame((doc) => setNode(doc, '1', { type: 'Source' }), { + actor: 'agent:planner', + opIds: ['op-1', 'op-2'] + }) + session.enqueue(frame) + session.commitNext(port) + + expect(seen).toHaveLength(1) + expect(seen[0]!.frame.actor).toBe('agent:planner') + expect(seen[0]!.frame.opIds).toEqual(['op-1', 'op-2']) + expect(seen[0]!.frame.seq).toBe(1) + expect(seen[0]!.stagedNodes).toEqual({ '1': { type: 'Source' } }) + }) + + it('preserves node incarnation bytes through the staged commit path', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => + setNode(doc, '9', { type: 'Source', __incarnation: 'inc-original-9' }) + ) + ) + + session.commitNext(acceptAll) + + const committed = readNodes(session.encodeCommittedState()) + expect(committed).toEqual({ + '9': { type: 'Source', __incarnation: 'inc-original-9' } + }) + expect(committed).toEqual(source.host.getMap('nodes').toJSON()) + }) + + it('a rejected apply leaves the frame queued and the committed tuple unchanged', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const before = session.snapshot() + const vectorBefore = session.recoveryStateVector() + + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'b' }))) + const failed = session.commitNext(rejectAll) + + expect(failed).toEqual({ status: 'failed', seq: 2 }) + expect(session.snapshot()).toEqual({ ...before, queuedFrames: 1 }) + expect(session.recoveryStateVector()).toEqual(vectorBefore) + + const retried = session.commitNext(acceptAll) + expect(retried).toEqual({ + status: 'committed', + commitId: `${before.lineage}:2`, + seq: 2 + }) + }) + + it('a throwing apply reports failed with the error and keeps the frame queued', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + const boom = new Error('projection exploded') + + const result = session.commitNext({ + apply: () => { + throw boom + } + }) + + expect(result).toEqual({ status: 'failed', seq: 1, error: boom }) + expect(session.snapshot().queuedFrames).toBe(1) + expect(session.snapshot().committedSeq).toBeNull() + }) + + it('skips duplicate frames at or below the last accepted sequence', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + const first = source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + session.enqueue(first) + session.commitNext(acceptAll) + + expect(session.enqueue(first)).toEqual({ status: 'duplicate', seq: 1 }) + + const second = source.frame((doc) => setNode(doc, '1', { title: 'c' })) + session.enqueue(second) + expect(session.enqueue(second)).toEqual({ status: 'duplicate', seq: 2 }) + expect(session.snapshot().queuedFrames).toBe(1) + }) + + it('a sequence gap discards the queue, demands resync, and preserves the recovery state vector', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const recoveryBefore = session.recoveryStateVector() + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'q' }))) + + source.frame((doc) => setNode(doc, '1', { title: 'lost' })) + const gapFrame = source.frame((doc) => setNode(doc, '2', { type: 'Sink' })) + const result = session.enqueue(gapFrame) + + expect(result).toEqual({ status: 'gap', expectedSeq: 3, receivedSeq: 4 }) + const snapshot = session.snapshot() + expect(snapshot.needsResync).toBe(true) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.committedSeq).toBe(1) + expect(session.recoveryStateVector()).toEqual(recoveryBefore) + expect(session.enqueue(gapFrame)).toEqual({ status: 'resync-required' }) + expect(session.commitNext(acceptAll)).toEqual({ + status: 'resync-required' + }) + }) + + it('recovers from a gap by replaying the diff against the last committed state vector', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + + source.frame((doc) => setNode(doc, '1', { title: 'lost' })) + session.enqueue(source.frame((doc) => setNode(doc, '2', { type: 'Sink' }))) + + session.beginResync() + const catchUp = source.diffFrom(session.recoveryStateVector(), 3) + expect(session.enqueue(catchUp)).toEqual({ + status: 'queued', + queuedFrames: 1 + }) + expect(session.commitNext(acceptAll).status).toBe('committed') + expect(readNodes(session.encodeCommittedState())).toEqual( + source.host.getMap('nodes').toJSON() + ) + }) + + it('overflow discards queued frames but keeps the last committed state for recovery', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID, { + maxQueuedFrames: 2 + }) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const recoveryBefore = session.recoveryStateVector() + + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'a' }))) + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'b' }))) + const overflowed = session.enqueue( + source.frame((doc) => setNode(doc, '1', { title: 'c' })) + ) + + expect(overflowed).toEqual({ status: 'overflow', discardedFrames: 2 }) + const snapshot = session.snapshot() + expect(snapshot.needsResync).toBe(true) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.committedSeq).toBe(1) + expect(session.recoveryStateVector()).toEqual(recoveryBefore) + + session.beginResync() + session.enqueue(source.diffFrom(session.recoveryStateVector(), 4)) + session.commitNext(acceptAll) + expect(readNodes(session.encodeCommittedState())).toEqual( + source.host.getMap('nodes').toJSON() + ) + }) + + it('doc_reset starts a fresh document and lineage and invalidates old commit ids', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.commitNext(acceptAll) + const oldSnapshot = session.snapshot() + const oldCommitId = oldSnapshot.lastCommitId! + expect(session.isCommitted(oldCommitId)).toBe(true) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { title: 'stale' })) + ) + + session.resetLineage(10) + + const snapshot = session.snapshot() + expect(snapshot.lineage).not.toBe(oldSnapshot.lineage) + expect(snapshot.committedSeq).toBe(10) + expect(snapshot.queuedFrames).toBe(0) + expect(snapshot.lastCommitId).toBeNull() + expect(session.isCommitted(oldCommitId)).toBe(false) + expect(readNodes(session.encodeCommittedState())).toEqual({}) + + const freshHost = new Y.Doc() + setNode(freshHost, '5', { type: 'Fresh' }) + session.enqueue({ + workflowId: WORKFLOW_ID, + seq: 11, + update: Y.encodeStateAsUpdate(freshHost) + }) + expect(session.commitNext(acceptAll).status).toBe('committed') + expect(session.snapshot().lastCommitId).toBe(`${snapshot.lineage}:11`) + freshHost.destroy() + }) + + it('rejects frames addressed to another target loudly', () => { + const session = createDetachedTargetSession(WORKFLOW_ID) + const stranger = createFrameSource('wf-other') + + expect(() => + session.enqueue( + stranger.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + ).toThrow(/frames must never cross targets/) + }) + + it('isCommitted answers for any sequence at or below the committed head of the same lineage', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.enqueue(source.frame((doc) => setNode(doc, '1', { title: 'a' }))) + session.drainAll(acceptAll) + const { lineage } = session.snapshot() + + expect(session.isCommitted(`${lineage}:1`)).toBe(true) + expect(session.isCommitted(`${lineage}:2`)).toBe(true) + expect(session.isCommitted(`${lineage}:3`)).toBe(false) + expect(session.isCommitted(`other-lineage:1`)).toBe(false) + expect(session.isCommitted('malformed')).toBe(false) + }) +}) diff --git a/src/core/graph/document/detachedTargetSession.ts b/src/core/graph/document/detachedTargetSession.ts new file mode 100644 index 00000000000..d0f24176bcc --- /dev/null +++ b/src/core/graph/document/detachedTargetSession.ts @@ -0,0 +1,255 @@ +import * as Y from 'yjs' + +import { createUuidv4 } from '@/utils/uuid' + +/** + * One ordered effect frame addressed to a target document. Structurally + * compatible with the workbench `DocUpdate` wire frame; declared here so the + * core document seam never imports workbench transport types. + */ +export interface TargetFrame { + readonly workflowId: string + readonly seq: number + readonly update: Uint8Array + readonly actor?: string + /** Accepted semantic op identities folded into this effect frame (DQ-9). */ + readonly opIds?: readonly string[] +} + +/** + * Projects one staged frame into the domain stores. `apply` receives the + * staged document with the frame already folded in; it must be all-or-nothing + * and report whether the projection committed. A `false` return (or a throw) + * leaves the frame queued and the session's committed tuple untouched. + */ +export interface TargetFrameApplyPort { + apply(frame: TargetFrame, stagedDoc: Y.Doc): boolean +} + +export type EnqueueResult = + | { status: 'queued'; queuedFrames: number } + /** `seq` at or below the last accepted frame — replay, skipped. */ + | { status: 'duplicate'; seq: number } + /** Non-contiguous `seq`; queue discarded, resync required. */ + | { status: 'gap'; expectedSeq: number; receivedSeq: number } + /** Queue bound exceeded; queue discarded, resync required. */ + | { status: 'overflow'; discardedFrames: number } + | { status: 'resync-required' } + +export type CommitResult = + | { status: 'idle' } + | { status: 'resync-required' } + | { status: 'committed'; commitId: string; seq: number } + | { status: 'failed'; seq: number; error?: unknown } + +export interface DetachedTargetSessionSnapshot { + readonly workflowId: string + readonly lineage: string + readonly committedSeq: number | null + readonly revision: number + readonly queuedFrames: number + readonly needsResync: boolean + readonly lastCommitId: string | null +} + +export interface DetachedTargetSessionOptions { + /** Upper bound on staged-but-uncommitted frames. */ + readonly maxQueuedFrames?: number + readonly initialLineage?: string +} + +const DEFAULT_MAX_QUEUED_FRAMES = 64 + +/** + * Staged frame queue for a target document that is not attached to a live + * follower (ADR-0024's unloaded-target path). Frames enqueue in wire order + * and commit one at a time: each commit folds the head frame into a clone of + * the last committed Yjs state, offers it to the projection port, and only + * on success publishes the new committed tuple + * `{revision, sequence, stateVector, lineage, lastCommitId}` and dequeues. + * + * The last committed state vector is the recovery anchor: on queue overflow + * or a sequence gap the queued frames are discarded but the committed state + * survives, so the host can be asked for exactly the missing diff + * (`recoveryStateVector`). A `doc_reset` starts a new lineage with a fresh + * document; commit identities (`lineage:seq`) from the old lineage never + * collide with the new one. + */ +export function createDetachedTargetSession( + workflowId: string, + options: DetachedTargetSessionOptions = {} +) { + const maxQueuedFrames = options.maxQueuedFrames ?? DEFAULT_MAX_QUEUED_FRAMES + + let lineage = options.initialLineage ?? createUuidv4() + let committedDoc = new Y.Doc() + let committedSeq: number | null = null + let revision = 0 + let lastCommitId: string | null = null + let needsResync = false + /** `null` accepts any sequence (fresh session or just resynced). */ + let expectedSeq: number | null = null + let queue: TargetFrame[] = [] + + function assertTarget(frameWorkflowId: string): void { + if (frameWorkflowId !== workflowId) { + throw new Error( + `DetachedTargetSession(${workflowId}) received a frame addressed to ` + + `"${frameWorkflowId}"; frames must never cross targets` + ) + } + } + + function enqueue(frame: TargetFrame): EnqueueResult { + assertTarget(frame.workflowId) + if (needsResync) return { status: 'resync-required' } + + const lastAcceptedSeq = queue.at(-1)?.seq ?? committedSeq + if (lastAcceptedSeq !== null && frame.seq <= lastAcceptedSeq) + return { status: 'duplicate', seq: frame.seq } + + if (expectedSeq !== null && frame.seq !== expectedSeq) { + const gapAt = expectedSeq + queue = [] + needsResync = true + return { status: 'gap', expectedSeq: gapAt, receivedSeq: frame.seq } + } + + if (queue.length >= maxQueuedFrames) { + const discardedFrames = queue.length + queue = [] + needsResync = true + return { status: 'overflow', discardedFrames } + } + + queue.push(frame) + expectedSeq = frame.seq + 1 + return { status: 'queued', queuedFrames: queue.length } + } + + function commitNext(port: TargetFrameApplyPort): CommitResult { + if (needsResync) return { status: 'resync-required' } + const frame = queue[0] + if (!frame) return { status: 'idle' } + + const staged = new Y.Doc() + Y.applyUpdate(staged, Y.encodeStateAsUpdate(committedDoc)) + Y.applyUpdate(staged, frame.update) + + let applied: boolean + try { + applied = port.apply(frame, staged) + } catch (error) { + staged.destroy() + return { status: 'failed', seq: frame.seq, error } + } + if (!applied) { + staged.destroy() + return { status: 'failed', seq: frame.seq } + } + + committedDoc.destroy() + committedDoc = staged + committedSeq = frame.seq + revision += 1 + lastCommitId = `${lineage}:${frame.seq}` + queue.shift() + return { status: 'committed', commitId: lastCommitId, seq: frame.seq } + } + + function drainAll(port: TargetFrameApplyPort): { + committed: number + stoppedBy: CommitResult + } { + let committed = 0 + for (;;) { + const result = commitNext(port) + if (result.status !== 'committed') return { committed, stoppedBy: result } + committed += 1 + } + } + + /** + * State vector of the last committed document state — what the host must + * diff against to replay everything this session is missing. + */ + function recoveryStateVector(): Uint8Array { + return Y.encodeStateVector(committedDoc) + } + + /** Committed Yjs state, byte-exact, for hydration into a live follower. */ + function encodeCommittedState(): Uint8Array { + return Y.encodeStateAsUpdate(committedDoc) + } + + /** + * The host has replayed the missing diff onto the committed state (or will + * send a full catch-up next); accept the next frame at any sequence. + */ + function beginResync(): void { + needsResync = false + queue = [] + expectedSeq = null + } + + /** + * `doc_reset`: the host re-minted the document, so prior updates do not + * compose with what follows. Starts a fresh document and lineage; queued + * frames from the old lineage are meaningless and dropped. + */ + function resetLineage(atSeq: number): void { + committedDoc.destroy() + committedDoc = new Y.Doc() + lineage = createUuidv4() + committedSeq = atSeq + expectedSeq = null + lastCommitId = null + needsResync = false + queue = [] + } + + function isCommitted(commitId: string): boolean { + const separator = commitId.lastIndexOf(':') + if (separator < 0) return false + const commitLineage = commitId.slice(0, separator) + const seq = Number(commitId.slice(separator + 1)) + if (!Number.isInteger(seq)) return false + return ( + commitLineage === lineage && committedSeq !== null && seq <= committedSeq + ) + } + + function snapshot(): DetachedTargetSessionSnapshot { + return { + workflowId, + lineage, + committedSeq, + revision, + queuedFrames: queue.length, + needsResync, + lastCommitId + } + } + + function destroy(): void { + committedDoc.destroy() + queue = [] + } + + return { + enqueue, + commitNext, + drainAll, + recoveryStateVector, + encodeCommittedState, + beginResync, + resetLineage, + isCommitted, + snapshot, + destroy + } +} + +export type DetachedTargetSession = ReturnType< + typeof createDetachedTargetSession +> diff --git a/src/core/graph/document/documentLifecycle.test.ts b/src/core/graph/document/documentLifecycle.test.ts new file mode 100644 index 00000000000..8c0c687ffd0 --- /dev/null +++ b/src/core/graph/document/documentLifecycle.test.ts @@ -0,0 +1,143 @@ +import { describe, expect, it } from 'vitest' + +import { + initialDocumentState, + persistenceOf, + reduceDocument +} from './documentLifecycle' +import type { DocumentEvent, DocumentTrackingState } from './documentLifecycle' + +function run( + events: readonly DocumentEvent[], + from: DocumentTrackingState = initialDocumentState +): DocumentTrackingState { + return events.reduce(reduceDocument, from) +} + +describe('reduceDocument', () => { + it('starts created and unsaved', () => { + expect(initialDocumentState.phase).toBe('created') + expect(persistenceOf(initialDocumentState)).toBe('unsaved') + }) + + it('hydrates created to loaded and ignores repeat hydration', () => { + const loaded = run([{ type: 'hydrated' }]) + expect(loaded.phase).toBe('loaded') + expect(run([{ type: 'hydrated' }], loaded)).toEqual(loaded) + }) + + it('accumulates mutations while unsaved without changing persistence', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'mutated' } + ]) + expect(state.revision).toBe(2) + expect(persistenceOf(state)).toBe('unsaved') + }) + + it('a completed save makes the document clean only at the captured revision', () => { + const dirty = run([{ type: 'hydrated' }, { type: 'mutated' }]) + const clean = reduceDocument(dirty, { + type: 'saveCompleted', + atRevision: dirty.revision + }) + expect(persistenceOf(clean)).toBe('clean') + }) + + it('a mutation that commits while a save is in flight leaves the document dirty', () => { + const beforeSave = run([{ type: 'hydrated' }, { type: 'mutated' }]) + const capturedRevision = beforeSave.revision + const mutatedDuringSave = reduceDocument(beforeSave, { type: 'mutated' }) + const afterSave = reduceDocument(mutatedDuringSave, { + type: 'saveCompleted', + atRevision: capturedRevision + }) + expect(afterSave.savedRevision).toBe(capturedRevision) + expect(persistenceOf(afterSave)).toBe('dirty') + }) + + it('ignores a save completion ahead of the live revision or behind the baseline', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'saveCompleted', atRevision: 1 } + ]) + expect( + reduceDocument(state, { type: 'saveCompleted', atRevision: 99 }) + ).toEqual(state) + expect( + reduceDocument(state, { type: 'saveCompleted', atRevision: 0 }) + ).toEqual(state) + }) + + it('remote or human mutations after a save make a loaded document dirty again', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'saveCompleted', atRevision: 1 }, + { type: 'mutated' } + ]) + expect(persistenceOf(state)).toBe('dirty') + }) + + it('closes a clean document at its exact revision', () => { + const state = run([ + { type: 'hydrated' }, + { type: 'mutated' }, + { type: 'saveCompleted', atRevision: 1 }, + { type: 'closed', atRevision: 1, discardChanges: false } + ]) + expect(state.phase).toBe('closed') + }) + + it('refuses to close a dirty document without an explicit discard decision', () => { + const dirty = run([{ type: 'hydrated' }, { type: 'mutated' }]) + expect( + reduceDocument(dirty, { + type: 'closed', + atRevision: dirty.revision, + discardChanges: false + }).phase + ).toBe('loaded') + expect( + reduceDocument(dirty, { + type: 'closed', + atRevision: dirty.revision, + discardChanges: true + }).phase + ).toBe('closed') + }) + + it('treats a close decision as stale when the live revision moved past it', () => { + const presented = run([{ type: 'hydrated' }, { type: 'mutated' }]) + const decisionRevision = presented.revision + const moved = reduceDocument(presented, { type: 'mutated' }) + const attempted = reduceDocument(moved, { + type: 'closed', + atRevision: decisionRevision, + discardChanges: true + }) + expect(attempted.phase).toBe('loaded') + }) + + it('ignores mutation and save events after close', () => { + const closed = run([ + { type: 'hydrated' }, + { type: 'closed', atRevision: 0, discardChanges: true } + ]) + expect(reduceDocument(closed, { type: 'mutated' })).toEqual(closed) + expect( + reduceDocument(closed, { type: 'saveCompleted', atRevision: 0 }) + ).toEqual(closed) + }) + + it('cannot close a document that was never loaded', () => { + const attempted = reduceDocument(initialDocumentState, { + type: 'closed', + atRevision: 0, + discardChanges: true + }) + expect(attempted.phase).toBe('created') + }) +}) diff --git a/src/core/graph/document/documentLifecycle.ts b/src/core/graph/document/documentLifecycle.ts new file mode 100644 index 00000000000..85b97b3e0b5 --- /dev/null +++ b/src/core/graph/document/documentLifecycle.ts @@ -0,0 +1,74 @@ +/** + * The pure lifecycle/persistence transition of one `GraphDocument` + * (ADR-0024). Lifecycle (`created | loaded | closed`) and persistence + * (`unsaved | clean | dirty`) are independent: the first describes document + * existence, the second compares the document with its persistence baseline. + * Persistence is derived from `revision` vs `savedRevision`, never stored. + * + * Save capture happens outside the reducer: a caller captures + * `{ revision, bytes }` before starting I/O and reports `saveCompleted` with + * that exact revision. The baseline advances to the captured revision only, + * so mutations that commit while the save is in flight leave the document + * dirty. Close is a compare-and-set over an exact revision: a decision made + * against a revision that has since moved is stale and ignored. + */ + +type DocumentLifecyclePhase = 'created' | 'loaded' | 'closed' +export type DocumentPersistenceState = 'unsaved' | 'clean' | 'dirty' + +export interface DocumentTrackingState { + readonly phase: DocumentLifecyclePhase + /** Monotonic; incremented by every committed domain mutation. */ + readonly revision: number + /** Persistence baseline revision; `null` until the first completed save. */ + readonly savedRevision: number | null +} + +export type DocumentEvent = + | { type: 'hydrated' } + | { type: 'mutated' } + | { type: 'saveCompleted'; atRevision: number } + | { type: 'closed'; atRevision: number; discardChanges: boolean } + +export const initialDocumentState: DocumentTrackingState = { + phase: 'created', + revision: 0, + savedRevision: null +} + +export function persistenceOf( + state: DocumentTrackingState +): DocumentPersistenceState { + if (state.savedRevision === null) return 'unsaved' + return state.revision === state.savedRevision ? 'clean' : 'dirty' +} + +export function reduceDocument( + state: DocumentTrackingState, + event: DocumentEvent +): DocumentTrackingState { + switch (event.type) { + case 'hydrated': + return state.phase === 'created' ? { ...state, phase: 'loaded' } : state + case 'mutated': + return state.phase === 'closed' + ? state + : { ...state, revision: state.revision + 1 } + case 'saveCompleted': + if (state.phase === 'closed') return state + if (event.atRevision > state.revision) return state + if ( + state.savedRevision !== null && + event.atRevision < state.savedRevision + ) + return state + return { ...state, savedRevision: event.atRevision } + case 'closed': { + if (state.phase !== 'loaded') return state + if (event.atRevision !== state.revision) return state + if (!event.discardChanges && persistenceOf(state) !== 'clean') + return state + return { ...state, phase: 'closed' } + } + } +} diff --git a/src/core/graph/document/documentSerializer.ts b/src/core/graph/document/documentSerializer.ts new file mode 100644 index 00000000000..36992dd3ab8 --- /dev/null +++ b/src/core/graph/document/documentSerializer.ts @@ -0,0 +1,59 @@ +import { useLinkStore } from '@/stores/linkStore' +import { useNodeDataStore } from '@/stores/nodeDataStore' +import { useWidgetValueStore } from '@/stores/widgetValueStore' +import type { GraphScope } from '@/types/graphScopeId' +import { compareNodeIds } from '@/types/nodeId' + +const RENDER_ONLY_KEYS = new Set(['boundingRect']) + +function canonicalize(value: unknown): unknown { + if (Array.isArray(value)) return value.map(canonicalize) + if (value instanceof Map || value instanceof Set) + return canonicalize([...value]) + if (typeof value === 'object' && value !== null) { + const source = value as Record + const result: Record = {} + for (const key of Object.keys(source).sort()) { + if (RENDER_ONLY_KEYS.has(key)) continue + const entry = canonicalize(source[key]) + if (entry !== undefined) result[key] = entry + } + return result + } + return value +} + +/** + * Renderer-independent canonical serialization of one document scope's + * semantic ECS state (ADR-0024's persistence seam). Reads only the domain + * stores — never the canvas, layout, or litegraph instances — so the same + * document content produces the same bytes whether the document is active + * on the canvas, activated under a different renderer, or never activated + * at all. Byte equality of two serializations is the save/reload identity + * check. + */ +export function serializeDocumentScope(scope: GraphScope): Uint8Array { + const nodeStore = useNodeDataStore() + const linkStore = useLinkStore() + const widgetStore = useWidgetValueStore() + + const nodes = [ + ...nodeStore.getGraphNodesFor(scope.rootGraphId, scope.owningGraphId) + ] + .sort((left, right) => compareNodeIds(left.id, right.id)) + .map(({ graphId: _graphId, lastSerialization: _cache, ...semantic }) => ({ + ...semantic, + widgets: widgetStore + .getNodeWidgets(scope.rootGraphId, semantic.id) + .map(({ name, type, value }) => ({ name, type, value })) + .sort((left, right) => left.name.localeCompare(right.name)) + })) + + const links = [...linkStore.graphTopologies(scope)] + .sort((left, right) => left.id - right.id) + .map(({ graphId: _graphId, ...topology }) => topology) + + return new TextEncoder().encode( + JSON.stringify(canonicalize({ nodes, links })) + ) +} diff --git a/src/stores/graphDocumentStore.test.ts b/src/stores/graphDocumentStore.test.ts new file mode 100644 index 00000000000..313cd17d345 --- /dev/null +++ b/src/stores/graphDocumentStore.test.ts @@ -0,0 +1,180 @@ +import { createPinia, setActivePinia } from 'pinia' +import { beforeEach, describe, expect, it } from 'vitest' + +import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' + +import { useGraphDocumentStore } from './graphDocumentStore' + +const scope = { + rootGraphId: toRootGraphId('root-a'), + owningGraphId: toOwningGraphId('root-a') +} + +describe('useGraphDocumentStore', () => { + beforeEach(() => { + setActivePinia(createPinia()) + }) + + it('creates local-only documents that are not agent-addressable', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + expect(documentId).not.toBeNull() + if (documentId === null) return + const entry = store.getDocument(documentId) + expect(entry?.workflowId).toBeNull() + expect(entry?.state.phase).toBe('created') + expect(store.persistenceStateOf(documentId)).toBe('unsaved') + }) + + it('resolves an agent target by workflow id, never by another key', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + expect(documentId).not.toBeNull() + expect(store.resolveWorkflowTarget('wf-1')?.documentId).toBe(documentId) + expect(store.resolveWorkflowTarget('wf-other')).toBeNull() + }) + + it('rejects a duplicate workflow id mapping', () => { + const store = useGraphDocumentStore() + const first = store.createDocument({ workflowId: 'wf-1' }) + expect(first).not.toBeNull() + expect(store.createDocument({ workflowId: 'wf-1' })).toBeNull() + const second = store.createDocument() + if (second === null) throw new Error('createDocument failed') + expect(store.assignWorkflowId(second, 'wf-1')).toBe(false) + }) + + it('rejects a stale reassignment of a document that already has a workflow id', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + if (documentId === null) throw new Error('createDocument failed') + expect(store.assignWorkflowId(documentId, 'wf-2')).toBe(false) + expect(store.assignWorkflowId(documentId, 'wf-1')).toBe(true) + expect(store.getDocument(documentId)?.workflowId).toBe('wf-1') + }) + + it('allows remapping a workflow id after its previous document closed', () => { + const store = useGraphDocumentStore() + const first = store.createDocument({ workflowId: 'wf-1' }) + if (first === null) throw new Error('createDocument failed') + store.hydrateDocument(first, scope) + expect( + store.closeDocument(first, { atRevision: 0, discardChanges: true }) + ).toBe(true) + expect(store.resolveWorkflowTarget('wf-1')).toBeNull() + + const second = store.createDocument() + if (second === null) throw new Error('createDocument failed') + expect(store.assignWorkflowId(second, 'wf-1')).toBe(true) + expect(store.resolveWorkflowTarget('wf-1')?.documentId).toBe(second) + }) + + it('hydration early-binds the scope without requiring a renderer', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + if (documentId === null) throw new Error('createDocument failed') + expect(store.hydrateDocument(documentId, scope)).toBe(true) + const entry = store.getDocument(documentId) + expect(entry?.state.phase).toBe('loaded') + expect(entry?.scope).toEqual(scope) + expect(store.hydrateDocument(documentId, scope)).toBe(false) + }) + + it('rebinds scope only while loaded', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + const rebound = { + rootGraphId: toRootGraphId('root-b'), + owningGraphId: toOwningGraphId('root-b') + } + expect(store.rebindScope(documentId, rebound)).toBe(false) + store.hydrateDocument(documentId, scope) + expect(store.rebindScope(documentId, rebound)).toBe(true) + expect(store.getDocument(documentId)?.scope).toEqual(rebound) + }) + + it('tracks dirtiness across the save capture boundary', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + store.markMutated(documentId) + expect(store.persistenceStateOf(documentId)).toBe('unsaved') + + const ticket = store.beginSave(documentId) + expect(ticket?.revision).toBe(1) + if (!ticket) return + store.markMutated(documentId) + expect(store.completeSave(ticket)).toBe(true) + expect(store.persistenceStateOf(documentId)).toBe('dirty') + + const secondTicket = store.beginSave(documentId) + if (!secondTicket) throw new Error('beginSave failed') + expect(store.completeSave(secondTicket)).toBe(true) + expect(store.persistenceStateOf(documentId)).toBe('clean') + }) + + it('close is compare-and-set: a stale decision must be re-presented', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + store.markMutated(documentId) + const presentedRevision = + store.getDocument(documentId)?.state.revision ?? -1 + store.markMutated(documentId) + expect( + store.closeDocument(documentId, { + atRevision: presentedRevision, + discardChanges: true + }) + ).toBe(false) + expect(store.getDocument(documentId)?.state.phase).toBe('loaded') + expect( + store.closeDocument(documentId, { + atRevision: presentedRevision + 1, + discardChanges: true + }) + ).toBe(true) + }) + + it('refuses to close a dirty document without an explicit discard', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument() + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + store.markMutated(documentId) + expect( + store.closeDocument(documentId, { atRevision: 1, discardChanges: false }) + ).toBe(false) + }) + + it('removes only closed documents and clears their stale mapping', () => { + const store = useGraphDocumentStore() + const documentId = store.createDocument({ workflowId: 'wf-1' }) + if (documentId === null) throw new Error('createDocument failed') + store.hydrateDocument(documentId, scope) + expect(store.removeDocument(documentId)).toBe(false) + store.closeDocument(documentId, { atRevision: 0, discardChanges: true }) + expect(store.removeDocument(documentId)).toBe(true) + expect(store.getDocument(documentId)).toBeNull() + const next = store.createDocument({ workflowId: 'wf-1' }) + expect(next).not.toBeNull() + }) + + it('isolates state between documents: mutating A never dirties B', () => { + const store = useGraphDocumentStore() + const a = store.createDocument({ workflowId: 'wf-a' }) + const b = store.createDocument({ workflowId: 'wf-b' }) + if (a === null || b === null) throw new Error('createDocument failed') + store.hydrateDocument(a, scope) + store.hydrateDocument(b, { + rootGraphId: toRootGraphId('root-b'), + owningGraphId: toOwningGraphId('root-b') + }) + store.markMutated(a) + expect(store.getDocument(a)?.state.revision).toBe(1) + expect(store.getDocument(b)?.state.revision).toBe(0) + }) +}) diff --git a/src/stores/graphDocumentStore.ts b/src/stores/graphDocumentStore.ts new file mode 100644 index 00000000000..dfbc807a735 --- /dev/null +++ b/src/stores/graphDocumentStore.ts @@ -0,0 +1,210 @@ +import { defineStore } from 'pinia' +import { shallowReactive } from 'vue' + +import { + initialDocumentState, + persistenceOf, + reduceDocument +} from '@/core/graph/document/documentLifecycle' +import type { + DocumentPersistenceState, + DocumentTrackingState +} from '@/core/graph/document/documentLifecycle' +import type { DocumentId } from '@/types/documentId' +import { createDocumentId } from '@/types/documentId' +import type { GraphScope } from '@/types/graphScopeId' + +export interface GraphDocumentEntry { + readonly documentId: DocumentId + /** Canonical cloud wire address, when assigned. Never used as identity. */ + readonly workflowId: string | null + /** Early-bound ECS scope; set at hydration, independent of any renderer. */ + readonly scope: GraphScope | null + readonly state: DocumentTrackingState +} + +export interface SaveTicket { + readonly documentId: DocumentId + /** The exact revision whose serialized bytes the caller captured. */ + readonly revision: number +} + +/** + * The GraphDocument registry (ADR-0024): every workflow document is a + * first-class entry keyed by a stable frontend `document_id`, whether or not + * a tab, renderer, or cloud `workflow_id` exists for it. The registry owns + * the optional `workflow_id → document_id` mapping and rejects duplicate or + * stale mappings; agent frames resolve their target here and never fall back + * to the active canvas. + */ +export const useGraphDocumentStore = defineStore('graphDocument', () => { + const documents = shallowReactive(new Map()) + const documentIdByWorkflowId = shallowReactive(new Map()) + + function getDocument(documentId: DocumentId): GraphDocumentEntry | null { + return documents.get(documentId) ?? null + } + + function resolveWorkflowTarget( + workflowId: string + ): GraphDocumentEntry | null { + const documentId = documentIdByWorkflowId.get(workflowId) + if (documentId === undefined) return null + const entry = documents.get(documentId) + return entry && entry.state.phase !== 'closed' ? entry : null + } + + function persistenceStateOf( + documentId: DocumentId + ): DocumentPersistenceState | null { + const entry = documents.get(documentId) + return entry ? persistenceOf(entry.state) : null + } + + function patch( + documentId: DocumentId, + changes: Partial> + ): GraphDocumentEntry | null { + const entry = documents.get(documentId) + if (!entry) return null + const next = { ...entry, ...changes } + documents.set(documentId, next) + return next + } + + function createDocument(options?: { + workflowId?: string + }): DocumentId | null { + const workflowId = options?.workflowId ?? null + if (workflowId !== null && resolveWorkflowTarget(workflowId) !== null) + return null + const documentId = createDocumentId() + documents.set(documentId, { + documentId, + workflowId, + scope: null, + state: initialDocumentState + }) + if (workflowId !== null) documentIdByWorkflowId.set(workflowId, documentId) + return documentId + } + + /** + * Map a cloud `workflow_id` onto an existing document. Rejects a duplicate + * mapping (the workflow id already addresses another live document) and a + * stale reassignment (the document already carries a different workflow id). + */ + function assignWorkflowId( + documentId: DocumentId, + workflowId: string + ): boolean { + const entry = documents.get(documentId) + if (!entry || entry.state.phase === 'closed') return false + if (entry.workflowId === workflowId) return true + if (entry.workflowId !== null) return false + const incumbent = resolveWorkflowTarget(workflowId) + if (incumbent !== null && incumbent.documentId !== documentId) return false + documentIdByWorkflowId.set(workflowId, documentId) + patch(documentId, { workflowId }) + return true + } + + /** Transition `created → loaded` and early-bind the document's ECS scope. */ + function hydrateDocument(documentId: DocumentId, scope: GraphScope): boolean { + const entry = documents.get(documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { type: 'hydrated' }) + if (state === entry.state || state.phase !== 'loaded') return false + patch(documentId, { state, scope }) + return true + } + + /** Rebind the loaded document's scope, e.g. after its graph id is reminted. */ + function rebindScope(documentId: DocumentId, scope: GraphScope): boolean { + const entry = documents.get(documentId) + if (!entry || entry.state.phase !== 'loaded') return false + patch(documentId, { scope }) + return true + } + + function markMutated(documentId: DocumentId): boolean { + const entry = documents.get(documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { type: 'mutated' }) + if (state === entry.state) return false + patch(documentId, { state }) + return true + } + + /** + * Capture the save point. The caller serializes the document's bytes at + * this exact revision before starting I/O, then reports `completeSave` + * with the ticket. Mutations committed in between leave the document dirty. + */ + function beginSave(documentId: DocumentId): SaveTicket | null { + const entry = documents.get(documentId) + if (!entry || entry.state.phase === 'closed') return null + return { documentId, revision: entry.state.revision } + } + + function completeSave(ticket: SaveTicket): boolean { + const entry = documents.get(ticket.documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { + type: 'saveCompleted', + atRevision: ticket.revision + }) + if (state === entry.state) return false + patch(ticket.documentId, { state }) + return true + } + + /** + * Compare-and-set close over an exact revision. Returns false when the + * decision is stale (the live revision moved) or the document is dirty + * without an explicit discard; the caller must re-present the decision. + */ + function closeDocument( + documentId: DocumentId, + decision: { atRevision: number; discardChanges: boolean } + ): boolean { + const entry = documents.get(documentId) + if (!entry) return false + const state = reduceDocument(entry.state, { + type: 'closed', + atRevision: decision.atRevision, + discardChanges: decision.discardChanges + }) + if (state.phase !== 'closed' || entry.state.phase === 'closed') return false + patch(documentId, { state, scope: null }) + return true + } + + /** Drop a closed document's registry entry and its stale mapping. */ + function removeDocument(documentId: DocumentId): boolean { + const entry = documents.get(documentId) + if (!entry || entry.state.phase !== 'closed') return false + if ( + entry.workflowId !== null && + documentIdByWorkflowId.get(entry.workflowId) === documentId + ) + documentIdByWorkflowId.delete(entry.workflowId) + documents.delete(documentId) + return true + } + + return { + createDocument, + getDocument, + resolveWorkflowTarget, + persistenceStateOf, + assignWorkflowId, + hydrateDocument, + rebindScope, + markMutated, + beginSave, + completeSave, + closeDocument, + removeDocument + } +}) diff --git a/src/types/documentId.ts b/src/types/documentId.ts new file mode 100644 index 00000000000..11f84c2bbaf --- /dev/null +++ b/src/types/documentId.ts @@ -0,0 +1,18 @@ +import { createUuidv4 } from '@/utils/uuid' + +/** + * Stable frontend-owned identity of a `GraphDocument` (ADR-0024). Every + * document has one, including local and unsaved workflows. A cloud-backed + * document may additionally map a canonical `workflow_id` — the wire address + * used by agent commands — but that mapping lives in the document registry; + * it is never the document's own identity. + */ +export type DocumentId = string & { readonly __brand: 'DocumentId' } + +export function toDocumentId(value: string): DocumentId { + return value as DocumentId +} + +export function createDocumentId(): DocumentId { + return createUuidv4() as DocumentId +} diff --git a/src/workbench/extensions/agent/AgentPanelRoot.vue b/src/workbench/extensions/agent/AgentPanelRoot.vue index a776b176f34..56e118bb180 100644 --- a/src/workbench/extensions/agent/AgentPanelRoot.vue +++ b/src/workbench/extensions/agent/AgentPanelRoot.vue @@ -48,6 +48,7 @@ import { api } from '@/scripts/api' import { app } from '@/scripts/app' import { useAgentNodeSelectionStore } from '@/stores/agentNodeSelectionStore' import { useExecutionErrorStore } from '@/stores/executionErrorStore' +import { useGraphDocumentStore } from '@/stores/graphDocumentStore' import { useWorkflowTabActivityStore } from '@/stores/workflowTabActivityStore' import { useSidebarTabStore } from '@/stores/workspace/sidebarTabStore' import { isLGraphNode } from '@/utils/litegraphUtil' @@ -110,6 +111,7 @@ const tabActivity = useWorkflowTabActivityStore() const CREATING_TAB_MIN_DURATION_MS = 500 const canvasStore = useCanvasStore() +const graphDocumentStore = useGraphDocumentStore() const graphMutationsByWorkflow = new Map< string, ReturnType @@ -117,15 +119,30 @@ const graphMutationsByWorkflow = new Map< const graphMutations = (workflowId: string) => { const existing = graphMutationsByWorkflow.get(workflowId) if (existing) return existing + // Document identity is early-bound (ADR-0024): the registry entry is + // created when the target is first addressed, not at commit time. Commit + // scope resolution then records/refreshes the entry's scope, so a target + // whose tab is momentarily unresolved still commits into its own document. + const documentId = + graphDocumentStore.resolveWorkflowTarget(workflowId)?.documentId ?? + graphDocumentStore.createDocument({ workflowId }) const mutations = createGraphMutations({ getScope() { - const rootGraphId = boundTabFor(workflowId)?.activeState?.id - return rootGraphId - ? { - rootGraphId: toRootGraphId(rootGraphId), - owningGraphId: toOwningGraphId(rootGraphId) - } + const registered = documentId + ? (graphDocumentStore.getDocument(documentId)?.scope ?? null) : null + const rootGraphId = boundTabFor(workflowId)?.activeState?.id + if (!rootGraphId) return registered + const scope = { + rootGraphId: toRootGraphId(rootGraphId), + owningGraphId: toOwningGraphId(rootGraphId) + } + if (documentId) { + if (!registered) graphDocumentStore.hydrateDocument(documentId, scope) + else if (registered.rootGraphId !== scope.rootGraphId) + graphDocumentStore.rebindScope(documentId, scope) + } + return scope }, layout: { createNode(scope, nodeId, layout, context) { diff --git a/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts new file mode 100644 index 00000000000..c0f8456197b --- /dev/null +++ b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts @@ -0,0 +1,364 @@ +import { + appliedOpIds, + mint, + NODE_INCARNATION_KEY, + nodesMap, + readStamps +} from '@comfyorg/comfy-multi-player' +import type { WidgetCatalog } from '@comfyorg/comfy-multi-player' +import { createTestingPinia } from '@pinia/testing' +import { setActivePinia } from 'pinia' +import { beforeEach, describe, expect, it, vi } from 'vitest' +import * as Y from 'yjs' + +import { createActivationCoordinator } from '@/core/graph/document/activationCoordinator' +import type { DocumentViewBinding } from '@/core/graph/document/activationCoordinator' +import { createDetachedTargetSession } from '@/core/graph/document/detachedTargetSession' +import type { DetachedTargetSession } from '@/core/graph/document/detachedTargetSession' +import { serializeDocumentScope } from '@/core/graph/document/documentSerializer' +import { createGraphMutations } from '@/core/graph/graphMutations' +import type { GraphMutations } from '@/core/graph/graphMutations' +import { useGraphDocumentStore } from '@/stores/graphDocumentStore' +import type { DocumentId } from '@/types/documentId' +import type { GraphScope } from '@/types/graphScopeId' +import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' + +import { createTargetFrameApplyPort } from './targetFrameProjection' + +const catalog: WidgetCatalog = { + types: { + Source: { widget_order: ['seed', 'stale'] }, + Sink: { widget_order: [] } + } +} + +const workflowJson = { + nodes: [ + { + id: 1, + type: 'Source', + title: 'Producer', + pos: [10, 20], + size: [180, 90], + inputs: [], + outputs: [{ name: 'out', type: 'IMAGE', links: [9] }], + widgets_values: { seed: 42, stale: 7 } + }, + { + id: 2, + type: 'Sink', + pos: [300, 20], + inputs: [{ name: 'in', type: 'IMAGE', link: 9 }], + outputs: [] + } + ], + links: [[9, 1, 0, 2, 0, 'IMAGE']] as [ + number, + number, + number, + number, + number, + string + ][] +} + +function scopeFor(graphId: string): GraphScope { + return { + rootGraphId: toRootGraphId(graphId), + owningGraphId: toOwningGraphId(graphId) + } +} + +function mutationsFor(scope: GraphScope): GraphMutations { + return createGraphMutations({ + getScope: () => scope, + layout: { createNode: vi.fn(), deleteNodes: vi.fn() } + }) +} + +function commitHostState( + session: DetachedTargetSession, + workflowId: string, + host: Y.Doc, + mutations: GraphMutations, + seq = 1 +): void { + expect( + session.enqueue({ + workflowId, + seq, + update: Y.encodeStateAsUpdate(host), + actor: 'agent:test', + opIds: [`bootstrap-${seq}`] + }).status + ).toBe('queued') + expect(session.commitNext(createTargetFrameApplyPort(mutations)).status).toBe( + 'committed' + ) +} + +/** A fake renderer-mode binding: activation must never touch semantic state. */ +function modeBinding(log: string[], mode: string): DocumentViewBinding { + return { + attach: () => log.push(`attach:${mode}`), + detach: () => log.push(`detach:${mode}`) + } +} + +function registerLoadedDocument(workflowId: string, scope: GraphScope) { + const registry = useGraphDocumentStore() + const documentId = registry.createDocument({ workflowId }) + if (documentId === null) throw new Error('duplicate workflow mapping') + expect(registry.hydrateDocument(documentId, scope)).toBe(true) + return { registry, documentId } +} + +function loadedCoordinator() { + const registry = useGraphDocumentStore() + return createActivationCoordinator({ + isLoaded: (id: DocumentId) => + registry.getDocument(id)?.state.phase === 'loaded' + }) +} + +describe('document activation persistence (ADR-0024 seam)', () => { + beforeEach(() => { + setActivePinia(createTestingPinia({ stubActions: false })) + }) + + it('serializes byte-identically across Base/ECS/Nodes-2.0 activation cycles and save/reload', async () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + + const baseline = serializeDocumentScope(scope) + expect(baseline.length).toBeGreaterThan(2) + + const { registry, documentId } = registerLoadedDocument('wf', scope) + const coordinator = loadedCoordinator() + const log: string[] = [] + + for (const mode of ['base', 'ecs', 'nodes2']) { + const outcome = await coordinator.activate( + documentId, + modeBinding(log, mode) + ) + expect(outcome.status).toBe('activated') + expect(serializeDocumentScope(scope)).toEqual(baseline) + expect(coordinator.deactivate(documentId)).toBe(true) + expect(serializeDocumentScope(scope)).toEqual(baseline) + } + expect(log).toEqual([ + 'attach:base', + 'detach:base', + 'attach:ecs', + 'detach:ecs', + 'attach:nodes2', + 'detach:nodes2' + ]) + + const ticket = registry.beginSave(documentId) + expect(ticket).not.toBeNull() + const savedBytes = serializeDocumentScope(scope) + expect(registry.completeSave(ticket!)).toBe(true) + expect(registry.persistenceStateOf(documentId)).toBe('clean') + + const reloadSession = createDetachedTargetSession('wf') + reloadSession.enqueue({ + workflowId: 'wf', + seq: 1, + update: session.encodeCommittedState() + }) + expect( + reloadSession.commitNext(createTargetFrameApplyPort(mutations)).status + ).toBe('committed') + + expect(serializeDocumentScope(scope)).toEqual(savedBytes) + expect(serializeDocumentScope(scope)).toEqual(baseline) + + session.destroy() + reloadSession.destroy() + host.destroy() + }) + + it('reloads byte-identically while a different renderer mode is active', async () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + const baseline = serializeDocumentScope(scope) + + const otherScope = scopeFor('other-root') + const { documentId: otherDocumentId } = registerLoadedDocument( + 'wf-other', + otherScope + ) + const coordinator = loadedCoordinator() + await coordinator.activate(otherDocumentId, modeBinding([], 'nodes2')) + + const reloadSession = createDetachedTargetSession('wf') + reloadSession.enqueue({ + workflowId: 'wf', + seq: 1, + update: session.encodeCommittedState() + }) + expect( + reloadSession.commitNext(createTargetFrameApplyPort(mutations)).status + ).toBe('committed') + + expect(serializeDocumentScope(scope)).toEqual(baseline) + expect(coordinator.activeDocumentId()).toBe(otherDocumentId) + + session.destroy() + reloadSession.destroy() + host.destroy() + }) + + it('preserves original stamps and DQ-11(c) node incarnations through the staged commit path', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + + const committed = new Y.Doc() + Y.applyUpdate(committed, session.encodeCommittedState()) + + expect(readStamps(committed)).toEqual(readStamps(host)) + expect([...appliedOpIds(committed)].sort()).toEqual( + [...appliedOpIds(host)].sort() + ) + for (const id of ['1', '2']) { + const hostIncarnation = nodesMap(host).get(id)?.get(NODE_INCARNATION_KEY) + expect(typeof hostIncarnation).toBe('string') + expect(nodesMap(committed).get(id)?.get(NODE_INCARNATION_KEY)).toBe( + hostIncarnation + ) + } + + committed.destroy() + session.destroy() + host.destroy() + }) + + it('isolates agent frames from the active canvas: frames land in their registry-resolved scope only', async () => { + const scopeA = scopeFor('root-a') + const scopeB = scopeFor('root-b') + const mutationsA = mutationsFor(scopeA) + const mutationsB = mutationsFor(scopeB) + + const hostA = mint(workflowJson, catalog) + const sessionA = createDetachedTargetSession('wf-a') + commitHostState(sessionA, 'wf-a', hostA, mutationsA) + const bytesA = serializeDocumentScope(scopeA) + + const registryA = registerLoadedDocument('wf-a', scopeA) + const registryB = registerLoadedDocument('wf-b', scopeB) + const registry = useGraphDocumentStore() + + const coordinator = loadedCoordinator() + await coordinator.activate(registryA.documentId, modeBinding([], 'base')) + + const target = registry.resolveWorkflowTarget('wf-b') + expect(target?.documentId).toBe(registryB.documentId) + expect(target?.scope).toEqual(scopeB) + expect(target?.documentId).not.toBe(coordinator.activeDocumentId()) + + const hostB = mint({ nodes: [workflowJson.nodes[1]!], links: [] }, catalog) + const sessionB = createDetachedTargetSession('wf-b') + commitHostState(sessionB, 'wf-b', hostB, mutationsB) + + expect(serializeDocumentScope(scopeA)).toEqual(bytesA) + expect(serializeDocumentScope(scopeB)).not.toEqual(bytesA) + + sessionA.destroy() + sessionB.destroy() + hostA.destroy() + hostB.destroy() + }) + + it('recovers a detached target across reconnect via the last committed state vector', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + const baseline = serializeDocumentScope(scope) + + const beforeMissed = Y.encodeStateVector(host) + nodesMap(host).get('1')?.set('title', 'Renamed while offline') + const missedFrame = { + workflowId: 'wf', + seq: 2, + update: Y.encodeStateAsUpdate(host, beforeMissed) + } + nodesMap(host).get('1')?.set('color', '#123456') + + expect(session.enqueue(missedFrame).status).toBe('queued') + const gap = session.enqueue({ + workflowId: 'wf', + seq: 4, + update: Y.encodeStateAsUpdate(host, Y.encodeStateVector(host)) + }) + expect(gap.status).toBe('gap') + expect(serializeDocumentScope(scope)).toEqual(baseline) + + session.beginResync() + session.enqueue({ + workflowId: 'wf', + seq: 4, + update: Y.encodeStateAsUpdate(host, session.recoveryStateVector()) + }) + expect( + session.commitNext(createTargetFrameApplyPort(mutations)).status + ).toBe('committed') + + const committed = new Y.Doc() + Y.applyUpdate(committed, session.encodeCommittedState()) + expect(nodesMap(committed).toJSON()).toEqual(nodesMap(host).toJSON()) + committed.destroy() + + expect(serializeDocumentScope(scope)).not.toEqual(baseline) + + session.destroy() + host.destroy() + }) + + it('doc_reset starts a new lineage whose fresh mint replaces the scope content', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + const host = mint(workflowJson, catalog) + const session = createDetachedTargetSession('wf') + commitHostState(session, 'wf', host, mutations) + const oldLineage = session.snapshot().lineage + + session.resetLineage(10) + expect(session.snapshot().lineage).not.toBe(oldLineage) + + const remintedHost = mint( + { nodes: [workflowJson.nodes[0]!], links: [] }, + catalog + ) + commitHostState(session, 'wf', remintedHost, mutations, 11) + + const committed = new Y.Doc() + Y.applyUpdate(committed, session.encodeCommittedState()) + expect([...nodesMap(committed).keys()]).toEqual(['1']) + committed.destroy() + + const reloaded = serializeDocumentScope(scope) + const parsed = JSON.parse(new TextDecoder().decode(reloaded)) as { + nodes: { id: string }[] + links: unknown[] + } + expect(parsed.nodes.map(({ id }) => id)).toEqual(['1']) + expect(parsed.links).toEqual([]) + + session.destroy() + host.destroy() + remintedHost.destroy() + }) +}) diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts new file mode 100644 index 00000000000..c9b35142253 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts @@ -0,0 +1,139 @@ +import { + linksMap, + nodesMap, + OPAQUE_WIDGETS_KEY +} from '@comfyorg/comfy-multi-player' +import * as Y from 'yjs' + +import type { + TargetFrame, + TargetFrameApplyPort +} from '@/core/graph/document/detachedTargetSession' +import type { + GraphMutations, + SemanticLinkPayload, + SemanticNodePayload +} from '@/core/graph/graphMutations' +import type { RemoteMutationContext } from '@/types/graphMutationContext' +import { compareNodeIds, toNodeId } from '@/types/nodeId' + +function plain(value: unknown): unknown { + if (value instanceof Y.Map || value instanceof Y.Array) return value.toJSON() + return structuredClone(value) +} + +/** + * Staged-doc counterpart of the adapter's live readers: the adapter reads + * incremental observer effects off its bound follower doc, while this reads + * whole snapshots off a detached session's staged doc. Kept local because the + * projection must never depend on adapter internals (ADR-0024's seam). + */ +function readSemanticNode(doc: Y.Doc, id: string): SemanticNodePayload | null { + const source = nodesMap(doc).get(id) + if (!(source instanceof Y.Map)) return null + const type = source.get('type') + if (typeof type !== 'string' || type.length === 0) return null + + const payload: Record = {} + source.forEach((value, key) => { + if (key === 'widgets' && value instanceof Y.Map) { + payload.widgets_values = value.toJSON() + } else if (key === OPAQUE_WIDGETS_KEY) { + payload.widgets_values = plain(value) + } else { + payload[key] = plain(value) + } + }) + payload.id = id + payload.type = type + return payload as SemanticNodePayload +} + +function readNodeSlots( + doc: Y.Doc, + id: string, + key: TKey +): SemanticLinkPayload[TKey extends 'inputs' + ? 'targetInputs' + : 'originOutputs'] { + const value = nodesMap(doc).get(id)?.get(key) + return ( + value instanceof Y.Array ? value.toJSON() : [] + ) as SemanticLinkPayload[TKey extends 'inputs' + ? 'targetInputs' + : 'originOutputs'] +} + +function readSemanticLink(doc: Y.Doc, id: string): SemanticLinkPayload | null { + const raw = linksMap(doc).get(id) + const tuple = raw instanceof Y.Array ? raw.toArray() : raw + if (!Array.isArray(tuple) || tuple.length < 5) return null + const linkId = Number(tuple[0] ?? id) + const originSlot = Number(tuple[2]) + const targetSlot = Number(tuple[4]) + if ( + !Number.isInteger(linkId) || + tuple[1] == null || + tuple[3] == null || + !Number.isInteger(originSlot) || + !Number.isInteger(targetSlot) + ) { + return null + } + return { + id: linkId, + originNodeId: String(tuple[1]), + originSlot, + targetNodeId: String(tuple[3]), + targetSlot, + type: + typeof tuple[5] === 'string' || typeof tuple[5] === 'number' + ? tuple[5] + : '*', + originOutputs: readNodeSlots(doc, String(tuple[1]), 'outputs'), + targetInputs: readNodeSlots(doc, String(tuple[3]), 'inputs') + } +} + +function frameContext(frame: TargetFrame): RemoteMutationContext { + const opIds = frame.opIds?.filter((id) => id.length > 0) + return { + source: 'agent-remote', + actor: frame.actor ?? 'agent-replay', + opId: opIds?.at(-1) ?? 'replay', + ...(opIds && opIds.length > 0 && { opIds: [...opIds] }) + } +} + +/** + * Full-snapshot projection of a detached target session's staged document + * into the ECS stores through the target's `GraphMutations` composite. One + * atomic batch clears the scope and rebuilds it from the staged doc, so a + * validation failure anywhere leaves the stores untouched and the frame + * queued (the session's all-or-nothing commit contract). + */ +export function createTargetFrameApplyPort( + mutations: GraphMutations +): TargetFrameApplyPort { + return { + apply(frame, stagedDoc) { + const nodeIds = [...nodesMap(stagedDoc).keys()].sort((left, right) => + compareNodeIds(toNodeId(left), toNodeId(right)) + ) + const linkIds = [...linksMap(stagedDoc).keys()].sort( + (left, right) => Number(left) - Number(right) + ) + return mutations.batch(frameContext(frame), (batch) => { + batch.clearSemanticGraph() + for (const id of nodeIds) { + const payload = readSemanticNode(stagedDoc, id) + if (payload) batch.reconcileNode(payload) + } + for (const id of linkIds) { + const link = readSemanticLink(stagedDoc, id) + if (link) batch.connect(link) + } + }) + } + } +} From 712c7d89617305f57ddb44123ba4cc17934ecdd6 Mon Sep 17 00:00:00 2001 From: bymyself Date: Mon, 31 Aug 2026 16:05:00 +0000 Subject: [PATCH 02/24] feat(agent): track exhausted reconnect retries --- src/platform/telemetry/TelemetryRegistry.ts | 5 +++ .../cloud/PostHogTelemetryProvider.ts | 5 +++ src/platform/telemetry/types.ts | 8 +++++ .../agent/crdt/useAgentCrdtFollower.test.ts | 31 +++++++++++++++++++ .../agent/crdt/useAgentCrdtFollower.ts | 31 ++++++++++++++++++- 5 files changed, 79 insertions(+), 1 deletion(-) diff --git a/src/platform/telemetry/TelemetryRegistry.ts b/src/platform/telemetry/TelemetryRegistry.ts index b5c1a307023..4294bd878f5 100644 --- a/src/platform/telemetry/TelemetryRegistry.ts +++ b/src/platform/telemetry/TelemetryRegistry.ts @@ -6,6 +6,7 @@ import type { AgentNodeTaggedMetadata, AgentPanelClosedMetadata, AgentPanelOpenedMetadata, + AgentReconnectFailedMetadata, AgentWorkflowAppliedMetadata, AuthErrorMetadata, AuthMetadata, @@ -373,6 +374,10 @@ export class TelemetryRegistry implements TelemetryDispatcher { this.dispatch((provider) => provider.trackAgentWorkflowApplied?.(metadata)) } + trackAgentReconnectFailed(metadata: AgentReconnectFailedMetadata): void { + this.dispatch((provider) => provider.trackAgentReconnectFailed?.(metadata)) + } + trackWidgetFavoriteToggled(metadata: WidgetFavoriteToggledMetadata): void { this.dispatch((provider) => provider.trackWidgetFavoriteToggled?.(metadata)) } diff --git a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts index ae7123778aa..0374a6925bd 100644 --- a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts @@ -18,6 +18,7 @@ import type { AgentNodeTaggedMetadata, AgentPanelClosedMetadata, AgentPanelOpenedMetadata, + AgentReconnectFailedMetadata, AgentWorkflowAppliedMetadata, AuthErrorMetadata, AuthMetadata, @@ -703,6 +704,10 @@ export class PostHogTelemetryProvider implements TelemetryProvider { this.trackEvent(TelemetryEvents.AGENT_WORKFLOW_APPLIED, metadata) } + trackAgentReconnectFailed(metadata: AgentReconnectFailedMetadata): void { + this.trackEvent(TelemetryEvents.AGENT_RECONNECT_FAILED, metadata) + } + trackWidgetFavoriteToggled(metadata: WidgetFavoriteToggledMetadata): void { this.trackEvent(TelemetryEvents.WIDGET_FAVORITE_TOGGLED, metadata) } diff --git a/src/platform/telemetry/types.ts b/src/platform/telemetry/types.ts index bcd0fdd489a..f4ba6e762ca 100644 --- a/src/platform/telemetry/types.ts +++ b/src/platform/telemetry/types.ts @@ -580,6 +580,12 @@ export interface AgentWorkflowAppliedMetadata extends Record { workflow_id: string target: 'active_tab_switch' | 'active_tab_open' } +export interface AgentReconnectFailedMetadata extends Record { + attempt: number + error_class: 'subscription_refused' + retryable: boolean + reconnect_duration_ms: number +} /** * Widget (input/parameter) favorite toggle tracking metadata. @@ -1075,6 +1081,7 @@ export interface TelemetryProvider { trackAgentNodeTagged?(metadata: AgentNodeTaggedMetadata): void trackAgentAttachButtonClicked?(): void trackAgentWorkflowApplied?(metadata: AgentWorkflowAppliedMetadata): void + trackAgentReconnectFailed?(metadata: AgentReconnectFailedMetadata): void // Right side panel widget favorite events trackWidgetFavoriteToggled?(metadata: WidgetFavoriteToggledMetadata): void @@ -1238,6 +1245,7 @@ export const TelemetryEvents = { AGENT_NODE_TAGGED: 'app:agent_node_tagged', AGENT_ATTACH_BUTTON_CLICKED: 'app:agent_attach_button_clicked', AGENT_WORKFLOW_APPLIED: 'app:agent_workflow_applied', + AGENT_RECONNECT_FAILED: 'app:agent_reconnect_failed', // Right Side Panel Widget Favorites WIDGET_FAVORITE_TOGGLED: 'app:widget_favorite_toggled', diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index 02a7da9b93a..e3125c6e1cb 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -49,6 +49,10 @@ const adapterState = vi.hoisted(() => ({ destroy: vi.fn() })) +const telemetryState = vi.hoisted(() => ({ + trackAgentReconnectFailed: vi.fn() +})) + const apiState = vi.hoisted(() => { const target = new EventTarget() return { @@ -99,6 +103,9 @@ vi.mock('./devPanelLog', () => ({ })) vi.mock('@/scripts/api', () => ({ api: apiState.api })) +vi.mock('@/platform/telemetry', () => ({ + useTelemetry: () => telemetryState +})) vi.mock('@/scripts/app', () => ({ app: { graph: null, canvas: null } })) vi.mock('@/stores/authStore', () => ({ useAuthStore: () => ({ userId: 'user-1' }) @@ -188,6 +195,7 @@ describe('useAgentCrdtFollower', () => { dispatchFrame('doc_subscribed', { ok: false }) vi.advanceTimersByTime(60_000) expect(bridge().resubscribe).toHaveBeenCalledTimes(6) + expect(telemetryState.trackAgentReconnectFailed).not.toHaveBeenCalled() unmount() }) @@ -205,6 +213,29 @@ describe('useAgentCrdtFollower', () => { unmount() }) + it('reports retry exhaustion exactly once with normalized metadata', () => { + vi.useFakeTimers() + vi.setSystemTime(1_000) + const { unmount } = mountFollower('wf-1') + apiState.target.dispatchEvent(new Event('reconnected')) + + for (let attempt = 0; attempt < 6; attempt++) { + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(500 * 2 ** attempt) + } + dispatchFrame('doc_subscribed', { ok: false }) + dispatchFrame('doc_subscribed', { ok: false }) + + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledOnce() + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledWith({ + attempt: 6, + error_class: 'subscription_refused', + retryable: false, + reconnect_duration_ms: 31_500 + }) + unmount() + }) + it('FE-1901: a workflow switch cancels the pending retry', () => { vi.useFakeTimers() const { unmount, workflowId } = mountFollower('wf-1') diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index fa62a6d6fef..00db7a8bbe5 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -1,6 +1,7 @@ import { computed, onBeforeUnmount, readonly, ref, watch } from 'vue' import type { Ref } from 'vue' +import { useTelemetry } from '@/platform/telemetry' import { api } from '@/scripts/api' import type { RemoteMutationContext } from '@/types/graphMutationContext' import { createUuidv4 } from '@/utils/uuid' @@ -172,6 +173,8 @@ export function useAgentCrdtFollower( const SUBSCRIBE_RETRY_MAX_ATTEMPTS = 6 let subscribeRetryTimer: ReturnType | null = null let subscribeRetryAttempt = 0 + let subscribeRetryStartedAt: number | null = null + let subscribeRetryFailureReported = false // The recency heartbeat: armed only while a subscribe is CONFIRMED (bound + // healthy by definition), slid forward by every doc-scoped frame, cancelled @@ -205,11 +208,35 @@ export function useAgentCrdtFollower( subscribeRetryTimer = null } subscribeRetryAttempt = 0 + subscribeRetryStartedAt = null + subscribeRetryFailureReported = false + } + + const reportSubscribeRetryExhausted = (): void => { + if ( + subscribeRetryFailureReported || + subscribeRetryStartedAt === null || + subscribeRetryAttempt < SUBSCRIBE_RETRY_MAX_ATTEMPTS + ) + return + subscribeRetryFailureReported = true + useTelemetry()?.trackAgentReconnectFailed({ + attempt: subscribeRetryAttempt, + error_class: 'subscription_refused', + retryable: false, + reconnect_duration_ms: Math.max( + 0, + Math.round(performance.now() - subscribeRetryStartedAt) + ) + }) } const scheduleSubscribeRetry = (): void => { if (subscribeRetryTimer !== null) return - if (subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) return + if (subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) { + reportSubscribeRetryExhausted() + return + } const target = subscribedWorkflowId.value if (target === null) return const delay = SUBSCRIBE_RETRY_BASE_MS * 2 ** subscribeRetryAttempt @@ -336,6 +363,8 @@ export function useAgentCrdtFollower( ) } const onReconnected: EventListener = () => { + clearSubscribeRetry() + subscribeRetryStartedAt = performance.now() connected.value = false clearStaleProbe() recordDevEvent('reconnected', null) From b3c864f917862f0ec4e13c9212907e1e5e6a3678 Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 05:27:41 +0000 Subject: [PATCH 03/24] fix(agent): time every subscribe retry cycle Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646256 --- src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 00db7a8bbe5..6841bc4ce72 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -215,7 +215,6 @@ export function useAgentCrdtFollower( const reportSubscribeRetryExhausted = (): void => { if ( subscribeRetryFailureReported || - subscribeRetryStartedAt === null || subscribeRetryAttempt < SUBSCRIBE_RETRY_MAX_ATTEMPTS ) return @@ -226,7 +225,7 @@ export function useAgentCrdtFollower( retryable: false, reconnect_duration_ms: Math.max( 0, - Math.round(performance.now() - subscribeRetryStartedAt) + Math.round(performance.now() - (subscribeRetryStartedAt ?? performance.now())) ) }) } @@ -239,6 +238,7 @@ export function useAgentCrdtFollower( } const target = subscribedWorkflowId.value if (target === null) return + subscribeRetryStartedAt ??= performance.now() const delay = SUBSCRIBE_RETRY_BASE_MS * 2 ** subscribeRetryAttempt subscribeRetryAttempt += 1 subscribeRetryTimer = setTimeout(() => { From fb084784c8f88b86f80753917b0b75d3e41a1ecc Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 05:27:49 +0000 Subject: [PATCH 04/24] fix(agent): report silent final subscribe failure Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646258 --- src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 6841bc4ce72..8a95eb04c2d 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -250,6 +250,8 @@ export function useAgentCrdtFollower( workflowId: target }) bridge.resubscribe() + if (subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) + reportSubscribeRetryExhausted() }, delay) } From 7b582b293b35a80754ba271a26107a2ee9479444 Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 05:27:58 +0000 Subject: [PATCH 05/24] fix(agent): preserve retry budget across reconnects Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646261 --- src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 8a95eb04c2d..956b7ae204d 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -365,8 +365,6 @@ export function useAgentCrdtFollower( ) } const onReconnected: EventListener = () => { - clearSubscribeRetry() - subscribeRetryStartedAt = performance.now() connected.value = false clearStaleProbe() recordDevEvent('reconnected', null) From 60974726760198308e62df57684634cb127c2c58 Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 05:28:06 +0000 Subject: [PATCH 06/24] fix(agent): mark subscribe exhaustion recoverable Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646265 --- src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 956b7ae204d..e37ef1ea9c8 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -222,7 +222,7 @@ export function useAgentCrdtFollower( useTelemetry()?.trackAgentReconnectFailed({ attempt: subscribeRetryAttempt, error_class: 'subscription_refused', - retryable: false, + retryable: true, reconnect_duration_ms: Math.max( 0, Math.round(performance.now() - (subscribeRetryStartedAt ?? performance.now())) From db960a7f654f1403637b587e2ea6e80608c95030 Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 05:28:31 +0000 Subject: [PATCH 07/24] test(agent): pin reconnect exhaustion timing Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646267 Covers https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646258 and https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646261 --- .../agent/crdt/useAgentCrdtFollower.test.ts | 24 ++++++++++++++----- 1 file changed, 18 insertions(+), 6 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index e3125c6e1cb..7679d30ec61 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -195,7 +195,7 @@ describe('useAgentCrdtFollower', () => { dispatchFrame('doc_subscribed', { ok: false }) vi.advanceTimersByTime(60_000) expect(bridge().resubscribe).toHaveBeenCalledTimes(6) - expect(telemetryState.trackAgentReconnectFailed).not.toHaveBeenCalled() + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledOnce() unmount() }) @@ -214,28 +214,40 @@ describe('useAgentCrdtFollower', () => { }) it('reports retry exhaustion exactly once with normalized metadata', () => { - vi.useFakeTimers() + vi.useFakeTimers({ toFake: ['performance', 'setTimeout', 'clearTimeout'] }) vi.setSystemTime(1_000) const { unmount } = mountFollower('wf-1') - apiState.target.dispatchEvent(new Event('reconnected')) for (let attempt = 0; attempt < 6; attempt++) { dispatchFrame('doc_subscribed', { ok: false }) vi.advanceTimersByTime(500 * 2 ** attempt) } - dispatchFrame('doc_subscribed', { ok: false }) - dispatchFrame('doc_subscribed', { ok: false }) expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledOnce() expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledWith({ attempt: 6, error_class: 'subscription_refused', - retryable: false, + retryable: true, reconnect_duration_ms: 31_500 }) unmount() }) + it('preserves the bounded subscribe retry budget across reconnects', () => { + vi.useFakeTimers() + const { unmount } = mountFollower('wf-1') + + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(500) + dispatchFrame('doc_subscribed', { ok: false }) + + apiState.target.dispatchEvent(new Event('reconnected')) + vi.advanceTimersByTime(1_000) + + expect(bridge().resubscribe).toHaveBeenCalledTimes(3) + unmount() + }) + it('FE-1901: a workflow switch cancels the pending retry', () => { vi.useFakeTimers() const { unmount, workflowId } = mountFollower('wf-1') From 3b39fcc2d0df44f0f8c76bb3ea6c667ab9c0be80 Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 05:31:36 +0000 Subject: [PATCH 08/24] style(agent): format retry duration calculation Follow-up to https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3900646256 --- src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index e37ef1ea9c8..21464b53ffd 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -225,7 +225,9 @@ export function useAgentCrdtFollower( retryable: true, reconnect_duration_ms: Math.max( 0, - Math.round(performance.now() - (subscribeRetryStartedAt ?? performance.now())) + Math.round( + performance.now() - (subscribeRetryStartedAt ?? performance.now()) + ) ) }) } From ce086530d8daa30e60af3445e08137c8ee1871f3 Mon Sep 17 00:00:00 2001 From: bymyself Date: Tue, 1 Sep 2026 20:29:20 +0000 Subject: [PATCH 09/24] fix(agent): use assert() for cross-target frame guard Replace throw new Error() in assertTarget() with the centralized assert() helper from ADR 0019's recoverable diagnostics contract. The message is static and names the invariant. --- src/core/graph/document/detachedTargetSession.ts | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/core/graph/document/detachedTargetSession.ts b/src/core/graph/document/detachedTargetSession.ts index d0f24176bcc..b2edad1ba2f 100644 --- a/src/core/graph/document/detachedTargetSession.ts +++ b/src/core/graph/document/detachedTargetSession.ts @@ -1,5 +1,6 @@ import * as Y from 'yjs' +import { assert } from '@/base/assert' import { createUuidv4 } from '@/utils/uuid' /** @@ -92,12 +93,10 @@ export function createDetachedTargetSession( let queue: TargetFrame[] = [] function assertTarget(frameWorkflowId: string): void { - if (frameWorkflowId !== workflowId) { - throw new Error( - `DetachedTargetSession(${workflowId}) received a frame addressed to ` + - `"${frameWorkflowId}"; frames must never cross targets` - ) - } + assert( + frameWorkflowId === workflowId, + `DetachedTargetSession: frame addressed to ${frameWorkflowId} does not match session target ${workflowId}; frames must never cross targets` + ) } function enqueue(frame: TargetFrame): EnqueueResult { From 0e99677540814cdd8a9e3428fc0d27d329f8e242 Mon Sep 17 00:00:00 2001 From: Christian Byrne Date: Tue, 1 Sep 2026 22:55:02 -0700 Subject: [PATCH 10/24] fix(agent): report reconnect exhaustion only after the final attempt fails The sixth subscribe attempt reported agent_reconnect_failed right after sending, before the server answered, so a confirmed final attempt still emitted the failure event. Arm a deadline of one more backoff step instead: ok:true cancels it via clearSubscribeRetry, ok:false on the final attempt reports immediately, silence reports at the deadline. DetachedTargetSession: assert() only throws in DEV, so the cross-target guard had become fail-open in production and interpolated workflow ids into a reporter-bound message. Keep the assert with a static message and return { status: 'rejected', reason: 'cross-target' } so enqueue fails closed in every build. Tests cover both DEV and non-DEV paths. --- .../document/detachedTargetSession.test.ts | 43 ++++++++++++++--- .../graph/document/detachedTargetSession.ts | 17 +++++-- .../agent/crdt/useAgentCrdtFollower.test.ts | 47 +++++++++++++++++++ .../agent/crdt/useAgentCrdtFollower.ts | 23 +++++++-- 4 files changed, 116 insertions(+), 14 deletions(-) diff --git a/src/core/graph/document/detachedTargetSession.test.ts b/src/core/graph/document/detachedTargetSession.test.ts index d3f3d2e0e38..dc83c1cbbf3 100644 --- a/src/core/graph/document/detachedTargetSession.test.ts +++ b/src/core/graph/document/detachedTargetSession.test.ts @@ -1,4 +1,4 @@ -import { describe, expect, it } from 'vitest' +import { afterEach, describe, expect, it, vi } from 'vitest' import * as Y from 'yjs' import type { @@ -6,6 +6,7 @@ import type { TargetFrameApplyPort } from '@/core/graph/document/detachedTargetSession' import { createDetachedTargetSession } from '@/core/graph/document/detachedTargetSession' +import { setAssertReporter } from '@/base/assert' const WORKFLOW_ID = 'wf-detached' @@ -303,15 +304,43 @@ describe('createDetachedTargetSession', () => { freshHost.destroy() }) - it('rejects frames addressed to another target loudly', () => { - const session = createDetachedTargetSession(WORKFLOW_ID) - const stranger = createFrameSource('wf-other') + describe('cross-target frames', () => { + afterEach(() => { + setAssertReporter(null) + }) + + it('rejects frames addressed to another target loudly in DEV', () => { + vi.stubEnv('DEV', true) + vi.spyOn(console, 'error').mockImplementation(() => {}) + const session = createDetachedTargetSession(WORKFLOW_ID) + const stranger = createFrameSource('wf-other') + + expect(() => + session.enqueue( + stranger.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + ).toThrow(/frames must never cross targets/) + }) - expect(() => - session.enqueue( + it('fails closed outside DEV: reported, never queued', () => { + vi.stubEnv('DEV', false) + vi.spyOn(console, 'error').mockImplementation(() => {}) + const reported: string[] = [] + setAssertReporter((message) => reported.push(message)) + const session = createDetachedTargetSession(WORKFLOW_ID) + const stranger = createFrameSource('wf-other') + + const result = session.enqueue( stranger.frame((doc) => setNode(doc, '1', { type: 'Source' })) ) - ).toThrow(/frames must never cross targets/) + + expect(result).toEqual({ status: 'rejected', reason: 'cross-target' }) + expect(reported).toHaveLength(1) + expect(reported[0]).toMatch(/frames must never cross targets/) + expect(reported[0]).not.toContain('wf-other') + expect(session.commitNext(acceptAll).status).toBe('idle') + expect(session.snapshot().committedSeq).toBeNull() + }) }) it('isCommitted answers for any sequence at or below the committed head of the same lineage', () => { diff --git a/src/core/graph/document/detachedTargetSession.ts b/src/core/graph/document/detachedTargetSession.ts index b2edad1ba2f..ab6c00dcc65 100644 --- a/src/core/graph/document/detachedTargetSession.ts +++ b/src/core/graph/document/detachedTargetSession.ts @@ -36,6 +36,8 @@ export type EnqueueResult = /** Queue bound exceeded; queue discarded, resync required. */ | { status: 'overflow'; discardedFrames: number } | { status: 'resync-required' } + /** Frame addressed to another target; never queued, in every build. */ + | { status: 'rejected'; reason: 'cross-target' } export type CommitResult = | { status: 'idle' } @@ -92,15 +94,22 @@ export function createDetachedTargetSession( let expectedSeq: number | null = null let queue: TargetFrame[] = [] - function assertTarget(frameWorkflowId: string): void { + /** + * Loud in DEV (throws), reported in production, and fail-closed in both: + * `assert` returns in non-DEV builds, so callers must still honour `false`. + */ + function isOwnTarget(frameWorkflowId: string): boolean { + const matches = frameWorkflowId === workflowId assert( - frameWorkflowId === workflowId, - `DetachedTargetSession: frame addressed to ${frameWorkflowId} does not match session target ${workflowId}; frames must never cross targets` + matches, + 'DetachedTargetSession: frame addressed to another target; frames must never cross targets' ) + return matches } function enqueue(frame: TargetFrame): EnqueueResult { - assertTarget(frame.workflowId) + if (!isOwnTarget(frame.workflowId)) + return { status: 'rejected', reason: 'cross-target' } if (needsResync) return { status: 'resync-required' } const lastAcceptedSeq = queue.at(-1)?.seq ?? committedSeq diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index 7679d30ec61..6f2bc10a106 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -222,6 +222,12 @@ describe('useAgentCrdtFollower', () => { dispatchFrame('doc_subscribed', { ok: false }) vi.advanceTimersByTime(500 * 2 ** attempt) } + // The final attempt was sent but not yet answered: no verdict yet. + expect(telemetryState.trackAgentReconnectFailed).not.toHaveBeenCalled() + + dispatchFrame('doc_subscribed', { ok: false }) + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(60_000) expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledOnce() expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledWith({ @@ -233,6 +239,47 @@ describe('useAgentCrdtFollower', () => { unmount() }) + it('does not report exhaustion when the final attempt is confirmed', () => { + vi.useFakeTimers() + const { unmount, status } = mountFollower('wf-1') + + for (let attempt = 0; attempt < 6; attempt++) { + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(500 * 2 ** attempt) + } + expect(bridge().resubscribe).toHaveBeenCalledTimes(6) + + dispatchFrame('doc_subscribed', { ok: true }) + vi.advanceTimersByTime(60_000) + + expect(telemetryState.trackAgentReconnectFailed).not.toHaveBeenCalled() + expect(status().connected).toBe(true) + unmount() + }) + + it('reports exhaustion when the final attempt is never answered', () => { + vi.useFakeTimers({ toFake: ['performance', 'setTimeout', 'clearTimeout'] }) + vi.setSystemTime(1_000) + const { unmount } = mountFollower('wf-1') + + for (let attempt = 0; attempt < 6; attempt++) { + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(500 * 2 ** attempt) + } + expect(bridge().resubscribe).toHaveBeenCalledTimes(6) + + // Silence for one more backoff step (500 * 2 ** 6) counts as a refusal. + vi.advanceTimersByTime(32_000 - 1) + expect(telemetryState.trackAgentReconnectFailed).not.toHaveBeenCalled() + vi.advanceTimersByTime(1) + + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledOnce() + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledWith( + expect.objectContaining({ attempt: 6, reconnect_duration_ms: 63_500 }) + ) + unmount() + }) + it('preserves the bounded subscribe retry budget across reconnects', () => { vi.useFakeTimers() const { unmount } = mountFollower('wf-1') diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 21464b53ffd..5575cca6892 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -218,6 +218,11 @@ export function useAgentCrdtFollower( subscribeRetryAttempt < SUBSCRIBE_RETRY_MAX_ATTEMPTS ) return + // The pending timer here is the final attempt's answer deadline. + if (subscribeRetryTimer !== null) { + clearTimeout(subscribeRetryTimer) + subscribeRetryTimer = null + } subscribeRetryFailureReported = true useTelemetry()?.trackAgentReconnectFailed({ attempt: subscribeRetryAttempt, @@ -233,11 +238,13 @@ export function useAgentCrdtFollower( } const scheduleSubscribeRetry = (): void => { - if (subscribeRetryTimer !== null) return + // A refusal after the final attempt is the exhaustion signal itself; it + // must win over the answer deadline armed below. if (subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) { reportSubscribeRetryExhausted() return } + if (subscribeRetryTimer !== null) return const target = subscribedWorkflowId.value if (target === null) return subscribeRetryStartedAt ??= performance.now() @@ -252,8 +259,18 @@ export function useAgentCrdtFollower( workflowId: target }) bridge.resubscribe() - if (subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) - reportSubscribeRetryExhausted() + // The final attempt has no retry to reveal a silently dropped answer, + // so treat silence for one more backoff step as a refusal. A confirmed + // subscribe cancels this through clearSubscribeRetry. + if (subscribeRetryAttempt >= SUBSCRIBE_RETRY_MAX_ATTEMPTS) { + subscribeRetryTimer = setTimeout( + () => { + subscribeRetryTimer = null + reportSubscribeRetryExhausted() + }, + SUBSCRIBE_RETRY_BASE_MS * 2 ** subscribeRetryAttempt + ) + } }, delay) } From 93aa81103ea8e3632e2ceb379d05f12af734dcaf Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 2 Sep 2026 07:20:42 +0000 Subject: [PATCH 11/24] test(agent): clarify retryable reconnect exhaustion Addresses https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911129088 --- .../agent/crdt/useAgentCrdtFollower.test.ts | 20 ++++++++++++++----- 1 file changed, 15 insertions(+), 5 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index 6f2bc10a106..cf2a50a3b56 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -280,18 +280,28 @@ describe('useAgentCrdtFollower', () => { unmount() }) - it('preserves the bounded subscribe retry budget across reconnects', () => { + it('preserves the retry budget across reconnects but leaves bridge recovery active', () => { vi.useFakeTimers() const { unmount } = mountFollower('wf-1') + for (let attempt = 0; attempt < 6; attempt++) { + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(500 * 2 ** attempt) + } dispatchFrame('doc_subscribed', { ok: false }) - vi.advanceTimersByTime(500) - dispatchFrame('doc_subscribed', { ok: false }) + expect(telemetryState.trackAgentReconnectFailed).toHaveBeenCalledWith( + expect.objectContaining({ retryable: true }) + ) + bridge().resubscribe.mockClear() apiState.target.dispatchEvent(new Event('reconnected')) - vi.advanceTimersByTime(1_000) + dispatchFrame('doc_subscribed', { ok: false }) + vi.advanceTimersByTime(60_000) + expect(bridge().resubscribe).toHaveBeenCalledOnce() - expect(bridge().resubscribe).toHaveBeenCalledTimes(3) + bridge().reconcile.mockClear() + apiState.target.dispatchEvent(new Event('status')) + expect(bridge().reconcile).toHaveBeenCalledOnce() unmount() }) From bc37fb3fcee25bd3c663002aae78b278fe1afe18 Mon Sep 17 00:00:00 2001 From: bymyself Date: Wed, 2 Sep 2026 08:05:54 +0000 Subject: [PATCH 12/24] feat(agent): track reconnect start on socket reconnect Emits app:agent_reconnect_started once per socket-level reconnect, retaining the follower document and starting state-vector resubscription. Only reports when a workflow was already bound; a reconnect firing before any subscribe intent exists is the initial-open case, not a loss/recovery. Payload: disconnect_class, attempt (reset on confirmed subscribe), last_seen_version (bridge.lastSequence), offline_duration_ms (since the last doc-scoped frame or confirmed subscribe). Tests: pnpm test:unit src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts --- src/platform/telemetry/TelemetryRegistry.ts | 5 ++ .../cloud/PostHogTelemetryProvider.ts | 5 ++ src/platform/telemetry/types.ts | 8 +++ .../agent/crdt/useAgentCrdtFollower.test.ts | 56 ++++++++++++++++++- .../agent/crdt/useAgentCrdtFollower.ts | 27 +++++++++ 5 files changed, 100 insertions(+), 1 deletion(-) diff --git a/src/platform/telemetry/TelemetryRegistry.ts b/src/platform/telemetry/TelemetryRegistry.ts index 4294bd878f5..cbefbcce818 100644 --- a/src/platform/telemetry/TelemetryRegistry.ts +++ b/src/platform/telemetry/TelemetryRegistry.ts @@ -7,6 +7,7 @@ import type { AgentPanelClosedMetadata, AgentPanelOpenedMetadata, AgentReconnectFailedMetadata, + AgentReconnectStartedMetadata, AgentWorkflowAppliedMetadata, AuthErrorMetadata, AuthMetadata, @@ -378,6 +379,10 @@ export class TelemetryRegistry implements TelemetryDispatcher { this.dispatch((provider) => provider.trackAgentReconnectFailed?.(metadata)) } + trackAgentReconnectStarted(metadata: AgentReconnectStartedMetadata): void { + this.dispatch((provider) => provider.trackAgentReconnectStarted?.(metadata)) + } + trackWidgetFavoriteToggled(metadata: WidgetFavoriteToggledMetadata): void { this.dispatch((provider) => provider.trackWidgetFavoriteToggled?.(metadata)) } diff --git a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts index 0374a6925bd..854602efa3f 100644 --- a/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts +++ b/src/platform/telemetry/providers/cloud/PostHogTelemetryProvider.ts @@ -19,6 +19,7 @@ import type { AgentPanelClosedMetadata, AgentPanelOpenedMetadata, AgentReconnectFailedMetadata, + AgentReconnectStartedMetadata, AgentWorkflowAppliedMetadata, AuthErrorMetadata, AuthMetadata, @@ -708,6 +709,10 @@ export class PostHogTelemetryProvider implements TelemetryProvider { this.trackEvent(TelemetryEvents.AGENT_RECONNECT_FAILED, metadata) } + trackAgentReconnectStarted(metadata: AgentReconnectStartedMetadata): void { + this.trackEvent(TelemetryEvents.AGENT_RECONNECT_STARTED, metadata) + } + trackWidgetFavoriteToggled(metadata: WidgetFavoriteToggledMetadata): void { this.trackEvent(TelemetryEvents.WIDGET_FAVORITE_TOGGLED, metadata) } diff --git a/src/platform/telemetry/types.ts b/src/platform/telemetry/types.ts index f4ba6e762ca..e835657abc2 100644 --- a/src/platform/telemetry/types.ts +++ b/src/platform/telemetry/types.ts @@ -586,6 +586,12 @@ export interface AgentReconnectFailedMetadata extends Record { retryable: boolean reconnect_duration_ms: number } +export interface AgentReconnectStartedMetadata extends Record { + disconnect_class: 'socket_reconnect' + attempt: number + last_seen_version: number + offline_duration_ms: number | null +} /** * Widget (input/parameter) favorite toggle tracking metadata. @@ -1082,6 +1088,7 @@ export interface TelemetryProvider { trackAgentAttachButtonClicked?(): void trackAgentWorkflowApplied?(metadata: AgentWorkflowAppliedMetadata): void trackAgentReconnectFailed?(metadata: AgentReconnectFailedMetadata): void + trackAgentReconnectStarted?(metadata: AgentReconnectStartedMetadata): void // Right side panel widget favorite events trackWidgetFavoriteToggled?(metadata: WidgetFavoriteToggledMetadata): void @@ -1246,6 +1253,7 @@ export const TelemetryEvents = { AGENT_ATTACH_BUTTON_CLICKED: 'app:agent_attach_button_clicked', AGENT_WORKFLOW_APPLIED: 'app:agent_workflow_applied', AGENT_RECONNECT_FAILED: 'app:agent_reconnect_failed', + AGENT_RECONNECT_STARTED: 'app:agent_reconnect_started', // Right Side Panel Widget Favorites WIDGET_FAVORITE_TOGGLED: 'app:widget_favorite_toggled', diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index cf2a50a3b56..fabb001bab7 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -50,7 +50,8 @@ const adapterState = vi.hoisted(() => ({ })) const telemetryState = vi.hoisted(() => ({ - trackAgentReconnectFailed: vi.fn() + trackAgentReconnectFailed: vi.fn(), + trackAgentReconnectStarted: vi.fn() })) const apiState = vi.hoisted(() => { @@ -367,6 +368,59 @@ describe('useAgentCrdtFollower', () => { unmount() }) + it('reports reconnect started exactly once per socket reconnect, retaining lastSequence', () => { + vi.useFakeTimers({ toFake: ['performance', 'setTimeout', 'clearTimeout'] }) + vi.setSystemTime(1_000) + const { unmount } = mountFollower('wf-1') + dispatchFrame('doc_subscribed', { ok: true }) + + vi.advanceTimersByTime(5_000) + apiState.target.dispatchEvent(new Event('reconnected')) + + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenCalledOnce() + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenCalledWith({ + disconnect_class: 'socket_reconnect', + attempt: 1, + last_seen_version: 41, + offline_duration_ms: 5_000 + }) + unmount() + }) + + it('counts successive reconnect attempts and resets after a confirmed subscribe', () => { + vi.useFakeTimers() + const { unmount } = mountFollower('wf-1') + dispatchFrame('doc_subscribed', { ok: true }) + + apiState.target.dispatchEvent(new Event('reconnected')) + apiState.target.dispatchEvent(new Event('reconnected')) + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenNthCalledWith( + 1, + expect.objectContaining({ attempt: 1 }) + ) + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenNthCalledWith( + 2, + expect.objectContaining({ attempt: 2 }) + ) + + dispatchFrame('doc_subscribed', { ok: true }) + apiState.target.dispatchEvent(new Event('reconnected')) + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenNthCalledWith( + 3, + expect.objectContaining({ attempt: 1 }) + ) + unmount() + }) + + it('does not report reconnect started when no subscribe intent exists yet', () => { + const { unmount } = mountFollower(null) + + apiState.target.dispatchEvent(new Event('reconnected')) + + expect(telemetryState.trackAgentReconnectStarted).not.toHaveBeenCalled() + unmount() + }) + it('clears only for an explicit reset and rebinds after replacement', () => { const { unmount } = mountFollower('wf-1') expect(adapterState.bind).toHaveBeenCalledTimes(1) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 5575cca6892..0df01377deb 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -183,6 +183,15 @@ export function useAgentCrdtFollower( // reality - and a stale channel's intent DOES equal reality). let staleProbeTimer: ReturnType | null = null + // BE-9740 (started leg): the last moment a doc-scoped frame confirmed the + // channel was alive. `onReconnected` diffs against this to report how long + // the follower was actually offline, not just how long since mount. + let lastActivityAt: number | null = null + let reconnectAttempt = 0 + const markActivity = (): void => { + lastActivityAt = performance.now() + } + const clearStaleProbe = (): void => { if (staleProbeTimer !== null) { clearTimeout(staleProbeTimer) @@ -284,6 +293,8 @@ export function useAgentCrdtFollower( if (ok) { clearSubscribeRetry() armStaleProbe() + reconnectAttempt = 0 + markActivity() // FE-1902 (poc-3): only a CONFIRMED binding is worth rebinding to after // a remount — persist on ok, not on intent. if (subscribedWorkflowId.value !== null) @@ -302,6 +313,7 @@ export function useAgentCrdtFollower( ) return if (staleProbeTimer !== null) armStaleProbe() + markActivity() updatesApplied.value = bridge.follower.updatesApplied lastFrameType.value = event.type adapter.applyFrame(update) @@ -384,6 +396,21 @@ export function useAgentCrdtFollower( ) } const onReconnected: EventListener = () => { + // Only a workflow already bound to this follower has a connection to + // lose; a reconnect firing before any subscribe intent exists is the + // initial-open case, not a loss/recovery, and is not reported. + if (subscribedWorkflowId.value !== null) { + reconnectAttempt += 1 + useTelemetry()?.trackAgentReconnectStarted({ + disconnect_class: 'socket_reconnect', + attempt: reconnectAttempt, + last_seen_version: bridge.lastSequence, + offline_duration_ms: + lastActivityAt === null + ? null + : Math.max(0, Math.round(performance.now() - lastActivityAt)) + }) + } connected.value = false clearStaleProbe() recordDevEvent('reconnected', null) From ab974bc79bb2aa3288e3c6fd5b29250665173b63 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 12:50:39 -0700 Subject: [PATCH 13/24] fix(agent): gate reconnect-start telemetry on a confirmed subscription The watcher assigns subscribedWorkflowId before bridge.subscribe, so it is subscription intent, not a binding the server ever answered. A socket loss before the first doc_subscribed { ok: true } therefore reported a reconnect for a connection that had never been established. Track the confirmed workflow id and gate the event on it. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3912085865 --- .../agent/crdt/useAgentCrdtFollower.test.ts | 11 +++++++++++ .../extensions/agent/crdt/useAgentCrdtFollower.ts | 13 ++++++++++--- 2 files changed, 21 insertions(+), 3 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index cb44723079b..956678df214 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -601,6 +601,17 @@ describe('useAgentCrdtFollower', () => { unmount() }) + it('does not report reconnect started for a subscribe the server never confirmed', () => { + const { unmount } = mountFollower('wf-1') + + apiState.target.dispatchEvent(new Event('reconnected')) + dispatchFrame('doc_subscribed', { ok: false }) + apiState.target.dispatchEvent(new Event('reconnected')) + + expect(telemetryState.trackAgentReconnectStarted).not.toHaveBeenCalled() + unmount() + }) + it('clears only for an explicit reset and rebinds after replacement', () => { const { unmount, status } = mountFollower('wf-1') expect(adapterState.bind).toHaveBeenCalledTimes(1) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index f72f721792d..2649c0e5c9c 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -313,6 +313,10 @@ export function useAgentCrdtFollower( // the follower was actually offline, not just how long since mount. let lastActivityAt: number | null = null let reconnectAttempt = 0 + // Subscription INTENT is set before `bridge.subscribe` and says nothing about + // whether the server ever answered. Only a confirmed binding has a connection + // to lose, so the reconnect legs gate on this instead. + let confirmedWorkflowId: string | null = null const markActivity = (): void => { lastActivityAt = performance.now() } @@ -436,11 +440,13 @@ export function useAgentCrdtFollower( armStaleProbe() reconnectAttempt = 0 markActivity() + confirmedWorkflowId = subscribedWorkflowId.value // FE-1902 (poc-3): only a CONFIRMED binding is worth rebinding to after // a remount — persist on ok, not on intent. if (subscribedWorkflowId.value !== null) persistConfirmedDocId(subscribedWorkflowId.value) } else { + confirmedWorkflowId = null clearStaleProbe() scheduleSubscribeRetry() // FE #16637 residual: a refusal is the earliest signal the sender can @@ -601,10 +607,10 @@ export function useAgentCrdtFollower( ) } const onReconnected: EventListener = () => { - // Only a workflow already bound to this follower has a connection to - // lose; a reconnect firing before any subscribe intent exists is the + // Only a workflow whose subscribe the server CONFIRMED has a connection to + // lose; a reconnect before the first `doc_subscribed { ok: true }` is the // initial-open case, not a loss/recovery, and is not reported. - if (subscribedWorkflowId.value !== null) { + if (confirmedWorkflowId !== null) { reconnectAttempt += 1 useTelemetry()?.trackAgentReconnectStarted({ disconnect_class: 'socket_reconnect', @@ -709,6 +715,7 @@ export function useAgentCrdtFollower( clearSubscribeRetry() clearStaleProbe() connected.value = false + confirmedWorkflowId = null knownDocNodeIds = new Set() if (!active) { if (next !== null) initialBind = false From ea25f354004fb3cade81aada9c9b8f6d0b97a61f Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 12:51:29 -0700 Subject: [PATCH 14/24] fix(agent): refresh the offline baseline on an accepted doc_reset doc_update refreshes lastActivityAt but doc_reset did not, so a reset that was the last document frame before a socket reconnect left offline_duration_ms counting an interval the channel was demonstrably alive. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3912085857 --- .../agent/crdt/useAgentCrdtFollower.test.ts | 17 +++++++++++++++++ .../agent/crdt/useAgentCrdtFollower.ts | 1 + 2 files changed, 18 insertions(+) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts index 956678df214..60fa9a6dc75 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.test.ts @@ -612,6 +612,23 @@ describe('useAgentCrdtFollower', () => { unmount() }) + it('a doc_reset on the bound workflow refreshes the offline baseline', () => { + vi.useFakeTimers({ toFake: ['performance', 'setTimeout', 'clearTimeout'] }) + vi.setSystemTime(1_000) + const { unmount } = mountFollower('wf-1') + dispatchFrame('doc_subscribed', { ok: true }) + + vi.advanceTimersByTime(5_000) + dispatchFrame('doc_reset', { workflowId: 'wf-1', seq: 7 }) + vi.advanceTimersByTime(2_000) + apiState.target.dispatchEvent(new Event('reconnected')) + + expect(telemetryState.trackAgentReconnectStarted).toHaveBeenCalledWith( + expect.objectContaining({ offline_duration_ms: 2_000 }) + ) + unmount() + }) + it('clears only for an explicit reset and rebinds after replacement', () => { const { unmount, status } = mountFollower('wf-1') expect(adapterState.bind).toHaveBeenCalledTimes(1) diff --git a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts index 2649c0e5c9c..67c8ea74360 100644 --- a/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts +++ b/src/workbench/extensions/agent/crdt/useAgentCrdtFollower.ts @@ -525,6 +525,7 @@ export function useAgentCrdtFollower( detail?.workflowId !== subscribedWorkflowId.value ) return + markActivity() const context: RemoteMutationContext = { source: 'agent-remote', actor: detail.actor ?? 'agent-reset', From ebd497e1f04391cb29a01ce62e6a3eaa97637fc4 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 12:53:43 -0700 Subject: [PATCH 15/24] fix(graph): make canonical document serialization environment-independent MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Byte equality is this serializer's stated save/reload identity check, but localeCompare depends on the active locale and the ICU build, and Map/Set were canonicalized in insertion order — which differs between the full-snapshot rebuild path and the live incremental path. Sort Map entries and Set members by their serialized form and compare widget names by code unit. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777458 --- .../graph/document/documentSerializer.test.ts | 66 +++++++++++++++++++ src/core/graph/document/documentSerializer.ts | 23 ++++++- 2 files changed, 86 insertions(+), 3 deletions(-) create mode 100644 src/core/graph/document/documentSerializer.test.ts diff --git a/src/core/graph/document/documentSerializer.test.ts b/src/core/graph/document/documentSerializer.test.ts new file mode 100644 index 00000000000..b4faa066abc --- /dev/null +++ b/src/core/graph/document/documentSerializer.test.ts @@ -0,0 +1,66 @@ +import { describe, expect, it, vi } from 'vitest' + +import { createGraphMutations } from '@/core/graph/graphMutations' +import type { GraphMutations } from '@/core/graph/graphMutations' +import type { RemoteMutationContext } from '@/types/graphMutationContext' +import type { GraphScope } from '@/types/graphScopeId' +import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' +import { toNodeId } from '@/types/nodeId' + +import { serializeDocumentScope } from './documentSerializer' + +const context: RemoteMutationContext = { + source: 'agent-remote', + actor: 'test', + opId: 'op-1' +} + +function scopeFor(graphId: string): GraphScope { + return { + rootGraphId: toRootGraphId(graphId), + owningGraphId: toOwningGraphId(graphId) + } +} + +function mutationsFor(scope: GraphScope): GraphMutations { + return createGraphMutations({ + getScope: () => scope, + layout: { createNode: vi.fn(), deleteNodes: vi.fn() } + }) +} + +function widgetNames(scope: GraphScope): string[] { + const parsed = JSON.parse( + new TextDecoder().decode(serializeDocumentScope(scope)) + ) as { nodes: { widgets: { name: string }[] }[] } + return parsed.nodes.flatMap(({ widgets }) => widgets.map(({ name }) => name)) +} + +describe('serializeDocumentScope', () => { + it('orders widget names by code unit, not by the ambient collation', () => { + const scope = scopeFor('root') + const mutations = mutationsFor(scope) + mutations.addNode({ id: '1', type: 'Source' }, context) + mutations.setWidget(toNodeId('1'), 'apples', 1, context) + mutations.setWidget(toNodeId('1'), 'Bananas', 2, context) + + expect(widgetNames(scope)).toEqual(['Bananas', 'apples']) + }) + + it('serializes a Map-valued widget identically whatever its insertion order', () => { + const forward = scopeFor('forward') + const reverse = scopeFor('reverse') + for (const [scope, entries] of [ + [forward, [['alpha', 1] as const, ['beta', 2] as const]], + [reverse, [['beta', 2] as const, ['alpha', 1] as const]] + ] as const) { + const mutations = mutationsFor(scope) + mutations.addNode({ id: '1', type: 'Source' }, context) + mutations.setWidget(toNodeId('1'), 'opaque', new Map(entries), context) + } + + expect(serializeDocumentScope(forward)).toEqual( + serializeDocumentScope(reverse) + ) + }) +}) diff --git a/src/core/graph/document/documentSerializer.ts b/src/core/graph/document/documentSerializer.ts index 36992dd3ab8..104e5f6cebf 100644 --- a/src/core/graph/document/documentSerializer.ts +++ b/src/core/graph/document/documentSerializer.ts @@ -6,10 +6,27 @@ import { compareNodeIds } from '@/types/nodeId' const RENDER_ONLY_KEYS = new Set(['boundingRect']) +function compareCodeUnits(left: string, right: string): number { + return left < right ? -1 : left > right ? 1 : 0 +} + +function sortBySerializedForm(entries: readonly unknown[]): unknown[] { + return entries + .map((entry) => [JSON.stringify(entry), entry] as const) + .sort(([left], [right]) => compareCodeUnits(left, right)) + .map(([, entry]) => entry) +} + function canonicalize(value: unknown): unknown { if (Array.isArray(value)) return value.map(canonicalize) - if (value instanceof Map || value instanceof Set) - return canonicalize([...value]) + // Iteration order of a Map or a Set is insertion order, which differs + // between the full-snapshot rebuild path and the live incremental path. + if (value instanceof Map) + return sortBySerializedForm( + [...value].map(([key, entry]) => [canonicalize(key), canonicalize(entry)]) + ) + if (value instanceof Set) + return sortBySerializedForm([...value].map(canonicalize)) if (typeof value === 'object' && value !== null) { const source = value as Record const result: Record = {} @@ -46,7 +63,7 @@ export function serializeDocumentScope(scope: GraphScope): Uint8Array { widgets: widgetStore .getNodeWidgets(scope.rootGraphId, semantic.id) .map(({ name, type, value }) => ({ name, type, value })) - .sort((left, right) => left.name.localeCompare(right.name)) + .sort((left, right) => compareCodeUnits(left.name, right.name)) })) const links = [...linkStore.graphTopologies(scope)] From 06a3df648258e8b035607d73c1474c3a3f4f9c59 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 12:54:51 -0700 Subject: [PATCH 16/24] fix(graph): reject a malformed sequence in isCommitted Number('') is 0 and Number.isInteger(0) is true, so ":" reported committed whenever committedSeq was at or above 0; ":-5" passed for the same reason. Require a plain nonnegative integer suffix. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777437 --- .../graph/document/detachedTargetSession.test.ts | 15 +++++++++++++++ src/core/graph/document/detachedTargetSession.ts | 8 +++++--- 2 files changed, 20 insertions(+), 3 deletions(-) diff --git a/src/core/graph/document/detachedTargetSession.test.ts b/src/core/graph/document/detachedTargetSession.test.ts index 0f3b554bc6e..4d1a5b13df7 100644 --- a/src/core/graph/document/detachedTargetSession.test.ts +++ b/src/core/graph/document/detachedTargetSession.test.ts @@ -359,4 +359,19 @@ describe('createDetachedTargetSession', () => { expect(session.isCommitted(`other-lineage:1`)).toBe(false) expect(session.isCommitted('malformed')).toBe(false) }) + + it('isCommitted rejects a commit id whose sequence is not a plain nonnegative integer', () => { + const source = createFrameSource() + const session = createDetachedTargetSession(WORKFLOW_ID) + session.enqueue( + source.frame((doc) => setNode(doc, '1', { type: 'Source' })) + ) + session.drainAll(acceptAll) + const { lineage } = session.snapshot() + + expect(session.isCommitted(`${lineage}:`)).toBe(false) + expect(session.isCommitted(`${lineage}:-5`)).toBe(false) + expect(session.isCommitted(`${lineage}:1.5`)).toBe(false) + expect(session.isCommitted(`${lineage}: 1`)).toBe(false) + }) }) diff --git a/src/core/graph/document/detachedTargetSession.ts b/src/core/graph/document/detachedTargetSession.ts index ab6c00dcc65..5c395d6de88 100644 --- a/src/core/graph/document/detachedTargetSession.ts +++ b/src/core/graph/document/detachedTargetSession.ts @@ -137,8 +137,8 @@ export function createDetachedTargetSession( function commitNext(port: TargetFrameApplyPort): CommitResult { if (needsResync) return { status: 'resync-required' } + if (queue.length === 0) return { status: 'idle' } const frame = queue[0] - if (!frame) return { status: 'idle' } const staged = new Y.Doc() Y.applyUpdate(staged, Y.encodeStateAsUpdate(committedDoc)) @@ -220,8 +220,10 @@ export function createDetachedTargetSession( const separator = commitId.lastIndexOf(':') if (separator < 0) return false const commitLineage = commitId.slice(0, separator) - const seq = Number(commitId.slice(separator + 1)) - if (!Number.isInteger(seq)) return false + const rawSeq = commitId.slice(separator + 1) + if (!/^\d+$/.test(rawSeq)) return false + const seq = Number(rawSeq) + if (!Number.isSafeInteger(seq)) return false return ( commitLineage === lineage && committedSeq !== null && seq <= committedSeq ) From 471dea5981e7870e93128336cd8dfb0b5348bf4b Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 12:58:23 -0700 Subject: [PATCH 17/24] fix(agent): narrow node payloads and slot arrays in the frame projection Mint the staged-doc map key as a NodeId and build the payload as a literal so it no longer needs a type assertion, and reject a slot array whose entries are not name/type records instead of asserting whatever Y.Array#toJSON returned onto ISerialisableNodeOutput and handing it to batch.connect. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777484 --- .../agent/crdt/targetFrameProjection.test.ts | 65 +++++++++++++++++++ .../agent/crdt/targetFrameProjection.ts | 27 ++++++-- 2 files changed, 85 insertions(+), 7 deletions(-) create mode 100644 src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts new file mode 100644 index 00000000000..073ddb4d323 --- /dev/null +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts @@ -0,0 +1,65 @@ +import { linksMap, nodesMap } from '@comfyorg/comfy-multi-player' +import { describe, expect, it } from 'vitest' +import * as Y from 'yjs' + +import type { TargetFrame } from '@/core/graph/document/detachedTargetSession' +import type { + GraphMutations, + SemanticLinkPayload +} from '@/core/graph/graphMutations' + +import { createTargetFrameApplyPort } from './targetFrameProjection' + +type GraphMutationBatch = Parameters[1]>[0] + +const frame: TargetFrame = { + workflowId: 'wf', + seq: 1, + update: new Uint8Array() +} + +function recordingMutations(): { + mutations: GraphMutations + links: SemanticLinkPayload[] +} { + const links: SemanticLinkPayload[] = [] + const batch = { + clearSemanticGraph: () => {}, + reconcileNode: () => {}, + connect: (link: SemanticLinkPayload) => { + links.push(link) + } + } as unknown as GraphMutationBatch + const mutations = { + batch: (_context: unknown, define: (batch: GraphMutationBatch) => void) => { + define(batch) + return true + } + } as unknown as GraphMutations + return { mutations, links } +} + +function setNode(doc: Y.Doc, id: string, fields: Record) { + const node = nodesMap(doc).get(id) ?? new Y.Map() + if (!nodesMap(doc).has(id)) nodesMap(doc).set(id, node) + for (const [key, value] of Object.entries(fields)) node.set(key, value) + return node +} + +describe('createTargetFrameApplyPort', () => { + it('drops a slot array holding non-record entries instead of forwarding it', () => { + const doc = new Y.Doc() + const source = setNode(doc, '1', { type: 'Source' }) + const outputs = new Y.Array() + outputs.push(['not-a-slot']) + source.set('outputs', outputs) + setNode(doc, '2', { type: 'Sink' }) + linksMap(doc).set('9', [9, '1', 0, '2', 0, 'IMAGE']) + + const { mutations, links } = recordingMutations() + createTargetFrameApplyPort(mutations).apply(frame, doc) + + expect(links[0]?.originOutputs).toEqual([]) + doc.destroy() + }) +}) diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts index c9b35142253..9b5e8c0779d 100644 --- a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts @@ -14,6 +14,7 @@ import type { SemanticLinkPayload, SemanticNodePayload } from '@/core/graph/graphMutations' +import type { ISlotType } from '@/lib/litegraph/src/interfaces' import type { RemoteMutationContext } from '@/types/graphMutationContext' import { compareNodeIds, toNodeId } from '@/types/nodeId' @@ -44,9 +45,19 @@ function readSemanticNode(doc: Y.Doc, id: string): SemanticNodePayload | null { payload[key] = plain(value) } }) - payload.id = id - payload.type = type - return payload as SemanticNodePayload + return { ...payload, id: toNodeId(id), type } +} + +function isSlotRecord( + value: unknown +): value is Record & { name: string; type: ISlotType } { + if (typeof value !== 'object' || value === null || Array.isArray(value)) + return false + const record = value as Record + return ( + typeof record.name === 'string' && + (typeof record.type === 'string' || typeof record.type === 'number') + ) } function readNodeSlots( @@ -56,12 +67,14 @@ function readNodeSlots( ): SemanticLinkPayload[TKey extends 'inputs' ? 'targetInputs' : 'originOutputs'] { - const value = nodesMap(doc).get(id)?.get(key) - return ( - value instanceof Y.Array ? value.toJSON() : [] - ) as SemanticLinkPayload[TKey extends 'inputs' + type Slots = SemanticLinkPayload[TKey extends 'inputs' ? 'targetInputs' : 'originOutputs'] + const value = nodesMap(doc).get(id)?.get(key) + if (!(value instanceof Y.Array)) return [] as Slots + const slots: unknown = value.toJSON() + if (!Array.isArray(slots) || !slots.every(isSlotRecord)) return [] as Slots + return slots } function readSemanticLink(doc: Y.Doc, id: string): SemanticLinkPayload | null { From d41d8a10aca864e1b41683a4494426e3b1dc8f6c Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 12:59:07 -0700 Subject: [PATCH 18/24] fix(agent): order link keys deterministically in the frame projection Number(left) - Number(right) returns NaN for a non-numeric link key, and a comparator that returns NaN leaves the resulting order implementation- defined, so the rebuild order of a snapshot was not reproducible. Sort numeric keys numerically and place the rest after them in code-unit order. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777490 --- .../agent/crdt/targetFrameProjection.test.ts | 15 +++++++++++++++ .../agent/crdt/targetFrameProjection.ts | 19 ++++++++++++++++--- 2 files changed, 31 insertions(+), 3 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts index 073ddb4d323..94432f67b5b 100644 --- a/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.test.ts @@ -47,6 +47,21 @@ function setNode(doc: Y.Doc, id: string, fields: Record) { } describe('createTargetFrameApplyPort', () => { + it('orders non-numeric link keys deterministically after the numeric ones', () => { + const doc = new Y.Doc() + setNode(doc, '1', { type: 'Source' }) + setNode(doc, '2', { type: 'Sink' }) + const linkIdByKey = { '10': 10, '2': 2, zz: 700, '1': 1, ab: 800 } + for (const [key, linkId] of Object.entries(linkIdByKey)) + linksMap(doc).set(key, [linkId, '1', 0, '2', 0, 'IMAGE']) + + const { mutations, links } = recordingMutations() + createTargetFrameApplyPort(mutations).apply(frame, doc) + + expect(links.map(({ id }) => id)).toEqual([1, 2, 10, 800, 700]) + doc.destroy() + }) + it('drops a slot array holding non-record entries instead of forwarding it', () => { const doc = new Y.Doc() const source = setNode(doc, '1', { type: 'Source' }) diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts index 9b5e8c0779d..6e8cc52508a 100644 --- a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts @@ -108,6 +108,21 @@ function readSemanticLink(doc: Y.Doc, id: string): SemanticLinkPayload | null { } } +/** + * Numeric keys ascend numerically; anything else follows them in code-unit + * order. `Number(key)` alone yields `NaN` for a non-numeric key, and a + * comparator returning `NaN` leaves the order implementation-defined. + */ +function compareLinkKeys(left: string, right: string): number { + const integerPattern = /^-?\d+$/ + const leftSeq = integerPattern.test(left) ? Number(left) : null + const rightSeq = integerPattern.test(right) ? Number(right) : null + if (leftSeq !== null && rightSeq !== null) return leftSeq - rightSeq + if (leftSeq !== null) return -1 + if (rightSeq !== null) return 1 + return left < right ? -1 : left > right ? 1 : 0 +} + function frameContext(frame: TargetFrame): RemoteMutationContext { const opIds = frame.opIds?.filter((id) => id.length > 0) return { @@ -133,9 +148,7 @@ export function createTargetFrameApplyPort( const nodeIds = [...nodesMap(stagedDoc).keys()].sort((left, right) => compareNodeIds(toNodeId(left), toNodeId(right)) ) - const linkIds = [...linksMap(stagedDoc).keys()].sort( - (left, right) => Number(left) - Number(right) - ) + const linkIds = [...linksMap(stagedDoc).keys()].sort(compareLinkKeys) return mutations.batch(frameContext(frame), (batch) => { batch.clearSemanticGraph() for (const id of nodeIds) { From 0bf916794567cccf70323aed9c989b1dab733a8a Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 13:01:41 -0700 Subject: [PATCH 19/24] fix(agent): drop slot link references a snapshot does not contain Pinning the link-reference invariant after a lineage replacement showed the reminted node keeping its pre-reset output link 9 while the replacement lineage carries no links at all, so a save would persist a reference to a link that does not exist. A full snapshot is authoritative for its own link set; filter slot references against it. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777467 --- ...tActivationPersistence.integration.test.ts | 21 +++++--- .../agent/crdt/targetFrameProjection.ts | 50 ++++++++++++++++--- 2 files changed, 57 insertions(+), 14 deletions(-) diff --git a/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts index aa05ac53b81..d1399bc4f05 100644 --- a/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts +++ b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts @@ -6,9 +6,7 @@ import { readStamps } from '@comfyorg/comfy-multi-player' import type { WidgetCatalog } from '@comfyorg/comfy-multi-player' -import { createTestingPinia } from '@pinia/testing' -import { setActivePinia } from 'pinia' -import { beforeEach, describe, expect, it, vi } from 'vitest' +import { describe, expect, it, vi } from 'vitest' import * as Y from 'yjs' import { createActivationCoordinator } from '@/core/graph/document/activationCoordinator' @@ -122,10 +120,6 @@ function loadedCoordinator() { } describe('document activation persistence (ADR-0024 seam)', () => { - beforeEach(() => { - setActivePinia(createTestingPinia({ stubActions: false })) - }) - it('serializes byte-identically across Base/ECS/Nodes-2.0 activation cycles and save/reload', async () => { const scope = scopeFor('root') const mutations = mutationsFor(scope) @@ -351,11 +345,22 @@ describe('document activation persistence (ADR-0024 seam)', () => { const reloaded = serializeDocumentScope(scope) const parsed = JSON.parse(new TextDecoder().decode(reloaded)) as { - nodes: { id: string }[] + nodes: { + id: string + inputs?: { link?: number | null }[] + outputs?: { links?: number[] }[] + }[] links: unknown[] } expect(parsed.nodes.map(({ id }) => id)).toEqual(['1']) expect(parsed.links).toEqual([]) + // The reminted node still declares its pre-reset output link, which the + // replacement lineage no longer contains. + expect( + parsed.nodes.flatMap((node) => + (node.outputs ?? []).map((slot) => slot.links) + ) + ).toEqual([[]]) session.destroy() host.destroy() diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts index 6e8cc52508a..47373936457 100644 --- a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts @@ -133,6 +133,43 @@ function frameContext(frame: TargetFrame): RemoteMutationContext { } } +/** + * A snapshot is authoritative for its own link set, so a slot may not carry a + * reference the snapshot does not contain — that reference would survive into + * the serialized document and outlive the link it names. + */ +function withKnownLinks( + payload: SemanticNodePayload, + knownLinkIds: ReadonlySet +): SemanticNodePayload { + const { inputs, outputs } = payload + return { + ...payload, + ...(Array.isArray(outputs) && { + outputs: outputs.map((slot) => + isSlotRecord(slot) && Array.isArray(slot.links) + ? { + ...slot, + links: slot.links.filter( + (linkId) => + typeof linkId === 'number' && knownLinkIds.has(linkId) + ) + } + : slot + ) + }), + ...(Array.isArray(inputs) && { + inputs: inputs.map((slot) => + isSlotRecord(slot) && + typeof slot.link === 'number' && + !knownLinkIds.has(slot.link) + ? { ...slot, link: null } + : slot + ) + }) + } +} + /** * Full-snapshot projection of a detached target session's staged document * into the ECS stores through the target's `GraphMutations` composite. One @@ -148,17 +185,18 @@ export function createTargetFrameApplyPort( const nodeIds = [...nodesMap(stagedDoc).keys()].sort((left, right) => compareNodeIds(toNodeId(left), toNodeId(right)) ) - const linkIds = [...linksMap(stagedDoc).keys()].sort(compareLinkKeys) + const links = [...linksMap(stagedDoc).keys()] + .sort(compareLinkKeys) + .flatMap((id) => readSemanticLink(stagedDoc, id) ?? []) + const knownLinkIds = new Set(links.map(({ id }) => id)) return mutations.batch(frameContext(frame), (batch) => { batch.clearSemanticGraph() for (const id of nodeIds) { const payload = readSemanticNode(stagedDoc, id) - if (payload) batch.reconcileNode(payload) - } - for (const id of linkIds) { - const link = readSemanticLink(stagedDoc, id) - if (link) batch.connect(link) + if (payload) + batch.reconcileNode(withKnownLinks(payload, knownLinkIds)) } + for (const link of links) batch.connect(link) }) } } From 55fabe2f9ef4a73358e98e207b3f99cbea6c48a9 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 13:02:28 -0700 Subject: [PATCH 20/24] test(graph): replace the default-value-only document lifecycle test AGENTS.md forbids a test that only asserts the defaults are certain values. Fold the initial-state prerequisite into the hydration transition, which now also pins that hydrating does not establish a persistence baseline. The initial phase stays covered by "cannot close a document that was never loaded", which goes red if it changes. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777453 --- src/core/graph/document/documentLifecycle.test.ts | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/src/core/graph/document/documentLifecycle.test.ts b/src/core/graph/document/documentLifecycle.test.ts index 8c0c687ffd0..75c79a12ac8 100644 --- a/src/core/graph/document/documentLifecycle.test.ts +++ b/src/core/graph/document/documentLifecycle.test.ts @@ -15,14 +15,10 @@ function run( } describe('reduceDocument', () => { - it('starts created and unsaved', () => { - expect(initialDocumentState.phase).toBe('created') - expect(persistenceOf(initialDocumentState)).toBe('unsaved') - }) - - it('hydrates created to loaded and ignores repeat hydration', () => { + it('hydrates created to loaded without establishing a persistence baseline', () => { const loaded = run([{ type: 'hydrated' }]) expect(loaded.phase).toBe('loaded') + expect(persistenceOf(loaded)).toBe('unsaved') expect(run([{ type: 'hydrated' }], loaded)).toEqual(loaded) }) From e4db5bfd73f9dadc1b3ae5fc42e33a1826877570 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 13:05:15 -0700 Subject: [PATCH 21/24] fix(agent): invalidate the cached mutations handler when its document changes The handler captured the documentId resolved on first use, but the registry may map the same workflowId onto a replacement document after the previous one closes. getScope() then reads the closed document, returns null, and the follower drops every later detached update. Key the cache on the currently resolved documentId. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777462 --- src/workbench/extensions/agent/AgentPanelRoot.vue | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/src/workbench/extensions/agent/AgentPanelRoot.vue b/src/workbench/extensions/agent/AgentPanelRoot.vue index 407531e4517..1372127c175 100644 --- a/src/workbench/extensions/agent/AgentPanelRoot.vue +++ b/src/workbench/extensions/agent/AgentPanelRoot.vue @@ -50,6 +50,7 @@ import { app } from '@/scripts/app' import { useAgentNodeSelectionStore } from '@/stores/agentNodeSelectionStore' import { useExecutionErrorStore } from '@/stores/executionErrorStore' import { useGraphDocumentStore } from '@/stores/graphDocumentStore' +import type { DocumentId } from '@/types/documentId' import { useWorkflowTabActivityStore } from '@/stores/workflowTabActivityStore' import { useSidebarTabStore } from '@/stores/workspace/sidebarTabStore' import { isLGraphNode } from '@/utils/litegraphUtil' @@ -161,11 +162,12 @@ const canvasStore = useCanvasStore() const graphDocumentStore = useGraphDocumentStore() const graphMutationsByWorkflow = new Map< string, - ReturnType + { + documentId: DocumentId | null + mutations: ReturnType + } >() const graphMutations = (workflowId: string) => { - const existing = graphMutationsByWorkflow.get(workflowId) - if (existing) return existing // Document identity is early-bound (ADR-0024): the registry entry is // created when the target is first addressed, not at commit time. Commit // scope resolution then records/refreshes the entry's scope, so a target @@ -173,6 +175,11 @@ const graphMutations = (workflowId: string) => { const documentId = graphDocumentStore.resolveWorkflowTarget(workflowId)?.documentId ?? graphDocumentStore.createDocument({ workflowId }) + // The registry may map this workflow onto a replacement document after the + // previous one closed; a handler that captured the closed document resolves + // no scope and silently drops every later update. + const existing = graphMutationsByWorkflow.get(workflowId) + if (existing && existing.documentId === documentId) return existing.mutations const mutations = createGraphMutations({ getScope() { const registered = documentId @@ -230,7 +237,7 @@ const graphMutations = (workflowId: string) => { } } }) - graphMutationsByWorkflow.set(workflowId, mutations) + graphMutationsByWorkflow.set(workflowId, { documentId, mutations }) return mutations } const { focusNodeInstance } = useFocusNode() From 9872f3602b60a4efae04061d6f87b57bb4660ab2 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 13:06:01 -0700 Subject: [PATCH 22/24] fix(agent): advance the document revision after a committed CRDT batch GraphMutations.batch() commits remote frames but no production caller advanced the document revision, so save tickets and close decisions could be taken against an obsolete one. Add an onCommitted hook that fires only after a batch validated and committed, and mark the target document mutated from it. Addresses review feedback: https://github.com/Comfy-Org/ComfyUI_frontend/pull/16397#discussion_r3911777466 --- src/core/graph/graphMutations.test.ts | 28 +++++++++++++++++++ src/core/graph/graphMutations.ts | 3 ++ .../extensions/agent/AgentPanelRoot.vue | 3 ++ 3 files changed, 34 insertions(+) diff --git a/src/core/graph/graphMutations.test.ts b/src/core/graph/graphMutations.test.ts index 5ba0bd0c778..8c099cbe772 100644 --- a/src/core/graph/graphMutations.test.ts +++ b/src/core/graph/graphMutations.test.ts @@ -426,4 +426,32 @@ describe('graphMutations', () => { expect(nodeContexts).toEqual([context]) expect(widgetContexts).toEqual([context]) }) + it('notifies onCommitted once per committed batch and never for a rejected one', () => { + const onCommitted = vi.fn() + const tracked = createGraphMutations({ + getScope: () => scope, + layout: { createNode: createLayout, deleteNodes: deleteLayouts }, + onCommitted + }) + const error = vi.spyOn(console, 'error').mockImplementation(() => {}) + + expect(tracked.addNode(node(1), context)).toBe(true) + expect(onCommitted).toHaveBeenCalledOnce() + + expect( + tracked.batch(context, (batch) => { + batch.addNode(node(2)) + batch.connect({ + id: 1, + originNodeId: 2, + originSlot: 0, + targetNodeId: 404, + targetSlot: 0, + type: 'IMAGE' + }) + }) + ).toBe(false) + expect(onCommitted).toHaveBeenCalledOnce() + error.mockRestore() + }) }) diff --git a/src/core/graph/graphMutations.ts b/src/core/graph/graphMutations.ts index 64d87fea562..224a09c7e5d 100644 --- a/src/core/graph/graphMutations.ts +++ b/src/core/graph/graphMutations.ts @@ -98,6 +98,8 @@ export interface GraphMutations { export interface GraphMutationsDeps { getScope(): GraphScope | null layout: SemanticLayoutMutationPort + /** Invoked once per batch that validated and committed. */ + onCommitted?: () => void } type QueuedMutation = @@ -827,6 +829,7 @@ export function createGraphMutations(deps: GraphMutationsDeps): GraphMutations { const prepared = prepare(scope, queued) if (typeof prepared === 'string') return fail(prepared) commit(scope, prepared, context) + deps.onCommitted?.() return true }, addNode(payload, context) { diff --git a/src/workbench/extensions/agent/AgentPanelRoot.vue b/src/workbench/extensions/agent/AgentPanelRoot.vue index 1372127c175..95e819b1e0a 100644 --- a/src/workbench/extensions/agent/AgentPanelRoot.vue +++ b/src/workbench/extensions/agent/AgentPanelRoot.vue @@ -181,6 +181,9 @@ const graphMutations = (workflowId: string) => { const existing = graphMutationsByWorkflow.get(workflowId) if (existing && existing.documentId === documentId) return existing.mutations const mutations = createGraphMutations({ + onCommitted() { + if (documentId) graphDocumentStore.markMutated(documentId) + }, getScope() { const registered = documentId ? (graphDocumentStore.getDocument(documentId)?.scope ?? null) From 8a18f00e7a466f7a9832d197b611f0f6c8adaf39 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 13:45:16 -0700 Subject: [PATCH 23/24] test(stores): use the global testing Pinia in the graph document store test comfy(use-global-pinia) rejects a second Pinia instance; vitest.setup.ts already installs one per test. --- src/stores/graphDocumentStore.test.ts | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/src/stores/graphDocumentStore.test.ts b/src/stores/graphDocumentStore.test.ts index 313cd17d345..5173415ecd4 100644 --- a/src/stores/graphDocumentStore.test.ts +++ b/src/stores/graphDocumentStore.test.ts @@ -1,5 +1,4 @@ -import { createPinia, setActivePinia } from 'pinia' -import { beforeEach, describe, expect, it } from 'vitest' +import { describe, expect, it } from 'vitest' import { toOwningGraphId, toRootGraphId } from '@/types/graphScopeId' @@ -11,10 +10,6 @@ const scope = { } describe('useGraphDocumentStore', () => { - beforeEach(() => { - setActivePinia(createPinia()) - }) - it('creates local-only documents that are not agent-addressable', () => { const store = useGraphDocumentStore() const documentId = store.createDocument() From 67cfcf06c48f9cf63c112e673324800c7f46f6d2 Mon Sep 17 00:00:00 2001 From: christian-byrne Date: Thu, 10 Sep 2026 14:01:16 -0700 Subject: [PATCH 24/24] docs: use the stable ADR identifier for the graph document seam #16196 made numbered ADR references legacy and pnpm adr:check now rejects them; this branch predates that. ADR-0024 is ADR-GRAPH-DOCUMENT-0024. --- src/core/graph/document/activationCoordinator.ts | 4 ++-- src/core/graph/document/detachedTargetSession.ts | 2 +- src/core/graph/document/documentLifecycle.ts | 2 +- src/core/graph/document/documentSerializer.ts | 2 +- src/stores/graphDocumentStore.ts | 2 +- src/types/documentId.ts | 2 +- src/workbench/extensions/agent/AgentPanelRoot.vue | 2 +- .../crdt/documentActivationPersistence.integration.test.ts | 2 +- src/workbench/extensions/agent/crdt/targetFrameProjection.ts | 2 +- 9 files changed, 10 insertions(+), 10 deletions(-) diff --git a/src/core/graph/document/activationCoordinator.ts b/src/core/graph/document/activationCoordinator.ts index 00f9bf23eff..da411122aee 100644 --- a/src/core/graph/document/activationCoordinator.ts +++ b/src/core/graph/document/activationCoordinator.ts @@ -4,7 +4,7 @@ import type { DocumentId } from '@/types/documentId' * View concerns attached by activation and detached by deactivation: the * renderer/canvas binding, render-attached caches, viewport projection, and * input/event hooks. Attach and detach must not touch semantic document - * state (ADR-0024: activation is presentation). + * state (ADR-GRAPH-DOCUMENT-0024: activation is presentation). */ export interface DocumentViewBinding { attach(documentId: DocumentId): void @@ -32,7 +32,7 @@ export interface ActivationCoordinatorDeps { } /** - * Serializes document activation onto the active-canvas binding (ADR-0024). + * Serializes document activation onto the active-canvas binding (ADR-GRAPH-DOCUMENT-0024). * Requests carry a monotonic generation: a newer request cancels any older * in-flight one, and a stale request may clean up its private staged work * but can never detach, attach, or publish. The winning request performs one diff --git a/src/core/graph/document/detachedTargetSession.ts b/src/core/graph/document/detachedTargetSession.ts index 5c395d6de88..356e97ddf0f 100644 --- a/src/core/graph/document/detachedTargetSession.ts +++ b/src/core/graph/document/detachedTargetSession.ts @@ -65,7 +65,7 @@ const DEFAULT_MAX_QUEUED_FRAMES = 64 /** * Staged frame queue for a target document that is not attached to a live - * follower (ADR-0024's unloaded-target path). Frames enqueue in wire order + * follower (ADR-GRAPH-DOCUMENT-0024's unloaded-target path). Frames enqueue in wire order * and commit one at a time: each commit folds the head frame into a clone of * the last committed Yjs state, offers it to the projection port, and only * on success publishes the new committed tuple diff --git a/src/core/graph/document/documentLifecycle.ts b/src/core/graph/document/documentLifecycle.ts index 85b97b3e0b5..7f5f8aae464 100644 --- a/src/core/graph/document/documentLifecycle.ts +++ b/src/core/graph/document/documentLifecycle.ts @@ -1,6 +1,6 @@ /** * The pure lifecycle/persistence transition of one `GraphDocument` - * (ADR-0024). Lifecycle (`created | loaded | closed`) and persistence + * (ADR-GRAPH-DOCUMENT-0024). Lifecycle (`created | loaded | closed`) and persistence * (`unsaved | clean | dirty`) are independent: the first describes document * existence, the second compares the document with its persistence baseline. * Persistence is derived from `revision` vs `savedRevision`, never stored. diff --git a/src/core/graph/document/documentSerializer.ts b/src/core/graph/document/documentSerializer.ts index 104e5f6cebf..ed367dddeac 100644 --- a/src/core/graph/document/documentSerializer.ts +++ b/src/core/graph/document/documentSerializer.ts @@ -42,7 +42,7 @@ function canonicalize(value: unknown): unknown { /** * Renderer-independent canonical serialization of one document scope's - * semantic ECS state (ADR-0024's persistence seam). Reads only the domain + * semantic ECS state (ADR-GRAPH-DOCUMENT-0024's persistence seam). Reads only the domain * stores — never the canvas, layout, or litegraph instances — so the same * document content produces the same bytes whether the document is active * on the canvas, activated under a different renderer, or never activated diff --git a/src/stores/graphDocumentStore.ts b/src/stores/graphDocumentStore.ts index dfbc807a735..5c48f7541b9 100644 --- a/src/stores/graphDocumentStore.ts +++ b/src/stores/graphDocumentStore.ts @@ -30,7 +30,7 @@ export interface SaveTicket { } /** - * The GraphDocument registry (ADR-0024): every workflow document is a + * The GraphDocument registry (ADR-GRAPH-DOCUMENT-0024): every workflow document is a * first-class entry keyed by a stable frontend `document_id`, whether or not * a tab, renderer, or cloud `workflow_id` exists for it. The registry owns * the optional `workflow_id → document_id` mapping and rejects duplicate or diff --git a/src/types/documentId.ts b/src/types/documentId.ts index 11f84c2bbaf..81360e8b551 100644 --- a/src/types/documentId.ts +++ b/src/types/documentId.ts @@ -1,7 +1,7 @@ import { createUuidv4 } from '@/utils/uuid' /** - * Stable frontend-owned identity of a `GraphDocument` (ADR-0024). Every + * Stable frontend-owned identity of a `GraphDocument` (ADR-GRAPH-DOCUMENT-0024). Every * document has one, including local and unsaved workflows. A cloud-backed * document may additionally map a canonical `workflow_id` — the wire address * used by agent commands — but that mapping lives in the document registry; diff --git a/src/workbench/extensions/agent/AgentPanelRoot.vue b/src/workbench/extensions/agent/AgentPanelRoot.vue index 95e819b1e0a..aaf3b26d3cf 100644 --- a/src/workbench/extensions/agent/AgentPanelRoot.vue +++ b/src/workbench/extensions/agent/AgentPanelRoot.vue @@ -168,7 +168,7 @@ const graphMutationsByWorkflow = new Map< } >() const graphMutations = (workflowId: string) => { - // Document identity is early-bound (ADR-0024): the registry entry is + // Document identity is early-bound (ADR-GRAPH-DOCUMENT-0024): the registry entry is // created when the target is first addressed, not at commit time. Commit // scope resolution then records/refreshes the entry's scope, so a target // whose tab is momentarily unresolved still commits into its own document. diff --git a/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts index d1399bc4f05..729a557565d 100644 --- a/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts +++ b/src/workbench/extensions/agent/crdt/documentActivationPersistence.integration.test.ts @@ -119,7 +119,7 @@ function loadedCoordinator() { }) } -describe('document activation persistence (ADR-0024 seam)', () => { +describe('document activation persistence (ADR-GRAPH-DOCUMENT-0024 seam)', () => { it('serializes byte-identically across Base/ECS/Nodes-2.0 activation cycles and save/reload', async () => { const scope = scopeFor('root') const mutations = mutationsFor(scope) diff --git a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts index 47373936457..917b9a1870d 100644 --- a/src/workbench/extensions/agent/crdt/targetFrameProjection.ts +++ b/src/workbench/extensions/agent/crdt/targetFrameProjection.ts @@ -27,7 +27,7 @@ function plain(value: unknown): unknown { * Staged-doc counterpart of the adapter's live readers: the adapter reads * incremental observer effects off its bound follower doc, while this reads * whole snapshots off a detached session's staged doc. Kept local because the - * projection must never depend on adapter internals (ADR-0024's seam). + * projection must never depend on adapter internals (ADR-GRAPH-DOCUMENT-0024's seam). */ function readSemanticNode(doc: Y.Doc, id: string): SemanticNodePayload | null { const source = nodesMap(doc).get(id)