prometeu-runtime/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md

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:

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:

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