Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity

added agendas

Browse Source
This commit is contained in:
bQUARKz 2026-03-04 15:58:07 +00:00
parent af8f4304b9
commit 60e0875147
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
12 changed files with 446 additions and 335 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
devtools/typescript-sdk/package.json
View File

@ -1,7 +0,0 @@
{
"name": "@prometeu/sdk",
"version": "0.1.0",
"type": "module",
"main": "src/index.ts",
"types": "types/index.d.ts"
}

57
devtools/typescript-sdk/tooling/eslint/base.js
View File

@ -1,57 +0,0 @@
export function createPrometeuEslintConfig({ tsParser, tseslint }) {
if (!tsParser || !tseslint) {
throw new Error(
"createPrometeuEslintConfig requires { tsParser, tseslint } provided by the project (root node_modules).",
);
}
return [
{
files: ["**/*.ts", "**/*.tsx"],
languageOptions: {
parser: tsParser,
parserOptions: {
ecmaVersion: "latest",
sourceType: "module",
},
},
plugins: {
"@typescript-eslint": tseslint,
},
rules: {
"@typescript-eslint/no-unused-vars": [
"warn",
{
varsIgnorePattern: "^(frame)$",
},
],
"@typescript-eslint/typedef": [
"error",
{
variableDeclaration: false,
variableDeclarationIgnoreFunction: false,
parameter: true,
propertyDeclaration: true,
memberVariableDeclaration: true,
arrowParameter: true,
},
],
"no-restricted-syntax": [
"error",
{
selector: "TSUnionType:not(:has(TSNullKeyword))",
message:
"Union types are not allowed in Prometeu code style (exception: T | null).",
},
{
selector: "TSUnionType:has(TSUndefinedKeyword)",
message:
"Use null (T | null) instead of undefined (T | undefined) in Prometeu code style.",
},
],
},
},
];
}

20
devtools/typescript-sdk/tsconfig.json
View File

@ -1,20 +0,0 @@
{
"compilerOptions": {
"strict": true,
"noImplicitAny": true,
"strictNullChecks": true,
"noImplicitThis": true,
"alwaysStrict": true,
"noImplicitReturns": true,
"noFallthroughCasesInSwitch": true,
"exactOptionalPropertyTypes": true,
"useUnknownInCatchVariables": true,
"noUncheckedIndexedAccess": true,
"forceConsistentCasingInFileNames": true
}
}

99
devtools/typescript-sdk/types/index.d.ts vendored
View File

@ -1,99 +0,0 @@
export {}; // that is a module, should not include any other scope here
declare global {
namespace Prometeu {
type Color565 = number & { readonly __brand: "Color565" };
interface Button {
readonly down: boolean;
readonly pressed: boolean;
readonly released: boolean;
readonly holdFrames: number;
}
interface Pad {
readonly up: Button;
readonly down: Button;
readonly left: Button;
readonly right: Button;
readonly a: Button;
readonly b: Button;
readonly x: Button;
readonly y: Button;
readonly l: Button;
readonly r: Button;
readonly start: Button;
readonly select: Button;
}
interface Touch {
readonly x: number;
readonly y: number;
readonly button: Button;
}
interface Gfx {
clear(color: Color565): void;
fillRect(x: number, y: number, w: number, h: number, color: Color565): void;
drawLine(x1: number, y1: number, x2: number, y2: number, color: Color565): void;
drawCircle(x: number, y: number, r: number, color: Color565): void;
drawDisc(x: number, y: number, r: number, borderColor: Color565, fillColor: Color565): void;
drawSquare(x: number, y: number, w: number, h: number, borderColor: Color565, fillColor: Color565): void;
drawText(x: number, y: number, s: string, color: Color565): void;
setSprite(assetName: string, id: number, x: number, y: number, tileId: number, paletteId: number, active: boolean, flipX: boolean, flipY: boolean, priority: number): void;
}
interface Color {
readonly black: Color565;
readonly white: Color565;
readonly red: Color565;
readonly green: Color565;
readonly blue: Color565;
readonly yellow: Color565;
readonly cyan: Color565;
readonly magenta: Color565;
readonly indigo: Color565;
readonly color_key: Color565;
readonly orange: Color565;
readonly gray: Color565;
readonly grey: Color565;
rgb(r: number, g: number, b: number): Color565;
}
interface System {
hasCart(): boolean;
}
interface Audio {
playSample(sampleId: number, voiceId: number, volume: number, pan: number, pitch: number): void;
play(assetName: string, sampleId: number, voiceId: number, volume: number, pan: number, pitch: number, loopMode: number): void;
}
interface Fs {
open(path: string): number;
read(handle: number): string | null;
write(handle: number, content: string): boolean;
close(handle: number): void;
listDir(path: string): string | null;
exists(path: string): boolean;
delete(path: string): boolean;
}
interface Log {
write(level: number, msg: string): void;
writeTag(level: number, tag: number, msg: string): void;
}
}
export const color: Prometeu.Color;
export const pad: Prometeu.Pad;
export const touch: Prometeu.Touch;
export const gfx: Prometeu.Gfx;
export const audio: Prometeu.Audio;
export const fs: Prometeu.Fs;
export const log: Prometeu.Log;
export const system: Prometeu.System;
}

