Datetime64 Overflow Verdict

Decides whether a date survives conversion to nanosecond resolution, AND WHAT IT BECOMES. Pure function: no numpy, no pandas, no I/O.

Measured against numpy 2.5.1, numpy 1.26.4 and pandas 3.0.5. NOT a numpy or pandas bug report.

THE MEASUREMENT:

    np.datetime64('9999-12-31', 'ns') -> 1816-03-29T05:56:08.066277376
    np.datetime64('1000-01-01', 'ns') -> 2169-02-08T23:09:07.419103232
    np.datetime64('2262-04-12', 'ns') -> 1677-09-21T00:25:26.290448384
    np.datetime64('0001-01-01', 'ns') -> 1754-08-30T22:43:41.128654848

No error, no warning. Each result is a real date -- just not yours -- so no schema check, no null check and no range check downstream can distinguish it from a correct one.

9999-12-31 IS THE VALUE THAT MATTERS. It is the "never expires" sentinel hardcoded across SQL Server high-dates, licence expiry columns, "forever" contract terms and ported COBOL-style records. It becomes 1816-03-29, a date in the PAST -- which INVERTS the comparison the sentinel exists to serve. Every "is this still valid?" test now answers the opposite.

THE WRAPPED VALUE IS COMPUTED, NOT LOOKED UP. This package performs the same two's-complement arithmetic numpy does, and its tests assert the result against numpy's REAL OUTPUT for every case above. The arithmetic cannot drift from the library without the suite going red.

THE SAME LIBRARY DISAGREES WITH ITSELF, AND YOUR VERSION DECIDES:

    numpy 2.5.1    astype -> RAISES OverflowError    constructor -> wraps silently
    numpy 1.26.4   astype -> wraps silently          constructor -> wraps silently

On numpy 2.x one code path bounds-checks and one does not -- same library, same value, and the difference is which function you happened to call. ON NUMPY 1.x THERE IS NO LOUD PATH AT ALL: nothing in numpy will ever tell you, and the only refusal available is pandas'. It also means an upgrade changes behaviour in the least expected direction -- code that was silently corrupting dates starts raising, which reads as "the upgrade broke it" rather than "the upgrade found it". The verdict is UNDECIDABLE when the major is unknown, rather than assuming the version that happens to be loud.

PANDAS RAISES -- ON TWO OF THREE PATHS:

    pd.Timestamp('9999-12-31').as_unit('ns')         -> RAISES OutOfBoundsDatetime
    pd.array(['9999-12-31'], dtype='datetime64[ns]') -> RAISES OutOfBoundsDatetime
    pd.to_datetime('9999-12-31')                     -> 9999-12-31 00:00:00

Stated in pandas' favour: the correct posture is not hypothetical, a sibling library already ships it. But to_datetime is the most-typed of the three and returns the value unchanged, so "use pandas" is not the rule. This package groups to_datetime with the WRAPPING paths, because grouping it with its raising siblings by library name would be a false reassurance.

THE QUOTED BOUNDS ARE WRONG AT THE BOTTOM:

    int64 MAX ns  -> 2262-04-11T23:47:16.854775807
    int64 MIN+1   -> 1677-09-21T00:12:43.145224193      <- the true minimum
    int64 MIN     -> NaT                                <- reserved, not an instant

    1677-09-21 -> 2262-04-11T23:34:33.709551616   *** WRAPS ***
    1677-09-22 -> 1677-09-22T00:00:00.000000000   safe

1677-09-21 is the date usually quoted as the lower bound, and MIDNIGHT ON IT IS OUT OF RANGE -- the true minimum is that day at 00:12:43.145224193, because the int64 MIN bit pattern is reserved for NaT rather than being an instant. A bounds check written against the quoted DATE, which is how everyone writes it, admits a value that wraps. The first fully safe date is 1677-09-22. NANOSECOND_RANGE is exported so you can bounds-check without re-deriving this.

WHAT THIS DOES NOT CLAIM, stated because it is the honest limit. numpy's docs carry an explicit "Overflow errors" section with a worked example, so int64 overflow in general is NOT undocumented. What is undocumented is the DATETIME manifestation -- that a calendar date silently becomes a different calendar date, and that two paths in one library disagree about whether to say so. And not every pipeline is exposed: the higher-level ingestion paths are clean, with to_csv/read_csv(parse_dates=...) round-tripping sub-microsecond precision without loss and Parquet nanosecond timestamps round-tripping byte-identical. The exposure is code that calls the constructor directly or hardcodes a sentinel or epoch date -- finance "forever" terms, licence expiry, ported high-date records. A real and valuable niche, but a niche.

VERIFIED: 26 tests, measured by running the suite, every mutation observed FAILING before restore.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function evaluateDatetime64(input: DatetimeOverflowInput): DatetimeOverflowVerdict;

  export type NumpyMajor = 1 | 2 | "unknown";
  export type Severity = "critical" | "warning" | "note";