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

# 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`](../../vm-arch/ARCHITECTURE.md);
- bytecode-level ISA:
  [`../virtual-machine/ISA_CORE.md`](../../vm-arch/ISA_CORE.md);
- pedagogical guides and learning material:
  [`../learn/README.md`](../runtime/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`](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/` defines the PROMETEU machine and its external execution surfaces.
- [`../virtual-machine/ARCHITECTURE.md`](../../vm-arch/ARCHITECTURE.md) remains the canonical authority for internal VM/runtime invariants.
- [`../virtual-machine/ISA_CORE.md`](../../vm-arch/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.