# 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

- Esta decisao define o data plane de bytes, nao a taxonomia final de faults por dominio.
- Condicoes operacionais devem retornar `status`.
- Violacoes estruturais de chamada/ABI seguem `16a` e a decisao de fault policy do dominio.
- Para `fs`, a classificacao normativa esta na decisao `007-filesystem-fault-core-policy.md`.

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

- `spec 08-save-memory-and-memcard.md` (historico arquitetural em `learn/historical-game-memcard-slots-surface-and-semantics.md`)
- `014-app-home-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`