Glossary

The words this repository uses with a precise meaning, in alphabetical order. Where a term has a home in the protocol, the section is given.

Alphabet. How frame bytes are written as SMS characters. b64 (base64url, 114 body bytes per SMS) is the default; z85g (127 bytes in 160 characters, marked by a leading full stop) carries 6 percent more. PROTOCOL.md section 2.1, ADR-0003, ADR-0013.

Allowlist. The phone numbers the server answers, TEXTWIRE_ALLOWED_NUMBERS. Anyone else is ignored without a reply.

Budget. The number of outbound SMS the server may send per UTC day, TEXTWIRE_DAILY_SEGMENT_BUDGET. Checked before any work, charged before any send. ADR-0012.

Chip. A link in document text, written as the anchor text followed by its number in square brackets: the council[3]. The phone renders it as something to tap; the server keeps the URL. ADR-0008.

Codec. How the text inside an envelope is encoded: 0 is raw UTF-8, 1 is zstd with the shared dictionary. PROTOCOL.md section 4.

Dictionary. The zstd dictionary (880 KiB in v1) trained on real pages, committed at protocol/dict/textwire-v1.zdict and shipped in both the server and the app. It is what makes small pages compress well. ADR-0004.

Document. What a request produces: a title, a body in the document-text subset of Markdown, and a link table. Pages, search results and help are all documents.

Document text. The small Markdown subset the phone renders: a title line, ## headings, paragraphs, - and 1. lists, and chips. PROTOCOL.md section 5.

Envelope. The four bytes at the front of every payload: kind, codec, page, pages. PROTOCOL.md section 4.

Fixture. A recorded page or search under protocol/fixtures/, served by the fakes in tests and by the offline simulator.

Frame. One SMS of a response: a six-byte header (version and type, tag, sequence, total, CRC-8) and up to 114 or 121 body bytes, written in an alphabet. PROTOCOL.md section 2.

Gateway (Android SMS gateway). The alternative transport: a spare Android phone running SMS Gateway for Android with its own SIM, driven over HTTP on the LAN.

GSM-7. The seven-bit alphabet of a standard SMS: 160 characters per message if every character is in it, 70 if any is not. Everything the server sends is inside it.

Handler. The part of the server that turns one inbound SMS into its replies, in three steps: resolve (fetch or search), render (frames or plain text), commit (store, charge).

Kind. What a document is: PAGE, SEARCH, STATUS or HELP. The first byte of the envelope.

Notice. A reply about a problem, such as a bad request or an exhausted budget, sent at most once per sender per TEXTWIRE_NOTICE_INTERVAL_MINUTES.

Page. One slice of a document that fits a number of frames once compressed. Every page starts with the document's title. PROTOCOL.md section 9.3.

Payload. The bytes a complete set of frames carries: the envelope and the document text.

Plain reply. A readable reply for any messaging app, asked for with ! after the verb. Messages are prefixed [a7 1/4] and the last one says what to send for the next page. PROTOCOL.md section 7, ADR-0007.

Request. Readable text from the phone: an optional tag, a verb, its arguments. a7 g https://example.com. PROTOCOL.md section 6.

Resend. The r verb: the phone lists the frame numbers it is missing and the server sends those frames again, verbatim. PROTOCOL.md section 8.

Segment. What the carrier bills: one SMS. Every frame is exactly one segment.

Simulator. textwire simulate: the real server and a virtual phone talking over the fake transport in the terminal. With --offline it needs no network.

Status. A one-line document: I ... for information, E <area> <detail> for an error. PROTOCOL.md section 9.6.

Tag. Two base-36 characters that name one response, 00 to zz. The phone allocates 00 to yz; the server allocates z0 to zz for requests that came without one. PROTOCOL.md section 3.

Transport. The interface to an SMS provider: receive, send, status. Twilio, the Android gateway and the fake implement it.

Vectors (golden vectors). The committed JSON cases under protocol/vectors/ that both the Python and Kotlin implementations are tested against, generated by the Python reference implementation. PROTOCOL.md section 12.

Virtual phone. The app's receiving logic written in Python, used by the simulator and the end-to-end tests.