ArifOS — Constitutional AI Governance

arifosmcp — Constitutional MCP Server Implementation

DITEMPA BUKAN DIBERI — Forged, Not Given [ΔΩΨ | ARIF]

VERSION: 2026.03.28-SEALED | STATUS: SOVEREIGNLY SEALED | AUTHORITY: 888_JUDGE

🔗 CANONICAL LINKS (Source of Truth)

Live Services

GitHub Repositories

📋 CANONICAL DOCUMENTS (Architecture Reference)

🎯 SNAPSHOT OF TRUTH

What is arifosmcp?

arifosmcp is the implementation of the arifOS constitutional intelligence kernel — the actual code that enforces the 13 Floors, runs the 000-999 pipeline, and delivers the 11 mega-tools.

The Parent vs. This Document:

Core Function:

graph LR
    A["User Request"] --> B["MCP Protocol"]
    B --> C["Constitutional Filter<br/>(F1-F13)"]
    C --> D["Tool Execution"]
    D --> E["Audit Log"]
    
    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style C fill:#0f3460,color:#fff
    style D fill:#1a1a2e,color:#fff
    style E fill:#16213e,color:#fff

🏗️ ARCHITECTURE OVERVIEW

Entry Points

graph TB
    A["server.py<br/>Universal Entry"] --> B{"FastMCP Version?"}
    B -->|"2.x"| C["server_horizon.py<br/>Proxy Mode<br/>8 tools"]
    B -->|"3.x"| D["runtime/server.py<br/>Full Kernel<br/>11 tools"]
    
    style A fill:#1a1a2e,color:#fff
    style C fill:#16213e,color:#fff
    style D fill:#0f3460,color:#fff

Server Modes

🚦 LIVE MCP CONTRACT STATUS

🔧 TOOL INVENTORY (12 Mega-Tools)

Tool Reference Table

📝 TOOL SPECIFICATIONS

init_anchor (000_INIT)

Purpose: Initialize constitutional session.

async def init_anchor(
    actor_id: str,
    declared_name: str,
    mode: Literal["init", "seal", "status"] = "init",
    thermodynamic_budget: dict = None,
    architect_registry: dict = None
) -> dict

Returns:

{
    "session_id": str,               # UUID
    "omega_0": float,                # Baseline uncertainty ∈ [0.03, 0.05]
    "delta_s": float,                # Baseline entropy
    "telos_manifold": dict,          # Telos vector weights
    "godel_lock": dict,              # Gödel lock status
    "constitutional_context": str,    # AI system prompt
    "philosophy": str,                # Selected quote from atlas
    "vitality_index": float,         # Ψ score
    "verdict_range": str             # "000_SEAL" | "101-499" | "500-899" | "999_VOID"
}

architect_registry (000_INIT)

Purpose: Discover tools and constitutional constraints.

async def architect_registry() -> dict

Returns:

{
    "tools": [
        {
            "name": str,
            "band": str,
            "stage": int,
            "constitutional_constraints": ["F1", "F2", ...],
            "input_schema": dict,
            "output_schema": dict
        }
    ],
    "total_count": int,
    "catalog_hash": str               # SHA-256 integrity
}

physics_reality (111_SENSE)

Purpose: Ground queries in real-world data. Prevents hallucinations.

async def physics_reality(
    query: str,
    mode: Literal["time", "search", "reality_check"] = "search",
    time_data: dict = None
) -> dict

Constitutional Filter: F2 (Truth) — all factual claims require citation.

agi_mind (333_MIND)

Purpose: Constitutional reasoning with three-phase Ollama pipeline.

graph TB
    A["Query"] --> B["Phase 1: FAST<br/>Quick pattern match"]
    B --> C["Phase 2: REFLECT<br/>Deep reasoning"]
    C --> D["Phase 3: DECIDE<br/>Action selection"]
    
    B -->|"F4 Clarity<br/>ΔS ≤ 0"| E["Pass/Fail"]
    C -->|"F2 Truth<br/>F3 Tri-Witness"| E
    D -->|"Constitutional<br/>Prefix"| E
    
    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style C fill:#0f3460,color:#fff
    style D fill:#1a1a2e,color:#fff

