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/persist optimitic records (#4826)
Sean Ayeeb4d49390267
diff --git a/apps/web/docs/graphql-normalized-cache-plan.md b/apps/web/docs/graphql-normalized-cache-plan.mdindex cb5a72cefe..65fddc06b7 100644--- a/apps/web/docs/graphql-normalized-cache-plan.md+++ b/apps/web/docs/graphql-normalized-cache-plan.md@@ -65,8 +65,8 @@ entire cache in browser memory. With 10s of thousands of cached objectsopaque session tag compared against the binding stored in the samedatabase (`__meta:identity`), so compare-and-wipe is atomic with thetriggering write (no stale-in-flight-write races). A mismatch wipes and- rebinds (“silent restart”), all active operations re-execute, and other- engine instances get a `reset` broadcast. Eager path: clear on logout.+ rebinds (“silent restart”) and all active operations re-execute. Eager+ path: clear on logout.Discard on schema/format mismatch (cache is disposable, rebuild fromnetwork).@@ -78,9 +78,11 @@ entire cache in browser memory. With 10s of thousands of cached objects`GraphqlSoupChannelMessage.id`); the build fails on malformed shapes.12. **Native-testable core** — the Rust engine is a pure crate (`cargo test`,no wasm) with storage/clock behind traits.-13. **Future** — mutations don't exist in the schema yet; design leaves room- for optimistic updates, mutation-driven invalidation, and an offline- mutation queue, but none of that is in scope now.+13. **Durable optimistic mutations** — optimistic GraphQL mutations are+ persisted with their replay request, restored across restarts, and applied+ strictly in enqueue order. Retryability is decided by an exchange callback;+ retryable failures retain their optimistic layer. Each queued network+ attempt has a one-minute timeout, comfortably inside its five-minute lease.### Open questions@@ -125,11 +127,11 @@ One Rust core engine, two hosts:│ module in a worker; │ │ Tauri host process (Rust); ││ IndexedDB via the `idb` crate │ │ no webview storage ever ││ (storage entirely in Rust) │ │ • naturally shared across ALL │-│ • SharedWorker where available│ │ webviews/windows │-│ (single engine instance) │ │ • SQLite (or fs) storage │-│ • fallback: worker-per-tab + │ │ • glue over invoke + channels/ │-│ Web Locks write serializing │ │ events │-│ + BroadcastChannel fanout │ │ │+│ • SharedWorker: one engine │ │ webviews/windows │+│ shared by every browser tab │ │ • SQLite (or fs) storage │+│ • no SharedWorker: storage- │ │ • glue over invoke + channels/ │+│ free no-op cache host │ │ events │+│ │ │ │└───────────────┬───────────────┘ └────────────────┬────────────────┘└──────────────────┬──────────────────────┘▼@@ -156,8 +158,9 @@ One Rust core engine, two hosts:### 4.2 Multi-consumer strategy (browser only)**Decision: IndexedDB-backed persistence via the [`idb`-crate](https://docs.rs/idb/latest/idb/), engine in a worker that may or may-not be a SharedWorker. OPFS is dropped.**+crate](https://docs.rs/idb/latest/idb/), with one engine in a SharedWorker.+Browsers without SharedWorker support use a storage-free no-op cache host.+OPFS is dropped.**Rationale (see Appendix A):@@ -167,32 +170,27 @@ Rationale (see Appendix A):- IDB point-reads measured *faster* than OPFS sync 4 KiB reads in the probe(0.35 ms vs 2 ms avg), and batched writes (119 ms / 1000 records / txn)are fine for our write rates.-- IDB is available in window, dedicated workers and SharedWorker, and- tolerates concurrent instances — so the same backend works in every- topology.+- IDB is available in SharedWorker on supported browsers.- Using the `idb` Rust crate keeps the entire storage layer inside the wasmmodule (no JS-callback storage shim; JS glue is transport only).Topology:-- **Preferred: SharedWorker** hosting the wasm engine — single instance,- no election, trivial routing. (Chromium probe: IDB, Web Locks and- BroadcastChannel all available in SharedWorker.)-- **Fallback (no SharedWorker): dedicated worker per tab**, each with its- own engine instance over the same IDB database. Web Locks serialize- writes/GC (single writer at a time); BroadcastChannel broadcasts- changed-keys so every tab's exchange re-executes affected operations.- Cost: N copies of the hot tier — acceptable.+- **Browser: SharedWorker** hosting the wasm engine — one instance across+ tabs, no election or cross-engine coordination.+- **No SharedWorker:** return a no-op `CacheHost` that always misses, ignores+ writes, and does not initialize wasm or persistent storage. Mutations pass+ through the exchange without durable optimism.- Selection at startup: Tauri detection (`isTauri`) → native transport;- otherwise `typeof SharedWorker === 'function'` picks the worker kind. All- paths sit behind the same `Storage` trait and `CacheHost` RPC interface.+ otherwise SharedWorker support selects either the browser cache or no-op+ host. All paths sit behind the same `CacheHost` interface.### 4.3 Storage backends| Backend | Host | Notes ||------------|--------------|------------------------------------------------|-| SQLite | Tauri native | records + links + meta tables; WAL mode |-| IndexedDB | browser | via the `idb` crate inside the wasm module; one DB, object stores for records / operation roots / meta |+| SQLite | Tauri native | records, mutation queue, optimistic layers, and meta; WAL mode |+| IndexedDB | browser | via the `idb` crate; stable per-scope DB with object stores for records, mutation queue, optimistic layers, and meta |`Storage` trait (async): `get_batch`, `put_batch`, `delete_batch`,`scan_prefix`, `approx_size`. Records serialized with `postcard` (stored as@@ -246,18 +244,16 @@ apps/web/tauri/graphql_cache_plugin/ # tauri commands + engine thread wrappingapps/web/src/lib/graphql-cache/ # JS gluehost/ # CacheHost interface + worker & tauri transportsexchange/ # urql normalizedCacheExchange- worker/ # SharedWorker/dedicated-worker entries+ worker/ # SharedWorker entry + worker core```## 6. Phases**Phase 0 — spike** *(closed)*- Browser probe harness built; Chromium results in Appendix A. **Decision- made: IDB-backed persistence via the `idb` crate, SharedWorker preferred- with dedicated-worker fallback (§4.2).** Safari/Firefox probe runs and- the Tauri IPC benchmark were deliberately skipped — the IDB + worker- approach is the lowest common denominator and doesn't depend on their- results.+ made: IDB-backed persistence via the `idb` crate in a SharedWorker, with+ caching disabled when SharedWorker is unavailable (§4.2).** Safari/Firefox+ probe runs and the Tauri IPC benchmark were deliberately skipped.- Wire protocol delivered in Phase 3 (`src/lib/graphql-cache/protocol.ts`).- The probe harness (`spikes/graphql-cache-probe/`) and the soup payloadmeasurement script (`scripts/measure-soup-payloads.ts`) were removed@@ -292,10 +288,9 @@ apps/web/src/lib/graphql-cache/ # JS gluewasm-bindgen-test. Build: `just build-cache-wasm` →`src/lib/graphql-cache/wasm/` (gitignored), ~460 KiB pre-gzip.- ~~JS glue~~ (`apps/web/src/lib/graphql-cache/`, alias `@graphql-cache/*`):- wire protocol (`protocol.ts`), `CacheWorkerCore` +- SharedWorker/dedicated-worker entries (Web Locks write serialization +- BroadcastChannel fanout in the fallback topology), `createWorkerCacheHost`- implementing `CacheHost`. Type-checked; end-to-end browser exercise+ wire protocol (`protocol.ts`), `CacheWorkerCore` + SharedWorker entry,+ and `createWorkerCacheHost` implementing `CacheHost` (with a storage-free+ no-op host when SharedWorker is unavailable). Type-checked; end-to-end browser exercisehappens with the Phase 4 exchange integration.- ~~Tauri host~~ (`apps/web/tauri/graphql_cache_plugin`, in the *tauri*workspace — it needs the patched tauri fork pinned there; path-deps on@@ -346,8 +341,8 @@ apps/web/src/lib/graphql-cache/ # JS glue- **Browser storage quirks** (Safari IDB edge cases/private mode, storageeviction under pressure) — mitigated by the disposable-cache design- (detect → discard → rebuild from network) and the dedicated-worker- fallback topology. Tauri is unaffected (native host only).+ (detect → discard → rebuild from network). Browsers without SharedWorker+ use the storage-free no-op host. Tauri is unaffected (native host only).- **`idb` crate dependency** — maintained third-party wasm bindings; if itstalls, the `Storage` trait isolates us (swap for hand-rolled`web-sys`-based bindings).@@ -401,8 +396,7 @@ Takeaways:3. RTT is a non-issue: ≤1 ms for 64 KiB payloads, well within the readbudget.-These takeaways drove the §4.2 decision (IDB via the `idb` crate, engine in-a worker that may or may not be a SharedWorker). Firefox/Safari probe runs-and the Tauri IPC benchmark were **skipped by decision** — the chosen-approach relies only on APIs universally available (IndexedDB, dedicated-workers, Web Locks, BroadcastChannel).+These takeaways originally drove the IDB decision. The current §4.2 topology+requires SharedWorker for browser caching and deliberately falls back to no+cache when it is unavailable. Firefox/Safari probe runs and the Tauri IPC+benchmark were **skipped by decision**.diff --git a/apps/web/src/lib/core/auth/logout.ts b/apps/web/src/lib/core/auth/logout.tsindex eeb1008011..a9be6d15ef 100644--- a/apps/web/src/lib/core/auth/logout.ts+++ b/apps/web/src/lib/core/auth/logout.ts@@ -2,6 +2,7 @@ import { useAnalytics } from '@app/lib/analytics/analytics-context';import { SERVER_HOSTS } from '@core/constant/servers';import { isNativeMobilePlatform } from '@core/mobile/isNativeMobilePlatform';import { syncLoginStorage } from '@core/util/cookies';+import { clearRegisteredCaches } from '@graphql-cache/lifecycle';import { authKeys } from '@queries/auth/user-info';import { queryClient } from '@queries/client';import { clearDocumentQueryCache } from '@queries/storage/document-cache';@@ -33,6 +34,9 @@ export function useLogout() {hasTrialed: false,});+ // Queued mutations are user intent; never allow them to replay under a+ // subsequent account sharing this anonymous device cache scope.+ await clearRegisteredCaches();await authServiceClient.logout();analytics.track('sign_out');analytics.reset();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 506333c2cc..9d068634e1 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@@ -1,20 +1,27 @@import {type Client,CombinedError,+ createRequest,gql,makeOperation,type Operation,type OperationResult,+ stringifyDocument,} from '@urql/core';import { beforeEach, describe, expect, it, vi } from 'vitest';import { makeSubject, map, pipe, type Source, subscribe } from 'wonka';import type { CacheHost } from '../host/types';import type {+ ClaimedMutation,+ MutationClaim,OptimisticWriteResult,ReadResult,WriteResult,} from '../protocol';-import { normalizedCacheExchange } from './normalized-cache-exchange';+import {+ type NormalizedCacheExchangeOptions,+ normalizedCacheExchange,+} from './normalized-cache-exchange';const QUERY = gql`query Soup($input: SoupInput!) {@@ -39,14 +46,23 @@ type FakeHost = CacheHost & {begins: Array<{ query: string; data: unknown }>;commits: Array<{ transactionId: string; query: string; data: unknown }>;rollbacks: string[];+ defers: Array<{ transactionId: string; error: string }>;+ claims: string[];teardowns: number[];scriptRead: (result: ReadResult) => void;+ seedQueued: (args: Parameters<CacheHost['beginOptimisticWrite']>[0]) => void;pushAffected: (opKeys: number[]) => void;};function makeFakeHost(): FakeHost {let readResult: ReadResult = { kind: 'miss' };const subscribers = new Set<(opKeys: number[]) => void>();+ const queue: Array<{+ transactionId: string;+ args: Parameters<CacheHost['beginOptimisticWrite']>[0];+ attemptCount: number;+ leased: boolean;+ }> = [];const host: FakeHost = {clientId: 'test-client',reads: [],@@ -54,10 +70,20 @@ function makeFakeHost(): FakeHost {begins: [],commits: [],rollbacks: [],+ defers: [],+ claims: [],teardowns: [],scriptRead: (r) => {readResult = r;},+ seedQueued: (args) => {+ queue.push({+ transactionId: `restored-${queue.length + 1}`,+ args,+ attemptCount: 0,+ leased: false,+ });+ },pushAffected: (opKeys) => {for (const cb of subscribers) cb(opKeys);},@@ -79,19 +105,52 @@ function makeFakeHost(): FakeHost {},async beginOptimisticWrite(args): Promise<OptimisticWriteResult> {host.begins.push({ query: args.query, data: args.data });+ const transactionId = `txn-${host.begins.length}`;+ queue.push({ transactionId, args, attemptCount: 0, leased: false });return {- transactionId: `txn-${host.begins.length}`,+ transactionId,changed: [],affectedOps: [],reset: false,};},- async commitOptimisticWrite(transactionId, args): Promise<WriteResult> {+ async claimNextMutation(_owner): Promise<ClaimedMutation | undefined> {+ const head = queue[0];+ if (!head || head.leased) return undefined;+ head.leased = true;+ head.attemptCount += 1;+ host.claims.push(head.transactionId);+ return {+ transactionId: head.transactionId,+ leaseGeneration: String(head.attemptCount),+ query: head.args.query,+ operationName: head.args.operationName,+ variables: head.args.variables ?? {},+ attemptCount: head.attemptCount,+ };+ },+ async deferOptimisticWrite(+ transactionId,+ _claim: MutationClaim,+ _nextAttemptAtMs,+ error+ ) {+ host.defers.push({ transactionId, error });+ const head = queue[0];+ if (head?.transactionId === transactionId) head.leased = false;+ },+ async commitOptimisticWrite(+ transactionId,+ _claim,+ args+ ): Promise<WriteResult> {host.commits.push({ transactionId, query: args.query, data: args.data });+ if (queue[0]?.transactionId === transactionId) queue.shift();return { changed: [], affectedOps: [], reset: false };},- async rollbackOptimisticWrite(transactionId): Promise<WriteResult> {+ async rollbackOptimisticWrite(transactionId, _claim): Promise<WriteResult> {host.rollbacks.push(transactionId);+ if (queue[0]?.transactionId === transactionId) queue.shift();return { changed: [], affectedOps: [], reset: false };},async invalidate() {@@ -151,10 +210,27 @@ function makeMutationOp(key: number, optimisticResponse?: unknown): Operation {/** Runs the exchange over a manual operation stream. */function harness(host: CacheHost,- resultFor?: (op: Operation) => Partial<OperationResult>+ resultFor?: (op: Operation) => Partial<OperationResult>,+ options: NormalizedCacheExchangeOptions = {}) {- const client = { reexecuteOperation: vi.fn() } as unknown as Client;const ops = makeSubject<Operation>();+ const client = {+ reexecuteOperation: vi.fn(),+ mutation: vi.fn((query, variables, context) => ({+ toPromise: () => {+ const request = createRequest(query, variables);+ ops.next(+ makeOperation('mutation', request, {+ requestPolicy: 'network-only',+ url: 'http://test',+ suspense: false,+ ...context,+ } as never)+ );+ return Promise.resolve(undefined);+ },+ })),+ } as unknown as Client;const forwarded: Operation[] = [];const forward = (ops$: Source<Operation>): Source<OperationResult> =>pipe(@@ -177,7 +253,10 @@ function harness();const results: OperationResult[] = [];- const exchangeIo = normalizedCacheExchange(host)({+ const exchangeIo = normalizedCacheExchange(+ host,+ options+ )({forward,client,dispatchDebug: () => undefined,@@ -189,7 +268,7 @@ function harness(return { ops, results, forwarded, client };}-const tick = () => new Promise((r) => setTimeout(r, 0));+const tick = () => new Promise((resolve) => setTimeout(resolve, 10));describe('normalizedCacheExchange', () => {let host: FakeHost;@@ -394,6 +473,34 @@ describe('normalizedCacheExchange', () => {describe('mutations', () => {const optimistic = { setEntityProperty: { id: 'prop-1' } };+ it('replays a persisted mutation when the exchange starts', async () => {+ host.seedQueued({+ query: stringifyDocument(MUTATION),+ operationName: 'SetEntityProperty',+ variables: { input: {} },+ data: optimistic,+ });+ const { forwarded } = harness(host);+ await tick();++ expect(host.begins).toHaveLength(0);+ expect(host.claims).toEqual(['restored-1']);+ expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);+ expect(forwarded[0]?.context.fetch).toBeTypeOf('function');+ expect(host.commits[0]?.transactionId).toBe('restored-1');+ });++ it('forwards optimistic mutations without cache work when the host is disabled', async () => {+ const disabledHost: CacheHost = { ...host, disabled: true };+ const { ops, forwarded } = harness(disabledHost);+ ops.next(makeMutationOp(1, optimistic));+ await tick();++ expect(host.begins).toHaveLength(0);+ expect(host.claims).toHaveLength(0);+ expect(forwarded.map((op) => op.kind)).toEqual(['mutation']);+ });+it('installs the optimistic layer before forwarding to the network', async () => {const { ops, results, forwarded } = harness(host);const begin = host.beginOptimisticWrite.bind(host);@@ -412,6 +519,44 @@ describe('normalizedCacheExchange', () => {expect(results[0]?.data).toEqual({ from: 'network' });});+ it('bounds queued network attempts to one minute', async () => {+ const timeoutSignal = new AbortController().signal;+ const existingSignal = new AbortController().signal;+ const combinedSignal = new AbortController().signal;+ const timeout = vi+ .spyOn(AbortSignal, 'timeout')+ .mockReturnValue(timeoutSignal);+ const any = vi.spyOn(AbortSignal, 'any').mockReturnValue(combinedSignal);+ const operationFetch = vi.fn().mockResolvedValue(new Response());+ try {+ const mutation = makeMutationOp(1, optimistic);+ const mutationWithFetch = makeOperation(mutation.kind, mutation, {+ ...mutation.context,+ fetch: operationFetch,+ } as never);+ const { ops } = harness(host, (op) => {+ if (op.kind === 'mutation') {+ void op.context.fetch?.('http://test', {+ signal: existingSignal,+ });+ }+ return {};+ });+ ops.next(mutationWithFetch);+ await tick();++ expect(timeout).toHaveBeenCalledWith(60_000);+ expect(any).toHaveBeenCalledWith([existingSignal, timeoutSignal]);+ expect(operationFetch).toHaveBeenCalledWith(+ 'http://test',+ expect.objectContaining({ signal: combinedSignal })+ );+ } finally {+ timeout.mockRestore();+ any.mockRestore();+ }+ });+it('commits with the network result on success and never emits a synthetic result', async () => {const { ops, results } = harness(host);ops.next(makeMutationOp(1, optimistic));@@ -455,6 +600,41 @@ describe('normalizedCacheExchange', () => {expect(host.commits).toHaveLength(0);});+ it('retains a retryable network failure and still returns the error', async () => {+ const error = new CombinedError({+ networkError: new Error('offline'),+ });+ const shouldRetryMutation = vi.fn(() => true);+ const { ops, results } = harness(+ host,+ (op) => (op.kind === 'mutation' ? { error, data: undefined } : {}),+ { shouldRetryMutation }+ );+ ops.next(makeMutationOp(1, optimistic));+ await tick();++ expect(shouldRetryMutation).toHaveBeenCalledWith(error);+ expect(host.defers).toEqual([+ { transactionId: 'txn-1', error: error.message },+ ]);+ expect(host.rollbacks).toHaveLength(0);+ expect(results[0]?.error).toBe(error);+ });++ it('forwards queued optimistic mutations strictly in enqueue order', async () => {+ const { ops, forwarded } = harness(host);+ ops.next(makeMutationOp(1, optimistic));+ ops.next(makeMutationOp(2, optimistic));+ await tick();++ expect(host.claims).toEqual(['txn-1', 'txn-2']);+ expect(forwarded.map((op) => op.key)).toEqual([1, 2]);+ expect(host.commits.map((entry) => entry.transactionId)).toEqual([+ 'txn-1',+ 'txn-2',+ ]);+ });+it('writes non-optimistic mutation responses through the standard path', async () => {const { ops, results, forwarded } = harness(host);ops.next(makeMutationOp(1));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 d72d604395..b5a96a0eb0 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@@ -18,12 +18,10 @@* - `cache-only`: hit → emit; miss → emit `data: undefined`, no network.** Mutations:- * - With an optimistic response (see `executeOptimisticMutation`): an- * in-memory optimistic layer is installed *before* the mutation is- * forwarded; dependent queries re-execute immediately. The layer commits- * with the real response on success and rolls back on error. No synthetic- * result is emitted — the caller's mutation promise resolves only with- * the network result.+ * - With an optimistic response (see `executeOptimisticMutation`): the+ * mutation and layer are durably queued before the ordered runner forwards+ * it. Retryable failures retain optimism for background replay; permanent+ * failures roll back. The caller still receives only its network result.* - Without one: forwarded normally; successful responses are normalized* through the standard write path so dependent cached queries update.*@@ -31,13 +29,19 @@*/import {+ type CombinedError,type Exchange,makeOperation,type Operation,type OperationResult,stringifyDocument,} from '@urql/core';-import { Kind, type OperationDefinitionNode } from 'graphql';+import {+ type DocumentNode,+ Kind,+ type OperationDefinitionNode,+ parse,+} from 'graphql';import {empty,filter,@@ -60,7 +64,31 @@ import { optimisticContextOf } from './optimistic';* urql operation key): identical concurrent mutations share a key but each* carries its own transaction.*/-const TRANSACTION_CONTEXT_KEY = 'normalizedCacheTransaction';+const QUEUE_ATTEMPT_CONTEXT_KEY = 'normalizedCacheQueueAttempt';+const QUEUE_REQUEST_TIMEOUT_MS = 60_000;+const QUEUE_LEASE_MS = 5 * 60_000;+const EMPTY_QUEUE_POLL_MS = 30_000;++type QueueAttemptContext = {+ transactionId: string;+ leaseOwner: string;+ leaseGeneration: string;+ attemptCount: number;+};++function queueAttemptOf(op: Operation): QueueAttemptContext | undefined {+ const value: unknown = op.context[QUEUE_ATTEMPT_CONTEXT_KEY];+ if (+ value !== null &&+ typeof value === 'object' &&+ 'transactionId' in value &&+ 'leaseOwner' in value &&+ 'leaseGeneration' in value+ ) {+ return value as QueueAttemptContext;+ }+ return undefined;+}const queryTextCache = new WeakMap<object, string>();@@ -83,6 +111,45 @@ function operationName(op: Operation): string | undefined {return undefined;}+function replayDocument(query: string, name?: string): DocumentNode {+ const document = parse(query);+ if (!name) return document;+ const definitions = document.definitions.filter(+ (definition) =>+ definition.kind !== Kind.OPERATION_DEFINITION ||+ definition.name?.value === name+ );+ if (+ !definitions.some(+ (definition) => definition.kind === Kind.OPERATION_DEFINITION+ )+ ) {+ throw new Error(`queued GraphQL operation ${name} is missing`);+ }+ return { ...document, definitions };+}++function retryDelayMs(attemptCount: number): number {+ return Math.min(1_000 * 2 ** Math.max(0, attemptCount - 1), 60_000);+}++/** Applies a hard network bound well inside the durable queue lease. */+function withQueueRequestTimeout(op: Operation): Operation {+ const operationFetch = op.context.fetch ?? globalThis.fetch;+ return makeOperation(op.kind, op, {+ ...op.context,+ fetch: (input, init) => {+ const timeoutSignal = AbortSignal.timeout(QUEUE_REQUEST_TIMEOUT_MS);+ return operationFetch(input, {+ ...init,+ signal: init?.signal+ ? AbortSignal.any([init.signal, timeoutSignal])+ : timeoutSignal,+ });+ },+ });+}+function cacheResult(op: Operation,data: unknown,@@ -110,6 +177,12 @@ export interface NormalizedCacheExchangeOptions {* layer itself is identity-agnostic.*/extractIdentity?: (data: unknown) => string | undefined;+ /**+ * Decides whether a failed optimistic mutation remains queued. The caller+ * still receives the current network error; `true` retains the optimistic+ * layer for a later background attempt. Defaults to `false`.+ */+ shouldRetryMutation?: (error: CombinedError) => boolean | Promise<boolean>;}export function normalizedCacheExchange(@@ -141,6 +214,84 @@ export function normalizedCacheExchange(// Async cache reads re-inject network-bound operations here.const { source: forwardQueue$, next: enqueueForward } =makeSubject<Operation>();+ const queueOwner = `exchange:${host.clientId}`;+ const liveQueuedOps = new Map<string, Operation>();+ let attemptInFlight = false;+ let drainRunning = false;+ let deferredUntil: number | undefined;+ let drainTimer: ReturnType<typeof setTimeout> | undefined;++ function scheduleDrain(delayMs = 0): void {+ if (drainTimer !== undefined) clearTimeout(drainTimer);+ drainTimer = setTimeout(() => {+ drainTimer = undefined;+ void drainQueue();+ }, delayMs);+ }++ async function drainQueue(): Promise<void> {+ if (attemptInFlight || drainRunning) return;+ drainRunning = true;+ try {+ const now = Date.now();+ const claimed = await host.claimNextMutation(+ queueOwner,+ now,+ now + QUEUE_LEASE_MS+ );+ if (!claimed) {+ scheduleDrain(+ deferredUntil === undefined+ ? EMPTY_QUEUE_POLL_MS+ : Math.max(0, deferredUntil - Date.now())+ );+ return;+ }++ deferredUntil = undefined;+ attemptInFlight = true;+ const attempt: QueueAttemptContext = {+ transactionId: claimed.transactionId,+ leaseOwner: queueOwner,+ leaseGeneration: claimed.leaseGeneration,+ attemptCount: claimed.attemptCount,+ };+ const live = liveQueuedOps.get(claimed.transactionId);+ if (live) {+ enqueueForward(+ withQueueRequestTimeout(+ makeOperation(live.kind, live, {+ ...live.context,+ [QUEUE_ATTEMPT_CONTEXT_KEY]: attempt,+ })+ )+ );+ } else {+ try {+ const replay = client.mutation(+ replayDocument(claimed.query, claimed.operationName),+ claimed.variables,+ {+ requestPolicy: 'network-only',+ [QUEUE_ATTEMPT_CONTEXT_KEY]: attempt,+ }+ );+ void replay.toPromise();+ } catch {+ await host.rollbackOptimisticWrite(claimed.transactionId, {+ owner: queueOwner,+ generation: claimed.leaseGeneration,+ });+ attemptInFlight = false;+ scheduleDrain();+ }+ }+ } catch {+ scheduleDrain(EMPTY_QUEUE_POLL_MS);+ } finally {+ drainRunning = false;+ }+ }async function readThenRoute(op: Operation@@ -177,12 +328,17 @@ export function normalizedCacheExchange(return undefined;}- /**- * Installs the optimistic layer (when the mutation carries one) and- * only then releases the mutation to the network. Cache failures- * degrade to a plain, non-optimistic network mutation.- */+ /** Durably queues optimism before allowing the ordered runner to send. */async function prepareMutation(op: Operation): Promise<void> {+ if (host.disabled) {+ enqueueForward(op);+ return;+ }+ // Reconstructed startup retries already have a durable transaction.+ if (queueAttemptOf(op)) {+ enqueueForward(withQueueRequestTimeout(op));+ return;+ }const optimistic = optimisticContextOf(op);if (!optimistic) {enqueueForward(op);@@ -195,12 +351,8 @@ export function normalizedCacheExchange(variables: op.variables as Record<string, unknown> | undefined,data: optimistic.optimisticResponse,});- enqueueForward(- makeOperation(op.kind, op, {- ...op.context,- [TRANSACTION_CONTEXT_KEY]: begin.transactionId,- })- );+ liveQueuedOps.set(begin.transactionId, op);+ scheduleDrain();} catch (error) {options.onCacheError?.(error, op);enqueueForward(op);@@ -225,16 +377,39 @@ export function normalizedCacheExchange(options.onCacheError?.(error, op);}} else if (op.kind === 'mutation') {- const transactionId: unknown = op.context[TRANSACTION_CONTEXT_KEY];- try {- if (typeof transactionId === 'string') {+ const attempt = queueAttemptOf(op);+ if (attempt) {+ const claim = {+ owner: attempt.leaseOwner,+ generation: attempt.leaseGeneration,+ };+ let retryAt: number | undefined;+ try {if (result.error || result.data == null) {- await host.rollbackOptimisticWrite(transactionId);+ let retry = false;+ if (result.error && options.shouldRetryMutation) {+ try {+ retry = await options.shouldRetryMutation(result.error);+ } catch (error) {+ options.onCacheError?.(error, op);+ }+ }+ if (retry) {+ retryAt = Date.now() + retryDelayMs(attempt.attemptCount);+ await host.deferOptimisticWrite(+ attempt.transactionId,+ claim,+ retryAt,+ result.error?.message ?? 'mutation returned no data'+ );+ } else {+ await host.rollbackOptimisticWrite(+ attempt.transactionId,+ claim+ );+ }} else {- // Atomic replace: dependents move straight from the- // optimistic data to the real response, never flickering- // back to the pre-mutation state.- await host.commitOptimisticWrite(transactionId, {+ await host.commitOptimisticWrite(attempt.transactionId, claim, {query: queryText(op),operationName: operationName(op),variables: op.variables as@@ -243,7 +418,19 @@ export function normalizedCacheExchange(data: result.data,});}- } else if (result.data != null && !result.error) {+ } catch (error) {+ options.onCacheError?.(error, op);+ retryAt = Date.now() + QUEUE_LEASE_MS;+ } finally {+ liveQueuedOps.delete(attempt.transactionId);+ attemptInFlight = false;+ deferredUntil = retryAt;+ scheduleDrain(+ retryAt === undefined ? 0 : Math.max(0, retryAt - Date.now())+ );+ }+ } else if (result.data != null && !result.error) {+ try {// Plain mutation write-through: normalized entities update// dependent cached queries.await host.writeQuery({@@ -252,9 +439,9 @@ export function normalizedCacheExchange(variables: op.variables as Record<string, unknown> | undefined,data: result.data,});+ } catch (error) {+ options.onCacheError?.(error, op);}- } catch (error) {- options.onCacheError?.(error, op);}}return result;@@ -274,9 +461,9 @@ export function normalizedCacheExchange(}));- // Mutations are held until their optimistic layer (if any) is- // installed, then re-injected through the forward queue. Emits- // nothing itself — the network result is the only mutation emission.+ // Optimistic mutations are held after durable enqueue until the strict+ // queue runner claims them. The network result remains the only+ // mutation emission.const mutationPrep$ = pipe(shared,filter((op) => op.kind === 'mutation'),@@ -305,6 +492,12 @@ export function normalizedCacheExchange(mergeMap((result) => fromPromise(writeThrough(result))));+ if (!host.disabled) {+ scheduleDrain();+ if (typeof addEventListener === 'function') {+ addEventListener('online', () => scheduleDrain());+ }+ }void unsubscribePush;return merge([cacheResults$, mutationPrep$, forwarded$]);};diff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.tsnew file mode 100644index 0000000000..e3954cea56--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts@@ -0,0 +1,54 @@+import type {+ OptimisticWriteResult,+ ReadResult,+ WriteResult,+} from '../protocol';+import type { CacheHost } from './types';++const emptyWriteResult = (): WriteResult => ({+ changed: [],+ affectedOps: [],+ reset: false,+});++/**+ * CacheHost used when the platform cannot run the shared cache engine.+ * It never stores data. Its disabled marker makes the exchange bypass+ * optimistic persistence and forward mutations directly.+ */+export function createNoopCacheHost(reason: string): CacheHost {+ console.warn(`[graphql-cache] disabled: ${reason}`);++ return {+ clientId: 'noop',+ disabled: true,+ async readQuery(): Promise<ReadResult> {+ return { kind: 'miss' };+ },+ async writeQuery(): Promise<WriteResult> {+ return emptyWriteResult();+ },+ async beginOptimisticWrite(): Promise<OptimisticWriteResult> {+ throw new Error('normalized GraphQL cache is unavailable');+ },+ async claimNextMutation() {+ return undefined;+ },+ async deferOptimisticWrite(): Promise<void> {},+ async commitOptimisticWrite(): Promise<WriteResult> {+ return emptyWriteResult();+ },+ async rollbackOptimisticWrite(): Promise<WriteResult> {+ return emptyWriteResult();+ },+ async invalidate(): Promise<string[]> {+ return [];+ },+ async teardown(): Promise<void> {},+ async clear(): Promise<void> {},+ onOpsAffected() {+ return () => undefined;+ },+ dispose() {},+ };+}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 4a21fbe77b..f647075d6d 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@@ -99,19 +99,29 @@ describe('createTauriCacheHost', () => {});expect(begun).toEqual(optimistic);- await host.commitOptimisticWrite('1', {+ const claim = { owner: 'runner', generation: '2' };+ await host.commitOptimisticWrite('1', claim, {query: 'mutation { m }',data: { m: 2 },});expect(invokeMock).toHaveBeenCalledWith('graphql_cache_commit_optimistic_write',- expect.objectContaining({ transactionId: '1', data: { m: 2 } })+ expect.objectContaining({+ transactionId: '1',+ leaseOwner: 'runner',+ leaseGeneration: '2',+ data: { m: 2 },+ }));- await host.rollbackOptimisticWrite('1');+ await host.rollbackOptimisticWrite('1', claim);expect(invokeMock).toHaveBeenCalledWith('graphql_cache_rollback_optimistic_write',- { transactionId: '1' }+ {+ transactionId: '1',+ leaseOwner: 'runner',+ leaseGeneration: '2',+ });});diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.tsindex 59cfe7e0fa..f164569e32 100644--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts@@ -10,6 +10,8 @@import { invoke } from '@tauri-apps/api/core';import { listen, type UnlistenFn } from '@tauri-apps/api/event';import type {+ ClaimedMutation,+ MutationClaim,OptimisticWriteResult,ReadResult,WriteResult,@@ -129,12 +131,42 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {operationName: args.operationName,variables: args.variables,data: args.data,+ createdAtMs: Date.now(),});},+ async claimNextMutation(+ owner: string,+ nowMs: number,+ leaseExpiresAtMs: number+ ): Promise<ClaimedMutation | undefined> {+ await ready;+ return await request<ClaimedMutation | undefined>(+ 'graphql_cache_claim_next_mutation',+ { owner, nowMs, leaseExpiresAtMs }+ );+ },++ async deferOptimisticWrite(+ transactionId: string,+ claim: MutationClaim,+ nextAttemptAtMs: number,+ error: string+ ): Promise<void> {+ await ready;+ await request('graphql_cache_defer_optimistic_write', {+ transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,+ nextAttemptAtMs,+ error,+ });+ },+async commitOptimisticWrite(transactionId: string,+ claim: MutationClaim,args: CacheWriteArgs): Promise<WriteResult> {await ready;@@ -142,6 +174,8 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {'graphql_cache_commit_optimistic_write',{transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,query: args.query,operationName: args.operationName,variables: args.variables,@@ -150,11 +184,18 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {);},- async rollbackOptimisticWrite(transactionId: string): Promise<WriteResult> {+ async rollbackOptimisticWrite(+ transactionId: string,+ claim: MutationClaim+ ): Promise<WriteResult> {await ready;return await request<WriteResult>('graphql_cache_rollback_optimistic_write',- { transactionId }+ {+ transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,+ });},diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.tsindex 627e1df72b..2d3af1ac75 100644--- a/apps/web/src/lib/graphql-cache/host/types.ts+++ b/apps/web/src/lib/graphql-cache/host/types.ts@@ -1,11 +1,13 @@/*** Transport-agnostic cache host interface consumed by the urql exchange and* imperative writers (websocket handlers). Implementations:- * - worker-host.ts: browser (SharedWorker / dedicated worker + wasm engine)+ * - worker-host.ts: browser (SharedWorker + wasm engine, or no-op fallback)* - tauri-host.ts (Phase 3b): Tauri IPC to the native engine*/import type {+ ClaimedMutation,+ MutationClaim,OptimisticWriteResult,ReadResult,WriteResult,@@ -28,26 +30,37 @@ export interface CacheWriteArgs extends CacheReadArgs {export interface CacheHost {/** Stable id of this context; used to namespace operation ids. */readonly clientId: string;+ /** True for the storage-free fallback used without SharedWorker support. */+ readonly disabled?: boolean;readQuery(args: CacheReadArgs): Promise<ReadResult>;writeQuery(args: CacheWriteArgs): Promise<WriteResult>;- /**- * Installs an in-memory optimistic layer from a mutation's optimistic- * response (`args.data`). Persists nothing; the returned transaction id- * must be settled with `commitOptimisticWrite` or- * `rollbackOptimisticWrite`.- */+ /** Durably queues a mutation and its optimistic response. */beginOptimisticWrite(args: CacheWriteArgs): Promise<OptimisticWriteResult>;- /**- * Replaces a pending optimistic layer with the real network response- * (`args.data`) atomically and flushes settled layers durably.- */+ /** Claims the oldest runnable mutation; later entries are never skipped. */+ claimNextMutation(+ owner: string,+ nowMs: number,+ leaseExpiresAtMs: number+ ): Promise<ClaimedMutation | undefined>;+ /** Retains a retryable mutation and releases its lease. */+ deferOptimisticWrite(+ transactionId: string,+ claim: MutationClaim,+ nextAttemptAtMs: number,+ error: string+ ): Promise<void>;+ /** Atomically commits a claimed mutation's real network response. */commitOptimisticWrite(transactionId: string,+ claim: MutationClaim,args: CacheWriteArgs): Promise<WriteResult>;- /** Drops a pending optimistic layer's contribution (mutation failed). */- rollbackOptimisticWrite(transactionId: string): Promise<WriteResult>;+ /** Permanently fails a claimed mutation and drops its optimistic layer. */+ rollbackOptimisticWrite(+ transactionId: string,+ claim: MutationClaim+ ): Promise<WriteResult>;/** Evict records by entity key (external/push updates); returns affected local op ids. */invalidate(keys: string[]): Promise<string[]>;/** urql teardown for an operation key. */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.tsnew file mode 100644index 0000000000..8bb7ab1d0a--- /dev/null+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts@@ -0,0 +1,47 @@+import { afterEach, describe, expect, it, vi } from 'vitest';+import { createWorkerCacheHost } from './worker-host';++describe('createWorkerCacheHost', () => {+ afterEach(() => {+ vi.unstubAllGlobals();+ vi.restoreAllMocks();+ });++ it('uses a storage-free no-op host when SharedWorker is unavailable', async () => {+ const worker = vi.fn();+ vi.stubGlobal('SharedWorker', undefined);+ vi.stubGlobal('Worker', worker);+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});++ const host = createWorkerCacheHost({ scope: 'scope-1' });++ expect(warn).toHaveBeenCalledWith(+ '[graphql-cache] disabled: SharedWorker is not supported by this browser'+ );+ expect(worker).not.toHaveBeenCalled();+ expect(host.disabled).toBe(true);+ await expect(host.readQuery({ query: '{ x }' })).resolves.toEqual({+ kind: 'miss',+ });+ await expect(+ host.writeQuery({ query: '{ x }', data: { x: 1 } })+ ).resolves.toEqual({ changed: [], affectedOps: [], reset: false });+ });++ it('falls back to no-op when SharedWorker initialization throws', () => {+ vi.stubGlobal(+ 'SharedWorker',+ vi.fn(function () {+ throw new Error('blocked');+ })+ );+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});++ const host = createWorkerCacheHost({ scope: 'scope-1' });++ expect(host.disabled).toBe(true);+ expect(warn).toHaveBeenCalledWith(+ '[graphql-cache] disabled: SharedWorker could not be initialized'+ );+ });+});diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 8f6a1ea9e7..ba72c4e57a 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -1,19 +1,20 @@/**- * Browser CacheHost: talks the RPC protocol to the cache worker.- * Prefers SharedWorker (single engine across tabs); falls back to a- * dedicated worker per tab (engines converge via IndexedDB + Web Locks +- * BroadcastChannel — see worker-core.ts).+ * Browser CacheHost: talks to the single cache engine in a SharedWorker.+ * Platforms without SharedWorker support receive a storage-free no-op host.*/import {type CacheNotice,type CacheRequest,+ type ClaimedMutation,isCachePush,+ type MutationClaim,type OptimisticWriteResult,type ReadResult,type WorkerMessage,type WriteResult,} from '../protocol';+import { createNoopCacheHost } from './noop-host';import type { CacheHost, CacheReadArgs, CacheWriteArgs } from './types';type Pending = {@@ -29,8 +30,6 @@ type DistributiveOmit<T, K extends PropertyKey> = T extends unknownexport interface WorkerHostOptions {scope: string;hotCapacity?: number;- /** Force a topology (tests/diagnostics). */- forceDedicatedWorker?: boolean;/*** Per-request timeout in ms (default 10s). A hung worker rejects the* pending call; the exchange degrades rejected reads to the network.@@ -41,6 +40,10 @@ export interface WorkerHostOptions {const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {+ if (typeof SharedWorker !== 'function') {+ return createNoopCacheHost('SharedWorker is not supported by this browser');+ }+const clientId = crypto.randomUUID();const pending = new Map<number,@@ -51,9 +54,6 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;let nextRequestId = 1;- const useShared =- typeof SharedWorker === 'function' && !options.forceDedicatedWorker;-let post: (msg: CacheRequest) => void;let dispose: () => void;@@ -81,30 +81,25 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {}};- if (useShared) {- const worker = new SharedWorker(+ let worker: SharedWorker;+ try {+ worker = new SharedWorker(new URL('../worker/cache.shared-worker.ts', import.meta.url),{ type: 'module', name: `graphql-cache:${options.scope}` });worker.port.onmessage = onMessage;worker.port.start();- post = (msg) => worker.port.postMessage(msg);- dispose = () => {- // Tell the SharedWorker to drop our port — there is no platform- // disconnect event, and stale ports would otherwise accumulate.- const notice: CacheNotice = { kind: 'disconnect' };- worker.port.postMessage(notice);- worker.port.close();- };- } else {- const worker = new Worker(- new URL('../worker/cache.worker.ts', import.meta.url),- { type: 'module', name: `graphql-cache:${options.scope}` }- );- worker.onmessage = onMessage;- post = (msg) => worker.postMessage(msg);- dispose = () => worker.terminate();+ } catch {+ return createNoopCacheHost('SharedWorker could not be initialized');}+ post = (msg) => worker.port.postMessage(msg);+ dispose = () => {+ // Tell the SharedWorker to drop our port — there is no platform+ // disconnect event, and stale ports would otherwise accumulate.+ const notice: CacheNotice = { kind: 'disconnect' };+ worker.port.postMessage(notice);+ worker.port.close();+ };// Best-effort cleanup when the page goes away (bfcache-safe: a restored// page gets a fresh host on next use anyway).@@ -173,17 +168,52 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {operationName: args.operationName,variables: args.variables,data: args.data,+ createdAtMs: Date.now(),})) as OptimisticWriteResult;},+ async claimNextMutation(+ owner: string,+ nowMs: number,+ leaseExpiresAtMs: number+ ): Promise<ClaimedMutation | undefined> {+ await ready;+ return (await request({+ kind: 'claim-next-mutation',+ owner,+ nowMs,+ leaseExpiresAtMs,+ })) as ClaimedMutation | undefined;+ },++ async deferOptimisticWrite(+ transactionId: string,+ claim: MutationClaim,+ nextAttemptAtMs: number,+ error: string+ ): Promise<void> {+ await ready;+ await request({+ kind: 'defer-optimistic-write',+ transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,+ nextAttemptAtMs,+ error,+ });+ },+async commitOptimisticWrite(transactionId: string,+ claim: MutationClaim,args: CacheWriteArgs): Promise<WriteResult> {await ready;return (await request({kind: 'commit-optimistic-write',transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,query: args.query,operationName: args.operationName,variables: args.variables,@@ -191,11 +221,16 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {})) as WriteResult;},- async rollbackOptimisticWrite(transactionId: string): Promise<WriteResult> {+ async rollbackOptimisticWrite(+ transactionId: string,+ claim: MutationClaim+ ): Promise<WriteResult> {await ready;return (await request({kind: 'rollback-optimistic-write',transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,})) as WriteResult;},diff --git a/apps/web/src/lib/graphql-cache/index.ts b/apps/web/src/lib/graphql-cache/index.tsindex 5abe5876cf..3b4ed9585e 100644--- a/apps/web/src/lib/graphql-cache/index.ts+++ b/apps/web/src/lib/graphql-cache/index.ts@@ -15,7 +15,6 @@ export type {} from './host/types';export { createWorkerCacheHost } from './host/worker-host';export type {- CacheBroadcast,CachePush,CacheRequest,CacheResponse,diff --git a/apps/web/src/lib/graphql-cache/lifecycle.test.ts b/apps/web/src/lib/graphql-cache/lifecycle.test.tsnew file mode 100644index 0000000000..f25180ddf5--- /dev/null+++ b/apps/web/src/lib/graphql-cache/lifecycle.test.ts@@ -0,0 +1,52 @@+import { beforeEach, describe, expect, it, vi } from 'vitest';+import type { CacheHost } from './host/types';++function hostWithClear(clear: () => Promise<void>): CacheHost {+ return { clear } as CacheHost;+}++describe('clearRegisteredCaches', () => {+ beforeEach(() => {+ localStorage.clear();+ vi.restoreAllMocks();+ vi.resetModules();+ });++ it('preserves the scope when every cache clears', async () => {+ localStorage.setItem('graphql-cache:scope', 'current-scope');+ const clear = vi.fn().mockResolvedValue(undefined);+ const { clearRegisteredCaches, registerCacheHost } = await import(+ './lifecycle'+ );+ registerCacheHost(hostWithClear(clear));++ await clearRegisteredCaches();++ expect(clear).toHaveBeenCalledOnce();+ expect(localStorage.getItem('graphql-cache:scope')).toBe('current-scope');+ });++ it('rotates the scope after attempting every clear when one fails', async () => {+ localStorage.setItem('graphql-cache:scope', 'current-scope');+ vi.spyOn(crypto, 'randomUUID').mockReturnValue(+ '00000000-0000-4000-8000-000000000001'+ );+ const successfulClear = vi.fn().mockResolvedValue(undefined);+ const failedClear = vi+ .fn()+ .mockRejectedValue(new Error('durable wipe failed'));+ const { clearRegisteredCaches, registerCacheHost } = await import(+ './lifecycle'+ );+ registerCacheHost(hostWithClear(successfulClear));+ registerCacheHost(hostWithClear(failedClear));++ await clearRegisteredCaches();++ expect(successfulClear).toHaveBeenCalledOnce();+ expect(failedClear).toHaveBeenCalledOnce();+ expect(localStorage.getItem('graphql-cache:scope')).toBe(+ '00000000-0000-4000-8000-000000000001'+ );+ });+});diff --git a/apps/web/src/lib/graphql-cache/lifecycle.ts b/apps/web/src/lib/graphql-cache/lifecycle.tsnew file mode 100644index 0000000000..7cdca28f53--- /dev/null+++ b/apps/web/src/lib/graphql-cache/lifecycle.ts@@ -0,0 +1,19 @@+import type { CacheHost } from './host/types';+import { rotateCacheScope } from './scope';++const hosts = new Set<CacheHost>();++/** Registers a cache host for account-lifecycle clearing. */+export function registerCacheHost(host: CacheHost): void {+ hosts.add(host);+}++/** Best-effort wipe of records and queued user intent during logout. */+export async function clearRegisteredCaches(): Promise<void> {+ const results = await Promise.allSettled(+ [...hosts].map((host) => host.clear())+ );+ if (results.some((result) => result.status === 'rejected')) {+ rotateCacheScope();+ }+}diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex 603d06292d..956512fe92 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -2,13 +2,8 @@* Wire protocol between page contexts and the cache worker (the `CacheHost`* RPC from the design doc, apps/web/docs/graphql-normalized-cache-plan.md §4).*- * Topologies:- * - SharedWorker: one engine, many ports. Invalidations fan out over the- * ports directly.- * - Dedicated worker per tab (fallback): one engine per tab over the same- * IndexedDB database. Writes are serialized with Web Locks; changed keys- * fan out across tabs via BroadcastChannel, and each tab's worker- * translates them into locally-affected operation ids.+ * The browser topology is one SharedWorker engine serving many page ports.+ * Platforms without SharedWorker support use a storage-free no-op host.** Operation ids are strings of the form `"{clientId}:{urqlOperationKey}"` so* one shared engine can track operations from many tabs without collisions.@@ -35,10 +30,28 @@ export type WriteResult = {* transaction commits.*/export type OptimisticWriteResult = WriteResult & {- /** Engine-assigned id; settle with commit/rollback-optimistic-write. */+ /** Engine-assigned id; settle after claiming the queue head. */transactionId: string;};+/** Claimed strict queue head, ready to be forwarded through urql. */+export type ClaimedMutation = {+ transactionId: string;+ leaseGeneration: string;+ query: string;+ operationName?: string;+ variables: Record<string, unknown>;+ /** Identity witness captured at enqueue time. */+ identity?: string;+ attemptCount: number;+};++/** Identifies the queue attempt allowed to settle a transaction. */+export type MutationClaim = {+ owner: string;+ generation: string;+};+export type CacheRequest = { id: number } & (| { kind: 'init'; scope: string; hotCapacity?: number }| {@@ -62,10 +75,7 @@ export type CacheRequest = { id: number } & (*/identity?: string;}- /**- * Install an in-memory optimistic layer from a mutation's optimistic- * response. Persists nothing; settle with commit/rollback.- */+ /** Durably enqueue a mutation together with its optimistic response. */| {kind: 'begin-optimistic-write';originOpId?: string;@@ -73,21 +83,40 @@ export type CacheRequest = { id: number } & (operationName?: string;variables?: Record<string, unknown>;data: unknown;+ createdAtMs: number;+ }+ | {+ kind: 'claim-next-mutation';+ owner: string;+ nowMs: number;+ leaseExpiresAtMs: number;}- /**- * Atomically replace a pending layer with the real network response and- * flush contiguous settled layers durably.- */+ | {+ kind: 'defer-optimistic-write';+ transactionId: string;+ leaseOwner: string;+ leaseGeneration: string;+ nextAttemptAtMs: number;+ error: string;+ }+ /** Atomically replace a claimed layer with the real network response. */| {kind: 'commit-optimistic-write';transactionId: string;+ leaseOwner: string;+ leaseGeneration: string;query: string;operationName?: string;variables?: Record<string, unknown>;data: unknown;}- /** Drop a pending layer's contribution (mutation failed). */- | { kind: 'rollback-optimistic-write'; transactionId: string }+ /** Drop a claimed layer's contribution (permanent mutation failure). */+ | {+ kind: 'rollback-optimistic-write';+ transactionId: string;+ leaseOwner: string;+ leaseGeneration: string;+ }| { kind: 'teardown'; opId: string }/** External invalidation (e.g. websocket push): evict + report ops. */| { kind: 'invalidate'; keys: string[] }@@ -126,28 +155,6 @@ export type CachePush = {export type WorkerMessage = CacheResponse | CachePush;-/** Cross-tab broadcast (fallback topology), channel `graphql-cache:{scope}`. */-export type CacheBroadcast =- | {- kind: 'changed';- keys: string[];- /** Random id of the emitting worker, to ignore own broadcasts. */- source: string;- }- | {- /** The shared storage was wiped (identity change silent restart). */- kind: 'reset';- source: string;- };--export function broadcastChannelName(scope: string): string {- return `graphql-cache:${scope}`;-}--export function writeLockName(scope: string): string {- return `graphql-cache:write:${scope}`;-}-export function isCachePush(msg: WorkerMessage): msg is CachePush {return 'kind' in msg && msg.kind === 'ops-affected';}diff --git a/apps/web/src/lib/graphql-cache/scope.ts b/apps/web/src/lib/graphql-cache/scope.tsindex 1c246d1d7c..8a901cd7a8 100644--- a/apps/web/src/lib/graphql-cache/scope.ts+++ b/apps/web/src/lib/graphql-cache/scope.ts@@ -9,12 +9,26 @@* different user than the one bound to the cache wipes and rebinds it* (silent restart). See the design doc and cache-core `identity_witness`.*- * The uuid is stable for the browser profile; identity changes rotate the- * cache *contents*, not the scope.+ * The uuid is stable for the browser profile; identity changes normally rotate+ * the cache *contents*. A failed logout wipe rotates the scope as a quarantine.*/const SCOPE_STORAGE_KEY = 'graphql-cache:scope';+/** Quarantines a cache whose durable logout wipe could not be confirmed. */+export function rotateCacheScope(): void {+ const scope = crypto.randomUUID();+ try {+ localStorage.setItem(SCOPE_STORAGE_KEY, scope);+ } catch {+ try {+ localStorage.removeItem(SCOPE_STORAGE_KEY);+ } catch {+ // Inaccessible storage already makes the current scope session-only.+ }+ }+}+export function getOrCreateCacheScope(): string {let scope: string | null = null;try {diff --git a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.tsindex f99bcfe0a1..214c08f031 100644--- a/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts+++ b/apps/web/src/lib/graphql-cache/worker/cache.shared-worker.ts@@ -11,7 +11,7 @@ import { CacheWorkerCore } from './worker-core';declare const self: SharedWorkerGlobalScope;-const core = new CacheWorkerCore({ multiEngine: false });+const core = new CacheWorkerCore();self.onconnect = (event: MessageEvent) => {const port = event.ports[0];diff --git a/apps/web/src/lib/graphql-cache/worker/cache.worker.ts b/apps/web/src/lib/graphql-cache/worker/cache.worker.tsdeleted file mode 100644index a9f1025a9d..0000000000--- a/apps/web/src/lib/graphql-cache/worker/cache.worker.ts+++ /dev/null@@ -1,18 +0,0 @@-/**- * Dedicated-worker entry: fallback topology when SharedWorker is- * unavailable. One engine per tab over the shared IndexedDB database;- * writes serialized via Web Locks; cross-tab invalidation over- * BroadcastChannel (handled inside CacheWorkerCore).- */--import type { CacheRequest } from '../protocol';-import { CacheWorkerCore } from './worker-core';--declare const self: DedicatedWorkerGlobalScope;--const core = new CacheWorkerCore({ multiEngine: true });-core.addPort(self);--self.onmessage = (msg: MessageEvent<CacheRequest>) => {- void core.handleRequest(self, msg.data);-};diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.tsindex 54633c40a9..a3184a349b 100644--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts@@ -9,6 +9,7 @@*/import type {+ ClaimedMutation,OptimisticWriteResult,ReadResult,WriteResult,@@ -34,18 +35,36 @@ export interface CacheEngine {query: string,operationName: string | undefined,variables: Record<string, unknown> | undefined,- data: unknown+ data: unknown,+ createdAtMs: number): Promise<OptimisticWriteResult>;+ claimNextMutation(+ owner: string,+ nowMs: number,+ leaseExpiresAtMs: number+ ): Promise<ClaimedMutation | undefined>;+ deferOptimisticWrite(+ transactionId: string,+ leaseOwner: string,+ leaseGeneration: string,+ nextAttemptAtMs: number,+ error: string+ ): Promise<void>;commitOptimisticWrite(transactionId: string,+ leaseOwner: string,+ leaseGeneration: string,query: string,operationName: string | undefined,variables: Record<string, unknown> | undefined,data: unknown): Promise<WriteResult>;- rollbackOptimisticWrite(transactionId: string): Promise<WriteResult>;+ rollbackOptimisticWrite(+ transactionId: string,+ leaseOwner: string,+ leaseGeneration: string+ ): Promise<WriteResult>;invalidateKeys(keys: string[]): Promise<string[]>;- externalReset(): Promise<string[]>;teardownOperation(opId: string): Promise<void>;clear(): Promise<void>;/** Close the IndexedDB connection; call before destroyCache. */diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.tsindex 14ff9bed16..d07521c783 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts@@ -1,22 +1,15 @@/**- * Topology-agnostic worker core: owns the wasm engine, serves the RPC- * protocol on one or more ports, and fans out invalidations.- *- * Used by both entries:- * - cache.shared-worker.ts (SharedWorker, many ports, one engine)- * - cache.worker.ts (dedicated worker per tab + BroadcastChannel + Web Locks)+ * SharedWorker core: owns the browser's single wasm engine, serves the RPC+ * protocol to page ports, and fans out invalidations.*/-import {- broadcastChannelName,- type CacheBroadcast,- type CachePush,- type CacheRequest,- type CacheResponse,- type OptimisticWriteResult,- type ReadResult,- type WriteResult,- writeLockName,+import type {+ CachePush,+ CacheRequest,+ CacheResponse,+ OptimisticWriteResult,+ ReadResult,+ WriteResult,} from '../protocol';import { type CacheEngine, loadCacheWasm } from './wasm-module';@@ -31,18 +24,6 @@ export class CacheWorkerCore {/** Serializes engine calls (defense in depth; the engine also locks). */private queue: Promise<unknown> = Promise.resolve();private readonly ports = new Set<PortLike>();- private broadcast: BroadcastChannel | undefined;- private readonly workerId = crypto.randomUUID();-- constructor(- private readonly options: {- /**- * Fallback topology (dedicated worker per tab): serialize writes via- * Web Locks and exchange changed keys over BroadcastChannel.- */- multiEngine: boolean;- }- ) {}addPort(port: PortLike): void {this.ports.add(port);@@ -90,57 +71,70 @@ export class CacheWorkerCore {}case 'write': {const engine = this.requireEngine();- const result = await this.durableWrite(- async () =>- await engine.writeQuery(- request.originOpId,- request.query,- request.operationName,- request.variables,- request.data,- request.identity- )+ const result = await engine.writeQuery(+ request.originOpId,+ request.query,+ request.operationName,+ request.variables,+ request.data,+ request.identity);this.fanOut(result);return result;}case 'begin-optimistic-write': {const engine = this.requireEngine();- // Memory-only: no write lock needed, and never broadcast — the- // layer is local to this engine (per tab in the fallback topology;- // shared by all attached clients under a SharedWorker).const result: OptimisticWriteResult = await engine.beginOptimisticWrite(request.originOpId,request.query,request.operationName,request.variables,- request.data+ request.data,+ request.createdAtMs);- this.fanOut(result, { broadcast: false });+ this.fanOut(result);return result;}+ case 'claim-next-mutation': {+ const engine = this.requireEngine();+ return await engine.claimNextMutation(+ request.owner,+ request.nowMs,+ request.leaseExpiresAtMs+ );+ }+ case 'defer-optimistic-write': {+ const engine = this.requireEngine();+ await engine.deferOptimisticWrite(+ request.transactionId,+ request.leaseOwner,+ request.leaseGeneration,+ request.nextAttemptAtMs,+ request.error+ );+ return null;+ }case 'commit-optimistic-write': {const engine = this.requireEngine();// Committing can flush settled layers into durable storage.- const result = await this.durableWrite(- async () =>- await engine.commitOptimisticWrite(- request.transactionId,- request.query,- request.operationName,- request.variables,- request.data- )+ const result = await engine.commitOptimisticWrite(+ request.transactionId,+ request.leaseOwner,+ request.leaseGeneration,+ request.query,+ request.operationName,+ request.variables,+ request.data);this.fanOut(result);return result;}case 'rollback-optimistic-write': {const engine = this.requireEngine();- // Rolling back can unblock a settled suffix and flush it durably.- const result = await this.durableWrite(- async () =>- await engine.rollbackOptimisticWrite(request.transactionId)+ const result = await engine.rollbackOptimisticWrite(+ request.transactionId,+ request.leaseOwner,+ request.leaseGeneration);this.fanOut(result);return result;@@ -181,50 +175,12 @@ export class CacheWorkerCore {this.initPromise = (async () => {const wasm = await loadCacheWasm();this.engine = await wasm.openCache(scope, hotCapacity);- if (this.options.multiEngine) {- this.broadcast = new BroadcastChannel(broadcastChannelName(scope));- this.broadcast.onmessage = (event: MessageEvent<CacheBroadcast>) => {- void this.onBroadcast(event.data);- };- }})();await this.initPromise;}- /** Broadcasts from other tabs' engines sharing our storage. */- private async onBroadcast(msg: CacheBroadcast): Promise<void> {- if (msg.source === this.workerId) return;- const engine = this.engine;- if (!engine) return;- if (msg.kind === 'reset') {- // Another engine wiped the shared storage (identity change): drop- // local in-memory state and re-execute everything we track.- const affectedOps = await this.enqueue(() => engine.externalReset());- this.push({ kind: 'ops-affected', opIds: affectedOps, keys: [] });- return;- }- const affectedOps = await this.enqueue(() =>- engine.invalidateKeys(msg.keys)- );- this.push({ kind: 'ops-affected', opIds: affectedOps, keys: msg.keys });- }-- /**- * Runs a durable engine write, serialized via Web Locks in the- * multi-engine (dedicated worker per tab) topology.- */- private async durableWrite<T>(write: () => Promise<T>): Promise<T> {- return this.options.multiEngine && this.scope- ? await navigator.locks.request(writeLockName(this.scope), write)- : await write();- }-- /**- * After a local change: notify connected clients + other tabs. Optimistic- * begins pass `broadcast: false` — their changes are visible only through- * this engine, so other instances must not be told to invalidate.- */- private fanOut(result: WriteResult, opts?: { broadcast?: boolean }): void {+ /** Notifies every page connected to this shared engine. */+ private fanOut(result: WriteResult): void {if (result.affectedOps.length > 0) {this.push({kind: 'ops-affected',@@ -232,17 +188,6 @@ export class CacheWorkerCore {keys: result.changed,});}- if (- opts?.broadcast !== false &&- this.options.multiEngine &&- this.broadcast &&- (result.changed.length > 0 || result.reset)- ) {- const msg: CacheBroadcast = result.reset- ? { kind: 'reset', source: this.workerId }- : { kind: 'changed', keys: result.changed, source: this.workerId };- this.broadcast.postMessage(msg);- }}private push(msg: CachePush): void {diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.tsindex ff4cecc00c..ecad9e746b 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts@@ -11,6 +11,7 @@ import {createTauriCacheHost,createWorkerCacheHost,} from '@graphql-cache/index';+import { registerCacheHost } from '@graphql-cache/lifecycle';import { getOrCreateCacheScope } from '@graphql-cache/scope';import { getMacroApiToken } from '@service-auth/fetch';import { type Client, createClient, fetchExchange } from '@urql/core';@@ -94,6 +95,7 @@ export function getGraphqlSoupClient(): Client {const host = isTauri()? createTauriCacheHost({ scope }): createWorkerCacheHost({ scope });+ registerCacheHost(host);return createClient({url: `${dssHost}/items/soup/graphql`,exchanges: [@@ -103,6 +105,9 @@ export function getGraphqlSoupClient(): Client {// rebinds the cache (see @graphql-cache/scope).extractIdentity: (data) =>(data as Partial<SoupQuery> | undefined)?.user?.id,+ // Transport failures remain queued with their optimistic layer;+ // GraphQL application errors are permanent and roll back.+ shouldRetryMutation: (error) => error.networkError != null,}),fetchExchange,],diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rsindex 1c0cfd22e1..808bd8fc20 100644--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs@@ -9,7 +9,9 @@//! the exchange degrades to the network) — same contract as the browser//! worker's `{ok: false, error}` responses.-use crate::engine::{EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire};+use crate::engine::{+ ClaimedMutationWire, EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire,+};use crate::{CacheState, InitializedCache, emit_ops_affected};use cache_sqlite::SqliteStorage;use tauri::{AppHandle, Manager, Runtime, State};@@ -105,9 +107,8 @@ pub async fn graphql_cache_write<R: Runtime>(Ok(result)}-/// Installs an in-memory optimistic layer from a mutation's optimistic-/// response. The one engine is shared by all webviews (SharedWorker-/// semantics), so visible changes are broadcast too.+/// Durably queues a mutation and its optimistic response. The one engine is+/// shared by all webviews, so visible changes are broadcast too.#[tauri::command]pub async fn graphql_cache_begin_optimistic_write<R: Runtime>(app: AppHandle<R>,@@ -117,6 +118,7 @@ pub async fn graphql_cache_begin_optimistic_write<R: Runtime>(operation_name: Option<String>,variables: Option<Variables>,data: serde_json::Value,+ created_at_ms: i64,) -> Result<OptimisticWriteResultWire, String> {let result = engine_handle(&state)?.begin_optimistic_write(@@ -125,19 +127,55 @@ pub async fn graphql_cache_begin_optimistic_write<R: Runtime>(operation_name,variables.unwrap_or_default(),data,+ created_at_ms,).await?;emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);Ok(result)}-/// Atomically replaces a pending optimistic layer with the real network-/// response and flushes contiguous settled layers durably.+/// Claims the oldest runnable queued mutation.+#[tauri::command]+pub async fn graphql_cache_claim_next_mutation(+ state: State<'_, CacheState>,+ owner: String,+ now_ms: i64,+ lease_expires_at_ms: i64,+) -> Result<Option<ClaimedMutationWire>, String> {+ engine_handle(&state)?+ .claim_next_mutation(owner, now_ms, lease_expires_at_ms)+ .await+}++/// Retains a retryable queued mutation and releases its lease.+#[tauri::command]+pub async fn graphql_cache_defer_optimistic_write(+ state: State<'_, CacheState>,+ transaction_id: String,+ lease_owner: String,+ lease_generation: String,+ next_attempt_at_ms: i64,+ error: String,+) -> Result<(), String> {+ engine_handle(&state)?+ .defer_optimistic_write(+ transaction_id,+ lease_owner,+ lease_generation,+ next_attempt_at_ms,+ error,+ )+ .await+}++/// Atomically replaces a claimed optimistic layer with the real response.#[tauri::command]pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(app: AppHandle<R>,state: State<'_, CacheState>,transaction_id: String,+ lease_owner: String,+ lease_generation: String,query: String,operation_name: Option<String>,variables: Option<Variables>,@@ -146,6 +184,8 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(let result = engine_handle(&state)?.commit_optimistic_write(transaction_id,+ lease_owner,+ lease_generation,query,operation_name,variables.unwrap_or_default(),@@ -156,15 +196,17 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(Ok(result)}-/// Drops a pending optimistic layer's contribution (mutation failed).+/// Permanently fails a claimed mutation and drops its optimistic layer.#[tauri::command]pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(app: AppHandle<R>,state: State<'_, CacheState>,transaction_id: String,+ lease_owner: String,+ lease_generation: String,) -> Result<WriteResultWire, String> {let result = engine_handle(&state)?- .rollback_optimistic_write(transaction_id)+ .rollback_optimistic_write(transaction_id, lease_owner, lease_generation).await?;emit_ops_affected(&app, &result.affected_ops, &result.changed);Ok(result)diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rsindex c32baa0e41..c9632e8691 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs@@ -13,6 +13,7 @@use cache_core::deps::OpId;use cache_core::engine::{Engine, ReadResult, WriteResult};+use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};use cache_core::value::EntityKey;use cache_sqlite::SqliteStorage;use serde::Serialize;@@ -59,6 +60,43 @@ pub struct OptimisticWriteResultWire {pub result: WriteResultWire,}+/// Claimed queue head returned to the JavaScript mutation runner.+#[derive(Debug, Serialize)]+#[serde(rename_all = "camelCase")]+pub struct ClaimedMutationWire {+ /// Durable mutation id.+ pub transaction_id: String,+ /// Claim generation required for settlement.+ pub lease_generation: String,+ /// GraphQL mutation document.+ pub query: String,+ /// Selected operation name.+ pub operation_name: Option<String>,+ /// Variables parsed from their durable canonical JSON representation.+ pub variables: serde_json::Value,+ /// Identity witness captured when the mutation was enqueued.+ pub identity: Option<String>,+ /// Number of network attempts including this claim.+ pub attempt_count: u32,+}++impl TryFrom<ClaimedMutation> for ClaimedMutationWire {+ type Error = String;++ fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {+ let request = claimed.queued.mutation.request;+ Ok(Self {+ transaction_id: claimed.queued.id.to_string(),+ lease_generation: claimed.lease_generation.to_string(),+ query: request.query,+ operation_name: request.operation_name,+ variables: serde_json::from_str(&request.variables_json).map_err(|e| e.to_string())?,+ identity: request.identity,+ attempt_count: claimed.queued.mutation.attempt_count,+ })+ }+}+/// Interns host-side string operation ids to engine `u64` ids.#[derive(Default)]struct OpInterner {@@ -116,9 +154,14 @@ fn wire_write_result(ops: &OpInterner, result: WriteResult) -> WriteResultWire {}}+fn parse_u64(value: &str, label: &str) -> Result<u64, String> {+ value+ .parse::<u64>()+ .map_err(|_| format!("invalid {label} `{value}`"))+}+fn parse_transaction_id(id: &str) -> Result<u64, String> {- id.parse::<u64>()- .map_err(|_| format!("invalid optimistic transaction id `{id}`"))+ parse_u64(id, "optimistic transaction id")}impl EngineHandle {@@ -185,7 +228,7 @@ impl EngineHandle {.map_err(|e| e.to_string())}- /// Installs an in-memory optimistic layer (persists nothing).+ /// Durably queues a mutation and its optimistic layer.pub async fn begin_optimistic_write(&self,origin_op_id: Option<String>,@@ -193,12 +236,20 @@ impl EngineHandle {operation_name: Option<String>,variables: Variables,data: serde_json::Value,+ created_at_ms: i64,) -> Result<OptimisticWriteResultWire, String> {let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;let origin = origin_op_id.map(|name| ops.intern(&name));engine- .begin_optimistic_write(origin, &query, operation_name.as_deref(), &variables, &data)+ .begin_optimistic_write(+ origin,+ &query,+ operation_name.as_deref(),+ &variables,+ &data,+ created_at_ms,+ ).await.map(|(transaction, result)| OptimisticWriteResultWire {transaction_id: transaction.to_string(),@@ -207,21 +258,72 @@ impl EngineHandle {.map_err(|e| e.to_string())}- /// Replaces a pending optimistic layer with the real network response.+ /// Claims the strict mutation queue head when it is runnable.+ pub async fn claim_next_mutation(+ &self,+ owner: String,+ now_ms: i64,+ lease_expires_at_ms: i64,+ ) -> Result<Option<ClaimedMutationWire>, String> {+ let mut state = self.inner.lock().await;+ state+ .engine+ .claim_next_mutation(MutationClaimRequest {+ owner,+ now_ms,+ lease_expires_at_ms,+ })+ .await+ .map_err(|e| e.to_string())?+ .map(ClaimedMutationWire::try_from)+ .transpose()+ }++ /// Retains a retryable mutation and releases its claim.+ pub async fn defer_optimistic_write(+ &self,+ transaction_id: String,+ lease_owner: String,+ lease_generation: String,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<(), String> {+ let transaction = parse_transaction_id(&transaction_id)?;+ let claim = MutationClaimToken {+ owner: lease_owner,+ generation: parse_u64(&lease_generation, "lease generation")?,+ };+ self.inner+ .lock()+ .await+ .engine+ .defer_optimistic_write(transaction, claim, next_attempt_at_ms, error)+ .await+ .map_err(|e| e.to_string())+ }++ /// Replaces a claimed optimistic layer with the real network response.pub async fn commit_optimistic_write(&self,transaction_id: String,+ lease_owner: String,+ lease_generation: String,query: String,operation_name: Option<String>,variables: Variables,data: serde_json::Value,) -> Result<WriteResultWire, String> {let transaction = parse_transaction_id(&transaction_id)?;+ let claim = MutationClaimToken {+ owner: lease_owner,+ generation: parse_u64(&lease_generation, "lease generation")?,+ };let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;engine.commit_optimistic_write(transaction,+ claim,&query,operation_name.as_deref(),&variables,@@ -232,16 +334,22 @@ impl EngineHandle {.map_err(|e| e.to_string())}- /// Drops a pending optimistic layer's contribution (mutation failed).+ /// Permanently fails a claimed mutation and drops its optimistic layer.pub async fn rollback_optimistic_write(&self,transaction_id: String,+ lease_owner: String,+ lease_generation: String,) -> Result<WriteResultWire, String> {let transaction = parse_transaction_id(&transaction_id)?;+ let claim = MutationClaimToken {+ owner: lease_owner,+ generation: parse_u64(&lease_generation, "lease generation")?,+ };let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;engine- .rollback_optimistic_write(transaction)+ .rollback_optimistic_write(transaction, claim).await.map(|result| wire_write_result(ops, result)).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 b5020c2e5e..715953ac9b 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs@@ -57,6 +57,12 @@ fn read(handle: &EngineHandle, op_id: Option<&str>) -> ReadResultWire {.unwrap()}+fn claim(handle: &EngineHandle) -> ClaimedMutationWire {+ block_on(handle.claim_next_mutation("runner".to_string(), 10, 1_000))+ .unwrap()+ .expect("queue head")+}+#[test]fn write_then_read_round_trips() {let handle = spawn_handle();@@ -112,6 +118,7 @@ fn optimistic_layer_commits_durably() {Some("Soup".to_string()),variables(),soup_data(true),+ 0,)).unwrap();assert_eq!(optimistic.result.affected_ops, vec!["client:1".to_string()]);@@ -122,8 +129,11 @@ fn optimistic_layer_commits_durably() {};assert_eq!(data, soup_data(true));+ let claimed = claim(&handle);let committed = block_on(handle.commit_optimistic_write(optimistic.transaction_id,+ "runner".to_string(),+ claimed.lease_generation,QUERY.to_string(),Some("Soup".to_string()),variables(),@@ -149,10 +159,17 @@ fn rollback_drops_optimistic_contribution() {Some("Soup".to_string()),variables(),soup_data(true),+ 0,)).unwrap();- block_on(handle.rollback_optimistic_write(optimistic.transaction_id)).unwrap();+ let claimed = claim(&handle);+ block_on(handle.rollback_optimistic_write(+ optimistic.transaction_id,+ "runner".to_string(),+ claimed.lease_generation,+ ))+ .unwrap();let ReadResultWire::Hit { data } = read(&handle, None) else {panic!("expected hit");};@@ -180,6 +197,11 @@ fn clear_wipes_everything() {#[test]fn bad_transaction_id_is_an_error() {let handle = spawn_handle();- let error = block_on(handle.rollback_optimistic_write("not-a-number".to_string())).unwrap_err();+ let error = block_on(handle.rollback_optimistic_write(+ "not-a-number".to_string(),+ "runner".to_string(),+ "1".to_string(),+ ))+ .unwrap_err();assert!(error.contains("invalid optimistic transaction id"));}diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rsindex 8a84213820..8e719d34e3 100644--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs@@ -22,7 +22,9 @@ use tauri::{AppHandle, Emitter, Runtime};pub mod commands;mod engine;-pub use engine::{EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire};+pub use engine::{+ ClaimedMutationWire, EngineHandle, OptimisticWriteResultWire, ReadResultWire, WriteResultWire,+};/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose/// underlying records changed. Emitted to every webview; hosts filter bydiff --git a/apps/web/tauri/src-tauri/src/lib.rs b/apps/web/tauri/src-tauri/src/lib.rsindex 42d5710201..e870565c63 100644--- a/apps/web/tauri/src-tauri/src/lib.rs+++ b/apps/web/tauri/src-tauri/src/lib.rs@@ -230,6 +230,8 @@ pub fn run() {graphql_cache_plugin::commands::graphql_cache_read,graphql_cache_plugin::commands::graphql_cache_write,graphql_cache_plugin::commands::graphql_cache_begin_optimistic_write,+ graphql_cache_plugin::commands::graphql_cache_claim_next_mutation,+ graphql_cache_plugin::commands::graphql_cache_defer_optimistic_write,graphql_cache_plugin::commands::graphql_cache_commit_optimistic_write,graphql_cache_plugin::commands::graphql_cache_rollback_optimistic_write,graphql_cache_plugin::commands::graphql_cache_invalidate,diff --git a/crates/client/README.md b/crates/client/README.mdindex 87cea93753..1ed08e6790 100644--- a/crates/client/README.md+++ b/crates/client/README.md@@ -7,7 +7,7 @@ Normalized GraphQL cache with disk-backed persistence for urql. Design doc:| Crate | Purpose ||---|---|-| `cache-core` | Pure engine: schema-metadata codegen (build.rs from `static_assets/schema.graphql`), normalize/denormalize, LRU hot tier, dependency index, async `Storage` trait |+| `cache-core` | Pure engine: normalize/denormalize, LRU hot tier, dependency index, durable ordered optimistic-mutation queue, async `Storage` trait || `cache-sqlite` | `Storage` over SQLite — Tauri native host || `cache-idb` | `Storage` over IndexedDB via the `idb` crate — browser wasm host (wasm32-only; empty shell elsewhere) || `cache-wasm` | wasm-bindgen shell exposing the engine to the browser worker glue (`apps/web/src/lib/graphql-cache/`) |@@ -53,3 +53,8 @@ because a property instance's value is per-entity).Identity is not the cache's concern: the engine accepts an opaque sessiontag on writes (extracted by the urql exchange from `data.user.id`) andwipes + rebinds atomically when the tag changes (silent restart).++Optimistic GraphQL mutations are persisted with their replay request before+becoming visible. The exchange claims and applies them strictly in enqueue+order; a configurable callback decides whether an error remains queued or+permanently rolls back.diff --git a/crates/client/cache-core/src/codec.rs b/crates/client/cache-core/src/codec.rsindex 46ed91a52a..3cea1db9f7 100644--- a/crates/client/cache-core/src/codec.rs+++ b/crates/client/cache-core/src/codec.rs@@ -4,7 +4,10 @@//! format or schema change starts a fresh cache instead of attempting//! migration (the cache is disposable by design).+use crate::normalize::RecordUpdates;+use crate::queue::{PersistedOptimisticLayer, StoredMutation};use crate::value::Record;+use serde::{Serialize, de::DeserializeOwned};use thiserror::Error;/// Bump when the stored representation of [`Record`]/[`CacheValue`]@@ -13,17 +16,55 @@ pub const CACHE_FORMAT_VERSION: u32 = 1;#[derive(Debug, Error)]pub enum CodecError {- #[error("corrupt record: {0}")]+ #[error("corrupt cache payload: {0}")]Corrupt(#[from] postcard::Error),}+fn encode<T: Serialize>(value: &T) -> Vec<u8> {+ // Serialization of an in-memory cache value cannot fail.+ postcard::to_allocvec(value).expect("cache value serializes")+}++fn decode<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, CodecError> {+ Ok(postcard::from_bytes(bytes)?)+}+pub fn encode_record(record: &Record) -> Vec<u8> {- // Serialization of an in-memory record cannot fail.- postcard::to_allocvec(record).expect("record serializes")+ encode(record)}pub fn decode_record(bytes: &[u8]) -> Result<Record, CodecError> {- Ok(postcard::from_bytes(bytes)?)+ decode(bytes)+}++/// Encodes one queued mutation's request and retry metadata.+pub fn encode_stored_mutation(mutation: &StoredMutation) -> Vec<u8> {+ encode(mutation)+}++/// Decodes one queued mutation's request and retry metadata.+pub fn decode_stored_mutation(bytes: &[u8]) -> Result<StoredMutation, CodecError> {+ decode(bytes)+}++/// Encodes one persisted optimistic layer.+pub fn encode_optimistic_layer(layer: &PersistedOptimisticLayer) -> Vec<u8> {+ encode(layer)+}++/// Decodes one persisted optimistic layer.+pub fn decode_optimistic_layer(bytes: &[u8]) -> Result<PersistedOptimisticLayer, CodecError> {+ decode(bytes)+}++/// Encodes normalized updates independently for relational backends.+pub fn encode_record_updates(updates: &RecordUpdates) -> Vec<u8> {+ encode(updates)+}++/// Decodes normalized updates independently for relational backends.+pub fn decode_record_updates(bytes: &[u8]) -> Result<RecordUpdates, CodecError> {+ decode(bytes)}/// Canonical database/namespace name for a cache instance.@@ -35,6 +76,15 @@ pub fn cache_namespace(scope: &str) -> String {)}+/// Stable physical database name for a cache scope.+///+/// Unlike [`cache_namespace`], this deliberately excludes the record schema+/// and format versions. Normalized records are disposable on version changes,+/// while queued mutations represent user intent and must remain discoverable.+pub fn cache_database_name(scope: &str) -> String {+ format!("graphql-cache:{scope}")+}+#[cfg(test)]mod tests {use super::*;diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rsindex cee1bcd6ae..8a7b528a8d 100644--- a/crates/client/cache-core/src/engine.rs+++ b/crates/client/cache-core/src/engine.rs@@ -6,8 +6,12 @@ use crate::denormalize::{DenormalizeError, ReadOutcome, RecordSource, denormalizuse crate::deps::{DepIndex, OpId};use crate::document::{Document, DocumentError, OperationKind};use crate::normalize::{NormalizeError, RecordUpdates, normalize};+use crate::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,+ NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,+};use crate::store::Storage;-use crate::value::{EntityKey, Record};+use crate::value::{EntityKey, Record, canonical_json};use lru::LruCache;use serde_json::Value as Json;use std::collections::{BTreeMap, BTreeSet, HashMap};@@ -24,6 +28,13 @@ pub enum EngineError<S: std::error::Error + 'static> {Denormalize(#[from] DenormalizeError),#[error("unknown or already-settled optimistic transaction {0}")]UnknownTransaction(OptimisticTransactionId),+ #[error("stale claim for optimistic transaction {0}")]+ StaleMutationClaim(OptimisticTransactionId),+ #[error("invalid queued mutation {id}: {detail}")]+ InvalidQueuedMutation {+ id: OptimisticTransactionId,+ detail: String,+ },#[error("storage: {0}")]Storage(#[source] S),}@@ -56,46 +67,15 @@ pub struct WriteResult {/// Engine-assigned id of one optimistic mutation transaction. Never reuse/// host operation keys: identical concurrent mutations share an urql key,/// but each needs its own layer.-pub type OptimisticTransactionId = u64;+pub type OptimisticTransactionId = MutationId;-/// One optimistic mutation's contribution to the cache view. Layers are-/// ordered by creation; later layers override earlier ones field-by-field,-/// all of them override the durable base. Nothing in a layer is persisted-/// until the layer settles *and* every earlier layer has settled too-/// (contiguous-prefix flushing keeps out-of-order settlement correct).+/// One queued optimistic mutation's contribution to the cache view. Layers+/// are persisted and ordered by their mutation ids; only the strict queue+/// head can be claimed and settled.+#[derive(Clone)]struct OptimisticLayer {id: OptimisticTransactionId,- state: OptimisticLayerState,-}--enum OptimisticLayerState {- /// Awaiting the network result; `updates` normalized from the- /// optimistic response.- Pending { updates: RecordUpdates },- /// Network result arrived; `updates` replaced by the real response.- /// Held in-memory until the layer reaches the settled prefix.- Succeeded { updates: RecordUpdates },- /// Rolled back. Kept as an ordered tombstone (contributing nothing)- /// until earlier layers settle, then dropped by the prefix flush.- Failed,-}--impl OptimisticLayer {- /// The record updates this layer currently contributes to reads.- fn updates(&self) -> Option<&RecordUpdates> {- match &self.state {- OptimisticLayerState::Pending { updates }- | OptimisticLayerState::Succeeded { updates } => Some(updates),- OptimisticLayerState::Failed => None,- }- }-- fn settled(&self) -> bool {- matches!(- self.state,- OptimisticLayerState::Succeeded { .. } | OptimisticLayerState::Failed- )- }+ updates: RecordUpdates,}/// Reserved storage key holding the identity bound to this cache. The@@ -126,10 +106,9 @@ pub struct Engine<S: Storage> {docs: HashMap<String, Document>,deps: DepIndex,identity: IdentityState,- /// Ordered optimistic mutation layers (memory-only; see- /// [`OptimisticLayer`]).+ /// Ordered optimistic mutation layers hydrated from durable storage.optimistic: Vec<OptimisticLayer>,- next_transaction: OptimisticTransactionId,+ optimistic_hydrated: bool,}impl<S: Storage> Engine<S> {@@ -145,8 +124,91 @@ impl<S: Storage> Engine<S> {deps: DepIndex::new(),identity: IdentityState::NotHydrated,optimistic: Vec::new(),- next_transaction: 0,+ optimistic_hydrated: false,+ }+ }++ /// Hydrates durable optimistic layers before the first operation. Queue+ /// order is the optimistic composition order.+ async fn hydrate_optimistic(&mut self) -> Result<(), EngineError<S::Error>> {+ if self.optimistic_hydrated {+ return Ok(());}+ let queued = self+ .storage+ .load_mutation_queue()+ .await+ .map_err(EngineError::Storage)?;+ self.optimistic = Self::normalize_queued_layers(&mut self.docs, queued)?;+ self.optimistic_hydrated = true;+ Ok(())+ }++ /// Reloads durable optimistic layers after another engine sharing this+ /// storage changes the queue. Returns operations whose effective view+ /// changed.+ pub async fn refresh_optimistic_queue(&mut self) -> Result<WriteResult, EngineError<S::Error>> {+ let queued = self+ .storage+ .load_mutation_queue()+ .await+ .map_err(EngineError::Storage)?;+ let replacement = Self::normalize_queued_layers(&mut self.docs, queued)?;+ let candidates: BTreeSet<EntityKey> = self+ .optimistic+ .iter()+ .chain(&replacement)+ .flat_map(|layer| layer.updates.keys().cloned())+ .collect();+ let bases = self.load_bases(&candidates).await?;+ let before = effective_records(&bases, &self.optimistic, &candidates);+ self.optimistic = replacement;+ self.optimistic_hydrated = true;+ let after = effective_records(&bases, &self.optimistic, &candidates);+ let changed: BTreeSet<EntityKey> = candidates+ .into_iter()+ .filter(|key| before.get(key) != after.get(key))+ .collect();+ let affected_ops = self.deps.ops_for_keys(changed.iter());+ Ok(WriteResult {+ changed,+ affected_ops,+ reset: false,+ })+ }++ fn normalize_queued_layers(+ docs: &mut HashMap<String, Document>,+ queued: Vec<QueuedMutation>,+ ) -> Result<Vec<OptimisticLayer>, EngineError<S::Error>> {+ queued+ .into_iter()+ .map(|queued| {+ let variables: Json = serde_json::from_str(&queued.mutation.request.variables_json)+ .map_err(|error| EngineError::InvalidQueuedMutation {+ id: queued.id,+ detail: format!("invalid variables: {error}"),+ })?;+ let Json::Object(variables) = variables else {+ return Err(EngineError::InvalidQueuedMutation {+ id: queued.id,+ detail: "variables are not an object".to_string(),+ });+ };+ let data: Json = serde_json::from_str(&queued.optimistic.optimistic_data_json)+ .map_err(|error| EngineError::InvalidQueuedMutation {+ id: queued.id,+ detail: format!("invalid optimistic response: {error}"),+ })?;+ let document = Self::document(docs, &queued.mutation.request.query)?;+ let operation =+ document.operation(queued.mutation.request.operation_name.as_deref())?;+ Ok(OptimisticLayer {+ id: queued.id,+ updates: normalize(operation, &variables, &data)?,+ })+ })+ .collect()}/// The identity binding of this cache, hydrating it from storage on@@ -197,6 +259,7 @@ impl<S: Storage> Engine<S> {operation_name: Option<&str>,variables: &serde_json::Map<String, Json>,) -> Result<ReadResult, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;let doc = Self::document(&mut self.docs, query)?;let op = doc.operation(operation_name)?;if op.kind != OperationKind::Query {@@ -308,6 +371,7 @@ impl<S: Storage> Engine<S> {data: &Json,identity: Option<&str>,) -> Result<WriteResult, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;let doc = Self::document(&mut self.docs, query)?;let op = doc.operation(operation_name)?;let updates = normalize(op, variables, data)?;@@ -323,6 +387,7 @@ impl<S: Storage> Engine<S> {// A different user's session: in-flight optimistic// mutations belong to the old identity — discard them.self.optimistic.clear();+ self.optimistic_hydrated = true;self.storage.clear().await.map_err(EngineError::Storage)?;self.bind_identity(observed).await?;reset = true;@@ -412,13 +477,9 @@ impl<S: Storage> Engine<S> {Ok(changed)}- /// Installs a new optimistic layer from a mutation's optimistic- /// response. Persists nothing. Returns the transaction id plus a- /// [`WriteResult`] whose `changed` keys are the entities whose- /// *effective visible* data changed (`affected_ops` excludes- /// `origin_op`). The layer stays in memory until- /// [`commit_optimistic_write`](Self::commit_optimistic_write) or- /// [`rollback_optimistic_write`](Self::rollback_optimistic_write).+ /// Atomically enqueues a mutation together with its optimistic layer.+ /// The layer is durable before it becomes visible or the caller is+ /// allowed to forward the mutation to the network.pub async fn begin_optimistic_write(&mut self,origin_op: Option<OpId>,@@ -426,7 +487,9 @@ impl<S: Storage> Engine<S> {operation_name: Option<&str>,variables: &serde_json::Map<String, Json>,data: &Json,+ created_at_ms: i64,) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {+ self.hydrate_optimistic().await?;let doc = Self::document(&mut self.docs, query)?;let op = doc.operation(operation_name)?;let updates = normalize(op, variables, data)?;@@ -434,18 +497,35 @@ impl<S: Storage> Engine<S> {let candidates: BTreeSet<EntityKey> = updates.keys().cloned().collect();let bases = self.load_bases(&candidates).await?;let before = effective_records(&bases, &self.optimistic, &candidates);-- self.next_transaction += 1;- let id = self.next_transaction;- self.optimistic.push(OptimisticLayer {- id,- state: OptimisticLayerState::Pending { updates },- });+ let identity = match self.bound_identity().await? {+ IdentityState::Bound(identity) => Some(identity),+ IdentityState::NotHydrated | IdentityState::Missing => None,+ };+ let id = self+ .storage+ .enqueue_mutation(NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: query.to_string(),+ operation_name: operation_name.map(str::to_string),+ variables_json: canonical_json(&Json::Object(variables.clone())),+ identity,+ },+ created_at_ms,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: canonical_json(data),+ normalized_updates: updates.clone(),+ },+ })+ .await+ .map_err(EngineError::Storage)?;+ self.optimistic.push(OptimisticLayer { id, updates });let after = effective_records(&bases, &self.optimistic, &candidates);let changed: BTreeSet<EntityKey> = candidates.into_iter()- .filter(|k| before.get(k) != after.get(k))+ .filter(|key| before.get(key) != after.get(key)).collect();let mut affected_ops = self.deps.ops_for_keys(changed.iter());if let Some(origin) = origin_op {@@ -461,116 +541,134 @@ impl<S: Storage> Engine<S> {))}- /// Replaces a pending layer's optimistic updates with the normalized- /// real network response and marks it succeeded — atomically, so- /// dependents never flicker back to pre-optimistic data. Flushes the- /// contiguous settled prefix of layers into durable storage.- ///- /// The returned `changed` keys are the *durably* changed records (for- /// cross-instance broadcast); `affected_ops` are the operations whose- /// effective visible data changed (for local re-execution).+ /// Claims the oldest runnable mutation. A leased or backed-off head+ /// blocks every later mutation.+ pub async fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> Result<Option<ClaimedMutation>, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;+ self.storage+ .claim_next_mutation(request)+ .await+ .map_err(EngineError::Storage)+ }++ /// Releases a retryable mutation while retaining its optimistic layer.+ pub async fn defer_optimistic_write(+ &mut self,+ transaction: OptimisticTransactionId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<(), EngineError<S::Error>> {+ self.hydrate_optimistic().await?;+ if !self+ .storage+ .defer_mutation(transaction, claim, next_attempt_at_ms, error)+ .await+ .map_err(EngineError::Storage)?+ {+ return Err(EngineError::StaleMutationClaim(transaction));+ }+ Ok(())+ }++ /// Replaces the claimed head's optimistic contribution with the real+ /// network response without flickering through the pre-mutation value.+ /// Real records and queue deletion commit in one storage transaction.pub async fn commit_optimistic_write(&mut self,transaction: OptimisticTransactionId,+ claim: MutationClaimToken,query: &str,operation_name: Option<&str>,variables: &serde_json::Map<String, Json>,data: &Json,) -> Result<WriteResult, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;+ let index = self+ .optimistic+ .iter()+ .position(|layer| layer.id == transaction)+ .ok_or(EngineError::UnknownTransaction(transaction))?;let doc = Self::document(&mut self.docs, query)?;let op = doc.operation(operation_name)?;let updates = normalize(op, variables, data)?;- self.settle_layer(transaction, OptimisticLayerState::Succeeded { updates })- .await- }- /// Marks a pending layer failed, removing its contribution from the- /// effective view, and flushes any now-contiguous settled prefix. The- /// failed layer remains an ordered tombstone until all earlier layers- /// settle. Result semantics match- /// [`commit_optimistic_write`](Self::commit_optimistic_write).- pub async fn rollback_optimistic_write(- &mut self,- transaction: OptimisticTransactionId,- ) -> Result<WriteResult, EngineError<S::Error>> {- self.settle_layer(transaction, OptimisticLayerState::Failed)+ let mut candidates: BTreeSet<EntityKey> =+ self.optimistic[index].updates.keys().cloned().collect();+ candidates.extend(updates.keys().cloned());+ let bases = self.load_bases(&candidates).await?;+ let before = effective_records(&bases, &self.optimistic, &candidates);+ let (durable_changed, entries) = stage_updates(&bases, updates);+ if !self+ .storage+ .complete_mutation(transaction, claim, entries.clone()).await+ .map_err(EngineError::Storage)?+ {+ return Err(EngineError::StaleMutationClaim(transaction));+ }++ let mut settled_bases = bases;+ for (key, record) in entries {+ settled_bases.insert(key.clone(), record.clone());+ self.hot.put(key, record);+ }+ self.optimistic.remove(index);+ let after = effective_records(&settled_bases, &self.optimistic, &candidates);+ let visible_changed: BTreeSet<EntityKey> = candidates+ .into_iter()+ .filter(|key| before.get(key) != after.get(key))+ .collect();+ let affected_ops = self.deps.ops_for_keys(visible_changed.iter());+ Ok(WriteResult {+ changed: durable_changed,+ affected_ops,+ reset: false,+ })}- async fn settle_layer(+ /// Permanently fails the claimed head, atomically removing its queue row+ /// and optimistic layer.+ pub async fn rollback_optimistic_write(&mut self,transaction: OptimisticTransactionId,- new_state: OptimisticLayerState,+ claim: MutationClaimToken,) -> Result<WriteResult, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;let index = self.optimistic.iter()- .position(|l| l.id == transaction && !l.settled())+ .position(|layer| layer.id == transaction).ok_or(EngineError::UnknownTransaction(transaction))?;-- // Keys whose effective value may change: everything the old- // (optimistic) or new (real) updates touch.- let mut candidates: BTreeSet<EntityKey> = self.optimistic[index]- .updates()- .map(|u| u.keys().cloned().collect())- .unwrap_or_default();- if let OptimisticLayerState::Succeeded { updates } = &new_state {- candidates.extend(updates.keys().cloned());- }-+ let candidates: BTreeSet<EntityKey> =+ self.optimistic[index].updates.keys().cloned().collect();let bases = self.load_bases(&candidates).await?;let before = effective_records(&bases, &self.optimistic, &candidates);- self.optimistic[index].state = new_state;+ if !self+ .storage+ .discard_mutation(transaction, claim)+ .await+ .map_err(EngineError::Storage)?+ {+ return Err(EngineError::StaleMutationClaim(transaction));+ }+ self.optimistic.remove(index);let after = effective_records(&bases, &self.optimistic, &candidates);let visible_changed: BTreeSet<EntityKey> = candidates.into_iter()- .filter(|k| before.get(k) != after.get(k))+ .filter(|key| before.get(key) != after.get(key)).collect();-- // Flush the contiguous settled prefix into durable storage. The- // flushed data was already visible through the layers, so this does- // not change the effective view and adds no local notifications;- // the durably changed keys it returns drive cross-instance- // broadcasts.- let durable_changed = self.flush_settled_prefix().await?;-let affected_ops = self.deps.ops_for_keys(visible_changed.iter());Ok(WriteResult {- changed: durable_changed,+ changed: BTreeSet::new(),affected_ops,reset: false,})}- /// Persists and drops the leading run of settled layers. Succeeded- /// layers' updates merge into durable storage (in layer order); failed- /// layers are dropped. Later pending layers keep overriding the newly- /// committed base, preserving order under out-of-order settlement.- async fn flush_settled_prefix(&mut self) -> Result<BTreeSet<EntityKey>, EngineError<S::Error>> {- let mut merged = RecordUpdates::new();- let mut count = 0;- for layer in &self.optimistic {- if !layer.settled() {- break;- }- if let Some(updates) = layer.updates() {- for (key, record) in updates {- merged.entry(key.clone()).or_default().merge(record.clone());- }- }- count += 1;- }- if count == 0 {- return Ok(BTreeSet::new());- }- self.optimistic.drain(..count);- if merged.is_empty() {- // Prefix was all tombstones.- return Ok(BTreeSet::new());- }- self.persist_updates(merged).await- }-/// Loads current durable records (hot tier, then storage) for `keys`/// without touching LRU recency or persisting anything.async fn load_bases(@@ -608,9 +706,10 @@ impl<S: Storage> Engine<S> {pub fn external_reset(&mut self) -> BTreeSet<OpId> {self.hot.clear();self.docs.clear();- // Optimistic layers were normalized against the wiped base.self.optimistic.clear();- // Another engine may have rebound the shared storage → re-hydrate.+ // Another engine may have rebound the shared storage and changed the+ // durable queue, so both identity and optimism must re-hydrate.+ self.optimistic_hydrated = false;self.identity = IdentityState::NotHydrated;self.deps.all_ops()}@@ -641,6 +740,7 @@ impl<S: Storage> Engine<S> {pub async fn clear(&mut self) -> Result<(), EngineError<S::Error>> {self.hot.clear();self.optimistic.clear();+ self.optimistic_hydrated = true;self.deps = DepIndex::new();// The wipe below removes the binding record too.self.identity = IdentityState::Missing;@@ -697,15 +797,41 @@ impl RecordSource for EngineSource<'_> {fn merged_optimistic(layers: &[OptimisticLayer]) -> BTreeMap<EntityKey, Record> {let mut out: BTreeMap<EntityKey, Record> = BTreeMap::new();for layer in layers {- if let Some(updates) = layer.updates() {- for (key, record) in updates {- out.entry(key.clone()).or_default().merge(record.clone());- }+ for (key, record) in &layer.updates {+ out.entry(key.clone()).or_default().merge(record.clone());}}out}+/// Merges partial response updates into already-loaded durable bases without+/// mutating the hot tier or storage. The caller can then atomically settle a+/// queued mutation before publishing the staged records in memory.+fn stage_updates(+ bases: &HashMap<EntityKey, Record>,+ updates: RecordUpdates,+) -> (BTreeSet<EntityKey>, Vec<(EntityKey, Record)>) {+ let mut changed = BTreeSet::new();+ let mut entries = Vec::with_capacity(updates.len());+ for (key, update) in updates {+ let merged = match bases.get(&key) {+ Some(existing) => {+ let mut merged = existing.clone();+ if merged.merge(update) {+ changed.insert(key.clone());+ }+ merged+ }+ None => {+ changed.insert(key.clone());+ update+ }+ };+ entries.push((key, merged));+ }+ (changed, entries)+}+/// Effective visible records for `keys`: durable base + every active layer/// merged in order. `None` when the key exists nowhere.fn effective_records(@@ -717,7 +843,7 @@ fn effective_records(.map(|key| {let mut record: Option<Record> = bases.get(key).cloned();for layer in layers {- if let Some(update) = layer.updates().and_then(|u| u.get(key)) {+ if let Some(update) = layer.updates.get(key) {record.get_or_insert_with(Record::default).merge(update.clone());diff --git a/crates/client/cache-core/src/lib.rs b/crates/client/cache-core/src/lib.rsindex 73dbd9fb03..64bda7a914 100644--- a/crates/client/cache-core/src/lib.rs+++ b/crates/client/cache-core/src/lib.rs@@ -9,5 +9,6 @@ pub mod document;pub mod engine;pub mod meta;pub mod normalize;+pub mod queue;pub mod store;pub mod value;diff --git a/crates/client/cache-core/src/queue.rs b/crates/client/cache-core/src/queue.rsnew file mode 100644index 0000000000..aec8f3c5be--- /dev/null+++ b/crates/client/cache-core/src/queue.rs@@ -0,0 +1,121 @@+//! Durable optimistic-mutation queue models.+//!+//! The cache engine owns mutation ordering and optimistic composition; storage+//! backends persist these transport-neutral values atomically. Authentication+//! credentials and urql operation context are deliberately excluded: replay+//! reconstructs an operation using the current client configuration.++use crate::normalize::RecordUpdates;+use serde::{Deserialize, Serialize};++/// Durable, monotonically increasing mutation identifier and queue position.+pub type MutationId = u64;++/// The serializable portion of a GraphQL mutation needed for replay.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct MutationRequest {+ /// GraphQL mutation document text.+ pub query: String,+ /// Selected operation when the document contains named operations.+ pub operation_name: Option<String>,+ /// Canonical JSON object containing the mutation variables.+ pub variables_json: String,+ /// Opaque identity witness bound when the mutation was enqueued.+ pub identity: Option<String>,+}++/// Persisted retry and lease state for one queued mutation.+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]+pub struct StoredMutation {+ /// Replayable GraphQL request.+ pub request: MutationRequest,+ /// Number of times this mutation has been claimed for a network attempt.+ pub attempt_count: u32,+ /// Earliest wall-clock time at which the head may be claimed again.+ pub next_attempt_at_ms: Option<i64>,+ /// Owner of the current claim, if any.+ pub lease_owner: Option<String>,+ /// Monotonic generation used to reject stale attempt results.+ pub lease_generation: u64,+ /// Time at which the current claim becomes available to another owner.+ pub lease_expires_at_ms: Option<i64>,+ /// Last retryable network error, for diagnostics.+ pub last_error: Option<String>,+ /// Wall-clock enqueue time, for diagnostics.+ pub created_at_ms: i64,+}++impl StoredMutation {+ /// Creates an unclaimed queue row for `request`.+ pub fn new(request: MutationRequest, created_at_ms: i64) -> Self {+ Self {+ request,+ attempt_count: 0,+ next_attempt_at_ms: None,+ lease_owner: None,+ lease_generation: 0,+ lease_expires_at_ms: None,+ last_error: None,+ created_at_ms,+ }+ }+}++/// One durable optimistic layer paired one-to-one with a queued mutation.+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]+pub struct PersistedOptimisticLayer {+ /// Canonical JSON optimistic response, retained for re-normalization after+ /// a record-schema change.+ pub optimistic_data_json: String,+ /// Normalized contribution used to hydrate the effective cache view.+ pub normalized_updates: RecordUpdates,+}++/// A mutation and optimistic layer before storage assigns its queue id.+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]+pub struct NewQueuedMutation {+ /// Mutation request plus initial retry metadata.+ pub mutation: StoredMutation,+ /// Optimistic contribution paired with the mutation.+ pub optimistic: PersistedOptimisticLayer,+}++/// One complete durable queue entry.+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]+pub struct QueuedMutation {+ /// Durable queue id and ordering key.+ pub id: MutationId,+ /// Mutation request and retry metadata.+ pub mutation: StoredMutation,+ /// Optimistic contribution paired with the mutation.+ pub optimistic: PersistedOptimisticLayer,+}++/// Successful claim of the oldest runnable mutation.+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]+pub struct ClaimedMutation {+ /// Claimed queue entry, including updated attempt and lease metadata.+ pub queued: QueuedMutation,+ /// Generation that settlement calls must present.+ pub lease_generation: u64,+}++/// Parameters for claiming the strict queue head.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct MutationClaimRequest {+ /// Stable owner id for one queue runner.+ pub owner: String,+ /// Current wall-clock time.+ pub now_ms: i64,+ /// Absolute expiration time for the new lease.+ pub lease_expires_at_ms: i64,+}++/// Identifies the attempt allowed to settle or defer a mutation.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct MutationClaimToken {+ /// Stable owner id supplied at claim time.+ pub owner: String,+ /// Lease generation returned by the successful claim.+ pub generation: u64,+}diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rsindex 4606ccfc65..e9c7148108 100644--- a/crates/client/cache-core/src/store.rs+++ b/crates/client/cache-core/src/store.rs@@ -6,9 +6,13 @@//! from a multi-threaded runtime), unbounded on wasm — wasm futures aren't//! `Send`.+use crate::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,+ QueuedMutation,+};use crate::value::{EntityKey, Record};use maybe_send::MaybeSend;-use std::collections::HashMap;+use std::collections::{BTreeMap, HashMap};use std::convert::Infallible;/// Async KV over normalized records. Batch-oriented by design: the engine@@ -34,7 +38,54 @@ pub trait Storage: MaybeSend {keys: &[EntityKey],) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;- /// Drops everything (logout / corruption rebuild).+ /// Atomically appends a mutation and its optimistic layer to the queue.+ fn enqueue_mutation(+ &mut self,+ entry: NewQueuedMutation,+ ) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend;++ /// Loads the complete mutation queue in ascending id order.+ fn load_mutation_queue(+ &self,+ ) -> impl Future<Output = Result<Vec<QueuedMutation>, Self::Error>> + MaybeSend;++ /// Claims the oldest mutation when it is runnable and not actively leased.+ /// Later mutations are never skipped.+ fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> impl Future<Output = Result<Option<ClaimedMutation>, Self::Error>> + MaybeSend;++ /// Retains a retryable mutation and its optimistic layer, releases its+ /// lease, and records the next eligible attempt time. Returns `false`+ /// when the claim is stale.+ fn defer_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;++ /// Atomically writes the real response records and removes the mutation+ /// plus optimistic layer. Returns `false` when the claim is stale.+ fn complete_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ entries: Vec<(EntityKey, Record)>,+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;++ /// Atomically removes a permanently failed mutation and its optimistic+ /// layer. Returns `false` when the claim is stale.+ fn discard_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ ) -> impl Future<Output = Result<bool, Self::Error>> + MaybeSend;++ /// Drops records, queued mutations, and optimistic layers (logout or+ /// identity mismatch).fn clear(&mut self) -> impl Future<Output = Result<(), Self::Error>> + MaybeSend;}@@ -42,6 +93,14 @@ pub trait Storage: MaybeSend {#[derive(Debug, Default)]pub struct InMemoryStorage {records: HashMap<EntityKey, Record>,+ mutations: BTreeMap<+ MutationId,+ (+ crate::queue::StoredMutation,+ crate::queue::PersistedOptimisticLayer,+ ),+ >,+ next_mutation_id: MutationId,}impl InMemoryStorage {@@ -79,8 +138,124 @@ impl Storage for InMemoryStorage {Ok(())}+ async fn enqueue_mutation(+ &mut self,+ entry: NewQueuedMutation,+ ) -> Result<MutationId, Self::Error> {+ self.next_mutation_id += 1;+ let id = self.next_mutation_id;+ self.mutations+ .insert(id, (entry.mutation, entry.optimistic));+ Ok(id)+ }++ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {+ Ok(self+ .mutations+ .iter()+ .map(|(id, (mutation, optimistic))| QueuedMutation {+ id: *id,+ mutation: mutation.clone(),+ optimistic: optimistic.clone(),+ })+ .collect())+ }++ async fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> Result<Option<ClaimedMutation>, Self::Error> {+ let Some((&id, (mutation, optimistic))) = self.mutations.iter_mut().next() else {+ return Ok(None);+ };+ if mutation+ .next_attempt_at_ms+ .is_some_and(|next| next > request.now_ms)+ || mutation+ .lease_expires_at_ms+ .is_some_and(|expiry| expiry > request.now_ms)+ {+ return Ok(None);+ }++ mutation.attempt_count = mutation.attempt_count.saturating_add(1);+ mutation.lease_generation = mutation.lease_generation.saturating_add(1);+ mutation.lease_owner = Some(request.owner);+ mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);+ mutation.next_attempt_at_ms = None;+ let generation = mutation.lease_generation;+ Ok(Some(ClaimedMutation {+ queued: QueuedMutation {+ id,+ mutation: mutation.clone(),+ optimistic: optimistic.clone(),+ },+ lease_generation: generation,+ }))+ }++ async fn defer_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<bool, Self::Error> {+ let Some((mutation, _)) = self.mutations.get_mut(&id) else {+ return Ok(false);+ };+ if !claim_matches(mutation, &claim) {+ return Ok(false);+ }+ mutation.next_attempt_at_ms = Some(next_attempt_at_ms);+ mutation.last_error = Some(error);+ mutation.lease_owner = None;+ mutation.lease_expires_at_ms = None;+ Ok(true)+ }++ async fn complete_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ entries: Vec<(EntityKey, Record)>,+ ) -> Result<bool, Self::Error> {+ let Some((mutation, _)) = self.mutations.get(&id) else {+ return Ok(false);+ };+ if !claim_matches(mutation, &claim) {+ return Ok(false);+ }+ for (key, record) in entries {+ self.records.insert(key, record);+ }+ self.mutations.remove(&id);+ Ok(true)+ }++ async fn discard_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ ) -> Result<bool, Self::Error> {+ let Some((mutation, _)) = self.mutations.get(&id) else {+ return Ok(false);+ };+ if !claim_matches(mutation, &claim) {+ return Ok(false);+ }+ self.mutations.remove(&id);+ Ok(true)+ }+async fn clear(&mut self) -> Result<(), Self::Error> {self.records.clear();+ self.mutations.clear();Ok(())}}++fn claim_matches(mutation: &crate::queue::StoredMutation, claim: &MutationClaimToken) -> bool {+ mutation.lease_owner.as_deref() == Some(&claim.owner)+ && mutation.lease_generation == claim.generation+}diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rsnew file mode 100644index 0000000000..1a98ab68cc--- /dev/null+++ b/crates/client/cache-core/tests/mutation_queue.rs@@ -0,0 +1,133 @@+use cache_core::queue::{+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,+ PersistedOptimisticLayer, StoredMutation,+};+use cache_core::store::{InMemoryStorage, Storage};+use cache_core::value::{CacheValue, EntityKey, Record};+use pollster::block_on;++fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {+ let mut update = Record::default();+ update+ .fields+ .insert("name".into(), CacheValue::String(value.into()));+ NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: "mutation Rename { rename { id } }".into(),+ operation_name: Some("Rename".into()),+ variables_json: format!(r#"{{"name":"{value}"}}"#),+ identity: Some("user-1".into()),+ },+ created_at_ms,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: format!(r#"{{"rename":{{"name":"{value}"}}}}"#),+ normalized_updates: [(EntityKey("Thing:1".into()), update)].into(),+ },+ }+}++#[test]+fn queue_claim_retry_and_settlement_are_ordered() {+ block_on(async {+ let mut storage = InMemoryStorage::new();+ let first = storage.enqueue_mutation(queued("a", 1)).await.unwrap();+ let second = storage.enqueue_mutation(queued("b", 2)).await.unwrap();+ assert!(first < second);++ let loaded = storage.load_mutation_queue().await.unwrap();+ assert_eq!(+ loaded.iter().map(|entry| entry.id).collect::<Vec<_>>(),+ [first, second]+ );++ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-1".into(),+ now_ms: 10,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(claimed.queued.id, first);+ assert_eq!(claimed.queued.mutation.attempt_count, 1);++ // The leased head blocks every later mutation.+ assert!(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-2".into(),+ now_ms: 20,+ lease_expires_at_ms: 120,+ })+ .await+ .unwrap()+ .is_none()+ );++ assert!(+ storage+ .defer_mutation(+ first,+ MutationClaimToken {+ owner: "runner-1".into(),+ generation: claimed.lease_generation,+ },+ 200,+ "offline".into(),+ )+ .await+ .unwrap()+ );+ assert!(+ storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-2".into(),+ now_ms: 199,+ lease_expires_at_ms: 300,+ })+ .await+ .unwrap()+ .is_none()+ );++ let retried = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner-2".into(),+ now_ms: 200,+ lease_expires_at_ms: 300,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(retried.queued.id, first);+ assert_eq!(retried.queued.mutation.attempt_count, 2);++ let mut real = Record::default();+ real.fields+ .insert("name".into(), CacheValue::String("server".into()));+ assert!(+ storage+ .complete_mutation(+ first,+ MutationClaimToken {+ owner: "runner-2".into(),+ generation: retried.lease_generation,+ },+ vec![(EntityKey("Thing:1".into()), real.clone())],+ )+ .await+ .unwrap()+ );+ assert_eq!(+ storage+ .get_batch(&[EntityKey("Thing:1".into())])+ .await+ .unwrap()[0],+ Some(real)+ );+ assert_eq!(storage.load_mutation_queue().await.unwrap()[0].id, second);+ });+}diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rsindex 6d67a7614f..488e0266de 100644--- a/crates/client/cache-core/tests/optimistic.rs+++ b/crates/client/cache-core/tests/optimistic.rs@@ -1,9 +1,10 @@-//! Optimistic mutation layer tests: begin/read/commit/rollback, out-of-order-//! settlement, layer composition, durable isolation, and lifecycle resets.+//! Durable optimistic mutation tests: enqueue/read/claim/retry/commit/fail,+//! strict ordering, and lifecycle resets.use cache_core::engine::{Engine, EngineError, ReadResult};-use cache_core::store::InMemoryStorage;-use cache_core::value::EntityKey;+use cache_core::queue::{MutationClaimRequest, MutationClaimToken};+use cache_core::store::{InMemoryStorage, Storage};+use cache_core::value::{CacheValue, EntityKey};use pollster::block_on;use serde_json::{Value as Json, json};@@ -110,7 +111,6 @@ fn mutation_response(display_name: &str, value: &str) -> Json {})}-/// Reads the property object out of a soup query hit.fn property_of(data: &Json) -> &Json {&data["user"]["soup"]["items"][0]["entity"]["properties"][0]}@@ -142,494 +142,257 @@ async fn read_hit(engine: &mut Engine<InMemoryStorage>, op: Option<u64>) -> Json}}-/// The durable (storage) value of the property record's displayName, read-/// directly from the underlying store — bypassing optimistic layers.-async fn durable_display_name(engine: &Engine<InMemoryStorage>) -> Option<String> {- use cache_core::store::Storage;- use cache_core::value::CacheValue;+async fn claim_head(+ engine: &mut Engine<InMemoryStorage>,+ owner: &str,+ now_ms: i64,+) -> (u64, MutationClaimToken) {+ let claimed = engine+ .claim_next_mutation(MutationClaimRequest {+ owner: owner.into(),+ now_ms,+ lease_expires_at_ms: now_ms + 1_000,+ })+ .await+ .unwrap()+ .expect("queue head");+ let id = claimed.queued.id;+ (+ id,+ MutationClaimToken {+ owner: owner.into(),+ generation: claimed.lease_generation,+ },+ )+}++async fn durable_value(engine: &Engine<InMemoryStorage>) -> Option<String> {let records = engine.storage().get_batch(&[EntityKey(PROPERTY_KEY.to_string())]).await.unwrap();- records- .into_iter()- .next()- .flatten()- .and_then(|record| match record.fields.get("displayName") {- Some(CacheValue::String(s)) => Some(s.clone()),- _ => None,- })-}--#[test]-fn network_mutation_without_layer_writes_through() {- block_on(async {- let mut engine = engine_with_base("Status", "todo").await;- // Register op 1 on the soup query.- read_hit(&mut engine, Some(1)).await;-- // A plain (non-optimistic) mutation response normalizes into the- // same records and notifies dependents.- let write = engine- .write_query(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("done"),- &mutation_response("Status", "done"),- None,- )- .await- .unwrap();- assert!(write.changed.contains(&EntityKey(PROPERTY_KEY.to_string())));- assert!(write.affected_ops.contains(&1));- // Mutation root fields are transient: nothing lands on ROOT_QUERY.- assert!(!write.changed.iter().any(|k| k.is_root()));-- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("done"));- assert_eq!(- durable_display_name(&engine).await.as_deref(),- Some("Status")- );- });-}--#[test]-fn reads_reject_mutation_documents() {- block_on(async {- let mut engine = Engine::new(InMemoryStorage::new());- let err = engine- .read_query(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("x"),- )- .await- .unwrap_err();- assert!(matches!(err, EngineError::Document(_)));- });-}--#[test]-fn begin_composes_over_base_without_persisting() {- block_on(async {- let mut engine = engine_with_base("Status", "todo").await;- read_hit(&mut engine, Some(1)).await;-- let (txn, begin) = engine- .begin_optimistic_write(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("doing"),- &mutation_response("Status", "doing"),- )- .await- .unwrap();- assert!(txn > 0);- assert!(begin.changed.contains(&EntityKey(PROPERTY_KEY.to_string())));- assert!(begin.affected_ops.contains(&1));- assert!(!begin.reset);-- // Reads see the optimistic value; durable state is untouched.- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));- use cache_core::store::Storage;- use cache_core::value::CacheValue;- let stored = engine- .storage()- .get_batch(&[EntityKey(PROPERTY_KEY.to_string())])- .await- .unwrap();- let stored = stored.into_iter().next().flatten().unwrap();- let Some(CacheValue::Object(value)) = stored.fields.get("value") else {- panic!("stored value shape");- };- assert_eq!(value.get("value"), Some(&CacheValue::String("todo".into())));- });-}--#[test]-fn begin_with_identical_data_notifies_nobody() {- block_on(async {- let mut engine = engine_with_base("Status", "todo").await;- read_hit(&mut engine, Some(1)).await;-- // Optimistic response identical to the cached data → the effective- // view is unchanged, nobody re-executes.- let (_, begin) = engine- .begin_optimistic_write(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("todo"),- &mutation_response("Status", "todo"),- )- .await- .unwrap();- assert!(begin.changed.is_empty());- assert!(begin.affected_ops.is_empty());- });+ let record = records.into_iter().next().flatten()?;+ let CacheValue::Object(value) = record.fields.get("value")? else {+ return None;+ };+ match value.get("value") {+ Some(CacheValue::String(value)) => Some(value.clone()),+ _ => None,+ }}#[test]-fn commit_replaces_layer_and_flushes_durably() {+fn begin_persists_mutation_and_optimistic_layer() {block_on(async {let mut engine = engine_with_base("Status", "todo").await;read_hit(&mut engine, Some(1)).await;-- let (txn, _) = engine+ let (transaction, result) = engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("doing"),&mutation_response("Status", "doing"),+ 123,).await.unwrap();- // The network result differs from the optimistic response.- let commit = engine- .commit_optimistic_write(- txn,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("doing"),- &mutation_response("Status (renamed)", "doing"),- )- .await- .unwrap();- // Durable flush happened (single layer = contiguous prefix).- assert!(- commit- .changed- .contains(&EntityKey(PROPERTY_KEY.to_string()))- );- // displayName's visible value changed with the real response.- assert!(commit.affected_ops.contains(&1));-- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["displayName"], json!("Status (renamed)"));- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));+ assert!(result.affected_ops.contains(&1));+ let queued = engine.storage().load_mutation_queue().await.unwrap();+ assert_eq!(queued.len(), 1);+ assert_eq!(queued[0].id, transaction);+ assert_eq!(queued[0].mutation.created_at_ms, 123);assert_eq!(- durable_display_name(&engine).await.as_deref(),- Some("Status (renamed)")+ queued[0].mutation.request.operation_name.as_deref(),+ Some("SetEntityProperty"));- // Settled transactions are gone: settling again is an error.- assert!(matches!(- engine.rollback_optimistic_write(txn).await,- Err(EngineError::UnknownTransaction(_))- ));+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));+ assert_eq!(durable_value(&engine).await.as_deref(), Some("todo"));});}#[test]-fn commit_matching_optimistic_response_is_silent() {+fn claimed_success_atomically_commits_real_response() {block_on(async {let mut engine = engine_with_base("Status", "todo").await;read_hit(&mut engine, Some(1)).await;-- let (txn, _) = engine+ let (transaction, _) = engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("doing"),&mutation_response("Status", "doing"),+ 0,).await.unwrap();- let commit = engine+ let (claimed_id, claim) = claim_head(&mut engine, "runner", 10).await;+ assert_eq!(claimed_id, transaction);++ let result = engine.commit_optimistic_write(- txn,+ transaction,+ claim,MUTATION,Some("SetEntityProperty"),&mutation_vars("doing"),- &mutation_response("Status", "doing"),+ &mutation_response("Status (server)", "done"),).await.unwrap();- // Visible data did not change (real == optimistic) → no local- // notifications; durable keys still broadcast for other instances.- assert!(commit.affected_ops.is_empty());+ assert!(result.changed.contains(&EntityKey(PROPERTY_KEY.into())));+ assert!(result.affected_ops.contains(&1));assert!(- commit- .changed- .contains(&EntityKey(PROPERTY_KEY.to_string()))+ engine+ .storage()+ .load_mutation_queue()+ .await+ .unwrap()+ .is_empty());- });-}--#[test]-fn rollback_restores_base_view() {- block_on(async {- let mut engine = engine_with_base("Status", "todo").await;- read_hit(&mut engine, Some(1)).await;+ assert_eq!(durable_value(&engine).await.as_deref(), Some("done"));- let (txn, _) = engine- .begin_optimistic_write(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("doing"),- &mutation_response("Status", "doing"),- )- .await- .unwrap();- let rollback = engine.rollback_optimistic_write(txn).await.unwrap();- assert!(rollback.affected_ops.contains(&1));- // Nothing was ever durable, nothing flushed.- assert!(rollback.changed.is_empty());-- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("todo"));- assert_eq!(- durable_display_name(&engine).await.as_deref(),- Some("Status")- );+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["displayName"], json!("Status (server)"));+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("done"));});}#[test]-fn out_of_order_settlement_preserves_later_layer() {+fn retryable_failure_keeps_optimistic_layer_and_blocks_later_mutations() {block_on(async {let mut engine = engine_with_base("Status", "todo").await;- read_hit(&mut engine, Some(1)).await;-- // A then B target the same field.- let (txn_a, _) = engine+ let (first, _) = engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("a"),&mutation_response("Status", "a"),+ 0,).await.unwrap();- let (txn_b, _) = engine+ let (second, _) = engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("b"),&mutation_response("Status", "b"),+ 1,).await.unwrap();- assert_ne!(txn_a, txn_b);+ assert!(first < second);- // B settles first: nothing flushes (A still pending ahead of it),- // and B's real value stays visible over A's pending layer.- let commit_b = engine- .commit_optimistic_write(- txn_b,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("b"),- &mutation_response("Status", "b!"),- )- .await- .unwrap();- assert!(commit_b.changed.is_empty(), "no durable flush yet");- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("b!"));- assert_eq!(- durable_display_name(&engine).await.as_deref(),- Some("Status")- );-- // A settles second: settling the earlier layer must not clobber the- // later one. The visible value stays B's; the flush persists both in- // order (B's response wins the shared field).- let commit_a = engine- .commit_optimistic_write(- txn_a,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("a"),- &mutation_response("Status", "a!"),- )+ let (_, claim) = claim_head(&mut engine, "runner", 10).await;+ engine+ .defer_optimistic_write(first, claim, 100, "offline".into()).await.unwrap();- assert!(commit_a.affected_ops.is_empty(), "visible data unchanged");assert!(- commit_a- .changed- .contains(&EntityKey(PROPERTY_KEY.to_string()))+ engine+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 99,+ lease_expires_at_ms: 200,+ })+ .await+ .unwrap()+ .is_none()+ );+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));+ assert_eq!(+ engine.storage().load_mutation_queue().await.unwrap().len(),+ 2);-- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("b!"));});}#[test]-fn rollback_of_earlier_layer_keeps_later_success() {+fn permanent_failure_rolls_back_only_the_claimed_head() {block_on(async {let mut engine = engine_with_base("Status", "todo").await;- read_hit(&mut engine, Some(1)).await;-- let (txn_a, _) = engine+ let (first, _) = engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("a"),&mutation_response("Status", "a"),+ 0,).await.unwrap();- let (txn_b, _) = engine+ engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("b"),&mutation_response("Status", "b"),+ 1,).await.unwrap();-- // B succeeds first; A then fails. The failed tombstone unblocks the- // prefix and B's real response is what persists.- engine- .commit_optimistic_write(- txn_b,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("b"),- &mutation_response("Status", "b!"),- )+ let (_, claim) = claim_head(&mut engine, "runner", 10).await;+ let result = engine+ .rollback_optimistic_write(first, claim).await.unwrap();- let rollback = engine.rollback_optimistic_write(txn_a).await.unwrap();- // A's contribution was masked by B → visible data unchanged.- assert!(rollback.affected_ops.is_empty());- // The flush persisted B's committed layer.- assert!(- rollback- .changed- .contains(&EntityKey(PROPERTY_KEY.to_string()))+ // The later layer masks the failed head, so the visible view is stable.+ assert!(result.affected_ops.is_empty());+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));+ assert_eq!(+ engine.storage().load_mutation_queue().await.unwrap().len(),+ 1);-- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("b!"));});}#[test]-fn different_fields_on_same_record_compose() {+fn stale_claim_cannot_settle_mutation() {block_on(async {let mut engine = engine_with_base("Status", "todo").await;- read_hit(&mut engine, Some(1)).await;-- // Layer A renames; layer B (pending) changes the value.- let (txn_a, _) = engine- .begin_optimistic_write(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("todo"),- &mutation_response("Stage", "todo"),- )- .await- .unwrap();- let (_txn_b, _) = engine+ let (transaction, _) = engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("doing"),- &mutation_response("Stage", "doing"),+ &mutation_response("Status", "doing"),+ 0,).await.unwrap();-- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["displayName"], json!("Stage"));- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));-- // A commits while B remains pending: B's pending layer stays- // visible over the committed base.- engine- .commit_optimistic_write(- txn_a,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("todo"),- &mutation_response("Stage", "todo"),+ let error = engine+ .rollback_optimistic_write(+ transaction,+ MutationClaimToken {+ owner: "wrong".into(),+ generation: 1,+ },).await- .unwrap();- let data = read_hit(&mut engine, Some(1)).await;- assert_eq!(property_of(&data)["value"]["stringValue"], json!("doing"));+ .unwrap_err();+ assert!(matches!(error, EngineError::StaleMutationClaim(id) if id == transaction));assert_eq!(- durable_display_name(&engine).await.as_deref(),- Some("Stage")+ engine.storage().load_mutation_queue().await.unwrap().len(),+ 1);});}#[test]-fn unknown_transaction_ids_error() {- block_on(async {- let mut engine = Engine::new(InMemoryStorage::new());- assert!(matches!(- engine.rollback_optimistic_write(42).await,- Err(EngineError::UnknownTransaction(42))- ));- assert!(matches!(- engine- .commit_optimistic_write(- 7,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("x"),- &mutation_response("Status", "x"),- )- .await,- Err(EngineError::UnknownTransaction(7))- ));- });-}--#[test]-fn clear_discards_pending_layers() {- block_on(async {- let mut engine = engine_with_base("Status", "todo").await;- let (txn, _) = engine- .begin_optimistic_write(- None,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("doing"),- &mutation_response("Status", "doing"),- )- .await- .unwrap();-- engine.clear().await.unwrap();- let read = engine- .read_query(None, QUERY, Some("Soup"), &query_vars())- .await- .unwrap();- assert!(matches!(read, ReadResult::Miss));- // The layer is gone; settling it later is an error, never a write.- assert!(matches!(- engine.rollback_optimistic_write(txn).await,- Err(EngineError::UnknownTransaction(_))- ));- });-}--#[test]-fn identity_reset_discards_pending_layers() {+fn clear_and_identity_reset_drop_durable_queue() {block_on(async {let mut engine = engine_with_base("Status", "todo").await;engine@@ -643,21 +406,19 @@ fn identity_reset_discards_pending_layers() {).await.unwrap();-- let (txn, _) = engine+ engine.begin_optimistic_write(None,MUTATION,Some("SetEntityProperty"),&mutation_vars("doing"),&mutation_response("Status", "doing"),+ 0,).await.unwrap();- // A response for another user silently wipes the cache — including- // the pending optimistic layer.- let write = engine+ let reset = engine.write_query(None,QUERY,@@ -673,18 +434,24 @@ fn identity_reset_discards_pending_layers() {).await.unwrap();- assert!(write.reset);- assert!(matches!(+ assert!(reset.reset);+ assert!(engine- .commit_optimistic_write(- txn,- MUTATION,- Some("SetEntityProperty"),- &mutation_vars("doing"),- &mutation_response("Status", "doing"),- )- .await,- Err(EngineError::UnknownTransaction(_))- ));+ .storage()+ .load_mutation_queue()+ .await+ .unwrap()+ .is_empty()+ );++ engine.clear().await.unwrap();+ assert!(+ engine+ .storage()+ .load_mutation_queue()+ .await+ .unwrap()+ .is_empty()+ );});}diff --git a/crates/client/cache-idb/src/idb_storage.rs b/crates/client/cache-idb/src/idb_storage.rsindex 1098cfcb2e..de712bc44e 100644--- a/crates/client/cache-idb/src/idb_storage.rs+++ b/crates/client/cache-idb/src/idb_storage.rs@@ -1,12 +1,24 @@-use cache_core::codec::{CodecError, cache_namespace, decode_record, encode_record};+use cache_core::codec::{+ CodecError, cache_database_name, cache_namespace, decode_optimistic_layer, decode_record,+ decode_stored_mutation, encode_optimistic_layer, encode_record, encode_stored_mutation,+};+use cache_core::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,+ QueuedMutation,+};use cache_core::store::Storage;use cache_core::value::{EntityKey, Record};use idb::{Database, DatabaseEvent, Factory, ObjectStoreParams, TransactionMode};use thiserror::Error;use wasm_bindgen::{JsCast, JsValue};+const META_STORE: &str = "meta";const RECORDS_STORE: &str = "records";+const MUTATION_QUEUE_STORE: &str = "mutation_queue";+const OPTIMISTIC_LAYERS_STORE: &str = "optimistic_layers";const DB_VERSION: u32 = 1;+const SCOPE_META_KEY: &str = "scope";+const NAMESPACE_META_KEY: &str = "namespace";#[derive(Debug, Error)]pub enum IdbStorageError {@@ -16,29 +28,78 @@ pub enum IdbStorageError {Codec(#[from] CodecError),#[error("stored value is not a Uint8Array")]NotBytes,+ #[error("stored metadata is not a string")]+ NotString,+ #[error("mutation queue key is not a safe positive integer")]+ InvalidMutationId,+ #[error("mutation queue and optimistic layer stores are inconsistent")]+ InconsistentQueue,}pub struct IdbStorage {db: Database,}+fn bytes_to_js(bytes: &[u8]) -> JsValue {+ js_sys::Uint8Array::from(bytes).into()+}++fn bytes_from_js(value: JsValue) -> Result<Vec<u8>, IdbStorageError> {+ let bytes: js_sys::Uint8Array = value.dyn_into().map_err(|_| IdbStorageError::NotBytes)?;+ Ok(bytes.to_vec())+}++fn mutation_id_from_js(value: &JsValue) -> Result<MutationId, IdbStorageError> {+ const MAX_SAFE_INTEGER: f64 = 9_007_199_254_740_991.0;+ let Some(number) = value.as_f64() else {+ return Err(IdbStorageError::InvalidMutationId);+ };+ if !(1.0..=MAX_SAFE_INTEGER).contains(&number) || number.fract() != 0.0 {+ return Err(IdbStorageError::InvalidMutationId);+ }+ Ok(number as MutationId)+}++fn mutation_id_to_js(id: MutationId) -> Result<JsValue, IdbStorageError> {+ const MAX_SAFE_INTEGER: MutationId = 9_007_199_254_740_991;+ if id == 0 || id > MAX_SAFE_INTEGER {+ return Err(IdbStorageError::InvalidMutationId);+ }+ Ok(JsValue::from_f64(id as f64))+}++fn claim_matches(mutation: &cache_core::queue::StoredMutation, claim: &MutationClaimToken) -> bool {+ mutation.lease_owner.as_deref() == Some(&claim.owner)+ && mutation.lease_generation == claim.generation+}+impl IdbStorage {- /// Opens the cache database for `scope`. A schema or format change- /// yields a different database name, i.e. an implicitly fresh cache- /// (stale namespaces are garbage-collected via [`Self::destroy`] by the- /// host, or eventually by the browser under storage pressure).+ /// Opens the cache database for `scope` and initializes all stores.+ /// Record namespace changes clear only disposable records; a scope change+ /// also clears queued user intent.pub async fn open(scope: &str) -> Result<Self, IdbStorageError> {- let name = cache_namespace(scope);+ let name = cache_database_name(scope);let factory = Factory::new()?;let mut request = factory.open(&name, Some(DB_VERSION))?;request.on_upgrade_needed(|event| {let database = event.database().expect("upgrade event has database");- // Out-of-line string keys (the entity key), Uint8Array values.- // Surface setup failures immediately rather than as misleading- // "store not found" errors on later transactions.- database- .create_object_store(RECORDS_STORE, ObjectStoreParams::new())- .expect("create records object store");+ let existing = database.store_names();+ for (name, params) in [+ (META_STORE, ObjectStoreParams::new()),+ (RECORDS_STORE, ObjectStoreParams::new()),+ (MUTATION_QUEUE_STORE, {+ let mut params = ObjectStoreParams::new();+ params.auto_increment(true);+ params+ }),+ (OPTIMISTIC_LAYERS_STORE, ObjectStoreParams::new()),+ ] {+ if !existing.iter().any(|store| store == name) {+ database+ .create_object_store(name, params)+ .unwrap_or_else(|_| panic!("create {name} object store"));+ }+ }});let mut db = request.await?;// Close immediately when another context needs this database gone or@@ -51,7 +112,51 @@ impl IdbStorage {}}});- Ok(IdbStorage { db })+ let mut storage = IdbStorage { db };+ storage.initialize_namespace(scope).await?;+ Ok(storage)+ }++ async fn initialize_namespace(&mut self, scope: &str) -> Result<(), IdbStorageError> {+ let tx = self.db.transaction(+ &[+ META_STORE,+ RECORDS_STORE,+ MUTATION_QUEUE_STORE,+ OPTIMISTIC_LAYERS_STORE,+ ],+ TransactionMode::ReadWrite,+ )?;+ let meta = tx.object_store(META_STORE)?;+ let scope_request = meta.get(JsValue::from_str(SCOPE_META_KEY))?;+ let namespace_request = meta.get(JsValue::from_str(NAMESPACE_META_KEY))?;+ let stored_scope = scope_request+ .await?+ .map(|value| value.as_string().ok_or(IdbStorageError::NotString))+ .transpose()?;+ let stored_namespace = namespace_request+ .await?+ .map(|value| value.as_string().ok_or(IdbStorageError::NotString))+ .transpose()?;+ let expected_namespace = cache_namespace(scope);++ if stored_scope.as_deref() != Some(scope) {+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;+ tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;+ tx.object_store(RECORDS_STORE)?.clear()?;+ } else if stored_namespace.as_deref() != Some(expected_namespace.as_str()) {+ tx.object_store(RECORDS_STORE)?.clear()?;+ }+ meta.put(+ &JsValue::from_str(scope),+ Some(&JsValue::from_str(SCOPE_META_KEY)),+ )?;+ meta.put(+ &JsValue::from_str(&expected_namespace),+ Some(&JsValue::from_str(NAMESPACE_META_KEY)),+ )?;+ tx.commit()?.await?;+ Ok(())}/// Deletes the database for `scope` (logout / stale-namespace cleanup).@@ -62,7 +167,7 @@ impl IdbStorage {/// instead of hanging silently.pub async fn destroy(scope: &str) -> Result<(), IdbStorageError> {let factory = Factory::new()?;- let mut request = factory.delete(&cache_namespace(scope))?;+ let mut request = factory.delete(&cache_database_name(scope))?;request.on_blocked(|_| {web_sys::console::warn_1(&"graphql-cache: database deletion blocked by an open connection".into(),@@ -99,11 +204,7 @@ impl Storage for IdbStorage {let value = request.await?;out.push(match value {None => None,- Some(js) => {- let bytes: js_sys::Uint8Array =- js.dyn_into().map_err(|_| IdbStorageError::NotBytes)?;- Some(decode_record(&bytes.to_vec())?)- }+ Some(js) => Some(decode_record(&bytes_from_js(js)?)?),});}Ok(out)@@ -116,8 +217,7 @@ impl Storage for IdbStorage {let store = tx.object_store(RECORDS_STORE)?;for (key, record) in &entries {let bytes = encode_record(record);- let value: JsValue = js_sys::Uint8Array::from(bytes.as_slice()).into();- store.put(&value, Some(&JsValue::from_str(&key.0)))?;+ store.put(&bytes_to_js(&bytes), Some(&JsValue::from_str(&key.0)))?;}// Committing the transaction is what makes the batch atomic.tx.commit()?.await?;@@ -136,10 +236,237 @@ impl Storage for IdbStorage {Ok(())}- async fn clear(&mut self) -> Result<(), Self::Error> {+ async fn enqueue_mutation(+ &mut self,+ entry: NewQueuedMutation,+ ) -> Result<MutationId, Self::Error> {+ let tx = self.db.transaction(+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],+ TransactionMode::ReadWrite,+ )?;+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;+ let mutation_bytes = encode_stored_mutation(&entry.mutation);+ let generated_key = queue.add(&bytes_to_js(&mutation_bytes), None)?.await?;+ let id = mutation_id_from_js(&generated_key)?;+ let optimistic_bytes = encode_optimistic_layer(&entry.optimistic);+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?+ .put(&bytes_to_js(&optimistic_bytes), Some(&generated_key))?;+ tx.commit()?.await?;+ Ok(id)+ }++ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {+ let tx = self.db.transaction(+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],+ TransactionMode::ReadOnly,+ )?;+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;+ let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;+ let queue_keys_request = queue.get_all_keys(None, None)?;+ let queue_values_request = queue.get_all(None, None)?;+ let optimistic_keys_request = optimistic.get_all_keys(None, None)?;+ let optimistic_values_request = optimistic.get_all(None, None)?;++ let queue_keys = queue_keys_request.await?;+ let queue_values = queue_values_request.await?;+ let optimistic_keys = optimistic_keys_request.await?;+ let optimistic_values = optimistic_values_request.await?;+ if queue_keys.len() != queue_values.len()+ || queue_keys.len() != optimistic_keys.len()+ || queue_keys.len() != optimistic_values.len()+ {+ return Err(IdbStorageError::InconsistentQueue);+ }++ let mut out = Vec::with_capacity(queue_keys.len());+ for (((queue_key, mutation), optimistic_key), layer) in queue_keys+ .into_iter()+ .zip(queue_values)+ .zip(optimistic_keys)+ .zip(optimistic_values)+ {+ let id = mutation_id_from_js(&queue_key)?;+ if mutation_id_from_js(&optimistic_key)? != id {+ return Err(IdbStorageError::InconsistentQueue);+ }+ out.push(QueuedMutation {+ id,+ mutation: decode_stored_mutation(&bytes_from_js(mutation)?)?,+ optimistic: decode_optimistic_layer(&bytes_from_js(layer)?)?,+ });+ }+ Ok(out)+ }++ async fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> Result<Option<ClaimedMutation>, Self::Error> {+ let tx = self.db.transaction(+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],+ TransactionMode::ReadWrite,+ )?;+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;+ let optimistic = tx.object_store(OPTIMISTIC_LAYERS_STORE)?;+ let queue_keys_request = queue.get_all_keys(None, Some(1))?;+ let queue_values_request = queue.get_all(None, Some(1))?;+ let optimistic_keys_request = optimistic.get_all_keys(None, Some(1))?;+ let optimistic_values_request = optimistic.get_all(None, Some(1))?;+ let queue_keys = queue_keys_request.await?;+ let queue_values = queue_values_request.await?;+ let optimistic_keys = optimistic_keys_request.await?;+ let optimistic_values = optimistic_values_request.await?;++ if queue_keys.is_empty() {+ if !queue_values.is_empty()+ || !optimistic_keys.is_empty()+ || !optimistic_values.is_empty()+ {+ return Err(IdbStorageError::InconsistentQueue);+ }+ tx.commit()?.await?;+ return Ok(None);+ }+ if queue_keys.len() != 1+ || queue_values.len() != 1+ || optimistic_keys.len() != 1+ || optimistic_values.len() != 1+ {+ return Err(IdbStorageError::InconsistentQueue);+ }+ let key = &queue_keys[0];+ let id = mutation_id_from_js(key)?;+ if mutation_id_from_js(&optimistic_keys[0])? != id {+ return Err(IdbStorageError::InconsistentQueue);+ }+ let mut mutation = decode_stored_mutation(&bytes_from_js(queue_values[0].clone())?)?;+ if mutation+ .next_attempt_at_ms+ .is_some_and(|next| next > request.now_ms)+ || mutation+ .lease_expires_at_ms+ .is_some_and(|expiry| expiry > request.now_ms)+ {+ tx.commit()?.await?;+ return Ok(None);+ }++ mutation.attempt_count = mutation.attempt_count.saturating_add(1);+ mutation.lease_generation = mutation.lease_generation.saturating_add(1);+ mutation.lease_owner = Some(request.owner);+ mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);+ mutation.next_attempt_at_ms = None;+ let generation = mutation.lease_generation;+ queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(key))?;+ let layer = decode_optimistic_layer(&bytes_from_js(optimistic_values[0].clone())?)?;+ tx.commit()?.await?;+ Ok(Some(ClaimedMutation {+ queued: QueuedMutation {+ id,+ mutation,+ optimistic: layer,+ },+ lease_generation: generation,+ }))+ }++ async fn defer_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<bool, Self::Error> {+ let key = mutation_id_to_js(id)?;let tx = self.db- .transaction(&[RECORDS_STORE], TransactionMode::ReadWrite)?;+ .transaction(&[MUTATION_QUEUE_STORE], TransactionMode::ReadWrite)?;+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;+ let Some(value) = queue.get(key.clone())?.await? else {+ tx.commit()?.await?;+ return Ok(false);+ };+ let mut mutation = decode_stored_mutation(&bytes_from_js(value)?)?;+ if !claim_matches(&mutation, &claim) {+ tx.commit()?.await?;+ return Ok(false);+ }+ mutation.next_attempt_at_ms = Some(next_attempt_at_ms);+ mutation.last_error = Some(error);+ mutation.lease_owner = None;+ mutation.lease_expires_at_ms = None;+ queue.put(&bytes_to_js(&encode_stored_mutation(&mutation)), Some(&key))?;+ tx.commit()?.await?;+ Ok(true)+ }++ async fn complete_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ entries: Vec<(EntityKey, Record)>,+ ) -> Result<bool, Self::Error> {+ let key = mutation_id_to_js(id)?;+ let tx = self.db.transaction(+ &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],+ TransactionMode::ReadWrite,+ )?;+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;+ let Some(value) = queue.get(key.clone())?.await? else {+ tx.commit()?.await?;+ return Ok(false);+ };+ let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;+ if !claim_matches(&mutation, &claim) {+ tx.commit()?.await?;+ return Ok(false);+ }+ let records = tx.object_store(RECORDS_STORE)?;+ for (record_key, record) in &entries {+ records.put(+ &bytes_to_js(&encode_record(record)),+ Some(&JsValue::from_str(&record_key.0)),+ )?;+ }+ queue.delete(key.clone())?;+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;+ tx.commit()?.await?;+ Ok(true)+ }++ async fn discard_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ ) -> Result<bool, Self::Error> {+ let key = mutation_id_to_js(id)?;+ let tx = self.db.transaction(+ &[MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],+ TransactionMode::ReadWrite,+ )?;+ let queue = tx.object_store(MUTATION_QUEUE_STORE)?;+ let Some(value) = queue.get(key.clone())?.await? else {+ tx.commit()?.await?;+ return Ok(false);+ };+ let mutation = decode_stored_mutation(&bytes_from_js(value)?)?;+ if !claim_matches(&mutation, &claim) {+ tx.commit()?.await?;+ return Ok(false);+ }+ queue.delete(key.clone())?;+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.delete(key)?;+ tx.commit()?.await?;+ Ok(true)+ }++ async fn clear(&mut self) -> Result<(), Self::Error> {+ let tx = self.db.transaction(+ &[RECORDS_STORE, MUTATION_QUEUE_STORE, OPTIMISTIC_LAYERS_STORE],+ TransactionMode::ReadWrite,+ )?;+ tx.object_store(OPTIMISTIC_LAYERS_STORE)?.clear()?;+ tx.object_store(MUTATION_QUEUE_STORE)?.clear()?;tx.object_store(RECORDS_STORE)?.clear()?;tx.commit()?.await?;Ok(())diff --git a/crates/client/cache-idb/src/lib.rs b/crates/client/cache-idb/src/lib.rsindex 0097d55907..38c595e083 100644--- a/crates/client/cache-idb/src/lib.rs+++ b/crates/client/cache-idb/src/lib.rs@@ -1,11 +1,10 @@//! IndexedDB [`Storage`](cache_core::store::Storage) backend for the browser//! host (wasm module in a SharedWorker / dedicated worker).//!-//! One IndexedDB database per cache namespace — the database *name* embeds-//! scope + schema hash + format version-//! ([`cache_core::codec::cache_namespace`]), so a schema/format change simply-//! opens a fresh database. Records live in a single `records` object store-//! as postcard bytes (`Uint8Array`) under their entity-key string.+//! One stable IndexedDB database per cache scope. Disposable normalized+//! records are versioned through metadata, while queued mutations and their+//! optimistic layers remain discoverable across record-schema changes.+//! Postcard payloads are stored as `Uint8Array` values.//!//! wasm32-only; on other targets this crate is an empty shell so workspace//! `cargo test` stays green.diff --git a/crates/client/cache-idb/tests/web.rs b/crates/client/cache-idb/tests/web.rsindex 533cce74e0..150d948db0 100644--- a/crates/client/cache-idb/tests/web.rs+++ b/crates/client/cache-idb/tests/web.rs@@ -5,6 +5,10 @@#![cfg(target_arch = "wasm32")]use cache_core::engine::{Engine, ReadResult};+use cache_core::queue::{+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,+ PersistedOptimisticLayer, StoredMutation,+};use cache_core::store::Storage;use cache_core::value::{CacheValue, EntityKey, Record};use cache_idb::IdbStorage;@@ -23,6 +27,24 @@ fn key(s: &str) -> EntityKey {EntityKey(s.to_string())}+fn queued(name: &str) -> NewQueuedMutation {+ NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: "mutation Rename { rename { id } }".into(),+ operation_name: Some("Rename".into()),+ variables_json: format!(r#"{{"name":"{name}"}}"#),+ identity: Some("user-1".into()),+ },+ 10,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: format!(r#"{{"rename":{{"name":"{name}"}}}}"#),+ normalized_updates: [(key("A:1"), record(name))].into(),+ },+ }+}+#[wasm_bindgen_test]async fn put_get_delete_roundtrip() {IdbStorage::destroy("test-rt").await.unwrap();@@ -63,6 +85,49 @@ async fn persists_across_reopen() {assert_eq!(got[0].as_ref().unwrap(), &record("a"));}+#[wasm_bindgen_test]+async fn mutation_queue_persists_and_settles_atomically() {+ IdbStorage::destroy("test-queue").await.unwrap();+ let mut storage = IdbStorage::open("test-queue").await.unwrap();+ let id = storage+ .enqueue_mutation(queued("optimistic"))+ .await+ .unwrap();+ storage.close();++ let mut storage = IdbStorage::open("test-queue").await.unwrap();+ let loaded = storage.load_mutation_queue().await.unwrap();+ assert_eq!(loaded.len(), 1);+ assert_eq!(loaded[0].id, id);+ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 20,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert!(+ storage+ .complete_mutation(+ id,+ MutationClaimToken {+ owner: "runner".into(),+ generation: claimed.lease_generation,+ },+ vec![(key("A:1"), record("server"))],+ )+ .await+ .unwrap()+ );+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage.get_batch(&[key("A:1")]).await.unwrap()[0],+ Some(record("server"))+ );+}+#[wasm_bindgen_test]async fn engine_over_idb() {IdbStorage::destroy("test-engine").await.unwrap();diff --git a/crates/client/cache-sqlite/src/lib.rs b/crates/client/cache-sqlite/src/lib.rsindex 56a8c00cae..9e26dbbdec 100644--- a/crates/client/cache-sqlite/src/lib.rs+++ b/crates/client/cache-sqlite/src/lib.rs@@ -13,10 +13,16 @@#![deny(missing_docs)]-use cache_core::codec::{cache_namespace, decode_record, encode_record};+use cache_core::codec::{+ cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,+};+use cache_core::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,+ NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,+};use cache_core::store::Storage;use cache_core::value::{EntityKey, Record};-use rusqlite::{Connection, OptionalExtension, params};+use rusqlite::{Connection, OptionalExtension, Transaction, params};use std::path::Path;use std::sync::{Mutex, MutexGuard};use thiserror::Error;@@ -27,9 +33,12 @@ pub enum SqliteStorageError {/// Underlying SQLite failure.#[error("sqlite: {0}")]Sqlite(#[from] rusqlite::Error),- /// A stored record failed to decode (corruption → discard & rebuild).+ /// A stored cache value failed to decode.#[error(transparent)]Codec(#[from] cache_core::codec::CodecError),+ /// Durable queue metadata violated an invariant.+ #[error("invalid mutation queue state: {0}")]+ QueueInvariant(String),}/// [`Storage`] backend over a SQLite database (Tauri native host).@@ -53,29 +62,77 @@ impl SqliteStorage {Self::init(Connection::open_in_memory()?, scope)}- fn init(conn: Connection, scope: &str) -> Result<Self, SqliteStorageError> {+ fn init(mut conn: Connection, scope: &str) -> Result<Self, SqliteStorageError> {conn.pragma_update(None, "journal_mode", "WAL")?;conn.pragma_update(None, "synchronous", "NORMAL")?;+ conn.pragma_update(None, "foreign_keys", "ON")?;conn.execute_batch(- "CREATE TABLE IF NOT EXISTS meta (k TEXT PRIMARY KEY, v TEXT NOT NULL);- CREATE TABLE IF NOT EXISTS records (key TEXT PRIMARY KEY, value BLOB NOT NULL);",+ "CREATE TABLE IF NOT EXISTS meta (+ k TEXT PRIMARY KEY,+ v TEXT NOT NULL+ );+ CREATE TABLE IF NOT EXISTS records (+ key TEXT PRIMARY KEY,+ value BLOB NOT NULL+ );+ CREATE TABLE IF NOT EXISTS mutation_queue (+ id INTEGER PRIMARY KEY AUTOINCREMENT,+ query TEXT NOT NULL,+ operation_name TEXT,+ variables_json TEXT NOT NULL,+ identity TEXT,+ attempt_count INTEGER NOT NULL DEFAULT 0,+ next_attempt_at_ms INTEGER,+ lease_owner TEXT,+ lease_generation INTEGER NOT NULL DEFAULT 0,+ lease_expires_at_ms INTEGER,+ last_error TEXT,+ created_at_ms INTEGER NOT NULL+ );+ CREATE TABLE IF NOT EXISTS optimistic_layers (+ mutation_id INTEGER PRIMARY KEY,+ optimistic_data_json TEXT NOT NULL,+ normalized_updates BLOB NOT NULL,+ FOREIGN KEY(mutation_id) REFERENCES mutation_queue(id) ON DELETE CASCADE+ );",)?;- let expected = cache_namespace(scope);- let stored: Option<String> = conn+ let expected_namespace = cache_namespace(scope);+ let stored_scope: Option<String> = conn+ .query_row("SELECT v FROM meta WHERE k = 'scope'", [], |row| row.get(0))+ .optional()?;+ let stored_namespace: Option<String> = conn.query_row("SELECT v FROM meta WHERE k = 'namespace'", [], |row| {row.get(0)}).optional()?;- if stored.as_deref() != Some(expected.as_str()) {- // Different user, schema or format → disposable rebuild.- conn.execute("DELETE FROM records", [])?;- conn.execute(- "INSERT INTO meta (k, v) VALUES ('namespace', ?1)- ON CONFLICT(k) DO UPDATE SET v = excluded.v",- params![expected],- )?;++ let tx = conn.transaction()?;+ if stored_scope.as_deref() != Some(scope) {+ // Scope changes are identity changes: queued user intent must not+ // cross the boundary. `None` is the one-time upgrade from the+ // pre-queue schema, where no durable mutations existed.+ tx.execute("DELETE FROM optimistic_layers", [])?;+ tx.execute("DELETE FROM mutation_queue", [])?;+ tx.execute("DELETE FROM records", [])?;+ } else if stored_namespace.as_deref() != Some(expected_namespace.as_str()) {+ // Record schema/format changes only invalidate disposable records.+ // The queue retains source GraphQL + optimistic JSON so the engine+ // can re-normalize it against the current schema.+ tx.execute("DELETE FROM records", [])?;}+ tx.execute(+ "INSERT INTO meta (k, v) VALUES ('scope', ?1)+ ON CONFLICT(k) DO UPDATE SET v = excluded.v",+ params![scope],+ )?;+ tx.execute(+ "INSERT INTO meta (k, v) VALUES ('namespace', ?1)+ ON CONFLICT(k) DO UPDATE SET v = excluded.v",+ params![expected_namespace],+ )?;+ tx.commit()?;+Ok(SqliteStorage {conn: Mutex::new(conn),})@@ -93,6 +150,74 @@ impl SqliteStorage {.conn().query_row("SELECT COUNT(*) FROM records", [], |row| row.get(0))?)}++ /// Number of mutations waiting for settlement.+ pub fn mutation_count(&self) -> Result<u64, SqliteStorageError> {+ Ok(self+ .conn()+ .query_row("SELECT COUNT(*) FROM mutation_queue", [], |row| row.get(0))?)+ }+}++fn mutation_id_from_sql(id: i64) -> Result<MutationId, SqliteStorageError> {+ id.try_into()+ .map_err(|_| SqliteStorageError::QueueInvariant(format!("negative mutation id {id}")))+}++fn mutation_id_to_sql(id: MutationId) -> Result<i64, SqliteStorageError> {+ id.try_into().map_err(|_| {+ SqliteStorageError::QueueInvariant(format!("mutation id {id} exceeds SQLite INTEGER"))+ })+}++fn row_stored_mutation(row: &rusqlite::Row<'_>, offset: usize) -> rusqlite::Result<StoredMutation> {+ let attempt_count: i64 = row.get(offset + 4)?;+ let lease_generation: i64 = row.get(offset + 7)?;+ Ok(StoredMutation {+ request: MutationRequest {+ query: row.get(offset)?,+ operation_name: row.get(offset + 1)?,+ variables_json: row.get(offset + 2)?,+ identity: row.get(offset + 3)?,+ },+ attempt_count: attempt_count.try_into().map_err(|e| {+ rusqlite::Error::FromSqlConversionFailure(+ offset + 4,+ rusqlite::types::Type::Integer,+ Box::new(e),+ )+ })?,+ next_attempt_at_ms: row.get(offset + 5)?,+ lease_owner: row.get(offset + 6)?,+ lease_generation: lease_generation.try_into().map_err(|e| {+ rusqlite::Error::FromSqlConversionFailure(+ offset + 7,+ rusqlite::types::Type::Integer,+ Box::new(e),+ )+ })?,+ lease_expires_at_ms: row.get(offset + 8)?,+ last_error: row.get(offset + 9)?,+ created_at_ms: row.get(offset + 10)?,+ })+}++fn claim_is_current(+ tx: &Transaction<'_>,+ id: i64,+ claim: &MutationClaimToken,+) -> Result<bool, rusqlite::Error> {+ let current: Option<(Option<String>, i64)> = tx+ .query_row(+ "SELECT lease_owner, lease_generation FROM mutation_queue WHERE id = ?1",+ params![id],+ |row| Ok((row.get(0)?, row.get(1)?)),+ )+ .optional()?;+ Ok(current.is_some_and(|(owner, generation)| {+ owner.as_deref() == Some(&claim.owner)+ && u64::try_from(generation).ok() == Some(claim.generation)+ }))}impl Storage for SqliteStorage {@@ -143,8 +268,241 @@ impl Storage for SqliteStorage {Ok(())}+ async fn enqueue_mutation(+ &mut self,+ entry: NewQueuedMutation,+ ) -> Result<MutationId, Self::Error> {+ let mut conn = self.conn();+ let tx = conn.transaction()?;+ let mutation = &entry.mutation;+ tx.execute(+ "INSERT INTO mutation_queue (+ query, operation_name, variables_json, identity,+ attempt_count, next_attempt_at_ms, lease_owner,+ lease_generation, lease_expires_at_ms, last_error, created_at_ms+ ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11)",+ params![+ mutation.request.query,+ mutation.request.operation_name,+ mutation.request.variables_json,+ mutation.request.identity,+ i64::from(mutation.attempt_count),+ mutation.next_attempt_at_ms,+ mutation.lease_owner,+ i64::try_from(mutation.lease_generation).map_err(|_| {+ SqliteStorageError::QueueInvariant(+ "lease generation exceeds SQLite INTEGER".to_string(),+ )+ })?,+ mutation.lease_expires_at_ms,+ mutation.last_error,+ mutation.created_at_ms,+ ],+ )?;+ let sql_id = tx.last_insert_rowid();+ tx.execute(+ "INSERT INTO optimistic_layers (+ mutation_id, optimistic_data_json, normalized_updates+ ) VALUES (?1, ?2, ?3)",+ params![+ sql_id,+ entry.optimistic.optimistic_data_json,+ encode_record_updates(&entry.optimistic.normalized_updates),+ ],+ )?;+ tx.commit()?;+ mutation_id_from_sql(sql_id)+ }++ async fn load_mutation_queue(&self) -> Result<Vec<QueuedMutation>, Self::Error> {+ let conn = self.conn();+ let mut stmt = conn.prepare_cached(+ "SELECT+ m.id, m.query, m.operation_name, m.variables_json, m.identity,+ m.attempt_count, m.next_attempt_at_ms, m.lease_owner,+ m.lease_generation, m.lease_expires_at_ms, m.last_error,+ m.created_at_ms, o.optimistic_data_json, o.normalized_updates+ FROM mutation_queue m+ INNER JOIN optimistic_layers o ON o.mutation_id = m.id+ ORDER BY m.id ASC",+ )?;+ let mut rows = stmt.query([])?;+ let mut out = Vec::new();+ while let Some(row) = rows.next()? {+ let id: i64 = row.get(0)?;+ let updates: Vec<u8> = row.get(13)?;+ out.push(QueuedMutation {+ id: mutation_id_from_sql(id)?,+ mutation: row_stored_mutation(row, 1)?,+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: row.get(12)?,+ normalized_updates: decode_record_updates(&updates)?,+ },+ });+ }+ Ok(out)+ }++ async fn claim_next_mutation(+ &mut self,+ request: MutationClaimRequest,+ ) -> Result<Option<ClaimedMutation>, Self::Error> {+ let mut conn = self.conn();+ let tx = conn.transaction()?;+ let head: Option<(i64, StoredMutation)> = tx+ .query_row(+ "SELECT+ id, query, operation_name, variables_json, identity,+ attempt_count, next_attempt_at_ms, lease_owner,+ lease_generation, lease_expires_at_ms, last_error,+ created_at_ms+ FROM mutation_queue+ ORDER BY id ASC+ LIMIT 1",+ [],+ |row| Ok((row.get(0)?, row_stored_mutation(row, 1)?)),+ )+ .optional()?;+ let Some((sql_id, mut mutation)) = head else {+ tx.commit()?;+ return Ok(None);+ };+ if mutation+ .next_attempt_at_ms+ .is_some_and(|next| next > request.now_ms)+ || mutation+ .lease_expires_at_ms+ .is_some_and(|expiry| expiry > request.now_ms)+ {+ tx.commit()?;+ return Ok(None);+ }++ mutation.attempt_count = mutation.attempt_count.saturating_add(1);+ mutation.lease_generation = mutation.lease_generation.saturating_add(1);+ mutation.lease_owner = Some(request.owner.clone());+ mutation.lease_expires_at_ms = Some(request.lease_expires_at_ms);+ mutation.next_attempt_at_ms = None;+ tx.execute(+ "UPDATE mutation_queue SET+ attempt_count = ?2,+ next_attempt_at_ms = NULL,+ lease_owner = ?3,+ lease_generation = ?4,+ lease_expires_at_ms = ?5+ WHERE id = ?1",+ params![+ sql_id,+ i64::from(mutation.attempt_count),+ mutation.lease_owner,+ i64::try_from(mutation.lease_generation).map_err(|_| {+ SqliteStorageError::QueueInvariant(+ "lease generation exceeds SQLite INTEGER".to_string(),+ )+ })?,+ mutation.lease_expires_at_ms,+ ],+ )?;+ let (optimistic_data_json, updates): (String, Vec<u8>) = tx.query_row(+ "SELECT optimistic_data_json, normalized_updates+ FROM optimistic_layers WHERE mutation_id = ?1",+ params![sql_id],+ |row| Ok((row.get(0)?, row.get(1)?)),+ )?;+ let generation = mutation.lease_generation;+ let queued = QueuedMutation {+ id: mutation_id_from_sql(sql_id)?,+ mutation,+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json,+ normalized_updates: decode_record_updates(&updates)?,+ },+ };+ tx.commit()?;+ Ok(Some(ClaimedMutation {+ queued,+ lease_generation: generation,+ }))+ }++ async fn defer_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ next_attempt_at_ms: i64,+ error: String,+ ) -> Result<bool, Self::Error> {+ let sql_id = mutation_id_to_sql(id)?;+ let mut conn = self.conn();+ let tx = conn.transaction()?;+ if !claim_is_current(&tx, sql_id, &claim)? {+ tx.commit()?;+ return Ok(false);+ }+ tx.execute(+ "UPDATE mutation_queue SET+ next_attempt_at_ms = ?2,+ lease_owner = NULL,+ lease_expires_at_ms = NULL,+ last_error = ?3+ WHERE id = ?1",+ params![sql_id, next_attempt_at_ms, error],+ )?;+ tx.commit()?;+ Ok(true)+ }++ async fn complete_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ entries: Vec<(EntityKey, Record)>,+ ) -> Result<bool, Self::Error> {+ let sql_id = mutation_id_to_sql(id)?;+ let mut conn = self.conn();+ let tx = conn.transaction()?;+ if !claim_is_current(&tx, sql_id, &claim)? {+ tx.commit()?;+ return Ok(false);+ }+ {+ let mut stmt = tx.prepare_cached(+ "INSERT INTO records (key, value) VALUES (?1, ?2)+ ON CONFLICT(key) DO UPDATE SET value = excluded.value",+ )?;+ for (key, record) in &entries {+ stmt.execute(params![key.0, encode_record(record)])?;+ }+ }+ tx.execute("DELETE FROM mutation_queue WHERE id = ?1", params![sql_id])?;+ tx.commit()?;+ Ok(true)+ }++ async fn discard_mutation(+ &mut self,+ id: MutationId,+ claim: MutationClaimToken,+ ) -> Result<bool, Self::Error> {+ let sql_id = mutation_id_to_sql(id)?;+ let mut conn = self.conn();+ let tx = conn.transaction()?;+ if !claim_is_current(&tx, sql_id, &claim)? {+ tx.commit()?;+ return Ok(false);+ }+ tx.execute("DELETE FROM mutation_queue WHERE id = ?1", params![sql_id])?;+ tx.commit()?;+ Ok(true)+ }+async fn clear(&mut self) -> Result<(), Self::Error> {- self.conn().execute("DELETE FROM records", [])?;+ let mut conn = self.conn();+ let tx = conn.transaction()?;+ tx.execute("DELETE FROM optimistic_layers", [])?;+ tx.execute("DELETE FROM mutation_queue", [])?;+ tx.execute("DELETE FROM records", [])?;+ tx.commit()?;Ok(())}}diff --git a/crates/client/cache-sqlite/tests/mutation_queue.rs b/crates/client/cache-sqlite/tests/mutation_queue.rsnew file mode 100644index 0000000000..1abe4d10cc--- /dev/null+++ b/crates/client/cache-sqlite/tests/mutation_queue.rs@@ -0,0 +1,203 @@+use cache_core::queue::{+ MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation,+ PersistedOptimisticLayer, StoredMutation,+};+use cache_core::store::Storage;+use cache_core::value::{CacheValue, EntityKey, Record};+use cache_sqlite::SqliteStorage;+use pollster::block_on;++const CACHE_QUERY: &str = r#"+query Soup($input: SoupInput!) {+ user {+ id+ soup(input: $input) {+ items {+ id+ entity {+ __typename+ ... on GraphqlSoupDocument {+ id+ properties { id displayName }+ }+ }+ }+ hasMore+ }+ }+}+"#;++const CACHE_MUTATION: &str = r#"+mutation SetEntityProperty($input: SetEntityPropertyInput!) {+ setEntityProperty(input: $input) { id displayName }+}+"#;++fn queued(value: &str) -> NewQueuedMutation {+ let mut update = Record::default();+ update+ .fields+ .insert("name".into(), CacheValue::String(value.into()));+ NewQueuedMutation {+ mutation: StoredMutation::new(+ MutationRequest {+ query: "mutation Rename { rename { id } }".into(),+ operation_name: Some("Rename".into()),+ variables_json: format!(r#"{{"name":"{value}"}}"#),+ identity: Some("user-1".into()),+ },+ 10,+ ),+ optimistic: PersistedOptimisticLayer {+ optimistic_data_json: format!(r#"{{"rename":{{"name":"{value}"}}}}"#),+ normalized_updates: [(EntityKey("Thing:1".into()), update)].into(),+ },+ }+}++#[test]+fn queue_and_optimistic_layer_survive_reopen() {+ block_on(async {+ let dir = tempfile::tempdir().unwrap();+ let path = dir.path().join("cache.db");+ let mut storage = SqliteStorage::open(&path, "scope-1").unwrap();+ let id = storage+ .enqueue_mutation(queued("optimistic"))+ .await+ .unwrap();+ drop(storage);++ let mut storage = SqliteStorage::open(&path, "scope-1").unwrap();+ let loaded = storage.load_mutation_queue().await.unwrap();+ assert_eq!(loaded.len(), 1);+ assert_eq!(loaded[0].id, id);+ assert_eq!(+ loaded[0].optimistic.optimistic_data_json,+ r#"{"rename":{"name":"optimistic"}}"#+ );++ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 20,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ let mut real = Record::default();+ real.fields+ .insert("name".into(), CacheValue::String("server".into()));+ assert!(+ storage+ .complete_mutation(+ id,+ MutationClaimToken {+ owner: "runner".into(),+ generation: claimed.lease_generation,+ },+ vec![(EntityKey("Thing:1".into()), real.clone())],+ )+ .await+ .unwrap()+ );+ drop(storage);++ let storage = SqliteStorage::open(&path, "scope-1").unwrap();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ assert_eq!(+ storage+ .get_batch(&[EntityKey("Thing:1".into())])+ .await+ .unwrap()[0],+ Some(real)+ );+ });+}++#[test]+fn engine_hydrates_optimistic_layer_after_restart() {+ use cache_core::engine::{Engine, ReadResult};+ use serde_json::json;++ block_on(async {+ let dir = tempfile::tempdir().unwrap();+ let path = dir.path().join("cache.db");+ let serde_json::Value::Object(query_vars) = json!({"input": {"limit": 1}}) else {+ unreachable!()+ };+ let serde_json::Value::Object(mutation_vars) = json!({"input": {+ "entityType": "DOCUMENT",+ "entityId": "doc-1",+ "propertyDefinitionId": "def-1",+ "value": {"string": "x"}+ }}) else {+ unreachable!()+ };+ let base = json!({"user": {"id": "user-1", "soup": {+ "items": [{"id": "item-1", "entity": {+ "__typename": "GraphqlSoupDocument",+ "id": "doc-1",+ "properties": [{"id": "prop-1", "displayName": "Status"}]+ }}],+ "hasMore": false+ }}});+ let optimistic = json!({"setEntityProperty": {+ "id": "prop-1",+ "displayName": "Stage"+ }});++ let mut engine = Engine::new(SqliteStorage::open(&path, "scope-1").unwrap());+ engine+ .write_query(+ None,+ CACHE_QUERY,+ Some("Soup"),+ &query_vars,+ &base,+ Some("user-1"),+ )+ .await+ .unwrap();+ engine+ .begin_optimistic_write(+ None,+ CACHE_MUTATION,+ Some("SetEntityProperty"),+ &mutation_vars,+ &optimistic,+ 10,+ )+ .await+ .unwrap();+ drop(engine);++ let mut reopened = Engine::new(SqliteStorage::open(&path, "scope-1").unwrap());+ let ReadResult::Hit { data } = reopened+ .read_query(None, CACHE_QUERY, Some("Soup"), &query_vars)+ .await+ .unwrap()+ else {+ panic!("expected hydrated hit");+ };+ assert_eq!(+ data["user"]["soup"]["items"][0]["entity"]["properties"][0]["displayName"],+ json!("Stage")+ );+ });+}++#[test]+fn scope_change_clears_queued_user_intent() {+ block_on(async {+ let dir = tempfile::tempdir().unwrap();+ let path = dir.path().join("cache.db");+ let mut storage = SqliteStorage::open(&path, "scope-1").unwrap();+ storage.enqueue_mutation(queued("a")).await.unwrap();+ drop(storage);++ let storage = SqliteStorage::open(&path, "scope-2").unwrap();+ assert!(storage.load_mutation_queue().await.unwrap().is_empty());+ });+}diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rsindex bbb6e82049..22f53422d1 100644--- a/crates/client/cache-wasm/src/shell.rs+++ b/crates/client/cache-wasm/src/shell.rs@@ -1,6 +1,7 @@use async_lock::Mutex;use cache_core::deps::OpId;use cache_core::engine::{Engine, ReadResult};+use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};use cache_core::value::EntityKey;use cache_idb::IdbStorage;use serde::Serialize;@@ -67,11 +68,56 @@ struct JsOptimisticWriteResult {reset: bool,}-/// Transaction ids cross the boundary as strings (JS numbers lose precision-/// past 2^53; ids are opaque to the host anyway).+#[derive(Serialize)]+#[serde(rename_all = "camelCase")]+struct JsClaimedMutation {+ transaction_id: String,+ lease_generation: String,+ query: String,+ operation_name: Option<String>,+ variables: serde_json::Value,+ identity: Option<String>,+ attempt_count: u32,+}++impl TryFrom<ClaimedMutation> for JsClaimedMutation {+ type Error = JsValue;++ fn try_from(claimed: ClaimedMutation) -> Result<Self, Self::Error> {+ let request = claimed.queued.mutation.request;+ Ok(Self {+ transaction_id: claimed.queued.id.to_string(),+ lease_generation: claimed.lease_generation.to_string(),+ query: request.query,+ operation_name: request.operation_name,+ variables: serde_json::from_str(&request.variables_json).map_err(err_js)?,+ identity: request.identity,+ attempt_count: claimed.queued.mutation.attempt_count,+ })+ }+}++/// Queue ids and lease generations cross the boundary as strings because JS+/// numbers lose precision past 2^53.+fn parse_u64(value: &str, label: &str) -> Result<u64, JsValue> {+ value+ .parse::<u64>()+ .map_err(|_| err_js(format!("invalid {label} `{value}`")))+}+fn parse_transaction_id(id: &str) -> Result<u64, JsValue> {- id.parse::<u64>()- .map_err(|_| err_js(format!("invalid optimistic transaction id `{id}`")))+ parse_u64(id, "optimistic transaction id")+}++fn parse_timestamp(value: f64, label: &str) -> Result<i64, JsValue> {+ if !value.is_finite()+ || value.fract() != 0.0+ || value < i64::MIN as f64+ || value >= i64::MAX as f64+ {+ return Err(err_js(format!("invalid {label} `{value}`")));+ }+ Ok(value as i64)}#[wasm_bindgen]@@ -206,10 +252,9 @@ impl CacheEngine {})}- /// Installs an in-memory optimistic layer from a mutation's optimistic- /// response; persists nothing. Resolves to `{transactionId: string,- /// changed: string[], affectedOps: string[], reset: false}` where- /// `changed`/`affectedOps` reflect *visible* (composed-view) changes.+ /// Durably queues a mutation and its optimistic response. Resolves to+ /// `{transactionId: string, changed: string[], affectedOps: string[],+ /// reset: false}` where changes reflect the composed view.#[wasm_bindgen(js_name = beginOptimisticWrite)]pub fn begin_optimistic_write(&self,@@ -218,16 +263,25 @@ impl CacheEngine {operation_name: Option<String>,variables: JsValue,data: JsValue,+ created_at_ms: f64,) -> js_sys::Promise {let engine = self.engine.clone();let ops = self.ops.clone();future_to_promise(async move {let vars = parse_variables(variables)?;let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;+ let created_at_ms = parse_timestamp(created_at_ms, "enqueue timestamp")?;let origin = origin_op_id.map(|name| ops.borrow_mut().intern(&name));let mut engine = engine.lock().await;let (transaction, result) = engine- .begin_optimistic_write(origin, &query, operation_name.as_deref(), &vars, &data)+ .begin_optimistic_write(+ origin,+ &query,+ operation_name.as_deref(),+ &vars,+ &data,+ created_at_ms,+ ).await.map_err(err_js)?;to_js(&JsOptimisticWriteResult {@@ -239,15 +293,74 @@ impl CacheEngine {})}- /// Atomically replaces a pending optimistic layer with the real network- /// response and flushes any contiguous settled layers durably. Resolves- /// to a write result whose `changed` keys are the *durably* changed- /// records (cross-instance broadcast) and whose `affectedOps` reflect- /// visible changes. Rejects on unknown/settled transaction ids.+ /// Claims the oldest runnable queued mutation.+ #[wasm_bindgen(js_name = claimNextMutation)]+ pub fn claim_next_mutation(+ &self,+ owner: String,+ now_ms: f64,+ lease_expires_at_ms: f64,+ ) -> js_sys::Promise {+ let engine = self.engine.clone();+ future_to_promise(async move {+ let request = MutationClaimRequest {+ owner,+ now_ms: parse_timestamp(now_ms, "claim timestamp")?,+ lease_expires_at_ms: parse_timestamp(+ lease_expires_at_ms,+ "lease expiration timestamp",+ )?,+ };+ let claimed = engine+ .lock()+ .await+ .claim_next_mutation(request)+ .await+ .map_err(err_js)?;+ to_js(&claimed.map(JsClaimedMutation::try_from).transpose()?)+ })+ }++ /// Retains a retryable mutation and releases its queue lease.+ #[wasm_bindgen(js_name = deferOptimisticWrite)]+ pub fn defer_optimistic_write(+ &self,+ transaction_id: String,+ lease_owner: String,+ lease_generation: String,+ next_attempt_at_ms: f64,+ error: String,+ ) -> js_sys::Promise {+ let engine = self.engine.clone();+ future_to_promise(async move {+ let transaction = parse_transaction_id(&transaction_id)?;+ let claim = MutationClaimToken {+ owner: lease_owner,+ generation: parse_u64(&lease_generation, "lease generation")?,+ };+ engine+ .lock()+ .await+ .defer_optimistic_write(+ transaction,+ claim,+ parse_timestamp(next_attempt_at_ms, "next attempt timestamp")?,+ error,+ )+ .await+ .map_err(err_js)?;+ Ok(JsValue::UNDEFINED)+ })+ }++ /// Atomically replaces a claimed optimistic layer with the real network+ /// response and removes it from the durable queue.#[wasm_bindgen(js_name = commitOptimisticWrite)]pub fn commit_optimistic_write(&self,transaction_id: String,+ lease_owner: String,+ lease_generation: String,query: String,operation_name: Option<String>,variables: JsValue,@@ -257,12 +370,17 @@ impl CacheEngine {let ops = self.ops.clone();future_to_promise(async move {let transaction = parse_transaction_id(&transaction_id)?;+ let claim = MutationClaimToken {+ owner: lease_owner,+ generation: parse_u64(&lease_generation, "lease generation")?,+ };let vars = parse_variables(variables)?;let data: serde_json::Value = serde_wasm_bindgen::from_value(data).map_err(err_js)?;let mut engine = engine.lock().await;let result = engine.commit_optimistic_write(transaction,+ claim,&query,operation_name.as_deref(),&vars,@@ -278,18 +396,26 @@ impl CacheEngine {})}- /// Removes a pending optimistic layer's contribution (mutation failed)- /// and flushes any now-contiguous settled layers. Result semantics match- /// [`commitOptimisticWrite`](Self::commit_optimistic_write).+ /// Permanently fails a claimed mutation and removes its optimistic+ /// contribution.#[wasm_bindgen(js_name = rollbackOptimisticWrite)]- pub fn rollback_optimistic_write(&self, transaction_id: String) -> js_sys::Promise {+ pub fn rollback_optimistic_write(+ &self,+ transaction_id: String,+ lease_owner: String,+ lease_generation: String,+ ) -> js_sys::Promise {let engine = self.engine.clone();let ops = self.ops.clone();future_to_promise(async move {let transaction = parse_transaction_id(&transaction_id)?;+ let claim = MutationClaimToken {+ owner: lease_owner,+ generation: parse_u64(&lease_generation, "lease generation")?,+ };let mut engine = engine.lock().await;let result = engine- .rollback_optimistic_write(transaction)+ .rollback_optimistic_write(transaction, claim).await.map_err(err_js)?;to_js(&JsWriteResult {@@ -315,6 +441,27 @@ impl CacheEngine {})}+ /// Reloads optimistic layers after another engine changes the durable+ /// queue and returns locally affected operations.+ #[wasm_bindgen(js_name = refreshOptimisticQueue)]+ pub fn refresh_optimistic_queue(&self) -> js_sys::Promise {+ let engine = self.engine.clone();+ let ops = self.ops.clone();+ future_to_promise(async move {+ let result = engine+ .lock()+ .await+ .refresh_optimistic_queue()+ .await+ .map_err(err_js)?;+ to_js(&JsWriteResult {+ changed: result.changed.into_iter().map(|key| key.0).collect(),+ affected_ops: ops.borrow().names(result.affected_ops),+ reset: result.reset,+ })+ })+ }+/// Reacts to a cache reset performed by another engine instance sharing/// the same storage (cross-tab broadcast). Drops local in-memory state/// and resolves to every local operation id (all must re-execute).diff --git a/crates/client/cache-wasm/tests/web.rs b/crates/client/cache-wasm/tests/web.rsindex c7d14b5dba..3109be200e 100644--- a/crates/client/cache-wasm/tests/web.rs+++ b/crates/client/cache-wasm/tests/web.rs@@ -151,6 +151,7 @@ async fn optimistic_write_round_trip() {Some("SetEntityProperty".into()),js(mutation_vars.clone()),js(serde_json::json!({ "setEntityProperty": { "id": "prop-1", "displayName": "Stage" } })),+ 123.0,)).await.unwrap();@@ -177,9 +178,18 @@ async fn optimistic_write_round_trip() {serde_json::json!("Stage"));+ let claimed = JsFuture::from(engine.claim_next_mutation("runner".into(), 10.0, 1_000.0))+ .await+ .unwrap();+ let claimed: serde_json::Value = serde_wasm_bindgen::from_value(claimed).unwrap();+ assert_eq!(claimed["transactionId"], txn);+ let generation = claimed["leaseGeneration"].as_str().unwrap().to_string();+// Commit with the real response; the layer flushes durably.let commit = JsFuture::from(engine.commit_optimistic_write(txn.clone(),+ "runner".into(),+ generation.clone(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_vars.clone()),@@ -195,10 +205,16 @@ async fn optimistic_write_round_trip() {assert_eq!(commit["affectedOps"], serde_json::json!(["tab1:1"]));// Settled transactions reject further commits/rollbacks.- let err = JsFuture::from(engine.rollback_optimistic_write(txn)).await;+ let err =+ JsFuture::from(engine.rollback_optimistic_write(txn, "runner".into(), generation)).await;assert!(err.is_err());// Malformed ids reject too.- let err = JsFuture::from(engine.rollback_optimistic_write("not-a-number".into())).await;+ let err = JsFuture::from(engine.rollback_optimistic_write(+ "not-a-number".into(),+ "runner".into(),+ "1".into(),+ ))+ .await;assert!(err.is_err());JsFuture::from(engine.close()).await.unwrap();