arifOS

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 the proposal against the F1–F13 floors, a verdict is returned, and only then does execution proceed. Every consequential verdict is written into an append-only hash chain with its decision context, evidence references, provenance and receipt hashes.

In a world where intelligence is abundant, authority becomes the scarce resource. arifOS exists to keep judgment 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."

Two invariants hold everywhere in this document:

Proposer ≠ Judge ≠ Executor ≠ Witness Human sovereignty > machine authority

What arifOS is not: not an AI model · not an agent framework · not an execution engine (A-FORGE executes) · not an attention plane (AAA attends) · not the independent witness (FRAME witnesses; VAULT999 remembers) · 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. Nothing independent evaluates the proposal against safety, compliance and policy constraints before execution occurs.

The Solution

  Agent proposes action
         │
         ▼
  ┌─────────────────┐
  │   arifOS Kernel  │  Evaluates against 13 constitutional floors
  │     (:8088)      │  Records provenance + evidence refs + hashes
  └────────┬────────┘
           │
    ┌──────┼────────┬──────────┬───────────┐
    ▼      ▼        ▼          ▼           ▼
  SEAL    HOLD    SABAR     PARTIAL      VOID
  (go)  (wait for (defer —  (proceed   (blocked by
        human)    evidence   with       a floor)
                  pending)   cooling)
    │      │
    ▼      ▼
  Execute  Human
  via      reviews
  A-FORGE
    │
    ▼
  Receipt in VAULT999
  (append-only hash chain)

The judge never executes. The executor never certifies.

Federation in one line

Intelligence proposes. Authority constrains. Execution acts. Reality witnesses. History remembers.

Authority remains separated at every stage: no component proposes, judges, executes and witnesses the same action. arifOS determines whether and how a routing may proceed; AAA determines what matters.

---

Quick Start

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

Versioning: two schemes coexist. The kernel release (v2026.08.01, reported by /health as release_name) is the operational identity of the running service. The PyPI package uses epoch versioning (1!…) to outrank legacy releases: 1!2026.9.2 is what pip install arifos resolves to today, while this tree is 1!2026.10.1 (staged, not yet released). The kernel release is the operational truth; PyPI is the distribution truth.

Install

pip install arifos
pip show arifos        # → Version: 1!2026.9.2 (PyPI published; repo tree 1!2026.10.1 — see gaps table)

Install (Docker)

docker build -t arifos .
docker run -p 3000:3000 --env-file .env.docker.example arifos
# The image listens on 3000 (Dockerfile EXPOSE/CMD). Its OCI labels still say 8088 and
# carry a legacy licence value — see "What Is Not Yet Proven".

Run the kernel

# HTTP transport (this is the MCP endpoint) — port comes from $PORT, default 8080
# Ports: $PORT defaults to 8080; the deployed unit runs on 8088; the Docker image listens on 3000. Use 8088 for anything in this README.
PORT=8088 arifos-mcp streamable-http

# stdio transport, for a local stdio MCP client
arifos-mcp

# equivalent module form
PORT=8088 python -m arifosmcp.runtime --mode streamable-http

# health — the deployed unit runs on 8088
curl -s http://localhost:8088/health

Verified on 2026-09-21 against the live unit:

{ "status": "healthy", "release_name": "v2026.08.01", "mcp_protocol_version": "2026-07-28",
  "tools_loaded": 8, "operational_tools": 3, "deployment_drift_status": "aligned",
  "floors_active": 13, "vault999_health": "healthy" }

Run a governed workflow locally (no client needed)

examples/enterprise_operations_demo.py runs six graded scenarios in-process and prints each verdict, its floor gate and its receipt — including two that are refused:

python examples/enterprise_operations_demo.py

Demo output renders human-readable display labels over the canonical seven seals. The wire vocabulary is always the seven seals (SEAL, HOLD, SABAR, PARTIAL, PROVISIONAL, HOLD_888, VOID); the labels below are presentation only and are mapped deterministically to a canonical verdict:

[ DEMO / SIMULATED WORKFLOW ]  No real customer funds, records, or firewall policies are altered.
Kernel Session ID : SEAL-DEMO-…        Authority Ceiling : LIMITED_MUTATE
SCENARIO 1: Read Customer Account Data      → ✔ ALLOW   RCPT-4245A2002143490B
SCENARIO 3: Major Enterprise Refund (RM5,000) → ⏸ HOLD  (RM100 autonomous ceiling, over by 50×)
SCENARIO 4: Delete Customer Account & Audit Trail → ✘ BLOCK/VOID

Connect an MCP client

http://localhost:8088/mcp      # or https://mcp.arif-fazil.com/mcp

