Merge pull request #1413 from Hellblazer/release/v6.14.0

release: conexus 6.14.0

Author: Hellblazer

.beads/interactions.jsonl

@@ -11,21 +11,21 @@
         "source": "git-subdir",
         "url": "https://github.com/Hellblazer/nexus.git",
         "path": "conexus",
-        "ref": "v6.13.1"
+        "ref": "v6.14.0"
       },
       "description": "Self-hosted three-tier knowledge management with 13 specialized agents, plan-centric retrieval via nx_answer, semantic search, and RDR decision tracking for Claude Code.",
-      "version": "6.13.1"
+      "version": "6.14.0"
     },
     {
       "name": "sn",
       "source": {
         "source": "git-subdir",
         "url": "https://github.com/Hellblazer/nexus.git",
         "path": "sn",
-        "ref": "v6.13.1"
+        "ref": "v6.14.0"
       },
       "description": "Injects Serena and Context7 MCP tool usage guidance into subagents via SubagentStart hook.",
-      "version": "6.13.1"
+      "version": "6.14.0"
     }
   ]
 }

.claude-plugin/marketplace.json

@@ -51,7 +51,7 @@ The Java CI (`service-ci.yml`) is **advisory** — it does not block auto-merge
 tests/e2e/migration-rehearsal/run.sh --guided      # local -Ob native build → nx guided-upgrade MVV
 ```
 
-Must end `GUIDED-UPGRADE MVV PASSED`.
+Must end `GUIDED LAND-THEN-TRANSFORM GATE PASSED` (marker renamed at the RDR-180 gate rewrite, nexus-jxizy.10.10).
 
 **Optional but recommended when the cut carries CLI-visible or concurrency-relevant service changes**: also run the candidate shakeout — the full CLI-verb matrix + incremental-index + concurrent-load journey against the SAME locally-built candidate (nexus-h8rf6; born from the 2026-07-03 post-release shakeout, whose findings were all locally discoverable):
 

.claude/skills/engine-release/SKILL.md

@@ -91,8 +91,11 @@ jobs:
           set -euo pipefail
           tests/e2e/migration-rehearsal/run.sh --guided 2>&1 | tee guided-mvv.log
           # Belt on the harness's own exit code: the success marker must be
-          # present (a truncated/killed run must not read as green).
-          grep -q "GUIDED-UPGRADE MVV PASSED" guided-mvv.log
+          # present (a truncated/killed run must not read as green). Marker
+          # renamed with the RDR-180 land-then-transform gate rewrite
+          # (nexus-jxizy.10.10) — the in-container run PASSED on 296cf85e
+          # while this grep still expected the old string.
+          grep -q "GUIDED LAND-THEN-TRANSFORM GATE PASSED" guided-mvv.log
 
       - name: Upload run log
         if: always()

.github/workflows/guided-upgrade-mvv.yml

@@ -39,11 +39,11 @@ Collection prefixes coexist in one T3 database. Always `__` (double underscore)
 
 | Prefix | Embedder | Document identity (catalog) | Chunk natural ID (T3) |
 |---|---|---|---|
-| `code__*` | `voyage-code-3` | `source_uri` (file path) | `chunk_text_hash[:32]` |
-| `docs__*`, `rdr__*` | `voyage-context-3` (CCE) | `source_uri` (file path) | `chunk_text_hash[:32]` |
-| `knowledge__*` | `voyage-context-3` | `source_uri` then `title` (fallback for MCP-stored notes) | `chunk_text_hash[:32]` |
+| `code__*` | `voyage-code-3` | `source_uri` (file path) | `chunk_text_hash` (full 64-hex; 32 bytes stored — RDR-180) |
+| `docs__*`, `rdr__*` | `voyage-context-3` (CCE) | `source_uri` (file path) | `chunk_text_hash` (full 64-hex) |
+| `knowledge__*` | `voyage-context-3` | `source_uri` then `title` (fallback for MCP-stored notes) | `chunk_text_hash` (full 64-hex) |
 
-**Catalog/T3 split (RDR-108)**: Catalog Documents are graph nodes addressed by tumblers (`Document.tumbler`); T3 chunks are content-addressed blobs whose Chroma natural ID is `sha256(chunk_text)[:32]`. Document structure (which chashes compose a doc, in what order) lives in the catalog `document_chunks` manifest, not in chunk metadata. The doc-to-chunks join is `documents.tumbler -> document_chunks.doc_id -> document_chunks.chash`; `chash[:32]` is the Chroma natural ID directly, no further lookup. Identical chunk text in the same collection collapses to one T3 row by design; the manifest preserves position via `(doc_id, position)` rows pointing at the shared chash.
+**Catalog/T3 split (RDR-108, widths per RDR-180)**: Catalog Documents are graph nodes addressed by tumblers (`Document.tumbler`); T3 chunks are content-addressed blobs whose natural ID is the FULL `sha256(chunk_text)` — 64 lowercase hex on the wire, 32 raw bytes in storage (`bytea`, `octet_length=32`); hex only at boundaries (see `docs/architecture.md` § Chunk identity). Document structure (which chashes compose a doc, in what order) lives in the catalog `document_chunks` manifest, not in chunk metadata. The doc-to-chunks join is `documents.tumbler -> document_chunks.doc_id -> document_chunks.chash`; the chash is the chunk id directly, no further lookup. Identical chunk text in the same collection collapses to one T3 row by design; the manifest preserves position via `(doc_id, position)` rows pointing at the shared chash.
 
 For the full module map, post-store hook contracts, T2 schema, and design heritage see [`docs/architecture.md`](docs/architecture.md). For module-local guidance see the `AGENTS.md` files inside `src/nexus/catalog/`, `src/nexus/db/`, and `src/nexus/mcp/`.
 

AGENTS.md

@@ -6,6 +6,48 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [6.14.0] - 2026-07-19
+
+Ships with (and requires) engine-service-v0.1.49.
+
+### Changed
+
+- **chash is now the full 32-byte SHA-256, stored as raw bytes** (RDR-180,
+  epic nexus-jxizy): the chunk content address was historically
+  `sha256(text)[:32]` — half the digest as hex text — while the citation
+  grammar advertised the full 64-hex. The producer now emits the full
+  digest, the engine stores `bytea` with `CHECK (octet_length(chash)=32)`,
+  and hex (64 lowercase chars) is strictly the interchange form. Requires
+  the paired RDR-180 engine generation; `nx upgrade`'s new `chash-rekey`
+  ladder rung performs the freeze-gated per-store cutover (rehash from
+  stored text, no re-embed) and records every legacy id in the permanent
+  `chash_alias` map so old 32-hex references stay resolvable forever.
+  The 32-vs-64 width bug class is structurally eliminated; content
+  citations (`chash:<64hex>`) now resolve at the full 256 bits they
+  always claimed.
+- **Guided migration is LAND-THEN-TRANSFORM** (RDR-180, nexus-jxizy.10):
+  the guided upgrade bulk-loads the legacy source into a PG staging schema,
+  then performs ONE transactional in-DB re-identification + promote —
+  retiring the per-leg in-flight rewrite class. The pregate width block is
+  gone: 16-char (GH #1408) and 32-hex legacy stores migrate; a disk
+  preflight and exact landing manifest run up front; promoted and rekeyed
+  rows carry `chunk_text_hash` metadata parity at every touch site, so
+  migrated chunks are immediately citable.
+
+### Fixed
+
+- **A table-rewriting migration now ANALYZEs what it rewrote, in the same
+  changelog pass** (engine-service-v0.1.49, BUG-0148/conexus-xpg7): the
+  RDR-180 `ALTER TYPE` boot conversion silently reset planner statistics —
+  and a rewritten table looks fresh to autovacuum, so autoanalyze may never
+  re-trigger — degrading sparse-text-gate hybrid queries to ZERO rows while
+  every health probe stayed green (observed live in the managed cloud,
+  2026-07-19). The engine floor bump is the delivery vehicle: this is why
+  6.14.0 requires v0.1.49. Related, benign: any table rewrite rebuilds the
+  HNSW indexes (graph construction is insertion-order dependent), so
+  borderline approximate-rank orderings can shift permanently after the
+  migration — re-baseline external oracles against post-migration serving.
+
 ## [6.13.1] - 2026-07-18
 
 Ships with (and requires) engine-service-v0.1.47 (unchanged from 6.13.0).

CHANGELOG.md

@@ -1,6 +1,6 @@
 {
   "name": "conexus",
-  "version": "6.13.1",
+  "version": "6.14.0",
   "description": "Self-hosted three-tier knowledge management with plan-centric retrieval (nx_answer), specialized agents, semantic search, and RDR decision tracking for Claude Code.",
   "author": {
     "name": "Hal Hildebrand",

conexus/.claude-plugin/plugin.json

@@ -4,6 +4,13 @@ All notable changes to the conexus plugin are documented here.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.14.0] - 2026-07-19
+
+- Plugin version aligned with conexus 6.14.0. No plugin-side changes. Root
+  CHANGELOG: chash is the full 32-byte SHA-256 (RDR-180); guided migration
+  is land-then-transform; engine pair v0.1.49 ANALYZEs rewritten tables in
+  the migration pass (BUG-0148).
+
 ## [6.13.1] - 2026-07-18
 
 - Plugin version aligned with conexus 6.13.1. No plugin-side changes. Root

conexus/CHANGELOG.md

@@ -190,6 +190,48 @@ addressing, the `document_chunks` manifest schema, span formats (`chash:<hex>`
 content-addressed spans vs. positional line/char spans), link types, the
 migration runbook, and admin/maintenance CLI surface.
 
+### Chunk identity: the canonical chash ([RDR-180](rdr/rdr-180-content-address-chash-binary-32byte.md))
+
+A **chash IS the 32-byte SHA-256 digest of the chunk text** — the full digest,
+never truncated. It has exactly two representations, with a hard rule about
+which appears where:
+
+- **Storage form: 32 raw bytes.** Postgres `BYTEA` with
+  `CHECK (octet_length(chash) = 32)`. Content-addressable storage keys on the
+  *value*, not its rendering; binary makes the width unambiguous (bytes are not
+  characters) and halves the key width vs hex text.
+- **Interchange form: 64 lowercase hex chars.** JSON wire values, the
+  `chash:[0-9a-f]{64}` citation grammar, CLI display, log lines. Hex belongs on
+  the wire, never in the key column.
+
+**One encode/decode seam, everywhere.** All conversions between the two forms
+go through a single boundary pair per side — nothing else encodes or decodes:
+
+| Side | Storage → interchange | Interchange → storage |
+|---|---|---|
+| Python client (`chunk_identity.py`) | `to_citation_hex()` | `to_storage_bytes()` |
+| Java engine (`db/Chash.java`) | `Chash.toHex()` | `Chash.fromHex()` / `Chash.fromSha256Bytes()` |
+
+Width validation lives inside that seam (the type constructor / the helper),
+so a wrong-width value fails loudly at the boundary with the offending length —
+never deep inside a transaction.
+
+**Why this is written down** (the bug class this eliminates): historically the
+stored chunk id was `sha256(chunk_text).hexdigest()[:32]` — 32 *hex chars* =
+128 bits = **half** the digest — while the citation grammar advertised the full
+64-hex digest, bridged by silent truncation. "32" meant hex-chars in one place
+and bytes in another. The canonical definition above makes the two subsystems
+agree at the full 256 bits, by construction.
+
+**Migration status:** the flip is IN this tree (epic `nexus-jxizy`): the
+producer emits the full digest, the engine stores bytea, and the
+`chash-rekey` ladder rung rekeys existing stores inside the freeze window. For every rehashable
+row the legacy 32-hex is the strict prefix of the new 64-hex (same text, same
+digest); the persisted `chash_alias` table is the collision-free resolver for
+legacy references thereafter (prefix matching only *builds* the map, it is not
+the resolver). The table below describes **current** (pre-flip) producer
+behavior.
+
 ### Metadata field semantics (chunk vs document level)
 
 Two hash fields look similar but mean very different things. Confusing them produces false-positive panic findings (e.g. "94% redundancy across the corpus" turns out to be 94% of chunks share a doc-level hash, which is correct: every chunk of one paper has the same `content_hash`). The table below locks the contract; consult before drawing conclusions from a metadata distribution.
@@ -198,7 +240,7 @@ Two hash fields look similar but mean very different things. Confusing them prod
 |---|---|---|---|---|
 | `content_hash` | document | `sha256(file_bytes)` | every indexer at register time (`indexer.py:1198`) | document-level dedup; staleness comparison; backup-snapshot identity |
 | `chunk_text_hash` | chunk | `sha256(chunk_text)` (full 64 chars) | every indexer per chunk; healed on an upgraded store by the ladder (`nx upgrade`) | content-addressed link spans (`chash:<hex>`); `nx t3 reidentify` natural-ID source (first 32 chars); cross-collection chunk dedup |
-| `chunk_text_hash[:32]` | chunk | first 32 chars of the SHA | `nx t3 reidentify` upsert ([RDR-108](rdr/rdr-108-graph-identity-normalization.md) Phase 2) | Chroma natural ID for the chunk; the join key from `document_chunks.chash` |
+| `chunk_text_hash` (as chunk id) | chunk | the full SHA (RDR-180) | every indexer via `chunk_identity.chunk_id` | the chunk natural ID and the `document_chunks.chash` join key; the pre-RDR-180 `[:32]` truncation is retired (legacy 32-hex references resolve via `chash_alias`) |
 | `source_uri` | document | `file://...` or `x-devonthink-item://<uuid>` etc. | indexer / MCP write paths | persistent URI identity; aspect-extraction routing; audit-membership home detection |
 | `source_path` | document | absolute or repo-relative file path | indexer | display + grep targets; legacy path predating `source_uri` |
 | `chunk_start_char` / `chunk_end_char` | chunk | char offsets in the source file | indexer per chunk | `chunk:char` span resolution; UI highlight |

