arifOS — The Authority Plane of the arifOS Federation

arifOS evaluates consequential AI actions against constitutional floors and returns an independent verdict before execution occurs.

When an AI agent proposes to write, delete, deploy, or spend, arifOS inserts a constitutional judgment step: the agent proposes, arifOS evaluates against F1–F13 floors, a verdict is reached, and only then does execution proceed. Every verdict is recorded with full evidence in an append-only ledger.

In a world where intelligence is abundant, authority becomes the scarce resource. arifOS exists to ensure that judgment remains independent from execution.

This is not an AI model. It is not an agent framework. It is a constitutional authority system — the layer between "agent wants to act" and "action is permitted."

What arifOS is not: not an AI model · not an agent framework · not an execution engine (A-FORGE executes) · not an attention plane (AAA compresses reality) · not a witness (arifFlow records) · not a substitute for authentication, sandboxing, or legal review.

Live: https://arifos.arif-fazil.com · MCP :8088 · sister organs GEOX · A-FORGE · AAA

The Problem

AI agents that act are also certifying their own actions. There is no independent authority evaluating proposals against safety, compliance, and policy constraints before execution occurs.

The Solution

  Agent proposes action
         │
         ▼
  ┌─────────────────┐
  │   arifOS Kernel  │  Evaluates against 13 constitutional floors
  │     (:8088)      │  Records evidence chain
  └────────┬────────┘
           │
    ┌──────┼──────┬──────────┐
    ▼      ▼      ▼          ▼
  SEAL    HOLD   SABAR     VOID
  (go)   (wait)  (patience) (blocked)
    │      │
    ▼      ▼
  Execute  Human
  via      reviews
  A-FORGE
    │
    ▼
  Receipt in VAULT999
  (append-only ledger)

The judge never executes. The executor never certifies.

Federation in One Line

arifOS decides. AAA routes. A-FORGE acts. VAULT999 witnesses.

Authority remains separated at every stage. No single component proposes, judges, executes, and witnesses the same action.

Quick Start

Requires Python 3.12+ (supported range: 3.12–3.14; see pyproject.toml).

Versioning: Two version schemes coexist. The kernel release (v2026.08.01) tracks the running service identity. The PyPI package (1!2026.9.1) uses epoch versioning (1!) to outrank legacy releases. They advance independently — the kernel release is the operational truth.

Install

pip install arifos

Install (Docker)

docker build -t arifos .
docker run -p 8088:8088 --env-file .env.docker arifos

Run the kernel

ARIF = Sovereign · arifOS = Law (Authority Plane) · AAA = Institution (Attention Plane) · A-FORGE = Hands (Execution Plane)

# Start the MCP server (console script; `arifos` is an equivalent alias)
arifos-mcp

# Equivalent module form
python -m arifosmcp.runtime

# Check health — the kernel defaults to port 8088
curl http://localhost:8088/health

Connect an MCP client

Point any MCP client at the Streamable HTTP endpoint:

http://localhost:8088/mcp

An illustrative tools/call for judgment:

// method: tools/call
{
  "name": "arif_judge",
  "arguments": {
    "candidate": "Write file /data/report.csv with production data",
    "action_tier": "standard"
  }
}
// → SEAL | HOLD | SABAR | VOID with evidence chain

Session Flow (agents start here)

The kernel requires session initialization before judgment. The canonical flow:

// Step 1: Initialize session — establishes actor identity and authority
{ "name": "arif_init", "arguments": { "actor_id": "my-agent", "requested_authority": "OBSERVE_ONLY" } }
// → session_id, session_token, floors bound

// Step 2: Judge a proposal — returns verdict + evidence chain
{ "name": "arif_judge", "arguments": { "candidate": "Deploy v2.1 to production", "action_tier": "standard" } }
// → SEAL | HOLD | SABAR | VOID with constitutional_chain_id

// Step 3: Seal (only after SEAL verdict) — records receipt in VAULT999
{ "name": "arif_seal", "arguments": { "payload": "Deployed v2.1", "constitutional_chain_id": "<from judge>" } }
// → receipt_id, hash chain link

Verb numbering: The kernel verbs follow a deliberate 000→999 progression: arif_init (000), arif_observe (111), arif_think (333), arif_route (444), arif_memory (555), arif_judge (666), arif_forge (777), arif_seal (999). Each number encodes the constitutional stage: ignition → sense → reason → route → recall → judgment → execution → sealing.

For a guided walkthrough, start with docs/START_HERE.md.

Core Concepts

Four Verdicts

13 Constitutional Floors (F1–F13)

Every proposal is evaluated against 13 non-compensatory policy constraints (F1–F13). Floors are never averaged or traded off — a failure propagates into the verdict (HOLD, SABAR, or VOID).

VAULT999 (Append-Only Audit Ledger)

Every verdict, evidence chain, and execution receipt is recorded in VAULT999 — a hash-chained, append-only JSONL ledger (live record count in the header manifest above, re-stamped by scripts/update_readme_sot.py). Designed for compliance auditing, forensic review, and governance proof. Chain verification tooling ships in scripts/verify_vault_chain.py.

Architecture

arifOS Federation — 4 Constitutional Planes

    ┌─────────────────────────────────────────────┐
    │          Authority Plane (arifOS :8088)      │
    │    Constitutional judgment · F1–F13 floors   │
    └──────────────────────┬──────────────────────┘
                           │
    ┌──────────────────────▼──────────────────────┐
    │          Attention Plane (AAA :3001)         │
    │    Reality compression · Routing · State     │
    └──────────────────────┬──────────────────────┘
                           │
    ┌──────────────────────▼──────────────────────┐
    │        Execution Plane (A-FORGE :7071/7072)  │
    │    Governed mutation · Leases · Receipts     │
    └──────────────────────┬──────────────────────┘
                           │
    ┌──────────────────────▼──────────────────────┐
    │     Witness Plane (VAULT999 + FRAME :18085)  │
    │    Append-only ledger · Drift detection      │
    └─────────────────────────────────────────────┘

arifOS Federation — 10 Organs

arifOS (:8088)     Constitutional judgment kernel
AAA (:3001)        Intelligence routing, state plane, skill catalog
A-FORGE (:7071/7072) Execution after authorization
GEOX (:8081)       Earth sciences domain evidence
WEALTH (:18082)    Capital and financial intelligence
WELL (:18083)      Human and machine vitality observation
arifFlow (:7073)   Metabolic ledger daemon (FQ monitoring, receipt ingestion)
FED (:7074)        Federation routing gateway (multi-provider LLM)
FRAME (:18085)     Independent observer, drift detection, evidence gathering
i-ARIF (:18095)    Seal B synthesis engine

ARIF vetoes. arifOS judges. AAA routes. A-FORGE executes. FRAME witnesses. FED routes.

arifOS is the kernel. The other organs are supporting infrastructure. GEOX is the primary reference implementation, demonstrating governance in high-consequence, uncertainty-heavy workflows. FRAME is the independent observer — its output is evidence, never a verdict.

MCP Interface

The kernel exposes 8 canonical MCP verbs over Streamable HTTP (protocol 2026-07-28, backward-compatible to 2024-11-05, 2025-03-26, 2025-11-25):

arif_forge is a governed dispatch verb: it routes authorized actions toward the execution organ (A-FORGE) and mutates only after a SEAL verdict. The kernel itself does not perform the underlying mutation. The judge never executes; the executor never certifies.

Verification Status

The header manifest is regenerated from the live kernel by scripts/update_readme_sot.py (run before release commits). Last stamp: last_verified above.

What Is Not Yet Proven

See SECURITY.md for the threat model, known gaps, and disclosure policy.

Who Is This For

Operators deploying AI agents in regulated environments who need an independent judgment layer between agent proposals and execution.

Developers building AI agent systems who want a policy decision point as a service.

Evaluators and security reviewers assessing AI governance frameworks.

Domain builders adapting governance to specific fields (geoscience, finance, healthcare).

Start here: docs/START_HERE.md

Founding Context

arifOS was built by Muhammad Arif bin Fazil, a senior exploration geoscientist who spent his career making decisions where observations are incomplete, interpretations are probabilistic, provenance matters, and irreversible action must be gated. He transferred that discipline into agent runtime governance.

The system is named after its founder and reflects a core belief: governance is a systems problem, not a model problem.

Development

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

# Install (light tier — kernel only)
pip install -e ".[light]"

# Run tests
python -m pytest tests/ -v

# Health check (all 10 federation surfaces)
make health

# Start the kernel
arifos-mcp   # or: python -m arifosmcp.runtime

See CODEOWNERS for sovereign ownership of automation surfaces. See CONTRIBUTING.md for contribution guidelines.

Project Structure

arifOS/
├── arifosmcp/          # Core kernel package
│   ├── abi/            # Capability registry and floor definitions
│   ├── constitution/   # Constitutional floor implementations
│   ├── kernel/         # Core judgment engine
│   └── VAULT999/       # VAULT999 ledger implementation
├── tests/              # Test suite (pytest — constitutional + integration)
├── scripts/            # Operational tooling (incl. update_readme_sot.py)
├── docs/               # Documentation
│   ├── START_HERE.md   # External reader entry point
│   └── ...
└── pyproject.toml      # Package metadata

Sister Repositories

Evidence & Trust

arifOS publishes verifiable evidence for its claims. Every public claim links to an artifact that can be independently regenerated.

See docs/evidence/ for the full claim registry and evidence index.

Honesty principle: We publish what passed, what failed, and what remains unknown. We do not claim maturity beyond our evidence.

Who Maintains This

One human, and the agents he directs.

I am a geologist, not a programmer. I did not write this codebase and I do not read it line by line. What I do is point at where the problem is — and the agents in my federation solve it, inside the constitution and the review gates I set, with the commit trail to show who ran what.

Read the commits if you want to check that claim: the author fields are agent handles, not aliases of mine. That is the deliberate shape of this project, not a detail being hidden. It also sets the honest expectation — the design and the judgment are mine, the implementation is theirs, and where the two disagree, the bug is mine to answer for.

Contributing

See CONTRIBUTING.md for guidelines.

Security

See SECURITY.md for threat model, known vulnerabilities, and disclosure policy.

License

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

When deployed over a network, the complete source code must be made available to all users interacting with the service, consistent with AGPL-3.0 terms.

Ditempa Bukan Diberi — Forged, Not Given.