prometeu-runtime/docs/specs/runtime

PROMETEU Machine Specs

This directory contains the technical specs for the PROMETEU machine.

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.

The organization here is intentionally flat. The taxonomy is conceptual, not structural.

Scope Boundary

Belongs in docs/runtime/specs/:

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

Does not belong in docs/runtime/specs/ as the primary canonical source:

• internal architectural invariants of the VM/runtime: ../virtual-machine/ARCHITECTURE.md;
• bytecode-level ISA: ../virtual-machine/ISA_CORE.md;
• pedagogical guides and learning material: ../learn/README.md;
• agendas, proposals, and plans: docs/runtime/agendas/ and docs/runtime/pull-requests/.

Organization Rules

• 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

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

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

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

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/ defines the PROMETEU machine and its external execution surfaces.
• ../virtual-machine/ARCHITECTURE.md remains the canonical authority for internal VM/runtime invariants.
• ../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

• 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

A topic should be created as a spec + learn pair when:

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

In those cases:

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