conexus 6.3.1__tar.gz → 6.3.2__tar.gz

{conexus-6.3.1 → conexus-6.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 6.3.1
+Version: 6.3.2
 Summary: Self-hosted semantic search and knowledge management for LLM-driven development
 Project-URL: Homepage, https://github.com/Hellblazer/nexus
 Project-URL: Repository, https://github.com/Hellblazer/nexus

{conexus-6.3.1 → conexus-6.3.2}/docs/rdr/README.md

@@ -194,6 +194,8 @@ An RDR (Research-Design-Review) is a short document that records a technical dec
 | [RDR-176](rdr-176-survivable-managed-migration-readiness.md) | Survivable Managed-Migration Readiness: Batched ETL, First-Class Downgrade with an Immutable Source, Unified Config-First Auth, Edge Route Coverage, and Migration Observability | Architecture | Closed | 2026-06-30 |
 | [RDR-177](rdr-177-tenant-telemetry-usage-metering.md) | Unified Tenant-Scoped Telemetry, Observability, and Usage Metering for the Engine Service: One Stats Layer for Local Users and Cloud Tenants | Architecture | Draft | 2026-07-01 |
 | [RDR-178](rdr-178-unattended-migration.md) | Unattended Migration: Industrialize the Store-Migration Path from Babysat to Autonomous | Architecture | Closed | 2026-07-01 |
+| [RDR-179](rdr-179-self-correction-machinery-remediation.md) | Self-Correction Machinery Remediation: Relight Plan-Reuse, Retrieval Benchmarking, Plan-Library Hygiene, and Taxonomy-Aware Recall | Architecture | Draft | 2026-07-04 |
+| [RDR-181](rdr-181-server-side-embed-skip-on-reindex.md) | Server-Side Embed-Skip on Re-Index: Stop Re-Embedding Chunks Whose Vector the Store Already Holds | Technical Debt | Accepted | 2026-07-05 |
 
 > **Scrapped 2026-05-19 (RDR-110-119 arc).** Bundled the storage-substrate split with new abstractions (tuplespace, ORB, host-trust, surfaces-as-tuples, UI fabric); scope discipline failed across nine RDRs and 67 stranded beads. Files preserved as tombstones per the "never delete RDR files" rule. Postmortem: [docs/postmortem/2026-05-16-rdr110-113-remediation-chain.md](../postmortem/2026-05-16-rdr110-113-remediation-chain.md). Active substrate work continues as [RDR-120](rdr-120-storage-substrate-split.md) with an explicit moratorium on co-shipped consumers. Numbers RDR-114 through RDR-117 are unused on `main` (drafted on feature branches that never merged).
 

{conexus-6.3.1 → conexus-6.3.2}/mcpb/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "conexus-mcpb"
-version = "6.3.1"
+version = "6.3.2"
 description = "Conexus packaged as Claude Desktop .mcpb (Desktop Extension)"
 requires-python = ">=3.12"
 dependencies = [
@@ -10,7 +10,7 @@ dependencies = [
     # while collections are indexed at 768/1024-dim, so every T3 search hits a
     # dimension mismatch and returns zero results. The .mcpb cannot run the
     # interactive `nx init` embedder choice, so it must pin [local] explicitly.
-    "conexus[local]>=6.3.1",
+    "conexus[local]>=6.3.2",
 ]
 
 [tool.uv]

{conexus-6.3.1 → conexus-6.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "6.3.1"
+version = "6.3.2"
 description = "Self-hosted semantic search and knowledge management for LLM-driven development"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12,<3.14"

{conexus-6.3.1 → conexus-6.3.2}/service/src/main/java/dev/nexus/service/db/CatalogRepository.java

@@ -450,6 +450,152 @@ public final class CatalogRepository {
         });
     }
 
+    /**
+     * Batch variant of {@link #registerDocument} (nexus-9dvqy, duoak.11 sink #2).
+     *
+     * <p>Registers N documents under one owner in a SINGLE transaction, returning
+     * their tumblers in INPUT ORDER. The per-doc {@code registerDocument} path pays
+     * one {@code SELECT next_seq FOR UPDATE} owner-row lock per call — 2,133 serial
+     * WAN round-trips on a --force index (333s / 16% of the duoak.11 gate wall), all
+     * queued on the SAME owner lock (so client concurrency cannot help). This claims
+     * the whole contiguous sequence block under ONE lock acquisition and inserts all
+     * new rows in one multi-row INSERT.
+     *
+     * <p>Idempotency matches the single-doc path exactly: a doc whose {@code source_uri}
+     * (then {@code file_path}) already maps to a LIVE (non-tombstoned) document returns
+     * that existing tumbler and does NOT consume a sequence number — so a re-registration
+     * leaves no seq gap. Only genuinely-new docs draw from the claimed block.
+     *
+     * <p>Caller (the HTTP handler) caps the batch under the PostgreSQL 32767 bind-param
+     * ceiling; with ~24 columns per row the safe cap is 1000 rows (24000 params).
+     */
+    public java.util.List<String> registerDocumentMany(
+            String tenant, String ownerPrefix, java.util.List<java.util.Map<String, Object>> docs) {
+        if (TenantConstants.isWildcard(tenant)) {
+            throw new IllegalArgumentException(
+                "tenant '*' is a reserved sentinel and cannot own catalog entries");
+        }
+        if (docs == null || docs.isEmpty()) {
+            return java.util.List.of();
+        }
+        return tenantScope.withTenant(tenant, ctx -> {
+            // Ensure owner row exists (idempotent upsert, minimal fields) — once.
+            ctx.insertInto(CATALOG_OWNERS, CATALOG_OWNERS.TENANT_ID, CATALOG_OWNERS.TUMBLER_PREFIX, CATALOG_OWNERS.NAME, CATALOG_OWNERS.OWNER_TYPE,
+                           CATALOG_OWNERS.REPO_HASH, CATALOG_OWNERS.DESCRIPTION, CATALOG_OWNERS.REPO_ROOT, CATALOG_OWNERS.HEAD_HASH, CATALOG_OWNERS.NEXT_SEQ)
+               .values(tenant, ownerPrefix,
+                       s(docs.get(0), "owner_name", ownerPrefix),
+                       s(docs.get(0), "owner_type", "repo"),
+                       null, null, "", null, 0L)
+               .onConflict(CATALOG_OWNERS.TENANT_ID, CATALOG_OWNERS.TUMBLER_PREFIX)
+               .doNothing()
+               .execute();
+
+            // Batch idempotency: fetch existing LIVE docs for every source_uri and
+            // file_path in the batch in ONE query per direction, then join locally.
+            java.util.List<String> srcUris = new java.util.ArrayList<>();
+            java.util.List<String> filePaths = new java.util.ArrayList<>();
+            for (var d : docs) {
+                String su = s(d, "source_uri", "");
+                if (!su.isEmpty()) srcUris.add(su);
+                String fp = s(d, "file_path", "");
+                if (!fp.isEmpty()) filePaths.add(fp);
+            }
+            java.util.Map<String, String> tumblerBySrcUri = new java.util.HashMap<>();
+            if (!srcUris.isEmpty()) {
+                ctx.select(CATALOG_DOCUMENTS.SOURCE_URI, CATALOG_DOCUMENTS.TUMBLER)
+                   .from(CATALOG_DOCUMENTS)
+                   .where(CATALOG_DOCUMENTS.TENANT_ID.eq(tenant)
+                          .and(CATALOG_DOCUMENTS.SOURCE_URI.in(srcUris))
+                          .and(CATALOG_DOCUMENTS.DELETED_AT.isNull()))
+                   .fetch()
+                   .forEach(r -> tumblerBySrcUri.putIfAbsent(r.value1(), r.value2()));
+            }
+            java.util.Map<String, String> tumblerByFilePath = new java.util.HashMap<>();
+            if (!filePaths.isEmpty()) {
+                ctx.select(CATALOG_DOCUMENTS.FILE_PATH, CATALOG_DOCUMENTS.TUMBLER)
+                   .from(CATALOG_DOCUMENTS)
+                   .where(CATALOG_DOCUMENTS.TENANT_ID.eq(tenant)
+                          .and(CATALOG_DOCUMENTS.FILE_PATH.in(filePaths))
+                          .and(CATALOG_DOCUMENTS.TUMBLER.startsWith(ownerPrefix + "."))
+                          .and(CATALOG_DOCUMENTS.DELETED_AT.isNull()))
+                   .fetch()
+                   .forEach(r -> tumblerByFilePath.putIfAbsent(r.value1(), r.value2()));
+            }
+
+            // Resolve each doc to an existing tumbler or mark it NEW (input order).
+            String[] out = new String[docs.size()];
+            java.util.List<Integer> newIdx = new java.util.ArrayList<>();
+            for (int i = 0; i < docs.size(); i++) {
+                var d = docs.get(i);
+                String su = s(d, "source_uri", "");
+                String fp = s(d, "file_path", "");
+                String existing = null;
+                if (!su.isEmpty()) existing = tumblerBySrcUri.get(su);
+                if (existing == null && !fp.isEmpty()) existing = tumblerByFilePath.get(fp);
+                if (existing != null) {
+                    out[i] = existing;
+                } else {
+                    newIdx.add(i);
+                }
+            }
+
+            if (!newIdx.isEmpty()) {
+                // Claim a contiguous seq block under ONE FOR UPDATE lock.
+                long seq = ctx.select(CATALOG_OWNERS.NEXT_SEQ).from(CATALOG_OWNERS)
+                              .where(CATALOG_OWNERS.TENANT_ID.eq(tenant).and(CATALOG_OWNERS.TUMBLER_PREFIX.eq(ownerPrefix)))
+                              .forUpdate()
+                              .fetchOne(CATALOG_OWNERS.NEXT_SEQ);
+                long cursor = seq;
+
+                var insert = ctx.insertInto(CATALOG_DOCUMENTS,
+                        CATALOG_DOCUMENTS.TENANT_ID, CATALOG_DOCUMENTS.TUMBLER, CATALOG_DOCUMENTS.TITLE, CATALOG_DOCUMENTS.AUTHOR, CATALOG_DOCUMENTS.YEAR,
+                        CATALOG_DOCUMENTS.CONTENT_TYPE, CATALOG_DOCUMENTS.FILE_PATH, CATALOG_DOCUMENTS.CORPUS, CATALOG_DOCUMENTS.PHYSICAL_COLLECTION, CATALOG_DOCUMENTS.CHUNK_COUNT,
+                        CATALOG_DOCUMENTS.HEAD_HASH, CATALOG_DOCUMENTS.INDEXED_AT, F_DOC_META, CATALOG_DOCUMENTS.SOURCE_MTIME, CATALOG_DOCUMENTS.ALIAS_OF, CATALOG_DOCUMENTS.SOURCE_URI,
+                        CATALOG_DOCUMENTS.BIB_YEAR, CATALOG_DOCUMENTS.BIB_AUTHORS, CATALOG_DOCUMENTS.BIB_VENUE, CATALOG_DOCUMENTS.BIB_CITATION_COUNT,
+                        CATALOG_DOCUMENTS.BIB_SEMANTIC_SCHOLAR_ID, CATALOG_DOCUMENTS.BIB_OPENALEX_ID, CATALOG_DOCUMENTS.BIB_DOI, CATALOG_DOCUMENTS.BIB_ENRICHED_AT);
+                for (int idx : newIdx) {
+                    var fields = docs.get(idx);
+                    cursor += 1;
+                    String tumbler = ownerPrefix + "." + cursor;
+                    out[idx] = tumbler;
+                    String metaJson = jsonOrNull(fields.get("meta"));
+                    insert = insert.values(tenant, tumbler,
+                            s(fields, "title", ""),
+                            nne(s(fields, "author", null)),
+                            ni(i(fields, "year"), 0),
+                            nne(s(fields, "content_type", "")),
+                            nne(s(fields, "file_path", "")),
+                            nne(s(fields, "corpus", "")),
+                            nne(s(fields, "physical_collection", "")),
+                            ni(i(fields, "chunk_count"), 0),
+                            nne(s(fields, "head_hash", "")),
+                            nne(s(fields, "indexed_at", "")),
+                            jsonbVal(metaJson),
+                            nd(dbl(fields, "source_mtime")),
+                            nne(s(fields, "alias_of", "")),
+                            nne(s(fields, "source_uri", "")),
+                            ni(i(fields, "bib_year"), 0),
+                            nne(s(fields, "bib_authors", "")),
+                            nne(s(fields, "bib_venue", "")),
+                            ni(i(fields, "bib_citation_count"), 0),
+                            nne(s(fields, "bib_semantic_scholar_id", "")),
+                            nne(s(fields, "bib_openalex_id", "")),
+                            nne(s(fields, "bib_doi", "")),
+                            nne(s(fields, "bib_enriched_at", "")));
+                }
+                insert.execute();
+
+                // Advance next_seq by exactly the number of new docs claimed.
+                ctx.update(CATALOG_OWNERS)
+                   .set(CATALOG_OWNERS.NEXT_SEQ, cursor)
+                   .where(CATALOG_OWNERS.TENANT_ID.eq(tenant).and(CATALOG_OWNERS.TUMBLER_PREFIX.eq(ownerPrefix)))
+                   .execute();
+            }
+
+            return java.util.Arrays.asList(out);
+        });
+    }
+
     /** Fetch a document by tumbler. Returns null if not found. */
     public Map<String, Object> getDocument(String tenant, String tumbler) {
         return tenantScope.withTenant(tenant, ctx -> {
@@ -1063,19 +1209,86 @@ public final class CatalogRepository {
     /** Replace manifest for docId with the provided rows (atomic delete + insert). */
     public void writeManifest(String tenant, String docId, List<Map<String, Object>> rows) {
         tenantScope.withTenant(tenant, ctx -> {
-            ctx.deleteFrom(CATALOG_DOCUMENT_CHUNKS).where(CATALOG_DOCUMENT_CHUNKS.DOC_ID.eq(docId)).execute();
-            for (var row : rows) {
-                ctx.insertInto(CATALOG_DOCUMENT_CHUNKS,
-                        CATALOG_DOCUMENT_CHUNKS.TENANT_ID, CATALOG_DOCUMENT_CHUNKS.DOC_ID, CATALOG_DOCUMENT_CHUNKS.POSITION, CATALOG_DOCUMENT_CHUNKS.CHASH, CATALOG_DOCUMENT_CHUNKS.CHUNK_INDEX,
-                        CATALOG_DOCUMENT_CHUNKS.LINE_START, CATALOG_DOCUMENT_CHUNKS.LINE_END, CATALOG_DOCUMENT_CHUNKS.CHAR_START, CATALOG_DOCUMENT_CHUNKS.CHAR_END)
-                   .values(tenant, docId, i(row,"position"), s(row,"chash"), i(row,"chunk_index"),
-                           i(row,"line_start"), i(row,"line_end"), i(row,"char_start"), i(row,"char_end"))
-                   .execute();
-            }
+            writeManifestRows(ctx, tenant, docId, rows);
             return null;
         });
     }
 
+    /**
+     * Shared REPLACE body (delete all rows for docId, then insert the provided
+     * rows) used by both {@link #writeManifest} (one doc per transaction) and
+     * {@link #writeManifestMany} (N docs, one transaction each). Assumes
+     * {@code ctx} is already scoped to {@code tenant}. Does NOT touch
+     * documents.chunk_count — {@code writeManifest}'s public behavior is unchanged;
+     * the chunk_count fold-in is {@code writeManifestMany}'s addition.
+     */
+    private static void writeManifestRows(DSLContext ctx, String tenant, String docId,
+                                          List<Map<String, Object>> rows) {
+        ctx.deleteFrom(CATALOG_DOCUMENT_CHUNKS).where(CATALOG_DOCUMENT_CHUNKS.DOC_ID.eq(docId)).execute();
+        for (var row : rows) {
+            ctx.insertInto(CATALOG_DOCUMENT_CHUNKS,
+                    CATALOG_DOCUMENT_CHUNKS.TENANT_ID, CATALOG_DOCUMENT_CHUNKS.DOC_ID, CATALOG_DOCUMENT_CHUNKS.POSITION, CATALOG_DOCUMENT_CHUNKS.CHASH, CATALOG_DOCUMENT_CHUNKS.CHUNK_INDEX,
+                    CATALOG_DOCUMENT_CHUNKS.LINE_START, CATALOG_DOCUMENT_CHUNKS.LINE_END, CATALOG_DOCUMENT_CHUNKS.CHAR_START, CATALOG_DOCUMENT_CHUNKS.CHAR_END)
+               .values(tenant, docId, i(row,"position"), s(row,"chash"), i(row,"chunk_index"),
+                       i(row,"line_start"), i(row,"line_end"), i(row,"char_start"), i(row,"char_end"))
+               .execute();
+        }
+    }
+
+    /**
+     * Batch REPLACE manifest for multiple docs (bead nexus-u2kwq). Each doc is
+     * replaced in its OWN {@link TenantScope#withTenant} transaction that folds
+     * together the {@link #writeManifest} REPLACE (delete all rows + insert) AND
+     * a {@code documents.chunk_count = rows.size()} UPDATE — collapsing the
+     * client's separate {@code /manifest/write} + chunk_count {@code /update}
+     * round-trips into one atomic per-doc write. A failure on one doc rolls back
+     * only that doc and its doc_id is collected in {@code failed_doc_ids}; sibling
+     * docs are unaffected (per-doc atomicity, cross-doc isolation). Empty list is
+     * a no-op.
+     *
+     * @param docs each entry {@code {"doc_id": "...", "rows": [<manifest row>...]}}.
+     * @return {@code {docs: <int ok>, rows: <int total written>, failed_doc_ids: [...]}}.
+     */
+    public Map<String, Object> writeManifestMany(String tenant, List<Map<String, Object>> docs) {
+        int okDocs = 0;
+        int totalRows = 0;
+        List<String> failed = new ArrayList<>();
+        if (docs != null) {
+            for (Map<String, Object> d : docs) {
+                String docId = s(d, "doc_id");
+                Object rawRows = d.get("rows");
+                @SuppressWarnings("unchecked")
+                List<Map<String, Object>> rows = rawRows instanceof List<?> l
+                    ? (List<Map<String, Object>>) l
+                    : List.of();
+                try {
+                    if (docId == null || docId.isBlank()) {
+                        throw new IllegalArgumentException("'doc_id' required");
+                    }
+                    tenantScope.withTenant(tenant, ctx -> {
+                        writeManifestRows(ctx, tenant, docId, rows);
+                        ctx.update(CATALOG_DOCUMENTS)
+                           .set(CATALOG_DOCUMENTS.CHUNK_COUNT, rows.size())
+                           .where(CATALOG_DOCUMENTS.TUMBLER.eq(docId))
+                           .execute();
+                        return null;
+                    });
+                    okDocs++;
+                    totalRows += rows.size();
+                } catch (Exception e) {
+                    log.debug("event=write_manifest_many_doc_failed tenant={} doc_id={} error={}",
+                              tenant, docId, e.getMessage());
+                    failed.add(docId);
+                }
+            }
+        }
+        Map<String, Object> result = new LinkedHashMap<>();
+        result.put("docs", okDocs);
+        result.put("rows", totalRows);
+        result.put("failed_doc_ids", failed);
+        return result;
+    }
+
     /** Append manifest rows (upsert by position). */
     public void appendManifestChunks(String tenant, String docId, List<Map<String, Object>> rows) {
         tenantScope.withTenant(tenant, ctx -> {

{conexus-6.3.1 → conexus-6.3.2}/service/src/main/java/dev/nexus/service/db/ChashRepository.java

@@ -173,15 +173,35 @@ public final class ChashRepository {
         if (chashes == null || chashes.isEmpty()) return;
 
         OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC);
+        // distinct(): a multi-VALUES INSERT .. ON CONFLICT DO UPDATE raises
+        // "cannot affect row a second time" (-> HTTP 500) when the same chash
+        // appears twice in one statement, and real files emit duplicate chunk
+        // text (nexus-85z0y). Dedup is semantics-free: a chash is a content
+        // hash, so every occurrence is identical.
+        // sorted(): the multi-row INSERT locks CHASH_INDEX rows in values() order.
+        // tenant + collection are constant within this call, so chash is the only
+        // varying part of the (tenant, chash, physical_collection) conflict key —
+        // sorting by chash gives every concurrent batch one global lock order and
+        // removes the cross-batch deadlock (SQLSTATE 40P01, nexus-ps9wb; same class as
+        // PgVectorRepository.upsertChunks). distinct(): a multi-VALUES INSERT ..
+        // ON CONFLICT DO UPDATE raises "cannot affect row a second time" (-> HTTP 500)
+        // when the same chash appears twice in one statement, and real files emit
+        // duplicate chunk text (nexus-85z0y). Dedup is semantics-free: a chash is a
+        // content hash, so every occurrence is identical.
         List<String> valid = chashes.stream()
                 .filter(c -> c != null && !c.isBlank())
+                .distinct()
+                .sorted()
                 .toList();
         if (valid.isEmpty()) return;
 
         // Own short committed txn — bounds the first-registration convoy DURATION
         // (see registerCollectionShortTxn doc); also handles markKnown post-commit.
         registerCollectionShortTxn(tenant, collection);
-        tenantScope.withTenant(tenant, ctx -> {
+        // nexus-ps9wb belt: retry a residual cross-path deadlock (the sort removes the
+        // same-batch cycle; a concurrent writer on a different lock order can still
+        // deadlock). Idempotent ON CONFLICT batch, victim already rolled back → safe.
+        DeadlockRetry.run(collection, () -> tenantScope.withTenant(tenant, ctx -> {
             var insert = ctx.insertInto(CHASH_INDEX,
                                         CHASH_INDEX.TENANT_ID, CHASH_INDEX.CHASH, CHASH_INDEX.PHYSICAL_COLLECTION, CHASH_INDEX.CREATED_AT);
             var step = insert.values(tenant, valid.get(0), collection, now);
@@ -193,7 +213,7 @@ public final class ChashRepository {
                 .set(CHASH_INDEX.CREATED_AT, DSL.field("EXCLUDED.created_at", OffsetDateTime.class))
                 .execute();
             return null;
-        });
+        }));
     }
 
     // ── lookup ─────────────────────────────────────────────────────────────────

conexus-6.3.2/service/src/main/java/dev/nexus/service/db/DeadlockRetry.java

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 Hal Hildebrand. All rights reserved.
+package dev.nexus.service.db;
+
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import java.sql.SQLException;
+import java.util.concurrent.ThreadLocalRandom;
+import java.util.function.Supplier;
+
+/**
+ * Shared deadlock-retry belt for the service's multi-row
+ * {@code INSERT ... ON CONFLICT (...) DO UPDATE} write paths (bead nexus-ps9wb).
+ *
+ * <p><strong>Background.</strong> Two concurrent multi-row upsert batches into the
+ * same table that touch an overlapping set of conflict keys in DIFFERENT arrival
+ * orders lock the shared rows in opposite orders within their single statement →
+ * lock cycle → Postgres kills a victim with {@code deadlock detected} (SQLSTATE
+ * 40P01) → the caller sees HTTP 500. The PRIMARY fix at each call site is to sort a
+ * batch's rows by the ON CONFLICT key before binding, so every concurrent batch
+ * acquires row locks in one global order and no cycle can form. This helper is the
+ * BELT for residual deadlocks the per-site sort cannot rule out — a concurrent
+ * delete, or a different repository writing an overlapping keyspace in its own order.
+ *
+ * <p><strong>Safety.</strong> The deadlock victim's transaction is ALREADY rolled
+ * back by Postgres before the exception surfaces, so re-running an idempotent
+ * {@code ON CONFLICT DO UPDATE} batch is safe (no partial state, no double effect).
+ * Attempts are bounded ({@link #MAX_ATTEMPTS}) with jittered backoff; the original
+ * exception propagates unchanged on exhaustion or for any non-deadlock error. The
+ * wrapped unit MUST be only the DB transaction — never anything with external side
+ * effects (e.g. embedding calls), or a retry would repeat them.
+ */
+public final class DeadlockRetry {
+
+    private static final Logger log = LoggerFactory.getLogger(DeadlockRetry.class);
+
+    /** Total attempts (initial try + retries) before the deadlock propagates. */
+    static final int MAX_ATTEMPTS = 4;
+
+    /** PostgreSQL SQLSTATE for {@code deadlock_detected}. */
+    static final String SQLSTATE_DEADLOCK = "40P01";
+
+    private DeadlockRetry() {
+    }
+
+    /**
+     * Run {@code writeTxn} (a single idempotent DB transaction), retrying on a
+     * deadlock (SQLSTATE 40P01) up to {@link #MAX_ATTEMPTS} total attempts.
+     *
+     * @param context short label for the retry log line (e.g. the collection name)
+     * @param writeTxn the transaction to run; MUST be free of external side effects
+     */
+    public static void run(String context, Runnable writeTxn) {
+        run(context, () -> {
+            writeTxn.run();
+            return null;
+        });
+    }
+
+    /**
+     * {@link #run(String, Runnable)} variant returning the transaction's value.
+     */
+    public static <T> T run(String context, Supplier<T> writeTxn) {
+        int attempt = 0;
+        while (true) {
+            try {
+                return writeTxn.get();
+            } catch (RuntimeException ex) {
+                if (isDeadlock(ex) && ++attempt < MAX_ATTEMPTS) {
+                    log.warn("event=deadlock_retry context={} attempt={} maxAttempts={}",
+                            context, attempt, MAX_ATTEMPTS);
+                    backoff(attempt);
+                    continue;
+                }
+                throw ex;
+            }
+        }
+    }
+
+    /**
+     * True if a {@code deadlock_detected} (SQLSTATE 40P01) SQLException appears
+     * anywhere in {@code t}'s cause chain. jOOQ wraps the driver SQLException in a
+     * {@code DataAccessException} (and TenantScope may further wrap that in a
+     * RuntimeException), so the SQLException is a cause, not the top-level throwable —
+     * hence the depth-bounded chain walk, which handles either wrapper.
+     */
+    static boolean isDeadlock(Throwable t) {
+        Throwable c = t;
+        for (int depth = 0; c != null && depth < 32; depth++, c = c.getCause()) {
+            if (c instanceof SQLException se && SQLSTATE_DEADLOCK.equals(se.getSQLState())) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    private static void backoff(int attempt) {
+        long ms = Math.min(attempt, MAX_ATTEMPTS) * (10L + ThreadLocalRandom.current().nextLong(20));
+        try {
+            Thread.sleep(ms);
+        } catch (InterruptedException ie) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException("interrupted during deadlock-retry backoff", ie);
+        }
+    }
+}