straplog 0.2.0__tar.gz

straplog-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+# Build, test, and publish to PyPI on a version tag (v0.2.0, ...).
+# Auth is PyPI trusted publishing (OIDC): no token in the repo. The PyPI
+# publisher is registered as personalscience/straplog-py, publish.yml, env `pypi`.
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - name: Tag matches package version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv run --group dev pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

straplog-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+dist/
+.venv/
+*.sqlite
+.claude/settings.local.json
+.claude/skills/
+.claude/rules/

straplog-0.2.0/CLAUDE.md

@@ -0,0 +1,20 @@
+# CLAUDE.md — straplog-py
+
+Public Python package `straplog` (PyPI): reads StrapLog iOS-app exports (Polar H10 RR in SQLite) and holds the shared HRV algorithms for the StrapLog skills (`personalscience/straplog-skills`). Split out of the app repo's `tools/py` on 2026-10-18 with history.
+
+## Commands
+
+```
+uv run --group dev pytest -q · uv build · uv publish (TestPyPI first)
+```
+
+## Rules that the tree does not tell you
+
+- The file format contract is `docs/SCHEMA.md` in the StrapLog app repo (`~/dev/ios projects/straplog`), enforced there by `SchemaTests.docsMatch`. A schema bump lands in the app first, then here.
+- `straplog.hrv` must stay format-agnostic: no imports from `db`/`export`.
+- Metric semantics are fixed for log continuity (hrv-resting's CSV log): ddof=1, `hr_mean` = mean of beat HRs. Changing them is a breaking change.
+- Never commit real exports (`*.sqlite` is ignored): they are personal health data. Tests use synthetic fixtures (`tests/conftest.py`).
+
+## Vault
+
+- Plan: `~/.claude/plans/straplog-skills-consolidation.md`

straplog-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Richard Sprague / Personal Science, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

straplog-0.2.0/PKG-INFO

@@ -0,0 +1,74 @@
+Metadata-Version: 2.5
+Name: straplog
+Version: 0.2.0
+Summary: Read StrapLog exports (Polar H10 RR intervals in SQLite) and compute HRV: library and CLI.
+Project-URL: Homepage, https://github.com/personalscience/straplog-py
+Author: Richard Sprague
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dfa-alpha1,heart-rate-variability,hrv,polar-h10,rr-intervals
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
+Requires-Python: >=3.11
+Requires-Dist: numpy
+Requires-Dist: pandas
+Provides-Extra: plot
+Requires-Dist: plotnine; extra == 'plot'
+Description-Content-Type: text/markdown
+
+# straplog
+
+Read [StrapLog](https://github.com/personalscience) exports and compute heart-rate variability.
+
+StrapLog is an iOS app that records beat-to-beat RR intervals from a Polar H10 chest strap. It writes each recording as one self-contained SQLite file (`<YYMMDD-HHMM>-<name>.sqlite`) to its iCloud folder, plus an `index.json` catalog. This package reads those files and provides the HRV algorithms used by the StrapLog Claude Code skills.
+
+## Install
+
+```sh
+uv add straplog            # or: pip install straplog
+uv add 'straplog[plot]'    # + the plotnine house chart style
+```
+
+## Use
+
+```python
+from straplog import db, hrv
+
+recs = db.list_recordings("251018-0712-REST.sqlite")
+rr, events, start_local, name = db.load_recording("251018-0712-REST.sqlite", recs[0]["pk"])
+
+clean = hrv.clean_rr(rr["rr_ms"], pct_thresh=0.20)
+hrv.time_domain(clean)        # n, hr_mean, sdnn_ms, rmssd_ms, ln_rmssd, pnn50_pct, ...
+hrv.dfa_alpha1(clean)
+hrv.rolling_features(rr)      # 2-min windows, 1-min stride: hr_bpm, alpha1, rmssd
+```
+
+| Module | Role |
+|---|---|
+| `straplog.export` | A file as stored: epoch ms UTC, typed events |
+| `straplog.catalog` | List a folder of exports via `index.json` |
+| `straplog.db` | Load beats and markers as DataFrames in local time |
+| `straplog.hrv` | Artifact filter, time-domain metrics, DFA α1, sliding windows. Works on any RR series |
+| `straplog.plot` | House chart style (plotnine; `plot` extra) |
+| `straplog.cli` | `straplog ls / rr / events / meta` |
+
+## CLI
+
+```sh
+straplog ls --activity sleep --since 14d
+straplog rr 251018-0712-REST --json
+straplog events 251018-0712-REST --markers
+```
+
+A bare export name resolves against the StrapLog iCloud folder.
+
+## Conventions
+
+- RR in ms. The H10 sends RR in 1/1024 s; `rr_1024` is canonical in the file and `rr_ms` is derived.
+- SDNN, SDSD and HR SD are sample statistics (ddof=1). `hr_mean` is the mean of per-beat HR, not `60000 / mean_rr_ms`.
+- The artifact filter applies a 300–2000 ms gate, then an iterative 5-beat median filter. The default threshold is 0.25 (workouts); use 0.20 for resting readings.
+
+## License
+
+MIT

straplog-0.2.0/README.md

@@ -0,0 +1,55 @@
+# straplog
+
+Read [StrapLog](https://github.com/personalscience) exports and compute heart-rate variability.
+
+StrapLog is an iOS app that records beat-to-beat RR intervals from a Polar H10 chest strap. It writes each recording as one self-contained SQLite file (`<YYMMDD-HHMM>-<name>.sqlite`) to its iCloud folder, plus an `index.json` catalog. This package reads those files and provides the HRV algorithms used by the StrapLog Claude Code skills.
+
+## Install
+
+```sh
+uv add straplog            # or: pip install straplog
+uv add 'straplog[plot]'    # + the plotnine house chart style
+```
+
+## Use
+
+```python
+from straplog import db, hrv
+
+recs = db.list_recordings("251018-0712-REST.sqlite")
+rr, events, start_local, name = db.load_recording("251018-0712-REST.sqlite", recs[0]["pk"])
+
+clean = hrv.clean_rr(rr["rr_ms"], pct_thresh=0.20)
+hrv.time_domain(clean)        # n, hr_mean, sdnn_ms, rmssd_ms, ln_rmssd, pnn50_pct, ...
+hrv.dfa_alpha1(clean)
+hrv.rolling_features(rr)      # 2-min windows, 1-min stride: hr_bpm, alpha1, rmssd
+```
+
+| Module | Role |
+|---|---|
+| `straplog.export` | A file as stored: epoch ms UTC, typed events |
+| `straplog.catalog` | List a folder of exports via `index.json` |
+| `straplog.db` | Load beats and markers as DataFrames in local time |
+| `straplog.hrv` | Artifact filter, time-domain metrics, DFA α1, sliding windows. Works on any RR series |
+| `straplog.plot` | House chart style (plotnine; `plot` extra) |
+| `straplog.cli` | `straplog ls / rr / events / meta` |
+
+## CLI
+
+```sh
+straplog ls --activity sleep --since 14d
+straplog rr 251018-0712-REST --json
+straplog events 251018-0712-REST --markers
+```
+
+A bare export name resolves against the StrapLog iCloud folder.
+
+## Conventions
+
+- RR in ms. The H10 sends RR in 1/1024 s; `rr_1024` is canonical in the file and `rr_ms` is derived.
+- SDNN, SDSD and HR SD are sample statistics (ddof=1). `hr_mean` is the mean of per-beat HR, not `60000 / mean_rr_ms`.
+- The artifact filter applies a 300–2000 ms gate, then an iterative 5-beat median filter. The default threshold is 0.25 (workouts); use 0.20 for resting readings.
+
+## License
+
+MIT

straplog-0.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "straplog"
+version = "0.2.0"
+description = "Read StrapLog exports (Polar H10 RR intervals in SQLite) and compute HRV: library and CLI."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Richard Sprague" }]
+requires-python = ">=3.11"
+dependencies = ["numpy", "pandas"]
+keywords = ["hrv", "polar-h10", "rr-intervals", "dfa-alpha1", "heart-rate-variability"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Medical Science Apps.",
+    "Intended Audience :: Science/Research",
+]
+
+[project.optional-dependencies]
+plot = ["plotnine"]
+
+[project.urls]
+Homepage = "https://github.com/personalscience/straplog-py"
+
+[project.scripts]
+straplog = "straplog.cli:main"
+
+[dependency-groups]
+dev = ["pytest", "plotnine"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

straplog-0.2.0/src/straplog/__init__.py

@@ -0,0 +1,10 @@
+"""Read StrapLog exports: one single-file SQLite snapshot per recording.
+
+`straplog.export` reads a file as stored (epoch ms UTC, typed markers);
+`straplog.catalog` lists a folder of exports; `straplog.db` loads into the
+HRV skills' Apple-epoch local-time convention; `straplog.hrv` holds the
+format-agnostic HRV algorithms; `straplog.plot` is the house chart style
+(needs the `plot` extra); `straplog.cli` is the agent tool surface.
+The schema is docs/SCHEMA.md in the StrapLog app repo.
+"""
+__version__ = "0.2.0"

straplog-0.2.0/src/straplog/_sqlite.py

@@ -0,0 +1,26 @@
+"""Opening a StrapLog export safely."""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+
+def connect(db_path: Path) -> sqlite3.Connection:
+    """Open read-only and immutable: no -wal/-shm is ever created beside the
+    user's export."""
+    return sqlite3.connect(f"{Path(db_path).resolve().as_uri()}?immutable=1",
+                           uri=True)
+
+
+def require_snapshot(db_path: Path) -> None:
+    """A StrapLog -wal means the live database, which an immutable read would
+    see only partly. Exports are always single files."""
+    if Path(str(db_path) + "-wal").exists():
+        raise SystemExit(
+            f"{db_path} has a -wal sidecar, so it is StrapLog's live database. "
+            "Use an exported snapshot (iCloud Drive > StrapLog > <date>-<name>.sqlite, on the Mac "
+            "~/Library/Mobile Documents/iCloud~com~personalscience~straplog/Documents/).")
+
+
+def columns(con: sqlite3.Connection, table: str) -> set[str]:
+    return {r[1] for r in con.execute(f"PRAGMA table_info({table})")}

straplog-0.2.0/src/straplog/catalog.py

@@ -0,0 +1,67 @@
+"""Find recordings in a folder of exports: `index.json` first, then a scan.
+
+The app rewrites `index.json` after every export and delete (ExportIndex),
+so an agent reads one file instead of opening each snapshot. Exports the
+index does not list (older builds, files copied in from elsewhere) are
+read directly, each as the recording it is named after, so a folder without
+an index still lists completely and without duplicates.
+"""
+from __future__ import annotations
+
+import json
+import re
+import time
+from datetime import datetime
+from pathlib import Path
+
+from . import export
+
+DEFAULT_DIR = Path.home() / "Library/Mobile Documents/iCloud~com~personalscience~straplog/Documents"
+INDEX = "index.json"
+
+
+def entries(where: Path = DEFAULT_DIR) -> list[dict]:
+    """Index entries, newest first, each with `path` and `downloaded` added.
+    `where` is a folder of exports or a single export file."""
+    where = Path(where).expanduser()
+    if where.is_file():
+        return [_located(e, where.parent) for e in export.recordings(where)]
+    indexed = []
+    if (where / INDEX).exists():
+        indexed = json.loads((where / INDEX).read_text())["recordings"]
+    listed = {e["file"] for e in indexed}
+    scanned = [e for f in sorted(where.glob("*.sqlite")) if f.name not in listed
+               for e in export.recordings(f, named_only=True)]
+    rows = [_located(e, where) for e in indexed + scanned]
+    return sorted(rows, key=lambda e: (e["started_at_ms"], e["id"]), reverse=True)
+
+
+def select(rows: list[dict], activity: str | None = None, since: str | None = None,
+           limit: int | None = None, now_ms: int | None = None) -> list[dict]:
+    if activity:
+        rows = [e for e in rows if e["activity"] == activity]
+    if since:
+        cutoff = since_ms(since, now_ms if now_ms is not None else int(time.time() * 1000))
+        rows = [e for e in rows if e["started_at_ms"] >= cutoff]
+    return rows[:limit] if limit else rows
+
+
+def since_ms(since: str, now_ms: int) -> int:
+    """`14d`, `12h`, `90m` back from now, or an ISO date/time (local if naive)."""
+    m = re.fullmatch(r"(\d+)([dhm])", since)
+    if m:
+        return now_ms - int(m[1]) * {"d": 86_400_000, "h": 3_600_000, "m": 60_000}[m[2]]
+    return int(datetime.fromisoformat(since).astimezone().timestamp() * 1000)
+
+
+def resolve(file: str, folder: Path | None = None) -> Path:
+    """A path, or a bare export name looked up in `folder` (default DEFAULT_DIR)."""
+    p = Path(file).expanduser()
+    if p.exists() or p.parent != Path("."):
+        return p
+    return Path(folder or DEFAULT_DIR) / file
+
+
+def _located(entry: dict, folder: Path) -> dict:
+    path = folder / entry["file"]
+    return {**entry, "path": str(path), "downloaded": path.exists()}

straplog-0.2.0/src/straplog/cli.py

@@ -0,0 +1,101 @@
+"""`straplog`: the agent tool surface over StrapLog exports.
+
+    straplog ls [FOLDER|FILE] [--activity sleep] [--since 14d] [--limit N] [--json]
+    straplog rr FILE [--id N] [--json]          beats: t_ms, rr_ms
+    straplog events FILE [--id N] [--markers] [--json]
+    straplog meta FILE
+
+FILE is a path or a bare export name in the iCloud folder. Times are epoch ms
+UTC; local time = UTC + tz_offset_s (`ls` prints it as `started_local`).
+Tables print as CSV unless --json.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+from . import catalog, export
+
+LS_COLUMNS = ("started_local", "activity", "name", "duration_ms", "beats", "coverage", "labels", "file")
+
+
+def main(argv: list[str] | None = None) -> None:
+    args = _parser().parse_args(argv)
+    args.run(args)
+
+
+def _ls(args) -> None:
+    rows = catalog.select(catalog.entries(args.where), args.activity, args.since, args.limit)
+    if args.json:
+        _json(rows)
+    else:
+        _csv([{**r, "labels": " ".join(r["labels"])} for r in rows], LS_COLUMNS)
+
+
+def _rr(args) -> None:
+    _table(export.beats(_file(args), args.id), ("t_ms", "rr_ms"), args.json)
+
+
+def _events(args) -> None:
+    _table(export.events(_file(args), args.id, args.markers), ("at_ms", "kind", "label", "note"), args.json)
+
+
+def _meta(args) -> None:
+    path = _file(args)
+    _json({"meta": export.meta(path), "recordings": export.recordings(path)})
+
+
+def _file(args) -> Path:
+    path = catalog.resolve(args.file)
+    if not path.exists():
+        raise SystemExit(f"No such export: {path}")
+    return path
+
+
+def _table(rows: list[dict], cols: tuple[str, ...], as_json: bool) -> None:
+    _json(rows) if as_json else _csv(rows, cols)
+
+
+def _json(value) -> None:
+    json.dump(value, sys.stdout, indent=2, ensure_ascii=False)
+    sys.stdout.write("\n")
+
+
+def _csv(rows: list[dict], cols: tuple[str, ...]) -> None:
+    w = csv.DictWriter(sys.stdout, cols, extrasaction="ignore", lineterminator="\n")
+    w.writeheader()
+    w.writerows(rows)
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="straplog", description=__doc__,
+                                formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(required=True, metavar="COMMAND")
+
+    ls = sub.add_parser("ls", help="list recordings, newest first")
+    ls.add_argument("where", nargs="?", type=Path, default=catalog.DEFAULT_DIR,
+                    help="folder of exports or one export (default: the iCloud folder)")
+    ls.add_argument("--activity", help="e.g. sleep, other")
+    ls.add_argument("--since", help="14d, 12h, 90m, or an ISO date")
+    ls.add_argument("--limit", type=int)
+    ls.add_argument("--json", action="store_true")
+    ls.set_defaults(run=_ls)
+
+    for name, run, help_ in (("rr", _rr, "beats: t_ms, rr_ms"),
+                             ("events", _events, "events: at_ms, kind, label, note"),
+                             ("meta", _meta, "meta table and index entry, as JSON")):
+        c = sub.add_parser(name, help=help_)
+        c.add_argument("file")
+        c.set_defaults(run=run)
+        if name != "meta":
+            c.add_argument("--id", type=int, help="recording id (only for multi-recording files)")
+            c.add_argument("--json", action="store_true")
+    sub.choices["events"].add_argument("--markers", action="store_true", help="markers only")
+    return p
+
+
+if __name__ == "__main__":
+    main()

straplog-0.2.0/src/straplog/db.py

@@ -0,0 +1,183 @@
+"""Read a StrapLog export in the HRV Logger loaders' conventions.
+
+StrapLog (the Polar H10 logger in ~/dev/iOS Projects/StrapLog) writes a
+single-file SQLite snapshot: `recording`, `notification`, `beat`, `event`,
+`motion`, `meta` (its docs/SCHEMA.md is the source of truth). Its times are
+Unix epoch ms UTC plus a per-recording `tz_offset_s`.
+
+The HRV Logger loaders in these skills work in Apple-epoch seconds of LOCAL
+wall-clock (Core Data stored local time as if it were UTC). This module maps
+StrapLog onto that convention, so every analysis downstream is unchanged:
+
+    t = (t_end_ms_est / 1000 + tz_offset_s) - 978307200
+
+Skills import it as `import straplog.db as straplog_db`; this replaced the
+copies `_hrv_shared/sync.sh` used to push into each skill's scripts/.
+"""
+from __future__ import annotations
+
+import sqlite3
+from pathlib import Path
+
+import numpy as np
+import pandas as pd
+
+from ._sqlite import columns, connect as _connect, require_snapshot as _require_snapshot
+
+APPLE_EPOCH_OFFSET = 978307200.0   # 2001-01-01 -> unix
+# Consecutive H10 notifications arrive ~1 s apart; a longer silence is a
+# Bluetooth dropout, and that time counts against coverage.
+NOTIFICATION_GAP_SEC = 3.0
+
+
+def is_straplog(db_path: Path) -> bool:
+    """True for a StrapLog file (it has a `beat` table); False for HRV Logger."""
+    con = _connect(db_path)
+    try:
+        return con.execute(
+            "SELECT 1 FROM sqlite_master WHERE type='table' AND name='beat'"
+        ).fetchone() is not None
+    finally:
+        con.close()
+
+
+def _local_apple(ms, tz_offset_s):
+    return ms / 1000.0 + tz_offset_s - APPLE_EPOCH_OFFSET
+
+
+def _recording(con: sqlite3.Connection, rid: int) -> dict:
+    row = con.execute(
+        "SELECT name, started_at_ms, ended_at_ms, tz_offset_s FROM recording "
+        "WHERE id=?", (rid,)).fetchone()
+    if row is None:
+        raise SystemExit(f"Recording {rid} not found.")
+    return dict(zip(("name", "started_at_ms", "ended_at_ms", "tz_offset_s"), row))
+
+
+def _coverage(received_ms: np.ndarray, start_ms: int, end_ms: int) -> float | None:
+    """Fraction of the recording's wall-clock span covered by notifications:
+    the sum of inter-notification intervals no longer than
+    NOTIFICATION_GAP_SEC, over end - start. Time before the first and after
+    the last notification is uncovered."""
+    span = end_ms - start_ms
+    if span <= 0 or received_ms.size < 2:
+        return None
+    d = np.diff(received_ms)
+    return float(d[d <= NOTIFICATION_GAP_SEC * 1000].sum() / span)
+
+
+def coverage(db_path: Path, rid: int) -> float | None:
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        rec = _recording(con, rid)
+        rx = np.array([r[0] for r in con.execute(
+            "SELECT received_at_ms FROM notification WHERE recording_id=? "
+            "ORDER BY id", (rid,))], dtype=float)
+    finally:
+        con.close()
+    end = rec["ended_at_ms"] or (int(rx[-1]) if rx.size else rec["started_at_ms"])
+    return _coverage(rx, rec["started_at_ms"], end)
+
+
+def list_recordings(db_path: Path) -> list[dict]:
+    """One dict per recording with the keys the HRV Logger listers share:
+    pk, name, start_local (ISO, local wall-clock), n_beats, duration_min,
+    avg_hr, coverage. Each skill adds its own extra keys."""
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        recs = con.execute(
+            "SELECT id, name, started_at_ms, ended_at_ms, tz_offset_s "
+            "FROM recording ORDER BY started_at_ms").fetchall()
+        beats = {r[0]: r[1:] for r in con.execute(
+            "SELECT recording_id, COUNT(*), AVG(rr_ms) FROM beat "
+            "GROUP BY recording_id")}
+        rx: dict[int, list[int]] = {}
+        for rid, ms in con.execute(
+                "SELECT recording_id, received_at_ms FROM notification ORDER BY id"):
+            rx.setdefault(rid, []).append(ms)
+    finally:
+        con.close()
+
+    out = []
+    for rid, name, start_ms, end_ms, tz in recs:
+        n, mean_rr = beats.get(rid, (0, None))
+        r = np.array(rx.get(rid, []), dtype=float)
+        end = end_ms or (int(r[-1]) if r.size else start_ms)
+        cov = _coverage(r, start_ms, end)
+        out.append({
+            "pk": rid,
+            "name": name or "",
+            "start_local": pd.to_datetime(start_ms + tz * 1000, unit="ms").isoformat(),
+            "n_beats": int(n),
+            "duration_min": round((end - start_ms) / 60000.0, 1),
+            "avg_hr": round(60000.0 / mean_rr, 1) if mean_rr else None,
+            "coverage": None if cov is None else round(cov, 3),
+        })
+    return out
+
+
+def load_rr(db_path: Path, rid: int) -> pd.DataFrame:
+    """Beats as DataFrame[t, rr_ms], t in Apple-epoch local seconds.
+
+    Ordered by beat id (true beat order). The H10 sends no beat timestamps, so
+    `t_end_ms_est` is anchored on phone receipt, and BLE delivery jitter
+    leaves ~2 % of beats up to ~0.9 s earlier than the beat before. `t` is
+    clamped non-decreasing so window and gap logic never sees time run
+    backwards; rr_ms itself is exact.
+    """
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        tz = _recording(con, rid)["tz_offset_s"]
+        rr = pd.read_sql_query(
+            "SELECT t_end_ms_est AS t, rr_ms FROM beat WHERE recording_id=? "
+            "ORDER BY id", con, params=(rid,))
+    finally:
+        con.close()
+    rr["t"] = _local_apple(rr["t"].astype(float).cummax(), tz)
+    return rr
+
+
+def load_events(db_path: Path, rid: int) -> pd.DataFrame:
+    """User markers as DataFrame[t, note]: StrapLog's `marker` events, which
+    are what HRV Logger's ZEVENT rows were. Lifecycle events (start, connect,
+    snapshot, ...) are not user notes and are left out.
+
+    From schema v3 a marker has a preset `label` (`a`, `awake`, ...), a free
+    `note`, or both; `note` here is the label, then ` · note` if both, which
+    matches v2 files where the label was the note."""
+    _require_snapshot(db_path)
+    con = _connect(db_path)
+    try:
+        tz = _recording(con, rid)["tz_offset_s"]
+        cols = columns(con, "event")
+        text = ("COALESCE(label || COALESCE(' · ' || note, ''), note, '')"
+                if "label" in cols else "COALESCE(note, '')")
+        ev = pd.read_sql_query(
+            f"SELECT at_ms AS t, {text} AS note FROM event "
+            "WHERE recording_id=? AND kind='marker' ORDER BY at_ms",
+            con, params=(rid,))
+    finally:
+        con.close()
+    ev["t"] = _local_apple(ev["t"].astype(float), tz)
+    return ev
+
+
+def load_recording(db_path: Path, rid: int):
+    """(rr[t, rr_ms, t_rel], ev[t, note, t_rel], start_local, name), the shape
+    of h10-session's HRV Logger `load_recording`. t_rel is seconds from the
+    first beat; start_local is a naive local-wall-clock Timestamp."""
+    rr = load_rr(db_path, rid)
+    ev = load_events(db_path, rid)
+    con = _connect(db_path)
+    try:
+        name = _recording(con, rid)["name"] or ""
+    finally:
+        con.close()
+    t0 = rr["t"].iloc[0] if len(rr) else 0.0
+    rr["t_rel"] = rr["t"] - t0
+    ev["t_rel"] = ev["t"] - t0
+    start_local = pd.to_datetime(t0 + APPLE_EPOCH_OFFSET, unit="s")
+    return rr, ev, start_local, name