Roadmap: Threshold Logic Neural Turing Machine with 64KB memory + LLM integration

todo.md

@@ -1,101 +1,148 @@
-# Self-Contained Tensor CPU Roadmap
+# Threshold Logic Neural Turing Machine
 
 ## Vision
-A fully self-contained CPU where:
-- All computation is threshold circuits (frozen weights)
-- Memory is a tensor partition (data flows through)
-- Stepper logic is encoded as circuits (no external orchestration)
-- One forward pass = one clock tick
 
-## Architecture
+A verified computational coprocessor embedded in transformer architecture:
+- **Frozen circuits**: Exhaustively tested threshold logic (can't compute wrong)
+- **ACT execution**: Runs until HALT within single forward pass
+- **Dual memory**: Hidden state integration + dedicated 64KB address space
+- **LLM integration**: Router/Extract/Inject learned, computation exact
+
+## Architecture Overview
 
 ```
-Input State Tensor:
-┌────────┬───────────┬───────┬─────────────────┐
-│ PC [8] │ Regs [32] │ Flags │ Memory [N×8]    │
-└────────┴───────────┴───────┴─────────────────┘
-                    ↓
-           Threshold Circuits
-         (fetch/decode/execute)
-                    ↓
-Output State Tensor:
-┌─────────┬───────────┬────────┬─────────────────┐
-│ PC' [8] │ Regs' [32]│ Flags' │ Memory' [N×8]   │
-└─────────┴───────────┴────────┴─────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                    Transformer Layer                        │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐  │
+│  │  Attention   │  │     MLP      │  │  ThresholdCPU    │  │
+│  │              │  │              │  │  (ACT-style)     │  │
+│  │              │  │              │  │                  │  │
+│  │              │  │              │  │ ┌──────────────┐ │  │
+│  │              │  │              │  │ │Router (learn)│ │  │
+│  │              │  │              │  │ ├──────────────┤ │  │
+│  │              │  │              │  │ │Extract (learn│ │  │
+│  │              │  │              │  │ ├──────────────┤ │  │
+│  │              │  │              │  │ │CPU (frozen)  │ │  │
+│  │              │  │              │  │ │ ↻ until HALT │ │  │
+│  │              │  │              │  │ ├──────────────┤ │  │
+│  │              │  │              │  │ │Inject (learn)│ │  │
+│  │              │  │              │  │ └──────────────┘ │  │
+│  └──────┬───────┘  └──────┬───────┘  └────────┬─────────┘  │
+│         └─────────────────┴───────────────────┘            │
+│                           ↓                                 │
+│                    Residual + CPU State                     │
+└─────────────────────────────────────────────────────────────┘
 ```
 
-## Phase 1: Memory Infrastructure
+## Memory Architecture
 
-| Component | Description | Status |
-|-----------|-------------|--------|
-| Memory Address Decoder | 8-bit address → 256 one-hot select | Pending |
-| Memory Read MUX | 256-to-1 mux, select byte by address | Pending |
-| Memory Write Demux | Route write data to addressed location | Pending |
-| Memory Cell Logic | Conditional update: new or keep old | Pending |
+### Hidden State Integration (Hot Memory)
+Reserve dimensions of residual stream for CPU state:
+```
+dims 0-511:     CPU memory (512 bits = 64 bytes hot cache)
+dims 512-543:   Registers (32 bits = 4 × 8-bit)
+dims 544-551:   PC (8 bits)
+dims 552-555:   Flags (4 bits: Z, N, C, V)
+dims 556-559:   Control (halt, interrupt, etc.)
+dims 560-959:   Normal embeddings (400 dims)
+```
+
+### Dedicated Memory Bank (Cold Storage)
+Full 64KB addressable memory via routing circuits:
+```
+Address space:  0x0000 - 0xFFFF (65,536 bytes)
+Tensors:        ~1.6M (routing overhead)
+Access:         Via 16-bit address decoder + mux/demux
+```
 
-## Phase 2: Instruction Fetch
+### Memory Hierarchy
+| Level | Size | Access | Use Case |
+|-------|------|--------|----------|
+| Registers | 4 × 8-bit | Direct | Operands, accumulators |
+| Hot cache | 64 bytes | Embedded in hidden state | Stack, scratch |
+| Cold bank | 64KB | Circuit-routed | Programs, data, heap |
 
-| Component | Description | Status |
-|-----------|-------------|--------|
-| PC → Memory Read | Fetch instruction at PC address | Pending |
-| Instruction Split | Separate opcode from operands | Pending |
-| Operand Decode | Extract src/dst register indices | Pending |
+## Phase 1: Memory Infrastructure
 
-## Phase 3: Execute Cycle
+| Component | Description | Tensors | Status |
+|-----------|-------------|---------|--------|
+| Address Decoder 16-bit | 16-bit → 65536 one-hot | ~65,600 | Pending |
+| Memory Read MUX | 65536-to-1 × 8 bits | ~524,288 | Pending |
+| Memory Write Demux | Route to addressed byte | ~524,288 | Pending |
+| Memory Cell Logic | Conditional update per byte | ~524,288 | Pending |
+| Bank Controller | Page/bank switching | ~1,000 | Pending |
 
-| Component | Description | Status |
-|-----------|-------------|--------|
-| Register Read MUX | Select source register(s) | Done (regmux4to1) |
-| ALU Dispatch | Route to correct operation circuit | Pending |
-| Result MUX | Select ALU output | Pending |
-| Writeback Logic | Route result to register or memory | Pending |
-| PC Update | Increment or load jump target | Done (pc_inc, pc_load) |
+**Estimated Phase 1 total: ~1.64M tensors**
 
-## Phase 4: Full Integration
+## Phase 2: ACT Execution Engine
 
 | Component | Description | Status |
 |-----------|-------------|--------|
-| State Packer | Combine all outputs into state tensor | Pending |
-| State Unpacker | Split input state into components | Pending |
-| Single-Pass Execute | One forward pass = one instruction | Pending |
+| Cycle Block | One fetch/decode/execute iteration | Pending |
+| Halt Detector | HALT instruction → stop signal | Pending |
+| Cycle Counter | Track pondering steps | Pending |
+| State Checkpointing | Save state for gradient flow | Pending |
+
+## Phase 3: LLM Integration Layers
+
+| Component | Description | Trainable | Status |
+|-----------|-------------|-----------|--------|
+| Router | Detect computation need | Yes | Pending |
+| State Extractor | Embeddings → CPU state | Yes | Pending |
+| State Injector | CPU state → embedding delta | Yes | Pending |
+| KV Cache Binding | CPU state persists with cache | No | Pending |
+
+## Phase 4: Instruction Set
+
+| Category | Instructions | Status |
+|----------|--------------|--------|
+| Arithmetic | ADD, SUB, MUL, DIV, NEG, ADC, SBC | Done |
+| Logic | AND, OR, XOR, NOT, shifts, rotates | Done |
+| Compare | CMP (sets flags) | Done |
+| Control | JMP, Jcc (conditional), CALL, RET | Partial |
+| Memory | LOAD, STORE (8/16-bit addressing) | Pending |
+| Stack | PUSH, POP | Partial |
+| System | NOP, HALT | Done |
 
 ## Completed Building Blocks
 
-These circuits are ready to use:
-
-### Arithmetic
-- NEG (76 tensors)
-- SUB (162 tensors)
-- ADC (144 tensors)
-- SBC (160 tensors)
-- DIV (1984 tensors)
-- ADD, MUL (from original model)
-
-### Comparison & Logic
-- CMP (168 tensors)
-- ASR, ROL, ROR (62 tensors total)
-- All boolean gates (from original model)
-
-### Control
-- NOP (24 tensors)
-- HALT (42 tensors)
-- PC Incrementer (62 tensors)
-- PC Load MUX (50 tensors)
-- Instruction Decoder (44 tensors)
-- Register File MUX (84 tensors)
-- Conditional jumps (from original model)
-
-## Memory Size Options
-
-| Size | Bytes | Bit-Tensors | Use Case |
-|------|-------|-------------|----------|
-| Tiny | 256 | ~2K | Proof of concept |
-| Small | 4KB | ~32K | Simple programs |
-| Medium | 64KB | ~512K | Full 8-bit address space |
-
-## Notes
-
-- Memory is DATA flowing through, not stored in weights
-- Weights remain frozen - only input/output tensors change
-- "Stepper" = calling forward() repeatedly
-- No Python logic in the loop - just tensor→forward→tensor
+### Arithmetic Core (2,756 tensors)
+- NEG: 76 tensors, 256/256 tests
+- SUB: 162 tensors, 65536/65536 tests
+- ADC: 144 tensors, 131072/131072 tests
+- SBC: 160 tensors, 131072/131072 tests
+- DIV: 1984 tensors, 65280/65280 tests
+- CMP: 168 tensors, 65536/65536 tests
+- ASR/ROL/ROR: 62 tensors total
+
+### Control Core (306 tensors)
+- NOP: 24 tensors, 4096/4096 tests
+- HALT: 42 tensors, 24576/24576 tests
+- PC Incrementer: 62 tensors, 256/256 tests
+- PC Load MUX: 50 tensors, 1536/1536 tests
+- Register MUX: 84 tensors, 1036/1036 tests
+- Instruction Decoder: 44 tensors, 16/16 tests
+
+### Original Model
+- Boolean gates, adders, multiplier, comparators
+- Threshold gates, pattern recognition
+- Modular arithmetic, error detection
+- ~3,100 tensors
+
+**Current total: 6,184 tensors**
+**Projected with 64KB memory: ~1.65M tensors**
+
+## Design Principles
+
+1. **Frozen correctness**: Circuit weights never change, exhaustively verified
+2. **Learned interface**: Router/Extract/Inject are trainable, CPU is not
+3. **Functional state**: Memory flows through as data, not mutated weights
+4. **Halting semantics**: HALT instruction terminates ACT loop
+5. **Composable**: Each circuit tested in isolation, composed at runtime
+
+## Key Insight
+
+The LLM learns **when** to compute and **how** to format input/output.
+The CPU defines **what** computation means - exactly, verifiably, always.
+
+This is not a learned calculator. This is a proven calculator with a learned interface.