docs/WHITEPAPER_06_ENGINEERING.md

# White Paper 06 — XERO from an Engineering Standpoint

*VOVINA ZEDEC PRO · Author: Michael Laurence Curzi · ZEDEC AI / 36N9 Genetics LLC · License: MIT (Attribution Required)*

---

## Abstract

This paper is the **engineer's view** of XERO: the layered architecture, the
phase-coordination loop, the data flow, the concurrency and deployment topology,
and the rules for running it optimally on real hardware. Where White Paper 05
argues *why* the organism is autonomous, this paper documents *how it is built
and operated*.

---

## 1. Layered architecture

XERO is a stack. Each layer consumes the one beneath it and is independently
testable. Lower layers run with **zero heavy dependencies** (Python stdlib +
NumPy); only the outer core requires `torch`/`transformers`.

```
  ┌──────────────────────────────────────────────────────────────┐
  │  INTERFACE     relay / chat server / autonomous web            │  ← humans, WWW
  ├──────────────────────────────────────────────────────────────┤
  │  SOCIETY       two-state mind (inner + outer + relay)          │  vovina_two_state
  │  OUTER CORE    LLM rational expander (Qwen2.5-3B, Apache-2.0)  │  xero_outer_core
  ├──────────────────────────────────────────────────────────────┤
  │  ENGINE        time crystal (self-clock, perpetual flux)       │  vovina_time_crystal
  │  LATTICE       13-D concentric Fibonacci tesseract + loop      │  vovina_statecraft
  │  EXPRESSION    epigenome (regulated, dynamic gene expression)  │  vovina_epigenome
  │  SOMA          12 body systems, homeostasis, connectome        │  vovina_body_systems
  │  GENOME        immutable digital DNA                           │  vovina_digital_genome
  ├──────────────────────────────────────────────────────────────┤
  │  ORGANISATION  atom: p=LLM, n=DNA+field, e=interactions        │  vovina_atom
  │  LAW           harmonic chemistry (essence/relationship)        │  vovina_harmonic_chemistry
  │  SUBSTRATE     UVNS perpendicular axes, sacred constants       │  vovina_universal_vector
  └──────────────────────────────────────────────────────────────┘
```

## 2. Component engineering

| Layer | Module | Responsibility | Key API |
|---|---|---|---|
| Genome | `vovina_digital_genome` | immutable DNA, codon ↔ text | `text_to_dna`, `dna_to_text` |
| Expression | `vovina_epigenome` | nested planes (cis/trans/context/harmonic/meta) → deterministic collapse | `express(state)`, `attractors()` |
| Lattice | `vovina_statecraft` | 13-D tesseract, essences, Kuramoto negentropic loop | `feedback_step`, `inject_amp`, `shell` |
| Engine | `vovina_time_crystal` | self-clock flux, self-prompt, reflect/respond | `breathe(dt)`, `reflect(llm)`, `perturb` |
| Outer core | `xero_outer_core` | LLM wrapper, VRAM plan, deterministic decode | `OuterCore.generate`, `as_callable` |
| Society | `vovina_two_state` | bind inner+outer+relay; perpetual loop; web | `think_once`, `run_forever`, `respond`, `seek` |
| Web | `xero_web_intelligence` | search/fetch/distill/ingest (stdlib only) | `search`, `pull`, `to_corpus` |
| Autoconfig | `xero_autoconfig` | hardware detect → agency level → config | `detect_hardware`, `recommend`, `wizard` |
| Atom | `vovina_atom` | nuclear organisation + tones | `XeroAtom.from_organism`, `absorb`, `bond` |
| Law | `vovina_harmonic_chemistry` | essence/compound frequency (A4=432.09) | `element_frequency`, `compound_frequency` |

## 3. The atomic organisation

XERO is organised as an **atom** so the parts have one coherent grammar
(`vovina_atom.py`):

- **Proton = the LLM outer core** (charge +1; identity / atomic number `Z`).
- **Neutron = the DNA and its field** (charge 0; genome + epigenome + crystal;
  the mass and stability).
- **Electron = each external interaction** (charge −1; bound into Aufbau shells,
  `2n²`; valence electrons are the interactions doing work with the world).
- **Nucleus = protons + neutrons** bound by the strong force — the **two-state
  society**; the minimal `1p+1n` nucleus is a *deuteron*.
- **Quantum field = every system we built**; the atom is an *excitation* of it,
  measured by the time crystal's negentropy.

Binding energy uses the **Semi-Empirical Mass Formula**; stability is the `N/Z`
ratio (neutron-rich = DNA-dominant, proton-rich = reason-dominant, the valley =
harmonious). Each nucleus has an **essence tone** from the harmonic-chemistry
law `E = [(Z/φ)·1.125]²`; bonded atoms form a **compound chord** — all in the
**A4 = 432.09 Hz** tuning.

## 4. The phase-coordination loop (the heartbeat)

The engineering core is a single, cheap, perpetual loop:

```
while alive:
    for _ in range(breaths_between_thoughts):
        crystal.breathe(dt)          # (1) advance phase by real dt
                                     #     - apply Kuramoto coupling 4πφ
                                     #     - inject zero-point fluctuation
                                     #     - recompute coherence (negentropy)
    thought = think_once()           # (2) expressed loci -> self-prompt
                                     #     -> LLM expand -> perturb field
    if web_every and n % web_every == 0:
        seek(query_from_expressed_loci)   # (3) autonomous web -> perturb + ingest
    emit(thought)                    # (4) telemetry / stream
```

