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

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.