diff --git a/docs/runtime/agendas/002-filesystem-surface-and-semantics.md b/docs/runtime/agendas/002-filesystem-surface-and-semantics.md deleted file mode 100644 index 42a33a5e..00000000 --- a/docs/runtime/agendas/002-filesystem-surface-and-semantics.md +++ /dev/null @@ -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. diff --git a/docs/runtime/agendas/003-filesystem-fault-semantics.md b/docs/runtime/agendas/003-filesystem-fault-semantics.md index 711be0b6..24b9b9a3 100644 --- a/docs/runtime/agendas/003-filesystem-fault-semantics.md +++ b/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 diff --git a/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md b/docs/runtime/agendas/013-game-memcard-slots-surface-and-semantics.md new file mode 100644 index 00000000..9c47e7c9 --- /dev/null +++ b/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. + diff --git a/docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md b/docs/runtime/agendas/014-app-home-filesystem-surface-and-semantics.md new file mode 100644 index 00000000..051d551e --- /dev/null +++ b/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`. diff --git a/docs/runtime/agendas/README.md b/docs/runtime/agendas/README.md index e8b9998a..58ad86d4 100644 --- a/docs/runtime/agendas/README.md +++ b/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` -3. `003-filesystem-fault-semantics.md` -4. `004-gfx-fault-semantics-and-command-contract.md` -5. `005-audio-fault-semantics-and-surface.md` -6. `006-asset-fault-semantics-and-surface.md` -7. `007-runtime-edge-test-plan.md` -8. `008-packed-cartridge-loader-pmc.md` -9. `009-system-run-cart.md` -10. `010-system-fault-semantics-and-control-surface.md` +2. `013-game-memcard-slots-surface-and-semantics.md` +3. `014-app-home-filesystem-surface-and-semantics.md` +4. `003-filesystem-fault-semantics.md` +5. `004-gfx-fault-semantics-and-command-contract.md` +6. `005-audio-fault-semantics-and-surface.md` +7. `006-asset-fault-semantics-and-surface.md` +8. `007-runtime-edge-test-plan.md` +9. `008-packed-cartridge-loader-pmc.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` -- `003` depende da decisao `003`, de `16a` e da `002` +- `013` depende da decisao `003`, de `16a`, de `08` (memcard), de `12` (Hub/OS) e de `13` (`app_mode`) +- `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: diff --git a/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md b/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md index f067e745..a9d105e9 100644 --- a/docs/runtime/decisions/003-vm-owned-byte-transfer-protocol.md +++ b/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: