Files
prometeu-runtime/README.md
T
bquarkz f1adf86dd5
Intrepid/Prometeu/Runtime/pipeline/head This commit looks good
feat(runtime): support Studio Play and separate integration gates
Add the windowless Studio host with authenticated binary control/frame channels,
managed input, pause/resume/stop, frame ownership and save-aware shutdown.
Preserve deterministic headless execution and add protocol/process fixtures.
Separate unit CI and coverage from opt-in integration/socket qualification,
retaining the prior combined coverage floors in the configuration history.

Validation: tooling make verify passed runtime ci-domains and integration.
2026-11-19 17:32:02 +00:00

7.1 KiB

PROMETEU Runtime

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 engineering lessons.

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;
  • engineering 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/lessons/: published engineering lessons and supporting assets
  • 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
  • Engineering lessons: published results and rationale

Engineering discussions, decisions, plans and execution evidence are maintained in the enclosing Prometeu Engineering workspace using AI Engineering.

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 1.98.1, pinned in 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

From the repository root, install and verify the pinned toolchain:

rustup toolchain install 1.98.1 --profile minimal --component rustfmt,clippy
rustc --version

Rustup selects the pinned version automatically for commands run in this repository. CI installs the toolchain from the same file.

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 shared strict CI gate (make ci is an alias):

make ci

The authoritative target used by both GitHub and Jenkins is:

make ci-domains

make test-unit selects library and binary unit-test harnesses with --lib --bins --all-features; test-local remains an alias. Both make test and make ci-domains run only this suite. Integration targets under tests/, installed-process qualification and the five ignored debugger socket tests are excluded from the pipeline. They remain available explicitly through make test-integration and make test-debugger-socket, orchestrated by ../tooling. Tests and fixtures stay in this repository. Physical audio and manual probes remain opt-in. See quality-gate prerequisites and commands.

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.

The fifteen canonical domains and fixed floors are defined in the repository configuration. Use make coverage-domain-list or the ownership documentation to inspect the current map.

Global coverage artifacts:

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
make coverage-domain-evidence DOMAIN=host/headless

make ci-domains runs formatting, strict workspace/all-target/all-feature Clippy, library/binary unit tests, fresh unit-only coverage and every domain ownership/evidence gate. Both CI providers archive available evidence on failure. A failing run never lowers a configured floor; local and CI checks use the same repository-owned commands. Reports identify their revision, source/configuration and actual execution platform.

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 AI Engineering;
  • 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.