# 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.