This commit is contained in:
2026-03-24 13:40:54 +00:00
parent f3f689fbef
commit d7c970a3e2
17 changed files with 713 additions and 589 deletions
+47 -47
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.