agents and learn refactor

AGENTS.md

@@ -0,0 +1,267 @@
+# AGENTS
+
+## Missao
+
+Este repositorio deve operar com um pipeline rigido de conhecimento e execucao:
+
+`agenda -> decision -> PR/plan -> spec ou codigo -> learn`
+
+Regra central:
+
+- nao pular etapas;
+- nao resolver ambiguidade estrutural no meio da implementacao;
+- nao transformar `learn` em deposito cru de historico;
+- nao escrever spec ou codigo sem base em `decision` e `PR/plan` quando houver impacto arquitetural.
+
+## Mapa Canonico
+
+- `docs/runtime/agendas/`: discussao, enquadramento do problema, pontos mais importantes, sugestoes e recomendacao.
+- `docs/runtime/decisions/`: registro normativo do que foi decidido. Deve estar pronto para propagar em spec ou implementacao.
+- `docs/runtime/pull-requests/`: plano executavel de entrega para spec e/ou codigo.
+- `docs/runtime/specs/`: contrato tecnico normativo consolidado.
+- `docs/runtime/learn/`: consolidacao didatica do que ja foi fechado e executado.
+- `crates/`: implementacao em codigo.
+
+## Fluxo Obrigatorio
+
+### 1. Agenda
+
+Use `agenda` quando ainda existe ambiguidade, disputa de abordagem, risco arquitetural, escopo mal fechado ou falta de recomendacao.
+
+Toda agenda deve:
+
+- apresentar o problema real;
+- listar os pontos mais importantes da discussao;
+- separar fato, risco, tradeoff e hipotese;
+- trazer sugestoes objetivas, nao so perguntas soltas;
+- terminar com uma recomendacao clara, mesmo que condicional;
+- explicitar o que ainda impede a decisao.
+
+Template minimo:
+
+- `Contexto`
+- `Problema`
+- `Pontos Criticos`
+- `Opcoes`
+- `Sugestao / Recomendacao`
+- `Perguntas em Aberto`
+- `Criterio para Encerrar`
+
+Regra de saida:
+
+- agenda concluida deve virar `decision`;
+- agenda que ainda nao fecha contrato nao pode virar PR de implementacao.
+
+### 2. Decision
+
+Toda agenda concluida deve se tornar uma `decision`.
+
+Uma `decision` deve conter tudo que a equipe precisa para propagar a decisao em spec ou implementacao, inclusive referencias para specs ja consolidadas quando existirem.
+
+Toda decision deve:
+
+- declarar a decisao tomada sem ambiguidade;
+- registrar contexto e drivers;
+- listar alternativas descartadas e por que foram descartadas;
+- definir invariantes e contrato operacional;
+- delimitar impacto em specs, runtime, host, firmware e tooling quando aplicavel;
+- apontar referencias normativas existentes;
+- deixar claro o que ainda precisa ser implementado ou publicado.
+
+Template minimo:
+
+- `Status`
+- `Contexto`
+- `Decisao`
+- `Rationale`
+- `Invariantes / Contrato`
+- `Impactos`
+- `Referencias`
+- `Propagacao Necessaria`
+
+Regra de saida:
+
+- decision fechada deve evoluir para `PR/plan`;
+- se a decision nao estiver pronta para orientar execucao, ela ainda nao esta fechada.
+
+### 3. PR / Plan
+
+`PR` e o artefato de planejamento de execucao. Ele nasce de uma ou mais `decisions`.
+
+Toda PR deve:
+
+- citar explicitamente as decisions de origem;
+- separar implementacao de spec e implementacao de codigo quando o escopo pedir;
+- definir alvo, fora de escopo, riscos e ordem de execucao;
+- trazer criterios de aceite verificaveis;
+- definir estrategia de testes e evidencias esperadas;
+- bloquear reabertura de debate arquitetural dentro da fase de execucao.
+
+Template minimo:
+
+- `Briefing`
+- `Decisions de Origem`
+- `Alvo`
+- `Escopo`
+- `Fora de Escopo`
+- `Plano de Execucao`
+- `Criterios de Aceite`
+- `Tests / Validacao`
+- `Riscos`
+
+Regra de saida:
+
+- PR de spec alimenta `docs/runtime/specs/`;
+- PR de codigo alimenta `crates/`;
+- PR concluida deve deixar rastro para consolidacao em `learn`.
+
+### 4. Learn
+
+`learn` recebe conhecimento consolidado de decisions que ja viraram PR e tiveram resultado publicado em spec, codigo ou ambos.
+
+`learn` nao e fonte normativa. `learn` explica, organiza, ensina e melhora a transmissao do modelo mental.
+
+Toda consolidacao em `learn` deve:
+
+- partir de decisions ja fechadas;
+- refletir o estado publicado em specs e/ou codigo;
+- explicar o "como pensar" e nao so o "o que aconteceu";
+- linkar para specs e decisions correspondentes;
+- remover redundancia historica quando houver material sobreposto.
+
+Regra de manutencao:
+
+- de tempos em tempos, refatorar `learn` por tema, modelo mental e progressao didatica;
+- preferir guias tematicos a acumulo cronologico de decisions aposentadas;
+- preservar backlinks para decisions/specs originais.
+
+## Workers Obrigatorios
+
+### Agenda Worker
+
+Use para abrir ou conduzir discussoes.
+
+Responsabilidades:
+
+- sintetizar pontos mais importantes;
+- propor sugestoes concretas;
+- separar sinal de ruido;
+- empurrar para uma recomendacao.
+
+Nao faz:
+
+- fechar contrato normativo cedo demais;
+- planejar implementacao detalhada.
+
+### Decision Worker
+
+Use para transformar agenda concluida em decisao clara.
+
+Responsabilidades:
+
+- cristalizar a decisao;
+- registrar invariantes;
+- preparar a propagacao para spec e implementacao;
+- referenciar material normativo ja existente.
+
+Nao faz:
+
+- escrever plano de execucao detalhado;
+- deixar ambiguidades estruturais escondidas.
+
+### PR Worker
+
+Use para transformar decisions em execucao.
+
+Responsabilidades:
+
+- decompor o trabalho;
+- separar fases editorial e de codigo;
+- definir aceite, testes, riscos e sequenciamento.
+
+Nao faz:
+
+- rediscutir arquitetura base;
+- improvisar contrato no meio do plano.
+
+### Learn Worker
+
+Use para consolidar conhecimento e refatorar `docs/runtime/learn/`.
+
+Perfil esperado:
+
+- didatico;
+- editorial;
+- orientado a modelo mental, exemplos e progressao pedagogica.
+
+Responsabilidades:
+
+- consolidar varias decisions em artefatos mais ensinaveis;
+- reorganizar material por tema;
+- reduzir repeticao e melhorar navegacao.
+
+Nao faz:
+
+- redefinir contrato tecnico;
+- competir com specs.
+
+### Spec Worker
+
+Use para implementar specs a partir de decisions e PRs.
+
+Perfil esperado:
+
+- editorial;
+- normativo;
+- preciso em contrato, escopo e linguagem.
+
+Responsabilidades:
+
+- atualizar ou criar specs coerentes com a decision;
+- manter contrato tecnico consistente;
+- citar referencias normativas corretas.
+
+Nao faz:
+
+- inventar decisao nova durante edicao;
+- introduzir framing pedagogico de `learn` dentro do texto normativo.
+
+### Code Worker
+
+Use para implementar codigo a partir de decisions, specs e PRs.
+
+Perfil esperado:
+
+- executor;
+- rigoroso;
+- focado em comportamento, testes e aderencia ao contrato.
+
+Responsabilidades:
+
+- implementar o que a spec/decision manda;
+- validar impacto e cobertura;
+- apontar qualquer conflito entre codigo e contrato.
+
+Nao faz:
+
+- compensar ambiguidade arquitetural com heuristica local;
+- esconder mudanca de contrato dentro de refactor.
+
+## Regras de Transicao
+
+- nunca criar PR de implementacao se o assunto ainda e uma agenda em aberto;
+- toda agenda encerrada deve resultar em `decision` ou ser explicitamente descartada;
+- toda decision relevante deve gerar `PR/plan` antes de alterar spec ou codigo;
+- toda decision executada deve deixar consolidacao em `learn`, direta ou agrupada;
+- quando `learn` acumular historico demais, ativar o `Learn Worker` para refatoracao didatica.
+
+## Regra Editorial
+
+- `agenda` discute;
+- `decision` decide;
+- `PR` planeja;
+- `spec` normatiza;
+- `codigo` implementa;
+- `learn` ensina.
+
+Se um artefato comecar a fazer o trabalho do outro, ele esta errado.

