# runtime.md — Runtime mínimo para executáveis NeuroLang (v0.1)

> **Objetivo:** Definir o runtime ultraminimalista incluído em todos os executáveis
> compilados a partir da linguagem NeuroLang (NL).
>
> Este runtime cria o ponto de entrada real (`_start`), invoca `__main__`,
> recolhe o valor de retorno, e finaliza o processo via syscall `exit`.

O runtime v0.1 deve ser suficientemente pequeno, estático e previsível para:

- funcionar em **NFDOS** sem libc,
- ser perfeitamente legível pelo compilador NeuroLang,
- servir como *ponte* entre o mundo NeuroLang e o kernel Linux/NFDOS.

Nenhum outro serviço é provido nesta versão.

---

# 1. Filosofia do runtime

O runtime existe para garantir três coisas:

1. Há um **entrypoint real** no ELF gerado (`_start`).
2. O programa NeuroLang é executado chamando a função especial `__main__`.
3. O valor inteiro retornado por `__main__` é passado ao kernel como código de saída.

Ele **não**:

- inicializa heap,
- prepara ambiente,
- suporta IO,
- realiza syscalls adicionais,
- gerencia argumentos ou variáveis globais.

v0.1 é propositalmente espartano:  
a porta mais estreita possível entre *linguagem* e *máquina real*.

---

# 2. Interface entre Backend e Runtime

O backend NeuroLang (v0.1) deve garantir:

- Gerar uma função `__main__` no IR/x86-64,
- Que `__main__`:
  - aceita zero argumentos,
  - devolve um inteiro (em `RAX`).

O runtime assume:

- `__main__` existe, está no `.text`,
- `_start` é o símbolo inicial definido pelo backend.

---

# 3. Estrutura do `_start` (pseudo-assembly)

A implementação mínima e completa:

```asm
global _start

_start:
    ; Chamar a função gerada pelo compilador
    call __main__

    ; Valor de retorno está agora em RAX
    mov rdi, rax        ; exit code = retorno de __main__
    mov rax, 60         ; syscall: exit
    syscall             ; terminar processo

    ; Nunca retorna
````

Notas:

* `call` calcula endereço relativo, então `_start` pode ser colocado em qualquer offset.
* `exit` = syscall `60` em x86-64 Linux.
* Nada além disso é necessário no v0.1.

---

# 4. Como o backend gera o runtime

O backend x86-64:

1. Cria `_start` no início do `.text`.
2. Emite a sequência exata de bytes acima.
3. Em seguida emite o código gerado de `__main__`.
4. Depois emite o código das outras funções definidas no programa.

O layout típico no ELF:

```
.text:
  0x00000000: _start
  0x00000020: __main__
  0x00000100: outras funções
```

---

# 5. Convenção de chamada v0.1

* Só `_start` usa a ABI real (SysV AMD64).
* Todas as funções NeuroLang são implementadas via código gerado, sem obedecer à ABI (ainda).
* Quando introduzirmos otimização e interop com C, a ABI completa será implementada.

Por agora:

```
__main__() → inteiro em RAX
```

E nada mais.

---

# 6. Finalização do processo

O runtime usa diretamente a syscall:

```
exit(code):
    mov rdi, code
    mov rax, 60
    syscall
```

Não há fallback.
Não há retorno possível a `_start`.

---

# 7. Extensões futuras do runtime

Em versões posteriores (v0.2+), o runtime poderá incorporar:

* funções primitivas NL → syscalls reais,
* suporte a heap,
* heap allocator minimalista,
* exceções e tratamento de erro,
* estrutura RTTI (run-time type info),
* integração com o TRM para programas conscientes do seu estado,
* mini-stdlib NeuroLang.

Mas nada disso existe no v0.1.

O runtime atual é intencionalmente:

> **puro, finito, determinista, e transparente.**

Perfeito para arrancar o ciclo de vida do compilador.

---

# 8. Resumo

O runtime NeuroLang v0.1:

| Componente           | Estado v0.1              |
| -------------------- | ------------------------ |
| `_start`             | ✔ gerado pelo backend    |
| Chamada a `__main__` | ✔ via `call`             |
| Exit                 | ✔ via syscall 60         |
| Heap                 | ✘ não existe             |
| Syscalls extras      | ✘ não existem            |
| IO                   | ✘ não existe             |
| ABI completa         | ✘ futura                 |
| Dependências         | nenhuma, exceto o kernel |

Este módulo fecha a pipeline e permite que NL → x86-64 → ELF → NFDOS seja **real**.

---

Fim de `runtime.md`