conexus 7.74.2__tar.gz → 7.76.0__tar.gz

{conexus-7.74.2 → conexus-7.76.0}/PKG-INFO

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

{conexus-7.74.2 → conexus-7.76.0}/docs/rdr/README.md

@@ -243,6 +243,8 @@ An RDR (Research-Design-Review) is a short document that records a technical dec
 | [RDR-223](rdr-223-atomic-chunk-plus-owner-write.md) | Atomic Chunk-Plus-Owner Write on Every Client Path | Architecture | Accepted | 2026-09-28 |
 | [RDR-224](rdr-224-native-windows-support.md) | Native Windows Support: Windows x64 Engine, PostgreSQL Bundle and Client | Architecture | Accepted | 2026-09-30 |
 | [RDR-225](rdr-225-vector-tables-per-embedding-model.md) | One Vector Table per Embedding Model, with Tenant Isolation | Architecture | Accepted | 2026-10-05 |
+| [RDR-226](rdr-226-one-statement-per-leaf-search.md) | Per-Collection Search in One Statement per Leaf | Architecture | Draft | 2026-10-08 |
+| [RDR-227](rdr-227-per-collection-hnsw-above-the-router-threshold.md) | Per-Collection HNSW Indexes Above the Router Threshold | Architecture | Draft | 2026-10-09 |
 
 > RDR-216 is unused on `develop`: drafted, gated BLOCKED, then abandoned 2026-09-19 without landing. Its measurements survive in T2 as `nexus_rdr/216-research-1` through `-19` and in `nexus/manticore-auto-chunking-analysis-2026-09-19`; the record itself never merged.
 

