Nexum Graph

GitHub-native merge gate and semantic control plane for AI-assisted software engineering.

Nexum Graph turns a codebase into a semantic graph, coordinates multiple agents against that graph, validates whether changes respect declared intent, records those changes in an event log, and exposes the system over both CLI and LSP surfaces.

The fastest way to understand the product is simple: install nex, run nex start, and then turn on the GitHub pull-request gate with nex github init. From there, nex github status tells you whether the repo is merely wired up, actually enforcing merge safety, and fully ready for branch protection.

This repository is the full product codebase:

• 8 Rust crates in one workspace
• 15 CLI commands
• Guided first run via nex start
• TypeScript, Python, and Rust semantic extraction
• Semantic diff, coordination, validation, event log, HTTP server, and LSP integration
• 316 source-defined automated tests (271 Rust, 45 Python)
• MIT licensed

⚡ Install in one step

macOS / Linux

curl -fsSL https://raw.githubusercontent.com/NexumCorpus/Nexum-Graph/main/install.sh | sh

Windows PowerShell

irm https://raw.githubusercontent.com/NexumCorpus/Nexum-Graph/main/install.ps1 | iex

Then run:

nex start

That gives you a guided first run with a semantic snapshot, recommended next commands, merge-hook status, and the shortest path to live coordination.

Release assets ship:

• nex and nex-lsp bundled for Linux, macOS, and Windows
• a packaged VS Code extension .vsix
• SHA256SUMS.txt for integrity verification

⚡ What You Get

• 🧠 A semantic map of your codebase instead of a blind pile of files
• 🤝 A coordination layer for multiple agents so they do not silently collide
• ✅ Validation that checks whether a change was actually authorized
• 📜 An event log you can replay, inspect, and roll back
• 🖥️ Editor and server surfaces that make the system usable in real workflows

✨ Why It Feels Different

Most AI coding tools still coordinate at the file or patch level. That breaks down when multiple agents touch the same repo at once.

Nexum Graph coordinates at the semantic unit level instead:

• Functions, methods, classes, traits, and other code units are first-class entities.
• Dependencies between those entities are explicit.
• Agents declare intent before writing.
• Validation checks whether the resulting changes were actually authorized.
• The system leaves behind an auditable trail instead of a pile of opaque patches.

The result is a foundation for multi-agent coding systems that need stronger guarantees than "hope the diffs merge."

In practice, that means a few almost-miraculous benefits:

• 🔍 You can ask "what changed?" and get a semantic answer, not just a textual diff
• 🛑 You can stop two agents from corrupting the same part of the system before it happens
• 🧾 You can prove who intended what, what was allowed, and what actually landed
• 🧯 You can replay or roll back changes with context instead of panic-reverting commits
• 🧭 You can turn a repo into something agents can navigate with rules instead of vibes

🚀 What You Can Do Today

• Start from zero with nex start.
• Get an immediate semantic snapshot of a repo with nex demo.
• Compute semantic diffs between refs with nex diff.
• Detect merge-risk conflicts between branches with nex check.
• Install a local semantic merge gate with nex check --install-hook.
• Generate visual HTML reports for onboarding, repo snapshots, and PR review with nex demo --format html, nex start --format html, and nex check --format html.
• Gate pull requests in GitHub Actions with uses: NexumCorpus/Nexum-Graph@v0.1.0.
• Acquire semantic locks on specific units with nex lock.
• Validate lock coverage before commit with nex validate.
• Run a local coordination server with nex serve.
• Bootstrap secure remote access with nex auth.
• Verify the tamper-evident audit trail with nex audit verify.
• Stream coordination signals into editors through nex-lsp.

🚀 Quickstart

1. Install Nexum Graph

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/NexumCorpus/Nexum-Graph/main/install.sh | sh

Windows PowerShell:

irm https://raw.githubusercontent.com/NexumCorpus/Nexum-Graph/main/install.ps1 | iex

2. Prove the product in one command

nex start

You will immediately see:

• 🌐 languages detected
• 🧩 indexed files, semantic units, and dependency edges
• 🔄 the current HEAD~1 -> HEAD semantic diff
• 🔐 current lock, event-log, and auth state
• 🪜 the next exact commands to run