77
docs/runtime/agendas/003-structured-runtime-abi.md
View File

@ -1,77 +0,0 @@
# Agenda - Structured Runtime ABI
## Problema
Partes importantes da borda do runtime ainda escapam para strings, texto ad hoc e JSON serializado para transportar dados estruturados.
Exemplos atuais:
- `fs.read` converte bytes para `String`;
- `fs.list_dir` concatena nomes com separador textual;
- `bank.info` e `bank.slot_info` devolvem JSON em um slot string.
## Dor
- O ABI deixa de ser estrutural e volta a depender de parsing textual no guest.
- Binários e bytes arbitrários ficam mutilados por `UTF-8 lossy`.
- Contratos ficam frágeis: delimitadores, shape do JSON e nomes de campo viram parte implícita da API.
- Isso contradiz a linha central do projeto: sem mágica, sem heurística, sem ambiguidade.
- O custo futuro aumenta porque qualquer linguagem cliente passa a embutir parser de conveniência para tapar buraco de ABI.
## Alvo da Discussao
Definir um modelo canônico para dados estruturados e/ou binários na fronteira guest <-> runtime.
Essa agenda precisa responder se o runtime vai operar com:
- slots primitivos fixos;
- objetos heapados do VM;
- handles opacos para buffers/iteradores;
- uma combinação dessas estratégias por domínio.
## O Que Precisa Ser Definido
1. Modelo de retorno estruturado.
Como representar listas, metadados de banco, resultados de leitura e payload binário sem texto improvisado.
2. Política para bytes.
`fs.read` deve retornar buffer/array/handle, nao string textual.
3. Política para structs.
`bank.info`, `button`, `slot info` e similares devem ter shape canônico:
- flatten em slots;
- objeto heapado;
- view estruturada com metadata fixa.
4. Política para listas.
`fs.list_dir` nao deve depender de delimitador textual; precisa de shape navegável.
5. Impacto no verifier e no HostReturn.
Se houver objetos heapados retornados por syscalls, a ABI e o runtime precisam suportar isso sem atalhos temporários.
6. Estratégia de migração.
Como substituir contratos atuais sem consolidar compatibilidade acidental ruim.
## O Que Necessita Para Resolver
- decisão arquitetural para transporte de dados estruturados;
- catálogo das syscalls afetadas;
- atualização do ABI canônico;
- estratégia de teste para garantir integridade de bytes e shape estável;
- posição explícita sobre backward compatibility.
## Fora de Escopo
- serialização genérica estilo JSON para tooling externo;
- reflection completa no guest;
- coleção completa de tipos ricos do SDK.
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisão escrita sobre:
- shape canônico por domínio afetado;
- representação de bytes;
- impacto no heap/GC/HostReturn;
- política de migração;
- suite mínima de testes de ABI.

97
docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md Normal file
View File

@ -0,0 +1,97 @@
# Agenda - VM-Owned Byte Buffer ABI
## Problema
O runtime ainda trata bytes como texto em partes da borda host <-> guest.
Exemplo atual:
- `fs.read` converte bytes para `String`.
Ao mesmo tempo, o projeto ja decidiu que:
- o host nunca devolve handles opacos;
- o host nunca devolve chunks de memoria host-owned;
- syscalls falam com o runtime apenas via stack;
- banks de hardware (`image`, `tilemap`, `sound`) trafegam apenas IDs;
- as unicas excecoes reais de payload binario sao `fs` e o futuro bank de dados.
## Dor
- bytes arbitrarios continuam vulneraveis a `UTF-8 lossy`;
- a fronteira host <-> guest fica ambigua;
- o runtime corre o risco de introduzir atalhos proibidos, como handles host-owned;
- `fs` e bank de dados ficam sem contrato canonico para copia de bytes.
## Alvo da Discussao
Definir o contrato canonico para syscalls que precisam copiar bytes do host para memoria da VM, usando:
- stack para argumentos e resultados;
- `HeapRef(Byte)` VM-owned como destino;
- preenchimento de memoria pelo host sem ownership host-side.
## Decisoes Ja Fixadas
- nao ha retorno estruturado generico por objetos heapados do host;
- nao ha handles opacos de buffers;
- nao ha backward compatibility;
- `button` fica fora desta agenda porque eh intrinsic;
- banks de hardware nao trafegam bytes para a VM.
## O Que Precisa Ser Definido
1. `Value::Byte`.
O ABI precisa de um valor primitivo `Byte` real, em vez de tratar byte como caso derivado de outro tipo.
2. `HeapRef(Byte)` como destino canonico.
A agenda precisa fechar como a VM aloca e tipa buffers de bytes que poderao ser preenchidos pelo host.
3. Protocolo de copia host -> VM.
Como a syscall recebe:
- referencia de destino;
- capacidade disponivel;
- offset/logica de janela, se aplicavel.
4. Shape de retorno via stack.
Como a syscall informa:
- quantidade de bytes escritos;
- EOF;
- leitura parcial;
- falha.
5. Impacto no verifier e no runtime.
O runtime precisa validar:
- tipo correto do heap ref;
- bounds;
- capacidade de escrita;
- integracao com `HostReturn` sem atalhos temporarios.
6. Relaçao com fault classification.
A agenda precisa explicitar quais erros pertencem ao contrato local de copia e quais dependem da agenda de falhas de syscall.
## O Que Necessita Para Resolver
- definicao normativa de `Value::Byte`;
- definicao normativa de `HeapRef(Byte)`;
- protocolo de syscall para copia de bytes;
- lista das operacoes que usarao esse contrato (`fs` e bank de dados);
- suite minima de testes de integridade de bytes e bounds.
## Fora de Escopo
- listas estruturadas retornadas pelo host;
- structs retornadas pelo host;
- `button` e outros intrinsics;
- design completo da API de `fs`;
- modelagem funcional do bank de dados.
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- semantica de `Value::Byte`;
- uso de `HeapRef(Byte)` VM-owned;
- shape exato do protocolo stack-based de copia;
- impacto minimo em verifier e `HostReturn`;
- suite minima de testes para bytes arbitrarios, leitura parcial e bounds.

3
docs/runtime/agendas/004-syscall-fault-classification.md
View File

@ -39,7 +39,8 @@ O objetivo é estabelecer uma regra previsível para classificar:
- falha interna de serviço.
2. Mapeamento por domínio.
FS, assets, bank, log, gfx, input e system precisam seguir a mesma filosofia.
FS, assets, bank, log, gfx e system precisam seguir a mesma filosofia.
`input` so permanece aqui enquanto ainda existir como syscall; se migrar integralmente para intrinsic, sai deste escopo.
3. Superfície de telemetria e crash report.
O que deve aparecer para usuário, tooling e testes.

98
docs/runtime/agendas/009-filesystem-surface-and-semantics.md Normal file
View File

@ -0,0 +1,98 @@
# Agenda - Filesystem Surface and Semantics
## Problema
O filesystem do runtime ainda esta subdefinido como superficie de API e como contrato semantico.
Hoje a discussao de `fs` tende a misturar:
- transporte de bytes;
- shape das operacoes;
- semantica de caminho e sandbox;
- classificacao de falhas;
- persistencia e determinismo.
Isso torna facil decidir localmente `fs.read` sem fechar o restante do dominio.
## Dor
- a API de `fs` pode crescer de forma acidental e incoerente;
- `list_dir`, `read`, `write`, metadados e mutacoes correm o risco de adotar contratos diferentes entre si;
- o runtime pode prometer mais semantica do que a plataforma consegue sustentar com portabilidade;
- testes e certificacao ficam sem alvo preciso.
## Alvo da Discussao
Definir a superficie canonica do dominio `fs` no runtime, separando claramente:
- o que e responsabilidade da agenda `003-vm-owned-byte-buffer-abi`;
- o que e responsabilidade propria do filesystem.
## O Que Precisa Ser Definido
1. Superficie minima de operacoes.
Quais operacoes existem no MVP do dominio `fs`.
Exemplos candidatos:
- `read`
- `write`
- `exists`
- `stat`
- `list_dir`
- `delete`
- `mkdir`
2. Modelo de chamada.
Definir se `fs` opera:
- por caminho direto;
- por IDs/descritores;
- por combinacao restrita.
3. Semantica de caminhos.
Como paths logicos sao validados, normalizados e limitados.
4. Semantica de leitura e escrita.
Definir:
- leitura total vs parcial;
- append vs overwrite;
- truncation;
- criacao implicita ou nao.
5. Semantica de diretórios.
`list_dir` precisa de contrato proprio.
Esta agenda deve decidir se ela existe no MVP e, se existir, qual o shape canonico do resultado.
6. Metadados.
Quais metadados o runtime expoe:
- tamanho;
- tipo;
- timestamps ou nao;
- flags de portabilidade.
7. Persistencia, sandbox e portabilidade.
O que `fs` promete em todas as plataformas e o que explicitamente nao promete.
8. Relacao com fault classification.
Quais erros `fs` pode produzir e quais classes de falha o dominio precisa usar.
## Dependencias
- `003-vm-owned-byte-buffer-abi.md` para transporte de bytes;
- `004-syscall-fault-classification.md` para shape de erro;
- specs de portabilidade para alinhamento com sandbox logico.
## Fora de Escopo
- detalhes internos de armazenamento por plataforma;
- banco de dados persistente;
- handles host-owned;
- compatibilidade retroativa.
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- conjunto minimo de operacoes de `fs`;
- shape de chamada de cada operacao;
- semantica de path, diretorio e persistencia;
- dependencia explicita do ABI de bytes da `003`;
- suite minima de testes funcionais de filesystem.

135
docs/runtime/agendas/010-input-intrinsics-surface.md Normal file
View File

@ -0,0 +1,135 @@
# Agenda - Input Intrinsics Surface
## Problema
`input` ja esta conceitualmente do lado de intrinsics, nao de syscalls, mas a superficie concreta desse dominio ainda nao esta congelada.
Nesta agenda, `input` significa o dominio formado por:
- `pad`;
- `touch`.
Sem uma agenda propria, o dominio de input corre o risco de ficar:
- espalhado pela spec de input;
- implícito no ISA;
- indefinido no verifier;
- lembrado tarde demais na fase de implementacao.
Hoje existe uma ambiguidade concreta no runtime:
- as specs tratam input como estado amostrado por frame;
- a linguagem/runtime quer expor `pad` e `touch` como surface built-in do guest;
- mas a implementacao ainda coleta esse estado por syscalls.
Exemplos atuais no runtime:
- `InputGetPad`
- `InputGetPadPressed`
- `InputGetPadReleased`
- `InputGetPadHold`
- `InputPadSnapshot`
- `InputTouchSnapshot`
- `TouchGetX`
- `TouchGetY`
- `TouchIsDown`
- `TouchIsPressed`
- `TouchIsReleased`
- `TouchGetHold`
- `TouchGetFinger`
- `PadGetUp` ate `PadGetSelect`
## Dor
- o runtime pode implementar intrinsics de input com shape arbitrario;
- custo, assinatura e IDs logicos podem divergir entre docs;
- o verifier pode aceitar chamadas sem contrato fechado;
- `button` pode ganhar peso desproporcional e esconder que ele eh apenas uma parte da surface de `pad`;
- o dominio de input fica misturado com decisoes de syscall, onde ele nao pertence.
- o runtime mantem duas historias ao mesmo tempo: input como estado latched e input como host service;
- a superficie explode em muitas syscalls pequenas para ler algo que ja esta disponivel como estado do hardware.
## Alvo da Discussao
Definir a superficie canonica dos intrinsics de input observavel pela VM.
`pad` e `touch` sao os dois blocos do dominio.
`button` entra aqui apenas como parte da surface de `pad`, nao como centro exclusivo da agenda.
Esta agenda tambem precisa decidir a migracao explicita:
- quais syscalls de input serao removidas;
- quais intrinsics as substituem;
- qual surface final o guest enxerga como built-in.
## O Que Precisa Ser Definido
1. Conjunto de intrinsics.
Quais operacoes existem no MVP:
- operacoes de `pad`;
- operacoes de `touch`, se entrarem no MVP.
No caso de `pad`, os candidatos iniciais sao:
- `btn`
- `btnp`
- `btnr`
- `axis`, se entrar ou nao.
2. Assinatura exata.
Definir:
- argumentos;
- tipo de retorno;
- custo/cycles;
- comportamento para ID invalido;
- comportamento para ausencia de suporte do dispositivo.
3. Superfícies do dominio.
Fechar quais familias de input a VM pode consultar no contrato inicial:
- pad;
- axis;
- touch.
4. Identificadores logicos.
Fechar o conjunto de IDs logicos que a VM pode consultar.
Isso inclui:
- botoes do pad;
- eixos, se existirem;
- pontos/canais de touch, se existirem.
5. Integracao com ISA e verifier.
Como os intrinsics sao referenciados, validados e emitidos no bytecode.
6. Migração da surface atual.
Definir:
- quais syscalls de input deixam de existir;
- se toda leitura de `pad` e `touch` sai da ABI de syscall;
- como a toolchain e a surface do guest passam a apontar apenas para intrinsics.
7. Observabilidade.
O que entra em trace, certificacao e relatorios de custo.
## Dependencias
- ISA/intrinsic model da VM;
- spec de input para o dominio logico;
- definicao de fault ou resposta para IDs invalidos, se houver;
- alinhamento com a spec de touch, se o dominio entrar no MVP.
## Fora de Escopo
- mapeamento fisico de teclado/gamepad;
- pipeline de coleta de input no host;
- gestos de alto nivel;
- novos syscalls de input;
- transporte de bytes.
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- lista final de intrinsics de input;
- assinatura e retorno de cada intrinsic;
- superfícies de input suportadas no MVP;
- IDs logicos suportados;
- lista das syscalls de input a serem removidas;
- integracao com ISA, verifier e tracing.

95
docs/runtime/agendas/011-input-frame-semantics-and-portability.md Normal file
View File

@ -0,0 +1,95 @@
# Agenda - Input Frame Semantics and Portability
## Problema
O dominio de input ja tem uma direcao documental, mas ainda precisa de fechamento operacional na borda runtime <-> plataforma.
Nesta agenda, `input` significa o dominio formado por:
- `pad`;
- `touch`.
Sem isso, intrinsics de input podem existir com nome certo e semantica errada.
Hoje a dor nao eh apenas teorica:
- `pad` e `touch` ja sao latched no host no inicio do frame;
- `Button` ja eh a unidade de estado usada por `pad` e pelo toque ativo;
- mas o runtime ainda expoe a leitura desse estado por syscalls em vez de intrinsics.
## Dor
- ambiguidades sobre quando o input e amostrado;
- risco de divergencia entre plataformas sobre pressed/held/released do `pad`;
- risco de divergencia sobre touch ativo, posicao, multitouch e ausencia de touch;
- replay, certificacao e reproducibilidade ficam dependentes de interpretacao;
- edge cases de foco, multiplos dispositivos e conflitos de direcao ficam sem dono.
- a borda guest pode acabar observando input como consulta host-driven, quando o modelo correto eh leitura de estado ja congelado no frame.
## Alvo da Discussao
Fixar a semantica temporal e de portabilidade do dominio de input.
`pad` e `touch` sao os dois subconjuntos principais do contrato.
`button` entra apenas como parte da semantica de `pad`.
## O Que Precisa Ser Definido
1. Momento de amostragem.
Em que ponto do frame o estado e capturado e congelado.
2. Semantica de estado.
Definir formalmente:
- pressed no `pad`;
- released no `pad`;
- held no `pad`;
- transicao entre frames.
3. Semantica de touch.
Definir formalmente, se touch fizer parte do contrato:
- ponto ativo ou inativo;
- coordenadas;
- multitouch ou touch unico;
- persistencia entre frames.
4. Determinismo e replay.
Como input gravado, injetado ou reproduzido conversa com o runtime.
5. Regras de portabilidade.
O que deve ser igual em todas as plataformas e o que pode variar.
6. Edge cases.
Exemplos:
- perda de foco;
- multiplos devices;
- direcoes opostas simultaneas no `pad`;
- ausencia de determinado dispositivo fisico;
- plataforma sem touch;
- diferenca de resolucao ou area de toque.
7. Relacao com CAP e certificacao.
Como consultas de input aparecem em custo e relatorios.
Esta agenda tambem precisa decidir se input continua ou nao exigindo capability de syscall depois da migracao para intrinsic.
## Dependencias
- `010-input-intrinsics-surface.md`;
- spec de input;
- modelo de frame do runtime.
## Fora de Escopo
- opcode ou encoding do intrinsic;
- mapeamento detalhado por plataforma;
- bytes e heap.
## Critério de Saida Desta Agenda
Pode virar PR quando houver decisao escrita sobre:
- momento de amostragem;
- semantica formal dos intrinsics de input do MVP;
- regras de replay e reproducibilidade;
- edge cases minimos que o runtime precisa tratar;
- posicao explicita sobre a saida de `input` da fronteira de syscall;
- impactos em CAP e certificacao.

26
docs/runtime/agendas/README.md
View File

@ -12,9 +12,12 @@ As agendas atuais são:
- `001-system-run-cart.md`
- `002-packed-cartridge-loader-pmc.md`
- `003-structured-runtime-abi.md`
- `003-vm-owned-byte-buffer-abi.md`
- `004-syscall-fault-classification.md`
- `005-runtime-edge-test-plan.md`
- `009-filesystem-surface-and-semantics.md`
- `010-input-intrinsics-surface.md`
- `011-input-frame-semantics-and-portability.md`
## Sequenciamento Recomendado
@ -23,18 +26,24 @@ Ordem sugerida para discussão e futura execução:
1. `007-single-canonical-architecture.md`
2. `008-hardware-specs-reorganization.md`
3. `006-break-monolith-runtime.md`
4. `003-structured-runtime-abi.md`
4. `003-vm-owned-byte-buffer-abi.md`
5. `004-syscall-fault-classification.md`
6. `005-runtime-edge-test-plan.md`
7. `001-system-run-cart.md`
8. `002-packed-cartridge-loader-pmc.md`
6. `009-filesystem-surface-and-semantics.md`
7. `010-input-intrinsics-surface.md`
8. `011-input-frame-semantics-and-portability.md`
9. `005-runtime-edge-test-plan.md`
10. `001-system-run-cart.md`
11. `002-packed-cartridge-loader-pmc.md`
Justificativa curta:
- `007` vem primeiro porque elimina ambiguidade sobre qual documento manda.
- `008` vem em seguida porque reorganiza o terreno documental onde specs e arquitetura se apoiam.
- `006` entra depois porque refactor estrutural grande sem documentação estável tende a cristalizar decisões erradas.
- `003` e `004` formam o núcleo de contrato da borda do runtime.
- `003` fecha o contrato base para trafego de bytes VM-owned.
- `004` fecha a taxonomia de falhas que `fs` e outras bordas vao reutilizar.
- `009` usa `003` e `004` para fechar o dominio de filesystem sem texto improvisado.
- `010` e `011` isolam o dominio maior de input fora de syscall, tratando `pad` e `touch` como superfícies centrais, `button` como parte de `pad`, e explicitando a migracao da leitura de input para intrinsics.
- `005` fecha a barra de qualidade antes das implementações mais arriscadas.
- `001` e `002` dependem mais fortemente de contrato de sistema, ABI e documentação estáveis.
@ -42,7 +51,10 @@ Dependências principais:
- `008` depende de `007`
- `006` depende de `007`
- `001` depende de `007`, `003`, `004` e `005`
- `009` depende de `003` e `004`
- `010` depende de `007`
- `011` depende de `010`
- `001` depende de `007`, `003`, `004`, `005` e deve alinhar com `009` quando usar `fs`
- `002` depende de `007` e deve ser alinhada com a reorganização documental de `008`
Regra de uso:

