Glossary — TERSL Docs

Terms#

Account: What you sign up for. An account owns its namespaces, API keys and portal users, and its plan sets its limits; two accounts never see each other's data. See What TERSL/DB is.
Address: A namespace name with a point in its history attached, written {ns}@{csn} or {ns}@{time}, such as 7QK4M2C@4096. It means the same as the Terse-As-Of-Csn and Terse-As-Of headers. See Addresses.
Administrator (of a namespace): A key that holds all at the namespace root. Only such a key may copy the namespace, run a scrub or a playback session, or call /explain; the API pages call it an admin. See Administrators and explain.
Administrator (portal role): A portal user who can do everything in the account, including adding users and keys, editing grants and managing billing. See Users.
API key: The credential a client presents on every request: tsk_, a 16-character key id, _ and a 43-character secret, shown once when it is issued. A key reaches nothing until a namespace's grants name its key id. See Keys.
Attribute: A property in the parentheses after a name, separated from the next by ;. There are three kinds: a flag (creaky), an identifier (hp: 25) and a raw value (0.95). See Attributes.
Bulk load: Writing a TERSL file too large for one Issue into a namespace through POST /v1/ns/{ns}/load, which applies the file as a series of batches, each with its own CSN. See Bulk load.
Burst rate: The short-term rate a plan allows, such as 120 requests a minute; a request over it waits for its turn and is refused with 429 only if the wait would be too long. See Bursts and the sustained pace.
Change sequence number (CSN): The number of a committed write in a namespace's record. The first write is CSN 1, each later write takes the next number, and the Terse-Csn header reports it. See The namespace and its CSN.
Checkpoint: A saved state of a namespace at a past CSN, from which the service starts point-in-time reads. A scrub checks the newest checkpoints. See Scrub and playback.
Companion document: The TERSL document {ns}_meta that belongs to each namespace and holds its # Access grants, its # Meta section and its # Verification settings. You edit it on the portal's Grants page; it cannot be addressed on the API. See The grants document.
Container: A line that starts with #; the number of # characters is its depth. A container holds objects, sub-containers and at most one TEXT payload. See Containers.
Copy: A new namespace made from an existing one at a chosen CSN or time, with the same state, the record up to that point and the source's grants. A copy starts read-only and is independent of its source. The API calls it a fork. See Copies.
Declaration: TERSL text that states the part of the state that should be different. A declaration changes only what it mentions. See Writing with declarations.
Diagnostic code: A stable identifier at the start of a message, such as TERSE028 from the language or TERSE-SEC-001 from TERSL/DB. See Diagnostic codes.
Directive: A keyword in capitals inside the bracketed tail at the end of a line, such as [FIRST], [WAS old name], [REMOVED] or [WHERE …], that tells a declaration or a query what else to do. See The directive tail.
Display name: A name as you wrote it, with its spaces and capitals. Programs and filters use its normalized identifier instead. See Names.
Empty 404: A 404 with no body and none of the service's headers. It is the same answer for a namespace that does not exist, a missing or invalid key, and a key the grants admit to nothing. See The empty 404.
Expected-Csn: A request header that asks the service to apply a write only if the namespace is still at the given CSN. A mismatch is reported in the Messages channel of a 200, and nothing is applied. See Concurrent writers.
Export: The namespace's state, as the key sees it, returned as one .terse file by GET /v1/ns/{ns}/export or downloaded from the portal's Bulk data page. See Export.
Flag: An attribute with no value, such as online or creaky, written as a human-readable descriptor. See Attributes.
Grant: A grant(…) line in a namespace's # Access section that gives one key a set of rights at a path. Grants only add rights; there are no deny rules. See Grant lines.
Hash chain: The keyed hash on every entry of a namespace's record, each entry linking to the one before it, so that a change made to the record outside the service is reported at the CSN where it happened. See The hash chain.
History: The entries of a namespace's record, read through GET /v1/ns/{ns}/history or the portal's History page. Reading history needs the history right. See Reading history.
Idempotency key: The value of the Terse-Idempotency-Key header, chosen fresh for each logical write and sent again on every retry of it. A retry with the same key and body is answered from the record instead of being applied twice. See Retries and idempotency keys.
Identifier: An attribute with a key and a value, such as hp: 25, used when a program or a [WHERE] filter will read the value. See Attributes.
Iron Rule: The rule that storing state and writing it back out changes names, flags and quoted text only by normalizing whitespace. See Names.
Issue: One request to POST /v1/ns/{ns}/issue: declarations, then the seam line, then queries. The declarations commit as one write and the queries read the result. See The Issue.
Limited user: A portal user who can use only the keys and read only the logs an administrator gave them. See Users.
Messages channel: The part of an Issue's answer after the seam line: one error:, warn: or info: line per message, counted in the Terse-Diagnostics header. See The Messages channel.
Moment (point-in-time read): A read of a namespace as it stood at an earlier CSN or time, asked for with an address or the Terse-As-Of-Csn and Terse-As-Of headers. The past is read-only, and what a key sees there is decided by its history right under its current grants. See Reading a moment.
Namespace: One TERSL document stored in TERSL/DB, with its own record, its own grants and a seven-character name. See What TERSL/DB is.
Namespace Id: The portal's label for a namespace's seven-character name, such as 74XEEJ5, which the HTTP API uses to address it. See What TERSL/DB is.
Normalized identifier: The machine form of a name, derived by fixed rules (for example, New York becomes New_York); the specification calls it a handle. See Names.
Object: A line under a container with no #. An object may carry attributes and has no children and no TEXT. See Objects.
Placement: The directives [FIRST], [LAST], [BEFORE name] and [AFTER name], which set where a line stands among its siblings. See Placement.
Plan: The set of limits an account has: burst rates and sustained paces, sizes, counts and the record level. See Plans, rates and limits.
Playback session: An administrator's session that steps through a namespace's record one entry at a time and checks each entry and checkpoint it passes. See Scrub and playback.
Point-in-time read: Another name for a moment: a read of a namespace as it stood at an earlier CSN or time. See Reading a moment.
Portal: The TERSL/DB web application where you administer namespaces, keys, grants, users and billing, and browse state, history and logs. Its own pages call it Command Center. See Portal guide.
Portal-only key: A key whose secret is discarded when it is issued, so it can be used only through the portal by the people it is given to. See Keys.
Query: A line that starts with ?, naming a path and optionally a bracketed tail of read directives. Outside a declaration a query never changes state. See Reading with queries.
Raw value: An attribute with no key, such as 0.95 or "a note", kept for human context. See Attributes.
Read-only namespace: A namespace whose # Meta header carries the readOnly flag. Queries, history and exports are served, and a write is refused with 409; every copy starts this way. See Read-only namespaces.
Record: A namespace's history of committed writes, one entry per CSN, each keeping the declaration text exactly as it was sent with its time and key. See The record.
Record level: How a namespace's record is protected, set by the plan: chain, seal or worm, each including the ones before it. See Record levels.
Reference: @ followed by a path, pointing at another node. A reference is stored as path text: queries do not follow it and a move does not rewrite it. See References.
Right: One permission a grant confers: read, add, modify, remove, append, reorder, rename, history, or all for all eight. See Rights.
Scrub: An administrator's check of a namespace's newest checkpoints against their digests and seals. It reports a mismatch and repairs nothing. See Scrub and playback.
Seal: A statement signed by the service that a namespace's record at a CSN ended at a given chain value and that the state there has a given digest. Seals are made at the seal record level and above. See Seals.
Seam: The line that separates an Issue's declarations from its queries, and its answers from its messages: %%%SEAM%%% unless the Terse-Seam header names another token. See The Issue.
Silence defers: The rule that a declaration changes only what it mentions: a line you do not restate does not change, and leaving out an attribute does not clear it. See Silence defers.
Status doctrine: The rule that an Issue the service processed answers 200, with any refusal inside it reported in the Messages channel, while HTTP status codes are kept for requests that were not processed. See The status doctrine.
Sustained pace: The daily rate a plan allows over time, such as about 8,300 requests a day, measured over a rolling 30-day window that refills continuously and has no reset date. See Bursts and the sustained pace.
TEXT: A container's free-text payload, written as a quoted line or a """ block, and addressed directly by a path ending in TEXT. See TEXT.
Visible world: The parts of a namespace a key's grants let it read. Answers, history, exports and point-in-time reads are pruned to it, and nothing outside it is reported. See The visible world.
worm: The record level at which every log entry and seal is immutable in storage for the plan's retention window, so that no credential the service holds can delete or rewrite it. See Record levels.