agenda discussion and decisions

This commit is contained in:
2026-03-24 13:40:48 +00:00
parent 60e0875147
commit d588502b57
5 changed files with 195 additions and 113 deletions
@@ -1,97 +0,0 @@
# 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.
@@ -25,7 +25,7 @@ Isso torna facil decidir localmente `fs.read` sem fechar o restante do dominio.
Definir a superficie canonica do dominio `fs` no runtime, separando claramente:
- o que e responsabilidade da agenda `003-vm-owned-byte-buffer-abi`;
- o que e responsabilidade da decisao `003-vm-owned-byte-transfer-protocol`;
- o que e responsabilidade propria do filesystem.
## O Que Precisa Ser Definido
@@ -76,7 +76,7 @@ Definir a superficie canonica do dominio `fs` no runtime, separando claramente:
## Dependencias
- `003-vm-owned-byte-buffer-abi.md` para transporte de bytes;
- `../decisions/003-vm-owned-byte-transfer-protocol.md` para transporte de bytes;
- `004-syscall-fault-classification.md` para shape de erro;
- specs de portabilidade para alinhamento com sandbox logico.
@@ -94,5 +94,5 @@ Pode virar PR quando houver decisao escrita sobre:
- conjunto minimo de operacoes de `fs`;
- shape de chamada de cada operacao;
- semantica de path, diretorio e persistencia;
- dependencia explicita do ABI de bytes da `003`;
- dependencia explicita da decisao `003` de transporte de bytes;
- suite minima de testes funcionais de filesystem.
+11 -13
View File
@@ -12,7 +12,6 @@ As agendas atuais são:
- `001-system-run-cart.md`
- `002-packed-cartridge-loader-pmc.md`
- `003-vm-owned-byte-buffer-abi.md`
- `004-syscall-fault-classification.md`
- `005-runtime-edge-test-plan.md`
- `009-filesystem-surface-and-semantics.md`
@@ -26,23 +25,22 @@ Ordem sugerida para discussão e futura execução:
1. `007-single-canonical-architecture.md`
2. `008-hardware-specs-reorganization.md`
3. `006-break-monolith-runtime.md`
4. `003-vm-owned-byte-buffer-abi.md`
5. `004-syscall-fault-classification.md`
6. `009-filesystem-surface-and-semantics.md`
7. `010-input-intrinsics-surface.md`
8. `011-input-frame-semantics-and-portability.md`
9. `005-runtime-edge-test-plan.md`
10. `001-system-run-cart.md`
11. `002-packed-cartridge-loader-pmc.md`
4. `004-syscall-fault-classification.md`
5. `009-filesystem-surface-and-semantics.md`
6. `010-input-intrinsics-surface.md`
7. `011-input-frame-semantics-and-portability.md`
8. `005-runtime-edge-test-plan.md`
9. `001-system-run-cart.md`
10. `002-packed-cartridge-loader-pmc.md`
Justificativa curta:
- `007` vem primeiro porque elimina ambiguidade sobre qual documento manda.
- `008` vem em seguida porque reorganiza o terreno documental onde specs e arquitetura se apoiam.
- `006` entra depois porque refactor estrutural grande sem documentação estável tende a cristalizar decisões erradas.
- `003` fecha o contrato base para trafego de bytes VM-owned.
- a decisao `003` ja fechou o contrato base para trafego de bytes VM-owned e agora deve ser consumida, nao rediscutida aqui.
- `004` fecha a taxonomia de falhas que `fs` e outras bordas vao reutilizar.
- `009` usa `003` e `004` para fechar o dominio de filesystem sem texto improvisado.
- `009` usa a decisao `003` e a agenda `004` para fechar o dominio de filesystem sem texto improvisado.
- `010` e `011` isolam o dominio maior de input fora de syscall, tratando `pad` e `touch` como superfícies centrais, `button` como parte de `pad`, e explicitando a migracao da leitura de input para intrinsics.
- `005` fecha a barra de qualidade antes das implementações mais arriscadas.
- `001` e `002` dependem mais fortemente de contrato de sistema, ABI e documentação estáveis.
@@ -51,10 +49,10 @@ Dependências principais:
- `008` depende de `007`
- `006` depende de `007`
- `009` depende de `003` e `004`
- `009` depende da decisao `003` e da agenda `004`
- `010` depende de `007`
- `011` depende de `010`
- `001` depende de `007`, `003`, `004`, `005` e deve alinhar com `009` quando usar `fs`
- `001` depende de `007`, da decisao `003`, de `004`, de `005` e deve alinhar com `009` quando usar `fs`
- `002` depende de `007` e deve ser alinhada com a reorganização documental de `008`
Regra de uso: