From d7c970a3e2b6e6113ad44b535a9507481bd4abdb Mon Sep 17 00:00:00 2001 From: bQUARKz Date: Wed, 11 Mar 2026 07:26:05 +0000 Subject: [PATCH] clean up --- AGENTS.md | 7 + docs/runtime/learn/README.md | 55 +++---- ...-status-first-fault-and-return-contract.md | 108 +++++++------- ...-status-first-fault-and-return-contract.md | 116 +++++++-------- ...ame-memcard-slots-surface-and-semantics.md | 126 ++++++++-------- ...-status-first-fault-and-return-contract.md | 118 +++++++-------- .../learn/mental-model-asset-management.md | 116 +++++++++++++++ docs/runtime/learn/mental-model-audio.md | 46 +++--- docs/runtime/learn/mental-model-gfx.md | 64 ++++---- docs/runtime/learn/mental-model-input.md | 42 +++--- ...ental-model-observability-and-debugging.md | 30 ++-- ...al-model-portability-and-cross-platform.md | 50 +++---- .../mental-model-save-memory-and-memcard.md | 108 +++++++------- ...l-model-status-first-and-fault-thinking.md | 140 +++++++++--------- .../learn/mental-model-time-and-cycles.md | 48 +++--- docs/runtime/learn/mental-model-touch.md | 34 ++--- docs/runtime/specs/README.md | 94 ++++++------ 17 files changed, 713 insertions(+), 589 deletions(-) create mode 100644 docs/runtime/learn/mental-model-asset-management.md diff --git a/AGENTS.md b/AGENTS.md index 4a3304c7..a781f661 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/docs/runtime/learn/README.md b/docs/runtime/learn/README.md index ea5b7a96..dc84c29b 100644 --- a/docs/runtime/learn/README.md +++ b/docs/runtime/learn/README.md @@ -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. diff --git a/docs/runtime/learn/historical-asset-status-first-fault-and-return-contract.md b/docs/runtime/learn/historical-asset-status-first-fault-and-return-contract.md index bbee140e..6c82f848 100644 --- a/docs/runtime/learn/historical-asset-status-first-fault-and-return-contract.md +++ b/docs/runtime/learn/historical-asset-status-first-fault-and-return-contract.md @@ -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`. diff --git a/docs/runtime/learn/historical-audio-status-first-fault-and-return-contract.md b/docs/runtime/learn/historical-audio-status-first-fault-and-return-contract.md index dda488b5..3b7289d7 100644 --- a/docs/runtime/learn/historical-audio-status-first-fault-and-return-contract.md +++ b/docs/runtime/learn/historical-audio-status-first-fault-and-return-contract.md @@ -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`. diff --git a/docs/runtime/learn/historical-game-memcard-slots-surface-and-semantics.md b/docs/runtime/learn/historical-game-memcard-slots-surface-and-semantics.md index b36d7f3a..009cb8b7 100644 --- a/docs/runtime/learn/historical-game-memcard-slots-surface-and-semantics.md +++ b/docs/runtime/learn/historical-game-memcard-slots-surface-and-semantics.md @@ -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` + janela explicita (`offset`, `max_bytes`/`len`); -- shape segue politica de `16a`. +- `status` is always the first return value; +- byte operations use `HeapRef` 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. diff --git a/docs/runtime/learn/historical-gfx-status-first-fault-and-return-contract.md b/docs/runtime/learn/historical-gfx-status-first-fault-and-return-contract.md index a673752d..8385d160 100644 --- a/docs/runtime/learn/historical-gfx-status-first-fault-and-return-contract.md +++ b/docs/runtime/learn/historical-gfx-status-first-fault-and-return-contract.md @@ -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. diff --git a/docs/runtime/learn/mental-model-asset-management.md b/docs/runtime/learn/mental-model-asset-management.md new file mode 100644 index 00000000..1828520d --- /dev/null +++ b/docs/runtime/learn/mental-model-asset-management.md @@ -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". diff --git a/docs/runtime/learn/mental-model-audio.md b/docs/runtime/learn/mental-model-audio.md index ab53bff9..f2d69bbd 100644 --- a/docs/runtime/learn/mental-model-audio.md +++ b/docs/runtime/learn/mental-model-audio.md @@ -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. diff --git a/docs/runtime/learn/mental-model-gfx.md b/docs/runtime/learn/mental-model-gfx.md index 0bcc4e73..5f20a217 100644 --- a/docs/runtime/learn/mental-model-gfx.md +++ b/docs/runtime/learn/mental-model-gfx.md @@ -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. diff --git a/docs/runtime/learn/mental-model-input.md b/docs/runtime/learn/mental-model-input.md index be05ec52..18270ca5 100644 --- a/docs/runtime/learn/mental-model-input.md +++ b/docs/runtime/learn/mental-model-input.md @@ -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. diff --git a/docs/runtime/learn/mental-model-observability-and-debugging.md b/docs/runtime/learn/mental-model-observability-and-debugging.md index 0973a0c6..e0d164d6 100644 --- a/docs/runtime/learn/mental-model-observability-and-debugging.md +++ b/docs/runtime/learn/mental-model-observability-and-debugging.md @@ -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. diff --git a/docs/runtime/learn/mental-model-portability-and-cross-platform.md b/docs/runtime/learn/mental-model-portability-and-cross-platform.md index 8507a43b..a472bdff 100644 --- a/docs/runtime/learn/mental-model-portability-and-cross-platform.md +++ b/docs/runtime/learn/mental-model-portability-and-cross-platform.md @@ -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. diff --git a/docs/runtime/learn/mental-model-save-memory-and-memcard.md b/docs/runtime/learn/mental-model-save-memory-and-memcard.md index 73479e54..3818a0ba 100644 --- a/docs/runtime/learn/mental-model-save-memory-and-memcard.md +++ b/docs/runtime/learn/mental-model-save-memory-and-memcard.md @@ -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. diff --git a/docs/runtime/learn/mental-model-status-first-and-fault-thinking.md b/docs/runtime/learn/mental-model-status-first-and-fault-thinking.md index 6b68904d..932606f9 100644 --- a/docs/runtime/learn/mental-model-status-first-and-fault-thinking.md +++ b/docs/runtime/learn/mental-model-status-first-and-fault-thinking.md @@ -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. diff --git a/docs/runtime/learn/mental-model-time-and-cycles.md b/docs/runtime/learn/mental-model-time-and-cycles.md index 55078c81..8ce5eee0 100644 --- a/docs/runtime/learn/mental-model-time-and-cycles.md +++ b/docs/runtime/learn/mental-model-time-and-cycles.md @@ -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. diff --git a/docs/runtime/learn/mental-model-touch.md b/docs/runtime/learn/mental-model-touch.md index 4a5bb629..bd29445d 100644 --- a/docs/runtime/learn/mental-model-touch.md +++ b/docs/runtime/learn/mental-model-touch.md @@ -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. diff --git a/docs/runtime/specs/README.md b/docs/runtime/specs/README.md index cd6b981a..aeb31f5e 100644 --- a/docs/runtime/specs/README.md +++ b/docs/runtime/specs/README.md @@ -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.