agents and learn refactor
This commit is contained in:
@@ -64,7 +64,7 @@ Justificativa curta:
|
||||
|
||||
- `011` foi fechada pela decisao `006`.
|
||||
- `012` e o primeiro consumidor da base stateful VM-owned fechada em `006`.
|
||||
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/011`).
|
||||
- `013` foi fechada e absorvida por `spec 08` (historico em `learn/historical-game-memcard-slots-surface-and-semantics.md`).
|
||||
- `014` fecha o contrato de `home` para apps sem abrir FS global.
|
||||
- a decisao `007` fixa o nucleo de fault policy de `fs`; os detalhes ficam distribuidos entre `spec 08` (`game`) e agenda `014` (`app`).
|
||||
- a decisao `008` fixa o contrato status-first de `gfx`.
|
||||
|
||||
@@ -142,7 +142,7 @@ Para suportar este protocolo, a VM precisa expor API canonica para:
|
||||
|
||||
As seguintes agendas devem consumir esta decisao:
|
||||
|
||||
- `spec 08-save-memory-and-memcard.md` (historico arquitetural em `learn/011`)
|
||||
- `spec 08-save-memory-and-memcard.md` (historico arquitetural em `learn/historical-game-memcard-slots-surface-and-semantics.md`)
|
||||
- `014-app-home-filesystem-surface-and-semantics.md`
|
||||
- discussoes futuras de data bank
|
||||
|
||||
|
||||
@@ -22,16 +22,16 @@ Decisoes ativas:
|
||||
|
||||
Decisoes implementadas e aposentadas (migradas para `learn/`):
|
||||
|
||||
- `008-gfx-status-first-fault-and-return-contract.md`
|
||||
- `historical-gfx-status-first-fault-and-return-contract.md`
|
||||
- spec: `../specs/04-gfx-peripheral.md`
|
||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/gfx.rs`
|
||||
- `009-audio-status-first-fault-and-return-contract.md`
|
||||
- `historical-audio-status-first-fault-and-return-contract.md`
|
||||
- spec: `../specs/05-audio-peripheral.md`
|
||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/audio.rs`, `crates/console/prometeu-hal/src/audio_bridge.rs`, `crates/console/prometeu-drivers/src/audio.rs`
|
||||
- `010-asset-status-first-fault-and-return-contract.md`
|
||||
- `historical-asset-status-first-fault-and-return-contract.md`
|
||||
- spec: `../specs/15-asset-management.md`
|
||||
- impl: `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/asset.rs`, `crates/console/prometeu-hal/src/asset_bridge.rs`, `crates/console/prometeu-drivers/src/asset.rs`
|
||||
- `011-game-memcard-slots-surface-and-semantics.md`
|
||||
- `historical-game-memcard-slots-surface-and-semantics.md`
|
||||
- spec: `../specs/08-save-memory-and-memcard.md`, `../specs/16-host-abi-and-syscalls.md`, `../specs/16a-syscall-policies.md`
|
||||
- impl: `crates/console/prometeu-system/src/services/memcard.rs`, `crates/console/prometeu-system/src/virtual_machine_runtime/dispatch.rs`, `crates/console/prometeu-hal/src/syscalls/domains/fs.rs`
|
||||
|
||||
@@ -42,4 +42,4 @@ Decisoes aposentadas que ja viraram spec:
|
||||
|
||||
Racional historico (nao normativo):
|
||||
|
||||
- `../learn/retired-decisions-004-005-history.md`
|
||||
- `../learn/historical-retired-fault-and-input-decisions.md`
|
||||
|
||||
@@ -10,27 +10,54 @@ Ela existe para explicar o modelo mental da fantasy handheld, suas influências,
|
||||
- As superfícies normativas da máquina vivem em [`../specs/`](../specs/README.md).
|
||||
- As invariantes internas da VM/runtime vivem em [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
|
||||
|
||||
## Current Guides
|
||||
## Reading Order
|
||||
|
||||
- [`gfx-mental-model.md`](gfx-mental-model.md)
|
||||
- [`audio-mental-model.md`](audio-mental-model.md)
|
||||
- [`input-mental-model.md`](input-mental-model.md)
|
||||
- [`touch-mental-model.md`](touch-mental-model.md)
|
||||
- [`save-memory-and-memcard.md`](save-memory-and-memcard.md)
|
||||
- [`observability-and-debugging.md`](observability-and-debugging.md)
|
||||
- [`portability-and-cross-platform.md`](portability-and-cross-platform.md)
|
||||
- [`time-model-and-cycles.md`](time-model-and-cycles.md)
|
||||
- [`retired-decisions-004-005-history.md`](retired-decisions-004-005-history.md)
|
||||
- [`008-gfx-status-first-fault-and-return-contract.md`](008-gfx-status-first-fault-and-return-contract.md)
|
||||
- [`009-audio-status-first-fault-and-return-contract.md`](009-audio-status-first-fault-and-return-contract.md)
|
||||
- [`010-asset-status-first-fault-and-return-contract.md`](010-asset-status-first-fault-and-return-contract.md)
|
||||
- [`011-game-memcard-slots-surface-and-semantics.md`](011-game-memcard-slots-surface-and-semantics.md)
|
||||
Se a pessoa esta entrando agora no modelo da maquina, a ordem mais util e:
|
||||
|
||||
1. [`mental-model-time-and-cycles.md`](mental-model-time-and-cycles.md)
|
||||
2. [`mental-model-portability-and-cross-platform.md`](mental-model-portability-and-cross-platform.md)
|
||||
3. [`mental-model-observability-and-debugging.md`](mental-model-observability-and-debugging.md)
|
||||
4. [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
5. depois os perifericos e dominios especificos
|
||||
|
||||
## Core Mental Models
|
||||
|
||||
- [`mental-model-time-and-cycles.md`](mental-model-time-and-cycles.md)
|
||||
- [`mental-model-portability-and-cross-platform.md`](mental-model-portability-and-cross-platform.md)
|
||||
- [`mental-model-observability-and-debugging.md`](mental-model-observability-and-debugging.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Peripheral Mental Models
|
||||
|
||||
- [`mental-model-gfx.md`](mental-model-gfx.md)
|
||||
- [`mental-model-audio.md`](mental-model-audio.md)
|
||||
- [`mental-model-input.md`](mental-model-input.md)
|
||||
- [`mental-model-touch.md`](mental-model-touch.md)
|
||||
- [`mental-model-save-memory-and-memcard.md`](mental-model-save-memory-and-memcard.md)
|
||||
|
||||
## Historical Snapshots
|
||||
|
||||
Estes arquivos preservam o racional de decisions ja absorvidas por specs e/ou implementacao. Eles sao uteis para contexto, mas nao devem ser lidos como contrato atual primario.
|
||||
|
||||
- [`historical-gfx-status-first-fault-and-return-contract.md`](historical-gfx-status-first-fault-and-return-contract.md)
|
||||
- [`historical-audio-status-first-fault-and-return-contract.md`](historical-audio-status-first-fault-and-return-contract.md)
|
||||
- [`historical-asset-status-first-fault-and-return-contract.md`](historical-asset-status-first-fault-and-return-contract.md)
|
||||
- [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
|
||||
- [`historical-retired-fault-and-input-decisions.md`](historical-retired-fault-and-input-decisions.md)
|
||||
|
||||
## Naming Convention
|
||||
|
||||
- `mental-model-*.md`: ponto de entrada didatico e consolidado.
|
||||
- `historical-*.md`: snapshot historico, racional aposentado ou consolidado em outro lugar.
|
||||
- `README.md`: mapa e navegacao da area.
|
||||
|
||||
## Rules
|
||||
|
||||
- material em `learn` pode explicar, comparar, ensinar e contextualizar;
|
||||
- material em `learn` não deve redefinir o contrato normativo dos specs;
|
||||
- quando um tema tiver spec e guia didático, o guia deve apontar para o spec correspondente.
|
||||
- quando houver snapshot historico e guia consolidado sobre o mesmo tema, o guia consolidado deve ser o ponto de entrada.
|
||||
- snapshots devem deixar claro que sao historicos e apontar para as anchors normativas atuais.
|
||||
|
||||
## When To Create A Pair
|
||||
|
||||
@@ -42,3 +69,12 @@ Criar um par `spec` + `learn` quando o tema:
|
||||
- exige exemplos, comparações ou intuição que não pertencem ao contrato.
|
||||
|
||||
Se o tema for pequeno e estritamente contratual, o capítulo pode nascer só em `specs`.
|
||||
|
||||
## Learn Refactoring Rule
|
||||
|
||||
Quando `learn` acumular snapshots demais:
|
||||
|
||||
- consolidar ideias repetidas em guias didaticos maiores;
|
||||
- reduzir redundancia cronologica;
|
||||
- manter snapshots apenas como rastro historico e backlink;
|
||||
- reorganizar por modelo mental, nao por ordem de decisao.
|
||||
|
||||
+8
-1
@@ -1,4 +1,11 @@
|
||||
# Decision Record - Asset Status-First Fault and Return Contract
|
||||
# Historical Snapshot - Asset Status-First Fault and Return Contract
|
||||
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
+8
-1
@@ -1,4 +1,11 @@
|
||||
# Decision Record - Audio Status-First Fault and Return Contract
|
||||
# Historical Snapshot - Audio Status-First Fault and Return Contract
|
||||
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
+10
-1
@@ -1,4 +1,13 @@
|
||||
# Decision Record - Game Memcard Slots Surface and Semantics
|
||||
# Historical Snapshot - Game Memcard Slots Surface and Semantics
|
||||
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
- [`../specs/16-host-abi-and-syscalls.md`](../specs/16-host-abi-and-syscalls.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-save-memory-and-memcard.md`](mental-model-save-memory-and-memcard.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
+8
-1
@@ -1,4 +1,11 @@
|
||||
# Decision Record - GFX Status-First Fault and Return Contract
|
||||
# Historical Snapshot - GFX Status-First Fault and Return Contract
|
||||
|
||||
Status: historical snapshot in `learn`, not normative.
|
||||
Current normative anchors:
|
||||
|
||||
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`mental-model-status-first-and-fault-thinking.md`](mental-model-status-first-and-fault-thinking.md)
|
||||
|
||||
## Status
|
||||
|
||||
@@ -0,0 +1,107 @@
|
||||
# Save Memory and MEMCARD
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
Historical snapshot: [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
|
||||
|
||||
PROMETEU trata persistência como hardware explícito, não como save invisível.
|
||||
|
||||
## Mental Model
|
||||
|
||||
O MEMCARD não é save state. Ele é um dispositivo de persistência controlado pelo jogo.
|
||||
|
||||
Isso implica:
|
||||
|
||||
- tamanho conhecido;
|
||||
- custo observável;
|
||||
- necessidade de `commit()`;
|
||||
- possibilidade de falha;
|
||||
- formato de dados sob controle do jogo.
|
||||
|
||||
## Slot Thinking
|
||||
|
||||
O modelo certo nao e "o jogo salva arquivos". O modelo certo e "o jogo conversa com slots".
|
||||
|
||||
Isso muda o jeito de pensar persistencia:
|
||||
|
||||
- capacidade e finita e conhecida;
|
||||
- cada slot tem identidade e estado;
|
||||
- ownership pertence ao `app_id` do cart;
|
||||
- o jogo nao ganha acesso amplo ao filesystem do host.
|
||||
|
||||
Essa escolha existe para manter:
|
||||
|
||||
- portabilidade;
|
||||
- isolamento entre apps;
|
||||
- UX previsivel de save;
|
||||
- contrato executavel em desktop e hardware dedicado.
|
||||
|
||||
## Staged Versus Committed
|
||||
|
||||
Uma intuicao importante em MEMCARD e a diferenca entre:
|
||||
|
||||
- mexer no conteudo em staging;
|
||||
- tornar a escrita persistida de fato.
|
||||
|
||||
`commit()` existe para separar essas duas fases.
|
||||
|
||||
Isso ensina um modelo de persistencia mais honesto:
|
||||
|
||||
- escrever ainda nao e persistir;
|
||||
- persistir tem custo;
|
||||
- persistir pode falhar;
|
||||
- atomicidade importa.
|
||||
|
||||
## Why Explicit Commit Matters
|
||||
|
||||
O `commit()` existe para tornar persistência uma decisão técnica visível.
|
||||
|
||||
Sem ele, não há ilusão de que “salvar simplesmente aconteceu”. O jogo precisa assumir quando quer:
|
||||
|
||||
- materializar escrita;
|
||||
- aceitar custo;
|
||||
- lidar com risco de perda ou corrupção.
|
||||
|
||||
## Runtime-Owned Metadata
|
||||
|
||||
Mesmo quando o payload pertence ao jogo, alguns aspectos do slot pertencem a maquina:
|
||||
|
||||
- integridade;
|
||||
- geracao/versionamento;
|
||||
- estado do slot;
|
||||
- isolamento por ownership.
|
||||
|
||||
Isso evita que cada jogo reinvente sua propria semantica basica de persistencia e permite que tooling e Hub/OS apresentem save de forma coerente.
|
||||
|
||||
## Hub/OS Role
|
||||
|
||||
PROMETEU separa claramente:
|
||||
|
||||
- o jogo grava e le seus slots;
|
||||
- o Hub/OS faz export, import, copia e apresentacao de saves.
|
||||
|
||||
Essa separacao impede que userland vire um mini-gerenciador de arquivos e mantem as operacoes de sistema na camada certa.
|
||||
|
||||
## Tooling Surface
|
||||
|
||||
Ferramentas externas podem expor utilidades como:
|
||||
|
||||
- criar ou resetar MEMCARD;
|
||||
- importar e exportar `.mem`;
|
||||
- inspecionar tamanho e uso;
|
||||
- associar cartões a projetos.
|
||||
|
||||
Essas superfícies são auxiliares. Elas não mudam o contrato da máquina.
|
||||
|
||||
## Why This Is Better Than Broad FS For Games
|
||||
|
||||
Para perfil `game`, o modelo de slot e melhor que abrir um filesystem geral porque:
|
||||
|
||||
- reduz ambiguidade de path, permissao e ownership;
|
||||
- facilita import/export controlado;
|
||||
- melhora compatibilidade entre hosts;
|
||||
- deixa mais claro o que significa "save valido" para a maquina.
|
||||
|
||||
## Why This Fits PROMETEU
|
||||
|
||||
Esse modelo conversa bem com a herança de console e com o foco DIY do projeto: persistência é parte do design da máquina, não conveniência escondida do host.
|
||||
@@ -0,0 +1,155 @@
|
||||
# Status-First and Fault Thinking
|
||||
|
||||
Status: pedagogical
|
||||
Companion specs:
|
||||
|
||||
- [`../specs/16a-syscall-policies.md`](../specs/16a-syscall-policies.md)
|
||||
- [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
|
||||
- [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
|
||||
- [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
|
||||
|
||||
PROMETEU usa um modelo status-first para impedir que a borda host/runtime esconda erro operacional como silencio, `Trap` indevido ou `Panic` acidental.
|
||||
|
||||
## Core Split
|
||||
|
||||
O modelo mental certo e:
|
||||
|
||||
- `Trap` para violacao estrutural de contrato;
|
||||
- `status` para resultado operacional observavel;
|
||||
- `Panic` para quebra de invariante interna.
|
||||
|
||||
Uma forma curta de pensar:
|
||||
|
||||
- guest chamou errado: `Trap`;
|
||||
- guest chamou certo, mas o dominio nao conseguiu concluir: `status`;
|
||||
- runtime quebrou por dentro: `Panic`.
|
||||
|
||||
## Why This Exists
|
||||
|
||||
Sem essa separacao, sistemas host-backed tendem a degradar para uma mistura ruim de:
|
||||
|
||||
- `void` em operacoes que falham de verdade;
|
||||
- fallback implicito;
|
||||
- no-op silencioso;
|
||||
- escalacao de erro de app para `Panic`.
|
||||
|
||||
Status-first existe para tornar o comportamento:
|
||||
|
||||
- observavel;
|
||||
- deterministico;
|
||||
- testavel;
|
||||
- documentavel por dominio.
|
||||
|
||||
## Return Shape Rule
|
||||
|
||||
A regra pratica mais importante e simples:
|
||||
|
||||
- se a operacao pode falhar operacionalmente, ela deve retornar `status`;
|
||||
- se a operacao nao tem caminho real de falha operacional, ela pode ser `void`.
|
||||
|
||||
Isso impede contratos em que o guest nao consegue distinguir:
|
||||
|
||||
- sucesso;
|
||||
- rejeicao;
|
||||
- ausencia de efeito;
|
||||
- backend indisponivel;
|
||||
- asset ou recurso ausente.
|
||||
|
||||
## Silent Failure Is Not Allowed
|
||||
|
||||
Em PROMETEU, erro operacional nao pode ser maquiado como:
|
||||
|
||||
- sucesso implicito;
|
||||
- ignorar a chamada;
|
||||
- fallback automatico para outro recurso;
|
||||
- `Trap`, quando o problema nao e estrutural;
|
||||
- `Panic`, quando o problema nao e interno.
|
||||
|
||||
Se o guest pode perceber a diferenca, essa diferenca deve aparecer como `status`.
|
||||
|
||||
## Reading The Boundary
|
||||
|
||||
Quando estiver lendo ou desenhando uma syscall, use esta sequencia:
|
||||
|
||||
1. A chamada esta estruturalmente correta?
|
||||
2. O guest tem permissao/capability para usar a surface?
|
||||
3. O dominio consegue executar a operacao com os recursos atuais?
|
||||
4. Ha payload adicional que so faz sentido quando o `status` indica sucesso?
|
||||
|
||||
Essa leitura tende a produzir contratos mais limpos, por exemplo:
|
||||
|
||||
- `asset.load(...) -> (status, handle)`
|
||||
- `mem.slot_read(...) -> (status, payload, bytes_read)`
|
||||
- operacoes sem falha real continuam `void`
|
||||
|
||||
## Domain Intuition
|
||||
|
||||
### GFX
|
||||
|
||||
Em `gfx`, o problema tipico nao e "a syscall explodiu". O problema tipico e:
|
||||
|
||||
- sprite inexistente;
|
||||
- indice fora da faixa operacional;
|
||||
- argumento invalido para a operacao;
|
||||
- chamada sem efeito real.
|
||||
|
||||
Esses casos pedem `status`, nao silencio.
|
||||
|
||||
### Audio
|
||||
|
||||
Em `audio`, o modelo impede coisas como:
|
||||
|
||||
- voz invalida ser ignorada;
|
||||
- sample ausente virar fallback mudo;
|
||||
- parametro fora de faixa parecer sucesso.
|
||||
|
||||
Audio deve se comportar como periferico finito e explicito, nao como "som automatico".
|
||||
|
||||
### Asset
|
||||
|
||||
Em `asset`, status-first separa melhor:
|
||||
|
||||
- erro de request;
|
||||
- lifecycle assíncrono;
|
||||
- commit/cancel invalido;
|
||||
- handle desconhecido.
|
||||
|
||||
Isso combina com o modelo de request + poll + commit, em vez de fingir que carregamento e instantaneo.
|
||||
|
||||
### FS / MEMCARD
|
||||
|
||||
Em persistencia, status-first impede a pior categoria de erro: "pareceu salvar".
|
||||
|
||||
Casos como:
|
||||
|
||||
- slot vazio;
|
||||
- storage cheio;
|
||||
- conflito;
|
||||
- corrupcao;
|
||||
- backend indisponivel;
|
||||
|
||||
precisam aparecer como estado observavel, porque o jogo e o Hub/OS precisam reagir a isso.
|
||||
|
||||
## Design Smells
|
||||
|
||||
Sinais de que o contrato ainda esta ruim:
|
||||
|
||||
- a operacao pode falhar, mas retorna `void`;
|
||||
- existe fallback implicito para recurso default;
|
||||
- a documentacao depende de "na pratica nao deve acontecer";
|
||||
- `Panic` aparece para erro de input do app;
|
||||
- o mesmo dominio mistura no-op silencioso e status explicito;
|
||||
- payload de retorno nao deixa claro quando e valido.
|
||||
|
||||
## Historical Anchors
|
||||
|
||||
Este guia consolida a intuicao que apareceu primeiro nestes snapshots historicos:
|
||||
|
||||
- [`historical-gfx-status-first-fault-and-return-contract.md`](historical-gfx-status-first-fault-and-return-contract.md)
|
||||
- [`historical-audio-status-first-fault-and-return-contract.md`](historical-audio-status-first-fault-and-return-contract.md)
|
||||
- [`historical-asset-status-first-fault-and-return-contract.md`](historical-asset-status-first-fault-and-return-contract.md)
|
||||
- [`historical-game-memcard-slots-surface-and-semantics.md`](historical-game-memcard-slots-surface-and-semantics.md)
|
||||
- [`historical-retired-fault-and-input-decisions.md`](historical-retired-fault-and-input-decisions.md)
|
||||
|
||||
Use os snapshots para contexto historico. Use as specs para o contrato normativo atual.
|
||||
@@ -1,43 +0,0 @@
|
||||
# Save Memory and MEMCARD
|
||||
|
||||
Status: pedagogical
|
||||
Companion spec: [`../specs/08-save-memory-and-memcard.md`](../specs/08-save-memory-and-memcard.md)
|
||||
|
||||
PROMETEU trata persistência como hardware explícito, não como save invisível.
|
||||
|
||||
## Mental Model
|
||||
|
||||
O MEMCARD não é save state. Ele é um dispositivo de persistência controlado pelo jogo.
|
||||
|
||||
Isso implica:
|
||||
|
||||
- tamanho conhecido;
|
||||
- custo observável;
|
||||
- necessidade de `commit()`;
|
||||
- possibilidade de falha;
|
||||
- formato de dados sob controle do jogo.
|
||||
|
||||
## Why Explicit Commit Matters
|
||||
|
||||
O `commit()` existe para tornar persistência uma decisão técnica visível.
|
||||
|
||||
Sem ele, não há ilusão de que “salvar simplesmente aconteceu”. O jogo precisa assumir quando quer:
|
||||
|
||||
- materializar escrita;
|
||||
- aceitar custo;
|
||||
- lidar com risco de perda ou corrupção.
|
||||
|
||||
## Tooling Surface
|
||||
|
||||
Ferramentas externas podem expor utilidades como:
|
||||
|
||||
- criar ou resetar MEMCARD;
|
||||
- importar e exportar `.mem`;
|
||||
- inspecionar tamanho e uso;
|
||||
- associar cartões a projetos.
|
||||
|
||||
Essas superfícies são auxiliares. Elas não mudam o contrato da máquina.
|
||||
|
||||
## Why This Fits PROMETEU
|
||||
|
||||
Esse modelo conversa bem com a herança de console e com o foco DIY do projeto: persistência é parte do design da máquina, não conveniência escondida do host.
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: machine timing and cycles
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/time-model-and-cycles.md`](../learn/time-model-and-cycles.md)
|
||||
Didactic companion: [`../learn/mental-model-time-and-cycles.md`](../learn/mental-model-time-and-cycles.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: virtual hardware: graphics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/gfx-mental-model.md`](../learn/gfx-mental-model.md)
|
||||
Didactic companion: [`../learn/mental-model-gfx.md`](../learn/mental-model-gfx.md)
|
||||
|
||||
## 1. Overview
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: virtual hardware: audio
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/audio-mental-model.md`](../learn/audio-mental-model.md)
|
||||
Didactic companion: [`../learn/mental-model-audio.md`](../learn/mental-model-audio.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: virtual hardware: input
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/input-mental-model.md`](../learn/input-mental-model.md)
|
||||
Didactic companion: [`../learn/mental-model-input.md`](../learn/mental-model-input.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: virtual hardware: touch
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/touch-mental-model.md`](../learn/touch-mental-model.md)
|
||||
Didactic companion: [`../learn/mental-model-touch.md`](../learn/mental-model-touch.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: virtual hardware: save memory
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/save-memory-and-memcard.md`](../learn/save-memory-and-memcard.md)
|
||||
Didactic companion: [`../learn/mental-model-save-memory-and-memcard.md`](../learn/mental-model-save-memory-and-memcard.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
@@ -137,4 +137,4 @@ The exact host-side file naming is internal to runtime/host as long as ownership
|
||||
|
||||
PROMETEU does not auto-save slot staging data.
|
||||
|
||||
Without `slot_commit`, writes remain staged and are not guaranteed as persisted committed state.]
|
||||
Without `slot_commit`, writes remain staged and are not guaranteed as persisted committed state.]
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: machine diagnostics
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/observability-and-debugging.md`](../learn/observability-and-debugging.md)
|
||||
Didactic companion: [`../learn/mental-model-observability-and-debugging.md`](../learn/mental-model-observability-and-debugging.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Domain: portability contract
|
||||
Function: normative
|
||||
|
||||
Didactic companion: [`../learn/portability-and-cross-platform.md`](../learn/portability-and-cross-platform.md)
|
||||
Didactic companion: [`../learn/mental-model-portability-and-cross-platform.md`](../learn/mental-model-portability-and-cross-platform.md)
|
||||
|
||||
## 1 Scope
|
||||
|
||||
|
||||
Reference in New Issue
Block a user