Times Keep Microseconds and Always Serialize Six Fractional Digits
Context and Problem Statement
Every time this node creates is stored at whole seconds: the clock helper drops microseconds. The reason was one serialized form per instant. A time with microseconds serializes with a fractional second and a time without them does not, so two copies of the same instant could hold different strings and compare unequal. The case ledger hashes those strings, so a different string is a different record.
Whole seconds cost the order of acts.
Two activities that one actor sends within the same second carry equal published times.
The divergence-recovery rule had to treat an equal fault and acknowledgement time as a tie (#5253, PR #5447), and a helper exists only to bump a same-second stamp to the next second.
How does this node keep one string per instant at one offset without losing the order of acts inside one second?
Decision Drivers
- One instant, written by one node at one offset, must have one serialized form, because the ledger hashes and compares the text.
- Acts that one actor sends in order must carry times in that order where the clock can show it.
- A time carried from a peer keeps the offset it arrived with (CS-13-005), because a changed offset changes the recorded text.
- No backward compatibility is owed to stored or replicated data from before the change.
Considered Options
- Keep whole seconds. Times stay second-precise; ties inside a second stay ties.
- Microseconds, fixed form. Times keep microseconds, and every serialization writes exactly six fractional digits and an explicit offset, whether or not the microseconds are zero.
- Microseconds, shortest form. Times keep microseconds and serialize as the platform writes them: no fraction when the microseconds are zero, six digits otherwise.
Decision Outcome
Chosen option: "Microseconds, fixed form", because it meets the one-string-per-instant driver as fully as whole seconds do and keeps the order that whole seconds discard. Option 1 keeps the ties that #5253 had to work around. Option 3 restores the problem whole seconds were chosen to solve: a time whose microseconds happen to be zero serializes without a fraction, so one serializer can give two string shapes, and a peer that writes the other shape holds a different string for the same instant.
The decision has three parts:
- Precision. A time this node creates keeps its microseconds.
- One form. Every time this node serializes, whether it created the time or carries it from a peer, is written as an RFC 3339 date-time with exactly six fractional digits and an explicit offset.
A time this node creates carries a UTC offset, and a naive value is read as UTC before it is written (CS-13-001, CS-13-006).
A carried time keeps the offset it arrived with (CS-13-005); only its fraction is written in the fixed form.
Two spellings of one instant at different offsets therefore remain two strings, and two different records: that is CLP-15-007's "carry as received", not a gap in this decision.
This narrows the wording of ADR-0103, which takes a carried
publishedorupdatedas received at every boundary, rendering included: the instant and the offset are still the peer's, and only the number of fractional digits is this node's. ADR-0103's drivers hold unchanged — nothing is minted where a peer made no claim, and rendering one stored object twice still gives equal dicts — so that decision stands rather than being superseded. - One place. One formatting function writes the form, and every serialization path uses it: model JSON dumps, the case ledger's hash input, the genesis hash and the storage encoder.
A peer may still send times at whole seconds. The fixed form is what this node writes, not what it requires to receive.
Consequences
- Good: two acts one actor sends inside one second carry ordered times, so a same-second tie is rare rather than routine.
- Good: one instant written at one offset has one string, whether or not its microseconds are zero.
- Neutral: a rule that compares times a peer claimed must still treat a tie with care, because a peer may write whole seconds.
- Bad: every stored ledger hash and every wire example that pins a whole-second string changes; stores written before the change are reset rather than migrated.
Validation
- One instant at one offset serializes to one string whether or not its microseconds are zero.
- Every datetime field on a model serializes in the fixed form.
- Two clock reads inside one second compare in order.
- A carried time with a non-UTC offset keeps that offset in the fixed form.
More Information
The current rules live in the CS-13 group of specs/code-style.yaml.
They replace CS-13-003, which stored every time at whole seconds.
Generated spec requirements: code-style.yaml CS-13-007, CS-13-008.