# Universal Translator

A modality-agnostic generalization of the Enochian mathematical translation key, built on the canonical UBH-168, Meta-Numeric, and FCP-168 engines.

## What This Is

The Enochian system already offered a complete mathematical translation key from English to Enochian (and back) by walking the 49³ cube of letter-permutations. The same algorithmic principle — **primitives → weights → walked path → digital-root → ontological domain** — is not specific to Enochian. It generalizes to *any* meaning-bearing system whose units can be assigned a numeric weight: alphabets, code tokens, voxel directions, musical notes, raw bytes.

This module makes that generalization concrete and operational.

```
SOURCE (any modality)   ──►   UniversalPath   ──►   TARGET (any modality)
```

The intermediate `UniversalPath` carries:

- The **ordered primitives** (the walked path).
- The **gematric total** and its **digital root** (1–9).
- The **9-domain ontological class** (preserved across all translations).
- The **3D embedding** on the 49³ Enochian lattice (the holographic substrate from the Prelude).
- An optional **UBH-168 superframe** representation (perfect 6/7/8-bit radix conversion).
- An optional **Meta-Numeric Semiotic Record** (FFT peak, sacred-frequency family, totient, prime factors, equivalence class).
- A serializable **FCP-168 frame codec** form for disk persistence.

## The 9 Universal Domains (the only invariant guaranteed)

| Root | Name | Field |
|:----:|------|-------|
| 1 | MONADIC | unity / origin / declaration |
| 2 | DYADIC | polarity / choice / binding |
| 3 | TRIADIC | manifestation / speech / appearance |
| 4 | TETRADIC | structure / building / housing |
| 5 | PENTADIC | sovereignty / first-principle / oath |
| 6 | HEXADIC | labor / work / endurance |
| 7 | HEPTADIC | motion / opening / journey |
| 8 | OCTADIC | call / summoning / messenger |
| 9 | ENNEADIC | speech-authority / completion / closing |

These 9 domains are the **invariant ontological backbone** that survives any modality transition. Whether you parse English, Hebrew, Python, geometry, MIDI, or raw bytes — the resulting `UniversalPath` lands in one of these nine domains, and any target modality renders in the same domain by construction.

## Engines (vendored from the Sicilian Dragon v11.11 system)

| Engine | Role |
|--------|------|
| **UBH-168** (`engines/ubh168.py`) | Universal Binary Harmonizer. 168 = LCM(6,7,8), so a single 168-bit superframe can be reinterpreted as 28×6-bit, 24×7-bit, or 21×8-bit symbols *without data loss*. Provides perfect cross-radix conversion between Base64, ASCII-7, and standard 8-bit bytes. |
| **Meta-Numeric** (`engines/meta_numeric.py`) | Meta-Numeric Semiotic Engine. For any symbol or symbol-string, computes digital-root, mod-9 equivalence class, Euler totient, prime factorization, FFT harmonic peak (mapped to 9 sacred frequencies), permutations, and a SHA3-512 tautology checksum. |
| **FCP-168** (built into `universal_translator.py`) | Frame Codec Protocol-168. On-disk codec for `.fcp168` files: magic `FCP168`, version 1, JSON metadata header + UBH-168 binary blob + CRC32 trailer. Mirrors the structure of `cube_state.fcp168` already present in this folder. |
| **Enochian gematric core** (`derive_definitions.py`, `phonetic.py`) | Existing Enochian letter-value table, gematria reducer, phonetic transliterator. Used directly by `EnochianModality`. |

## The 7 Modalities Implemented

