agenda discussion about memcard and app fs
This commit is contained in:
parent
833798e143
commit
1394f8e241
SSH Key Fingerprint:
SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
@ -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.
|
||||
@ -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
|
||||
|
||||
|
||||
@ -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.
|
||||
|
||||
@ -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`.
|
||||
@ -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:
|
||||
|
||||
@ -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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user