feat(firestore): add BSON cross-type query ordering support

[ohmayr]

Context & Problem

Firestore queries require client-side and cross-type value ordering support for BSON types, including BSONMinKey, BSONMaxKey, BSONObjectId, BSONInt32, BSONDecimal128, BSONBinary, BSONRegex, and BSONTimestamp, aligning cross-type ordering with backend specifications.

Summary of Changes

• Add _BSON_KEY_TO_TYPE_ORDER mapping dictionary in order.py for $O(1)$ wire-key resolution to TypeOrder.
• Consolidate cross-type numeric comparisons in Order.compare_numbers with inline unboxing, unified NaN handling, and safe float-to-Decimal conversion to prevent float overflow and precision loss.
• Restore Order.compare_doubles to standard float comparisons.
• Implement cross-type timestamp comparison in Order.compare_timestamps supporting native Firestore timestamps and BSONTimestamp.
• Add unit tests in test_order.py verifying BSON type ordering, 1e1000 large Decimal comparisons, Decimal NaN handling, and wire-key mapping lookups.
• Update system test to verify query ordering across BSON types.

Verification

• Ran local unit test suite: pytest tests/unit/v1/test_order.py tests/unit/v1/test_bson.py (112 passed in 1.18s).
• Ran full test suite across Python 3.11 with python and upb protobuf implementations (3,708 passed).
• Ran linter suite: nox -e lint (all checks passed, 276 files formatted).
• Ran type checker: nox -s mypy-3.11 (Success: no issues found in 111 source files).

[gemini-code-assist]

Code Review

This pull request introduces support for ordering and comparing BSON types (such as BSON min/max keys, object IDs, binaries, regexes, timestamps, and numbers) in Firestore. Feedback on these changes suggests adding defensive checks for keys in BSON regex and timestamp maps to prevent potential KeyError exceptions, as well as simplifying the number comparison logic by removing redundant float attribute checks.

[daniel-sanche]

It looks like BSONDecimal can hold larger values than float. maybe we should use decimal.Decimal here?

[ohmayr]

Exactly right. Casting to float caused overflow/precision loss on large values (e.g. 1e1000).

We updated compare_numbers to extract decimal.Decimal via .to_decimal(), unified NaN handling across both float and Decimal, and convert float to Decimal(str(float)) when comparing across types to prevent Python's TypeError and avoid float overflow. We've also added unit tests for 1e1000 and Decimal NaN comparisons.

[daniel-sanche]

This wouldn't be needed if we implement __int__ and __float__ in the BSON types, so they are automatically treated as numbers (We would still need to compare decimals for BSONDecimal though)

[ohmayr]

Implementing int or float on BSONDecimal128 would still lose precision or overflow for values exceeding standard IEEE 754 float limits (1e1000).

By using a small inline extractor in compare_numbers:

def _to_number(val):
    num = decode_value(val, None)
    to_decimal = getattr(num, "to_decimal", None)
    return to_decimal() if callable(to_decimal) else getattr(num, "value", num)

we cleanly unbox native ints/floats, BSONInt32 (.value), and BSONDecimal128 (.to_decimal()) without modifying the public interfaces or type contracts of the BSON classes.

[daniel-sanche]

• math.isnan can raise OverflowError if the value is too large, so we might have to guard against that
• Can we pull _to_number and _is_nan out into helper methods, so we don't have to re-define them on each invocation?
• [optional] if we can avoid calling decode_value() in _to_number and inspect the protobuf fields directly (like the other compare_* methods), that should keep things fast

[ohmayr]

Done!

• Extracted module-level _to_number and _is_nan helpers.
• _to_number now directly inspects the protobuf fields (integer_value, double_value, and map_value for __int__ / __decimal128__) to avoid the overhead of decode_value().
• _is_nan safely handles non-floats, returns False for int and Decimal, and catches OverflowError.

[daniel-sanche]

LGTM!