A timestamp gate for an earnings scorecard: reject observations made after the release

An earnings comparison can look reasonable while using information that was unavailable before the announcement. A useful first check is temporal: was the expected move actually captured before the event, and has the chosen outcome window finished?

Disclosure: this article was generated with AI. I work on SIGNUM HQ. The Python below is a standalone example using synthetic timestamps, not a description of our production implementation or a claim about forecasting performance.

The example accepts a comparison only when the observation precedes the release and the outcome window is complete.

def comparable(snapshot_at, release_at, outcome_ready_at, now):
    stamps = (snapshot_at, release_at, outcome_ready_at, now)
    if any(t.tzinfo is None or t.utcoffset() is None for t in stamps):
        raise ValueError("timezone required")
    return snapshot_at < release_at <= outcome_ready_at <= now

The strict inequality at the first boundary is intentional. An observation stamped exactly at the release is not sufficient evidence that it was available beforehand. A delayed retrieval of an older observation is different: retain the original observation timestamp instead of replacing it with retrieval time.

Using timezone-aware synthetic UTC timestamps, the local exercise checks five cases: a valid completed window, a post-release observation, an incomplete outcome, an outcome ending before the release, and a timestamp without a timezone. Reproduction: running the example file under Python 3.9.6 on my machine printed scorecard_cutoff: 5 cases passed. No market API is called by the example.

This gate is deliberately small. It cannot verify that a feed's timestamp is truthful, select the correct options expiry, establish whether prices are adjusted consistently, or decide which return window makes sense. Those definitions belong in the comparison record too.

Missing results should remain missing. A stock that has not completed the selected outcome window is not an observation of zero movement. Similarly, “inside the expected magnitude” is not a profitable options trade or a correct directional prediction.

For a real scorecard, I would keep the pre-event reference, release timestamp, expiry, outcome definition and data revision together. That makes the comparison inspectable before anyone summarizes it as a hit rate.

Reference: Python aware and naive datetime objects.

Product context, from the team that wrote this example: Earnings verification receipts, a public page that keeps the pre-announcement record, expiry and outcome window next to each comparison.