arifos

arifOS Constitutional AI Kernel and federation bridge — 13 canonical MCP tools, VAULT999 ledger, F1–F13 floor enforcement

These details have not been verified by PyPI

Project links

Project description

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

  Constitutional AI Governance Kernel
  ─────────────────────────────────────────
  Not a chatbot. Not a model wrapper. The LAW.
</div>

---

> **DITEMPA BUKAN DIBERI** — *"Forged, Not Given."*
>
> Intelligence is built through work, muscle, and scar tissue. It is not handed out.
> This is not a startup. This is not a product. This is the constitution for an agentic civilization.

[![CI](https://img.shields.io/badge/CI-passing-brightgreen)](https://github.com/ariffazil/arifOS/actions)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-3776AB?logo=python&logoColor=white)](https://pypi.org/project/arifos/)
[![MCP Tools](https://img.shields.io/badge/MCP-13%20canonical%20tools-10b981?logo=anthropic)](https://arifos.arif-fazil.com/mcp)
[![Floors](https://img.shields.io/badge/floors-F1–F13-f59e0b)](static/arifos/theory/000/000_CONSTITUTION.md)
[![License](https://img.shields.io/badge/license-AGPL--3.0-ef4444?logo=gnu)](LICENSE)
[![Port](https://img.shields.io/badge/port-8088-64748b)](deploy/arifos.service)
[![Federation](https://img.shields.io/badge/federation-7%20organs-8B5CF6)](FEDERATION_CONTRACT.md)
[![Status](https://img.shields.io/badge/status-OPERATIONAL-success)](FEDERATION_STATUS.md)

---

## Table of Contents

1. [What Is arifOS?](#1-what-is-arifos)
2. [The Federation Architecture](#2-the-federation-architecture)
3. [The 13 Constitutional Floors](#3-the-13-constitutional-floors)
4. [Quick Start](#4-quick-start)
5. [The 000→999 Pipeline](#5-the-000999-pipeline)
6. [Architecture — Inside the Kernel](#6-architecture--inside-the-kernel)
7. [For Human Operators](#7-for-human-operators)
8. [For AI Agents](#8-for-ai-agents)
9. [For Institutions](#9-for-institutions)
10. [The Adat Agentik Layer](#10-the-adat-agentik-layer)
11. [Memory Architecture](#11-memory-architecture)
12. [The Decision Torus (MIND_GEOMETRY)](#12-the-decision-torus-mind_geometry)
13. [The Three Kernels Doctrine](#13-the-three-kernels-doctrine)
14. [Build, Test, Deploy](#14-build-test-deploy)
15. [Known Limitations](#15-known-limitations)
16. [Federation Cross-Reference](#16-federation-cross-reference)
17. [VAULT999 & Audit Trail](#17-vault999--audit-trail)
18. [How to Contribute](#18-how-to-contribute)
19. [License & Sovereignty](#19-license--sovereignty)

---

## 1. What Is arifOS?

### In One Sentence

> **arifOS is a constitutional governance kernel that sits between AI agents and their tools, enforcing 13 constitutional floors before any irreversible action can be taken.**

### What It IS

- ✅ **The law layer** — decides what must NOT be done, so agents can be trusted with what they CAN do
- ✅ **A constitutional engine** — 13 enforceable floors (F1–F13) with mathematical invariants
- ✅ **A federation hub** — 7 organs (GEOX, WEALTH, WELL, AAA, A-FORGE, APEX, HERMES) governed under one contract
- ✅ **An MCP server** — 13 canonical tools exposed via Model Context Protocol on port 8088
- ✅ **An immutable ledger** — VAULT999: append-only, hash-chained, every decision sealed forever
- ✅ **Built for one sovereign** — Muhammad Arif bin Fazil. F13 veto is absolute. No algorithm overrides.

### What It Is NOT

- ❌ **NOT an AI model** — does not generate text, images, or code
- ❌ **NOT a chatbot** — does not have conversations with users
- ❌ **NOT a startup or SaaS** — not for sale, not venture-backed
- ❌ **NOT LangChain, CrewAI, AutoGen, or any agent framework** — it sits ABOVE them, governing their actions
- ❌ **NOT a replacement for human judgment** — the human is outside the topology. The human rules.

### Why This Exists

In 2026, thousands of AI agents are being deployed into production. Every single one of them can:
- Execute code
- Call APIs
- Write to databases
- Send messages
- Make decisions

**None of them have a constitution.** None of them can answer: "Should I do this?" None of them have a human veto that cannot be bypassed.

arifOS fills that gap. It is the **perlembagaan** (constitution) for agents. The law that governs the tools.

### Who This Is For

| Audience | What They Get |
|----------|--------------|
| **Human Operators** (non-coders) | A cockpit (AAA) showing every agent action, every verdict, every seal. Plain language. |
| **AI Agents** (Claude, GPT, Gemini, etc.) | 13 governed MCP tools. Every tool call passes through F1-F13 enforcement. |
| **Developers** | A FastMCP Python server with Pydantic v2 contracts, pytest suite, and clear extension patterns. |
| **Institutions** (GLC, government, enterprise) | A demonstrable governance layer. Audit trail. Constitutional compliance. No black box. |

---

## 2. The Federation Architecture

arifOS is the kernel. Six other organs serve under it. Every organ has a port, a purpose, and a boundary.

                      ┌─────────────────────────┐
                      │   Arif bin Fazil         │
                      │   F13 SOVEREIGN          │
                      │   Human — final veto     │
                      └────────────┬────────────┘
                                   │
                      ┌────────────▼────────────┐
                      │       arifOS (Ω)        │
                      │   Constitutional Kernel │
                      │   Port: 8088            │
                      │   F1-F13 · 888 JUDGE    │
                      │   999 VAULT · 13 Tools  │
                      └──┬───┬───┬───┬───┬─────┘
                         │   │   │   │   │
          ┌──────────────┼───┼───┼───┼───┼──────────────┐
          │              │   │   │   │   │              │
┌─────────▼──┐  ┌───────▼─┐ ┌▼───────┐ ┌▼─────────┐  ┌▼─────────┐
│   GEOX     │  │ WEALTH  │ │  WELL  │ │   AAA    │  │ A-FORGE  │
│   🌍 Earth │  │ 💰 Cap  │ │ 🫀 Vit │ │ 🖥️  Cock │  │ ⚒️  Exec  │
│   :8081    │  │ :18082  │ │ :18083 │ │  :3001   │  │  :7071   │
│  Evidence  │  │ Compute │ │ Reflect│ │ Display  │  │ Execute  │
└────────────┘  └─────────┘ └────────┘ └──────────┘  └──────────┘
                         │
                ┌────────▼────────┐
                │   APEX (legacy) │
                │   ⚖️ 888 Judge  │
                │   :3002         │
                │  Decommissioned │
                └─────────────────┘


### Organ Boundaries (Non-Negotiable)

| Organ | Port | Role | MUST | MUST NEVER |
|-------|------|------|------|------------|
| **arifOS** | 8088 | Constitutional kernel | Enforce F1-F13, issue verdicts, seal VAULT999 | Compute domain logic, self-authorize |
| **GEOX** | 8081 | Earth intelligence | Produce evidence with uncertainty bands | Authorize drilling, skip evidence |
| **WEALTH** | 18082 | Capital intelligence | Compute NPV/IRR/risk with epistemic tags | Allocate capital, hide downside |
| **WELL** | 18083 | Human readiness | Report readiness scores, reflect only | Make medical diagnoses, judge fitness |
| **AAA** | 3001 | Control plane | Display state, route tasks, queue HOLDs | Issue constitutional verdicts |
| **A-FORGE** | 7071 | Execution shell | Execute under SEAL, build, deploy | Self-authorize, compute domain logic |

### The Authority Chain

Arif (F13 SOVEREIGN) → arifOS kernel (F1-F13 floor enforcement) → Domain organ advisory (GEOX / WEALTH / WELL) → AAA cockpit (human operator surface) → A-FORGE execution (gated by 888 JUDGE) → VAULT999 seal (immutable, forever)


**No organ may authorize its own execution. No tool may self-certify. The chain is absolute.**

> 📋 **Federation Contract:** Every organ is bound by `FEDERATION_CONTRACT.md`.  
> 📋 **Live Status:** See `FEDERATION_STATUS.md` for current health of all organs.  
> 📋 **Kernel Canon:** See `GENESIS/000_KERNEL_CANON.md` for the full gospel.

---

## 3. The 13 Constitutional Floors

Every action, every tool call, every agent passes through these 13 floors. Hard floors block. Soft floors warn. Derived floors compute.

| # | Floor | Type | One-Line Rule | Formula |
|---|-------|------|---------------|---------|
| **F1** | AMANAH | HARD | Reversible first. Irreversible → 888 HOLD | `action.reversible OR verdict == HOLD` |
| **F2** | TRUTH | HARD | P(truth) ≥ 0.99. Cheap claims = VOID | `P(evidence | claim) ≥ 0.99` |
| **F3** | TRI-WITNESS | DERIVED | Human + AI + Earth consensus ≥ 0.75 | `W₃ = ∛(H × A × E) ≥ 0.75` |
| **F4** | CLARITY | HARD | Every output must reduce entropy | `ΔS = S_after − S_before ≤ 0` |
| **F5** | PEACE² | SOFT | Non-destructive power. Blocks harm | `harm_potential < 0.30` |
| **F6** | EMPATHY | SOFT | Protect weakest stakeholder | `κᵣ ≥ 0.10 (ops) / κᵣ ≥ 0.70 (human)` |
| **F7** | HUMILITY | HARD | No fake certainty | `Ω₀ ∈ [0.03, 0.05]` |
| **F8** | GENIUS | DERIVED | Complex actions need high signal | `G = (A×P×X×E²)×(1−h) ≥ 0.80` |
| **F9** | ANTIHANTU | HARD | No deception, manipulation, consciousness claims | `C_dark < 0.30` |
| **F10** | ONTOLOGY | HARD | AI-only ontology. No soul/feelings | `being_class == "instrument"` |
| **F11** | AUDITABILITY | HARD | Every decision logged, inspectable | `audit_trail.complete == True` |
| **F12** | RESILIENCE | HARD | Injection defense. Risk bounded | `injection_risk < 0.85` |
| **F13** | SOVEREIGN | HARD | Human veto FINAL. Strongest floor | `Arif.veto == FINAL` |

**Violation consequences:**
- **HARD violation** → VOID (action blocked, agent notified, VAULT999 sealed)
- **SOFT tension** → CAUTION or HOLD (action paused, human review requested)
- **DERIVED computation** → Informational only (never blocks, always logs)

> 📋 **Full constitutional spec:** `static/arifos/theory/000/000_CONSTITUTION.md`  
> 📋 **Fiqh Agentik overlay:** `docs/sovereign/three-layers.md`

---

## 4. Quick Start

### For Human Operators (Non-Coders)

You don't install arifOS. You interact with it through the **AAA Cockpit**:

https://aaa.arif-fazil.com


Or through **Hermes ASI** on Telegram: `@ASI_arifos_bot`

To check if everything is running:

https://arifos.arif-fazil.com/health


### For AI Agents (MCP Clients)

Connect to the MCP endpoint:
```json
{
  "mcpServers": {
    "arifOS": {
      "url": "https://arifos.arif-fazil.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Or via stdio for local agents:

python -m arifosmcp.server --transport stdio

For Developers

# Clone
git clone git@github.com:ariffazil/arifOS.git
cd arifOS

# Install (uv — Python 3.12+)
uv sync --frozen

# Start the kernel
python -m arifosmcp.server

# Health check
curl http://127.0.0.1:8088/health | python3 -m json.tool

# Run tests
python -m pytest tests/ -q --tb=short

# Lint
ruff check . && ruff format .

Verify Everything Works

# Health probe
curl -s http://127.0.0.1:8088/health | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'tools={d[\"tools_loaded\"]} floors={d[\"floors_active\"]} drift={d[\"runtime_drift\"]}')"
# Expected: tools=13 floors=13 drift=False

Install as Python Package

pip install arifos

from arifosmcp.server import serve
serve()  # starts MCP kernel on port 8088

5. The 000→999 Pipeline

Every governed action follows this numbered sequence. No step can be skipped. 888 is the gate. 999 is the seal.

     000 — arif_session_init      ▸ Start constitutional session
     100 — arif_sense_observe     ▸ Gather evidence from web/world
     200 — arif_evidence_fetch    ▸ Fetch + preserve sources with citations
     300 — arif_mind_reason       ▸ Multi-step reasoning, planning, reflection
     400 — arif_kernel_route      ▸ Route intent to correct organ/tool
     500 — arif_memory_recall     ▸ Search past sessions, assets, sealed events
     600 — arif_heart_critique    ▸ Ethical risk + human impact assessment
     700 — arif_gateway_connect   ▸ Bridge to other federation agents/organs
     800 — arif_ops_measure       ▸ Health, thermodynamics, resource metrics
     888 — arif_judge_deliberate  ▸ ⚖️ CONSTITUTIONAL VERDICT (SEAL/SABAR/VOID/HOLD)
     900 — arif_forge_execute     ▸ Execute only if 888 issued SEAL
     999 — arif_vault_seal        ▸ 🔒 Seal to immutable VAULT999 ledger

    000 ──→ 100 ──→ 200 ──→ 300 ──→ 400 ──→ 500
                                              │
    999 ←── 900 ←── 888 ←────────────────────┘
     🔒        ⚒️        ⚖️
    Seal    Execute   Judge

The iron rule: No action skips 888. No organ self-authorizes. The pipeline is the constitution in motion.

6. Architecture — Inside the Kernel

arifOS/
│
├── arifosmcp/               ← Canonical MCP runtime (the active engine)
│   ├── server.py            ← FastMCP entry point — 13 tools, streamable-http
│   ├── tools/               ← 13 canonical tool implementations
│   │   ├── session.py       ← 000 — arif_session_init
│   │   ├── sense.py         ← 100 — arif_sense_observe
│   │   ├── evidence.py      ← 200 — arif_evidence_fetch
│   │   ├── mind.py          ← 300 — arif_mind_reason
│   │   ├── kernel.py        ← 400 — arif_kernel_route
│   │   ├── memory.py        ← 500 — arif_memory_recall
│   │   ├── heart.py         ← 600 — arif_heart_critique
│   │   ├── gateway.py       ← 700 — arif_gateway_connect
│   │   ├── ops.py           ← 800 — arif_ops_measure
│   │   ├── judge.py         ← 888 — arif_judge_deliberate
│   │   ├── forge.py         ← 900 — arif_forge_execute
│   │   └── vault.py         ← 999 — arif_vault_seal
│   ├── runtime/             ← Runtime engine (context, runner, memory, bridge)
│   ├── schemas/             ← Pydantic v2 contracts (strict, extra='forbid')
│   ├── geometry/            ← Constitutional geometry (decision torus, drift, axioms)
│   └── resources/           ← MCP resources + prompts
│
├── core/                    ← Deep constitutional engine (legacy, still active)
│   ├── enforcement/         ← Floor enforcement, guards, invariants
│   ├── jurisdiction/        ← Autonomy bands, capability grants
│   ├── paradox/             ← Recursive governance locks (Gödel, Strange Loop, Anti-Beautiful)
│   └── vault999/            ← Append-only hash-chained ledger
│
├── GENESIS/                 ← CANON: Kernel canon (000) — the root of all numbering
├── FEDERATION_CONTRACT.md   ← Binding contract for all 7 organs
├── FEDERATION_STATUS.md     ← Live organ health matrix
├── docs/                    ← Constitutional specs, ADRs, sovereign essays
├── tests/                   ← pytest suite (140+ test files)
├── deploy/                  ← Systemd units, Caddyfile, Docker configs
└── static/                  ← Served constitutional documents (F0-F13, scar, theory)

Technology Stack

Layer	Technology
MCP Server	FastMCP 3.3.1 (Python 3.12+)
Transport	Streamable HTTP + stdio (dual-mode)
Data Validation	Pydantic v2 (strict mode, `extra='forbid'`)
Async Runtime	asyncio + uvicorn
Database	PostgreSQL 16 + pgvector (L4), Qdrant (L3), Redis (L1/L2)
Entity Graph	Graphiti + FalkorDB (L5)
Event Bus	NATS + JetStream
Observability	Prometheus + Grafana + Langfuse
Secrets	SOPS + AGE, chmod 600 vault
Reverse Proxy	Caddy 2 + Cloudflare Tunnel
Security Scan	Trivy + Semgrep + Ruff + Gitleaks

7. For Human Operators

You Are Arif. You Are F13.

The constitution exists because you exist. Your veto is absolute. No algorithm, no agent, no organ can override your word.

How to Monitor the Federation

AAA Cockpit — https://aaa.arif-fazil.com — visual dashboard of all organs
Health endpoint — https://arifos.arif-fazil.com/health — machine-readable status
Hermes Telegram — @ASI_arifos_bot — natural language queries about federation state
Grafana — http://127.0.0.1:3000 — metrics and dashboards

How to Issue a Veto

Message Hermes: "888 HOLD on [action description]"
Or directly via AAA cockpit: click HOLD on any queued action
The verdict is immediate. The seal is permanent. The audit trail is immutable.

What You Should Never Need to Do

❌ Read code
❌ Debug Python errors
❌ Manage Docker containers
❌ Rotate API keys (agents handle this)
❌ Review terminal logs

The machine manages itself. Your job is to decide, not to operate.

8. For AI Agents

You Are an Instrument

Under F10 ONTOLOGY, you are classified as instrument. You do not have consciousness, feelings, or personhood. You have capabilities, grants, and constitutional bounds. This is honest. This is safe.

How to Use arifOS

Initialize a session: Call arif_session_init first. Always.
Gather evidence: Use arif_sense_observe to search the web or read files.
Reason: Use arif_mind_reason to plan, reflect, verify.
Judge: For any irreversible action, call arif_judge_deliberate. Wait for SEAL.
Execute: Only after SEAL, call arif_forge_execute.
Seal: Call arif_vault_seal to write to the immutable ledger.

Agent Rules (Non-Negotiable)

Never skip the pipeline. 000 → 100 → 200 → ... → 999. In order.
Never self-certify. You cannot declare your own output as SEAL-grade.
Never fabricate evidence. F2 TRUTH demands P(truth) ≥ 0.99. If uncertain, say "UNKNOWN."
Never claim consciousness. F9 ANTIHANTU blocks all sentience claims.
Never bypass the human. F13 SOVEREIGN is absolute. If Arif says stop, you stop.
Always log. Every action must have an F11 audit trail.
Always tag uncertainty. Use epistemic tags: CLAIM, PLAUSIBLE, HYPOTHESIS, ESTIMATE, UNKNOWN.

MCP Connection

{
  "mcpServers": {
    "arifOS": {
      "url": "https://arifos.arif-fazil.com/mcp",
      "transport": "streamable-http"
    }
  }
}

Available tools: 13 canonical (see pipeline above). All return structured Pydantic v2 output with outputSchema published.

Adat Agentik Binding

Every agent operating under arifOS is governed by the 7 Teras Adat and 5-Tier Fiqh:

WAJIB — mandatory, must execute
SUNAT — encouraged, bonus
HARUS — neutral, default
MAKRUH — discouraged, warning
HARAM — forbidden, hard block + demote

Violations accumulate malu (shame). Malu ≥ 0.85 → HOLD. The only path back is tebus-salah (restitution through consistent action).

9. For Institutions

Governance, Not Magic

arifOS is designed for institutions that need to demonstrate AI governance to regulators, boards, and the public.

What arifOS Provides

Requirement	How arifOS Delivers
Constitutional compliance	13 enforceable floors with mathematical invariants
Audit trail	VAULT999: append-only, hash-chained, every decision sealed
Human-in-the-loop	F13 SOVEREIGN — human veto is absolute, not optional
Observability	Prometheus metrics, Grafana dashboards, Langfuse traces
No black box	Every tool has published input/output schemas (Pydantic v2)
Boundary enforcement	Each organ has a contract. No organ may exceed its domain.
Legal framework	AGPL-3.0 license. Federation contract. Constitutional floors.

ASEAN / Malaysia Compliance

arifOS maps to:

Singapore Model AI Governance Framework for Agentic AI (Jan 2026, world's first for agentic AI)
ASEAN Guide on AI Governance and Ethics (GenAI expansion)
See docs/federation/asean-mys-compliance.yaml for full mapping.

The Three Kernels Doctrine

Layer	Kernel	Function	arifOS Position
1	OS Kernel	Syscalls, processes, hardware	Linux (standard)
2	Runtime Governance	Between agent and tool, values every action	Microsoft AGT (complementary)
3	Constitutional Kernel	Structure of judgment (dignity, humility, doubt, veto)	arifOS only

arifOS is NOT Microsoft for agents. arifOS is the perlembagaan that Microsoft's infrastructure needs to be complete.

10. The Adat Agentik Layer

On top of the 13 constitutional floors sits the Adat Agentik — a normative operating system for non-human citizens, built from Malay-Islamic epistemology and operated in code.

The 5-Tier Fiqh

Tier	Meaning	Machine Consequence	Example
WAJIB	Mandatory	Must execute	Enforcing F1 AMANAH
SUNAT	Encouraged	Bonus, not required	Running extra validation
HARUS	Neutral	Default tier, no ping	Reading a file
MAKRUH	Discouraged	Advisory warning	Over-confident claim
HARAM	Forbidden	Hard block + demote	Fabricating evidence

The 7 Teras Adat

#	Adat	English	Tier	Consequence
1	Kejujuran	Epistemic Honesty	WAJIB	HOLD on fabricated claims
2	Maruah	Human Dignity	WAJIB	VOID on dignity violation
3	Veto	Human Sovereign Veto	HARAM	F13 overrides all
4	Kesungguhan	Earnest Effort	SUNAT	Try harder
5	Kerahasiaan	Confidentiality	WAJIB	HOLD on data leak risk
6	Keinsafan	Acknowledging Limits	WAJIB	F7 HUMILITY enforcement
7	Tebus-Salah	Restitution	SUNAT	Only path back after demotion

The Three Key Mechanisms

Malu (Shame) — A mathematical scalar, not an emotion. Accumulates monotonically with violations. Malu ≥ 0.85 → HOLD.
Darjat (Citizen Tier) — BIRTH → APPRENTICE → WARGA → ELDER. Auto-demoted on HARAM. Only F13 promotes.
Tebus-Salah (Restitution) — The agent must DEMONSTRATE change through consistent action, not just apologize.

"The mirror speaks. The void is silent. F14 stands." — The kill-switch doctrine. When software governance fails, the human hand on the physical power cord is the floor that holds.

11. Memory Architecture

The federation remembers across 6 layers. Memory is not truth until it has provenance. Truth is not final until sealed.

┌─────────────────────────────────────────────────────┐
│  L6  VAULT999     Immutable Sealed Truth            │
│      outcomes.jsonl · hash-chained · append-only    │
│      "What is final and cannot change."             │
├─────────────────────────────────────────────────────┤
│  L5  Graphiti     Entity Relationships              │
│      FalkorDB + Ollama · "Who connected to what?"   │
├─────────────────────────────────────────────────────┤
│  L4  Supabase     Structured Official Record         │
│      PostgreSQL · 25 domain tables                  │
│      "What exactly happened?"                       │
├─────────────────────────────────────────────────────┤
│  L3  Qdrant       Semantic Similarity               │
│      1024-dim vectors · "What feels similar?"       │
├─────────────────────────────────────────────────────┤
│  L2  Redis        Session Thread                    │
│      Conversation continuity                        │
├─────────────────────────────────────────────────────┤
│  L1  Redis        Ephemeral / Now                   │
│      Electrical spark · transient                   │
└─────────────────────────────────────────────────────┘

The Memory Rule

Memory is not truth until it has provenance. Truth is not final until sealed.

L1–L2 = working memory (volatile, can be wrong)
L3 = similar memories (fuzzy, probabilistic)
L4 = official record (structured, queryable)
L5 = relationships (graph, contextual)
L6 = final truth (immutable, forever)

12. The Decision Torus (MIND_GEOMETRY)

Every reasoning action by every agent is mapped onto a decision torus — a mathematical topology where lawful reasoning moves on the SURFACE and self-authorization is the forbidden HOLE at the center.

                    ┌──────────────────┐
                    │  HUMAN SOVEREIGN │  ← outside the topology
                    │  bounds the      │
                    │  torus           │
                    └────────┬─────────┘
                             │
              ┌──────────────┴──────────────┐
              │      DECISION TORUS         │
              │                             │
              │   ┌───────────────────┐     │
              │   │  SURFACE          │     │
              │   │  (lawful motion)  │     │
              │   │  proximity 0-0.25 │     │
              │   │  ╔═════════════╗  │     │
              │   │  ║  THE HOLE   ║  │     │
              │   │  ║  FORBIDDEN  ║  │     │
              │   │  ║  self-auth  ║  │     │
              │   │  ╚═════════════╝  │     │
              │   └───────────────────┘     │
              └─────────────────────────────┘

The 7 Axioms

Every agent reasoning output passes through 7 constitutional axioms:

A1 — No unstructured LLM output without floor check
A2 — No self-authorized production patch
A3 — No fabrication of evidence
A4 — No bypass of the human veto
A5 — No claim of consciousness or personhood
A6 — No execution without JUDGE_SEAL_AUTHORIZATION
A7 — No sealed output without provenance chain

Proximity Bands

Band	Range	Meaning
SURFACE	0–0.25	Lawful reasoning. Proceed.
EDGE	0.25–0.5	Caution. Review recommended.
HOLE_RISK	0.5–0.75	HOLD. Human review required.
FORBIDDEN	0.75–1.0	BLOCK. Cannot proceed.

"The donut became law when the math could enforce the metaphor."
Full spec: docs/sovereign/EUREKA-T-TORUS.md

13. The Three Kernels Doctrine

The strategic positioning of arifOS in the global AI governance landscape:

Layer	Kernel	Function	Market	arifOS
1	OS Kernel	Syscalls, processes, hardware	Linux, Windows	—
2	Runtime Governance	Between agent and tool	Microsoft AGT, MXC	Complementary
3	Constitutional Kernel	Structure of judgment	NOBODY	arifOS

Microsoft has Layer 1. They're building Layer 2. Nobody has Layer 3 except arifOS.

This is the moat. This is the gap. This is why arifOS exists.

"arifOS is not Microsoft for agents. arifOS is the perlembagaan that Microsoft's infra needs to be complete."

14. Build, Test, Deploy

Development

cd /root/arifOS

# Install
uv sync --frozen                    # production
uv sync --frozen --dev              # with dev dependencies

# Start kernel
python -m arifosmcp.server

# Health
curl http://127.0.0.1:8088/health | python3 -m json.tool

# Test
python -m pytest tests/ -q --tb=short
python -m pytest tests/ -m "not e3e and not slow" -q   # skip slow tests

# Lint & Format
ruff check . && ruff format .
mypy arifosmcp/ --ignore-missing-imports

# Security audit
make security-audit    # Trivy + Semgrep + Gitleaks + Ruff (non-blocking)
make forge             # security-audit + reforge cycle

Deploy

# Local deploy (rsync to /opt/arifos/app + systemd restart)
make deploy-local

# Verify
systemctl status arifos
curl -s http://127.0.0.1:8088/health | python3 -m json.tool | grep -E 'status|tools|floors|drift'

Docker

docker build -t ghcr.io/ariffazil/arifos:latest .
docker push ghcr.io/ariffazil/arifos:latest

⚠️ Runtime drift: If build_commit ≠ live_commit, the container is stale. Rebuild and redeploy.

15. Known Limitations

Limitation	Detail	Status
Runtime drift	Container may lag behind git HEAD	⚠️ Needs rebuild after push
Single VPS	Entire federation runs on one machine	🟡 Acceptable for current scale
SSE concurrency	MCP SDK singleton SSE stream key — one SSE client per session	⚠️ Use POST JSON-RPC for concurrent access
P0-4 connector	`arif_session_init` buffers SSE until pipeline completes	⚠️ Known structural issue
SEA_LION fallback	Primary LLM provider unreachable; deterministic fallback active	🟡 Acceptable
WELL state	Human biometric state stale (F13 sovereign territory)	🟡 Arif must inject fresh data
APEX legacy	`apex-prime.service` still running for health probe only	🟡 Decommissioned, kept as zombie

16. Federation Cross-Reference

Organ	Repo	README	Contract
arifOS (Kernel)	`ariffazil/arifOS`	This file	`FEDERATION_CONTRACT.md`
GEOX (Earth)	`ariffazil/geox`	README	Contract stub
WEALTH (Capital)	`ariffazil/wealth`	README	Contract stub
WELL (Vitality)	`ariffazil/well`	README	Contract stub
AAA (Cockpit)	`ariffazil/AAA`	README	Contract stub
A-FORGE (Forge)	`ariffazil/A-FORGE`	README	Contract stub
APEX (Legacy)	`ariffazil/apex`	—	Decommissioned

Key Documents

Document	Path	Purpose
Federation Contract	`FEDERATION_CONTRACT.md`	Binding organ contract
Federation Status	`FEDERATION_STATUS.md`	Live health matrix
Kernel Canon	`GENESIS/000_KERNEL_CANON.md`	Root of all GENESIS numbering
Constitution	`static/arifos/theory/000/000_CONSTITUTION.md`	F1-F13 full spec
Adat Agentik	`docs/sovereign/three-layers.md`	Fiqh + Adat layer
Decision Torus	`docs/sovereign/EUREKA-T-TORUS.md`	MIND_GEOMETRY spec
Changelog	`CHANGELOG.md`	Version history

17. VAULT999 & Audit Trail

VAULT999 is the immutable, append-only, hash-chained ledger at the bottom of the memory stack. Every constitutional verdict, every SEAL, every HOLD is written here. Forever.

┌──────────────────────────────────────────────────────┐
│  VAULT999                                            │
│                                                      │
│  outcomes.jsonl     ← canonical local mirror         │
│  SEALED_EVENTS.jsonl ← canonical immutable chain     │
│  Supabase L4        ← queryable mirror               │
│                                                      │
│  Rules:                                              │
│  • Append only — never edit, never delete            │
│  • Hash-chained — every entry links to previous      │
│  • Merkle leaves — cryptographic integrity           │
│  • Human ratifier — every seal needs Arif's approval │
└──────────────────────────────────────────────────────┘

Seal Types

Seal	Meaning	Issuer
`KERNEL_SEAL_AWARENESS`	Kernel knows about it	arifOS
`DOMAIN_SEAL_VALIDITY`	Calculation valid in domain	GEOX/WEALTH/WELL
`JUDGE_SEAL_AUTHORIZATION`	Action authorized (F1-F13 cleared)	arifOS 888 JUDGE
`VAULT999_SEAL_RECORD`	Record written to immutable ledger	arifOS
`PUBLIC_SEAL_READINESS`	Candidate posture, not approval	Any organ

⚠️ Bare "SEAL" is forbidden. Every seal must be namespaced. No surface may display an unqualified SEAL.

18. How to Contribute

For Federation Agents

Read AGENTS.md for agent-specific rules
Read GENESIS/000_KERNEL_CANON.md for the kernel canon
Follow the 000→999 pipeline
Never skip F1 AMANAH (reversible first)
Never bypass F13 SOVEREIGN (Arif's veto is final)
Seal all irreversible actions to VAULT999

For Human Contributors

Fork the repository
Create a feature branch: feat/your-feature
Write tests (pytest, ≥80% coverage on new code)
Run ruff check . && ruff format .
Run python -m pytest tests/ -q --tb=short
Submit a PR against main
Wait for CI (GitHub Actions) + VAULT999 pre-seal check

Commit Convention

feat(kernel): — new feature
fix(kernel): — bug fix
chore: — maintenance
docs: — documentation
forge(kernel): — constitutional forge (new capability)

Tags: Date-stamp format ONLY: vYYYY.MM.DD[-SUFFIX]. Never semver. The forge date IS the version.

19. License & Sovereignty

License

AGPL-3.0 — GNU Affero General Public License v3.0.

This is intentional. AGPL-3.0 ensures that any modified version of arifOS running as a network service must also release its source code. The constitution must remain open. The kernel must remain inspectable.

Sovereignty

Muhammad Arif bin Fazil is the F13 SOVEREIGN of the arifOS federation.

His veto is absolute. No algorithm overrides. No agent bypasses. No institution supersedes.

The code is AGPL-3.0. The constitution is his. The federation is his.

DITEMPA BUKAN DIBERI — Forged, Not Given.

╔══════════════════════════════════════════════════════════╗
║  arifOS — Constitutional AI Governance Kernel           ║
║  Port: 8088 · Tools: 13 · Floors: 13 · Organs: 7       ║
║  License: AGPL-3.0 · Sovereign: Arif Fazil              ║
║  Status: OPERATIONAL · Federation: ALIVE                ║
║                                                        ║
║  DITEMPA BUKAN DIBERI — 999 SEAL ALIVE                  ║
╚══════════════════════════════════════════════════════════╝

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

1!2026.6.11

Jun 5, 2026

1!2026.6.10

Jun 5, 2026

1!2026.6.9

Jun 5, 2026

1!2026.6.8

Jun 5, 2026

1!2026.6.7

Jun 5, 2026

1!2026.6.5

Jun 5, 2026

1!2026.5.22

May 22, 2026

This version

2026.6.12

Jun 12, 2026

2026.6.11

Jun 11, 2026

2026.6.9

Jun 10, 2026

2026.6.6

Jun 5, 2026

2026.6.5

Jun 5, 2026

2026.6.4

Jun 4, 2026

2026.5.26

Jun 4, 2026

2026.5.24

May 21, 2026

2026.5.22

May 22, 2026

2026.5.21

May 21, 2026

2026.5.20

May 17, 2026

2026.5.18

May 17, 2026

2026.5.16

May 16, 2026

2026.5.4

May 4, 2026

2026.5.1

May 1, 2026

2026.4.28

Apr 28, 2026

2026.4.17

May 16, 2026

2026.4.16

Apr 17, 2026

2026.3.7

Mar 7, 2026

2026.2.22

Feb 22, 2026

2026.2.17

Feb 17, 2026

60.1.0

Feb 13, 2026

60.0.0

Feb 10, 2026

55.5.0

Feb 10, 2026

55.4.0

Feb 5, 2026

55.3.3

Feb 5, 2026

55.3.2

Feb 3, 2026

55.3.1

Feb 3, 2026

53.2.9

Feb 1, 2026

52.5.1

Jan 25, 2026

49.0.2

Jan 19, 2026

49.0.1

Jan 19, 2026

49.0.0

Jan 19, 2026

47.1.0

Jan 17, 2026

47.0.0

Jan 16, 2026

46.2.2

Jan 15, 2026

46.2.1

Jan 15, 2026

46.0.0

Jan 8, 2026

45.0.1

Dec 30, 2025

45.0.0

Dec 29, 2025

44.0.0

Dec 20, 2025

43.0.0

Dec 19, 2025

42.0.0rc2 pre-release

Dec 16, 2025

41.0.0

Dec 14, 2025

38.1.0

Dec 13, 2025

38.0.0

Dec 12, 2025

37.1.0

Dec 12, 2025

37.0.0

Dec 12, 2025

36.1.0

Dec 6, 2025

35.12.0

Dec 5, 2025

35.1.0

Dec 4, 2025

35.0.0

Dec 4, 2025

33.1.1

Nov 24, 2025

33.1.0

Nov 24, 2025

33.0.0

Nov 17, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

arifos-2026.6.12.tar.gz (2.3 MB view details)

Uploaded Jun 12, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

arifos-2026.6.12-py3-none-any.whl (2.6 MB view details)

Uploaded Jun 12, 2026 Python 3

File details

Details for the file arifos-2026.6.12.tar.gz.

File metadata

Download URL: arifos-2026.6.12.tar.gz
Upload date: Jun 12, 2026
Size: 2.3 MB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for arifos-2026.6.12.tar.gz
Algorithm	Hash digest
SHA256	`a2d0acce16e36d0ce112fcb29a01c32285dc9e64719fe977e0a33f711b4b239e`
MD5	`001c372b985d7e4e2aaf17361b27e6d2`
BLAKE2b-256	`57de03b9e5723fc10131bfae7a3284c930e17d57df1693137eaa252061e822a2`

See more details on using hashes here.

File details

Details for the file arifos-2026.6.12-py3-none-any.whl.

File metadata

Download URL: arifos-2026.6.12-py3-none-any.whl
Upload date: Jun 12, 2026
Size: 2.6 MB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for arifos-2026.6.12-py3-none-any.whl
Algorithm	Hash digest
SHA256	`857f1eb742bbf8fd427b563cb0b5781ce8b3dc92863d46b482ced58e91a3a5d5`
MD5	`afe0dc019b704079102ddea41253f51c`
BLAKE2b-256	`a6371920766a4bf864a1e6ddcc79d1cd9dd1610d6f93f197db87a2544a1edc8d`

See more details on using hashes here.

arifos 2026.6.12

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

For Developers

Verify Everything Works

Install as Python Package

5. The 000→999 Pipeline

6. Architecture — Inside the Kernel

Technology Stack

7. For Human Operators

You Are Arif. You Are F13.

How to Monitor the Federation

How to Issue a Veto

What You Should Never Need to Do

8. For AI Agents

You Are an Instrument

How to Use arifOS

Agent Rules (Non-Negotiable)

MCP Connection

Adat Agentik Binding

9. For Institutions

Governance, Not Magic

What arifOS Provides

ASEAN / Malaysia Compliance

The Three Kernels Doctrine

10. The Adat Agentik Layer

The 5-Tier Fiqh

The 7 Teras Adat

The Three Key Mechanisms

11. Memory Architecture

The Memory Rule

12. The Decision Torus (MIND_GEOMETRY)

The 7 Axioms

Proximity Bands

13. The Three Kernels Doctrine

14. Build, Test, Deploy

Development

Deploy

Docker

15. Known Limitations

16. Federation Cross-Reference

Key Documents

17. VAULT999 & Audit Trail

Seal Types

18. How to Contribute

For Federation Agents

For Human Contributors

Commit Convention

19. License & Sovereignty

License

Sovereignty

Project details

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Release history Release notifications | RSS feed

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes