agenda discussion about memcard and app fs

docs/runtime/agendas/002-filesystem-surface-and-semantics.md

@@ -1,98 +0,0 @@
-# Agenda - Filesystem Surface and Semantics
-
-## Problema
-
-O filesystem do runtime ainda esta subdefinido como superficie de API e como contrato semantico.
-
-Hoje a discussao de `fs` tende a misturar:
-
-- transporte de bytes;
-- shape das operacoes;
-- semantica de caminho e sandbox;
-- classificacao de falhas;
-- persistencia e determinismo.
-
-Isso torna facil decidir localmente `fs.read` sem fechar o restante do dominio.
-
-## Dor
-
-- a API de `fs` pode crescer de forma acidental e incoerente;
-- `list_dir`, `read`, `write`, metadados e mutacoes correm o risco de adotar contratos diferentes entre si;
-- o runtime pode prometer mais semantica do que a plataforma consegue sustentar com portabilidade;
-- testes e certificacao ficam sem alvo preciso.
-
-## Alvo da Discussao
-
-Definir a superficie canonica do dominio `fs` no runtime, separando claramente:
-
-- o que e responsabilidade da decisao `003-vm-owned-byte-transfer-protocol`;
-- o que e responsabilidade propria do filesystem.
-
-## O Que Precisa Ser Definido
-
-1. Superficie minima de operacoes.
-   Quais operacoes existem no MVP do dominio `fs`.
-   Exemplos candidatos:
-   - `read`
-   - `write`
-   - `exists`
-   - `stat`
-   - `list_dir`
-   - `delete`
-   - `mkdir`
-
-2. Modelo de chamada.
-   Definir se `fs` opera:
-   - por caminho direto;
-   - por IDs/descritores;
-   - por combinacao restrita.
-
-3. Semantica de caminhos.
-   Como paths logicos sao validados, normalizados e limitados.
-
-4. Semantica de leitura e escrita.
-   Definir:
-   - leitura total vs parcial;
-   - append vs overwrite;
-   - truncation;
-   - criacao implicita ou nao.
-
-5. Semantica de diretórios.
-   `list_dir` precisa de contrato proprio.
-   Esta agenda deve decidir se ela existe no MVP e, se existir, qual o shape canonico do resultado.
-
-6. Metadados.
-   Quais metadados o runtime expoe:
-   - tamanho;
-   - tipo;
-   - timestamps ou nao;
-   - flags de portabilidade.
-
-7. Persistencia, sandbox e portabilidade.
-   O que `fs` promete em todas as plataformas e o que explicitamente nao promete.
-
-8. Relacao com fault classification.
-   Quais erros `fs` pode produzir e quais classes de falha o dominio precisa usar.
-
-## Dependencias
-
-- `../decisions/003-vm-owned-byte-transfer-protocol.md` para transporte de bytes;
-- `../specs/16a-syscall-policies.md` para shape de erro/fault;
-- specs de portabilidade para alinhamento com sandbox logico.
-
-## Fora de Escopo
-
-- detalhes internos de armazenamento por plataforma;
-- banco de dados persistente;
-- handles host-owned;
-- compatibilidade retroativa.
-
-## Critério de Saida Desta Agenda
-
-Pode virar PR quando houver decisao escrita sobre:
-
-- conjunto minimo de operacoes de `fs`;
-- shape de chamada de cada operacao;
-- semantica de path, diretorio e persistencia;
-- dependencia explicita da decisao `003` de transporte de bytes;
-- suite minima de testes funcionais de filesystem.

docs/runtime/agendas/003-filesystem-fault-semantics.md

@@ -5,13 +5,14 @@
 O dominio `fs` certamente precisara de politica de fault propria, mas ainda depende de duas discussoes anteriores:
 
 - a decisao `003` sobre transporte de bytes;
-- a agenda `002` sobre superficie e semantica funcional de filesystem.
+- a agenda `013` sobre superficie/semantica de memcard para `game`;
+- a agenda `014` sobre superficie/semantica de `home` para `app`.
 
 Discutir fault semantics antes disso tende a cristalizar classificacao em cima de uma API que ainda pode mudar.
 
 ## Alvo da Discussao
 
-Fechar a politica de fault de `fs` somente depois da agenda `002`.
+Fechar a politica de fault de `fs` somente depois das agendas `013` e `014`.
 
 ## O Que Precisa Ser Definido
 
