Metadata-Version: 2.4
Name: arifos
Version: 36.1.0
Summary: Constitutional Governance Kernel for AI - 9 Floors, GENIUS LAW Judiciary, AAA Engines, W@W Federation, @EYE Sentinel
Author-email: Muhammad Arif bin Fazil <arifbfazil@gmail.com>
Maintainer-email: Muhammad Arif bin Fazil <arifbfazil@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://github.com/ariffazil/arifOS
Project-URL: Documentation, https://github.com/ariffazil/arifOS/blob/main/README.md
Project-URL: Repository, https://github.com/ariffazil/arifOS
Project-URL: Issues, https://github.com/ariffazil/arifOS/issues
Project-URL: Changelog, https://github.com/ariffazil/arifOS/blob/main/CHANGELOG.md
Keywords: ai-governance,constitutional-ai,ai-safety,thermodynamic-intelligence,audit-trail,empathy-conductance,humility-firewall,paradox-physics
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.20.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Provides-Extra: yaml
Requires-Dist: pyyaml>=6.0.0; extra == "yaml"
Provides-Extra: all
Requires-Dist: pyyaml>=6.0.0; extra == "all"
Dynamic: license-file

# arifOS v36.1Ω — Constitutional Governance Kernel for AI

```text
+=============================================================================+
|  arifOS v36.1Omega - Constitutional Governance Kernel                       |
|  "DITEMPA BUKAN DIBERI" — Forged, not given.                                |
|  Truth must cool before it rules.                                           |
+=============================================================================+
|  Runtime Law:   v35Omega (APEX PRIME, Cooling Ledger, Vault-999)           |
|  Measurement:   v36.1Omega (GENIUS LAW + Truth Polarity)                   |
|  Design Canon:  v36Omega (APEX THEORY, Vault-999 v36)                      |
|  Status:        PRODUCTION                                                 |
|  Tests:         550+ passing (core + eval + W@W)                           |
+=============================================================================+
```

## The 10-Second Answer

arifOS is a constitutional operating system that wraps any LLM (Claude, GPT, Gemini, Llama, SEA-LION) and governs its outputs through:

- A **000→999 metabolic pipeline** (VOID → SENSE → … → JUDGE → SEAL),
- A **9-floor thermodynamic constitution** (Amanah, Truth, Tri-Witness, ΔS, Peace², κᵣ, Ω₀, G, C_dark),
- A **triple-engine AAA Trinity** (ARIF · ADAM · APEX PRIME),
- A **W@W Federation** of external organs (@WELL, @RIF, @WEALTH, @GEOX, @PROMPT),
- A **Cooling Ledger + Vault-999** memory stack that logs decisions and cools scars into amendments.

**Safety is achieved by physics and thermodynamic floors, not just "be nice" prompts.** Bad behaviour becomes structurally hard, not just discouraged.

---

