PROMETEU is an educational and experimental fantasy handheld / fantasy console. This repository contains the Rust runtime workspace for the machine: VM-facing components, virtual peripherals, firmware/system services, host integration, CLI entrypoints, development utilities, specs, and discussion artifacts.

The VM is only one subsystem of the machine. The canonical docs in this repository intentionally distinguish:

machine-level specs;
VM/runtime internal architecture;
implementation crates;
discussion workflow and lessons learned.

What This Repository Contains

crates/console/: core machine/runtime crates such as prometeu-vm, prometeu-system, prometeu-hal, prometeu-drivers, and prometeu-firmware
crates/host/: host-side execution surfaces, currently including prometeu-host-desktop-winit
crates/tools/: user-facing and support binaries such as prometeu and pbxgen-stress
crates/dev/: test support, layer tests, and quality-check utilities
docs/specs/runtime/: canonical PROMETEU machine specs
docs/vm-arch/: canonical VM/runtime architecture and ISA references
devtools/: debugger protocol material
discussion/: agendas, decisions, plans, and lessons for architectural work
test-cartridges/: cartridge fixtures used for validation and manual runs

Canonical Documentation

Use these entrypoints instead of inferring the model from isolated source files:

Machine specs: authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI
VM architecture: authoritative internal architecture for VM/runtime invariants
ISA reference: bytecode-level instruction set authority
Discussion workflow: architectural agenda, decision, and execution traceability

Workspace Layout

This repository is a Rust workspace rooted at Cargo.toml with members in:

crates/console
crates/host
crates/tools
crates/dev

The main user-facing dispatcher binary is prometeu, built from crates/tools/prometeu-cli. The same package also builds prometeu-runtime, which embeds the current desktop host runtime.

Current CLI surface:

prometeu run <cart>
prometeu debug <cart> --port <port>

The dispatcher forwards runtime execution to prometeu-runtime. For lower-level local runs, prometeu-runtime also accepts:

--run <cart>
--debug <cart> --port <port>
--fs-root <path>
--cap <path>

Other ecosystem commands, such as build, pack, and verification tooling, are not part of the current dispatcher surface in this workspace.

Requirements

Rust toolchain from rust-toolchain.toml
rustup for toolchain installation and management
cargo-llvm-cov for coverage targets such as make coverage and make ci-domains
a local graphical environment for desktop runtime commands

Quick Start

Build the workspace:

cargo build

Inspect the CLI:

cargo run -q -p prometeu-cli --bin prometeu -- --help

Run the current stress cartridge fixture:

cargo run -q -p prometeu-cli --bin prometeu -- run test-cartridges/stress-console

Run the embedded runtime binary directly:

cargo run -q -p prometeu-cli --bin prometeu-runtime -- --run test-cartridges/stress-console

Regenerate and run the stress cartridge fixture:

./scripts/run-stress.sh

The desktop runtime opens a native window through the host layer, so runtime commands are intended for a local graphical environment.

Validation

Format, lint, and test the workspace:

make test

Run the CI-oriented non-domain gate:

make ci

Run the CI-oriented domain coverage gate:

make ci-domains

The debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; make test includes them through the dedicated test-debugger-socket target.

Coverage Governance

The repository uses a two-layer runtime-edge coverage model:

a mandatory CI gate based on canonical runtime-edge domains;
domain-oriented review evidence for the canonical runtime-edge domains.

Current canonical domains:

system/runtime
fs
asset/bank
firmware
host-dependent

Global coverage artifacts:

make ci
make cobertura
make ci-domains

This produces:

target/llvm-cov/html
target/llvm-cov/report.json
target/llvm-cov/summary.json
target/llvm-cov/cobertura.xml

Domain-oriented evidence helpers:

make coverage-domain-list
make coverage-domain-evidence DOMAIN=firmware
make coverage-domain-evidence DOMAIN=host-dependent

Per-domain baselines currently start around 60. That does not waive test obligations. It means the project is adopting explicit domain evidence immediately while tightening quantitative expectations incrementally over time.

make ci-domains is the CI entrypoint used by Jenkins. It runs the standard coverage pipeline, produces the HTML/XML/JSON artifacts, and fails when any canonical domain falls below its configured baseline_percent. The CI gate currently compares domain lines coverage against each domain baseline.

When a PR changes the observable contract of a canonical domain, it is expected to:

add or adjust tests for that domain; or
justify explicitly why the observable contract did not change.

Improving the global percentage alone is not sufficient review evidence when the changed behavior belongs to a canonical domain.

Current State

The project is still in active architectural and implementation convergence.

the machine contract is being clarified through the specs and discussion workflow;
the workspace already contains concrete runtime and host code;
the CLI dispatcher currently exposes the runtime paths that are backed by binaries in this workspace.

Treat APIs, file formats, and execution flows as evolving unless the relevant spec explicitly defines them as stable.

License

This project is licensed under the MIT License.