78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# 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.
|