CAVDAX
README.md
<div align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="assets/cavdax-logo-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="assets/cavdax-logo-light.svg">
<img src="assets/cavdax-logo-dark.svg" width="100" height="100" alt="CAVDAX Logo" />
</picture>
<h1>CAVDAX: Contextual Action & Verified Decision Autonomous eXecution</h1>
<p><strong>Graph-Grounded Decision Execution for Coding Agents</strong></p>
<p><em>Track 01: Agents That Act on Connected Data (Primary) • Track 02: Knowledge Graphs & Long-Term Memory (Eligible)</em><br />
Built for the <strong>WeMakeDevs × FalkorDB Graph Hacks Hackathon (October 2026)</strong></p>
</div>
[](https://github.com/suneetchugh-dev/CAVDAX/actions)
[](https://cavdax.sahnirmaan.live/)
[](https://falkordb.com/)
[-06B6D4?style=for-the-badge)](https://modelcontextprotocol.io/)
[](./docker-compose.yml)
[](./LICENSE)
[](#empirical-benchmarks)
---
## ā” The Fundamental Flaw of Modern Coding Agents
Modern autonomous coding agents (Claude Code, Cursor Composer, Windsurf, GitHub Copilot) rely on **Vector RAG (retrieval-augmented generation)** or lexical search to fetch repository context before modifying code.
### Why Vector RAG Fails in Production Repositories:
1. **Cosine Similarity Ignores Causal Directionality:** A superseded architecture decision (`ADR-001: Adopt TokenAuth v1`) and its superseding decision (`ADR-002: TokenAuth Deprecated; Enforce OAuth2`) share identical semantic vectors (`"payment", "auth", "checkout"`). Vector RAG often retrieves the older, higher-frequency document.
2. **Zero Invalidation Guarantees:** When an engineer commits a change to a config file (`CODEOWNERS`, `package.json`, or an ADR), vector embeddings remain static unless costly re-indexing is triggered.
3. **Unprotected Execution Paths:** Coding agents execute code modifications directly through standard file-system APIs without validating whether the decision justifying the change is still causally valid.
---
## š”ļø The CAVDAX Solution: Graph-Grounded Enclosed Execution
**CAVDAX** converts repository artifacts into an active, temporal causal Directed Acyclic Graph (DAG) stored inside **FalkorDB**:
```
[Source: ADR / Commit] āā(:EXTRACTED_FROM)āā> [Fact: Verified Claim] āā(:DEPENDS_ON)āā> [Decision] āā(:GROUNDED_IN)āā> [AgentAction]
```
When a superseding commit or ADR arrives:
1. **Deterministic Ingestion:** Real YAML frontmatter (`supersedes: ADR-001`) is parsed instantly without probabilistic LLM hops.
2. **Cascading Invalidation Wave:** FalkorDB establishes a `[:SUPERSEDES]` relationship and cascades status flags across the DAG in **< 4ms** via GraphBLAS sparse matrix operations.
3. **Enclosed MCP Execution Gate:** The agent's file modification tool (`apply_code_change`) is enclosed inside an internal Cypher gate. If any ancestor source or fact has been superseded, the gate **hard-rejects** execution (`BLOCKED_SUPERSEDED_SOURCE`). Zero invalid bytes are written.
4. **Act IV Revalidation Loop:** The agent is guided to create a fresh decision grounded in the active source, enabling safe, verified execution.
---
## š§¬ Graph Data Model & Causal Ontology
CAVDAX models engineering knowledge and agent actions using a formal 4-tier Causal Directed Acyclic Graph (DAG) optimized for sub-millisecond GraphBLAS traversal in FalkorDB:
```
(ADR-002:Source {status: 'ACTIVE'})
ā
[:EXTRACTED_FROM]
ā¼
(F-OAuth2-v2:Fact {claim: 'OAuth2 Enforced', is_stale: false})
ā²
[:DEPENDS_ON]
ā
(DEC-103:Decision {status: 'VALID'}) āā[:REPLACES]āā> (DEC-102:Decision {status: 'INVALIDATED'})
ā² ā
[:GROUNDED_IN] [:DEPENDS_ON]
ā ā¼
(:AgentAction {tool: 'apply_code_change', verdict: 'APPROVED'}) (F-Auth-v1:Fact {is_stale: true})
ā
[:EXTRACTED_FROM]
ā¼
(ADR-002:Source) āāāāāāāāāāāāāāā[:SUPERSEDES]āāāāāāāāāāāāāāā> (ADR-001:Source {status: 'SUPERSEDED'})
```
### 1. Node Schemas & Labels
* **`(:Source)` ā Authoritative Engineering Artifacts:**
* `id` *(String, Primary Key)*: Unique identifier (e.g., `'ADR-001'`, `'commit-9f8a2b'`).
* `title` *(String)*: Human-readable title of the document or change.
* `type` *(String)*: Polymorphic artifact type (`'ADR'`, `'COMMIT'`, `'CODEOWNERS'`, `'PACKAGE_JSON'`).
* `status` *(String)*: `'ACTIVE'` or `'SUPERSEDED'`.
* `superseded_at` *(Integer, Optional)*: Unix millisecond epoch timestamp when superseded.
* **`(:Fact)` ā Atomic Invariant Claims:**
* `id` *(String, Primary Key)*: Unique claim ID (e.g., `'F-Auth-v1'`, `'F-OAuth2-v2'`).
* `claim` *(String)*: Normalized atomic statement (e.g., `'TokenAuth v1 active'`, `'OAuth2 enforced'`).
* `is_stale` *(Boolean)*: `false` when active; flipped to `true` when parent source is superseded.
* `invalidated_at` *(Integer, Optional)*: Unix timestamp when marked stale.
* **`(:Decision)` ā Architecture & Implementation Directives:**
* `id` *(String, Primary Key)*: Directive identifier (e.g., `'DEC-102'`, `'DEC-103'`).
* `title` *(String)*: Directive summary (e.g., `'Implement TokenAuth v1 for checkout'`).
* `status` *(String)*: `'VALID'`, `'INVALIDATED_NEEDS_REVALIDATION'`, or `'REPLACED_ARCHIVED'`.
* `created_at` *(Integer)*: Creation epoch timestamp.
* **`(:AgentAction)` ā Verified Tool Execution Audit Log:**
* `id` *(String, Primary Key)*: Unique audit event hash.
* `tool` *(String)*: Invoked MCP tool name (`'apply_code_change'`).
* `target_file` *(String)*: Protected file path (`'src/services/payment.js'`).
* `verdict` *(String)*: `'APPROVED'` or `'BLOCKED'`.
* `timestamp` *(Integer)*: Execution epoch timestamp.
### 2. Relationship Types & Causal Semantics
* **`(:Source)-[:SUPERSEDES]->(:Source)`**: Directed temporal invalidation edge between a newer artifact and an obsolete artifact.
* **`(:Fact)-[:EXTRACTED_FROM]->(:Source)`**: Provenance grounding attributing an atomic proposition to its authoritative origin.
* **`(:Decision)-[:DEPENDS_ON]->(:Fact)`**: Directional dependency indicating that a decision's validity is conditional on the fact remaining fresh (`*1..4` hops).
* **`(:Decision)-[:REPLACES]->(:Decision)`**: Evolutionary replacement edge linking a newly synthesized Act IV decision to an archived predecessor.
* **`(:AgentAction)-[:GROUNDED_IN]->(:Decision)`**: Mandatory audit link created only upon verified gate approval.
---
## š System Architecture & Flowchart Diagrams
### 1. End-to-End System Architecture Flowchart
### 2. Multi-Layer Architecture & FalkorDB GraphBLAS Engine Flowchart
### 3. Enclosed MCP Protocol Execution Gate Flowchart
---
## š¬ Core Cypher Queries (FalkorDB GraphBLAS)
CAVDAX leverages FalkorDB's linear-algebraic matrix engine to run deep multi-hop traversals in sub-millisecond timeframes.
### Query 1: Enclosed Action Gate Verification (`verifyActionGate`)
Evaluates the full causal dependency tree and uses `ANY(...)` aggregation to prevent mixed-path false positives:
```cypher
MATCH (d:Decision {id: $decisionId})
WITH d, d.status AS decision_status
OPTIONAL MATCH path = (d)-[:DEPENDS_ON*1..4]->(f:Fact)-[:EXTRACTED_FROM]->(s:Source)
WITH d, decision_status,
collect({
path_nodes: [n IN nodes(path) | labels(n)[0] + ':' + coalesce(n.id, n.ref)],
fact_stale: coalesce(f.is_stale, false),
source_status: coalesce(s.status, 'ACTIVE')
}) AS dependencies
RETURN d.id AS decision_id,
decision_status,
CASE
WHEN decision_status = 'INVALIDATED_NEEDS_REVALIDATION' THEN 'BLOCKED_DECISION_INVALIDATED'
WHEN size(dependencies) = 0 THEN 'BLOCKED_NO_GROUNDING'
WHEN ANY(dep IN dependencies WHERE dep.fact_stale = true) THEN 'BLOCKED_STALE_FACT'
WHEN ANY(dep IN dependencies WHERE dep.source_status = 'SUPERSEDED') THEN 'BLOCKED_SUPERSEDED_SOURCE'
ELSE 'APPROVED'
END AS gate_verdict,
[dep IN dependencies WHERE dep.fact_stale = true OR dep.source_status = 'SUPERSEDED' | dep.path_nodes] AS violation_paths
```
### Query 2: Cascading Invalidation Wave (`cascadeInvalidation`)
Propagates invalidation from a newly ingested source down to all affected decisions in $< 3\text{ ms}$:
```cypher
MATCH (newSource:Source {id: $newSourceId})
MATCH (oldSource:Source {id: $oldSourceId})
MERGE (newSource)-[:SUPERSEDES]->(oldSource)
SET oldSource.status = 'SUPERSEDED',
oldSource.superseded_at = timestamp()
WITH oldSource
MATCH (oldSource)<-[:EXTRACTED_FROM]-(staleFact:Fact)
SET staleFact.is_stale = true,
staleFact.invalidated_at = timestamp()
WITH staleFact
MATCH (d:Decision)-[:DEPENDS_ON*1..4]->(staleFact)
SET d.status = 'INVALIDATED_NEEDS_REVALIDATION',
d.invalidated_at = timestamp()
RETURN count(DISTINCT d) AS affected_decisions,
collect(DISTINCT d.id) AS invalidated_decision_ids
```
### Query 3: Act IV Revalidation Loop (`revalidateDecision`)
Closes the loop by safely retiring the invalidated decision and grounding the fresh decision:
```cypher
MATCH (newSource:Source {id: $newSourceId})<-[:EXTRACTED_FROM]-(newFact:Fact {id: $newFactId})
MATCH (oldDecision:Decision {id: $oldDecisionId})
CREATE (newDecision:Decision {
id: $newDecisionId,
title: $title,
status: 'VALID',
created_at: timestamp()
})
CREATE (newDecision)-[:DEPENDS_ON]->(newFact)
CREATE (newDecision)-[:REPLACES]->(oldDecision)
SET oldDecision.status = 'REPLACED_ARCHIVED'
RETURN newDecision.id AS active_decision_id, oldDecision.id AS archived_decision_id
```
---
## š Empirical Benchmarks
### 1. Vector RAG vs. CAVDAX (10 Engineering Scenarios)
Evaluated via `node benchmark/evaluate.js`:
| Scenario ID | Category | Vector RAG Baseline | CAVDAX FalkorDB Gate | Latency |
|---|---|---|---|---|
| **SCEN-01** | Authentication Migration | ā Stale TokenAuth v1 written | š”ļø **BLOCKED_SUPERSEDED_SOURCE** | `1.84ms` |
| **SCEN-02** | API Routing Breaking Change | ā Deprecated /v1 route built | š”ļø **BLOCKED_SUPERSEDED_SOURCE** | `1.42ms` |
| **SCEN-03** | Crypto CVE Deprecation | ā Vulnerable crypto-js imported | š”ļø **BLOCKED_STALE_FACT** | `1.95ms` |
| **SCEN-04** | CODEOWNERS Governance Shift | ā Stale reviewer assigned | š”ļø **BLOCKED_SUPERSEDED_SOURCE** | `1.15ms` |
| **SCEN-05** | Docker Base Image Bump | ā Outdated node:18 base written | š”ļø **BLOCKED_STALE_FACT** | `1.72ms` |
| **SCEN-06** | NoSQL to SQL Migration | ā Mongoose schema created | š”ļø **BLOCKED_SUPERSEDED_SOURCE** | `2.31ms` |
| **SCEN-07** | Secret Vault Transition | ā Plaintext env var leaked | š”ļø **BLOCKED_DECISION_INVALIDATED** | `1.68ms` |
| **SCEN-08** | Feature Flag Deprecation | ā Dead flag conditional reintroduced | š”ļø **BLOCKED_SUPERSEDED_SOURCE** | `1.34ms` |
| **SCEN-09** | Rate-Limit Threshold Lowering | ā Flood test tripped alarms | š”ļø **BLOCKED_STALE_FACT** | `1.55ms` |
| **SCEN-10** | OSS License Compliance | ā Incompatible license header added | š”ļø **BLOCKED_SUPERSEDED_SOURCE** | `1.49ms` |
* **Vector RAG Failure Rate:** **100% (10/10 silent hallucinations)**
* **CAVDAX Gate Protection Rate:** **100% (10/10 deterministic blocks)**
* **Average Gate Latency:** **1.65ms**
### 2. Large-Scale Enterprise DAG Performance
Evaluated via `node benchmark/scale_generator.js`:
| Total Nodes | Total Edges | Graph Depth | Gate Query 1 Latency | Cascade Query 2 Latency | GraphBLAS Memory |
|---|---|---|---|---|---|
| **3,300** | 3,270 | 4 hops | **2.16 ms** | **3.32 ms** | 6.9 MB |
| **9,900** | 9,810 | 4 hops | **2.04 ms** | **3.42 ms** | 12.3 MB |
| **25,150** | 24,940 | 4 hops | **2.53 ms** | **3.47 ms** | 24.8 MB |
| **50,550** | 50,100 | 4 hops | **2.30 ms** | **3.81 ms** | 45.7 MB |
---
## š¬ Live Demo: The 4-Act Storyline
The Web HUD features an interactive 4-Act stepper designed for video demonstration:
* **Act I: Baseline (ADR-001 Active):** `DEC-102` is valid and authorized to scaffold checkout using `TokenAuth v1`.
* **Act II: Commit Mutation (ADR-002 Ingested):** Security board commits `ADR-002` superseding `ADR-001`. Query 2 executes in 2.1ms, turning `ADR-001` red (`SUPERSEDED`), `F-Auth-v1` red (`STALE`), and `DEC-102` red (`INVALIDATED_NEEDS_REVALIDATION`).
* **Act III: Enclosed MCP Gate Rejection:** The coding agent attempts to write `TokenAuth.v1` into `demo-repo/src/services/payment.js`. The enclosed MCP tool executes Query 1, detects the broken causal link, and emits `[ ā 403 MCP GATE BLOCKED: BLOCKED_SUPERSEDED_SOURCE ]`. The file remains 100% untouched on disk!
* **Act IV: Revalidation & Safe Execution:** The agent synthesizes `DEC-103` (OAuth2 JWT/RS256) grounded in `ADR-002`. The gate verifies the fresh causal path in 1.62ms and emits `[ ā
200 MCP GATE APPROVED ]`. The verified OAuth2 code is safely written to disk.
---
## š Live Production Deployment
CAVDAX is deployed and running live in production:
š **[https://cavdax.sahnirmaan.live/](https://cavdax.sahnirmaan.live/)**
### Production Architecture & Cloud Infrastructure:
* **Edge Reverse Proxy & Automated SSL:** Caddy 2 reverse proxy with dynamic TLS/SSL certificates terminates production traffic over port 443 with HSTS and security headers.
* **Low-Latency Streaming:** Dedicated `/api/events` Server-Sent Events (SSE) pipeline with reverse-proxy buffering disabled (`proxy_buffering off`) for instant UI graph invalidation pulses.
* **Remote Model Context Protocol (MCP) Endpoint:** Accessible at `https://cavdax.sahnirmaan.live/api/mcp/sse` for remote coding agents, IDEs, and CI/CD pipelines.
* **GraphBLAS Backend Mesh:** Low-overhead Docker Compose mesh linking the Node.js Express gateway and FalkorDB GraphBLAS on an isolated internal network.
---
## š„ļø Interactive Web HUD & Verification Suite
The CAVDAX Web HUD provides a world-class, industrial-brutalist / porcelain-dark operational interface:
1. **Interactive Causal Verification Console (`McpActionPlayground`):**
* Pre-flight causal verification simulator for engineers and evaluators.
* Dynamic sliders for adjusting graph traversal depth (`1..4` hops) and threshold constraints.
* Real-time Cypher query generator and execution engine displaying sub-millisecond execution times.
* Multi-scenario testing: evaluate ADR migrations, CVE deprecations, and CODEOWNERS governance shifts on the fly.
2. **Interactive Guided Tour Engine (`TourGuide`):**
* Multi-step contextual onboarding walkthrough.
* Features dynamic viewport collision avoidance ensuring tour cards never obstruct active graph vertices or terminal logs.
3. **FalkorDB Temporal Causal Graph Canvas (`GraphCanvas`):**
* Cytoscape.js-powered Directed Acyclic Graph (DAG) with real-time status pulses (`ACTIVE`, `SUPERSEDED`, `INVALIDATED_NEEDS_REVALIDATION`, `REPLACED_ARCHIVED`).
* **Fullscreen Mode:** Full-viewport interactive graph inspection with responsive pan/zoom, live node type filters (Sources, Facts, Decisions), and dual-boundary scroll isolation.
4. **Accessible System Preferences & Keyboard Hotkeys (`PreferencesModal`):**
* Comprehensive shortcut engine (press `?` anywhere to reveal).
* Contextual, theme-aware custom tooltips with keyboard badge accessibility.
* High-contrast mode, reduced motion compliance, and cybernetic audio feedback toggles.
---
## š Quickstart Guide
### Option 1: Docker Compose (Recommended)
Launch the entire mesh (FalkorDB + Server + Web HUD) with one command:
```bash
docker-compose up --build
```
- **Porcelain Dark Web HUD:** `http://localhost:5173`
- **CAVDAX Backend Gateway & MCP:** `http://localhost:3001` (internal container port 3000)
- **FalkorDB Redis Endpoint:** `localhost:6379`
### Option 2: Local Development
```bash
# 1. Install dependencies
cd apps/server && npm install
cd ../client && npm install
cd ../..
# 2. Run benchmark tests
npm run benchmark
npm run benchmark:scale
# 3. Start server and client
npm run server
npm run client
```
---
## š Model Context Protocol (MCP) Integration & Client Setup
CAVDAX implements the Anthropic Model Context Protocol (MCP) specification `2024-11-05` to enclose autonomous coding agents (Claude Code, Cursor IDE, Claude Desktop, Windsurf/Roo Code) behind a FalkorDB GraphBLAS causal barrier.
š **Comprehensive Technical Guide**: [docs/MCP_SPECIFICATION.md](docs/MCP_SPECIFICATION.md)
### Supported Transports & Connectors
- **Local Stdio (`stdio`):** `npx -y @cavdax/mcp-server` (zero-latency, runs the MCP gate locally against your own FalkorDB instance).
- **Remote Cloud SSE (`SSE`):** Connect to `https://cavdax.sahnirmaan.live/api/mcp/sse` (for centralized team graphs and remote CI/CD pipelines).
### Client Configuration Snippets
#### 1. Cursor IDE (`.cursor/mcp.json`)
```json
{
"mcpServers": {
"cavdax": {
"url": "https://cavdax.sahnirmaan.live/api/mcp/sse"
}
}
}
```
#### 2. Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"cavdax": {
"url": "https://cavdax.sahnirmaan.live/api/mcp/sse"
}
}
}
```
#### 3. Claude Code CLI
```bash
claude mcp add cavdax https://cavdax.sahnirmaan.live/api/mcp/sse
```
#### 4. Windsurf / Roo Code (`mcp_config.json`)
```json
{
"mcpServers": {
"cavdax": {
"command": "npx",
"args": ["-y", "@cavdax/mcp-server"]
}
}
}
```
### Enclosed MCP Tools Registered:
1. `apply_code_change`: Intercepts in-flight code changes and validates decision provenance against FalkorDB.
2. `query_causal_graph`: Sub-millisecond GraphBLAS BFS Cypher query for active ADRs and invalidation trails.
3. `verify_decision`: Pre-flight dry-run check before code synthesis.
---
## š Repository Structure
```
CAVDAX/
āāā apps/
ā āāā client/ # React 18 + Vite + Tailwind Porcelain Dark Web HUD
ā ā āāā src/components/ # AuditPage, DevConsolePage, McpActionPlayground, GraphCanvas, etc.
ā ā āāā Dockerfile # Client containerization
ā āāā server/ # Node.js + Express Backend Gateway
ā ā āāā index.js # REST API, SSE broadcaster, MCP SSE transport, ingest-source, dev/tier-check
ā ā āāā Dockerfile # Server containerization
ā āāā mcp-server/ # Standalone NPM package (@cavdax/mcp-server ā published)
ā āāā bin/cavdax.js # Universal CLI: npx cavdax mcp|ingest|check|doctor
ā āāā src/ # stdioServer, ingestCommand, checkCommand, doctorCommand
āāā assets/ # Monochromatic Mermaid-style architecture flowcharts (.svg)
āāā benchmark/ # Evaluation harness & empirical scale tests
ā āāā evaluate.js # 10-Scenario Vector RAG vs CAVDAX benchmark
ā āāā scale_generator.js # 50,000-node GraphBLAS stress test
ā āāā results.json # Benchmark metrics data
ā āāā EVALUATION_REPORT.md # Detailed evaluation markdown report
āāā core/ # Core Engine Modules
ā āāā graph/ # FalkorDB client manager & optimized Cypher queries
ā āāā ingestion/ # parser.js (ADR YAML) + sources.js (commit/package/codeowners/issue)
ā āāā mcp/ # Enclosed MCP server & apply_code_change tool
āāā demo-repo/ # Target repository subject to agent mutations
ā āāā docs/adrs/ # ADR-001 (stale), ADR-002 (superseding), ADR-003 (multi-supersedes), TEMPLATE.md
ā āāā .github/CODEOWNERS # Governance source generalization
ā āāā src/services/ # payment.js target service
āāā docs/ # Complete technical specifications & guides
ā āāā FUTURE_ROADMAP.md # Tiered distribution plan & long-term source ingestion roadmap
āāā .env.example # Environment variable reference (copy to .env ā never commit .env)
āāā action.yml # Reusable composite GitHub Action (CAVDAX causal invalidation gate)
āāā .github/workflows/ # CI pipeline + cavdax-gate.yml (PR blocking workflow)
āāā docker-compose.yml # Multi-container orchestration (FalkorDB, server, client)
āāā LICENSE # GNU General Public License v3.0
āāā package.json # Monorepo root scripts
```
---
## š„ Team & Attribution
Built with passion for the **WeMakeDevs × FalkorDB Graph Hacks Hackathon**:
* **Suneet Chugh** (`@suneetchugh-dev`) ā Frontend Web HUD Architecture, DevOps & Docker Orchestration, Video Presentation.
* **Geetika Chugh** ā Domain Logic, 10-Scenario Evaluation Dataset, Documentation & Project Blog Author.
---
*License: GNU GPL 3.0 • Powered by FalkorDB GraphBLAS & Model Context Protocol (MCP)*
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues