diff --git a/devtools/typescript-sdk/package.json b/devtools/typescript-sdk/package.json deleted file mode 100644 index 930f81cf..00000000 --- a/devtools/typescript-sdk/package.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "name": "@prometeu/sdk", - "version": "0.1.0", - "type": "module", - "main": "src/index.ts", - "types": "types/index.d.ts" -} diff --git a/devtools/typescript-sdk/tooling/eslint/base.js b/devtools/typescript-sdk/tooling/eslint/base.js deleted file mode 100644 index f6fe2439..00000000 --- a/devtools/typescript-sdk/tooling/eslint/base.js +++ /dev/null @@ -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.", - }, - ], - }, - }, - ]; -} \ No newline at end of file diff --git a/devtools/typescript-sdk/tsconfig.json b/devtools/typescript-sdk/tsconfig.json deleted file mode 100644 index ae3ed354..00000000 --- a/devtools/typescript-sdk/tsconfig.json +++ /dev/null @@ -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 - } -} \ No newline at end of file diff --git a/devtools/typescript-sdk/types/index.d.ts b/devtools/typescript-sdk/types/index.d.ts deleted file mode 100644 index d2dae14e..00000000 --- a/devtools/typescript-sdk/types/index.d.ts +++ /dev/null @@ -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; -} - diff --git a/docs/runtime/agendas/003-structured-runtime-abi.md b/docs/runtime/agendas/003-structured-runtime-abi.md deleted file mode 100644 index 69021e97..00000000 --- a/docs/runtime/agendas/003-structured-runtime-abi.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md b/docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md new file mode 100644 index 00000000..f91b3578 --- /dev/null +++ b/docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md @@ -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. diff --git a/docs/runtime/agendas/004-syscall-fault-classification.md b/docs/runtime/agendas/004-syscall-fault-classification.md index f9847ebe..611c33ae 100644 --- a/docs/runtime/agendas/004-syscall-fault-classification.md +++ b/docs/runtime/agendas/004-syscall-fault-classification.md @@ -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. diff --git a/docs/runtime/agendas/009-filesystem-surface-and-semantics.md b/docs/runtime/agendas/009-filesystem-surface-and-semantics.md new file mode 100644 index 00000000..40e4a78d --- /dev/null +++ b/docs/runtime/agendas/009-filesystem-surface-and-semantics.md @@ -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. diff --git a/docs/runtime/agendas/010-input-intrinsics-surface.md b/docs/runtime/agendas/010-input-intrinsics-surface.md new file mode 100644 index 00000000..9d74016d --- /dev/null +++ b/docs/runtime/agendas/010-input-intrinsics-surface.md @@ -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. diff --git a/docs/runtime/agendas/011-input-frame-semantics-and-portability.md b/docs/runtime/agendas/011-input-frame-semantics-and-portability.md new file mode 100644 index 00000000..ab13d0ff --- /dev/null +++ b/docs/runtime/agendas/011-input-frame-semantics-and-portability.md @@ -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. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 4cd0cbfe..8a10df79 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -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: diff --git a/docs/runtime/pull-requests/PR-013-[DEBUGGER]-consume-structured-fault-events.md b/docs/runtime/pull-requests/PR-013-[DEBUGGER]-consume-structured-fault-events.md deleted file mode 100644 index 897d00f7..00000000 --- a/docs/runtime/pull-requests/PR-013-[DEBUGGER]-consume-structured-fault-events.md +++ /dev/null @@ -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.