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