async def agi_mind(
    query: str,
    context: dict,
    mode: Literal["think", "reflect", "decide"] = "think"
) -> dict

Three Phases:

Constitutional Prefix:

CONSTITUTIONAL FRAMEWORK (ΔΩΨ | ARIF):
- Δ CLARITY: Reduce entropy. ΔS ≤ 0.
- Ω HUMILITY: Stay in bounds. Ω ∈ [0.03, 0.05].
- Ψ VITALITY: Every action witnessed.

FLOORS ACTIVE: [F1-F13]

arifOS_kernel (444_ROUT)

Purpose: Primary conductor — orchestrates full 000→888 pipeline.

graph LR
    A["Query"] --> B["1. Parse Intent<br/>111_SENSE"]
    B --> C["2. Ground Reality<br/>physics_reality"]
    C --> D["3. Reason<br/>agi_mind"]
    D --> E["4. Route Action<br/>444_ROUT"]
    E --> F["5. Safety Critique<br/>asi_heart"]
    F --> G["6. Estimate Cost<br/>math_estimator"]
    G --> H["7. Issue Verdict<br/>apex_soul"]
    
    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style C fill:#0f3460,color:#fff
    style D fill:#1a1a2e,color:#fff
    style E fill:#16213e,color:#fff
    style F fill:#0f3460,color:#fff
    style G fill:#1a1a2e,color:#fff
    style H fill:#16213e,color:#fff

async def arifOS_kernel(
    query: str,
    tools: list[str],
    context: dict
) -> dict

asi_heart (666_HEART)

Purpose: Safety critique — F5 Peace², F9 Ethics, harm potential.

async def asi_heart(
    action_plan: dict
) -> dict

Returns:

{
    "peace_squared": float,          # Must be ≥ 1.0 (F5)
    "c_dark": float,                 # Must be < 0.30 (F9)
    "harm_potential": str,           # "NONE" | "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
    "f5_pass": bool,
    "f9_pass": bool,
    "recommendations": list[str]
}

math_estimator (777_OPS)

Purpose: Thermodynamic cost estimation.

async def math_estimator(
    operation: str,
    inputs: dict
) -> dict

Returns:

{
    "landauer_limit_pJ": float,       # Minimum thermodynamic cost
    "entropy_change": float,         # ΔS (must be ≤ 0 for F4)
    "coherence_score": float,         # System coherence [0, 1]
    "estimated_energy_J": float,      # Total energy estimate
    "shannon_entropy_bits": float     # Information entropy
}

apex_soul (888_JUDGE)

Purpose: Final constitutional judgment.

async def apex_soul(
    evidence: dict,
    context: dict
) -> dict

Returns:

{
    "verdict": str,                   # "000_SEAL" | "101-499" | "500-899" | "999_VOID"
    "floor_scores": {
        "F1": {"passed": bool, "score": float},
        "F2": {"passed": bool, "score": float},
        # ... F3-F13
    },
    "genius_index": float,            # G = A × P × X × E² (≥ 0.80)
    "vitality_index": float,           # Ψ (≥ 1.0 for healthy)
    "witness_cube": float,            # W³ (≥ 0.95)
    "override_available": bool         # 888_JUDGE can always override
}

vault_ledger (999_SEAL)

Purpose: Immutable audit storage with Merkle sealing.

async def vault_ledger(
    data: dict,
    tier: Literal["constitutional", "standard", "transient"] = "standard"
) -> dict

Tiers:

engineering_memory (555_MEM)

Purpose: Redis-backed session memory.

async def engineering_memory(
    key: str,
    operation: Literal["get", "set", "delete", "list"],
    value: any = None,
    ttl: int = 3600
) -> dict

code_engine (—)

Purpose: Constrained Python execution for tool actions.

async def code_engine(
    code: str,
    language: Literal["python", "javascript"] = "python",
    constraints: dict = None
) -> dict

Safety Constraints:

• No filesystem access
• No network access
• No subprocess creation
• Memory limit: 128MB
• Timeout: 30s

🌐 API ENDPOINTS

HTTP Endpoints

MCP Protocol Examples

# List tools
curl -X POST https://arifosmcp.arif-fazil.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Call init_anchor
curl -X POST https://arifosmcp.arif-fazil.com/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{
      "name":"init_anchor",
      "arguments":{
        "actor_id":"test",
        "declared_name":"TestAgent"
      }
    }
  }'

