158 lines
4.7 KiB
Markdown
158 lines
4.7 KiB
Markdown
---
|
|
id: AGD-0006
|
|
ticket: app-home-filesystem-surface-and-semantics
|
|
title: Agenda - App Home Filesystem Surface and Semantics
|
|
status: open
|
|
created: 2026-03-27
|
|
resolved:
|
|
decision:
|
|
tags: []
|
|
---
|
|
|
|
# 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`.
|