# README_HOLODECK.md — Holodeck VM (v0.1)

> **O Holodeck é a Máquina Virtual mínima que executa o IR da Neuro Language.**
>
> Ele é a primeira forma de “existência” de um programa Neuro Language:
> antes de virar ELF, antes de tocar no hardware, antes de existir como
> binário real… ele vive aqui, neste ambiente controlado e deterministicamente
> simples.
>
> O Holodeck é a ponte entre **linguagem → IR → execução simbólica → execução nativa**.

---

# 1. Objetivos do Holodeck v0.1

O Holodeck existe, no v0.1, com três objetivos:

### ✔ 1. Executar IR de forma determinista  
Sem otimizações, sem JIT, sem syscalls — apenas a execução pura de:

- stack machine,
- frames,
- instruções aritméticas,
- chamadas de função,
- recursão.

### ✔ 2. Servir de ferramenta pedagógica  
O Holodeck permite observar o **comportamento interno** de um programa Neuro Language:

- estado da stack,
- frames ativos,
- IP atual,
- chamadas recursivas.

Perfeito para debug, ensino e compreensão.

### ✔ 3. Validar o compilador antes da fase ELF  
Todo programa deve:

1. ser lexado,
2. ser parseado,
3. gerar AST,
4. gerar IR,
5. rodar corretamente no Holodeck,
6. só depois ir para o backend real.

---

# 2. Filosofia do design v0.1

O Holodeck é:

### **Minimal**  
Não tem GC, heap, IO, syscalls, objetos, strings nem mutabilidade além de argumentos.

### **Determinístico**  
Dado IR fixo → comportamento fixo.

### **Transparente**  
Qualquer estado interno pode ser inspecionado.

### **Stack-based**  
Operações manipulam apenas a pilha e variáveis locais.

### **Frame-oriented**  
Cada chamada de função cria um novo frame contendo:

- valores dos argumentos,
- instruções associadas,
- IP atual.

---

# 3. Estrutura Interna da VM

O estado principal consiste em:

```

VMState:
stack: [operandos inteiros]
call_stack: [Frame]

```

E cada frame:

```

Frame:
locals: {nome → valor}
ip: índice da instrução atual
code: lista de instruções IR
nargs: número de argumentos esperados

```

As funções são carregadas num dicionário global:

```

functions: {
"fib": Function(code, nargs=1),
"**main**": Function(code, nargs=0)
}

```

---

# 4. Ciclo de Execução

A VM segue o ciclo clássico:

```

loop:
instr = frame.code[frame.ip]
executar(instr)
frame.ip += 1 (salvo instruções de salto)

```

Termina quando:

- `__main__` retorna,
- a call stack fica vazia.

---

# 5. Instruções Suportadas (v0.1)

O Holodeck executa exatamente o IR definido no `SPEC_IR.md`.

Instruções implementadas:

- `PUSH_CONST n`
- `LOAD_VAR name`
- `STORE_VAR name` *(não usado ainda em fib, mas incluído para completude)*
- `ADD`, `SUB`
- `LT` (menor que)
- `JUMP label`
- `JUMP_IF_FALSE label`
- `CALL name nargs`
- `RET`

Todas manipulações são feitas sobre a stack.

---

# 6. Semântica de Chamadas

### `CALL f N`

1. Retira N argumentos da stack.
2. Cria novo frame com:

```

locals = {arg0 → value0, arg1 → value1, ...}
ip = 0
code = functions[f].code

```

3. Empilha o frame.
4. Continua execução no novo contexto.

### `RET`

1. Valor no topo da stack é o retorno.
2. Frame atual é descartado.
3. Valor é colocado no topo da stack do frame anterior.

---

# 7. Labels

Durante carregamento do IR:

- labels são convertidos para offsets numéricos,
- código textual é transformado em lista compacta de instruções e endereços.

Resultado:

```

JUMP L_else → JUMP 7

```

---

# 8. Exemplo: Execução de `fib(3)`

```

CALL fib 1
LOAD_VAR x        → push 3
PUSH_CONST 3
LT                → push false
JUMP_IF_FALSE → vai para L_else
...
CALL fib 1        → cria novo frame com x=2
...
RET

```

Tudo descrito detalhadamente no `design_vm.md`.

---

# 9. Limitações Intencionais do v0.1

- sem loops nativos,
- sem strings,
- sem memória global,
- sem IO,
- sem syscalls,
- sem alocação dinâmica,
- sem otimizações.

Tudo isso será introduzido após o compilador NL → ELF estar funcional.

---

# 10. Futuro do Holodeck

As versões seguintes podem introduzir:

### v0.2  
- instruções adicionais (EQ, GT, etc.)
- suporte a variáveis locais mutáveis

### v0.3  
- heap minimalista  
- objetos simples (registos)

### v0.4  
- integração com TRM  
- instrumentação automática para introspecção cognitiva

### v0.5  
- JIT opcional  
- execução híbrida Holodeck + backend nativo

Mas a v0.1 deve permanecer:

> **um ambiente de execução minimalista, determinístico e pedagógico.**

---

# 11. Resumo

O Holodeck é:

| Propriedade | Estado |
|-------------|--------|
| Stack machine | ✔ |
| Frames | ✔ |
| Labels | ✔ |
| Recursão | ✔ |
| IR completo v0.1 | ✔ |
| Execução determinística | ✔ |
| Syscalls | ✘ |
| Heap | ✘ |
| IO | ✘ |
| Strings | ✘ |

Ele completa a pipeline:

```

source.nl → AST → IR → Holodeck → ELF → NFDOS → Neurotron

```

E permite que programas Neuro Language *existam* antes de existir fisicamente.

---

Fim de `README_HOLODECK.md`