integrated 14 into specs

This commit is contained in:
2026-03-24 13:42:18 +00:00
parent 1cacbd4f9a
commit 4b44674907
16 changed files with 2455 additions and 856 deletions
+537
View File
@@ -0,0 +1,537 @@
# PR — lsp-base (LSP MVP)
**Branch:** `pr-08-lsp-mvp`
## Briefing
Queremos um **LSP mínimo funcional** que já permita trabalhar PBS no VSCode com:
* erros aparecendo (diagnostics)
* navegação básica (goto definition)
* visão estrutural (document/workspace symbols)
Regras-chave (MVP):
* `didChange` será **full-text**
* rebuild será **coarse** (recompila o projeto inteiro) sempre que qualquer arquivo muda
* sem incremental analysis ainda
* comentários extensivos com exemplos se necessário e em inglês sempre
Este PR não inclui semantic tokens nem completion (virão nos PRs seguintes).
---
## Alvo (Features)
### LSP endpoints
* ✅ `initialize`
* ✅ `textDocument/didOpen`
* ✅ `textDocument/didChange` (FULL)
* ✅ `textDocument/didClose`
* ✅ `textDocument/documentSymbol`
* ✅ `workspace/symbol`
* ✅ `textDocument/definition`
* ✅ `textDocument/publishDiagnostics`
### Modelo de build
* `AnalysisDb` em memória
* `FileDb` (uri → texto)
* `rebuild()` recompila **workspace inteiro** e produz um snapshot
---
## Design (como deve funcionar)
### 1) AnalysisDb: estado e snapshot
**Objetivo:** separar “estado de arquivos” de “resultado de análise”.
Estruturas recomendadas:
```rust
pub struct AnalysisDb {
pub file_db: FileDb,
pub revision: u64,
pub active_rebuild: Option<RebuildHandle>,
pub last_good: Option<AnalysisSnapshot>,
}
pub struct AnalysisSnapshot {
pub diagnostics: Vec<Diagnostic>,
pub symbols: SymbolIndex, // index por Project/Module (coarse)
pub node_to_symbol: NodeToSymbol, // para definition
pub def_index: DefIndex, // opcional se você já tiver
pub ast: AstArena, // opcional (mas útil para nodes)
}
```
> Observação: use os tipos reais do seu compiler. O importante é ter um “snapshot” único que o LSP consulta.
### 2) Fluxo de rebuild
* `didOpen/didChange`:
* atualizar `file_db` com texto atual
* incrementar `revision`
* disparar `request_rebuild()` (coalescing)
* `request_rebuild()`:
* cancela rebuild anterior se houver
* agenda um rebuild assíncrono (tokio task)
* no fim, se não estiver cancelado e se `revision` não mudou, grava `last_good` e publica diagnostics
### 3) Diagnostics
* O compiler já deve produzir diagnostics com `Span { file, start, end }` em bytes.
* Para publicar, converter:
* `Span` → `lsp_types::Range` via `TextIndex` (já existe do refactor)
Regra:
* Diagnóstico sem `Span` (ou span inválido) deve ser **ignorado** ou degradado para range 0..0.
### 4) Definition
Ao receber `textDocument/definition`:
1. converter `Position` → byte offset (com `TextIndex`)
2. encontrar `NodeId` no ponto
3. resolver `NodeId -> SymbolId` via `node_to_symbol`
4. pegar `Symbol.decl_span`
5. converter `decl_span` → `Location`
> Se `NodeId` não existir ou não resolver símbolo: retornar `None`.
### 5) documentSymbol / workspaceSymbol
* `documentSymbol`: filtrar símbolos cujo `decl_span.file` == arquivo da request.
* `workspaceSymbol`: busca textual simples (contains/case-insensitive) nos nomes de símbolos (coarse) e retorna top N.
---
## Tarefas de implementação (checklist técnico)
### Capabilities em `initialize`
Declarar no server:
* `textDocumentSync: Full`
* `definitionProvider: true`
* `documentSymbolProvider: true`
* `workspaceSymbolProvider: true`
* `diagnosticProvider`: use publishDiagnostics (push)
### didOpen
* upsert texto
* request_rebuild
### didChange (Full)
* receber texto completo do doc
* upsert texto
* request_rebuild
### didClose
* remover do file_db (ou marcar fechado)
* publicar diagnostics vazios para o arquivo fechado
### Conversions
* `uri <-> FileId`: FileDb precisa mapear URI para FileId estável.
* `Span -> Range`: usar `TextIndex` do texto atual do arquivo.
* `Position -> byte`: usar `TextIndex`.
### Node lookup
Você precisa de uma função no snapshot (ou util) tipo:
* `fn node_at(file: FileId, byte: u32) -> Option<NodeId>`
MVP aceitável:
* se você ainda não tiver um índice de nodes por span, pode:
* usar AST arena e fazer busca linear na árvore (aceitável no coarse MVP)
---
## Test Harness (mínimo, mas real)
### Opção A (preferida): tests com `tower-lsp` client in-process
Criar um teste `tests/lsp_mvp.rs`:
* sobe o backend LSP em memória
* envia:
* `initialize`
* `didOpen` com um fixture PBS (2 arquivos)
* espera `publishDiagnostics` (pode interceptar via `Client` mock)
* chama `definition` em uma posição de uso e verifica que retorna `Location` do `decl_span`
**Aceite:**
* definition retorna arquivo correto
* range bate com span convertido
### Opção B (mais simples): unit tests nos adaptadores
Se o harness LSP demorar, pelo menos criar:
* `span_to_range_uses_utf16()`
* `position_to_byte_roundtrip()`
* `definition_resolves_to_decl_span()` usando snapshot fake.
---
## Checklist de aceite (obrigatório)
* [ ] `cargo test -q` passa no workspace
* [ ] VSCode: abrir arquivo `.pbs` mostra diagnostics (pelo menos 1 erro sintático)
* [ ] VSCode: `Go to Definition` funciona para símbolo resolvido
* [ ] VSCode: Outline mostra `documentSymbol`
* [ ] Mudanças em um arquivo disparam rebuild e atualizam diagnostics
* [ ] Unicode: diagnostics não ficam “desalinhados” (teste manual com `ação`/emoji)
---
## Fora de escopo (explicitamente)
* semantic tokens
* completion
* references/rename
* hover/signatureHelp
* incremental analysis e cancelation avançada
---
# PR — lsp-hightlight-base (Semantic Tokens — lexer-first)
**Branch:** `pr-12a-lsp-semantic-lexer`
## Briefing
Queremos **highlight no VSCode via LSP**, sem depender de resolver e sem TextMate.
Estratégia:
* Implementar `textDocument/semanticTokens/full`.
* Gerar tokens **lexer-first**: comments/strings/numbers/keywords/identifiers.
* Converter spans (bytes) para LSP positions (UTF-16) usando `TextIndex`.
* comentários extensivos com exemplos se necessário e em inglês sempre
Isso entrega um highlight “bom o suficiente” e muito estável, mesmo com arquivo com erro de parse.
---
## Alvo (Features)
* ✅ `textDocument/semanticTokens/full`
* ✅ `SemanticTokensLegend` consistente
* ✅ tokens derivados do lexer
Opcional (não obrigatório neste PR):
* `semanticTokens/range`
* `semanticTokens/full/delta`
---
## Design
### 1) Legend fixa
Escolher um conjunto pequeno de token types:
* `comment`
* `string`
* `number`
* `keyword`
* `operator` (opcional)
* `variable` (para identifiers genéricos)
> Não inventar muitos tipos agora; fácil expandir depois.
### 2) Fonte de tokens
Implementar uma função no analysis/compiler layer (ou no lsp crate) que, dado:
* `FileId`
* `text: &str`
retorna `Vec<(Span, TokenType, TokenModifiers)>`.
**Importante:**
* Spans são em bytes.
* Devem ser **não sobrepostos** e preferencialmente em ordem.
### 3) Conversão para formato LSP (deltas)
LSP semantic tokens usa encoding em deltas:
* `deltaLine`, `deltaStartChar`, `length`, `tokenType`, `tokenModifiers`
Algoritmo:
1. Converter `Span.start` e `Span.end` em `(line, utf16_col)`.
2. Calcular `length` em UTF-16 units para o trecho (start..end).
3. Ordenar por `(line, col)`.
4. Emitir deltas.
Regra:
* Se `Span` cruza linhas, **quebrar** em múltiplos tokens por linha (MVP seguro).
### 4) Robustez
* Token inválido (end < start, ou fora do texto) deve ser ignorado.
* Se o arquivo não estiver no `FileDb`, retornar tokens vazios.
---
## Tarefas de implementação
### Server capabilities
No `initialize`, anunciar:
* `semanticTokensProvider` com:
* `legend`
* `full: true`
* `range: false` (por enquanto)
### Handler
Implementar `semantic_tokens_full(params)`:
* pegar `uri`
* buscar texto no `file_db`
* gerar tokens do lexer
* converter com `TextIndex`
* retornar `SemanticTokensResult::Tokens`
### Lexer tokens
Se você já tem lexer com spans:
* mapear tokens para os tipos (keyword/string/comment/number/identifier)
* keywords: pode ser por enum do token ou por tabela
Se o lexer não marca keyword vs ident:
* fallback: parse por string e classifica keywords via `HashSet<&'static str>`.
---
## Testes
### Unit tests (obrigatórios)
1. `semantic_tokens_legend_is_stable()`
* garante que legend não muda sem intenção.
2. `semantic_tokens_are_sorted_and_non_negative()`
* gera tokens em um fixture com 2 linhas
* valida que deltas nunca ficam negativos e que ordem é válida.
3. `semantic_tokens_unicode_length_utf16()`
* texto com `ação🙂`
* valida que `length` corresponde a UTF-16 (emoji conta como 2).
### Teste manual (aceite)
* Abrir `.pbs` no VSCode
* Verificar:
* strings e comentários coloridos
* keywords coloridas
* números coloridos
* identifiers coloridos (mesmo que genérico)
---
## Checklist de aceite
* [ ] `cargo test -q` passa
* [ ] VSCode: arquivos PBS ficam coloridos via LSP (sem TextMate)
* [ ] Unicode não quebra offsets
* [ ] Arquivo com erro de parse ainda tem highlight (lexer-first)
---
## Fora de escopo
* semantic tokens semântico (type vs fn vs var) — virá em `PR-12b`
* `range`/`delta`
* completion
---
# PR — lsp-completion-base (Completion mínimo)
**Branch:** `pr-11a-lsp-completion-min`
## Briefing
Queremos autocomplete **mínimo mas útil** para conseguir escrever SDK/ECS em PBS sem fricção.
Princípio:
* Não depende de scope facts, nem type facts.
* Usa somente:
* keywords/builtins
* símbolos top-level do módulo atual
* exports/imports visíveis no projeto (coarse)
Isso é suficiente para começar a programar e evoluir o LSP depois.
* comentários extensivos com exemplos se necessário e em inglês sempre
---
## Alvo (Features)
* ✅ `textDocument/completion`
* ✅ `completionItem/resolve` (opcional; pode retornar item já completo)
---
## Design
### 1) Buckets e ordenação
Retornar `CompletionList` com itens nesta prioridade:
1. Keywords (`fn`, `let`, `mutate`, `declare`, `struct`, `storage`, `if`, `else`, `for`, `return`, etc.)
2. Builtins/funções globais (ex.: `alloc`, `box`, `unbox`, `range`, etc. — conforme spec do PBS)
3. Símbolos do módulo atual (top-level)
4. Símbolos “workspace visible” (exports/imports), limitado (ex.: top 200)
**Regra de ranking simples:**
* locals (não teremos) > módulo atual > workspace
### 2) Contexto
Para completion mínimo, só precisamos:
* `uri` do documento
* `position` (para pegar prefixo)
Prefixo:
* converter `Position` -> byte
* extrair texto até o cursor e identificar o “token parcial” (regex simples `[A-Za-z_][A-Za-z0-9_]*$`)
### 3) Fonte dos símbolos
Usar o `AnalysisSnapshot` (produzido na PR-08) para expor:
* `fn symbols_in_file(file: FileId) -> Vec<SymbolId>`
* `fn symbols_in_module(project: ProjectId, module: ModuleId) -> Vec<SymbolId>`
* `fn workspace_symbols() -> impl Iterator<Item = (name, kind, decl_span)>`
MVP aceitável:
* `workspace_symbols()` pode ser um vetor “flatten” pré-calculado no snapshot.
### 4) CompletionItem
Mapeamento para `CompletionItemKind`:
* functions -> `FUNCTION`
* types -> `CLASS` (ou `STRUCT` se quiser)
* modules -> `MODULE`
* variables/constants -> `VARIABLE` / `CONSTANT`
Campos:
* `label`: nome
* `detail`: (opcional) `"fn"/"type"/"module"`
* `sortText`: prefixado para impor bucket (ex.: `"1_"`, `"2_"`)
* `filterText`: label
---
## Tarefas de implementação
### Capabilities
No `initialize`:
* `completionProvider: { resolveProvider: false, triggerCharacters: [".", ":"]? }`
> Para completion mínimo, nem precisa trigger chars. Pode deixar default.
### Handler `completion`
* buscar texto e `TextIndex`
* calcular prefixo
* montar lista de candidatos por bucket
* filtrar por prefixo (case-sensitive ou insensitive; escolha e documente)
* limitar tamanho
* retornar `CompletionResponse::List`
### Builtins/keywords
Criar tabelas estáticas em `prometeu-lsp`:
* `static KEYWORDS: &[&str] = ...`
* `static BUILTINS: &[&str] = ...`
---
## Testes
### Unit tests (obrigatórios)
1. `completion_extracts_prefix()`
* valida regex de prefixo
2. `completion_includes_keywords()`
* chama handler com texto vazio e posição 0
* garante que `fn` aparece
3. `completion_filters_by_prefix()`
* prefixo `"ra"` deve sugerir `range` (se builtin)
4. (se possível) `completion_includes_module_symbols()`
* usando snapshot fake ou fixture compilado pela infra da PR-08
### Teste manual (aceite)
* Abrir arquivo PBS e digitar `ra` -> aparece `range`
* Digitar nome de tipo/fn do SDK -> aparece suggestion
---
## Checklist de aceite
* [ ] `cargo test -q` passa
* [ ] VSCode: autocomplete sugere keywords e builtins
* [ ] VSCode: autocomplete sugere símbolos do módulo atual
* [ ] Não trava com rebuild coarse
---
## Fora de escopo
* locals em scope
* members (`obj.`)
* signatureHelp
* hover
+219
View File
@@ -0,0 +1,219 @@
# LSP Roadmap — do “base usable” até “LSP completo”
> Este documento é o mapa incremental pós `lsp-base`, `lsp-hightlight-base`, `lsp-completion-base`.
> A ideia é manter o LSP evoluindo sem rework, enquanto SDK/ECS/Packer avançam em paralelo.
---
## Estado atual (após os 3 PRs base)
### ✅ Já temos
* Diagnostics (publishDiagnostics)
* Definition (goto definition)
* DocumentSymbol / WorkspaceSymbol
* Semantic tokens (lexer-first)
* Completion mínimo (keywords/builtins/top-level/module/workspace)
### ❌ Ainda não temos
* references / rename
* hover / signatureHelp
* completion com locals em scope
* semantic tokens semântico (type vs fn vs var)
* incremental analysis real (por arquivo / cancelation)
* debug map pc→span integrado com traps
* code actions / formatting
---
## Próximos PRs recomendados (ordem sugerida)
## PR-09 — References + Rename (seguro)
### Objetivo
Habilitar `references`, `prepareRename`, `rename` com regras de segurança.
### Pré-requisitos
* `RefIndex` completo (SymbolId -> usos em spans)
* `NodeToSymbol` estável
* `TriviaIndex` (comments/strings) para não renomear spans proibidos
### Regras de segurança
* Não renomear símbolo não-resolvido
* Não renomear em comentário/string
* Renomear deve gerar `WorkspaceEdit` apenas para spans válidos
### Testes
* Fixture com 2 arquivos: rename atualiza todas as refs
* Fixture: rename em comentário não altera nada
---
## PR-10 — Hover + SignatureHelp
### Objetivo
* `hover`: mostrar tipo + docstring (docstring opcional)
* `signatureHelp`: para call nodes
### Pré-requisitos
* Type facts básicos: `NodeId -> TypeId`
* Modelo de assinatura: para functions (params, retorno)
### Testes
* Hover em símbolo mostra tipo
* SignatureHelp em chamada mostra params
---
## PR-11b — Completion com locals em scope
### Objetivo
Autocomplete útil para código real:
* locals/params
* shadowing correto
### Pré-requisitos
* Binder/Scope facts:
* `Position -> ScopeId`
* `ScopeId -> bindings (name -> SymbolId/TypeId)`
### Testes
* Dentro de bloco, sugere variável local
* Shadowing: sugere a mais interna
---
## PR-12b — Semantic tokens resolver-backed (semântico)
### Objetivo
Melhorar highlight:
* diferenciar `type` vs `function` vs `variable` vs `parameter` vs `module`
### Pré-requisitos
* `NodeAtPosition` confiável
* `NodeToSymbol` confiável
* `SymbolKind` consistente
### Testes
* Identificador de tipo recebe token `type`
* Função recebe token `function`
---
## PR-13 — Formatting + Code Actions (opcional)
### Objetivo
* `textDocument/formatting` (nem que seja formatter simples/estável)
* code actions básicas:
* organizar imports
* criar stub de função/struct
### Pré-requisitos
* AST pretty printer (ou formatter incremental)
---
## PR-14 — Incremental analysis + cancelation (de verdade)
### Objetivo
Sair do rebuild coarse:
* recompilar somente arquivo/módulo afetado
* cancelamento real de builds longos
* snapshots por versão
### Pré-requisitos
* Graph de dependências por módulo
* Cache de parse/resolve por arquivo
* `revision` por doc
### Testes
* Editar arquivo A não recompila projeto inteiro
* Cancel: digitar rápido não aplica resultados velhos
---
## PR-15 — Debug map (pc→span) + integração com traps
### Objetivo
Quando a VM gerar trap/runtime error:
* mapear `pc` para `Span`
* mostrar erro com localização exata
### Pré-requisitos
* SourceMap gerado no backend bytecode
* runtime expõe `pc`/contexto
### Testes
* programa que gera trap aponta para linha/col corretos
---
# Backlog adicional (nice to have)
* `workspace/didChangeWatchedFiles` (reagir a mudanças fora do editor)
* `textDocument/codeLens` (ex.: run test / run main)
* `textDocument/inlayHint`
* `workspace/diagnostic` pull-mode (se quiser)
* semanticTokens `range` e `delta` para performance
---
## Interação com SDK/ECS/Packer
### Com os 3 PRs base, você já consegue:
* escrever SDK/ECS em PBS com feedback imediato
* navegar rapidamente pelo código
* manter arquivos grandes com highlight
* usar completion para nomes de APIs
### Enquanto isso, em paralelo:
* packer pode evoluir (não depende do LSP)
* quando packer estabilizar, podemos adicionar code actions/codelens para “build/pack/run” direto no VSCode
---
## Definição de “LSP completo” (para Prometeu view-ready)
Para chamar de "completo" (na sua visão de produto):
* ✅ diagnostics
* ✅ definition
* ✅ symbols
* ✅ highlight semântico
* ✅ completion com scope + members
* ✅ hover + signatureHelp
* ✅ references + rename
* ✅ incremental + cancel
* ✅ debug map integrado com traps
> A ordem acima é incremental por valor percebido e por dependências.
View File
+564
View File
@@ -0,0 +1,564 @@
# Prometeu Packer (prometeu-packer) — Specification (Draft)
> **Status:** Draft / Community-facing
>
> This document specifies the **Prometeu Packer**, the tooling responsible for **asset management** and producing two build artifacts:
>
> * `build/assets.pa` — the ROM payload containing packed asset bytes
> * `build/asset_table.json` — a machine-readable descriptor of the packed assets
>
> The Packer is deliberately **agnostic of cartridge building**. A separate **Cartridge Builder** (outside the Packer) consumes `build/asset_table.json` to generate the final `cartridge/manifest.json`, copy `assets.pa` to the cartridge directory, and zip the cartridge into a distributable format.
---
## 1. Goals and Non-Goals
### 1.1 Goals
1. **Be the guardian of sanity** in a constantly mutating `assets/` workspace.
* Users may be disorganized.
* The directory may contain WIP, junk, unused files, duplicates, outdated exports.
* The Packer must help users identify and fix mistakes.
2. Provide a robust, deterministic, **tooling-grade** asset pipeline.
* Stable asset identity.
* Deterministic packing order.
* Reproducible output bytes.
3. Support both **raw (direct) assets** and **virtual assets**.
* Raw assets: the payload in ROM is exactly the source bytes.
* Virtual assets: the payload is derived from multiple inputs via a build pipeline (e.g., PNG + palettes → `TILES` payload).
4. Produce an output descriptor (`build/asset_table.json`) suitable for:
* a Cartridge Builder to generate the runtime manifest
* CI checks
* a future IDE / GUI tooling
5. Provide an extensive **diagnostics chain** (doctor) with structured error codes and suggested fixes.
### 1.2 Non-Goals
* The Packer **does not**:
* generate `cartridge/manifest.json`
* decide preload slots
* copy files into `cartridge/`
* compile PBS bytecode
* zip cartridges
These responsibilities belong to a separate **Cartridge Builder**.
---
## 2. Repository / Project Layout (Golden Pipeline)
The Prometeu project uses the following canonical structure:
* `src/` — PBS scripts
* `assets/` — mutable asset workspace (WIP allowed)
* `build/` — generated artifacts and caches
* `cartridge/` — final cartridge directory (produced by Cartridge Builder)
* `prometeu.json` — project description (dependencies, version, etc.)
* `sdk/` — SDK/tooling and libraries
The Packer owns the asset workspace metadata under:
* `assets/.prometeu/` — Packer control directory (registry, cache, quarantine)
---
## 3. Crate Topology
### 3.1 Crates
* **`prometeu-packer`**
* **lib**: `prometeu_packer_core`
* **bin**: `prometeu-packer`
* a thin CLI wrapper delegating to `prometeu_packer_core::run()`
* **`prometeu` dispatcher**
* provides a wrapper command **`prometeup`** (or integrated subcommand)
* delegates to `prometeu-packer` for packer operations
### 3.2 Design Principle
Treat the Packer like the compiler: core library + CLI wrapper.
* The core library enables future integrations (IDE, GUI, watch mode) without shelling out.
* CLI is a stable interface for users and CI.
---
## 4. Mental Model: A “Git-like” Asset Workspace
The Packer treats `assets/` like a **dirty working tree**.
* `assets/` can contain *anything*.
* Only the assets registered in the Packer registry are considered part of the build.
This is analogous to Git:
* working tree (chaos) vs index (truth)
The **source of truth** for “what counts” is the registry:
* `assets/.prometeu/index.json`
---
## 5. Core Concepts
### 5.1 Managed Asset
A **managed asset** is an entry in `assets/.prometeu/index.json` pointing to an **asset root directory** that contains an anchor file:
* `asset.json` (the asset specification)
Everything else is free-form.
### 5.2 Asset Identity
Each asset has stable identity:
* `asset_id: u32` — stable within the project (used by runtime/tooling)
* `asset_uuid: string` — globally unique stable identifier (useful for IDE and future migrations)
Names and paths may change, but identity remains.
### 5.3 Asset Types (Bank Targets)
Assets ultimately target a **bank type** in the runtime:
* `TILES`
* `SOUNDS`
* (future) `SPRITESHEET`, `MAP`, `FONT`, `RAW_BLOB`, etc.
The Packer does **not** define bank memory semantics. It defines the *ROM payload* and its metadata.
### 5.4 Raw vs Virtual Assets
* **Raw assets**: ROM payload equals the source bytes.
* **Virtual assets**: ROM payload is derived from input(s) via deterministic build steps.
Examples:
* PNG + palette files → `TILES` payload (indexed pixels + packed palettes)
* WAV → PCM16LE payload
* Multiple PNGs → atlas spritesheet
---
## 6. Directory Structure and Control Files
### 6.1 Workspace
`assets/` is a mutable workspace:
* users may create nested organization trees
* junk files are allowed
### 6.2 Control Directory
The Packer stores its truth + tools state in:
```
assets/
.prometeu/
index.json
cache/
fingerprints.json
build-cache.json
quarantine/
...
```
* `index.json` — registry of managed assets
* `cache/` — fingerprints and incremental build cache
* `quarantine/` — optional area to move detected junk (only by explicit user action)
---
## 7. Asset Specification: `asset.json`
`asset.json` describes:
1. **the output ROM payload** expected by runtime
2. **the build pipeline** (for virtual assets)
3. **metadata** needed by runtime/builder
This spec is modular: **each asset format** (e.g. `TILES/indexed_v1`) has its own dedicated specification document.
### 7.1 Common Fields (All Assets)
* `schema_version`
* `name`
* `type` (bank type)
* `codec` (e.g. `RAW`; future: compression)
* `inputs` (for virtual assets)
* `output` (format + required metadata)
* `build` (optional pipeline configuration)
### 7.2 Virtual Asset Pipeline Declaration
Virtual assets must be declared in a way that is:
* deterministic
* fully materialized (no silent inference)
* explicit about defaults (defaults may exist, but must be written into `asset.json` or build outputs)
---
## 8. Build Artifacts Produced by the Packer
### 8.1 `build/assets.pa`
**`assets.pa`** is the ROM asset payload used by the runtime.
**Definition:** a contiguous binary blob where each managed asset contributes a payload region.
#### Key Properties
* Deterministic asset order (by `asset_id`)
* Offsets are recorded in `build/asset_table.json`
* Alignment rules (configurable by packer, default: no alignment unless required by a format)
**Note:** `assets.pa` is intentionally simple.
* No internal header is required.
* The authoritative structure comes from the descriptor (`asset_table.json`).
Future versions may introduce chunk tables, but v1 keeps ROM simple.
### 8.2 `build/asset_table.json`
**`asset_table.json`** is the canonical descriptor output of the Packer.
It contains:
* `assets_pa` file info (size, hash)
* `asset_table[]` entries describing each payload slice
* optional diagnostics/warnings
#### Asset Table Entry
An entry describes a ROM slice and its runtime meaning:
* `asset_id` — stable u32
* `asset_uuid` — stable UUID string
* `asset_name` — stable user-facing name
* `bank_type` — e.g. `TILES`, `SOUNDS`
* `offset` — byte offset in `assets.pa`
* `size` — bytes stored in ROM
* `decoded_size` — bytes after decode (equal to `size` when `codec=RAW`)
* `codec` — `RAW` (future: compression)
* `metadata` — format-specific metadata needed by runtime/builder
Additional tooling fields:
* `source_root` — path to asset dir
* `inputs` — resolved input paths
* `source_hashes` — stable fingerprints of inputs
`asset_table.json` is machine-readable and designed for:
* cartridge builder consumption
* IDE visualization
* debugging
---
## 9. Determinism Rules
1. Asset packing order MUST be deterministic.
* Default: increasing `asset_id`
2. All derived outputs MUST be deterministic.
* No random seeds unless explicitly declared
* Any seed must be written to output metadata
3. Default values MUST be materialized.
* If the packer infers something, it must be written into `asset.json` (via `--fix`) or recorded in build outputs.
---
## 10. Diagnostics and the “Sanity Guardian” Chain
The Packer provides structured diagnostics:
* `code` — stable diagnostic code
* `severity` — `error | warning | info`
* `path` — affected file
* `message` — human friendly
* `help` — extended context
* `fixes[]` — suggested automated or manual fixes
### 10.1 Diagnostic Classes
1. **Registered Errors** (break build)
* registry entry missing anchor file
* `asset.json` invalid
* missing inputs
* format/metadata mismatch
2. **Workspace Warnings** (does not break build)
* orphaned `asset.json` (not registered)
* unused large files
* duplicate inputs by hash
3. **Policy Hints** (optional)
* naming conventions
* missing preview
### 10.2 `doctor` Modes
* `doctor` (default) — validate registry only (fast)
* `doctor --workspace` — deep scan workspace (slow)
---
## 11. Incremental Build, Cache, and Fingerprints
The Packer maintains fingerprints of inputs:
* size
* mtime
* strong hash (sha256)
Stored in:
* `assets/.prometeu/cache/fingerprints.json`
This enables:
* detecting changes
* rebuild only what changed
* producing stable reports
The cache must never compromise determinism.
---
## 12. Quarantine and Garbage Collection
### 12.1 Quarantine
The Packer can optionally move suspected junk to:
* `assets/.prometeu/quarantine/`
Rules:
* Quarantine is **never automatic** without user consent.
* Packer must explain exactly what will be moved.
### 12.2 Garbage Collection (`gc`)
The Packer can report unused files:
* files not referenced by any registered asset
* orphaned asset dirs
Actions:
* list candidates
* optionally move to quarantine
* never delete without explicit user request
---
## 13. CLI Commands (Comprehensive)
> The CLI is a stable interface; all commands are implemented by calling `prometeu_packer_core`.
### 13.1 `prometeu packer init`
Creates the control directory and initial registry:
* creates `assets/.prometeu/index.json`
* creates caches directory
### 13.2 `prometeu packer add <path> [--name <name>] [--type <TILES|SOUNDS|...>]`
Registers a new managed asset.
* does not require moving files
* can create an asset root directory if desired
* generates `asset.json` with explicit defaults
* allocates `asset_id` and `asset_uuid`
Variants:
* `add --dir` creates a dedicated asset root dir
* `add --in-place` anchors next to the file
### 13.3 `prometeu packer adopt`
Scans workspace for unregistered `asset.json` anchors and offers to register them.
* default: dry-run list
* `--apply` registers them
### 13.4 `prometeu packer forget <name|id|uuid>`
Removes an asset from the registry without deleting files.
Useful for WIP and cleanup.
### 13.5 `prometeu packer rm <name|id|uuid> [--delete]`
Removes the asset from the registry.
* default: no deletion
* `--delete` can remove the asset root dir (dangerous; must confirm in UI tooling, or require a force flag in CLI)
### 13.6 `prometeu packer list`
Lists managed assets:
* id, uuid, name
* type
* status (ok/error)
### 13.7 `prometeu packer show <name|id|uuid>`
Shows detailed information:
* resolved inputs
* metadata
* fingerprints
* last build summary
### 13.8 `prometeu packer doctor [--workspace] [--strict] [--fix]`
Runs diagnostics:
* `--workspace` deep scan
* `--strict` warnings become errors
* `--fix` applies safe automatic fixes (materialize defaults, normalize paths)
### 13.9 `prometeu packer build [--out build/assets.pa] [--table build/asset_table.json]`
Builds:
* `build/assets.pa`
* `build/asset_table.json`
Key behaviors:
* validates registry before packing
* packs assets deterministically
* for virtual assets, runs build pipelines
* records all offsets and metadata
### 13.10 `prometeu packer watch`
Watches registered inputs and registry changes.
* emits events (future)
* rebuilds incrementally
`watch` is optional in v0 but recommended.
### 13.11 `prometeu packer gc [--workspace] [--quarantine]`
Reports unused files.
* default: report only
* `--quarantine` moves candidates to quarantine
### 13.12 `prometeu packer quarantine <path> [--restore]`
Moves or restores files into/from quarantine.
---
## 14. Virtual Assets (Deep Explanation)
Virtual assets are a major capability.
### 14.1 Why Virtual Assets
* Most runtime formats should be derived from human-friendly authoring formats.
* Example:
* author uses `source.png` and palette files
* runtime expects indexed pixels + packed RGB565 palettes
### 14.2 Virtual Asset Contract
* Inputs are explicit.
* Build steps are deterministic.
* Outputs match a well-defined runtime payload format.
### 14.3 Examples of Future Virtual Assets
* `TILES/indexed_v1`: PNG + palette files → indexed pixels + packed palettes
* `SOUNDS/pcm16le_v1`: WAV → PCM16LE
* `SPRITESHEET/atlas_v1`: multiple PNG frames → atlas + metadata
Each `output.format` must have its own dedicated spec.
---
## 15. Integration with Cartridge Builder
The Cartridge Builder should:
1. Compile PBS into bytecode (e.g. `program.pbc` / `program.pbx`)
2. Call `prometeu packer build`
3. Consume `build/asset_table.json` and produce `cartridge/manifest.json`
4. Copy artifacts into `cartridge/`
5. Zip the cartridge into a distributable format (`.crt` / `.rom` / `.pro`)
The packer never touches `cartridge/`.
---
## 16. Compatibility and Versioning
* `assets/.prometeu/index.json` has `schema_version`
* `asset.json` has `schema_version`
* `build/asset_table.json` has `schema_version`
The Packer must be able to migrate older schema versions or emit actionable diagnostics.
---
## 17. Security and Trust Model
* The Packer is offline tooling.
* It must never execute untrusted scripts.
* It should treat external inputs as untrusted data.
---
## 18. Implementation Notes (Non-Normative)
* Rust implementation with a core crate + CLI wrapper.
* Prefer structured JSON serde models.
* Use stable diagnostic codes.
* Keep the build deterministic.
---
## Appendix A — Glossary
* **ROM (`assets.pa`)**: packed asset payload used by runtime
* **Descriptor (`asset_table.json`)**: mapping from logical assets to ROM slices
* **Managed asset**: registered asset with stable identity and anchor file
* **Virtual asset**: derived asset built from multiple inputs
* **Quarantine**: safe area for suspected junk
* **Doctor**: diagnostic command to keep sanity