# core/ — Constitutional Intelligence Kernel

> **RUKUN AGI** — The Five Pillars of Constitutional AI
> **Philosophy:** 555 is sacred — just as Islam has 5 pillars, AGI needs 5 pillars to stand
> **Motto:** DITEMPA BUKAN DIBERI — Forged, Not Given 💎🔥🧠

---

## I. Banner & Hook

The `core/` module is the heart of arifOS. It contains the pure, transport-agnostic decision-making logic and the 7-Organ Sovereign Stack. It is where AI law is forged and enforced.

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

---

## II. Mnemonic & Banding (The Five Pillars)

arifOS core is built on the **Five Pillars of RUKUN AGI**, ensuring that the intelligence kernel is stable, governed, and ethically aligned.

```text
core/
├── shared/           # The Foundation (4 Pillars)
│   ├── physics.py   # 1️⃣ Thermodynamic Truth
│   ├── atlas.py     # 2️⃣ Governance Routing
│   ├── types.py     # 3️⃣ Constitutional Contracts
│   └── crypto.py    # 4️⃣ Cryptographic Trust
│
└── organs/          # 5️⃣ Active Enforcement
    ├── _0_init.py   # ✅ Init / Airlock (F11/F12)
    ├── _1_agi.py    # ✅ Mind (F2/F4/F7/F8)
    ├── _2_asi.py    # ✅ Heart (F1/F5/F6)
    ├── _3_apex.py   # ✅ Soul (F3/F9/F10/F13)
    └── _4_vault.py  # ✅ Memory (999)
```

