Parsing time from the wild: a deterministic benchmark of consumer-export timestamp pathologies and the floating wall-clock model

Michal Planicka  ·  corresponding author — Tepna Project

Clock Contract (clock.js · DexClock), Tepna physiological-signal suite

Draft v1 · July 2026 · Analysis: timestamp-pathology-analysis.html (runs the production parser live) · Corpus: real vendor headers + synthetic edge cases · 100% local, deterministic

Keywords: timestamp parsing · data provenance · wall-clock time · timezone · DMY/MDY ambiguity · ISO-8601 · epoch time · consumer wearables · reproducibility · cross-device synchronization

1. Introduction

Physiological analysis papers report what happened at a time; almost none report how the time itself was parsed. Yet consumer device exports — the raw material of at-home physiology — encode time in mutually incompatible ways, and the default tools resolve them inconsistently. A single archive can contain an O2Ring oximeter writing HH:MM:SS DD/MM/YYYY, a Welltory CSV writing MM/DD/YYYY HH:MM, a Polar sensor logger writing zoned ISO-8601, and a filename embedding a bare YYYYMMDDHHMMSS. Handing any of these to new Date(str) invokes locale- and engine-dependent heuristics: it may read a European 13/05 correctly by luck and an American 05/13 wrongly, attach the parsing machine's timezone to a stamp that had none, or — most dangerously — return the current time for an unparseable input, silently fabricating a data point.

The synthetic-data-frontier perspective explicitly named this as the series' "narrowest first paper." This is that paper. Its contribution is not an algorithm but a stated standard: a single time model, the failure corpus it must survive, and a live tool that proves the shipping parser survives it. We make three claims: (i) the correct canonical unit for zone-less consumer physiology is a floating wall-clock, not a real UTC instant; (ii) every vendor format maps into it deterministically by explicit regex, never by locale heuristics; and (iii) a missing or malformed stamp must resolve to null, never to a fabricated time.

2. Methods

2.1 The canonical unit — floating wall-clock tMs

Each record's local civil time is stored encoded as if it were UTC: tMs = Date.UTC(year, month−1, day, hour, min, sec, ms). This is deliberately not a real UTC instant. Consumer devices speak local civil time with no zone; storing a real UTC instant and rendering it with local getters would make displayed time depend on the viewer's timezone (a New-York night reads 03:00 in London). Floating tMs read back with the getUTC* family is viewer-timezone-independent, and two devices recording the same wall-clock minute yield the same tMs by construction — so cross-device synchronization holds without either device sharing a timezone. An optional offsetMin is captured only when the input carried a real zone; the true instant is then recoverable as tMs − offsetMin·60000, but all sorting, alignment and display default to tMs.

2.2 Resolution order (the parser)

The single parser DexClock.parseTimestamp(raw, opts) resolves in a fixed priority, each branch an explicit regex — never Date.parse on a vendor string: (1) numeric epoch (10–13 digits or numeric type, plausible-range gated), localized to the parse-time zone; (2) ISO-8601 with zone — zone authoritative, re-expressed as wall clock with offsetMin captured; (3) ISO / YYYY-MM-DD[ T]HH:MM[:SS] without zone — components verbatim, offsetMin=null; (4) explicit vendor formats — HH:MM:SS DD/MM/YYYY (O2Ring), 14-digit compact, DD/MM/YYYY HH:MM (Welltory), YYYY/MM/DD HH:MM:SS; (5) time-only HH:MM[:SS] combined with a date anchor and rolled forward monotonically past each midnight; (6) fallback → null, never now().

2.3 DMY vs MDY disambiguation

Any row whose day-field exceeds 12 makes the file unambiguous, and that order is locked for the whole file; otherwise the caller's preferDMY hint decides (default true for O2Ring/Welltory, false for the CGM MDY convention). The order is never switched mid-file.

2.4 Benchmark construction

The corpus (Table 1) has one entry per parser branch and per vendor format observed in the suite's real exports, plus adversarial edge cases (implausible epoch, partial date, empty, garbage, anchorless time-only). The invariants (Table 2) encode the contract's behavioural guarantees. Both run against the production clock.js in timestamp-pathology-analysis.html; the pass counts below are read from that tool's live output (window.__tsbench).

3. Results

The production parser resolved 24 / 24 corpus cases and upheld 6 / 6 contract invariants — all green, regenerated live from the shipping code.

Invariant B1 deserves a precise statement: only the floating branches (2–5) are viewer-timezone-independent, and by construction — they never call getTimezoneOffset. The epoch branch (1) does consult the runner timezone, deliberately, because a bare epoch is a genuine instant that must be localized to a wall clock; that is the one place the viewer's zone legitimately enters, and it is confined there.

4. Discussion

The practical lesson is that timestamp parsing is a correctness surface, not a convenience call, and that the default library path is actively unsafe for consumer physiology on three counts: silent DMY/MDY mis-resolution, spurious timezone attachment, and fabrication-on-miss. The floating wall-clock model neutralizes the first two by construction (components-as-written + getUTC* read-back) and the third by contract (miss → null). The model's non-obvious move — storing local civil time as if UTC rather than as a real instant — is what buys viewer-timezone independence and zero-configuration cross-device alignment, the two properties every multi-signal result in this suite silently relies on. Because the benchmark is a live tool over the shipping parser rather than a frozen table, it doubles as a regression guard: any future parser change that breaks a vendor format or an invariant turns the tool red.