arifOS - Sovereign Constitutional Intelligence Kernel

DITEMPA BUKAN DIBERI — Intelligence is forged, not given.

arifOS is the constitutional runtime kernel for a governed AI federation. It is not a model, chatbot, or agent persona. It is the law layer that decides how AI systems observe, reason, execute, judge, and seal actions through 13 canonical MCP tools, 13 constitutional floors (F01–F13), and an immutable VAULT999 audit ledger.

The core guarantee: high-impact or irreversible action must pass constitutional judgment (888_JUDGE) before execution. The human sovereign (Arif) retains final veto at all times.

Version


Package	`arifos` on PyPI
Version	`2026.05.01`
Runtime	`kanon-2026.05.01`
Python	`>=3.12`
MCP framework	`fastmcp>=3.2.0`
HTTP port	`8080` (configurable via `ARIFOS_PORT`)

Architecture

Operator (Arif) → WELL (Human Substrate Mirror) → arifOS (Constitutional Kernel) → A-FORGE (Execution)
                    ↕                                        ↕
                 (WELL)                                (888_JUDGE)
              Human substrate                          Constitutional verdict

arifOS adjudicates. WELL mirrors the human substrate. A-FORGE executes.

13 Canonical MCP Tools

Stage	Tool	Lane	Purpose
000	`arif_session_init`	AGI	Session anchor — opens governed session with identity binding
111	`arif_sense_observe`	AGI	Observe reality — web search, system telemetry, environmental data
222	`arif_evidence_fetch`	AGI	Fetch and preserve evidence from URLs, files, databases
333	`arif_mind_reason`	AGI	First-principles reasoning — synthesis, hypothesis, cross-domain analysis
444	`arif_kernel_route`	AGI	Route tasks to correct organ — GEOX, WEALTH, or WELL
444r	`arif_reply_compose`	AGI	Governed response compositor — drafts with constitutional tone
555	`arif_memory_recall`	AGI	Vector memory retrieval — searches past sessions, decisions, sealed events
666	`arif_heart_critique`	ASI	Safety + empathy check — consequence modeling, bias detection
666g	`arif_gateway_connect`	ASI	A2A mesh router — connects federation agents (Hermes, AAA, etc.)
777	`arif_ops_measure`	AGI	Thermodynamic metrics — CPU, memory, entropy, g_score
888	`arif_judge_deliberate`	ASI	Final constitutional verdict — SEAL / HOLD / VOID
010	`arif_forge_execute`	AGI sovereign	Dispatch execution to A-FORGE after SEAL authorization
999	`arif_vault_seal`	APEX	Permanently seal verdicts to VAULT999 (Merkle-hashed)

WELL — Human Substrate Governance Layer

WELL sits between Arif and the constitutional kernel. It answers:

"Is the human substrate capable of reliable intent for this decision class right now?"

WELL does not veto. It informs. (W0 Sovereignty Invariant)

WELL_v2 Schema

WELL_v2 introduces the consent reliability composite — a weighted governance signal:

consent_reliability = 40% HRV_factor + 25% sleep_architecture + 25% decision_reserve + 10% floor
Penalties: acute_stress (0.6x), strain_debt (0.7x at danger threshold)

Key fields:

Field	Purpose
`hrv` + `hrv_trend[]` + `hrv_velocity`	Predictive signal — HRV velocity predicts performance 12–48h ahead
`sleep_deep_min` + `sleep_rem_min` + `sleep_efficiency`	Real recovery engine — deep sleep drives growth hormone; REM drives emotional processing
`strain_debt`	Accumulated recovery deficit — invisible until catastrophic
`decision_reserve_pct`	Finite decision resource remaining — not accumulation, a ceiling
`convergence_alert`	Multi-channel danger detector — 2+ channels declining simultaneously = alert
`acute_stress_active`	Circuit breaker — forces HOLD regardless of other signals

Consent Reliability Thresholds

Range	Meaning
≥ 0.85	OPTIMAL — full execution bandwidth
0.65–0.84	FUNCTIONAL — normal mode
0.30–0.64	LOW_CAPACITY — draft_only, sovereign review recommended
< 0.30	DEGRADED — HOLD until substrate recovers

