Intrepid/prometeu-runtime
Intrepid/prometeu-runtime
3
0
Fork 0
Code Pull Requests Activity

clean up

Browse Source
This commit is contained in:
bQUARKz 2026-03-11 07:26:05 +00:00
parent f3f689fbef
commit d7c970a3e2
Signed by: bquarkz
SSH Key Fingerprint: SHA256:Z7dgqoglWwoK6j6u4QC87OveEq74WOhFN+gitsxtkf8
17 changed files with 713 additions and 589 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
AGENTS.md
View File

@ -265,3 +265,10 @@ Nao faz:
- `learn` ensina.
Se um artefato comecar a fazer o trabalho do outro, ele esta errado.
## Regra de Idioma
- todo conteudo publicado em `docs/runtime/specs/` deve ser escrito em ingles;
- todo conteudo publicado em `docs/runtime/learn/` deve ser escrito em ingles;
- essa regra vale mesmo quando a discussao, agenda, decision, PR ou conversa com o usuario acontecer em portugues;
- ao editar artefatos existentes em `specs` ou `learn`, corrigir para ingles qualquer trecho residual em outro idioma.

55
docs/runtime/learn/README.md
View File

@ -1,24 +1,24 @@
# PROMETEU Learn
Esta área reúne material didático sobre a máquina PROMETEU.
This area contains pedagogical material about the PROMETEU machine.
Ela existe para explicar o modelo mental da fantasy handheld, suas influências, tradeoffs e implicações de design sem contaminar as specs normativas com framing pedagógico.
It exists to explain the fantasy handheld's mental model, influences, tradeoffs, and design implications without contaminating the normative specs with pedagogical framing.
## Authority
- `docs/runtime/learn/` não é fonte canônica de contrato técnico.
- 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).
- `docs/runtime/learn/` is not a canonical source of technical contract.
- The machine's normative surfaces live in [`../specs/`](../specs/README.md).
- The VM/runtime's internal invariants live in [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md).
## Reading Order
Se a pessoa esta entrando agora no modelo da maquina, a ordem mais util e:
If someone is entering the machine model now, the most useful order is:
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
5. then the peripherals and specific domains
## Core Mental Models
@ -31,13 +31,14 @@ Se a pessoa esta entrando agora no modelo da maquina, a ordem mais util e:
- [`mental-model-gfx.md`](mental-model-gfx.md)
- [`mental-model-audio.md`](mental-model-audio.md)
- [`mental-model-asset-management.md`](mental-model-asset-management.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.
These files preserve the rationale of decisions already absorbed by specs and/or implementation. They are useful for context, but they should not be read as the primary current contract.
- [`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)
@ -47,34 +48,34 @@ Estes arquivos preservam o racional de decisions ja absorvidas por specs e/ou im
## 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.
- `mental-model-*.md`: consolidated pedagogical entry point.
- `historical-*.md`: historical snapshot, retired rationale, or material consolidated elsewhere.
- `README.md`: area map and navigation.
## 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.
- material in `learn` may explain, compare, teach, and provide context;
- material in `learn` must not redefine the normative contract of the specs;
- when a topic has both a spec and a pedagogical guide, the guide should point to the corresponding spec;
- when there is both a historical snapshot and a consolidated guide for the same topic, the consolidated guide should be the entry point;
- snapshots must make clear that they are historical and point to the current normative anchors.
## When To Create A Pair
Criar um par `spec` + `learn` quando o tema:
Create a `spec` + `learn` pair when the topic:
- precisa de contrato técnico estável e também de modelo mental;
- tem forte carga histórica, pedagógica ou de design rationale;
- corre risco de virar manifesto dentro do spec normativo;
- exige exemplos, comparações ou intuição que não pertencem ao contrato.
- needs a stable technical contract and a mental model;
- has strong historical, pedagogical, or design-rationale weight;
- risks turning into manifesto text inside the normative spec;
- requires examples, comparisons, or intuition that do not belong in the contract.
Se o tema for pequeno e estritamente contratual, o capítulo pode nascer só em `specs`.
If the topic is small and strictly contractual, the chapter may live only in `specs`.
## Learn Refactoring Rule
Quando `learn` acumular snapshots demais:
When `learn` accumulates too many snapshots:
- 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.
- consolidate repeated ideas into larger pedagogical guides;
- reduce chronological redundancy;
- keep snapshots only as historical trace and backlink;
- reorganize by mental model, not by decision order.

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

@ -11,69 +11,69 @@ Current normative anchors:
Accepted
## Contexto
## Context
A agenda `006-asset-fault-semantics-and-surface.md` evidenciou inconsistencia no dominio `asset`:
Agenda `006-asset-fault-semantics-and-surface.md` exposed inconsistency in the `asset` domain:
- `asset.status` ja usa status numerico;
- `asset.load` ainda escalava erro operacional para `Panic`;
- `asset.commit`/`asset.cancel` eram `void` com no-op silencioso para varios casos.
- `asset.status` already used numeric status;
- `asset.load` was still escalating operational failure to `Panic`;
- `asset.commit`/`asset.cancel` were `void` with silent no-op in several cases.
Para alinhar o dominio com `16a`, foi fechado contrato status-first para `asset`.
To align the domain with `16a`, a status-first contract was adopted for `asset`.
## Decisao
## Decision
### 1. Fronteira de fault class em `asset`
### 1. Fault-class boundary in `asset`
`asset` segue:
`asset` follows:
- `Trap`: violacao estrutural de ABI/chamada (tipo, aridade, capability, shape).
- `status` (inteiro): erro operacional recuperavel de dominio.
- `Panic`: apenas quebra de invariante interna de runtime/host.
- `Trap`: structural ABI/call violation (type, arity, capability, shape).
- `status` (integer): recoverable operational domain error.
- `Panic`: internal runtime/host invariant break only.
### 2. Surface canonica do dominio
### 2. Canonical domain surface
A surface final do MVP fica:
The final MVP surface is:
- `asset.load(name, kind, slot) -> (status:int, handle:int)`
- `asset.status(handle) -> status:int`
- `asset.commit(handle) -> status:int`
- `asset.cancel(handle) -> status:int`
Regras:
Rules:
- `handle` so e valido quando `status == ASSET_OK`;
- em falha de `load`, `handle` deve ser `0`.
- `handle` is only valid when `status == ASSET_OK`;
- on `load` failure, `handle` must be `0`.
### 3. No-op silencioso proibido
### 3. Silent no-op forbidden
No-op silencioso nao e permitido para operacoes com erro operacional possivel.
Silent no-op is not allowed for operations with possible operational error.
Casos como:
Cases such as:
- handle desconhecido;
- transicao invalida de lifecycle;
- slot invalido;
- asset ausente;
- unknown handle;
- invalid lifecycle transition;
- invalid slot;
- missing asset;
devem retornar `status` explicito.
must return explicit `status`.
### 4. `asset.load` (request path)
Falhas operacionais de request devem virar `status`, incluindo:
Operational request failures must become `status`, including:
- `ASSET_NOT_FOUND`;
- `SLOT_KIND_MISMATCH`;
- `SLOT_INDEX_INVALID`;
- `BACKEND_ERROR`.
`Panic` nao deve ser usado para falha operacional de `load`.
`Panic` must not be used for operational `load` failure.
### 5. `asset.status` (lifecycle path)
`asset.status` permanece a fonte de verdade do lifecycle assíncrono.
`asset.status` remains the source of truth for the asynchronous lifecycle.
Codigos de lifecycle devem cobrir:
Lifecycle codes should cover:
- `PENDING`
- `LOADING`
@ -83,47 +83,47 @@ Codigos de lifecycle devem cobrir:
- `ERROR`
- `UNKNOWN_HANDLE`
### 6. `asset.commit` e `asset.cancel`
### 6. `asset.commit` and `asset.cancel`
Ambas operacoes devem retornar `status`.
Both operations must return `status`.
Tabela minima de resposta:
Minimum response table:
- `ASSET_OK` (acao aceita/concluida para o estado atual)
- `ASSET_OK` (action accepted/completed for the current state)
- `UNKNOWN_HANDLE`
- `INVALID_STATE`
### 7. Relacao com dominio `bank`
### 7. Relationship with the `bank` domain
Erros de residency/slot permanecem no dominio `asset`.
Residency/slot errors remain in the `asset` domain.
`bank` permanece dominio de inspecao (`info`, `slot_info`) e nao absorve erros operacionais de mutacao de asset lifecycle.
`bank` remains an inspection domain (`info`, `slot_info`) and does not absorb operational errors from asset lifecycle mutation.
### 8. Compatibilidade e migracao
### 8. Compatibility and migration
Nao ha requisito de compatibilidade retroativa para esta mudanca.
There is no backward-compatibility requirement for this change.
E permitido:
It is allowed to:
- alterar `ret_slots` de `asset.load`, `asset.commit`, `asset.cancel`;
- ajustar registry/loader/dispatch/runtime com o novo contrato;
- regenerar stress test com as assinaturas novas.
- change `ret_slots` for `asset.load`, `asset.commit`, and `asset.cancel`;
- adjust registry/loader/dispatch/runtime to the new contract;
- regenerate the stress test with the new signatures.
## Consequencias
## Consequences
### Positivas
### Positive
- remove `Panic` operacional indevido do dominio `asset`;
- torna fluxo de lifecycle observavel e consistente;
- elimina ambiguidade de no-op em `commit`/`cancel`.
- removes improper operational `Panic` from the `asset` domain;
- makes lifecycle flow observable and consistent;
- eliminates no-op ambiguity in `commit`/`cancel`.
### Custos
### Costs
- exige migracao de ABI das syscalls `asset`;
- exige atualizacao de testes e artefatos gerados.
- requires ABI migration of `asset` syscalls;
- requires updates to tests and generated artifacts.
## Follow-up Obrigatorio
## Required Follow-up
- agenda `006-asset-fault-semantics-and-surface.md` deve ser considerada absorvida e removida;
- specs `15` e `16a` devem absorver o contrato final quando a implementacao estiver estavel;
- registry de syscall deve refletir o shape final (`ret_slots`) das operacoes `asset`.
- agenda `006-asset-fault-semantics-and-surface.md` should be considered absorbed and removed;
- specs `15` and `16a` should absorb the final contract when implementation is stable;
- the syscall registry should reflect the final operation shape (`ret_slots`) for `asset`.

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

@ -11,107 +11,107 @@ Current normative anchors:
Accepted
## Contexto
## Context
A agenda `005-audio-fault-semantics-and-surface.md` mostrou ambiguidade no dominio `audio`:
Agenda `005-audio-fault-semantics-and-surface.md` exposed ambiguity in the `audio` domain:
- no-op/fallback silencioso para falhas operacionais;
- operacoes `void` mesmo quando ha possibilidade real de falha;
- risco de escalar erro de app para `Panic`.
- silent no-op/fallback for operational failures;
- `void` operations even when real failure is possible;
- risk of escalating app errors to `Panic`.
Para alinhar com `16a`, o dominio `audio` adota politica status-first.
To align with `16a`, the `audio` domain adopts a status-first policy.
## Decisao
## Decision
### 1. Fronteira de fault class em `audio`
### 1. Fault-class boundary in `audio`
`audio` segue a taxonomia:
`audio` follows this taxonomy:
- `Trap`: violacao estrutural de ABI/chamada (tipo, aridade, capability, shape).
- `status` (inteiro): erro operacional recuperavel de dominio.
- `Panic`: apenas quebra de invariante interna de runtime/host.
- `Trap`: structural ABI/call violation (type, arity, capability, shape).
- `status` (integer): recoverable operational domain error.
- `Panic`: internal runtime/host invariant break only.
### 2. Politica de retorno por operacao
### 2. Per-operation return policy
Nem toda syscall precisa retornar `status`.
Not every syscall needs to return `status`.
Regra canonica:
Canonical rule:
- se a operacao pode falhar operacionalmente, deve retornar `status: int` (`ret_slots >= 1`);
- se a operacao nao possui via real de erro operacional, pode permanecer `void`.
- if the operation can fail operationally, it should return `status: int` (`ret_slots >= 1`);
- if the operation has no real operational error path, it may remain `void`.
Para o MVP atual:
For the current MVP:
- `audio.play` deve retornar `status`;
- `audio.play_sample` deve retornar `status`.
- `audio.play` should return `status`;
- `audio.play_sample` should return `status`.
### 3. No-op e fallback
### 3. No-op and fallback
No-op silencioso nao e permitido em operacoes com possibilidade de erro operacional.
Silent no-op is not allowed in operations with possible operational error.
Fallback implicito tambem nao e permitido quando mascara erro de dominio.
Implicit fallback is also not allowed when it masks a domain error.
Exemplos proibidos:
Forbidden examples:
- fallback implicito para `bank_id` default quando asset nao e encontrado;
- ignorar `voice_id` invalido sem retorno explicito.
- implicit fallback to default `bank_id` when the asset is not found;
- ignoring invalid `voice_id` without explicit return.
### 4. Tabela de status por operacao
### 4. Per-operation status table
Cada operacao `audio` que retorna `status` deve declarar codigos inteiros de forma normativa.
Each `audio` operation that returns `status` must define integer codes normatively.
Tabela minima para `play`/`play_sample` deve cobrir, quando aplicavel:
The minimum table for `play`/`play_sample` should cover, when applicable:
- `OK`;
- `VOICE_INVALID`;
- `ASSET_NOT_FOUND`;
- `SAMPLE_NOT_FOUND`;
- `ARG_RANGE_INVALID`;
- `NO_EFFECT` (somente quando houver sem efeito operacional valido e explicito).
- `NO_EFFECT` (only when a valid and explicit no-effect case exists).
### 5. Faixas numericas
### 5. Numeric ranges
Entradas numericas com faixa normativa (`volume`, `pan`, `pitch`) devem ter politica explicita.
Numeric inputs with normative ranges (`volume`, `pan`, `pitch`) must have explicit policy.
Quando fora da faixa aceita:
When outside the accepted range:
- retornar `status` de erro de faixa;
- nao mascarar como sucesso silencioso.
- return range-error `status`;
- do not mask it as silent success.
### 6. Higiene de panic
### 6. Panic hygiene
Erros de argumento de app nao devem escalar para `Panic`.
App argument errors must not escalate to `Panic`.
Esses casos devem ser classificados como:
These cases should be classified as:
- `Trap` (estrutural); ou
- `status` (operacional, conforme a operacao).
- `Trap` (structural); or
- `status` (operational, according to the operation).
### 7. Compatibilidade e migracao
### 7. Compatibility and migration
Nao ha requisito de compatibilidade retroativa para esta mudanca.
There is no backward-compatibility requirement for this change.
E permitido:
It is allowed to:
- ajustar assinaturas de syscall `audio` (incluindo `ret_slots`);
- atualizar registry/loader/runtime com o contrato novo;
- regenerar o stress test com as assinaturas finais.
- adjust `audio` syscall signatures (including `ret_slots`);
- update registry/loader/runtime with the new contract;
- regenerate the stress test with the final signatures.
## Consequencias
## Consequences
### Positivas
### Positive
- reduz comportamento silencioso em erros operacionais de audio;
- torna chamadas de audio observaveis e testaveis;
- alinha `audio` com o modelo geral de `16a`.
- reduces silent behavior in audio operational errors;
- makes audio calls observable and testable;
- aligns `audio` with the general `16a` model.
### Custos
### Costs
- exige mudanca de ABI das syscalls de audio;
- exige atualizacao de testes e artefatos de stress.
- requires ABI changes to audio syscalls;
- requires updates to tests and stress artifacts.
## Follow-up Obrigatorio
## Required Follow-up
- agenda `005-audio-fault-semantics-and-surface.md` deve ser considerada absorvida e removida;
- specs `05` e `16a` devem absorver o contrato final quando a implementacao estiver estavel;
- registry de syscall deve refletir `ret_slots` e codigos de status finais para `audio`.
- agenda `005-audio-fault-semantics-and-surface.md` should be considered absorbed and removed;
- specs `05` and `16a` should absorb the final contract when implementation is stable;
- the syscall registry should reflect the final `ret_slots` and status codes for `audio`.

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

@ -13,30 +13,30 @@ Current normative anchors:
Accepted
## Contexto
## Context
Jogos precisam de persistencia previsivel e portavel para save/config/blob, sem acesso amplo ao filesystem.
Games need predictable, portable persistence for save/config/blob data without broad filesystem access.
A agenda `013-game-memcard-slots-surface-and-semantics.md` consolidou os inputs de produto:
Agenda `013-game-memcard-slots-surface-and-semantics.md` consolidated the product inputs:
- `game` usa `32` slots por jogo;
- payload maximo por slot de `32KB`;
- jogo acessa somente slots do proprio `app_id`;
- persistencia explicita com `commit` atomico por slot;
- copia/export/import de saves ocorre fora do jogo (Hub/OS).
- `game` uses `32` slots per game;
- maximum payload per slot is `32KB`;
- the game accesses only slots owned by its own `app_id`;
- persistence is explicit, with atomic `commit` per slot;
- save copy/export/import happens outside the game (Hub/OS).
Esta decisao fecha o contrato v1 do perfil `game` usando a decisao `003` como data plane de bytes.
This decision closes the v1 contract for the `game` profile while using decision `003` as the byte data plane.
## Decisao
## Decision
### 1. Contrato base de capacidade e ownership
### 1. Base capacity and ownership contract
- cada jogo possui exatamente `32` slots logicos (`0..31`);
- cada slot oferece payload util de ate `32 * 1024` bytes;
- acesso em userland e restrito ao `app_id` dono do cart carregado;
- nao existe acesso por path para jogos no v1.
- each game has exactly `32` logical slots (`0..31`);
- each slot offers up to `32 * 1024` bytes of usable payload;
- userland access is restricted to the `app_id` that owns the loaded cart;
- there is no path-based access for games in v1.
### 2. Surface minima de memcard (status-first)
### 2. Minimum memcard surface (status-first)
- `slot_count() -> (status:int, count:int)`
- `slot_stat(slot:int) -> (status:int, state:int, used_bytes:int, generation:int, checksum:int)`
@ -45,17 +45,17 @@ Esta decisao fecha o contrato v1 do perfil `game` usando a decisao `003` como da
- `slot_commit(slot:int) -> status:int`
- `slot_clear(slot:int) -> status:int`
Regras:
Rules:
- `status` e sempre o primeiro retorno;
- operacoes de bytes usam `HeapRef<Bytes>` + janela explicita (`offset`, `max_bytes`/`len`);
- shape segue politica de `16a`.
- `status` is always the first return value;
- byte operations use `HeapRef<Bytes>` plus an explicit window (`offset`, `max_bytes`/`len`);
- shape follows the policy in `16a`.
### 3. Envelope digital runtime-owned por slot
### 3. Runtime-owned digital envelope per slot
Cada slot mantem metadados canonicos runtime-owned:
Each slot keeps canonical runtime-owned metadata:
- `app_id` dono;
- owning `app_id`;
- `slot_index`;
- `save_uuid`;
- `generation`;
@ -63,36 +63,36 @@ Cada slot mantem metadados canonicos runtime-owned:
- `checksum`;
- `state` (`EMPTY`, `STAGED`, `COMMITTED`, `CORRUPT`).
`generation` e `checksum` nao sao controlados manualmente pela userland:
`generation` and `checksum` are not manually controlled by userland:
- `generation` incrementa a cada `slot_commit` bem-sucedido;
- `checksum` e recalculado pelo runtime no payload persistido.
- `generation` increments on each successful `slot_commit`;
- `checksum` is recalculated by the runtime on the persisted payload.
### 4. Envelope visual para Hub/OS
### 4. Visual envelope for Hub/OS
O slot expoe metadados visuais para UX fora do jogo:
The slot exposes visual metadata for UX outside the game:
- `label`;
- `subtitle`;
- `updated_at` (ou contador logico equivalente);
- `icon_ref` (v1 estatico, formato extensivel para animacao futura).
- `updated_at` (or equivalent logical counter);
- `icon_ref` (static in v1, extensible to future animation).
### 5. Politica de escrita e atomicidade
### 5. Write policy and atomicity
- `slot_write` altera staging (nao persiste no destino final);
- `slot_commit` aplica persistencia atomica por slot;
- sucesso parcial silencioso e proibido;
- em falha de commit, retorna `status` de erro e preserva invariante de atomicidade.
- `slot_write` changes staging (it does not persist to the final destination);
- `slot_commit` applies per-slot atomic persistence;
- silent partial success is forbidden;
- on commit failure, it returns error `status` and preserves the atomicity invariant.
### 6. Fronteira de fault class
### 6. Fault-class boundary
`memcard(game)` segue `16a`:
`memcard(game)` follows `16a`:
- `Trap`: erro estrutural (slot fora da faixa, `HeapRef` invalido/dead, janela invalida, shape ABI invalido);
- `status`: erro operacional de dominio;
- `Panic`: apenas quebra de invariante interna.
- `Trap`: structural error (slot out of range, invalid/dead `HeapRef`, invalid window, invalid ABI shape);
- `status`: operational domain error;
- `Panic`: internal invariant break only.
Catalogo minimo de status do dominio:
Minimum domain status catalog:
- `OK`;
- `EMPTY`;
@ -104,35 +104,35 @@ Catalogo minimo de status do dominio:
- `UNAVAILABLE`;
- `INVALID_STATE`.
### 7. Politica de copia/export/import (fora do jogo)
### 7. Copy/export/import policy (outside the game)
- copia/export/import e responsabilidade do Hub/OS;
- jogo nao recebe API para copiar slots entre apps;
- v1 valida ownership por `app_id` no import;
- conflito e corrupcao devem ser refletidos por status do dominio e UX do Hub.
- copy/export/import is a Hub/OS responsibility;
- the game does not receive an API to copy slots between apps;
- v1 validates ownership by `app_id` on import;
- conflict and corruption must be reflected through domain status and Hub UX.
### 8. Integracao com storage host
### 8. Integration with host storage
- namespace fisico isolado por `app_id`;
- representacao fisica por slot e interna ao runtime/host;
- persistencia deve usar estrategia atomica (arquivo temporario + flush + rename equivalente da plataforma).
- physical namespace isolated by `app_id`;
- physical per-slot representation is internal to the runtime/host;
- persistence should use an atomic strategy (temporary file + flush + platform-equivalent rename).
## Consequencias
## Consequences
### Positivas
### Positive
- fecha o contrato de save de `game` sem abrir FS amplo;
- torna copy/export/import um fluxo de sistema (Hub/OS), nao de userland;
- padroniza integridade/versionamento de slot com `generation` + `checksum`.
- closes the `game` save contract without opening broad FS access;
- makes copy/export/import a system flow (Hub/OS), not a userland flow;
- standardizes slot integrity/versioning through `generation` + `checksum`.
### Custos
### Costs
- exige implementacao de staging/commit atomico por slot;
- exige especificacao explicita do formato de export/import no Hub/OS;
- exige alinhamento com specs de memcard e ABI.
- requires per-slot staging/atomic commit implementation;
- requires explicit specification of the export/import format in Hub/OS;
- requires alignment with memcard and ABI specs.
## Follow-up Obrigatorio
## Required Follow-up
- a agenda `013-game-memcard-slots-surface-and-semantics.md` deve ser considerada fechada e removida;
- `specs/08-save-memory-and-memcard.md` deve absorver este contrato (`32 x 32KB`, slots por `app_id`, commit atomico);
- `specs/16-host-abi-and-syscalls.md` e `specs/16a-syscall-policies.md` devem absorver a surface e matriz de fault/status.
- agenda `013-game-memcard-slots-surface-and-semantics.md` should be considered closed and removed;
- `specs/08-save-memory-and-memcard.md` should absorb this contract (`32 x 32KB`, slots by `app_id`, atomic commit);
- `specs/16-host-abi-and-syscalls.md` and `specs/16a-syscall-policies.md` should absorb the surface and fault/status matrix.

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

@ -11,101 +11,101 @@ Current normative anchors:
Accepted
## Contexto
## Context
A agenda `004-gfx-fault-semantics-and-command-contract.md` consolidou que o dominio `gfx` estava com ambiguidade entre:
Agenda `004-gfx-fault-semantics-and-command-contract.md` consolidated that the `gfx` domain had ambiguity between:
- `Trap`/`Panic` desnecessarios para erro operacional;
- no-op silencioso;
- chamadas `void` em operacoes que podem falhar operacionalmente.
- unnecessary `Trap`/`Panic` for operational errors;
- silent no-op;
- `void` calls in operations that may fail operationally.
Para alinhar com `16a`, foi decidido fechar uma politica status-first no dominio `gfx`.
To align with `16a`, a status-first policy was adopted for the `gfx` domain.
## Decisao
## Decision
### 1. Fronteira de fault class em `gfx`
### 1. Fault-class boundary in `gfx`
`gfx` segue a taxonomia:
`gfx` follows this taxonomy:
- `Trap`: violacao estrutural de ABI/chamada (tipo, aridade, capability, shape).
- `status` (inteiro): erro operacional recuperavel de dominio.
- `Panic`: apenas quebra de invariante interna de runtime/host.
- `Trap`: structural ABI/call violation (type, arity, capability, shape).
- `status` (integer): recoverable operational domain error.
- `Panic`: internal runtime/host invariant break only.
### 2. Politica de retorno por operacao
### 2. Per-operation return policy
Nem toda syscall `gfx` precisa retornar `status`.
Not every `gfx` syscall needs to return `status`.
Regra canonica:
Canonical rule:
- se a operacao pode produzir erro operacional observavel, deve retornar `status: int` (`ret_slots >= 1`);
- se a operacao nao possui via real de erro operacional, pode permanecer `void`.
- if the operation can produce observable operational error, it should return `status: int` (`ret_slots >= 1`);
- if the operation has no real operational error path, it may remain `void`.
### 3. Tabela de status por operacao
### 3. Per-operation status table
Cada operacao `gfx` que retorna `status` deve declarar tabela de codigos inteiros propria.
Each `gfx` operation that returns `status` must declare its own integer code table.
A tabela deve cobrir, quando aplicavel:
The table should cover, when applicable:
- recurso ausente (`asset_not_found`);
- indice invalido (`invalid_sprite_index`);
- argumento fora de faixa (`invalid_arg_range`);
- sem efeito operacional (`no_effect`), quando houver.
- missing resource (`asset_not_found`);
- invalid index (`invalid_sprite_index`);
- out-of-range argument (`invalid_arg_range`);
- no operational effect (`no_effect`), when applicable.
### 4. Politica de no-op
### 4. No-op policy
No-op silencioso nao e permitido para operacoes com possibilidade de erro operacional.
Silent no-op is not allowed in operations that can fail operationally.
Quando houver falha/ignoracao operacional:
When there is operational failure/ignoring:
- a chamada deve retornar `status` explicito;
- o resultado nao pode ser mascarado como sucesso implicito.
- the call must return explicit `status`;
- the result must not be disguised as implicit success.
### 5. Contrato de `gfx.set_sprite`
### 5. `gfx.set_sprite` contract
`set_sprite` nao deve depender de fallback implicito para banco default.
`set_sprite` must not depend on implicit fallback to a default bank.
Casos como:
Cases such as:
- `asset_name` ausente/nao encontrado;
- `sprite_index` fora de faixa;
- `palette_id`/`priority` fora da faixa;
- missing/not-found `asset_name`;
- `sprite_index` out of range;
- `palette_id`/`priority` out of range;
devem ser reportados por `status` conforme a tabela da operacao.
must be reported via `status` according to the operation table.
### 6. Higiene de panic
### 6. Panic hygiene
Erros de argumento de app nao devem escalar para `Panic`.
App argument errors must not escalate to `Panic`.
Helpers e dispatch devem mapear esses casos para:
Helpers and dispatch must map those cases to:
- `Trap` (quando estrutural); ou
- `status` (quando operacional, para operacoes com retorno de status).
- `Trap` (when structural); or
- `status` (when operational, for operations with status return).
### 7. Compatibilidade e migracao
### 7. Compatibility and migration
Nao ha requisito de compatibilidade retroativa para esta mudanca.
There is no backward-compatibility requirement for this change.
E permitido:
It is allowed to:
- ajustar assinaturas de syscall `gfx` (especialmente `ret_slots`);
- atualizar registry/loader/runtime em linha com a matriz final;
- regenerar artefatos de stress test com o contrato novo.
- adjust `gfx` syscall signatures (especially `ret_slots`);
- update registry/loader/runtime in line with the final matrix;
- regenerate stress-test artifacts with the new contract.
## Consequencias
## Consequences
### Positivas
### Positive
- reduz `Trap`/`Panic` indevidos no dominio grafico;
- elimina comportamento silencioso em comandos com erro operacional;
- torna contratos de retorno mais consistentes e testaveis.
- reduces improper `Trap`/`Panic` in the graphics domain;
- eliminates silent behavior in commands with operational error;
- makes return contracts more consistent and testable.
### Custos
### Costs
- exige atualizacao de metadata de syscall e dispatch;
- exige atualizacao dos testes e do gerador de stress.
- requires updates to syscall metadata and dispatch;
- requires updates to tests and the stress generator.
## Follow-up Obrigatorio
## Required Follow-up
- agenda `004-gfx-fault-semantics-and-command-contract.md` deve ser considerada absorvida e removida;
- specs `04` e `16a` devem absorver o contrato final quando a implementacao estiver estavel;
- a matriz final por syscall (`void` vs `status`) e a tabela de codigos devem ser refletidas no registry de syscalls.
- agenda `004-gfx-fault-semantics-and-command-contract.md` should be considered absorbed and removed;
- specs `04` and `16a` should absorb the final contract when implementation is stable;
- the final per-syscall matrix (`void` vs `status`) and code table should be reflected in the syscall registry.

116
docs/runtime/learn/mental-model-asset-management.md Normal file
View File

@ -0,0 +1,116 @@
# Asset Management Mental Model
Status: pedagogical
Companion specs:
- [`../specs/13-cartridge.md`](../specs/13-cartridge.md)
- [`../specs/15-asset-management.md`](../specs/15-asset-management.md)
Origin decision: [`../decisions/011-assets-pa-autocontained-runtime-contract.md`](../decisions/011-assets-pa-autocontained-runtime-contract.md)
PROMETEU treats assets as a self-contained cart artifact, not as metadata scattered across `manifest.json`, the loader, and the runtime.
## One Runtime Artifact
The right mental model is:
- `manifest.json` identifies the cart and its capabilities;
- `assets.pa` carries the runtime-facing asset contract;
- the runtime consumes that contract without depending on auxiliary tooling artifacts.
That avoids mixing:
- cart editorial metadata;
- internal packer details;
- runtime loading policy.
## Why `assets.pa` Owns The Asset Contract
`assets.pa` puts into the same binary:
- a fixed prelude to locate the header;
- a JSON header that is easy to inspect;
- the cold binary payload of the assets.
That split exists to preserve two properties at the same time:
- fixed cost to open and validate the artifact;
- a readable header that is simple to debug.
The important point is not the format by itself. The important point is that the runtime finds everything it needs for assets behind one stable boundary.
## `preload` Is Not `asset_table`
Both live in the header, but they serve different roles:
- `asset_table` is the live asset-resolution index for the entire execution;
- `preload` is only a boot-time instruction for initial residency.
A short way to think about it:
- `asset_table` stays;
- `preload` passes.
That prevents the runtime from treating preload as permanent metadata when, in practice, it is only an initial loading impulse.
## Payload-Relative Thinking
`AssetEntry` offsets are relative to the start of the payload, not to the start of the whole file.
That choice preserves the semantics of the `asset` domain:
- `AssetEntry` describes where content sits inside the cold-byte region;
- the outer envelope can evolve without contaminating each entry with container details.
The runtime only needs to resolve:
```text
payload_base + entry.offset
```
## Slice-First Loading
The correct loading mental model is not:
```text
ROM -> load the whole assets.pa into RAM -> look up asset
```
The correct flow is:
```text
ROM -> open_slice -> CODEX/decode -> Bank
```
or, when the codec requires it:
```text
ROM -> open_slice -> temporary blob -> CODEX/decode -> Bank
```
That matters because PROMETEU was designed for low-cost hardware. Keeping the whole payload resident as a baseline wastes memory, couples IO to a monolithic blob, and weakens the runtime's real boundary.
## `OP_MODE` Belongs To The Runtime
The cart describes the asset. The runtime decides how to consume the slice.
In v1, that decision comes from the `codec`/CODEX:
- some assets can be read directly from the limited view;
- others require temporary materialization before decode.
The key point is to separate:
- the asset storage contract;
- the operational strategy for reading and decode.
## Why This Fits PROMETEU
This model fits the project well because:
- it reduces dependence on metadata scattered through `manifest.json`;
- it separates `packer`, `shipper`, and runtime more cleanly;
- it allows early failure when `Capability::Asset` requires `assets.pa`;
- it preserves a runtime that can run on desktop and on low-cost dedicated hardware.
When thinking about assets in PROMETEU, think less in terms of "a manifest with attachments" and more in terms of "a cart with an asset artifact that explains itself".

46
docs/runtime/learn/mental-model-audio.md
View File

@ -3,25 +3,25 @@
Status: pedagogical
Companion spec: [`../specs/05-audio-peripheral.md`](../specs/05-audio-peripheral.md)
O modelo mental correto para áudio em PROMETEU é o de um periférico ativo com orçamento, não o de “som automático”.
The right mental model for audio in PROMETEU is an active peripheral with a budget, not "automatic sound".
## Philosophy
Som:
Sound:
- consome tempo;
- consome memória;
- usa canais finitos;
- depende de comandos explícitos.
- consumes time;
- consumes memory;
- uses finite channels;
- depends on explicit commands.
Isso aproxima PROMETEU de consoles e arcades clássicos em que o jogo “conversa” com um bloco de áudio com regras próprias.
That brings PROMETEU closer to classic consoles and arcades where the game "talks" to an audio block with its own rules.
## Audio CPU Metaphor
Uma metáfora útil é pensar em:
A useful metaphor is:
```text
[Game CPU] -> envia comandos em 60 Hz -> [AUDIO Peripheral]
[Game CPU] -> sends commands at 60 Hz -> [AUDIO Peripheral]
|
v
Voices + Mixer
@ -30,26 +30,26 @@ Uma metáfora útil é pensar em:
PCM Output
```
Essa metáfora não exige um thread dedicado. Ela só separa responsabilidades:
This metaphor does not require a dedicated thread. It only separates responsibilities:
- a máquina define o modelo lógico;
- o host decide como entregar buffers contínuos;
- o jogo fala em comandos, não em manipulação direta do backend.
- the machine defines the logical model;
- the host decides how to deliver continuous buffers;
- the game speaks in commands, not direct backend manipulation.
## Good Habits
- reutilizar samples;
- limitar vozes simultâneas;
- tratar som como evento intencional;
- separar música e efeitos;
- evitar disparar o mesmo som todo frame.
- reuse samples;
- limit simultaneous voices;
- treat sound as an intentional event;
- separate music and effects;
- avoid triggering the same sound every frame.
## Historical Direction
As influências principais aqui são:
The main influences here are:
- NES, pela clareza de canais limitados;
- SNES, por playback de sample e mistura;
- CPS-2 e Neo Geo, pela sensação de folga e presença de sample playback.
- NES, for the clarity of limited channels;
- SNES, for sample playback and mixing;
- CPS-2 and Neo Geo, for the feeling of headroom and sample presence.
PROMETEU abstrai essas referências. Ele não tenta reproduzir nenhum desses sistemas literalmente.
PROMETEU abstracts those references. It does not try to reproduce any of those systems literally.

64
docs/runtime/learn/mental-model-gfx.md
View File

@ -3,63 +3,63 @@
Status: pedagogical
Companion spec: [`../specs/04-gfx-peripheral.md`](../specs/04-gfx-peripheral.md)
PROMETEU trata gráficos como um periférico explícito, não como uma GPU moderna.
PROMETEU treats graphics as an explicit peripheral, not as a modern GPU.
O modelo mental correto é o de uma máquina 2D retro com:
The right mental model is a retro 2D machine with:
- framebuffer;
- tile banks;
- tile layers;
- sprites por ordem de desenho;
- composição determinística por frame.
- deterministic composition per frame.
## Why This Exists
O objetivo não é imitar hardware histórico byte a byte. O objetivo é capturar a família de restrições e de linguagem visual de consoles como SNES, CPS-2 e Neo Geo, mas em um contrato pequeno, portátil e implementável em desktop e hardware DIY.
The goal is not to imitate historical hardware byte for byte. The goal is to capture the family of constraints and visual language of consoles such as SNES, CPS-2, and Neo Geo in a small, portable contract that can run on desktop and DIY hardware.
Isso produz algumas consequências importantes:
That produces some important consequences:
- desenho por ordem importa mais do que “efeitos”;
- paletas importam como parte do asset design;
- o programador pensa em rasterização, não em shaders;
- o custo visual fica mais observável.
- draw order matters more than "effects";
- palettes matter as part of asset design;
- the programmer thinks in terms of rasterization, not shaders;
- visual cost becomes more observable.
## What The GFX Is Not
PROMETEU GFX não é:
PROMETEU GFX is not:
- pipeline moderno de GPU;
- framebuffer RGBA com alpha arbitrário;
- sistema de shaders;
- composição automática pós-processada.
- a modern GPU pipeline;
- an RGBA framebuffer with arbitrary alpha;
- a shader system;
- automatic post-processed composition.
Essas ausências são deliberadas. Elas forçam uma linguagem visual mais próxima de console clássico e mantêm o contrato executável em ambientes modestos.
Those absences are deliberate. They force a visual language closer to classic consoles and keep the contract executable in modest environments.
## Practical Intuition
- Tile layers existem para mundo e cenário.
- HUD existe para informação fixa e deve permanecer desacoplado da câmera.
- Sprites existem para entidades móveis e sua profundidade depende da ordem e da prioridade.
- Paletas existem para variar estado visual sem duplicar tile art.
- Fade existe como efeito especial discreto, não como alpha genérico.
- Tile layers exist for world and scenery.
- HUD exists for fixed information and should remain decoupled from the camera.
- Sprites exist for moving entities, and their depth depends on order and priority.
- Palettes exist to vary visual state without duplicating tile art.
- Fade exists as a discrete special effect, not as generic alpha.
## Palette Thinking
Uma boa maneira de pensar PROMETEU é: arte e cor não são a mesma coisa.
A good way to think about PROMETEU is that art and color are not the same thing.
O tile é a forma. A paleta é o estado visual.
The tile is the shape. The palette is the visual state.
Isso habilita:
That enables:
- variação de inimigos;
- mudança de bioma;
- dano, gelo, veneno, power-up;
- temas de HUD;
- ciclos de dia e noite.
- enemy variation;
- biome changes;
- damage, ice, poison, power-up states;
- HUD themes;
- day and night cycles.
## Use Cases
- troca de área com `Scene Fade`;
- troca de HUD com `HUD Fade`;
- flash de dano ou teleporte;
- swap global de paleta para clima ou estado de mundo.
- area transition with `Scene Fade`;
- HUD transition with `HUD Fade`;
- damage flash or teleport flash;
- global palette swap for weather or world state.

42
docs/runtime/learn/mental-model-input.md
View File

@ -3,41 +3,41 @@
Status: pedagogical
Companion spec: [`../specs/06-input-peripheral.md`](../specs/06-input-peripheral.md)
PROMETEU trata input como estado amostrado, não como evento assíncrono.
PROMETEU treats input as sampled state, not as an asynchronous event.
## State Versus Event
O modelo mais importante para entender é:
The most important model to understand is:
- botão não “dispara” uma ação sozinho;
- botão muda de estado;
- o jogo consulta esse estado durante o frame.
- a button does not "fire" an action by itself;
- a button changes state;
- the game reads that state during the frame.
Isso se parece muito mais com polling de registrador em console clássico do que com callbacks de UI moderna.
That looks much more like classic console register polling than like modern UI callbacks.
## Why This Matters
Esse modelo:
This model:
- melhora determinismo;
- simplifica replay;
- facilita depuração;
- torna o frame loop mais legível.
- improves determinism;
- simplifies replay;
- makes debugging easier;
- makes the frame loop easier to read.
Também encaixa melhor na identidade de PROMETEU como máquina com forte inspiração em hardware retro e em construção DIY.
It also fits PROMETEU's identity better as a machine strongly inspired by retro hardware and DIY construction.
## Good Habits
- ler input em `UPDATE`;
- mapear ações, não teclas físicas;
- separar leitura de input de lógica pesada;
- tratar polling como parte do frame budget.
- read input in `UPDATE`;
- map actions, not physical keys;
- separate input reading from heavy logic;
- treat polling as part of the frame budget.
## Teaching Value
O periférico de input ajuda a ensinar:
The input peripheral helps teach:
- diferença entre estado e evento;
- amostragem temporal;
- sincronização entre input e lógica;
- determinismo em sistemas interativos.
- the difference between state and event;
- temporal sampling;
- synchronization between input and logic;
- determinism in interactive systems.

30
docs/runtime/learn/mental-model-observability-and-debugging.md
View File

@ -3,31 +3,31 @@
Status: pedagogical
Companion spec: [`../specs/10-debug-inspection-and-profiling.md`](../specs/10-debug-inspection-and-profiling.md)
PROMETEU foi desenhado para ser observável.
PROMETEU was designed to be observable.
## Debug Philosophy
Há três ideias centrais aqui:
There are three central ideas here:
1. estado vem antes de abstração;
2. tempo é cidadão de primeira classe;
3. observar não deve alterar o resultado lógico.
1. state comes before abstraction;
2. time is a first-class citizen;
3. observing must not alter the logical result.
Isso puxa o projeto para um estilo de depuração mais próximo de máquina e menos próximo de “tentativa e erro”.
That pushes the project toward a debugging style that is closer to machine reasoning and farther from "trial and error".
## Why This Matters
Quando a máquina expõe pilhas, heap, ciclos, buffers e faults de forma consistente, o programador consegue:
When the machine exposes stacks, heap, cycles, buffers, and faults consistently, the programmer can:
- localizar custo real;
- correlacionar tempo e memória;
- justificar decisão técnica;
- depurar sem inventar explicações mágicas.
- locate real cost;
- correlate time and memory;
- justify technical decisions;
- debug without inventing magical explanations.
## Teaching Value
Essa superfície didática existe porque PROMETEU quer ensinar também como sistemas são analisados:
This pedagogical surface exists because PROMETEU also wants to teach how systems are analyzed:
- debugging como observação informada;
- profiling como leitura de evidência;
- certification como relatório técnico reproduzível.
- debugging as informed observation;
- profiling as evidence reading;
- certification as a reproducible technical report.

50
docs/runtime/learn/mental-model-portability-and-cross-platform.md
View File

@ -3,50 +3,50 @@
Status: pedagogical
Companion spec: [`../specs/11-portability-and-cross-platform-execution.md`](../specs/11-portability-and-cross-platform-execution.md)
PROMETEU trata portabilidade como propriedade arquitetural da máquina, não como adaptação posterior.
PROMETEU treats portability as an architectural property of the machine, not as an after-the-fact adaptation.
## Core Idea
O ponto principal é simples:
The main point is simple:
- a máquina define a semântica;
- o host realiza apresentação e integração física;
- o cartridge não negocia comportamento com o sistema operacional.
- the machine defines the semantics;
- the host performs presentation and physical integration;
- the cartridge does not negotiate behavior with the operating system.
Isso evita a noção comum de que cada plataforma “tem sua versão” da lógica do jogo.
That avoids the common notion that each platform has "its own version" of game logic.
## Why This Matters
Quando tempo, memória, input, áudio e gráficos são definidos pela máquina, ficam mais fáceis:
When time, memory, input, audio, and graphics are defined by the machine, the following become easier:
- replay determinístico;
- certification reproduzível;
- execução em desktop, mobile e hardware DIY;
- separação limpa entre semântica e adaptação.
- deterministic replay;
- reproducible certification;
- execution on desktop, mobile, and DIY hardware;
- clean separation between semantics and adaptation.
## Practical Separation
Uma forma útil de pensar é:
A useful way to think about it is:
- cartridge carrega programa e assets;
- a VM/runtime executa a lógica;
- o host mostra pixels, entrega áudio e coleta input físico;
- o host não redefine as regras do jogo.
- the cartridge carries program and assets;
- the VM/runtime executes the logic;
- the host shows pixels, delivers audio, and collects physical input;
- the host does not redefine the game's rules.
## What Portability Does Not Mean
PROMETEU não promete:
PROMETEU does not promise:
- a mesma latência física;
- o mesmo consumo energético;
- o mesmo throughput bruto do host.
- the same physical latency;
- the same power consumption;
- the same raw host throughput.
Ele promete consistência lógica. Isso é o que importa para a identidade da máquina.
It promises logical consistency. That is what matters to the machine's identity.
## Teaching Value
Esse modelo ajuda a ensinar:
This model helps teach:
- diferença entre lógica e apresentação;
- por que engines modernas frequentemente perdem determinismo;
- como projetar software portátil sem depender de sorte.
- the difference between logic and presentation;
- why modern engines often lose determinism;
- how to design portable software without relying on luck.

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

@ -4,104 +4,104 @@ 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.
PROMETEU treats persistence as explicit hardware, not as invisible save behavior.
## Mental Model
O MEMCARD não é save state. Ele é um dispositivo de persistência controlado pelo jogo.
MEMCARD is not save state. It is a persistence device controlled by the game.
Isso implica:
That implies:
- tamanho conhecido;
- custo observável;
- necessidade de `commit()`;
- possibilidade de falha;
- formato de dados sob controle do jogo.
- known size;
- observable cost;
- the need for `commit()`;
- the possibility of failure;
- a data format under the game's control.
## Slot Thinking
O modelo certo nao e "o jogo salva arquivos". O modelo certo e "o jogo conversa com slots".
The right model is not "the game saves files". The right model is "the game talks to slots".
Isso muda o jeito de pensar persistencia:
That changes how you think about persistence:
- 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.
- capacity is finite and known;
- each slot has identity and state;
- ownership belongs to the cart's `app_id`;
- the game does not get broad access to the host filesystem.
Essa escolha existe para manter:
That choice exists to preserve:
- portabilidade;
- isolamento entre apps;
- UX previsivel de save;
- contrato executavel em desktop e hardware dedicado.
- portability;
- isolation between apps;
- predictable save UX;
- a contract that runs on desktop and dedicated hardware.
## Staged Versus Committed
Uma intuicao importante em MEMCARD e a diferenca entre:
An important MEMCARD intuition is the difference between:
- mexer no conteudo em staging;
- tornar a escrita persistida de fato.
- changing content in staging;
- making the write actually persistent.
`commit()` existe para separar essas duas fases.
Isso ensina um modelo de persistencia mais honesto:
That teaches a more honest model of persistence:
- escrever ainda nao e persistir;
- persistir tem custo;
- persistir pode falhar;
- atomicidade importa.
- writing is not yet persisting;
- persisting has a cost;
- persisting can fail;
- atomicity matters.
## Why Explicit Commit Matters
O `commit()` existe para tornar persistência uma decisão técnica visível.
`commit()` exists to make persistence a visible technical decision.
Sem ele, não há ilusão de que “salvar simplesmente aconteceu”. O jogo precisa assumir quando quer:
Without it, there is no illusion that "saving simply happened". The game must decide when it wants to:
- materializar escrita;
- aceitar custo;
- lidar com risco de perda ou corrupção.
- materialize a write;
- accept the cost;
- deal with the risk of loss or corruption.
## Runtime-Owned Metadata
Mesmo quando o payload pertence ao jogo, alguns aspectos do slot pertencem a maquina:
Even when the payload belongs to the game, some aspects of the slot belong to the machine:
- integridade;
- geracao/versionamento;
- estado do slot;
- isolamento por ownership.
- integrity;
- generation/versioning;
- slot state;
- ownership isolation.
Isso evita que cada jogo reinvente sua propria semantica basica de persistencia e permite que tooling e Hub/OS apresentem save de forma coerente.
That prevents each game from reinventing its own basic persistence semantics and lets tooling and Hub/OS present save data coherently.
## Hub/OS Role
PROMETEU separa claramente:
PROMETEU separates clearly:
- o jogo grava e le seus slots;
- o Hub/OS faz export, import, copia e apresentacao de saves.
- the game writes and reads its own slots;
- the Hub/OS handles export, import, copy, and save presentation.
Essa separacao impede que userland vire um mini-gerenciador de arquivos e mantem as operacoes de sistema na camada certa.
That separation prevents userland from becoming a mini file manager and keeps system operations in the right layer.
## Tooling Surface
Ferramentas externas podem expor utilidades como:
External tools may expose utilities such as:
- criar ou resetar MEMCARD;
- importar e exportar `.mem`;
- inspecionar tamanho e uso;
- associar cartões a projetos.
- create or reset MEMCARD;
- import and export `.mem`;
- inspect size and usage;
- associate cards with projects.
Essas superfícies são auxiliares. Elas não mudam o contrato da máquina.
Those surfaces are auxiliary. They do not change the machine contract.
## Why This Is Better Than Broad FS For Games
Para perfil `game`, o modelo de slot e melhor que abrir um filesystem geral porque:
For the `game` profile, the slot model is better than exposing a broad filesystem because:
- 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.
- it reduces ambiguity around path, permission, and ownership;
- it makes controlled import/export easier;
- it improves compatibility across hosts;
- it makes it clearer what a "valid save" means to the machine.
## 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.
This model fits well with the project's console heritage and DIY focus: persistence is part of the machine design, not convenience hidden inside the host.

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

@ -9,117 +9,117 @@ Companion specs:
- [`../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.
PROMETEU uses a status-first model so the host/runtime boundary does not hide operational errors as silence, improper `Trap`, or accidental `Panic`.
## Core Split
O modelo mental certo e:
The right mental model is:
- `Trap` para violacao estrutural de contrato;
- `status` para resultado operacional observavel;
- `Panic` para quebra de invariante interna.
- `Trap` for structural contract violations;
- `status` for observable operational results;
- `Panic` for internal invariant breaks.
Uma forma curta de pensar:
A short way to think about it:
- guest chamou errado: `Trap`;
- guest chamou certo, mas o dominio nao conseguiu concluir: `status`;
- runtime quebrou por dentro: `Panic`.
- the guest called it wrong: `Trap`;
- the guest called it correctly, but the domain could not complete it: `status`;
- the runtime broke internally: `Panic`.
## Why This Exists
Sem essa separacao, sistemas host-backed tendem a degradar para uma mistura ruim de:
Without that separation, host-backed systems tend to degrade into a bad mix of:
- `void` em operacoes que falham de verdade;
- fallback implicito;
- no-op silencioso;
- escalacao de erro de app para `Panic`.
- `void` in operations that can really fail;
- implicit fallback;
- silent no-op;
- escalation of app errors into `Panic`.
Status-first existe para tornar o comportamento:
Status-first exists to make behavior:
- observavel;
- deterministico;
- testavel;
- documentavel por dominio.
- observable;
- deterministic;
- testable;
- documentable per domain.
## Return Shape Rule
A regra pratica mais importante e simples:
The most important practical rule is simple:
- se a operacao pode falhar operacionalmente, ela deve retornar `status`;
- se a operacao nao tem caminho real de falha operacional, ela pode ser `void`.
- if the operation can fail operationally, it should return `status`;
- if the operation has no real operational failure path, it may be `void`.
Isso impede contratos em que o guest nao consegue distinguir:
That prevents contracts in which the guest cannot distinguish:
- sucesso;
- rejeicao;
- ausencia de efeito;
- backend indisponivel;
- asset ou recurso ausente.
- success;
- rejection;
- absence of effect;
- backend unavailable;
- missing asset or resource.
## Silent Failure Is Not Allowed
Em PROMETEU, erro operacional nao pode ser maquiado como:
In PROMETEU, an operational error cannot be disguised as:
- sucesso implicito;
- ignorar a chamada;
- fallback automatico para outro recurso;
- `Trap`, quando o problema nao e estrutural;
- `Panic`, quando o problema nao e interno.
- implicit success;
- ignoring the call;
- automatic fallback to another resource;
- `Trap`, when the problem is not structural;
- `Panic`, when the problem is not internal.
Se o guest pode perceber a diferenca, essa diferenca deve aparecer como `status`.
If the guest can perceive the difference, that difference should appear as `status`.
## Reading The Boundary
Quando estiver lendo ou desenhando uma syscall, use esta sequencia:
When reading or designing a syscall, use this sequence:
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?
1. Is the call structurally correct?
2. Does the guest have permission/capability to use the surface?
3. Can the domain execute the operation with the current resources?
4. Is there additional payload that only makes sense when `status` indicates success?
Essa leitura tende a produzir contratos mais limpos, por exemplo:
That reading tends to produce cleaner contracts, for example:
- `asset.load(...) -> (status, handle)`
- `mem.slot_read(...) -> (status, payload, bytes_read)`
- operacoes sem falha real continuam `void`
- operations without a real failure path remain `void`
## Domain Intuition
### GFX
Em `gfx`, o problema tipico nao e "a syscall explodiu". O problema tipico e:
In `gfx`, the typical problem is not "the syscall exploded". The typical problem is:
- sprite inexistente;
- indice fora da faixa operacional;
- argumento invalido para a operacao;
- chamada sem efeito real.
- missing sprite;
- index outside the operational range;
- invalid argument for the operation;
- a call with no real effect.
Esses casos pedem `status`, nao silencio.
Those cases call for `status`, not silence.
### Audio
Em `audio`, o modelo impede coisas como:
In `audio`, the model prevents things like:
- voz invalida ser ignorada;
- sample ausente virar fallback mudo;
- parametro fora de faixa parecer sucesso.
- an invalid voice being ignored;
- a missing sample turning into silent fallback;
- an out-of-range parameter looking like success.
Audio deve se comportar como periferico finito e explicito, nao como "som automatico".
Audio should behave like a finite, explicit peripheral, not like "automatic sound".
### Asset
Em `asset`, status-first separa melhor:
In `asset`, status-first better separates:
- erro de request;
- lifecycle assíncrono;
- commit/cancel invalido;
- handle desconhecido.
- request errors;
- asynchronous lifecycle;
- invalid commit/cancel;
- unknown handle.
Isso combina com o modelo de request + poll + commit, em vez de fingir que carregamento e instantaneo.
That fits the request + poll + commit model instead of pretending loading is instantaneous.
### FS / MEMCARD
Em persistencia, status-first impede a pior categoria de erro: "pareceu salvar".
In persistence, status-first prevents the worst category of error: "it seemed to save".
Casos como:
@ -129,22 +129,22 @@ Casos como:
- corrupcao;
- backend indisponivel;
precisam aparecer como estado observavel, porque o jogo e o Hub/OS precisam reagir a isso.
must appear as observable state because the game and the Hub/OS need to react to them.
## Design Smells
Sinais de que o contrato ainda esta ruim:
Signs that the contract is still weak:
- 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.
- the operation can fail, but returns `void`;
- there is implicit fallback to a default resource;
- the documentation depends on "in practice this should not happen";
- `Panic` appears for app input errors;
- the same domain mixes silent no-op and explicit status;
- return payload does not make clear when it is valid.
## Historical Anchors
Este guia consolida a intuicao que apareceu primeiro nestes snapshots historicos:
This guide consolidates the intuition that first appeared in these historical snapshots:
- [`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)
@ -152,4 +152,4 @@ Este guia consolida a intuicao que apareceu primeiro nestes snapshots historicos
- [`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.
Use the snapshots for historical context. Use the specs for the current normative contract.

48
docs/runtime/learn/mental-model-time-and-cycles.md
View File

@ -3,48 +3,48 @@
Status: pedagogical
Companion spec: [`../specs/01-time-model-and-cycles.md`](../specs/01-time-model-and-cycles.md)
PROMETEU trata tempo como parte explícita da máquina.
PROMETEU treats time as an explicit part of the machine.
## Core Idea
Nada acontece “de graça” ou “instantaneamente”. O programador deve pensar em:
Nothing happens "for free" or "instantly". The programmer should think in terms of:
- ritmo da máquina;
- custo por frame;
- distribuição de trabalho ao longo do tempo;
- impacto arquitetural de quando cada sistema roda.
- machine rhythm;
- cost per frame;
- distribution of work over time;
- the architectural impact of when each system runs.
## Why Cycles Instead of Milliseconds
Milissegundos variam com plataforma, jitter e hardware real. Cycles dão uma métrica de custo que pertence à máquina PROMETEU, não ao host.
Milliseconds vary with platform, jitter, and real hardware. Cycles provide a cost metric that belongs to the PROMETEU machine rather than to the host.
Isso torna mais fácil comparar soluções, ensinar custo e raciocinar sobre performance sem esconder a conta atrás do sistema operacional.
That makes it easier to compare solutions, teach cost, and reason about performance without hiding the bill behind the operating system.
## Temporal Distribution As Design
Uma das intuições mais importantes em PROMETEU é: otimização não é só “fazer menos”, é decidir **quando** fazer.
One of the most important intuitions in PROMETEU is that optimization is not only about "doing less", it is about deciding **when** to do it.
Exemplos úteis:
Useful examples:
- IA em 30 Hz;
- pathfinding em 15 Hz;
- timers dirigidos por frame count;
- separação entre atualização pesada e apresentação.
- AI at 30 Hz;
- pathfinding at 15 Hz;
- frame-count-driven timers;
- separation between heavy update work and presentation.
## Why CAP Fits Here
O CAP reforça essa leitura de tempo como evidência técnica. Ele não existe para bloquear execução, e sim para tornar visíveis:
CAP reinforces this reading of time as technical evidence. It does not exist to block execution, but to make visible:
- picos;
- gargalos;
- distribuição de custo;
- decisões de arquitetura temporal.
- spikes;
- bottlenecks;
- cost distribution;
- temporal architecture decisions.
## Teaching Value
Esse modelo ajuda a ensinar:
This model helps teach:
- planejamento de execução;
- trade-offs técnicos;
- leitura de perfil real;
- organização temporal como ferramenta arquitetural.
- execution planning;
- technical tradeoffs;
- reading real profiling evidence;
- temporal organization as an architectural tool.

34
docs/runtime/learn/mental-model-touch.md
View File

@ -3,38 +3,38 @@
Status: pedagogical
Companion spec: [`../specs/07-touch-peripheral.md`](../specs/07-touch-peripheral.md)
PROMETEU usa TOUCH como um ponteiro absoluto e determinístico, não como uma superfície rica em gestos.
PROMETEU uses TOUCH as an absolute, deterministic pointer, not as a gesture-rich surface.
## Design Intuition
O princípio central é simples:
The central principle is simple:
- um único ponteiro ativo;
- sem gestos implícitos;
- sem aceleração;
- sem heurística;
- mesmo comportamento em desktop, mobile e hardware dedicado.
- a single active pointer;
- no implicit gestures;
- no acceleration;
- no heuristics;
- the same behavior on desktop, mobile, and dedicated hardware.
Se o comportamento não puder ser garantido de forma portátil, ele não entra na máquina.
If a behavior cannot be guaranteed portably, it does not enter the machine.
## Why Single Pointer
Multitouch físico pode existir no host, mas a máquina escolhe um único ponteiro lógico para evitar:
Physical multitouch may exist on the host, but the machine chooses a single logical pointer to avoid:
- ambiguidades de captura;
- diferenças entre plataformas;
- mudanças semânticas entre mouse, touch real e touchscreen embutido.
- capture ambiguities;
- differences between platforms;
- semantic shifts between mouse, real touch, and built-in touchscreen.
## Good Uses
TOUCH funciona bem para:
TOUCH works well for:
- UI;
- seleção direta;
- direct selection;
- drag-and-drop;
- puzzles de apontamento;
- trilhas, cortes e mecânicas baseadas em contato.
- pointing puzzles;
- trails, cuts, and contact-based mechanics.
## What Games Must Do Themselves
Se um jogo quiser gesto, swipe, long-press ou smoothing, ele deve construir isso por cima do estado bruto por frame. O periférico não interpreta intenção.
If a game wants gestures, swipe, long-press, or smoothing, it must build that on top of the raw per-frame state. The peripheral does not interpret intent.

94
docs/runtime/specs/README.md
View File

@ -1,41 +1,41 @@
# PROMETEU Machine Specs
Este diretório reúne as specs técnicas da máquina PROMETEU.
This directory contains the technical specs for the PROMETEU machine.
PROMETEU é uma fantasy handheld / fantasy console. A VM é apenas um subsistema dessa máquina. Por isso, esta superfície documental cobre mais do que bytecode e runtime: ela cobre tempo, hardware virtual, firmware, cartridge, assets e ABI com o host.
PROMETEU is a fantasy handheld / fantasy console. The VM is only one subsystem of that machine. Because of that, this documentation surface covers more than bytecode and runtime: it covers timing, virtual hardware, firmware, cartridge packaging, assets, and the host ABI.
A organização aqui é intencionalmente plana. A taxonomia é conceitual, não estrutural.
The organization here is intentionally flat. The taxonomy is conceptual, not structural.
## Scope Boundary
Pertence a `docs/runtime/specs/`:
Belongs in `docs/runtime/specs/`:
- contrato técnico da máquina PROMETEU;
- hardware virtual e seus periféricos;
- envelope de firmware e boot;
- cartridge, assets e superfícies de carga;
- ABI da VM com o host.
- the technical contract of the PROMETEU machine;
- virtual hardware and its peripherals;
- the firmware and boot envelope;
- cartridge, asset, and load surfaces;
- the VM-to-host ABI.
Não pertence a `docs/runtime/specs/` como fonte canônica principal:
Does not belong in `docs/runtime/specs/` as the primary canonical source:
- invariantes arquiteturais internas da VM/runtime:
- internal architectural invariants of the VM/runtime:
[`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md);
- ISA em nível de bytecode:
- bytecode-level ISA:
[`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md);
- guias didáticos e material de aprendizagem:
- pedagogical guides and learning material:
[`../learn/README.md`](../learn/README.md);
- agendas, propostas e planos:
`docs/runtime/agendas/` e `docs/runtime/pull-requests/`.
- agendas, proposals, and plans:
`docs/runtime/agendas/` and `docs/runtime/pull-requests/`.
## Organization Rules
- estrutura plana;
- sem pasta `topics/`;
- sem navegação embutida `Back` / `Next` / `Summary`;
- nomes de arquivos semânticos;
- cada capítulo deve poder ser aberto isoladamente;
- cada capítulo deve declarar seu domínio e sua função documental no topo do arquivo;
- a taxonomia deve viver no `README`, não em uma árvore de diretórios artificial.
- flat structure;
- no `topics/` folder;
- no embedded `Back` / `Next` / `Summary` navigation;
- semantic filenames;
- each chapter must stand on its own;
- each chapter must declare its domain and documentary function at the top of the file;
- taxonomy should live in the `README`, not in an artificial directory tree.
## Taxonomy
@ -48,16 +48,16 @@ Não pertence a `docs/runtime/specs/` como fonte canônica principal:
| `12` and `14` | firmware and boot orchestration |
| `13` and `15` | cartridge package and asset surface |
Hardware, aqui, não é um saco genérico para tudo. No pacote atual, “hardware” significa os periféricos virtuais da máquina: GFX, AUDIO, INPUT, TOUCH e MEMCARD/save memory. VM, firmware, cartridge e ABI ficam em categorias irmãs, não dentro da categoria de hardware.
Here, hardware is not a generic bucket for everything. In the current package, "hardware" means the machine's virtual peripherals: GFX, AUDIO, INPUT, TOUCH, and MEMCARD/save memory. VM, firmware, cartridge, and ABI sit in sibling categories rather than inside hardware.
## Document Functions
- `normative`: define contrato técnico, comportamento esperado ou superfície compatível com implementação.
- `mixed (normative + explanatory)`: contém contrato técnico, mas preserva framing didático para explicar o modelo da máquina.
- `historical`: material arquivado; não é autoridade para implementação nova.
- `pedagogical`: material de ensino; não define sozinho contrato técnico.
- `normative`: defines the technical contract, expected behavior, or implementation-facing surface.
- `mixed (normative + explanatory)`: contains technical contract material but preserves explanatory framing to clarify the machine model.
- `historical`: archived material; not the authority for new implementation work.
- `pedagogical`: teaching material; does not define the technical contract on its own.
No estado atual, nenhum capítulo sob a raiz ativa de `docs/runtime/specs/` é `historical` puro. Se material histórico surgir, ele não deve competir com a superfície normativa principal.
In the current state, no chapter under the active `docs/runtime/specs/` root is purely `historical`. If historical material appears, it must not compete with the primary normative surface.
## Current Chapter Map
@ -86,31 +86,31 @@ No estado atual, nenhum capítulo sob a raiz ativa de `docs/runtime/specs/` é `
## Authority Model
- `docs/runtime/specs/` define a máquina PROMETEU e suas superfícies externas de execução.
- [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md) continua sendo a autoridade canônica das invariantes internas da VM/runtime.
- [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md) continua sendo a autoridade para a ISA de bytecode.
- Quando um capítulo daqui tocar a VM, ele pode complementar, mas não contradizer, a arquitetura canônica da VM/runtime.
- `docs/runtime/specs/` defines the PROMETEU machine and its external execution surfaces.
- [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
- [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md) remains the authority for the bytecode ISA.
- When a chapter here touches the VM, it may complement but must not contradict the canonical VM/runtime architecture.
## Rules for Future Chapters
- o nome do arquivo deve comunicar o domínio;
- o capítulo deve declarar `Domain` e `Function` no topo;
- capítulos sobre hardware devem tratar de periféricos ou superfícies de máquina observáveis, não de qualquer tema técnico solto;
- capítulos históricos ou puramente pedagógicos não devem disputar autoridade com capítulos normativos;
- links internos devem agregar contexto real, não servir como navegação obrigatória.
- the filename should communicate the domain;
- the chapter should declare `Domain` and `Function` at the top;
- hardware chapters should cover peripherals or observable machine surfaces, not arbitrary technical topics;
- historical or purely pedagogical chapters must not compete with normative chapters for authority;
- internal links should add real context rather than act as mandatory navigation.
## Pairing Rule
Um tema deve nascer como par `spec` + `learn` quando:
A topic should be created as a `spec` + `learn` pair when:
- o contrato normativo é importante, mas o modelo mental também é;
- o texto precisa de contexto histórico, comparação com hardware clássico ou design rationale extenso;
- o material didático ameaça inflar ou confundir o capítulo normativo;
- o assunto serve tanto como superfície técnica quanto como ferramenta de ensino.
- the normative contract matters, but the mental model matters too;
- the text needs historical context, comparison with classic hardware, or extensive design rationale;
- the pedagogical material risks bloating or confusing the normative chapter;
- the subject serves both as a technical surface and as a teaching tool.
Nesses casos:
In those cases:
- `docs/runtime/specs/` define o contrato;
- `docs/runtime/learn/` explica o porquê, a intuição e os exemplos;
- o spec deve apontar para o companion didático no topo;
- o guia didático deve apontar de volta para o spec canônico.
- `docs/runtime/specs/` defines the contract;
- `docs/runtime/learn/` explains the why, the intuition, and the examples;
- the spec should point to the pedagogical companion near the top;
- the pedagogical guide should point back to the canonical spec.