Make a host, step 4: prove it exact

Your host shows what the reference shows. This step proves that it agrees to the last bit, with a yes-or-no test: the state hash.

The state hash

Between frames, a machine's whole state is one string of bytes, the state serialization; the state hash is its BLAKE3-256 hash. Two hosts given the same program and input agree exactly when their hashes do after every frame. The string holds, in order:

Check yourself

STATE.md gives the hashes of step 1's exit.terse, at reset and after its frame:

9cbfa0da982561dd1c5dbaf1d5fde2121dee78c097d754aa0c2a350584bbeb5a
3272a879392d8179997dc398726430bf92bbd413b89653be8c9af4472656fe9b

and of hello after 30 frames, as the reference prints it:

terse run programs/hello/hello.terse --frames 30 --hash
819432152b38626f8fc54b43f50d5d4c501dc99e6904315b61dc78b796c611e2

--frames 0 gives the hash at reset, --hash-every 1 one per frame: the first that differs shows where your host goes wrong. --save-state <file> writes a snapshot file whose bytes 94 to 293 are the string's first 200 (header, registers, frame loop).

Save and restore

The same string is a snapshot: a machine restored from it goes on as if it had never stopped. Read it back section by section; send each device's section to its driver with RESTORE, which replies how many bytes it took; refuse a string that does not serialize back to itself. Save after 10 frames, restore, run 20 more, and the hash is that of 30 frames:

terse run programs/hello/hello.terse --frames 10 \
    --save-state hello.snap
terse run programs/hello/hello.terse --load-state hello.snap \
    --frames 20 --hash

prints 8194... again. A host that runs one program may leave restoring out, as tcore does.

Input, and the rest of the System device

The conformance program needs all of the System device: the event queue (keys, text, pointer, wheel), controllers, and the other calls (unix_time, random, controller, open, argument, device). For tests, read input from an events file (STATE.md section 6.2). programs/hello/hello.events types into hello; the screen must then be expected-30-frames.txt:

terse run programs/hello/hello.terse --frames 30 --dump \
    --events programs/hello/hello.events

The conformance program

programs/conform-program checks a host from the inside. It needs the 2D vector display too: start terse-dev-vector, asking it for slots 3 and 9 together (DEVICES.md section 1.1). Run it for 200 frames with its input:

terse run programs/conform-program/conform-program.terse \
    --events programs/conform-program/conform-program.events \
    --frames 200 --dump

Your screen should be the first 30 lines of expected-screen.txt: 22 PASS lines, no FAIL. With --hash-every 10 instead of --dump, your hashes must be the 20 of expected-hashes.txt. Then your host is exact.

How much code

In tcore the serialization is 46 lines of C, the events file about 160, and the whole core about 1,580.

Where to go next

What you have now

A host that runs Terse32 programs exactly as the reference does, and proves it. Next, write a device as a separate program: Make a device.

The detail is in State, replay and conformance, sections "The state serialization", "The hash", "Snapshots" and "The conformance image" (STATE.md sections 1, 3, 4 and 6; SPEC §conformance), with the input in Events and input and the calls in The system device.