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/upsert optimistic queue (#6078)
Sean Aye80c17dc4aaeb
diff --git a/Cargo.lock b/Cargo.lockindex 021d44b57e..25a044d6b5 100644--- a/Cargo.lock+++ b/Cargo.lock@@ -2935,6 +2935,7 @@ dependencies = ["serde_json","sha2 0.10.9","thiserror 2.0.18",+ "uuid",][[package]]@@ -2950,12 +2951,13 @@ dependencies = ["thiserror 2.0.18","turso-opfs","turso_core",+ "uuid","wasm-bindgen-test",][[package]]name = "cache-wasm"-version = "0.6.3"+version = "0.6.4"dependencies = ["async-lock","cache-core",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 725106c262..c66debf635 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@@ -21,6 +21,7 @@ import type { CacheHost } from '../host/types';import {ADMITTED_ENQUEUE_UNCERTAIN_ERROR_CODE,type ClaimedMutation,+ type CommitOptimisticWriteResult,type EnqueueOptimisticMutationResult,INITIAL_CACHE_REVISION,type MutationClaim,@@ -219,6 +220,8 @@ function makeFakeHost(): FakeHost {host.claims.push(head.transactionId);return {transactionId: head.transactionId,+ uuid: head.args.uuid,+ superseded: false,leaseGeneration: String(head.attemptCount),query: head.args.query,operationName: head.args.operationName,@@ -318,6 +321,7 @@ function makeFakeHost(): FakeHost {changed: [],affectedOps: [],reset: false,+ upsertKind: { kind: 'inserted' },initialClaim: mutation? { kind: 'claimed', mutation }: { kind: 'not-runnable' },@@ -347,25 +351,28 @@ function makeFakeHost(): FakeHost {head.leased = false;head.nextAttemptAtMs = nextAttemptAtMs;}+ return { kind: 'deferred' };},async commitOptimisticWrite(transactionId,_claim,args- ): Promise<WriteResult> {+ ): Promise<CommitOptimisticWriteResult> {host.commits.push({ transactionId, query: args.query, data: args.data });if (queue[0]?.transactionId === transactionId) queue.shift();return {+ kind: 'committed',revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],reset: false,};},- async rollbackOptimisticWrite(transactionId, _claim): Promise<WriteResult> {+ async rollbackOptimisticWrite(transactionId, _claim) {host.rollbacks.push(transactionId);if (queue[0]?.transactionId === transactionId) queue.shift();return {+ kind: 'rolled-back' as const,revision: INITIAL_CACHE_REVISION,changed: [],affectedOps: [],@@ -466,7 +473,12 @@ function makeMutationOp(key: number, optimisticResponse?: unknown): Operation {suspense: false,...(optimisticResponse === undefined? {}- : { normalizedCacheOptimistic: { optimisticResponse } }),+ : {+ normalizedCacheOptimistic: {+ uuid: crypto.randomUUID(),+ optimisticResponse,+ },+ }),} as never);}@@ -1539,6 +1551,7 @@ describe('normalizedCacheExchange', () => {it('replays a persisted mutation when the exchange starts', async () => {host.seedQueued({+ uuid: '00000000-0000-4000-8000-000000000001',query: stringifyDocument(MUTATION),operationName: 'SetEntityProperty',variables: { input: {} },@@ -1556,6 +1569,7 @@ describe('normalizedCacheExchange', () => {it('rolls back when a persisted replay resolves with an urql error', async () => {host.seedQueued({+ uuid: '00000000-0000-4000-8000-000000000002',query: stringifyDocument(MUTATION),operationName: 'SetEntityProperty',variables: { input: {} },@@ -1704,6 +1718,7 @@ describe('normalizedCacheExchange', () => {const operation = makeOperation(base.kind, base, {...base.context,normalizedCacheOptimistic: {+ uuid: crypto.randomUUID(),optimisticResponse: optimistic,linkPatches: [{@@ -1734,6 +1749,7 @@ describe('normalizedCacheExchange', () => {it('replays an older returned claim and reports the new caller as queued', async () => {host.seedQueued({+ uuid: '00000000-0000-4000-8000-000000000003',query: stringifyDocument(MUTATION),operationName: 'SetEntityProperty',variables: { input: { restored: true } },@@ -1819,6 +1835,7 @@ describe('normalizedCacheExchange', () => {const op = makeOperation(base.kind, base, {...base.context,normalizedCacheOptimistic: {+ uuid: crypto.randomUUID(),optimisticResponse: optimistic,linkPatches: [patch],revalidations: [],@@ -1836,6 +1853,7 @@ describe('normalizedCacheExchange', () => {const op = makeOperation(base.kind, base, {...base.context,normalizedCacheOptimistic: {+ uuid: crypto.randomUUID(),optimisticResponse: optimistic,linkPatches: [{@@ -1930,6 +1948,26 @@ describe('normalizedCacheExchange', () => {expect(host.writes).toHaveLength(0);});+ it('does not expose a stale response when commit lands beneath a replacement', async () => {+ const commit = host.commitOptimisticWrite.bind(host);+ host.commitOptimisticWrite = async (transactionId, claim, args) => ({+ ...(await commit(transactionId, claim, args)),+ kind: 'committed-superseded',+ replacementTransactionId: 'txn-2',+ });+ const { ops, results } = harness(host);++ ops.next(makeMutationOp(1, optimistic));+ await tick();++ expect(host.commits[0]?.data).toEqual({ from: 'network' });+ expect(results[0]?.data).toBeUndefined();+ expect(optimisticMutationDispositionOf(results[0])).toEqual({+ kind: 'queued',+ transactionId: 'txn-2',+ });+ });+it('replays mixed explicit cache effects in order after an optimistic commit', async () => {const deletion = {__typename: 'GraphqlCacheDeletion',@@ -1958,6 +1996,7 @@ describe('normalizedCacheExchange', () => {const operation = makeOperation(base.kind, base, {...base.context,normalizedCacheOptimistic: {+ uuid: crypto.randomUUID(),optimisticResponse: {renameEntities: { results: [] },},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 a488070413..e7ad69735f 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@@ -732,6 +732,27 @@ export function normalizedCacheExchange(claimed: ClaimedMutation): Promise<void> {deferredUntil = undefined;+ if (claimed.superseded) {+ const discarded = await host.deferOptimisticWrite(+ claimed.transactionId,+ { owner: queueOwner, generation: claimed.leaseGeneration },+ Date.now(),+ 'superseded before network replay'+ );+ if (discarded.kind !== 'discarded-superseded') {+ throw new Error('superseded mutation was unexpectedly deferred');+ }+ const live = liveQueuedOps.get(claimed.transactionId);+ if (live) {+ liveQueuedOps.delete(claimed.transactionId);+ live.resolveRoute(+ queuedMutationResult(live.operation, claimed.transactionId)+ );+ }+ resolveLiveOperationsAsQueued();+ scheduleDrain();+ return;+ }attemptInFlight = true;const attempt: QueueAttemptContext = {transactionId: claimed.transactionId,@@ -925,6 +946,7 @@ export function normalizedCacheExchange(return undefined;}const args = {+ uuid: optimistic.uuid,query: queryText(op),operationName: operationName(op),variables: op.variables as Record<string, unknown> | undefined,@@ -980,6 +1002,20 @@ export function normalizedCacheExchange(return undefined;}}+ if (enqueue.upsertKind.kind === 'replaced-pending') {+ const superseded = liveQueuedOps.get(+ enqueue.upsertKind.removedTransactionId+ );+ if (superseded) {+ liveQueuedOps.delete(enqueue.upsertKind.removedTransactionId);+ superseded.resolveRoute(+ queuedMutationResult(+ superseded.operation,+ enqueue.upsertKind.removedTransactionId+ )+ );+ }+ }const routed = new Promise<OperationResult | undefined>((resolve) => {liveQueuedOps.set(enqueue.transactionId, {operation: op,@@ -1164,8 +1200,12 @@ export function normalizedCacheExchange(generation: attempt.leaseGeneration,};let retryAt: number | undefined;- let disposition: 'committed' | 'queued' | 'permanently-failed' =- 'queued';+ let replacementTransactionId: string | undefined;+ let disposition:+ | 'committed'+ | 'queued'+ | 'superseded'+ | 'permanently-failed' = 'queued';try {if (result.error || result.data == null) {let retry = false;@@ -1178,20 +1218,33 @@ export function normalizedCacheExchange(}if (retry) {retryAt = Date.now() + retryDelayMs(attempt.attemptCount);- await host.deferOptimisticWrite(+ const deferred = await host.deferOptimisticWrite(attempt.transactionId,claim,retryAt,result.error?.message ?? 'mutation returned no data');- disposition = 'queued';+ if (deferred.kind === 'discarded-superseded') {+ retryAt = undefined;+ replacementTransactionId =+ deferred.replacementTransactionId;+ disposition = 'superseded';+ } else {+ disposition = 'queued';+ }} else {- await host.rollbackOptimisticWrite(+ const rolledBack = await host.rollbackOptimisticWrite(attempt.transactionId,claim,result.error?.message ?? 'mutation returned no data');- disposition = 'permanently-failed';+ if (rolledBack.kind === 'discarded-superseded') {+ replacementTransactionId =+ rolledBack.replacementTransactionId;+ disposition = 'superseded';+ } else {+ disposition = 'permanently-failed';+ }}} else {const committed = await host.commitOptimisticWrite(@@ -1214,7 +1267,12 @@ export function normalizedCacheExchange(await applyOperationCacheEffects(op, effects);}revalidateAfterCommit(committed.revalidations ?? [], op);- disposition = 'committed';+ if (committed.kind === 'committed-superseded') {+ replacementTransactionId = committed.replacementTransactionId;+ disposition = 'superseded';+ } else {+ disposition = 'committed';+ }}} catch (error) {options.onCacheError?.(error, op);@@ -1231,10 +1289,20 @@ export function normalizedCacheExchange(retryAt === undefined ? 0 : Math.max(0, retryAt - Date.now()));}- return withOptimisticMutationDisposition(result, {- kind: disposition,- transactionId: attempt.transactionId,- });+ return withOptimisticMutationDisposition(+ result,+ disposition === 'superseded'+ ? {+ kind: 'superseded',+ transactionId: attempt.transactionId,+ replacementTransactionId:+ replacementTransactionId ?? attempt.transactionId,+ }+ : {+ kind: disposition,+ transactionId: attempt.transactionId,+ }+ );}const optimistic = optimisticContextOf(op);diff --git a/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts b/apps/web/src/lib/graphql-cache/exchange/optimistic.test.tsindex fc5dee5fb9..cd972a0c44 100644--- a/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts+++ b/apps/web/src/lib/graphql-cache/exchange/optimistic.test.ts@@ -1,6 +1,9 @@+import type { TypedDocumentNode } from '@graphql-typed-document-node/core';import { GroupSoupMembershipDocument } from '@service-storage/graphql/generated/graphql';+import type { Client } from '@urql/core';import { describe, expect, it } from 'vitest';import {+ executeOptimisticMutation,prependUnique,remove,removeEmbeddedLink,@@ -147,3 +150,27 @@ describe('typed optimistic graph updates', () => {expect(typeAssertions).toBeTypeOf('function');});});++describe('executeOptimisticMutation UUID validation', () => {+ const client = {} as Client;+ const document = {} as TypedDocumentNode<unknown, Record<string, never>>;++ it('rejects an invalid caller UUID before invoking the client', () => {+ expect(() =>+ executeOptimisticMutation(client, document, {}, {}, { uuid: 'invalid' })+ ).toThrow(TypeError);+ });++ it('rejects missing options at runtime', () => {+ expect(() =>+ (+ executeOptimisticMutation as unknown as (+ client: Client,+ document: TypedDocumentNode<unknown, Record<string, never>>,+ variables: Record<string, never>,+ data: unknown+ ) => unknown+ )(client, document, {}, {})+ ).toThrow(TypeError);+ });+});diff --git a/apps/web/src/lib/graphql-cache/exchange/optimistic.ts b/apps/web/src/lib/graphql-cache/exchange/optimistic.tsindex df623fef62..29185fb98e 100644--- a/apps/web/src/lib/graphql-cache/exchange/optimistic.ts+++ b/apps/web/src/lib/graphql-cache/exchange/optimistic.ts@@ -17,6 +17,7 @@ import {stringifyDocument,} from '@urql/core';import type { DocumentNode } from 'graphql';+import { validate as validateUuid } from 'uuid';import type {EmbeddedLinkPathSegment,OptimisticLinkPatchWire,@@ -108,12 +109,15 @@ export type QueryRevalidation = {};export type OptimisticMutationOptions = {+ /** Required RFC UUID; reuse only when the newer intent safely replaces the older one. */+ uuid: string;updates?: readonly OptimisticUpdate[];/** Relevant queries that cannot safely be updated still revalidate on success. */revalidations?: readonly QueryRevalidation[];};export type OptimisticMutationContext<TData = unknown> = {+ uuid: string;optimisticResponse: TData;linkPatches: OptimisticLinkPatchWire[];revalidations: QueryRevalidationWire[];@@ -129,6 +133,11 @@ export type OptimisticMutationDisposition<TData> =export type OptimisticMutationDispositionMetadata =| { kind: 'committed'; transactionId?: string }| { kind: 'queued'; transactionId: string }+ | {+ kind: 'superseded';+ transactionId: string;+ replacementTransactionId: string;+ }| { kind: 'permanently-failed'; transactionId?: string };/** Returns a copy of an operation result carrying its queue disposition. */@@ -150,7 +159,14 @@ export function withOptimisticMutationDisposition(// that would roll back UI state or block the next edit.error: undefined,}- : {}),+ : disposition.kind === 'superseded'+ ? {+ // The replacement's optimistic payload is already visible in the+ // cache. Never expose this older operation's stale response.+ data: undefined,+ error: undefined,+ }+ : {}),extensions: {...result.extensions,[OPTIMISTIC_MUTATION_DISPOSITION_KEY]: disposition,@@ -175,6 +191,12 @@ export function optimisticMutationDispositionOf<if (metadata.kind === 'queued' && metadata.transactionId) {return { kind: 'queued', transactionId: metadata.transactionId };}+ if (metadata.kind === 'superseded' && metadata.replacementTransactionId) {+ return {+ kind: 'queued',+ transactionId: metadata.replacementTransactionId,+ };+ }if (metadata.kind === 'committed' && result.data != null) {return { kind: 'committed', data: result.data };}@@ -371,9 +393,13 @@ export function executeOptimisticMutation<document: TypedDocumentNode<TData, TVariables>,variables: TVariables,optimisticData: TData,- options: OptimisticMutationOptions = {}+ options: OptimisticMutationOptions): OperationResultSource<OperationResult<TData, TVariables>> {+ if (!validateUuid(options.uuid)) {+ throw new TypeError(`invalid optimistic mutation UUID: ${options.uuid}`);+ }const context: OptimisticMutationContext<TData> = {+ uuid: options.uuid,optimisticResponse: optimisticData,linkPatches: [...(options.updates ?? [])],revalidations: (options.revalidations ?? []).map(serializeRevalidation),@@ -396,7 +422,13 @@ export function optimisticContextOf(const context = value as Partial<OptimisticMutationContext> & {optimisticResponse: unknown;};+ if (typeof context.uuid !== 'string' || !validateUuid(context.uuid)) {+ throw new TypeError(+ 'invalid optimistic mutation UUID in operation context'+ );+ }return {+ uuid: context.uuid,optimisticResponse: context.optimisticResponse,linkPatches: Array.isArray(context.linkPatches)? context.linkPatchesdiff --git a/apps/web/src/lib/graphql-cache/host/noop-host.ts b/apps/web/src/lib/graphql-cache/host/noop-host.tsindex cbaa58d312..48c0e1c86e 100644--- a/apps/web/src/lib/graphql-cache/host/noop-host.ts+++ b/apps/web/src/lib/graphql-cache/host/noop-host.ts@@ -1,4 +1,5 @@import type {+ CommitOptimisticWriteResult,EnqueueOptimisticMutationResult,ReadResult,WriteResult,@@ -57,12 +58,14 @@ export function createNoopCacheHost(reason: string): CacheHost {async claimNextMutation() {return undefined;},- async deferOptimisticWrite(): Promise<void> {},- async commitOptimisticWrite(): Promise<WriteResult> {- return emptyWriteResult();+ async deferOptimisticWrite() {+ return { kind: 'deferred' } as const;},- async rollbackOptimisticWrite(): Promise<WriteResult> {- return emptyWriteResult();+ async commitOptimisticWrite(): Promise<CommitOptimisticWriteResult> {+ return { kind: 'committed', ...emptyWriteResult() };+ },+ async rollbackOptimisticWrite() {+ return { kind: 'rolled-back' as const, ...emptyWriteResult() };},async invalidate() {return { revision: INITIAL_CACHE_REVISION, affectedOps: [] };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 91047c5821..e631621455 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@@ -217,18 +217,24 @@ describe('createTauriCacheHost', () => {changed: ['A:1'],affectedOps: [],reset: false,+ upsertKind: { kind: 'inserted' as const },initialClaim: { kind: 'not-runnable' as const },};invokeMock.mockImplementation((command: string) => {if (command === 'graphql_cache_enqueue_optimistic_mutation') {return Promise.resolve(optimistic);}- if (- command === 'graphql_cache_commit_optimistic_write' ||- command === 'graphql_cache_rollback_optimistic_write'- ) {+ if (command === 'graphql_cache_commit_optimistic_write') {return Promise.resolve({ changed: [], affectedOps: [], reset: false });}+ if (command === 'graphql_cache_rollback_optimistic_write') {+ return Promise.resolve({+ kind: 'rolled-back',+ changed: [],+ affectedOps: [],+ reset: false,+ });+ }return Promise.resolve(null);});@@ -245,6 +251,7 @@ describe('createTauriCacheHost', () => {};const begun = await host.enqueueOptimisticMutation({+ uuid: '00000000-0000-4000-8000-000000000004',query: 'mutation { m }',data: { m: 1 },linkPatches: [patch],@@ -259,6 +266,7 @@ describe('createTauriCacheHost', () => {expect(invokeMock).toHaveBeenCalledWith('graphql_cache_enqueue_optimistic_mutation',expect.objectContaining({+ uuid: '00000000-0000-4000-8000-000000000004',linkPatches: [patch],createdAtMs: 123,owner: 'runner',@@ -446,7 +454,11 @@ describe('createTauriCacheHost', () => {let settled = false;void host.enqueueOptimisticMutation(- { query: 'mutation Rename { rename { id } }', data: {} },+ {+ uuid: '00000000-0000-4000-8000-000000000101',+ query: 'mutation Rename { rename { id } }',+ data: {},+ },{ owner: 'runner', nowMs: 10, leaseExpiresAtMs: 1_010 }).then(diff --git a/apps/web/src/lib/graphql-cache/host/tauri-host.ts b/apps/web/src/lib/graphql-cache/host/tauri-host.tsindex 877b5e5e28..ea4a05fc12 100644--- a/apps/web/src/lib/graphql-cache/host/tauri-host.ts+++ b/apps/web/src/lib/graphql-cache/host/tauri-host.ts@@ -15,6 +15,8 @@ import type {CachedQueryVariantWire,CacheRevision,ClaimedMutation,+ CommitOptimisticWriteResult,+ DeferOptimisticWriteResult,EnqueueOptimisticMutationResult,HydrationResult,MutationClaim,@@ -22,6 +24,7 @@ import type {ReadRecordsByKeysArgs,ReadRecordsByKeysResult,ReadResult,+ RollbackOptimisticWriteResult,SearchCacheArgs,SearchCachePage,WriteResult,@@ -247,6 +250,7 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {'graphql_cache_enqueue_optimistic_mutation',{originOpId: args.opKey === undefined ? undefined : opId(args.opKey),+ uuid: args.uuid,query: args.query,operationName: args.operationName,variables: args.variables,@@ -308,24 +312,27 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {claim: MutationClaim,nextAttemptAtMs: number,error: string- ): Promise<void> {+ ): Promise<DeferOptimisticWriteResult> {await ready;- await request('graphql_cache_defer_optimistic_write', {- transactionId,- leaseOwner: claim.owner,- leaseGeneration: claim.generation,- nextAttemptAtMs,- error,- });+ return await request<DeferOptimisticWriteResult>(+ 'graphql_cache_defer_optimistic_write',+ {+ transactionId,+ leaseOwner: claim.owner,+ leaseGeneration: claim.generation,+ nextAttemptAtMs,+ error,+ }+ );},async commitOptimisticWrite(transactionId: string,claim: MutationClaim,args: CacheWriteArgs- ): Promise<WriteResult> {+ ): Promise<CommitOptimisticWriteResult> {await ready;- return await request<WriteResult>(+ return await request<CommitOptimisticWriteResult>('graphql_cache_commit_optimistic_write',{transactionId,@@ -343,9 +350,9 @@ export function createTauriCacheHost(options: TauriHostOptions): CacheHost {transactionId: string,claim: MutationClaim,error: string- ): Promise<WriteResult> {+ ): Promise<RollbackOptimisticWriteResult> {await ready;- return await request<WriteResult>(+ return await request<RollbackOptimisticWriteResult>('graphql_cache_rollback_optimistic_write',{transactionId,diff --git a/apps/web/src/lib/graphql-cache/host/types.ts b/apps/web/src/lib/graphql-cache/host/types.tsindex 2ab919cd11..3e5e79a3db 100644--- a/apps/web/src/lib/graphql-cache/host/types.ts+++ b/apps/web/src/lib/graphql-cache/host/types.ts@@ -14,6 +14,8 @@ import type {CacheReadPriority,CacheRevision,ClaimedMutation,+ CommitOptimisticWriteResult,+ DeferOptimisticWriteResult,EnqueueOptimisticMutationResult,EntityFilterCacheArgs,EntityFilterCacheResult,@@ -26,6 +28,7 @@ import type {ReadRecordsByKeysArgs,ReadRecordsByKeysResult,ReadResult,+ RollbackOptimisticWriteResult,SearchCacheArgs,SearchCachePage,WriteResult,@@ -67,6 +70,8 @@ export interface CacheWriteArgs extends Omit<CacheReadArgs, 'priority'> {}export interface EnqueueOptimisticMutationArgs extends CacheWriteArgs {+ /** Caller-supplied RFC UUID used for explicit safe coalescing. */+ uuid: string;linkPatches?: OptimisticLinkPatchWire[];/** Revalidations for relevant cached fields that could not be patched. */revalidations?: QueryRevalidationWire[];@@ -122,19 +127,19 @@ export interface CacheHost {claim: MutationClaim,nextAttemptAtMs: number,error: string- ): Promise<void>;+ ): Promise<DeferOptimisticWriteResult>;/** Atomically commits a claimed mutation's real network response. */commitOptimisticWrite(transactionId: string,claim: MutationClaim,args: CacheWriteArgs- ): Promise<WriteResult>;+ ): Promise<CommitOptimisticWriteResult>;/** Permanently fails a claimed mutation and drops its optimistic layer. */rollbackOptimisticWrite(transactionId: string,claim: MutationClaim,error: string- ): Promise<WriteResult>;+ ): Promise<RollbackOptimisticWriteResult>;/** Evict records by entity key (external/push updates); returns affected local op ids. */invalidate(keys: string[]): Promise<AffectedOperationsResult>;/** Apply explicit server-provided cache-deletion effects. */@@ -157,7 +162,7 @@ export interface CacheHost {/** Invalidates revision watermarks before a replacement engine is used. */onCacheGenerationChanged(cb: () => void): () => void;- /** Subscribes to final commit/rollback events for queued mutations. */+ /** Subscribes to final commit, rollback, or supersession events. */onMutationSettled(cb: (settlement: MutationSettlement) => void): () => void;dispose(): void;diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.tsindex 5ec9ee9756..efab6bed68 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.integration.test.ts@@ -62,6 +62,7 @@ function optimisticMutation(key: number, query: Operation['query']): Operation {url: 'http://integration.test',suspense: false,normalizedCacheOptimistic: {+ uuid: '00000000-0000-4000-8000-000000000001',optimisticResponse: { held: true },},} as never);@@ -169,6 +170,7 @@ class IntegrationCore {changed: [],affectedOps: [],reset: false,+ upsertKind: { kind: 'inserted' },initialClaim: { kind: 'not-runnable' },};}diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts b/apps/web/src/lib/graphql-cache/host/worker-host.test.tsindex 2a90cb5c0a..c7e3dee1d5 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.test.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.test.ts@@ -398,6 +398,7 @@ describe('createWorkerCacheHost', () => {}),host.enqueueOptimisticMutation({+ uuid: '00000000-0000-4000-8000-000000000005',opKey: 9,query: 'mutation Rename { rename { id } }',data: { rename: { id: 'doc-1' } },@@ -474,6 +475,11 @@ describe('createWorkerCacheHost', () => {nowMs: 123,},});+ expect(requests[5]).toEqual(+ expect.objectContaining({+ uuid: '00000000-0000-4000-8000-000000000005',+ })+ );expect(requests[4]).toEqual(expect.objectContaining({originOpId: `${CLIENT_ID}:8`,@@ -521,7 +527,11 @@ describe('createWorkerCacheHost', () => {const read = host.readQuery({ opKey: 4, query: 'query Read { user }' });const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });const readRejected = expect(read).rejects.toThrow(@@ -578,7 +588,11 @@ describe('createWorkerCacheHost', () => {const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });const readRejected = expect(read).rejects.toMatchObject({@@ -662,6 +676,7 @@ describe('createWorkerCacheHost', () => {const read = host.readQuery({ query: 'query Read { user { id } }' });const mutation = host.enqueueOptimisticMutation({+ uuid: '00000000-0000-4000-8000-000000000006',query: 'mutation Rename { rename { id } }',data: { rename: { id: 'doc-1' } },},@@ -721,7 +736,11 @@ describe('createWorkerCacheHost', () => {const read = host.readQuery({ opKey: 44, query: 'query Read { user }' });const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });const readRejected = expect(read).rejects.toThrow('owner epoch 1 was lost');@@ -959,7 +978,11 @@ describe('createWorkerCacheHost', () => {await host.clear();const adapter = requireAdapter();const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });const mutationRejected = expect(mutation).rejects.toMatchObject({@@ -1138,7 +1161,11 @@ describe('createWorkerCacheHost', () => {});adapter.dispose.mockImplementationOnce(async () => await draining);const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });await vi.waitFor(() =>@@ -1275,7 +1302,11 @@ describe('createWorkerCacheHost', () => {});adapter.dispose.mockImplementationOnce(async () => await draining);const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });await vi.waitFor(() =>@@ -1309,7 +1340,11 @@ describe('createWorkerCacheHost', () => {await host.clear();const adapter = requireAdapter();const mutation = host.enqueueOptimisticMutation(- { query: 'mutation Update { update }', data: { update: true } },+ {+ uuid: '00000000-0000-4000-8000-000000000100',+ query: 'mutation Update { update }',+ data: { update: true },+ },{ owner: 'runner', nowMs: 1, leaseExpiresAtMs: 101 });const rejected = expect(mutation).rejects.toMatchObject({diff --git a/apps/web/src/lib/graphql-cache/host/worker-host.ts b/apps/web/src/lib/graphql-cache/host/worker-host.tsindex 9f10c32cb2..0053a1a098 100644--- a/apps/web/src/lib/graphql-cache/host/worker-host.ts+++ b/apps/web/src/lib/graphql-cache/host/worker-host.ts@@ -14,6 +14,8 @@ import {type CacheResponseErrorCode,type CacheRevision,type ClaimedMutation,+ type CommitOptimisticWriteResult,+ type DeferOptimisticWriteResult,type EnqueueOptimisticMutationResult,type EntityFilterCacheArgs,type EntityFilterCacheResult,@@ -26,6 +28,7 @@ import {type ReadRecordsByKeysArgs,type ReadRecordsByKeysResult,type ReadResult,+ type RollbackOptimisticWriteResult,type SearchCacheArgs,type SearchCachePage,validateCacheSearchArgs,@@ -916,6 +919,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {return (await request({kind: 'enqueue-optimistic-mutation',originOpId: args.opKey === undefined ? undefined : opId(args.opKey),+ uuid: args.uuid,query: args.query,operationName: args.operationName,variables: args.variables,@@ -973,23 +977,23 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {claim: MutationClaim,nextAttemptAtMs: number,error: string- ): Promise<void> {+ ) {await ensureInitialized();- await request({+ return (await request({kind: 'defer-optimistic-write',transactionId,leaseOwner: claim.owner,leaseGeneration: claim.generation,nextAttemptAtMs,error,- });+ })) as DeferOptimisticWriteResult;},async commitOptimisticWrite(transactionId: string,claim: MutationClaim,args: CacheWriteArgs- ): Promise<WriteResult> {+ ): Promise<CommitOptimisticWriteResult> {await ensureInitialized();return (await request({kind: 'commit-optimistic-write',@@ -1000,14 +1004,14 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {operationName: args.operationName,variables: args.variables,data: args.data,- })) as WriteResult;+ })) as CommitOptimisticWriteResult;},async rollbackOptimisticWrite(transactionId: string,claim: MutationClaim,error: string- ): Promise<WriteResult> {+ ): Promise<RollbackOptimisticWriteResult> {await ensureInitialized();return (await request({kind: 'rollback-optimistic-write',@@ -1015,7 +1019,7 @@ export function createWorkerCacheHost(options: WorkerHostOptions): CacheHost {leaseOwner: claim.owner,leaseGeneration: claim.generation,error,- })) as WriteResult;+ })) as RollbackOptimisticWriteResult;},async invalidate(keys: string[]): Promise<AffectedOperationsResult> {diff --git a/apps/web/src/lib/graphql-cache/protocol.test.ts b/apps/web/src/lib/graphql-cache/protocol.test.tsindex cbcf668c43..afbcb39ad5 100644--- a/apps/web/src/lib/graphql-cache/protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/protocol.test.ts@@ -153,6 +153,14 @@ describe('cache worker message validators', () => {kind: 'mutation-settled',settlement: {transactionId: '4',+ status: 'superseded',+ replacementTransactionId: '5',+ },+ },+ {+ kind: 'mutation-settled',+ settlement: {+ transactionId: '6',status: 'permanently-failed',error: 'denied',},@@ -184,6 +192,10 @@ describe('cache worker message validators', () => {kind: 'mutation-settled',settlement: { transactionId: '4', status: 'permanently-failed' },},+ {+ kind: 'mutation-settled',+ settlement: { transactionId: '5', status: 'superseded' },+ },])('rejects malformed or extended worker message %#', (value) => {expect(isWorkerMessage(value)).toBe(false);});diff --git a/apps/web/src/lib/graphql-cache/protocol.ts b/apps/web/src/lib/graphql-cache/protocol.tsindex 3616898fe0..9b88dde21f 100644--- a/apps/web/src/lib/graphql-cache/protocol.ts+++ b/apps/web/src/lib/graphql-cache/protocol.ts@@ -329,9 +329,17 @@ export type OptimisticWriteResult = WriteResult & {transactionId: string;};+/** How a caller UUID changed the durable queue. */+export type MutationUpsertKind =+ | { kind: 'inserted' }+ | { kind: 'replaced-pending'; removedTransactionId: string }+ | { kind: 'appended-after-active'; activeTransactionId: string };+/** Claimed strict queue head, ready to be forwarded through urql. */export type ClaimedMutation = {transactionId: string;+ uuid: string;+ superseded: boolean;leaseGeneration: string;query: string;operationName?: string;@@ -349,6 +357,7 @@ export type InitialMutationClaim =/** Result returned after enqueue and the initial claim attempt complete. */export type EnqueueOptimisticMutationResult = OptimisticWriteResult & {+ upsertKind: MutationUpsertKind;initialClaim: InitialMutationClaim;};@@ -358,9 +367,38 @@ export type MutationClaim = {generation: string;};+/** Result of deferring a retryable attempt. */+export type DeferOptimisticWriteResult =+ | { kind: 'deferred' }+ | (WriteResult & {+ kind: 'discarded-superseded';+ replacementTransactionId: string;+ });++/** Result of committing a current or superseded attempt. */+export type CommitOptimisticWriteResult =+ | (WriteResult & { kind: 'committed' })+ | (WriteResult & {+ kind: 'committed-superseded';+ replacementTransactionId: string;+ });++/** Result of rolling back a failed attempt. */+export type RollbackOptimisticWriteResult =+ | (WriteResult & { kind: 'rolled-back' })+ | (WriteResult & {+ kind: 'discarded-superseded';+ replacementTransactionId: string;+ });+/** Final settlement of a previously queued optimistic mutation. */export type MutationSettlement =| { transactionId: string; status: 'committed' }+ | {+ transactionId: string;+ status: 'superseded';+ replacementTransactionId: string;+ }| {transactionId: string;status: 'permanently-failed';@@ -411,6 +449,7 @@ export type CacheRequest = { id: number } & (| {kind: 'enqueue-optimistic-mutation';originOpId?: string;+ uuid: string;query: string;operationName?: string;variables?: Record<string, unknown>;@@ -618,6 +657,15 @@ export function isCachePush(value: unknown): value is CachePush {if (settlement.status === 'committed') {return hasOnlyWireKeys(settlement, ['transactionId', 'status']);}+ if (settlement.status === 'superseded') {+ return (+ hasOnlyWireKeys(settlement, [+ 'transactionId',+ 'status',+ 'replacementTransactionId',+ ]) && typeof settlement.replacementTransactionId === 'string'+ );+ }return (settlement.status === 'permanently-failed' &&hasOnlyWireKeys(settlement, ['transactionId', 'status', 'error']) &&diff --git a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.tsindex a954dc7a78..fd37d89163 100644--- a/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts+++ b/apps/web/src/lib/graphql-cache/worker/browser-test/cache-recovery-harness.ts@@ -238,6 +238,7 @@ const enqueueRequest = (createdAtMs: number): ProductionCacheRequestWithoutId => ({kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000011',query: MUTATION,operationName: 'SetEntityProperty',variables: MUTATION_VARIABLES,diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.tsindex 54ef7cec71..b26eec73ca 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.test.ts@@ -57,6 +57,19 @@ describe('coordinator runtime protocol', () => {data: { user: { id: 'user-1' } },})).toBe(false);+ const enqueue = {+ id: 2,+ kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000001',+ query: 'mutation Update { update }',+ data: { update: true },+ createdAtMs: 1,+ owner: 'runner',+ nowMs: 1,+ leaseExpiresAtMs: 1_001,+ };+ expect(isCacheRequest(enqueue)).toBe(true);+ expect(isCacheRequest({ ...enqueue, uuid: undefined })).toBe(false);expect(isCacheRequest({id: 2,diff --git a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.tsindex 2e1c2c8b37..38339fcf84 100644--- a/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts+++ b/apps/web/src/lib/graphql-cache/worker/coordinator-protocol.ts@@ -430,6 +430,7 @@ export function isCacheRequest(value: unknown): value is CacheRequest {'id','kind','originOpId',+ 'uuid','query','operationName','variables',@@ -442,6 +443,7 @@ export function isCacheRequest(value: unknown): value is CacheRequest {'leaseExpiresAtMs',]) &&isOptionalString(value.originOpId) &&+ isString(value.uuid) &&isString(value.query) &&isOptionalString(value.operationName) &&isOptionalRecord(value.variables) &&diff --git a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts b/apps/web/src/lib/graphql-cache/worker/wasm-module.tsindex 73ceecb80a..7f52b0886d 100644--- a/apps/web/src/lib/graphql-cache/worker/wasm-module.ts+++ b/apps/web/src/lib/graphql-cache/worker/wasm-module.ts@@ -16,6 +16,8 @@ import type {CacheRevision,CacheRevisionResult,ClaimedMutation,+ CommitOptimisticWriteResult,+ DeferOptimisticWriteResult,EnqueueOptimisticMutationResult,EntityFilterCacheArgs,EntityFilterCacheResult,@@ -23,6 +25,7 @@ import type {QueryRevalidationWire,ReadRecordsByKeysResult,ReadResult,+ RollbackOptimisticWriteResult,SearchCacheArgs,SearchCachePage,WriteResult,@@ -110,6 +113,7 @@ export interface CacheEngine {): Promise<CacheEngineHydrationResult>;enqueueOptimisticMutation(originOpId: string | undefined,+ uuid: string,query: string,operationName: string | undefined,variables: Record<string, unknown> | undefined,@@ -143,7 +147,7 @@ export interface CacheEngine {leaseGeneration: string,nextAttemptAtMs: number,error: string- ): Promise<void>;+ ): Promise<DeferOptimisticWriteResult>;commitOptimisticWrite(transactionId: string,leaseOwner: string,@@ -152,12 +156,12 @@ export interface CacheEngine {operationName: string | undefined,variables: Record<string, unknown> | undefined,data: unknown- ): Promise<WriteResult>;+ ): Promise<CommitOptimisticWriteResult>;rollbackOptimisticWrite(transactionId: string,leaseOwner: string,leaseGeneration: string- ): Promise<WriteResult>;+ ): Promise<RollbackOptimisticWriteResult>;invalidateKeys(keys: string[]): Promise<AffectedOperationsResult>;deleteKeys(keys: string[]): Promise<AffectedOperationsResult>;teardownOperation(opId: string): Promise<void>;diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.test.tsindex 97d41364f0..7066345db6 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.test.ts@@ -100,6 +100,50 @@ describe('CacheWorkerCore', () => {expect(messages.at(-1)).toEqual({ id: 2, ok: true, result: page });});+ it('reports a successful stale commit as superseded', async () => {+ const commitOptimisticWrite = vi.fn().mockResolvedValue({+ kind: 'committed-superseded',+ replacementTransactionId: '2',+ revision: INITIAL_CACHE_REVISION,+ changed: [],+ affectedOps: [],+ reset: false,+ revalidations: [],+ });+ loadCacheWasmMock.mockResolvedValue({+ openCache: vi.fn().mockResolvedValue({ commitOptimisticWrite }),+ });+ const messages: unknown[] = [];+ const port = { postMessage: (message: unknown) => messages.push(message) };+ const core = new CacheWorkerCore();+ core.addPort(port);+ await core.handleRequest(port, {+ id: 1,+ kind: 'init',+ scope: 'scope-1',+ });+ messages.length = 0;++ await core.handleRequest(port, {+ id: 2,+ kind: 'commit-optimistic-write',+ transactionId: '1',+ leaseOwner: 'runner',+ leaseGeneration: '1',+ query: 'mutation Update { update }',+ data: { update: true },+ });++ expect(messages).toContainEqual({+ kind: 'mutation-settled',+ settlement: {+ transactionId: '1',+ status: 'superseded',+ replacementTransactionId: '2',+ },+ });+ });+it('finishes the initial claim before pushes or queued reads run', async () => {const order: string[] = [];let resolveEnqueue!: (result: {@@ -108,6 +152,10 @@ describe('CacheWorkerCore', () => {changed: string[];affectedOps: string[];reset: false;+ upsertKind: {+ kind: 'replaced-pending';+ removedTransactionId: string;+ };initialClaim: { kind: 'not-runnable' };}) => void;const enqueueOptimisticMutation = vi.fn(() => {@@ -118,6 +166,10 @@ describe('CacheWorkerCore', () => {changed: string[];affectedOps: string[];reset: false;+ upsertKind: {+ kind: 'replaced-pending';+ removedTransactionId: string;+ };initialClaim: { kind: 'not-runnable' };}>((resolve) => {resolveEnqueue = (result) => {@@ -150,6 +202,7 @@ describe('CacheWorkerCore', () => {const enqueue = core.handleRequest(port, {id: 2,kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000007',query: 'mutation Update { update }',data: { update: true },createdAtMs: 10,@@ -180,6 +233,10 @@ describe('CacheWorkerCore', () => {changed: ['Thing:1'],affectedOps: ['client:query'],reset: false,+ upsertKind: {+ kind: 'replaced-pending',+ removedTransactionId: '0',+ },initialClaim: { kind: 'not-runnable' },});await Promise.all([enqueue, read]);@@ -190,6 +247,14 @@ describe('CacheWorkerCore', () => {opIds: ['client:query'],keys: ['Thing:1'],});+ expect(messages).toContainEqual({+ kind: 'mutation-settled',+ settlement: {+ transactionId: '0',+ status: 'superseded',+ replacementTransactionId: '1',+ },+ });});it('runs standalone claims ahead of queued observational reads', async () => {@@ -431,7 +496,7 @@ describe('CacheWorkerCore', () => {return { kind: 'hit' as const, data: { opId } };});const enqueueOptimisticMutation = vi.fn(- async (_originOpId: string | undefined, query: string) => {+ async (_originOpId: string | undefined, _uuid: string, query: string) => {order.push(`enqueue:${query}`);return {transactionId: query,@@ -439,6 +504,7 @@ describe('CacheWorkerCore', () => {changed: [],affectedOps: [],reset: false,+ upsertKind: { kind: 'inserted' as const },initialClaim: { kind: 'not-runnable' as const },};}@@ -481,6 +547,7 @@ describe('CacheWorkerCore', () => {const firstEnqueue = core.handleRequest(port, {id: 5,kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000008',query: 'mutation First { first }',data: { first: true },createdAtMs: 1,@@ -491,6 +558,7 @@ describe('CacheWorkerCore', () => {const secondEnqueue = core.handleRequest(port, {id: 6,kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000009',query: 'mutation Second { second }',data: { second: true },createdAtMs: 2,@@ -661,6 +729,7 @@ describe('CacheWorkerCore', () => {changed: [],affectedOps: [],reset: false,+ upsertKind: { kind: 'inserted' as const },initialClaim: { kind: 'not-runnable' as const },};});@@ -700,6 +769,7 @@ describe('CacheWorkerCore', () => {const enqueue = core.handleRequest(port, {id: 5,kind: 'enqueue-optimistic-mutation',+ uuid: '00000000-0000-4000-8000-000000000010',query: 'mutation Update { update }',data: { update: true },createdAtMs: 1,diff --git a/apps/web/src/lib/graphql-cache/worker/worker-core.ts b/apps/web/src/lib/graphql-cache/worker/worker-core.tsindex 4ff0f6ba3f..b3f9ebaf49 100644--- a/apps/web/src/lib/graphql-cache/worker/worker-core.ts+++ b/apps/web/src/lib/graphql-cache/worker/worker-core.ts@@ -502,6 +502,7 @@ export class CacheWorkerCore {const result: EnqueueOptimisticMutationResult =await engine.enqueueOptimisticMutation(request.originOpId,+ request.uuid,request.query,request.operationName,request.variables,@@ -515,6 +516,16 @@ export class CacheWorkerCore {);result.revision = parseCacheRevision(result.revision);this.fanOut(result, true);+ if (result.upsertKind.kind === 'replaced-pending') {+ this.push({+ kind: 'mutation-settled',+ settlement: {+ transactionId: result.upsertKind.removedTransactionId,+ status: 'superseded',+ replacementTransactionId: result.transactionId,+ },+ });+ }return result;}).with({ kind: 'inspect-query-variants' }, async (request) => {@@ -542,14 +553,26 @@ export class CacheWorkerCore {}).with({ kind: 'defer-optimistic-write' }, async (request) => {const engine = this.requireEngine();- await engine.deferOptimisticWrite(+ const result = await engine.deferOptimisticWrite(request.transactionId,request.leaseOwner,request.leaseGeneration,request.nextAttemptAtMs,request.error);- return null;+ if (result.kind === 'discarded-superseded') {+ result.revision = parseCacheRevision(result.revision);+ this.fanOut(result, true);+ this.push({+ kind: 'mutation-settled',+ settlement: {+ transactionId: request.transactionId,+ status: 'superseded',+ replacementTransactionId: result.replacementTransactionId,+ },+ });+ }+ return result;}).with({ kind: 'commit-optimistic-write' }, async (request) => {const engine = this.requireEngine();@@ -567,10 +590,17 @@ export class CacheWorkerCore {this.fanOut(result, true);this.push({kind: 'mutation-settled',- settlement: {- transactionId: request.transactionId,- status: 'committed',- },+ settlement:+ result.kind === 'committed-superseded'+ ? {+ transactionId: request.transactionId,+ status: 'superseded',+ replacementTransactionId: result.replacementTransactionId,+ }+ : {+ transactionId: request.transactionId,+ status: 'committed',+ },});return result;})@@ -585,11 +615,18 @@ export class CacheWorkerCore {this.fanOut(result, true);this.push({kind: 'mutation-settled',- settlement: {- transactionId: request.transactionId,- status: 'permanently-failed',- error: request.error,- },+ settlement:+ result.kind === 'discarded-superseded'+ ? {+ transactionId: request.transactionId,+ status: 'superseded',+ replacementTransactionId: result.replacementTransactionId,+ }+ : {+ transactionId: request.transactionId,+ status: 'permanently-failed',+ error: request.error,+ },});return result;})diff --git a/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts b/apps/web/src/lib/queries/properties/graphql/entity-options.test.tsindex d0ced0bb75..e914eb0ac3 100644--- a/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts+++ b/apps/web/src/lib/queries/properties/graphql/entity-options.test.ts@@ -1,4 +1,5 @@import type { Property, PropertyDefinitionDomain } from '@property/types';+import { validate as validateUuid } from 'uuid';import { beforeEach, describe, expect, it, vi } from 'vitest';const executeOptimisticMutationMock = vi.hoisted(() => vi.fn());@@ -126,9 +127,33 @@ describe('updateGraphqlEntityPropertyOptions', () => {]);// The record already exists, so the entity's property link list is intact.expect(options.revalidations).toEqual([]);+ expect(validateUuid(options.uuid)).toBe(true);expect(inspectMock).not.toHaveBeenCalled();});+ it('uses a fresh UUID for each non-coalescible delta batch', async () => {+ const input = {+ entityType: 'DOCUMENT' as const,+ entityId: 'doc-1',+ properties: [+ {+ property: tagProperty,+ currentOptionIds: ['stale'],+ nextOptionIds: ['spotlight'],+ },+ ],+ };++ await updateGraphqlEntityPropertyOptions(input);+ await updateGraphqlEntityPropertyOptions(input);++ const uuids = executeOptimisticMutationMock.mock.calls.map(+ (call) => call[4].uuid+ );+ expect(uuids.every(validateUuid)).toBe(true);+ expect(new Set(uuids).size).toBe(2);+ });+it('revalidates only the cached queries holding the entity when it has no record for the definition', async () => {inspectMock.mockResolvedValueOnce([diff --git a/apps/web/src/lib/queries/properties/graphql/entity-options.ts b/apps/web/src/lib/queries/properties/graphql/entity-options.tsindex 3d81977e66..61ce596209 100644--- a/apps/web/src/lib/queries/properties/graphql/entity-options.ts+++ b/apps/web/src/lib/queries/properties/graphql/entity-options.ts@@ -154,7 +154,7 @@ export async function updateGraphqlEntityPropertyOptions(UpdateEntityPropertyOptionsDocument,variables,{ updateEntityPropertyOptions: optimisticProperties },- { revalidations }+ { uuid: crypto.randomUUID(), revalidations }).toPromise();const disposition = optimisticMutationDispositionOf<diff --git a/apps/web/src/lib/queries/properties/graphql/entity.test.ts b/apps/web/src/lib/queries/properties/graphql/entity.test.tsindex 71d0f68748..73b5b6eb20 100644--- a/apps/web/src/lib/queries/properties/graphql/entity.test.ts+++ b/apps/web/src/lib/queries/properties/graphql/entity.test.ts@@ -9,6 +9,7 @@ import {type OperationResult,} from '@urql/core';import { createRoot, createSignal } from 'solid-js';+import { validate as validateUuid } from 'uuid';import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';import { filter, makeSubject, mergeMap, pipe } from 'wonka';@@ -31,6 +32,7 @@ import {createGraphqlAddEntityPropertyMutation,createGraphqlBulkSaveEntityPropertiesMutation,createGraphqlEntityPropertiesQuery,+ entityPropertyOptimisticMutationUuid,mapGraphqlEntityProperties,} from './entity';@@ -172,6 +174,39 @@ describe('mapGraphqlEntityProperties', () => {});});+describe('entityPropertyOptimisticMutationUuid', () => {+ it('is stable per property slot and distinct across slots', () => {+ const args = {+ entityType: 'DOCUMENT' as const,+ entityId: 'document-1',+ propertyDefinitionId: 'property-1',+ };+ const uuid = entityPropertyOptimisticMutationUuid(args);++ expect(validateUuid(uuid)).toBe(true);+ expect(entityPropertyOptimisticMutationUuid(args)).toBe(uuid);+ expect(+ entityPropertyOptimisticMutationUuid({+ ...args,+ propertyDefinitionId: 'property-2',+ })+ ).not.toBe(uuid);+ expect(+ entityPropertyOptimisticMutationUuid({+ ...args,+ entityId: 'document-1:property',+ propertyDefinitionId: '1',+ })+ ).not.toBe(+ entityPropertyOptimisticMutationUuid({+ ...args,+ entityId: 'document-1',+ propertyDefinitionId: 'property:1',+ })+ );+ });+});+describe('GraphQL entity property mutations', () => {let dispose: (() => void) | undefined;diff --git a/apps/web/src/lib/queries/properties/graphql/entity.ts b/apps/web/src/lib/queries/properties/graphql/entity.tsindex 88de495fbc..3821082cfa 100644--- a/apps/web/src/lib/queries/properties/graphql/entity.ts+++ b/apps/web/src/lib/queries/properties/graphql/entity.ts@@ -39,6 +39,7 @@ import {import { CombinedError, type OperationResult } from '@urql/core';import { type Accessor, createMemo } from 'solid-js';import { match } from 'ts-pattern';+import { v5 as uuidv5 } from 'uuid';import {buildOptimisticGroupedPropertyUpdates,groupedPropertyKeys,@@ -335,6 +336,26 @@ function mutationDisposition(return { kind: 'committed', property: result.data.setEntityProperty };}+const ENTITY_PROPERTY_OPTIMISTIC_UUID_NAMESPACE =+ '1697e6bc-0d9a-4dd2-bc3f-bd33bcb6f607';++/** Stable coalescing UUID for one absolute entity-property value slot. */+export function entityPropertyOptimisticMutationUuid(args: {+ entityType: GraphqlPropertyTargetEntityType;+ entityId: string;+ propertyDefinitionId: string;+}): string {+ return uuidv5(+ JSON.stringify([+ 'setEntityProperty',+ args.entityType,+ args.entityId,+ args.propertyDefinitionId,+ ]),+ ENTITY_PROPERTY_OPTIMISTIC_UUID_NAMESPACE+ );+}+const executeGraphqlEntityPropertyMutation: UrqlMutationExecutor<SetEntityPropertyMutation,SetEntityPropertyMutationVariables,@@ -356,7 +377,10 @@ const executeGraphqlEntityPropertyMutation: UrqlMutationExecutor<mutation,variables,{ setEntityProperty: args.optimisticProperty },- args.optimisticCache+ {+ ...args.optimisticCache,+ uuid: entityPropertyOptimisticMutationUuid(args),+ }).toPromise(): client.mutation(mutation, variables, context).toPromise());const disposition = mutationDisposition(mutationResult);diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts b/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.tsindex f6461eb258..c7ea71eb5d 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-activity-notifications.test.ts@@ -144,6 +144,7 @@ describe('channel activity and notification GraphQL cache separation', () => {},{normalizedCacheOptimistic: {+ uuid: expect.any(String),optimisticResponse: {updateNotifications: [{diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts b/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.tsindex 3d46eb88c8..b6e2c35b3f 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-update-notifications.ts@@ -101,7 +101,8 @@ export async function executeGraphqlUpdateNotifications(client,UpdateNotificationsDocument,variables,- optimisticData+ optimisticData,+ { uuid: crypto.randomUUID() }).toPromise();// A retryable transport failure keeps the normalized optimistic layer indiff --git a/apps/web/tauri/Cargo.lock b/apps/web/tauri/Cargo.lockindex f7dda666b5..3715440532 100644--- a/apps/web/tauri/Cargo.lock+++ b/apps/web/tauri/Cargo.lock@@ -36,7 +36,7 @@ checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"dependencies = ["cfg-if","cipher",- "cpufeatures",+ "cpufeatures 0.2.17",][[package]]@@ -777,6 +777,7 @@ dependencies = ["serde_json","sha2","thiserror 2.0.18",+ "uuid",][[package]]@@ -789,6 +790,7 @@ dependencies = ["thiserror 2.0.18","turso-opfs","turso_core",+ "uuid",][[package]]@@ -915,6 +917,17 @@ version = "0.1.1"source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "18758054972164c3264f7c8386f5fc6da6114cb46b619fd365d4e3b2dc3ae487"+[[package]]+name = "chacha20"+version = "0.10.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d524456ba66e72eb8b115ff89e01e497f8e6d11d78b70b1aa13c0fbd97540a81"+dependencies = [+ "cfg-if",+ "cpufeatures 0.3.0",+ "rand_core 0.10.1",+]+[[package]]name = "chrono"version = "0.4.44"@@ -1138,6 +1151,15 @@ dependencies = ["libc",]+[[package]]+name = "cpufeatures"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8b2a41393f66f16b0823bb79094d54ac5fbd34ab292ddafb9a0456ac9f87d201"+dependencies = [+ "libc",+]+[[package]]name = "crc"version = "3.4.0"@@ -2225,6 +2247,7 @@ dependencies = ["js-sys","libc","r-efi 6.0.0",+ "rand_core 0.10.1","wasip2","wasip3","wasm-bindgen",@@ -4518,7 +4541,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "9d1fe60d06143b2430aa532c94cfe9e29783047f06c0d7fd359a9a51b729fa25"dependencies = ["cfg-if",- "cpufeatures",+ "cpufeatures 0.2.17","opaque-debug","universal-hash",]@@ -4855,6 +4878,17 @@ dependencies = ["rand_core 0.9.5",]+[[package]]+name = "rand"+version = "0.10.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c7f5fa3a058cd35567ef9bfa5e75732bee0f9e4c55fa90477bef2dfcdbc4be80"+dependencies = [+ "chacha20",+ "getrandom 0.4.2",+ "rand_core 0.10.1",+]+[[package]]name = "rand_chacha"version = "0.2.2"@@ -4912,6 +4946,12 @@ dependencies = ["getrandom 0.3.4",]+[[package]]+name = "rand_core"+version = "0.10.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"+[[package]]name = "rand_hc"version = "0.2.0"@@ -5680,7 +5720,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"dependencies = ["cfg-if",- "cpufeatures",+ "cpufeatures 0.2.17","digest",]@@ -5697,7 +5737,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"dependencies = ["cfg-if",- "cpufeatures",+ "cpufeatures 0.2.17","digest",]@@ -7581,6 +7621,7 @@ checksum = "ddd74a9687298c6858e9b88ec8935ec45d22e8fd5e6394fa1bd4e99a87789c76"dependencies = ["getrandom 0.4.2","js-sys",+ "rand 0.10.2","serde_core","sha1_smol","wasm-bindgen",diff --git a/apps/web/tauri/graphql_cache_plugin/src/commands.rs b/apps/web/tauri/graphql_cache_plugin/src/commands.rsindex fb50f9ce94..95a8ada902 100644--- a/apps/web/tauri/graphql_cache_plugin/src/commands.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/commands.rs@@ -10,9 +10,10 @@//! worker's `{ok: false, error}` responses.use crate::engine::{- AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,- EnqueueOptimisticMutationResultWire, ReadResultWire, RecordSelectionResultWire,- WriteRegistration, WriteRequest, WriteResultWire,+ AffectedOperationsResultWire, ClaimedMutationWire, CommitOptimisticWriteResultWire,+ DeferOptimisticWriteResultWire, EngineHandle, EnqueueOptimisticMutationResultWire,+ MutationUpsertKindWire, ReadResultWire, RecordSelectionResultWire,+ RollbackOptimisticWriteResultWire, WriteRegistration, WriteRequest, WriteResultWire,};use crate::{CacheState, InitializedCache, emit_cache_changed, emit_mutation_settled, emit_ops_affected,@@ -236,6 +237,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(app: AppHandle<R>,state: State<'_, CacheState>,origin_op_id: Option<String>,+ uuid: String,query: String,operation_name: Option<String>,variables: Option<Variables>,@@ -250,6 +252,7 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(let result = engine_handle(&state)?.enqueue_optimistic_mutation(origin_op_id,+ uuid,query,operation_name,variables.unwrap_or_default(),@@ -264,6 +267,18 @@ pub async fn graphql_cache_enqueue_optimistic_mutation<R: Runtime>(.await?;emit_ops_affected(&app, &result.result.affected_ops, &result.result.changed);emit_cache_changed(&app, &result.result.revision);+ if let MutationUpsertKindWire::ReplacedPending {+ removed_transaction_id,+ } = &result.upsert_kind+ {+ emit_mutation_settled(+ &app,+ removed_transaction_id.clone(),+ "superseded",+ None,+ Some(result.transaction_id.clone()),+ );+ }Ok(result)}@@ -325,15 +340,17 @@ pub async fn graphql_cache_claim_next_mutation(/// Retains a retryable queued mutation and releases its lease.#[tauri::command]-pub async fn graphql_cache_defer_optimistic_write(+pub async fn graphql_cache_defer_optimistic_write<R: Runtime>(+ app: AppHandle<R>,state: State<'_, CacheState>,transaction_id: String,lease_owner: String,lease_generation: String,next_attempt_at_ms: i64,error: String,-) -> Result<(), String> {- engine_handle(&state)?+) -> Result<DeferOptimisticWriteResultWire, String> {+ let settlement_transaction_id = transaction_id.clone();+ let result = engine_handle(&state)?.defer_optimistic_write(transaction_id,lease_owner,@@ -341,7 +358,23 @@ pub async fn graphql_cache_defer_optimistic_write(next_attempt_at_ms,error,)- .await+ .await?;+ if let DeferOptimisticWriteResultWire::DiscardedSuperseded {+ replacement_transaction_id,+ result: write_result,+ } = &result+ {+ emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);+ emit_cache_changed(&app, &write_result.revision);+ emit_mutation_settled(+ &app,+ settlement_transaction_id,+ "superseded",+ None,+ Some(replacement_transaction_id.clone()),+ );+ }+ Ok(result)}/// Atomically replaces a claimed optimistic layer with the real response.@@ -356,7 +389,7 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(operation_name: Option<String>,variables: Option<Variables>,data: serde_json::Value,-) -> Result<WriteResultWire, String> {+) -> Result<CommitOptimisticWriteResultWire, String> {let settlement_transaction_id = transaction_id.clone();let result = engine_handle(&state)?.commit_optimistic_write(@@ -369,9 +402,30 @@ pub async fn graphql_cache_commit_optimistic_write<R: Runtime>(data,).await?;- emit_ops_affected(&app, &result.affected_ops, &result.changed);- emit_cache_changed(&app, &result.revision);- emit_mutation_settled(&app, settlement_transaction_id, "committed", None);+ let (write_result, replacement_transaction_id) = match &result {+ CommitOptimisticWriteResultWire::Committed { result } => (result, None),+ CommitOptimisticWriteResultWire::CommittedSuperseded {+ replacement_transaction_id,+ result,+ } => (result, Some(replacement_transaction_id.clone())),+ };+ emit_ops_affected(+ &app,+ &write_result.affected_ops,+ &write_result.changed,+ );+ emit_cache_changed(&app, &write_result.revision);+ emit_mutation_settled(+ &app,+ settlement_transaction_id,+ if replacement_transaction_id.is_some() {+ "superseded"+ } else {+ "committed"+ },+ None,+ replacement_transaction_id,+ );Ok(result)}@@ -384,19 +438,40 @@ pub async fn graphql_cache_rollback_optimistic_write<R: Runtime>(lease_owner: String,lease_generation: String,error: String,-) -> Result<WriteResultWire, String> {+) -> Result<RollbackOptimisticWriteResultWire, String> {let settlement_transaction_id = transaction_id.clone();let result = engine_handle(&state)?.rollback_optimistic_write(transaction_id, lease_owner, lease_generation).await?;- emit_ops_affected(&app, &result.affected_ops, &result.changed);- emit_cache_changed(&app, &result.revision);- emit_mutation_settled(- &app,- settlement_transaction_id,- "permanently-failed",- Some(error),- );+ match &result {+ RollbackOptimisticWriteResultWire::RolledBack {+ result: write_result,+ } => {+ emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);+ emit_cache_changed(&app, &write_result.revision);+ emit_mutation_settled(+ &app,+ settlement_transaction_id,+ "permanently-failed",+ Some(error),+ None,+ );+ }+ RollbackOptimisticWriteResultWire::DiscardedSuperseded {+ replacement_transaction_id,+ result: write_result,+ } => {+ emit_ops_affected(&app, &write_result.affected_ops, &write_result.changed);+ emit_cache_changed(&app, &write_result.revision);+ emit_mutation_settled(+ &app,+ settlement_transaction_id,+ "superseded",+ None,+ Some(replacement_transaction_id.clone()),+ );+ }+ }Ok(result)}diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine.rs b/apps/web/tauri/graphql_cache_plugin/src/engine.rsindex 8c8923d249..e7f22c3d0d 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine.rs@@ -13,13 +13,16 @@use cache_core::deps::OpId;use cache_core::engine::{- BeginOptimisticWrite, Engine, InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,- WriteResult,+ BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,+ InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,+ RollbackOptimisticWriteResult, WriteResult,};use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};use cache_core::query_inspection::{CachedQueryInstance, CachedQueryVariant, QueryInspection};-use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};+use cache_core::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,+};use cache_core::record_selection::{RecordSelection, SelectedRecord};use cache_core::revision::CacheRevision;use cache_core::search::{SearchPage, SearchRequest};@@ -97,6 +100,8 @@ pub struct EnqueueOptimisticMutationResultWire {/// Engine-assigned id; settle with commit/rollback. A string because JS/// numbers lose precision past 2^53 (same as the wasm shell).pub transaction_id: String,+ /// How the caller UUID changed the queue.+ pub upsert_kind: MutationUpsertKindWire,/// Visible composed-view changes caused by the new optimistic layer.#[serde(flatten)]pub result: WriteResultWire,@@ -104,6 +109,42 @@ pub struct EnqueueOptimisticMutationResultWire {pub initial_claim: InitialMutationClaimWire,}+/// Queue collision outcome serialized for the webview.+#[derive(Debug, Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+pub enum MutationUpsertKindWire {+ /// A new UUID was appended.+ Inserted,+ /// A pending row was removed and replaced at the tail.+ ReplacedPending {+ /// Removed queue transaction.+ removed_transaction_id: String,+ },+ /// A live row was retained and superseded.+ AppendedAfterActive {+ /// Still-active queue transaction.+ active_transaction_id: String,+ },+}++impl From<MutationUpsertKind> for MutationUpsertKindWire {+ fn from(kind: MutationUpsertKind) -> Self {+ match kind {+ MutationUpsertKind::Inserted => Self::Inserted,+ MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {+ removed_transaction_id: removed_id.to_string(),+ },+ MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {+ active_transaction_id: active_id.to_string(),+ },+ }+ }+}+/// Tagged outcome of the initial strict-head claim attempt.#[derive(Debug, Serialize)]#[serde(tag = "kind", rename_all = "kebab-case")]@@ -128,6 +169,10 @@ pub enum InitialMutationClaimWire {pub struct ClaimedMutationWire {/// Durable mutation id.pub transaction_id: String,+ /// Caller coalescing UUID.+ pub uuid: String,+ /// Whether a newer current row superseded this request.+ pub superseded: bool,/// Claim generation required for settlement.pub lease_generation: String,/// GraphQL mutation document.@@ -142,6 +187,74 @@ pub struct ClaimedMutationWire {pub attempt_count: u32,}+/// Tagged result of deferring or discarding a failed queue attempt.+#[derive(Debug, Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+pub enum DeferOptimisticWriteResultWire {+ /// Retry state was retained normally.+ Deferred,+ /// A superseded row was discarded instead of retried.+ DiscardedSuperseded {+ /// Current transaction carrying the newer intent.+ replacement_transaction_id: String,+ /// Cache changes caused by discarding the old layer.+ #[serde(flatten)]+ result: WriteResultWire,+ },+}++/// Tagged result of committing a current or superseded queue attempt.+#[derive(Debug, Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+pub enum CommitOptimisticWriteResultWire {+ /// The current mutation committed normally.+ Committed {+ /// Cache changes caused by commit.+ #[serde(flatten)]+ result: WriteResultWire,+ },+ /// The response committed beneath a newer optimistic replacement.+ CommittedSuperseded {+ /// Current transaction carrying the newer intent.+ replacement_transaction_id: String,+ /// Cache changes caused by commit.+ #[serde(flatten)]+ result: WriteResultWire,+ },+}++/// Tagged result of permanently failing or superseding a queue attempt.+#[derive(Debug, Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+pub enum RollbackOptimisticWriteResultWire {+ /// The current mutation permanently failed.+ RolledBack {+ /// Cache changes caused by rollback.+ #[serde(flatten)]+ result: WriteResultWire,+ },+ /// A superseded attempt was accepted and discarded.+ DiscardedSuperseded {+ /// Current transaction carrying the newer intent.+ replacement_transaction_id: String,+ /// Cache changes caused by discarding the old layer.+ #[serde(flatten)]+ result: WriteResultWire,+ },+}+impl TryFrom<ClaimedMutation> for ClaimedMutationWire {type Error = String;@@ -149,6 +262,8 @@ impl TryFrom<ClaimedMutation> for ClaimedMutationWire {let request = claimed.queued.mutation.request;Ok(Self {transaction_id: claimed.queued.id.to_string(),+ uuid: claimed.queued.uuid.to_string(),+ superseded: claimed.queued.superseded,lease_generation: claimed.lease_generation.to_string(),query: request.query,operation_name: request.operation_name,@@ -475,6 +590,7 @@ impl EngineHandle {pub async fn enqueue_optimistic_mutation(&self,origin_op_id: Option<String>,+ uuid: String,query: String,operation_name: Option<String>,variables: Variables,@@ -493,6 +609,7 @@ impl EngineHandle {.enqueue_optimistic_mutation(origin,BeginOptimisticWrite {+ uuid: &uuid,query: &query,operation_name: operation_name.as_deref(),variables: &variables,@@ -520,6 +637,7 @@ impl EngineHandle {};Ok(EnqueueOptimisticMutationResultWire {transaction_id: result.transaction_id.to_string(),+ upsert_kind: result.upsert_kind.into(),result: wire_write_result(ops, result.write_result),initial_claim,})@@ -554,19 +672,27 @@ impl EngineHandle {lease_generation: String,next_attempt_at_ms: i64,error: String,- ) -> Result<(), String> {+ ) -> Result<DeferOptimisticWriteResultWire, 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+ let mut state = self.inner.lock().await;+ let EngineState { engine, ops } = &mut *state;+ match engine.defer_optimistic_write(transaction, claim, next_attempt_at_ms, error).await- .map_err(|e| e.to_string())+ .map_err(|e| e.to_string())?+ {+ DeferOptimisticWriteResult::Deferred => Ok(DeferOptimisticWriteResultWire::Deferred),+ DeferOptimisticWriteResult::DiscardedSuperseded(result) => {+ Ok(DeferOptimisticWriteResultWire::DiscardedSuperseded {+ replacement_transaction_id: result.replacement_transaction_id.to_string(),+ result: wire_write_result(ops, result.write_result),+ })+ }+ }}/// Replaces a claimed optimistic layer with the real network response.@@ -579,7 +705,7 @@ impl EngineHandle {operation_name: Option<String>,variables: Variables,data: serde_json::Value,- ) -> Result<WriteResultWire, String> {+ ) -> Result<CommitOptimisticWriteResultWire, String> {let transaction = parse_transaction_id(&transaction_id)?;let claim = MutationClaimToken {owner: lease_owner,@@ -587,8 +713,8 @@ impl EngineHandle {};let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;- engine- .commit_optimistic_write(+ match engine+ .commit_optimistic_write_with_outcome(transaction,claim,&query,@@ -597,8 +723,20 @@ impl EngineHandle {&data,).await- .map(|result| wire_write_result(ops, result))- .map_err(|e| e.to_string())+ .map_err(|e| e.to_string())?+ {+ CommitOptimisticWriteResult::Committed(result) => {+ Ok(CommitOptimisticWriteResultWire::Committed {+ result: wire_write_result(ops, result),+ })+ }+ CommitOptimisticWriteResult::CommittedSuperseded(result) => {+ Ok(CommitOptimisticWriteResultWire::CommittedSuperseded {+ replacement_transaction_id: result.replacement_transaction_id.to_string(),+ result: wire_write_result(ops, result.write_result),+ })+ }+ }}/// Permanently fails a claimed mutation and drops its optimistic layer.@@ -607,7 +745,7 @@ impl EngineHandle {transaction_id: String,lease_owner: String,lease_generation: String,- ) -> Result<WriteResultWire, String> {+ ) -> Result<RollbackOptimisticWriteResultWire, String> {let transaction = parse_transaction_id(&transaction_id)?;let claim = MutationClaimToken {owner: lease_owner,@@ -615,11 +753,23 @@ impl EngineHandle {};let mut state = self.inner.lock().await;let EngineState { engine, ops } = &mut *state;- engine- .rollback_optimistic_write(transaction, claim)+ match engine+ .rollback_optimistic_write_with_outcome(transaction, claim).await- .map(|result| wire_write_result(ops, result))- .map_err(|e| e.to_string())+ .map_err(|e| e.to_string())?+ {+ RollbackOptimisticWriteResult::RolledBack(result) => {+ Ok(RollbackOptimisticWriteResultWire::RolledBack {+ result: wire_write_result(ops, result),+ })+ }+ RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {+ Ok(RollbackOptimisticWriteResultWire::DiscardedSuperseded {+ replacement_transaction_id: result.replacement_transaction_id.to_string(),+ result: wire_write_result(ops, result.write_result),+ })+ }+ }}/// Evicts records by entity key; returns the affected registered op ids.diff --git a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rsindex 27d138a99d..4c346e3826 100644--- a/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/engine/test.rs@@ -68,6 +68,58 @@ fn read(handle: &EngineHandle, op_id: Option<&str>) -> ReadResultWire {.unwrap()}+fn empty_write_result() -> WriteResultWire {+ WriteResultWire {+ revision: "0".to_string(),+ changed: Vec::new(),+ affected_ops: Vec::new(),+ reset: false,+ revalidations: Vec::new(),+ }+}++#[test]+fn tagged_wire_enum_fields_are_camel_case() {+ assert_eq!(+ serde_json::to_value(MutationUpsertKindWire::ReplacedPending {+ removed_transaction_id: "1".to_string(),+ })+ .unwrap(),+ serde_json::json!({"kind": "replaced-pending", "removedTransactionId": "1"})+ );+ assert_eq!(+ serde_json::to_value(MutationUpsertKindWire::AppendedAfterActive {+ active_transaction_id: "2".to_string(),+ })+ .unwrap(),+ serde_json::json!({"kind": "appended-after-active", "activeTransactionId": "2"})+ );+ assert_eq!(+ serde_json::to_value(DeferOptimisticWriteResultWire::DiscardedSuperseded {+ replacement_transaction_id: "3".to_string(),+ result: empty_write_result(),+ })+ .unwrap()["replacementTransactionId"],+ "3"+ );+ assert_eq!(+ serde_json::to_value(CommitOptimisticWriteResultWire::CommittedSuperseded {+ replacement_transaction_id: "4".to_string(),+ result: empty_write_result(),+ })+ .unwrap()["replacementTransactionId"],+ "4"+ );+ assert_eq!(+ serde_json::to_value(RollbackOptimisticWriteResultWire::DiscardedSuperseded {+ replacement_transaction_id: "5".to_string(),+ result: empty_write_result(),+ })+ .unwrap()["replacementTransactionId"],+ "5"+ );+}+#[test]fn write_then_read_round_trips() {let handle = spawn_handle();@@ -368,6 +420,7 @@ fn optimistic_layer_commits_durably() {let optimistic = block_on(handle.enqueue_optimistic_mutation(Some("client:2".to_string()),+ "00000000-0000-4000-8000-000000000001".to_string(),QUERY.to_string(),Some("Soup".to_string()),variables(),@@ -382,6 +435,7 @@ fn optimistic_layer_commits_durably() {.unwrap();assert_eq!(optimistic.result.affected_ops, vec!["client:1".to_string()]);let serialized = serde_json::to_value(&optimistic).unwrap();+ assert_eq!(serialized["upsertKind"]["kind"], "inserted");assert_eq!(serialized["initialClaim"]["kind"], "claimed");assert_eq!(serialized["initialClaim"]["mutation"]["transactionId"],@@ -391,6 +445,8 @@ fn optimistic_layer_commits_durably() {panic!("new queue head should be claimed")};assert_eq!(claimed.transaction_id, optimistic.transaction_id);+ assert_eq!(claimed.uuid, "00000000-0000-4000-8000-000000000001");+ assert!(!claimed.superseded);// The optimistic view answers reads.let ReadResultWire::Hit { data } = read(&handle, None) else {@@ -408,6 +464,9 @@ fn optimistic_layer_commits_durably() {soup_data(true),)).unwrap();+ let CommitOptimisticWriteResultWire::Committed { result: committed } = committed else {+ panic!("current transaction was reported as superseded")+ };assert!(!committed.changed.is_empty());let ReadResultWire::Hit { data } = read(&handle, None) else {@@ -423,6 +482,7 @@ fn rollback_drops_optimistic_contribution() {let optimistic = block_on(handle.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000002".to_string(),QUERY.to_string(),Some("Soup".to_string()),variables(),diff --git a/apps/web/tauri/graphql_cache_plugin/src/lib.rs b/apps/web/tauri/graphql_cache_plugin/src/lib.rsindex 4a68c11000..1b5519070f 100644--- a/apps/web/tauri/graphql_cache_plugin/src/lib.rs+++ b/apps/web/tauri/graphql_cache_plugin/src/lib.rs@@ -23,9 +23,10 @@ pub mod commands;mod engine;pub use engine::{- AffectedOperationsResultWire, ClaimedMutationWire, EngineHandle,- EnqueueOptimisticMutationResultWire, InitialMutationClaimWire, ReadResultWire,- RecordSelectionResultWire, WriteResultWire,+ AffectedOperationsResultWire, ClaimedMutationWire, CommitOptimisticWriteResultWire,+ DeferOptimisticWriteResultWire, EngineHandle, EnqueueOptimisticMutationResultWire,+ InitialMutationClaimWire, ReadResultWire, RecordSelectionResultWire,+ RollbackOptimisticWriteResultWire, WriteResultWire,};/// Broadcast event carrying [`OpsAffectedEvent`]: operations whose@@ -66,6 +67,8 @@ struct MutationSettledEvent {status: &'static str,#[serde(skip_serializing_if = "Option::is_none")]error: Option<String>,+ #[serde(skip_serializing_if = "Option::is_none")]+ replacement_transaction_id: Option<String>,}struct InitializedCache {@@ -112,8 +115,8 @@ fn emit_cache_changed<R: Runtime>(app: &AppHandle<R>, revision: &str) {revision: revision.to_owned(),},)- .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))- .ok();+ .inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql cache change event"))+ .ok();}fn emit_mutation_settled<R: Runtime>(@@ -121,6 +124,7 @@ fn emit_mutation_settled<R: Runtime>(transaction_id: String,status: &'static str,error: Option<String>,+ replacement_transaction_id: Option<String>,) {app.emit(MUTATION_SETTLED_EVENT,@@ -128,6 +132,7 @@ fn emit_mutation_settled<R: Runtime>(transaction_id,status,error,+ replacement_transaction_id,},).inspect_err(|e| tracing::error!(error=?e, "failed to emit graphql mutation settlement"))diff --git a/crates/client/cache-core/Cargo.toml b/crates/client/cache-core/Cargo.tomlindex 4fdf86cd26..7263e00d87 100644--- a/crates/client/cache-core/Cargo.toml+++ b/crates/client/cache-core/Cargo.toml@@ -15,6 +15,7 @@ serde = { workspace = true }serde_json = { workspace = true }sha2 = { workspace = true }thiserror = { workspace = true }+uuid = { workspace = true }[build-dependencies]apollo-compiler = { workspace = true }diff --git a/crates/client/cache-core/src/engine.rs b/crates/client/cache-core/src/engine.rsindex 2492113ed1..40e3e4e2b3 100644--- a/crates/client/cache-core/src/engine.rs+++ b/crates/client/cache-core/src/engine.rs@@ -21,10 +21,10 @@ use crate::normalize::{project_hydration_response,};use crate::predicate::{- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,- ProjectionMutation, ProjectionMutationLayer, ProjectionState,+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,+ PredicateQueryResult, ProjectionMutation, ProjectionMutationLayer, ProjectionState,+ StagedOptimisticProjection, StagedOptimisticProjectionOwner,apply_authoritative_projection_patch, compose_effective_optimistic_projection,- compose_pending_optimistic_projection,};use crate::query_inspection::{CachedQueryInstance, CachedQueryVariant, OwnerResolution, QueryInspection,@@ -32,9 +32,10 @@ use crate::query_inspection::{selected_result_value,};use crate::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,- NewQueuedMutation, OptimisticSource, PersistedOptimisticLayer, QueuedMutation, StoredMutation,- decode_optimistic_source, encode_optimistic_source,+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationQueueSnapshot,+ MutationRequest, MutationUpsertKind, NewQueuedMutation, OptimisticSource,+ PersistedOptimisticLayer, QueuedMutation, StoredMutation, decode_optimistic_source,+ encode_optimistic_source,};use crate::record_selection::{MAX_RECORD_SELECTION_KEYS, RecordSelection, RecordSelectionError, SelectedRecord,@@ -54,6 +55,7 @@ use serde_json::Value as Json;use std::collections::{BTreeMap, BTreeSet, HashMap};use std::num::NonZeroUsize;use thiserror::Error;+use uuid::Uuid;#[derive(Debug, Error)]pub enum EngineError<S: std::error::Error + 'static> {@@ -84,6 +86,10 @@ pub enum EngineError<S: std::error::Error + 'static> {},#[error("invalid optimistic projection: {0}")]InvalidOptimisticProjection(String),+ #[error("invalid optimistic mutation UUID `{0}`")]+ InvalidMutationUuid(String),+ #[error("durable optimistic queue changed while staging UUID upsert")]+ StaleOptimisticUpsert,#[error("storage: {0}")]Storage(#[source] S),#[error("cache revision overflow")]@@ -169,14 +175,54 @@ pub enum InitialClaimOutcome<E> {pub struct EnqueueOptimisticMutationResult<E> {/// Engine-assigned id of the newly enqueued optimistic mutation.pub transaction_id: OptimisticTransactionId,+ /// How the caller UUID changed the queue.+ pub upsert_kind: MutationUpsertKind,/// Visible cache changes caused by the newly published optimistic layer.pub write_result: WriteResult,/// Outcome of the claim attempt made before hosts publish cache changes.pub initial_claim: InitialClaimOutcome<E>,}+/// Cache change and replacement identity produced by settling superseded work.+#[derive(Debug)]+pub struct SupersededMutationResult {+ /// Cache changes caused by settling the superseded layer.+ pub write_result: WriteResult,+ /// Current transaction carrying the caller's newer intent.+ pub replacement_transaction_id: OptimisticTransactionId,+}++/// Tagged commit result used by transport adapters for settlement fanout.+#[derive(Debug)]+pub enum CommitOptimisticWriteResult {+ /// A current mutation committed normally.+ Committed(WriteResult),+ /// The response committed beneath a newer optimistic replacement.+ CommittedSuperseded(SupersededMutationResult),+}++/// Result of attempting to defer a failed queue attempt.+#[derive(Debug)]+pub enum DeferOptimisticWriteResult {+ /// The current mutation retained its optimistic layer and retry state.+ Deferred,+ /// The attempt was superseded, so it was discarded instead of retried.+ DiscardedSuperseded(SupersededMutationResult),+}++/// Tagged rollback result used by transport adapters for settlement fanout.+#[derive(Debug)]+pub enum RollbackOptimisticWriteResult {+ /// A current mutation permanently failed normally.+ RolledBack(WriteResult),+ /// A superseded attempt was accepted and discarded.+ DiscardedSuperseded(SupersededMutationResult),+}+/// Borrowed inputs for atomically beginning one optimistic mutation.pub struct BeginOptimisticWrite<'a> {+ /// Caller-supplied RFC UUID used only for safe coalescing.+ pub uuid: &'a str,/// GraphQL mutation document.pub query: &'a str,/// Selected operation name.@@ -204,12 +250,20 @@ pub type OptimisticTransactionId = MutationId;#[derive(Clone)]struct OptimisticLayer {id: OptimisticTransactionId,+ uuid: Uuid,+ superseded: bool,updates: RecordUpdates,link_patches: Vec<OptimisticLinkPatch>,revalidations: Vec<QueryRevalidation>,projection_mutations: Vec<OptimisticProjectionMutation>,}+struct BegunOptimisticWrite {+ transaction_id: OptimisticTransactionId,+ upsert_kind: MutationUpsertKind,+ write_result: WriteResult,+}+/// Reserved storage key holding the identity bound to this cache. The/// `__meta:` prefix can never collide with entity keys (typenames can't/// contain `:`).@@ -351,6 +405,15 @@ impl<S: Storage> Engine<S> {async fn rebuild_queued_layers(&mut self,queued: Vec<QueuedMutation>,+ ) -> Result<Vec<OptimisticLayer>, EngineError<S::Error>> {+ self.rebuild_queued_layers_with_strict_tail(queued, None)+ .await+ }++ async fn rebuild_queued_layers_with_strict_tail(+ &mut self,+ queued: Vec<QueuedMutation>,+ strict_tail: Option<MutationId>,) -> Result<Vec<OptimisticLayer>, EngineError<S::Error>> {let mut layers = Vec::with_capacity(queued.len());for queued in queued {@@ -388,8 +451,14 @@ impl<S: Storage> Engine<S> {let mut effective = present_records(composed);merge_updates_into_effective(&mut effective, &updates);// Missing query fields after a format wipe are intentionally not- // recreated from stale recipes during hydration.- apply_link_patches(&mut effective, &mut updates, &patches, true)?;+ // recreated from stale recipes during hydration. A newly submitted+ // tail remains strict so invalid caller patches cannot be persisted.+ apply_link_patches(+ &mut effective,+ &mut updates,+ &patches,+ strict_tail != Some(queued.id),+ )?;let revalidations = deduplicate_revalidations(source.revalidations.iter().cloned().chain(source@@ -400,6 +469,8 @@ impl<S: Storage> Engine<S> {);layers.push(OptimisticLayer {id: queued.id,+ uuid: queued.uuid,+ superseded: queued.superseded,updates,link_patches: patches,revalidations,@@ -1228,8 +1299,23 @@ impl<S: Storage> Engine<S> {input: BeginOptimisticWrite<'_>,projection_mutations: Vec<OptimisticProjectionMutation>,) -> Result<(OptimisticTransactionId, WriteResult), EngineError<S::Error>> {+ let begun = self+ .upsert_optimistic_write(origin_op, input, projection_mutations)+ .await?;+ Ok((begun.transaction_id, begun.write_result))+ }++ async fn upsert_optimistic_write(+ &mut self,+ origin_op: Option<OpId>,+ input: BeginOptimisticWrite<'_>,+ projection_mutations: Vec<OptimisticProjectionMutation>,+ ) -> Result<BegunOptimisticWrite, EngineError<S::Error>> {+ let uuid = Uuid::parse_str(input.uuid)+ .map_err(|_| EngineError::InvalidMutationUuid(input.uuid.to_owned()))?;self.ensure_revision_can_advance()?;let BeginOptimisticWrite {+ uuid: _,query,operation_name,variables,@@ -1239,9 +1325,35 @@ impl<S: Storage> Engine<S> {created_at_ms,} = input;self.hydrate_optimistic().await?;- let doc = Self::document(&mut self.docs, query)?;- let op = doc.operation(operation_name)?;- let mut updates = normalize(op, variables, data)?;++ let queued = self+ .storage+ .load_mutation_queue()+ .await+ .map_err(EngineError::Storage)?;+ let expected_queue = queued+ .iter()+ .map(MutationQueueSnapshot::from)+ .collect::<Vec<_>>();+ let old_layers = self.rebuild_queued_layers(queued.clone()).await?;+ let collision = queued+ .iter()+ .find(|queued| queued.uuid == uuid && !queued.superseded)+ .map(|queued| {+ (+ queued.id,+ queued+ .mutation+ .lease_expires_at_ms+ .is_some_and(|expiry| expiry > created_at_ms),+ )+ });+ let expected_kind = match collision {+ None => MutationUpsertKind::Inserted,+ Some((active_id, true)) => MutationUpsertKind::AppendedAfterActive { active_id },+ Some((removed_id, false)) => MutationUpsertKind::ReplacedPending { removed_id },+ };+let patches = deduplicate_patches(link_patches)?;let revalidations = deduplicate_revalidations(revalidations@@ -1249,127 +1361,165 @@ impl<S: Storage> Engine<S> {.cloned().chain(patches.iter().map(OptimisticLinkPatch::revalidation)),);-- let candidates: BTreeSet<EntityKey<'static>> = updates.keys().cloned().collect();- let optimistic = self.optimistic.clone();- let (candidates, bases) = self- .load_link_patch_bases(candidates, &optimistic, &updates, &patches)- .await?;- let before = effective_records(&bases, &self.optimistic, &candidates);- let mut effective = present_records(before.clone());- merge_updates_into_effective(&mut effective, &updates);- // This stages on clones internally, so no part of an invalid patch- // set can become visible or durable.- apply_link_patches(&mut effective, &mut updates, &patches, false)?;-- let identity = match self.bound_identity().await? {- IdentityState::Bound(identity) => Some(identity),- IdentityState::NotHydrated | IdentityState::Missing => None,- };for mutation in &projection_mutations {mutation.validate().map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?;}- let shadow_replacements = if projection_mutations.is_empty() {- Vec::new()- } else {- let keys = projection_mutations- .iter()- .map(|mutation| mutation.record_key().clone())- .collect::<BTreeSet<_>>()- .into_iter()- .collect::<Vec<_>>();- let authoritative = self- .storage- .load_projection_states(&keys)- .await- .map_err(EngineError::Storage)?;- let current = self- .storage- .load_optimistic_projections(&keys)- .await- .map_err(EngineError::Storage)?;- if authoritative.len() != keys.len() || current.len() != keys.len() {- return Err(EngineError::InvalidOptimisticProjection(- "storage returned misaligned optimistic projection bases".to_owned(),- ));- }- keys.iter()- .zip(authoritative.iter())- .zip(current.iter())- .map(|((key, authoritative), current)| {- compose_pending_optimistic_projection(- key,- authoritative.as_ref(),- current.as_ref(),- &projection_mutations,- )- .map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?- .ok_or_else(|| {- EngineError::InvalidOptimisticProjection(- "touched optimistic projection key was not composed".to_owned(),- )- })- })- .collect::<Result<Vec<_>, _>>()?+ let identity = match self.bound_identity().await? {+ IdentityState::Bound(identity) => Some(identity),+ IdentityState::NotHydrated | IdentityState::Missing => None,};let source = OptimisticSource {mutation_data: data.clone(),- link_patches: patches.clone(),- revalidations: revalidations.clone(),- projection_mutations: projection_mutations.clone(),+ link_patches: patches,+ revalidations,+ projection_mutations,+ };+ let mut entry = NewQueuedMutation {+ uuid,+ 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: encode_optimistic_source(&source),+ normalized_updates: RecordUpdates::default(),+ },};- let id = self++ let mut proposed_queue = queued.clone();+ match expected_kind {+ MutationUpsertKind::Inserted => {}+ MutationUpsertKind::ReplacedPending { removed_id } => {+ proposed_queue.retain(|queued| queued.id != removed_id);+ }+ MutationUpsertKind::AppendedAfterActive { active_id } => {+ proposed_queue+ .iter_mut()+ .find(|queued| queued.id == active_id)+ .expect("collision was loaded")+ .superseded = true;+ }+ }+ proposed_queue.push(QueuedMutation {+ id: MutationId::MAX,+ uuid,+ superseded: false,+ mutation: entry.mutation.clone(),+ optimistic: entry.optimistic.clone(),+ });+ let mut proposed_layers = self+ .rebuild_queued_layers_with_strict_tail(proposed_queue, Some(MutationId::MAX))+ .await?;+ entry.optimistic.normalized_updates = proposed_layers+ .last()+ .expect("proposed queue contains the new tail")+ .updates+ .clone();++ let mut candidates = layer_keys(&old_layers);+ candidates.extend(layer_keys(&proposed_layers));+ let bases = self.load_bases(&candidates).await?;+ let before = effective_records(&bases, &old_layers, &candidates);+ let after = effective_records(&bases, &proposed_layers, &candidates);++ let affected_projection_keys = old_layers+ .iter()+ .chain(&proposed_layers)+ .flat_map(|layer| &layer.projection_mutations)+ .map(|mutation| mutation.record_key().clone())+ .collect::<BTreeSet<_>>()+ .into_iter()+ .collect::<Vec<_>>();+ let authoritative = self.storage- .enqueue_mutation_with_shadow(- 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: encode_optimistic_source(&source),- normalized_updates: updates.clone(),- },+ .load_projection_states(&affected_projection_keys)+ .await+ .map_err(EngineError::Storage)?;+ if authoritative.len() != affected_projection_keys.len() {+ return Err(EngineError::InvalidOptimisticProjection(+ "storage returned misaligned authoritative projection states".to_owned(),+ ));+ }+ let projection_layers = proposed_layers+ .iter()+ .map(|layer| ProjectionMutationLayer {+ owner: layer.id,+ mutations: &layer.projection_mutations,+ })+ .collect::<Vec<_>>();+ let replacements = affected_projection_keys+ .iter()+ .zip(authoritative.iter())+ .filter_map(|(key, authoritative)| {+ compose_effective_optimistic_projection(+ key,+ authoritative.as_ref(),+ &projection_layers,+ )+ .transpose()+ })+ .collect::<Result<Vec<_>, _>>()+ .map_err(|error| EngineError::InvalidOptimisticProjection(error.to_string()))?+ .into_iter()+ .map(|projection| StagedOptimisticProjection {+ owner: if projection.owner == MutationId::MAX {+ StagedOptimisticProjectionOwner::Enqueued+ } else {+ StagedOptimisticProjectionOwner::Existing(projection.owner)+ },+ state: projection.state,+ uncertainty: projection.uncertainty,+ })+ .collect();+ let upsert = self+ .storage+ .upsert_mutation_with_shadow(+ entry,+ created_at_ms,+ OptimisticUpsertReconciliation {+ expected_queue: Some(expected_queue),+ affected_keys: affected_projection_keys,+ replacements,},- shadow_replacements,).await.map_err(EngineError::Storage)?;- self.optimistic.push(OptimisticLayer {- id,- updates,- link_patches: patches,- revalidations,- projection_mutations,- });+ if upsert.kind != expected_kind {+ return Err(EngineError::StaleOptimisticUpsert);+ }+ proposed_layers+ .last_mut()+ .expect("proposed queue contains the new tail")+ .id = upsert.id;+ self.optimistic = proposed_layers;- let after = effective_records(&bases, &self.optimistic, &candidates);- let changed: BTreeSet<EntityKey<'static>> = candidates+ let changed = candidates.into_iter().filter(|key| before.get(key) != after.get(key))- .collect();+ .collect::<BTreeSet<_>>();let mut affected_ops = self.deps.ops_for_keys(changed.iter());if let Some(origin) = origin_op {affected_ops.remove(&origin);}let revision = self.advance_revision()?;- Ok((- id,- WriteResult {+ Ok(BegunOptimisticWrite {+ transaction_id: upsert.id,+ upsert_kind: upsert.kind,+ write_result: WriteResult {revision,changed,affected_ops,reset: false,revalidations: Vec::new(),},- ))+ })}/// Durably enqueues a mutation and publishes its optimistic layer, then@@ -1394,8 +1544,8 @@ impl<S: Storage> Engine<S> {claim: MutationClaimRequest,projection_mutations: Vec<OptimisticProjectionMutation>,) -> Result<EnqueueOptimisticMutationResult<EngineError<S::Error>>, EngineError<S::Error>> {- let (transaction_id, write_result) = self- .begin_optimistic_write_with_projections(origin_op, input, projection_mutations)+ let begun = self+ .upsert_optimistic_write(origin_op, input, projection_mutations).await?;let initial_claim = match self.claim_next_mutation(claim).await {Ok(Some(claimed)) => InitialClaimOutcome::Claimed(Box::new(claimed)),@@ -1403,8 +1553,9 @@ impl<S: Storage> Engine<S> {Err(error) => InitialClaimOutcome::Failed(error),};Ok(EnqueueOptimisticMutationResult {- transaction_id,- write_result,+ transaction_id: begun.transaction_id,+ upsert_kind: begun.upsert_kind,+ write_result: begun.write_result,initial_claim,})}@@ -1422,15 +1573,35 @@ impl<S: Storage> Engine<S> {.map_err(EngineError::Storage)}- /// Releases a retryable mutation while retaining its optimistic layer.+ /// Releases a retryable mutation, or discards it when a newer UUID match exists.pub async fn defer_optimistic_write(&mut self,transaction: OptimisticTransactionId,claim: MutationClaimToken,next_attempt_at_ms: i64,error: String,- ) -> Result<(), EngineError<S::Error>> {+ ) -> Result<DeferOptimisticWriteResult, EngineError<S::Error>> {self.hydrate_optimistic().await?;+ let layer = self+ .optimistic+ .iter()+ .find(|layer| layer.id == transaction)+ .ok_or(EngineError::UnknownTransaction(transaction))?;+ if layer.superseded {+ let replacement_transaction_id = self+ .optimistic+ .iter()+ .find(|candidate| candidate.uuid == layer.uuid && !candidate.superseded)+ .map(|candidate| candidate.id)+ .ok_or(EngineError::UnknownTransaction(transaction))?;+ let write_result = self.rollback_optimistic_write(transaction, claim).await?;+ return Ok(DeferOptimisticWriteResult::DiscardedSuperseded(+ SupersededMutationResult {+ write_result,+ replacement_transaction_id,+ },+ ));+ }if !self.storage.defer_mutation(transaction, claim, next_attempt_at_ms, error)@@ -1439,7 +1610,7 @@ impl<S: Storage> Engine<S> {{return Err(EngineError::StaleMutationClaim(transaction));}- Ok(())+ Ok(DeferOptimisticWriteResult::Deferred)}async fn stage_shadow_reconciliation(@@ -1596,6 +1767,80 @@ impl<S: Storage> Engine<S> {.await}+ /// Commits an optimistic write and reports whether a newer UUID match superseded it.+ #[allow(clippy::too_many_arguments)]+ pub async fn commit_optimistic_write_with_outcome(+ &mut self,+ transaction: OptimisticTransactionId,+ claim: MutationClaimToken,+ query: &str,+ operation_name: Option<&str>,+ variables: &serde_json::Map<String, Json>,+ data: &Json,+ ) -> Result<CommitOptimisticWriteResult, EngineError<S::Error>> {+ self.commit_optimistic_write_with_projections_outcome(+ transaction,+ claim,+ query,+ operation_name,+ variables,+ data,+ Vec::new(),+ )+ .await+ }++ /// Commits an optimistic write with projections and reports supersession.+ #[allow(clippy::too_many_arguments)]+ pub async fn commit_optimistic_write_with_projections_outcome(+ &mut self,+ transaction: OptimisticTransactionId,+ claim: MutationClaimToken,+ query: &str,+ operation_name: Option<&str>,+ variables: &serde_json::Map<String, Json>,+ data: &Json,+ projections: Vec<ProjectionMutation>,+ ) -> Result<CommitOptimisticWriteResult, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;+ let layer = self+ .optimistic+ .iter()+ .find(|layer| layer.id == transaction)+ .ok_or(EngineError::UnknownTransaction(transaction))?;+ let replacement_transaction_id = if layer.superseded {+ Some(+ self.optimistic+ .iter()+ .find(|candidate| candidate.uuid == layer.uuid && !candidate.superseded)+ .map(|candidate| candidate.id)+ .ok_or(EngineError::UnknownTransaction(transaction))?,+ )+ } else {+ None+ };+ let write_result = self+ .commit_optimistic_write_with_projections(+ transaction,+ claim,+ query,+ operation_name,+ variables,+ data,+ projections,+ )+ .await?;+ match replacement_transaction_id {+ Some(replacement_transaction_id) => Ok(+ CommitOptimisticWriteResult::CommittedSuperseded(SupersededMutationResult {+ write_result,+ replacement_transaction_id,+ }),+ ),+ None => Ok(CommitOptimisticWriteResult::Committed(write_result)),+ }+ }+/// Settles an optimistic write with atomic generic projection replacement.#[allow(clippy::too_many_arguments)]pub async fn commit_optimistic_write_with_projections(@@ -1685,6 +1930,41 @@ impl<S: Storage> Engine<S> {})}+ /// Permanently fails the claimed head with an explicit supersession outcome.+ pub async fn rollback_optimistic_write_with_outcome(+ &mut self,+ transaction: OptimisticTransactionId,+ claim: MutationClaimToken,+ ) -> Result<RollbackOptimisticWriteResult, EngineError<S::Error>> {+ self.hydrate_optimistic().await?;+ let layer = self+ .optimistic+ .iter()+ .find(|layer| layer.id == transaction)+ .ok_or(EngineError::UnknownTransaction(transaction))?;+ let replacement_transaction_id = if layer.superseded {+ Some(+ self.optimistic+ .iter()+ .find(|candidate| candidate.uuid == layer.uuid && !candidate.superseded)+ .map(|candidate| candidate.id)+ .ok_or(EngineError::UnknownTransaction(transaction))?,+ )+ } else {+ None+ };+ let write_result = self.rollback_optimistic_write(transaction, claim).await?;+ match replacement_transaction_id {+ Some(replacement_transaction_id) => Ok(+ RollbackOptimisticWriteResult::DiscardedSuperseded(SupersededMutationResult {+ write_result,+ replacement_transaction_id,+ }),+ ),+ None => Ok(RollbackOptimisticWriteResult::RolledBack(write_result)),+ }+ }+/// Permanently fails the claimed head, atomically removing its queue row/// and optimistic layer.pub async fn rollback_optimistic_write(diff --git a/crates/client/cache-core/src/predicate.rs b/crates/client/cache-core/src/predicate.rsindex cfff39d968..b0af321309 100644--- a/crates/client/cache-core/src/predicate.rs+++ b/crates/client/cache-core/src/predicate.rs@@ -1,6 +1,10 @@//! Generic predicate-projection lifecycle and exact-query storage port.-use crate::{store::Storage, value::EntityKey};+use crate::{+ queue::{MutationId, MutationQueueSnapshot},+ store::Storage,+ value::EntityKey,+};use maybe_send::MaybeSend;pub use predicate_index::ProjectionIncompleteKind;use predicate_index::{@@ -82,6 +86,81 @@ pub enum ProjectionCompositionError {InvalidReconciliation,}+/// Owner of a projection shadow staged before storage assigns the new queue id.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum StagedOptimisticProjectionOwner {+ /// An existing durable mutation remains the final owner.+ Existing(MutationId),+ /// The newly inserted tail mutation is the final owner.+ Enqueued,+}++/// Effective projection shadow staged for a UUID-aware queue upsert.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct StagedOptimisticProjection {+ /// Existing or transaction-local final owner.+ pub owner: StagedOptimisticProjectionOwner,+ /// Effective optimistic state.+ pub state: OptimisticProjectionState,+ /// Attributes whose effective value remains uncertain.+ pub uncertainty: OptimisticUncertainty,+}++/// Atomic optimistic-shadow replacement staged against exact queue lifecycle state.+#[derive(Debug, Clone, PartialEq, Eq, Default)]+pub struct OptimisticUpsertReconciliation {+ /// Exact queue state observed while rebuilding optimistic layers. `None`+ /// is reserved for direct storage callers that do not stage shadows.+ pub expected_queue: Option<Vec<MutationQueueSnapshot>>,+ /// Keys to remove or replace, in deterministic key order.+ pub affected_keys: Vec<RecordKey>,+ /// Effective replacements for keys still touched by proposed layers.+ pub replacements: Vec<StagedOptimisticProjection>,+}++impl OptimisticUpsertReconciliation {+ /// Validates deterministic keys, replacement ownership, and projection bounds.+ pub fn validate(&self) -> Result<(), ProjectionCompositionError> {+ if self.affected_keys.windows(2).any(|keys| keys[0] >= keys[1]) {+ return Err(ProjectionCompositionError::InvalidReconciliation);+ }+ if let Some(queue) = &self.expected_queue+ && (queue.iter().any(|row| row.id == 0)+ || queue.windows(2).any(|rows| rows[0].id >= rows[1].id))+ {+ return Err(ProjectionCompositionError::LayerOrder);+ }+ let existing = self+ .expected_queue+ .iter()+ .flatten()+ .map(|row| row.id)+ .collect::<BTreeSet<_>>();+ let affected = self.affected_keys.iter().collect::<BTreeSet<_>>();+ let mut replacement_keys = BTreeSet::new();+ for replacement in &self.replacements {+ let projection = EffectiveOptimisticProjection {+ owner: match replacement.owner {+ StagedOptimisticProjectionOwner::Existing(owner) => owner,+ StagedOptimisticProjectionOwner::Enqueued => u64::MAX,+ },+ state: replacement.state.clone(),+ uncertainty: replacement.uncertainty.clone(),+ };+ projection.validate()?;+ if matches!(+ replacement.owner,+ StagedOptimisticProjectionOwner::Existing(owner) if !existing.contains(&owner)+ ) || !affected.contains(replacement.state.record_key())+ || !replacement_keys.insert(replacement.state.record_key())+ {+ return Err(ProjectionCompositionError::InvalidReconciliation);+ }+ }+ Ok(())+ }+}+/// Atomic shadow replacement staged against one exact durable queue identity.#[derive(Debug, Clone, PartialEq, Eq)]pub struct OptimisticShadowReconciliation {diff --git a/crates/client/cache-core/src/queue.rs b/crates/client/cache-core/src/queue.rsindex 6215deb501..7e691e87a2 100644--- a/crates/client/cache-core/src/queue.rs+++ b/crates/client/cache-core/src/queue.rs@@ -11,6 +11,7 @@ use crate::value::canonical_json;use predicate_index::OptimisticProjectionMutation;use serde::{Deserialize, Serialize};use serde_json::Value as Json;+use uuid::Uuid;/// Durable, monotonically increasing mutation identifier and queue position.pub type MutationId = u64;@@ -180,6 +181,8 @@ pub struct PersistedOptimisticLayer {/// A mutation and optimistic layer before storage assigns its queue id.#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]pub struct NewQueuedMutation {+ /// Caller-supplied coalescing key.+ pub uuid: Uuid,/// Mutation request plus initial retry metadata.pub mutation: StoredMutation,/// Optimistic contribution paired with the mutation.@@ -191,12 +194,75 @@ pub struct NewQueuedMutation {pub struct QueuedMutation {/// Durable queue id and ordering key.pub id: MutationId,+ /// Caller-supplied coalescing key.+ pub uuid: Uuid,+ /// Whether a newer mutation superseded this still-active row.+ pub superseded: bool,/// Mutation request and retry metadata.pub mutation: StoredMutation,/// Optimistic contribution paired with the mutation.pub optimistic: PersistedOptimisticLayer,}+/// Queue and lifecycle state used to fence a staged UUID upsert.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct MutationQueueSnapshot {+ /// Durable queue id.+ pub id: MutationId,+ /// Caller coalescing key.+ pub uuid: Uuid,+ /// Whether this row has been superseded.+ pub superseded: bool,+ /// Current lease owner.+ pub lease_owner: Option<String>,+ /// Current lease generation.+ pub lease_generation: u64,+ /// Current lease expiry.+ pub lease_expires_at_ms: Option<i64>,+ /// Current retry eligibility time.+ pub next_attempt_at_ms: Option<i64>,+}++impl From<&QueuedMutation> for MutationQueueSnapshot {+ fn from(queued: &QueuedMutation) -> Self {+ Self {+ id: queued.id,+ uuid: queued.uuid,+ superseded: queued.superseded,+ lease_owner: queued.mutation.lease_owner.clone(),+ lease_generation: queued.mutation.lease_generation,+ lease_expires_at_ms: queued.mutation.lease_expires_at_ms,+ next_attempt_at_ms: queued.mutation.next_attempt_at_ms,+ }+ }+}++/// How a UUID-aware enqueue changed the existing queue.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+pub enum MutationUpsertKind {+ /// No current row used this UUID.+ Inserted,+ /// A non-active current row was removed.+ ReplacedPending {+ /// Transaction removed by the replacement.+ removed_id: MutationId,+ },+ /// A live row was retained and marked superseded.+ AppendedAfterActive {+ /// Still-active transaction retained ahead of the replacement.+ active_id: MutationId,+ },+}++/// Result of atomically inserting or replacing a queued mutation.+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]+pub struct MutationUpsertResult {+ /// Fresh queue id assigned to the inserted tail row.+ pub id: MutationId,+ /// Queue collision outcome.+ pub kind: MutationUpsertKind,+}+/// Successful claim of the oldest runnable mutation.#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]pub struct ClaimedMutation {diff --git a/crates/client/cache-core/src/store.rs b/crates/client/cache-core/src/store.rsindex 4e0861513c..86db233f01 100644--- a/crates/client/cache-core/src/store.rs+++ b/crates/client/cache-core/src/store.rs@@ -7,12 +7,13 @@//! `Send`.use crate::predicate::{- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,- ProjectionMutation, ProjectionState, apply_authoritative_projection_patch,+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,+ PredicateQueryResult, ProjectionMutation, ProjectionState, StagedOptimisticProjection,+ StagedOptimisticProjectionOwner, apply_authoritative_projection_patch,};use crate::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,- QueuedMutation,+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationQueueSnapshot,+ MutationUpsertKind, MutationUpsertResult, NewQueuedMutation, QueuedMutation,};use crate::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};use crate::value::{EntityKey, Record};@@ -97,24 +98,68 @@ pub trait Storage: MaybeSend {async { Ok(Vec::new()) }}- /// Atomically appends a mutation and its optimistic layer to the queue.+ /// Atomically inserts or replaces a mutation by its caller UUID.fn enqueue_mutation(&mut self,entry: NewQueuedMutation,) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend {- self.enqueue_mutation_with_shadow(entry, Vec::new())+ let now_ms = entry.mutation.created_at_ms;+ async move {+ self.upsert_mutation_with_shadow(+ entry,+ now_ms,+ OptimisticUpsertReconciliation::default(),+ )+ .await+ .map(|result| result.id)+ }}- /// Atomically appends a mutation, its layer, and effective shadow replacements.- ///- /// Storage binds every pending projection to the mutation ID assigned in- /// this transaction. Existing shadows for the pending record keys are- /// replaced; all other shadows remain byte-for-byte unchanged.+ /// Convenience upsert that assigns all supplied shadows to the new tail row.fn enqueue_mutation_with_shadow(&mut self,entry: NewQueuedMutation,projections: Vec<PendingOptimisticProjection>,- ) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend;+ ) -> impl Future<Output = Result<MutationId, Self::Error>> + MaybeSend {+ let now_ms = entry.mutation.created_at_ms;+ let mut affected_keys = projections+ .iter()+ .map(|projection| projection.state.record_key().clone())+ .collect::<Vec<_>>();+ affected_keys.sort();+ let mut replacements = projections+ .into_iter()+ .map(|projection| StagedOptimisticProjection {+ owner: StagedOptimisticProjectionOwner::Enqueued,+ state: projection.state,+ uncertainty: projection.uncertainty,+ })+ .collect::<Vec<_>>();+ replacements.sort_by(|left, right| left.state.record_key().cmp(right.state.record_key()));+ let reconciliation = OptimisticUpsertReconciliation {+ expected_queue: None,+ affected_keys,+ replacements,+ };+ async move {+ self.upsert_mutation_with_shadow(entry, now_ms, reconciliation)+ .await+ .map(|result| result.id)+ }+ }++ /// Atomically inserts or replaces a mutation, its layer, and effective shadows.+ ///+ /// A live UUID collision retains and supersedes the old row. Any other+ /// collision removes the old row. Storage resolves `Enqueued` projection+ /// owners to the fresh ID assigned inside the same transaction and rejects+ /// an expected queue snapshot that no longer matches.+ fn upsert_mutation_with_shadow(+ &mut self,+ entry: NewQueuedMutation,+ now_ms: i64,+ reconciliation: OptimisticUpsertReconciliation,+ ) -> impl Future<Output = Result<MutationUpsertResult, Self::Error>> + MaybeSend;/// Loads authoritative projection states aligned with `keys`.fn load_projection_states(@@ -229,19 +274,21 @@ pub struct InMemoryStorage {search_documents: HashMap<(SearchProfile, EntityKey<'static>), SearchDocument>,projections: HashMap<PredicateRecordKey, ProjectionState>,optimistic_projections: HashMap<PredicateRecordKey, EffectiveOptimisticProjection>,- mutations: BTreeMap<- MutationId,- (- crate::queue::StoredMutation,- crate::queue::PersistedOptimisticLayer,- ),- >,+ mutations: BTreeMap<MutationId, InMemoryQueuedMutation>,next_mutation_id: MutationId,record_get_count: Arc<AtomicUsize>,search_catalog_load_count: Arc<AtomicUsize>,mutation_queue_load_count: Arc<AtomicUsize>,}+#[derive(Clone, Debug)]+struct InMemoryQueuedMutation {+ uuid: uuid::Uuid,+ superseded: bool,+ mutation: crate::queue::StoredMutation,+ optimistic: crate::queue::PersistedOptimisticLayer,+}+impl InMemoryStorage {pub fn new() -> Self {Self::default()@@ -357,27 +404,88 @@ impl Storage for InMemoryStorage {Ok(documents)}- async fn enqueue_mutation_with_shadow(+ async fn upsert_mutation_with_shadow(&mut self,entry: NewQueuedMutation,- projections: Vec<PendingOptimisticProjection>,- ) -> Result<MutationId, Self::Error> {+ now_ms: i64,+ reconciliation: OptimisticUpsertReconciliation,+ ) -> Result<MutationUpsertResult, Self::Error> {+ debug_assert!(reconciliation.validate().is_ok());+ if let Some(expected) = &reconciliation.expected_queue {+ let actual = self+ .mutations+ .iter()+ .map(|(id, queued)| MutationQueueSnapshot {+ id: *id,+ uuid: queued.uuid,+ superseded: queued.superseded,+ lease_owner: queued.mutation.lease_owner.clone(),+ lease_generation: queued.mutation.lease_generation,+ lease_expires_at_ms: queued.mutation.lease_expires_at_ms,+ next_attempt_at_ms: queued.mutation.next_attempt_at_ms,+ })+ .collect::<Vec<_>>();+ assert_eq!(&actual, expected, "stale in-memory mutation upsert plan");+ }++ let collision = self+ .mutations+ .iter()+ .find(|(_, queued)| queued.uuid == entry.uuid && !queued.superseded)+ .map(|(id, queued)| {+ (+ *id,+ queued+ .mutation+ .lease_expires_at_ms+ .is_some_and(|expiry| expiry > now_ms),+ )+ });+ let kind = match collision {+ None => MutationUpsertKind::Inserted,+ Some((id, true)) => {+ self.mutations+ .get_mut(&id)+ .expect("collision exists")+ .superseded = true;+ MutationUpsertKind::AppendedAfterActive { active_id: id }+ }+ Some((id, false)) => {+ self.mutations.remove(&id);+ MutationUpsertKind::ReplacedPending { removed_id: id }+ }+ };+self.next_mutation_id += 1;let id = self.next_mutation_id;- self.mutations- .insert(id, (entry.mutation, entry.optimistic));- for projection in projections {- let record_key = projection.state.record_key().clone();+ self.mutations.insert(+ id,+ InMemoryQueuedMutation {+ uuid: entry.uuid,+ superseded: false,+ mutation: entry.mutation,+ optimistic: entry.optimistic,+ },+ );+ for key in reconciliation.affected_keys {+ self.optimistic_projections.remove(&key);+ }+ for replacement in reconciliation.replacements {+ let owner = match replacement.owner {+ StagedOptimisticProjectionOwner::Existing(owner) => owner,+ StagedOptimisticProjectionOwner::Enqueued => id,+ };+ debug_assert!(self.mutations.contains_key(&owner));self.optimistic_projections.insert(- record_key,+ replacement.state.record_key().clone(),EffectiveOptimisticProjection {- owner: id,- state: projection.state,- uncertainty: projection.uncertainty,+ owner,+ state: replacement.state,+ uncertainty: replacement.uncertainty,},);}- Ok(id)+ Ok(MutationUpsertResult { id, kind })}async fn load_projection_states(@@ -406,10 +514,12 @@ impl Storage for InMemoryStorage {Ok(self.mutations.iter()- .map(|(id, (mutation, optimistic))| QueuedMutation {+ .map(|(id, queued)| QueuedMutation {id: *id,- mutation: mutation.clone(),- optimistic: optimistic.clone(),+ uuid: queued.uuid,+ superseded: queued.superseded,+ mutation: queued.mutation.clone(),+ optimistic: queued.optimistic.clone(),}).collect())}@@ -421,7 +531,7 @@ impl Storage for InMemoryStorage {oldest_created_at_ms: self.mutations.values()- .map(|(mutation, _)| mutation.created_at_ms)+ .map(|queued| queued.mutation.created_at_ms).min(),})}@@ -430,9 +540,10 @@ impl Storage for InMemoryStorage {&mut self,request: MutationClaimRequest,) -> Result<Option<ClaimedMutation>, Self::Error> {- let Some((&id, (mutation, optimistic))) = self.mutations.iter_mut().next() else {+ let Some((&id, queued)) = self.mutations.iter_mut().next() else {return Ok(None);};+ let mutation = &mut queued.mutation;if mutation.next_attempt_at_ms.is_some_and(|next| next > request.now_ms)@@ -452,8 +563,10 @@ impl Storage for InMemoryStorage {Ok(Some(ClaimedMutation {queued: QueuedMutation {id,+ uuid: queued.uuid,+ superseded: queued.superseded,mutation: mutation.clone(),- optimistic: optimistic.clone(),+ optimistic: queued.optimistic.clone(),},lease_generation: generation,}))@@ -466,12 +579,13 @@ impl Storage for InMemoryStorage {next_attempt_at_ms: i64,error: String,) -> Result<bool, Self::Error> {- let Some((mutation, _)) = self.mutations.get_mut(&id) else {+ let Some(queued) = self.mutations.get_mut(&id) else {return Ok(false);};- if !claim_matches(mutation, &claim) {+ if !claim_matches(&queued.mutation, &claim) {return Ok(false);}+ let mutation = &mut queued.mutation;mutation.next_attempt_at_ms = Some(next_attempt_at_ms);mutation.last_error = Some(error);mutation.lease_owner = None;@@ -496,10 +610,10 @@ impl Storage for InMemoryStorage {entries: Vec<(EntityKey<'static>, Record)>,projections: Vec<ProjectionMutation>,) -> Result<bool, Self::Error> {- let Some((mutation, _)) = self.mutations.get(&id) else {+ let Some(queued) = self.mutations.get(&id) else {return Ok(false);};- if !claim_matches(mutation, &claim) {+ if !claim_matches(&queued.mutation, &claim) {return Ok(false);}for (key, record) in entries {@@ -531,10 +645,10 @@ impl Storage for InMemoryStorage {{return Ok(false);}- let Some((mutation, _)) = self.mutations.get(&id) else {+ let Some(queued) = self.mutations.get(&id) else {return Ok(false);};- if !claim_matches(mutation, &claim) {+ if !claim_matches(&queued.mutation, &claim) {return Ok(false);}for replacement in &reconciliation.replacements {@@ -568,10 +682,10 @@ impl Storage for InMemoryStorage {id: MutationId,claim: MutationClaimToken,) -> Result<bool, Self::Error> {- let Some((mutation, _)) = self.mutations.get(&id) else {+ let Some(queued) = self.mutations.get(&id) else {return Ok(false);};- if !claim_matches(mutation, &claim) {+ if !claim_matches(&queued.mutation, &claim) {return Ok(false);}self.mutations.remove(&id);@@ -591,10 +705,10 @@ impl Storage for InMemoryStorage {{return Ok(false);}- let Some((mutation, _)) = self.mutations.get(&id) else {+ let Some(queued) = self.mutations.get(&id) else {return Ok(false);};- if !claim_matches(mutation, &claim) {+ if !claim_matches(&queued.mutation, &claim) {return Ok(false);}for replacement in &reconciliation.replacements {diff --git a/crates/client/cache-core/tests/grouped_optimistic.rs b/crates/client/cache-core/tests/grouped_optimistic.rsindex f0b275fb23..cee2dee756 100644--- a/crates/client/cache-core/tests/grouped_optimistic.rs+++ b/crates/client/cache-core/tests/grouped_optimistic.rs@@ -293,6 +293,7 @@ fn cache_only_read_observes_move_and_rollback_restores_it() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000021",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_variables("completed"),@@ -376,6 +377,7 @@ fn success_reapplies_recipe_and_returns_deduplicated_revalidation() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000022",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_variables("completed"),@@ -455,6 +457,7 @@ fn missing_destination_is_created_with_the_updated_item() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000023",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_variables("completed"),@@ -532,6 +535,7 @@ fn missing_destination_rejects_the_whole_patch_set_without_enqueueing() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000024",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_variables("completed"),diff --git a/crates/client/cache-core/tests/mutation_queue.rs b/crates/client/cache-core/tests/mutation_queue.rsindex ea273da7b2..5d74513ab1 100644--- a/crates/client/cache-core/tests/mutation_queue.rs+++ b/crates/client/cache-core/tests/mutation_queue.rs@@ -1,6 +1,8 @@+use cache_core::predicate::OptimisticUpsertReconciliation;use cache_core::queue::{- MutationClaimRequest, MutationClaimToken, MutationRequest, NewQueuedMutation, OptimisticSource,- PersistedOptimisticLayer, StoredMutation, decode_optimistic_source, encode_optimistic_source,+ MutationClaimRequest, MutationClaimToken, MutationRequest, MutationUpsertKind,+ NewQueuedMutation, OptimisticSource, PersistedOptimisticLayer, StoredMutation,+ decode_optimistic_source, encode_optimistic_source,};use cache_core::store::{InMemoryStorage, Storage};use cache_core::value::{CacheValue, EntityKey, Record};@@ -89,6 +91,7 @@ fn queued(value: &str, created_at_ms: i64) -> NewQueuedMutation {.fields.insert("name".into(), CacheValue::String(value.into()));NewQueuedMutation {+ uuid: uuid::Uuid::new_v5(&uuid::Uuid::NAMESPACE_OID, value.as_bytes()),mutation: StoredMutation::new(MutationRequest {query: "mutation Rename { rename { id } }".into(),@@ -163,6 +166,61 @@ fn queue_diagnostics_are_payload_free_and_track_oldest() {});}+#[test]+fn storage_upsert_reports_pending_and_active_uuid_collisions() {+ block_on(async {+ let mut storage = InMemoryStorage::new();+ let uuid = uuid::Uuid::new_v4();+ let mut first = queued("a", 1);+ first.uuid = uuid;+ let first = storage+ .upsert_mutation_with_shadow(first, 1, OptimisticUpsertReconciliation::default())+ .await+ .unwrap();+ assert_eq!(first.kind, MutationUpsertKind::Inserted);++ let mut pending = queued("b", 2);+ pending.uuid = uuid;+ let pending = storage+ .upsert_mutation_with_shadow(pending, 2, OptimisticUpsertReconciliation::default())+ .await+ .unwrap();+ assert_eq!(+ pending.kind,+ MutationUpsertKind::ReplacedPending {+ removed_id: first.id+ }+ );+ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 3,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(claimed.queued.id, pending.id);++ let mut active = queued("c", 4);+ active.uuid = uuid;+ let active = storage+ .upsert_mutation_with_shadow(active, 4, OptimisticUpsertReconciliation::default())+ .await+ .unwrap();+ assert_eq!(+ active.kind,+ MutationUpsertKind::AppendedAfterActive {+ active_id: pending.id+ }+ );+ let queue = storage.load_mutation_queue().await.unwrap();+ assert_eq!(queue.len(), 2);+ assert!(queue[0].superseded);+ assert_eq!(queue[1].id, active.id);+ });+}+#[test]fn queue_claim_retry_and_settlement_are_ordered() {block_on(async {diff --git a/crates/client/cache-core/tests/optimistic.rs b/crates/client/cache-core/tests/optimistic.rsindex 384e252949..7e7cc5e237 100644--- a/crates/client/cache-core/tests/optimistic.rs+++ b/crates/client/cache-core/tests/optimistic.rs@@ -2,17 +2,17 @@//! strict ordering, and lifecycle resets.use cache_core::engine::{- BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, ReadResult,+ BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,+ EngineError, InitialClaimOutcome, ReadResult,};-use cache_core::predicate::ProjectionMutation;+use cache_core::predicate::{OptimisticUpsertReconciliation, ProjectionMutation};use cache_core::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,- QueuedMutation,+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationUpsertResult,+ NewQueuedMutation, QueuedMutation,};use cache_core::store::{InMemoryStorage, Storage};use cache_core::value::{CacheValue, EntityKey, Record};use pollster::block_on;-use predicate_index::PendingOptimisticProjection;use serde_json::{Value as Json, json};use std::sync::atomic::{AtomicBool, Ordering};@@ -117,14 +117,15 @@ impl Storage for ClaimFailingStorage {Ok(())}- async fn enqueue_mutation_with_shadow(+ async fn upsert_mutation_with_shadow(&mut self,entry: NewQueuedMutation,- projections: Vec<PendingOptimisticProjection>,- ) -> Result<MutationId, Self::Error> {+ now_ms: i64,+ reconciliation: OptimisticUpsertReconciliation,+ ) -> Result<MutationUpsertResult, Self::Error> {Ok(self.inner- .enqueue_mutation_with_shadow(entry, projections)+ .upsert_mutation_with_shadow(entry, now_ms, reconciliation).await.unwrap())}@@ -297,6 +298,7 @@ async fn reconciliation_engine() -> (Engine<ClaimFailingStorage>, MutationId) {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000005",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -362,6 +364,33 @@ async fn claim_head()}+async fn begin_value(+ engine: &mut Engine<InMemoryStorage>,+ uuid: &str,+ value: &str,+ created_at_ms: i64,+) -> MutationId {+ let variables = mutation_vars(value);+ let data = mutation_response("Status", value);+ engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ uuid,+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &variables,+ data: &data,+ link_patches: &[],+ revalidations: &[],+ created_at_ms,+ },+ )+ .await+ .unwrap()+ .0+}+async fn durable_value(engine: &Engine<InMemoryStorage>) -> Option<String> {let records = engine.storage()@@ -387,6 +416,7 @@ fn begin_persists_mutation_and_optimistic_layer() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000006",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -423,6 +453,7 @@ fn enqueue_claims_new_mutation_when_queue_was_empty() {.enqueue_optimistic_mutation(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000007",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -456,6 +487,7 @@ fn enqueue_claims_older_strict_head() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000008",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("older"),@@ -471,6 +503,7 @@ fn enqueue_claims_older_strict_head() {.enqueue_optimistic_mutation(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000009",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("new"),@@ -505,6 +538,7 @@ fn enqueue_does_not_skip_a_leased_or_deferred_head() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000010",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("older"),@@ -528,6 +562,7 @@ fn enqueue_does_not_skip_a_leased_or_deferred_head() {.enqueue_optimistic_mutation(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000011",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("new"),@@ -585,6 +620,7 @@ fn claim_failure_after_enqueue_preserves_one_durable_visible_mutation() {.enqueue_optimistic_mutation(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000012",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -694,6 +730,7 @@ fn claimed_success_atomically_commits_real_response() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000013",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -745,6 +782,7 @@ fn retryable_failure_keeps_optimistic_layer_and_blocks_later_mutations() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000014",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("a"),@@ -760,6 +798,7 @@ fn retryable_failure_keeps_optimistic_layer_and_blocks_later_mutations() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000015",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("b"),@@ -806,6 +845,7 @@ fn permanent_failure_rolls_back_only_the_claimed_head() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000016",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("a"),@@ -821,6 +861,7 @@ fn permanent_failure_rolls_back_only_the_claimed_head() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000017",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("b"),@@ -856,6 +897,7 @@ fn stale_claim_cannot_settle_mutation() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000018",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -887,6 +929,222 @@ fn stale_claim_cannot_settle_mutation() {});}+#[test]+fn pending_uuid_replacement_moves_to_tail_and_keeps_only_latest_layer() {+ block_on(async {+ const X: &str = "13e0b56d-772d-4cc6-920d-358de3235849";+ const Y: &str = "34736e0a-cd21-418b-9f34-67362bc213cd";+ let mut engine = engine_with_base("Status", "todo").await;+ let first = begin_value(&mut engine, X, "a", 1).await;+ let intervening = begin_value(&mut engine, Y, "c", 2).await;+ let replacement = begin_value(&mut engine, X, "b", 3).await;++ assert!(replacement > intervening && intervening > first);+ let queued = engine.storage().load_mutation_queue().await.unwrap();+ assert_eq!(+ queued.iter().map(|row| row.id).collect::<Vec<_>>(),+ [intervening, replacement]+ );+ assert_eq!(+ queued.iter().map(|row| row.uuid).collect::<Vec<_>>(),+ [+ uuid::Uuid::parse_str(Y).unwrap(),+ uuid::Uuid::parse_str(X).unwrap(),+ ]+ );+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));+ });+}++#[test]+fn pending_replacement_restores_fields_omitted_by_the_new_intent() {+ block_on(async {+ const X: &str = "5470d1c4-e5d8-45d7-a165-afca1331954c";+ let mut engine = engine_with_base("Status", "todo").await;+ let variables = mutation_vars("a");+ let first_data = mutation_response("Transient", "a");+ engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ uuid: X,+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &variables,+ data: &first_data,+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 1,+ },+ )+ .await+ .unwrap();+ let variables = mutation_vars("b");+ let replacement_data = json!({+ "setEntityProperty": {+ "id": "prop-1",+ "value": {+ "__typename": "GraphqlStringPropertyValue",+ "stringValue": "b"+ }+ }+ });+ engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ uuid: X,+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &variables,+ data: &replacement_data,+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 2,+ },+ )+ .await+ .unwrap();++ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["displayName"], json!("Status"));+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));+ });+}++#[test]+fn active_uuid_replacement_is_superseded_and_failed_attempt_is_discarded() {+ block_on(async {+ const X: &str = "6483ff81-262e-47cc-a56b-3c6bed971fbe";+ let mut engine = engine_with_base("Status", "todo").await;+ let active = begin_value(&mut engine, X, "a", 1).await;+ let claimed = engine+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 10,+ lease_expires_at_ms: 20,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(claimed.queued.id, active);+ let replacement = begin_value(&mut engine, X, "b", 11).await;++ let queued = engine.storage().load_mutation_queue().await.unwrap();+ assert_eq!(queued.len(), 2);+ assert!(queued[0].superseded);+ assert!(!queued[1].superseded);+ assert_eq!(queued[1].id, replacement);+ assert!(+ engine+ .claim_next_mutation(MutationClaimRequest {+ owner: "other".into(),+ now_ms: 12,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .is_none()+ );++ let recovered = engine+ .claim_next_mutation(MutationClaimRequest {+ owner: "recovery".into(),+ now_ms: 20,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert!(recovered.queued.superseded);+ let deferred = engine+ .defer_optimistic_write(+ active,+ MutationClaimToken {+ owner: "recovery".into(),+ generation: recovered.lease_generation,+ },+ 500,+ "superseded".into(),+ )+ .await+ .unwrap();+ let DeferOptimisticWriteResult::DiscardedSuperseded(discarded) = deferred else {+ panic!("superseded attempt was retained")+ };+ assert_eq!(discarded.replacement_transaction_id, replacement);+ let queued = engine.storage().load_mutation_queue().await.unwrap();+ assert_eq!(queued.len(), 1);+ assert_eq!(queued[0].id, replacement);+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));+ });+}++#[test]+fn successful_superseded_attempt_commits_beneath_the_replacement_without_flicker() {+ block_on(async {+ const X: &str = "e1fe0a96-37f7-4534-a8fe-613bba700c13";+ let mut engine = engine_with_base("Status", "todo").await;+ let active = begin_value(&mut engine, X, "a", 1).await;+ let (claimed, claim) = claim_head(&mut engine, "runner", 10).await;+ assert_eq!(claimed, active);+ let replacement = begin_value(&mut engine, X, "b", 11).await;++ let outcome = engine+ .commit_optimistic_write_with_outcome(+ active,+ claim,+ MUTATION,+ Some("SetEntityProperty"),+ &mutation_vars("a"),+ &mutation_response("Status", "server-a"),+ )+ .await+ .unwrap();+ let CommitOptimisticWriteResult::CommittedSuperseded(outcome) = outcome else {+ panic!("stale response was reported as a current commit")+ };+ assert_eq!(outcome.replacement_transaction_id, replacement);++ let queue = engine.storage().load_mutation_queue().await.unwrap();+ assert_eq!(queue.len(), 1);+ assert_eq!(queue[0].id, replacement);+ let data = read_hit(&mut engine, None).await;+ assert_eq!(property_of(&data)["value"]["stringValue"], json!("b"));+ assert_eq!(durable_value(&engine).await.as_deref(), Some("server-a"));+ });+}++#[test]+fn invalid_uuid_is_rejected_before_queue_hydration() {+ block_on(async {+ let mut engine = engine_with_base("Status", "todo").await;+ let variables = mutation_vars("doing");+ let data = mutation_response("Status", "doing");+ let queue_loads = engine.storage().mutation_queue_load_count();+ let error = engine+ .begin_optimistic_write(+ None,+ BeginOptimisticWrite {+ uuid: "not-a-uuid",+ query: MUTATION,+ operation_name: Some("SetEntityProperty"),+ variables: &variables,+ data: &data,+ link_patches: &[],+ revalidations: &[],+ created_at_ms: 1,+ },+ )+ .await+ .unwrap_err();+ assert!(matches!(error, EngineError::InvalidMutationUuid(_)));+ assert_eq!(engine.storage().mutation_queue_load_count(), queue_loads);+ });+}+#[test]fn clear_and_identity_reset_drop_durable_queue() {block_on(async {@@ -906,6 +1164,7 @@ fn clear_and_identity_reset_drop_durable_queue() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000019",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),diff --git a/crates/client/cache-core/tests/predicate.rs b/crates/client/cache-core/tests/predicate.rsindex 418209c97e..018944d9b7 100644--- a/crates/client/cache-core/tests/predicate.rs+++ b/crates/client/cache-core/tests/predicate.rs@@ -111,11 +111,21 @@ fn optimistic_variables() -> serde_json::Map<String, serde_json::Value> {async fn try_begin_with_projection(engine: &mut Engine<InMemoryStorage>,projection_mutations: Vec<OptimisticProjectionMutation>,+) -> Result<MutationId, EngineError<std::convert::Infallible>> {+ let uuid = uuid::Uuid::new_v4().to_string();+ try_begin_with_projection_uuid(engine, &uuid, projection_mutations).await+}++async fn try_begin_with_projection_uuid(+ engine: &mut Engine<InMemoryStorage>,+ uuid: &str,+ projection_mutations: Vec<OptimisticProjectionMutation>,) -> Result<MutationId, EngineError<std::convert::Infallible>> {engine.begin_optimistic_write_with_projections(None,BeginOptimisticWrite {+ uuid,query: OPTIMISTIC_MUTATION,operation_name: Some("SetEntityProperty"),variables: &optimistic_variables(),@@ -929,6 +939,69 @@ fn optimistic_settlement_applies_authoritative_patch_before_shadow_reconciliatio});}+#[test]+fn pending_uuid_replacement_reassigns_projection_shadow_to_the_new_tail() {+ pollster::block_on(async {+ let mut engine = Engine::new(InMemoryStorage::new());+ engine+ .put_records_with_projections(+ None,+ vec![(+ EntityKey::entity("GraphqlSoupDocument", &["doc-1"]),+ Record::default(),+ )],+ vec![ProjectionMutation::Replace(projection("authority"))],+ )+ .await+ .unwrap();+ let uuid = "e3ac0a53-8789-4925-8664-744630448ebe";+ let first = try_begin_with_projection_uuid(+ &mut engine,+ uuid,+ vec![OptimisticProjectionMutation::Replace(projection("owner-1"))],+ )+ .await+ .unwrap();+ let replacement = try_begin_with_projection_uuid(+ &mut engine,+ uuid,+ vec![OptimisticProjectionMutation::Replace(projection("owner-2"))],+ )+ .await+ .unwrap();++ assert!(replacement > first);+ let queue = engine.storage().load_mutation_queue().await.unwrap();+ assert_eq!(+ queue.iter().map(|row| row.id).collect::<Vec<_>>(),+ [replacement]+ );+ let shadow = engine+ .storage()+ .load_optimistic_projections(&[record_key()])+ .await+ .unwrap()+ .pop()+ .flatten()+ .unwrap();+ assert_eq!(shadow.owner, replacement);+ assert_eq!(+ engine+ .query_predicate_index(&query("owner-2"))+ .await+ .unwrap(),+ PredicateQueryResult::Optimistic(vec![record_key()])+ );+ assert_eq!(+ engine+ .query_predicate_index(&query("owner-1"))+ .await+ .unwrap(),+ PredicateQueryResult::Optimistic(Vec::new())+ );+ });+}+#[test]fn optimistic_deletion_overfetches_authoritative_replacement_candidates() {pollster::block_on(async {diff --git a/crates/client/cache-core/tests/query_inspection.rs b/crates/client/cache-core/tests/query_inspection.rsindex ed318404ad..fe52308e1d 100644--- a/crates/client/cache-core/tests/query_inspection.rs+++ b/crates/client/cache-core/tests/query_inspection.rs@@ -4,16 +4,15 @@ use cache_core::engine::{BeginOptimisticWrite, Engine};use cache_core::link_patch::{LinkOperation, LinkPathSegment, ListItemByScalar, OptimisticLinkPatch,};-use cache_core::predicate::ProjectionMutation;+use cache_core::predicate::{OptimisticUpsertReconciliation, ProjectionMutation};use cache_core::query_inspection::{MAX_INSPECTED_VARIANTS, QueryInspection, QueryInspectionError};use cache_core::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,- QueuedMutation,+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationUpsertResult,+ NewQueuedMutation, QueuedMutation,};use cache_core::store::{InMemoryStorage, Storage};use cache_core::value::{EntityKey, Record};use pollster::block_on;-use predicate_index::PendingOptimisticProjection;use serde_json::{Value as Json, json};const GROUP_QUERY: &str = r#"@@ -120,13 +119,14 @@ impl Storage for OwnerOnlyStorage {self.0.delete_batch(keys).await}- async fn enqueue_mutation_with_shadow(+ async fn upsert_mutation_with_shadow(&mut self,entry: NewQueuedMutation,- projections: Vec<PendingOptimisticProjection>,- ) -> Result<MutationId, Self::Error> {+ now_ms: i64,+ reconciliation: OptimisticUpsertReconciliation,+ ) -> Result<MutationUpsertResult, Self::Error> {self.0- .enqueue_mutation_with_shadow(entry, projections)+ .upsert_mutation_with_shadow(entry, now_ms, reconciliation).await}@@ -497,6 +497,7 @@ mutation SetEntityProperty($input: SetEntityPropertyInput!) {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000002",query: mutation,operation_name: Some("SetEntityProperty"),variables: &mutation_variables,diff --git a/crates/client/cache-core/tests/record_selection.rs b/crates/client/cache-core/tests/record_selection.rsindex fb4f287f04..0ea87ea611 100644--- a/crates/client/cache-core/tests/record_selection.rs+++ b/crates/client/cache-core/tests/record_selection.rs@@ -287,6 +287,7 @@ fn merges_optimistic_updates_with_cold_linked_bases() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000003",query: mutation,operation_name: Some("SetProperty"),variables: &variables,@@ -346,6 +347,7 @@ fn includes_optimistic_only_records() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000004",query: mutation,operation_name: Some("SetProperty"),variables: &variables,diff --git a/crates/client/cache-core/tests/search.rs b/crates/client/cache-core/tests/search.rsindex e897c58404..6c1fcdd1c9 100644--- a/crates/client/cache-core/tests/search.rs+++ b/crates/client/cache-core/tests/search.rs@@ -252,6 +252,7 @@ fn optimistic_records_explicitly_overlay_the_durable_search_catalog() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000000020",query: RENAME,operation_name: Some("Rename"),variables: &rename_variables,diff --git a/crates/client/cache-turso/Cargo.toml b/crates/client/cache-turso/Cargo.tomlindex dd23da10d2..a4d1f122c4 100644--- a/crates/client/cache-turso/Cargo.toml+++ b/crates/client/cache-turso/Cargo.toml@@ -13,6 +13,7 @@ cache-core = { path = "../cache-core" }maybe_send = { path = "../../maybe_send" }predicate-index = { path = "../../predicate_index" }thiserror = { workspace = true }+uuid = { workspace = true }[target.'cfg(target_arch = "wasm32")'.dependencies]turso-opfs = { path = "../turso-opfs" }diff --git a/crates/client/cache-turso/src/storage.rs b/crates/client/cache-turso/src/storage.rsindex 3ef97f630c..c3a5c27933 100644--- a/crates/client/cache-turso/src/storage.rs+++ b/crates/client/cache-turso/src/storage.rs@@ -5,27 +5,31 @@ use cache_core::codec::{cache_namespace, decode_record, decode_record_updates, encode_record, encode_record_updates,};use cache_core::predicate::{- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,- ProjectionIncompleteKind, ProjectionMutation, ProjectionState,- apply_authoritative_projection_patch,+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,+ PredicateQueryResult, ProjectionIncompleteKind, ProjectionMutation, ProjectionState,+ StagedOptimisticProjectionOwner, apply_authoritative_projection_patch,};use cache_core::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationRequest,- NewQueuedMutation, PersistedOptimisticLayer, QueuedMutation, StoredMutation,+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationQueueSnapshot,+ MutationRequest, MutationUpsertKind, MutationUpsertResult, NewQueuedMutation,+ PersistedOptimisticLayer, QueuedMutation, StoredMutation,};use cache_core::search::{SearchCursor, SearchDocument, SearchProfile, project_search_documents};use cache_core::store::{QueueDiagnostics, QueueDiagnosticsAvailability, Storage};use cache_core::value::{EntityKey, Record};use predicate_index::{- EffectiveOptimisticProjection, OptimisticProjectionState, OptimisticUncertainty,- PendingOptimisticProjection, PredicateExpr, Profile, RangeBound,- RecordKey as PredicateRecordKey, SortDirection, Token, ValidatedIndexQuery,+ EffectiveOptimisticProjection, OptimisticProjectionState, OptimisticUncertainty, PredicateExpr,+ Profile, RangeBound, RecordKey as PredicateRecordKey, SortDirection, Token,+ ValidatedIndexQuery,};-use std::collections::{BTreeSet, HashMap, HashSet};+use std::collections::{BTreeSet, HashMap};use std::sync::Arc;use std::sync::atomic::{AtomicU8, Ordering};use turso_core::{Connection, Numeric, Value};+#[cfg(test)]+use predicate_index::PendingOptimisticProjection;+#[cfg(not(target_arch = "wasm32"))]use std::io::ErrorKind;#[cfg(not(target_arch = "wasm32"))]@@ -43,7 +47,7 @@ use turso_opfs::{};/// Frozen storage schema version, independent of cache postcard versions.-pub const STORAGE_SCHEMA_VERSION: u32 = 10;+pub const STORAGE_SCHEMA_VERSION: u32 = 11;/// Coarse outcome of validating a Turso database.#[derive(Clone, Copy, Debug, PartialEq, Eq)]@@ -54,13 +58,14 @@ pub enum TursoStorageOpenOutcome {OpenedNew,}-const CREATE_SCHEMA: [&str; 27] = [+const CREATE_SCHEMA: [&str; 28] = ["CREATE TABLE meta (key TEXT PRIMARY KEY, value TEXT NOT NULL)","CREATE TABLE records (__typename TEXT NOT NULL, id TEXT NOT NULL, value BLOB NOT NULL, PRIMARY KEY (__typename, id))","CREATE TABLE search_documents (profile TEXT NOT NULL, __typename TEXT NOT NULL, id TEXT NOT NULL, bucket TEXT NOT NULL, search_text TEXT NOT NULL, timestamp_ms INTEGER NOT NULL, source_hash TEXT NOT NULL, PRIMARY KEY (profile, __typename, id))","CREATE INDEX search_documents_browse_idx ON search_documents(profile, bucket, timestamp_ms DESC, __typename, id)",- "CREATE TABLE 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 mutation_queue (id INTEGER PRIMARY KEY AUTOINCREMENT, uuid TEXT NOT NULL, superseded INTEGER NOT NULL DEFAULT 0, 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 INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",+ "CREATE UNIQUE INDEX mutation_queue_current_uuid_idx ON mutation_queue(uuid) WHERE superseded = 0","CREATE TABLE 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)","CREATE TABLE index_documents (id INTEGER PRIMARY KEY, record_key TEXT NOT NULL, profile TEXT NOT NULL, partition TEXT NOT NULL, state INTEGER NOT NULL)","CREATE UNIQUE INDEX index_documents_record_key_idx ON index_documents(record_key)",@@ -105,10 +110,10 @@ const INTEGER_FACT_INSERT: &str ="INSERT INTO integer_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";const SORT_FACT_INSERT: &str ="INSERT INTO sort_facts (document_id, attribute, value) VALUES (?1, ?2, ?3)";-const QUEUE_INSERT: &str = "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)";+const QUEUE_INSERT: &str = "INSERT INTO mutation_queue (uuid, superseded, 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, 0, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)";const LAYER_INSERT: &str = "INSERT INTO optimistic_layers (mutation_id, optimistic_data_json, normalized_updates) VALUES (?1, ?2, ?3)";-const QUEUE_SELECT: &str = "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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC";-const QUEUE_HEAD_SELECT: &str = "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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC LIMIT 1";+const QUEUE_SELECT: &str = "SELECT m.id, m.uuid, m.superseded, 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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC";+const QUEUE_HEAD_SELECT: &str = "SELECT m.id, m.uuid, m.superseded, 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 AS m LEFT JOIN optimistic_layers AS o ON o.mutation_id = m.id ORDER BY m.id ASC LIMIT 1";const ORPHAN_LAYER_SELECT: &str = "SELECT o.mutation_id FROM optimistic_layers AS o LEFT JOIN mutation_queue AS m ON m.id = o.mutation_id WHERE m.id IS NULL LIMIT 1";const ANY_LAYER_SELECT: &str = "SELECT mutation_id FROM optimistic_layers LIMIT 1";const CLAIM_SELECT: &str = "SELECT lease_owner, lease_generation FROM mutation_queue WHERE id = ?1";@@ -245,6 +250,7 @@ impl TursoStorage {&connection,QUEUE_INSERT,vec![+ text("00000000-0000-4000-8000-000000000001"),text("mutation BrowserTestCorrupt { __typename }"),Value::Null,text("{}"),@@ -935,24 +941,70 @@ impl Storage for TursoStorage {self.latch_result(result)}- async fn enqueue_mutation_with_shadow(+ async fn upsert_mutation_with_shadow(&mut self,entry: NewQueuedMutation,- projections: Vec<PendingOptimisticProjection>,- ) -> Result<MutationId, Self::Error> {+ now_ms: i64,+ reconciliation: OptimisticUpsertReconciliation,+ ) -> Result<MutationUpsertResult, Self::Error> {self.require_healthy()?;let result = (|| {- validate_pending_optimistic_projections(&projections)?;- let mutation_values = mutation_values(&entry.mutation)?;+ reconciliation+ .validate()+ .map_err(|_| TursoStorageError::InvalidInput)?;+ let mutation_values = mutation_values(&entry)?;let updates = encode_record_updates(&entry.optimistic.normalized_updates);let connection = self.connection();driver::write_transaction(&connection, || {+ if let Some(expected) = &reconciliation.expected_queue+ && !queue_snapshot_matches(&connection, expected)?+ {+ return Err(TursoStorageError::InvalidInput);+ }+ let collision = driver::query(+ &connection,+ "SELECT id, lease_expires_at_ms FROM mutation_queue WHERE uuid = ?1 AND superseded = 0",+ vec![text(&entry.uuid.to_string())],+ )?;+ let kind = match collision.as_slice() {+ [] => MutationUpsertKind::Inserted,+ [row] if row.len() == 2 => {+ let existing = mutation_id_from_row(required_i64(row, 0)?)?;+ if nullable_i64(row, 1)?.is_some_and(|expiry| expiry > now_ms) {+ require_changed(+ driver::execute(+ &connection,+ "UPDATE mutation_queue SET superseded = 1 WHERE id = ?1 AND superseded = 0",+ vec![Value::from_i64(mutation_id_to_sql(existing)?)],+ )?,+ 1,+ )?;+ MutationUpsertKind::AppendedAfterActive {+ active_id: existing,+ }+ } else {+ require_changed(+ driver::execute(+ &connection,+ "DELETE FROM mutation_queue WHERE id = ?1 AND superseded = 0",+ vec![Value::from_i64(mutation_id_to_sql(existing)?)],+ )?,+ 1,+ )?;+ MutationUpsertKind::ReplacedPending {+ removed_id: existing,+ }+ }+ }+ _ => return Err(invariant()),+ };+ self.fault_after(TestFaultSite::Enqueue, 0)?;require_changed(driver::execute(&connection, QUEUE_INSERT, mutation_values)?,1,)?;- self.fault_after(TestFaultSite::Enqueue, 0)?;let id = mutation_id_from_row(connection.last_insert_rowid())?;+ self.fault_after(TestFaultSite::Enqueue, 1)?;require_changed(driver::execute(&connection,@@ -965,10 +1017,11 @@ impl Storage for TursoStorage {)?,1,)?;- write_pending_optimistic_projections(&connection, id, projections, |index| {- self.fault_after(TestFaultSite::Enqueue, index + 1)+ self.fault_after(TestFaultSite::Enqueue, 2)?;+ write_upsert_shadow_reconciliation(&connection, id, reconciliation, |index| {+ self.fault_after(TestFaultSite::Enqueue, index + 3)})?;- Ok(id)+ Ok(MutationUpsertResult { id, kind })})})();self.latch_result(result)@@ -1009,6 +1062,8 @@ impl Storage for TursoStorage {let optimistic = parsed.optimistic.ok_or_else(invariant)?;queue.push(QueuedMutation {id: parsed.id,+ uuid: parsed.uuid,+ superseded: parsed.superseded,mutation: parsed.mutation,optimistic,});@@ -1104,6 +1159,8 @@ impl Storage for TursoStorage {Ok(Some(ClaimedMutation {queued: QueuedMutation {id: parsed.id,+ uuid: parsed.uuid,+ superseded: parsed.superseded,mutation: parsed.mutation,optimistic,},@@ -1429,21 +1486,6 @@ impl PredicateIndexStorage for TursoStorage {}}-fn validate_pending_optimistic_projections(- projections: &[PendingOptimisticProjection],-) -> Result<(), TursoStorageError> {- let mut keys = HashSet::with_capacity(projections.len());- for projection in projections {- projection- .validate()- .map_err(|_| TursoStorageError::InvalidInput)?;- if !keys.insert(projection.state.record_key()) {- return Err(TursoStorageError::InvalidInput);- }- }- Ok(())-}-fn validate_shadow_reconciliation(id: MutationId,reconciliation: &OptimisticShadowReconciliation,@@ -1453,6 +1495,35 @@ fn validate_shadow_reconciliation(.map_err(|_| TursoStorageError::InvalidInput)}+fn queue_snapshot_matches(+ connection: &Arc<Connection>,+ expected: &[MutationQueueSnapshot],+) -> Result<bool, TursoStorageError> {+ let rows = driver::query(+ connection,+ "SELECT id, uuid, superseded, lease_owner, lease_generation, lease_expires_at_ms, next_attempt_at_ms FROM mutation_queue ORDER BY id ASC",+ Vec::new(),+ )?;+ if rows.len() != expected.len() {+ return Ok(false);+ }+ for (row, expected) in rows.iter().zip(expected) {+ if row.len() != 7+ || mutation_id_from_row(required_i64(row, 0)?)? != expected.id+ || parse_uuid(&required_text(row, 1)?)? != expected.uuid+ || parse_boolean(row, 2)? != expected.superseded+ || nullable_text(row, 3)? != expected.lease_owner+ || u64::try_from(required_i64(row, 4)?).map_err(|_| invariant())?+ != expected.lease_generation+ || nullable_i64(row, 5)? != expected.lease_expires_at_ms+ || nullable_i64(row, 6)? != expected.next_attempt_at_ms+ {+ return Ok(false);+ }+ }+ Ok(true)+}+fn queue_identity_matches(connection: &Arc<Connection>,expected: &[MutationId],@@ -1493,16 +1564,26 @@ fn write_shadow_reconciliation(Ok(())}-fn write_pending_optimistic_projections(+fn write_upsert_shadow_reconciliation(connection: &Arc<Connection>,- owner: MutationId,- projections: Vec<PendingOptimisticProjection>,+ enqueued: MutationId,+ reconciliation: OptimisticUpsertReconciliation,mut after_write: impl FnMut(usize) -> Result<(), TursoStorageError>,) -> Result<(), TursoStorageError> {- let owner = mutation_id_to_sql(owner)?;- for (index, projection) in projections.into_iter().enumerate() {- delete_optimistic_projection(connection, projection.state.record_key())?;- insert_optimistic_projection(connection, owner, projection.state, projection.uncertainty)?;+ for key in &reconciliation.affected_keys {+ delete_optimistic_projection(connection, key)?;+ }+ for (index, replacement) in reconciliation.replacements.into_iter().enumerate() {+ let owner = match replacement.owner {+ StagedOptimisticProjectionOwner::Existing(owner) => owner,+ StagedOptimisticProjectionOwner::Enqueued => enqueued,+ };+ insert_optimistic_projection(+ connection,+ mutation_id_to_sql(owner)?,+ replacement.state,+ replacement.uncertainty,+ )?;after_write(index)?;}Ok(())@@ -2680,6 +2761,20 @@ const MUTATION_COLUMNS: &[ColumnSpec] = &[default_zero: false,primary_key_position: 1,},+ ColumnSpec {+ name: "uuid",+ declared_type: "TEXT",+ not_null: true,+ default_zero: false,+ primary_key_position: 0,+ },+ ColumnSpec {+ name: "superseded",+ declared_type: "INTEGER",+ not_null: true,+ default_zero: true,+ primary_key_position: 0,+ },ColumnSpec {name: "query",declared_type: "TEXT",@@ -3077,6 +3172,7 @@ fn validate_allowed_schema_objects(connection: &Arc<Connection>) -> Result<(), T"integer_facts_lookup_idx","index_documents_record_key_idx","mutation_queue_created_at_ms_idx",+ "mutation_queue_current_uuid_idx","optimistic_exact_facts_lookup_idx","optimistic_index_documents_owner_idx","optimistic_index_documents_record_key_idx",@@ -3334,41 +3430,87 @@ fn validate_mutation_queue_indexes(connection: &Arc<Connection>) -> Result<(), TVec::new(),).map_err(TursoStorageError::initialization)?;- let [row] = rows.as_slice() else {+ if rows.len() != 2 {+ return Err(compatibility());+ }+ let created = rows+ .iter()+ .find(|row| {+ required_text(row, 1).ok().as_deref() == Some("mutation_queue_created_at_ms_idx")+ })+ .ok_or_else(compatibility)?;+ let current = rows+ .iter()+ .find(|row| {+ required_text(row, 1).ok().as_deref() == Some("mutation_queue_current_uuid_idx")+ })+ .ok_or_else(compatibility)?;+ if created.len() != 5+ || required_i64(created, 2).ok() != Some(0)+ || required_text(created, 3).ok().as_deref() != Some("c")+ || required_i64(created, 4).ok() != Some(0)+ || current.len() != 5+ || required_i64(current, 2).ok() != Some(1)+ || required_text(current, 3).ok().as_deref() != Some("c")+ || required_i64(current, 4).ok() != Some(1)+ {+ return Err(compatibility());+ }+ validate_mutation_index_columns(+ connection,+ "mutation_queue_created_at_ms_idx",+ 13,+ "created_at_ms",+ )?;+ validate_mutation_index_columns(connection, "mutation_queue_current_uuid_idx", 1, "uuid")?;+ let sql = driver::query(+ connection,+ "SELECT sql FROM sqlite_schema WHERE type = 'index' AND name = 'mutation_queue_current_uuid_idx'",+ Vec::new(),+ )+ .map_err(TursoStorageError::initialization)?;+ let [row] = sql.as_slice() else {return Err(compatibility());};- if row.len() != 5- || required_i64(row, 0).ok() != Some(0)- || required_text(row, 1).ok().as_deref() != Some("mutation_queue_created_at_ms_idx")- || required_i64(row, 2).ok() != Some(0)- || required_text(row, 3).ok().as_deref() != Some("c")- || required_i64(row, 4).ok() != Some(0)+ let normalized = required_text(row, 0)+ .map_err(|_| compatibility())?+ .split_whitespace()+ .collect::<Vec<_>>()+ .join(" ")+ .to_ascii_lowercase();+ if normalized+ != "create unique index mutation_queue_current_uuid_idx on mutation_queue (uuid) where superseded = 0"{return Err(compatibility());}- let index_rows = driver::query(+ Ok(())+}++fn validate_mutation_index_columns(+ connection: &Arc<Connection>,+ index: &str,+ column: i64,+ name: &str,+) -> Result<(), TursoStorageError> {+ let rows = driver::query(connection,- "PRAGMA index_xinfo('mutation_queue_created_at_ms_idx')",+ &format!("PRAGMA index_xinfo('{index}')"),Vec::new(),).map_err(TursoStorageError::initialization)?;- let [created_at, rowid] = index_rows.as_slice() else {+ let [key, rowid] = rows.as_slice() else {return Err(compatibility());};- if created_at.len() != 6- || required_i64(created_at, 0).ok() != Some(0)- || required_i64(created_at, 1).ok() != Some(11)- || required_text(created_at, 2).ok().as_deref() != Some("created_at_ms")- || required_i64(created_at, 3).ok() != Some(0)- || required_text(created_at, 4).ok().as_deref() != Some("BINARY")- || required_i64(created_at, 5).ok() != Some(1)+ if key.len() != 6+ || required_i64(key, 0).ok() != Some(0)+ || required_i64(key, 1).ok() != Some(column)+ || required_text(key, 2).ok().as_deref() != Some(name)+ || required_i64(key, 3).ok() != Some(0)+ || required_text(key, 4).ok().as_deref() != Some("BINARY")+ || required_i64(key, 5).ok() != Some(1)|| rowid.len() != 6|| required_i64(rowid, 0).ok() != Some(1)|| required_i64(rowid, 1).ok() != Some(-1)- || !rowid.get(2).is_some_and(|value| {- matches!(value, Value::Null)- || matches!(value, Value::Text(text) if text.as_str().is_empty())- })|| required_i64(rowid, 3).ok() != Some(0)|| required_text(rowid, 4).ok().as_deref() != Some("BINARY")|| required_i64(rowid, 5).ok() != Some(0)@@ -4016,8 +4158,10 @@ fn parse_search_document(})}-fn mutation_values(mutation: &StoredMutation) -> Result<Vec<Value>, TursoStorageError> {+fn mutation_values(entry: &NewQueuedMutation) -> Result<Vec<Value>, TursoStorageError> {+ let mutation = &entry.mutation;Ok(vec![+ text(&entry.uuid.to_string()),text(&mutation.request.query),optional_text(mutation.request.operation_name.as_deref()),text(&mutation.request.variables_json),@@ -4034,44 +4178,60 @@ fn mutation_values(mutation: &StoredMutation) -> Result<Vec<Value>, TursoStoragestruct ParsedQueueRow {id: MutationId,+ uuid: uuid::Uuid,+ superseded: bool,mutation: StoredMutation,optimistic: Option<PersistedOptimisticLayer>,}fn parse_queue_row(row: &[Value]) -> Result<ParsedQueueRow, TursoStorageError> {- if row.len() != 14 {+ if row.len() != 16 {return Err(invariant());}- let optimistic = match (&row[12], &row[13]) {+ let optimistic = match (&row[14], &row[15]) {(Value::Null, Value::Null) => None,(Value::Null, _) | (_, Value::Null) => return Err(invariant()),_ => Some(PersistedOptimisticLayer {- optimistic_data_json: required_text(row, 12)?,- normalized_updates: decode_record_updates(&required_blob(row, 13)?)+ optimistic_data_json: required_text(row, 14)?,+ normalized_updates: decode_record_updates(&required_blob(row, 15)?).map_err(|_| TursoStorageError::reset(PhysicalResetReason::Codec))?,}),};Ok(ParsedQueueRow {id: mutation_id_from_row(required_i64(row, 0)?)?,+ uuid: parse_uuid(&required_text(row, 1)?)?,+ superseded: parse_boolean(row, 2)?,mutation: StoredMutation {request: MutationRequest {- query: required_text(row, 1)?,- operation_name: nullable_text(row, 2)?,- variables_json: required_text(row, 3)?,- identity: nullable_text(row, 4)?,+ query: required_text(row, 3)?,+ operation_name: nullable_text(row, 4)?,+ variables_json: required_text(row, 5)?,+ identity: nullable_text(row, 6)?,},- attempt_count: u32::try_from(required_i64(row, 5)?).map_err(|_| invariant())?,- next_attempt_at_ms: nullable_i64(row, 6)?,- lease_owner: nullable_text(row, 7)?,- lease_generation: u64::try_from(required_i64(row, 8)?).map_err(|_| invariant())?,- lease_expires_at_ms: nullable_i64(row, 9)?,- last_error: nullable_text(row, 10)?,- created_at_ms: required_i64(row, 11)?,+ attempt_count: u32::try_from(required_i64(row, 7)?).map_err(|_| invariant())?,+ next_attempt_at_ms: nullable_i64(row, 8)?,+ lease_owner: nullable_text(row, 9)?,+ lease_generation: u64::try_from(required_i64(row, 10)?).map_err(|_| invariant())?,+ lease_expires_at_ms: nullable_i64(row, 11)?,+ last_error: nullable_text(row, 12)?,+ created_at_ms: required_i64(row, 13)?,},optimistic,})}+fn parse_uuid(value: &str) -> Result<uuid::Uuid, TursoStorageError> {+ uuid::Uuid::parse_str(value).map_err(|_| invariant())+}++fn parse_boolean(row: &[Value], index: usize) -> Result<bool, TursoStorageError> {+ match required_i64(row, index)? {+ 0 => Ok(false),+ 1 => Ok(true),+ _ => Err(invariant()),+ }+}+fn claim_is_current(connection: &Arc<Connection>,id: i64,diff --git a/crates/client/cache-turso/src/storage/browser_test.rs b/crates/client/cache-turso/src/storage/browser_test.rsindex cf236c3486..f668e7059d 100644--- a/crates/client/cache-turso/src/storage/browser_test.rs+++ b/crates/client/cache-turso/src/storage/browser_test.rs@@ -10,6 +10,36 @@ fn key(value: &str) -> EntityKey<'static> {EntityKey(value.to_owned().into())}+#[cfg(feature = "browser-test-hooks")]+#[wasm_bindgen_test(async)]+async fn browser_corrupt_queue_hook_preserves_queue_bindings() {+ let owner = OpfsOwner::acquire("cache-turso-browser-corrupt-queue.db")+ .await+ .unwrap()+ .recovery_wipe()+ .await+ .unwrap();+ let OpenResult::Ready(session) = owner.open().await.unwrap() else {+ panic!("recovery wipe must produce a complete fresh pair")+ };+ let mut storage =+ TursoStorage::from_opfs_session(session.connect().unwrap(), "browser-corrupt-queue")+ .unwrap();+ storage.browser_test_corrupt_queue_payload().unwrap();+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Codec)+ );+ let TursoStorageCloseOutcome::ResetRequired(closed) = storage.try_close().unwrap() else {+ panic!("corrupt queue payload must require reset")+ };+ closed.reset().await.unwrap().release().await.unwrap();+}+#[wasm_bindgen_test(async)]async fn runtime_corruption_closes_reset_only_and_replacement_is_empty() {let owner = OpfsOwner::acquire("cache-turso-wp06-runtime-reset.db")diff --git a/crates/client/cache-turso/src/storage/test.rs b/crates/client/cache-turso/src/storage/test.rsindex 4f7ef448e3..3e0a68f73c 100644--- a/crates/client/cache-turso/src/storage/test.rs+++ b/crates/client/cache-turso/src/storage/test.rs@@ -23,6 +23,7 @@ fn record(value: &str) -> Record {fn queued(label: &str) -> NewQueuedMutation {NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation::new(MutationRequest {query: format!("mutation {label} {{ update {{ id }} }}"),@@ -312,7 +313,7 @@ fn queue_diagnostics_use_the_created_at_covering_index_at_scale() {let storage = TursoStorage::open_in_memory("queue-diagnostics-plan").unwrap();raw_execute(&storage,- "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (query, variables_json, created_at_ms) SELECT 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",+ "WITH RECURSIVE values_to_insert(value) AS (VALUES(1) UNION ALL SELECT value + 1 FROM values_to_insert WHERE value < 10000) INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) SELECT printf('00000000-0000-4000-8000-%012d', value), 'mutation Scale { scale }', '{}', 10001 - value FROM values_to_insert",Vec::new(),);let plan = driver::query(@@ -412,6 +413,44 @@ fn fresh_schema_metadata_foreign_keys_quick_check_and_cascade_are_real() {});}+#[test]+fn partial_uuid_index_rejects_two_current_rows_but_allows_superseded_history() {+ block_on(async {+ let mut storage = TursoStorage::open_in_memory("partial-current-uuid-index").unwrap();+ let uuid = uuid::Uuid::new_v4();+ let mut first = queued("First");+ first.uuid = uuid;+ let first_id = storage.enqueue_mutation(first).await.unwrap();++ assert!(+ driver::execute(+ &storage.connection(),+ "INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",+ vec![text(&uuid.to_string()), text("mutation Duplicate { x }"), text("{}"), Value::from_i64(2)],+ )+ .is_err()+ );+ raw_execute(+ &storage,+ "UPDATE mutation_queue SET superseded = 1 WHERE id = ?1",+ vec![Value::from_i64(mutation_id_to_sql(first_id).unwrap())],+ );+ assert_eq!(+ raw_execute(+ &storage,+ "INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",+ vec![+ text(&uuid.to_string()),+ text("mutation Current { x }"),+ text("{}"),+ Value::from_i64(3)+ ],+ ),+ 1+ );+ });+}+#[test]fn enqueue_atomically_replaces_one_effective_shadow_per_key() {block_on(async {@@ -816,6 +855,10 @@ fn every_metadata_mismatch_and_missing_schema_requests_physical_reset() {"queue-diagnostics-index","DROP INDEX mutation_queue_created_at_ms_idx",),+ (+ "queue-current-uuid-index",+ "DROP INDEX mutation_queue_current_uuid_idx",+ ),("search-table", "DROP TABLE search_documents"),("search-index", "DROP INDEX search_documents_browse_idx"),] {@@ -872,6 +915,8 @@ fn semantically_equivalent_schema_formatting_is_accepted_on_reopen() {)"#,r#"create table 'mutation_queue' ('id' integer /* AUTOINCREMENT UNIQUE CHECK COLLATE */ primary key autoincrement,+ "uuid" text not null,+ [superseded] integer default ((0)) not null,"query" text not null,[operation_name] text,`variables_json` text not null,@@ -885,6 +930,7 @@ fn semantically_equivalent_schema_formatting_is_accepted_on_reopen() {"created_at_ms" integer not null)"#,"CREATE INDEX mutation_queue_created_at_ms_idx ON mutation_queue(created_at_ms)",+ "CREATE UNIQUE INDEX mutation_queue_current_uuid_idx ON mutation_queue(uuid) WHERE superseded = 0",r#"create table `optimistic_layers` (`mutation_id` integer primary key,[optimistic_data_json] text not null,@@ -1175,8 +1221,9 @@ fn corrupt_keys_blobs_queue_relationships_and_numerics_request_reset() {let storage = TursoStorage::open_in_memory("missing-layer").unwrap();raw_execute(&storage,- "INSERT INTO mutation_queue (query, variables_json, created_at_ms) VALUES (?1, ?2, ?3)",+ "INSERT INTO mutation_queue (uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",vec![+ text("00000000-0000-4000-8000-000000000001"),text("mutation Missing { x }"),text("{}"),Value::from_i64(0),@@ -1257,14 +1304,36 @@ fn corrupt_keys_blobs_queue_relationships_and_numerics_request_reset() {);}+ for (name, assignment) in [+ ("invalid-uuid", "uuid = 'not-a-uuid'"),+ ("invalid-superseded", "superseded = 2"),+ ] {+ let mut storage = TursoStorage::open_in_memory(name).unwrap();+ let id = storage.enqueue_mutation(queued(name)).await.unwrap();+ raw_execute(+ &storage,+ &format!("UPDATE mutation_queue SET {assignment} WHERE id = ?1"),+ vec![Value::from_i64(mutation_id_to_sql(id).unwrap())],+ );+ assert_eq!(+ storage+ .load_mutation_queue()+ .await+ .unwrap_err()+ .physical_reset_reason(),+ Some(PhysicalResetReason::Invariant)+ );+ }+for invalid_id in [0, -1] {let storage =TursoStorage::open_in_memory(&format!("invalid-id-{invalid_id}")).unwrap();raw_execute(&storage,- "INSERT INTO mutation_queue (id, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4)",+ "INSERT INTO mutation_queue (id, uuid, query, variables_json, created_at_ms) VALUES (?1, ?2, ?3, ?4, ?5)",vec![Value::from_i64(invalid_id),+ text("00000000-0000-4000-8000-000000000002"),text("mutation Invalid { x }"),text("{}"),Value::from_i64(0),@@ -1590,6 +1659,54 @@ fn record_and_projection_patch_roll_back_together_on_storage_fault() {});}+#[test]+fn every_uuid_upsert_fault_rolls_back_queue_layer_and_shadow_changes() {+ block_on(async {+ for fault_index in 0..=3 {+ let mut storage =+ TursoStorage::open_in_memory(&format!("uuid-upsert-fault-{fault_index}")).unwrap();+ let uuid = uuid::Uuid::new_v4();+ let mut first = queued("First");+ first.uuid = uuid;+ storage+ .enqueue_mutation_with_shadow(+ first,+ vec![pending_projection("Thing:1", "user-1", 10)],+ )+ .await+ .unwrap();+ let queue_before = storage.load_mutation_queue().await.unwrap();+ let shadow_before = storage+ .load_optimistic_projections(&[PredicateRecordKey::new("Thing:1").unwrap()])+ .await+ .unwrap();++ let mut replacement = queued("Replacement");+ replacement.uuid = uuid;+ storage.arm_fault(TestFault::After {+ site: TestFaultSite::Enqueue,+ index: fault_index,+ });+ storage+ .enqueue_mutation_with_shadow(+ replacement,+ vec![pending_projection("Thing:1", "user-2", 20)],+ )+ .await+ .unwrap_err();++ assert_eq!(storage.load_mutation_queue().await.unwrap(), queue_before);+ assert_eq!(+ storage+ .load_optimistic_projections(&[PredicateRecordKey::new("Thing:1").unwrap()])+ .await+ .unwrap(),+ shadow_before+ );+ }+ });+}+#[test]fn injected_statement_failures_roll_back_every_storage_boundary() {block_on(async {diff --git a/crates/client/cache-turso/tests/engine_turso.rs b/crates/client/cache-turso/tests/engine_turso.rsindex 5adf243307..93a0dde9b5 100644--- a/crates/client/cache-turso/tests/engine_turso.rs+++ b/crates/client/cache-turso/tests/engine_turso.rs@@ -203,6 +203,7 @@ fn optimistic_hydration_retry_complete_and_reopen_run_over_turso() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000001008",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("doing"),@@ -316,6 +317,7 @@ fn stale_local_head_and_storage_settlement_races_report_stale_claims() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000001009",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("first"),@@ -331,6 +333,7 @@ fn stale_local_head_and_storage_settlement_races_report_stale_claims() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000001010",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("second"),@@ -413,6 +416,7 @@ fn optimistic_discard_restores_durable_base_over_turso() {.begin_optimistic_write(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000001011",query: MUTATION,operation_name: Some("SetEntityProperty"),variables: &mutation_vars("bad"),diff --git a/crates/client/cache-turso/tests/native_file.rs b/crates/client/cache-turso/tests/native_file.rsindex b0743aa0b2..e51c19f2a9 100644--- a/crates/client/cache-turso/tests/native_file.rs+++ b/crates/client/cache-turso/tests/native_file.rs@@ -58,6 +58,7 @@ fn filesystem_database_preserves_the_mutation_queue() {let mut storage = database.open("scope-1").unwrap();let mutation_id = storage.enqueue_mutation(NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation::new(MutationRequest {query: "mutation Persist { persist }".into(),diff --git a/crates/client/cache-turso/tests/predicate.rs b/crates/client/cache-turso/tests/predicate.rsindex 358aefccff..e8ef437dcf 100644--- a/crates/client/cache-turso/tests/predicate.rs+++ b/crates/client/cache-turso/tests/predicate.rs@@ -109,6 +109,7 @@ async fn begin_optimistic_projection(.begin_optimistic_write_with_projections(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000001000",query: r#"mutation SetEntityProperty($input: SetEntityPropertyInput!) {setEntityProperty(input: $input) {@@ -465,6 +466,7 @@ fn turso_rehydrates_and_queries_durable_optimistic_projection_layers() {.begin_optimistic_write_with_projections(None,BeginOptimisticWrite {+ uuid: "00000000-0000-4000-8000-000000001001",query: r#"mutation SetEntityProperty($input: SetEntityPropertyInput!) {setEntityProperty(input: $input) {diff --git a/crates/client/cache-turso/tests/shared_conformance.rs b/crates/client/cache-turso/tests/shared_conformance.rsindex 04a826ce48..21e7668da4 100644--- a/crates/client/cache-turso/tests/shared_conformance.rs+++ b/crates/client/cache-turso/tests/shared_conformance.rs@@ -78,6 +78,7 @@ fn record(value: &str) -> Record {fn queued(label: &str) -> NewQueuedMutation {NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation::new(MutationRequest {query: format!("mutation {label} {{ update {{ id }} }}"),@@ -96,6 +97,7 @@ fn queued(label: &str) -> NewQueuedMutation {fn fully_populated_queued() -> NewQueuedMutation {NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation {request: MutationRequest {query: "mutation Full($id: ID!) { update(id: $id) { id } }".into(),diff --git a/crates/client/cache-turso/tests/storage_conformance.rs b/crates/client/cache-turso/tests/storage_conformance.rsindex 4325c69ef8..593e35a9d6 100644--- a/crates/client/cache-turso/tests/storage_conformance.rs+++ b/crates/client/cache-turso/tests/storage_conformance.rs@@ -28,6 +28,7 @@ fn queued(label: &str, created_at_ms: i64) -> NewQueuedMutation {.fields.insert("value".into(), CacheValue::String(label.into()));NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation {request: MutationRequest {query: format!("mutation {label} {{ update {{ id }} }}"),@@ -50,6 +51,12 @@ fn queued(label: &str, created_at_ms: i64) -> NewQueuedMutation {}}+fn queued_with_uuid(label: &str, created_at_ms: i64, uuid: uuid::Uuid) -> NewQueuedMutation {+ let mut queued = queued(label, created_at_ms);+ queued.uuid = uuid;+ queued+}+fn claim(owner: &str, generation: u64) -> MutationClaimToken {MutationClaimToken {owner: owner.into(),@@ -57,6 +64,63 @@ fn claim(owner: &str, generation: u64) -> MutationClaimToken {}}+#[test]+fn uuid_replacements_survive_reopen_with_pending_and_active_semantics() {+ block_on(async {+ let database = TursoMemoryDatabase::new("uuid-replacements.db");+ let uuid = uuid::Uuid::new_v4();+ let mut storage = database.open("pending").unwrap();+ let first = storage+ .enqueue_mutation(queued_with_uuid("First", 1, uuid))+ .await+ .unwrap();+ let replacement = storage+ .enqueue_mutation(queued_with_uuid("Replacement", 2, uuid))+ .await+ .unwrap();+ assert!(replacement > first);+ assert_eq!(storage.load_mutation_queue().await.unwrap().len(), 1);+ storage.try_close().unwrap();++ let storage = database.open("pending").unwrap();+ let queue = storage.load_mutation_queue().await.unwrap();+ assert_eq!(queue.len(), 1);+ assert_eq!(queue[0].id, replacement);+ assert_eq!(queue[0].uuid, uuid);+ storage.try_close().unwrap();++ database.physical_reset();+ let mut storage = database.open("active").unwrap();+ let active = storage+ .enqueue_mutation(queued_with_uuid("Active", 10, uuid))+ .await+ .unwrap();+ let claimed = storage+ .claim_next_mutation(MutationClaimRequest {+ owner: "runner".into(),+ now_ms: 10,+ lease_expires_at_ms: 100,+ })+ .await+ .unwrap()+ .unwrap();+ assert_eq!(claimed.queued.id, active);+ let replacement = storage+ .enqueue_mutation(queued_with_uuid("Latest", 11, uuid))+ .await+ .unwrap();+ storage.try_close().unwrap();++ let storage = database.open("active").unwrap();+ let queue = storage.load_mutation_queue().await.unwrap();+ assert_eq!(queue.len(), 2);+ assert_eq!(queue[0].id, active);+ assert!(queue[0].superseded);+ assert_eq!(queue[1].id, replacement);+ assert!(!queue[1].superseded);+ });+}+#[test]fn compound_keys_batches_duplicates_and_checked_inputs_conform() {block_on(async {@@ -141,6 +205,7 @@ fn queue_preserves_every_field_order_and_reopen_state() {first_entry.mutation.lease_owner = Some("reopen-owner".into());first_entry.mutation.lease_expires_at_ms = Some(175);let second_entry = NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation::new(MutationRequest {query: "mutation Second { update { id } }".into(),diff --git a/crates/client/cache-turso/tests/web.rs b/crates/client/cache-turso/tests/web.rsindex 341cc6556f..f1b955fec7 100644--- a/crates/client/cache-turso/tests/web.rs+++ b/crates/client/cache-turso/tests/web.rs@@ -34,6 +34,7 @@ fn healthy_close(outcome: TursoStorageCloseOutcome) -> HealthyTursoStorageClosedfn queued() -> NewQueuedMutation {NewQueuedMutation {+ uuid: uuid::Uuid::new_v4(),mutation: StoredMutation::new(MutationRequest {query: "mutation Browser { update { id } }".into(),diff --git a/crates/client/cache-wasm/Cargo.toml b/crates/client/cache-wasm/Cargo.tomlindex 5b3862a282..5af6db50bb 100644--- a/crates/client/cache-wasm/Cargo.toml+++ b/crates/client/cache-wasm/Cargo.toml@@ -2,7 +2,7 @@edition = "2024"name = "cache-wasm"publish = false-version = "0.6.3"+version = "0.6.4"[features]default = []diff --git a/crates/client/cache-wasm/src/shell.rs b/crates/client/cache-wasm/src/shell.rsindex e169844791..9907d24299 100644--- a/crates/client/cache-wasm/src/shell.rs+++ b/crates/client/cache-wasm/src/shell.rs@@ -2,14 +2,17 @@ use async_lock::Mutex;use cache_core::codec::cache_database_name;use cache_core::deps::OpId;use cache_core::engine::{- BeginOptimisticWrite, Engine, EngineError, InitialClaimOutcome, NetworkWrite,- QueryRegistration, ReadResult, WriteResult,+ BeginOptimisticWrite, CommitOptimisticWriteResult, DeferOptimisticWriteResult, Engine,+ EngineError, InitialClaimOutcome, NetworkWrite, QueryRegistration, ReadResult,+ RollbackOptimisticWriteResult, WriteResult,};use cache_core::entity_resolver::EntityResolver;use cache_core::link_patch::{OptimisticLinkPatch, QueryRevalidation};use cache_core::predicate::PredicateQueryResult;use cache_core::query_inspection::QueryInspection;-use cache_core::queue::{ClaimedMutation, MutationClaimRequest, MutationClaimToken};+use cache_core::queue::{+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationUpsertKind,+};use cache_core::record_selection::RecordSelection;use cache_core::search::SearchRequest;use cache_core::store::QueueDiagnosticsAvailability;@@ -167,6 +170,7 @@ struct JsInspectionPathSegment {#[serde(rename_all = "camelCase")]struct JsEnqueueOptimisticMutationResult {transaction_id: String,+ upsert_kind: JsMutationUpsertKind,revision: String,changed: Vec<String>,affected_ops: Vec<String>,@@ -175,6 +179,32 @@ struct JsEnqueueOptimisticMutationResult {initial_claim: JsInitialMutationClaim,}+#[derive(Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+enum JsMutationUpsertKind {+ Inserted,+ ReplacedPending { removed_transaction_id: String },+ AppendedAfterActive { active_transaction_id: String },+}++impl From<MutationUpsertKind> for JsMutationUpsertKind {+ fn from(kind: MutationUpsertKind) -> Self {+ match kind {+ MutationUpsertKind::Inserted => Self::Inserted,+ MutationUpsertKind::ReplacedPending { removed_id } => Self::ReplacedPending {+ removed_transaction_id: removed_id.to_string(),+ },+ MutationUpsertKind::AppendedAfterActive { active_id } => Self::AppendedAfterActive {+ active_transaction_id: active_id.to_string(),+ },+ }+ }+}+#[derive(Serialize)]#[serde(tag = "kind", rename_all = "kebab-case")]enum JsInitialMutationClaim {@@ -187,6 +217,8 @@ enum JsInitialMutationClaim {#[serde(rename_all = "camelCase")]struct JsClaimedMutation {transaction_id: String,+ uuid: String,+ superseded: bool,lease_generation: String,query: String,operation_name: Option<String>,@@ -202,6 +234,8 @@ impl TryFrom<ClaimedMutation> for JsClaimedMutation {let request = claimed.queued.mutation.request;Ok(Self {transaction_id: claimed.queued.id.to_string(),+ uuid: claimed.queued.uuid.to_string(),+ superseded: claimed.queued.superseded,lease_generation: claimed.lease_generation.to_string(),query: request.query,operation_name: request.operation_name,@@ -301,6 +335,57 @@ struct JsRevisionResult {revision: String,}+#[derive(Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+enum JsDeferOptimisticWriteResult {+ Deferred,+ DiscardedSuperseded {+ replacement_transaction_id: String,+ #[serde(flatten)]+ result: JsWriteResult,+ },+}++#[derive(Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+enum JsCommitOptimisticWriteResult {+ Committed {+ #[serde(flatten)]+ result: JsWriteResult,+ },+ CommittedSuperseded {+ replacement_transaction_id: String,+ #[serde(flatten)]+ result: JsWriteResult,+ },+}++#[derive(Serialize)]+#[serde(+ tag = "kind",+ rename_all = "kebab-case",+ rename_all_fields = "camelCase"+)]+enum JsRollbackOptimisticWriteResult {+ RolledBack {+ #[serde(flatten)]+ result: JsWriteResult,+ },+ DiscardedSuperseded {+ replacement_transaction_id: String,+ #[serde(flatten)]+ result: JsWriteResult,+ },+}+fn js_write_result(result: WriteResult, ops: &OpInterner) -> JsWriteResult {JsWriteResult {revision: result.revision.to_string(),@@ -1050,6 +1135,7 @@ impl CacheEngine {pub fn enqueue_optimistic_mutation(&self,origin_op_id: Option<String>,+ uuid: String,query: String,operation_name: Option<String>,variables: JsValue,@@ -1086,6 +1172,7 @@ impl CacheEngine {.enqueue_optimistic_mutation_with_projections(origin,BeginOptimisticWrite {+ uuid: &uuid,query: &query,operation_name: operation_name.as_deref(),variables: &vars,@@ -1113,6 +1200,7 @@ impl CacheEngine {};to_js(&JsEnqueueOptimisticMutationResult {transaction_id: result.transaction_id.to_string(),+ upsert_kind: result.upsert_kind.into(),revision: result.write_result.revision.to_string(),changed: result.write_result@@ -1208,6 +1296,7 @@ impl CacheEngine {error: String,) -> js_sys::Promise {let state = self.state.clone();+ let ops = self.ops.clone();future_to_promise(async move {let mut state = state.lock().await;state.ensure_callable()?;@@ -1221,8 +1310,17 @@ impl CacheEngine {.engine_mut()?.defer_optimistic_write(transaction, claim, next_attempt_at_ms, error).await;- state.engine_result(result)?;- Ok(JsValue::UNDEFINED)+ let result = state.engine_result(result)?;+ let result = match result {+ DeferOptimisticWriteResult::Deferred => JsDeferOptimisticWriteResult::Deferred,+ DeferOptimisticWriteResult::DiscardedSuperseded(result) => {+ JsDeferOptimisticWriteResult::DiscardedSuperseded {+ replacement_transaction_id: result.replacement_transaction_id.to_string(),+ result: js_write_result(result.write_result, &ops.borrow()),+ }+ }+ };+ to_js(&result)})}@@ -1257,7 +1355,7 @@ impl CacheEngine {.map_err(err_js)?;let result = state.engine_mut()?- .commit_optimistic_write_with_projections(+ .commit_optimistic_write_with_projections_outcome(transaction,claim,&query,@@ -1267,8 +1365,20 @@ impl CacheEngine {projections,).await;- let result = state.engine_result(result)?;- to_js(&js_write_result(result, &ops.borrow()))+ let result = match state.engine_result(result)? {+ CommitOptimisticWriteResult::Committed(result) => {+ JsCommitOptimisticWriteResult::Committed {+ result: js_write_result(result, &ops.borrow()),+ }+ }+ CommitOptimisticWriteResult::CommittedSuperseded(result) => {+ JsCommitOptimisticWriteResult::CommittedSuperseded {+ replacement_transaction_id: result.replacement_transaction_id.to_string(),+ result: js_write_result(result.write_result, &ops.borrow()),+ }+ }+ };+ to_js(&result)})}@@ -1293,10 +1403,22 @@ impl CacheEngine {};let result = state.engine_mut()?- .rollback_optimistic_write(transaction, claim)+ .rollback_optimistic_write_with_outcome(transaction, claim).await;- let result = state.engine_result(result)?;- to_js(&js_write_result(result, &ops.borrow()))+ let result = match state.engine_result(result)? {+ RollbackOptimisticWriteResult::RolledBack(result) => {+ JsRollbackOptimisticWriteResult::RolledBack {+ result: js_write_result(result, &ops.borrow()),+ }+ }+ RollbackOptimisticWriteResult::DiscardedSuperseded(result) => {+ JsRollbackOptimisticWriteResult::DiscardedSuperseded {+ replacement_transaction_id: result.replacement_transaction_id.to_string(),+ result: js_write_result(result.write_result, &ops.borrow()),+ }+ }+ };+ to_js(&result)})}diff --git a/crates/client/cache-wasm/src/shell/test.rs b/crates/client/cache-wasm/src/shell/test.rsindex 6c5e565345..93c5b5285a 100644--- a/crates/client/cache-wasm/src/shell/test.rs+++ b/crates/client/cache-wasm/src/shell/test.rs@@ -181,6 +181,58 @@ async fn resolved(promise: js_sys::Promise) -> JsValue {JsFuture::from(promise).await.expect("promise resolves")}+fn empty_js_write_result() -> JsWriteResult {+ JsWriteResult {+ revision: "0".to_string(),+ changed: Vec::new(),+ affected_ops: Vec::new(),+ reset: false,+ revalidations: Vec::new(),+ }+}++#[wasm_bindgen_test]+fn tagged_wire_enum_fields_are_camel_case() {+ assert_eq!(+ serde_json::to_value(JsMutationUpsertKind::ReplacedPending {+ removed_transaction_id: "1".to_string(),+ })+ .unwrap(),+ serde_json::json!({"kind": "replaced-pending", "removedTransactionId": "1"})+ );+ assert_eq!(+ serde_json::to_value(JsMutationUpsertKind::AppendedAfterActive {+ active_transaction_id: "2".to_string(),+ })+ .unwrap(),+ serde_json::json!({"kind": "appended-after-active", "activeTransactionId": "2"})+ );+ assert_eq!(+ serde_json::to_value(JsDeferOptimisticWriteResult::DiscardedSuperseded {+ replacement_transaction_id: "3".to_string(),+ result: empty_js_write_result(),+ })+ .unwrap()["replacementTransactionId"],+ "3"+ );+ assert_eq!(+ serde_json::to_value(JsCommitOptimisticWriteResult::CommittedSuperseded {+ replacement_transaction_id: "4".to_string(),+ result: empty_js_write_result(),+ })+ .unwrap()["replacementTransactionId"],+ "4"+ );+ assert_eq!(+ serde_json::to_value(JsRollbackOptimisticWriteResult::DiscardedSuperseded {+ replacement_transaction_id: "5".to_string(),+ result: empty_js_write_result(),+ })+ .unwrap()["replacementTransactionId"],+ "5"+ );+}+async fn assert_closed(promise: js_sys::Promise) {let error = JsFuture::from(promise).await@@ -959,6 +1011,7 @@ async fn optimistic_v2_patch_is_filterable_after_enqueue_reopen_and_rollback() {let enqueue: serde_json::Value = from_js(resolved(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000001".into(),OPTIMISTIC_DOCUMENT_MUTATION.into(),Some("RenameEntities".into()),js(serde_json::json!({@@ -1089,6 +1142,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {let first: serde_json::Value = from_js(resolved(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000002".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),@@ -1109,6 +1163,7 @@ async fn queue_and_optimistic_layers_survive_preserve_reopen_in_id_order() {let second: serde_json::Value = from_js(resolved(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000003".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),@@ -1211,6 +1266,7 @@ async fn optimistic_commit_reports_affected_ops_and_rejects_settled_or_malformedlet enqueue: serde_json::Value = from_js(resolved(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000004".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),@@ -1308,6 +1364,7 @@ async fn destroy_recovery_wipes_records_and_queue() {.await;resolved(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000005".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),@@ -1523,6 +1580,7 @@ async fn storage_reset_errors_latch_and_block_hot_read_write_and_control_methods.await;assert_reset_required(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000006".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),@@ -1572,6 +1630,7 @@ async fn physical_reset_serializes_recreates_and_preserves_interner_registration.expect("operation is interned before reset");resolved(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000007".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),@@ -1690,6 +1749,7 @@ async fn every_method_rejects_after_consuming_close() {.await;assert_closed(engine.enqueue_optimistic_mutation(None,+ "00000000-0000-4000-8000-000000000008".into(),PROPERTY_MUTATION.into(),Some("SetEntityProperty".into()),js(mutation_variables()),diff --git a/crates/client/cache-wasm/src/shell/test_storage.rs b/crates/client/cache-wasm/src/shell/test_storage.rsindex 1ac420b28f..3209a54ba1 100644--- a/crates/client/cache-wasm/src/shell/test_storage.rs+++ b/crates/client/cache-wasm/src/shell/test_storage.rs@@ -1,18 +1,16 @@use cache_core::predicate::{- OptimisticShadowReconciliation, PredicateIndexStorage, PredicateQueryResult,- ProjectionMutation, ProjectionState,+ OptimisticShadowReconciliation, OptimisticUpsertReconciliation, PredicateIndexStorage,+ PredicateQueryResult, ProjectionMutation, ProjectionState,};use cache_core::queue::{- ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, NewQueuedMutation,- QueuedMutation,+ ClaimedMutation, MutationClaimRequest, MutationClaimToken, MutationId, MutationUpsertResult,+ NewQueuedMutation, QueuedMutation,};use cache_core::search::{SearchCursor, SearchDocument, SearchProfile};use cache_core::store::{QueueDiagnostics, Storage};use cache_core::value::{EntityKey, Record};use cache_turso::{PhysicalResetReason, TursoStorage, TursoStorageError};-use predicate_index::{- EffectiveOptimisticProjection, PendingOptimisticProjection, RecordKey, ValidatedIndexQuery,-};+use predicate_index::{EffectiveOptimisticProjection, RecordKey, ValidatedIndexQuery};use std::sync::atomic::{AtomicU8, Ordering};#[derive(Clone, Copy)]@@ -105,13 +103,14 @@ impl Storage for BrowserStorage {.await}- async fn enqueue_mutation_with_shadow(+ async fn upsert_mutation_with_shadow(&mut self,entry: NewQueuedMutation,- projections: Vec<PendingOptimisticProjection>,- ) -> Result<MutationId, Self::Error> {+ now_ms: i64,+ reconciliation: OptimisticUpsertReconciliation,+ ) -> Result<MutationUpsertResult, Self::Error> {self.inner- .enqueue_mutation_with_shadow(entry, projections)+ .upsert_mutation_with_shadow(entry, now_ms, reconciliation).await}