prometeu-runtime/docs/agendas/003-structured-runtime-abi.md

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.