🇹🇭 ภาษาไทย  •  🇨🇳 简体中文  •  🇯🇵 日本語

Fault-Keeper

The Sovereign AI Co-Processor & Zero-Stall Systems Sentry

51 Engineering Pillars · 13 Deep-Inspection Domains · Sovereign Standalone Architecture · Zero External Wrappers

        Hey fellow developers! 🙏✨ We built Fault-Keeper out of the very frustrations many of us live through every day — chasing down bizarre heisenbugs that refuse to reproduce, hitting silent deadlocks the moment real users hit concurrent workloads, or watching systems quietly break because a data structure shifted slightly under the hood.

        When we started writing code alongside AI assistants, things definitely moved faster, but a new layer of paranoia crept in. You find yourself constantly second-guessing: did the model secretly prune a critical helper function? Did it drop a lazy // implement later comment? Is it spinning in an expensive loop burning through tokens without making actual progress? As codebases scale, we end up spending more time babysitting AI output than actually designing new features.

        Fault-Keeper installs and runs locally on your machine with zero friction — no need to refactor existing code or overhaul your workflow. It guards invariants the moment you save a file, catches subtle vulnerabilities long before production, and acts as an intelligent safety harness keeping AI code generation honest, sound, and loop-free. 💖🐡

⚠️ The Hypothesis: Speed vs. Stability	🌿 Enter Fault-Keeper
The AI-assisted coding crisis: silently pruned logic, full-system deadlocks, and skyrocketing token costs from repetitive doom loops.	Fault-Keeper acts as your local engineering co-pilot: real-time defect interception, pure standalone execution, and strict cognitive bounds on AI.

---

🌟 Architectural Highlights

📐 4-Layer System Anatomy	🛡️ 3 Core Operating Principles
4-Layer Runtime Architecture: Sovereign CLI (The Crust) ➔ MCP 2.0 (The Mantle) ➔ Memory Bridge (Outer Core) ➔ 51 Pillars (Inner Core)	3 Invariant Principles: Sovereign Standalone, AI Co-Processor (MCP 2.0 Sensory Cortex), and Formal Mathematical Verification (Z3 SMT)

📐 4-Layer Runtime System Architecture Diagram

┌──────────────────────────────────────────────────────────────────────────────────────┐
│                    4-LAYER RUNTIME ARCHITECTURE OF FAULT-KEEPER v1.0                 │
├──────────────────────────────────────────────────────────────────────────────────────┤
│ Layer 1: Sovereign CLI & Python Ergonomics Facade (fault_keeper.py, Decorators, Lazy)│
├──────────────────────────────────────────────────────────────────────────────────────┤
│ Layer 2: MCP 2.0 Server Daemon (JSON-RPC over stdio -> 5 Omni-Tools via MCP-OFA)     │
├──────────────────────────────────────────────────────────────────────────────────────┤
│ Layer 3: Unified Engine Dispatcher & Shared Memory Bridge (Zero-Copy Memory Buffers) │
├──────────────────────────────────────────────────────────────────────────────────────┤
│ Layer 4: Core Deterministic Algorithm Engines (51 Pillars: Math, Systems, SMT, AST)  │
└──────────────────────────────────────────────────────────────────────────────────────┘

🛡️ 3 Core Architectural Principles

1. Sovereign Standalone ("Python Outside, Native Inside"):
   • Operates as a pure UNIX CLI via fault_keeper.py immediately without relying on external system wrappers.
   • Startup latency stays lightning-fast through dynamic lazy module evaluation.
2. AI Co-Processor & Sensory Cortex:
   • Serves as the ground-truth sensory cortex for AI Coding Assistants like Cursor, Claude Code, Windsurf, Copilot, and Antigravity.
   • Communicates over the standard MCP 2.0 Protocol, collapsing tools into 5 Omni-Tools to save system prompt tokens during turn-by-turn agent invocation.
3. Formal Mathematical Verification:
   • Formally proves logical invariants using Z3 Dual SMT Solver Consensus, Dual Numbers Automatic Differentiation, and Wait-For Graph Cycle Elimination.
   • Every defect detection operates by verifying mathematical invariants directly in memory.

