@multiplatform.one/frappe 6.4.3 → 6.7.0

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();
+  });
+});

package/src/sync/subscriptionManager.spec.ts

@@ -128,6 +128,46 @@ describe("SubscriptionManager", () => {
         fields: ["title", "description", "modified", "name"],
         filters: { status: "Active" },
         orderBy: { field: "modified", order: Order.Desc },
+        limit: 20,
+      });
+    });
+
+    it("passes an explicit limit (and limitStart) through to the initial fetch", async () => {
+      // Regression: the initial fetch used to drop query.limit entirely, so
+      // the request carried no limit_page_length and the bench clamped every
+      // collection to its default page length (20) — `useFrappeCollection`
+      // consumers with `limit: N > 20` silently lost rows (pokemon moves
+      // accordion truncation).
+      const query: SubscriptionQuery = {
+        doctype: "TestDoc",
+        fields: ["title"],
+        limit: 500,
+        limitStart: 40,
+      };
+
+      await subscriptionManager.subscribe(query);
+
+      expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
+        fields: ["title", "modified", "name"],
+        filters: undefined,
+        orderBy: undefined,
+        limit: 500,
+        limitStart: 40,
+      });
+    });
+
+    it("omits limit from the initial fetch when the query has none", async () => {
+      const query: SubscriptionQuery = {
+        doctype: "TestDoc",
+        fields: ["title"],
+      };
+
+      await subscriptionManager.subscribe(query);
+
+      expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
+        fields: ["title", "modified", "name"],
+        filters: undefined,
+        orderBy: undefined,
       });
     });
 
@@ -183,6 +223,7 @@ describe("SubscriptionManager", () => {
 
       expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
         fields: ["*", "modified", "name"],
+        limit: 20,
         cursor: undefined,
       });
       expect(result.rows).toEqual(mockDocs);

package/src/sync/subscriptionManager.ts

@@ -168,6 +168,16 @@ export class SubscriptionManager {
         filters: query.filters,
         orderBy: query.orderBy,
       };
+      // Honor an explicit subscription limit on the INITIAL fetch. Without
+      // this the request carries no limit_page_length and the bench clamps
+      // to its default page length (20) — collections created with
+      // `limit: N` silently truncated to 20 rows (surfaced by the pokemon
+      // moves accordion once rosters grew past 20 junction rows). No
+      // explicit limit keeps the previous no-param behavior.
+      if (query.limit != null) {
+        listOptions.limit = query.limit;
+        if (query.limitStart != null) listOptions.limitStart = query.limitStart;
+      }
       if (this.options.useCursorPagination) listOptions.cursor = undefined;
       const response = await this.db.getDocList<Data>(query.doctype, listOptions);
 

package/src/sync/subscriptions.spec.ts

@@ -134,6 +134,9 @@ describe("SubscriptionManager", () => {
         fields: ["title", "description", "modified", "name"],
         filters: { status: "Active" },
         orderBy: { field: "modified", order: Order.Desc },
+        // The initial fetch honors the subscription limit (it used to drop
+        // it, so the bench clamped every list to its default page length).
+        limit: 20,
       });
     });
 
@@ -189,6 +192,7 @@ describe("SubscriptionManager", () => {
 
       expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
         fields: ["*", "modified", "name"],
+        limit: 20,
         cursor: undefined,
       });
       expect(result.rows).toEqual(mockDocs);

package/src/sync/types.ts

@@ -106,6 +106,15 @@ export interface CreateMutation<D extends FrappeDocData> {
   doc: FrappeDoc<D>;
   version?: string;
   affected?: { doctype: string; name: string }[];
+  /**
+   * Client-side temporary identity the optimistic row was inserted under.
+   * Set by the engine when the mutation is applied: equals `doc.name` when
+   * the consumer provided a placeholder, otherwise an engine-generated
+   * `tmp_*` id (which is never sent to the server). The server ack remap,
+   * rollback, and journal paths all resolve the optimistic row through
+   * this single field.
+   */
+  temporaryName?: string;
 }
 
 export interface UpdateMutation<Data extends FrappeDocData> {

package/types/collection.d.ts

@@ -30,6 +30,18 @@ export interface FrappeCollectionOptionsConfig<_TDoc extends object & {
      */
     onSyncError?: (error: unknown) => void;
 }
+/**
+ * Releases the Frappe-side sync resources (SyncModule subscription + store
+ * listener → realtime room) of a collection created by
+ * {@link createFrappeCollection}, without touching TanStack DB's lifecycle.
+ * Idempotent; also runs automatically when TanStack stops the sync itself.
+ *
+ * @returns true when an active sync session was released, false when the
+ * collection has no registered session (sync never started, already
+ * stopped, or not a Frappe collection) — callers may fall back to
+ * `collection.cleanup()` in that case.
+ */
+export declare function releaseFrappeCollectionSync(collection: object): boolean;
 /**
  * Creates TanStack DB collection options wired to Frappe's SyncModule.
  *