<!--
  Legendas:
    - Item iniciado por "- [ ]" → Sugerido pela nossa Engenheira Codex
    - Item iniciado por "* [ ]" → Sugerido por ti
-->

## 📌 TODO.md — Neuro Lang / Programador / Holodeck / NeuroBoot

> Estado atual: ✅ pipeline validada
>
> `.nl → lexer → parser → AST → IR → validate → HolodeckVM → value`
>
> Exemplo validado: `fib.nl → 21`

---

## 🧭 POLICY CANÓNICA (não apagar)

- [ ] Definir e aplicar "mode gating" como regra única:
  - `active`     → pode sync + pode executar VM
  - `diagnostic` → pode sync (shadow) + NÃO executa VM
  - `safe`       → NÃO escreve + NÃO executa VM (só observar)
  - (qualquer outro) → comportamento conservador (como safe)

- [ ] Padronizar eventos e tags:
  - erros sempre como: `[FS]`, `[LEX]`, `[PARSE]`, `[IR]`, `[VM]`
  - eventos sempre com `kind`, `phase`, `file`, `code`, `ts`

---

## 🟢 FASE 1 — Consolidação da Pipeline (v0.1 → v0.1.1)

### 🔧 Programador / Infra

- [ ] Generalizar `fib.nl` → scan recursivo de `*.nl`:
  - scan: `runtime/lang/examples/**.nl`
  - evitar hardcode (nenhum nome fixo)
  - preservar estrutura de diretórios

- [ ] Sync ROM→runtime (multi-ficheiro, incremental):
  - origem ROM: `/opt/kernel/neurotron/src/neurotron/lang/examples/**.nl`
  - destino runtime: `ctx.lang_examples_dir/**.nl`
  - copiar só se `mtime/hash` mudar
  - registar ações: `lang.sync`

- [ ] Watcher incremental + pedido de compilação:
  - manter tabela `{path: mtime/hash}`
  - trigger quando muda + `mode == active`
  - publicar evento `lang.compile.request`
  - aceitar trigger de outros neurónios/agentes (pedido explícito)

- [ ] Persistência de telemetria em runtime/logs:
  - `telemetry.json` em `ctx.log_dir` (ou `ctx.runtime_dir`)
  - evitar paths read-only (DATA_DIR/package data)

### 🧠 Integração Cognitiva Básica

- [ ] Registar erros no Hippocampus:
  - kind: `"lang.error"`
  - phase: `FS|LEX|PARSE|IR|VM`
  - file: path
  - payload: msg + snapshot (quando existir)

- [ ] Mapear falhas para eventos TRM/telemetria:
  - falha → evento negativo (valência -)
  - sucesso → evento positivo (valência +)
  - repetição → penalização crescente

* [ ] **Correlacionar erros de IR com eventos passados**
  - usar Hippocampus
  - “isto já falhou antes?” + frequência + recência

---

## 🟡 FASE 2 — Programador como Agente Reativo (v0.2)

### 🤖 Comportamento do ProgramadorAgent

* [ ] Fazer o ProgramadorAgent reagir a falhas:
  - erro `[FS]` → forçar sync + verificar origem ROM + logar causa
  - erro `[IR]` → marcar fonte como “suspeita” + propor teste mínimo
  - erro `[VM]` → ativar trace (se disponível) + capturar estado

* [ ] Ligar falhas a valência negativa
  - erros repetidos → penalização crescente
  - sucesso → recuperação gradual

* [ ] Registar ações tomadas
  - sync, recompilação, bloqueio preventivo, retry/backoff

- [ ] Backoff e proteção contra loops:
  - se mesma falha em N ticks → parar exec e só observar (até mudança)

### ✍️ Escrita de Código Neuro

* [ ] Permitir que o Programador escreva `.nl`
  - aceitar `.nl` gerado por outros agentes
  - outputs experimentais em pasta separada