@@ -32,11 +33,12 @@ Fechar a politica de fault de `fs` somente depois da agenda `002`.
 
 - `../decisions/003-vm-owned-byte-transfer-protocol.md`
 - `../specs/16a-syscall-policies.md`
-- `002-filesystem-surface-and-semantics.md`
+- `013-game-memcard-slots-surface-and-semantics.md`
+- `014-app-home-filesystem-surface-and-semantics.md`
 
 ## Regra de Sequenciamento
 
-Esta agenda nao deve ser discutida antes da `002`.
+Esta agenda nao deve ser discutida antes da `013` e da `014`.
 
 ## Critério de Saida Desta Agenda
 

docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md

@@ -0,0 +1,94 @@
+# Agenda - Game Memcard Slots Surface and Semantics
+
+## Problema
+
+Jogos precisam de persistencia previsivel e portavel para save/config/blob, sem abrir acesso amplo ao filesystem.
+
+Ao mesmo tempo, copia de saves deve acontecer fora do jogo (Hub/OS), com identificacao digital e visual por slot.
+
+## Inputs Ja Fechados
+
+1. Perfil `game` usa 32 slots por jogo.
+2. Cada slot oferece payload de ate 32KB.
+3. Jogo acessa somente os proprios slots.
+4. `commit` e atomico por slot.
+5. Copia/export/import de slots ocorre fora do jogo.
+
+## Alvo da Discussao
+
+Fechar o contrato de slots de memcard para jogos, usando a decisao `003` como data plane de bytes.
+
+## O Que Precisa Ser Definido
+
+1. Surface minima para jogos.
+   Operacoes candidatas:
+   - `slot_count`;
+   - `slot_stat`;
+   - `slot_read`;
+   - `slot_write`;
+   - `slot_commit`;
+   - `slot_clear`.
+
+2. Envelope de identidade do slot.
+   Definir metadados runtime-owned:
+   - `app_id` dono;
+   - `slot_index`;
+   - `save_uuid`/generation;
+   - tamanho de payload;
+   - checksum/integridade;
+   - estado (`empty`, `used`, `corrupt`).
+
+3. Identidade visual do slot.
+   Definir metadados para Hub/OS:
+   - label/subtitulo;
+   - timestamp/logical counter;
+   - icone/preview (incluindo caminho para suporte futuro de icone animado estilo PSX).
+
+4. Politica de copia fora do jogo.
+   Definir:
+   - formato de export/import;
+   - validacoes de ownership;
+   - comportamento para conflito/duplicata/corrupcao.
+
+5. Integracao com storage host.
+   Definir:
+   - como slots viram arquivos fisicos no storage host;
+   - regra de namespace por jogo (`app_id`);
+   - garantias de atomicidade por slot.
+
+6. Fault/status do dominio.
+   Fechar fronteira de:
+   - `status` operacional;
+   - `Trap` estrutural;
+   - `Panic` interno.
+
+## Open Questions de Arquitetura
+
+1. Qual fonte canonica de `app_id` unico no ecossistema?
+2. Qual formato minimo do bloco visual do slot no v1?
+3. Qual politica de integridade v1 (CRC somente vs assinatura adicional)?
+4. Como o Hub deve tratar slots corrompidos sem quebrar UX?
+
+## Dependencias
+
+- `../decisions/003-vm-owned-byte-transfer-protocol.md`
+- `../specs/08-save-memory-and-memcard.md`
+- `../specs/13-cartridge.md`
+- `../specs/12-firmware-pos-and-prometeuhub.md`
+- `../specs/16a-syscall-policies.md`
+
+## Fora de Escopo
+
+- acesso amplo de jogos ao FS por path;
+- banco de dados ou sync remoto;
+- APIs de app sandbox (fica na agenda `014`).
+
+## Criterio de Saida Desta Agenda
+
+Pode virar PR quando houver decisao escrita sobre:
+
+- contrato de slots (`32 x 32KB`) e ownership por jogo;
+- envelope de identidade digital/visual do slot;
+- politica de copia fora do jogo;
+- surface minima + fault/status para operacoes de slot.
+

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

@@ -0,0 +1,99 @@
+# 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`.

docs/runtime/agendas/README.md

