A single reading tells you almost nothing.
Your heart rate right now is a fact without a reference. Is it high? Compared to what? A population average built from people who are not you, in conditions that are not yours, at a time of day that is not this one. The comparison is worse than useless, because it looks like information.
What actually means something is you, last Tuesday. You on a good week. You before the thing that changed.
That requires two things we did not have. Recordings solid enough to compare across months, and a way of scoring them that knows when it does not have enough to say. Over the last week of August we built both.
Sessions that survive the trip
A session is a recording: signals coming off a device, written down, kept, and read back later.
The hard part is that every step of that trip is a chance to lose fidelity. A device drops out mid-recording. A worker stalls. A schema changes between the version that wrote the file and the version reading it. Six months later you open a session and the numbers are subtly different from the ones you saw at the time, and you have no way to know which set was right.
So biosignal-session is built around a versioned wire protocol and Arrow chunks, recorded locally and kept on the machine that made them. Nothing has to leave your device for a session to be valid.
Two of us built this independently, in different branches, at the same time. Rather than delete one, we reconciled them and wrote down what got ported and why. Both versions had solved things the other had not.
Proving it instead of claiming it
Most of the work here was not writing the recorder. It was proving the recorder does what it says.
We generated golden fixtures and made every implementation conform to them. We read our Arrow chunks back with pyarrow and pandas, so the guarantee holds across languages rather than only inside our own code. We ran bit exact round trips and property based invariants.
We wrote a hostile client, a fake consumer that does everything wrong on purpose, and it found two real gaps in the host. We proved that memory used during recording does not grow with session length, so a four hour session costs what a four minute one does. We crossed every recoverable fault with every position in a session, because a dropout at the start and a dropout at minute ninety are different bugs. We confirmed chunks still read correctly after the schema evolves underneath them.
That is why this landed as sixty thousand lines. Roughly half of it is fixtures and tests.
Six scores, and the honest null
On top of sessions sits biosignal-analytics, which turns recordings into six numbers: measurement quality, activation, recovery, focus, readiness, and resilience.
Each is scored 0 to 100. Each can also be withheld, and when it is withheld the value is null rather than a polite middle number. This matters more than it sounds. A score of 50 with no data behind it is a lie that looks like a measurement, and every app downstream will render it as one.
When a score is withheld, it says why. Not enough baseline yet. Capture quality too poor. No activation detected. Inputs missing. Not enough history for a longitudinal read. An app can show the reason instead of showing a number, which is both more honest and more useful, because the reason usually tells you what to do about it.
Underneath, we moved the pulse and activation maths into Rust and exposed the analyzers to the browser through WebAssembly, with Python oracles pinning the Rust results so the two agree.
Back to the baseline
The last piece is the one the rest exists for.
Scores are computed against a rolling personal baseline, built from your own recent sessions, bucketed by context so a morning reading is compared to your mornings. Outliers are handled robustly, so one bad night does not drag the reference with it. Until enough history exists to make that comparison real, the score stays withheld.
Which means the first week is quiet by design. We think that is correct. A number you can trust in week three is worth more than a number you cannot trust on day one.
Where this stands
biosignal-session and biosignal-analytics are merged into main at 0.1.0 and are not on npm yet. The source is at github.com/Elata-Biosciences/elata-bio-sdk if you want to read the protocol or the fixtures before we cut the release.
If you are building on this, the question we most want thrown at us is which of the six scores you would refuse to trust, and what would have to be true for you to change your mind.