# Agenda - Structured Runtime ABI

## Problema

Partes importantes da borda do runtime ainda escapam para strings, texto ad hoc e JSON serializado para transportar dados estruturados.

Exemplos atuais:

- `fs.read` converte bytes para `String`;
- `fs.list_dir` concatena nomes com separador textual;
- `bank.info` e `bank.slot_info` devolvem JSON em um slot string.

## Dor

- O ABI deixa de ser estrutural e volta a depender de parsing textual no guest.
- Binários e bytes arbitrários ficam mutilados por `UTF-8 lossy`.
- Contratos ficam frágeis: delimitadores, shape do JSON e nomes de campo viram parte implícita da API.
- Isso contradiz a linha central do projeto: sem mágica, sem heurística, sem ambiguidade.
- O custo futuro aumenta porque qualquer linguagem cliente passa a embutir parser de conveniência para tapar buraco de ABI.

## Alvo da Discussao

Definir um modelo canônico para dados estruturados e/ou binários na fronteira guest <-> runtime.

Essa agenda precisa responder se o runtime vai operar com:

- slots primitivos fixos;
- objetos heapados do VM;
- handles opacos para buffers/iteradores;
- uma combinação dessas estratégias por domínio.

## O Que Precisa Ser Definido

1. Modelo de retorno estruturado.
   Como representar listas, metadados de banco, resultados de leitura e payload binário sem texto improvisado.

2. Política para bytes.
   `fs.read` deve retornar buffer/array/handle, nao string textual.

3. Política para structs.
   `bank.info`, `button`, `slot info` e similares devem ter shape canônico:
   - flatten em slots;
   - objeto heapado;
   - view estruturada com metadata fixa.

4. Política para listas.
   `fs.list_dir` nao deve depender de delimitador textual; precisa de shape navegável.

5. Impacto no verifier e no HostReturn.
   Se houver objetos heapados retornados por syscalls, a ABI e o runtime precisam suportar isso sem atalhos temporários.

6. Estratégia de migração.
   Como substituir contratos atuais sem consolidar compatibilidade acidental ruim.

## O Que Necessita Para Resolver

- decisão arquitetural para transporte de dados estruturados;
- catálogo das syscalls afetadas;
- atualização do ABI canônico;
- estratégia de teste para garantir integridade de bytes e shape estável;
- posição explícita sobre backward compatibility.

## Fora de Escopo

- serialização genérica estilo JSON para tooling externo;
- reflection completa no guest;
- coleção completa de tipos ricos do SDK.

## Critério de Saida Desta Agenda

Pode virar PR quando houver decisão escrita sobre:

- shape canônico por domínio afetado;
- representação de bytes;
- impacto no heap/GC/HostReturn;
- política de migração;
- suite mínima de testes de ABI.