@ai-matrx/messaging 0.11.1 → 0.11.3

package/dist/react.cjs

@@ -203,14 +203,15 @@ var MessagingError = class extends Error {
     this.remedy = remedy;
     if (cause !== void 0) this.cause = cause;
   }
-  /** True when retrying after the host re-establishes a session is the fix. */
+  /** True when re-running the same call is the fix. */
   get isRetryable() {
-    return this.code === "session-unavailable" || this.code === "transport";
+    return this.code === "session-unavailable" || this.code === "contention" || this.code === "transport";
   }
 };
 var FORBIDDEN_CODES = /* @__PURE__ */ new Set(["42501", "PGRST301", "PGRST302"]);
 var NOT_FOUND_CODES = /* @__PURE__ */ new Set(["PGRST116", "PGRST205"]);
 var CONFLICT_CODES = /* @__PURE__ */ new Set(["23505"]);
+var CONTENTION_CODES = /* @__PURE__ */ new Set(["40P01", "40001", "55P03"]);
 var SESSION_MARKERS = [
   "auth session missing",
   "jwt expired",
@@ -232,6 +233,14 @@ function normalizeMessagingError(error, operation) {
       error
     );
   }
+  if (code !== void 0 && CONTENTION_CODES.has(code)) {
+    return new MessagingError(
+      "contention",
+      `${operation}: the database resolved a lock collision by cancelling this call (${code}: ${message})`,
+      "Nothing of this call committed, so it is safe to re-run \u2014 the package re-runs it a bounded number of times and announces each heal. Seeing it repeatedly means real contention on the messaging tables (usually DDL applied against live traffic); look at what else held a lock at that moment, never at the caller.",
+      error
+    );
+  }
   if (code !== void 0 && FORBIDDEN_CODES.has(code)) {
     return new MessagingError(
       "forbidden",
@@ -259,7 +268,7 @@ function normalizeMessagingError(error, operation) {
   return new MessagingError(
     "transport",
     `${operation}: ${message}`,
-    "Transient transport failure. The package retries reads; a write is surfaced to the outbox so the typed message is never lost.",
+    "Transient transport failure. A typed message is surfaced to the outbox so it is never lost; a read is the caller's to re-issue (only `contention` and `session-unavailable` are re-run inside the package).",
     error
   );
 }
@@ -1564,6 +1573,12 @@ function requireOrg(organizationId, operation) {
   }
   return organizationId;
 }
+var CONTENTION_ATTEMPTS = 3;
+var CONTENTION_BACKOFF_MS = [60, 180];
+function sleep(ms) {
+  const jittered = ms + Math.random() * ms * 0.5;
+  return new Promise((resolve) => setTimeout(resolve, jittered));
+}
 function createMessagingRepository(options) {
   const { identity } = options;
   const org = requireOrg(identity.organizationId, "createMessagingRepository");
@@ -1575,18 +1590,31 @@ function createMessagingRepository(options) {
   const db = () => client.schema(MESSAGING_SCHEMA);
   const rpcDb = () => client.schema(MESSAGING_RPC_SCHEMA);
   async function withSessionRetry(operation, run) {
-    try {
-      return await run();
-    } catch (error) {
-      const normalized = normalizeMessagingError(error, operation);
-      if (normalized.code !== "session-unavailable" || options.resolveSession === void 0) {
-        throw normalized;
-      }
-      await options.resolveSession();
+    let sessionRetried = false;
+    for (let attempt = 1; ; attempt += 1) {
       try {
-        return await run();
-      } catch (retryError) {
-        throw normalizeMessagingError(retryError, operation);
+        const value = await run();
+        if (attempt > 1) {
+          options.onDiagnostic?.(
+            `${operation}: healed on attempt ${attempt} after a database lock collision (rolled back, safe to re-run).`
+          );
+        }
+        return value;
+      } catch (error) {
+        const normalized = normalizeMessagingError(error, operation);
+        if (normalized.code === "session-unavailable" && options.resolveSession !== void 0 && !sessionRetried) {
+          sessionRetried = true;
+          await options.resolveSession();
+          continue;
+        }
+        if (normalized.code === "contention" && attempt < CONTENTION_ATTEMPTS) {
+          options.onDiagnostic?.(
+            `${operation}: attempt ${attempt}/${CONTENTION_ATTEMPTS} hit a database lock collision (${normalized.message}) \u2014 re-running in ${CONTENTION_BACKOFF_MS[attempt - 1] ?? 0}ms.`
+          );
+          await sleep(CONTENTION_BACKOFF_MS[attempt - 1] ?? 0);
+          continue;
+        }
+        throw normalized;
       }
     }
   }
@@ -1970,6 +1998,10 @@ function MessagingRuntime(props) {
       // contract, which `supabase-shape.test.ts` proves a real client honors.
       client,
       identity,
+      // An automatic heal ANNOUNCES itself: a lock collision the package
+      // re-ran is a warning in the host's diagnostics, never a banner on the
+      // inbox and never silence.
+      onDiagnostic: (message) => report({ level: "warn", message }),
       ...props.resolveSession !== void 0 ? { resolveSession: props.resolveSession } : {}
     });
     let built = null;