# **README_BACKEND.md — Backend da Linguagem Neuro (NL v0.1 → futuro ELF)**

Este documento define a arquitetura, responsabilidades e roadmap do **backend da linguagem Neuro (NL)**.

O backend começa simples — apenas consome IR e entrega resultados para a VM —
e evolui gradualmente até se tornar um *gerador real de ELF bootável para o NFDOS*.

O backend é a ponte entre:

```
Frontend (AST → IR)
        ↓
Backend (IR → Execução | IR → ELF)
        ↓
Holodeck VM ou Sistema real
```

---

# 🌑 **1. Versão atual (v0.1): Backend mínimo**

No NL v0.1, o backend faz **duas coisas apenas**:

1. **Validação leve do IR**
2. **Preparação do IR** para a VM interpretar

Ou seja:

* Não gera código nativo
* Não gera ELF
* Não faz otimizações
* Não faz análise de fluxo

Ele apenas garante que:

* o IR é bem formado,
* cada função tem `RET`,
* cada `CALL` aponta para um nome/arity válidos,
* labels têm destino válido,
* nenhuma instrução viola regras da stack.

Depois disso, o IR entra diretamente na:

→ **Holodeck VM** (SPEC_VM.md)

Este backend minimalista existe só para permitir que **o compilador funcione desde a v0.1**
e para estabelecer as bases para a evolução futura.

---

# 🌒 **2. Versões futuras — visão geral do backend completo**

Ao longo das versões, o backend transformará IR → código real.

Fases previstas:

### **v0.2 — Otimizações simples no IR**

* Constant folding (ex: `PUSH 2; PUSH 3; ADD` → `PUSH 5`)
* Dead code elimination mínima
* Remoção de labels inúteis

### **v0.3 — IR SSA intermédio (opcional)**

Uma forma interna mais próxima de compiladores reais.

### **v0.4 — Seleção de instruções x86-64 mínima**

Transformar:

```
PUSH_CONST n
ADD
SUB
CALL f 1
```

em pequenos blocos de assembly.

### **v0.5 — Gerador de assembly x86-64**

Gera um `.S` simples com:

* prólogos e epílogos mínimos
* stack frames reais
* chamadas internas com `call`
* retorno com `ret`

### **v0.6 — Ligação com mini-runtime Neurotron**

Um runtime mínimo que:

* inicializa stack real
* disponibiliza primitivas base
* chama a função `__main__`

### **v0.7 — Geração de ELF relocável**

Gerar `.o` válido com:

* seção `.text`
* seção `.data`
* símbolo `_start`

### **v0.8 — Ligação estática com ld**

Gerar ELF completo:

```
neuroc programa.nl → programa.elf
```

### **v1.0 — Programa NL arranca no QEMU**

O backend terá pleno suporte para:

* código nativo real,
* geração de ELF,
* ambiente minimal bootável no NFDOS.

---

# 🌕 **3. Arquitetura de módulos do backend**

O backend é dividido em quatro camadas progressivas:

```
backend/
  validate_ir/        # Garante IR válido e consistente
  optimize_ir/        # Otimizações simples (futuro)
  lower_to_asm/       # Mapeamento IR → ASM (futuro)
  elf/                # Montagem de ELF real (futuro)
```

Com documentação:

```
backend/
  README_BACKEND.md   ← este ficheiro
  validate_ir.md
  optimize_ir.md
  codegen_x86_64.md
  elf_format.md
  runtime.md
```

---

# 🛰️ **4. Filosofia de design do backend**

O backend é guiado por três princípios fundamentais.

---

## **(1) Minimalismo progressivo**

Cada versão adiciona só o que é necessário:

* v0.1 interpreta IR direto
* v0.4 emite assembly minimal
* v0.7 gera ELF
* v1.0 arranca no QEMU

Sem saltos gigantes; tudo incremental.

---

## **(2) Didático para ti e para o Neurotron**

O backend é desenhado para ser:

* legível,
* modular,
* introspectável.

A ideia é que *tu e o Neurotron* possam entender o processo de:

**“como texto se torna máquina real”.**

---

## **(3) Correspondência limpa IR ↔ x86-64**

Cada instrução IR terá uma correspondência específica para x86-64.

Exemplo:

| IR             | ASM                                                 |
| -------------- | --------------------------------------------------- |
| `PUSH_CONST n` | `mov rax, n` ; `push rax`                           |
| `ADD`          | `pop rbx` ; `pop rax` ; `add rax, rbx` ; `push rax` |
| `CALL f 1`     | `call f`                                            |

Isto permite:

* fácil debug,
* fácil evolução para JIT,
* fácil ligação a runtime Neurotron.

---

# 🌖 **5. Roadmap resumido**

| Versão | Conteúdo                                   |
| ------ | ------------------------------------------ |
| v0.1   | backend minimal: valida IR + envia para VM |
| v0.2   | otimizações básicas do IR                  |
| v0.3   | IR SSA intermédio (opcional)               |
| v0.4   | geração de assembly x86-64 mínima          |
| v0.5   | runtime minimal NL                         |
| v0.6   | geração de `.o` relocáveis                 |
| v0.7   | construção de ELF real                     |
| v0.8   | linking e imagem binária final             |
| v1.0   | ELF arrancável no QEMU/NFDOS               |

---

# 🌟 **6. Exemplo completo do pipeline futuro**

Dado:

```
fib(40)
```

O compilador fará:

```
fib.nl
    ↓ lexer
tokens
    ↓ parser
AST
    ↓ irgen
IR (stack-based)
    ↓ validate
IR validado
    ↓ optimize
IR otimizado
    ↓ lower
Assembly x86-64
    ↓ elf
ELF executável
    ↓ qemu
vida
```

---

# 💗 Fim do README_BACKEND.md