---

🛠️ Installation

📥 Clone & Setup Dependencies

1. Clone the repository and enter the directory

git clone https://github.com/xTanTHaix/Fault-Keeper.git
cd Fault-Keeper

2. Install Dependencies

Fault-Keeper supports Python 3.10, 3.11, and 3.12:

# Install production runtime dependencies (NumPy, SciPy, Z3 SMT Solver)
pip install -r requirements.txt

# For developers looking to run the test suite
pip install -r requirements-dev.txt

Note: For baseline CLI commands (audit, test-audit), Fault-Keeper includes built-in fallbacks that function immediately even before optional math solvers like Z3 or SciPy are installed.

---

🚀 The 4 Operational Postures

Fault-Keeper adapts seamlessly to any developer workflow — from direct shell terminal commands to automated AI Agent co-piloting:

4 ways to integrate Fault-Keeper into your workflow: CLI Engine, MCP 2.0 for AI, Library Module, and One-Line Auto Armor Decorators

┌────────────────────────────────────────────────────────────────────────────────────────┐
│                        FAULT-KEEPER v1.0 OPERATIONAL POSTURES                          │
├─────────────────────┬─────────────────────┬─────────────────────┬──────────────────────┤
│  Posture 1: CLI     │ Posture 2: MCP 2.0  │ Posture 3: Library  │ Posture 4: Auto Armor│
│  (UNIX Engine)      │ (Omni-Facade)       │ (Modular & Facade)  │ (One-Line Decorator) │
├─────────────────────┼─────────────────────┼─────────────────────┼──────────────────────┤
│ python              │ fk_audit            │ import fault_keeper │ @fk.guard            │
│   fault_keeper.py   │ fk_diagnose         │ fk = FaultKeeper()  │ @fault_keeper.armored│
│   audit / test / diag│ fk_patch / fk_verify│ fk.systems.ZSC_ThP()│ (max_drift=0.05)     │
├─────────────────────┼─────────────────────┼─────────────────────┼──────────────────────┤
│ Shell / Pre-commit  │ Serves AI Agents    │ Embed in Backend    │ Instant function     │
│ CI/CD Pipeline      │ (Saves Tokens)      │ Deep Algorithms     │ Deadlock-free shield │
└─────────────────────┴─────────────────────┴─────────────────────┴──────────────────────┘

💻 Posture 1: Sovereign Command-Line Interface (fault_keeper.py)

Audit code, verify architecture, and diagnose issues directly from your shell using 6 core subcommands:

1. Help and Command Reference (--help)

Display all subcommands and flags supported by Fault-Keeper:

python fault_keeper.py --help

2. Architecture Audit & Deadlock Detection (audit)

Scan a target directory for unhandled fail-silent paths (U-FSR), code cohesion and coupling metrics (WPA-HIS), database transaction deadlock cycles (Tx-DLO), and cross-boundary frontend-backend API breaks (CDC-ABS):

python fault_keeper.py audit ./src

• POSIX Exit Codes:
  • 0 = Clean pass (no violations or deadlocks detected)
  • 1 = Violations detected (invariant breach, deadlock risk, or API contract break)
  • 2 = Invalid path or incorrect CLI arguments

3. Flaky Test Isolation & Toxic Pair Sieve (test-audit)

Run permutation shuffling schedule sieves to identify order-dependent test pairs passing dirty shared state (Polluter & Victim Toxic Pair) and capture memory leaks:

python fault_keeper.py test-audit ./tests

4. Deep Root-Cause Diagnosis (diagnose)

Pinpoint high-frequency pitfalls such as loop N+1 queries (LQPC), missing async await race conditions (AE-FPS), catastrophic ReDoS backtracking (RDA-NP), week-based year formatting traps (TC-GTC), and responsive layout clipping (GSLD):

# General diagnostic scan
python fault_keeper.py diagnose ./src

# Enable strict mode to exit with code 1 upon any defect (ideal for CI/CD gates)
python fault_keeper.py diagnose ./src --strict

5. Automated AST 3-Way Merge (solve-merge)

Resolve Git merge conflicts at the Abstract Syntax Tree level by semantically interleaving commutative declarations and reconciling AST branches (supports file paths or inline snippets):