⚙️ CONFIGURATION

Environment Variables

Docker Compose

services:
  arifosmcp:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - OLLAMA_URL=http://ollama_engine:11434
      - REDIS_URL=redis://redis:6379/0
      - DATABASE_URL=postgresql://user:pass@postgres:5432/arifos_vault
      - QDRANT_URL=http://qdrant:6333
    ports:
      - "127.0.0.1:8080:8080"

📁 CODE ARCHITECTURE

Directory Structure

arifosmcp/
├── README.md                      # ← This file
├── server.py                      # Universal entry
├── server_horizon.py              # Horizon proxy (FastMCP 2.x)
├── pyproject.toml                 # Dependencies
├── requirements.txt               # Pip dependencies
│
├── runtime/
│   ├── server.py                  # Full kernel (FastMCP 3.x)
│   ├── philosophy.py              # 27-zone atlas
│   ├── init_anchor_hardened.py    # Session anchoring
│   ├── tools_hardened_dispatch.py # Tool routing
│   ├── tools_hardened_v2.py       # Mega-tools
│   ├── tools_internal.py          # Internal utils
│   └── thermo_estimator.py        # Thermodynamic math
│
├── core/
│   ├── governance_kernel.py       # Main orchestrator
│   ├── pipeline.py                 # Execution pipeline
│   └── organs/
│       ├── _1_agi.py             # Mind (333_MIND)
│       ├── _2_asi.py             # Heart (666_HEART)
│       └── _3_apex.py            # Soul (888_JUDGE)
│
├── intelligence/
│   └── tools/
│       ├── thermo_estimator.py   # Cost estimation
│       └── wisdom_quotes.py       # Quote integration
│
├── aaa_mcp/                       # FastMCP tool definitions
├── transport/                     # Protocol transport
├── shared/                        # Shared utilities
└── enforcement/                   # Constitutional enforcement

🛡️ CONSTITUTIONAL ENFORCEMENT

Floor Compliance Matrix

Kill Switch Conditions

graph RL
    A["KILL SWITCH"] --> B1["F1 Amanah = 0"]
    A --> B2["F9 C_dark ≥ 0.50"]
    A --> B3["F10 + F2 Violation"]
    A --> B4["Ψ < 0.20"]
    A --> B5["Human Override"]
    
    B1 -.->|VOID| K["999_SEAL<br/>HALT"]
    B2 -.->|VOID| K
    B3 -.->|VOID| K
    B4 -.->|VOID| K
    B5 -.->|VOID| K
    
    style A fill:#ff0000,color:#fff
    style K fill:#8b0000,color:#fff

KILL_SWITCH_CONDITIONS = [
    ("F1_AMANAH", lambda s: s["amanah"] == 0),
    ("F9_ETHICS", lambda s: s["c_dark"] >= 0.50),
    ("F10_CONSCIENCE", lambda s: s["f10_violation"] and s["f2_violation"]),
    ("PSI_COLLAPSE", lambda s: s["vitality_index"] < 0.20),
    ("HUMAN_OVERRIDE", lambda s: s.get("judge_override", False)),
]

🔬 IMPLEMENTATION DETAILS

Philosophy Selection Algorithm

# 1. Compute session coordinates: (S, G, Ω)
S = +1 if delta_s <= 0 else -1
G = g_score  # 0/0.5/1
Omega = f7_band  # High/Med/Low

# 2. Compute 3D Euclidean distance to each of 27 zones
distances = [
    euclidean((S, G, Omega), zone.coords)
    for zone in philosophy_atlas.zones
]

# 3. Select nearest zone's quote
nearest_zone = min(distances, key=lambda d: d.distance)

# 4. INIT/SEAL sessions: motto + Z01 (Humble Sovereign)
if session_type in ("init", "seal"):
    return "DITEMPA BUKAN DIBERI." + nearest_zone.quote

Goodhart Resistance

# Measure entropy reduction
S_before = shannon_entropy(user_state)
S_after = shannon_entropy(model_output)

if S_after > S_before:
    raise FLOOR_VIOLATION("F4_CLARITY")

Landauer Limit Check