If you prefer to build from source instead, jump to I want to build everything from source below.

3. Take the next step when you want more

nex diff HEAD~1 HEAD
nex check feature/a feature/b
nex serve --host 127.0.0.1 --port 4000
nex demo --format html > nex-demo-report.html

What those do:

• nex diff shows semantic changes between refs
• nex check shows branch-to-branch merge risk before merge time
• nex serve turns Nexum Graph into a live coordination service

4. Add the editor experience

1. Download nexum-graph-vscode-X.Y.Z.vsix from the latest GitHub Release.
2. In VS Code, open Extensions.
3. Select ....
4. Choose Install from VSIX....
5. Pick the downloaded .vsix.

🧭 Choose Your Path

I just want proof this is real

nex start

I want to inspect a real change

nex diff HEAD~1 HEAD

I want to see merge-risk before merge time

nex check feature/a feature/b
nex check --install-hook

I want to run it as coordination infrastructure

nex auth init --agent alice --agent bob
nex serve --host 127.0.0.1 --port 4000

I want to build everything from source

git clone https://github.com/NexumCorpus/Nexum-Graph.git
cd Nexum-Graph
cargo build --release
npm --prefix extensions/vscode ci
npm --prefix extensions/vscode run package

🛠️ Product Surface

CLI commands

Command	Purpose
nex start	Guided first run with next-step recommendations
nex demo	One-command semantic snapshot of the current repository
nex diff	Semantic diff between two git refs
nex check	Conflict detection between two branches
nex lock	Acquire a semantic lock
nex unlock	Release a semantic lock
nex locks	List active locks
nex validate	Validate lock coverage against a base ref
nex log	Show semantic event history
nex rollback	Generate a rollback event
nex replay	Replay semantic state to an event boundary
nex auth	Bootstrap and manage server auth
nex audit verify	Verify the tamper-evident audit trail
nex serve	Start the coordination server

LSP surface

The nex-lsp binary provides editor integration with:

• nex/semanticDiff
• nex/activeLocks
• nex/agentIntent
• nex/validationStatus
• nex/eventStream

It also proxies standard LSP requests to an upstream server and merges Nexum Graph overlays into the editor experience.

VS Code extension

The repo now includes a release-packaged VS Code extension plus the source under extensions/vscode. It:

• auto-starts nex-lsp for TypeScript, Python, and Rust workspaces
• supports per-language upstream server configuration
• falls back to overlay-only mode when an upstream command is not installed
• exposes a Nexum Graph: Show Semantic Diff for Current File command

🧭 Developer Review Map

If you are reviewing the codebase rather than just using the product, start here:

File	Why it matters
CORE_INVARIANTS.md	Frozen behavioral contracts for semantic identity, graph diffing, coordination, and persistence
crates/nex-core/src/semantic.rs	Shared semantic contracts used everywhere else; changes here ripple across the whole product
crates/nex-parse/src/lib.rs	Extractor registry and shared semantic-id formula
crates/nex-graph/src/lib.rs	CodeGraph construction and the diff algorithm
crates/nex-coord/src/coordinator.rs	Low-level lock engine and transitive conflict rules
crates/nex-coord/src/service.rs	Protocol-facing coordination service, TTL handling, and CRDT-backed reconciliation
crates/nex-cli/src/coordination_pipeline.rs	Repo-local lock persistence, graph loading, and validation lock remapping
crates/nex-cli/src/output.rs	All public text, JSON, GitHub, and HTML report rendering
tools/project_facts.py	Canonical generated repo facts used to keep README stats and public copy from drifting
action.yml	Public GitHub Action entrypoint for semantic PR checks
FUZZING.md	How the parse/build/diff fuzz surface is intended to be exercised

Recommended reading order for a new developer:

1. CORE_INVARIANTS.md
2. crates/nex-core/src/semantic.rs
3. crates/nex-graph/src/lib.rs
4. crates/nex-coord/src/coordinator.rs
5. crates/nex-coord/src/service.rs
6. crates/nex-cli/src/coordination_pipeline.rs

If you are only validating the current release surface, focus on:

