@ai-matrx/messaging 0.11.1 → 0.11.3

package/dist/index.d.cts

@@ -794,6 +794,12 @@ interface RepositoryOptions {
     identity: MessagingIdentity;
     /** Called once before a retry when a read fails with a missing session. */
     resolveSession?: SessionResolver | undefined;
+    /**
+     * Announced automatic interventions. Nothing fails silently and nothing heals
+     * silently either: every lock-collision retry below reports here (the React
+     * provider wires it to the host's diagnostics as a warning).
+     */
+    onDiagnostic?: ((message: string) => void) | undefined;
     /** Profile-lookup cache TTL. Default 5 minutes (the frontend's proven value). */
     userTtlMs?: number | undefined;
     now?: (() => number) | undefined;
@@ -1077,14 +1083,14 @@ declare function messagingClientId(): string;
  * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
  * warns and retries; it is never a red error.
  */
-type MessagingErrorCode = "session-unavailable" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
+type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
 declare class MessagingError extends Error {
     readonly code: MessagingErrorCode;
     /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
     readonly remedy: string;
     readonly cause?: unknown;
     constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
-    /** 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(): boolean;
 }
 interface PostgrestErrorLike {

package/dist/index.d.ts

@@ -794,6 +794,12 @@ interface RepositoryOptions {
     identity: MessagingIdentity;
     /** Called once before a retry when a read fails with a missing session. */
     resolveSession?: SessionResolver | undefined;
+    /**
+     * Announced automatic interventions. Nothing fails silently and nothing heals
+     * silently either: every lock-collision retry below reports here (the React
+     * provider wires it to the host's diagnostics as a warning).
+     */
+    onDiagnostic?: ((message: string) => void) | undefined;
     /** Profile-lookup cache TTL. Default 5 minutes (the frontend's proven value). */
     userTtlMs?: number | undefined;
     now?: (() => number) | undefined;
@@ -1077,14 +1083,14 @@ declare function messagingClientId(): string;
  * errors in 0.6 seconds. A missing session is a NORMAL lifecycle moment — it
  * warns and retries; it is never a red error.
  */
-type MessagingErrorCode = "session-unavailable" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
+type MessagingErrorCode = "session-unavailable" | "contention" | "forbidden" | "not-found" | "conflict" | "transport" | "invalid-response" | "misconfigured" | "unknown";
 declare class MessagingError extends Error {
     readonly code: MessagingErrorCode;
     /** The remedy. Nothing fails silently, and nothing fails without saying what to do. */
     readonly remedy: string;
     readonly cause?: unknown;
     constructor(code: MessagingErrorCode, message: string, remedy: string, cause?: unknown);
-    /** 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(): boolean;
 }
 interface PostgrestErrorLike {

package/dist/index.js

@@ -159,14 +159,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",
@@ -188,6 +189,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",
@@ -215,7 +224,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
   );
 }
@@ -1613,6 +1622,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");
@@ -1624,18 +1639,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;
       }
     }
   }