From d588502b573aa222d4ac5fd33fd92f9e234c2ea8 Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 4 Mar 2026 16:53:11 +0000 Subject: [PATCH] agenda discussion and decisions --- .../agendas/003-vm-owned-byte-buffer-abi.md | 97 ----------- .../009-filesystem-surface-and-semantics.md | 6 +- docs/runtime/agendas/README.md | 24 ++- .../003-vm-owned-byte-transfer-protocol.md | 162 ++++++++++++++++++ docs/runtime/decisions/README.md | 19 ++ 5 files changed, 195 insertions(+), 113 deletions(-) delete mode 100644 docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md create mode 100644 docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md create mode 100644 docs/runtime/decisions/README.md diff --git a/docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md b/docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md deleted file mode 100644 index f91b3578..00000000 --- a/docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md +++ /dev/null @@ -1,97 +0,0 @@ -# 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/009-filesystem-surface-and-semantics.md b/docs/runtime/agendas/009-filesystem-surface-and-semantics.md index 40e4a78d..c3f16b31 100644 --- a/docs/runtime/agendas/009-filesystem-surface-and-semantics.md +++ b/docs/runtime/agendas/009-filesystem-surface-and-semantics.md @@ -25,7 +25,7 @@ Isso torna facil decidir localmente `fs.read` sem fechar o restante do dominio. 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 da decisao `003-vm-owned-byte-transfer-protocol`; - o que e responsabilidade propria do filesystem. ## O Que Precisa Ser Definido @@ -76,7 +76,7 @@ Definir a superficie canonica do dominio `fs` no runtime, separando claramente: ## Dependencias -- `003-vm-owned-byte-buffer-abi.md` para transporte de bytes; +- `../decisions/003-vm-owned-byte-transfer-protocol.md` para transporte de bytes; - `004-syscall-fault-classification.md` para shape de erro; - specs de portabilidade para alinhamento com sandbox logico. @@ -94,5 +94,5 @@ 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`; +- dependencia explicita da decisao `003` de transporte de bytes; - suite minima de testes funcionais de filesystem. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index 8a10df79..c9a17767 100644 --- a/docs/runtime/agendas/README.md +++ b/docs/runtime/agendas/README.md @@ -12,7 +12,6 @@ As agendas atuais são: - `001-system-run-cart.md` - `002-packed-cartridge-loader-pmc.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` @@ -26,23 +25,22 @@ 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-vm-owned-byte-buffer-abi.md` -5. `004-syscall-fault-classification.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` +4. `004-syscall-fault-classification.md` +5. `009-filesystem-surface-and-semantics.md` +6. `010-input-intrinsics-surface.md` +7. `011-input-frame-semantics-and-portability.md` +8. `005-runtime-edge-test-plan.md` +9. `001-system-run-cart.md` +10. `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` fecha o contrato base para trafego de bytes VM-owned. +- a decisao `003` ja fechou o contrato base para trafego de bytes VM-owned e agora deve ser consumida, nao rediscutida aqui. - `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. +- `009` usa a decisao `003` e a agenda `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. @@ -51,10 +49,10 @@ Dependências principais: - `008` depende de `007` - `006` depende de `007` -- `009` depende de `003` e `004` +- `009` depende da decisao `003` e da agenda `004` - `010` depende de `007` - `011` depende de `010` -- `001` depende de `007`, `003`, `004`, `005` e deve alinhar com `009` quando usar `fs` +- `001` depende de `007`, da decisao `003`, de `004`, de `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/decisions/003-vm-owned-byte-transfer-protocol.md b/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md new file mode 100644 index 00000000..34fb73cb --- /dev/null +++ b/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md @@ -0,0 +1,162 @@ +# Decision Record - VM-Owned Byte Transfer Protocol + +## Status + +Accepted + +## Contexto + +O runtime precisa de um protocolo canonico para trafegar bytes entre host e userland sem: + +- converter payload binario em `String`; +- devolver handles host-owned; +- inventar formatos ad hoc por dominio. + +O estado atual relevante e: + +- a heap ja possui `ObjectKind::Bytes`; +- o runtime ja consegue armazenar payload binario bruto na heap; +- `Value` ainda nao possui `Byte`; +- a spec de valores ainda nao reconhece `byte` como valor primitivo; +- `HostReturn` ainda modela apenas empilhar valores na stack; +- `fs` e o futuro data bank precisarao trafegar bytes pela borda host <-> guest. + +O projeto tambem ja fixou que: + +- syscalls usam stack; +- o host nao devolve handles opacos; +- o host nao devolve memoria host-owned; +- banks de hardware trafegam IDs, nao bytes; +- nao ha backward compatibility. + +## Decisao + +### 1. Tipo base + +- O runtime passa a exigir `Value::Byte` como valor primitivo real. +- A spec de valores deve ser atualizada para incluir `byte`. + +### 2. Buffer canonico + +- O buffer canonico de bytes da VM e `HeapRef(Byte)`. +- `HeapRef(Byte)` significa um `HeapRef` cujo objeto alvo e `ObjectKind::Bytes`. +- Nao sera introduzido mecanismo paralelo para buffer binario. + +### 3. Nomes canonicos + +- `src` = origem dos bytes. +- `dst` = destino dos bytes. +- `src_ref`/`dst_ref` = handle VM-owned para buffer de bytes. +- `src_offset`/`dst_offset` = offset no buffer da VM. +- `host_handle` = identificador opaco do lado host. +- `host_offset` = offset do lado host. +- `max_bytes` = quantidade maxima pedida para a operacao. +- `bytes_transferred` = quantidade efetivamente transferida. + +### 4. Domain ops iniciais + +Os dois domain ops iniciais deste protocolo sao: + +- `read`: host -> VM +- `write`: VM -> host + +### 5. Assinatura canonica de `read` + +`read` deve seguir este formato: + +```text +read(host_handle, host_offset, dst_ref, dst_offset, max_bytes) -> (status, bytes_transferred, eof) +``` + +Regras: + +- `status` e `bytes_transferred` sao inteiros; +- `eof` e booleano; +- `dst_ref` deve apontar para `HeapRef(Byte)`; +- `read` parcial pode ser sucesso; +- `eof` representa fim/exaustao observada no lado host. + +### 6. Assinatura canonica de `write` + +`write` deve seguir este formato: + +```text +write(host_handle, host_offset, src_ref, src_offset, max_bytes) -> (status, bytes_transferred) +``` + +Regras: + +- `status` e `bytes_transferred` sao inteiros; +- `src_ref` deve apontar para `HeapRef(Byte)`; +- `write` parcial e falha. + +### 7. Janela explicita de transferencia + +Toda operacao atua sobre uma janela explicita da heap da VM: + +- `read` escreve em `dst_ref[dst_offset .. dst_offset + max_bytes)`; +- `write` le de `src_ref[src_offset .. src_offset + max_bytes)`. + +### 8. Politica de falha + +- O protocolo deve preferir `status` ao maximo. +- Falhas operacionais e erros observaveis de contrato devem retornar `status`, nao `Trap`. +- `Trap` fica reservado para bug/inconsistencia interna do runtime. + +Isso inclui, por decisao arquitetural, que erros como: + +- `host_handle` invalido; +- `HeapRef(Byte)` invalido; +- kind incorreto; +- offset invalido; +- janela invalida; +- indisponibilidade operacional do host; + +devem ser modelados como `status`, nao como `Trap`, salvo se revelarem inconsistencia interna do runtime. + +### 9. API minima necessaria na VM + +Para suportar este protocolo, a VM precisa expor API canonica para: + +- alocar buffer de bytes VM-owned; +- validar se um `HeapRef` aponta para `ObjectKind::Bytes`; +- expor comprimento/capacidade relevantes; +- escrever bytes em faixa valida; +- ler bytes em faixa valida. + +## Consequencias + +### Positivas + +- `fs` e data bank passam a compartilhar o mesmo protocolo estrutural. +- A borda host <-> guest deixa de depender de texto para payload binario. +- O host nao precisa alocar memoria propria para devolver bytes. +- O guest passa a controlar explicitamente buffer, janela e interpretacao do payload. + +### Custos + +- `Value` e a spec de valores precisam mudar. +- A heap precisa de API publica mais util para `Bytes`. +- `HostReturn` e a camada host-backed precisam acomodar o protocolo sem atalhos. +- Dominios como `fs` ainda precisam decidir suas semanticas funcionais sobre este protocolo. + +## Fora de Escopo + +- API funcional completa de `fs`; +- API funcional do data bank; +- listas e structs retornadas pelo host; +- transporte de banks graficos/sonoros para a VM; +- input/intrinsics. + +## Follow-up Obrigatorio + +As seguintes agendas devem consumir esta decisao: + +- `009-filesystem-surface-and-semantics.md` +- discussoes futuras de data bank + +As seguintes specs precisarao ser atualizadas: + +- `02a-vm-values-and-calling-convention.md` +- `03-memory-stack-heap-and-allocation.md` +- `16-host-abi-and-syscalls.md` diff --git a/docs/runtime/decisions/README.md b/docs/runtime/decisions/README.md new file mode 100644 index 00000000..0daf84bf --- /dev/null +++ b/docs/runtime/decisions/README.md @@ -0,0 +1,19 @@ +# Runtime Decisions + +Este diretório reúne decision records do runtime. + +Objetivo: + +- registrar decisoes arquiteturais ja tomadas; +- servir como referencia normativa para agendas derivadas; +- evitar reabrir discussoes que ja foram fechadas. + +Regra de uso: + +- agendas existem para discutir e fechar ambiguidade; +- decision records existem para registrar o que foi decidido; +- quando uma agenda for resolvida, ela deve sair de `agendas/` e virar decision record aqui. + +Decisoes atuais: + +- `003-vm-owned-byte-transfer-protocol.md`