# Locus: Deterministic AST safety firewall for AI agents in pure Rust (<0.05ms)

> Source: <https://github.com/ahmadshady747-create/LOCUS>
> Published: 2026-08-21 12:24:23+00:00

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 to**80% 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)**.

``` bash
$ 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 + LRU`18.68 µs` |
100% PASS |
🔌 MCP Stdio JSON-RPC Dispatch |
1,000 round-trips | `42.316 ms` |
/ dispatch`42.32 µs` |
100% PASS |
✂️ AstDiffEngine (Patch & Skeleton) |
500 cycles | `28.063 ms` |
/ operation`56.13 µs` |
100% PASS |
🧠 SymbolGraph Polyglot Indexer |
600 files (1,600 symbols) | `16.294 ms` |
/ file`27.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 blocking`std::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()`

, or`if 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
# 1. Deterministic Safety Verification (<0.05ms)
locus check src/lib.rs

# 2. Index Workspace Symbol Graph & Measure Token Savings
locus graph src/

# 3. Surgical Symbol Patching
locus patch src/models.rs --symbol User --with "pub struct User { pub id: u64 }"

# 4. Start Model Context Protocol (MCP) stdio Server
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)](/ahmadshady747-create/LOCUS/blob/main/LICENSE):

| 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](https://www.facebook.com/share/1DZibmYSrx/) - 🐙
**GitHub:**[@ahmadshady747-create](https://github.com/ahmadshady747-create) - 📧
**Direct Inquiries:** Via GitHub Issues & Discussions