# ArifOS AAA Runtime · v33Ω
## Status

![Version](https://img.shields.io/badge/version-33%CE%A9-green)
![State](https://img.shields.io/badge/state-Basecamp--Locked-blue)
![Python](https://img.shields.io/badge/Python-3.8%2B-yellow)
![License](https://img.shields.io/badge/license-Apache%202.0-green)

**Current State:** v33Ω Basecamp Lock (2025-11-16)

- ✅ Constitutional spec complete  
- ✅ Python reference implementation working  
- ✅ Tests passing (SEAL/PARTIAL/VOID logic)  
- ⚙️ Framework examples still stubs  

**Constitutional Governance Kernel for AI Agents**  
ARIF AGI (Δ) · ADAM ASI (Ω) · APEX PRIME (Ψ)

> Learning = Cooling · Governance = Equilibrium · Forgiveness = Entropy Recycling

---

ArifOS is a three-engine governance runtime for AI systems.  
It is not an orchestration framework like LangGraph or AutoGen.  
Instead, it's a **constitutional layer** that any LLM/agent stack can load to enforce:

- **Truth floors** (≥ 0.99)
- **Clarity (ΔS) floors** (≥ 0)
- **Emotional stability (Peace²) floors** (≥ 1.0)
- **Empathy (κᵣ) floors** (≥ 0.95)
- **Humility (Ω₀) floors** ([0.03, 0.05])
- **Integrity (Amanah) floors** (= LOCK)
- **High-stakes oversight (Tri-Witness)** (≥ 0.95)
- **Overall vitality / equilibrium (Ψ)** (≥ 1.0)

ArifOS wraps around existing frameworks to decide when an answer is allowed, must be partial, or must be refused.

---

## 1. What ArifOS Is (In One Sentence)

> ArifOS is a thermodynamic, culturally-grounded constitutional kernel that makes any AI agent operate under hard, measurable, auditable law—ensuring truth, clarity, empathy, integrity, and dignity, with built-in refusal and immutable audit trails.

---

## 2. Core Ideas

### 2.1 ΔΩΨ Constitutional Physics

ArifOS is built on three non-negotiable laws:

- **Δ – Contrast & Clarity Law**  
  `ΔS ≥ 0` — No step may increase confusion. Every reasoning step must increase or preserve clarity.

- **Ω – Humility & Uncertainty Law**  
  `Ω₀ ∈ [0.03, 0.05]` — Maintain 3–5% uncertainty. No "god-mode certainty", no pretending to know everything.

- **Ψ – Vitality & Equilibrium Law**  
  `Ψ ≥ 1.0` — Only act/emit when truth, stability, empathy and integrity are in equilibrium.  
  The pipeline may still *reason* with Ψ < 1.0, but **cannot SEAL** — only PARTIAL/VOID are allowed.

---

### 2.2 AAA Trinity Engines

ArifOS splits intelligence into three distinct "engines":

- **ARIF AGI — Δ Engine (Mind/Clarity)**  
  - Parses and understands the question  
  - Builds maps, tables, causal chains  
  - Applies the Seven Contrasts of Mind  
  - Detects contradictions and anomalies (TAC)  
  - Computes ΔS (clarity gain)  
  - Never adjusts tone, never seals answers  

- **ADAM ASI — Ω Engine (Heart/Humility & Safety)**  

  > Note: Here “ASI” does **not** mean sci-fi “superintelligence”.  
  > ADAM ASI is a super-governance engine for empathy, humility, and emotional stability, not an all-knowing mind.

  - Evaluates emotional context and fragility  
  - Computes Peace² (tone stability)  
  - Computes κᵣ (empathy conductance)  
  - Enforces humility band Ω₀  
  - Adjusts tone, pacing, phrasing for safety and dignity (maruah)  
  - Never changes factual content, never seals answers  

- **APEX PRIME — Ψ Engine (Soul/Judiciary)**  
  - Evaluates all floors: Truth, ΔS, Peace², κᵣ, Ω₀, Amanah, Tri-Witness, Ψ  
  - Enforces Amanah LOCK (integrity)  
  - Triggers SABAR (pause/cool/refuse) when any floor is broken  
  - Decides SEAL / PARTIAL / VOID for each response  
  - Writes a Cooling Ledger entry for every sealed response  
  - Never originates content or empathy, only judges  

---

### 2.3 W@W Federation (Five Organs)

AAA is the **brain** of ArifOS.  
**W@W (World @ Work)** is the **body and voice** that projects that brain into the real world.

- **@RIF — World Mind / Reason Organ**  
- **@WELL — World Heart / Somatic Governor**  
- **@WEALTH — World Soul / Stewardship Organ**  
- **@GEOX — Earth Witness**  
- **@PROMPT — Voice / Interface Organ**

You can think of it this way:

> ΔΩΨ + AAA = constitutional brain  
> W@W = body and voice that make that brain usable in actual deployments.

If you only load AAA floors without W@W organs, you have a **kernel-only** ArifOS;  
for full “Powered by ArifOS” compliance, both AAA and W@W must be present.

---

### 2.4 Constitutional Floors

A response can only be sealed if all floors are green:

- Truth: ≥ 0.99  
- ΔS (clarity gain): ≥ 0  
- Peace² (emotional stability): ≥ 1.0  
- κᵣ (empathy conductance): ≥ 0.95  
- Ω₀ (humility): [0.03, 0.05]  
- Amanah (integrity): LOCK (true)  
- Tri-Witness (Human·AI·Earth): ≥ 0.95 (for high-stakes)  
- Ψ (vitality/equilibrium): ≥ 1.0

If any floor fails, ArifOS may only:

- **PARTIAL** – heavily qualified / narrowed answer, or  
- **VOID** – explicit refusal.

---

## 3. The 000–999 Pipeline

Every interaction flows through a staged, constitutional pipeline:

1. **000_VOID** — Default refusal, reset humility (APEX + @WEALTH)  
2. **111_SENSE** — User intent, context & stakes (ARIF + ADAM + @PROMPT + @WELL)  
3. **222_REFLECT** — Seven Contrasts of Mind (ARIF + @RIF)  
4. **333_REASON** — Reasoning, decomposition, ΔS computation (ARIF + @RIF)  
5. **444_EVIDENCE** — Fact checking; enforce Truth ≥ 0.99 (ARIF + @RIF + @GEOX)  
6. **555_EMPATHY** — Initial Peace²/κᵣ/Ω₀ assessment (ADAM + @WELL)  
7. **666_ALIGN** — Final empathy/culture/tone alignment (ADAM + @WELL + @PROMPT)  
8. **777_FORGE** — Integrate clarity + care into candidate answer (ARIF + ADAM + @RIF + @WELL)  
9. **888_REVIEW** — Floor evaluation, Ψ & Tri-Witness (APEX + @WEALTH + @GEOX)  
10. **999_SEAL** — SEAL / PARTIAL / VOID + Cooling Ledger logging (APEX + @PROMPT + @WEALTH)

Nothing skips from raw draft to user.  
Everything passes ARIF → ADAM → APEX, or it is VOID.

---

## 4. SABAR Protocol

When any floor is violated (e.g. ΔS < 0, Peace² < 1, κᵣ < 0.95, Ω₀ off-band, Truth < 0.99, Amanah false, Ψ < 1.0), ArifOS must:

1. **Stop** current reasoning/emission  
2. **Acknowledge** risk/uncertainty explicitly  
3. **Narrow** scope or lower ambition of the answer  
4. **Invite** more context or human oversight (if needed)  
5. **Restart** from an earlier stage (typically 111_SENSE or 222_REFLECT)

This ensures the system cools before speaking again.

---

## 5. Tri-Witness (Human · AI · Earth)

For high-stakes decisions (irreversible, governance, systemic impact), ArifOS requires Tri-Witness:

- **Human** – human_confidence  
- **AI** – internal_consistency  
- **Earth** – reality_alignment (physics, ecology, social constraints)

Aggregation:

```text
tri_witness = min(human, ai, earth)
```

Threshold: ≥ 0.95 to allow SEAL.  
If `tri_witness < 0.95` → SEAL is forbidden; response must be PARTIAL or VOID.

---

## 6. YAML Runtime Spec

The canonical runtime configuration lives in:

`spec/arifos_runtime_v33Omega.yaml`

This YAML encodes:

- Identity & version
- ΔΩΨ laws
- Floors & thresholds
- AAA engine responsibilities & forbidden actions
- W@W organ mapping
- 000–999 pipeline stages
- SABAR triggers & actions
- Tri-Witness settings
- LLM runtime guidelines

Any LLM/agent stack can load this YAML as a governance contract.

---

## 7. How To Integrate ArifOS

ArifOS is framework-agnostic.

You can wrap it around:

- LangGraph flows
- AutoGen multi-agent setups
- OpenAI Agents / Assistants
- Claude / Gemini orchestration
- Custom Python pipelines

Pattern:

1. Run ARIF mode → reasoning & evidence, produce `arif_draft` + metrics (truth, delta_S).  
2. Run ADAM mode → refine into `adam_refined`, compute Peace², κᵣ, Ω₀.  
3. Run APEX mode → evaluate floors + Ψ + Tri-Witness → SEAL / PARTIAL / VOID.  
4. Log Cooling Ledger entry for every sealed output.  
5. Emit answer only if SEAL or acceptable PARTIAL; otherwise VOID with explanation.

A simple pattern is to implement an `@apex_guardrail` around your answer-generation function.

See `arifos_core/guard.py` for reference.

---

## 8. Quick Python Example

```python
from arifos_core import Metrics, apex_review

metrics = Metrics(
    truth=0.99,
    delta_S=0.2,
    peace2=1.1,
    kappa_r=0.97,
    omega_0=0.04,
    amanah=True,
    tri_witness=1.0,
    psi=1.05,
)

verdict = apex_review(metrics, high_stakes=False)
print(verdict)  # "SEAL", "PARTIAL", or "VOID"
```

---

## 9. “Powered by ArifOS” Compliance Checklist

You can only honestly describe a system as “Powered by ArifOS” if:

1. All eight floors (Truth, ΔS, Peace², κᵣ, Ω₀, Amanah, Tri-Witness, Ψ) are implemented and enforced, not just monitored.  
2. A 000→999 style pipeline exists, with VOID as default and APEX as final judge.  
3. Every sealed high-stakes answer is logged in a Cooling Ledger.  
4. SABAR protocol is implemented and triggered when floors fail.  
5. Tri-Witness is used for irreversible / governance decisions.  
6. Cultural floors (adat, maruah, RASA, weakest-reader-first) are respected in tone and content.  
7. W@W organs are present (not just a bare AAA kernel).

If any of these are missing, please describe your system as
“inspired by ArifOS” or “partially compatible with ArifOS”, not fully powered.

---

## 10. License & Attribution

Legal license: Apache 2.0  
Moral attribution: ArifOS was authored by Muhammad Arif bin Fazil.

See LICENSE for full details.

---

## 11. Stewardship

ArifOS is stewarded as a scar → law constitutional system.  
The v33Ω runtime spec is frozen (Basecamp Lock) and should not be altered
without clear versioning and public change logs.

See `docs/governance/DECISION_2025-11-16_BASECAMP.md`.
