0009: Timestamps and clocks
Status: Accepted. Item 2 amended by decision 0012.
Context
The prototype uses absolute UTC times in match and game headers (2026-10-31T10:16:13.418Z) and m:ss elapsed game time on event lines (1:52). Many events share a second, so line order is the real sequence, but this is not stated. [Clock "25"] hints at MTGO's 25-minute per-player chess clock, but the time each player has left is never recorded.
Time matters differently by source. On MTGO each player has a chess clock, and running out of time loses the game. In paper Magic there is usually only a round timer, and running out of time can end a match in a draw. MTGOSDK (checked at v1.7.0) exposes GamePlayer.ChessClock, "the amount of time left on the player's clock", and Tournament.TimeRemaining for round time.
Decision
- Line order is the authoritative sequence. Events happen in the order they are written. Timestamps are informational and MUST NOT be used to order events.
- Header times are absolute UTC times in ISO 8601.
- Event times are elapsed time since the game started, at whatever precision the source provides (whole seconds or finer).
- Clocks are optional and recorded only when the source has them. Two kinds are supported:
- per-player clocks (MTGO, Arena): the time each player has left is recorded in each keyframe and at each priority change, so a replay can show time pressure and losses on time;
- a round or match timer (paper tournaments, MTGO rounds): the time limit is a header, and the time remaining is recorded in each keyframe. A file from a source without clocks simply has no clock data. This is not an incompleteness.
Rules basis
The Comprehensive Rules (effective 2026-09-25) do not cover time limits or clocks; those belong to tournament policy. This decision is a format choice.
Alternatives rejected
- Timestamps as the ordering key. Rejected: many events share a timestamp at the precision sources provide.
- Absolute times on every event. Rejected: long, hard to read, and elapsed game time is what readers care about.
- Requiring clock data. Rejected: paper Magic and other sources without per-player clocks could never produce a complete file.
- Clock data only in keyframes. Rejected: time spent within a turn, on each priority decision, is what shows time pressure.
Consequences
- The spec must define the elapsed-time format and both clock kinds, and state that clock data being absent is not an incompleteness.
[Clock "25"]from the prototype is replaced by a defined clock header.