agenda discussion and decisions
This commit is contained in:
@@ -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.
|
||||
|
||||
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user