deepdiff-rs 0.11.2__tar.gz → 0.12.0__tar.gz

{deepdiff_rs-0.11.2 → deepdiff_rs-0.12.0}/Cargo.lock

@@ -629,7 +629,7 @@ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
 
 [[package]]
 name = "onix-arrow"
-version = "0.11.2"
+version = "0.12.0"
 dependencies = [
  "arrow-array",
  "arrow-buffer",
@@ -648,7 +648,7 @@ dependencies = [
 
 [[package]]
 name = "onix-cli"
-version = "0.11.2"
+version = "0.12.0"
 dependencies = [
  "onix-core",
  "serde_json",
@@ -656,7 +656,7 @@ dependencies = [
 
 [[package]]
 name = "onix-core"
-version = "0.11.2"
+version = "0.12.0"
 dependencies = [
  "num-bigint",
  "num-traits",
@@ -669,7 +669,7 @@ dependencies = [
 
 [[package]]
 name = "onix-py"
-version = "0.11.2"
+version = "0.12.0"
 dependencies = [
  "arrow-array",
  "arrow-schema",

{deepdiff_rs-0.11.2 → deepdiff_rs-0.12.0}/Cargo.toml

@@ -3,7 +3,7 @@ resolver = "3"
 members = ["crates/onix-core", "crates/onix-py", "crates/onix-arrow"]
 
 [workspace.package]
-version = "0.11.2"
+version = "0.12.0"
 edition = "2024"
 license = "MIT"
 

{deepdiff_rs-0.11.2 → deepdiff_rs-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: deepdiff-rs
-Version: 0.11.2
+Version: 0.12.0
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Rust
 Classifier: License :: OSI Approved :: MIT License
@@ -91,6 +91,24 @@ if diff:
 {'values_changed': {"root['a']": {'new_value': 2, 'old_value': 1}}}
 ```
 
+A custom object diffs by its attributes:
+
+```python
+from dataclasses import dataclass
+from deepdiff_rs import DeepDiff
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+print(DeepDiff(Point(1, 2), Point(1, 3)).to_json())
+```
+
+```
+{"values_changed":{"root.y":{"new_value":3,"old_value":2}}}
+```
+
 `diff_json`, the fast path when you already have JSON text (it parses, diffs, and serializes entirely in Rust, with no Python-object conversion):
 
 ```python
@@ -151,31 +169,31 @@ Beyond a join-based diff, `diff_tables` reports duplicate and null keys rather t
 
 Two committed, regenerable reports back the numbers below; every figure here is copied verbatim from them.
 
-The Python bindings against real `deepdiff` on **live Python objects**, the number a real caller pays (source: [`crates/onix-py/benchmarks/bench_bindings.py`](crates/onix-py/benchmarks/bench_bindings.py), macOS 26.5.1, Apple M5 Max, median of 11 isolated subprocess runs per side, run on 2026-09-04):
+The Python bindings against real `deepdiff` on **live Python objects**, the number a real caller pays (source: [`crates/onix-py/benchmarks/bench_bindings.py`](crates/onix-py/benchmarks/bench_bindings.py), macOS 26.5.1, Apple M5 Max, median of 11 isolated subprocess runs per side, run on 2026-09-23):
 
 | Shape | deepdiff | deepdiff_rs | Speedup |
 | --- | --- | --- | --- |
-| `ignore_order`, 10k shuffled ints, ~5% mutated (live objects) | 3111.56ms | 71.68ms | **43.41x** |
-|   peak RSS | 228.5 MB | 93.2 MB | **2.45x** |
-|   CPU seconds | 3.110 s | 0.072 s | **43.42x** |
-| Heterogeneous API-payload records, n=20,000 (live objects) | 3439.96ms | 153.83ms | **22.36x** |
-|   peak RSS | 118.1 MB | 147.8 MB | **0.80x** |
-|   CPU seconds | 3.439 s | 0.154 s | **22.36x** |
-| Typed records (datetime/tuple/set fields), n=10,000 (live objects) | 795.17ms | 48.48ms | **16.40x** |
-|   peak RSS | 60.2 MB | 62.2 MB | **0.97x** |
-|   CPU seconds | 0.795 s | 0.048 s | **16.40x** |
-| Same typed-records shape, `ignore_order` (live objects) | 60506.65ms | 775.38ms | **78.03x** |
-|   peak RSS | 110.3 MB | 121.6 MB | **0.91x** |
-|   CPU seconds | 60.471 s | 0.774 s | **78.10x** |
-| Same `ignore_order` shape, via `diff_json` (JSON-string path) | 3116.22ms | 73.85ms | **42.20x** |
-|   peak RSS | 228.8 MB | 93.8 MB | **2.44x** |
-|   CPU seconds | 3.114 s | 0.074 s | **42.20x** |
-| Same API-payload shape, via `diff_json` (JSON-string path) | 4559.90ms | 87.02ms | **52.40x** |
-|   peak RSS | 139.5 MB | 140.9 MB | **0.99x** |
-|   CPU seconds | 4.558 s | 0.087 s | **52.58x** |
-| Same API-payload shape, both tools reading two JSON files from disk | 4555.37ms | 85.62ms | **53.20x** |
-|   peak RSS | 139.5 MB | 141.0 MB | **0.99x** |
-|   CPU seconds | 4.553 s | 0.086 s | **53.21x** |
+| `ignore_order`, 10k shuffled ints, ~5% mutated (live objects) | 699.68ms | 66.23ms | **10.56x** |
+|   peak RSS | 401.8 MB | 203.4 MB | **1.98x** |
+|   CPU seconds | 0.699 s | 0.066 s | **10.56x** |
+| Heterogeneous API-payload records, n=20,000 (live objects) | 3486.50ms | 141.42ms | **24.65x** |
+|   peak RSS | 228.1 MB | 274.6 MB | **0.83x** |
+|   CPU seconds | 3.484 s | 0.141 s | **24.64x** |
+| Typed records (datetime/tuple/set fields), n=10,000 (live objects) | 795.03ms | 46.45ms | **17.11x** |
+|   peak RSS | 169.8 MB | 175.6 MB | **0.97x** |
+|   CPU seconds | 0.794 s | 0.046 s | **17.11x** |
+| Same typed-records shape, `ignore_order` (live objects) | 60834.60ms | 864.82ms | **70.34x** |
+|   peak RSS | 225.6 MB | 257.6 MB | **0.88x** |
+|   CPU seconds | 60.786 s | 0.863 s | **70.47x** |
+| Same `ignore_order` shape, via `diff_json` (JSON-string path) | 731.31ms | 74.54ms | **9.81x** |
+|   peak RSS | 402.3 MB | 203.9 MB | **1.97x** |
+|   CPU seconds | 0.730 s | 0.074 s | **9.81x** |
+| Same API-payload shape, via `diff_json` (JSON-string path) | 5125.41ms | 95.33ms | **53.76x** |
+|   peak RSS | 249.1 MB | 269.7 MB | **0.92x** |
+|   CPU seconds | 4.971 s | 0.095 s | **52.22x** |
+| Same API-payload shape, both tools reading two JSON files from disk | 4774.33ms | 97.33ms | **49.05x** |
+|   peak RSS | 249.0 MB | 269.7 MB | **0.92x** |
+|   CPU seconds | 4.771 s | 0.097 s | **49.12x** |
 
 The engine's own diff-only time and peak resident memory against pinned `deepdiff` 9.1.0 (source: [`perf/RESULTS.md`](perf/RESULTS.md), same machine, median over tier-appropriate runs, diff time excluding process startup and JSON parsing on both sides):
 
@@ -198,7 +216,7 @@ Both reports carry their full methodology, fairness rules, and the reproduce com
 
 **Python API.** The public surface is `DeepDiff`, `diff_json`, `diff_tables` (returning a `TableDiff`), `MaxDepthError`, `MAX_DEPTH_CEILING`, and `__version__` (a `str` matching the installed `deepdiff-rs` distribution version).
 
-- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta` (see [Known limitations](#known-limitations) for the exact restrictions and exclusions, including which types a `dict` key may be); `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict — with Python types preserved, so a value the diff found in a `tuple`, `set` or `frozenset` comes back as one and a `datetime`/`date`/`time`/`timedelta` comes back as a real one of those — and the instance is falsy when there is no difference. The `set_item_added`/`set_item_removed` categories are lists of path strings, each ending in the item itself (`root['a'][2]`, `root['x']`, `root[(1, 2)]`).
+- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta`, plus any custom object (diffed by its attributes; see [Known limitations](#known-limitations) for the exact restrictions and exclusions, including which types a `dict` key may be, and the types that raise `TypeError` instead); `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict — with Python types preserved, so a value the diff found in a `tuple`, `set` or `frozenset` comes back as one and a `datetime`/`date`/`time`/`timedelta` comes back as a real one of those (a custom object, though, comes back as a plain `dict` of its attributes, since onix cannot reconstruct the instance — see [Known limitations](#known-limitations)) — and the instance is falsy when there is no difference. The `set_item_added`/`set_item_removed` categories are lists of path strings, each ending in the item itself (`root['a'][2]`, `root['x']`, `root[(1, 2)]`).
 - `diff_json(a, b, ignore_order=False, max_depth=None) -> str`: diffs two JSON strings entirely in Rust and returns the report as a JSON string.
 - `MaxDepthError` (a `ValueError` subclass) is raised when input exceeds `max_depth`; `MAX_DEPTH_CEILING` (20,000) is the hard upper bound on `max_depth`.
 - `diff_tables(left, right, key=[...], threads=None) -> TableDiff`: diffs two Arrow tables (see [Diffing tables](#diffing-tables)). `threads` sets the row diff's worker count — `None` uses the machine's available parallelism, `1` runs single-threaded, and a value below 1 or above 1024 raises `ValueError` (the diff spawns one worker per thread); the result is byte-identical at any value. `TableDiff.schema` is the list of changed columns, `.schema_arrow` the same as an Arrow table, `.summary()` the schema and row change counts, `.to_json()` the full diff (schema, summary, and every row-level member, capped at 10,000 embedded rows); `.rows_added()`, `.rows_removed()`, `.cells_changed()`, and `.duplicate_keys()` return Arrow tables.
@@ -233,11 +251,12 @@ perf/              # cross-language benchmark harness and RESULTS.md
 ## Known limitations
 
 - Only the core diff is implemented: `exclude_paths`, `significant_digits`, custom operators, `verbose_level != 2`, and delta/patch are not (yet) supported.
-- Supported value types are `None`, `bool`, `int`, `float` (`NaN`/`Infinity`/`-Infinity` included), `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta`; a `set`/`frozenset` member may be any of these except a `list`, `dict` or `set`, matching Python's own hashability rule, transitively through whatever the member nests, and a `dict` key may be `str`, `None`, `bool`, `int`, `float`, `datetime.datetime`, `datetime.date`, or a `tuple` of those (never nested), or a `tuple`/`datetime`/`date` subclass key (`namedtuple` included), accepted and matched against its base-type value the same way — see [Known limitations](#known-limitations)'s subclass bullet. An `int` of any magnitude converts and keeps its exact value (an arbitrary-precision integer beyond `i64`/`u64` is compared, ordered, hashed and rendered by its full digits), while a custom object raises `TypeError` naming the exact path it was found at. Under `ignore_order`, comparing an integer beyond `f64::MAX` (about `2**1024`) reports the change deterministically where real DeepDiff raises `OverflowError` (its distance function calls `float()` on it unguarded), a documented crash-class divergence like the datetime one below (see [`tests/golden/README.md`](tests/golden/README.md)). Reading JSON *text* (`diff_json` and the CLI, not the Python-object path), an integer beyond `i64`/`u64` parses as the nearest `float`, so two documents whose integers differ only past that range compare **equal** and diff to `{}` — a limitation of the JSON number reader, not the value model, tracked in [#92](https://github.com/ksco92/onix/issues/92). A non-`str` key's path renders via Python's own `repr()`, except a `tuple` key, which splits into one bracket group per element (`root[1][2]` for `(1, 2)`, never `root[(1, 2)]`, with one deliberate exception for a real DeepDiff bug on the empty tuple, and another on a non-finite-float key — see [`tests/golden/README.md`](tests/golden/README.md)). A nested dict value's own `bool`/`None`/`int`/`float` key stringifies the way `json.dumps` does, but its `datetime`/`date`/`tuple` key renders that same `repr()` text where DeepDiff's own `to_json()` raises `TypeError` on one — a superset, not a difference in the findings (see [`tests/golden/README.md`](tests/golden/README.md)). `1`/`1.0`/`True` match as the same key between two dicts (Python `dict`/`set` equality). The **Datetimes**, **Sets** and **Non-finite floats** bullets below cover the deliberate divergences for those types. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs) and [`tests/golden/README.md`](tests/golden/README.md).
+- Supported value types are `None`, `bool`, `int`, `float` (`NaN`/`Infinity`/`-Infinity` included), `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta`; a `set`/`frozenset` member may be any of these except a `list`, `dict` or `set`, matching Python's own hashability rule, transitively through whatever the member nests, and a `dict` key may be `str`, `None`, `bool`, `int`, `float`, `datetime.datetime`, `datetime.date`, or a `tuple` of those (never nested), or a `tuple`/`datetime`/`date` subclass key (`namedtuple` included), accepted and matched against its base-type value the same way — see [Known limitations](#known-limitations)'s subclass bullet. An `int` of any magnitude converts and keeps its exact value (an arbitrary-precision integer beyond `i64`/`u64` is compared, ordered, hashed and rendered by its full digits), while a custom object is diffed by its attributes (see the **Custom objects** bullet below). Under `ignore_order`, comparing an integer beyond `f64::MAX` (about `2**1024`) reports the change deterministically where real DeepDiff raises `OverflowError` (its distance function calls `float()` on it unguarded), a documented crash-class divergence like the datetime one below (see [`tests/golden/README.md`](tests/golden/README.md)). Reading JSON *text* (`diff_json` and the CLI, not the Python-object path), an integer beyond `i64`/`u64` parses as the nearest `float`, so two documents whose integers differ only past that range compare **equal** and diff to `{}` — a limitation of the JSON number reader, not the value model, tracked in [#92](https://github.com/ksco92/onix/issues/92). A non-`str` key's path renders via Python's own `repr()`, except a `tuple` key, which splits into one bracket group per element (`root[1][2]` for `(1, 2)`, never `root[(1, 2)]`, with one deliberate exception for a real DeepDiff bug on the empty tuple, and another on a non-finite-float key — see [`tests/golden/README.md`](tests/golden/README.md)). A nested dict value's own `bool`/`None`/`int`/`float` key stringifies the way `json.dumps` does, but its `datetime`/`date`/`tuple` key renders that same `repr()` text where DeepDiff's own `to_json()` raises `TypeError` on one — a superset, not a difference in the findings (see [`tests/golden/README.md`](tests/golden/README.md)). `1`/`1.0`/`True` match as the same key between two dicts (Python `dict`/`set` equality). The **Datetimes**, **Sets** and **Non-finite floats** bullets below cover the deliberate divergences for those types. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs) and [`tests/golden/README.md`](tests/golden/README.md).
+- **Custom objects** diff by their attributes, matching DeepDiff's `_diff_obj` (`attribute_added`/`attribute_removed`, `root.attr` paths, `type_changes` between two different class objects), and an `Enum` member by its `name` and `value`, matching `_diff_enum`. A type DeepDiff routes to a handler onix lacks — `bytes`, `bytearray`, a generator or any other iterable, `complex`, `Decimal`, `Fraction`, a `numpy` scalar, `uuid`, `ipaddress`, a class object, a module, or a bare `object()` — raises `TypeError` at the root; below it, such a value is equal only to the same object, as DeepDiff's `t1 is t2` check makes it, and raises `TypeError` naming its path wherever the report would have to show it. Two identical Python objects at one position are never walked, a class attribute converts only when a report compares it with a shadowing value, and a class attribute is left out of a whole object in a report, as in DeepDiff (see [`tests/golden/README.md`](tests/golden/README.md#types-deepdiff-routes-to-a-handler-onix-lacks)). A `pydantic` model raises `TypeError` where DeepDiff diffs it (see [`tests/golden/README.md`](tests/golden/README.md#pydantic-models)). A custom non-`dict` `Mapping`, and a `re.Pattern` pair whose named groups differ, raise `TypeError` where DeepDiff diffs them (see [`tests/golden/README.md`](tests/golden/README.md#refused-mappings)). A `@property` that raises `AttributeError`, or an unset slot beside a `__dict__`, raises `TypeError` where DeepDiff reports the object as `unprocessed` (see [`tests/golden/README.md`](tests/golden/README.md#a-property-that-raises)). A child that points back at an object on its path reports nothing when it is on the first side; on the second side only it is compared as the object it points back at, as DeepDiff's `parents_ids` tracks only the first side's ancestry (see [`tests/golden/README.md`](tests/golden/README.md#a-recursive-object)). Three attribute-view divergences (`ignore_order` hashing, and the whole-object values in `to_json()` and `to_dict()`) are tracked in [#99](https://github.com/ksco92/onix/issues/99), see [`tests/golden/README.md`](tests/golden/README.md#custom-objects-where-onix-is-deliberately-different).
 - A subclass of a supported `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, or `datetime.timedelta` (including `namedtuple` and pandas' `Timestamp`) converts and compares as its base type but carries its own class name into a `type_changes` entry, matching DeepDiff's `type(obj).__name__` reporting, with three exceptions: a calendar-type (`datetime`/`date`/`time`/`timedelta`) subclass held as a `set`/`frozenset` member compares as its base with no `type_changes`, matching DeepDiff, since set membership has no pairwise comparison to report one against; a `tuple`/`frozenset` subclass, including a `namedtuple`, is not accepted as a `set`/`frozenset` member at all and raises `TypeError` where DeepDiff accepts and compares it by value (a documented divergence); and `namedtuple` diffs positionally rather than by field (also documented). A `type_changes` entry's `old_type`/`new_type` are type *names* in `to_dict()`, where DeepDiff returns the type objects. See [`tests/golden/README.md`](tests/golden/README.md).
 - **Datetimes** compare by instant, with a naive value read as UTC, matching DeepDiff. A changed pair is reported normalized to UTC (`to_json()` renders `...+00:00`, `to_dict()` returns UTC-aware `datetime`s); everywhere else a datetime keeps its raw value. Three deliberate departures: `to_json()` renders a `date` as `YYYY-MM-DD` where DeepDiff's own `to_json()` raises `TypeError` (a documented superset); a `zoneinfo`/`pytz` tzinfo comes back from `to_dict()` as a fixed-offset `datetime.timezone` carrying the offset it was in force at, not the original zone object; and a set holding both a naive and an aware value at one instant reports both as members, where DeepDiff's own digest cache can report only one (see [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs)). Comparing two datetimes whose UTC form would leave year 1..=9999 raises `ValueError` naming the path, where DeepDiff raises `OverflowError`; under `ignore_order` DeepDiff's hasher normalizes every datetime and so raises for such a value even when it is only added, removed, or shuffled, where onix hashes by instant and reports it normally (see [`tests/golden/README.md`](tests/golden/README.md)). `truncate_datetime` is not supported; the normalized-versus-raw split is documented there too. A `time`/`timedelta`, unlike a datetime, is never normalized for report (DeepDiff compares `time`/`date`/`timedelta` with a plain `!=`), and a naive `time` is never equal to an aware one; `to_json()` renders a `time` as `time.isoformat()`'s bytes and a `timedelta` as `str(timedelta)`'s, both supersets. Under `ignore_order`, `DeepHash` hashes a `time` by whole seconds-of-day only — dropping the microsecond and any offset, a confirmed upstream quirk — while a `timedelta` hashes exactly; see [`tests/golden/README.md`](tests/golden/README.md)'s "Known DeepDiff quirks" section.
 - **Sets** are diffed deterministically, where DeepDiff's own answers depend on the order the running process happens to iterate a set in (hash order, and `PYTHONHASHSEED`-dependent for `str` members) or on how its digest cache/computation handles a tuple, frozenset, or calendar member independently of Python's own `==`. Each consequence — entry order, which member of an equality class is reported, set-versus-sequence coercion, and a tuple/frozenset member's own (positional, not order-/repetition-insensitive) matching rule — is shown with both tools' output in [`tests/golden/README.md`](tests/golden/README.md)'s "Set iteration order" section. A report holding a `frozenset` value also serializes to JSON here, where DeepDiff's own `to_json()` raises `TypeError` — a superset, not a difference in the findings.
-- **Non-finite floats** (`NaN`, `Infinity`, `-Infinity`) compare and hash like real Python: two `NaN`s are never equal, `Infinity == Infinity`, `to_json()` renders the same bare `NaN`/`Infinity`/`-Infinity` tokens Python's `json.dumps` does, and `ignore_order` matching treats every `NaN` as one shared item, matching `DeepHash`. The one divergence, always deterministic: this crate's value model carries no Python object identity, so two independently-obtained `NaN`s always compare unequal here, where DeepDiff sometimes reports no difference (`t1 is t2`) or lets one collapse into another (a `set` member, an ordered-list match) when the two objects, or their containers, happen to be the same one. See [`tests/golden/README.md`](tests/golden/README.md)'s "Non-finite floats" section.
+- **Non-finite floats** (`NaN`, `Infinity`, `-Infinity`) compare and hash like real Python: two `NaN`s are never equal, `Infinity == Infinity`, `to_json()` renders the same bare `NaN`/`Infinity`/`-Infinity` tokens Python's `json.dumps` does, and `ignore_order` matching treats every `NaN` as one shared item, matching `DeepHash`. The one divergence, always deterministic: this crate's value model carries Python object identity for custom objects only, so two `NaN`s outside one shared custom object always compare unequal here, where DeepDiff sometimes reports no difference (`t1 is t2`) or lets one collapse into another (a `set` member, an ordered-list match) when the two objects, or their containers, happen to be the same one. See [`tests/golden/README.md`](tests/golden/README.md)'s "Non-finite floats" section.
 - A `str` (or `dict` key) containing a lone (unpaired) surrogate code point (e.g. `'\udc80'`, legal in Python but not encodable as UTF-8) is compared and reported exactly like any other `str`, matching DeepDiff's plain `==`; `to_json()` renders it with `json.dumps`'s own single-backslash `\uXXXX` escape. The one accepted divergence, always deterministic: hashing one — a `set`/`frozenset` member, or *any* value at all once `ignore_order=True` (`DeepHash` hashes every value there, not just a set's members) — crashes real DeepDiff with an unhandled `UnicodeEncodeError`, where onix hashes by code point and reports normally. See [`tests/golden/README.md`](tests/golden/README.md)'s "Known DeepDiff quirks" section.
 - A `str` inside a `tuple` or `frozenset` set item is escaped exactly as Python's `repr()` escapes it, against Unicode 16.0.0; on a Python older than 3.14 (an older `unicodedata` table), a code point assigned to Unicode after that Python's own version is escaped by DeepDiff and rendered literally by onix. See [`tests/golden/README.md`](tests/golden/README.md)'s "Pinned versions" section.
 - Adversarially deep input raises `MaxDepthError` instead of crashing: the default `max_depth` is 512 and the hard ceiling is `MAX_DEPTH_CEILING` (20,000). See [`crates/onix-py/src/guard.rs`](crates/onix-py/src/guard.rs).
@@ -247,8 +266,12 @@ perf/              # cross-language benchmark harness and RESULTS.md
 - `diff_tables` inherits some Arrow-interchange quirks: a column name with an embedded NUL byte (`\0`) arrives truncated at the NUL through the C Data Interface (the report shows the truncated name; rare in practice); a list of structs named exactly `key`/`value` with a nullable key is not distinguished from a real map, so a migration between the two is not reported as a type change (polars exports both as the same Arrow type — see `map_entries` in [`crates/onix-arrow/src/schema.rs`](crates/onix-arrow/src/schema.rs)); and a polars all-null (`Null`-typed) column fails at Arrow C import with a `ValueError` (`the datatype "Null" doesn't expect buffer at index 0`), so give such a column a concrete type first (a pyarrow all-`None` column, inferred as `null`, works and compares as all-null).
 - In `diff_tables`, DuckDB labels a `TIMESTAMP WITH TIME ZONE` column with the connection's *session* time zone when it exports to Arrow (a UTC session as `Timestamp(µs, "UTC")`, an `America/New_York` session as `Timestamp(µs, "America/New_York")`), so on a non-UTC machine such a column can be reported as a type change against a UTC column from another library. Run `SET TimeZone='UTC'` on the DuckDB connection first for a deterministic, machine-independent result.
 - `diff_tables` refuses a column whose Arrow type is nested deeper than `MAX_NESTING_DEPTH` (128) with a `MaxDepthError`, because comparing arbitrarily deep nesting would overflow the native stack; 128 is far beyond any real schema. Importing a schema nested many thousands of levels deep is also slow regardless, a cost of the Arrow C Data Interface itself.
-- `diff_tables`'s row diff costs, per call: RAM for a 32-byte hash per row per side (sorted), so peak memory is linear in row count (about 75 MB at 1M rows/side, 660 MB at 10M); the diff hashes and classifies across all cores by default, running single-threaded only when both sides stay under 50,000 rows and under 64 MB of decoded data (either bound reached first runs the parallel path), and appends the per-row hashes into shared per-partition buffers so there is no separate combined copy; the parallel path adds only the in-flight batches (worker count times batch size) plus the shared buffers' reallocation slack, measured at the linear shape as a peak of about 629 MB single-threaded and 857 MB at 18 threads at 8M rows/side (+228 MB) and about 2.9 GB and 3.6 GB at 37M rows/side (+685 MB) — roughly 10-15 bytes per row per side, under one extra copy of the 32-byte hash vectors, and within the run-to-run slack the single-threaded peak itself shows (2.9-4.2 GB at 37M); `threads=1` runs the sequential path; the size gate peeks each side only up to 50,000 rows or 64 MB of decoded data before choosing, reading the left side first; the peek holds at most 64 MB plus one producer batch per side — a streamed 49,999-row/side pair of 8 KB cells in 100-row batches peaks at about 78 MB at 18 threads and 14 MB single-threaded, rising to about 1.6 GB when the whole side arrives as one batch (see the size-gate peek table in [`perf/arrow/RESULTS.md`](perf/arrow/RESULTS.md)); wall time is `N·log N` work spread across the workers, plus a second term for the duplicate-key report, which holds the key values of every *distinct duplicated* key — an all-duplicate 200k-rows/side table (100k distinct duplicated keys) peaks at about 37 MB with 16-byte keys and 1.05 GB with 1 KB keys, 1M rows/side (500k distinct) at about 165 MB with 16-byte keys; a third term for the per-cell diff, which spills each side's changed value rows — every common value column of every changed row, changed or not — to anonymous per-key-hash-partition Arrow IPC files and compares and renders one partition at a time across the workers. Its resident cost is the spilled changed value rows (the changed-row count times the total width of the common value columns, both sides — resident where written temp pages count, e.g. macOS or a RAM-backed `tmpfs`) plus about twice the `cells_changed` output (its one out-of-place reorder) plus the per-row hash vectors; the spill term dominates for wide rows with few changed cells, the output term for many changed cells. Measured (`row_diff_rss`, 18 threads): a 1 KB `string` cell changed on every row (output-dominated) peaks at 0.92 GB at 100k rows/side, 1.31 GB at 200k, and 4.81 GB at 1M (the single-threaded path, holding both sides, is 8.30 GB); eight 512 B value columns with only one differing (spill-dominated: 150k changed cells, ~160 MB output) peaks at about 2.09 GB at 150k rows/side, versus 0.84 GB with one such column (medians over 5 runs); these are at 18 threads, the low point of the range -- the same two shapes peak higher at the ends (spill-dominated 3.03 GB at 2 threads and 2.09 GB at 64; output-dominated, 200k, 1.98 GB at 2 and 1.49 GB at 64) as fewer partitions enlarge the resident chunk and the 64-way framing adds a little; two narrow `int64` columns with every row changed peak at 0.38 GB at 1M; the full wide benchmark fixture (34 columns, nearly every cell changed) measures about 33 GB whole-process at 16.875M rows/side at 18 threads, down from about 67 GB before the streaming cell pass. The two Arrow types whose `take` retains data beyond the selected rows are decoded before the spill -- byte-view columns (`Utf8View`/`BinaryView`) cast to their large i64-offset non-view type (`LargeUtf8`/`LargeBinary`, since one batch's retained view buffers can exceed the i32 offset type's ~2 GB ceiling) and dictionaries (what polars and DuckDB emit for strings) decoded to their value type -- so the spill stays compact and independent of the partition count; without the decode it would grow with the partition count (about 97 GB at 64 threads for the wide pair vs about 34 GB with it), see [`perf/arrow/RESULTS.md`](perf/arrow/RESULTS.md). Then temp disk, because each input is re-read several times and so is spooled to an anonymous file (`tempfile`: unlinked at once, mode 0600, no predictable name — nothing is left on disk even on abnormal exit), and the cell pass additionally spills both sides' changed value rows to anonymous per-partition files (byte-view columns cast to their non-view type and dictionaries decoded to their value type first, so the spill is compact and does not grow with the thread count); the input spools and the partition spill are resident together, and for the full wide pair the whole process (input spool + spill + working set) peaks at about 33 GB at 18 threads, 45 GB at 2, and 34 GB at 64 (on Linux the spill may be a RAM-backed `tmpfs`), a full temp filesystem raising `ValueError` naming `TMPDIR`. None of these has a built-in cap: for untrusted input, bound the row count, the changed fraction, the column widths (key columns for duplicate-heavy data; for the cell pass, the total width of the common value columns — every one is spilled in full for each changed row, changed or not — plus the rendered changed cells; and any column's width for the size-gate peek, which buffers decoded cells whether or not they change), the producer's batch size, and the thread count (the cell pass's peak is lowest at the default and higher at 2 threads, where 2 partitions hold half the rows, and slightly higher at 64, the partition cap), since the peek holds up to one whole batch per side beyond the 64 MB bound. Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss` (worker count from `ROW_DIFF_THREADS`, rows per generated batch from `ROW_DIFF_BATCH`), single run, macOS on an Apple M-series laptop, 2026-09-06, same method as [Performance](#performance). See [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs).
-- `TableDiff.to_json()` is the one member with a built-in cap: it embeds `rows_added`, `rows_removed`, `cells_changed`, and `duplicate_keys` in full, one JSON object per row, so it refuses with `ValueError` — naming the row count and the cap — once those four together hold more than 10,000 rows. The cap bounds row count only, the same way the row-diff cost bullet above states its per-cell term as changed cells times cell width, not column count or cell width — so a table under the row cap but with wide or large cells can still be large; use the Arrow-returning accessors instead. See [`crates/onix-arrow/src/json_rows.rs`](crates/onix-arrow/src/json_rows.rs).
+- `diff_tables` row diff: per-row hash (32 B/row/side): 75 MB at 1M, 660 MB at 10M, linear in row count; wall time `N·log N` across workers. Parallel overhead ~10-15 B/row/side: 629/857 MB at 8M (1/18 threads), 2.9/3.6 GB at 37M; `threads=1` sequential. Duplicate-key report (every distinct duplicated key): 37 MB (16 B keys) to 1.05 GB (1 KB keys) at 200k (100k distinct), 165 MB at 1M (500k distinct, 16 B keys). Cell-pass resident (spilled rows-x-column-width, both sides + 2x `cells_changed` output + hash vectors) at 18 threads: 0.92/1.31/4.81 GB at 100k/200k/1M output-dominated (single-threaded 8.30 GB); eight 512 B columns, one differing (150k changed cells, ~160 MB output): 2.09 GB at 150k spill-dominated vs 0.84 GB one column; 0.38 GB at 1M two int64.
+- Temp disk, same call: each input is spooled to an anonymous file (`tempfile`: unlinked at once, mode 0600, no name, nothing left on abnormal exit). The cell pass spills both sides' changed rows to anonymous per-partition files: byte-view columns cast to a large-offset type (buffers can exceed i32's ~2 GB), dictionaries decoded to value type, keeping the spill compact, independent of partition count (~97 GB at 64 threads undecoded vs ~34 GB decoded, wide pair). Spool and spill resident together, whole-process peaks (34-column fixture, 16.875M rows/side): ~33 GB at 18 threads, 45 GB at 2, 34 GB at 64, down from ~67 GB pre-streaming (Linux spill may be a RAM-backed `tmpfs`). A full temp filesystem raises `ValueError` naming `TMPDIR`.
+- The size gate peeks up to 50,000 rows or 64 MB decoded per side, holding one whole producer batch per side beyond it: a 49,999-row/side, 8 KB-cell, 100-row-batch pair peaks ~78 MB at 18 threads, 14 MB single-threaded, ~1.6 GB for one whole-side batch.
+- None of the row-diff memory, temp-disk or size-gate-peek costs above has a built-in cap. Bound: row count; changed fraction; column widths (key-column width, for duplicate-heavy data; for the cell pass, the total width of all common value columns, since every one spills in full per changed row whether it changed or not, plus the rendered changed cells; any column's width for the size-gate peek, which buffers decoded cells whether or not they change); the producer's batch size; thread count, lowest at 18 threads (measured default), higher at 2 threads (two partitions each holding half the rows), slightly higher at 64: spill-dominated 3.03 GB at 2 threads, 2.09 GB at 64; output-dominated at 200k rows, 1.98 GB at 2, 1.49 GB at 64.
+- Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss` (worker count from `ROW_DIFF_THREADS`, rows per batch from `ROW_DIFF_BATCH`), single run, macOS on an Apple M-series laptop, 2026-09-06, same method as [Performance](#performance); the single-threaded hash-term figures carry run-to-run slack up to 2.9-4.2 GB at 37M rows/side, and the two spill/output cell-pass shapes are medians over 5 runs. See [`perf/arrow/RESULTS.md`](perf/arrow/RESULTS.md) for the size-gate peek table and the decode-vs-undecoded partition figures, and [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs) for the implementation.
+- `TableDiff.to_json()` is the one member with a built-in cap: it embeds `rows_added`, `rows_removed`, `cells_changed`, and `duplicate_keys` in full, one JSON object per row, so it refuses with `ValueError` — naming the row count and the cap — once those four together hold more than 10,000 rows. The cap bounds row count only, the same way the first row-diff bullet above states its per-cell term as changed cells times cell width, not column count or cell width — so a table under the row cap but with wide or large cells can still be large; use the Arrow-returning accessors instead. See [`crates/onix-arrow/src/json_rows.rs`](crates/onix-arrow/src/json_rows.rs).
 - `diff_tables` compares scalar columns by value (hashed: null, booleans, every integer, float and decimal width, strings and binary in every encoding, timestamps, dates, times, durations, intervals, and dictionaries of these; refused with `ValueError`: run-end encoded columns and any type-and-unit combination Arrow itself cannot build; nested non-key columns skipped, nested key columns refused), with the exact enumeration in the module doc of [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs). It also refuses a key column whose type differs across the two inputs after encoding normalization (the conservative choice: a primary key that changed type is refused rather than guessed, not coerced). A row whose only difference is a lossless type change — an `Int32` widened to `Int64`, a timestamp unit change at the same instant — hashes equal on both sides, so it is in neither `rows_changed` nor `cells_changed`; the column's type change is still reported in `schema`.
 - Output is byte-identical to DeepDiff except for the cases listed above and two path-rendering quirks; [`tests/golden/README.md`](tests/golden/README.md) enumerates every accepted exception, including integers past `2^53` (the limit of exact `f64` representation) inside ordered scalar lists and `ignore_order` pairing among naive datetimes, which DeepDiff ranks using the *process's local timezone* while onix reads a naive value as UTC everywhere.
 

{deepdiff_rs-0.11.2 → deepdiff_rs-0.12.0}/README.md

@@ -73,6 +73,24 @@ if diff:
 {'values_changed': {"root['a']": {'new_value': 2, 'old_value': 1}}}
 ```
 
+A custom object diffs by its attributes:
+
+```python
+from dataclasses import dataclass
+from deepdiff_rs import DeepDiff
+
+@dataclass
+class Point:
+    x: int
+    y: int
+
+print(DeepDiff(Point(1, 2), Point(1, 3)).to_json())
+```
+
+```
+{"values_changed":{"root.y":{"new_value":3,"old_value":2}}}
+```
+
 `diff_json`, the fast path when you already have JSON text (it parses, diffs, and serializes entirely in Rust, with no Python-object conversion):
 
 ```python
@@ -133,31 +151,31 @@ Beyond a join-based diff, `diff_tables` reports duplicate and null keys rather t
 
 Two committed, regenerable reports back the numbers below; every figure here is copied verbatim from them.
 
-The Python bindings against real `deepdiff` on **live Python objects**, the number a real caller pays (source: [`crates/onix-py/benchmarks/bench_bindings.py`](crates/onix-py/benchmarks/bench_bindings.py), macOS 26.5.1, Apple M5 Max, median of 11 isolated subprocess runs per side, run on 2026-09-04):
+The Python bindings against real `deepdiff` on **live Python objects**, the number a real caller pays (source: [`crates/onix-py/benchmarks/bench_bindings.py`](crates/onix-py/benchmarks/bench_bindings.py), macOS 26.5.1, Apple M5 Max, median of 11 isolated subprocess runs per side, run on 2026-09-23):
 
 | Shape | deepdiff | deepdiff_rs | Speedup |
 | --- | --- | --- | --- |
-| `ignore_order`, 10k shuffled ints, ~5% mutated (live objects) | 3111.56ms | 71.68ms | **43.41x** |
-|   peak RSS | 228.5 MB | 93.2 MB | **2.45x** |
-|   CPU seconds | 3.110 s | 0.072 s | **43.42x** |
-| Heterogeneous API-payload records, n=20,000 (live objects) | 3439.96ms | 153.83ms | **22.36x** |
-|   peak RSS | 118.1 MB | 147.8 MB | **0.80x** |
-|   CPU seconds | 3.439 s | 0.154 s | **22.36x** |
-| Typed records (datetime/tuple/set fields), n=10,000 (live objects) | 795.17ms | 48.48ms | **16.40x** |
-|   peak RSS | 60.2 MB | 62.2 MB | **0.97x** |
-|   CPU seconds | 0.795 s | 0.048 s | **16.40x** |
-| Same typed-records shape, `ignore_order` (live objects) | 60506.65ms | 775.38ms | **78.03x** |
-|   peak RSS | 110.3 MB | 121.6 MB | **0.91x** |
-|   CPU seconds | 60.471 s | 0.774 s | **78.10x** |
-| Same `ignore_order` shape, via `diff_json` (JSON-string path) | 3116.22ms | 73.85ms | **42.20x** |
-|   peak RSS | 228.8 MB | 93.8 MB | **2.44x** |
-|   CPU seconds | 3.114 s | 0.074 s | **42.20x** |
-| Same API-payload shape, via `diff_json` (JSON-string path) | 4559.90ms | 87.02ms | **52.40x** |
-|   peak RSS | 139.5 MB | 140.9 MB | **0.99x** |
-|   CPU seconds | 4.558 s | 0.087 s | **52.58x** |
-| Same API-payload shape, both tools reading two JSON files from disk | 4555.37ms | 85.62ms | **53.20x** |
-|   peak RSS | 139.5 MB | 141.0 MB | **0.99x** |
-|   CPU seconds | 4.553 s | 0.086 s | **53.21x** |
+| `ignore_order`, 10k shuffled ints, ~5% mutated (live objects) | 699.68ms | 66.23ms | **10.56x** |
+|   peak RSS | 401.8 MB | 203.4 MB | **1.98x** |
+|   CPU seconds | 0.699 s | 0.066 s | **10.56x** |
+| Heterogeneous API-payload records, n=20,000 (live objects) | 3486.50ms | 141.42ms | **24.65x** |
+|   peak RSS | 228.1 MB | 274.6 MB | **0.83x** |
+|   CPU seconds | 3.484 s | 0.141 s | **24.64x** |
+| Typed records (datetime/tuple/set fields), n=10,000 (live objects) | 795.03ms | 46.45ms | **17.11x** |
+|   peak RSS | 169.8 MB | 175.6 MB | **0.97x** |
+|   CPU seconds | 0.794 s | 0.046 s | **17.11x** |
+| Same typed-records shape, `ignore_order` (live objects) | 60834.60ms | 864.82ms | **70.34x** |
+|   peak RSS | 225.6 MB | 257.6 MB | **0.88x** |
+|   CPU seconds | 60.786 s | 0.863 s | **70.47x** |
+| Same `ignore_order` shape, via `diff_json` (JSON-string path) | 731.31ms | 74.54ms | **9.81x** |
+|   peak RSS | 402.3 MB | 203.9 MB | **1.97x** |
+|   CPU seconds | 0.730 s | 0.074 s | **9.81x** |
+| Same API-payload shape, via `diff_json` (JSON-string path) | 5125.41ms | 95.33ms | **53.76x** |
+|   peak RSS | 249.1 MB | 269.7 MB | **0.92x** |
+|   CPU seconds | 4.971 s | 0.095 s | **52.22x** |
+| Same API-payload shape, both tools reading two JSON files from disk | 4774.33ms | 97.33ms | **49.05x** |
+|   peak RSS | 249.0 MB | 269.7 MB | **0.92x** |
+|   CPU seconds | 4.771 s | 0.097 s | **49.12x** |
 
 The engine's own diff-only time and peak resident memory against pinned `deepdiff` 9.1.0 (source: [`perf/RESULTS.md`](perf/RESULTS.md), same machine, median over tier-appropriate runs, diff time excluding process startup and JSON parsing on both sides):
 
@@ -180,7 +198,7 @@ Both reports carry their full methodology, fairness rules, and the reproduce com
 
 **Python API.** The public surface is `DeepDiff`, `diff_json`, `diff_tables` (returning a `TableDiff`), `MaxDepthError`, `MAX_DEPTH_CEILING`, and `__version__` (a `str` matching the installed `deepdiff-rs` distribution version).
 
-- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta` (see [Known limitations](#known-limitations) for the exact restrictions and exclusions, including which types a `dict` key may be); `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict — with Python types preserved, so a value the diff found in a `tuple`, `set` or `frozenset` comes back as one and a `datetime`/`date`/`time`/`timedelta` comes back as a real one of those — and the instance is falsy when there is no difference. The `set_item_added`/`set_item_removed` categories are lists of path strings, each ending in the item itself (`root['a'][2]`, `root['x']`, `root[(1, 2)]`).
+- `DeepDiff(t1, t2, ignore_order=False, max_depth=None)`: diffs two live Python objects of supported value types — `None`, `bool`, `int`, `float`, `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta`, plus any custom object (diffed by its attributes; see [Known limitations](#known-limitations) for the exact restrictions and exclusions, including which types a `dict` key may be, and the types that raise `TypeError` instead); `.to_json()` returns the DeepDiff-compatible JSON string, `.to_dict()` the same report as a dict — with Python types preserved, so a value the diff found in a `tuple`, `set` or `frozenset` comes back as one and a `datetime`/`date`/`time`/`timedelta` comes back as a real one of those (a custom object, though, comes back as a plain `dict` of its attributes, since onix cannot reconstruct the instance — see [Known limitations](#known-limitations)) — and the instance is falsy when there is no difference. The `set_item_added`/`set_item_removed` categories are lists of path strings, each ending in the item itself (`root['a'][2]`, `root['x']`, `root[(1, 2)]`).
 - `diff_json(a, b, ignore_order=False, max_depth=None) -> str`: diffs two JSON strings entirely in Rust and returns the report as a JSON string.
 - `MaxDepthError` (a `ValueError` subclass) is raised when input exceeds `max_depth`; `MAX_DEPTH_CEILING` (20,000) is the hard upper bound on `max_depth`.
 - `diff_tables(left, right, key=[...], threads=None) -> TableDiff`: diffs two Arrow tables (see [Diffing tables](#diffing-tables)). `threads` sets the row diff's worker count — `None` uses the machine's available parallelism, `1` runs single-threaded, and a value below 1 or above 1024 raises `ValueError` (the diff spawns one worker per thread); the result is byte-identical at any value. `TableDiff.schema` is the list of changed columns, `.schema_arrow` the same as an Arrow table, `.summary()` the schema and row change counts, `.to_json()` the full diff (schema, summary, and every row-level member, capped at 10,000 embedded rows); `.rows_added()`, `.rows_removed()`, `.cells_changed()`, and `.duplicate_keys()` return Arrow tables.
@@ -215,11 +233,12 @@ perf/              # cross-language benchmark harness and RESULTS.md
 ## Known limitations
 
 - Only the core diff is implemented: `exclude_paths`, `significant_digits`, custom operators, `verbose_level != 2`, and delta/patch are not (yet) supported.
-- Supported value types are `None`, `bool`, `int`, `float` (`NaN`/`Infinity`/`-Infinity` included), `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta`; a `set`/`frozenset` member may be any of these except a `list`, `dict` or `set`, matching Python's own hashability rule, transitively through whatever the member nests, and a `dict` key may be `str`, `None`, `bool`, `int`, `float`, `datetime.datetime`, `datetime.date`, or a `tuple` of those (never nested), or a `tuple`/`datetime`/`date` subclass key (`namedtuple` included), accepted and matched against its base-type value the same way — see [Known limitations](#known-limitations)'s subclass bullet. An `int` of any magnitude converts and keeps its exact value (an arbitrary-precision integer beyond `i64`/`u64` is compared, ordered, hashed and rendered by its full digits), while a custom object raises `TypeError` naming the exact path it was found at. Under `ignore_order`, comparing an integer beyond `f64::MAX` (about `2**1024`) reports the change deterministically where real DeepDiff raises `OverflowError` (its distance function calls `float()` on it unguarded), a documented crash-class divergence like the datetime one below (see [`tests/golden/README.md`](tests/golden/README.md)). Reading JSON *text* (`diff_json` and the CLI, not the Python-object path), an integer beyond `i64`/`u64` parses as the nearest `float`, so two documents whose integers differ only past that range compare **equal** and diff to `{}` — a limitation of the JSON number reader, not the value model, tracked in [#92](https://github.com/ksco92/onix/issues/92). A non-`str` key's path renders via Python's own `repr()`, except a `tuple` key, which splits into one bracket group per element (`root[1][2]` for `(1, 2)`, never `root[(1, 2)]`, with one deliberate exception for a real DeepDiff bug on the empty tuple, and another on a non-finite-float key — see [`tests/golden/README.md`](tests/golden/README.md)). A nested dict value's own `bool`/`None`/`int`/`float` key stringifies the way `json.dumps` does, but its `datetime`/`date`/`tuple` key renders that same `repr()` text where DeepDiff's own `to_json()` raises `TypeError` on one — a superset, not a difference in the findings (see [`tests/golden/README.md`](tests/golden/README.md)). `1`/`1.0`/`True` match as the same key between two dicts (Python `dict`/`set` equality). The **Datetimes**, **Sets** and **Non-finite floats** bullets below cover the deliberate divergences for those types. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs) and [`tests/golden/README.md`](tests/golden/README.md).
+- Supported value types are `None`, `bool`, `int`, `float` (`NaN`/`Infinity`/`-Infinity` included), `str`, `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, and `datetime.timedelta`; a `set`/`frozenset` member may be any of these except a `list`, `dict` or `set`, matching Python's own hashability rule, transitively through whatever the member nests, and a `dict` key may be `str`, `None`, `bool`, `int`, `float`, `datetime.datetime`, `datetime.date`, or a `tuple` of those (never nested), or a `tuple`/`datetime`/`date` subclass key (`namedtuple` included), accepted and matched against its base-type value the same way — see [Known limitations](#known-limitations)'s subclass bullet. An `int` of any magnitude converts and keeps its exact value (an arbitrary-precision integer beyond `i64`/`u64` is compared, ordered, hashed and rendered by its full digits), while a custom object is diffed by its attributes (see the **Custom objects** bullet below). Under `ignore_order`, comparing an integer beyond `f64::MAX` (about `2**1024`) reports the change deterministically where real DeepDiff raises `OverflowError` (its distance function calls `float()` on it unguarded), a documented crash-class divergence like the datetime one below (see [`tests/golden/README.md`](tests/golden/README.md)). Reading JSON *text* (`diff_json` and the CLI, not the Python-object path), an integer beyond `i64`/`u64` parses as the nearest `float`, so two documents whose integers differ only past that range compare **equal** and diff to `{}` — a limitation of the JSON number reader, not the value model, tracked in [#92](https://github.com/ksco92/onix/issues/92). A non-`str` key's path renders via Python's own `repr()`, except a `tuple` key, which splits into one bracket group per element (`root[1][2]` for `(1, 2)`, never `root[(1, 2)]`, with one deliberate exception for a real DeepDiff bug on the empty tuple, and another on a non-finite-float key — see [`tests/golden/README.md`](tests/golden/README.md)). A nested dict value's own `bool`/`None`/`int`/`float` key stringifies the way `json.dumps` does, but its `datetime`/`date`/`tuple` key renders that same `repr()` text where DeepDiff's own `to_json()` raises `TypeError` on one — a superset, not a difference in the findings (see [`tests/golden/README.md`](tests/golden/README.md)). `1`/`1.0`/`True` match as the same key between two dicts (Python `dict`/`set` equality). The **Datetimes**, **Sets** and **Non-finite floats** bullets below cover the deliberate divergences for those types. See [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs) and [`tests/golden/README.md`](tests/golden/README.md).
+- **Custom objects** diff by their attributes, matching DeepDiff's `_diff_obj` (`attribute_added`/`attribute_removed`, `root.attr` paths, `type_changes` between two different class objects), and an `Enum` member by its `name` and `value`, matching `_diff_enum`. A type DeepDiff routes to a handler onix lacks — `bytes`, `bytearray`, a generator or any other iterable, `complex`, `Decimal`, `Fraction`, a `numpy` scalar, `uuid`, `ipaddress`, a class object, a module, or a bare `object()` — raises `TypeError` at the root; below it, such a value is equal only to the same object, as DeepDiff's `t1 is t2` check makes it, and raises `TypeError` naming its path wherever the report would have to show it. Two identical Python objects at one position are never walked, a class attribute converts only when a report compares it with a shadowing value, and a class attribute is left out of a whole object in a report, as in DeepDiff (see [`tests/golden/README.md`](tests/golden/README.md#types-deepdiff-routes-to-a-handler-onix-lacks)). A `pydantic` model raises `TypeError` where DeepDiff diffs it (see [`tests/golden/README.md`](tests/golden/README.md#pydantic-models)). A custom non-`dict` `Mapping`, and a `re.Pattern` pair whose named groups differ, raise `TypeError` where DeepDiff diffs them (see [`tests/golden/README.md`](tests/golden/README.md#refused-mappings)). A `@property` that raises `AttributeError`, or an unset slot beside a `__dict__`, raises `TypeError` where DeepDiff reports the object as `unprocessed` (see [`tests/golden/README.md`](tests/golden/README.md#a-property-that-raises)). A child that points back at an object on its path reports nothing when it is on the first side; on the second side only it is compared as the object it points back at, as DeepDiff's `parents_ids` tracks only the first side's ancestry (see [`tests/golden/README.md`](tests/golden/README.md#a-recursive-object)). Three attribute-view divergences (`ignore_order` hashing, and the whole-object values in `to_json()` and `to_dict()`) are tracked in [#99](https://github.com/ksco92/onix/issues/99), see [`tests/golden/README.md`](tests/golden/README.md#custom-objects-where-onix-is-deliberately-different).
 - A subclass of a supported `dict`, `list`, `tuple`, `set`, `frozenset`, `datetime.datetime`, `datetime.date`, `datetime.time`, or `datetime.timedelta` (including `namedtuple` and pandas' `Timestamp`) converts and compares as its base type but carries its own class name into a `type_changes` entry, matching DeepDiff's `type(obj).__name__` reporting, with three exceptions: a calendar-type (`datetime`/`date`/`time`/`timedelta`) subclass held as a `set`/`frozenset` member compares as its base with no `type_changes`, matching DeepDiff, since set membership has no pairwise comparison to report one against; a `tuple`/`frozenset` subclass, including a `namedtuple`, is not accepted as a `set`/`frozenset` member at all and raises `TypeError` where DeepDiff accepts and compares it by value (a documented divergence); and `namedtuple` diffs positionally rather than by field (also documented). A `type_changes` entry's `old_type`/`new_type` are type *names* in `to_dict()`, where DeepDiff returns the type objects. See [`tests/golden/README.md`](tests/golden/README.md).
 - **Datetimes** compare by instant, with a naive value read as UTC, matching DeepDiff. A changed pair is reported normalized to UTC (`to_json()` renders `...+00:00`, `to_dict()` returns UTC-aware `datetime`s); everywhere else a datetime keeps its raw value. Three deliberate departures: `to_json()` renders a `date` as `YYYY-MM-DD` where DeepDiff's own `to_json()` raises `TypeError` (a documented superset); a `zoneinfo`/`pytz` tzinfo comes back from `to_dict()` as a fixed-offset `datetime.timezone` carrying the offset it was in force at, not the original zone object; and a set holding both a naive and an aware value at one instant reports both as members, where DeepDiff's own digest cache can report only one (see [`crates/onix-py/src/convert.rs`](crates/onix-py/src/convert.rs)). Comparing two datetimes whose UTC form would leave year 1..=9999 raises `ValueError` naming the path, where DeepDiff raises `OverflowError`; under `ignore_order` DeepDiff's hasher normalizes every datetime and so raises for such a value even when it is only added, removed, or shuffled, where onix hashes by instant and reports it normally (see [`tests/golden/README.md`](tests/golden/README.md)). `truncate_datetime` is not supported; the normalized-versus-raw split is documented there too. A `time`/`timedelta`, unlike a datetime, is never normalized for report (DeepDiff compares `time`/`date`/`timedelta` with a plain `!=`), and a naive `time` is never equal to an aware one; `to_json()` renders a `time` as `time.isoformat()`'s bytes and a `timedelta` as `str(timedelta)`'s, both supersets. Under `ignore_order`, `DeepHash` hashes a `time` by whole seconds-of-day only — dropping the microsecond and any offset, a confirmed upstream quirk — while a `timedelta` hashes exactly; see [`tests/golden/README.md`](tests/golden/README.md)'s "Known DeepDiff quirks" section.
 - **Sets** are diffed deterministically, where DeepDiff's own answers depend on the order the running process happens to iterate a set in (hash order, and `PYTHONHASHSEED`-dependent for `str` members) or on how its digest cache/computation handles a tuple, frozenset, or calendar member independently of Python's own `==`. Each consequence — entry order, which member of an equality class is reported, set-versus-sequence coercion, and a tuple/frozenset member's own (positional, not order-/repetition-insensitive) matching rule — is shown with both tools' output in [`tests/golden/README.md`](tests/golden/README.md)'s "Set iteration order" section. A report holding a `frozenset` value also serializes to JSON here, where DeepDiff's own `to_json()` raises `TypeError` — a superset, not a difference in the findings.
-- **Non-finite floats** (`NaN`, `Infinity`, `-Infinity`) compare and hash like real Python: two `NaN`s are never equal, `Infinity == Infinity`, `to_json()` renders the same bare `NaN`/`Infinity`/`-Infinity` tokens Python's `json.dumps` does, and `ignore_order` matching treats every `NaN` as one shared item, matching `DeepHash`. The one divergence, always deterministic: this crate's value model carries no Python object identity, so two independently-obtained `NaN`s always compare unequal here, where DeepDiff sometimes reports no difference (`t1 is t2`) or lets one collapse into another (a `set` member, an ordered-list match) when the two objects, or their containers, happen to be the same one. See [`tests/golden/README.md`](tests/golden/README.md)'s "Non-finite floats" section.
+- **Non-finite floats** (`NaN`, `Infinity`, `-Infinity`) compare and hash like real Python: two `NaN`s are never equal, `Infinity == Infinity`, `to_json()` renders the same bare `NaN`/`Infinity`/`-Infinity` tokens Python's `json.dumps` does, and `ignore_order` matching treats every `NaN` as one shared item, matching `DeepHash`. The one divergence, always deterministic: this crate's value model carries Python object identity for custom objects only, so two `NaN`s outside one shared custom object always compare unequal here, where DeepDiff sometimes reports no difference (`t1 is t2`) or lets one collapse into another (a `set` member, an ordered-list match) when the two objects, or their containers, happen to be the same one. See [`tests/golden/README.md`](tests/golden/README.md)'s "Non-finite floats" section.
 - A `str` (or `dict` key) containing a lone (unpaired) surrogate code point (e.g. `'\udc80'`, legal in Python but not encodable as UTF-8) is compared and reported exactly like any other `str`, matching DeepDiff's plain `==`; `to_json()` renders it with `json.dumps`'s own single-backslash `\uXXXX` escape. The one accepted divergence, always deterministic: hashing one — a `set`/`frozenset` member, or *any* value at all once `ignore_order=True` (`DeepHash` hashes every value there, not just a set's members) — crashes real DeepDiff with an unhandled `UnicodeEncodeError`, where onix hashes by code point and reports normally. See [`tests/golden/README.md`](tests/golden/README.md)'s "Known DeepDiff quirks" section.
 - A `str` inside a `tuple` or `frozenset` set item is escaped exactly as Python's `repr()` escapes it, against Unicode 16.0.0; on a Python older than 3.14 (an older `unicodedata` table), a code point assigned to Unicode after that Python's own version is escaped by DeepDiff and rendered literally by onix. See [`tests/golden/README.md`](tests/golden/README.md)'s "Pinned versions" section.
 - Adversarially deep input raises `MaxDepthError` instead of crashing: the default `max_depth` is 512 and the hard ceiling is `MAX_DEPTH_CEILING` (20,000). See [`crates/onix-py/src/guard.rs`](crates/onix-py/src/guard.rs).
@@ -229,8 +248,12 @@ perf/              # cross-language benchmark harness and RESULTS.md
 - `diff_tables` inherits some Arrow-interchange quirks: a column name with an embedded NUL byte (`\0`) arrives truncated at the NUL through the C Data Interface (the report shows the truncated name; rare in practice); a list of structs named exactly `key`/`value` with a nullable key is not distinguished from a real map, so a migration between the two is not reported as a type change (polars exports both as the same Arrow type — see `map_entries` in [`crates/onix-arrow/src/schema.rs`](crates/onix-arrow/src/schema.rs)); and a polars all-null (`Null`-typed) column fails at Arrow C import with a `ValueError` (`the datatype "Null" doesn't expect buffer at index 0`), so give such a column a concrete type first (a pyarrow all-`None` column, inferred as `null`, works and compares as all-null).
 - In `diff_tables`, DuckDB labels a `TIMESTAMP WITH TIME ZONE` column with the connection's *session* time zone when it exports to Arrow (a UTC session as `Timestamp(µs, "UTC")`, an `America/New_York` session as `Timestamp(µs, "America/New_York")`), so on a non-UTC machine such a column can be reported as a type change against a UTC column from another library. Run `SET TimeZone='UTC'` on the DuckDB connection first for a deterministic, machine-independent result.
 - `diff_tables` refuses a column whose Arrow type is nested deeper than `MAX_NESTING_DEPTH` (128) with a `MaxDepthError`, because comparing arbitrarily deep nesting would overflow the native stack; 128 is far beyond any real schema. Importing a schema nested many thousands of levels deep is also slow regardless, a cost of the Arrow C Data Interface itself.
-- `diff_tables`'s row diff costs, per call: RAM for a 32-byte hash per row per side (sorted), so peak memory is linear in row count (about 75 MB at 1M rows/side, 660 MB at 10M); the diff hashes and classifies across all cores by default, running single-threaded only when both sides stay under 50,000 rows and under 64 MB of decoded data (either bound reached first runs the parallel path), and appends the per-row hashes into shared per-partition buffers so there is no separate combined copy; the parallel path adds only the in-flight batches (worker count times batch size) plus the shared buffers' reallocation slack, measured at the linear shape as a peak of about 629 MB single-threaded and 857 MB at 18 threads at 8M rows/side (+228 MB) and about 2.9 GB and 3.6 GB at 37M rows/side (+685 MB) — roughly 10-15 bytes per row per side, under one extra copy of the 32-byte hash vectors, and within the run-to-run slack the single-threaded peak itself shows (2.9-4.2 GB at 37M); `threads=1` runs the sequential path; the size gate peeks each side only up to 50,000 rows or 64 MB of decoded data before choosing, reading the left side first; the peek holds at most 64 MB plus one producer batch per side — a streamed 49,999-row/side pair of 8 KB cells in 100-row batches peaks at about 78 MB at 18 threads and 14 MB single-threaded, rising to about 1.6 GB when the whole side arrives as one batch (see the size-gate peek table in [`perf/arrow/RESULTS.md`](perf/arrow/RESULTS.md)); wall time is `N·log N` work spread across the workers, plus a second term for the duplicate-key report, which holds the key values of every *distinct duplicated* key — an all-duplicate 200k-rows/side table (100k distinct duplicated keys) peaks at about 37 MB with 16-byte keys and 1.05 GB with 1 KB keys, 1M rows/side (500k distinct) at about 165 MB with 16-byte keys; a third term for the per-cell diff, which spills each side's changed value rows — every common value column of every changed row, changed or not — to anonymous per-key-hash-partition Arrow IPC files and compares and renders one partition at a time across the workers. Its resident cost is the spilled changed value rows (the changed-row count times the total width of the common value columns, both sides — resident where written temp pages count, e.g. macOS or a RAM-backed `tmpfs`) plus about twice the `cells_changed` output (its one out-of-place reorder) plus the per-row hash vectors; the spill term dominates for wide rows with few changed cells, the output term for many changed cells. Measured (`row_diff_rss`, 18 threads): a 1 KB `string` cell changed on every row (output-dominated) peaks at 0.92 GB at 100k rows/side, 1.31 GB at 200k, and 4.81 GB at 1M (the single-threaded path, holding both sides, is 8.30 GB); eight 512 B value columns with only one differing (spill-dominated: 150k changed cells, ~160 MB output) peaks at about 2.09 GB at 150k rows/side, versus 0.84 GB with one such column (medians over 5 runs); these are at 18 threads, the low point of the range -- the same two shapes peak higher at the ends (spill-dominated 3.03 GB at 2 threads and 2.09 GB at 64; output-dominated, 200k, 1.98 GB at 2 and 1.49 GB at 64) as fewer partitions enlarge the resident chunk and the 64-way framing adds a little; two narrow `int64` columns with every row changed peak at 0.38 GB at 1M; the full wide benchmark fixture (34 columns, nearly every cell changed) measures about 33 GB whole-process at 16.875M rows/side at 18 threads, down from about 67 GB before the streaming cell pass. The two Arrow types whose `take` retains data beyond the selected rows are decoded before the spill -- byte-view columns (`Utf8View`/`BinaryView`) cast to their large i64-offset non-view type (`LargeUtf8`/`LargeBinary`, since one batch's retained view buffers can exceed the i32 offset type's ~2 GB ceiling) and dictionaries (what polars and DuckDB emit for strings) decoded to their value type -- so the spill stays compact and independent of the partition count; without the decode it would grow with the partition count (about 97 GB at 64 threads for the wide pair vs about 34 GB with it), see [`perf/arrow/RESULTS.md`](perf/arrow/RESULTS.md). Then temp disk, because each input is re-read several times and so is spooled to an anonymous file (`tempfile`: unlinked at once, mode 0600, no predictable name — nothing is left on disk even on abnormal exit), and the cell pass additionally spills both sides' changed value rows to anonymous per-partition files (byte-view columns cast to their non-view type and dictionaries decoded to their value type first, so the spill is compact and does not grow with the thread count); the input spools and the partition spill are resident together, and for the full wide pair the whole process (input spool + spill + working set) peaks at about 33 GB at 18 threads, 45 GB at 2, and 34 GB at 64 (on Linux the spill may be a RAM-backed `tmpfs`), a full temp filesystem raising `ValueError` naming `TMPDIR`. None of these has a built-in cap: for untrusted input, bound the row count, the changed fraction, the column widths (key columns for duplicate-heavy data; for the cell pass, the total width of the common value columns — every one is spilled in full for each changed row, changed or not — plus the rendered changed cells; and any column's width for the size-gate peek, which buffers decoded cells whether or not they change), the producer's batch size, and the thread count (the cell pass's peak is lowest at the default and higher at 2 threads, where 2 partitions hold half the rows, and slightly higher at 64, the partition cap), since the peek holds up to one whole batch per side beyond the 64 MB bound. Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss` (worker count from `ROW_DIFF_THREADS`, rows per generated batch from `ROW_DIFF_BATCH`), single run, macOS on an Apple M-series laptop, 2026-09-06, same method as [Performance](#performance). See [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs).
-- `TableDiff.to_json()` is the one member with a built-in cap: it embeds `rows_added`, `rows_removed`, `cells_changed`, and `duplicate_keys` in full, one JSON object per row, so it refuses with `ValueError` — naming the row count and the cap — once those four together hold more than 10,000 rows. The cap bounds row count only, the same way the row-diff cost bullet above states its per-cell term as changed cells times cell width, not column count or cell width — so a table under the row cap but with wide or large cells can still be large; use the Arrow-returning accessors instead. See [`crates/onix-arrow/src/json_rows.rs`](crates/onix-arrow/src/json_rows.rs).
+- `diff_tables` row diff: per-row hash (32 B/row/side): 75 MB at 1M, 660 MB at 10M, linear in row count; wall time `N·log N` across workers. Parallel overhead ~10-15 B/row/side: 629/857 MB at 8M (1/18 threads), 2.9/3.6 GB at 37M; `threads=1` sequential. Duplicate-key report (every distinct duplicated key): 37 MB (16 B keys) to 1.05 GB (1 KB keys) at 200k (100k distinct), 165 MB at 1M (500k distinct, 16 B keys). Cell-pass resident (spilled rows-x-column-width, both sides + 2x `cells_changed` output + hash vectors) at 18 threads: 0.92/1.31/4.81 GB at 100k/200k/1M output-dominated (single-threaded 8.30 GB); eight 512 B columns, one differing (150k changed cells, ~160 MB output): 2.09 GB at 150k spill-dominated vs 0.84 GB one column; 0.38 GB at 1M two int64.
+- Temp disk, same call: each input is spooled to an anonymous file (`tempfile`: unlinked at once, mode 0600, no name, nothing left on abnormal exit). The cell pass spills both sides' changed rows to anonymous per-partition files: byte-view columns cast to a large-offset type (buffers can exceed i32's ~2 GB), dictionaries decoded to value type, keeping the spill compact, independent of partition count (~97 GB at 64 threads undecoded vs ~34 GB decoded, wide pair). Spool and spill resident together, whole-process peaks (34-column fixture, 16.875M rows/side): ~33 GB at 18 threads, 45 GB at 2, 34 GB at 64, down from ~67 GB pre-streaming (Linux spill may be a RAM-backed `tmpfs`). A full temp filesystem raises `ValueError` naming `TMPDIR`.
+- The size gate peeks up to 50,000 rows or 64 MB decoded per side, holding one whole producer batch per side beyond it: a 49,999-row/side, 8 KB-cell, 100-row-batch pair peaks ~78 MB at 18 threads, 14 MB single-threaded, ~1.6 GB for one whole-side batch.
+- None of the row-diff memory, temp-disk or size-gate-peek costs above has a built-in cap. Bound: row count; changed fraction; column widths (key-column width, for duplicate-heavy data; for the cell pass, the total width of all common value columns, since every one spills in full per changed row whether it changed or not, plus the rendered changed cells; any column's width for the size-gate peek, which buffers decoded cells whether or not they change); the producer's batch size; thread count, lowest at 18 threads (measured default), higher at 2 threads (two partitions each holding half the rows), slightly higher at 64: spill-dominated 3.03 GB at 2 threads, 2.09 GB at 64; output-dominated at 200k rows, 1.98 GB at 2, 1.49 GB at 64.
+- Figures are the peak resident set of `cargo run -p onix-arrow --release --example row_diff_rss` (worker count from `ROW_DIFF_THREADS`, rows per batch from `ROW_DIFF_BATCH`), single run, macOS on an Apple M-series laptop, 2026-09-06, same method as [Performance](#performance); the single-threaded hash-term figures carry run-to-run slack up to 2.9-4.2 GB at 37M rows/side, and the two spill/output cell-pass shapes are medians over 5 runs. See [`perf/arrow/RESULTS.md`](perf/arrow/RESULTS.md) for the size-gate peek table and the decode-vs-undecoded partition figures, and [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs) for the implementation.
+- `TableDiff.to_json()` is the one member with a built-in cap: it embeds `rows_added`, `rows_removed`, `cells_changed`, and `duplicate_keys` in full, one JSON object per row, so it refuses with `ValueError` — naming the row count and the cap — once those four together hold more than 10,000 rows. The cap bounds row count only, the same way the first row-diff bullet above states its per-cell term as changed cells times cell width, not column count or cell width — so a table under the row cap but with wide or large cells can still be large; use the Arrow-returning accessors instead. See [`crates/onix-arrow/src/json_rows.rs`](crates/onix-arrow/src/json_rows.rs).
 - `diff_tables` compares scalar columns by value (hashed: null, booleans, every integer, float and decimal width, strings and binary in every encoding, timestamps, dates, times, durations, intervals, and dictionaries of these; refused with `ValueError`: run-end encoded columns and any type-and-unit combination Arrow itself cannot build; nested non-key columns skipped, nested key columns refused), with the exact enumeration in the module doc of [`crates/onix-arrow/src/row_diff.rs`](crates/onix-arrow/src/row_diff.rs). It also refuses a key column whose type differs across the two inputs after encoding normalization (the conservative choice: a primary key that changed type is refused rather than guessed, not coerced). A row whose only difference is a lossless type change — an `Int32` widened to `Int64`, a timestamp unit change at the same instant — hashes equal on both sides, so it is in neither `rows_changed` nor `cells_changed`; the column's type change is still reported in `schema`.
 - Output is byte-identical to DeepDiff except for the cases listed above and two path-rendering quirks; [`tests/golden/README.md`](tests/golden/README.md) enumerates every accepted exception, including integers past `2^53` (the limit of exact `f64` representation) inside ordered scalar lists and `ignore_order` pairing among naive datetimes, which DeepDiff ranks using the *process's local timezone* while onix reads a naive value as UTC everywhere.
 

{deepdiff_rs-0.11.2 → deepdiff_rs-0.12.0}/crates/onix-arrow/src/lib.rs

@@ -1,58 +1,16 @@
 //! Table diffing for onix, over Apache Arrow.
 //!
-//! [`diff_tables`] compares two tables presented as [`TableInput`]s and returns
-//! a [`TableDiff`] carrying the **schema** diff — which columns were added,
-//! removed, or changed type — the keyed **row** diff — which rows were added,
-//! removed, or changed, and which keys are duplicated — and the per-cell diff
-//! (`cells_changed`), reporting which columns changed in each changed row and
-//! how.
+//! [`diff_tables`] compares two tables presented as [`TableInput`]s and
+//! returns a [`TableDiff`] carrying the schema diff, the keyed row diff, and
+//! the per-cell diff. The two tables are matched on a required, non-empty
+//! set of key columns, carried in [`TableDiffOptions`]. The row diff reads
+//! each side more than once, so [`diff_tables`] takes a re-openable
+//! [`TableInput`] rather than a single-use `RecordBatchReader`. In-memory
+//! tables use [`MemoryInput`]; a one-shot stream spools to a temporary file
+//! and implements [`TableInput`] over it, as the Python bindings do.
 //!
-//! The two tables are matched on a required, non-empty set of key columns (the
-//! table's primary key), carried in [`TableDiffOptions`]. Every key column must
-//! exist on both sides — a missing one is a [`TableDiffError::KeyColumnMissing`].
-//! Column names must be unique on each side; a repeated name is a
-//! [`TableDiffError::DuplicateColumn`].
-//!
-//! # Inputs
-//!
-//! The row diff reads each side more than once (to hash every row, to
-//! materialize the added/removed rows, and to materialize the changed rows for
-//! the per-cell diff), so [`diff_tables`] takes a re-openable [`TableInput`]
-//! rather than a single-use `RecordBatchReader`.
-//! In-memory tables use [`MemoryInput`]; a caller whose data is a one-shot
-//! stream spools it to a temporary Arrow IPC file first and implements
-//! [`TableInput`] over that file (as the Python bindings do).
-//!
-//! # Row diff
-//!
-//! Rows are matched by a keyed 128-bit hash of the key columns; a row present
-//! only on one side is added or removed, a row on both sides whose non-key
-//! columns differ is changed, and a key appearing more than once on either side
-//! is a duplicate — reported with its per-side counts and excluded from the
-//! added/removed/changed sets. Only the non-key columns present on *both* sides
-//! take part in change detection (a column on one side only is a schema change,
-//! not a cell change), and only scalar columns are compared; a nested non-key
-//! column is skipped, while a nested key column is a
-//! [`TableDiffError::UnsupportedRowType`]. See `src/row_diff.rs` for the exact
-//! value semantics.
-//!
-//! # Type comparison
-//!
-//! Two columns of the same name are "changed type" when their Arrow
-//! [`arrow_schema::DataType`]s differ, comparing every logical parameter
-//! (timestamp unit and timezone, decimal precision and scale). Nullability is
-//! ignored (but reported). Physical encodings that carry the same logical type
-//! are treated as equal — recursively — so a column keeps the same type when a
-//! producer picks a different encoding of it: dictionary encoding, string and
-//! binary views, and the several list variants all normalize together
-//! (`diff_tables(pl.DataFrame, pa.Table)` does not flag every string column, for
-//! instance); a `FixedSizeList` keeps its width; and a list of structs named
-//! exactly `key`/`value` with a nullable key is read as a map, on every list
-//! variant, so a real map and such a list are not distinguished. See
-//! `normalized_type` in `src/schema.rs` for the exact, enumerated rule list.
-//!
-//! The reported `left_type`/`right_type` strings show the actual (un-normalized)
-//! Arrow type, so a real change reports exactly what each side holds.
+//! See `src/row_diff.rs` for the row-matching and value-comparison rules, and
+//! `src/schema.rs` for the column type-normalization rules.
 //!
 //! # Example
 //!
@@ -118,33 +76,10 @@ pub use row_diff::{MemoryInput, TableInput};
 pub use schema::{ChangeKind, SchemaChange, diff_schemas};
 pub use table_diff::{TableDiff, TableDiffSummary};
 
-/// The maximum column-type nesting depth [`diff_tables`] will compare; a
-/// column nested deeper is refused with [`TableDiffError::MaxDepthExceeded`].
-///
-/// Arrow `DataType` nesting depth is attacker-controlled and unbounded, and
-/// every recursive walk over one — the comparison, the type's `Display` (which
-/// renders the report), and its own `Clone`/`Drop` — is a native-stack sink
-/// that would abort the process with an uncatchable overflow, not a Python
-/// exception (pyarrow's own recursive `str()` survives depths where these
-/// die, so the producer is not a backstop). This bound is checked iteratively,
-/// before any recursive walk runs, and converts that hazard into a recoverable
-/// error.
-///
-/// The value, 128, is far above any real Arrow schema (nesting beyond a
-/// handful of levels is exotic; a hundred is unheard of). The per-level native
-/// stack cost of those recursive walks is measured by a committed example,
-/// `crates/onix-arrow/examples/type_stack_cost.rs` (`cargo run -p onix-arrow
-/// --example type_stack_cost`, and `--release`), which builds a type nested to
-/// a given depth and binary-searches the deepest one that survives a
-/// clone + `Display` + drop on a fixed-size stack. The worst case is nested
-/// structs in a debug build (the profile `cargo test` uses) at roughly
-/// 5.0 KiB per level; release is roughly 0.7 KiB. So 128 levels costs on the
-/// order of 640 KiB debug / 90 KiB release. The Python bindings run the whole
-/// operation — the recursive FFI import and the drop of the imported types
-/// included — on the large stack-sized worker thread `crate::guard` sizes for
-/// the JSON path (hundreds of MiB), which clears the debug worst case by
-/// roughly 500x, so this bound is the clean-error ceiling rather than the sole
-/// backstop.
+/// The maximum column-type nesting depth [`diff_tables`] will compare; deeper is refused
+/// with [`TableDiffError::MaxDepthExceeded`], turning a native-stack overflow (recursive
+/// comparison, `Display`, `Clone`/`Drop`) into an error before it can run.
+/// Per-level cost is measured by `crates/onix-arrow/examples/type_stack_cost.rs`.
 pub const MAX_NESTING_DEPTH: usize = 128;
 
 /// The maximum worker-thread count for the row diff. A larger `threads` is
@@ -153,8 +88,9 @@ pub const MAX_THREADS: usize = 1024;
 
 /// Diffs two tables presented as re-openable [`TableInput`]s.
 ///
-/// See the [crate-level docs](crate) for the type-comparison rules, the
-/// key-column contract, and the row-diff semantics.
+/// See the [crate-level docs](crate) for the key-column contract; the
+/// row-diff rules are in `row_diff.rs` and the type-comparison rules in
+/// `schema.rs`.
 ///
 /// # Errors
 ///
@@ -164,24 +100,18 @@ pub const MAX_THREADS: usize = 1024;
 /// - [`TableDiffError::DuplicateColumn`] if either input has two columns with
 ///   the same name.
 /// - [`TableDiffError::KeyColumnMissing`] if a key column is absent from
-///   either input's schema, naming the column and the side.
+///   either input's schema.
 /// - [`TableDiffError::KeyTypeMismatch`] if a key column's normalized type
-///   differs across the two inputs (a primary key that changed type is refused,
-///   not coerced).
+///   differs across the two inputs.
 /// - [`TableDiffError::UnsupportedRowType`] if a key column's type, or any
-///   non-nested column's type on either side, cannot be hashed by value — a
-///   nested key, a run-end-encoded column, or a type combination Arrow cannot
-///   build.
+///   non-nested column's type on either side, cannot be hashed by value.
 /// - [`TableDiffError::Read`] if a batch cannot be read from either input.
-/// - [`TableDiffError::Render`] if a changed cell's value cannot be rendered to
-///   its canonical string — for example an out-of-range temporal value the
-///   formatter cannot format.
+/// - [`TableDiffError::Render`] if a changed cell's value cannot be rendered
+///   to its canonical string.
 /// - [`TableDiffError::TooManyChangedRows`] if one side has more than
-///   `u32::MAX` changed rows, which the per-cell diff's row-index arrays cannot
-///   address.
-/// - [`TableDiffError::EqualRenderings`] never fires for real input: it guards
-///   the internal invariant that a `value_changed` cell always renders two
-///   different strings.
+///   `u32::MAX` changed rows.
+/// - [`TableDiffError::EqualRenderings`] never fires for real input; it
+///   guards an internal invariant.
 pub fn diff_tables(
     left: &impl TableInput,
     right: &impl TableInput,