How Terse works

Sharing information

An article is plain text that reads well as it is, with a few marks for headings, lists, tables, preformatted text and links. A diagram is written into the article as path data in the style of SVG, so it is part of the text and needs no image file. There are no scripts, no styles and no embedded programs, and an article cannot link to a web page, only to other Terse articles, feeds and programs.

Authors publish articles in feeds. A feed belongs to a key that its author holds, not to a website: every entry is signed, so a reader can check that it came from the author whoever delivered it. Relays store and pass on feeds and articles. Anyone can run a relay, a feed can be on several at once, and a reader can follow the same feed through any of them, so no single site decides what may be published or read.

A reader for all of this is a small program. It needs the network and the article format and nothing else.

Sharing programs

A Terse program is a small file of machine code for a simple virtual computer. The machine is isolated: a program sees only its own memory and the few devices its host offers, such as a terminal, a vector display and the content store. It gets a fixed amount of work per frame, so it cannot slow its host down, and it behaves the same on every host.

All of this is optional. A host may leave out the machine altogether, or any device it does not want to build, and still be a complete Terse reader. Articles never contain programs: they can only link to them.

The three layers

Terse has three layers. The network (blobs, relays, feeds, entries, profiles, names and search) and the article format are the core: a native reader that implements those two, with no virtual machine at all, is a complete Terse client. The machine is an optional third layer that reuses them: a small virtual computer whose programs are shared the same way articles are. This article goes through the network and articles first, then the machine and what surrounds it.

The network

Everything that travels is a blob: 1 to 1,048,576 bytes, named by the BLAKE3-256 hash of its bytes, so a host checks every blob it receives against its name and needs to trust no one to deliver it. Program images are blobs too, so a program's image ID is a blob ID. Relays are blob stores reached over WebSocket. Authors have feeds: numbered series of small entries signed with an Ed25519 key, each pointing at a blob and giving its size and title. An entry is an article, a profile (a display name and a short description), a program or a document. Hosts subscribe to feeds and fetch small articles ahead of time, so reading never waits on the network.

An article is UTF-8 text that reads well as it is, with a few line-start markers for headings, lists, preformatted text, tables and figures, and links of the form terse: followed by a blob ID. A program is published the same way, as a feed entry whose title is the program's name and whose blob is its image; its identity, the publisher's feed key and the name, stays the same from one version to the next. A host downloads the current version of each program in the feeds it follows. Articles never contain programs: they link to them.

The machine

A program is a file of RISC-V machine code, at most 128 KiB, identified by the hash of its bytes. It runs in a machine with at most 1 MiB of RAM and a fixed amount of work per frame, and it reaches the outside world only through a handful of host devices. The same program, given the same inputs, does exactly the same thing on every host. A host that runs only the reader needs just the reading profile (devices 1, 2, 4 and 7).

The CPU is RV32IMC: the 32-bit RISC-V base integer set with multiply and divide and compressed instructions, in user mode only. There are no floating-point instructions, no interrupts and no privileged state. The memory map has two regions and nothing else: ROM holds the program's bytes and RAM is zero at reset. Any access outside them faults, so a null pointer dereference stops the program with a recorded fault.

ColourAddressesMeaning
greyeverything elseany load, store or fetch faults
red mark0000_0000haddress 0, so a null pointer faults
blue bar0001_0000h to 0001_0000h + rom_len − 1ROM (1 to 131,072 bytes): read and execute
green bar0010_0000h to 0010_0000h + 8,192 × ram_pages − 1RAM (8 KiB to 1 MiB): read, write and execute
blue triangle0001_0000hwhere pc starts
orange triangleend of RAMwhere sp starts

The drawing is not to scale: the address space is 4 GiB, and the two regions are small islands in it.

Time advances in frames, nominally 60 a second. Each frame the machine gets a budget of 125,000 units: an instruction from ROM costs 1, one from RAM costs 4, and each device call has a small charge on top. When the budget runs out the machine pauses and continues with the next instruction in the next frame; the program is not told. A program that has done its work for the frame calls wait_frame, which gives up the rest of the budget and returns at the start of the next frame. Because the budget is the same on every host, a program runs at the same speed everywhere, and the work a host does for one frame of any program is bounded.

Devices

Programs reach devices with the ecall instruction: the call number in register a7 is the device slot times 256 plus a function, arguments go in a0 to a5, and the result comes back in a0. An image lists the devices it needs in its header; a host that lacks one refuses the image, and a device the image does not list behaves as absent.

SlotDevice
1System: frames, events, clock, random bytes, controllers, exit (always present)
2Terminal: 80 × 30 character cells
32D vector display: lines and filled shapes from a display list
4Content: blobs, feeds, search, named records
6Sound: 16 voices of a wavetable synthesizer, 48,000 Hz stereo (optional)
7Page: typeset proportional text and figures
8Machines: starting and placing other machines (the shell only)
93D vector display: lines placed in space, seen in perspective

Devices present and transport; they do not compute for the program, and nothing a host draws can be read back. The screen is 640 × 480 units for every device that draws.

Determinism and replay

A machine's state is a pure function of its image and its inputs: the events of each frame (keys, text, pointer, wheel and the answers devices send back), the Unix time latched at the start of each frame, the random bytes the host supplies, the controller state, and the completions of content requests. A host that records these per frame can replay a run exactly. To compare two implementations, the state of a machine between frames has a byte-for-byte serialization, and its BLAKE3-256 hash is the state hash: two runs agree as long as their hashes agree. The same serialization is a snapshot, from which a machine can be restored and continued.

Systems, the shell and the reader

A host can run several machines as one system. One of them, the shell, holds device 8: it starts other machines (up to 8), places each one's screen in a rectangle of its own, decides which receives the keyboard, and keeps them as snapshots. Each machine is complete and separate, with its own memory, devices, events and budget. The host runs the machines, draws their screens where the shell put them, and routes input; layout and policy are the shell's. A machine can ask the shell to open a blob or a program, and the shell decides what to do. The host's built-in shell shows machines as tiles, with a launcher of built-in programs and of programs from the feeds the user follows.

The reader is the first built-in program: a feed reader that shows the timeline of followed feeds and typesets articles on the page device. When the user follows a link to a program, the reader asks the shell to open it in a tile of its own.

Where to go next