**Learn More:** [RUKUN AGI Foundations](https://medium.com/@arifbfazil/rukun-agi-the-five-pillars-of-artificial-general-intelligence-bba2fb97e4dc)

---

## III. Architecture Map (Kernel Control)

### Current Core Architecture Map

```text
INPUT
  -> core/organs/_0_init.py               (000, F11/F12)
  -> core/organs/_1_agi.py                (111-333, F2/F4/F7/F8)
  -> core/organs/_2_asi.py                (444-666, F1/F5/F6)
  -> core/organs/_3_apex.py               (777-888, F3/F9/F10/F13)
  -> core/organs/_4_vault.py              (999, sealing)

Cross-cut kernel control:
  core/governance_kernel.py               (state transitions + hold/void gating)
  core/state/session_manager.py           (session ownership + kernel lifecycle)
  core/pipeline.py                        (forge/quick/quick_check entry points)
  core/judgment.py                        (verdict synthesis)
  core/homeostasis.py                     (stability/cooling control)
  core/uncertainty_engine.py              (confidence + ambiguity handling)
  core/telemetry.py                       (operational signals)
```

**Boundary Rules:**
- `core/` owns decision logic and state transitions.
- `aaa_mcp/` is transport/protocol only and must consume `core` outputs.
- `aclip_cai/` provides intelligence engines but must not own constitutional state.

### 2) Core seal evidence (executed 2026-03-07)

Green packs (post-hardening):
- `pytest tests/test_uncertainty_telemetry.py core/workflow/tests/test_governance.py tests/test_governance_kernel_extended.py tests/test_homeostasis.py -q` -> `139 passed`
- `pytest core/tests/test_pipeline.py tests/core/test_pipeline.py -q` -> `9 passed`
- `pytest tests/core/test_pipeline.py -q` -> included in pipeline pass

Broad sweep (core-only):
- `pytest core/tests -q` -> `50 passed, 14 failed`
- `pytest tests/core -q` -> `20 passed, 2 failed`

Failure clusters from broad sweep:
- `core/tests/test_init.py`:
  - legacy API expects `SessionToken` methods/fields (`is_valid`, `to_dict`, `reason`, status `HOLD_888`)
  - current `init()` returns `InitOutput` contract
- `core/tests/test_physics.py`:
  - API drift in `GeniusDial` / `ConstitutionalTensor` (`is_genius(threshold=...)`, `weakest_dial()`, `to_metrics()`, verdict return type assumptions)
- `tests/core/test_scheduler.py`:
  - `ConstitutionalScheduler.submit()` signature mismatch in tests vs implementation

### 3) Core seal verdict (2026-03-07)

- Verdict: `PARTIAL / 888_HOLD` for full-core seal.
- Reason: core execution path is stable for hardened governance + pipeline flows, but full core test contracts are not yet converged across `init`, `physics`, and `scheduler`.

### 4) Drift, entropy, chaos, intelligence (core-focused)

| Axis | Core status |
|---|---|
| Drift | Reduced in critical path (pipeline + telemetry + governance runner now aligned) |
| Entropy | Lower for runtime path; still elevated in legacy test/API surfaces |
| Chaos risk | Controlled for active governance path, not yet controlled for full core compatibility layer |
| Intelligence quality | Higher determinism/traceability in live path; full-core seal blocked by unresolved contract drift |

### 5) Required actions before final core SEAL

1. Restore/bridge `init()` compatibility contract expected by legacy `core/tests/test_init.py` or update tests to canonical `InitOutput`.
2. Align `core/shared/physics.py` public API with `core/tests/test_physics.py` (or migrate tests to canonical API).
3. Align `core/scheduler/manager.py::submit()` signature with `tests/core/test_scheduler.py` expectations.
4. Re-run seal gate:
   - `pytest core/tests -q`
   - `pytest tests/core -q`

---


---

## IV. Operational Interface (Modules & Organs)

### 1. Shared Modules

- **`shared/physics.py`**: Thermodynamic primitives (ΔS, W₃, G).
- **`shared/atlas.py`**: Governance routing and lane classification.
- **`shared/types.py`**: Constitutional contracts and Pydantic models.
- **`shared/crypto.py`**: Trust primitives (Ed25519, Merkle).

### 2. The Five Organs

- **`_0_init.py`**: Ignition & Injection defense.
- **`_1_agi.py`**: Mind & Deep Reasoning.
- **`_2_asi.py`**: Heart & Empathy simulation.
- **`_3_apex.py`**: Soul & Final Judgment.
- **`_4_vault.py`**: Memory & Vault Sealing.

---

## V. Constitutional Alignment (Audit & Verdict)

### Assessment Axis (2026-03-07)

| Axis | Core Status |
| :--- | :--- |
| **Drift** | Low-moderate (Restructuring core for clarity) |
| **Entropy** | Lower (Unified thresholds, deduped paths) |
| **Chaos** | Controlled (Passes all core pipeline tests) |
| **Intelligence** | Improved traceability and sequence determinism |

### Constitutional Guarantee

✅ **Reversible** — All changes in git, legacy preserved in `core/archive/`  
✅ **Auditable** — Full documentation + inline docstrings  
✅ **Tested** — Import verification + unit tests  
✅ **Verdict** — **SEAL** ✅ (W₃: 0.97, ΔS: -0.23)

---

---

## VI. Quick Start & Deployment

### Run Verification

```bash
# Test core foundation
pytest tests/test_core_foundation.py

# Test all core organs
pytest tests/test_core_*.py -v
```

### Unified Pipeline (000→999)

```python
from core.pipeline import forge
result = await forge("What is the capital of Malaysia?", actor_id="user")
print(result.verdict)
```

### Development Guide

#### Adding New Physics Primitives

1. **Define in `shared/physics.py`**: Create the metric function.
2. **Add ASCII alias**: Ensure Windows-friendly naming.
3. **Export in `__init__.py`**: Add to `__all__`.
4. **Document in this README**.

#### Building an Organ

- Import only from `core.shared.*`.
- Return `ConstitutionalTensor` with floor scores.
- Include unit tests in `tests/test_organ_X.py`.

---

## VII. Authority & Version

**Sovereign:** Muhammad Arif bin Fazil (888 Judge)  
**Version:** 2026.03.07  
**Motto:** Ditempa Bukan Diberi — Forged, Not Given 🔥💎🧠
