This commit is contained in:
2026-03-24 13:40:22 +00:00
parent 747ac81da2
commit bbe7ea4dbe
9 changed files with 1097 additions and 12 deletions
+233 -11
View File
@@ -1,5 +1,25 @@
# Prometeu — PR Plan (Arena-Driven) para um LSP Completo
---
# **PR-00.X — Reorganização estrutural do workspace (pré–Arena / pré–LSP)**
> **Objetivo macro:** separar *modelo/ABI*, *execução*, *kernel* e *tooling* antes de qualquer refator arena-driven.
>
> **Regra de ouro:** nenhuma mudança de comportamento. Apenas **movimentação de código + ajuste de dependências**.
>
> **Modelo final alvo:**
>
> * `prometeu-bytecode` ✅ (fica)
> * `prometeu-abi` ✅ (novo — ex-`prometeu-core` sem execução)
> * `prometeu-vm` ✅ (novo)
> * `prometeu-kernel` ✅ (novo)
> * `prometeu-runtime-desktop` ✅ (fica)
> * `prometeu-compiler` ✅ (fica)
> * `prometeu` (CLI) ✅ (fica agregando)
---
> **Meta do Nilton / Junie workflow**: PRs extremamente prescritivos. A Junie só implementa; você revisa o design **antes** do código.
>
> **Regra de ouro:** cada PR abaixo vem com:
@@ -25,6 +45,35 @@ Workspace (Archive.zip) tem crates:
---
## Visão de arquitetura alvo
### Camadas
1. **FileDB**: texto, URI/path, line-index, snapshots.
2. **Lexer/Parser**: produz **AstArena** (NodeId + spans por nó).
3. **Binder/Resolver**: produz **SymbolArena** + índices (def/ref).
4. **Typecheck**: produz **TypeArena** + facts (node→type, symbol→type).
5. **Analysis Export**: `analysis.json` (full) + `symbols.json` (leve e estável).
6. **LSP Server**: consome `AnalysisDb` e responde requests.
### IDs padronizados (newtypes)
* `FileId(u32)`
* `NodeId(u32)`
* `NameId(u32)` (interner)
* `SymbolId(u32)`
* `TypeId(u32)`
* `ProjectId(u32)`
* `ModuleId(u32)`
### Invariantes
* AST é **imutável** após construção (normativo na spec PBS).
* Nenhuma fase expõe referências diretas entre nós; apenas **IDs**.
* IDs externos são aceitos, mas sempre passam por **validate/resolve** (API checked).
---
# Templates prescritivos para PR (usar em TODAS)
## Template de descrição (copiar/colar)
@@ -37,6 +86,17 @@ Workspace (Archive.zip) tem crates:
* **Riscos & rollback:**
* **Checklist de aceite (binário):**
## Regras para Junie (para reduzir vai-e-volta)
1. Não “inventar design”. Se algo não estiver especificado, **criar TODO** e parar.
2. Não mudar formatação/estilo fora do escopo.
3. Todo novo tipo público precisa de doc-comment curta e exemplo.
4. Toda mudança de JSON precisa:
* `schema_version` bump (se não for backward)
* teste de snapshot
5. Cada PR deve deixar `cargo test` verde.
---
# PRs (detalhados)
@@ -320,6 +380,167 @@ pub struct AnalysisDb {
---
# Série PR-00.X — Reestruturação de crates (Arena-Driven + LSP-ready)
> **Objetivo da série PR-00.X:** reorganizar o workspace em crates com fronteiras claras, **sem alterar comportamento**, preparando o terreno para o Prometeu Arena-Driven (compiler/analysis) e um LSP completo depois.
>
> **Novo layout alvo (travado):**
>
> * `prometeu-bytecode` (fica)
> * `prometeu-abi` (novo nome para o atual `prometeu-core` depurado) = **types + model + protocols** (sem execução)
> * `prometeu-vm` (novo) = execução da VM
> * `prometeu-kernel` (novo) = OS + FS + syscalls (implementa interface para a VM)
> * `prometeu-runtime-desktop` (fica) = host desktop
> * `prometeu-compiler` (fica)
> * `prometeu` (CLI) (fica)
>
> **Regra de ouro:** 1 PR = 1 fronteira. Nada de mover tudo de uma vez.
>
> **Regras para Junie (serie 00.X):**
>
> 1. **Não mudar lógica**; apenas mover, ajustar imports, e deixar testes verdes.
> 2. Se algo exigir mudança de API pública, criar `TODO(PR-00.Y)` e parar.
> 3. Sempre manter o workspace compilável a cada PR.
---
## PR-00.1 — Introduzir `prometeu-abi` (renomear/diluir `prometeu-core`)
**Branch:** `pr-00-1-prometeu-abi`
### Objetivo
Criar crate `prometeu-abi` contendo **somente tipos e contratos** (types+model+protocols), e manter `prometeu-core` temporariamente como facade/reexport para não quebrar consumidores.
### Passos prescritivos
1. Criar novo crate `crates/prometeu-abi/` com `src/lib.rs`.
2. Copiar para `prometeu-abi` (sem execução):
* `model/*`
* `debugger_protocol.rs`
* `telemetry.rs`
* `log.rs` (somente tipos/config; se tiver runtime logger, deixar no core por enquanto)
* **traits/contratos** usados por outros crates (ex.: IDs, enums de eventos)
3. Atualizar dependências dos crates consumidores para apontar para `prometeu-abi` onde aplicável.
4. Manter `prometeu-core` compilando com:
* `pub use prometeu_abi as abi;`
* reexports temporários de tipos que mudaram de path.
### Critérios de aceite
* Workspace compila.
* Nenhum comportamento muda.
* `prometeu-core` ainda existe (temporário).
---
## PR-00.2 — Extrair `prometeu-vm` do `prometeu-core`
**Branch:** `pr-00-2-prometeu-vm`
### Objetivo
Mover `virtual_machine/*` para `crates/prometeu-vm/`.
### Passos prescritivos
1. Criar crate `crates/prometeu-vm/`.
2. Mover `crates/prometeu-core/src/virtual_machine/**` → `crates/prometeu-vm/src/**`.
3. Ajustar `use` paths em todos os crates.
4. Adicionar shim temporário no `prometeu-core` (se ainda existir):
* `pub mod virtual_machine { pub use prometeu_vm::*; }`
### Critérios de aceite
* `cargo test` verde.
* runtime desktop ainda roda.
---
## PR-00.3 — Extrair `prometeu-kernel` (OS + FS + syscalls)
**Branch:** `pr-00-3-prometeu-kernel`
### Objetivo
Mover `prometeu_os/*` + `fs/*` (e qualquer dispatcher de syscalls) para `crates/prometeu-kernel/`.
### Passos prescritivos
1. Criar crate `crates/prometeu-kernel/`.
2. Mover:
* `crates/prometeu-core/src/prometeu_os/**` → `crates/prometeu-kernel/src/**`
* `crates/prometeu-core/src/fs/**` → `crates/prometeu-kernel/src/fs/**`
3. Garantir que o kernel **depende** de:
* `prometeu-abi`
* `prometeu-vm`
4. Garantir que a VM chama syscalls via interface implementada pelo kernel.
5. Manter shim temporário no `prometeu-core` (se existir): `pub mod prometeu_os { pub use prometeu_kernel::*; }`
### Critérios de aceite
* `cargo test` verde.
* Sem mudança comportamental (mesmo conjunto de syscalls e traps).
---
## PR-00.4 — Depurar `prometeu-core`: remover execução e virar apenas compat layer
**Branch:** `pr-00-4-deprecate-prometeu-core`
### Objetivo
Eliminar o conteúdo executável restante do `prometeu-core`, deixando-o como reexport/compat por um curto período.
### Passos
* `hardware` e `firmware/hub` ficam onde estiverem por enquanto (podem virar PR-00.5/00.6 se necessário)
* `prometeu-core` passa a reexportar:
* `prometeu-abi`
* `prometeu-vm`
* `prometeu-kernel`
### Critérios
* Zero imports internos `crate::virtual_machine` etc. fora da facade.
---
## PR-00.5 — (Opcional) Extrair `prometeu-firmware` (hub/boot)
**Branch:** `pr-00-5-prometeu-firmware`
### Objetivo
Mover `firmware/*` + `prometeu_hub/*` para `crates/prometeu-firmware/`.
### Critérios
* runtime desktop depende de `prometeu-firmware`.
---
## PR-00.6 — Remover `prometeu-core` e migrar consumidores
**Branch:** `pr-00-6-remove-prometeu-core`
### Objetivo
Apagar `prometeu-core` após migração total.
### Critérios
* Nenhum crate depende de `prometeu-core`.
---
## PR-01 — FileDB + LineIndex (base do LSP e spans)
**Branch:** `pr-01-filedb`
@@ -775,15 +996,16 @@ Baseado em RefIndex e NodeToSymbol.
---
# Ordem recomendada (para minimizar refator churn)
1. PR-00, PR-01
2. PR-02
3. PR-03
4. PR-04
5. PR-06
6. PR-05
7. PR-07
8. PR-08 → PR-12
9. PR-14
10. PR-15
---
# Sequência recomendada (travada)
1. PR-00.1 (`prometeu-abi` + compat)
2. PR-00.2 (`prometeu-vm`)
3. PR-00.3 (`prometeu-kernel`)
4. PR-00.4 (depurar `prometeu-core`)
5. PR-00.5 (opcional firmware)
6. PR-00.6 (remover core)
> Após PR-00.X, iniciar a trilha Arena-Driven (PR-01..PR-07) no compiler/analysis.