agents and learn refactor

This commit is contained in:
2026-03-24 13:40:53 +00:00
parent 52aed9d0ea
commit 76fd0943d3
28 changed files with 629 additions and 77 deletions
+50 -14
View File
@@ -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.
@@ -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
@@ -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
@@ -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
@@ -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.