199 lines
6.8 KiB
Markdown
199 lines
6.8 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 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](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
|
|
- [Engineering lessons](discussion/lessons/): published results and rationale
|
|
|
|
Engineering discussions, decisions, plans and execution evidence are maintained in
|
|
the enclosing [Prometeu Engineering workspace](../README.md) using
|
|
[AI Engineering](../.ai-engineering/README.md).
|
|
|
|
## 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 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](LICENSE).
|