Files
prometeu-runtime/README.md
T
bquarkz 49d7fca0b7
Intrepid/Prometeu/Runtime/pipeline/head There was a failure building this commit
chore(toolchain): pin Rust to 1.98.1
2026-11-10 22:39:19 +00:00

195 lines
6.6 KiB
Markdown

# 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 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](docs/specs/runtime/README.md): authoritative contract for the PROMETEU machine, peripherals, firmware, cartridge format, timing, and host ABI
- [VM architecture](docs/vm-arch/ARCHITECTURE.md): authoritative internal architecture for VM/runtime invariants
- [ISA reference](docs/vm-arch/ISA_CORE.md): bytecode-level instruction set authority
- [Discussion workflow](discussion/index.ndjson): architectural agenda, decision, and execution traceability
## Workspace Layout
This repository is a Rust workspace rooted at [Cargo.toml](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](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:
```bash
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:
```bash
cargo build
```
Inspect the CLI:
```bash
cargo run -q -p prometeu-cli --bin prometeu -- --help
```
Run the current stress cartridge fixture:
```bash
cargo run -q -p prometeu-cli --bin prometeu -- run test-cartridges/stress-console
```
Run the embedded runtime binary directly:
```bash
cargo run -q -p prometeu-cli --bin prometeu-runtime -- --run test-cartridges/stress-console
```
Regenerate and run the stress cartridge fixture:
```bash
./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:
```bash
make test
```
Run the shared strict CI gate (`make ci` is an alias):
```bash
make ci
```
The authoritative target used by both GitHub and Jenkins is:
```bash
make ci-domains
```
The five debugger socket tests bind localhost sockets and are marked ignored in Rust test metadata; both `make test` and `make ci-domains` select only `runner::tests` through `test-debugger-socket`. Physical audio and other manual probes remain opt-in. See [quality-gate prerequisites and commands](docs/vm-arch/COVERAGE_DOMAINS.md#commands-and-ci).
## 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](files/config/runtime-edge-coverage-domains.json).
Use `make coverage-domain-list` or the [ownership documentation](docs/vm-arch/COVERAGE_DOMAINS.md)
to inspect the current map.
Global coverage artifacts:
```bash
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:
```bash
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,
all-target tests, the five debugger socket tests, fresh 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 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](LICENSE).