conexus 8.2.0__tar.gz → 8.2.2__tar.gz

{conexus-8.2.0 → conexus-8.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: conexus
-Version: 8.2.0
+Version: 8.2.2
 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-8.2.0 → conexus-8.2.2}/docs/rdr/README.md

@@ -262,6 +262,7 @@ An RDR (Research-Design-Review) is a short document that records a technical dec
 | [RDR-243](rdr-243-first-class-document-sensitivity.md) | First-Class Document Sensitivity: Route, Stamp and Exempt Sensitive Documents from Every LLM and External Surface | Feature | Closed | 2026-11-03 |
 | [RDR-244](rdr-244-public-retrieval-evaluation.md) | Public retrieval evaluation others can run | Feature | Accepted | 2026-11-03 |
 | [RDR-245](rdr-245-structured-asks-on-the-threads-board.md) | Structured Asks: Typed ask Blocks on the Threads Board, Answered through a Mediator Session or nx ask and Routed to the Asker's Mailbox | Feature | Accepted | 2026-11-05 |
+| [RDR-247](rdr-247-one-index-per-row.md) | One Index per Row: Index Each Vector Once, Not in Both the Leaf Graph and a Per-Collection Graph | Architecture | Deferred | 2026-11-10 |
 | [RDR-248](rdr-248-cloud-tenant-backup.md) | Cloud-Mode nx backup: an Engine Tenant Export Saved to One File, with a Tested Restore into an Empty Tenant | Feature | Accepted | 2026-11-11 |
 
 > 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-8.2.0 → conexus-8.2.2}/mcpb/pyproject.toml

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

{conexus-8.2.0 → conexus-8.2.2}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "conexus"
-version = "8.2.0"
+version = "8.2.2"
 description = "Self-hosted semantic search and knowledge management for LLM-driven development"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.12,<3.14"
