A measurement that leaves nothing behind is a script. What makes a run something you can resume, watch, hand to a colleague and read back in three years is the directory it writes.
The run directory
<run_root>/<run_id>/ run_id = <name>_<YYYYmmdd-HHMMSS>
├── plan.json the frozen schedule + config, content-hashed
├── journal.jsonl append-only event log
├── records.jsonl one line per completed step
└── data/ arrays and blobs the records reference
Three files, all append-only or written once, all plain text. Nothing here needs a database, a server or a running process to be read — which is what lets a monitor, an analysis and a re-render all read the same run without coordinating with each other or with the experiment.
plan.json is decided before the first step. The whole schedule and the
configuration that produced it are written down and content-hashed. Resuming
rebuilds the plan and compares hashes, so a configuration edited halfway
through is refused rather than quietly stitched into the middle of a
measurement.
journal.jsonl and records.jsonl answer different questions. The
journal is what happened — started, resumed, failed, finished. The records
are what was measured, one line per completed step. A step appears in
records.jsonl only once it is fully persisted, which is why the write is the
commit: a line exists, or the step did not finish. That property is what a
live view relies on when it tails the file (see
Live Views).
Every record carries its own provenance — which step produced it, calling what, with which arguments — so a row can be traced back to the plan that asked for it without keeping the plan open beside it.
Blobs never cross the network
A spectrometer frame is 1340 numbers; a camera image is far more. Sending those back through the device server to the experiment PC, so the experiment can write them to a disk, wastes the network twice over and makes the acquiring machine wait.
So it does not happen. The instrument writes its own files to a shared disk, and the record carries only the path.
That is a platform-wide rule, not an experiment's choice, and it explains several things that otherwise look odd: why a device is told where to write rather than asked for its data, why records reference files instead of containing them, and why a monitor needs a frame reader at all.
One disk, two spellings
The consequence of that rule is that a path written by one machine has to be
readable by another — and the same disk is rarely spelled the same way twice.
The acquiring PC may know it as D:\data while the analysis machine calls it
/Volumes/lab-data.
The share is therefore named twice, by environment:
PLESTY_DATA_DIR |
The share as the acquiring host writes it |
PLESTY_DATA_MOUNT |
The same share as this machine reads it |
Both spellings are journaled when the run starts. Any machine that opens the run later can translate a recorded path into its own view of the disk without being told anything further — which is why a viewer opened on a laptop can read frames an instrument PC wrote under a drive letter that laptop has never had.
On a one-machine bench the two are equal and the translation does nothing. The code that works across a lab is the same code.
Read next
- Build an Experiment — plans, step operations, retries, and resume in practice.
- Live Views — how a monitor reads a run while it is still being written.
- The Bench — what is running on the machine the instruments are plugged into.