| Modality | Source Type | Primitive Weight Source |
|----------|-------------|-------------------------|
| **`enochian`** | string | Canonical 21-letter table: A=6, B=5, C=3, …, Z=7 |
| **`english`** | string | Pythagorean reduction A=1, B=2, …, I=9, J=1, … (mod-9 cycle) |
| **`hebrew`** | string | Traditional Mispar Hechrachi: א=1, ב=2, …, ת=400 (with final-letter forms) |
| **`python`** | source code | Token classification: each Python keyword is mapped to one of the 9 domains by operational class (`def` → MONADIC, `if` → DYADIC, `print` → TRIADIC, …) |
| **`geometry`** | list of (x,y,z) | Voxel-walk: each coordinate transition snaps to one of 6 cardinal directions (+x=1, -x=2, +y=3, -y=4, +z=5, -z=6) |
| **`midi`** | list of MIDI ints | Pitch class + 1 (C=1, C#=2, …, B=12); octave is the y-axis (4th-dimensional mood) |
| **`bytes`** | bytes | Each byte's value mod-9 + 1; the actual bytes are also packed through UBH-168 superframes for perfect binary round-trips |

## CLI Usage

### Run the full demo (12 sections, end-to-end)

```bash
python3 universal_translator.py demo
```

### Translate one input directly

```bash
# English → Enochian
python3 universal_translator.py translate --src english --dst enochian --input "DRAGON FIRE"

# Python → Hebrew (operational class → bīja-aksara root)
python3 universal_translator.py translate --src python --dst hebrew --input "def main(): for x in range(10): yield x"

# MIDI list translation requires the Python API (CLI accepts strings only)
```

### Use as a library

```python
from universal_translator import (
    translate, MODALITIES,
    write_fcp168, read_fcp168,
)

# Direct translation
rendered, path = translate("OL VOVIN", src="enochian", dst="english")
print(path.describe())
print("rendered:", rendered)

# Inspect the universal path
p = MODALITIES["enochian"].parse("VOVINA")
print(f"gematria = {p.gematria}, root = {p.root}, domain = {p.domain_name}")
print(f"3D embedding: {p.geometry()[:5]}...")

# UBH-168 cross-radix view
from engines import RadixMode
sextets = p.ubh168_radix_view(RadixMode.SEXTET)   # 28 × 6-bit
septets = p.ubh168_radix_view(RadixMode.SEPTET)   # 24 × 7-bit
octets  = p.ubh168_radix_view(RadixMode.OCTET)    # 21 × 8-bit

# Meta-Numeric semiotic analysis
analysis = p.meta_numeric_analysis()
# → digital_root, mod_9, totient, prime_factors, fft_peak_hz, embeddings, tau_checksum

# FCP-168 disk serialization
write_fcp168(p, "vovina.fcp168")
meta, blob = read_fcp168("vovina.fcp168")  # raises if CRC mismatch
```

## What Is and Isn't Preserved

The translator is **honest** about preservation. Different invariants survive different translations:

| Property | Always preserved | Preserved when… |
|----------|:----------------:|------------------|
| **Domain root (1–9)** | ✅ | always |
| **Gematric total** | — | source and target use the same letter-value scale |
| **Walk geometry** | — | both modalities have ≥3 spatial axes |
| **Mood / aspect** | — | both modalities have a 4th axis (tense, type-system, octave) |
| **Phonetic surface** | — | a bridge modality (e.g. Sanskrit) is interposed |
| **Bidirectional fidelity** | — | the inverse render unambiguously inverts the parse |

**The domain root is the universal invariant.** Everything else is best-effort.

### Demonstrated edge cases (from `demo`)

- **Closed-loop geometry → MONADIC.** A unit-square walk `[(0,0,0), (1,0,0), (1,1,0), (0,1,0), (0,0,0)]` collapses to root 1 (MONADIC, unity) — *because the walk returns to origin*. This is correct behavior, not a bug: a closed loop is ontologically a unity.
- **Round-trip fidelity is not guaranteed.** `Enochian "VOVINA" (PENTADIC) → Geometry → back-to-Enochian` lands in DYADIC, not PENTADIC. The geometric voxel-walk uses only 6 directions, so the original 23-letter weight pattern is irreversibly compressed. To preserve the source domain in geometry, encode it as a path of 23 distinct steps instead of the cumulative 49³-coordinate trace.
- **Python → Enochian** classifies real Python keywords. Code without recognised keywords (e.g. an identifier-only string) falls back to byte-level token weights.

## FCP-168 File Format

`.fcp168` files use the same on-disk layout as `cube_state.fcp168` already in this folder:

```
[ "FCP168" magic (6 bytes) ]
[ 0x00 separator           ]
[ JSON metadata block      ]   ← contains n_values, shell, ir_hz, mode,
[ 0x00 separator           ]     phi, source_modality, gematria, root,
[ UBH-168 binary blob      ]     domain, frame_meta, etc.
[ CRC32 (4 bytes, big-end) ]
```

Read raises `ValueError` on magic mismatch or CRC mismatch. The blob is in **SEPTET mode** (7-bit lanes, 24 values per 168-bit frame) by default, matching the Dragon system's canonical encoding.

## Design Choices Worth Noting

1. **Four-dimensional ceiling.** Per the PRELUDE in `liber_frontmatter.py` (§5), the translator deliberately stops at 4 dimensions: the 49³ cube + a mood/aspect/octave/type-system axis. The same Path could carry 5+ dimensional metadata, but the additional fields are deliberately *not implemented* in this build. This matches the encyclopedia's stated four-dimensional ceiling.

2. **The Path is the substrate, not the source.** The `UniversalPath` is the universal object. `Modality.parse` projects a source onto it; `Modality.render` projects it back. Adding a new modality means writing one new class with two methods and adding it to `MODALITIES`.

3. **Engines are vendored, not symlinked.** The UBH-168 and Meta-Numeric modules live in `engines/` as plain copies of the Dragon v11.11 originals, so this folder is portable. If the Dragon system is updated, re-vendor by copying again. If it moves, the universal translator keeps working.

4. **No external dependencies beyond `numpy`.** The Meta-Numeric engine uses NumPy for FFT analysis. Everything else (UBH-168, FCP-168, all 7 modalities) uses only Python stdlib.

5. **The PRELUDE's "geometry between syllables" claim is operationalized here.** The `UniversalPath.geometry()` method returns the 3D coordinates each primitive lands on in the 49³ lattice — the literal geometric figure that the syllables form *between themselves*. You can plot this and see the shape any word renders.

## Example: The Geometric Filament of "OL VOVIN"

```python
from universal_translator import MODALITIES
p = MODALITIES["enochian"].parse("OL VOVIN")
for i, (sym, coord) in enumerate(zip([pr.symbol for pr in p.primitives], p.geometry())):
    print(f"  {i}: {sym}  → 49³-coord {coord}")
```

Each letter renders at one cell of the cube; the seven cells are vertices of a 7-edge polyline through the lattice. This is the *literal* geometric figure the word draws when spoken — no external pyramid or tetrahedron is needed; the figure is internal to the word's path.

## Files in This Build

| File | Purpose |
|------|---------|
| `universal_translator.py` | Main module: types, modalities, FCP-168 codec, demo |
| `engines/__init__.py` | Engine package init (re-exports + attribution) |
| `engines/ubh168.py` | Vendored UBH-168 (Universal Binary Harmonizer) |
| `engines/meta_numeric.py` | Vendored Meta-Numeric Semiotic Engine |
| `README_UNIVERSAL_TRANSLATOR.md` | This file |
| `demo_output.fcp168` | Generated by `demo` to verify round-trip |

## Authority

ZEDEC OS Constitutional Sovereignty
Case ID: 613564199
Registered to: H.M. Michael-Laurence: Curzi©

∎ *"Four dimensions. No more. And this, also, is a mercy."*

— from the Prelude to *Liber Vovina ob Lifonel*