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

## 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`
- `../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;
- fault/status para as operacoes do perfil `app`.