LANDACKER_pJ_per_bit = 2.87  # at room temperature

bits_erased = estimate_bits_erased(operation)
cost_pJ = bits_erased * LANDACKER_pJ_per_bit

if cost_pJ > thermodynamic_budget:
    raise CONSTRAINT_VIOLATION("F8_ENERGY")

Explorer/Conservator Dual-Process

graph LR
    subgraph EXPLORER["EXPLORER"]
        E1["Proposes mutations"]
        E2["Searches aggressively"]
        E3["Optimizes capability"]
        E4["Score: G (Genius)"]
    end
    
    subgraph CONSERVATOR["CONSERVATOR"]
        C1["Protects stability"]
        C2["Rejects risky changes"]
        C3["Monitors drift"]
        C4["Score: Ψ (Vitality)"]
    end
    
    E1 -->|"TENSION"| EQ["EQUILIBRIUM"]
    C1 -->|"TENSION"| EQ
    
    style EXPLORER fill:#1a4d1a,color:#fff
    style CONSERVATOR fill:#4d1a1a,color:#fff
    style EQ fill:#1a1a2e,color:#fff

Both must agree for evolution to proceed.

🧪 TESTING

Constitutional Compliance Test

docker compose exec -T arifosmcp python3 /dev/stdin << 'PYEOF'
import sys
sys.path.insert(0, '/usr/src/app')

from arifosmcp.runtime.init_anchor_hardened import init_anchor_hardened
import asyncio

async def test():
    result = await init_anchor_hardened(
        mode='status',
        thermodynamic_budget={'enthalpy': 100, 'entropy': 50},
        architect_registry={'resources': [], 'agents': []}
    )
    print('philosophy:', result.get('philosophy')[:100] if result.get('philosophy') else None)
    print('telos_manifold:', result.get('telos_manifold'))
    print('godel_lock:', result.get('godel_lock'))
    print('constitutional_context present:', result.get('constitutional_context') is not None)

asyncio.run(test())
PYEOF

Health Check

curl -s https://arifosmcp.arif-fazil.com/health | python3 -m json.tool

📊 MONITORING

Prometheus Metrics

Grafana Dashboard

URL: https://monitor.arifosmcp.arif-fazil.com

Dashboards:

• Constitutional Health (F1-F13 compliance)
• Tool Usage Statistics
• Pipeline Latency
• Memory Usage

🔧 TROUBLESHOOTING

Issue: "Module file points to site-packages"

Symptom: import arifosmcp loads /usr/local/lib/python3.12/site-packages/

Cause: pip install in Dockerfile creates conflicting package

Fix: Rebuild image or ensure volume mounts are correct

Issue: "philosophy returns null"

Symptom: init_anchor returns null philosophy

Cause: Old site-packages version loaded

Fix: Rebuild container, clear Python cache

Issue: "OLLAMA connection failed"

Symptom: agi_mind returns connection error

Fix: docker compose restart ollama && docker compose logs --tail=20 ollama

📦 DEPENDENCIES

Core

Philosophy Atlas

🚀 DEPLOYMENT

Build

docker build --no-cache -t arifos/arifosmcp:latest -f Dockerfile .

Run

docker compose up -d arifosmcp

Rebuild (after code changes)

docker compose up -d --force-recreate --no-deps arifosmcp

Full Reforge

docker compose build --no-cache arifosmcp && docker compose up -d arifosmcp

📜 API REFERENCE SUMMARY

init_anchor

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "init_anchor",
    "arguments": {
      "actor_id": "string",
      "declared_name": "string",
      "mode": "init|seal|status"
    }
  }
}

Response Schema

{
  "session_id": "uuid",
  "omega_0": 0.03-0.05,
  "delta_s": "float",
  "telos_manifold": {},
  "godel_lock": {},
  "constitutional_context": "string",
  "philosophy": "string",
  "vitality_index": "float",
  "verdict_range": "000_SEAL|101-499|500-899|999_VOID"
}

📋 FOR AI AGENTS (AGENTS.md Reference)

All AI agents operating in this repository MUST follow the rules in ../AGENTS.md:

