conexus 5.4.0__tar.gz → 5.4.2__tar.gz

{conexus-5.4.0 → conexus-5.4.2}/PKG-INFO

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

{conexus-5.4.0 → conexus-5.4.2}/docs/rdr/README.md

@@ -153,6 +153,7 @@ An RDR (Research-Design-Review) is a short document that records a technical dec
 | [RDR-135](rdr-135-windowed-aspect-extraction.md) | Windowed Aspect Extraction with Cross-Window Merge: Stop Whole-Paper Single-Shot Extraction from Degrading on Long Inputs | Architecture | Draft | 2026-05-27 |
 | [RDR-136](rdr-136-messagedisplay-projection-substrate.md) | Display Projection via the MessageDisplay Hook: One-Way Output Mirroring and Routing-Marker Hiding | Architecture | Draft | 2026-05-27 |
 | [RDR-137](rdr-137-eliminate-repos-json.md) | Eliminate repos.json: Catalog as the Canonical Repo→Collection Source of Truth | Architecture | Closed | 2026-05-28 |
+| [RDR-138](rdr-138-rename-cascade-aspect-worker-coordination.md) | Rename-Cascade / Aspect-Worker Coordination: Serialize T2 Collection Rename Against In-Flight Aspect Extraction | Architecture | Accepted | 2026-05-29 |
 
 > **Scrapped 2026-05-19 (RDR-110-119 arc).** Bundled the storage-substrate split with new abstractions (tuplespace, ORB, host-trust, surfaces-as-tuples, UI fabric); scope discipline failed across nine RDRs and 67 stranded beads. Files preserved as tombstones per the "never delete RDR files" rule. Postmortem: [docs/postmortem/2026-05-16-rdr110-113-remediation-chain.md](../postmortem/2026-05-16-rdr110-113-remediation-chain.md). Active substrate work continues as [RDR-120](rdr-120-storage-substrate-split.md) with an explicit moratorium on co-shipped consumers. Numbers RDR-114 through RDR-117 are unused on `main` (drafted on feature branches that never merged).
 

{conexus-5.4.0 → conexus-5.4.2}/mcpb/pyproject.toml

@@ -1,10 +1,10 @@
 [project]
 name = "conexus-mcpb"
-version = "5.4.0"
+version = "5.4.2"
 description = "Conexus packaged as Claude Desktop .mcpb (Desktop Extension)"
 requires-python = ">=3.12"
 dependencies = [
-    "conexus>=5.4.0",
+    "conexus>=5.4.2",
 ]
 
 [tool.uv]

{conexus-5.4.0 → conexus-5.4.2}/pyproject.toml

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

{conexus-5.4.0 → conexus-5.4.2}/src/nexus/db/t2/__init__.py

@@ -59,6 +59,7 @@ extend the tier.
 
 from __future__ import annotations
 
+import threading
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
@@ -306,6 +307,38 @@ class T2Database:
         if effective:
             T2Database.bootstrap_schema(path)
 
