# Hachimoji Codec — Library Receipt

**Generated:** 2025-01-15  
**Library:** `hachimoji_codec.py` + `HachimojiCodec.lean`  
**Pipeline:** Equation → Hachimoji State → Logogram Receipt → RRC Admission → Emit

---

## 1. Architecture Overview

```
Equation string (e.g. "E = mc^2")
  │
  ▼
[Step 1: parse_equation]        ──► EquationShape
  │                                 (n_vars, n_ops, max_depth,
  ▼                                  n_quantifiers, n_relations)
[Step 2: classify_hachimoji]    ──► HachimojiState (one of 8)
  │
  ▼
[Step 3: build_receipt]         ──► LogogramReceipt
  │                                 (regime + 5 witness booleans)
  ▼
[Step 4: admit_receipt]         ──► ADMIT / QUARANTINE / HOLD
  │
  ▼
[Step 5: emit_stamped]          ──► AVMIsa.Emit stamped dict
```

---

## 2. Data Structures

### EquationShape

| Field | Type | Description |
|-------|------|-------------|
| `n_vars` | `int` | Distinct variables |
| `n_ops` | `int` | Operator count (including structural) |
| `max_depth` | `int` | Maximum nesting depth |
| `n_quantifiers` | `int` | ∀ / ∃ count |
| `n_relations` | `int` | = / ∈ / ∉ / → count |

### HachimojiState (8 Greek States)

| State | Name | Condition |
|-------|------|-----------|
| Φ | Phi | ≤3 vars, no quantifiers, 1 relation, not symmetric |
| Λ | Lambda | Quantifiers present, max_depth ≤ 2 |
| Ρ | Rho | >5 ops, no quantifiers, ≤10 ops |
| Κ | Kappa | >5 vars, max_depth ≤ 1 |
| Ω | Omega | Contradiction OR (quantifiers > 0 ∧ relations = 0) |
| Σ | Sigma | Palindromic / self-dual / sum-of-squares pattern |
| Π | Pi | >10 ops |
| Ζ | Zeta | Default (undetermined) |

### LogogramReceipt

| Field | Type | Description |
|-------|------|-------------|
| `shape` | `str` | Human-readable state label |
| `status` | `str` | State enum name |
| `regime` | `str` | `beautifulTopologicalFolding` / `tornManifoldRegime` / `horribleManifoldTearing` |
| `payloadBound` | `bool` | Topological folding integrity |
| `contradictionWitness` | `bool` | Active contradiction detected |
| `tearBoundary` | `bool` | Manifold boundary torn |
| `detachedMass` | `bool` | Orphaned symbolic mass |
| `residualLane` | `bool` | Unresolved inference lane |

---

## 3. Regime Table

| State | Regime | payloadBound | contradictionWitness | tearBoundary | detachedMass | residualLane |
|-------|--------|:------------:|:--------------------:|:------------:|:------------:|:------------:|
| Φ | beautifulTopologicalFolding | ✅ | ❌ | ❌ | ❌ | ❌ |
| Λ | beautifulTopologicalFolding | ✅ | ❌ | ✅ | ❌ | ❌ |
| Ρ | tornManifoldRegime | ❌ | ❌ | ✅ | ✅ | ❌ |
| Κ | tornManifoldRegime | ❌ | ❌ | ✅ | ❌ | ✅ |
| Ω | horribleManifoldTearing | ❌ | ✅ | ✅ | ✅ | ✅ |
| Σ | beautifulTopologicalFolding | ✅ | ❌ | ❌ | ❌ | ❌ |
| Π | tornManifoldRegime | ❌ | ❌ | ✅ | ✅ | ❌ |
| Ζ | horribleManifoldTearing | ❌ | ❌ | ❌ | ❌ | ✅ |

---

## 4. Admission Gates

