@multiplatform.one/frappe 6.4.3 → 6.6.0

package/src/frappeReactLiveQueryGc.spec.ts

@@ -281,7 +281,7 @@ describe("shared collection GC vs real live queries", () => {
     expect(liveQueryErrors()).toHaveLength(0);
   });
 
-  it("force window: a leaked query cannot pin the collection forever, and a fresh mount recovers", async () => {
+  it("force window: a leaked query releases the sync WITHOUT erroring, and a fresh mount recovers", async () => {
     const config = configFor("leak");
     const hook = renderHook(() => useFrappeCollection<WorkspaceDoc>(config, "Workspace"));
     await flushMicrotasks();
@@ -290,18 +290,29 @@ describe("shared collection GC vs real live queries", () => {
     // A leaked query: created (sync started, source subscribed) but never
     // given a subscriber — the shape a discarded render leaves behind.
     // TanStack DB never arms its GC for it, so only the force window frees
-    // the source collection.
-    createLiveQueryCollection({
+    // the sync resources.
+    const leakedQuery = createLiveQueryCollection({
       query: (q) => q.from({ workspace: collection }),
       startSync: true,
       gcTime: 300_000,
     });
     await flushMicrotasks();
     expect(collection.subscriberCount).toBeGreaterThan(0);
+    const unsubscribesBefore = mockUnsubscribe.mock.calls.length;
 
     hook.unmount();
     await advanceTime(FORCE_WAIT_MS);
-    expect(collection.status).toBe("cleaned-up");
+    // The regression this pins: the force window used to call cleanup() on
+    // the pinned collection, permanently erroring every attached query with
+    // "[Live Query Error] Source collection 'Workspace' was manually cleaned
+    // up while live query … depends on it" (7× in the console sweep).
+    // Now the SyncModule subscription is released externally instead: the
+    // collection is never transitioned to cleaned-up, the leaked query
+    // never errors, and no console error is emitted.
+    expect(mockUnsubscribe.mock.calls.length).toBeGreaterThan(unsubscribesBefore);
+    expect(collection.status).not.toBe("cleaned-up");
+    expect(leakedQuery.status).not.toBe("error");
+    expect(liveQueryErrors()).toHaveLength(0);
 
     // A consumer mounting afterwards gets a FRESH working collection — a new
     // live query over it loads and reaches ready.
@@ -316,5 +327,34 @@ describe("shared collection GC vs real live queries", () => {
     expect(fresh.result.current!.status).toBe("ready");
     expect(freshQuery.status).toBe("ready");
     expect(freshQuery.toArray).toHaveLength(2);
+    expect(liveQueryErrors()).toHaveLength(0);
+  });
+
+  it("errored entry: idle cleanup with a leaked query attached releases sync without erroring", async () => {
+    // The production path from the console sweep: initial sync fails (401),
+    // consumers unmount (error screen), the errored entry is evicted through
+    // cleanupEntryCollectionWhenIdle — which, past the force window, used to
+    // cleanup() the collection while leaked queries were still attached.
+    const config = configFor("error");
+    mockSubscribe.mockRejectedValueOnce(new Error("AuthenticationError"));
+
+    const hook = renderHook(() => useFrappeCollection<WorkspaceDoc>(config, "Workspace"));
+    await flushMicrotasks();
+    const collection = hook.result.current!;
+
+    const leakedQuery = createLiveQueryCollection({
+      query: (q) => q.from({ workspace: collection }),
+      startSync: true,
+      gcTime: 300_000,
+    });
+    await flushMicrotasks();
+    expect(collection.subscriberCount).toBeGreaterThan(0);
+
+    hook.unmount();
+    await advanceTime(FORCE_WAIT_MS);
+
+    expect(collection.status).not.toBe("cleaned-up");
+    expect(leakedQuery.status).not.toBe("error");
+    expect(liveQueryErrors()).toHaveLength(0);
   });
 });

package/src/sync/index.ts

@@ -226,7 +226,16 @@ export class SyncModule {
   }
 
   async mutate(mutation: Mutation<FrappeDocData>) {
-    await this.mutationEngine.mutate(mutation);
+    try {
+      await this.mutationEngine.mutate(mutation);
+    } catch (err) {
+      // The failure path rolled back optimistic state (e.g. a rejected
+      // create's temp row was evicted) — store listeners must see that
+      // rollback too, or consumers that mirrored the optimistic membership
+      // keep rendering a ghost row the engine already dropped.
+      this.emit();
+      throw err;
+    }
     // Broadcast mutation to other tabs for cross-tab sync
     this.persistenceManager.broadcastMutation(mutation);
     this.emit();

package/src/sync/mutationEngine.ts

@@ -147,10 +147,22 @@ export class MutationEngine {
           if (result.data) {
             this.normalizedCache.upsert(result.data);
 
-            // Handle temp ID mapping for creates
-            if (mutation.operation === Operation.Create && mutation.doc.name !== result.data.name) {
-              this.temporaryIdToRealNameMap.set(mutation.doc.name!, result.data.name);
-              this.rehydrationManager.registerTempIdMapping(mutation.doc.name!, result.data.name);
+            // Reconcile optimistic identity for creates — the full remap
+            // (subscription membership + temp cache row eviction), not just
+            // the id maps, or the optimistic row lingers beside the server
+            // row exactly like the non-batched path used to.
+            if (mutation.operation === Operation.Create) {
+              const temporaryName = mutation.temporaryName ?? mutation.doc.name;
+              if (temporaryName && result.data.name && temporaryName !== result.data.name) {
+                this.handleTemporaryToRealMapping(
+                  mutation.doc.doctype,
+                  temporaryName,
+                  result.data.name,
+                );
+                this.rehydrationManager.registerTempIdMapping(temporaryName, result.data.name);
+              } else if (temporaryName) {
+                this.globalOptimisticDocIds.get(mutation.doc.doctype)?.delete(temporaryName);
+              }
             }
           }
 
@@ -244,7 +256,11 @@ export class MutationEngine {
           : mutation.doc;
     this.mutationJournal.add(mutation.mutationId, {
       doctype: doc.doctype,
-      docname: doc.name,
+      // Creates journal the optimistic identity (consumer placeholder or
+      // engine-generated temp id) so page refreshes keep the pending row
+      // and rollback can evict it even when doc.name was never set.
+      docname:
+        mutation.operation === Operation.Create ? (mutation.temporaryName ?? doc.name) : doc.name,
       values,
       operation: mutation.operation,
       version,
@@ -318,6 +334,11 @@ export class MutationEngine {
 
   private async handleOptimisticCreate<Data extends FrappeDocData>(mutation: CreateMutation<Data>) {
     const temporaryName = mutation.doc.name || `tmp_${cryptoRandomId()}`;
+    // Record the optimistic identity on the mutation itself: the server-ack
+    // remap, rollback, and journal paths must all resolve the SAME name.
+    // For engine-generated names, mutation.doc.name stays unset so the
+    // synthetic id is never sent to the server.
+    mutation.temporaryName = temporaryName;
     const optimisticDoc = {
       ...mutation.doc,
       name: temporaryName,
@@ -370,11 +391,27 @@ export class MutationEngine {
   }
 
   private async handleServerCreate<Data extends FrappeDocData>(mutation: CreateMutation<Data>) {
-    const created = await this.db.createDoc<FrappeDoc<Data>>(mutation.doc);
+    // Idempotency-Key rides the first attempt (not just replays) so an
+    // HTTP-level retry after a lost response replays the recorded outcome
+    // instead of double-inserting (live-protocol FRAPPE-EXT-001).
+    const created = await this.db.createDoc<FrappeDoc<Data>>({
+      ...mutation.doc,
+      client_mutation_id: mutation.mutationId,
+    });
     // Authoritative name assigned by the backend (may equal the provided temp name)
     const realName = created?.name;
     // The client-synthesized or user-provided temporary name used during optimism
-    const temporaryName = mutation.doc.name;
+    const temporaryName = mutation.temporaryName ?? mutation.doc.name;
+    // The ack payload IS the authoritative post-insert document (same user
+    // context as any refetch) — seed the cache unconditionally so remapped
+    // membership resolves immediately instead of waiting for the realtime
+    // echo (which used to leave the row blank until the socket delivered).
+    if (realName) {
+      this.normalizedCache.upsert({
+        ...created,
+        doctype: created.doctype || mutation.doc.doctype,
+      });
+    }
     // If backend assigned a different name, remap temporary → real across subscriptions.
     if (realName && temporaryName && realName !== temporaryName) {
       this.handleTemporaryToRealMapping(mutation.doc.doctype, temporaryName, realName);
@@ -387,10 +424,6 @@ export class MutationEngine {
         globalDocs.delete(temporaryName);
       }
     }
-    // When realtime is unhealthy, seed cache with authoritative document.
-    if (!this.realtime?.isHealthy()) {
-      this.normalizedCache.upsert(created);
-    }
   }
 
   private async handleServerUpdate<Data extends FrappeDocData>(
@@ -433,10 +466,16 @@ export class MutationEngine {
       globalDocs.delete(temporaryName);
       // Real name is no longer optimistic, so we don't add it back
     }
-    // replace in subscriptions
+    // Replace in subscriptions. When the realtime event / CDC backfill /
+    // page-refresh reconcile already delivered the server row (the ack lost
+    // the race), a plain map would leave the same name twice — drop the
+    // temporary id instead so exactly one row remains.
     for (const subscription of this.subscriptionManager.getAllSubscriptions().values()) {
       if (subscription.query.doctype !== doctype) continue;
-      subscription.docIds = subscription.docIds.map((x) => (x === temporaryName ? realName : x));
+      if (!subscription.docIds.includes(temporaryName)) continue;
+      subscription.docIds = subscription.docIds.includes(realName)
+        ? subscription.docIds.filter((id) => id !== temporaryName)
+        : subscription.docIds.map((id) => (id === temporaryName ? realName : id));
     }
     // Remove the temporary cached row now that the authoritative name exists
     this.normalizedCache.remove({ doctype, name: temporaryName });
@@ -450,7 +489,12 @@ export class MutationEngine {
     const realName = (docname && this.temporaryIdToRealNameMap.get(docname)) || docname;
     // A deleted doc no longer exists server-side — refetching it would 404
     // and route a server-confirmed delete into the error/rollback path.
-    if (realName && mutation.operation !== Operation.Delete) {
+    // A created doc is the insert-side sibling of the same bug: its cache
+    // copy was already seeded from the authoritative ack response, and
+    // refetching the pre-remap temporary name is a guaranteed 404 that used
+    // to roll back a server-confirmed create. Only updates refetch the
+    // main document here.
+    if (realName && mutation.operation === Operation.Update) {
       targets.push({ doctype, name: realName });
     }
     if (mutation.affected?.length) targets.push(...mutation.affected);
@@ -503,11 +547,9 @@ export class MutationEngine {
     switch (mutation.operation) {
       case Operation.Create:
         // Remove temporary optimistic document from cache and subscriptions
+        // (handleFailedCreate resolves the optimistic identity — consumer
+        // placeholder or engine-generated temp id — and evicts both).
         await this.handleFailedCreate(mutation);
-        // Also remove from cache
-        if (docname) {
-          this.normalizedCache.remove({ doctype, name: docname });
-        }
         break;
 
       case Operation.Update:
@@ -541,7 +583,10 @@ export class MutationEngine {
   }
 
   private async handleFailedCreate<Data extends FrappeDocData>(mutation: Mutation<Data>) {
-    const temporaryName = mutation.doc.name;
+    const temporaryName =
+      mutation.operation === Operation.Create
+        ? (mutation.temporaryName ?? mutation.doc.name)
+        : mutation.doc.name;
     const doctype = mutation.doc.doctype;
 
     if (temporaryName) {
@@ -555,6 +600,9 @@ export class MutationEngine {
         if (subscription.query.doctype !== doctype) continue;
         subscription.docIds = subscription.docIds.filter((id) => id !== temporaryName);
       }
+      // Evict the optimistic cache row (generated temp ids never lived in
+      // mutation.doc.name, so keying off the resolved name matters here).
+      this.normalizedCache.remove({ doctype, name: temporaryName });
     }
   }
 
@@ -788,12 +836,25 @@ export class MutationEngine {
       }
       try {
         if (entry.operation === Operation.Create) {
-          await this.db.createDoc({
+          const created = await this.db.createDoc({
             ...entry.values,
             client_mutation_id: id,
             doctype: entry.doctype,
             name: entry.docname || cryptoRandomId(),
           });
+          // A replayed create acks with the authoritative document (possibly
+          // an idempotent replay of an earlier success) — reconcile the
+          // optimistic identity exactly like the first attempt.
+          if (created?.name) {
+            this.normalizedCache.upsert({
+              ...created,
+              doctype: created.doctype || entry.doctype,
+            });
+            if (entry.docname && created.name !== entry.docname) {
+              this.handleTemporaryToRealMapping(entry.doctype, entry.docname, created.name);
+              this.rehydrationManager.registerTempIdMapping(entry.docname, created.name);
+            }
+          }
         } else if (entry.operation === Operation.Update && entry.docname) {
           await this.db.updateDoc({
             ...entry.values,

package/src/sync/optimisticCreateReconcile.spec.ts

@@ -0,0 +1,372 @@
+/**
+ * Optimistic create → server row identity reconciliation.
+ *
+ * Regression suite for the "optimistic insert row lingers beside the realtime
+ * server row" bug (p-results/fix-backoffice-resilience.md gap 3 known limit):
+ * the live wire wraps whitelisted method returns as `{message: {...doc}}`, so
+ * `createDoc().name` was undefined and the temporary→real remap never ran —
+ * the temp row stayed in membership forever, the realtime row was inserted
+ * alongside (2 UI rows / 1 server doc), the temp row's mutations 404'd, and
+ * with realtime unhealthy the post-create refetch of the temp name 404'd and
+ * rolled back a server-confirmed create (the insert-side sibling of the
+ * delete-refetch rollback bug).
+ *
+ * These specs run the REAL engine stack — SubscriptionManager,
+ * NormalizedCache, MutationJournal, RehydrationManager, RealtimeHandler,
+ * MutationEngine — over a scripted DbModule, so the ack/realtime race is
+ * exercised end-to-end in both orders (subscriptionManager.spec.ts pattern:
+ * real internals, mocked db).
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+import type { DbModule } from "../db";
+import type { RealtimeModule } from "../realtime";
+import { MutationEngine } from "./mutationEngine";
+import { MutationJournal } from "./mutationJournal";
+import { NormalizedCache } from "./normalizedCache";
+import { RealtimeHandler } from "./realtime";
+import { RehydrationManager } from "./rehydration";
+import { SubscriptionManager } from "./subscriptionManager";
+import { Operation } from "./types";
+import type { CreateMutation } from "./types";
+
+type Doc = FrappeDoc<FrappeDocData>;
+
+interface Harness {
+  engine: MutationEngine;
+  subscriptionManager: SubscriptionManager;
+  cache: NormalizedCache;
+  journal: MutationJournal;
+  db: {
+    getDoc: ReturnType<typeof vi.fn>;
+    getDocList: ReturnType<typeof vi.fn>;
+    createDoc: ReturnType<typeof vi.fn>;
+    updateDoc: ReturnType<typeof vi.fn>;
+    deleteDoc: ReturnType<typeof vi.fn>;
+    backfill: ReturnType<typeof vi.fn>;
+  };
+  /** Server-side rows the mocked db serves (list + getDoc). */
+  serverRows: Doc[];
+  /** Fires a realtime list_update the way the socket would. */
+  emitListUpdate: (name: string) => Promise<void>;
+  realtimeHealthy: { value: boolean };
+  dispose: () => void;
+}
+
+function createHarness(): Harness {
+  const serverRows: Doc[] = [];
+  const realtimeHealthy = { value: true };
+
+  const db = {
+    getDoc: vi.fn(async (doctype: string, name: string) => {
+      const row = serverRows.find((doc) => doc.doctype === doctype && doc.name === name);
+      if (!row) {
+        const error = new Error(`${doctype}/${name} not found`) as Error & { status: number };
+        error.status = 404;
+        throw error;
+      }
+      return { ...row };
+    }),
+    getDocList: vi.fn(async (doctype: string) =>
+      serverRows.filter((doc) => doc.doctype === doctype).map((doc) => ({ ...doc })),
+    ),
+    createDoc: vi.fn(),
+    updateDoc: vi.fn(),
+    deleteDoc: vi.fn(),
+    backfill: vi.fn(async () => ({ rows: [], checkpoint: undefined })),
+  };
+
+  const realtimeHandlers = new Map<string, (payload: unknown) => Promise<void> | void>();
+  const realtime = {
+    isHealthy: () => realtimeHealthy.value,
+    on: (event: string, handler: (payload: unknown) => Promise<void> | void) => {
+      realtimeHandlers.set(event, handler);
+    },
+    subscribeList: vi.fn(),
+    unsubscribeList: vi.fn(),
+    disconnect: vi.fn(),
+  } as unknown as RealtimeModule;
+
+  const cache = new NormalizedCache({});
+  const journal = new MutationJournal({ enableAutoCleanup: false });
+  const subscriptionManager = new SubscriptionManager(db as unknown as DbModule, cache, {});
+  const rehydrationManager = new RehydrationManager(
+    db as unknown as DbModule,
+    cache,
+    subscriptionManager,
+    journal,
+  );
+  const engine = new MutationEngine(
+    db as unknown as DbModule,
+    realtime,
+    cache,
+    journal,
+    subscriptionManager,
+    rehydrationManager,
+    {},
+  );
+  const realtimeHandler = new RealtimeHandler(
+    db as unknown as DbModule,
+    realtime,
+    cache,
+    subscriptionManager,
+    rehydrationManager,
+    {},
+  );
+
+  return {
+    engine,
+    subscriptionManager,
+    cache,
+    journal,
+    db,
+    serverRows,
+    emitListUpdate: async (name: string) => {
+      await realtimeHandlers.get("list_update")?.({ doctype: "TestDoc", name });
+    },
+    realtimeHealthy,
+    dispose: () => {
+      engine.dispose();
+      realtimeHandler.dispose();
+      rehydrationManager.clear();
+      journal.dispose();
+    },
+  };
+}
+
+const serverDoc = (name: string): Doc => ({
+  doctype: "TestDoc",
+  name,
+  title: "Created",
+  modified: "2024-01-01T10:00:00",
+});
+
+const createMutation = (
+  doc: Partial<Doc>,
+  mutationId = "create-1",
+): CreateMutation<FrappeDocData> => ({
+  mutationId,
+  operation: Operation.Create,
+  doc: { doctype: "TestDoc", ...doc } as Doc,
+  affected: [],
+});
+
+describe("optimistic create reconciliation (engine-level)", () => {
+  let harness: Harness;
+  let subscriptionId: string;
+
+  const rowNames = () =>
+    harness.subscriptionManager.getDocsForSubscription(subscriptionId).map((doc) => doc.name);
+  const docIds = () => [
+    ...(harness.subscriptionManager.getSubscription(subscriptionId)?.docIds ?? []),
+  ];
+
+  beforeEach(async () => {
+    vi.useFakeTimers();
+    harness = createHarness();
+    const result = await harness.subscriptionManager.subscribe({
+      doctype: "TestDoc",
+      fields: ["name", "title", "modified"],
+    });
+    subscriptionId = result.subscriptionId;
+  });
+
+  afterEach(() => {
+    harness.dispose();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  it("server ack reconciles the optimistic row to a single server-named row", async () => {
+    harness.db.createDoc.mockImplementation(async () => {
+      harness.serverRows.push(serverDoc("real-1"));
+      return serverDoc("real-1");
+    });
+
+    const mutation = createMutation({ name: "new-todo-placeholder" });
+    const mutatePromise = harness.engine.mutate(mutation);
+
+    // Optimistic state: the placeholder row is live immediately.
+    expect(docIds()).toEqual(["new-todo-placeholder"]);
+    expect(rowNames()).toEqual(["new-todo-placeholder"]);
+
+    await mutatePromise;
+
+    // Ack reconciled identity: exactly one row, under the server name, and
+    // the row resolves from the cache (the ack payload seeded it — no wait
+    // for the realtime echo).
+    expect(docIds()).toEqual(["real-1"]);
+    expect(rowNames()).toEqual(["real-1"]);
+    expect(harness.cache.get({ doctype: "TestDoc", name: "new-todo-placeholder" })).toBeUndefined();
+    expect(harness.engine.getTemporaryIdToRealNameMap().get("new-todo-placeholder")).toBe("real-1");
+
+    // The idempotency machinery rides the first attempt.
+    expect(harness.db.createDoc).toHaveBeenCalledWith(
+      expect.objectContaining({ client_mutation_id: "create-1" }),
+    );
+  });
+
+  it("reconciles when the realtime insert arrives BEFORE the REST ack", async () => {
+    let resolveAck: (doc: Doc) => void = () => {};
+    harness.db.createDoc.mockImplementation(() => {
+      // Server commits immediately (realtime will observe the row); only the
+      // HTTP response is still in flight.
+      harness.serverRows.push(serverDoc("real-2"));
+      return new Promise<Doc>((resolve) => {
+        resolveAck = resolve;
+      });
+    });
+
+    const mutation = createMutation({ name: "new-todo-racer" });
+    const mutatePromise = harness.engine.mutate(mutation);
+    await vi.advanceTimersByTimeAsync(0);
+    expect(docIds()).toEqual(["new-todo-racer"]);
+
+    // Realtime beats the ack: the doctype-room event lands and the page
+    // refresh it schedules runs while the create is still pending.
+    await harness.emitListUpdate("real-2");
+    await vi.advanceTimersByTimeAsync(600);
+
+    // Pre-ack the engine honestly shows both: the unmatched server row and
+    // the still-pending optimistic row (they cannot be correlated until the
+    // ack names the create).
+    expect([...docIds()].sort()).toEqual(["new-todo-racer", "real-2"]);
+
+    resolveAck(serverDoc("real-2"));
+    await mutatePromise;
+
+    // Ack lands: the temp row is dropped rather than remapped onto the
+    // already-present server row — exactly one row, no duplicates.
+    expect(docIds()).toEqual(["real-2"]);
+    expect(rowNames()).toEqual(["real-2"]);
+    expect(harness.cache.get({ doctype: "TestDoc", name: "new-todo-racer" })).toBeUndefined();
+
+    // Late rehydrations stay idempotent.
+    await vi.advanceTimersByTimeAsync(1000);
+    expect(docIds()).toEqual(["real-2"]);
+  });
+
+  it("reconciles when the REST ack lands BEFORE the realtime insert", async () => {
+    harness.db.createDoc.mockImplementation(async () => {
+      harness.serverRows.push(serverDoc("real-3"));
+      return serverDoc("real-3");
+    });
+
+    await harness.engine.mutate(createMutation({ name: "new-todo-early-ack" }));
+    expect(docIds()).toEqual(["real-3"]);
+
+    // The realtime echo for the same doc arrives afterwards — membership
+    // already contains the server name, so nothing duplicates.
+    await harness.emitListUpdate("real-3");
+    await vi.advanceTimersByTimeAsync(1000);
+
+    expect(docIds()).toEqual(["real-3"]);
+    expect(rowNames()).toEqual(["real-3"]);
+  });
+
+  it("acks a create with an engine-generated temp name without sending the temp name", async () => {
+    harness.db.createDoc.mockImplementation(async () => {
+      harness.serverRows.push(serverDoc("real-4"));
+      return serverDoc("real-4");
+    });
+
+    const mutation = createMutation({});
+    const mutatePromise = harness.engine.mutate(mutation);
+    const optimisticIds = docIds();
+    expect(optimisticIds).toHaveLength(1);
+    expect(optimisticIds[0]).toMatch(/^tmp_/);
+
+    await mutatePromise;
+
+    // The generated temp id was never sent to the server…
+    expect(harness.db.createDoc.mock.calls[0][0].name).toBeUndefined();
+    // …and the ack still reconciled it away.
+    expect(docIds()).toEqual(["real-4"]);
+    expect(harness.cache.get({ doctype: "TestDoc", name: optimisticIds[0] })).toBeUndefined();
+  });
+
+  it("does not roll back a server-confirmed create when realtime is unhealthy", async () => {
+    // The insert-side sibling of the delete-refetch rollback bug: with the
+    // socket down, the post-mutation refetch used to target the PRE-remap
+    // temporary name → guaranteed 404 → journal.fail + rollback of a create
+    // the server had already committed.
+    harness.realtimeHealthy.value = false;
+    harness.db.createDoc.mockImplementation(async () => {
+      harness.serverRows.push(serverDoc("real-5"));
+      return serverDoc("real-5");
+    });
+
+    await expect(
+      harness.engine.mutate(createMutation({ name: "new-todo-offline-socket" })),
+    ).resolves.not.toThrow();
+
+    expect(docIds()).toEqual(["real-5"]);
+    expect(rowNames()).toEqual(["real-5"]);
+    // The temp name was never refetched (it would 404).
+    expect(harness.db.getDoc).not.toHaveBeenCalledWith("TestDoc", "new-todo-offline-socket");
+    expect(harness.journal.get("create-1")).toBeUndefined(); // confirmed → removed
+  });
+
+  it("confirms (not rolls back) a create whose ack carries no document name", async () => {
+    // Custom endpoints (and the pre-fix live envelope) can yield an ack
+    // without a usable name. The engine then cannot remap — but it must NOT
+    // refetch the temporary name (guaranteed 404) and roll back a create
+    // the server just confirmed. The optimistic row stays until realtime /
+    // backfill reconciles it.
+    harness.realtimeHealthy.value = false;
+    harness.db.createDoc.mockResolvedValue({} as Doc);
+
+    await expect(
+      harness.engine.mutate(createMutation({ name: "new-todo-nameless-ack" })),
+    ).resolves.not.toThrow();
+
+    expect(harness.db.getDoc).not.toHaveBeenCalled();
+    expect(harness.journal.get("create-1")).toBeUndefined(); // confirmed → removed
+    expect(docIds()).toEqual(["new-todo-nameless-ack"]);
+    expect(rowNames()).toEqual(["new-todo-nameless-ack"]);
+  });
+
+  it("rolls back a rejected create (temp row evicted from membership and cache)", async () => {
+    harness.db.createDoc.mockRejectedValue(
+      Object.assign(new Error("Validation failed"), {
+        status: 417,
+      }),
+    );
+
+    await expect(
+      harness.engine.mutate(createMutation({ name: "new-todo-rejected" })),
+    ).rejects.toThrow("Validation failed");
+
+    expect(docIds()).toEqual([]);
+    expect(rowNames()).toEqual([]);
+    expect(harness.cache.get({ doctype: "TestDoc", name: "new-todo-rejected" })).toBeUndefined();
+  });
+
+  it("rolls back a rejected create even when the realtime row already landed", async () => {
+    // Rejection while a foreign-looking server row is present (e.g. another
+    // user's concurrent insert): only the optimistic temp row is rolled
+    // back — the authoritative server row stays.
+    harness.serverRows.push(serverDoc("real-other"));
+    let rejectAck: (err: unknown) => void = () => {};
+    harness.db.createDoc.mockImplementation(
+      () =>
+        new Promise((_resolve, reject) => {
+          rejectAck = reject;
+        }),
+    );
+
+    const mutatePromise = harness.engine.mutate(createMutation({ name: "new-todo-doomed" }));
+    const settled = mutatePromise.catch((err) => err);
+    await vi.advanceTimersByTimeAsync(0);
+    await harness.emitListUpdate("real-other");
+    await vi.advanceTimersByTimeAsync(600);
+    expect([...docIds()].sort()).toEqual(["new-todo-doomed", "real-other"]);
+
+    rejectAck(Object.assign(new Error("Server said no"), { status: 417 }));
+    expect(await settled).toBeInstanceOf(Error);
+
+    expect(docIds()).toEqual(["real-other"]);
+    expect(rowNames()).toEqual(["real-other"]);
+    expect(harness.cache.get({ doctype: "TestDoc", name: "new-todo-doomed" })).toBeUndefined();
+  });
+});