* [ ] Overwrite controlado + versionamento
  - não apagar ficheiros estáveis
  - versionar outputs (`.nl.v1`, `.nl.v2`) ou hash no nome

* [ ] Base para Neuro Lang v0.2 (geração simples)
  - foco em correção
  - sem otimização
  - subset explícito

---

## 🟠 FASE 3 — Observabilidade e Debug Profundo

### 🧪 HolodeckVM — Trace Opcional

- [ ] Trace on-demand vindo do Programador:
  - flag no bus (ex.: `lang.vm.trace=true`)
  - trace nunca por default

* [ ] Adicionar trace configurável:
  - dump de `ip`
  - instrução atual
  - stack

* [ ] Associar trace a erros:
  - em `[VM]` guardar últimos N passos + estado final

- [ ] Dump opcional de IR/AST por falha:
  - `lang.dump.ir` / `lang.dump.ast` (apenas sob pedido)

---

## 🔵 FASE 4 — Programador Cognitivo Real (futuro)

> ⚠️ Só depois de tudo acima estar sólido

* [ ] Programador começa a interpretar erros
* [ ] Sugerir fixes possíveis
* [ ] Testar hipóteses em `.nl` temporários
* [ ] Escolher ação com base em:
  - histórico, custo, valência
* [ ] Atuar como agente cognitivo autónomo

---

# =====================================================================
# NeuroBoot — rota por fases (real-mode → 32-bit → long mode)
# Minimal + static + sem dynamic loader.
# =====================================================================

## 🟣 FASE 5 — NeuroBoot Design First (NeuroBoot.md)

- [ ] Criar `NeuroBoot.md` (design, sem código):
  - fases 0→4 (bootstrap/transição/64/prep/handoff)
  - contrato `neuroboot_info`
  - política de falha
  - modelo de logs/eventos do boot (buffer em memória)

- [ ] Definir política de falha (enum + códigos):
  - NX ausente: continuar/parar?
  - long mode ausente: fallback/halt?
  - ELF inválido: panic/halt?
  - memória insuficiente: degrade/halt?

---

## 🟣 FASE 6 — NeuroBoot v0.1 (16-bit real mode) “Hello, fib”

> Objetivo: provar vida **fora do Linux**
> Boot em real mode imprime na tela o resultado.

### Fase 0 — Bootstrap cru (real mode / early asm)

- [ ] Entry point fixo + stack mínima 16-bit
- [ ] Setup de segmentos (DS/ES/SS) + DF=0
- [ ] A20: enable + confirmação
- [ ] CPUID básico (se suportado) + fallback seguro
- [ ] Output mínimo:
  - BIOS teletype (INT 10h) **ou** VGA text buffer (0xB8000)

- [ ] `print16()`, `print_hex16()`, `print_dec16()` (mínimos)

### Prova “fib fora do runtime”

- [ ] Payload ultra simples (sem parser/IR/VM):
  - `entry()` devolve `21` (ou escreve num buffer)
- [ ] Boot chama payload + imprime: `fib(8)=21` (ou equivalente)

- [ ] Watchdog/timeout de execução:
  - se passar de X ciclos → imprimir “timeout” + halt

- [ ] BootEvent buffer em memória (ring buffer):
  - cada fase escreve `{phase, code, tsc_low}`
  - kernel injeta no Hippocampus mais tarde

---

## 🟤 FASE 7 — Transição 16 → 32-bit (infra de cópia/parsing)

> Objetivo: facilitar parsing/cópias e preparar o loader.

### Fase 1 — Transição

- [ ] GDT mínima + entrar em protected mode 32-bit
- [ ] Rotinas 32-bit para:
  - memcpy/memset
  - parsing de headers
- [ ] Voltar a imprimir status (tela/serial) por checkpoint

- [ ] (Opcional) unreal mode para cópias grandes

---

## 🟤 FASE 8 — ELF Loader mínimo (static-first)

> Objetivo: carregar ELF de forma conservadora e previsível.

### Fase 3 — Preparação do kernel (loader)

