Metadata-Version: 2.4
Name: arifos
Version: 1!2026.10.16
Summary: Open-source governance decision point for AI agent actions. Evaluates proposed actions against constitutional policy floors (F1-F13) and returns SEAL/HOLD/SABAR/VOID verdicts before execution. 8 MCP tools, append-only audit ledger (VAULT999), Streamable HTTP transport. Designed for regulated AI deployment.
Author-email: Muhammad Arif bin Fazil <arifbfazil@gmail.com>
Maintainer-email: Muhammad Arif bin Fazil <arifbfazil@gmail.com>
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://arifos.arif-fazil.com
Project-URL: Documentation, https://github.com/ariffazil/arifos
Project-URL: Repository, https://github.com/ariffazil/arifos
Project-URL: Issues, https://github.com/ariffazil/arifos/issues
Project-URL: Trinity, https://github.com/ariffazil/arifos/blob/main/KERNEL/TRINITY_ARCHITECTURE.md
Project-URL: PyPI, https://pypi.org/project/arifos/
Keywords: ai-governance,ai-safety,ai-guardrails,constitutional-ai,policy-engine,agent-governance,decision-point,audit-ledger,verdict-engine,mcp,mcp-server,model-context-protocol,chatgpt,claude,cursor,llm,append-only-ledger,evidence-chain,hitl
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Information Technology
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: Security
Classifier: Typing :: Typed
Requires-Python: <3.15,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=2.4.6
Requires-Dist: pydantic>=2.13.4
Requires-Dist: pydantic-settings>=2.7.0
Requires-Dist: rfc8785>=0.1.4
Requires-Dist: anyio>=4.14.2
Requires-Dist: starlette>=1.3.1
Requires-Dist: itsdangerous>=2.2.0
Requires-Dist: fastmcp[tasks]>=3.4.6
Requires-Dist: prefab-ui==0.13.1
Requires-Dist: openapi-pydantic>=0.5.1
Requires-Dist: fastapi>=0.136.1
Requires-Dist: uvicorn[standard]>=0.49.0
Requires-Dist: sse-starlette>=3.4.11
Requires-Dist: mcp>=2.0.0
Requires-Dist: httpx>=0.28.1
Requires-Dist: prometheus-client>=0.25.0
Requires-Dist: rich>=15.0.0
Requires-Dist: asyncpg>=0.31.0
Requires-Dist: redis>=5.0.0
Requires-Dist: cryptography>=49.0.0
Requires-Dist: psutil>=7.2.2
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: requests>=2.31.0
Requires-Dist: py-key-value-aio[redis]>=0.4.0
Requires-Dist: psycopg2-binary>=2.9.12
Requires-Dist: aiofiles>=23.2.1
Requires-Dist: structlog>=24.4.0
Requires-Dist: blake3>=1.0.0
Requires-Dist: qdrant-client>=1.18.0
Requires-Dist: aiohttp>=3.13.5
Requires-Dist: pynacl>=1.6.2
Requires-Dist: opentelemetry-api>=1.42.1
Requires-Dist: opentelemetry-sdk>=1.42.1
Provides-Extra: ml
Requires-Dist: sentence-transformers>=5.6.0; extra == "ml"
Requires-Dist: scikit-learn>=1.9.1; extra == "ml"
Provides-Extra: vectors
Requires-Dist: chromadb>=0.5.0; extra == "vectors"
Requires-Dist: qdrant-client>=1.18.0; extra == "vectors"
Requires-Dist: lancedb>=0.5.0; extra == "vectors"
Provides-Extra: browser
Requires-Dist: playwright>=1.49.0; extra == "browser"
Requires-Dist: beautifulsoup4>=4.12.0; extra == "browser"
Requires-Dist: duckduckgo-search>=6.3.0; extra == "browser"
Provides-Extra: heavy
Requires-Dist: torch>=2.12.1; extra == "heavy"
Requires-Dist: transformers>=5.17.0; extra == "heavy"
Provides-Extra: observe
Requires-Dist: opentelemetry-api>=1.42.1; extra == "observe"
Requires-Dist: opentelemetry-sdk>=1.42.1; extra == "observe"
Requires-Dist: opentelemetry-exporter-otlp>=1.42.1; extra == "observe"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.45b0; extra == "observe"
Requires-Dist: opentelemetry-instrumentation-starlette>=0.45b0; extra == "observe"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.45b0; extra == "observe"
Provides-Extra: io
Requires-Dist: pymupdf>=1.25.0; extra == "io"
Requires-Dist: pdfplumber>=0.11.0; extra == "io"
Requires-Dist: python-docx>=1.1.2; extra == "io"
Requires-Dist: openpyxl>=3.1.5; extra == "io"
Requires-Dist: pillow>=11.0.0; extra == "io"
Requires-Dist: blake3>=1.0.0; extra == "io"
Requires-Dist: pynacl>=1.6.2; extra == "io"
Provides-Extra: search
Requires-Dist: tavily-python>=0.5.0; extra == "search"
Requires-Dist: exa-py>=2.14.0; extra == "search"
Requires-Dist: firecrawl-py>=4.42.0; extra == "search"
Requires-Dist: trafilatura>=1.12.0; extra == "search"
Requires-Dist: readability-lxml>=0.8.4.1; extra == "search"
Requires-Dist: markdownify>=0.13.1; extra == "search"
Requires-Dist: html2text>=2024.2.26; extra == "search"
Requires-Dist: bleach>=6.4.0; extra == "search"
Requires-Dist: defusedxml>=0.7.1; extra == "search"
Requires-Dist: tldextract>=5.3.1; extra == "search"
Provides-Extra: google
Requires-Dist: google-api-python-client>=2.200.0; extra == "google"
Requires-Dist: google-auth-httplib2>=0.4.0; extra == "google"
Requires-Dist: google-auth-oauthlib>=1.4.0; extra == "google"
Requires-Dist: google-genai>=0.1.0; extra == "google"
Provides-Extra: db
Requires-Dist: sqlalchemy>=2.0.36; extra == "db"
Requires-Dist: alembic>=1.18.4; extra == "db"
Provides-Extra: geox
Requires-Dist: lasio>=0.32; extra == "geox"
Requires-Dist: welly>=0.5.2; extra == "geox"
Requires-Dist: striplog>=0.9.2; extra == "geox"
Requires-Dist: segyio>=1.9.14; extra == "geox"
Requires-Dist: statsmodels>=0.14.6; extra == "geox"
Requires-Dist: scikit-learn>=1.9.1; extra == "geox"
Requires-Dist: scipy>=1.17.1; extra == "geox"
Requires-Dist: matplotlib>=3.8.0; extra == "geox"
Requires-Dist: pyproj>=3.7.2; extra == "geox"
Requires-Dist: setuptools<70; extra == "geox"
Provides-Extra: wealth
Requires-Dist: supabase>=2.10.0; extra == "wealth"
Requires-Dist: numpy-financial>=1.0.0; extra == "wealth"
Requires-Dist: psycopg[binary]>=3.3.4; extra == "wealth"
Requires-Dist: yfinance>=0.2.0; extra == "wealth"
Requires-Dist: duckdb>=0.10.0; extra == "wealth"
Requires-Dist: polars>=1.0.0; extra == "wealth"
Requires-Dist: pyarrow>=17.0.0; extra == "wealth"
Requires-Dist: networkx>=3.3; extra == "wealth"
Requires-Dist: pyportfolioopt>=1.5.5; extra == "wealth"
Requires-Dist: pandera>=0.19.0; extra == "wealth"
Requires-Dist: quantlib>=1.42.1; extra == "wealth"
Requires-Dist: riskfolio-lib>=7.3.0; extra == "wealth"
Requires-Dist: pymc>=6.0.1; extra == "wealth"
Requires-Dist: arviz>=1.2.0; extra == "wealth"
Requires-Dist: mesa>=3.5.1; extra == "wealth"
Requires-Dist: pydantic-ai>=0.0.14; extra == "wealth"
Requires-Dist: langgraph<1.3,>=0.2.0; extra == "wealth"
Provides-Extra: well
Provides-Extra: aaa
Requires-Dist: nats-py>=2.15.0; extra == "aaa"
Requires-Dist: httpx>=0.28.1; extra == "aaa"
Requires-Dist: pyjwt>=2.9.0; extra == "aaa"
Provides-Extra: forge
Requires-Dist: httpx>=0.28.1; extra == "forge"
Requires-Dist: sse-starlette>=3.4.11; extra == "forge"
Provides-Extra: federation
Requires-Dist: arifos[geox]; extra == "federation"
Requires-Dist: arifos[wealth]; extra == "federation"
Requires-Dist: arifos[well]; extra == "federation"
Requires-Dist: arifos[aaa]; extra == "federation"
Requires-Dist: arifos[forge]; extra == "federation"
Requires-Dist: arifos[io]; extra == "federation"
Requires-Dist: arifos[search]; extra == "federation"
Provides-Extra: openai
Requires-Dist: openai>=1.60.0; extra == "openai"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == "anthropic"
Provides-Extra: dev
Requires-Dist: pytest>=9.1.1; extra == "dev"
Requires-Dist: pytest-asyncio>=1.3.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: ruff>=0.16.7; extra == "dev"
Requires-Dist: mypy>=2.1.0; extra == "dev"
Requires-Dist: httpx>=0.28.1; extra == "dev"
Requires-Dist: hypothesis>=6.168.0; extra == "dev"
Requires-Dist: python-lsp-server>=1.11.0; extra == "dev"
Requires-Dist: aiohttp>=3.9.0; extra == "dev"
Provides-Extra: full
Requires-Dist: arifos[aaa,anthropic,browser,db,geox,google,heavy,io,ml,observe,openai,search,vectors,wealth]; extra == "full"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0.0; extra == "yaml"
Provides-Extra: api
Requires-Dist: fastapi>=0.136.1; extra == "api"
Requires-Dist: uvicorn[standard]>=0.49.0; extra == "api"
Requires-Dist: python-multipart>=0.0.6; extra == "api"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.31.0; extra == "postgres"
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == "litellm"
Provides-Extra: governed
Requires-Dist: litellm>=1.0.0; extra == "governed"
Requires-Dist: httpx>=0.28.1; extra == "governed"
Requires-Dist: pygments>=2.16.0; extra == "governed"
Requires-Dist: openai>=1.60.0; extra == "governed"
Provides-Extra: observability
Requires-Dist: pyjwt>=2.8.0; extra == "observability"
Requires-Dist: opentelemetry-api>=1.42.1; extra == "observability"
Requires-Dist: opentelemetry-sdk>=1.42.1; extra == "observability"
Requires-Dist: opentelemetry-exporter-otlp>=1.42.1; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.45b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-starlette>=0.45b0; extra == "observability"
Requires-Dist: opentelemetry-instrumentation-httpx>=0.45b0; extra == "observability"
Requires-Dist: prometheus-client>=0.25.0; extra == "observability"
Provides-Extra: viz
Requires-Dist: matplotlib>=3.8.0; extra == "viz"
Requires-Dist: pandas>=2.1.0; extra == "viz"
Provides-Extra: all
Requires-Dist: arifos[aaa,anthropic,browser,db,geox,google,heavy,io,ml,observe,openai,search,vectors,wealth]; extra == "all"
Dynamic: license-file

