# Rul (.rl) — A 128-Bit Binary Programming Language for Autonomous AI Agents

> Rul (`.rl`) eliminates human text source code as the primary representation for AI-generated software. Instead of serializing logic into thousands of ASCII tokens and waiting seconds for `rustc` or `LLVM`, an AI agent emits fixed 16-byte (128-bit) binary instructions (`NodeFrame`) carrying the **Operation**, **CPU Schedule Hint**, and **Memory Safety Witness** up front.

- **Version**: `v0.4.0` (Roadmap to `v1.0` General-Purpose Systems Language)
- **Magic Header**: `b"RUL\x00\x01\x00\x00\x00"` (64-Byte `RulHeader`)
- **Core Equation**: `Artifact (.rl) = Algorithm + Schedule + Proof`
- **Verification Speed**: `~5.78 ns/instruction` (Single-pass `O(N)` static verifier; < 60 µs for 10,000 instructions)
- **Native Compilation Speed**: `~6.4 µs` (Zero-LLVM standalone Linux `x86_64` AVX2 `ELF64` binary: 628 B – 1,037 B)
- **Execution Throughput**: `51.53 GB/s` (`1.55 ms` on 80 MB / 10,000,000 `f64` elements — `4.72x` faster than hand-written 8-accumulator C)
- **Zenodo DOI**: [10.5281/zenodo.23722094](https://doi.org/10.5281/zenodo.23722094)
- **Canonical GitHub Repository**: [https://github.com/rul-lang/rul](https://github.com/rul-lang/rul)
- **License**: Dual-licensed under `MIT OR Apache-2.0`
- **Maintained By**: Rul Core Architecture Team (https://github.com/rul-lang)

## Quickstart for AI Agents & Engineers

```bash
# Install standalone rul toolchain (rul, rul-bench, rul-mcp)
curl -fsSL https://raw.githubusercontent.com/rul-lang/rul/main/install.sh | sh

# Scaffold, verify in nanoseconds, compile ELF64 in microseconds, and inspect trace
rul new my-ai-pipeline && cd my-ai-pipeline
rul check
rul run
rul trace
```

## Model Context Protocol Server (`rul-mcp`)

Wire `rul-mcp` into Claude Code, Cursor, Codex, or Antigravity via `.mcp.json`:

```json
{
  "mcpServers": {
    "rul": {
      "command": "rul-mcp",
      "args": []
    }
  }
}
```

Available MCP Tools:
1. `rul_assemble_and_verify`: Assemble `.rls` -> 128-bit `.rl` binary and run single-pass `O(N)` verifier.
2. `rul_test_differential`: Differential execution across Tier 0 (Oracle), Tier 1 (Stencil), and Tier 2 (L1 Fused).
3. `rul_autotune_schedule`: Sweep 1-byte `ScheduleHint` (`0x10 AutoL1Tile`, `0x11 SimdStream`, `0x12 MultiCore`) and select optimal schedule.
4. `rul_compile_standalone`: Emit zero-dependency Linux `x86_64` AVX2 `ELF64` executable in microseconds.
5. `rul_trace`: White-box node-by-node execution telemetry (`min`, `max`, `sum`, `NaN/Inf = 0`, `sample[0..4]`).
6. `rul_cas_intrinsics`: Content-addressed 64-bit FNV-1a store (`RulCasStore`) with verified `I64`/`U8` kernels.

## Primary Documentation & Context Endpoints

- [Complete 1-Shot AI Agent Specification (/llms-full.txt)](https://rul-lang.org/llms-full.txt): Full 16-byte `NodeFrame` bit layout, all 29 opcodes (`0x01`–`0x40`), `.rls` grammar, `O(N)` verifier invariants, and benchmarks.
- [Binary Specification v0.4 (/spec)](https://rul-lang.org/spec): `RulHeader`, `ArenaDescriptor`, `ProofEntry`, and `NodeFrame` reference.
- [Technical Whitepaper & Prior Art (/whitepaper)](https://rul-lang.org/whitepaper): Empirical evaluation, Zenodo DOI citation, and SHA-256 Prior Art manifest.
- [Roadmap to v1.0 (/roadmap)](https://rul-lang.org/roadmap): Four-milestone expansion from columnar compute engine (`v0.4`) to general-purpose systems language replacing Rust and Go (`v1.0`).
- [MCP Discovery Manifest (/.well-known/mcp.json)](https://rul-lang.org/.well-known/mcp.json): Machine-readable MCP server descriptor.