The words
The words, in plain terms.
Every word this project uses, explained by what it does, in the order you meet them. Some are ordinary computing words, like PID 1 or to mount; some are this project's own names for plain things, like the court, which is simply the check a machine file must pass before anything runs.
These are the same words, in the same order, that harb learn --words prints and that the README carries. A check in the repository fails if any of them drift apart.
a machineOne computer, written down in a
.machine file: which board and processor it has, which disks it uses, which programs it runs, and what each program may touch. It is only text until it is built.a declarationOne block of that file, starting with
DEFINE: the machine itself, a program, a disk, a network, a permission. Every block must end with a RATIONALE, which says in plain words why it is there, and a file with one missing is refused.a clauseOne line inside a block, such as
RUN [...] (the program to start) or NEEDS [...] (what it must be allowed to do). Each kind of block accepts a fixed list of clauses, and any other is refused by name.a serviceA program the machine starts and looks after, declared with
DEFINE SERVICE. It says what to run, whether to restart it when it stops, and what it needs.a capabilityOne kind of access a program must be granted before it has it:
network, filesystem (the disks), process (starting other programs), and a few more. A program that did not ask for network runs with no network at all, because the kernel gives it none.to mountTo attach a disk, or one part of a disk, so that its files appear in a folder: an SD card's second partition at
/data, for instance. A MOUNT block names the disk and the folder. It can also be scratch space held in memory, which vanishes when the machine stops.the kernelThe core of the operating system: the part that drives the hardware and decides what each program is allowed to do. Harobanda uses the Linux kernel, unmodified; the machine file decides which of its parts are switched on. What is new is everything above it.
to judgeTo check something against what it must be, and say plainly where it differs. Before anything runs,
harb check judges a machine file against the language's rules. At the end of every boot, the machine judges what it printed against what its file says a correct boot prints.the courtThe part of
harb that judges a machine file before anything runs (harb check). It gives a verdict, which is why it is called a court: accepted, or refused with the line number and the reason in plain words. It is checked in turn against example files it must accept and more it must refuse (zig build court).the planThe order in which the machine will do things when it boots: which disks first, which programs after which.
harb plan works it out from the file and prints it before anything runs.an imageThe exact files a machine boots from: the kernel,
harb, the programs, the machine file itself, and a copy of what a correct boot must print. A change to the machine is a new image, built from the changed file.QEMUA free program that imitates a whole computer, so a machine can boot on your laptop with no board at all.
PID 1The first program the kernel starts when a computer boots. It starts every other program and looks after them until the machine stops. Every Linux system has one (on Ubuntu it is systemd); on a declared machine it is
harb itself, reading the machine file. PID means process ID, the number the kernel gives each running program.the transcriptEverything one boot printed, from the first line to the last. The machine prints a line for every step as it takes it, which this project calls narrating.
a pinA saved copy of a transcript someone read and found right, kept in the repository as
machines/<name>.expected. The next boot is compared with it line by line, so any change shows up as a difference.a worldOne service while it runs, inside walls the kernel keeps: what it did not ask for (the network, a disk, starting other programs) it does not have. The word is this project's; the walls are Linux's own (namespaces and control groups).
the envelopeThe walls around one world: exactly what it may see and do, and how much memory and processor time it may use. They are worked out from what the world declared it
NEEDS, never from a separate permission file someone could edit later.the floorWhat no world may do, whatever it declared: attach or detach disks, set the clock, load code into the kernel, rename the machine, build or enter walls of its own, look inside or take control of another program, or restart the box.
EGRESSThe list of networks a machine may reach beyond its own. The kernel is given a route (the directions to a network) to those and to no others, and every boot says so. A route is not a wall: the machine knows no way anywhere else, which is not the same as being blocked from finding one.
a trialHow an update is installed: it is written to a second copy of the system and booted once. If that boot matches its file, the update is committed, which means kept. If it does not, the board goes back to the copy it had.
the watchdogA timer in the hardware that restarts the board unless the system keeps resetting it. The machine stops resetting it when a trial boot does not match its file, or when a service that promised to keep answering goes quiet: a bad update undoes itself, and a stuck box restarts.
a fleetA set of machines checked together, in a
.fleet file. Some mistakes only show across a set: two boxes that each claim to be the network's server are each fine alone.a seatOne unit of work in this project's history, tagged like
NS-1 or SEE-1. Every rule in the doctrine names the seat that paid for it, and experiment/PROTOCOL.md tells each story in full.