Deterministic AST Safety Guard, Polyglot Semantic Symbol Graph, Surgical Byte-Span Patching, and Zero-Dependency Model Context Protocol (MCP) Server in Pure Rust.
Modern AI code generation agents (Claude Code, Cursor, Copilot, Devin) and automated developer pipelines face two systemic engineering bottlenecks:
Probabilistic Syntax & Concurrency Regressions: AI agents frequently hallucinate unclosed delimiters, panic-inducing.unwrap()
traps, async-mutex thread deadlocks, catastrophic polynomial regular expressions (ReDoS), and unbounded array indexing.Context Window Inflation: Repeatedly feeding entire source code files into LLM context windows wastes up to80% of token budgets on repetitive function bodies rather than high-level interface contracts.
** locus-engine** solves both challenges as a
standalone, zero-bloat, high-performance systems engine written in 100% safe Rust. It enforces deterministic, non-negotiable safety invariants in
microsecond time (, extracts cross-file symbol graphs with minimal context footprints, and communicates natively with modern AI IDEs via the
9.04 µs
)Model Context Protocol (MCP).
$ locus check src/async_task.rs
+-------------------------------------------------------------+
| LOCUS AST GUARD VERIFICATION |
+-------------------------------------------------------------+
Target File: src/async_task.rs
Verified Latency: 0.0194 ms
Status: [FAIL] Invariant Violation Detected
Violation Kind: ASYNC_MUTEX_DEADLOCK
Violation Detail: std::sync::Mutex used in async context with .await — use tokio::sync::Mutex instead.
+-------------------------------------------------------------+
$ locus graph src/
+-------------------------------------------------------------+
| LOCUS SYMBOL GRAPH INDEX |
+-------------------------------------------------------------+
Indexed Root: src/
Total Indexed Files: 8
Extracted AST Symbols: 28
Token Savings via AST Skeleton: 74.8%
Indexing Latency: 4.82 ms
+-------------------------------------------------------------+
Benchmarked under optimized release profile (opt-level = 3
, lto = thin
, codegen-units = 1
):
| Subsystem / Operation | Benchmark Cycles | Total Elapsed | Average Latency | Status |
|---|---|---|---|---|
| 🛡️ AstGuard 6-Pass Verification | ||||
| 1,000 iterations | 9.036 ms |
|||
(0.009 ms / check)9.04 µs |
||||
| 100% PASS | ||||
| ⚡ AstContextCache (FIPS 180-4 SHA-256) | ||||
| 1,000 inserts/lookups | 18.675 ms |
|||
/ digest + LRU18.68 µs |
||||
| 100% PASS | ||||
| 🔌 MCP Stdio JSON-RPC Dispatch | ||||
| 1,000 round-trips | 42.316 ms |
|||
/ dispatch42.32 µs |
||||
| 100% PASS | ||||
| ✂️ AstDiffEngine (Patch & Skeleton) | ||||
| 500 cycles | 28.063 ms |
|||
/ operation56.13 µs |
||||
| 100% PASS | ||||
| 🧠 SymbolGraph Polyglot Indexer | ||||
| 600 files (1,600 symbols) | 16.294 ms |
|||
/ file27.15 µs |
||||
| 100% PASS |
| Capability | locus-engine |
Traditional Linters (ESLint, Clippy) | Cloud AI Guardrails |
|---|---|---|---|
Verification Latency |
9 µs – 0.05 ms (Nanosecond-scale) |
250 – 1,500 ms (Process Spawns) | 500 – 2,500 ms (Network Round-Trip) |
Execution Architecture |
In-Memory Pure Rust Kernel |
Node.js / Python Runtime | Remote HTTP Cloud API |
Context Token Savings |
> 50% - 80% (AST Skeleton) |
0% (Full Files) | 0% (Full Files) |
MCP Protocol Support |
Built-In JSON-RPC 2.0 over Stdio |
Requires Custom Wrappers | Proprietary APIs |
Memory Safety |
100% Safe Rust (0 Unsafe Blocks) |
Varies (C/C++/Node) | Undefined |
External Dependencies |
Zero Crypto/Runtime Bloat |
Heavy node_modules / Python env |
Cloud Connection & API Keys |
Deterministic Guarantee |
100% Formal Invariant Rejection |
Heuristic Warnings | Probabilistic LLM Re-evaluation |
flowchart TD
subgraph Input ["Incoming Code / AI Agent Patch"]
RawCode["Raw Code Snippet / File"]
end
subgraph AstGuardPipeline ["🛡️ AstGuard: 6-Pass Deterministic Firewall (<0.05ms)"]
P0["Pass 0: Delimiter Balance (Dijkstra)"]
P1["Pass 1: Async Mutex Across Await"]
P2["Pass 2: Division-by-Zero Guard"]
P3["Pass 3: Array Bounds Overflow"]
P4["Pass 4: Unsafe Unwrap / Expect Trap"]
P5["Pass 5: ReDoS Catastrophic Backtracking"]
P6["Pass 6: TS/JS Deep Null Dereference"]
end
subgraph Resolution ["Resolution & Verification Verdict"]
VerdictSafe{"All Passes Passed?"}
Reject["❌ Immediate Rejection & Counterexample"]
Approve["✅ Verified Safe AST"]
end
subgraph ContextEngine ["✂️ AstDiffEngine & 🧠 SymbolGraph"]
Cache["⚡ AstContextCache (FIPS 180-4 SHA-256)"]
Skeleton["Context Compression (>50-80% Token Savings)"]
Patch["Surgical Byte-Span Node Replacement"]
end
subgraph Interfaces ["Exposed Runtime Interfaces"]
CLI["💻 CLI Binary: locus check / graph / patch"]
MCP["🔌 Model Context Protocol Server: locus mcp"]
LIB["📦 Rust Library Crate: locus_engine"]
end
RawCode --> P0 --> P1 --> P2 --> P3 --> P4 --> P5 --> P6 --> VerdictSafe
VerdictSafe -->|No| Reject
VerdictSafe -->|Yes| Approve
Approve --> Cache --> Skeleton --> Patch
Patch --> Interfaces
php
graph LR
A[AstGuard Invariant Passes] --> B[1. Delimiter Balance: Dijkstra stack scan]
A --> C[2. Concurrency: std::sync::Mutex across .await points]
A --> D[3. Arithmetic: Unguarded division by variable]
A --> E[4. Bounds: Array index without length checks]
A --> F[5. Panics: Unguarded .unwrap() and .expect()]
A --> G[6. ReDoS: Exponential nested regex quantifiers]
Delimiter Balance (Dijkstra Algorithm): Performs a linear single-pass stack scan validating matching closure for{}
[]
()
across raw byte streams while safely ignoring string literals and escapes. -
Async Mutex Concurrency Trap: Prevents blockingstd::sync::Mutex
locks across asynchronous.await
suspension points to eliminate thread pool exhaustion and deadlocks. -
Division-by-Zero Protection: Proves the denominator is non-zero ($y \neq 0$ ) before permitting arithmetic evaluation. -
Array Bounds Protection: Ensures array and slice indexing (arr[i]
) is preceded by length assertions or safe accessors (.get()
). -
Unsafe Unwrap Guard: Eliminates panic-inducing direct.unwrap()
or.expect()
calls lacking prior safety checks (is_some()
,is_ok()
, orif let
). -
ReDoS Catastrophic Backtracking Guard: Identifies polynomial and exponential nested quantifiers (such as(a+)+$
) that freeze CPU execution threads.
locus-engine
ships with a built-in, zero-dependency MCP server running over stdio (JSON-RPC 2.0). It connects directly to Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code.
Add locus
to your claude_desktop_config.json
or Cursor MCP settings:
{
"mcpServers": {
"locus": {
"command": "locus",
"args": ["mcp"]
}
}
}
| MCP Tool Name | Arguments | Capabilities & Output |
|---|---|---|
check_safety |
||
{"code": "string", "path": "string"} |
||
| Executes 6-pass AST verification; returns passed/failed report with exact violation byte span. | ||
skeletonize |
||
| `{"code": "string", "language": "rust | typescript | python"}` |
| Strips implementation bodies while preserving all signatures, saving >50-80% LLM context tokens. | ||
patch_symbol |
||
{"source": "string", "symbol": "string", "new_code": "string", "language": "string"} |
||
| Performs surgical byte-offset node replacement of a target function/struct without rewriting unchanged code. | ||
index_graph |
||
{"path": "string"} |
||
| Recursively indexes project directory, extracts definitions, and maps cross-file dependency edges. |
curl -fsSL https://raw.githubusercontent.com/ahmadshady747-create/LOCUS/main/scripts/install.sh | bash
irm https://raw.githubusercontent.com/ahmadshady747-create/LOCUS/main/scripts/install.ps1 | iex
cargo install locus-engine
locus check src/lib.rs
locus graph src/
locus patch src/models.rs --symbol User --with "pub struct User { pub id: u64 }"
locus mcp
Add locus-engine
to your Cargo.toml
:
[dependencies]
locus-engine = "0.1.0"
use locus_engine::{AstGuard, AstDiffEngine, SymbolGraph, AstContextCache, Language};
fn main() {
let code = "pub fn safe_calc(a: f64, b: f64) -> f64 { if b != 0.0 { a / b } else { 0.0 } }";
// 1. Instant Invariant Safety Verification (9µs)
let report = AstGuard::verify(code);
assert!(report.passed);
// 2. Surgical Context Compression (>70% Token Savings)
let skeleton = AstDiffEngine::skeletonize(code, Language::Rust);
println!("Compressed Skeleton:\n{}", skeleton);
// 3. Fast In-Memory FIPS 180-4 SHA-256 LRU Cache
let cache = AstContextCache::new(1024);
let hash = cache.insert(code, skeleton, 1);
assert_eq!(hash.len(), 64);
}
d:\LOCUS\
├── Cargo.toml # Single-crate package manifest (locus bin + locus_engine lib)
├── LICENSE # Business Source License 1.1 with explicit As-Is disclaimer
├── README.md # Comprehensive technical documentation & benchmarks
├── SPEC.md # Detailed formal specification of core algorithms
├── .gitattributes # GitHub Linguist classification (100% Rust project)
├── scripts/
│ ├── install.sh # One-line curl installer for Linux & macOS
│ └── install.ps1 # One-line PowerShell installer for Windows
├── tests/
│ └── benchmarks.rs # High-precision benchmark & stress test suite
└── src/
├── lib.rs # Public library exports
├── main.rs # CLI entrypoint (check, graph, patch, mcp commands)
├── types.rs # Core models (SymbolNode, SymbolEdge, VerificationReport)
├── guard.rs # 6-pass deterministic AST safety invariants engine
├── cache.rs # Pure FIPS 180-4 SHA-256 LRU cache with monotonic indexing
├── graph.rs # Polyglot symbol graph & dependency resolver (Rust, TS, Python)
├── diff.rs # Surgical byte-span AST patching and skeletonizer
└── mcp.rs # Zero-dependency stdio Model Context Protocol (MCP) server
locus-engine
is published under the Business Source License 1.1 (BSL 1.1):
| License Tier | Target Audience / Scope | Pricing |
|---|---|---|
| Free Tier | ||
| Individuals, students, open-source projects, and teams with < 5 developers. | ||
| $0 (Free) | ||
| Internal Commercial Seat | ||
| Internal usage & CI/CD within organizations with 5+ developers (Internal use only; no re-selling/SaaS). | ||
| $150 USD / seat / year | ||
| Commercial SaaS & Cloud OEM | ||
| Embedding, hosting, or offering locus-engine as a commercial SaaS, cloud API, or OEM product. | $10,000 USD / year |
Warranty & Support Disclaimer (As-Is / Self-Service):The software is provided "AS IS" on a self-service basis without warranties of any kind. Dedicated technical support, custom SLA guarantees, and enterprise integration assistance are not included unless negotiated under a separate custom agreement.
For license activation and commercial contracts: Contact the author below or email licensing@locus.dev
.
Architected & built independently by Ahmed Shadi (Libya 🇱🇾).
- 📘 Facebook:Ahmed Shadi Profile - 🐙 GitHub:@ahmadshady747-create - 📧 Direct Inquiries: Via GitHub Issues & Discussions