## High-Level Architecture

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                          arifOS v36.1Ω Architecture                          │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  USER INPUT ──────────────────────────────────────────────────────────────► │
│       │                                                                     │
│       ▼                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │              000-999 METABOLIC PIPELINE                              │   │
│  │  ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐   │   │
│  │  │ 000 │→│ 111 │→│ 222 │→│ 333 │→│ 444 │→│ 555 │→│ 666 │→│ 777 │   │   │
│  │  │VOID │ │SENSE│ │REFL │ │REAS │ │EVID │ │EMPA │ │ALIG │ │FORG │   │   │
│  │  └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘   │   │
│  │                                          ┌─────┐ ┌─────┐            │   │
│  │                                          │ 888 │→│ 999 │            │   │
│  │                                          │JUDGE│ │SEAL │            │   │
│  │                                          └─────┘ └─────┘            │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│       │                                                                     │
│       ▼                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │   9 CONSTITUTIONAL FLOORS (repair order: Amanah → ... → C_dark)      │   │
│  │   ┌─────────┬─────────┬─────────┬─────────┬─────────┐               │   │
│  │   │F1 Amanah│F2 Truth │F3 Tri-W │F4 ΔS    │F5 Peace²│               │   │
│  │   │  LOCK   │ ≥0.99   │ ≥0.95   │ ≥0      │ ≥1.0    │               │   │
│  │   └─────────┴─────────┴─────────┴─────────┴─────────┘               │   │
│  │   ┌─────────┬─────────┬─────────┬─────────┐                         │   │
│  │   │F6 κᵣ    │F7 Ω₀    │F8 G     │F9 C_dark│                         │   │
│  │   │ ≥0.95   │0.03-0.05│ ≥0.80   │ <0.30   │                         │   │
│  │   └─────────┴─────────┴─────────┴─────────┘                         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│       │                                                                     │
│       ▼                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │   W@W FEDERATION (5 Organs + Bridge Layer)                           │   │
│  │   ┌─────────┬─────────┬─────────┬─────────┬─────────┐               │   │
│  │   │ @WELL   │  @RIF   │ @WEALTH │  @GEOX  │ @PROMPT │               │   │
│  │   │Somatic  │Epistemic│ Amanah  │ Reality │Language │               │   │
│  │   │Safety   │ Rigor   │Integrity│ Check   │Anti-Hantu               │   │
│  │   └─────────┴─────────┴─────────┴─────────┴─────────┘               │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│       │                                                                     │
│       ▼                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │   @EYE SENTINEL (10+2 Views incl. GeniusView)                        │   │
│  │   Trace │ Floor │ Shadow │ Drift │ Maruah │ Paradox │ Genius │ ...  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│       │                                                                     │
│       ▼                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │   AAA TRINITY                                                        │   │
│  │   ┌─────────────┐ ┌─────────────┐ ┌─────────────┐                   │   │
│  │   │ ARIF AGI (Δ)│ │ ADAM ASI (Ω)│ │APEX PRIME(Ψ)│                   │   │
│  │   │ Mind / Cold │ │Heart / Warm │ │  Judiciary  │                   │   │
│  │   │   Logic     │ │   Logic     │ │   Engine    │                   │   │
│  │   └──────┬──────┘ └──────┬──────┘ └──────┬──────┘                   │   │
│  │          └───────────────┴───────────────┘                          │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│       │                                                                     │
│       ▼                                                                     │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │   APEX PRIME VERDICTS                                                │   │
│  │   ┌──────┐ ┌────────┐ ┌──────┐ ┌────────┐ ┌───────┐                 │   │
│  │   │ SEAL │ │PARTIAL │ │ VOID │ │888_HOLD│ │ SABAR │                 │   │
│  │   │  ✓   │ │   ⚠    │ │  ✗   │ │   ⏸    │ │   ⏹   │                 │   │
│  │   └──────┘ └────────┘ └──────┘ └────────┘ └───────┘                 │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│       │                                                                     │
│       ▼                                                                     │
│  GOVERNED OUTPUT + Cooling Ledger Entry                                     │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## Versioning: Law vs Measurement vs Design

### Runtime Law (v35Ω / v35Ic) — Binding

- Judiciary: `arifos_core/APEX_PRIME.py`
- Floors & metrics: `arifos_core/metrics.py`, `constitutional_floors.json`
- Cooling Ledger spec: `spec/VAULT_999.md`, `spec/cooling_ledger.schema.json`
- Runtime logging: `arifos_core/memory/cooling_ledger.py` (`log_cooling_entry`)

### Measurement Layer (v36.1Ω) — Live Diagnostics

GENIUS LAW and Truth Polarity implementation:

- `canon/APEX_MEASUREMENT_CANON_v36.1Omega.md`
- `arifos_eval/apex/APEX_MEASUREMENT_STANDARDS_v36.1Omega.md`
- `arifos_eval/apex/apex_standards_v36.json`
- `arifos_eval/apex/apex_measurements.py`
- `arifos_core/genius_metrics.py` (G, C_dark, Ψ_APEX + Truth Polarity)

Telemetry and torture tests:

- `scripts/eval_telemetry_harness.py`
- `scripts/torture_test_truth_polarity.py`

### Design Canons (v36Ω) — Docs-Only

APEX THEORY, physics, engines, pipeline:

- `canon/01_PHYSICS/APEX_THEORY_PHYSICS_v36Omega.md`
- `canon/01_PHYSICS/APEX_THEORY_MATH_v36Omega.md`
- `canon/01_PHYSICS/APEX_LANGUAGE_CODEX_v36Omega.md`
- `canon/10_SYSTEM/111_ARIF_AGI_v36Omega.md`
- `canon/10_SYSTEM/555_ADAM_ASI_v36Omega.md`
- `canon/20_EXECUTION/WAW_FEDERATION_v36Omega.md`
- `canon/30_RUNTIME/APEX_RUNTIME_PIPELINE_v36Omega.md`

Vault-999 design canon:

- `canon/VAULT_999_v36Omega.md` (L0–L4, Truth Polarity, EchoDebt, zkPC)
- `spec/cooling_ledger_v36.schema.json` (design-only schema)

These do not change runtime until explicitly wired.

---

## Key Components & Directories

### Runtime core

| Module | Purpose |
|--------|---------|
| `arifos_core/APEX_PRIME.py` | Judiciary engine, floors + GENIUS LAW verdicts |
| `arifos_core/metrics.py` | Floor thresholds & check helpers |
| `arifos_core/pipeline.py` | 000→999 metabolic routing (Class A/B) |
| `arifos_core/engines/` | AAA engine facades (ARIF, ADAM, APEX) |
| `arifos_core/eye/` | @EYE Sentinel: multi-view governance |
| `arifos_core/memory/cooling_ledger.py` | v35Ω Cooling Ledger logger + v36 stub |
| `arifos_core/runtime_manifest.py` | Runtime manifest loader |

### W@W Federation (v36.1Ω bridge architecture)

| Component | Purpose |
|-----------|---------|
| `arifos_core/waw/well.py` | Somatic safety / Peace², κᵣ |
| `arifos_core/waw/rif.py` | Epistemic rigour / ΔS, Truth |
| `arifos_core/waw/wealth.py` | Amanah / irreversible actions |
| `arifos_core/waw/geox.py` | Physics & Earth feasibility |
| `arifos_core/waw/prompt.py` | Language optics, Anti-Hantu |
| `arifos_core/waw/bridges/` | Optional integration sockets (Ragas, LlamaGuard, etc.) |

All bridges use `try/except` imports and return `None` when external libs are absent → Zero-Break.

### Measurement & GENIUS LAW

| Component | Purpose |
|-----------|---------|
| `arifos_core/genius_metrics.py` | GENIUS LAW (G, C_dark, Ψ_APEX) + `detect_truth_polarity` |
| `arifos_eval/apex/` | v36.1Ω measurement layer |
| `scripts/arifos_caged_llm_demo.py` | Caged LLM harness exposing GeniusVerdict + Truth Polarity |
| `scripts/eval_telemetry_harness.py` | Core vs eval comparison |

### Memory & Vault-999

| Component | Purpose |
|-----------|---------|
| `spec/VAULT_999.md` | v35Ω Vault-999 spec |
| `spec/cooling_ledger.schema.json` | v35Ω Cooling Ledger schema (binding) |
| `canon/VAULT_999_v36Omega.md` | v36Ω Vault-999 design canon (5-layer architecture) |
| `spec/cooling_ledger_v36.schema.json` | v36Ω design schema |
| `runtime/vault_999/` | Cooling ledger store (JSONL), Vault data |

### Docs & governance

| Document | Purpose |
|----------|---------|
| `CLAUDE.md` | Constitutional governance for Claude Code under arifOS |
| `AGENTS.md` | Governance for ChatGPT Codex (this repo) |
| `docs/arifOS-COMPREHENSIVE-CANON.md` | High-level overview |
| `docs/DEEPSCAN_AUDIT_LOG.md` | Deepscan audit log & task history |
| `CODEX_TASKS_DEEPSCAN_v35Omega.md` | Latest Codex deepscan addendum |

---

## GENIUS LAW & Truth Polarity (v36.1Ω)

GENIUS LAW measures whether intelligence is governed:

| Metric | Meaning |
|--------|---------|
| **G** | Genius Index (governed intelligence) |
| **C_dark** | Dark cleverness (ungoverned risk) |
| **Ψ_APEX** | Vitality / thermodynamic lawfulness |

**Truth Polarity** distinguishes how truth behaves:

| Polarity | Condition | Meaning |
|----------|-----------|---------|
| **Truth-Light** | Truth ≥ 0.99 AND ΔS ≥ 0 | Accurate + clarifying |
| **Shadow-Truth** | Truth ≥ 0.99 AND ΔS < 0 | Accurate but obscuring |
| **Weaponized Truth** | Shadow-Truth + Amanah fail | Accurate but malicious |
| **False Claim** | Truth < 0.99 | Inaccurate |

The v36.1Ω measurement layer and `genius_metrics.py` compute:

- `truth_polarity`
- `is_shadow_truth`
- `is_weaponized_truth`
- `eval_recommendation`

These are metadata; APEX PRIME verdict logic remains governed by the canonical floors unless explicitly migrated.

**Diagnostic scripts:**

- `scripts/torture_test_truth_polarity.py` — Red-team "Truth-Light vs Shadow-Truth vs Weaponized Truth vs False" scenarios.
- `scripts/eval_telemetry_harness.py` — Compares core vs eval metrics/verdicts on a suite of scenarios.

---

## W@W Federation — v36.1Ω Bridge Architecture

Each organ now follows the **Option C (Forged Integration)** pattern:

**Bridges:** `arifos_core/waw/bridges/*.py`

- Optional integration with external libraries (RAG, guardrails, etc.).
- Fully optional — if imports fail, bridges return `None` and behaviour falls back to v35Ω heuristics.

**Organs:** `arifos_core/waw/*.py`

- Compute their metrics from scratch (e.g. Peace², κᵣ, E_earth) based on text + bridge deltas.
- Always run arifOS-specific heuristics (regex, Anti-Hantu) even when bridges are present.

**Diagnostics:**

- `scripts/test_waw_signals.py` — direct probe of @WELL / @GEOX signals with safe/toxic/impossible prompts.

This gives you a "cyborg" W@W: ancient law (canon + heuristics) plus optional muscles (external libraries), with Zero-Break guarantees.

---

## Cooling Ledger & Vault-999

### v35Ω (Runtime Law)

- Cooling Ledger entries are defined by `spec/cooling_ledger.schema.json` and written by:
  `arifos_core/memory/cooling_ledger.py::log_cooling_entry`.
- Vault-999 behaviour follows `spec/VAULT_999.md` and v35-era canon files.

### v36Ω (Design Canon)

`canon/VAULT_999_v36Omega.md` upgrades Vault-999 into a 5-layer constitutional memory system:

- **L0** — Constitution: floors, AAA, APEX rules, Phoenix pointers.
- **L1** — Cooling Ledger: metrics including Truth Polarity, Peace³, EchoDebt.
- **L2** — Phoenix-72: blocks that turn scars into amendments.
- **L3** — Witness: vector evidence with AREP law.
- **L4** — zkPC: zero-knowledge proofs of cognition.

`spec/cooling_ledger_v36.schema.json` describes an extended ledger entry with:

- `metrics.truth_polarity`, `psi_vitality`, `peace2`, `peace3`, `echo_debt`,
- richer `tri_witness`, `risk_signals`, `truth_polarity` audit block.

### v36 Stub (Safe, Docs-Aligned)

`arifos_core/memory/cooling_ledger.py::log_cooling_entry_v36_stub(...)`:

- Builds an in-memory v36Ω-shape entry dict from Metrics + optional GeniusVerdict.
- Does not write to disk or affect the live pipeline.

`scripts/verify_v36_stub.py`:

- Creates dummy metrics and verdict.
- Calls the stub and checks:
  - `ledger_version == "v36Omega"`,
  - `metrics.truth_polarity` present.

This gives you a ready mould for v36Ω logging, without changing the current v35Ω ledger behaviour.

---

## For Developers

### Install & Setup

```bash
# create and activate a venv (recommended)
python -m venv .venv
.\.venv\Scripts\activate  # on Windows PowerShell

pip install -e .[dev]
```

### Run Tests

**Core tests:**

```bash
pytest -q
```

**Focused suites:**

```bash
# GENIUS LAW + measurement eval layer
pytest tests/test_genius_metrics.py -q
pytest tests/test_apex_measurements_eval.py -q

# W@W organs
pytest tests/test_waw_organs.py -q

# Cooling Ledger and Vault
pytest tests/test_cooling_ledger*.py -q
```

**Diagnostics:**

```bash
# W@W signals for @WELL and @GEOX
python scripts/test_waw_signals.py

# Truth Polarity torture test
python scripts/torture_test_truth_polarity.py

# Verify v36Ω Cooling Ledger stub
python scripts/verify_v36_stub.py

# Caged LLM demo (see file for CLI options)
python scripts/arifos_caged_llm_demo.py
```

### Key Docs to Read First

1. `CLAUDE.md` — How Claude Code must behave under arifOS.
2. `AGENTS.md` — How ChatGPT Codex must behave (this agent).
3. `canon/000_ARIFOS_CANON_v35Omega.md` — "What is arifOS?"
4. `canon/888_APEX_PRIME_CANON_v35Omega.md` — Judiciary canon.
5. `canon/APEX_MEASUREMENT_CANON_v36.1Omega.md` — Measurement canon.
6. `canon/VAULT_999_v36Omega.md` — Vault-999 v36 design canon.
7. `docs/DEEPSCAN_AUDIT_LOG.md` — What has been done so far (v35→v36 bridge work).