+        # ── RDR-138 T1.1 (nexus-tgzvt): process-wide rename coordination lock ──
+        #
+        # RENAME_LOCK is the OUTERMOST lock in the daemon process. It
+        # serializes ``rename_collection_cascade`` against every queue and
+        # aspect mutator, closing the rename-cascade vs aspect-worker race
+        # (Gaps 1-3 per the RDR).
+        #
+        # Lock type: ``threading.RLock`` (reentrant), NOT ``threading.Lock``.
+        # Rationale: T1.2 will guard ``claim_batch`` AND the inner
+        # ``claim_next`` it calls in a loop. A plain Lock would self-deadlock
+        # when the outer claim_batch acquire re-enters for each claim_next
+        # call. RLock allows the same thread to acquire again without blocking.
+        # An alternative shape (unlocked ``_claim_next_locked`` helper) is
+        # documented in ``AspectExtractionQueue`` but the RLock approach is
+        # chosen for its simplicity.
+        #
+        # Lock ordering (forward constraint for T1.2 authors):
+        #   RENAME_LOCK -> per-store self._lock   (RENAME_LOCK acquired FIRST)
+        #   NEVER acquire RENAME_LOCK while already inside a self._lock region.
+        #
+        # The daemon runs exactly ONE T2Database instance (verified by
+        # t2_daemon.py's ``_build_dispatch_table`` receiving a single
+        # ``self._t2db``). The lock is instance-held: tests that construct
+        # T2Database directly each get their own lock, isolating them from each
+        # other. Stand-alone AspectExtractionQueue construction (outside
+        # T2Database) falls back to its own RLock via the default parameter.
+        #
+        # The cascade (rename_collection_cascade) bypasses all per-store
+        # self._lock regions by design — it uses its own dedicated connection.
+        # It acquires only RENAME_LOCK.
+        self.RENAME_LOCK: threading.RLock = threading.RLock()
+
         # ── Construct domain stores ───────────────────────────────────
         self.memory: MemoryStore = MemoryStore(path)
         self.plans: PlanLibrary = PlanLibrary(path)
@@ -324,7 +357,11 @@ class T2Database:
         # RDR-089 follow-up (nexus-qeo8): durable queue feeding the
         # async aspect-extraction worker. The hook fires fast (just
         # an enqueue); the worker drains in a background thread.
-        self.aspect_queue: AspectExtractionQueue = AspectExtractionQueue(path)
+        # RDR-138 T1.1: inject RENAME_LOCK so the queue shares the same
+        # lock instance as the cascade. T1.2 will wrap mutator bodies.
+        self.aspect_queue: AspectExtractionQueue = AspectExtractionQueue(
+            path, rename_lock=self.RENAME_LOCK
+        )
 
         # RDR-120 P5.A.1 (nexus-9zmpl): catalog is the eighth domain
         # store. Constructed lazily via the ``catalog`` property so
@@ -532,7 +569,27 @@ class T2Database:
         ``_conn`` is a private test-seam parameter. Production callers
         omit it; the method opens a fresh dedicated connection. Tests
         pass a wrapper object to inject mid-cascade failures.
+
+        RDR-138 T1.1 (nexus-tgzvt): acquires ``self.RENAME_LOCK`` for the
+        ENTIRE method body — including the connection open, BEGIN, all
+        UPDATEs, COMMIT, and connection close. This serializes the cascade
+        against every queue/aspect mutator that T1.2 will also guard with
+        the same lock. Lock is held across the full SQLite transaction to
+        close Gaps 1-3 (aspect-worker observes a consistent view).
+        Lock ordering: RENAME_LOCK is the outermost lock. The cascade
+        bypasses all per-store ``self._lock`` regions by design (own conn).
         """
+        with self.RENAME_LOCK:
+            return self._rename_collection_cascade_locked(old=old, new=new, _conn=_conn)
+
+    def _rename_collection_cascade_locked(
+        self,
+        *,
+        old: str,
+        new: str,
+        _conn: "sqlite3.Connection | None" = None,
+    ) -> dict[str, int]:
+        """Inner implementation — called only while RENAME_LOCK is held."""
         counts: dict[str, int] = {
             "chash": 0,
             "aspects": 0,
@@ -1005,9 +1062,20 @@ class T2Database:
         idempotent, so a reclaim-driven re-extraction after a crash
         between the two writes simply re-upserts — no duplicate, no stuck
         row.
+
+        RDR-138 T1.2 (nexus-ra2vj): wraps the ENTIRE call — both the
+        ``document_aspects.upsert`` AND the ``aspect_queue.mark_done`` —
+        under ONE ``RENAME_LOCK`` acquisition. This closes Gap 3: a
+        ``rename_collection_cascade`` cannot interleave between the two
+        writes (which would rename the document_aspects row under the OLD
+        collection name before mark_done can clear the queue row, leaving
+        an orphaned queue row under OLD). The ``mark_done`` call
+        re-acquires RENAME_LOCK via the now-guarded mutator; the RLock
+        makes the re-entrant acquisition safe.
         """
         from nexus.db.t2.document_aspects import AspectRecord
         record = AspectRecord(**record_fields)