{conexus-7.74.2 → conexus-7.76.0}/mcpb/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "conexus-mcpb"
-version = "7.74.2"
+version = "7.76.0"
 description = "Conexus packaged as Claude Desktop .mcpb (Desktop Extension)"
 requires-python = ">=3.12,<3.14"
 dependencies = [
@@ -12,7 +12,7 @@ dependencies = [
     # the extension's plan cache picked a different embedder than the plugin's
     # and downloaded its own bge copy. Pinned by
     # tests/test_plugin_structure.py::test_mcpb_pins_bare_conexus.
-    "conexus>=7.74.2",
+    "conexus>=7.76.0",
 ]
 
 [tool.uv]

{conexus-7.74.2 → conexus-7.76.0}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "7.74.2"
+version = "7.76.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-7.74.2 → conexus-7.76.0}/service/src/main/java/dev/nexus/service/db/PgSession.java

@@ -708,12 +708,24 @@ public final class PgSession {
      * hold at most this many PHYSICAL rows in the tenant, the statement runs exact (index scans
      * off) instead of walking the shared HNSW index. 0 disables the router.
      *
-     * <p>PROVISIONAL. 10000 is a placeholder chosen to sit well inside what an exact scan over a
-     * PK-prefix bitmap or seq scan costs on 768/1024-d rows; the conexus fork measurement B sets the
-     * real value, and no engine tag is cut on this number. Until then, set
-     * {@code NX_SEARCH_EXACT_MAX_ROWS} explicitly where it matters.
+     * <p>30000 (nexus-nqsa7, Sam's decision 2026-10-09). Above the threshold an arm walks its leaf's HNSW
+     * index under {@code relaxed_order}, which stops at the first {@code k} rows the collection filter
+     * admits; in a leaf shared by many collections the filter discarded about 80% of the walk, and a full
+     * page missed the collection's true nearest row (recall against exact 0.925 at k=40 on code__1-72,
+     * 27,893 rows; T2 conexus/nqsa7-fork-hnsw-vs-exact-2026-10-09). The empty-result re-run cannot see
+     * that, because the page is full. Exact is complete.
+     *
+     * <p>Why not higher. engine-service-v0.1.155 shipped 60000, and on the live engine the five code
+     * collections then searched exact ran five at a time and each took about 2.5x its solo time on the
+     * fork (CPU and memory-bandwidth contention, zero permit wait): the two largest, 58,588 and 45,525 rows,
+     * took 1.1-2.0 s, and a warm default search got about 1 s slower. More fan-out permits would add
+     * concurrent exact scans and make it worse. 30000 keeps the measured repro and the 29,355-row collection
+     * exact and puts the two largest back on HNSW, which leaves them exposed to the same miss; a remedy
+     * independent of this threshold is tracked as its own bead. It was a provisional 10000 before v0.1.155.
+     * The probe reads up to {@code limit + 1} keys, so a collection above the threshold pays a 30,001-key
+     * Index Only Scan before its HNSW walk.
      */
-    static final int DEFAULT_SEARCH_EXACT_MAX_ROWS = 10_000;
+    static final int DEFAULT_SEARCH_EXACT_MAX_ROWS = 30_000;
 
     /** Upper bound on the {@code NX_SEARCH_EXACT_MAX_ROWS} override: an exact scan over more rows than
      *  this would no longer be the cheap plan the router exists to take. */

{conexus-7.74.2 → conexus-7.76.0}/service/src/main/java/dev/nexus/service/db/SchemaMigrator.java

@@ -8,6 +8,9 @@ import liquibase.database.Database;
 import liquibase.database.DatabaseFactory;
 import liquibase.database.jvm.JdbcConnection;
 import liquibase.exception.LiquibaseException;
+import liquibase.lockservice.DatabaseChangeLogLock;
+import liquibase.lockservice.LockService;
+import liquibase.lockservice.LockServiceFactory;
 import liquibase.resource.ClassLoaderResourceAccessor;
 import org.jooq.DSLContext;
 import org.jooq.Field;
@@ -25,6 +28,7 @@ import java.sql.Connection;
 import java.sql.PreparedStatement;
 import java.sql.ResultSet;
 import java.sql.SQLException;
+import java.time.Duration;
 import java.time.ZoneId;
 import java.time.ZoneOffset;
 import java.util.TimeZone;
@@ -379,6 +383,31 @@ public final class SchemaMigrator {
         return migrate(ds, () -> { });
     }
 
+    /**
+     * Key of the session-level advisory lock a migrator holds for its whole walk (nexus-8sph2).
+     *
+     * <p>The bytes of {@code "nexus"} as a bigint. It sits above the int4 range on purpose:
+     * {@code TaxonomyRepository} keys its transaction locks on {@code hashtext(...)}, an int4 widened to
+     * bigint, so no key it can produce equals this one.
+     */
+    public static final long MIGRATION_ADVISORY_LOCK_KEY = 0x6e65787573L;
+
+    /**
+     * How long a migrator waits for another live migrator's advisory lock before it refuses to boot.
+     * Liquibase's own default wait for its changelog lock, so a contended boot fails on the same clock
+     * it always has.
+     */
+    static final Duration DEFAULT_MIGRATION_LOCK_WAIT = Duration.ofMinutes(5);
+
+    /**
+     * Test seam (nexus-8sph2): as {@link #migrate(DataSource)} with the wait for another live migrator's
+     * advisory lock set by the caller, so a test of the contended case does not wait five minutes. Public
+     * for the cross-package reason {@link #migrate(DataSource, Runnable)} gives.
+     */
+    public static MigrationOutcome migrate(DataSource ds, Duration migrationLockWait) {
+        return migrate(ds, () -> { }, LocalDiskPreflight::dataDirFreeBytesFromEnv, migrationLockWait);
+    }
+
     /**
      * Test seam (nexus-jl08t round 3, T2 [25617]/critic round-2 finding).
      * {@code afterUpdateHook} runs immediately after {@code
@@ -420,6 +449,12 @@ public final class SchemaMigrator {
      */
     public static MigrationOutcome migrate(DataSource ds, Runnable afterUpdateHook,
                                            java.util.function.Supplier<java.util.OptionalLong> dataDirFreeBytes) {
+        return migrate(ds, afterUpdateHook, dataDirFreeBytes, DEFAULT_MIGRATION_LOCK_WAIT);
+    }
+
+    private static MigrationOutcome migrate(DataSource ds, Runnable afterUpdateHook,
+                                            java.util.function.Supplier<java.util.OptionalLong> dataDirFreeBytes,
+                                            Duration migrationLockWait) {
         log.info("event=schema_migration_start changelog={}", MASTER_CHANGELOG);
         try {
             pinJvmTimeZoneToUtc();
@@ -494,10 +529,14 @@ public final class SchemaMigrator {
             database.setLiquibaseSchemaName("public");
             database.setDefaultSchemaName("public");
 
+            // nexus-8sph2: the migration lock is declared AFTER Liquibase so it closes FIRST. Liquibase's
+            // close() closes the connection, which on a pool returns it with the session, and so the
+            // session-level advisory lock, still alive; the lock must be released before that happens.
             try (Liquibase liquibase = new Liquibase(
                     MASTER_CHANGELOG,
                     new ClassLoaderResourceAccessor(),
-                    database)) {
+                    database);
+                 MigrationLock migrationLock = MigrationLock.acquire(conn, database, migrationLockWait)) {
 
                 // Count pending changesets for the structured log entry.
                 int pending = liquibase.listUnrunChangeSets(
@@ -1246,6 +1285,125 @@ public final class SchemaMigrator {
      * Unchecked exception thrown when {@link #migrate(DataSource)} cannot
      * complete. {@code Main.java} catches this and calls {@code System.exit(1)}.
      */
+    /**
+     * The migrator's session-level advisory lock, held from before Liquibase takes its changelog lock until
+     * after the walk (nexus-8sph2).
+     *
+     * <p>Liquibase's lock is a committed row in {@code databasechangeloglock}. A walker stopped mid-walk
+     * (SIGTERM, CTRL_BREAK, a crash) leaves the row {@code locked=true}, and the next boot waited five
+     * minutes for it and failed (measured 2026-10-05, T2 nexus_rdr/224-research-19). The row cannot tell a
+     * dead walker from a live one. A session-level advisory lock can: PostgreSQL drops it when the holding
+     * session ends, however the process stopped. Every migrator takes it first, so a migrator that holds it
+     * knows no other migrator is walking, and a locked row it finds is stale. It releases that row through
+     * Liquibase's own {@link LockService#forceReleaseLock()} and lets Liquibase take its lock as before.
+     * Liquibase's lock stays in place, so an engine that predates this lock still waits on the row.
+     *
+     * <p>The lock is SESSION-scoped, so the migration connection must be a real PostgreSQL session for the
+     * whole walk. A transaction-mode pooler (PgBouncer {@code pool_mode=transaction}) between the migrator and
+     * PostgreSQL can hand each statement a different server session, which silently voids the lock: the
+     * migrator would then release a live walker's row. Point the migrator at PostgreSQL directly or through
+     * a session-mode pool.
+     *
+     * <p>Accepted gap: an engine that predates this lock, walking at the same moment as one that has it,
+     * holds the row but not the advisory lock, and would have its row released. That needs two engine
+     * versions booting against one database at once; the cloud runs one engine and a local install one.
+     */
+    private static final class MigrationLock implements AutoCloseable {
+        private static final Duration POLL = Duration.ofSeconds(1);
+        private final Connection conn;
+
+        private MigrationLock(Connection conn) {
+            this.conn = conn;
+        }
+
+        static MigrationLock acquire(Connection conn, Database database, Duration wait) throws LiquibaseException {
+            DSLContext ctx = DSL.using(conn, SQLDialect.POSTGRES);
+            long deadline = System.nanoTime() + wait.toNanos();
+            boolean logged = false;
+            while (!tryLock(ctx)) {
+                if (!logged) {
+                    log.info("event=schema_migration_lock_wait key={} holder_pid={} wait_s={}",
+                             MIGRATION_ADVISORY_LOCK_KEY, holderPid(ctx), wait.toSeconds());
+                    logged = true;
+                }
+                long remaining = deadline - System.nanoTime();
+                if (remaining <= 0) {
+                    throw new MigrationException("another migrator holds the migration lock (advisory key "
+                        + MIGRATION_ADVISORY_LOCK_KEY + ", holder pid " + holderPid(ctx) + ") after waiting "
+                        + wait.toSeconds() + " s");
+                }
+                try {
+                    Thread.sleep(Math.min(POLL.toMillis(), Math.max(1, remaining / 1_000_000)));
+                } catch (InterruptedException e) {
+                    Thread.currentThread().interrupt();
+                    throw new MigrationException("interrupted waiting for the migration lock", e);
+                }
+            }
+            MigrationLock lock = new MigrationLock(conn);
+            try {
+                releaseStaleChangelogLock(database);
+            } catch (LiquibaseException | RuntimeException e) {
+                lock.close();
+                throw e;
+            }
+            return lock;
+        }
+
+        private static boolean tryLock(DSLContext ctx) {
+            return Boolean.TRUE.equals(ctx.select(DSL.function("pg_try_advisory_lock", SQLDataType.BOOLEAN,
+                    DSL.val(MIGRATION_ADVISORY_LOCK_KEY)))
+                .fetchOne(0, Boolean.class));
+        }
+
+        /** The pid holding the migration lock, or -1 when none is visible; for the log line only. */
+        private static int holderPid(DSLContext ctx) {
+            try {
+                Integer pid = ctx.select(DSL.field(DSL.name("pid"), Integer.class))
+                    .from(DSL.table(DSL.name("pg_catalog", "pg_locks")))
+                    .where(DSL.field(DSL.name("locktype"), String.class).eq("advisory"))
+                    .and(DSL.field(DSL.name("granted"), Boolean.class).isTrue())
+                    .and(DSL.field(DSL.name("classid"), Long.class).cast(SQLDataType.BIGINT)
+                        .eq(MIGRATION_ADVISORY_LOCK_KEY >>> 32))
+                    .and(DSL.field(DSL.name("objid"), Long.class).cast(SQLDataType.BIGINT)
+                        .eq(MIGRATION_ADVISORY_LOCK_KEY & 0xffffffffL))
+                    .and(DSL.field(DSL.name("objsubid"), Integer.class).eq(1))
+                    .limit(1)
+                    .fetchOne(0, Integer.class);
+                return pid == null ? -1 : pid;
+            } catch (DataAccessException e) {
+                return -1;
+            }
+        }
+
+        /** Under the migration lock any locked changelog row is stale: release it, naming who left it. */
+        private static void releaseStaleChangelogLock(Database database) throws LiquibaseException {
+            LockService lockService = LockServiceFactory.getInstance().getLockService(database);
+            DatabaseChangeLogLock[] locks = lockService.listLocks();
+            if (locks.length == 0) {
+                return;
+            }
+            for (DatabaseChangeLogLock stale : locks) {
+                log.warn("event=schema_changelog_lock_stale_released lockedby=\"{}\" lockgranted={}",
+                         stale.getLockedBy(), stale.getLockGranted() == null ? null
+                             : stale.getLockGranted().toInstant());
+            }
+            lockService.forceReleaseLock();
+        }
+
+        @Override
+        public void close() {
+            try {
+                DSL.using(conn, SQLDialect.POSTGRES)
+                    .select(DSL.function("pg_advisory_unlock", SQLDataType.BOOLEAN,
+                        DSL.val(MIGRATION_ADVISORY_LOCK_KEY)))
+                    .fetchOne();
+            } catch (DataAccessException e) {
+                // The session ending releases it anyway; a failed unlock on a broken connection is not fatal.
+                log.warn("event=schema_migration_lock_release_failed cause=\"{}\"", e.toString());
+            }
+        }
+    }
+
     public static final class MigrationException extends RuntimeException {
         public MigrationException(String message, Throwable cause) {
             super(message, cause);

{conexus-7.74.2 → conexus-7.76.0}/service/src/main/java/dev/nexus/service/http/RerankStage.java

@@ -71,6 +71,32 @@ final class RerankStage {
      *              and the degraded path (the caller sized its consumer for topK)
      */
     Map<String, Object> apply(String query, List<Map<String, Object>> rows, Integer topK) {
+        return apply(query, rows, topK, null);
+    }
+
+    /**
+     * {@link #apply(String, List, Integer)} with a cap on the rows SCORED.
+     *
+     * <p>{@code maxCandidates} (request field {@code rerank_max_candidates}) bounds the
+     * scoring cost, which is per document and the dominant cost of the local cross-encoder
+     * (Sam, 2026-10-08, T2 nexus/search-latency-local-mode-2026-10-08: about 3.5 to 4.9 s of
+     * a 4 to 5 s CLI search scored all 135 candidates). Only the first {@code maxCandidates}
+     * rows with text, in the order the caller handed them (distance order), reach the
+     * scorer. Every other row stays in the result, after the scored rows and in its
+     * original relative order, with no {@code rerank_score}, so the result count and the
+     * response shape are unchanged. {@code null} scores every row (today's behaviour); a
+     * value at or above the number of scorable rows is the same thing. Textless rows do
+     * not use up a slot. Distinct from {@code topK}, which bounds what comes BACK, not
+     * what is scored.
+     *
+     * @throws IllegalArgumentException {@code maxCandidates} is not positive
+     */
+    Map<String, Object> apply(String query, List<Map<String, Object>> rows, Integer topK,
+                              Integer maxCandidates) {
+        if (maxCandidates != null && maxCandidates < 1) {
+            throw new IllegalArgumentException(
+                    "rerank_max_candidates must be at least 1, got " + maxCandidates);
+        }
         if (rows.isEmpty()) {
             return envelope(rows, false, null, null);
         }
@@ -84,6 +110,7 @@ final class RerankStage {
         List<String> documents = new ArrayList<>(rows.size());
         List<Integer> docIndexToRowIndex = new ArrayList<>(rows.size());
         for (int i = 0; i < rows.size(); i++) {
+            if (maxCandidates != null && documents.size() >= maxCandidates) break;
             Object content = rows.get(i).get("content");
             if (content instanceof String s && !s.isBlank()) {
                 documents.add(s);
@@ -133,7 +160,7 @@ final class RerankStage {
             row.put("rerank_score", s.relevanceScore());
             ordered.add(row);
         }
-        // Unscored rows (textless, or beyond the scorer's topK) rank below every
+        // Unscored rows (textless, beyond maxCandidates, or beyond the scorer's topK) rank below every
         // scored row, keeping their original relative order.
         for (int i = 0; i < rows.size(); i++) {
             if (!taken[i]) ordered.add(rows.get(i));

{conexus-7.74.2 → conexus-7.76.0}/service/src/main/java/dev/nexus/service/http/VectorHandler.java

@@ -65,7 +65,9 @@ import java.util.Map;
  * <p><strong>Fused rerank stage (RDR-188, bead nexus-9o6y2.2).</strong> The five
  * search routes (search/query, hybrid-search, search-metadata-scoped,
  * search-topic-scoped, search-graph-hop) accept optional {@code "rerank": true}
- * + {@code "rerank_top_k": N} request fields. With {@code rerank=true} the
+ * + {@code "rerank_top_k": N} (cap on rows returned) and {@code "rerank_max_candidates": N}
+ * (cap on rows SCORED: the first N in input order, the rest returned unscored behind
+ * them) request fields. With {@code rerank=true} the
  * response becomes the {@link RerankStage} object envelope
  * ({@code {"results": [...], "rerank_degraded": ...}}) — rows are reranked
  * server-side on content already fetched under RLS, and any scoring failure
@@ -606,7 +608,9 @@ public final class VectorHandler implements HttpHandler {
      *   "include_embeddings": false,            // optional; each row then carries its stored vector, see below
      *   "embeddings_limit": 300,                // optional, with include_embeddings: only the first N rows keep the vector
      *   "rerank":             false,            // optional; then limit must be &lt;= 1000
-     *   "rerank_top_k":       null              // optional; requires rerank
+     *   "rerank_top_k":       null,             // optional; requires rerank
+     *   "rerank_max_candidates": null,          // optional; requires rerank; score at most this many rows
+     *   "content_chars": 300                    // optional (nexus-tao37); cap each row's text at N code points
      * }
      * </pre>
      *
@@ -677,6 +681,11 @@ public final class VectorHandler implements HttpHandler {
             throw new IllegalArgumentException(
                     "rerank_top_k requires \"rerank\": true — set both or neither");
         }
+        Integer rerankMaxCandidates = optRerankMaxCandidates(body, rerank);
+        Integer contentChars        = optInteger(body, "content_chars");
+        if (contentChars != null && contentChars < 1) {
+            throw new IllegalArgumentException("field 'content_chars' must be at least 1, got " + contentChars);
+        }
         if (rerank && limit > dev.nexus.service.vectors.VoyageReranker.MAX_DOCS_PER_REQUEST) {
             throw new IllegalArgumentException("rerank scores at most "
                     + dev.nexus.service.vectors.VoyageReranker.MAX_DOCS_PER_REQUEST
@@ -692,7 +701,7 @@ public final class VectorHandler implements HttpHandler {
 
         Map<String, Object> envelope = new LinkedHashMap<>();
         if (rerank) {
-            envelope.putAll(rerankStage.apply(queryText, result.rows(), rerankTopK));
+            envelope.putAll(rerankStage.apply(queryText, result.rows(), rerankTopK, rerankMaxCandidates));
         } else {
             envelope.put("results", result.rows());
         }
@@ -717,9 +726,23 @@ public final class VectorHandler implements HttpHandler {
                 }
             }
         }
+        if (contentChars != null && envelope.get("results") instanceof List<?> finalRows) {
+            // nexus-tao37: after the rerank, which scores the full text. A default MCP search shows 200-300
+            // characters of a 10-row page from this pool; the full text was about half of every response.
+            for (Object o : finalRows) {
+                if (o instanceof Map<?, ?> row && row.get("content") instanceof String text) {
+                    @SuppressWarnings("unchecked")
+                    Map<String, Object> mutable = (Map<String, Object>) row;
+                    mutable.put("content", capCodePoints(text, contentChars));
+                }
+            }
+        }
         envelope.put("per_collection", perCollection);
         envelope.put("per_collection_k", perK);
         envelope.put("limit", limit);
+        if (contentChars != null) {
+            envelope.put("content_chars", contentChars);
+        }
         if (includeEmbeddings) {
             envelope.put("embedding_encoding", PgVectorRepository.EMBEDDING_ENCODING);
             envelope.put("embedding_dim", result.embeddingDim());
@@ -767,7 +790,8 @@ public final class VectorHandler implements HttpHandler {
             throw new IllegalArgumentException(
                     "rerank_top_k requires \"rerank\": true — set both or neither");
         }
-        Object payload = rerank ? rerankStage.apply(queryText, result.value(), rerankTopK)
+        Integer rerankMaxCandidates = optRerankMaxCandidates(body, rerank);
+        Object payload = rerank ? rerankStage.apply(queryText, result.value(), rerankTopK, rerankMaxCandidates)
                                 : result.value();
         HttpUtil.send(ex, 200, json(payload));
     }
@@ -2336,6 +2360,20 @@ public final class VectorHandler implements HttpHandler {
     }
 
     /** Optional boolean field; absent or null → {@code defaultValue}. */
+    /**
+     * The first {@code max} code points of {@code text} (nexus-tao37): a cut never splits a surrogate pair.
+     * Returns {@code text} itself when it is already short enough.
+     */
+    public static String capCodePoints(String text, int max) {
+        if (text == null || text.length() <= max) {
+            return text;
+        }
+        if (text.codePointCount(0, text.length()) <= max) {
+            return text;
+        }
+        return text.substring(0, text.offsetByCodePoints(0, max));
+    }
+
     private boolean optBool(Map<String, Object> body, String key, boolean defaultValue) {
         Object val = body.get(key);
         if (val == null) return defaultValue;
@@ -2351,6 +2389,26 @@ public final class VectorHandler implements HttpHandler {
         return s.isBlank() ? null : s;
     }
 
+    /**
+     * The optional {@code rerank_max_candidates} request field: score at most this many
+     * rows, see {@link RerankStage#apply(String, List, Integer, Integer)}. Absent means
+     * score every row. Like {@code rerank_top_k} it is a caller error (400) without
+     * {@code "rerank": true}, and below 1.
+     */
+    private Integer optRerankMaxCandidates(Map<String, Object> body, boolean rerank) {
+        Integer v = optInteger(body, "rerank_max_candidates");
+        if (v == null) return null;
+        if (!rerank) {
+            throw new IllegalArgumentException(
+                    "rerank_max_candidates requires \"rerank\": true — set both or neither");
+        }
+        if (v < 1) {
+            throw new IllegalArgumentException(
+                    "field 'rerank_max_candidates' must be at least 1, got " + v);
+        }
+        return v;
+    }
+
     /** Optional integer field; null → null (no-filter on that dimension). */
     private Integer optInteger(Map<String, Object> body, String key) {
         Object val = body.get(key);

{conexus-7.74.2 → conexus-7.76.0}/service/src/main/java/dev/nexus/service/vectors/Bge768Embedder.java

@@ -114,6 +114,16 @@ public final class Bge768Embedder implements Embedder {
     private static final long MAX_ATTENTION_TENSOR_BYTES =
             attentionTensorBytes(16, MAX_SEQ_LEN);
 
+    /**
+     * Largest fraction of a group's tokens that may be padding before the planner starts a new
+     * group: a group closes when {@code size * maxLen > (1 + MAX_PAD_WASTE) * realTokens}.
+     * 0.25 from a simulation over 12,999 real chunks at 16 per request: padded tokens 1.62x ->
+     * 1.12x of real, at about 4 ONNX calls per request instead of one. 0.1 reaches 1.04x but
+     * needs about 6 calls per request, and a call that small starts to lose the arithmetic
+     * efficiency the saved padding was meant to buy; 0.5 stays at 1.24x.
+     */
+    static final double MAX_PAD_WASTE = 0.25;
+
     private static long attentionTensorBytes(long batchSize, long seqLen) {
         return batchSize * ATTENTION_HEADS * seqLen * seqLen * Float.BYTES;
     }
@@ -350,22 +360,30 @@ public final class Bge768Embedder implements Embedder {
     }
 
     /**
-     * Tokenizes the whole input once (cheap relative to an ONNX forward pass), then
-     * greedily partitions it into sub-batches bounded by {@link #MAX_PADDED_TOKEN_AREA}
-     * — never re-ordering, so results concatenate directly in input order. Each
-     * sub-batch is a separate {@link #runOnnxSubBatch} call, so an oversize request
-     * degrades in throughput (more ONNX invocations) rather than in memory (one
-     * unbounded rectangular tensor).
+     * Tokenizes the whole input once (cheap relative to an ONNX forward pass), orders the rows by
+     * token length, partitions that order into groups of similar length, and runs one ONNX call
+     * per group. Results are scattered back to the caller's input order.
+     *
+     * <p>Why length-ordered: every group is padded to its longest row, and the cost of a call
+     * grows with the padded token count (and, for attention, with its square). Measured on this
+     * repo's own chunks (12,999 chunks, mean 278 tokens, 11% at the 512 cap), a request of 16
+     * chunks in arrival order padded to 1.62x its real tokens (attention 2.03x); the same chunks
+     * grouped by length at {@link #MAX_PAD_WASTE} = 0.25 pad to about 1.12x (attention about
+     * 1.22x), in about 4 calls per request instead of one (T2 nexus/index-embedding-throughput-2026-10-08).
+     * The local engine is CPU-bound, so those padded tokens are wall time.
      *
-     * <p>Sequential (not sorted-by-length) partitioning: extending the current group
-     * with the next text in order is enough to bound padded-token area — a long text
-     * simply forces its group to close sooner — without the added complexity and
-     * result-reordering bookkeeping a sort-then-bucket scheme would need to restore
-     * input order afterward.
+     * <p>Two bounds close a group: the padded-token-area ceiling {@link #MAX_PADDED_TOKEN_AREA}
+     * (memory, nexus-zu4ma, unchanged) and the padding-waste ceiling. A row is always allowed to
+     * start a group, so a single row never fails either bound. The output for a text does not
+     * depend on its group beyond float rounding (cosine to the same text alone is above
+     * {@code 1 - 1e-6}, pinned by {@link Bge768BatchCompositionTest}).
      *
-     * <p>Degrades to the pre-existing single-shot behavior when the whole input
-     * already fits under budget: the loop below produces exactly one group and one
-     * ONNX call, identical to what the old unconditional {@code embedBatch} did.
+     * <p>Degrades to the pre-existing single-call behavior when the whole input is already one
+     * length: the planner then produces one group (or the area-bounded groups, as before).
+     *
+     * <p>A deadline abort between groups discards every group already finished: the request
+     * returns nothing and the client retries the WHOLE request. A request now has about four
+     * groups, so there are more check points per request than before grouping.
      */
     private List<float[]> embedSubBatched(List<String> texts) throws Exception {
         int n = texts.size();
@@ -377,6 +395,11 @@ public final class Bge768Embedder implements Embedder {
             lens[i] = Math.min((int) encodings[i].getIds().length, MAX_SEQ_LEN);
         }
 
+        GroupPlan plan = planGroups(lens, MAX_PADDED_TOKEN_AREA, MAX_PAD_WASTE);
+        Encoding[] ordered = new Encoding[n];
+        for (int k = 0; k < n; k++) ordered[k] = encodings[plan.order()[k]];
+        float[][] scattered = new float[n][];
+
         // Bead nexus-s71lr: this call's own clock, for the "elapsed"/"chunks_per_sec"
         // fields on the progress line below. Independent of progressGate's clock, which
         // is shared instance-wide across every concurrent embed() call.
@@ -387,25 +410,21 @@ public final class Bge768Embedder implements Embedder {
         // (RequestDeadlineProbe.NONE outside a filtered request -> never aborts).
         long deadlineNanos = RequestDeadlineProbe.currentDeadlineNanos();
 
-        List<float[]> results = new ArrayList<>(n);
-        int start = 0;
-        while (start < n) {
-            int end = start + 1;
-            int groupMaxLen = Math.max(lens[start], 1);
-            while (end < n) {
-                int candidateMaxLen = Math.max(groupMaxLen, Math.max(lens[end], 1));
-                long candidateArea = (long) (end - start + 1) * candidateMaxLen * candidateMaxLen;
-                if (candidateArea > MAX_PADDED_TOKEN_AREA) break;
-                groupMaxLen = candidateMaxLen;
-                end++;
-            }
-            if (end - start < n) {
-                // Only log when sub-batching actually engaged — the common case (whole
-                // request under budget) stays silent at the old single-call volume.
+        int[][] groups = plan.groups();
+        for (int[] group : groups) {
+            int start = group[0];
+            int end = group[1];
+            int groupMaxLen = group[2];
+            if (groups.length > 1) {
+                // Only a request that planned more than one group logs here. Length grouping
+                // makes that the usual case for a mixed-length request (about four groups at 16
+                // chunks), so this is a debug line per group, not a rare event; a request whose
+                // rows all fit one group stays silent.
                 log.debug("event=bge768_subbatch start={} size={} maxLen={} totalBatch={}",
                         start, end - start, groupMaxLen, n);
             }
-            results.addAll(runOnnxSubBatch(encodings, start, end, groupMaxLen));
+            List<float[]> part = runOnnxSubBatch(ordered, start, end, groupMaxLen);
+            for (int k = 0; k < part.size(); k++) scattered[plan.order()[start + k]] = part.get(k);
             chunksDone += end - start;
 
             long nowNanos = System.nanoTime();
@@ -439,8 +458,11 @@ public final class Bge768Embedder implements Embedder {
                         admissionFields);
             }
             subBatchIndex++;
-            start = end;
 
+            // A deadline abort discards the groups already finished: nothing is returned
+            // for the request, and the client retries the WHOLE request after
+            // retry_after_s. With about four groups per request there are more such check
+            // points than before length grouping, so more finished work can be thrown away.
             // nexus-8hdg9 phase 3: cooperative deadline check BETWEEN sub-batches, before
             // the next runOnnxSubBatch. Reuses this iteration's nowNanos (design record §4:
             // no second clock read; the added cost is one long comparison). Only when more
@@ -449,7 +471,7 @@ public final class Bge768Embedder implements Embedder {
             // AdmissionControlledEmbedder's finally; the session.run() that just returned
             // is the granularity floor (the deadline never interrupts a run; only
             // shutdown does, through GatedRun's terminate flag, nexus-o5xyx.3).
-            if (start < n && RequestDeadlineProbe.expired(deadlineNanos, nowNanos)) {
+            if (chunksDone < n && RequestDeadlineProbe.expired(deadlineNanos, nowNanos)) {
                 long elapsedMs = (nowNanos - callStartNanos) / 1_000_000L;
                 long pastDeadlineMs = (nowNanos - deadlineNanos) / 1_000_000L;
                 activityTracker.recordDeadlineAbort();  // GET /v1/status deadline_aborts_total
@@ -464,7 +486,51 @@ public final class Bge768Embedder implements Embedder {
                         RequestDeadlineExceededException.DEFAULT_RETRY_AFTER_SECONDS);
             }
         }
-        return results;
+        return new ArrayList<>(java.util.Arrays.asList(scattered));
+    }
+
+    /**
+     * One partition of a request: {@code order[k]} is the input index of the k-th row in length
+     * order, and each {@code groups[g]} is {@code {start, end, maxLen}} over that order
+     * ({@code end} exclusive, {@code maxLen >= 1} the group's padded width).
+     */
+    record GroupPlan(int[] order, int[][] groups) {}
+
+    /**
+     * Partition {@code lens} (token counts, already capped at {@link #MAX_SEQ_LEN}) into ONNX
+     * groups: stable ascending sort by length, then greedy extension of the current group while
+     * BOTH bounds hold: the padded-token area {@code size * maxLen^2 <= maxArea}, and the padding
+     * waste {@code size * maxLen <= (1 + maxWaste) * (real tokens in the group)}. The first row of
+     * a group is always accepted. Package-private and pure so the planner is testable without the
+     * 416 MB model.
+     */
+    static GroupPlan planGroups(int[] lens, long maxArea, double maxWaste) {
+        int n = lens.length;
+        Integer[] boxed = new Integer[n];
+        for (int i = 0; i < n; i++) boxed[i] = i;
+        java.util.Arrays.sort(boxed, java.util.Comparator.comparingInt(i -> lens[i]));  // stable
+        int[] order = new int[n];
+        for (int k = 0; k < n; k++) order[k] = boxed[k];
+
+        List<int[]> groups = new ArrayList<>();
+        int start = 0;
+        while (start < n) {
+            int end = start + 1;
+            long realTokens = Math.max(lens[order[start]], 1);
+            int groupMaxLen = (int) realTokens;
+            while (end < n) {
+                int len = Math.max(lens[order[end]], 1);  // ascending: the new row is the new max
+                long size = end - start + 1;
+                if (size * len * len > maxArea) break;
+                if (size * len > (1.0 + maxWaste) * (realTokens + len)) break;
+                realTokens += len;
+                groupMaxLen = len;
+                end++;
+            }
+            groups.add(new int[]{start, end, groupMaxLen});
+            start = end;
+        }
+        return new GroupPlan(order, groups.toArray(new int[0][]));
     }
 
     /**