python fault_keeper.py solve-merge base.py our_changes.py their_changes.py

6. Start the MCP JSON-RPC 2.0 AI Server Daemon (mcp)

Launch the headless MCP stdio daemon to serve Cursor, Claude Desktop, Antigravity, or other AI agents:

python fault_keeper.py mcp
# Or specify transport explicitly:
python fault_keeper.py mcp --transport stdio

🤖 Posture 2: Connect AI Agents via MCP 2.0 (Cursor, Claude, Antigravity)

Fault-Keeper ships with an out-of-the-box standalone server supporting the full MCP 2.0 Protocol:

Entrypoint: mcp_server.py

Add this block to your MCP client configuration (e.g., ~/.gemini/config/mcp_config.json, claude_desktop_config.json, or Cursor Settings):

{
  "mcpServers": {
    "fault-keeper": {
      "command": "python",
      "args": [
        "L:\\.Tool\\Fault-Keeper\\mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

The 5 Omni-Tools for AI:

1. fk_audit: Deep-scans files or folders for safety invariants, structural topology, and deadlock hazards.
2. fk_diagnose: Diagnoses performance bottlenecks, async race conditions, N+1 queries, ReDoS, and causal root causes.
3. fk_patch: Generates prescriptive patches and validates them within isolated shadow sandboxes.
4. fk_verify: Verifies cross-system contracts and formally proves mathematical requirements.
5. fk_discover: Allows AI agents to query detailed specs and mathematical invariants across all 51 pillars Just-in-Time.

Natural Chat Prompts (No Terminal Typing Required):

Once MCP is connected, simply prompt your AI assistant directly in chat:

• "Audit the code inside the src folder" ➔ The agent calls fk_audit
• "Diagnose the root cause of the bug in this module" ➔ The agent calls fk_diagnose
• "Test this proposed bugfix in a sandbox" ➔ The agent calls fk_patch
• "Verify the API contract between frontend and backend" ➔ The agent calls fk_verify
• "Find which pillar prevents database transaction deadlocks" ➔ The agent calls fk_discover

📦 Posture 3: Embedded Python Library & Facade (FaultKeeper)

Access all 51 engines through a single unified facade powered by dynamic lazy loading to keep memory footprint minimal:

import fault_keeper

# Create a singleton facade instance
fk = fault_keeper.FaultKeeper()

# 1. Numerical computation & automatic differentiation
dual_x = fk.num.DualNumber(real=3.0, dual=1.0)
y = dual_x * dual_x + 5.0  # y = x^2 + 5
print(f"Function value: {y.real}, Exact derivative: {y.dual}")

# 2. Timezone drift detection for YYYY format trap
has_trap, details = fk.num.TimezoneDriftDetector.detect_format_drift("YYYY-MM-dd")
if has_trap:
    print(f"Warning: Week-based year pattern may shift year boundary: {details}")

# 3. Transaction deadlock cycle detection
wfg = fk.daily.WaitForGraph()
wfg.add_dependency(tx_a="TX1", tx_b="TX2")
wfg.add_dependency(tx_a="TX2", tx_b="TX1") # Cycle formed
cycles = wfg.detect_cycles()
print(f"Detected deadlock cycles: {cycles}")

# 4. Hardware-aware zero-stall memory allocator
allocator = fk.systems.ZSC_ThP() # Dual-Pool Zero Compaction Stall THP Allocator
ptr = allocator.allocate(size_bytes=1024 * 1024 * 2) # Allocated from 2MB THP Static Arena

🛡️ Posture 4: Instant Function Guard with One-Line Decorators (@armored, @guard)

Wrap mission-critical functions with runtime invariant verification using a single clean decorator:

import fault_keeper

# Catch state drift and enforce strict mathematical tolerances
@fault_keeper.armored(max_drift=0.05)
def critical_financial_settlement(account_id: str, balance: float):
    # If state deviation exceeds the threshold, system warns or raises immediately
    return process_settlement(account_id, balance)

# Enforce defensive input contract assertions
@fault_keeper.guard
def transfer_funds(source: str, target: str, amount: float):
    assert amount > 0, "Transfer amount must be positive"
    return execute_transfer(source, target, amount)

---

🏛️ The 51 Core Pillars Catalog

The system architecture is structured across 13 core domains, spanning applied mathematics, hardware-level microarchitecture, and cognitive AI guardrails:

🧪 The 51 Core Pillars Taxonomy	🛡️ AI Agent Armor & Cognitive Router
Taxonomy of 51 pillars spanning 13 domains: from numerical math and low-level memory to daily developer traps.	Shielding against lazy AI placeholders (ASP-HG), shattering doom loops (ACT-LO), and drastically pruning system prompt tokens via Omni-Tools.

1. Applied Mathematics & Numerical Kernel (fk.num): 3 Pillars

Pillar	Full Name	Mechanism & Responsibility
FK-NUM	Numerical Kernel	Computes Dual Number Automatic Differentiation, 128-bit Fixed-Point Arithmetic for financial safety, and $O(1)$ streaming variance via Welford's algorithm.
FK-SLA	Sparse Linear Algebra	64-byte cache-aligned SIMD CSR/CSC storage, parallel SpMV, Pivoted Cholesky decomposition, and Randomized Low-Rank SVD (Halko-Martinsson-Tropp).
FK-GEO	Robust Geometry Engine	Eliminates precision collapse via Shewchuk Exact Adaptive Floating-Point Predicates (Orient2D / InCircle), 30-bit Morton code Linear BVH Trees, and $O(N \log N)$ Monotone Chain Convex Hull.

2. Hardware, Microarchitecture & Systems Low-Level (fk.systems): 16 Pillars

Pillar	Full Name	Mechanism & Responsibility
NUMA-AFS	NUMA-Aware Affinity Sentry	Decodes ACPI SLIT distance matrices, computes Locality Quotient (LQ), and executes Kuhn-Munkres Bipartite Matching (KM-BAW) to bind cores and pages, eliminating interconnect stalls.
ZSC-THP	Zero-Stall Compaction THP	Dual-Pool Hybrid Allocation Arena (DHACS) separating a 2MB THP static arena from a 4KB dynamic pool with an asynchronous background compaction siphon to achieve 0.0ms direct compaction stalls.
FS-CCO	False Sharing Cache Optimizer	Realigns struct layouts to 64-byte cache line boundaries, preventing L1 cache invalidation thrashing across concurrent worker threads.
HEH-DR	Hazard-Epoch Hybrid Reclamation	Lock-free memory reclamation combining 3-Epoch Based Reclamation (EBR) and Hazard Pointers with $< 3%$ reclamation overhead.
APM-RLME	Adaptive Array Layout Engine	Zero-stall transpositions between Array of Structures (AoS) and Structure of Arrays (SoA) using vectorized SIMD strides adapted to runtime read/write ratios.
TSCA	Topological Simplicial Arbiter	Wait-free concurrency arbiter modeled as a simplicial complex; proves absence of deadlock cycles via 1st Betti number homology ($H_1 = 0$).
CAM-RO	Cross-Arch Memory Reordering	Evaluates litmus tests and synthesizes atomic memory barriers across x86 TSO and ARMv8/RISC-V weak memory models.
AC-SBE	Auto-Cooperative Yield Injector	AST-scans CPU-bound operations in async event loops and injects deterministic cooperative preemption points to prevent event loop starvation.
EV-IPP	eBPF Verifier Simulator	Simulates 64-bit Truncated Numbers (Tnum) and register bounds inside your IDE to formally verify eBPF program termination and memory safety.
SABA	SIMD Auto-Vectorization Analyzer	Analyzes loop-carried dependency distances and pointer aliasing to break barriers inhibiting automatic loop vectorization (AVX-512 / NEON).
SC-BBW	Spectral Basic-Block Weaver	Computes the Graph Laplacian of control flow graphs and utilizes the Fiedler eigenvector to order hot basic blocks, drastically cutting instruction cache misses.
PT-PAFS	Pointer Provenance & Tree Borrows	Tracks pointer origins and permissions under the Tree Borrows model to intercept undefined behavior and strict aliasing violations in unsafe C/Rust code.
DIS-RA	Deterministic io_uring Arbiter	Manages io_uring Submission Queues (SQ) and Completion Queues (CQ) with zero-copy ring buffers and deterministic backpressure to prevent CQE overflow.
H-TSS	Hardware Tagged Pointer Sentry	Simulates ARM TBI and x86 UAM top-byte pointer tagging to catch Use-After-Free (UAF) and buffer overflow vulnerabilities at runtime.
MD-BBE	Monomorphization Deduplicator	Computes structural ABI hashes across generic instantiations and collapses redundant implementations into shared polymorphic thunks, reducing binary footprint by 40%–70%.
DMCS	Dominator-Tree Memory Cut Sentry	Analyzes memory reference graphs via Dominator Trees and severs circular reference clusters using Max-Flow Min-Cut, reclaiming $\ge 80%$ of leaked memory.

3. Daily Developer Traps & Pitfalls (fk.daily): 7 Pillars

Pillar	Full Name	Mechanism & Responsibility
FT-DSO	Flaky Test Sieve & Order Oracle	Permutation shuffling schedule generator ($\pi_{\text{shuf}}$), Gray Code binary search toxic-pair isolator ($O(N \log N)$), state leak detector, and virtual discrete event-clock quencher.
Tx-DLO	Transaction Deadlock Oracle	Wait-For Directed Graph ($\mathcal{G}{\text{wfg}}$) analysis enforcing Havender Canonical Total Lock Ordering ($\prec{\text{lock}}$) to ensure $\Pr(\text{Deadlock}) \equiv 0.0$ with pre-sorted dynamic batch keys.
CDC-ABS	Cross-Boundary Contract Sentry	Intercepts breaking API contract changes across backend and frontend at the AST level (Zero-E2E) using Structural Subtyping Covariance Invariants.
AEC-VS	Env Contract & Secret Sentry	Formally validates environment configurations (.env), intercepts leaked credentials, and ensures strict typing on system configurations.
TC-GTC	Timezone & DST Trap Detector	Catches subtle timezone shifts, Daylight Saving Time (DST) traps, and format confusion between week-based YYYY and calendar yyyy.
RDA-NP	ReDoS Catastrophic Backtrack Sentry	Evaluates regular expression complexity and identifies catastrophic polynomial/exponential backtracking traps prior to deployment.
CASI-OP	Cache Stampede & Invalidation Sentry	Coordinates dual-phase cache invalidation alongside database transactions and injects XFetch probabilistic early recomputation to eliminate cache stampedes.

4. AI Agent Armor & Cognitive Router (fk.armor, fk.mcp): 4 Pillars

Pillar	Full Name	Mechanism & Responsibility
ASP-HG	Anti-Placeholder Guard	Detects and blocks lazy AI pruning patterns (such as // implement later, ... existing code ...) via AST Structural Anchor Matching.
ACT-LO	Agent Thrashing Loop Oracle	Detects repetitive edit thrashing (Doom Loops), enforces Monotonic Progress Invariants, and isolates Minimal Unsatisfiable Cores (MUC).
SC-PVE	Speculative Candidate Parallel Verifier	Evaluates candidate patches in parallel across in-memory Copy-on-Write shadow sandboxes and ranks candidates via Zhang-Shasha Tree Edit Distance.
MCP-OFA	Model Context Protocol Omni-Facade	Collapses 51 capabilities into 5 Omni-Tools to conserve system prompt tokens while offering progressive Just-in-Time discovery (fk_discover).

5. Developer Workflow, Typing, Formal & Distributed Systems: 21 Pillars

Category	Featured Pillars	Mechanism & Responsibility
Typing (fk.typing)	FSAS, ATH-BS, AE-FPS, TWSA, ACDS	Virtual Ghost CST error correction, Typed-Hole DTO synthesis, unawaited coroutine race detection, and Type Lattice auto-completions.
Workflow (fk.workflow)	CRCAE, LQPC, SSDL, STAS, A-SMW, PTHO	Single-line causal root-cause abduction, polyhedral N+1 query batching, dependency hell resolver, and AST-based 3-Way merge reconciliation.
Audit (fk.audit)	U-FSR, WPA-HIS	Single-file robustness scoring (Shannon Entropy, Cohesion) and holistic whole-project architectural scoring from 0 to 100 (Acyclic DAG, Modularity).
Full-Stack (fk.workflow)	ZEC-SW, GSLD	Zero-downtime schema evolution via shadow triggers, and responsive CSS clipping resolution via Linear Programming Simplex solvers.
Formal (fk.formal)	CIS3, DCEG, SADS, FSLS	Mock data synthesis using Dual Z3 SMT Consensus, differential causal graphs, and categorical synchronizers.
Distributed & Time (fk.dist)	D-CAS, CADRE	Deterministic network partition and clock drift simulation, and time-travel execution tracers for omniscient replay debugging.

---

🧪 Test Verification & Quality Gates

4-Tier Verification Architecture: From Micro 1:1 Invariants to Stress, Cluster Phase-Gates, and Holistic E2E guaranteeing 100% sound code.

🛡️ 4-Tier Verification Architecture

Fault-Keeper enforces quality across 4 rigorous tiers:

1. Tier 1 (Micro 1:1 Invariants): Mathematical equations and invariants validated 1:1 per pillar against genuine implementations.
2. Tier 2 (Stress & Concurrency): Extreme latency constraints and high-concurrency race condition torture gates.
3. Tier 3 (Cluster Phase-Gates): Large-scale real-world cluster simulations, such as the Monorepo Flaky-Deadlock Gate and Multi-Socket NUMA Cluster.
4. Tier 4 (Holistic E2E): End-to-end POSIX CLI subcommands and live MCP Daemon JSON-RPC communication verification.

# Run the complete test suite across all 723 tests
python -m pytest -q

============================ 723 passed in 73.14s =============================

---

📁 Repository Directory Layout

📂 Complete Directory Tree

Fault-Keeper/
├── fault_keeper.py            # Sovereign Standalone CLI Entrypoint (Layer 1)
├── mcp_server.py              # MCP 2.0 JSON-RPC Standalone Server Daemon (Layer 2)
├── pyproject.toml             # Project Metadata & Packaging Configuration
├── requirements.txt           # Production Runtime Dependencies (NumPy, SciPy, Z3)
├── requirements-dev.txt       # Developer Test Dependencies (PyTest)
│
├── src/
│   └── fault_keeper/          # Core Python Facade & Modules
│       ├── __init__.py        # Singleton FaultKeeper & Lazy Module Loader
│       ├── facade.py          # Unified Omni-Facade & Subsystem Routers
│       ├── systems/           # Hardware & Systems Low-Level Sentries (16 Pillars: NUMA, THP, eBPF...)
│       ├── daily/             # Daily Developer Traps (FT-DSO, Tx-DLO, CDC-ABS)
│       ├── typing/            # Inner-Loop Typing Sentinels (Ghost CST, Await Checker)
│       ├── workflow/          # Developer Productivity (CRCAE, SSDL, N+1 Query)
│       ├── audit/             # Architectural Health & File Robustness (U-FSR, WPA-HIS)
│       └── ...                # Other Domain Engines (num, sla, geo, armor, formal, dist)
│
├── tests/                     # 4-Tier Zero-Mock Deterministic Test Suites (723 Tests)
│   ├── test_tier1_invariants.py
│   ├── test_exhaustive_imports.py
│   ├── test_phase2_tier3_cluster_gate.py
│   ├── test_phase3_tier3_cluster_gate.py
│   └── pillars/               # 1:1 Invariant Tests per Pillar
│
└── assets/
    ├── fault_keeper_chest.png # Project Visual Mascot
    └── 1.jpg - 9.jpg          # System Architecture & Infographic Assets

☕ Reclaim Your Time & Support

Reclaim your time and creative focus: clone, install, and code with absolute peace of mind.

If Fault-Keeper helps save your engineering time and sanity, consider supporting us with coffee or tea on Ko-fi to help fuel future development:

Thank you so much for your support and enthusiasm! 🙏💖☕

---

📜 License

This project is licensed under the open-source MIT License — feel free to use, customize, extend, and integrate it into your personal and commercial workflows. ✨