prometeu-runtime/discussion/workflow/agendas/AGD-0006-app-home-filesystem-surface-and-semantics.md

id	ticket	title	status	created	resolved	decision	tags
AGD-0006	app-home-filesystem-surface-and-semantics	Agenda - App Home Filesystem Surface and Semantics	open	2026-03-27

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.
4. Existe uma async IO lane compartilhavel por assets, memcard e FS. Esta agenda deve decidir a API publica de FS considerando essa lane, mas a existencia da lane ja esta fechada por DEC-0034.

Fronteira com a Async IO Lane

DEC-0034 fecha a existencia de uma lane serial para trabalho async de IO. FS pode consumir essa lane internamente para escrita, configuracao, leitura ou listagem, conforme prioridade operacional definida pelo runtime.

Esta agenda continua dona da decisao sobre API publica de FS para app home. Portanto, a existencia da lane nao implica criar agora request handles, polling publico ou novas syscalls de FS. Esses shapes permanecem em aberto aqui.

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?
5. Quais operacoes de FS devem consumir a async IO lane e quais permanecem sincrono-aparentes para a userland?

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 (fechado na spec 08);
• 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.