⚖️ AETHEL Swarm – Autonomous Verified Systems Builder

From natural language to verified binary. Self-healing. Edge-native.

AETHEL Swarm is a cybernetic system that synthesizes, builds, verifies, and repairs C programs from a single idea. It spawns a fleet of isolated agent kernels (coders, compiler, integrator, verifier, harness‑gen) that work in parallel to generate code, resolve linker errors autonomously, and formally verify the resulting binary — all on your local machine or phone.

TRL 4/5 – Validated on edge hardware (Termux/Android). Ready for real‑world use.

---

The Trinity

---

Key Features

• Self‑Healing Linker – Detects duplicate symbols, undefined references, and missing files; surgically patches source code (regex and AST‑based) and retries the link automatically.
• Automated Verification Harness Generation – Generates CBMC harnesses for C functions, with nondeterministic inputs and post‑condition assertions.
• AST‑Based Code Patching – Moves beyond string replacements to structural code transformation via pycparser. Supports renaming, adding free() calls, and extensible recipes.
• Dependency & Header Resolution – Detects missing includes and attempts to locate them in system paths (logs, with future auto‑flagging).
• Runtime Fuzzing & Sanitizers – Executes the final binary with ASan/UBSan and random inputs, reporting memory and undefined behaviour issues.
• Formal Verification Fallback – Uses CBMC if available; otherwise gracefully falls back to Clang Static Analyzer.
• Injection‑Safe & Sandboxed – All compiler/linker commands are invoked via spawn() with array arguments, with path traversal prevention. No shell injection.
• Edge‑Native – Runs on Termux (Android), Linux, macOS, and Windows (WSL). No cloud, no containers, no external orchestration.
• Persistent Learning – HIVE memory bank (lib/hive_memory.json) stores error patterns and repair strategies across sessions.
• Live Logs – WebSocket server (ws://localhost:8090) streams real‑time build telemetry.

---

Quick Start

git clone https://github.com/espnrari-dev/aethel-swarm.git
cd aethel-swarm
./setup.sh           # Installs dependencies, creates directories
npm start &          # Starts SPARX manager on port 3000
sleep 2
npm run forge -- "Build a simple memory allocator"
cat > README.md << 'EOF'
# ⚖️ AETHEL Swarm – Autonomous Verified Systems Builder

> **From natural language to verified binary. Self-healing. Edge-native.**

AETHEL Swarm is a cybernetic system that synthesizes, builds, verifies, and repairs C programs from a single idea. It spawns a fleet of isolated agent kernels (coders, compiler, integrator, verifier, harness‑gen) that work in parallel to generate code, resolve linker errors autonomously, and formally verify the resulting binary — all on your local machine or phone.

**TRL 4/5** – Validated on edge hardware (Termux/Android). Ready for real‑world use.

---

## The Trinity

| Component | Role |
| :--- | :--- |
| **SPARX** (`server.js`) | The **Multiverse Observer**. Launches, monitors, and manages isolated VERITY kernels. Waits for TCP readiness before handing off control. |
| **VERITY** (`templates/verity_kernel.js`) | The **Universe**. A role‑based kernel (coder, compiler, integrator, verifier, coder‑js, harness‑gen) with its own memory, governance, and world model. |
| **FORGE** (`FORGE.js`) | The **Cybernetic Loop**. Orchestrates the full pipeline: plan → generate → harness → compile → link → fuzz → verify → repair → learn → inject. |

---

## Key Features

- **Self‑Healing Linker** – Detects duplicate symbols, undefined references, and missing files; surgically patches source code (regex and AST‑based) and retries the link automatically.
- **Automated Verification Harness Generation** – Generates CBMC harnesses for C functions, with nondeterministic inputs and post‑condition assertions.
- **AST‑Based Code Patching** – Moves beyond string replacements to structural code transformation via `pycparser`. Supports renaming, adding `free()` calls, and extensible recipes.
- **Dependency & Header Resolution** – Detects missing includes and attempts to locate them in system paths (logs, with future auto‑flagging).
- **Runtime Fuzzing & Sanitizers** – Executes the final binary with ASan/UBSan and random inputs, reporting memory and undefined behaviour issues.
- **Formal Verification Fallback** – Uses CBMC if available; otherwise gracefully falls back to Clang Static Analyzer.
- **Injection‑Safe & Sandboxed** – All compiler/linker commands are invoked via `spawn()` with array arguments, with path traversal prevention. No shell injection.
- **Edge‑Native** – Runs on **Termux (Android)**, Linux, macOS, and Windows (WSL). No cloud, no containers, no external orchestration.
- **Persistent Learning** – HIVE memory bank (`lib/hive_memory.json`) stores error patterns and repair strategies across sessions.
- **Live Logs** – WebSocket server (`ws://localhost:8090`) streams real‑time build telemetry.

---

## Quick Start

```bash
git clone https://github.com/espnrari-dev/aethel-swarm.git
cd aethel-swarm
./setup.sh           # Installs dependencies, creates directories
npm start &          # Starts SPARX manager on port 3000
sleep 2
npm run forge -- "Build a simple memory allocator"
⚙️  FORGE: Starting build for "Build a simple memory allocator"
  Generated harness for allocator -> .../allocator_harness.c
  CBMC not installed – skipping harness compilation.
  Compiled mmap_wrapper.c -> .../mmap_wrapper.o
  Compiled allocator.c -> .../allocator.o
  Linked binary -> .../a.out
  ✅ Sanitizers: clean
  Verification [clang-analyzer]: verified
✅ FORGE: Build complete
--

How It Works

1. Planning – FORGE decomposes your idea into modules via lib/planner.js.
2. Fleet Creation – SPARX copies the VERITY template into isolated instances (instances/<domain>/), each assigned a unique role and port.
3. Code Generation – Each coder kernel writes its .c file into the shared volume (shared_build/src/).
4. Harness Generation – FORGE calls lib/harness_gen.py to create CBMC harnesses for each non‑main function.
5. Compilation – The compiler kernel runs gcc -c on each file, producing .o objects. If CBMC is present, harnesses are compiled too.
6. Linking & Auto‑Repair – The integrator kernel links all objects. If a linker error occurs, FORGE parses it and applies a repair (regex or AST‑based), recompiles, and retries. HIVE learns the fix.
7. Runtime Fuzzing – The final binary is executed with ASan/UBSan and random inputs via lib/fuzz.py.
8. Verification – The verifier kernel runs CBMC (if available) or Clang Static Analyzer on the source and harness files.
9. Learn & Inject – HIVE stores the repair pattern. If the build generated JavaScript modules, they are injected into HIVE's memory bank at runtime.

---

Project Structure

aethel-swarm/ ├── FORGE.js # Cybernetic orchestrator ├── server.js # SPARX manager ├── templates/ │ └── verity_kernel.js # Role‑based kernel template ├── lib/ │ ├── sandbox.js # spawn-based safe execution │ ├── verify.js # CBMC / Clang fallback │ ├── errors.js # Linker error parser │ ├── wsLogger.js # WebSocket live logs │ ├── planner.js # Natural‑language to modules │ ├── hive_controller.js # Reasoning engine with memory bank │ ├── ast_patch.py # AST‑based code repair (pycparser) │ ├── harness_gen.py # CBMC harness generation │ ├── deps.py # Dependency & header resolution │ └── fuzz.py # Runtime fuzzing + sanitizers ├── shared_build/ # Shared volume between kernels │ ├── src/ # Generated .c and .o files │ ├── src-js/ # Generated .js modules │ ├── harnesses/ # CBMC harness .c files │ └── out/ # Final binary (a.out) ├── instances/ # SPARX‑managed isolated kernels ├── package.json └── README.md

---

Technology Readiness Level (TRL)

Level Criteria Status
TRL 1–2 Basic principles, concept formulated ✅ Historical
TRL 3 Analytical proof‑of‑concept (regex repairs, no fallback) ✅ Completed
TRL 4 Component/system validation in lab environment ✅ Current
TRL 5 Validated on realistic edge hardware (Termux/Android) ✅ Current
TRL 6 Demonstration in relevant environment (cross‑compilation, multi‑file AST, packaged deps) ⏳ Aspirational

---

Security

· No shell interpolation – gcc and ld are invoked via spawn() with argument arrays.
· Path traversal protection – resolveSharedPath() rejects any path that escapes shared_build.
· Isolation – Each VERITY kernel runs as a separate Node process with its own environment and port.

---

Verification Engine

Tool Status
CBMC Preferred. Formal bounded model checking. Harnesses generated automatically.
Clang Static Analyzer Fallback. Installed by default on Termux (clang).
ASan/UBSan Runtime fuzzing with random inputs. Reports memory and UB issues.

---

Contributing

1. Fork the repo.
2. Create a feature branch: git checkout -b feature/amazing.
3. Commit your changes.
4. Push and open a pull request.

---

License & Ownership

Author: Royriace "Royriquez" Gates
Genesis: July 3, 2026
Reduction to Practice: August 31, 2026
Current Status: TRL 4/5 – Validated on edge hardware

The weight does not lie. We execute the loop.

---

Star the Repo

If this project helps you build verified systems autonomously, please give it a star ⭐. It fuels the multiverse.

---

P.S. – The system is fully functional. The a.out in shared_build/out/ is a real executable. Run it with ./shared_build/out/a.out (it will exit cleanly, because it was verified).