Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
perf(graphql-cache): prioritize optimistic affected rereads (#5428)
Sean Aye56bc758700b4
diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.tsindex 5c0c788f55..3c6a19d9d4 100644--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.test.ts@@ -124,7 +124,12 @@ const ALIASED_RENAME_MUTATION = gql``;type FakeHost = CacheHost & {- reads: Array<{ opKey?: number; query: string; variables?: object }>;+ reads: Array<{+ opKey?: number;+ query: string;+ variables?: object;+ priority?: 'user-visible';+ }>;writes: Array<{ opKey?: number; data: unknown; identity?: string }>;begins: Array<{query: string;@@ -184,6 +189,7 @@ function makeFakeHost(): FakeHost {opKey: args.opKey,query: args.query,variables: args.variables,+ priority: args.priority,});return readResult;},@@ -825,18 +831,27 @@ describe('normalizedCacheExchange', () => {expect(host.writes[0]?.identity).toBe('macro|[email protected]');});- it('re-executes affected active operations as cache-first', async () => {+ it('re-executes each affected active operation once as a prioritized cache read', async () => {+ host.scriptRead({ kind: 'hit', data: { from: 'cache' } });const { ops, client } = harness(host);const op = makeOp(7, 'cache-and-network');ops.next(op);await tick();+ vi.mocked(client.reexecuteOperation).mockImplementation((reissued) => {+ ops.next(reissued);+ });host.pushAffected([7, 999]); // 999 is not active → ignored+ await tick();+const reexec = vi.mocked(client.reexecuteOperation);expect(reexec).toHaveBeenCalledOnce();const reissued = reexec.mock.calls[0]?.[0] as Operation;expect(reissued.key).toBe(7);expect(reissued.context.requestPolicy).toBe('cache-first');+ expect(host.reads).toHaveLength(2);+ expect(host.reads[0]?.priority).toBeUndefined();+ expect(host.reads[1]?.priority).toBe('user-visible');});it('teardown unregisters the op with the host and stops re-execution', async () => {diff --git a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.tsindex c7b225654b..d273f7dc1e 100644--- a/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts+++ b/apps/web/src/lib/graphql-cache/exchange/normalized-cache-exchange.ts@@ -71,6 +71,8 @@ import {* carries its own transaction.*/const QUEUE_ATTEMPT_CONTEXT_KEY = 'normalizedCacheQueueAttempt';+/** Marks dependency-pushed reads as latency-sensitive worker work. */+const AFFECTED_READ_CONTEXT_KEY = 'normalizedCacheAffectedRead';const QUEUE_REQUEST_TIMEOUT_MS = 60_000;const QUEUE_LEASE_MS = 5 * 60_000;const EMPTY_QUEUE_POLL_MS = 30_000;@@ -319,6 +321,7 @@ export function normalizedCacheExchange(makeOperation(op.kind, op, {...op.context,requestPolicy: 'cache-first',+ [AFFECTED_READ_CONTEXT_KEY]: true,}));}@@ -489,6 +492,10 @@ export function normalizedCacheExchange(query: queryText(op),operationName: operationName(op),variables: op.variables as Record<string, unknown> | undefined,+ priority:+ op.context[AFFECTED_READ_CONTEXT_KEY] === true+ ? 'user-visible'+ : undefined,});if (read.kind === 'hit') {const stale = policy === 'cache-and-network';diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.tsindex 14ef0da6f9..a6da384cee 100644--- a/apps/web/src/lib/graphql-cache/host/types.ts+++ b/apps/web/src/lib/graphql-cache/host/types.ts@@ -7,6 +7,7 @@import type {CachedQueryInstanceWire,+ CacheReadPriority,ClaimedMutation,MutationClaim,MutationSettlement,@@ -25,6 +26,8 @@ export interface CacheReadArgs {query: string;operationName?: string;variables?: Record<string, unknown>;+ /** Prioritizes a pushed, user-visible refresh over incidental reads. */+ priority?: CacheReadPriority;}export interface InspectQueryArgs {@@ -34,7 +37,7 @@ export interface InspectQueryArgs {path: Array<{ field: string }>;}-export interface CacheWriteArgs extends CacheReadArgs {+export interface CacheWriteArgs extends Omit<CacheReadArgs, 'priority'> {data: unknown;/** Opaque session tag; see protocol.ts `identity`. */identity?: string;diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.tsindex 23e20cb97d..0b5d85d13c 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts@@ -77,6 +77,52 @@ describe('createWorkerCacheHost', () => {host.dispose();});+ it('forwards user-visible read priority to the worker', async () => {+ const requests: Array<{ id?: number; kind: string; priority?: string }> =+ [];+ class FakeSharedWorker {+ port = {+ onmessage: null as ((event: MessageEvent) => void) | null,+ start() {},+ close() {},+ postMessage: (request: {+ id?: number;+ kind: string;+ priority?: string;+ }) => {+ requests.push(request);+ if (request.id === undefined) return;+ queueMicrotask(() => {+ this.port.onmessage?.({+ data: {+ id: request.id,+ ok: true,+ result:+ request.kind === 'read'+ ? { kind: 'hit', data: { soup: true } }+ : null,+ },+ } as MessageEvent);+ });+ },+ };+ }+ vi.stubGlobal('SharedWorker', FakeSharedWorker);+ const host = createWorkerCacheHost({ scope: 'scope-1' });++ await expect(+ host.readQuery({+ opKey: 7,+ query: 'query GroupSoup { groupSoup }',+ priority: 'user-visible',+ })+ ).resolves.toEqual({ kind: 'hit', data: { soup: true } });+ expect(requests).toContainEqual(+ expect.objectContaining({ kind: 'read', priority: 'user-visible' })+ );+ host.dispose();+ });+it('delivers queued mutation settlements pushed by the worker', async () => {let push: (message: unknown) => void = () => {throw new Error('worker not initialized');diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 17b1889136..6d9d761ec9 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -181,6 +181,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {query: args.query,operationName: args.operationName,variables: args.variables,+ priority: args.priority,})) as ReadResult;},diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.tsindex 27bbd83668..41826e73dc 100644--- a/apps/web/src/lib/graphql-cache/index.ts+++ b/apps/web/src/lib/graphql-cache/index.ts@@ -41,6 +41,7 @@ export { createWorkerCacheHost } from './host/worker-host';export type {CachedQueryInstanceWire,CachePush,+ CacheReadPriority,CacheRequest,CacheResponse,MutationSettlement,diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex 6aabe2135c..aa614654c5 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -11,6 +11,9 @@export type ReadResult = { kind: 'hit'; data: unknown } | { kind: 'miss' };+/** Scheduling hint for latency-sensitive cache reads. */+export type CacheReadPriority = 'user-visible';+/** Opaque exclusive cursor for deterministic normalized-record scans. */export type RecordCursor = string;@@ -140,6 +143,8 @@ export type CacheRequest = { id: number } & (query: string;operationName?: string;variables?: Record<string, unknown>;+ /** May overtake unrelated observational reads, never ordering barriers. */+ priority?: CacheReadPriority;}| {kind: 'write';diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.tsindex 09cbfda42e..569547d23e 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts@@ -7,7 +7,7 @@ vi.mock('./wasm-module', () => ({ loadCacheWasm: loadCacheWasmMock }));import type { SelectedRecordPageWire } from '../protocol';import { CacheWorkerCore } from './worker-core';-describe('CacheWorkerCore record selection', () => {+describe('CacheWorkerCore', () => {beforeEach(() => {vi.clearAllMocks();});@@ -48,6 +48,232 @@ describe('CacheWorkerCore record selection', () => {expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: page });});+ it('coalesces queued affected rereads and runs them ahead of incidental reads', async () => {+ const order: string[] = [];+ let releaseBlocker!: () => void;+ let markBlockerStarted!: () => void;+ const blocker = new Promise<void>((resolve) => {+ releaseBlocker = resolve;+ });+ const blockerStarted = new Promise<void>((resolve) => {+ markBlockerStarted = resolve;+ });+ const readQuery = vi.fn(async (opId: string | undefined) => {+ order.push(`read:${opId}`);+ if (opId === 'client:blocker') {+ markBlockerStarted();+ await blocker;+ }+ return { kind: 'hit' as const, data: { opId } };+ });+ const beginOptimisticWrite = vi.fn(+ async (_originOpId: string | undefined, query: string) => {+ order.push(`begin:${query}`);+ return {+ transactionId: query,+ changed: [],+ affectedOps: [],+ reset: false,+ };+ }+ );+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({+ readQuery,+ beginOptimisticWrite,+ }),+ });+ const messages: unknown[] = [];+ const port = { postMessage: (message: unknown) => messages.push(message) };+ const core = new CacheWorkerCore();+ await core.handleRequest(port, {+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ });++ const running = core.handleRequest(port, {+ id: 2,+ kind: 'read',+ opId: 'client:blocker',+ query: 'query Blocker { blocker }',+ });+ await blockerStarted;+ const ordinaryDuplicate = core.handleRequest(port, {+ id: 3,+ kind: 'read',+ opId: 'client:group-soup',+ query: 'query GroupSoup { groupSoup }',+ variables: { input: { limit: 20 } },+ });+ const incidental = core.handleRequest(port, {+ id: 4,+ kind: 'read',+ opId: 'client:child',+ query: 'query Child { child }',+ });+ const firstBegin = core.handleRequest(port, {+ id: 5,+ kind: 'begin-optimistic-write',+ query: 'mutation First { first }',+ data: { first: true },+ createdAtMs: 1,+ });+ const secondBegin = core.handleRequest(port, {+ id: 6,+ kind: 'begin-optimistic-write',+ query: 'mutation Second { second }',+ data: { second: true },+ createdAtMs: 2,+ });+ const affectedDuplicate = core.handleRequest(port, {+ id: 7,+ kind: 'read',+ opId: 'client:group-soup',+ query: 'query GroupSoup { groupSoup }',+ variables: { input: { limit: 20 } },+ priority: 'user-visible',+ });++ releaseBlocker();+ await Promise.all([+ running,+ ordinaryDuplicate,+ incidental,+ firstBegin,+ secondBegin,+ affectedDuplicate,+ ]);++ expect(order).toEqual([+ 'read:client:blocker',+ 'begin:mutation First { first }',+ 'begin:mutation Second { second }',+ 'read:client:group-soup',+ 'read:client:child',+ ]);+ // Two read RPCs for the same active operation require one wasm call, so+ // the full denormalization and its IndexedDB get_batch work run once.+ expect(+ readQuery.mock.calls.filter(([opId]) => opId === 'client:group-soup')+ ).toHaveLength(1);+ expect(messages).toContainEqual({+ id: 3,+ ok: true,+ result: {+ kind: 'hit',+ data: { opId: 'client:group-soup' },+ },+ });+ expect(messages).toContainEqual({+ id: 7,+ ok: true,+ result: {+ kind: 'hit',+ data: { opId: 'client:group-soup' },+ },+ });+ });++ it('does not reorder or coalesce reads across operation teardown', async () => {+ const order: string[] = [];+ let releaseBlocker!: () => void;+ let markBlockerStarted!: () => void;+ const blocker = new Promise<void>((resolve) => {+ releaseBlocker = resolve;+ });+ const blockerStarted = new Promise<void>((resolve) => {+ markBlockerStarted = resolve;+ });+ const readQuery = vi.fn(async (opId: string | undefined) => {+ order.push(`read:${opId}`);+ if (opId === 'client:blocker') {+ markBlockerStarted();+ await blocker;+ }+ return { kind: 'miss' as const };+ });+ const teardownOperation = vi.fn(async (opId: string) => {+ order.push(`teardown:${opId}`);+ });+ const beginOptimisticWrite = vi.fn(async () => {+ order.push('begin');+ return {+ transactionId: '1',+ changed: [],+ affectedOps: [],+ reset: false,+ };+ });+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({+ readQuery,+ teardownOperation,+ beginOptimisticWrite,+ }),+ });+ const port = { postMessage: vi.fn() };+ const core = new CacheWorkerCore();+ await core.handleRequest(port, {+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ });++ const running = core.handleRequest(port, {+ id: 2,+ kind: 'read',+ opId: 'client:blocker',+ query: 'query Blocker { blocker }',+ });+ await blockerStarted;+ const readBeforeTeardown = core.handleRequest(port, {+ id: 3,+ kind: 'read',+ opId: 'client:group-soup',+ query: 'query GroupSoup { groupSoup }',+ });+ const teardown = core.handleRequest(port, {+ id: 4,+ kind: 'teardown',+ opId: 'client:group-soup',+ });+ const begin = core.handleRequest(port, {+ id: 5,+ kind: 'begin-optimistic-write',+ query: 'mutation Update { update }',+ data: { update: true },+ createdAtMs: 1,+ });+ const readAfterTeardown = core.handleRequest(port, {+ id: 6,+ kind: 'read',+ opId: 'client:group-soup',+ query: 'query GroupSoup { groupSoup }',+ priority: 'user-visible',+ });++ releaseBlocker();+ await Promise.all([+ running,+ readBeforeTeardown,+ teardown,+ begin,+ readAfterTeardown,+ ]);++ expect(order).toEqual([+ 'read:client:blocker',+ 'read:client:group-soup',+ 'teardown:client:group-soup',+ 'begin',+ 'read:client:group-soup',+ ]);+ expect(+ readQuery.mock.calls.filter(([opId]) => opId === 'client:group-soup')+ ).toHaveLength(2);+ });+it('pushes cache changes even without affected operations', async () => {const writeResult = {changed: ['GraphqlSoupDocument:doc-1'],diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.tsindex 515c8b3b14..305ee9cd79 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts@@ -19,12 +19,68 @@ type PortLike = {postMessage(msg: unknown): void;};+type RequestWaiter = {+ resolve: (value: unknown) => void;+ reject: (error: unknown) => void;+};++type QueuedEngineRequest = {+ request: CacheRequest;+ priority: number;+ readSignature?: string;+ waiters: RequestWaiter[];+};++const NORMAL_READ_PRIORITY = 0;+const USER_VISIBLE_READ_PRIORITY = 1;+const CACHE_WRITE_PRIORITY = 2;++/** Reads may reorder while they overlap, but never across lifecycle barriers. */+function isOrderingBarrier(request: CacheRequest): boolean {+ return (+ request.kind === 'init' ||+ request.kind === 'teardown' ||+ request.kind === 'clear'+ );+}++function requestPriority(request: CacheRequest): number {+ if (request.kind === 'read') {+ return request.priority === 'user-visible'+ ? USER_VISIBLE_READ_PRIORITY+ : NORMAL_READ_PRIORITY;+ }+ if (+ request.kind === 'write' ||+ request.kind === 'begin-optimistic-write' ||+ request.kind === 'commit-optimistic-write' ||+ request.kind === 'rollback-optimistic-write' ||+ request.kind === 'invalidate' ||+ request.kind === 'delete-records'+ ) {+ return CACHE_WRITE_PRIORITY;+ }+ return NORMAL_READ_PRIORITY;+}++/** Exact active-operation reads can share one denormalization/storage pass. */+function readSignature(request: CacheRequest): string | undefined {+ if (request.kind !== 'read' || request.opId === undefined) return;+ return JSON.stringify([+ request.opId,+ request.query,+ request.operationName ?? null,+ request.variables ?? null,+ ]);+}+export class CacheWorkerCore {private engine: CacheEngine | undefined;private initPromise: Promise<void> | undefined;private scope: string | undefined;- /** Serializes engine calls (defense in depth; the engine also locks). */- private queue: Promise<unknown> = Promise.resolve();+ /** Serializes engine calls while allowing safe read prioritization. */+ private readonly queue: QueuedEngineRequest[] = [];+ private running = false;private readonly ports = new Set<PortLike>();addPort(port: PortLike): void {@@ -38,7 +94,7 @@ export class CacheWorkerCore {async handleRequest(port: PortLike, request: CacheRequest): Promise<void> {const respond = (response: CacheResponse) => port.postMessage(response);try {- const result = await this.enqueue(() => this.dispatch(request));+ const result = await this.enqueue(request);respond({ id: request.id, ok: true, result });} catch (error) {respond({@@ -49,10 +105,83 @@ export class CacheWorkerCore {}}- private enqueue<T>(task: () => Promise<T>): Promise<T> {- const next = this.queue.then(task, task);- this.queue = next.catch(() => undefined);- return next;+ private enqueue(request: CacheRequest): Promise<unknown> {+ return new Promise((resolve, reject) => {+ const priority = requestPriority(request);+ const signature = readSignature(request);++ // Coalesce only within the current lifecycle segment. In particular, a+ // remount after teardown must perform a fresh read to re-register deps.+ if (signature !== undefined) {+ let segmentStart = 0;+ for (let i = this.queue.length - 1; i >= 0; i -= 1) {+ const queued = this.queue[i];+ if (queued && isOrderingBarrier(queued.request)) {+ segmentStart = i + 1;+ break;+ }+ }+ const duplicate = this.queue+ .slice(segmentStart)+ .find((queued) => queued.readSignature === signature);+ if (duplicate) {+ duplicate.priority = Math.max(duplicate.priority, priority);+ duplicate.waiters.push({ resolve, reject });+ this.drain();+ return;+ }+ }++ this.queue.push({+ request,+ priority,+ readSignature: signature,+ waiters: [{ resolve, reject }],+ });+ this.drain();+ });+ }++ /**+ * Runs the highest-priority request before the next lifecycle barrier.+ * Cache-view writes retain FIFO order with each other; overlapping reads+ * may observe the newer state, which is linearizable and avoids stale work.+ */+ private drain(): void {+ if (this.running || this.queue.length === 0) return;++ let segmentEnd = this.queue.findIndex((queued) =>+ isOrderingBarrier(queued.request)+ );+ if (segmentEnd === -1) segmentEnd = this.queue.length;++ let index = 0;+ if (segmentEnd > 0) {+ for (let i = 1; i < segmentEnd; i += 1) {+ const candidate = this.queue[i];+ const selected = this.queue[index];+ if (candidate && selected && candidate.priority > selected.priority) {+ index = i;+ }+ }+ }++ const [queued] = this.queue.splice(index, 1);+ if (!queued) return;+ this.running = true;+ void this.dispatch(queued.request)+ .then(+ (result) => {+ for (const waiter of queued.waiters) waiter.resolve(result);+ },+ (error) => {+ for (const waiter of queued.waiters) waiter.reject(error);+ }+ )+ .finally(() => {+ this.running = false;+ this.drain();+ });}private async dispatch(request: CacheRequest): Promise<unknown> {