{"id":33609390,"url":"https://github.com/hivellm/nexus","last_synced_at":"2026-05-02T23:05:54.469Z","repository":{"id":320493338,"uuid":"1082296987","full_name":"hivellm/nexus","owner":"hivellm","description":"Nexus is a modern graph database built for read-heavy workloads with first-class KNN (K-Nearest Neighbors) support. Inspired by Neo4j's architecture, it combines the power of graph traversal with vector similarity search for hybrid RAG (Retrieval-Augmented Generation) applications.","archived":false,"fork":false,"pushed_at":"2026-04-26T13:45:14.000Z","size":32774,"stargazers_count":4,"open_issues_count":0,"forks_count":2,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T14:32:49.758Z","etag":null,"topics":["graphdb","knn-algorithm","rust"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hivellm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security/AUTHENTICATION.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-10-24T03:10:39.000Z","updated_at":"2026-04-26T10:38:01.000Z","dependencies_parsed_at":"2025-10-24T05:33:16.005Z","dependency_job_id":"1737d4c9-516a-49f0-a5f7-ed70e48f283f","html_url":"https://github.com/hivellm/nexus","commit_stats":null,"previous_names":["hivellm/nexus"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/hivellm/nexus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivellm%2Fnexus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivellm%2Fnexus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivellm%2Fnexus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivellm%2Fnexus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hivellm","download_url":"https://codeload.github.com/hivellm/nexus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivellm%2Fnexus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32550915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-02T21:31:48.061Z","status":"ssl_error","status_checked_at":"2026-05-02T21:31:46.574Z","response_time":132,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["graphdb","knn-algorithm","rust"],"created_at":"2025-11-30T19:02:49.891Z","updated_at":"2026-05-02T23:05:54.460Z","avatar_url":"https://github.com/hivellm.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nexus Graph Database\n\n**⚡ High-performance property graph database with native vector search and binary-RPC-first clients**\n\n![Rust](https://img.shields.io/badge/rust-nightly%201.85%2B-orange.svg)\n![Edition](https://img.shields.io/badge/edition-2024-blue.svg)\n![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)\n![Status](https://img.shields.io/badge/status-v2.1.0-success.svg)\n![Tests](https://img.shields.io/badge/tests-2310%2B%20passing-success.svg)\n![Compatibility](https://img.shields.io/badge/Neo4j%20compat-300%2F300-success.svg)\n\n[Quick Start](#-quick-start) • [Transports](#-transports) • [Documentation](#-documentation) • [SDKs](#-official-sdks) • [Roadmap](#-roadmap) • [Contributing](#-contributing)\n\n---\n\n## 🎯 What is Nexus?\n\nNexus is a **property graph database** built for **read-heavy workloads** with **first-class vector search**. Inspired by Neo4j's storage architecture, it combines graph traversal with approximate nearest-neighbor search for hybrid **RAG**, **recommendation**, and **knowledge-graph** applications.\n\n**Think Neo4j meets vector search**, shipped as a single Rust binary with a CLI, six first-party SDKs, and three transports (native binary RPC, HTTP/JSON, RESP3).\n\n### Highlights (v2.1.0)\n\n- **Neo4j-compatible Cypher** — MATCH / CREATE / MERGE / SET / DELETE / REMOVE / WHERE / RETURN / ORDER BY / LIMIT / SKIP / UNION / WITH / UNWIND / FOREACH / CASE / EXISTS subqueries / list \u0026 map comprehensions / pattern comprehensions and 250+ functions \u0026 procedures. **300/300** Neo4j diff-suite tests pass ([Neo4j 2025.09.0, 2026-04-19](docs/compatibility/NEO4J_COMPATIBILITY_REPORT.md)). See the [openCypher status table](#-opencypher-support-matrix) at the bottom.\n- **APOC compatibility** — ~100 procedures across `apoc.coll.*` / `apoc.map.*` / `apoc.text.*` / `apoc.date.*` / `apoc.schema.*` / `apoc.util.*` / `apoc.convert.*` / `apoc.number.*` / `apoc.agg.*`. Drop-in replacement for most of the Neo4j APOC surface. Matrix: [`docs/procedures/APOC_COMPATIBILITY.md`](docs/procedures/APOC_COMPATIBILITY.md).\n- **Full-text search** — Tantivy 0.22 backend behind the Neo4j `db.index.fulltext.*` procedure namespace. Per-index analyzer catalogue (standard / whitespace / simple / keyword / ngram / english / spanish / portuguese / german / french), BM25 ranking, WAL-integrated auto-maintenance on CREATE / SET / REMOVE / DELETE, optional async writer with `refresh_ms` cadence, crash-recovery replay. \u003e60k docs/sec bulk ingest, \u003c5 ms p95 single-term query.\n- **Constraint enforcement** — `UNIQUE` / `NODE KEY` / `NOT NULL` (node + relationship) / property-type (`IS :: INTEGER|FLOAT|STRING|BOOLEAN|BYTES|LIST|MAP`) enforced on every CREATE / MERGE / SET / REMOVE / SET LABEL path. Cypher 25 `FOR (n:L) REQUIRE (...)` DDL grammar wired.\n- **Advanced types** — BYTES scalar family (`bytes()` / `bytesFromBase64` / `bytesSlice` / …), write-side dynamic labels (`CREATE (n:$label)` / `SET n:$label` / `REMOVE n:$label`), composite B-tree indexes, `LIST\u003cT\u003e` typed collections, transaction savepoints (`SAVEPOINT` / `ROLLBACK TO SAVEPOINT` / `RELEASE SAVEPOINT`), `GRAPH[\u003cname\u003e]` preamble.\n- **External node IDs** *(new in 2.1.0)* — caller-supplied stable identifiers via the reserved `_id` property. `CREATE (n {_id: '...'}) ON CONFLICT ERROR|MATCH|REPLACE`, `MERGE (n {_id: '...'})`, and `MATCH (n {_id: ...})` all hit a dedicated `O(log n)` catalog index (forward + reverse LMDB sub-DBs, WAL-replay safe). `ExternalId` wire format covers Hash (Blake3 / SHA-256 / SHA-512), Uuid, String (≤256 B), and Bytes (≤64 B). REST surface: `POST /data/nodes` with `external_id` + `conflict_policy`, `GET /data/nodes/by-external-id`. All six SDKs ship `create_node_with_external_id` + `get_node_by_external_id` helpers. See [`docs/reference/external-node-ids.md`](docs/reference/external-node-ids.md).\n- **Native KNN** — per-label HNSW indexes with cosine / L2 / dot metrics. Bytes-native embeddings on the RPC wire (no base64 tax).\n- **Binary RPC default** — length-prefixed MessagePack on port `15475`; 3–10× lower latency and 40–60% smaller payloads vs HTTP/JSON. `nexus://host:15475` URL scheme used by CLI + every SDK.\n- **Full auth stack** — API keys, JWT, RBAC, rate limiting, audit log with fail-open policy.\n- **Three-layer back-pressure** — per-key rate limiter + per-connection RPC semaphore + global `AdmissionQueue` (bounded concurrency with FIFO wait + `503 Retry-After` on timeout). Light-weight diagnostic endpoints bypass the queue. [`docs/security/OVERLOAD_PROTECTION.md`](docs/security/OVERLOAD_PROTECTION.md).\n- **Multi-database** — isolated databases in a single server instance, CLI + Cypher + SDK.\n- **SIMD-accelerated hot paths** — AVX-512 / AVX2 / NEON runtime dispatch. 12.7× KNN dot @ dim=768 on Zen 4, 7.9× `sum_f64` @ 262K rows, all with proptest-enforced parity vs scalar.\n- **V2 sharded cluster (core)** — hash-based shards, per-shard Raft consensus, distributed query coordinator, `/cluster/*` management API. +201 V2-dedicated tests.\n- **2310+ workspace tests** passing on `cargo +nightly test --workspace` (0 failed, 67 ignored). 2019 lib-only on `cargo +nightly test -p nexus-core --lib`.\n\n## 🚀 Quick Start\n\n### Install (pre-built binary)\n\n```bash\n# Linux / macOS\ncurl -fsSL https://raw.githubusercontent.com/hivellm/nexus/main/scripts/install/install.sh | bash\n\n# Windows (PowerShell)\npowershell -c \"irm https://raw.githubusercontent.com/hivellm/nexus/main/scripts/install/install.ps1 | iex\"\n```\n\nThe installer puts `nexus-server` and `nexus` (CLI) on `PATH` and registers a system service.\n\n### Install (from source)\n\n```bash\ngit clone https://github.com/hivellm/nexus\ncd nexus\ncargo +nightly build --release --workspace\n./target/release/nexus-server        # default: 127.0.0.1:15474 (HTTP) + 127.0.0.1:15475 (RPC)\n```\n\n### First query with the CLI\n\n```bash\n./target/release/nexus query \"RETURN 1 + 2 AS sum, 'hello' AS greeting\"\n# ┌─────┬──────────┐\n# │ sum │ greeting │\n# ╞═════╪══════════╡\n# │ 3.0 │ hello    │\n# └─────┴──────────┘\n```\n\nThe CLI defaults to `nexus://127.0.0.1:15475` (binary RPC). Every subcommand (`query`, `db`, `user`, `key`, `schema`, `data`) goes through RPC. See [`crates/nexus-cli/README.md`](crates/nexus-cli/README.md) for the full command reference.\n\n### First query from a SDK (Rust)\n\n```rust\nuse nexus_sdk::NexusClient;\n\n#[tokio::main]\nasync fn main() -\u003e Result\u003c(), Box\u003cdyn std::error::Error\u003e\u003e {\n    let client = NexusClient::new(\"nexus://127.0.0.1:15475\")?;\n    let result = client.execute_cypher(\"MATCH (n:Person) RETURN n.name LIMIT 10\", None).await?;\n    println!(\"{} rows via {}\", result.rows.len(), client.endpoint_description());\n    Ok(())\n}\n```\n\nSee [sdks/](sdks/README.md) for install + quick-start in every language.\n\n### First query over HTTP (legacy / diagnostic)\n\n```bash\ncurl -X POST http://localhost:15474/cypher \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"query\": \"RETURN 1 + 2 AS sum\"}'\n# {\"columns\":[\"sum\"],\"rows\":[[3]],\"execution_time_ms\":1}\n```\n\n## 🧬 Transports\n\n| URL form                  | Transport              | Default port | Use case                                     |\n|---------------------------|------------------------|--------------|----------------------------------------------|\n| `nexus://host[:port]`     | Binary RPC (MessagePack) | `15475`    | **Default.** CLI + SDK. Fastest path.       |\n| `http://host[:port]`      | HTTP/JSON              | `15474`      | Browser builds, firewalls, diagnostic.      |\n| `https://host[:port]`     | HTTPS/JSON             | `443`        | Public-internet HTTP with TLS.              |\n| `resp3://host[:port]`     | RESP3 (Redis-style)    | `15476`      | `redis-cli` / `iredis` / Grafana debug tail. |\n\nEvery CLI and SDK reads a URL scheme, honours the `NEXUS_SDK_TRANSPORT` / `NEXUS_TRANSPORT` env var, and falls back to an explicit `transport` field in config. The URL scheme wins over env/config. Full spec: [`docs/specs/sdk-transport.md`](docs/specs/sdk-transport.md).\n\n**There is no `nexus-rpc://` or `nexus+rpc://` scheme.** The canonical single-token scheme is `nexus`.\n\n## 🌟 Features\n\n### Graph engine\n- **Property graph model** — labels + types + properties on nodes and relationships.\n- **Cypher subset** — familiar Neo4j syntax. See [docs/specs/cypher-subset.md](docs/specs/cypher-subset.md).\n- **Record-store architecture** — 32-byte nodes, 48-byte relationships, O(1) traversal via linked adjacency lists.\n- **ACID transactions** — single-writer + epoch-based MVCC, WAL for crash recovery.\n- **19 GDS procedures** — PageRank (standard / weighted / parallel), betweenness, eigenvector, Dijkstra, A\\*, Yen's k-paths, Louvain, label propagation, triangle count, clustering coefficients.\n\n### Vector search (native)\n- **HNSW indexes** per label (`cosine` / `l2` / `dot`).\n- **Bytes-native embeddings** on the RPC wire — send `NexusValue::Bytes` of little-endian `f32` directly, no base64.\n- **Hybrid queries** — combine `CALL vector.knn` with graph traversal in a single Cypher statement.\n\n### Performance\n- **Runtime SIMD dispatch** — `NEXUS_SIMD_DISABLE=1` for emergency rollback, no rebuild.\n- **Linear-time Cypher parser** — O(N²) → O(N) fix, ~290× faster on 32 KiB queries.\n- **Hierarchical cache** (L1/L2/L3) with 90%+ hit rates.\n- **Runtime-dispatched CRC32C** for WAL (hardware-accelerated).\n- **JIT query compilation** (Cranelift) for hot paths.\n\n### Benchmarks — Nexus vs Neo4j 5.15 Community\n\nNexus native RPC vs Neo4j Bolt, both in Docker, shared tiny dataset (100 nodes / 50 edges), 2 warmup + 10 measured runs per scenario, release build. Harness: `crates/nexus-bench` (`--compare` mode).\n\n- **56 / 56 head-to-head wins for Nexus** (0 parity, 0 behind, 0 gap; 42 Nexus-only features skipped).\n- Nexus p50 is between **0.08× and 0.55× of Neo4j p50** — median **4.7× faster**, best case **12.5×**.\n\n| Category | Scenarios | Median speedup |\n|---|---|---|\n| `aggregation` | 5 | **9.1×** |\n| `constraint` | 3 | **6.7×** |\n| `hybrid` (vector + graph) | 1 | **5.6×** |\n| `filter` | 4 | **5.3×** |\n| `label_scan` | 2 | **5.3×** |\n| `subquery` | 6 | **4.7×** |\n| `scalar` | 14 | **4.3×** |\n| `write` | 5 | **4.2×** |\n| `point_read` | 2 | **4.1×** |\n| `order` | 2 | **3.3×** |\n| `procedure` | 4 | **3.0×** |\n| `traversal` | 7 | **2.6×** |\n\nTop wins: `aggregation.avg_score_a` 12.5× · `aggregation.count_all` 11.1× · `ecosystem.call_in_transactions` 10.0× · `aggregation.stdev_score` 9.1× · `aggregation.min_max_score` 8.3×. Closest margin still Nexus-ahead: `traversal.two_hop_chain` 1.8×. Full report at [`target/bench/report.md`](target/bench/report.md) after running [`crates/nexus-bench/README.md`](crates/nexus-bench/README.md).\n\n\u003e The 74-test cross-bench numbers under [`docs/performance/BENCHMARK_NEXUS_VS_NEO4J.md`](docs/performance/BENCHMARK_NEXUS_VS_NEO4J.md) (the older Dec-2025 record) are flagged stale and pending re-run on v2.0.0+; reproduction recipe + concurrent-load matrix scaffold ships with [`scripts/benchmarks/run-vs-neo4j.sh`](scripts/benchmarks/run-vs-neo4j.sh).\n\n### Security + Ops\n- **API keys + JWT + RBAC** with rate limiting (1k/min, 10k/hour default).\n- **Audit logging** — fail-open with `nexus_audit_log_failures_total` metric; never converts IO pressure into mass 500s. Rationale: [`docs/security/SECURITY_AUDIT.md §5`](docs/security/SECURITY_AUDIT.md).\n- **Prometheus metrics** — `/prometheus` endpoint exposes query / cache / connection / audit counters.\n- **Master-replica replication** — WAL streaming, async / sync modes, automatic failover.\n- **V2 sharded cluster (core)** — hash-partitioned shards with per-shard Raft consensus, distributed query coordinator, cross-shard traversal, `/cluster/*` management API. Opt-in via `[cluster.sharding]`. See [`docs/guides/DISTRIBUTED_DEPLOYMENT.md`](docs/guides/DISTRIBUTED_DEPLOYMENT.md).\n\n## 🏗️ Architecture\n\n```\n┌───────────────────────────────────────────────────────────────────────┐\n│                         Client transports                             │\n│  Binary RPC (15475)   │    HTTP/JSON (15474)   │   RESP3 (15476)      │\n│  nexus_protocol::rpc  │    axum routes         │   resp3 TCP listener │\n└─────────┬─────────────┴───────────┬────────────┴───────────┬──────────┘\n          │                         │                        │\n          └─────────────┬───────────┴────────────────────────┘\n                        │\n┌───────────────────────┴──────────────────────────────────┐\n│                   Cypher Executor                        │\n│        Pattern Match • Expand • Filter • Project         │\n│         Heuristic Cost-Based Query Planner               │\n└───────────────────────┬──────────────────────────────────┘\n                        │\n┌───────────────────────┴──────────────────────────────────┐\n│            Transaction Layer (MVCC)                      │\n│      Epoch-Based Snapshots • Single-Writer Locking       │\n└───────────────────────┬──────────────────────────────────┘\n                        │\n┌───────────────────────┴──────────────────────────────────┐\n│                   Index Layer                            │\n│   Label Bitmap • B-tree • Full-Text • KNN (HNSW)         │\n└───────────────────────┬──────────────────────────────────┘\n                        │\n┌───────────────────────┴──────────────────────────────────┐\n│                  Storage Layer                           │\n│  Catalog (LMDB) • WAL • Record Stores • Page Cache       │\n└──────────────────────────────────────────────────────────┘\n```\n\n| Layer                   | Tech                            | Purpose                                       |\n|-------------------------|---------------------------------|-----------------------------------------------|\n| Binary RPC listener     | `nexus_protocol::rpc` + tokio   | Default transport, multiplexed connections.  |\n| HTTP router             | `axum`                          | REST + SSE + MCP + UMICP + GraphQL.          |\n| RESP3 listener          | Hand-written parser             | `redis-cli`-compatible debug port.           |\n| Catalog                 | LMDB via `heed`                 | Label / type / key ID mappings.              |\n| Record stores           | `memmap2` fixed-size records    | 32-byte nodes, 48-byte relationships.        |\n| Page cache              | Custom (Clock / 2Q / TinyLFU)   | 8 KB pages, hot-data retention.              |\n| WAL                     | Append-only with CRC32C         | Crash recovery + replication stream.         |\n| KNN                     | `hnsw_rs`                       | Per-label HNSW vector index.                 |\n| Executor                | Custom                          | Cypher parser + planner + operators.         |\n\nFull detail: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n## 🗄️ Multi-database\n\n```cypher\n-- Via Cypher (CLI / SDK / HTTP all work)\nSHOW DATABASES\nCREATE DATABASE mydb\n:USE mydb\nRETURN database() AS current_db\nDROP DATABASE mydb\n```\n\n```bash\n# Via the CLI\nnexus db list\nnexus db create mydb\nnexus db switch mydb\nnexus db info\nnexus db drop mydb\n```\n\nEvery SDK ships equivalent methods (`list_databases` / `listDatabases` / etc.). Databases are fully isolated — separate catalogs, stores, and indexes. See [`docs/users/guides/MULTI_DATABASE.md`](docs/users/guides/MULTI_DATABASE.md) for the full lifecycle guide.\n\n## 📦 Official SDKs\n\nSix first-party SDKs, all tracking the same 2.1.0 line. Every SDK shares the URL grammar, command-map table, and error semantics defined in [`docs/specs/sdk-transport.md`](docs/specs/sdk-transport.md).\n\n| SDK            | Install                                    | Docs                                          | RPC status   |\n|----------------|--------------------------------------------|-----------------------------------------------|--------------|\n| 🦀 Rust        | `nexus-sdk = \"2.1.0\"`                     | [sdks/rust/](sdks/rust/README.md)             | ✅ shipped   |\n| 🐍 Python      | `pip install hivehub-nexus-sdk`            | [sdks/python/](sdks/python/README.md)         | ✅ shipped   |\n| 📘 TypeScript  | `npm install @hivehub/nexus-sdk`           | [sdks/typescript/](sdks/typescript/README.md) | ✅ shipped   |\n| 🐹 Go          | `go get github.com/hivellm/nexus-go`       | [sdks/go/](sdks/go/README.md)                 | ✅ shipped   |\n| 💜 C#          | `dotnet add package Nexus.SDK`             | [sdks/csharp/](sdks/csharp/README.md)         | ✅ shipped   |\n| 🐘 PHP         | `composer require hivellm/nexus-php`       | [sdks/php/](sdks/php/README.md)               | ✅ shipped   |\n\nEvery SDK defaults to `nexus://host:15475` (binary RPC) and falls back to HTTP/JSON when given an `http://` URL. RESP3 is a diagnostic port — SDKs refuse `resp3://` with a clear error pointing at the transport spec. Transport precedence across languages: **URL scheme \u003e `NEXUS_SDK_TRANSPORT` env \u003e config field \u003e `nexus` default**.\n\n### SDK quick examples\n\n**Python**:\n```python\nfrom nexus_sdk import NexusClient\n\nasync with NexusClient(\"nexus://127.0.0.1:15475\") as client:\n    result = await client.execute_cypher(\"MATCH (n:Person) RETURN n.name LIMIT 10\")\n    print(f\"Found {len(result.rows)} people via {client.endpoint_description()}\")\n```\n\n**TypeScript**:\n```typescript\nimport { NexusClient } from '@hivehub/nexus-sdk';\n\nconst client = new NexusClient({ baseUrl: 'nexus://127.0.0.1:15475' });\nconst result = await client.executeCypher('MATCH (n:Person) RETURN n.name LIMIT 10');\nconsole.log(`Found ${result.rows.length} people`);\n```\n\n**Rust**:\n```rust\nuse nexus_sdk::NexusClient;\nlet client = NexusClient::new(\"nexus://127.0.0.1:15475\")?;\nlet result = client.execute_cypher(\"MATCH (n:Person) RETURN n.name LIMIT 10\", None).await?;\n```\n\n## 🖥️ Desktop GUI\n\nA React 18 + TypeScript desktop client lives under [`gui/`](gui/).\nCypher editor (Monaco), force-directed graph result view\n(`react-force-graph-2d`), live-metrics drawer with sparklines,\nmulti-connection management, dark / light theme. Run it against\nany nexus-server with:\n\n```bash\ncd gui\nNEXUS_NO_ELECTRON=1 npx vite      # opens http://localhost:15475/\n```\n\nSee [`gui/README.md`](gui/README.md) for the component map and\nthe dev workflow. The mockup source files this rewrite mirrors\nlive at [`docs/design/gui-mockup-v2/`](docs/design/gui-mockup-v2/).\n\n## ⚙️ Configuration\n\n### Environment variables (server)\n\n| Var                           | Default              | Purpose                                    |\n|-------------------------------|----------------------|--------------------------------------------|\n| `NEXUS_ADDR`                  | `127.0.0.1:15474`    | HTTP bind address.                        |\n| `NEXUS_RPC_ADDR`              | `127.0.0.1:15475`    | Binary RPC bind address.                  |\n| `NEXUS_RESP3_ENABLED`         | `false`              | Enable RESP3 listener on `15476`.         |\n| `NEXUS_DATA_DIR`              | `./data`             | Storage root (catalog + stores + WAL).    |\n| `NEXUS_AUTH_ENABLED`          | `true` for `0.0.0.0` | Force API-key / RBAC authentication.      |\n| `NEXUS_REPLICATION_ROLE`      | `standalone`         | `master`, `replica`, or `standalone`.     |\n| `NEXUS_REPLICATION_MODE`      | `async`              | `async` or `sync`.                        |\n| `NEXUS_SIMD_DISABLE`          | `0`                  | Emergency scalar fallback across kernels. |\n| `RUST_LOG`                    | `info`               | Logging level (`error`/`warn`/`info`/`debug`/`trace`). |\n\n### Environment variables (CLI / SDK)\n\n| Var                      | Effect                                                           |\n|--------------------------|------------------------------------------------------------------|\n| `NEXUS_URL`              | Endpoint URL for the CLI (`nexus://`, `http://`, etc.).         |\n| `NEXUS_TRANSPORT`        | Force CLI transport (`nexus` / `http` / `auto`).                |\n| `NEXUS_SDK_TRANSPORT`    | Same semantics for SDKs.                                         |\n| `NEXUS_API_KEY`          | API-key authentication (CLI).                                   |\n| `NEXUS_USERNAME` / `NEXUS_PASSWORD` | Username/password authentication (CLI).               |\n\n### Data directory layout\n\n```\ndata/\n├── catalog.mdb          # LMDB catalog (labels, types, keys)\n├── nodes.store          # 32-byte node records\n├── rels.store           # 48-byte relationship records\n├── props.store          # Variable-size property records\n├── strings.store        # String / blob dictionary\n├── wal.log              # Write-ahead log (v1 / v2 frames)\n├── checkpoints/         # Per-epoch snapshots\n└── indexes/\n    ├── label_*.bitmap   # Label bitmap indexes (RoaringBitmap)\n    └── hnsw_*.bin       # HNSW vector indexes\n```\n\n## 🔐 Authentication\n\nAuth is **disabled by default on 127.0.0.1** (local dev) and **required for 0.0.0.0 binding**. The first admin is the configured root user; every subsequent user is created via `CREATE USER` Cypher.\n\n```bash\n# Create the first user + API key via the CLI\nnexus --username root --password root user create alice --password secret\nnexus --username alice --password secret key create myapp\n\n# Use the API key on later requests\nnexus --api-key nexus_sk_abc123... query \"RETURN 1\"\n```\n\nRate limiting: 1k requests/minute and 10k/hour per API key, returning `429 Too Many Requests` when exceeded. Full details: [`docs/security/AUTHENTICATION.md`](docs/security/AUTHENTICATION.md).\n\n### RESP3 debug port\n\n```bash\nNEXUS_RESP3_ENABLED=true ./nexus-server\n# in another shell:\nredis-cli -p 15476\n127.0.0.1:15476\u003e HELLO 3 AUTH root root\n127.0.0.1:15476\u003e CYPHER \"MATCH (n) RETURN count(n) AS c\"\n127.0.0.1:15476\u003e STATS\n```\n\nNot Redis emulation — `SET key value` returns `-ERR unknown command 'SET' (Nexus is a graph DB, see HELP)`. Full vocabulary: [`docs/specs/resp3-nexus-commands.md`](docs/specs/resp3-nexus-commands.md).\n\n## 🔄 Replication\n\nMaster-replica replication ships in 1.0.0. Use the master for writes, replicas for reads.\n\n```bash\n# Master\nNEXUS_REPLICATION_ROLE=master \\\nNEXUS_REPLICATION_BIND_ADDR=0.0.0.0:15475 \\\n./nexus-server\n\n# Replica\nNEXUS_REPLICATION_ROLE=replica \\\nNEXUS_REPLICATION_MASTER_ADDR=master:15475 \\\n./nexus-server\n```\n\n| Endpoint               | Method | Purpose                          |\n|------------------------|--------|----------------------------------|\n| `/replication/status`  | GET    | Role + lag + connected replicas. |\n| `/replication/promote` | POST   | Promote a replica.               |\n| `/replication/pause`   | POST   | Pause WAL streaming.             |\n| `/replication/resume`  | POST   | Resume WAL streaming.            |\n| `/replication/lag`     | GET    | Real-time lag metrics.           |\n\nFeatures: full sync via snapshot, incremental WAL streaming (circular buffer, 1M ops), async / sync modes, auto-reconnect with exponential backoff.\n\n## 🕸️ Sharded Cluster (V2)\n\nNexus V2 adds horizontal scalability through **hash-based sharding** with\n**per-shard Raft consensus** and a **distributed query coordinator**.\nStandalone deployments are unaffected — sharding is opt-in via\n`[cluster.sharding]`.\n\n```toml\n# config.toml\n[cluster.sharding]\nmode = \"bootstrap\"        # \"disabled\" | \"bootstrap\" | \"join\"\nnode_id = \"node-a\"\nlisten_addr = \"0.0.0.0:15480\"\npeers = [\n  { node_id = \"node-a\", addr = \"10.0.0.1:15480\" },\n  { node_id = \"node-b\", addr = \"10.0.0.2:15480\" },\n  { node_id = \"node-c\", addr = \"10.0.0.3:15480\" },\n]\nnum_shards = 3\nreplica_factor = 3\n```\n\n| Endpoint                  | Method | Purpose                                   |\n|---------------------------|--------|-------------------------------------------|\n| `/cluster/status`         | GET    | Layout + generation + per-shard health.  |\n| `/cluster/add_node`       | POST   | Admin: register a node (leader-only).    |\n| `/cluster/remove_node`    | POST   | Admin: remove a node, `drain: true` opt. |\n| `/cluster/rebalance`      | POST   | Admin: trigger rebalancer.               |\n| `/cluster/shards/{id}`    | GET    | Per-shard detail.                        |\n\nGuarantees:\n\n- **Leader election** ≤ 3× election timeout (~900 ms default).\n- **Majority quorum replication** — 3-replica shard tolerates 1 loss,\n  5-replica tolerates 2.\n- **Atomic scatter/gather** — any shard failure fails the whole query\n  (no partial rows).\n- **Generation-tagged metadata** — stale coordinator caches detected\n  via `ERR_STALE_GEN` and refreshed once before retry.\n- **Leader-hint retry** — scatter RPCs retry up to 3× against the new\n  leader on `ERR_NOT_LEADER`.\n\nFull operator guide + failure-mode table:\n[`docs/guides/DISTRIBUTED_DEPLOYMENT.md`](docs/guides/DISTRIBUTED_DEPLOYMENT.md).\nMulti-host TCP transport between replicas is scheduled in the\n[`phase5_v2-tcp-transport-bridge`](.rulebook/tasks/phase5_v2-tcp-transport-bridge/)\nfollow-up task; the current in-process transport covers single-host\nclusters and all integration scenarios.\n\n## 📦 Use cases\n\n### RAG (Retrieval-Augmented Generation)\n```cypher\nCALL vector.knn('Document', $query_vector, 10)\nYIELD node AS doc, score\nMATCH (doc)-[:CITES]-\u003e(cited:Document)\nRETURN doc.title, doc.content, COLLECT(cited.title) AS citations, score\nORDER BY score DESC\n```\n\n### Recommendation engine\n```cypher\nMATCH (user:Person {id: $user_id})-[:LIKES]-\u003e(item:Product)\nMATCH (item)\u003c-[:LIKES]-(similar:Person)\nMATCH (similar)-[:LIKES]-\u003e(recommendation:Product)\nWHERE NOT (user)-[:LIKES]-\u003e(recommendation)\nRETURN recommendation.name, COUNT(*) AS score\nORDER BY score DESC LIMIT 10\n```\n\n### Code analysis + LLM context\n```cypher\nCALL graph.generate('call_graph', {scope: {file_patterns: ['*.rs']}})\nYIELD graph_id\nCALL graph.analyze(graph_id, 'pattern_detection')\nYIELD pattern_type, confidence, nodes\nWHERE confidence \u003e 0.8\nRETURN pattern_type, confidence, SIZE(nodes) AS pattern_size\nORDER BY confidence DESC\n```\n\n## 📖 Documentation\n\n### User-facing\n- [`docs/users/`](docs/users/README.md) — getting started, Cypher reference, API guide, SDKs, ops, tuning.\n- [`docs/users/getting-started/`](docs/users/getting-started/) — installation, Docker, first query.\n- [`docs/users/cypher/`](docs/users/cypher/) — supported Cypher grammar.\n- [`docs/users/vector-search/`](docs/users/vector-search/) — HNSW + hybrid queries.\n- [`docs/users/configuration/`](docs/users/configuration/) — server, logging, performance, cluster.\n\n### Architecture + specs\n- [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — system design.\n- [`docs/ROADMAP.md`](docs/ROADMAP.md) — development phases.\n- [`docs/specs/`](docs/specs/) — binary specs (storage format, Cypher subset, page cache, WAL/MVCC, KNN, RPC wire format, RESP3 vocabulary, SDK transport, SIMD dispatch).\n\n### Compatibility\n- [`docs/compatibility/NEO4J_COMPATIBILITY_REPORT.md`](docs/compatibility/NEO4J_COMPATIBILITY_REPORT.md) — **300/300** tests (Neo4j 2025.09.0 diff), per-feature breakdown.\n\n### Performance\n- [`docs/performance/PERFORMANCE_V1.md`](docs/performance/PERFORMANCE_V1.md) — throughput, latency, vs-Neo4j benchmark matrix.\n- [`docs/performance/MEMORY_TUNING.md`](docs/performance/MEMORY_TUNING.md) — cache sizes, page budgets, Docker memtest.\n- [`docs/performance/KNN_RECALL.md`](docs/performance/KNN_RECALL.md) — HNSW recall@1/10/100 + latency p50/p95/p99 on SIFT1M and GloVe-200d.\n\n### Deployment\n- [`deploy/helm/nexus/`](deploy/helm/nexus/README.md) — official Helm chart (single-node + sharded cluster topology).\n- [`deploy/docker-compose/`](deploy/docker-compose/README.md) — single-node, master-replica, and v2-cluster Compose stacks.\n- [`docs/operations/KUBERNETES.md`](docs/operations/KUBERNETES.md) — install, upgrade, scaling, TLS, observability, backups.\n\n### Migration\n- [`docs/migration/FROM_KUZU.md`](docs/migration/FROM_KUZU.md) — **migrating from KuzuDB** (archived 2025-10-10). Schema mapping, Cypher dialect deltas, vector + FTS port, embedded-mode replacement, three end-to-end cookbooks.\n- [`scripts/migration/`](scripts/migration/README.md) — Kùzu CSV → Nexus bulk RPC ingester + Cypher dialect translator.\n\n## 🗺️ Roadmap\n\n### 2.0.0 — current (2026-04-30)\n- ✅ Property graph engine + broad openCypher surface + 19 GDS procedures + ~100 APOC procedures.\n- ✅ **300/300** Neo4j diff suite (2025.09.0).\n- ✅ Native HNSW KNN per label.\n- ✅ Binary RPC default, HTTP/JSON legacy, RESP3 debug.\n- ✅ CLI + six SDKs on the RPC-first 1.x line.\n- ✅ Authentication (API keys, JWT, RBAC, rate limiting, audit log with fail-open policy).\n- ✅ Three-layer back-pressure (per-key rate limit + per-connection RPC semaphore + global admission queue).\n- ✅ Multi-database with `SHOW DATABASES` / `CREATE DATABASE` / `DROP DATABASE` / `:USE`.\n- ✅ Master-replica replication (async / sync).\n- ✅ SIMD kernels (AVX-512 / AVX2 / NEON) with runtime dispatch.\n- ✅ **Full-text search** (Tantivy 0.22) with per-index analyzer catalogue, WAL auto-maintenance, optional async writer.\n- ✅ **Constraint enforcement** for UNIQUE / NODE KEY / NOT NULL / property-type + Cypher 25 `FOR (n:L) REQUIRE (...)` DDL.\n- ✅ **Advanced types**: BYTES family, dynamic labels on writes, composite B-tree indexes, `LIST\u003cT\u003e` typed collections, savepoints, `GRAPH[\u003cname\u003e]` scoping.\n- ✅ **APOC ecosystem** — `apoc.coll.*` / `apoc.map.*` / `apoc.text.*` / `apoc.date.*` / `apoc.schema.*` / `apoc.util.*` / `apoc.convert.*` / `apoc.number.*` / `apoc.agg.*`.\n- ✅ **System procedures** — `db.indexes`, `db.constraints`, `db.labels`, `db.schema.*`, `dbms.*`.\n- ✅ openCypher quickwins — type-check predicates, `isEmpty` polymorphism, list converters, string extractors, dynamic property access, `SET +=`.\n- ✅ **V2 sharding core** (2026-04-20) — hash-based shards, per-shard Raft consensus, distributed query coordinator, `/cluster/*` API. +201 V2 tests.\n- ✅ **V2 multi-host TCP transport bridge** (2026-04-20) — Raft replicas over TCP, single-host in-process transport retained for tests.\n- ✅ **Nexus vs Neo4j benchmark suite** — Docker-based harness, 14/14 Lead on the live compare run (2026-04-21).\n\n### Queued on 1.x\n\nEvery item below is an active rulebook task under [`.rulebook/tasks/`](.rulebook/tasks/). Pick one up via `rulebook_task_show \u003ctaskId\u003e`.\n\n**openCypher coverage** (broadening Neo4j 5.x parity):\n- 🧭 [`phase6_opencypher-quantified-path-patterns`](.rulebook/tasks/phase6_opencypher-quantified-path-patterns/) — Neo4j 5.9 QPP syntax (`()-[]-\u003e{1,5}()`). Grammar + AST variant shipped 2026-04-21; execution engine pending.\n- 🧭 [`phase6_opencypher-subquery-transactions`](.rulebook/tasks/phase6_opencypher-subquery-transactions/) — `CALL {} IN TRANSACTIONS OF N ROWS [ON ERROR …] [REPORT STATUS …]`. Grammar slice landed 2026-04-22.\n- 🧭 [`phase6_opencypher-geospatial-predicates`](.rulebook/tasks/phase6_opencypher-geospatial-predicates/) — R-tree index + point / polygon predicates.\n\n**Infrastructure \u0026 ops**:\n- 🧭 [`phase5_implement-cluster-mode`](.rulebook/tasks/phase5_implement-cluster-mode/) — cluster-mode implementation (active, 90/417 items).\n- 🧭 [`phase5_implement-v1-gui`](.rulebook/tasks/phase5_implement-v1-gui/) — Electron + Vue 3 desktop app (`gui/` scaffolded).\n- 🧭 [`phase5_hub-integration`](.rulebook/tasks/phase5_hub-integration/) — HiveHub SaaS multi-tenant control plane (billing, per-user databases).\n\n**Protocol polish**:\n- 🧭 **RESP3 in non-Rust SDKs** — every SDK accepts `resp3://` URLs and throws a clear error; parser/writer queued for a subsequent 1.x release.\n- 🧭 **Streaming Cypher / live queries** — RPC push frame is reserved (`PUSH_ID = u32::MAX`); no SDK consumer yet.\n\n### V2 — distributed ✅ core complete (2026-04-20)\n- ✅ **Sharding** — deterministic xxh3 hash partitioning, generation-tagged metadata, iterative rebalancer ([`crates/nexus-core/src/sharding/`](crates/nexus-core/src/sharding/)).\n- ✅ **Raft consensus** — purpose-built per-shard Raft with leader election, log replication, snapshot install, 5-node tolerates 2 failures ([`crates/nexus-core/src/sharding/raft/`](crates/nexus-core/src/sharding/raft/)).\n- ✅ **Distributed queries** — scatter/gather coordinator with atomic failure, leader-hint retry, COUNT/SUM/AVG decomposition, top-k merge ([`crates/nexus-core/src/coordinator/`](crates/nexus-core/src/coordinator/)).\n- ✅ **Cluster operations** — `/cluster/*` management API, admin-gated, 307 redirect on followers, drain semantics ([`crates/nexus-server/src/api/cluster.rs`](crates/nexus-server/src/api/cluster.rs)).\n- ✅ **Multi-host TCP transport** — Raft replica bridge over TCP (2026-04-20).\n- 🧭 **Online re-sharding / cross-shard 2PC / geo-distribution** — V2.1 / V3.\n\nFull detail: [`docs/ROADMAP.md`](docs/ROADMAP.md).\n\n## ⚡ Why Nexus?\n\n| Property         | Neo4j                | Redis / Redis Stack   | **Nexus**                                |\n|------------------|----------------------|-----------------------|------------------------------------------|\n| Query language   | Cypher (full)        | RedisGraph Cypher     | Cypher 25 + ~100 APOC procedures         |\n| Storage model    | Record stores        | In-memory / flash     | Record stores (Neo4j-inspired)           |\n| Vector search    | GDS plugin           | Redis Search module   | **Native HNSW per label**                |\n| Default transport| Bolt binary          | RESP3                 | **Binary RPC (MessagePack)**, HTTP, RESP3 |\n| SDKs             | Official 7 languages | Extensive community   | 6 first-party, same 2.0.0 cadence       |\n| Target workload  | General graph OLTP   | In-memory KV + graph  | **Read-heavy + RAG + vector hybrid**     |\n\n### Sweet spot\n- RAG with citation + semantic hybrid.\n- Recommendation systems over labeled embeddings.\n- Knowledge graphs with vector-seeded expansion.\n- Code-analysis call graphs + pattern detection for LLM context.\n\n### Not ideal\n- Write-heavy OLTP — use a traditional RDBMS.\n- Pure key-value — use Redis or Synap.\n- Document-only search — use Elasticsearch or the Vectorizer standalone.\n\n## 🧮 openCypher Support Matrix\n\nCanonical list of openCypher / Cypher 25 surfaces in Nexus v2.1.0. ✅ shipped · 🟡 partial (grammar-only or limited scope) · 🧭 queued. Validated against the [300/300 Neo4j diff suite](docs/compatibility/NEO4J_COMPATIBILITY_REPORT.md); per-clause detail lives in [`docs/specs/cypher-subset.md`](docs/specs/cypher-subset.md).\n\n### Reading clauses\n\n| Clause / feature | Status | Notes |\n|------------------|--------|-------|\n| `MATCH` (nodes, relationships, multiple labels, directed / undirected) | ✅ | Label intersection via RoaringBitmap. |\n| Variable-length paths `*`, `*n`, `*m..n`, `+`, `?` | ✅ | Planner routes to optimized BFS for bounded lengths. |\n| `OPTIONAL MATCH` | ✅ | Left-outer semantics, null propagation. |\n| Quantified path patterns `()-[]-\u003e{m,n}()` | 🟡 | Grammar + AST shipped (2026-04-21); execution engine in [`phase6_opencypher-quantified-path-patterns`](.rulebook/tasks/phase6_opencypher-quantified-path-patterns/). |\n| `WHERE` (after `MATCH` / `OPTIONAL MATCH` / `WITH`) | ✅ | Clause-ordering rule enforced since `phase3_unwind-where-neo4j-parity`. |\n| `WITH` (projection, aggregation, chaining) | ✅ | Supports `DISTINCT`, `ORDER BY`, `LIMIT`, `SKIP`, `WHERE`. |\n| `UNWIND` | ✅ | Into `CREATE`, aggregation, filter. |\n| `RETURN` — projection, `DISTINCT`, `AS` alias, `n.*` | ✅ | Including complex expressions + CASE in projections. |\n| `ORDER BY` / `SKIP` / `LIMIT` | ✅ | Top-k merge for distributed queries. |\n| `UNION` / `UNION ALL` | ✅ | |\n| `CALL` subquery (`CALL { … }`) | ✅ | Scalar + row-level. |\n| `CALL { … } IN TRANSACTIONS OF N ROWS` | 🟡 | Grammar + suffix clauses landed 2026-04-22 ([`phase6_opencypher-subquery-transactions`](.rulebook/tasks/phase6_opencypher-subquery-transactions/)); executor integration pending. |\n| Named paths (`p = (a)-[*]-(b)`) + `nodes(p)` / `relationships(p)` / `length(p)` | ✅ | |\n| `shortestPath()` / `allShortestPaths()` | ✅ | |\n| Pattern comprehensions `[(n)-[]-\u003e(m) \\| m.name]` | ✅ | |\n| List comprehensions `[x IN list WHERE … \\| …]` | ✅ | |\n| Map projection `n {.prop, alias: expr}` | ✅ | |\n| `CASE` (simple + generic) | ✅ | |\n| `EXISTS { … }` subqueries | ✅ | |\n\n### Writing clauses\n\n| Clause / feature | Status | Notes |\n|------------------|--------|-------|\n| `CREATE` nodes / relationships (with properties, multi-label) | ✅ | |\n| `MERGE` (+ `ON CREATE SET` / `ON MATCH SET`) | ✅ | |\n| `SET` property / `SET n += map` / multi-property | ✅ | |\n| `SET n:Label` (add label) / `REMOVE n:Label` | ✅ | |\n| `SET n:$label` / `REMOVE n:$label` / `CREATE (n:$label)` (write-side dynamic labels) | ✅ | STRING or `LIST\u003cSTRING\u003e` parameter. |\n| `DELETE` / `DETACH DELETE` | ✅ | RPC parity fixed in v1.0.0 release. |\n| `REMOVE` property | ✅ | |\n| `FOREACH (x IN list \\| …)` | ✅ | |\n| `LOAD CSV` (+ `WITH HEADERS`) | ✅ | |\n| `SAVEPOINT` / `ROLLBACK TO SAVEPOINT` / `RELEASE SAVEPOINT` | ✅ | Nested LIFO unwind. |\n\n### Schema \u0026 constraints\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| `CREATE INDEX [IF NOT EXISTS]` / `DROP INDEX [IF EXISTS]` on single property | ✅ | |\n| Composite B-tree indexes `ON (n.p1, n.p2, …)` | ✅ | Exact / prefix / range seeks + optional uniqueness flag. |\n| Full-text indexes via `db.index.fulltext.createNodeIndex` / `createRelationshipIndex` | ✅ | Tantivy 0.22, per-index analyzer catalogue. |\n| FTS query procedures (`queryNodes` / `queryRelationships`) | ✅ | BM25 ranking, top-k, tie-break on node id. |\n| FTS `drop` / `listAvailableAnalyzers` / `awaitEventuallyConsistentIndexRefresh` | ✅ | |\n| FTS WAL integration (auto-populate on CREATE / SET / REMOVE / DELETE, crash replay) | ✅ | v1.11 + v1.12. |\n| FTS per-index async writer with `refresh_ms` cadence | ✅ | v1.13; default remains sync (read-your-writes). |\n| Spatial indexes | 🟡 | `CREATE SPATIAL INDEX` grammar parses; R-tree backend in [`phase6_opencypher-geospatial-predicates`](.rulebook/tasks/phase6_opencypher-geospatial-predicates/). |\n| `UNIQUE` constraint | ✅ | Enforced on CREATE / MERGE / SET. |\n| `NODE KEY` (composite uniqueness + implicit NOT NULL) | ✅ | Backed by composite B-tree with `unique` flag. |\n| `NOT NULL` / `EXISTS(n.p)` (nodes + relationships) | ✅ | |\n| Property-type constraint `IS :: INTEGER \\| FLOAT \\| STRING \\| BOOLEAN \\| BYTES \\| LIST \\| MAP` | ✅ | Strict semantics (INTEGER ≠ FLOAT). |\n| Backfill validator for constraints on existing data | ✅ | First 100 offending rows surfaced; atomic abort. |\n| Cypher 25 `FOR (n:L) REQUIRE (…) IS NODE KEY` DDL | ✅ | Parser + planner wired. |\n| Database DDL (`SHOW / CREATE / DROP DATABASE [IF EXISTS]`, `USE`) | ✅ | Multi-database isolation. |\n| `GRAPH[\u003cname\u003e]` preamble | ✅ | Cross-database routing via DatabaseManager. |\n\n### Procedures\n\n| Namespace | Status | Notes |\n|-----------|--------|-------|\n| `db.indexes` / `db.constraints` / `db.labels` / `db.schema.*` | ✅ | System-procedure surface landed v1.x. |\n| `dbms.procedures()` / `dbms.functions()` / `dbms.*` | ✅ | Every registered proc surfaces here, incl. APOC + GDS. |\n| `db.index.fulltext.*` | ✅ | See FTS row above. |\n| `vector.knn(label, vector, k)` + KNN-seeded traversal | ✅ | Bytes-native embeddings on RPC. |\n| `graph.generate` / `graph.analyze` (correlation \u0026 pattern detection) | ✅ | Code-analysis use case. |\n| GDS — PageRank (standard / weighted / parallel), betweenness, eigenvector, Dijkstra, A\\*, Yen's k-paths, Louvain, label propagation, triangle count, clustering coefficients | ✅ | 19 procedures. |\n| `apoc.coll.*` (30 procs: union, intersection, sort, partition, flatten, …) | ✅ | |\n| `apoc.map.*` (20 procs: merge, fromPairs, groupBy, submap, …) | ✅ | |\n| `apoc.text.*` (20 procs: levenshtein, jaroWinkler, regex.*, phonetic, base64, …) | ✅ | |\n| `apoc.date.*` (25 procs: format, parse, convertFormat, diff, toYears, …) | ✅ | |\n| `apoc.schema.*` (10 procs: assert, nodes, relationships, indexExists, …) | ✅ | |\n| `apoc.util.*` / `apoc.convert.*` / `apoc.number.*` / `apoc.agg.*` | ✅ | Delta namespaces landed 2026-04-21. |\n\n### Expressions \u0026 functions\n\n| Group | Status | Notes |\n|-------|--------|-------|\n| Comparison / boolean / unary operators | ✅ | `=`, `!=`, `\u003c`, `\u003c=`, `\u003e`, `\u003e=`, `AND`, `OR`, `NOT`, unary `-`. |\n| `IN` / `IS NULL` / `IS NOT NULL` | ✅ | |\n| String predicates `STARTS WITH` / `ENDS WITH` / `CONTAINS` / regex `=~` | ✅ | |\n| String functions — `toLower`, `toUpper`, `substring`, `trim`, `ltrim`, `rtrim`, `replace`, `split`, `length`, `left`, `right`, `reverse` | ✅ | |\n| Regex helper functions — `regexMatch`, `regexReplace`, `regexReplaceAll`, `regexExtract`, `regexExtractAll`, `regexExtractGroups`, `regexSplit` | ✅ | |\n| Math — `abs`, `ceil`, `floor`, `round`, `sqrt`, `pow`, `sign`, `rand`, trig (`sin`/`cos`/`tan`, `asin`/`acos`/`atan`/`atan2`), `exp`, `log`, `log10`, `radians`, `degrees`, `pi()`, `e()` | ✅ | |\n| Type conversion — `toInteger`, `toFloat`, `toString`, `toBoolean`, `toDate` | ✅ | |\n| Type-check predicates — `isEmpty`, `isString`, `isNumber`, `isInteger`, `isFloat`, `isBoolean`, `isList`, `isMap`, `isNull` | ✅ | Landed in openCypher quickwins. |\n| List functions — `size`, `head`, `tail`, `last`, `range`, `reverse`, `keys`, `nodes`, `relationships`, `length` | ✅ | |\n| Aggregation — `COUNT(*)`, `COUNT(DISTINCT x)`, `SUM`, `AVG`, `MIN`, `MAX`, `COLLECT`, `COLLECT(DISTINCT …)` | ✅ | |\n| Temporal — `date()`, `datetime()`, `time()`, `duration()`, `localdatetime()` | ✅ | |\n| BYTES family — `bytes`, `bytesFromBase64`, `bytesToBase64`, `bytesToHex`, `bytesLength`, `bytesSlice` | ✅ | Wire format `{\"_bytes\": \"\u003cbase64\u003e\"}`; 64 MiB per-property cap. |\n| Typed collections `LIST\u003cINTEGER\\|FLOAT\\|STRING\\|BOOLEAN\\|BYTES\\|ANY\u003e` | ✅ | Parser + constraint-engine validator. |\n| Spatial / geospatial predicates (`distance`, `point()`, polygon containment) | 🧭 | Queued in [`phase6_opencypher-geospatial-predicates`](.rulebook/tasks/phase6_opencypher-geospatial-predicates/). |\n\n### Transactions, admin \u0026 observability\n\n| Feature | Status | Notes |\n|---------|--------|-------|\n| `BEGIN` / `COMMIT` / `ROLLBACK` | ✅ | |\n| Transaction savepoints | ✅ | v1.5. |\n| `EXPLAIN` / `PROFILE` | ✅ | |\n| Query hints — `USING INDEX` / `USING SCAN` / `USING JOIN` | ✅ | |\n| `SHOW QUERIES` / `TERMINATE QUERY '\u003cid\u003e'` | ✅ | |\n| `CREATE USER` / `DROP USER` / RBAC DDL | ✅ | Via auth subsystem + Cypher admin surface. |\n| Replication DDL (`/replication/promote`, `/pause`, `/resume`) | ✅ | HTTP only. |\n| Cluster DDL (`/cluster/add_node`, `/remove_node`, `/rebalance`) | ✅ | Admin-gated. |\n\n## 🛠️ Development\n\n### Project layout\n\n```\nnexus/\n├── crates/                # 🦀 Rust workspace crates (standard layout)\n│   ├── nexus-core/        # 🧠 Graph engine library (catalog, storage, WAL,\n│   │                      #    index, executor, MVCC, sharding, coordinator)\n│   ├── nexus-server/      # 🌐 Axum HTTP + RPC + RESP3 server\n│   ├── nexus-protocol/    # 🔌 Shared wire types (rpc, resp3, mcp, rest, umicp)\n│   └── nexus-cli/         # 💻 `nexus` binary, RPC-default\n├── sdks/                  # 📦 Six first-party SDKs (rust, python, typescript, go, csharp, php)\n├── tests/                 # 🧪 Workspace integration + Neo4j compatibility\n├── docs/                  # 📚 User guides, specs, compatibility, performance\n└── scripts/install/       # 🔧 install.sh / install.ps1\n```\n\n### Build + test\n\n```bash\ncargo +nightly build --release --workspace\ncargo +nightly test --workspace\ncargo +nightly clippy --workspace --all-targets --all-features -- -D warnings\ncargo +nightly fmt --all\n```\n\nCoverage: `cargo llvm-cov --workspace --ignore-filename-regex 'examples'` (95%+ expected for new code).\n\n## 🤝 Contributing\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow. Short version:\n\n1. Fork, branch (`git checkout -b feature/your-feature`).\n2. Make changes + tests (95%+ coverage on new code).\n3. Run `cargo fmt`, `cargo clippy`, `cargo test`.\n4. Conventional commits (`feat(scope): …`, `fix(scope): …`, `refactor(scope): …`).\n5. Submit PR with description, tests, docs.\n\nFor major features, this repo uses [@hivehub/rulebook](https://github.com/hivellm/rulebook) for spec-driven development — proposals + tasks live under [`.rulebook/tasks/`](.rulebook/tasks/).\n\n## 📜 License\n\nApache-2.0. See [`LICENSE`](LICENSE).\n\n## 🙏 Acknowledgments\n\n- [Neo4j](https://neo4j.com/) — inspiration for the record-store layout and Cypher.\n- [HNSW](https://arxiv.org/abs/1603.09320) — the approximate-NN algorithm powering KNN.\n- [OpenCypher](https://opencypher.org/) — language specification.\n- [Rust](https://www.rust-lang.org/) — the ecosystem behind every crate here.\n\n## 📞 Contact\n\n- 🐛 Issues: [github.com/hivellm/nexus/issues](https://github.com/hivellm/nexus/issues)\n- 💬 Discussions: [github.com/hivellm/nexus/discussions](https://github.com/hivellm/nexus/discussions)\n- 📧 Email: team@hivellm.org\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Built with ❤️ in Rust** 🦀\n\n_Neo4j-compatible graph + native vector search, binary-RPC first_\n\n[⭐ Star on GitHub](https://github.com/hivellm/nexus) • [📖 Docs](docs/) • [🚀 Quick Start](#-quick-start)\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhivellm%2Fnexus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhivellm%2Fnexus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhivellm%2Fnexus/lists"}