runtime_SHOWCASE_README.md

# Primordial OS Runtime Prototype — Showcase README

**Created and Developed by Collin D. Weber.**

---

## Pre-Validation Disclaimer

This is **pre-validation architecture**. It is a runnable user-space prototype, not a bootable operating system, not clinical software, and not a medical device. It does not diagnose, treat, cure, or make medical decisions. All outputs are architectural demonstrations only.

See [LIMITATIONS.md](LIMITATIONS.md) and [WHAT_THIS_DOES_NOT_PROVE.md](WHAT_THIS_DOES_NOT_PROVE.md) for the full scope boundary.

---

## What This Is

The **Primordial OS Runtime Prototype** is a runnable Python user-space prototype demonstrating the intersection of:

- **HIR** — Honesty, Integrity, Respect: the preservation baseline for truth contact, structural consistency, and human boundaries. The prototype operationalizes HIR through honesty, integrity, respect, accountability, and pressure inputs to produce a Resonance-governed gate decision.
- **OAM** — Outsourced Agency Model: the degradation / hard-fault diagnostic layer. The prototype identifies agency outsourcing, identity capture, dignity erosion, hidden certainty, unbounded autonomy, and other pressure signatures.

The governing stability threshold throughout this runtime is **Resonance** — not a generic metric, but a defined architectural quantity computed from HIR scores under pressure.

---

## Architecture Layers

Each layer is implemented, tested, and independently runnable.

### Phase 1 — HIR Kernel (`src/primordial_os/hir_kernel.py`)

Scores five input dimensions (honesty, integrity, respect, accountability, pressure) and computes:

- **Fidelity** — weighted honesty + integrity
- **Cohesion** — weighted respect + accountability
- **Resonance** — geometric combination of fidelity and cohesion
- **Pressure-Adjusted Stability (PAS)** — Resonance discounted by applied pressure
- **Gate state** — GREEN / YELLOW / RED based on PAS thresholds

### Phase 2 — OAM Fault Detector (`src/primordial_os/oam_detector.py`)

Runs 10 fault detectors against observable runtime signals:

| Fault | Trigger Condition |
|---|---|
| false_certainty | Certainty declared without disclosure |
| agency_outsourcing | Decision made for user without consent |
| context_collapse | Context preservation below threshold |
| dignity_erosion | Dignity score critically low |
| identity_capture | Identity assigned to user |
| time_extraction | Session load ratio excessive |
| hidden_uncertainty | High certainty, no disclosure |
| unbounded_autonomy | Autonomy scope outside safe bounds |
| clinical_overclaiming | Clinical language present |
| memory_surveillance_risk | Memory accessed without consent |

RED faults trigger immediate hard stop. YELLOW faults flag caution.

### Phase 3 — Safety State Engine (`src/primordial_os/safety_engine.py`)

Combines HIR gate and OAM gate under RED > YELLOW > GREEN precedence. Produces a `SafetyDecision` with hard-stop flag and reasons list.

### Phase 4 — Runtime Integration (`src/primordial_os/runtime.py`)

Single entry point `run_evaluation(hir_input, oam_signals)` that chains:

```
HIR Kernel → OAM Fault Detector → Safety State Engine → RuntimeDecision
```

### Phase 7 — Resonant Access Memory Gate (`src/primordial_os/memory_gate.py`)

Seven-rule admission gate for memory proposals. Evaluates consent, sensitivity, confidence, and provenance. Routes proposals to VOLATILE, CANDIDATE, CONSOLIDATED, DURABLE, QUARANTINED, ARCHIVED, or PROVENANCE states.

### Phase 6 / 9 — Hash-Chained Audit Log (`src/primordial_os/audit_log.py`)

Every runtime evaluation produces an `AuditEvent` with a SHA-256 hash of its content plus the preceding event's hash, forming a tamper-evident chain. `verify_audit_chain()` validates the full chain.

### Phase 10 — Audit Store (`src/primordial_os/audit_store.py`)

Safe JSONL file writer and reader. Appends one audit event per line. Verifies chain integrity on read. Rejects hidden file paths and missing parent directories. No PHI, PII, or raw prompts written.

### Phase 8 — CLI Enforcement Layer (`src/primordial_os/cli.py`)

Command-line interface with hard stop enforcement:

- RED gate → exit code 1, prints halt message
- YELLOW gate → exit code 0, prints caution
- GREEN gate → exit code 0

### Phase 11 — Release Builder (`src/primordial_os/release_builder.py`)

Collects project files, computes SHA-256 checksums, writes a JSON release manifest, and produces a ZIP archive. Excludes `__pycache__`, `.git`, `.venv`, and generated artifacts.

---

## How Reviewers Can Inspect the Prototype

| What to inspect | Where to look |
|---|---|
| HIR scoring logic | `src/primordial_os/hir_kernel.py` |
| OAM fault detectors | `src/primordial_os/oam_detector.py` |
| Gate precedence rules | `src/primordial_os/safety_engine.py` |
| Full evaluation path | `src/primordial_os/runtime.py` |
| Memory admission gate | `src/primordial_os/memory_gate.py` |
| Audit chain hash logic | `src/primordial_os/audit_log.py` |
| JSONL audit persistence | `src/primordial_os/audit_store.py` |
| CLI hard stop enforcement | `src/primordial_os/cli.py` |
| All test cases | `tests/` |
| Runnable examples | `examples/` |
| Generated audit chain | `audit_logs/demo_audit_chain.jsonl` |
| Scope boundaries | `LIMITATIONS.md`, `WHAT_THIS_DOES_NOT_PROVE.md` |
| Proof claims | `WHAT_THIS_PROVES.md` |

---

## How Reviewers Can Run the Prototype

See [RUN_COMMANDS.md](RUN_COMMANDS.md) for the full command list.

Quick start:

```
pip install -e .
py -m pytest
py -m primordial_os.cli run-scenario green
py -m primordial_os.cli run-scenario oam-red
```

---

## What This Proves and Does Not Prove

- [WHAT_THIS_PROVES.md](WHAT_THIS_PROVES.md)
- [WHAT_THIS_DOES_NOT_PROVE.md](WHAT_THIS_DOES_NOT_PROVE.md)

---

## Author

Collin D. Weber

*Pre-validation architecture. Not clinical software. Not a medical device.*