conexus 6.3.3__tar.gz → 6.3.4__tar.gz

{conexus-6.3.3 → conexus-6.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: conexus
-Version: 6.3.3
+Version: 6.3.4
 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.3 → conexus-6.3.4}/mcpb/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "conexus-mcpb"
-version = "6.3.3"
+version = "6.3.4"
 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.3",
+    "conexus[local]>=6.3.4",
 ]
 
 [tool.uv]

{conexus-6.3.3 → conexus-6.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "6.3.3"
+version = "6.3.4"
 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.3 → conexus-6.3.4}/service/src/main/java/dev/nexus/service/db/CatalogRepository.java

@@ -36,6 +36,7 @@ import com.fasterxml.jackson.databind.ObjectMapper;
 import org.jooq.Condition;
 import org.jooq.DSLContext;
 import org.jooq.Field;
+import org.jooq.Query;
 import org.jooq.SelectField;
 import org.jooq.Table;
 import org.jooq.UpdateSetMoreStep;
@@ -669,6 +670,108 @@ public final class CatalogRepository {
 
     public int updateDocument(String tenant, String tumbler, Map<String, Object> fields) {
         if (fields.isEmpty()) return 0;
+        return tenantScope.withTenant(tenant, ctx -> {
+            Query query = buildUpdateDocumentQuery(ctx, tenant, tumbler, fields);
+            return query == null ? 0 : query.execute();
+        });
+    }
+
+    /**
+     * Batch-update mutable document fields for N documents in ONE round trip
+     * (nexus-xedhp, duoak.11 follow-up to the register_many fix above).
+     *
+     * <p>{@code writer.update()} per changed doc was the WAN-round-trip sink:
+     * a HEAD bump (any new git commit) flips every indexed doc's stored
+     * {@code head_hash} to "changed", forcing the indexer's catalog hook
+     * through one serial {@code POST /update} per file — 175.5s / 1718 files
+     * (~102ms/file) on this repo's own shakeout. Each entry in *updates*
+     * carries the same shape as {@link #updateDocument}'s {@code fields} map
+     * plus a {@code "tumbler"} key identifying the row.
+     *
+     * <p>Executed as ONE {@code ctx.batch(...)} — i.e. one JDBC
+     * {@code Statement.addBatch()}/{@code executeBatch()} round trip to
+     * Postgres, not N sequential {@code execute()} calls. This is standard
+     * JDBC batching, the same mechanism used for heterogeneous-shape batch
+     * writes throughout the JDBC ecosystem; jOOQ's {@code batch(Query...)}
+     * groups identical-SQL queries into one {@code PreparedStatement} batch
+     * and any remaining distinct-SQL queries into one {@code Statement}
+     * batch, flushing everything via a single {@code executeBatch()} — never
+     * a per-query round trip. (An attempt at a single hand-built
+     * multi-row {@code UPDATE ... FROM (VALUES ...)} statement was tried
+     * here first and reverted: jOOQ's typed {@code DSL.values(RowN...)} API
+     * requires uniform per-column types across all rows, which this
+     * whitelist's heterogeneous optional fields can't satisfy without
+     * fighting Postgres's NULL-parameter type-inference rules; the raw-SQL
+     * {@code DSL.table("(VALUES {0})", ...)} template compiles but its
+     * `.field(...)` accessors don't resolve column metadata at all — this
+     * specific failure (a {@code NullPointerException} on the returned
+     * field) was reproduced against the real Postgres testcontainer suite
+     * below. The tests below verify functional correctness, per-entry
+     * failure isolation, and idempotency — NOT round-trip count or
+     * statement count; the "one JDBC round trip" claim for {@code
+     * ctx.batch(...)} on heterogeneous SQL is drawn from jOOQ's documented
+     * {@code batch(Query...)} behavior, not independently measured here.)
+     *
+     * <p>Per-doc failure isolation mirrors {@code register_many}: a single
+     * malformed entry (missing tumbler, non-updatable column) is excluded
+     * from the batch and marked {@code -1} in the result rather than
+     * aborting the whole call — the caller's existing per-file try/except
+     * ghost-class-isolation contract depends on partial-batch survivability.
+     *
+     * @return per-index update counts aligned 1:1 with the input list:
+     *         {@code 1} updated, {@code 0} not found/tombstoned/no-op,
+     *         {@code -1} malformed entry (build-time rejection, never sent).
+     */
+    public List<Integer> updateDocumentsMany(String tenant, List<Map<String, Object>> updates) {
+        if (updates.isEmpty()) return List.of();
+        return tenantScope.withTenant(tenant, ctx -> {
+            Integer[] resultSlots = new Integer[updates.size()];
+            var queries = new ArrayList<Query>();
+            var queryIndexes = new ArrayList<Integer>();  // index into `updates` for each entry in `queries`
+
+            for (int i = 0; i < updates.size(); i++) {
+                var upd = updates.get(i);
+                Object tumblerObj = upd.get("tumbler");
+                if (!(tumblerObj instanceof String tumbler) || tumbler.isBlank()) {
+                    resultSlots[i] = -1;
+                    continue;
+                }
+                Map<String, Object> fields = new LinkedHashMap<>(upd);
+                fields.remove("tumbler");
+                Query query;
+                try {
+                    query = buildUpdateDocumentQuery(ctx, tenant, tumbler, fields);
+                } catch (IllegalArgumentException e) {
+                    resultSlots[i] = -1;
+                    continue;
+                }
+                if (query == null) {
+                    resultSlots[i] = 0;
+                    continue;
+                }
+                queryIndexes.add(i);
+                queries.add(query);
+            }
+            if (!queries.isEmpty()) {
+                int[] batchResults = ctx.batch(queries).execute();
+                for (int q = 0; q < queryIndexes.size(); q++) {
+                    resultSlots[queryIndexes.get(q)] = batchResults[q];
+                }
+            }
+            return java.util.Arrays.asList(resultSlots);
+        });
+    }
+
+    /**
+     * Shared SET-clause builder for {@link #updateDocument} and
+     * {@link #updateDocumentsMany} — same column whitelist, same
+     * {@code deleted_at}-strip, same {@code meta} jsonb-merge semantics.
+     * Returns {@code null} when *fields* yields no settable column (mirrors
+     * {@code updateDocument}'s 0-row short-circuit).
+     */
+    private Query buildUpdateDocumentQuery(
+        DSLContext ctx, String tenant, String tumbler, Map<String, Object> fields
+    ) {
         for (String key : fields.keySet()) {
             // deleted_at keeps its documented silent-strip contract (callers must use
             // trash/restore); every OTHER unknown key is a caller error — fail loud.
@@ -678,43 +781,40 @@ public final class CatalogRepository {
                     + "' (allowed: " + UPDATABLE_DOC_COLUMNS + ")");
             }
         }
-        return tenantScope.withTenant(tenant, ctx -> {
-            var step = ctx.update(CATALOG_DOCUMENTS);
-            UpdateSetMoreStep<?> more = null;
-            for (var e : fields.entrySet()) {
-                if (e.getValue() == null) continue;
-                // Strip deleted_at — must not be settable via updateDocument
-                if ("deleted_at".equals(e.getKey())) continue;
-                // metadata is a jsonb column: callers pass it as an object (or JSON
-                // string) under "meta"/"metadata". A bare set() of a Map fails with
-                // "LinkedHashMap is not supported in dialect POSTGRES"; JSON-encode and
-                // bind as jsonb, mirroring upsertDocument (RDR-168 nexus-njrcn.7).
-                // nexus-ke45f: MERGE, not replace — local Catalog.update() does
-                // dict.update (add/overwrite keys, never remove), and every
-                // writer.update(meta=...) caller (enrich write-back, catalog
-                // hook, dt stamp, remediation) is written against that
-                // contract; the bare SET silently dropped pre-existing keys
-                // in service mode. jsonb_concat == the || operator.
-                if ("meta".equals(e.getKey()) || "metadata".equals(e.getKey())) {
-                    Field<String> merged = DSL.function("jsonb_concat", String.class,
-                        DSL.coalesce(F_DOC_META, jsonbVal("{}")),
-                        jsonbVal(jsonOrNull(e.getValue())));
-                    more = (more == null)
-                        ? step.set(F_DOC_META, merged)
-                        : more.set(F_DOC_META, merged);
-                    continue;
-                }
-                @SuppressWarnings("unchecked")
-                Field<Object> f = (Field<Object>) DSL.field(DSL.name("catalog_documents", e.getKey()));
-                more = (more == null) ? step.set(f, e.getValue()) : more.set(f, e.getValue());
+        var step = ctx.update(CATALOG_DOCUMENTS);
+        UpdateSetMoreStep<?> more = null;
+        for (var e : fields.entrySet()) {
+            if (e.getValue() == null) continue;
+            // Strip deleted_at — must not be settable via updateDocument
+            if ("deleted_at".equals(e.getKey())) continue;
+            // metadata is a jsonb column: callers pass it as an object (or JSON
+            // string) under "meta"/"metadata". A bare set() of a Map fails with
+            // "LinkedHashMap is not supported in dialect POSTGRES"; JSON-encode and
+            // bind as jsonb, mirroring upsertDocument (RDR-168 nexus-njrcn.7).
+            // nexus-ke45f: MERGE, not replace — local Catalog.update() does
+            // dict.update (add/overwrite keys, never remove), and every
+            // writer.update(meta=...) caller (enrich write-back, catalog
+            // hook, dt stamp, remediation) is written against that
+            // contract; the bare SET silently dropped pre-existing keys
+            // in service mode. jsonb_concat == the || operator.
+            if ("meta".equals(e.getKey()) || "metadata".equals(e.getKey())) {
+                Field<String> merged = DSL.function("jsonb_concat", String.class,
+                    DSL.coalesce(F_DOC_META, jsonbVal("{}")),
+                    jsonbVal(jsonOrNull(e.getValue())));
+                more = (more == null)
+                    ? step.set(F_DOC_META, merged)
+                    : more.set(F_DOC_META, merged);
+                continue;
             }
-            if (more == null) return 0;
-            // AND deleted_at IS NULL: refuse to update tombstoned documents
-            return more.where(CATALOG_DOCUMENTS.TENANT_ID.eq(tenant)
-                              .and(CATALOG_DOCUMENTS.TUMBLER.eq(tumbler))
-                              .and(CATALOG_DOCUMENTS.DELETED_AT.isNull()))
-                       .execute();
-        });
+            @SuppressWarnings("unchecked")
+            Field<Object> f = (Field<Object>) DSL.field(DSL.name("catalog_documents", e.getKey()));
+            more = (more == null) ? step.set(f, e.getValue()) : more.set(f, e.getValue());
+        }
+        if (more == null) return null;
+        // AND deleted_at IS NULL: refuse to update tombstoned documents
+        return more.where(CATALOG_DOCUMENTS.TENANT_ID.eq(tenant)
+                          .and(CATALOG_DOCUMENTS.TUMBLER.eq(tumbler))
+                          .and(CATALOG_DOCUMENTS.DELETED_AT.isNull()));
     }
 
     /**
@@ -734,6 +834,38 @@ public final class CatalogRepository {
         );
     }
 
+    /**
+     * Batch-tombstone N documents in ONE round trip (nexus-xedhp follow-up:
+     * completes the update_many/register_many/delete_many batch trio).
+     *
+     * <p>Unlike {@link #updateDocumentsMany}, every row shares the identical
+     * {@code SET deleted_at = NOW()} — no per-row heterogeneous values, so a
+     * plain {@code WHERE tumbler = ANY(?)} multi-row match is both simplest
+     * and a genuine single SQL statement (no VALUES-table / batch-API
+     * ambiguity to navigate). {@code RETURNING tumbler} identifies exactly
+     * which of the input tumblers were actually tombstoned (already-deleted
+     * or non-existent tumblers are silently excluded, same as the single-doc
+     * {@link #deleteDocument}'s idempotent 0-return).
+     *
+     * @return the SET of tumblers that were tombstoned by this call (a
+     *         subset of *tumblers*; order not significant — callers map
+     *         membership, not position, unlike updateDocumentsMany's
+     *         positional contract, since there's only one outcome shape
+     *         here: deleted or not).
+     */
+    public Set<String> deleteDocumentsMany(String tenant, List<String> tumblers) {
+        if (tumblers.isEmpty()) return Set.of();
+        return tenantScope.withTenant(tenant, ctx ->
+            new java.util.HashSet<>(ctx.update(CATALOG_DOCUMENTS)
+                .set(CATALOG_DOCUMENTS.DELETED_AT, DSL.currentOffsetDateTime())
+                .where(CATALOG_DOCUMENTS.TUMBLER.in(tumblers)
+                       .and(CATALOG_DOCUMENTS.TENANT_ID.eq(tenant))
+                       .and(CATALOG_DOCUMENTS.DELETED_AT.isNull()))
+                .returning(CATALOG_DOCUMENTS.TUMBLER)
+                .fetch(CATALOG_DOCUMENTS.TUMBLER))
+        );
+    }
+
     /**
      * FTS search over title/author/corpus/file_path using OR'd tsquery.
      * Optionally filter by content_type. Returns up to limit results.

{conexus-6.3.3 → conexus-6.3.4}/service/src/main/java/dev/nexus/service/http/CatalogHandler.java

@@ -33,6 +33,8 @@ import java.util.*;
  *   GET   /v1/catalog/list               list documents (paginated)
  *   GET   /v1/catalog/search             FTS search
  *   POST  /v1/catalog/update             update document fields
+ *   POST  /v1/catalog/update_many        batch-update fields for N documents (nexus-xedhp)
+ *   POST  /v1/catalog/delete_many        batch-tombstone N documents (nexus-xedhp)
  *   DELETE /v1/catalog/delete            delete document by tumbler
  *   POST  /v1/catalog/link               upsert link
  *   POST  /v1/catalog/unlink             delete link
@@ -118,7 +120,9 @@ public final class CatalogHandler implements HttpHandler {
                 case "/list"                  -> handleList(exchange, tenant, method);
                 case "/search"                -> handleSearch(exchange, tenant, method);
                 case "/update"                -> handleUpdate(exchange, tenant, method);
+                case "/update_many"           -> handleUpdateMany(exchange, tenant, method);
                 case "/delete"                -> handleDelete(exchange, tenant, method);
+                case "/delete_many"           -> handleDeleteMany(exchange, tenant, method);
                 case "/resolve"               -> handleResolve(exchange, tenant, method);
                 case "/stats"                 -> handleStats(exchange, tenant, method);
 
@@ -313,6 +317,83 @@ public final class CatalogHandler implements HttpHandler {
         HttpUtil.send(exchange, 200, "{\"updated\":" + updated + "}");
     }
 
+    /**
+     * POST /v1/catalog/update_many — batch-update N documents' mutable fields
+     * in ONE round trip (nexus-xedhp, duoak.11 follow-up).
+     *
+     * <p>Body: {"updates": [{"tumbler": "1.1.3", "head_hash": "...", ...}, ...]}
+     * Response: {"updated": [1, 1, 0, ...]}  (per-entry update count, aligned
+     * 1:1 with the input — 0 means not found / tombstoned / no-op; a
+     * non-updatable-column entry is -1 (marked, not dropped) — the entry's
+     * OWN column-whitelist violation does NOT abort the rest of the batch,
+     * mirroring register_many's per-doc failure isolation. A malformed
+     * *shape* (non-list body, non-object element) is a client bug, not a
+     * per-doc data problem, and 400s rather than silently shrinking the
+     * response array — mirrors handleManifestWriteMany's review #2 fix.
+     *
+     * <p>Capped at {@value #MAX_BATCH_DOC_IDS} rows, same bind-limit rationale
+     * as register_many.
+     */
+    @SuppressWarnings("unchecked")
+    private void handleUpdateMany(HttpExchange exchange, String tenant, String method) throws IOException {
+        if (!"POST".equals(method)) { HttpUtil.send(exchange, 405, "{\"error\":\"method not allowed\"}"); return; }
+        Map<String, Object> body = readBody(exchange);
+        Object raw = body.get("updates");
+        if (!(raw instanceof List<?> l)) {
+            HttpUtil.send(exchange, 400, "{\"error\":\"'updates' must be a list\"}"); return;
+        }
+        if (l.stream().anyMatch(o -> !(o instanceof Map))) {
+            HttpUtil.send(exchange, 400, "{\"error\":\"every 'updates' element must be an object\"}"); return;
+        }
+        List<Map<String, Object>> updates = l.stream().map(o -> (Map<String, Object>) o).toList();
+        if (updates.size() > MAX_BATCH_DOC_IDS) {
+            HttpUtil.send(exchange, 400, "{\"error\":\"too many updates (max "
+                + MAX_BATCH_DOC_IDS + ")\"}"); return;
+        }
+        var counts = repo.updateDocumentsMany(tenant, updates);
+        HttpUtil.send(exchange, 200, MAPPER.writeValueAsString(Map.of("updated", counts)));
+    }
+
+    /**
+     * POST /v1/catalog/delete_many — batch-tombstone N documents in ONE
+     * round trip (nexus-xedhp: completes the update_many/register_many/
+     * delete_many batch trio).
+     *
+     * <p>Body: {"tumblers": ["1.1.3", "1.1.4", ...]}
+     * Response: {"deleted": ["1.1.3", ...]}  (the subset of input tumblers
+     * that were actually tombstoned — already-deleted or non-existent
+     * tumblers are silently excluded, same idempotent semantics as the
+     * single-doc DELETE). NOT positionally aligned with the input (unlike
+     * update_many) — a duplicate or already-deleted tumbler collapses to
+     * one membership check; callers needing per-position outcomes should
+     * not assume this response mirrors input order/length.
+     *
+     * <p>A malformed *shape* (non-list body, non-string element) 400s
+     * rather than silently shrinking the input — mirrors
+     * handleManifestWriteMany's review #2 fix and handleUpdateMany above.
+     *
+     * <p>Capped at {@value #MAX_BATCH_DOC_IDS} rows, same bind-limit
+     * rationale as register_many / update_many.
+     */
+    private void handleDeleteMany(HttpExchange exchange, String tenant, String method) throws IOException {
+        if (!"POST".equals(method)) { HttpUtil.send(exchange, 405, "{\"error\":\"method not allowed\"}"); return; }
+        Map<String, Object> body = readBody(exchange);
+        Object raw = body.get("tumblers");
+        if (!(raw instanceof List<?> l)) {
+            HttpUtil.send(exchange, 400, "{\"error\":\"'tumblers' must be a list\"}"); return;
+        }
+        if (l.stream().anyMatch(o -> !(o instanceof String))) {
+            HttpUtil.send(exchange, 400, "{\"error\":\"every 'tumblers' element must be a string\"}"); return;
+        }
+        List<String> tumblers = l.stream().map(o -> (String) o).toList();
+        if (tumblers.size() > MAX_BATCH_DOC_IDS) {
+            HttpUtil.send(exchange, 400, "{\"error\":\"too many tumblers (max "
+                + MAX_BATCH_DOC_IDS + ")\"}"); return;
+        }
+        var deleted = repo.deleteDocumentsMany(tenant, tumblers);
+        HttpUtil.send(exchange, 200, MAPPER.writeValueAsString(Map.of("deleted", deleted)));
+    }
+
     /** DELETE /v1/catalog/delete?tumbler=X */
     private void handleDelete(HttpExchange exchange, String tenant, String method) throws IOException {
         if (!"DELETE".equals(method) && !"POST".equals(method)) {

{conexus-6.3.3 → conexus-6.3.4}/service/src/test/java/dev/nexus/service/CatalogRepositoryTest.java

@@ -370,6 +370,101 @@ class CatalogRepositoryTest {
         assertThat(repo.getDocument(TENANT_A, "2.9").get("title")).isEqualTo("Still Guarded");
     }
 
+    @Test @Order(135)
+    void document_updateDocumentsMany_batchesHeterogeneousUpdatesInOneRoundTrip() {
+        // nexus-xedhp: replaces N serial writer.update() calls with one
+        // updateDocumentsMany() batch — each entry may set DIFFERENT fields
+        // (mirrors the indexer catalog hook's real per-file payload shape:
+        // head_hash is repo-wide but physical_collection/meta/source_mtime
+        // vary per file).
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.20", "title", "Many A", "content_type", "code",
+            "corpus", "code", "physical_collection", "code__nexus__v1"));
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.21", "title", "Many B", "content_type", "docs",
+            "corpus", "docs", "physical_collection", "docs__nexus__v1",
+            "metadata", Map.of("content_hash", "keepme")));
+
+        List<Integer> results = repo.updateDocumentsMany(TENANT_A, List.of(
+            Map.of("tumbler", "2.20", "head_hash", "abc123", "source_mtime", 111.0),
+            Map.of("tumbler", "2.21", "head_hash", "abc123",
+                   "meta", Map.of("bib_checked", true))
+        ));
+        assertThat(results).containsExactly(1, 1);
+
+        var doc20 = repo.getDocument(TENANT_A, "2.20");
+        assertThat(doc20.get("head_hash")).isEqualTo("abc123");
+
+        var doc21 = repo.getDocument(TENANT_A, "2.21");
+        assertThat(doc21.get("head_hash")).isEqualTo("abc123");
+        @SuppressWarnings("unchecked")
+        Map<String, Object> meta21 = (Map<String, Object>) doc21.get("metadata");
+        assertThat(meta21.get("content_hash")).as("meta merge semantics preserved in batch path").isEqualTo("keepme");
+        assertThat(meta21.get("bib_checked")).isEqualTo(true);
+    }
+
+    @Test @Order(136)
+    void document_updateDocumentsMany_isolatesPerEntryFailures() {
+        // A malformed entry (missing tumbler, non-updatable column) must not
+        // abort the rest of the batch — mirrors register_many's per-doc
+        // failure isolation, which the indexer's catalog hook depends on.
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.22", "title", "Survivor", "content_type", "code",
+            "corpus", "code"));
+
+        List<Integer> results = repo.updateDocumentsMany(TENANT_A, java.util.Arrays.asList(
+            Map.of("no_tumbler_key", "x"),
+            Map.of("tumbler", "2.22", "head_hash", "def456"),
+            Map.of("tumbler", "2.999-does-not-exist", "head_hash", "def456"),
+            Map.of("tumbler", "2.22", "no_such_column", "y")
+        ));
+        assertThat(results).containsExactly(-1, 1, 0, -1);
+
+        var doc = repo.getDocument(TENANT_A, "2.22");
+        assertThat(doc.get("head_hash")).isEqualTo("def456");
+    }
+
+    @Test @Order(137)
+    void document_updateDocumentsMany_emptyListReturnsEmpty() {
+        assertThat(repo.updateDocumentsMany(TENANT_A, List.of())).isEmpty();
+    }
+
+    @Test @Order(138)
+    void document_deleteDocumentsMany_tombstonesInOneRoundTrip() {
+        // nexus-xedhp: completes the update_many/register_many/delete_many
+        // batch trio — replaces N serial writer.delete_document() calls.
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.30", "title", "Del A", "content_type", "code", "corpus", "code"));
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.31", "title", "Del B", "content_type", "code", "corpus", "code"));
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.32", "title", "Survivor", "content_type", "code", "corpus", "code"));
+
+        Set<String> deleted = repo.deleteDocumentsMany(
+            TENANT_A, List.of("2.30", "2.31", "2.999-does-not-exist"));
+
+        assertThat(deleted).containsExactlyInAnyOrder("2.30", "2.31");
+        assertThat(repo.getDocument(TENANT_A, "2.30")).isNull();
+        assertThat(repo.getDocument(TENANT_A, "2.31")).isNull();
+        assertThat(repo.getDocument(TENANT_A, "2.32")).isNotNull();
+    }
+
+    @Test @Order(139)
+    void document_deleteDocumentsMany_idempotentOnAlreadyTombstoned() {
+        repo.upsertDocument(TENANT_A, Map.of(
+            "tumbler", "2.33", "title", "Once", "content_type", "code", "corpus", "code"));
+        repo.deleteDocument(TENANT_A, "2.33");
+
+        Set<String> deleted = repo.deleteDocumentsMany(TENANT_A, List.of("2.33"));
+
+        assertThat(deleted).as("already-tombstoned tumbler is not re-reported as deleted").isEmpty();
+    }
+
+    @Test @Order(140)
+    void document_deleteDocumentsMany_emptyListReturnsEmpty() {
+        assertThat(repo.deleteDocumentsMany(TENANT_A, List.of())).isEmpty();
+    }
+
     @Test @Order(14)
     void document_delete() {
         repo.upsertDocument(TENANT_A, Map.of(