docs/runtime/agendas/README.md

@@ -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`.

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

@@ -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
 

docs/runtime/decisions/README.md

@@ -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`

docs/runtime/learn/README.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.

docs/runtime/learn/historical-asset-status-first-fault-and-return-contract.md

@@ -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
 

docs/runtime/learn/historical-audio-status-first-fault-and-return-contract.md

@@ -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
 

docs/runtime/learn/historical-game-memcard-slots-surface-and-semantics.md

@@ -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
 

docs/runtime/learn/historical-gfx-status-first-fault-and-return-contract.md

@@ -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
 

docs/runtime/learn/mental-model-save-memory-and-memcard.md

@@ -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.

docs/runtime/learn/mental-model-status-first-and-fault-thinking.md

@@ -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.

docs/runtime/learn/save-memory-and-memcard.md

@@ -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.

docs/runtime/specs/01-time-model-and-cycles.md

@@ -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
 

docs/runtime/specs/04-gfx-peripheral.md

@@ -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
 

docs/runtime/specs/05-audio-peripheral.md

@@ -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
 

docs/runtime/specs/06-input-peripheral.md

@@ -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
 

docs/runtime/specs/07-touch-peripheral.md

@@ -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
 

docs/runtime/specs/08-save-memory-and-memcard.md

@@ -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.]

docs/runtime/specs/10-debug-inspection-and-profiling.md

@@ -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
 

docs/runtime/specs/11-portability-and-cross-platform-execution.md

@@ -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