agenda discussion and decisions

docs/runtime/agendas/003-vm-owned-byte-buffer-abi.md

@@ -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.

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.

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:

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`

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`