@@ -355,6 +355,7 @@ markers = [
     "no_service_jar: integration test that drives PostgreSQL directly and is exempt from the service-jar freshness gate",
     "needs_stamped_jar: integration test that constructs a vector client, so its service jar must carry a release_version (build with scripts/build-gate-jar.sh) — nexus-ao29z",
     "lived_in: integration test that dispatches real claude -p or requires seeded lived-in corpora (deselect with '-m \"integration and not lived_in\"')",
+    "pg_bundle_artifact: integration test of the BUILT portable PostgreSQL bundle (NEXUS_PG_BUNDLE_ROOT, a relocated extract); only the ci.yml CA-3 bundle jobs build one and run it by path, so the local-service gate and the release-PR integration shards deselect it instead of carrying its skips (nexus-f3yqd.2)",
     "keyed_voyage: integration test that needs the SERVICE embedding voyage-* collections: a keyed engine on the Voyage profile. The keyless local-service gate deselects it ('-m \"integration and not keyed_voyage\"'); tests/e2e/dual-embedder-gate.sh runs it (nexus-8errq)",
     "real_managed_default: opt OUT of the unit suite's black-holed default managed endpoint (nexus-d5aye) — for tests that assert DEFAULT_MANAGED_SERVICE_URL's own value; they must still not reach the network",
     "lint: repo-structure/meta lint tests (AST-scan the whole src tree, walk conexus/ agent-skill-command markdown, RDR frontmatter, marker-selection coverage) rather than exercising src behavior. Excluded from default addopts; runs in the dedicated CI lint leg — see .github/workflows/ci.yml's test-lint job, 'pytest (lint markers, group N/2)' (test-suite-compression P0, nexus-test-cleanup 2026-08-05).",

{conexus-8.2.0 → conexus-8.2.2}/service/src/main/java/dev/nexus/service/Main.java

@@ -603,6 +603,8 @@ public final class Main {
         service.chunkConstraintAdmin(new dev.nexus.service.vectors.ChunkConstraintAdmin(adminConnection));
         // nexus-6pfgb.44: the same for the catalog TTL CHECK census/add/validate routes; nothing calls them.
         service.catalogTtlCheckAdmin(new dev.nexus.service.db.CatalogTtlCheckAdmin(adminConnection));
+        // nexus-f3yqd: the same for the user-started chash VALIDATE CONSTRAINT job; bound here, started only by a user's POST.
+        service.chashConstraintValidator(adminConnection);
         // nexus-hbnml: a retired aspect_extraction_queue table that still holds rows (aspects-005-2 keeps it) is
         // drained onto the aspects tuples once, shortly after boot; the next boot's guard drops the emptied table.
         service.aspectQueueDrain(adminConnection);

{conexus-8.2.0 → conexus-8.2.2}/service/src/main/java/dev/nexus/service/NexusService.java

@@ -319,6 +319,11 @@ public final class NexusService {
     private volatile dev.nexus.service.vectors.ChunkConstraintAdmin chunkConstraintAdmin;
     /** nexus-6pfgb.44: the admin-connection DDL behind {@code /v1/admin/catalog-ttl-check/*}; null until {@code Main} binds it. */
     private volatile dev.nexus.service.db.CatalogTtlCheckAdmin catalogTtlCheckAdmin;
+    /** nexus-f3yqd: the admin-connection VALIDATE behind {@code /v1/admin/validate-constraints}; null until {@code Main} binds it. */
+    private volatile dev.nexus.service.db.ChashConstraintValidator chashConstraintValidator;
+    /** nexus-f3yqd: the engine-wide validate job, one at a time and never tenant-scoped, so no tenant reset reaches it. */
+    private final dev.nexus.service.http.EngineJobs<dev.nexus.service.http.ValidateConstraintsJobs.Progress> validateConstraintsJobs =
+        dev.nexus.service.http.ValidateConstraintsJobs.registry(System::currentTimeMillis);
     /**
      * nexus-hbnml: the result of the engine-start drain of the retired aspect queue table, served by
      * {@code GET /v1/status} as {@code aspect_queue_table_present} / {@code aspect_queue_rows_retained}. Null until
@@ -770,7 +775,7 @@ public final class NexusService {
         // reveal how many tenants share the engine.
         var chashConformanceCtx = server.createContext(dev.nexus.service.http.ChashConformanceHandler.PATH,
                 new dev.nexus.service.http.ChashConformanceHandler(
-                        new dev.nexus.service.db.ChashConformanceConstraints(tenantScope)));
+                        new dev.nexus.service.db.ChashConformanceConstraints(tenantScope), tenantScope));
         chashConformanceCtx.getFilters().addAll(authFilter);
 
         // /v1/requests/<id> — RDR-222 Phase 1 request status (bead nexus-yye8l.4). The one
@@ -903,6 +908,12 @@ public final class NexusService {
                         () -> catalogTtlCheckAdmin, tokenStore::listKnownTenants, tenantScope));
         catalogTtlCtx.getFilters().addAll(authFilter);
 
+        // /v1/admin/validate-constraints — the user-started VALIDATE CONSTRAINT job of the chash width CHECKs (nexus-f3yqd),
+        // root token only; never started by the engine. The admin connection it runs on is bound late, from Main.
+        var validateConstraintsCtx = server.createContext(dev.nexus.service.http.ValidateConstraintsHandler.PATH,
+                new dev.nexus.service.http.ValidateConstraintsHandler(() -> chashConstraintValidator, validateConstraintsJobs));
+        validateConstraintsCtx.getFilters().addAll(authFilter);
+
         // /v1/tuples/* — RDR-205 Linda tuple space (bead nexus-em75s.4). Registered
         // only when a boot-checked TemplateRegistry was supplied (see the constructor
         // javadoc above) — a null registry means the feature was never loaded, so the
@@ -1115,7 +1126,9 @@ public final class NexusService {
                 t -> dataSweepFailuresByTenant.remove(t) != null ? 1 : 0),
             dev.nexus.service.db.TenantKeyedState.of("ChunkKeysSweepJobs", chunkKeysJobs::evictTenant),
             dev.nexus.service.db.TenantKeyedState.of("EngineJobs.reconcile", reconcileJobs::evictTenant),
-            dev.nexus.service.db.TenantKeyedState.of("EngineJobs.manifestFill", manifestFillJobs::evictTenant));
+            dev.nexus.service.db.TenantKeyedState.of("EngineJobs.manifestFill", manifestFillJobs::evictTenant),
+            dev.nexus.service.db.TenantKeyedState.of("ValidateConstraintsJobs",
+                t -> dev.nexus.service.http.ValidateConstraintsJobs.forgetTenant(validateConstraintsJobs, t)));
     }
 
     /** The evictors the tenant reset route runs, in order; empty-safe, built whether or not the route is enabled. */
@@ -1292,6 +1305,24 @@ public final class NexusService {
         this.catalogTtlCheckAdmin = admin;
     }
 
+    /**
+     * Bind the admin-connection VALIDATE behind {@code POST /v1/admin/validate-constraints} (nexus-f3yqd). {@code Main} calls
+     * it once, with the same {@code NX_DB_ADMIN_*} values; until then the route answers 503. Binding runs nothing: the job
+     * starts only when a user sends the POST.
+     */
+    public void chashConstraintValidator(dev.nexus.service.db.ChashConstraintValidator validator) {
+        this.chashConstraintValidator = validator;
+    }
+
+    /**
+     * As {@link #chashConstraintValidator(dev.nexus.service.db.ChashConstraintValidator)} over {@code admin}, with this
+     * service's tenant scope and known-tenant list, so a refused table's bad rows can be counted by tenant.
+     */
+    public void chashConstraintValidator(dev.nexus.service.db.AdminConnection admin) {
+        this.chashConstraintValidator = new dev.nexus.service.db.ChashConstraintValidator(admin, tenantScope,
+            tokenStore::listKnownTenants);
+    }
+
     /**
      * Bind the engine-start drain of the retired {@code aspect_extraction_queue} table (nexus-hbnml) and schedule it
      * once, {@value #ASPECT_QUEUE_DRAIN_DELAY_SECONDS} seconds after the call, on the sweep thread. {@code Main}
@@ -1364,6 +1395,11 @@ public final class NexusService {
         return manifestFillJobs;
     }
 
+    /** Test seam (nexus-f3yqd): the registry the chash VALIDATE job lives in. */
+    dev.nexus.service.http.EngineJobs<dev.nexus.service.http.ValidateConstraintsJobs.Progress> validateConstraintsJobsForTests() {
+        return validateConstraintsJobs;
+    }
+
     /** The sink bound now (see {@link #chunkKeysAudit(dev.nexus.service.http.ChunkKeysAdminHandler.Audit)}). */
     public dev.nexus.service.http.ChunkKeysAdminHandler.Audit chunkKeysAudit() {
         return chunkKeysAudit;
@@ -2191,6 +2227,10 @@ public final class NexusService {
         chunkKeysJobs.shutdown();
         reconcileJobs.shutdown();
         manifestFillJobs.shutdown();
+        validateConstraintsJobs.shutdown();
+        if (chashConstraintValidator != null) {
+            chashConstraintValidator.cancelRunning();   // a VALIDATE must not outlive the engine that asked for it
+        }
         // The runner's executor too; an in-flight batch is interrupted, and a job left running resumes from its
         // cursor on the next boot.
         if (reembedExecutor != null) {

{conexus-8.2.0 → conexus-8.2.2}/service/src/main/java/dev/nexus/service/db/AdminDdlSession.java

@@ -42,6 +42,12 @@ public final class AdminDdlSession implements AutoCloseable {
     private static final String LOCK_TIMEOUT = "5s";
     /** Above the longest statement bound a caller sets, so the server gives up before the socket does. */
     private static final int SOCKET_TIMEOUT_SECONDS = 35 * 60;
+    /**
+     * The longest {@code statement_timeout} (or {@code lock_timeout}) a caller may set on this session, in milliseconds: a
+     * minute under the socket timeout, so the server gives up before the client's read does and the caller sees the
+     * server's SQLSTATE rather than a dropped socket. A configurable bound must be clamped to this.
+     */
+    public static final long MAX_STATEMENT_TIMEOUT_MS = (SOCKET_TIMEOUT_SECONDS - 60L) * 1000L;
     private static final int LOGIN_TIMEOUT_SECONDS = 30;
 
     /** SQLSTATE: lock_not_available (the 5 s lock_timeout tripped). */
@@ -57,11 +63,23 @@ public final class AdminDdlSession implements AutoCloseable {
     public static final class Refused extends RuntimeException {
         private final int status;
         private final String reason;
+        private final String sqlState;
 
         public Refused(int status, String reason, String message) {
+            this(status, reason, message, null);
+        }
+
+        /** {@code sqlState} is the SQLSTATE of the failed statement, or null when the refusal is not a statement's. */
+        public Refused(int status, String reason, String message, String sqlState) {
             super(message);
             this.status = status;
             this.reason = reason;
+            this.sqlState = sqlState;
+        }
+
+        /** The SQLSTATE of the statement that failed (55P03, 23514, 57014, ...), or null. */
+        public String sqlState() {
+            return sqlState;
         }
 
         public int status() {
@@ -97,12 +115,34 @@ public final class AdminDdlSession implements AutoCloseable {
     private final Connection conn;
     private final DSLContext ctx;
     private boolean locked;
+    /**
+     * The statement in flight on this session (a DDL, or any jOOQ query: {@link CancelTracker} records it), so another thread
+     * (the engine's shutdown) can cancel it; null between statements.
+     */
+    private volatile Statement running;
+    /** Set first by {@link #cancel}: a statement about to start sees it and does not start (see {@link #runDdl}). */
+    private volatile boolean cancelled;
+    /** The admin values this session was opened with (null for a session handed a connection), for {@link #cancel}'s fresh connection. */
+    private AdminConnection admin;
+    /** The server backend of this session's connection, or 0 when it is not known. */
+    private int backendPid;
+    /** When that backend started: with the pid it names this backend and no later one that reuses the pid. */
+    private java.time.OffsetDateTime backendStart;
+    /** Test seam: the admin values the backend cancel connects with, in place of {@link #admin} (an unreachable server). */
+    volatile AdminConnection resendAdminForTests;
+    /** The wall-clock bound of {@link #cancel}, in milliseconds (default {@value #DEFAULT_CANCEL_DEADLINE_MS}, 100 to 60000). */
+    public static final String CANCEL_DEADLINE_PROPERTY = "nexus.validate.cancel_deadline_ms";
+    static final long DEFAULT_CANCEL_DEADLINE_MS = 5_000L;
+
+    /** Test seam: {@link #cancel} skips the driver's statement cancel, so a test can show the backend cancel alone lands. */
+    volatile boolean statementCancelDisabledForTests;
 
     /** Package-private so a test can hand it a connection that fails where a real one rarely does. */
     AdminDdlSession(Settings settings, Connection conn) {
         this.settings = settings;
         this.conn = conn;
-        this.ctx = DSL.using(conn, SQLDialect.POSTGRES);
+        this.ctx = DSL.using(new org.jooq.impl.DefaultConfiguration().set(conn).set(SQLDialect.POSTGRES)
+            .set(new org.jooq.impl.DefaultExecuteListenerProvider(new CancelTracker())));
     }
 
     /**
@@ -119,6 +159,7 @@ public final class AdminDdlSession implements AutoCloseable {
         props.setProperty("loginTimeout", Integer.toString(LOGIN_TIMEOUT_SECONDS));
         props.setProperty("socketTimeout", Integer.toString(SOCKET_TIMEOUT_SECONDS));
         props.setProperty("tcpKeepAlive", "true");
+        props.setProperty("cancelSignalTimeout", "2");   // the driver's own cancel connection: seconds, not its default ten
         Connection conn;
         try {
             conn = DriverManager.getConnection(admin.url(), props);
@@ -128,6 +169,18 @@ public final class AdminDdlSession implements AutoCloseable {
                 "the constraint run could not open the admin connection: sqlstate=" + e.getSQLState());
         }
         AdminDdlSession s = new AdminDdlSession(settings, conn);
+        s.admin = admin;
+        try {
+            var pid = DSL.field(DSL.name("pid"), Integer.class);
+            var started = s.ctx.select(DSL.function("pg_backend_pid", SQLDataType.INTEGER),
+                    DSL.field(DSL.name("backend_start"), SQLDataType.TIMESTAMPWITHTIMEZONE))
+                .from(DSL.table(DSL.name("pg_catalog", "pg_stat_activity")))
+                .where(pid.eq(DSL.function("pg_backend_pid", SQLDataType.INTEGER))).fetchOne();
+            s.backendPid = started.value1();
+            s.backendStart = started.value2();
+        } catch (DataAccessException | NullPointerException e) {
+            s.backendPid = 0;   // cancel() then relies on the driver's statement cancel alone
+        }
         if (lock) {
             try {
                 s.lock();
@@ -414,7 +467,15 @@ public final class AdminDdlSession implements AutoCloseable {
             params[i + 1] = a instanceof String[] arr
                 ? DSL.val(arr, SQLDataType.CLOB.array()) : DSL.val((String) a);
         }
-        String sql = ctx.select(DSL.function("format", SQLDataType.CLOB, params)).fetchOne(0, String.class);
+        String sql;
+        try {
+            sql = ctx.select(DSL.function("format", SQLDataType.CLOB, params)).fetchOne(0, String.class);
+        } catch (DataAccessException e) {
+            if (QUERY_CANCELED.equals(e.sqlState()) && (cancelled || Thread.currentThread().isInterrupted())) {
+                throw refusal(new SQLException("the statement was cancelled before it started", QUERY_CANCELED));
+            }
+            throw e;
+        }
         try {
             runDdl(sql);
         } catch (SQLException e) {
@@ -428,7 +489,143 @@ public final class AdminDdlSession implements AutoCloseable {
     // concatenated in Java. Plain JDBC Statement.execute, as PciBuilderSession does. Single-homed: ddl.
     private void runDdl(String sql) throws SQLException {
         try (Statement st = conn.createStatement()) {
+            running = st;
+            // cancel() sets `cancelled` and then reads `running`; this sets `running` and then reads `cancelled`: either the
+            // cancel sees the statement or this sees the cancel, so a stop that lands before the statement starts is seen
+            // here (the engine's stop interrupts the thread before it cancels, so the interrupt flag says the same)
+            if (cancelled || Thread.currentThread().isInterrupted()) {
+                throw new SQLException("the statement was cancelled before it started", QUERY_CANCELED);
+            }
             st.execute(sql);
+        } finally {
+            running = null;
+        }
+    }
+
+    /** True once {@link #cancel} was called on this session: whatever it was about to do, it must not start. */
+    public boolean isCancelled() {
+        return cancelled;
+    }
+
+    /**
+     * Cancels the statement in flight, DDL or query, if any, and makes every later statement of this session refuse to
+     * start ({@link #isCancelled}, 57014). Safe from any thread; used by the engine's shutdown (synchronously), so a VALIDATE
+     * does not outlive the engine that started it.
+     *
+     * <p>What it guarantees. A statement whose start comes after this sets the flag is refused before it reaches the server
+     * (a DDL in {@link #runDdl}, a jOOQ query in {@link CancelTracker#executeStart}). A statement already past that check is
+     * cancelled: first by the driver's cancel on its statement, then, while it is still the statement in flight, by {@code
+     * pg_cancel_backend} on this session's backend from a fresh short-lived admin connection, re-sent every 100 ms. The
+     * re-send is what covers a cancel that landed in the instant before the server started the statement (the driver sends a
+     * statement's cancel once and PostgreSQL drops a signal that reaches an idle backend). It signals only the backend that
+     * was recorded at open, by pid AND backend start time, so a pid the server has since reused for another session is never
+     * signalled.
+     *
+     * <p>The whole of it is bounded by a WALL-CLOCK deadline, {@value #CANCEL_DEADLINE_PROPERTY} (default 5 s): each driver or
+     * re-send call runs on a daemon thread this waits for only as long as the deadline has left, and a re-send's connection
+     * gets connect, login and socket timeouts that fit in what is left, so a server that does not answer cannot hold the
+     * engine's shutdown past it. At the deadline this gives up: that one statement runs to its own timeout (the only case not
+     * covered), and every statement after it is refused.
+     */
+    public void cancel() {
+        cancelled = true;
+        long deadline = System.nanoTime() + java.util.concurrent.TimeUnit.MILLISECONDS.toNanos(
+            Math.max(100L, Math.min(60_000L, Long.getLong(CANCEL_DEADLINE_PROPERTY, DEFAULT_CANCEL_DEADLINE_MS))));
+        for (int attempt = 0; ; attempt++) {
+            Statement st = running;
+            if (st == null) return;
+            long remaining = deadline - System.nanoTime();
+            if (remaining <= 0) {
+                log.warn("event=admin_ddl_cancel_gave_up run={} backend_pid={}", settings.runLabel(), backendPid);
+                return;
+            }
+            if (attempt == 0 && !statementCancelDisabledForTests) {
+                boundedCall(() -> {
+                    try {
+                        st.cancel();
+                    } catch (SQLException e) {
+                        log.debug("event=admin_ddl_cancel_failed run={} cause=\"{}\"", settings.runLabel(), e.toString());
+                    }
+                }, remaining);
+            } else {
+                boundedCall(() -> cancelBackend(remaining), remaining);
+            }
+            try {
+                Thread.sleep(Math.min(100L, Math.max(1L, (deadline - System.nanoTime()) / 1_000_000L)));
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+                return;
+            }
+            if (running != st) return;   // it ended (cancelled, or finished first)
+        }
+    }
+
+    /** Runs {@code call} on a daemon thread and waits at most {@code remainingNanos} for it; a call that hangs is abandoned (it ends on its own timeouts). */
+    private static void boundedCall(Runnable call, long remainingNanos) {
+        Thread t = new Thread(call, "admin-ddl-cancel");
+        t.setDaemon(true);
+        t.start();
+        try {
+            t.join(Math.max(1L, remainingNanos / 1_000_000L));
+        } catch (InterruptedException e) {
+            Thread.currentThread().interrupt();
+        }
+    }
+
+    /**
+     * {@code pg_cancel_backend} on this session's backend, from a fresh connection that is closed again, only for the backend
+     * with the recorded pid AND start time; failures are logged only. The connection's timeouts fit in {@code remainingNanos}.
+     */
+    private void cancelBackend(long remainingNanos) {
+        AdminConnection target = resendAdminForTests != null ? resendAdminForTests : admin;
+        if (target == null || backendPid <= 0 || backendStart == null) return;
+        String seconds = Long.toString(Math.max(1L, (remainingNanos + 999_999_999L) / 1_000_000_000L));
+        Properties props = new Properties();
+        props.setProperty("user", target.user());
+        props.setProperty("password", target.password());
+        props.setProperty("ApplicationName", settings.applicationName() + "-cancel");
+        props.setProperty("connectTimeout", seconds);
+        props.setProperty("loginTimeout", seconds);
+        props.setProperty("socketTimeout", seconds);
+        try (Connection c = DriverManager.getConnection(target.url(), props)) {
+            c.setAutoCommit(true);
+            var pid = DSL.field(DSL.name("pid"), Integer.class);
+            var start = DSL.field(DSL.name("backend_start"), SQLDataType.TIMESTAMPWITHTIMEZONE);
+            DSL.using(c, SQLDialect.POSTGRES).select(DSL.function("pg_cancel_backend", SQLDataType.BOOLEAN, pid))
+                .from(DSL.table(DSL.name("pg_catalog", "pg_stat_activity"))).where(pid.eq(backendPid)).and(start.eq(backendStart))
+                .fetch();
+        } catch (SQLException | DataAccessException e) {
+            log.debug("event=admin_ddl_backend_cancel_failed run={} cause=\"{}\"", settings.runLabel(), e.toString());
+        }
+    }
+
+    /** Test seam: replaces the recorded backend start time, to show a pid whose start differs is not signalled. */
+    void backendStartForTests(java.time.OffsetDateTime start) {
+        this.backendStart = start;
+    }
+
+    /** Test seam: the backend start time recorded at open. */
+    java.time.OffsetDateTime backendStartForTests() {
+        return backendStart;
+    }
+
+    /**
+     * Records the statement a jOOQ query has in flight on this session, so {@link #cancel} can reach it, and refuses to start
+     * one after a cancel or an interrupt (the Dekker partner of {@link #cancel}: it publishes, then reads the flag).
+     */
+    private final class CancelTracker implements org.jooq.ExecuteListener {
+        @Override
+        public void executeStart(org.jooq.ExecuteContext c) {
+            running = c.statement();
+            if (cancelled || Thread.currentThread().isInterrupted()) {
+                throw new DataAccessException("the statement was cancelled before it started",
+                    new SQLException("the statement was cancelled before it started", QUERY_CANCELED));
+            }
+        }
+
+        @Override
+        public void end(org.jooq.ExecuteContext c) {
+            running = null;
         }
     }
 
@@ -438,23 +635,25 @@ public final class AdminDdlSession implements AutoCloseable {
             return new Refused(503, "lock_timeout",
                 "the table lock was not available within " + LOCK_TIMEOUT + ". Earlier constraints of this run "
                     + "may already have landed (a run is several statements, none rolled back); a rerun is safe: "
-                    + "add skips a constraint that exists and validate skips one that is valid");
+                    + "add skips a constraint that exists and validate skips one that is valid", state);
         }
         if (CHECK_VIOLATION.equals(state)) {
             return new Refused(409, "check_violation",
                 "VALIDATE found a row that breaks the constraint; it stays NOT VALID. Count the offenders with "
-                    + "the " + settings.offenderCount() + " and fix them first");
+                    + "the " + settings.offenderCount() + " and fix them first", state);
         }
         if (INSUFFICIENT_PRIVILEGE.equals(state)) {
             return new Refused(503, "insufficient_privilege",
-                "the admin role may not alter " + settings.tableLabel() + " (NX_DB_ADMIN_* must name its owner)");
+                "the admin role may not alter " + settings.tableLabel() + " (NX_DB_ADMIN_* must name its owner)", state);
         }
         log.warn("event=admin_ddl_failed run={} sqlstate={} cause=\"{}\"", settings.runLabel(), state, e.getMessage());
-        return new Refused(500, "ddl_failed", "the constraint statement failed: sqlstate=" + state);
+        return new Refused(500, "ddl_failed", "the constraint statement failed: sqlstate=" + state, state);
     }
 
     @Override
     public void close() {
+        // after a cancel the unlock below is refused like any statement (57014); that is swallowed here, and closing the
+        // connection releases the session lock all the same
         try {
             if (locked) {
                 ctx.select(DSL.function("pg_advisory_unlock", SQLDataType.BOOLEAN, DSL.val(settings.lockKey())))

{conexus-8.2.0 → conexus-8.2.2}/service/src/main/java/dev/nexus/service/db/ChashConformanceConstraints.java

@@ -22,7 +22,8 @@ import static dev.nexus.service.jooq.nexus.Tables.CHUNKS;
  *
  * <p><b>What it replaces, and what it does not.</b> It speaks to the two poison tables' width CHECKs only. The client's
  * legacy-debt legs ({@code topic_assignments}, {@code frecency}, {@code relevance_log}: anti-joins with no CHECK behind
- * them) are unchanged, and the migrations leave both CHECKs NOT VALID until the chash re-key rung validates them, so on a
+ * them) are unchanged, and the migrations leave both CHECKs NOT VALID until a user starts the VALIDATE job ({@code POST
+ * /v1/admin/validate-constraints}), so on a
  * fresh or never-validated store the answer is {@code all_validated: false} and nothing is saved. The payoff begins where a
  * store has been validated (the ladder's VALIDATE job of engine 0.1.190 is what makes that common).
  *
@@ -30,8 +31,8 @@ import static dev.nexus.service.jooq.nexus.Tables.CHUNKS;
  * ({@code nexus.db.chash_tables.POISON_CHASH_TABLES}: the tables that carry a width CHECK, so a non-conformant row
  * crash-loops an upgrade): {@code chunks_chash_octet_check} on {@code nexus.chunks} and
  * {@code catalog_document_chunks_chash_octet_check} on {@code nexus.catalog_document_chunks}, both
- * {@code CHECK (octet_length(chash) = 32)}, both added NOT VALID (rdr180-001, vectors-004) and validated by the chash
- * re-key rung's VALIDATE. The debt tables ({@code topic_assignments.doc_id}, {@code frecency.chunk_id},
+ * {@code CHECK (octet_length(chash) = 32)}, both added NOT VALID (rdr180-001, vectors-004) and validated by that
+ * job. The debt tables ({@code topic_assignments.doc_id}, {@code frecency.chunk_id},
  * {@code relevance_log.chunk_id}) carry no width CHECK and are NOT reported: a client that wants them counts them. A
  * same-named constraint on another relation (the retired {@code chunks_retired_225} carries its own
  * {@code chunks_chash_octet_check}) is not one of these and is never read: a constraint counts only through the table it
@@ -125,36 +126,54 @@ public final class ChashConformanceConstraints {
      * any other table (a same-named constraint on a retired table) leads to no root and is not counted.
      */
     static Report aggregate(List<Row> rows) {
-        Map<Long, Row> byRelation = new HashMap<>();
-        for (Row r : rows) byRelation.put(r.relation(), r);
         List<Entry> out = new ArrayList<>(TARGETS.size());
         for (Target t : TARGETS) {
-            Row root = rows.stream()
-                .filter(r -> r.relationParent() == 0 && r.relationName().equals(t.table().getName())
-                    && r.name().equals(t.constraint()))
-                .findFirst().orElse(null);
+            Tree tree = tree(t, rows);
+            Row root = tree.root();
             if (root == null) {
                 out.add(new Entry(t.qualifiedTable(), t.constraint(), false, false, false, 0, 0));
                 continue;
             }
-            int copies = 0;
             int notValid = 0;
             // A constraint that carries the right name with another expression (hand-recreated, weaker) is not the check this
             // reports on, validated or not: the root and every copy must deparse to the expected definition.
             boolean definitionMatches = normalise(root.definition()).equals(t.expectedDefinition());
-            for (Row r : rows) {
-                if (r.relation() != root.relation() && r.name().equals(root.name()) && descendsFrom(r, root.relation(), byRelation)) {
-                    copies++;
-                    if (!r.validated()) notValid++;
-                    if (!normalise(r.definition()).equals(t.expectedDefinition())) definitionMatches = false;
-                }
+            for (Row r : tree.copies()) {
+                if (!r.validated()) notValid++;
+                if (!normalise(r.definition()).equals(t.expectedDefinition())) definitionMatches = false;
             }
             out.add(new Entry(t.qualifiedTable(), t.constraint(), true, root.validated() && notValid == 0 && definitionMatches,
-                definitionMatches, copies, notValid));
+                definitionMatches, tree.copies().size(), notValid));
         }
         return new Report(List.copyOf(out));
     }
 
+    /**
+     * One target's rows: its {@code root}, the constraint on the declaring table (null when the constraint is absent), and its
+     * {@code copies}, the same-named constraint on every partition below it at any depth, in the order {@code rows} gave them.
+     * The report folds this, and the VALIDATE job ({@link ChashConstraintValidator}) walks it, so both read one definition of
+     * which rows belong to a target.
+     */
+    record Tree(Row root, List<Row> copies) {}
+
+    /** The rows of {@code t} among {@code rows}: see {@link Tree}. A same-named row on a table that leads to no root is in neither. */
+    static Tree tree(Target t, List<Row> rows) {
+        Map<Long, Row> byRelation = new HashMap<>();
+        for (Row r : rows) byRelation.put(r.relation(), r);
+        Row root = rows.stream()
+            .filter(r -> r.relationParent() == 0 && r.relationName().equals(t.table().getName())
+                && r.name().equals(t.constraint()))
+            .findFirst().orElse(null);
+        if (root == null) return new Tree(null, List.of());
+        List<Row> copies = new ArrayList<>();
+        for (Row r : rows) {
+            if (r.relation() != root.relation() && r.name().equals(root.name()) && descendsFrom(r, root.relation(), byRelation)) {
+                copies.add(r);
+            }
+        }
+        return new Tree(root, List.copyOf(copies));
+    }
+
     /** True when the table of {@code r} is below table {@code ancestor} through {@code relationParent} links (bounded, so a cycle cannot loop). */
     private static boolean descendsFrom(Row r, long ancestor, Map<Long, Row> byRelation) {
         Row at = r;