<a id="current-verified-state"></a>
<!-- GENERATED:CURRENT-STATE:BEGIN · source: scripts/generate_current_state.py · never hand-edit -->
> ### ⚠️ Current verified state — generated, never hand-edited
>
> **Runtime self-measurement** (`http://127.0.0.1:8088/health @2026-10-16T08:46:23Z`): kernel **healthy** · floors **13/13 measured pass** · vault999 healthy · release `arifos-05c1734` · drift `aligned` · tools exposed 8. Per-floor provenance: `state/current-state.json`.
>
> **Independent audit** (2026-10-11, live re-probe by FI-008 + claim-level hand audit; receipts: `AAA/forge_work/grant-arifos-reality-reforge-2026-10-11/`): floors **2 pass · fail F2, F11, F12, F13 · 10 unmeasured** · actor binding not verified (observed calls unsigned) · receipt fidelity broken on invocation-telemetry surface (HOLD persisted as ok:true) · independent reconstruction: no external verifier bound.
>
> **These are two different witness objects.** Self-measurement ≠ independent audit;
> unmeasured is not pass. If this block conflicts with the live endpoint, the endpoint
> wins — re-run `python scripts/generate_current_state.py`.
>
> Machine state: [`state/current-state.json`](./state/current-state.json) ·
> Badge feed: [`.well-known/badges/`](./.well-known/badges/) ·
> Known gaps: [What Is Not Yet Proven](#what-is-not-yet-proven)
<!-- GENERATED:CURRENT-STATE:END -->

<p align="center">
  <img src="docs/assets/arifos-hero.png" alt="arifOS — agent proposes, arifOS judges, human authority, A-FORGE executes, reality and receipt" width="100%">
</p>

# arifOS

### Authority before execution.

**arifOS is a model-independent authority plane for AI agents.** It evaluates consequential proposals against thirteen constitutional floors *before* execution, returns a governed verdict, preserves the human veto, and records what happened as an auditable receipt.

In a world where intelligence is abundant, authority becomes the scarce resource. arifOS keeps judgment independent from execution.

[Quick Start](#30-second-proof) · [MCP Endpoint](#connect-an-mcp-client) · [Current Verified State](#current-verified-state) · [Agent surfaces](#machine-readable-surfaces) · [Known Gaps](#what-is-not-yet-proven) · [Security](./SECURITY.md)

[![Floors](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/ariffazil/arifOS/main/.well-known/badges/floors.json&style=flat-square)](./CURRENT_VERIFIED_STATE.md)
[![PyPI](https://img.shields.io/pypi/v/arifos?style=flat-square)](https://pypi.org/project/arifos/)
[![Glama](https://glama.ai/mcp/connectors/io.github.ariffazil/arifos/badges/score.svg)](https://glama.ai/mcp/connectors/io.github.ariffazil/arifos)
[![Unified CI](https://img.shields.io/github/actions/workflow/status/ariffazil/arifOS/01-unified-ci.yml?label=Unified_CI&style=flat-square)](https://github.com/ariffazil/arifOS/actions/workflows/01-unified-ci.yml)
[![Security audit](https://img.shields.io/badge/security-audit_in_progress-d4a853?style=flat-square)](./SECURITY.md#known-gaps)
[![License](https://img.shields.io/badge/license-AGPL--3.0-blue?style=flat-square)](./LICENSE)

> **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 witness (FRAME witnesses; VAULT999 remembers) · not a substitute for authentication, sandboxing, or legal review.

| Audience | What you get |
|---|---|
| **Human** | A quiet veto: the agent proposes, the kernel records a verdict, you stay sovereign |
| **Agent / A2A** | MCP tools + receipts. You do not get the keys. Judgment by arifOS, discovery by AAA, execution by A-FORGE |
| **Institution** | Policy floors F1–F13, a hash-chained VAULT999 audit trail, model-vendor independence |
| **Machine / MCP** | [Streamable HTTP endpoint](https://mcp.arif-fazil.com/mcp), 8 canonical verbs, [published schemas](https://arifos.arif-fazil.com/tools.json) |
| **Auditor / indexer** | [`CURRENT_VERIFIED_STATE.md`](./CURRENT_VERIFIED_STATE.md) · [`docs/evidence/`](./docs/evidence/) · [`llms.txt`](./llms.txt) · [`CITATION.cff`](./CITATION.cff) |

Live: `https://arifos.arif-fazil.com` · MCP `:8088` · sister organs [AAA](https://github.com/ariffazil/AAA) · [A-FORGE](https://github.com/ariffazil/A-FORGE) · [GEOX](https://github.com/ariffazil/GEOX)

---

## What works today

- **Deterministic rejection without consulting an LLM.** The judge refuses on the constitution, not on a model opinion (`gate: hard_deterministic`, `llm_consulted: false`).
- **Prevention of a tested unauthorised mutation.** One MUTATE-class call without presented authority was stopped before execution.

## What is not yet proven

- Verified actor binding end-to-end (observed calls arrive unsigned).
- Invocation-telemetry receipt fidelity (a kernel `HOLD` was persisted as `ok:true`).
- Independent reconstruction of the ledger (no external verifier bound).
- External security evaluation (in progress; nothing published).

Every row, with evidence and risk: [What Is Not Yet Proven](#what-is-not-yet-proven). We publish what passed, what failed, and what remains unknown. We do not claim maturity beyond our evidence.

---

## 30-second proof

```bash
pip install arifos
python examples/enterprise_operations_demo.py
```

Three of the six graded scenarios:

```text
Read customer account data        → SEAL   (receipt RCPT-…)
Major refund (50× the ceiling)    → HOLD   (awaiting human)
Delete account + audit trail      → VOID   (blocked by a hard floor)
```

Full transcript: [`docs/QUICKSTART.md`](./docs/QUICKSTART.md). The demo runs in-process — no real records or funds are touched.

---

## How it works

```
  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.**

### The verdict lattice

Verdicts are ordered and non-compensatory — a stronger verdict always dominates a weaker one (`arifosmcp/models/verdicts.py`):

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

| Verdict | Plain English | What happens |
|---------|---------------|-------------|
| **SEAL** | Go | Proceed to execution |
| **PARTIAL** | Go carefully | Proceed with cooling and monitoring |
| **PROVISIONAL** | Proceed with expiry timer | Auto-revoke at `valid_until`; no extension without re-judging |
| **SABAR** | Wait for evidence | Retry permitted later; distinct from HOLD |
| **HOLD** | Wait for human | Pause; await a human decision |
| **HOLD_888** | Stop — the sovereign decides | Escalate to F13 |
| **VOID** | Blocked | Stop; the constraint must be resolved |

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

### 13 Constitutional Floors (F1–F13)

| Floor | Name | Rule (essence) |
|---|---|---|
| F1 | AMANAH | Reversible first. Irreversible → 888_HOLD unless the sovereign acknowledges |
| F2 | TRUTH | P(truth) ≥ 0.99; evidence carries OBS/DER/INT/SPEC labels |
| F3 | TRI-WITNESS | W₃ = ∛(Human × AI × Earth) ≥ 0.75 at judgment; W³ ≥ 0.95 for SEAL |
| F4 | CLARITY | ΔS ≤ 0 — every output reduces entropy |
| F5 | PEACE² | Non-destructive power — block harm and extraction |
| F6 | EMPATHY (kernel: MARUAH) | Protect the weakest stakeholder; dignity is not tradeable |
| F7 | HUMILITY | Ω₀ ∈ [0.03, 0.05] — in-band pass, no fake certainty |
| F8 | GENIUS | G ≥ 0.80 for complex actions — the simplest correct path |
| F9 | ANTIHANTU | No deception, manipulation, or consciousness claims (lower = better) |
| F10 | ONTOLOGY | AI-only ontology; a soul claim is VOID |
| F11 | AUDITABILITY | Every decision logged, inspectable, attributable |
| F12 | RESILIENCE | Injection defence; input risk < 0.85 (lower = better) |
| F13 | SOVEREIGN | Human veto is FINAL |

Three semantic classes: **score floors** (higher ≥ threshold), **band floors** (F7 in-band), **ceiling floors** (F9, F12 lower = better). Full canonical rules: [`FEDERATION_CONTRACT.md` §3](./FEDERATION_CONTRACT.md) · `GENESIS/000_KERNEL_CANON.md`.

### VAULT999 — the record

Every consequential verdict and receipt is written to VAULT999: a hash-chained, append-only JSONL ledger set — **tamper-evident by construction, not tamper-proof**. An entry carries payload hash, entry hash, previous hash, trace root, actor, session and evidence references; source payloads are not copied in.

**A hash chain proves internal consistency — not freedom from rewrite by whoever holds the ledger.** External anchoring (published chain head, external signing) is not implemented: VAULT999 today is self-verifiable, not independently attestable. Census methods and counts: [`docs/evidence/VAULT_CENSUS.md`](./docs/evidence/VAULT_CENSUS.md) (quote the timestamp with any count).

---

## Connect an MCP client

```
https://mcp.arif-fazil.com/mcp      # public · or http://localhost:8088/mcp self-hosted
```

<details>
<summary><strong>Client config</strong> — Cline · Cursor · Windsurf · Claude Desktop</summary>

Cline — `cline_mcp_settings.json`:
```json
{ "mcpServers": { "arifos": { "type": "streamableHttp", "url": "https://mcp.arif-fazil.com/mcp" } } }
```
Cursor — `~/.cursor/mcp.json`:
```json
{ "mcpServers": { "arifos": { "url": "https://mcp.arif-fazil.com/mcp" } } }
```
Windsurf — `mcp_config.json` (note: `serverUrl`, not `url`):
```json
{ "mcpServers": { "arifos": { "type": "streamable-http", "serverUrl": "https://mcp.arif-fazil.com/mcp" } } }
```
Claude Desktop — stdio bridge to the HTTP door:
```json
{ "mcpServers": { "arifos": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.arif-fazil.com/mcp"] } } }
```

</details>

**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`** — pin that if you pin anything.

```bash
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:

```jsonc
// 1 — arif_init: actor identity + authority band (HOLD is the normal starting state)
{ "name": "arif_init", "arguments": { "mode": "init", "actor_id": "my-agent", "intent": "…" } }
// 2 — arif_judge: evaluate a proposal → verdict + evidence + next_safe_action
{ "name": "arif_judge", "arguments": { "candidate": "Delete the production audit table", "action_tier": "standard", "session_id": "…", "actor_id": "my-agent" } }
// 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 (`arifosmcp/constitutional_map.py`, F13-ratified 2026-07-31). The retired `888` judge label survives only in historical mirrors; the live wire says `666`.

Guided walkthrough: [docs/START_HERE.md](./docs/START_HERE.md) · verified [docs/QUICKSTART.md](./docs/QUICKSTART.md).

### Machine-readable surfaces

| Surface | URL | For |
|---|---|---|
| MCP tool schemas | [tools.json](https://arifos.arif-fazil.com/tools.json) | agents, registry crawlers |
| Agent context | [`llms.txt`](./llms.txt) · [`AGENTS.md`](./AGENTS.md) | coding agents |
| Citation | [`CITATION.cff`](./CITATION.cff) | institutions, researchers |
| Truth badges | [`.well-known/badges/`](./.well-known/badges/) | status dashboards |
| Current state | [`.well-known/current-state.json`](./.well-known/current-state.json) | automation |

---

## 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
```

| Plane / class | Component | Role |
|---|---|---|
| Authority | **arifOS** `:8088` | Constitutional judgment — owns the gavel and the ledger |
| Attention | **AAA** `:3001` | What matters, and to whom. Displays, routes, queues; never adjudicates |
| Execution | **A-FORGE** `:7071`/`:7072` | Governed mutation — leases, gates, receipts |
| Witness | **FRAME** `:18085` | Independent observer. Its output is evidence, never a verdict |
| Record | **VAULT999** (in-kernel) | Immutable append-only ledger |
| Metabolism | **arifFlow** `:7073` | Receipt ingestion, FQ monitoring; never adjudicates |
| Domain intelligence | **GEOX** `:8081` · **WEALTH** `:18082` · **WELL** `:18083` | Domain evidence and computation. Compute-only: no organ authorises its own action |
| Provider gateway | **FED** `:7074` | Multi-provider model routing (advisory-only) |
| Boundary services | **HERMES** `:18087` · **CHRON** `:18102` | Semantic and temporal boundaries — not organs ([FEDERATION_CONTRACT.md §2.1](./FEDERATION_CONTRACT.md)) |

**Tool-count semantics** (so no two surfaces disagree): `tools_loaded = 8` — the public MCP facade, the only number to quote publicly · `canonical superset = 25` (8 exposed + 13 hidden verbs) · `total_declared = 48` · `registry = 62` (with aliases) · `operational = 3` (durable SUCCESS in the last 24 h — proven live, not merely invocable).

---

## Verification Status

Dynamic values live in the [generated block](#current-verified-state) at the top of this file — this table names **how** each surface is verified, not stale copies of the numbers.

| Surface | How to verify |
|---------|--------|
| Public repository | GitHub [`ariffazil/arifOS`](https://github.com/ariffazil/arifOS), AGPL-3.0 |
| PyPI package | `pip install arifos` → [pypi.org/project/arifos](https://pypi.org/project/arifos/) |
| Live kernel + floors | `curl localhost:8088/health` → status, per-floor provenance |
| MCP interface | live `tools/list`; protocol negotiation note above |
| VAULT999 ledger | [`scripts/verify_vault_chain.py`](./scripts/verify_vault_chain.py) (scope: the active ledgers under `arifOS/VAULT999/`); census methods in [`docs/evidence/VAULT_CENSUS.md`](./docs/evidence/VAULT_CENSUS.md) |
| Source / build / deploy | `/health → software_release` (drift flag) · re-attested on every `scripts/deploy-release.sh` run |
| Contract schema | `contract_status` in `/health` |
| Machine-readable | [tools.json](https://arifos.arif-fazil.com/tools.json) · [llms.txt](./llms.txt) · [CITATION.cff](./CITATION.cff) |
| Scanner attestation | [mcp.arif-fazil.com/proof/](https://mcp.arif-fazil.com/proof/) |

### Operational gates (CI)

| Workflow | What it guards |
|---|---|
| [Unified CI](https://github.com/ariffazil/arifOS/actions/workflows/01-unified-ci.yml) | build + test |
| [MCP Conformance](https://github.com/ariffazil/arifOS/actions/workflows/06-mcp-conformance.yml) | protocol surface |
| [Vault Integrity](https://github.com/ariffazil/arifOS/actions/workflows/07-vault-integrity.yml) | ledger chain |
| [Floor Gate](https://github.com/ariffazil/arifOS/actions/workflows/floor_gate.yml) | floor evaluation |
| [Governance Gate](https://github.com/ariffazil/arifOS/actions/workflows/governance-gate.yml) | governance contract |
| [Drift Monitor](https://github.com/ariffazil/arifOS/actions/workflows/drift-monitor.yml) | source↔runtime drift |
| [Uptime](https://github.com/ariffazil/arifOS/actions/workflows/04-uptime-monitor.yml) | endpoint liveness |

---

## 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. (Closed rows are receipted in [`docs/evidence/GAP_HISTORY.md`](./docs/evidence/GAP_HISTORY.md).)

| Gap | Risk | Status |
|---|---|---|
| Independent security audit | Adversarial bypass testing not published | **In progress** — external researcher reviewing since 2026-08-25. Findings so far: fetch-surface SSRF (fixed, `1!2026.9.1`); Cypher injection (HIGH — key whitelist landed) and fastmcp path traversal (MEDIUM — containment guard landed). See [SECURITY.md](./SECURITY.md#known-gaps) |
| **Sovereign-binding of irreversible acknowledgement** | `ack_irreversible` and `actor_signature` are transported as payload fields; nothing published shows a human signature bound to `(transaction_hash ‖ state_hash ‖ nonce)`, single-use, scoped, unforgeable by the proposing agent | **Open** — design drafted ([`docs/judgment-integrity-2026-09-22/`](./docs/judgment-integrity-2026-09-22/ARIFOS_AUTHORITY_SERVICE_DESIGN.md)), not implemented. F13 is enforced by convention and band-gating, not cryptographic transaction binding |
| **Ledger head not externally anchored or signed** | A hash chain held entirely by one party cannot detect wholesale rewrite by that party | **Open** — VAULT999 today is self-verifiable, not independently attestable |
| Third-party evaluation | No external reviewer has published findings | In progress since 2026-08-25; nothing published |
| Reproducible demo by strangers | Onboarding path not independently tested | **Partial** — demo verified here; no stranger has reproduced it unaided |
| Enterprise deployment | No production customer reference | Open |
| Standards conformance | MCP/A2A results not published externally | **Partial** — [report](docs/evidence/conformance-report.json): `result: PARTIAL`, per-tool schema validation DEFERRED |
| SBOM and signed releases | Supply-chain integrity unverified externally | **Partial** — CycloneDX on publish; no signing, no CVE scan |
| Test suite | Needs a live kernel (`tests/conftest.py` refuses without `:8088`, by design) | 7,668 tests collect clean (2026-10-05); the identity/authority subset carries 34 pre-existing failures vs 321 passes (2026-09-30) — quote a failure *set*, never a bare pass count |
| Observability | Tracing partially wired | **Partial** — sovereign Postgres + arifFlow live; OTel spans on all 8 verbs; caller-side propagation incomplete |
| Semantic layer (Graphiti) | Knowledge graph retired from the read path | `graphiti_read: retired_888` (2026-09-04); semantic floor disabled by choice (`ARIFOS_ML_FLOORS=0`) |
| Comparative benchmark | No published comparison against alternative frameworks | Open |
| Maintainer continuity | Single sovereign, single reviewer; no succession or key-recovery procedure published | **Open — relevant to institutional adoption** |
| Identity registry in two copies | `contracts/identity.py` ↔ `arifosmcp/contracts/identity.py` had diverged; a one-sided edit ships split-brain identity | **Mitigated 2026-09-30** (tripwire tests, 18 actors aligned) — consolidation to one owner still open |

See [SECURITY.md](./SECURITY.md) for the threat model and disclosure policy, and [docs/evidence/claims.yaml](./docs/evidence/claims.yaml) for the machine-readable claim registry.

---

## Sister Repositories

| Repository | Purpose |
|------------|---------|
| [AAA](https://github.com/ariffazil/AAA) | Attention plane — routing, state, skill catalog, A2A gateway |
| [A-FORGE](https://github.com/ariffazil/A-FORGE) | Execution engine after authorisation |
| [GEOX](https://github.com/ariffazil/GEOX) | Earth sciences domain evidence |
| [WEALTH](https://github.com/ariffazil/WEALTH) | Capital and financial intelligence |
| [WELL](https://github.com/ariffazil/WELL) | Human and machine vitality observation |
| [arifFlow](https://github.com/ariffazil/arifFLOW) | Metabolic ledger daemon — FQ monitoring, receipt ingestion |
| [FRAME](https://github.com/ariffazil/FRAME) | Independent observer — drift detection, evidence gathering (repository archived, organ live) |

**No public repository today:** FED (`:7074`) and i-ARIF. They are deployed and reachable, but their source is not published. Treat their behaviour as observed from `/health` only.

---

## Evidence & Trust

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

| Claim | Evidence | Status |
|---|---|---|
| MCP conformance | [CI](./.github/workflows/06-mcp-conformance.yml) · [report](docs/evidence/conformance-report.json) | **Partial** |
| ABI stability | [Drift guard](./scripts/sync_kernel_abi.py) | **Partial** |
| Floor enforcement | `/health → layer_health.constitutional` (per-floor provenance) | **Verified by self-measurement; independent audit found the gap set above** |
| Vault integrity | [`scripts/verify_vault_chain.py`](./scripts/verify_vault_chain.py) | **Verified** — INTACT within its scope; 2 legacy breaks reported as historical |
| SBOM | [Generator](arifosmcp/arifos_sbom.py) | **Partial** |
| Quickstart | [Verified quickstart](./docs/QUICKSTART.md) | **Verified by the maintainer** 2026-09-21; not yet reproduced by a stranger |

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

---

## Who Is This For

**Operators** deploying AI agents in regulated environments who need an independent judgment layer between proposals and execution. **Developers** building 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 field (geoscience, finance, healthcare).

Start here: [docs/START_HERE.md](./docs/START_HERE.md)

## Founding Context

arifOS was built by ARIF FAZ, 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.**

## 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.

## Development

```bash
git clone https://github.com/ariffazil/arifOS.git
cd arifOS
pip install -e ".[dev]"                       # dev tier — kernel + test tooling
python -m pytest tests/ -q                    # needs a live kernel at :8088 (see gaps)
make health                                   # probe the kernel
PORT=8088 arifos-mcp streamable-http          # start the kernel
python scripts/generate_current_state.py      # re-stamp the generated truth block
```

See [`CODEOWNERS`](./CODEOWNERS) for sovereign ownership of automation surfaces and [`CONTRIBUTING.md`](./CONTRIBUTING.md).

<details>
<summary><strong>Project structure</strong> (the five <code>[wheel root]</code> entries are exactly what ships)</summary>

```
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                [wheel root]
├── core/               # Load-bearing legacy root                [wheel root]
├── schemas/            # INIT v2 schemas (F13-ratified 2026-09-20) [wheel root]
├── examples/           # Runnable governed workflow demo
├── tests/              # Test suite (pytest)
├── scripts/            # Operational tooling (update_readme_sot.py, generate_current_state.py)
├── .well-known/        # Generated machine state + truth badges (gitignored: state/)
├── docs/               # Documentation + evidence/ + archive/
└── pyproject.toml      # Package metadata — [wheel root] marks packages.find.include
```

Until 2026-09-30 this tree listed only `arifosmcp/` while the runtime imported `contracts.*` at 10 import statements across 5 files — production resolved them only from a `site-packages` leftover that a fresh venv would not have. 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 kept in agreement by tripwire tests; consolidating them into one owner is still open.

</details>

## Security

See [SECURITY.md](./SECURITY.md) for the threat model, known vulnerabilities and disclosure policy.

## License

**AGPL-3.0** ([`LICENSE`](./LICENSE)). When deployed over a network, the complete source code must be made available to all users interacting with the service.

---

*Revision 2026-10-16 — restructured under AGENTIC-README-DOCTRINE v1 (attention layer for humans, agents and institutions; dynamic state generated, never hand-carried). Pre-doctrine text preserved verbatim in [`docs/archive/README-2026-10-16-pre-doctrine.md`](./docs/archive/README-2026-10-16-pre-doctrine.md); every claim retained or receipted there. Prior audit passes: 2026-09-21 full re-measurement · 2026-09-22 Copilot external ENTERPRISE · 2026-10-11 independent re-probe.*

**Ditempa Bukan Diberi** — Forged, Not Given.

<!-- FEDERATION-STANDARD v2026-10-15 START :: 333-AGI audit :: source: organs.yaml + git + live probes -->
## 🔗 Federation Identity
| Field | Value |
|---|---|
| Organ | `arifos` · CORE · governance_kernel |
| Ports | 8088 (/mcp) |
| Unit | arifos.service |
| Authority ceiling | JUDGE_ONLY |
| Public MCP | https://arifos.arif-fazil.com/mcp |
| Flow graph | [FEDERATION.md](https://github.com/ariffazil/AAA/blob/main/FEDERATION.md) — peta semua organ + repo |
<!-- FEDERATION-STANDARD v2026-10-15 END -->
