prometeu-runtime/docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md

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.