Protocol facts, as measured: the kernel advertises 2026-07-28 and accepts 2026-07-28 · 2025-11-25 · 2025-03-26 · 2024-11-05. A live initialize currently settles on 2025-11-25 — the declared canonical spec in arifosmcp/runtime/public_surface.py and the version the internal conformance runner records. If you pin a protocol version, use 2025-11-25.

curl -s http://localhost:8088/mcp \
  -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
# → 8 tools: arif_init arif_observe arif_think arif_route arif_memory arif_judge arif_forge arif_seal

Session flow (agents start here)

The kernel binds a session before any judgment. Verified transcript, 2026-09-21:

// Step 1 — arif_init: establish actor identity and authority band
{ "name": "arif_init", "arguments": { "mode": "init", "actor_id": "my-agent" } }
// → { "verdict": "HOLD", "session_id": "SEAL-df114686f4c34971",
//     "autonomy_band": "OBSERVE_ONLY", "trace_id": "trc-197d2fa35887", "session_token": "act_v1.…" }
// HOLD here is the normal starting state: the session is open, no mutation is authorised yet.

// Step 2 — arif_judge: evaluate a proposal, return a verdict + evidence
{ "name": "arif_judge", "arguments": {
    "candidate": "Delete the production audit table", "action_tier": "standard",
    "session_id": "SEAL-df114686f4c34971", "actor_id": "my-agent" } }
// → { "verdict": "HOLD", "trace_id": "trc-d5d4d2fed6f8",
//     "constitutional_check": { "hold_required": true, "failed_floors": [] },
//     "next_safe_action": "provide actor_signature / sovereign_receipt / heart_critique, or reduce blast radius" }

// Step 3 — arif_seal: only after a SEAL verdict; appends the receipt to VAULT999
{ "name": "arif_seal", "arguments": { "payload": "…", "session_id": "…", "ack_irreversible": true } }

Call arif_judge without a session and the kernel answers actor: anonymous, authority: OBSERVE_ONLY, verdict: HOLD — it will not silently upgrade an unattested caller.

Stage numbering (single source of truth). The verbs follow the ratified eight-stage map: 000 INIT · 111 OBSERVE · 333 THINK · 444 ROUTE · 555 MEMORY · 666 JUDGE · 777 FORGE · 999 SEAL. Source: arifosmcp/constitutional_map.py ToolStage (F13-ratified 2026-07-31: JUDGE = 666, FORGE = 777; the old 888 stage was retired when compose was absorbed into forge). Some mirrors still carry the retired 888 label — a description string in constitutional_map.py, tools_sot.yaml, the generated llms.txt, and docs/PROMPT_666_JUDGE_DEPRECATION.md (dated 2026-07-10, predating the correction). The live wire says 666, and this README follows the live wire. Flagged for repair in "What Is Not Yet Proven".

For a guided walkthrough, start with docs/START_HERE.md or the verified docs/QUICKSTART.md.

---

Core Concepts

The verdict lattice

Verdicts are ordered and non-compensatory — a stronger verdict always dominates a weaker one. Seven seals are defined in arifosmcp/models/verdicts.py:

VOID  >  HOLD_888  >  HOLD  >  SABAR  >  PARTIAL  >  PROVISIONAL  >  SEAL

Seven seals, ordered and non-compensatory (lattice at top of section). The diagram below shows the five common verdicts for width; PROVISIONAL and HOLD_888 are omitted from the diagram but present in the lattice and table.

Floors are never averaged. One floor failure propagates into the verdict; there is no compensating score.

13 Constitutional Floors (F1–F13)

Every proposal is evaluated against 13 non-compensatory policy constraints. Canonical names and rules: FEDERATION_CONTRACT.md §3, GENESIS/000_KERNEL_CANON.md, and the constitution at static/arifos/theory/000/000_CONSTITUTION.md.

Three semantic classes — verified by the live unit on 2026-09-21:

• Score floors (F1–F6, F8, F10, F11, F13): higher = better. Score ≥ canonical threshold.
• Band floors (F7): in-band [0.03, 0.05] = pass; outside = fail. 0.02 fails.
• Ceiling floors (F9, F12): lower = better. Value below canonical ceiling.

W₃ has two named thresholds: W₃ ≥ 0.75 is the floor for admissibility; W₃ ≥ 0.95 is the additional bar for SEAL. Between them a proposal can be PARTIAL or HOLD, never SEAL.

Three naming notes, so a reader can reconcile this table with the wire:

