logos/docs/REFERENCE.md

# LOGOS System Reference
**Logarithmic Ordering Generation Operating Software v1.0**

---

## Quick Start

```bash
# Start LM Studio server on port 1234
# Then launch LOGOS:
python -m logos.server

# Test MTL:
python -c "from logos.mtl.interpreter import MTLInterpreter; m=MTLInterpreter(); print(m.execute('(mult [2] [3])'))"
```

---

## Genesis Block (Prime Axioms)

| Prime | Name | Domain | Function |
|:-----:|:-----|:-------|:---------|
| 2 | MECHANISM | Operator | The Verb |
| 3 | RESULT | Operand | The Noun |
| 5 | CHOICE | Branch | The Fork |
| 7 | PERSIST | Memory | Storage Flag |
| 11 | WHY | Query | The Reason |
| 13 | RELATE | Link | Synapse Creator |
| 17 | IMAGE | Visual | Image Data |
| 19 | TEXT | Linguistic | Text Data |
| 23 | AUDIO | Acoustic | Audio Data |
| 29 | SIGNAL | Raw | Binary/Sensor |

---

## Composite Domains (Derived)

| Value | Factors | Name | Function |
|:-----:|:--------|:-----|:---------|
| 6 | 2×3 | FLIP | Action |
| 10 | 2×5 | AROUND | Navigation |
| 14 | 2×7 | HOLD | Save Command |
| 42 | 2×3×7 | DEEP_STORAGE | Permanent Record |
| 323 | 17×19 | VISUAL_TEXT | PDF/Document |
| 782 | 2×17×23 | VIDEO | Multimedia |

---

## Processing Domains

| Domain | Address | Function |
|:-------|:--------|:---------|
| VISUAL_CORTEX | 1700 | Image Processing |
| TEXT_ENGINE | 1900 | Language Processing |
| AUDIO_CORTEX | 2300 | Audio Processing |
| RELATIONSHIP | 1300 | Knowledge Graph |
| USER_REGISTRY | 2900 | User Ownership |

---

## MTL Operators

| Category | Operator | Syntax | Function |
|:---------|:---------|:-------|:---------|
| **Arithmetic** | mult | `(mult [A] [B])` | A × B |
| | div | `(div [A] [B])` | A ÷ B |
| | add | `(add A B)` | A + B |
| | sub | `(sub A B)` | A - B |
| **Logic Gates** | or | `(or [A] [B])` | LCM (Superposition) |
| | and | `(and [A] [B])` | GCD (Intersection) |
| | not | `(not K [A] [B])` | Steering (If K=A → B) |
| **Knowledge** | relate | `(relate [A] [B])` | A × B × 13 (Synapse) |
| | trace | `(trace S [A])` | Check if A divides S |
| | dissolve-link | `(dissolve-link S)` | S ÷ 13 |
| | get-linked | `(get-linked S [A])` | Find B given synapse |
| **Memory** | hold | `(hold name val)` | Store value |
| | fetch | `(fetch name)` | Retrieve value |
| | domain | `(domain [P])` | Set active domain |
| | store | `(store key val)` | Store in domain |
| **Control** | if | `(if cond then else)` | Conditional |
| | defun | `(defun name (args) body)` | Define function |
| | fractran | `(fractran instr N)` | Fractran loop |

---

## Concentric Topology (Mod 10)

The LOGOS network uses **concentric circles** where:
- **Ring** = Decade (log₁₀ scale: 1, 10, 100, 1000...)
- **Position** = Last digit (Mod 10)

### Prime Lanes (Residue Classes)

| Mod 10 | Color | Notes |
|:------:|:------|:------|
| 1 | Cyan | Primes ending in 1 |
| 3 | Magenta | Primes ending in 3 |
| 7 | Yellow | Primes ending in 7 |
| 9 | Green | Primes ending in 9 |

**Key Insight:** All primes > 5 end in 1, 3, 7, or 9.

---

## System Modules

| Module | Path | Function |
|:-------|:-----|:---------|
| MTL Interpreter | `logos/mtl/interpreter.py` | Turing-complete language |
| Genesis Kernel | `logos/kernel.py` | Agent flow lifecycle |
| SPCW Transceiver | `logos/spcw_transceiver.py` | Binary transport |
| Harmonizer | `logos/harmonizer.py` | Resonance filter |
| Dissolution Engine | `logos/agents/dissolution_engine.py` | Type detection |
| Prime DB | `logos/memory/prime_db.py` | Token→Prime mapping |
| Server | `logos/server.py` | Flask API (port 5000) |

---

## API Endpoints

| Method | Endpoint | Function |
|:-------|:---------|:---------|
| GET | `/v1` | Health check |
| GET | `/v1/models` | List models |
| POST | `/v1/chat/completions` | Chat (OpenAI-compat) |
| POST | `/v1/mtl/execute` | Execute MTL code |
| POST | `/v1/kernel/process` | Process kernel packet |
| POST | `/v1/context/buffer` | Update context |
| POST | `/ingest` | Ingest signal |

---

## Agent Models (LM Studio)

| Model | Role |
|:------|:-----|
| `dolphin-x1-8b` | Main inference |
| `google/gemma-3-4b` | Router/semantic |
| `essentialai/rnj-1` | Tensor logic |
| `text-embedding-nomic-embed-text-v1.5` | Embeddings |

---

## Core Axiom

> **Computing a value IS routing it.**

Standard OS: `if (condition) jump`  
LOGOS: `GCD(State, Filter) = next_address`

---

*LOGOS v1.0 • Arithmetic is Architecture*