@@ -10,7 +10,6 @@ Objetivo:
 
 As agendas atuais são:
 
-- `002-filesystem-surface-and-semantics.md`
 - `003-filesystem-fault-semantics.md`
 - `004-gfx-fault-semantics-and-command-contract.md`
 - `005-audio-fault-semantics-and-surface.md`
@@ -20,27 +19,32 @@ As agendas atuais são:
 - `009-system-run-cart.md`
 - `010-system-fault-semantics-and-control-surface.md`
 - `012-vm-owned-random-service.md`
+- `013-game-memcard-slots-surface-and-semantics.md`
+- `014-app-home-filesystem-surface-and-semantics.md`
 
 ## Sequenciamento Recomendado
 
 Ordem sugerida para discussão e futura execução:
 
 1. `012-vm-owned-random-service.md`
-2. `002-filesystem-surface-and-semantics.md`
+2. `013-game-memcard-slots-surface-and-semantics.md`
-3. `003-filesystem-fault-semantics.md`
+3. `014-app-home-filesystem-surface-and-semantics.md`
-4. `004-gfx-fault-semantics-and-command-contract.md`
+4. `003-filesystem-fault-semantics.md`
-5. `005-audio-fault-semantics-and-surface.md`
+5. `004-gfx-fault-semantics-and-command-contract.md`
-6. `006-asset-fault-semantics-and-surface.md`
+6. `005-audio-fault-semantics-and-surface.md`
-7. `007-runtime-edge-test-plan.md`
+7. `006-asset-fault-semantics-and-surface.md`
-8. `008-packed-cartridge-loader-pmc.md`
+8. `007-runtime-edge-test-plan.md`
-9. `009-system-run-cart.md`
+9. `008-packed-cartridge-loader-pmc.md`
-10. `010-system-fault-semantics-and-control-surface.md`
+10. `009-system-run-cart.md`
+11. `010-system-fault-semantics-and-control-surface.md`
 
 Justificativa curta:
 
 - `011` foi fechada pela decisao `006`.
 - `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
-- `002` e `003` ficam na sequencia para fechar `fs` com superficie e fault semantics consistentes.
+- `013` fecha o contrato de memcard para jogos (`32 x 32KB`, ownership, identidade e copia fora do jogo).
+- `014` fecha o contrato de `home` para apps sem abrir FS global.
+- `003` vem depois de `013` e `014` para consolidar fault semantics de `fs` em ambos os perfis.
 - `004`, `005` e `006` consolidam fault semantics por dominio com base em `16a`.
 - `007` vem depois para transformar as decisoes em cobertura de regressao na borda do runtime.
 - `008` e importante, mas nao bloqueia bytecode/backend agora.
@@ -49,14 +53,15 @@ Justificativa curta:
 Dependências principais:
 
 - `012` depende da decisao `006` e de `16`/`16a`
-- `002` depende da decisao `003` e de `16a`
+- `013` depende da decisao `003`, de `16a`, de `08` (memcard), de `12` (Hub/OS) e de `13` (`app_mode`)
-- `003` depende da decisao `003`, de `16a` e da `002`
+- `014` depende da decisao `003`, de `16a`, de `12` (Hub/OS) e de `13` (`app_mode`)
+- `003` depende da decisao `003`, de `16a`, da `013` e da `014`
 - `004` depende de `16a`
 - `005` depende de `16a`
 - `006` depende de `16a`
 - `007` depende da estabilizacao minima das agendas de superficie/fault por dominio
 - `008` depende de contrato fechado de `13-cartridge.md` + comportamento equivalente ao loader de diretorio
-- `009` depende da decisao `003`, de `16a` e de `06`, e deve alinhar com `002` quando usar `fs`
+- `009` depende da decisao `003`, de `16a` e de `06`, e deve alinhar com `013`/`014` quando usar `fs`
 - `010` depende de `16a` e da `009`
 
 Regra de uso:

docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md

@@ -152,7 +152,8 @@ Para suportar este protocolo, a VM precisa expor API canonica para:
 
 As seguintes agendas devem consumir esta decisao:
 
-- `002-filesystem-surface-and-semantics.md`
+- `013-game-memcard-slots-surface-and-semantics.md`
+- `014-app-home-filesystem-surface-and-semantics.md`
 - discussoes futuras de data bank
 
 As seguintes specs precisarao ser atualizadas: