Glossary
Every term Ranvier uses, what it means, and where it is taught.
Why this exists. A term used in one document and defined in another gets
used inconsistently, and drifts. docs/docs.tools/check-docs.py reads every
### heading here and fails if the term it names appears in no other document
under docs/ or spec/, so a definition nothing uses cannot sit here quietly.
Taught names the document that introduces the term to a reader meeting it for the first time. A term with no entry there is a gap.
Concepts and wire fields are listed separately. A concept is something you think about; a field is something that exists in a message. Mixing them makes both harder to find.
Concepts
Each contains the next, and the sections below follow that order.
Graph what runs
└── Node one program
└── Stream what a node publishes, under a Name
├── Announcement sent once: what this stream is
└── Sample sent repeatedly: one observation
└── values shaped by a Schema
Message is the word for anything one program sends to another. There are three kinds and each is defined below in the section it belongs to: an announcement and a sample belong to a stream, a request passes between a node and the runtime.
Graph
| Term | Means | Tier | Taught |
|---|---|---|---|
| Graph | Which nodes run, and which stream names each publishes and subscribes to. The mathematical sense — a network of connected things, never a chart | 1 | concepts.md §2 |
| Conformance profile | A named set of requirements a session declares when it runs a graph. The system checks the configuration against it and reports what does not meet it | 1 | scope-and-goals.md §4 |
Node
| Term | Means | Tier | Taught |
|---|---|---|---|
| Node | One program. It publishes streams, subscribes to streams, or both, and never refers to another node | 1 | concepts.md §2 |
| Request | A message between a node and the runtime — start, stop, wire up. Low-rate, and always answered, unlike a sample, which is sent and forgotten | 2 | architecture.md §2.7 |
Stream
| Term | Means | Tier | Taught |
|---|---|---|---|
| Stream | What one node publishes: a continuous sequence of samples, beginning when that node starts publishing and ending when it stops | 1 | concepts.md §2 |
| Stream name | What a stream is published under. The only address in the system: subscribing to a name delivers every stream published under it | 1 | concepts.md §2 |
| Announcement | The message a stream sends once, before its first sample, describing itself — its name, its schema, its timeline, who was operating. Everything that does not change from one sample to the next | 1 | concepts.md §3 |
| Origin | Whether this stream's data entered the graph from outside it, was computed inside it, or is not meant to persist. See below | 1 | concepts.md §5 |
| Sequence number | The count a stream keeps of its own samples: 1, then 2, then 3. Independent of every clock | 1 | concepts.md §5 |
| Timeline | The set of timestamps that can be compared with each other directly. Every stream belongs to one, named by the machine and the boot. Comparing across two timelines needs an estimated offset, and that estimate has a measured quality | 1 | concepts.md §5 |
Sample
| Term | Means | Tier | Taught |
|---|---|---|---|
| Sample | One observation on a stream: its values, when it was published, and where it sits in that stream's count. The kind of message that carries data | 1 | concepts.md §3 |
A sample's values are opaque to everything that carries them. No part of the system between the publishing node and the subscribing node reads them, which is what lets a new kind of sample be added without changing anything in the middle.
Values
| Term | Means | Tier | Taught |
|---|---|---|---|
| Schema | The declared shape of a sample's values: the fields, each field's type, and what each field means. Every stream has one, and you can write your own for data only your lab produces | 1 | concepts.md §3 |
| Canonical schema | A schema Ranvier defines rather than you, for a kind of sample many instruments produce — gaze, hands, body pose. Every integration producing that kind must use it, which is what makes two eye trackers interchangeable. Fixes the fields, their units, the coordinate frame, and the order of anything repeated | 1 | concepts.md §4 |
| Tensor form | A named, versioned declaration mapping a schema onto a fixed-shape array of numbers. Fixes the shape, the type of each number, the label of every axis, the units, and the coordinate frame | 2 | concepts.md §4 |
| Tensor | The array of numbers itself, laid out as its tensor form declares | 2 | concepts.md §4 |
The three origins
| Value | Means | Could Ranvier recreate it? |
|---|---|---|
source | Entered the graph from outside — an instrument, a service, a replayed file, a simulation, another program's output | No. If it is lost it is gone |
derived | Computed inside the graph from other streams | Yes, if the inputs were recorded and the computation is versioned |
ephemeral | Produced for immediate display or monitoring, not intended to become a record | Irrelevant |
The axis is inside or outside the graph, not instrument versus software. An instrument and a web service are equally outside, and that is what decides recoverability.
Why a stream is not the same as its name
A stream name is not unique. Several streams may share one — a
trial.events name fed by a stimulus program, a button box, and an annotation
tool is the ordinary case. A subscriber asking for that name receives all of
them.
Each stream counts its own samples, and that is the whole reason streams and names are separate things. If those three programs shared one counter the numbers would interleave — 1, 2, 3 from one and 1, 2 from another — and a gap would no longer mean a dropped sample. Separate counters keep a gap meaning exactly one thing.
A node that restarts produces a new stream, because its count starts again at 1. Treating it as the same stream would make a restart look like enormous data loss. This is also why a stream reference is never reused: reusing one would let a consumer resolve an old sample against a newer stream's definition.
If you know Lab Streaming Layer
The stream is the same idea: one outlet's output, resolved by name, and several outlets may share a name. A device is a source of several streams — an eye tracker publishes gaze, inertial measurement, eye video, scene video, and events separately.
The two part company one level down. An LSL channel is always a single number, so a stream there is a flat list of scalars. That fits electrode data exactly and structured data badly: a three-dimensional gaze vector becomes three channels a consumer reassembles by convention, and the convention lives in documentation rather than in the type.
A schema is what replaces the channel list here. A gaze direction is one field of a declared type carrying its own units and coordinate frame. Nothing is reassembled, and nothing depends on remembering which index meant what.
Message fields
What actually exists in a message. Concepts are above; these are the fields that carry them.
In a Sample
| Field | Means |
|---|---|
stream_ref | Which stream this belongs to. Resolves against a StreamInfo the stream announced before its first sample. Never zero |
monotonic_timestamp_ns | When the publishing host sent it, read from that host's monotonic clock. Authoritative for order |
sequence | This sample's position in its stream's own count |
values | The sample's values, encoded. Opaque here; their shape is the schema the stream names |
In a StreamInfo
Announced once, before the stream's first sample, so that every sample after it can carry a small reference instead of repeating constants.
| Field | Means |
|---|---|
stream_ref | The number samples use to refer to this stream. Never zero, never reused |
name | What this stream is published under |
schema_ref | Which schema its measurements use |
origin | source, derived, or ephemeral |
host_id | Which machine produced this stream. Stable across reboots |
boot_id | Which run of that machine's clock. Changes at every reboot |
node_id | Which node produced it. Provenance for a reader, not an address |
operator_ref | Who the host application said was operating. Never verified by Ranvier |
operator_assertion | How that identity arrived, so a reader can weigh it |
authorisation_ref | Under what authority this stream captured data |
authorised_from_unix_ns, authorised_until_unix_ns | The window that authority covers |
host_id and boot_id are both needed. A monotonic clock restarts from
zero at reboot, so one machine presents two unrelated timelines over its
lifetime. Naming only the machine would treat those two as one and mislabel
data across a restart, silently. The pair is what names a timeline.
Time
Three different kinds of thing, and keeping them apart removes most of the confusion. A clock is a source of time. A timestamp is one reading taken from a clock and stored in a sample. A timeline is the set of timestamps that can be compared.
Clocks
| Term | Means | Tier | Taught |
|---|---|---|---|
| Monotonic clock | The host's counter that only moves forward and never jumps. Immune to network time corrections, daylight saving, and manual edits — which is why it, and not the wall clock, decides order | 2 | concepts.md §5 |
| Wall clock | Ordinary calendar time. For saying when a session happened. Never orders anything, because it can step backwards | 2 | concepts.md §5 |
| Source clock | The instrument's own internal clock. Unrelated to the host's, and running at a slightly different rate | 2 | concepts.md §5 |
Timestamps
Every field is named for the reading, never for the clock it came from.
| Field | Reads which clock | Means |
|---|---|---|
monotonic_timestamp_ns | Host monotonic | When the host published the sample. Authoritative for order |
wall_timestamp | Host wall clock | When it happened in calendar time. Human reference only |
source_timestamp_ns | The instrument's own | When the instrument says it sampled, passed through untouched |
Measurement
Tier 2, not tier 3. These name figures a user reads to decide whether Ranvier can meet their timing needs, to choose a batch size or a loss policy, or — for a client assessing this software for a regulated submission — to carry out a risk assessment. The harness is developer tooling; its output is not.
| Term | Means | Tier | Taught |
|---|---|---|---|
| Reading | One timing measurement: how long a single call took. A latency distribution is built from many readings | 2 | bench crate docs |
| Noise floor | The cost of the measurement itself. Nothing measured can be faster, and a difference smaller than the floor's own spread is one the harness cannot see | 2 | not measured here |
| per-call | One timed call per reading. The percentiles are real percentiles of observed latency, tail included | 2 | bench crate docs |
| mean of N | One timed batch of N calls per reading, divided by N. Each reading is a mean, so the tail is averaged away. Its percentiles show variance between batches and are not worst-case latency | 2 | bench crate docs |
| Budget | The ceiling a measurement must stay under, or the build fails | 3 | decisions/0008 |
Noise floor is borrowed from signal processing and percentiles from statistics — both vocabulary this audience already has.
Regulatory
Terms from outside the project. Ranvier does not define these; it conforms to existing definitions, and getting one subtly wrong would be worse than not using it.
| Term | Means | Source |
|---|---|---|
| Source data | The original record of an observation, as first captured | ICH E6(R3), FDA guidance |
| Data originator | The person, system, device, or instrument a data element came from | FDA, Electronic Source Data |
| ALCOA++ | Attributable, Legible, Contemporaneous, Original, Accurate, Complete, Consistent, Enduring, Available, Traceable | FDA / ICH |
| Audit trail | A secure, computer-generated, time-stamped record of who changed what and when, which does not obscure what it replaced | 21 CFR 11.10(e) |
| Pseudonymisation | Replacing a direct identifier with a reference, the mapping held separately | GDPR Article 4(5), Article 89 |
| SOUP | Software of Unknown Provenance: software already available, not developed for this device. Ranvier is SOUP to a client using it in a regulated product | IEC 62304 |
Note that origin: source and the regulatory term source data mean the
same thing on purpose: data as first captured, before anything derived it.
Words we deliberately do not use
| Not this | Use | Because |
|---|---|---|
| topic | stream name | An extra concept. A stream has a name, and subscribing by name is the whole mechanism |
| envelope | Sample | Protocol jargon, and it collides with the amplitude envelope in signal processing |
| payload | a sample's values | Networking jargon for the thing a researcher calls their data |
| measurement (as a term for a sample's contents) | values | A measurement can mean an instrument reading or a quantity computed from one. This system draws exactly that distinction with origin, and reusing the word blurred it. The ordinary English word is fine where it means the ordinary thing |
| provenance | origin | Promises the full history of the data. Origin answers one narrow question: could Ranvier recreate this |
| projection | tensor form | Vague, and it collides with anatomical projections in neuroscience |
| channel | stream, or a schema field | Means an electrode channel to this audience, and a single scalar to an LSL user. Neither is what we mean |
| sink | recorder, writer | Dataflow jargon at tier 1. Says nothing about what it does |
| broker | stream registry | Implies a separate service to install and run, which is exactly what Ranvier is not |
| client / server | node, runtime | Implies a request-and-reply relationship that streams do not have |
| seam, node handle | (see below) | Two names for one boundary, both jargon |
| Flow | (nothing) | The retired name of a predecessor system |
| realtime (one word) | real-time, and say which kind | The unhyphenated form reads as marketing. concepts.md §8 has the three kinds |
| blazingly fast, powerful, seamless, intuitive | a number, or nothing | Unfalsifiable. If there is a figure, give the figure |
The rule that replaced "the seam"
There is a line through the system. Above it is your code; below it is the machinery that moves bytes. Neither the line nor the interface across it has a name, because two coined terms for one boundary were two too many.
What is left is the rule, stated as the promise it actually is:
Your node imports Ranvier and nothing else about how data moves. No sockets, no encoding formats, no clocks. That is what lets the transport, the encoding, and the clock be replaced without breaking a node anybody wrote.
The thing you create in code is a node — the same word the graph file uses for the same thing, because your program is one of the nodes in the graph.
This naming is provisional, and recorded as unresolved in deferred.md. The concept is settled; the word is not.
Words that carry more weight than they appear to
A reader may skim past these distinctions. Each one has cost somebody something.
- "Accepted" on a decision record means the argument is settled, not that the thing exists. Every record states its implementation status on its own second line.
- "Source" means entered the graph from outside it, not from an instrument. A web service and a replayed file are equally source data.
- "Declares" means a node states a fact about itself. "Chooses" means a user states a preference. Origin is declared; loss policy is chosen, and nothing derives one from the other.
- "Recorded, not verified" on an identity means Ranvier stored what it was told. It says who the application said was operating, never who was operating. That distinction is the one an auditor cares about.