• README.md
• NEWS.md
• tools/project_facts.py
• action.yml
• .github/workflows/semantic-check.yml
• extensions/vscode

🏗️ Architecture

Nexum Graph is built as a five-layer chassis:

1. Semantic Code Graph Parses source into semantic units and dependency edges.
2. Intent Coordination Declares intent, grants locks, detects conflicts, and converges distributed state with CRDTs.
3. Continuous Validation Checks whether modifications and deletions are covered by locks and flags broken references.
4. Immutable Event Log Records semantic mutations for replay and rollback.
5. IDE and Server Integration Exposes the system through CLI, HTTP, WebSocket, and LSP surfaces.

Workspace map

Crate	Purpose
nex-core	Shared contracts, types, errors, persistence helpers
nex-parse	Tree-sitter extraction and language-specific semantic extractors
nex-graph	Semantic graph construction and graph diffing
nex-coord	Coordination engine, conflict detection, service layer, CRDT state
nex-validate	Lock coverage and semantic validation rules
nex-eventlog	Event storage, replay, rollback, backend abstraction
nex-lsp	Editor integration and upstream LSP proxy
nex-cli	CLI, server, auth, audit, and operator workflows

🌍 Supported Languages

Language	Current extractor coverage
TypeScript / TSX	Functions, classes, methods, interfaces, enums, type aliases
Python	Functions, classes, methods, decorators, async variants
Rust	Functions, structs, enums, traits, impl methods, inline modules

The extractor trait is intentionally extensible, so more languages can be added without changing the rest of the chassis.

🔄 Core Workflows

Semantic diff

nex diff main feature/refactor --format text
nex diff v0.1.0 HEAD --format json

Conflict detection

nex check feature/a feature/b
nex check --install-hook
nex check feature/a feature/b --format html > nex-check-report.html

nex check --install-hook installs a pre-merge-commit git hook for the current repo. On local merges, Git will run nex check HEAD MERGE_HEAD before the merge commit is created.

GitHub pull request gate

Fast local path:

nex github init --gate-mode errors-only
nex github status
nex github status --require-current
nex github status --require-current --min-gate-mode errors-only
nex github status --require-current --min-gate-mode errors-only --require-pr-comment --require-sarif

That writes .github/workflows/nexum-graph-semantic-check.yml into the current repo and points it at the reusable workflow published from Nexum Graph. nex github status tells you whether that workflow is missing, custom, managed, or pinned to an older Nexum Graph release. Add --require-current when you want CI or local checks to fail on stale workflow pins, --min-gate-mode errors-only when you want to reject advisory-only rollout posture, and --require-pr-comment --require-sarif when you want to enforce the full review surface as well.

If you prefer to wire it manually, the reusable workflow looks like this:

Fastest path: use the reusable workflow.

name: Semantic Check

on:
  pull_request:

jobs:
  semantic-check:
    uses: NexumCorpus/Nexum-Graph/.github/workflows/reusable-semantic-check.yml@v0.1.0
    with:
      format: github
      gate-mode: errors-only
      post-pr-comment: true
      upload-sarif: true

The reusable workflow checks out the target repo, runs the Nexum Graph action, uploads HTML/SARIF/insights artifacts, optionally uploads SARIF into GitHub code scanning, and keeps a sticky PR comment in sync.

For advanced/custom workflows, you can still use the composite action directly:

- id: semantic
  uses: NexumCorpus/Nexum-Graph@v0.1.0
  with:
    format: github
    gate-mode: errors-only

The action exports structured outputs for downstream workflows: risk-score, risk-label, blocking-conflicts, warning-conflicts, gate-status, gate-exit-code, insights-path, and sarif-report-path.

gate-mode controls rollout posture:

• strict: block on errors and warnings
• errors-only: block on errors, keep warnings advisory
• advisory: never fail the action for semantic conflicts

If you upload the generated SARIF file, GitHub code scanning can surface semantic merge conflicts as native review findings instead of only as a PR comment or artifact.

For exact rollout recipes, see docs/github-rollout.md.

Locking and validation

nex lock alice validate write
nex validate alice --base HEAD~1
nex unlock alice validate

Secure server bootstrap

