conexus 6.2.0__tar.gz → 6.3.0__tar.gz

{conexus-6.2.0 → conexus-6.3.0}/PKG-INFO

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

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

{conexus-6.2.0 → conexus-6.3.0}/pyproject.toml

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

@@ -531,8 +531,35 @@ public final class CatalogRepository {
      * Silently strips {@code deleted_at} from the input map — callers must use
      * {@code document_trash} / {@code document_restore} to manage the tombstone column.
      */
+    /**
+     * Settable columns for {@link #updateDocument} (wave review, SQL audit CRITICAL):
+     * request JSON keys become SET targets via {@code DSL.field(DSL.name(...))}, so
+     * WITHOUT this whitelist any body key was an arbitrary-column write from
+     * {@code POST /v1/catalog/update} — including {@code tenant_id} (re-homing a
+     * document across tenants) and lifecycle columns like {@code created_at}.
+     * The set mirrors the local {@code Catalog.update} mutable surface
+     * ({@link #documentFields()} minus the identity/lifecycle columns:
+     * tumbler, tenant_id, deleted_at, created_at). Unknown keys fail loud with
+     * {@code IllegalArgumentException} → 400, never a silent skip.
+     */
+    private static final Set<String> UPDATABLE_DOC_COLUMNS = Set.of(
+        "title", "author", "year", "content_type", "file_path", "corpus",
+        "physical_collection", "chunk_count", "head_hash", "indexed_at",
+        "meta", "metadata", "source_mtime", "alias_of", "source_uri",
+        "bib_year", "bib_authors", "bib_venue", "bib_citation_count",
+        "bib_semantic_scholar_id", "bib_openalex_id", "bib_doi", "bib_enriched_at");
+
     public int updateDocument(String tenant, String tumbler, Map<String, Object> fields) {
         if (fields.isEmpty()) return 0;
+        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.
+            if (!"deleted_at".equals(key) && !UPDATABLE_DOC_COLUMNS.contains(key)) {
+                throw new IllegalArgumentException(
+                    "updateDocument: column not updatable: '" + key
+                    + "' (allowed: " + UPDATABLE_DOC_COLUMNS + ")");
+            }
+        }
         return tenantScope.withTenant(tenant, ctx -> {
             var step = ctx.update(T_DOCS);
             UpdateSetMoreStep<?> more = null;
@@ -1420,6 +1447,16 @@ public final class CatalogRepository {
      * streaming buffer and the entire local-mode (sqlite/Chroma) cascade.
      */
     public Map<String, Integer> deleteCollection(String tenant, String name) {
+        Map<String, Integer> counts = deleteCollectionTxn(tenant, name);
+        // Post-commit (nexus-h8rf6 wave review): the registry row is gone; a stale
+        // CollectionRegistry entry would make later writers silently skip
+        // re-registration if the name is reused. Same post-commit discipline as
+        // markKnown — see CollectionRegistry.evict.
+        CollectionRegistry.evict(tenant, name);
+        return counts;
+    }
+
+    private Map<String, Integer> deleteCollectionTxn(String tenant, String name) {
         return tenantScope.withTenant(tenant, ctx -> {
             Map<String, Integer> counts = new LinkedHashMap<>();
             // 1. T3 chunk vectors (registry children, fk-002 RESTRICT).
@@ -1516,6 +1553,19 @@ public final class CatalogRepository {
      * rows untouched — preserving pre-RDR-164 RDR-162 behavior.
      */
     public Map<String, Integer> renameCollection(String tenant, String oldName, String newName) {
+        Map<String, Integer> counts = renameCollectionTxn(tenant, oldName, newName);
+        // Post-commit (nexus-h8rf6 wave review): the canonical branch DELETEs the
+        // old registry row — evict it so a later same-named collection re-registers.
+        // The cross-model COPY branch leaves both registry rows untouched (no key
+        // in counts), so nothing is evicted there.
+        if (counts.containsKey("catalog_collections_deleted")) {
+            CollectionRegistry.evict(tenant, oldName);
+            CollectionRegistry.markKnown(tenant, newName);
+        }
+        return counts;
+    }
+
+    private Map<String, Integer> renameCollectionTxn(String tenant, String oldName, String newName) {
         return tenantScope.withTenant(tenant, ctx -> {
             Map<String, Integer> counts = new LinkedHashMap<>();
             boolean targetExists = ctx.fetchExists(

{conexus-6.2.0 → conexus-6.3.0}/service/src/main/java/dev/nexus/service/db/ChashRepository.java

@@ -1,6 +1,8 @@
 package dev.nexus.service.db;
 
 import org.jooq.DSLContext;
+
+import static dev.nexus.service.jooq.nexus.Tables.CATALOG_COLLECTIONS;
 import org.jooq.Field;
 import org.jooq.Record3;
 import org.jooq.impl.DSL;
@@ -72,16 +74,71 @@ public final class ChashRepository {
      * error — fail loud rather than silently skipping the registration step and letting the
      * subsequent INSERT fail with a cryptic FK violation.
      *
+     * <p>Bead nexus-h8rf6.2 (contention relief): skips the INSERT entirely when
+     * {@link CollectionRegistry} already knows this {@code (tenant, collection)} pair is
+     * registered. See {@link CollectionRegistry} class doc for why the repeated
+     * {@code ON CONFLICT DO NOTHING} was a same-row lock-wait convoy under concurrent
+     * indexing, and why callers (not this method) are responsible for marking the cache
+     * only after the enclosing transaction commits.
+     *
      * @throws IllegalArgumentException if collection is null or blank
      */
     private static void ensureCollectionRegistered(DSLContext ctx, String tenant, String collection) {
         if (collection == null || collection.isBlank()) {
             throw new IllegalArgumentException("physical_collection must not be blank");
         }
-        ctx.execute(
-            "INSERT INTO nexus.catalog_collections (tenant_id, name) VALUES (?, ?) " +
-            "ON CONFLICT (tenant_id, name) DO NOTHING",
-            tenant, collection);
+        if (CollectionRegistry.isKnown(tenant, collection)) {
+            return;
+        }
+        ctx.insertInto(CATALOG_COLLECTIONS,
+                        CATALOG_COLLECTIONS.TENANT_ID, CATALOG_COLLECTIONS.NAME)
+           .values(tenant, collection)
+           .onConflict(CATALOG_COLLECTIONS.TENANT_ID, CATALOG_COLLECTIONS.NAME)
+           .doNothing()
+           .execute();
+    }
+
+    /**
+     * Register {@code collection} in its OWN short committed transaction, then mark
+     * the {@link CollectionRegistry} cache.
+     *
+     * <p>Bounded first-burst convoy (v0.1.21, ChashVectorConcurrencyTest full-suite
+     * failure): with registration inside the batch transaction, the FIRST writer to
+     * a brand-new collection holds the {@code catalog_collections} ON CONFLICT value
+     * lock for its ENTIRE batch — every concurrent racer blocks for the winner's
+     * whole batch duration, and on a loaded host that exceeds the pool's
+     * connectionTimeout, surfacing typed 503s the cache was built to prevent. The
+     * CollectionRegistry cache bounds convoy COUNT (one per process lifetime);
+     * this bounds convoy DURATION (a single-statement micro-transaction, committed
+     * before the batch begins).
+     *
+     * <p>Trade-off, accepted: if the subsequent batch rolls back, the stub row
+     * persists — a zero-chunk registry stub is benign (collection existence is
+     * live-chunk-count-based everywhere: {@code collection_exists}, {@code /stats};
+     * {@code deleteCollection} removes stubs) and the pre-registration is exactly
+     * what any retry would recreate. Batch paths use this; {@code renameCollection}
+     * keeps in-transaction {@link #ensureCollectionRegistered} because its
+     * registration must be atomic with the re-point.
+     */
+    private void registerCollectionShortTxn(String tenant, String collection) {
+        if (collection == null || collection.isBlank()) {
+            throw new IllegalArgumentException("physical_collection must not be blank");
+        }
+        if (CollectionRegistry.isKnown(tenant, collection)) {
+            return;
+        }
+        tenantScope.withTenant(tenant, ctx -> {
+            ctx.insertInto(CATALOG_COLLECTIONS,
+                            CATALOG_COLLECTIONS.TENANT_ID, CATALOG_COLLECTIONS.NAME)
+               .values(tenant, collection)
+               .onConflict(CATALOG_COLLECTIONS.TENANT_ID, CATALOG_COLLECTIONS.NAME)
+               .doNothing()
+               .execute();
+            return null;
+        });
+        // Post-commit discipline per CollectionRegistry class doc: the registration
+        // transaction above has committed by the time withTenant returns.
+        CollectionRegistry.markKnown(tenant, collection);
     }
 
     // ── upsert ─────────────────────────────────────────────────────────────────
@@ -100,9 +157,10 @@ public final class ChashRepository {
         if (collection == null || collection.isBlank()) throw new IllegalArgumentException("collection must not be empty");
 
         OffsetDateTime now = OffsetDateTime.now(ZoneOffset.UTC);
+        // 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 -> {
-            // RDR-156 P0.2: ensure catalog_collections has a stub row before the chash write.
-            ensureCollectionRegistered(ctx, tenant, collection);
             ctx.insertInto(CHASH_INDEX,
                             F_TENANT, F_CHASH, F_COLLECTION, F_CREATED_AT)
                .values(tenant, chash, collection, now)
@@ -131,9 +189,10 @@ public final class ChashRepository {
                 .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 -> {
-            // RDR-156 P0.2: ensure catalog_collections has a stub row before the chash writes.
-            ensureCollectionRegistered(ctx, tenant, collection);
             var insert = ctx.insertInto(CHASH_INDEX,
                                         F_TENANT, F_CHASH, F_COLLECTION, F_CREATED_AT);
             var step = insert.values(tenant, valid.get(0), collection, now);
@@ -221,7 +280,7 @@ public final class ChashRepository {
      * via {@code withTenant}.
      */
     public int renameCollection(String tenant, String oldCollection, String newCollection) {
-        return tenantScope.withTenant(tenant, ctx -> {
+        int updated = tenantScope.withTenant(tenant, ctx -> {
             // RDR-156 P0.2: ensure the new collection is registered before renaming.
             ensureCollectionRegistered(ctx, tenant, newCollection);
             // Drop rows in new that would collide with the rename
@@ -239,6 +298,9 @@ public final class ChashRepository {
                       .where(F_COLLECTION.eq(oldCollection))
                       .execute();
         });
+        // Post-commit (nexus-h8rf6.2): see upsert()'s comment / CollectionRegistry doc.
+        CollectionRegistry.markKnown(tenant, newCollection);
+        return updated;
     }
 
     // ── delete_stale ───────────────────────────────────────────────────────────
@@ -351,9 +413,10 @@ public final class ChashRepository {
         }
 
         final OffsetDateTime ts = createdAt;
+        // 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 -> {
-            // RDR-156 P0.2: ensure catalog_collections has a stub row before the chash write.
-            ensureCollectionRegistered(ctx, tenant, collection);
             ctx.insertInto(CHASH_INDEX,
                             F_TENANT, F_CHASH, F_COLLECTION, F_CREATED_AT)
                .values(tenant, chash, collection, ts)
@@ -405,11 +468,13 @@ public final class ChashRepository {
         }
         final List<ImportRow> deduped = List.copyOf(unique.values());
 
-        return tenantScope.withTenant(tenant, ctx -> {
-            Set<String> collections = new java.util.LinkedHashSet<>();
-            for (ImportRow r : deduped) collections.add(r.collection());
-            for (String c : collections) ensureCollectionRegistered(ctx, tenant, c);
+        Set<String> collections = new java.util.LinkedHashSet<>();
+        for (ImportRow r : deduped) collections.add(r.collection());
 
+        // Own short committed txns — bounds the first-registration convoy DURATION
+        // (see registerCollectionShortTxn doc); also handles markKnown post-commit.
+        for (String c : collections) registerCollectionShortTxn(tenant, c);
+        int landed = tenantScope.withTenant(tenant, ctx -> {
             var insert = ctx.insertInto(CHASH_INDEX,
                     F_TENANT, F_CHASH, F_COLLECTION, F_CREATED_AT);
             for (ImportRow r : deduped) {
@@ -429,5 +494,6 @@ public final class ChashRepository {
                   .execute();
             return deduped.size();
         });
+        return landed;
     }
 }

conexus-6.3.0/service/src/main/java/dev/nexus/service/db/CollectionRegistry.java

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 Hal Hildebrand. All rights reserved.
+package dev.nexus.service.db;
+
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
+
+/**
+ * Bead nexus-h8rf6.2 — in-process cache of {@code (tenant, collection)} pairs KNOWN
+ * to already have a row in {@code nexus.catalog_collections}.
+ *
+ * <p><strong>Why this exists.</strong> Both {@code ChashRepository
+ * .ensureCollectionRegistered} and {@code PgVectorRepository.upsertChunksInternal}
+ * issue {@code INSERT INTO nexus.catalog_collections ... ON CONFLICT (tenant_id,
+ * name) DO NOTHING} on EVERY batch write, so the collection stub exists before the
+ * chash/chunk row lands. PostgreSQL's {@code ON CONFLICT} clause takes a value lock
+ * on the conflicting unique-index entry to safely decide whether to apply DO
+ * NOTHING; when two concurrent transactions target the SAME {@code (tenant_id,
+ * name)} row — the ordinary case for one repo's indexing run, which writes chash
+ * and vector batches for ONE physical collection over and over — the second
+ * transaction BLOCKS until the first commits or rolls back, even though the
+ * eventual outcome is a no-op. Because the winning transaction typically keeps
+ * its connection open for the rest of its own batch (chunk/chash writes), every
+ * other concurrent writer to that collection sits blocked HOLDING its own pooled
+ * connection for that whole window. Under sustained concurrent indexing this
+ * convoy exhausts the shared HikariCP pool: unrelated requests then fail
+ * {@code dataSource.getConnection()} with {@code SQLTransientConnectionException}
+ * ("Connection is not available, request timed out"), which surfaces as an
+ * opaque 500 (reproduced by {@code ChashVectorConcurrencyTest}).
+ *
+ * <p><strong>Fix shape.</strong> Once a {@code (tenant, collection)} pair is known
+ * to be registered, every subsequent write skips the redundant
+ * {@code INSERT ... ON CONFLICT} entirely — eliminating the repeated same-row
+ * lock-wait for the remainder of the process's lifetime. Only the FIRST
+ * registration (racing among whichever concurrent requests reach it first) still
+ * pays the lock-wait cost; that window is small and bounded by however many
+ * requests happen to race at that exact instant, not by the length of the run.
+ *
+ * <p><strong>Correctness: mark-known only after commit.</strong> Callers MUST call
+ * {@link #markKnown} only after the transaction that performed the (possibly
+ * skipped) registration has committed successfully — never from inside the
+ * {@code TenantScope.withTenant} lambda itself. If the enclosing transaction later
+ * rolls back (e.g. an unrelated error later in the same batch), the
+ * {@code catalog_collections} row was never actually persisted; marking the cache
+ * eagerly would cause every subsequent writer to skip re-registration forever,
+ * silently starving the row. Marking post-commit means a rollback simply leaves
+ * the pair unmarked, so the next writer retries registration as usual.
+ *
+ * <p>Process-local and unbounded by design: {@code (tenant, collection)} pairs are
+ * low-cardinality relative to write volume (one entry per physical collection ever
+ * touched by this process), so an unbounded {@link ConcurrentHashMap}-backed set is
+ * the right trade-off — no eviction complexity, no cache-miss storms.
+ */
+public final class CollectionRegistry {
+
+    private static final Set<String> KNOWN = ConcurrentHashMap.newKeySet();
+
+    private CollectionRegistry() {}
+
+    private static String key(String tenant, String collection) {
+        // Printable delimiter on purpose (wave review): the original '\0' made git
+        // treat this FILE as binary, so every diff rendered as "Bin N -> M bytes"
+        // and logic changes were invisible to text review. '|' is not legal in
+        // tenant ids or conformant collection names, so keys cannot collide.
+        return tenant + '|' + collection;
+    }
+
+    /** True when {@code (tenant, collection)} is known-registered — safe to skip the INSERT. */
+    public static boolean isKnown(String tenant, String collection) {
+        return KNOWN.contains(key(tenant, collection));
+    }
+
+    /**
+     * Record {@code (tenant, collection)} as registered. Callers MUST only invoke
+     * this AFTER the enclosing transaction has committed (see class doc).
+     */
+    public static void markKnown(String tenant, String collection) {
+        KNOWN.add(key(tenant, collection));
+    }
+
+    /**
+     * Forget {@code (tenant, collection)} — MUST be called after any commit that
+     * DELETEs the {@code catalog_collections} row ({@code CatalogRepository
+     * .deleteCollection}; the canonical branch of {@code CatalogRepository
+     * .renameCollection}, which deletes the OLD row). A stale entry would make
+     * every subsequent writer skip re-registration for a later same-named
+     * collection, landing chash/chunk rows with no registry stub — the exact
+     * silent-skip failure the fail-loud registration design exists to prevent.
+     *
+     * <p>Same post-commit discipline as {@link #markKnown}: evict only after the
+     * deleting transaction has committed. The small window between commit and
+     * eviction is fail-loud, not silent — a concurrent writer that skips
+     * registration in that window hits the {@code ON DELETE RESTRICT} FK and
+     * errors rather than writing orphaned rows.
+     */
+    public static void evict(String tenant, String collection) {
+        KNOWN.remove(key(tenant, collection));
+    }
+
+    /** Test-only: clears all cached entries. */
+    static void clearForTests() {
+        KNOWN.clear();
+    }
+}

{conexus-6.2.0 → conexus-6.3.0}/service/src/main/java/dev/nexus/service/db/TenantScope.java

@@ -9,7 +9,13 @@ import org.slf4j.LoggerFactory;
 import javax.sql.DataSource;
 import java.sql.Connection;
 import java.sql.SQLException;
+import java.sql.SQLTransientConnectionException;
+import java.util.Collections;
+import java.util.IdentityHashMap;
+import java.util.Map;
 import java.util.Set;
+import java.util.concurrent.Semaphore;
+import java.util.concurrent.TimeUnit;
 import java.util.function.Function;
 
 /**
@@ -63,10 +69,61 @@ public final class TenantScope {
      */
     private static final Set<String> PERMITTED_GUCS = Set.of(DEFAULT_TENANT_GUC, T1_TENANT_GUC);
 
+    /**
+     * Per-DataSource admission semaphores (wave review, Java-tree audit High-1).
+     *
+     * <p>The HTTP layer is virtual-thread-per-request with NO inherent bound on how
+     * many requests concurrently attempt DB work against the fixed HikariCP pool.
+     * Every convoy fix so far (batched INSERTs, embed-before-borrow,
+     * registration-in-own-txn) is per-call-site; this is the SYSTEMIC backpressure:
+     * at most {@code 2 * maximumPoolSize} callers may be inside {@link #withTenant}
+     * at once (poolSize active + poolSize queued), everyone else gets the same
+     * typed retryable pool-exhaustion signal HikariCP's connectionTimeout produces
+     * ({@link SQLTransientConnectionException} in the cause chain →
+     * {@code HttpUtil.isPoolExhausted} → 503) — without first burning a
+     * connectionTimeout wait per surplus caller.
+     *
+     * <p>Identity-keyed and static because production constructs MULTIPLE
+     * TenantScope instances over the SAME DataSource (NexusService + Main's
+     * PgVectorRepository) — a per-instance semaphore would multiply the bound.
+     * Fair, so a burst cannot starve early arrivals.
+     */
+    private static final Map<DataSource, Semaphore> ADMISSION =
+        Collections.synchronizedMap(new IdentityHashMap<>());
+
+    private static final int DEFAULT_POOL_SIZE = 10;
+    private static final long DEFAULT_TIMEOUT_MS = 30_000L;
+
     private final DataSource dataSource;
+    private final Semaphore admission;
+    private final long admissionTimeoutMs;
 
     public TenantScope(DataSource dataSource) {
         this.dataSource = dataSource;
+        int poolSize = DEFAULT_POOL_SIZE;
+        long timeoutMs = DEFAULT_TIMEOUT_MS;
+        if (dataSource instanceof com.zaxxer.hikari.HikariDataSource hikari) {
+            int configured = hikari.getMaximumPoolSize();
+            if (configured > 0) {
+                poolSize = configured;
+            }
+            long ct = hikari.getConnectionTimeout();
+            if (ct > 0) {
+                timeoutMs = ct;
+            }
+        }
+        this.admissionTimeoutMs = timeoutMs;
+        final int permits = poolSize * 2;
+        this.admission = ADMISSION.computeIfAbsent(
+            dataSource, ds -> new Semaphore(permits, true));
+    }
+
+    /** Test-only: admission bound + timeout injected directly (stub DataSource path). */
+    TenantScope(DataSource dataSource, int admissionPermits, long admissionTimeoutMs) {
+        this.dataSource = dataSource;
+        this.admissionTimeoutMs = admissionTimeoutMs;
+        this.admission = ADMISSION.computeIfAbsent(
+            dataSource, ds -> new Semaphore(admissionPermits, true));
     }
 
     /**
@@ -124,6 +181,34 @@ public final class TenantScope {
                     "gucName not permitted: " + gucName + " (allowed: " + PERMITTED_GUCS + ")");
         }
 
+        // Admission control (see ADMISSION doc): bound concurrent DB work BEFORE
+        // borrowing a connection. Rejection surfaces as the SAME typed retryable
+        // signal as HikariCP connectionTimeout (SQLTransientConnectionException in
+        // the cause chain), so every handler's sendTypedDbError ladder maps it to
+        // a 503 with zero new error-mapping surface.
+        boolean admitted;
+        try {
+            admitted = admission.tryAcquire(admissionTimeoutMs, TimeUnit.MILLISECONDS);
+        } catch (InterruptedException ie) {
+            Thread.currentThread().interrupt();
+            throw new RuntimeException("interrupted awaiting DB admission for tenant: " + tenant, ie);
+        }
+        if (!admitted) {
+            log.warn("event=tenant_scope_admission_timeout tenant={} guc={} timeout_ms={}",
+                tenant, gucName, admissionTimeoutMs);
+            throw new RuntimeException(
+                "DB admission queue full for tenant: " + tenant,
+                new SQLTransientConnectionException(
+                    "admission queue full after " + admissionTimeoutMs + "ms (retryable)"));
+        }
+        try {
+            return stampAndRun(tenant, gucName, work);
+        } finally {
+            admission.release();
+        }
+    }
+
+    private <T> T stampAndRun(String tenant, String gucName, Function<DSLContext, T> work) {
         Connection conn = null;
         try {
             conn = dataSource.getConnection();

{conexus-6.2.0 → conexus-6.3.0}/service/src/main/java/dev/nexus/service/db/TokenCache.java

@@ -125,8 +125,18 @@ public final class TokenCache {
             return Optional.empty();  // expired — do not cache
         }
         if (map.size() >= maxEntries) {
-            log.warn("event=token_cache_overflow max={} action=clear", maxEntries);
-            map.clear();
+            // Wave review: was map.clear() — evicting EVERY cached principal at once
+            // meant the next request from every active tenant paid a synchronous
+            // TokenStore round-trip simultaneously (a self-inflicted thundering herd
+            // right when the system is busiest). Evict ~25% instead: the flood
+            // backstop still bounds memory, but hot tokens survive the trim.
+            int toEvict = Math.max(1, maxEntries / 4);
+            log.warn("event=token_cache_overflow max={} action=evict count={}", maxEntries, toEvict);
+            var it = map.keySet().iterator();
+            for (int i = 0; i < toEvict && it.hasNext(); i++) {
+                it.next();
+                it.remove();
+            }
         }
         map.put(tokenHash, new Entry(st.tenantId(), st.isRoot(), st.expiresAt(), now));
         return Optional.of(new Resolved(st.tenantId(), st.isRoot()));

{conexus-6.2.0 → conexus-6.3.0}/service/src/main/java/dev/nexus/service/http/AspectHandler.java

@@ -144,28 +144,15 @@ public final class AspectHandler implements HttpHandler {
         } catch (IllegalArgumentException e) {
             HttpUtil.send(exchange, 400, "{\"error\":" + HttpUtil.jsonString(e.getMessage()) + "}");
         } catch (Exception e) {
-            String sqlState = sqlState23(e);
-            if (sqlState != null) {
-                // RDR-172 P3.1 (nexus-gfl3y): a SQLSTATE class-23 integrity violation —
-                // e.g. the aspect_extraction_queue.doc_id FK rejecting a non-blank but
-                // UNREGISTERED doc_id (bug nexus-ov0sw) — is a CLIENT error, not a server
-                // fault. Map it to a typed 409 AHEAD of the generic 500 so the caller sees
-                // a loud, actionable failure instead of an opaque 500 (and never a silent
-                // 200). jOOQ wraps the driver PSQLException in a DataAccessException, so the
-                // violation surfaces as a cause, not the top-level throwable. RF-5 / RF-8.
-                // Full driver message (the parameterised SQL + PG detail) goes to the
-                // server log for operators; the client body is sanitised to a fixed
-                // message + the sqlstate. The 409 is client-triggerable (a bad doc_id),
-                // so echoing the raw jOOQ SQL would leak schema/constraint shape to any
-                // caller — return only the programmatic signal (sqlstate).
-                log.warn("event=aspects_handler_integrity_violation op={} sqlstate={} error={}",
-                    op, sqlState, e.getMessage());
-                HttpUtil.send(exchange, 409,
-                    "{\"error\":\"integrity constraint violation\",\"sqlstate\":"
-                    + HttpUtil.jsonString(sqlState) + "}");
-            } else {
+            // Shared typed-DB-error ladder: pool-exhaustion 503 + class-23 409
+            // (nexus-h8rf6.2 / nexus-7e057) — see HttpUtil.sendTypedDbError.
+            // (RDR-172 P3.1 / nexus-gfl3y history preserved on HttpUtil.sendTypedDbError.)
+            if (!HttpUtil.sendTypedDbError(exchange, e, log, "aspects_handler",
+                    "op=" + op)) {
                 log.error("event=aspects_handler_error op={} error={}", op, e.getMessage(), e);
-                HttpUtil.send(exchange, 500, "{\"error\":" + HttpUtil.jsonString(e.getMessage()) + "}");
+                // Wave review: fixed 500 body — the previous body echoed e.getMessage(),
+                // which can carry jOOQ SQL / schema shape to any caller.
+                HttpUtil.send(exchange, 500, "{\"error\":\"internal server error\"}");
             }
         }
     }

{conexus-6.2.0 → conexus-6.3.0}/service/src/main/java/dev/nexus/service/http/CatalogHandler.java

@@ -199,22 +199,10 @@ public final class CatalogHandler implements HttpHandler {
         } catch (IllegalArgumentException e) {
             HttpUtil.send(exchange, 400, "{\"error\":" + MAPPER.writeValueAsString(e.getMessage()) + "}");
         } catch (Exception e) {
-            // nexus-7e057 (RDR-172 follow-up): a client-supplied doc_id that is
-            // non-blank but UNREGISTERED violates fk_catalog_chunks_catalog_doc
-            // on the manifest write/append path — same bug class as nexus-ov0sw
-            // (AspectHandler's aspect_extraction_queue.doc_id FK). Map class-23
-            // integrity violations to a typed 409 ahead of the generic 500. The
-            // full driver message goes to the server log; the client body is
-            // sanitised to a fixed message + the sqlstate (never the raw jOOQ
-            // SQL, which would leak schema/constraint shape to any caller).
-            String sqlState = HttpUtil.sqlState23(e);
-            if (sqlState != null) {
-                log.warn("event=catalog_handler_integrity_violation op={} tenant={} sqlstate={} error={}",
-                    op, tenant, sqlState, e.getMessage());
-                HttpUtil.send(exchange, 409,
-                    "{\"error\":\"integrity constraint violation\",\"sqlstate\":"
-                    + HttpUtil.jsonString(sqlState) + "}");
-            } else {
+            // Shared typed-DB-error ladder: pool-exhaustion 503 + class-23 409
+            // (nexus-h8rf6.2 / nexus-7e057) — see HttpUtil.sendTypedDbError.
+            if (!HttpUtil.sendTypedDbError(exchange, e, log, "catalog_handler",
+                    "op=" + op + " tenant=" + tenant)) {
                 log.error("event=catalog_handler_error op={} tenant={} error={}", op, tenant, e.getMessage(), e);
                 HttpUtil.send(exchange, 500, "{\"error\":\"internal server error\"}");
             }

{conexus-6.2.0 → conexus-6.3.0}/service/src/main/java/dev/nexus/service/http/ChashHandler.java

@@ -91,8 +91,13 @@ public final class ChashHandler implements HttpHandler {
         } catch (IllegalArgumentException e) {
             HttpUtil.send(exchange, 400, "{\"error\":" + MAPPER.writeValueAsString(e.getMessage()) + "}");
         } catch (Exception e) {
-            log.error("event=chash_handler_error op={} tenant={} error={}", op, tenant, e.getMessage(), e);
-            HttpUtil.send(exchange, 500, "{\"error\":\"internal server error\"}");
+            // Shared typed-DB-error ladder: pool-exhaustion 503 + class-23 409
+            // (nexus-h8rf6.2 / nexus-7e057) — see HttpUtil.sendTypedDbError.
+            if (!HttpUtil.sendTypedDbError(exchange, e, log, "chash_handler",
+                    "op=" + op + " tenant=" + tenant)) {
+                log.error("event=chash_handler_error op={} tenant={} error={}", op, tenant, e.getMessage(), e);
+                HttpUtil.send(exchange, 500, "{\"error\":\"internal server error\"}");
+            }
         }
     }