Skip to content
C.W.K.
Stream
Lesson 01 of 05 · published

Whose Calendar Is That Date?

~12 min · timezone, bug, war-story, provenance

Level 0Raw Ore
0 XP0/36 lessons0/12 achievements
0/100 XP to next level100 XP to go0% complete
"Never stamp today's date on a snapshot."

The line that looks fine

Somewhere in every data-collecting system there is a line that says, in effect, data_date = date.today(). It passes review. It passes type checking. It reads as obviously correct: we are storing today's reading, so we store today's date.

It is only wrong when the machine's calendar and the subject's calendar are different things — and once you say it that way, the surprise is that anyone ever expects them to agree.

The specific collision

The daily loop fires at 07:11 Asia/Seoul. That hour was chosen for good reasons: safely after the US close in both summer and winter, comfortably before the Korean open. It is also 22:11 UTC on the previous day.

So on the morning of August 6th in Seoul, the loop fetched the US close — which was the session of August 5th in New York — and stamped it with the local date: August 6th. Every US gauge row in the store now claimed to describe a session that had not happened yet.

Nothing crashed. No test failed. The value was correct, the source string was correct, the fetch timestamp was correct. Exactly one field was wrong, and it was the field the entire read model sorts on.

The measurement that settled it
The fix was not argued into place, it was measured. At one instant on 2026-08-06, a US ETF proxy resolved to a session date of 2026-08-05 and a Tokyo-listed ETF resolved to 2026-08-06. Two listings, one moment, two different correct answers. That single observation kills every design that stamps one date across a multi-market pass, because it shows the disagreement is not an edge case — it is the normal state of a world with more than one exchange in it.

Why this class of bug is so quiet

Three properties combine, and they are worth recognizing in your own systems.

First, the wrong value is well-formed. It is a valid date, in range, in the right format. Every validation you would think to write passes.

Second, it is wrong by different amounts for different rows, and never uniformly. It is tempting to assume Seoul's date at least suited the Korean and Japanese gauges. It did not: those gauges are built on Tokyo-listed and US-listed ETF proxies, and at the moment the loop runs neither market has opened, so their newest completed session is also the previous day. Measured on the live engine, a pass finishing 22:11 UTC — 07:11 the next morning in Seoul — wrote US, Korean and Japanese rows all belonging to the same earlier session. The local date suited none of them. A defect that is wrong everywhere but by amounts that vary with the row does not look like a defect; it looks like a data source behaving oddly.

Third, the observer shares the defect. The developer reading the dashboard is also in Seoul, also thinking it is August 6th, and the number labelled August 6th looks exactly right to them. You cannot catch this by looking unless you already know to look.

A timestamp names two different things, and you must decide which one you are storing. There is the moment your process acted, and the moment the subject belongs to. They are different questions with different owners, and in any system that crosses a timezone, a schedule, or a batch boundary they will eventually disagree. Store both, and never let one impersonate the other.

Code

The wrong version and the right one, in a single-market and multi-market world·python
# WRONG -- and it looks completely reasonable:
row = {
    "symbol": symbol,
    "value": quote["close"],
    "data_date": datetime.date.today().isoformat(),  # WHOSE today?
    "source": f"provider:{symbol}",
}

# At 07:11 Asia/Seoul on 2026-08-06 this labels the 2026-08-05
# New York close as 2026-08-06. Valid date. Right format. Wrong day.


# RIGHT -- the target shape, not a quote of the shipped caller.
# (The engine does the first half and not the second; the next
#  lesson shows exactly where the disclosure goes missing.)
session = market.listing_close_date(info)   # from the provider
row = {
    "symbol": symbol,
    "value": quote["close"],
    "data_date": session or utc_today(),    # and SAY SO when guessed
    "source": f"provider:{symbol}",
    "fetched_at": db.utcnow(),              # our clock, kept separate
}

# Two fields, two questions:
#   data_date  -> which session does this describe?   (theirs)
#   fetched_at -> when did we ask?                    (ours)

External links

Exercise

Grep your own codebase for the equivalent of today() or now() being written into a stored record's business-meaning date field — not the audit timestamp, the field that says which day the record is about. For each hit, ask: could this code ever run on a machine whose calendar date differs from the subject's? A scheduled job, a batch that starts before midnight and finishes after, a queue consumer in another region — any of those is enough.
Hint
Search for date fields whose names describe the subject rather than the system: data_date, business_date, session_date, as_of, effective_date. If any of them is assigned from the local clock, you have this bug latent, and it will surface the first time the job moves or the schedule shifts.

Progress

Progress is local-only — sign in to sync across devices.
Spotted a bug or have feedback on this page?Report an Issue

Comments 0

🔔 Reply notifications (sign in)
Sign inPlease sign in to comment.

No comments yet — be the first.