pr 00.4
This commit is contained in:
@@ -1,39 +0,0 @@
|
||||
## 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).
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -1,955 +0,0 @@
|
||||
# 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:
|
||||
>
|
||||
> 1. Arquivos/alvos exatos
|
||||
> 2. Estruturas e assinaturas obrigatórias
|
||||
> 3. Esquemas JSON (quando aplicável)
|
||||
> 4. Testes (golden + unit)
|
||||
> 5. Critérios de aceite “binário” (passou/não passou)
|
||||
|
||||
---
|
||||
|
||||
## Estado atual (confirmado pelo repo)
|
||||
|
||||
Workspace (Archive.zip) tem crates:
|
||||
|
||||
* `prometeu/`
|
||||
* `prometeu-bytecode/`
|
||||
* `prometeu-core/`
|
||||
* `prometeu-compiler/` (bin `src/main.rs`, deps: `serde`, `serde_json`, `anyhow`, `clap`, e família `oxc_*`).
|
||||
|
||||
**Saída atual existente:** `symbols.json` (schema_version 0), exportando símbolos por projeto, com `decl_span` em `line/col` e paths absolutos. (Vamos evoluir isso no PR-07.)
|
||||
|
||||
---
|
||||
|
||||
## 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)
|
||||
|
||||
* **Motivação:**
|
||||
* **Mudança de modelo de dados:**
|
||||
* **APIs novas / alteradas:**
|
||||
* **Arquivos tocados:**
|
||||
* **Testes adicionados/atualizados:**
|
||||
* **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)
|
||||
|
||||
## PR-00 — Infra: crates de análise + lsp (estrutura do workspace)
|
||||
|
||||
**Branch:** `pr-00-analysis-lsp-foundations`
|
||||
|
||||
### Decisão travada (LSP)
|
||||
|
||||
* **Biblioteca escolhida:** `tower-lsp`
|
||||
* **Motivo:** reduzir boilerplate, acelerar MVP e minimizar vai-e-volta. Cancelamento/incremental será feito **por cima** (tasks async + cancel tokens).
|
||||
|
||||
### Objetivo
|
||||
|
||||
Adicionar crates novas sem mexer no pipeline existente.
|
||||
|
||||
### Entregas obrigatórias
|
||||
|
||||
1. **Novo crate:** `prometeu-analysis/`
|
||||
|
||||
* `Cargo.toml` (library)
|
||||
* `src/lib.rs`
|
||||
2. **Novo crate:** `prometeu-lsp/`
|
||||
|
||||
* `Cargo.toml` (bin)
|
||||
* `src/main.rs`
|
||||
3. Workspace root: ajustar `Cargo.toml` (se existir no root) para incluir members.
|
||||
|
||||
### Dependências (fixas)
|
||||
|
||||
* `prometeu-analysis`: `serde`, `serde_json`
|
||||
* `prometeu-lsp`:
|
||||
|
||||
* `tower-lsp = "0.20"` (ou versão estável atual)
|
||||
* `tokio` (full)
|
||||
* `prometeu-analysis` (path)
|
||||
|
||||
### Esqueleto obrigatório (`prometeu-lsp/src/main.rs`)
|
||||
|
||||
```rust
|
||||
use tower_lsp::{LspService, Server};
|
||||
use tokio::sync::RwLock;
|
||||
use std::sync::Arc;
|
||||
|
||||
#[derive(Default)]
|
||||
struct AnalysisDb {
|
||||
// FileDB, AstArena, SymbolArena, TypeArena, Diagnostics
|
||||
}
|
||||
|
||||
struct Backend {
|
||||
db: Arc<RwLock<AnalysisDb>>,
|
||||
}
|
||||
|
||||
#[tower_lsp::async_trait]
|
||||
impl tower_lsp::LanguageServer for Backend {
|
||||
async fn initialize(&self, _: tower_lsp::lsp_types::InitializeParams)
|
||||
-> tower_lsp::jsonrpc::Result<tower_lsp::lsp_types::InitializeResult> {
|
||||
Ok(tower_lsp::lsp_types::InitializeResult {
|
||||
capabilities: tower_lsp::lsp_types::ServerCapabilities {
|
||||
text_document_sync: Some(tower_lsp::lsp_types::TextDocumentSyncCapability::Kind(
|
||||
tower_lsp::lsp_types::TextDocumentSyncKind::FULL,
|
||||
)),
|
||||
// Declaramos capacidades desde já para evitar churn posterior.
|
||||
definition_provider: Some(true.into()),
|
||||
document_symbol_provider: Some(true.into()),
|
||||
workspace_symbol_provider: Some(true.into()),
|
||||
hover_provider: Some(true.into()),
|
||||
references_provider: Some(true.into()),
|
||||
rename_provider: Some(tower_lsp::lsp_types::OneOf::Left(true)),
|
||||
completion_provider: Some(tower_lsp::lsp_types::CompletionOptions {
|
||||
resolve_provider: Some(false),
|
||||
trigger_characters: Some(vec![".".into(), ":".into()]),
|
||||
..Default::default()
|
||||
}),
|
||||
semantic_tokens_provider: Some(
|
||||
tower_lsp::lsp_types::SemanticTokensServerCapabilities::SemanticTokensOptions(
|
||||
tower_lsp::lsp_types::SemanticTokensOptions {
|
||||
legend: tower_lsp::lsp_types::SemanticTokensLegend {
|
||||
// preenchido no PR-12
|
||||
token_types: vec![],
|
||||
token_modifiers: vec![],
|
||||
},
|
||||
full: Some(tower_lsp::lsp_types::SemanticTokensFullOptions::Bool(true)),
|
||||
range: None,
|
||||
..Default::default()
|
||||
},
|
||||
),
|
||||
),
|
||||
..Default::default()
|
||||
},
|
||||
..Default::default()
|
||||
})
|
||||
}
|
||||
|
||||
async fn initialized(&self, _: tower_lsp::lsp_types::InitializedParams) {}
|
||||
}
|
||||
|
||||
#[tokio::main]
|
||||
async fn main() {
|
||||
let stdin = tokio::io::stdin();
|
||||
let stdout = tokio::io::stdout();
|
||||
let (service, socket) = LspService::new(|_| Backend { db: Arc::new(RwLock::new(AnalysisDb::default())) });
|
||||
Server::new(stdin, stdout, socket).serve(service).await;
|
||||
}
|
||||
```
|
||||
|
||||
### Contrato exato do AnalysisDb (travado)
|
||||
|
||||
> **Regra:** o LSP nunca recalcula segurando `RwLock` por muito tempo. Toda análise pesada roda fora do lock e depois faz swap.
|
||||
|
||||
Criar arquivo: `prometeu-lsp/src/analysis_db.rs`
|
||||
|
||||
```rust
|
||||
use std::sync::Arc;
|
||||
use tokio::sync::RwLock;
|
||||
use tokio_util::sync::CancellationToken;
|
||||
|
||||
use prometeu_analysis::FileDB;
|
||||
|
||||
#[derive(Default)]
|
||||
pub struct AnalysisDb {
|
||||
pub file_db: FileDB,
|
||||
|
||||
// Os campos abaixo serão conectados conforme PR-03/04/05 (podem começar como None)
|
||||
// pub ast: Option<AstArena>,
|
||||
// pub symbols: Option<SymbolArena>,
|
||||
// pub types: Option<TypeArena>,
|
||||
// pub diagnostics: Vec<Diagnostic>,
|
||||
|
||||
/// Incrementa a cada rebuild concluído com sucesso
|
||||
pub revision: u64,
|
||||
|
||||
/// Cancel token do último rebuild em progresso (se houver)
|
||||
pub active_rebuild: Option<CancellationToken>,
|
||||
}
|
||||
|
||||
pub type SharedDb = Arc<RwLock<AnalysisDb>>;
|
||||
```
|
||||
|
||||
No `main.rs`, **substituir** o `AnalysisDb` local pelo import acima (ou manter local e delegar, mas sem duplicar).
|
||||
|
||||
### Modelo de cancelamento e coalescing (travado)
|
||||
|
||||
> Objetivo: quando chegam múltiplos `didChange` em sequência, cancelar o rebuild anterior e rodar apenas o último.
|
||||
|
||||
Adicionar dependência fixa em `prometeu-lsp/Cargo.toml`:
|
||||
|
||||
* `tokio-util`
|
||||
|
||||
Criar arquivo: `prometeu-lsp/src/rebuild.rs`
|
||||
|
||||
```rust
|
||||
use tokio_util::sync::CancellationToken;
|
||||
use crate::analysis_db::SharedDb;
|
||||
|
||||
/// Solicita rebuild do projeto (coarse). Cancela rebuild anterior se em progresso.
|
||||
/// Implementação inicial: apenas cria task e retorna.
|
||||
pub async fn request_rebuild(db: SharedDb) {
|
||||
// 1) lock curto: cancelar token anterior e instalar token novo
|
||||
// 2) spawn task: roda análise fora do lock
|
||||
// 3) lock curto: se token não cancelado, swap estado + revision++
|
||||
}
|
||||
```
|
||||
|
||||
Regras obrigatórias:
|
||||
|
||||
1. `request_rebuild` deve:
|
||||
|
||||
* cancelar `active_rebuild` anterior (se existir)
|
||||
* instalar um token novo
|
||||
* `tokio::spawn` uma task de rebuild
|
||||
2. A task deve checar `token.is_cancelled()` em pontos seguros:
|
||||
|
||||
* antes de começar
|
||||
* após parsing
|
||||
* após resolver
|
||||
* após typecheck
|
||||
3. O lock (`RwLock`) deve ser segurado apenas:
|
||||
|
||||
* para trocar `active_rebuild`
|
||||
* para aplicar o resultado final
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* `cargo build -p prometeu-lsp` ok
|
||||
* LSP inicializa em VS Code/Neovim sem crash
|
||||
* Nenhuma feature além do declarado
|
||||
|
||||
---
|
||||
|
||||
## Política fixa de cancelamento e rebuild (tower-lsp)
|
||||
|
||||
### Objetivo
|
||||
|
||||
Garantir que edições rápidas não gerem backlog de análises e evitar race conditions.
|
||||
|
||||
### Decisão travada
|
||||
|
||||
* Usar `tokio_util::sync::CancellationToken`
|
||||
* **Um token por rebuild**
|
||||
* Qualquer `didChange`:
|
||||
|
||||
1. Cancela o rebuild anterior
|
||||
2. Cria novo token
|
||||
3. Agenda nova task de análise
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
use tokio_util::sync::CancellationToken;
|
||||
|
||||
struct AnalysisController {
|
||||
current: Option<CancellationToken>,
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* Nunca segurar `RwLock<AnalysisDb>` durante parsing/resolver/typecheck.
|
||||
* Fluxo correto:
|
||||
|
||||
1. Clonar snapshot dos textos (FileDB)
|
||||
2. Soltar lock
|
||||
3. Rodar análise pesada
|
||||
4. Re-adquirir lock e substituir estado
|
||||
* Tasks devem checar `token.is_cancelled()` entre fases (parse / bind / type).
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Digitar rapidamente não acumula tasks.
|
||||
* Apenas o último estado publica diagnostics.
|
||||
|
||||
---
|
||||
|
||||
## Contrato fechado do AnalysisDb (fonte de verdade do LSP)
|
||||
|
||||
### Objetivo
|
||||
|
||||
Eliminar ambiguidade sobre o que vive no estado compartilhado.
|
||||
|
||||
### Estrutura obrigatória
|
||||
|
||||
```rust
|
||||
#[derive(Default)]
|
||||
pub struct AnalysisDb {
|
||||
pub files: FileDB,
|
||||
pub ast: Option<AstArena>,
|
||||
pub symbols: Option<SymbolArena>,
|
||||
pub types: Option<TypeArena>,
|
||||
pub type_facts: Option<TypeFacts>,
|
||||
pub diagnostics: Vec<Diagnostic>,
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* `AnalysisDb` **nunca** armazena estado parcialmente válido.
|
||||
* Se uma fase falhar:
|
||||
|
||||
* `ast/symbols/types` podem ficar `None`
|
||||
* `diagnostics` deve estar preenchido
|
||||
* LSP handlers **não** rodam análise: apenas leem `AnalysisDb`.
|
||||
|
||||
### Leitura segura
|
||||
|
||||
* Todos os handlers (`definition`, `hover`, `references`, etc.) devem:
|
||||
|
||||
* adquirir `db.read()`
|
||||
* lidar com `Option::None` retornando `null` / resposta vazia
|
||||
|
||||
### Escrita segura
|
||||
|
||||
* Apenas a task de rebuild escreve no `AnalysisDb`.
|
||||
* Escrita sempre substitui o estado inteiro (swap lógico).
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Nenhum handler pode panic por `None`.
|
||||
* Rebuild substitui estado de forma atômica (do ponto de vista do LSP).
|
||||
|
||||
---
|
||||
|
||||
|
||||
# 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.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`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Criar uma base de arquivos com IDs estáveis na sessão e conversão offset<->(line,col).
|
||||
|
||||
### Arquivos / módulos
|
||||
|
||||
* `prometeu-analysis/src/file_db.rs`
|
||||
* `prometeu-analysis/src/span.rs`
|
||||
* `prometeu-analysis/src/ids.rs`
|
||||
* `prometeu-analysis/src/lib.rs` (re-exports)
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
// prometeu-analysis/src/ids.rs
|
||||
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, serde::Serialize, serde::Deserialize)]
|
||||
pub struct FileId(pub u32);
|
||||
|
||||
// prometeu-analysis/src/span.rs
|
||||
#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize, serde::Deserialize)]
|
||||
pub struct Span {
|
||||
pub file: FileId,
|
||||
pub start: u32, // byte offset
|
||||
pub end: u32, // byte offset, exclusive
|
||||
}
|
||||
|
||||
// prometeu-analysis/src/file_db.rs
|
||||
pub struct FileDB {
|
||||
// map uri->id, id->uri/text/line_index
|
||||
}
|
||||
|
||||
pub struct LineIndex {
|
||||
// stores line start offsets
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* Spans são **byte offsets UTF-8** (`start` inclusive, `end` exclusive) — alinhado ao Canonical Addenda.
|
||||
* `LineIndex` deve lidar com `
|
||||
` (LF). (CRLF pode ser normalizado na entrada.)
|
||||
|
||||
### APIs obrigatórias
|
||||
|
||||
```rust
|
||||
impl FileDB {
|
||||
pub fn upsert(&mut self, uri: &str, text: String) -> FileId;
|
||||
pub fn file_id(&self, uri: &str) -> Option<FileId>;
|
||||
pub fn uri(&self, id: FileId) -> &str;
|
||||
pub fn text(&self, id: FileId) -> &str;
|
||||
pub fn line_index(&self, id: FileId) -> &LineIndex;
|
||||
}
|
||||
|
||||
impl LineIndex {
|
||||
pub fn offset_to_line_col(&self, offset: u32) -> (u32, u32);
|
||||
pub fn line_col_to_offset(&self, line: u32, col: u32) -> Option<u32>;
|
||||
}
|
||||
```
|
||||
|
||||
### Testes obrigatórios
|
||||
|
||||
* `tests/file_db_line_index.rs` (unit)
|
||||
|
||||
* roundtrip offset->(l,c)->offset
|
||||
* bordas (start/end, EOF)
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Testes passam.
|
||||
* Nenhuma mudança no output do `prometeu-compiler` ainda.
|
||||
|
||||
---
|
||||
|
||||
## PR-02 — NameInterner (NameId) e eliminação de String no hot path
|
||||
|
||||
**Branch:** `pr-02-name-interner`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Trocar identificadores em AST/resolver de `String` para `NameId`.
|
||||
|
||||
### Arquivos
|
||||
|
||||
* `prometeu-analysis/src/interner.rs`
|
||||
* Ajustar frontend PBS no `prometeu-compiler` (ver lista de toques abaixo).
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, serde::Serialize, serde::Deserialize)]
|
||||
pub struct NameId(pub u32);
|
||||
|
||||
pub struct NameInterner {
|
||||
// bidirectional: string->id, id->string
|
||||
}
|
||||
```
|
||||
|
||||
### APIs obrigatórias
|
||||
|
||||
```rust
|
||||
impl NameInterner {
|
||||
pub fn new() -> Self;
|
||||
pub fn intern(&mut self, s: &str) -> NameId;
|
||||
pub fn resolve(&self, id: NameId) -> &str;
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* Interner é **session-local**.
|
||||
* `resolve` deve retornar `&str` estável (armazenar `String` internamente).
|
||||
|
||||
### Touch points no `prometeu-compiler`
|
||||
|
||||
* Onde hoje existe `String` como nome de símbolo, token de identifier, etc:
|
||||
|
||||
* AST nodes de `Ident`
|
||||
* Resolver scopes: `HashMap<NameId, _>`
|
||||
|
||||
### Testes
|
||||
|
||||
* Unit: intern/resolve, dedup
|
||||
* Golden: manter comportamento de resolver/diags
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Redução de `String` em estruturas hot (resolver)
|
||||
* Build e testes ok.
|
||||
|
||||
---
|
||||
|
||||
## PR-03 — AST Arena (NodeId) para PBS
|
||||
|
||||
**Branch:** `pr-03-ast-arena`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Refatorar o AST PBS (atualmente recursivo) para uma arena `Vec` com `NodeId`.
|
||||
|
||||
### Alvos no repo
|
||||
|
||||
* `prometeu-compiler/src/frontends/pbs/*` (localizar AST/parser atuais)
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, serde::Serialize, serde::Deserialize)]
|
||||
pub struct NodeId(pub u32);
|
||||
|
||||
pub struct AstArena {
|
||||
pub nodes: Vec<NodeKind>,
|
||||
pub spans: Vec<prometeu_analysis::Span>,
|
||||
pub roots: Vec<NodeId>,
|
||||
}
|
||||
|
||||
pub enum NodeKind {
|
||||
File { imports: Vec<NodeId>, decls: Vec<NodeId> },
|
||||
Import { /* ... */ },
|
||||
FnDecl { name: NameId, /* ... */, body: NodeId },
|
||||
// ... (conforme canonical AST do PBS)
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* `AstArena::push(kind, span) -> NodeId` sempre faz append.
|
||||
* `spans.len() == nodes.len()` sempre.
|
||||
|
||||
### APIs obrigatórias
|
||||
|
||||
```rust
|
||||
impl AstArena {
|
||||
pub fn push(&mut self, kind: NodeKind, span: Span) -> NodeId;
|
||||
pub fn kind(&self, id: NodeId) -> &NodeKind;
|
||||
pub fn span(&self, id: NodeId) -> Span;
|
||||
}
|
||||
```
|
||||
|
||||
### Testes obrigatórios
|
||||
|
||||
* Parser golden tests: comparar JSON canonical (se você já tem) ou snapshots equivalentes.
|
||||
* Unit: invariantes (push mantém alinhamento).
|
||||
|
||||
### Critérios de aceite
|
||||
|
||||
* Nenhum `Box<Node>` em AST PBS.
|
||||
* Resolver e typechecker passam a consumir NodeId.
|
||||
|
||||
---
|
||||
|
||||
## PR-04 — SymbolArena + índices (defs/refs) + node→symbol
|
||||
|
||||
**Branch:** `pr-04-symbol-arena-index`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Criar `SymbolArena` e índices para features de LSP sem traversal pesado.
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, serde::Serialize, serde::Deserialize)]
|
||||
pub struct SymbolId(pub u32);
|
||||
|
||||
pub enum SymbolKind { Type, Value, Service, Function /* etc */ }
|
||||
|
||||
pub struct Symbol {
|
||||
pub name: NameId,
|
||||
pub kind: SymbolKind,
|
||||
pub exported: bool,
|
||||
pub module: ModuleId,
|
||||
pub decl_span: Span,
|
||||
}
|
||||
|
||||
pub struct SymbolArena { pub symbols: Vec<Symbol> }
|
||||
|
||||
pub struct DefIndex { /* HashMap<(ModuleId, NameId, Namespace), SymbolId> */ }
|
||||
|
||||
pub struct RefIndex { /* Vec<Vec<Span>> by SymbolId */ }
|
||||
|
||||
pub struct NodeToSymbol { /* Vec<Option<SymbolId>> by NodeId */ }
|
||||
```
|
||||
|
||||
### APIs obrigatórias
|
||||
|
||||
* `insert_symbol(...) -> SymbolId` (falha se duplicate, com diag E_RESOLVE_DUPLICATE_SYMBOL)
|
||||
* `record_ref(symbol_id, span)`
|
||||
* `bind_node(node_id, symbol_id)`
|
||||
|
||||
### Testes
|
||||
|
||||
* Duplicate symbol
|
||||
* Undefined identifier
|
||||
* Visibility violations
|
||||
* Determinismo (mesma input → mesma ordem IDs, quando possível)
|
||||
|
||||
---
|
||||
|
||||
## PR-05 — TypeArena + TypeFacts (node→type, symbol→type)
|
||||
|
||||
**Branch:** `pr-05-type-arena-facts`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Dar base para hover, completion e erros de tipo.
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash, serde::Serialize, serde::Deserialize)]
|
||||
pub struct TypeId(pub u32);
|
||||
|
||||
pub enum TypeKind {
|
||||
Primitive { name: NameId },
|
||||
Struct { sym: SymbolId },
|
||||
Optional { inner: TypeId },
|
||||
Result { ok: TypeId, err: TypeId },
|
||||
Array { inner: TypeId, len: Option<u32> },
|
||||
// ... conforme v0
|
||||
}
|
||||
|
||||
pub struct TypeArena { pub types: Vec<TypeKind> }
|
||||
|
||||
pub struct TypeFacts {
|
||||
pub node_type: Vec<Option<TypeId>>, // index by NodeId
|
||||
pub symbol_type: Vec<Option<TypeId>>, // index by SymbolId
|
||||
}
|
||||
```
|
||||
|
||||
### APIs obrigatórias
|
||||
|
||||
* `intern_type(TypeKind) -> TypeId` (dedup opcional; documentar)
|
||||
* `set_node_type(NodeId, TypeId)`
|
||||
* `set_symbol_type(SymbolId, TypeId)`
|
||||
|
||||
### Testes
|
||||
|
||||
* Hover type display snapshots.
|
||||
|
||||
---
|
||||
|
||||
## PR-06 — Diagnostics canonizados (E_* / W_*)
|
||||
|
||||
**Branch:** `pr-06-diagnostics`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Diagnósticos estáveis e serializáveis, alinhados ao Canonical Addenda (codes).
|
||||
|
||||
### Estruturas obrigatórias
|
||||
|
||||
```rust
|
||||
pub enum Severity { Error, Warning }
|
||||
|
||||
pub struct Diagnostic {
|
||||
pub severity: Severity,
|
||||
pub code: String,
|
||||
pub message: String,
|
||||
pub span: Span,
|
||||
pub related: Vec<(String, Span)>,
|
||||
}
|
||||
```
|
||||
|
||||
### Regras
|
||||
|
||||
* Codes conforme Canonical Addenda (E_PARSE_*, E_RESOLVE_*, E_TYPE_*).
|
||||
|
||||
### Testes
|
||||
|
||||
* Golden diag JSON determinístico.
|
||||
|
||||
---
|
||||
|
||||
## PR-07 — Export: `symbols.json` v1 + `analysis.json` v0
|
||||
|
||||
**Branch:** `pr-07-analysis-export`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Separar índice leve (`symbols.json`) e export completo (`analysis.json`).
|
||||
|
||||
### Símbolos (novo formato recomendado)
|
||||
|
||||
* **IMPORTANTE:** parar de gravar paths absolutos (usar URI relativo ao projeto quando possível).
|
||||
|
||||
`symbols.json` v1 (schema_version=1):
|
||||
|
||||
* `projects[]`:
|
||||
|
||||
* `project` (string)
|
||||
* `project_dir` (string) (pode ficar absoluto por enquanto)
|
||||
* `symbols[]`:
|
||||
|
||||
* `symbol_id` (u32) **OU** string estável atual (mantém compat)
|
||||
* `name` (string)
|
||||
* `kind` (string)
|
||||
* `exported` (bool)
|
||||
* `module_path` (string)
|
||||
* `decl_span`: `{ file_uri, start:{line,col}, end:{line,col} }`
|
||||
|
||||
`analysis.json` (schema_version=0):
|
||||
|
||||
* `file_table`: [{file_id:u32, uri:string}]
|
||||
* `symbols`: [{symbol_id:u32, name_id:u32, kind, exported, module_id, decl_span}]
|
||||
* `refs`: [{symbol_id:u32, spans:[Span]}]
|
||||
* `types`: [{type_id:u32, kind:...}]
|
||||
* `facts`: { node_type: [...], symbol_type: [...] }
|
||||
* `diagnostics`: [Diagnostic]
|
||||
|
||||
### Testes
|
||||
|
||||
* Snapshot de ambos JSONs.
|
||||
|
||||
---
|
||||
|
||||
## PR-08 — LSP MVP (diagnostics + symbols + goto definition)
|
||||
|
||||
**Branch:** `pr-08-lsp-mvp`
|
||||
|
||||
### Objetivo
|
||||
|
||||
LSP funcional mínimo usando `AnalysisDb` (em memória), recompilando quando arquivo muda.
|
||||
|
||||
### Features
|
||||
|
||||
* `initialize`
|
||||
* `didOpen`/`didChange`/`didClose`
|
||||
* `publishDiagnostics`
|
||||
* `documentSymbol` / `workspaceSymbol`
|
||||
* `definition`
|
||||
|
||||
### Regras
|
||||
|
||||
* `didChange`: por enquanto full-text (simplifica)
|
||||
* Rebuild: coarse (projeto inteiro) inicialmente
|
||||
|
||||
### Testes
|
||||
|
||||
* Test harness: abrir doc e pedir definition.
|
||||
|
||||
---
|
||||
|
||||
## PR-09 — LSP: references + rename
|
||||
|
||||
**Branch:** `pr-09-lsp-refs-rename`
|
||||
|
||||
### Objetivo
|
||||
|
||||
Baseado em RefIndex e NodeToSymbol.
|
||||
|
||||
### Features
|
||||
|
||||
* `references`
|
||||
* `prepareRename`
|
||||
* `rename`
|
||||
|
||||
### Regras de segurança
|
||||
|
||||
* Não renomear se símbolo não-resolvido.
|
||||
* Não renomear se span em comentário/string.
|
||||
|
||||
---
|
||||
|
||||
## PR-10 — LSP: hover + signatureHelp
|
||||
|
||||
**Branch:** `pr-10-lsp-hover-sighelp`
|
||||
|
||||
### Features
|
||||
|
||||
* `hover`: type + docstring (docstring opcional por enquanto)
|
||||
* `signatureHelp`: para call nodes (se parser já marca)
|
||||
|
||||
---
|
||||
|
||||
## PR-11 — LSP: completion
|
||||
|
||||
**Branch:** `pr-11-lsp-completion`
|
||||
|
||||
### Buckets
|
||||
|
||||
* locals em scope (se você tiver scope facts)
|
||||
* symbols do módulo
|
||||
* exports importados
|
||||
* members via type facts
|
||||
|
||||
---
|
||||
|
||||
## PR-12 — LSP: semantic tokens + highlights
|
||||
|
||||
**Branch:** `pr-12-lsp-semantic`
|
||||
|
||||
---
|
||||
|
||||
## PR-13 — LSP: formatting + code actions (opcional)
|
||||
|
||||
**Branch:** `pr-13-lsp-actions`
|
||||
|
||||
---
|
||||
|
||||
## PR-14 — Incremental analysis + cancelation
|
||||
|
||||
**Branch:** `pr-14-incremental`
|
||||
|
||||
---
|
||||
|
||||
## PR-15 — Debug map (pc→span) + integração com traps
|
||||
|
||||
**Branch:** `pr-15-debug-map`
|
||||
|
||||
---
|
||||
|
||||
|
||||
---
|
||||
|
||||
# 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.
|
||||
@@ -1,341 +0,0 @@
|
||||
# Prometeu Base Script (PBS)
|
||||
|
||||
> **A didactic scripting language for game development with explicit cost, explicit memory, and predictable runtime.**
|
||||
|
||||
---
|
||||
|
||||
## 0. What PBS Is (and What It Is Not)
|
||||
|
||||
PBS (Prometeu Base Script) is a **small, explicit scripting language designed for game engines and real‑time runtimes**.
|
||||
|
||||
Its core goals are:
|
||||
|
||||
* **Didactic clarity** — the language teaches how memory, data, and APIs really work.
|
||||
* **Game‑friendly execution** — predictable runtime, no hidden allocation, no tracing GC.
|
||||
* **Explicit cost model** — you always know *when* you allocate, *where* data lives, and *who* can mutate it.
|
||||
|
||||
PBS is **not**:
|
||||
|
||||
* a general‑purpose application language
|
||||
* a productivity scripting language like Python or Lua
|
||||
* a language that hides runtime cost
|
||||
|
||||
PBS is intentionally opinionated. It is built for developers who want **control, predictability, and understanding**, especially in **game and engine contexts**.
|
||||
|
||||
---
|
||||
|
||||
## 1. The Core Philosophy
|
||||
|
||||
PBS is built around one rule:
|
||||
|
||||
> **If you do not allocate, you are safe. If you allocate, you are responsible.**
|
||||
|
||||
From this rule, everything else follows.
|
||||
|
||||
### 1.1 Two Worlds
|
||||
|
||||
PBS has **two explicit memory worlds**:
|
||||
|
||||
| World | Purpose | Properties |
|
||||
| ----- | -------------- | ---------------------------------------------- |
|
||||
| SAFE | Stack / values | No aliasing, no leaks, no shared mutation |
|
||||
| HIP | Storage / heap | Explicit aliasing, shared mutation, refcounted |
|
||||
|
||||
You never cross between these worlds implicitly.
|
||||
|
||||
---
|
||||
|
||||
## 2. First Contact: SAFE‑Only PBS
|
||||
|
||||
A PBS program that never allocates lives entirely in the SAFE world.
|
||||
|
||||
SAFE code:
|
||||
|
||||
* uses value semantics
|
||||
* copies data on assignment (conceptually)
|
||||
* cannot leak memory
|
||||
* cannot accidentally share mutable state
|
||||
|
||||
This makes SAFE PBS ideal for:
|
||||
|
||||
* gameplay logic
|
||||
* math and simulation
|
||||
* AI logic
|
||||
* scripting without fear
|
||||
|
||||
Example:
|
||||
|
||||
```pbs
|
||||
let a = Vector(1, 2);
|
||||
let b = a; // conceptual copy
|
||||
|
||||
b.scale(2);
|
||||
// a is unchanged
|
||||
```
|
||||
|
||||
No pointers. No references. No surprises.
|
||||
|
||||
---
|
||||
|
||||
## 3. Values, Not Objects
|
||||
|
||||
PBS does not have objects with identity by default.
|
||||
|
||||
### 3.1 Value Types
|
||||
|
||||
All basic types are **values**:
|
||||
|
||||
* numbers
|
||||
* bool
|
||||
* string (immutable)
|
||||
* tuples
|
||||
* user‑defined `struct`
|
||||
|
||||
A value:
|
||||
|
||||
* has no identity
|
||||
* has no lifetime beyond its scope
|
||||
* is safe to copy
|
||||
|
||||
This matches how most gameplay data *should* behave.
|
||||
|
||||
---
|
||||
|
||||
## 4. Structs (Data First)
|
||||
|
||||
Structs are **pure data models**.
|
||||
|
||||
```pbs
|
||||
declare struct Vector(x: float, y: float)
|
||||
{
|
||||
pub fn len(self: this): float { ... }
|
||||
pub fn scale(self: mut this, s: float): void { ... }
|
||||
}
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
* fields are private
|
||||
* mutation is explicit (`mut this`)
|
||||
* no inheritance
|
||||
* no identity
|
||||
|
||||
Structs are designed to be:
|
||||
|
||||
* cache‑friendly
|
||||
* predictable
|
||||
* easy to reason about
|
||||
|
||||
---
|
||||
|
||||
## 5. Mutability Is a Property of Bindings
|
||||
|
||||
In PBS, **types are never mutable**. Bindings are.
|
||||
|
||||
```pbs
|
||||
let v = Vector.ZERO;
|
||||
v.scale(); // ERROR
|
||||
|
||||
let w = mut Vector.ZERO;
|
||||
w.scale(); // OK
|
||||
```
|
||||
|
||||
This single rule eliminates entire classes of bugs.
|
||||
|
||||
---
|
||||
|
||||
## 6. When You Need Power: Allocation (HIP World)
|
||||
|
||||
Allocation is **explicit**.
|
||||
|
||||
```pbs
|
||||
let enemies = alloc list<Enemy>();
|
||||
```
|
||||
|
||||
Once you allocate:
|
||||
|
||||
* data lives in Storage (heap)
|
||||
* access happens through **gates** (handles)
|
||||
* aliasing is real and visible
|
||||
|
||||
This is intentional and explicit.
|
||||
|
||||
---
|
||||
|
||||
## 7. Gates (Handles, Not Pointers)
|
||||
|
||||
A gate is a small value that refers to heap storage.
|
||||
|
||||
Properties:
|
||||
|
||||
* cheap to copy
|
||||
* may alias shared data
|
||||
* managed by reference counting
|
||||
|
||||
### 7.1 Strong vs Weak Gates
|
||||
|
||||
* **Strong gate** — keeps data alive
|
||||
* **Weak gate** — observes without ownership
|
||||
|
||||
```pbs
|
||||
let a = alloc Node;
|
||||
let w: weak<Node> = a as weak;
|
||||
let maybeA = w as strong;
|
||||
```
|
||||
|
||||
This model mirrors real engine constraints without hiding them.
|
||||
|
||||
---
|
||||
|
||||
## 8. Controlled Access to Storage
|
||||
|
||||
Heap data is never accessed directly.
|
||||
|
||||
You must choose *how*:
|
||||
|
||||
* `peek` — copy to SAFE
|
||||
* `borrow` — temporary read‑only access
|
||||
* `mutate` — temporary mutable access
|
||||
|
||||
```pbs
|
||||
mutate enemies as e
|
||||
{
|
||||
e.push(newEnemy);
|
||||
}
|
||||
```
|
||||
|
||||
This keeps mutation visible and scoped.
|
||||
|
||||
---
|
||||
|
||||
## 9. Errors Are Values
|
||||
|
||||
PBS has no exceptions.
|
||||
|
||||
### 9.1 `optional<T>`
|
||||
|
||||
Used when absence is normal.
|
||||
|
||||
```pbs
|
||||
let x = maybeValue else 0;
|
||||
```
|
||||
|
||||
### 9.2 `result<T, E>`
|
||||
|
||||
Used when failure matters.
|
||||
|
||||
```pbs
|
||||
let v = loadTexture(path)?;
|
||||
```
|
||||
|
||||
Error propagation is explicit and typed.
|
||||
|
||||
---
|
||||
|
||||
## 10. Control Flow Without Surprises
|
||||
|
||||
PBS favors explicit flow:
|
||||
|
||||
* `if` — control only
|
||||
* `when` — expression
|
||||
* `for` — bounded loops only
|
||||
|
||||
```pbs
|
||||
for i in [0b..count] {
|
||||
update(i);
|
||||
}
|
||||
```
|
||||
|
||||
No unbounded iteration by accident.
|
||||
|
||||
---
|
||||
|
||||
## 11. Services: Explicit API Boundaries
|
||||
|
||||
A `service` is how behavior crosses module boundaries.
|
||||
|
||||
```pbs
|
||||
pub service Audio
|
||||
{
|
||||
fn play(sound: Sound): void;
|
||||
}
|
||||
```
|
||||
|
||||
Services are:
|
||||
|
||||
* explicit
|
||||
* statically checked
|
||||
* singleton‑like
|
||||
|
||||
They map naturally to engine subsystems.
|
||||
|
||||
---
|
||||
|
||||
## 12. Contracts: Static Guarantees
|
||||
|
||||
Contracts define **what exists**, not how.
|
||||
|
||||
```pbs
|
||||
pub declare contract Gfx host
|
||||
{
|
||||
fn drawText(x: int, y: int, msg: string): void;
|
||||
}
|
||||
```
|
||||
|
||||
Contracts:
|
||||
|
||||
* have no runtime cost
|
||||
* are validated at compile time
|
||||
* define engine ↔ script boundaries
|
||||
|
||||
---
|
||||
|
||||
## 13. Modules (Simple and Predictable)
|
||||
|
||||
* one directory = one module
|
||||
* only `pub` symbols cross modules
|
||||
* no side effects on import
|
||||
|
||||
This keeps build and runtime deterministic.
|
||||
|
||||
---
|
||||
|
||||
## 14. Why PBS Works for Games
|
||||
|
||||
PBS is designed around real engine needs:
|
||||
|
||||
* frame‑based execution
|
||||
* explicit allocation
|
||||
* deterministic cleanup
|
||||
* predictable performance
|
||||
|
||||
It teaches developers **why engines are written the way they are**, instead of hiding reality.
|
||||
|
||||
---
|
||||
|
||||
## 15. Who PBS Is For
|
||||
|
||||
PBS is for:
|
||||
|
||||
* game developers who want control
|
||||
* engine developers
|
||||
* students learning systems concepts
|
||||
* educators teaching memory and runtime models
|
||||
|
||||
PBS is *not* for:
|
||||
|
||||
* rapid prototyping without constraints
|
||||
* general app scripting
|
||||
* hiding complexity
|
||||
|
||||
---
|
||||
|
||||
## 16. Design Promise
|
||||
|
||||
PBS makes one promise:
|
||||
|
||||
> **Nothing happens behind your back.**
|
||||
|
||||
If you understand PBS, you understand your runtime.
|
||||
|
||||
That is the product.
|
||||
Reference in New Issue
Block a user