Refuse a date past the year 9999 before the arithmetic

[jwrosewell]

What was wrong

Versions 2 and 3 carry the creation date as an unsigned 32 bit count of minutes since 2020-01-01. The wire therefore allows up to 4,294,967,295 minutes, which lands on 15 February 10186. datetime.max is the last moment of the year 9999, so BASE_DATE + timedelta(minutes=minutes) in owid/parse.py raised OverflowError for any count from 4,197,074,400 upwards. A caller supplied envelope could make parse_bytes, parse_prefix and parse, which promise never to raise, raise.

The rule applied

The same bytes read fine in Java, PHP and JavaScript, whose date types reach that far, so the envelope is structurally consistent and the finding is this runtime's limit. That is what IMPLEMENTATION_CAPACITY_EXCEEDED means. The count is compared with the largest one datetime can hold before the arithmetic, never caught after it.

Before and after for a caller

Before, on an envelope whose four date bytes were FF FF FF FF:

Owid.parse_bytes(raw)
# raised OverflowError: date value out of range

After:

result = Owid.parse_bytes(raw)
# result.ok is False, result.owid is None,
# result.status is ParseStatus.IMPLEMENTATION_CAPACITY_EXCEEDED

The framed parse_prefix behaves the same way and consumes nothing. Every count up to 4,197,074,399 (9999-12-31 23:59) parses exactly as before, and nothing changes for creation.

Changes

• owid.io.MAXIMUM_MINUTES, derived from datetime.max so it cannot drift from the runtime.
• owid/parse.py compares the count with it before the addition and reports IMPLEMENTATION_CAPACITY_EXCEEDED. Version 1's two byte hour count reaches 65,535 hours, which is June 2027, so it has no guard and the comment says why.
• The ParseStatus.IMPLEMENTATION_CAPACITY_EXCEEDED documentation and the README status row now say what produces the status.
• tests/test_date_range.py covers the maximum count, the first count past the runtime, the last count inside it, the boundary constant against the runtime, and the version 1 maximum, on both reading contracts. In tests/test_parse_contract.py the test that named IMPLEMENTATION_CAPACITY_EXCEEDED unreachable now produces it, and MALFORMED_ENVELOPE keeps its own test as the one member still unreachable.

Verification

• python -m unittest discover -s tests, 111 tests before and 117 after, all passing.
• Neutralisation, with the guard disabled: 5 tests error with OverflowError: date value out of range (test_maximum_count_is_capacity_exceeded and test_first_count_beyond_the_runtime_is_capacity_exceeded on both contracts, and test_implementation_capacity_is_a_date_the_runtime_cannot_hold). Restored, all 117 pass.

Not changed

owid.io.Reader.read_date is the private raising reader kept only so the tests can pin its messages. It still raises OverflowError on such a count, which is consistent with a path that raises by design and is not reachable from the public surface.

Produced with AI assistance under James Rosewell's direction and needs human review.