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;
ISA em nível de bytecode: ../virtual-machine/ISA_CORE.md;
guias didáticos e material de aprendizagem: ../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`	machine timing and cycles	normative
`02-vm-instruction-set.md`	VM subsystem overview	normative
`02a-vm-values-and-calling-convention.md`	VM values and calling convention	normative
`02b-vm-function-values-and-closures.md`	VM closures and function values	normative
`03-memory-stack-heap-and-allocation.md`	VM memory model	normative
`04-gfx-peripheral.md`	virtual hardware: graphics	normative
`05-audio-peripheral.md`	virtual hardware: audio	normative
`06-input-peripheral.md`	virtual hardware: input	normative
`07-touch-peripheral.md`	virtual hardware: touch	normative
`08-save-memory-and-memcard.md`	virtual hardware: save memory	normative
`09-events-and-concurrency.md`	machine events and frame scheduling	normative
`09a-coroutines-and-cooperative-scheduling.md`	VM coroutine model	normative
`10-debug-inspection-and-profiling.md`	machine diagnostics	normative
`11-portability-and-cross-platform-execution.md`	portability contract	normative
`12-firmware-pos-and-prometeuhub.md`	firmware and system orchestration	normative
`13-cartridge.md`	cartridge package	normative
`14-boot-profiles.md`	firmware boot flow	normative
`15-asset-management.md`	asset runtime surface	normative
`16-host-abi-and-syscalls.md`	host ABI structure	normative
`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 continua sendo a autoridade canônica das invariantes internas da VM/runtime.
../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.

6.5 KiB Raw Blame History