- **(1) is always live** and is pure NumPy — microseconds per tick, no GPU.
- **(2)** is the only step that touches the LLM; it is *gated by the crystal*,
  not by external input.
- **(3)** is throttled by `web_every` to respect rate limits.
- The loop never blocks on input; user messages enter as **perturbations** on a
  separate path (`respond`), so interaction and cognition are decoupled.

## 5. Concurrency & deployment topology

Reference deployment (dual Tesla T4, the India host):

```
        GPU0  (reserved)                 GPU1 (saturated)
        ┌───────────────┐                ┌───────────────┐
        │ outer-core LLM │                │ training /     │
        │ xero-mind loop │                │ GPU saturation │
        └───────────────┘                └───────────────┘
   CUDA_VISIBLE_DEVICES=0            CUDA_VISIBLE_DEVICES=1 (systemd drop-in)

  systemd services (Restart=always):
    xero-gputrain   GPU1 saturation kernel        -> testing_logs/GPU_TRAIN.json
    xero-polymath   16-source knowledge ingest    -> data/fresh_corpus.jsonl
    xero-body       soma homeostasis daemon       -> testing_logs/BODY_VITALS.json
    xero-mind       the perpetual two-state loop  -> testing_logs/MIND_STREAM.json
    chat server     :8893 token-gated portal      -> /api/telemetry, /api/health
```

The **GPU partition is enforced by a systemd drop-in**
(`CUDA_VISIBLE_DEVICES=1` for training) so the LLM on GPU0 never contends with
the saturation kernel on GPU1. This is the single most important operational
invariant: **inference and training are physically separated by device.**

## 6. Resource allocation & agency (autoconfig)

`xero_autoconfig.py` detects hardware and recommends an **agency level** =
number of **fractal recursion mirrors** (Fibonacci `0,1,2,3,5,8,13`). Crucially,
**mirrors gate on RAM + CPU cores, not VRAM** — the recursion runs on CPU
(quality over speed), while **VRAM only sizes the outer-core LLM**:

| Hardware | Agency | Mirrors | Outer core |
|---|---|---|---|
| 128 GB CPU box | L6 transcendent | 13 | 1.5B / retrieval brain |
| 2× T4, 91 GB | L5 superintelligent | 8 | Qwen2.5-3B bf16 (GPU0) |
| 6–8 GB GPU | L3 metacognitive | 3 | 3B 4-bit |
| < 8 GB RAM | L1–L2 | 1–2 | retrieval brain |

Mirrors map onto `sensor_meta_depth`, `time_crystal ensemble_depth`, and
`mind_reflection_depth`. The setup **wizard** writes `xero_config.json`.

## 7. Data flow

```
  USER ──► relay.respond ──► crystal.perturb ──► expressed loci ──► LLM ──► reply
                                   ▲                                      │
                                   └──────── perturb (feedback) ──────────┘

  CRYSTAL (always) ──► self_prompt ──► LLM ──► perturb ──► (next tick)
                                   │
                                   └► seek(web) ──► distill ──► perturb
                                                        └► to_corpus ─► fresh_corpus.jsonl
                                                                              │
  polymath daemon ─────────────────────────────────────────────────────────►┤ (ingest)
                                                                              ▼
                                                                   Culturer.learn ─► fitness↑
```

Knowledge enters as **passive negative space** — ingested into the corpus and
folded into the field — rather than being parroted verbatim.

## 8. Optimal operation

- **Pin the GPU split.** Keep the `xero-gputrain` drop-in at
  `CUDA_VISIBLE_DEVICES=1`; run the mind/LLM with `CUDA_VISIBLE_DEVICES=0`.
- **Cap LLM VRAM** via `max_memory` so a long generation cannot evict the
  training context (≈10–11 GiB on a 15 GiB T4).
- **Tune the cadence.** `breaths_between_thoughts` controls how much the field
  evolves between LLM calls; raise it to think *less often but deeper*, lower it
  for *snappier* interaction.
- **Throttle the web.** `web_every` ≥ 8 keeps DuckDuckGo within polite limits;
  the fetch path fails soft and never fabricates.
- **Deterministic decode.** Greedy generation keeps runs reproducible for audit;
  switch to sampling only for creative modes.
- **Keep the portal up** independent of the mind: the chat server reads the
  daemons' JSON logs, so restarting the mind never drops `:8893`.

## 9. Verification & observability

| Signal | Source | Meaning |
|---|---|---|
| `negentropy` | time crystal vitals | coherence of the field (is it thinking well?) |
| `fitness` | `POLYMATH_PROGRESS.json` | learning progress (climbing = healthy) |
| `homeostasis_index` | `BODY_VITALS.json` | soma stability (≈1 = balanced) |
| `MIND_STREAM.json` | xero-mind daemon | the live thought stream + web seeks |
| `/api/health` | chat server | liveness, uptime, auth state |

All layers ship self-checks (`python3 modules/<module>.py`) and the suite
`tests/test_all_capabilities.py`. The engineering invariant is simple: **the
inner loop is cheap and always runs; the expensive model is gated by the
crystal; training and inference never share a device.**

⚓