Contracts for every repository in the Hadley's Hope colony simulation (ITMO, "Systems Engineering", 2026). No code lives here, only the agreements the code must follow: the language, the bytecode, the VM host interface, the MQTT topics and the rules of the simulated world.
Important
If two repositories disagree, this repository is right. Change the spec first, then the code.
| Folder | What it fixes | Who depends on it |
|---|---|---|
requirements.md |
MVP scope, mapped to the course slides | everyone |
architecture/ |
C4 diagrams, tick order, event chain, decision records | everyone |
language/ |
the Hope language: syntax (EBNF), types, built-ins | compiler, houses |
bytecode/ |
.hbc file format, instruction set, VM host interface |
compiler, vm, runtime |
messaging/ |
MQTT topic tree and JSON message schemas | world, runtime, monitoring, infra |
world/ |
physics, incident table, tariffs, house catalog | world, monitoring |
repos.md |
what each repository owns | everyone |
requirements.mdto see what "done" means.architecture/overview.mdto see who talks to whom.- Then only the folder that concerns your repository.
| Term | Meaning |
|---|---|
| tick | one step of simulated time, equal to one simulated minute |
| sensor | a value the world publishes and a house program can read |
| actuator | a value a house program writes and the world obeys |
| house program | a .hope file compiled to .hbc, the "brain" of one house |
| world | the process that owns time, physics, incidents and money |
| runtime | the process that runs 300 VM instances and bridges them to MQTT |
| issue | a problem object with a status: open, in_progress, resolved |