prometeu-runtime/docs/runtime/specs/README.md

# PROMETEU Machine Specs

Este diretório reúne as specs técnicas da máquina PROMETEU.

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.

A organização aqui é intencionalmente plana. A taxonomia é conceitual, não estrutural.

## Scope Boundary

Pertence a `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.

Não pertence a `docs/runtime/specs/` como fonte canônica principal:

- invariantes arquiteturais internas da VM/runtime:
  [`../virtual-machine/ARCHITECTURE.md`](../virtual-machine/ARCHITECTURE.md);
- ISA em nível de bytecode:
  [`../virtual-machine/ISA_CORE.md`](../virtual-machine/ISA_CORE.md);
- guias didáticos e material de aprendizagem:
  [`../learn/README.md`](../learn/README.md);
- agendas, propostas e planos:
  `docs/runtime/agendas/` e `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.

## Taxonomy

| Range | Domain |
| --- | --- |
| `01` | machine timing and cycle budget |
| `02` to `03`, `09a`, `16` to `16a` | VM subsystem and host ABI |
| `04` to `08` | virtual hardware peripherals |
| `09` to `11` | machine execution envelope, diagnostics, and portability |
| `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.

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

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.

## Current Chapter Map

| File | Domain | Function |
| --- | --- | --- |
| [`01-time-model-and-cycles.md`](01-time-model-and-cycles.md) | machine timing and cycles | normative |
| [`02-vm-instruction-set.md`](02-vm-instruction-set.md) | VM subsystem overview | normative |
| [`02a-vm-values-and-calling-convention.md`](02a-vm-values-and-calling-convention.md) | VM values and calling convention | normative |
| [`02b-vm-function-values-and-closures.md`](02b-vm-function-values-and-closures.md) | VM closures and function values | normative |
| [`03-memory-stack-heap-and-allocation.md`](03-memory-stack-heap-and-allocation.md) | VM memory model | normative |
| [`04-gfx-peripheral.md`](04-gfx-peripheral.md) | virtual hardware: graphics | normative |
| [`05-audio-peripheral.md`](05-audio-peripheral.md) | virtual hardware: audio | normative |
| [`06-input-peripheral.md`](06-input-peripheral.md) | virtual hardware: input | normative |
| [`07-touch-peripheral.md`](07-touch-peripheral.md) | virtual hardware: touch | normative |
| [`08-save-memory-and-memcard.md`](08-save-memory-and-memcard.md) | virtual hardware: save memory | normative |
| [`09-events-and-concurrency.md`](09-events-and-concurrency.md) | machine events and frame scheduling | normative |
| [`09a-coroutines-and-cooperative-scheduling.md`](09a-coroutines-and-cooperative-scheduling.md) | VM coroutine model | normative |
| [`10-debug-inspection-and-profiling.md`](10-debug-inspection-and-profiling.md) | machine diagnostics | normative |
| [`11-portability-and-cross-platform-execution.md`](11-portability-and-cross-platform-execution.md) | portability contract | normative |
| [`12-firmware-pos-and-prometeuhub.md`](12-firmware-pos-and-prometeuhub.md) | firmware and system orchestration | normative |
| [`13-cartridge.md`](13-cartridge.md) | cartridge package | normative |
| [`14-boot-profiles.md`](14-boot-profiles.md) | firmware boot flow | normative |
| [`15-asset-management.md`](15-asset-management.md) | asset runtime surface | normative |
| [`16-host-abi-and-syscalls.md`](16-host-abi-and-syscalls.md) | host ABI structure | normative |
| [`16a-syscall-policies.md`](16a-syscall-policies.md) | host ABI operational policy | normative |

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

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

## Pairing Rule

Um tema deve nascer como par `spec` + `learn` quando:

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

Nesses casos:

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