Make your computer a home for your AI partner. Avibe is the local-first Agent OS: Vibey, its built-in AI partner, works out of the box, and Claude Code, Codex & OpenCode run unchanged beside it — reach them from your browser, phone, or any chat app.
Python agentagent-osaiai-agentsai-partnerchatopsclaudeclaude-codecodexdevtoolsdiscord-botlark-botllmlocal-firstlong-term-memoryopencodeslack-botvibe-codingvibeywechat
// @vitest-environment jsdom
// One class: a provider mounted ABOVE the router bootstraps on its first real
// consumer, not on mount. The providers below are shared by every route, so a
// mount-time read makes every route pay for data it may never render — the
// project tree on /admin, thirty rows of inbox feed on a page that shows only a
// badge. These tests state the property (what the document actually reads
// decides what is fetched) rather than enumerating which routes are exempt, so a
// route added later inherits the rule.
import { act, cleanup, render } from '@testing-library/react';
import { useEffect } from 'react';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import { WorkbenchInboxProvider } from './WorkbenchInboxProvider';
import { useWorkbenchInbox, type InboxState } from './WorkbenchInboxContext';
import { WorkbenchProjectsProvider } from './WorkbenchProjectsProvider';
import {
useWorkbenchProjectsActions,
useWorkbenchProjectsTree,
type WorkbenchProjectsActions,
type WorkbenchProjectsTree,
} from './WorkbenchProjectsContext';
import type { WorkbenchEventHandlers } from './ApiContext';
import { NotificationPreferencesContext, type NotificationPreferencesState } from './NotificationPreferencesContext';
import { BotRosterContext, UNKNOWN_BOT_ROSTER, type BotRoster } from './BotRosterContext';
const project = {
id: 'proj_a',
scope_id: 'scope_a',
display_name: 'Project A',
folder_path: '/tmp/project-a',
created_at: '2026-08-18T00:00:00Z',
last_active_at: null,
archived: false,
};
const session = {
id: 'ses_a',
scope_id: 'scope_a',
project_id: 'proj_a',
title: 'A session',
agent_id: null,
agent_name: null,
agent_backend: 'codex',
agent_variant: null,
model: null,
reasoning_effort: null,
status: 'active',
visibility: 'foreground' as const,
pinned: false,
agent_status: 'idle' as const,
workdir: null,
native_session_id: null,
created_at: '2026-08-18T00:00:00Z',
updated_at: '2026-08-18T00:00:00Z',
last_active_at: '2026-08-18T00:00:00Z',
metadata: {},
};
const bootstrapPayload = {
projects: [project],
sessions: { proj_a: { sessions: [session], next_before_id: null } },
};
const inboxRow = {
session_id: session.id,
scope_id: session.scope_id,
title: session.title,
preview: 'A feed row',
preview_message_id: 'msg_a',
last_activity_at: session.last_active_at,
unread_count: 3,
visibility: 'foreground' as const,
};
// Every read of /api/inbox answers with a feed row AND a cursor alongside the
// unread map, exactly as the server does. A counts-only read must discard both.
const inboxPayload = {
sessions: [inboxRow],
next_cursor: 'cursor_1',
unread_by_session: { [session.id]: 3 },
};
type ListInboxArgs = { platform: string; limit: number; before?: string; onlySession?: string; backgroundPush?: boolean };
type FakeApi = {
getWorkbenchProjectsBootstrap?: () => Promise<unknown>;
listSessions?: () => Promise<unknown>;
getSession?: () => Promise<unknown>;
updateSession?: () => Promise<unknown>;
createSession?: () => Promise<unknown>;
forkSession?: (sessionId: string) => Promise<unknown>;
listInbox?: (args: ListInboxArgs) => Promise<unknown>;
markSessionRead?: () => Promise<unknown>;
connectWorkbenchEvents: (handlers: WorkbenchEventHandlers) => () => void;
};
const apiRef = { current: null as FakeApi | null };
type StreamConnectHandler = NonNullable<WorkbenchEventHandlers['onConnected']>;
const streamConnectHandlers = new Set<StreamConnectHandler>();
const wrappedApis = new WeakMap<FakeApi, FakeApi>();
/**
* Supply the half of the resume edge the real ApiContext owns. Consumers no
* longer watch page activity themselves: ApiContext decides whether the shared
* event stream can vouch for the gap the page spent away, recycles the ones that
* cannot, and announces the replacement through `onConnected`. These fakes stand
* in for that context, so the signal has to come from here rather than from every
* fake in the file.
*/
function withStreamConnect(api: FakeApi | null): FakeApi | null {
if (!api) return null;
// Consumers key their subscription effect on the api object, so a fresh
// wrapper per render would resubscribe forever.
const cached = wrappedApis.get(api);
if (cached) return cached;
const wrapped: FakeApi = {
...api,
connectWorkbenchEvents: (handlers) => {
const disconnect = api.connectWorkbenchEvents(handlers);
const onConnected = handlers.onConnected;
if (!onConnected) return disconnect;
streamConnectHandlers.add(onConnected);
return () => {
streamConnectHandlers.delete(onConnected);
disconnect();
};
},
};
wrappedApis.set(api, wrapped);
return wrapped;
}
vi.mock('./ApiContext', async () => {
const actual = await vi.importActual<typeof import('./ApiContext')>('./ApiContext');
return { ...actual, useApi: () => withStreamConnect(apiRef.current) };
});
// The provider reports its one never-sent refusal through the toast surface, which
// this tree does not mount. Nothing here asserts that copy — a no-op keeps the
// dependency from throwing.
vi.mock('./ToastContext', () => ({ useToast: () => ({ showToast: () => {} }) }));
function settle() {
return act(async () => {
await Promise.resolve();
await Promise.resolve();
});
}
function deferred<T>() {
let resolve!: (value: T) => void;
let reject!: (reason?: unknown) => void;
const promise = new Promise<T>((res, rej) => {
resolve = res;
reject = rej;
});
return { promise, resolve, reject };
}
// `active={false}` is the real opt-out a tree reader has (a surface that renders
// from provider state without being the reason it loads). Here it doubles as an
// observer that can watch provider state across a navigation that removes every
// activating consumer.
const TreeProbe = ({
active = true,
onState,
}: { active?: boolean; onState?: (tree: WorkbenchProjectsTree) => void } = {}) => {
const tree = useWorkbenchProjectsTree({ active });
useEffect(() => {
onState?.(tree);
}, [onState, tree]);
return null;
};
// A write-only surface (new-session dialogs, rename, archive) reaches the
// provider through the mutation half of the contract, which cannot read
// `projects` and must not make the document load them.
const ActionsProbe = ({ onState }: { onState?: (actions: WorkbenchProjectsActions) => void }) => {
const actions = useWorkbenchProjectsActions();
useEffect(() => {
onState?.(actions);
}, [actions, onState]);
return null;
};
const InboxProbe = ({
feed,
onState,
}: {
feed: boolean;
onState?: (state: InboxState) => void;
}) => {
const state = useWorkbenchInbox({ feed });
useEffect(() => {
onState?.(state);
}, [onState, state]);
return null;
};
// A resume only concerns the feed when the shared event stream cannot vouch for
// the gap the page spent away. That verdict belongs to ApiContext, which recycles
// such a stream and announces the replacement -- so drive that signal rather than
// the raw activity edge, which a page whose stream never dropped also sees and
// which no longer reaches these consumers.
const resumePage = async () => {
await act(async () => {
for (const handler of [...streamConnectHandlers]) handler({ sub_id: 1, source: 'browser' });
});
};
describe('Demand-driven shell bootstrap', () => {
beforeEach(() => {
apiRef.current = null;
});
afterEach(() => {
cleanup();
apiRef.current = null;
});
describe('projects tree', () => {
it('stays unfetched while the document renders no project', async () => {
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
};
render(
<WorkbenchProjectsProvider>
<div />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).not.toHaveBeenCalled();
});
it('bootstraps once for a document that reads the tree', async () => {
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
};
render(
<WorkbenchProjectsProvider>
<TreeProbe />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
});
// Demand is a property of what a consumer ASKS FOR, not of which route it sits
// on: a permanently mounted write-only surface (fork, pin, rename, archive)
// would otherwise re-eagerize the bootstrap on every route through the back
// door. The mutation half of the contract cannot read `projects`, so it has
// nothing to load.
it('leaves the tree unfetched for a document whose only consumer mutates it', async () => {
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
};
let actions: WorkbenchProjectsActions | null = null;
const capture = (next: WorkbenchProjectsActions) => {
actions = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<ActionsProbe onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).not.toHaveBeenCalled();
// The writes are live regardless — they patch whatever is cached.
expect(actions?.createSessionForProject).toBeTypeOf('function');
// Non-activating is not inert: the same document loads the tree the moment
// something actually renders it.
rerender(
<WorkbenchProjectsProvider>
<ActionsProbe onState={capture} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
});
// Activation has two cases, and they are not interchangeable: the first load
// builds the tree, a return REVALIDATES whatever the tree already holds. A
// consumer that paged a project in has a window wider than page one, so
// resuming through the first-load path would silently truncate it — the same
// defect the reconnect reconcile exists to prevent, arriving through
// navigation instead of through the stream.
it('revalidates a paged-in window when a consumer returns, instead of truncating it', async () => {
const secondSession = { ...session, id: 'ses_b', title: 'Older session' };
const bootstrap = vi.fn(async (args?: { projectIds?: string[] }) => ({
projects: [project],
sessions: {
proj_a: args?.projectIds
? { sessions: [session, secondSession], next_before_id: null }
: { sessions: [session], next_before_id: session.id },
},
}));
const listSessions = vi
.fn()
.mockResolvedValue({ sessions: [secondSession], next_before_id: null });
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
};
let tree: WorkbenchProjectsTree | null = null;
const capture = (next: WorkbenchProjectsTree) => {
tree = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={capture} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(1);
await act(async () => {
tree?.loadMore(project.id);
});
await settle();
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(2);
// Navigate away from every surface that renders the tree, then back.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={capture} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
const returningRead = bootstrap.mock.calls.at(-1)?.[0] as
| { projectIds?: string[]; limit?: number; cache?: boolean }
| undefined;
expect(returningRead).toMatchObject({ projectIds: [project.id], cache: false });
expect(returningRead?.limit).toBeGreaterThanOrEqual(2);
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(2);
});
it('does not re-bootstrap on a reconnect while nothing reads the tree', async () => {
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
render(
<WorkbenchProjectsProvider>
<div />
</WorkbenchProjectsProvider>,
);
await settle();
// A long-lived tab sees the shared stream flap and re-authorize; neither is
// a reason to load a tree the document does not render.
await act(async () => {
handlers?.onConnected?.();
handlers?.onAuthorizationChanged?.();
});
await settle();
expect(bootstrap).not.toHaveBeenCalled();
});
});
describe('inbox', () => {
it('reads only the unread map for a document that renders no feed', async () => {
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
apiRef.current = { listInbox, connectWorkbenchEvents: vi.fn(() => vi.fn()) };
let state: InboxState | null = null;
render(
<WorkbenchInboxProvider>
<InboxProbe
feed={false}
onState={(next) => {
state = next;
}}
/>
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
expect(listInbox.mock.calls[0][0]).toMatchObject({ platform: 'avibe', limit: 1 });
// The badge is live; the feed and its cursor are untouched, so activating
// the feed later still starts from a real first page.
expect(state?.totalUnread).toBe(3);
expect(state?.unreadBySession).toEqual({ [session.id]: 3 });
expect(state?.inboxSessions).toEqual([]);
expect(state?.nextCursor).toBeNull();
});
it('reads the feed page instead of the counts when the document renders a feed', async () => {
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
apiRef.current = { listInbox, connectWorkbenchEvents: vi.fn(() => vi.fn()) };
let state: InboxState | null = null;
render(
<WorkbenchInboxProvider>
<InboxProbe
feed
onState={(next) => {
state = next;
}}
/>
</WorkbenchInboxProvider>,
);
await settle();
// One read, not two: a feed consumer activates from its own effect, which
// React runs before the provider's, so the counts-only read is skipped in
// favour of the feed read that supersedes it.
expect(listInbox).toHaveBeenCalledTimes(1);
expect(listInbox.mock.calls[0][0]).toMatchObject({ platform: 'avibe', limit: 30 });
expect(state?.inboxSessions).toHaveLength(1);
expect(state?.nextCursor).toBe('cursor_1');
});
it('loads page one when a later navigation brings a feed consumer in', async () => {
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
apiRef.current = { listInbox, connectWorkbenchEvents: vi.fn(() => vi.fn()) };
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
expect(listInbox.mock.calls[1][0]).toMatchObject({ platform: 'avibe', limit: 30 });
expect(listInbox.mock.calls[1][0]).not.toHaveProperty('before');
expect(state?.inboxSessions).toHaveLength(1);
});
});
// The demand gate decides what is READ. It must not also decide what stays
// cached: a reconnect says "you may have missed events" and can wait for a
// consumer, but an authorization change says "what you hold may no longer be
// authorized", and both providers' resumption paths deliberately preserve rows
// (the projects list survives a failed retry; the inbox reconcile keeps rows the
// response omitted). These pin the drop WITHOUT letting any response resolve, so
// they hold for a revalidation that is slow, failing, or never arrives.
describe('authorization changes invalidate what nothing is reading', () => {
it('drops the cached project tree rather than keeping it for the way back', async () => {
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const capture = (next: WorkbenchProjectsTree) => {
tree = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toHaveLength(1);
// Navigate to a route that renders no project, then lose access there.
rerender(
<WorkbenchProjectsProvider>
<div />
</WorkbenchProjectsProvider>,
);
await settle();
bootstrap.mockReturnValue(deferred<typeof bootstrapPayload>().promise);
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
// Nothing re-reads the tree here, and nothing needs to: coming back must not
// be able to render a project that was authorized before the change.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toBeNull();
expect(tree?.sessionsOf(project.id).sessions).toBeNull();
expect(tree?.isExpanded(project.id)).toBe(false);
});
// Invalidating a read that is already in flight is itself what queues its
// replacement, so the drop above has a second half: that retry must not
// survive the last reader. Otherwise the invalidation repopulates exactly what
// it just dropped — off-route, and with a snapshot the server produced BEFORE
// the authorization change.
it('drops the tree retry the invalidation itself queues', async () => {
const stale = deferred<typeof bootstrapPayload>();
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const capture = (next: WorkbenchProjectsTree) => {
tree = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={capture} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toHaveLength(1);
// A reconnect reconcile is in flight when the user navigates away.
bootstrap.mockReturnValue(stale.promise);
await act(async () => {
handlers?.onConnected?.();
});
expect(bootstrap).toHaveBeenCalledTimes(2);
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(tree?.projects).toBeNull();
// The pre-change response now arrives and is correctly refused. What it
// queues in its place has no reader, so it is dropped rather than issued.
await act(async () => {
stale.resolve(bootstrapPayload);
});
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
expect(tree?.projects).toBeNull();
});
it('drops cached inbox rows and makes the next feed read authoritative', async () => {
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(state?.inboxSessions).toHaveLength(1);
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
listInbox.mockReturnValue(deferred<typeof inboxPayload>().promise);
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(state?.inboxSessions).toEqual([]);
expect(state?.nextCursor).toBeNull();
// Returning to a feed must reload page one destructively, not reconcile onto
// a window whose rows were just invalidated.
listInbox.mockResolvedValue({ sessions: [], next_cursor: null, unread_by_session: {} });
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
const feedRead = listInbox.mock.calls.at(-1)?.[0];
expect(feedRead).toMatchObject({ platform: 'avibe', limit: 30 });
expect(feedRead).not.toHaveProperty('before');
// reconcile() re-reads with cache disabled; page one does not.
expect(feedRead).not.toHaveProperty('cache');
expect(state?.inboxSessions).toEqual([]);
});
it('drops the feed retry the invalidation itself queues', async () => {
const stale = deferred<typeof inboxPayload>();
const countsOnly = { sessions: [], next_cursor: null, unread_by_session: { [session.id]: 3 } };
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const feedReads = () => listInbox.mock.calls.filter(([args]) => args.limit > 1).length;
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
expect(state?.inboxSessions).toHaveLength(1);
expect(feedReads()).toBe(1);
// A resume reconcile is in flight when the user navigates away. The
// counts-only read stays live throughout — it is what the remaining route
// legitimately reads.
listInbox.mockImplementation((args: ListInboxArgs) =>
args.limit > 1 ? stale.promise : Promise.resolve(countsOnly),
);
await resumePage();
expect(feedReads()).toBe(2);
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(state?.inboxSessions).toEqual([]);
await act(async () => {
stale.resolve(inboxPayload);
});
await settle();
expect(feedReads()).toBe(2);
expect(state?.inboxSessions).toEqual([]);
expect(state?.nextCursor).toBeNull();
});
it('re-reads the unread map when a mutation invalidates the counts read', async () => {
const first = deferred<typeof inboxPayload>();
const second = deferred<typeof inboxPayload>();
const listInbox = vi
.fn()
.mockReturnValueOnce(first.promise)
.mockReturnValueOnce(second.promise);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
render(
<WorkbenchInboxProvider>
<InboxProbe
feed={false}
onState={(next) => {
state = next;
}}
/>
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
// A live event lands while the counts read is in flight, so that response is
// no longer authoritative — and the event itself only carries one session's
// count. Discarding it silently would leave every other session's badge
// missing until some later focus or reconnect.
await act(async () => {
handlers?.onInboxSessionUpdated?.(inboxRow);
});
await act(async () => {
first.resolve({ ...inboxPayload, unread_by_session: { [session.id]: 3, ses_b: 5 } });
});
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
expect(listInbox.mock.calls[1][0]).toMatchObject({ platform: 'avibe', limit: 1 });
await act(async () => {
second.resolve({ ...inboxPayload, sessions: [], unread_by_session: { ses_b: 7 } });
});
await settle();
expect(state?.unreadBySession).toEqual({ ses_b: 7 });
expect(state?.totalUnread).toBe(7);
});
});
// The one thing in this provider that NO route is exempt from: every document
// badges the unread total on its favicon and app icon. So the demand gate may
// decide whether the 30-row feed is read, but never whether the whole-account
// map is — and the feed read is the one that usually carries it. These state that
// as a debt rather than as a list of reads: whichever read was supposed to
// deliver the map may fail, be invalidated, or be dropped by the gate, and the
// badge still ends up with one.
describe('the unread map no route gates', () => {
it('reapplies an unchanged authoritative badge count after a worker write', async () => {
const originalSetBadge = Object.getOwnPropertyDescriptor(navigator, 'setAppBadge');
const originalClearBadge = Object.getOwnPropertyDescriptor(navigator, 'clearAppBadge');
const originalWorker = Object.getOwnPropertyDescriptor(navigator, 'serviceWorker');
const setAppBadge = vi.fn(async () => {});
const clearAppBadge = vi.fn(async () => {});
const worker = new EventTarget();
Object.defineProperty(navigator, 'setAppBadge', { configurable: true, value: setAppBadge });
Object.defineProperty(navigator, 'clearAppBadge', { configurable: true, value: clearAppBadge });
Object.defineProperty(navigator, 'serviceWorker', { configurable: true, value: worker });
try {
const listInbox = vi.fn(async (_args: ListInboxArgs) => ({
sessions: [],
next_cursor: null,
unread_by_session: {},
}));
apiRef.current = { listInbox, connectWorkbenchEvents: vi.fn(() => vi.fn()) };
render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} />
</WorkbenchInboxProvider>,
);
await settle();
expect(clearAppBadge).toHaveBeenCalledOnce();
// The worker finished a stale write just after the page's last 0.
await setAppBadge(1);
await act(async () => {
worker.dispatchEvent(new MessageEvent('message', {
data: { type: 'vibe.push-badge-refresh' },
}));
});
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
expect(listInbox.mock.calls[1][0]).toMatchObject({ backgroundPush: true });
expect(clearAppBadge).toHaveBeenCalledTimes(2);
} finally {
cleanup();
if (originalSetBadge) Object.defineProperty(navigator, 'setAppBadge', originalSetBadge);
else Reflect.deleteProperty(navigator, 'setAppBadge');
if (originalClearBadge) Object.defineProperty(navigator, 'clearAppBadge', originalClearBadge);
else Reflect.deleteProperty(navigator, 'clearAppBadge');
if (originalWorker) Object.defineProperty(navigator, 'serviceWorker', originalWorker);
else Reflect.deleteProperty(navigator, 'serviceWorker');
}
});
it('badges only categories whose notifications are on, once the switches and the Bot list are known', async () => {
const originalSetBadge = Object.getOwnPropertyDescriptor(navigator, 'setAppBadge');
const originalClearBadge = Object.getOwnPropertyDescriptor(navigator, 'clearAppBadge');
const setAppBadge = vi.fn(async () => {});
const clearAppBadge = vi.fn(async () => {});
Object.defineProperty(navigator, 'setAppBadge', { configurable: true, value: setAppBadge });
Object.defineProperty(navigator, 'clearAppBadge', { configurable: true, value: clearAppBadge });
try {
// Two unread replies from a Bot; five and three from ordinary Sessions,
// one with an id that merely starts like a Bot's: the list decides.
const listInbox = vi.fn(async (_args: ListInboxArgs) => ({
sessions: [],
next_cursor: null,
unread_by_session: { ses_cso: 2, sesa1b2c3d4e5: 5, ses_ordinary: 3 },
}));
apiRef.current = { listInbox, connectWorkbenchEvents: vi.fn(() => vi.fn()) };
const roster: BotRoster = { sessionIds: new Set(['ses_main', 'ses_cso']), known: true };
const tree = (preferences: NotificationPreferencesState, bots: BotRoster = roster) => (
<BotRosterContext.Provider value={{ roster: bots, publish: () => {} }}>
<NotificationPreferencesContext.Provider value={preferences}>
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={(state) => { latest = state; }} />
</WorkbenchInboxProvider>
</NotificationPreferencesContext.Provider>
</BotRosterContext.Provider>
);
let latest: InboxState | null = null;
const sessionsMuted = { enabled: true, bots: true, sessions: false };
const view = render(tree({ preferences: sessionsMuted, loaded: false, update: async () => true }));
await settle();
// The map is in, the switches are not: a badge the push worker set while
// the app was closed is the better number, so nothing is written yet.
expect(setAppBadge).not.toHaveBeenCalled();
expect(clearAppBadge).not.toHaveBeenCalled();
// The switches are in, the Bot list is not: which unread is a Bot's is unknown.
view.rerender(tree({ preferences: sessionsMuted, loaded: true, update: async () => true }, UNKNOWN_BOT_ROSTER));
await settle();
expect(setAppBadge).not.toHaveBeenCalled();
expect(clearAppBadge).not.toHaveBeenCalled();
view.rerender(tree({ preferences: sessionsMuted, loaded: true, update: async () => true }));
await settle();
expect(setAppBadge).toHaveBeenLastCalledWith(2);
expect(latest).toMatchObject({ totalUnread: 10, badgeTotal: 2, unreadByCategory: { bot: 2, session: 8 } });
view.rerender(tree({ preferences: { ...sessionsMuted, enabled: false }, loaded: true, update: async () => true }));
await settle();
expect(clearAppBadge).toHaveBeenCalledOnce();
} finally {
cleanup();
if (originalSetBadge) Object.defineProperty(navigator, 'setAppBadge', originalSetBadge);
else Reflect.deleteProperty(navigator, 'setAppBadge');
if (originalClearBadge) Object.defineProperty(navigator, 'clearAppBadge', originalClearBadge);
else Reflect.deleteProperty(navigator, 'clearAppBadge');
}
});
it('reads the counts a dropped feed read was carrying', async () => {
const feedRead = deferred<typeof inboxPayload>();
const countsOnly = {
sessions: [inboxRow],
next_cursor: 'cursor_1',
unread_by_session: { [session.id]: 3, ses_b: 5 },
};
const listInbox = vi.fn((args: ListInboxArgs) =>
args.limit > 1 ? feedRead.promise : Promise.resolve(countsOnly),
);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const feedReads = () => listInbox.mock.calls.filter(([args]) => args.limit > 1).length;
const countsReads = () => listInbox.mock.calls.filter(([args]) => args.limit === 1).length;
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
expect(feedReads()).toBe(1);
expect(countsReads()).toBe(0);
// A live event invalidates that first page while it is still in flight, and
// carries only its own session's count — so no whole-account map has arrived.
await act(async () => {
handlers?.onInboxSessionUpdated?.(inboxRow);
});
// The user reaches a feedless route before it settles, so the replacement it
// queues is dropped: correct for the rows, and the map is now owed to nobody.
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
await act(async () => {
feedRead.resolve(inboxPayload);
});
await settle();
// No 30-row read is re-issued for a document that renders no feed...
expect(feedReads()).toBe(1);
// ...and the badge does not wait for a later focus, reconnect or permission
// change to learn every other session's count.
expect(countsReads()).toBe(1);
expect(state?.unreadBySession).toEqual({ [session.id]: 3, ses_b: 5 });
expect(state?.totalUnread).toBe(8);
});
it('leaves the counts alone when a healthy feed consumer detaches', async () => {
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
apiRef.current = { listInbox, connectWorkbenchEvents: vi.fn(() => vi.fn()) };
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
// Workbench → admin. The feed read already delivered a whole map, so the
// demand edge owes nothing: re-reading here would put back exactly the
// per-navigation traffic this provider exists to avoid.
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
expect(state?.unreadBySession).toEqual({ [session.id]: 3 });
});
it('reads the counts an authorization change left owing', async () => {
const stale = deferred<typeof inboxPayload>();
const postChange = { sessions: [], next_cursor: null, unread_by_session: { ses_b: 5 } };
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const feedReads = () => listInbox.mock.calls.filter(([args]) => args.limit > 1).length;
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
// A whole map HAS arrived, so "have we ever loaded one" is already satisfied
// here — and is the wrong question, because the map it describes is about to
// stop describing this account.
expect(state?.unreadBySession).toEqual({ [session.id]: 3 });
listInbox.mockImplementation((args: ListInboxArgs) =>
args.limit > 1 ? stale.promise : Promise.resolve(postChange),
);
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(feedReads()).toBe(2);
// That refresh is invalidated mid-flight, and its replacement is dropped when
// the user leaves the feed behind — so the read that owed the new scope's map
// never delivers one.
await act(async () => {
handlers?.onInboxSessionUpdated?.(inboxRow);
});
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
await act(async () => {
stale.resolve(inboxPayload);
});
await settle();
expect(feedReads()).toBe(2);
expect(state?.unreadBySession).toEqual({ ses_b: 5 });
expect(state?.totalUnread).toBe(5);
});
});
// The gate is a property of the READ, not of the events that trigger it. Written
// at call sites it has to be remembered by each of them, and these providers have
// more triggers than any list of guards would cover — a reconnect, session
// activity, a pin re-order, a status or turn-end row refresh, a foreground
// restore. So these seed one of every request-issuing shape and assert the
// property (a revalidation the next activation would redo costs nothing while
// nothing reads it) rather than enumerating the triggers that were remembered.
describe('the demand gate belongs to the reads, not to their triggers', () => {
it('drops every revalidation a stream event or a write triggers while nothing reads the tree', async () => {
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
const listSessions = vi.fn().mockResolvedValue({ sessions: [session], next_before_id: null });
const getSession = vi.fn().mockResolvedValue(session);
const updateSession = vi.fn().mockResolvedValue({ ...session, pinned: true });
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
getSession,
updateSession,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
let actions: WorkbenchProjectsActions | null = null;
const captureTree = (next: WorkbenchProjectsTree) => {
tree = next;
};
const captureActions = (next: WorkbenchProjectsActions) => {
actions = next;
};
const reads = () =>
bootstrap.mock.calls.length + listSessions.mock.calls.length + getSession.mock.calls.length;
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<ActionsProbe onState={captureActions} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(1);
// Workbench → /admin/settings/messaging. The write-only surface stays mounted
// (a settings page can still rename or pin), so the provider keeps its cache
// and its stream — it simply has no reader left.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<ActionsProbe onState={captureActions} />
</WorkbenchProjectsProvider>,
);
await settle();
const before = reads();
await act(async () => {
handlers?.onConnected?.();
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'created',
restored: true,
});
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'updated',
pinned: true,
});
handlers?.onSessionStatus?.({ session_id: session.id, agent_status: 'idle' });
handlers?.onTurnEnd?.({ session_id: session.id });
await actions?.setSessionPinned(project.id, session.id, true);
});
await settle();
// The gate drops revalidations, never mutations: the write still reaches the
// server and still patches the cache the way back will render.
expect(updateSession).toHaveBeenCalledTimes(1);
expect(tree?.sessionsOf(project.id).sessions?.[0]?.pinned).toBe(true);
expect(reads()).toBe(before);
// And nothing is lost by dropping them, which is what makes it a revalidation:
// the returning consumer re-reads the window once.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<ActionsProbe onState={captureActions} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
});
// The boundary that scopes the rule: a revalidation is a read the next activation
// would redo, so dropping it costs nothing. A POPULATING read produces something
// nothing else will produce — gating it would leave the group the write just
// expanded rendering empty on the way back, because the reconcile skips projects
// whose window was never loaded. So the exemption is a property of the read too,
// not a call site that forgot the gate.
it('still populates a window a write just created, with nothing reading the tree', async () => {
const projectB = { ...project, id: 'proj_b', scope_id: 'scope_b', display_name: 'Project B' };
const createdSession = { ...session, id: 'ses_new', project_id: projectB.id, scope_id: projectB.scope_id };
const bootstrap = vi.fn().mockResolvedValue({
projects: [project, projectB],
sessions: { proj_a: { sessions: [session], next_before_id: null } },
});
const listSessions = vi
.fn()
.mockResolvedValue({ sessions: [createdSession], next_before_id: null });
const createSession = vi.fn().mockResolvedValue(createdSession);
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
createSession,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
};
let tree: WorkbenchProjectsTree | null = null;
let actions: WorkbenchProjectsActions | null = null;
const captureTree = (next: WorkbenchProjectsTree) => {
tree = next;
};
const captureActions = (next: WorkbenchProjectsActions) => {
actions = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<ActionsProbe onState={captureActions} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.sessionsOf(projectB.id).sessions).toBeNull();
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<ActionsProbe onState={captureActions} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
await actions?.createSessionForProject(projectB.id);
});
await settle();
expect(listSessions).toHaveBeenCalledTimes(1);
expect(listSessions.mock.calls[0][0]).toMatchObject({ projectId: projectB.id });
expect(tree?.sessionsOf(projectB.id).sessions).toEqual([createdSession]);
});
// Exempting the populating reads at the read leaves exactly one demand
// decision the reads cannot make for themselves: a populating read whose
// response was refused re-queues ITSELF, and that retry is a revalidation
// wearing the populating read's name. So the intent flush keeps the gate for
// that one case and no other — the queued tree reconcile below it is gated by
// the read it runs, and double-gating it would give one property two owners.
it('drops the first load a mutation refused once its reader is gone', async () => {
const firstLoad = deferred<typeof bootstrapPayload>();
const bootstrap = vi.fn().mockReturnValue(firstLoad.promise);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const captureTree = (next: WorkbenchProjectsTree) => {
tree = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
// A turn ends while the first load is still in flight, which invalidates it.
await act(async () => {
handlers?.onTurnEnd?.({ session_id: session.id });
});
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
firstLoad.resolve(bootstrapPayload);
});
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
// Dropping it lost nothing: a returning consumer re-reads unconditionally.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
expect(tree?.projects).toHaveLength(1);
});
// The inbox's targeted restore read is the one revalidation that is only HALF
// droppable: the card it upserts is not rendered, but the same response owns that
// session's unread count, and `unreadBySession` holds only foreground sessions —
// so a restore genuinely moves the badge total. Declining the request therefore
// has to hand the obligation to the whole-account map instead of dropping it.
it('owes the whole map for a foreground restore instead of reading one session', async () => {
const beforeRestore = { sessions: [], next_cursor: null, unread_by_session: {} };
const afterRestore = {
sessions: [],
next_cursor: null,
unread_by_session: { [session.id]: 3, ses_b: 5 },
};
const listInbox = vi.fn().mockResolvedValueOnce(beforeRestore).mockResolvedValue(afterRestore);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const wholeCountsReads = () =>
listInbox.mock.calls.filter(([args]) => args.limit === 1 && !args.onlySession).length;
const targetedReads = () => listInbox.mock.calls.filter(([args]) => args.onlySession).length;
render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(wholeCountsReads()).toBe(1);
expect(state?.totalUnread).toBe(0);
await act(async () => {
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'updated',
visibility: 'foreground',
});
});
await settle();
// No card work for a document that renders no card...
expect(targetedReads()).toBe(0);
// ...and the badge still learns the count the restore brought back, which a
// plain skip would have left out until some later focus or reconnect.
expect(wholeCountsReads()).toBe(2);
expect(state?.unreadBySession).toEqual({ [session.id]: 3, ses_b: 5 });
expect(state?.totalUnread).toBe(8);
});
it('coalesces a burst of restores into one counts read', async () => {
const listInbox = vi.fn().mockResolvedValue({
sessions: [],
next_cursor: null,
unread_by_session: { [session.id]: 1, ses_b: 2, ses_c: 3 },
});
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
// Restoring a scope restores its sessions together. Owing one map is what
// makes that cost one read rather than one read per session — the reason the
// obligation is state and not a per-event request.
await act(async () => {
for (const sessionId of [session.id, 'ses_b', 'ses_c']) {
handlers?.onSessionActivity?.({
session_id: sessionId,
scope_id: session.scope_id,
event: 'updated',
visibility: 'foreground',
});
}
});
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
expect(listInbox.mock.calls[1][0]).toMatchObject({ platform: 'avibe', limit: 1 });
expect(state?.totalUnread).toBe(6);
});
// Owing the map and fencing the reads that could pay it are one act. A read that
// left the server before the change cannot describe the counts it is about to
// commit, and committing it would pay the debt without satisfying it — the case a
// bare `setWholeUnreadOwed(true)` cannot even schedule work for, because the debt
// was already outstanding. Stated over every edge that voids the current map
// rather than for one of them, because the property belongs to owing the map.
const mapVoidingEdges: Array<[string, (handlers: WorkbenchEventHandlers | null) => void]> = [
['an authorization change', (handlers) => handlers?.onAuthorizationChanged?.({})],
['unread counts moving without a map', (handlers) => handlers?.onInboxUnreadChanged?.({ unread_counts: {} })],
];
for (const [edge, fire] of mapVoidingEdges) {
it(`invalidates the counts read ${edge} left unable to describe the account`, async () => {
const preChange = deferred<typeof inboxPayload>();
const listInbox = vi
.fn()
.mockReturnValueOnce(preChange.promise)
.mockResolvedValue({ sessions: [], next_cursor: null, unread_by_session: { ses_b: 5 } });
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
await act(async () => {
fire(handlers);
});
await act(async () => {
preChange.resolve({ ...inboxPayload, unread_by_session: { [session.id]: 3 } });
});
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
expect(state?.unreadBySession).toEqual({ ses_b: 5 });
expect(state?.totalUnread).toBe(5);
});
}
});
// Round 5 moved the demand decision into the reads; this states WHEN each read
// asks it. Two things can make a response impossible or pointless to commit —
// no reader left, and nowhere to put it — and both used to be answered somewhere
// other than the moment of asking: the first once on the way into a read that
// then issues many requests, the second only after a request had been paid for.
// A read is not one request. `reconcileSessions` pages a window, the tree rebuild
// issues one bootstrap per window size, and both go round again on a refused
// response. So the property is per REQUEST: every request is preceded by the same
// predicate, and a read that cannot commit anything issues nothing at all.
describe('every request is preceded by the question, not every read', () => {
it('stops paging a window between pages when its last reader leaves', async () => {
const sessionB = { ...session, id: 'ses_b' };
const bootstrap = vi.fn().mockResolvedValue({
projects: [project],
sessions: { proj_a: { sessions: [session, sessionB], next_before_id: null } },
});
const firstPage = deferred<{ sessions: Array<typeof session>; next_before_id: string | null }>();
const listSessions = vi
.fn()
.mockReturnValueOnce(firstPage.promise)
.mockResolvedValue({ sessions: [sessionB], next_before_id: null });
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const captureTree = (next: WorkbenchProjectsTree) => {
tree = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(2);
// Activity on a two-row window starts a reconcile that needs two pages.
await act(async () => {
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'user_message',
});
});
expect(listSessions).toHaveBeenCalledTimes(1);
// Workbench → /admin between page one and page two.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
firstPage.resolve({ sessions: [session], next_before_id: 'cursor_2' });
});
await settle();
// An entry gate passed before the navigation would have finished rebuilding a
// window nobody renders, one page at a time.
expect(listSessions).toHaveBeenCalledTimes(1);
// And the abandoned half costs nothing: the window is still what it was, and
// the returning consumer re-reads it.
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(2);
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
});
it('stops rebuilding the tree between window-size groups', async () => {
// The rebuild batches projects by how much of each window has to come back,
// so it is one request per distinct size — a loop like any other.
const projectWide = { ...project, id: 'proj_wide', scope_id: 'scope_wide', display_name: 'Wide' };
const wideWindow = Array.from({ length: 10 }, (_, index) => ({
...session,
id: `ses_wide_${index}`,
project_id: projectWide.id,
scope_id: projectWide.scope_id,
}));
const treePayload = {
projects: [project, projectWide],
sessions: {
[project.id]: { sessions: [session], next_before_id: null },
[projectWide.id]: { sessions: wideWindow, next_before_id: null },
},
};
const firstGroup = deferred<typeof treePayload>();
const bootstrap = vi
.fn()
.mockResolvedValueOnce(treePayload)
.mockReturnValueOnce(firstGroup.promise)
.mockResolvedValue(treePayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions: vi.fn().mockResolvedValue({ sessions: [], next_before_id: null }),
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
await act(async () => {
handlers?.onConnected?.();
});
expect(bootstrap).toHaveBeenCalledTimes(2);
expect(bootstrap.mock.calls[1][0]).toMatchObject({ projectIds: [project.id] });
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
firstGroup.resolve(treePayload);
});
await settle();
// The ten-row group is never asked for.
expect(bootstrap).toHaveBeenCalledTimes(2);
});
it('stops a row refresh that a mid-flight event sent round again', async () => {
// This read loops in place: an event landing while it is in flight refuses the
// response and makes it read the row again. The second read is a request of
// its own and asks the question of its own.
const unbound = { ...session, native_session_id: null };
const bootstrap = vi.fn().mockResolvedValue({
projects: [project],
sessions: { proj_a: { sessions: [unbound], next_before_id: null } },
});
const firstRead = deferred<typeof unbound>();
const getSession = vi.fn().mockReturnValueOnce(firstRead.promise).mockResolvedValue(unbound);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
getSession,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
handlers?.onTurnEnd?.({ session_id: session.id });
});
expect(getSession).toHaveBeenCalledTimes(1);
// A second turn-end refuses the read in flight and queues another pass.
await act(async () => {
handlers?.onTurnEnd?.({ session_id: session.id });
});
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
firstRead.resolve(unbound);
});
await settle();
expect(getSession).toHaveBeenCalledTimes(1);
});
// The other half of the question. A populating read is exempt from demand, but
// it still has to have somewhere to land — and it already knew the answer, since
// it discarded every response that came back for a project the tree does not
// hold. Asking first is the same question one round-trip earlier.
it('issues no window read for a fork on a document that never loaded the tree', async () => {
const forked = { ...session, id: 'ses_forked' };
const forkSession = vi.fn().mockResolvedValue(forked);
const listSessions = vi.fn().mockResolvedValue({ sessions: [forked], next_before_id: null });
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
forkSession,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
};
let actions: WorkbenchProjectsActions | null = null;
const captureActions = (next: WorkbenchProjectsActions) => {
actions = next;
};
// /chat/:id renders one session, never the tree — but it does fork.
render(
<WorkbenchProjectsProvider>
<ActionsProbe onState={captureActions} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
await actions?.forkSession(project.id, session.id);
});
await settle();
// The write is untouched; only the read that had nowhere to commit is gone.
expect(forkSession).toHaveBeenCalledTimes(1);
expect(listSessions).not.toHaveBeenCalled();
expect(bootstrap).not.toHaveBeenCalled();
});
// The boundary that makes asking first safe. A write can CREATE the address in
// the same tick it asks for the window, so membership has to be true when the
// write returns rather than one render later — the list and its mirror are
// committed together for exactly this.
it('loads the window of a project the write it followed just added', async () => {
const newProject = { ...project, id: 'proj_new', scope_id: 'scope_new', display_name: 'New' };
const newSession = { ...session, id: 'ses_new', project_id: newProject.id, scope_id: newProject.scope_id };
const bootstrap = vi.fn().mockResolvedValue({ projects: [project], sessions: {} });
const listSessions = vi.fn().mockResolvedValue({ sessions: [newSession], next_before_id: null });
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn(() => vi.fn()),
createProject: vi.fn().mockImplementation(async () => {
bootstrap.mockResolvedValue({ projects: [project, newProject], sessions: {} });
return newProject;
}),
};
let tree: WorkbenchProjectsTree | null = null;
const captureTree = (next: WorkbenchProjectsTree) => {
tree = next;
};
render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toEqual([project]);
// Opening a new folder appends the project and asks for its sessions in the
// same statement. Subsequent reads observe the completed creation.
await act(async () => {
await tree?.createProject({ folder_path: newProject.folder_path });
});
await settle();
expect(listSessions).toHaveBeenCalledTimes(1);
expect(listSessions.mock.calls[0][0]).toMatchObject({ projectId: newProject.id });
expect(tree?.projects).toEqual([project, newProject]);
expect(tree?.sessionsOf(newProject.id).sessions).toEqual([newSession]);
});
// The window read's own copy of the one demand decision a read cannot make for
// itself: a populating read whose response a mutation refused re-queues ITSELF,
// and that retry is a revalidation wearing the populating read's name. Same rule
// as ``flushBootstrapReadIntent``, one level down.
it('drops the window retry a mutation refused, once its reader is gone', async () => {
const bootstrap = vi.fn().mockResolvedValue({ projects: [project], sessions: {} });
const firstLoad = deferred<{ sessions: Array<typeof session>; next_before_id: string | null }>();
const listSessions = vi
.fn()
.mockReturnValueOnce(firstLoad.promise)
.mockResolvedValue({ sessions: [session], next_before_id: null });
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const captureTree = (next: WorkbenchProjectsTree) => {
tree = next;
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
// Expanding a group populates its window — exempt from demand, and in flight.
await act(async () => {
tree?.toggleExpanded(project.id);
});
expect(listSessions).toHaveBeenCalledTimes(1);
// Activity invalidates that read, so its response can no longer be committed.
await act(async () => {
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'updated',
title: 'Fresh title',
});
});
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
firstLoad.resolve({ sessions: [session], next_before_id: null });
});
await settle();
// With a reader still there this retries (see WorkbenchSessionReadOrdering);
// with none, the window it would keep filled has nobody to fill it for.
expect(listSessions).toHaveBeenCalledTimes(1);
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} onState={captureTree} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
});
});
// Gating the reads makes requests refusable, and a refusable request cannot be
// where an obligation lives: a debt is a LEVEL, cleared only by the commit that
// satisfies it, so whatever discharges it must be driven by the level rather
// than by the attempt carrying it or by the state edge that created it. Both
// members below record what is owed at one moment and pay it at another, with a
// demand gate, a navigation or a failure in between.
describe('a debt outlives the read that was carrying it', () => {
it('rebuilds the width a restore asked for after the gate declined to pay it', async () => {
const wideWindow = Array.from({ length: 10 }, (_, index) => ({
...session,
id: `ses_wide_${index}`,
}));
const treePayload = {
projects: [project],
sessions: { [project.id]: { sessions: wideWindow, next_before_id: null } },
};
// The rebuild that honours the debt comes back one row short of it: first
// with more rows behind a cursor, then from a source that says there are
// none. Only the second can settle a minimum it did not reach.
const shortOfTheDebt = {
projects: [project],
sessions: { [project.id]: { sessions: wideWindow, next_before_id: 'cursor_2' } },
};
const inFlightPage = deferred<{ sessions: typeof wideWindow; next_before_id: string | null }>();
const bootstrap = vi
.fn()
.mockResolvedValueOnce(treePayload)
.mockResolvedValueOnce(shortOfTheDebt)
.mockResolvedValue(treePayload);
const listSessions = vi
.fn()
.mockReturnValueOnce(inFlightPage.promise)
.mockResolvedValue({ sessions: wideWindow, next_before_id: null });
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
const { rerender } = render(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
// A reconcile of the ten-row window is in flight...
await act(async () => {
handlers?.onSessionActivity?.({
session_id: wideWindow[0].id,
scope_id: project.scope_id,
event: 'user_message',
});
});
expect(listSessions).toHaveBeenCalledTimes(1);
// ...when Undo restores a session ranked just past it. One row more than is
// loaded is the only record of that restore: every other path sizes this
// project's window from the rows already cached.
await act(async () => {
handlers?.onSessionActivity?.({
session_id: 'ses_restored',
scope_id: project.scope_id,
event: 'created',
restored: true,
});
});
// Workbench → /admin, and the page lands with no reader left to widen for.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
inFlightPage.resolve({ sessions: wideWindow, next_before_id: 'cursor_2' });
});
await settle();
expect(listSessions).toHaveBeenCalledTimes(1);
// Back on the workbench the rebuild asks for eleven rows, not the ten the
// cache holds: refusing a request declines to pay the debt, it does not
// discharge it, and no later revalidation would put the restored row back.
rerender(
<WorkbenchProjectsProvider>
<TreeProbe active={false} />
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
expect(bootstrap.mock.calls[1][0]).toMatchObject({ projectIds: [project.id], limit: 11 });
// That rebuild committed ten rows with a cursor behind them, so it did not
// reach the minimum and does not get to clear it either: the reconnect
// still asks for eleven. Paying part of a debt is not paying it.
await act(async () => {
handlers?.onConnected?.();
});
await settle();
expect(bootstrap).toHaveBeenCalledTimes(3);
expect(bootstrap.mock.calls[2][0]).toMatchObject({ projectIds: [project.id], limit: 11 });
// This one commits the same ten rows with nothing behind them. A source
// that says there is no eleventh row settles the debt as surely as one
// that produces it — otherwise a restore later undone would widen every
// rebuild of this project forever.
await act(async () => {
handlers?.onConnected?.();
});
await settle();
expect(bootstrap).toHaveBeenCalledTimes(4);
expect(bootstrap.mock.calls[3][0]).toMatchObject({ projectIds: [project.id], limit: 10 });
});
it('re-reads the counts a failed read left owing', async () => {
const listInbox = vi
.fn()
.mockRejectedValueOnce(new Error('counts read failed'))
.mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
const logged = vi.spyOn(console, 'error').mockImplementation(() => {});
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
expect(state?.unreadBySession).toEqual({});
// The counts changed and the event did not say how, so all it can do is owe a
// whole map — one that is already owed, by a read that failed and is no longer
// in flight. There is no state edge for an effect to run on and no in-flight
// read for the fence to re-arm, so nothing but the level itself can reach this
// debt, and the badge would keep counts nothing describes until some unrelated
// focus or reconnect.
await act(async () => {
handlers?.onInboxUnreadChanged?.({ unread_counts: {} });
});
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
expect(state?.unreadBySession).toEqual({ [session.id]: 3 });
expect(state?.totalUnread).toBe(3);
logged.mockRestore();
});
});
// Every read in this shell that loops in place re-enters on evidence its own
// pass produced: a mutation that invalidated the response, or a trigger the
// in-flight guard turned away and now owes a pass. An outstanding obligation is
// not that evidence — it is the reason the work exists, and it says nothing
// about whether another attempt can discharge it. A loop that re-enters on the
// obligation alone spins for as long as it keeps being refused.
//
// Each loop asserts it here rather than being correct by construction, so the
// next change to any of them fails a test instead of costing a review round.
describe('a read loop retries only on evidence its own pass produced', () => {
// Twenty rejections then a success: an escape hatch turns a retry loop into a
// countable assertion instead of a test that hangs on its own microtasks.
function failingReads<T>(value: T) {
let attempts = 0;
return vi.fn(async () => {
attempts += 1;
if (attempts <= 20) throw new Error('read failed');
return value;
});
}
it('honours a trigger the in-flight guard turned away, exactly once', async () => {
// The positive half of the rule. This trigger has no other payer: the guard
// sent its caller home, so unless the read in flight goes round again the
// event is simply lost — and it must go round ONCE, not for as long as the
// record of it survives.
const windowPage = { sessions: [session], next_before_id: null };
const bootstrap = vi.fn().mockResolvedValue({
projects: [project],
sessions: { [project.id]: windowPage },
});
const inFlight = deferred<typeof windowPage>();
let laterReads = 0;
const listSessions = vi.fn().mockReturnValueOnce(inFlight.promise).mockImplementation(async () => {
laterReads += 1;
// An escape hatch again: an empty window has nothing left to reconcile, so
// a loop that never consumes the trigger it honoured is a count rather
// than a hung suite.
return laterReads >= 20 ? { sessions: [], next_before_id: null } : windowPage;
});
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
render(
<WorkbenchProjectsProvider>
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: project.scope_id,
event: 'user_message',
});
});
expect(listSessions).toHaveBeenCalledTimes(1);
// A second event lands while that read is in flight and is turned away.
await act(async () => {
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: project.scope_id,
event: 'user_message',
});
});
await act(async () => {
inFlight.resolve(windowPage);
});
await settle();
expect(listSessions).toHaveBeenCalledTimes(2);
});
it('leaves the debt its own failed window read could not pay to the next trigger', async () => {
const wideWindow = Array.from({ length: 10 }, (_, index) => ({
...session,
id: `ses_wide_${index}`,
}));
const bootstrap = vi.fn().mockResolvedValue({
projects: [project],
sessions: { [project.id]: { sessions: wideWindow, next_before_id: null } },
});
const listSessions = failingReads({ sessions: wideWindow, next_before_id: null });
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
listSessions,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
render(
<WorkbenchProjectsProvider>
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
expect(bootstrap).toHaveBeenCalledTimes(1);
// Undo restores a session ranked just past the window, so this reconcile
// carries a minimum of eleven — and its first request fails.
await act(async () => {
handlers?.onSessionActivity?.({
session_id: 'ses_restored',
scope_id: project.scope_id,
event: 'created',
restored: true,
});
});
await settle();
// A failed request is not evidence that another one would land. Demand is
// still here and the debt is still owed, and neither says this pass can pay
// it: retrying on the debt alone is an unbounded loop against a failing API.
expect(listSessions).toHaveBeenCalledTimes(1);
// The debt is untouched, so the next trigger asks for eleven rows: the
// failure declined to pay it, exactly as a refusal does.
await act(async () => {
handlers?.onConnected?.();
});
await settle();
expect(bootstrap).toHaveBeenCalledTimes(2);
expect(bootstrap.mock.calls[1][0]).toMatchObject({ projectIds: [project.id], limit: 11 });
});
it('stops a row refresh whose read failed instead of reading the row again', async () => {
const unbound = { ...session, native_session_id: null };
const bootstrap = vi.fn().mockResolvedValue({
projects: [project],
sessions: { proj_a: { sessions: [unbound], next_before_id: null } },
});
const getSession = failingReads(unbound);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
getSession,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
render(
<WorkbenchProjectsProvider>
<TreeProbe />
</WorkbenchProjectsProvider>,
);
await settle();
await act(async () => {
handlers?.onTurnEnd?.({ session_id: session.id });
});
await settle();
// The next turn-end re-reads this row anyway; a failed one has no reason of
// its own to go round again.
expect(getSession).toHaveBeenCalledTimes(1);
});
it('stops a targeted card read whose request failed', async () => {
const logged = vi.spyOn(console, 'error').mockImplementation(() => {});
const feedPage = { sessions: [inboxRow], next_cursor: null, unread_by_session: {} };
const listInbox = vi.fn(async (args: ListInboxArgs) => {
if (!args.onlySession) return feedPage;
throw new Error('targeted read failed');
});
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
const targetedReads = () => listInbox.mock.calls.filter(([args]) => args.onlySession).length;
await act(async () => {
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'updated',
visibility: 'foreground',
});
});
await settle();
expect(targetedReads()).toBe(1);
logged.mockRestore();
});
});
// An authorization change is an INVALIDATION. Demand decides only whether a
// replacement READ follows it — never whether the cache it voids is dropped.
// Reading the two as one question is what puts the drop in the no-consumer
// branch, which says "nothing is reading, so let it go" when the actual reason
// is that the change made the rows unauthorized. With a consumer the caches
// then merely revalidate, and every one of them deliberately PRESERVES what it
// holds when a read fails, so a revoked row stays rendered for as long as the
// replacement takes and indefinitely if it never lands.
describe('an authorization change invalidates whether or not anyone is reading', () => {
it('drops the project tree at the edge, then re-reads it as a first load', async () => {
const replacement = deferred<typeof bootstrapPayload>();
const bootstrap = vi.fn().mockResolvedValue(bootstrapPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const capture = (next: WorkbenchProjectsTree) => {
tree = next;
};
render(
<WorkbenchProjectsProvider>
<TreeProbe onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toHaveLength(1);
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(1);
bootstrap.mockReturnValue(replacement.promise);
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
// Asserted while the replacement read is still in flight: the edge is what
// drops it, not the response.
expect(tree?.projects).toBeNull();
expect(tree?.sessionsOf(project.id).sessions).toBeNull();
// And what follows is the authoritative first load, not a reconcile of the
// window this same edge just dropped — a reconcile would re-read only the
// projects it still had cached, which is now none of them.
expect(bootstrap).toHaveBeenCalledTimes(2);
expect(bootstrap.mock.calls.at(-1)?.[0]).not.toHaveProperty('projectIds');
await act(async () => {
replacement.resolve(bootstrapPayload);
});
await settle();
expect(tree?.projects).toHaveLength(1);
expect(tree?.sessionsOf(project.id).sessions).toHaveLength(1);
});
it('refuses a tree response the server produced before the change', async () => {
const stale = deferred<typeof bootstrapPayload>();
const pending = deferred<typeof bootstrapPayload>();
const bootstrap = vi
.fn()
.mockResolvedValueOnce(bootstrapPayload)
.mockReturnValueOnce(stale.promise)
.mockReturnValue(pending.promise);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const capture = (next: WorkbenchProjectsTree) => {
tree = next;
};
render(
<WorkbenchProjectsProvider>
<TreeProbe onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toHaveLength(1);
// A reconnect reconcile is in flight when access changes under it.
await act(async () => {
handlers?.onConnected?.();
});
expect(bootstrap).toHaveBeenCalledTimes(2);
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(tree?.projects).toBeNull();
// The pre-change snapshot now arrives. Fencing belongs to the edge for the
// same reason the drop does: this response describes the authorization the
// change replaced, whether or not a consumer is waiting for it.
await act(async () => {
stale.resolve(bootstrapPayload);
});
await settle();
expect(tree?.projects).toBeNull();
});
it('drops the inbox feed at the edge, not only when nothing reads it', async () => {
const replacement = deferred<typeof inboxPayload>();
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const feedReads = () => listInbox.mock.calls.filter(([args]) => args.limit > 1);
render(
<WorkbenchInboxProvider>
<InboxProbe feed onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(state?.inboxSessions).toHaveLength(1);
expect(state?.nextCursor).toBe('cursor_1');
listInbox.mockReturnValue(replacement.promise);
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
// Asserted before the replacement read settles, and the cursor goes with
// the rows: a cursor is a position in a list this document may no longer be
// allowed to page through.
expect(state?.inboxSessions).toEqual([]);
expect(state?.nextCursor).toBeNull();
// The consumer is still reading, so a replacement follows the drop — and
// having dropped the window is what makes it the authoritative page one
// rather than a reconcile onto rows that are no longer there.
expect(feedReads()).toHaveLength(2);
expect(feedReads().at(-1)?.[0]).toMatchObject({ platform: 'avibe', limit: 30 });
expect(feedReads().at(-1)?.[0]).not.toHaveProperty('cache');
await act(async () => {
replacement.resolve({ sessions: [], next_cursor: null, unread_by_session: {} });
});
await settle();
expect(state?.inboxSessions).toEqual([]);
});
it('refuses a feed response the change outran, even when its replacement is dropped', async () => {
const stale = deferred<typeof inboxPayload>();
const countsOnly = { sessions: [], next_cursor: null, unread_by_session: { [session.id]: 3 } };
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
expect(state?.inboxSessions).toHaveLength(1);
// A resume reconcile is in flight when access changes under it.
listInbox.mockImplementation((args: ListInboxArgs) =>
args.limit > 1 ? stale.promise : Promise.resolve(countsOnly),
);
await resumePage();
// The change lands while the feed still has a reader, so a replacement read
// is queued behind the one in flight...
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(state?.inboxSessions).toEqual([]);
// ...and then the reader leaves, which drops that queued read. Nothing is
// left to replace the rows, so the edge itself has to have refused the
// response that is about to arrive.
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
await act(async () => {
stale.resolve(inboxPayload);
});
await settle();
expect(state?.inboxSessions).toEqual([]);
expect(state?.nextCursor).toBeNull();
});
// A straggler of the same rule that moved the gate onto the reads: this loop
// asks once on the way in, so a retry queued while a card was rendered still
// runs after the last feed consumer left.
it('stops a queued targeted retry whose feed consumer left, and owes the map instead', async () => {
const inFlight = deferred<typeof inboxPayload>();
const countsOnly = { sessions: [], next_cursor: null, unread_by_session: { [session.id]: 7 } };
const listInbox = vi.fn().mockImplementation((args: ListInboxArgs) => {
if (args.onlySession) return inFlight.promise;
return Promise.resolve(args.limit > 1 ? inboxPayload : countsOnly);
});
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const targetedReads = () => listInbox.mock.calls.filter(([args]) => args.onlySession).length;
const wholeCountsReads = () =>
listInbox.mock.calls.filter(([args]) => args.limit === 1 && !args.onlySession).length;
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
const restore = () =>
handlers?.onSessionActivity?.({
session_id: session.id,
scope_id: session.scope_id,
event: 'updated',
visibility: 'foreground',
});
await act(async () => {
restore();
});
expect(targetedReads()).toBe(1);
// A second restore lands mid-read, so the loop owes itself another pass.
await act(async () => {
restore();
});
expect(targetedReads()).toBe(1);
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
const countsBefore = wholeCountsReads();
await act(async () => {
inFlight.resolve(inboxPayload);
});
await settle();
// The card that pass would upsert is not rendered anywhere, so the request
// is declined — but its other half is the session's unread count, which
// every route badges, so the obligation moves to the whole-account map.
expect(targetedReads()).toBe(1);
expect(wholeCountsReads()).toBeGreaterThan(countsBefore);
expect(state?.unreadBySession).toEqual({ [session.id]: 7 });
});
});
// A guard that declines on a CORRELATE of the thing it needs is right until the
// two come apart. "A feed consumer exists" correlates with "the feed read will
// carry the map", and "this is a read" correlates with "this is how a row reaches
// the cache" — both hold in the common case and both have an edge where they do
// not, and on that edge the guard silently drops what it was protecting.
describe('a guard names the invariant, not something that usually travels with it', () => {
it('reads the map a live feed consumer left owing, without reading it twice', async () => {
const listInbox = vi.fn().mockResolvedValue(inboxPayload);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
expect(state?.unreadBySession).toEqual({ [session.id]: 3 });
// The counts moved and the event did not say how, so the map this document
// holds no longer describes the account. Nothing is in flight to replace it:
// the feed read that would normally carry one already finished.
listInbox.mockResolvedValue({ ...inboxPayload, unread_by_session: { [session.id]: 9 } });
await act(async () => {
handlers?.onInboxUnreadChanged?.({});
});
await settle();
// Having a feed consumer is not having a payment scheduled. The debt is paid
// by ASKING for the read that carries the map...
expect(listInbox).toHaveBeenCalledTimes(2);
expect(state?.unreadBySession).toEqual({ [session.id]: 9 });
// ...and by asking once: the read this queued is the payment, so the counts
// effect that also observes the debt must not add a second request.
await settle();
expect(listInbox).toHaveBeenCalledTimes(2);
});
it('pays a debt raised over the very read that debt just fenced', async () => {
const feedRead = deferred<typeof inboxPayload>();
const listInbox = vi.fn((args: ListInboxArgs) =>
args.limit > 1 && listInbox.mock.calls.length === 1
? feedRead.promise
: Promise.resolve({ ...inboxPayload, unread_by_session: { ses_b: 5 } }),
);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
// Raising the debt fences the reads that started before it — including this
// one. It is in flight AND it is guaranteed not to pay.
await act(async () => {
handlers?.onInboxUnreadChanged?.({});
});
await act(async () => {
feedRead.resolve(inboxPayload);
});
await settle();
// Its rows are still current and commit; its map is refused, exactly as the
// fence intends. Something else therefore has to carry one.
expect(listInbox).toHaveBeenCalledTimes(2);
expect(state?.unreadBySession).toEqual({ ses_b: 5 });
});
it('re-owes the map when the gate drops the read that was going to carry it', async () => {
const feedRead = deferred<typeof inboxPayload>();
const listInbox = vi.fn((args: ListInboxArgs) =>
args.limit > 1
? feedRead.promise
: Promise.resolve({ sessions: [], next_cursor: null, unread_by_session: { ses_b: 5 } }),
);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const feedReads = () => listInbox.mock.calls.filter(([args]) => args.limit > 1).length;
const countsReads = () => listInbox.mock.calls.filter(([args]) => args.limit === 1).length;
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
<InboxProbe feed />
</WorkbenchInboxProvider>,
);
await settle();
expect(feedReads()).toBe(1);
// The debt is raised while a feed consumer is mounted, so the payment it
// schedules is a feed read — which cannot start until the one in flight ends.
await act(async () => {
handlers?.onInboxUnreadChanged?.({});
});
// The user leaves for a feedless route first. The demand edge is observed
// while that payment is still only queued, so the settle it triggers sees a
// payment scheduled and correctly stands aside...
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(countsReads()).toBe(0);
await act(async () => {
feedRead.resolve(inboxPayload);
});
await settle();
// ...which makes the gate's drop the moment that payment stops existing, and
// therefore the moment the debt has to be owed again. No 30-row read for a
// feedless document, and no badge left describing counts that already moved.
expect(feedReads()).toBe(1);
expect(countsReads()).toBe(1);
expect(state?.unreadBySession).toEqual({ ses_b: 5 });
});
it('re-tests a debt its only payer failed to pay, at the next demand edge', async () => {
const reconcileRead = deferred<typeof inboxPayload>();
const listInbox = vi.fn((args: ListInboxArgs) => {
if (args.limit === 1) {
return Promise.resolve({ sessions: [], next_cursor: null, unread_by_session: { ses_b: 5 } });
}
return listInbox.mock.calls.filter(([a]) => a.limit > 1).length === 1
? Promise.resolve(inboxPayload)
: reconcileRead.promise;
});
const feedReads = () => listInbox.mock.calls.filter(([args]) => args.limit > 1).length;
const countsReads = () => listInbox.mock.calls.filter(([args]) => args.limit === 1).length;
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
const { rerender } = render(
<WorkbenchInboxProvider>
<InboxProbe feed onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(feedReads()).toBe(1);
// The debt is raised with a feed consumer mounted, so the payment it
// schedules is a feed read — and that read is the only payer there is.
await act(async () => {
handlers?.onInboxUnreadChanged?.({});
});
await settle();
expect(feedReads()).toBe(2);
// It fails. Re-asking here would re-enter on the debt itself, which is the
// one thing that cannot decide when to retry: it is still owed precisely
// because the last attempt failed, so the loop would never end.
await act(async () => {
reconcileRead.reject(new Error('offline'));
});
await settle();
expect(countsReads()).toBe(0);
// A demand edge is a real event rather than a level, and it changes which
// read can pay: leaving the feed makes the counts-only read the one that
// can, so the badge recovers there instead of on a timer.
rerender(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(feedReads()).toBe(2);
expect(countsReads()).toBe(1);
expect(state?.unreadBySession).toEqual({ ses_b: 5 });
});
it('collapses a burst of debts into one re-read rather than one read each', async () => {
const firstRead = deferred<typeof inboxPayload>();
const listInbox = vi.fn(() =>
listInbox.mock.calls.length === 1
? firstRead.promise
: Promise.resolve({ sessions: [], next_cursor: null, unread_by_session: { ses_b: 5 } }),
);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
listInbox,
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let state: InboxState | null = null;
const capture = (next: InboxState) => {
state = next;
};
render(
<WorkbenchInboxProvider>
<InboxProbe feed={false} onState={capture} />
</WorkbenchInboxProvider>,
);
await settle();
expect(listInbox).toHaveBeenCalledTimes(1);
// Three events land while that read is in flight. Each one voids the map the
// read is carrying, so each one genuinely re-owes it — what they must not do
// is each buy their own request for the same answer.
for (let i = 0; i < 3; i += 1) {
await act(async () => {
handlers?.onInboxUnreadChanged?.({});
});
}
expect(listInbox).toHaveBeenCalledTimes(1);
await act(async () => {
firstRead.resolve(inboxPayload);
});
await settle();
// The read in flight is what makes the debt a flag instead of a fan-out: it
// absorbs the burst, and the one re-read it owes afterwards answers all three.
expect(listInbox).toHaveBeenCalledTimes(2);
expect(state?.unreadBySession).toEqual({ ses_b: 5 });
});
it('refuses a project a create wrote after the change that dropped the tree', async () => {
const created = deferred<typeof project>();
// The re-read the change triggers stays in flight, so the tree observed below
// is the one the drop left behind rather than a fresh authorized load.
const reload = deferred<typeof bootstrapPayload>();
const bootstrap = vi
.fn()
.mockResolvedValueOnce(bootstrapPayload)
.mockReturnValue(reload.promise);
let handlers: WorkbenchEventHandlers | null = null;
apiRef.current = {
getWorkbenchProjectsBootstrap: bootstrap,
createProject: vi.fn(() => created.promise),
connectWorkbenchEvents: vi.fn((next) => {
handlers = next;
return vi.fn();
}),
};
let tree: WorkbenchProjectsTree | null = null;
const capture = (next: WorkbenchProjectsTree) => {
tree = next;
};
render(
<WorkbenchProjectsProvider>
<TreeProbe onState={capture} />
</WorkbenchProjectsProvider>,
);
await settle();
expect(tree?.projects).toHaveLength(1);
// The user creates a project, and access changes while that write is in
// flight. The tree is dropped — including the row the create was going to
// land next to.
let placed: unknown;
let writing: Promise<void> | undefined;
await act(async () => {
writing = tree!.createProject({ folder_path: '/tmp/new' }).then((result) => {
placed = result;
});
});
await act(async () => {
handlers?.onAuthorizationChanged?.();
});
expect(tree?.projects).toBeNull();
await act(async () => {
created.resolve({ ...project, id: 'proj_new' });
await writing;
});
await settle();
// A write is the other way a row reaches this cache, and it is the only one
// that can SEED it: committing here would rebuild the tree from an
// authorization this document no longer holds, out of a single row. The
// project exists on the server; the next activation is what decides whether
// this document may see it.
expect(tree?.projects).toBeNull();
expect(placed).toBeNull();
});
});
});