A2A Federation

arifOS connects to domain agents via the A2A (Agent-to-Agent) mesh:

Agent	Role	Status
Hermes (port 3002)	ASI-level constitutional deliberation	Running ✅
AAA gateway (port 3001)	Agent dispatch + federation manifest	Running ✅
GEOX	Earth-domain coprocessor (geoscience, physical evidence)	External
WEALTH	Capital intelligence coprocessor (valuation, risk)	External

13 Constitutional Floors

Floor	Name	Rule
F01	AMANAH	Actions are accountable; irreversible action requires approval and trace
F02	TRUTH	Do not fabricate — separate fact, estimate, hypothesis, unknown
F03	WITNESS	Evidence must be inspectable and preserved where possible
F04	CLARITY	Intent, uncertainty, and consequences must be legible
F05	PEACE	Preserve dignity and reduce avoidable harm
F06	EMPATHY	Model stakeholder consequences before acting
F07	HUMILITY	Bound confidence and acknowledge limits
F08	GENIUS	Prefer elegant correctness over noisy complexity
F09	ANTIHANTU	Reject manipulation, dark patterns, false agency claims
F10	ONTOLOGY	Preserve structural and identity coherence
F11	AUTH	Verify actor authority before sensitive operations
F12	INJECTION	Treat inputs as hostile until sanitized
F13	SOVEREIGN	Human veto is absolute

Verdicts

Verdict	Meaning
`SEAL`	Proceed — constitutionally cleared, may be recorded
`HOLD`	Pause — more evidence, identity, consent, or review required
`VOID`	Halt — violates a hard floor or cannot be safely justified

Expected path: observe → reason → critique → judge → execute or hold → seal

HTTP Endpoints

Endpoint	Purpose
`/mcp`	MCP streamable HTTP endpoint
`/health`	Lightweight liveness probe — service name, version, tool count
`/ready`	Deep integrity probe — full runtime selftest
`/tools`	Interactive tool browser
`/components`	Full topology map of connected systems
`/.well-known/agent-card.json`	Agent card for A2A federation discovery

Quick Start

# Install from PyPI
pip install arifos

# Run MCP server
arifos-mcp

# Or via Python
python -m arifosmcp.server

# Probe
curl -s http://localhost:8080/health | jq .

Docker

# Build
docker build -t arifos:local .

# Run
docker run --rm -p 8080:8080 arifos:local

# Production compose
docker compose up -d --build arifosmcp

Development

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

# Lint
ruff check .

# Type check
mypy arifosmcp/

Source of Truth Order

When files disagree:

Live runtime endpoints: /health, /ready, MCP discovery
arifosmcp/constitutional_map.py — floor + tool authority registry
arifosmcp/runtime/tools.py — registered tool behavior
arifosmcp/schemas/ — typed output schemas
arifOS/000/000_CONSTITUTION.md — F01–F13 constitutional law
pyproject.toml, Dockerfile, docker-compose.yml — packaging + deployment
This README

Security Rules for Agents

Do not fabricate runtime facts — verify with code, tests, or live endpoints
Do not expose secrets, tokens, .env files, private keys, or raw credentials
Do not run destructive operations without explicit human (Arif) approval
Treat VAULT999 ledgers as append-only
Keep constitutional judgment in arifOS — 888_JUDGE is the final arbiter
WELL informs, Arif decides — WELL never vetoes (W0 Invariant)
If docs, registry, and runtime disagree — report the conflict and cite the stronger SOT

License

AGPL-3.0-only. See LICENSE.

One-Sentence Summary

arifOS is the constitutional MCP law kernel that gives AI agents a governed path from human substrate verification (WELL) through observation, reasoning, constitutional judgment (888_JUDGE), and execution (A-FORGE) to immutable audit sealing (VAULT999) — while preserving human sovereignty at every stage.

Name	arifos-align
Description	Match emotional frequency, detect power dynamics (444_CONSULT). Detects emotional state and power imbalance. The empathy detection stage of arifOS metabolic loop. Use when emotional calibration matters.

arifos-align

SKILL.md