# Agenda - App Home Filesystem Surface and Semantics

## Problema

Apps precisam de filesystem util para dados de usuario, cache e configuracao, mas sem acesso ao FS inteiro do host.

Sem um contrato claro de `home` por app, a API tende a crescer com semantica inconsistente entre plataformas.

## Inputs Ja Fechados

1. Todo `app` acessa somente sua `home` logica.
2. Nunca ha acesso direto ao filesystem global do host pela userland.
3. O runtime `fs` interno continua cobrindo tanto `game` quanto `app`.

## Alvo da Discussao

Fechar a superficie e semantica funcional de `fs` para perfil `app`, com sandbox por `app_id` e transporte de bytes via decisao `003`.

## O Que Precisa Ser Definido

1. Surface minima do perfil `app`.
   Operacoes candidatas:
   - `read`;
   - `write`;
   - `exists`;
   - `stat`;
   - `list_dir`;
   - `delete`;
   - `mkdir`;
   - `rename`.

2. Modelo de caminho logico.
   Definir:
   - raiz virtual (`home`);
   - normalizacao de path;
   - bloqueio de path traversal;
   - limites de profundidade/tamanho.

3. Mapeamento host.
   Definir:
   - como `home` vira caminho fisico no host;
   - isolamento entre apps por `app_id`;
   - regras de portabilidade entre hosts.

4. Semantica de leitura/escrita.
   Definir:
   - leitura total vs parcial;
   - overwrite vs append;
   - truncation;
   - criacao implicita;
   - escrita atomica por arquivo (quando aplicavel).

5. Quotas e capacidade.
   Definir:
   - se v1 tem quota por app;
   - comportamento para `storage full`;
   - exposicao de metrica de uso livre/ocupado.

6. Metadados e listagem.
   Definir:
   - campos minimos de `stat`;
   - shape canonico de `list_dir`;
   - timestamps (sim/nao e com qual garantia).

7. Fault/status do dominio.
   Fechar fronteira de:
   - `status` operacional;
   - `Trap` estrutural;
   - `Panic` interno.
   E obrigatorio fechar, por operacao, a matriz final de retorno e fault class.

## Responsabilidade Absorvida da Agenda 003

No perfil `app` (`home` sandbox), esta agenda passa a ser a fonte normativa para:

1. Catalogo de `status` de filesystem para app.
   Minimo esperado:
   - `OK`;
   - `NOT_FOUND`;
   - `PATH_INVALID`;
   - `ACCESS_DENIED`;
   - `NO_SPACE`;
   - `ALREADY_EXISTS`;
   - `UNAVAILABLE`.

2. Matriz por operacao (`read`, `write`, `exists`, `stat`, `list_dir`, `delete`, `mkdir`, `rename`).
   Para cada caso, classificar explicitamente:
   - `status`;
   - `Trap`;
   - `Panic`.

3. Shape de retorno por operacao.
   Definir, no minimo:
   - `status` como primeiro retorno;
   - `bytes_transferred` em `read`/`write` quando aplicavel;
   - payload de metadados/listagem com formato canonico.

4. Regra de escrita parcial.
   `write` nao pode reportar sucesso parcial silencioso.
   Quando a operacao nao puder ser concluida conforme contrato, deve retornar falha de dominio.

## Open Questions de Arquitetura

1. O v1 precisa de quota fixa por app ou apenas limites fisicos do host?
2. `rename` entra no MVP ou pode ficar para fase seguinte?
3. Qual conjunto minimo de metadados garante portabilidade real entre hosts?
4. Qual grau de atomicidade e obrigatorio para escrita de arquivo no v1?

## Dependencias

- `../decisions/003-vm-owned-byte-transfer-protocol.md`
- `../decisions/007-filesystem-fault-core-policy.md`
- `../specs/13-cartridge.md`
- `../specs/12-firmware-pos-and-prometeuhub.md`
- `../specs/16a-syscall-policies.md`

## Fora de Escopo

- slots de memcard para `game` (fica na agenda `013`);
- acesso cross-app;
- sync remoto/cloud;
- DB embutido como contrato de plataforma.

## Criterio de Saida Desta Agenda

Pode virar PR quando houver decisao escrita sobre:

- surface minima de `fs` para `app` em `home`;
- sandbox e isolamento por `app_id`;
- semantica final de path/read/write/listagem;
- matriz completa de fault/status para as operacoes do perfil `app`.