-        upserted = self.document_aspects.upsert(record)
-        self.aspect_queue.mark_done(record.collection, record.source_path)
+        with self.RENAME_LOCK:
+            upserted = self.document_aspects.upsert(record)
+            self.aspect_queue.mark_done(record.collection, record.source_path)
         return upserted

{conexus-5.4.0 → conexus-5.4.2}/src/nexus/db/t2/aspect_extraction_queue.py

@@ -146,10 +146,39 @@ class AspectExtractionQueue:
     """Owns the ``aspect_extraction_queue`` table.
 
     See module docstring for state transitions and locking contract.
+
+    Locking hierarchy (RDR-138 T1.1, nexus-tgzvt):
+
+    ``rename_lock`` (process-wide ``threading.RLock`` owned by
+    ``T2Database``) is the OUTERMOST lock — it must be acquired BEFORE any
+    ``self._lock`` region, NEVER while ``self._lock`` is already held.
+    Ordering: ``rename_lock`` -> ``self._lock``.
+
+    ``rename_lock`` is an ``RLock`` (not a plain ``Lock``) because
+    ``claim_batch`` calls ``claim_next`` in a loop. When T1.2 wraps both
+    with ``rename_lock``, a non-reentrant lock would self-deadlock on the
+    inner ``claim_next`` call. The ``RLock`` allows the same thread to
+    acquire it again safely. An alternative is an unlocked
+    ``_claim_next_locked()`` helper (callable while lock held), but
+    ``RLock`` is the simpler shape here given the bounded call depth.
     """
 
-    def __init__(self, path: Path) -> None:
+    def __init__(
+        self,
+        path: Path,
+        *,
+        rename_lock: "threading.RLock | None" = None,
+    ) -> None:
         self._lock = threading.Lock()
+        # RDR-138 T1.1 (nexus-tgzvt): process-wide outermost lock shared
+        # with T2Database and the rename_collection_cascade path. Injected
+        # by T2Database at construction so all three paths share the SAME
+        # lock instance. Falls back to a new RLock when constructed
+        # stand-alone (tests / direct construction outside T2Database).
+        # T1.2 will wrap every queue mutator body with this lock.
+        self.rename_lock: threading.RLock = (
+            rename_lock if rename_lock is not None else threading.RLock()
+        )
         self.conn = sqlite3.connect(str(path), check_same_thread=False)
         # nexus-v4m7y: bumped from 5s to 30s. Nine T2 stores hold their own
         # sqlite3.Connection against memory.db. Under WAL mode, only one
@@ -273,15 +302,16 @@ class AspectExtractionQueue:
         if not source_path:
             raise ValueError("source_path must not be empty")
         now = datetime.now(UTC).isoformat()
-        with self._lock:
-            self.conn.execute(
-                "INSERT OR REPLACE INTO aspect_extraction_queue "
-                "(collection, source_path, doc_id, content_hash, content, "
-                " status, retry_count, enqueued_at, last_attempt_at, last_error) "
-                "VALUES (?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL)",
-                (collection, source_path, doc_id, content_hash, content, now),
-            )
-            self.conn.commit()
+        with self.rename_lock:
+            with self._lock:
+                self.conn.execute(
+                    "INSERT OR REPLACE INTO aspect_extraction_queue "
+                    "(collection, source_path, doc_id, content_hash, content, "
+                    " status, retry_count, enqueued_at, last_attempt_at, last_error) "
+                    "VALUES (?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL)",
+                    (collection, source_path, doc_id, content_hash, content, now),
+                )
+                self.conn.commit()
 
     def claim_next(self) -> QueueRow | None:
         """Atomically claim the oldest pending row.
@@ -308,40 +338,41 @@ class AspectExtractionQueue:
         sequences across separate connections.
         """
         now = datetime.now(UTC).isoformat()
