Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
c51a952
feat(agent): add GraphDocument registry and activation seam
ampagent Aug 31, 2026
712c7d8
feat(agent): track exhausted reconnect retries
christian-byrne Aug 31, 2026
b3c864f
fix(agent): time every subscribe retry cycle
christian-byrne Sep 1, 2026
fb08478
fix(agent): report silent final subscribe failure
christian-byrne Sep 1, 2026
7b582b2
fix(agent): preserve retry budget across reconnects
christian-byrne Sep 1, 2026
6097472
fix(agent): mark subscribe exhaustion recoverable
christian-byrne Sep 1, 2026
db960a7
test(agent): pin reconnect exhaustion timing
christian-byrne Sep 1, 2026
3b39fcc
style(agent): format retry duration calculation
christian-byrne Sep 1, 2026
ce08653
fix(agent): use assert() for cross-target frame guard
christian-byrne Sep 1, 2026
0e99677
fix(agent): report reconnect exhaustion only after the final attempt …
christian-byrne Sep 2, 2026
93aa811
test(agent): clarify retryable reconnect exhaustion
christian-byrne Sep 2, 2026
bc37fb3
feat(agent): track reconnect start on socket reconnect
christian-byrne Sep 2, 2026
dc7934d
Merge origin/main into christian-byrne/tel11-reconnect-failed
christian-byrne Sep 3, 2026
3fa35b9
chore: merge origin/main into christian-byrne/tel11-reconnect-failed
christian-byrne Sep 10, 2026
ab974bc
fix(agent): gate reconnect-start telemetry on a confirmed subscription
christian-byrne Sep 10, 2026
ea25f35
fix(agent): refresh the offline baseline on an accepted doc_reset
christian-byrne Sep 10, 2026
ebd497e
fix(graph): make canonical document serialization environment-indepen…
christian-byrne Sep 10, 2026
06a3df6
fix(graph): reject a malformed sequence in isCommitted
christian-byrne Sep 10, 2026
471dea5
fix(agent): narrow node payloads and slot arrays in the frame projection
christian-byrne Sep 10, 2026
d41d8a1
fix(agent): order link keys deterministically in the frame projection
christian-byrne Sep 10, 2026
0bf9167
fix(agent): drop slot link references a snapshot does not contain
christian-byrne Sep 10, 2026
55fabe2
test(graph): replace the default-value-only document lifecycle test
christian-byrne Sep 10, 2026
e4db5bf
fix(agent): invalidate the cached mutations handler when its document…
christian-byrne Sep 10, 2026
9872f36
fix(agent): advance the document revision after a committed CRDT batch
christian-byrne Sep 10, 2026
8a18f00
test(stores): use the global testing Pinia in the graph document stor…
christian-byrne Sep 10, 2026
67cfcf0
docs: use the stable ADR identifier for the graph document seam
christian-byrne Sep 10, 2026
7b26990
chore: merge main
ampagent Sep 22, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
165 changes: 165 additions & 0 deletions src/core/graph/document/activationCoordinator.test.ts
Original file line number Diff line number Diff line change
@@ -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<void>; resolve: () => void } {
let resolve!: () => void
const promise = new Promise<void>((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)
})
})
89 changes: 89 additions & 0 deletions src/core/graph/document/activationCoordinator.ts
Original file line number Diff line number Diff line change
@@ -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-GRAPH-DOCUMENT-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<void>
}

/**
* 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
* 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<ActivationOutcome> {
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)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Binding failures leave the published active identity inconsistent. If old detach succeeds and this attach throws, activeDocumentId() still returns the detached old document; deactivate has the same problem if detach throws. Define a non-throwing binding contract or handle rollback and cleanup around the handoff.

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 }
}
Loading
Loading