99 lines
2.7 KiB
Markdown
99 lines
2.7 KiB
Markdown
# Agenda - Filesystem Surface and Semantics
|
|
|
|
## Problema
|
|
|
|
O filesystem do runtime ainda esta subdefinido como superficie de API e como contrato semantico.
|
|
|
|
Hoje a discussao de `fs` tende a misturar:
|
|
|
|
- transporte de bytes;
|
|
- shape das operacoes;
|
|
- semantica de caminho e sandbox;
|
|
- classificacao de falhas;
|
|
- persistencia e determinismo.
|
|
|
|
Isso torna facil decidir localmente `fs.read` sem fechar o restante do dominio.
|
|
|
|
## Dor
|
|
|
|
- a API de `fs` pode crescer de forma acidental e incoerente;
|
|
- `list_dir`, `read`, `write`, metadados e mutacoes correm o risco de adotar contratos diferentes entre si;
|
|
- o runtime pode prometer mais semantica do que a plataforma consegue sustentar com portabilidade;
|
|
- testes e certificacao ficam sem alvo preciso.
|
|
|
|
## Alvo da Discussao
|
|
|
|
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 propria do filesystem.
|
|
|
|
## O Que Precisa Ser Definido
|
|
|
|
1. Superficie minima de operacoes.
|
|
Quais operacoes existem no MVP do dominio `fs`.
|
|
Exemplos candidatos:
|
|
- `read`
|
|
- `write`
|
|
- `exists`
|
|
- `stat`
|
|
- `list_dir`
|
|
- `delete`
|
|
- `mkdir`
|
|
|
|
2. Modelo de chamada.
|
|
Definir se `fs` opera:
|
|
- por caminho direto;
|
|
- por IDs/descritores;
|
|
- por combinacao restrita.
|
|
|
|
3. Semantica de caminhos.
|
|
Como paths logicos sao validados, normalizados e limitados.
|
|
|
|
4. Semantica de leitura e escrita.
|
|
Definir:
|
|
- leitura total vs parcial;
|
|
- append vs overwrite;
|
|
- truncation;
|
|
- criacao implicita ou nao.
|
|
|
|
5. Semantica de diretórios.
|
|
`list_dir` precisa de contrato proprio.
|
|
Esta agenda deve decidir se ela existe no MVP e, se existir, qual o shape canonico do resultado.
|
|
|
|
6. Metadados.
|
|
Quais metadados o runtime expoe:
|
|
- tamanho;
|
|
- tipo;
|
|
- timestamps ou nao;
|
|
- flags de portabilidade.
|
|
|
|
7. Persistencia, sandbox e portabilidade.
|
|
O que `fs` promete em todas as plataformas e o que explicitamente nao promete.
|
|
|
|
8. Relacao com fault classification.
|
|
Quais erros `fs` pode produzir e quais classes de falha o dominio precisa usar.
|
|
|
|
## Dependencias
|
|
|
|
- `003-vm-owned-byte-buffer-abi.md` para transporte de bytes;
|
|
- `004-syscall-fault-classification.md` para shape de erro;
|
|
- specs de portabilidade para alinhamento com sandbox logico.
|
|
|
|
## Fora de Escopo
|
|
|
|
- detalhes internos de armazenamento por plataforma;
|
|
- banco de dados persistente;
|
|
- handles host-owned;
|
|
- compatibilidade retroativa.
|
|
|
|
## Critério de Saida Desta Agenda
|
|
|
|
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`;
|
|
- suite minima de testes funcionais de filesystem.
|