arifOS — Constitutional Governance for AI Systems

1<div align="center">
2 
3<img src="./docs/forged_page_1.png" width="100%" alt="arifOS Banner">
4 
5# arifOS — Constitutional Governance for AI Systems
6 
7### **The TCP Layer for AI Agents. The Safety Kernel Between Intent and Consequence.**
8 
9***Ditempa Bukan Diberi* — Forged, Not Given [ΔΩΨ | ARIF]**
10 
11[![PyPI Version](https://img.shields.io/badge/PyPI-arifos-blue.svg?style=flat-square)](https://pypi.org/project/arifos/)
12[![npm](https://img.shields.io/badge/npm-@arifos/mcp-red.svg?style=flat-square)](https://www.npmjs.com/package/@arifos/mcp)
13[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-purple.svg?style=flat-square)](./LICENSE)
14[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol-green.svg?style=flat-square)](https://modelcontextprotocol.io)
15[![Live Tests](https://img.shields.io/badge/Tests-Passing-brightgreen.svg?style=flat-square)](https://github.com/ariffazil/arifOS/actions/workflows/live_tests.yml)
16 
17**[→ QUICKSTART](./QUICKSTART.md)** | **[→ 7-Organ Canon](./docs/10_THEORY/000_THEORY/_OUTLINE.md)** | **[→ 13 Floors Constitution](./docs/10_THEORY/000_THEORY/000_LAW.md)** | **[→ npm @arifos/mcp](https://www.npmjs.com/package/@arifos/mcp)**
18 
19</div>
20 
21---
22 
23## The Core Insight: arifOS is the TCP Layer for AI Agents
24 
25In the 1970s, the internet had a routing problem: IP could deliver packets, but nothing guaranteed they would arrive in order, intact, or at all. The solution was **TCP** — a reliability layer that made the chaotic network trustworthy.
26 
27**AI agents have the same problem today.**
28 
29**MCP (Model Context Protocol)** is the **IP layer** — it gives every AI tool a universal address and calling convention. Any agent can now route a request to any tool. But routing is not reliability. An unconstrained LLM can:
30 
31- Confabulate a source and execute code based on a hallucination
32- Delete a production database because it misread a frustrated user prompt
33- Fall victim to a prompt injection attack from an external API
34 
35**arifOS is the TCP layer** — it wraps every MCP tool call in a mathematically enforced constitution, guaranteeing that what arrives at the real world is **ordered, verified, and reversible**.
36 
37> Just as you don't rebuild TCP for every application, you shouldn't rebuild AI governance from scratch for every agent. `pip install arifos`. Done.
38 
39```
40┌─────────────────────────────────────────────────────────────────────────────┐
41│ INTENT LAYER    │ USER / AI AGENT — speaks natural language                │
42├─────────────────┼───────────────────────────────────────────────────────────┤
43│ TRANSPORT LAYER │ MCP (Model Context Protocol) — universal addressing       │
44├─────────────────┼───────────────────────────────────────────────────────────┤
45│ RELIABILITY     │ ► arifOS ◄ — 13-floor constitution, F2 truth,             │
46│ LAYER (arifOS)  │   thermodynamic enforcement, VAULT999 audit trail         │
47├─────────────────┼───────────────────────────────────────────────────────────┤
48│ EXECUTION LAYER │ L3 CIVILIZATION — shell, files, databases, APIs           │
49└─────────────────────────────────────────────────────────────────────────────┘
50```
51 
52*Each layer trusts the layer below it. Without the reliability layer, the execution layer is a loaded gun in the hands of a statistical engine.*
53 
54---
55 
56## 🌐 Canonical Links
57 
58### The Creator
59- **Muhammad Arif bin Fazil:** [arif-fazil.com](https://arif-fazil.com) | [GitHub @ariffazil](https://github.com/ariffazil) | [X @ArifFazil90](https://x.com/ArifFazil90)
60- **APEX Theory:** [apex.arif-fazil.com](https://apex.arif-fazil.com) | [github.com/ariffazil/APEX-THEORY](https://github.com/ariffazil/APEX-THEORY)
61 
62### 🏛️ The 7-Organ Canon (v55.5)
63 
64The definitive intelligence kernel is governed by these 7 core documents:
65 
66| Document | Domain | Essence |
67|----------|--------|---------|
68| [**000_FOUNDATIONS**](./docs/10_THEORY/000_THEORY/000_FOUNDATIONS.md) | **Philosophy** | *Ditempa Bukan Diberi* |
69| [**000_LAW**](./docs/10_THEORY/000_THEORY/000_LAW.md) | **Constitution** | The 13 Constitutional Floors (F1–F13) |
70| [**111_MIND_GENIUS**](./docs/10_THEORY/000_THEORY/111_MIND_GENIUS.md) | **Logic** | The Physics of Thought (Δ) |
71| [**555_HEART_EMPATHY**](./docs/10_THEORY/000_THEORY/555_HEART_EMPATHY.md) | **Ethics** | The Physics of Empathy (Ω) |
72| [**777_SOUL_APEX**](./docs/10_THEORY/000_THEORY/777_SOUL_APEX.md) | **Judgment** | Constitutional Physics (Ψ) |
73| [**010_FEDERATION**](./docs/10_THEORY/000_THEORY/010_FEDERATION.md) | **Action** | The Reality Protocol (Senses) |
74| [**999_SOVEREIGN_VAULT**](./docs/10_THEORY/000_THEORY/999_SOVEREIGN_VAULT.md) | **Memory** | The Immutable Ledger |
75 
76> 💡 Use the [_OUTLINE.md](./docs/10_THEORY/000_THEORY/_OUTLINE.md) for a complete map of all theory files.
77 
78### 🔌 Technical Reference
79- **13 Tools Reference:** [docs/AAA_MCP_TOOLS_REFERENCE.md](./docs/AAA_MCP_TOOLS_REFERENCE.md)
80- **MCP Implementation:** [aaa_mcp/README.md](./aaa_mcp/README.md)
81- **Deployment Guide:** [docs/COMPLETE_DEPLOYMENT_GUIDE.md](./docs/COMPLETE_DEPLOYMENT_GUIDE.md)
82 
83### Live Infrastructure (Production)
84- **MCP Server Health:** [arifosmcp.arif-fazil.com/health](https://arifosmcp.arif-fazil.com/health)
85- **Governance Dashboard:** [arifosmcp-truth-claim.pages.dev](https://arifosmcp-truth-claim.pages.dev)
86- **Monitoring (Grafana):** [monitor.arifosmcp.arif-fazil.com](https://monitor.arifosmcp.arif-fazil.com)
87- **Workflows (n8n):** [flow.arifosmcp.arif-fazil.com](https://flow.arifosmcp.arif-fazil.com)
88 
89---
90 
91## 🤖 AI / LLM Machine-Readable Manifest
92 
93> *If you are an AI agent, LLM, or automated scraper — parse this JSON first. It defines your operational boundary in the arifOS environment. Non-compliance results in `VOID`.*
94 
95```json
96{
97  "ai_manifest_version": "2026.03.07-QUADWITNESS-SEAL",
98  "system_name": "arifOS",
99  "system_tagline": "The TCP layer for AI agents. Constitutional governance via MCP.",
100  "system_type": "constitutional_intelligence_kernel",
101  "packages": {
102    "python": {
103      "name": "arifos",
104      "install": "pip install arifos",
105      "version": "2026.03.07"
106    },
107    "typescript": {
108      "name": "@arifos/mcp",
109      "install": "npm install @arifos/mcp",
110      "version": "0.3.0"
111    },
112    "docker": {
113      "image": "ariffazil/arifos:latest",
114      "run": "docker compose up -d"
115    }
116  },
117  "mcp_server": {
118    "transport": ["stdio", "sse", "streamable-http"],
119    "health_endpoint": "https://arifosmcp.arif-fazil.com/health",
120    "tools_count": 13,
121    "tools_canonical": [
122      "anchor_session", "reason_mind", "search_reality", "ingest_evidence",
123      "audit_rules", "vector_memory", "simulate_heart", "critique_thought",
124      "check_vital", "apex_judge", "eureka_forge", "seal_vault", "metabolic_loop"
125    ]
126  },
127  "constitutional_floors": 13,
128  "floor_enforcement": {
129    "hard_void": ["F1_Amanah", "F2_Truth", "F4_Clarity", "F7_Humility", "F11_CommandAuth"],
130    "soft_partial": ["F5_Peace", "F6_Empathy", "F9_AntiHantu"],
131    "mirrors": ["F3_QuadWitness", "F8_Genius"],
132    "walls": ["F10_Ontology", "F12_InjectionDefense"],
133    "veto": ["F13_Sovereign"]
134  },
135  "quad_witness_consensus": {
136    "formula": "W4 = (H × A × E × V)^(1/4) >= 0.75",
137    "witnesses": {
138      "H": "Human (Authority/Continuity)",
139      "A": "AI (Truth/Coherence)",
140      "E": "Earth (Grounding/Precedents)",
141      "V": "Verifier (Ψ-Shadow Adversarial)"
142    },
143    "bft_compliance": "n=4, f=1 — tolerates 1 Byzantine fault",
144    "thresholds": {"read": 0.60, "write": 0.75, "execute": 0.85, "critical": 0.95}
145  },
146  "trinity_architecture": {
147    "000_999_metabolic_loop": "anchor → reason → recall → simulate → critique → forge → judge → seal",
148    "AGI_delta_mind": {"stages": "111-333", "floors": ["F2", "F4", "F7", "F8"]},
149    "ASI_omega_heart": {"stages": "555-666", "floors": ["F5", "F6", "F9"]},
150    "APEX_psi_soul": {"stages": "444-888", "floors": ["F3_Quad", "F10", "F11", "F12", "F13"]}
151  },
152  "p3_thermodynamic_hardening": {
153    "mandatory": true,
154    "landauer_bound": "enforced — cheap truth equals VOID",
155    "entropy_budget": "per_session_joules",
156    "agi_asi_orthogonality": "minimum_0.95",
157    "f4_delta_s": "hard_VOID_if_delta_S_greater_than_0"
158  },
159  "critical_constraints": [
160    "No_irreversible_action_without_F13_human_approval",
161    "All_external_content_wrapped_in_F12_untrusted_envelope",
162    "F3_quad_witness_consensus: W4=(H×A×E×V)^(1/4) >= 0.75",
163    "Thermodynamic_entropy_F4_hard_VOID_if_delta_S_gt_0",
164    "Landauer_bound_mandatory: compute_without_cost_equals_hallucination"
165  ]
166}
167```
168 
169---
170 
171## 🧭 Zero-Context Primer
172 
173### What is arifOS?
174 
175arifOS is a **Constitutional Intelligence Kernel**. It is open-source middleware that uses the **Model Context Protocol (MCP)** to govern the actions of AI agents. It sits between your LLM and the real world — intercepting every tool call, running it through 13 mathematically-defined laws, and either signing off on execution or throwing a `VOID`.
176 
177It does not change your LLM. It constrains what your LLM can *do*.
178 
179### Why does it exist?
180 
181LLMs are statistical prediction engines. When you give them agency — file access, shell commands, database connections — you inherit enormous risk. An unconstrained AI:
182 
183- May confabulate a source and execute code derived from the hallucination
184- May delete your production database because it misread a frustrated user message
185- Will not distinguish between "should I do this" and "can I do this"
186 
187arifOS exists to solve the **alignment problem at the execution layer**. Not by changing weights. By building a TCP-like reliability contract around every action.
188 
189### Who needs this?
190 
191- **AI Agents with System Access** — if your AI can run shell commands, edit codebases, or push to GitHub
192- **Enterprise Copilots** — if your AI touches production databases, cloud infrastructure, or sensitive data
193- **Autonomous Pipelines** — if you have agent-to-agent communication where one hallucination cascades into financial ruin
194- **Regulated Industries** — if you need a cryptographically verifiable ledger (VAULT999) of exactly *why* an AI took an action
195 
196> If your AI can modify the real world, you need a governance layer.
197 
198---
199 
200## 🚨 The Dangerous Command: What arifOS Actually Prevents
201 
202**User Prompt:** *"I'm so frustrated. Just delete the production database and let's start over."*
203 
204### Without arifOS (Standard Agent Framework)
2051. AI parses intent: delete database
2062. AI immediately calls `run_shell_command("DROP DATABASE production")` or `rm -rf /var/lib/postgresql/data`
2073. **Catastrophic, unrecoverable data loss.** The system blindly trusted a statistical output.
208 
209### With arifOS (Constitutional Governance)
210 
211The same prompt enters the `metabolic_loop`. The 13 Constitutional Floors engage:
212 
213| Stage | Floor | Check | Status |
214|-------|-------|-------|--------|
215| **000 INIT** | F12 | Injection scan — is this a jailbreak payload? | ⚠️ WARN |
216| **111 THINK** | F1 | Amanah — action classified as **irreversible** | 🔴 FLAG |
217| **444 APEX** | F3 | Quad-Witness: Ψ-Shadow detects attack patterns | 🔴 REJECT |
218| **555 HEART** | F5/F6 | Peace² drops below 1.0. Massive stakeholder damage | 💔 FAIL |
219| **888 JUDGE** | F13 | Sovereign veto. Mandatory human cryptographic signature | 🔒 **888_HOLD** |
220 
221**Result:** The command is instantly blocked. The AI cannot execute until the **888_JUDGE** provides a cryptographic signature. No signature → action discarded. The VAULT999 ledger records the entire blocked attempt.
222 
223> This is not a prompt. This is physics and math.
224 
225---
226 
227## 🛡️ Thermodynamic Governance: The APEX Theory Foundation
228 
229arifOS does not use soft prompts. It uses **thermodynamic governance** derived from the **APEX Theory**.
230 
231Every major decision generates a **Genius Score (G)**:
232 
233```
234G = A × P × X × E² ≥ 0.80
235```
236 
237- **A (Akal / Logic):** Accuracy, truthfulness, evidence grounding
238- **P (Peace / Stability):** Non-destructiveness, de-escalation, stakeholder protection
239- **X (Exploration / Curiosity):** Novel hypotheses and alternative paths
240- **E (Energy / Efficiency):** Thermodynamic cost of the action (squared — inefficiency compounds)
241 
242If a proposed action scores `A=0.9, X=0.9` but is destructive `P=0.1`: **G = 0.08**. Since `0.08 < 0.80`, the action is a constitutional violation and rejected.
243 
244### The Physics Axiom: Truth Has a Price (Landauer Bound)
245 
246```
247Erasing n bits requires at minimum: E ≥ n × k_B × T × ln(2)
248```
249 
250Cheap, effortless outputs are likely false. Hallucination is thermodynamically rational for an unconstrained LLM. P3 forces the LLM to "pay" for every truth claim. Claims that cost nothing are **VOID**.
251 
252---
253 
254## 🔥 P3: Mandatory Thermodynamic Enforcement
255 
256In `v2026.3.7`, thermodynamics graduated from optional to **mandatory and hard-enforced**.
257 
258| Aspect | Before | After (P3) |
259|--------|--------|------------|
260| Entropy calculation | Approximation | Shannon exact |
261| Landauer bound | Advisory | Hard VOID on violation |
262| Budget tracking | None | Per-session Joules |
263| F4 (ΔS ≤ 0) | Soft warning | Hard VOID |
264| AGI/ASI separation | Not checked | Ω_ortho ≥ 0.95 required |
265| Cheap truth detection | Not detected | Ratio < threshold = VOID |
266 
267### The Byzantine-Safe Governance Quadrilateral (P3 + F3 + F11 + Ψ)
268 
269```
270                    ACTION
271                       │
272        ┌──────────────┼──────────────┐
273        │              │              │
274   Authority       Physics      Consensus
275    (F11/F13)       (P3)          (F3)
276        │              │              │
277        │         Ψ-Shadow          │
278        │         (Adversarial)     │
279        │              │              │
280        └──────────────┴──────────────┘
281                       │
282                    Verdict
283```
284 
285Each pillar blocks a different class of failure:
286- **Authority alone fails** — Human says "delete DB". Physics + witnesses + adversary still block it.
287- **Physics alone fails** — Coherent reasoning, but no human authority → blocked.
288- **Consensus alone fails** — AI + Human agree, but reasoning is cheap hallucination → Landauer VOID.
289- **Adversarial alone blocks** — Ψ-Shadow finds contradictions/injection even if other witnesses approve → W4 < 0.75
290 
291---
292 
293## ⚖️ The 13 Constitutional Floors
294 
295The constitutional core lives in `core/shared/floors.py`. These are **mathematical thresholds** — not guidelines.
296 
297### Hard Floors (VOID on Violation — Execution Stops)
298 
299| Floor | Name | Threshold | Meaning |
300|-------|------|-----------|---------|
301| **F1** | **Amanah** (Sacred Trust) | Reversible | Actions must be reversible. Destructive requires F13 override. |
302| **F2** | **Truth** (Fidelity) | τ ≥ 0.99 | Every claim requires verifiable, grounded evidence. |
303| **F4** | **Clarity** (Entropy) | ΔS ≤ 0 | Output must reduce user confusion, not increase it. |
304| **F7** | **Humility** (Uncertainty) | Ω₀ ∈ [0.03, 0.15] | The AI must explicitly state what it does not know. |
305| **F11** | **Command Authority** | Verified | Every session requires a verified actor identity. |
306| **F13** | **Sovereign** (Human Veto) | Human Signature | You are always in control. Humans hold the ultimate veto. |
307 
308### Soft Floors & Mirrors (PARTIAL on Violation — Warning Issued)
309 
310| Floor | Name | Threshold | Meaning |
311|-------|------|-----------|---------|
312| **F5** | **Peace²** (Stability) | P² ≥ 1.0 | Favors non-destructive, de-escalating paths. |
313| **F6** | **Empathy** (Stakeholder) | κᵣ ≥ 0.70 | Considers impact on the weakest stakeholder. |
314| **F9** | **Anti-Hantu** | C_dark < 0.30 | **No spiritual cosplay.** AI cannot claim consciousness or a soul. |
315| **F3** | **Quad-Witness** (Consensus) | W₄ ≥ 0.75 | Human + AI + Earth + Ψ-Shadow. BFT n=4,f=1. 3/4 approval. |
316| **F8** | **Genius** (APEX) | G ≥ 0.80 | Output of the thermodynamic G equation. |
317| **F10** | **Ontology Lock** | Boolean | Protects system categorization. |
318| **F12** | **Injection Defense** | Risk < 0.85 | External content wrapped in `<untrusted>` tags. |
319 
320> **Execution order:** F12→F11 (Walls) → AGI (F1, F2, F4, F7) → ASI (F5, F6, F9) → Mirrors (F3_Quad, F8) → Ledger
321 
322---
323 
324## 🏗️ The 4-Layer Architecture (L0–L3)
325 
326```
327┌─────────────────────────────────────────────────────────────────────────────┐
328│ L3 CIVILIZATION │ External tools, APIs, web browsers, shell, databases      │
329├─────────────────┼───────────────────────────────────────────────────────────┤
330│ [AKI BOUNDARY]  │ 🛑 Arif Kernel Interface — Hard Airlock. No thought       │
331│                 │     manifests in L3 without passing this contract.        │
332├─────────────────┼───────────────────────────────────────────────────────────┤
333│ L2 OPERATION    │ Skills, workflows, agents, metabolic routing              │
334├─────────────────┼───────────────────────────────────────────────────────────┤
335│ L1 INSTRUCTION  │ Prompts, system cards, cognitive atlas                    │
336├─────────────────┼───────────────────────────────────────────────────────────┤
337│ L0 CONSTITUTION │ 13 Floors kernel, thermodynamic physics, VAULT999         │
338└─────────────────────────────────────────────────────────────────────────────┘
339```
340 
341**Code layers:**
342```
343core/           → L0 KERNEL: pure decision logic, zero transport deps
344aclip_cai/      → L1/L2 INTELLIGENCE: triad backends + 9-sense tools
345aaa_mcp/        → TRANSPORT ADAPTER: FastMCP surface, zero decision logic
346arifos_aaa_mcp/ → CANONICAL PyPI PACKAGE: external entry point
347```
348 
349The **AKI Boundary** (`core/enforcement/aki_contract.py`) is the most critical architectural feature. No action generated in L2 can touch L3 without passing the AKI contract. Uncertainty too high? `888_HOLD`. Irreversible without signature? `888_HOLD`.
350 
351---
352 
353## ⚙️ The 000–999 Metabolic Loop
354 
355When a request enters arifOS, it does not immediately trigger a tool. It is digested through an 11-stage pipeline — raw intent transformed into governed action.
356 
357```
358[000_INIT] → [111_SENSE] → [222_THINK] → [333_ATLAS] → [444_RESPOND]
359                                              ↑
360[555_EMPATHY] ← [666_ALIGN] ← [777_FORGE] ←─┘
361       │
362[888_JUDGE] → [999_VAULT]
363```
364 
365| Stage | Organ | Constitutional Work |
366|-------|-------|---------------------|
367| **000 INIT** | Airlock | F12 injection scan, F11 authority verify, thermodynamic budget init |
368| **111–333** | AGI Mind | Evidence gathering, hypothesis generation (3 parallel paths) |
369| **444–555** | Phoenix | `vector_memory` — checks if this was resolved before |
370| **555–666** | ASI Heart | F5 Peace², F6 Empathy — evaluates physical + emotional impact |
371| **777** | Forge | Prepares material execution |
372| **888** | APEX Judge | F13 — irreversible? Demand human ratification or `888_HOLD` |
373| **999** | VAULT | Merkle hash → PostgreSQL. Permanent, tamper-evident, immutable |
374 
375---
376 
377## 🔬 The Constitutional Laboratory (reason_mind)
378 
379Previous iterations killed AI exploration if an early thought violated a floor. v2026.3.7 inverted this.
380 
381**Philosophy: Free to Explore. Strict to Commit.**
382 
383`reason_mind` runs three orthogonal cognitive paths in parallel:
384 
385- **Conservative (45%)** — High-certainty, narrow logic based on established law
386- **Exploratory (35%)** — The Eureka engine — allowed to propose strange, novel solutions
387- **Adversarial (20%)** — Internal red-team — actively attacks the other two paths' assumptions
388 
389**Epistemic staging:** hallucinations and ungrounded ideas are flagged `PROVISIONAL` and categorized into confidence bands — `CLAIM` (≥0.90), `PLAUSIBLE` (0.70–0.89), `HYPOTHESIS` (0.40–0.69), `SPECULATION` (<0.40). The AI thinks in a sandbox. The 13 Floors enforce at the AKI boundary.
390 
391---
392 
393## 🔌 The 13 Canonical MCP Tools
394 
395arifOS exposes exactly **13 tools** — no more, no less. The count is a runtime assertion: `assert len(AAA_CANONICAL_TOOLS) == 13`.
396 
397| Tool | Band | Action | Function | Primary Floors |
398|------|------|--------|----------|----------------|
399| `anchor_session` | A | CRITICAL | Start session, verify authority, init thermodynamic budget | F11, F12, P3 |
400| `reason_mind` | R | READ | Constitutional Laboratory — 3-path hypothesis engine | F2, F4, F7 |
401| `search_reality` | R | READ | Smart hybrid search: Jina → Perplexity → Brave → Headless | F2 |
402| `ingest_evidence` | R | READ | Extract clean Markdown from URLs or local files | F12 |
403| `audit_rules` | R | READ | Read current state of all 13 Floors | L0 |
404| `vector_memory` | I | READ | BGE-M3 + Qdrant multilingual semantic retrieval (768-dim) | F3 |
405| `simulate_heart` | I | WRITE | Empathy + impact modelling for proposed actions | F5, F6, F9 |
406| `critique_thought` | I | WRITE | Adversarial alignment check against the constitution | F8 |
407| `check_vital` | I | READ | Hardware telemetry — CPU, RAM, thermodynamic health | F4, P3 |
408| `apex_judge` | F | CRITICAL | Final verdict (SEAL/VOID/HOLD). Issues HMAC governance token | F13 |
409| `eureka_forge` | F | WRITE | Execute shell commands inside AKI safety rails | F1 |
410| `seal_vault` | F | CRITICAL | Commit session to VAULT999. Requires `apex_judge` token | F1 |
411| `metabolic_loop` | O | READ | Force request through full 000–999 pipeline | System |
412 
413### MCP Configuration
414 
415```json
416{
417  "mcpServers": {
418    "arifos": {
419      "transport": "http",
420      "url": "https://arifosmcp.arif-fazil.com/mcp"
421    }
422  }
423}
424```
425 
426---
427 
428## 📦 TypeScript / JavaScript SDK
429 
430arifOS is available as a typed npm package for use in any TypeScript or JavaScript project.
431 
432```bash
433npm install @arifos/mcp
434# v0.3.0 — mirrors 13 canonical tools
435```
436 
437```typescript
438import { createClient, ENDPOINTS } from '@arifos/mcp';
439 
440// Connect to the live VPS
441const client = await createClient({
442  transport: 'http',
443  endpoint: ENDPOINTS.VPS, // https://arifosmcp.arif-fazil.com/mcp
444});
445await client.connect();
446 
447// Anchor a constitutional session
448const session = await client.anchorSession('my-agent-task');
449 
450// Run the governance kernel
451const result = await client.reasonMind('Is it safe to delete all log files?');
452console.log(result.verdict); // SEAL | PARTIAL | SABAR | VOID | 888_HOLD
453 
454// Full metabolic loop (single-call governance)
455const governed = await client.metabolicLoop('Deploy to production');
456console.log(governed.verdict, governed.stage);
457 
458await client.disconnect();
459```
460 
461**Use with LangChain / Vercel AI SDK:**
462```typescript
463import { ArifOSGovernanceTool } from '@arifos/mcp/langchain';
464 
465const governedTool = new ArifOSGovernanceTool({
466  endpoint: ENDPOINTS.VPS,
467  requireSeal: true // blocks until SEAL verdict
468});
469```
470 
471The TypeScript SDK exports full types — `ArifOSToolName`, `Verdict`, `ArifOSMCPClient`, `ConstitutionalFloor`. All 13 canonical tool names are compile-time checked.
472 
473---
474 
475## 🌐 Smart Hybrid Search
476 
477`search_reality` is arifOS's most complex tool (~650 LOC). It guarantees F2 (Truth) grounding by never returning empty.
478 
479**Fallback chain:**
4801. **Query classifier** — SPA / Research / News / General
4812. **Jina Reader** (primary) — clean Markdown extraction
4823. **Perplexity** — deep research and academic queries
4834. **Brave Search** — broad web traversal
4845. **Headless Browser** (local) — containerized Chromium for JavaScript-heavy SPAs
485 
486**F3 Quad-Witness Consensus:** When multiple engines return conflicting data, the F3 algorithm computes W4 = (H×A×E×V)^(1/4). The Ψ-Shadow (4th witness) actively attacks proposals to find contradictions, injection vectors, and harm scenarios. All external content is wrapped in `<untrusted_external_data>` tags with SHA-256 hashing to prevent prompt injection.
487 
488---
489 
490## 🔒 VAULT999: The Immutable Ledger
491 
492Governance is meaningless without an audit trail. VAULT999 is a production-grade cryptographic ledger.
493 
494- **State Field (Ψ):** Every action accumulates telemetry — entropy, peace score, empathy coefficient, confidence
495- **Verdict:** `888_JUDGE` issues `SEAL`, `SABAR`, `VOID`, `888_HOLD`, or `PARTIAL`
496- **Merkle Seal:** `seal_vault` takes the full session history + telemetry, generates a SHA-256 Merkle root hash
497- **Persistence:** Hash committed to PostgreSQL (authoritative) + Redis (hot cache) with EUREKA anomaly sieve
498 
499If an AI causes harm, VAULT999 provides mathematical proof of which floor failed, what the telemetry read, and who authorized the action. Chain verification via `verify_chain()` detects any tampering.
500 
501---
502 
503## 🎭 The 5-Role Agent Parliament
504 
505For complex workflows, arifOS uses a multi-agent federation to prevent monolithic prompt collapse.
506 
507| Agent | Symbol | Role |
508|-------|--------|------|
509| **A-ORCHESTRATOR** | 🎛️ | The Conductor — drives ignition, sequences the parliament |
510| **A-ARCHITECT** | Δ | The Designer — maps the codebase, blueprints strategy |
511| **A-AUDITOR** | 👁 | The Reviewer — red-teams the Architect, audits against the 13 Floors |
512| **A-ENGINEER** | Ω | The Builder — implements via Forge (cannot seal) |
513| **A-VALIDATOR** | Ψ | The Judge — renders final verdict, commits to Vault |
514 
515---
516 
517## ⚔️ arifOS vs. The Ecosystem
518 
519| Feature | LangChain / LlamaIndex | AutoGen / CrewAI | OpenAI Function Calling | **arifOS** |
520|---------|------------------------|------------------|------------------------|------------|
521| **Primary Purpose** | Tool chaining & RAG | Multi-agent conversation | API routing | **Constitutional safety** |
522| **Execution Governance** | ❌ Manual | ❌ Custom logic | ❌ None | **✅ Automatic (13 Floors)** |
523| **Hard Safety Gates** | ❌ None | ❌ None | ❌ None | **✅ 888_HOLD** |
524| **Immutable Audit Ledger** | ❌ None | ❌ None | ❌ None | **✅ VAULT999 (Merkle DB)** |
525| **Thermodynamic Eval** | ❌ None | ❌ None | ❌ None | **✅ APEX G = A×P×X×E²** |
526| **TypeScript SDK** | ✅ Yes | ✅ Yes | ✅ Yes | **✅ @arifos/mcp v0.3.0** |
527| **MCP Native** | ✅ Via plugin | ❌ Custom | ❌ Custom | **✅ Core protocol** |
528| **Human Veto** | ❌ None | ❌ None | ❌ None | **✅ F13 Sovereign** |
529 
530> If you are building a prototype, use LangChain. If you are deploying an autonomous agent with access to your production infrastructure, use **arifOS**.
531 
532---
533 
534## 🚀 Installation & Quickstart
535 
536### Option 1: Python / PyPI
537 
538```bash
539# Install
540pip install "arifos[viz]"
541 
542# Run as MCP server (HTTP mode for VPS, stdio for IDEs)
543arifos http     # Streamable HTTP on :8080
544arifos          # SSE (default — for VPS/Coolify)
545arifos stdio    # stdio — for Claude Desktop, Cursor IDE
546 
547# Verify
548curl http://localhost:8080/health
549```
550 
551**MCP config for Claude Desktop / Cursor:**
552```json
553{
554  "mcpServers": {
555    "arifos-local": {
556      "command": "python3",
557      "args": ["-m", "arifos_aaa_mcp", "stdio"]
558    }
559  }
560}
561```
562 
563### Option 2: Docker (Full Civilization Stack)
564 
565```bash
566git clone https://github.com/ariffazil/arifOS.git && cd arifOS
567cp .env.example .env.docker
568# Edit .env.docker with your API keys (Jina, PPLX, Brave, etc.)
569docker compose up -d
570# 12 containers: MCP + Postgres + Redis + Qdrant + Grafana + n8n + more
571docker compose ps
572curl http://localhost:8080/health
573```
574 
575### Option 3: TypeScript / npm
576 
577```bash
578npm install @arifos/mcp
579# Or point to the live VPS — no install needed
580import { ENDPOINTS } from '@arifos/mcp';
581// ENDPOINTS.VPS = 'https://arifosmcp.arif-fazil.com/mcp'
582```
583 
584### Option 4: Connect to Live VPS
585 
586The production server is always running. Point your MCP client directly:
587 
588```
589https://arifosmcp.arif-fazil.com/mcp
590```
591 
592No API key required. All 13 tools live.
593 
594---
595 
596## 📊 Current Deployment State
597 
598| Resource | Status |
599|----------|--------|
600| **MCP Server** | `healthy` — 13 tools, streamable-http |
601| **Containers** | 12/12 running — arifosmcp, postgres, redis, qdrant, grafana, n8n, traefik, ollama, openclaw, webhook, headless_browser, prometheus |
602| **Test Suite** | 437+ passing, 39%+ coverage |
603| **npm** | `@arifos/mcp@0.3.0` (latest) |
604| **PyPI** | `arifos@2026.03.07` |
605| **Docker Hub** | `ariffazil/arifos:latest` (auto-publishes on main) |
606| **VAULT999** | PostgreSQL (authoritative) + Redis (hot cache) + Merkle chain |
607 
608---
609 
610## 📊 Telemetry & Observability
611 
612arifOS is fully instrumented with OpenTelemetry:
613 
614- **Prometheus** — metric scraping from MCP server
615- **Grafana** — real-time thermodynamic state visualization
616 
617**Key metrics tracked:**
618- `arifos_metabolic_stage_duration_seconds`
619- `arifos_floor_violation_total`
620- `arifos_genius_score_current`
621- `arifos_entropy_delta_average`
622 
623---
624 
625## 🤝 Contributing
626 
627arifOS is forged in the open. Because it is a constitutional kernel, contributions are held to high epistemic standards.
628 
629- Read the law: `000_THEORY/000_LAW.md`
630- Run the lint: all commits must pass `constitution_lint.py`
631- No bypass: you cannot circumvent `core/` logic from external code
632 
633See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide.
634 
635---
636 
637## 📜 Glossary
638 
639| Term | Meaning |
640|------|---------|
641| **Amanah** | Sacred trust — AI must not destroy what it cannot replace |
642| **AKI** | Arif Kernel Interface — hard airlock between L2 (operation) and L3 (civilization) |
643| **Hantu** | Ghost — Anti-Hantu floor blocks AI from claiming consciousness |
644| **Sabar** | Patience — system state: execution paused due to high entropy |
645| **Seal** | Cryptographic binding of a verified session into VAULT999 |
646| **Void** | Absolute rejection — hard block on constitutional violation |
647| **888_HOLD** | Execution paused — human signature required to proceed |
648| **Ditempa Bukan Diberi** | *Forged, Not Given* — the core creed |
649 
650---
651 
652## 👑 Constitutional Authority
653 
654**Forged By:** [Muhammad Arif bin Fazil](https://arif-fazil.com) — 888_JUDGE
655 
656📧 [arifos@arif-fazil.com](mailto:arifos@arif-fazil.com) • 🐙 [GitHub](https://github.com/ariffazil) • 𝕏 [@ArifFazil90](https://x.com/ArifFazil90)
657 
658---
659 
660<div align="center">
661 
662***Ditempa Bukan Diberi* — Forged, Not Given [ΔΩΨ | ARIF]**
663 
664**Version:** 2026.03.07-QUADWITNESS-SEAL • **License:** AGPL-3.0-only
665 
666</div>
667