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
Seanaye/feat/cache revision (#5923)
Sean Ayeefb54a47af4e
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 4dea3b61c6..725106c262 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@@ -22,6 +22,7 @@ import {ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,type ClaimedMutation,type EnqueueOptimisticMutationResult,+ INITIAL_CACHE_REVISION,type MutationClaim,type ReadResult,type WriteResult,@@ -31,6 +32,7 @@ import {HYDRATE_ONLY_CONTEXT_KEY,type NormalizedCacheExchangeOptions,normalizedCacheExchange,+ normalizedCacheResultMetadata,} from './normalized-cache-exchange';import { optimisticMutationDispositionOf } from './optimistic';@@ -251,6 +253,9 @@ function makeFakeHost(): FakeHost {pushAffected: (opKeys) => {for (const cb of subscribers) cb(opKeys);},+ async currentRevision() {+ return INITIAL_CACHE_REVISION;+ },async readQuery(args) {host.reads.push({opKey: args.opKey,@@ -262,7 +267,7 @@ function makeFakeHost(): FakeHost {return readResult;},async readRecordsByKeys() {- return [];+ return { revision: INITIAL_CACHE_REVISION, records: [] };},async search() {return { documents: [], nextCursor: null };@@ -279,12 +284,21 @@ function makeFakeHost(): FakeHost {entityResolvers: args.entityResolvers,});host.cacheActions.push({ kind: 'write', value: args.data });- return { changed: [], affectedOps: [], reset: false };+ return {+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ };},async hydrateQuery(args) {host.writes.push({ data: args.data, identity: args.identity });host.cacheActions.push({ kind: 'write', value: args.data });- return { kind: 'data', data: args.data };+ return {+ kind: 'data',+ data: args.data,+ revision: INITIAL_CACHE_REVISION,+ };},async enqueueOptimisticMutation(args,@@ -300,6 +314,7 @@ function makeFakeHost(): FakeHost {const mutation = claimQueueHead(claim.nowMs);return {transactionId,+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -340,25 +355,37 @@ function makeFakeHost(): FakeHost {): Promise<WriteResult> {host.commits.push({ transactionId, query: args.query, data: args.data });if (queue[0]?.transactionId === transactionId) queue.shift();- return { changed: [], affectedOps: [], reset: false };+ return {+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ };},async rollbackOptimisticWrite(transactionId, _claim): Promise<WriteResult> {host.rollbacks.push(transactionId);if (queue[0]?.transactionId === transactionId) queue.shift();- return { changed: [], affectedOps: [], reset: false };+ return {+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ };},async invalidate() {- return [];+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };},async deleteRecords(keys) {host.invalidations.push(keys);host.cacheActions.push({ kind: 'delete', value: keys });- return [];+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };},async teardown(opKey) {host.teardowns.push(opKey);},- async clear() {},+ async clear() {+ return INITIAL_CACHE_REVISION;+ },onOpsAffected(cb) {subscribers.add(cb);return () => subscribers.delete(cb);@@ -366,6 +393,9 @@ function makeFakeHost(): FakeHost {onCacheChanged() {return () => undefined;},+ onCacheGenerationChanged() {+ return () => undefined;+ },onMutationSettled() {return () => undefined;},@@ -677,11 +707,16 @@ describe('normalizedCacheExchange', () => {markWriteStarted();await writeCanFinish;cacheContainsDocument = true;- return { changed: [], affectedOps: [], reset: false };+ return {+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ };});vi.spyOn(host, 'deleteRecords').mockImplementation(async () => {cacheContainsDocument = false;- return [];+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };});const ops = makeSubject<Operation>();@@ -879,6 +914,10 @@ describe('normalizedCacheExchange', () => {[{ from: 'cache' }, true],[{ from: 'network' }, false],]);+ expect(results.map(normalizedCacheResultMetadata)).toEqual([+ { source: 'normalized-cache-hit' },+ { source: 'live-network', revision: INITIAL_CACHE_REVISION },+ ]);expect(forwarded.map((op) => op.key)).toEqual([1]);expect(host.writes).toHaveLength(1);expect(host.reads).toHaveLength(1);@@ -910,6 +949,7 @@ describe('normalizedCacheExchange', () => {return {kind: 'data' as const,data: { soup: { nextCursor: 'cursor-2' } },+ revision: INITIAL_CACHE_REVISION,};});const { ops, network, forwarded, results } = controlledQueryHarness(host);@@ -935,6 +975,10 @@ describe('normalizedCacheExchange', () => {expect(results[0]?.data).toEqual({soup: { nextCursor: 'cursor-2' },});+ expect(normalizedCacheResultMetadata(results[0]!)).toEqual({+ source: 'live-network',+ revision: INITIAL_CACHE_REVISION,+ });});it('cache-only miss emits empty data and never touches the network', async () => {@@ -1106,6 +1150,9 @@ describe('normalizedCacheExchange', () => {[{ status: 'In Review' }, true],[{ status: 'Completed' }, true],]);+ expect(normalizedCacheResultMetadata(results.at(-1)!)).toEqual({+ source: 'affected-cache-reread',+ });});it('registers a slow fallback write without a replacement reread', async () => {@@ -1170,7 +1217,12 @@ describe('normalizedCacheExchange', () => {.mockRejectedValueOnce(new Error('replacement init not ready')).mockImplementationOnce(async (args) => {cached = args.data;- return { changed: [], affectedOps: [], reset: false };+ return {+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ };});const { ops, network, forwarded, results, client } = controlledQueryHarness(host,@@ -1235,7 +1287,12 @@ describe('normalizedCacheExchange', () => {.fn().mockImplementationOnce(async () => await initialWrite).mockRejectedValueOnce(new Error('replacement failed while writing'))- .mockResolvedValueOnce({ changed: [], affectedOps: [], reset: false });+ .mockResolvedValueOnce({+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ });const { ops, network, forwarded, client } = controlledQueryHarness(host);ops.next(makeOp(43));await tick();@@ -1290,7 +1347,12 @@ describe('normalizedCacheExchange', () => {if (writeCount === 1) throw new Error('initial A write failed');if (writeCount === 2) throw new Error('replacement A write failed');cached = args.data;- return { changed: [], affectedOps: [], reset: false };+ return {+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ };});const { ops, network, forwarded, client } = controlledQueryHarness(host,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 88d085d228..a488070413 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@@ -62,9 +62,11 @@ import {} from 'wonka';import type { CacheHost } from '../host/types';import {+ type CacheRevision,type ClaimedMutation,type EnqueueOptimisticMutationResult,isAdmittedEnqueueUncertainError,+ isCacheRevision,isOwnerEpochLostError,type QueryRevalidationWire,} from '../protocol';@@ -98,6 +100,42 @@ const QUEUE_REQUEST_TIMEOUT_MS = 60_000;const QUEUE_LEASE_MS = 5 * 60_000;const EMPTY_QUEUE_POLL_MS = 30_000;+const NORMALIZED_CACHE_RESULT_METADATA_KEY = '__macroNormalizedCache';++/** Private authority metadata attached by the normalized-cache exchange. */+export type NormalizedCacheResultMetadata =+ | { source: 'live-network'; revision?: CacheRevision }+ | { source: 'normalized-cache-hit' }+ | { source: 'affected-cache-reread' };++/** Reads normalized-cache authority metadata from an urql operation result. */+export function normalizedCacheResultMetadata(+ result: Pick<OperationResult, 'extensions'>+): NormalizedCacheResultMetadata | undefined {+ const metadata = result.extensions?.[NORMALIZED_CACHE_RESULT_METADATA_KEY];+ if (metadata === null || typeof metadata !== 'object') return;+ const source = (metadata as { source?: unknown }).source;+ if (source === 'normalized-cache-hit' || source === 'affected-cache-reread') {+ return { source };+ }+ if (source !== 'live-network') return;+ const revision = (metadata as { revision?: unknown }).revision;+ return isCacheRevision(revision) ? { source, revision } : { source };+}++function withResultMetadata(+ result: OperationResult,+ metadata: NormalizedCacheResultMetadata+): OperationResult {+ return {+ ...result,+ extensions: {+ ...result.extensions,+ [NORMALIZED_CACHE_RESULT_METADATA_KEY]: metadata,+ },+ };+}+type QueueAttemptContext = {transactionId: string;leaseOwner: string;@@ -227,16 +265,23 @@ function withQueueRequestTimeout(op: Operation): Operation {function cacheResult(op: Operation,data: unknown,- stale: boolean+ stale: boolean,+ source: Extract<+ NormalizedCacheResultMetadata,+ { source: 'normalized-cache-hit' | 'affected-cache-reread' }+ >['source'] = 'normalized-cache-hit'): OperationResult {- return {- operation: op,- data,- error: undefined,- extensions: undefined,- stale,- hasNext: false,- };+ return withResultMetadata(+ {+ operation: op,+ data,+ error: undefined,+ extensions: undefined,+ stale,+ hasNext: false,+ },+ { source }+ );}type CacheEffect =@@ -575,7 +620,9 @@ export function normalizedCacheExchange(// Preserve the authoritative request while immediately surfacing the// newer local view. Its eventual result still gets the deferred// cache reread below when it could not register fresh dependencies.- emitAffectedResult(cacheResult(active, read.data, true));+ emitAffectedResult(+ cacheResult(active, read.data, true, 'affected-cache-reread')+ );}).catch((error) => options.onCacheError?.(error, operation));};@@ -993,6 +1040,10 @@ export function normalizedCacheExchange(result: OperationResult): Promise<OperationResult> {const op = result.operation;+ let output =+ op.kind === 'query'+ ? withResultMetadata(result, { source: 'live-network' })+ : result;if (op.kind === 'subscription' && result.data != null) {// Serialize effects across every emission for this operation, as// well as within buffered payloads, so a slower earlier write cannot@@ -1022,10 +1073,13 @@ export function normalizedCacheExchange(identity: options.extractIdentity?.(result.data),entityResolvers,});- return {- ...result,- data: hydration.kind === 'data' ? hydration.data : undefined,- };+ return withResultMetadata(+ {+ ...result,+ data: hydration.kind === 'data' ? hydration.data : undefined,+ },+ { source: 'live-network', revision: hydration.revision }+ );} catch (error) {options.onCacheError?.(error, op);return {@@ -1079,7 +1133,11 @@ export function normalizedCacheExchange(state.retainedReplacementFallback = retained;}try {- await host.writeQuery(writeArgs);+ const write = await host.writeQuery(writeArgs);+ output = withResultMetadata(result, {+ source: 'live-network',+ revision: write.revision,+ });state.networkRegistrationSatisfied =writeArgs.registerDependencies;if (state.retainedReplacementFallback === retained) {@@ -1195,7 +1253,7 @@ export function normalizedCacheExchange(});}}- return result;+ return output;}const cacheResults$ = pipe(diff --git a/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts b/apps/web/src/lib/graphql-cache/exchange/record-selection.test.tsindex 0b2cd3a969..75bb22c1d8 100644--- a/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts+++ b/apps/web/src/lib/graphql-cache/exchange/record-selection.test.ts@@ -5,16 +5,20 @@ import {} from '@service-storage/graphql/generated/graphql';import { describe, expect, expectTypeOf, it, vi } from 'vitest';import type { CacheHost } from '../host/types';+import { INITIAL_CACHE_REVISION } from '../protocol';import { readRecordsByKeys, selectRecords } from './record-selection';describe('typed record selection', () => {it('projects explicit keys and infers generated result types', async () => {- const readRecordsByKeysHost = vi.fn().mockResolvedValue([- {- recordKey: 'GraphqlSoupDocument:item-1',- record: { id: 'item-1' },- },- ]);+ const readRecordsByKeysHost = vi.fn().mockResolvedValue({+ revision: INITIAL_CACHE_REVISION,+ records: [+ {+ recordKey: 'GraphqlSoupDocument:item-1',+ record: { id: 'item-1' },+ },+ ],+ });const host = {readRecordsByKeys: readRecordsByKeysHost,} as unknown as CacheHost;@@ -28,11 +32,11 @@ describe('typed record selection', () => {fragmentName: 'SoupItemFields',keys: ['GraphqlSoupDocument:item-1'],});- expectTypeOf(records).toEqualTypeOf<+ expectTypeOf(records.records).toEqualTypeOf<Array<{ recordKey: string; record: SoupItemFieldsFragment }>>();// @ts-expect-error Generated fragment records have no arbitrary field.- records[0]?.record.missing;+ records.records[0]?.record.missing;});it('rejects operation documents and malformed host records', async () => {@@ -46,7 +50,10 @@ describe('typed record selection', () => {[{ recordKey: 'GraphqlSoupDocument:1', record: null }],]) {const host = {- readRecordsByKeys: async () => result,+ readRecordsByKeys: async () => ({+ revision: INITIAL_CACHE_REVISION,+ records: result,+ }),} as unknown as CacheHost;await expect(readRecordsByKeys(host, selection, ['GraphqlSoupDocument:1'])diff --git a/apps/web/src/lib/graphql-cache/exchange/record-selection.ts b/apps/web/src/lib/graphql-cache/exchange/record-selection.tsindex 57c9b5f6fd..4749f1085b 100644--- a/apps/web/src/lib/graphql-cache/exchange/record-selection.ts+++ b/apps/web/src/lib/graphql-cache/exchange/record-selection.ts@@ -2,7 +2,7 @@ import type { TypedDocumentNode } from '@graphql-typed-document-node/core';import { stringifyDocument } from '@urql/core';import { type FragmentDefinitionNode, Kind } from 'graphql';import type { CacheHost } from '../host/types';-import type { SelectedRecordByKeyWire } from '../protocol';+import type { CacheRevision } from '../protocol';const recordResultType: unique symbol = Symbol('recordResultType');@@ -50,16 +50,22 @@ export async function readRecordsByKeys<TResult>(host: Pick<CacheHost, 'readRecordsByKeys'>,selection: RecordSelection<TResult>,keys: string[]-): Promise<Array<{ recordKey: string; record: TResult }>> {- const records: SelectedRecordByKeyWire[] = await host.readRecordsByKeys({+): Promise<{+ revision: CacheRevision;+ records: Array<{ recordKey: string; record: TResult }>;+}> {+ const result = await host.readRecordsByKeys({document: selection.document,fragmentName: selection.fragmentName,keys,});- return records.map(({ recordKey, record }) => {- if (!recordKey || !isRecord(record)) {- throw new Error('invalid cache selected record by key');- }- return { recordKey, record: record as TResult };- });+ return {+ revision: result.revision,+ records: result.records.map(({ recordKey, record }) => {+ if (!recordKey || !isRecord(record)) {+ throw new Error('invalid cache selected record by key');+ }+ return { recordKey, record: record as TResult };+ }),+ };}diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.tsindex c1599ebe4a..cbaa58d312 100644--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts@@ -3,9 +3,11 @@ import type {ReadResult,WriteResult,} from '../protocol';+import { INITIAL_CACHE_REVISION } from '../protocol';import type { CacheHost } from './types';const emptyWriteResult = (): WriteResult => ({+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -22,11 +24,14 @@ export function createNoopCacheHost(reason: string): CacheHost {return {clientId: 'noop',disabled: true,+ async currentRevision() {+ return INITIAL_CACHE_REVISION;+ },async readQuery(): Promise<ReadResult> {return { kind: 'miss' };},async readRecordsByKeys() {- return [];+ return { revision: INITIAL_CACHE_REVISION, records: [] };},async search() {return { documents: [], nextCursor: null };@@ -59,20 +64,25 @@ export function createNoopCacheHost(reason: string): CacheHost {async rollbackOptimisticWrite(): Promise<WriteResult> {return emptyWriteResult();},- async invalidate(): Promise<string[]> {- return [];+ async invalidate() {+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };},- async deleteRecords(): Promise<string[]> {- return [];+ async deleteRecords() {+ return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };},async teardown(): Promise<void> {},- async clear(): Promise<void> {},+ async clear() {+ return INITIAL_CACHE_REVISION;+ },onOpsAffected() {return () => undefined;},onCacheChanged() {return () => undefined;},+ onCacheGenerationChanged() {+ return () => undefined;+ },onMutationSettled() {return () => undefined;},diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.test.tsindex 392dd346e1..91047c5821 100644--- a/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.test.ts@@ -6,6 +6,7 @@ const listenMock = vi.hoisted(() => vi.fn());vi.mock('@tauri-apps/api/core', () => ({ invoke: invokeMock }));vi.mock('@tauri-apps/api/event', () => ({ listen: listenMock }));+import { INITIAL_CACHE_REVISION } from '../protocol';import { createTauriCacheHost } from './tauri-host';type EventCallback = (event: { payload: Record<string, unknown> }) => void;@@ -91,7 +92,9 @@ describe('createTauriCacheHost', () => {];invokeMock.mockImplementation((command: string) =>Promise.resolve(- command === 'graphql_cache_read_records_by_keys' ? records : null+ command === 'graphql_cache_read_records_by_keys'+ ? { revision: INITIAL_CACHE_REVISION, records }+ : null));const host = createTauriCacheHost({ scope: 'scope-1' });@@ -102,7 +105,7 @@ describe('createTauriCacheHost', () => {fragmentName: 'Item',keys: ['GraphqlSoupDocument:item-1'],})- ).resolves.toEqual(records);+ ).resolves.toEqual({ revision: INITIAL_CACHE_REVISION, records });expect(invokeMock).toHaveBeenCalledWith('graphql_cache_read_records_by_keys',{@@ -366,7 +369,9 @@ describe('createTauriCacheHost', () => {host.onCacheChanged(() => calls++);await Promise.resolve();- eventCallbacks.get('graphql-cache://cache-changed')?.({ payload: {} });+ eventCallbacks.get('graphql-cache://cache-changed')?.({+ payload: { revision: INITIAL_CACHE_REVISION },+ });expect(calls).toBe(1);});diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.tsindex ced191945c..877b5e5e28 100644--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts@@ -9,22 +9,27 @@import { invoke } from '@tauri-apps/api/core';import { listen, type UnlistenFn } from '@tauri-apps/api/event';+import type {+ AffectedOperationsResult,+ CachedQueryInstanceWire,+ CachedQueryVariantWire,+ CacheRevision,+ ClaimedMutation,+ EnqueueOptimisticMutationResult,+ HydrationResult,+ MutationClaim,+ MutationSettlement,+ ReadRecordsByKeysArgs,+ ReadRecordsByKeysResult,+ ReadResult,+ SearchCacheArgs,+ SearchCachePage,+ WriteResult,+} from '../protocol';import {- type CachedQueryInstanceWire,- type CachedQueryVariantWire,- type ClaimedMutation,- type EnqueueOptimisticMutationResult,- type HydrationResult,- type MutationClaim,- type MutationSettlement,- type ReadRecordsByKeysArgs,- type ReadResult,- type SearchCacheArgs,- type SearchCachePage,- type SelectedRecordByKeyWire,+ parseCacheRevision,validateCacheSearchArgs,validateRecordSelectionKeys,- type WriteResult,} from '../protocol';import type {CacheHost,@@ -49,7 +54,7 @@ type OpsAffectedPayload = {keys: string[];};-type CacheChangedPayload = Record<string, never>;+type CacheChangedPayload = { revision: string };export interface TauriHostOptions {scope: string;@@ -69,7 +74,7 @@ const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;export function createTauriCacheHost(options: TauriHostOptions): CacheHost {const clientId = crypto.randomUUID();const affectedSubscribers = new Set<(opKeys: number[]) => void>();- const cacheChangeSubscribers = new Set<() => void>();+ const cacheChangeSubscribers = new Set<(revision: CacheRevision) => void>();const settlementSubscribers = new Set<(settlement: MutationSettlement) => void>();@@ -127,8 +132,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {});const unlistenCacheChanges: Promise<UnlistenFn | undefined> =- listen<CacheChangedPayload>(CACHE_CHANGED_EVENT, () => {- for (const cb of cacheChangeSubscribers) cb();+ listen<CacheChangedPayload>(CACHE_CHANGED_EVENT, (event) => {+ const revision = parseCacheRevision(event.payload.revision);+ for (const cb of cacheChangeSubscribers) cb(revision);}).catch((error) => {console.warn('graphql cache change listener failed', error);return undefined;@@ -153,6 +159,13 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {return {clientId,+ async currentRevision(): Promise<CacheRevision> {+ await ready;+ return parseCacheRevision(+ await request<string>('graphql_cache_current_revision', {})+ );+ },+async readQuery(args: CacheReadArgs): Promise<ReadResult> {await ready;return await request<ReadResult>('graphql_cache_read', {@@ -166,10 +179,10 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {async readRecordsByKeys(args: ReadRecordsByKeysArgs- ): Promise<SelectedRecordByKeyWire[]> {+ ): Promise<ReadRecordsByKeysResult> {const keys = validateRecordSelectionKeys(args.keys);await ready;- return await request<SelectedRecordByKeyWire[]>(+ const result = await request<ReadRecordsByKeysResult>('graphql_cache_read_records_by_keys',{document: args.document,@@ -177,6 +190,7 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {keys,});+ return { ...result, revision: parseCacheRevision(result.revision) };},async search(args: SearchCacheArgs): Promise<SearchCachePage> {@@ -342,14 +356,22 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {);},- async invalidate(keys: string[]): Promise<string[]> {+ async invalidate(keys: string[]): Promise<AffectedOperationsResult> {await ready;- return await request<string[]>('graphql_cache_invalidate', { keys });+ const result = await request<AffectedOperationsResult>(+ 'graphql_cache_invalidate',+ { keys }+ );+ return { ...result, revision: parseCacheRevision(result.revision) };},- async deleteRecords(keys: string[]): Promise<string[]> {+ async deleteRecords(keys: string[]): Promise<AffectedOperationsResult> {await ready;- return await request<string[]>('graphql_cache_delete_records', { keys });+ const result = await request<AffectedOperationsResult>(+ 'graphql_cache_delete_records',+ { keys }+ );+ return { ...result, revision: parseCacheRevision(result.revision) };},async teardown(opKey: number): Promise<void> {@@ -357,9 +379,11 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {await request('graphql_cache_teardown', { opId: opId(opKey) });},- async clear(): Promise<void> {+ async clear(): Promise<CacheRevision> {await ready;- await request('graphql_cache_clear', {});+ return parseCacheRevision(+ await request<string>('graphql_cache_clear', {})+ );},onOpsAffected(cb: (opKeys: number[]) => void): () => void {@@ -367,11 +391,16 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {return () => affectedSubscribers.delete(cb);},- onCacheChanged(cb: () => void): () => void {+ onCacheChanged(cb: (revision: CacheRevision) => void): () => void {cacheChangeSubscribers.add(cb);return () => cacheChangeSubscribers.delete(cb);},+ onCacheGenerationChanged(): () => void {+ // The native host process owns one engine generation for its lifetime.+ return () => undefined;+ },+onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void {diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.tsindex 34edb45e31..2ab919cd11 100644--- a/apps/web/src/lib/graphql-cache/host/types.ts+++ b/apps/web/src/lib/graphql-cache/host/types.ts@@ -8,9 +8,11 @@import type { EntityResolverWire } from '../exchange/entity-resolvers';import type {+ AffectedOperationsResult,CachedQueryInstanceWire,CachedQueryVariantWire,CacheReadPriority,+ CacheRevision,ClaimedMutation,EnqueueOptimisticMutationResult,EntityFilterCacheArgs,@@ -22,10 +24,10 @@ import type {QueryRevalidationWire,QueryVariableFilter,ReadRecordsByKeysArgs,+ ReadRecordsByKeysResult,ReadResult,SearchCacheArgs,SearchCachePage,- SelectedRecordByKeyWire,WriteResult,} from '../protocol';@@ -83,11 +85,13 @@ export interface CacheHost {/** True for the storage-free fallback when browser cache APIs are unsupported. */readonly disabled?: boolean;+ /** Returns the current revision of the active cache-engine generation. */+ currentRevision(): Promise<CacheRevision>;readQuery(args: CacheReadArgs): Promise<ReadResult>;/** Projects a bounded explicit set of normalized entity keys. */readRecordsByKeys(args: ReadRecordsByKeysArgs- ): Promise<SelectedRecordByKeyWire[]>;+ ): Promise<ReadRecordsByKeysResult>;/** Searches the compact write-through materialized projection. */search(args: SearchCacheArgs): Promise<SearchCachePage>;/** Evaluates an exact initial Soup filter page over complete local projections. */@@ -132,13 +136,13 @@ export interface CacheHost {error: string): Promise<WriteResult>;/** Evict records by entity key (external/push updates); returns affected local op ids. */- invalidate(keys: string[]): Promise<string[]>;+ invalidate(keys: string[]): Promise<AffectedOperationsResult>;/** Apply explicit server-provided cache-deletion effects. */- deleteRecords(keys: string[]): Promise<string[]>;+ deleteRecords(keys: string[]): Promise<AffectedOperationsResult>;/** urql teardown for an operation key. */teardown(opKey: number): Promise<void>;/** Wipe all cached state (logout). */- clear(): Promise<void>;+ clear(): Promise<CacheRevision>;/*** Subscribes to "these urql operation keys must re-execute" pushes@@ -148,7 +152,10 @@ export interface CacheHost {onOpsAffected(cb: (opKeys: number[]) => void): () => void;/** Subscribes whenever the effective normalized-cache view changes. */- onCacheChanged(cb: () => void): () => void;+ onCacheChanged(cb: (revision: CacheRevision) => void): () => void;++ /** Invalidates revision watermarks before a replacement engine is used. */+ onCacheGenerationChanged(cb: () => void): () => void;/** Subscribes to final commit/rollback events for queued mutations. */onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void;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 1653af502e..2a90cb5c0a 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@@ -5,6 +5,7 @@ import type {WorkerMessage,WriteResult,} from '../protocol';+import { INITIAL_CACHE_REVISION } from '../protocol';import type {CacheCoordinatorPageAdapter,CacheCoordinatorPageAdapterOptions,@@ -21,6 +22,7 @@ import { createWorkerCacheHost } from './worker-host';const CLIENT_ID = '00000000-0000-4000-8000-000000000007';const EMPTY_WRITE: WriteResult = {+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -28,14 +30,20 @@ const EMPTY_WRITE: WriteResult = {function responseFor(request: CacheRequest): unknown {switch (request.kind) {+ case 'current-revision':+ return INITIAL_CACHE_REVISION;case 'read':return { kind: 'miss' };case 'read-records-by-keys':- return [];+ return { revision: INITIAL_CACHE_REVISION, records: [] };case 'search':return { documents: [], nextCursor: null };case 'hydrate':- return { kind: 'data', data: { cursor: 'next' } };+ return {+ kind: 'data',+ data: { cursor: 'next' },+ revision: INITIAL_CACHE_REVISION,+ };case 'write':case 'commit-optimistic-write':case 'rollback-optimistic-write':@@ -53,12 +61,13 @@ function responseFor(request: CacheRequest): unknown {return undefined;case 'invalidate':case 'delete-records':- return request.keys;+ return { revision: INITIAL_CACHE_REVISION, affectedOps: request.keys };case 'init':case 'defer-optimistic-write':case 'teardown':- case 'clear':return null;+ case 'clear':+ return INITIAL_CACHE_REVISION;}}@@ -208,7 +217,11 @@ describe('createWorkerCacheHost', () => {data: { items: [{ id: '1' }], cursor: 'next' },identity: 'user-1',})- ).resolves.toEqual({ kind: 'data', data: { cursor: 'next' } });+ ).resolves.toEqual({+ kind: 'data',+ data: { cursor: 'next' },+ revision: INITIAL_CACHE_REVISION,+ });expect(requireAdapter().requests).toContainEqual(expect.objectContaining({@@ -530,6 +543,29 @@ describe('createWorkerCacheHost', () => {expect(vi.getTimerCount()).toBe(0);});+ it('times out a hung current-revision request', async () => {+ vi.useFakeTimers();+ configureAdapter = (fake) => fake.ignoredKinds.add('current-revision');+ const host = createWorkerCacheHost({+ scope: 'scope-1',+ requestTimeoutMs: 10,+ });++ const revision = host.currentRevision();+ const revisionRejected = expect(revision).rejects.toThrow(+ 'cache worker timeout: current-revision'+ );++ await vi.advanceTimersByTimeAsync(11);+ await revisionRejected;+ expect(requireAdapter().requests.map(({ kind }) => kind)).toEqual([+ 'init',+ 'current-revision',+ ]);+ host.dispose();+ expect(vi.getTimerCount()).toBe(0);+ });+it('recovers typed initial epoch loss with fresh init handshakes only', async () => {configureAdapter = (fake) => fake.ignoredKinds.add('init');const onInitializationError = vi.fn();@@ -852,7 +888,10 @@ describe('createWorkerCacheHost', () => {keys: ['User:1'],});adapter.push({ kind: 'ops-affected', opIds: [7], keys: [] });- adapter.push({ kind: 'cache-changed' });+ adapter.push({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ });adapter.push({kind: 'mutation-settled',settlement: { transactionId: '3', status: 'committed' },diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 1e8c32ebe4..9f10c32cb2 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -7,10 +7,12 @@import { deleteLegacyNormalizedCacheIdb } from '../legacy-idb-cleanup';import {ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,+ type AffectedOperationsResult,type CachedQueryInstanceWire,type CachedQueryVariantWire,type CacheRequest,type CacheResponseErrorCode,+ type CacheRevision,type ClaimedMutation,type EnqueueOptimisticMutationResult,type EntityFilterCacheArgs,@@ -22,10 +24,10 @@ import {type MutationSettlement,OWNER_EPOCH_LOST_ERROR_CODE,type ReadRecordsByKeysArgs,+ type ReadRecordsByKeysResult,type ReadResult,type SearchCacheArgs,type SearchCachePage,- type SelectedRecordByKeyWire,validateCacheSearchArgs,validateRecordSelectionKeys,type WorkerMessage,@@ -189,7 +191,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {const lostRegisteredOpKeys = new Set<number>();const replacementReadOpKeys = new Set<number>();const affectedSubscribers = new Set<(opKeys: number[]) => void>();- const cacheChangeSubscribers = new Set<() => void>();+ const cacheChangeSubscribers = new Set<(revision: CacheRevision) => void>();+ const generationChangeSubscribers = new Set<() => void>();const settlementSubscribers = new Set<(settlement: MutationSettlement) => void>();@@ -247,7 +250,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {const msg = event.data;if (isCachePush(msg)) {if (msg.kind === 'cache-changed') {- for (const cb of cacheChangeSubscribers) cb();+ for (const cb of cacheChangeSubscribers) cb(msg.revision);return;}if (msg.kind === 'mutation-settled') {@@ -331,6 +334,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {latestReplacementEpoch = ownerEpoch;// Initial readiness completes the already-running first handshake.if (state === 'initializing' && !recoveryInProgress) return;+ for (const cb of generationChangeSubscribers) cb();if (state === 'ready') {beginRecoveryGeneration();// No old response put this host into recovery. Requests still pending at@@ -457,6 +461,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {function clearSubscribers(): void {affectedSubscribers.clear();cacheChangeSubscribers.clear();+ generationChangeSubscribers.clear();settlementSubscribers.clear();}@@ -651,7 +656,8 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {const timeoutMs =msg.kind === 'init'? initializationTimeoutMs- : msg.kind === 'read' ||+ : msg.kind === 'current-revision' ||+ msg.kind === 'read' ||msg.kind === 'read-records-by-keys' ||msg.kind === 'search' ||msg.kind === 'entity-filter' ||@@ -804,6 +810,11 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return {clientId,+ async currentRevision(): Promise<CacheRevision> {+ await ensureInitialized();+ return (await request({ kind: 'current-revision' })) as CacheRevision;+ },+async readQuery(args: CacheReadArgs): Promise<ReadResult> {if (args.opKey !== undefined) {activeOpKeys.add(args.opKey);@@ -826,7 +837,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {async readRecordsByKeys(args: ReadRecordsByKeysArgs- ): Promise<SelectedRecordByKeyWire[]> {+ ): Promise<ReadRecordsByKeysResult> {const keys = validateRecordSelectionKeys(args.keys);await ensureInitialized();return (await request({@@ -834,7 +845,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {document: args.document,fragmentName: args.fragmentName,keys,- })) as SelectedRecordByKeyWire[];+ })) as ReadRecordsByKeysResult;},async search(args: SearchCacheArgs): Promise<SearchCachePage> {@@ -1007,14 +1018,20 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {})) as WriteResult;},- async invalidate(keys: string[]): Promise<string[]> {+ async invalidate(keys: string[]): Promise<AffectedOperationsResult> {await ensureInitialized();- return (await request({ kind: 'invalidate', keys })) as string[];+ return (await request({+ kind: 'invalidate',+ keys,+ })) as AffectedOperationsResult;},- async deleteRecords(keys: string[]): Promise<string[]> {+ async deleteRecords(keys: string[]): Promise<AffectedOperationsResult> {await ensureInitialized();- return (await request({ kind: 'delete-records', keys })) as string[];+ return (await request({+ kind: 'delete-records',+ keys,+ })) as AffectedOperationsResult;},async teardown(opKey: number): Promise<void> {@@ -1038,9 +1055,9 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {await request({ kind: 'teardown', opId: opId(opKey) });},- async clear(): Promise<void> {+ async clear(): Promise<CacheRevision> {await ensureInitialized();- await request({ kind: 'clear' });+ const revision = (await request({ kind: 'clear' })) as CacheRevision;telemetry?.record({name: 'graphql_cache.logical_reset',operationCategory: 'lifecycle',@@ -1048,6 +1065,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {errorCode: 'none',resetReason: 'explicit-clear',});+ return revision;},onOpsAffected(cb: (opKeys: number[]) => void): () => void {@@ -1055,11 +1073,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return () => affectedSubscribers.delete(cb);},- onCacheChanged(cb: () => void): () => void {+ onCacheChanged(cb: (revision: CacheRevision) => void): () => void {cacheChangeSubscribers.add(cb);return () => cacheChangeSubscribers.delete(cb);},+ onCacheGenerationChanged(cb: () => void): () => void {+ generationChangeSubscribers.add(cb);+ return () => generationChangeSubscribers.delete(cb);+ },+onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void {diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.tsindex 9b0a39ce2a..ad7ae6a30b 100644--- a/apps/web/src/lib/graphql-cache/index.ts+++ b/apps/web/src/lib/graphql-cache/index.ts@@ -18,6 +18,10 @@ export {inspectVariants,selectAll,} from './exchange/inspection';+export {+ type NormalizedCacheResultMetadata,+ normalizedCacheResultMetadata,+} from './exchange/normalized-cache-exchange';export {executeOptimisticMutation,type LinkDiff,@@ -56,6 +60,7 @@ export type {CacheReadPriority,CacheRequest,CacheResponse,+ CacheRevision,EnqueueOptimisticMutationResult,EntityFilterCacheArgs,EntityFilterCacheResult,@@ -64,6 +69,7 @@ export type {OptimisticWriteResult,QueryVariableFilter,ReadRecordsByKeysArgs,+ ReadRecordsByKeysResult,ReadResult,SearchCacheArgs,SearchCachePage,@@ -74,6 +80,7 @@ export type {WriteResult,} from './protocol';export {+ INITIAL_CACHE_REVISION,MAX_CACHE_SEARCH_QUERY_BYTES,MAX_RECORD_SELECTION_PAGE_SIZE,validateCacheSearchArgs,diff --git a/apps/web/src/lib/graphql-cache/lifecycle.test.ts b/apps/web/src/lib/graphql-cache/lifecycle.test.tsindex 0f2664e866..1ab7803968 100644--- a/apps/web/src/lib/graphql-cache/lifecycle.test.ts+++ b/apps/web/src/lib/graphql-cache/lifecycle.test.ts@@ -1,8 +1,8 @@import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import type { CacheHost } from './host/types';-function hostWithClear(clear: () => Promise<void>): CacheHost {- return { clear } as CacheHost;+function hostWithClear(clear: () => Promise<unknown>): CacheHost {+ return { clear } as unknown as CacheHost;}describe('clearRegisteredCaches', () => {diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.tsindex 6814e7095d..cbcf668c43 100644--- a/apps/web/src/lib/graphql-cache/protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts@@ -1,14 +1,30 @@import { describe, expect, it } from 'vitest';import type { SearchCacheArgs } from './protocol';import {+ INITIAL_CACHE_REVISION,isCachePush,isCacheResponse,isWorkerMessage,MAX_RECORD_SELECTION_PAGE_SIZE,+ parseCacheRevision,validateCacheSearchArgs,validateRecordSelectionKeys,} from './protocol';+describe('cache revisions', () => {+ it('accepts canonical Rust u64 decimal strings beyond JS safe integers', () => {+ expect(parseCacheRevision('9007199254740993')).toBe('9007199254740993');+ expect(parseCacheRevision('18446744073709551615')).toBe(+ '18446744073709551615'+ );+ });++ it.each(['', '-1', '+1', '01', '1.0', '18446744073709551616'])(+ 'rejects malformed revision %s',+ (revision) => expect(() => parseCacheRevision(revision)).toThrow()+ );+});+describe('validateRecordSelectionKeys', () => {it('accepts bounded canonical entity keys, including an empty set', () => {expect(validateRecordSelectionKeys([])).toEqual([]);@@ -128,7 +144,7 @@ describe('cache worker message validators', () => {errorCode: 'admitted-enqueue-uncertain',},{ kind: 'ops-affected', opIds: ['client:7'], keys: ['User:1'] },- { kind: 'cache-changed' },+ { kind: 'cache-changed', revision: INITIAL_CACHE_REVISION },{kind: 'mutation-settled',settlement: { transactionId: '3', status: 'committed' },diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex 90f985f889..3616898fe0 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -14,6 +14,32 @@ import type { EntityResolverWire } from './exchange/entity-resolvers';export type ReadResult = { kind: 'hit'; data: unknown } | { kind: 'miss' };+/** Opaque in-memory revision of one live cache engine generation. */+export type CacheRevision = string & {+ readonly __cacheRevision: unique symbol;+};++const MAX_CACHE_REVISION = 18_446_744_073_709_551_615n;++/** Validates the canonical unsigned-decimal Rust `u64` wire representation. */+export function isCacheRevision(value: unknown): value is CacheRevision {+ return (+ typeof value === 'string' &&+ /^(0|[1-9][0-9]*)$/.test(value) &&+ BigInt(value) <= MAX_CACHE_REVISION+ );+}++/** Parses an untrusted cache revision at protocol ingress. */+export function parseCacheRevision(value: unknown): CacheRevision {+ if (!isCacheRevision(value)) {+ throw new TypeError('invalid cache revision');+ }+ return value;+}++export const INITIAL_CACHE_REVISION = '0' as CacheRevision;+/** Scheduling hint for latency-sensitive cache reads. */export type CacheReadPriority = 'user-visible';@@ -60,9 +86,14 @@ export type EntityFilterCacheArgs = {};export type EntityFilterCacheResult =- | { kind: 'complete'; keys: string[]; optimistic: boolean }+ | {+ kind: 'complete';+ revision: CacheRevision;+ keys: string[];+ optimistic: boolean;+ }| { kind: 'unsupported' }- | { kind: 'incomplete' };+ | { kind: 'incomplete'; revision: CacheRevision };export type ReadRecordsByKeysArgs = {/** Serialized generated fragment document. */@@ -78,6 +109,20 @@ export type SelectedRecordByKeyWire = {record: unknown;};+export type ReadRecordsByKeysResult = {+ revision: CacheRevision;+ records: SelectedRecordByKeyWire[];+};++export type AffectedOperationsResult = {+ revision: CacheRevision;+ affectedOps: string[];+};++export type CacheRevisionResult = {+ revision: CacheRevision;+};+export const MAX_RECORD_SELECTION_PAGE_SIZE = 500;export const MAX_CACHE_SEARCH_QUERY_BYTES = 512;export const MAX_NORMALIZED_RECORD_KEY_LENGTH = 1024;@@ -254,10 +299,12 @@ export type CachedQueryInstanceWire = CachedQueryVariantWire & {};export type HydrationResult =- | { kind: 'data'; data: unknown }- | { kind: 'void' };+ | { kind: 'data'; data: unknown; revision: CacheRevision }+ | { kind: 'void'; revision: CacheRevision };export type WriteResult = {+ /** Effective-view revision installed by this logical mutation. */+ revision: CacheRevision;/** Entity keys whose records changed. */changed: string[];/** Registered operation ids affected by the change (origin excluded). */@@ -322,6 +369,7 @@ export type MutationSettlement =export type CacheRequest = { id: number } & (| { kind: 'init'; scope: string; hotCapacity?: number }+ | { kind: 'current-revision' }| {kind: 'read';opId?: string;@@ -479,7 +527,7 @@ export type CachePush =/** Changed entity keys, for diagnostics/advanced consumers. */keys: string[];}- | { kind: 'cache-changed' }+ | { kind: 'cache-changed'; revision: CacheRevision }| { kind: 'mutation-settled'; settlement: MutationSettlement };export type WorkerMessage = CacheResponse | CachePush;@@ -554,7 +602,10 @@ export function isCachePush(value: unknown): value is CachePush {isWireStringArray(value.keys));case 'cache-changed':- return hasOnlyWireKeys(value, ['kind']);+ return (+ hasOnlyWireKeys(value, ['kind', 'revision']) &&+ isCacheRevision(value.revision)+ );case 'mutation-settled': {const settlement = value.settlement;if (diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.test.tsindex 4420345ba6..de17d075ef 100644--- a/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.test.ts@@ -27,6 +27,7 @@ describe('cache OpenTelemetry sink', () => {errorCode: 'opfs-quota',openOutcome: 'reset-corrupt',queueDiagnosticsAvailability: 'available',+ revisionCategory: 'optimistic-commit',resetAttempt: 'wipe-before-open',queueDepth: 4,oldestAgeMs: 25,@@ -45,6 +46,7 @@ describe('cache OpenTelemetry sink', () => {'cache.error_code': 'opfs-quota','cache.open_outcome': 'reset-corrupt','cache.queue_diagnostics_availability': 'available',+ 'cache.revision_category': 'optimistic-commit','cache.reset_attempt': 'wipe-before-open','cache.duration_ms': 12,'cache.queue_depth': 4,diff --git a/apps/web/src/lib/graphql-cache/telemetry-otel.ts b/apps/web/src/lib/graphql-cache/telemetry-otel.tsindex 2c5ec32d01..996ccd440f 100644--- a/apps/web/src/lib/graphql-cache/telemetry-otel.ts+++ b/apps/web/src/lib/graphql-cache/telemetry-otel.ts@@ -46,6 +46,9 @@ export function createOtelCacheTelemetrySink(): CacheTelemetrySink {event.queueDiagnosticsAvailability);}+ if (event.revisionCategory !== undefined) {+ span.setAttr('cache.revision_category', event.revisionCategory);+ }if (event.resetAttempt !== undefined) {span.setAttr('cache.reset_attempt', event.resetAttempt);}diff --git a/apps/web/src/lib/graphql-cache/telemetry.test.ts b/apps/web/src/lib/graphql-cache/telemetry.test.tsindex aa061702ad..b978b7e637 100644--- a/apps/web/src/lib/graphql-cache/telemetry.test.ts+++ b/apps/web/src/lib/graphql-cache/telemetry.test.ts@@ -77,6 +77,7 @@ describe('cache telemetry privacy contract', () => {errorCode: 'none',openOutcome: 'reset-corrupt',queueDiagnosticsAvailability: 'available',+ revisionCategory: 'authoritative-write',resetAttempt: 'wipe-before-open',queueDepth: 3,oldestAgeMs: 42,@@ -90,6 +91,7 @@ describe('cache telemetry privacy contract', () => {name: 'graphql_cache.queue_diagnostics',openOutcome: 'reset-corrupt',queueDiagnosticsAvailability: 'available',+ revisionCategory: 'authoritative-write',resetAttempt: 'wipe-before-open',queueDepth: 3,oldestAgeMs: 42,diff --git a/apps/web/src/lib/graphql-cache/telemetry.ts b/apps/web/src/lib/graphql-cache/telemetry.tsindex 386ad31fbf..952021ce1f 100644--- a/apps/web/src/lib/graphql-cache/telemetry.ts+++ b/apps/web/src/lib/graphql-cache/telemetry.ts@@ -19,6 +19,7 @@ export const CACHE_TELEMETRY_EVENT_NAMES = ['graphql_cache.lock_wait','graphql_cache.storage_reset_required','graphql_cache.logical_reset',+ 'graphql_cache.revision_advance','graphql_cache.reset_wipe','graphql_cache.origin_storage_pressure','graphql_cache.linear_memory',@@ -75,6 +76,17 @@ export const CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY = [export type CacheQueueDiagnosticsAvailability =(typeof CACHE_QUEUE_DIAGNOSTICS_AVAILABILITY)[number];+export const CACHE_REVISION_CATEGORIES = [+ 'authoritative-write',+ 'optimistic-enqueue',+ 'optimistic-commit',+ 'optimistic-rollback',+ 'external-invalidation',+ 'deletion',+ 'clear',+] as const;+export type CacheRevisionCategory = (typeof CACHE_REVISION_CATEGORIES)[number];+/** Payload-free, bounded error classes shared by all cache layers. */export const CACHE_ERROR_CODES = ['none',@@ -143,6 +155,7 @@ export type CacheTelemetryObservation = {persistence?: 'granted' | 'denied' | 'unknown';openOutcome?: CacheOpenOutcome;queueDiagnosticsAvailability?: CacheQueueDiagnosticsAvailability;+ revisionCategory?: CacheRevisionCategory;resetAttempt?: 'wipe-before-open';durationMs?: number;bytes?: number;@@ -245,6 +258,10 @@ function sanitizeObservation(queueDiagnosticsAvailability: input.queueDiagnosticsAvailability,}: {}),+ ...(input.revisionCategory !== undefined &&+ CACHE_REVISION_CATEGORIES.includes(input.revisionCategory)+ ? { revisionCategory: input.revisionCategory }+ : {}),...(input.resetAttempt === 'wipe-before-open'? { resetAttempt: input.resetAttempt }: {}),@@ -470,6 +487,7 @@ export function operationCategoryForRequest(.with('init', () => 'initialization' as const).with('read',+ 'current-revision','read-records-by-keys','search','entity-filter',@@ -612,6 +630,7 @@ export function isCacheTelemetryObservation('persistence','openOutcome','queueDiagnosticsAvailability',+ 'revisionCategory','resetAttempt','durationMs','bytes',diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.tsindex 80087a8d1f..746e4a7f7b 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/fake-cache.engine-worker.ts@@ -1,6 +1,10 @@/// <reference lib="webworker" />-import type { CacheRequest, CacheResponse } from '../../protocol';+import type {+ CacheRequest,+ CacheResponse,+ INITIAL_CACHE_REVISION,+} from '../../protocol';import {CACHE_COORDINATOR_PROTOCOL_VERSION,type CoordinatorToEngineEnvelope,@@ -92,9 +96,12 @@ const sendStaleResponse = (ownerEpoch: number, routeId: number): void => {);};+type FakeEngineState = { revision: bigint };+const execute = async (database: IDBDatabase,- request: CacheRequest+ request: CacheRequest,+ state: FakeEngineState): Promise<CacheResponse> => {if (request.kind === 'read' && request.query.includes('Slow')) {await delay(10_000);@@ -102,12 +109,20 @@ const execute = async (switch (request.kind) {case 'init':return { id: request.id, ok: true, result: null };+ case 'current-revision':+ return { id: request.id, ok: true, result: state.revision.toString() };case 'write':await put(database, request.data);+ state.revision += 1n;return {id: request.id,ok: true,- result: { changed: ['ROOT_QUERY'], affectedOps: [], reset: false },+ result: {+ revision: state.revision.toString(),+ changed: ['ROOT_QUERY'],+ affectedOps: [],+ reset: false,+ },};case 'read': {const value = await get(database);@@ -120,7 +135,12 @@ const execute = async (}case 'clear':await clear(database);- return { id: request.id, ok: true, result: null };+ state.revision += 1n;+ return {+ id: request.id,+ ok: true,+ result: state.revision.toString(),+ };default:return {id: request.id,@@ -148,6 +168,7 @@ async function activate(ownerEpoch: activation.ownerEpoch,});let database: IDBDatabase | undefined;+ const engineState: FakeEngineState = { revision: 0n };let queue = Promise.resolve();let draining = false;let requestShutdown: (() => void) | undefined;@@ -214,7 +235,11 @@ async function activate(queue = queue.then(async () => {let response: CacheResponse;try {- response = await execute(activeDatabase, message.request);+ response = await execute(+ activeDatabase,+ message.request,+ engineState+ );} catch (error) {response = {id: message.request.id,@@ -240,7 +265,11 @@ async function activate(withVersion<EngineToCoordinatorEnvelope>({kind: 'engine-push',ownerEpoch: activation.ownerEpoch,- push: { kind: 'cache-changed' },+ push: {+ kind: 'cache-changed',+ revision:+ engineState.revision.toString() as typeof INITIAL_CACHE_REVISION,+ },}));}diff --git a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.tsindex aca24db805..28c543fa52 100644--- a/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/cache-engine-runtime.test.ts@@ -1,5 +1,6 @@import { describe, expect, it, vi } from 'vitest';import type { CacheRequest } from '../protocol';+import { INITIAL_CACHE_REVISION } from '../protocol';import {type CacheEngineRuntimeOptions,installCacheEngineWorker,@@ -587,7 +588,10 @@ describe('cache engine worker runtime', () => {markEffectStarted();await oldOutputBlocked;port.postMessage({ id: request.id, ok: true, result: null });- port.postMessage({ kind: 'cache-changed' });+ port.postMessage({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ });markOldOutputPosted();},})diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.tsindex ad24cc8d0d..c624b82af1 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-core.test.ts@@ -1,4 +1,5 @@import { describe, expect, it } from 'vitest';+import { INITIAL_CACHE_REVISION } from '../protocol';import { type CoordinatorAction, CoordinatorCore } from './coordinator-core';import type { DatabaseActionProof } from './coordinator-protocol';@@ -168,8 +169,16 @@ describe('CoordinatorCore', () => {core.beginGracefulDeparture('tab-a', 1);expect(core.request('tab-b', clear(5))).toEqual([]);expect(core.snapshot().queuedRequestCount).toBe(1);- expect(core.enginePush(1, { kind: 'cache-changed' })).toEqual([- { kind: 'broadcast-push', push: { kind: 'cache-changed' } },+ expect(+ core.enginePush(1, {+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ })+ ).toEqual([+ {+ kind: 'broadcast-push',+ push: { kind: 'cache-changed', revision: INITIAL_CACHE_REVISION },+ },]);expect(core.engineResponse(1, routed.routeId, {@@ -254,7 +263,12 @@ describe('CoordinatorCore', () => {reason: 'unknown-route',}));- expect(core.enginePush(0, { kind: 'cache-changed' })).toContainEqual(+ expect(+ core.enginePush(0, {+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ })+ ).toContainEqual(expect.objectContaining({kind: 'drop-stale-engine-message',reason: 'stale-epoch',diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.tsindex e3db174409..54ef7cec71 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts@@ -1,4 +1,5 @@import { describe, expect, it } from 'vitest';+import { INITIAL_CACHE_REVISION } from '../protocol';import {CACHE_COORDINATOR_PROTOCOL_VERSION,databaseOwnerLockName,@@ -25,6 +26,7 @@ const enginePort = {describe('coordinator runtime protocol', () => {it('validates cache RPCs and rejects unknown fields or kinds', () => {expect(isCacheRequest({ id: 0, kind: 'clear' })).toBe(true);+ expect(isCacheRequest({ id: 1, kind: 'current-revision' })).toBe(true);expect(isCacheRequest({ id: 1, kind: 'read', query: '{ x }' })).toBe(true);expect(isCacheRequest({@@ -114,7 +116,12 @@ describe('coordinator runtime protocol', () => {})).toBe(false);expect(isCacheResponse({ id: 3, ok: false, error: 4 })).toBe(false);- expect(isCachePush({ kind: 'cache-changed' })).toBe(true);+ expect(+ isCachePush({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ })+ ).toBe(true);expect(isCachePush({kind: 'mutation-settled',diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.tsindex 83dad846e2..2e1c2c8b37 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts@@ -365,6 +365,8 @@ export function isCacheRequest(value: unknown): value is CacheRequest {isNonEmptyString(value.scope) &&isOptionalPositiveInteger(value.hotCapacity));+ case 'current-revision':+ return hasOnlyKeys(value, ['id', 'kind']);case 'read':return (hasOnlyKeys(value, [diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.tsindex be8c5a8ddd..bb62975579 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-router.test.ts@@ -1,4 +1,5 @@import { afterEach, describe, expect, it, vi } from 'vitest';+import { INITIAL_CACHE_REVISION } from '../protocol';import {CACHE_COORDINATOR_PROTOCOL_VERSION,databaseOwnerLockName,@@ -338,11 +339,19 @@ describe('CoordinatorRouter', () => {...version,kind: 'engine-push',ownerEpoch: 1,- push: { kind: 'cache-changed' },+ push: {+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ },});for (const tab of [tabA, tabB, tabC]) {expect(messagesOfKind(tab, 'cache-message')).toContainEqual(- expect.objectContaining({ message: { kind: 'cache-changed' } })+ expect.objectContaining({+ message: {+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ },+ }));}});diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.tsindex df389e562c..73ceecb80a 100644--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts@@ -10,18 +10,21 @@import type { EntityResolverWire } from '../exchange/entity-resolvers';import type {+ AffectedOperationsResult,CachedQueryInstanceWire,CachedQueryVariantWire,+ CacheRevision,+ CacheRevisionResult,ClaimedMutation,EnqueueOptimisticMutationResult,EntityFilterCacheArgs,EntityFilterCacheResult,OptimisticLinkPatchWire,QueryRevalidationWire,+ ReadRecordsByKeysResult,ReadResult,SearchCacheArgs,SearchCachePage,- SelectedRecordByKeyWire,WriteResult,} from '../protocol';import { workerCacheTelemetry } from '../telemetry-relay';@@ -62,6 +65,7 @@ export type CacheEngineHydrationResult = WriteResult & {};export interface CacheEngine {+ currentRevision(): Promise<CacheRevision>;boundIdentity(): Promise<string | null>;/** Optional for compatibility engines; absence means unavailable. */queueDiagnostics?(): Promise<CacheQueueDiagnostics>;@@ -76,7 +80,7 @@ export interface CacheEngine {document: string,fragmentName: string,keys: string[]- ): Promise<SelectedRecordByKeyWire[]>;+ ): Promise<ReadRecordsByKeysResult>;search(request: SearchCacheArgs & { nowMs: number }): Promise<SearchCachePage>;@@ -154,10 +158,10 @@ export interface CacheEngine {leaseOwner: string,leaseGeneration: string): Promise<WriteResult>;- invalidateKeys(keys: string[]): Promise<string[]>;- deleteKeys(keys: string[]): Promise<string[]>;+ invalidateKeys(keys: string[]): Promise<AffectedOperationsResult>;+ deleteKeys(keys: string[]): Promise<AffectedOperationsResult>;teardownOperation(opId: string): Promise<void>;- clear(): Promise<void>;+ clear(): Promise<CacheRevisionResult>;/** Reset/recreate OPFS; concurrent calls wait for the fresh engine. */physicalReset(): Promise<void>;/** Gracefully close Turso/OPFS and release the owner lock. */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 4e01e2b67e..97d41364f0 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@@ -1,4 +1,5 @@import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { INITIAL_CACHE_REVISION } from '../protocol';const loadCacheWasmMock = vi.hoisted(() => vi.fn());@@ -22,7 +23,11 @@ describe('CacheWorkerCore', () => {record: { id: 'item-1' },},];- const readRecordsByKeys = vi.fn().mockResolvedValue(records);+ const selectionResult = {+ revision: INITIAL_CACHE_REVISION,+ records,+ };+ const readRecordsByKeys = vi.fn().mockResolvedValue(selectionResult);loadCacheWasmMock.mockResolvedValue({openCache: vi.fn().mockResolvedValue({ readRecordsByKeys }),});@@ -48,7 +53,11 @@ describe('CacheWorkerCore', () => {'Item',['GraphqlSoupDocument:item-1']);- expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: records });+ expect(messages.at(-1)).toEqual({+ id: 2,+ ok: true,+ result: selectionResult,+ });});it('dispatches bounded search to the wasm compact projection', async () => {@@ -95,6 +104,7 @@ describe('CacheWorkerCore', () => {const order: string[] = [];let resolveEnqueue!: (result: {transactionId: string;+ revision: typeof INITIAL_CACHE_REVISION;changed: string[];affectedOps: string[];reset: false;@@ -104,6 +114,7 @@ describe('CacheWorkerCore', () => {order.push('enqueue:start');return new Promise<{transactionId: string;+ revision: typeof INITIAL_CACHE_REVISION;changed: string[];affectedOps: string[];reset: false;@@ -165,6 +176,7 @@ describe('CacheWorkerCore', () => {);resolveEnqueue({transactionId: '1',+ revision: INITIAL_CACHE_REVISION,changed: ['Thing:1'],affectedOps: ['client:query'],reset: false,@@ -423,6 +435,7 @@ describe('CacheWorkerCore', () => {order.push(`enqueue:${query}`);return {transactionId: query,+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -644,6 +657,7 @@ describe('CacheWorkerCore', () => {order.push('enqueue');return {transactionId: '1',+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -754,6 +768,7 @@ describe('CacheWorkerCore', () => {it('pushes cache changes even without affected operations', async () => {const writeResult = {+ revision: INITIAL_CACHE_REVISION,changed: ['GraphqlSoupDocument:doc-1'],affectedOps: [],reset: false,@@ -795,7 +810,10 @@ describe('CacheWorkerCore', () => {{ user: { id: 'user-1' } },undefined);- expect(messages).toContainEqual({ kind: 'cache-changed' });+ expect(messages).toContainEqual({+ kind: 'cache-changed',+ revision: INITIAL_CACHE_REVISION,+ });});it('drains earlier request responses before consuming close and rejects later admission', async () => {@@ -953,6 +971,7 @@ describe('CacheWorkerCore', () => {});const close = vi.fn().mockResolvedValue(undefined);const writeQuery = vi.fn().mockResolvedValue({+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -1086,6 +1105,7 @@ describe('CacheWorkerCore', () => {.mockImplementation(() => new Promise(() => {}));const readQuery = vi.fn().mockResolvedValue({ kind: 'miss' });const writeQuery = vi.fn().mockResolvedValue({+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -1155,6 +1175,7 @@ describe('CacheWorkerCore', () => {.mockRejectedValueOnce(resetError).mockImplementation(() => new Promise(() => {}));const writeQuery = vi.fn().mockResolvedValue({+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,@@ -1225,6 +1246,7 @@ describe('CacheWorkerCore', () => {it('records an identity-changing hydration as a logical reset', async () => {const hydrateQuery = vi.fn().mockResolvedValue({+ revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: true,@@ -1260,7 +1282,12 @@ describe('CacheWorkerCore', () => {expect(port.postMessage).toHaveBeenLastCalledWith({id: 2,ok: true,- result: { kind: 'data', data: { cursor: 'next' }, reset: true },+ result: {+ kind: 'data',+ data: { cursor: 'next' },+ revision: INITIAL_CACHE_REVISION,+ reset: true,+ },});});diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.tsindex 6961f33a50..4ff0f6ba3f 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts@@ -5,17 +5,20 @@import { match } from 'ts-pattern';import type {+ AffectedOperationsResult,CachePush,CacheRequest,CacheResponse,+ CacheRevisionResult,EnqueueOptimisticMutationResult,EntityFilterCacheResult,HydrationResult,+ ReadRecordsByKeysResult,ReadResult,SearchCachePage,- SelectedRecordByKeyWire,WriteResult,} from '../protocol';+import { parseCacheRevision } from '../protocol';import {type CacheTelemetryRecorderLike,classifyCacheError,@@ -81,6 +84,28 @@ function isQueryDataWrite(request: CacheRequest): boolean {return request.kind === 'write' || request.kind === 'hydrate';}+function revisionAdvancementCategory(+ request: CacheRequest+):+ | 'authoritative-write'+ | 'optimistic-enqueue'+ | 'optimistic-commit'+ | 'optimistic-rollback'+ | 'external-invalidation'+ | 'deletion'+ | 'clear'+ | undefined {+ return match(request.kind)+ .with('write', 'hydrate', () => 'authoritative-write' as const)+ .with('enqueue-optimistic-mutation', () => 'optimistic-enqueue' as const)+ .with('commit-optimistic-write', () => 'optimistic-commit' as const)+ .with('rollback-optimistic-write', () => 'optimistic-rollback' as const)+ .with('invalidate', () => 'external-invalidation' as const)+ .with('delete-records', () => 'deletion' as const)+ .with('clear', () => 'clear' as const)+ .otherwise(() => undefined);+}+function requestPriority(request: CacheRequest): number {if (request.kind === 'hydrate') return BACKGROUND_HYDRATION_PRIORITY;if (request.kind === 'read') {@@ -181,6 +206,16 @@ export class CacheWorkerCore {try {const result = await this.enqueue(request);const durationMs = this.now() - startedAt;+ const revisionCategory = revisionAdvancementCategory(request);+ if (revisionCategory !== undefined) {+ this.telemetry.record({+ name: 'graphql_cache.revision_advance',+ operationCategory: category,+ outcome: 'success',+ errorCode: 'none',+ revisionCategory,+ });+ }this.telemetry.record({name: 'graphql_cache.engine_request',operationCategory: category,@@ -385,6 +420,9 @@ export class CacheWorkerCore {await this.init(request.scope, request.hotCapacity);return null;})+ .with({ kind: 'current-revision' }, async () => {+ return parseCacheRevision(await this.requireEngine().currentRevision());+ }).with({ kind: 'read' }, async (request) => {const engine = this.requireEngine();const result: ReadResult = await engine.readQuery(@@ -397,13 +435,16 @@ export class CacheWorkerCore {return result;}).with({ kind: 'read-records-by-keys' }, async (request) => {- const result: SelectedRecordByKeyWire[] =+ const result: ReadRecordsByKeysResult =await this.requireEngine().readRecordsByKeys(request.document,request.fragmentName,request.keys);- return result;+ return {+ ...result,+ revision: parseCacheRevision(result.revision),+ };}).with({ kind: 'search' }, async (request) => {const result: SearchCachePage = await this.requireEngine().search(@@ -414,7 +455,9 @@ export class CacheWorkerCore {.with({ kind: 'entity-filter' }, async (request) => {const result: EntityFilterCacheResult =await this.requireEngine().entityFilter(request.request);- return result;+ return result.kind === 'unsupported'+ ? result+ : { ...result, revision: parseCacheRevision(result.revision) };}).with({ kind: 'write' }, async (request) => {const engine = this.requireEngine();@@ -429,6 +472,7 @@ export class CacheWorkerCore {request.data,request.identity);+ result.revision = parseCacheRevision(result.revision);this.fanOut(result, true);return result;})@@ -440,11 +484,17 @@ export class CacheWorkerCore {request.data,request.identity);+ result.revision = parseCacheRevision(result.revision);this.fanOut(result, true);const hydration: HydrationResult & Pick<WriteResult, 'reset'> =result.data === null- ? { kind: 'void', reset: result.reset }- : { kind: 'data', data: result.data, reset: result.reset };+ ? { kind: 'void', revision: result.revision, reset: result.reset }+ : {+ kind: 'data',+ data: result.data,+ revision: result.revision,+ reset: result.reset,+ };return hydration;}).with({ kind: 'enqueue-optimistic-mutation' }, async (request) => {@@ -463,6 +513,7 @@ export class CacheWorkerCore {request.nowMs,request.leaseExpiresAtMs);+ result.revision = parseCacheRevision(result.revision);this.fanOut(result, true);return result;})@@ -512,6 +563,7 @@ export class CacheWorkerCore {request.variables,request.data);+ result.revision = parseCacheRevision(result.revision);this.fanOut(result, true);this.push({kind: 'mutation-settled',@@ -529,6 +581,7 @@ export class CacheWorkerCore {request.leaseOwner,request.leaseGeneration);+ result.revision = parseCacheRevision(result.revision);this.fanOut(result, true);this.push({kind: 'mutation-settled',@@ -542,40 +595,49 @@ export class CacheWorkerCore {}).with({ kind: 'invalidate' }, async (request) => {const engine = this.requireEngine();- const affectedOps = await engine.invalidateKeys(request.keys);+ const result: AffectedOperationsResult = await engine.invalidateKeys(+ request.keys+ );+ result.revision = parseCacheRevision(result.revision);this.fanOut({+ revision: result.revision,changed: request.keys,- affectedOps,+ affectedOps: result.affectedOps,reset: false,revalidations: [],},true);- return affectedOps;+ return result;}).with({ kind: 'delete-records' }, async (request) => {const engine = this.requireEngine();- const affectedOps = await engine.deleteKeys(request.keys);+ const result: AffectedOperationsResult = await engine.deleteKeys(+ request.keys+ );+ result.revision = parseCacheRevision(result.revision);this.fanOut({+ revision: result.revision,changed: request.keys,- affectedOps,+ affectedOps: result.affectedOps,reset: false,revalidations: [],},true);- return affectedOps;+ return result;}).with({ kind: 'teardown' }, async (request) => {await this.requireEngine().teardownOperation(request.opId);return null;}).with({ kind: 'clear' }, async () => {- await this.requireEngine().clear();- this.push({ kind: 'cache-changed' });- return null;+ const result: CacheRevisionResult = await this.requireEngine().clear();+ const revision = parseCacheRevision(result.revision);+ this.push({ kind: 'cache-changed', revision });+ return revision;}).exhaustive();}@@ -820,7 +882,7 @@ export class CacheWorkerCore {});}if (cacheChanged) {- this.push({ kind: 'cache-changed' });+ this.push({ kind: 'cache-changed', revision: result.revision });}}diff --git a/apps/web/src/lib/queries/channel/graphql.ts b/apps/web/src/lib/queries/channel/graphql.tsindex b6b65e78b6..9cbf00fc9d 100644--- a/apps/web/src/lib/queries/channel/graphql.ts+++ b/apps/web/src/lib/queries/channel/graphql.ts@@ -51,7 +51,7 @@ export async function materializeCachedGraphqlChannels(channelDocuments.map((document) => document.recordKey));- return records.flatMap(({ recordKey, record }) => {+ return records.records.flatMap(({ recordKey, record }) => {const channel = record as GraphqlChannelQuickAccessFieldsFragment;if (channel.__typename !== 'GraphqlSoupChannel') return [];const separator = recordKey.indexOf(':');diff --git a/apps/web/src/lib/queries/channel/tests/graphql.test.ts b/apps/web/src/lib/queries/channel/tests/graphql.test.tsindex 23fbf893d3..a06ec7f196 100644--- a/apps/web/src/lib/queries/channel/tests/graphql.test.ts+++ b/apps/web/src/lib/queries/channel/tests/graphql.test.ts@@ -4,6 +4,7 @@ import type {SearchCacheArgs,SearchCachePage,} from '@graphql-cache/index';+import { INITIAL_CACHE_REVISION } from '@graphql-cache/index';import { expect, it, vi } from 'vitest';import { readCachedGraphqlChannels } from '../graphql';@@ -13,7 +14,13 @@ function cacheHost(args: ReadRecordsByKeysArgs) => Promise<Array<{ recordKey: string; record: unknown }>>): Pick<CacheHost, 'search' | 'readRecordsByKeys'> {- return { search, readRecordsByKeys };+ return {+ search,+ readRecordsByKeys: async (args) => ({+ revision: INITIAL_CACHE_REVISION,+ records: await readRecordsByKeys(args),+ }),+ };}it('reads recent channels and DMs from the cache projection', async () => {diff --git a/apps/web/src/lib/queries/history/graphql.ts b/apps/web/src/lib/queries/history/graphql.tsindex 95b76e1906..e29472db3b 100644--- a/apps/web/src/lib/queries/history/graphql.ts+++ b/apps/web/src/lib/queries/history/graphql.ts@@ -120,7 +120,7 @@ export async function materializeCachedGraphqlHistoryItems(nameSelection(typename),keys);- for (const { recordKey, record } of records) {+ for (const { recordKey, record } of records.records) {recordsByKey.set(recordKey, record);}})diff --git a/apps/web/src/lib/queries/history/tests/graphql.test.ts b/apps/web/src/lib/queries/history/tests/graphql.test.tsindex fd477a4cd7..142c771a07 100644--- a/apps/web/src/lib/queries/history/tests/graphql.test.ts+++ b/apps/web/src/lib/queries/history/tests/graphql.test.ts@@ -4,6 +4,7 @@ import type {SearchCacheArgs,SearchCachePage,} from '@graphql-cache/index';+import { INITIAL_CACHE_REVISION } from '@graphql-cache/index';import { describe, expect, it, vi } from 'vitest';import { readCachedGraphqlHistoryItems } from '../graphql';@@ -13,7 +14,13 @@ function cacheHost(args: ReadRecordsByKeysArgs) => Promise<Array<{ recordKey: string; record: unknown }>>): Pick<CacheHost, 'search' | 'readRecordsByKeys'> {- return { search, readRecordsByKeys };+ return {+ search,+ readRecordsByKeys: async (args) => ({+ revision: INITIAL_CACHE_REVISION,+ records: await readRecordsByKeys(args),+ }),+ };}describe('cached GraphQL history', () => {diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.tsindex 619dd41570..2ceec4bac2 100644--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts@@ -13,6 +13,9 @@ const getGraphqlSoupClientMock = vi.hoisted(() => vi.fn());const getGraphqlSoupCacheHostMock = vi.hoisted(() => vi.fn());const entityFilterMock = vi.hoisted(() => vi.fn());const readRecordsByKeysMock = vi.hoisted(() => vi.fn());+const REVISION_0 = '0';+const REVISION_1 = '1';+const REVISION_2 = '2';const mapGraphqlSoupPageMock = vi.hoisted(() =>vi.fn((data: {@@ -29,7 +32,10 @@ const mapSoupPageToEntityListMock = vi.hoisted(() =>const makeGraphqlSoupInputMock = vi.hoisted(() => vi.fn());vi.mock('@macro-inc/observability', () => ({- Telemetry: { error: vi.fn() },+ Telemetry: {+ error: vi.fn(),+ span: vi.fn(() => ({ setAttr: vi.fn(), end: vi.fn() })),+ },}));vi.mock('@queries/storage/instructions-md', () => ({@@ -39,6 +45,8 @@ vi.mock('@queries/storage/instructions-md', () => ({vi.mock('@app/lib/graphql-cache', () => ({selectRecords: vi.fn(() => ({})),readRecordsByKeys: readRecordsByKeysMock,+ normalizedCacheResultMetadata: (result: OperationResult) =>+ result.extensions?.__macroNormalizedCache,}));vi.mock('@service-storage/graphql-soup', () => ({@@ -59,7 +67,13 @@ vi.mock('../transform-utils', () => ({import { createGraphqlSoupAstItemsQuery } from './items';type FakeExecution = {- next(data: unknown): void;+ next(+ data: unknown,+ metadata?: {+ source: 'live-network' | 'normalized-cache-hit';+ revision?: string;+ }+ ): void;};type SoupPageFixture = {@@ -94,11 +108,17 @@ function makeFakeClient(): {context,} as Operation<unknown, Record<string, unknown>>;executions.push({- next: (data) =>- subject.next({ operation, data } as OperationResult<- unknown,- Record<string, unknown>- >),+ next: (+ data,+ metadata = { source: 'live-network', revision: REVISION_1 }+ ) =>+ subject.next({+ operation,+ data,+ extensions: { __macroNormalizedCache: metadata },+ stale: false,+ hasNext: false,+ } as OperationResult<unknown, Record<string, unknown>>),});return subject.source;};@@ -124,8 +144,10 @@ describe('createGraphqlSoupAstItemsQuery', () => {const fake = makeFakeClient();getGraphqlSoupClientMock.mockReturnValue(fake.client);getGraphqlSoupCacheHostMock.mockReturnValue({+ currentRevision: async () => REVISION_0,entityFilter: entityFilterMock,onCacheChanged: () => () => undefined,+ onCacheGenerationChanged: () => () => undefined,});makeGraphqlSoupInputMock.mockReturnValue({ initial: { limit: 50 } });@@ -145,20 +167,26 @@ describe('createGraphqlSoupAstItemsQuery', () => {const fake = makeFakeClient();getGraphqlSoupClientMock.mockReturnValue(fake.client);getGraphqlSoupCacheHostMock.mockReturnValue({+ currentRevision: async () => REVISION_0,entityFilter: entityFilterMock,onCacheChanged: () => () => undefined,+ onCacheGenerationChanged: () => () => undefined,});entityFilterMock.mockResolvedValue({kind: 'complete',+ revision: REVISION_0,keys: ['GraphqlSoupDocument:task-1'],optimistic: false,});- readRecordsByKeysMock.mockResolvedValue([- {- recordKey: 'GraphqlSoupDocument:task-1',- record: { id: 'task-1', type: 'document', name: 'Local task' },- },- ]);+ readRecordsByKeysMock.mockResolvedValue({+ revision: REVISION_0,+ records: [+ {+ recordKey: 'GraphqlSoupDocument:task-1',+ record: { id: 'task-1', type: 'document', name: 'Local task' },+ },+ ],+ });await new Promise<void>((resolve) => {createRoot((dispose) => {@@ -192,34 +220,52 @@ describe('createGraphqlSoupAstItemsQuery', () => {expect(entityFilterMock).toHaveBeenCalled();});- it('keeps an optimistic local page until cache settlement', async () => {+ it('reevaluates exact local membership after optimistic settlement', async () => {const fake = makeFakeClient();getGraphqlSoupClientMock.mockReturnValue(fake.client);- let notifyCacheChanged: () => void = () => undefined;+ let currentRevision = REVISION_0;+ let notifyCacheChanged: (revision: string) => void = () => undefined;getGraphqlSoupCacheHostMock.mockReturnValue({+ currentRevision: async () => currentRevision,entityFilter: entityFilterMock,- onCacheChanged: (callback: () => void) => {+ onCacheChanged: (callback: (revision: string) => void) => {notifyCacheChanged = callback;return () => undefined;},+ onCacheGenerationChanged: () => () => undefined,});entityFilterMock.mockResolvedValueOnce({kind: 'complete',+ revision: REVISION_0,keys: ['GraphqlSoupDocument:task-1'],optimistic: true,}).mockResolvedValueOnce({kind: 'complete',+ revision: REVISION_2,keys: ['GraphqlSoupDocument:task-1'],optimistic: false,});- readRecordsByKeysMock.mockResolvedValue([- {- recordKey: 'GraphqlSoupDocument:task-1',- record: { id: 'task-1', type: 'document', name: 'Optimistic task' },- },- ]);+ readRecordsByKeysMock+ .mockResolvedValueOnce({+ revision: REVISION_0,+ records: [+ {+ recordKey: 'GraphqlSoupDocument:task-1',+ record: { id: 'task-1', type: 'document', name: 'Optimistic task' },+ },+ ],+ })+ .mockResolvedValueOnce({+ revision: REVISION_2,+ records: [+ {+ recordKey: 'GraphqlSoupDocument:task-1',+ record: { id: 'task-1', type: 'document', name: 'Network task' },+ },+ ],+ });await new Promise<void>((resolve) => {createRoot((dispose) => {@@ -242,9 +288,10 @@ describe('createGraphqlSoupAstItemsQuery', () => {next_cursor: null,}));- expect(query.data()?.entities[0]?.name).toBe('Optimistic task');+ expect(query.data()?.entities[0]?.name).toBe('Network task');- notifyCacheChanged();+ currentRevision = REVISION_2;+ notifyCacheChanged(REVISION_2);await vi.waitFor(() => {expect(entityFilterMock).toHaveBeenCalledTimes(2);expect(query.data()?.entities[0]?.name).toBe('Network task');@@ -257,6 +304,139 @@ describe('createGraphqlSoupAstItemsQuery', () => {});});+ it('promotes realtime local revisions without a network rerun and fences stale generations', async () => {+ const fake = makeFakeClient();+ getGraphqlSoupClientMock.mockReturnValue(fake.client);+ let currentRevision = REVISION_1;+ let notifyCacheChanged: (revision: string) => void = () => undefined;+ let notifyGenerationChanged: () => void = () => undefined;+ let resolveRevision4!: (value: unknown) => void;+ const revision4Filter = new Promise((resolve) => {+ resolveRevision4 = resolve;+ });+ getGraphqlSoupCacheHostMock.mockReturnValue({+ currentRevision: async () => currentRevision,+ onCacheChanged: (callback: (revision: string) => void) => {+ notifyCacheChanged = callback;+ return () => undefined;+ },+ onCacheGenerationChanged: (callback: () => void) => {+ notifyGenerationChanged = callback;+ return () => undefined;+ },+ entityFilter: entityFilterMock,+ });+ entityFilterMock.mockImplementation(async () => {+ if (currentRevision === '4') return await revision4Filter;+ const names =+ currentRevision === REVISION_2+ ? ['Network item', 'Realtime item']+ : currentRevision === '5'+ ? ['Latest local item']+ : ['Replacement durable item'];+ return {+ kind: 'complete',+ revision: currentRevision,+ keys: names.map((_, index) => `GraphqlSoupDocument:item-${index}`),+ optimistic: false,+ };+ });+ readRecordsByKeysMock.mockImplementation(+ async (_host, _selection, keys: string[]) => {+ const names =+ currentRevision === REVISION_2+ ? ['Network item', 'Realtime item']+ : currentRevision === '5'+ ? ['Latest local item']+ : ['Replacement durable item'];+ return {+ revision: currentRevision,+ records: keys.map((recordKey, index) => ({+ recordKey,+ record: {+ id: `item-${index}`,+ type: 'document',+ name: names[index],+ },+ })),+ };+ }+ );++ let dispose!: () => void;+ let query!: ReturnType<typeof createGraphqlSoupAstItemsQuery>;+ createRoot((rootDispose) => {+ dispose = rootDispose;+ query = createGraphqlSoupAstItemsQuery(+ () => ({ params: {}, body: {} }) as never,+ () => ({ enabled: true })+ );+ });++ fake.executions[0]?.next(+ graphqlSoupPage({+ items: [{ id: 'item-0', type: 'document', name: 'Network item' }],+ next_cursor: null,+ }),+ { source: 'live-network', revision: REVISION_1 }+ );+ expect(query.data()?.entities.map((item) => item.name)).toEqual([+ 'Network item',+ ]);++ currentRevision = REVISION_2;+ notifyCacheChanged(REVISION_2);+ await vi.waitFor(() => {+ expect(query.data()?.entities.map((item) => item.name)).toEqual([+ 'Network item',+ 'Realtime item',+ ]);+ });+ expect(fake.executions).toHaveLength(1);++ fake.executions[0]?.next(+ graphqlSoupPage({+ items: [{ id: 'item-0', type: 'document', name: 'New network item' }],+ next_cursor: null,+ }),+ { source: 'live-network', revision: '3' }+ );+ expect(query.data()?.entities.map((item) => item.name)).toEqual([+ 'New network item',+ ]);++ currentRevision = '4';+ notifyCacheChanged('4');+ await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalledTimes(2));+ currentRevision = '5';+ notifyCacheChanged('5');+ await vi.waitFor(() => {+ expect(query.data()?.entities.map((item) => item.name)).toEqual([+ 'Latest local item',+ ]);+ });+ resolveRevision4({+ kind: 'complete',+ revision: '4',+ keys: ['GraphqlSoupDocument:stale'],+ optimistic: false,+ });+ await Promise.resolve();+ expect(query.data()?.entities.map((item) => item.name)).toEqual([+ 'Latest local item',+ ]);++ currentRevision = REVISION_0;+ notifyGenerationChanged();+ await vi.waitFor(() => {+ expect(query.data()?.entities.map((item) => item.name)).toEqual([+ 'Replacement durable item',+ ]);+ });+ expect(fake.executions).toHaveLength(1);+ dispose();+ });+it('retains identical page projections across cache re-executions', () => {const firstPage = {items: [{ id: 'task-1', type: 'document', name: 'Task' }],diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.tsindex cadf13acd9..c25c4d03c7 100644--- a/apps/web/src/lib/queries/soup/graphql/items.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.ts@@ -4,7 +4,12 @@* directly. The public REST/GraphQL facade lives in ../items.ts.*/-import { readRecordsByKeys, selectRecords } from '@app/lib/graphql-cache';+import {+ type CacheRevision,+ normalizedCacheResultMetadata,+ readRecordsByKeys,+ selectRecords,+} from '@app/lib/graphql-cache';import { createUrqlInfiniteQuery } from '@app/lib/urql-solid';import { Telemetry } from '@macro-inc/observability';import { useInstructionsMdIdQuery } from '@queries/storage/instructions-md';@@ -24,6 +29,7 @@ import {import type { CombinedError } from '@urql/core';import {type Accessor,+ batch,createComputed,createEffect,createMemo,@@ -85,31 +91,110 @@ export function createGraphqlSoupAstItemsQuery(const firstPageInput = createMemo(() => inputForCursor(null));const isSupported = () => firstPageInput() !== undefined;- const [localPlaceholder, setLocalPlaceholder] = createSignal<- { data: SoupAstItemsData; optimistic: boolean } | undefined+ type LocalProjection = {+ revision: CacheRevision;+ data: SoupAstItemsData;+ optimistic: boolean;+ };+ const [currentCacheRevision, setCurrentCacheRevision] = createSignal<+ CacheRevision | undefined+ >();+ const [networkAuthorityRevision, setNetworkAuthorityRevision] = createSignal<+ CacheRevision | undefined+ >();+ const [localProjection, setLocalProjection] = createSignal<+ LocalProjection | undefined>();- const [cacheRevision, setCacheRevision] = createSignal(0);const soupItemSelection = selectRecords(SoupItemFieldsFragmentDoc);let localRequest = 0;+ let cacheGeneration = 0;+ let resetContinuationPages: (() => void) | undefined;+ let previousInitialInput: GraphqlSoupInput | undefined;+ let staleFallbackSpan: ReturnType<typeof Telemetry.span> | undefined;++ const recordAuthority = (source: 'network' | 'local' | 'stale-fallback') => {+ const span = Telemetry.span('graphql_cache.soup_authority');+ span.setAttr('authority.source', source);+ span.end();+ };+ const finishStaleFallback = (source: 'network' | 'local') => {+ staleFallbackSpan?.setAttr('authority.resumed_by', source);+ staleFallbackSpan?.end();+ staleFallbackSpan = undefined;+ };createEffect(() => {const host = getGraphqlSoupCacheHost();if (!host) return;- const unsubscribe = host.onCacheChanged(() => {- setCacheRevision((revision) => revision + 1);+ cacheGeneration += 1;+ const invalidateGeneration = () => {+ localRequest += 1;+ setCurrentCacheRevision(undefined);+ setNetworkAuthorityRevision(undefined);+ setLocalProjection(undefined);+ };+ const observeCurrentRevision = () => {+ const observedGeneration = cacheGeneration;+ void host+ .currentRevision()+ .then((revision) => {+ if (+ observedGeneration === cacheGeneration &&+ currentCacheRevision() === undefined+ ) {+ setCurrentCacheRevision(revision);+ }+ })+ .catch(() => undefined);+ };+ const unsubscribeChanges = host.onCacheChanged((revision) => {+ if (+ networkAuthorityRevision() !== undefined &&+ networkAuthorityRevision() !== revision &&+ staleFallbackSpan === undefined+ ) {+ staleFallbackSpan = Telemetry.span('graphql_cache.soup_stale_fallback');+ recordAuthority('stale-fallback');+ }+ setCurrentCacheRevision(revision);+ });+ const unsubscribeGeneration = host.onCacheGenerationChanged(() => {+ const span = Telemetry.span('graphql_cache.engine_generation_changed');+ span.end();+ cacheGeneration += 1;+ invalidateGeneration();+ observeCurrentRevision();+ });+ observeCurrentRevision();+ onCleanup(() => {+ staleFallbackSpan?.end();+ staleFallbackSpan = undefined;+ cacheGeneration += 1;+ unsubscribeChanges();+ unsubscribeGeneration();});- onCleanup(unsubscribe);});createEffect(() => {- cacheRevision();- const requestId = ++localRequest;- setLocalPlaceholder(undefined);+ const revision = currentCacheRevision();const input = firstPageInput();const queryOptions = options();const host = getGraphqlSoupCacheHost();- if (!queryOptions.enabled || !input || !host || !('initial' in input))+ const requestId = ++localRequest;+ if (input !== previousInitialInput) {+ previousInitialInput = input;+ setLocalProjection(undefined);+ }+ if (+ revision === undefined ||+ networkAuthorityRevision() === revision ||+ !queryOptions.enabled ||+ !input ||+ !host ||+ !('initial' in input)+ ) {return;+ }const initial = input.initial;if (!initial) return;const filters = initial.filters ?? {};@@ -118,44 +203,84 @@ export function createGraphqlSoupAstItemsQuery(const sortDirection = initial.sortDirection ?? 'DESC';const limit = initial.limit ?? 20;- void host- .entityFilter({ filters, sortMethod, sortDirection, limit })- .then(async (result) => {- if (result.kind !== 'complete' || requestId !== localRequest) return;- const selected = await readRecordsByKeys(- host,- soupItemSelection,- result.keys- );- if (- requestId !== localRequest ||- selected.length !== result.keys.length- )+ void (async () => {+ const span = Telemetry.span('graphql_cache.soup_local_evaluation');+ let expectedRevision = revision;+ let retryCount = 0;+ let discarded = false;+ let outcome: 'success' | 'incomplete' | 'error' = 'incomplete';+ try {+ for (let attempt = 0; attempt < 3; attempt += 1) {+ const result = await host.entityFilter({+ filters,+ sortMethod,+ sortDirection,+ limit,+ });+ if (result.kind !== 'complete') return;+ if (requestId !== localRequest) {+ discarded = true;+ return;+ }+ const selected = await readRecordsByKeys(+ host,+ soupItemSelection,+ result.keys+ );+ const latestRevision = await host.currentRevision();+ if (requestId !== localRequest) {+ discarded = true;+ return;+ }+ if (+ result.revision !== selected.revision ||+ result.revision !== latestRevision ||+ result.revision !== expectedRevision+ ) {+ discarded = true;+ retryCount += 1;+ expectedRevision = latestRevision;+ setCurrentCacheRevision(latestRevision);+ continue;+ }+ if (selected.records.length !== result.keys.length) return;+ const items = selected.records.flatMap(({ record }) => {+ const item = mapGraphqlSoupItem(record);+ return item ? [item] : [];+ });+ if (items.length !== result.keys.length) return;+ setLocalProjection({+ revision: latestRevision,+ optimistic: result.optimistic,+ data: {+ entities: mapSoupPageToEntityList(+ { items, next_cursor: undefined },+ {+ instructionsIdQuery,+ showSupportedForeignEntities:+ queryOptions.showSupportedForeignEntities,+ }+ ),+ groups: undefined,+ },+ });+ outcome = 'success';+ recordAuthority('local');+ finishStaleFallback('local');+ resetContinuationPages?.();return;- const items = selected.flatMap(({ record }) => {- const item = mapGraphqlSoupItem(record);- return item ? [item] : [];- });- if (items.length !== result.keys.length) return;- setLocalPlaceholder({- optimistic: result.optimistic,- data: {- entities: mapSoupPageToEntityList(- { items, next_cursor: undefined },- {- instructionsIdQuery,- showSupportedForeignEntities:- queryOptions.showSupportedForeignEntities,- }- ),- groups: undefined,- },- });- })- .catch(() => {- // Unsupported, incomplete, validation, and storage failures all use- // the already-running authoritative network request.- });+ }+ } catch {+ outcome = 'error';+ // Unsupported, incomplete, validation, and storage failures retain+ // the stale network/normalized-cache fallback already on screen.+ } finally {+ span.setAttr('evaluation.outcome', outcome);+ span.setAttr('evaluation.retry_count', retryCount);+ span.setAttr('evaluation.discarded', discarded);+ span.end();+ }+ })();});const query = createUrqlInfiniteQuery<@@ -185,6 +310,18 @@ export function createGraphqlSoupAstItemsQuery(enabled: queryOptions.enabled && firstInput !== undefined,requestPolicy: 'cache-and-network',keepPreviousData: false,+ onResult: (result, page) => {+ if (page.pageIndex !== 0) return;+ const metadata = normalizedCacheResultMetadata(result);+ if (metadata?.source !== 'live-network' || !metadata.revision) return;+ batch(() => {+ setCurrentCacheRevision(metadata.revision);+ setNetworkAuthorityRevision(metadata.revision);+ setLocalProjection(undefined);+ });+ recordAuthority('network');+ finishStaleFallback('network');+ },select: ({ pages }) => ({entities: pages.flatMap((page) =>mapSoupPageToEntityList(mapGraphqlSoupPage(page), {@@ -197,6 +334,17 @@ export function createGraphqlSoupAstItemsQuery(};});+ resetContinuationPages = query.resetToInitialPage;++ const authoritativeLocalProjection = (): LocalProjection | undefined => {+ const local = localProjection();+ const revision = currentCacheRevision();+ return local?.revision === revision ? local : undefined;+ };+ const networkIsAuthoritative = (): boolean =>+ networkAuthorityRevision() !== undefined &&+ networkAuthorityRevision() === currentCacheRevision();+const error = (): CombinedError | undefined => query.error ?? undefined;createComputed(on(error, (queryError) => {@@ -208,23 +356,24 @@ export function createGraphqlSoupAstItemsQuery(return {data: () => {- const local = localPlaceholder();- return local?.optimistic ? local.data : (query.data ?? local?.data);+ if (networkIsAuthoritative()) return query.data;+ const local = authoritativeLocalProjection();+ return local?.data ?? query.data ?? localProjection()?.data;},error,isSupported,isEnabled: () => query.isEnabled,- isLoading: () => query.isLoading && localPlaceholder() === undefined,+ isLoading: () =>+ query.isLoading && authoritativeLocalProjection() === undefined,isFetching: () => query.isFetching,isFetchingNextPage: () => query.isFetchingNextPage,- isPlaceholderData: () => {- const local = localPlaceholder();- return (- local !== undefined && (query.data === undefined || local.optimistic)- );- },+ isPlaceholderData: () =>+ !networkIsAuthoritative() && authoritativeLocalProjection() !== undefined,hasNextPage: () => query.hasNextPage,fetchNextPage: async () => {+ // Local predicate pagination is not revision-safe yet. Return to the+ // stale server page chain before requesting its continuation cursor.+ setLocalProjection(undefined);await query.fetchNextPage();},resetToInitialPage: query.resetToInitialPage,diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rsindex 4e4c91e22f..fb50f9ce94 100644--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs@@ -10,7 +10,8 @@//! worker's `{ok: false, error}` responses.use crate::engine::{- ClaimedMutationWire, EngineHandle, EnqueueOptimisticMutationResultWire, ReadResultWire,+ AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,+ EnqueueOptimisticMutationResultWire, ReadResultWire, RecordSelectionResultWire,WriteRegistration, WriteRequest, WriteResultWire,};use crate::{@@ -19,7 +20,6 @@ use crate::{use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant};-use cache_core::record_selection::SelectedRecord;use cache_core::search::{SearchPage, SearchRequest};use cache_turso::TursoFileDatabase;use serde::{Deserialize, Serialize};@@ -77,6 +77,14 @@ pub async fn graphql_cache_init<R: Runtime>(Ok(())}+/// Returns the current in-memory cache revision as a decimal string.+#[tauri::command]+pub async fn graphql_cache_current_revision(+ state: State<'_, CacheState>,+) -> Result<String, String> {+ Ok(engine_handle(&state)?.current_revision().await.to_string())+}+/// Attempts a cache read; registers `op_id` as active when given.#[tauri::command]pub async fn graphql_cache_read(@@ -105,7 +113,7 @@ pub async fn graphql_cache_read_records_by_keys(document: String,fragment_name: String,keys: Vec<String>,-) -> Result<Vec<SelectedRecord>, String> {+) -> Result<RecordSelectionResultWire, String> {engine_handle(&state)?.read_records_by_keys(document, fragment_name, keys).await@@ -160,7 +168,7 @@ pub async fn graphql_cache_write<R: Runtime>(}).await?;emit_ops_affected(&app, &result.affected_ops, &result.changed);- emit_cache_changed(&app);+ emit_cache_changed(&app, &result.revision);Ok(result)}@@ -172,9 +180,14 @@ pub enum HydrationResultWire {Data {/// Projected GraphQL response data.data: serde_json::Value,+ /// Revision installed by the hydration write.+ revision: String,},/// Every response field was cache-only.- Void,+ Void {+ /// Revision installed by the hydration write.+ revision: String,+ },}/// Normalizes and stores a network response, broadcasts affected operations,@@ -203,10 +216,15 @@ pub async fn graphql_cache_hydrate<R: Runtime>(&result.write_result.affected_ops,&result.write_result.changed,);- emit_cache_changed(&app);+ emit_cache_changed(&app, &result.write_result.revision);Ok(match result.data {- Some(data) => HydrationResultWire::Data { data },- None => HydrationResultWire::Void,+ Some(data) => HydrationResultWire::Data {+ data,+ revision: result.write_result.revision,+ },+ None => HydrationResultWire::Void {+ revision: result.write_result.revision,+ },})}@@ -245,7 +263,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>().await?;emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);- emit_cache_changed(&app);+ emit_cache_changed(&app, &result.result.revision);Ok(result)}@@ -352,7 +370,7 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>().await?;emit_ops_affected(&app, &result.affected_ops, &result.changed);- emit_cache_changed(&app);+ emit_cache_changed(&app, &result.revision);emit_mutation_settled(&app, settlement_transaction_id, "committed", None);Ok(result)}@@ -372,7 +390,7 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(.rollback_optimistic_write(transaction_id, lease_owner, lease_generation).await?;emit_ops_affected(&app, &result.affected_ops, &result.changed);- emit_cache_changed(&app);+ emit_cache_changed(&app, &result.revision);emit_mutation_settled(&app,settlement_transaction_id,@@ -389,10 +407,10 @@ pub async fn graphql_cache_invalidate<R: Runtime>(app: AppHandle<R>,state: State<'_, CacheState>,keys: Vec<String>,-) -> Result<Vec<String>, String> {+) -> Result<AffectedOperationsResultWire, String> {let affected = engine_handle(&state)?.invalidate(keys.clone()).await?;- emit_ops_affected(&app, &affected, &keys);- emit_cache_changed(&app);+ emit_ops_affected(&app, &affected.affected_ops, &keys);+ emit_cache_changed(&app, &affected.revision);Ok(affected)}@@ -403,9 +421,10 @@ pub async fn graphql_cache_delete_records<R: Runtime>(app: AppHandle<R>,state: State<'_, CacheState>,keys: Vec<String>,-) -> Result<Vec<String>, String> {+) -> Result<AffectedOperationsResultWire, String> {let affected = engine_handle(&state)?.delete_records(keys.clone()).await?;- emit_ops_affected(&app, &affected, &keys);+ emit_ops_affected(&app, &affected.affected_ops, &keys);+ emit_cache_changed(&app, &affected.revision);Ok(affected)}@@ -423,8 +442,8 @@ pub async fn graphql_cache_teardown(pub async fn graphql_cache_clear<R: Runtime>(app: AppHandle<R>,state: State<'_, CacheState>,-) -> Result<(), String> {- engine_handle(&state)?.clear().await?;- emit_cache_changed(&app);- Ok(())+) -> Result<String, String> {+ let revision = engine_handle(&state)?.clear().await?.to_string();+ emit_cache_changed(&app, &revision);+ Ok(revision)}diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rsindex 951be2e1d4..8c8923d249 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs@@ -20,7 +20,8 @@ use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};-use cache_core::record_selection::RecordSelection;+use cache_core::record_selection::{RecordSelection, SelectedRecord};+use cache_core::revision::CacheRevision;use cache_core::search::{SearchPage, SearchRequest};use cache_core::value::EntityKey;use cache_turso::{TursoStorage, TursoStorageCloseOutcome};@@ -46,6 +47,8 @@ pub enum ReadResultWire {#[derive(Debug, Serialize)]#[serde(rename_all = "camelCase")]pub struct WriteResultWire {+ /// Effective-view revision installed by this logical mutation.+ pub revision: String,/// Entity keys whose records changed.pub changed: Vec<String>,/// Registered operation ids affected by the change (origin excluded).@@ -66,6 +69,26 @@ pub struct HydrationWriteResultWire {pub data: Option<serde_json::Value>,}+/// Revision-qualified normalized record selection result.+#[derive(Debug, Serialize)]+#[serde(rename_all = "camelCase")]+pub struct RecordSelectionResultWire {+ /// Revision observed by record selection.+ pub revision: String,+ /// Selected normalized records.+ pub records: Vec<SelectedRecord>,+}++/// Revision-qualified affected operation ids.+#[derive(Debug, Serialize)]+#[serde(rename_all = "camelCase")]+pub struct AffectedOperationsResultWire {+ /// Revision installed by the invalidation or deletion.+ pub revision: String,+ /// Registered operation ids affected by the change.+ pub affected_ops: Vec<String>,+}+/// Result of durably enqueueing an optimistic mutation and attempting to/// claim the strict queue head.#[derive(Debug, Serialize)]@@ -213,6 +236,7 @@ pub struct EngineHandle {fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {WriteResultWire {+ revision: result.revision.to_string(),changed: result.changed.into_iter()@@ -267,6 +291,11 @@ impl EngineHandle {}}+ /// Returns the current in-memory cache revision.+ pub async fn current_revision(&self) -> CacheRevision {+ self.inner.lock().await.engine.current_revision()+ }+/// Cache read; registers `op_id` as active when given.pub async fn read(&self,@@ -301,7 +330,7 @@ impl EngineHandle {document: String,fragment_name: String,keys: Vec<String>,- ) -> Result<Vec<cache_core::record_selection::SelectedRecord>, String> {+ ) -> Result<RecordSelectionResultWire, String> {let selection =RecordSelection::parse(&document, &fragment_name).map_err(|error| error.to_string())?;let keys: Vec<_> = keys.into_iter().map(|key| EntityKey(key.into())).collect();@@ -311,6 +340,10 @@ impl EngineHandle {.engine.read_records_by_keys(&selection, &keys).await+ .map(|result| RecordSelectionResultWire {+ revision: result.revision.to_string(),+ records: result.value,+ }).map_err(|error| error.to_string())}@@ -590,24 +623,38 @@ impl EngineHandle {}/// Evicts records by entity key; returns the affected registered op ids.- pub async fn invalidate(&self, keys: Vec<String>) -> Result<Vec<String>, String> {+ pub async fn invalidate(+ &self,+ keys: Vec<String>,+ ) -> Result<AffectedOperationsResultWire, String> {let keys: Vec<EntityKey<'static>> =keys.into_iter().map(|key| EntityKey(key.into())).collect();let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;- let affected = engine.invalidate_keys(keys.iter());- Ok(ops.names(affected))+ let affected = engine+ .invalidate_keys(keys.iter())+ .map_err(|error| error.to_string())?;+ Ok(AffectedOperationsResultWire {+ revision: affected.revision.to_string(),+ affected_ops: ops.names(affected.value),+ })}/// Deletes stale records from durable and hot storage and returns the/// registered operations that traversed them.- pub async fn delete_records(&self, keys: Vec<String>) -> Result<Vec<String>, String> {+ pub async fn delete_records(+ &self,+ keys: Vec<String>,+ ) -> Result<AffectedOperationsResultWire, String> {let keys: Vec<EntityKey<'static>> =keys.into_iter().map(|key| EntityKey(key.into())).collect();let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;let affected = engine.delete_keys(&keys).await.map_err(|e| e.to_string())?;- Ok(ops.names(affected))+ Ok(AffectedOperationsResultWire {+ revision: affected.revision.to_string(),+ affected_ops: ops.names(affected.value),+ })}/// Unregisters an operation (urql teardown).@@ -621,7 +668,7 @@ impl EngineHandle {}/// Drops all cached state (logout).- pub async fn clear(&self) -> Result<(), String> {+ pub async fn clear(&self) -> Result<CacheRevision, String> {let mut state = self.inner.lock().await;state.engine.clear().await.map_err(|e| e.to_string())}diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rsindex 489a7d7b1a..27d138a99d 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs@@ -211,7 +211,7 @@ fn explicit_key_selection_returns_native_cache_entities() {)).unwrap();assert_eq!(- records[0].record,+ records.records[0].record,serde_json::json!({"id": "doc-1", "name": "A note"}));}@@ -458,7 +458,7 @@ fn invalidate_reports_dependent_ops() {read(&handle, Some("client:1"));let affected = block_on(handle.invalidate(written.changed)).unwrap();- assert_eq!(affected, vec!["client:1".to_string()]);+ assert_eq!(affected.affected_ops, vec!["client:1".to_string()]);}#[test]diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rsindex 89015a7724..4a68c11000 100644--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs@@ -23,8 +23,9 @@ pub mod commands;mod engine;pub use engine::{- ClaimedMutationWire, EngineHandle, EnqueueOptimisticMutationResultWire,- InitialMutationClaimWire, ReadResultWire, WriteResultWire,+ AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,+ EnqueueOptimisticMutationResultWire, InitialMutationClaimWire, ReadResultWire,+ RecordSelectionResultWire, WriteResultWire,};/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose@@ -53,7 +54,10 @@ pub struct OpsAffectedEvent {/// Payload of [`CACHE_CHANGED_EVENT`].#[derive(Clone, Debug, Serialize)]#[serde(rename_all = "camelCase")]-pub struct CacheChangedEvent {}+pub struct CacheChangedEvent {+ /// Effective-view revision installed by the logical mutation.+ pub revision: String,+}#[derive(Clone, Debug, Serialize)]#[serde(rename_all = "camelCase")]@@ -101,8 +105,13 @@ fn emit_ops_affected<R: Runtime>(app: &AppHandle<R>, op_ids: &[String], keys: &[.ok();}-fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>) {- app.emit(CACHE_CHANGED_EVENT, CacheChangedEvent {})+fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str) {+ app.emit(+ CACHE_CHANGED_EVENT,+ CacheChangedEvent {+ revision: revision.to_owned(),+ },+ ).inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event")).ok();}diff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rsindex 5a155aba72..c5d0327261 100644--- a/apps/web/tauri/src-tauri/src/lib.rs+++ b/apps/web/tauri/src-tauri/src/lib.rs@@ -251,6 +251,7 @@ pub fn run() {.manage(IsIpad(is_ipad_device)).invoke_handler(tauri::generate_handler![graphql_cache_plugin::commands::graphql_cache_init,+ graphql_cache_plugin::commands::graphql_cache_current_revision,graphql_cache_plugin::commands::graphql_cache_read,graphql_cache_plugin::commands::graphql_cache_read_records_by_keys,graphql_cache_plugin::commands::graphql_cache_search,diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rsindex 839baa9a71..4195cb30b9 100644--- a/crates/client/cache-core/src/engine.rs+++ b/crates/client/cache-core/src/engine.rs@@ -2,6 +2,9 @@//! and dependency tracking together behind the API the hosts (wasm worker ///! Tauri) expose over RPC.+#[cfg(test)]+mod test;+use crate::denormalize::{DenormalizeError, ReadOutcome, RecordSource, denormalize_record,denormalize_with_entity_resolvers,@@ -31,6 +34,7 @@ use crate::queue::{use crate::record_selection::{MAX_RECORD_SELECTION_KEYS, RecordSelection, RecordSelectionError, SelectedRecord,};+use crate::revision::{CacheRevision, Revisioned};use crate::search::{SearchCursor, SearchDocument, SearchError, SearchPage, SearchProfile, SearchRequest,compare_recent, fuzzy_freshness_score, project_search_documents, validate_search_request,@@ -78,6 +82,8 @@ pub enum EngineError<S: std::error::Error + 'static> {InvalidOptimisticProjection(String),#[error("storage: {0}")]Storage(#[source] S),+ #[error("cache revision overflow")]+ RevisionOverflow,}/// Result of a cache read.@@ -116,6 +122,8 @@ pub struct QueryRegistration<'a> {/// Result of writing a network response.#[derive(Debug)]pub struct WriteResult {+ /// Revision installed after this logical cache mutation.+ pub revision: CacheRevision,/// Records whose contents changed.pub changed: BTreeSet<EntityKey<'static>>,/// Active operations depending on changed records (host re-executes@@ -222,6 +230,7 @@ pub const DEFAULT_HOT_CAPACITY: usize = 10_000;pub struct Engine<S: Storage> {storage: S,+ revision: CacheRevision,hot: LruCache<EntityKey<'static>, Record>,docs: HashMap<String, Document>,deps: DepIndex,@@ -242,6 +251,7 @@ impl<S: Storage> Engine<S> {pub fn with_capacity(storage: S, hot_capacity: usize) -> Self {Engine {storage,+ revision: CacheRevision::ZERO,hot: LruCache::new(NonZeroUsize::new(hot_capacity).expect("capacity > 0")),docs: HashMap::new(),deps: DepIndex::new(),@@ -252,6 +262,34 @@ impl<S: Storage> Engine<S> {}}+ /// Returns the current effective-view revision of this engine generation.+ pub fn current_revision(&self) -> CacheRevision {+ self.revision+ }++ fn ensure_revision_can_advance(&self) -> Result<(), EngineError<S::Error>> {+ self.revision+ .checked_successor()+ .map(|_| ())+ .ok_or(EngineError::RevisionOverflow)+ }++ fn advance_revision(&mut self) -> Result<CacheRevision, EngineError<S::Error>> {+ let next = self+ .revision+ .checked_successor()+ .ok_or(EngineError::RevisionOverflow)?;+ self.revision = next;+ Ok(next)+ }++ fn revisioned<T>(&self, value: T) -> Revisioned<T> {+ Revisioned {+ revision: self.revision,+ value,+ }+ }+/// Hydrates durable optimistic layers before the first operation. Queue/// order is the optimistic composition order. Relation recipes are/// reconstructed against the durable base and preceding layers.@@ -273,6 +311,7 @@ impl<S: Storage> Engine<S> {/// storage changes the queue. Returns operations whose effective view/// changed.pub async fn refresh_optimistic_queue(&mut self) -> Result<WriteResult, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;let queued = self.storage.load_mutation_queue()@@ -295,7 +334,9 @@ impl<S: Storage> Engine<S> {.filter(|key| before_all.get(key) != after.get(key)).collect();let affected_ops = self.deps.ops_for_keys(changed.iter());+ let revision = self.advance_revision()?;Ok(WriteResult {+ revision,changed,affected_ops,reset: false,@@ -549,7 +590,7 @@ impl<S: Storage> Engine<S> {&mut self,selection: &RecordSelection,keys: &[EntityKey<'static>],- ) -> Result<Vec<SelectedRecord>, EngineError<S::Error>> {+ ) -> Result<Revisioned<Vec<SelectedRecord>>, EngineError<S::Error>> {if keys.len() > MAX_RECORD_SELECTION_KEYS {return Err(RecordSelectionError::TooManyKeys {count: keys.len(),@@ -571,7 +612,7 @@ impl<S: Storage> Engine<S> {return Err(RecordSelectionError::InvalidKey.into());}if keys.is_empty() {- return Ok(Vec::new());+ return Ok(self.revisioned(Vec::new()));}self.hydrate_optimistic().await?;@@ -601,14 +642,15 @@ impl<S: Storage> Engine<S> {.project_record_batch(selection, candidates, &optimistic).await?;let mut projected: HashMap<_, _> = projected.into_iter().collect();- Ok(ordered_keys+ let records = ordered_keys.into_iter().filter_map(|record_key| {projected.remove(&record_key).map(|record| SelectedRecord { record_key, record })})- .collect())+ .collect();+ Ok(self.revisioned(records))}async fn project_record_batch(@@ -935,6 +977,7 @@ impl<S: Storage> Engine<S> {input: NetworkWrite<'_>,projections: Vec<ProjectionMutation>,) -> Result<WriteResult, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;let NetworkWrite {query,operation_name,@@ -983,7 +1026,7 @@ impl<S: Storage> Engine<S> {candidates.extend(updates.keys().cloned());let bases_before = self.load_bases(&candidates).await?;let before = effective_records(&bases_before, &self.optimistic, &candidates);- let changed = self.persist_updates(updates, projections).await?;+ let (changed, revision) = self.persist_updates(updates, projections).await?;if !self.optimistic.is_empty() {let queued = self@@ -1021,6 +1064,7 @@ impl<S: Storage> Engine<S> {}}Ok(WriteResult {+ revision,changed,affected_ops,reset,@@ -1100,7 +1144,7 @@ impl<S: Storage> Engine<S> {&mut self,updates: RecordUpdates,projections: Vec<ProjectionMutation>,- ) -> Result<BTreeSet<EntityKey<'static>>, EngineError<S::Error>> {+ ) -> Result<(BTreeSet<EntityKey<'static>>, CacheRevision), EngineError<S::Error>> {// Load current values (hot tier, then storage) so merges detect real// changes. Merges are staged in a plain map, NOT the LRU: a batch// larger than the hot capacity would otherwise evict its own@@ -1156,8 +1200,9 @@ impl<S: Storage> Engine<S> {.put_batch_with_projections(to_persist.clone(), projections).await.map_err(EngineError::Storage)?;+ let revision = self.advance_revision()?;self.update_loaded_search_catalogs(&to_persist);- Ok(changed)+ Ok((changed, revision))}/// Atomically enqueues a mutation together with its optimistic layer.@@ -1179,6 +1224,7 @@ impl<S: Storage> Engine<S> {input: BeginOptimisticWrite<'_>,projection_mutations: Vec<OptimisticProjectionMutation>,) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;let BeginOptimisticWrite {query,operation_name,@@ -1263,9 +1309,11 @@ impl<S: Storage> Engine<S> {if let Some(origin) = origin_op {affected_ops.remove(&origin);}+ let revision = self.advance_revision()?;Ok((id,WriteResult {+ revision,changed,affected_ops,reset: false,@@ -1380,6 +1428,7 @@ impl<S: Storage> Engine<S> {data: &Json,projections: Vec<ProjectionMutation>,) -> Result<WriteResult, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;self.hydrate_optimistic().await?;let index = self.optimistic@@ -1414,6 +1463,7 @@ impl<S: Storage> Engine<S> {{return Err(EngineError::StaleMutationClaim(transaction));}+ let revision = self.advance_revision()?;self.update_loaded_search_catalogs(&entries);for (key, record) in entries {self.hot.put(key, record);@@ -1438,6 +1488,7 @@ impl<S: Storage> Engine<S> {.collect();let affected_ops = self.deps.ops_for_keys(visible_changed.iter());Ok(WriteResult {+ revision,changed: durable_changed,affected_ops,reset: false,@@ -1452,6 +1503,7 @@ impl<S: Storage> Engine<S> {transaction: OptimisticTransactionId,claim: MutationClaimToken,) -> Result<WriteResult, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;self.hydrate_optimistic().await?;self.optimistic.iter()@@ -1468,6 +1520,7 @@ impl<S: Storage> Engine<S> {{return Err(EngineError::StaleMutationClaim(transaction));}+ let revision = self.advance_revision()?;let queued = self.storage.load_mutation_queue()@@ -1484,6 +1537,7 @@ impl<S: Storage> Engine<S> {.collect();let affected_ops = self.deps.ops_for_keys(visible_changed.iter());Ok(WriteResult {+ revision,changed: BTreeSet::new(),affected_ops,reset: false,@@ -1627,7 +1681,8 @@ impl<S: Storage> Engine<S> {/// Reacts to a reset performed by *another* engine instance sharing the/// same storage (cross-tab broadcast): drops all local in-memory state/// and returns every local active operation for re-execution.- pub fn external_reset(&mut self) -> BTreeSet<OpId> {+ pub fn external_reset(&mut self) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;self.hot.clear();self.docs.clear();self.optimistic.clear();@@ -1636,7 +1691,9 @@ impl<S: Storage> Engine<S> {// durable queue, so both identity and optimism must re-hydrate.self.optimistic_hydrated = false;self.identity = IdentityState::NotHydrated;- self.deps.all_ops()+ let affected = self.deps.all_ops();+ self.advance_revision()?;+ Ok(self.revisioned(affected))}/// Unregisters an active operation (urql teardown).@@ -1651,6 +1708,16 @@ impl<S: Storage> Engine<S> {pub fn invalidate_keys<'k>(&mut self,keys: impl IntoIterator<Item = &'k EntityKey<'static>>,+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;+ let affected = self.invalidate_keys_inner(keys);+ self.advance_revision()?;+ Ok(self.revisioned(affected))+ }++ fn invalidate_keys_inner<'k>(+ &mut self,+ keys: impl IntoIterator<Item = &'k EntityKey<'static>>,) -> BTreeSet<OpId> {let mut affected = BTreeSet::new();for key in keys {@@ -1673,7 +1740,8 @@ impl<S: Storage> Engine<S> {pub async fn delete_keys(&mut self,keys: &[EntityKey<'static>],- ) -> Result<BTreeSet<OpId>, EngineError<S::Error>> {+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;let affected = self.deps.ops_for_keys(keys.iter());self.storage.delete_batch(keys)@@ -1685,12 +1753,14 @@ impl<S: Storage> Engine<S> {catalog.remove(key);}}- Ok(affected)+ self.advance_revision()?;+ Ok(self.revisioned(affected))}/// Drops all cached state (for example, on logout), including any pending/// optimistic layers.- pub async fn clear(&mut self) -> Result<(), EngineError<S::Error>> {+ pub async fn clear(&mut self) -> Result<CacheRevision, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;self.hot.clear();self.optimistic.clear();self.optimistic_hydrated = true;@@ -1698,7 +1768,8 @@ impl<S: Storage> Engine<S> {self.deps = DepIndex::new();// The wipe below removes the binding record too.self.identity = IdentityState::Missing;- self.storage.clear().await.map_err(EngineError::Storage)+ self.storage.clear().await.map_err(EngineError::Storage)?;+ self.advance_revision()}pub fn active_ops(&self) -> usize {@@ -1749,16 +1820,18 @@ impl<S: PredicateIndexStorage> Engine<S> {entries: Vec<(EntityKey<'static>, Record)>,projections: Vec<ProjectionMutation>,) -> Result<WriteResult, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;let mut updates = RecordUpdates::new();for (key, record) in entries {updates.entry(key).or_default().merge(record);}- let changed = self.persist_updates(updates, projections).await?;+ let (changed, revision) = self.persist_updates(updates, projections).await?;let mut affected_ops = self.deps.ops_for_keys(changed.iter());if let Some(origin_op) = origin_op {affected_ops.remove(&origin_op);}Ok(WriteResult {+ revision,changed,affected_ops,reset: false,@@ -1770,11 +1843,30 @@ impl<S: PredicateIndexStorage> Engine<S> {pub async fn mark_projections_incomplete(&mut self,projections: Vec<ProjectionMutation>,- ) -> Result<(), EngineError<S::Error>> {+ ) -> Result<CacheRevision, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;self.storage.put_batch_with_projections(Vec::new(), projections).await- .map_err(EngineError::Storage)+ .map_err(EngineError::Storage)?;+ self.advance_revision()+ }++ /// Marks generic projections incomplete and invalidates normalized hot-tier records+ /// as one externally observed logical view mutation.+ pub async fn invalidate_keys_with_projections(+ &mut self,+ keys: &[EntityKey<'static>],+ projections: Vec<ProjectionMutation>,+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;+ self.storage+ .put_batch_with_projections(Vec::new(), projections)+ .await+ .map_err(EngineError::Storage)?;+ let affected = self.invalidate_keys_inner(keys.iter());+ self.advance_revision()?;+ Ok(self.revisioned(affected))}/// Delete normalized records and generic projections in one storage transaction.@@ -1782,7 +1874,8 @@ impl<S: PredicateIndexStorage> Engine<S> {&mut self,keys: &[EntityKey<'static>],projection_keys: &[PredicateRecordKey],- ) -> Result<BTreeSet<OpId>, EngineError<S::Error>> {+ ) -> Result<Revisioned<BTreeSet<OpId>>, EngineError<S::Error>> {+ self.ensure_revision_can_advance()?;let affected = self.deps.ops_for_keys(keys.iter());self.storage.delete_batch_with_projections(keys, projection_keys)@@ -1794,13 +1887,22 @@ impl<S: PredicateIndexStorage> Engine<S> {catalog.remove(key);}}- Ok(affected)+ self.advance_revision()?;+ Ok(self.revisioned(affected))}/// Execute a complete generic exact-index query over authoritative and optimistic projections.pub async fn query_predicate_index(&mut self,query: &ValidatedIndexQuery,+ ) -> Result<Revisioned<PredicateQueryResult>, EngineError<S::Error>> {+ let value = self.query_predicate_index_value(query).await?;+ Ok(self.revisioned(value))+ }++ async fn query_predicate_index_value(+ &mut self,+ query: &ValidatedIndexQuery,) -> Result<PredicateQueryResult, EngineError<S::Error>> {self.hydrate_optimistic().await?;let projection_mutations = selfdiff --git a/crates/client/cache-core/src/engine/test.rs b/crates/client/cache-core/src/engine/test.rsnew file mode 100644index 0000000000..69c89cc64e--- /dev/null+++ b/crates/client/cache-core/src/engine/test.rs@@ -0,0 +1,15 @@+use super::*;+use crate::store::InMemoryStorage;++#[test]+fn revision_overflow_is_rejected_without_mutating_storage() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ engine.revision = u64::MAX.to_string().parse().unwrap();++ let result = engine.clear().await;+ assert!(matches!(result, Err(EngineError::RevisionOverflow)));+ assert_eq!(engine.current_revision().to_string(), u64::MAX.to_string());+ assert!(engine.storage().is_empty());+ });+}diff --git a/crates/client/cache-core/src/lib.rs b/crates/client/cache-core/src/lib.rsindex 947c8fd461..c7ae9dfa71 100644--- a/crates/client/cache-core/src/lib.rs+++ b/crates/client/cache-core/src/lib.rs@@ -16,6 +16,7 @@ pub mod query_inspection;mod query_path;pub mod queue;pub mod record_selection;+pub mod revision;pub mod search;pub mod store;pub mod value;diff --git a/crates/client/cache-core/src/revision.rs b/crates/client/cache-core/src/revision.rsnew file mode 100644index 0000000000..4efa8c8fd0--- /dev/null+++ b/crates/client/cache-core/src/revision.rs@@ -0,0 +1,83 @@+//! In-memory cache revision values and revision-qualified observations.++#[cfg(test)]+mod test;++use std::fmt;+use std::ops::Deref;+use std::str::FromStr;+use thiserror::Error;++/// Opaque revision of one live cache engine's effective view.+///+/// Revisions are meaningful only within one engine generation. Consumers+/// should compare them for equality and must discard them when the engine is+/// replaced.+#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]+pub struct CacheRevision(u64);++impl CacheRevision {+ /// The initial revision of every newly created engine.+ pub const ZERO: Self = Self(0);++ pub(crate) fn checked_successor(self) -> Option<Self> {+ self.0.checked_add(1).map(Self)+ }+}++impl fmt::Display for CacheRevision {+ fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {+ self.0.fmt(formatter)+ }+}++/// Error returned when parsing a cache revision from its wire representation.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Error)]+pub enum ParseCacheRevisionError {+ /// The input was not a canonical unsigned decimal integer.+ #[error("cache revision must be a canonical unsigned decimal integer")]+ Invalid,+ /// The input exceeded the unsigned 64-bit revision range.+ #[error("cache revision exceeds the unsigned 64-bit range")]+ Overflow,+}++impl FromStr for CacheRevision {+ type Err = ParseCacheRevisionError;++ fn from_str(value: &str) -> Result<Self, Self::Err> {+ if value.is_empty()+ || (value.len() > 1 && value.starts_with('0'))+ || !value.bytes().all(|byte| byte.is_ascii_digit())+ {+ return Err(ParseCacheRevisionError::Invalid);+ }+ value+ .parse::<u64>()+ .map(Self)+ .map_err(|_| ParseCacheRevisionError::Overflow)+ }+}++/// A value observed from one exact cache-engine revision.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct Revisioned<T> {+ /// Revision installed in the engine when `value` was observed.+ pub revision: CacheRevision,+ /// The observed value.+ pub value: T,+}++impl<T> Deref for Revisioned<T> {+ type Target = T;++ fn deref(&self) -> &Self::Target {+ &self.value+ }+}++impl<T: PartialEq> PartialEq<T> for Revisioned<T> {+ fn eq(&self, other: &T) -> bool {+ self.value.eq(other)+ }+}diff --git a/crates/client/cache-core/src/revision/test.rs b/crates/client/cache-core/src/revision/test.rsnew file mode 100644index 0000000000..3f73a75384--- /dev/null+++ b/crates/client/cache-core/src/revision/test.rs@@ -0,0 +1,20 @@+use super::*;++#[test]+fn decimal_wire_format_is_canonical_and_bounded() {+ assert_eq!(CacheRevision::ZERO.to_string(), "0");+ assert_eq!(+ "18446744073709551615"+ .parse::<CacheRevision>()+ .unwrap()+ .to_string(),+ u64::MAX.to_string()+ );++ for invalid in ["", "-1", "+1", "01", " 1", "1.0", "18446744073709551616"] {+ assert!(+ invalid.parse::<CacheRevision>().is_err(),+ "accepted {invalid:?}"+ );+ }+}diff --git a/crates/client/cache-core/tests/engine.rs b/crates/client/cache-core/tests/engine.rsindex 8756a6d83d..dc97e76359 100644--- a/crates/client/cache-core/tests/engine.rs+++ b/crates/client/cache-core/tests/engine.rs@@ -2,6 +2,7 @@//! storage, dependency-driven re-execution, teardown, clear.use cache_core::engine::{Engine, NetworkWrite, QueryRegistration, ReadResult};+use cache_core::revision::CacheRevision;use cache_core::store::InMemoryStorage;use pollster::block_on;use serde_json::{Value as Json, json};@@ -130,6 +131,72 @@ fn consuming_engine_returns_exclusively_owned_storage() {assert!(storage.is_empty());}+#[test]+fn revision_tracks_logical_mutations_only_within_one_engine_generation() {+ block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ assert_eq!(engine.current_revision(), CacheRevision::ZERO);++ let data = page(&[("doc-1", "A")]);+ let first = engine+ .write_query(None, QUERY, Some("Soup"), &vars(10), &data, None)+ .await+ .unwrap();+ assert_eq!(first.revision.to_string(), "1");+ assert_eq!(engine.current_revision(), first.revision);++ engine+ .read_query(None, QUERY, Some("Soup"), &vars(10))+ .await+ .unwrap();+ assert_eq!(engine.current_revision(), first.revision);++ // Conservative advancement: an idempotent logical write still makes+ // older observations stale.+ let second = engine+ .write_query(None, QUERY, Some("Soup"), &vars(10), &data, None)+ .await+ .unwrap();+ assert!(second.changed.is_empty());+ assert_eq!(second.revision.to_string(), "2");++ let storage = engine.storage().clone();+ let mut replacement = Engine::new(storage);+ assert_eq!(replacement.current_revision(), CacheRevision::ZERO);+ assert!(matches!(+ replacement+ .read_query(None, QUERY, Some("Soup"), &vars(10))+ .await+ .unwrap(),+ ReadResult::Hit { .. }+ ));+ assert_eq!(replacement.current_revision(), CacheRevision::ZERO);++ let cleared = replacement.clear().await.unwrap();+ assert_eq!(cleared.to_string(), "1");+ assert_eq!(replacement.current_revision(), cleared);+ });+}++#[test]+fn failed_commands_do_not_advance_revision() {+ block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ let result = engine+ .write_query(+ None,+ "query Broken {",+ Some("Broken"),+ &serde_json::Map::new(),+ &json!({}),+ None,+ )+ .await;+ assert!(result.is_err());+ assert_eq!(engine.current_revision(), CacheRevision::ZERO);+ });+}+#[test]fn miss_then_write_then_hit() {block_on(async {@@ -658,7 +725,7 @@ fn identity_witness_wipes_on_user_change() {assert_eq!(data["user"]["id"], serde_json::json!("user-2"));// external_reset drops local state and reports all local ops.- let ops = engine.external_reset();+ let ops = engine.external_reset().unwrap();assert!(ops.contains(&1) && ops.contains(&2));});}diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rsindex e65fd95459..c0e1f32fda 100644--- a/crates/client/cache-core/tests/optimistic.rs+++ b/crates/client/cache-core/tests/optimistic.rs@@ -13,6 +13,7 @@ use cache_core::store::{InMemoryStorage, Storage};use cache_core::value::{CacheValue, EntityKey, Record};use pollster::block_on;use serde_json::{Value as Json, json};+use std::sync::atomic::{AtomicBool, Ordering};const QUERY: &str = r#"query Soup($input: SoupInput!) {@@ -58,6 +59,7 @@ const PROPERTY_KEY: &str = "GraphqlProperty:prop-1";struct ClaimFailingStorage {inner: InMemoryStorage,fail_next_claim: bool,+ fail_next_queue_load: AtomicBool,}impl ClaimFailingStorage {@@ -65,8 +67,21 @@ impl ClaimFailingStorage {Self {inner: InMemoryStorage::new(),fail_next_claim: true,+ fail_next_queue_load: AtomicBool::new(false),}}++ fn reconciliation_failing() -> Self {+ Self {+ inner: InMemoryStorage::new(),+ fail_next_claim: false,+ fail_next_queue_load: AtomicBool::new(false),+ }+ }++ fn fail_next_queue_load(&self) {+ self.fail_next_queue_load.store(true, Ordering::Relaxed);+ }}impl Storage for ClaimFailingStorage {@@ -109,6 +124,11 @@ impl Storage for ClaimFailingStorage {}async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {+ if self.fail_next_queue_load.swap(false, Ordering::Relaxed) {+ return Err(std::io::Error::other(+ "injected reconciliation queue load failure",+ ));+ }Ok(self.inner.load_mutation_queue().await.unwrap())}@@ -254,6 +274,53 @@ async fn engine_with_base(display_name: &str, value: &str) -> Engine<InMemoryStoengine}+async fn reconciliation_engine() -> (Engine<ClaimFailingStorage>, MutationId) {+ let mut engine = Engine::new(ClaimFailingStorage::reconciliation_failing());+ engine+ .write_query(+ None,+ QUERY,+ Some("Soup"),+ &query_vars(),+ &soup_page("Status", "todo"),+ None,+ )+ .await+ .unwrap();+ let (transaction, _) = engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &mutation_vars("doing"),+ data: &mutation_response("Status", "doing"),+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 123,+ },+ )+ .await+ .unwrap();+ (engine, transaction)+}++async fn claim_reconciliation_head(engine: &mut Engine<ClaimFailingStorage>) -> MutationClaimToken {+ let claimed = engine+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 123,+ lease_expires_at_ms: 1_123,+ })+ .await+ .unwrap()+ .expect("queue head");+ MutationClaimToken {+ owner: "runner".into(),+ generation: claimed.lease_generation,+ }+}+async fn read_hit(engine: &mut Engine<InMemoryStorage>, op: Option<u64>) -> Json {match engine.read_query(op, QUERY, Some("Soup"), &query_vars())@@ -529,6 +596,11 @@ fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {.await.unwrap();+ assert_eq!(+ result.write_result.revision,+ engine.current_revision(),+ "the failed lease claim must not add a second revision"+ );assert!(matches!(result.initial_claim,InitialClaimOutcome::Failed(EngineError::Storage(ref error))@@ -550,6 +622,63 @@ fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {});}+#[test]+fn durable_mutations_advance_revision_before_reconciliation() {+ block_on(async {+ let (mut write_engine, _) = reconciliation_engine().await;+ write_engine.storage().fail_next_queue_load();+ let write_result = write_engine+ .write_query(+ None,+ QUERY,+ Some("Soup"),+ &query_vars(),+ &soup_page("Status (server)", "done"),+ None,+ )+ .await;+ assert!(matches!(+ write_result,+ Err(EngineError::Storage(ref error))+ if error.to_string() == "injected reconciliation queue load failure"+ ));+ assert_eq!(write_engine.current_revision().to_string(), "3");++ let (mut commit_engine, transaction) = reconciliation_engine().await;+ let claim = claim_reconciliation_head(&mut commit_engine).await;+ commit_engine.storage().fail_next_queue_load();+ let commit_result = commit_engine+ .commit_optimistic_write(+ transaction,+ claim,+ MUTATION,+ Some("SetEntityProperty"),+ &mutation_vars("done"),+ &mutation_response("Status (server)", "done"),+ )+ .await;+ assert!(matches!(+ commit_result,+ Err(EngineError::Storage(ref error))+ if error.to_string() == "injected reconciliation queue load failure"+ ));+ assert_eq!(commit_engine.current_revision().to_string(), "3");++ let (mut rollback_engine, transaction) = reconciliation_engine().await;+ let claim = claim_reconciliation_head(&mut rollback_engine).await;+ rollback_engine.storage().fail_next_queue_load();+ let rollback_result = rollback_engine+ .rollback_optimistic_write(transaction, claim)+ .await;+ assert!(matches!(+ rollback_result,+ Err(EngineError::Storage(ref error))+ if error.to_string() == "injected reconciliation queue load failure"+ ));+ assert_eq!(rollback_engine.current_revision().to_string(), "3");+ });+}+#[test]fn claimed_success_atomically_commits_real_response() {block_on(async {@@ -732,6 +861,7 @@ fn stale_claim_cannot_settle_mutation() {).await.unwrap();+ let revision_before_stale_settlement = engine.current_revision();let error = engine.rollback_optimistic_write(transaction,@@ -743,6 +873,7 @@ fn stale_claim_cannot_settle_mutation() {.await.unwrap_err();assert!(matches!(error, EngineError::StaleMutationClaim(id) if id == transaction));+ assert_eq!(engine.current_revision(), revision_before_stale_settlement);assert_eq!(engine.storage().load_mutation_queue().await.unwrap().len(),1diff --git a/crates/client/cache-core/tests/predicate.rs b/crates/client/cache-core/tests/predicate.rsindex 37dda5dd9b..aaaff82ef9 100644--- a/crates/client/cache-core/tests/predicate.rs+++ b/crates/client/cache-core/tests/predicate.rs@@ -147,13 +147,12 @@ fn replacement_removes_stale_facts_and_incomplete_states_fall_back() {).await.unwrap();- assert_eq!(- engine- .query_predicate_index(&query("owner-1"))- .await- .unwrap(),- PredicateQueryResult::Complete(vec![record_key()])- );+ let observed = engine+ .query_predicate_index(&query("owner-1"))+ .await+ .unwrap();+ assert_eq!(observed.revision, engine.current_revision());+ assert_eq!(observed, PredicateQueryResult::Complete(vec![record_key()]));engine.put_records_with_projections(diff --git a/crates/client/cache-core/tests/record_selection.rs b/crates/client/cache-core/tests/record_selection.rsindex 263a4e6fe6..fb4f287f04 100644--- a/crates/client/cache-core/tests/record_selection.rs+++ b/crates/client/cache-core/tests/record_selection.rs@@ -101,6 +101,8 @@ fn projects_cold_links_and_skips_incomplete_explicit_keys() {).await.unwrap();+ assert_eq!(selected.revision, engine.current_revision());+ assert_eq!(selected.revision.to_string(), "0");assert_eq!(selected.len(), 2);assert_eq!(selected[0].record["documentId"], json!("a"));assert_eq!(diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rsindex 0bc7990978..f2b8854221 100644--- a/crates/client/cache-wasm/src/shell.rs+++ b/crates/client/cache-wasm/src/shell.rs@@ -3,7 +3,7 @@ use cache_core::codec::cache_database_name;use cache_core::deps::OpId;use cache_core::engine::{BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, NetworkWrite,- QueryRegistration, ReadResult,+ QueryRegistration, ReadResult, WriteResult,};use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};@@ -140,6 +140,7 @@ struct JsQueryRegistration {#[derive(Serialize)]#[serde(rename_all = "camelCase")]struct JsWriteResult {+ revision: String,changed: Vec<String>,affected_ops: Vec<String>,reset: bool,@@ -149,6 +150,7 @@ struct JsWriteResult {#[derive(Serialize)]#[serde(rename_all = "camelCase")]struct JsHydrationWriteResult {+ revision: String,changed: Vec<String>,affected_ops: Vec<String>,reset: bool,@@ -165,6 +167,7 @@ struct JsInspectionPathSegment {#[serde(rename_all = "camelCase")]struct JsEnqueueOptimisticMutationResult {transaction_id: String,+ revision: String,changed: Vec<String>,affected_ops: Vec<String>,reset: bool,@@ -268,9 +271,48 @@ struct JsEntityFilterRequest {#[derive(Serialize)]#[serde(tag = "kind", rename_all = "kebab-case")]enum JsEntityFilterResult {- Complete { keys: Vec<String>, optimistic: bool },+ Complete {+ revision: String,+ keys: Vec<String>,+ optimistic: bool,+ },Unsupported,- Incomplete,+ Incomplete {+ revision: String,+ },+}++#[derive(Serialize)]+#[serde(rename_all = "camelCase")]+struct JsRecordSelectionResult {+ revision: String,+ records: Vec<cache_core::record_selection::SelectedRecord>,+}++#[derive(Serialize)]+#[serde(rename_all = "camelCase")]+struct JsAffectedOperationsResult {+ revision: String,+ affected_ops: Vec<String>,+}++#[derive(Serialize)]+struct JsRevisionResult {+ revision: String,+}++fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {+ JsWriteResult {+ revision: result.revision.to_string(),+ changed: result+ .changed+ .into_iter()+ .map(|key| key.0.into_owned())+ .collect(),+ affected_ops: ops.names(result.affected_ops),+ reset: result.reset,+ revalidations: result.revalidations,+ }}struct CacheState {@@ -737,6 +779,17 @@ impl CacheEngine {})}+ /// Returns the current in-memory cache revision as an unsigned decimal string.+ #[wasm_bindgen(js_name = currentRevision)]+ pub fn current_revision(&self) -> js_sys::Promise {+ let state = self.state.clone();+ future_to_promise(async move {+ let mut state = state.lock().await;+ let revision = state.engine_mut()?.current_revision();+ Ok(JsValue::from_str(&revision.to_string()))+ })+ }+/// Returns the opaque identity bound to this cache, or `null` when no/// identity-bearing response has been stored yet.#[wasm_bindgen(js_name = boundIdentity)]@@ -809,7 +862,10 @@ impl CacheEngine {.read_records_by_keys(&selection, &keys).await;let records = state.engine_result(result)?;- to_js(&records)+ to_js(&JsRecordSelectionResult {+ revision: records.revision.to_string(),+ records: records.value,+ })})}@@ -848,8 +904,11 @@ impl CacheEngine {SoupFilterCompileOutcome::Unsupported => JsEntityFilterResult::Unsupported,SoupFilterCompileOutcome::Supported(query) => {let result = state.engine_mut()?.query_predicate_index(&query).await;- match state.engine_result(result)? {+ let result = state.engine_result(result)?;+ let revision = result.revision.to_string();+ match result.value {PredicateQueryResult::Complete(keys) => JsEntityFilterResult::Complete {+ revision,keys: keys.into_iter().map(|key| key.as_str().to_owned())@@ -857,13 +916,16 @@ impl CacheEngine {optimistic: false,},PredicateQueryResult::Optimistic(keys) => JsEntityFilterResult::Complete {+ revision,keys: keys.into_iter().map(|key| key.as_str().to_owned()).collect(),optimistic: true,},- PredicateQueryResult::Incomplete => JsEntityFilterResult::Incomplete,+ PredicateQueryResult::Incomplete => {+ JsEntityFilterResult::Incomplete { revision }+ }}}};@@ -925,16 +987,7 @@ impl CacheEngine {).await;let result = state.engine_result(result)?;- to_js(&JsWriteResult {- changed: result- .changed- .into_iter()- .map(|key| key.0.into_owned())- .collect(),- affected_ops: ops.borrow().names(result.affected_ops),- reset: result.reset,- revalidations: result.revalidations,- })+ to_js(&js_write_result(result, &ops.borrow()))})}@@ -970,6 +1023,7 @@ impl CacheEngine {.await;let result = state.engine_result(result)?;to_js(&JsHydrationWriteResult {+ revision: result.write_result.revision.to_string(),changed: result.write_result.changed@@ -1055,6 +1109,7 @@ impl CacheEngine {};to_js(&JsEnqueueOptimisticMutationResult {transaction_id: result.transaction_id.to_string(),+ revision: result.write_result.revision.to_string(),changed: result.write_result.changed@@ -1207,16 +1262,7 @@ impl CacheEngine {).await;let result = state.engine_result(result)?;- to_js(&JsWriteResult {- changed: result- .changed- .into_iter()- .map(|key| key.0.into_owned())- .collect(),- affected_ops: ops.borrow().names(result.affected_ops),- reset: result.reset,- revalidations: result.revalidations,- })+ to_js(&js_write_result(result, &ops.borrow()))})}@@ -1244,16 +1290,7 @@ impl CacheEngine {.rollback_optimistic_write(transaction, claim).await;let result = state.engine_result(result)?;- to_js(&JsWriteResult {- changed: result- .changed- .into_iter()- .map(|key| key.0.into_owned())- .collect(),- affected_ops: ops.borrow().names(result.affected_ops),- reset: result.reset,- revalidations: result.revalidations,- })+ to_js(&js_write_result(result, &ops.borrow()))})}@@ -1268,17 +1305,17 @@ impl CacheEngine {let mut state = state.lock().await;state.ensure_callable()?;let projections = dirty_projection_mutations(&keys);- if !projections.is_empty() {- let result = state- .engine_mut()?- .mark_projections_incomplete(projections)- .await;- state.engine_result(result)?;- }let keys: Vec<EntityKey<'static>> =keys.into_iter().map(|key| EntityKey(key.into())).collect();- let affected = state.engine_mut()?.invalidate_keys(keys.iter());- to_js(&ops.borrow().names(affected))+ let result = state+ .engine_mut()?+ .invalidate_keys_with_projections(&keys, projections)+ .await;+ let affected = state.engine_result(result)?;+ to_js(&JsAffectedOperationsResult {+ revision: affected.revision.to_string(),+ affected_ops: ops.borrow().names(affected.value),+ })})}@@ -1302,7 +1339,10 @@ impl CacheEngine {.delete_keys_with_projections(&keys, &projection_keys).await;let affected = state.engine_result(result)?;- to_js(&ops.borrow().names(affected))+ to_js(&JsAffectedOperationsResult {+ revision: affected.revision.to_string(),+ affected_ops: ops.borrow().names(affected.value),+ })})}@@ -1316,16 +1356,7 @@ impl CacheEngine {let mut state = state.lock().await;let result = state.engine_mut()?.refresh_optimistic_queue().await;let result = state.engine_result(result)?;- to_js(&JsWriteResult {- changed: result- .changed- .into_iter()- .map(|key| key.0.into_owned())- .collect(),- affected_ops: ops.borrow().names(result.affected_ops),- reset: result.reset,- revalidations: result.revalidations,- })+ to_js(&js_write_result(result, &ops.borrow()))})}@@ -1338,8 +1369,12 @@ impl CacheEngine {let ops = self.ops.clone();future_to_promise(async move {let mut state = state.lock().await;- let affected = state.engine_mut()?.external_reset();- to_js(&ops.borrow().names(affected))+ let result = state.engine_mut()?.external_reset();+ let affected = state.engine_result(result)?;+ to_js(&JsAffectedOperationsResult {+ revision: affected.revision.to_string(),+ affected_ops: ops.borrow().names(affected.value),+ })})}@@ -1364,8 +1399,10 @@ impl CacheEngine {future_to_promise(async move {let mut state = state.lock().await;let result = state.engine_mut()?.clear().await;- state.engine_result(result)?;- Ok(JsValue::UNDEFINED)+ let revision = state.engine_result(result)?;+ to_js(&JsRevisionResult {+ revision: revision.to_string(),+ })})}diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rsindex fef6a162b6..9bb47bfbe0 100644--- a/crates/client/cache-wasm/src/shell/test.rs+++ b/crates/client/cache-wasm/src/shell/test.rs@@ -30,10 +30,36 @@ const PROPERTY_MUTATION: &str = r#"mutation SetEntityProperty($input: SetEntityPsetEntityProperty(input: $input) { id displayName }}"#;+const SOUP_UPDATES_SUBSCRIPTION: &str = r#"subscription SoupUpdates {+ soupUpdates {+ __typename+ ... on SoupUpdated {+ item {+ __typename+ id+ displayName+ ... on GraphqlSoupDocument {+ ownerId+ projectId+ fileType+ createdAt+ updatedAt+ }+ }+ }+ }+}"#;+const RECORD_FRAGMENT: &str = r#"fragment CachedDocument on GraphqlSoupDocument {id}"#;+const REALTIME_DOCUMENT_FRAGMENT: &str = r#"fragment RealtimeDocument on GraphqlSoupDocument {+ id+ displayName+ ownerId+}"#;+fn js(json: serde_json::Value) -> JsValue {use serde::Serialize;json.serialize(&serde_wasm_bindgen::Serializer::json_compatible())@@ -126,6 +152,45 @@ fn mutation_variables() -> serde_json::Value {}})}+fn realtime_document_data(document_id: &str) -> serde_json::Value {+ serde_json::json!({+ "soupUpdates": [{+ "__typename": "SoupUpdated",+ "item": {+ "__typename": "GraphqlSoupDocument",+ "id": document_id,+ "displayName": "Realtime document",+ "ownerId": "macro|[email protected]",+ "projectId": null,+ "fileType": "md",+ "createdAt": "2026-01-01T00:00:00.000Z",+ "updatedAt": "2026-01-02T00:00:00.000Z"+ }+ }]+ })+}++fn exact_document_filter(document_id: &str) -> serde_json::Value {+ const NIL_ID: &str = "00000000-0000-0000-0000-000000000000";+ serde_json::json!({+ "filters": {+ "calendarEventFilter": { "literal": { "id": NIL_ID } },+ "documentFilter": { "literal": { "id": document_id } },+ "projectFilter": { "literal": { "projectIdSelf": NIL_ID } },+ "chatFilter": { "literal": { "chatId": NIL_ID } },+ "emailFilter": { "tree": { "literal": { "threadId": NIL_ID } } },+ "channelFilter": { "literal": { "channelId": NIL_ID } },+ "channelThreadFilter": { "literal": { "threadId": NIL_ID } },+ "callFilter": { "literal": { "callId": NIL_ID } },+ "crmCompanyFilter": { "literal": { "id": NIL_ID } },+ "foreignEntityFilter": { "literal": { "id": NIL_ID } }+ },+ "sortMethod": "UPDATED_AT",+ "sortDirection": "DESC",+ "limit": 20+ })+}+async fn fresh_engine(scope: &str) -> CacheEngine {destroy_cache(scope.into()).await@@ -253,6 +318,54 @@ async fn operations_preserve_js_boundary_interner_and_ordering() {close_and_destroy(&engine, SCOPE).await;}+#[wasm_bindgen_test(async)]+async fn realtime_soup_items_are_locally_filterable_without_a_query_fetch() {+ const SCOPE: &str = "cache-wasm-realtime-local-filter";+ const DOCUMENT_ID: &str = "00000000-0000-0000-0000-000000000001";+ let engine = fresh_engine(SCOPE).await;++ resolved(engine.write_query(+ write_context(None),+ SOUP_UPDATES_SUBSCRIPTION.into(),+ Some("SoupUpdates".into()),+ js(serde_json::json!({})),+ js(realtime_document_data(DOCUMENT_ID)),+ None,+ ))+ .await;++ // This asks only the local predicate index; no Soup query response has+ // been fetched or written before the realtime item is returned.+ let filtered: serde_json::Value =+ from_js(resolved(engine.entity_filter(js(exact_document_filter(DOCUMENT_ID)))).await);+ assert_eq!(+ filtered,+ serde_json::json!({+ "kind": "complete",+ "revision": "1",+ "keys": [format!("GraphqlSoupDocument:{DOCUMENT_ID}")],+ "optimistic": false+ })+ );++ let selected: serde_json::Value = from_js(+ resolved(engine.read_records_by_keys(+ REALTIME_DOCUMENT_FRAGMENT.into(),+ "RealtimeDocument".into(),+ js(filtered["keys"].clone()),+ ))+ .await,+ );+ assert_eq!(selected["revision"], "1");+ assert_eq!(selected["records"][0]["record"]["id"], DOCUMENT_ID);+ assert_eq!(+ selected["records"][0]["record"]["displayName"],+ "Realtime document"+ );++ close_and_destroy(&engine, SCOPE).await;+}+#[wasm_bindgen_test(async)]async fn entity_resolvers_cross_the_js_boundary() {const SCOPE: &str = "cache-wasm-wp07-entity-resolver";