- [ ] Escolher formato alvo inicial:
  - Opção A: `ET_EXEC` estático (primeiro)
  - Opção B: `ET_DYN` (PIE) — só depois

- [ ] Validação de ELF header:
  - `ELFCLASS64`, `ELFDATA2LSB`, `EM_X86_64`
  - sanity: `e_phoff`, `e_phnum`, `e_entry`

- [ ] Suporte a `PT_LOAD`:
  - copiar segmentos para memória
  - (mais tarde) permissões R/W/X com paging

- [ ] Recusas explícitas (v0.1):
  - `PT_INTERP` → reject (sem dynamic loader)
  - relocations → reject na v0.1 (ou suportar 1 tipo só depois)
  - `ET_DYN` → reject na v0.1

- [ ] Estratégia de endereços (v0.1):
  - carregar em físico conhecido e saltar
  - (HHDM/map alto) só depois

---

## 🔴 FASE 9 — Ambiente 32-bit robusto (pré-64)

> Objetivo: base sólida para long mode (evita fantasmas).

### Fase 1.5 — Robustez

- [ ] Memory map E820 real → preencher `neuroboot_info`
- [ ] Alocador linear (bump allocator) no boot
- [ ] Stack 32-bit definitiva (guard simples)
- [ ] Serial debug opcional (COM) + fallback tela

- [ ] PIC/APIC:
  - (mínimo) desativar PIC quando aplicável
  - APIC só quando fizer sentido (mais tarde)

---

## 🟧 FASE 10 — Long Mode 64-bit + handoff limpo

> Objetivo: estado previsível + contrato claro.

### Fase 2 — Ambiente 64-bit

- [ ] Paging + entrar em long mode
- [ ] MSRs críticos:
  - EFER (LME/LMA)
  - (mais tarde) STAR/LSTAR para syscall
- [ ] Layout canónico mínimo:
  - identity map inicial
  - (depois) região alta + HHDM-like

- [ ] Stack 64-bit alinhada 16B antes de calls

### Fase 4 — Handoff limpo

- [ ] Definir `neuroboot_info` v0.1 (mínimo):
  - magic/version
  - memory map + count
  - flags de features (NX/WP etc quando aplicável)
  - rsdp_addr (futuro)
  - output (texto/serial) + boot events buffer

- [ ] Jump para `kernel_entry64(info*)` (sem retorno)
- [ ] Kernel imprime “nasci” + dump do `neuroboot_info`

---

## 🟨 FASE 11 — Convergência Neurotron ↔ Neuro Lang no novo boot

> Objetivo: a pipeline existir no mundo nativo (NFDOS).

- [ ] Rodar HolodeckVM em 64-bit nativo (no teu kernel/userspace NFDOS)
- [ ] Reexecutar `fib.nl` e validar valor
- [ ] Registrar eventos de execução (FS/IR/VM) no Hippocampus real

---

## 🟦 FASE 12 — ABI/ELF compliance (subconjunto explícito)

> Objetivo: previsibilidade e portabilidade dentro de x86_64 SysV.

- [ ] Checklist SysV AMD64 ABI:
  - stack alignment 16B (call boundary)
  - args: RDI, RSI, RDX, RCX, R8, R9
  - return: RAX
  - callee-saved: RBX, RBP, R12–R15
  - red-zone: decidir (kernel normalmente desativa)
  - DF=0 garantido

- [ ] Documentar subset suportado (por design):
  - static only
  - sem dynamic linker (sem PLT/GOT no início)
  - relocations mínimas (ou nenhuma na fase inicial)
  - SSE/float só quando precisares

---

## 🧭 NOTAS DE ARQUITETURA (não apagar)

* O Programador não é um compilador → é um agente que decide quando compilar
* O `.nl` é linguagem viva, não só input
* O Holodeck é execução observável
* Erros são eventos cognitivos, não exceções
* Boot fala a língua da mente: logs estruturados + eventos de fase