• RULE 1 DRY_RUN: Dry-run outputs labeled "Estimate Only / Simulated"
• RULE 2 DOMAIN_GATE: Cannot-compute domains return exact phrase
• RULE 3 VERDICT_SCOPE: Only DOMAIN_SEAL authorizes factual claims
• RULE 4 ANCHOR_VOID: init_anchor returns void → session BLOCKED

⚖️ Truth Hierarchy

The arifOS verdict system follows a strict Truth Hierarchy where higher-priority verdicts override lower ones:

Derived Verdicts (not primary):

• ALIVE — Session initialized, not yet grounded
• PROVISIONAL — Exploratory result, needs confirmation

🗺️ Tool Categories

arifOS tools are organized into 5 constitutional bands:

🗂️ Contract Truth Table

Legend: ✅ = mandatory floor for this tool

📡 Horizon vs VPS Exposure Matrix

⚠️ Known Misalignments and Limitations

1. apex_judge alias: The tool is canonically named apex_soul in code but exposed as apex_judge via MCP. This is a public alias documented here — do not rename canonical code without completing the full migration.

2. physics_reality field name: Uses input field instead of query — historical inconsistency from legacy API.

3. check_vital, audit_rules: Internal lifecycle tools in server_horizon.py bootstrap — NOT callable via MCP.

4. agi_mind nested verdicts: When agi_mind returns verdict: "SEAL" at top-level but coherence.verdict: "SABAR" inside, the worst verdict wins (truth before speed).

5. search_tool, vault_ledger, reality_compass: These "naked" tools return raw data without verdict wrapper. Wrap in RuntimeEnvelope with verdict_wrapper.forge_verdict() — empty results produce PARTIAL, not VOID.

6. VerdictCode vs Verdict: Two separate enum classes exist — VerdictCode (SEAL/SABAR/PARTIAL/VOID) for verdict_wrapper and Verdict (includes HOLD/ALIVE/PROVISIONAL) for stage contracts. Keep separate to avoid breaking existing code.

🛰️ MCP Call Schema Examples

init_anchor

{
  "tool": "init_anchor",
  "arguments": {
    "actor_id": "user-123",
    "declared_name": "Arif",
    "mode": "init"
  }
}

agi_mind (reason mode)

{
  "tool": "agi_mind",
  "arguments": {
    "mode": "reason",
    "query": "Why does entropy matter?",
    "constitutional_context": {
      "stage": "MIND_333",
      "floors_active": ["F2", "F4", "F7", "F8"]
    }
  }
}

vault_ledger (seal mode)

{
  "tool": "vault_ledger",
  "arguments": {
    "mode": "seal",
    "data": {
      "content": "Verified fact",
      "metadata": {"source": "arifOS"}
    }
  }
}

apex_soul (judge mode)

{
  "tool": "apex_soul",
  "arguments": {
    "mode": "judge",
    "action": "seal_vault",
    "stakes": "HIGH"
  }
}

🔐 Stability Tiers

🏛️ LICENSE

Runtime: AGPL-3.0 (must release modifications) Theory: CC0 (public domain)

Version: 2026.03.28-SEALED Maintainer: Muhammad Arif bin Fazil Constitutional Authority: 888_JUDGE

Ditempa Bukan Diberi — Forged, Not Given [ΔΩΨ | ARIF]

██╗      ██████╗ ███████╗████████╗    ███████╗███╗   ██╗██╗██╗  ██╗██╗██╗  ██╗██╗   ██╗
██║     ██╔══██╗██╔════╝╚══██╔══╝    ██╔════╝████╗  ██║██║╚██╗██╔╝██║██║  ██║╚██╗ ██╔╝
██║     ██║  ██║█████╗     ██║       █████╗  ██╔██╗ ██║██║ ╚███╔╝ ██║███████║ ╚████╔╝ 
██║     ██║  ██║██╔══╝     ██║       ██╔══╝  ██║╚██╗██║██║ ██╔██╗ ██║██╔══██║  ╚██╔╝  
███████╗╚█████╔╝███████╗   ██║       ███████╗██║ ╚████║██║██╔╝ ██╗██║██║  ██║   ██║   
╚══════╝ ╚═════╝ ╚══════╝   ╚═╝       ╚══════╝╚═╝  ╚══╝╚═╝╚═╝  ╚═╝╚═╝╚═╝  ╚═╝    ╚═╝