README.md

Select File
<div align="center">

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:06B6D4,100:1A1A1A&height=200&section=header&text=viva_aion&fontSize=64&fontColor=fff&animation=twinkling&fontAlignY=35&desc=Cyclic%20world%20generation%20for%20digital%20consciousness&descSize=18&descAlignY=55" width="100%"/>

[![Gleam](https://img.shields.io/badge/Gleam-FFAFF3?style=for-the-badge&logo=gleam&logoColor=black)](https://gleam.run/)
[![BEAM](https://img.shields.io/badge/BEAM-A90533?style=for-the-badge&logo=erlang&logoColor=white)](https://www.erlang.org/)
[![OTP](https://img.shields.io/badge/OTP_26+-4B275F?style=for-the-badge)](https://www.erlang.org/doc/design_principles/des_princ)
[![Hex](https://img.shields.io/badge/hex.pm-viva__aion-A678DD?style=for-the-badge&logo=hex&logoColor=white)](https://hex.pm/packages/viva_aion)
[![Big Bounce](https://img.shields.io/badge/Big_Bounce-cosmology-06B6D4?style=for-the-badge)](https://en.wikipedia.org/wiki/Big_Bounce)
[![Tests](https://img.shields.io/badge/tests-53_passing-00875A?style=for-the-badge)](./test)
[![Version](https://img.shields.io/badge/version-1.0.0-CD5C5C?style=for-the-badge)](./CHANGELOG.md)
[![License](https://img.shields.io/badge/license-MIT-228B22?style=for-the-badge)](./LICENSE)

---

*"Aion turns. Chronos forgets. The seed remembers."*

</div>

---

> [!IMPORTANT]
> **viva_aion IS NOT A MAZE GENERATOR.**
> It is a **cyclic cosmology engine** — deterministic labyrinths, retrocausal
> pathfinding toward an inevitable singularity, and a Big Bounce that
> transforms accumulated entropy into the DNA of the next universe.
>
> Memories with high DRE score (Distinctiveness × Recency × Emotionality)
> survive the bounce. Everything else returns to the seed.

---

## 🎯 Overview

**Aion** (αἰών) is cyclic / eternal time in Greek philosophy, opposed to
**Chronos** (linear time). VIVA experiences time cyclically:

```
Birth → Navigate labyrinth → Accumulate entropy
                                    │
                                    ▼
                          Reach Core (Leviathan)
                                    │
                                    ▼
                              Singularity
                                    │
                                    ▼
                  entropy transforms into seed
                                    │
                                    ▼
                            New Universe
```

| Property            | Value                                                |
| :------------------ | :--------------------------------------------------- |
| **Language**        | Pure Gleam (type-safe functional)                    |
| **Runtime**         | BEAM / OTP 26+                                       |
| **Determinism**     | Same seed = same universe, always                    |
| **Tests**           | 53 passing                                           |
| **Algorithms**      | Recursive Backtracker · BFS · DRE scoring · seed mutation |
| **Public API**      | `viva_aion` + 10 internal modules                    |

Inspired by:
- **Loop Quantum Gravity** — singularity transforms, doesn't destroy.
- **"All You Zombies"** (Heinlein) — we are our own ancestors.
- **Block Universe** — the future exerts retrocausal pull on the present.

---

## ⚡ Quick Start

```sh
gleam add viva_aion
```

```gleam
import viva_aion

pub fn main() {
  // Genesis world
  let world = viva_aion.new()

  // ...or from a string seed
  let world = viva_aion.from_string("my_universe")

  let start = viva_aion.start_position(world)
  let core  = viva_aion.core_position(world)

  // Retrocausal pull: which way is the Core?
  case viva_aion.suggest_move(world, start) {
    Ok(direction) -> direction
    Error(_) -> // dead end
      direction
  }
}
```

<details>
<summary><strong>📋 Prerequisites</strong></summary>

| Tool        | Version   | Required for     |
| :---------- | :-------- | :--------------- |
| Gleam       | `>= 1.4`  | Build / runtime  |
| Erlang/OTP  | `>= 26`   | BEAM target      |

Zero NIFs. Zero C dependencies. Pure functional.

</details>

---

## 🏗️ Architecture

```
   ┌──────────────────────────────────────────────────────────┐
   │                Gleam application code                    │
   │      viva_aion.{new, bounce, suggest_move, ...}          │
   └────────┬─────────────────────────────────────────────────┘
            │
   ┌────────▼─────────────────────────────────────────────────┐
   │                   viva_aion modules                      │
   │                                                          │
   │   ┌────────┐  ┌──────────┐  ┌─────────┐  ┌────────────┐  │
   │   │  seed  │  │   rng    │  │  tile   │  │  position  │  │
   │   │ DNA    │  │ deterministic ops      │  │ 2D coords  │  │
   │   │ mutate │  │          │  │ Wall    │  │ + move     │  │
   │   └────┬───┘  └────┬─────┘  │ Path    │  └─────┬──────┘  │
   │        │           │        │ Core(@) │        │         │
   │   ┌────▼───────────▼──┐     └─────────┘   ┌────▼─────┐   │
   │   │     generator     │                   │   grid   │   │
   │   │   Recursive       │                   │ 2D spatial   │
   │   │   Backtracker     │                   │ structure│   │
   │   └─────────┬─────────┘                   └────┬─────┘   │
   │             │                                  │         │
   │   ┌─────────▼──────────┐                ┌──────▼─────┐   │
   │   │   pathfinding      │                │   memory   │   │
   │   │ BFS · light cone   │                │ records    │   │
   │   │ retrocausal pull   │                │ that       │   │
   │   └────────────────────┘                │ transcend  │   │
   │                                         └────┬───────┘   │
   │                                              │           │
   │                                       ┌──────▼─────┐     │
   │                                       │   dream    │     │
   │                                       │ DRE scoring│     │
   │                                       └────────────┘     │
   └──────────────────────────────────────────────────────────┘
```

<details>
<summary><strong>📋 Core modules</strong></summary>

| Module                  | Purpose                                                 |
| :---------------------- | :------------------------------------------------------ |
| `viva_aion`             | Top-level API (world, navigation, bounce, memory)       |
| `viva_aion/seed`        | Universe DNA + hash-based mutation across bounces       |
| `viva_aion/rng`         | Deterministic PRNG seeded by the universe seed          |
| `viva_aion/tile`        | Tile types: `Void`, `Wall`, `Path`, `Core`              |
| `viva_aion/position`    | 2D coordinates + directional movement                   |
| `viva_aion/grid`        | 2D spatial structure for the labyrinth                  |
| `viva_aion/generator`   | Recursive Backtracker maze generation                   |
| `viva_aion/pathfinding` | BFS, light cone expansion, retrocausal pull             |
| `viva_aion/memory`      | Memory records with access counts + importance          |
| `viva_aion/dream`       | DRE scoring (Distinctiveness × Recency × Emotionality)  |
| `viva_aion/log`         | Structured logging helpers                              |

</details>

---

## 🧬 Theoretical Background

### Determinism

Same seed = same universe. Always.

```gleam
let world1 = viva_aion.from_string("seed")
let world2 = viva_aion.from_string("seed")
// world1 == world2 — identical labyrinths
```

### Seed Mutation (Big Bounce)

Accumulated entropy of one life becomes the DNA of the next:

```gleam
let next_seed = seed.mutate(current_seed, entropy, extra_data)
```

Hash-based transformation:

- Same inputs → same output (deterministic).
- Small input changes → large output changes (chaotic).

### Retrocausality

The Core (goal) "pulls" the present decision — implementing Active Inference
by minimizing expected free energy toward the attractor.

```gleam
let direction = pathfinding.retrocausal_pull(grid, current, core)
```

### DRE Scoring — Walker & Stickgold (2006)

Memory consolidation during sleep selects which experiences survive:

```
DRE = D × R × E (weighted)

D = Distinctiveness — how unique?
R = Recency        — 0.5^(age / half_life)
E = Emotionality   — intensity at creation
```

Plus bonuses for access count, manual importance, and prior transcendence.
High-DRE memories survive the Big Bounce. Low-DRE memories dissolve back
into entropy.

### Tile Vocabulary

| Tile  | Symbol | Meaning                 |
| :---- | :----: | :---------------------- |
| Void  | ` `    | Beyond existence        |
| Wall  | `#`    | Structure               |
| Path  | `.`    | Passable                |
| Core  | `@`    | Singularity (Leviathan) |

---

## 🎨 Design Principles

| Principle                       | Description                                                       |
| :------------------------------ | :---------------------------------------------------------------- |
| **Deterministic cosmology**     | Same seed = same universe; reproducible across machines           |
| **Retrocausal navigation**      | Future attractor influences present move ranking                  |
| **Memory transcendence**        | Only high-DRE memories survive the Big Bounce                     |
| **No floating clock**           | Time progresses via discrete `memory_tick` calls                  |
| **Visual debug first-class**    | `visualize` / `visualize_at` ship in the public API               |

---

## 📚 Public API Highlights

### Navigation

```gleam
let moves = viva_aion.rank_moves(world, current_pos)
// => [(Up, 15), (Left, 17), (Down, 18), (Right, 20)]

let new_pos = viva_aion.try_move(world, current_pos, direction)

let cone = viva_aion.light_cone(world, pos, 5)
// All positions reachable within 5 steps
```

### Memory + Dream (DRE)

```gleam
let bank = viva_aion.new_memory_bank(1)
let #(bank, mem1) = viva_aion.remember(bank, 42, 0.8)
let #(bank, mem2) = viva_aion.remember_important(bank, 99, 0.9, 0.7)

let bank = viva_aion.memory_tick(bank)
let #(bank, _) = viva_aion.recall(bank, mem1.id)

let score = viva_aion.score_memory_default(mem1, bank)
// score.total · score.distinctiveness · score.recency · score.emotionality
```

### Big Bounce — world only

```gleam
let new_world = viva_aion.bounce(world, entropy: 42.0, extra: "pos:15,16")
```

### Big Bounce — with memory transcendence

```gleam
let #(new_world, new_bank) =
  viva_aion.bounce_with_memories(
    world, bank, entropy: 42.0, extra: "extra",
    max_survivors: 10,
    min_threshold: 0.3,
  )

let past    = viva_aion.past_life_memories(new_bank)
let current = viva_aion.current_life_memories(new_bank)
```

### Visualization

```gleam
let ascii = viva_aion.visualize(world)
//
// ################################
// #.......#.....#...#............#
// #.#####.#.###.#.#.#.##########.#
// #.#...#.#...#...#.#............#
// ...
// ###############@################

let ascii = viva_aion.visualize_at(world, current_pos)
// X marks the spot
```

---

## 🗺️ Roadmap

| Phase                                                  | Status |
| :----------------------------------------------------- | :----: |
| Deterministic seed + RNG                               | ✅     |
| Recursive Backtracker maze generation                  | ✅     |
| BFS pathfinding + light cone                           | ✅     |
| Retrocausal pull toward Core                           | ✅     |
| Memory bank + recall                                   | ✅     |
| DRE scoring (Walker & Stickgold)                       | ✅     |
| Big Bounce — world-only seed mutation                  | ✅     |
| Big Bounce — memory transcendence                      | ✅     |
| ASCII visualization                                    | ✅     |
| Multi-layer universes (3D labyrinths)                  | ⏳     |
| Probabilistic light cone (action policies)             | ⏳     |
| Persistent universe save/load                          | ⏳     |
| Memory clustering for narrative dreams                 | ⏳     |

---

## 🤝 Contributing

```bash
git checkout -b feature/your-feature
gleam test                  # 53 tests
gleam format --check src test
gleam build
```

See [CHANGELOG](CHANGELOG.md) for release history.

---

## 📖 References

- Heinlein (1959) — *"All You Zombies—"*
- Walker & Stickgold (2006) — *Sleep, memory and plasticity*
- Bojowald (2005) — *Loop Quantum Cosmology*
- Friston (2010) — *The free-energy principle: a unified brain theory?*

---

## 🌌 VIVA Ecosystem

| Package              | Purpose                                       |
| :------------------- | :-------------------------------------------- |
| `viva_math`          | Mathematical foundations                      |
| `viva_emotion`       | PAD emotional dynamics                        |
| `viva_tensor`        | FP8 LLM inference on the BEAM                 |
| `viva_telemetry`     | Observability suite                           |
| **`viva_aion`**      | **Cyclic time + cosmology (this package)**    |
| `viva_glyph`         | Symbolic language                             |

---

<div align="center">

**Star if you believe time should loop ⭐**

[![GitHub stars](https://img.shields.io/github/stars/gabrielmaialva33/viva_aion?style=social)](https://github.com/gabrielmaialva33/viva_aion)

*Created by Gabriel Maia · MIT License*

<img src="https://capsule-render.vercel.app/api?type=waving&color=0:1A1A1A,100:06B6D4&height=100&section=footer" width="100%"/>

</div>