67
docs/runtime/pull-requests/PR-013-[DEBUGGER]-consume-structured-fault-events.md
View File

@ -1,67 +0,0 @@
# PR-013 [DEBUGGER]: Consume Structured Fault Events
## Briefing
O runtime e o host agora produzem `CrashReport` e emitem evento `fault` estruturado no protocolo do debugger. Mas o lado consumidor do DevTools ainda nao foi ajustado para tratar esse evento como dado de primeira classe. Sem isso, o debugger continua dependente de logs gerais ou de texto livre para exibir falhas da VM.
Esta PR fecha a ponta do debugger: faults estruturados passam a ser recebidos, armazenados e renderizados como diagnostico explicito, separado de logs e telemetria numerica.
## Problema
- o protocolo ja expõe `DebugEvent::Fault`, mas o cliente do debugger ainda pode ignorar esse evento;
- traps, panics e falhas de init continuam sem superficie dedicada no tooling;
- o operador do debugger nao consegue distinguir com clareza:
- log normal;
- violacao de certificacao;
- fault terminal da VM.
## Alvo
- cliente do debugger / DevTools que consome `DebugEvent`
- componentes de UI/estado que exibem logs, telemetria e status de execucao
- testes do lado cliente do debugger, se existirem no repo
## Escopo
- Consumir `DebugEvent::Fault` como evento estruturado, nao como log generico.
- Exibir pelo menos:
- tipo (`vm_trap`, `vm_panic`, `vm_init`);
- resumo;
- `pc`, quando existir;
- `trap_code` e `opcode`, quando existirem.
- Manter faults historicos recentes no estado do debugger de forma simples e deterministica.
- Garantir que um fault terminal fique visualmente distinguivel de log comum.
## Fora de Escopo
- Redesenhar toda a UI do debugger.
- Alterar novamente o protocolo do host, salvo ajuste minimo estritamente necessario.
- Implementar crash screen dentro da VM/firmware.
- Introduzir persistencia em disco de faults do debugger.
## Abordagem
1. Auditar o cliente do debugger e localizar onde `DebugEvent` e desserializado e roteado.
2. Adicionar tratamento explicito para `fault`, com estado proprio no cliente.
3. Renderizar o fault em area dedicada ou secao claramente separada de logs.
4. Preservar os campos estruturados; nenhuma logica deve depender de parsear `summary`.
5. Se houver historico, limitar o buffer de faults para manter simplicidade e previsibilidade.
## Criterios de Aceite
- O debugger reconhece `DebugEvent::Fault`.
- Um `VmTrap` aparece com `trap_code`, `opcode`, `pc` e resumo.
- Um `VmPanic` aparece distinto de `VmTrap`, sem depender de convencao textual.
- Um `VmInit` aparece distinto de fault de runtime.
- O fluxo de logs continua funcionando sem regressao.
## Tests
- Teste de desserializacao/roteamento do cliente cobrindo evento `fault`.
- Teste de estado/UI garantindo que `VmTrap` e `VmPanic` aparecem em superficie dedicada.
- Se houver suite de frontend/cliente, rodar a suite relevante do debugger.
- Se o cliente estiver no mesmo crate do host, incluir ao menos teste unitario do handler de eventos.
## Risco
Baixo a medio. O maior risco e introduzir uma segunda representacao local de fault que volte a colapsar semantica em texto. A implementacao deve reaproveitar o protocolo estruturado ja existente e manter a taxonomia pequena e estavel.