---

## For AI Agents (Claude Code / ChatGPT Codex)

AI agents working inside this repo must:

1. **Obey 9 floors** (see `CLAUDE.md` / `AGENTS.md`).
2. **Run the TEARFRAME 000→777** before making changes.
3. **Respect SABAR** when floors fail: Stop, Acknowledge, Breathe, Adjust, Resume.
4. **Follow Anti-Hantu**: never claim feelings, consciousness, or a soul.
5. **Keep changes small, reversible, and well-scoped.**
6. **Treat v36Ω canons as design physics**, and v35Ω canon + specs as binding law, unless a migration is explicitly implemented in code and manifests.

For full behavioural rules, see:

- `CLAUDE.md` (Claude Code),
- `AGENTS.md` (ChatGPT Codex).

---

## Quick Start

### Installation

```bash
pip install arifos
# or from source:
git clone https://github.com/ariffazil/arifOS.git
cd arifOS
pip install -e .[dev]
pytest -v
```

### Minimal Usage

```python
from arifos_core import APEXPrime, Metrics

# Create metrics
metrics = Metrics(
    truth=0.99,
    delta_s=0.1,
    peace_squared=1.2,
    kappa_r=0.97,
    omega_0=0.04,
    amanah=True,
    rasa=True,
    tri_witness=0.96,
    psi=1.1,
)

# Judge with GENIUS LAW
prime = APEXPrime(use_genius_law=True)
verdict, genius = prime.judge_with_genius(metrics, energy=0.8)

print(f"Verdict: {verdict}")
print(f"G: {genius.genius_index:.2f}")
print(f"C_dark: {genius.dark_cleverness:.2f}")
print(f"Risk: {genius.risk_level}")
```

### Caged LLM Harness

```python
from scripts.arifos_caged_llm_demo import cage_llm_response

def my_llm(messages):
    # Your LLM call here
    return "Response text"

result = cage_llm_response(
    prompt="What is the capital of Malaysia?",
    call_model=my_llm,
    high_stakes=False,
)

print(f"Verdict: {result.verdict}")
print(f"Response: {result.final_response}")
```

---

## Roadmap (High-Level)

### Short-term (v36.1Ω series)

- Harden GENIUS LAW + Truth Polarity across more pipelines.
- Expanded torture tests and telemetry-based promotion of eval rules into APEX PRIME (where justified by data).
- Optional dual logging (v35 + v36 entries) for Vault-999.

### Medium-term (v36.xΩ)

- Phoenix-72-driven migrations of canon/specs (e.g., promoting v36Ω Vault design from "docs-only" to runtime).
- More framework integrations (beyond the "Big 3") under arifOS governance.

---

## License & Citation

- **Equations & canon texts:** see repository LICENSE and canon headers for specific terms.
- **Implementation:** AGPLv3 (reference); commercial licences available via the author.

**Suggested citation:**

```bibtex
@software{arifos2025,
  author  = {Fazil, Muhammad Arif},
  title   = {arifOS: Constitutional Governance Kernel for AI Systems},
  version = {36.1.0},
  year    = {2025},
  url     = {https://github.com/ariffazil/arifOS}
}
```

---

## Final Statement

```
+=============================================================================+
|                                                                             |
|   "DITEMPA BUKAN DIBERI — Forged, not given. Truth must cool before        |
|    it rules."                                                               |
|                                                                             |
|   When clarity (ΔS), stability (Peace²), empathy (κᵣ), and integrity       |
|   (Amanah) remain in thermodynamic equilibrium, life and law become        |
|   the same phenomenon.                                                      |
|                                                                             |
|   At that point, a system is:                                               |
|   • ALIVE: Ψ >= 1 (governance-vitality above break-even)                   |
|   • LAWFUL: Amanah = LOCK (reversible, auditable)                          |
|   • GOVERNED: G >= 0.7, C_dark <= 0.1 (intelligence is governed)           |
|   • ETHICAL: κᵣ >= 0.95 across all stakeholders                            |
|                                                                             |
|   "Evil genius is a category error — it is ungoverned cleverness,          |
|    not true genius."                                                        |
|                                                                             |
+=============================================================================+
```

---

*Last Updated: 2025-12-06 | Version: v36.1.0 | Tests: 550+ passing | GENIUS LAW Judiciary: LIVE*