nex auth init --agent alice --agent bob
nex serve --host 0.0.0.0 --port 4000
nex audit verify

One-command repo demo

nex demo
nex demo --base origin/main --head HEAD
nex demo --format html > nex-demo-report.html

Guided first run

nex start
nex start --base origin/main --head HEAD
nex start --format html > nex-start-report.html

nex start is the hand-hold path for new users. It shows the current repo snapshot, tells you whether the semantic merge hook is installed, tells you whether auth is configured, and prints the next exact commands to run.

🔐 Security and Operations

Nexum Graph now includes operator-oriented hardening out of the box:

• Remote binds are rejected unless auth is configured or explicitly bypassed.
• Repo-local auth config stores BLAKE3 token hashes at rest, not raw bearer secrets.
• Raw auth tokens are only shown once at issue time.
• Server audit records are hash chained and anchored by .nex/server-audit.head.json.
• nex audit verify detects record edits, missing anchors, and tail truncation.
• Existing plaintext auth configs are still readable for migration compatibility.

State lives under .nex/:

File	Purpose
coordination.loro	CRDT coordination state
locks.json	Compatibility snapshot of active locks
events.json	Local event log when using the file backend
server-auth.json	Reloadable auth config with token hashes at rest
server-audit.jsonl	Hash-chained server audit trail
server-audit.head.json	Audit head anchor for integrity verification
cache/	Local tool caches

For repo security policy and reporting guidance, see SECURITY.md.

🧪 Developer Workflow

The repo includes a small toolchain for spec-driven, slice-based development:

• tools/release_tools.py Validates version parity, packages release bundles, and writes checksum manifests.
• tools/spec_query.py Searches the Markdown implementation spec and whitepapers, with .docx fallback for archival sources.
• tools/export_spec_markdown.py Regenerates the public Markdown spec docs from the archival Word sources in the repo root.
• tools/github_release_watch.py Checks the public GitHub repo state and watches tagged release workflows until assets are actually published.
• tools/verify_slice.py Runs tests, Clippy, and format checks only for changed crates and downstream dependents.
• tools/workspace_doctor.py Checks repo health, tool availability, and skill sync state.
• tools/sync_nex_skills.py Installs repo-managed Codex skills into $CODEX_HOME.
• tools/tool_selftest.py Runs the Python tool regression suite and skill checks.

Typical workflow:

python tools/release_tools.py assert-version-parity --tag v0.1.0
python tools/verify_slice.py --changed
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --check
npm --prefix extensions/vscode test

If you plan to contribute, start with CONTRIBUTING.md.

📚 Architecture Docs

The readable architecture docs live in:

• docs/Nexum_Graph_Final_Implementation_Spec.md
• docs/Nexum_Graph_Whitepaper_v3.md

The .docx files in the repo root remain as archival source documents. If you need to refresh the Markdown exports after an edit to those source files, run:

python tools/export_spec_markdown.py

If you plan to cut releases, use RELEASING.md. If you want the public-facing update log, use NEWS.md.

For contract-heavy review work, also use:

• CORE_INVARIANTS.md for the non-negotiable semantics
• FUZZING.md for parse/build/diff stress guidance
• tools/project_facts.py for the generated README facts block

📈 Project Status

Implemented and usable today:

• Semantic extraction for TypeScript, Python, and Rust
• Graph-based diffing
• Coordination engine and CRDT-backed lock state
• Validation engine
• Event log with replay and rollback
• Local coordination server
• Auth bootstrap, rotation, revocation, and audit verification
• LSP shim with upstream proxy support

Active expansion areas:

• More language extractors
• Stronger remote trust anchoring for audit provenance
• Broader editor packaging and distribution
• Distributed backend and deployment ergonomics

🧠 Philosophy

Nexum Graph is opinionated:

• Semantic units matter more than raw files.
• Deterministic contracts matter more than agent improvisation.
• Compiler and validator feedback should be part of the agent loop.
• Operational safety has to be part of the product, not an afterthought.

This repo is also a live example of spec-driven multi-agent Rust development. The codebase itself is part of the thesis.

Contributing

Please read CONTRIBUTING.md before opening a pull request.

License

This project is licensed under the MIT License. See LICENSE.