prometeu-runtime/docs/runtime/agendas/009-filesystem-surface-and-semantics.md

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 decisao 003-vm-owned-byte-transfer-protocol;
• 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

• ../decisions/003-vm-owned-byte-transfer-protocol.md para transporte de bytes;
• ../decisions/004-host-fault-taxonomy.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 da decisao 003 de transporte de bytes;
• suite minima de testes funcionais de filesystem.