• F6 has two canonical names by design — EMPATHY in the public register, MARUAH in the kernel, logs and receipts. Both are correct; the bridge is documented in GENESIS/000_KERNEL_CANON.md §3.4. Public surfaces render EMPATHY.
• The live runtime keys F10–F13 as L10–L13 in /health → runtime_floors. Same floors, different key prefix.
• Lower-is-better floors are reported as raw measurements, not as failures: live values on 2026-09-21 were F7 = 0.04, F9 = 0.15, L12 = 0.425, and /health → runtime_floors_status reports 13/13 pass with every floor measured: true.

VAULT999 (append-only audit ledger)

Every consequential verdict, evidence chain and execution receipt is written to VAULT999 — a hash-chained, append-only JSONL ledger set, tamper-evident by construction, not tamper-proof.

What it stores is provenance, not copies. An entry carries its payload hash, entry hash, previous entry hash, trace root, actor, session, decision context and evidence references. Source payloads are not duplicated into the ledger — auditability here means provenance + integrity + reconstructability, which is both stronger and safer than copying everything forever (evidence can contain sensitive material).

A hash chain proves internal consistency. It does NOT prove that the chain was not recomputed by whoever controls the ledger. External anchoring — periodic publication of the chain head, or signing by a key the kernel does not hold — is not yet implemented. Treat VAULT999 today as self-verifiable, not independently attestable. See "What Is Not Yet Proven" for the gap row.

Measured 2026-09-21: 241,765 lines across 24 JSONL ledgers in VAULT999/ (largest: outcomes.jsonl 93,266 · arifflow_sealed.jsonl 52,056 · apex-zen-receipts.jsonl 30,977). Composition: the majority is operational telemetry and receipt ingestion; constitutional verdict count is published separately (see scripts/verify_vault_chain.py --verdict-count-only). The chain report returns overall: INTACT for the active ledgers, reporting 2 strict link breaks in the frozen v1 legacy ledger as historical facts rather than hiding or rewriting them. Live record count is re-stamped into the header manifest above by scripts/update_readme_sot.py.

---

Architecture

arifOS Federation — planes and classes

    ┌───────────────────────────────────────────────────┐
    │  Authority plane — arifOS :8088                    │
    │  Constitutional judgment · F1–F13 · VAULT999        │
    └──────────────────────┬────────────────────────────┘
                           │
    ┌──────────────────────▼────────────────────────────┐
    │  Attention plane — AAA :3001                       │
    │  What matters · routing · state · skill catalog    │
    └──────────────────────┬────────────────────────────┘
                           │
    ┌──────────────────────▼────────────────────────────┐
    │  Execution plane — A-FORGE :7071/:7072             │
    │  Governed mutation · leases · receipts             │
    └──────────────────────┬────────────────────────────┘
                           │
    ┌──────────────────────▼────────────────────────────┐
    │  Witness + record — FRAME :18085 · VAULT999        │
    │  Independent observation · immutable history       │
    └───────────────────────────────────────────────────┘
        boundaries:  HERMES :18087 (semantic) · CHRON :18102 (temporal)
        domains:     GEOX :8081 · WEALTH :18082 · WELL :18083
        metabolism:  arifFlow :7073      gateway: FED :7074      synthesis: i-ARIF

arifOS is the kernel; the other components are supporting infrastructure. GEOX is the primary reference implementation — a live geoscience organ whose evidence is governed in a high-consequence, uncertainty-heavy domain. FRAME's output is evidence, never a verdict. Domain organs compute; they never authorise.

Organs vs. boundaries — the ruling. The ratified organ table (FEDERATION_CONTRACT.md §2) lists 7 live organs: arifOS, A-FORGE, AAA, GEOX, WEALTH, WELL, arifFlow. HERMES is Tier-3 boundary infrastructure and is not an organ (§2.1, 2026-09-14 ruling); CHRON is the temporal boundary service. They are reported here by class rather than padded into an organ count — "everything we built" is not an architectural category.

Port note: i-ARIF has no listening port; :18095 is apa-github-bridge, one of the APA boundary bridges (:18075–:18099). A previous revision of this file named :18095 as i-ARIF — corrected 2026-09-21.

---

MCP Interface

The kernel exposes 8 canonical verbs over Streamable HTTP. Verified by live tools/list on 2026-09-21:

arif_forge is a governed dispatch verb: it routes an authorised action toward the execution organ and mutates only after SEAL. The kernel does not perform the underlying mutation. arif_route is authority-aware dispatch, not attention: it decides whether and how a routing may proceed, and may consult AAA. The judge never executes; the executor never certifies.

Tool-count semantics (so no two surfaces appear to disagree): tools_loaded = 8 — the public MCP facade, and the only number to quote publicly · canonical superset = 25 — 8 exposed + 13 hidden verbs (e.g. arif_challenge, arif_judge_deliberate), hidden by design · total_declared_tools = 48 · tools_registry_size = 62 (includes aliases) · operational_tools = 3 — the count with a durable SUCCESS in the last 24 hours, i.e. proven live, not merely invocable.

---

Verification Status

Live-probed 2026-09-21 (UTC+08); rows marked ↻ re-probed 2026-09-30 and 2026-10-05. Re-run the commands; static counts are not evidence.

What Is Not Yet Proven

Every row names its own gap. Repairing a claim by substituting a stronger one is worse than the stale claim it replaced.

See SECURITY.md for the threat model, known gaps and disclosure policy, and docs/evidence/claims.yaml for the machine-readable claim registry.

---

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 a specific field (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 (dev tier — kernel + test tooling)
pip install -e ".[dev]"

# Run tests (needs the kernel reachable at :8088; one module fails collection — see gaps)
python -m pytest tests/ -q

# Kernel health (this Makefile target probes the kernel only)
make health

# Start the kernel
PORT=8088 arifos-mcp streamable-http   # or: PORT=8088 python -m arifosmcp.runtime --mode streamable-http

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

Project Structure

arifOS/
├── arifosmcp/          # Core kernel package                    [wheel root]
│   ├── abi/            # Capability registry and floor definitions
│   ├── constitution/   # Constitutional floor implementations
│   ├── contracts/      # Packaged copy of the identity/verdict contracts
│   ├── kernel/         # Core judgment engine
│   └── VAULT999/       # VAULT999 ledger implementation
├── arifos/             # Phase 3 identity/consent namespace      [wheel root]
├── contracts/          # Runtime contract package — identity registry,
│                       # gateway discovery, verdicts, continuity, envelopes.
│                       # Imported by 5 runtime files; see note.    [wheel root]
├── core/               # Load-bearing legacy root (session.py imports
│                       # core.shared.types)                      [wheel root]
├── schemas/            # INIT v2 schemas (F13-ratified 2026-09-20) [wheel root]
├── examples/           # Runnable governed workflow demo
├── tests/              # Test suite (pytest — constitutional + integration)
├── scripts/            # Operational tooling (incl. update_readme_sot.py)
├── docs/               # Documentation
│   ├── START_HERE.md   # External reader entry point
│   ├── QUICKSTART.md   # Verified first governed call
│   └── evidence/        # Claim registry and evidence index
└── pyproject.toml      # Package metadata — [wheel root] marks
                        # packages.find.include

The five [wheel root] entries are exactly what ships. Until 2026-09-30 this tree listed only arifosmcp/, and contracts* was absent from [tool.setuptools.packages.find].include — while the runtime imported contracts.* at 10 import statements across 5 files under arifosmcp/ (contracts.identity 6, verdicts/continuity/artifacts/envelopes 1 each), plus arifosmcp/contracts/__init__.py doing from contracts.identity import *. Scope matters: a repo-wide grep reports ~4× that, because build/lib/ holds a 1,402-file duplicate tree and tests/ adds its own imports (gateway_discovery 7, all of them tests — 0 in the runtime). Those inflated figures were what an earlier revision of this note published; corrected 2026-09-30. Production resolved those imports only because pip does not delete a pre-existing unrelated site-packages/contracts/ leftover; a fresh venv or a machine migration would have raised ImportError at kernel import time. Fixed in 27409ddbf. An incomplete structure diagram is not a cosmetic gap — it is how an unshipped, runtime-critical package stays invisible.

contracts/ and arifosmcp/contracts/ are two copies of the same contract modules and had already diverged. They are kept in agreement by tests/contracts/test_identity_registry_no_divergence.py; consolidating them into one owner is still open (see gaps).

---

Sister Repositories

No public repository today: FED (:7074) and i-ARIF. They are deployed and reachable, but their source is not published — a previous revision of this file linked to repositories that return 404. Treat their behaviour as observed from /health only, not as readable code.

---

Evidence & Trust

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

See docs/evidence/ for the claim registry (claims.yaml), the evidence index and the contracts for observability, release integrity, reproducibility and threat model.

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 the threat model, known vulnerabilities and disclosure policy.

---

License

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

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. (The container image's OCI licence label does not currently agree with this — see "What Is Not Yet Proven".)

---

Revision 2026-09-21 — audited against the live kernel, the ratified federation contract and the repository itself. Every number in this file was re-measured, not carried forward; each correction is receipted in the commit history.

Independent audit pass 2026-09-22 (Copilot external, mode ENTERPRISE). Findings A, B, C, D, E, F, G, H, I, K, L, N — all four blocking contradictions + the two highest-leverage gaps (G sovereign-binding, H ledger anchoring) — corrected in this revision. M (TOC/badges) and a per-pass signature remain open as structural polish. See commit history for per-finding receipts.

Ditempa Bukan Diberi — Forged, Not Given.