-        for _ in range(_MAX_CAS_RETRIES):
-            with self._lock:
-                row = self.conn.execute(
-                    "SELECT collection, source_path, content_hash, content, "
-                    "       retry_count, doc_id "
-                    "FROM aspect_extraction_queue "
-                    "WHERE status = 'pending' "
-                    "ORDER BY enqueued_at ASC, source_path ASC "
-                    "LIMIT 1"
-                ).fetchone()
-                if row is None:
-                    return None
-                collection, source_path, content_hash, content, retry_count, doc_id = row
-                cur = self.conn.execute(
-                    "UPDATE aspect_extraction_queue "
-                    "SET status = 'in_progress', last_attempt_at = ? "
-                    "WHERE collection = ? "
-                    "  AND source_path = ? "
-                    "  AND status = 'pending'",
-                    (now, collection, source_path),
-                )
-                self.conn.commit()
-                if cur.rowcount == 1:
-                    return QueueRow(
-                        collection=collection,
-                        source_path=source_path,
-                        content_hash=content_hash,
-                        content=content,
-                        retry_count=retry_count,
-                        doc_id=doc_id or "",
+        with self.rename_lock:
+            for _ in range(_MAX_CAS_RETRIES):
+                with self._lock:
+                    row = self.conn.execute(
+                        "SELECT collection, source_path, content_hash, content, "
+                        "       retry_count, doc_id "
+                        "FROM aspect_extraction_queue "
+                        "WHERE status = 'pending' "
+                        "ORDER BY enqueued_at ASC, source_path ASC "
+                        "LIMIT 1"
+                    ).fetchone()
+                    if row is None:
+                        return None
+                    collection, source_path, content_hash, content, retry_count, doc_id = row
+                    cur = self.conn.execute(
+                        "UPDATE aspect_extraction_queue "
+                        "SET status = 'in_progress', last_attempt_at = ? "
+                        "WHERE collection = ? "
+                        "  AND source_path = ? "
+                        "  AND status = 'pending'",
+                        (now, collection, source_path),
                     )
-                # rowcount == 0 → another process / thread won the
-                # CAS; loop and try a different row.
-        return None
+                    self.conn.commit()
+                    if cur.rowcount == 1:
+                        return QueueRow(
+                            collection=collection,
+                            source_path=source_path,
+                            content_hash=content_hash,
+                            content=content,
+                            retry_count=retry_count,
+                            doc_id=doc_id or "",
+                        )
+                    # rowcount == 0 → another process / thread won the
+                    # CAS; loop and try a different row.
+            return None
 
     def claim_batch(self, limit: int) -> list[QueueRow]:
         """Claim up to ``limit`` pending rows in FIFO order.
@@ -358,11 +389,12 @@ class AspectExtractionQueue:
         if limit <= 0:
             return []
         out: list[QueueRow] = []
-        for _ in range(limit):
-            row = self.claim_next()
-            if row is None:
-                break
-            out.append(row)
+        with self.rename_lock:
+            for _ in range(limit):
+                row = self.claim_next()
+                if row is None:
+                    break
+                out.append(row)
         return out
 
     def mark_done(
@@ -383,22 +415,23 @@ class AspectExtractionQueue:
         Returns deleted row count (0 when the row was already gone —
         idempotent under concurrent worker invocations).
         """
-        with self._lock:
-            if doc_id:
-                cur = self.conn.execute(
-                    "DELETE FROM aspect_extraction_queue WHERE doc_id = ?",
-                    (doc_id,),
-                )
-            elif collection or source_path:
-                cur = self.conn.execute(
-                    "DELETE FROM aspect_extraction_queue "
-                    "WHERE collection = ? AND source_path = ?",
-                    (collection, source_path),
-                )
-            else:
-                return 0
-            self.conn.commit()
-            return cur.rowcount
+        with self.rename_lock:
+            with self._lock:
+                if doc_id:
+                    cur = self.conn.execute(
+                        "DELETE FROM aspect_extraction_queue WHERE doc_id = ?",
+                        (doc_id,),
+                    )
+                elif collection or source_path:
+                    cur = self.conn.execute(
+                        "DELETE FROM aspect_extraction_queue "
+                        "WHERE collection = ? AND source_path = ?",
+                        (collection, source_path),
+                    )
+                else:
+                    return 0
+                self.conn.commit()
+                return cur.rowcount
 
     def mark_failed(
         self,
@@ -413,16 +446,17 @@ class AspectExtractionQueue:
         the row — re-extraction triggers can find failed rows and
         re-enqueue them.
         """
-        with self._lock:
-            self.conn.execute(
-                "UPDATE aspect_extraction_queue "
-                "SET status = 'failed', "
-                "    retry_count = retry_count + 1, "
-                "    last_error = ? "
-                "WHERE collection = ? AND source_path = ?",
-                (error[:2000], collection, source_path),
-            )
-            self.conn.commit()
+        with self.rename_lock:
+            with self._lock:
+                self.conn.execute(
+                    "UPDATE aspect_extraction_queue "
+                    "SET status = 'failed', "
+                    "    retry_count = retry_count + 1, "
+                    "    last_error = ? "
+                    "WHERE collection = ? AND source_path = ?",
+                    (error[:2000], collection, source_path),
+                )
+                self.conn.commit()
 
     def mark_retry(self, collection: str, source_path: str) -> None:
         """Reset the row to ``pending`` and increment ``retry_count``.
@@ -431,16 +465,17 @@ class AspectExtractionQueue:
         and the retry budget has not been exhausted. The next
         ``claim_next`` call will pick it up.
         """
-        with self._lock:
-            self.conn.execute(
-                "UPDATE aspect_extraction_queue "
-                "SET status = 'pending', "
-                "    retry_count = retry_count + 1, "
-                "    last_attempt_at = NULL "
-                "WHERE collection = ? AND source_path = ?",
-                (collection, source_path),
-            )
-            self.conn.commit()
+        with self.rename_lock:
+            with self._lock:
+                self.conn.execute(
+                    "UPDATE aspect_extraction_queue "
+                    "SET status = 'pending', "
+                    "    retry_count = retry_count + 1, "
+                    "    last_attempt_at = NULL "
+                    "WHERE collection = ? AND source_path = ?",
+                    (collection, source_path),
+                )
+                self.conn.commit()
 
     # nexus-v4m7y: retry-with-backoff for reclaim_stale. Three attempts
     # with two inter-attempt sleeps (0.1s, 0.5s) on top of the 30s
@@ -481,21 +516,22 @@ class AspectExtractionQueue:
         max_attempts = len(sleeps_between) + 1
         for attempt in range(1, max_attempts + 1):
             try:
-                with self._lock:
-                    cur = self.conn.execute(
-                        "UPDATE aspect_extraction_queue "
-                        "SET status = 'pending', last_attempt_at = NULL "
-                        "WHERE status = 'in_progress' "
-                        f"  AND datetime(last_attempt_at) < {cutoff_clause}",
-                    )
-                    self.conn.commit()
-                    if attempt > 1:
-                        _log.debug(
-                            "aspect_queue_reclaim_stale_recovered",
-                            attempt=attempt,
-                            rowcount=cur.rowcount,
+                with self.rename_lock:
+                    with self._lock:
+                        cur = self.conn.execute(
+                            "UPDATE aspect_extraction_queue "
+                            "SET status = 'pending', last_attempt_at = NULL "
+                            "WHERE status = 'in_progress' "
+                            f"  AND datetime(last_attempt_at) < {cutoff_clause}",
                         )
-                    return cur.rowcount
+                        self.conn.commit()
+                        if attempt > 1:
+                            _log.debug(
+                                "aspect_queue_reclaim_stale_recovered",
+                                attempt=attempt,
+                                rowcount=cur.rowcount,
+                            )
+                        return cur.rowcount
             except sqlite3.OperationalError as exc:
                 # Only retry on writer-slot contention. Anything else
                 # (schema corruption, FK violation, etc.) propagates
@@ -583,23 +619,32 @@ class AspectExtractionQueue:
         Returns row count updated (0 when no rows match -- safe no-op).
         Idempotent: a second call with the same ``old`` name returns 0
         without error.
+
+        RDR-138 follow-up (nexus-k44w4): this standalone queue-rename has no
+        production caller — ``rename_collection_cascade`` re-homes the queue
+        inline on its own dedicated connection. It survives as a tested store
+        primitive. It acquires ``rename_lock`` (outermost, before ``self._lock``)
+        so that if it IS ever invoked directly it serializes against the cascade
+        and every queue mutator, the same as the 7 guarded mutators. Lock
+        ordering matches the rest of the store: ``rename_lock`` -> ``self._lock``.
         """
-        with self._lock:
-            # Drop any pre-existing new-collection rows that would collide
-            # with the rename (same source_path). Mirrors ChashIndex pattern.
-            self.conn.execute(
-                "DELETE FROM aspect_extraction_queue "
-                "WHERE collection = ? "
-                "  AND source_path IN ("
-                "    SELECT source_path FROM aspect_extraction_queue"
-                "    WHERE collection = ?"
-                "  )",
-                (new, old),
-            )
-            cur = self.conn.execute(
-                "UPDATE aspect_extraction_queue "
-                "SET collection = ? WHERE collection = ?",
-                (new, old),
-            )
-            self.conn.commit()
-            return cur.rowcount
+        with self.rename_lock:
+            with self._lock:
+                # Drop any pre-existing new-collection rows that would collide
+                # with the rename (same source_path). Mirrors ChashIndex pattern.
+                self.conn.execute(
+                    "DELETE FROM aspect_extraction_queue "
+                    "WHERE collection = ? "
+                    "  AND source_path IN ("
+                    "    SELECT source_path FROM aspect_extraction_queue"
+                    "    WHERE collection = ?"
+                    "  )",
+                    (new, old),
+                )
+                cur = self.conn.execute(
+                    "UPDATE aspect_extraction_queue "
+                    "SET collection = ? WHERE collection = ?",
+                    (new, old),
+                )
+                self.conn.commit()
+                return cur.rowcount

{conexus-5.4.0 → conexus-5.4.2}/src/nexus/indexer.py

@@ -2006,6 +2006,21 @@ def _run_index(
     # these with conformant names before the indexer reads from T3.
     code_collection = info.get("code_collection", info["collection"])
     docs_collection = info.get("docs_collection") or _repo_collection_or_legacy(repo, "docs")
+    # nexus-5ut2a: the registry value can carry a legacy 2-segment name
+    # (``code__<owner>``) when repos.json holds a pre-RDR-103 entry for a
+    # repo that has no catalog owner yet (e.g. a stale entry from a prior
+    # failed run, or the RDR-137 migration's un-cataloged residue). The
+    # Phase-4 migration below is a no-op without an owner, so an
+    # un-reconciled legacy name would reach the strict get_or_create_collection
+    # guard (db/t3.py) and crash the whole index. Re-route any
+    # non-conformant value through the path-derived conformant synth, which
+    # builds ``code__<owner>__<model>__v1`` without needing a registered
+    # owner (model segment self-adjusts to local/cloud mode).
+    from nexus.corpus import is_conformant_collection_name  # noqa: PLC0415
+    if not is_conformant_collection_name(code_collection):
+        code_collection = _repo_collection_or_legacy(repo, "code")
+    if not is_conformant_collection_name(docs_collection):
+        docs_collection = _repo_collection_or_legacy(repo, "docs")
     _migrated_names: dict[str, str] = {}
 
     # Load config (picks up per-repo .nexus.yml if present)