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

The implementation boundary for host portability is the platform layer. Runtime,
firmware, and host integration code use typed platform services for rendering,
input, audio, assets, and telemetry. A concrete local hardware aggregate may
exist inside a host or test platform, but it is not the normative runtime-facing
contract.

The real render worker contract is documented across the GFX, events, and
portability chapters. `04-gfx-peripheral.md` defines the render submission and
`OwnedRgba8888Frame` publication contract, `09-events-and-concurrency.md`
defines latest-wins handoff and bounded shutdown behavior, and
`11-portability-and-cross-platform-execution.md` defines the split between
worker-owned RGBA8888 frame production and host-owned native upload/present.

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