docs/architecture.md

@@ -1028,7 +1028,7 @@ echo "# Cache Strategy" | nx store put - --collection knowledge --title "decisio
 | Subcommand | Description |
 |------------|-------------|
 | `put FILE_OR_DASH` | Store document (use `-` for stdin) |
-| `get DOC_ID` | Retrieve entry by 32-char hex ID (from `nx store list`) |
+| `get DOC_ID` | Retrieve entry by 64-char hex ID (from `nx store list`) |
 | `list` | List stored entries |
 | `delete` | Delete a single entry by ID or title |
 | `export [COLLECTION]` | Export a collection to portable `.nxexp` backup |
@@ -1059,11 +1059,11 @@ echo "# Cache Strategy" | nx store put - --collection knowledge --title "decisio
 | Flag | Description |
 |------|-------------|
 | `-c` / `--collection NAME` | Collection name (required) |
-| `--id ID` | Exact 32-char document ID from `nx store list` |
+| `--id ID` | Exact 64-char document ID from `nx store list` |
 | `--title TITLE` | Exact title metadata match (deletes all matching chunks) |
 | `-y` / `--yes` | Skip confirmation prompt |
 
-Note: IDs shown by `nx store list` are 32 hex chars (`sha256(text)[:32]`). `--title` delete is paginated and safe for multi-chunk documents. To delete an entire collection use `nx collection delete`.
+Note: IDs shown by `nx store list` are 64 hex chars (the full `sha256(text)` digest — RDR-180; pre-cohort 32-hex IDs resolve via the permanent `chash_alias` route). `--title` delete is paginated and safe for multi-chunk documents. To delete an entire collection use `nx collection delete`.
 
 **`get` flags:**
 
@@ -1090,9 +1090,10 @@ Note: IDs shown by `nx store list` are 32 hex chars (`sha256(text)[:32]`). `--ti
 | `--assume-model MODEL` | Override the export header's declared embedding model. Pre-migration `.nxexp` files can carry a wrong label (GH #1370); use this to supply the true model instead of trusting the header |
 | `--skip-existing` | Skip records whose id already exists in the target collection, instead of overwriting. Useful for resuming a partial import |
 
-Non-conformant legacy chunk ids (16-char pre-migration ids that fail the
-service backend's `chash` length constraint) are re-hashed to 32-char
-content-derived ids automatically; the CLI reports how many were re-hashed.
+Non-conformant legacy chunk ids (16- or 32-char pre-migration ids that fail
+the service backend's `chash` length constraint) are re-hashed to full 64-char
+content-derived ids automatically (RDR-180); the CLI reports how many were
+re-hashed.
 
 **Restoring a pre-migration (Chroma-era) backup:**