@multiplatform.one/frappe 6.6.0 → 7.0.0

package/src/core/http.ts

@@ -23,6 +23,85 @@ function isAbortError(err: unknown, signal?: AbortSignal): boolean {
   if (signal?.aborted) return true;
   return err instanceof Error && err.name === "AbortError";
 }
+
+/**
+ * Frappe's `_server_messages` is a JSON array of JSON strings, each an object
+ * like `{"message": "You don't have access to Report: ToDo", "title": "Message"}`,
+ * and the messages carry inline HTML (`<strong>…</strong>`).
+ */
+function readServerMessage(raw: unknown): string | undefined {
+  if (typeof raw !== "string" || !raw.trim()) return undefined;
+  let entries: unknown;
+  try {
+    entries = JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+  if (!Array.isArray(entries)) return undefined;
+  for (const entry of entries) {
+    let text: unknown = entry;
+    if (typeof entry === "string") {
+      try {
+        text = (JSON.parse(entry) as { message?: unknown })?.message ?? entry;
+      } catch {
+        text = entry;
+      }
+    } else if (entry && typeof entry === "object") {
+      text = (entry as { message?: unknown }).message;
+    }
+    if (typeof text === "string" && text.trim()) {
+      // Strip the inline markup so the sentence survives into plain-text UI.
+      // Frappe separates multiple sentences inside ONE message with `<br>`, so
+      // line-breaking tags become spaces or the sentences run together.
+      const plain = text
+        .replace(/<\s*br\s*\/?\s*>|<\/\s*(?:p|div|li)\s*>/gi, " ")
+        .replace(/<[^>]+>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+      if (plain) return plain;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The user-facing sentence for a failed response.
+ *
+ * With `developer_mode` on, Frappe puts a full python traceback in `exc`, and
+ * reading that first meant every permission failure surfaced a traceback as its
+ * error message — which components then rendered verbatim into the UI. The
+ * readable sentence is in `_server_messages`, and it is preferred here; `exc`
+ * is a last resort and contributes only its final line (the actual raise),
+ * never the whole stack.
+ */
+export function errorMessageFromPayload(payload: unknown, statusText: string): string {
+  // A non-JSON body is usually an HTML error page — frappe's dev server emits a
+  // full werkzeug debug page for a dropped connection. The status line is the
+  // only part of that safe to show a user.
+  if (typeof payload === "string") return statusText || payload;
+  if (!payload || typeof payload !== "object") return statusText;
+  const body = payload as Record<string, unknown>;
+
+  if (typeof body.message === "string" && body.message.trim()) return body.message;
+
+  const serverMessage = readServerMessage(body._server_messages);
+  if (serverMessage) return serverMessage;
+
+  if (typeof body.exception === "string" && body.exception.trim()) return body.exception;
+
+  if (typeof body.exc === "string" && body.exc.trim()) {
+    const lines = body.exc
+      .split("\\n")
+      .flatMap((line) => line.split("\n"))
+      .map((line) => line.trim())
+      .filter((line) => line && line !== '"]' && line !== '["');
+    const lastFrame = lines.at(-1);
+    if (lastFrame) return lastFrame.replace(/^\[?"?/, "").replace(/"?\]?$/, "");
+  }
+
+  if (body.message !== undefined && body.message !== null) return String(body.message);
+  return statusText;
+}
 export type RequestBody = BodyInit | Record<string, unknown> | unknown[] | ArrayBufferView;
 
 export interface HttpResponse<T> {
@@ -290,9 +369,7 @@ export class HttpClient {
           const payload = contentType?.includes("application/json")
             ? await res.json()
             : await res.text();
-          const message =
-            (payload && (payload.message || payload.exc || payload._server_messages)) ||
-            res.statusText;
+          const message = errorMessageFromPayload(payload, res.statusText);
           const err = new FrappeError(message, res.status, payload);
           // Native cookie-auth: a 400 on a mutating request may be frappe's
           // CSRFTokenError from a rotated session — drop the cached token so

package/src/doctype.spec.ts

@@ -271,7 +271,7 @@ describe("useDocTypeMeta", () => {
     // Config must be stable (defined outside renderHook) — hooks with [config]
     // in deps loop infinitely if a new object is created on every render.
     const config = { baseURL: `https://meta-${testId}.example.com` };
-    mockGetFn.mockResolvedValueOnce({ payload: { data: rawDocType(doctype) } });
+    mockGetFn.mockResolvedValueOnce({ payload: { docs: [rawDocType(doctype)] } });
 
     const { result } = renderHook(() => useDocTypeMeta(config, doctype));
 
@@ -285,6 +285,85 @@ describe("useDocTypeMeta", () => {
     expect(result.current.meta!.permissions[0].read).toBe(true);
   });
 
+  // The REST route reads the DocType *document* — System-Manager-only, so
+  // ordinary users got a 403 traceback instead of a form. Assert the endpoint
+  // itself, not just that meta parsed: only the URL distinguishes the two.
+  it("loads meta over the whitelisted getdoctype RPC, not the DocType resource route", async () => {
+    const doctype = `DocRpc${testId}`;
+    const config = { baseURL: `https://meta-rpc-${testId}.example.com` };
+    mockGetFn.mockResolvedValueOnce({ payload: { docs: [rawDocType(doctype)] } });
+
+    const { result } = renderHook(() => useDocTypeMeta(config, doctype));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(mockGetFn).toHaveBeenCalledWith("/api/method/frappe.desk.form.load.getdoctype", {
+      doctype,
+    });
+    const requestedPaths = mockGetFn.mock.calls.map((call) => String(call[0]));
+    expect(requestedPaths.some((path) => path.includes("/api/resource/DocType/"))).toBe(false);
+  });
+
+  it("falls back to the DocType document route when the RPC returns no docs", async () => {
+    const doctype = `DocFallback${testId}`;
+    const config = { baseURL: `https://meta-fallback-${testId}.example.com` };
+    // desk RPCs unregistered → the call resolves, but carries no `docs`
+    mockGetFn.mockResolvedValueOnce({ payload: {} });
+    mockGetFn.mockResolvedValueOnce({ payload: { data: rawDocType(doctype) } });
+
+    const { result } = renderHook(() => useDocTypeMeta(config, doctype));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.meta!.name).toBe(doctype);
+    expect(mockGetFn.mock.calls.map((call) => String(call[0]))).toEqual([
+      "/api/method/frappe.desk.form.load.getdoctype",
+      `/api/resource/DocType/${doctype}`,
+    ]);
+  });
+
+  it("picks the requested doctype out of a bundle that also carries child tables", async () => {
+    const doctype = `DocParent${testId}`;
+    const config = { baseURL: `https://meta-bundle-${testId}.example.com` };
+    mockGetFn.mockResolvedValueOnce({
+      payload: { docs: [rawDocType(`${doctype} Child`), rawDocType(doctype)] },
+    });
+
+    const { result } = renderHook(() => useDocTypeMeta(config, doctype));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.meta!.name).toBe(doctype);
+  });
+
+  it("reads meta from the fixture provider's DocType collection without any request", async () => {
+    const doctype = `DocFix${testId}`;
+    const fixtures = {
+      getDoc: vi.fn(async () => rawDocType(doctype)),
+    } as unknown as NonNullable<Parameters<typeof useDocTypeMeta>[0]>["fixtures"];
+    const config = { baseURL: `https://meta-fix-${testId}.example.com`, fixtures };
+
+    const { result } = renderHook(() => useDocTypeMeta(config, doctype));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.meta!.name).toBe(doctype);
+    expect(mockGetFn).not.toHaveBeenCalled();
+  });
+
+  it("falls through to the RPC when the fixture provider has no meta for the doctype", async () => {
+    const doctype = `DocFixMiss${testId}`;
+    const fixtures = {
+      getDoc: vi.fn(async () => null),
+    } as unknown as NonNullable<Parameters<typeof useDocTypeMeta>[0]>["fixtures"];
+    const config = { baseURL: `https://meta-fixmiss-${testId}.example.com`, fixtures };
+    mockGetFn.mockResolvedValueOnce({ payload: { docs: [rawDocType(doctype)] } });
+
+    const { result } = renderHook(() => useDocTypeMeta(config, doctype));
+    await waitFor(() => expect(result.current.isLoading).toBe(false));
+
+    expect(result.current.meta!.name).toBe(doctype);
+    expect(mockGetFn).toHaveBeenCalledWith("/api/method/frappe.desk.form.load.getdoctype", {
+      doctype,
+    });
+  });
+
   it("sets error state when the fetch fails", async () => {
     const doctype = `DocB${testId}`;
     const config = { baseURL: `https://meta-err-${testId}.example.com` };
@@ -314,7 +393,7 @@ describe("useDocTypeMeta", () => {
       ...rawDocType(doctype),
       field_order: ["status", "name"], // reversed
     };
-    mockGetFn.mockResolvedValueOnce({ payload: { data: raw } });
+    mockGetFn.mockResolvedValueOnce({ payload: { docs: [raw] } });
 
     const { result } = renderHook(() => useDocTypeMeta(config, doctype));
 
@@ -326,7 +405,7 @@ describe("useDocTypeMeta", () => {
   it("refetch() clears cache and re-fetches", async () => {
     const doctype = `DocD${testId}`;
     const config = { baseURL: `https://meta-refetch-${testId}.example.com` };
-    mockGetFn.mockResolvedValue({ payload: { data: rawDocType(doctype) } });
+    mockGetFn.mockResolvedValue({ payload: { docs: [rawDocType(doctype)] } });
 
     const { result } = renderHook(() => useDocTypeMeta(config, doctype));
     await waitFor(() => expect(result.current.isLoading).toBe(false));

package/src/doctype.ts

@@ -503,6 +503,13 @@ function useHttpClientRef(
 /**
  * Fetch and cache DocType metadata (schema, fields, layout, permissions).
  *
+ * Metadata comes from `frappe.desk.form.load.getdoctype`, the whitelisted RPC
+ * the Desk itself uses, so ordinary users load forms too — the REST
+ * `/api/resource/DocType/<name>` route reads the DocType *document* and is
+ * System-Manager-only. That route stays as a fallback for desk-less sites
+ * where the RPC is not registered. When `config.fixtures` carries a "DocType"
+ * entry for the doctype it is used instead and no request is made.
+ *
  * Responses are cached per-session in memory keyed by `{baseURL}:{doctype}`.
  * The `refetch` function clears the cache entry and forces a fresh fetch.
  *
@@ -576,13 +583,50 @@ export function useDocTypeMeta(
 
     (async () => {
       try {
-        const response = await http.get<{ data: RawDocTypeResponse }>(
-          `/api/resource/DocType/${encodeURIComponent(doctype)}`,
-        );
-
+        // Fixture hosts (stories/tests) keep the getdoctype-shaped meta doc in
+        // the provider's "DocType" collection — the same convention the
+        // backoffice meta loader uses. Providers that stub only documents fall
+        // through to the network below.
+        const fromFixtures = config.fixtures
+          ? ((await config.fixtures.getDoc("DocType", doctype)) as RawDocTypeResponse | null)
+          : null;
         if (cancelled) return;
 
-        const raw = response.payload?.data;
+        let raw = fromFixtures?.fields ? fromFixtures : undefined;
+
+        if (!raw) {
+          // `getdoctype` is the whitelisted RPC the Desk itself loads form
+          // metadata with, and every logged-in user may call it. Reading
+          // `/api/resource/DocType/<name>` instead asks for the DocType
+          // *document*, which only System Manager holds read permission on, so
+          // ordinary users got a 403 PermissionError — and Frappe's
+          // developer-mode traceback rendered into the UI instead of a form.
+          const response = await http.get<{ docs?: RawDocTypeResponse[] }>(
+            "/api/method/frappe.desk.form.load.getdoctype",
+            { doctype },
+          );
+
+          if (cancelled) return;
+
+          // docs[0] is the requested doctype; docs[1..] are its child tables.
+          const docs = response.payload?.docs;
+          raw = docs?.find((doc) => doc?.name === doctype) ?? docs?.[0];
+        }
+
+        if (!raw) {
+          // Sites that expose the REST API without the desk leave the RPC
+          // above unregistered, so it answers with no `docs`. The document
+          // route still serves meta there, and such a site's API clients are
+          // typically System Managers, who may read it.
+          const rest = await http.get<{ data?: RawDocTypeResponse }>(
+            `/api/resource/DocType/${encodeURIComponent(doctype)}`,
+          );
+
+          if (cancelled) return;
+
+          raw = rest.payload?.data;
+        }
+
         if (!raw) {
           throw new Error(`No data returned for DocType "${doctype}"`);
         }
@@ -605,8 +649,8 @@ export function useDocTypeMeta(
     // Depend on the stable string `cacheKey` (baseURL + doctype), NOT the
     // `config` object — callers frequently pass a freshly-allocated config
     // object every render. Keying on the object identity would re-run this
-    // effect on every render and, when the request fails (e.g. a Guest hitting
-    // the permission-gated DocType meta endpoint → 403, which never populates
+    // effect on every render and, when the request fails (e.g. a Guest calling
+    // the login-gated getdoctype RPC → 403, which never populates
     // `metaCache`), spin into an infinite refetch loop.
   }, [cacheKey, version]);
 

package/src/frappeReact.ts

@@ -1,6 +1,6 @@
 import { isWindowDefined } from "@multiplatform.one/platform";
 import type { Collection } from "@tanstack/db";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   createFrappeCollection,
   releaseFrappeCollectionSync,
@@ -12,6 +12,8 @@ import { DbModule } from "./db";
 import { FixtureDbModule } from "./fixtureDb";
 import { RealtimeModule } from "./realtime";
 import { SyncModule } from "./sync";
+import { Status } from "./sync/types";
+import type { DebugMutationEntry } from "./sync/types";
 import { isBrowser } from "./util";
 
 /**
@@ -26,6 +28,20 @@ export interface UseFrappeCollectionConfig {
    * behind a reverse proxy so the base URL port is used.
    */
   socketPort?: number;
+  /**
+   * Dial the realtime socket at this origin instead of deriving it from
+   * `baseURL` + `socketPort` — for dev servers that proxy `/socket.io` on
+   * their own origin (same-origin socket). See
+   * `RealtimeConfig.socketBaseURL`.
+   */
+  socketBaseURL?: string;
+  /**
+   * Frappe site name — the Socket.IO namespace the realtime connection must
+   * join. Required whenever the `baseURL` hostname is not the bench site
+   * name (e.g. baseURL http://127.0.0.1:8000 serving site "localhost"). See
+   * `RealtimeConfig.siteName`.
+   */
+  siteName?: string;
   /** Authentication configuration */
   auth?: {
     useToken?: boolean;
@@ -61,6 +77,20 @@ export function __getActiveSyncModule(): SyncModule | undefined {
   return undefined;
 }
 
+/**
+ * Public accessor for the shared SyncModule behind a connection config —
+ * the seam consumers use to issue engine mutations that a collection can't
+ * express (e.g. custom-transport writes via `mutation.execute`). Returns
+ * the same refcounted instance the collection hooks use, or undefined
+ * during SSR.
+ */
+export function getFrappeSyncModule(
+  config: UseFrappeCollectionConfig | undefined,
+): SyncModule | undefined {
+  if (!config) return undefined;
+  return getSyncModule(config);
+}
+
 /**
  * Gets or creates a shared SyncModule for the given config.
  * SyncModules are cached by baseURL to prevent duplicate connections.
@@ -90,7 +120,18 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
     return sync;
   }
 
-  const key = config.baseURL;
+  // Key on the full socket target, not just baseURL: socketPort /
+  // socketBaseURL / siteName all change where (or how) the realtime socket
+  // dials, so configs that differ in them must not share a SyncModule —
+  // sharing would silently keep the FIRST config's socket target for every
+  // later consumer. Consumers reading the same FrappeProvider still coalesce
+  // (identical fields → identical key).
+  const key = [
+    config.baseURL,
+    config.socketPort ?? "",
+    config.socketBaseURL ?? "",
+    config.siteName ?? "",
+  ].join("|");
   let sync = syncModuleCache.get(key);
   if (!sync) {
     // The FIRST config for a baseURL wins for every later consumer (the
@@ -114,6 +155,12 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
     const realtimeConfig = {
       baseURL: config.baseURL,
       socketPort: config.socketPort,
+      socketBaseURL: config.socketBaseURL,
+      // Forward siteName: Frappe's realtime server only emits events on the
+      // site's namespace, so dropping it here silently connected sockets to
+      // a namespace the server rejects whenever the baseURL hostname isn't
+      // the site name (e.g. 127.0.0.1 vs "localhost").
+      siteName: config.siteName,
       auth: authConfig,
       socketOptions: config.socketOptions,
     };
@@ -601,6 +648,81 @@ export function useFrappeDoctypeEvents(
   }, [enabled, config?.baseURL, !!config?.fixtures, doctype]);
 }
 
+// ---------------------------------------------------------------------------
+// Mutation ledger hook
+// ---------------------------------------------------------------------------
+
+/** Result of {@link useFrappePendingMutations}. */
+export interface UseFrappePendingMutationsResult {
+  /** All live ledger entries (pending + failed), submission order. */
+  entries: DebugMutationEntry[];
+  /** Entries still awaiting a server ack. */
+  pending: DebugMutationEntry[];
+  /** Entries the server rejected — rollback already ran; show these. */
+  failed: DebugMutationEntry[];
+  /** Re-issues every pending/failed entry with its ORIGINAL mutation id
+   * (idempotent on the server via Idempotency-Key). */
+  retry: () => Promise<void>;
+  /** Drops one failed entry without retrying (clears the error surface). */
+  dismiss: (id: string) => void;
+}
+
+const EMPTY_LEDGER: DebugMutationEntry[] = [];
+
+/**
+ * React hook exposing the mutation ledger for a connection (optionally
+ * scoped to one doctype): which optimistic writes are still in flight and
+ * which the server rejected. This is the state behind the rejected-write
+ * UI contract — a surface that initiated a write renders `failed` entries
+ * inline (e.g. via frappe-ui's `SyncErrorNotice`) with `retry`/`dismiss`.
+ *
+ * Reactive: re-reads on every store emit, but only re-renders when the
+ * ledger signature (ids × status × retryCount) actually changes.
+ */
+export function useFrappePendingMutations(
+  config: UseFrappeCollectionConfig | undefined,
+  doctype?: string,
+): UseFrappePendingMutationsResult {
+  const [entries, setEntries] = useState<DebugMutationEntry[]>(EMPTY_LEDGER);
+  const syncModuleRef = useRef<SyncModule | undefined>(undefined);
+
+  useEffect(() => {
+    if (!config || !isBrowser()) {
+      setEntries(EMPTY_LEDGER);
+      return;
+    }
+    const syncModule = getSyncModule(config);
+    if (!syncModule) return;
+    syncModuleRef.current = syncModule;
+
+    let lastSignature = "";
+    const read = () => {
+      const next = syncModule.getMutationEntries(doctype);
+      const signature = next.map((e) => `${e.id}:${e.status}:${e.retryCount}`).join("|");
+      if (signature === lastSignature) return;
+      lastSignature = signature;
+      setEntries(next.length === 0 ? EMPTY_LEDGER : next);
+    };
+    read();
+    return syncModule.subscribeStore(read);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config?.baseURL, !!config?.fixtures, doctype]);
+
+  const retry = useCallback(async () => {
+    await syncModuleRef.current?.replayPending();
+  }, []);
+
+  const dismiss = useCallback((id: string) => {
+    syncModuleRef.current?.dismissMutation(id);
+  }, []);
+
+  return useMemo(() => {
+    const pending = entries.filter((e) => e.status === Status.Pending);
+    const failed = entries.filter((e) => e.status === Status.Failed);
+    return { entries, pending, failed, retry, dismiss };
+  }, [entries, retry, dismiss]);
+}
+
 // ---------------------------------------------------------------------------
 // Infinite Scroll Hook
 // ---------------------------------------------------------------------------
@@ -663,7 +785,7 @@ export interface UseInfiniteScrollResult {
  *
  *   return (
  *     <div>
- *       {data.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       {data.map(pokemon => <PokemonCard key={pokemon.name} pokemon={pokemon} />)}
  *       <div ref={sentinelRef}>
  *         {isLoadingMore ? <Spinner /> : hasMore ? "Scroll for more" : "No more items"}
  *       </div>
@@ -865,7 +987,7 @@ export interface UseFrappeInfiniteListResult<TDoc> {
  *
  *   return (
  *     <div>
- *       {items.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       {items.map(pokemon => <PokemonCard key={pokemon.name} pokemon={pokemon} />)}
  *       <div ref={sentinelRef}>
  *         {hasMore ? <Spinner /> : "No more pokemon"}
  *       </div>

package/src/index.ts

@@ -12,7 +12,19 @@ export { AuthModule } from "./auth";
 export { CallModule } from "./call";
 export { DbModule } from "./db";
 export { FileModule } from "./file";
-export { RealtimeModule } from "./realtime";
+export { RealtimeModule, RealtimePlatform } from "./realtime";
+export type {
+  RealtimeConfig,
+  RealtimeTransport,
+  RealtimeSSEConfig,
+  SSEFrame,
+  SSEMappedEvent,
+  SSEMessageEventLike,
+  SSEEventSourceLike,
+  SSEEventSourceConstructor,
+  DocRoom,
+  ListRoom,
+} from "./realtime";
 export { SyncModule } from "./sync";
 
 // TanStack DB collection integration
@@ -23,20 +35,30 @@ export {
   fixtureCollectionOptions,
 } from "./collection";
 export type { FrappeCollectionOptionsConfig, FixtureCollectionOptionsConfig } from "./collection";
-export { createOptimisticAction } from "./optimistic";
+export {
+  createOptimisticAction,
+  isOptimisticTempId,
+  newOptimisticTempId,
+  OPTIMISTIC_TEMP_PREFIX,
+  runOptimisticRpc,
+} from "./optimistic";
+export type { OptimisticRpcContext, OptimisticRpcOptions } from "./optimistic";
 
 // React hooks for Frappe + TanStack DB
 export {
   useFrappeCollection,
   useFrappeConnection,
   useFrappeDoctypeEvents,
+  useFrappePendingMutations,
   useInfiniteScroll,
   useFrappeInfiniteList,
+  getFrappeSyncModule,
   __getActiveSyncModule,
 } from "./frappeReact";
 export type {
   FrappeConnectionState,
   UseFrappeCollectionConfig,
+  UseFrappePendingMutationsResult,
   UseInfiniteScrollConfig,
   UseInfiniteScrollResult,
   UseFrappeInfiniteListConfig,
@@ -168,6 +190,9 @@ export type {
   PageBoundaries,
   RehydrationStrategy,
   Mutation,
+  CreateMutation,
+  UpdateMutation,
+  DeleteMutation,
   ConnectionConfig,
   TabCoordinationConfig,
   TabMessage,
@@ -176,7 +201,7 @@ export type {
   DebugMutationEntry,
   PageIsland,
 } from "./sync/types";
-export { Order } from "./sync/types";
+export { Order, Operation } from "./sync/types";
 export { MergeStrategy, FieldMergeStrategy } from "./sync/merge";
 export type { FieldMergeStrategyOrFunction, MergeConfig, MergeResult } from "./sync/merge";
 

package/src/optimistic.spec.ts

@@ -1,6 +1,12 @@
 import { createOptimisticAction as tanstackCreateOptimisticAction } from "@tanstack/db";
-import { describe, expect, it } from "vitest";
-import { createOptimisticAction } from "./optimistic";
+import { describe, expect, it, vi } from "vitest";
+import {
+  OPTIMISTIC_TEMP_PREFIX,
+  createOptimisticAction,
+  isOptimisticTempId,
+  newOptimisticTempId,
+  runOptimisticRpc,
+} from "./optimistic";
 
 describe("createOptimisticAction re-export", () => {
   it("is the same reference as @tanstack/db createOptimisticAction", () => {
@@ -11,3 +17,108 @@ describe("createOptimisticAction re-export", () => {
     expect(typeof createOptimisticAction).toBe("function");
   });
 });
+
+describe("newOptimisticTempId / isOptimisticTempId", () => {
+  it("issues unique tmp_-prefixed identities (MutationEngine convention)", () => {
+    const a = newOptimisticTempId();
+    const b = newOptimisticTempId();
+    expect(a.startsWith(OPTIMISTIC_TEMP_PREFIX)).toBe(true);
+    expect(b.startsWith(OPTIMISTIC_TEMP_PREFIX)).toBe(true);
+    expect(a).not.toBe(b);
+    expect(isOptimisticTempId(a)).toBe(true);
+  });
+
+  it("rejects server-issued names and non-strings", () => {
+    expect(isOptimisticTempId("TODO-0001")).toBe(false);
+    expect(isOptimisticTempId(undefined)).toBe(false);
+    expect(isOptimisticTempId(42)).toBe(false);
+  });
+});
+
+describe("runOptimisticRpc lifecycle", () => {
+  it("applies locally BEFORE the request resolves (local apply is the first reveal)", async () => {
+    const order: string[] = [];
+    let releaseSend: (value: string) => void = () => {};
+    const sendGate = new Promise<string>((resolve) => {
+      releaseSend = resolve;
+    });
+
+    const promise = runOptimisticRpc<string>({
+      apply: () => {
+        order.push("apply");
+        return () => order.push("undo");
+      },
+      send: async () => {
+        order.push("send");
+        return sendGate;
+      },
+      reconcile: () => order.push("reconcile"),
+    });
+
+    // Apply and send already happened synchronously; the ack has not landed.
+    expect(order).toEqual(["apply", "send"]);
+    releaseSend("ack");
+    await expect(promise).resolves.toBe("ack");
+    expect(order).toEqual(["apply", "send", "reconcile"]);
+  });
+
+  it("passes the SAME temp id through apply, send, and reconcile (identity convergence)", async () => {
+    const seen: string[] = [];
+    await runOptimisticRpc({
+      apply: (ctx) => {
+        seen.push(ctx.tempId);
+      },
+      send: async (ctx) => {
+        seen.push(ctx.tempId);
+        return "ok";
+      },
+      reconcile: (_ack, ctx) => {
+        seen.push(ctx.tempId);
+      },
+    });
+    expect(seen).toHaveLength(3);
+    expect(new Set(seen).size).toBe(1);
+    expect(isOptimisticTempId(seen[0])).toBe(true);
+  });
+
+  it("rolls back (undo) then surfaces the error visibly (onError) on failure, and rethrows", async () => {
+    const order: string[] = [];
+    const failure = new Error("server said no");
+    const onError = vi.fn((error: unknown) => {
+      order.push("onError");
+      expect(error).toBe(failure);
+    });
+
+    await expect(
+      runOptimisticRpc({
+        apply: () => {
+          order.push("apply");
+          return () => order.push("undo");
+        },
+        send: async () => {
+          throw failure;
+        },
+        reconcile: () => order.push("reconcile"),
+        onError,
+      }),
+    ).rejects.toBe(failure);
+
+    // Rollback precedes the visible error; reconcile never runs.
+    expect(order).toEqual(["apply", "undo", "onError"]);
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+
+  it("still surfaces onError when apply returned no undo", async () => {
+    const onError = vi.fn();
+    await expect(
+      runOptimisticRpc({
+        apply: () => {},
+        send: async () => {
+          throw new Error("boom");
+        },
+        onError,
+      }),
+    ).rejects.toThrow("boom");
+    expect(onError).toHaveBeenCalledTimes(1);
+  });
+});