| Gate | Logic | Rejects |
|------|-------|---------|
| **typeAdmissible** | regime ∈ {beautiful, torn, horrible} | never (all regimes recognized) |
| **projectionAdmissible** | payloadBound ∨ (tearBoundary ∧ ¬detachedMass) | Ρ, Κ, Π, Ω, Ζ |
| **mergeAdmissible** | ¬residualLane | Κ, Ω, Ζ |

### Admission Verdict

```
if ¬typeAdmissible      → HOLD
else if ¬projection     → QUARANTINE
else if ¬merge          → QUARANTINE
else                    → ADMIT
```

| State | type | projection | merge | Verdict |
|-------|------|------------|-------|---------|
| Φ | ✅ | ✅ | ✅ | **ADMIT** |
| Λ | ✅ | ✅ | ✅ | **ADMIT** |
| Ρ | ✅ | ❌ | ✅ | QUARANTINE |
| Κ | ✅ | ❌ | ❌ | QUARANTINE |
| Ω | ✅ | ❌ | ❌ | QUARANTINE |
| Σ | ✅ | ✅ | ✅ | **ADMIT** |
| Π | ✅ | ❌ | ✅ | QUARANTINE |
| Ζ | ✅ | ❌ | ❌ | QUARANTINE |

---

## 5. Test Results

| # | Equation | Parsed Shape | State | Regime | Admission | Result |
|---|----------|-------------|-------|--------|-----------|--------|
| 1 | `E = mc^2` | (3 vars, 1 op, depth 0, 0 quant, 1 rel) | Φ | beautiful | ADMIT | ✅ PASS |
| 2 | `a^2 + b^2 = c^2` | (3 vars, 3 ops, depth 0, 0 quant, 1 rel) | Σ | beautiful | ADMIT | ✅ PASS |
| 3 | `∀x. P(x) → Q(x)` | (3 vars, 6 ops, depth 1, 1 quant, 1 rel) | Λ | beautiful | ADMIT | ✅ PASS |
| 4 | `0 = 1` | (0 vars, 0 ops, depth 0, 1 quant, 0 rel) | Ω | horrible | QUARANTINE | ✅ PASS |
| 5 | `∃x. x ∉ x` | (1 var, 3 ops, depth 0, 1 quant, 1 rel) | Λ | beautiful | ADMIT | ✅ PASS |
| 6 | `∫ f(x) dx = F(x) + C` | (4 vars, 12 ops, depth 1, 0 quant, 1 rel) | Π | torn | QUARANTINE | ✅ PASS |

**Overall: 6/6 tests passed**

---

## 6. File Inventory

| File | Lines | Purpose |
|------|-------|---------|
| `hachimoji_codec.py` | ~512 | Python library with full pipeline + self-test |
| `HachimojiCodec.lean` | ~290 | Lean 4 formalization with proofs |
| `codec_receipt.md` | — | This documentation receipt |

---

## 7. API Reference (Python)

### `parse_equation(eq_str: str) -> EquationShape`
Tokenizes the equation string and extracts structural metrics.

### `classify_hachimoji(shape: EquationShape, eq_str: str = "") -> HachimojiState`
Maps structural metrics to one of the 8 Hachimoji states.

### `build_receipt(state: HachimojiState) -> LogogramReceipt`
Constructs a fully populated receipt from a state via the regime table.

### `admit_receipt(receipt: LogogramReceipt) -> str`
Runs the three RRC admission gates. Returns `"ADMIT"`, `"QUARANTINE"`, or `"HOLD"`.

### `emit_stamped(receipt: LogogramReceipt, admission: str) -> dict`
Builds the final AVMIsa.Emit stamped output dictionary.

### `equation_to_emit(eq_str: str) -> dict`
**Master function.** Runs the complete pipeline and returns the stamped output.

---

## 8. Determinism Guarantee

The pipeline is **fully deterministic**: the same equation string always produces
the same `HachimojiState`, the same `LogogramReceipt`, and the same admission
verdict. No randomness, no machine learning, no external state.

> *"Same equation → same state → same receipt → same stamp. Every time."*